@indigoai-us/hq-cli 5.98.2 → 5.99.0

package/dist/lib/doctor/deep/executor.js

@@ -0,0 +1,369 @@
+/**
+ * `--deep-test` execution for pure guard hooks (US-008).
+ *
+ * Default `hq doctor` proves a hook is *wired*. Deep test proves it *works*: for
+ * every pure-guard fixture (US-007 schema, {@link isPureGuard} classification)
+ * it replays each case through the REAL `hook-gate.sh` and checks the verdict
+ * against the fixture's expectation. Four rules make this trustworthy rather
+ * than theatre:
+ *
+ *   1. Route through the gate, never the hook directly. A hook can pass direct
+ *      invocation and still silently no-op under the active gate profile — the
+ *      documented `block-hq-root-git-mutation` incident did exactly that. So
+ *      each case runs `hook-gate.sh <id> <script>` with a payload on stdin, and
+ *      under ALL THREE profiles (minimal, standard, strict). A profile whose
+ *      outcome differs from the expectation is a FAIL naming that profile: an
+ *      expected block that no-ops to exit 0 under standard is caught here and
+ *      nowhere else.
+ *
+ *   2. Sandbox, never the live tree. The gate and hooks are copied into a
+ *      throwaway temp tree and every case executes there, so a diagnosis can
+ *      never mutate the user's real setup. A test asserts the live tree is
+ *      byte-identical before and after a run.
+ *
+ *   3. Time-bound every case. A hook that hangs must fail its case, not the
+ *      command — each execution is spawned with a per-case timeout and a
+ *      timeout is reported as FAIL, never left to block the run.
+ *
+ *   4. Never fire a hook in default mode. This module runs only when the caller
+ *      asks for it (the command wires it behind `--deep-test`); the default
+ *      registry does not include it. A test asserts no hook process is spawned
+ *      without the flag.
+ *
+ * Expectation matching and the `expectedFailure` rule are owned by
+ * {@link outcomeMatches} / {@link classifyCaseStatus} in the fixture schema, so
+ * a case outcome means the same thing here as in the coverage tier. The Claude
+ * block protocol (a non-zero gate exit is a block) is the only one this story
+ * handles; Grok's stdout-`deny` protocol is US-010's parity replay.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { GATE_PROFILES } from "../hook-gate-profiles.js";
+import { discoverFixtures, registeredHookIds } from "../fixtures/discover.js";
+import { classifyCaseStatus, outcomeMatches, } from "../fixtures/schema.js";
+import { isPureGuard } from "./classify.js";
+/** The id of the deep-test family the command appends under `--deep-test`. */
+export const DEEP_FAMILY_ID = "deep";
+/** Human title of the deep-test family. */
+export const DEEP_FAMILY_TITLE = "Deep guard-hook tests";
+/** Default per-case time bound. Deep test has no latency target, but no case
+ * may hang the command, so every execution is capped. */
+export const DEFAULT_PER_CASE_TIMEOUT_MS = 10_000;
+/**
+ * The tree entries copied into the sandbox. Deliberately a curated set, not the
+ * whole tree: the live `.claude/` carries worktrees and session state that can
+ * run to hundreds of megabytes, whereas the gate only needs the hook scripts,
+ * the settings a hook might read, the Codex/Grok mirrors, and `core/` (where the
+ * gate finds `hook-lib.sh` and hooks find their helpers). Missing entries are
+ * skipped, so a partial tree still sandboxes cleanly.
+ */
+export const SANDBOX_COPY_RELPATHS = [
+    ".claude/hooks",
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".codex/hooks",
+    ".codex/hooks.json",
+    ".grok",
+    "core",
+];
+/**
+ * The real runner: spawn `bash hook-gate.sh <id> <script>` with the payload on
+ * stdin, `HQ_HOOK_PROFILE` set, and a hard timeout. A timeout is detected by the
+ * `ETIMEDOUT` error code spawnSync reports; the process is killed with SIGKILL so
+ * a hook cannot ignore the bound.
+ */
+export const defaultGateRunner = (input) => {
+    const result = spawnSync("bash", [input.gatePath, input.hookId, input.hookScriptPath], {
+        input: input.payload,
+        cwd: input.cwd,
+        timeout: input.timeoutMs,
+        killSignal: "SIGKILL",
+        encoding: "utf8",
+        maxBuffer: 8 * 1024 * 1024,
+        env: {
+            ...process.env,
+            HQ_HOOK_PROFILE: input.profile,
+            CLAUDE_PROJECT_DIR: input.cwd,
+            HQ_ROOT: input.cwd,
+        },
+    });
+    const errno = result.error?.code;
+    return {
+        timedOut: errno === "ETIMEDOUT",
+        exitCode: result.status,
+        stderr: result.stderr ?? "",
+    };
+};
+// --- sandbox lifecycle --------------------------------------------------------
+const trackedSandboxes = new Set();
+let sandboxExitHandlerRegistered = false;
+/** Remove every sandbox still on disk. Safe to call repeatedly. */
+export function cleanupAllDeepSandboxes() {
+    for (const root of trackedSandboxes)
+        removeTree(root);
+    trackedSandboxes.clear();
+}
+function ensureSandboxExitHandler() {
+    if (sandboxExitHandlerRegistered)
+        return;
+    sandboxExitHandlerRegistered = true;
+    // Fires on normal exit and after a crash alike, guaranteeing no sandbox
+    // survives even if a case throws or the process is torn down mid-run.
+    process.on("exit", cleanupAllDeepSandboxes);
+}
+function removeTree(root) {
+    try {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort: cleanup must never mask a test's real failure.
+    }
+}
+/**
+ * Copy the curated {@link SANDBOX_COPY_RELPATHS} from the live tree into a fresh
+ * temp root. Pure guards do not write, so one sandbox is reused for the whole
+ * run; the live tree is only ever read from.
+ */
+function createSandbox(hqRoot, relpaths) {
+    ensureSandboxExitHandler();
+    const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "hq-doctor-deep-")));
+    trackedSandboxes.add(root);
+    for (const rel of relpaths) {
+        const segments = rel.split("/");
+        const src = path.join(hqRoot, ...segments);
+        if (!fs.existsSync(src))
+            continue;
+        const dest = path.join(root, ...segments);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        // cpSync preserves mode bits, so the gate and hooks stay executable.
+        fs.cpSync(src, dest, { recursive: true });
+    }
+    return root;
+}
+// --- entry point --------------------------------------------------------------
+/**
+ * Execute every pure-guard fixture's cases through the real gate under all three
+ * profiles and return the per-case results. Read-only against the live tree;
+ * all execution happens in a sandbox that is removed before returning. Returns
+ * an empty list — creating no sandbox — when there is nothing to run.
+ */
+export async function runDeepGuardTests(context, options = {}) {
+    const hqRoot = context.hqRoot;
+    const timeoutMs = options.perCaseTimeoutMs ?? DEFAULT_PER_CASE_TIMEOUT_MS;
+    const runner = options.runner ?? defaultGateRunner;
+    const copyRelpaths = options.sandboxRelpaths ?? SANDBOX_COPY_RELPATHS;
+    const runnable = selectRunnableFixtures(hqRoot);
+    if (runnable.length === 0)
+        return [];
+    const sandbox = createSandbox(hqRoot, copyRelpaths);
+    try {
+        return runAllFixtures(runnable, { sandbox, timeoutMs, runner });
+    }
+    finally {
+        if (!options.keepSandbox) {
+            removeTree(sandbox);
+            trackedSandboxes.delete(sandbox);
+        }
+    }
+}
+/**
+ * The pure-guard fixtures worth executing: valid (US-007 already reports the
+ * invalid, unknown-version and orphan cases), registered, non-empty, and not a
+ * side-effecting hook (those are US-009's sandboxed effect tier).
+ */
+function selectRunnableFixtures(hqRoot) {
+    const registered = new Set(registeredHookIds(hqRoot));
+    const discovery = discoverFixtures(hqRoot);
+    const runnable = [];
+    for (const discovered of discovery.fixtures) {
+        if (discovered.parsed.status !== "ok")
+            continue;
+        const fixture = discovered.parsed.fixture;
+        if (!registered.has(fixture.hookId))
+            continue;
+        if (fixture.cases.length === 0)
+            continue;
+        if (!isPureGuard(fixture))
+            continue;
+        runnable.push(fixture);
+    }
+    return runnable;
+}
+function runAllFixtures(fixtures, env) {
+    const results = [];
+    const gatePath = path.join(env.sandbox, ".claude", "hooks", "hook-gate.sh");
+    // No gate means the real gate path cannot be exercised at all — honest UNKNOWN
+    // for every fixture (never PASS), mirroring the tool's central safeguard.
+    if (!fs.existsSync(gatePath)) {
+        for (const fixture of fixtures) {
+            results.push({
+                status: "UNKNOWN",
+                checkId: "hooks.deep.gate-missing",
+                target: fixture.hookId,
+                message: `Cannot deep-test "${fixture.hookId}": .claude/hooks/hook-gate.sh is absent, so its cases cannot be run through the real gate.`,
+            });
+        }
+        return results;
+    }
+    for (const fixture of fixtures) {
+        const scriptPath = path.join(env.sandbox, ".claude", "hooks", `${fixture.hookId}.sh`);
+        if (!fs.existsSync(scriptPath)) {
+            results.push({
+                status: "UNKNOWN",
+                checkId: "hooks.deep.script-missing",
+                target: fixture.hookId,
+                message: `Cannot deep-test "${fixture.hookId}": its script .claude/hooks/${fixture.hookId}.sh is absent, so no case can be executed.`,
+            });
+            continue;
+        }
+        for (const testCase of fixture.cases) {
+            results.push(evaluateCase(fixture, testCase, gatePath, scriptPath, env));
+        }
+    }
+    return results;
+}
+/**
+ * Run one case under all three profiles and classify the aggregate. A timeout
+ * under any profile is a FAIL for timeout; otherwise a profile whose verdict
+ * differs from the expectation makes the case FAIL (or KNOWN-DEFECT under an
+ * `expectedFailure` marker) naming those profiles, their exit codes, and their
+ * stderr.
+ */
+function evaluateCase(fixture, testCase, gatePath, scriptPath, env) {
+    const target = `${fixture.hookId}:${testCase.name}`;
+    const payload = buildPayload(testCase, env.sandbox);
+    const runs = [];
+    const timedOut = [];
+    for (const profile of GATE_PROFILES) {
+        const run = env.runner({
+            gatePath,
+            hookScriptPath: scriptPath,
+            hookId: fixture.hookId,
+            profile,
+            payload,
+            cwd: env.sandbox,
+            timeoutMs: env.timeoutMs,
+        });
+        if (run.timedOut) {
+            timedOut.push(profile);
+            runs.push({ profile, run, met: false });
+            continue;
+        }
+        const observed = {
+            blocked: run.exitCode !== 0,
+            stderr: run.stderr,
+        };
+        runs.push({ profile, run, met: outcomeMatches(testCase.expect, observed) });
+    }
+    // A hook that cannot answer within the bound fails its case rather than
+    // hanging the command — reported distinctly so a timeout is never confused
+    // with a wrong verdict.
+    if (timedOut.length > 0) {
+        return {
+            status: "FAIL",
+            checkId: "hooks.deep.timeout",
+            target,
+            message: `Case "${testCase.name}" for "${fixture.hookId}" exceeded the ${env.timeoutMs}ms per-case time bound under ${formatProfiles(timedOut)}; a hook that does not return within the bound is treated as a failure, not left to hang the command.`,
+            remediation: `Investigate why "${fixture.hookId}" does not return within ${env.timeoutMs}ms for case "${testCase.name}".`,
+        };
+    }
+    const failed = runs.filter((r) => !r.met).map((r) => r.profile);
+    const status = classifyCaseStatus(failed.length === 0, testCase.expectedFailure);
+    if (status === "PASS") {
+        return {
+            status,
+            checkId: "hooks.deep.case",
+            target,
+            message: `Case "${testCase.name}" for "${fixture.hookId}" produced the expected ${describeExpect(testCase.expect)} through the gate under all three profiles.`,
+        };
+    }
+    if (status === "WARN") {
+        // Marked as a pinned defect, yet it now passes everywhere — the marker is
+        // stale and should be removed (US-007 `expectedFailure` semantics).
+        return {
+            status,
+            checkId: "hooks.deep.stale-expected-failure",
+            target,
+            message: `Case "${testCase.name}" for "${fixture.hookId}" is marked expectedFailure (${testCase.expectedFailure?.reason ?? ""}) but now produces the expected ${describeExpect(testCase.expect)} under all three profiles; remove the stale marker.`,
+            remediation: `Delete the expectedFailure marker from case "${testCase.name}" in core/hook-tests/${fixture.hookId}.yaml.`,
+        };
+    }
+    // FAIL or KNOWN-DEFECT: name each failing profile with its exit code and stderr.
+    const detail = runs
+        .filter((r) => !r.met)
+        .map((r) => `${r.profile} (exit ${formatExit(r.run.exitCode)}${r.run.stderr.trim()
+        ? `, stderr: ${oneLine(r.run.stderr)}`
+        : ", no stderr"})`)
+        .join("; ");
+    const base = `Case "${testCase.name}" for "${fixture.hookId}" expected ${describeExpect(testCase.expect)} but the outcome differed under ${formatProfiles(failed)}: ${detail}.`;
+    if (status === "KNOWN-DEFECT") {
+        return {
+            status,
+            checkId: "hooks.deep.case",
+            target,
+            message: `${base} Tracked as a known defect: ${testCase.expectedFailure?.reason ?? ""}.`,
+        };
+    }
+    return {
+        status: "FAIL",
+        checkId: "hooks.deep.case",
+        target,
+        message: base,
+        remediation: remediationForExpect(testCase.expect, fixture.hookId, failed),
+    };
+}
+/**
+ * The Claude/Codex hook payload shape the gate delegates on stdin: the fixture's
+ * event, tool, and opaque input under the keys hooks read (`.hook_event_name`,
+ * `.tool_name`, `.tool_input`). `cwd`/`session_id` are set for hooks that key
+ * off them, pointing at the sandbox.
+ */
+function buildPayload(testCase, cwd) {
+    return JSON.stringify({
+        hook_event_name: testCase.event,
+        tool_name: testCase.tool,
+        tool_input: testCase.input,
+        cwd,
+        session_id: "hq-doctor-deep-test",
+    });
+}
+// --- message helpers ----------------------------------------------------------
+function describeExpect(expect) {
+    switch (expect.kind) {
+        case "block":
+            return "a block";
+        case "allow":
+            return "an allow (pass-through)";
+        case "stderr":
+            return `stderr matching /${expect.pattern}/`;
+    }
+}
+function remediationForExpect(expect, hookId, failed) {
+    if (expect.kind === "block") {
+        return `Ensure "${hookId}" blocks this input under ${formatProfiles(failed)} — most often it is missing from ${formatProfiles(failed)} in .claude/hooks/hook-gate.sh, so the gate no-ops it there.`;
+    }
+    if (expect.kind === "allow") {
+        return `"${hookId}" blocked an input the fixture expects to be allowed; verify the hook logic or correct the fixture case.`;
+    }
+    return `"${hookId}" did not emit the expected stderr; verify the hook or the fixture pattern.`;
+}
+/** Render a profile list as "minimal", "minimal and standard", or "a, b and c". */
+function formatProfiles(profiles) {
+    const ordered = GATE_PROFILES.filter((p) => profiles.includes(p));
+    if (ordered.length <= 1)
+        return ordered.join("");
+    if (ordered.length === 2)
+        return `${ordered[0]} and ${ordered[1]}`;
+    return `${ordered.slice(0, -1).join(", ")} and ${ordered[ordered.length - 1]}`;
+}
+function formatExit(exitCode) {
+    return exitCode === null ? "none" : String(exitCode);
+}
+/** Collapse captured stderr to a single trimmed, length-capped line for a message. */
+function oneLine(stderr) {
+    const collapsed = stderr.replace(/\s+/g, " ").trim();
+    return collapsed.length > 200 ? `${collapsed.slice(0, 197)}…` : collapsed;
+}
+//# sourceMappingURL=executor.js.map

