aiwcli 0.10.3 → 0.11.0

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/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);