gsd-remix 1.0.0

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

@@ -0,0 +1,216 @@
+/**
+ * Unit tests for QueryRegistry, extractField, and createRegistry factory.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { QueryRegistry, extractField, resolveQueryArgv } from './registry.js';
+import { createRegistry, QUERY_MUTATION_COMMANDS } from './index.js';
+import type { QueryResult } from './utils.js';
+
+// ─── extractField ──────────────────────────────────────────────────────────
+
+describe('extractField', () => {
+  it('extracts nested value with dot notation', () => {
+    expect(extractField({ a: { b: 1 } }, 'a.b')).toBe(1);
+  });
+
+  it('extracts top-level value', () => {
+    expect(extractField({ slug: 'my-phase' }, 'slug')).toBe('my-phase');
+  });
+
+  it('extracts array element with bracket notation', () => {
+    expect(extractField({ items: [10, 20, 30] }, 'items[1]')).toBe(20);
+  });
+
+  it('extracts array element with negative index', () => {
+    expect(extractField({ items: [10, 20, 30] }, 'items[-1]')).toBe(30);
+  });
+
+  it('returns undefined for null input', () => {
+    expect(extractField(null, 'a')).toBeUndefined();
+  });
+
+  it('returns undefined for undefined input', () => {
+    expect(extractField(undefined, 'a')).toBeUndefined();
+  });
+
+  it('returns undefined for missing nested path', () => {
+    expect(extractField({ a: 1 }, 'b.c')).toBeUndefined();
+  });
+
+  it('returns undefined when bracket access targets non-array', () => {
+    expect(extractField({ items: 'not-array' }, 'items[0]')).toBeUndefined();
+  });
+
+  it('handles deeply nested paths', () => {
+    expect(extractField({ a: { b: { c: { d: 42 } } } }, 'a.b.c.d')).toBe(42);
+  });
+
+  it('handles mixed dot and bracket notation', () => {
+    expect(extractField({ data: { items: [{ name: 'x' }] } }, 'data.items[0].name')).toBe('x');
+  });
+});
+
+// ─── QueryRegistry ─────────────────────────────────────────────────────────
+
+describe('QueryRegistry', () => {
+  it('register makes has() return true', () => {
+    const registry = new QueryRegistry();
+    const handler = async () => ({ data: 'test' });
+    registry.register('test-cmd', handler);
+
+    expect(registry.has('test-cmd')).toBe(true);
+  });
+
+  it('has() returns false for unregistered command', () => {
+    const registry = new QueryRegistry();
+
+    expect(registry.has('nonexistent')).toBe(false);
+  });
+
+  it('dispatch calls registered handler', async () => {
+    const registry = new QueryRegistry();
+    const handler = vi.fn(async (args: string[], _projectDir: string): Promise<QueryResult> => {
+      return { data: { value: args[0] } };
+    });
+    registry.register('test-cmd', handler);
+
+    const result = await registry.dispatch('test-cmd', ['arg1'], '/tmp');
+
+    expect(handler).toHaveBeenCalledWith(['arg1'], '/tmp');
+    expect(result).toEqual({ data: { value: 'arg1' } });
+  });
+
+  it('dispatch throws GSDError for unregistered command', async () => {
+    const registry = new QueryRegistry();
+    // Bridge removed in v3.0 — unknown commands throw, not fallback
+    await expect(registry.dispatch('unknown-cmd', ['arg1'], '/tmp/project'))
+      .rejects.toThrow('Unknown command: "unknown-cmd"');
+  });
+
+  it('commands() returns all registered command names', () => {
+    const registry = new QueryRegistry();
+    registry.register('alpha', async () => ({ data: 1 }));
+    registry.register('beta', async () => ({ data: 2 }));
+    expect(registry.commands().sort()).toEqual(['alpha', 'beta']);
+  });
+});
+
+// ─── QUERY_MUTATION_COMMANDS vs registry ───────────────────────────────────
+
+describe('QUERY_MUTATION_COMMANDS', () => {
+  it('has a registered handler for every mutation command name', () => {
+    const registry = createRegistry();
+    const missing: string[] = [];
+    for (const cmd of QUERY_MUTATION_COMMANDS) {
+      if (!registry.has(cmd)) missing.push(cmd);
+    }
+    expect(missing).toEqual([]);
+  });
+});
+
+// ─── createRegistry ────────────────────────────────────────────────────────
+
+describe('createRegistry', () => {
+  it('returns a QueryRegistry instance', () => {
+    const registry = createRegistry();
+
+    expect(registry).toBeInstanceOf(QueryRegistry);
+  });
+
+  it('has generate-slug registered', () => {
+    const registry = createRegistry();
+
+    expect(registry.has('generate-slug')).toBe(true);
+  });
+
+  it('has current-timestamp registered', () => {
+    const registry = createRegistry();
+
+    expect(registry.has('current-timestamp')).toBe(true);
+  });
+
+  it('has summary-extract dash alias (PR #2179 / workflows)', () => {
+    const registry = createRegistry();
+    expect(registry.has('summary-extract')).toBe(true);
+  });
+
+  it('has context-history registered', () => {
+    const registry = createRegistry();
+    expect(registry.has('context-history')).toBe(true);
+  });
+
+  it('has plan.execution-route registered', () => {
+    const registry = createRegistry();
+    expect(registry.has('plan.execution-route')).toBe(true);
+  });
+
+  it('has failure.capture-phase registered', () => {
+    const registry = createRegistry();
+    expect(registry.has('failure.capture-phase')).toBe(true);
+  });
+
+  it('has runtime.health registered', () => {
+    const registry = createRegistry();
+    expect(registry.has('runtime.health')).toBe(true);
+  });
+
+  it('has sdk.health alias registered', () => {
+    const registry = createRegistry();
+    expect(registry.has('sdk.health')).toBe(true);
+  });
+
+  it('has failure.preflight registered', () => {
+    const registry = createRegistry();
+    expect(registry.has('failure.preflight')).toBe(true);
+  });
+
+  it('has failure.promote-phase registered', () => {
+    const registry = createRegistry();
+    expect(registry.has('failure.promote-phase')).toBe(true);
+  });
+
+  it('can dispatch generate-slug', async () => {
+    const registry = createRegistry();
+    const result = await registry.dispatch('generate-slug', ['My Phase'], '/tmp');
+
+    expect(result).toEqual({ data: { slug: 'my-phase' } });
+  });
+});
+
+// ─── resolveQueryArgv ───────────────────────────────────────────────────────
+
+describe('resolveQueryArgv', () => {
+  it('matches longest dotted prefix (state.update + args)', () => {
+    const registry = createRegistry();
+    const m = resolveQueryArgv(['state', 'update', 'status', 'X'], registry);
+    expect(m).toEqual({ cmd: 'state.update', args: ['status', 'X'] });
+  });
+
+  it('matches longest prefix (phase.add wins over phase when both registered)', () => {
+    const registry = createRegistry();
+    const m = resolveQueryArgv(['phase', 'add', 'desc'], registry);
+    expect(m).toEqual({ cmd: 'phase.add', args: ['desc'] });
+  });
+
+  it('prefers longer match over shorter', () => {
+    const registry = createRegistry();
+    const m = resolveQueryArgv(['state', 'load'], registry);
+    expect(m?.cmd).toBe('state.load');
+    expect(m?.args).toEqual([]);
+  });
+
+  it('returns null when no prefix matches', () => {
+    const registry = createRegistry();
+    const m = resolveQueryArgv(['totally-unknown', 'x'], registry);
+    expect(m).toBeNull();
+  });
+
+  it('matches a single dotted command token', () => {
+    const registry = createRegistry();
+    expect(resolveQueryArgv(['init.new-project'], registry)).toEqual({
+      cmd: 'init.new-project',
+      args: [],
+    });
+  });
+});

package/sdk/src/query/registry.ts

@@ -0,0 +1,174 @@
+/**
+ * Query command registry — routes commands to native SDK handlers.
+ *
+ * The registry is a flat `Map<string, QueryHandler>` that maps command names
+ * to handler functions. Unknown keys passed to `dispatch()` throw `GSDError`.
+ * The `gsd-remix-sdk query` CLI resolves argv with `resolveQueryArgv()` before dispatch;
+ * there is no automatic delegation to `gsd-tools.cjs`.
+ *
+ * Also exports `extractField` — a TypeScript port of the `--pick` field
+ * extraction logic from gsd-tools.cjs (lines 365-382).
+ *
+ * @example
+ * ```typescript
+ * import { QueryRegistry, extractField } from './registry.js';
+ *
+ * const registry = new QueryRegistry();
+ * registry.register('generate-slug', generateSlug);
+ * const result = await registry.dispatch('generate-slug', ['My Phase'], '/project');
+ * const slug = extractField(result.data, 'slug'); // 'my-phase'
+ * ```
+ */
+
+import type { QueryResult, QueryHandler } from './utils.js';
+import { GSDError, ErrorClassification } from '../errors.js';
+
+// ─── extractField ──────────────────────────────────────────────────────────
+
+/**
+ * Extract a nested field from an object using dot-notation and bracket syntax.
+ *
+ * Direct port of `extractField()` from gsd-tools.cjs (lines 365-382).
+ * Supports `a.b.c` dot paths, `items[0]` array indexing, and `items[-1]`
+ * negative indexing.
+ *
+ * @param obj - The object to extract from
+ * @param fieldPath - Dot-separated path with optional bracket notation
+ * @returns The extracted value, or undefined if the path doesn't resolve
+ */
+export function extractField(obj: unknown, fieldPath: string): unknown {
+  const parts = fieldPath.split('.');
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    const bracketMatch = part.match(/^(.+?)\[(-?\d+)]$/);
+    if (bracketMatch) {
+      const key = bracketMatch[1];
+      const index = parseInt(bracketMatch[2], 10);
+      current = (current as Record<string, unknown>)[key];
+      if (!Array.isArray(current)) return undefined;
+      current = index < 0 ? current[current.length + index] : current[index];
+    } else {
+      current = (current as Record<string, unknown>)[part];
+    }
+  }
+  return current;
+}
+
+// ─── QueryRegistry ─────────────────────────────────────────────────────────
+
+/**
+ * Flat command registry that routes query commands to native handlers.
+ *
+ * `dispatch()` throws `GSDError` for unknown command keys. The `gsd-remix-sdk query`
+ * CLI uses `resolveQueryArgv()` first; when no handler matches, it may shell out
+ * to `gsd-tools.cjs` (see `cli.ts` and `QUERY-HANDLERS.md` fallback policy).
+ */
+export class QueryRegistry {
+  private handlers = new Map<string, QueryHandler>();
+
+  /**
+   * Register a native handler for a command name.
+   *
+   * @param command - The command name (e.g., 'generate-slug', 'state.load')
+   * @param handler - The handler function to invoke
+   */
+  register(command: string, handler: QueryHandler): void {
+    this.handlers.set(command, handler);
+  }
+
+  /**
+   * Check if a command has a registered native handler.
+   *
+   * @param command - The command name to check
+   * @returns True if the command has a native handler
+   */
+  has(command: string): boolean {
+    return this.handlers.has(command);
+  }
+
+  /**
+   * List all registered command names (for tooling, pipelines, and tests).
+   */
+  commands(): string[] {
+    return Array.from(this.handlers.keys());
+  }
+
+  /**
+   * Get the handler for a command without dispatching.
+   *
+   * @param command - The command name to look up
+   * @returns The handler function, or undefined if not registered
+   */
+  getHandler(command: string): QueryHandler | undefined {
+    return this.handlers.get(command);
+  }
+
+  /**
+   * Dispatch a command to its registered native handler.
+   *
+   * @param command - The command name to dispatch
+   * @param args - Arguments to pass to the handler
+   * @param projectDir - The project directory for context
+   * @returns The query result from the handler
+   * @throws GSDError if no handler is registered for the command
+   */
+  async dispatch(command: string, args: string[], projectDir: string): Promise<QueryResult> {
+    const handler = this.handlers.get(command);
+    if (!handler) {
+      throw new GSDError(
+        `Unknown command: "${command}". No native handler registered.`,
+        ErrorClassification.Validation,
+      );
+    }
+    return handler(args, projectDir);
+  }
+}
+
+function expandSingleDottedToken(tokens: string[]): string[] {
+  if (tokens.length !== 1 || tokens[0].startsWith('--')) {
+    return tokens;
+  }
+  const t = tokens[0];
+  if (!t.includes('.')) {
+    return tokens;
+  }
+  return t.split('.');
+}
+
+function matchRegisteredPrefix(
+  tokens: string[],
+  registry: QueryRegistry,
+): { cmd: string; args: string[] } | null {
+  for (let i = tokens.length; i >= 1; i--) {
+    const head = tokens.slice(0, i);
+    const dotted = head.join('.');
+    const spaced = head.join(' ');
+    if (registry.has(dotted)) {
+      return { cmd: dotted, args: tokens.slice(i) };
+    }
+    if (registry.has(spaced)) {
+      return { cmd: spaced, args: tokens.slice(i) };
+    }
+  }
+  return null;
+}
+
+/**
+ * Map argv after `gsd-remix-sdk query` to a registered handler key and remaining args.
+ * Longest-prefix match on dotted (`a.b.c`) and spaced (`a b c`) keys; if no match,
+ * expands a single dotted token (`state.validate` → `state`, `validate`) and retries.
+ */
+export function resolveQueryArgv(
+  tokens: string[],
+  registry: QueryRegistry,
+): { cmd: string; args: string[] } | null {
+  let matched = matchRegisteredPrefix(tokens, registry);
+  if (!matched) {
+    const expanded = expandSingleDottedToken(tokens);
+    if (expanded !== tokens) {
+      matched = matchRegisteredPrefix(expanded, registry);
+    }
+  }
+  return matched;
+}

