mandrel 2.57.0 → 2.59.0

package/.agents/scripts/lib/runtime-deps/dep-resolution.js

@@ -0,0 +1,155 @@
+/**
+ * runtime-deps/dep-resolution — is a declared runtime dependency actually
+ * there, is it the right major, and how do we say so.
+ *
+ * `.agents/` materializes into the consumer's repository root, so every
+ * framework runtime dependency resolves from *their* `node_modules`. A range
+ * in `.agents/runtime-deps.json` therefore documents a requirement it cannot
+ * enforce, and the preflight guard needs to compare the range against what
+ * actually resolved.
+ *
+ * Deliberately major-only, and deliberately not `semver`. The framework's
+ * runtime ranges are all `^`, whose whole contract is "this major"; pulling in
+ * a semver implementation to decide one comparison would add a dependency to
+ * the very closure this module exists to keep honest.
+ *
+ * @module lib/runtime-deps/dep-resolution
+ */
+
+/**
+ * Leading major number of a version or a caret/tilde range, or `null`.
+ *
+ * Module-local: `majorMismatch` is the only question callers have.
+ *
+ * Anything this cannot read as `<major>.` — `*`, a tag, a git URL, a
+ * `>=x <y` span — yields `null` and is treated as "not range-checked". That
+ * asymmetry is intentional: a conservative miss is a no-op, while a false
+ * positive blocks a working install.
+ *
+ * @param {string|null|undefined} spec
+ * @returns {number|null}
+ */
+function majorOf(spec) {
+  if (typeof spec !== 'string') return null;
+  const match = /^[\^~]?(\d+)\./.exec(spec.trim());
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Does `resolved` sit outside the major `range` names?
+ *
+ * Module-local: `checkRuntimeDeps` is the only caller, and exporting it only
+ * for a test would be a production-dead export.
+ *
+ * `false` whenever either side is unreadable, so an unparseable range or an
+ * unreadable installed version is never reported as a mismatch.
+ *
+ * `0.x` majors compare as written: `^0.1.0` and `0.2.1` differ in minor, not
+ * major, so this does not separate them. Accepted — the `0.x` packages in the
+ * closure are terminal, and the range this exists to enforce is
+ * `@babel/parser`'s `^7`.
+ *
+ * @param {string|null|undefined} range
+ * @param {string|null|undefined} resolved
+ * @returns {boolean}
+ */
+function majorMismatch(range, resolved) {
+  const want = majorOf(range);
+  if (want === null) return false;
+  const got = majorOf(resolved);
+  if (got === null) return false;
+  return want !== got;
+}
+
+/**
+ * Is a package present in the resolvable tree?
+ *
+ * The bare specifier is tried first, then `<name>/package.json`. The fallback
+ * is not belt-and-braces: a package with no `main` and no `exports` — which
+ * `typhonjs-escomplex-commons` and `babel-runtime` both are — cannot be
+ * resolved by name at all, and is reached only by deep path. Probing the bare
+ * name alone would report such a package missing while it sits installed, and
+ * this guard exits the process on that verdict.
+ *
+ * @param {string} dep
+ * @param {(specifier: string) => string} resolve
+ * @returns {boolean}
+ */
+export function isResolvable(dep, resolve) {
+  try {
+    resolve(dep);
+    return true;
+  } catch {
+    // fall through to the manifest probe
+  }
+  try {
+    resolve(`${dep}/package.json`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remediation text for a resolved dependency whose major differs from the
+ * range the framework declares.
+ *
+ * Named separately from the missing-deps message because the remedy differs:
+ * the package is installed, so installing again changes nothing. What is
+ * wrong is the version the consumer's own tree resolves, which only they can
+ * change.
+ *
+ * @param {{name: string, required: string, resolved: string}[]} mismatched
+ * @param {{ root: string }} ctx
+ * @returns {string}
+ */
+export function formatMismatchedDepsMessage(mismatched, { root }) {
+  const lines = mismatched.map(
+    (m) => `  - ${m.name}: need ${m.required}, resolved ${m.resolved}`,
+  );
+  return [
+    'Mandrel framework runtime dependency version mismatch:',
+    ...lines,
+    '',
+    `Resolved from: ${root}`,
+    'These packages are resolved from your repository, not from mandrel, so',
+    'the version your tree installs is the version the framework gets. Pin a',
+    'compatible major in your package.json and reinstall.',
+  ].join('\n');
+}
+
+/**
+ * Resolve each required package via the injected `resolve` seam and collect
+ * the ones that fail. `resolve` is typically `require.resolve` bound to the
+ * framework module location; it throws `MODULE_NOT_FOUND` when a package is
+ * absent from the resolvable `node_modules`.
+ *
+ * @param {{ required: string[], resolve: (specifier: string) => string }} opts
+ * @returns {{ ok: boolean, missing: string[] }}
+ */
+export function checkRuntimeDeps({
+  required,
+  resolve,
+  ranges = null,
+  readVersion = null,
+}) {
+  const missing = [];
+  const mismatched = [];
+  for (const dep of required) {
+    if (!isResolvable(dep, resolve)) {
+      missing.push(dep);
+      continue;
+    }
+    if (!ranges || !readVersion) continue;
+    const range = ranges[dep];
+    const resolved = readVersion(dep);
+    if (majorMismatch(range, resolved)) {
+      mismatched.push({ name: dep, required: range, resolved });
+    }
+  }
+  return {
+    ok: missing.length === 0 && mismatched.length === 0,
+    missing,
+    mismatched,
+  };
+}

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

@@ -28,12 +28,13 @@
  */
 
 import { createRequire } from 'node:module';
-import { loadRuntimeDepsManifest } from './manifest.js';
+import { resolveDependencyVersion } from '../dependency-version.js';
 import {
   checkRuntimeDeps,
-  detectPackageManager,
-  formatMissingDepsMessage,
-} from './preflight.js';
+  formatMismatchedDepsMessage,
+} from './dep-resolution.js';
+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 —
@@ -50,7 +51,8 @@ const frameworkRequire = createRequire(import.meta.url);
  *   cwd?: string,
  *   stderr?: { write: (s: string) => void },
  *   exit?: (code: number) => void,
- *   manifest?: { required: string[] },
+ *   manifest?: { required: string[], dependencies?: Record<string,string> },
+ *   readVersion?: (name: string) => string | null,
  * }} [opts]
  * @returns {{ ok: boolean, missing: string[] }}
  */
@@ -61,6 +63,7 @@ export function ensureRuntimeDepsInstalled(opts = {}) {
     stderr = process.stderr,
     exit = process.exit,
     manifest = safeLoadManifest(),
+    readVersion,
   } = opts;
 
   // A manifest we cannot read is a packaging defect the drift test owns —
@@ -70,17 +73,49 @@ export function ensureRuntimeDepsInstalled(opts = {}) {
   const result = checkRuntimeDeps({
     required: manifest.required,
     resolve: requireResolve,
+    ranges: manifest.dependencies ?? null,
+    readVersion: readVersion ?? defaultReadVersion,
   });
   if (result.ok) return result;
 
-  const packageManager = detectPackageManager(cwd);
-  stderr.write(
-    `${formatMissingDepsMessage(result.missing, { root: cwd, packageManager })}\n`,
-  );
+  stderr.write(`${describeFailure(result, cwd)}\n`);
   exit(1);
   return result;
 }
 
+/**
+ * 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.
+ *
+ * @param {{ missing: string[], mismatched: {name: string, required: string, resolved: string}[] }} result
+ * @param {string} cwd
+ * @returns {string}
+ */
+function describeFailure(result, cwd) {
+  if (result.missing.length === 0) {
+    return formatMismatchedDepsMessage(result.mismatched, { root: cwd });
+  }
+  const packageManager = detectPackageManager(cwd);
+  return formatMissingDepsMessage(result.missing, {
+    root: cwd,
+    packageManager,
+  });
+}
+
+/**
+ * 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}
+ */
+function defaultReadVersion(name) {
+  return resolveDependencyVersion(name, frameworkRequire);
+}
+
 /**
  * Load the manifest, swallowing a read/parse failure to `null` so the guard
  * stays inert on a packaging defect (see `ensureRuntimeDepsInstalled`).

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

@@ -0,0 +1,110 @@
+/**
+ * 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.
+ *
+ * @module lib/runtime-deps/parser-major
+ */
+
+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.
+ */
+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. */
+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.
+ *
+ * @returns {string|null} The resolved version, or `null` when the manifest
+ *   cannot be read (a layout that hides `package.json` behind `exports`, say).
+ */
+function resolveParserVersion() {
+  if (parserVersion !== undefined) return parserVersion;
+  try {
+    const require = createRequire(import.meta.url);
+    const manifest = require.resolve(`${PARSER_PACKAGE}/package.json`);
+    const parsed = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
+    parserVersion = typeof parsed?.version === 'string' ? parsed.version : null;
+  } catch {
+    parserVersion = null;
+  }
+  return parserVersion;
+}
+
+/**
+ * The resolved parser's major version.
+ *
+ * @returns {number|null} `null` when the version could not be resolved or
+ *   does not lead with an integer.
+ */
+function resolveParserMajor() {
+  const version = resolveParserVersion();
+  if (version === null) return null;
+  const major = Number.parseInt(version, 10);
+  return Number.isInteger(major) ? major : null;
+}
+
+/**
+ * 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.
+ *
+ * @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.
+ * @returns {string|null} The message, or `null` when the resolved parser is
+ *   supported (or its version is unknowable).
+ */
+export function describeParserMajorError(resolved = {}) {
+  const { major = resolveParserMajor(), version = resolveParserVersion() } =
+    resolved;
+  if (major === null || major === SUPPORTED_PARSER_MAJOR) return null;
+  return (
+    `unsupported ${PARSER_PACKAGE} major: resolved ${version}, ` +
+    `the complexity kernel requires ${SUPPORTED_PARSER_MAJOR}.x. It parses ` +
+    `with a fixed plugin list that later majors reject, so CRAP and ` +
+    `maintainability scoring would fail mid-scan with an opaque plugin-list ` +
+    `error. Declare "${PARSER_PACKAGE}": "^${SUPPORTED_PARSER_MAJOR}" in ` +
+    `your package.json (see .agents/runtime-deps.json).`
+  );
+}

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

@@ -1,9 +1,11 @@
 /**
- * runtime-deps/preflight — pure helpers for the dependency-presence check.
+ * runtime-deps/preflight — pure helpers for the dependency-presence check's
+ * *messaging* half.
  *
- * These functions hold no side effects so they are unit-testable in
- * isolation: `checkRuntimeDeps` takes an injected `resolve` seam,
- * `detectPackageManager` takes an injected `exists` seam, and
+ * 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`.
  *
@@ -14,27 +16,6 @@
 import fs from 'node:fs';
 import { detectPackageManager as detectPm } from '../detect-package-manager.js';
 
-/**
- * Resolve each required package via the injected `resolve` seam and collect
- * the ones that fail. `resolve` is typically `require.resolve` bound to the
- * framework module location; it throws `MODULE_NOT_FOUND` when a package is
- * absent from the resolvable `node_modules`.
- *
- * @param {{ required: string[], resolve: (specifier: string) => string }} opts
- * @returns {{ ok: boolean, missing: string[] }}
- */
-export function checkRuntimeDeps({ required, resolve }) {
-  const missing = [];
-  for (const dep of required) {
-    try {
-      resolve(dep);
-    } catch {
-      missing.push(dep);
-    }
-  }
-  return { ok: missing.length === 0, missing };
-}
-
 /**
  * Detect the consumer's package manager from lockfile presence so the
  * remediation message names the right install command. Defaults to `npm`.

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

@@ -71,6 +71,51 @@ const STATIC_FROM =
 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.
+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.
+ *
+ * @param {string} cleaned Comment-stripped source.
+ * @returns {RegExp|null}
+ */
+function aliasedRequireMatcher(cleaned) {
+  REQUIRE_ALIAS.lastIndex = 0;
+  const names = new Set();
+  let m = REQUIRE_ALIAS.exec(cleaned);
+  while (m !== null) {
+    if (m[1] !== 'require') names.add(m[1]);
+    m = REQUIRE_ALIAS.exec(cleaned);
+  }
+  if (names.size === 0) return null;
+  const alternation = [...names]
+    .map((n) => n.replace(/[$]/g, '\\$$'))
+    .join('|');
+  return new RegExp(`\\b(?:${alternation})\\s*\\(\\s*['"]([^'"]+)['"]`, 'g');
+}
+
+/**
+ * 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[]}
+ */
+function specifierMatchers(cleaned) {
+  const aliased = aliasedRequireMatcher(cleaned);
+  if (!aliased) return [STATIC_FROM, SIDE_EFFECT, CALL_FORM];
+  return [STATIC_FROM, SIDE_EFFECT, CALL_FORM, aliased];
+}
 
 /**
  * Extract the set of third-party top-level package names imported by a
@@ -82,7 +127,7 @@ const CALL_FORM = /\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]/g;
 export function extractThirdPartyImports(source) {
   const found = new Set();
   const cleaned = stripJsComments(source);
-  for (const re of [STATIC_FROM, SIDE_EFFECT, CALL_FORM]) {
+  for (const re of specifierMatchers(cleaned)) {
     re.lastIndex = 0;
     let match = re.exec(cleaned);
     while (match !== null) {

package/.agents/scripts/lib/skills/walk-skill-files.js

@@ -41,7 +41,7 @@ export const LOCAL_SKILLS_SEGMENTS = Object.freeze([
 
 /**
  * A skill id is the tier-relative path naming a skill — e.g.
- * `core/scope-triage` or `stack/qa/playwright`. It is the value that
+ * `core/test-first` or `stack/qa/playwright`. It is the value that
  * appears in `skills.index.json` minus the root prefix, and the value a
  * `qa.environments.*.signInSeam.skill` seam carries.
  *

package/.agents/scripts/lib/story-body/story-body.js

@@ -164,7 +164,14 @@ const HUMANIZED_PATH_ENTRY_RE = /^`([^`]+)`\s+—\s+(\S+)$/;
 // AC-<n> presentation prefix on acceptance checkboxes (Story #4600). The
 // numbering is a stable 1-based human handle only — parse() strips it so the
 // top-level acceptance[] machine contract round-trips byte-identical.
-const AC_PREFIX_RE = /^AC-\d+:\s+/;
+//
+// The lettered form (`AC-14a:`) is accepted too (Story #5323). Nothing emits
+// one — `serialize()` numbers from the array index — but a Story planned from
+// an existing ticket can copy one out of the source issue's rendered
+// checkboxes, and a body that already carries one must still parse to the
+// handle-free text or the round-trip invariant breaks for it alone. Trailing
+// whitespace is optional so `AC-3:text` normalises as readily as `AC-3: text`.
+const AC_PREFIX_RE = /^AC-\d+[a-z]?:\s*/i;
 
 // Machine-managed marker lines a body authored before Story #5312 may still
 // carry: the `> **Wide:** <reason>` rationale line (Story #4600), the
@@ -560,6 +567,33 @@ function parseTextListSection(lines) {
  * @returns {ParseResult}
  * @throws {StoryBodyParseError} When the body is structurally unrecoverable.
  */
+/**
+ * Strip the presentation `AC-<n>:` handle off one acceptance item.
+ *
+ * The handle belongs to {@link serialize}, which numbers every checkbox from
+ * its position in `acceptance[]`; an authored item that already carries one
+ * would render doubled (`- [ ] AC-1: AC-1: …`) and a lettered handle copied
+ * from a source ticket would survive into the machine contract. Both parse
+ * and the persist-side normalisation resolve the grammar here so the two can
+ * never disagree about what a handle is (Story #5323).
+ *
+ * Stacked handles are peeled in full — a body persisted while the doubling
+ * was live carries two, and leaving the inner one would normalise to
+ * something that still is not the authored text.
+ *
+ * @param {string} item
+ * @returns {{ text: string, stripped: boolean }} The handle-free text, and
+ *   whether anything was removed.
+ */
+export function stripAcceptanceHandle(item) {
+  const original = String(item ?? '');
+  let text = original;
+  while (AC_PREFIX_RE.test(text)) {
+    text = text.replace(AC_PREFIX_RE, '');
+  }
+  return { text, stripped: text !== original };
+}
+
 export function parse(input) {
   if (input === null || input === undefined) {
     throw new StoryBodyParseError('Story body is null or undefined', {
@@ -618,7 +652,7 @@ export function parse(input) {
   // The AC-<n> checkbox prefix is presentation-only (Story #4600): strip it
   // so acceptance[] round-trips byte-identical to the authored array.
   const acceptance = parseTextListSection(sections.get('acceptance') ?? []).map(
-    (a) => a.replace(AC_PREFIX_RE, ''),
+    (a) => stripAcceptanceHandle(a).text,
   );
   const verify = parseTextListSection(sections.get('verify') ?? []);
   const references = parsePathEntrySection(