gsd-remix 1.0.0

package/sdk/src/query/phase-list-queries.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Unit tests for phase.list-plans and phase.list-artifacts.
+ */
+
+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 { phaseListPlans, phaseListArtifacts } from './phase-list-queries.js';
+
+const PLAN_A = `---
+phase: 09-foundation
+plan: 01
+wave: 1
+must_haves:
+  truths: []
+---
+
+<objective>
+A
+</objective>
+<tasks><task type="auto"><name>T</name></task></tasks>
+`;
+
+const PLAN_B = `---
+phase: 09-foundation
+plan: 02
+wave: 1
+---
+
+<objective>
+B
+</objective>
+<tasks><task type="auto"><name>T</name></task></tasks>
+`;
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'gsd-plans-'));
+  const phaseDir = join(tmpDir, '.planning', 'phases', '09-foundation');
+  await mkdir(phaseDir, { recursive: true });
+  await writeFile(join(phaseDir, '09-01-PLAN.md'), PLAN_A);
+  await writeFile(join(phaseDir, '09-02-PLAN.md'), PLAN_B);
+  await writeFile(join(phaseDir, '09-CONTEXT.md'), 'ctx');
+  await writeFile(join(phaseDir, '09-RESEARCH.md'), 'res');
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('phaseListPlans', () => {
+  it('lists all plans in phase', async () => {
+    const r = await phaseListPlans(['9'], tmpDir);
+    const data = r.data as { plans: Array<{ id: string }> };
+    expect(data.plans.map((p) => p.id).sort()).toEqual(['09-01', '09-02']);
+  });
+
+  it('filters with --with-schema', async () => {
+    const r = await phaseListPlans(['9', '--with-schema', 'must_haves'], tmpDir);
+    const data = r.data as { plans: Array<{ id: string }> };
+    expect(data.plans.map((p) => p.id)).toEqual(['09-01']);
+  });
+
+  it('throws when phase missing', async () => {
+    await expect(phaseListPlans([], tmpDir)).rejects.toThrow(GSDError);
+  });
+});
+
+describe('phaseListArtifacts', () => {
+  it('lists context artifacts', async () => {
+    const r = await phaseListArtifacts(['9', '--type', 'context'], tmpDir);
+    const data = r.data as { artifacts: string[] };
+    expect(data.artifacts.some((a) => a.endsWith('09-CONTEXT.md'))).toBe(true);
+  });
+
+  it('lists research artifacts', async () => {
+    const r = await phaseListArtifacts(['9', '--type', 'research'], tmpDir);
+    const data = r.data as { artifacts: string[] };
+    expect(data.artifacts.some((a) => a.endsWith('09-RESEARCH.md'))).toBe(true);
+  });
+
+  it('throws without --type', async () => {
+    await expect(phaseListArtifacts(['9'], tmpDir)).rejects.toThrow(GSDError);
+  });
+});

package/sdk/src/query/phase-list-queries.ts

