aiwcli 0.15.4 → 0.15.7

package/dist/lib/runtime/inference.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Inference utility for AI-powered text processing.
+ * Unified interface for Claude API calls using the claude CLI.
+ * See SPEC.md §6
+ */
+import type { InferenceResult } from "../types.js";
+/**
+ * Run inference using the claude CLI.
+ * See SPEC.md §6.1
+ */
+export declare function inference(systemPrompt: string, userPrompt: string, level?: string, timeout?: number, options?: {
+    model?: string;
+}): InferenceResult;
+/**
+ * Generate a keyword summary of a user prompt.
+ * Uses Sonnet (standard tier). Returns null if inference fails.
+ * See SPEC.md §6.2
+ */
+export declare function generateSemanticSummary(prompt: string, timeout?: number): string | null;
+/**
+ * Generate a 5-12 word context ID slug from a user prompt.
+ * Uses Codex Spark first, then falls back to current fast tier for resilience.
+ * See SPEC.md §6.3
+ */
+export declare function generateContextIdSlug(prompt: string, timeout?: number): string | null;
+/**
+ * Async version of inference() that does NOT block the event loop.
+ * Use for parallel AI calls (e.g., Stage 3 parallel summarizers).
+ * Uses execFileAsync and getInternalSubprocessEnv for proper subprocess isolation.
+ */
+export declare function inferenceAsync(systemPrompt: string, userPrompt: string, level?: string, timeout?: number, options?: {
+    model?: string;
+}): Promise<InferenceResult>;
+export declare function codexInferAsync(prompt: string, model: string, options?: {
+    sandbox?: string;
+    timeout?: number;
+}): Promise<InferenceResult>;

package/dist/lib/runtime/inference.js

