@event4u/agent-config 9.6.0 → 9.8.0

package/src/scripts/check_secret_leak.ts

@@ -0,0 +1,290 @@
+#!/usr/bin/env tsx
+/**
+ * CI secret-leak gate — the non-bypassable second layer behind the
+ * `secret-vcs-guard` behavioral rule.
+ *
+ * Runs the shared `secret_detector` library (regex rule pack + Shannon entropy +
+ * keyword context) over the repository's tracked working tree (or a supplied
+ * path set), and FAILS (exit 1) on any `high`-confidence finding that is not
+ * suppressed. This is the deterministic enforcing net: a PR cannot merge red,
+ * unlike a client-side commit hook (which fires only on agent-initiated bash and
+ * is `--no-verify`/GUI/fresh-clone bypassable) — see
+ * `src/rules/secret-vcs-guard.md` and `skill:secrets-management` for the
+ * layering rationale.
+ *
+ * Suppression (audited, narrow — never a global mute):
+ *   - inline `# secret-allow` / `// secret-allow` / `<!-- secret-allow -->` on a
+ *     line (handled inside `secret_detector`);
+ *   - a repo-root `.secret-allow` file: one entry per line, `path` or
+ *     `path:line`, `#` comments allowed. Each entry SHOULD carry a one-line
+ *     justification comment so it is reviewable in the diff.
+ *
+ * Default excludes (fixtures/tests/examples legitimately hold fake secrets;
+ * generated + vendored trees are not source): node_modules, dist, dist-*,
+ * .git, .claude, **\/fixtures\/**, *.test.*, *.spec.*, *.example, *.sample,
+ * .env.example, lockfiles, *.min.*.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_secret_leak [paths...] [--all] [--base <ref>] [--json]
+ *   default → files changed vs origin/main + untracked (shift-left); --all →
+ *   whole tracked tree; paths → exactly those (excludes skipped).
+ *
+ * Exit codes: 0 clean · 1 high-confidence leak found · 2 usage/env error.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { scanText, type SecretFinding } from './_lib/secret_detector.js';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+// repo root: src/scripts/check_secret_leak.ts → parents[2].
+export const REPO_ROOT = path.resolve(_HERE, '..', '..');
+
+const DEFAULT_EXCLUDE: readonly RegExp[] = [
+    /(^|\/)node_modules(\/|$)/,
+    /(^|\/)dist(\/|$)/,
+    /(^|\/)dist-[^/]+(\/|$)/,
+    /(^|\/)\.git(\/|$)/,
+    /(^|\/)\.claude(\/|$)/,
+    /(^|\/)fixtures(\/|$)/,
+    /(^|\/)tests(\/|$)/, // test + golden + parity data legitimately holds secret-shaped strings
+    /(^|\/)__[a-z_]+__(\/|$)/, // snapshot dirs (e.g. __parity_snapshots__)
+    /\.test\.[a-z]+$/,
+    /\.spec\.[a-z]+$/,
+    /\.example$/,
+    /\.sample$/,
+    /(^|\/)\.env\.example$/,
+    /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|composer\.lock)$/,
+    /\.min\.[a-z]+$/,
+];
+
+export interface LeakHit extends SecretFinding {
+    file: string;
+}
+
+interface AllowEntry {
+    file: string;
+    line: number | null; // null = whole-file allow
+}
+
+/** Parse `.secret-allow` (repo-root) into path[:line] entries. */
+export function readAllowFile(root: string): AllowEntry[] {
+    const p = path.join(root, '.secret-allow');
+    if (!fs.existsSync(p)) {
+        return [];
+    }
+    const out: AllowEntry[] = [];
+    for (const raw of fs.readFileSync(p, 'utf-8').split(/\r?\n/)) {
+        const line = raw.replace(/#.*$/, '').trim();
+        if (line === '') {
+            continue;
+        }
+        const m = /^(.*?)(?::(\d+))?$/.exec(line);
+        if (m) {
+            out.push({ file: m[1] as string, line: m[2] ? parseInt(m[2], 10) : null });
+        }
+    }
+    return out;
+}
+
+function isAllowed(rel: string, lineno: number, allow: readonly AllowEntry[]): boolean {
+    return allow.some((a) => a.file === rel && (a.line === null || a.line === lineno));
+}
+
+function isExcluded(rel: string): boolean {
+    return DEFAULT_EXCLUDE.some((rx) => rx.test(rel));
+}
+
+/** Fast binary sniff — a NUL byte in the first 8 KiB means "not text". */
+function isBinary(abs: string): boolean {
+    try {
+        const fd = fs.openSync(abs, 'r');
+        const buf = Buffer.alloc(8192);
+        const n = fs.readSync(fd, buf, 0, 8192, 0);
+        fs.closeSync(fd);
+        return buf.subarray(0, n).includes(0);
+    } catch {
+        return true; // unreadable → skip
+    }
+}
+
+function gitLines(root: string, args: readonly string[]): string[] {
+    const res = spawnSync('git', args as string[], { cwd: root, encoding: 'utf-8' });
+    if (res.status !== 0) {
+        return [];
+    }
+    return res.stdout.split('\n').filter((l) => l.trim() !== '');
+}
+
+export type Mode = 'diff' | 'all' | 'explicit';
+
+/**
+ * Resolve the file set.
+ *   explicit → the named paths (intent — excludes skipped by the caller).
+ *   all      → every tracked file (`git ls-files`).
+ *   diff     → files this branch adds or changes vs `base` PLUS untracked files —
+ *              the shift-left surface: scan what the change introduces, never the
+ *              pre-existing corpus (which floods a mature repo with matches).
+ */
+export function resolveFiles(
+    root: string,
+    mode: Mode,
+    opts: { explicit?: readonly string[] | undefined; base?: string | undefined } = {},
+): string[] {
+    if (mode === 'explicit') {
+        return (opts.explicit ?? []).map((p) =>
+            path.isAbsolute(p) ? path.relative(root, p) : p,
+        );
+    }
+    if (mode === 'all') {
+        return gitLines(root, ['ls-files']);
+    }
+    const base = opts.base ?? 'origin/main';
+    // An unresolvable base is a scan of NOTHING, not a clean scan.
+    //
+    // `git diff <missing-ref>` yields no lines, so the changed-set silently
+    // became empty and the gate reported "no high-confidence secret found in the
+    // tracked tree" while examining zero files. That is the shape a shallow CI
+    // checkout produces by default — verified: with an unresolvable base this
+    // function returned 0 paths. A secret gate that passes green on an empty
+    // scan is worse than no gate, because it is believed.
+    const probe = spawnSync('git', ['-C', root, 'rev-parse', '--verify', '--quiet', `${base}^{commit}`], {
+        encoding: 'utf-8',
+    });
+    if ((probe.status ?? 1) !== 0) {
+        throw new Error(
+            `check_secret_leak: baseline ref '${base}' does not resolve, so the changed-set would be empty ` +
+                `and the scan would examine no files. Fetch the branch (CI: actions/checkout with fetch-depth: 0), ` +
+                `pass --base <ref>, or use --all to scan the whole tracked tree.`,
+        );
+    }
+    const changed = gitLines(root, ['diff', '--name-only', '--diff-filter=ACMR', base]);
+    const untracked = gitLines(root, ['ls-files', '--others', '--exclude-standard']);
+    return Array.from(new Set([...changed, ...untracked]));
+}
+
+export function scanRepo(
+    root: string,
+    mode: Mode = 'diff',
+    opts: { explicit?: readonly string[] | undefined; base?: string | undefined } = {},
+): LeakHit[] {
+    const allow = readAllowFile(root);
+    // Explicit paths express intent — the fixture/test/example excludes (which
+    // exist so an auto-discovered scan ignores intentional fake secrets) are
+    // skipped only when the caller names paths directly.
+    const applyExcludes = mode !== 'explicit';
+    const hits: LeakHit[] = [];
+    for (const rel of resolveFiles(root, mode, opts)) {
+        if (applyExcludes && isExcluded(rel)) {
+            continue;
+        }
+        const abs = path.join(root, rel);
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isFile() || isBinary(abs)) {
+            continue;
+        }
+        let text: string;
+        try {
+            text = fs.readFileSync(abs, 'utf-8');
+        } catch {
+            continue;
+        }
+        for (const f of scanText(text, { path: rel })) {
+            if (f.confidence !== 'high') {
+                continue;
+            }
+            if (isAllowed(rel, f.line, allow)) {
+                continue;
+            }
+            hits.push({ ...f, file: rel });
+        }
+    }
+    return hits;
+}
+
+interface Args {
+    json: boolean;
+    all: boolean;
+    base: string | undefined;
+    paths: string[];
+}
+
+function parseArgs(argv: readonly string[]): Args {
+    const paths: string[] = [];
+    let json = false;
+    let all = false;
+    let base: string | undefined;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--json') {
+            json = true;
+        } else if (a === '--all') {
+            all = true;
+        } else if (a === '--base') {
+            base = argv[++i];
+        } else if (a === '-h' || a === '--help') {
+            _stdout(
+                'usage: check_secret_leak [paths...] [--all] [--base <ref>] [--json]\n' +
+                    '  default → scans files changed vs origin/main + untracked (shift-left).\n' +
+                    '  --all   → scans the whole tracked tree.\n' +
+                    '  paths   → scans exactly those paths (excludes skipped).\n' +
+                    '  Exit 1 on a high-confidence leak.\n',
+            );
+            process.exit(0);
+        } else if (a.startsWith('--')) {
+            _stderr(`check_secret_leak: unknown flag ${a}\n`);
+            process.exit(2);
+        } else {
+            paths.push(a);
+        }
+    }
+    return { json, all, base, paths };
+}
+
+function _stdout(s: string): void {
+    process.stdout.write(s);
+}
+function _stderr(s: string): void {
+    process.stderr.write(s);
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = parseArgs(argv ?? process.argv.slice(2));
+    const mode: Mode = args.paths.length > 0 ? 'explicit' : args.all ? 'all' : 'diff';
+    const hits = scanRepo(REPO_ROOT, mode, { explicit: args.paths, base: args.base });
+
+    if (args.json) {
+        _stdout(JSON.stringify({ check: 'secret-leak', count: hits.length, hits }, null, 2) + '\n');
+    } else if (hits.length === 0) {
+        _stdout('✅  check_secret_leak: no high-confidence secret found in the tracked tree.\n');
+    } else {
+        _stderr(`❌  check_secret_leak: ${hits.length} high-confidence secret finding(s):\n`);
+        for (const h of hits) {
+            _stderr(`   ${h.file}:${h.line}  ${h.kind}  (${h.masked})\n`);
+        }
+        _stderr(
+            '\nRotate any real credential NOW (a commit does not un-leak it), move it to a\n' +
+                'secret store (see skill:secrets-management), or add an audited entry to\n' +
+                '.secret-allow / an inline `# secret-allow` marker if this is a false positive.\n',
+        );
+    }
+    return hits.length === 0 ? 0 : 1;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention).
+if (process.argv[1] !== undefined) {
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        if (here === argv1) {
+            process.exit(main());
+        }
+    } catch {
+        const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+        if (import.meta.url === argvUrl) {
+            process.exit(main());
+        }
+    }
+}