package/sdk/src/query/requirements-extract-from-plans.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Unit tests for requirements.extract-from-plans.
+ */
+
+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 { requirementsExtractFromPlans } from './requirements-extract-from-plans.js';
+
+const P1 = `---
+phase: 09-foundation
+requirements:
+  - REQ-A
+  - REQ-B
+---
+
+<objective>
+O
+</objective>
+<tasks><task type="auto"><name>T</name></task></tasks>
+`;
+
+const P2 = `---
+phase: 09-foundation
+requirements:
+  - REQ-B
+---
+
+<objective>
+O2
+</objective>
+<tasks><task type="auto"><name>T</name></task></tasks>
+`;
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'gsd-req-'));
+  const phaseDir = join(tmpDir, '.planning', 'phases', '09-foundation');
+  await mkdir(phaseDir, { recursive: true });
+  await writeFile(join(phaseDir, '09-01-PLAN.md'), P1);
+  await writeFile(join(phaseDir, '09-02-PLAN.md'), P2);
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('requirementsExtractFromPlans', () => {
+  it('dedupes requirements across plans', async () => {
+    const r = await requirementsExtractFromPlans(['9'], tmpDir);
+    const d = r.data as { requirements: string[]; by_plan: Record<string, string[]> };
+    expect(d.requirements.sort()).toEqual(['REQ-A', 'REQ-B']);
+    expect(d.by_plan['09-01'].sort()).toEqual(['REQ-A', 'REQ-B']);
+    expect(d.by_plan['09-02']).toEqual(['REQ-B']);
+  });
+});

