aiwcli 0.10.3 → 0.11.1

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

@@ -6,10 +6,10 @@
  * 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 { readStateJson, toDict as _toDict, writeStateJson } from "../base/state-io.js";
 import { nowIso } from "../base/utils.js";
-import type { ContextState, Task } from "../types.js";
+import type { ContextState as _ContextState, Task } from "../types.js";
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -27,7 +27,7 @@ export function generateNextTaskId(contextId: string, projectRoot?: string): str
   for (const t of tasks) {
     const match = /^aiw-(\d+)$/.exec(t.id);
     if (match) {
-      const num = parseInt(match[1]!, 10);
+      const num = Number.parseInt(match[1]!, 10);
       if (num > maxNum) maxNum = num;
     }
   }
@@ -46,7 +46,7 @@ export function addTask(
   activeForm = "",
   sessionId = "",
   projectRoot?: string,
-): Task | null {
+): null | Task {
   const state = readStateJson(contextId, projectRoot);
   if (!state) return null;
 
@@ -80,11 +80,11 @@ export function updateTask(
   contextId: string,
   taskId: string,
   opts?: {
-    status?: string;
     evidence?: string;
-    work_summary?: string;
     files_changed?: string[];
     session_id?: string;
+    status?: string;
+    work_summary?: string;
   },
   projectRoot?: string,
 ): boolean {
@@ -99,6 +99,7 @@ export function updateTask(
           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;
@@ -167,12 +168,15 @@ export function generateTaskSummary(contextId: string, projectRoot?: string): st
     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}`);
   }

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

@@ -6,17 +6,18 @@
  * 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 * 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 { getContextDir, getContextHandoffsDir } from "../base/constants.js";
+import { logError, logInfo } from "../base/logger.js";
 import { nowIso } from "../base/utils.js";
-import { getContext, saveState } from "../context/context-store.js";
+import { getContext, saveState as _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";
+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.
@@ -124,8 +125,7 @@ function renderHandoffMarkdown(doc: HandoffDocument): string {
   );
 
   // Active tasks
-  lines.push(renderTaskList(doc.active_tasks, "Active Tasks", true).trimEnd());
-  lines.push("");
+  lines.push(renderTaskList(doc.active_tasks, "Active Tasks", true).trimEnd(), "");
 
   // Completed this session
   if (doc.completed_tasks_this_session.length > 0) {
@@ -133,8 +133,7 @@ function renderHandoffMarkdown(doc: HandoffDocument): string {
       doc.completed_tasks_this_session as any[],
       "Completed This Session",
       false,
-    ).trimEnd());
-    lines.push("");
+    ).trimEnd(), "");
   }
 
   // Work summary
@@ -148,6 +147,7 @@ function renderHandoffMarkdown(doc: HandoffDocument): string {
     for (let i = 0; i < doc.next_steps.length; i++) {
       lines.push(`${i + 1}. ${doc.next_steps[i]}`);
     }
+
     lines.push("");
   }
 
@@ -157,6 +157,7 @@ function renderHandoffMarkdown(doc: HandoffDocument): string {
     for (const note of doc.important_notes) {
       lines.push(`- ${note}`);
     }
+
     lines.push("");
   }
 

package/dist/templates/_shared/lib-ts/handoff/handoff-reader.ts

@@ -0,0 +1,158 @@
+/**
+ * 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): string | null {
+  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[entries.length - 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, "utf-8");
+      }
+    } 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(
+    parseInt(year!, 10),
+    parseInt(month!, 10) - 1,
+    parseInt(day!, 10),
+    parseInt(hour!, 10),
+    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,
+): string | null {
+  // Try plan.md frontmatter
+  const planMdPath = path.join(handoffFolder, "plan.md");
+  try {
+    if (fs.existsSync(planMdPath)) {
+      const content = fs.readFileSync(planMdPath, "utf-8");
+      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(/\r?\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/templates/formatters.ts

@@ -32,7 +32,7 @@ export function getStatusIcon(status: string): string {
 
 // §13.3 — Task rendering
 export function renderTaskItem(
-  task: Task | Record<string, any>,
+  task: Record<string, any> | Task,
   showDescription = true,
   maxDescriptionLength = 100,
 ): string {
@@ -48,14 +48,16 @@ export function renderTaskItem(
     let truncated = description.slice(0, maxDescriptionLength);
     if (description.length > maxDescriptionLength) {
       truncated += "...";
-    }
+    }
+
     return `${line}\n  - ${truncated}`;
-  }
+  }
+
   return line;
 }
 
 export function renderTaskList(
-  tasks: Array<Task | Record<string, any>>,
+  tasks: Array<Record<string, any> | Task>,
   header = "Active Tasks",
   showDescription = true,
 ): string {

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

@@ -5,112 +5,114 @@
  */
 
 // §1.1
-export type Mode = "idle" | "has_plan" | "has_handoff" | "active";
+export type Mode = "active" | "has_handoff" | "has_plan" | "idle";
 
 export interface ContextState {
-  id: string;
-  status: "active" | "completed";
-  summary: string;
-  method: string;
-  tags: string[];
   created_at: string;
+  handoff_consumed: boolean;
+  handoff_path: null | string;
+  id: string;
   last_active: string;
+  last_session: LastSession | null;
+  method: string;
   mode: Mode;
-  plan_path: string | null;
-  plan_hash: string | null;
-  plan_signature: string | null;
-  plan_id: string | null;
   plan_anchors: string[];
   plan_consumed: boolean;
-  handoff_path: string | null;
-  handoff_consumed: boolean;
+  plan_hash: null | string;
+  plan_id: null | string;
+  plan_path: null | string;
+  plan_signature: null | string;
   session_ids: string[];
-  last_session: LastSession | null;
+  status: "active" | "completed";
+  summary: string;
+  tags: string[];
   tasks: Task[];
 }
 
 // §1.2
 export interface GitState {
   branch?: string;
-  uncommitted_files?: string[];
   last_commit_short?: string;
+  uncommitted_files?: string[];
 }
 
 export interface LastSession {
-  session_id?: string;
-  saved_at?: string;
-  save_reason?: string;
-  transcript_path?: string;
   context_remaining_pct?: number;
+  context_warnings_fired?: number[];
   git_state?: GitState;
+  save_reason?: string;
+  saved_at?: string;
+  session_id?: string;
+  transcript_path?: string;
 }
 
 // §1.3
 export interface Task {
-  id: string;
-  subject: string;
-  description: string;
   active_form: string;
-  status: "pending" | "in_progress" | "completed" | "blocked";
+  completed_at: null | string;
   created_at: string;
-  completed_at: string | null;
+  description: string;
   evidence: string;
-  work_summary: string;
   files_changed: string[];
+  id: string;
   session_id?: string;
+  status: "blocked" | "completed" | "in_progress" | "pending";
+  subject: string;
+  work_summary: string;
 }
 
 // §1.4
 export interface IndexEntry {
-  summary: string;
-  mode: string;
   last_active: string;
+  mode: string;
+  summary: string;
 }
 
 export interface IndexFile {
-  version: "3.0";
-  updated_at: string;
-  sessions: Record<string, string>;
   contexts: Record<string, IndexEntry>;
+  sessions: Record<string, string>;
+  updated_at: string;
+  version: "3.0";
 }
 
 // §1.5
 export interface LogEntry {
-  ts: string;
-  level: "debug" | "info" | "warn" | "error";
-  hook: string;
-  msg: string;
   component?: string;
   data?: any;
+  hook: string;
+  level: "debug" | "error" | "info" | "warn";
+  msg: string;
   tb?: string;
+  ts: string;
 }
 
 // §1.6
 export interface HookInput {
-  hook_event_name: string;
-  tool_name?: string;
-  tool_input?: Record<string, any>;
-  tool_result?: string;
-  session_id?: string;
-  cwd?: string;
-  transcript_path?: string;
   context_window?: {
+    context_window_size?: number;
     current_usage?: {
+      cache_creation_input_tokens?: number;
       cache_read_input_tokens?: number;
       input_tokens?: number;
-      cache_creation_input_tokens?: number;
       output_tokens?: number;
     };
-    context_window_size?: number;
   };
+  cwd?: string;
+  hook_event_name: string;
   permission_mode?: string;
+  session_id?: string;
   source?: string;
+  tool_input?: Record<string, any>;
+  tool_name?: string;
+  tool_result?: string;
+  transcript_path?: string;
 }
 
 // §1.7
 export interface HookOutput {
   hookSpecificOutput?: {
     additionalContext?: string;
+    hookEventName?: string;
     permissionDecision?: "allow" | "deny";
     permissionDecisionReason?: string;
   };
@@ -118,34 +120,45 @@ export interface HookOutput {
 
 // §1.8
 export interface InferenceResult {
-  success: boolean;
-  output: string;
   error?: string;
   latency_ms: number;
+  output: string;
+  success: boolean;
 }
 
 // §1.9
 export interface HandoffDocument {
+  active_tasks: Task[];
+  completed_tasks_this_session: Array<{ subject: string }>;
+  context_folder: string;
   context_id: string;
   context_summary: string;
-  session_id: string;
-  reason: string;
   created_at: string;
-  plan_path: string | null;
-  context_folder: string;
   events_log_path: string;
-  active_tasks: Task[];
-  completed_tasks_this_session: Array<{ subject: string }>;
-  work_summary: string;
-  next_steps: string[];
+  file_path: null | string;
   important_notes: string[];
-  file_path: string | null;
+  next_steps: string[];
+  plan_path: null | string;
+  reason: string;
+  session_id: string;
+  work_summary: string;
 }
 
 // §1.10
+export interface HandoffSections {
+  completedWork: null | string;
+  context: null | string;
+  deadEnds: null | string;
+  decisions: null | string;
+  index: null | string;
+  pending: null | string;
+  plan: null | string;
+}
+
+// §1.11
 export interface CaretCommand {
   ends: string[];
-  select: string | null;
-  new_context_desc: string | null;
+  new_context_desc: null | string;
   remaining_prompt: string;
+  select: null | string;
 }

package/dist/templates/_shared/scripts/resolve_context.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env bun
+/**
+ * Resolve and print the active context ID.
+ *
+ * Usage:
+ *   bun .aiwcli/_shared/scripts/resolve_context.ts
+ *
+ * Prints the context ID to stdout. Exits 1 if no active context found.
+ * Used by command templates (/handoff, /handoff-resume) to programmatically
+ * get the context ID instead of parsing system reminders.
+ */
+import { getProjectRoot } from "../lib-ts/base/constants.js";
+import { eprint } from "../lib-ts/base/utils.js";
+import { findActiveContextId } from "../lib-ts/context/context-store.js";
+
+const projectRoot = getProjectRoot(process.cwd());
+const contextId = findActiveContextId(projectRoot);
+
+if (!contextId) {
+  eprint("No active context found. Handoffs require an active context.");
+  process.exit(1);
+}
+
+console.log(contextId);