@event4u/agent-config 14.19.0 → 14.21.0

package/src/scripts/check_branch_work_committed.ts

@@ -0,0 +1,234 @@
+/**
+ * Refuse a push that leaves this branch's OWN work uncommitted.
+ *
+ * The defect, measured on 2026-09-07 in `fix/release-obligation-answerable`:
+ * a merge-reconciliation baseline was computed, written into
+ * `gate-violation-baselines.json` AFTER `git add`, and then committed with
+ * `git commit --no-edit` — which captured the STAGED side. The reconciled
+ * number stayed in the working tree, the push went out without it, and the
+ * pushed branch asserted a baseline the tree contradicted. The operator found
+ * it, not the pipeline.
+ *
+ * Nothing in CI can catch this class: CI checks out the pushed commit, where
+ * the working tree that holds the lost edit does not exist. The only place the
+ * evidence is available is the machine doing the push, which is why this gate
+ * is pre-push and local-only — the same reach `check_branch_freshness` has.
+ *
+ * The discriminator, whose work is it:
+ *
+ * A dirty tree at push time is not automatically a defect. Gate scripts write
+ * reports, a parallel session may touch a shared file, a test run leaves
+ * artifacts. Blocking on all of it would train the operator to set the skip
+ * variable, which is worse than no gate.
+ *
+ * So the split is by AUTHORSHIP, and it is decidable from git alone:
+ *
+ *   1. INDEX/WORKTREE DIVERGENCE (`MM`, `AM`, `RM`, …) — the file is staged
+ *      AND changed again since. That is "edited after `git add`" as a fact, not
+ *      an inference, and it is exactly the shape that produced the defect.
+ *   2. STAGED AT ALL — `git add` is a recorded intent to ship the file, and a
+ *      push carries commits rather than the index, so a staged-but-uncommitted
+ *      path is this branch's work being left behind by definition. No
+ *      authorship inference is needed for this class.
+ *   3. A DIRTY FILE THIS BRANCH'S OWN COMMITS TOUCHED — the branch has been
+ *      editing it deliberately, so an open change to it is this branch's
+ *      unfinished work rather than someone else's noise.
+ *   4. EVERYTHING ELSE — a dirty file the branch never committed, or an
+ *      untracked file. Reported by name, never blocking: this is where a
+ *      parallel session's edit and a gate script's own report output land, and
+ *      the branch has no claim on either.
+ *
+ * Class 4 is advisory, and the residual limit is stated rather than hidden: a
+ * file this branch created and has neither staged nor committed is
+ * indistinguishable from a foreign untracked file. Class 2 closes it at the
+ * first `git add` — which was itself a finding of testing this gate against the
+ * live tree, where its own source file sat in class 4 until the rule was
+ * widened.
+ */
+import * as path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export interface WorkVerdict {
+    /** False when the push must be refused. */
+    ok: boolean;
+    /** Files that are this branch's own unfinished work, with the reason. */
+    blocking: { path: string; why: string }[];
+    /** Files that are dirty but not this branch's to answer for. */
+    advisory: string[];
+}
+
+/** One `git status --porcelain` row. */
+interface StatusRow {
+    index: string;
+    worktree: string;
+    path: string;
+}
+
+export function parsePorcelain(porcelain: string): StatusRow[] {
+    const out: StatusRow[] = [];
+    for (const line of porcelain.split('\n')) {
+        if (line.length < 4) continue;
+        const index = line[0] as string;
+        const worktree = line[1] as string;
+        let p = line.slice(3);
+        // Renames read `R  old -> new`; the new path is the one that matters.
+        const arrow = p.indexOf(' -> ');
+        if (arrow !== -1) p = p.slice(arrow + 4);
+        out.push({ index, worktree, path: p.replace(/^"|"$/gu, '') });
+    }
+    return out;
+}
+
+/**
+ * The verdict, as a pure function of the two git readings — so the rules are
+ * unit-testable without a repository, the shape `confirmGate` and
+ * `preflightPosition` already use in this pipeline.
+ */
+export function classifyBranchWork(opts: {
+    porcelain: string;
+    /** Files this branch's own commits touched (`git diff --name-only base..HEAD`). */
+    branchFiles: readonly string[];
+}): WorkVerdict {
+    const touched = new Set(opts.branchFiles);
+    const blocking: { path: string; why: string }[] = [];
+    const advisory: string[] = [];
+
+    for (const row of parsePorcelain(opts.porcelain)) {
+        const untracked = row.index === '?' && row.worktree === '?';
+        const staged = row.index !== ' ' && !untracked;
+        const dirty = row.worktree !== ' ' && !untracked;
+
+        if (staged && dirty) {
+            blocking.push({
+                path: row.path,
+                why: 'staged AND changed again since — edited after `git add`, so the commit would capture the stale side',
+            });
+            continue;
+        }
+        if (staged) {
+            blocking.push({
+                path: row.path,
+                why: 'staged but never committed — `git add` records the intent to ship it, and a push carries commits, not the index',
+            });
+            continue;
+        }
+        if (dirty && touched.has(row.path)) {
+            blocking.push({
+                path: row.path,
+                why: "this branch's own commits touch this file, so an open change to it is unfinished work from this branch",
+            });
+            continue;
+        }
+        advisory.push(row.path);
+    }
+    return { ok: blocking.length === 0, blocking, advisory };
+}
+
+function git(args: readonly string[]): string {
+    const r = spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf-8' });
+    return r.status === 0 ? (r.stdout ?? '') : '';
+}
+
+/** Files this branch's commits touched, relative to where it left the base. */
+export function branchOwnFiles(baseRef: string): string[] {
+    const base = git(['merge-base', baseRef, 'HEAD']).trim();
+    if (base === '') return [];
+    return git(['diff', '--name-only', `${base}..HEAD`])
+        .split('\n')
+        .filter((l) => l.trim() !== '');
+}
+
+export function main(argv: readonly string[]): number {
+    const quiet = argv.includes('--quiet');
+    let baseRef = 'origin/main';
+    const bi = argv.indexOf('--base');
+    if (bi !== -1 && argv[bi + 1]) baseRef = argv[bi + 1] as string;
+
+    const porcelain = git(['status', '--porcelain']);
+    const verdict = classifyBranchWork({ porcelain, branchFiles: branchOwnFiles(baseRef) });
+
+    // Through the shared reporter, not a hand-written line: `check_gate_coverage`
+    // reads the CALL, and a printed `scanned:` string satisfies the eye while
+    // leaving the gate unhardened (measured — this gate reded that ratchet on
+    // its first CI run for exactly that reason).
+    //
+    // Zero rows is the GOOD state here, which inverts the usual dead-scope
+    // reasoning: for every other gate an empty corpus may mean the root moved,
+    // while for this one it means the operator has nothing outstanding. The
+    // scope cannot go dead either — `git status` is the corpus, and a reading it
+    // could not produce comes back as an empty string from a non-zero exit,
+    // which is indistinguishable from clean and is why the reason below is
+    // stated rather than left implicit.
+    reportScanned({
+        gate: 'check_branch_work_committed',
+        scanned: parsePorcelain(porcelain).length,
+        units: 'dirty path(s)',
+        roots: ['git status --porcelain'],
+        allowEmpty:
+            'EMPTY_VALID: a clean working tree is this gate\'s PASSING state, not a dead scope. ' +
+            'The corpus is git\'s own status output over the whole repository, so there is no ' +
+            'root to move; zero rows means the operator has committed everything, which is the ' +
+            'outcome the gate exists to produce.',
+    });
+
+    if (verdict.ok) {
+        if (!quiet) {
+            process.stdout.write(
+                `✅  check_branch_work_committed: nothing of this branch's own work is uncommitted` +
+                    (verdict.advisory.length > 0
+                        ? ` (${String(verdict.advisory.length)} unrelated dirty path(s) left alone)\n`
+                        : '\n'),
+            );
+        }
+        if (verdict.advisory.length > 0 && !quiet) {
+            for (const p of verdict.advisory) {
+                process.stdout.write(`    ·  ${p} — not touched by this branch's commits\n`);
+            }
+        }
+        return 0;
+    }
+
+    process.stderr.write(
+        `❌  check_branch_work_committed: ${String(verdict.blocking.length)} file(s) carry this ` +
+            "branch's own uncommitted work:\n",
+    );
+    for (const b of verdict.blocking) {
+        process.stderr.write(`    - ${b.path}\n        ${b.why}\n`);
+    }
+    process.stderr.write(
+        '    A push that leaves them behind ships a branch whose tree contradicts its own\n' +
+            '    commits, and NO CI gate can see it — CI checks out the commit, never the tree\n' +
+            '    the edit is sitting in.\n' +
+            '    Commit them (or `git restore` what was not meant to land), then push again.\n' +
+            '    Genuinely foreign changes are reported without blocking; if one of these is\n' +
+            "    truly a parallel session's, commit around it with an explicit pathspec.\n" +
+            '    WIP push: AGENT_CONFIG_SKIP_PREPUSH_WORKTREE=1.\n',
+    );
+    if (verdict.advisory.length > 0) {
+        process.stderr.write(
+            `    Left alone (${String(verdict.advisory.length)}): ${verdict.advisory.join(', ')}\n`,
+        );
+    }
+    return 1;
+}
+
+const _isMain = (() => {
+    const entry = process.argv[1];
+    if (!entry) return false;
+    try {
+        return path.resolve(entry) === path.resolve(_HERE);
+    } catch {
+        return false;
+    }
+})();
+
+if (_isMain) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_mcp_doc_drift.ts

