@indigoai-us/hq-cli 5.98.3 → 5.99.1

package/dist/lib/doctor/payload-shapes.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Per-platform hook payload shapes, tool-name aliasing, and block protocols
+ * (US-010).
+ *
+ * `hq doctor --deep-test` replays one fixture case through all three platform
+ * adapters and compares their verdicts (parity.ts). The three platforms do not
+ * speak the same wire language, and this module owns every difference so the
+ * replay orchestration can stay platform-agnostic:
+ *
+ *   1. Payload shape. Claude and Codex hooks read a snake_case document
+ *      (`hook_event_name` / `tool_name` / `tool_input`). Grok speaks camelCase
+ *      (`hookEventName` / `toolName` / `toolInput`) and its own tool names
+ *      (`Shell`, `StrReplace`, …). {@link toClaudePayload}, {@link toCodexPayload},
+ *      and {@link toGrokPayload} normalise one case into each shape.
+ *
+ *   2. Tool-name aliases. Grok surfaces the same underlying tool under several
+ *      names — `Shell` / `run_terminal_command` for Bash, `StrReplace` /
+ *      `search_replace` for Edit, `write` for Write, and so on. The alias tables
+ *      here mirror the case statement in `.grok/hooks/hq-grok-hook-adapter.sh`
+ *      exactly, so a payload we emit is one the real adapter recognises, and a
+ *      Grok name the adapter would receive maps back to the canonical Claude
+ *      tool the fixtures are written against.
+ *
+ *   3. Block protocol. Claude and Codex signal a block with a non-zero exit.
+ *      Grok's PreToolUse block is a stdout `{"decision":"deny"}` document AND/OR
+ *      a non-zero exit — {@link interpretGrokBlock} recognises either, so a
+ *      correct Grok block that exits 0 with a deny decision is not misread as an
+ *      allow. Grok's passive events (everything but PreToolUse) run side-effect
+ *      hooks but cannot inject model-facing context or emit a decision at all;
+ *      {@link grokCanBlock} names that limitation for the replay to report NA.
+ *
+ * Everything here is pure and exhaustively unit-tested; parity.ts wires these to
+ * the real adapters and to the verdict comparison.
+ */
+/** The three platforms a fixture case is replayed through. */
+export type PlatformId = "claude" | "codex" | "grok";
+/** Canonical platform order for side-by-side reporting. */
+export declare const PARITY_PLATFORMS: readonly PlatformId[];
+/**
+ * The minimal slice of a fixture case the payload builders need: the lifecycle
+ * event, the tool name (canonical Claude name, as fixtures are authored), and
+ * the opaque tool input. A {@link import("./fixtures/schema.js").FixtureCase} is
+ * assignable to this.
+ */
+export interface CaseShape {
+    /** Lifecycle event, e.g. `PreToolUse`. */
+    event: string;
+    /** Canonical Claude tool name, e.g. `Bash`, `Edit`, `Read`. */
+    tool: string;
+    /** The tool input payload, opaque to normalisation. */
+    input: unknown;
+}
+/** Common fields stamped onto every payload so session-scoped hooks behave. */
+export interface PayloadContext {
+    /** Working directory the hook should see (the sandbox root). */
+    cwd: string;
+    /** Session id, so per-session dedupe does not collapse into a shared ledger. */
+    sessionId: string;
+}
+/** The snake_case document Claude and Codex hooks read from stdin. */
+export interface SnakeCasePayload {
+    hook_event_name: string;
+    tool_name: string;
+    tool_input: unknown;
+    cwd: string;
+    session_id: string;
+}
+/** The camelCase document the Grok adapter reads from stdin. */
+export interface GrokPayload {
+    hookEventName: string;
+    toolName: string;
+    toolInput: unknown;
+    cwd: string;
+    sessionId: string;
+}
+/**
+ * The canonical Grok tool name to emit for each canonical Claude tool. These are
+ * names the real adapter's case statement recognises; an unlisted tool is passed
+ * through unchanged (the adapter's `*` arm does the same). The AC requires at
+ * minimum `Shell` (Bash), `StrReplace` (Edit), `Read`, and `Write`.
+ */
+export declare const CLAUDE_TO_GROK_TOOL: Readonly<Record<string, string>>;
+/**
+ * Every Grok tool alias mapped back to its canonical Claude tool, mirroring the
+ * `case "$GTOOL" in …` block of `.grok/hooks/hq-grok-hook-adapter.sh`. Includes
+ * the snake_case aliases the AC calls out — `run_terminal_command`,
+ * `search_replace`, `write` — alongside the CamelCase forms.
+ */
+export declare const GROK_TO_CLAUDE_TOOL: Readonly<Record<string, string>>;
+/** The Grok tool name to emit for a canonical Claude tool (identity if unknown). */
+export declare function toGrokToolName(claudeTool: string): string;
+/**
+ * The canonical Claude tool a Grok tool name maps to, mirroring the adapter.
+ * An unrecognised name is returned unchanged (the adapter's `*` arm keeps it).
+ */
+export declare function resolveGrokTool(grokTool: string): string;
+/**
+ * Normalise a case into the Claude payload shape: snake_case keys, the canonical
+ * tool name, and the input under `tool_input`. This is exactly what
+ * `.claude/hooks/hook-gate.sh` delegates to a hook on stdin.
+ */
+export declare function toClaudePayload(c: CaseShape, ctx: PayloadContext): SnakeCasePayload;
+/**
+ * Normalise a case into the Codex payload shape. Codex hooks read the same
+ * snake_case document Claude does (the Codex adapter normalises its own edit
+ * events into this shape before the gate sees them), so this is structurally a
+ * Claude payload — kept a distinct function so a future Codex-specific quirk
+ * (e.g. an `apply_patch` representation) has one obvious seam to grow at.
+ */
+export declare function toCodexPayload(c: CaseShape, ctx: PayloadContext): SnakeCasePayload;
+/**
+ * Normalise a case into the Grok payload shape: camelCase keys and the Grok
+ * tool alias, matching what the real Grok adapter reads. The inner `toolInput`
+ * field names stay as the case authored them (the adapter reads
+ * `.toolInput.command` / `.toolInput.file_path` / …), so only the outer envelope
+ * is renamed.
+ */
+export declare function toGrokPayload(c: CaseShape, ctx: PayloadContext): GrokPayload;
+/**
+ * Convert a Grok camelCase payload back into the Claude-shaped snake_case
+ * document the gate delegates on stdin — exactly what
+ * `.grok/hooks/hq-grok-hook-adapter.sh` does internally before it pipes to
+ * `hook-gate.sh`: it reads the camelCase envelope, maps the Grok tool alias back
+ * to the canonical Claude tool, and builds `CLAUDE_JSON`. Reproducing that
+ * normalisation lets the replay route one Grok case through the same canonical
+ * `.claude/` gate + script the adapter ultimately execs, isolating a single hook.
+ */
+export declare function grokToSnakePayload(payload: GrokPayload): SnakeCasePayload;
+/**
+ * Grok's passive lifecycle events: they run side-effect hooks (autocommit,
+ * checkpoints, policy evaluation) but, unlike Claude/Codex, cannot inject
+ * model-facing context or emit a block decision. Only `PreToolUse` can deny.
+ * The set mirrors the adapter's event handlers.
+ */
+export declare const GROK_PASSIVE_EVENTS: readonly string[];
+/**
+ * Normalise the event-name spellings the Grok adapter accepts (`pre_tool_use`
+ * and `PreToolUse` both occur in Grok docs) to the canonical Claude spelling.
+ */
+export declare function normalizeGrokEvent(event: string): string;
+/**
+ * Whether Grok can produce a comparable block/allow verdict for this event.
+ * Only `PreToolUse` can — every other event is passive under Grok and its
+ * verdict must be reported NA rather than compared (AC5), never PASS or FAIL.
+ */
+export declare function grokCanBlock(event: string): boolean;
+/**
+ * Claude/Codex block protocol: a hook (through the gate) signals a block with a
+ * non-zero exit. Timeouts are handled upstream, so a `null` exit (killed) is not
+ * expected here; treated conservatively as non-zero.
+ */
+export declare function interpretExitBlock(exitCode: number | null): boolean;
+/**
+ * The decision a Grok adapter stdout carries, or null when none. Scans the
+ * output line by line for a JSON object with a string `decision` field —
+ * diagnostics on other lines (or on stderr) are ignored — and returns the last
+ * such decision seen, so a trailing `deny` is not masked by an earlier `allow`.
+ */
+export declare function parseGrokDecision(stdout: string): "deny" | "allow" | null;
+/**
+ * Grok block protocol: a block is either a non-zero exit OR a stdout `deny`
+ * decision — the adapter's `deny()` emits both, but a deny with exit 0 is still
+ * a block (AC3), so both signals are honoured. A `null` exit (timeout/kill) is
+ * handled upstream; here it counts as non-zero and therefore a block.
+ */
+export declare function interpretGrokBlock(output: {
+    exitCode: number | null;
+    stdout: string;
+}): boolean;
+//# sourceMappingURL=payload-shapes.d.ts.map

