gsd-pi 2.61.0-dev.7aed0bf → 2.62.0-dev.a987556

package/packages/mcp-server/src/readers/doctor-lite.ts

@@ -0,0 +1,225 @@
+// GSD MCP Server — lightweight structural health checks
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { existsSync, readFileSync } from 'node:fs';
+import {
+  resolveGsdRoot,
+  resolveRootFile,
+  findMilestoneIds,
+  resolveMilestoneFile,
+  resolveMilestoneDir,
+  findSliceIds,
+  resolveSliceFile,
+  findTaskFiles,
+} from './paths.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type Severity = 'info' | 'warning' | 'error';
+
+export interface DoctorIssue {
+  severity: Severity;
+  code: string;
+  scope: 'project' | 'milestone' | 'slice' | 'task';
+  unitId: string;
+  message: string;
+  file?: string;
+}
+
+export interface DoctorResult {
+  ok: boolean;
+  issues: DoctorIssue[];
+  counts: { error: number; warning: number; info: number };
+}
+
+// ---------------------------------------------------------------------------
+// Check implementations
+// ---------------------------------------------------------------------------
+
+function checkProjectLevel(gsdRoot: string, issues: DoctorIssue[]): void {
+  // PROJECT.md should exist
+  const projectPath = resolveRootFile(gsdRoot, 'PROJECT.md');
+  if (!existsSync(projectPath)) {
+    issues.push({
+      severity: 'warning',
+      code: 'missing_project_md',
+      scope: 'project',
+      unitId: '',
+      message: 'PROJECT.md is missing — project lacks a description',
+      file: projectPath,
+    });
+  }
+
+  // STATE.md should exist if milestones exist
+  const milestones = findMilestoneIds(gsdRoot);
+  if (milestones.length > 0) {
+    const statePath = resolveRootFile(gsdRoot, 'STATE.md');
+    if (!existsSync(statePath)) {
+      issues.push({
+        severity: 'warning',
+        code: 'missing_state_md',
+        scope: 'project',
+        unitId: '',
+        message: 'STATE.md is missing — run /gsd status to regenerate',
+        file: statePath,
+      });
+    }
+  }
+}
+
+function checkMilestoneLevel(gsdRoot: string, mid: string, issues: DoctorIssue[]): void {
+  const mDir = resolveMilestoneDir(gsdRoot, mid);
+  if (!mDir) {
+    issues.push({
+      severity: 'error',
+      code: 'missing_milestone_dir',
+      scope: 'milestone',
+      unitId: mid,
+      message: `Milestone directory for ${mid} not found`,
+    });
+    return;
+  }
+
+  // CONTEXT.md should exist
+  const ctxPath = resolveMilestoneFile(gsdRoot, mid, 'CONTEXT');
+  if (!ctxPath || !existsSync(ctxPath)) {
+    // Check for draft
+    const draftPath = resolveMilestoneFile(gsdRoot, mid, 'CONTEXT-DRAFT');
+    if (!draftPath || !existsSync(draftPath)) {
+      issues.push({
+        severity: 'warning',
+        code: 'missing_context',
+        scope: 'milestone',
+        unitId: mid,
+        message: `${mid} has no CONTEXT.md — milestone lacks defined scope`,
+      });
+    }
+  }
+
+  // ROADMAP.md should exist if slices exist
+  const sliceIds = findSliceIds(gsdRoot, mid);
+  if (sliceIds.length > 0) {
+    const roadmapPath = resolveMilestoneFile(gsdRoot, mid, 'ROADMAP');
+    if (!roadmapPath || !existsSync(roadmapPath)) {
+      issues.push({
+        severity: 'warning',
+        code: 'missing_roadmap',
+        scope: 'milestone',
+        unitId: mid,
+        message: `${mid} has ${sliceIds.length} slices but no ROADMAP.md`,
+      });
+    }
+  }
+
+  // Check if all slices done but no SUMMARY
+  if (sliceIds.length > 0) {
+    const allDone = sliceIds.every((sid) => {
+      const tasks = findTaskFiles(gsdRoot, mid, sid);
+      return tasks.length > 0 && tasks.every((t) => t.hasSummary);
+    });
+    const summaryPath = resolveMilestoneFile(gsdRoot, mid, 'SUMMARY');
+    if (allDone && (!summaryPath || !existsSync(summaryPath))) {
+      issues.push({
+        severity: 'error',
+        code: 'all_slices_done_missing_summary',
+        scope: 'milestone',
+        unitId: mid,
+        message: `${mid} has all slices completed but no SUMMARY.md`,
+      });
+    }
+  }
+}
+
+function checkSliceLevel(
+  gsdRoot: string, mid: string, sid: string, issues: DoctorIssue[],
+): void {
+  const unitId = `${mid}/${sid}`;
+
+  // PLAN.md should exist
+  const planPath = resolveSliceFile(gsdRoot, mid, sid, 'PLAN');
+  if (!planPath || !existsSync(planPath)) {
+    issues.push({
+      severity: 'error',
+      code: 'missing_slice_plan',
+      scope: 'slice',
+      unitId,
+      message: `${unitId} has no PLAN.md`,
+    });
+  }
+
+  // Tasks should have plans
+  const tasks = findTaskFiles(gsdRoot, mid, sid);
+  for (const task of tasks) {
+    const taskUnitId = `${unitId}/${task.id}`;
+    if (!task.hasPlan) {
+      issues.push({
+        severity: 'warning',
+        code: 'missing_task_plan',
+        scope: 'task',
+        unitId: taskUnitId,
+        message: `${taskUnitId} has a summary but no plan file`,
+      });
+    }
+  }
+
+  // Check for empty slice (directory exists but no tasks or plan)
+  if (tasks.length === 0 && (!planPath || !existsSync(planPath))) {
+    issues.push({
+      severity: 'warning',
+      code: 'empty_slice',
+      scope: 'slice',
+      unitId,
+      message: `${unitId} has no plan and no tasks — may be abandoned`,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function runDoctorLite(projectDir: string, scope?: string): DoctorResult {
+  const gsdRoot = resolveGsdRoot(projectDir);
+  const issues: DoctorIssue[] = [];
+
+  if (!existsSync(gsdRoot)) {
+    return {
+      ok: true,
+      issues: [{
+        severity: 'info',
+        code: 'no_gsd_directory',
+        scope: 'project',
+        unitId: '',
+        message: 'No .gsd/ directory found — project not initialized',
+      }],
+      counts: { error: 0, warning: 0, info: 1 },
+    };
+  }
+
+  // Project-level checks
+  checkProjectLevel(gsdRoot, issues);
+
+  // Milestone + slice checks
+  const milestoneIds = scope
+    ? findMilestoneIds(gsdRoot).filter((id) => id === scope)
+    : findMilestoneIds(gsdRoot);
+
+  for (const mid of milestoneIds) {
+    checkMilestoneLevel(gsdRoot, mid, issues);
+
+    const sliceIds = findSliceIds(gsdRoot, mid);
+    for (const sid of sliceIds) {
+      checkSliceLevel(gsdRoot, mid, sid, issues);
+    }
+  }
+
+  const counts = {
+    error: issues.filter((i) => i.severity === 'error').length,
+    warning: issues.filter((i) => i.severity === 'warning').length,
+    info: issues.filter((i) => i.severity === 'info').length,
+  };
+
+  return { ok: counts.error === 0, issues, counts };
+}

package/packages/mcp-server/src/readers/index.ts

@@ -0,0 +1,16 @@
+// GSD MCP Server — readers barrel export
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+export { resolveGsdRoot, resolveRootFile } from './paths.js';
+export { readProgress } from './state.js';
+export type { ProgressResult } from './state.js';
+export { readRoadmap } from './roadmap.js';
+export type { RoadmapResult, MilestoneInfo, SliceInfo, TaskInfo } from './roadmap.js';
+export { readHistory } from './metrics.js';
+export type { HistoryResult, MetricsUnit } from './metrics.js';
+export { readCaptures } from './captures.js';
+export type { CapturesResult, CaptureEntry } from './captures.js';
+export { readKnowledge } from './knowledge.js';
+export type { KnowledgeResult, KnowledgeEntry } from './knowledge.js';
+export { runDoctorLite } from './doctor-lite.js';
+export type { DoctorResult, DoctorIssue } from './doctor-lite.js';

package/packages/mcp-server/src/readers/knowledge.ts

@@ -0,0 +1,111 @@
+// GSD MCP Server — knowledge base reader
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolveGsdRoot, resolveRootFile } from './paths.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type KnowledgeType = 'rule' | 'pattern' | 'lesson';
+
+export interface KnowledgeEntry {
+  id: string;
+  type: KnowledgeType;
+  scope: string;
+  content: string;
+  addedAt: string;
+}
+
+export interface KnowledgeResult {
+  entries: KnowledgeEntry[];
+  counts: { rules: number; patterns: number; lessons: number };
+}
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+function parseTableRows(section: string, type: KnowledgeType): KnowledgeEntry[] {
+  const entries: KnowledgeEntry[] = [];
+  const lines = section.split('\n');
+
+  for (const line of lines) {
+    if (!line.includes('|')) continue;
+    const cells = line.split('|').map((c) => c.trim()).filter(Boolean);
+    if (cells.length < 3) continue;
+    // Skip header/separator
+    if (cells[0].startsWith('#') || cells[0].startsWith('-')) continue;
+
+    const id = cells[0];
+    if (!/^[KPL]\d+$/i.test(id)) continue;
+
+    if (type === 'rule' && cells.length >= 5) {
+      entries.push({
+        id, type, scope: cells[1], content: cells[2], addedAt: cells[4] ?? '',
+      });
+    } else if (type === 'pattern' && cells.length >= 4) {
+      entries.push({
+        id, type, scope: cells[2] ?? '', content: cells[1], addedAt: cells[3] ?? '',
+      });
+    } else if (type === 'lesson' && cells.length >= 5) {
+      entries.push({
+        id, type, scope: cells[4] ?? '',
+        content: `${cells[1]} — Root cause: ${cells[2]} — Fix: ${cells[3]}`,
+        addedAt: '',
+      });
+    }
+  }
+
+  return entries;
+}
+
+function parseKnowledgeMarkdown(content: string): KnowledgeEntry[] {
+  const entries: KnowledgeEntry[] = [];
+
+  // Find ## Rules section
+  const rulesMatch = content.match(/## Rules\s*\n([\s\S]*?)(?=\n## |$)/i);
+  if (rulesMatch) {
+    entries.push(...parseTableRows(rulesMatch[1], 'rule'));
+  }
+
+  // Find ## Patterns section
+  const patternsMatch = content.match(/## Patterns\s*\n([\s\S]*?)(?=\n## |$)/i);
+  if (patternsMatch) {
+    entries.push(...parseTableRows(patternsMatch[1], 'pattern'));
+  }
+
+  // Find ## Lessons Learned section
+  const lessonsMatch = content.match(/## Lessons Learned\s*\n([\s\S]*?)(?=\n## |$)/i);
+  if (lessonsMatch) {
+    entries.push(...parseTableRows(lessonsMatch[1], 'lesson'));
+  }
+
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function readKnowledge(projectDir: string): KnowledgeResult {
+  const gsd = resolveGsdRoot(projectDir);
+  const knowledgePath = resolveRootFile(gsd, 'KNOWLEDGE.md');
+
+  if (!existsSync(knowledgePath)) {
+    return { entries: [], counts: { rules: 0, patterns: 0, lessons: 0 } };
+  }
+
+  const content = readFileSync(knowledgePath, 'utf-8');
+  const entries = parseKnowledgeMarkdown(content);
+
+  return {
+    entries,
+    counts: {
+      rules: entries.filter((e) => e.type === 'rule').length,
+      patterns: entries.filter((e) => e.type === 'pattern').length,
+      lessons: entries.filter((e) => e.type === 'lesson').length,
+    },
+  };
+}

package/packages/mcp-server/src/readers/metrics.ts

@@ -0,0 +1,118 @@
+// GSD MCP Server — metrics/history reader
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolveGsdRoot, resolveRootFile } from './paths.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface MetricsUnit {
+  type: string;
+  id: string;
+  model: string;
+  startedAt: number;
+  finishedAt: number;
+  tokens: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+  cost: number;
+  toolCalls: number;
+  apiRequests: number;
+}
+
+export interface HistoryResult {
+  entries: MetricsUnit[];
+  totals: {
+    cost: number;
+    tokens: { input: number; output: number; total: number };
+    units: number;
+    durationMs: number;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+function parseMetricsJson(content: string): MetricsUnit[] {
+  try {
+    const data = JSON.parse(content);
+    if (!data.units || !Array.isArray(data.units)) return [];
+
+    return data.units.map((u: Record<string, unknown>) => ({
+      type: String(u.type ?? 'unknown'),
+      id: String(u.id ?? ''),
+      model: String(u.model ?? 'unknown'),
+      startedAt: Number(u.startedAt ?? 0),
+      finishedAt: Number(u.finishedAt ?? 0),
+      tokens: {
+        input: Number((u.tokens as Record<string, unknown>)?.input ?? 0),
+        output: Number((u.tokens as Record<string, unknown>)?.output ?? 0),
+        cacheRead: Number((u.tokens as Record<string, unknown>)?.cacheRead ?? 0),
+        cacheWrite: Number((u.tokens as Record<string, unknown>)?.cacheWrite ?? 0),
+        total: Number((u.tokens as Record<string, unknown>)?.total ?? 0),
+      },
+      cost: Number(u.cost ?? 0),
+      toolCalls: Number(u.toolCalls ?? 0),
+      apiRequests: Number(u.apiRequests ?? 0),
+    }));
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function readHistory(projectDir: string, limit?: number): HistoryResult {
+  const gsd = resolveGsdRoot(projectDir);
+
+  // metrics.json (primary)
+  const metricsPath = resolveRootFile(gsd, 'metrics.json');
+  let units: MetricsUnit[] = [];
+
+  if (existsSync(metricsPath)) {
+    const content = readFileSync(metricsPath, 'utf-8');
+    units = parseMetricsJson(content);
+  }
+
+  // Sort by startedAt descending (most recent first)
+  units.sort((a, b) => b.startedAt - a.startedAt);
+
+  // Apply limit
+  if (limit && limit > 0) {
+    units = units.slice(0, limit);
+  }
+
+  // Compute totals from ALL units (not just limited set)
+  const allUnits = existsSync(metricsPath)
+    ? parseMetricsJson(readFileSync(metricsPath, 'utf-8'))
+    : [];
+
+  const totals = {
+    cost: 0,
+    tokens: { input: 0, output: 0, total: 0 },
+    units: allUnits.length,
+    durationMs: 0,
+  };
+
+  for (const u of allUnits) {
+    totals.cost += u.cost;
+    totals.tokens.input += u.tokens.input;
+    totals.tokens.output += u.tokens.output;
+    totals.tokens.total += u.tokens.total;
+    totals.durationMs += (u.finishedAt - u.startedAt);
+  }
+
+  // Round cost to 4 decimal places
+  totals.cost = Math.round(totals.cost * 10000) / 10000;
+
+  return { entries: units, totals };
+}

package/packages/mcp-server/src/readers/paths.ts

@@ -0,0 +1,217 @@
+// GSD MCP Server — .gsd/ directory resolution
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { existsSync, statSync, readdirSync } from 'node:fs';
+import { join, resolve, dirname, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Resolve the .gsd/ root directory for a project.
+ *
+ * Probes in order:
+ *   1. projectDir/.gsd (fast path)
+ *   2. git repo root/.gsd
+ *   3. Walk up from projectDir
+ *   4. Fallback: projectDir/.gsd (even if missing — for init)
+ */
+export function resolveGsdRoot(projectDir: string): string {
+  const resolved = resolve(projectDir);
+
+  // Fast path: .gsd/ in the given directory
+  const direct = join(resolved, '.gsd');
+  if (existsSync(direct) && statSync(direct).isDirectory()) {
+    return direct;
+  }
+
+  // Try git repo root
+  try {
+    const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: resolved,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    const gitGsd = join(gitRoot, '.gsd');
+    if (existsSync(gitGsd) && statSync(gitGsd).isDirectory()) {
+      return gitGsd;
+    }
+  } catch {
+    // Not a git repo or git not available
+  }
+
+  // Walk up from projectDir
+  let dir = resolved;
+  while (dir !== dirname(dir)) {
+    const candidate = join(dir, '.gsd');
+    if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+      return candidate;
+    }
+    dir = dirname(dir);
+  }
+
+  // Fallback
+  return direct;
+}
+
+/** Resolve path to a .gsd/ root file (STATE.md, KNOWLEDGE.md, etc.) */
+export function resolveRootFile(gsdRoot: string, name: string): string {
+  return join(gsdRoot, name);
+}
+
+/** Resolve path to milestones directory */
+export function milestonesDir(gsdRoot: string): string {
+  return join(gsdRoot, 'milestones');
+}
+
+/**
+ * Find all milestone directory IDs (M001, M002, etc.).
+ * Handles both bare (M001/) and descriptor (M001-FLIGHT-SIM/) naming.
+ */
+export function findMilestoneIds(gsdRoot: string): string[] {
+  const dir = milestonesDir(gsdRoot);
+  if (!existsSync(dir)) return [];
+
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const ids: string[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const match = entry.name.match(/^(M\d+)/);
+    if (match) ids.push(match[1]);
+  }
+
+  return ids.sort();
+}
+
+/**
+ * Resolve the actual directory name for a milestone ID.
+ * M001 might live in M001/ or M001-SOME-DESCRIPTOR/.
+ */
+export function resolveMilestoneDir(gsdRoot: string, milestoneId: string): string | null {
+  const dir = milestonesDir(gsdRoot);
+  if (!existsSync(dir)) return null;
+
+  // Fast path: exact match
+  const exact = join(dir, milestoneId);
+  if (existsSync(exact) && statSync(exact).isDirectory()) return exact;
+
+  // Prefix match
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name.startsWith(milestoneId)) {
+      return join(dir, entry.name);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve a milestone-level file (M001-ROADMAP.md, M001-CONTEXT.md, etc.).
+ * Handles various naming conventions.
+ */
+export function resolveMilestoneFile(gsdRoot: string, milestoneId: string, suffix: string): string | null {
+  const mDir = resolveMilestoneDir(gsdRoot, milestoneId);
+  if (!mDir) return null;
+
+  const dirName = basename(mDir);
+
+  // Try: M001-ROADMAP.md, then DIRNAME-ROADMAP.md
+  const candidates = [
+    join(mDir, `${milestoneId}-${suffix}.md`),
+    join(mDir, `${dirName}-${suffix}.md`),
+    join(mDir, `${suffix}.md`),
+  ];
+
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return null;
+}
+
+/** Find all slice IDs within a milestone (S01, S02, etc.) */
+export function findSliceIds(gsdRoot: string, milestoneId: string): string[] {
+  const mDir = resolveMilestoneDir(gsdRoot, milestoneId);
+  if (!mDir) return [];
+
+  const slicesDir = join(mDir, 'slices');
+  if (!existsSync(slicesDir)) return [];
+
+  const entries = readdirSync(slicesDir, { withFileTypes: true });
+  const ids: string[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const match = entry.name.match(/^(S\d+)/);
+    if (match) ids.push(match[1]);
+  }
+
+  return ids.sort();
+}
+
+/** Resolve the actual directory for a slice */
+export function resolveSliceDir(gsdRoot: string, milestoneId: string, sliceId: string): string | null {
+  const mDir = resolveMilestoneDir(gsdRoot, milestoneId);
+  if (!mDir) return null;
+
+  const slicesDir = join(mDir, 'slices');
+  if (!existsSync(slicesDir)) return null;
+
+  const exact = join(slicesDir, sliceId);
+  if (existsSync(exact) && statSync(exact).isDirectory()) return exact;
+
+  const entries = readdirSync(slicesDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name.startsWith(sliceId)) {
+      return join(slicesDir, entry.name);
+    }
+  }
+  return null;
+}
+
+/** Resolve a slice-level file (S01-PLAN.md, etc.) */
+export function resolveSliceFile(
+  gsdRoot: string, milestoneId: string, sliceId: string, suffix: string,
+): string | null {
+  const sDir = resolveSliceDir(gsdRoot, milestoneId, sliceId);
+  if (!sDir) return null;
+
+  const dirName = basename(sDir);
+  const candidates = [
+    join(sDir, `${sliceId}-${suffix}.md`),
+    join(sDir, `${dirName}-${suffix}.md`),
+    join(sDir, `${suffix}.md`),
+  ];
+
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return null;
+}
+
+/** Find all task files in a slice's tasks/ directory */
+export function findTaskFiles(
+  gsdRoot: string, milestoneId: string, sliceId: string,
+): Array<{ id: string; hasPlan: boolean; hasSummary: boolean }> {
+  const sDir = resolveSliceDir(gsdRoot, milestoneId, sliceId);
+  if (!sDir) return [];
+
+  const tasksDir = join(sDir, 'tasks');
+  if (!existsSync(tasksDir)) return [];
+
+  const files = readdirSync(tasksDir);
+  const taskMap = new Map<string, { hasPlan: boolean; hasSummary: boolean }>();
+
+  for (const f of files) {
+    const match = f.match(/^(T\d+).*-(PLAN|SUMMARY)\.md$/i);
+    if (!match) continue;
+    const [, id, type] = match;
+    const existing = taskMap.get(id) ?? { hasPlan: false, hasSummary: false };
+    if (type.toUpperCase() === 'PLAN') existing.hasPlan = true;
+    if (type.toUpperCase() === 'SUMMARY') existing.hasSummary = true;
+    taskMap.set(id, existing);
+  }
+
+  return Array.from(taskMap.entries())
+    .map(([id, info]) => ({ id, ...info }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}