mandrel 1.91.0 → 1.93.0

package/.agents/scripts/check-loop-units.js

@@ -1,204 +0,0 @@
-/**
- * CLI: loop-unit lint gate (Story #4288, Epic #4284).
- *
- * Validates every loop-unit markdown file under `.agents/workflows/loops/`
- * against `.agents/schemas/loop-unit.schema.json` via
- * `lib/loop-units/validate-loop-unit.js`. An absent or empty loops
- * directory is a **clean pass** (exit 0) — the gate only fails when a unit
- * file is present and invalid.
- *
- * On any invalid (or structurally unparseable) unit the CLI prints a
- * message naming the offending file and the missing/invalid field, then
- * exits non-zero. This is wired into `npm run lint` so a malformed loop
- * unit fails the lint gate.
- *
- * Flags:
- *   --dir <path>  override the loops directory (default
- *                 `.agents/workflows/loops`, resolved from cwd)
- *   --json        write a structured envelope to stdout instead of the
- *                 human-readable preview
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-import { runAsCli } from './lib/cli-utils.js';
-import {
-  LoopUnitParseError,
-  validateLoopUnit,
-} from './lib/loop-units/validate-loop-unit.js';
-
-export const DEFAULT_LOOPS_DIR = path.join('.agents', 'workflows', 'loops');
-
-/**
- * Parse argv for `--dir <path>` and `--json`. Exported so tests can pin
- * the parser.
- *
- * @param {string[]} argv
- * @returns {{ dir: string | null, json: boolean }}
- */
-export function parseArgv(argv = []) {
-  let dir = null;
-  let json = false;
-  for (let i = 0; i < argv.length; i += 1) {
-    const a = argv[i];
-    if (a === '--dir') {
-      const next = argv[i + 1];
-      if (next && !next.startsWith('--')) {
-        dir = next;
-        i += 1;
-      }
-    } else if (a === '--json') {
-      json = true;
-    }
-  }
-  return { dir, json };
-}
-
-/**
- * `README.md` (any case) under the loops directory is namespace
- * documentation, not a loop unit — it carries no `loop:` frontmatter and is
- * not projected as a `/loops:` command (see `sync-claude-commands.js`). It is
- * excluded from the loop-unit collector so the lint gate never flags the
- * directory's own README as a malformed unit.
- *
- * @param {string} name a directory-entry basename
- * @returns {boolean}
- */
-export function isLoopUnitFile(name) {
-  return name.endsWith('.md') && name.toLowerCase() !== 'readme.md';
-}
-
-/**
- * Collect `*.md` loop-unit files directly under `dir`, sorted. Returns an
- * empty array when the directory is absent (the clean-pass case). The
- * directory's `README.md` is excluded — it is namespace documentation, not a
- * unit (see `isLoopUnitFile`).
- *
- * @param {string} dir absolute path
- * @returns {string[]} absolute paths
- */
-export function collectLoopUnitFiles(dir) {
-  let entries;
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((e) => e.isFile() && isLoopUnitFile(e.name))
-    .map((e) => path.join(dir, e.name))
-    .sort();
-}
-
-/**
- * Validate every loop unit under `dir`. Returns the per-file results and a
- * roll-up `failures` array carrying `{ file, issues }` for each invalid or
- * unparseable unit.
- *
- * @param {string} dir absolute path
- * @param {{ schemaPath?: string }} [opts]
- * @returns {{ files: string[], failures: Array<{ file: string, issues: Array<{path:string,message:string}> }> }}
- */
-export function checkLoopUnits(dir, opts = {}) {
-  const files = collectLoopUnitFiles(dir);
-  const failures = [];
-  for (const file of files) {
-    try {
-      const { valid, issues } = validateLoopUnit(file, opts);
-      if (!valid) failures.push({ file, issues });
-    } catch (err) {
-      if (err instanceof LoopUnitParseError) {
-        failures.push({ file, issues: [{ path: '/', message: err.reason }] });
-      } else {
-        throw err;
-      }
-    }
-  }
-  return { files, failures };
-}
-
-/**
- * Render the human-readable report. Each failure lists the offending file
- * and one line per issue naming the field path and message.
- *
- * @param {{ files: string[], failures: Array<{ file: string, issues: Array<{path:string,message:string}> }> }} result
- * @returns {string}
- */
-export function renderReport({ files, failures }) {
-  const lines = [];
-  if (files.length === 0) {
-    lines.push('[check-loop-units] no loop units found (ok)');
-    return lines.join('\n');
-  }
-  for (const { file, issues } of failures) {
-    lines.push(`✖ ${file}`);
-    for (const issue of issues) {
-      lines.push(`    ${issue.path}: ${issue.message}`);
-    }
-  }
-  const tag = failures.length > 0 ? '(gate fail)' : '(ok)';
-  lines.push(
-    `[check-loop-units] checked=${files.length} invalid=${failures.length} ${tag}`,
-  );
-  return lines.join('\n');
-}
-
-/**
- * Top-level CLI entry. Exported so tests can drive the full pipeline
- * against a tmpdir fixture directory.
- *
- * @param {{
- *   argv?: string[],
- *   cwd?: string,
- *   stdout?: { write: (s: string) => void },
- *   stderr?: { write: (s: string) => void },
- * }} [opts]
- * @returns {Promise<number>} 0 = clean; 1 = at least one invalid unit
- */
-export async function runCli({
-  argv = process.argv.slice(2),
-  cwd = process.cwd(),
-  stdout = process.stdout,
-  stderr = process.stderr,
-} = {}) {
-  const { dir, json } = parseArgv(argv);
-  const loopsDir = path.resolve(cwd, dir ?? DEFAULT_LOOPS_DIR);
-  const result = checkLoopUnits(loopsDir);
-  const exitCode = result.failures.length > 0 ? 1 : 0;
-
-  if (json) {
-    stdout.write(
-      `${JSON.stringify(
-        {
-          kind: 'loop-units-report',
-          dir: loopsDir,
-          checked: result.files.length,
-          failures: result.failures,
-          exitCode,
-        },
-        null,
-        2,
-      )}\n`,
-    );
-  } else {
-    const report = renderReport(result);
-    if (exitCode === 0) {
-      stdout.write(`${report}\n`);
-    } else {
-      stderr.write(`${report}\n`);
-    }
-  }
-
-  return exitCode;
-}
-
-async function main() {
-  return runCli();
-}
-
-runAsCli(import.meta.url, main, {
-  source: 'check-loop-units',
-  propagateExitCode: true,
-  errorPrefix: '[check-loop-units] ❌ Fatal error',
-});

