aiwcli 0.10.2 → 0.11.0

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

@@ -0,0 +1,216 @@
+/**
+ * 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 crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { atomicWrite } from "../base/atomic-write.js";
+import { getContextDir, getContextHandoffsDir } from "../base/constants.js";
+import { logError, logInfo } from "../base/logger.js";
+import { nowIso } from "../base/utils.js";
+import { getContext, saveState as _saveState } from "../context/context-store.js";
+import { getTasks } from "../context/task-tracker.js";
+import { formatContinuationHeader, formatReason, renderTaskList } from "../templates/formatters.js";
+import type { HandoffDocument, Task as _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(), "");
+
+  // 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(), "");
+  }
+
+  // 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/handoff/handoff-reader.ts

@@ -0,0 +1,159 @@
+/**
+ * Handoff reader utilities for programmatic resume.
+ *
+ * Provides functions to find, read, and parse handoff folders
+ * created by save_handoff.ts. Used by resume_handoff.ts script
+ * and potentially by session_start hooks.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { getContextHandoffsDir } from "../base/constants.js";
+import { getContext } from "../context/context-store.js";
+import type { HandoffSections } from "../types.js";
+
+/**
+ * Find the most recent handoff folder for a context.
+ * Lists subdirectories in the handoffs dir, sorts by name
+ * (YYYY-MM-DD-HHMM format ensures lexicographic = chronological).
+ * Returns full path to most recent folder, or null.
+ */
+export function findLatestHandoff(contextId: string, projectRoot?: string): null | string {
+  const handoffsDir = getContextHandoffsDir(contextId, projectRoot);
+
+  try {
+    if (!fs.existsSync(handoffsDir)) return null;
+    const entries = fs.readdirSync(handoffsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => e.name)
+      .sort();
+
+    if (entries.length === 0) return null;
+    return path.join(handoffsDir, entries.at(-1)!);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read all section files from a handoff folder, structured by priority.
+ * Returns content for each file (null if missing/unreadable).
+ */
+export function readHandoffSections(handoffFolder: string): HandoffSections {
+  const fileMap: Record<keyof HandoffSections, string> = {
+    index: "index.md",
+    deadEnds: "dead-ends.md",
+    pending: "pending.md",
+    plan: "plan.md",
+    decisions: "decisions.md",
+    completedWork: "completed-work.md",
+    context: "context.md",
+  };
+
+  const sections: HandoffSections = {
+    index: null,
+    deadEnds: null,
+    pending: null,
+    plan: null,
+    decisions: null,
+    completedWork: null,
+    context: null,
+  };
+
+  for (const [key, filename] of Object.entries(fileMap)) {
+    const filePath = path.join(handoffFolder, filename);
+    try {
+      if (fs.existsSync(filePath)) {
+        sections[key as keyof HandoffSections] = fs.readFileSync(filePath, "utf8");
+      }
+    } catch {
+      // graceful — leave as null
+    }
+  }
+
+  return sections;
+}
+
+/**
+ * Parse the handoff folder name to extract creation timestamp.
+ * Expects YYYY-MM-DD-HHMM format (with optional -N suffix for collisions).
+ */
+export function getHandoffTimestamp(handoffFolder: string): Date | null {
+  const basename = path.basename(handoffFolder);
+  // Match YYYY-MM-DD-HHMM with optional collision suffix
+  const match = basename.match(/^(\d{4})-(\d{2})-(\d{2})-(\d{2})(\d{2})/);
+  if (!match) return null;
+
+  const [, year, month, day, hour, minute] = match;
+  const date = new Date(
+    Number.parseInt(year!, 10),
+    Number.parseInt(month!, 10) - 1,
+    Number.parseInt(day!, 10),
+    Number.parseInt(hour!, 10),
+    Number.parseInt(minute!, 10),
+  );
+
+  return isNaN(date.getTime()) ? null : date;
+}
+
+/**
+ * Get the plan path referenced by a handoff.
+ * First checks plan.md frontmatter for plan_path, then falls back
+ * to the context state's plan_path.
+ */
+export function getHandoffPlanReference(
+  handoffFolder: string,
+  contextId: string,
+  projectRoot?: string,
+): null | string {
+  // Try plan.md frontmatter
+  const planMdPath = path.join(handoffFolder, "plan.md");
+  try {
+    if (fs.existsSync(planMdPath)) {
+      const content = fs.readFileSync(planMdPath, "utf8");
+      const frontmatter = parseFrontmatter(content);
+      if (frontmatter["plan_path"]) {
+        const pp = frontmatter["plan_path"];
+        if (fs.existsSync(pp)) return pp;
+      }
+    }
+  } catch {
+    // fall through to context state
+  }
+
+  // Fall back to context state
+  try {
+    const context = getContext(contextId, projectRoot);
+    if (context?.plan_path && fs.existsSync(context.plan_path)) {
+      return context.plan_path;
+    }
+  } catch {
+    // ignore
+  }
+
+  return null;
+}
+
+/**
+ * Parse YAML-style frontmatter from markdown content.
+ * Returns key-value pairs from the --- block.
+ */
+function parseFrontmatter(content: string): Record<string, string> {
+  const frontmatter: Record<string, string> = {};
+  if (!content.startsWith("---")) return frontmatter;
+
+  const parts = content.split("---", 3);
+  if (parts.length < 3) return frontmatter;
+
+  for (const line of parts[1]!.trim().split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx !== -1) {
+      const key = line.slice(0, colonIdx).trim();
+      const value = line.slice(colonIdx + 1).trim();
+      frontmatter[key] = value;
+    }
+  }
+
+  return frontmatter;
+}

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"
+  }
+}

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

