gsd-remix 1.0.0

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

@@ -0,0 +1,169 @@
+/**
+ * Unit tests for pipeline middleware.
+ *
+ * Tests wrapWithPipeline with dry-run mode, prepare/finalize callbacks,
+ * and normal execution passthrough.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, writeFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { QueryRegistry } from './registry.js';
+import { wrapWithPipeline } from './pipeline.js';
+import type { QueryResult } from './utils.js';
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'gsd-pipeline-'));
+  await mkdir(join(tmpDir, '.planning'), { recursive: true });
+  await writeFile(join(tmpDir, '.planning', 'STATE.md'), '# State\nstatus: idle\n');
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ─── Helper ───────────────────────────────────────────────────────────────
+
+function makeRegistry(): QueryRegistry {
+  const registry = new QueryRegistry();
+  registry.register('read-cmd', async (_args, _dir) => ({ data: { read: true } }));
+  registry.register('mut-cmd', async (_args, dir) => {
+    // Simulate a mutation: write a file to the project dir
+    const { writeFile: wf } = await import('node:fs/promises');
+    await wf(join(dir, '.planning', 'MUTATED.md'), '# mutated');
+    return { data: { mutated: true } };
+  });
+  return registry;
+}
+
+const MUTATION_SET = new Set(['mut-cmd']);
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe('wrapWithPipeline — passthrough (no options)', () => {
+  it('read command passes through normally', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, {});
+    const result = await registry.dispatch('read-cmd', [], tmpDir);
+    expect((result.data as Record<string, unknown>).read).toBe(true);
+  });
+
+  it('mutation command executes and writes to disk when dryRun=false', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, { dryRun: false });
+    const result = await registry.dispatch('mut-cmd', [], tmpDir);
+    expect((result.data as Record<string, unknown>).mutated).toBe(true);
+    // File should have been written to the real dir
+    const { existsSync } = await import('node:fs');
+    expect(existsSync(join(tmpDir, '.planning', 'MUTATED.md'))).toBe(true);
+  });
+});
+
+describe('wrapWithPipeline — dry-run mode', () => {
+  it('dry-run mutation returns diff without writing to disk', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, { dryRun: true });
+    const result = await registry.dispatch('mut-cmd', [], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    // Should be a dry-run result
+    expect(data.dry_run).toBe(true);
+    expect(data.command).toBe('mut-cmd');
+    expect(data.diff).toBeDefined();
+    expect(typeof data.changes_summary).toBe('string');
+
+    // Real project should NOT have been written to
+    const { existsSync } = await import('node:fs');
+    expect(existsSync(join(tmpDir, '.planning', 'MUTATED.md'))).toBe(false);
+  });
+
+  it('dry-run diff contains before/after for changed files', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, { dryRun: true });
+    const result = await registry.dispatch('mut-cmd', [], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const diff = data.diff as Record<string, { before: string | null; after: string | null }>;
+
+    // MUTATED.md is a new file — before should be null
+    const mutatedKey = Object.keys(diff).find(k => k.includes('MUTATED'));
+    expect(mutatedKey).toBeDefined();
+    expect(diff[mutatedKey!].before).toBeNull();
+    expect(diff[mutatedKey!].after).toBe('# mutated');
+  });
+
+  it('dry-run read command executes normally (side-effect-free)', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, { dryRun: true });
+    // read-cmd is NOT in MUTATION_SET, so it's not wrapped at all
+    const result = await registry.dispatch('read-cmd', [], tmpDir);
+    expect((result.data as Record<string, unknown>).read).toBe(true);
+  });
+
+  it('dry-run changes_summary reflects number of changed files', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, { dryRun: true });
+    const result = await registry.dispatch('mut-cmd', [], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.changes_summary).toContain('1 file');
+  });
+});
+
+describe('wrapWithPipeline — prepare/finalize callbacks', () => {
+  it('onPrepare fires before mutation execution', async () => {
+    const registry = makeRegistry();
+    const preparedCommands: string[] = [];
+    wrapWithPipeline(registry, MUTATION_SET, {
+      onPrepare: async (cmd) => { preparedCommands.push(cmd); },
+    });
+    await registry.dispatch('mut-cmd', ['arg1'], tmpDir);
+    expect(preparedCommands).toContain('mut-cmd');
+  });
+
+  it('onFinalize fires after mutation with result', async () => {
+    const registry = makeRegistry();
+    let capturedResult: QueryResult | null = null;
+    wrapWithPipeline(registry, MUTATION_SET, {
+      onFinalize: async (_cmd, _args, result) => { capturedResult = result; },
+    });
+    await registry.dispatch('mut-cmd', [], tmpDir);
+    expect(capturedResult).not.toBeNull();
+  });
+
+  it('onPrepare receives correct args', async () => {
+    const registry = makeRegistry();
+    let capturedArgs: string[] = [];
+    wrapWithPipeline(registry, MUTATION_SET, {
+      onPrepare: async (_cmd, args) => { capturedArgs = args; },
+    });
+    await registry.dispatch('mut-cmd', ['foo', 'bar'], tmpDir);
+    expect(capturedArgs).toEqual(['foo', 'bar']);
+  });
+
+  it('onFinalize fires even in dry-run mode', async () => {
+    const registry = makeRegistry();
+    let finalizeCalled = false;
+    wrapWithPipeline(registry, MUTATION_SET, {
+      dryRun: true,
+      onFinalize: async () => { finalizeCalled = true; },
+    });
+    await registry.dispatch('mut-cmd', [], tmpDir);
+    expect(finalizeCalled).toBe(true);
+  });
+});
+
+describe('wrapWithPipeline — unregistered command passthrough', () => {
+  it('commands not in mutation set are not wrapped', async () => {
+    const registry = makeRegistry();
+    const spy = vi.fn(async (_args: string[], _dir: string): Promise<QueryResult> => ({ data: { value: 42 } }));
+    registry.register('other-cmd', spy);
+    wrapWithPipeline(registry, MUTATION_SET, {
+      onPrepare: async () => { /* should not fire for non-mutation */ },
+    });
+    const result = await registry.dispatch('other-cmd', [], tmpDir);
+    // Since other-cmd is not in MUTATION_SET, it's not wrapped
+    expect((result.data as Record<string, unknown>).value).toBe(42);
+  });
+});

