@lannguyensi/harness 0.15.0 → 0.16.0

package/dist/cli/session-start/branch-check.js

@@ -0,0 +1,165 @@
+// `harness session-start branch-check` — SessionStart hook entrypoint
+// for the `branch-protection` policy pack.
+//
+// Reads `.git/HEAD` for the cwd and, when the current branch is NOT in
+// the operator's protected list, writes a `branch:non-protected:<branch>`
+// fact to the evidence ledger so the pack's PreToolUse blocker has a
+// fresh tag to satisfy its 5-minute freshness window.
+//
+// SessionStart contract: `blocking:false`. Every failure path (no git
+// dir, manifest load fails, no grounding-mcp wired, ledger write
+// fails) logs one line to stderr and exits 0. The only observable
+// effect of a failure is that the blocker stays closed, which is the
+// safe default: a session that can't prove it's NOT on a protected
+// branch is treated as if it might be.
+//
+// Detached HEAD (`branch === ""`) is treated as PROTECTED: we can't
+// audit-by-name what the agent might commit. The producer leaves the
+// tag unwritten and stderr-notes the reason.
+//
+// Re-runnable on demand from the operator's `!` shell with no event
+// JSON piped on stdin — same CLI verb, no SessionStart event needed.
+import { addLedgerFact, resolveGitContext, } from "../../runtime/index.js";
+import { resolveReadSessionId, } from "../../runtime/session-id.js";
+import { DEFAULT_PROTECTED_BRANCHES, isProtectedBranch, NON_PROTECTED_TAG_PREFIX, PACK_NAME, resolveProtectedBranches, } from "../../policy-packs/builtin/branch-protection-runtime.js";
+import { loadManifest } from "../loader.js";
+const FALLBACK_SESSION = "default";
+const LEDGER_SOURCE = "harness-session-start-branch-check";
+async function readStdin(stream) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk) => {
+            data += chunk;
+        });
+        stream.on("end", () => resolve(data));
+        stream.on("error", reject);
+    });
+}
+function findGroundingMcp(manifest) {
+    return manifest.tools.mcp.find((m) => m.name === "grounding-mcp") ?? null;
+}
+function mcpCommandList(server) {
+    return Array.isArray(server.command)
+        ? server.command
+        : server.command.trim().split(/\s+/);
+}
+export async function runSessionStartBranchCheck(opts = {}) {
+    const stdin = opts.stdin ?? process.stdin;
+    const stderr = opts.stderr ?? process.stderr;
+    const note = (msg) => {
+        stderr.write(`harness session-start branch-check: ${msg}\n`);
+    };
+    const done = (wrote, branch, isProtected, sessionId, sessionSource, reason) => ({
+        exitCode: 0,
+        wrote,
+        branch,
+        protected: isProtected,
+        sessionId,
+        sessionSource,
+        ...(reason !== undefined && { reason }),
+    });
+    let event;
+    try {
+        event = JSON.parse((await readStdin(stdin)).trim() || "{}");
+    }
+    catch (err) {
+        const reason = `malformed event JSON: ${err.message}`;
+        note(reason);
+        return done(false, "", false, FALLBACK_SESSION, "default", reason);
+    }
+    const cwd = typeof opts.cwd === "string" && opts.cwd.length > 0
+        ? opts.cwd
+        : typeof event.cwd === "string" && event.cwd.length > 0
+            ? event.cwd
+            : process.cwd();
+    const { branch } = resolveGitContext(cwd);
+    // Load manifest to resolve the pack's protected_branches override.
+    // Fallback to defaults on any load failure (the producer's job is
+    // best-effort; an unresolvable manifest still permits a sane gate).
+    let manifest = null;
+    if (opts.manifest) {
+        manifest = opts.manifest;
+    }
+    else {
+        try {
+            manifest = loadManifest(opts).manifest;
+        }
+        catch (err) {
+            note(`manifest load failed: ${err.message}; falling back to default protected list`);
+        }
+    }
+    const pack = manifest?.policy_packs.find((p) => p.name === PACK_NAME);
+    const { branches: protectedList, warning: protectedWarning } = pack
+        ? resolveProtectedBranches(pack)
+        : { branches: [...DEFAULT_PROTECTED_BRANCHES], warning: null };
+    if (protectedWarning)
+        note(protectedWarning);
+    // Resolve session id with the same precedence chain as
+    // session-start/preflight so the two producers stay symmetric.
+    const explicit = typeof opts.session === "string" && opts.session.length > 0
+        ? opts.session
+        : typeof event.session_id === "string" && event.session_id.length > 0
+            ? event.session_id
+            : undefined;
+    const resolveSession = opts.resolveSession ?? resolveReadSessionId;
+    const sessionId = resolveSession(explicit, {});
+    const sessionSource = typeof opts.session === "string" && opts.session.length > 0
+        ? "flag"
+        : typeof event.session_id === "string" && event.session_id.length > 0
+            ? "stdin"
+            : sessionId === FALLBACK_SESSION
+                ? "default"
+                : typeof process.env.CLAUDE_SESSION_ID === "string" &&
+                    process.env.CLAUDE_SESSION_ID === sessionId
+                    ? "env"
+                    : "transcript";
+    if (branch === "") {
+        const reason = `cwd is not on a named branch (detached HEAD or outside a git work tree); leaving the gate closed (treated as protected)`;
+        note(reason);
+        return done(false, "", true, sessionId, sessionSource, reason);
+    }
+    const isProtected = isProtectedBranch(branch, protectedList);
+    if (isProtected) {
+        const reason = `branch "${branch}" is in the protected list (${protectedList.join(", ")}); leaving the gate closed`;
+        note(reason);
+        return done(false, branch, true, sessionId, sessionSource, reason);
+    }
+    // Branch is non-protected: write the tag.
+    const content = `${NON_PROTECTED_TAG_PREFIX}:${branch}`;
+    let writeLedger = opts.writeLedger;
+    if (!writeLedger) {
+        if (!manifest) {
+            const reason = `manifest unavailable; cannot record ${content}`;
+            note(reason);
+            return done(false, branch, false, sessionId, sessionSource, reason);
+        }
+        const server = findGroundingMcp(manifest);
+        if (!server) {
+            const reason = `grounding-mcp not declared in manifest; cannot record ${content}`;
+            note(reason);
+            return done(false, branch, false, sessionId, sessionSource, reason);
+        }
+        const command = mcpCommandList(server);
+        const env = server.env ?? undefined;
+        const timeoutMs = opts.ledgerTimeoutMs ?? server.health?.timeout_ms ?? 5_000;
+        writeLedger = (args) => addLedgerFact({
+            mcpCommand: command,
+            ...(env && { mcpEnv: env }),
+            timeoutMs,
+            ...args,
+        });
+    }
+    const result = await writeLedger({ sessionId, content, source: LEDGER_SOURCE });
+    if (!result.ok) {
+        const reason = `ledger write failed: ${result.reason ?? "unknown error"}`;
+        note(reason);
+        return done(false, branch, false, sessionId, sessionSource, reason);
+    }
+    note(`recorded ${content} for session ${sessionId}`);
+    if (sessionSource === "default") {
+        note("WARNING: session resolved to the literal \"default\". The blocker queries the real Claude Code session id and will NOT see this tag. Pipe SessionStart event JSON on stdin, export $CLAUDE_SESSION_ID, or pass --session <id>.");
+    }
+    return done(true, branch, false, sessionId, sessionSource);
+}
+//# sourceMappingURL=branch-check.js.map

