mandrel 1.57.0

package/.agents/scripts/git-cleanup.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/* node:coverage ignore file -- multi-phase repo-cleanup CLI; thin shell over `git` + `gh` */
+
+/**
+ * git-cleanup.js — Story #2466 thin CLI shell over the multi-phase
+ * cleanup pipeline.
+ *
+ * The pipeline lives under `lib/orchestration/git-cleanup/phases/`:
+ *
+ *   1. parse-args   — argv → normalized opts bag (`parseCleanupArgs`).
+ *   2. filters      — pure glob + protected-branch helpers.
+ *   3. git-probes   — every `gitSpawn` / `gh` subprocess wrapper plus
+ *                     small parsers (`probeMergedPr`, etc).
+ *   4. branches     — merged-branch reap (`planCleanup`,
+ *                     `executeCleanup`).
+ *   5. fast-forward — fast-forward-main phase.
+ *   6. prune        — prune-remotes phase + `parsePrunedRefs`.
+ *   7. stashes      — stash triage (`parseStashList`, `planStashes`,
+ *                     `executeStashes`, `stashRefIndex`,
+ *                     `buildAllowlistDecider`).
+ *   8. render       — operator-facing renderers + `buildJsonEnvelope`,
+ *                     `computeExitCode`.
+ *   9. cli          — interactive prompts + per-phase drivers + `main`.
+ *
+ * Public CLI surface, named exports, and exit codes are byte-identical
+ * to the pre-refactor implementation. See the original module docstring
+ * (preserved below) for the operator-facing flag + phase contract.
+ *
+ * Phases (selectable, run sequentially when no narrowing flag set):
+ *   1. fast-forward-main — `git fetch origin <base>` → `git merge --ff-only`.
+ *   2. prune-remotes     — `git fetch --prune <remote>`.
+ *   3. branches          — enumerate merged local branches via `gh pr list`
+ *                          + `git branch --merged <base>` and reap.
+ *   4. stashes           — `git stash list` → optional per-stash drops.
+ *
+ * Exit codes:
+ *   0 — clean (dry-run preview, or every active phase succeeded).
+ *   1 — at least one phase reported a failure.
+ *   2 — every active phase produced nothing to do (informational).
+ */
+
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  executeCleanup,
+  planCleanup,
+} from './lib/orchestration/git-cleanup/phases/branches.js';
+import { runCleanup } from './lib/orchestration/git-cleanup/phases/cli.js';
+import {
+  executeFastForward,
+  planFastForward,
+} from './lib/orchestration/git-cleanup/phases/fast-forward.js';
+import {
+  buildGlobFilter,
+  computeProtectedReason,
+  computeProtectedSet,
+} from './lib/orchestration/git-cleanup/phases/filters.js';
+import {
+  branchTipSha,
+  classifyLatestPr,
+  probeAllPrs,
+  probeLatestPr,
+  probeMergedPr,
+} from './lib/orchestration/git-cleanup/phases/git-probes.js';
+import { parseCleanupArgs } from './lib/orchestration/git-cleanup/phases/parse-args.js';
+import {
+  executePrune,
+  parsePrunedRefs,
+} from './lib/orchestration/git-cleanup/phases/prune.js';
+import {
+  buildJsonEnvelope,
+  computeExitCode,
+  renderDeferredLine,
+  renderDryRun,
+  renderExecutionLine,
+  renderExecutionSummary,
+  renderLatestPrSkipLine,
+  renderPruneLine,
+} from './lib/orchestration/git-cleanup/phases/render.js';
+import {
+  buildAllowlistDecider,
+  executeStashes,
+  parseStashList,
+  planStashes,
+  stashRefIndex,
+} from './lib/orchestration/git-cleanup/phases/stashes.js';
+
+// Public surface preserved for tests + `single-story-sweep.js`.
+export {
+  branchTipSha,
+  buildAllowlistDecider,
+  buildGlobFilter,
+  buildJsonEnvelope,
+  classifyLatestPr,
+  computeExitCode,
+  computeProtectedReason,
+  computeProtectedSet,
+  executeCleanup,
+  executeFastForward,
+  executePrune,
+  executeStashes,
+  parseCleanupArgs,
+  parsePrunedRefs,
+  parseStashList,
+  planCleanup,
+  planFastForward,
+  planStashes,
+  probeAllPrs,
+  probeLatestPr,
+  probeMergedPr,
+  renderDeferredLine,
+  renderDryRun,
+  renderExecutionLine,
+  renderExecutionSummary,
+  renderLatestPrSkipLine,
+  renderPruneLine,
+  stashRefIndex,
+};
+
+async function main() {
+  const { exitCode } = await runCleanup();
+  process.exit(exitCode);
+}
+
+runAsCli(import.meta.url, main, { source: 'git-cleanup' });

