name	release
description	Release a new version of antigravity-booster (bumps version, tags git, pushes, triggers npm publish)
license	MIT
user-invocable	true
metadata	{"version":"1.0.0","internal":true}
last-verified	"2026-07-21T00:00:00.000Z"

Release

Use this command to release a new version of antigravity-booster.

Arguments

First positional argument: Version bump type — "patch", "minor", or "major". Defaults to "minor" if not specified.

Steps

Determine the new version. Read the current version from ./package.json. Apply the requested semver bump (default "minor") to compute the new version number.
Verify preconditions — all must pass before any changes are made:

a. Working tree is clean:
```
git status --porcelain
```
Must be empty. If not, abort and tell the user to commit or stash changes first.

b. On the main branch:
```
git branch --show-current
```
Must return main. If not, abort.

c. Up to date with remote:
```
git fetch origin
git status -uno
```
Output must not contain "Your branch is behind". If it does, abort and tell the user to pull first.

d. repository.url is set in ./package.json:
```
node -e "const p=JSON.parse(require('fs').readFileSync('package.json','utf8')); process.exit(p.repository?.url ? 0 : 1)"
```
Must exit 0. If missing, abort and print:

repository.url is required for --provenance publishing. Add it to ./package.json: "repository": { "type": "git", "url": "https://github.com/ORG/REPO.git" }

e. No file: dependencies in ./package.json:
```
grep -c '"file:' package.json
```
Must return 0. If any file: deps are found, abort and print:

file: dependencies cannot be published to npm. Replace them with registry versions before releasing. Found: (list each file: dep and its key)

f. Tests pass:
```
npm test
```
Must exit 0. If tests fail, abort — do not proceed.
Bump version:
```
npm version <patch|minor|major> --no-git-tag-version
```
This atomically updates the "version" field in both ./package.json and ./package-lock.json.
Commit the bump on a release branch. main is protected by the main-protection ruleset (1 approving review + code-owner review), and its only bypass is pull_request mode — so a direct git push origin main is rejected for everyone, including admins. The bump has to land via a PR.
```
git checkout -b release/vX.Y.Z
git add package.json package-lock.json CHANGELOG.md
git commit -m "chore: bump version to X.Y.Z"
git push -u origin release/vX.Y.Z
gh pr create --title "chore: release X.Y.Z" --body "Version bump + changelog for X.Y.Z."
```
Also move the ## [Unreleased] entries in ./CHANGELOG.md under a new ## [X.Y.Z] — YYYY-MM-DD heading in this commit.
Get the PR reviewed and merged. Wait for CI and an approval, then merge. Do not tag before it lands: .github/workflows/publish.yml refuses to publish a tag that is not an ancestor of main, so a tag on an unmerged commit fails the release.
Tag the merged commit on main and push the tag:
```
git checkout main && git pull origin main
# Confirm you are tagging the bump you just merged.
node -p "require('./package.json').version"   # must equal X.Y.Z
git tag vX.Y.Z
git push origin vX.Y.Z
```
Tag creation is restricted by the release tags ruleset (refs/tags/v*), which grants an always-bypass to the maintainer role — so this push succeeds for a maintainer and is refused for everyone else. That tag push is what triggers the publish.
Confirm completion. Print a summary stating the released version (was A.B.C, now X.Y.Z) and that tag vX.Y.Z was pushed to origin, then remind the user:

GitHub Actions will publish to npm on tag push, but the job waits for approval first: it runs under the npm-publish protected environment, which requires a reviewer. Approve it under the repo's Actions tab.

The publish job verifies the tag is an ancestor of main and that it matches the version in ./package.json, then publishes with --provenance --access public via npm OIDC trusted publishing (no long-lived npm token).

If the publish job fails with ENEEDAUTH, trusted publishing is not configured for antigravity-booster on npmjs.com. See docs/github-rulesets/README.md § "npm trusted publishing (OIDC)".

Release

Use this command to release a new version of antigravity-booster.

Arguments

First positional argument: Version bump type — "patch", "minor", or "major". Defaults to "minor" if not specified.

Steps

Determine the new version. Read the current version from ./package.json. Apply the requested semver bump (default "minor") to compute the new version number.

Verify preconditions — all must pass before any changes are made:

a. Working tree is clean:

git status --porcelain

Must be empty. If not, abort and tell the user to commit or stash changes first.

b. On the main branch:

git branch --show-current

Must return main. If not, abort.

c. Up to date with remote:

git fetch origin
git status -uno

Output must not contain "Your branch is behind". If it does, abort and tell the user to pull first.

d. repository.url is set in ./package.json:

node -e "const p=JSON.parse(require('fs').readFileSync('package.json','utf8')); process.exit(p.repository?.url ? 0 : 1)"

Must exit 0. If missing, abort and print:

repository.url is required for --provenance publishing. Add it to ./package.json: "repository": { "type": "git", "url": "https://github.com/ORG/REPO.git" }

e. No file: dependencies in ./package.json:

grep -c '"file:' package.json

Must return 0. If any file: deps are found, abort and print:

file: dependencies cannot be published to npm. Replace them with registry versions before releasing. Found: (list each file: dep and its key)

f. Tests pass:

npm test

Must exit 0. If tests fail, abort — do not proceed.

Bump version:

npm version <patch|minor|major> --no-git-tag-version

This atomically updates the "version" field in both ./package.json and ./package-lock.json.

Commit the bump on a release branch. main is protected by the main-protection ruleset (1 approving review + code-owner review), and its only bypass is pull_request mode — so a direct git push origin main is rejected for everyone, including admins. The bump has to land via a PR.

git checkout -b release/vX.Y.Z
git add package.json package-lock.json CHANGELOG.md
git commit -m "chore: bump version to X.Y.Z"
git push -u origin release/vX.Y.Z
gh pr create --title "chore: release X.Y.Z" --body "Version bump + changelog for X.Y.Z."

Also move the ## [Unreleased] entries in ./CHANGELOG.md under a new ## [X.Y.Z] — YYYY-MM-DD heading in this commit.

Get the PR reviewed and merged. Wait for CI and an approval, then merge. Do not tag before it lands: .github/workflows/publish.yml refuses to publish a tag that is not an ancestor of main, so a tag on an unmerged commit fails the release.

Tag the merged commit on main and push the tag:

git checkout main && git pull origin main
# Confirm you are tagging the bump you just merged.
node -p "require('./package.json').version"   # must equal X.Y.Z
git tag vX.Y.Z
git push origin vX.Y.Z

Tag creation is restricted by the release tags ruleset (refs/tags/v*), which grants an always-bypass to the maintainer role — so this push succeeds for a maintainer and is refused for everyone else. That tag push is what triggers the publish.

Confirm completion. Print a summary stating the released version (was A.B.C, now X.Y.Z) and that tag vX.Y.Z was pushed to origin, then remind the user:

GitHub Actions will publish to npm on tag push, but the job waits for approval first: it runs under the npm-publish protected environment, which requires a reviewer. Approve it under the repo's Actions tab.

The publish job verifies the tag is an ancestor of main and that it matches the version in ./package.json, then publishes with --provenance --access public via npm OIDC trusted publishing (no long-lived npm token).

If the publish job fails with ENEEDAUTH, trusted publishing is not configured for antigravity-booster on npmjs.com. See docs/github-rulesets/README.md § "npm trusted publishing (OIDC)".