mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/runtime-deps/ensure-installed.js

@@ -1,30 +1,12 @@
 /**
  * runtime-deps/ensure-installed — fail-fast guard for framework runtime deps.
  *
- * Importing this module runs the dependency-presence check as a side effect:
- * if any package in `.agents/runtime-deps.json`'s `dependencies` block cannot
- * be resolved from the framework's `node_modules` (i.e. the consumer's
- * install is missing, empty, or stale), it prints an actionable remediation
- * message and exits non-zero — *before* the entry point's heavier imports
- * reach the first `import 'ajv'` and throw an opaque `ERR_MODULE_NOT_FOUND`
- * (Story #3432).
- *
- * Why a side-effect-on-import (rather than a function the entry point calls):
- * ESM evaluates a module's imports in source order, depth-first, *before* the
- * module body runs. A function call in `main()` would therefore execute only
- * after the third-party-importing sibling modules had already been evaluated
- * (and already thrown). By making each target entry point's *first* import a
- * side-effect import of this module, the check runs first and short-circuits a
- * broken install with a clear message.
- *
- * The guard only ever exits when a *required* dependency is genuinely
- * missing. With a healthy install (CI, tests, normal runs) it is a no-op, so
- * it is safe for entry points imported by the test suite. `optionalDependencies`
- * are intentionally not checked — they sit behind graceful-degradation paths.
- *
- * Set `MANDREL_SKIP_DEP_PREFLIGHT=1` to disable the side effect (escape hatch
- * for tooling that imports an entry point in an environment that deliberately
- * lacks the framework deps).
+ * Runs on import, deliberately: ESM evaluates imports depth-first before any
+ * module body, so only a side-effect import placed first in an entry point
+ * can report a broken install before a sibling throws an opaque
+ * `ERR_MODULE_NOT_FOUND`. A no-op on a healthy install. `optionalDependencies`
+ * are not checked (they degrade gracefully). `MANDREL_SKIP_DEP_PREFLIGHT=1`
+ * disables it.
  */
 
 import { createRequire } from 'node:module';