@@ -0,0 +1,262 @@
+/**
+ * Inference utility for AI-powered text processing.
+ * Unified interface for Claude API calls using the claude CLI.
+ * See SPEC.md §6
+ */
+import { execFileSync } from "node:child_process";
+import { logDebug, logWarn } from "./logger.js";
+import { STOP_WORDS } from "./stop-words.js";
+import { buildCliInvocation, inferenceSpec, isModelTier, resolveModel, getTierTimeout, TIER_TIMEOUTS, } from "./cli-args.js";
+import { CODEX_MODELS } from "./models.js";
+import { execFileAsync } from "./subprocess-utils.js";
+const CONTEXT_ID_PRIMARY_MODEL = CODEX_MODELS.spark;
+/**
+ * Run inference using the claude CLI.
+ * See SPEC.md §6.1
+ */
+export function inference(systemPrompt, userPrompt, level = "fast", timeout, options) {
+    const startTime = Date.now();
+    const modelInput = options?.model ?? level;
+    const timeoutSec = timeout ?? (isModelTier(modelInput) ? getTierTimeout(modelInput) : TIER_TIMEOUTS.fast);
+    const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
+    const invocation = buildCliInvocation(inferenceSpec(modelInput));
+    const isWin = invocation.needsShell;
+    // Prompt arg needs Windows quoting when using shell mode
+    let promptArg = fullPrompt;
+    if (isWin) {
+        promptArg = '"' + fullPrompt.replaceAll(/\r?\n/g, " ").replaceAll('"', '""') + '"';
+    }
+    try {
+        const stdout = execFileSync(invocation.cliName, [...invocation.args, promptArg], {
+            timeout: timeoutSec * 1000,
+            env: invocation.env,
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: isWin,
+        });
+        const latencyMs = Date.now() - startTime;
+        return {
+            success: true,
+            output: stdout.trim(),
+            latency_ms: latencyMs,
+        };
+    }
+    catch (error) {
+        const latencyMs = Date.now() - startTime;
+        const execError = error;
+        if (execError.code === "ETIMEDOUT" || execError.killed) {
+            return {
+                success: false,
+                output: "",
+                error: `Timeout after ${timeoutSec}s`,
+                latency_ms: latencyMs,
+            };
+        }
+        if (execError.code === "ENOENT") {
+            return {
+                success: false,
+                output: "",
+                error: "claude CLI not found",
+                latency_ms: latencyMs,
+            };
+        }
+        // Non-zero exit code
+        if (execError.status !== undefined && execError.status !== 0) {
+            return {
+                success: false,
+                output: String(execError.stdout ?? "").trim(),
+                error: String(execError.stderr ?? "").trim() || `Exit code: ${execError.status}`,
+                latency_ms: latencyMs,
+            };
+        }
+        return {
+            success: false,
+            output: "",
+            error: String(error),
+            latency_ms: latencyMs,
+        };
+    }
+}
+// §6.2 — System prompt for keyword extraction
+const CONTEXT_ID_SYSTEM_PROMPT = `Extract 6-12 keywords from what the user wants to do.
+
+Rules:
+- Output 6-12 keywords only
+- Keywords: nouns, verbs, adjectives, technical terms, proper names
+- NO function words: the, to, with, for, in, a, an, of, on, is, it, and, or, that, this, be, as, at, by, from
+- Most important/specific words preferred
+- No punctuation, no quotes
+
+Output ONLY the keywords separated by spaces, nothing else.`;
+/**
+ * Generate a keyword summary of a user prompt.
+ * Uses Sonnet (standard tier). Returns null if inference fails.
+ * See SPEC.md §6.2
+ */
+export function generateSemanticSummary(prompt, timeout = 15) {
+    const result = inference(CONTEXT_ID_SYSTEM_PROMPT, prompt, "standard", timeout);
+    if (!result.success || !result.output)
+        return null;
+    let summary = result.output.trim();
+    summary = summary.replaceAll(/^["']+|["']+$/g, "");
+    summary = summary.replace(/[.!?]+$/, "");
+    // Filter stop words
+    summary = filterStopWords(summary);
+    const words = summary.split(/\s+/);
+    if (words.length < 6 || words.length > 12)
+        return null;
+    return summary;
+}
+// §6.3 — System prompt for context ID slug generation
+const CONTEXT_ID_SLUG_PROMPT = `You generate short title phrases for work sessions. These become folder names like \`260206-1959-fix-auth-middleware-redirect-loop-session-timeout\`.
+
+Users scan 100+ such names to find past sessions. Your title must make THIS session instantly recognizable.
+
+Rules:
+- Exactly 8-12 lowercase words
+- First word is an action verb (fix, add, implement, refactor, update, create, remove, optimize, debug, migrate, integrate, configure, deploy, scaffold, restructure)
+- Coherent phrase, not disjointed keywords — reads like a short task description
+- Prefer specific technical terms over generic words
+- No articles (the, a, an), no pronouns, no filler words, no punctuation, no quotes
+- Input may come from speech-to-text with filler words (uh, um, like, you know, basically, so) — ignore them entirely
+
+Examples:
+
+Input: "um so basically I need to like fix the auth bug in the login page"
+{"slug": "fix authentication bug login page redirect session handling flow"}
+
+Input: "hey uh can we add dark mode to the settings page"
+{"slug": "add dark mode toggle settings page user preference storage"}
+
+Input: "the context ids are bad can we change how we generate them towards a summary"
+{"slug": "improve context id generation use prompt summary slugs"}
+
+Input: "I want to refactor the database connection pooling for PostgreSQL"
+{"slug": "refactor postgresql database connection pooling optimize query performance"}
+
+Input: "so like you know the webhook retry logic is broken and stuff"
+{"slug": "fix webhook retry logic broken error handling recovery mechanism"}
+
+Input: "update the CI pipeline to cache node modules between runs"
+{"slug": "update ci pipeline cache node modules between workflow runs"}
+
+Respond with ONLY a JSON object: {"slug": "your 8-12 word phrase here"}`;
+/**
+ * Generate a 5-12 word context ID slug from a user prompt.
+ * Uses Codex Spark first, then falls back to current fast tier for resilience.
+ * See SPEC.md §6.3
+ */
+export function generateContextIdSlug(prompt, timeout = 3) {
+    const truncated = prompt.slice(0, 500);
+    const sparkResult = inference(CONTEXT_ID_SLUG_PROMPT, truncated, "fast", timeout, { model: CONTEXT_ID_PRIMARY_MODEL });
+    if (!sparkResult.success || !sparkResult.output) {
+        logWarn("inference", `Context ID slug Spark (${CONTEXT_ID_PRIMARY_MODEL}) failed or returned empty output. Falling back to ${resolveModel("fast")}`);
+    }
+    const result = sparkResult.success && sparkResult.output ? sparkResult : inference(CONTEXT_ID_SLUG_PROMPT, truncated, "fast", timeout);
+    if (!result.success || !result.output) {
+        logWarn("inference", `Context ID slug inference failed: ${result.error}`);
+        return null;
+    }
+    const raw = result.output.trim();
+    // Parse JSON response, fall back to raw text
+    let slug = null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && "slug" in parsed) {
+            slug = parsed.slug;
+        }
+    }
+    catch {
+        // Fall through to raw text
+    }
+    if (!slug)
+        slug = raw;
+    // Clean up
+    slug = slug.replaceAll(/^["'`]+|["'`]+$/g, "");
+    slug = slug.replace(/[.!?]+$/, "");
+    slug = slug.replaceAll('-', " ");
+    slug = slug.replaceAll(/[^a-zA-Z0-9 ]/g, "");
+    slug = slug.replaceAll(/\s+/g, " ").trim();
+    const words = slug.split(" ");
+    if (words.length > 12)
+        words.length = 12;
+    if (words.length < 5) {
+        logDebug("inference", `Context ID slug too short (${words.length} words): '${slug}'`);
+        return null;
+    }
+    const resultSlug = words.join(" ");
+    logDebug("inference", `Generated context ID slug: '${resultSlug}' (${result.latency_ms}ms)`);
+    return resultSlug;
+}
+/**
+ * Async version of inference() that does NOT block the event loop.
+ * Use for parallel AI calls (e.g., Stage 3 parallel summarizers).
+ * Uses execFileAsync and getInternalSubprocessEnv for proper subprocess isolation.
+ */
+export async function inferenceAsync(systemPrompt, userPrompt, level = "fast", timeout, options) {
+    const startTime = Date.now();
+    const modelInput = options?.model ?? level;
+    const timeoutSec = timeout ?? (isModelTier(modelInput) ? getTierTimeout(modelInput) : TIER_TIMEOUTS.fast);
+    const timeoutMs = timeoutSec * 1000;
+    const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
+    const invocation = buildCliInvocation(inferenceSpec(modelInput));
+    const isWin = invocation.needsShell;
+    // Prompt arg needs Windows quoting when using shell mode
+    const promptArg = isWin
+        ? ('"' + fullPrompt.replaceAll(/\r?\n/g, " ").replaceAll('"', '""') + '"')
+        : fullPrompt;
+    const result = await execFileAsync(invocation.cliName, [...invocation.args, promptArg], { timeout: timeoutMs, env: invocation.env, shell: isWin });
+    const latencyMs = Date.now() - startTime;
+    if (result.killed) {
+        return { success: false, output: "", error: `Timeout after ${timeoutSec}s`, latency_ms: latencyMs };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            success: false,
+            output: result.stdout.trim(),
+            error: result.stderr.trim() || `Exit code: ${result.exitCode}`,
+            latency_ms: latencyMs,
+        };
+    }
+    return { success: true, output: result.stdout.trim(), latency_ms: latencyMs };
+}
+export async function codexInferAsync(prompt, model, options) {
+    const startTime = Date.now();
+    const args = ["exec", "--model", model, "--json"];
+    if (options?.sandbox) {
+        args.push("--sandbox", options.sandbox);
+    }
+    const result = await execFileAsync("codex", args, {
+        env: process.env,
+        input: prompt,
+        timeout: (options?.timeout ?? 30) * 1000,
+    });
+    const latencyMs = Date.now() - startTime;
+    if (result.killed) {
+        return { success: false, output: "", error: `Timeout after ${options?.timeout ?? 30}s`, latency_ms: latencyMs };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            success: false,
+            output: result.stdout.trim(),
+            error: result.stderr.trim() || `Exit code: ${result.exitCode}`,
+            latency_ms: latencyMs,
+        };
+    }
+    return {
+        success: true,
+        output: result.stdout.trim(),
+        latency_ms: latencyMs,
+    };
+}
+/**
+ * Filter stop words from text.
+ * See SPEC.md §6.4
+ */
+function filterStopWords(text) {
+    return text
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => !STOP_WORDS.has(w) && w.length > 1)
+        .join(" ");
+}

