@opengsd/get-shit-done-redux 1.0.0

package/sdk/src/gsd-tools.ts

@@ -0,0 +1,237 @@
+/**
+ * GSD Tools Bridge — programmatic access to GSD planning operations.
+ *
+ * By default routes commands through the SDK **query registry** (same handlers as
+ * `gsd-sdk query`) so `PhaseRunner`, `InitRunner`, and `GSD` share contracts with
+ * the typed CLI. Runner hot-path helpers (`initPhaseOp`, `phasePlanIndex`,
+ * `phaseComplete`, `initNewProject`, `configSet`, `commit`) call
+ * `registry.dispatch()` with canonical keys when native query is active, avoiding
+ * repeated argv resolution. When a workstream is set, dispatches to `gsd-tools.cjs` so
+ * workstream env stays aligned with CJS.
+ */
+
+
+import type { InitNewProjectInfo, PhaseOpInfo, PhasePlanIndex, RoadmapAnalysis } from './types.js';
+import type { GSDEventStream } from './event-stream.js';
+import { toToolsErrorFromUnknown } from './query-tools-error-factory.js';
+import { GSDToolsError } from './gsd-tools-error.js';
+import type { QueryCommandResolution } from './query/query-command-resolution-strategy.js';
+import { resolveGsdToolsPath } from './query-gsd-tools-path.js';
+import { createGSDToolsRuntime } from './query-gsd-tools-runtime.js';
+import { QueryCommandExecutor } from './query-command-executor.js';
+import { QueryHotpathMethods } from './query-hotpath-methods.js';
+import { QueryRuntimeBridge, type RuntimeBridgeOptions } from './query-runtime-bridge.js';
+
+export { GSDToolsError } from './gsd-tools-error.js';
+
+// ─── GSDTools class ──────────────────────────────────────────────────────────
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+
+export class GSDTools {
+  private readonly projectDir: string;
+  private readonly gsdToolsPath: string;
+  private readonly timeoutMs: number;
+  private readonly workstream?: string;
+  private readonly bridge: QueryRuntimeBridge;
+  private readonly preferNativeQuery: boolean;
+  private readonly commandExecutor: QueryCommandExecutor;
+  private readonly hotpathMethods: QueryHotpathMethods;
+
+  constructor(opts: {
+    projectDir: string;
+    gsdToolsPath?: string;
+    timeoutMs?: number;
+    workstream?: string;
+    /** When set, mutation handlers emit the same events as `gsd-sdk query`. */
+    eventStream?: GSDEventStream;
+    /** Correlation id for mutation events when `eventStream` is set. */
+    sessionId?: string;
+    /**
+     * When true (default), route known commands through the SDK query registry.
+     * Set false in tests that substitute a mock `gsdToolsPath` script.
+     */
+    preferNativeQuery?: boolean;
+    /** When true, fail if a command has no native registry adapter. */
+    strictSdk?: boolean;
+    /** Explicit subprocess bridge policy. Default false for SDK-native mode. */
+    allowFallbackToSubprocess?: boolean;
+    /** Structured runtime bridge dispatch observability callback. */
+    onDispatchEvent?: RuntimeBridgeOptions['onDispatchEvent'];
+  }) {
+    this.projectDir = opts.projectDir;
+    this.gsdToolsPath =
+      opts.gsdToolsPath ?? resolveGsdToolsPath(opts.projectDir);
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.workstream = opts.workstream;
+    this.preferNativeQuery = opts.preferNativeQuery ?? true;
+
+    const runtime = createGSDToolsRuntime({
+      projectDir: this.projectDir,
+      gsdToolsPath: this.gsdToolsPath,
+      timeoutMs: this.timeoutMs,
+      workstream: this.workstream,
+      eventStream: opts.eventStream,
+      sessionId: opts.sessionId,
+      shouldUseNativeQuery: () => this.shouldUseNativeQuery(),
+      execJsonFallback: (legacyCommand, legacyArgs) => this.exec(legacyCommand, legacyArgs),
+      execRawFallback: (legacyCommand, legacyArgs) => this.execRaw(legacyCommand, legacyArgs),
+      strictSdk: opts.strictSdk,
+      allowFallbackToSubprocess: opts.allowFallbackToSubprocess,
+      onDispatchEvent: opts.onDispatchEvent,
+    });
+
+    this.bridge = runtime.bridge;
+    this.commandExecutor = new QueryCommandExecutor({
+      nativeMatch: (command, args) => this.nativeMatch(command, args),
+      execute: async (input) => this.bridge.execute({
+        legacyCommand: input.legacyCommand,
+        legacyArgs: input.legacyArgs,
+        registryCommand: input.registryCommand,
+        registryArgs: input.registryArgs,
+        mode: input.mode,
+        projectDir: this.projectDir,
+        workstream: this.workstream,
+      }),
+    });
+
+    this.hotpathMethods = new QueryHotpathMethods({
+      dispatchNativeHotpath: (legacyCommand, legacyArgs, registryCommand, registryArgs, mode) =>
+        this.dispatchNativeHotpath(legacyCommand, legacyArgs, registryCommand, registryArgs, mode),
+    });
+  }
+
+  private shouldUseNativeQuery(): boolean {
+    return this.preferNativeQuery && !this.workstream;
+  }
+
+  private nativeMatch(command: string, args: string[]): QueryCommandResolution | null {
+    return this.bridge.resolve(command, args);
+  }
+
+  private async dispatchNativeHotpath(
+    legacyCommand: string,
+    legacyArgs: string[],
+    registryCommand: string,
+    registryArgs: string[],
+    mode: 'json' | 'raw',
+  ): Promise<unknown> {
+    return this.executeWithToolsError(legacyCommand, legacyArgs, () =>
+      this.bridge.dispatchHotpath(
+        legacyCommand,
+        legacyArgs,
+        registryCommand,
+        registryArgs,
+        mode,
+      ));
+  }
+
+  private async executeWithToolsError<T>(command: string, args: string[], work: () => Promise<T>): Promise<T> {
+    try {
+      return await work();
+    } catch (err) {
+      if (err instanceof GSDToolsError) throw err;
+      throw toToolsErrorFromUnknown(command, args, err);
+    }
+  }
+
+  // ─── Core exec ───────────────────────────────────────────────────────────
+
+  /**
+   * Execute a gsd-tools command and return parsed JSON output.
+   * Handles the `@file:` prefix pattern for large results.
+   */
+  async exec(command: string, args: string[] = []): Promise<unknown> {
+    return this.executeWithToolsError(command, args, () => this.commandExecutor.exec(command, args, 'json'));
+  }
+
+  // ─── Raw exec (no JSON parsing) ───────────────────────────────────────
+
+  /**
+   * Execute a gsd-tools command and return raw stdout without JSON parsing.
+   * Use for commands like `config-set` that return plain text, not JSON.
+   */
+  async execRaw(command: string, args: string[] = []): Promise<string> {
+    return this.executeWithToolsError(command, args, async () => {
+      const out = await this.commandExecutor.exec(command, args, 'raw');
+      return typeof out === 'string' ? out : String(out ?? '');
+    });
+  }
+
+
+  // ─── Typed convenience methods ─────────────────────────────────────────
+
+  async stateLoad(): Promise<unknown> {
+    return this.exec('state', ['load']);
+  }
+
+  async roadmapAnalyze(): Promise<RoadmapAnalysis> {
+    return this.exec('roadmap', ['analyze']) as Promise<RoadmapAnalysis>;
+  }
+
+  async phaseComplete(phase: string): Promise<string> {
+    return this.hotpathMethods.phaseComplete(phase);
+  }
+
+  async commit(message: string, files?: string[]): Promise<string> {
+    return this.hotpathMethods.commit(message, files);
+  }
+
+  async verifySummary(path: string): Promise<string> {
+    return this.execRaw('verify-summary', [path]);
+  }
+
+  async initExecutePhase(phase: string): Promise<string> {
+    return this.execRaw('state', ['begin-phase', '--phase', phase]);
+  }
+
+  /**
+   * Query phase state from gsd-tools.cjs `init phase-op`.
+   * Returns a typed PhaseOpInfo describing what exists on disk for this phase.
+   */
+  async initPhaseOp(phaseNumber: string): Promise<PhaseOpInfo> {
+    return this.hotpathMethods.initPhaseOp(phaseNumber);
+  }
+
+  /**
+   * Get a config value via the `config-get` surface (CJS and registry use the same key path).
+   */
+  async configGet(key: string): Promise<string | null> {
+    return this.hotpathMethods.configGet(key);
+  }
+
+  /**
+   * Begin phase state tracking in gsd-tools.cjs.
+   */
+  async stateBeginPhase(phaseNumber: string): Promise<string> {
+    return this.execRaw('state', ['begin-phase', '--phase', phaseNumber]);
+  }
+
+  /**
+   * Get the plan index for a phase, grouping plans into dependency waves.
+   * Returns typed PhasePlanIndex with wave assignments and completion status.
+   */
+  async phasePlanIndex(phaseNumber: string): Promise<PhasePlanIndex> {
+    return this.hotpathMethods.phasePlanIndex(phaseNumber);
+  }
+
+  /**
+   * Query new-project init state from gsd-tools.cjs `init new-project`.
+   * Returns project metadata, model configs, brownfield detection, etc.
+   */
+  async initNewProject(): Promise<InitNewProjectInfo> {
+    return this.hotpathMethods.initNewProject();
+  }
+
+  /**
+   * Set a config value via gsd-tools.cjs `config-set`.
+   * Handles type coercion (booleans, numbers, JSON) on the gsd-tools side.
+   * Note: config-set returns `key=value` text, not JSON, so we use execRaw.
+   */
+  async configSet(key: string, value: string): Promise<string> {
+    return this.hotpathMethods.configSet(key, value);
+  }
+}
+
+export { resolveGsdToolsPath } from './query-gsd-tools-path.js';

