@lannguyensi/harness 0.32.0 → 0.34.0

package/dist/cli/index.js

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { Command } from "commander";
 // Production version probe for `harness doctor`: synchronous --version
@@ -33,6 +34,7 @@ import { runPackHookCodexPreToolUseCli } from "./pack/hook-codex-pre-tool-use.js
 import { runPackHookCodexStopCli } from "./pack/hook-codex-stop.js";
 import { runPackHookCodexUserPromptSubmitCli } from "./pack/hook-codex-user-prompt-submit.js";
 import { isRuntime, KNOWN_RUNTIMES } from "../policy-packs/index.js";
+import { approveBranchProtection } from "./approve/branch-protection.js";
 import { approveRisk } from "./approve/risk.js";
 import { approveUnderstanding } from "./approve/understanding.js";
 import { describe, isPillar } from "./describe.js";
@@ -64,6 +66,7 @@ import { runPackHookSolutionAcceptanceWriteguardCli } from "./pack/hook-solution
 import { runPackHookRuntimeRealityCli } from "./pack/hook-runtime-reality.js";
 import { gateDisable, GateDisableError } from "./gate/disable.js";
 import { gateEnable, GateEnableError } from "./gate/enable.js";
+import { DEFAULT_RETENTION_DAYS, gc } from "./gc/index.js";
 import { uninstall, UninstallError } from "./uninstall/index.js";
 import { migrateHome } from "./migrate-home/index.js";
 import { pause as pauseHarness, resume as resumeHarness } from "./pause/index.js";
