productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/commands/reconcile.js

@@ -0,0 +1,292 @@
+// Top-level packet-free `foo reconcile` (reconcile-anywhere-v0 T-003/T-004).
+//
+// The adoption wedge: a stranger in a repo that has never heard of packets runs
+// `foo reconcile --source github:<pr-url>` and gets value in one command — no
+// specs/ dir, no init, no config. It recovers the PR's intent, diffs what the
+// change actually does against that recovered intent, and reports drift, silent
+// scope, and unproven claims.
+//
+// Two hard rules from the packet Decisions:
+//   D-001 — this is a NEW top-level command, but it shares ONE engine with
+//     `asp reconcile` (githubReconcile.reconcilePrProof / packetReconcile
+//     .classifyChangedFiles), so the two entry points can never drift.
+//   D-002 — zero side effects by default. Read-only. `--adopt` is the ONLY write
+//     path (T-004), and it goes through the spec-after machinery in specCmd.
+//
+// Report ORDER is load-bearing (R-003, the anti-"PR linter" defense): it LEADS
+// with recovered intent, not lint findings. Intent is the reference point.
+import { readJson } from "../jsonFile.js";
+import path from "node:path";
+import { extractBehaviorStories } from "../codeCatalog.js";
+import { parseGithubSource } from "../sourceIngress.js";
+import { evidenceFromFixture } from "../githubReconcile.js";
+import { recoverPrIntent, suggestDrift, } from "../specAfter.js";
+import { adoptReconcileIntent } from "./specCmd.js";
+import { STATUS_GLYPHS, withGlyph } from "../statusGlyphs.js";
+import { flagValue } from "./shared.js";
+import { classifyThrown, markFailure } from "../errorTaxonomy.js";
+// A malformed reconcile invocation returns exit 1 with a usage line rather than
+// throwing, so it must mark itself usage_error — otherwise a codeless nonzero
+// exit files as a command_error crash and pages for a typo.
+function reconcileUsageFail(output) {
+    markFailure({ errorClass: "usage_error", errorCode: "E_BAD_FLAG", message: output.trim() });
+    return { output, exitCode: 1 };
+}
+// Collect changed file paths from whichever field the fixture carries.
+function changedFilePaths(fixture) {
+    if (fixture.files && fixture.files.length)
+        return fixture.files;
+    const paths = new Set();
+    for (const f of fixture.files_changed ?? [])
+        paths.add(f);
+    for (const c of fixture.commits ?? [])
+        for (const f of c.files ?? [])
+            paths.add(f);
+    return [...paths].map((p) => ({ path: p }));
+}
+function storyFromFile(file, seq) {
+    const added = file.additions ?? 0;
+    const removed = file.deletions ?? 0;
+    const delta = added || removed ? ` (+${added}/-${removed})` : "";
+    return {
+        id: `bs-${String(seq + 1).padStart(3, "0")}`,
+        file: file.path,
+        change_kind: "modified",
+        title: `changes ${file.path}`,
+        expected_behavior: `Changes \`${file.path}\`${delta}.`,
+        evidence: [],
+        added_symbols: [],
+        removed_symbols: [],
+        added_lines: added,
+        removed_lines: removed,
+        // File-list-derived from the PR's own changed files — repo truth, not a
+        // guess about symbols.
+        provenance: "repo-truth",
+        self_reported: true,
+    };
+}
+// What the change does. A full diff yields symbol-level behavior stories; a plain
+// file list yields one story per changed file.
+function behaviorFromFixture(fixture) {
+    if (fixture.diff && fixture.diff.trim()) {
+        const { stories, coverage } = extractBehaviorStories(fixture.diff);
+        return { stories, coverage };
+    }
+    const files = changedFilePaths(fixture);
+    const stories = files.map((f, i) => storyFromFile(f, i));
+    return {
+        stories,
+        coverage: {
+            scanned_files: files.length,
+            story_files: stories.length,
+            stories: stories.length,
+            basis: "PR changed-file list (no unified diff supplied); one behavior story per changed file. Code-derived, self-reported.",
+            skipped: [],
+        },
+    };
+}
+function summarizeChecks(fixture) {
+    const checks = fixture.checks ?? [];
+    if (checks.length === 0)
+        return "absent";
+    if (checks.some((c) => c.conclusion === "failure"))
+        return "fail";
+    if (checks.every((c) => c.conclusion === "success"))
+        return "pass";
+    return "mixed";
+}
+export function buildReconcileReport(source, fixture) {
+    const recovered = recoverPrIntent({ title: fixture.title, body: fixture.body, linked_issue: fixture.linked_issue });
+    const { stories, coverage } = behaviorFromFixture(fixture);
+    const drift = suggestDrift(recovered.items.map((item, index) => ({ id: item.id, text: item.text, source: "prompt", raw_index: index })), stories);
+    const evidence = evidenceFromFixture(fixture);
+    const checks = summarizeChecks(fixture);
+    const proven = [];
+    const contradicted = [];
+    if (evidence.merged === true)
+        proven.push("PR is merged (typed fact)");
+    if (evidence.merged === false)
+        contradicted.push(`PR is not merged (state: ${evidence.state ?? "open"})`);
+    if (checks === "pass")
+        proven.push(`required checks green (${(fixture.checks ?? []).length}/${(fixture.checks ?? []).length})`);
+    if (checks === "fail")
+        contradicted.push("a required check reports failure");
+    return {
+        schema_version: "0.1",
+        source,
+        packet_free: true,
+        recovered_intent: recovered,
+        behavior: stories,
+        coverage,
+        drift,
+        proof: {
+            merged: evidence.merged ?? null,
+            checks,
+            declared_packet: recovered.declares_packet,
+            // Recovered intent is a claim, never proven by a title/body — only typed
+            // facts corroborate (🟡 claimed vs ✅ proven).
+            claimed: recovered.items.map((i) => i.text),
+            proven,
+            contradicted,
+        },
+    };
+}
+const JUDGMENT_GLOSS = {
+    "repo-evidence": "repo evidence",
+    "approved-context": "approved context",
+    "role-expertise": "role expertise",
+    "agent-inference": "agent inference",
+    "user-judgment": "user judgment",
+};
+const SOURCE_GLOSS = {
+    "pr-title": "PR title",
+    "pr-body": "PR body",
+    "linked-issue": "linked issue",
+};
+export function renderReconcileReport(report, glyphsOn) {
+    const lines = [];
+    lines.push(`foo reconcile — packet-free drift-against-intent for ${report.source}`);
+    lines.push("");
+    // (1) Recovered intent — LEADS the report (R-003). Intent is the reference
+    //     point, not findings volume.
+    lines.push(withGlyph("classification", "Recovered intent (provisional — recovered from the PR, not agreed):", glyphsOn));
+    if (report.recovered_intent.recovered) {
+        for (const item of report.recovered_intent.items) {
+            lines.push(`  ${item.id} [${JUDGMENT_GLOSS[item.judgment]} · ${SOURCE_GLOSS[item.source]}] ${item.text}`);
+        }
+    }
+    else {
+        lines.push(withGlyph("needs_input", `  ${report.recovered_intent.reason}`, glyphsOn));
+    }
+    if (report.recovered_intent.declares_packet) {
+        lines.push(`  (the PR declares Foo-Spec: ${report.recovered_intent.declares_packet})`);
+    }
+    if (report.recovered_intent.screening.triggered) {
+        lines.push(`  ${report.recovered_intent.screening.stripped.length} injected directive(s) in the PR text were neutralized as inert data.`);
+    }
+    if (report.recovered_intent.redaction.quarantined) {
+        lines.push("  a secret-shaped token in the PR text was quarantined — a human must clear it before --adopt.");
+    }
+    lines.push("");
+    // (2) What the diff actually does.
+    lines.push("What the change does:");
+    if (report.behavior.length) {
+        for (const story of report.behavior)
+            lines.push(`  ${story.id}: ${story.expected_behavior}`);
+    }
+    else {
+        lines.push("  (no changed files in the supplied evidence)");
+    }
+    lines.push("");
+    // (3) Drift / silent scope.
+    lines.push("Drift & silent scope:");
+    const intentOnly = report.drift.filter((d) => d.category === "INTENT_ONLY");
+    const codeOnly = report.drift.filter((d) => d.category === "CODE_ONLY");
+    if (!intentOnly.length && !codeOnly.length) {
+        lines.push("  (recovered intent and the change line up — nothing unmatched)");
+    }
+    for (const d of intentOnly)
+        lines.push(withGlyph("drift", `  [asked, not built] ${d.label}`, glyphsOn));
+    for (const d of codeOnly)
+        lines.push(withGlyph("drift", `  [silent scope — built, not stated] ${d.label}`, glyphsOn));
+    lines.push("  note: deterministic keyword-overlap suggestions over recovered (not agreed) intent — you reconcile.");
+    lines.push("");
+    // (4) Unproven claims — the internal `claimed` state gets an actionable
+    // human label while the report/JSON contract remains unchanged.
+    lines.push(`Proof — ${STATUS_GLYPHS.claimed.label} vs proven:`);
+    lines.push(withGlyph("claimed", `  ${STATUS_GLYPHS.claimed.label}: ${report.proof.claimed.length} recovered intent item(s) — the PR asserts them; typed facts have not proven them.`, glyphsOn));
+    for (const p of report.proof.proven)
+        lines.push(withGlyph("proven", `  proven: ${p}`, glyphsOn));
+    for (const c of report.proof.contradicted)
+        lines.push(withGlyph("drift", `  contradicted: ${c}`, glyphsOn));
+    if (report.proof.checks === "absent")
+        lines.push("  no required checks present — merge/verify state cannot be proven from typed facts.");
+    lines.push("");
+    lines.push("Next: `foo reconcile --source github:<pr-url> --adopt --packet <name>` writes the recovered intent as a spec-after packet you can keep honest with `foo asp reconcile`.");
+    return lines.join("\n");
+}
+function reconcileUsageHandoff() {
+    return [
+        "usage: foo reconcile --source github:<pr-url> [--source-fixture <file.json>] [--json] [--adopt --packet <name> [--by <who>]]",
+        "  Packet-free: recovers a PR's intent, diffs the change against it, reports drift and unproven claims.",
+        "  Read-only by default; --adopt is the only write path.",
+    ].join("\n");
+}
+export function runReconcileCommand(root, args, glyphsOn) {
+    const json = args.includes("--json");
+    const source = flagValue(args, "--source");
+    if (!source)
+        return reconcileUsageFail(`${reconcileUsageHandoff()}\n`);
+    if (!source.startsWith("github:")) {
+        return reconcileUsageFail(`--source '${source}' is not supported; V0 admits only github:<pr-url>\n`);
+    }
+    let selection;
+    try {
+        selection = parseGithubSource(source);
+    }
+    catch (error) {
+        return { exitCode: 1, output: `${error instanceof Error ? error.message : String(error)}\n` };
+    }
+    if (selection.unit !== "pr") {
+        return {
+            exitCode: 1,
+            output: `point foo reconcile at a specific pull request (…/pull/<n>); a whole-repo URL is out of scope for the packet-free wedge: ${selection.url}\n`,
+        };
+    }
+    const fixturePath = flagValue(args, "--source-fixture");
+    if (!fixturePath) {
+        return {
+            exitCode: 1,
+            output: `no GitHub evidence for ${selection.url}. productfoo's CLI has no live GitHub MCP — supply the PR payload with --source-fixture <file.json>, then re-run:\n` +
+                `  foo reconcile --source ${source} --source-fixture <file.json>\n`,
+        };
+    }
+    let fixture;
+    try {
+        fixture = readJson(path.resolve(root, fixturePath));
+    }
+    catch {
+        return { exitCode: 1, output: `--source-fixture is not readable JSON: ${fixturePath}\n` };
+    }
+    const report = buildReconcileReport(source, fixture);
+    // --adopt (T-004): the ONLY write path (D-002). Graduates the one-shot run into
+    // a spec-after packet via the spec-after machinery (specCmd). Refuses when
+    // there is no recoverable intent — never writes a hallucinated contract.
+    if (args.includes("--adopt")) {
+        if (!report.recovered_intent.recovered) {
+            return { exitCode: 1, output: `nothing to adopt: ${report.recovered_intent.reason}\n` };
+        }
+        const packetName = flagValue(args, "--packet");
+        if (!packetName)
+            return reconcileUsageFail("foo reconcile --adopt needs --packet <name>\n");
+        const by = flagValue(args, "--by") ?? "reconcile-adopt";
+        try {
+            const result = adoptReconcileIntent(root, {
+                target: selection.url,
+                recovered: report.recovered_intent,
+                behavior: report.behavior,
+                coverage: report.coverage,
+                packetName,
+                by,
+            });
+            if (json)
+                return { exitCode: result.canonized ? 0 : 1, output: `${JSON.stringify({ schema_version: "0.1", report, adopt: result }, null, 2)}\n` };
+            if (!result.canonized)
+                return { exitCode: 1, output: `Not adopted: ${result.reason}\n` };
+            const rel = packetName.includes("/") ? packetName : `specs/${packetName}`;
+            return {
+                exitCode: 0,
+                output: `${renderReconcileReport(report, glyphsOn)}\n\n` +
+                    `Adopted recovered intent into ${rel} (spec-after draft — provisional, agent-inference).\n` +
+                    `Validate it: foo asp validate ${rel}\n`,
+            };
+        }
+        catch (error) {
+            markFailure(classifyThrown(error));
+            return { exitCode: 1, output: `${error instanceof Error ? error.message : String(error)}\n` };
+        }
+    }
+    if (json)
+        return { exitCode: 0, output: `${JSON.stringify(report, null, 2)}\n` };
+    return { exitCode: 0, output: `${renderReconcileReport(report, glyphsOn)}\n` };
+}