package/sdk/src/gsd-transport-policy.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { resolveTransportPolicy, setTransportPolicy, clearTransportPolicy } from './gsd-transport-policy.js';
+
+describe('gsd-transport-policy', () => {
+  afterEach(() => {
+    clearTransportPolicy();
+  });
+
+  it('uses legacy-safe defaults for unknown command', () => {
+    const policy = resolveTransportPolicy('unknown-cmd');
+    expect(policy.preferNative).toBe(true);
+    expect(policy.allowFallbackToSubprocess).toBe(true);
+    expect(policy.outputMode).toBe('json');
+  });
+
+  it('applies built-in raw output override', () => {
+    const policy = resolveTransportPolicy('config-set');
+    expect(policy.outputMode).toBe('raw');
+    expect(policy.allowFallbackToSubprocess).toBe(true);
+  });
+
+  it('applies verify-summary alias raw overrides', () => {
+    expect(resolveTransportPolicy('verify-summary').outputMode).toBe('raw');
+    expect(resolveTransportPolicy('verify.summary').outputMode).toBe('raw');
+    expect(resolveTransportPolicy('verify summary').outputMode).toBe('raw');
+  });
+
+  it('supports per-command override updates', () => {
+    setTransportPolicy('state', { allowFallbackToSubprocess: false, outputMode: 'raw' });
+    const policy = resolveTransportPolicy('state');
+    expect(policy.allowFallbackToSubprocess).toBe(false);
+    expect(policy.outputMode).toBe('raw');
+  });
+});