@@ -127,6 +130,7 @@ export function buildProgram(opts = {}) {
         .option("--project <name>", "apply per-project overrides for this project name")
         .option("--strict", "promote warnings to errors")
         .option("--check-lock", "surface harness.lock asset-content drift as warnings (or errors with --strict)")
+        .option("--json", "emit a structured JSON report ({ diagnostics, errorCount, warningCount }) instead of prose")
         .action((options) => {
         const result = validate({
             configPath: options.config,
@@ -134,11 +138,22 @@ export function buildProgram(opts = {}) {
             strict: options.strict,
             checkLock: options.checkLock,
         });
-        const report = formatReport(result);
-        if (result.diagnostics.length > 0)
-            stderr(report);
-        else
-            stdout(report);
+        if (options.json) {
+            // JSON goes to stdout regardless of outcome so pipelines can
+            // always parse it; the exit code still carries pass/fail.
+            stdout(`${JSON.stringify({
+                diagnostics: result.diagnostics,
+                errorCount: result.errorCount,
+                warningCount: result.warningCount,
+            }, null, 2)}\n`);
+        }
+        else {
+            const report = formatReport(result);
+            if (result.diagnostics.length > 0)
+                stderr(report);
+            else
+                stdout(report);
+        }
         if (result.errorCount > 0) {
             throw new HarnessExitError("", EX_FAIL);
         }
@@ -463,7 +478,8 @@ export function buildProgram(opts = {}) {
         .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides for this project name")
         .option("--dry-run", "print the would-be diff + restart hints; do not write")
-        .option("--overwrite-drift", "discard any on-disk hand-edits to harness.generated/ files (prompts for `yes`)")
+        .option("--overwrite-drift", "discard any on-disk hand-edits to harness.generated/ files (prompts for `yes`; pair with --yes for non-interactive runs)")
+        .option("--yes", "with --overwrite-drift, skip the confirmation prompt (for non-interactive use)")
         .option("--strict-lock", "refuse with exit 1 (no write) when harness.lock asset drift is detected; dry-run wins")
         .option("--target <path>", "additionally write the generated settings.json to <path> (e.g. .claude/settings.local.json)")
         .option("--merge", "with --target, 3-way merge into an existing target file (replace owned keys, preserve others)")
@@ -494,6 +510,7 @@ export function buildProgram(opts = {}) {
             ...(options.project !== undefined ? { project: options.project } : {}),
             ...(options.dryRun ? { dryRun: true } : {}),
             ...(options.overwriteDrift ? { overwriteDrift: true } : {}),
+            ...(options.yes ? { yes: true } : {}),
             ...(options.strictLock ? { strictLock: true } : {}),
             ...(options.target !== undefined ? { target: options.target } : {}),
             ...(options.merge ? { merge: true } : {}),
@@ -835,7 +852,8 @@ export function buildProgram(opts = {}) {
         .command("branch-protection")
         .description("PreToolUse blocker for the branch-protection pack: read tool-event JSON from stdin, consult the " +
         "evidence ledger, emit a deny envelope on protected branches unless either a fresh " +
-        "`branch:non-protected` tag (within 5m) or a `branch-protection-ack` override is present.")
+        "`branch:non-protected` tag (within 5m) or the operator-only override marker " +
+        "(written by `harness approve branch-protection`) is present.")
         .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
         .option("--project <name>", "apply per-project overrides")
         .option("--ledger-timeout <ms>", "per-call ledger timeout in milliseconds")
@@ -1064,6 +1082,11 @@ export function buildProgram(opts = {}) {
                 ? "; stamped sessionId"
                 : "";
             lines.push(`report:  ✓ ${result.persistedReport.filePath} (approvalStatus: ${prev} → approved${stampNote})`);
+            const fb = result.persistedReport.fallbackAdopted;
+            if (fb) {
+                lines.push(`  ⚠ adopted via sessionId-less fallback: created ${fb.createdAt ?? "<unknown>"} (${fb.ageMinutes}m ago).`);
+                lines.push("  The live session's report was never persisted, or an older producer", "  wrote it without a sessionId. Verify this is the report you just read", "  before trusting the approval.");
+            }
         }
         else {
             lines.push(`report:  ⚠ skipped (${result.persistedReport.reason})`);
@@ -1170,6 +1193,58 @@ export function buildProgram(opts = {}) {
         }
         stdout(`${lines.join("\n")}\n`);
     });
+    approveCmd
+        .command("branch-protection")
+        .description("Bless a deliberate protected-branch edit for one session. Writes the canonical " +
+        "operator-only approval marker under harness.generated/.approvals/ that the " +
+        "branch-protection blocker consults, plus a best-effort branch-protection-ack " +
+        "ledger row for audit. Operator action: the marker (not the ledger tag) is the " +
+        "trusted override, because the ledger is agent-writable.")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--project <name>", "apply per-project overrides")
+        .option("--session <id>", "explicit session id (default: $CLAUDE_CODE_SESSION_ID, then $CLAUDE_SESSION_ID, then $CODEX_SESSION_ID, then staged .pending-approval)")
+        .option("--reason <text>", "free-form note recorded in the audit ledger tag (why the override fired)")
+        .option("--approved-by <actor>", "actor to record on the marker (default: harness-approve-cli)")
+        .action(async (options) => {
+        const cliOpts = {};
+        if (options.config)
+            cliOpts.configPath = options.config;
+        if (options.project)
+            cliOpts.project = options.project;
+        if (options.session)
+            cliOpts.session = options.session;
+        if (options.reason)
+            cliOpts.reason = options.reason;
+        if (options.approvedBy)
+            cliOpts.approvedBy = options.approvedBy;
+        const result = await approveBranchProtection(cliOpts);
+        const lines = [];
+        const sourceNote = result.sessionSource === "pending-approval"
+            ? " (resolved from .pending-approval staged by the gate hook)"
+            : result.sessionSource === "env-claude-code"
+                ? " (from $CLAUDE_CODE_SESSION_ID)"
+                : result.sessionSource === "env-claude"
+                    ? " (from $CLAUDE_SESSION_ID)"
+                    : result.sessionSource === "env-codex"
+                        ? " (from $CODEX_SESSION_ID)"
+                        : "";
+        lines.push(`session: ${result.sessionId}${sourceNote}`);
+        if (result.marker.ok) {
+            lines.push(`marker:  ✓ ${result.marker.filePath} (canonical gate signal)`);
+            lines.push("  the branch-protection gate now allows protected-branch edits for this session.");
+        }
+        else {
+            lines.push(`marker:  ✗ FAILED (${result.marker.reason})`);
+            lines.push("  the gate WILL keep blocking the next tool call until the marker exists.");
+        }
+        if (result.ledger.ok) {
+            lines.push(`ledger:  ✓ wrote ${result.ledger.tag} (audit only)`);
+        }
+        else {
+            lines.push(`ledger:  ⚠ skipped (${result.ledger.reason ?? "unknown"}) (audit only)`);
+        }
+        stdout(`${lines.join("\n")}\n`);
+    });
     const VALID_DECISION_FILTERS = [
         "allow",
         "warn",
@@ -1635,18 +1710,77 @@ export function buildProgram(opts = {}) {
             throw err;
         }
     });
+    program
+        .command("gc")
+        .description("Retention-based cleanup of harness-owned gate state: terminal " +
+        "(approved/expired) understanding-gate reports, parse-error logs, and " +
+        "approval markers older than the retention window. Pending reports and " +
+        "anything outside the enumerated harness-owned dirs are never touched " +
+        "(the evidence ledger and solution-acceptance verdict dirs are owned by " +
+        "their producers). Dry-run by default; pass --apply to delete.")
+        .option("--config <path>", "manifest path (default: ~/.harness/harness.yaml; legacy fallback ~/.claude/harness.yaml)")
+        .option("--retention-days <n>", `delete artifacts older than this many days (default: ${DEFAULT_RETENTION_DAYS})`)
+        .option("--apply", "delete the listed artifacts (default: dry-run listing only)")
+        .action((options) => {
+        const cliOpts = {};
+        if (options.config)
+            cliOpts.configPath = options.config;
+        if (options.apply)
+            cliOpts.apply = true;
+        if (options.retentionDays !== undefined) {
+            const parsed = Number(options.retentionDays);
+            if (!Number.isFinite(parsed) || parsed < 1) {
+                stderr(`--retention-days must be a positive number, got ${JSON.stringify(options.retentionDays)}\n`);
+                throw new HarnessExitError("", EX_USAGE);
+            }
+            cliOpts.retentionDays = parsed;
+        }
+        const result = gc(cliOpts);
+        const sweptDirs = [
+            result.reportsDir,
+            ...(result.parseErrorsDir !== null ? [result.parseErrorsDir] : []),
+            result.approvalsDir,
+        ];
+        if (result.parseErrorsDir === null) {
+            stderr("gc: skipping the parse-errors sweep (reports dir does not have the conventional .understanding-gate/reports shape)\n");
+        }
+        if (result.candidates.length === 0) {
+            stdout(`gc: nothing older than ${result.retentionDays}d (cutoff ${result.cutoffIso}) under\n` +
+                sweptDirs.map((d) => `  ${d}\n`).join("") +
+                `${result.keptCount} artifact(s) inspected and kept.\n`);
+            return;
+        }
+        const verb = result.applied ? "removing" : "would remove";
+        stdout(`gc: ${verb} ${result.candidates.length} artifact(s) older than ${result.retentionDays}d (cutoff ${result.cutoffIso}); keeping ${result.keptCount}:\n`);
+        for (const c of result.candidates) {
+            stdout(`  [${c.category}] ${c.filePath} (${c.reason})\n`);
+        }
+        if (!result.applied) {
+            stdout(`\nDry-run; pass --apply to delete.\n`);
+            return;
+        }
+        stdout(`removed ${result.removed.length} file(s).\n`);
+        if (result.failures.length > 0) {
+            for (const f of result.failures) {
+                stderr(`gc: failed to remove ${f.filePath}: ${f.reason}\n`);
+            }
+            throw new HarnessExitError(`${result.failures.length} deletion(s) failed`, EX_FAIL);
+        }
+    });
     program
         .command("uninstall")
         .description("Clean teardown of a harness installation. Inventories harness-owned " +
-        "entries in ~/.claude/ (manifest, lock, harness.generated/, hook groups " +
-        "and mcpServers in settings.json) and prints them. With --apply, removes " +
-        "them after writing a reversible settings.json backup + snapshot. " +
+        "state (manifest, lock, harness.generated/, .understanding-gate/ under " +
+        "the state root; hook groups and mcpServers in ~/.claude/settings.json) " +
+        "and prints it. With --apply, removes it after writing a reversible " +
+        "settings.json backup + snapshot. " +
         "settings.json.pre-harness-<TS> backups are listed but never deleted, " +
         "so the operator can hand them to --restore-from <path> (atomic restore " +
         "from that file) or `rm` them manually.")
         .option("--apply", "execute the teardown (default: dry-run listing only)")
         .option("--restore-from <path>", "atomic restore: copy this file over settings.json instead of selective removal (implies --apply)")
-        .option("--home <path>", "override ~/.claude/ root (for tests / non-default installs)")
+        .option("--home <path>", "override ~/.claude/ (settings home; without --state it also overrides the state root, for tests / non-default installs)")
+        .option("--state <path>", "override the harness state root (default: ~/.harness/, legacy fallback ~/.claude/)")
         .option("--settings <path>", "override ~/.claude/settings.json")
         .action(async (options) => {
         const cliOpts = {};
@@ -1656,6 +1790,8 @@ export function buildProgram(opts = {}) {
             cliOpts.restoreFrom = options.restoreFrom;
         if (options.home)
             cliOpts.homeDir = options.home;
+        if (options.state)
+            cliOpts.stateDir = options.state;
         if (options.settings)
             cliOpts.settingsPath = options.settings;
         try {
@@ -1665,22 +1801,28 @@ export function buildProgram(opts = {}) {
                 const nothing = inv.manifestPath === null &&
                     inv.lockPath === null &&
                     inv.generatedDir === null &&
+                    inv.gateStateDir === null &&
                     inv.hookGroups.length === 0 &&
                     inv.mcpServers.length === 0 &&
                     inv.preHarnessBackups.length === 0;
+                const rootsLabel = inv.stateDir === inv.homeDir
+                    ? inv.homeDir
+                    : `${inv.stateDir} (state) + ${inv.homeDir} (settings)`;
                 if (nothing) {
-                    stdout(`no harness install found under ${inv.homeDir}; nothing to do.\n`);
+                    stdout(`no harness install found under ${rootsLabel}; nothing to do.\n`);
                     for (const w of inv.warnings)
                         stderr(`warning: ${w}\n`);
                     return;
                 }
-                stdout(`harness install under ${inv.homeDir}:\n`);
+                stdout(`harness install under ${rootsLabel}:\n`);
                 if (inv.manifestPath)
                     stdout(`  manifest:  ${inv.manifestPath}\n`);
                 if (inv.lockPath)
                     stdout(`  lock:      ${inv.lockPath}\n`);
                 if (inv.generatedDir)
                     stdout(`  generated: ${inv.generatedDir}/\n`);
+                if (inv.gateStateDir)
+                    stdout(`  gate:      ${inv.gateStateDir}/ (understanding-gate state)\n`);
                 if (inv.hookGroups.length > 0) {
                     stdout(`  hook groups in ${inv.settingsPath}:\n`);
                     for (const g of inv.hookGroups) {
@@ -1734,11 +1876,29 @@ export function buildProgram(opts = {}) {
                 stdout(`removed from disk:\n`);
                 for (const f of result.removedFiles)
                     stdout(`  ${f}\n`);
+                // Explicit kept-list: name whatever survives under the state
+                // root (machines/ + projects/ override layers are
+                // operator-authored; foreign files are not ours to judge) so
+                // the operator never has to discover residue by accident.
+                try {
+                    const residue = fs
+                        .readdirSync(inv.stateDir)
+                        .filter((name) => !name.startsWith("settings.json"));
+                    if (residue.length > 0) {
+                        stdout(`kept under ${inv.stateDir}: ${residue.join(", ")} (not removed; operator-authored or out of scope)\n`);
+                    }
+                }
+                catch {
+                    /* state root itself may be gone or unreadable; nothing to report */
+                }
             }
             if (result.backupPath === null &&
                 result.snapshotPath === null &&
                 result.removedFiles.length === 0) {
-                stdout(`no harness install found under ${inv.homeDir}; nothing to remove.\n`);
+                const rootsLabel = inv.stateDir === inv.homeDir
+                    ? inv.homeDir
+                    : `${inv.stateDir} (state) + ${inv.homeDir} (settings)`;
+                stdout(`no harness install found under ${rootsLabel}; nothing to remove.\n`);
             }
             else {
                 stdout(`\nTo finish: \`npm uninstall -g @lannguyensi/harness\` (uninstall does not touch the npm install).\n`);