@opengsd/get-shit-done-redux 1.0.0

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

@@ -0,0 +1,208 @@
+/**
+ * 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', undefined);
+    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('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: [],
+    });
+  });
+
+  // Regression: #2597 — dotted command token followed by positional args.
+  // Before the fix, argv like ['init.execute-phase', '1'] returned null because
+  // expansion only ran for single-token input.
+  it('matches a dotted command token when positional args follow (#2597)', () => {
+    const registry = createRegistry();
+    expect(resolveQueryArgv(['init.execute-phase', '1'], registry)).toEqual({
+      cmd: 'init.execute-phase',
+      args: ['1'],
+    });
+  });
+
+  it('matches dotted state.update with trailing args (#2597)', () => {
+    const registry = createRegistry();
+    expect(resolveQueryArgv(['state.update', 'status', 'X'], registry)).toEqual({
+      cmd: 'state.update',
+      args: ['status', 'X'],
+    });
+  });
+
+  it('matches dotted phase.add with trailing args (#2597)', () => {
+    const registry = createRegistry();
+    expect(resolveQueryArgv(['phase.add', 'desc'], registry)).toEqual({
+      cmd: 'phase.add',
+      args: ['desc'],
+    });
+  });
+});

package/sdk/src/query/registry.ts

@@ -0,0 +1,142 @@
+/**
+ * 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-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';
+import { resolveQueryTokens } from './query-command-resolution-strategy.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-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
+   * @param workstream - Optional workstream name to scope .planning paths
+   * @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, workstream?: 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, workstream);
+  }
+}
+
+/**
+ * Map argv after `gsd-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 {
+  const resolved = resolveQueryTokens(tokens, registry);
+  if (!resolved) return null;
+  return { cmd: resolved.cmd, args: resolved.args };
+}

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, workstream?: string): Promise<string | null> {
+  const phasesDir = planningPaths(projectDir, workstream).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, workstream) => {
+  const phase = args[0];
+  if (!phase) {
+    throw new GSDError('phase required', ErrorClassification.Validation);
+  }
+
+  const normalized = normalizePhaseName(phase);
+  const phaseDir = await resolvePhaseDir(phase, projectDir, workstream);
+  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,
+    },
+  };
+};