@indigoai-us/hq-cli 5.98.3 → 5.99.1

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

@@ -0,0 +1,376 @@
+/**
+ * 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 * as fs from "node:fs";
+import * as path from "node:path";
+import { ALLOWED_DIVERGENCE_RELPATH, loadAllowedDivergence, } from "../allowed-divergence.js";
+/**
+ * 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 function checkCodexWiring(context, options = {}) {
+    const hqRoot = context.hqRoot;
+    const allowed = options.allowed ?? loadAllowedDivergence(hqRoot);
+    const results = [];
+    results.push({
+        status: "NA",
+        checkId: "hooks.codex.scope",
+        target: "codex",
+        message: "Codex hook checks are wiring only (registration, executable bit, and Claude parity); live Codex hook execution is verified only when the doctor runs under the Codex host.",
+    });
+    results.push(...checkRegistrations(hqRoot));
+    results.push(...checkParity(hqRoot, allowed));
+    for (const problem of allowed.problems) {
+        results.push({
+            status: "WARN",
+            checkId: "hooks.codex.allowed-divergence-invalid",
+            target: problem.file ?? ALLOWED_DIVERGENCE_RELPATH,
+            message: problem.message,
+        });
+    }
+    return results;
+}
+// --- 1. Registration checks ----------------------------------------------------
+function checkRegistrations(hqRoot) {
+    const results = [];
+    const hooksJsonPath = path.join(hqRoot, ".codex", "hooks.json");
+    let raw;
+    try {
+        raw = fs.readFileSync(hooksJsonPath, "utf8");
+    }
+    catch {
+        results.push({
+            status: "FAIL",
+            checkId: "hooks.codex.registrations-present",
+            target: hooksJsonPath,
+            message: ".codex/hooks.json is missing — no Codex hooks are wired.",
+        });
+        return results;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        results.push({
+            status: "FAIL",
+            checkId: "hooks.codex.registrations-valid",
+            target: hooksJsonPath,
+            message: ".codex/hooks.json is present but is not valid JSON.",
+        });
+        return results;
+    }
+    const registrations = collectRegistrations(parsed);
+    if (registrations.length === 0) {
+        results.push({
+            status: "WARN",
+            checkId: "hooks.codex.registrations-present",
+            target: hooksJsonPath,
+            message: ".codex/hooks.json declares no hook registrations.",
+        });
+        return results;
+    }
+    const gatesChecked = new Set();
+    for (const registration of registrations) {
+        results.push(...checkRegistration(hqRoot, registration, gatesChecked));
+    }
+    return results;
+}
+function checkRegistration(hqRoot, registration, gatesChecked) {
+    const results = [];
+    const scriptPath = resolvePath(hqRoot, registration.script);
+    const id = registration.id ??
+        (scriptPath ? path.basename(scriptPath, ".sh") : "unknown");
+    if (!scriptPath) {
+        results.push({
+            status: "FAIL",
+            checkId: "hooks.codex.registration",
+            target: id,
+            message: `Codex registration for ${id} does not reference a hook script path.`,
+        });
+        return results;
+    }
+    const state = fileState(scriptPath);
+    if (!state.present) {
+        results.push({
+            status: "FAIL",
+            checkId: "hooks.codex.registration",
+            target: id,
+            message: `Registered Codex hook script is missing: ${scriptPath}`,
+        });
+    }
+    else if (!state.executable) {
+        results.push({
+            status: "FAIL",
+            checkId: "hooks.codex.registration",
+            target: id,
+            message: `Registered Codex hook script is present but not executable: ${scriptPath}`,
+            remediation: `chmod +x ${scriptPath}`,
+        });
+    }
+    else {
+        results.push({
+            status: "PASS",
+            checkId: "hooks.codex.registration",
+            target: id,
+            message: `Codex hook ${id} is registered, present, and executable.`,
+        });
+    }
+    // The gate is referenced by every registration; check each distinct gate once.
+    const gatePath = resolvePath(hqRoot, registration.gate);
+    if (gatePath && !gatesChecked.has(gatePath)) {
+        gatesChecked.add(gatePath);
+        const gateState = fileState(gatePath);
+        if (!gateState.present) {
+            results.push({
+                status: "FAIL",
+                checkId: "hooks.codex.gate",
+                target: gatePath,
+                message: `Codex hook-gate is missing: ${gatePath}`,
+            });
+        }
+        else if (!gateState.executable) {
+            results.push({
+                status: "FAIL",
+                checkId: "hooks.codex.gate",
+                target: gatePath,
+                message: `Codex hook-gate is present but not executable: ${gatePath}`,
+                remediation: `chmod +x ${gatePath}`,
+            });
+        }
+        else {
+            results.push({
+                status: "PASS",
+                checkId: "hooks.codex.gate",
+                target: gatePath,
+                message: "Codex hook-gate is present and executable.",
+            });
+        }
+    }
+    return results;
+}
+/** Flatten `{hooks:{Event:[{hooks:[{command}]}]}}` into parsed registrations. */
+function collectRegistrations(parsed) {
+    const registrations = [];
+    for (const command of collectCommands(parsed)) {
+        registrations.push(parseCodexCommand(command));
+    }
+    return registrations;
+}
+/** Parse a Codex gate command: `'<gate>' <hook-id> '<script>'`. */
+function parseCodexCommand(command) {
+    const canonical = command.match(/'([^']*)'\s+(\S+)\s+'([^']*)'/);
+    if (canonical) {
+        return { gate: canonical[1], id: canonical[2], script: canonical[3] };
+    }
+    const quoted = [...command.matchAll(/'([^']*)'/g)].map((m) => m[1]);
+    return {
+        gate: quoted[0],
+        script: quoted.length >= 2 ? quoted[quoted.length - 1] : undefined,
+    };
+}
+// --- 2 & 3. Parity, missing counterparts, stale allowed entries ---------------
+function checkParity(hqRoot, allowed) {
+    const results = [];
+    const claudeDir = path.join(hqRoot, ".claude", "hooks");
+    const codexDir = path.join(hqRoot, ".codex", "hooks");
+    const claudeFiles = listShellScripts(claudeDir);
+    const codexFiles = listShellScripts(codexDir);
+    const claudeSet = new Set(claudeFiles);
+    const codexSet = new Set(codexFiles);
+    const allowedSet = new Set(allowed.entries.map((entry) => entry.file));
+    const minimalIds = readMinimalProfileIds(hqRoot);
+    const driftingFiles = new Set();
+    // Content parity for every Codex mirror with a Claude counterpart.
+    for (const file of codexFiles) {
+        if (!claudeSet.has(file))
+            continue; // Codex-only script — not a mirror.
+        if (filesEqual(path.join(codexDir, file), path.join(claudeDir, file))) {
+            continue; // Byte-identical — healthy.
+        }
+        driftingFiles.add(file);
+        if (allowedSet.has(file))
+            continue; // Intentional divergence — suppressed.
+        results.push({
+            status: "FAIL",
+            checkId: "hooks.codex.parity",
+            target: file,
+            message: `Codex mirror .codex/hooks/${file} differs from its Claude original and is not on the allowed-divergence list.`,
+            remediation: `Reconcile the two copies, or add {file: ${file}, reason: ...} to ${ALLOWED_DIVERGENCE_RELPATH}.`,
+        });
+    }
+    // Claude hooks with no Codex counterpart: WARN, or FAIL when safety-critical.
+    for (const file of claudeFiles) {
+        if (codexSet.has(file))
+            continue;
+        const id = file.replace(/\.sh$/, "");
+        if (minimalIds.has(id)) {
+            results.push({
+                status: "FAIL",
+                checkId: "hooks.codex.missing-counterpart",
+                target: file,
+                message: `Safety-critical Claude hook ${file} has no Codex counterpart — it is in the hook-gate.sh minimal profile, so Codex is missing an enforced guard.`,
+                remediation: `Mirror .claude/hooks/${file} into .codex/hooks/${file}.`,
+            });
+        }
+        else {
+            results.push({
+                status: "WARN",
+                checkId: "hooks.codex.missing-counterpart",
+                target: file,
+                message: `Claude hook ${file} has no Codex counterpart; Codex will not run it.`,
+                remediation: `Mirror .claude/hooks/${file} into .codex/hooks/${file} if Codex should enforce it.`,
+            });
+        }
+    }
+    // Stale allowed-divergence entries: the list must not rot into suppressing
+    // drift that no longer exists.
+    for (const entry of allowed.entries) {
+        if (driftingFiles.has(entry.file))
+            continue;
+        results.push({
+            status: "WARN",
+            checkId: "hooks.codex.allowed-divergence-stale",
+            target: entry.file,
+            message: `allowed-divergence entry for ${entry.file} is stale — the Codex and Claude copies no longer differ. Remove it so the list cannot rot.`,
+        });
+    }
+    return results;
+}
+// --- minimal-profile parsing ---------------------------------------------------
+function readMinimalProfileIds(hqRoot) {
+    const gatePath = path.join(hqRoot, ".claude", "hooks", "hook-gate.sh");
+    let source;
+    try {
+        source = fs.readFileSync(gatePath, "utf8");
+    }
+    catch {
+        return new Set();
+    }
+    return parseMinimalProfileIds(source);
+}
+/**
+ * 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 function parseMinimalProfileIds(gateSource) {
+    const ids = new Set();
+    const fnIndex = gateSource.indexOf("is_in_minimal_profile");
+    if (fnIndex < 0)
+        return ids;
+    const body = extractBraceBlock(gateSource, fnIndex);
+    // Each `case` arm that returns 0 is a pipe-delimited list of ids before `)`.
+    const armPattern = /([A-Za-z0-9_.|-]+)\)\s*(?:\r?\n)\s*return\s+0\b/g;
+    let match;
+    while ((match = armPattern.exec(body)) !== null) {
+        for (const token of match[1].split("|")) {
+            const id = token.trim();
+            if (id && id !== "*")
+                ids.add(id);
+        }
+    }
+    return ids;
+}
+/** Return the contents of the first brace-balanced `{ … }` block after `from`. */
+function extractBraceBlock(source, from) {
+    const open = source.indexOf("{", from);
+    if (open < 0)
+        return "";
+    let depth = 0;
+    for (let i = open; i < source.length; i++) {
+        const char = source[i];
+        if (char === "{")
+            depth++;
+        else if (char === "}") {
+            depth--;
+            if (depth === 0)
+                return source.slice(open + 1, i);
+        }
+    }
+    return source.slice(open + 1);
+}
+// --- shared low-level helpers --------------------------------------------------
+/** Collect every `command` string from a `{hooks:{Event:[{hooks:[…]}]}}` doc. */
+function collectCommands(parsed) {
+    const commands = [];
+    if (!parsed || typeof parsed !== "object")
+        return commands;
+    const hooks = parsed.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return commands;
+    for (const entries of Object.values(hooks)) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            const inner = entry?.hooks;
+            if (!Array.isArray(inner))
+                continue;
+            for (const hook of inner) {
+                const command = hook?.command;
+                if (typeof command === "string")
+                    commands.push(command);
+            }
+        }
+    }
+    return commands;
+}
+function resolvePath(hqRoot, target) {
+    if (!target)
+        return null;
+    return path.isAbsolute(target) ? target : path.resolve(hqRoot, target);
+}
+function fileState(target) {
+    try {
+        const stat = fs.statSync(target);
+        return { present: stat.isFile(), executable: (stat.mode & 0o111) !== 0 };
+    }
+    catch {
+        return { present: false, executable: false };
+    }
+}
+function filesEqual(a, b) {
+    try {
+        return fs.readFileSync(a).equals(fs.readFileSync(b));
+    }
+    catch {
+        return false;
+    }
+}
+function listShellScripts(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".sh"))
+        .map((entry) => entry.name)
+        .sort();
+}
+//# sourceMappingURL=codex-wiring.js.map

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