package/src/scripts/check_source_pointer_freshness.ts

@@ -0,0 +1,165 @@
+#!/usr/bin/env tsx
+/**
+ * check_source_pointer_freshness — fail when an AUTHORING artifact asserts a
+ * RETIRED source-of-truth pointer as the current one.
+ *
+ * The doc-follows-code discipline (rule: downstream-changes § Doc-Impact;
+ * skill: agent-docs-writing § Doc-Impact) is a behavioral obligation. This is
+ * its deterministic backstop for the one drift class a plain script CAN catch
+ * without semantics: a doc that still names the retired `.agent-src.uncondensed/`
+ * tree as the source of truth after the source moved to `src/` (ADR-051).
+ *
+ * Scope is deliberately narrow (council 2026-07-21, do-not-build list): an
+ * explicit allowlist of the authoring files that MAKE a source-of-truth claim,
+ * not a whole-tree sweep — a gate that fires on every commit and gets
+ * routinely overridden is worse than none. Historical mentions (ADRs under
+ * docs/decisions/, archived roadmaps) are out of scope by construction; a
+ * genuinely-historical line inside an allowlisted file is exempted with an
+ * inline `<!-- pointer-freshness: historical -->` marker.
+ *
+ * Extend AUTHORING_FILES as the broader `.agent-src.uncondensed` cleanup lands
+ * (186 files still carry the token; see road-to-doc-follows-code Phase 4/5
+ * follow-up).
+ *
+ * Exit codes: 0 = clean, 1 = a retired pointer in an allowlisted authoring
+ * file, 2 = usage / self-test failure.
+ *
+ * Usage:
+ *     tsx src/scripts/check_source_pointer_freshness.ts [--json] [--selftest]
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+// parents[2] of src/scripts/<file> is the repo root.
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+// Authoring files that assert WHERE the source of truth lives. Each must NOT
+// name the retired `.agent-src.uncondensed/` tree as current. Extend as the
+// broader cleanup lands.
+const AUTHORING_FILES: readonly string[] = [
+    'src/agent-src/README.md',
+    'src/skills/agents-md-thin-root/SKILL.md',
+];
+
+// Retired source-of-truth pointer. Matches both the bare token and the older
+// monorepo-prefixed form `packages/core/.agent-src.uncondensed/`.
+const RETIRED_POINTER = /\.agent-src\.uncondensed\//;
+
+// A line carrying this marker is a deliberate historical reference — exempt.
+const HISTORICAL_MARKER = '<!-- pointer-freshness: historical -->';
+
+interface Hit {
+    file: string;
+    line: number;
+    text: string;
+}
+
+function _scanFile(rel: string): Hit[] {
+    const abs = path.join(ROOT, rel);
+    let text: string;
+    try {
+        if (!fs.statSync(abs).isFile()) {
+            return [];
+        }
+        text = fs.readFileSync(abs, 'utf-8');
+    } catch {
+        // A missing allowlisted file is a config drift in itself — surface it.
+        return [{ file: rel, line: 0, text: '(allowlisted authoring file not found)' }];
+    }
+    const hits: Hit[] = [];
+    const lines = text.split('\n');
+    for (let idx = 0; idx < lines.length; idx += 1) {
+        const line = lines[idx] as string;
+        if (line.includes(HISTORICAL_MARKER)) {
+            continue;
+        }
+        if (RETIRED_POINTER.test(line)) {
+            hits.push({ file: rel, line: idx + 1, text: line.trim().slice(0, 160) });
+        }
+    }
+    return hits;
+}
+
+/** Deterministic self-check of the matcher — no filesystem, no network. */
+function _selftest(): number {
+    const stale = 'The source of truth is `.agent-src.uncondensed/`. Edit there.';
+    const monorepo = 'Editing `packages/core/.agent-src.uncondensed/templates/AGENTS.md`.';
+    const clean = 'The source of truth is `src/`. Edit there, then run `task sync`.';
+    const historical = `Retired path \`.agent-src.uncondensed/\` ${HISTORICAL_MARKER}`;
+    const cases: Array<[string, boolean]> = [
+        [stale, true],
+        [monorepo, true],
+        [clean, false],
+        [historical, false], // marker suppresses the match at scan time
+    ];
+    let ok = true;
+    for (const [sample, shouldMatch] of cases) {
+        const exempt = sample.includes(HISTORICAL_MARKER);
+        const matched = !exempt && RETIRED_POINTER.test(sample);
+        if (matched !== shouldMatch) {
+            process.stderr.write(`selftest FAIL: ${JSON.stringify(sample)} expected match=${shouldMatch}, got ${matched}\n`);
+            ok = false;
+        }
+    }
+    if (ok) {
+        process.stdout.write('✅  check_source_pointer_freshness selftest passed (4/4).\n');
+        return 0;
+    }
+    return 2;
+}
+
+function main(argv: readonly string[]): number {
+    if (argv.includes('--selftest')) {
+        return _selftest();
+    }
+    const asJson = argv.includes('--json');
+    const hits: Hit[] = [];
+    for (const rel of AUTHORING_FILES) {
+        hits.push(..._scanFile(rel));
+    }
+
+    if (asJson) {
+        process.stdout.write(JSON.stringify({ ok: hits.length === 0, hits }, null, 2) + '\n');
+    } else if (hits.length > 0) {
+        process.stdout.write(`❌  ${hits.length} retired source-of-truth pointer(s) in authoring files:\n\n`);
+        for (const h of hits) {
+            process.stdout.write(`  ${h.file}:${h.line}  ${h.text}\n`);
+        }
+        process.stdout.write(
+            '\nThese name the retired `.agent-src.uncondensed/` tree as the source of\n' +
+                'truth. The source of truth is `src/` (ADR-051, rule: source-of-truth).\n' +
+                'Fix the pointer, or mark a genuinely-historical line with\n' +
+                `\`${HISTORICAL_MARKER}\`. See rule: downstream-changes § Doc-Impact.\n`,
+        );
+    } else {
+        process.stdout.write('✅  No retired source-of-truth pointers in authoring files.\n');
+    }
+    return hits.length > 0 ? 1 : 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main(process.argv.slice(2)));
+}
+
+export { main, _scanFile, _selftest, AUTHORING_FILES, RETIRED_POINTER, HISTORICAL_MARKER };