package/dist/lib/doctor/payload-shapes.js

@@ -0,0 +1,275 @@
+/**
+ * Per-platform hook payload shapes, tool-name aliasing, and block protocols
+ * (US-010).
+ *
+ * `hq doctor --deep-test` replays one fixture case through all three platform
+ * adapters and compares their verdicts (parity.ts). The three platforms do not
+ * speak the same wire language, and this module owns every difference so the
+ * replay orchestration can stay platform-agnostic:
+ *
+ *   1. Payload shape. Claude and Codex hooks read a snake_case document
+ *      (`hook_event_name` / `tool_name` / `tool_input`). Grok speaks camelCase
+ *      (`hookEventName` / `toolName` / `toolInput`) and its own tool names
+ *      (`Shell`, `StrReplace`, …). {@link toClaudePayload}, {@link toCodexPayload},
+ *      and {@link toGrokPayload} normalise one case into each shape.
+ *
+ *   2. Tool-name aliases. Grok surfaces the same underlying tool under several
+ *      names — `Shell` / `run_terminal_command` for Bash, `StrReplace` /
+ *      `search_replace` for Edit, `write` for Write, and so on. The alias tables
+ *      here mirror the case statement in `.grok/hooks/hq-grok-hook-adapter.sh`
+ *      exactly, so a payload we emit is one the real adapter recognises, and a
+ *      Grok name the adapter would receive maps back to the canonical Claude
+ *      tool the fixtures are written against.
+ *
+ *   3. Block protocol. Claude and Codex signal a block with a non-zero exit.
+ *      Grok's PreToolUse block is a stdout `{"decision":"deny"}` document AND/OR
+ *      a non-zero exit — {@link interpretGrokBlock} recognises either, so a
+ *      correct Grok block that exits 0 with a deny decision is not misread as an
+ *      allow. Grok's passive events (everything but PreToolUse) run side-effect
+ *      hooks but cannot inject model-facing context or emit a decision at all;
+ *      {@link grokCanBlock} names that limitation for the replay to report NA.
+ *
+ * Everything here is pure and exhaustively unit-tested; parity.ts wires these to
+ * the real adapters and to the verdict comparison.
+ */
+/** Canonical platform order for side-by-side reporting. */
+export const PARITY_PLATFORMS = [
+    "claude",
+    "codex",
+    "grok",
+];
+// --- tool-name aliases ---------------------------------------------------------
+/**
+ * The canonical Grok tool name to emit for each canonical Claude tool. These are
+ * names the real adapter's case statement recognises; an unlisted tool is passed
+ * through unchanged (the adapter's `*` arm does the same). The AC requires at
+ * minimum `Shell` (Bash), `StrReplace` (Edit), `Read`, and `Write`.
+ */
+export const CLAUDE_TO_GROK_TOOL = {
+    Bash: "Shell",
+    Edit: "StrReplace",
+    Write: "Write",
+    Read: "Read",
+    Grep: "Grep",
+    Glob: "ListDir",
+    WebSearch: "WebSearch",
+    Task: "spawn_subagent",
+};
+/**
+ * Every Grok tool alias mapped back to its canonical Claude tool, mirroring the
+ * `case "$GTOOL" in …` block of `.grok/hooks/hq-grok-hook-adapter.sh`. Includes
+ * the snake_case aliases the AC calls out — `run_terminal_command`,
+ * `search_replace`, `write` — alongside the CamelCase forms.
+ */
+export const GROK_TO_CLAUDE_TOOL = {
+    // Bash
+    run_terminal_command: "Bash",
+    Shell: "Bash",
+    Bash: "Bash",
+    bash: "Bash",
+    // Edit
+    search_replace: "Edit",
+    StrReplace: "Edit",
+    Edit: "Edit",
+    MultiEdit: "Edit",
+    apply_patch: "Edit",
+    // Write
+    write: "Write",
+    Write: "Write",
+    // Read
+    read_file: "Read",
+    Read: "Read",
+    // Grep
+    grep: "Grep",
+    Grep: "Grep",
+    // Glob
+    list_dir: "Glob",
+    Glob: "Glob",
+    ListDir: "Glob",
+    // WebSearch
+    web_search: "WebSearch",
+    WebSearch: "WebSearch",
+    // Task
+    spawn_subagent: "Task",
+    Task: "Task",
+};
+/** The Grok tool name to emit for a canonical Claude tool (identity if unknown). */
+export function toGrokToolName(claudeTool) {
+    return CLAUDE_TO_GROK_TOOL[claudeTool] ?? claudeTool;
+}
+/**
+ * The canonical Claude tool a Grok tool name maps to, mirroring the adapter.
+ * An unrecognised name is returned unchanged (the adapter's `*` arm keeps it).
+ */
+export function resolveGrokTool(grokTool) {
+    return GROK_TO_CLAUDE_TOOL[grokTool] ?? grokTool;
+}
+// --- payload builders ----------------------------------------------------------
+/**
+ * Normalise a case into the Claude payload shape: snake_case keys, the canonical
+ * tool name, and the input under `tool_input`. This is exactly what
+ * `.claude/hooks/hook-gate.sh` delegates to a hook on stdin.
+ */
+export function toClaudePayload(c, ctx) {
+    return {
+        hook_event_name: c.event,
+        tool_name: c.tool,
+        tool_input: c.input,
+        cwd: ctx.cwd,
+        session_id: ctx.sessionId,
+    };
+}
+/**
+ * Normalise a case into the Codex payload shape. Codex hooks read the same
+ * snake_case document Claude does (the Codex adapter normalises its own edit
+ * events into this shape before the gate sees them), so this is structurally a
+ * Claude payload — kept a distinct function so a future Codex-specific quirk
+ * (e.g. an `apply_patch` representation) has one obvious seam to grow at.
+ */
+export function toCodexPayload(c, ctx) {
+    return {
+        hook_event_name: c.event,
+        tool_name: c.tool,
+        tool_input: c.input,
+        cwd: ctx.cwd,
+        session_id: ctx.sessionId,
+    };
+}
+/**
+ * Normalise a case into the Grok payload shape: camelCase keys and the Grok
+ * tool alias, matching what the real Grok adapter reads. The inner `toolInput`
+ * field names stay as the case authored them (the adapter reads
+ * `.toolInput.command` / `.toolInput.file_path` / …), so only the outer envelope
+ * is renamed.
+ */
+export function toGrokPayload(c, ctx) {
+    return {
+        hookEventName: c.event,
+        toolName: toGrokToolName(c.tool),
+        toolInput: c.input,
+        cwd: ctx.cwd,
+        sessionId: ctx.sessionId,
+    };
+}
+/**
+ * Convert a Grok camelCase payload back into the Claude-shaped snake_case
+ * document the gate delegates on stdin — exactly what
+ * `.grok/hooks/hq-grok-hook-adapter.sh` does internally before it pipes to
+ * `hook-gate.sh`: it reads the camelCase envelope, maps the Grok tool alias back
+ * to the canonical Claude tool, and builds `CLAUDE_JSON`. Reproducing that
+ * normalisation lets the replay route one Grok case through the same canonical
+ * `.claude/` gate + script the adapter ultimately execs, isolating a single hook.
+ */
+export function grokToSnakePayload(payload) {
+    return {
+        hook_event_name: payload.hookEventName,
+        tool_name: resolveGrokTool(payload.toolName),
+        tool_input: payload.toolInput,
+        cwd: payload.cwd,
+        session_id: payload.sessionId,
+    };
+}
+// --- Grok events ---------------------------------------------------------------
+/**
+ * Grok's passive lifecycle events: they run side-effect hooks (autocommit,
+ * checkpoints, policy evaluation) but, unlike Claude/Codex, cannot inject
+ * model-facing context or emit a block decision. Only `PreToolUse` can deny.
+ * The set mirrors the adapter's event handlers.
+ */
+export const GROK_PASSIVE_EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PostToolUse",
+    "Stop",
+    "PreCompact",
+    "SessionEnd",
+];
+/**
+ * Normalise the event-name spellings the Grok adapter accepts (`pre_tool_use`
+ * and `PreToolUse` both occur in Grok docs) to the canonical Claude spelling.
+ */
+export function normalizeGrokEvent(event) {
+    switch (event) {
+        case "pre_tool_use":
+        case "PreToolUse":
+            return "PreToolUse";
+        case "post_tool_use":
+        case "PostToolUse":
+            return "PostToolUse";
+        case "session_start":
+        case "SessionStart":
+            return "SessionStart";
+        case "user_prompt_submit":
+        case "UserPromptSubmit":
+            return "UserPromptSubmit";
+        case "pre_compact":
+        case "PreCompact":
+            return "PreCompact";
+        case "stop":
+        case "Stop":
+            return "Stop";
+        case "session_end":
+        case "SessionEnd":
+            return "SessionEnd";
+        default:
+            return event;
+    }
+}
+/**
+ * Whether Grok can produce a comparable block/allow verdict for this event.
+ * Only `PreToolUse` can — every other event is passive under Grok and its
+ * verdict must be reported NA rather than compared (AC5), never PASS or FAIL.
+ */
+export function grokCanBlock(event) {
+    return normalizeGrokEvent(event) === "PreToolUse";
+}
+// --- block protocols -----------------------------------------------------------
+/**
+ * Claude/Codex block protocol: a hook (through the gate) signals a block with a
+ * non-zero exit. Timeouts are handled upstream, so a `null` exit (killed) is not
+ * expected here; treated conservatively as non-zero.
+ */
+export function interpretExitBlock(exitCode) {
+    return exitCode !== 0;
+}
+/**
+ * The decision a Grok adapter stdout carries, or null when none. Scans the
+ * output line by line for a JSON object with a string `decision` field —
+ * diagnostics on other lines (or on stderr) are ignored — and returns the last
+ * such decision seen, so a trailing `deny` is not masked by an earlier `allow`.
+ */
+export function parseGrokDecision(stdout) {
+    let decision = null;
+    for (const rawLine of stdout.split("\n")) {
+        const line = rawLine.trim();
+        if (!line.startsWith("{"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object")
+            continue;
+        const value = parsed.decision;
+        if (value === "deny" || value === "block")
+            decision = "deny";
+        else if (value === "allow")
+            decision = "allow";
+    }
+    return decision;
+}
+/**
+ * Grok block protocol: a block is either a non-zero exit OR a stdout `deny`
+ * decision — the adapter's `deny()` emits both, but a deny with exit 0 is still
+ * a block (AC3), so both signals are honoured. A `null` exit (timeout/kill) is
+ * handled upstream; here it counts as non-zero and therefore a block.
+ */
+export function interpretGrokBlock(output) {
+    if (output.exitCode !== 0)
+        return true;
+    return parseGrokDecision(output.stdout) === "deny";
+}
+//# sourceMappingURL=payload-shapes.js.map