release

# Releasing @insforge/ui A GitHub Release tagged `v<version>` triggers `.github/workflows/publish.yml`. The workflow authenticates with npm trusted publishing: GitHub issues an OIDC token for the run, npm checks it against the trusted publisher registered for the package, and the publish carries provenance. No npm token exists in this repository, its secrets, or any maintainer's environment, and none should be added. ## One-Time Setup on npmjs.com Done once by a package maintainer, at https://www.npmjs.com/package/@insforge/ui/access → Trusted Publisher → GitHub Actions: | Field | Value | | --- | --- | | Organization or user | `InsForge` | | Repository | `UI` | | Workflow filename | `publish.yml` | | Environment name | leave empty | The four values must match the workflow exactly. Renaming the repository or the workflow file breaks publishing until the npm side is updated. Creating a Release requires write access to the repository, and that is the whole access control for publishing. ## Cut a Release 1. On a branch, bump the version and the lockfile together: ```bash npm version <patch|minor|major> --no-git-tag-version ``` Open a PR, merge to `main`, wait for the CI run on `main` to be green. 2. Create the Release. The tag is `v` plus the exact `package.json` version: ```bash gh release create v<version> --target main --generate-notes ``` Tick pre-release only for a version with a prerelease suffix (`0.2.0-beta.1`); pre-releases publish under the `next` dist-tag instead of `latest`. Drafts do not trigger anything until published. 3. Watch the run and read the authoritative conclusion afterwards (`gh run watch` can exit non-zero for reasons other than failure): ```bash gh run list --workflow publish.yml --limit 1 gh run watch <run-id> --exit-status gh run view <run-id> ``` 4. Verify on npm: ```bash npm view @insforge/ui version dist-tags ``` The package page shows a Provenance section linking back to the workflow run. 5. Move consumers forward: bump the `@insforge/ui` range in the InsForge monorepo (`packages/dashboard/package.json`) and in insforge-cloud (`package.json`), then run `npm install` there. ## When the Workflow Fails - **"package.json is at X but the release tag is vY"** — tag and version disagree. Bump to a new version and cut a fresh release; do not reuse the tag. - **"already on npm"** — that version exists. npm never accepts a republish, so bump. - **`ENEEDAUTH`, `E401`, `E404`, or "Unable to authenticate" at `npm publish`** — the trusted publisher on npmjs.com does not match the run (owner, repository, workflow filename, environment), or npm on the runner is older than 11.5.1. The workflow prints `npm --version` right after upgrading; check it. - **lint, typecheck, or test failed** — the release ran ahead of CI. Fix on `main`, bump, release again. - A failed run leaves nothing on npm. Re-running the same release is safe until the publish step has succeeded once. ## Rules - Publish only through the workflow. A laptop publish has no provenance and skips the checks. - Never add an npm token to the repository, its secrets, or the workflow. - Versions are immutable. To retract a bad release, publish a fixed version and deprecate the bad one: ```bash npm deprecate @insforge/ui@<bad-version> "use <fixed-version>" ``` Deprecation is a manual maintainer action against npm and is the only step in this process that uses a personal login.