gsd-pi 2.18.0 → 2.19.0

package/dist/resources/extensions/gsd/captures.ts

@@ -0,0 +1,384 @@
+/**
+ * GSD Captures — Fire-and-forget thought capture with triage classification
+ *
+ * Append-only capture file at `.gsd/CAPTURES.md`. Each capture is an H3 section
+ * with bold metadata fields, parseable by the same patterns used in files.ts.
+ *
+ * Worktree-aware: captures always resolve to the original project root's
+ * `.gsd/CAPTURES.md`, not the worktree's local `.gsd/`.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+import { gsdRoot } from "./paths.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type Classification = "quick-task" | "inject" | "defer" | "replan" | "note";
+
+export interface CaptureEntry {
+  id: string;
+  text: string;
+  timestamp: string;
+  status: "pending" | "triaged" | "resolved";
+  classification?: Classification;
+  resolution?: string;
+  rationale?: string;
+  resolvedAt?: string;
+}
+
+export interface TriageResult {
+  captureId: string;
+  classification: Classification;
+  rationale: string;
+  affectedFiles?: string[];
+  targetSlice?: string;
+}
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const CAPTURES_FILENAME = "CAPTURES.md";
+const VALID_CLASSIFICATIONS: readonly string[] = [
+  "quick-task", "inject", "defer", "replan", "note",
+];
+
+// ─── Path Resolution ──────────────────────────────────────────────────────────
+
+/**
+ * Resolve the path to CAPTURES.md, aware of worktree context.
+ *
+ * In worktree-isolated mode, basePath is `.gsd/worktrees/<MID>/`.
+ * Captures must resolve to the *original* project root's `.gsd/CAPTURES.md`,
+ * not the worktree-local `.gsd/`. This ensures all captures go to one file
+ * regardless of which worktree the agent is running in.
+ *
+ * Detection: if basePath contains `/.gsd/worktrees/`, walk up to the
+ * directory that contains `.gsd/worktrees/` — that's the project root.
+ */
+export function resolveCapturesPath(basePath: string): string {
+  const resolved = resolve(basePath);
+  const worktreeMarker = `${sep}.gsd${sep}worktrees${sep}`;
+  const idx = resolved.indexOf(worktreeMarker);
+  if (idx !== -1) {
+    // basePath is inside a worktree — resolve to project root
+    const projectRoot = resolved.slice(0, idx);
+    return join(projectRoot, ".gsd", CAPTURES_FILENAME);
+  }
+  return join(gsdRoot(basePath), CAPTURES_FILENAME);
+}
+
+// ─── File I/O ─────────────────────────────────────────────────────────────────
+
+/**
+ * Append a new capture entry to CAPTURES.md.
+ * Creates `.gsd/` and the file if they don't exist.
+ * Returns the generated capture ID.
+ */
+export function appendCapture(basePath: string, text: string): string {
+  const filePath = resolveCapturesPath(basePath);
+  const dir = join(filePath, "..");
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const id = `CAP-${randomUUID().slice(0, 8)}`;
+  const timestamp = new Date().toISOString();
+
+  const entry = [
+    `### ${id}`,
+    `**Text:** ${text}`,
+    `**Captured:** ${timestamp}`,
+    `**Status:** pending`,
+    "",
+  ].join("\n");
+
+  if (existsSync(filePath)) {
+    const existing = readFileSync(filePath, "utf-8");
+    writeFileSync(filePath, existing.trimEnd() + "\n\n" + entry, "utf-8");
+  } else {
+    const header = `# Captures\n\n`;
+    writeFileSync(filePath, header + entry, "utf-8");
+  }
+
+  return id;
+}
+
+/**
+ * Parse all capture entries from CAPTURES.md.
+ * Returns entries in file order (oldest first).
+ */
+export function loadAllCaptures(basePath: string): CaptureEntry[] {
+  const filePath = resolveCapturesPath(basePath);
+  if (!existsSync(filePath)) return [];
+
+  const content = readFileSync(filePath, "utf-8");
+  return parseCapturesContent(content);
+}
+
+/**
+ * Load only pending (unresolved) captures.
+ */
+export function loadPendingCaptures(basePath: string): CaptureEntry[] {
+  return loadAllCaptures(basePath).filter(c => c.status === "pending");
+}
+
+/**
+ * Fast check for pending captures without full parse.
+ * Reads the file and scans for `**Status:** pending` via regex.
+ * Returns false if the file doesn't exist.
+ */
+export function hasPendingCaptures(basePath: string): boolean {
+  const filePath = resolveCapturesPath(basePath);
+  if (!existsSync(filePath)) return false;
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    return /\*\*Status:\*\*\s*pending/i.test(content);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Count pending captures without full parse — single file read.
+ * Uses regex to count `**Status:** pending` occurrences.
+ * Returns 0 if file doesn't exist or on error.
+ */
+export function countPendingCaptures(basePath: string): number {
+  const filePath = resolveCapturesPath(basePath);
+  if (!existsSync(filePath)) return 0;
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const matches = content.match(/\*\*Status:\*\*\s*pending/gi);
+    return matches ? matches.length : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Mark a capture as resolved with classification and rationale.
+ * Rewrites the entry in place, preserving other entries.
+ */
+export function markCaptureResolved(
+  basePath: string,
+  captureId: string,
+  classification: Classification,
+  resolution: string,
+  rationale: string,
+): void {
+  const filePath = resolveCapturesPath(basePath);
+  if (!existsSync(filePath)) return;
+
+  const content = readFileSync(filePath, "utf-8");
+  const resolvedAt = new Date().toISOString();
+
+  // Find the section for this capture ID and rewrite its fields
+  const sectionRegex = new RegExp(
+    `(### ${escapeRegex(captureId)}\\n(?:(?!### ).)*?)(?=### |$)`,
+    "s",
+  );
+  const match = sectionRegex.exec(content);
+  if (!match) return;
+
+  let section = match[1];
+
+  // Update Status field
+  section = section.replace(
+    /\*\*Status:\*\*\s*.+/,
+    `**Status:** resolved`,
+  );
+
+  // Append classification, resolution, rationale, and timestamp if not present
+  const newFields = [
+    `**Classification:** ${classification}`,
+    `**Resolution:** ${resolution}`,
+    `**Rationale:** ${rationale}`,
+    `**Resolved:** ${resolvedAt}`,
+  ];
+
+  // Remove any existing classification/resolution/rationale/resolved fields
+  // (in case of re-triage)
+  section = section.replace(/\*\*Classification:\*\*\s*.+\n?/g, "");
+  section = section.replace(/\*\*Resolution:\*\*\s*.+\n?/g, "");
+  section = section.replace(/\*\*Rationale:\*\*\s*.+\n?/g, "");
+  section = section.replace(/\*\*Resolved:\*\*\s*.+\n?/g, "");
+
+  // Add new fields after Status line
+  section = section.trimEnd() + "\n" + newFields.join("\n") + "\n";
+
+  const updated = content.replace(sectionRegex, section);
+  writeFileSync(filePath, updated, "utf-8");
+}
+
+// ─── Parser ───────────────────────────────────────────────────────────────────
+
+/**
+ * Parse CAPTURES.md content into CaptureEntry array.
+ */
+function parseCapturesContent(content: string): CaptureEntry[] {
+  const entries: CaptureEntry[] = [];
+
+  // Split on H3 headings
+  const sections = content.split(/^### /m).slice(1); // skip content before first H3
+
+  for (const section of sections) {
+    const lines = section.split("\n");
+    const id = lines[0]?.trim();
+    if (!id) continue;
+
+    const body = lines.slice(1).join("\n");
+    const text = extractBoldField(body, "Text");
+    const timestamp = extractBoldField(body, "Captured");
+    const statusRaw = extractBoldField(body, "Status");
+    const classification = extractBoldField(body, "Classification") as Classification | null;
+    const resolution = extractBoldField(body, "Resolution");
+    const rationale = extractBoldField(body, "Rationale");
+    const resolvedAt = extractBoldField(body, "Resolved");
+
+    if (!text || !timestamp) continue;
+
+    const status = (statusRaw === "resolved" || statusRaw === "triaged")
+      ? statusRaw
+      : "pending";
+
+    entries.push({
+      id,
+      text,
+      timestamp,
+      status,
+      ...(classification && VALID_CLASSIFICATIONS.includes(classification) ? { classification } : {}),
+      ...(resolution ? { resolution } : {}),
+      ...(rationale ? { rationale } : {}),
+      ...(resolvedAt ? { resolvedAt } : {}),
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Extract value from a bold-prefixed line like "**Key:** Value".
+ * Local copy of the pattern from files.ts to keep this module self-contained.
+ */
+function extractBoldField(text: string, key: string): string | null {
+  const regex = new RegExp(`^\\*\\*${escapeRegex(key)}:\\*\\*\\s*(.+)$`, "m");
+  const match = regex.exec(text);
+  return match ? match[1].trim() : null;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ─── Triage Output Parser ─────────────────────────────────────────────────────
+
+/**
+ * Parse LLM triage output into TriageResult array.
+ *
+ * Handles:
+ * - Clean JSON array
+ * - JSON wrapped in fenced code block (```json ... ```)
+ * - JSON with leading/trailing prose
+ * - Single object (not array) — wraps in array
+ * - Malformed JSON — returns empty array (caller should fall back to note)
+ * - Partial results — valid entries are kept, invalid skipped
+ */
+export function parseTriageOutput(llmResponse: string): TriageResult[] {
+  if (!llmResponse || !llmResponse.trim()) return [];
+
+  // Try to extract JSON from fenced code blocks first
+  const fenced = llmResponse.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/);
+  const jsonStr = fenced ? fenced[1] : extractJsonSubstring(llmResponse);
+
+  if (!jsonStr) return [];
+
+  try {
+    const parsed = JSON.parse(jsonStr);
+    const arr = Array.isArray(parsed) ? parsed : [parsed];
+    return arr
+      .filter(isValidTriageResult)
+      .map(normalizeTriageResult);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Try to find a JSON array or object substring in prose text.
+ * Looks for the first [ or { and finds its matching bracket.
+ */
+function extractJsonSubstring(text: string): string | null {
+  // Find first [ or {
+  const arrStart = text.indexOf("[");
+  const objStart = text.indexOf("{");
+
+  let start: number;
+  let openChar: string;
+  let closeChar: string;
+
+  if (arrStart === -1 && objStart === -1) return null;
+  if (arrStart === -1) {
+    start = objStart;
+    openChar = "{";
+    closeChar = "}";
+  } else if (objStart === -1) {
+    start = arrStart;
+    openChar = "[";
+    closeChar = "]";
+  } else {
+    start = Math.min(arrStart, objStart);
+    openChar = start === arrStart ? "[" : "{";
+    closeChar = start === arrStart ? "]" : "}";
+  }
+
+  // Find matching bracket
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escape = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === openChar) depth++;
+    if (ch === closeChar) depth--;
+    if (depth === 0) {
+      return text.slice(start, i + 1);
+    }
+  }
+
+  return null;
+}
+
+function isValidTriageResult(obj: unknown): boolean {
+  if (!obj || typeof obj !== "object") return false;
+  const o = obj as Record<string, unknown>;
+  return (
+    typeof o.captureId === "string" &&
+    typeof o.classification === "string" &&
+    VALID_CLASSIFICATIONS.includes(o.classification) &&
+    typeof o.rationale === "string"
+  );
+}
+
+function normalizeTriageResult(obj: Record<string, unknown>): TriageResult {
+  return {
+    captureId: obj.captureId as string,
+    classification: obj.classification as Classification,
+    rationale: obj.rationale as string,
+    ...(Array.isArray(obj.affectedFiles) ? { affectedFiles: obj.affectedFiles as string[] } : {}),
+    ...(typeof obj.targetSlice === "string" ? { targetSlice: obj.targetSlice } : {}),
+  };
+}

package/dist/resources/extensions/gsd/commands.ts

@@ -11,9 +11,11 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
+import { GSDVisualizerOverlay } from "./visualizer-overlay.js";
 import { showQueue, showDiscuss } from "./guided-flow.js";
 import { startAuto, stopAuto, pauseAuto, isAutoActive, isAutoPaused, isStepMode, stopAutoRemote } from "./auto.js";
 import { resolveProjectRoot } from "./worktree.js";
+import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
 import {
   getGlobalGSDPreferencesPath,
   getLegacyGlobalGSDPreferencesPath,
@@ -64,10 +66,11 @@ function projectRoot(): string {
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd next|auto|stop|pause|status|queue|history|undo|skip|export|cleanup|prefs|config|hooks|doctor|migrate|remote|steer|knowledge",
+    description: "GSD — Get Shit Done: /gsd next|auto|stop|pause|status|visualize|queue|capture|triage|history|undo|skip|export|cleanup|prefs|config|hooks|doctor|migrate|remote|steer|knowledge",
     getArgumentCompletions: (prefix: string) => {
       const subcommands = [
-        "next", "auto", "stop", "pause", "status", "queue", "discuss",
+        "next", "auto", "stop", "pause", "status", "visualize", "queue", "discuss",
+        "capture", "triage",
         "history", "undo", "skip", "export", "cleanup", "prefs",
         "config", "hooks", "doctor", "migrate", "remote", "steer", "knowledge",
       ];
@@ -163,6 +166,11 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "visualize") {
+        await handleVisualize(ctx);
+        return;
+      }
+
       if (trimmed === "prefs" || trimmed.startsWith("prefs ")) {
         await handlePrefs(trimmed.replace(/^prefs\s*/, "").trim(), ctx);
         return;
@@ -259,6 +267,16 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed.startsWith("capture ") || trimmed === "capture") {
+        await handleCapture(trimmed.replace(/^capture\s*/, "").trim(), ctx);
+        return;
+      }
+
+      if (trimmed === "triage") {
+        await handleTriage(ctx, pi, process.cwd());
+        return;
+      }
+
       if (trimmed === "config") {
         await handleConfig(ctx);
         return;
@@ -306,7 +324,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
       }
 
       ctx.ui.notify(
-        `Unknown: /gsd ${trimmed}. Use /gsd next|auto|stop|pause|status|queue|discuss|history|undo|skip <unit>|export|cleanup|prefs|config|hooks|doctor|migrate|remote|steer <change>|knowledge <type> <entry>.`,
+        `Unknown: /gsd ${trimmed}. Use /gsd next|auto|stop|pause|status|visualize|queue|capture|triage|discuss|history|undo|skip <unit>|export|cleanup|prefs|config|hooks|doctor|migrate|remote|steer <change>|knowledge <type> <entry>.`,
         "warning",
       );
     },
@@ -344,6 +362,28 @@ export async function fireStatusViaCommand(
   await handleStatus(ctx as ExtensionCommandContext);
 }
 
+async function handleVisualize(ctx: ExtensionCommandContext): Promise<void> {
+  if (!ctx.hasUI) {
+    ctx.ui.notify("Visualizer requires an interactive terminal.", "warning");
+    return;
+  }
+
+  await ctx.ui.custom<void>(
+    (tui, theme, _kb, done) => {
+      return new GSDVisualizerOverlay(tui, theme, () => done());
+    },
+    {
+      overlay: true,
+      overlayOptions: {
+        width: "80%",
+        minWidth: 80,
+        maxHeight: "90%",
+        anchor: "center",
+      },
+    },
+  );
+}
+
 async function handlePrefs(args: string, ctx: ExtensionCommandContext): Promise<void> {
   const trimmed = args.trim();
 
@@ -1195,6 +1235,102 @@ async function handleKnowledge(args: string, ctx: ExtensionCommandContext): Prom
   ctx.ui.notify(`Added ${type} to KNOWLEDGE.md: "${entryText}"`, "success");
 }
 
+// ─── Capture Command ──────────────────────────────────────────────────────────
+
+/**
+ * Handle `/gsd capture "..."` — fire-and-forget thought capture.
+ * Appends to `.gsd/CAPTURES.md` without interrupting auto-mode.
+ * Works in all modes: auto running, paused, stopped, no project.
+ */
+async function handleCapture(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  // Strip surrounding quotes from the argument
+  let text = args.trim();
+  if (!text) {
+    ctx.ui.notify('Usage: /gsd capture "your thought here"', "warning");
+    return;
+  }
+  // Remove wrapping quotes (single or double)
+  if ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'"))) {
+    text = text.slice(1, -1);
+  }
+  if (!text) {
+    ctx.ui.notify('Usage: /gsd capture "your thought here"', "warning");
+    return;
+  }
+
+  const basePath = process.cwd();
+
+  // Ensure .gsd/ exists — capture should work even without a milestone
+  const gsdDir = join(basePath, ".gsd");
+  if (!existsSync(gsdDir)) {
+    mkdirSync(gsdDir, { recursive: true });
+  }
+
+  const id = appendCapture(basePath, text);
+  ctx.ui.notify(`Captured: ${id} — "${text.length > 60 ? text.slice(0, 57) + "..." : text}"`, "info");
+}
+
+// ─── Triage Command ───────────────────────────────────────────────────────────
+
+/**
+ * Handle `/gsd triage` — manually trigger triage of pending captures.
+ * Dispatches the triage prompt to the LLM for classification.
+ * Triage result handling (confirmation UI) is wired in T03.
+ */
+async function handleTriage(ctx: ExtensionCommandContext, pi: ExtensionAPI, basePath: string): Promise<void> {
+  if (!hasPendingCaptures(basePath)) {
+    ctx.ui.notify("No pending captures to triage.", "info");
+    return;
+  }
+
+  const pending = loadPendingCaptures(basePath);
+  ctx.ui.notify(`Triaging ${pending.length} pending capture${pending.length === 1 ? "" : "s"}...`, "info");
+
+  // Build context for the triage prompt
+  const state = await deriveState(basePath);
+  let currentPlan = "";
+  let roadmapContext = "";
+
+  if (state.activeMilestone && state.activeSlice) {
+    const { resolveSliceFile, resolveMilestoneFile } = await import("./paths.js");
+    const planFile = resolveSliceFile(basePath, state.activeMilestone.id, state.activeSlice.id, "PLAN");
+    if (planFile) {
+      const { loadFile: load } = await import("./files.js");
+      currentPlan = (await load(planFile)) ?? "";
+    }
+    const roadmapFile = resolveMilestoneFile(basePath, state.activeMilestone.id, "ROADMAP");
+    if (roadmapFile) {
+      const { loadFile: load } = await import("./files.js");
+      roadmapContext = (await load(roadmapFile)) ?? "";
+    }
+  }
+
+  // Format pending captures for the prompt
+  const capturesList = pending.map(c =>
+    `- **${c.id}**: "${c.text}" (captured: ${c.timestamp})`
+  ).join("\n");
+
+  // Dispatch triage prompt
+  const { loadPrompt } = await import("./prompt-loader.js");
+  const prompt = loadPrompt("triage-captures", {
+    pendingCaptures: capturesList,
+    currentPlan: currentPlan || "(no active slice plan)",
+    roadmapContext: roadmapContext || "(no active roadmap)",
+  });
+
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
+  const workflow = readFileSync(workflowPath, "utf-8");
+
+  pi.sendMessage(
+    {
+      customType: "gsd-triage",
+      content: `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${prompt}`,
+      display: false,
+    },
+    { triggerTurn: true },
+  );
+}
+
 async function handleSteer(change: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
   const basePath = process.cwd();
   const state = await deriveState(basePath);