@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/resolve-release/scripts/plan.mjs

@@ -0,0 +1,806 @@
+#!/usr/bin/env node
+// Changelog + SemVer plan from baseline tag..SHA.
+//
+// Usage:
+//   node plan.mjs --sha <sha> [--trunk main] [--json] [--strict] [--cloud-run] [--dark-flags <list.json>] [--prepared-metadata <file>]
+//
+// Exit: 0 ok · 1 git/inspect failed · 2 usage
+import { createHash, randomUUID } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { isDeepStrictEqual } from 'node:util'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+const PLAN_USAGE = 'plan.mjs --sha <sha> [--trunk main] [--json] [--strict] [--cloud-run] [--dark-flags <list.json>] [--prepared-metadata <file>]'
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)$/
+const TITLE_RE = /^\s*([a-zA-Z]+)(?:\(([^)]*)\))?(!)?:\s*(.+)$/
+const SECTION_BY_TYPE = {
+  feat: 'Added',
+  fix: 'Fixed',
+  perf: 'Changed',
+  refactor: 'Changed',
+  revert: 'Removed',
+  security: 'Security',
+}
+const INTERNAL_TYPES = new Set(['build', 'chore', 'ci', 'docs', 'style', 'test'])
+const SECTION_ORDER = ['Breaking', 'Added', 'Changed', 'Removed', 'Fixed', 'Security']
+export const DISTRIBUTION_MANIFEST = 'skills/distribution/manifest.json'
+
+export function parseSemver(input) {
+  const match = SEMVER_RE.exec(String(input || '').trim())
+  if (!match) return null
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) }
+}
+
+export function formatVersion(version) {
+  return `${version.major}.${version.minor}.${version.patch}`
+}
+
+export function compareVersions(left, right) {
+  for (const key of ['major', 'minor', 'patch']) {
+    if (left[key] !== right[key]) return left[key] < right[key] ? -1 : 1
+  }
+  return 0
+}
+
+export function latestReleaseTag(tags) {
+  const parsed = tags
+    .map((tag) => ({ tag, version: parseSemver(tag) }))
+    .filter((item) => item.version)
+  if (parsed.length === 0) return null
+  parsed.sort((left, right) => compareVersions(left.version, right.version))
+  return parsed[parsed.length - 1]
+}
+
+export function nextReleaseCandidateTag(finalTag, tags) {
+  const escaped = finalTag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const pattern = new RegExp(`^${escaped}-rc\\.([1-9]\\d*)$`)
+  const ordinals = tags
+    .map((tag) => pattern.exec(tag))
+    .filter(Boolean)
+    .map((match) => Number(match[1]))
+  return `${finalTag}-rc.${ordinals.length ? Math.max(...ordinals) + 1 : 1}`
+}
+
+export function classifySubject(subject, body = '') {
+  const title = String(subject || '').trim()
+  const match = TITLE_RE.exec(title)
+  const type = match ? match[1].toLowerCase() : 'other'
+  const breaking = Boolean(match && match[3]) || /(^|\n)BREAKING[ -]CHANGE:/.test(body)
+  const internal = INTERNAL_TYPES.has(type)
+  const section = breaking ? 'Breaking' : internal ? null : (SECTION_BY_TYPE[type] || 'Changed')
+  return {
+    title,
+    type,
+    breaking,
+    internal,
+    section,
+    scope: match ? match[2] || null : null,
+    summary: match ? match[4] : title,
+  }
+}
+
+export function bumpFor(changes, current, { strict = false } = {}) {
+  const zeroVer = !strict && current.major === 0
+  if (changes.some((change) => change.breaking)) {
+    return { bump: zeroVer ? 'minor' : 'major', reason: 'breaking change in the release content' }
+  }
+  if (changes.some((change) => change.type === 'feat')) {
+    return { bump: 'minor', reason: 'new feature in the release content' }
+  }
+  return { bump: 'patch', reason: 'fixes and internal changes only' }
+}
+
+export function nextVersion(current, bump) {
+  if (bump === 'major') return { major: current.major + 1, minor: 0, patch: 0 }
+  if (bump === 'minor') return { major: current.major, minor: current.minor + 1, patch: 0 }
+  return { major: current.major, minor: current.minor, patch: current.patch + 1 }
+}
+
+export function renderChangelog({ version, date, changes, darkFlags = null }) {
+  const groups = new Map(SECTION_ORDER.map((name) => [name, []]))
+  for (const change of changes) {
+    if (!change.section) continue
+    const list = groups.get(change.section)
+    if (list) list.push(change)
+  }
+  const lines = [`## [${version}] - ${date}`]
+  for (const name of SECTION_ORDER) {
+    const items = groups.get(name)
+    if (!items.length) continue
+    lines.push('', `### ${name}`)
+    for (const item of items) lines.push(`- ${item.summary}`)
+  }
+  // Dark launch (resolve-release only): features that shipped behind a default-off flag.
+  if (darkFlags?.length) {
+    lines.push('', '### Shipped dark')
+    for (const flag of darkFlags) lines.push(`- ${flag.summary} (flag \`${flag.name}\`, off)`)
+  }
+  if (lines.length === 1) {
+    lines.push('', '- See the commits included in this tag.')
+  }
+  return `${lines.join('\n')}\n`
+}
+
+function distributionVersion(text) {
+  try {
+    const manifest = JSON.parse(text)
+    const parsed = parseSemver(manifest.releaseVersion)
+    return parsed ? formatVersion(parsed) : null
+  } catch {
+    return null
+  }
+}
+
+export function discoverVersionFiles(root) {
+  const distributionPath = join(root, DISTRIBUTION_MANIFEST)
+  if (existsSync(distributionPath) && distributionVersion(readFileSync(distributionPath, 'utf8'))) {
+    return [DISTRIBUTION_MANIFEST]
+  }
+  const files = []
+  for (const name of ['package.json', 'package-lock.json', 'pyproject.toml', 'VERSION']) {
+    if (existsSync(join(root, name))) files.push(name)
+  }
+  return files
+}
+
+export function currentVersionFromFiles(root, files = discoverVersionFiles(root)) {
+  if (files.includes(DISTRIBUTION_MANIFEST)) {
+    return distributionVersion(readFileSync(join(root, DISTRIBUTION_MANIFEST), 'utf8'))
+  }
+  if (files.includes('package.json')) {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+    const parsed = parseSemver(pkg.version)
+    if (parsed) return formatVersion(parsed)
+  }
+  if (files.includes('pyproject.toml')) {
+    const text = readFileSync(join(root, 'pyproject.toml'), 'utf8')
+    const match = text.match(/^version\s*=\s*"([^"]+)"/m)
+    const parsed = match && parseSemver(match[1])
+    if (parsed) return formatVersion(parsed)
+  }
+  if (files.includes('VERSION')) {
+    const parsed = parseSemver(readFileSync(join(root, 'VERSION'), 'utf8'))
+    if (parsed) return formatVersion(parsed)
+  }
+  return null
+}
+
+function git(args, cwd) {
+  const result = spawnSync('git', args, { encoding: 'utf8', cwd })
+  if (result.status !== 0) {
+    const err = new Error(result.stderr.trim() || `git ${args.join(' ')} failed`)
+    err.exitCode = 1
+    throw err
+  }
+  return result.stdout
+}
+
+function versionFilesAt(sha, cwd) {
+  const tree = new Set(git(['ls-tree', '-r', '--name-only', sha], cwd)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean))
+  if (tree.has(DISTRIBUTION_MANIFEST)) {
+    const version = distributionVersion(git(['show', `${sha}:${DISTRIBUTION_MANIFEST}`], cwd))
+    if (version) return [DISTRIBUTION_MANIFEST]
+  }
+  return ['package.json', 'package-lock.json', 'pyproject.toml', 'VERSION']
+    .filter((name) => tree.has(name))
+}
+
+function versionFromGitFiles(sha, files, cwd) {
+  const contents = (path) => git(['show', `${sha}:${path}`], cwd)
+  if (files.includes(DISTRIBUTION_MANIFEST)) {
+    return distributionVersion(contents(DISTRIBUTION_MANIFEST))
+  }
+  if (files.includes('package.json')) {
+    const parsed = parseSemver(JSON.parse(contents('package.json')).version)
+    if (parsed) return formatVersion(parsed)
+  }
+  if (files.includes('pyproject.toml')) {
+    const match = contents('pyproject.toml').match(/^version\s*=\s*"([^"]+)"/m)
+    const parsed = match && parseSemver(match[1])
+    if (parsed) return formatVersion(parsed)
+  }
+  if (files.includes('VERSION')) {
+    const parsed = parseSemver(contents('VERSION'))
+    if (parsed) return formatVersion(parsed)
+  }
+  return null
+}
+
+const FULL_SHA_RE = /^[0-9a-f]{40}$/
+const sha256 = (text) => createHash('sha256').update(text).digest('hex')
+
+function requirePrepared(condition, message) {
+  if (!condition) throw new Error(`prepared metadata: ${message}`)
+}
+
+function exactFields(value, fields, label) {
+  requirePrepared(value && typeof value === 'object' && !Array.isArray(value), `${label} must be an object`)
+  requirePrepared(Object.keys(value).every((key) => fields.includes(key)), `${label} has an unknown field`)
+  requirePrepared(fields.every((key) => Object.hasOwn(value, key)), `${label} is missing a required field`)
+}
+
+function requireSafePreparedVersion(actual, label) {
+  requirePrepared(typeof actual === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(actual)
+    && actual.split('.').every((part) => Number.isSafeInteger(Number(part))),
+  `${label} version must be canonical x.y.z with safe integer components`)
+}
+
+function validatePreparedInput(input) {
+  exactFields(input, ['schema', 'repository', 'version', 'metadataPr', 'cutSha', 'mergeSha', 'previousAttempt'], 'input')
+  requirePrepared(['prepared-release-metadata/v1', 'prepared-release-metadata/v2'].includes(input.schema), 'unsupported schema')
+  requirePrepared(typeof input.repository === 'string' && /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(input.repository)
+    && !input.repository.endsWith('.git'), 'repository must be owner/repo')
+  requirePrepared(typeof input.version === 'string' && parseSemver(input.version)
+    && formatVersion(parseSemver(input.version)) === input.version, 'version must be canonical x.y.z')
+  requirePrepared(Number.isSafeInteger(input.metadataPr) && input.metadataPr > 0, 'metadataPr must be a positive PR number')
+  for (const key of ['cutSha', 'mergeSha']) requirePrepared(typeof input[key] === 'string' && FULL_SHA_RE.test(input[key]), `${key} must be a full commit SHA`)
+  const previous = input.previousAttempt
+  const v2 = input.schema === 'prepared-release-metadata/v2'
+  if (v2) requirePrepared(previous && ['pre-tag', 'cloudRunRC'].includes(previous.kind), 'previousAttempt.kind must be pre-tag or cloudRunRC')
+  const preTag = v2 && previous.kind === 'pre-tag'
+  exactFields(previous, [...(v2 ? ['kind'] : []), 'receiptId', 'receiptSha256',
+    ...(preTag ? ['sourceSha'] : ['candidateTag', 'candidateSha'])], 'previousAttempt')
+  requirePrepared(typeof previous.receiptId === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(previous.receiptId), 'invalid previous receiptId')
+  requirePrepared(typeof previous.receiptSha256 === 'string' && /^[0-9a-f]{64}$/.test(previous.receiptSha256), 'invalid previous receiptSha256')
+  if (preTag) {
+    requireSafePreparedVersion(input.version, 'input')
+    requirePrepared(typeof previous.sourceSha === 'string' && FULL_SHA_RE.test(previous.sourceSha), 'previous sourceSha must be a full commit SHA')
+    return
+  }
+  const escapedTag = `v${input.version}`.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  requirePrepared(typeof previous.candidateTag === 'string' && new RegExp(`^${escapedTag}-rc\\.([1-9]\\d*)$`).test(previous.candidateTag), 'previous candidateTag must be an RC for this version')
+  const ordinal = new RegExp(`^${escapedTag}-rc\\.([1-9]\\d*)$`).exec(previous.candidateTag)?.[1]
+  requirePrepared(ordinal && Number.isSafeInteger(Number(ordinal)), 'previous candidateTag RC ordinal is out of range')
+  requirePrepared(previous.candidateSha === input.mergeSha, 'previous candidateSha must equal the historical mergeSha')
+}
+
+function canonicalRepository(cwd) {
+  // Read the declared identity, not get-url's transport rewrite (used by offline git fixtures).
+  const url = git(['config', '--get', 'remote.origin.url'], cwd).trim()
+  const match = /^(?:https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([A-Za-z0-9-]+\/[A-Za-z0-9._-]+?)(?:\.git)?$/.exec(url)
+  requirePrepared(match, 'expected a canonical GitHub origin URL')
+  return match[1]
+}
+
+function checkedCommit(sha, cwd) {
+  const actual = git(['rev-parse', '--verify', `${sha}^{commit}`], cwd).trim()
+  requirePrepared(actual === sha, 'full commit SHA must identify a commit, not a tag object')
+}
+
+function requireAncestor(ancestor, descendant, label, cwd) {
+  const result = spawnSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], { cwd, encoding: 'utf8' })
+  requirePrepared(result.status === 0, `${label} ancestor check ${result.status === 1 ? 'failed' : 'could not be inspected'}`)
+}
+
+function preparedVersionFilesAt(sha, cwd) {
+  const files = versionFilesAt(sha, cwd)
+  if (git(['ls-tree', sha, '--', 'uv.lock'], cwd).trim()) {
+    requirePrepared(files.includes('pyproject.toml'), 'uv.lock requires a root pyproject.toml')
+    files.push('uv.lock')
+  }
+  return files
+}
+
+const PREPARED_BLOB_LIMIT = 8 * 1024 * 1024
+
+function preparedBlobAt(sha, path, cwd) {
+  const result = spawnSync('git', ['show', `${sha}:${path}`], {
+    cwd, timeout: 5_000, maxBuffer: PREPARED_BLOB_LIMIT,
+  })
+  requirePrepared(!result.error && result.status === 0 && result.stdout.length <= PREPARED_BLOB_LIMIT,
+    `${path} Git blob acquisition failed (bounded to five seconds and 8 MiB)`)
+  return result.stdout
+}
+
+function preparedTomlAt(sha, path, cwd) {
+  return parsePreparedToml(preparedBlobAt(sha, path, cwd), path, cwd)
+}
+
+function preparedNumberIdentity(source) {
+  requirePrepared(typeof source === 'string', 'JSON numeric source requires Node 22+')
+  // JSON.parse owns syntax; normalize only its original numeric token, never the rounded Number.
+  const [, sign, integer, fraction = '', power = '0'] = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(source)
+  const digits = `${integer}${fraction}`.replace(/^0+/, '')
+  if (!digits) return ['number', `${sign}0`, '0']
+  const exponent = Number(power)
+  // Extreme exponents retain lexical identity without allocating an enormous BigInt.
+  if (!Number.isSafeInteger(exponent)) return ['number-source', source]
+  let end = digits.length
+  while (digits[end - 1] === '0') end -= 1
+  const coefficient = digits.slice(0, end)
+  const scale = BigInt(exponent) - BigInt(fraction.length) + BigInt(digits.length - end)
+  return ['number', `${sign}${coefficient}`, String(scale)]
+}
+
+function preparedJsonAt(sha, path, cwd) {
+  const bytes = preparedBlobAt(sha, path, cwd)
+  let parsed
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)
+    parsed = JSON.parse(text, (_key, item, context) => {
+      if (typeof item === 'number') {
+        if (!Number.isFinite(item) || (Number.isInteger(item) && !Number.isSafeInteger(item))) {
+          throw new Error('unsupported JSON number')
+        }
+        return { data: item, canonical: preparedNumberIdentity(context?.source) }
+      }
+      // Tag every node so input arrays/objects cannot impersonate numeric identities.
+      if (Array.isArray(item)) {
+        return { data: item.map((child) => child.data), canonical: ['array', item.map((child) => child.canonical)] }
+      }
+      if (item !== null && typeof item === 'object') {
+        const entries = Object.entries(item)
+        return {
+          data: Object.fromEntries(entries.map(([key, child]) => [key, child.data])),
+          canonical: ['object', Object.fromEntries(entries.map(([key, child]) => [key, child.canonical]))],
+        }
+      }
+      return { data: item, canonical: [item === null ? 'null' : typeof item, item] }
+    })
+  } catch {
+    requirePrepared(false, `${path} JSON inspection failed (requires strict UTF-8, finite numbers, safe integers and original numeric source)`)
+  }
+  requirePrepared(parsed.data && typeof parsed.data === 'object' && !Array.isArray(parsed.data), `${path} JSON root must be an object`)
+  return parsed
+}
+
+function preparedNpmAt(sha, files, version, cwd) {
+  requirePrepared(files.includes('package.json'), 'pre-tag reuse requires a publishable root package.json')
+  requireRegularFile(sha, 'package.json', cwd)
+  const { data: pkg, canonical: pkgIdentity } = preparedJsonAt(sha, 'package.json', cwd)
+  requirePrepared(typeof pkg.name === 'string' && pkg.name.length <= 214
+    && /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(pkg.name)
+    && !['node_modules', 'favicon.ico'].includes(pkg.name), 'package.json name must be a canonical safe npm package name (max 214 characters)')
+  requirePrepared(!Object.hasOwn(pkg, 'private') || pkg.private === false, 'package.json private must be absent or false')
+  requirePrepared(!Object.hasOwn(pkg, 'workspaces'), 'package.json workspaces are unsupported for pre-tag reuse')
+  const checkVersion = (actual, label) => {
+    requireSafePreparedVersion(actual, label)
+    if (version !== null) requirePrepared(actual === version, `${label} version ${actual} does not match ${version}`)
+  }
+  checkVersion(pkg.version, 'package.json')
+  if (!files.includes('package-lock.json')) return { pkg, lock: null, canonical: { pkg: pkgIdentity, lock: null } }
+  requireRegularFile(sha, 'package-lock.json', cwd)
+  const { data: lock, canonical: lockIdentity } = preparedJsonAt(sha, 'package-lock.json', cwd)
+  requirePrepared(Number.isInteger(lock.lockfileVersion) && [2, 3].includes(lock.lockfileVersion), 'package-lock.json has an unsupported lock format (expected integer 2 or 3)')
+  requirePrepared(lock.name === pkg.name, 'package-lock.json name does not match package.json')
+  checkVersion(lock.version, 'package-lock.json')
+  requirePrepared(lock.packages && typeof lock.packages === 'object' && !Array.isArray(lock.packages)
+    && Object.hasOwn(lock.packages, '') && lock.packages[''] && typeof lock.packages[''] === 'object'
+    && !Array.isArray(lock.packages['']), 'package-lock.json root identity is missing')
+  requirePrepared(lock.packages[''].name === pkg.name, 'package-lock.json root name does not match package.json')
+  checkVersion(lock.packages[''].version, 'package-lock.json root')
+  return { pkg, lock, canonical: { pkg: pkgIdentity, lock: lockIdentity } }
+}
+
+function parsePreparedToml(bytes, path, cwd) {
+  requirePrepared(bytes.length <= PREPARED_BLOB_LIMIT, `${path} exceeds TOML input limit`)
+  // Keep raw Git bytes through strict UTF-8 decoding; JSON numbers alone lose TOML types.
+  const result = spawnSync('python3', ['-I', '-S', '-c', `
+import json, math, sys, tomllib
+value = tomllib.loads(sys.stdin.buffer.read().decode('utf-8', errors='strict'))
+def canonical(value):
+    if type(value) is dict:
+        return ['dict', {key: canonical(item) for key, item in value.items()}]
+    if type(value) is list:
+        return ['list', [canonical(item) for item in value]]
+    if type(value) is bool:
+        return ['bool', value]
+    if type(value) is int:
+        if abs(value) > 9007199254740991:
+            raise ValueError('integer exceeds lossless JSON range')
+        return ['int', str(value)]
+    if type(value) is float and math.isfinite(value):
+        return ['float', value.hex()]
+    if type(value) is str:
+        return ['str', value]
+    raise ValueError('unsupported TOML value')
+json.dump({'data': value, 'canonical': canonical(value)}, sys.stdout, allow_nan=False)
+`], { cwd, input: bytes, encoding: 'utf8', timeout: 5_000, maxBuffer: PREPARED_BLOB_LIMIT })
+  requirePrepared(!result.error && result.status === 0, `${path} TOML inspection failed (requires Python 3.11+ with tomllib; bounded, JSON-compatible TOML)`)
+  try {
+    return JSON.parse(result.stdout)
+  } catch {
+    requirePrepared(false, `${path} TOML parser returned invalid JSON`)
+  }
+}
+
+// Every node, including containers, is tagged, so repository data cannot impersonate a scalar.
+function omitTomlPath(canonical, path) {
+  let node = canonical
+  for (const key of path.slice(0, -1)) node = node[1][key]
+  delete node[1][path.at(-1)]
+}
+
+function pyprojectIdentities(parsed) {
+  const { data, canonical: withoutVersions } = parsed
+  const project = data.project ?? data.tool?.poetry
+  const name = project?.name
+  const version = project?.version
+  const versions = []
+  for (const [section, path] of [[data.project, ['project', 'version']], [data.tool?.poetry, ['tool', 'poetry', 'version']]]) {
+    if (!section || !Object.hasOwn(section, 'version')) continue
+    requirePrepared(typeof section.version === 'string', 'pyproject has no static project version')
+    versions.push(section.version)
+    omitTomlPath(withoutVersions, path)
+  }
+  requirePrepared(versions.length > 0, 'pyproject has no static project version')
+  return { name, version, versions, withoutVersions }
+}
+
+function preparedPythonAt(sha, files, cwd) {
+  if (!files.includes('pyproject.toml')) return null
+  const project = pyprojectIdentities(preparedTomlAt(sha, 'pyproject.toml', cwd))
+  if (!files.includes('uv.lock')) return { project }
+  requirePrepared(typeof project.name === 'string' && project.name.trim().length > 0, 'pyproject.toml project name is missing')
+  requirePrepared(typeof project.version === 'string', 'pyproject.toml project version must be static')
+  const { data: lock, canonical: withoutRootVersion } = preparedTomlAt(sha, 'uv.lock', cwd)
+  requirePrepared(lock.version === 1 && withoutRootVersion[1].version[0] === 'int', 'uv.lock has an unsupported lock format version (expected integer 1)')
+  requirePrepared(Array.isArray(lock.package), 'uv.lock package root is missing')
+  // Include name matches so a same-name package with the wrong source cannot disappear.
+  const roots = lock.package.filter((pkg) => pkg.name === project.name
+    || pkg.source?.editable === '.' || pkg.source?.virtual === '.')
+  requirePrepared(roots.length === 1, 'uv.lock must identify exactly one project root')
+  const root = roots[0]
+  requirePrepared(root.name === project.name, 'uv.lock root name does not match pyproject.toml project name')
+  requirePrepared(isDeepStrictEqual(root.source, { editable: '.' }) || isDeepStrictEqual(root.source, { virtual: '.' }),
+    'uv.lock root source must be exactly editable = "." or virtual = "."')
+  requirePrepared(typeof root.version === 'string' && parseSemver(root.version)
+    && formatVersion(parseSemver(root.version)) === root.version, 'uv.lock root version must be canonical x.y.z')
+  const version = root.version
+  omitTomlPath(withoutRootVersion, ['package', lock.package.indexOf(root), 'version'])
+  return { project, lock: withoutRootVersion, version, rootSource: root.source }
+}
+
+function requireRegularFile(sha, path, cwd) {
+  requirePrepared(git(['ls-tree', sha, '--', path], cwd).startsWith('100644 blob '), `expected a regular metadata file: ${path}`)
+}
+
+function releaseSection(sha, version, cwd) {
+  requireRegularFile(sha, 'CHANGELOG.md', cwd)
+  const text = git(['show', `${sha}:CHANGELOG.md`], cwd)
+  const headings = [...text.matchAll(/^## \[([^\]\n]+)\][^\n]*(?:\n|$)/gm)]
+  const matches = headings.filter((heading) => heading[1] === version)
+  requirePrepared(matches.length === 1, `CHANGELOG.md must contain exactly one [${version}] section`)
+  const heading = matches[0]
+  const date = /^## \[[^\]]+\] - (\d{4}-\d{2}-\d{2})\s*$/.exec(heading[0].trim())?.[1]
+  requirePrepared(date && new Date(`${date}T00:00:00Z`).toISOString().slice(0, 10) === date, 'changelog heading needs a valid release date')
+  const next = headings.find((item) => item.index > heading.index)
+  const markdown = `${text.slice(heading.index, next?.index ?? text.length).trimEnd()}\n`
+  requirePrepared(markdown.slice(heading[0].length).trim().length > 0, 'changelog release section is empty')
+  return { markdown, date }
+}
+
+function validateRootIdentities(sha, files, version, cwd, npm = null) {
+  requirePrepared(files.length > 0, 'no supported root version files')
+  requirePrepared(!files.includes(DISTRIBUTION_MANIFEST), 'distribution-aware cuts need a dedicated metadata-only verifier; reuse is unsupported')
+  let packageName = null
+  if (!npm && files.includes('package.json')) packageName = JSON.parse(git(['show', `${sha}:package.json`], cwd)).name
+  const check = (actual, label) => {
+    if (npm) requireSafePreparedVersion(actual, label)
+    requirePrepared(actual === version, `${label} version ${actual} does not match ${version}`)
+  }
+  const python = preparedPythonAt(sha, files, cwd)
+  for (const path of files) {
+    requireRegularFile(sha, path, cwd)
+    if (npm && ['package.json', 'package-lock.json'].includes(path)) continue
+    if (path === 'pyproject.toml') {
+      for (const actual of python.project.versions) check(actual, path)
+      continue
+    }
+    if (path === 'uv.lock') {
+      check(python.version, 'uv.lock root')
+      continue
+    }
+    const text = git(['show', `${sha}:${path}`], cwd)
+    if (path === 'VERSION') check(text.trim(), path)
+    else {
+      const json = JSON.parse(text)
+      check(json.version, path === 'package-lock.json' ? 'root lock' : path)
+      if (path !== 'package-lock.json') continue
+      if (packageName !== null) requirePrepared(json.name === packageName, 'root lock name does not match package.json')
+      if (Object.hasOwn(json, 'packages')) {
+        requirePrepared(json.packages && typeof json.packages === 'object' && !Array.isArray(json.packages)
+          && Object.hasOwn(json.packages, '') && json.packages[''] && typeof json.packages[''] === 'object', 'root lock identity is missing')
+        check(json.packages[''].version, 'root lock packages[""]')
+        if (Object.hasOwn(json.packages[''], 'name') && packageName !== null) {
+          requirePrepared(json.packages[''].name === packageName, 'root lock packages[""] name does not match package.json')
+        }
+      }
+    }
+  }
+  return python
+}
+
+function identityWithoutVersion(text, path, python, npm = null) {
+  if (path === 'VERSION') return '<release-version>'
+  if (path === 'pyproject.toml') return python.project.withoutVersions
+  if (path === 'uv.lock') return python.lock
+  if (npm) {
+    const canonical = structuredClone(path === 'package.json' ? npm.canonical.pkg : npm.canonical.lock)
+    delete canonical[1].version
+    if (path === 'package-lock.json') delete canonical[1].packages[1][''][1].version
+    return canonical
+  }
+  const json = JSON.parse(text)
+  delete json.version
+  if (path === 'package-lock.json' && json.packages?.['']) delete json.packages[''].version
+  return json
+}
+
+function verifyMetadataOnlyCut(input, files, cwd, preTag = false) {
+  const { cutSha, version } = input
+  const parents = git(['rev-list', '--parents', '-n', '1', cutSha], cwd).trim().split(' ')
+  requirePrepared(parents.length === 2, 'metadata-only cut must have exactly one parent')
+  const parent = parents[1]
+  const previousFiles = preparedVersionFilesAt(parent, cwd)
+  requirePrepared(JSON.stringify(previousFiles) === JSON.stringify(files), 'metadata-only cut must preserve the root identity file set')
+  const previousPython = preparedPythonAt(parent, files, cwd)
+  const cutPython = preparedPythonAt(cutSha, files, cwd)
+  const previousNpm = preTag ? preparedNpmAt(parent, files, null, cwd) : null
+  const cutNpm = preTag ? preparedNpmAt(cutSha, files, version, cwd) : null
+  if (preTag) {
+    if (files.includes('VERSION')) requireSafePreparedVersion(git(['show', `${parent}:VERSION`], cwd).trim(), 'VERSION')
+    for (const actual of previousPython?.project.versions ?? []) requireSafePreparedVersion(actual, 'pyproject.toml')
+    if (previousPython?.version) requireSafePreparedVersion(previousPython.version, 'uv.lock root')
+  }
+  const previousVersion = previousNpm ? previousNpm.pkg.version : files.includes('package.json')
+    ? versionFromGitFiles(parent, files, cwd)
+    : previousPython?.project.version ?? versionFromGitFiles(parent, files, cwd)
+  requirePrepared(previousVersion !== version, 'metadata-only cut did not prepare a new version')
+  const changed = git(['diff', '--no-renames', '--name-only', '-z', parent, cutSha], cwd).split('\0').filter(Boolean)
+  requirePrepared(changed.includes('CHANGELOG.md') && changed.every((path) => path === 'CHANGELOG.md' || files.includes(path)), 'original cut is not metadata-only')
+  for (const path of files) {
+    const structured = path === 'pyproject.toml' || path === 'uv.lock'
+      || (preTag && ['package.json', 'package-lock.json'].includes(path))
+    const oldText = structured ? null : git(['show', `${parent}:${path}`], cwd)
+    const newText = structured ? null : git(['show', `${cutSha}:${path}`], cwd)
+    const oldValue = identityWithoutVersion(oldText, path, previousPython, previousNpm)
+    const newValue = identityWithoutVersion(newText, path, cutPython, cutNpm)
+    requirePrepared(isDeepStrictEqual(oldValue, newValue), `original cut is not metadata-only: ${path} changes more than version identity`)
+    const oldMode = git(['ls-tree', parent, '--', path], cwd).split(' ')[0]
+    const newMode = git(['ls-tree', cutSha, '--', path], cwd).split(' ')[0]
+    requirePrepared(oldMode === '100644' && newMode === oldMode, `metadata-only cut requires regular root identity files: ${path}`)
+  }
+}
+
+function inspectRemoteTags(patterns, cwd) {
+  const result = spawnSync('git', ['ls-remote', '--tags', 'origin', ...patterns], {
+    cwd, encoding: 'utf8', timeout: 30_000, maxBuffer: 8 * 1024 * 1024,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  })
+  requirePrepared(result.status === 0, 'remote inspection failed; tag absence is unproven')
+  const refs = new Map()
+  for (const line of result.stdout.split('\n').filter(Boolean)) {
+    const match = /^([0-9a-f]{40})\t(refs\/tags\/[^\s]+)$/.exec(line)
+    requirePrepared(match && !refs.has(match[2]), 'remote inspection returned invalid or duplicate refs')
+    refs.set(match[2], match[1])
+  }
+  return refs
+}
+
+function planPreparedRelease({ sha, trunk, cloudRun, darkFlags, preparedMetadata: input, cwd, now }) {
+  validatePreparedInput(input)
+  const previous = input.previousAttempt
+  const preTag = input.schema === 'prepared-release-metadata/v2' && previous.kind === 'pre-tag'
+  requirePrepared(!preTag || cloudRun === false, 'pre-tag provenance requires cloudRun false')
+  requirePrepared(typeof sha === 'string' && FULL_SHA_RE.test(sha), '--sha must be the full frozen target commit SHA')
+  requirePrepared(trunk === 'main', 'trunk must be main')
+  requirePrepared(darkFlags === null, 'dark flags cannot rewrite prepared notes; verify reviewed notes at the cut stage')
+  const repository = canonicalRepository(cwd)
+  requirePrepared(repository.toLowerCase() === input.repository.toLowerCase(), `repository ${input.repository} does not match origin ${repository}`)
+  for (const commit of [sha, input.cutSha, input.mergeSha, ...(preTag ? [previous.sourceSha] : [])]) checkedCommit(commit, cwd)
+  requireAncestor(input.cutSha, input.mergeSha, 'cut to merge', cwd)
+  requireAncestor(input.mergeSha, sha, 'historical merge to target', cwd)
+  if (preTag) {
+    requireAncestor(input.mergeSha, previous.sourceSha, 'historical merge to previous source', cwd)
+    requireAncestor(previous.sourceSha, sha, 'previous source to target', cwd)
+  }
+  requirePrepared(git(['rev-parse', `${input.cutSha}^{tree}`], cwd) === git(['rev-parse', `${input.mergeSha}^{tree}`], cwd), 'cut and merge trees must be equal')
+  const files = preparedVersionFilesAt(input.cutSha, cwd)
+  const pythonIdentities = []
+  let preparedPackageName
+  for (const commit of [input.cutSha, ...(preTag ? [previous.sourceSha] : []), sha]) {
+    requirePrepared(JSON.stringify(preparedVersionFilesAt(commit, cwd)) === JSON.stringify(files), 'root version file set changed after preparation')
+    const npm = preTag ? preparedNpmAt(commit, files, input.version, cwd) : null
+    if (npm) {
+      preparedPackageName ??= npm.pkg.name
+      requirePrepared(npm.pkg.name === preparedPackageName, 'package.json name differs from prepared identity')
+    }
+    pythonIdentities.push(validateRootIdentities(commit, files, input.version, cwd, npm))
+  }
+  const cutPython = pythonIdentities[0]
+  const targetPython = pythonIdentities.at(-1)
+  if (cutPython) {
+    requirePrepared(targetPython.project.name === cutPython.project.name, 'pyproject.toml target project name differs from prepared identity')
+    requirePrepared(isDeepStrictEqual(targetPython.rootSource, cutPython.rootSource), 'uv.lock target root source mode differs from prepared identity')
+  }
+  verifyMetadataOnlyCut(input, files, cwd, preTag)
+  const original = releaseSection(input.cutSha, input.version, cwd)
+  const prepared = releaseSection(sha, input.version, cwd)
+  const tag = `v${input.version}`
+  const refs = inspectRemoteTags([`refs/tags/${tag}`, `refs/tags/${tag}^{}`, ...(preTag ? [] : [`refs/tags/${tag}-rc.*`])], cwd)
+  requirePrepared(!refs.has(`refs/tags/${tag}`) && !refs.has(`refs/tags/${tag}^{}`), 'final tag already exists remotely; version is spent')
+  let candidateTag = null
+  if (!preTag) {
+    const previousRef = `refs/tags/${previous.candidateTag}`
+    if (refs.has(previousRef)) {
+      requirePrepared((refs.get(`${previousRef}^{}`) || refs.get(previousRef)) === previous.candidateSha, 'previous candidate remote tag SHA does not match provenance')
+    }
+    const knownTags = [...refs.keys()].map((ref) => ref.slice('refs/tags/'.length))
+    knownTags.push(...git(['tag', '--list', `${tag}-rc.*`], cwd).trim().split('\n'), previous.candidateTag)
+    candidateTag = cloudRun ? nextReleaseCandidateTag(tag, knownTags) : null
+  }
+  if (candidateTag) {
+    requirePrepared(/^v\d+\.\d+\.\d+-rc\.[1-9]\d*$/.test(candidateTag)
+      && Number.isSafeInteger(Number(candidateTag.split('-rc.')[1])), 'RC ordinal is out of range')
+    const exact = inspectRemoteTags([`refs/tags/${tag}`, `refs/tags/${tag}^{}`, `refs/tags/${candidateTag}`, `refs/tags/${candidateTag}^{}`], cwd)
+    requirePrepared(exact.size === 0, 'final or proposed candidate tag already exists remotely; replan')
+  }
+  let receiptId
+  do { receiptId = randomUUID() } while (receiptId === previous.receiptId)
+  return {
+    trunk, sha, releaseSourceSha: sha, receiptId,
+    baselineTag: null, currentVersion: input.version, bump: 'none',
+    reason: 'reuse human-approved prepared metadata; no new version cut',
+    nextVersion: input.version, tag, candidateTag, versionFiles: files, changes: [],
+    date: prepared.date, changelogMarkdown: prepared.markdown,
+    ...(preTag ? { artifact: { kind: 'npm', packageName: preparedPackageName, version: input.version } } : {}),
+    metadata: {
+      mode: 'reuse-prepared', schema: input.schema, repository, metadataPr: input.metadataPr,
+      cutSha: input.cutSha, mergeSha: input.mergeSha,
+      originalSectionSha256: sha256(original.markdown), preparedSectionSha256: sha256(prepared.markdown),
+      previousAttempt: { ...previous },
+      remoteInspection: { remote: 'origin', finalTagAbsent: tag, candidateTagAbsent: candidateTag, inspectedAt: now.toISOString() },
+    },
+  }
+}
+
+function parseLog(stdout) {
+  return stdout
+    .split('\u001e')
+    .map((chunk) => chunk.trim())
+    .filter(Boolean)
+    .map((chunk) => {
+      const [subject, ...rest] = chunk.split('\n')
+      return classifySubject(subject, rest.join('\n'))
+    })
+}
+
+export function planRelease({
+  sha,
+  trunk = 'main',
+  strict = false,
+  cloudRun = false,
+  darkFlags = null,
+  preparedMetadata = null,
+  cwd = process.cwd(),
+  now = new Date(),
+} = {}) {
+  if (!sha) {
+    const err = new Error(`usage: ${PLAN_USAGE}`)
+    err.exitCode = 2
+    throw err
+  }
+  if (preparedMetadata !== null) {
+    return planPreparedRelease({ sha, trunk, cloudRun, darkFlags, preparedMetadata, cwd, now })
+  }
+  git(['rev-parse', '--verify', sha], cwd)
+  const tags = git(['tag', '--merged', sha, '--list', 'v*'], cwd)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((tag) => parseSemver(tag))
+  const baseline = latestReleaseTag(tags)
+  const range = baseline ? `${baseline.tag}..${sha}` : sha
+  const logArgs = baseline
+    ? ['log', range, '--first-parent', '--format=%s%n%b%x1e']
+    : ['log', sha, '--first-parent', '-n', '50', '--format=%s%n%b%x1e']
+  const changes = parseLog(git(logArgs, cwd))
+  const files = versionFilesAt(sha, cwd)
+  const fileVersion = versionFromGitFiles(sha, files, cwd)
+  const current = parseSemver(fileVersion) || baseline?.version || { major: 0, minor: 0, patch: 0 }
+  const { bump, reason } = bumpFor(changes, current, { strict })
+  const next = nextVersion(current, bump)
+  const version = formatVersion(next)
+  const tag = `v${version}`
+  const candidateTag = cloudRun
+    ? nextReleaseCandidateTag(tag, git(['tag', '--list', `${tag}-rc.*`], cwd)
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean))
+    : null
+  const date = now.toISOString().slice(0, 10)
+  return {
+    trunk,
+    sha,
+    baselineTag: baseline?.tag || null,
+    currentVersion: formatVersion(current),
+    bump,
+    reason,
+    nextVersion: version,
+    tag,
+    candidateTag,
+    versionFiles: files,
+    changes,
+    date,
+    changelogMarkdown: renderChangelog({ version, date, changes, darkFlags }),
+    ...(darkFlags ? { darkFlags } : {}),
+  }
+}
+
+// The `dark-flags.mjs list --json` output (or its `flags` array): [{ name, summary }].
+function readDarkFlags(path) {
+  if (!path) {
+    const err = new Error('--dark-flags needs a file')
+    err.exitCode = 2
+    throw err
+  }
+  const parsed = JSON.parse(readFileSync(path, 'utf8'))
+  const flags = Array.isArray(parsed) ? parsed : parsed.flags
+  if (!Array.isArray(flags) || flags.some((flag) => !flag?.name || !flag?.summary)) {
+    const err = new Error('--dark-flags must list { name, summary } entries')
+    err.exitCode = 2
+    throw err
+  }
+  return flags.map(({ name, summary }) => ({ name, summary }))
+}
+
+function parseArgs(argv) {
+  const opts = { json: false, strict: false, cloudRun: false, trunk: 'main', sha: null, darkFlags: null, preparedMetadata: null }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--json') opts.json = true
+    else if (arg === '--strict') opts.strict = true
+    else if (arg === '--cloud-run') opts.cloudRun = true
+    else if (arg === '--sha') opts.sha = argv[++i]
+    else if (arg === '--trunk') opts.trunk = argv[++i]
+    else if (arg === '--dark-flags') opts.darkFlags = readDarkFlags(argv[++i])
+    else if (arg === '--prepared-metadata') {
+      const path = argv[++i]
+      if (!path || path.startsWith('--')) {
+        const err = new Error('--prepared-metadata needs a JSON file')
+        err.exitCode = 2
+        throw err
+      }
+      opts.preparedMetadata = JSON.parse(readFileSync(path, 'utf8'))
+      if (opts.preparedMetadata === null) throw new Error('--prepared-metadata must be an object')
+    }
+    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.sha || !opts.trunk) {
+    const err = new Error(`usage: ${PLAN_USAGE}`)
+    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(`${PLAN_USAGE}\n`)
+    return 0
+  }
+  const result = planRelease(opts)
+  process.stdout.write(opts.json ? `${JSON.stringify(result, null, 2)}\n` : `${result.tag}\n${result.changelogMarkdown}`)
+  return 0
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    process.exitCode = main()
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`)
+    process.exitCode = error.exitCode || 1
+  }
+}