Merge #8: Add release workflow

Author: codethief

.github/workflows/prepare-release.yml

@@ -0,0 +1,57 @@
+name: Prepare release
+
+# Manually-triggered release prep. Bumps the version, rolls the CHANGELOG, and opens a
+# PR — nothing is pushed to master directly. Merging the PR triggers release.yml.
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Target version, e.g. 0.2.0 (must be > current package.json version)"
+        required: true
+
+permissions: {}
+
+concurrency:
+  group: prepare-release
+  cancel-in-progress: false
+
+# Injection-safety: the free-text `version` input is bound ONCE here; every step below
+# references the quoted shell variable "$VERSION" and never expands ${{ inputs.version }}
+# inside a `run:` script (which Actions would substitute before the shell parses it).
+env:
+  VERSION: ${{ inputs.version }}
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # push the release branch
+      pull-requests: write # open the PR
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: jdx/mise-action@dba19683ed58901619b14f395a24841710cb4925 # v4.1.0
+        with:
+          cache: true
+      - run: npm ci
+      - run: ./scripts/check-version-increases.ts "$VERSION"
+      - run: ./scripts/roll-changelog.ts "$VERSION"
+      - run: npm version "$VERSION" --no-git-tag-version
+      - name: Commit on a branch and open PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          BRANCH="release/v${VERSION}"
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git switch -c "$BRANCH"
+          git commit package.json package-lock.json CHANGELOG.md -m "Release v${VERSION}"
+          # Credential helper reads the token from env at git runtime — token never lands
+          # in argv (URL) or on-disk git config. Leading empty helper clears inherited ones.
+          git -c credential.helper= \
+              -c credential.helper='!f() { echo username=x-access-token; echo "password=${GH_TOKEN}"; }; f' \
+              push "https://github.com/${{ github.repository }}.git" "$BRANCH"
+          gh pr create --base master --head "$BRANCH" \
+            --title "Release v${VERSION}" \
+            --body "Automated release prep for v${VERSION}. Review the version bump and rolled CHANGELOG, then merge to trigger the gated release."

.github/workflows/release.yml