package/.agents/scripts/detect-merges.js

@@ -1,111 +0,0 @@
-/* node:coverage ignore file -- pre-push conflict-marker scanner; pure I/O glue over `git ls-files` */
-
-import { execFileSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-import { runAsCli } from './lib/cli-utils.js';
-import { Logger } from './lib/Logger.js';
-import { concurrentMap } from './lib/util/concurrent-map.js';
-
-// Paths under these prefixes are treated as template/documentation files
-// that may legitimately contain literal conflict-marker strings (e.g. the
-// merge-conflict runbook). Paths use forward slashes to match `git ls-files`.
-export const TEMPLATE_PATH_PREFIXES = ['.agents/workflows/'];
-
-// Standard git conflict markers. The leading '\n' on '=======' avoids
-// matching plain separator lines.
-const CONFLICT_MARKERS = ['<<<<<<< ', '\n=======', '>>>>>>> '];
-
-const SELF_PATH = '.agents/scripts/detect-merges.js';
-
-// Test fixtures for detect-merges itself embed literal conflict-marker strings
-// to exercise the scanner. Matches any file named `detect-merges*.js` (including
-// `.test.js`) under any depth below `tests/`.
-const TEST_FIXTURE_PATTERN = /(^|\/)tests\/(?:[^/]+\/)*detect-merges[^/]*\.js$/;
-
-// Cap concurrent `fs.readFile` calls. Unbounded `Promise.all` over every
-// tracked file blows past EMFILE on large repos and starves the event loop;
-// 64 keeps the kernel happy while still saturating typical SSDs.
-export const FILE_READ_CAP = 64;
-
-export function isTemplatePath(file) {
-  return TEMPLATE_PATH_PREFIXES.some((prefix) => file.startsWith(prefix));
-}
-
-function isDetectMergesTestFixture(file) {
-  return TEST_FIXTURE_PATTERN.test(file);
-}
-
-/**
- * Scan the given files for conflict markers, skipping templates and self.
- *
- * @param {string[]} files - Repo-relative paths (forward slashes).
- * @param {string}   root  - Repo root used to resolve file paths.
- * @returns {Promise<Array<{ file: string, marker: string }>>}
- */
-export async function scanForConflicts(files, root) {
-  const mapped = await concurrentMap(
-    files,
-    async (file) => {
-      if (
-        file === SELF_PATH ||
-        isTemplatePath(file) ||
-        isDetectMergesTestFixture(file)
-      ) {
-        return null;
-      }
-      try {
-        const content = await fs.promises.readFile(
-          path.join(root, file),
-          'utf8',
-        );
-        for (const marker of CONFLICT_MARKERS) {
-          if (content.includes(marker)) {
-            return { file, marker };
-          }
-        }
-        return null;
-      } catch (_readErr) {
-        // Ignore unreadable files (binaries, broken symlinks, etc.).
-        return null;
-      }
-    },
-    { concurrency: FILE_READ_CAP },
-  );
-  // `concurrentMap` preserves input order, so filtering yields a hit list in
-  // the same order as `files`. Sort by file for byte-stable output regardless
-  // of caller-supplied ordering.
-  const hits = mapped.filter((hit) => hit !== null);
-  hits.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
-  return hits;
-}
-
-export async function main() {
-  try {
-    const root = process.cwd();
-    const filesOutput = execFileSync('git', ['ls-files'], {
-      cwd: root,
-    }).toString();
-    const files = filesOutput.split('\n').filter(Boolean);
-
-    const hits = await scanForConflicts(files, root);
-
-    if (hits.length > 0) {
-      for (const { file, marker } of hits) {
-        Logger.error(
-          `Conflict marker '${marker.trim()}' found in tracked file: ${file}`,
-        );
-      }
-      throw new Error(
-        '\nERROR: Merge conflicts detected. Please resolve them before proceeding.',
-      );
-    } else {
-      Logger.info('No conflict markers found in tracked files.');
-      process.exit(0);
-    }
-  } catch (err) {
-    throw new Error(`Error detecting merges: ${err.message}`);
-  }
-}
-
-runAsCli(import.meta.url, main, { source: 'detect-merges' });

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

@@ -1,205 +0,0 @@
-#!/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 / test / baselines 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 checks it
- * runs are read from
- * `.agentrc.json → github.branchProtection.requiredChecks` when present,
- * falling back to the hardcoded default trio, which mirrors the live required
- * check set (`lint`, `test`, `baselines` — Story #4356, Epic #4355; the stale
- * `lifecycle-doc-drift` check was pruned in the same slice).
- *
- * 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: 'test', cmd: ['npm', 'test'] },
-  { name: 'baselines', cmd: ['node', '.agents/scripts/check-baselines.js'] },
-]);
-
-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' });