package/.agents/scripts/git-pr-quality-gate.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/* node:coverage ignore file -- top-level CLI gate; spawns lint/format/test and asserts exit codes — heavy mocking would assert only mock structure */
+
+/**
+ * git-pr-quality-gate.js — Lint / format / test gate for `/git-merge-pr`.
+ *
+ * `/git-merge-pr` Steps 3–4 previously hardcoded the command sequence
+ * (`npm run lint`, `npm run format:check`, `npm test`) in the workflow
+ * markdown. That coupled the .md to specific tooling names; a project that
+ * renames `lint` to `lint:ci` or swaps Biome for ESLint had to patch the
+ * skill every time.
+ *
+ * This script runs the gate and emits a structured result so the .md routes
+ * on outcome rather than re-implementing the command sequence. The three
+ * checks it runs are read from
+ * `.agentrc.json → github.branchProtection.requiredChecks` when present,
+ * falling back to the hardcoded default trio.
+ *
+ * Usage:
+ *   node .agents/scripts/git-pr-quality-gate.js [--json] [--skip <name>[,<name>]]
+ *
+ * `--skip` takes a comma-separated list of check names to bypass (useful when
+ * a flake needs a targeted rerun).
+ *
+ * Output (always JSON when --json; human-readable otherwise):
+ *   {
+ *     ok: boolean,
+ *     checks: [{ name, cmd, status, stdout, stderr, durationMs }, ...],
+ *     failed: [{ name, reason }, ...]
+ *   }
+ *
+ * Exit codes:
+ *   0 — every check passed.
+ *   1 — one or more checks failed (see `failed[]`).
+ *   2 — usage / config error.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+
+/**
+ * Default check suite when `.agentrc.json` supplies no override. Each entry:
+ *   name — short identifier surfaced in output
+ *   cmd  — argv array (no shell expansion; first element is the binary)
+ */
+export const DEFAULT_CHECKS = Object.freeze([
+  { name: 'lint', cmd: ['npm', 'run', 'lint'] },
+  { name: 'format:check', cmd: ['npm', 'run', 'format:check'] },
+  { name: 'test', cmd: ['npm', 'test'] },
+]);
+
+function resolveChecks(config) {
+  // Canonical: required checks live under `github.branchProtection.requiredChecks`.
+  const configured = config?.github?.branchProtection?.requiredChecks;
+  if (!Array.isArray(configured) || configured.length === 0) {
+    return DEFAULT_CHECKS;
+  }
+  return configured.map((c) => ({ name: c.name, cmd: c.cmd }));
+}
+
+function runCheck(check, cwd) {
+  const start = Date.now();
+  const [bin, ...args] = check.cmd;
+  const result = spawnSync(bin, args, {
+    cwd,
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 600_000,
+  });
+  const durationMs = Date.now() - start;
+  return {
+    name: check.name,
+    cmd: check.cmd.join(' '),
+    status: result.status ?? -1,
+    stdout: (result.stdout ?? '').slice(-4000),
+    stderr: (result.stderr ?? '').slice(-4000),
+    durationMs,
+  };
+}
+
+/**
+ * Pure test seam: run the supplied check suite with a caller-provided runner.
+ *
+ * @param {{
+ *   checks: Array<{ name: string, cmd: string[] }>,
+ *   cwd?: string,
+ *   skip?: Set<string>|string[],
+ *   runner?: (check: {name: string, cmd: string[]}, cwd: string) => { name, cmd, status, stdout, stderr, durationMs },
+ * }} opts
+ */
+export function runQualityGate({
+  checks,
+  cwd = PROJECT_ROOT,
+  skip,
+  runner = runCheck,
+}) {
+  const skipSet =
+    skip instanceof Set ? skip : new Set((skip ?? []).filter(Boolean));
+  const results = [];
+  for (const c of checks) {
+    if (skipSet.has(c.name)) {
+      results.push({
+        name: c.name,
+        cmd: c.cmd.join(' '),
+        status: 0,
+        stdout: '',
+        stderr: '',
+        durationMs: 0,
+        skipped: true,
+      });
+      continue;
+    }
+    results.push(runner(c, cwd));
+  }
+  const failed = results
+    .filter((r) => !r.skipped && r.status !== 0)
+    .map((r) => ({
+      name: r.name,
+      reason: `exit ${r.status} — ${(r.stderr || r.stdout || '').trim().split('\n').slice(0, 3).join(' | ')}`,
+    }));
+  return { ok: failed.length === 0, checks: results, failed };
+}
+
+/**
+ * Pure: format the per-check status line shown in the human report.
+ *
+ * @param {{ name: string, status: number, durationMs: number, skipped?: boolean }} check
+ */
+export function formatCheckLine(check) {
+  const icon = check.skipped ? '⏭' : check.status === 0 ? '✅' : '❌';
+  const suffix = check.skipped ? ' (skipped)' : ` (${check.durationMs}ms)`;
+  return `[quality-gate] ${icon} ${check.name}${suffix}`;
+}
+
+/**
+ * Pure: render the human report for a quality-gate verdict, returning info
+ * lines (always emitted) and error lines (emitted on failure).
+ *
+ * @param {{ ok: boolean, checks: Array<object>, failed: Array<{ name: string, reason: string }> }} result
+ */
+export function renderHumanReport(result) {
+  const info = result.checks.map(formatCheckLine);
+  const errors = [];
+  if (!result.ok) {
+    errors.push(
+      `[quality-gate] ❌ ${result.failed.length} check(s) failed:`,
+      ...result.failed.map((f) => `  - ${f.name}: ${f.reason}`),
+    );
+  } else {
+    info.push(`[quality-gate] ✅ All ${result.checks.length} check(s) passed.`);
+  }
+  return { info, errors };
+}
+
+/**
+ * Pure: split a comma-separated `--skip` value into a clean list of check
+ * names.
+ *
+ * @param {string|null|undefined} value
+ */
+export function parseSkipList(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/* node:coverage ignore next */
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      json: { type: 'boolean', default: false },
+      skip: { type: 'string' },
+    },
+    strict: false,
+  });
+  const config = resolveConfig();
+  const checks = resolveChecks(config);
+  const skip = parseSkipList(values.skip);
+
+  const result = runQualityGate({ checks, skip });
+
+  if (values.json === true) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (!result.ok) process.exit(1);
+    return;
+  }
+
+  const { info, errors } = renderHumanReport(result);
+  for (const line of info) Logger.info(line);
+  for (const line of errors) Logger.error(line);
+  if (!result.ok) process.exit(1);
+}
+
+// Re-export Logger so callers that dynamic-import this module can surface
+// fatal errors through the same channel as other scripts.
+export { Logger };
+
+runAsCli(import.meta.url, main, { source: 'git-pr-quality-gate' });