package/dist/lib/runtime/lint-dispatch.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Linter dispatch table and runner for PostToolUse lint-after-edit hook.
+ * Maps file extensions to linter configs, runs linters, parses output.
+ * See root CLAUDE.md for template sync targets.
+ */
+export interface LinterConfig {
+    name: string;
+    extensions: string[];
+    source: "bundled" | "system";
+    binaryName: string;
+    buildArgs: (filePath: string) => string[];
+    parseOutput: (stdout: string, stderr: string, exitCode: number) => LintError[];
+    /** Exit codes that mean "lint errors found" (parse output). Other non-zero = crash (skip). */
+    lintExitCodes: number[];
+}
+export interface LintError {
+    line: number;
+    column?: number;
+    severity: "error" | "warning";
+    message: string;
+    rule?: string;
+}
+/**
+ * Look up the linter config for a file by extension.
+ * Returns null if no linter is configured for this file type.
+ */
+export declare function getLinterForFile(filePath: string): LinterConfig | null;
+/**
+ * Run a linter on a file.
+ * Returns null if the linter binary is not found.
+ * Returns { errors: [] } if the file passes lint.
+ */
+export declare function runLinter(config: LinterConfig, filePath: string, projectRoot: string): {
+    errors: LintError[];
+} | null;
+/**
+ * Format lint errors for Claude's context injection.
+ * Returns a human-readable string suitable for emitContext().
+ */
+export declare function formatLintErrors(filePath: string, linterName: string, errors: LintError[], maxShown?: number): string;