@@ -0,0 +1,152 @@
+/**
+ * Handlers: phase.list-plans, phase.list-artifacts — deterministic plan/artifact listing
+ * for agents (replaces shell `ls` / `find` patterns). SDK-only; no gsd-tools.cjs mirror.
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative } 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';
+
+/** Resolve `.planning/phases/<dir>` for a phase token, or null. */
+async function resolvePhaseDir(phase: string, projectDir: string): Promise<string | null> {
+  const phasesDir = planningPaths(projectDir).phases;
+  const normalized = normalizePhaseName(phase);
+  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));
+    return match ? join(phasesDir, match) : null;
+  } catch {
+    return null;
+  }
+}
+
+type ArtifactType = 'context' | 'summary' | 'verification' | 'research';
+
+/**
+ * phase.list-artifacts — list CONTEXT / SUMMARY / VERIFICATION / RESEARCH files in a phase directory.
+ *
+ * Args: `<phase>` `--type` `<context|summary|verification|research>`
+ */
+export const phaseListArtifacts: QueryHandler = async (args, projectDir) => {
+  if (!args[0]) {
+    throw new GSDError('phase required', ErrorClassification.Validation);
+  }
+  const typeIdx = args.indexOf('--type');
+  if (typeIdx === -1 || !args[typeIdx + 1]) {
+    throw new GSDError('--type context|summary|verification|research required', ErrorClassification.Validation);
+  }
+  const phase = args[0];
+  const rawType = args[typeIdx + 1].toLowerCase();
+  const allowed: ArtifactType[] = ['context', 'summary', 'verification', 'research'];
+  if (!allowed.includes(rawType as ArtifactType)) {
+    throw new GSDError(`invalid --type ${rawType}`, ErrorClassification.Validation);
+  }
+  const artifactType = rawType as ArtifactType;
+
+  const phaseDir = await resolvePhaseDir(phase, projectDir);
+  if (!phaseDir) {
+    return { data: { phase: normalizePhaseName(phase), type: artifactType, artifacts: [], error: 'Phase not found' } };
+  }
+
+  const files = await readdir(phaseDir);
+  const baseNames = files.filter((f) => {
+    if (artifactType === 'context') {
+      return f.endsWith('-CONTEXT.md') || f === 'CONTEXT.md';
+    }
+    if (artifactType === 'summary') {
+      return f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md';
+    }
+    if (artifactType === 'verification') {
+      return f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md';
+    }
+    return f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md';
+  });
+
+  const artifacts = baseNames.sort().map((f) =>
+    toPosixPath(relative(projectDir, join(phaseDir, f))),
+  );
+
+  return {
+    data: {
+      phase: normalizePhaseName(phase),
+      type: artifactType,
+      artifacts,
+    },
+  };
+};
+
+/**
+ * phase.list-plans — list PLAN files in a phase with optional frontmatter key filter.
+ *
+ * Args: `<phase>` [`--with-schema` `<yamlKey>`]
+ */
+export const phaseListPlans: QueryHandler = async (args, projectDir) => {
+  if (!args[0]) {
+    throw new GSDError('phase required', ErrorClassification.Validation);
+  }
+  let schemaKey: string | null = null;
+  const wsIdx = args.indexOf('--with-schema');
+  if (wsIdx !== -1) {
+    schemaKey = args[wsIdx + 1] ?? null;
+    if (!schemaKey) {
+      throw new GSDError('--with-schema requires a field name', ErrorClassification.Validation);
+    }
+  }
+
+  const phase = args[0];
+  const normalized = normalizePhaseName(phase);
+  const phaseDir = await resolvePhaseDir(phase, projectDir);
+  if (!phaseDir) {
+    return {
+      data: {
+        phase: normalized,
+        plans: [] as Array<Record<string, unknown>>,
+        error: 'Phase not found',
+      },
+    };
+  }
+
+  const phaseFiles = await readdir(phaseDir);
+  const planFiles = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').sort();
+
+  const plans: Array<Record<string, unknown>> = [];
+  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) as Record<string, unknown>;
+
+    if (schemaKey && !(schemaKey in fm)) {
+      continue;
+    }
+
+    plans.push({
+      id: planId,
+      file: toPosixPath(planFile),
+      wave: parseInt(String(fm.wave ?? '1'), 10) || 1,
+      autonomous: fm.autonomous !== false && fm.autonomous !== 'false',
+      frontmatter_keys: Object.keys(fm).sort(),
+    });
+  }
+
+  return {
+    data: {
+      phase: normalized,
+      with_schema: schemaKey,
+      plans,
+    },
+  };
+};

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

@@ -0,0 +1,65 @@
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it, expect } from 'vitest';
+import { checkPhaseReady } from './phase-ready.js';
+
+async function writeMinimalRoadmap(root: string): Promise<void> {
+  await mkdir(join(root, '.planning'), { recursive: true });
+  await writeFile(
+    join(root, '.planning', 'STATE.md'),
+    `---
+milestone: v1.0
+---
+
+# State
+`,
+    'utf-8',
+  );
+  await writeFile(
+    join(root, '.planning', 'ROADMAP.md'),
+    `## Milestone v1.0 — Test
+
+### Phase 3: Sample Phase
+
+**Goal:** Test goal
+
+`,
+    'utf-8',
+  );
+}
+
+describe('checkPhaseReady', () => {
+  it('throws when phase is missing', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'gsd-pr-'));
+    await mkdir(join(dir, '.planning'), { recursive: true });
+    await expect(checkPhaseReady([], dir)).rejects.toThrow(/phase number required/);
+  });
+
+  it('returns discuss next_step when phase directory is missing', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'gsd-pr-'));
+    await writeMinimalRoadmap(dir);
+    const { data } = await checkPhaseReady(['3'], dir);
+    expect(data).toMatchObject({
+      found: false,
+      next_step: 'discuss',
+      ready: false,
+    });
+  });
+
+  it('returns plan when context exists but no plans', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'gsd-pr-'));
+    await writeMinimalRoadmap(dir);
+    const phaseDir = join(dir, '.planning', 'phases', '03-sample-phase');
+    await mkdir(phaseDir, { recursive: true });
+    await writeFile(join(phaseDir, '03-CONTEXT.md'), '# Ctx\n', 'utf-8');
+    const { data } = await checkPhaseReady(['3'], dir);
+    expect(data).toMatchObject({
+      found: true,
+      has_context: true,
+      plan_count: 0,
+      next_step: 'plan',
+      ready: true,
+    });
+  });
+});

package/sdk/src/query/phase-ready.ts

