aiwcli 0.10.2 → 0.11.0

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

@@ -0,0 +1,250 @@
+/**
+ * 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
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const LEVELS: Record<string, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const MAX_LOG_LINES = 10_000; // Max lines in global log before pruning
+
+// Module-level session ID cache
+let _cachedSessionId: null | string = null;
+
+// Module-level context path cache (kept for external callers)
+let _cachedContextPath: null | string = null;
+let _contextResolved = false;
+
+/**
+ * Set the session ID for this process. All subsequent log calls include it.
+ */
+export function setSessionId(sessionId: null | string): void {
+  _cachedSessionId = sessionId;
+}
+
+/**
+ * Set the context path for this process. Kept for external callers.
+ */
+export function setContextPath(contextPath: null | string): void {
+  _cachedContextPath = contextPath;
+  _contextResolved = true;
+}
+
+export function getContextPath(): null | string {
+  if (!_contextResolved) {
+    _contextResolved = true; // Don't retry
+  }
+
+  return _cachedContextPath;
+}
+
+function getMinLevel(): number {
+  const env = (process.env.HOOK_LOG_LEVEL ?? "debug").toLowerCase();
+  return LEVELS[env] ?? 0;
+}
+
+function isDisabled(): boolean {
+  return (
+    process.env.HOOK_LOG_DISABLE === "1" ||
+    process.env.HOOK_ERROR_LOG_DISABLE === "1" ||
+    process.env.CCNATIVE_DEBUG_DISABLE === "1"
+  );
+}
+
+function getProjectRoot(): string {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * 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 function hookLog(
+  level: string,
+  hookName: string,
+  message: string,
+  opts?: {
+    component?: string;
+    data?: any;
+    stderr?: boolean;
+    traceback_str?: string;
+  },
+): void {
+  try {
+    const levelLower = level.toLowerCase();
+    const levelNum = LEVELS[levelLower] ?? 0;
+    const component = opts?.component ?? "";
+    const tracebackStr = opts?.traceback_str ?? "";
+    const stderrEnabled = opts?.stderr === true;
+
+    // Write to stderr
+    if (stderrEnabled) {
+      const prefix = component
+        ? `[${hookName}:${component}]`
+        : `[${hookName}]`;
+      process.stderr.write(`${prefix} ${message}\n`);
+      if (tracebackStr) {
+        process.stderr.write(tracebackStr + "\n");
+      }
+    }
+
+    // Check if file logging is enabled
+    if (isDisabled()) return;
+
+    // Check minimum level
+    if (levelNum < getMinLevel()) return;
+
+    // Build JSONL entry
+    const now = new Date();
+    const ts = now.toISOString().replace("Z", "").slice(0, 23);
+    const entry: Record<string, any> = {
+      ts,
+      level: levelLower,
+      hook: hookName,
+      msg: message,
+    };
+    if (_cachedSessionId) entry.sid = _cachedSessionId;
+    if (component) entry.component = component;
+    if (opts?.data !== undefined && opts.data !== null) {
+      try {
+        JSON.stringify(opts.data);
+        entry.data = opts.data;
+      } catch {
+        entry.data = String(opts.data);
+      }
+    }
+
+    if (tracebackStr) entry.tb = tracebackStr.trimEnd();
+
+    const line = JSON.stringify(entry) + "\n";
+
+    // Always write to global log
+    const logPath = path.join(getProjectRoot(), "_output", "hook-log.jsonl");
+
+    // Ensure directory exists
+    const dir = path.dirname(logPath);
+    fs.mkdirSync(dir, { recursive: true });
+
+    // Line-count guard: prune to last MAX_LOG_LINES
+    try {
+      if (fs.existsSync(logPath)) {
+        const content = fs.readFileSync(logPath, "utf8");
+        const lines = content.split("\n");
+        if (lines.length > MAX_LOG_LINES) {
+          fs.writeFileSync(
+            logPath,
+            lines.slice(lines.length - MAX_LOG_LINES).join("\n"),
+            "utf-8",
+          );
+        }
+      }
+    } catch {
+      // ignore
+    }
+
+    fs.appendFileSync(logPath, line, "utf-8");
+  } catch {
+    // Never crash
+  }
+}
+
+export function logDebug(hookName: string, message: string, opts?: Record<string, any>): void {
+  hookLog("debug", hookName, message, opts);
+}
+
+export function logInfo(hookName: string, message: string, opts?: Record<string, any>): void {
+  hookLog("info", hookName, message, opts);
+}
+
+export function logWarn(hookName: string, message: string, opts?: Record<string, any>): void {
+  hookLog("warn", hookName, message, opts);
+}
+
+export function logError(hookName: string, message: string, opts?: Record<string, any>): void {
+  hookLog("error", hookName, message, opts);
+}
+
+/**
+ * Log an error that SHOULD be visible to user/model via stderr.
+ * Use for real problems needing attention, not routine diagnostics.
+ */
+export function logBlocking(hookName: string, message: string, opts?: Record<string, any>): void {
+  hookLog("error", hookName, message, { ...opts, stderr: true });
+}
+
+/**
+ * Log a structured diagnostic entry at a hook decision point.
+ * See SPEC.md §3.8
+ */
+export function logDiagnostic(
+  hookName: string,
+  phase: string,
+  summary: string,
+  opts?: {
+    component?: string;
+    data?: any;
+    decision?: any;
+    inputs?: any;
+    reasoning?: any;
+  },
+): void {
+  const diagData: Record<string, any> = { phase };
+  if (opts?.inputs !== undefined) diagData.inputs = opts.inputs;
+  if (opts?.decision !== undefined) diagData.decision = opts.decision;
+  if (opts?.reasoning !== undefined) diagData.reasoning = opts.reasoning;
+  if (opts?.data && typeof opts.data === "object") {
+    Object.assign(diagData, opts.data);
+  }
+
+  hookLog("debug", hookName, `[DIAG:${phase}] ${summary}`, {
+    component: opts?.component ?? "diag",
+    data: diagData,
+  });
+}
+
+/**
+ * Backward-compatible wrapper matching old hook_utils.log_hook_error signature.
+ * See SPEC.md §3.6
+ */
+export function logHookError(
+  hookName: string,
+  error: Error | string,
+  hookEvent = "unknown",
+  tracebackStr = "",
+): void {
+  const errStr = typeof error === "string" ? error : String(error);
+  const msg = errStr.replaceAll(/[\n\r]/g, " ").slice(0, 200);
+  const errType =
+    typeof error === "object" && error !== null
+      ? error.constructor.name
+      : "Error";
+  hookLog("error", hookName, `[${hookEvent}] ${errType}: ${msg}`, {
+    traceback_str: tracebackStr,
+    stderr: true,
+  });
+}

package/dist/templates/_shared/lib-ts/base/state-io.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared I/O for state.json — read, write, serialize.
+ * Extracted to avoid circular deps between context-store and task-tracker.
+ * See SPEC.md §7.1
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { atomicWrite } from "./atomic-write.js";
+import { getContextDir } from "./constants.js";
+import { logWarn } from "./logger.js";
+import type { ContextState, Mode } from "../types.js";
+
+/** Mode migration from legacy context_manager values. */
+const MODE_MIGRATION: Record<string, Mode> = {
+  none: "idle",
+  planning: "idle",
+  pending_implementation: "has_plan",
+  implementing: "active",
+};
+
+/**
+ * Serialize a ContextState for JSON output.
+ * Omits null/undefined keys but keeps false, 0, empty string, and empty arrays.
+ */
+export function toDict(state: ContextState): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(state)) {
+    if (value !== null && value !== undefined) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get path to state.json for a context.
+ */
+export function statePath(contextId: string, projectRoot?: string): string {
+  return path.join(getContextDir(contextId, projectRoot), "state.json");
+}
+
+/**
+ * Read and parse state.json for a context.
+ * Applies legacy mode migration. Returns null if file doesn't exist or is corrupt.
+ */
+export function readStateJson(
+  contextId: string,
+  projectRoot?: string,
+): ContextState | null {
+  const sp = statePath(contextId, projectRoot);
+  if (!fs.existsSync(sp)) return null;
+
+  try {
+    const raw = fs.readFileSync(sp, "utf8");
+    const data = JSON.parse(raw) as Record<string, any>;
+    return dictToState(data);
+  } catch (error: any) {
+    logWarn("state_io", `Failed to read state.json for '${contextId}': ${error}`);
+    return null;
+  }
+}
+
+/**
+ * Atomically write state.json for a context.
+ * Returns [success, error].
+ */
+export function writeStateJson(
+  contextId: string,
+  state: ContextState,
+  projectRoot?: string,
+): [boolean, null | string] {
+  const sp = statePath(contextId, projectRoot);
+  const dir = path.dirname(sp);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const content = JSON.stringify(toDict(state), null, 2);
+  return atomicWrite(sp, content);
+}
+
+/**
+ * Construct a ContextState from a dict, migrating old mode names.
+ * Only includes fields that are present in the source data (preserves null-stripping).
+ */
+export function dictToState(data: Record<string, any>): ContextState {
+  const rawMode: string = data.mode ?? "idle";
+  const mode: Mode = (MODE_MIGRATION[rawMode] ?? rawMode) as Mode;
+
+  const state: any = {
+    id: data.id,
+    status: data.status ?? "active",
+    summary: data.summary ?? "",
+    method: data.method ?? "",
+    tags: data.tags ?? [],
+    created_at: data.created_at ?? "",
+    last_active: data.last_active ?? "",
+    mode,
+    plan_anchors: data.plan_anchors ?? [],
+    plan_consumed: data.plan_consumed ?? false,
+    handoff_consumed: data.handoff_consumed ?? false,
+    session_ids: data.session_ids ?? [],
+    tasks: data.tasks ?? [],
+  };
+
+  // Only set nullable fields if they exist in the source data
+  if ("plan_path" in data) state.plan_path = data.plan_path;
+  if ("plan_hash" in data) state.plan_hash = data.plan_hash;
+  if ("plan_signature" in data) state.plan_signature = data.plan_signature;
+  if ("plan_id" in data) state.plan_id = data.plan_id;
+  if ("handoff_path" in data) state.handoff_path = data.handoff_path;
+  if ("last_session" in data) state.last_session = data.last_session;
+
+  return state as ContextState;
+}

package/dist/templates/_shared/lib-ts/base/stop-words.ts

@@ -0,0 +1,184 @@
+/**
+ * Stop words for context ID generation.
+ *
+ * Generated from analysis of 1,424 prompts, context summaries, and plan files.
+ * Words that appear frequently but don't help identify the specific task.
+ *
+ * ACTION VERBS ARE INTENTIONALLY EXCLUDED:
+ * add, fix, update, create, implement, refactor, migrate, debug, remove, change,
+ * move, rename, delete, build, test, deploy, verify, analyze, modify, write, run,
+ * check, replace, save, sync, load, extract, install, clean, merge, etc.
+ *
+ * See SPEC.md §14.1
+ */
+
+export const STOP_WORDS: ReadonlySet<string> = new Set([
+  // ARTICLES
+  "a", "about", "above",
+
+  "absolutely", "accordingly", "across", "active", "actually", "after", "afterwards", "against", "ago", "ah",
+  "aiw", "all", "allow", "almost", "along", "already", "alright", "also",
+  "alternatively", "although", "always", // AUXILIARY/MODAL VERBS
+  "am", "among", "an", // CONJUNCTIONS
+  "and", "another",
+  "any", "anybody", "anyone", "anything", "anyway", "anyways", "apparently", "appear",
+  "are", "aren", "arent", "args", "around", "as", "ask",
+  "assert", "async", "at", // SINGLE LETTERS
+  "b",
+
+  "based", "basic", "basically", "bat", "be", "because", "become",
+  "been", "before", "begin", "behind", "being",
+  "below", "below", "beside", "besides", "between", "beyond", "block",
+
+  "both", "but", "by", "c", "can", "cant", "case",
+  "cases", "cause", "cc", "certainly", "chunk",
+
+  "clarification", "class", "clearly", "come",
+
+  "complete", "completely", "consequently", "consider",
+
+  "const", "contain", "contains", "continue", "conversely", "correct",
+  "correctly", "could", "couldn", "couldnt", "critical", "current",
+  "currently", "d",
+
+  "def", "definitely", "dict", "did", "didn", "didnt", "different", "directory",
+  "do", "does", "doesn", "doesn",
+  "doesnt", "doing", "don", "done", "dont",
+  "down", "during", "e", "each", "eh", "eight", "either", "elif", "else",
+
+  "empty", "end", "enough", "entirely", "eprint", "er",
+  "essentially", // SHORT NOISE
+  "etc", "eventually", "every", "everybody", "everyone", "everything",
+  "exactly", "example", "examples", "except", "exe",
+
+  "existing", "expect", "expected", "f", "false",
+
+  "feature", "features", "feel", "few", "finally", "find", "first",
+  "five", "folder", "follow", "following", "footer", "for", "format",
+  "four", "from", "full", "furthermore", "g",
+  "general", "get", "getting", "give",
+
+  // COMMON NON-ACTION VERBS
+  "go", "going", "gonna", "gotta",
+  "group", "h", "had", "hadn", "hadnt", "has", "hasn",
+  "hasnt", "have", "haven", "havent", "having", "he", "header",
+
+  "hello", "help", "hence", "her", "her", // ADVERBS OF PLACE/TIME
+  "here", "heres", "hers", "herself",
+  "hes", "hey", "hi", // GENERIC ADJECTIVES
+  "high", "him", "himself", "his", "hm",
+  "hmm", "how",
+
+  // LINKING/TRANSITION WORDS
+  "however", "huh", // PRONOUNS - Personal
+  "i", "id", "if", "ill", // CONTRACTED FORMS
+  "im",
+  "immediately", "import", "important", "in", "include", "index", // GENERIC TECHNICAL NOUNS
+  "information",
+  "inside", "instead", "into", "is", "isn",
+  "isnt", "issue", "it", "item", "items", "its",
+  "itself", "ive", "j", "js", "json",
+
+  // FILLER/HEDGE WORDS
+  "just", "k", "keep", "kind", "kinda", "know", "l", "lambda", "last",
+  "later", "least", "len", "less", "let", "lets", "level", "like",
+  "likewise", "line", "lines", "list", "literally",
+  "ll", "look", "looking", "low", "m", "main",
+
+  "make", "making", "manual", "many", "may", "maybe", "md",
+  "me", "mean", "meanwhile", "method", "might", "mine", "mode",
+  "more", "moreover", "most", "much", "multiple", "must",
+
+  // PRONOUNS - Possessive
+  "my", "myself", "n", "nah", "near", "nearly", "need", "needed",
+  "neither", "never", "nevertheless", "new", "next", "nine", // NEGATION
+  "no", "nobody",
+  "none", "none", "nonetheless", "no one", "nope", "nor",
+  "not", "nothing", "now", "o", "obviously", "of",
+  "off", "often",
+
+  "oh", "ok", "okay", "on", "one", "ones",
+  "only", "onto", "option", "optional", "options",
+  "or", "other", "otherwise", "our", "ours",
+
+  "ourselves", "out", "outside", "over", "overall", "p", "part", "parts", "pass",
+
+  "per", "perhaps", "phase",
+  "pl", "please",
+  "point", "points", "possibly", "pretty", "previously", "primary", "probably",
+  "process", "proper", "provide", "provided", "purpose",
+  "put", // FILE EXTENSIONS
+  "py", "q", "question", // QUERY LANGUAGE
+  "questions",
+  "quite", "r", "rather",
+
+  // FRAGMENT WORDS
+  "re", "real", "really", "recently",
+
+  "region", "remain", "require",
+
+  "required", "result", "return", "right", "s", "same", "say",
+  "secondary", // DOCUMENT/CODE STRUCTURE
+  "section", "see", "seem",
+  // PROGRAMMING KEYWORDS
+  "self", "set", "seven", "several",
+  "shall", "she", "shes", "should",
+  "shouldn", "shouldnt", "show", "similarly", "simple",
+
+  "simply", "since", "single", "six", "so", // QUANTIFIERS
+  "some", "somebody", // PRONOUNS - Indefinite
+  "someone",
+  "something", "sometimes", "somewhat", "soon", "sorta", "source", "specific", "stable",
+  "start", "state", "status", "stay", // STRUCTURAL WORDS
+  "step", "steps",
+
+  "still", "str", "stuff", "such", "sys", "t",
+  "take", "tell", "ten", "that", "thats", "the",
+  "their", "theirs", "them", "themselves", "then", "there",
+
+  "therefore", "theres", "these", "they", "theyre", "theyve",
+  // OVERLY GENERIC TERMS
+  "thing", "things", "think", // PRONOUNS - Demonstrative
+  "this", "those", "though", "three",
+  "through", "thus", "time", "times",
+
+  // PREPOSITIONS
+  "to", "today", "toml", "tomorrow", // SHORT FILLER
+  "too", "totally",
+  "toward", "towards", "true", "try", "trying", "ts",
+
+  // NUMBER WORDS
+  "two", "type", "types", "u", "uh", // SPEECH-TO-TEXT FILLERS (STT artifacts from voice input)
+  "um", "under", "unless",
+
+  "until", "up", "upon", "us", "used", "uses", // COMMON CODING TERMS
+  "using",
+  "v", "value", "ve", "version", "very", "via", "w",
+  "wanna", // COMMON REQUEST PHRASES
+  "want", "was", "wasn", "wasnt", "way", "ways",
+  "we", "well", "were", "weren", "werent", "weve", // QUESTION WORDS
+  "what",
+  "whats", "when", "whenever", "where", "whereas",
+
+  "wherever", "whether", "which", "while",
+
+  // PRONOUNS - Relative
+  "who", "whom", "whos", "whose", "why", "will", "with", "within", "without",
+
+  "won", "wont", "work", "working", "works", "would", "wouldn", "wouldnt", "x", "y", "yaml", "yeah", "yep", "yes",
+  "yesterday", "yet", "yield", "you", "youll", "your", "youre", "yours",
+
+  "yourself", "youve", "yup", "z",
+]);
+
+/**
+ * Filter stop words from text.
+ * Splits on whitespace, removes words in STOP_WORDS set and single-char words.
+ * See SPEC.md §6.4
+ */
+export function filterStopWords(text: string): string {
+  return text
+    .split(/\s+/)
+    .filter((word) => word.length > 1 && !STOP_WORDS.has(word.toLowerCase()))
+    .join(" ");
+}