package/dist/lib/runtime/lint-dispatch.js

@@ -0,0 +1,285 @@
+/**
+ * Linter dispatch table and runner for PostToolUse lint-after-edit hook.
+ * Maps file extensions to linter configs, runs linters, parses output.
+ * See root CLAUDE.md for template sync targets.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from "node:fs";
+import path from "node:path";
+import { logDebug, logWarn } from "./logger.js";
+import { findExecutable } from "./subprocess-utils.js";
+// ─── Output Parsers ─────────────────────────────────────────────────────────
+function parseBiomeOutput(stdout, _stderr, _exitCode) {
+    try {
+        const data = JSON.parse(stdout);
+        const diagnostics = data.diagnostics ?? [];
+        return diagnostics.map((d) => ({
+            line: d.location?.span?.start?.line ?? d.location?.sourceCode?.lineIndex ?? 0,
+            column: d.location?.span?.start?.character ?? undefined,
+            severity: d.severity === "error" || d.severity === "fatal" ? "error" : "warning",
+            message: typeof d.description === "string" ? d.description : (d.message ?? "Unknown issue"),
+            ...(d.category ? { rule: d.category } : {}),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function parseRuffOutput(stdout, _stderr, _exitCode) {
+    try {
+        const items = JSON.parse(stdout);
+        return items.map((item) => ({
+            line: item.location?.row ?? 0,
+            column: item.location?.column ?? undefined,
+            severity: "error",
+            message: item.message ?? "Unknown issue",
+            ...(item.code ? { rule: item.code } : {}),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function parseShellcheckOutput(stdout, _stderr, _exitCode) {
+    try {
+        const data = JSON.parse(stdout);
+        const comments = data.comments ?? [];
+        return comments.map((c) => ({
+            line: c.line ?? 0,
+            column: c.column ?? undefined,
+            severity: c.level === "error" ? "error" : "warning",
+            message: c.message ?? "Unknown issue",
+            ...(c.code ? { rule: `SC${c.code}` } : {}),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function parseRubocopOutput(stdout, _stderr, _exitCode) {
+    try {
+        const data = JSON.parse(stdout);
+        const offenses = data.files?.[0]?.offenses ?? [];
+        return offenses.map((o) => ({
+            line: o.location?.line ?? 0,
+            column: o.location?.column ?? undefined,
+            severity: o.severity === "error" || o.severity === "fatal" ? "error" : "warning",
+            message: o.message ?? "Unknown issue",
+            ...(o.cop_name ? { rule: o.cop_name } : {}),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+const CPPCHECK_RE = /^(.+):(\d+):(\d+): (\w+): (.+) \[(.+)\]$/;
+function parseCppcheckOutput(_stdout, stderr, _exitCode) {
+    const errors = [];
+    for (const line of stderr.split("\n")) {
+        const m = CPPCHECK_RE.exec(line.trim());
+        if (m) {
+            errors.push({
+                line: parseInt(m[2], 10),
+                column: parseInt(m[3], 10),
+                severity: m[4] === "error" ? "error" : "warning",
+                message: m[5],
+                ...(m[6] ? { rule: m[6] } : {}),
+            });
+        }
+    }
+    return errors;
+}
+function parseEslintOutput(stdout, _stderr, _exitCode) {
+    try {
+        const files = JSON.parse(stdout);
+        const messages = files[0]?.messages ?? [];
+        return messages.map((m) => ({
+            line: m.line ?? 0,
+            column: m.column ?? undefined,
+            severity: m.severity === 2 ? "error" : "warning",
+            message: m.message ?? "Unknown issue",
+            ...(m.ruleId ? { rule: m.ruleId } : {}),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+const RUSTFMT_DIFF_RE = /^Diff in (.+) at line (\d+)/;
+function parseRustfmtOutput(stdout, _stderr, _exitCode) {
+    const errors = [];
+    for (const line of stdout.split("\n")) {
+        const m = RUSTFMT_DIFF_RE.exec(line.trim());
+        if (m) {
+            errors.push({
+                line: parseInt(m[2], 10),
+                severity: "warning",
+                message: "Formatting differs from rustfmt style",
+                rule: "rustfmt",
+            });
+        }
+    }
+    return errors;
+}
+// ─── Dispatch Table ─────────────────────────────────────────────────────────
+const LINTERS = [
+    {
+        name: "biome",
+        extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ".jsonc", ".css"],
+        source: "bundled",
+        binaryName: "biome",
+        buildArgs: (filePath) => ["lint", "--reporter=json", "--max-diagnostics=20", filePath],
+        parseOutput: parseBiomeOutput,
+        lintExitCodes: [1],
+    },
+    {
+        name: "ruff",
+        extensions: [".py", ".pyi"],
+        source: "system",
+        binaryName: "ruff",
+        buildArgs: (filePath) => ["check", "--no-fix", "--output-format=json", filePath],
+        parseOutput: parseRuffOutput,
+        lintExitCodes: [1],
+    },
+    {
+        name: "shellcheck",
+        extensions: [".sh", ".bash"],
+        source: "system",
+        binaryName: "shellcheck",
+        buildArgs: (filePath) => ["-f", "json1", filePath],
+        parseOutput: parseShellcheckOutput,
+        lintExitCodes: [1],
+    },
+    {
+        name: "rubocop",
+        extensions: [".rb"],
+        source: "system",
+        binaryName: "rubocop",
+        buildArgs: (filePath) => ["--format", "json", "--no-autocorrect", filePath],
+        parseOutput: parseRubocopOutput,
+        lintExitCodes: [1, 2],
+    },
+    {
+        name: "cppcheck",
+        extensions: [".c", ".cpp", ".h", ".hpp"],
+        source: "system",
+        binaryName: "cppcheck",
+        buildArgs: (filePath) => ["--enable=warning,style", "--template=gcc", filePath],
+        parseOutput: parseCppcheckOutput,
+        lintExitCodes: [1],
+    },
+    {
+        name: "eslint",
+        extensions: [".svelte"],
+        source: "system",
+        binaryName: "eslint",
+        buildArgs: (filePath) => ["--format", "json", "--no-fix", filePath],
+        parseOutput: parseEslintOutput,
+        lintExitCodes: [1],
+    },
+    {
+        name: "rustfmt",
+        extensions: [".rs"],
+        source: "system",
+        binaryName: "rustfmt",
+        buildArgs: (filePath) => ["--check", filePath],
+        parseOutput: parseRustfmtOutput,
+        lintExitCodes: [1],
+    },
+];
+/** Extension → LinterConfig lookup map (built once). */
+const EXT_MAP = new Map();
+for (const linter of LINTERS) {
+    for (const ext of linter.extensions) {
+        EXT_MAP.set(ext, linter);
+    }
+}
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Look up the linter config for a file by extension.
+ * Returns null if no linter is configured for this file type.
+ */
+export function getLinterForFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return EXT_MAP.get(ext) ?? null;
+}
+/**
+ * Resolve the binary path for a linter.
+ * Bundled linters: check project node_modules/.bin first, then PATH.
+ * System linters: check PATH only.
+ * Returns null if binary not found.
+ */
+function resolveBinary(config, projectRoot) {
+    if (config.source === "bundled") {
+        // 1. Project-local node_modules
+        const localBin = path.join(projectRoot, "node_modules", ".bin", config.binaryName);
+        if (fs.existsSync(localBin))
+            return localBin;
+        // 2. PATH (covers global npm install of aiwcli)
+        return findExecutable(config.binaryName);
+    }
+    // System linters: PATH only
+    return findExecutable(config.binaryName);
+}
+/**
+ * Run a linter on a file.
+ * Returns null if the linter binary is not found.
+ * Returns { errors: [] } if the file passes lint.
+ */
+export function runLinter(config, filePath, projectRoot) {
+    const binary = resolveBinary(config, projectRoot);
+    if (!binary) {
+        logDebug("lint-dispatch", `${config.name} binary not found, skipping`);
+        return null;
+    }
+    const args = config.buildArgs(filePath);
+    try {
+        const result = spawnSync(binary, args, {
+            cwd: projectRoot,
+            timeout: 8000, // 8s soft limit (10s hook timeout is the hard kill)
+            stdio: 'pipe',
+            encoding: 'utf8',
+        });
+        const exitCode = result.status ?? 1;
+        const stdout = result.stdout ?? "";
+        const stderr = result.stderr ?? "";
+        // Exit 0 = clean
+        if (exitCode === 0)
+            return { errors: [] };
+        // Known lint-error exit codes → parse output
+        if (config.lintExitCodes.includes(exitCode)) {
+            const errors = config.parseOutput(stdout, stderr, exitCode);
+            return { errors };
+        }
+        // Unknown exit code = crash/timeout → skip
+        logWarn("lint-dispatch", `${config.name} exited with unexpected code ${exitCode} on ${filePath}`);
+        return { errors: [] };
+    }
+    catch (error) {
+        logWarn("lint-dispatch", `${config.name} execution failed: ${error}`);
+        return { errors: [] };
+    }
+}
+/**
+ * Format lint errors for Claude's context injection.
+ * Returns a human-readable string suitable for emitContext().
+ */
+export function formatLintErrors(filePath, linterName, errors, maxShown = 15) {
+    const shown = errors.slice(0, maxShown);
+    const lines = [
+        `Lint: ${errors.length} issue(s) in \`${filePath}\` (${linterName})`,
+        "",
+    ];
+    for (const err of shown) {
+        const loc = err.column ? `L${err.line}:${err.column}` : `L${err.line}`;
+        const sev = err.severity === "error" ? "error" : "warn";
+        const rule = err.rule ? ` [${err.rule}]` : "";
+        lines.push(`- **${sev}** ${loc}: ${err.message}${rule}`);
+    }
+    if (errors.length > maxShown) {
+        lines.push(`- ... and ${errors.length - maxShown} more`);
+    }
+    lines.push("");
+    lines.push("Fix these lint errors in the file you just edited.");
+    return lines.join("\n");
+}

