Publishing @tagna/udiot to npmjs.org

Automatic release flow

Source metadata currently identifies 1.0.0-rc.1. While RC evaluation is active, release-mode.cjs pauses automatic stable release preparation. The normal flow below applies only after a separately reviewed stable promotion. Current readiness gates remain machine-readable in docs/releases/v1-readiness.json in the framework checkout; six gates are pending and RC publication is recorded as approved in the inspected evidence.

The workflows publish the public @tagna/udiot package to https://registry.npmjs.org/, not GitHub Packages.

1. Merge a normal feature/fix PR into main.
2. Prepare and Release opens or updates a dedicated release PR containing the next version, lockfile, release manifest, and generated changelog.
3. Review that PR, its CI results, migration notes, and the support and evaluation requirements.
4. Merging the release PR authorizes automatic npm publication. The workflow creates its Git tag/GitHub release and directly calls the npm publish workflow.
5. The publisher checks the exact tagged commit, runs tests/lint/build/audits, packs and tests a fresh consumer installation, and publishes the tested archive. A failed validation prevents npm publication.

An ordinary implementation PR does not publish a package merely by merging. Neither workflow merges PRs automatically. The dedicated release-PR merge is the maintainer-controlled approval point. Creating a GitHub release by hand no longer starts a second publisher; use the explicit retry command below if necessary.

The configured approach follows Release Please. The npm secret is only passed to the final publish step, and lifecycle scripts are disabled while publishing the already built archive.

Version selection

Use Conventional Commit titles when squash-merging PRs:

The dated publication evidence records 1.0.0-rc.1 on next and 0.19.2 on latest as verified on 2026-09-20. This is historical registry evidence; query npm view @tagna/udiot dist-tags for current tags. RC publication does not approve stable 1.0 or complete application pilots. There is no permanent release-as override. Pre-1.0 version rules continue until a deliberate reviewed 1.0 request; merging ordinary fixes will not itself select 1.0. Review the version in each generated release PR before merging.

Files managed by the automation:

• release-please-config.json: root Node package strategy and version policy.
• .release-please-manifest.json: tracked release version (the reviewed target while preparing an unpublished RC; not evidence of registry publication).
• package.json, package-lock.json, and CHANGELOG.md: next release changes.

Repository and npm setup

Run the GitHub CLI commands below from the framework checkout so they target its configured repository. Workflow guards use its immutable GitHub repository ID.

• GitHub Actions must be allowed to create pull requests. This was enabled when checked on 2026-09-12.
• Release preparation uses the repository's built-in GITHUB_TOKEN; no personal GitHub access token is required.
• Bot-created PR events do not automatically start other Actions workflows. The automation explicitly dispatches ci.yml at the release PR branch. This uses GitHub's supported workflow-dispatch exception.
• NPM_TOKEN must allow unattended publication of @tagna/udiot. The repository secret exists, but its validity, expiry, and npm permissions cannot be confirmed from secret metadata. An expired or stage-only credential cannot complete this direct-publication workflow.
• Use an appropriately scoped, current credential according to npm's access-token documentation. The old documentation about non-expiring legacy Automation tokens no longer applies. Do not paste tokens into PRs, source files, or logs.
• The build runtime is Node 22; consumers require Node >=22.17.0 and npm >=9.
• Require review and passing CI for main in repository protection/rulesets. Classic branch protection was not configured when checked; this task does not change repository-wide protection or reviewer policy.

The 0.18.0 through 0.19.2 publications succeeded with the maintainer's updated npm credential. This is historical evidence, not a guarantee against future expiry. Enabling workflows does not satisfy application deployment or 1.0 approval gates.

The publisher also runs the packed consumer in Chromium, Firefox and WebKit before exposing the npm token. See the browser validation policy for local commands, evidence and the limits of these smoke checks.

All executable workflows route to the private tagna-local self-hosted group; see runner setup and access requirements. There is no hosted-runner fallback. The new workflow routing takes effect on main only when the configuration PR is merged; retries of old runs retain their original workflow revision.

Publication safeguards

