gsd-pi 2.73.1 → 2.74.0-dev.0306a2e

package/src/resources/extensions/gsd/commands-do.ts

@@ -0,0 +1,109 @@
+/**
+ * GSD Command — /gsd do
+ *
+ * Routes freeform natural language to the correct /gsd subcommand
+ * using keyword matching. Falls back to /gsd quick for task-like input.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+interface Route {
+  keywords: string[];
+  command: string;
+}
+
+const ROUTES: Route[] = [
+  { keywords: ["progress", "status", "dashboard", "how far", "where are we"], command: "status" },
+  { keywords: ["auto", "autonomous", "run all", "keep going", "start auto"], command: "auto" },
+  { keywords: ["stop", "halt", "abort"], command: "stop" },
+  { keywords: ["pause", "break", "take a break"], command: "pause" },
+  { keywords: ["history", "past", "what happened", "previous"], command: "history" },
+  { keywords: ["doctor", "health", "diagnose", "check health"], command: "doctor" },
+  { keywords: ["clean up", "cleanup", "remove old", "prune", "tidy"], command: "cleanup" },
+  { keywords: ["export", "report", "share results"], command: "export" },
+  { keywords: ["ship", "pull request", "create pr", "open pr", "merge"], command: "ship" },
+  { keywords: ["discuss", "talk about", "architecture", "design"], command: "discuss" },
+  { keywords: ["undo", "revert", "rollback", "take back"], command: "undo" },
+  { keywords: ["skip", "skip task", "skip this"], command: "skip" },
+  { keywords: ["queue", "reorder", "milestone order", "order milestones"], command: "queue" },
+  { keywords: ["visualize", "viz", "graph", "chart", "show graph"], command: "visualize" },
+  { keywords: ["capture", "note", "idea", "thought", "remember"], command: "capture" },
+  { keywords: ["inspect", "database", "sqlite", "db state"], command: "inspect" },
+  { keywords: ["knowledge", "rule", "pattern", "lesson"], command: "knowledge" },
+  { keywords: ["session report", "session summary", "cost summary", "how much"], command: "session-report" },
+  { keywords: ["backlog", "parking lot", "later", "someday"], command: "backlog" },
+  { keywords: ["pr branch", "clean branch", "filter commits"], command: "pr-branch" },
+  { keywords: ["add tests", "write tests", "generate tests", "test coverage"], command: "add-tests" },
+  { keywords: ["next", "step", "next step", "what's next"], command: "next" },
+  { keywords: ["migrate", "migration", "convert", "upgrade"], command: "migrate" },
+  { keywords: ["steer", "change direction", "pivot", "redirect"], command: "steer" },
+  { keywords: ["park", "shelve", "set aside"], command: "park" },
+  { keywords: ["widget", "toggle widget"], command: "widget" },
+  { keywords: ["logs", "debug logs", "log files"], command: "logs" },
+];
+
+interface MatchResult {
+  command: string;
+  remainingArgs: string;
+  score: number;
+}
+
+function matchRoute(input: string): MatchResult | null {
+  const lower = input.toLowerCase();
+  let bestMatch: MatchResult | null = null;
+
+  for (const route of ROUTES) {
+    for (const keyword of route.keywords) {
+      if (lower.includes(keyword)) {
+        const score = keyword.length; // Longer match = higher confidence
+        if (!bestMatch || score > bestMatch.score) {
+          // Strip the matched keyword from input to get remaining args
+          const idx = lower.indexOf(keyword);
+          const remaining = (input.slice(0, idx) + input.slice(idx + keyword.length)).trim();
+          bestMatch = { command: route.command, remainingArgs: remaining, score };
+        }
+      }
+    }
+  }
+
+  return bestMatch;
+}
+
+export async function handleDo(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  if (!args.trim()) {
+    ctx.ui.notify(
+      "Usage: /gsd do <what you want to do>\n\n" +
+      "Examples:\n" +
+      "  /gsd do show me progress\n" +
+      "  /gsd do run autonomously\n" +
+      "  /gsd do clean up old branches\n" +
+      "  /gsd do fix the login bug",
+      "warning",
+    );
+    return;
+  }
+
+  const match = matchRoute(args);
+
+  if (match) {
+    const fullCommand = match.remainingArgs
+      ? `${match.command} ${match.remainingArgs}`
+      : match.command;
+
+    ctx.ui.notify(`→ /gsd ${fullCommand}`, "info");
+
+    // Re-dispatch through the main dispatcher
+    const { handleGSDCommand } = await import("./commands/dispatcher.js");
+    await handleGSDCommand(fullCommand, ctx, pi);
+    return;
+  }
+
+  // No keyword match → treat as quick task
+  ctx.ui.notify(`→ /gsd quick ${args}`, "info");
+  const { handleQuick } = await import("./quick.js");
+  await handleQuick(args, ctx, pi);
+}

package/src/resources/extensions/gsd/commands-extract-learnings.ts

@@ -0,0 +1,304 @@
+/**
+ * GSD Command — /gsd extract-learnings
+ *
+ * Analyses completed milestone artefacts and dispatches an LLM turn that
+ * extracts structured knowledge into 4 categories:
+ *   Decisions · Lessons · Patterns · Surprises
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, basename } from "node:path";
+
+import { gsdRoot, resolveMilestonePath } from "./paths.js";
+import { projectRoot } from "./commands/context.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface PhaseArtifacts {
+  plan: string | null;
+  summary: string | null;
+  verification: string | null;
+  uat: string | null;
+  missingRequired: string[];
+}
+
+export interface ExtractLearningsPromptContext {
+  milestoneId: string;
+  milestoneName: string;
+  outputPath: string;
+  relativeOutputPath: string;
+  planContent: string;
+  summaryContent: string;
+  verificationContent: string | null;
+  uatContent: string | null;
+  missingArtifacts: string[];
+  projectName: string;
+}
+
+export interface FrontmatterContext {
+  milestoneId: string;
+  milestoneName: string;
+  projectName: string;
+  generatedAt: string;
+  counts: {
+    decisions: number;
+    lessons: number;
+    patterns: number;
+    surprises: number;
+  };
+  missingArtifacts: string[];
+}
+
+// ─── Pure functions ───────────────────────────────────────────────────────────
+
+export function parseExtractLearningsArgs(args: string): { milestoneId: string | null } {
+  const trimmed = args.trim();
+  return { milestoneId: trimmed || null };
+}
+
+export function buildLearningsOutputPath(milestoneDir: string, milestoneId: string): string {
+  return join(milestoneDir, `${milestoneId}-LEARNINGS.md`);
+}
+
+export function resolvePhaseArtifacts(milestoneDir: string, milestoneId: string): PhaseArtifacts {
+  const missingRequired: string[] = [];
+
+  const planFile = `${milestoneId}-PLAN.md`;
+  const summaryFile = `${milestoneId}-SUMMARY.md`;
+  const verificationFile = `${milestoneId}-VERIFICATION.md`;
+  const uatFile = `${milestoneId}-UAT.md`;
+
+  const planPath = join(milestoneDir, planFile);
+  const summaryPath = join(milestoneDir, summaryFile);
+  const verificationPath = join(milestoneDir, verificationFile);
+  const uatPath = join(milestoneDir, uatFile);
+
+  const plan = existsSync(planPath) ? planPath : null;
+  const summary = existsSync(summaryPath) ? summaryPath : null;
+  const verification = existsSync(verificationPath) ? verificationPath : null;
+  const uat = existsSync(uatPath) ? uatPath : null;
+
+  if (!plan) missingRequired.push(planFile);
+  if (!summary) missingRequired.push(summaryFile);
+
+  return { plan, summary, verification, uat, missingRequired };
+}
+
+export function buildExtractLearningsPrompt(ctx: ExtractLearningsPromptContext): string {
+  const optionalSections: string[] = [];
+
+  if (ctx.verificationContent) {
+    optionalSections.push(`## Verification Report\n\n${ctx.verificationContent}`);
+  }
+  if (ctx.uatContent) {
+    optionalSections.push(`## UAT Report\n\n${ctx.uatContent}`);
+  }
+
+  const missingNote = ctx.missingArtifacts.length > 0
+    ? `\nNote: The following optional artefacts were not available: ${ctx.missingArtifacts.join(", ")}\n`
+    : "";
+
+  return `# Extract Learnings — ${ctx.milestoneId}: ${ctx.milestoneName}
+
+**Project:** ${ctx.projectName}
+**Output file:** ${ctx.outputPath}
+
+## Your Task
+
+Analyse the artefacts below and extract structured knowledge from milestone **${ctx.milestoneId}**.
+
+Write a LEARNINGS document to \`${ctx.outputPath}\` with the following 4 sections:
+
+### Decisions
+Key architectural and design decisions made during this milestone, including the rationale and alternatives considered.
+
+### Lessons
+What the team learned — technical discoveries, process insights, and knowledge gaps that were filled.
+
+### Patterns
+Reusable patterns, approaches, or solutions that emerged and should be applied in future work.
+
+### Surprises
+Unexpected challenges, discoveries, or outcomes — things that deviated from assumptions.
+
+### Source Attribution (REQUIRED)
+
+Every extracted item MUST include a \`Source:\` line immediately after the item text.
+Format: \`Source: {artifact-filename}/{section}\`
+Example: \`Source: M001-PLAN.md/Architecture Decisions\`
+
+Items without a Source attribution are invalid and must not be included in the output.
+
+---
+
+## Artefacts
+
+### Plan
+
+${ctx.planContent}
+
+---
+
+### Summary
+
+${ctx.summaryContent}
+
+${optionalSections.join("\n\n---\n\n")}
+${missingNote}
+---
+
+## Output Format
+
+Write the LEARNINGS file to \`${ctx.relativeOutputPath}\` with YAML frontmatter followed by the 4 sections above.
+Each section should contain concise, actionable bullet points.
+Every bullet point MUST be followed by a source line, for example:
+
+\`\`\`
+### Decisions
+- Chose PostgreSQL over SQLite for concurrent write support.
+  Source: M001-PLAN.md/Architecture Decisions
+\`\`\`
+
+Items without a \`Source:\` line are invalid.
+
+---
+
+## Optional: Capture Individual Learnings
+
+If the \`capture_thought\` tool is available, call it once for each extracted item with:
+- category: "decision" | "lesson" | "pattern" | "surprise"
+- phase: "${ctx.milestoneId}"
+- content: {the learning text}
+- source: {artifact filename}
+
+If \`capture_thought\` is not available, skip this step silently — do not report an error.
+
+---
+
+## Rebuild Knowledge Graph
+
+After writing LEARNINGS.md, call the \`gsd_graph\` tool with \`{ "mode": "build" }\` to rebuild the knowledge graph so the new learnings are immediately queryable by future milestone prompts.
+
+If the \`gsd_graph\` tool is not available, skip this step silently.
+`;
+}
+
+export function buildFrontmatter(ctx: FrontmatterContext): string {
+  const missingList = ctx.missingArtifacts.length > 0
+    ? ctx.missingArtifacts.map((a) => `  - ${a}`).join("\n")
+    : "  []";
+
+  const missingValue = ctx.missingArtifacts.length > 0
+    ? `\n${missingList}`
+    : " []";
+
+  return `---
+phase: ${ctx.milestoneId}
+phase_name: ${ctx.milestoneName}
+project: ${ctx.projectName}
+generated: ${ctx.generatedAt}
+counts:
+  decisions: ${ctx.counts.decisions}
+  lessons: ${ctx.counts.lessons}
+  patterns: ${ctx.counts.patterns}
+  surprises: ${ctx.counts.surprises}
+missing_artifacts:${missingValue}
+---`;
+}
+
+export function extractProjectName(basePath: string): string {
+  const projectMdPath = join(gsdRoot(basePath), "PROJECT.md");
+
+  if (existsSync(projectMdPath)) {
+    try {
+      const content = readFileSync(projectMdPath, "utf-8");
+      const match = content.match(/^name:\s*(.+)$/m);
+      if (match) return match[1].trim();
+    } catch {
+      // non-fatal
+    }
+  }
+
+  return basename(basePath);
+}
+
+// ─── Handler ──────────────────────────────────────────────────────────────────
+
+export async function handleExtractLearnings(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  const { milestoneId } = parseExtractLearningsArgs(args);
+
+  if (!milestoneId) {
+    ctx.ui.notify("Usage: /gsd extract-learnings <milestoneId>  (e.g. M001)", "warning");
+    return;
+  }
+
+  // projectRoot() throws GSDNoProjectError if no project found — intentional, handled by dispatcher
+  const basePath = projectRoot();
+  const milestoneDir = resolveMilestonePath(basePath, milestoneId);
+
+  if (!milestoneDir) {
+    ctx.ui.notify(`Milestone not found: ${milestoneId}`, "error");
+    return;
+  }
+
+  const artifacts = resolvePhaseArtifacts(milestoneDir, milestoneId);
+
+  if (artifacts.missingRequired.length > 0) {
+    ctx.ui.notify(
+      `Cannot extract learnings — required artefacts missing: ${artifacts.missingRequired.join(", ")}`,
+      "error",
+    );
+    return;
+  }
+
+  // Read required artefacts
+  const planContent = readFileSync(artifacts.plan!, "utf-8");
+  const summaryContent = readFileSync(artifacts.summary!, "utf-8");
+
+  // Read optional artefacts
+  const verificationContent = artifacts.verification
+    ? readFileSync(artifacts.verification, "utf-8")
+    : null;
+  const uatContent = artifacts.uat
+    ? readFileSync(artifacts.uat, "utf-8")
+    : null;
+
+  // Determine missing optional artefacts for context
+  const missingArtifacts: string[] = [];
+  if (!artifacts.verification) missingArtifacts.push(`${milestoneId}-VERIFICATION.md`);
+  if (!artifacts.uat) missingArtifacts.push(`${milestoneId}-UAT.md`);
+
+  // Extract milestone name from Plan H1 or fall back to milestoneId
+  const h1Match = planContent.match(/^#\s+(.+)$/m);
+  const milestoneName = h1Match?.[1]?.trim() ?? milestoneId;
+
+  const projectName = extractProjectName(basePath);
+  const outputPath = buildLearningsOutputPath(milestoneDir, milestoneId);
+  const relativeOutputPath = outputPath.replace(basePath + "/", "");
+
+  const prompt = buildExtractLearningsPrompt({
+    milestoneId,
+    milestoneName,
+    outputPath,
+    relativeOutputPath,
+    planContent,
+    summaryContent,
+    verificationContent,
+    uatContent,
+    missingArtifacts,
+    projectName,
+  });
+
+  ctx.ui.notify(`Extracting learnings for ${milestoneId}: "${milestoneName}"...`, "info");
+
+  pi.sendMessage(
+    { customType: "gsd-extract-learnings", content: prompt, display: false },
+    { triggerTurn: true },
+  );
+}

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -28,6 +28,11 @@ import { loadPrompt } from "./prompt-loader.js";
 const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/gsd-pi/latest";
 const UPDATE_FETCH_TIMEOUT_MS = 5000;
 
+function resolveInstallCommand(pkg: string): string {
+  if ('bun' in process.versions) return `bun add -g ${pkg}`;
+  return `npm install -g ${pkg}`;
+}
+
 async function fetchLatestVersionForCommand(): Promise<string | null> {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), UPDATE_FETCH_TIMEOUT_MS);
@@ -431,8 +436,9 @@ export async function handleUpdate(ctx: ExtensionCommandContext): Promise<void>
 
   ctx.ui.notify(`Updating: v${current} → v${latest}...`, "info");
 
+  const installCmd = resolveInstallCommand(`${NPM_PACKAGE}@latest`);
   try {
-    execSync(`npm install -g ${NPM_PACKAGE}@latest`, {
+    execSync(installCmd, {
       stdio: ["ignore", "pipe", "ignore"],
     });
     ctx.ui.notify(
@@ -441,7 +447,7 @@ export async function handleUpdate(ctx: ExtensionCommandContext): Promise<void>
     );
   } catch {
     ctx.ui.notify(
-      `Update failed. Try manually: npm install -g ${NPM_PACKAGE}@latest`,
+      `Update failed. Try manually: ${installCmd}`,
       "error",
     );
   }

package/src/resources/extensions/gsd/commands-maintenance.ts

@@ -488,7 +488,7 @@ export async function handleCleanupProjects(args: string, ctx: ExtensionCommandC
  * Prints counts of recovered items and the resulting project phase.
  */
 export async function handleRecover(ctx: ExtensionCommandContext, basePath: string): Promise<void> {
-  const { isDbAvailable: dbAvailable, _getAdapter, transaction: dbTransaction } = await import("./gsd-db.js");
+  const { isDbAvailable: dbAvailable, clearEngineHierarchy, transaction: dbTransaction } = await import("./gsd-db.js");
   const { migrateHierarchyToDb } = await import("./md-importer.js");
   const { invalidateStateCache } = await import("./state.js");
 
@@ -498,12 +498,12 @@ export async function handleRecover(ctx: ExtensionCommandContext, basePath: stri
   }
 
   try {
-    // 1. Delete + re-populate inside a single transaction for atomicity
-    const db = _getAdapter()!;
+    // 1. Delete + re-populate inside a single transaction for atomicity.
+    //    clearEngineHierarchy() uses transaction() internally but transaction()
+    //    is re-entrant, so wrapping in dbTransaction() keeps the whole
+    //    clear+repopulate atomic.
     const counts = dbTransaction(() => {
-      db.exec("DELETE FROM tasks");
-      db.exec("DELETE FROM slices");
-      db.exec("DELETE FROM milestones");
+      clearEngineHierarchy();
       return migrateHierarchyToDb(basePath);
     });