howtofixcli 0.7.13 → 0.7.15

package/dist/hooks.js

@@ -1,443 +0,0 @@
-/**
- * User-configured hooks: shell commands that run at lifecycle points.
- *
- * Why this exists: every extension in this CLI is compiled into the bundle. A
- * user who wants "run prettier after every edit" or "refuse any `rm -rf`" or
- * "add our house rules to every prompt" has to edit the source and rebuild — or
- * repeat themselves every session. Claude Code answers this with **hooks**: a
- * JSON config naming a shell command per lifecycle point, and a stdin/stdout
- * contract the command speaks. That is the right shape for this because the
- * command can be anything the user already has — a script, `jq`, a linter — with
- * no build step and no TypeScript.
- *
- * The SDK's extension API is the substrate (`hxf.on(...)` exposes 48 events), but
- * it requires code in the bundle. This module is the declarative layer on top: a
- * config file, mapped onto the SDK's own events.
- *
- *   <AGENT_DIR>/hooks.json
- *
- * ## The contract (deliberately Claude Code's, so it is already familiar)
- *
- * The command receives a JSON payload on **stdin** and answers on **stdout**:
- *
- * - **exit 0** — allowed. `stdout` may carry JSON with a `hookSpecificOutput`
- *   block (see below). Plain text on stdout is added as context where the event
- *   has a place for it.
- * - **exit 2** — blocked. `stderr` is the reason the model and the user are
- *   shown. This is Claude Code's convention and it is the useful one: a hook
- *   needs a way to say no that is not the same as "the hook crashed".
- * - **any other exit** — the hook failed. It is reported and the action is
- *   allowed, because a broken linter must not become a broken session.
- *
- * `hookSpecificOutput` fields, matching Claude Code:
- *
- * ```json
- * { "hookSpecificOutput": {
- *     "hookEventName": "PreToolUse",
- *     "permissionDecision": "deny",
- *     "permissionDecisionReason": "no rm -rf in this repo",
- *     "additionalContext": "…" } }
- * ```
- *
- * ## What is supported, and what is not
- *
- * Supported: `PreToolUse` (block a call, or rewrite its arguments),
- * `PostToolUse` (add context after one), `UserPromptSubmit` (add context to a
- * prompt, or block it), `SessionStart` (add context once per session), `Stop`
- * (notification when a run settles), `PreCompact` (observe a compaction),
- * `SessionEnd` (observe a shutdown).
- *
- * Not supported, and named rather than silently ignored: `SubagentStop`,
- * `Notification`, `PermissionRequest`, `PostToolUseFailure` do not map onto an
- * event this CLI can act on yet. An unknown name is reported at load, never
- * dropped quietly — a hook the user wrote that never fires is worse than a
- * config error.
- *
- * ## Rules that are load-bearing
- *
- * - **A rewritten tool input is validated before it is used.** `updatedInput` is
- *   the most dangerous field in the contract: it replaces what the tool will
- *   actually do. Claude Code rejects a rewrite that fails the tool's schema, and
- *   so do we — an unvalidated rewrite turns a guard into a weapon. The schema
- *   comes from the SDK's own `getAllTools()`, so it is the same one the provider
- *   was given.
- * - **A rewrite is applied only when nothing blocks.** A hook that denies wins
- *   over one that rewrites: refusing is the stronger statement.
- * - **A hook is a subprocess on an interactive path, so it must be async and
- *   bounded.** Every spawn is `spawn` (never `execFileSync`) with a per-hook
- *   timeout, because a hung hook would otherwise freeze the TUI for as long as
- *   the process lives. On timeout the hook is killed and the action is allowed.
- * - **A hook that cannot run is not a reason to refuse to work.** A missing
- *   config, unreadable file, bad JSON, or a command that does not exist all
- *   degrade to "no hooks" with a diagnostic.
- * - **The config is read once per session**, not per tool call. Re-reading a file
- *   on every `tool_call` is a synchronous disk hit on the hot path.
- */
-import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { Value } from "typebox/value";
-import { AGENT_DIR } from "./paths.js";
-/** The user's hook config. Named here so the docs and the check script agree. */
-export const HOOKS_FILE = join(AGENT_DIR, "hooks.json");
-/**
- * A hook config is a payload, not a program. Past this size it is skipped rather
- * than truncated, for the same reason `APPEND_SYSTEM.md` is: half a config is a
- * different config.
- */
-const MAX_BYTES = 64 * 1024;
-/** Claude Code's default. Long enough for a real linter, short enough to not wedge a turn. */
-export const DEFAULT_TIMEOUT_S = 30;
-/** The events this CLI can actually act on. Anything else is reported. */
-export const SUPPORTED_EVENTS = ["PreToolUse", "PostToolUse", "UserPromptSubmit", "SessionStart", "Stop", "PreCompact", "SessionEnd"];
-/**
- * Validate a rewritten tool input against the tool's own schema.
- *
- * The reference is the SDK's own extension runtime: it exposes `typebox/value`
- * as a **virtual module** for extensions (`core/extensions/virtual-modules.js`),
- * and uses it to validate the same tool inputs. Writing a hand-rolled checker
- * instead would be a second, weaker opinion on a question the toolchain already
- * answers — and the failure mode is the worst kind: a rewrite that passes our
- * check and then breaks the tool.
- *
- * `typebox` is a direct dependency of the SDK, and the schema it gives us
- * (`ToolInfo.parameters`) is the very one the provider was handed, so this is
- * the same validation the model's own call goes through.
- *
- * Returns `undefined` when the value is acceptable, or a reason it is not.
- */
-export function checkToolInput(schema, value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        return "the rewrite is not a JSON object";
-    }
-    if (schema === null || typeof schema !== "object")
-        return undefined;
-    try {
-        if (Value.Check(schema, value))
-            return undefined;
-        const first = [...Value.Errors(schema, value)][0];
-        if (!first)
-            return "the rewrite does not match the tool's schema";
-        const at = "instancePath" in first ? String(first.instancePath) : "";
-        const where = at && at !== "/" ? ` at \`${at}\`` : "";
-        return `the rewrite does not match the tool's schema${where}: ${first.message}`;
-    }
-    catch (error) {
-        // A schema TypeBox cannot walk (an exotic tool, a future shape) must not
-        // become a reason to refuse the call: the rewrite is dropped and the tool
-        // runs with its original arguments.
-        return `the tool's schema could not be checked: ${error instanceof Error ? error.message : String(error)}`;
-    }
-}
-/**
- * Read and validate the config. Never throws: a broken config must leave the
- * session working, with a diagnostic saying what was wrong.
- */
-export function loadHooks(path = HOOKS_FILE) {
-    const diagnostics = [];
-    const empty = { hooks: {} };
-    try {
-        if (!existsSync(path))
-            return { config: empty, diagnostics };
-        const raw = readFileSync(path, "utf8");
-        if (Buffer.byteLength(raw, "utf8") > MAX_BYTES) {
-            diagnostics.push({ source: path, message: `skipped: larger than ${MAX_BYTES} bytes` });
-            return { config: empty, diagnostics };
-        }
-        const parsed = JSON.parse(raw);
-        const result = validateHooks(parsed);
-        for (const message of result.diagnostics)
-            diagnostics.push({ source: path, message });
-        return { config: result.config, diagnostics };
-    }
-    catch (error) {
-        diagnostics.push({
-            source: path,
-            message: `unreadable: ${error instanceof Error ? error.message : String(error)}`,
-        });
-        return { config: empty, diagnostics };
-    }
-}
-/**
- * Validate a parsed config. Pure, so the shape rules are testable without a
- * session or a file — including the two that matter most: an unsupported event
- * name is *reported*, and a malformed entry is dropped rather than taking the
- * whole config with it.
- */
-export function validateHooks(parsed) {
-    const diagnostics = [];
-    const config = { hooks: {} };
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        return { config, diagnostics: ["expected a JSON object with a `hooks` key"] };
-    }
-    const hooks = parsed.hooks;
-    if (hooks === undefined)
-        return { config, diagnostics: ["no `hooks` key"] };
-    if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks)) {
-        return { config, diagnostics: ["`hooks` must be an object keyed by event name"] };
-    }
-    for (const [name, value] of Object.entries(hooks)) {
-        if (!SUPPORTED_EVENTS.includes(name)) {
-            diagnostics.push(`unknown event \`${name}\` — supported: ${SUPPORTED_EVENTS.join(", ")}`);
-            continue;
-        }
-        if (!Array.isArray(value)) {
-            diagnostics.push(`\`${name}\` must be an array of matchers`);
-            continue;
-        }
-        const matchers = [];
-        for (const entry of value) {
-            const matcher = validateMatcher(entry, name, diagnostics);
-            if (matcher)
-                matchers.push(matcher);
-        }
-        if (matchers.length)
-            config.hooks[name] = matchers;
-    }
-    return { config, diagnostics };
-}
-function validateMatcher(entry, event, diagnostics) {
-    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
-        diagnostics.push(`\`${event}\`: a matcher must be an object`);
-        return undefined;
-    }
-    const record = entry;
-    const commands = Array.isArray(record.hooks) ? record.hooks : undefined;
-    if (!commands) {
-        diagnostics.push(`\`${event}\`: a matcher needs a \`hooks\` array`);
-        return undefined;
-    }
-    const hooks = [];
-    for (const command of commands) {
-        if (command === null || typeof command !== "object")
-            continue;
-        const c = command;
-        const type = typeof c.type === "string" ? c.type : "command";
-        if (type !== "command") {
-            diagnostics.push(`\`${event}\`: only \`type: "command"\` is supported, got \`${type}\``);
-            continue;
-        }
-        if (typeof c.command !== "string" || !c.command.trim()) {
-            diagnostics.push(`\`${event}\`: a hook needs a non-empty \`command\``);
-            continue;
-        }
-        const timeout = typeof c.timeout === "number" && Number.isFinite(c.timeout) && c.timeout > 0 ? c.timeout : undefined;
-        hooks.push({
-            type: "command",
-            command: c.command,
-            timeout,
-            ...(c.async === true ? { async: true } : {}),
-            ...(c.once === true ? { once: true } : {}),
-        });
-    }
-    if (!hooks.length)
-        return undefined;
-    const matcher = typeof record.matcher === "string" ? record.matcher : undefined;
-    return { matcher, hooks };
-}
-/**
- * Which matchers fire for a tool. `undefined`, `""`, `*` and a `|`-separated
- * list all work, because that is how Claude Code's `matcher` reads and a user
- * arriving from there will write it that way. Case-insensitive: tool names are
- * written `bash` here and `Bash` there.
- */
-export function matchersFor(config, event, toolName) {
-    const matchers = config.hooks[event];
-    if (!matchers)
-        return [];
-    return matchers.filter((matcher) => {
-        const pattern = matcher.matcher?.trim();
-        if (!pattern || pattern === "*")
-            return true;
-        if (toolName === undefined)
-            return false;
-        const name = toolName.toLowerCase();
-        return pattern
-            .split("|")
-            .map((part) => part.trim().toLowerCase())
-            .filter(Boolean)
-            .includes(name);
-    });
-}
-/**
- * Run one hook. Async and bounded: a hook that hangs is killed and reported, so
- * a bad command cannot freeze the session.
- */
-export function runHook(command, payload, options = { cwd: process.cwd() }) {
-    const timeoutS = options.timeoutS ?? DEFAULT_TIMEOUT_S;
-    return new Promise((resolve) => {
-        let stdout = "";
-        let stderr = "";
-        let timedOut = false;
-        let settled = false;
-        const child = spawn(command, {
-            cwd: options.cwd,
-            shell: true,
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        // A hook that exits without reading stdin closes the pipe under us, and the
-        // write then fails **asynchronously** — an unhandled `error` event on the
-        // socket, which takes the whole process down. `exit 0` and `exit 2` are both
-        // normal hooks and both do this, so the handler is not optional. (The
-        // try/catch around the `end()` call below does not catch it: by then the
-        // write has been queued.)
-        child.stdin?.on("error", () => { });
-        child.stdout?.on("error", () => { });
-        child.stderr?.on("error", () => { });
-        const timer = setTimeout(() => {
-            timedOut = true;
-            child.kill("SIGKILL");
-        }, timeoutS * 1000);
-        child.stdout?.on("data", (chunk) => {
-            stdout += chunk.toString("utf8");
-        });
-        child.stderr?.on("data", (chunk) => {
-            stderr += chunk.toString("utf8");
-        });
-        const finish = (code) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            resolve({ code, stdout, stderr, timedOut });
-        };
-        child.on("error", (error) => {
-            stderr += error.message;
-            finish(null);
-        });
-        child.on("close", (code) => finish(code));
-        try {
-            child.stdin?.end(JSON.stringify(payload));
-        }
-        catch {
-            // A hook that closes stdin early is not an error; the exit code decides.
-        }
-    });
-}
-/**
- * Read a hook's answer. Pure, so every branch is testable without spawning.
- *
- * The precedence is the point: an explicit `permissionDecision` beats the exit
- * code, and `exit 2` beats stdout, because a hook that wrote a reason to stderr
- * and exited 2 means it — that is the convention.
- */
-export function interpretHookResult(result) {
-    const { code, stdout, stderr, timedOut } = result;
-    const trimmedErr = stderr.trim();
-    if (timedOut)
-        return { block: false, error: `timed out after ${DEFAULT_TIMEOUT_S}s and was killed` };
-    const parsed = parseJsonObject(stdout);
-    // `additionalContext` is the field Claude Code uses for "here is more context";
-    // it is honoured whatever the exit code, because a hook can both add context
-    // and refuse.
-    const specific = parsed?.hookSpecificOutput;
-    const context = typeof specific?.additionalContext === "string" ? specific.additionalContext : typeof parsed?.additionalContext === "string" ? parsed.additionalContext : undefined;
-    const decision = typeof specific?.permissionDecision === "string" ? specific.permissionDecision : undefined;
-    const decisionReason = typeof specific?.permissionDecisionReason === "string" ? specific.permissionDecisionReason : undefined;
-    // `updatedInput` replaces what the tool will actually do. It is read here and
-    // validated by the caller, which is the only place that has the tool's schema.
-    const rewritten = specific?.updatedInput;
-    const updatedInput = rewritten !== null && typeof rewritten === "object" && !Array.isArray(rewritten) ? rewritten : undefined;
-    if (decision === "deny" || decision === "block") {
-        return { block: true, reason: decisionReason || trimmedErr || "denied by a hook", context };
-    }
-    if (decision === "allow")
-        return { block: false, context, updatedInput };
-    if (code === 2)
-        return { block: true, reason: trimmedErr || "blocked by a hook", context };
-    if (code !== 0) {
-        return {
-            block: false,
-            context,
-            updatedInput,
-            error: `exited ${code === null ? "without a status" : code}${trimmedErr ? `: ${trimmedErr}` : ""}`,
-        };
-    }
-    // Exit 0 with plain text is the simple form: the text is the context.
-    if (!parsed && stdout.trim())
-        return { block: false, context: stdout.trim() };
-    return { block: false, context, updatedInput };
-}
-function parseJsonObject(text) {
-    const trimmed = text.trim();
-    if (!trimmed.startsWith("{"))
-        return undefined;
-    try {
-        const value = JSON.parse(trimmed);
-        if (value && typeof value === "object" && !Array.isArray(value)) {
-            return value;
-        }
-        return undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** Commands already run, for `once`. Session-scoped by design. */
-const firedOnce = new Set();
-/** Reset the `once` ledger. Called when a session starts, so a resumed session re-arms. */
-export function resetOnceHooks() {
-    firedOnce.clear();
-}
-/**
- * Run every matcher for an event and combine the outcomes. A block wins over
- * context and over a rewrite: refusing is the stronger statement, and a hook that
- * said no meant it. Contexts from every hook are kept, in order, so two hooks can
- * each add a piece. A rewrite is last-writer-wins, because two hooks rewriting the
- * same call cannot both be right.
- *
- * `async: true` and `once: true` are handled here rather than at each call site,
- * so no event can forget them. An async hook is started and **not awaited**: it
- * cannot contribute a decision, only a side effect.
- */
-export async function runHooksFor(config, event, payload, options) {
-    const matchers = matchersFor(config, event, payload.tool_name);
-    if (!matchers.length)
-        return { outcome: { block: false }, ran: 0 };
-    const contexts = [];
-    let ran = 0;
-    let block;
-    let error;
-    let updatedInput;
-    for (const matcher of matchers) {
-        for (const hook of matcher.hooks) {
-            if (hook.once) {
-                const key = `${event}\u0000${hook.command}`;
-                if (firedOnce.has(key))
-                    continue;
-                firedOnce.add(key);
-            }
-            ran += 1;
-            if (hook.async) {
-                // Started, never awaited. A rejection is swallowed on purpose: an async
-                // hook has no channel to report on, and an unhandled rejection would take
-                // the process down for a log line.
-                void runHook(hook.command, payload, { cwd: options.cwd, timeoutS: hook.timeout }).catch(() => { });
-                continue;
-            }
-            const result = await runHook(hook.command, payload, {
-                cwd: options.cwd,
-                timeoutS: hook.timeout,
-            });
-            const outcome = interpretHookResult(result);
-            if (outcome.context)
-                contexts.push(outcome.context);
-            if (outcome.error)
-                error = outcome.error;
-            if (outcome.updatedInput)
-                updatedInput = outcome.updatedInput;
-            if (outcome.block && !block)
-                block = outcome;
-        }
-    }
-    if (block) {
-        return {
-            outcome: { block: true, reason: block.reason, context: contexts.join("\n\n") || undefined },
-            ran,
-        };
-    }
-    return {
-        outcome: { block: false, context: contexts.join("\n\n") || undefined, error, updatedInput },
-        ran,
-    };
-}