package/sdk/src/gsd-transport-policy.ts

@@ -0,0 +1,48 @@
+import { TRANSPORT_RAW_COMMANDS } from './query/query-policy-capability.js';
+
+export type TransportMode = 'json' | 'raw';
+
+export interface TransportPolicy {
+  preferNative: boolean;
+  allowFallbackToSubprocess: boolean;
+  outputMode: TransportMode;
+}
+
+const DEFAULT_POLICY: TransportPolicy = {
+  preferNative: true,
+  allowFallbackToSubprocess: true,
+  outputMode: 'json',
+};
+
+const BUILTIN_COMMAND_POLICY: Record<string, Partial<TransportPolicy>> = Object.fromEntries(
+  TRANSPORT_RAW_COMMANDS.map((command) => [command, { outputMode: 'raw' as const }]),
+);
+
+const COMMAND_POLICY_OVERRIDES: Record<string, Partial<TransportPolicy>> = {};
+
+export function resolveTransportPolicy(command: string): TransportPolicy {
+  const override = {
+    ...(BUILTIN_COMMAND_POLICY[command] ?? {}),
+    ...(COMMAND_POLICY_OVERRIDES[command] ?? {}),
+  };
+  return {
+    preferNative: override.preferNative ?? DEFAULT_POLICY.preferNative,
+    allowFallbackToSubprocess:
+      override.allowFallbackToSubprocess ?? DEFAULT_POLICY.allowFallbackToSubprocess,
+    outputMode: override.outputMode ?? DEFAULT_POLICY.outputMode,
+  };
+}
+
+export function setTransportPolicy(command: string, override: Partial<TransportPolicy>): void {
+  COMMAND_POLICY_OVERRIDES[command] = { ...(COMMAND_POLICY_OVERRIDES[command] ?? {}), ...override };
+}
+
+export function clearTransportPolicy(command?: string): void {
+  if (command) {
+    delete COMMAND_POLICY_OVERRIDES[command];
+    return;
+  }
+  for (const key of Object.keys(COMMAND_POLICY_OVERRIDES)) {
+    delete COMMAND_POLICY_OVERRIDES[key];
+  }
+}