@@ -0,0 +1,35 @@
+/**
+ * Grok hook wiring checks (US-005).
+ *
+ * Grok executes the canonical `.claude/hooks/` scripts (it does not duplicate
+ * them the way Codex does), reaching them through a small adapter and a
+ * user-global bridge. So the Grok tier has no content-parity surface; instead it
+ * verifies the three things that make Grok enforcement actually reachable:
+ *
+ *   1. `.grok/hooks/hq-grok.json` exists and registers `hq-grok-hook-adapter.sh`.
+ *   2. `hq-grok-hook-adapter.sh` exists and is executable.
+ *   3. The user-global bridge under `~/.grok/hooks/` is installed — Grok loads
+ *      user hooks reliably but project hooks only when the folder is trusted, so
+ *      the bridge is what actually routes Grok through the HQ adapter. When it is
+ *      absent the doctor WARNs (not FAILs — a project-local run cannot always see
+ *      it) and points at `core/scripts/grok-trust.sh` to install it.
+ *
+ * These are wiring checks, not live verification: Grok hook execution is only
+ * exercised under the Grok host. The report states that plainly via an `NA`
+ * scope note. The bridge directory is injectable so tests are hermetic and never
+ * depend on the developer's real home directory.
+ */
+import type { CheckContext, CheckResult } from "../types.js";
+/** The command a user runs to install the user-global Grok bridge. */
+export declare const GROK_TRUST_REMEDIATION = "bash core/scripts/grok-trust.sh";
+/** Options for {@link checkGrokWiring}; injectable for hermetic tests. */
+export interface GrokWiringOptions {
+    /** Directory of the user-global Grok bridge. Default: `~/.grok/hooks`. */
+    bridgeDir?: string;
+}
+/**
+ * Run the Grok tier of the hooks family against the resolved HQ tree. Never
+ * throws for a merely-broken tree — every broken state is reported as a result.
+ */
+export declare function checkGrokWiring(context: CheckContext, options?: GrokWiringOptions): CheckResult[];
+//# sourceMappingURL=grok-wiring.d.ts.map

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