package/dist-public/src/commands/runtime.d.ts

@@ -0,0 +1 @@
+export declare function runRuntimeCommand(args: string[], glyphs: boolean): string;

package/dist-public/src/commands/runtime.js

@@ -0,0 +1,36 @@
+// `foo runtime` reports the active harness AND, when the harness is routed to a
+// non-native model endpoint (e.g. Claude Code pointed at z.ai to run GLM 5.2), the
+// backing-model signal. This is provenance for the judgment ledger: productfoo's runtime
+// identity is the harness, but the model actually answering may be swapped under it.
+// Signal, not boundary — it never blocks and never changes branch prefix or the
+// elicitation surface. The 🏷️ classification glyph is human-surface-only (gated off
+// for --json/piped output by `glyphs`).
+import { detectRuntimeId } from "../elicitationSurface.js";
+import { describeActiveModel, resolveActiveModel } from "../activeModel.js";
+import { withGlyph } from "../statusGlyphs.js";
+export function runRuntimeCommand(args, glyphs) {
+    const runtime = detectRuntimeId();
+    const active = resolveActiveModel();
+    if (args.includes("--json")) {
+        return `${JSON.stringify({ runtime, active }, null, 2)}\n`;
+    }
+    const lines = [`Runtime (harness): ${runtime}`];
+    const note = describeActiveModel(active);
+    if (note) {
+        // ⚠️ when the model is only assumed (inferred from a base URL); 🏷️ when a routed
+        // model is explicitly confirmed. Glyphs are human-surface-only (gated off for --json).
+        const state = active.confidence === "assumed" ? "drift" : "classification";
+        lines.push(withGlyph(state, `Active model:      ${note}`, glyphs));
+        lines.push("  Runtime identity and branch prefix are unchanged — the harness is still " + runtime + ".");
+    }
+    else {
+        lines.push(`Active model:      native (${runtime} running its own model)`);
+    }
+    // Roster/unknown-model findings (model-roster-data-v0 R-003): always worded;
+    // the ⚠️ drift glyph is human-surface-only (gated off for --json above).
+    for (const finding of active.findings) {
+        lines.push(withGlyph("drift", `  finding: ${finding}`, glyphs));
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist-public/src/commands/scanRedact.d.ts

@@ -0,0 +1,8 @@
+export declare function runScanCommand(args: string[]): {
+    output: string;
+    exitCode: number;
+};
+export declare function runRedactCommand(args: string[]): {
+    output: string;
+    exitCode: number;
+};

package/dist-public/src/commands/scanRedact.js

@@ -0,0 +1,266 @@
+import { existsSync, lstatSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseAllowlist, redactText, scanText } from "../redactEngine.js";
+// Argument validation throws UsageError, never a bare Error: a mistyped flag is a
+// typo, and a bare Error classifies as command_error — which pages and files a Bug
+// Capsule. See src/errorTaxonomy.ts.
+import { UsageError } from "../errorTaxonomy.js";
+// --- foo scan (prompt_redaction_safety_v0 T-001) -----------------------------
+// Thin IO wrapper over the pure redactEngine: walk files/dirs/stdin, scan each,
+// print metadata-only findings. The engine never returns secret values (R-007).
+const SCAN_SKIP_DIRS = new Set([".git", "node_modules", "dist", ".worktrees"]);
+// Crude binary guard: a NUL byte in the first chunk means skip (not text).
+function isProbablyText(buf) {
+    const n = Math.min(buf.length, 4096);
+    for (let i = 0; i < n; i++)
+        if (buf[i] === 0)
+            return false;
+    return true;
+}
+// A path the walk declines to scan is surfaced, never silently dropped.
+function skipScanTarget(target, skipped, reason) {
+    skipped.push({ file: path.relative(process.cwd(), target) || target, reason });
+}
+function collectScanTargets(target, acc, skipped) {
+    const stat = lstatSync(target);
+    // lstat sees a symlink as neither file nor directory, which is how #777
+    // silently dropped linked files — a secret-detection blindspot. Resolve one
+    // hop with statSync so the real file gets scanned; an unresolvable link
+    // (dangling, looped) surfaces as a broken-symlink skip. Links to directories
+    // are not followed (a cycle would not terminate) and special files (fifo,
+    // socket) cannot be read as text — both surface as skips so the contract at
+    // the skipped list below holds for every path the walk visits.
+    if (stat.isSymbolicLink()) {
+        let resolved;
+        try {
+            resolved = statSync(target);
+        }
+        catch {
+            skipScanTarget(target, skipped, "broken-symlink");
+            return;
+        }
+        if (resolved.isFile())
+            acc.push(target);
+        else
+            skipScanTarget(target, skipped, resolved.isDirectory() ? "symlinked-directory" : "symlinked-special");
+        return;
+    }
+    if (stat.isDirectory()) {
+        if (SCAN_SKIP_DIRS.has(path.basename(target)))
+            return;
+        for (const entry of readdirSync(target).sort())
+            collectScanTargets(path.join(target, entry), acc, skipped);
+    }
+    else if (stat.isFile()) {
+        acc.push(target);
+    }
+}
+export function runScanCommand(args) {
+    const json = args.includes("--json");
+    const exitOnFindings = args.includes("--exit-code");
+    let minEntropyLen = 20;
+    let profiles;
+    const allowlist = [];
+    const positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json" || arg === "--exit-code")
+            continue;
+        if (arg === "--profile") {
+            const value = args[++i];
+            if (value)
+                profiles = value.split(",").map((s) => s.trim()).filter(Boolean);
+            continue;
+        }
+        if (arg === "--allow") {
+            const file = args[++i];
+            if (!file)
+                throw new UsageError("--allow needs a file path", "E_BAD_FLAG");
+            allowlist.push(...parseAllowlist(readFileSync(path.resolve(process.cwd(), file), "utf8")));
+            continue;
+        }
+        if (arg === "--min-entropy-len") {
+            const n = Number(args[++i]);
+            if (Number.isFinite(n) && n > 0)
+                minEntropyLen = n;
+            continue;
+        }
+        if (arg.startsWith("--"))
+            throw new UsageError(`unknown scan flag: ${arg}`, "E_BAD_FLAG");
+        positionals.push(arg);
+    }
+    const opts = { allowlist, minEntropyLen, profiles };
+    const results = [];
+    const targets = positionals.filter((p) => p !== "-");
+    const wantStdin = positionals.includes("-") || (positionals.length === 0 && !process.stdin.isTTY);
+    if (positionals.length === 0 && process.stdin.isTTY) {
+        throw new UsageError("scan target missing: pass a file, a directory, or - for stdin", "E_BAD_FLAG");
+    }
+    if (wantStdin)
+        results.push({ file: "<stdin>", result: scanText(readFileSync(0, "utf8"), opts) });
+    const files = [];
+    const skipped = [];
+    for (const p of targets) {
+        const resolved = path.resolve(process.cwd(), p);
+        if (!existsSync(resolved))
+            throw new Error(`scan target not found: ${p}`);
+        collectScanTargets(resolved, files, skipped);
+    }
+    // A skipped file is surfaced, never silently dropped: an unscanned path is a
+    // coverage gap the caller must be able to see (blindspot: NUL-early binaries).
+    for (const file of files.sort()) {
+        const rel = path.relative(process.cwd(), file) || file;
+        let buf;
+        try {
+            buf = readFileSync(file);
+        }
+        catch {
+            skipped.push({ file: rel, reason: "unreadable" });
+            continue;
+        }
+        if (!isProbablyText(buf)) {
+            skipped.push({ file: rel, reason: "binary" });
+            continue;
+        }
+        results.push({ file: rel, result: scanText(buf.toString("utf8"), opts) });
+    }
+    const totals = { high: 0, medium: 0, low: 0, total: 0 };
+    for (const r of results) {
+        totals.high += r.result.counts.high;
+        totals.medium += r.result.counts.medium;
+        totals.low += r.result.counts.low;
+        totals.total += r.result.counts.total;
+    }
+    // Pure reporting by default (exit 0). --exit-code makes high-confidence
+    // findings non-zero for scripting; the blocking gate proper is T-003.
+    const exitCode = exitOnFindings && totals.high > 0 ? 2 : 0;
+    if (json) {
+        const payload = { schema_version: "0.1", scanned: results.length, skipped, totals, results };
+        return { output: `${JSON.stringify(payload, null, 2)}\n`, exitCode };
+    }
+    const lines = ["foo scan", ""];
+    const withFindings = results.filter((r) => r.result.findings.length > 0);
+    if (withFindings.length === 0) {
+        lines.push(`  no secrets detected across ${results.length} file(s).`);
+    }
+    else {
+        for (const r of withFindings) {
+            lines.push(r.file);
+            for (const f of r.result.findings) {
+                const ent = f.entropy !== undefined ? ` entropy=${f.entropy}` : "";
+                lines.push(`  ${f.line}:${f.column}  [${f.confidence}] ${f.detector} (len ${f.length})${ent}`);
+            }
+            lines.push("");
+        }
+    }
+    lines.push(`Totals: ${totals.high} high · ${totals.medium} medium · ${totals.low} low (${totals.total} findings, ${results.length} file(s))`);
+    if (skipped.length > 0) {
+        lines.push(`Skipped (not scanned): ${skipped.length} file(s)`);
+        for (const s of skipped)
+            lines.push(`  ${s.file} — ${s.reason}`);
+    }
+    lines.push("Note: scan reports; the fail-closed commit gate (T-003) decides what blocks. Secret values are never shown (R-007).");
+    lines.push("");
+    return { output: lines.join("\n"), exitCode };
+}
+// --- foo redact (prompt_redaction_safety_v0 T-002) ---------------------------
+// Replace detected secrets with consistent, irreversible placeholders and emit
+// a metadata-only receipt (R-002, R-003). Default prints redacted output to
+// stdout (non-mutating); --write overwrites the file (explicit), --dry-run
+// previews the receipt and changed lines without writing.
+function renderRedactionReceipt(receipt) {
+    const lines = [
+        `Redactions: ${receipt.redactions}  (${receipt.by_confidence.high} high · ${receipt.by_confidence.medium} medium · ${receipt.by_confidence.low} low)`,
+    ];
+    const types = Object.keys(receipt.by_type).sort();
+    if (types.length)
+        lines.push(`  by type: ${types.map((t) => `${t}=${receipt.by_type[t]}`).join(", ")}`);
+    if (receipt.placeholders.length)
+        lines.push(`  placeholders: ${receipt.placeholders.join(", ")}`);
+    if (receipt.kept.length) {
+        lines.push(`  kept for review (below threshold): ${receipt.kept.length}`);
+        for (const k of receipt.kept)
+            lines.push(`    ${k.line}:${k.column} ${k.detector} [${k.confidence}] — ${k.reason}`);
+    }
+    return lines;
+}
+export function runRedactCommand(args) {
+    const json = args.includes("--json");
+    const dryRun = args.includes("--dry-run");
+    const write = args.includes("--write");
+    let threshold = "medium";
+    if (args.includes("--high-only"))
+        threshold = "high";
+    if (args.includes("--include-low"))
+        threshold = "low";
+    let minEntropyLen = 20;
+    let profiles;
+    const allowlist = [];
+    const positionals = [];
+    const flags = new Set(["--json", "--dry-run", "--write", "--high-only", "--include-low"]);
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (flags.has(arg))
+            continue;
+        if (arg === "--profile") {
+            const value = args[++i];
+            if (value)
+                profiles = value.split(",").map((s) => s.trim()).filter(Boolean);
+            continue;
+        }
+        if (arg === "--allow") {
+            const file = args[++i];
+            if (!file)
+                throw new UsageError("--allow needs a file path", "E_BAD_FLAG");
+            allowlist.push(...parseAllowlist(readFileSync(path.resolve(process.cwd(), file), "utf8")));
+            continue;
+        }
+        if (arg === "--min-entropy-len") {
+            const n = Number(args[++i]);
+            if (Number.isFinite(n) && n > 0)
+                minEntropyLen = n;
+            continue;
+        }
+        if (arg.startsWith("--"))
+            throw new UsageError(`unknown redact flag: ${arg}`, "E_BAD_FLAG");
+        positionals.push(arg);
+    }
+    if (positionals.length > 1)
+        throw new UsageError("redact accepts one file or - for stdin", "E_BAD_FLAG");
+    const target = positionals[0];
+    const fromStdin = !target || target === "-";
+    if (write && fromStdin)
+        throw new UsageError("--write needs a file target (not stdin)", "E_BAD_FLAG");
+    if (!target && process.stdin.isTTY)
+        throw new UsageError("redact target missing: pass a file or - for stdin", "E_BAD_FLAG");
+    const inputPath = fromStdin ? null : path.resolve(process.cwd(), target);
+    if (inputPath && !existsSync(inputPath))
+        throw new Error(`redact target not found: ${target}`);
+    const text = fromStdin ? readFileSync(0, "utf8") : readFileSync(inputPath, "utf8");
+    const { redactedText, receipt } = redactText(text, { allowlist, minEntropyLen, threshold, profiles });
+    if (json) {
+        return { output: `${JSON.stringify({ schema_version: "0.1", receipt, redactedText }, null, 2)}\n`, exitCode: 0 };
+    }
+    if (dryRun) {
+        const origLines = text.split("\n");
+        const redLines = redactedText.split("\n");
+        const changed = [];
+        for (let i = 0; i < redLines.length; i++) {
+            if (origLines[i] !== redLines[i])
+                changed.push(`  ${i + 1}: ${redLines[i]}`);
+        }
+        const lines = ["foo redact --dry-run", "", ...renderRedactionReceipt(receipt), ""];
+        if (changed.length)
+            lines.push("Preview (redacted lines — secret values already removed):", ...changed, "");
+        lines.push("(--dry-run: no output emitted, no file written. Drop --dry-run to emit; add --write to overwrite the file.)");
+        lines.push("");
+        return { output: lines.join("\n"), exitCode: 0 };
+    }
+    if (write && inputPath) {
+        writeFileSync(inputPath, redactedText);
+        const rel = path.relative(process.cwd(), inputPath) || target;
+        return { output: [`foo redact — wrote ${rel}`, "", ...renderRedactionReceipt(receipt), ""].join("\n"), exitCode: 0 };
+    }
+    // Default: emit redacted content to stdout (non-mutating).
+    return { output: redactedText, exitCode: 0 };
+}

