Release

Create a new versioned release. This includes generating a changelog, creating a git tag, and publishing a GitHub release.

Parse $ARGUMENTS for:

• •<version> — semver version (e.g. 1.2.0, 2.0.0-beta.1)
• •--draft — create the GitHub release as a draft
• •--prerelease — mark the GitHub release as a prerelease

Step 1: Validate Prerequisites

Run ALL checks upfront before doing any release work. If any check fails, stop immediately and print the remediation instructions.

1a. Git state

• •Run git status — working directory must be clean (no uncommitted changes)
• •Verify the current branch is the main/default branch (git symbolic-ref refs/remotes/origin/HEAD or check for main/master)
• •Run git pull to ensure the branch is up to date

1b. Package metadata

If package.json exists, verify these fields are present and non-empty:

• •repository — must be set (string or object with url). Required for linking the release to the correct repo.
• •files — must be a non-empty array. Ensures the published package includes the right files.

If either is missing, stop and tell the user which fields need to be added.

1c. GitHub authentication

Check in order:

1. •which gh && gh auth status — gh CLI installed and authenticated
2. •If gh is unavailable or not authed, check: [ -n "$GITHUB_TOKEN" ] || [ -n "$GH_TOKEN" ]

If neither is available, stop and tell the user:

GitHub authentication is required for creating releases. Set up one of:

1. •Run gh auth login for interactive GitHub CLI login
2. •Set export GITHUB_TOKEN=<token> with a personal access token that has repo scope

Create a token at: https://github.com/settings/tokens/new?scopes=repo

1d. Git remote

• •Run git remote get-url origin — must have a remote configured

Step 2: Determine Version

If a version was provided in $ARGUMENTS, validate it's valid semver.

If no version was provided:

1. •Read the current version from package.json (if it exists) or the latest git tag (git describe --tags --abbrev=0)
2. •Present the user with options for the next version (patch, minor, major) using AskUserQuestion
3. •Use the selected version

Ensure the version doesn't already exist as a tag (git tag -l "v<version>").

Step 3: Generate Changelog

Generate a changelog from commits since the last tag:

git log <last-tag>..HEAD --pretty=format:"%s (%h)" --no-merges

If there is no previous tag, use all commits.

Group commits by conventional commit type prefix:

• •Breaking Changes — commits with "!" suffix or "BREAKING CHANGE" in body
• •Features — feat: commits
• •Bug Fixes — fix: commits
• •Other — everything else (chore, docs, refactor, style, test, ci, perf, build)

Format as markdown:

## What's Changed

### Breaking Changes

- description (hash)

### Features

- description (hash)

### Bug Fixes

- description (hash)

### Other

- description (hash)

Omit empty sections.

Step 4: Confirm with User

Present the user with a summary before proceeding:

• •Version: v<version>
• •Changelog (the generated markdown)
• •Actions that will be performed:
  • •Update package.json version (if applicable)
  • •Create git tag v<version>
  • •Push tag to origin
  • •Create GitHub release (draft/prerelease if flagged)

Ask the user to confirm before continuing.

Step 5: Execute Release

Perform these steps in order:

5a. Update version files

If package.json exists, update the version field to the new version (use npm version <version> --no-git-tag-version).

Commit the version bump:

git add package.json
git commit -m "chore: release v<version>"

5b. Create and push git tag

git tag -a "v<version>" -m "Release v<version>"
git push origin HEAD
git push origin "v<version>"

5c. Create GitHub release

If gh CLI is available and authed:

gh release create "v<version>" --title "v<version>" --notes "<changelog>" [--draft] [--prerelease]

Otherwise, use curl:

curl -X POST "https://api.github.com/repos/{owner}/{repo}/releases" \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag_name":"v<version>","name":"v<version>","body":"<changelog>","draft":<bool>,"prerelease":<bool>}'

Parse {owner}/{repo} from git remote get-url origin.

Step 6: Summary

Print a summary of everything that was done:

• •Git tag created
• •GitHub release URL