@1aboveio/skills 0.18.0 → 0.19.0

package/skills/engineering/rush-release/references/cut.md

@@ -0,0 +1,66 @@
+# Cut
+
+Turn the frozen SHA into a versioned commit without taking later trunk commits
+along for the ride.
+
+## 1. Plan
+
+```bash
+node <skillsRoot>/rush-release/scripts/plan.mjs --sha <candidateSha> --json \
+  > /tmp/rush-release-plan.json
+```
+
+The plan names `baselineTag`, `currentVersion`, `bump`, `reason`,
+`nextVersion`, `tag`, `changelogMarkdown`, and `versionFiles`.
+
+SemVer (0.x treats breaking as minor unless the human asks for strict):
+
+| Content since baseline | Bump |
+|---|---|
+| breaking (`feat!:`, `BREAKING CHANGE:`) | major (minor under 0.x) |
+| `feat:` | minor |
+| otherwise | patch |
+
+Changelog entries come from conventional-commit subjects in
+`baselineTag..candidateSha` (or the recent first-parent log when there is no
+tag). Keep an existing `## [Unreleased]` body — derived entries merge with it,
+they do not replace it.
+
+## 2. Confirm
+
+Show the frozen SHA, proposed version/tag, bump reason, changelog, version
+files, and publisher. Wait for confirmation. A different bump the human names
+wins, as long as it is still SemVer.
+
+Do not create a branch, edit files, or tag before that confirmation.
+
+## 3. Apply and commit
+
+Branch from the frozen SHA only:
+
+```bash
+git switch -c release/<tag> <candidateSha>
+jq -r '.changelogMarkdown' /tmp/rush-release-plan.json | \
+  node <skillsRoot>/rush-release/scripts/apply.mjs \
+    --version <nextVersion> --date <YYYY-MM-DD> \
+    --changelog-section - --json
+git add -- <paths from apply>
+git commit -m "chore(release): <nextVersion>"
+```
+
+`apply.mjs` requires the confirmed plan's `changelogMarkdown` on stdin, writes
+that section, and bumps the discovered identity files. It refuses a missing or
+empty changelog section rather than silently replacing the plan with a bare
+version heading. If the human edited the notes, write the confirmed markdown
+to stdin instead of the raw plan field.
+
+Then:
+
+- Diff must be metadata only. If product code changed, reset and stop.
+- `git rev-parse HEAD^` must equal the frozen SHA.
+- Do not rebase onto a newer `main`, merge `main` in, or squash onto a moved
+  tip. Any of those would tag commits this candidate check never saw.
+
+The cut SHA is `HEAD` after the commit. It is the immutable PR-head identity;
+the release identity is the provider's verified merged SHA on `main`.
+Proceed to [publish.md](publish.md).

package/skills/engineering/rush-release/references/preflight.md

@@ -0,0 +1,47 @@
+# Preflight
+
+Preflight has three outputs: trunk `main`, the publisher to watch, and the
+files that carry the version. It does not pick the SHA, bump the version, or
+push.
+
+## 1. Trunk
+
+Fetch `origin`. Confirm the release trunk is `main` from those fetched refs
+(`origin/main` exists). A repo whose production branch is `master` or `release`
+is not this workflow.
+
+## 2. Publisher
+
+Detect how a tag becomes a shipped artifact. Prefer what the human named;
+otherwise look at the tree:
+
+| Signal | Publisher |
+|---|---|
+| `cloudbuild.yaml` / `cloudbuild.json`, or a Cloud Build trigger on `v*` / `v*-rc.*` tags | `cloudbuild` |
+| `package.json` with a publish workflow, `publishConfig`, or an explicit npm release | `npm` |
+| both | watch both |
+| neither, and the human did not name one | refuse — nothing to watch |
+
+Record `publisher` as `cloudbuild`, `npm`, or `both`. If a GitHub Actions
+workflow publishes on `release: published` rather than on tag push, note that
+`gh release create` is required at publish time.
+
+## 3. Version files
+
+List identity files present at the repo root (and only those):
+
+- `package.json` (and `package-lock.json` when it exists)
+- `pyproject.toml`
+- `VERSION`
+
+Do not bump nested workspace packages unless the human names them. The cut
+must stay metadata-only.
+
+## 4. Baseline
+
+Read the current version from those files when present. List annotated/lightweight
+release tags matching `vMAJOR.MINOR.PATCH` with no prerelease. The highest such
+tag is the changelog baseline. A prerelease (`v1.2.0-rc.1`) is not a baseline.
+
+Preflight succeeds when trunk, publisher, version files, and baseline are
+recorded. Proceed to [candidate.md](candidate.md).

