mandrel 1.57.0

package/.agents/scripts/lib/cli/standard-args.js

@@ -0,0 +1,351 @@
+/**
+ * standard-args.js — shared CLI flag parser for the dispatcher's
+ * top-level scripts (Story #2460, Epic #2453 — CLI thinning pilot).
+ *
+ * Replaces the per-CLI hand-rolled flag dispatch with a single
+ * declarative entrypoint that the refactored scripts (story-close,
+ * epic-deliver, check-baselines, audit-suite/cli) all call. The helper
+ * covers the flags every dispatcher CLI shares (`--epic`, `--story`,
+ * `--changed-since`, `--json`, `--full-scope`, `--dry-run`)
+ * and — via the `extras` schema entry — caller-defined extras (e.g.
+ * `--root`, `--scope`, `--check`) so a script can replace its local
+ * argv walker with a single declarative call.
+ *
+ * Contract
+ * --------
+ *   parseStandardCliArgs(argv, schema?) → { values, positionals }
+ *   parseStandardCliArgs({ argv, schema?, extras? }) → { values, positionals }
+ *
+ *   - `argv`    — `process.argv.slice(2)` shape; the helper does NOT strip
+ *     the leading `node` + script-path entries on the caller's behalf.
+ *   - `schema`  — optional, declarative override of which standard flags
+ *     are required. Shape: `{ [flagName]: { required?: boolean } }`.
+ *     Unknown keys are rejected so a typo doesn't silently disable the
+ *     required-field check.
+ *   - `extras`  — optional, declarative map of caller-defined flags.
+ *     Shape: `{ [flagName]: { type, alias?, default?, required? } }`.
+ *     `type` is one of `'string' | 'boolean' | 'ticket' | 'integer' |
+ *     'string-multi'`. `alias` defaults to the camelCased flag name.
+ *     Extras flow through the same `defineFlags` machinery as the
+ *     standard set and are emitted on `values` under their `alias`.
+ *
+ *   `values` is always returned with every known flag present:
+ *
+ *     { epicId, storyId, changedSince, json, fullScope, dryRun,
+ *       ...extras }
+ *
+ *   Ticket-shaped flags (`--epic`, `--story`) parse via
+ *   `parseTicketId` (positive integer; leading `#` stripped; `null` on
+ *   anything invalid). The string-shaped `--changed-since` keeps the raw
+ *   string (or `null` when absent). Boolean flags coerce to `false` when
+ *   absent and `true` when present (with or without a value).
+ *
+ * Failure modes
+ * -------------
+ *   - **Unknown flag**: an argv token shaped like `--foo` whose name is
+ *     not in the supported set (standard + extras) throws an `Error`
+ *     with a stable `code: 'UNKNOWN_FLAG'` plus the offending flag name.
+ *   - **Missing required flag**: when `schema[flag].required === true`
+ *     (or `extras[flag].required === true`) and the resolved value is
+ *     absent (ticket flags → `null`; string flags → `null`/empty;
+ *     boolean flags → `false`), the parser throws with
+ *     `code: 'MISSING_REQUIRED_FLAG'` and the flag name.
+ *   - **Unsupported extras type**: a typo in `extras[flag].type` throws
+ *     with `code: 'UNKNOWN_EXTRAS_TYPE'`.
+ *
+ * Why a thin shim and not a re-export of `defineFlags`
+ * ----------------------------------------------------
+ *   `defineFlags` is a powerful declarative parser, but every dispatcher
+ *   CLI hand-rolls its own option spec — duplicated `--epic` / `--story`
+ *   blocks across four scripts, each subtly different. `parseStandardCliArgs`
+ *   collapses that duplication into one canonical spec with a small
+ *   `extras` surface for the per-script flags.
+ *
+ * @module lib/cli/standard-args
+ */
+
+import { defineFlags, parseTicketId } from '../cli-args.js';
+
+/**
+ * Canonical spec passed to `defineFlags`. Every key in `SUPPORTED_FLAGS`
+ * is what the parser will accept; anything else triggers `UNKNOWN_FLAG`
+ * unless it is declared via `extras`.
+ *
+ * Each entry below maps the kebab-cased CLI flag to:
+ *   - `key`:  the camelCased output key on `values`
+ *   - `type`: 'ticket' | 'string' | 'boolean'
+ */
+const SUPPORTED_FLAGS = Object.freeze({
+  epic: { key: 'epicId', type: 'ticket' },
+  story: { key: 'storyId', type: 'ticket' },
+  'changed-since': { key: 'changedSince', type: 'string' },
+  json: { key: 'json', type: 'boolean' },
+  'full-scope': { key: 'fullScope', type: 'boolean' },
+  'dry-run': { key: 'dryRun', type: 'boolean' },
+});
+
+const FLAG_NAMES = Object.keys(SUPPORTED_FLAGS);
+
+const SUPPORTED_EXTRAS_TYPES = new Set([
+  'string',
+  'boolean',
+  'ticket',
+  'integer',
+  'string-multi',
+]);
+
+function camelCase(name) {
+  return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+}
+
+/**
+ * Normalize the call signature. Accepts either positional
+ * `(argv, schema)` (backward compat) or the object form
+ * `({ argv, schema, extras })`.
+ *
+ * @param {unknown} argvOrOpts
+ * @param {unknown} maybeSchema
+ * @returns {{ argv: string[], schema: object | undefined, extras: object | undefined }}
+ */
+function normaliseCallSignature(argvOrOpts, maybeSchema) {
+  if (
+    argvOrOpts !== null &&
+    typeof argvOrOpts === 'object' &&
+    !Array.isArray(argvOrOpts)
+  ) {
+    const { argv, schema, extras } = argvOrOpts;
+    return { argv: argv ?? [], schema, extras };
+  }
+  return { argv: argvOrOpts ?? [], schema: maybeSchema, extras: undefined };
+}
+
+/**
+ * Build the `defineFlags` spec from the canonical flag table plus any
+ * caller-supplied extras. Extras are merged after the standard set; a
+ * collision (e.g. extras declaring `--story`) is rejected up-front in
+ * `validateExtras`.
+ */
+function buildDefineFlagsSpec(extras) {
+  const spec = {};
+  for (const [flag, { key, type }] of Object.entries(SUPPORTED_FLAGS)) {
+    spec[flag] = { type, alias: key };
+  }
+  if (!extras) return spec;
+  for (const [flag, def] of Object.entries(extras)) {
+    const entry = { type: def.type, alias: def.alias ?? camelCase(flag) };
+    if ('default' in def) entry.default = def.default;
+    spec[flag] = entry;
+  }
+  return spec;
+}
+
+/**
+ * Collect every flag name the parser recognises (standard + extras).
+ * Used by the unknown-flag walker.
+ */
+function knownFlagNames(extras) {
+  if (!extras) return FLAG_NAMES;
+  return FLAG_NAMES.concat(Object.keys(extras));
+}
+
+/**
+ * Scan the raw argv for `--foo` tokens whose name is not in the known
+ * set. Returns the first offender or `null`.
+ */
+function findUnknownFlag(argv, known) {
+  for (const tok of argv) {
+    if (typeof tok !== 'string') continue;
+    if (tok === '--') break;
+    if (!tok.startsWith('--')) continue;
+    const eq = tok.indexOf('=');
+    const name = eq >= 0 ? tok.slice(2, eq) : tok.slice(2);
+    if (name.length === 0) continue;
+    if (!known.includes(name)) return name;
+  }
+  return null;
+}
+
+/**
+ * Validate the caller-supplied `schema`. Reject any key that is not a
+ * supported standard flag.
+ */
+function validateSchema(schema) {
+  if (schema === undefined || schema === null) return;
+  if (typeof schema !== 'object') {
+    throw new Error('parseStandardCliArgs: schema must be an object');
+  }
+  for (const flag of Object.keys(schema)) {
+    if (!Object.hasOwn(SUPPORTED_FLAGS, flag)) {
+      const err = new Error(
+        `parseStandardCliArgs: schema references unsupported flag "${flag}". ` +
+          `Supported: ${FLAG_NAMES.join(', ')}.`,
+      );
+      err.code = 'UNKNOWN_FLAG_IN_SCHEMA';
+      throw err;
+    }
+  }
+}
+
+/**
+ * Validate the caller-supplied `extras`. Each entry must declare a
+ * supported type; declaring a flag name that collides with a standard
+ * flag is rejected (use the `schema` for required-marking instead).
+ */
+function validateExtras(extras) {
+  if (extras === undefined || extras === null) return;
+  if (typeof extras !== 'object') {
+    throw new Error('parseStandardCliArgs: extras must be an object');
+  }
+  for (const [flag, def] of Object.entries(extras)) {
+    if (Object.hasOwn(SUPPORTED_FLAGS, flag)) {
+      const err = new Error(
+        `parseStandardCliArgs: extras "${flag}" collides with a standard flag; ` +
+          `use the schema entry to mark it required instead.`,
+      );
+      err.code = 'EXTRAS_FLAG_COLLISION';
+      throw err;
+    }
+    if (!def || typeof def !== 'object') {
+      throw new Error(
+        `parseStandardCliArgs: extras["${flag}"] must be an object`,
+      );
+    }
+    if (!SUPPORTED_EXTRAS_TYPES.has(def.type)) {
+      const err = new Error(
+        `parseStandardCliArgs: extras["${flag}"].type "${def.type}" is unsupported. ` +
+          `Supported: ${[...SUPPORTED_EXTRAS_TYPES].join(', ')}.`,
+      );
+      err.code = 'UNKNOWN_EXTRAS_TYPE';
+      throw err;
+    }
+  }
+}
+
+/**
+ * "Absent" test parameterised by flag type. Mirrored across the
+ * standard and extras enforcement passes.
+ */
+function isAbsent(type, cur) {
+  if (type === 'ticket') return cur === null || cur === undefined;
+  if (type === 'string') return cur === null || cur === undefined || cur === '';
+  if (type === 'boolean') return !cur;
+  if (type === 'integer') return cur === undefined || Number.isNaN(cur);
+  if (type === 'string-multi') return !Array.isArray(cur) || cur.length === 0;
+  return cur === undefined || cur === null;
+}
+
+function throwMissing(flag) {
+  const err = new Error(
+    `parseStandardCliArgs: missing required flag --${flag}`,
+  );
+  err.code = 'MISSING_REQUIRED_FLAG';
+  err.flag = flag;
+  throw err;
+}
+
+/**
+ * Apply the per-flag `required` constraints from `schema` against the
+ * resolved `values`.
+ */
+function enforceRequired(values, schema) {
+  if (!schema) return;
+  for (const [flag, rule] of Object.entries(schema)) {
+    if (!rule || rule.required !== true) continue;
+    const meta = SUPPORTED_FLAGS[flag];
+    if (isAbsent(meta.type, values[meta.key])) throwMissing(flag);
+  }
+}
+
+/**
+ * Apply the per-flag `required` constraints declared on `extras`.
+ */
+function enforceExtrasRequired(values, extras) {
+  if (!extras) return;
+  for (const [flag, def] of Object.entries(extras)) {
+    if (!def || def.required !== true) continue;
+    const key = def.alias ?? camelCase(flag);
+    if (isAbsent(def.type, values[key])) throwMissing(flag);
+  }
+}
+
+/**
+ * Coerce the raw `defineFlags` output into the canonical shape the
+ * dispatcher CLIs consume. `defineFlags` already applies the alias
+ * (`epic` → `epicId`, …) and runs `parseTicketId` for the ticket-typed
+ * entries; we normalise absent strings / booleans into a stable
+ * JSON-friendly shape for the standard set and pass extras through
+ * with light coercion (string → null on empty, boolean → strict false).
+ */
+function normaliseValues(raw, extras) {
+  const out = {};
+  for (const [, { key, type }] of Object.entries(SUPPORTED_FLAGS)) {
+    let v = raw[key];
+    if (type === 'ticket') {
+      v = parseTicketId(v);
+    } else if (type === 'string') {
+      v = typeof v === 'string' && v.length > 0 ? v : null;
+    } else if (type === 'boolean') {
+      v = v === true;
+    }
+    out[key] = v;
+  }
+  if (!extras) return out;
+  for (const [flag, def] of Object.entries(extras)) {
+    const key = def.alias ?? camelCase(flag);
+    let v = raw[key];
+    if (def.type === 'boolean') {
+      v = v === true;
+    } else if (def.type === 'string') {
+      if (v === undefined) v = 'default' in def ? def.default : null;
+    } else if (def.type === 'ticket') {
+      v = parseTicketId(v);
+    } else if (def.type === 'string-multi') {
+      if (!Array.isArray(v)) v = 'default' in def ? def.default : [];
+    } else if (def.type === 'integer') {
+      if (v === undefined && 'default' in def) v = def.default;
+    }
+    out[key] = v;
+  }
+  return out;
+}
+
+/**
+ * Parse the dispatcher's shared CLI flag surface. See module docstring
+ * for the full contract.
+ *
+ * @param {string[]|{argv?: string[], schema?: object, extras?: object}} argvOrOpts
+ * @param {Record<string, { required?: boolean }>} [maybeSchema]
+ * @returns {{ values: Record<string, unknown>, positionals: string[] }}
+ */
+export function parseStandardCliArgs(argvOrOpts = [], maybeSchema) {
+  const { argv, schema, extras } = normaliseCallSignature(
+    argvOrOpts,
+    maybeSchema,
+  );
+  if (!Array.isArray(argv)) {
+    throw new Error('parseStandardCliArgs: argv must be an array');
+  }
+  validateExtras(extras);
+  validateSchema(schema);
+  const known = knownFlagNames(extras);
+  const unknown = findUnknownFlag(argv, known);
+  if (unknown !== null) {
+    const err = new Error(
+      `parseStandardCliArgs: unknown flag --${unknown}. ` +
+        `Supported: ${known.map((n) => `--${n}`).join(', ')}.`,
+    );
+    err.code = 'UNKNOWN_FLAG';
+    err.flag = unknown;
+    throw err;
+  }
+  const { values: raw, positionals } = defineFlags(
+    buildDefineFlagsSpec(extras),
+    argv,
+  );
+  const values = normaliseValues(raw, extras);
+  enforceRequired(values, schema);
+  enforceExtrasRequired(values, extras);
+  return { values, positionals };
+}
+
+export { FLAG_NAMES, SUPPORTED_FLAGS };