@@ -0,0 +1,104 @@
+/**
+ * Formatters for context management templates.
+ * Constants and helpers for consistent formatting across hooks and display.
+ * See SPEC.md §13
+ */
+
+import type { Task } from "../types.js";
+
+// §13.1 — Legacy mode display mapping (used by handoff/document_generator)
+export const LEGACY_MODE_MAP: Record<string, string> = {
+  planning: "[Planning]",
+  pending_implementation: "[Plan Ready]",
+  implementing: "[Implementing]",
+  none: "",
+};
+
+// §13.2 — Status icon mapping
+export const STATUS_ICONS: Record<string, string> = {
+  pending: "⬜",
+  in_progress: "🔄",
+  blocked: "🚫",
+  completed: "✅",
+};
+
+export function getModeDisplay(mode: string): string {
+  return LEGACY_MODE_MAP[mode] ?? "";
+}
+
+export function getStatusIcon(status: string): string {
+  return STATUS_ICONS[status] ?? "⬜";
+}
+
+// §13.3 — Task rendering
+export function renderTaskItem(
+  task: Record<string, any> | Task,
+  showDescription = true,
+  maxDescriptionLength = 100,
+): string {
+  const status = (task as any).status ?? "pending";
+  const subject = (task as any).subject ?? "";
+  const description = (task as any).description ?? "";
+
+  const icon = getStatusIcon(status);
+  const statusText = `[${status.toUpperCase()}]`;
+  const line = `- ${icon} ${statusText} ${subject}`;
+
+  if (showDescription && description) {
+    let truncated = description.slice(0, maxDescriptionLength);
+    if (description.length > maxDescriptionLength) {
+      truncated += "...";
+    }
+
+    return `${line}\n  - ${truncated}`;
+  }
+
+  return line;
+}
+
+export function renderTaskList(
+  tasks: Array<Record<string, any> | Task>,
+  header = "Active Tasks",
+  showDescription = true,
+): string {
+  const lines = [`### ${header}`, ""];
+
+  if (tasks.length === 0) {
+    lines.push("No active tasks.");
+  } else {
+    for (const task of tasks) {
+      lines.push(renderTaskItem(task, showDescription));
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+// §13.4 — Continuation headers
+const CONTINUATION_HEADERS: Record<string, (id: string) => string> = {
+  context: (id) => `## CONTINUING CONTEXT: ${id}`,
+  resuming: (id) => `## RESUMING FROM HANDOFF: ${id}`,
+  implementing: (id) => `## CONTINUING IMPLEMENTATION: ${id}`,
+  handoff: (id) => `# Session Handoff: ${id}`,
+};
+
+export function formatContinuationHeader(
+  headerType: string,
+  contextId: string,
+): string {
+  const fn = CONTINUATION_HEADERS[headerType];
+  return fn ? fn(contextId) : `## ${contextId}`;
+}
+
+// §13.5 — Reason formatting
+export const REASON_MAP: Record<string, string> = {
+  low_context: "Context window running low",
+  user_requested: "User requested handoff",
+  error_recovery: "Error recovery",
+  session_end: "Session ending",
+};
+
+export function formatReason(reason: string): string {
+  return REASON_MAP[reason] ?? reason;
+}

package/dist/templates/_shared/{lib/templates/plan_context.py → lib-ts/templates/plan-context.ts}

@@ -1,18 +1,10 @@
-"""Plan context templates for add_plan_context hook.
+/**
+ * Plan context templates for add_plan_context hook.
+ * See SPEC.md §13.6
+ */
 
-Provides standardized templates for:
-- Evaluation context reminder (injected on plan writes)
-"""
-
-
-def get_evaluation_context_reminder() -> str:
-    """Get the plan evaluation context reminder template.
-
-    Returns:
-        Formatted markdown reminder about adding evaluation context
-    """
-    return """
-## CRITICAL: Write This Plan for a Different Agent
+export function getEvaluationContextReminder(): string {
+  return `## CRITICAL: Write This Plan for a Different Agent
 
 The agent executing this plan has ZERO context from this conversation — no chat history, no memory of files you explored or research you did.
 
@@ -20,7 +12,7 @@ The agent executing this plan has ZERO context from this conversation — no cha
 
 ### Required Structure
 
-```
+\`\`\`
 # Plan: <descriptive title>
 
 ## Background
@@ -31,10 +23,10 @@ What exactly to build/change
 
 ## Files
 **Modify:**
-- `exact/path/to/file.py` - What changes (reference line numbers or patterns)
+- \`exact/path/to/file.py\` - What changes (reference line numbers or patterns)
 
 **Reference:**
-- `exact/path/to/reference.py` - Why relevant (e.g., "pattern to follow at lines 12-30")
+- \`exact/path/to/reference.py\` - Why relevant (e.g., "pattern to follow at lines 12-30")
 
 ## Steps
 1. [Specific steps with function names, patterns, or code snippets]
@@ -47,7 +39,7 @@ What exactly to build/change
 Decisions not written down are lost when this session ends. Update the nearest CLAUDE.md and MEMORY.md so the next session inherits what you learned.
 
 **CLAUDE.md** (nearest to changed code — cascades to subdirectories):
-- `exact/path/to/CLAUDE.md` — What to document
+- \`exact/path/to/CLAUDE.md\` — What to document
 
 **What to write:**
 - Architectural choices and why alternatives were rejected
@@ -55,7 +47,7 @@ Decisions not written down are lost when this session ends. Update the nearest C
 - Workarounds with context on the underlying issue
 - Patterns that prevent future mistakes
 
-**Format:** `## Topic` / `**Decision:** ...` / `**Rationale:** ...`
+**Format:** \`## Topic\` / \`**Decision:** ...\` / \`**Rationale:** ...\`
 
 **MEMORY.md** (cross-session learning for the AI agent):
 - Insight that would prevent a future mistake (e.g., "hook X silently drops field Y")
@@ -63,11 +55,11 @@ Decisions not written down are lost when this session ends. Update the nearest C
 **Include when:** Architectural decisions, non-obvious constraints, workarounds, or patterns discovered during implementation.
 **Omit entries for:** Routine changes with no decisions (rename, formatting, dependency bump).
 When in doubt, write it — a lean entry is better than a lost decision.
-```
+\`\`\`
 
 ### Self-Check
 - [ ] Could I execute this if I forgot our entire conversation?
 - [ ] Are file paths exact (not "the auth file")?
 - [ ] Are implementation details specific (not "use the approach we discussed")?
-- [ ] Do documentation entries capture decisions the next session would otherwise lose?
-""".strip()
+- [ ] Do documentation entries capture decisions the next session would otherwise lose?`;
+}

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

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "Node16",
+    "moduleResolution": "node16",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": true
+  },
+  "include": ["./**/*.ts"]
+}