release

Release

.github/workflows/release.yml owns version allocation and artifact mutation. The workflow validates every push to main or master first, then reserves the v<version> tag for the version root package.json names, publishes GHCR and the CLI (or confirms the CLI version already exists), and finally publishes the GitHub Release. Do not pre-create a release tag, draft, or release/<version> branch.

Root package.json holds the version. No other file records it. A release is a deliberate bump: an unchanged version gives a clean, green no-op run.

1. Resolve the canonical destination

if git remote get-url upstream >/dev/null 2>&1; then
  REMOTE=upstream
else
  REMOTE=origin
fi
REPO=$(gh repo view "$(git remote get-url "$REMOTE")" --json nameWithOwner -q .nameWithOwner)

if git ls-remote --exit-code --heads "$REMOTE" main >/dev/null 2>&1; then
  TARGET=main
elif git ls-remote --exit-code --heads "$REMOTE" master >/dev/null 2>&1; then
  TARGET=master
else
  echo "No main or master release branch exists on $REMOTE" >&2
  exit 1
fi
SOURCE=$(git branch --show-current)
printf 'Repo: %s · source: %s · release branch: %s\n' "$REPO" "$SOURCE" "$TARGET"

2. Pre-flight

Require all of the following before a release push:

• The working tree is clean.
• The source commit is pushed to the canonical remote.
• CI for the source commit is green.
• Root package.json names the version to publish, and no v<version> tag exists yet. An unbumped push is a green no-op that publishes nothing.
• CHANGELOG.md has a ## [<version>] section matching that version (the workflow falls back to [Unreleased] when the section is absent).
• The remote release branch is an ancestor of the source commit, so promotion is a fast-forward.

test -z "$(git status --porcelain)" || { echo "Working tree is dirty" >&2; exit 1; }
git fetch "$REMOTE" "$SOURCE" "$TARGET" --tags
VERSION=$(node -p "require('./package.json').version")
git rev-parse -q --verify "refs/tags/v$VERSION" >/dev/null && {
  echo "v$VERSION is already tagged; bump package.json to cut a new release" >&2
  exit 1
}
grep -q "^## \[$VERSION\]" CHANGELOG.md || {
  echo "CHANGELOG.md has no section for $VERSION" >&2
  exit 1
}
SHA=$(git rev-parse "$REMOTE/$SOURCE")
test "$(git rev-parse HEAD)" = "$SHA" || {
  echo "Local $SOURCE is not identical to $REMOTE/$SOURCE" >&2
  exit 1
}
git merge-base --is-ancestor "$REMOTE/$TARGET" "$SHA" || {
  echo "$TARGET has diverged from $SOURCE; reconcile before release" >&2
  exit 1
}