@@ -0,0 +1,121 @@
+name: Release
+
+# Triggered after CI succeeds on a push to master (i.e. after a release-prep PR merges).
+# A cheap, ungated `gate` job decides whether this push introduced a new version; only
+# then does the `release` job — behind a manual approval environment — tag, build, create
+# the GitHub Release, and publish to npm via OIDC.
+#
+# zizmor flags `workflow_run` as a dangerous trigger because it runs privileged and is
+# commonly misused to execute untrusted PR code. We use it safely: the gate requires a
+# *push* to *master* that *succeeded*, the checkout pins the triggering commit SHA (a
+# trusted master commit, never PR head), and the privileged publish sits behind a manual
+# approval environment. Hence the suppression below.
+on: # zizmor: ignore[dangerous-triggers]
+  workflow_run:
+    workflows: ["CI"] # matches name: in ci.yml
+    types: [completed]
+    branches: [master] # head branch of the CI run; excludes PR runs at the trigger
+
+permissions: {}
+
+# NOTE: no workflow-level `concurrency:` on purpose. A top-level group would put
+# every release RUN — including the ones that no-op at the gate — into one
+# serialized slot, and GitHub cancels the older *pending* run whenever a newer
+# one queues. Under a quick succession of merges A -> B -C where only A bumps
+# the version, B/C's no-op runs could evict A while it waits, so nothing
+# releases. Concurrency lives on the `release` job instead (below), where only
+# genuine releases land.
+
+jobs:
+  gate:
+    # Belt-and-suspenders: the trigger's `branches: [master]` already excludes PR runs;
+    # this also requires the CI run to be a *push* that *succeeded*.
+    if: >-
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == 'master' &&
+      github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      # workflow_run defaults to default-branch HEAD — must pin the triggering SHA.
+      # fetch-depth: 2 so the first parent is present for the version-introduced diff.
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 2
+          persist-credentials: false
+      - uses: jdx/mise-action@dba19683ed58901619b14f395a24841710cb4925 # v4.1.0
+        with:
+          cache: true
+      - run: npm ci
+      - id: decide
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          ./scripts/validate-version.ts "$VERSION"   # format check (defence-in-depth)
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+          # Release ONLY when THIS commit introduced the version (vs its first
+          # parent), not merely whenever master happens to carry an untagged
+          # version. This ties the release to the prepare commit and makes any
+          # later same-version commit a no-op regardless of CI/approval
+          # ordering.
+          # HEAD^ = first parent, so this covers both squash and merge-commit merges.
+          git show "HEAD^:package.json" > /tmp/package.parent.json
+          PARENT_VERSION=$(node -p "require('/tmp/package.parent.json').version")
+
+          if [ "$VERSION" != "$PARENT_VERSION" ]; then
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+          fi
+    outputs:
+      should_release: ${{ steps.decide.outputs.should_release }}
+      version: ${{ steps.decide.outputs.version }}
+      sha: ${{ github.event.workflow_run.head_sha }}
+
+
+  release:
+    needs: gate
+    if: needs.gate.outputs.should_release == 'true'
+    name: Create git tag & GitHub Release, publish to npm
+    runs-on: ubuntu-latest
+    environment: tag-release-and-publish # <- MANUAL APPROVAL GATE (required reviewer)
+    timeout-minutes: 15 # bound a hung job holding id-token: write
+    # Serialize on the VERSION — the resource that actually needs mutual exclusion (it owns
+    # the v$VERSION tag, the GitHub Release, and the npm version). Job-level concurrency can
+    # read `needs.*` (it's evaluated after `gate`), unlike top-level concurrency. Keying by
+    # version (not SHA) collapses two commits that target the SAME version (e.g. a bump, a
+    # revert, then a re-bump) into one serialized slot with a single approval.
+    concurrency:
+      group: release-${{ needs.gate.outputs.version }}
+      cancel-in-progress: false
+    permissions:
+      contents: write # create the Github release (and its tag)
+      id-token: write # OIDC trusted publishing
+    env:
+      VERSION: ${{ needs.gate.outputs.version }} # from package.json, bound once
+      SHA: ${{ needs.gate.outputs.sha }}
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: ${{ needs.gate.outputs.sha }}
+          persist-credentials: false
+      - uses: jdx/mise-action@dba19683ed58901619b14f395a24841710cb4925 # v4.1.0
+        with:
+          cache: true
+      - run: npm ci
+      - run: ./scripts/extract-notes.ts "$VERSION" /tmp/release-notes.md
+      - run: npm run build
+      - name: Create GitHub release (which creates the tag), then publish to npm
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TARBALL=$(npm pack | tail -n1)
+          # --target makes GitHub create the v$VERSION tag on the release commit as part of
+          # creating the release — tag and release are born together from one API call, so
+          # there's no separate git tag/push and no credential-helper dance. Release is
+          # created before publish (publish is the least-reversible step).
+          gh release create "v${VERSION}" --target "$SHA" --title "v${VERSION}" \
+            --notes-file /tmp/release-notes.md "$TARBALL"
+          npm publish "$TARBALL"  # OIDC: no token, provenance automatic; same artifact attached above

package-lock.json