package/sdk/src/query/pipeline.ts

@@ -0,0 +1,243 @@
+/**
+ * Staged execution pipeline — registry-level middleware for pre/post hooks
+ * and full in-memory dry-run support.
+ *
+ * Wraps all registry handlers with prepare/execute/finalize stages.
+ * When dryRun=true and the command is a mutation, the mutation executes
+ * against a temporary directory clone of .planning/ instead of the real
+ * project, and the before/after diff is returned without writing to disk.
+ *
+ * Read commands are always executed normally — they are side-effect-free.
+ *
+ * @example
+ * ```typescript
+ * import { createRegistry } from './index.js';
+ * import { wrapWithPipeline } from './pipeline.js';
+ *
+ * const registry = createRegistry();
+ * wrapWithPipeline(registry, MUTATION_COMMANDS, { dryRun: true });
+ * // mutations now return { data: { dry_run: true, diff: { ... } } }
+ * ```
+ */
+
+import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import type { QueryResult } from './utils.js';
+import type { QueryRegistry } from './registry.js';
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+/**
+ * Configuration for the pipeline middleware.
+ */
+export interface PipelineOptions {
+  /** When true, mutations execute against a temp clone and return a diff */
+  dryRun?: boolean;
+  /** Called before each handler invocation */
+  onPrepare?: (command: string, args: string[], projectDir: string) => Promise<void>;
+  /** Called after each handler invocation */
+  onFinalize?: (command: string, args: string[], result: QueryResult) => Promise<void>;
+}
+
+/**
+ * A single stage in the execution pipeline.
+ */
+export type PipelineStage = 'prepare' | 'execute' | 'finalize';
+
+// ─── Internal helpers ──────────────────────────────────────────────────────
+
+/**
+ * Recursively collect all files under a directory.
+ * Returns paths relative to the base directory.
+ */
+function collectFiles(dir: string, base: string): string[] {
+  const results: string[] = [];
+  if (!existsSync(dir)) return results;
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    const relPath = relative(base, fullPath);
+    if (entry.isFile()) {
+      results.push(relPath);
+    } else if (entry.isDirectory()) {
+      results.push(...collectFiles(fullPath, base));
+    }
+  }
+  return results;
+}
+
+/**
+ * Copy .planning/ subtree from sourceDir to destDir.
+ * Only copies text files relevant to GSD state (skips binaries and logs).
+ */
+async function copyPlanningTree(sourceDir: string, destDir: string): Promise<void> {
+  const planningSource = join(sourceDir, '.planning');
+  if (!existsSync(planningSource)) return;
+
+  const files = collectFiles(planningSource, planningSource);
+  for (const relFile of files) {
+    // Skip large or binary-ish files (> 1MB) — only relevant for text state
+    const sourcePath = join(planningSource, relFile);
+    const destPath = join(destDir, '.planning', relFile);
+    await mkdir(dirname(destPath), { recursive: true });
+    try {
+      const content = await readFile(sourcePath, 'utf-8');
+      await writeFile(destPath, content, 'utf-8');
+    } catch {
+      // Skip unreadable files (binary, permission issues, etc.)
+    }
+  }
+}
+
+/**
+ * Read all files from .planning/ in a directory into a map of relPath → content.
+ */
+async function readPlanningState(projectDir: string): Promise<Map<string, string>> {
+  const planningDir = join(projectDir, '.planning');
+  const result = new Map<string, string>();
+  if (!existsSync(planningDir)) return result;
+
+  const files = collectFiles(planningDir, planningDir);
+  for (const relFile of files) {
+    try {
+      const content = await readFile(join(planningDir, relFile), 'utf-8');
+      result.set(relFile, content);
+    } catch { /* skip unreadable */ }
+  }
+  return result;
+}
+
+/**
+ * Diff two file maps, returning files that changed (with before/after content).
+ */
+function diffPlanningState(
+  before: Map<string, string>,
+  after: Map<string, string>,
+): Record<string, { before: string | null; after: string | null }> {
+  const diff: Record<string, { before: string | null; after: string | null }> = {};
+  const allKeys = new Set([...before.keys(), ...after.keys()]);
+  for (const key of allKeys) {
+    const b = before.get(key) ?? null;
+    const a = after.get(key) ?? null;
+    if (b !== a) {
+      diff[`.planning/${key}`] = { before: b, after: a };
+    }
+  }
+  return diff;
+}
+
+// ─── wrapWithPipeline ──────────────────────────────────────────────────────
+
+/**
+ * Wrap all registered handlers with prepare/execute/finalize pipeline stages.
+ *
+ * When dryRun=true and a mutation command is dispatched, the real projectDir
+ * is cloned (only .planning/ subtree) into a temp directory. The mutation
+ * runs against the clone, a before/after diff is computed, and the temp
+ * directory is cleaned up in a finally block. The real project is never
+ * touched during a dry run.
+ *
+ * @param registry - The registry whose handlers to wrap
+ * @param mutationCommands - Set of command names that perform mutations
+ * @param options - Pipeline configuration
+ */
+export function wrapWithPipeline(
+  registry: QueryRegistry,
+  mutationCommands: Set<string>,
+  options: PipelineOptions,
+): void {
+  const { dryRun = false, onPrepare, onFinalize } = options;
+
+  // Collect all currently registered commands by iterating known handlers
+  // We wrap by re-registering with the same name using the same technique
+  // as event emission wiring in index.ts
+  const commandsToWrap: string[] = [];
+
+  // Enumerate mutation commands via the caller-provided set. QueryRegistry also
+  // exposes commands() for full command lists when needed by tooling.
+  // We wrap the register method temporarily to collect known commands,
+  // then restore. Instead, we use the mutation commands set + a marker approach:
+  // wrap mutation commands for dry-run, and wrap all via onPrepare/onFinalize.
+  //
+  // For pipeline wrapping we use a two-pass approach:
+  // Pass 1: wrap mutation commands (for dry-run + hooks)
+  // Pass 2: wrap non-mutation commands (for hooks only, if hooks provided)
+
+  const wrapHandler = (cmd: string, isMutation: boolean): void => {
+    const original = registry.getHandler(cmd);
+    if (!original) return;
+
+    registry.register(cmd, async (args: string[], projectDir: string) => {
+      // ─── Prepare stage ───────────────────────────────────────────────
+      if (onPrepare) {
+        await onPrepare(cmd, args, projectDir);
+      }
+
+      let result: QueryResult;
+
+      if (dryRun && isMutation) {
+        // ─── Dry-run: clone → mutate → diff ──────────────────────────
+        let tempDir: string | null = null;
+        try {
+          tempDir = await mkdtemp(join(tmpdir(), 'gsd-dryrun-'));
+
+          // Snapshot state before mutation
+          const beforeState = await readPlanningState(projectDir);
+
+          // Copy .planning/ to temp dir
+          await copyPlanningTree(projectDir, tempDir);
+
+          // Execute mutation against temp dir clone
+          await original(args, tempDir);
+
+          // Snapshot state after mutation (from temp dir)
+          const afterState = await readPlanningState(tempDir);
+
+          // Compute diff
+          const diff = diffPlanningState(beforeState, afterState);
+          const changedFiles = Object.keys(diff);
+
+          result = {
+            data: {
+              dry_run: true,
+              command: cmd,
+              args,
+              diff,
+              changes_summary: changedFiles.length > 0
+                ? `${changedFiles.length} file(s) would be modified: ${changedFiles.join(', ')}`
+                : 'No files would be modified',
+            },
+          };
+        } finally {
+          // T-14-06: Always clean up temp dir, even on error
+          if (tempDir) {
+            await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+          }
+        }
+      } else {
+        // ─── Normal execution ─────────────────────────────────────────
+        result = await original(args, projectDir);
+      }
+
+      // ─── Finalize stage ───────────────────────────────────────────────
+      if (onFinalize) {
+        await onFinalize(cmd, args, result);
+      }
+
+      return result;
+    });
+
+    commandsToWrap.push(cmd);
+  };
+
+  // Wrap mutation commands (dry-run eligible + hooks)
+  for (const cmd of mutationCommands) {
+    wrapHandler(cmd, true);
+  }
+
+  // Note: non-mutation commands are NOT wrapped here for performance — callers
+  // can provide onPrepare/onFinalize for mutations only. If full wrapping of
+  // read commands is needed, callers should pass their command set explicitly.
+}

