@indigoai-us/hq-cli 5.98.2 → 5.99.0

package/dist/lib/doctor/checks/claude-wiring.js

@@ -0,0 +1,524 @@
+/**
+ * Claude Code hook WIRING checks (US-004).
+ *
+ * "Wiring" is everything short of firing the hook: is every registration backed
+ * by a script that exists and is executable, is every script on disk actually
+ * registered, is every gated hook id a member of all three `hook-gate.sh`
+ * profiles, and does any command word-split its own script path. A hook can be
+ * present, correct, and completely dead — this check catches the ways that
+ * happens without a single error surfacing to the user.
+ *
+ * It is strictly read-only: it stats and reads files and never writes, so a
+ * doctor run is byte-identical to no run at all (asserted by test).
+ *
+ * The unquoted-`$CLAUDE_PROJECT_DIR` detection is a faithful TypeScript port of
+ * the quote-aware shell tokenizer in `core/scripts/lib/hook-command-scan.sh`
+ * (used by `core/scripts/check-hq-hooks.sh`), not a reinvention: Claude Code
+ * runs each hook command through `/bin/sh`, so an expansion outside double
+ * quotes is word-split, and on an install root containing whitespace the shell
+ * execs a truncated path and every such hook dies as an invisible non-blocking
+ * error. Sharing the tokenizer's semantics is the point — a quoted form such as
+ * `"$CLAUDE_PROJECT_DIR/x"` or `"${CLAUDE_PROJECT_DIR}/x"` must never be called
+ * broken, and an unquoted one must never be missed.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { GATE_PROFILES, gateMembership, parseHookGateProfiles, } from "../hook-gate-profiles.js";
+/** Common id prefix for every result this check family emits. */
+export const CLAUDE_WIRING_PREFIX = "hooks.claude";
+/**
+ * Run every Claude wiring check against the resolved HQ tree and return the
+ * per-item results. Never throws on a malformed or partial tree — a missing or
+ * unreadable input contributes a result (or nothing), not an exception.
+ */
+export function checkClaudeWiring(context) {
+    const root = context.hqRoot;
+    const claudeDir = path.join(root, ".claude");
+    const hooksDir = path.join(claudeDir, "hooks");
+    const gatePath = path.join(hooksDir, "hook-gate.sh");
+    const results = [];
+    // --- Load registrations from both settings files -----------------------------
+    // Claude Code merges .claude/settings.local.json over .claude/settings.json, so
+    // a hook that lives only in the overlay is wired exactly like a shipped one.
+    const registrations = [];
+    const base = readJsonFile(path.join(claudeDir, "settings.json"));
+    if (base.present && !base.invalid) {
+        registrations.push(...enumerateRegistrations(base.value, ".claude/settings.json"));
+    }
+    const local = readJsonFile(path.join(claudeDir, "settings.local.json"));
+    if (local.present && local.invalid) {
+        results.push({
+            status: "FAIL",
+            checkId: `${CLAUDE_WIRING_PREFIX}.settings-local-valid-json`,
+            target: path.join(claudeDir, "settings.local.json"),
+            message: ".claude/settings.local.json is present but is not valid JSON.",
+        });
+    }
+    else if (local.present) {
+        registrations.push(...enumerateRegistrations(local.value, ".claude/settings.local.json"));
+    }
+    const scans = registrations.map((reg) => ({
+        reg,
+        scan: scanHookCommand(reg.command),
+    }));
+    // --- AC1: total registrations per lifecycle event ----------------------------
+    const perEvent = new Map();
+    for (const reg of registrations) {
+        perEvent.set(reg.event, (perEvent.get(reg.event) ?? 0) + 1);
+    }
+    for (const [event, count] of [...perEvent.entries()].sort(byKey)) {
+        results.push({
+            status: "PASS",
+            checkId: `${CLAUDE_WIRING_PREFIX}.event.${event}`,
+            target: event,
+            message: `${count} Claude hook registration${count === 1 ? "" : "s"} on ${event}.`,
+        });
+    }
+    // --- AC2: every referenced script exists and is executable -------------------
+    const scriptRelpaths = new Set();
+    for (const { scan } of scans) {
+        for (const rp of scan.requiredRelpaths)
+            scriptRelpaths.add(rp);
+    }
+    for (const rp of [...scriptRelpaths].sort()) {
+        const abs = path.join(root, rp);
+        const stat = statSafe(abs);
+        if (!stat) {
+            results.push({
+                status: "FAIL",
+                checkId: `${CLAUDE_WIRING_PREFIX}.script-missing`,
+                target: abs,
+                message: `Registered hook script is missing on disk: ${rp}.`,
+                remediation: `Restore ${rp} or remove its registration from .claude/settings.json.`,
+            });
+            continue;
+        }
+        if (!isExecutable(stat.mode)) {
+            results.push({
+                status: "FAIL",
+                checkId: `${CLAUDE_WIRING_PREFIX}.script-not-executable`,
+                target: abs,
+                message: `Registered hook script is present but not executable: ${rp}.`,
+                remediation: `chmod +x "${abs}"`,
+            });
+            continue;
+        }
+        results.push({
+            status: "PASS",
+            checkId: `${CLAUDE_WIRING_PREFIX}.script`,
+            target: abs,
+            message: `Registered hook script exists and is executable: ${rp}.`,
+        });
+    }
+    // --- AC3: scripts present on disk but registered nowhere ---------------------
+    const referencedBasenames = new Set(["hook-gate.sh"]);
+    for (const { scan } of scans) {
+        for (const rp of scan.requiredRelpaths)
+            referencedBasenames.add(baseName(rp));
+    }
+    for (const file of listShellScripts(hooksDir)) {
+        if (referencedBasenames.has(file))
+            continue;
+        results.push({
+            status: "WARN",
+            checkId: `${CLAUDE_WIRING_PREFIX}.orphan`,
+            target: path.join(hooksDir, file),
+            message: `Hook script ${file} is present in .claude/hooks/ but is not registered in any settings file.`,
+            remediation: `Register ${file} in .claude/settings.json or delete it.`,
+        });
+    }
+    // --- AC4: every gated hook id is in ALL THREE profiles -----------------------
+    const gatedIds = new Set();
+    for (const { scan } of scans) {
+        if (scan.gatedHookId)
+            gatedIds.add(scan.gatedHookId);
+    }
+    if (gatedIds.size > 0) {
+        const gateSource = readTextFile(gatePath);
+        if (gateSource === null) {
+            results.push({
+                status: "FAIL",
+                checkId: `${CLAUDE_WIRING_PREFIX}.hook-gate-missing`,
+                target: gatePath,
+                message: "Hooks route through hook-gate.sh but .claude/hooks/hook-gate.sh is missing; profile membership cannot be verified.",
+            });
+        }
+        else {
+            const profiles = parseHookGateProfiles(gateSource);
+            for (const id of [...gatedIds].sort()) {
+                const { present, missing } = gateMembership(id, profiles);
+                if (missing.length === 0) {
+                    results.push({
+                        status: "PASS",
+                        checkId: `${CLAUDE_WIRING_PREFIX}.gate-profiles`,
+                        target: id,
+                        message: `Gated hook ${id} is allowlisted in all three hook-gate.sh profiles.`,
+                    });
+                    continue;
+                }
+                const missingList = formatProfiles(missing);
+                const presentDesc = present.length > 0 ? formatProfiles(present) : "no profile";
+                results.push({
+                    status: "FAIL",
+                    checkId: `${CLAUDE_WIRING_PREFIX}.gate-profiles`,
+                    target: id,
+                    message: `Gated hook ${id} is missing from the ${missingList} hook-gate.sh ` +
+                        `profile${missing.length === 1 ? "" : "s"} (present in ${presentDesc}); ` +
+                        `it silently no-ops under ${missing.length === 1 ? "that profile" : "those profiles"}.`,
+                    remediation: `Add ${id} to the ${missingList} allowlist${missing.length === 1 ? "" : "s"} in .claude/hooks/hook-gate.sh.`,
+                });
+            }
+        }
+    }
+    // --- AC5: unquoted $CLAUDE_PROJECT_DIR word-splits on a spaced root ----------
+    const unquoted = scans.filter(({ scan }) => scan.unquotedProjectDir);
+    if (unquoted.length > 0) {
+        const events = [...new Set(unquoted.map(({ reg }) => reg.event))]
+            .sort()
+            .join(", ");
+        const remediation = 'Quote every $CLAUDE_PROJECT_DIR expansion (use "$CLAUDE_PROJECT_DIR/…") in .claude/settings.json.';
+        if (/\s/.test(root)) {
+            results.push({
+                status: "FAIL",
+                checkId: `${CLAUDE_WIRING_PREFIX}.unquoted-project-dir`,
+                target: root,
+                message: `${unquoted.length} hook command(s) reference $CLAUDE_PROJECT_DIR without quotes and this HQ root ` +
+                    `contains whitespace, so /bin/sh word-splits the path and every one of those hooks is failing ` +
+                    `right now (events: ${events}): ${root}`,
+                remediation,
+            });
+        }
+        else {
+            results.push({
+                status: "WARN",
+                checkId: `${CLAUDE_WIRING_PREFIX}.unquoted-project-dir`,
+                target: root,
+                message: `${unquoted.length} hook command(s) reference $CLAUDE_PROJECT_DIR without quotes; they break on ` +
+                    `any install path containing whitespace (events: ${events}).`,
+                remediation,
+            });
+        }
+    }
+    // --- AC6: event-directory hooks under core/hooks/<Event>/ --------------------
+    const coreHooksDir = path.join(root, "core", "hooks");
+    for (const event of listSubdirs(coreHooksDir)) {
+        const eventDir = path.join(coreHooksDir, event);
+        for (const file of listShellScripts(eventDir)) {
+            const abs = path.join(eventDir, file);
+            const stat = statSafe(abs);
+            if (!stat)
+                continue;
+            if (!isExecutable(stat.mode)) {
+                results.push({
+                    status: "FAIL",
+                    checkId: `hooks.core-event.not-executable`,
+                    target: abs,
+                    message: `Event-directory hook core/hooks/${event}/${file} is not executable; the runtime skips non-executable event hooks silently.`,
+                    remediation: `chmod +x "${abs}"`,
+                });
+            }
+            else {
+                results.push({
+                    status: "PASS",
+                    checkId: `hooks.core-event`,
+                    target: abs,
+                    message: `Event-directory hook core/hooks/${event}/${file} is executable.`,
+                });
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Enumerate every `type: "command"` hook registration across every lifecycle
+ * event in a parsed settings object. Tolerant of malformed shapes — any
+ * non-conforming branch contributes nothing rather than throwing.
+ */
+function enumerateRegistrations(settings, source) {
+    const out = [];
+    if (!settings || typeof settings !== "object")
+        return out;
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return out;
+    for (const [event, entries] of Object.entries(hooks)) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            const inner = entry?.hooks;
+            if (!Array.isArray(inner))
+                continue;
+            for (const item of inner) {
+                const hook = item;
+                if (hook?.type === "command" &&
+                    typeof hook.command === "string" &&
+                    hook.command.length > 0) {
+                    out.push({ event, command: hook.command, source });
+                }
+            }
+        }
+    }
+    return out;
+}
+// --- command scanner (port of core/scripts/lib/hook-command-scan.sh) -----------
+/** A sentinel standing in for a resolved $CLAUDE_PROJECT_DIR expansion. */
+const SENTINEL = "\u0001";
+/** The interpreters whose first path argument is the script actually run. */
+const INTERPRETERS = new Set(["bash", "sh", "zsh", "dash", "ksh"]);
+/** Quote-aware analysis of a single hook command. See {@link CommandScan}. */
+export function scanHookCommand(command) {
+    const { first, unsafe } = tokenizeCommand(command);
+    const { required, gatedHookId } = requiredFromFirstCommand(first);
+    return {
+        unquotedProjectDir: unsafe,
+        requiredRelpaths: required,
+        gatedHookId,
+    };
+}
+/**
+ * Split a command the way `/bin/sh` would: track single- and double-quote state,
+ * honour backslash escapes, replace each $CLAUDE_PROJECT_DIR expansion with a
+ * sentinel, and flag the command when such an expansion sits outside double
+ * quotes. Mirrors the `tokenize` awk function in hook-command-scan.sh.
+ */
+function tokenizeCommand(command) {
+    const first = [];
+    let firstDone = false;
+    let unsafe = false;
+    let tok = "";
+    let inTok = false;
+    let inSingle = false;
+    let inDouble = false;
+    const endToken = () => {
+        if (inTok && !firstDone)
+            first.push(tok);
+        tok = "";
+        inTok = false;
+    };
+    const n = command.length;
+    let i = 0;
+    while (i < n) {
+        const c = command[i];
+        if (inSingle) {
+            if (c === "'")
+                inSingle = false;
+            else
+                tok += c;
+            inTok = true;
+            i += 1;
+            continue;
+        }
+        if (c === "\\") {
+            const d = i + 1 < n ? command[i + 1] : "";
+            if (d === "") {
+                tok += c;
+                inTok = true;
+                i += 1;
+                continue;
+            }
+            // In double quotes a backslash only escapes " \ $ ` — otherwise it is literal.
+            if (inDouble && d !== '"' && d !== "\\" && d !== "$" && d !== "`") {
+                tok += c;
+                inTok = true;
+                i += 1;
+                continue;
+            }
+            tok += d;
+            inTok = true;
+            i += 2;
+            continue;
+        }
+        if (c === '"') {
+            inDouble = !inDouble;
+            inTok = true;
+            i += 1;
+            continue;
+        }
+        if (!inDouble && c === "'") {
+            inSingle = true;
+            inTok = true;
+            i += 1;
+            continue;
+        }
+        const vl = varExpansionLen(command, i);
+        if (vl > 0) {
+            if (!inDouble)
+                unsafe = true;
+            tok += SENTINEL;
+            inTok = true;
+            i += vl;
+            continue;
+        }
+        if (!inDouble) {
+            if (c === " " || c === "\t") {
+                endToken();
+                i += 1;
+                continue;
+            }
+            if (c === "\n" ||
+                c === ";" ||
+                c === "&" ||
+                c === "|" ||
+                c === "(" ||
+                c === ")") {
+                endToken();
+                firstDone = true;
+                i += 1;
+                continue;
+            }
+        }
+        tok += c;
+        inTok = true;
+        i += 1;
+    }
+    endToken();
+    return { first, unsafe };
+}
+/** Length of a $CLAUDE_PROJECT_DIR expansion starting at index `i`, or 0. */
+function varExpansionLen(s, i) {
+    if (s.startsWith("$CLAUDE_PROJECT_DIR", i)) {
+        const next = s.charAt(i + 19);
+        if (next === "" || !/[A-Za-z0-9_]/.test(next))
+            return 19;
+        return 0;
+    }
+    if (s.startsWith("${CLAUDE_PROJECT_DIR}", i))
+        return 21;
+    return 0;
+}
+/**
+ * From the first simple command's tokens, return the scripts it actually
+ * executes (relative to the root) and the gated hook id when it routes through
+ * hook-gate.sh. Mirrors the `emit_required` awk function.
+ */
+function requiredFromFirstCommand(first) {
+    const required = [];
+    let gatedHookId = null;
+    let k = 0;
+    // Skip leading VAR=value environment assignments.
+    while (k < first.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(first[k]))
+        k += 1;
+    if (k >= first.length)
+        return { required, gatedHookId };
+    if (INTERPRETERS.has(baseName(first[k]))) {
+        k += 1;
+        while (k < first.length && first[k].startsWith("-")) {
+            // -c means the script is inline, not a file we can check.
+            if (/^-[A-Za-z]*c/.test(first[k]))
+                return { required, gatedHookId };
+            k += 1;
+        }
+    }
+    if (k >= first.length)
+        return { required, gatedHookId };
+    const rp = relpathOf(first[k]);
+    if (rp === "")
+        return { required, gatedHookId };
+    required.push(rp);
+    // hook-gate.sh runs the script named in its second argument; its first bare
+    // argument is the gated hook id.
+    if (baseName(rp) === "hook-gate.sh") {
+        for (let j = k + 1; j < first.length; j++) {
+            if (gatedHookId === null && !first[j].includes(SENTINEL) && first[j].length > 0) {
+                gatedHookId = first[j];
+            }
+            const rp2 = relpathOf(first[j]);
+            if (rp2 !== "") {
+                required.push(rp2);
+                break;
+            }
+        }
+    }
+    return { required, gatedHookId };
+}
+/**
+ * The path a token builds from its first $CLAUDE_PROJECT_DIR expansion: the text
+ * between the sentinel and either the next sentinel or the token end. Quoting is
+ * already collapsed, so a space inside the path survives. Only an absolute
+ * expansion (`$CLAUDE_PROJECT_DIR/…`) yields a relpath.
+ */
+function relpathOf(token) {
+    const p = token.indexOf(SENTINEL);
+    if (p < 0)
+        return "";
+    let q = token.slice(p + 1);
+    const r = q.indexOf(SENTINEL);
+    if (r >= 0)
+        q = q.slice(0, r);
+    if (q.charAt(0) !== "/")
+        return "";
+    return q.slice(1);
+}
+function readJsonFile(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return { present: false };
+    }
+    try {
+        return { present: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { present: true, invalid: true };
+    }
+}
+function readTextFile(file) {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function statSafe(file) {
+    try {
+        return fs.statSync(file);
+    }
+    catch {
+        return null;
+    }
+}
+function isExecutable(mode) {
+    return (mode & 0o111) !== 0;
+}
+/** Top-level `*.sh` filenames in `dir`, sorted; empty when `dir` is absent. */
+function listShellScripts(dir) {
+    return listDir(dir)
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".sh"))
+        .map((entry) => entry.name)
+        .sort();
+}
+/** Immediate subdirectory names of `dir`, sorted; empty when `dir` is absent. */
+function listSubdirs(dir) {
+    return listDir(dir)
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+}
+function listDir(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function baseName(p) {
+    const idx = p.lastIndexOf("/");
+    return idx >= 0 ? p.slice(idx + 1) : p;
+}
+/** 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 byKey(a, b) {
+    return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+}
+//# sourceMappingURL=claude-wiring.js.map

package/dist/lib/doctor/checks/codex-wiring.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Codex hook wiring and Claude-parity checks (US-005).
+ *
+ * Claude and Grok both execute the canonical `.claude/hooks/` scripts; only
+ * Codex runs duplicated copies under `.codex/hooks/`, so Codex is the entire
+ * drift surface the doctor has to police. This check does three things, all
+ * read-only and all against the resolved HQ tree (not the live host):
+ *
+ *   1. Enumerates the registrations in `.codex/hooks.json` and verifies each
+ *      referenced script exists and is executable — the Codex analogue of the
+ *      Claude wiring tier.
+ *   2. Compares every `.codex/hooks/<file>` against its same-named
+ *      `.claude/hooks/<file>` original and FAILs on any content divergence that
+ *      is not on the allowed-divergence list.
+ *   3. WARNs on any `.claude/hooks/<file>` that has no Codex counterpart, and
+ *      escalates that to FAIL when the hook id is in the `hook-gate.sh` minimal
+ *      profile, because minimal-profile membership marks it safety-critical.
+ *
+ * These are wiring checks, not live verification: Codex hook *execution* is only
+ * exercised when the doctor runs under the Codex host. That distinction is
+ * stated plainly in the report via an `NA` scope note, so a green Codex tier is
+ * never mistaken for "Codex actually enforced this here".
+ */
+import { type AllowedDivergenceLoad } from "../allowed-divergence.js";
+import type { CheckContext, CheckResult } from "../types.js";
+/** Options for {@link checkCodexWiring}; all injectable for hermetic tests. */
+export interface CodexWiringOptions {
+    /** Pre-loaded allowed-divergence list. Default: loaded from the tree. */
+    allowed?: AllowedDivergenceLoad;
+}
+/**
+ * Run the Codex tier of the hooks family against the resolved HQ tree. Never
+ * throws for a merely-broken tree — a missing or malformed `.codex/hooks.json`
+ * is reported as a result, not an exception.
+ */
+export declare function checkCodexWiring(context: CheckContext, options?: CodexWiringOptions): CheckResult[];
+/**
+ * Extract the hook ids listed in `is_in_minimal_profile()` from a `hook-gate.sh`
+ * source. Scoped to that one function's `{ … }` body so the standard and strict
+ * profiles' ids are never mixed in. A focused, self-contained parser: the Codex
+ * check only needs the minimal profile, so it does not depend on the broader
+ * profile parser built by the Claude wiring tier.
+ */
+export declare function parseMinimalProfileIds(gateSource: string): Set<string>;
+//# sourceMappingURL=codex-wiring.d.ts.map