package/.agents/scripts/git-rebase-and-resolve.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/* node:coverage ignore file -- rebase CLI; conflict-resolution heuristics over real git state, testing would assert only the mock structure */
+
+/**
+ * git-rebase-and-resolve.js — Rebase pipeline for `/git-merge-pr` Step 2.5.
+ *
+ * `/git-merge-pr` previously embedded the rebase retry loop as prose in
+ * markdown: "rebase onto base → if conflicts, follow the template → stage and
+ * continue → force-push". That works right up until the LLM forgets one of
+ * the steps (the force-push with `--force-with-lease`, the abort on
+ * cascading conflicts, the continue after each resolved batch).
+ *
+ * This script runs the rebase, reports the outcome in structured form, and
+ * — when a conflict stops the rebase — leaves the working tree in the
+ * conflicted state so the caller can apply manual resolutions and invoke
+ * `--continue` (delegating back to git's native flow rather than trying to
+ * automate conflict merging, which is a problem for judgment not scripting).
+ *
+ * Usage:
+ *   node .agents/scripts/git-rebase-and-resolve.js --onto <base> [--head <branch>] [--continue] [--abort] [--json]
+ *
+ * Modes:
+ *   (default)     — `git fetch origin`, checkout head, `git rebase <onto>`.
+ *   --continue    — `git rebase --continue` after resolutions are staged.
+ *   --abort       — `git rebase --abort` to bail cleanly.
+ *
+ * Output (always JSON when --json, otherwise human-readable):
+ *   {
+ *     outcome: 'clean' | 'conflict' | 'aborted' | 'continued',
+ *     head, onto,
+ *     conflictedFiles: [...],
+ *     stderr: "...",
+ *   }
+ *
+ * Exit codes:
+ *   0 — clean rebase or continue that completed.
+ *   1 — conflict state (caller must resolve then invoke --continue).
+ *   2 — usage / git error.
+ */
+
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { PROJECT_ROOT } from './lib/config-resolver.js';
+import { gitSpawn } from './lib/git-utils.js';
+import { Logger } from './lib/Logger.js';
+
+function currentBranch(cwd) {
+  const res = gitSpawn(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');
+  return res.status === 0 ? res.stdout.trim() : null;
+}
+
+function listConflictedFiles(cwd) {
+  const res = gitSpawn(cwd, 'diff', '--name-only', '--diff-filter=U');
+  if (res.status !== 0) return [];
+  return res.stdout
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Perform a rebase and classify the outcome. Pure seam: callers inject a
+ * `git` runner for tests.
+ *
+ * @param {{
+ *   onto: string,
+ *   head?: string,
+ *   cwd?: string,
+ *   git?: { spawn: (cwd: string, ...args: string[]) => { status: number, stdout: string, stderr: string } },
+ * }} opts
+ */
+export function runRebase({
+  onto,
+  head,
+  cwd = PROJECT_ROOT,
+  git = { spawn: gitSpawn },
+}) {
+  if (!onto) throw new Error('[rebase] --onto is required.');
+
+  const fetch = git.spawn(cwd, 'fetch', 'origin');
+  if (fetch.status !== 0) {
+    return {
+      outcome: 'error',
+      head: head ?? null,
+      onto,
+      conflictedFiles: [],
+      stderr: fetch.stderr ?? '',
+    };
+  }
+
+  if (head) {
+    const checkout = git.spawn(cwd, 'checkout', head);
+    if (checkout.status !== 0) {
+      return {
+        outcome: 'error',
+        head,
+        onto,
+        conflictedFiles: [],
+        stderr: checkout.stderr ?? '',
+      };
+    }
+    git.spawn(cwd, 'pull', 'origin', head);
+  }
+
+  const rebase = git.spawn(cwd, 'rebase', onto);
+  if (rebase.status === 0) {
+    return {
+      outcome: 'clean',
+      head: head ?? currentBranch(cwd),
+      onto,
+      conflictedFiles: [],
+      stderr: '',
+    };
+  }
+
+  // Non-zero exit: likely conflict. Enumerate the unmerged files so the caller
+  // can route to the conflict-template procedure.
+  const conflicted = listConflictedFiles(cwd);
+  return {
+    outcome: conflicted.length > 0 ? 'conflict' : 'error',
+    head: head ?? currentBranch(cwd),
+    onto,
+    conflictedFiles: conflicted,
+    stderr: rebase.stderr ?? '',
+  };
+}
+
+export function continueRebase({
+  cwd = PROJECT_ROOT,
+  git = { spawn: gitSpawn },
+}) {
+  const res = git.spawn(cwd, 'rebase', '--continue');
+  if (res.status === 0) {
+    return { outcome: 'continued', conflictedFiles: [], stderr: '' };
+  }
+  return {
+    outcome: 'conflict',
+    conflictedFiles: listConflictedFiles(cwd),
+    stderr: res.stderr ?? '',
+  };
+}
+
+export function abortRebase({ cwd = PROJECT_ROOT, git = { spawn: gitSpawn } }) {
+  const res = git.spawn(cwd, 'rebase', '--abort');
+  return {
+    outcome: res.status === 0 ? 'aborted' : 'error',
+    stderr: res.stderr ?? '',
+  };
+}
+
+/**
+ * Pure: parse argv into the normalized rebase-action option bag.
+ *
+ * @param {string[]} argv
+ * @returns {{ onto?: string, head?: string, continueFlag: boolean, abortFlag: boolean, json: boolean }}
+ */
+export function parseRebaseArgs(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      onto: { type: 'string' },
+      head: { type: 'string' },
+      continue: { type: 'boolean', default: false },
+      abort: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    strict: false,
+  });
+  return {
+    onto: values.onto,
+    head: values.head,
+    continueFlag: values.continue === true,
+    abortFlag: values.abort === true,
+    json: values.json === true,
+  };
+}
+
+/** Pure: did the rebase end in a clean / non-failure outcome? */
+export function isCleanRebaseOutcome(outcome) {
+  return (
+    outcome === 'clean' || outcome === 'continued' || outcome === 'aborted'
+  );
+}
+
+/** Pure: render the human-facing output lines for a rebase result. */
+export function renderRebaseHumanLines(result) {
+  const lines = [`[rebase] outcome: ${result.outcome}`];
+  if (result.conflictedFiles?.length > 0) {
+    lines.push(`[rebase] conflicted files (${result.conflictedFiles.length}):`);
+    for (const f of result.conflictedFiles) lines.push(`  - ${f}`);
+  }
+  return lines;
+}
+
+/**
+ * Pure: dispatch the parsed args to the matching rebase action. Throws when
+ * the implicit-rebase path was selected without `--onto`. Exported for tests.
+ */
+export function selectRebaseAction(args) {
+  if (args.abortFlag) return { kind: 'abort' };
+  if (args.continueFlag) return { kind: 'continue' };
+  if (!args.onto) {
+    return {
+      kind: 'usage-error',
+      message:
+        'Usage: node git-rebase-and-resolve.js --onto <base> [--head <branch>] [--json]',
+    };
+  }
+  return { kind: 'rebase', onto: args.onto, head: args.head };
+}
+
+function runSelectedAction(action, cwd) {
+  if (action.kind === 'abort') return abortRebase({ cwd });
+  if (action.kind === 'continue') return continueRebase({ cwd });
+  return runRebase({ onto: action.onto, head: action.head, cwd });
+}
+
+function emitRebaseHuman(result) {
+  for (const line of renderRebaseHumanLines(result)) Logger.info(line);
+  if (result.stderr?.trim()) Logger.error(result.stderr.trim());
+}
+
+/* node:coverage ignore next */
+async function main() {
+  const args = parseRebaseArgs(process.argv.slice(2));
+  const action = selectRebaseAction(args);
+  if (action.kind === 'usage-error') throw new Error(action.message);
+  const result = runSelectedAction(action, PROJECT_ROOT);
+  if (args.json) process.stdout.write(`${JSON.stringify(result)}\n`);
+  else emitRebaseHuman(result);
+  if (!isCleanRebaseOutcome(result.outcome)) process.exit(1);
+}
+
+runAsCli(import.meta.url, main, { source: 'git-rebase-and-resolve' });