@@ -20,13 +20,15 @@
   "scripts": {
     "start": "./src/main.ts",
     "build": "tsdown",
-    "test": "vitest run src/",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check src/"
+    "test": "vitest run src/ scripts/",
+    "typecheck": "tsc --build",
+    "lint": "biome check src/ scripts/"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.16",
     "@types/node": "^22",
+    "@types/semver": "^7.7.1",
+    "semver": "^7.8.5",
     "tsdown": "^0.22.2",
     "typescript": "^6",
     "vitest": "^4.1.8"

package.json

@@ -0,0 +1,23 @@
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+import { readFileSync } from "node:fs";
+import { assertGreater } from "./lib/semver.ts";
+
+// Prepare-time guard: verify the target version strictly increases over the current
+// package.json version. Mutates nothing — `npm version` does the actual bump.
+
+const next = process.argv[2];
+if (next === undefined) {
+  throw new Error("Usage: check-version-increases.ts <target-version>");
+}
+
+const parsed: unknown = JSON.parse(readFileSync("./package.json", "utf8"));
+if (
+  typeof parsed !== "object" ||
+  parsed === null ||
+  !("version" in parsed) ||
+  typeof parsed.version !== "string"
+) {
+  throw new Error("package.json does not contain a string `version` field.");
+}
+
+assertGreater(parsed.version, next);

scripts/check-version-increases.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+import { readFileSync, writeFileSync } from "node:fs";
+import { extractReleaseNotes } from "./lib/changelog.ts";
+
+// Release-time: pull the already-merged dated section's body out of CHANGELOG.md and
+// write it to a file for `gh release create --notes-file`.
+
+const rawVersion = process.argv[2];
+const outPath = process.argv[3];
+if (rawVersion === undefined || outPath === undefined) {
+  throw new Error("Usage: extract-notes.ts <version> <output-path>");
+}
+const version = rawVersion.replace(/^v/, "");
+
+const content = readFileSync("CHANGELOG.md", "utf8");
+writeFileSync(outPath, extractReleaseNotes(content, version));

scripts/extract-notes.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from "vitest";
+import { extractReleaseNotes, rollUnreleasedSection } from "./changelog.ts";
+
+const SAMPLE = `# Unreleased
+
+## Features
+- A shiny new thing.
+
+## Bug fixes
+- Fixed an old thing.
+
+
+# 0.1.0 (2026-06-15)
+Initial release.
+
+- Did the first things.
+`;
+
+describe("rollUnreleasedSection", () => {
+  test("inserts a dated section and re-opens an empty Unreleased", () => {
+    const rolled = rollUnreleasedSection(SAMPLE, "0.2.0", "2026-06-20");
+    expect(rolled).toBe(`# Unreleased
+
+
+# 0.2.0 (2026-06-20)
+
+## Features
+- A shiny new thing.
+
+## Bug fixes
+- Fixed an old thing.
+
+
+# 0.1.0 (2026-06-15)
+Initial release.
+
+- Did the first things.
+`);
+  });
+
+  test("leaves prior dated sections untouched", () => {
+    const rolled = rollUnreleasedSection(SAMPLE, "0.2.0", "2026-06-20");
+    expect(rolled).toContain("# 0.1.0 (2026-06-15)\nInitial release.");
+  });
+
+  test("throws when there is no Unreleased section", () => {
+    expect(() =>
+      rollUnreleasedSection(
+        "# 0.1.0 (2026-06-15)\nstuff\n",
+        "0.2.0",
+        "2026-06-20",
+      ),
+    ).toThrow(/no .*unreleased/i);
+  });
+
+  test("throws when the Unreleased section is empty", () => {
+    const empty = "# Unreleased\n\n\n# 0.1.0 (2026-06-15)\nstuff\n";
+    expect(() => rollUnreleasedSection(empty, "0.2.0", "2026-06-20")).toThrow(
+      /empty/i,
+    );
+  });
+});
+
+describe("extractReleaseNotes", () => {
+  test("returns the trimmed body of the requested version", () => {
+    expect(extractReleaseNotes(SAMPLE, "0.1.0")).toBe(
+      "Initial release.\n\n- Did the first things.",
+    );
+  });
+
+  test("throws when the version section is absent", () => {
+    expect(() => extractReleaseNotes(SAMPLE, "9.9.9")).toThrow(/no .*9\.9\.9/i);
+  });
+
+  test("throws when the version section body is empty", () => {
+    const emptyBody = "# 0.2.0 (2026-06-20)\n\n# 0.1.0 (2026-06-15)\nstuff\n";
+    expect(() => extractReleaseNotes(emptyBody, "0.2.0")).toThrow(/empty/i);
+  });
+});
+
+describe("roll then extract round-trip", () => {
+  test("extracts exactly the rolled notes for the new version", () => {
+    const rolled = rollUnreleasedSection(SAMPLE, "0.2.0", "2026-06-20");
+    expect(extractReleaseNotes(rolled, "0.2.0")).toBe(
+      `## Features
+- A shiny new thing.
+
+## Bug fixes
+- Fixed an old thing.`,
+    );
+  });
+});