package/dist/lib/runtime/logger.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Unified logging for all hooks and libraries.
+ *
+ * Log format: JSONL (one JSON object per line)
+ * Log location: _output/hook-log.jsonl (global, all sessions)
+ * Filter by session using the "sid" field.
+ *
+ * stderr is OPT-IN: convenience functions (logDebug, logInfo, logWarn, logError)
+ * write to file only by default. To also write to stderr (visible to Claude Code
+ * as "hook error"), pass { stderr: true } or use logBlocking().
+ * logHookError() always writes to stderr (unhandled errors must be visible).
+ *
+ * Environment variables:
+ * - HOOK_LOG_DISABLE=1: Disable all file logging
+ * - HOOK_LOG_LEVEL=warn: Minimum level to log (default: debug)
+ * - HOOK_ERROR_LOG_DISABLE=1: Legacy alias for HOOK_LOG_DISABLE
+ *
+ * Never throws. No buffering. Stdlib only.
+ * See SPEC.md §3
+ */
+/**
+ * Set the session ID for this process. All subsequent log calls include it.
+ */
+export declare function setSessionId(sessionId: string | null): void;
+/**
+ * Set the context path for this process. Kept for external callers.
+ */
+export declare function setContextPath(contextPath: string | null): void;
+export declare function getContextPath(): string | null;
+/**
+ * Write a structured log entry to the global hook log.
+ *
+ * All entries go to _output/hook-log.jsonl. Use the "sid" field
+ * (set via setSessionId) to filter by session.
+ */
+export declare function hookLog(level: string, hookName: string, message: string, opts?: {
+    component?: string;
+    data?: unknown;
+    traceback_str?: string;
+    stderr?: boolean;
+}): void;
+export declare function logDebug(hookName: string, message: string, opts?: Record<string, unknown>): void;
+export declare function logInfo(hookName: string, message: string, opts?: Record<string, unknown>): void;
+export declare function logWarn(hookName: string, message: string, opts?: Record<string, unknown>): void;
+export declare function logError(hookName: string, message: string, opts?: Record<string, unknown>): void;
+/**
+ * Log an error that SHOULD be visible to user/model via stderr.
+ * Use for real problems needing attention, not routine diagnostics.
+ */
+export declare function logBlocking(hookName: string, message: string, opts?: Record<string, unknown>): void;
+/**
+ * Log a structured diagnostic entry at a hook decision point.
+ * See SPEC.md §3.8
+ */
+export declare function logDiagnostic(hookName: string, phase: string, summary: string, opts?: {
+    inputs?: unknown;
+    decision?: unknown;
+    reasoning?: unknown;
+    component?: string;
+    data?: unknown;
+}): void;
+/**
+ * Backward-compatible wrapper matching old hook_utils.log_hook_error signature.
+ * See SPEC.md §3.6
+ */
+export declare function logHookError(hookName: string, error: Error | string, hookEvent?: string, tracebackStr?: string): void;