package/sdk/src/query/requirements-extract-from-plans.ts

@@ -0,0 +1,86 @@
+/**
+ * requirements.extract-from-plans — aggregate `requirements` frontmatter across all plans in a phase.
+ */
+
+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,
+  planningPaths,
+} from './helpers.js';
+import type { QueryHandler } from './utils.js';
+
+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;
+  }
+}
+
+function normalizeReqList(v: unknown): string[] {
+  if (!v) return [];
+  if (Array.isArray(v)) return v.map((x) => String(x));
+  if (typeof v === 'string') return [v];
+  return [];
+}
+
+/**
+ * Args: `<phase>`
+ */
+export const requirementsExtractFromPlans: QueryHandler = async (args, projectDir) => {
+  const phase = args[0];
+  if (!phase) {
+    throw new GSDError('phase required', ErrorClassification.Validation);
+  }
+
+  const normalized = normalizePhaseName(phase);
+  const phaseDir = await resolvePhaseDir(phase, projectDir);
+  if (!phaseDir) {
+    return {
+      data: {
+        phase: normalized,
+        requirements: [] as string[],
+        by_plan: {} as Record<string, string[]>,
+        error: 'Phase not found',
+      },
+    };
+  }
+
+  const files = await readdir(phaseDir);
+  const planFiles = files.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md').sort();
+  const byPlan: Record<string, string[]> = {};
+  const seen = new Set<string>();
+
+  for (const planFile of planFiles) {
+    const planId =
+      planFile === 'PLAN.md' ? 'PLAN' : planFile.replace(/-PLAN\.md$/i, '').replace(/PLAN\.md$/i, '');
+    const content = await readFile(join(phaseDir, planFile), 'utf-8');
+    const fm = extractFrontmatter(content) as Record<string, unknown>;
+    const list = normalizeReqList(fm.requirements);
+    byPlan[planId] = list;
+    for (const r of list) {
+      seen.add(r);
+    }
+  }
+
+  return {
+    data: {
+      phase: normalized,
+      requirements: [...seen].sort(),
+      by_plan: byPlan,
+    },
+  };
+};