package/sdk/src/query/plan-execution-route.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Unit tests for plan.execution-route.
+ */
+
+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 { planExecutionRoute } from './plan-execution-route.js';
+
+let tmpDir: string;
+let phaseDir: string;
+
+function makeTask(index: number, options?: {
+  type?: string;
+  files?: string[];
+  readFirst?: string[];
+  acceptance?: string[];
+}): string {
+  const type = options?.type ?? 'auto';
+  const files = (options?.files ?? [`src/file-${index}.ts`]).join(', ');
+  const readFirst = (options?.readFirst ?? []).join(', ');
+  const acceptance = options?.acceptance ?? [];
+  return `<task type="${type}">
+  <name>Task ${index}</name>
+  <files>${files}</files>
+  <read_first>${readFirst}</read_first>
+  <action>Do task ${index}</action>
+  <verify>echo ok</verify>
+  <acceptance_criteria>
+${acceptance.map((criterion) => `    - ${criterion}`).join('\n')}
+  </acceptance_criteria>
+  <done>done</done>
+</task>`;
+}
+
+function makePlan(options: {
+  autonomous?: boolean;
+  filesModified?: string[];
+  tasks: string[];
+}): string {
+  return `---
+phase: 09-foundation
+plan: "01"
+wave: 1
+depends_on: []
+files_modified: [${(options.filesModified ?? []).join(', ')}]
+autonomous: ${options.autonomous ?? true}
+---
+
+<objective>
+Route this plan
+</objective>
+
+<tasks>
+${options.tasks.join('\n')}
+</tasks>
+`;
+}
+
+async function writePlan(content: string): Promise<string> {
+  const rel = join('.planning', 'phases', '09-x', '09-01-PLAN.md');
+  await writeFile(join(tmpDir, rel), content, 'utf-8');
+  return rel;
+}
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'gsd-per-'));
+  phaseDir = join(tmpDir, '.planning', 'phases', '09-x');
+  await mkdir(phaseDir, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('planExecutionRoute', () => {
+  it('uses threshold inline routing for plans at or below the configured threshold', async () => {
+    const rel = await writePlan(makePlan({
+      filesModified: ['src/a.ts', 'src/b.ts'],
+      tasks: [
+        makeTask(1, { acceptance: ['criterion 1'] }),
+        makeTask(2, { acceptance: ['criterion 2'] }),
+      ],
+    }));
+
+    const r = await planExecutionRoute([rel, '--inline-threshold', '2'], tmpDir);
+    const d = r.data as Record<string, unknown>;
+
+    expect(d.recommended_pattern).toBe('C');
+    expect(d.recommended_execution).toBe('main-inline');
+    expect(d.reason).toBe('task_count_threshold');
+  });
+
+  it('applies low-complexity override for simple 4-task plans above the threshold', async () => {
+    const rel = await writePlan(makePlan({
+      filesModified: ['src/a.ts', 'src/b.ts', 'src/c.ts'],
+      tasks: [
+        makeTask(1, { files: ['src/a.ts'], readFirst: ['src/base.ts'], acceptance: ['a1'] }),
+        makeTask(2, { files: ['src/b.ts'], acceptance: ['b1'] }),
+        makeTask(3, { files: ['src/c.ts'], acceptance: ['c1'] }),
+        makeTask(4, { files: ['src/c.ts'], acceptance: ['c2'] }),
+      ],
+    }));
+
+    const r = await planExecutionRoute([rel, '--inline-threshold', '2'], tmpDir);
+    const d = r.data as Record<string, unknown>;
+
+    expect(d.low_complexity_inline).toBe(true);
+    expect(d.recommended_pattern).toBe('C');
+    expect(d.reason).toBe('low_complexity_override');
+  });
+
+  it('keeps complex 4-task plans on the subagent route', async () => {
+    const rel = await writePlan(makePlan({
+      filesModified: ['src/a.ts', 'src/b.ts', 'src/c.ts', 'src/d.ts', 'src/e.ts'],
+      tasks: [
+        makeTask(1, { files: ['src/a.ts'], readFirst: ['src/r1.ts', 'src/r2.ts'], acceptance: ['a1', 'a2'] }),
+        makeTask(2, { files: ['src/b.ts'], readFirst: ['src/r3.ts', 'src/r4.ts'], acceptance: ['b1', 'b2'] }),
+        makeTask(3, { files: ['src/c.ts'], readFirst: ['src/r5.ts'], acceptance: ['c1'] }),
+        makeTask(4, { files: ['src/d.ts', 'src/e.ts'], acceptance: ['d1'] }),
+      ],
+    }));
+
+    const r = await planExecutionRoute([rel, '--inline-threshold', '2'], tmpDir);
+    const d = r.data as Record<string, unknown>;
+
+    expect(d.low_complexity_inline).toBe(false);
+    expect(d.recommended_pattern).toBe('A');
+    expect(d.reason).toBe('autonomous_default');
+  });
+
+  it('routes verify-only checkpoints to segmented execution', async () => {
+    const rel = await writePlan(makePlan({
+      tasks: [
+        makeTask(1),
+        makeTask(2, { type: 'checkpoint:human-verify' }),
+        makeTask(3),
+      ],
+    }));
+
+    const r = await planExecutionRoute([rel, '--inline-threshold', '2'], tmpDir);
+    const d = r.data as Record<string, unknown>;
+
+    expect(d.checkpoint_mode).toBe('verify_only');
+    expect(d.recommended_pattern).toBe('B');
+    expect(d.reason).toBe('verify_checkpoints');
+  });
+
+  it('routes decision checkpoints to main inline execution', async () => {
+    const rel = await writePlan(makePlan({
+      tasks: [
+        makeTask(1),
+        makeTask(2, { type: 'checkpoint:decision' }),
+        makeTask(3),
+      ],
+    }));
+
+    const r = await planExecutionRoute([rel, '--inline-threshold', '2'], tmpDir);
+    const d = r.data as Record<string, unknown>;
+
+    expect(d.checkpoint_mode).toBe('decision_or_action');
+    expect(d.recommended_pattern).toBe('C');
+    expect(d.reason).toBe('decision_checkpoint');
+  });
+});