npm-release

# npm-release: Bump @oxide/api to a new omicron release This skill handles the full release cycle for the `@oxide/api` npm package when a new omicron release tag appears (e.g., `rel/v19/rc0`). ## Inputs Ask the user for: - **Omicron release tag** (e.g., `rel/v19/rc0`). If not provided, look up the latest `rel/` tag on oxidecomputer/omicron via `gh-api-read repos/oxidecomputer/omicron/tags --jq '.[].name'` and pick the newest one. Confirm with the user before proceeding. - **New `@oxide/api` version**: Always a minor bump. Read the current version from `oxide-api/package.json` and bump minor (e.g., `0.5.1` → `0.6.0`). ## Steps ### Phase 1: Prepare the bump 1. **Resolve the omicron tag to a commit SHA.** Omicron release tags are annotated tags, so you need to dereference to the underlying commit: ``` gh-api-read repos/oxidecomputer/omicron/git/ref/tags/<tag> --jq '.object.sha' ``` That gives you the tag object SHA. Then: ``` gh-api-read repos/oxidecomputer/omicron/git/tags/<tag-object-sha> --jq '.object.sha' ``` That gives you the commit SHA. Write it to `OMICRON_VERSION`. 2. **Update `OMICRON_VERSION`** with the commit SHA (just the SHA, one line, trailing newline). 3. **Bump version in `oxide-api/package.json`** to the agreed version. Then run `cd oxide-api && npm install --package-lock-only` so `package-lock.json` is updated to match. 4. **Update the versions table in `oxide-api/README.md`.** Add a row for the new release at the top of the table with the system version, `@oxide/api` version, and npm dist-tag. 5. **Regenerate the API client** by running `./tools/gen.sh`. This downloads the OpenAPI spec from the omicron commit and regenerates `oxide-api/src/`. 6. **Update test snapshots.** In `oxide-openapi-gen-ts/`, run: ``` npm ci && npm test run -- --update ``` This regenerates the snapshots in `oxide-openapi-gen-ts/src/__snapshots__/`. 7. **Run CI checks locally** to make sure everything passes: - `cd oxide-api && npm ci && npm run tsc` - `cd oxide-openapi-gen-ts && npm run tsc && npm run lint && npm run fmt:check` ### Phase 2: Hand off (do not push) 8. **Describe the commit and stop.** Set the commit description with `jj desc -m 'Bump API to <tag> (<version>)'` and leave the change in the working copy for the user to review. Do **not** push a branch, and do **not** open a PR. No `jj git push`, no `gh pr create`. The user pushes and opens the PR themselves. Report what changed (the files touched and any notable spec changes) and stop there. Note for when the PR does exist: the `update-api-spec` workflow runs on push to non-main branches and may create an "Autogenerate config update" commit — that is expected. The `validate` workflow must pass. The user reviews and merges; never merge the PR yourself. ### Phase 3: Publish (automatic) and dist-tag (manual) 9. **Approve and wait for the automatic publish.** Merging the PR triggers the `Release` workflow on main, which runs validation and then waits for a required reviewer to approve the `release` environment deployment. Tell the user to approve it (or ask another required reviewer to approve it) in the Actions run UI. The workflow then publishes any package version not already on the registry via npm trusted publishing — no manual `npm publish`. Watch it with `gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')` and confirm with `npm view @oxide/api version`, which should show the new version. 10. **Add npm dist-tag.** Tag the published version with the release name so consumers can pin to it: ``` npm dist-tag add @oxide/api@<version> rel<N> ``` where `<N>` is the system release number (e.g., `19` for `rel/v19/rc0`). Note: bare version numbers like `v10` are not allowed by npm because they parse as semver — use the `rel` prefix. Do **not** run this yourself. It requires interactive npm auth (a browser one-time-password flow) that won't work from an automated tool call, and CI can't do it either — the trusted-publishing OIDC credential only works for `npm publish`, not `dist-tag`. Present the exact command with `<version>` and `<N>` already substituted and let the user run it. ### Notes - The `@oxide/openapi-gen-ts` package version is bumped separately and less frequently — do not bump it as part of this flow unless the user asks. - The version scheme for `@oxide/api` roughly follows omicron releases with minor bumps for new releases and patch bumps for fixes. See issue #245 for ongoing discussion. - If the gen script fails to download the spec, verify the commit SHA is correct and that `openapi/nexus/nexus-latest.json` exists at that commit.