mandrel 2.59.0 → 2.61.0

package/.agents/scripts/check-workflow-timeouts.js

@@ -1,291 +0,0 @@
-/**
- * CLI: GitHub Actions job-timeout gate.
- *
- * Story #4936. Every job in this repository inherited GitHub's 360-minute
- * default because not one of the four workflow files set `timeout-minutes`.
- * That is not a theoretical cost: a deadlocked `Windows Smoke` job burned 44
- * minutes of a `windows-latest` runner, and — because the run stayed
- * `in_progress` — GitHub withheld the logs of the *required* check that had
- * already failed on the same run, so the real merge blocker could not be
- * diagnosed until the run was cancelled by hand. An unbounded job costs
- * runner time and diagnosability at once.
- *
- * A ceiling only helps if it is bounded on both ends, so this gate fails on
- * two shapes:
- *
- *   - a job with no `timeout-minutes` at all (unbounded, 360-minute default);
- *   - a job whose `timeout-minutes` exceeds `MAX_TIMEOUT_MINUTES`, i.e. a
- *     number generous enough to be useless as a deadlock detector.
- *
- * `MIN_TIMEOUT_MINUTES` is the floor a value must clear to be plausible
- * headroom over a job that takes a couple of minutes today; below it, a
- * transient slow runner reds the build for no defect.
- *
- * Contract:
- *   - Scans the workflows directory (default `.github/workflows`, override
- *     with `--dir <path>`), parsing each `*.yml` / `*.yaml` with js-yaml and
- *     enumerating every `jobs.<id>` key.
- *   - Prints `<file> job <id> — <reason>` per violation, then a one-line
- *     summary even on a clean scan so the "ok" signal is visible in CI.
- *   - With `--json`: writes a structured envelope to stdout and skips the
- *     human summary.
- *   - Exit codes: 0 = every job bounded in range; 1 = at least one violation.
- *     A missing / empty workflows directory exits 0 (nothing to gate).
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-import yaml from 'js-yaml';
-import { runAsCli } from './lib/cli-utils.js';
-
-/**
- * Inclusive bounds every job's `timeout-minutes` must sit within.
- *
- * The ceiling is the load-bearing half — it is what turns a deadlock into a
- * bounded loss instead of a six-hour one. The floor keeps a well-meaning
- * `timeout-minutes: 2` from reddening the build on a slow runner.
- */
-export const MIN_TIMEOUT_MINUTES = 10;
-export const MAX_TIMEOUT_MINUTES = 30;
-
-/**
- * Enumerate workflow files (`*.yml` / `*.yaml`) directly under `dir`.
- * Returns absolute paths sorted for deterministic output. A missing directory
- * yields an empty list.
- *
- * @param {string} dir Absolute workflows directory.
- * @param {typeof fs} [fsLike]
- * @returns {string[]}
- */
-export function listWorkflowFiles(dir, fsLike = fs) {
-  let entries;
-  try {
-    entries = fsLike.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((e) => e.isFile() && /\.ya?ml$/i.test(e.name))
-    .map((e) => path.join(dir, e.name))
-    .sort();
-}
-
-/**
- * Read the `jobs` mapping out of one workflow document.
- *
- * The single parse point for both the violation scan and the job count, so
- * the two can never disagree about what a workflow's job set is.
- *
- * @param {string} text The file contents.
- * @param {(s: string) => unknown} parse YAML parser; injected in tests.
- * @returns {{ jobs: Record<string, unknown> | null, error: Error | null }}
- */
-function readJobs(text, parse) {
-  let doc;
-  try {
-    doc = parse(text);
-  } catch (err) {
-    return { jobs: null, error: err };
-  }
-  const jobs = doc && typeof doc === 'object' ? doc.jobs : null;
-  return {
-    jobs: jobs && typeof jobs === 'object' ? jobs : null,
-    error: null,
-  };
-}
-
-/**
- * Judge one job body's `timeout-minutes`, returning the violation shape or
- * `null` when the job is bounded in range.
- *
- * Reusable-workflow calls (`jobs.<id>.uses:`) are exempt: `timeout-minutes`
- * is not a valid key on a job that delegates to another workflow — the
- * callee's own jobs carry their timeouts, and setting one here is a schema
- * error rather than a fix.
- *
- * @param {unknown} body The `jobs.<id>` value.
- * @returns {{ timeout: number | null, reason: string } | null}
- */
-function judgeJobTimeout(body) {
-  if (!body || typeof body !== 'object') return null;
-  if (typeof body.uses === 'string') return null;
-
-  const timeout = body['timeout-minutes'];
-  if (timeout === undefined || timeout === null) {
-    return {
-      timeout: null,
-      reason: `no timeout-minutes — the job inherits GitHub's 360-minute default`,
-    };
-  }
-  if (typeof timeout !== 'number' || !Number.isFinite(timeout)) {
-    return {
-      timeout: null,
-      reason: `timeout-minutes is not a number (${JSON.stringify(timeout)})`,
-    };
-  }
-  if (timeout > MAX_TIMEOUT_MINUTES) {
-    return {
-      timeout,
-      reason: `timeout-minutes ${timeout} exceeds the ${MAX_TIMEOUT_MINUTES}-minute ceiling`,
-    };
-  }
-  if (timeout < MIN_TIMEOUT_MINUTES) {
-    return {
-      timeout,
-      reason: `timeout-minutes ${timeout} is below the ${MIN_TIMEOUT_MINUTES}-minute floor`,
-    };
-  }
-  return null;
-}
-
-/**
- * Pure helper: enumerate every `jobs.<id>` key in one workflow document and
- * return the violations.
- *
- * An unparseable document is itself a violation: a workflow whose jobs cannot
- * be enumerated cannot be certified as bounded, and failing open would let
- * the very drift this gate exists to catch through.
- *
- * @param {string} file Relative file label used in violation rows.
- * @param {string} text The file contents.
- * @param {(s: string) => unknown} [parse] YAML parser; injected in tests.
- * @returns {Array<{ file: string, job: string, timeout: number | null, reason: string }>}
- */
-export function scanWorkflowText(file, text, parse = yaml.load) {
-  const { jobs, error } = readJobs(text, parse);
-  if (error) {
-    return [
-      {
-        file,
-        job: '(document)',
-        timeout: null,
-        reason: `workflow could not be parsed as YAML: ${error.message}`,
-      },
-    ];
-  }
-  if (!jobs) return [];
-
-  const violations = [];
-  for (const [job, body] of Object.entries(jobs)) {
-    const verdict = judgeJobTimeout(body);
-    if (verdict) violations.push({ file, job, ...verdict });
-  }
-  return violations;
-}
-
-/**
- * Pure helper: render the human-readable report. One line per violation
- * followed by a one-line summary carrying a `(gate fail)` / `(ok)` marker.
- *
- * @param {Array<{ file: string, job: string, timeout: number | null, reason: string }>} violations
- * @param {number} jobsScanned
- * @returns {string}
- */
-export function renderReport(violations, jobsScanned) {
-  const lines = violations.map((v) => `${v.file} job ${v.job} — ${v.reason}`);
-  const tag = violations.length > 0 ? '(gate fail)' : '(ok)';
-  lines.push(
-    `[workflow-timeouts] jobs=${jobsScanned} violations=${violations.length} ${tag}`,
-  );
-  return lines.join('\n');
-}
-
-/**
- * Count every `jobs.<id>` key in a parsed workflow document, including the
- * reusable-workflow calls the violation scan exempts — the summary reports
- * how many jobs were enumerated, not how many were eligible.
- *
- * @param {string} text
- * @param {(s: string) => unknown} [parse]
- * @returns {number}
- */
-export function countJobs(text, parse = yaml.load) {
-  const { jobs } = readJobs(text, parse);
-  return jobs ? Object.keys(jobs).length : 0;
-}
-
-/**
- * Top-level CLI entry. Exported so tests can drive the full pipeline against
- * a fixture workflows directory without touching the repo's real workflows.
- *
- * @param {{
- *   argv?: string[],
- *   cwd?: string,
- *   stdout?: { write: (s: string) => void },
- *   stderr?: { write: (s: string) => void },
- * }} [opts]
- * @returns {Promise<number>} exit code: 0 = every job bounded; 1 = violation
- */
-export async function runCli({
-  argv = process.argv.slice(2),
-  cwd = process.cwd(),
-  stdout = process.stdout,
-  stderr = process.stderr,
-} = {}) {
-  const dirIdx = argv.indexOf('--dir');
-  const dir =
-    dirIdx !== -1 && argv[dirIdx + 1] && !argv[dirIdx + 1].startsWith('--')
-      ? argv[dirIdx + 1]
-      : null;
-  const json = argv.includes('--json');
-  const resolvedDir = path.resolve(
-    cwd,
-    dir ?? path.join('.github', 'workflows'),
-  );
-
-  const files = listWorkflowFiles(resolvedDir);
-  const violations = [];
-  let jobsScanned = 0;
-  for (const file of files) {
-    let text;
-    try {
-      text = fs.readFileSync(file, 'utf-8');
-    } catch {
-      continue;
-    }
-    const label = path.relative(cwd, file);
-    jobsScanned += countJobs(text);
-    violations.push(...scanWorkflowText(label, text));
-  }
-
-  const exitCode = violations.length > 0 ? 1 : 0;
-
-  if (json) {
-    stdout.write(
-      `${JSON.stringify(
-        {
-          kind: 'workflow-timeouts-report',
-          dir: resolvedDir,
-          filesScanned: files.length,
-          jobsScanned,
-          minTimeoutMinutes: MIN_TIMEOUT_MINUTES,
-          maxTimeoutMinutes: MAX_TIMEOUT_MINUTES,
-          violations,
-          exitCode,
-        },
-        null,
-        2,
-      )}\n`,
-    );
-  } else {
-    if (files.length === 0) {
-      stderr.write(
-        `[workflow-timeouts] ⚠ no workflow files found under ${resolvedDir}\n`,
-      );
-    }
-    stdout.write(`${renderReport(violations, jobsScanned)}\n`);
-  }
-
-  return exitCode;
-}
-
-async function main() {
-  return runCli();
-}
-
-runAsCli(import.meta.url, main, {
-  source: 'workflow-timeouts',
-  propagateExitCode: true,
-  errorPrefix: '[workflow-timeouts] ❌ Fatal error',
-});

package/.agents/scripts/install-matrix-assert.js

@@ -1,326 +0,0 @@
-#!/usr/bin/env node
-// .agents/scripts/install-matrix-assert.js
-/**
- * Golden-path install assertions for the install matrix (Story #3472).
- *
- * The `.github/workflows/install-matrix.yml` workflow exercises the published
- * package contract — install `mandrel`, run `mandrel sync`, run
- * `mandrel doctor` — across {npm, pnpm, yarn} x {ubuntu-latest,
- * windows-latest}. Rather than spread the per-leg invariants across
- * PowerShell-vs-bash shell snippets (which diverge on quoting, `$?`, and
- * path separators), every leg shells out to this single Node script so the
- * checks run identically on every OS.
- *
- * It asserts three invariants against a consumer project directory:
- *
- *   1. `materialized` — `<consumer>/.agents/instructions.md` exists, i.e. the
- *      `.agents/` payload was materialized into the consumer working copy by
- *      `mandrel sync` (or the best-effort postinstall hook).
- *
- *   2. `manifest-clean` — the consumer's `package.json` was NOT mutated with
- *      the framework's internal runtime dependencies. Installing
- *      `mandrel` is expected to add exactly that one package to the
- *      consumer manifest (npm/pnpm/yarn all record the installed dep); what
- *      MUST NOT happen is the framework's own runtime deps (ajv, js-yaml,
- *      minimatch, …) leaking into the consumer's declared dependencies. Those
- *      packages are declared inside `.agents/runtime-deps.json` and the
- *      framework scripts free-ride on the consumer's node_modules — they are
- *      never written into the consumer's package.json.
- *
- *   3. `doctor-ready` — `mandrel doctor` exited 0 and printed the
- *      "✅  Ready" verdict line. This is asserted by the workflow step that
- *      runs doctor and pipes its output here via `--doctor-output <file>`.
- *
- * Each invariant can be run independently (`--check <name>`) or all at once
- * (default). The script exits 0 when every requested check passes and 1 (with
- * an actionable message on stderr) when any fails — so a CI step that invokes
- * it fails the leg loudly rather than silently.
- *
- * Usage:
- *   node .agents/scripts/install-matrix-assert.js \
- *     --consumer <dir> [--check materialized|manifest-clean|doctor-ready] \
- *     [--doctor-output <file>] [--package-name <name>]
- *
- * Security: pure local filesystem reads. No network, no shell, no secrets
- * logged. The doctor-output file is read as plain text and only scanned for
- * the verdict marker.
- *
- * Injectable seams (used by tests):
- *   - `fs`     — replaces the node:fs surface
- *   - `write`  — replaces process.stdout.write
- *   - `writeErr` — replaces process.stderr.write
- */
-
-import nodeFs from 'node:fs';
-import path from 'node:path';
-
-/**
- * The framework's internal runtime dependencies. These are declared in
- * `.agents/runtime-deps.json` and provided by the consumer's install of
- * `mandrel` (npm hoists them into node_modules), but they MUST NOT
- * appear in the consumer's *declared* package.json dependencies. Kept in sync
- * with `.agents/runtime-deps.json` `dependencies` keys — the whole set, so
- * this list documents the closure; {@link SHAREABLE_RUNTIME_DEPS} carries the
- * policy about which of them a consumer may also declare.
- */
-const FRAMEWORK_RUNTIME_DEPS = [
-  '@babel/parser',
-  'ajv',
-  'ajv-formats',
-  'babel-runtime',
-  'escomplex-plugin-metrics-module',
-  'escomplex-plugin-syntax-babylon',
-  'js-yaml',
-  'minimatch',
-  'picomatch',
-  'typhonjs-ast-walker',
-  'typhonjs-escomplex-commons',
-];
-
-/**
- * Runtime dependencies the framework declares but does **not** claim
- * exclusively, so a consumer declaring one is not evidence of a mutated
- * manifest.
- *
- * This check exists to catch a consumer's `package.json` being written into
- * with framework-internal packages. That inference only holds for packages
- * nobody else would plausibly declare. `@babel/parser` and `babel-runtime`
- * fail that test completely: a repository with its own Babel pipeline, AST
- * tooling or legacy transpile output declares them for its own reasons, and
- * failing `manifest-clean` for that would be a false positive on an ordinary
- * consumer rather than a caught mutation.
- *
- * Kept as an explicit list rather than a heuristic: adding a widely-used
- * package to the framework's runtime closure should be a deliberate decision
- * to stop policing it, recorded here.
- */
-const SHAREABLE_RUNTIME_DEPS = ['@babel/parser', 'babel-runtime'];
-
-/**
- * Is this framework dependency's presence in a consumer manifest evidence of a
- * mutated manifest?
- *
- * Only for packages the framework claims exclusively. A shareable one is
- * declared by ordinary repositories for their own reasons.
- *
- * @param {string} dep
- * @param {Record<string, string>} declared Consumer's merged declared deps.
- * @returns {boolean}
- */
-function isLeak(dep, declared) {
-  if (!(dep in declared)) return false;
-  return !SHAREABLE_RUNTIME_DEPS.includes(dep);
-}
-
-/** Exported for the manifest-mirror drift assertion. */
-export { FRAMEWORK_RUNTIME_DEPS, SHAREABLE_RUNTIME_DEPS };
-
-/** The verdict marker `mandrel doctor` prints when every check passes. */
-const DOCTOR_READY_MARKER = '✅  Ready';
-
-const ALL_CHECKS = ['materialized', 'manifest-clean', 'doctor-ready'];
-
-/**
- * Parse `--flag value` / `--flag=value` argv into an options object. Repeated
- * `--check` flags accumulate into an array.
- *
- * @param {string[]} argv
- * @returns {{ consumer?: string, checks: string[], doctorOutput?: string, packageName: string }}
- */
-export function parseArgs(argv) {
-  const opts = { checks: [], packageName: 'mandrel' };
-  for (let i = 0; i < argv.length; i++) {
-    const token = argv[i];
-    const eq = token.indexOf('=');
-    const flag = eq === -1 ? token : token.slice(0, eq);
-    const inlineValue = eq === -1 ? undefined : token.slice(eq + 1);
-    const next = () => inlineValue ?? argv[++i];
-    switch (flag) {
-      case '--consumer':
-        opts.consumer = next();
-        break;
-      case '--check':
-        opts.checks.push(next());
-        break;
-      case '--doctor-output':
-        opts.doctorOutput = next();
-        break;
-      case '--package-name':
-        opts.packageName = next();
-        break;
-      default:
-        // Ignore unknown flags so the script is forward-compatible with
-        // additional workflow plumbing.
-        break;
-    }
-  }
-  if (opts.checks.length === 0) opts.checks = [...ALL_CHECKS];
-  return opts;
-}
-
-/**
- * Assert the `.agents/` payload was materialized into the consumer project.
- *
- * @param {{ consumer: string, fs?: typeof nodeFs }} opts
- * @returns {{ ok: boolean, detail: string }}
- */
-export function checkMaterialized({ consumer, fs = nodeFs }) {
-  const target = path.join(consumer, '.agents', 'instructions.md');
-  if (fs.existsSync(target)) {
-    return { ok: true, detail: `.agents/ materialized (${target})` };
-  }
-  return {
-    ok: false,
-    detail: `./.agents/instructions.md not found at ${target} — \`mandrel sync\` did not materialize the payload.`,
-  };
-}
-
-/**
- * Assert the consumer's package.json was not mutated with framework runtime
- * deps. Installing `mandrel` itself is expected; the framework's
- * internal runtime packages are not.
- *
- * @param {{ consumer: string, packageName: string, fs?: typeof nodeFs }} opts
- * @returns {{ ok: boolean, detail: string }}
- */
-export function checkManifestClean({ consumer, packageName, fs = nodeFs }) {
-  const manifestPath = path.join(consumer, 'package.json');
-  let manifest;
-  try {
-    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-  } catch (err) {
-    return {
-      ok: false,
-      detail: `could not read consumer package.json at ${manifestPath}: ${err.message}`,
-    };
-  }
-
-  const declared = {
-    ...(manifest.dependencies ?? {}),
-    ...(manifest.devDependencies ?? {}),
-    ...(manifest.optionalDependencies ?? {}),
-    ...(manifest.peerDependencies ?? {}),
-  };
-
-  const leaked = FRAMEWORK_RUNTIME_DEPS.filter((dep) => isLeak(dep, declared));
-  if (leaked.length > 0) {
-    return {
-      ok: false,
-      detail: `consumer package.json was mutated with framework runtime deps: ${leaked.join(', ')}`,
-    };
-  }
-
-  // The framework package itself MAY be present (that is the intended install)
-  // but its absence is also fine — the workflow installs it separately and the
-  // assertion only guards against *unexpected* framework-internal deps.
-  const hasFrameworkPkg = packageName in declared;
-  return {
-    ok: true,
-    detail: hasFrameworkPkg
-      ? `manifest clean: only '${packageName}' added, no framework runtime deps leaked`
-      : 'manifest clean: no framework runtime deps leaked',
-  };
-}
-
-/**
- * Assert `mandrel doctor` printed the ready verdict. The workflow captures
- * doctor's stdout to a file and passes it via `--doctor-output`.
- *
- * @param {{ doctorOutput?: string, fs?: typeof nodeFs }} opts
- * @returns {{ ok: boolean, detail: string }}
- */
-export function checkDoctorReady({ doctorOutput, fs = nodeFs }) {
-  if (!doctorOutput) {
-    return {
-      ok: false,
-      detail:
-        '--doctor-output <file> is required for the doctor-ready check (capture `mandrel doctor` stdout to it first).',
-    };
-  }
-  let text;
-  try {
-    text = fs.readFileSync(doctorOutput, 'utf8');
-  } catch (err) {
-    return {
-      ok: false,
-      detail: `could not read doctor output at ${doctorOutput}: ${err.message}`,
-    };
-  }
-  if (text.includes(DOCTOR_READY_MARKER)) {
-    return { ok: true, detail: 'mandrel doctor reported a ready verdict' };
-  }
-  return {
-    ok: false,
-    detail:
-      'mandrel doctor did not report a ready verdict (no "✅  Ready" line in captured output).',
-  };
-}
-
-/**
- * Run the requested checks and report a per-check result. Exits non-zero when
- * any requested check fails.
- *
- * @param {{
- *   argv?: string[],
- *   fs?: typeof nodeFs,
- *   write?: (s: string) => void,
- *   writeErr?: (s: string) => void,
- * }} [opts]
- * @returns {{ ok: boolean, results: Array<{ name: string, ok: boolean, detail: string }> }}
- */
-export function runAssertions({
-  argv = process.argv.slice(2),
-  fs = nodeFs,
-  write = (s) => process.stdout.write(s),
-  writeErr = (s) => process.stderr.write(s),
-} = {}) {
-  const opts = parseArgs(argv);
-
-  if (!opts.consumer) {
-    writeErr('install-matrix-assert: --consumer <dir> is required.\n');
-    return { ok: false, results: [] };
-  }
-
-  const results = [];
-  for (const name of opts.checks) {
-    let result;
-    switch (name) {
-      case 'materialized':
-        result = checkMaterialized({ consumer: opts.consumer, fs });
-        break;
-      case 'manifest-clean':
-        result = checkManifestClean({
-          consumer: opts.consumer,
-          packageName: opts.packageName,
-          fs,
-        });
-        break;
-      case 'doctor-ready':
-        result = checkDoctorReady({ doctorOutput: opts.doctorOutput, fs });
-        break;
-      default:
-        result = { ok: false, detail: `unknown check '${name}'` };
-        break;
-    }
-    results.push({ name, ...result });
-  }
-
-  for (const r of results) {
-    const icon = r.ok ? 'PASS' : 'FAIL';
-    const sink = r.ok ? write : writeErr;
-    sink(`[${icon}] ${r.name}: ${r.detail}\n`);
-  }
-
-  const ok = results.every((r) => r.ok);
-  return { ok, results };
-}
-
-// cli-opt-out: synchronous CLI whose bespoke main-guard forwards an explicit
-// 0/1 exit code from runAssertions(); runAsCli's async-main signature does not
-// preserve that result code (same rationale as coverage-capture.js).
-// Run when invoked directly (not when imported by tests).
-const invokedDirectly = process.argv[1]?.endsWith('install-matrix-assert.js');
-if (invokedDirectly) {
-  const { ok } = runAssertions();
-  process.exit(ok ? 0 : 1);
-}