aiwcli 0.10.2 → 0.10.3

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

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

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

@@ -0,0 +1,23 @@
+/**
+ * Subprocess environment utilities.
+ * See SPEC.md §5.10
+ */
+
+/**
+ * Check if this is an internal subprocess call.
+ * All hooks should check this and return early to prevent recursion.
+ */
+export function isInternalCall(): boolean {
+  return process.env.AIWCLI_INTERNAL_CALL === "true";
+}
+
+/**
+ * Get environment for internal subprocess calls.
+ * Returns a copy of process.env with AIWCLI_INTERNAL_CALL=true.
+ */
+export function getInternalSubprocessEnv(): Record<string, string | undefined> {
+  return {
+    ...process.env,
+    AIWCLI_INTERNAL_CALL: "true",
+  };
+}