package/sdk/src/query/roadmap-update-plan-progress.ts

@@ -0,0 +1,132 @@
+/**
+ * roadmap.update-plan-progress — sync ROADMAP.md progress table + plan checkboxes
+ * from on-disk PLAN/SUMMARY counts for a phase.
+ *
+ * Port of `cmdRoadmapUpdatePlanProgress` from get-shit-done/bin/lib/roadmap.cjs
+ * (lines 257–354). Uses `findPhase` for disk stats and `readModifyWriteRoadmapMd`
+ * for atomic writes (same pattern as `phase.complete`).
+ */
+
+import { findPhase } from './phase.js';
+import { readModifyWriteRoadmapMd, replaceInCurrentMilestone } from './phase-lifecycle.js';
+import { existsSync } from 'node:fs';
+import { escapeRegex, planningPaths } from './helpers.js';
+import { GSDError, ErrorClassification } from '../errors.js';
+import type { QueryHandler } from './utils.js';
+
+export const roadmapUpdatePlanProgress: QueryHandler = async (args, projectDir) => {
+  const phaseNum = args[0];
+  if (!phaseNum) {
+    throw new GSDError('phase number required for roadmap update-plan-progress', ErrorClassification.Validation);
+  }
+
+  const phaseResult = await findPhase([phaseNum], projectDir);
+  const info = phaseResult.data as {
+    found: boolean;
+    plans: string[];
+    summaries: string[];
+  };
+
+  if (!info.found) {
+    throw new GSDError(`Phase ${phaseNum} not found`, ErrorClassification.Validation);
+  }
+
+  const planCount = info.plans.length;
+  const summaryCount = info.summaries.length;
+
+  if (planCount === 0) {
+    return {
+      data: {
+        updated: false,
+        reason: 'No plans found',
+        plan_count: 0,
+        summary_count: 0,
+      },
+    };
+  }
+
+  const isComplete = summaryCount >= planCount;
+  const status = isComplete ? 'Complete' : summaryCount > 0 ? 'In Progress' : 'Planned';
+  const today = new Date().toISOString().split('T')[0]!;
+
+  const roadmapPath = planningPaths(projectDir).roadmap;
+  if (!existsSync(roadmapPath)) {
+    return {
+      data: {
+        updated: false,
+        reason: 'ROADMAP.md not found',
+        plan_count: planCount,
+        summary_count: summaryCount,
+      },
+    };
+  }
+
+  await readModifyWriteRoadmapMd(projectDir, (roadmapContent) => {
+    const phaseEscaped = escapeRegex(phaseNum);
+
+    const tableRowPattern = new RegExp(
+      `^(\\|\\s*${phaseEscaped}\\.?\\s[^|]*(?:\\|[^\\n]*))$`,
+      'im',
+    );
+    const dateField = isComplete ? ` ${today} ` : '  ';
+    roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
+      const cells = fullRow.split('|').slice(1, -1);
+      if (cells.length === 5) {
+        cells[2] = ` ${summaryCount}/${planCount} `;
+        cells[3] = ` ${status.padEnd(11)}`;
+        cells[4] = dateField;
+      } else if (cells.length === 4) {
+        cells[1] = ` ${summaryCount}/${planCount} `;
+        cells[2] = ` ${status.padEnd(11)}`;
+        cells[3] = dateField;
+      }
+      return '|' + cells.join('|') + '|';
+    });
+
+    const planCountPattern = new RegExp(
+      `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`,
+      'i',
+    );
+    const planCountText = isComplete
+      ? `${summaryCount}/${planCount} plans complete`
+      : `${summaryCount}/${planCount} plans executed`;
+    roadmapContent = replaceInCurrentMilestone(roadmapContent, planCountPattern, `$1${planCountText}`);
+
+    if (isComplete) {
+      const checkboxPattern = new RegExp(
+        `(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}[:\\s][^\\n]*)`,
+        'i',
+      );
+      roadmapContent = replaceInCurrentMilestone(
+        roadmapContent,
+        checkboxPattern,
+        `$1x$2 (completed ${today})`,
+      );
+    }
+
+    const summaries = info.summaries;
+    for (const summaryFile of summaries) {
+      const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
+      if (!planId) continue;
+      const planEscaped = escapeRegex(planId);
+      const planCheckboxPattern = new RegExp(
+        `(-\\s*\\[) (\\]\\s*(?:\\*\\*)?${planEscaped}(?:\\*\\*)?)`,
+        'i',
+      );
+      roadmapContent = roadmapContent.replace(planCheckboxPattern, '$1x$2');
+    }
+
+    return roadmapContent;
+  });
+
+  return {
+    data: {
+      updated: true,
+      phase: phaseNum,
+      plan_count: planCount,
+      summary_count: summaryCount,
+      status,
+      complete: isComplete,
+    },
+  };
+};