aiwcli 0.10.1 → 0.10.3

package/dist/templates/_shared/lib-ts/context/plan-manager.ts

@@ -0,0 +1,292 @@
+/**
+ * Plan lifecycle management — archival, lookup, and path extraction.
+ * See SPEC.md §9
+ *
+ * Provides pure-data operations on plan files:
+ * - archivePlan: copy plan to context plans/ folder, compute hash + signature
+ * - findLatestPlan: locate the most relevant plan for a context
+ * - extractPlanPathFromResult: parse plan path from ExitPlanMode output
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { getContextDir, getContextPlansDir, sanitizeTitle } from "../base/constants.js";
+import { atomicWrite } from "../base/atomic-write.js";
+import { readStateJson } from "../base/state-io.js";
+import { logDebug, logInfo, logWarn, logError } from "../base/logger.js";
+import type { ContextState } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Plan archival
+// ---------------------------------------------------------------------------
+
+/**
+ * Archive a plan file to the context's plans/ folder.
+ * Computes a content hash and signature.
+ * Does NOT modify state.json or mode.
+ * See SPEC.md §9.2
+ *
+ * Returns [archivedPath, planHash, planSignature] on success,
+ * or [null, null, null] on error.
+ */
+export async function archivePlan(
+  planPath: string,
+  contextId: string,
+  projectRoot?: string,
+): Promise<[string | null, string | null, string | null]> {
+  if (!fs.existsSync(planPath)) {
+    logWarn("plan_manager", `Plan file not found: ${planPath}`);
+    return [null, null, null];
+  }
+
+  let content: string;
+  try {
+    content = fs.readFileSync(planPath, "utf-8");
+  } catch (e: any) {
+    logError("plan_manager", `Failed to read plan: ${e}`);
+    return [null, null, null];
+  }
+
+  // Compute hash and signature
+  const planHash = crypto.createHash("sha256").update(content, "utf-8").digest("hex").slice(0, 12);
+  const planSignature = content.slice(0, 200);
+
+  // Ensure plans directory exists
+  const plansDir = getContextPlansDir(contextId, projectRoot);
+  fs.mkdirSync(plansDir, { recursive: true });
+
+  // Generate archive filename: YYYY-MM-DD-HHMM-<slug>.md
+  const now = new Date();
+  const dateStr = [
+    now.getFullYear(),
+    "-",
+    String(now.getMonth() + 1).padStart(2, "0"),
+    "-",
+    String(now.getDate()).padStart(2, "0"),
+    "-",
+    String(now.getHours()).padStart(2, "0"),
+    String(now.getMinutes()).padStart(2, "0"),
+  ].join("");
+
+  // Try AI inference for a descriptive slug
+  let slug: string | null = null;
+  try {
+    const { generateContextIdSlug } = await import("../base/inference.js");
+    const aiSlug = generateContextIdSlug(content.slice(0, 500), 5);
+    if (aiSlug) {
+      slug = sanitizeTitle(aiSlug, 60);
+    }
+  } catch {
+    // AI inference unavailable — use filename fallback
+  }
+
+  // Fallback: use plan filename
+  if (!slug) {
+    const stem = path.basename(planPath, path.extname(planPath));
+    slug = sanitizeTitle(stem, 30);
+  }
+
+  let archiveName = `${dateStr}-${slug}.md`;
+  let archivePath = path.join(plansDir, archiveName);
+
+  // Handle filename collisions
+  let counter = 2;
+  while (fs.existsSync(archivePath)) {
+    archiveName = `${dateStr}-${slug}-${counter}.md`;
+    archivePath = path.join(plansDir, archiveName);
+    counter++;
+  }
+
+  // Write archived plan atomically
+  const [success, error] = atomicWrite(archivePath, content);
+  if (!success) {
+    logError("plan_manager", `Failed to write archive: ${error}`);
+    return [null, null, null];
+  }
+
+  logInfo("plan_manager", `Archived plan to: ${archivePath}`);
+  return [archivePath, planHash, planSignature];
+}
+
+// ---------------------------------------------------------------------------
+// Plan lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the most relevant plan file for a context.
+ * Priority: state.json plan_path > most recent .md in plans/ dir.
+ * See SPEC.md §9.3
+ */
+export function findLatestPlan(
+  contextId: string,
+  projectRoot?: string,
+): string | null {
+  // 1. Check state.json plan_path first
+  try {
+    const state = readStateJson(contextId, projectRoot);
+    if (state?.plan_path && fs.existsSync(state.plan_path)) {
+      return state.plan_path;
+    }
+  } catch (e: any) {
+    logWarn("plan_manager", `Failed to check state.json plan_path: ${e}`);
+  }
+
+  // 2. Fall back to most recent .md in plans/ dir
+  const plansDir = getContextPlansDir(contextId, projectRoot);
+  if (fs.existsSync(plansDir)) {
+    try {
+      const files = fs.readdirSync(plansDir)
+        .filter(f => f.endsWith(".md"))
+        .map(f => {
+          const fullPath = path.join(plansDir, f);
+          return { path: fullPath, mtime: fs.statSync(fullPath).mtimeMs };
+        })
+        .sort((a, b) => b.mtime - a.mtime);
+
+      if (files.length > 0) {
+        return files[0]!.path;
+      }
+    } catch { /* ignore */ }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Plan identification and normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a short unique plan identifier (8 hex chars).
+ * See SPEC.md §9.4
+ */
+export function generatePlanId(): string {
+  return crypto.randomUUID().replace(/-/g, "").slice(0, 8);
+}
+
+/**
+ * Aggressively normalize plan content for hashing.
+ * Strips all XML/HTML tags and collapses whitespace.
+ * See SPEC.md §9.5
+ */
+export function normalizePlanContent(text: string): string {
+  let result = text.replace(/<[^>]+>/g, "");
+  result = result.replace(/\s+/g, " ").trim();
+  return result;
+}
+
+/**
+ * Extract structural anchors from plan content.
+ * Returns markdown headings + first substantial paragraph as short strings.
+ * See SPEC.md §9.6
+ */
+export function extractPlanAnchors(content: string, maxAnchors = 5): string[] {
+  const anchors: string[] = [];
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("#") && trimmed.length > 3) {
+      anchors.push(trimmed.slice(0, 80));
+    } else if (anchors.length === 0 && trimmed.length > 20) {
+      anchors.push(trimmed.slice(0, 80));
+    }
+    if (anchors.length >= maxAnchors) break;
+  }
+  return anchors;
+}
+
+// ---------------------------------------------------------------------------
+// Transcript-based plan path extraction
+// ---------------------------------------------------------------------------
+
+const MAX_TRANSCRIPT_SIZE = 50 * 1024 * 1024; // 50 MB
+
+/**
+ * Find the plan file path by parsing the session transcript JSONL.
+ * Searches in reverse for the most recent Write tool call targeting .claude/plans/.
+ * See SPEC.md §9.7
+ */
+export function findPlanPathInTranscript(transcriptPath: string): string | null {
+  if (!transcriptPath) return null;
+
+  if (!fs.existsSync(transcriptPath)) {
+    logDebug("plan_manager", `Transcript not found: ${transcriptPath}`);
+    return null;
+  }
+
+  let size: number;
+  try {
+    size = fs.statSync(transcriptPath).size;
+  } catch {
+    return null;
+  }
+
+  if (size > MAX_TRANSCRIPT_SIZE) {
+    logWarn("plan_manager", `Transcript too large (${size} bytes), skipping`);
+    return null;
+  }
+
+  let lines: string[];
+  try {
+    lines = fs.readFileSync(transcriptPath, "utf-8").split("\n");
+  } catch (e: any) {
+    logWarn("plan_manager", `Failed to read transcript: ${e}`);
+    return null;
+  }
+
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]!.trim();
+    if (!line) continue;
+
+    let data: any;
+    try {
+      data = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    let contentArr: any;
+    try {
+      contentArr = data.message?.content;
+    } catch {
+      continue;
+    }
+
+    if (!Array.isArray(contentArr)) continue;
+
+    for (const block of contentArr) {
+      if (typeof block !== "object" || block === null) continue;
+      if (block.type !== "tool_use" || block.name !== "Write") continue;
+
+      const filePath = block.input?.file_path;
+      if (!filePath) continue;
+
+      // Check if path contains .claude/plans/ as consecutive parts
+      const parts = filePath.replace(/\\/g, "/").split("/");
+      for (let j = 0; j < parts.length - 1; j++) {
+        if (parts[j] === ".claude" && parts[j + 1] === "plans") {
+          logInfo("plan_manager", `Extracted plan path from transcript: ${filePath}`);
+          return filePath;
+        }
+      }
+    }
+  }
+
+  logDebug("plan_manager", "No plan Write found in transcript");
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Path extraction from tool output
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract plan file path from ExitPlanMode tool result.
+ * Parses the pattern: "Your plan has been saved to: <path>"
+ * See SPEC.md §9.8
+ */
+export function extractPlanPathFromResult(toolResult: string): string | null {
+  if (!toolResult) return null;
+  const match = toolResult.match(/Your plan has been saved to:\s*(.+\.md)/);
+  return match ? match[1]!.trim() : null;
+}