@@ -0,0 +1,217 @@
+#!/usr/bin/env tsx
+/**
+ * The documented MCP client snippets must match the entry the installer writes.
+ *
+ * `docs/mcp-server.md` documented an absolute `tsx` path in four snippets while
+ * the installer wrote an `npx` invocation, so a consumer who followed the docs
+ * and a consumer who ran the installer landed on two different servers — for
+ * long enough that nobody noticed either was wrong.
+ *
+ * Scope is two literals in this tree. It asserts NOTHING about host behaviour:
+ * that a host reads the file at all is a separate question this gate does not
+ * touch and must not be cited for.
+ *
+ * Exit codes: 0 in sync · 1 drift · 2 a source is missing or unreadable.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { MCP_PACKAGE_NAME, MCP_SERVER_KEY, mcpBridgeEntry } from './_lib/mcp_bridge.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const DOC_REL = 'docs/mcp-server.md';
+
+/**
+ * A snippet is any fenced block naming our server key.
+ *
+ * Deliberately not a JSON/YAML parse: the four documented clients use three
+ * different shapes (`command` as a string, `command` as an object with `path`,
+ * and a YAML list), and a parser per shape would drift from the docs as surely
+ * as the docs drifted from the installer. The two facts that matter — the
+ * runner and the package spec — are the same literals in all three.
+ */
+export function snippetBlocks(text: string): string[] {
+    const out: string[] = [];
+    const lines = text.split('\n');
+    let open: string[] | null = null;
+    for (const line of lines) {
+        if (line.startsWith('```')) {
+            if (open === null) open = [];
+            else {
+                const body = open.join('\n');
+                if (body.includes(MCP_SERVER_KEY) || body.includes('mcpServers')) out.push(body);
+                open = null;
+            }
+            continue;
+        }
+        if (open !== null) open.push(line);
+    }
+    return out;
+}
+
+export interface DocFinding {
+    snippet: number;
+    reason: string;
+}
+
+export function checkSnippets(text: string, packageRoot: string): DocFinding[] {
+    const server = (mcpBridgeEntry(packageRoot)['mcpServers'] as Record<string, unknown>)[
+        MCP_SERVER_KEY
+    ] as { command: string; args: string[] };
+    const findings: DocFinding[] = [];
+
+    snippetBlocks(text).forEach((body, i) => {
+        // Only blocks that actually configure the server — a block that merely
+        // mentions `mcpServers` in prose is not a client configuration.
+        if (!body.includes('command')) return;
+        if (!body.includes(server.command)) {
+            findings.push({
+                snippet: i + 1,
+                reason: `does not use the installer's runner \`${server.command}\``,
+            });
+        }
+        if (!body.includes(MCP_PACKAGE_NAME)) {
+            findings.push({
+                snippet: i + 1,
+                reason: `does not name the package \`${MCP_PACKAGE_NAME}\``,
+            });
+        }
+        // QUOTED, not a substring: `mcp-server` contains `serve`, so a plain
+        // `includes` reported a snippet as current after the entry had been
+        // changed to `serve` and the doc had not — measured, on this gate's own
+        // sensitivity probe. Every documented shape quotes the token.
+        const subcommand = server.args[server.args.length - 1] as string;
+        if (!body.includes(`"${subcommand}"`)) {
+            findings.push({
+                snippet: i + 1,
+                reason: `does not invoke \`${subcommand}\``,
+            });
+        }
+        if (body.includes('node_modules/.bin/tsx')) {
+            findings.push({
+                snippet: i + 1,
+                reason: 'documents an absolute tsx path the installer never writes',
+            });
+        }
+    });
+    return findings;
+}
+
+function main(): number {
+    if (process.argv.slice(2).includes('--self-test')) return selfTest();
+    const rootIdx = process.argv.indexOf('--root');
+    const root = rootIdx === -1 ? ROOT : (process.argv[rootIdx + 1] ?? ROOT);
+    const doc = path.join(root, DOC_REL);
+    if (!fs.existsSync(doc)) {
+        process.stderr.write(`❌  ${DOC_REL} not found under ${root}\n`);
+        return 2;
+    }
+    const text = fs.readFileSync(doc, 'utf-8');
+    const blocks = snippetBlocks(text).filter((b) => b.includes('command'));
+    const findings = checkSnippets(text, root);
+
+    reportScanned({
+        gate: 'check_mcp_doc_drift',
+        scanned: blocks.length,
+        units: 'documented client snippet(s)',
+        roots: [DOC_REL],
+    });
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stdout.write(`❌  ${DOC_REL} snippet ${String(f.snippet)}: ${f.reason}\n`);
+        }
+        process.stdout.write(
+            `\n${String(findings.length)} finding(s). The documented entry and the entry ` +
+                '`mcpBridgeEntry()` writes have drifted apart.\n',
+        );
+        return 1;
+    }
+    process.stdout.write(
+        `✅  check_mcp_doc_drift: ${String(blocks.length)} documented snippet(s) match the ` +
+            'installer entry.\n',
+    );
+    return 0;
+}
+
+/** One rejecting case per way the two literals can drift. */
+function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-doc-drift-'));
+    const write = (name: string, doc: string): string => {
+        const dir = path.join(tmp, name);
+        fs.mkdirSync(path.join(dir, 'docs'), { recursive: true });
+        fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ version: '1.0.0' }));
+        fs.writeFileSync(path.join(dir, DOC_REL), doc, 'utf-8');
+        return dir;
+    };
+    const run = (root: string): number =>
+        runGateCli(ROOT, 'src/scripts/check_mcp_doc_drift.ts', ['--root', root], root);
+
+    const good = [
+        '```json',
+        '{ "mcpServers": { "agent-config": {',
+        '  "command": "npx",',
+        '  "args": ["-y", "@event4u/agent-config@<version>", "mcp-server"] } } }',
+        '```',
+        '',
+    ].join('\n');
+    const tsxPath = good.replace('"npx"', '"/abs/agent-config/node_modules/.bin/tsx"');
+    const noPackage = good.replace('@event4u/agent-config@<version>', 'some-other-package');
+    const noSubcommand = good.replace('"mcp-server"', '"serve"');
+
+    try {
+        return runSelfTest({
+            gate: 'check_mcp_doc_drift',
+            minCases: 4,
+            minRejectCases: 3,
+            cases: [
+                {
+                    name: 'an absolute tsx path is rejected',
+                    expect: 'reject',
+                    run: () => run(write('tsx', tsxPath)),
+                },
+                {
+                    name: 'a snippet naming another package is rejected',
+                    expect: 'reject',
+                    run: () => run(write('pkg', noPackage)),
+                },
+                {
+                    name: 'a snippet invoking another subcommand is rejected',
+                    expect: 'reject',
+                    run: () => run(write('sub', noSubcommand)),
+                },
+                {
+                    name: 'the installer-shaped snippet passes',
+                    expect: 'accept',
+                    run: () => run(write('good', good)),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { DOC_REL, main };