@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/resolve-release/scripts/flow.test.mjs

@@ -0,0 +1,340 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { listPredefined, loadFlow, renderFlow, resolveChoices, validateFlow } from './flow.mjs'
+
+const SCRIPT = join(import.meta.dirname, 'flow.mjs')
+
+// The variation pi-better-harness releases with: package-scoped dispatch publishing, no traffic.
+const WORKSPACE_FLOW = `---
+route: workspace-npm
+publisher:
+  workflow: publish.yml
+  input: package
+  ownsTags: true
+packages:
+  exclude: [pi-better-read-aloud, navigator, sandbox-core]
+  publishLast: [pi-better-harness]
+changelog: package-scoped
+registry: https://registry.npmjs.org/
+ask:
+  - id: bundle-bump
+    question: Should pi-better-harness bundle the new component versions?
+    options: [yes, no]
+exposure: n/a
+dark: n/a
+---
+
+# Release flow
+
+## before-cut
+
+- \`npm run verify\`
+- \`npm publish --dry-run -w <workspace> --registry=<registry>\` for each package
+
+## after-publish
+
+- \`npm view <pkg> version --registry=<registry>\` prints the planned version
+- \`pi install npm:<pkg>\` succeeds
+
+## hand-back-if
+
+- a planned package has never been published on npm
+  (a first publish needs a human npm login)
+`
+
+const CANARY_FLOW = `---
+route: cloud-run
+exposure: canary
+canary:
+  steps: [10, 50]
+  holdMinutes: 15
+  healthCheck: npm run release:health -- --url {candidateUrl}
+dark: on
+flagRegistry: config/flags.json
+required: [canary]
+---
+`
+
+const flow = (text) => {
+  const result = validateFlow(text)
+  assert.deepEqual(result.errors, [])
+  return result
+}
+
+function run(cwd, args, input) {
+  return spawnSync('node', [SCRIPT, ...args], { cwd, encoding: 'utf8', input })
+}
+
+function project(text) {
+  const cwd = mkdtempSync(join(tmpdir(), 'resolve-release-flow-'))
+  if (text !== undefined) {
+    mkdirSync(join(cwd, '.release'))
+    writeFileSync(join(cwd, '.release', 'flow.md'), text)
+  }
+  return cwd
+}
+
+test('a workspace-npm flow fills slots and lists its steps per stage', () => {
+  const result = flow(WORKSPACE_FLOW)
+  assert.equal(result.settings.route, 'workspace-npm')
+  assert.deepEqual(result.settings.packages.publishLast, ['pi-better-harness'])
+  assert.equal(result.steps['before-cut'].length, 2)
+  assert.deepEqual(result.steps['hand-back-if'], ['a planned package has never been published on npm (a first publish needs a human npm login)'])
+  assert.match(result.sha256, /^[0-9a-f]{64}$/)
+  assert.notEqual(validateFlow(`${WORKSPACE_FLOW}\n`).sha256, result.sha256, 'any byte change is a different flow')
+})
+
+test('a flow cannot reshape the skeleton, the invocation policy, or invent slots', () => {
+  const cases = [
+    ['---\ntrunk: develop\n---\n', /release skeleton/],
+    ['---\ndisable-model-invocation: false\n---\n', /manual-only/],
+    ['---\nconfirm: true\n---\n', /release skeleton/],
+    ['---\nrolloutSpeed: fast\n---\n', /unknown setting "rolloutSpeed"/],
+    ['---\nroute: gitflow\n---\n', /route must be one of/],
+    ['---\n---\n## deploy-first\n- x\n', /unknown section "## deploy-first"/],
+    ['---\n---\n## before-cut\nrun the checks\n', /only "- " steps/],
+    ['# no frontmatter\n', /starts with a --- frontmatter/],
+    ['---\nroute: workspace-npm\nexposure: canary\ncanary: {steps: [10], holdMinutes: 5, healthCheck: x}\n---\n', /only to route cloud-run/],
+    ['---\nexposure: canary\n---\n', /needs a canary block/],
+    ['---\ncanary: {steps: [50, 10], holdMinutes: 5, healthCheck: x}\n---\n', /strictly increase/],
+    ['---\ncanary: {steps: [10, 100], holdMinutes: 5, healthCheck: x}\n---\n', /between 1 and 99/],
+    ['---\ndark: on\n---\n', /dark on needs flagRegistry/],
+    ['---\nrequired: [canary]\n---\n', /required canary needs exposure canary/],
+    ['---\nrequired: [speed]\n---\n', /required lists only canary/],
+    ['---\nask:\n  - {id: exposure, question: Q}\n---\n', /built-in choice/],
+    ['---\nask:\n  - {id: tier, question: Q, options: [a, b], default: c}\n---\n', /default must be one of its options/],
+    ['---\nregistry: http://registry.npmjs.org/\n---\n', /https:\/\//],
+    ['---\npackages: {exclude: [a]}\nroute: root-tag\n---\n', /only to route workspace-npm/],
+  ]
+  for (const [text, pattern] of cases) {
+    const result = validateFlow(text)
+    assert.equal(result.valid, false, text)
+    assert.ok(result.errors.some((error) => pattern.test(error)), `${text}\n→ ${result.errors.join('; ')}`)
+  }
+})
+
+test('shortcut mode with no flow is the unchanged rush-release: full, off, no questions', () => {
+  const result = resolveChoices({ mode: 'shortcut' })
+  assert.deepEqual(result.choices, { exposure: 'full', dark: 'off', canary: null, flagRegistry: null, ask: {} })
+  assert.deepEqual(result.questions, [])
+  assert.deepEqual(result.refusals, [])
+})
+
+test('shortcut mode never asks: flow defaults answer, and anything it cannot answer refuses', () => {
+  const withDefault = flow(WORKSPACE_FLOW.replace('options: [yes, no]', 'options: [yes, no]\n    default: no'))
+  const answered = resolveChoices({ mode: 'shortcut', flow: withDefault })
+  assert.deepEqual(answered.choices.ask, { 'bundle-bump': 'no' })
+  assert.equal(answered.choices.exposure, 'n/a')
+  assert.deepEqual(answered.questions, [])
+  assert.deepEqual(answered.refusals, [])
+
+  const noDefault = resolveChoices({ mode: 'shortcut', flow: flow(WORKSPACE_FLOW) })
+  assert.match(noDefault.refusals.join('\n'), /no default; rush-release never asks/)
+
+  const required = resolveChoices({ mode: 'shortcut', flow: flow(CANARY_FLOW) })
+  assert.match(required.refusals.join('\n'), /requires canary; rush-release cannot provide it/)
+  assert.equal(required.choices.exposure, 'full', 'the shortcut never takes the flow canary')
+
+  const option = resolveChoices({ mode: 'shortcut', invocation: { exposure: 'canary' } })
+  assert.match(option.refusals.join('\n'), /accepts no exposure option; use \/resolve-release/)
+})
+
+test('full mode asks exposure and dark, suggesting what the repository declares', () => {
+  const bare = resolveChoices({ mode: 'full' })
+  assert.deepEqual(bare.questions.map((q) => [q.id, q.default]), [['exposure', 'full'], ['dark', 'off']])
+  const hinted = resolveChoices({ mode: 'full', repo: { canary: true, flagRegistry: true } })
+  assert.deepEqual(hinted.questions.map((q) => [q.id, q.default]), [['exposure', 'canary'], ['dark', 'on']])
+})
+
+test('full mode asks canary details only once canary is chosen, then resolves', () => {
+  const chosen = resolveChoices({ mode: 'full', answers: { exposure: 'canary', dark: 'off' }, invocation: { healthCheck: 'npm run health' } })
+  assert.deepEqual(chosen.questions.map((q) => q.id), ['canarySteps', 'holdMinutes'])
+  const done = resolveChoices({
+    mode: 'full',
+    answers: { exposure: 'canary', dark: 'off', canarySteps: '5,25,50', holdMinutes: '10' },
+    invocation: { healthCheck: 'npm run health' },
+  })
+  assert.deepEqual(done.questions, [])
+  assert.deepEqual(done.refusals, [])
+  assert.deepEqual(done.choices.canary, { steps: [5, 25, 50], holdMinutes: 10, healthCheck: 'npm run health' })
+
+  const noHealth = resolveChoices({ mode: 'full', answers: { exposure: 'canary', dark: 'off', canarySteps: '10', holdMinutes: '5' } })
+  assert.match(noHealth.refusals.join('\n'), /repository-declared health check/)
+})
+
+test('precedence: invocation over flow over preflight answer', () => {
+  const canaryFlow = flow(CANARY_FLOW.replace('required: [canary]\n', ''))
+  const fromFlow = resolveChoices({ mode: 'full', flow: canaryFlow, answers: { exposure: 'full', dark: 'off' } })
+  assert.equal(fromFlow.choices.exposure, 'canary')
+  assert.equal(fromFlow.sources.exposure, 'flow')
+  assert.equal(fromFlow.choices.dark, 'on')
+  assert.equal(fromFlow.choices.flagRegistry, 'config/flags.json')
+  assert.deepEqual(fromFlow.questions, [])
+
+  const overridden = resolveChoices({ mode: 'full', flow: canaryFlow, invocation: { exposure: 'full', dark: 'off' } })
+  assert.equal(overridden.choices.exposure, 'full')
+  assert.equal(overridden.sources.exposure, 'invocation')
+  assert.equal(overridden.choices.canary, null)
+
+  const requiredFlow = resolveChoices({ mode: 'full', flow: flow(CANARY_FLOW), invocation: { exposure: 'full' } })
+  assert.match(requiredFlow.refusals.join('\n'), /requires canary exposure/)
+
+  const notApplicable = resolveChoices({ mode: 'full', flow: flow(WORKSPACE_FLOW), invocation: { exposure: 'canary' } })
+  assert.match(notApplicable.refusals.join('\n'), /marks exposure n\/a/)
+})
+
+test('full mode asks flow questions and checks answers against their options', () => {
+  const asked = resolveChoices({ mode: 'full', flow: flow(WORKSPACE_FLOW) })
+  assert.deepEqual(asked.questions.map((q) => q.id), ['bundle-bump'])
+  const answered = resolveChoices({ mode: 'full', flow: flow(WORKSPACE_FLOW), answers: { 'bundle-bump': 'yes' } })
+  assert.deepEqual(answered.choices.ask, { 'bundle-bump': 'yes' })
+  const wrong = resolveChoices({ mode: 'full', flow: flow(WORKSPACE_FLOW), answers: { 'bundle-bump': 'maybe' } })
+  assert.match(wrong.refusals.join('\n'), /bundle-bump must be one of yes, no/)
+})
+
+test('the CLI exit code says resolved, questions pending, refused, or invalid', () => {
+  assert.equal(run(project(), ['resolve', '--mode', 'shortcut', '--json']).status, 0)
+  const pending = run(project(), ['resolve', '--mode', 'full', '--json'])
+  assert.equal(pending.status, 4)
+  assert.equal(JSON.parse(pending.stdout).flow, null)
+  assert.equal(run(project(CANARY_FLOW), ['resolve', '--mode', 'shortcut']).status, 3)
+  const invalid = run(project('---\ntrunk: develop\n---\n'), ['resolve', '--mode', 'shortcut'])
+  assert.equal(invalid.status, 1)
+  assert.match(invalid.stdout, /release skeleton/)
+  const resolved = run(project(CANARY_FLOW), ['resolve', '--mode', 'full', '--json'])
+  assert.equal(resolved.status, 0, resolved.stdout)
+  assert.equal(JSON.parse(resolved.stdout).flow.sha256, validateFlow(CANARY_FLOW).sha256)
+  assert.equal(run(project(), ['validate']).stdout.trim(), 'no project flow at .release/flow.md')
+  assert.equal(run(project(), ['resolve']).status, 2)
+})
+
+test('saving a flow records the choices and keeps every existing slot and step', () => {
+  const cwd = project(WORKSPACE_FLOW.replace('exposure: n/a\ndark: n/a\n', ''))
+  const existing = loadFlow('.release/flow.md', { cwd })
+  const text = renderFlow({ choices: { exposure: 'full', dark: 'off', canary: null, flagRegistry: null, ask: { 'bundle-bump': 'yes' } } }, existing)
+  const saved = flow(text)
+  assert.equal(saved.settings.exposure, 'full')
+  assert.equal(saved.settings.dark, 'off')
+  assert.equal(saved.settings.route, 'workspace-npm')
+  assert.deepEqual(saved.steps, existing.steps)
+  assert.doesNotMatch(text, /bundle-bump: yes/, 'per-release answers are asked again, not saved')
+
+  const piped = run(cwd, ['render'], JSON.stringify({ choices: { exposure: 'full', dark: 'off' } }))
+  assert.equal(piped.status, 0, piped.stderr)
+  assert.equal(validateFlow(piped.stdout).valid, true)
+})
+
+// The project half of a flow that starts from the skill's predefined workspace-npm flow.
+const EXTENDING_FLOW = `---
+extends: workspace-npm
+publisher: { workflow: publish.yml, input: package, ownsTags: true }
+packages:
+  exclude: [pi-better-read-aloud]
+  publishLast: [pi-better-harness]
+ask:
+  - id: bundle-bump
+    question: Should pi-better-harness bundle the new component versions?
+    options: [yes, no]
+---
+
+## after-publish
+- \`pi install npm:<pkg>\` succeeds
+`
+
+function predefinedDir(files) {
+  const dir = mkdtempSync(join(tmpdir(), 'resolve-release-flows-'))
+  for (const [name, text] of Object.entries(files)) writeFileSync(join(dir, `${name}.md`), text)
+  return dir
+}
+
+test('every predefined flow the skill ships is valid and describes itself', () => {
+  const flows = listPredefined()
+  assert.deepEqual(flows.map((flow) => flow.name), ['cloud-run', 'cloud-run-canary', 'root-tag-npm', 'workspace-npm'])
+  for (const flow of flows) {
+    assert.deepEqual(flow.errors, [], flow.name)
+    assert.ok(flow.description.length > 20, flow.name)
+  }
+  const listed = run(project(), ['list', '--json'])
+  assert.equal(listed.status, 0)
+  assert.equal(JSON.parse(listed.stdout).length, 4)
+})
+
+test('a project flow extends a predefined one: slots merge, base steps run first', () => {
+  const flow = loadFlow('.release/flow.md', { cwd: project(EXTENDING_FLOW) })
+  assert.deepEqual(flow.errors, [])
+  assert.equal(flow.base, 'workspace-npm')
+  assert.equal(flow.settings.route, 'workspace-npm', 'from the predefined flow')
+  assert.equal(flow.settings.registry, 'https://registry.npmjs.org/', 'from the predefined flow')
+  assert.equal(flow.settings.publisher.workflow, 'publish.yml', 'from the project')
+  assert.equal('extends' in flow.settings, false)
+  assert.equal(flow.steps['after-publish'].length, 2)
+  assert.match(flow.steps['after-publish'][0], /npm view/)
+  assert.match(flow.steps['after-publish'][1], /pi install/)
+  assert.equal(flow.steps['hand-back-if'].length, 1)
+  assert.equal(resolveChoices({ mode: 'shortcut', flow }).choices.exposure, 'n/a')
+})
+
+test('the effective hash covers both files, so a skill update to the base is a different flow', () => {
+  const cwd = project('---\nextends: base\nregistry: https://r.example/\n---\n')
+  const before = loadFlow('.release/flow.md', { cwd, dir: predefinedDir({ base: '---\ndescription: base flow for tests\n---\n' }) })
+  const after = loadFlow('.release/flow.md', { cwd, dir: predefinedDir({ base: '---\ndescription: base flow for tests, changed\n---\n' }) })
+  assert.equal(before.valid, true, before.errors.join('; '))
+  assert.notEqual(before.sha256, after.sha256)
+})
+
+test('extends must name a shipped flow, and a predefined flow cannot extend', () => {
+  const unknown = loadFlow('.release/flow.md', { cwd: project('---\nextends: gitflow\n---\n') })
+  assert.equal(unknown.valid, false)
+  assert.match(unknown.errors.join('\n'), /no predefined flow "gitflow"; available: cloud-run, cloud-run-canary/)
+  const dir = predefinedDir({ chained: '---\nextends: cloud-run\n---\n' })
+  assert.match(listPredefined(dir)[0].errors.join('\n'), /cannot extend another flow/)
+})
+
+test('cross-field rules apply to the merged flow', () => {
+  const canary = loadFlow('.release/flow.md', { cwd: project('---\nextends: cloud-run-canary\ncanary: { healthCheck: npm run health }\n---\n') })
+  assert.deepEqual(canary.errors, [])
+  assert.deepEqual(canary.settings.canary, { steps: [10, 50], holdMinutes: 15, healthCheck: 'npm run health' })
+  const full = resolveChoices({ mode: 'full', flow: canary, answers: { dark: 'off' } })
+  assert.deepEqual(full.refusals, [])
+  assert.equal(full.choices.canary.healthCheck, 'npm run health')
+
+  const noHealth = loadFlow('.release/flow.md', { cwd: project('---\nextends: cloud-run-canary\n---\n') })
+  assert.equal(noHealth.valid, true, 'the health check is a resolve-time requirement')
+  assert.match(resolveChoices({ mode: 'full', flow: noHealth, answers: { dark: 'off' } }).refusals.join('\n'), /health check/)
+
+  const mismatch = loadFlow('.release/flow.md', { cwd: project('---\nextends: root-tag-npm\nexposure: canary\ncanary: { steps: [10], holdMinutes: 5 }\n---\n') })
+  assert.equal(mismatch.valid, false)
+  assert.match(mismatch.errors.join('\n'), /\.release\/flow\.md \+ root-tag-npm: canary exposure applies only to route cloud-run/)
+})
+
+test('--flow picks a predefined flow only when the project has none', () => {
+  const picked = loadFlow('.release/flow.md', { cwd: project(), name: 'cloud-run-canary' })
+  assert.equal(picked.valid, true)
+  assert.equal(picked.path, null)
+  assert.equal(picked.base, 'cloud-run-canary')
+  const shortcut = resolveChoices({ mode: 'shortcut', flow: picked })
+  assert.equal(shortcut.choices.exposure, 'full', 'the shortcut never takes a canary it was not required to')
+  assert.deepEqual(shortcut.refusals, [])
+
+  const clash = run(project(EXTENDING_FLOW), ['validate', '--flow', 'cloud-run'])
+  assert.equal(clash.status, 1)
+  assert.match(clash.stdout, /project flow wins/)
+  assert.equal(run(project(), ['resolve', '--mode', 'full', '--flow', 'nope']).status, 1)
+})
+
+test('saving a flow that extends keeps only the project half', () => {
+  const cwd = project(EXTENDING_FLOW)
+  const text = renderFlow({ choices: { exposure: 'n/a', dark: 'off' } }, loadFlow('.release/flow.md', { cwd }))
+  assert.match(text, /^extends: workspace-npm$/m)
+  assert.doesNotMatch(text, /registry:/, 'base slots stay in the skill')
+  assert.equal((text.match(/npm view/g) || []).length, 0, 'base steps are not copied')
+  assert.match(text, /pi install/)
+  const fromPredefined = renderFlow({ choices: { exposure: 'canary', dark: 'off', canary: { steps: [10, 50], holdMinutes: 15, healthCheck: 'npm run health' } } },
+    loadFlow('.release/flow.md', { cwd: project(), name: 'cloud-run-canary' }))
+  assert.match(fromPredefined, /^extends: cloud-run-canary$/m)
+  assert.equal(loadFlow('.release/flow.md', { cwd: project(fromPredefined) }).valid, true)
+})

package/skills/engineering/resolve-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
+  }
+}

