aiwcli 0.10.2 → 0.11.0

package/dist/templates/_shared/lib-ts/base/hook-utils.ts

@@ -0,0 +1,439 @@
+/**
+ * Common utilities for hook scripts.
+ * Standardized boilerplate for JSON parsing, validation, error handling.
+ * See SPEC.md §5
+ */
+
+import * as fs from "node:fs";
+
+import { getProjectRoot } from "./constants.js";
+import { getContextPath as _getContextPath, hookLog, logDebug, setSessionId } from "./logger.js";
+import { getContextBySessionId } from "../context/context-store.js";
+import type { HookInput, HookOutput } from "../types.js";
+
+// Re-export logger functions for convenience (matches Python hook_utils re-exports)
+
+
+// Context window baseline: tokens not visible in hook data §5.9
+export const CONTEXT_BASELINE_TOKENS = 22_600;
+export const DEFAULT_CONTEXT_WINDOW_SIZE = 200_000;
+
+// Event metadata stash — populated by loadHookInput(), read by runHook()
+let _lastHookEvent: null | string = null;
+let _lastToolName: null | string = null;
+let _cachedHookName: null | string = null;
+
+// Pre-fetched input stash
+let _prefetchedInput: null | Record<string, any> = null;
+
+/**
+ * Load and parse JSON from stdin (or return prefetched input if set).
+ * Returns null if stdin is empty or invalid JSON.
+ * See SPEC.md §5.1
+ */
+export function loadHookInput(): HookInput | null {
+  if (_prefetchedInput !== null) {
+    const result = _prefetchedInput;
+    _prefetchedInput = null; // consume once
+    if (result && typeof result === "object") {
+      _lastHookEvent = result.hook_event_name ?? null;
+      _lastToolName = result.tool_name ?? null;
+    }
+
+    return result as HookInput;
+  }
+
+  try {
+    // Read entire stdin using fd 0 (cross-platform, works on Windows)
+    const inputData = fs.readFileSync(0, "utf8").trim();
+    if (!inputData) return null;
+
+    const result = JSON.parse(inputData);
+    if (result && typeof result === "object") {
+      _lastHookEvent = result.hook_event_name ?? null;
+      _lastToolName = result.tool_name ?? null;
+    }
+
+    return result as HookInput;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate hook event type and optional tool name.
+ * See SPEC.md §5.2
+ */
+export function validateHookEvent(
+  payload: HookInput,
+  expectedEvent: string,
+  expectedTool?: string,
+): boolean {
+  if (payload.hook_event_name !== expectedEvent) return false;
+  if (expectedTool && payload.tool_name !== expectedTool) return false;
+  return true;
+}
+
+/**
+ * Extract and validate tool_input from payload.
+ * See SPEC.md §5.3
+ */
+export function getToolInput(
+  payload: HookInput,
+): null | Record<string, any> {
+  const toolInput = payload.tool_input;
+  return toolInput && typeof toolInput === "object" ? toolInput : null;
+}
+
+/**
+ * Check if persistence should be skipped based on metadata flags.
+ * See SPEC.md §5.4
+ */
+export function checkSkipPersistence(
+  payload: HookInput,
+  hookName = "hook",
+): boolean {
+  const toolInput = getToolInput(payload);
+  if (!toolInput) return false;
+
+  const {metadata} = toolInput;
+  if (metadata && typeof metadata === "object" && metadata.skip_persistence) {
+    logDebug(hookName, "Skipping persistence (skip_persistence flag set)");
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Emit hookSpecificOutput with additionalContext to stdout.
+ * hookEventName is required by Claude Code's Zod validator (discriminated union).
+ * Auto-detected from stdin payload (set by loadHookInput/runHook).
+ * See SPEC.md §5.5
+ */
+export function emitContext(additionalContext: string): void {
+  const eventName = _lastHookEvent ?? undefined;
+  const out: HookOutput = {
+    hookSpecificOutput: {
+      ...(eventName ? { hookEventName: eventName } : {}),
+      additionalContext,
+    },
+  };
+  const json = JSON.stringify(out);
+  _logEmit("context", additionalContext.length, { additionalContext });
+  process.stdout.write(json + "\n");
+}
+
+/**
+ * Emit hookSpecificOutput that denies the tool call with context and reason.
+ * hookEventName is required by Claude Code's Zod validator (discriminated union).
+ * Auto-detected from stdin payload (set by loadHookInput/runHook).
+ * See SPEC.md §5.6
+ */
+export function emitContextAndBlock(
+  additionalContext: string,
+  reason: string,
+): void {
+  const eventName = _lastHookEvent ?? undefined;
+  const out: HookOutput = {
+    hookSpecificOutput: {
+      ...(eventName ? { hookEventName: eventName } : {}),
+      additionalContext,
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  };
+  const json = JSON.stringify(out);
+  _logEmit("block", additionalContext.length, { additionalContext, blockReason: reason });
+  process.stdout.write(json + "\n");
+}
+
+/** Log hook output (context or block) to hook-log.jsonl for visibility. */
+function _logEmit(type: "block" | "context", chars: number, payload: Record<string, any>): void {
+  const hook = _cachedHookName ?? "unknown";
+  const msg = type === "block"
+    ? `HOOK_OUTPUT [${type}] ${chars} chars, reason="${(payload.blockReason ?? "").slice(0, 80)}"`
+    : `HOOK_OUTPUT [${type}] ${chars} chars`;
+  hookLog("info", hook, msg, { data: payload });
+}
+
+/**
+ * Auto-detect template origin from the hook script path.
+ */
+function detectTemplate(scriptPath = ""): string {
+  const p = (scriptPath || (process.argv[1] ?? "")).replaceAll('\\', "/");
+  if (p.includes("/_shared/hooks/") || p.startsWith("_shared/hooks/")) {
+    return "shared";
+  }
+
+  const match = p.match(/_([a-z][a-z0-9-]*)\/hooks\//);
+  if (match?.[1]) return match[1]; // e.g., "cc-native"
+  return "unknown";
+}
+
+/**
+ * Parse context window from hook input.
+ * Returns [tokensUsed, maxTokens] or [null, null].
+ * See SPEC.md §5.9
+ */
+export function parseContextWindow(
+  hookInput: HookInput,
+): [null | number, null | number] {
+  const contextWindow = hookInput.context_window;
+  if (!contextWindow) return [null, null];
+
+  const currentUsage = contextWindow.current_usage;
+  if (!currentUsage) return [null, null];
+
+  const cacheRead = currentUsage.cache_read_input_tokens ?? 0;
+  const inputTokens = currentUsage.input_tokens ?? 0;
+  const cacheCreation = currentUsage.cache_creation_input_tokens ?? 0;
+  const outputTokens = currentUsage.output_tokens ?? 0;
+
+  const contentTokens = cacheRead + inputTokens + cacheCreation + outputTokens;
+  const tokensUsed = contentTokens + CONTEXT_BASELINE_TOKENS;
+  const maxTokens = contextWindow.context_window_size ?? DEFAULT_CONTEXT_WINDOW_SIZE;
+
+  return [tokensUsed, maxTokens];
+}
+
+/**
+ * Get context percentage remaining with fallback.
+ * Returns [percentRemaining, tokensUsed, maxTokens] or [null, null, null].
+ * See SPEC.md §5.9
+ */
+export function getContextPercentRemaining(
+  hookInput: HookInput,
+): [null | number, null | number, null | number] {
+  const [tokensUsed, maxTokens] = parseContextWindow(hookInput);
+
+  if (tokensUsed !== null && maxTokens !== null && maxTokens > 0) {
+    const remaining = maxTokens - tokensUsed;
+    const percentRemaining = Math.max(
+      0,
+      Math.min(100, Math.round((remaining / maxTokens) * 100)),
+    );
+    return [percentRemaining, tokensUsed, maxTokens];
+  }
+
+  // Source 2: context.json fallback (written by status_line.py)
+  try {
+    const sessionId = hookInput.session_id;
+    if (sessionId) {
+      const projectRoot = getProjectRoot(hookInput.cwd);
+      const context = getContextBySessionId(sessionId, projectRoot);
+      if (context?.last_session?.context_remaining_pct !== undefined) {
+        return [context.last_session.context_remaining_pct, null, null];
+      }
+    }
+  } catch {
+    // Fallback failed — degrade gracefully
+  }
+
+  return [null, null, null];
+}
+
+/**
+ * Read stdin early and extract session_id + event metadata.
+ * Stashes parsed input for loadHookInput() to consume later.
+ */
+function _earlyReadInput(prefetchedInput?: Record<string, any>): void {
+  if (prefetchedInput !== undefined) {
+    _prefetchedInput = prefetchedInput;
+  }
+
+  // If we already have prefetched input, extract metadata from it
+  if (_prefetchedInput && typeof _prefetchedInput === "object") {
+    _lastHookEvent = _prefetchedInput.hook_event_name ?? null;
+    _lastToolName = _prefetchedInput.tool_name ?? null;
+    if (_prefetchedInput.session_id) {
+      setSessionId(_prefetchedInput.session_id);
+    }
+
+    return;
+  }
+
+  // Read stdin now so HOOK_START can include sid
+  try {
+    const inputData = fs.readFileSync(0, "utf8").trim();
+    if (inputData) {
+      const parsed = JSON.parse(inputData);
+      if (parsed && typeof parsed === "object") {
+        _prefetchedInput = parsed;
+        _lastHookEvent = parsed.hook_event_name ?? null;
+        _lastToolName = parsed.tool_name ?? null;
+        if (parsed.session_id) {
+          setSessionId(parsed.session_id);
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — loadHookInput will return null
+  }
+}
+
+/**
+ * Standard hook entry point with lifecycle logging.
+ * See SPEC.md §5.7
+ */
+export function runHook(
+  mainFunc: () => number | void,
+  hookName = "unknown",
+  prefetchedInput?: Record<string, any>,
+): never {
+  _earlyReadInput(prefetchedInput);
+  _cachedHookName = hookName;
+
+  const startTime = performance.now();
+  const template = detectTemplate();
+  const event = _lastHookEvent ?? "unknown";
+  const tool = _lastToolName;
+
+  const startData: Record<string, any> = {
+    lifecycle: "start",
+    template,
+    event,
+  };
+  if (tool) startData.tool = tool;
+  hookLog("info", hookName, "HOOK_START", { data: startData });
+
+  let exitCode = 0;
+  let status = "success";
+  let errorInfo: [Error, string] | null = null;
+
+  try {
+    const result = mainFunc();
+    exitCode = typeof result === "number" ? result : 0;
+    status = exitCode === 0 ? "success" : "blocked";
+  } catch (error: any) {
+    if (error instanceof Error && error.message.startsWith("SystemExit:")) {
+      const code = parseInt(error.message.slice(11), 10);
+      exitCode = isNaN(code) ? (error.message.slice(11) ? 1 : 0) : code;
+      status = exitCode !== 0 ? "blocked" : "success";
+    } else {
+      exitCode = 0; // Non-blocking
+      status = "error";
+      const stack = error instanceof Error ? error.stack ?? "" : "";
+      errorInfo = [error instanceof Error ? error : new Error(String(error)), stack];
+    }
+  }
+
+  _emitHookEnd(hookName, startTime, exitCode, status, errorInfo, startData, event, tool, template);
+  process.exit(exitCode);
+}
+
+/**
+ * Async variant of runHook for hooks that need await (e.g., AI inference).
+ * Provides identical structured JSONL lifecycle logging as runHook.
+ * See SPEC.md §5.7
+ */
+export function runHookAsync(
+  mainFunc: () => Promise<number | void>,
+  hookName = "unknown",
+  prefetchedInput?: Record<string, any>,
+): void {
+  _earlyReadInput(prefetchedInput);
+  _cachedHookName = hookName;
+
+  const startTime = performance.now();
+  const template = detectTemplate();
+  const event = _lastHookEvent ?? "unknown";
+  const tool = _lastToolName;
+
+  const startData: Record<string, any> = {
+    lifecycle: "start",
+    template,
+    event,
+  };
+  if (tool) startData.tool = tool;
+  hookLog("info", hookName, "HOOK_START", { data: startData });
+
+  mainFunc()
+    .then((result) => {
+      const exitCode = typeof result === "number" ? result : 0;
+      _emitHookEnd(hookName, startTime, exitCode, exitCode === 0 ? "success" : "blocked", null, startData, event, tool, template);
+      _drainAndExit(exitCode);
+    })
+    .catch((error: any) => {
+      let exitCode = 0;
+      let status = "error";
+      let errorInfo: [Error, string] | null = null;
+
+      if (error instanceof Error && error.message.startsWith("SystemExit:")) {
+        const code = parseInt(error.message.slice(11), 10);
+        exitCode = isNaN(code) ? (error.message.slice(11) ? 1 : 0) : code;
+        status = exitCode !== 0 ? "blocked" : "success";
+      } else {
+        exitCode = 0; // Non-blocking (fail open)
+        const stack = error instanceof Error ? error.stack ?? "" : "";
+        errorInfo = [error instanceof Error ? error : new Error(String(error)), stack];
+      }
+
+      _emitHookEnd(hookName, startTime, exitCode, status, errorInfo, startData, event, tool, template);
+      _drainAndExit(exitCode);
+    });
+}
+
+/** Shared HOOK_END logic for runHook and runHookAsync */
+function _emitHookEnd(
+  hookName: string,
+  startTime: number,
+  exitCode: number,
+  status: string,
+  errorInfo: [Error, string] | null,
+  startData: Record<string, any>,
+  event: string,
+  tool: null | string,
+  template: string,
+): void {
+  // Retroactive HOOK_START to per-context log (context_path resolved after main runs)
+  const resolvedAfter = _getContextPath();
+  if (resolvedAfter && fs.existsSync(resolvedAfter)) {
+    hookLog("info", hookName, "HOOK_START", { data: startData });
+  }
+
+  const durationMs = Math.round((performance.now() - startTime) * 10) / 10;
+  const endEvent = _lastHookEvent ?? event;
+  const endTool = _lastToolName ?? tool;
+  const endData: Record<string, any> = {
+    lifecycle: "end",
+    status,
+    duration_ms: durationMs,
+    exit_code: exitCode,
+    template,
+    event: endEvent,
+  };
+  if (endTool) endData.tool = endTool;
+
+  if (errorInfo) {
+    const [err, tb] = errorInfo;
+    endData.error_type = err.constructor.name;
+    hookLog("error", hookName, `[${endEvent}] ${err.constructor.name}: ${String(err).replaceAll(/[\n\r]/g, " ").slice(0, 200)}`, { traceback_str: tb });
+    hookLog("error", hookName, `HOOK_END: ${err}`, { data: endData, traceback_str: tb });
+  } else if (status === "blocked") {
+    hookLog("warn", hookName, "HOOK_END", { data: endData });
+  } else {
+    hookLog("info", hookName, "HOOK_END", { data: endData });
+  }
+}
+
+/**
+ * Drain stdout before exiting to ensure pipe consumers receive all data.
+ * On Windows, stdout to a pipe is fully buffered — process.exit() can
+ * discard unflushed data. This waits for the write buffer to drain.
+ */
+function _drainAndExit(code: number): void {
+  // If stdout is already finished or not writable, exit immediately
+  if (!process.stdout.writable || process.stdout.writableFinished) {
+    process.exit(code);
+  }
+
+  // Attempt to end stdout and wait for drain
+  const timeout = setTimeout(() => process.exit(code), 1000); // safety fallback
+  process.stdout.end(() => {
+    clearTimeout(timeout);
+    process.exit(code);
+  });
+}
+
+export {hookLog, logBlocking, logDebug, logDiagnostic, logError, logHookError, logInfo, logWarn, setContextPath, setSessionId} from "./logger.js";

package/dist/templates/_shared/lib-ts/base/inference.ts

@@ -0,0 +1,252 @@
+/**
+ * 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 { cleanTextForSlug } from "./utils.js";
+import type { InferenceResult } from "../types.js";
+
+// Model configurations §6.1
+const MODELS: Record<string, string> = {
+  fast: "claude-3-haiku-20240307",
+  standard: "claude-sonnet-4-20250514",
+  smart: "claude-opus-4-20250514",
+};
+
+const TIMEOUTS: Record<string, number> = {
+  fast: 15,
+  standard: 30,
+  smart: 90,
+};
+
+/**
+ * Run inference using the claude CLI.
+ * See SPEC.md §6.1
+ */
+export function inference(
+  systemPrompt: string,
+  userPrompt: string,
+  level = "fast",
+  timeout?: number,
+): InferenceResult {
+  const startTime = Date.now();
+  const model = MODELS[level] ?? MODELS["fast"] ?? "claude-3-haiku-20240307";
+  const timeoutSec = timeout ?? TIMEOUTS[level] ?? 15;
+  const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
+
+  // Remove ANTHROPIC_API_KEY to force subscription auth
+  const env = { ...process.env };
+  delete env.ANTHROPIC_API_KEY;
+
+  try {
+    const isWin = process.platform === "win32";
+    // On Windows with shell:true, Node.js sets windowsVerbatimArguments —
+    // args are joined with spaces, NOT individually quoted. We must manually
+    // wrap multi-word/special-char args in "..." for cmd.exe parsing.
+    // Inside double quotes: "" = literal ", and |&<> are safe.
+    const empty = isWin ? '""' : "";
+    let promptArg = fullPrompt;
+    if (isWin) {
+      promptArg = '"' + fullPrompt.replaceAll(/\r?\n/g, " ").replaceAll('"', '""') + '"';
+    }
+
+    const stdout = execFileSync(
+      "claude",
+      ["--model", model, "--print", "--setting-sources", empty, "-p", promptArg],
+      {
+        timeout: timeoutSec * 1000,
+        env,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        shell: isWin, // Windows needs shell for .cmd resolution
+      },
+    );
+
+    const latencyMs = Date.now() - startTime;
+    return {
+      success: true,
+      output: stdout.trim(),
+      latency_ms: latencyMs,
+    };
+  } catch (error: any) {
+    const latencyMs = Date.now() - startTime;
+
+    if (error.code === "ETIMEDOUT" || error.killed) {
+      return {
+        success: false,
+        output: "",
+        error: `Timeout after ${timeoutSec}s`,
+        latency_ms: latencyMs,
+      };
+    }
+
+    if (error.code === "ENOENT") {
+      return {
+        success: false,
+        output: "",
+        error: "claude CLI not found",
+        latency_ms: latencyMs,
+      };
+    }
+
+    // Non-zero exit code
+    if (error.status !== undefined && error.status !== 0) {
+      return {
+        success: false,
+        output: (error.stdout ?? "").toString().trim(),
+        error: (error.stderr ?? "").toString().trim() || `Exit code: ${error.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: string,
+  timeout = 15,
+): null | string {
+  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 Haiku (fast tier) for low latency.
+ * See SPEC.md §6.3
+ */
+export function generateContextIdSlug(
+  prompt: string,
+  timeout = 3,
+): null | string {
+  const truncated = prompt.slice(0, 500);
+
+  const result = 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 | string = 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;
+}
+
+/**
+ * Filter stop words from text.
+ * See SPEC.md §6.4
+ */
+function filterStopWords(text: string): string {
+  const cleaned = cleanTextForSlug(text);
+  return cleaned
+    .split(/\s+/)
+    .filter((w) => !STOP_WORDS.has(w) && w.length > 1)
+    .join(" ");
+}