package/sdk/src/gsd-transport.test.ts

@@ -0,0 +1,299 @@
+import { describe, it, expect, vi } from 'vitest';
+import { GSDToolsError } from './gsd-tools-error.js';
+import { QueryRegistry } from './query/registry.js';
+import { GSDTransport } from './gsd-transport.js';
+
+describe('GSDTransport', () => {
+  it('uses native adapter when command registered and policy prefers native', async () => {
+    const registry = new QueryRegistry();
+    registry.register('state.load', async () => ({ data: { ok: true } }));
+
+    const adapters = {
+      dispatchNative: vi.fn(async () => ({ data: { ok: true } })),
+      execSubprocessJson: vi.fn(async () => ({ ok: false })),
+      execSubprocessRaw: vi.fn(async () => 'subprocess'),
+    };
+
+    const transport = new GSDTransport(registry, adapters);
+    const result = await transport.run({
+      legacyCommand: 'state',
+      legacyArgs: ['load'],
+      registryCommand: 'state.load',
+      registryArgs: [],
+      mode: 'json',
+      projectDir: '/tmp',
+    }, {
+      preferNative: true,
+      allowFallbackToSubprocess: true,
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(adapters.dispatchNative).toHaveBeenCalledOnce();
+    expect(adapters.execSubprocessJson).not.toHaveBeenCalled();
+  });
+
+  it('falls back to subprocess when native throws and policy allows fallback', async () => {
+    const registry = new QueryRegistry();
+    registry.register('state.load', async () => ({ data: { ok: true } }));
+
+    const adapters = {
+      dispatchNative: vi.fn(async () => {
+        throw new Error('native failed');
+      }),
+      execSubprocessJson: vi.fn(async () => ({ ok: 'fallback' })),
+      execSubprocessRaw: vi.fn(async () => 'fallback-raw'),
+    };
+
+    const transport = new GSDTransport(registry, adapters);
+    const result = await transport.run({
+      legacyCommand: 'state',
+      legacyArgs: ['load'],
+      registryCommand: 'state.load',
+      registryArgs: [],
+      mode: 'json',
+      projectDir: '/tmp',
+    }, {
+      preferNative: true,
+      allowFallbackToSubprocess: true,
+    });
+
+    expect(result).toEqual({ ok: 'fallback' });
+    expect(adapters.dispatchNative).toHaveBeenCalledOnce();
+    expect(adapters.execSubprocessJson).toHaveBeenCalledOnce();
+  });
+
+  it('hard-fails when native throws and fallback disabled', async () => {
+    const registry = new QueryRegistry();
+    registry.register('state.load', async () => ({ data: { ok: true } }));
+
+    const adapters = {
+      dispatchNative: vi.fn(async () => {
+        throw new Error('native failed');
+      }),
+      execSubprocessJson: vi.fn(async () => ({ ok: 'fallback' })),
+      execSubprocessRaw: vi.fn(async () => 'fallback-raw'),
+    };
+
+    const transport = new GSDTransport(registry, adapters);
+
+    await expect(transport.run({
+      legacyCommand: 'state',
+      legacyArgs: ['load'],
+      registryCommand: 'state.load',
+      registryArgs: [],
+      mode: 'json',
+      projectDir: '/tmp',
+    }, {
+      preferNative: true,
+      allowFallbackToSubprocess: false,
+    })).rejects.toThrow('native failed');
+
+    expect(adapters.execSubprocessJson).not.toHaveBeenCalled();
+  });
+
+  it('does not fallback after timeout-like native error', async () => {
+    const registry = new QueryRegistry();
+    registry.register('state.load', async () => ({ data: { ok: true } }));
+
+    const adapters = {
+      dispatchNative: vi.fn(async () => {
+        throw new Error('gsd-tools timed out after 500ms: state load');
+      }),
+      execSubprocessJson: vi.fn(async () => ({ ok: 'fallback' })),
+      execSubprocessRaw: vi.fn(async () => 'fallback-raw'),
+    };
+
+    const transport = new GSDTransport(registry, adapters);
+
+    await expect(transport.run({
+      legacyCommand: 'state',
+      legacyArgs: ['load'],
+      registryCommand: 'state.load',
+      registryArgs: [],
+      mode: 'json',
+      projectDir: '/tmp',
+    }, {
+      preferNative: true,
+      allowFallbackToSubprocess: true,
+    })).rejects.toThrow('timed out after');
+
+    expect(adapters.execSubprocessJson).not.toHaveBeenCalled();
+  });
+
+  it('does not fallback after typed timeout native error', async () => {
+    const registry = new QueryRegistry();
+    registry.register('state.load', async () => ({ data: { ok: true } }));
+
+    const timeoutError = GSDToolsError.timeout('native timed out', 'state', ['load'], '', 500);
+    const adapters = {
+      dispatchNative: vi.fn(async () => {
+        throw timeoutError;
+      }),
+      execSubprocessJson: vi.fn(async () => ({ ok: 'fallback' })),
+      execSubprocessRaw: vi.fn(async () => 'fallback-raw'),
+    };
+
+    const transport = new GSDTransport(registry, adapters);
+
+    await expect(transport.run({
+      legacyCommand: 'state',
+      legacyArgs: ['load'],
+      registryCommand: 'state.load',
+      registryArgs: [],
+      mode: 'json',
+      projectDir: '/tmp',
+    }, {
+      preferNative: true,
+      allowFallbackToSubprocess: true,
+    })).rejects.toBe(timeoutError);
+
+    expect(adapters.execSubprocessJson).not.toHaveBeenCalled();
+  });
+
+  it('formats native raw output via formatNativeRaw when provided', async () => {
+    const registry = new QueryRegistry();
+    registry.register('commit', async () => ({ data: { hash: 'abc123' } }));
+
+    const adapters = {
+      dispatchNative: vi.fn(async () => ({ data: { hash: 'abc123' } })),
+      execSubprocessJson: vi.fn(async () => ({ ok: false })),
+      execSubprocessRaw: vi.fn(async () => 'subprocess-raw'),
+      formatNativeRaw: vi.fn(() => 'raw-native-output'),
+    };
+
+    const transport = new GSDTransport(registry, adapters);
+    const result = await transport.run({
+      legacyCommand: 'commit',
+      legacyArgs: ['msg'],
+      registryCommand: 'commit',
+      registryArgs: ['msg'],
+      mode: 'raw',
+      projectDir: '/tmp',
+    }, {
+      preferNative: true,
+      allowFallbackToSubprocess: true,
+    });
+
+    expect(result).toBe('raw-native-output');
+    expect(adapters.formatNativeRaw).toHaveBeenCalledOnce();
+    expect(adapters.execSubprocessRaw).not.toHaveBeenCalled();
+  });
+
+  it('falls back to internal raw formatter when formatNativeRaw missing', async () => {
+    const registry = new QueryRegistry();
+    registry.register('commit', async () => ({ data: undefined }));
+
+    const adapters = {
+      dispatchNative: vi.fn(async () => ({ data: undefined })),
+      execSubprocessJson: vi.fn(async () => ({ ok: false })),
+      execSubprocessRaw: vi.fn(async () => 'subprocess-raw'),
+    };
+
+    const transport = new GSDTransport(registry, adapters);
+    const result = await transport.run({
+      legacyCommand: 'commit',
+      legacyArgs: ['msg'],
+      registryCommand: 'commit',
+      registryArgs: ['msg'],
+      mode: 'raw',
+      projectDir: '/tmp',
+    }, {
+      preferNative: true,
+      allowFallbackToSubprocess: true,
+    });
+
+    expect(result).toBe('');
+    expect(adapters.execSubprocessRaw).not.toHaveBeenCalled();
+  });
+  it('routes natively when workstream present (Phase 6 fix)', async () => {
+    // Phase 6 fix: GSDTransport no longer forces subprocess for workstream-scoped
+    // requests. The per-request dispatchNative closure (Phase 5.1) correctly
+    // threads workstream to registry.dispatch(), so native dispatch is used.
+    const registry = new QueryRegistry();
+    registry.register('state.load', async () => ({ data: { ok: true } }));
+
+    const adapters = {
+      dispatchNative: vi.fn(async () => ({ data: { ok: true } })),
+      execSubprocessJson: vi.fn(async () => ({ ok: 'ws-subprocess' })),
+      execSubprocessRaw: vi.fn(async () => 'ws-subprocess-raw'),
+    };
+
+    const transport = new GSDTransport(registry, adapters);
+    const result = await transport.run({
+      legacyCommand: 'state',
+      legacyArgs: ['load'],
+      registryCommand: 'state.load',
+      registryArgs: [],
+      mode: 'json',
+      projectDir: '/tmp',
+      workstream: 'ws-1',
+    }, {
+      preferNative: true,
+      allowFallbackToSubprocess: true,
+    });
+
+    // Native dispatch is used — subprocess is NOT called.
+    expect(result).toEqual({ ok: true });
+    expect(adapters.dispatchNative).toHaveBeenCalledOnce();
+    expect(adapters.execSubprocessJson).not.toHaveBeenCalled();
+  });
+
+  it('fails when command is unregistered and subprocess fallback is disabled', async () => {
+    const registry = new QueryRegistry();
+
+    const adapters = {
+      dispatchNative: vi.fn(async () => ({ data: { ok: true } })),
+      execSubprocessJson: vi.fn(async () => ({ ok: 'fallback' })),
+      execSubprocessRaw: vi.fn(async () => 'fallback-raw'),
+    };
+
+    const transport = new GSDTransport(registry, adapters);
+
+    await expect(transport.run({
+      legacyCommand: 'unknown',
+      legacyArgs: [],
+      registryCommand: 'unknown',
+      registryArgs: [],
+      mode: 'json',
+      projectDir: '/tmp',
+    }, {
+      preferNative: true,
+      allowFallbackToSubprocess: false,
+    })).rejects.toThrow("Subprocess fallback disabled");
+
+    expect(adapters.execSubprocessJson).not.toHaveBeenCalled();
+  });
+
+  it('routes natively when workstream present and mode is raw (Phase 6 fix)', async () => {
+    // Phase 6 fix: workstream no longer forces subprocess. Native dispatch is used
+    // even in raw mode — formatNativeRaw (if set) handles the output projection.
+    const registry = new QueryRegistry();
+    registry.register('commit', async () => ({ data: { hash: 'abc' } }));
+
+    const adapters = {
+      dispatchNative: vi.fn(async () => ({ data: { hash: 'abc' } })),
+      execSubprocessJson: vi.fn(async () => ({ ok: 'json-subprocess' })),
+      execSubprocessRaw: vi.fn(async () => 'raw-subprocess'),
+    };
+
+    const transport = new GSDTransport(registry, adapters);
+    const result = await transport.run({
+      legacyCommand: 'commit',
+      legacyArgs: ['msg'],
+      registryCommand: 'commit',
+      registryArgs: ['msg'],
+      mode: 'raw',
+      projectDir: '/tmp',
+      workstream: 'ws-1',
+    }, {
+      preferNative: true,
+      allowFallbackToSubprocess: true,
+    });
+
+    // Native dispatch is used — toRaw serializes data to JSON.
+    expect(typeof result).toBe('string');
+    expect(adapters.dispatchNative).toHaveBeenCalledOnce();
+    expect(adapters.execSubprocessRaw).not.toHaveBeenCalled();
+    expect(adapters.execSubprocessJson).not.toHaveBeenCalled();
+  });
+});