package/dist/lib/doctor/deep/parity.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Cross-platform parity replay (US-010).
+ *
+ * The payoff of the declarative fixture format: one case, three executions,
+ * automatic drift detection. Under `--deep-test`, every pure-guard fixture case
+ * is normalised into the Claude, Codex, and Grok payload shapes (payload-shapes.ts)
+ * and replayed through each platform's REAL adapter path, and their verdicts are
+ * compared. Platform drift — a Codex mirror whose logic diverged from its Claude
+ * original — becomes a test result instead of a manual audit.
+ *
+ * The three "real adapter paths", matching how each platform is actually wired:
+ *
+ *   - Claude runs the canonical `.claude/hooks/<id>.sh` through
+ *     `.claude/hooks/hook-gate.sh`, exactly as `.claude/settings.json` registers
+ *     it. A block is a non-zero gate exit.
+ *   - Codex runs its DUPLICATED `.codex/hooks/<id>.sh` mirror through
+ *     `.codex/hooks/hook-gate.sh`, exactly as `.codex/hooks.json` registers it.
+ *     This is the entire drift surface: only Codex runs copies, so a mirror whose
+ *     logic differs is caught precisely here. A block is a non-zero gate exit.
+ *   - Grok drives `.grok/hooks/hq-grok-hook-adapter.sh` with the camelCase
+ *     payload; the adapter maps the Grok tool alias back to canonical and routes
+ *     through the same `.claude/` gate. A block is a stdout `deny` decision
+ *     and/or a non-zero exit (payload-shapes `interpretGrokBlock`).
+ *
+ * Three rules keep the replay honest:
+ *
+ *   1. Disagreement is a FAIL that names every platform's verdict side by side,
+ *      so a reviewer sees `claude=block, codex=allow, grok=block` rather than a
+ *      bare failure.
+ *   2. Grok's passive events (everything but PreToolUse) cannot inject
+ *      model-facing context or emit a decision, so a case on such an event is
+ *      NA — never PASS or FAIL — with the platform limitation named.
+ *   3. A platform whose script/adapter is absent, or whose case timed out, is an
+ *      honest UNKNOWN (never PASS): an exec failure must not be misread as a
+ *      block, and a platform we could not run cannot be declared in agreement.
+ *
+ * Parity replay runs ONLY under `--deep-test`; the command appends it there, not
+ * in the default registry, so a plain `hq doctor` never fires a hook. It reuses
+ * the same pure-guard selection as US-008's executor and its own sandbox, so the
+ * live tree is only ever read from.
+ */
+import type { CheckContext, CheckResult } from "../types.js";
+import type { FixtureCase } from "../fixtures/schema.js";
+import { type PlatformId } from "../payload-shapes.js";
+/** The id of the parity family the command appends under `--deep-test`. */
+export declare const PARITY_FAMILY_ID = "deep-parity";
+/** Human title of the parity family. */
+export declare const PARITY_FAMILY_TITLE = "Cross-platform parity replay";
+/** Default per-case, per-platform time bound. */
+export declare const DEFAULT_PARITY_TIMEOUT_MS = 10000;
+/** The gate profile the replay runs each hook under. Strict is the broadest
+ * allowlist, so profile gating never suppresses the hook whose LOGIC is being
+ * compared across platforms — profile-specific behaviour is US-008's concern. */
+export declare const PARITY_GATE_PROFILE = "strict";
+/** The session id stamped onto every replay payload. */
+export declare const PARITY_SESSION_ID = "hq-doctor-parity-replay";
+/** One platform replay's inputs. */
+export interface PlatformRunInput {
+    /** Which platform's adapter path to exercise. */
+    platform: PlatformId;
+    /** The sandbox root (also the payload `cwd`). */
+    sandbox: string;
+    /** The hook id under test. */
+    hookId: string;
+    /** The case being replayed. */
+    testCase: FixtureCase;
+    /** Per-platform time bound in milliseconds. */
+    timeoutMs: number;
+}
+/** One platform replay's observed output, before protocol interpretation. */
+export interface PlatformRunOutput {
+    /** True when the platform could not be run at all (missing script/adapter). */
+    unavailable?: {
+        reason: string;
+    };
+    /** True when the execution exceeded {@link PlatformRunInput.timeoutMs}. */
+    timedOut: boolean;
+    /** Process exit code, or null when it did not exit normally. */
+    exitCode: number | null;
+    /** Captured stdout (empty when none). */
+    stdout: string;
+    /** Captured stderr (empty when none). */
+    stderr: string;
+}
+/** Executes one platform replay. Injectable so the comparison is unit-testable. */
+export type PlatformRunner = (input: PlatformRunInput) => PlatformRunOutput;
+/** The real runner set, keyed by platform. */
+export type PlatformRunners = Record<PlatformId, PlatformRunner>;
+/** The real Claude runner: the canonical script through the Claude gate. */
+export declare const defaultClaudeRunner: PlatformRunner;
+/** The real Codex runner: the duplicated mirror through the Codex gate. */
+export declare const defaultCodexRunner: PlatformRunner;
+/**
+ * The real Grok runner. Grok shares the canonical `.claude/hooks/` scripts with
+ * Claude — it has no mirror of its own — and its adapter's whole job is to read
+ * the camelCase payload, map the tool alias back to canonical, build the Claude
+ * JSON, and pipe it to the same `hook-gate.sh`. We reproduce that routing here
+ * (via {@link toGrokPayload} + {@link grokToSnakePayload}) rather than spawn the
+ * adapter directly, for two reasons: the live adapter runs a whole tool
+ * *sequence* where the replay needs one isolated hook, and its user-global
+ * bridge cannot be simulated from a project-local run (US-005 keeps bridge
+ * presence a wiring check). The Grok block protocol still applies — the gate's
+ * non-zero exit is what the adapter would translate into a stdout `deny`
+ * ({@link interpretGrokBlock} in verdictFor recognises both).
+ */
+export declare const defaultGrokRunner: PlatformRunner;
+/** The default real runner set wired to each platform's real adapter path. */
+export declare const defaultPlatformRunners: PlatformRunners;
+/** Options for {@link runParityReplay}. All injectable for testing. */
+export interface ParityOptions {
+    /** Per-case, per-platform time bound. Default: {@link DEFAULT_PARITY_TIMEOUT_MS}. */
+    perCaseTimeoutMs?: number;
+    /** Tree entries copied into the sandbox. Default: {@link SANDBOX_COPY_RELPATHS}. */
+    sandboxRelpaths?: readonly string[];
+    /** Platform runners. Defaults to the real {@link defaultPlatformRunners}. */
+    runners?: Partial<PlatformRunners>;
+    /** Leave the sandbox on disk (debugging). Default: false. */
+    keepSandbox?: boolean;
+}
+/** Remove every parity sandbox still on disk. Safe to call repeatedly. */
+export declare function cleanupAllParitySandboxes(): void;
+/**
+ * Replay every pure-guard fixture case through all three platform adapters and
+ * report the per-case parity verdict. Read-only against the live tree; all
+ * execution happens in a sandbox that is removed before returning. Returns an
+ * empty list — creating no sandbox — when there is nothing to replay.
+ */
+export declare function runParityReplay(context: CheckContext, options?: ParityOptions): Promise<CheckResult[]>;
+//# sourceMappingURL=parity.d.ts.map