package/skills/engineering/resolve-release/scripts/green-head.test.mjs

@@ -0,0 +1,101 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  findGreenHead,
+  inspectGreen,
+  parseGithubRemote,
+  pickGreenHead,
+  requiredContexts,
+} from './green-head.mjs'
+
+test('parses GitHub remotes', () => {
+  assert.deepEqual(parseGithubRemote('git@github.com:acme/app.git'), { owner: 'acme', repo: 'app' })
+  assert.deepEqual(parseGithubRemote('https://github.com/acme/app.git'), { owner: 'acme', repo: 'app' })
+  assert.equal(parseGithubRemote('git@gitlab.com:acme/app.git'), null)
+})
+
+test('required contexts union both protection shapes', () => {
+  assert.deepEqual(
+    requiredContexts({
+      required_status_checks: {
+        contexts: ['build'],
+        checks: [{ context: 'test' }, { context: 'build' }],
+      },
+    }),
+    ['build', 'test'],
+  )
+})
+
+test('required checks must all pass; pending is not green', () => {
+  const required = ['build', 'test']
+  const pending = inspectGreen({
+    status: { state: 'pending', statuses: [] },
+    checkRuns: { check_runs: [{ name: 'build', conclusion: 'success' }, { name: 'test', status: 'in_progress' }] },
+    required,
+  })
+  assert.equal(pending.green, false)
+  assert.deepEqual(pending.pending, ['test'])
+
+  const green = inspectGreen({
+    status: { state: 'success', statuses: [] },
+    checkRuns: { check_runs: [{ name: 'build', conclusion: 'success' }, { name: 'test', conclusion: 'skipped' }] },
+    required,
+  })
+  assert.equal(green.green, true)
+})
+
+test('without required checks, no CI is not green and failures refuse', () => {
+  assert.equal(inspectGreen({ status: { state: 'pending' }, checkRuns: { check_runs: [] }, required: [] }).green, false)
+  assert.equal(inspectGreen({
+    status: { state: 'success' },
+    checkRuns: { check_runs: [{ name: 'build', conclusion: 'failure' }] },
+    required: [],
+  }).green, false)
+  assert.equal(inspectGreen({
+    status: { state: 'pending', statuses: [] },
+    checkRuns: { check_runs: [{ name: 'build', conclusion: 'success' }] },
+    required: [],
+  }).green, true, 'check-run-only repositories must not be blocked by an empty combined Status API')
+
+  const pagedFailure = inspectGreen({
+    status: { state: 'pending', statuses: [] },
+    checkRuns: [
+      { check_runs: [{ name: 'build', conclusion: 'success' }] },
+      { check_runs: [{ name: 'late-page', conclusion: 'failure' }] },
+    ],
+    required: [],
+  })
+  assert.equal(pagedFailure.green, false)
+  assert.deepEqual(pagedFailure.failed, ['late-page'])
+})
+
+test('findGreenHead requests every check-run page', () => {
+  const calls = []
+  const git = (args) => {
+    if (args[0] === 'fetch') return { status: 0, stdout: '', stderr: '' }
+    if (args[0] === 'remote') return { status: 0, stdout: 'https://github.com/acme/app.git\n', stderr: '' }
+    if (args[0] === 'log') return { status: 0, stdout: `${'a'.repeat(40)}\n`, stderr: '' }
+    throw new Error(`unexpected git call: ${args.join(' ')}`)
+  }
+  const api = (path, options = {}) => {
+    calls.push({ path, options })
+    if (path.endsWith('/protection')) return null
+    if (path.endsWith('/status')) return { state: 'pending', statuses: [] }
+    if (path.includes('/check-runs')) return [{ check_runs: [{ name: 'build', conclusion: 'success' }] }]
+    throw new Error(`unexpected API call: ${path}`)
+  }
+
+  const result = findGreenHead({ cwd: '.', git, api })
+  assert.equal(result.candidateSha, 'a'.repeat(40))
+  assert.deepEqual(
+    calls.find((call) => call.path.includes('/check-runs'))?.options,
+    { paginate: true },
+  )
+})
+
+test('picker returns the newest green SHA and stops', () => {
+  const shas = ['tip-red', 'green', 'older-green']
+  const inspect = (sha) => ({ green: sha !== 'tip-red' })
+  assert.deepEqual(pickGreenHead(shas, inspect), { sha: 'green', verdict: { green: true } })
+  assert.equal(pickGreenHead(['red'], () => ({ green: false })), null)
+})