mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/child-exec.js

@@ -1,37 +1,10 @@
 /**
- * child-exec.js — the one child-process execution surface (Story #5009).
- *
- * Every synchronous and asynchronous child this framework spawns runs through
- * this module. It owns exactly three policies, and nothing else:
- *
- *   1. **The stdout ceiling.** `MAX_BUFFER_BYTES` is defined here and nowhere
- *      else. Node's child-process runners default `maxBuffer` to 1 MB and
- *      *kill* the child on overflow — `status: null`, `signal: 'SIGTERM'`,
- *      `error.code: 'ENOBUFS'` — so the call fails for a reason that has
- *      nothing to do with the command. That failure class has shipped
- *      operator-visible breakage more than once (Story #4914's committed
- *      baseline read at 1,178,910 bytes; Story #4948's `git push` relaying a
- *      2,166,643-byte `pre-push` envelope, which reddened `phase: push` on
- *      every Story close while the gates themselves were green). Both were
- *      fixed one call site at a time. This module is why there is no third.
- *   2. **Shell-free argv.** `shell: false` on every invocation, so no argument
- *      is ever shell-interpolated (`rules/security-baseline.md` § Output &
- *      Rendering). Callers pass argv tokens; they cannot pass a command line.
- *   3. **Result and error normalisation.** {@link spawnCapture} collapses the
- *      `spawnSync` return into `{ status, stdout, stderr }` with a non-null
- *      status and trimmed streams; {@link formatChildFailure} renders the one
- *      failure-message shape so a thrown child error reads the same wherever
- *      it came from.
- *
- * Every wrapper takes an optional `run` — the injected child-process runner —
- * so a module keeps its own test seam (`git-base.js`'s `__setSpawnRunner`,
- * `git-utils.js`'s `__setGitRunners`, the `run` / `spawn` parameters threaded
- * through the audit-baselines engine) while still delegating buffer, shell and
- * error policy here. Omit it and the real Node runner is used.
- *
- * **Do not re-import `node:child_process` in new modules.**
- * `tests/enforcement/child-process-imports.test.js` captures the current set
- * of direct importers and fails on any addition outside that allowlist.
+ * The one child-process execution surface. It owns three policies: the
+ * stdout ceiling (Node's 1 MB default kills the child with ENOBUFS for a
+ * reason unrelated to the command), shell-free argv, and result/error
+ * normalisation. Each wrapper takes an optional injected `run` so callers
+ * keep their own test seams. New modules must not import
+ * `node:child_process` directly (an enforcement test allowlists importers).
  *
  * @module lib/child-exec
  */
@@ -39,55 +12,31 @@
 import { execFile, execFileSync, spawnSync } from 'node:child_process';
 import { promisify } from 'node:util';
 
