mandrel 2.65.0 → 2.66.0

package/.agents/scripts/lib/baselines/duplication-scanner.js

@@ -5,24 +5,33 @@
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { resolveDependencyVersion } from '../dependency-version.js';
 
 const DEFAULT_MIN_TOKENS = 50;
 const DEFAULT_FORMATS = Object.freeze(['javascript']);
 
 const require = createRequire(import.meta.url);
 
+/** jscpd 5 is a Rust rewrite with no Node API; only major 4 exposes one. */
+const SUPPORTED_JSCPD_MAJOR = '^4';
+
 /**
  * Lazy CJS load: jscpd's ESM entry has a broken transitive `colors/safe`
  * specifier under strict ESM resolution, and importers that never scan should
  * not pay the load.
  *
+ * No `detectClones` means an unsupported major, not a missing install.
+ *
+ * @param {NodeJS.Require} [requireFn] substitutes the module resolver
  * @returns {(opts: object) => Promise<Array<object>>}
  */
-export function resolveDetectClones() {
-  const jscpd = require('jscpd');
-  if (typeof jscpd.detectClones !== 'function') {
+export function resolveDetectClones(requireFn = require) {
+  const jscpd = requireFn('jscpd');
+  if (typeof jscpd?.detectClones !== 'function') {
+    const version = resolveDependencyVersion('jscpd', requireFn) ?? 'unknown';
     throw new Error(
-      "[Duplication] jscpd.detectClones is not available — run 'npm install'",
+      `[Duplication] jscpd ${version} exposes no detectClones Node API — ` +
+        `the duplication gate supports jscpd ${SUPPORTED_JSCPD_MAJOR}; install jscpd@${SUPPORTED_JSCPD_MAJOR}`,
     );
   }
   return jscpd.detectClones;
@@ -44,6 +53,9 @@ export function relativisePath(sourceId, cwd) {
 }
 
 /**
+ * A side with `end.line < start.line` counts nothing: its real span is
+ * unrecoverable, and widening it recorded hundreds of phantom lines.
+ *
  * @param {{ start?: { line?: number }, end?: { line?: number } }} dup
  * @returns {Array<number>} the 1-based line numbers the clone covers
  */
@@ -51,10 +63,8 @@ function cloneLineNumbers(dup) {
   const start = dup?.start?.line;
   const end = dup?.end?.line;
   if (!Number.isInteger(start) || !Number.isInteger(end)) return [];
-  const lo = Math.min(start, end);
-  const hi = Math.max(start, end);
   const lines = [];
-  for (let n = lo; n <= hi; n += 1) lines.push(n);
+  for (let n = start; n <= end; n += 1) lines.push(n);
   return lines;
 }
 

package/.agents/scripts/lib/bootstrap/project-bootstrap.js

@@ -80,6 +80,10 @@ function writeJson(p, obj, fsImpl = fs) {
   fsImpl.writeFileSync(p, `${JSON.stringify(obj, null, 2)}\n`, 'utf8');
 }
 
+function agentRootOf(ctx) {
+  return ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents');
+}
+
 /**
  * Node floor SSOT (`node:sqlite` stabilised at 22.22.1); import it, never
  * duplicate. Matches `package.json` `engines.node` (`>=22.22.1 <25`).
@@ -126,9 +130,36 @@ export function detectPackageManager(projectRoot, fsImpl = fs) {
   return detectPm(projectRoot, (p) => fsImpl.existsSync(p)) ?? 'npm';
 }
 
+/** @returns {'added'|'already-present'} */
+function ensureScript(scripts, key, command) {
+  if (scripts[key]) return 'already-present';
+  scripts[key] = command;
+  return 'added';
+}
+
+/** Append each projection independently so a partial prepare gains the other. */
+function ensurePrepareScript(scripts) {
+  const prepare = scripts.prepare;
+  if (!prepare) {
+    scripts.prepare = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
+    return 'added';
+  }
+  let next = prepare;
+  if (!next.includes('sync-claude-commands.js')) {
+    next = `${next} && ${SYNC_COMMAND}`;
+  }
+  if (!next.includes('sync-claude-agents.js')) {
+    next = `${next} && ${SYNC_AGENTS_COMMAND}`;
+  }
+  if (next === prepare) return 'already-present';
+  scripts.prepare = next;
+  return 'appended';
+}
+
 /**
  * Ensure `package.json` carries the sync/prepare/bootstrap scripts. Never
  * touches `dependencies` — framework deps arrive transitively via `mandrel`.
+ * An operator-defined `bootstrap` script always wins.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
@@ -136,62 +167,32 @@ export function detectPackageManager(projectRoot, fsImpl = fs) {
 export function ensurePackageJson(ctx) {
   const { fsImpl = fs } = ctx;
   const pkgPath = path.join(ctx.projectRoot, 'package.json');
-  const projectName = path.basename(path.resolve(ctx.projectRoot));
-  const outcomes = {
-    created: false,
-    scriptsSyncCommands: 'already-present',
-    scriptsSyncAgents: 'already-present',
-    scriptsPrepare: 'already-present',
-    scriptsBootstrap: 'already-present',
+  const existing = readJsonIfExists(pkgPath, fsImpl);
+  const pkg = existing || {
+    name: path.basename(path.resolve(ctx.projectRoot)),
+    version: '0.0.0',
+    private: true,
+    type: 'module',
   };
-  let pkg = readJsonIfExists(pkgPath, fsImpl);
-  if (!pkg) {
-    pkg = {
-      name: projectName,
-      version: '0.0.0',
-      private: true,
-      type: 'module',
-    };
-    outcomes.created = true;
-  }
   pkg.scripts = pkg.scripts ?? {};
-  if (!pkg.scripts['sync:commands']) {
-    pkg.scripts['sync:commands'] = SYNC_COMMAND;
-    outcomes.scriptsSyncCommands = 'added';
-  }
-  if (!pkg.scripts['sync:agents']) {
-    pkg.scripts['sync:agents'] = SYNC_AGENTS_COMMAND;
-    outcomes.scriptsSyncAgents = 'added';
-  }
-  const prepare = pkg.scripts.prepare;
-  if (!prepare) {
-    pkg.scripts.prepare = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
-    outcomes.scriptsPrepare = 'added';
-  } else {
-    // Append each projection independently so a partial prepare gains the other.
-    let next = prepare;
-    if (!next.includes('sync-claude-commands.js')) {
-      next = `${next} && ${SYNC_COMMAND}`;
-    }
-    if (!next.includes('sync-claude-agents.js')) {
-      next = `${next} && ${SYNC_AGENTS_COMMAND}`;
-    }
-    if (next !== prepare) {
-      pkg.scripts.prepare = next;
-      outcomes.scriptsPrepare = 'appended';
-    }
-  }
-  // An operator-defined `bootstrap` script always wins.
-  if (!pkg.scripts.bootstrap) {
-    pkg.scripts.bootstrap = BOOTSTRAP_COMMAND;
-    outcomes.scriptsBootstrap = 'added';
-  }
-  const mutated =
-    outcomes.created ||
-    outcomes.scriptsSyncCommands === 'added' ||
-    outcomes.scriptsSyncAgents === 'added' ||
-    outcomes.scriptsPrepare !== 'already-present' ||
-    outcomes.scriptsBootstrap === 'added';
+  const outcomes = {
+    created: !existing,
+    scriptsSyncCommands: ensureScript(
+      pkg.scripts,
+      'sync:commands',
+      SYNC_COMMAND,
+    ),
+    scriptsSyncAgents: ensureScript(
+      pkg.scripts,
+      'sync:agents',
+      SYNC_AGENTS_COMMAND,
+    ),
+    scriptsPrepare: ensurePrepareScript(pkg.scripts),
+    scriptsBootstrap: ensureScript(pkg.scripts, 'bootstrap', BOOTSTRAP_COMMAND),
+  };
+  const mutated = Object.values(outcomes).some(
+    (v) => v === true || v === 'added' || v === 'appended',
+  );
   if (mutated) writeJson(pkgPath, pkg, fsImpl);
   return { ...outcomes, path: pkgPath, mutated };
 }
@@ -246,10 +247,7 @@ export function ensureAgentrc(ctx) {
   if (fsImpl.existsSync(target)) {
     return { action: 'already-present', path: target };
   }
-  const starter = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
-    'starter-agentrc.json',
-  );
+  const starter = path.join(agentRootOf(ctx), 'starter-agentrc.json');
   if (!fsImpl.existsSync(starter)) {
     return { action: 'missing-starter', path: target };
   }
@@ -269,16 +267,28 @@ export function ensureAgentrc(ctx) {
   return { action: 'seeded', path: target, source: 'starter' };
 }
 
+async function loadAgentrcValidator(schemaModule) {
+  // pathToFileURL handles Windows drive letters and percent-encoding.
+  const mod = await import(pathToFileURL(schemaModule).href);
+  return mod.getAgentrcValidator();
+}
+
+function agentrcVerdict(validate, data) {
+  if (!data) return { ok: false, errors: ['.agentrc.json missing'] };
+  const ok = validate(data);
+  return { ok: !!ok, errors: ok ? [] : (validate.errors ?? []) };
+}
+
 /**
  * Validate `.agentrc.json` against the AJV schema; the caller decides whether to abort.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
  */
-export async function validateAgentrc(ctx) {
+async function validateAgentrc(ctx) {
   const { fsImpl = fs } = ctx;
   const schemaModule = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
+    agentRootOf(ctx),
     'scripts',
     'lib',
     'config-settings-schema.js',
@@ -286,16 +296,12 @@ export async function validateAgentrc(ctx) {
   if (!fsImpl.existsSync(schemaModule)) {
     return { ok: false, errors: ['config-settings-schema.js not found'] };
   }
-  // pathToFileURL handles Windows drive letters and percent-encoding.
-  const mod = await import(pathToFileURL(schemaModule).href);
-  const validate = mod.getAgentrcValidator();
+  const validate = await loadAgentrcValidator(schemaModule);
   const data = readJsonIfExists(
     path.join(ctx.projectRoot, '.agentrc.json'),
     fsImpl,
   );
-  if (!data) return { ok: false, errors: ['.agentrc.json missing'] };
-  const ok = validate(data);
-  return { ok: !!ok, errors: ok ? [] : (validate.errors ?? []) };
+  return agentrcVerdict(validate, data);
 }
 
 /**
@@ -347,12 +353,9 @@ function ensureIssueFormsPhase(ctx) {
  * @param {object} ctx
  * @param {typeof defaultSpawnSync} [ctx.spawnImpl]
  */
-export function runSyncCommands(ctx) {
+function runSyncCommands(ctx) {
   const { spawnImpl = defaultSpawnSync } = ctx;
-  const scriptsDir = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
-    'scripts',
-  );
+  const scriptsDir = path.join(agentRootOf(ctx), 'scripts');
   const projections = [
     { label: 'sync-claude-commands.js', script: 'sync-claude-commands.js' },
     { label: 'sync-claude-agents.js', script: 'sync-claude-agents.js' },
@@ -390,10 +393,7 @@ export function runSyncCommands(ctx) {
  */
 export function checkParity(ctx) {
   const { fsImpl = fs } = ctx;
-  const workflowsDir = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
-    'workflows',
-  );
+  const workflowsDir = path.join(agentRootOf(ctx), 'workflows');
   const commandsDir = path.join(ctx.projectRoot, '.claude', 'commands');
   const list = (dir) =>
     fsImpl.existsSync(dir)
@@ -437,13 +437,13 @@ export function ensureSystemPromptWiring(ctx) {
  * @param {typeof fs} [ctx.fsImpl]
  * @param {typeof defaultSpawnSync} [ctx.spawnImpl]
  */
-export function checkWindowsGitPerf(ctx) {
+function checkWindowsGitPerf(ctx) {
   const { fsImpl = fs, spawnImpl = defaultSpawnSync } = ctx;
-  if (os.platform() !== 'win32') {
+  if ((ctx.platform ?? os.platform()) !== 'win32') {
     return { platform: process.platform, skipped: true };
   }
   const script = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
+    agentRootOf(ctx),
     'scripts',
     'check-windows-git-perf.js',
   );

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

@@ -24,13 +24,26 @@ const SUPPORTED_FLAGS = Object.freeze({
 
 const FLAG_NAMES = Object.keys(SUPPORTED_FLAGS);
 
-const SUPPORTED_EXTRAS_TYPES = new Set([
-  'string',
-  'boolean',
-  'ticket',
-  'integer',
-  'string-multi',
-]);
+const isNullish = (v) => v === null || v === undefined;
+
+/** Per-type rules shared by built-in and extra flags. */
+const FLAG_TYPES = Object.freeze({
+  string: {
+    normalise: (v, orDefault) =>
+      typeof v === 'string' && v.length > 0 ? v : orDefault(null),
+    isAbsent: (v) => isNullish(v) || v === '',
+  },
+  boolean: { normalise: (v) => v === true, isAbsent: (v) => !v },
+  ticket: { normalise: (v) => parseTicketId(v), isAbsent: isNullish },
+  integer: {
+    normalise: (v, orDefault) => (v === undefined ? orDefault(undefined) : v),
+    isAbsent: (v) => v === undefined || Number.isNaN(v),
+  },
+  'string-multi': {
+    normalise: (v, orDefault) => (Array.isArray(v) ? v : orDefault([])),
+    isAbsent: (v) => !Array.isArray(v) || v.length === 0,
+  },
+});
 
 function camelCase(name) {
   return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
@@ -50,16 +63,33 @@ function normaliseCallSignature(opts) {
   return { argv: argv ?? [], schema, extras };
 }
 
-function buildDefineFlagsSpec(extras) {
+function flagEntries(schema, extras) {
+  const entries = Object.entries(SUPPORTED_FLAGS).map(
+    ([flag, { key, type }]) => ({
+      flag,
+      key,
+      type,
+      def: {},
+      required: schema?.[flag]?.required === true,
+    }),
+  );
+  for (const [flag, def] of Object.entries(extras ?? {})) {
+    entries.push({
+      flag,
+      key: def.alias ?? camelCase(flag),
+      type: def.type,
+      def,
+      required: def.required === true,
+    });
+  }
+  return entries;
+}
+
+function buildDefineFlagsSpec(entries) {
   const spec = {};
-  for (const [flag, { key, type }] of Object.entries(SUPPORTED_FLAGS)) {
+  for (const { flag, key, type, def } of entries) {
     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;
+    if ('default' in def) spec[flag].default = def.default;
   }
   return spec;
 }
@@ -119,10 +149,10 @@ function validateExtras(extras) {
         `parseStandardCliArgs: extras["${flag}"] must be an object`,
       );
     }
-    if (!SUPPORTED_EXTRAS_TYPES.has(def.type)) {
+    if (!Object.hasOwn(FLAG_TYPES, def.type)) {
       const err = new Error(
         `parseStandardCliArgs: extras["${flag}"].type "${def.type}" is unsupported. ` +
-          `Supported: ${[...SUPPORTED_EXTRAS_TYPES].join(', ')}.`,
+          `Supported: ${Object.keys(FLAG_TYPES).join(', ')}.`,
       );
       err.code = 'UNKNOWN_EXTRAS_TYPE';
       throw err;
@@ -130,15 +160,6 @@ function validateExtras(extras) {
   }
 }
 
-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}`,
@@ -148,56 +169,19 @@ function throwMissing(flag) {
   throw err;
 }
 
-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);
-  }
-}
-
-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);
+function normaliseValues(raw, entries) {
+  const out = {};
+  for (const { key, type, def } of entries) {
+    const orDefault = (empty) => ('default' in def ? def.default : empty);
+    out[key] = FLAG_TYPES[type].normalise(raw[key], orDefault);
   }
+  return out;
 }
 
-/** Absent strings become `null` and booleans 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;
+function enforceRequired(values, entries) {
+  for (const { flag, key, type, required } of entries) {
+    if (required && FLAG_TYPES[type].isAbsent(values[key])) throwMissing(flag);
   }
-  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;
 }
 
 /**
@@ -222,13 +206,13 @@ export function parseStandardCliArgs(opts = {}) {
     err.flag = unknown;
     throw err;
   }
+  const entries = flagEntries(schema, extras);
   const { values: raw, positionals } = defineFlags(
-    buildDefineFlagsSpec(extras),
+    buildDefineFlagsSpec(entries),
     argv,
   );
-  const values = normaliseValues(raw, extras);
-  enforceRequired(values, schema);
-  enforceExtrasRequired(values, extras);
+  const values = normaliseValues(raw, entries);
+  enforceRequired(values, entries);
   return { values, positionals };
 }
 

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

@@ -133,6 +133,30 @@ function tolerantOverrideReviewBlock(value) {
   }
 }
 
+/**
+ * Best-effort: absent or junk is `null` plus a warning, never a throw.
+ *
+ * @param {unknown} value
+ * @returns {{ tokens: number|null, warning: string|null }}
+ */
+export function parseWorkerTokens(value) {
+  if (value == null) {
+    return {
+      tokens: null,
+      warning:
+        '--worker-tokens not supplied; telemetry.workerTokens records null.',
+    };
+  }
+  const raw = String(value).trim();
+  if (/^\d+$/.test(raw) && Number.isSafeInteger(Number(raw))) {
+    return { tokens: Number(raw), warning: null };
+  }
+  return {
+    tokens: null,
+    warning: `--worker-tokens must be a non-negative integer (got ${JSON.stringify(value)}); telemetry.workerTokens records null.`,
+  };
+}
+
 /**
  * Throws when a validating flag parser rejects a value; error handlers use
  * {@link parseSprintArgsTolerant} instead of re-calling this.
@@ -164,6 +188,7 @@ export function parseSprintArgs(
       'merge-watch-mode': { type: 'string' },
       'rerun-advisory': { type: 'string' },
       'override-review-block': { type: 'string' },
+      'worker-tokens': { type: 'string' },
       executor: { type: 'string' },
       cwd: { type: 'string' },
       'recut-of': { type: 'string' },
@@ -194,6 +219,7 @@ export function parseSprintArgs(
     overrideReviewBlock: tolerant
       ? tolerantOverrideReviewBlock(values['override-review-block'])
       : parseOverrideReviewBlock(values['override-review-block']),
+    workerTokens: values['worker-tokens'],
     executor: values.executor ?? null,
     cwd:
       (typeof values.cwd === 'string' && values.cwd.trim()) ||

package/.agents/scripts/lib/config/gates/shared.js

@@ -23,7 +23,7 @@ export const LIST_OR_EXTENDER_OF_STRINGS = {
   ],
 };
 
-export const TOLERANCE_SCHEMA = {
+const TOLERANCE_SCHEMA = {
   type: 'object',
   description:
     'How much a rollup may drift from the committed baseline before the gate reports a regression.',
@@ -47,7 +47,7 @@ export const TOLERANCE_SCHEMA = {
 /**
  * `"*"` is optional: the resolver injects the framework default when absent.
  */
-export const FLOORS_SCHEMA = {
+const FLOORS_SCHEMA = {
   type: 'object',
   description:
     'Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.',
@@ -57,7 +57,7 @@ export const FLOORS_SCHEMA = {
   },
 };
 
-export const COMPONENTS_SCHEMA = {
+const COMPONENTS_SCHEMA = {
   type: 'object',
   description:
     'Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer.',