mandrel 1.57.0

package/.agents/scripts/lib/git-utils.js

@@ -0,0 +1,363 @@
+/**
+ * git-utils.js — Shared Git Shell Utilities
+ *
+ * Centralizes all Git subprocess invocations for the orchestration
+ * engine, eliminating duplicated wrappers across the codebase.
+ *
+ * Two flavours are provided. Choose based on whether a non-zero git exit
+ * code represents a bug (use `gitSync`) or a recoverable runtime state
+ * (use `gitSpawn`):
+ *
+ *   - `gitSync(cwd, ...args)`  — throws on non-zero exit; returns trimmed
+ *     stdout. Use when the operation must succeed for the caller to
+ *     proceed (e.g. `rev-parse HEAD`, `merge-base --is-ancestor` inside a
+ *     critical-path check). A non-zero exit is treated as a bug or a
+ *     corrupted repo state, and the throw propagates to the caller's
+ *     existing error path.
+ *
+ *   - `gitSpawn(cwd, ...args)` — never throws; returns a {@link GitResult}
+ *     object. Use when the caller needs to inspect or recover from the
+ *     non-zero case (e.g. `merge-base --is-ancestor` as a boolean check,
+ *     `branch -D` where "no such branch" is acceptable, fetch/push retry
+ *     loops where the caller decides whether to retry on stderr content).
+ *
+ * The two functions are intentional siblings — they share argument shape so
+ * either can be substituted at a call site by changing the import. Do not
+ * unify into a single `git({ throwOnNonZero })` until the call-site split
+ * shows roughly even use of each contract.
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+
+/**
+ * Result of a `gitSpawn` invocation. Field semantics match `child_process.spawnSync`
+ * with two normalisations: `status` is coerced to `1` when null (e.g. when
+ * the child terminated by signal), and stdout/stderr are trimmed.
+ *
+ * @typedef {object} GitResult
+ * @property {number} status - Process exit code (0 = success).
+ * @property {string} stdout - Trimmed stdout.
+ * @property {string} stderr - Trimmed stderr.
+ */
+
+let _execFileSync = execFileSync;
+let _spawnSync = spawnSync;
+
+/**
+ * Build a child-process env that drops every `GIT_*` variable inherited from
+ * the parent. When this module's helpers run inside a git hook (e.g. husky
+ * pre-push) the parent git invocation exports GIT_DIR / GIT_WORK_TREE /
+ * GIT_INDEX_FILE / GIT_PREFIX / GIT_COMMON_DIR / etc. Those env vars
+ * override the explicit `cwd` we pass, so a `gitSync(tmpdir, 'init')` ends
+ * up operating on the parent worktree's `.git` rather than `tmpdir`. Tests
+ * that spin up real git fixtures break reproducibly under that shape.
+ *
+ * Stripping every `GIT_*` is broader than strictly necessary but cheap and
+ * impossible to drift out of sync with future git releases. Author/committer
+ * identity is restored via per-call `env:` overrides where required.
+ */
+function cleanGitEnv() {
+  return Object.fromEntries(
+    Object.entries(process.env).filter(([k]) => !k.startsWith('GIT_')),
+  );
+}
+
+/**
+ * Override git runners. Testing-only seam — not part of the stable API.
+ *
+ * Production code must not call this. The double-underscore prefix is the
+ * contract: `__setGitRunners` exists so the test suite can inject mock
+ * child-process runners without requiring a broader DI refactor of every
+ * `gitSync`/`gitSpawn` call site. If more injection points become needed,
+ * replace this seam with a proper `createGitRunner({exec, spawn})` factory
+ * and thread it through the module graph.
+ *
+ * @param {typeof execFileSync} exec  - Mock for `execFileSync`.
+ * @param {typeof spawnSync}    spawn - Mock for `spawnSync`.
+ */
+export function __setGitRunners(exec, spawn) {
+  _execFileSync = exec;
+  _spawnSync = spawn;
+}
+
+/**
+ * Run a git command synchronously, returning trimmed stdout.
+ * Throws an Error if the command exits with a non-zero code.
+ *
+ * @param {string}   cwd  - Working directory for the git process.
+ * @param {...string} args - Git sub-command and arguments.
+ * @returns {string} Trimmed stdout text.
+ */
+export function gitSync(cwd, ...args) {
+  return _execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    shell: false,
+    env: cleanGitEnv(),
+  }).trim();
+}
+
+/**
+ * Run a git command synchronously, returning a result object.
+ * Never throws — callers must inspect `status` to detect failure.
+ *
+ * @param {string}   cwd  - Working directory for the git process.
+ * @param {...string} args - Git sub-command and arguments.
+ * @returns {GitResult}
+ */
+export function gitSpawn(cwd, ...args) {
+  const result = _spawnSync('git', args, {
+    cwd,
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    shell: false,
+    env: cleanGitEnv(),
+  });
+  return {
+    status: result.status ?? 1,
+    stdout: (result.stdout ?? '').trim(),
+    stderr: (result.stderr ?? '').trim(),
+  };
+}
+
+/**
+ * Build a git interface closed over injected child-process runners. Preferred
+ * seam for callers that want explicit injection without touching the
+ * module-global `__setGitRunners` state (which is a test-only override that
+ * leaks between suites). The returned object has the same shape as this
+ * module's namespace exports (`gitSync`, `gitSpawn`, `gitFetchWithRetry`,
+ * `gitPullWithRetry`) so it is drop-in as a `ctx.git` replacement.
+ *
+ * @param {object} [deps]
+ * @param {typeof execFileSync} [deps.exec]   - Defaults to real `execFileSync`.
+ * @param {typeof spawnSync}    [deps.spawn]  - Defaults to real `spawnSync`.
+ * @param {(ms: number) => Promise<void>} [deps.sleep] - Retry backoff sleep.
+ * @param {number} [deps.jitter] - Jitter factor for retry backoff.
+ */
+export function createGitInterface(deps = {}) {
+  const exec = deps.exec ?? execFileSync;
+  const spawn = deps.spawn ?? spawnSync;
+  const sleep =
+    deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const jitterFactor = deps.jitter ?? 0.5;
+
+  const gitSync = (cwd, ...args) =>
+    exec('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: false,
+      env: cleanGitEnv(),
+    }).trim();
+
+  const gitSpawn = (cwd, ...args) => {
+    const result = spawn('git', args, {
+      cwd,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      shell: false,
+      env: cleanGitEnv(),
+    });
+    return {
+      status: result.status ?? 1,
+      stdout: (result.stdout ?? '').trim(),
+      stderr: (result.stderr ?? '').trim(),
+    };
+  };
+
+  async function runWithRetry(leadingArgs, cwd, args) {
+    const backoff = [250, 500, 1000];
+    let attempt = 0;
+    let last;
+    for (;;) {
+      attempt++;
+      last = gitSpawn(cwd, ...leadingArgs, ...args);
+      if (last.status === 0) return { ...last, attempts: attempt };
+      if (!isPackedRefsContention(last.stderr))
+        return { ...last, attempts: attempt };
+      if (attempt > backoff.length) return { ...last, attempts: attempt };
+      const base = backoff[attempt - 1];
+      const jitter = Math.floor(Math.random() * base * jitterFactor);
+      await sleep(base + jitter);
+    }
+  }
+
+  return {
+    gitSync,
+    gitSpawn,
+    gitFetchWithRetry: (cwd, ...args) => runWithRetry(['fetch'], cwd, args),
+    gitPullWithRetry: (cwd, ...args) =>
+      runWithRetry(['pull', '--rebase'], cwd, args),
+  };
+}
+
+/**
+ * Known lock-contention error signatures that occur when two worktrees
+ * fetch concurrently against the same repo. Matching any of these is the
+ * only condition under which `gitFetchWithRetry` will re-attempt —
+ * unrelated fetch failures surface immediately.
+ */
+const PACKED_REFS_CONTENTION_PATTERNS = [
+  /packed-refs\.lock/i,
+  /cannot lock ref/i,
+  /Unable to create '.*\.lock'/i,
+  /another git process seems to be running/i,
+];
+
+function isPackedRefsContention(stderr) {
+  if (!stderr) return false;
+  return PACKED_REFS_CONTENTION_PATTERNS.some((p) => p.test(stderr));
+}
+
+/**
+ * Sleep helper for retry backoff. Overridable via `__setSleep` so tests
+ * can skip real wall-clock delays without relying on node:test timer mocks.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+let _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+let _jitterFactor = 0.5;
+
+/**
+ * Test-only seam: replace the sleep implementation used by
+ * `gitFetchWithRetry` to avoid real backoff in unit tests.
+ * @param {(ms: number) => Promise<void>} fn
+ * @param {{ jitter?: number }} [opts] - Override jitter factor (default: 0 for mocks).
+ */
+export function __setSleep(fn, opts = {}) {
+  _sleep = fn;
+  _jitterFactor = opts.jitter ?? 0;
+}
+
+/**
+ * Run `git fetch …` with a bounded retry loop that only triggers on known
+ * packed-refs lock-contention signatures. Non-contention failures surface
+ * immediately (no retry). Success short-circuits the loop.
+ *
+ * Backoff schedule: 250ms, 500ms, 1000ms (3 retries → 4 attempts total).
+ * Deliberately no global lock — a mutex would erase the parallelism the
+ * worktree-isolation model is designed to enable.
+ *
+ * @param {string} cwd
+ * @param {...string} args - Arguments after `fetch` (e.g. `'origin'`).
+ * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
+ */
+export async function gitFetchWithRetry(cwd, ...args) {
+  const backoff = [250, 500, 1000];
+  let attempt = 0;
+  let last;
+  for (;;) {
+    attempt++;
+    last = gitSpawn(cwd, 'fetch', ...args);
+    if (last.status === 0) return { ...last, attempts: attempt };
+    if (!isPackedRefsContention(last.stderr))
+      return { ...last, attempts: attempt };
+    if (attempt > backoff.length) return { ...last, attempts: attempt };
+    const base = backoff[attempt - 1];
+    const jitter = Math.floor(Math.random() * base * _jitterFactor);
+    await _sleep(base + jitter);
+  }
+}
+
+/**
+ * Run `git pull --rebase …` with the same bounded retry loop as
+ * `gitFetchWithRetry`. Packed-refs contention can occur during pulls
+ * just as during fetches — particularly in multi-worktree setups.
+ *
+ * @param {string} cwd
+ * @param {...string} args - Arguments after `pull --rebase` (e.g. `'origin', 'main'`).
+ * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
+ */
+export async function gitPullWithRetry(cwd, ...args) {
+  const backoff = [250, 500, 1000];
+  let attempt = 0;
+  let last;
+  for (;;) {
+    attempt++;
+    last = gitSpawn(cwd, 'pull', '--rebase', ...args);
+    if (last.status === 0) return { ...last, attempts: attempt };
+    if (!isPackedRefsContention(last.stderr))
+      return { ...last, attempts: attempt };
+    if (attempt > backoff.length) return { ...last, attempts: attempt };
+    const base = backoff[attempt - 1];
+    const jitter = Math.floor(Math.random() * base * _jitterFactor);
+    await _sleep(base + jitter);
+  }
+}
+
+/**
+ * Resolves the canonical branch name for an Epic.
+ * v5 Standard: epic/[EPIC_ID]
+ * @param {string|number} epicId
+ * @returns {string}
+ */
+export function getEpicBranch(epicId) {
+  const id = typeof epicId === 'number' ? epicId : Number.parseInt(epicId, 10);
+  if (!Number.isFinite(id) || id <= 0) {
+    throw new Error(`getEpicBranch: invalid epicId: ${epicId}`);
+  }
+  return `epic/${id}`;
+}
+
+/**
+ * Sanitize a string into a URL/branch-safe slug.
+ * Lowercases, replaces non-alphanumeric characters with hyphens,
+ * collapses multiple hyphens, and trims leading/trailing hyphens.
+ *
+ * @param {string} text - Raw text to slugify.
+ * @returns {string} Sanitized slug.
+ */
+export function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * Resolves the canonical branch name for a Story.
+ * v5 Standard: story-[STORY_ID]
+ * @param {string|number} _epicId - Unused; retained for back-compat call sites.
+ * @param {string|number} storyId
+ * @returns {string}
+ */
+export function getStoryBranch(_epicId, storyId) {
+  const id =
+    typeof storyId === 'number' ? storyId : Number.parseInt(storyId, 10);
+  if (!Number.isFinite(id) || id <= 0) {
+    throw new Error(`getStoryBranch: invalid storyId: ${storyId}`);
+  }
+  return `story-${id}`;
+}
+
+/**
+ * Canonical `story-<id>` branch name matcher. Single source of truth for the
+ * Story-branch shape — `parseStoryBranch` and `isStoryBranch` both close over
+ * this so call sites never re-author the regex inline.
+ */
+const STORY_BRANCH_RE = /^story-(\d+)$/;
+
+/**
+ * Parse a canonical Story branch name into its numeric Story ID.
+ *
+ * @param {string} name - Branch name to inspect (e.g. `story-3334`).
+ * @returns {number|null} The Story ID when `name` matches `story-<id>`,
+ *   otherwise `null`.
+ */
+export function parseStoryBranch(name) {
+  if (typeof name !== 'string') return null;
+  const match = STORY_BRANCH_RE.exec(name);
+  return match ? Number.parseInt(match[1], 10) : null;
+}
+
+/**
+ * Predicate: is `name` a canonical `story-<id>` branch name?
+ *
+ * @param {string} name - Branch name to test.
+ * @returns {boolean}
+ */
+export function isStoryBranch(name) {
+  return parseStoryBranch(name) !== null;
+}