package/dist/cli/session-start/branch-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-check.js","sourceRoot":"","sources":["../../../src/cli/session-start/branch-check.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,2CAA2C;AAC3C,EAAE;AACF,uEAAuE;AACvE,0EAA0E;AAC1E,qEAAqE;AACrE,sDAAsD;AACtD,EAAE;AACF,sEAAsE;AACtE,iEAAiE;AACjE,kEAAkE;AAClE,qEAAqE;AACrE,mEAAmE;AACnE,uCAAuC;AACvC,EAAE;AACF,oEAAoE;AACpE,qEAAqE;AACrE,6CAA6C;AAC7C,EAAE;AACF,oEAAoE;AACpE,qEAAqE;AAErE,OAAO,EACL,aAAa,EACb,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,oBAAoB,GAErB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,wBAAwB,EACxB,SAAS,EACT,wBAAwB,GACzB,MAAM,yDAAyD,CAAC;AAEjE,OAAO,EAAE,YAAY,EAAsB,MAAM,cAAc,CAAC;AAEhE,MAAM,gBAAgB,GAAG,SAAS,CAAC;AACnC,MAAM,aAAa,GAAG,oCAAoC,CAAC;AA+C3D,KAAK,UAAU,SAAS,CAAC,MAA6B;IACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAC3B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAClC,IAAI,IAAI,KAAK,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAkB;IAC1C,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,eAAe,CAAC,IAAI,IAAI,CAAC;AAC5E,CAAC;AAED,SAAS,cAAc,CAAC,MAAiB;IACvC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;QAClC,CAAC,CAAC,MAAM,CAAC,OAAO;QAChB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,OAAuC,EAAE;IAEzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAC7C,MAAM,IAAI,GAAG,CAAC,GAAW,EAAQ,EAAE;QACjC,MAAM,CAAC,KAAK,CAAC,uCAAuC,GAAG,IAAI,CAAC,CAAC;IAC/D,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,CACX,KAAc,EACd,MAAc,EACd,WAAoB,EACpB,SAAiB,EACjB,aAA6D,EAC7D,MAAe,EACgB,EAAE,CAAC,CAAC;QACnC,QAAQ,EAAE,CAAC;QACX,KAAK;QACL,MAAM;QACN,SAAS,EAAE,WAAW;QACtB,SAAS;QACT,aAAa;QACb,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC;KACxC,CAAC,CAAC;IAEH,IAAI,KAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,CAAsB,CAAC;IACnF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,yBAA0B,GAAa,CAAC,OAAO,EAAE,CAAC;QACjE,IAAI,CAAC,MAAM,CAAC,CAAC;QACb,OAAO,IAAI,CAAC,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,GAAG,GACP,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC;QACjD,CAAC,CAAC,IAAI,CAAC,GAAG;QACV,CAAC,CAAC,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC;YACrD,CAAC,CAAC,KAAK,CAAC,GAAG;YACX,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAE1C,mEAAmE;IACnE,kEAAkE;IAClE,oEAAoE;IACpE,IAAI,QAAQ,GAAoB,IAAI,CAAC;IACrC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,IAAI,CAAC;YACH,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;QACzC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,yBAA0B,GAAa,CAAC,OAAO,0CAA0C,CAAC,CAAC;QAClG,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IACtE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI;QACjE,CAAC,CAAC,wBAAwB,CAAC,IAAI,CAAC;QAChC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,0BAA0B,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACjE,IAAI,gBAAgB;QAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAE7C,uDAAuD;IACvD,+DAA+D;IAC/D,MAAM,QAAQ,GACZ,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QACzD,CAAC,CAAC,IAAI,CAAC,OAAO;QACd,CAAC,CAAC,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;YACnE,CAAC,CAAC,KAAK,CAAC,UAAU;YAClB,CAAC,CAAC,SAAS,CAAC;IAClB,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,oBAAoB,CAAC;IACnE,MAAM,SAAS,GAAG,cAAc,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC/C,MAAM,aAAa,GACjB,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QACzD,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;YACnE,CAAC,CAAC,OAAO;YACT,CAAC,CAAC,SAAS,KAAK,gBAAgB;gBAC9B,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,QAAQ;oBAC/C,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,SAAS;oBAC7C,CAAC,CAAC,KAAK;oBACP,CAAC,CAAC,YAAY,CAAC;IAEzB,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,yHAAyH,CAAC;QACzI,IAAI,CAAC,MAAM,CAAC,CAAC;QACb,OAAO,IAAI,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC7D,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,WAAW,MAAM,+BAA+B,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,4BAA4B,CAAC;QACpH,IAAI,CAAC,MAAM,CAAC,CAAC;QACb,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;IACrE,CAAC;IAED,0CAA0C;IAC1C,MAAM,OAAO,GAAG,GAAG,wBAAwB,IAAI,MAAM,EAAE,CAAC;IAExD,IAAI,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;IACnC,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,MAAM,GAAG,uCAAuC,OAAO,EAAE,CAAC;YAChE,IAAI,CAAC,MAAM,CAAC,CAAC;YACb,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;QACtE,CAAC;QACD,MAAM,MAAM,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,MAAM,GAAG,yDAAyD,OAAO,EAAE,CAAC;YAClF,IAAI,CAAC,MAAM,CAAC,CAAC;YACb,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;QACtE,CAAC;QACD,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,SAAS,CAAC;QACpC,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,UAAU,IAAI,KAAK,CAAC;QAC7E,WAAW,GAAG,CAAC,IAAI,EAAE,EAAE,CACrB,aAAa,CAAC;YACZ,UAAU,EAAE,OAAO;YACnB,GAAG,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;YAC3B,SAAS;YACT,GAAG,IAAI;SACR,CAAC,CAAC;IACP,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;IAChF,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,wBAAwB,MAAM,CAAC,MAAM,IAAI,eAAe,EAAE,CAAC;QAC1E,IAAI,CAAC,MAAM,CAAC,CAAC;QACb,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,CAAC,YAAY,OAAO,gBAAgB,SAAS,EAAE,CAAC,CAAC;IACrD,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CACF,gOAAgO,CACjO,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;AAC7D,CAAC"}