@@ -0,0 +1,186 @@
+/**
+ * Grok hook wiring checks (US-005).
+ *
+ * Grok executes the canonical `.claude/hooks/` scripts (it does not duplicate
+ * them the way Codex does), reaching them through a small adapter and a
+ * user-global bridge. So the Grok tier has no content-parity surface; instead it
+ * verifies the three things that make Grok enforcement actually reachable:
+ *
+ *   1. `.grok/hooks/hq-grok.json` exists and registers `hq-grok-hook-adapter.sh`.
+ *   2. `hq-grok-hook-adapter.sh` exists and is executable.
+ *   3. The user-global bridge under `~/.grok/hooks/` is installed — Grok loads
+ *      user hooks reliably but project hooks only when the folder is trusted, so
+ *      the bridge is what actually routes Grok through the HQ adapter. When it is
+ *      absent the doctor WARNs (not FAILs — a project-local run cannot always see
+ *      it) and points at `core/scripts/grok-trust.sh` to install it.
+ *
+ * These are wiring checks, not live verification: Grok hook execution is only
+ * exercised under the Grok host. The report states that plainly via an `NA`
+ * scope note. The bridge directory is injectable so tests are hermetic and never
+ * depend on the developer's real home directory.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** The command a user runs to install the user-global Grok bridge. */
+export const GROK_TRUST_REMEDIATION = "bash core/scripts/grok-trust.sh";
+/** Files that grok-trust.sh installs into `~/.grok/hooks/` for the bridge. */
+const GROK_BRIDGE_FILES = ["hq-hq-bridge.sh", "hq-hq-bridge.json"];
+/**
+ * Run the Grok tier of the hooks family against the resolved HQ tree. Never
+ * throws for a merely-broken tree — every broken state is reported as a result.
+ */
+export function checkGrokWiring(context, options = {}) {
+    const grokDir = path.join(context.hqRoot, ".grok", "hooks");
+    const bridgeDir = options.bridgeDir ?? path.join(os.homedir(), ".grok", "hooks");
+    return [
+        {
+            status: "NA",
+            checkId: "hooks.grok.scope",
+            target: "grok",
+            message: "Grok hook checks are wiring only (registration, adapter executable bit, and user-global bridge presence); live Grok hook execution is verified only when the doctor runs under the Grok host.",
+        },
+        checkRegistration(path.join(grokDir, "hq-grok.json")),
+        checkAdapter(path.join(grokDir, "hq-grok-hook-adapter.sh")),
+        checkBridge(bridgeDir),
+    ];
+}
+function checkRegistration(registrationPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(registrationPath, "utf8");
+    }
+    catch {
+        return {
+            status: "FAIL",
+            checkId: "hooks.grok.registration",
+            target: registrationPath,
+            message: ".grok/hooks/hq-grok.json is missing — Grok will not run the HQ adapter.",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            status: "FAIL",
+            checkId: "hooks.grok.registration",
+            target: registrationPath,
+            message: ".grok/hooks/hq-grok.json is present but is not valid JSON.",
+        };
+    }
+    const commands = collectCommands(parsed);
+    if (commands.length === 0) {
+        return {
+            status: "FAIL",
+            checkId: "hooks.grok.registration",
+            target: registrationPath,
+            message: ".grok/hooks/hq-grok.json declares no hook registrations.",
+        };
+    }
+    if (!commands.some((command) => command.includes("hq-grok-hook-adapter.sh"))) {
+        return {
+            status: "FAIL",
+            checkId: "hooks.grok.registration",
+            target: registrationPath,
+            message: ".grok/hooks/hq-grok.json does not register hq-grok-hook-adapter.sh.",
+        };
+    }
+    return {
+        status: "PASS",
+        checkId: "hooks.grok.registration",
+        target: registrationPath,
+        message: `.grok/hooks/hq-grok.json registers the HQ Grok adapter across ${commands.length} event${commands.length === 1 ? "" : "s"}.`,
+    };
+}
+function checkAdapter(adapterPath) {
+    const state = fileState(adapterPath);
+    if (!state.present) {
+        return {
+            status: "FAIL",
+            checkId: "hooks.grok.adapter",
+            target: adapterPath,
+            message: "hq-grok-hook-adapter.sh is missing.",
+        };
+    }
+    if (!state.executable) {
+        return {
+            status: "FAIL",
+            checkId: "hooks.grok.adapter",
+            target: adapterPath,
+            message: "hq-grok-hook-adapter.sh is present but not executable.",
+            remediation: `chmod +x ${adapterPath}`,
+        };
+    }
+    return {
+        status: "PASS",
+        checkId: "hooks.grok.adapter",
+        target: adapterPath,
+        message: "hq-grok-hook-adapter.sh is present and executable.",
+    };
+}
+function checkBridge(bridgeDir) {
+    if (bridgeInstalled(bridgeDir)) {
+        return {
+            status: "PASS",
+            checkId: "hooks.grok.bridge",
+            target: bridgeDir,
+            message: `User-global Grok bridge is installed at ${bridgeDir}.`,
+        };
+    }
+    return {
+        status: "WARN",
+        checkId: "hooks.grok.bridge",
+        target: bridgeDir,
+        message: `User-global Grok bridge is not installed at ${bridgeDir}; Grok user hooks will not reach the HQ adapter. Install it with \`${GROK_TRUST_REMEDIATION}\`.`,
+        remediation: GROK_TRUST_REMEDIATION,
+    };
+}
+function bridgeInstalled(bridgeDir) {
+    for (const name of GROK_BRIDGE_FILES) {
+        try {
+            if (fs.statSync(path.join(bridgeDir, name)).isFile())
+                return true;
+        }
+        catch {
+            // Keep checking the remaining bridge files.
+        }
+    }
+    return false;
+}
+// --- shared low-level helpers --------------------------------------------------
+/** Collect every `command` string from a `{hooks:{Event:[{hooks:[…]}]}}` doc. */
+function collectCommands(parsed) {
+    const commands = [];
+    if (!parsed || typeof parsed !== "object")
+        return commands;
+    const hooks = parsed.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return commands;
+    for (const entries of Object.values(hooks)) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            const inner = entry?.hooks;
+            if (!Array.isArray(inner))
+                continue;
+            for (const hook of inner) {
+                const command = hook?.command;
+                if (typeof command === "string")
+                    commands.push(command);
+            }
+        }
+    }
+    return commands;
+}
+function fileState(target) {
+    try {
+        const stat = fs.statSync(target);
+        return { present: stat.isFile(), executable: (stat.mode & 0o111) !== 0 };
+    }
+    catch {
+        return { present: false, executable: false };
+    }
+}
+//# sourceMappingURL=grok-wiring.js.map