package/skills/engineering/rush-release/references/publish.md

@@ -0,0 +1,100 @@
+# Publish
+
+Push the cut, tag it, and watch the publisher. The tag is the deploy trigger
+in this lane, so a pushed tag that fails to ship **burns the version** — the
+next attempt takes the next patch. Do not move or delete the tag to "reuse" it.
+
+## 1. Push and merge the metadata PR
+
+Push the immutable cut head, then open a PR against `main`. Do not create or
+push the release tag yet:
+
+```bash
+git push origin HEAD:refs/heads/release/<tag>
+gh pr create --base main --head release/<tag> \
+  --title "chore(release): <nextVersion>" \
+  --body "Metadata-only GitHub Flow release cut from <candidateSha>."
+```
+
+Deliver that PR through the repository's configured merge queue and its
+stateful watcher. The queue must test the synthetic merged tree. Freeze the
+provider-reported merge commit as `<mergedSha>` and independently verify the
+PR's head was `<cutSha>`. A squash merge is refused because `<cutSha>` would
+not be an ancestor of `<mergedSha>`.
+
+If `main` is genuinely unprotected and direct pushes are the repository's
+documented release path, a successful fast-forward of `<cutSha>` to `main`
+may use `<cutSha>` as `<mergedSha>`. Never infer this from local state: re-fetch
+and verify the remote ref.
+
+## 2. Verify and tag the merged main SHA
+
+The release tag must name a commit reachable from the remote default branch.
+This is the ancestry gate used by release publishers to refuse off-main
+releases:
+
+```bash
+git fetch origin main
+git merge-base --is-ancestor "<cutSha>" "<mergedSha>"
+git merge-base --is-ancestor "<mergedSha>" origin/main
+test "$(git rev-parse "<cutSha>^{tree}")" = \
+  "$(git rev-parse "<mergedSha>^{tree}")"
+test "$(git show "<mergedSha>:package.json" | jq -r .version)" = "<nextVersion>"
+git tag -a "<tag>" "<mergedSha>" -m "Release <tag>"
+git push --no-verify origin "refs/tags/<tag>"
+```
+
+The tree equality check proves the provider merge introduced no post-freeze
+`main` changes beyond the approved cut. If it fails, do not tag: abandon the
+unpublished cut and restart candidate selection and planning from current
+`main`. Use the repository's declared version file in the `git show` check
+when it is not `package.json`. Re-read the exact required queue/CI result for
+`<mergedSha>` before tagging. A green cut head is not evidence for a different
+merge commit.
+
+`--no-verify` is for tag refs, because a Mergify (or similar) pre-push hook
+that rewrites `git push` into a stack push is correct for branches and wrong
+for immutable tags.
+
+Re-tagging the same SHA is a resume no-op. A tag that already names a
+**different** SHA is a stop. There is no `--force`.
+
+If preflight recorded a workflow that publishes only on
+`release: published`, create the GitHub Release after the tag is on the
+remote (`gh release create <tag> --notes-file …`). Otherwise the tag push is
+the trigger.
+
+## 3. Watch
+
+Launch one background watcher; do not poll in the foreground.
+
+**Cloud Build** (`publisher` `cloudbuild` or `both`):
+
+```bash
+gcloud builds list --limit=1 --format='value(id,status,substitutions.TAG_NAME)' \
+  --filter="substitutions.TAG_NAME=<tag> OR tags=<tag>"
+```
+
+Success is `SUCCESS` for that tag. `FAILURE` / `TIMEOUT` / `CANCELLED` is a
+hand-back. Load `cloud-debug` only to diagnose, not to rerun the release.
+
+**npm** (`publisher` `npm` or `both`):
+
+```bash
+npm view <package>@<nextVersion> version
+```
+
+Success is stdout equal to `<nextVersion>`. An `E404` means "not published
+yet" and the watcher continues. Any other npm error is inconclusive — stop
+rather than treating it as unpublished or published.
+
+When a GitHub Actions workflow is the npm publisher, `gh run list` /
+`gh run watch` for the tag SHA is the wait; `npm view` remains the proof the
+artifact exists.
+
+## 4. Failure
+
+If the watch fails, leave the tag in place and hand back: cut SHA, tag,
+publisher logs, and that the version is burned. Do not delete the tag, do not
+roll back production, and do not open a `resolve-release` traffic shift. A
+fix ships as the next patch from a new green HEAD.