package/dist/cli/uninstall/index.d.ts

@@ -0,0 +1,68 @@
+export declare class UninstallError extends Error {
+    constructor(message: string);
+}
+export interface UninstallOptions {
+    /** Override for `~/.claude/`. Falls back to `os.homedir()/.claude`. */
+    homeDir?: string;
+    /** Override settings.json path (test injection / non-default install). */
+    settingsPath?: string;
+    /** Mutate when true; pure listing otherwise. */
+    apply?: boolean;
+    /**
+     * Atomic restore from a specific backup (typically a
+     * `settings.json.pre-harness-<TS>` file). Implies `apply`; mutually
+     * exclusive with the standard selective-removal flow.
+     */
+    restoreFrom?: string;
+    /** Override "now" for deterministic timestamps in tests. */
+    now?: Date;
+}
+export interface HookGroupRef {
+    event: string;
+    index: number;
+    matcher: string | null;
+    /** Short summary of the inner `hooks[].command` list for the listing UI. */
+    description: string;
+}
+export interface UninstallInventory {
+    /** Resolved `~/.claude/` (or override). */
+    homeDir: string;
+    /** Resolved settings.json path (or override). */
+    settingsPath: string;
+    /** `~/.claude/harness.yaml` when present, else null. */
+    manifestPath: string | null;
+    /** `~/.claude/harness.lock` when present, else null. */
+    lockPath: string | null;
+    /** `~/.claude/harness.generated/` when present, else null. */
+    generatedDir: string | null;
+    /** Harness-owned hook groups currently in settings.json. */
+    hookGroups: HookGroupRef[];
+    /** Harness-owned mcpServers keys currently in settings.json. */
+    mcpServers: string[];
+    /** Discovered `settings.json.pre-harness-*` backups in the settings directory. */
+    preHarnessBackups: string[];
+    /** Soft notices (e.g. project-local `~/.claude.json` registers grounding-mcp). */
+    warnings: string[];
+}
+export type UninstallResult = {
+    mode: "list";
+    inventory: UninstallInventory;
+} | {
+    mode: "apply";
+    inventory: UninstallInventory;
+    /** Backup path (null when settings.json had nothing to remove). */
+    backupPath: string | null;
+    /** Snapshot path (null when no settings.json mutation was needed). */
+    snapshotPath: string | null;
+    /** Filesystem entries removed from disk (manifest, lock, generated dir). */
+    removedFiles: string[];
+} | {
+    mode: "restore";
+    inventory: UninstallInventory;
+    restoredFrom: string;
+    backupPath: string;
+    snapshotPath: string;
+    /** Filesystem entries removed from disk (manifest, lock, generated dir). */
+    removedFiles: string[];
+};
+export declare function uninstall(opts?: UninstallOptions): UninstallResult;