@@ -36,16 +18,10 @@ import {
 import { loadRuntimeDepsManifest } from './manifest.js';
 import { detectPackageManager, formatMissingDepsMessage } from './preflight.js';
 
-// `require.resolve` bound to this module's location walks `node_modules`
-// upward from `.agents/scripts/lib/runtime-deps/` to the consumer root —
-// exactly the resolution path the framework's third-party imports follow.
+// Resolves from this file upward — the same path the framework's imports take.
 const frameworkRequire = createRequire(import.meta.url);
 
 /**
- * Run the dependency-presence check and, on failure, write the remediation
- * message and exit. Seams (`requireResolve`, `cwd`, `stderr`, `exit`,
- * `manifest`) make it fully testable without touching the real process.
- *
  * @param {{
  *   requireResolve?: (specifier: string) => string,
  *   cwd?: string,
@@ -66,8 +42,8 @@ export function ensureRuntimeDepsInstalled(opts = {}) {
     readVersion,
   } = opts;
 
-  // A manifest we cannot read is a packaging defect the drift test owns —
-  // never let the guard kill an otherwise-healthy process over it.
+  // An unreadable manifest is a packaging defect the drift test owns; never
+  // kill a healthy process over it.
   if (!manifest) return { ok: true, missing: [] };
 
   const result = checkRuntimeDeps({
@@ -84,11 +60,7 @@ export function ensureRuntimeDepsInstalled(opts = {}) {
 }
 
 /**
- * Remediation text for a failed check.
- *
- * Absence is reported first: a package that is not installed cannot have a
- * version, and installing it is the prerequisite for any version complaint
- * being actionable.
+ * Absence first: installing is the prerequisite for any version complaint.
  *
  * @param {{ missing: string[], mismatched: {name: string, required: string, resolved: string}[] }} result
  * @param {string} cwd
@@ -106,9 +78,6 @@ function describeFailure(result, cwd) {
 }
 
 /**
- * Read a resolved package's version through the framework's own resolution,
- * so the version checked is the one the framework's imports will load.
- *
  * @param {string} name
  * @returns {string | null}
  */
@@ -117,9 +86,6 @@ function defaultReadVersion(name) {
 }
 
 /**
- * Load the manifest, swallowing a read/parse failure to `null` so the guard
- * stays inert on a packaging defect (see `ensureRuntimeDepsInstalled`).
- *
  * @returns {{ required: string[] } | null}
  */
 function safeLoadManifest() {

package/.agents/scripts/lib/runtime-deps/manifest.js

@@ -1,18 +1,7 @@
 /**
- * runtime-deps/manifest — loader for the framework's vendored runtime-dep SSOT.
- *
- * `.agents/runtime-deps.json` is the single source of truth for the
- * third-party npm packages the framework scripts import at runtime
- * (Story #3432). It ships *inside* `.agents/` so it travels with the
- * `mandrel` package into consumer projects. This module is the only reader of that
- * file — the bootstrap seeder (`project-bootstrap.js`), the preflight guard
- * (`ensure-installed.js`), and the import-vs-manifest drift test all derive
- * their dependency lists from `loadRuntimeDepsManifest()` so there is exactly
- * one place the list lives.
- *
- * The loader stays on Node builtins only (`node:fs`, `node:path`,
- * `node:url`) so it can run inside the preflight guard *before* any
- * third-party package is imported — that is the whole point of the guard.
+ * runtime-deps/manifest — the only reader of `.agents/runtime-deps.json`, the
+ * SSOT for the framework's runtime npm packages. Builtins only, because the
+ * preflight guard loads it before any third-party import.
  */
 
 import fs from 'node:fs';
@@ -21,30 +10,21 @@ import { fileURLToPath } from 'node:url';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
-/**
- * Absolute path to the vendored manifest. `HERE` is
- * `.agents/scripts/lib/runtime-deps/`; the manifest sits at the `.agents/`
- * root, three directories up.
- */
 const MANIFEST_PATH = path.resolve(HERE, '..', '..', '..', 'runtime-deps.json');
 
 /**
  * @typedef {object} RuntimeDepsManifest
- * @property {Record<string,string>} dependencies        — required runtime
- *   packages (name → semver range). Fail-fast enforced by the preflight.
- * @property {Record<string,string>} optionalDependencies — packages imported
- *   behind graceful-degradation paths; declared but never preflight-blocked.
- * @property {string[]} required — `Object.keys(dependencies)`.
- * @property {string[]} optional — `Object.keys(optionalDependencies)`.
+ * @property {Record<string,string>} dependencies        — required; preflight-enforced.
+ * @property {Record<string,string>} optionalDependencies — graceful-degradation
+ *   imports; never preflight-blocked.
+ * @property {string[]} required
+ * @property {string[]} optional
  * @property {Set<string>} declared — union of required + optional names.
  */
 
 /**
- * Read, parse, and structurally validate the runtime-deps manifest.
- *
- * Throws a clear `Error` when the file is missing or malformed so the
- * drift test and bootstrap seeder fail loudly on a packaging regression,
- * rather than silently treating the dependency set as empty.
+ * Throws on a missing or malformed file rather than yielding an empty set,
+ * so a packaging regression fails loudly.
  *
  * @param {string} [manifestPath=MANIFEST_PATH]
  * @returns {RuntimeDepsManifest}

package/.agents/scripts/lib/runtime-deps/parser-major.js

@@ -1,17 +1,9 @@
 /**
- * runtime-deps/parser-major — which `@babel/parser` major the complexity
- * kernel can actually parse with, and how to say so when it is wrong.
- *
- * Its own module because two very different callers need the same answer and
- * neither should drag the other in: the kernel asserts it at load, and
- * `mandrel doctor` reports it to a consumer. Importing the kernel into doctor
- * to ask one version question would pull the whole metric core and install the
- * AST compatibility patch as a side effect.
- *
- * `.agents/` materializes into the consumer's repository root, so
- * `@babel/parser` resolves from *their* `node_modules`. A range in
- * `runtime-deps.json` documents the requirement; it cannot enforce it. This is
- * the enforcement.
+ * runtime-deps/parser-major — whether the resolved `@babel/parser` major is
+ * one the complexity kernel can parse with. Separate so `mandrel doctor` can
+ * ask without importing the kernel (and its AST patch side effect). The
+ * parser resolves from the consumer's tree, so this is the enforcement of the
+ * declared range.
  *
  * @module lib/runtime-deps/parser-major
  */
@@ -19,36 +11,20 @@
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
 
-/**
- * The only `@babel/parser` major the kernel supports.
- *
- * Module-local, with `describeParserMajorError` as the single public door:
- * every caller wants the verdict and the remedy, not the number.
- *
- * 8.x removed several plugin names from the kernel's fixed list (they became
- * default syntax), so it does not merely warn — it throws on the plugin list
- * itself. Adopting it is a deliberate change with a baseline recut attached,
- * not something to absorb from a consumer's resolution.
- */
+// 8.x throws on the kernel's fixed plugin list; adopting it is a deliberate
+// change with a baseline recut, not something to absorb from a consumer.
 const SUPPORTED_PARSER_MAJOR = 7;
 
-/** Package whose resolved major gates the kernel. */
 const PARSER_PACKAGE = '@babel/parser';
 
-/** Memoised resolved parser version: `undefined` unread, `null` unresolvable. */
+/** Memoised: `undefined` unread, `null` unresolvable. */
 let parserVersion;
 
 /**
- * Read the resolved `@babel/parser` version from its own manifest.
- *
- * The package exports no version, so its `package.json` is the only source.
- * This is the one non-static resolution in the file and it deliberately
- * targets a manifest rather than code: `@babel/parser` itself is reached by a
- * static import above, so it is declared and preflighted like every other
- * dependency.
+ * The package exports no version, so its manifest is the only source.
  *
  * @returns {string|null} The resolved version, or `null` when the manifest
- *   cannot be read (a layout that hides `package.json` behind `exports`, say).
+ *   cannot be read.
  */
 function resolveParserVersion() {
   if (parserVersion !== undefined) return parserVersion;
@@ -64,10 +40,7 @@ function resolveParserVersion() {
 }
 
 /**
- * The resolved parser's major version.
- *
- * @returns {number|null} `null` when the version could not be resolved or
- *   does not lead with an integer.
+ * @returns {number|null}
  */
 function resolveParserMajor() {
   const version = resolveParserVersion();
@@ -77,21 +50,12 @@ function resolveParserMajor() {
 }
 
 /**
- * Describe the resolved-parser problem, if there is one.
- *
- * Single-sourced so the load-time assertion below and the preflight guard
- * (`runtime-deps/ensure-installed.js`) emit the *same* named, actionable
- * message — the point of AC-5 is that a consumer never meets this as a
- * plugin-list syntax error mid-scan.
- *
- * An unresolvable version is **not** a problem: a consumer layout that hides
- * the manifest still resolves the parser itself, and refusing to score would
- * be a worse answer than scoring with an unverified parser. Only a
- * *known-wrong* major is reported.
+ * One message shared by the kernel's load-time assertion and the preflight
+ * guard. An unknowable version is not reported — scoring with an unverified
+ * parser beats refusing to score; only a known-wrong major is.
  *
  * @param {{major?: number|null, version?: string|null}} [resolved] Overrides
- *   the resolved parser, so the message a consumer on an unsupported major
- *   would read is assertable without installing one.
+ *   the resolved parser (test seam).
  * @returns {string|null} The message, or `null` when the resolved parser is
  *   supported (or its version is unknowable).
  */

package/.agents/scripts/lib/runtime-deps/preflight.js

@@ -1,28 +1,13 @@
 /**
- * runtime-deps/preflight — pure helpers for the dependency-presence check's
- * *messaging* half.
- *
- * The check itself moved to `dep-resolution.js`, which owns resolving a
- * declared dependency, judging its major, and explaining a mismatch. What is
- * left here holds no side effects and stays unit-testable in isolation:
- * `detectPackageManager` takes an injected `exists` seam and
- * `formatMissingDepsMessage` is a pure string builder. The side-effecting
- * guard that wires them to the real process lives in `ensure-installed.js`.
- *
- * Builtins only — this module runs *before* any third-party package is
- * imported, so importing a third-party here would defeat its own purpose.
+ * runtime-deps/preflight — pure messaging helpers for the dependency check.
+ * Builtins only: it runs before any third-party package is imported.
  */
 
 import fs from 'node:fs';
 import { detectPackageManager as detectPm } from '../detect-package-manager.js';
 
 /**
- * Detect the consumer's package manager from lockfile presence so the
- * remediation message names the right install command. Defaults to `npm`.
- *
- * Delegates to the shared `detectPackageManager` helper
- * (Story #4048 B3 — one implementation per concept). The `exists` seam
- * is forwarded directly; `null` (no manifest) coerces to `'npm'`.
+ * Lockfile-based, so the message names the right install command.
  *
  * @param {string} root
  * @param {(p: string) => boolean} [exists=fs.existsSync]
@@ -32,7 +17,6 @@ export function detectPackageManager(root, exists = fs.existsSync) {
   return detectPm(root, exists) ?? 'npm';
 }
 
-/** Map a detected package manager to its install command. */
 function installCommand(packageManager) {
   if (packageManager === 'pnpm') return 'pnpm install';
   if (packageManager === 'yarn') return 'yarn install';
@@ -40,9 +24,7 @@ function installCommand(packageManager) {
 }
 
 /**
- * Build the actionable remediation message naming the missing packages and
- * the consumer's install command. This is what replaces the opaque raw
- * `ERR_MODULE_NOT_FOUND` stack trace.
+ * Replaces the opaque `ERR_MODULE_NOT_FOUND` stack with an actionable message.
  *
  * @param {string[]} missing
  * @param {{ root: string, packageManager: 'pnpm'|'yarn'|'npm' }} opts

package/.agents/scripts/lib/runtime-deps/scan-imports.js

@@ -1,26 +1,9 @@
 /**
- * runtime-deps/scan-imports — extract third-party package imports from source.
- *
- * Powers the import-vs-manifest drift test (Story #3432): it walks
- * `.agents/scripts/**` and reports every third-party (non-builtin,
- * non-relative) top-level package the framework imports, so the test can
- * assert each one is declared in `.agents/runtime-deps.json`.
- *
- * Robustness is the whole game here. A naive `from ['"]...['"]` regex also
- * matches prose inside strings and comments (e.g. a log line containing the
- * word "from 'x'"), which would invent phantom dependencies. Two guards
- * prevent that:
- *
- *   1. Static `import` / `export … from` matches are anchored to the start
- *      of a line — a real import statement begins the line; prose inside a
- *      template literal does not.
- *   2. Every extracted specifier's *top-level* package name is validated
- *      against the npm package-name grammar. Names with spaces, uppercase,
- *      or stray punctuation (i.e. accidental prose captures) are rejected.
- *
- * Node builtins (`node:fs`, `path`, …) and relative/absolute specifiers are
- * excluded. Subpath specifiers (`ajv/dist/2020.js`, `@scope/pkg/sub`) are
- * collapsed to their installable top-level name (`ajv`, `@scope/pkg`).
+ * runtime-deps/scan-imports — extract third-party top-level package imports
+ * from source, for the import-vs-manifest drift test. To avoid inventing
+ * phantom deps from prose, comments are stripped, static imports must start
+ * a line, and every name must match the npm package-name grammar. Subpaths
+ * collapse to their installable name.
  */
 
 import fs from 'node:fs';
@@ -28,21 +11,15 @@ import { builtinModules } from 'node:module';
 import path from 'node:path';
 import { stripJsComments } from '../source-text/strip-js-comments.js';
 
-/** Node builtins, with and without the `node:` prefix. */
 const BUILTIN_MODULES = new Set([
   ...builtinModules,
   ...builtinModules.map((m) => `node:${m}`),
 ]);
 
-/**
- * npm package-name grammar (top-level, optionally scoped). Lowercase,
- * digits, and a small punctuation set only — deliberately strict so that
- * accidental prose captures are rejected.
- */
+// Deliberately strict so accidental prose captures are rejected.
 const PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
 
 /**
- * Collapse an import specifier to its installable top-level package name.
  * `@scope/pkg/sub` → `@scope/pkg`; `pkg/sub` → `pkg`.
  *
  * @param {string} specifier
@@ -55,8 +32,6 @@ export function toTopLevelPackage(specifier) {
 }
 
 /**
- * True when `name` is a syntactically valid npm package name.
- *
  * @param {string} name
  * @returns {boolean}
  */
@@ -64,27 +39,19 @@ export function isValidPackageName(name) {
   return typeof name === 'string' && PACKAGE_NAME.test(name);
 }
 
-// Anchored static import / re-export: the statement must start the line.
 const STATIC_FROM =
   /^\s*(?:import|export)\b[^\n;]*?\bfrom\s*['"]([^'"]+)['"]/gm;
-// Anchored side-effect import at line start.
 const SIDE_EFFECT = /^\s*import\s*['"]([^'"]+)['"]/gm;
 // `require(...)` and dynamic `import(...)` may appear mid-expression.
 const CALL_FORM = /\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]/g;
-// Names bound to a `createRequire(...)` result, e.g.
-// `const fromReader = createRequire(x)`. Such a binding is a require function
-// under a different name, so calls through it are real runtime imports that
-// `CALL_FORM` cannot see — it matches the literal callees `require`/`import`.
-// A module reached only that way would be an undeclared, unpreflighted
-// dependency that this scanner reported as absent.
+// A `createRequire(...)` binding is a require under another name; calls
+// through it are real imports CALL_FORM cannot see.
 const REQUIRE_ALIAS =
   /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*createRequire\s*\(/g;
 
 /**
- * Build a matcher for calls through `createRequire`-bound identifiers.
- *
- * Returns `null` when the source binds none, so the common case adds no pass.
- * Aliases named `require` need no entry — `CALL_FORM` already covers them.
+ * `null` when the source binds no alias (aliases named `require` are already
+ * covered).
  *
  * @param {string} cleaned Comment-stripped source.
  * @returns {RegExp|null}
@@ -105,9 +72,6 @@ function aliasedRequireMatcher(cleaned) {
 }
 
 /**
- * The specifier patterns to run over one source: the three fixed forms, plus
- * an alias matcher when the source binds a `createRequire` result.
- *
  * @param {string} cleaned Comment-stripped source.
  * @returns {RegExp[]}
  */
@@ -118,9 +82,6 @@ function specifierMatchers(cleaned) {
 }
 
 /**
- * Extract the set of third-party top-level package names imported by a
- * single source string.
- *
  * @param {string} source
  * @returns {Set<string>}
  */
@@ -132,7 +93,7 @@ export function extractThirdPartyImports(source) {
     let match = re.exec(cleaned);
     while (match !== null) {
       const specifier = match[1];
-      // Advance the iterator up front so every `continue` below is safe.
+      // Advance first so every `continue` below is safe.
       match = re.exec(cleaned);
       if (
         specifier.startsWith('.') ||
@@ -152,8 +113,6 @@ export function extractThirdPartyImports(source) {
 }
 
 /**
- * Recursively collect every `.js` file under `dir`.
- *
  * @param {string} dir
  * @returns {string[]}
  */
@@ -171,9 +130,6 @@ export function listJsFiles(dir) {
 }
 
 /**
- * Scan every `.js` file under `dir` and map each third-party top-level
- * package to the (relative) files that import it.
- *
  * @param {string} dir — directory root to scan (e.g. `.agents/scripts`).
  * @returns {{ packages: Set<string>, byPackage: Map<string, string[]> }}
  */

package/.agents/scripts/lib/signals/detectors/common.js

@@ -1,14 +1,9 @@
 /**
- * detectors/common.js — shared helpers for the signals layer.
- *
- * Hoisted out of the detector modules (retry, rework) plus
- * the since-deleted `signals/read.js`, and `signals/schema.js`, all of which shipped
- * byte-equivalent copies of these predicates. See Story #2464.
+ * detectors/common.js — shared predicates for the signals layer.
  */
 
 /**
- * Return true when `v` is a positive (strictly > 0) integer. Used by every
- * signal writer and reader as the canonical numeric-id guard.
+ * The canonical numeric-id guard for signal writers and readers.
  *
  * @param {unknown} v
  * @returns {boolean}
@@ -18,9 +13,7 @@ export function isPositiveInt(v) {
 }
 
 /**
- * Pull the tool name from a trace record. The hook writes the tool name
- * into `emitter.tool` (canonical provenance) and, defensively, into
- * `details.tool` — we accept either.
+ * `emitter.tool` is canonical; `details.tool` is accepted defensively.
  *
  * @param {object} rec
  * @returns {string|null}
@@ -36,35 +29,17 @@ export function extractTool(rec) {
 }
 
 /**
- * Validate and normalize the shared detector argument preamble.
- *
- * `detectRework` and `detectRetry` previously shipped a near-identical
- * guard block: the `args` object-shape `TypeError`, the `nowFn`
- * function-type `TypeError`, the positive-integer `RangeError`s for the id
- * fields, the non-empty-string `tracesPath` check, and the
- * non-negative-integer `threshold` check. Story #4077 hoists that preamble
- * here so the detectors share one error-message contract.
- *
- * Error wording stays per-detector-accurate by prefixing every message with
- * `fnName` (e.g. `detectRework: …`). Error *types* are preserved exactly:
- * the `args`/`tracesPath`/`nowFn` guards throw `TypeError`; the id and
- * `threshold` guards throw `RangeError`.
- *
- * The validated fields are gated by the `require*` flags so the same helper
- * serves both the Story-scoped detectors (rework/retry — full preamble) and
- * the Epic-scoped hotspot detector (only `epicId` + `nowFn`). A field that
- * is not required is neither validated nor read.
+ * Shared detector argument guard. Messages are prefixed with `fnName`;
+ * shape/`tracesPath`/`nowFn` failures throw `TypeError`, id and `threshold`
+ * failures `RangeError`. A field whose `require*` flag is off is neither
+ * validated nor returned.
  *
  * @param {object} args — the detector's raw argument object.
  * @param {object} opts
- * @param {string} opts.fnName — the calling detector's name, used verbatim as
- *   the prefix on every thrown error message (e.g. `'detectRework'`).
- * @param {boolean} [opts.requireTracesPath=true] — validate + return
- *   `tracesPath` (non-empty string).
- * @param {boolean} [opts.requireStoryId=true] — validate + return `storyId`
- *   (positive integer) and the optional `taskId` (positive integer or null).
- * @param {boolean} [opts.requireThreshold=true] — validate + return
- *   `threshold` (non-negative integer).
+ * @param {string} opts.fnName — error-message prefix (e.g. `'detectRework'`).
+ * @param {boolean} [opts.requireTracesPath=true]
+ * @param {boolean} [opts.requireStoryId=true] — also gates the optional `taskId`.
+ * @param {boolean} [opts.requireThreshold=true]
  * @returns {{
  *   tracesPath: string|undefined,
  *   epicId: number,
@@ -72,8 +47,7 @@ export function extractTool(rec) {
  *   taskId: number|null|undefined,
  *   threshold: number|undefined,
  *   nowFn: () => string,
- * }} the normalized argument set. Fields gated off by a `require*` flag are
- *   omitted (left `undefined`).
+ * }}
  */
 export function validateDetectorArgs(args, opts) {
   const { fnName } = opts;

package/.agents/scripts/lib/signals/index.js

@@ -1,23 +1,6 @@
 /**
- * `lib/signals/` barrel.
- *
- * Consumers do `import { schema, appendSignal } from './lib/signals/index.js'`
- * (or `import * as signals from './lib/signals/index.js'`) so a future
- * shape migration only has to touch this file.
- *
- * History:
- *   - Epic #1181 / Story #1438 / Task #1459 — initial barrel with `read`
- *     + `schema`; `buildSpanTree` was a throwing placeholder.
- *   - Epic #1181 / Story #1440 / Task #1461 — placeholder replaced by
- *     the real span-tree builder.
- *   - Story #1476 — `appendSignal` / `appendTrace` re-exported here
- *     via `./write.js` so the gate scripts (and any
- *     new code) converge on `lib/signals/` instead of importing the
- *     writer directly from `lib/observability/`.
- *   - Story #5003 — the reader half (`read`, `buildSpanTree`) went with the
- *     debug viewer that consumed it: it walked a `run-<id>/` layout no v2
- *     writer populates. `appendTrace` went with the trace hook, its only
- *     producer. What remains is the live write surface.
+ * `lib/signals/` barrel — the one import point, so a shape migration touches
+ * only this file.
  *
  * @module lib/signals
  */