@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/adapter-completion-artifact.mjs

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import { TextDecoder } from 'node:util'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+export const COMPLETION_SCHEMA = 'resolve-release/isolated-adapter-completion@2'
+export const COMPLETION_ARTIFACT_MAX_BYTES = 1024 * 1024
+export const COMPLETION_COUNT_MAX = 1_000_000
+export const COMPLETION_MATRICES = Object.freeze({
+  ambient: 81,
+  processAdjacent: 18,
+  generated: 81,
+})
+export const COMPLETION_POLICY = Object.freeze({
+  id: 'resolve-release/isolated-adapter-completion-policy@1',
+  suites: Object.freeze({
+    focused: Object.freeze({
+      id: 'resolve-release/isolated-adapter-focused@1',
+      minimumPassed: 77,
+    }),
+    full: Object.freeze({
+      id: 'resolve-release/full-suite@1',
+      minimumPassed: 900,
+    }),
+  }),
+})
+
+const SHA_PATTERN = /^[a-f0-9]{40}$/
+const HASH_PATTERN = /^[a-f0-9]{64}$/
+const ROOT_FIELDS = Object.freeze([
+  'schema', 'status', 'issue', 'parent', 'epic', 'componentHead',
+  'callerVerifiedHead', 'publicLoaderExecuted', 'matrices', 'policy', 'tests', 'integrity',
+])
+const TEST_FIELDS = Object.freeze(['suite', 'passed', 'failed', 'floor'])
+const INTEGRITY_FIELDS = Object.freeze(['algorithm', 'sha256'])
+const UTF8_DECODER = new TextDecoder('utf-8', { fatal: true })
+
+function fail(code) {
+  const error = new Error(code)
+  error.code = code
+  throw error
+}
+
+function isObject(value) {
+  return value != null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function exactFields(value, expected, code) {
+  if (!isObject(value) || Object.keys(value).sort().join('\0') !== [...expected].sort().join('\0')) fail(code)
+}
+
+function positiveInteger(value, code) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > COMPLETION_COUNT_MAX) fail(code)
+  return value
+}
+
+function boundedInteger(value, code) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > COMPLETION_COUNT_MAX) fail(code)
+  return value
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(',')}]`
+  if (isObject(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`).join(',')}}`
+  }
+  const encoded = JSON.stringify(value)
+  if (encoded === undefined) fail('e:completion-not-serializable')
+  return encoded
+}
+
+function digestBody(body) {
+  return crypto.createHash('sha256').update(canonicalize(body)).digest('hex')
+}
+
+function completionBody({
+  componentHead,
+  callerVerifiedHead,
+  focusedPassed,
+  focusedFailed = 0,
+  focusedFloor,
+  fullPassed,
+  fullFailed = 0,
+  fullFloor,
+}) {
+  if (!SHA_PATTERN.test(componentHead ?? '') || !SHA_PATTERN.test(callerVerifiedHead ?? '')) {
+    fail('e:completion-head-invalid')
+  }
+  if (componentHead !== callerVerifiedHead) fail('e:completion-caller-head-mismatch')
+  const focused = {
+    suite: COMPLETION_POLICY.suites.focused.id,
+    passed: positiveInteger(focusedPassed, 'e:completion-focused-count-invalid'),
+    failed: boundedInteger(focusedFailed, 'e:completion-focused-count-invalid'),
+    floor: positiveInteger(focusedFloor, 'e:completion-focused-floor-invalid'),
+  }
+  const full = {
+    suite: COMPLETION_POLICY.suites.full.id,
+    passed: positiveInteger(fullPassed, 'e:completion-full-count-invalid'),
+    failed: boundedInteger(fullFailed, 'e:completion-full-count-invalid'),
+    floor: positiveInteger(fullFloor, 'e:completion-full-floor-invalid'),
+  }
+  if (focused.floor !== COMPLETION_POLICY.suites.focused.minimumPassed) {
+    fail('e:completion-focused-policy-floor-mismatch')
+  }
+  if (full.floor !== COMPLETION_POLICY.suites.full.minimumPassed) {
+    fail('e:completion-full-policy-floor-mismatch')
+  }
+  if (focused.failed !== 0 || focused.passed < focused.floor) fail('e:completion-focused-floor-unmet')
+  if (full.failed !== 0 || full.passed < full.floor) fail('e:completion-full-floor-unmet')
+  return {
+    schema: COMPLETION_SCHEMA,
+    status: 'complete',
+    issue: 980,
+    parent: 939,
+    epic: 904,
+    componentHead,
+    callerVerifiedHead,
+    publicLoaderExecuted: true,
+    matrices: { ...COMPLETION_MATRICES },
+    policy: COMPLETION_POLICY.id,
+    tests: { focused, full },
+  }
+}
+
+export function createCompletionArtifact(input) {
+  const body = completionBody(input)
+  return Object.freeze({
+    ...body,
+    matrices: Object.freeze(body.matrices),
+    tests: Object.freeze({
+      focused: Object.freeze(body.tests.focused),
+      full: Object.freeze(body.tests.full),
+    }),
+    integrity: Object.freeze({ algorithm: 'sha256', sha256: digestBody(body) }),
+  })
+}
+
+function artifactStat(file, code) {
+  try {
+    return fs.lstatSync(file, { bigint: true })
+  } catch {
+    fail(code)
+  }
+}
+
+function sameArtifactIdentity(left, right) {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.mode === right.mode
+    && left.size === right.size
+    && left.mtimeNs === right.mtimeNs
+    && left.ctimeNs === right.ctimeNs
+}
+
+function validateArtifactStat(stat) {
+  if (stat.isSymbolicLink()) fail('e:completion-artifact-symlink')
+  if (!stat.isFile()) fail('e:completion-artifact-not-regular-file')
+  if ((stat.mode & 0o222n) !== 0n) fail('e:completion-artifact-writable')
+  if (stat.size > BigInt(COMPLETION_ARTIFACT_MAX_BYTES)) fail('e:completion-artifact-too-large')
+}
+
+function openArtifact(file) {
+  if (!Number.isInteger(fs.constants.O_NOFOLLOW)) fail('e:completion-artifact-nofollow-unsupported')
+  if (!Number.isInteger(fs.constants.O_NONBLOCK)) fail('e:completion-artifact-nonblock-unsupported')
+  try {
+    return fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK)
+  } catch {
+    fail('e:completion-artifact-unreadable')
+  }
+}
+
+function readArtifactBytes(fd, expectedSize) {
+  const size = Number(expectedSize)
+  const bytes = Buffer.alloc(size)
+  let offset = 0
+  while (offset < size) {
+    const count = fs.readSync(fd, bytes, offset, size - offset, offset)
+    if (count === 0) fail('e:completion-artifact-changed-during-acquisition')
+    offset += count
+  }
+  const extra = Buffer.alloc(1)
+  if (fs.readSync(fd, extra, 0, 1, offset) !== 0) {
+    fail('e:completion-artifact-changed-during-acquisition')
+  }
+  return bytes
+}
+
+function readCheckedCompletionArtifact(file) {
+  if (typeof file !== 'string' || file.length === 0) fail('e:completion-artifact-unreadable')
+  const approved = artifactStat(file, 'e:completion-artifact-unreadable')
+  validateArtifactStat(approved)
+
+  const fd = openArtifact(file)
+  let bytes
+  let opened
+  let acquisitionError
+  try {
+    opened = fs.fstatSync(fd, { bigint: true })
+    validateArtifactStat(opened)
+    if (!sameArtifactIdentity(approved, opened)) fail('e:completion-artifact-replaced-before-open')
+
+    const afterOpenPath = artifactStat(file, 'e:completion-artifact-replaced-after-open')
+    if (!sameArtifactIdentity(opened, afterOpenPath)) {
+      fail('e:completion-artifact-replaced-after-open')
+    }
+
+    bytes = readArtifactBytes(fd, opened.size)
+    const afterRead = fs.fstatSync(fd, { bigint: true })
+    if (!sameArtifactIdentity(opened, afterRead)) {
+      fail('e:completion-artifact-changed-during-acquisition')
+    }
+    const afterReadPath = artifactStat(file, 'e:completion-artifact-replaced-after-open')
+    if (!sameArtifactIdentity(opened, afterReadPath)) {
+      fail('e:completion-artifact-replaced-after-open')
+    }
+  } catch (error) {
+    acquisitionError = error?.code?.startsWith?.('e:completion-')
+      ? error
+      : Object.assign(new Error('e:completion-artifact-unreadable'), {
+          code: 'e:completion-artifact-unreadable',
+        })
+  } finally {
+    try {
+      fs.closeSync(fd)
+    } catch {
+      if (acquisitionError == null) {
+        acquisitionError = Object.assign(new Error('e:completion-artifact-close-failed'), {
+          code: 'e:completion-artifact-close-failed',
+        })
+      }
+    }
+  }
+  if (acquisitionError != null) throw acquisitionError
+
+  try {
+    return UTF8_DECODER.decode(bytes)
+  } catch {
+    fail('e:completion-artifact-invalid-utf8')
+  }
+}
+
+function parseCheckedCompletionArtifact(file) {
+  const text = readCheckedCompletionArtifact(file)
+  try {
+    return JSON.parse(text)
+  } catch {
+    fail('e:completion-artifact-json-invalid')
+  }
+}
+
+function validateTestResult(value, name) {
+  exactFields(value, TEST_FIELDS, `e:completion-${name}-shape-invalid`)
+  const trusted = COMPLETION_POLICY.suites[name]
+  if (value.suite !== trusted.id) fail(`e:completion-${name}-suite-unsupported`)
+  const passed = positiveInteger(value.passed, `e:completion-${name}-count-invalid`)
+  const failed = boundedInteger(value.failed, `e:completion-${name}-count-invalid`)
+  const floor = positiveInteger(value.floor, `e:completion-${name}-floor-invalid`)
+  if (floor !== trusted.minimumPassed) fail(`e:completion-${name}-policy-floor-mismatch`)
+  if (failed !== 0 || passed < floor) fail(`e:completion-${name}-floor-unmet`)
+}
+
+function verifyCompletionValue(artifact, { expectedComponentHead, expectedSha256 }) {
+  exactFields(artifact, ROOT_FIELDS, 'e:completion-shape-invalid')
+  if (artifact.schema !== COMPLETION_SCHEMA || artifact.status !== 'complete'
+      || artifact.issue !== 980 || artifact.parent !== 939 || artifact.epic !== 904
+      || artifact.publicLoaderExecuted !== true || artifact.policy !== COMPLETION_POLICY.id) {
+    fail('e:completion-contract-invalid')
+  }
+  if (!SHA_PATTERN.test(expectedComponentHead ?? '') || artifact.componentHead !== expectedComponentHead
+      || artifact.callerVerifiedHead !== expectedComponentHead) {
+    fail('e:completion-finalizer-head-mismatch')
+  }
+  exactFields(artifact.matrices, Object.keys(COMPLETION_MATRICES), 'e:completion-matrices-invalid')
+  if (Object.entries(COMPLETION_MATRICES).some(([name, count]) => artifact.matrices[name] !== count)) {
+    fail('e:completion-matrices-invalid')
+  }
+  exactFields(artifact.tests, ['focused', 'full'], 'e:completion-tests-shape-invalid')
+  validateTestResult(artifact.tests.focused, 'focused')
+  validateTestResult(artifact.tests.full, 'full')
+  exactFields(artifact.integrity, INTEGRITY_FIELDS, 'e:completion-integrity-invalid')
+  if (artifact.integrity.algorithm !== 'sha256' || !HASH_PATTERN.test(artifact.integrity.sha256 ?? '')
+      || !HASH_PATTERN.test(expectedSha256 ?? '')) {
+    fail('e:completion-integrity-invalid')
+  }
+  const { integrity, ...body } = artifact
+  const actual = digestBody(body)
+  if (integrity.sha256 !== actual || expectedSha256 !== actual) fail('e:completion-sha256-mismatch')
+  return Object.freeze({
+    status: 'verified',
+    policy: COMPLETION_POLICY.id,
+    componentHead: artifact.componentHead,
+    callerVerifiedHead: artifact.callerVerifiedHead,
+    sha256: actual,
+    tests: Object.freeze({
+      focused: Object.freeze({
+        suite: artifact.tests.focused.suite,
+        passed: artifact.tests.focused.passed,
+        minimumPassed: COMPLETION_POLICY.suites.focused.minimumPassed,
+      }),
+      full: Object.freeze({
+        suite: artifact.tests.full.suite,
+        passed: artifact.tests.full.passed,
+        minimumPassed: COMPLETION_POLICY.suites.full.minimumPassed,
+      }),
+    }),
+  })
+}
+
+export function verifyCompletionArtifact(file, expected) {
+  const artifact = parseCheckedCompletionArtifact(file)
+  return verifyCompletionValue(artifact, expected)
+}
+
+function parseArgs(argv) {
+  const positional = []
+  const options = {}
+  const known = new Set([
+    '--component-head', '--caller-verified-head', '--focused-passed', '--focused-failed',
+    '--focused-floor', '--full-passed', '--full-failed', '--full-floor', '--artifact',
+    '--sha256', '--output',
+  ])
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index]
+    if (!value.startsWith('--')) positional.push(value)
+    else {
+      if (!known.has(value) || options[value] !== undefined) fail('e:completion-option-invalid')
+      const next = argv[++index]
+      if (next == null || next.startsWith('--')) fail('e:completion-option-invalid')
+      options[value] = next
+    }
+  }
+  return { positional, options }
+}
+
+function numberOption(options, name, defaultValue) {
+  if (options[name] == null) return defaultValue
+  if (!/^\d+$/.test(options[name])) fail('e:completion-option-invalid')
+  return Number(options[name])
+}
+
+function writeOutput(value, output) {
+  const text = `${JSON.stringify(value)}\n`
+  if (output == null) process.stdout.write(text)
+  else fs.writeFileSync(output, text, { encoding: 'utf8', flag: 'wx', mode: 0o444 })
+}
+
+export function main(argv) {
+  const { positional, options } = parseArgs(argv)
+  const command = positional[0]
+  if (positional.length !== 1 || !['emit', 'verify'].includes(command)) fail('e:completion-command-invalid')
+  const commandOptions = command === 'emit'
+    ? new Set(['--component-head', '--caller-verified-head', '--focused-passed',
+        '--focused-failed', '--focused-floor', '--full-passed', '--full-failed',
+        '--full-floor', '--output'])
+    : new Set(['--artifact', '--component-head', '--sha256', '--output'])
+  if (Object.keys(options).some((name) => !commandOptions.has(name))) fail('e:completion-option-invalid')
+  if (command === 'emit') {
+    const artifact = createCompletionArtifact({
+      componentHead: options['--component-head'],
+      callerVerifiedHead: options['--caller-verified-head'],
+      focusedPassed: numberOption(options, '--focused-passed'),
+      focusedFailed: numberOption(options, '--focused-failed', 0),
+      focusedFloor: numberOption(options, '--focused-floor'),
+      fullPassed: numberOption(options, '--full-passed'),
+      fullFailed: numberOption(options, '--full-failed', 0),
+      fullFloor: numberOption(options, '--full-floor'),
+    })
+    writeOutput(artifact, options['--output'])
+    return 0
+  }
+  if (options['--artifact'] == null) fail('e:completion-option-invalid')
+  const verified = verifyCompletionArtifact(options['--artifact'], {
+    expectedComponentHead: options['--component-head'],
+    expectedSha256: options['--sha256'],
+  })
+  writeOutput(verified, options['--output'])
+  return 0
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    process.exitCode = main(process.argv.slice(2))
+  } catch (error) {
+    process.stderr.write(`${error?.code ?? 'e:completion-failed'}\n`)
+    process.exitCode = 1
+  }
+}

package/skills/engineering/resolve-release/scripts/build-changes.mjs

@@ -0,0 +1,209 @@
+// build-changes — assemble the `--changes` JSON that `version.mjs plan|changelog` consumes,
+// from the constituent PRs, WITHOUT the two silent failures the hand-run gh→jq recipe carries.
+//
+// `version.mjs plan --changes <json>` reads an array of `{ pr, title, labels?, body?, issues? }`
+// (see version.mjs `readChanges` / `classifyChange`). `gh pr view --json` does NOT emit that
+// shape, and copying its output straight through fails SILENTLY in two ways this script closes:
+//
+//   #407 — number → pr, and the vanishing close-links. gh emits `number`, not `pr`, and emits
+//     no `issues` field at all. `classifyChange` still computes the bump off `title`/`labels`,
+//     so `plan` LOOKS correct — while every `closes #n` link silently vanishes from the cut
+//     CHANGELOG, discovered only when a human reads the published notes. This script renames
+//     `number` → `pr` and derives `issues` (from gh's `closingIssuesReferences` PLUS a parse of
+//     `Closes/Fixes/Resolves #N` in the body), so the links survive.
+//
+//   #408 — a BREAKING CHANGE in the body escaping the bump. `classifyChange` (version.mjs:~112)
+//     reads `BREAKING[ -]CHANGE:` out of `change.body`, but the hand recipe never fetched
+//     `body`, so a breaking footer living only in a PR body was invisible → a `minor` bump where
+//     a `major` was owed, a silently under-versioned release. This script fetches `body` and
+//     carries it through, so `classifyChange` sees the footer and bumps major.
+//
+// The `gh pr view --json` query below therefore MUST include `body` (for #408) and
+// `closingIssuesReferences` (for #407) alongside `number`/`title`/`labels`. Dropping either from
+// the field list re-opens the corresponding silent failure — the CLI test asserts the query
+// carries both.
+
+import fs from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// The gh `--json` field list the query MUST request. `body` is load-bearing for #408 and
+// `closingIssuesReferences` for #407 — see the header. Exported so the test can assert the
+// query the CLI builds still carries both rather than silently regressing.
+export const GH_JSON_FIELDS = ['number', 'title', 'labels', 'body', 'closingIssuesReferences']
+
+// GitHub's closing keywords (https://docs.github.com/issues/tracking-your-work-with-issues/
+// linking-a-pull-request-to-an-issue): close/closes/closed, fix/fixes/fixed, resolve/resolves/
+// resolved, case-insensitive, followed by `#N`. This is the same set gh resolves into
+// `closingIssuesReferences`; we parse it out of the body too because a body may name a link gh
+// did not resolve (a cross-repo `owner/repo#N`, a PR opened before the issue existed), and
+// because a caller feeding a captured body without that gh field still gets its links.
+const CLOSING_RE = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\b[:\s]+#(\d+)/gi
+
+// Parse `Closes #N` / `Fixes #N` / `Resolves #N` (and their case/tense variants) out of a PR
+// body, returning `#N` strings in first-seen order. Never throws on a null/empty body.
+export function parseClosingIssues(body) {
+  const out = []
+  const seen = new Set()
+  for (const m of String(body || '').matchAll(CLOSING_RE)) {
+    const ref = `#${m[1]}`
+    if (!seen.has(ref)) {
+      seen.add(ref)
+      out.push(ref)
+    }
+  }
+  return out
+}
+
+// Normalize gh's `labels` (array of `{name}` objects) OR an already-flattened array of strings
+// into a `string[]`. `classifyChange` lowercases labels itself, so we keep the raw name.
+function normalizeLabels(labels) {
+  if (!Array.isArray(labels)) return []
+  return labels.map((l) => (typeof l === 'string' ? l : l && l.name ? String(l.name) : null)).filter(Boolean)
+}
+
+// The `issues` a change closes: gh's resolved `closingIssuesReferences` FIRST (the authoritative
+// linked-issue field), then any body-parsed `Closes #N` the field did not already carry. Deduped,
+// order-preserving, each as `#N`.
+function deriveIssues(raw) {
+  const out = []
+  const seen = new Set()
+  const push = (ref) => {
+    const norm = `#${String(ref).replace(/^#/, '')}`
+    if (!seen.has(norm)) {
+      seen.add(norm)
+      out.push(norm)
+    }
+  }
+  if (Array.isArray(raw.closingIssuesReferences)) {
+    for (const ref of raw.closingIssuesReferences) {
+      if (ref && ref.number != null) push(ref.number)
+    }
+  }
+  for (const ref of parseClosingIssues(raw.body)) push(ref)
+  return out
+}
+
+// The pure transform: one raw gh PR object → one `{ pr, title, labels, body, issues }` change.
+// This is where #407's `number` → `pr` rename and `issues` derivation, and #408's `body`
+// pass-through, actually happen.
+export function buildChange(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new TypeError('build-changes: each gh PR record must be an object')
+  }
+  if (raw.number == null) {
+    throw new Error('build-changes: gh PR record has no `number` — was the query missing `number`?')
+  }
+  return {
+    pr: `#${String(raw.number).replace(/^#/, '')}`,
+    title: String(raw.title || ''),
+    labels: normalizeLabels(raw.labels),
+    body: raw.body == null ? '' : String(raw.body),
+    issues: deriveIssues(raw),
+  }
+}
+
+// The pure transform over a whole gh result: accepts either the array `gh pr list --json` emits
+// or a single object from `gh pr view --json`, and returns the `--changes` array `version.mjs
+// plan` accepts. No gh, no network — this is the unit under test.
+export function buildChanges(rawGhJson) {
+  const records = Array.isArray(rawGhJson) ? rawGhJson : [rawGhJson]
+  return records.map(buildChange)
+}
+
+// ---- gh (CLI only) ----
+
+// Fetch one PR's raw gh JSON. The `--json` list MUST carry GH_JSON_FIELDS (body +
+// closingIssuesReferences included) or the silent failures re-open. `run` is injectable so the
+// CLI path is testable without a live gh (the test puts a captured-gh shim on PATH, which is the
+// default `gh` here).
+function fetchPr(pr, { repo, run = defaultGh } = {}) {
+  const args = ['pr', 'view', String(pr), '--json', GH_JSON_FIELDS.join(',')]
+  if (repo) args.push('--repo', repo)
+  const r = run(args)
+  if (r.status !== 0) {
+    throw new Error(`build-changes: \`gh ${args.join(' ')}\` failed (exit ${r.status}): ${(r.stderr || '').trim()}`)
+  }
+  return JSON.parse(r.stdout)
+}
+
+function defaultGh(args) {
+  const r = spawnSync('gh', args, { encoding: 'utf8' })
+  return { status: r.status ?? 1, stdout: r.stdout || '', stderr: r.stderr || '' }
+}
+
+const USAGE = `build-changes — assemble the \`--changes\` JSON for \`version.mjs plan|changelog\`.
+
+Runs \`gh pr view --json\` for each constituent PR (including \`body\` and
+\`closingIssuesReferences\`), renames gh's \`number\` → the \`pr\` field \`version.mjs\` expects,
+derives \`issues\` (from \`closingIssuesReferences\` + \`Closes/Fixes/Resolves #N\` in the body),
+and carries \`body\` through so a \`BREAKING CHANGE:\` living only in a PR body still bumps major.
+
+Usage:
+  build-changes <pr>...            [--repo owner/name]   query gh for each PR, emit the --changes array
+  build-changes --raw <file>|-                            transform captured gh JSON (array or object); no gh call
+  build-changes --help | -h                               print this usage and exit 0
+
+Output: a JSON array of { pr, title, labels, body, issues } on stdout — feed it to
+  \`version.mjs plan --changes -\`  (pipe) or  \`--changes <file>\`.
+
+Why a script and not the raw gh→jq recipe (both fail SILENTLY):
+  #407  gh emits \`number\`, not \`pr\`, and no \`issues\` — copied straight through, the bump still
+        computes off titles/labels so \`plan\` looks correct while every \`closes #n\` link vanishes
+        from the published notes. This renames number→pr and derives issues.
+  #408  the hand recipe never fetched \`body\`, so a \`BREAKING CHANGE:\` in a PR body escaped
+        classification → a minor bump where major was owed. This fetches and carries body.
+
+Doctrine: references/versioning.md (§6, the bump). Bump/flag reference: version.mjs --help.`
+
+export function main(argv, { run = defaultGh, readStdin = () => fs.readFileSync(0, 'utf8') } = {}) {
+  const args = [...argv]
+  const prs = []
+  let repo = null
+  let rawSource = null
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--help' || a === '-h' || a === 'help') {
+      console.log(USAGE)
+      return 0
+    }
+    if (a === '--repo') {
+      repo = args[++i]
+      continue
+    }
+    if (a === '--raw') {
+      rawSource = args[++i] ?? '-'
+      continue
+    }
+    if (a.startsWith('-') && a !== '-') {
+      console.error(`build-changes: unknown flag "${a}" (see --help).`)
+      return 2
+    }
+    prs.push(a)
+  }
+
+  try {
+    let changes
+    if (rawSource != null) {
+      const text = rawSource === '-' ? readStdin() : fs.readFileSync(rawSource, 'utf8')
+      changes = buildChanges(JSON.parse(text))
+    } else {
+      if (prs.length === 0) {
+        console.error('build-changes: give one or more PR numbers, or --raw <file>|- (see --help).')
+        return 2
+      }
+      changes = buildChanges(prs.map((pr) => fetchPr(pr, { repo, run })))
+    }
+    console.log(JSON.stringify(changes, null, 2))
+    return 0
+  } catch (err) {
+    console.error(`build-changes: ${err.message}`)
+    return 1
+  }
+}
+
+// Only run the CLI when invoked directly (so tests import the pure transforms).
+if (isMainModule(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)))
+}