name	npm-release
description	Bump @oxide/api to a new omicron release tag, open the PR, and (after the user merges) hand off the npm publish commands.
user_invocable	true

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

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.
Update OMICRON_VERSION with the commit SHA (just the SHA, one line, trailing newline).
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.
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.
Regenerate the API client by running ./tools/gen.sh. This downloads the OpenAPI spec from the omicron commit and regenerates oxide-api/src/.
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__/.
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: PR

Create a branch and PR. Use jj to create a new commit, then push a branch and open a PR:
```
jj desc -m 'Bump API to <tag> (<version>)'
jj git push --change @
```
Then create the PR with gh pr create. Use a title like Bump API to rel/v19/rc0 (0.6.0) and mention the omicron tag in the body.
Wait for CI. The update-api-spec workflow runs on push to non-main branches and may create an "Autogenerate config update" commit — this is expected. The validate workflow must pass.
Hand off to the user for review and merge. Once CI is green, report that the PR is ready and stop. The user will review and merge the PR themselves, then tell you to continue. Do not merge the PR yourself.

Phase 3: Publish

Do not run these steps yourself. npm publish and npm dist-tag require interactive npm auth (a browser one-time-password flow) that won't work from an automated tool call. Instead, present the exact commands — with <version> and <N> already substituted for this release — and let the user run them. Give the commands one step at a time (or as a short numbered list), and wait for the user to confirm each is done before relying on it.

Pull main. After the PR is merged, update the local working copy so the publish builds from the merged commit:
```
jj git fetch
jj new main
```
Publish to npm. From oxide-api/:
```
npm publish
```
The prepublishOnly script runs npm run build (tsup) automatically. The user must be logged into npm with publish access to the @oxide scope.
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.

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.

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

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.

Update OMICRON_VERSION with the commit SHA (just the SHA, one line, trailing newline).

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.

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.

Regenerate the API client by running ./tools/gen.sh. This downloads the OpenAPI spec from the omicron commit and regenerates oxide-api/src/.

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__/.

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: PR

Create a branch and PR. Use jj to create a new commit, then push a branch and open a PR:

jj desc -m 'Bump API to <tag> (<version>)'
jj git push --change @

Then create the PR with gh pr create. Use a title like Bump API to rel/v19/rc0 (0.6.0) and mention the omicron tag in the body.

Wait for CI. The update-api-spec workflow runs on push to non-main branches and may create an "Autogenerate config update" commit — this is expected. The validate workflow must pass.

Hand off to the user for review and merge. Once CI is green, report that the PR is ready and stop. The user will review and merge the PR themselves, then tell you to continue. Do not merge the PR yourself.

Phase 3: Publish

Pull main. After the PR is merged, update the local working copy so the publish builds from the merged commit:

jj git fetch
jj new main

Publish to npm. From oxide-api/:

npm publish

The prepublishOnly script runs npm run build (tsup) automatically. The user must be logged into npm with publish access to the @oxide scope.

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.

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.