gsd-remix 1.0.0

package/sdk/src/query/phase.test.ts

@@ -0,0 +1,307 @@
+/**
+ * Unit tests for phase query handlers.
+ *
+ * Tests findPhase and phasePlanIndex handlers.
+ * Uses temp directories with real .planning/ structures.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { GSDError } from '../errors.js';
+
+import { findPhase, phasePlanIndex } from './phase.js';
+
+// ─── Fixtures ──────────────────────────────────────────────────────────────
+
+const PLAN_01_CONTENT = `---
+phase: 09-foundation
+plan: 01
+wave: 1
+autonomous: true
+files_modified:
+  - sdk/src/errors.ts
+  - sdk/src/errors.test.ts
+---
+
+<objective>
+Build error classification system.
+</objective>
+
+<tasks>
+<task type="auto">
+  <name>Task 1: Create error types</name>
+</task>
+<task type="auto">
+  <name>Task 2: Add exit codes</name>
+</task>
+</tasks>
+`;
+
+const PLAN_02_CONTENT = `---
+phase: 09-foundation
+plan: 02
+wave: 1
+autonomous: false
+files_modified:
+  - sdk/src/query/registry.ts
+---
+
+<objective>
+Build query registry.
+</objective>
+
+<tasks>
+<task type="auto">
+  <name>Task 1: Registry class</name>
+</task>
+<task type="checkpoint:human-verify">
+  <name>Task 2: Verify registry</name>
+</task>
+</tasks>
+`;
+
+const PLAN_03_CONTENT = `---
+phase: 09-foundation
+plan: 03
+wave: 2
+autonomous: true
+---
+
+<objective>
+Golden file tests.
+</objective>
+
+<tasks>
+<task type="auto">
+  <name>Task 1: Setup golden files</name>
+</task>
+</tasks>
+`;
+
+let tmpDir: string;
+
+// ─── Setup / Teardown ──────────────────────────────────────────────────────
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'gsd-phase-test-'));
+  const planningDir = join(tmpDir, '.planning');
+  const phasesDir = join(planningDir, 'phases');
+
+  await mkdir(phasesDir, { recursive: true });
+
+  // Phase 09
+  const phase09 = join(phasesDir, '09-foundation');
+  await mkdir(phase09, { recursive: true });
+  await writeFile(join(phase09, '09-01-PLAN.md'), PLAN_01_CONTENT);
+  await writeFile(join(phase09, '09-01-SUMMARY.md'), 'Summary 1');
+  await writeFile(join(phase09, '09-02-PLAN.md'), PLAN_02_CONTENT);
+  await writeFile(join(phase09, '09-02-SUMMARY.md'), 'Summary 2');
+  await writeFile(join(phase09, '09-03-PLAN.md'), PLAN_03_CONTENT);
+  // No summary for plan 03 (incomplete)
+  await writeFile(join(phase09, '09-RESEARCH.md'), 'Research');
+  await writeFile(join(phase09, '09-CONTEXT.md'), 'Context');
+
+  // Phase 10
+  const phase10 = join(phasesDir, '10-read-only-queries');
+  await mkdir(phase10, { recursive: true });
+  await writeFile(join(phase10, '10-01-PLAN.md'), '---\nphase: 10\nplan: 01\n---\n<objective>\nPort helpers.\n</objective>\n<tasks>\n<task type="auto">\n  <name>Task 1</name>\n</task>\n</tasks>');
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ─── findPhase ─────────────────────────────────────────────────────────────
+
+describe('findPhase', () => {
+  it('finds existing phase by number', async () => {
+    const result = await findPhase(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.found).toBe(true);
+    expect(data.phase_number).toBe('09');
+    expect(data.phase_name).toBe('foundation');
+  });
+
+  it('returns posix-style directory path', async () => {
+    const result = await findPhase(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.directory).toBe('.planning/phases/09-foundation');
+    // No backslashes
+    expect((data.directory as string)).not.toContain('\\');
+  });
+
+  it('lists plans and summaries', async () => {
+    const result = await findPhase(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    const plans = data.plans as string[];
+    const summaries = data.summaries as string[];
+
+    expect(plans.length).toBe(3);
+    expect(summaries.length).toBe(2);
+    expect(plans).toContain('09-01-PLAN.md');
+    expect(summaries).toContain('09-01-SUMMARY.md');
+  });
+
+  it('returns not found for nonexistent phase', async () => {
+    const result = await findPhase(['99'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.found).toBe(false);
+    expect(data.directory).toBeNull();
+    expect(data.phase_number).toBeNull();
+    expect(data.plans).toEqual([]);
+    expect(data.summaries).toEqual([]);
+  });
+
+  it('throws GSDError with Validation classification when no args', async () => {
+    await expect(findPhase([], tmpDir)).rejects.toThrow(GSDError);
+    try {
+      await findPhase([], tmpDir);
+    } catch (err) {
+      expect((err as GSDError).classification).toBe('validation');
+    }
+  });
+
+  it('handles two-digit phase numbers', async () => {
+    const result = await findPhase(['10'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.found).toBe(true);
+    expect(data.phase_number).toBe('10');
+    expect(data.phase_name).toBe('read-only-queries');
+  });
+
+  it('includes file stats (research, context)', async () => {
+    const result = await findPhase(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.has_research).toBe(true);
+    expect(data.has_context).toBe(true);
+  });
+
+  it('computes incomplete plans', async () => {
+    const result = await findPhase(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const incompletePlans = data.incomplete_plans as string[];
+
+    expect(incompletePlans.length).toBe(1);
+    expect(incompletePlans[0]).toBe('09-03-PLAN.md');
+  });
+
+  it('searches archived milestone phases', async () => {
+    // Create archived milestone directory
+    const archiveDir = join(tmpDir, '.planning', 'milestones', 'v1.0-phases', '01-setup');
+    await mkdir(archiveDir, { recursive: true });
+    await writeFile(join(archiveDir, '01-01-PLAN.md'), '---\nphase: 01\nplan: 01\n---\nPlan');
+    await writeFile(join(archiveDir, '01-01-SUMMARY.md'), 'Summary');
+
+    const result = await findPhase(['1'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.found).toBe(true);
+    expect(data.archived).toBe('v1.0');
+  });
+});
+
+// ─── phasePlanIndex ────────────────────────────────────────────────────────
+
+describe('phasePlanIndex', () => {
+  it('returns plan metadata for phase', async () => {
+    const result = await phasePlanIndex(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.phase).toBe('09');
+    const plans = data.plans as Array<Record<string, unknown>>;
+    expect(plans.length).toBe(3);
+  });
+
+  it('includes plan details (id, wave, autonomous, objective, task_count)', async () => {
+    const result = await phasePlanIndex(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const plans = data.plans as Array<Record<string, unknown>>;
+
+    const plan1 = plans.find(p => p.id === '09-01');
+    expect(plan1).toBeDefined();
+    expect(plan1!.wave).toBe(1);
+    expect(plan1!.autonomous).toBe(true);
+    expect(plan1!.objective).toBe('Build error classification system.');
+    expect(plan1!.task_count).toBe(2);
+    expect(plan1!.has_summary).toBe(true);
+  });
+
+  it('correctly counts XML task tags', async () => {
+    const result = await phasePlanIndex(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const plans = data.plans as Array<Record<string, unknown>>;
+
+    const plan1 = plans.find(p => p.id === '09-01');
+    expect(plan1!.task_count).toBe(2);
+
+    const plan2 = plans.find(p => p.id === '09-02');
+    expect(plan2!.task_count).toBe(2);
+
+    const plan3 = plans.find(p => p.id === '09-03');
+    expect(plan3!.task_count).toBe(1);
+  });
+
+  it('groups plans by wave', async () => {
+    const result = await phasePlanIndex(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const waves = data.waves as Record<string, string[]>;
+
+    expect(waves['1']).toContain('09-01');
+    expect(waves['1']).toContain('09-02');
+    expect(waves['2']).toContain('09-03');
+  });
+
+  it('identifies incomplete plans', async () => {
+    const result = await phasePlanIndex(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const incomplete = data.incomplete as string[];
+
+    expect(incomplete).toContain('09-03');
+    expect(incomplete).not.toContain('09-01');
+  });
+
+  it('detects has_checkpoints from non-autonomous plans', async () => {
+    const result = await phasePlanIndex(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    // Plan 02 has autonomous: false
+    expect(data.has_checkpoints).toBe(true);
+  });
+
+  it('parses files_modified from frontmatter', async () => {
+    const result = await phasePlanIndex(['9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const plans = data.plans as Array<Record<string, unknown>>;
+
+    const plan1 = plans.find(p => p.id === '09-01');
+    const filesModified = plan1!.files_modified as string[];
+
+    expect(filesModified).toContain('sdk/src/errors.ts');
+    expect(filesModified).toContain('sdk/src/errors.test.ts');
+  });
+
+  it('throws GSDError with Validation classification when no args', async () => {
+    await expect(phasePlanIndex([], tmpDir)).rejects.toThrow(GSDError);
+    try {
+      await phasePlanIndex([], tmpDir);
+    } catch (err) {
+      expect((err as GSDError).classification).toBe('validation');
+    }
+  });
+
+  it('returns error for nonexistent phase', async () => {
+    const result = await phasePlanIndex(['99'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.error).toBe('Phase not found');
+    expect(data.plans).toEqual([]);
+  });
+});

package/sdk/src/query/phase.ts

@@ -0,0 +1,340 @@
+/**
+ * Phase finding and plan index query handlers.
+ *
+ * Ported from get-shit-done/bin/lib/phase.cjs and core.cjs.
+ * Provides find-phase (directory lookup with archived fallback)
+ * and phase-plan-index (plan metadata with wave grouping).
+ *
+ * @example
+ * ```typescript
+ * import { findPhase, phasePlanIndex } from './phase.js';
+ *
+ * const found = await findPhase(['9'], '/project');
+ * // { data: { found: true, directory: '.planning/phases/09-foundation', ... } }
+ *
+ * const index = await phasePlanIndex(['9'], '/project');
+ * // { data: { phase: '09', plans: [...], waves: { '1': [...] }, ... } }
+ * ```
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { GSDError, ErrorClassification } from '../errors.js';
+import { extractFrontmatter } from './frontmatter.js';
+import {
+  normalizePhaseName,
+  comparePhaseNum,
+  phaseTokenMatches,
+  toPosixPath,
+  planningPaths,
+} from './helpers.js';
+import type { QueryHandler } from './utils.js';
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+interface PhaseInfo {
+  found: boolean;
+  directory: string | null;
+  phase_number: string | null;
+  phase_name: string | null;
+  phase_slug: string | null;
+  plans: string[];
+  summaries: string[];
+  incomplete_plans: string[];
+  has_research: boolean;
+  has_context: boolean;
+  has_verification: boolean;
+  has_reviews: boolean;
+  archived?: string;
+}
+
+// ─── Internal helpers ──────────────────────────────────────────────────────
+
+/**
+ * Get file stats for a phase directory.
+ *
+ * Port of getPhaseFileStats from core.cjs lines 1461-1471.
+ */
+async function getPhaseFileStats(phaseDir: string): Promise<{
+  plans: string[];
+  summaries: string[];
+  hasResearch: boolean;
+  hasContext: boolean;
+  hasVerification: boolean;
+  hasReviews: boolean;
+}> {
+  const files = await readdir(phaseDir);
+  return {
+    plans: files.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md'),
+    summaries: files.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md'),
+    hasResearch: files.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
+    hasContext: files.some(f => f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md'),
+    hasVerification: files.some(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md'),
+    hasReviews: files.some(f => f.endsWith('-REVIEWS.md') || f === 'REVIEWS.md'),
+  };
+}
+
+/**
+ * Search for a phase directory matching the normalized name.
+ *
+ * Port of searchPhaseInDir from core.cjs lines 956-1000.
+ */
+async function searchPhaseInDir(baseDir: string, relBase: string, normalized: string): Promise<PhaseInfo | null> {
+  try {
+    const entries = await readdir(baseDir, { withFileTypes: true });
+    const dirs = entries
+      .filter(e => e.isDirectory())
+      .map(e => e.name)
+      .sort((a, b) => comparePhaseNum(a, b));
+
+    const match = dirs.find(d => phaseTokenMatches(d, normalized));
+    if (!match) return null;
+
+    // Extract phase number and name
+    const dirMatch = match.match(/^(?:[A-Z]{1,6}-)(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i)
+      || match.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i)
+      || match.match(/^([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*)-(.+)/i)
+      || [null, match, null];
+    const phaseNumber = dirMatch ? dirMatch[1] : normalized;
+    const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
+    const phaseDir = join(baseDir, match);
+
+    const { plans: unsortedPlans, summaries: unsortedSummaries, hasResearch, hasContext, hasVerification, hasReviews } = await getPhaseFileStats(phaseDir);
+    const plans = unsortedPlans.sort();
+    const summaries = unsortedSummaries.sort();
+
+    const completedPlanIds = new Set(
+      summaries.map(s => s.replace('-SUMMARY.md', '').replace('SUMMARY.md', ''))
+    );
+    const incompletePlans = plans.filter(p => {
+      const planId = p.replace('-PLAN.md', '').replace('PLAN.md', '');
+      return !completedPlanIds.has(planId);
+    });
+
+    return {
+      found: true,
+      directory: toPosixPath(join(relBase, match)),
+      phase_number: phaseNumber,
+      phase_name: phaseName,
+      phase_slug: phaseName ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') : null,
+      plans,
+      summaries,
+      incomplete_plans: incompletePlans,
+      has_research: hasResearch,
+      has_context: hasContext,
+      has_verification: hasVerification,
+      has_reviews: hasReviews,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract objective text from plan content.
+ */
+function extractObjective(content: string): string | null {
+  const m = content.match(/<objective>\s*\n?\s*(.+)/);
+  return m ? m[1].trim() : null;
+}
+
+// ─── Exported handlers ─────────────────────────────────────────────────────
+
+/**
+ * Query handler for find-phase.
+ *
+ * Locates a phase directory by number/identifier, searching current phases
+ * first, then archived milestone phases.
+ *
+ * Port of cmdFindPhase from phase.cjs lines 152-196, combined with
+ * findPhaseInternal from core.cjs lines 1002-1038.
+ *
+ * @param args - args[0] is the phase identifier (required)
+ * @param projectDir - Project root directory
+ * @returns QueryResult with PhaseInfo
+ * @throws GSDError with Validation classification if phase identifier missing
+ */
+export const findPhase: QueryHandler = async (args, projectDir) => {
+  const phase = args[0];
+  if (!phase) {
+    throw new GSDError('phase identifier required', ErrorClassification.Validation);
+  }
+
+  const phasesDir = planningPaths(projectDir).phases;
+  const normalized = normalizePhaseName(phase);
+
+  const notFound: PhaseInfo = {
+    found: false,
+    directory: null,
+    phase_number: null,
+    phase_name: null,
+    phase_slug: null,
+    plans: [],
+    summaries: [],
+    incomplete_plans: [],
+    has_research: false,
+    has_context: false,
+    has_verification: false,
+    has_reviews: false,
+  };
+
+  // Search current phases first
+  const relPhasesDir = '.planning/phases';
+  const current = await searchPhaseInDir(phasesDir, relPhasesDir, normalized);
+  if (current) return { data: current };
+
+  // Search archived milestone phases (newest first)
+  const milestonesDir = join(projectDir, '.planning', 'milestones');
+  try {
+    const milestoneEntries = await readdir(milestonesDir, { withFileTypes: true });
+    const archiveDirs = milestoneEntries
+      .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
+      .map(e => e.name)
+      .sort()
+      .reverse();
+
+    for (const archiveName of archiveDirs) {
+      const versionMatch = archiveName.match(/^(v[\d.]+)-phases$/);
+      const version = versionMatch ? versionMatch[1] : archiveName;
+      const archivePath = join(milestonesDir, archiveName);
+      const relBase = '.planning/milestones/' + archiveName;
+      const result = await searchPhaseInDir(archivePath, relBase, normalized);
+      if (result) {
+        result.archived = version;
+        return { data: result };
+      }
+    }
+  } catch { /* milestones dir doesn't exist */ }
+
+  return { data: notFound };
+};
+
+/**
+ * Query handler for phase-plan-index.
+ *
+ * Returns plan metadata with wave grouping for a specific phase.
+ *
+ * Port of cmdPhasePlanIndex from phase.cjs lines 203-310.
+ *
+ * @param args - args[0] is the phase identifier (required)
+ * @param projectDir - Project root directory
+ * @returns QueryResult with { phase, plans[], waves{}, incomplete[], has_checkpoints }
+ * @throws GSDError with Validation classification if phase identifier missing
+ */
+export const phasePlanIndex: QueryHandler = async (args, projectDir) => {
+  const phase = args[0];
+  if (!phase) {
+    throw new GSDError('phase required for phase-plan-index', ErrorClassification.Validation);
+  }
+
+  const phasesDir = planningPaths(projectDir).phases;
+  const normalized = normalizePhaseName(phase);
+
+  // Find phase directory
+  let phaseDir: string | null = null;
+  try {
+    const entries = await readdir(phasesDir, { withFileTypes: true });
+    const dirs = entries
+      .filter(e => e.isDirectory())
+      .map(e => e.name)
+      .sort((a, b) => comparePhaseNum(a, b));
+    const match = dirs.find(d => phaseTokenMatches(d, normalized));
+    if (match) {
+      phaseDir = join(phasesDir, match);
+    }
+  } catch { /* phases dir doesn't exist */ }
+
+  if (!phaseDir) {
+    return {
+      data: {
+        phase: normalized,
+        error: 'Phase not found',
+        plans: [],
+        waves: {},
+        incomplete: [],
+        has_checkpoints: false,
+      },
+    };
+  }
+
+  // Get all files in phase directory
+  const phaseFiles = await readdir(phaseDir);
+  const planFiles = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').sort();
+  const summaryFiles = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+
+  // Build set of plan IDs with summaries
+  const completedPlanIds = new Set(
+    summaryFiles.map(s => s.replace('-SUMMARY.md', '').replace('SUMMARY.md', ''))
+  );
+
+  const plans: Array<Record<string, unknown>> = [];
+  const waves: Record<string, string[]> = {};
+  const incomplete: string[] = [];
+  let hasCheckpoints = false;
+
+  for (const planFile of planFiles) {
+    const planId = planFile.replace('-PLAN.md', '').replace('PLAN.md', '');
+    const planPath = join(phaseDir, planFile);
+    const content = await readFile(planPath, 'utf-8');
+    const fm = extractFrontmatter(content);
+
+    // Count tasks: XML <task> tags (canonical) or ## Task N markdown (legacy)
+    const xmlTasks = content.match(/<task[\s>]/gi) || [];
+    const mdTasks = content.match(/##\s*Task\s*\d+/gi) || [];
+    const taskCount = xmlTasks.length || mdTasks.length;
+
+    // Parse wave as integer
+    const wave = parseInt(String(fm.wave), 10) || 1;
+
+    // Parse autonomous (default true if not specified)
+    let autonomous = true;
+    if (fm.autonomous !== undefined) {
+      autonomous = fm.autonomous === 'true' || fm.autonomous === true;
+    }
+
+    if (!autonomous) {
+      hasCheckpoints = true;
+    }
+
+    // Parse files_modified
+    let filesModified: string[] = [];
+    const fmFiles = (fm['files_modified'] || fm['files-modified']) as string | string[] | undefined;
+    if (fmFiles) {
+      filesModified = Array.isArray(fmFiles) ? fmFiles : [fmFiles];
+    }
+
+    const hasSummary = completedPlanIds.has(planId);
+    if (!hasSummary) {
+      incomplete.push(planId);
+    }
+
+    const plan = {
+      id: planId,
+      wave,
+      autonomous,
+      objective: extractObjective(content) || (fm.objective as string) || null,
+      files_modified: filesModified,
+      task_count: taskCount,
+      has_summary: hasSummary,
+    };
+
+    plans.push(plan);
+
+    // Group by wave
+    const waveKey = String(wave);
+    if (!waves[waveKey]) {
+      waves[waveKey] = [];
+    }
+    waves[waveKey].push(planId);
+  }
+
+  return {
+    data: {
+      phase: normalized,
+      plans,
+      waves,
+      incomplete,
+      has_checkpoints: hasCheckpoints,
+    },
+  };
+};