@@ -0,0 +1,158 @@
+/**
+ * Phase readiness snapshot (`check.phase-ready`).
+ *
+ * Deterministic file + plan/summary counts and a suggested `next_step` for orchestration.
+ * See `.planning/research/decision-routing-audit.md` §3.4.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { GSDError, ErrorClassification } from '../errors.js';
+import { comparePhaseNum, escapeRegex, normalizePhaseName, planningPaths } from './helpers.js';
+import { findPhase } from './phase.js';
+import { roadmapAnalyze } from './roadmap.js';
+import type { QueryHandler } from './utils.js';
+
+const UI_INDICATOR_RE = /UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget/i;
+
+/**
+ * True if ROADMAP phase heading line for this phase matches UI_INDICATOR_RE.
+ */
+async function roadmapPhaseLineHasUiIndicators(
+  projectDir: string,
+  phaseNum: string,
+): Promise<boolean> {
+  const roadmapPath = planningPaths(projectDir).roadmap;
+  let content: string;
+  try {
+    content = await readFile(roadmapPath, 'utf-8');
+  } catch {
+    return false;
+  }
+  const re = new RegExp(
+    `#{2,4}\\s*Phase\\s+${escapeRegex(phaseNum)}\\s*:[^\\n]*`,
+    'i',
+  );
+  const m = content.match(re);
+  if (!m) return false;
+  return UI_INDICATOR_RE.test(m[0]);
+}
+
+function hasUiSpecFile(phaseDirFull: string): boolean {
+  if (!existsSync(phaseDirFull)) return false;
+  try {
+    const files = readdirSync(phaseDirFull);
+    return files.some(f => f === 'UI-SPEC.md' || f.endsWith('-UI-SPEC.md'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether all roadmap phases strictly before `phaseNum` are complete on disk / roadmap.
+ */
+function dependenciesMet(
+  phases: Array<Record<string, unknown>>,
+  phaseNum: string,
+): boolean {
+  const sorted = [...phases].sort((a, b) =>
+    comparePhaseNum(String(a.number), String(b.number)),
+  );
+  const idx = sorted.findIndex(p => normalizePhaseName(String(p.number)) === normalizePhaseName(phaseNum));
+  if (idx <= 0) return true;
+  for (let i = 0; i < idx; i++) {
+    const p = sorted[i];
+    const complete =
+      p.roadmap_complete === true ||
+      p.disk_status === 'complete';
+    if (!complete) return false;
+  }
+  return true;
+}
+
+type NextStep = 'discuss' | 'plan' | 'execute' | 'verify' | 'complete';
+
+function inferNextStep(params: {
+  found: boolean;
+  has_context: boolean;
+  has_research: boolean;
+  plan_count: number;
+  incomplete_plans: string[];
+  has_verification: boolean;
+}): NextStep {
+  if (!params.found) return 'discuss';
+  if (!params.has_context && !params.has_research) return 'discuss';
+  if (params.plan_count === 0) return 'plan';
+  if (params.incomplete_plans.length > 0) return 'execute';
+  if (!params.has_verification) return 'verify';
+  return 'complete';
+}
+
+export const checkPhaseReady: QueryHandler = async (args, projectDir) => {
+  const raw = args[0];
+  if (!raw) {
+    throw new GSDError('phase number required for check phase-ready', ErrorClassification.Validation);
+  }
+  const phaseArg = normalizePhaseName(raw);
+
+  const phaseRes = await findPhase([raw], projectDir);
+  const pdata = phaseRes.data as Record<string, unknown>;
+  const found = Boolean(pdata.found);
+
+  const planCount = (pdata.plans as string[] | undefined)?.length ?? 0;
+  const incomplete = (pdata.incomplete_plans as string[] | undefined) ?? [];
+  const has_context = Boolean(pdata.has_context);
+  const has_research = Boolean(pdata.has_research);
+  const has_verification = Boolean(pdata.has_verification);
+
+  let has_ui_spec = false;
+  let phaseDirFull: string | null = null;
+  if (found && pdata.directory) {
+    phaseDirFull = join(projectDir, pdata.directory as string);
+    has_ui_spec = hasUiSpecFile(phaseDirFull);
+  }
+
+  const phaseNumForRoadmap = (pdata.phase_number as string) || phaseArg;
+  const has_ui_indicators =
+    (await roadmapPhaseLineHasUiIndicators(projectDir, phaseNumForRoadmap)) ||
+    (phaseNumForRoadmap !== phaseArg ? await roadmapPhaseLineHasUiIndicators(projectDir, phaseArg) : false);
+
+  const analysis = await roadmapAnalyze([], projectDir);
+  const adata = analysis.data as { phases?: Array<Record<string, unknown>> };
+  const phases = adata.phases ?? [];
+  const deps = dependenciesMet(phases, phaseArg);
+
+  const next_step = inferNextStep({
+    found,
+    has_context,
+    has_research,
+    plan_count: planCount,
+    incomplete_plans: incomplete,
+    has_verification,
+  });
+
+  /** Phase exists on disk and prior roadmap phases are complete — safe to focus on `next_step`. */
+  const ready = found && deps;
+
+  return {
+    data: {
+      found,
+      ready,
+      phase: phaseArg,
+      phase_name: (pdata.phase_name as string) ?? null,
+      phase_dir: (pdata.directory as string) ?? null,
+      has_context,
+      has_research,
+      has_plans: planCount > 0,
+      plan_count: planCount,
+      incomplete_plans: incomplete.length,
+      has_verification,
+      has_ui_spec,
+      has_ui_indicators,
+      dependencies_met: deps,
+      blockers: [] as string[],
+      next_step,
+    },
+  };
+};