@@ -1,32 +1,38 @@
11 ---
22 name: release
3-description: Create a new tagged npm release (patch/minor/major)
3+description: "Create a new tagged npm release (patch/minor/major). Use when the user asks to release, publish, bump version, or cut a new version."
4+compatibility: "Requires git, bun, and npm with publish credentials"
45 ---
56
67 Create a new npm release for this repo. The bump type is: $1 (default to "patch" if not provided).
78
8-Steps to follow exactly:
9+## Steps
910
10-1. Normalize bump type to one of `patch|minor|major`; if empty, use `patch`.
11-2. Verify git state before doing anything:
12- - current branch must be `main`
13- - working tree must be clean
14- - run `git fetch origin --tags` and ensure `HEAD` equals `origin/main`
15- If any check fails, stop and report.
16-3. Run the full repo check suit — stop and report failures.
17-4. Read `package.json` and capture both `name` and current `version`.
18-5. Compute the next semver version by bumping the selected part.
19-6. Guardrails before mutating files:
20- - ensure git tag `v<new-version>` does not exist locally or on origin
21- - ensure npm version does not already exist: `npm view <package-name>@<new-version> version`
22- If either exists, stop and report.
23-7. Update the `version` field in `package.json` to `<new-version>`.
24-8. Run `bun run build`.
25-9. Commit all staged and unstaged changes with message: `chore: release v<new-version>`.
26-10. Create annotated tag: `git tag -a v<new-version> -m "<new-version>"`.
27-11. Push explicitly to main and the exact tag:
11+1. **Normalize** the bump type to one of `patch | minor | major`. Default to `patch` if empty.
12+2. **Verify git state** before mutating anything:
13+ - Current branch must be `main`.
14+ - Working tree must be clean (`git status --porcelain` is empty).
15+ - Run `git fetch origin --tags` and ensure `HEAD` equals `origin/main`.
16+ - If any check fails, stop and report.
17+3. **Run checks** — execute the full repo check suite. Stop and report on failures.
18+4. **Read `package.json`** and capture `name` and current `version`.
19+5. **Compute next version** by bumping the selected semver part.
20+6. **Guardrails** before mutating files:
21+ - Ensure git tag `v<new-version>` does not exist locally or on origin.
22+ - Ensure npm version does not already exist: `npm view <name>@<new-version> version`.
23+ - If either exists, stop and report.
24+7. **Update `package.json`** — set the `version` field to `<new-version>`.
25+8. **Build** — run `bun run build`.
26+9. **Commit** all staged and unstaged changes: `chore: release v<new-version>`.
27+10. **Tag** — create annotated tag: `git tag -a v<new-version> -m "<small changelog>"`.
28+11. **Push** explicitly to main and the exact tag:
2829 - `git push origin main`
2930 - `git push origin v<new-version>`
30-12. Post-push verification: run `npm view <package-name>@<new-version> version`.
31- - If it already exists, report that publish already happened and do **not** ask user to publish again.
32- - If it does not exist, ask user to run `npm publish` (passkey auth step).
31+12. **Post-push verification** — run `npm view <name>@<new-version> version`.
32+ - If it already exists, report that publish already happened — do **not** ask to publish again.
33+ - If it does not exist, run `npm publish`.
34+
35+## Edge cases
36+
37+- If the build fails, revert the version bump in `package.json` and stop.
38+- If the push fails, do not retry — report the failure and let the user resolve.