package/.agents/scripts/lib/cli-args.js

@@ -0,0 +1,286 @@
+import { parseArgs } from 'node:util';
+
+/**
+ * Parse a single ticket-ID-style value. Strips an optional leading `#`,
+ * coerces to a positive integer, and returns `null` for anything invalid.
+ *
+ * Shared by every CLI that accepts `--epic`, `--story`, `--task`, `--recut-of`,
+ * or a ticket positional, so the `Number.parseInt(..., 10)` + `# ` prefix dance lives
+ * in exactly one place.
+ *
+ * @param {string|number|null|undefined} value
+ * @returns {number|null}
+ */
+export function parseTicketId(value) {
+  if (value === null || value === undefined) return null;
+  const raw = typeof value === 'number' ? String(value) : value.toString();
+  const cleaned = raw.replace(/^#/, '').trim();
+  if (cleaned === '') return null;
+  const n = Number.parseInt(cleaned, 10);
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+/**
+ * Coerce a value returned by `node:util`'s `parseArgs` for a boolean flag into
+ * a real boolean. Under `strict: false`, `--flag=true` / `--flag=false` arrive
+ * here as the literal strings `'true'` / `'false'`, while bare `--flag` lands
+ * as `true`. Absence yields `undefined`, which collapses to `false`.
+ *
+ * @param {boolean|string|null|undefined} value
+ * @returns {boolean}
+ */
+function coerceBooleanFlag(value) {
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    const lowered = value.trim().toLowerCase();
+    if (lowered === 'false' || lowered === '0' || lowered === '') return false;
+    return true;
+  }
+  return Boolean(value);
+}
+
+/**
+ * Standardized CLI argument parser for sprint scripts.
+ * Supports options like --epic, --story, --dry-run, --skip-dashboard.
+ * @param {string[]} args Array of arguments (defaults to process.argv)
+ * @returns {object} Parsed and typed argument values
+ */
+export function parseSprintArgs(args = process.argv) {
+  const { values, positionals } = parseArgs({
+    args: args.slice(2),
+    options: {
+      epic: { type: 'string', short: 'e' },
+      story: { type: 'string', short: 's' },
+      'dry-run': { type: 'boolean', default: false },
+      'skip-dashboard': { type: 'boolean', default: false },
+      'skip-validation': { type: 'boolean', default: false },
+      'skip-sync': { type: 'boolean', default: false },
+      'no-auto-merge': { type: 'boolean', default: false },
+      'no-full-scope-crap': { type: 'boolean', default: false },
+      executor: { type: 'string' },
+      cwd: { type: 'string' },
+      'recut-of': { type: 'string' },
+      resume: { type: 'boolean', default: false },
+      restart: { type: 'boolean', default: false },
+      'no-evidence': { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  const parsed = {
+    epicId: parseTicketId(values.epic),
+    storyId: parseTicketId(values.story),
+    ticketId: null,
+    dryRun: values['dry-run'] ?? false,
+    skipDashboard: values['skip-dashboard'] ?? false,
+    skipValidation: coerceBooleanFlag(values['skip-validation']),
+    skipSync: coerceBooleanFlag(values['skip-sync']),
+    noAutoMerge: coerceBooleanFlag(values['no-auto-merge']),
+    noFullScopeCrap: coerceBooleanFlag(values['no-full-scope-crap']),
+    executor: values.executor ?? null,
+    // Resolve worktree cwd from flag or env. Empty string/whitespace → null.
+    cwd:
+      (typeof values.cwd === 'string' && values.cwd.trim()) ||
+      process.env.AGENT_WORKTREE_ROOT ||
+      null,
+    recutOf: parseTicketId(values['recut-of']),
+    resume: values.resume ?? false,
+    restart: values.restart ?? false,
+    noEvidence: values['no-evidence'] ?? false,
+  };
+
+  parsed.ticketId =
+    parseTicketId(positionals[0]) ?? parsed.storyId ?? parsed.epicId ?? null;
+
+  return parsed;
+}
+
+const SUPPORTED_FLAG_TYPES = new Set([
+  'boolean',
+  'ticket',
+  'integer',
+  'string',
+  'string-multi',
+]);
+
+function camelCase(name) {
+  return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+}
+
+function initialValueFor(type) {
+  if (type === 'boolean') return false;
+  if (type === 'string-multi') return [];
+  if (type === 'ticket') return null;
+  return undefined;
+}
+
+function coerceValue(type, raw) {
+  if (type === 'string') return raw;
+  if (type === 'ticket') return parseTicketId(raw);
+  if (type === 'integer') return Number(raw);
+  return raw;
+}
+
+/**
+ * Declarative argv parser used by every top-level script under
+ * `.agents/scripts/`. Replaces the hand-rolled `parseCliArgs` walkers that
+ * the `tests/enforcement/parse-cli-args.test.js` enforcement gate forbids.
+ *
+ * Spec entry shape:
+ *   { type, alias?, default?, envKey?, optionalValue?, short? }
+ *
+ *   - `type`: 'boolean' | 'ticket' | 'integer' | 'string' | 'string-multi'.
+ *     'ticket' coerces via `parseTicketId` (positive int, leading `#` stripped,
+ *     `null` for invalid). 'integer' coerces via `Number()` (NaN on garbage).
+ *   - `alias`: output key on `values`. Defaults to camel-cased flag name.
+ *   - `default`: applied when no value was provided AND no envKey produced
+ *     one. For 'ticket' the default fires when the parsed value is null.
+ *   - `envKey`: env-var fallback, used only when the flag is absent and the
+ *     env value is a non-empty string.
+ *   - `optionalValue`: value to assign when the flag is present without a
+ *     value (i.e. EOF or the next token is another `--flag`).
+ *   - `short`: single-char short flag (e.g. `-h`).
+ *
+ * @param {Record<string, object>} spec
+ * @param {string[]} args  argv slice (no `process` / script entries)
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ values: Record<string, any>, positionals: string[] }}
+ */
+function validateSpec(spec) {
+  for (const [name, def] of Object.entries(spec)) {
+    if (!SUPPORTED_FLAG_TYPES.has(def.type)) {
+      throw new Error(
+        `defineFlags: unsupported type "${def.type}" for flag "${name}"`,
+      );
+    }
+  }
+}
+
+function initParserState(spec) {
+  const values = {};
+  const keyOf = {};
+  const shortMap = {};
+  for (const [name, def] of Object.entries(spec)) {
+    const key = def.alias ?? camelCase(name);
+    keyOf[name] = key;
+    values[key] = initialValueFor(def.type);
+    if (def.short) shortMap[def.short] = name;
+  }
+  return { values, keyOf, shortMap };
+}
+
+function classifyToken(tok, shortMap) {
+  if (tok.startsWith('--')) {
+    const eq = tok.indexOf('=');
+    if (eq >= 0)
+      return { flagName: tok.slice(2, eq), inlineValue: tok.slice(eq + 1) };
+    return { flagName: tok.slice(2), inlineValue: null };
+  }
+  if (tok.startsWith('-') && tok.length > 1) {
+    const candidate = shortMap[tok.slice(1)];
+    if (candidate) return { flagName: candidate, inlineValue: null };
+  }
+  return { flagName: null, inlineValue: null };
+}
+
+function assignFlagValue(values, key, def, raw) {
+  if (def.type === 'string-multi') {
+    values[key] = [...(values[key] ?? []), raw];
+  } else {
+    values[key] = coerceValue(def.type, raw);
+  }
+}
+
+function readValuedFlag(args, i, inlineValue, def, values, key) {
+  if (inlineValue !== null) {
+    assignFlagValue(values, key, def, inlineValue);
+    return i + 1;
+  }
+  const next = args[i + 1];
+  const missing =
+    next === undefined || (typeof next === 'string' && next.startsWith('--'));
+  if (missing) {
+    if (def.optionalValue !== undefined) values[key] = def.optionalValue;
+    return i + 1;
+  }
+  assignFlagValue(values, key, def, next);
+  return i + 2;
+}
+
+function parseTokens(args, spec, state) {
+  const { values, keyOf, shortMap } = state;
+  const positionals = [];
+  let i = 0;
+  while (i < args.length) {
+    const tok = args[i];
+    if (typeof tok !== 'string') {
+      i += 1;
+      continue;
+    }
+    if (tok === '--') {
+      for (let j = i + 1; j < args.length; j += 1) positionals.push(args[j]);
+      break;
+    }
+    const { flagName, inlineValue } = classifyToken(tok, shortMap);
+    if (!flagName) {
+      positionals.push(tok);
+      i += 1;
+      continue;
+    }
+    const def = spec[flagName];
+    if (!def) {
+      i += 1;
+      continue;
+    }
+    const key = keyOf[flagName];
+    if (def.type === 'boolean') {
+      values[key] = true;
+      i += 1;
+      continue;
+    }
+    i = readValuedFlag(args, i, inlineValue, def, values, key);
+  }
+  return positionals;
+}
+
+function isAbsentValue(def, cur) {
+  if (def.type === 'ticket') return cur === null;
+  if (def.type === 'string-multi') return cur.length === 0;
+  return cur === undefined;
+}
+
+function applyEnvFallbacks(spec, state, env) {
+  const { values, keyOf } = state;
+  for (const [name, def] of Object.entries(spec)) {
+    if (!def.envKey) continue;
+    const envRaw = env?.[def.envKey];
+    if (typeof envRaw !== 'string' || envRaw.length === 0) continue;
+    const key = keyOf[name];
+    if (!isAbsentValue(def, values[key])) continue;
+    if (def.type === 'string-multi') values[key] = [envRaw];
+    else values[key] = coerceValue(def.type, envRaw);
+  }
+}
+
+function applyDefaults(spec, state) {
+  const { values, keyOf } = state;
+  for (const [name, def] of Object.entries(spec)) {
+    if (!('default' in def)) continue;
+    const key = keyOf[name];
+    const cur = values[key];
+    const absent = def.type === 'ticket' ? cur === null : cur === undefined;
+    if (absent) values[key] = def.default;
+  }
+}
+
+export function defineFlags(spec, args = [], opts = {}) {
+  validateSpec(spec);
+  const env = opts.env ?? process.env;
+  const state = initParserState(spec);
+  const positionals = parseTokens(args, spec, state);
+  applyEnvFallbacks(spec, state, env);
+  applyDefaults(spec, state);
+  return { values: state.values, positionals };
+}

package/.agents/scripts/lib/cli-utils.js

@@ -0,0 +1,69 @@
+/**
+ * CLI bootstrap helpers shared by every entry-point script under .agents/scripts.
+ *
+ * Before this module, 15 entry points each reimplemented the same main-guard
+ * and error-handling boilerplate:
+ *
+ *   if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+ *     main().catch((err) => { ... Logger.fatal / console.error ... });
+ *   }
+ *
+ * `runAsCli` centralises that pattern. Callers pass `import.meta.url`, a main
+ * function, and an options bag for customising the error prefix, exit code,
+ * or a fully-custom onError handler for scripts with non-standard failure
+ * behaviour.
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { formatCliError } from './error-redactor.js';
+
+/**
+ * Is the current module being executed directly as a CLI (as opposed to
+ * imported by another module)?
+ *
+ * @param {string} importMetaUrl The caller's `import.meta.url`.
+ * @returns {boolean}
+ */
+export function isDirectInvocation(importMetaUrl) {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  return fileURLToPath(importMetaUrl) === path.resolve(entry);
+}
+
+/**
+ * Run `main` as the CLI entry point for the caller's module. No-op when the
+ * module is imported rather than invoked directly. Promise rejection from
+ * `main` is funnelled through either the caller-supplied `onError` callback
+ * or the default handler (prefixed stderr line + `process.exit(exitCode)`).
+ *
+ * @param {string} importMetaUrl        Caller's `import.meta.url`.
+ * @param {() => Promise<unknown>} main The CLI's main function.
+ * @param {object} [options]
+ * @param {string} [options.source='CLI']           Prefix used in the default error message.
+ * @param {number} [options.exitCode=1]             Exit code used by the default error handler.
+ * @param {(err: Error) => void} [options.onError]  Full override of the error handler.
+ */
+export function runAsCli(importMetaUrl, main, options = {}) {
+  if (!isDirectInvocation(importMetaUrl)) return;
+  const {
+    source = 'CLI',
+    exitCode = 1,
+    onError,
+    propagateExitCode = false,
+    errorPrefix,
+  } = options;
+  const promise = main();
+  if (propagateExitCode) {
+    promise.then((code) => process.exit(code ?? 0));
+  }
+  promise.catch((err) => {
+    if (typeof onError === 'function') {
+      onError(err);
+      return;
+    }
+    const prefix = errorPrefix ?? `[${source}] Fatal error`;
+    console.error(`${prefix}: ${formatCliError(err)}`);
+    process.exit(exitCode);
+  });
+}