gsd-pi 2.43.0 → 2.44.0-dev.0b97ffd

package/src/resources/extensions/gsd/tools/complete-slice.ts

@@ -0,0 +1,300 @@
+/**
+ * complete-slice handler — the core operation behind gsd_slice_complete.
+ *
+ * Validates inputs, checks all tasks are complete, writes slice row to DB in
+ * a transaction, then (outside the transaction) renders SUMMARY.md + UAT.md
+ * to disk, toggles the roadmap checkbox, stores rendered markdown in DB for
+ * D004 recovery, and invalidates caches.
+ */
+
+import { join } from "node:path";
+import { mkdirSync } from "node:fs";
+
+import type { CompleteSliceParams } from "../types.js";
+import {
+  transaction,
+  insertMilestone,
+  insertSlice,
+  getSliceTasks,
+  updateSliceStatus,
+  _getAdapter,
+} from "../gsd-db.js";
+import { resolveSliceFile, resolveSlicePath, clearPathCache } from "../paths.js";
+import { saveFile, clearParseCache } from "../files.js";
+import { invalidateStateCache } from "../state.js";
+import { renderRoadmapCheckboxes } from "../markdown-renderer.js";
+
+export interface CompleteSliceResult {
+  sliceId: string;
+  milestoneId: string;
+  summaryPath: string;
+  uatPath: string;
+}
+
+/**
+ * Render slice summary markdown matching the template format.
+ * YAML frontmatter uses snake_case keys for parseSummary() compatibility.
+ */
+function renderSliceSummaryMarkdown(params: CompleteSliceParams): string {
+  const now = new Date().toISOString();
+
+  const providesYaml = params.provides.length > 0
+    ? params.provides.map(p => `  - ${p}`).join("\n")
+    : "  - (none)";
+
+  const requiresYaml = params.requires.length > 0
+    ? params.requires.map(r => `  - slice: ${r.slice}\n    provides: ${r.provides}`).join("\n")
+    : "  []";
+
+  const affectsYaml = params.affects.length > 0
+    ? params.affects.map(a => `  - ${a}`).join("\n")
+    : "  []";
+
+  const keyFilesYaml = params.keyFiles.length > 0
+    ? params.keyFiles.map(f => `  - ${f}`).join("\n")
+    : "  - (none)";
+
+  const keyDecisionsYaml = params.keyDecisions.length > 0
+    ? params.keyDecisions.map(d => `  - ${d}`).join("\n")
+    : "  - (none)";
+
+  const patternsYaml = params.patternsEstablished.length > 0
+    ? params.patternsEstablished.map(p => `  - ${p}`).join("\n")
+    : "  - (none)";
+
+  const observabilityYaml = params.observabilitySurfaces.length > 0
+    ? params.observabilitySurfaces.map(o => `  - ${o}`).join("\n")
+    : "  - none";
+
+  const drillDownYaml = params.drillDownPaths.length > 0
+    ? params.drillDownPaths.map(d => `  - ${d}`).join("\n")
+    : "  []";
+
+  // Requirements sections
+  const reqAdvanced = params.requirementsAdvanced.length > 0
+    ? params.requirementsAdvanced.map(r => `- ${r.id} — ${r.how}`).join("\n")
+    : "None.";
+
+  const reqValidated = params.requirementsValidated.length > 0
+    ? params.requirementsValidated.map(r => `- ${r.id} — ${r.proof}`).join("\n")
+    : "None.";
+
+  const reqSurfaced = params.requirementsSurfaced.length > 0
+    ? params.requirementsSurfaced.map(r => `- ${r}`).join("\n")
+    : "None.";
+
+  const reqInvalidated = params.requirementsInvalidated.length > 0
+    ? params.requirementsInvalidated.map(r => `- ${r.id} — ${r.what}`).join("\n")
+    : "None.";
+
+  // Files modified
+  const filesMod = params.filesModified.length > 0
+    ? params.filesModified.map(f => `- \`${f.path}\` — ${f.description}`).join("\n")
+    : "None.";
+
+  return `---
+id: ${params.sliceId}
+parent: ${params.milestoneId}
+milestone: ${params.milestoneId}
+provides:
+${providesYaml}
+requires:
+${requiresYaml}
+affects:
+${affectsYaml}
+key_files:
+${keyFilesYaml}
+key_decisions:
+${keyDecisionsYaml}
+patterns_established:
+${patternsYaml}
+observability_surfaces:
+${observabilityYaml}
+drill_down_paths:
+${drillDownYaml}
+duration: ""
+verification_result: passed
+completed_at: ${now}
+blocker_discovered: false
+---
+
+# ${params.sliceId}: ${params.sliceTitle}
+
+**${params.oneLiner}**
+
+## What Happened
+
+${params.narrative}
+
+## Verification
+
+${params.verification}
+
+## Requirements Advanced
+
+${reqAdvanced}
+
+## Requirements Validated
+
+${reqValidated}
+
+## New Requirements Surfaced
+
+${reqSurfaced}
+
+## Requirements Invalidated or Re-scoped
+
+${reqInvalidated}
+
+## Deviations
+
+${params.deviations || "None."}
+
+## Known Limitations
+
+${params.knownLimitations || "None."}
+
+## Follow-ups
+
+${params.followUps || "None."}
+
+## Files Created/Modified
+
+${filesMod}
+`;
+}
+
+/**
+ * Render UAT markdown matching the template format.
+ */
+function renderUatMarkdown(params: CompleteSliceParams): string {
+  return `# ${params.sliceId}: ${params.sliceTitle} — UAT
+
+**Milestone:** ${params.milestoneId}
+**Written:** ${new Date().toISOString()}
+
+${params.uatContent}
+`;
+}
+
+/**
+ * Handle the complete_slice operation end-to-end.
+ *
+ * 1. Validate required fields
+ * 2. Verify all tasks are complete
+ * 3. Write DB in a transaction (milestone, slice upsert, status update)
+ * 4. Render SUMMARY.md + UAT.md to disk
+ * 5. Toggle roadmap checkbox
+ * 6. Store rendered markdown back in DB (for D004 recovery)
+ * 7. Invalidate caches
+ */
+export async function handleCompleteSlice(
+  params: CompleteSliceParams,
+  basePath: string,
+): Promise<CompleteSliceResult | { error: string }> {
+  // ── Validate required fields ────────────────────────────────────────────
+  if (!params.sliceId || typeof params.sliceId !== "string" || params.sliceId.trim() === "") {
+    return { error: "sliceId is required and must be a non-empty string" };
+  }
+  if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
+    return { error: "milestoneId is required and must be a non-empty string" };
+  }
+
+  // ── Verify all tasks are complete ───────────────────────────────────────
+  const tasks = getSliceTasks(params.milestoneId, params.sliceId);
+  if (tasks.length === 0) {
+    return { error: `no tasks found for slice ${params.sliceId} in milestone ${params.milestoneId}` };
+  }
+
+  const incompleteTasks = tasks.filter(t => t.status !== "complete");
+  if (incompleteTasks.length > 0) {
+    const incompleteIds = incompleteTasks.map(t => `${t.id} (status: ${t.status})`).join(", ");
+    return { error: `incomplete tasks: ${incompleteIds}` };
+  }
+
+  // ── DB writes inside a transaction ──────────────────────────────────────
+  const completedAt = new Date().toISOString();
+
+  transaction(() => {
+    insertMilestone({ id: params.milestoneId });
+    insertSlice({ id: params.sliceId, milestoneId: params.milestoneId });
+    updateSliceStatus(params.milestoneId, params.sliceId, "complete", completedAt);
+  });
+
+  // ── Filesystem operations (outside transaction) ─────────────────────────
+  // If disk render fails, roll back the DB status so deriveState() and
+  // verifyExpectedArtifact() stay consistent (both say "not done").
+
+  // Render summary markdown
+  const summaryMd = renderSliceSummaryMarkdown(params);
+
+  // Resolve and write summary to disk
+  let summaryPath: string;
+  const sliceDir = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+  if (sliceDir) {
+    summaryPath = join(sliceDir, `${params.sliceId}-SUMMARY.md`);
+  } else {
+    // Slice dir doesn't exist on disk yet — build path manually and ensure dirs
+    const gsdDir = join(basePath, ".gsd");
+    const manualSliceDir = join(gsdDir, "milestones", params.milestoneId, "slices", params.sliceId);
+    mkdirSync(manualSliceDir, { recursive: true });
+    summaryPath = join(manualSliceDir, `${params.sliceId}-SUMMARY.md`);
+  }
+
+  const uatMd = renderUatMarkdown(params);
+  const uatPath = summaryPath.replace(/-SUMMARY\.md$/, "-UAT.md");
+
+  try {
+    await saveFile(summaryPath, summaryMd);
+    await saveFile(uatPath, uatMd);
+
+    // Toggle roadmap checkbox via renderer module
+    const roadmapToggled = await renderRoadmapCheckboxes(basePath, params.milestoneId);
+    if (!roadmapToggled) {
+      process.stderr.write(
+        `gsd-db: complete_slice — could not find roadmap for ${params.milestoneId}, skipping checkbox toggle\n`,
+      );
+    }
+  } catch (renderErr) {
+    // Disk render failed — roll back DB status so state stays consistent
+    process.stderr.write(
+      `gsd-db: complete_slice — disk render failed, rolling back DB status: ${(renderErr as Error).message}\n`,
+    );
+    const rollbackAdapter = _getAdapter();
+    if (rollbackAdapter) {
+      rollbackAdapter.prepare(
+        `UPDATE slices SET status = 'pending' WHERE milestone_id = :mid AND id = :sid`,
+      ).run({
+        ":mid": params.milestoneId,
+        ":sid": params.sliceId,
+      });
+    }
+    invalidateStateCache();
+    return { error: `disk render failed: ${(renderErr as Error).message}` };
+  }
+
+  // Store rendered markdown in DB for D004 recovery
+  const adapter = _getAdapter();
+  if (adapter) {
+    adapter.prepare(
+      `UPDATE slices SET full_summary_md = :summary_md, full_uat_md = :uat_md WHERE milestone_id = :mid AND id = :sid`,
+    ).run({
+      ":summary_md": summaryMd,
+      ":uat_md": uatMd,
+      ":mid": params.milestoneId,
+      ":sid": params.sliceId,
+    });
+  }
+
+  // Invalidate all caches
+  invalidateStateCache();
+  clearPathCache();
+  clearParseCache();
+
+  return {
+    sliceId: params.sliceId,
+    milestoneId: params.milestoneId,
+    summaryPath,
+    uatPath,
+  };
+}

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -0,0 +1,245 @@
+/**
+ * complete-task handler — the core operation behind gsd_complete_task.
+ *
+ * Validates inputs, writes task row to DB in a transaction, then (outside
+ * the transaction) renders SUMMARY.md to disk, toggles the plan checkbox,
+ * stores the rendered markdown in the DB for D004 recovery, and invalidates
+ * caches.
+ */
+
+import { join } from "node:path";
+import { mkdirSync, existsSync } from "node:fs";
+
+import type { CompleteTaskParams } from "../types.js";
+import {
+  transaction,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  insertVerificationEvidence,
+  _getAdapter,
+} from "../gsd-db.js";
+import { resolveSliceFile, resolveTasksDir, clearPathCache } from "../paths.js";
+import { saveFile, clearParseCache } from "../files.js";
+import { invalidateStateCache } from "../state.js";
+import { renderPlanCheckboxes } from "../markdown-renderer.js";
+
+export interface CompleteTaskResult {
+  taskId: string;
+  sliceId: string;
+  milestoneId: string;
+  summaryPath: string;
+}
+
+/**
+ * Render task summary markdown matching the template format.
+ * YAML frontmatter uses snake_case keys for parseSummary() compatibility.
+ */
+function renderSummaryMarkdown(params: CompleteTaskParams): string {
+  const now = new Date().toISOString();
+  const keyFilesYaml = params.keyFiles.length > 0
+    ? params.keyFiles.map(f => `  - ${f}`).join("\n")
+    : "  - (none)";
+  const keyDecisionsYaml = params.keyDecisions.length > 0
+    ? params.keyDecisions.map(d => `  - ${d}`).join("\n")
+    : "  - (none)";
+
+  // Build verification evidence table rows
+  let evidenceTable = "| # | Command | Exit Code | Verdict | Duration |\n|---|---------|-----------|---------|----------|\n";
+  if (params.verificationEvidence.length > 0) {
+    params.verificationEvidence.forEach((e, i) => {
+      evidenceTable += `| ${i + 1} | \`${e.command}\` | ${e.exitCode} | ${e.verdict} | ${e.durationMs}ms |\n`;
+    });
+  } else {
+    evidenceTable += "| — | No verification commands discovered | — | — | — |\n";
+  }
+
+  // Determine verification_result from evidence
+  const allPassed = params.verificationEvidence.length > 0 &&
+    params.verificationEvidence.every(e => e.exitCode === 0 || e.verdict.includes("✅") || e.verdict.toLowerCase().includes("pass"));
+  const verificationResult = allPassed ? "passed" : (params.verificationEvidence.length === 0 ? "untested" : "mixed");
+
+  // Extract a title from the oneLiner or taskId
+  const title = params.oneLiner || params.taskId;
+
+  return `---
+id: ${params.taskId}
+parent: ${params.sliceId}
+milestone: ${params.milestoneId}
+key_files:
+${keyFilesYaml}
+key_decisions:
+${keyDecisionsYaml}
+duration: ""
+verification_result: ${verificationResult}
+completed_at: ${now}
+blocker_discovered: ${params.blockerDiscovered}
+---
+
+# ${params.taskId}: ${title}
+
+**${params.oneLiner}**
+
+## What Happened
+
+${params.narrative}
+
+## Verification
+
+${params.verification}
+
+## Verification Evidence
+
+${evidenceTable}
+
+## Deviations
+
+${params.deviations || "None."}
+
+## Known Issues
+
+${params.knownIssues || "None."}
+
+## Files Created/Modified
+
+${params.keyFiles.map(f => `- \`${f}\``).join("\n") || "None."}
+`;
+}
+
+/**
+ * Handle the complete_task operation end-to-end.
+ *
+ * 1. Validate required fields
+ * 2. Write DB in a transaction (milestone, slice, task, verification evidence)
+ * 3. Render SUMMARY.md to disk
+ * 4. Toggle plan checkbox
+ * 5. Store rendered markdown back in DB (for D004 recovery)
+ * 6. Invalidate caches
+ */
+export async function handleCompleteTask(
+  params: CompleteTaskParams,
+  basePath: string,
+): Promise<CompleteTaskResult | { error: string }> {
+  // ── Validate required fields ────────────────────────────────────────────
+  if (!params.taskId || typeof params.taskId !== "string" || params.taskId.trim() === "") {
+    return { error: "taskId is required and must be a non-empty string" };
+  }
+  if (!params.sliceId || typeof params.sliceId !== "string" || params.sliceId.trim() === "") {
+    return { error: "sliceId is required and must be a non-empty string" };
+  }
+  if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
+    return { error: "milestoneId is required and must be a non-empty string" };
+  }
+
+  // ── DB writes inside a transaction ──────────────────────────────────────
+  const completedAt = new Date().toISOString();
+
+  transaction(() => {
+    insertMilestone({ id: params.milestoneId });
+    insertSlice({ id: params.sliceId, milestoneId: params.milestoneId });
+    insertTask({
+      id: params.taskId,
+      sliceId: params.sliceId,
+      milestoneId: params.milestoneId,
+      title: params.oneLiner,
+      status: "complete",
+      oneLiner: params.oneLiner,
+      narrative: params.narrative,
+      verificationResult: params.verification,
+      duration: "",
+      blockerDiscovered: params.blockerDiscovered,
+      deviations: params.deviations,
+      knownIssues: params.knownIssues,
+      keyFiles: params.keyFiles,
+      keyDecisions: params.keyDecisions,
+    });
+
+    for (const evidence of params.verificationEvidence) {
+      insertVerificationEvidence({
+        taskId: params.taskId,
+        sliceId: params.sliceId,
+        milestoneId: params.milestoneId,
+        command: evidence.command,
+        exitCode: evidence.exitCode,
+        verdict: evidence.verdict,
+        durationMs: evidence.durationMs,
+      });
+    }
+  });
+
+  // ── Filesystem operations (outside transaction) ─────────────────────────
+  // If disk render fails, roll back the DB status so deriveState() and
+  // verifyExpectedArtifact() stay consistent (both say "not done").
+
+  // Render summary markdown
+  const summaryMd = renderSummaryMarkdown(params);
+
+  // Resolve and write summary to disk
+  let summaryPath: string;
+  const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+  if (tasksDir) {
+    summaryPath = join(tasksDir, `${params.taskId}-SUMMARY.md`);
+  } else {
+    // Tasks dir doesn't exist on disk yet — build path manually and ensure dirs
+    const gsdDir = join(basePath, ".gsd");
+    const manualTasksDir = join(gsdDir, "milestones", params.milestoneId, "slices", params.sliceId, "tasks");
+    mkdirSync(manualTasksDir, { recursive: true });
+    summaryPath = join(manualTasksDir, `${params.taskId}-SUMMARY.md`);
+  }
+
+  try {
+    await saveFile(summaryPath, summaryMd);
+
+    // Toggle plan checkbox via renderer module
+    const planPath = resolveSliceFile(basePath, params.milestoneId, params.sliceId, "PLAN");
+    if (planPath) {
+      await renderPlanCheckboxes(basePath, params.milestoneId, params.sliceId);
+    } else {
+      process.stderr.write(
+        `gsd-db: complete_task — could not find plan file for ${params.sliceId}/${params.milestoneId}, skipping checkbox toggle\n`,
+      );
+    }
+  } catch (renderErr) {
+    // Disk render failed — roll back DB status so state stays consistent
+    process.stderr.write(
+      `gsd-db: complete_task — disk render failed, rolling back DB status: ${(renderErr as Error).message}\n`,
+    );
+    const rollbackAdapter = _getAdapter();
+    if (rollbackAdapter) {
+      rollbackAdapter.prepare(
+        `UPDATE tasks SET status = 'pending' WHERE milestone_id = :mid AND slice_id = :sid AND id = :tid`,
+      ).run({
+        ":mid": params.milestoneId,
+        ":sid": params.sliceId,
+        ":tid": params.taskId,
+      });
+    }
+    invalidateStateCache();
+    return { error: `disk render failed: ${(renderErr as Error).message}` };
+  }
+
+  // Store rendered markdown in DB for D004 recovery
+  const adapter = _getAdapter();
+  if (adapter) {
+    adapter.prepare(
+      `UPDATE tasks SET full_summary_md = :md WHERE milestone_id = :mid AND slice_id = :sid AND id = :tid`,
+    ).run({
+      ":md": summaryMd,
+      ":mid": params.milestoneId,
+      ":sid": params.sliceId,
+      ":tid": params.taskId,
+    });
+  }
+
+  // Invalidate all caches
+  invalidateStateCache();
+  clearPathCache();
+  clearParseCache();
+
+  return {
+    taskId: params.taskId,
+    sliceId: params.sliceId,
+    milestoneId: params.milestoneId,
+    summaryPath,
+  };
+}