package/skills/engineering/rush-release/scripts/apply.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// Write changelog section + version identity files. Does not commit.
+//
+// Usage:
+//   node apply.mjs --version <x.y.z> --date <YYYY-MM-DD> --changelog-section - [--json]
+//
+// Exit: 0 ok · 1 IO/parse failed · 2 usage
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { discoverVersionFiles, parseSemver } from './plan.mjs'
+
+export function insertChangelog(markdown, { version, date, section }) {
+  const heading = `## [${version}] - ${date}`
+  const body = String(section || '').trim() || heading
+  const existing = String(markdown || '')
+  if (!body.startsWith(heading)) {
+    const err = new Error(`changelog section must start with ${heading}`)
+    err.exitCode = 2
+    throw err
+  }
+  const escapedVersion = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const versionHeading = new RegExp(`^## \\[${escapedVersion}\\][^\\n]*`, 'm').exec(existing)
+  if (versionHeading) {
+    const start = versionHeading.index
+    const rest = existing.slice(start)
+    const next = rest.slice(versionHeading[0].length).search(/^## \[/m)
+    const end = next === -1 ? existing.length : start + versionHeading[0].length + next
+    const actual = existing.slice(start, end).trim()
+    if (actual === body || actual.startsWith(`${body}\n`)) return existing
+    const err = new Error(`existing ${version} changelog section does not match the confirmed plan`)
+    err.exitCode = 1
+    throw err
+  }
+
+  const unreleased = /^## \[Unreleased\]\s*\n/m.exec(existing)
+  if (unreleased) {
+    const start = unreleased.index + unreleased[0].length
+    const next = existing.slice(start).search(/^## \[/m)
+    const end = next === -1 ? existing.length : start + next
+    const kept = existing.slice(start, end).trim()
+    const combined = kept ? `${body}\n\n${kept}` : body
+    return `${existing.slice(0, unreleased.index)}## [Unreleased]\n\n${heading}\n${stripHeading(combined, version)}\n\n${existing.slice(end).replace(/^\n+/, '')}`
+  }
+
+  const title = /^# .+\n/.exec(existing)
+  if (title) {
+    return `${existing.slice(0, title[0].length)}\n${body}\n\n${existing.slice(title[0].length).replace(/^\n+/, '')}`
+  }
+  return `# Changelog\n\n${body}\n`
+}
+
+function stripHeading(text, version) {
+  return text.replace(new RegExp(`^## \\[${version}\\][^\\n]*\\n?`), '').trim()
+}
+
+export function bumpPackageJson(text, version) {
+  const pkg = JSON.parse(text)
+  pkg.version = version
+  return `${JSON.stringify(pkg, null, 2)}\n`
+}
+
+export function bumpPackageLock(text, version) {
+  const lock = JSON.parse(text)
+  lock.version = version
+  if (lock.packages && lock.packages[''] && typeof lock.packages[''] === 'object') {
+    lock.packages[''].version = version
+  }
+  return `${JSON.stringify(lock, null, 2)}\n`
+}
+
+export function bumpPyproject(text, version) {
+  let inProject = false
+  let replaced = false
+  const lines = String(text).split('\n')
+  const out = lines.map((line) => {
+    if (/^\[project\]\s*$/.test(line) || /^\[tool\.poetry\]\s*$/.test(line)) inProject = true
+    else if (/^\[/.test(line)) inProject = false
+    if (inProject && /^version\s*=/.test(line)) {
+      replaced = true
+      return `version = "${version}"`
+    }
+    return line
+  })
+  if (!replaced) {
+    const err = new Error('pyproject.toml has no [project]/[tool.poetry] version')
+    err.exitCode = 1
+    throw err
+  }
+  return out.join('\n')
+}
+
+export function applyRelease({
+  version,
+  date,
+  cwd = process.cwd(),
+  changelogSection = null,
+  now = new Date(),
+} = {}) {
+  if (!parseSemver(version)) {
+    const err = new Error('usage: apply.mjs --version <x.y.z> --date <YYYY-MM-DD> --changelog-section - [--json]')
+    err.exitCode = 2
+    throw err
+  }
+  if (typeof changelogSection !== 'string' || changelogSection.trim() === '') {
+    const err = new Error('apply.mjs requires the confirmed plan changelog via --changelog-section -')
+    err.exitCode = 2
+    throw err
+  }
+  const stamp = date || now.toISOString().slice(0, 10)
+  const files = discoverVersionFiles(cwd)
+  const changed = []
+  const changelogPath = join(cwd, 'CHANGELOG.md')
+  const previous = existsSync(changelogPath) ? readFileSync(changelogPath, 'utf8') : ''
+  writeFileSync(changelogPath, insertChangelog(previous, { version, date: stamp, section: changelogSection }))
+  changed.push('CHANGELOG.md')
+
+  if (files.includes('package.json')) {
+    writeFileSync(join(cwd, 'package.json'), bumpPackageJson(readFileSync(join(cwd, 'package.json'), 'utf8'), version))
+    changed.push('package.json')
+  }
+  if (files.includes('package-lock.json')) {
+    writeFileSync(join(cwd, 'package-lock.json'), bumpPackageLock(readFileSync(join(cwd, 'package-lock.json'), 'utf8'), version))
+    changed.push('package-lock.json')
+  }
+  if (files.includes('pyproject.toml')) {
+    writeFileSync(join(cwd, 'pyproject.toml'), bumpPyproject(readFileSync(join(cwd, 'pyproject.toml'), 'utf8'), version))
+    changed.push('pyproject.toml')
+  }
+  if (files.includes('VERSION')) {
+    writeFileSync(join(cwd, 'VERSION'), `${version}\n`)
+    changed.push('VERSION')
+  }
+  return { version, date: stamp, changed }
+}
+
+function readStdin() {
+  return readFileSync(0, 'utf8')
+}
+
+function parseArgs(argv) {
+  const opts = { json: false, version: null, date: null, changelogSection: null }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--json') opts.json = true
+    else if (arg === '--version') opts.version = argv[++i]
+    else if (arg === '--date') opts.date = argv[++i]
+    else if (arg === '--changelog-section') opts.changelogFrom = argv[++i]
+    else if (arg === '--help' || arg === '-h') opts.help = true
+    else {
+      const err = new Error(`unknown argument: ${arg}`)
+      err.exitCode = 2
+      throw err
+    }
+  }
+  if (opts.help) return opts
+  if (!opts.version || !opts.date || !opts.changelogFrom) {
+    const err = new Error('usage: apply.mjs --version <x.y.z> --date <YYYY-MM-DD> --changelog-section - [--json]')
+    err.exitCode = 2
+    throw err
+  }
+  if (opts.changelogFrom === '-') opts.changelogSection = readStdin()
+  else if (opts.changelogFrom) opts.changelogSection = opts.changelogFrom
+  return opts
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv)
+  if (opts.help) {
+    process.stdout.write('apply.mjs --version <x.y.z> --date <YYYY-MM-DD> --changelog-section - [--json]\n')
+    return 0
+  }
+  const result = applyRelease(opts)
+  process.stdout.write(opts.json ? `${JSON.stringify(result, null, 2)}\n` : `${result.changed.join('\n')}\n`)
+  return 0
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    process.exitCode = main()
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`)
+    process.exitCode = error.exitCode || 1
+  }
+}

package/skills/engineering/rush-release/scripts/green-head.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// Newest first-parent SHA on trunk whose required CI is already green.
+//
+// Usage:
+//   node green-head.mjs [--trunk main] [--max 50] [--json]
+//
+// Exit: 0 found · 1 no green head / inspect failed · 2 usage
+import { spawnSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+export const DEFAULT_TRUNK = 'main'
+export const DEFAULT_MAX = 50
+const PASSING = new Set(['success', 'neutral', 'skipped'])
+const FAILING = new Set(['failure', 'failed', 'error', 'timed_out', 'cancelled', 'action_required', 'stale', 'startup_failure'])
+
+export function parseGithubRemote(url) {
+  const raw = String(url || '').trim()
+  const ssh = raw.match(/^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/)
+  if (ssh) return { owner: ssh[1], repo: ssh[2] }
+  const https = raw.match(/^https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/)
+  if (https) return { owner: https[1], repo: https[2] }
+  const sshUrl = raw.match(/^ssh:\/\/git@github\.com\/([^/]+)\/(.+?)(?:\.git)?$/)
+  if (sshUrl) return { owner: sshUrl[1], repo: sshUrl[2] }
+  return null
+}
+
+export function runGit(args, { cwd, allowFail = false } = {}) {
+  const result = spawnSync('git', args, { encoding: 'utf8', cwd })
+  if (result.status !== 0 && !allowFail) {
+    const err = new Error(result.stderr.trim() || `git ${args.join(' ')} failed`)
+    err.exitCode = 1
+    throw err
+  }
+  return result
+}
+
+export function ghApi(path, { cwd, paginate = false } = {}) {
+  const args = ['api', path]
+  if (paginate) args.push('--paginate', '--slurp')
+  const result = spawnSync('gh', args, { encoding: 'utf8', cwd })
+  if (result.status !== 0) {
+    const err = new Error(result.stderr.trim() || `gh api ${path} failed`)
+    err.exitCode = 1
+    err.status = result.status
+    throw err
+  }
+  return result.stdout ? JSON.parse(result.stdout) : null
+}
+
+export function requiredContexts(protection) {
+  if (!protection || typeof protection !== 'object') return []
+  const checks = protection.required_status_checks
+  if (!checks) return []
+  const names = []
+  for (const context of checks.contexts || []) names.push(String(context))
+  for (const check of checks.checks || []) {
+    if (check && check.context) names.push(String(check.context))
+  }
+  return [...new Set(names)]
+}
+
+function conclusionOf(run) {
+  return String(run?.conclusion || run?.status || '').toLowerCase()
+}
+
+export function inspectGreen({ status, checkRuns, required }) {
+  const runs = Array.isArray(checkRuns)
+    ? checkRuns.flatMap((page) => Array.isArray(page?.check_runs) ? page.check_runs : [page])
+    : checkRuns?.check_runs || []
+  const statuses = Array.isArray(status?.statuses) ? status.statuses : []
+  const state = String(status?.state || '').toLowerCase()
+  const byName = new Map()
+  for (const run of runs) {
+    const name = String(run.name || run.context || '')
+    if (name && !byName.has(name)) byName.set(name, run)
+  }
+
+  if (required.length > 0) {
+    const missing = []
+    const pending = []
+    const failed = []
+    for (const name of required) {
+      const run = byName.get(name)
+      const statusContext = statuses.find((item) => item.context === name)
+      const token = run ? conclusionOf(run) : String(statusContext?.state || '').toLowerCase()
+      if (!token) missing.push(name)
+      else if (token === 'pending' || token === 'queued' || token === 'in_progress') pending.push(name)
+      else if (FAILING.has(token)) failed.push(name)
+      else if (!PASSING.has(token) && token !== 'success') failed.push(name)
+    }
+    const green = missing.length === 0 && pending.length === 0 && failed.length === 0
+    return { green, missing, pending, failed, required: true }
+  }
+
+  const failedStatuses = statuses.filter((item) => FAILING.has(String(item?.state || '').toLowerCase()))
+  const pendingStatuses = statuses.filter((item) => ['pending', 'queued', 'in_progress', ''].includes(String(item?.state || '').toLowerCase()))
+  const passingStatuses = statuses.filter((item) => PASSING.has(String(item?.state || '').toLowerCase()))
+  if (state === 'failure' || state === 'error' || failedStatuses.length > 0) {
+    return { green: false, missing: [], pending: [], failed: ['combined-status'], required: false }
+  }
+  const pendingRuns = runs.filter((run) => {
+    const token = conclusionOf(run)
+    return token === 'pending' || token === 'queued' || token === 'in_progress' || token === ''
+  })
+  const failedRuns = runs.filter((run) => FAILING.has(conclusionOf(run)))
+  const passingRuns = runs.filter((run) => PASSING.has(conclusionOf(run)))
+  if (failedRuns.length > 0) {
+    return { green: false, missing: [], pending: [], failed: failedRuns.map((run) => run.name), required: false }
+  }
+  if (pendingRuns.length > 0 || pendingStatuses.length > 0) {
+    return {
+      green: false,
+      missing: [],
+      pending: [
+        ...pendingRuns.map((run) => run.name || 'check-run'),
+        ...pendingStatuses.map((item) => item.context || 'status-context'),
+      ],
+      failed: [],
+      required: false,
+    }
+  }
+  if (state === 'success' || passingRuns.length > 0 || passingStatuses.length > 0) {
+    return { green: true, missing: [], pending: [], failed: [], required: false }
+  }
+  return { green: false, missing: ['no-checks'], pending: [], failed: [], required: false }
+}
+
+export function pickGreenHead(shas, inspect) {
+  for (const sha of shas) {
+    const verdict = inspect(sha)
+    if (verdict.green) return { sha, verdict }
+  }
+  return null
+}
+
+function loadProtection(owner, repo, trunk, api) {
+  try {
+    return api(`repos/${owner}/${repo}/branches/${trunk}/protection`)
+  } catch (error) {
+    if (/HTTP 404|Not Found|no required/i.test(error.message)) return null
+    throw error
+  }
+}
+
+export function findGreenHead({
+  trunk = DEFAULT_TRUNK,
+  max = DEFAULT_MAX,
+  cwd,
+  git = runGit,
+  api = (path, options = {}) => ghApi(path, { cwd, ...options }),
+} = {}) {
+  git(['fetch', 'origin', trunk], { cwd })
+  const remote = parseGithubRemote(git(['remote', 'get-url', 'origin'], { cwd }).stdout)
+  if (!remote) {
+    const err = new Error('origin is not a GitHub remote')
+    err.exitCode = 1
+    throw err
+  }
+  const log = git(['log', `origin/${trunk}`, '--first-parent', '-n', String(max), '--format=%H'], { cwd })
+  const shas = log.stdout.split('\n').map((line) => line.trim()).filter(Boolean)
+  if (shas.length === 0) {
+    const err = new Error(`no commits on origin/${trunk}`)
+    err.exitCode = 1
+    throw err
+  }
+  const protection = loadProtection(remote.owner, remote.repo, trunk, api)
+  const required = requiredContexts(protection)
+  const inspect = (sha) => {
+    const status = api(`repos/${remote.owner}/${remote.repo}/commits/${sha}/status`)
+    const checks = api(`repos/${remote.owner}/${remote.repo}/commits/${sha}/check-runs?per_page=100`, { paginate: true })
+    return inspectGreen({ status, checkRuns: checks, required })
+  }
+  const picked = pickGreenHead(shas, inspect)
+  if (!picked) {
+    const err = new Error('no-green-head')
+    err.exitCode = 1
+    throw err
+  }
+  return {
+    trunk,
+    owner: remote.owner,
+    repo: remote.repo,
+    tipSha: shas[0],
+    candidateSha: picked.sha,
+    walked: shas.indexOf(picked.sha) + 1,
+    requiredChecks: required,
+    verdict: picked.verdict,
+  }
+}
+
+function parseArgs(argv) {
+  const opts = { trunk: DEFAULT_TRUNK, max: DEFAULT_MAX, json: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--json') opts.json = true
+    else if (arg === '--trunk') opts.trunk = argv[++i]
+    else if (arg === '--max') opts.max = Number(argv[++i])
+    else if (arg === '--help' || arg === '-h') opts.help = true
+    else {
+      const err = new Error(`unknown argument: ${arg}`)
+      err.exitCode = 2
+      throw err
+    }
+  }
+  if (!opts.trunk || !Number.isInteger(opts.max) || opts.max < 1) {
+    const err = new Error('usage: green-head.mjs [--trunk main] [--max 50] [--json]')
+    err.exitCode = 2
+    throw err
+  }
+  return opts
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv)
+  if (opts.help) {
+    process.stdout.write('green-head.mjs [--trunk main] [--max 50] [--json]\n')
+    return 0
+  }
+  const result = findGreenHead({ trunk: opts.trunk, max: opts.max })
+  process.stdout.write(opts.json ? `${JSON.stringify(result, null, 2)}\n` : `${result.candidateSha}\n`)
+  return 0
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    process.exitCode = main()
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`)
+    process.exitCode = error.exitCode || 1
+  }
+}