-/** One mebibyte, so the ceilings below read as the units they are quoted in. */
 const MIB = 1024 * 1024;
 
 /**
- * The stdout ceiling every child in this framework runs under — the single
- * definition of the constant.
- *
- * Deliberately **not** exported. Every wrapper below applies it as its
- * default, so a call site gets the ceiling by importing the wrapper rather
- * than by importing (and possibly forgetting) a number. The only bound a
- * caller ever names explicitly is one that is deliberately *different* —
- * today that is {@link INTERCEPTOR_MAX_BUFFER_BYTES} and nothing else.
- *
- * 64 MiB is not a fresh guess: it is the bound Stories #4914 and #4948 already
- * settled on independently for the git read and git push paths, and the value
- * `run-test-profile.js`, `audit-baselines/trend.js` and
- * `audit-baselines/weights.js` had hand-copied. `maxBuffer` caps a buffer, it
- * does not reserve one, so a generous ceiling costs nothing on the calls that
- * print two lines.
+ * Not exported: callers get it by using a wrapper, never by remembering a
+ * number. `maxBuffer` caps rather than reserves, so generous is free.
  *
  * @type {number}
  */
 const MAX_BUFFER_BYTES = 64 * MIB;
 
 /**
- * The deliberately *lower* ceiling the friction interceptor spawns arbitrary
- * operator commands under (`diagnose-friction.js`).
- *
- * This one is a reported policy bound, not an overflow guard: when it fires,
- * the interceptor records `executionMaxBuffer` on the friction row and tells
- * the operator to quieten the command rather than split it (Story #4915).
- * Raising it to {@link MAX_BUFFER_BYTES} would change that emitted row, so it
- * stays where it was — but it is defined here, alongside the ceiling it is
- * deliberately different from, rather than hand-copied into the interceptor.
+ * Deliberately lower bound for `diagnose-friction.js`: a reported policy
+ * limit (it records `executionMaxBuffer` on the friction row), not an
+ * overflow guard.
  *
  * @type {number}
  */
 export const INTERCEPTOR_MAX_BUFFER_BYTES = 10 * MIB;
 
 /**
- * Merge caller options over this module's fixed policy.
- *
- * `maxBuffer` is applied **last** so a caller's spread cannot silently drop it
- * back to Node's 1 MB default — the only way to change the ceiling is to pass
- * `maxBuffer` explicitly, which the two named constants above exist for.
+ * `maxBuffer` goes last so a caller's spread cannot reset it to 1 MB.
  *
- * @param {{ encoding: string }} defaults - Runner-specific defaults.
- * @param {object} rest      - Caller options (`cwd`, `env`, `stdio`, …).
- * @param {number} maxBuffer - Resolved stdout ceiling.
+ * @param {{ encoding: string }} defaults
+ * @param {object} rest
+ * @param {number} maxBuffer
  * @returns {object}
  */
 function childOptions(defaults, rest, maxBuffer) {
@@ -95,16 +44,13 @@ function childOptions(defaults, rest, maxBuffer) {
 }
 
 /**
- * Run a child synchronously via `execFileSync`, returning whatever the runner
- * returns (a UTF-8 string under the default encoding). **Throws** on a
- * non-zero exit, exactly like `execFileSync` — callers that treat failure as a
- * recoverable state want {@link spawnCapture} instead.
+ * Throws on non-zero exit, like `execFileSync`.
  *
- * @param {string}   file   - Executable name (never a shell command line).
- * @param {string[]} args   - Argv tokens.
- * @param {object}   [opts] - `cwd` / `env` / `stdio` / `encoding`, plus:
- * @param {Function} [opts.run]       - Injected runner; defaults to `execFileSync`.
- * @param {number}   [opts.maxBuffer] - Override the ceiling; defaults to {@link MAX_BUFFER_BYTES}.
+ * @param {string}   file
+ * @param {string[]} args
+ * @param {object}   [opts]
+ * @param {Function} [opts.run]
+ * @param {number}   [opts.maxBuffer]
  * @returns {string}
  */
 export function execFileCapture(file, args, opts = {}) {
@@ -112,17 +58,14 @@ export function execFileCapture(file, args, opts = {}) {
   return run(file, args, childOptions({ encoding: 'utf8' }, rest, maxBuffer));
 }
 
-/** Promisified `execFile` — the default runner for {@link execFileCaptureAsync}. */
 const execFileAsync = promisify(execFile);
 
 /**
- * The asynchronous sibling of {@link execFileCapture}. Resolves to
- * `{ stdout, stderr }` and rejects on a non-zero exit.
+ * Rejects on non-zero exit.
  *
- * @param {string}   file   - Executable name.
- * @param {string[]} args   - Argv tokens.
- * @param {object}   [opts] - As {@link execFileCapture}; `run` defaults to a
- *   promisified `execFile`.
+ * @param {string}   file
+ * @param {string[]} args
+ * @param {object}   [opts]
  * @returns {Promise<{ stdout: string, stderr: string }>}
  */
 export function execFileCaptureAsync(file, args, opts = {}) {
@@ -131,18 +74,12 @@ export function execFileCaptureAsync(file, args, opts = {}) {
 }
 
 /**
- * Run a child synchronously via `spawnSync`, returning the runner's **raw**
- * result. Never throws on a non-zero exit.
+ * Raw `spawnSync` result (untrimmed output, `null` status preserved); never
+ * throws on non-zero exit.
  *
- * Use this when the caller needs the untouched result — untrimmed `stdout`
- * (file contents, TAP output), a `status` of `null` that must stay `null`
- * (`git show`'s 128-vs-killed split), or `result.error`. Callers that only
- * want a normalised `{ status, stdout, stderr }` should use
- * {@link spawnCapture}.
- *
- * @param {string}   file   - Executable name.
- * @param {string[]} args   - Argv tokens.
- * @param {object}   [opts] - As {@link execFileCapture}; `run` defaults to `spawnSync`.
+ * @param {string}   file
+ * @param {string[]} args
+ * @param {object}   [opts]
  * @returns {import('node:child_process').SpawnSyncReturns<string>}
  */
 export function spawnChild(file, args, opts = {}) {
@@ -155,14 +92,12 @@ export function spawnChild(file, args, opts = {}) {
 }
 
 /**
- * {@link spawnChild} with the result normalised: `status` is coerced to `1`
- * when the child did not exit normally (so no caller can read a `null` status
- * as success — `process.exit(null)` exits 0), and both streams are coerced to
- * trimmed strings.
+ * A `null` status becomes 1 (`process.exit(null)` would exit 0); streams are
+ * trimmed.
  *
- * @param {string}   file   - Executable name.
- * @param {string[]} args   - Argv tokens.
- * @param {object}   [opts] - As {@link spawnChild}.
+ * @param {string}   file
+ * @param {string[]} args
+ * @param {object}   [opts]
  * @returns {{ status: number, stdout: string, stderr: string }}
  */
 export function spawnCapture(file, args, opts = {}) {
@@ -175,16 +110,12 @@ export function spawnCapture(file, args, opts = {}) {
 }
 
 /**
- * The one failure-message shape for a child that exited non-zero.
- *
- * `status` is rendered verbatim — a `null` prints as `status=null`, which is
- * the diagnostic: it means the child was killed (buffer overflow, timeout,
- * signal) rather than having reported an exit code of its own.
+ * `status=null` is printed verbatim: it means the child was killed.
  *
  * @param {object} failure
- * @param {string} failure.label    - What was being attempted, e.g. `readBaseFromGit: git show main:x`.
- * @param {number|null} failure.status - Raw child exit status.
- * @param {unknown} [failure.stderr]   - Raw stderr; coerced and trimmed.
+ * @param {string} failure.label
+ * @param {number|null} failure.status
+ * @param {unknown} [failure.stderr]
  * @returns {string}
  */
 export function formatChildFailure({ label, status, stderr }) {

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

@@ -1,79 +1,18 @@
 /**
- * standard-args.js — shared CLI flag parser for the dispatcher's
- * top-level scripts (Story #2460, Epic #2453 — CLI thinning pilot).
+ * Shared CLI flag parser: one canonical spec for the standard dispatcher
+ * flags plus declarative per-script `extras`
+ * (`{ type, alias?, default?, required? }`, alias defaults to camelCase).
  *
- * Replaces the per-CLI hand-rolled flag dispatch with a single
- * declarative entrypoint that the refactored scripts (story-close,
- * epic-deliver, check-baselines) 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?, 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.
+ * `argv` is `process.argv.slice(2)`. `values` always carries every known
+ * flag. Throws with a stable `code`: `UNKNOWN_FLAG`, `MISSING_REQUIRED_FLAG`,
+ * `UNKNOWN_FLAG_IN_SCHEMA`, `UNKNOWN_EXTRAS_TYPE`, `EXTRAS_FLAG_COLLISION`.
  *
  * @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'
- */
+/** Kebab-case flag → `{ key` on `values`, `type }`. */
 const SUPPORTED_FLAGS = Object.freeze({
   epic: { key: 'epicId', type: 'ticket' },
   story: { key: 'storyId', type: 'ticket' },
@@ -98,9 +37,6 @@ function camelCase(name) {
 }
 
 /**
- * Validate the call signature. Only the object form
- * `({ argv, schema, extras })` is accepted.
- *
  * @param {unknown} opts
  * @returns {{ argv: string[], schema: object | undefined, extras: object | undefined }}
  */
@@ -114,12 +50,6 @@ function normaliseCallSignature(opts) {
   return { argv: argv ?? [], schema, extras };
 }
 
-/**
- * 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)) {
@@ -134,19 +64,11 @@ function buildDefineFlagsSpec(extras) {
   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;
@@ -160,10 +82,7 @@ function findUnknownFlag(argv, known) {
   return null;
 }
 
-/**
- * Validate the caller-supplied `schema`. Reject any key that is not a
- * supported standard flag.
- */
+/** Reject unknown keys so a typo cannot silently disable a required check. */
 function validateSchema(schema) {
   if (schema === undefined || schema === null) return;
   if (typeof schema !== 'object') {
@@ -181,11 +100,6 @@ function validateSchema(schema) {
   }
 }
 
-/**
- * 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') {
@@ -216,10 +130,6 @@ function validateExtras(extras) {
   }
 }
 
-/**
- * "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 === '';
@@ -238,10 +148,6 @@ function throwMissing(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)) {
@@ -251,9 +157,6 @@ function enforceRequired(values, schema) {
   }
 }
 
-/**
- * Apply the per-flag `required` constraints declared on `extras`.
- */
 function enforceExtrasRequired(values, extras) {
   if (!extras) return;
   for (const [flag, def] of Object.entries(extras)) {
@@ -263,14 +166,7 @@ function enforceExtrasRequired(values, extras) {
   }
 }
 
-/**
- * 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).
- */
+/** Absent strings become `null` and booleans strict `false`. */
 function normaliseValues(raw, extras) {
   const out = {};
   for (const [, { key, type }] of Object.entries(SUPPORTED_FLAGS)) {
@@ -305,9 +201,6 @@ function normaliseValues(raw, extras) {
 }
 
 /**
- * Parse the dispatcher's shared CLI flag surface. See module docstring
- * for the full contract.
- *
  * @param {{ argv?: string[], schema?: object, extras?: object }} [opts]
  * @returns {{ values: Record<string, unknown>, positionals: string[] }}
  */