gsd-pi 2.28.0 → 2.29.0-dev.23d50d0

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

@@ -0,0 +1,102 @@
+/**
+ * GSD Config — Tool API key management.
+ *
+ * Contains: TOOL_KEYS, loadToolApiKeys, getConfigAuthStorage, handleConfig
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { AuthStorage } from "@gsd/pi-coding-agent";
+import { existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+/**
+ * Tool API key configurations.
+ * This is the source of truth for tool credentials - used by both the config wizard
+ * and session startup to load keys from auth.json into environment variables.
+ */
+export const TOOL_KEYS = [
+  { id: "tavily",   env: "TAVILY_API_KEY",   label: "Tavily Search",     hint: "tavily.com/app/api-keys" },
+  { id: "brave",    env: "BRAVE_API_KEY",     label: "Brave Search",      hint: "brave.com/search/api" },
+  { id: "context7", env: "CONTEXT7_API_KEY",  label: "Context7 Docs",     hint: "context7.com/dashboard" },
+  { id: "jina",     env: "JINA_API_KEY",      label: "Jina Page Extract", hint: "jina.ai/api" },
+  { id: "groq",     env: "GROQ_API_KEY",      label: "Groq Voice",        hint: "console.groq.com" },
+] as const;
+
+/**
+ * Load tool API keys from auth.json into environment variables.
+ * Called at session startup to ensure tools have access to their credentials.
+ */
+export function loadToolApiKeys(): void {
+  try {
+    const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+    if (!existsSync(authPath)) return;
+
+    const auth = AuthStorage.create(authPath);
+    for (const tool of TOOL_KEYS) {
+      const cred = auth.get(tool.id);
+      if (cred && cred.type === "api_key" && cred.key && !process.env[tool.env]) {
+        process.env[tool.env] = cred.key;
+      }
+    }
+  } catch {
+    // Failed to load tool keys — ignore, they can still be set via env vars
+  }
+}
+
+export function getConfigAuthStorage(): AuthStorage {
+  const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+  mkdirSync(dirname(authPath), { recursive: true });
+  return AuthStorage.create(authPath);
+}
+
+export async function handleConfig(ctx: ExtensionCommandContext): Promise<void> {
+  const auth = getConfigAuthStorage();
+
+  // Show current status
+  const statusLines = ["GSD Tool Configuration\n"];
+  for (const tool of TOOL_KEYS) {
+    const hasKey = !!process.env[tool.env] || !!(auth.get(tool.id) as { key?: string })?.key;
+    statusLines.push(`  ${hasKey ? "\u2713" : "\u2717"} ${tool.label}${hasKey ? "" : ` \u2014 get key at ${tool.hint}`}`);
+  }
+  ctx.ui.notify(statusLines.join("\n"), "info");
+
+  // Ask which tools to configure
+  const options = TOOL_KEYS.map(t => {
+    const hasKey = !!process.env[t.env] || !!(auth.get(t.id) as { key?: string })?.key;
+    return `${t.label} ${hasKey ? "(configured \u2713)" : "(not set)"}`;
+  });
+  options.push("(done)");
+
+  let changed = false;
+  while (true) {
+    const choice = await ctx.ui.select("Configure which tool? Press Escape when done.", options);
+    if (!choice || typeof choice !== "string" || choice === "(done)") break;
+
+    const toolIdx = TOOL_KEYS.findIndex(t => choice.startsWith(t.label));
+    if (toolIdx === -1) break;
+
+    const tool = TOOL_KEYS[toolIdx];
+    const input = await ctx.ui.input(
+      `API key for ${tool.label} (${tool.hint}):`,
+      "paste your key here",
+    );
+
+    if (input !== null && input !== undefined) {
+      const key = input.trim();
+      if (key) {
+        auth.set(tool.id, { type: "api_key", key });
+        process.env[tool.env] = key;
+        ctx.ui.notify(`${tool.label} key saved and activated.`, "info");
+        // Update option label
+        options[toolIdx] = `${tool.label} (configured \u2713)`;
+        changed = true;
+      }
+    }
+  }
+
+  if (changed) {
+    await ctx.waitForIdle();
+    await ctx.reload();
+    ctx.ui.notify("Configuration saved. Extensions reloaded with new keys.", "info");
+  }
+}

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