package/.agents/scripts/lib/github-url.js

@@ -0,0 +1,29 @@
+// .agents/scripts/lib/github-url.js
+/**
+ * Shared GitHub URL utilities. Consolidates the `parsePrNumberFromUrl` helper
+ * that was triplicated across `finalizer.js`, `watcher.js`, and
+ * `code-review.js`, each with a subtly different regex. Story #3649.
+ */
+
+/**
+ * Extract the PR number from a GitHub PR URL.
+ *
+ * Accepts any URL whose path contains `/pull/<digits>` — the fragment
+ * (`#diff-…`), query string (`?diff=split`), and trailing slash are all
+ * ignored. Returns `null` when the URL is not a string, does not contain
+ * a `/pull/` segment, or when the parsed integer is ≤ 0.
+ *
+ * This is the canonical implementation; the inline copies in `finalizer.js`,
+ * `watcher.js`, and `code-review.js` have been deleted in favour of this
+ * function.
+ *
+ * @param {string|null|undefined} prUrl
+ * @returns {number|null}
+ */
+export function parsePrNumberFromUrl(prUrl) {
+  if (typeof prUrl !== 'string') return null;
+  const m = prUrl.match(/\/pull\/(\d+)(?:[/?#]|$)/);
+  if (!m) return null;
+  const n = Number.parseInt(m[1], 10);
+  return Number.isInteger(n) && n > 0 ? n : null;
+}

package/.agents/scripts/lib/install-cmd-parser.js

@@ -0,0 +1,51 @@
+/**
+ * Tokenize + spawn the operator-supplied install command in argv form
+ * (shell:true is only used on Windows because well-known package managers
+ * ship as `.cmd` shims and Node 18.20+/20.10+/22+ refuses to spawn them
+ * with shell:false under CVE-2024-27980). Tokenization removes the
+ * single-string injection vector — args are escaped individually even
+ * when shell:true is required for binary resolution.
+ *
+ * Whitespace tokenization (no quote handling) is deliberate: the input
+ * contract is a simple `binary arg arg …` form. Operators that need
+ * quoted args can pass a `runInstall` override directly.
+ */
+
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
+
+/**
+ * @param {string} installCmd
+ * @returns {{ bin: string, args: string[], shell: boolean }}
+ */
+export function parseInstallCmd(installCmd) {
+  const tokens = String(installCmd ?? '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  if (tokens.length === 0) {
+    throw new RangeError(
+      'parseInstallCmd: install command must contain at least one token',
+    );
+  }
+  const [bin, ...args] = tokens;
+  return { bin, args, shell: process.platform === 'win32' };
+}
+
+/**
+ * Default runInstall implementation. Tokenizes `installCmd`, then spawns
+ * synchronously with the correct shell flag per platform.
+ *
+ * @param {string} installCmd
+ * @param {string} cwd
+ * @param {{ spawnSync?: typeof defaultSpawnSync }} [deps] — test seam
+ * @returns {{ status: number, stderr: string }}
+ */
+export function runInstallCommand(installCmd, cwd, deps = {}) {
+  const spawnSync = deps.spawnSync ?? defaultSpawnSync;
+  const { bin, args, shell } = parseInstallCmd(installCmd);
+  const r = spawnSync(bin, args, { cwd, stdio: 'inherit', shell });
+  return {
+    status: r.status ?? 1,
+    stderr: r.stderr ? String(r.stderr) : '',
+  };
+}

package/.agents/scripts/lib/issue-link-parser.js

@@ -0,0 +1,74 @@
+/**
+ * Parse PRD / Tech-Spec / Acceptance-Spec references from a GitHub epic body.
+ * Extracted from providers/github.js so link-parsing is not mixed with HTTP
+ * transport.
+ *
+ * Expected markdown conventions in an epic body (case-insensitive, tolerant
+ * of the `- [ ]` / `- [x]` checkbox prefix that `epic-plan-spec.js` emits in
+ * the `## Planning Artifacts` section):
+ *   - "PRD: #42"  or  "prd #42"
+ *   - "Tech Spec: #43"  /  "Technical Spec: #43"  /  "tech-spec: #43"
+ *   - "Acceptance Spec: #44"  /  "acceptance-spec: #44"  /  "accept spec: #44"
+ *
+ * Story #2091 added the `acceptanceSpec` slot so the
+ * `closePlanningArtifacts()` cascade in `epic-deliver-finalize.js` can close
+ * the `context::acceptance-spec` ticket Epic #2001 introduces alongside the
+ * existing PRD / Tech-Spec pair.
+ *
+ * Story #3848: regexes are now scoped to the `## Planning Artifacts` section
+ * only. Prose elsewhere in the body (e.g. bundled-follow-up notes that
+ * mention a foreign Epic's spec ticket by number) can no longer collide with
+ * the machine-managed list items.
+ */
+
+const PRD_RE = /(?:PRD|prd)[:\s]+#(\d+)/;
+const TECH_SPEC_RE = /(?:Tech Spec|tech.?spec|technical.?spec)[:\s]+#(\d+)/i;
+const ACCEPTANCE_SPEC_RE =
+  /(?:Acceptance Spec|acceptance.?spec|accept.?spec)[:\s]+#(\d+)/i;
+
+/**
+ * Extract the `## Planning Artifacts` section text from an Epic body.
+ * Returns the slice from just after the heading line to the next `##`-level
+ * heading (exclusive), or to end-of-string when no following heading is
+ * present. Returns an empty string when the section is absent.
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+function extractPlanningArtifactsSection(body) {
+  // Step 1: locate the heading.
+  const startMatch = body.match(/^##\s+Planning Artifacts[^\n]*/m);
+  if (!startMatch) return '';
+  // Step 2: slice from just after the heading to the next ## heading (or EOB).
+  const afterHeading = body.slice(startMatch.index + startMatch[0].length);
+  const nextHeadingMatch = afterHeading.match(/\n##\s/);
+  return nextHeadingMatch
+    ? afterHeading.slice(0, nextHeadingMatch.index)
+    : afterHeading;
+}
+
+/**
+ * @param {string|null|undefined} body
+ * @returns {{ prd: number|null, techSpec: number|null, acceptanceSpec: number|null }}
+ */
+export function parseLinkedIssues(body) {
+  const result = { prd: null, techSpec: null, acceptanceSpec: null };
+  if (typeof body !== 'string' || body.length === 0) return result;
+
+  // Scope all regex matching to the canonical Planning Artifacts section so
+  // prose references elsewhere in the body do not shadow the machine-managed
+  // list items. When the section is absent every slot stays null — the caller
+  // (plan-epic.js) treats null as "not yet linked" and creates fresh tickets.
+  const section = extractPlanningArtifactsSection(body);
+  if (section.length === 0) return result;
+
+  const prdMatch = section.match(PRD_RE);
+  if (prdMatch) result.prd = Number.parseInt(prdMatch[1], 10);
+  const specMatch = section.match(TECH_SPEC_RE);
+  if (specMatch) result.techSpec = Number.parseInt(specMatch[1], 10);
+  const acceptanceMatch = section.match(ACCEPTANCE_SPEC_RE);
+  if (acceptanceMatch) {
+    result.acceptanceSpec = Number.parseInt(acceptanceMatch[1], 10);
+  }
+  return result;
+}

package/.agents/scripts/lib/json-utils.js

@@ -0,0 +1,60 @@
+/**
+ * json-utils.js — shared JSON-shape helpers.
+ *
+ * Hoisted out of five callers (`lib/baselines/writer.js`,
+ * `lib/config/defaults.js`, `lib/observability/baseline-refresh-rate.js`,
+ * `lib/observability/perf-aggregator.js`, `lib/signals/schema.js`) which
+ * shipped functionally-equivalent copies of these predicates. See Story
+ * #2464.
+ *
+ * The helpers are scoped to JSON-shaped data — numbers, strings, booleans,
+ * null, arrays, and plain objects. They do not handle Dates, Maps, Sets,
+ * RegExps, or class instances; callers either JSON-roundtrip their inputs
+ * or only ever pass JSON-equivalent values (the on-disk baseline writer
+ * and the config defaults module both fall in the second bucket).
+ */
+
+/**
+ * Return true when `v` is a plain object (not null, not an array). Used
+ * by readers and aggregators to defensively pre-flight record shapes.
+ *
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+export function isObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * Structural deep-equality for JSON-shaped data. Object key order is
+ * ignored. Array order is significant. NaN compares unequal (matches
+ * `===` semantics; callers must not pass NaN).
+ *
+ * @param {unknown} a
+ * @param {unknown} b
+ * @returns {boolean}
+ */
+export function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return a === b;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== 'object') return false;
+  const aArr = Array.isArray(a);
+  const bArr = Array.isArray(b);
+  if (aArr !== bArr) return false;
+  if (aArr) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i += 1) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const k of aKeys) {
+    if (!Object.hasOwn(b, k)) return false;
+    if (!deepEqual(a[k], b[k])) return false;
+  }
+  return true;
+}