package/dist/templates/_shared/lib-ts/context/task-tracker.ts

@@ -0,0 +1,181 @@
+/**
+ * Task tracker — direct state.json CRUD for tasks.
+ * See SPEC.md §10
+ *
+ * Writes tasks directly to the tasks[] array in state.json.
+ * Uses state-io for I/O to avoid circular imports with context-store.
+ */
+
+import { readStateJson, writeStateJson, toDict } from "../base/state-io.js";
+import { logWarn } from "../base/logger.js";
+import { nowIso } from "../base/utils.js";
+import type { ContextState, Task } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan tasks[] for highest aiw-N, return aiw-(N+1).
+ * See SPEC.md §10.2
+ */
+export function generateNextTaskId(contextId: string, projectRoot?: string): string {
+  const state = readStateJson(contextId, projectRoot);
+  const tasks = state?.tasks ?? [];
+
+  let maxNum = 0;
+  for (const t of tasks) {
+    const match = /^aiw-(\d+)$/.exec(t.id);
+    if (match) {
+      const num = parseInt(match[1]!, 10);
+      if (num > maxNum) maxNum = num;
+    }
+  }
+
+  return `aiw-${maxNum + 1}`;
+}
+
+/**
+ * Add a new task to state.json tasks[] and return the task object.
+ * See SPEC.md §10.3
+ */
+export function addTask(
+  contextId: string,
+  subject: string,
+  description = "",
+  activeForm = "",
+  sessionId = "",
+  projectRoot?: string,
+): Task | null {
+  const state = readStateJson(contextId, projectRoot);
+  if (!state) return null;
+
+  const taskId = generateNextTaskId(contextId, projectRoot);
+  const task: Task = {
+    id: taskId,
+    subject,
+    description,
+    active_form: activeForm,
+    status: "pending",
+    created_at: nowIso(),
+    completed_at: null,
+    evidence: "",
+    work_summary: "",
+    files_changed: [],
+    session_id: sessionId,
+  };
+
+  state.tasks.push(task);
+  state.last_active = nowIso();
+
+  const [success] = writeStateJson(contextId, state, projectRoot);
+  return success ? task : null;
+}
+
+/**
+ * Find task by task_id in tasks[], update fields, return true on success.
+ * See SPEC.md §10.4
+ */
+export function updateTask(
+  contextId: string,
+  taskId: string,
+  opts?: {
+    status?: string;
+    evidence?: string;
+    work_summary?: string;
+    files_changed?: string[];
+    session_id?: string;
+  },
+  projectRoot?: string,
+): boolean {
+  const state = readStateJson(contextId, projectRoot);
+  if (!state) return false;
+
+  for (const task of state.tasks) {
+    if (task.id === taskId) {
+      if (opts?.status !== undefined) {
+        task.status = opts.status as Task["status"];
+        if (opts.status === "completed") {
+          task.completed_at = nowIso();
+        }
+      }
+      if (opts?.evidence) task.evidence = opts.evidence;
+      if (opts?.work_summary) task.work_summary = opts.work_summary;
+      if (opts?.files_changed !== undefined) task.files_changed = opts.files_changed;
+      if (opts?.session_id) task.session_id = opts.session_id;
+      state.last_active = nowIso();
+      const [success] = writeStateJson(contextId, state, projectRoot);
+      return success;
+    }
+  }
+
+  logWarn("task_tracker", `Task '${taskId}' not found in context '${contextId}'`);
+  return false;
+}
+
+/**
+ * Remove task from tasks[] and return true on success.
+ * See SPEC.md §10.5
+ */
+export function deleteTask(
+  contextId: string,
+  taskId: string,
+  projectRoot?: string,
+): boolean {
+  const state = readStateJson(contextId, projectRoot);
+  if (!state) return false;
+
+  const originalLen = state.tasks.length;
+  state.tasks = state.tasks.filter(t => t.id !== taskId);
+
+  if (state.tasks.length === originalLen) {
+    logWarn("task_tracker", `Task '${taskId}' not found in context '${contextId}'`);
+    return false;
+  }
+
+  state.last_active = nowIso();
+  const [success] = writeStateJson(contextId, state, projectRoot);
+  return success;
+}
+
+/**
+ * Return tasks[] from state.json.
+ * See SPEC.md §10.6
+ */
+export function getTasks(contextId: string, projectRoot?: string): Task[] {
+  const state = readStateJson(contextId, projectRoot);
+  if (!state) return [];
+  return state.tasks;
+}
+
+/**
+ * Partition tasks and format as markdown checklist.
+ * See SPEC.md §10.7
+ */
+export function generateTaskSummary(contextId: string, projectRoot?: string): string {
+  const tasks = getTasks(contextId, projectRoot);
+  if (tasks.length === 0) return "No tasks in this context.";
+
+  const completed = tasks.filter(t => t.status === "completed");
+  const inProgress = tasks.filter(t => t.status === "in_progress");
+  const pending = tasks.filter(t => t.status === "pending");
+  const blocked = tasks.filter(t => t.status === "blocked");
+
+  const lines: string[] = [`### Tasks (${tasks.length} total)`, ""];
+
+  for (const t of completed) {
+    const ws = t.work_summary ? `\n  Work: ${t.work_summary}` : "";
+    lines.push(`- [x] ${t.id}: ${t.subject}${ws}`);
+  }
+  for (const t of inProgress) {
+    lines.push(`- [~] ${t.id}: ${t.subject}`);
+  }
+  for (const t of pending) {
+    lines.push(`- [ ] ${t.id}: ${t.subject}`);
+  }
+  for (const t of blocked) {
+    lines.push(`- [!] ${t.id}: ${t.subject}`);
+  }
+
+  return lines.join("\n");
+}

