aiwcli 0.12.6 → 0.12.8

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

@@ -1,184 +1,184 @@
-/**
- * Core utilities for shared context management.
- * See SPEC.md §14.2, §14.3
- */
-
-import { sanitizeTitle } from "./constants.js";
-import { logDebug, logError, logWarn } from "./logger.js";
-import { STOP_WORDS } from "./stop-words.js";
-
-/**
- * Print to stderr. For terminal-only UX messages, not diagnostics.
- */
-export function eprint(...args: any[]): void {
-  process.stderr.write(args.map(String).join(" ") + "\n");
-}
-
-/**
- * Get current local datetime as Date.
- */
-export function nowLocal(): Date {
-  return new Date();
-}
-
-/**
- * Get current time as ISO 8601 string (local time, no timezone suffix).
- * Matches Python datetime.now().isoformat() behavior.
- */
-export function nowIso(): string {
-  const d = new Date();
-  const year = d.getFullYear();
-  const month = String(d.getMonth() + 1).padStart(2, "0");
-  const day = String(d.getDate()).padStart(2, "0");
-  const hours = String(d.getHours()).padStart(2, "0");
-  const minutes = String(d.getMinutes()).padStart(2, "0");
-  const seconds = String(d.getSeconds()).padStart(2, "0");
-  const ms = String(d.getMilliseconds()).padStart(3, "0");
-  return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${ms}`;
-}
-
-/**
- * Format datetime for display.
- * Returns "YYYY-MM-DD HH:MM:SS"
- * See SPEC.md §14.3
- */
-export function formatTimestamp(dt?: Date): string {
-  const d = dt ?? nowLocal();
-  const year = d.getFullYear();
-  const month = String(d.getMonth() + 1).padStart(2, "0");
-  const day = String(d.getDate()).padStart(2, "0");
-  const hours = String(d.getHours()).padStart(2, "0");
-  const minutes = String(d.getMinutes()).padStart(2, "0");
-  const seconds = String(d.getSeconds()).padStart(2, "0");
-  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
-}
-
-/**
- * Parse ISO 8601 timestamp string.
- * Returns null if parsing fails.
- * See SPEC.md §14.3
- */
-export function parseIsoTimestamp(isoStr: string): Date | null {
-  try {
-    const normalized = isoStr.replace("Z", "+00:00");
-    const d = new Date(normalized);
-    if (isNaN(d.getTime())) return null;
-    return d;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Clean text for stop-word matching in slug generation.
- * Strips apostrophes (i'm -> im), removes punctuation, normalizes whitespace.
- * See SPEC.md §14.2
- */
-export function cleanTextForSlug(text: string): string {
-  if (!text) return "";
-  let result = text.toLowerCase();
-  result = result.replaceAll('\'', "");            // i'm -> im, you're -> youre
-  result = result.replaceAll(/[^a-z0-9\s]/g, " "); // punctuation -> spaces
-  result = result.replaceAll(/\s+/g, " ").trim();
-  return result;
-}
-
-/**
- * Generate a slug from text using AI inference with stop-word fallbacks.
- * Pipeline: AI inference → stop-word post-filter → stop-word fallback → word-length fallback.
- * Reusable by both context ID generation and plan archival.
- * See SPEC.md §14.2
- */
-export function generateSlug(
-  text: string,
-  maxLen = 150,
-  fallbackSlug = "context",
-): string {
-  if (!text || !text.trim()) return fallbackSlug;
-
-  let slug: null | string = null;
-  const cleanedText = cleanTextForSlug(text);
-
-  // Tier 1: AI inference via generateContextIdSlug (sync — uses execFileSync)
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports, no-undef
-    const { generateContextIdSlug } = require("./inference.js");
-    const aiSlug = generateContextIdSlug(text);
-    if (aiSlug) {
-      const filteredWords = aiSlug
-        .split(/\s+/)
-        .filter(
-          (w: string) => !STOP_WORDS.has(w.toLowerCase()) && w.length > 1,
-        );
-      if (filteredWords.length >= 5) {
-        slug = sanitizeTitle(filteredWords.join(" "), maxLen);
-      } else {
-        logDebug(
-          "utils",
-          `AI slug too generic after stop-word filter (${filteredWords.length} words remain), using fallback`,
-        );
-      }
-    }
-  } catch (error: any) {
-    logWarn("utils", `AI slug generation failed, using fallback: ${error}`);
-  }
-
-  // Tier 2: Stop-word filtering on cleaned text
-  if (!slug) {
-    const words = cleanedText
-      .split(/\s+/)
-      .filter((w) => !STOP_WORDS.has(w) && w.length > 1)
-      .slice(0, 12);
-    slug = words.length >= 3
-      ? sanitizeTitle(words.join(" "), maxLen)
-      : sanitizeTitle(
-          cleanedText.split(/\s+/).filter((w) => w.length > 2).slice(0, 6).join(" "),
-          maxLen,
-        ) || fallbackSlug;
-  }
-
-  return slug;
-}
-
-/**
- * Generate a context ID from a summary string.
- * Format: YYMMDD-HHMM-slug
- * Delegates slug generation to generateSlug().
- * See SPEC.md §14.2
- */
-export function generateContextId(
-  summary: string,
-  existingIds?: Set<string>,
-): string {
-  const now = new Date();
-  const yy = String(now.getFullYear()).slice(2);
-  const mm = String(now.getMonth() + 1).padStart(2, "0");
-  const dd = String(now.getDate()).padStart(2, "0");
-  const hh = String(now.getHours()).padStart(2, "0");
-  const min = String(now.getMinutes()).padStart(2, "0");
-  const timestamp = `${yy}${mm}${dd}-${hh}${min}`;
-
-  let baseId: string;
-
-  try {
-    const slug = generateSlug(summary);
-    baseId = `${timestamp}-${slug}`;
-  } catch (error: any) {
-    logError(
-      "utils",
-      `Context ID generation failed entirely, using timestamp: ${error}`,
-    );
-    baseId = `${timestamp}-context`;
-  }
-
-  if (!existingIds || !existingIds.has(baseId)) {
-    return baseId;
-  }
-
-  let counter = 2;
-  while (existingIds.has(`${baseId}-${counter}`)) {
-    counter++;
-  }
-
-  return `${baseId}-${counter}`;
-}
+/**
+ * Core utilities for shared context management.
+ * See SPEC.md §14.2, §14.3
+ */
+
+import { sanitizeTitle } from "./constants.js";
+import { logDebug, logError, logWarn } from "./logger.js";
+import { STOP_WORDS } from "./stop-words.js";
+
+/**
+ * Print to stderr. For terminal-only UX messages, not diagnostics.
+ */
+export function eprint(...args: any[]): void {
+  process.stderr.write(args.map(String).join(" ") + "\n");
+}
+
+/**
+ * Get current local datetime as Date.
+ */
+export function nowLocal(): Date {
+  return new Date();
+}
+
+/**
+ * Get current time as ISO 8601 string (local time, no timezone suffix).
+ * Matches Python datetime.now().isoformat() behavior.
+ */
+export function nowIso(): string {
+  const d = new Date();
+  const year = d.getFullYear();
+  const month = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  const hours = String(d.getHours()).padStart(2, "0");
+  const minutes = String(d.getMinutes()).padStart(2, "0");
+  const seconds = String(d.getSeconds()).padStart(2, "0");
+  const ms = String(d.getMilliseconds()).padStart(3, "0");
+  return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${ms}`;
+}
+
+/**
+ * Format datetime for display.
+ * Returns "YYYY-MM-DD HH:MM:SS"
+ * See SPEC.md §14.3
+ */
+export function formatTimestamp(dt?: Date): string {
+  const d = dt ?? nowLocal();
+  const year = d.getFullYear();
+  const month = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  const hours = String(d.getHours()).padStart(2, "0");
+  const minutes = String(d.getMinutes()).padStart(2, "0");
+  const seconds = String(d.getSeconds()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
+/**
+ * Parse ISO 8601 timestamp string.
+ * Returns null if parsing fails.
+ * See SPEC.md §14.3
+ */
+export function parseIsoTimestamp(isoStr: string): Date | null {
+  try {
+    const normalized = isoStr.replace("Z", "+00:00");
+    const d = new Date(normalized);
+    if (isNaN(d.getTime())) return null;
+    return d;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clean text for stop-word matching in slug generation.
+ * Strips apostrophes (i'm -> im), removes punctuation, normalizes whitespace.
+ * See SPEC.md §14.2
+ */
+export function cleanTextForSlug(text: string): string {
+  if (!text) return "";
+  let result = text.toLowerCase();
+  result = result.replaceAll('\'', "");            // i'm -> im, you're -> youre
+  result = result.replaceAll(/[^a-z0-9\s]/g, " "); // punctuation -> spaces
+  result = result.replaceAll(/\s+/g, " ").trim();
+  return result;
+}
+
+/**
+ * Generate a slug from text using AI inference with stop-word fallbacks.
+ * Pipeline: AI inference → stop-word post-filter → stop-word fallback → word-length fallback.
+ * Reusable by both context ID generation and plan archival.
+ * See SPEC.md §14.2
+ */
+export function generateSlug(
+  text: string,
+  maxLen = 150,
+  fallbackSlug = "context",
+): string {
+  if (!text || !text.trim()) return fallbackSlug;
+
+  let slug: null | string = null;
+  const cleanedText = cleanTextForSlug(text);
+
+  // Tier 1: AI inference via generateContextIdSlug (sync — uses execFileSync)
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, no-undef
+    const { generateContextIdSlug } = require("./inference.js");
+    const aiSlug = generateContextIdSlug(text);
+    if (aiSlug) {
+      const filteredWords = aiSlug
+        .split(/\s+/)
+        .filter(
+          (w: string) => !STOP_WORDS.has(w.toLowerCase()) && w.length > 1,
+        );
+      if (filteredWords.length >= 5) {
+        slug = sanitizeTitle(filteredWords.join(" "), maxLen);
+      } else {
+        logDebug(
+          "utils",
+          `AI slug too generic after stop-word filter (${filteredWords.length} words remain), using fallback`,
+        );
+      }
+    }
+  } catch (error: any) {
+    logWarn("utils", `AI slug generation failed, using fallback: ${error}`);
+  }
+
+  // Tier 2: Stop-word filtering on cleaned text
+  if (!slug) {
+    const words = cleanedText
+      .split(/\s+/)
+      .filter((w) => !STOP_WORDS.has(w) && w.length > 1)
+      .slice(0, 12);
+    slug = words.length >= 3
+      ? sanitizeTitle(words.join(" "), maxLen)
+      : sanitizeTitle(
+          cleanedText.split(/\s+/).filter((w) => w.length > 2).slice(0, 6).join(" "),
+          maxLen,
+        ) || fallbackSlug;
+  }
+
+  return slug;
+}
+
+/**
+ * Generate a context ID from a summary string.
+ * Format: YYMMDD-HHMM-slug
+ * Delegates slug generation to generateSlug().
+ * See SPEC.md §14.2
+ */
+export function generateContextId(
+  summary: string,
+  existingIds?: Set<string>,
+): string {
+  const now = new Date();
+  const yy = String(now.getFullYear()).slice(2);
+  const mm = String(now.getMonth() + 1).padStart(2, "0");
+  const dd = String(now.getDate()).padStart(2, "0");
+  const hh = String(now.getHours()).padStart(2, "0");
+  const min = String(now.getMinutes()).padStart(2, "0");
+  const timestamp = `${yy}${mm}${dd}-${hh}${min}`;
+
+  let baseId: string;
+
+  try {
+    const slug = generateSlug(summary);
+    baseId = `${timestamp}-${slug}`;
+  } catch (error: any) {
+    logError(
+      "utils",
+      `Context ID generation failed entirely, using timestamp: ${error}`,
+    );
+    baseId = `${timestamp}-context`;
+  }
+
+  if (!existingIds || !existingIds.has(baseId)) {
+    return baseId;
+  }
+
+  let counter = 2;
+  while (existingIds.has(`${baseId}-${counter}`)) {
+    counter++;
+  }
+
+  return `${baseId}-${counter}`;
+}

package/dist/templates/_shared/lib-ts/context/CLAUDE.md

@@ -0,0 +1,134 @@
+# Context Management System
+
+Shared library for context lifecycle management: state machine, session binding, plan tracking, and artifact routing.
+
+## Overview
+
+A "context" is a named work session with a state machine that tracks mode transitions, staged artifacts, and session history. Contexts persist to disk as `state.json` files under `_output/contexts/{id}/`. They are the backbone of the handoff and session-restore system.
+
+## File Structure
+
+```
+context/
+├── CLAUDE.md          ← This file
+├── context-store.ts   ← Core CRUD + state machine transitions
+├── context-formatter.ts ← Context → human-readable text for injection
+├── context-selector.ts  ← Find active/relevant contexts by criteria
+├── plan-manager.ts    ← Plan file archive, discovery, hash, path extraction
+└── task-tracker.ts    ← Task progress tracking within a context
+```
+
+## State Machine
+
+```
+                      ┌─────────────┐
+                      │   created   │
+                      └──────┬──────┘
+                             │ first user prompt / maybeActivate()
+                             ▼
+                      ┌─────────────┐
+                  ┌──▶│   active    │◀──────────────────┐
+                  │   └──────┬──────┘                   │
+                  │          │ session_end + artifact    │ session_start (clear)
+                  │          ▼                           │
+                  │   ┌─────────────────┐               │
+                  │   │ has_staged_work  │ ──────────────┘
+                  │   └──────┬──────────┘
+                  │          │ work_consumed = true
+                  │          ▼
+                  │   ┌─────────────┐
+                  │   │  archived   │──▶ (terminal)
+                  │   └─────────────┘
+                  │
+                  └─── reopenContext()
+```
+
+**Modes:**
+- `created` — context initialized, not yet bound to a session
+- `active` — session in progress, context is current
+- `has_staged_work` — session ended with staged artifact (plan or handoff)
+- `archived` — context complete and closed
+
+## API Reference
+
+### `context-store.ts`
+
+| Function | Purpose |
+|----------|---------|
+| `createContext(id, opts)` | Create new context with initial state |
+| `getContext(contextId)` | Read context by ID |
+| `getAllContexts(mode?, root?)` | List all contexts, optionally filtered by mode |
+| `getContextBySessionId(sessionId, root?)` | Find context that owns a session ID |
+| `updateContext(contextId, patch)` | Partial state update |
+| `bindSession(contextId, sessionId)` | Attach session ID to context |
+| `updateMode(contextId, mode)` | Transition state machine mode |
+| `maybeActivate(contextId)` | Activate if in `created` mode (idempotent) |
+| `completeContext(contextId)` | Mark complete, archive |
+| `archiveContext(contextId)` | Archive without completing |
+| `reopenContext(contextId)` | Transition `archived` → `active` |
+| `createContextFromPrompt(prompt)` | Create context from user prompt text |
+| `loadState(contextId)` | Raw state.json read |
+| `saveState(contextId, state)` | Raw state.json write |
+| `determineArtifactType(context)` | Detect `"plan"` or `"handoff"` from staged state |
+
+### `context-formatter.ts`
+
+Formats context state for injection into Claude's context window.
+
+| Function | Purpose |
+|----------|---------|
+| `formatContext(context)` | Full context as human-readable markdown |
+| `formatContextSummary(context)` | Short one-line summary |
+
+### `context-selector.ts`
+
+Finds contexts by various criteria.
+
+| Function | Purpose |
+|----------|---------|
+| `selectActiveContext(root?)` | Find the single active context (errors if multiple) |
+| `findContextByMode(mode, root?)` | Find contexts in a given mode |
+| `findStagedWorkContext(root?)` | Find context with `has_staged_work` mode |
+
+### `plan-manager.ts`
+
+Manages plan file lifecycle within a context.
+
+| Function | Purpose |
+|----------|---------|
+| `archivePlan(contextId, planPath)` | Copy plan to context's `plans/` folder |
+| `findLatestPlan(contextId)` | Find most recent archived plan |
+| `generatePlanId()` | Generate unique plan ID |
+| `normalizePlanContent(text)` | Strip metadata for hashing |
+| `extractPlanAnchors(content)` | Extract key phrases from plan for matching |
+| `findPlanPathInTranscript(transcriptPath)` | Parse plan path from JSONL transcript |
+| `extractPlanPathFromResult(toolResult)` | Extract plan path from tool result JSON |
+
+### `task-tracker.ts`
+
+Tracks task progress (ISC criteria) within a context.
+
+| Function | Purpose |
+|----------|---------|
+| `initTaskTracker(contextId)` | Create task tracker for context |
+| `addTask(contextId, task)` | Add tracked task |
+| `updateTask(contextId, taskId, patch)` | Update task status |
+| `getTaskSummary(contextId)` | Progress summary |
+
+## Which Hooks Use This System
+
+| Hook | Usage |
+|------|-------|
+| `session_start.ts` | `getContextBySessionId()`, `bindSession()`, `updateMode()`, `getAllContexts()` |
+| `session_end.ts` | `getContextBySessionId()`, `updateMode()`, `saveState()` |
+| `user_prompt_submit.ts` | `getAllContexts()`, `maybeActivate()`, `determineArtifactType()` |
+| `archive_plan.ts` | `getContextBySessionId()`, `archivePlan()` |
+| `save_handoff.ts` | `getContextBySessionId()`, `updateContext()` |
+| `cc-native-plan-review.ts` | `getContextBySessionId()`, `getAllContexts()` |
+
+## Design Decisions
+
+- **Single state.json per context:** All state is in one file. No distributed state. Atomic writes prevent corruption.
+- **No moves out of lib-ts:** Context is pure library code imported by ~8 shared hooks. Moving it would require updating all those import paths for no structural gain. The subfolder is already co-located; it just needed documentation.
+- **`maybeActivate()` is idempotent:** Can be called from any hook without checking current mode — safe to call repeatedly.
+- **`determineArtifactType()` drives session restore:** Returns `"plan"` or `"handoff"` to dispatch the correct restoration path in `session_start.ts`.