• Only this repository and the main workflow ref can publish.
• Stable publication accepts only vMAJOR.MINOR.PATCH tags. The separate RC dispatch accepts only vMAJOR.MINOR.PATCH-rc.NUMBER for npm next. Both require the exact tagged commit to belong to main and matching version metadata.
• Require matching tag, package, root lockfile, release manifest, and changelog versions.
• Query the public npm registry before publishing. An existing version is skipped only when the requested channel selects it; mismatches fail without moving tags. Lookup/network errors fail closed. New versions must be newer than npm latest.
• Serialize publication jobs and do not cancel an active publication.
• Require release-tool tests, lint, the full framework tests, TypeScript build, root/SmartForm audits, publish build, and a clean fresh packed consumer install.
• Require the reviewed public declaration snapshot and compile a TypeScript consumer.
• Stable 1.x additionally requires all entries in v1-readiness.json to have approved evidence.
• A future stable major requires its own matching readiness record. Pre-1.0 and RC tags do not require an initial stable-release approval record.
• Supply npm credentials only after validation and publish the tested archive with --ignore-scripts.
• Invoke publication directly from the release workflow. Do not depend on a bot-created GitHub release event to start another workflow.
• Verify the requested channel and SHA-512 of the tested archive after publishing. Retry propagation delays and transient registry failures up to 12 attempts, five seconds apart. Identity/integrity/authentication errors remain hard failures.

The local framework audit does not prove all supported peer versions or existing consumer lockfiles are secure. Complete the separate peer-floor and tagna-web validation gates before approving the first release PR.

Retrying a failed npm publication

Release Please may already have created the GitHub release/tag when validation or npm authentication fails. A GitHub release entry alone is not proof that npm publication succeeded.

After resolving the failure, retry the same existing release tag from main:

gh workflow run publish.yml --ref main -f tag=v0.18.0

This does not bump a version on the runner, create a new tag, or overwrite an existing npm version. If code changes are needed, prepare a new release; do not move an existing tag to different code. If the first run already published successfully, a retry skips the duplicate publication.

Do not rerun a completed release-preparation job expecting it to recreate its release_created output. Retry publish.yml with the explicit tag instead.

Release candidates (explicit approval only)

publish-rc.yml calls the same guarded publisher with channel fixed to next. The stable automation remains on latest; it will reject an RC tag. The RC path rejects stable tags, arbitrary channels, malformed versions, and backwards next updates. npm dist-tags select the installation channel; see npm's dist-tag documentation.

When main's package, lockfile, manifest and changelog contain matching RC metadata, release-mode.cjs pauses Release Please before it can prepare or tag an automatic stable release. Malformed/mismatched metadata fails the workflow. This hold does not affect CI or the explicitly approved publish-rc.yml path. Merging the RC preparation PR alone does not publish, tag or approve the candidate.

Before dispatch, review and merge an RC preparation change aligning package.json, both root lockfile versions, release manifest, and a changelog heading at e.g. 1.0.0-rc.1. Create the matching immutable tag on that reviewed main commit only with maintainer approval. Do not merge an older automatically proposed stable release PR while the RC is under evaluation; the hold does not close existing PRs or revoke older workflow runs. No script fabricates RC metadata or moves a tag.

After approval, dispatch or retry the existing RC tag:

gh workflow run publish-rc.yml --ref main -f tag=v1.0.0-rc.1

An existing npm version on the requested channel is skipped without republishing or moving any dist-tag. A different or missing channel is an explicit error. The next RC must be numerically newer; rc.10 follows rc.9. Validate the exact RC tarball in pilots and verify latest stayed unchanged. The 2026-09-20 registry evidence records 1.0.0-rc.1 on next and 0.19.2 on latest; query current tags before publishing. Publication alone does not count as completed pilot evidence.

After readiness approval, a separately reviewed promotion change must restore matching stable metadata to lift the RC hold. Review the one-time final release request and Release Please release PR/labels before allowing tagging/publication; do not merely change the number or assume the RC preparation is a release PR. Never leave a permanent release-as override. Normal patches after the approved 1.0.0 are permitted by the preflight and produce 1.0.1.

Verification

Before merging a release PR:

npm run test:release
npm run lint
npm test -- --runInBand
npm run build
npm run build:publish
npm run test:consumer
npm run test:consumer:all
npm audit --audit-level=low
npm audit --audit-level=low --prefix apps/SmartForm

After publication, check the workflow and registry:

gh run list --limit 10
npm view @tagna/udiot version dist-tags
npm view @tagna/udiot@0.18.0 version dist.integrity engines

Then promote tested downstream applications through their own release process. This automation does not update or deploy tagna-web or the separate website.

The publish build now shares internal ESM chunks so classes, metadata Symbols, and singleton state retain their identity across exports. Keep the generated chunks in the archive. OpenAPI tools resolve through a package-local import map. The packed checks exercise the root container with the database adapter, not just successful imports. The SDK's version-pinned, type-only Supabase patch is documented in its shipped notice; consumers do not run patch scripts. Third-party bundled sources retain upstream licenses, while UDIOT implementation sources and source maps remain excluded.