package/dist/templates/_shared/lib-ts/handoff/document-generator.ts

@@ -0,0 +1,215 @@
+/**
+ * Handoff document generator for context-aware session management.
+ * See SPEC.md §12
+ *
+ * Creates structured handoff documents when a session needs to transfer
+ * work to a new session (typically due to context window limits).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { getContextHandoffsDir, getContextDir } from "../base/constants.js";
+import { atomicWrite } from "../base/atomic-write.js";
+import { logInfo, logError } from "../base/logger.js";
+import { nowIso } from "../base/utils.js";
+import { getContext, saveState } from "../context/context-store.js";
+import { getTasks } from "../context/task-tracker.js";
+import { renderTaskList, formatContinuationHeader, formatReason } from "../templates/formatters.js";
+import type { HandoffDocument, Task } from "../types.js";
+
+/**
+ * Generate and save a handoff document for a context.
+ * See SPEC.md §12.2
+ */
+export function generateHandoffDocument(
+  contextId: string,
+  reason = "low_context",
+  workSummary = "",
+  nextSteps?: string[],
+  importantNotes?: string[],
+  completedThisSession?: string[],
+  projectRoot?: string,
+): HandoffDocument | null {
+  const context = getContext(contextId, projectRoot);
+  if (!context) {
+    logError("handoff", `Context '${contextId}' not found`);
+    return null;
+  }
+
+  // Generate session ID
+  const sessionId = crypto.randomUUID().slice(0, 8);
+
+  // Get pending tasks from state.json
+  const allTasks = getTasks(contextId, projectRoot);
+  const pendingTasks = allTasks.filter(
+    t => t.status === "pending" || t.status === "in_progress" || t.status === "blocked",
+  );
+
+  // Build document
+  const now = nowIso();
+  const contextDir = getContextDir(contextId, projectRoot);
+
+  const doc: HandoffDocument = {
+    context_id: contextId,
+    context_summary: context.summary,
+    session_id: sessionId,
+    reason,
+    created_at: now,
+    plan_path: context.plan_path,
+    context_folder: contextDir,
+    events_log_path: path.join(contextDir, "state.json"),
+    active_tasks: pendingTasks,
+    completed_tasks_this_session: (completedThisSession ?? []).map(s => ({ subject: s })),
+    work_summary: workSummary,
+    next_steps: nextSteps ?? [],
+    important_notes: importantNotes ?? [],
+    file_path: null,
+  };
+
+  // Compute file path BEFORE rendering markdown
+  const handoffsDir = getContextHandoffsDir(contextId, projectRoot);
+  fs.mkdirSync(handoffsDir, { recursive: true });
+
+  const d = new Date();
+  const dateStr = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+  const filename = `${dateStr}-session-${sessionId}.md`;
+  const filePath = path.join(handoffsDir, filename);
+
+  // Set file_path on doc BEFORE rendering markdown
+  doc.file_path = filePath;
+
+  // Generate markdown content
+  const markdown = renderHandoffMarkdown(doc);
+
+  // Save to handoffs folder
+  const [success, error] = atomicWrite(filePath, markdown);
+  if (!success) {
+    logError("handoff", `Failed to write handoff document: ${error}`);
+    return null;
+  }
+
+  logInfo("handoff", `Created handoff document: ${filePath}`);
+  return doc;
+}
+
+/**
+ * Render handoff document as markdown.
+ */
+function renderHandoffMarkdown(doc: HandoffDocument): string {
+  const lines: string[] = [
+    formatContinuationHeader("handoff", doc.context_id),
+    "",
+    `**Created**: ${doc.created_at}`,
+    `**Context ID**: ${doc.context_id}`,
+    `**Session ID**: ${doc.session_id}`,
+    `**Reason**: ${formatReason(doc.reason)}`,
+    "",
+    "## Links",
+    "",
+  ];
+
+  // Plan link
+  if (doc.plan_path) {
+    const planName = path.basename(doc.plan_path);
+    lines.push(`- **Plan**: [${planName}](${doc.plan_path})`);
+  }
+
+  lines.push(
+    `- **Context Folder**: \`${doc.context_folder}\``,
+    `- **Events Log**: \`${doc.events_log_path}\``,
+    "",
+    "## Current State",
+    "",
+  );
+
+  // Active tasks
+  lines.push(renderTaskList(doc.active_tasks, "Active Tasks", true).trimEnd());
+  lines.push("");
+
+  // Completed this session
+  if (doc.completed_tasks_this_session.length > 0) {
+    lines.push(renderTaskList(
+      doc.completed_tasks_this_session as any[],
+      "Completed This Session",
+      false,
+    ).trimEnd());
+    lines.push("");
+  }
+
+  // Work summary
+  if (doc.work_summary) {
+    lines.push("## Context Summary", "", doc.work_summary, "");
+  }
+
+  // Next steps
+  if (doc.next_steps.length > 0) {
+    lines.push("## Next Steps", "");
+    for (let i = 0; i < doc.next_steps.length; i++) {
+      lines.push(`${i + 1}. ${doc.next_steps[i]}`);
+    }
+    lines.push("");
+  }
+
+  // Important notes
+  if (doc.important_notes.length > 0) {
+    lines.push("## Important Notes", "");
+    for (const note of doc.important_notes) {
+      lines.push(`- ${note}`);
+    }
+    lines.push("");
+  }
+
+  // Continuation prompt
+  lines.push(
+    "---",
+    "",
+    "**Continuation Prompt**:",
+    "```",
+    `Continue working on context "${doc.context_id}".`,
+    "",
+    `Handoff document: ${doc.file_path ?? "See above"}`,
+    "",
+    "Read the handoff document, restore tasks with TaskCreate, and continue implementation.",
+    "```",
+  );
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate the prompt to paste into new session for continuation.
+ * See SPEC.md §12.3
+ */
+export function getHandoffContinuationPrompt(doc: HandoffDocument): string {
+  return `Continue working on context "${doc.context_id}".\n\nHandoff document: ${doc.file_path}\n\nRead the handoff document, restore tasks with TaskCreate, and continue implementation.`;
+}
+
+/**
+ * Generate system reminder for low context warning.
+ * See SPEC.md §12.4
+ */
+export function getLowContextWarning(contextRemainingPercent: number, contextId: string): string {
+  return `<system-reminder>
+## LOW CONTEXT WARNING (${contextRemainingPercent}% remaining)
+
+Your context window is running low. Please:
+
+1. **Finish current task** if 1-2 steps away, OR save current progress
+2. **Create handoff document** by calling:
+   \`\`\`python
+   from _shared.lib.handoff import generate_handoff_document
+   doc = generate_handoff_document(
+       context_id="${contextId}",
+       reason="low_context",
+       work_summary="<describe current work>",
+       next_steps=["<step 1>", "<step 2>"],
+       important_notes=["<key decision 1>"]
+   )
+   \`\`\`
+3. **Ask permission** to clear and paste continuation prompt
+
+After creating handoff, ask the user:
+"Context is low. I've created a handoff document. May I clear and continue in a new session?"
+</system-reminder>`;
+}

package/dist/templates/_shared/lib-ts/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "lib-ts-tests",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "mocha",
+    "test:unit": "mocha '__tests__/base/**/*.test.ts' '__tests__/templates/**/*.test.ts'",
+    "test:contract": "mocha '__tests__/context/**/*.test.ts' '__tests__/handoff/**/*.test.ts'",
+    "test:integration": "mocha '__tests__/integration/**/*.test.ts'",
+    "test:parity": "mocha '__tests__/integration/python-parity.test.ts'",
+    "fixtures": "python __tests__/fixtures/generate_fixtures.py"
+  },
+  "devDependencies": {
+    "mocha": "^10.0.0",
+    "chai": "^5.0.0",
+    "@types/mocha": "^10.0.0",
+    "@types/sinon": "^17.0.0",
+    "sinon": "^17.0.0",
+    "typescript": "^5.0.0"
+  }
+}