package/dist-public/src/commands/setup.d.ts

@@ -0,0 +1,28 @@
+import { type ChannelFreshness } from "../channelFreshness.js";
+type HooksWiringState = "wired" | "unset-safe" | "conflict" | "no-dir";
+export declare function hooksWiringPlan(input: {
+    dirPresent: boolean;
+    currentHooksPath: string | null;
+}): {
+    state: HooksWiringState;
+    wired: boolean;
+};
+export declare function wireHooks(): string;
+type BuildFreshnessState = "no-src" | "no-build" | "fresh" | "stale";
+export declare function buildFreshnessPlan(input: {
+    newestSrcMtimeMs: number | null;
+    distMtimeMs: number | null;
+}): {
+    state: BuildFreshnessState;
+    stale: boolean;
+};
+export type ResearchGateWiring = {
+    label: string;
+    format: string;
+    wired: boolean;
+};
+export declare function researchGateWiring(root: string): ResearchGateWiring[];
+export declare function currentHarnessLabel(env?: NodeJS.ProcessEnv): string | null;
+export declare function researchGateDoctorLine(wiring: ResearchGateWiring[], currentLabel: string | null): string;
+export declare function renderDoctor(root: string, format: "text" | "json", selfRoot?: string, freshness?: ChannelFreshness, homeRoot?: string, now?: () => string): string;
+export {};