package/src/scripts/code_graph/cli.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env tsx
+/**
+ * Native code-graph engine CLI (Class-A, ADR-124).
+ *
+ *   build    [--root P] [--out P] [--force]   (re)build the deterministic graph
+ *   validate [--graph P]                       schema-gate a graph.json
+ *
+ * Query subcommands (query/path/explain/affected/detect) are added by the
+ * Phase-3 query tier. Deterministic, LLM-free, no network. Exit codes:
+ * 0 ok · 1 not-found / validation-failed · 2 usage · 3 internal.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
+import { buildFromRepo } from './build.js';
+import { detectSources, pickSource } from './detect.js';
+import { affected, explain, loadGraph, type LoadedGraph, path as graphPath, query, type QueryResult } from './query.js';
+import { validateGraph } from './validate.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
+export const DEFAULT_CACHE = path.join(REPO_ROOT, 'agents', 'runtime', 'state', 'code-graph-v1.json');
+
+function flag(argv: string[], name: string): string | null {
+    const i = argv.indexOf(name);
+    return i >= 0 && i + 1 < argv.length ? (argv[i + 1] as string) : null;
+}
+
+async function cmdBuild(argv: string[]): Promise<number> {
+    const root = flag(argv, '--root') ?? REPO_ROOT;
+    const out = argv.includes('--out') ? flag(argv, '--out') : DEFAULT_CACHE;
+    if (!fs.existsSync(root)) {
+        process.stderr.write(`code-graph: root not found: ${root}\n`);
+        return 1;
+    }
+    const update = argv.includes('--update');
+    const { graph, fileCount, reExtracted, reused } = await buildFromRepo(root, out, { update });
+    const c = graph.edge_confidence_counts;
+    process.stdout.write(
+        `✅  code-graph ${update ? 'updated' : 'built'} — ${fileCount} files · ${graph.nodes.length} nodes · ${graph.edges.length} edges\n` +
+            `    languages: ${graph.languages.join(', ') || '(none)'} · grammar ABI ${graph.grammar_abi}\n` +
+            `    edges: EXTRACTED ${c.EXTRACTED} · INFERRED ${c.INFERRED} · AMBIGUOUS ${c.AMBIGUOUS}\n` +
+            (update ? `    incremental: ${reExtracted} re-extracted · ${reused} reused\n` : '') +
+            (out ? `    cache: ${path.relative(REPO_ROOT, out)}\n` : ''),
+    );
+    return 0;
+}
+
+function cmdValidate(argv: string[]): number {
+    const p = flag(argv, '--graph') ?? DEFAULT_CACHE;
+    if (!fs.existsSync(p)) {
+        process.stderr.write(`code-graph: graph not found: ${p}\n`);
+        return 1;
+    }
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    } catch (e) {
+        process.stderr.write(`code-graph: graph is not valid JSON: ${(e as Error).message}\n`);
+        return 1;
+    }
+    const r = validateGraph(parsed);
+    if (r.ok) {
+        process.stdout.write(`✅  graph schema valid: ${path.relative(REPO_ROOT, p)}\n`);
+        return 0;
+    }
+    process.stderr.write(`❌  graph schema invalid (${r.errors.length}):\n`);
+    for (const e of r.errors) process.stderr.write(`  ${e}\n`);
+    return 1;
+}
+
+function resolveGraph(argv: string[]): { g: LoadedGraph; note: string } | { err: string } {
+    const explicit = flag(argv, '--graph');
+    const root = flag(argv, '--root') ?? REPO_ROOT;
+    if (explicit) {
+        if (!fs.existsSync(explicit)) return { err: `graph not found: ${explicit}` };
+        return { g: loadGraph(explicit, path.relative(REPO_ROOT, explicit)), note: '' };
+    }
+    const picked = pickSource(detectSources(root, DEFAULT_CACHE));
+    if (!picked) return { err: 'no code-graph source found — run `code_graph build` or ship a graph.json' };
+    if (picked.kind === 'scip') return { err: `${picked.note ?? 'SCIP detected'} — pass --graph <json> or install peer tooling` };
+    const staleNote = picked.stale ? ` ⚠ index is ${picked.commits_behind ?? 'N'} commit(s) behind — rebuild before trusting` : '';
+    return { g: loadGraph(picked.path, `${picked.kind}:${path.relative(REPO_ROOT, picked.path)}`), note: staleNote };
+}
+
+function render(r: QueryResult, staleNote: string): number {
+    process.stdout.write(`source: ${r.source}${staleNote}\n`);
+    if (r.seeds.length) process.stdout.write(`seeds: ${r.seeds.join(', ')}\n`);
+    for (const l of r.lines) process.stdout.write(`  ${l}\n`);
+    if (r.truncated) process.stdout.write('  … (budget reached — narrow the seed or raise --budget)\n');
+    if (!r.lines.length) process.stdout.write('  (no matching relations)\n');
+    return 0;
+}
+
+function budgetOf(argv: string[]): number {
+    const b = Number(flag(argv, '--budget'));
+    return Number.isFinite(b) && b > 0 ? b : 1500;
+}
+
+function changedNodeSeeds(g: LoadedGraph, root: string, ref: string): string[] {
+    let files: string[];
+    try {
+        files = execFileSync('git', ['-C', root, 'diff', '--name-only', `${ref}..HEAD`], {
+            env: hardenedSpawnEnv(),
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .split('\n')
+            .map((s) => s.trim())
+            .filter(Boolean);
+    } catch {
+        return [];
+    }
+    const set = new Set(files);
+    return g.graph.nodes.filter((n) => set.has(n.source_file) && n.kind !== 'file').map((n) => n.id);
+}
+
+function cmdQuery(kind: 'query' | 'explain' | 'affected' | 'path', argv: string[]): number {
+    const r = resolveGraph(argv);
+    if ('err' in r) {
+        process.stderr.write(`code-graph: ${r.err}\n`);
+        return 1;
+    }
+    const positional = argv.filter((a) => !a.startsWith('--') && !isFlagValue(argv, a));
+    const budget = budgetOf(argv);
+    if (kind === 'affected' && flag(argv, '--since')) {
+        const root = flag(argv, '--root') ?? REPO_ROOT;
+        const seeds = changedNodeSeeds(r.g, root, flag(argv, '--since') as string);
+        const merged: QueryResult = { source: r.g.source, seeds: [], lines: [], truncated: false };
+        for (const s of seeds) {
+            const one = affected(r.g, s, 2, budget);
+            merged.seeds.push(...one.seeds);
+            merged.lines.push(...one.lines);
+        }
+        return render(merged, r.note);
+    }
+    const a = positional[0];
+    if (!a) {
+        process.stderr.write(`usage: code_graph/cli.ts ${kind} <symbol> [--graph P] [--budget N]\n`);
+        return 2;
+    }
+    if (kind === 'path') {
+        const b = positional[1];
+        if (!b) {
+            process.stderr.write('usage: code_graph/cli.ts path <a> <b>\n');
+            return 2;
+        }
+        return render(graphPath(r.g, a, b, budget), r.note);
+    }
+    const fn = kind === 'query' ? query : kind === 'explain' ? explain : affected;
+    return render(fn(r.g, a, budget), r.note);
+}
+
+function isFlagValue(argv: string[], token: string): boolean {
+    const i = argv.indexOf(token);
+    return i > 0 && (argv[i - 1] as string).startsWith('--');
+}
+
+function cmdDetect(argv: string[]): number {
+    const root = flag(argv, '--root') ?? REPO_ROOT;
+    const verdicts = detectSources(root, DEFAULT_CACHE);
+    if (!verdicts.length) {
+        process.stdout.write('no code-graph source detected\n');
+        return 1;
+    }
+    for (const v of verdicts) {
+        const fresh = v.stale === undefined ? '' : v.stale ? ` · STALE${v.commits_behind !== undefined ? ` (${v.commits_behind} behind)` : ''}` : ' · fresh';
+        process.stdout.write(`${v.kind.padEnd(9)} ${path.relative(REPO_ROOT, v.path)}${fresh}${v.note ? ` · ${v.note}` : ''}\n`);
+    }
+    const picked = pickSource(verdicts);
+    if (picked) process.stdout.write(`→ query would use: ${picked.kind}\n`);
+    return 0;
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+    const sub = argv[0];
+    try {
+        if (sub === 'build') return await cmdBuild(argv.slice(1));
+        if (sub === 'validate') return cmdValidate(argv.slice(1));
+        if (sub === 'detect') return cmdDetect(argv.slice(1));
+        if (sub === 'query' || sub === 'explain' || sub === 'affected' || sub === 'path')
+            return cmdQuery(sub, argv.slice(1));
+        process.stderr.write(
+            'usage: code_graph/cli.ts <build|validate|detect|query|explain|affected|path> [options]\n',
+        );
+        return 2;
+    } catch (e) {
+        process.stderr.write(`code-graph: internal error: ${(e as Error).message}\n`);
+        return 3;
+    }
+}
+
+const _invokedDirectly = (() => {
+    if (process.argv[1] === undefined) return false;
+    try {
+        return fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(_HERE);
+    } catch {
+        return import.meta.url === `file://${process.argv[1]}`;
+    }
+})();
+if (_invokedDirectly) {
+    main().then((rc) => process.exit(rc));
+}