@@ -0,0 +1,394 @@
+/**
+ * GSD Command Handlers — fire-and-forget handlers that delegate to other modules.
+ *
+ * Contains: handleDoctor, handleSteer, handleCapture, handleTriage, handleKnowledge,
+ * handleRunHook, handleUpdate, handleSkillHealth
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { deriveState } from "./state.js";
+import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
+import { appendOverride, appendKnowledge } from "./files.js";
+import {
+  formatDoctorIssuesForPrompt,
+  formatDoctorReport,
+  runGSDDoctor,
+  selectDoctorScope,
+  filterDoctorIssues,
+} from "./doctor.js";
+import { isAutoActive } from "./auto.js";
+import { projectRoot } from "./commands.js";
+import { loadPrompt } from "./prompt-loader.js";
+
+export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
+  const workflow = readFileSync(workflowPath, "utf-8");
+  const prompt = loadPrompt("doctor-heal", {
+    doctorSummary: reportText,
+    structuredIssues,
+    scopeLabel: scope ?? "active milestone / blocking scope",
+    doctorCommandSuffix: scope ? ` ${scope}` : "",
+  });
+
+  const content = `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${prompt}`;
+
+  pi.sendMessage(
+    { customType: "gsd-doctor-heal", content, display: false },
+    { triggerTurn: true },
+  );
+}
+
+export async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+  const trimmed = args.trim();
+  const parts = trimmed ? trimmed.split(/\s+/) : [];
+  const mode = parts[0] === "fix" || parts[0] === "heal" || parts[0] === "audit" ? parts[0] : "doctor";
+  const requestedScope = mode === "doctor" ? parts[0] : parts[1];
+  const scope = await selectDoctorScope(projectRoot(), requestedScope);
+  const effectiveScope = mode === "audit" ? requestedScope : scope;
+  const report = await runGSDDoctor(projectRoot(), {
+    fix: mode === "fix" || mode === "heal",
+    scope: effectiveScope,
+  });
+
+  const reportText = formatDoctorReport(report, {
+    scope: effectiveScope,
+    includeWarnings: mode === "audit",
+    maxIssues: mode === "audit" ? 50 : 12,
+    title: mode === "audit" ? "GSD doctor audit." : mode === "heal" ? "GSD doctor heal prep." : undefined,
+  });
+
+  ctx.ui.notify(reportText, report.ok ? "info" : "warning");
+
+  if (mode === "heal") {
+    const unresolved = filterDoctorIssues(report.issues, {
+      scope: effectiveScope,
+      includeWarnings: true,
+    });
+    const actionable = unresolved.filter(issue => issue.severity === "error" || issue.code === "all_tasks_done_missing_slice_uat" || issue.code === "slice_checked_missing_uat");
+    if (actionable.length === 0) {
+      ctx.ui.notify("Doctor heal found nothing actionable to hand off to the LLM.", "info");
+      return;
+    }
+
+    const structuredIssues = formatDoctorIssuesForPrompt(actionable);
+    dispatchDoctorHeal(pi, effectiveScope, reportText, structuredIssues);
+    ctx.ui.notify(`Doctor heal dispatched ${actionable.length} issue(s) to the LLM.`, "info");
+  }
+}
+
+export async function handleSkillHealth(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const {
+    generateSkillHealthReport,
+    formatSkillHealthReport,
+    formatSkillDetail,
+  } = await import("./skill-health.js");
+
+  const basePath = projectRoot();
+
+  // /gsd skill-health <skill-name> — detail view
+  if (args && !args.startsWith("--")) {
+    const detail = formatSkillDetail(basePath, args);
+    ctx.ui.notify(detail, "info");
+    return;
+  }
+
+  // Parse flags
+  const staleMatch = args.match(/--stale\s+(\d+)/);
+  const staleDays = staleMatch ? parseInt(staleMatch[1], 10) : undefined;
+  const decliningOnly = args.includes("--declining");
+
+  const report = generateSkillHealthReport(basePath, staleDays);
+
+  if (decliningOnly) {
+    if (report.decliningSkills.length === 0) {
+      ctx.ui.notify("No skills flagged for declining performance.", "info");
+      return;
+    }
+    const filtered = {
+      ...report,
+      skills: report.skills.filter(s => s.flagged),
+    };
+    ctx.ui.notify(formatSkillHealthReport(filtered), "info");
+    return;
+  }
+
+  ctx.ui.notify(formatSkillHealthReport(report), "info");
+}
+
+export 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");
+}
+
+export 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: loadTriagePrompt } = await import("./prompt-loader.js");
+  const prompt = loadTriagePrompt("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 },
+  );
+}
+
+export async function handleSteer(change: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+  const basePath = process.cwd();
+  const state = await deriveState(basePath);
+  const mid = state.activeMilestone?.id ?? "none";
+  const sid = state.activeSlice?.id ?? "none";
+  const tid = state.activeTask?.id ?? "none";
+  const appliedAt = `${mid}/${sid}/${tid}`;
+  await appendOverride(basePath, change, appliedAt);
+
+  if (isAutoActive()) {
+    pi.sendMessage({
+      customType: "gsd-hard-steer",
+      content: [
+        "HARD STEER — User override registered.",
+        "",
+        `**Override:** ${change}`,
+        "",
+        "This override has been saved to `.gsd/OVERRIDES.md` and will be injected into all future task prompts.",
+        "A document rewrite unit will run before the next task to propagate this change across all active plan documents.",
+        "",
+        "If you are mid-task, finish your current work respecting this override. The next dispatched unit will be a document rewrite.",
+      ].join("\n"),
+      display: false,
+    }, { triggerTurn: true });
+    ctx.ui.notify(`Override registered: "${change}". Will be applied before next task dispatch.`, "info");
+  } else {
+    pi.sendMessage({
+      customType: "gsd-hard-steer",
+      content: [
+        "HARD STEER — User override registered.",
+        "",
+        `**Override:** ${change}`,
+        "",
+        "This override has been saved to `.gsd/OVERRIDES.md`.",
+        "Before continuing, read `.gsd/OVERRIDES.md` and update the current plan documents to reflect this change.",
+        "Focus on: active slice plan, incomplete task plans, and DECISIONS.md.",
+      ].join("\n"),
+      display: false,
+    }, { triggerTurn: true });
+    ctx.ui.notify(`Override registered: "${change}". Update plan documents to reflect this change.`, "info");
+  }
+}
+
+export async function handleKnowledge(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const parts = args.split(/\s+/);
+  const typeArg = parts[0]?.toLowerCase();
+
+  if (!typeArg || !["rule", "pattern", "lesson"].includes(typeArg)) {
+    ctx.ui.notify(
+      "Usage: /gsd knowledge <rule|pattern|lesson> <description>\nExample: /gsd knowledge rule Use real DB for integration tests",
+      "warning",
+    );
+    return;
+  }
+
+  const entryText = parts.slice(1).join(" ").trim();
+  if (!entryText) {
+    ctx.ui.notify(`Usage: /gsd knowledge ${typeArg} <description>`, "warning");
+    return;
+  }
+
+  const type = typeArg as "rule" | "pattern" | "lesson";
+  const basePath = process.cwd();
+  const state = await deriveState(basePath);
+  const scope = state.activeMilestone?.id
+    ? `${state.activeMilestone.id}${state.activeSlice ? `/${state.activeSlice.id}` : ""}`
+    : "global";
+
+  await appendKnowledge(basePath, type, entryText, scope);
+  ctx.ui.notify(`Added ${type} to KNOWLEDGE.md: "${entryText}"`, "success");
+}
+
+export async function handleRunHook(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+  const parts = args.trim().split(/\s+/);
+  if (parts.length < 3) {
+    ctx.ui.notify(`Usage: /gsd run-hook <hook-name> <unit-type> <unit-id>
+
+Unit types:
+  execute-task   - Task execution (unit-id: M001/S01/T01)
+  plan-slice     - Slice planning (unit-id: M001/S01)
+  research-milestone - Milestone research (unit-id: M001)
+  complete-slice - Slice completion (unit-id: M001/S01)
+  complete-milestone - Milestone completion (unit-id: M001)
+
+Examples:
+  /gsd run-hook code-review execute-task M001/S01/T01
+  /gsd run-hook lint-check plan-slice M001/S01`, "warning");
+    return;
+  }
+
+  const [hookName, unitType, unitId] = parts;
+  const basePath = projectRoot();
+
+  // Import the hook trigger function
+  const { triggerHookManually, formatHookStatus, getHookStatus } = await import("./post-unit-hooks.js");
+  const { dispatchHookUnit } = await import("./auto.js");
+
+  // Check if the hook exists
+  const hooks = getHookStatus();
+  const hookExists = hooks.some(h => h.name === hookName);
+  if (!hookExists) {
+    ctx.ui.notify(`Hook "${hookName}" not found. Configured hooks:\n${formatHookStatus()}`, "error");
+    return;
+  }
+
+  // Validate unit ID format
+  const unitIdPattern = /^M\d{3}\/S\d{2,3}\/T\d{2,3}$/;
+  if (!unitIdPattern.test(unitId)) {
+    ctx.ui.notify(`Invalid unit ID format: "${unitId}". Expected format: M004/S04/T03`, "warning");
+    return;
+  }
+
+  // Trigger the hook manually
+  const hookUnit = triggerHookManually(hookName, unitType, unitId, basePath);
+  if (!hookUnit) {
+    ctx.ui.notify(`Failed to trigger hook "${hookName}". The hook may be disabled or not configured for unit type "${unitType}".`, "error");
+    return;
+  }
+
+  ctx.ui.notify(`Manually triggering hook: ${hookName} for ${unitType} ${unitId}`, "info");
+
+  // Dispatch the hook unit directly, bypassing normal pre-dispatch hooks
+  const success = await dispatchHookUnit(
+    ctx,
+    pi,
+    hookName,
+    unitType,
+    unitId,
+    hookUnit.prompt,
+    hookUnit.model,
+    basePath,
+  );
+
+  if (!success) {
+    ctx.ui.notify("Failed to dispatch hook. Auto-mode may have been cancelled.", "error");
+  }
+}
+
+// ─── Self-update handler ────────────────────────────────────────────────────
+
+function compareSemverLocal(a: string, b: string): number {
+  const pa = a.split('.').map(Number)
+  const pb = b.split('.').map(Number)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const va = pa[i] || 0
+    const vb = pb[i] || 0
+    if (va > vb) return 1
+    if (va < vb) return -1
+  }
+  return 0
+}
+
+export async function handleUpdate(ctx: ExtensionCommandContext): Promise<void> {
+  const { execSync } = await import("node:child_process");
+
+  const NPM_PACKAGE = "gsd-pi";
+  const current = process.env.GSD_VERSION || "0.0.0";
+
+  ctx.ui.notify(`Current version: v${current}\nChecking npm registry...`, "info");
+
+  let latest: string;
+  try {
+    latest = execSync(`npm view ${NPM_PACKAGE} version`, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    ctx.ui.notify("Failed to reach npm registry. Check your network connection.", "error");
+    return;
+  }
+
+  if (compareSemverLocal(latest, current) <= 0) {
+    ctx.ui.notify(`Already up to date (v${current}).`, "info");
+    return;
+  }
+
+  ctx.ui.notify(`Updating: v${current} → v${latest}...`, "info");
+
+  try {
+    execSync(`npm install -g ${NPM_PACKAGE}@latest`, {
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    ctx.ui.notify(
+      `Updated to v${latest}. Restart your GSD session to use the new version.`,
+      "info",
+    );
+  } catch {
+    ctx.ui.notify(
+      `Update failed. Try manually: npm install -g ${NPM_PACKAGE}@latest`,
+      "error",
+    );
+  }
+}

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

@@ -0,0 +1,90 @@
+/**
+ * GSD Inspect — SQLite DB diagnostics.
+ *
+ * Contains: InspectData type, formatInspectOutput, handleInspect
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+export interface InspectData {
+  schemaVersion: number | null;
+  counts: { decisions: number; requirements: number; artifacts: number };
+  recentDecisions: Array<{ id: string; decision: string; choice: string }>;
+  recentRequirements: Array<{ id: string; status: string; description: string }>;
+}
+
+export function formatInspectOutput(data: InspectData): string {
+  const lines: string[] = [];
+  lines.push("=== GSD Database Inspect ===");
+  lines.push(`Schema version: ${data.schemaVersion ?? "unknown"}`);
+  lines.push("");
+  lines.push(`Decisions:    ${data.counts.decisions}`);
+  lines.push(`Requirements: ${data.counts.requirements}`);
+  lines.push(`Artifacts:    ${data.counts.artifacts}`);
+
+  if (data.recentDecisions.length > 0) {
+    lines.push("");
+    lines.push("Recent decisions:");
+    for (const d of data.recentDecisions) {
+      lines.push(`  ${d.id}: ${d.decision} → ${d.choice}`);
+    }
+  }
+
+  if (data.recentRequirements.length > 0) {
+    lines.push("");
+    lines.push("Recent requirements:");
+    for (const r of data.recentRequirements) {
+      lines.push(`  ${r.id} [${r.status}]: ${r.description}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export async function handleInspect(ctx: ExtensionCommandContext): Promise<void> {
+  try {
+    const { isDbAvailable, _getAdapter } = await import("./gsd-db.js");
+
+    if (!isDbAvailable()) {
+      ctx.ui.notify("No GSD database available. Run /gsd auto to create one.", "info");
+      return;
+    }
+
+    const adapter = _getAdapter();
+    if (!adapter) {
+      ctx.ui.notify("No GSD database available. Run /gsd auto to create one.", "info");
+      return;
+    }
+
+    const versionRow = adapter.prepare("SELECT MAX(version) as v FROM schema_version").get();
+    const schemaVersion = versionRow ? (versionRow["v"] as number | null) : null;
+
+    const dCount = adapter.prepare("SELECT count(*) as cnt FROM decisions").get();
+    const rCount = adapter.prepare("SELECT count(*) as cnt FROM requirements").get();
+    const aCount = adapter.prepare("SELECT count(*) as cnt FROM artifacts").get();
+
+    const recentDecisions = adapter
+      .prepare("SELECT id, decision, choice FROM decisions ORDER BY seq DESC LIMIT 5")
+      .all() as Array<{ id: string; decision: string; choice: string }>;
+
+    const recentRequirements = adapter
+      .prepare("SELECT id, status, description FROM requirements ORDER BY id DESC LIMIT 5")
+      .all() as Array<{ id: string; status: string; description: string }>;
+
+    const data: InspectData = {
+      schemaVersion,
+      counts: {
+        decisions: (dCount?.["cnt"] as number) ?? 0,
+        requirements: (rCount?.["cnt"] as number) ?? 0,
+        artifacts: (aCount?.["cnt"] as number) ?? 0,
+      },
+      recentDecisions,
+      recentRequirements,
+    };
+
+    ctx.ui.notify(formatInspectOutput(data), "info");
+  } catch (err) {
+    process.stderr.write(`gsd-db: /gsd inspect failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    ctx.ui.notify("Failed to inspect GSD database. Check stderr for details.", "error");
+  }
+}