@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,500 @@
+#!/usr/bin/env node
+// Release flows: predefined flows shipped in ../flows/, and a project's own .release/flow.md,
+// which may `extends:` one of them. Validate the effective flow, resolve the release choices,
+// render a project flow.
+//
+// Usage:
+//   node flow.mjs list [--json]
+//   node flow.mjs validate [--file .release/flow.md] [--flow <predefined>] [--json]
+//   node flow.mjs resolve --mode full|shortcut [--file .release/flow.md] [--flow <predefined>] [--json]
+//        [--exposure full|canary] [--canary-steps 10,50] [--hold-minutes 15]
+//        [--health-check <cmd>] [--dark on|off] [--flag-registry <path>]
+//        [--answer <id>=<value>]... [--repo-canary] [--repo-flag-registry]
+//   node flow.mjs render [--file .release/flow.md] [--flow <predefined>] < resolved.json
+//
+// Exit: 0 ok/resolved · 1 invalid flow · 2 usage · 3 refused · 4 questions pending
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { dumpYamlMapping, parseYamlMapping } from '../../engineering-runtime/scripts/yaml-mapping.mjs'
+
+export const DEFAULT_FLOW_PATH = '.release/flow.md'
+export const PREDEFINED_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'flows')
+const FLOW_NAME = /^[a-z0-9][a-z0-9-]*$/
+export const ROUTES = ['root-tag', 'workspace-npm', 'cloud-run']
+export const STEP_SECTIONS = ['before-cut', 'after-merge', 'before-exposure', 'after-publish', 'after-live', 'hand-back-if']
+const SETTING_KEYS = ['extends', 'description', 'route', 'publisher', 'packages', 'changelog', 'registry', 'ask', 'exposure', 'canary', 'dark', 'flagRegistry', 'required']
+// Keys that would reshape the release rather than fill a slot of it. Named so the refusal says why.
+const SKELETON_KEYS = new Set([
+  'trunk', 'branch', 'releaseBranch', 'stages', 'skip', 'skipStages', 'confirm', 'confirmPlan',
+  'invocation', 'autoInvoke', 'disable-model-invocation', 'allow_implicit_invocation',
+])
+const CHOICE_IDS = new Set(['exposure', 'dark', 'canarySteps', 'holdMinutes'])
+const ASK_ID = /^[a-z][A-Za-z0-9-]*$/
+
+const isMapping = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+const isText = (value) => typeof value === 'string' && value.trim() !== ''
+const isTextList = (value) => Array.isArray(value) && value.every(isText)
+
+function normalizeSwitch(value) {
+  if (value === true) return 'on'
+  if (value === false) return 'off'
+  return value
+}
+
+export function splitFlow(text) {
+  const source = String(text ?? '').replace(/\r\n/g, '\n')
+  const match = /^---\n(?:([\s\S]*?)\n)?---(?:\n|$)/.exec(source)
+  if (!match) return { frontmatter: null, body: source }
+  return { frontmatter: match[1] ?? '', body: source.slice(match[0].length) }
+}
+
+export function parseSteps(body) {
+  const steps = {}
+  const errors = []
+  let current = null
+  for (const line of String(body).split('\n')) {
+    const heading = /^##\s+(.+?)\s*$/.exec(line)
+    if (heading) {
+      const name = heading[1].trim()
+      if (!STEP_SECTIONS.includes(name)) {
+        errors.push(`unknown section "## ${name}"; allowed: ${STEP_SECTIONS.join(', ')}`)
+        current = null
+        continue
+      }
+      if (steps[name]) errors.push(`section "## ${name}" appears twice`)
+      steps[name] = steps[name] || []
+      current = name
+      continue
+    }
+    if (!current || line.trim() === '') continue
+    const bullet = /^[-*]\s+(.+)$/.exec(line)
+    if (bullet) steps[current].push(bullet[1].trim())
+    else if (/^\s+\S/.test(line) && steps[current].length) {
+      steps[current][steps[current].length - 1] += ` ${line.trim()}`
+    } else errors.push(`section "## ${current}" holds only "- " steps; found: ${line.trim()}`)
+  }
+  return { steps, errors }
+}
+
+function validateSettings(settings, { predefined = false, partial = false } = {}) {
+  const errors = []
+  if (settings.extends !== undefined) {
+    if (predefined) errors.push('a predefined flow cannot extend another flow')
+    else if (!isText(settings.extends) || !FLOW_NAME.test(settings.extends)) errors.push('extends must name a predefined flow')
+  }
+  if (settings.description !== undefined && !isText(settings.description)) errors.push('description must be text')
+  for (const key of Object.keys(settings)) {
+    if (SKELETON_KEYS.has(key)) errors.push(`"${key}" would change the release skeleton or manual-only invocation; a flow only fills slots`)
+    else if (!SETTING_KEYS.includes(key)) errors.push(`unknown setting "${key}"; allowed: ${SETTING_KEYS.join(', ')}`)
+  }
+  const { route, exposure, canary, flagRegistry, required } = settings
+  const dark = normalizeSwitch(settings.dark)
+  if (route !== undefined && !ROUTES.includes(route)) errors.push(`route must be one of ${ROUTES.join(', ')}`)
+  if (settings.publisher !== undefined) {
+    if (!isMapping(settings.publisher)) errors.push('publisher must be a mapping')
+    else for (const [key, value] of Object.entries(settings.publisher)) {
+      if (!['string', 'boolean', 'number'].includes(typeof value)) errors.push(`publisher.${key} must be a scalar`)
+    }
+  }
+  if (settings.packages !== undefined) {
+    if (!isMapping(settings.packages)) errors.push('packages must be a mapping')
+    else {
+      for (const key of Object.keys(settings.packages)) {
+        if (!['exclude', 'publishLast'].includes(key)) errors.push(`unknown packages.${key}; allowed: exclude, publishLast`)
+        else if (!isTextList(settings.packages[key])) errors.push(`packages.${key} must be a list of package names`)
+      }
+      if (route !== undefined && route !== 'workspace-npm') errors.push('packages applies only to route workspace-npm')
+    }
+  }
+  if (settings.changelog !== undefined && !['root', 'package-scoped'].includes(settings.changelog)) {
+    errors.push('changelog must be root or package-scoped')
+  }
+  if (settings.registry !== undefined && !(isText(settings.registry) && /^https:\/\//.test(settings.registry))) {
+    errors.push('registry must be an https:// URL')
+  }
+  if (settings.ask !== undefined) {
+    if (!Array.isArray(settings.ask)) errors.push('ask must be a list')
+    else {
+      const seen = new Set()
+      settings.ask.forEach((item, index) => {
+        const where = `ask[${index}]`
+        if (!isMapping(item)) return errors.push(`${where} must be a mapping with id and question`)
+        for (const key of Object.keys(item)) {
+          if (!['id', 'question', 'options', 'default'].includes(key)) errors.push(`unknown ${where}.${key}`)
+        }
+        if (!isText(item.id) || !ASK_ID.test(item.id)) errors.push(`${where}.id must match ${ASK_ID}`)
+        else if (CHOICE_IDS.has(item.id)) errors.push(`${where}.id "${item.id}" is a built-in choice; set it directly`)
+        else if (seen.has(item.id)) errors.push(`${where}.id "${item.id}" is repeated`)
+        else seen.add(item.id)
+        if (!isText(item.question)) errors.push(`${where}.question must be text`)
+        if (item.options !== undefined && !(isTextList(item.options) && item.options.length >= 2)) {
+          errors.push(`${where}.options must list at least two choices`)
+        }
+        if (item.default !== undefined) {
+          if (!isText(item.default)) errors.push(`${where}.default must be text`)
+          else if (item.options && !item.options.includes(item.default)) errors.push(`${where}.default must be one of its options`)
+        }
+      })
+    }
+  }
+  if (exposure !== undefined && !['full', 'canary', 'n/a'].includes(exposure)) errors.push('exposure must be full, canary or n/a')
+  if (canary !== undefined) {
+    if (!isMapping(canary)) errors.push('canary must be a mapping')
+    else {
+      for (const key of Object.keys(canary)) {
+        if (!['steps', 'holdMinutes', 'healthCheck'].includes(key)) errors.push(`unknown canary.${key}`)
+      }
+      // A project half may set only some canary keys; the merged flow must have them all.
+      const stepError = partial && canary.steps === undefined ? null : canarySteps(canary.steps).error
+      if (stepError) errors.push(`canary.steps ${stepError}`)
+      if (!(partial && canary.holdMinutes === undefined) && !(Number.isInteger(canary.holdMinutes) && canary.holdMinutes > 0)) {
+        errors.push('canary.holdMinutes must be a positive integer')
+      }
+      // Optional here so a predefined flow can declare steps; the project supplies the command,
+      // and resolving a canary without one is a refusal.
+      if (canary.healthCheck !== undefined && !isText(canary.healthCheck)) errors.push('canary.healthCheck must be the repository command that judges each hold')
+    }
+  }
+  if (exposure === 'canary' && canary === undefined) errors.push('exposure canary needs a canary block (steps, holdMinutes)')
+  if ((exposure === 'canary' || canary !== undefined) && route !== undefined && route !== 'cloud-run') {
+    errors.push('canary exposure applies only to route cloud-run')
+  }
+  if (dark !== undefined && !['on', 'off', 'n/a'].includes(dark)) errors.push('dark must be on, off or n/a')
+  if (flagRegistry !== undefined && !isText(flagRegistry)) errors.push('flagRegistry must be a repository path')
+  if (dark === 'on' && !isText(flagRegistry)) errors.push('dark on needs flagRegistry')
+  if (required !== undefined) {
+    if (!isTextList(required) || required.some((item) => !['canary', 'dark'].includes(item))) {
+      errors.push('required lists only canary and/or dark')
+    } else {
+      if (required.includes('canary') && exposure !== 'canary') errors.push('required canary needs exposure canary')
+      if (required.includes('dark') && dark !== 'on') errors.push('required dark needs dark on')
+    }
+  }
+  return errors
+}
+
+export function validateFlow(text, { predefined = false, partial = false } = {}) {
+  const sha256 = createHash('sha256').update(String(text ?? '')).digest('hex')
+  const { frontmatter, body } = splitFlow(text)
+  if (frontmatter === null) {
+    return { valid: false, errors: ['a flow starts with a --- frontmatter block of settings'], sha256, settings: null, steps: {} }
+  }
+  let settings
+  try {
+    settings = frontmatter.trim() === '' ? {} : parseYamlMapping(frontmatter, 'flow frontmatter')
+  } catch (error) {
+    return { valid: false, errors: [error.message], sha256, settings: null, steps: {} }
+  }
+  const { steps, errors: stepErrors } = parseSteps(body)
+  const errors = [...(partial ? validateSlots(settings) : validateSettings(settings, { predefined })), ...stepErrors]
+  if (settings.dark !== undefined) settings = { ...settings, dark: normalizeSwitch(settings.dark) }
+  return { valid: errors.length === 0, errors, sha256, settings, steps }
+}
+
+// A project flow that extends a predefined one is checked slot by slot on its own, then as a
+// whole once merged, because a cross-field rule (canary needs cloud-run) can span both files.
+function validateSlots(settings) {
+  const errors = validateSettings(settings, { partial: true })
+  const crossField = [/^exposure canary needs/, /only to route/, /^dark on needs/, /^required (canary|dark) needs/]
+  return errors.filter((error) => !crossField.some((pattern) => pattern.test(error)))
+}
+
+export function listPredefined(dir = PREDEFINED_DIR) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.md'))
+    .map((file) => file.slice(0, -3))
+    .sort()
+    .map((name) => {
+      const file = `${name}.md`
+      const flow = validateFlow(readFileSync(join(dir, file), 'utf8'), { predefined: true })
+      return { name, description: flow.settings?.description || '', valid: flow.valid, errors: flow.errors }
+    })
+}
+
+export function loadPredefined(name, dir = PREDEFINED_DIR) {
+  const path = join(dir, `${name}.md`)
+  if (!FLOW_NAME.test(String(name)) || !existsSync(path)) {
+    const known = listPredefined(dir).map((flow) => flow.name).join(', ')
+    return { valid: false, errors: [`no predefined flow "${name}"; available: ${known}`], text: '' }
+  }
+  const text = readFileSync(path, 'utf8')
+  return { name, text, ...validateFlow(text, { predefined: true }) }
+}
+
+const MERGED_MAPPINGS = ['publisher', 'packages', 'canary']
+
+// Project settings override the base; mapping slots merge key by key; ask items merge by id.
+// Steps append: the base flow's steps at a point run first, then the project's.
+export function mergeFlows(base, own) {
+  const settings = { ...base.settings }
+  for (const [key, value] of Object.entries(own.settings)) {
+    if (key === 'extends') continue
+    if (MERGED_MAPPINGS.includes(key) && isMapping(value) && isMapping(settings[key])) settings[key] = { ...settings[key], ...value }
+    else if (key === 'ask' && Array.isArray(value) && Array.isArray(settings.ask)) {
+      const ids = new Set(value.map((item) => item?.id))
+      settings.ask = [...settings.ask.filter((item) => !ids.has(item.id)), ...value]
+    } else settings[key] = value
+  }
+  const steps = {}
+  for (const name of STEP_SECTIONS) {
+    const merged = [...(base.steps[name] || []), ...(own.steps[name] || [])]
+    if (merged.length) steps[name] = merged
+  }
+  return { settings, steps }
+}
+
+function declaresExtends(text) {
+  const { frontmatter } = splitFlow(text)
+  if (!frontmatter) return false
+  try {
+    return parseYamlMapping(frontmatter).extends !== undefined
+  } catch {
+    return false
+  }
+}
+
+const digest = (...parts) => createHash('sha256').update(parts.join('\0')).digest('hex')
+
+// The effective flow: the project's own file (optionally extending a predefined flow), or a
+// predefined flow named at invocation when the project has none. Neither: no flow.
+export function loadFlow(file = DEFAULT_FLOW_PATH, { cwd = process.cwd(), name = null, dir = PREDEFINED_DIR } = {}) {
+  const path = resolve(cwd, file)
+  const hasProject = existsSync(path)
+  const invalid = (errors, extra = {}) => ({ present: true, valid: false, errors, settings: null, steps: {}, ...extra })
+  if (!hasProject && !name) return { present: false, path: file }
+  if (hasProject && name) {
+    return invalid([`${file} exists; the project flow wins, so name a predefined flow in its extends instead of --flow`], { path: file })
+  }
+  if (!hasProject) {
+    const base = loadPredefined(name, dir)
+    if (!base.valid) return invalid(base.errors, { path: null, base: name })
+    return { present: true, valid: true, errors: [], path: null, base: name, own: null, settings: base.settings, steps: base.steps, sha256: digest(`flow:${name}`, base.text) }
+  }
+  const text = readFileSync(path, 'utf8')
+  const own = validateFlow(text, { partial: declaresExtends(text) })
+  if (!own.valid) return invalid(own.errors, { path: file })
+  if (!own.settings.extends) {
+    return { present: true, valid: true, errors: [], path: file, base: null, own: { settings: own.settings, steps: own.steps }, settings: own.settings, steps: own.steps, sha256: own.sha256 }
+  }
+  const base = loadPredefined(own.settings.extends, dir)
+  if (!base.valid) return invalid(base.errors, { path: file, base: own.settings.extends })
+  const merged = mergeFlows(base, own)
+  const errors = validateSettings(merged.settings)
+  if (errors.length) return invalid(errors.map((error) => `${file} + ${own.settings.extends}: ${error}`), { path: file, base: own.settings.extends })
+  return {
+    present: true, valid: true, errors: [], path: file, base: own.settings.extends,
+    own: { settings: own.settings, steps: own.steps }, ...merged,
+    sha256: digest(`flow:${own.settings.extends}`, base.text, text),
+  }
+}
+
+export function canarySteps(value) {
+  const steps = typeof value === 'string' ? value.split(',').map((part) => Number(part.trim())) : value
+  if (!Array.isArray(steps) || steps.length === 0) return { error: 'must list at least one percentage' }
+  if (!steps.every((step) => Number.isInteger(step) && step > 0 && step < 100)) {
+    return { error: 'must be whole percentages between 1 and 99 (100% is the final shift)' }
+  }
+  if (steps.some((step, index) => index > 0 && step <= steps[index - 1])) return { error: 'must strictly increase' }
+  return { steps }
+}
+
+// Precedence: invocation option > release flow > preflight answer/question. Shortcut mode
+// (rush-release) asks nothing: exposure full, dark off, flow questions take their defaults.
+export function resolveChoices({ mode, flow = null, invocation = {}, answers = {}, repo = {} } = {}) {
+  if (!['full', 'shortcut'].includes(mode)) throw usage('--mode must be full or shortcut')
+  const settings = flow?.settings || {}
+  const required = settings.required || []
+  const choices = { exposure: null, dark: null, canary: null, flagRegistry: null, ask: {} }
+  const sources = {}
+  const questions = []
+  const refusals = []
+  const set = (key, value, source) => { choices[key] = value; sources[key] = source }
+
+  if (mode === 'shortcut') {
+    const passed = ['exposure', 'dark', 'canarySteps', 'holdMinutes'].filter((key) => invocation[key] !== undefined)
+    if (passed.length) refusals.push(`rush-release takes the shortcut (exposure full, dark off) and accepts no ${passed.join('/')} option; use /resolve-release`)
+    for (const item of required) refusals.push(`the release flow requires ${item}; rush-release cannot provide it, use /resolve-release`)
+    set('exposure', settings.exposure === 'n/a' ? 'n/a' : 'full', 'shortcut')
+    set('dark', settings.dark === 'n/a' ? 'n/a' : 'off', 'shortcut')
+    for (const item of settings.ask || []) {
+      if (item.default !== undefined) { choices.ask[item.id] = item.default; sources[`ask.${item.id}`] = 'flow-default' }
+      else refusals.push(`the release flow asks "${item.question}" with no default; rush-release never asks, use /resolve-release`)
+    }
+    return { mode, choices, sources, questions, refusals }
+  }
+
+  const pick = (key) => {
+    if (invocation[key] !== undefined) return [invocation[key], 'invocation']
+    if (settings[key] !== undefined) return [settings[key], 'flow']
+    if (answers[key] !== undefined) return [answers[key], 'answer']
+    return [undefined, null]
+  }
+
+  const [exposure, exposureSource] = pick('exposure')
+  if (exposure === undefined) {
+    const suggested = repo.canary || settings.canary ? 'canary' : 'full'
+    questions.push({ id: 'exposure', question: 'How should users move to the new version?', options: ['full', 'canary'], default: suggested })
+  } else if (!['full', 'canary', 'n/a'].includes(exposure)) refusals.push(`exposure must be full or canary, got ${exposure}`)
+  else if (exposure !== 'n/a' && settings.exposure === 'n/a') refusals.push('the release flow marks exposure n/a (no traffic to split)')
+  else set('exposure', exposure, exposureSource)
+
+  if (choices.exposure === 'canary') {
+    const fromFlow = settings.canary || {}
+    const stepsValue = invocation.canarySteps ?? fromFlow.steps ?? answers.canarySteps
+    const holdValue = invocation.holdMinutes ?? fromFlow.holdMinutes ?? answers.holdMinutes
+    const healthCheck = invocation.healthCheck ?? fromFlow.healthCheck
+    let steps = null
+    if (stepsValue === undefined) questions.push({ id: 'canarySteps', question: 'Which traffic percentages before 100%?', default: '10,50' })
+    else {
+      const parsed = canarySteps(stepsValue)
+      if (parsed.error) refusals.push(`canary steps ${parsed.error}`)
+      else steps = parsed.steps
+    }
+    const hold = holdValue === undefined ? undefined : Number(holdValue)
+    if (holdValue === undefined) questions.push({ id: 'holdMinutes', question: 'How many minutes to hold at each step?', default: '15' })
+    else if (!(Number.isInteger(hold) && hold > 0)) refusals.push('hold minutes must be a positive integer')
+    if (!isText(healthCheck)) refusals.push('canary needs a repository-declared health check (flow canary.healthCheck or --health-check)')
+    if (steps && Number.isInteger(hold) && hold > 0 && isText(healthCheck)) {
+      set('canary', { steps, holdMinutes: hold, healthCheck }, invocation.canarySteps !== undefined ? 'invocation' : fromFlow.steps ? 'flow' : 'answer')
+    }
+  }
+
+  const [darkRaw, darkSource] = pick('dark')
+  const dark = normalizeSwitch(darkRaw)
+  const flagRegistry = invocation.flagRegistry ?? settings.flagRegistry
+  if (dark === undefined) {
+    questions.push({ id: 'dark', question: 'Check that features shipping behind flags stay switched off?', options: ['on', 'off'], default: flagRegistry || repo.flagRegistry ? 'on' : 'off' })
+  } else if (!['on', 'off', 'n/a'].includes(dark)) refusals.push(`dark must be on or off, got ${dark}`)
+  else if (dark !== 'n/a' && settings.dark === 'n/a') refusals.push('the release flow marks dark launch n/a')
+  else {
+    set('dark', dark, darkSource)
+    if (dark === 'on') {
+      if (isText(flagRegistry)) set('flagRegistry', flagRegistry, invocation.flagRegistry ? 'invocation' : 'flow')
+      else refusals.push('dark launch needs a flag registry (flow flagRegistry or --flag-registry)')
+    }
+  }
+  for (const item of required) {
+    if (item === 'canary' && choices.exposure && choices.exposure !== 'canary') refusals.push('the release flow requires canary exposure')
+    if (item === 'dark' && choices.dark && choices.dark !== 'on') refusals.push('the release flow requires dark launch on')
+  }
+
+  for (const item of settings.ask || []) {
+    if (answers[item.id] !== undefined) {
+      if (item.options && !item.options.includes(answers[item.id])) refusals.push(`${item.id} must be one of ${item.options.join(', ')}`)
+      else { choices.ask[item.id] = answers[item.id]; sources[`ask.${item.id}`] = 'answer' }
+    } else questions.push({ id: item.id, question: item.question, ...(item.options ? { options: item.options } : {}), ...(item.default !== undefined ? { default: item.default } : {}) })
+  }
+  return { mode, choices, sources, questions, refusals }
+}
+
+// The saved flow keeps every existing slot and step and records this run's exposure and dark
+// choices. Per-release answers (ask items) are not saved: they are asked again next time.
+export function renderFlow({ choices }, existing = null) {
+  const settings = existing?.own ? { ...existing.own.settings } : {}
+  if (existing?.base) settings.extends = existing.base
+  if (choices.exposure && choices.exposure !== 'n/a') settings.exposure = choices.exposure
+  if (choices.canary) settings.canary = { ...choices.canary }
+  if (choices.dark && choices.dark !== 'n/a') settings.dark = choices.dark
+  if (choices.flagRegistry) settings.flagRegistry = choices.flagRegistry
+  const lines = ['---', dumpYamlMapping(settings).trimEnd(), '---', '', '# Release flow', '']
+  for (const name of STEP_SECTIONS) {
+    const steps = existing?.own?.steps?.[name]
+    if (!steps?.length) continue
+    lines.push(`## ${name}`, '', ...steps.map((step) => `- ${step}`), '')
+  }
+  const text = `${lines.join('\n').trimEnd()}\n`
+  const check = validateFlow(text, { partial: Boolean(settings.extends) })
+  if (!check.valid) throw new Error(`rendered flow is invalid: ${check.errors.join('; ')}`)
+  return text
+}
+
+function usage(message) {
+  const err = new Error(message)
+  err.exitCode = 2
+  return err
+}
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv
+  const opts = { command, file: DEFAULT_FLOW_PATH, json: false, invocation: {}, answers: {}, repo: {} }
+  const value = (i, name) => {
+    if (rest[i] === undefined) throw usage(`${name} needs a value`)
+    return rest[i]
+  }
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i]
+    if (arg === '--json') opts.json = true
+    else if (arg === '--file') opts.file = value(++i, arg)
+    else if (arg === '--flow') opts.flow = value(++i, arg)
+    else if (arg === '--mode') opts.mode = value(++i, arg)
+    else if (arg === '--exposure') opts.invocation.exposure = value(++i, arg)
+    else if (arg === '--canary-steps') opts.invocation.canarySteps = value(++i, arg)
+    else if (arg === '--hold-minutes') opts.invocation.holdMinutes = value(++i, arg)
+    else if (arg === '--health-check') opts.invocation.healthCheck = value(++i, arg)
+    else if (arg === '--dark') opts.invocation.dark = value(++i, arg)
+    else if (arg === '--flag-registry') opts.invocation.flagRegistry = value(++i, arg)
+    else if (arg === '--repo-canary') opts.repo.canary = true
+    else if (arg === '--repo-flag-registry') opts.repo.flagRegistry = true
+    else if (arg === '--answer') {
+      const pair = value(++i, arg)
+      const eq = pair.indexOf('=')
+      if (eq < 1) throw usage('--answer takes <id>=<value>')
+      opts.answers[pair.slice(0, eq)] = pair.slice(eq + 1)
+    } else throw usage(`unknown argument: ${arg}`)
+  }
+  if (!['list', 'validate', 'resolve', 'render'].includes(command)) throw usage('usage: flow.mjs list|validate|resolve|render [options]')
+  if (command === 'resolve' && !opts.mode) throw usage('resolve needs --mode full|shortcut')
+  return opts
+}
+
+function write(opts, value, text) {
+  process.stdout.write(opts.json ? `${JSON.stringify(value, null, 2)}\n` : `${text}\n`)
+}
+
+export function main(argv = process.argv.slice(2), { cwd = process.cwd(), stdin = () => readFileSync(0, 'utf8') } = {}) {
+  const opts = parseArgs(argv)
+  if (opts.command === 'list') {
+    const flows = listPredefined()
+    write(opts, flows, flows.map((flow) => `${flow.name}: ${flow.description}`).join('\n'))
+    return flows.every((flow) => flow.valid) ? 0 : 1
+  }
+  const flow = loadFlow(opts.file, { cwd, name: opts.flow || null })
+  if (flow.present && !flow.valid) {
+    write(opts, flow, `invalid flow ${flow.path || flow.base}:\n- ${flow.errors.join('\n- ')}`)
+    return 1
+  }
+  if (opts.command === 'validate') {
+    const label = [flow.path, flow.base && `extends ${flow.base}`].filter(Boolean).join(' ')
+    write(opts, flow, flow.present ? `${label || flow.base} valid (sha256 ${flow.sha256})` : `no project flow at ${flow.path}`)
+    return 0
+  }
+  if (opts.command === 'render') {
+    process.stdout.write(renderFlow(JSON.parse(stdin()), flow.present ? flow : null))
+    return 0
+  }
+  const result = {
+    flow: flow.present ? { path: flow.path, base: flow.base, sha256: flow.sha256, steps: flow.steps, settings: flow.settings } : null,
+    ...resolveChoices({ mode: opts.mode, flow: flow.present ? flow : null, invocation: opts.invocation, answers: opts.answers, repo: opts.repo }),
+  }
+  const summary = result.refusals.length
+    ? `refused:\n- ${result.refusals.join('\n- ')}`
+    : result.questions.length
+      ? `ask:\n${result.questions.map((q) => `- ${q.id}: ${q.question}${q.options ? ` [${q.options.join('|')}]` : ''}${q.default !== undefined ? ` (default ${q.default})` : ''}`).join('\n')}`
+      : `resolved: exposure ${result.choices.exposure}, dark ${result.choices.dark}`
+  write(opts, result, summary)
+  if (result.refusals.length) return 3
+  return result.questions.length ? 4 : 0
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    process.exitCode = main()
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`)
+    process.exitCode = error.exitCode || 1
+  }
+}