aiwcli 0.10.1 → 0.10.3

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

@@ -0,0 +1,360 @@
+/**
+ * Common utilities for hook scripts.
+ * Standardized boilerplate for JSON parsing, validation, error handling.
+ * See SPEC.md §5
+ */
+
+import * as fs from "node:fs";
+import { logDebug, logInfo, logWarn, logError, logHookError, logDiagnostic, hookLog, setContextPath, getContextPath as _getContextPath } from "./logger.js";
+import { getProjectRoot } from "./constants.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)
+export { logDebug, logInfo, logWarn, logError, logHookError, logDiagnostic, hookLog, setContextPath };
+
+// 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: string | null = null;
+let _lastToolName: string | null = null;
+
+// Pre-fetched input stash
+let _prefetchedInput: Record<string, any> | null = 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, "utf-8").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,
+): Record<string, any> | null {
+  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.metadata;
+  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.
+ * See SPEC.md §5.5
+ */
+export function emitContext(additionalContext: string): void {
+  const out: HookOutput = {
+    hookSpecificOutput: {
+      additionalContext,
+    },
+  };
+  process.stdout.write(JSON.stringify(out) + "\n");
+}
+
+/**
+ * Emit hookSpecificOutput that denies the tool call with context and reason.
+ * See SPEC.md §5.6
+ */
+export function emitContextAndBlock(
+  additionalContext: string,
+  reason: string,
+): void {
+  const out: HookOutput = {
+    hookSpecificOutput: {
+      additionalContext,
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  };
+  process.stdout.write(JSON.stringify(out) + "\n");
+}
+
+/**
+ * Auto-detect template origin from the hook script path.
+ */
+function detectTemplate(scriptPath = ""): string {
+  const p = (scriptPath || (process.argv[1] ?? "")).replace(/\\/g, "/");
+  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,
+): [number | null, number | null] {
+  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,
+): [number | null, number | null, number | null] {
+  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];
+}
+
+/**
+ * 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 {
+  if (prefetchedInput !== undefined) {
+    _prefetchedInput = prefetchedInput;
+  }
+
+  const startTime = performance.now();
+  const template = detectTemplate();
+  const event = _lastHookEvent ?? "unknown";
+  const tool = _lastToolName;
+
+  // HOOK_START
+  const startData: Record<string, any> = {
+    lifecycle: "start",
+    template,
+    event,
+  };
+  if (tool) startData.tool = tool;
+  logInfo(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 ? "blocked" : "success";
+  } catch (e: any) {
+    if (e instanceof Error && e.message.startsWith("SystemExit:")) {
+      const code = parseInt(e.message.slice(11), 10);
+      exitCode = isNaN(code) ? (e.message.slice(11) ? 1 : 0) : code;
+      status = exitCode !== 0 ? "blocked" : "success";
+    } else {
+      exitCode = 0; // Non-blocking
+      status = "error";
+      const stack = e instanceof Error ? e.stack ?? "" : "";
+      errorInfo = [e instanceof Error ? e : new Error(String(e)), 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 {
+  if (prefetchedInput !== undefined) {
+    _prefetchedInput = prefetchedInput;
+  }
+
+  const startTime = performance.now();
+  const template = detectTemplate();
+  const event = _lastHookEvent ?? "unknown";
+  const tool = _lastToolName;
+
+  // HOOK_START
+  const startData: Record<string, any> = {
+    lifecycle: "start",
+    template,
+    event,
+  };
+  if (tool) startData.tool = tool;
+  logInfo(hookName, "HOOK_START", { data: startData });
+
+  mainFunc()
+    .then((result) => {
+      const exitCode = typeof result === "number" ? result : 0;
+      _emitHookEnd(hookName, startTime, exitCode, exitCode !== 0 ? "blocked" : "success", null, startData, event, tool, template);
+      process.exit(exitCode);
+    })
+    .catch((e: any) => {
+      let exitCode = 0;
+      let status = "error";
+      let errorInfo: [Error, string] | null = null;
+
+      if (e instanceof Error && e.message.startsWith("SystemExit:")) {
+        const code = parseInt(e.message.slice(11), 10);
+        exitCode = isNaN(code) ? (e.message.slice(11) ? 1 : 0) : code;
+        status = exitCode !== 0 ? "blocked" : "success";
+      } else {
+        exitCode = 0; // Non-blocking (fail open)
+        const stack = e instanceof Error ? e.stack ?? "" : "";
+        errorInfo = [e instanceof Error ? e : new Error(String(e)), stack];
+      }
+
+      _emitHookEnd(hookName, startTime, exitCode, status, errorInfo, startData, event, tool, template);
+      process.exit(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: string | null,
+  template: string,
+): void {
+  // Retroactive HOOK_START to per-context log
+  const resolvedAfter = _getContextPath();
+  if (resolvedAfter && fs.existsSync(resolvedAfter)) {
+    hookLog("info", hookName, "HOOK_START", {
+      data: startData,
+      context_path: resolvedAfter,
+      stderr: false,
+    });
+  }
+
+  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;
+    logHookError(hookName, err, endEvent, tb);
+    logError(hookName, `HOOK_END: ${err}`, { data: endData, traceback_str: tb });
+  } else if (status === "blocked") {
+    logWarn(hookName, "HOOK_END", { data: endData });
+  } else {
+    logInfo(hookName, "HOOK_END", { data: endData });
+  }
+}

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

@@ -0,0 +1,245 @@
+/**
+ * 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";
+    let stdout: string;
+
+    // Use execFileSync with shell option on Windows for safe argument passing
+    // (no string interpolation — avoids command injection)
+    stdout = execFileSync(
+      "claude",
+      ["--model", model, "--print", "--setting-sources", "", "-p", fullPrompt],
+      {
+        timeout: timeoutSec * 1000,
+        env,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        shell: isWin, // Windows needs shell for command resolution
+      },
+    );
+
+    const latencyMs = Date.now() - startTime;
+    return {
+      success: true,
+      output: stdout.trim(),
+      latency_ms: latencyMs,
+    };
+  } catch (e: any) {
+    const latencyMs = Date.now() - startTime;
+
+    if (e.code === "ETIMEDOUT" || e.killed) {
+      return {
+        success: false,
+        output: "",
+        error: `Timeout after ${timeoutSec}s`,
+        latency_ms: latencyMs,
+      };
+    }
+
+    if (e.code === "ENOENT") {
+      return {
+        success: false,
+        output: "",
+        error: "claude CLI not found",
+        latency_ms: latencyMs,
+      };
+    }
+
+    // Non-zero exit code
+    if (e.status !== undefined && e.status !== 0) {
+      return {
+        success: false,
+        output: (e.stdout ?? "").toString().trim(),
+        error: (e.stderr ?? "").toString().trim() || `Exit code: ${e.status}`,
+        latency_ms: latencyMs,
+      };
+    }
+
+    return {
+      success: false,
+      output: "",
+      error: String(e),
+      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,
+): string | null {
+  const result = inference(CONTEXT_ID_SYSTEM_PROMPT, prompt, "standard", timeout);
+
+  if (!result.success || !result.output) return null;
+
+  let summary = result.output.trim();
+  summary = summary.replace(/^["']+|["']+$/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,
+): string | null {
+  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: string | null = 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.replace(/^["'`]+|["'`]+$/g, "");
+  slug = slug.replace(/[.!?]+$/, "");
+  slug = slug.replace(/-/g, " ");
+  slug = slug.replace(/[^a-zA-Z0-9 ]/g, "");
+  slug = slug.replace(/\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(" ");
+}