@opengsd/get-shit-done-redux 1.0.0

package/sdk/src/gsd-transport.ts

@@ -0,0 +1,118 @@
+import type { QueryResult } from './query/utils.js';
+import type { QueryRegistry } from './query/registry.js';
+import type { TransportMode } from './gsd-transport-policy.js';
+import { toFailureSignal } from './query-failure-classification.js';
+import { GSDToolsError } from './gsd-tools-error.js';
+
+export interface TransportRequest {
+  legacyCommand: string;
+  legacyArgs: string[];
+  registryCommand: string;
+  registryArgs: string[];
+  mode: TransportMode;
+  projectDir: string;
+  workstream?: string;
+}
+
+export interface TransportAdapters {
+  dispatchNative: (request: TransportRequest) => Promise<QueryResult>;
+  execSubprocessJson: (legacyCommand: string, legacyArgs: string[]) => Promise<unknown>;
+  execSubprocessRaw: (legacyCommand: string, legacyArgs: string[]) => Promise<string>;
+  formatNativeRaw?: (registryCommand: string, data: unknown) => string;
+}
+
+export interface TransportPolicyLike {
+  preferNative: boolean;
+  allowFallbackToSubprocess: boolean;
+}
+
+export interface TransportDecision {
+  dispatchMode: 'native' | 'subprocess';
+  reason?: 'native_not_preferred' | 'native_unregistered' | 'native_failure_fallback';
+}
+
+export class GSDTransport {
+  constructor(
+    private readonly registry: QueryRegistry,
+    private readonly adapters: TransportAdapters,
+  ) {}
+
+  async run(
+    request: TransportRequest,
+    policy: TransportPolicyLike,
+    onDecision?: (decision: TransportDecision) => void,
+  ): Promise<unknown> {
+    const useNative = this.shouldUseNative(request, policy);
+    if (useNative) {
+      try {
+        const native = await this.adapters.dispatchNative(request);
+        onDecision?.({ dispatchMode: 'native' });
+        return this.projectNativeOutput(request, native.data);
+      } catch (error) {
+        if (this.shouldRethrowNativeError(error, policy)) throw error;
+        onDecision?.({ dispatchMode: 'subprocess', reason: 'native_failure_fallback' });
+      }
+    } else {
+      const reason = this.subprocessReason(request, policy);
+      if (!policy.allowFallbackToSubprocess && reason === 'native_unregistered') {
+        throw GSDToolsError.failure(
+          `Subprocess fallback disabled: command '${request.registryCommand}' cannot run without native dispatch`,
+          request.legacyCommand,
+          request.legacyArgs,
+          null,
+        );
+      }
+      onDecision?.({ dispatchMode: 'subprocess', reason });
+    }
+
+    return this.dispatchSubprocess(request);
+  }
+
+  private shouldUseNative(request: TransportRequest, policy: TransportPolicyLike): boolean {
+    // Phase 5.0 worker fix: dispatchNative now correctly threads projectDir and
+    // workstream per-request (see worker.ts dispatchNative closure). Workstream
+    // commands no longer need to force subprocess — native dispatch handles them.
+    return policy.preferNative && this.registry.has(request.registryCommand);
+  }
+
+  private subprocessReason(request: TransportRequest, policy: TransportPolicyLike): TransportDecision['reason'] {
+    if (!policy.preferNative) return 'native_not_preferred';
+    if (!this.registry.has(request.registryCommand)) return 'native_unregistered';
+
+    throw new Error(
+      `Unexpected subprocess reason state for command '${request.registryCommand}' with preferNative=${String(policy.preferNative)}`,
+    );
+  }
+
+  private shouldRethrowNativeError(error: unknown, policy: TransportPolicyLike): boolean {
+    if (!policy.allowFallbackToSubprocess) return true;
+    // Do not subprocess-fallback after a timed-out native dispatch:
+    // the timeout does not cancel the native handler, so falling through
+    // would run the same command twice (double-execution race).
+    return toFailureSignal(error).kind === 'timeout';
+  }
+
+  private dispatchSubprocess(request: TransportRequest): Promise<unknown> {
+    if (request.mode === 'raw') {
+      return this.adapters.execSubprocessRaw(request.legacyCommand, request.legacyArgs);
+    }
+    return this.adapters.execSubprocessJson(request.legacyCommand, request.legacyArgs);
+  }
+
+  private projectNativeOutput(request: TransportRequest, data: unknown): unknown {
+    if (request.mode === 'raw') {
+      if (this.adapters.formatNativeRaw) {
+        return this.adapters.formatNativeRaw(request.registryCommand, data).trim();
+      }
+      return this.toRaw(data);
+    }
+    return data;
+  }
+
+  private toRaw(data: unknown): string {
+    if (typeof data === 'string') return data.trim();
+    const json = JSON.stringify(data, null, 2);
+    if (json == null) return '';
+    return json.trim();
+  }
+}

package/sdk/src/index.ts

@@ -0,0 +1,366 @@
+/**
+ * GSD SDK — Public API for running GSD plans programmatically.
+ *
+ * The GSD class composes plan parsing, config loading, prompt building,
+ * and session running into a single `executePlan()` call.
+ *
+ * @example
+ * ```typescript
+ * import { GSD } from '@opengsd/gsd-sdk';
+ *
+ * const gsd = new GSD({ projectDir: '/path/to/project' });
+ * const result = await gsd.executePlan('.planning/phases/01-auth/01-auth-01-PLAN.md');
+ *
+ * if (result.success) {
+ *   console.log(`Plan completed in ${result.durationMs}ms, cost: $${result.totalCostUsd}`);
+ * } else {
+ *   console.error(`Plan failed: ${result.error?.messages.join(', ')}`);
+ * }
+ * ```
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+import type { GSDOptions, PlanResult, SessionOptions, GSDEvent, TransportHandler, PhaseRunnerOptions, PhaseRunnerResult, MilestoneRunnerOptions, MilestoneRunnerResult, RoadmapPhaseInfo } from './types.js';
+import { GSDEventType } from './types.js';
+import { parsePlan, parsePlanFile } from './plan-parser.js';
+import { loadConfig } from './config.js';
+import { GSDTools, resolveGsdToolsPath } from './gsd-tools.js';
+import { runPlanSession } from './session-runner.js';
+import { buildExecutorPrompt, parseAgentTools } from './prompt-builder.js';
+import { GSDEventStream } from './event-stream.js';
+import { PhaseRunner } from './phase-runner.js';
+import { ContextEngine } from './context-engine.js';
+import { PromptFactory } from './phase-prompt.js';
+
+export { PlanningJournal } from './planning-journal.js';
+export type { PlanningEvent, PlanningEventActor, PlanningJournalAppendInput } from './planning-journal.js';
+export { PlanningRuntime } from './planning-runtime.js';
+
+// ─── GSD class ───────────────────────────────────────────────────────────────
+
+export class GSD {
+  private readonly projectDir: string;
+  private readonly gsdToolsPath: string;
+  private readonly sessionId?: string;
+  private readonly defaultModel?: string;
+  private readonly defaultMaxBudgetUsd: number;
+  private readonly defaultMaxTurns: number;
+  private readonly autoMode: boolean;
+  private readonly workstream?: string;
+  private readonly strictSdk?: boolean;
+  private readonly allowFallbackToSubprocess?: boolean;
+  readonly eventStream: GSDEventStream;
+
+  constructor(options: GSDOptions) {
+    this.projectDir = resolve(options.projectDir);
+    this.gsdToolsPath =
+      options.gsdToolsPath ?? resolveGsdToolsPath(this.projectDir);
+    this.sessionId = options.sessionId;
+    this.defaultModel = options.model;
+    this.defaultMaxBudgetUsd = options.maxBudgetUsd ?? 5.0;
+    this.defaultMaxTurns = options.maxTurns ?? 50;
+    this.autoMode = options.autoMode ?? false;
+    this.workstream = options.workstream;
+    this.strictSdk = options.strictSdk;
+    this.allowFallbackToSubprocess = options.allowFallbackToSubprocess;
+    this.eventStream = new GSDEventStream();
+  }
+
+  /**
+   * Execute a single GSD plan file.
+   *
+   * Reads the plan from disk, parses it, loads project config,
+   * optionally reads the agent definition, then runs a query() session.
+   *
+   * @param planPath - Path to the PLAN.md file (absolute or relative to projectDir)
+   * @param options - Per-execution overrides
+   * @returns PlanResult with cost, duration, success/error status
+   */
+  async executePlan(planPath: string, options?: SessionOptions): Promise<PlanResult> {
+    // Resolve plan path relative to project dir
+    const absolutePlanPath = resolve(this.projectDir, planPath);
+
+    // Parse the plan
+    const plan = await parsePlanFile(absolutePlanPath);
+
+    // Load project config
+    const config = await loadConfig(this.projectDir, this.workstream);
+
+    // Try to load agent definition for tool restrictions
+    const agentDef = await this.loadAgentDefinition();
+
+    // Merge defaults with per-call options
+    const sessionOptions: SessionOptions = {
+      maxTurns: options?.maxTurns ?? this.defaultMaxTurns,
+      maxBudgetUsd: options?.maxBudgetUsd ?? this.defaultMaxBudgetUsd,
+      model: options?.model ?? this.defaultModel,
+      cwd: options?.cwd ?? this.projectDir,
+      allowedTools: options?.allowedTools,
+    };
+
+    return runPlanSession(plan, config, sessionOptions, agentDef, this.eventStream, {
+      phase: undefined, // Phase context set by higher-level orchestrators
+      planName: plan.frontmatter.plan,
+    });
+  }
+
+  /**
+   * Subscribe a simple handler to receive all GSD events.
+   */
+  onEvent(handler: (event: GSDEvent) => void): void {
+    this.eventStream.on('event', handler);
+  }
+
+  /**
+   * Subscribe a transport handler to receive all GSD events.
+   * Transports provide structured onEvent/close lifecycle.
+   */
+  addTransport(handler: TransportHandler): void {
+    this.eventStream.addTransport(handler);
+  }
+
+  /**
+   * Create a GSDTools instance for state management operations.
+   */
+  createTools(): GSDTools {
+    return new GSDTools({
+      projectDir: this.projectDir,
+      gsdToolsPath: this.gsdToolsPath,
+      workstream: this.workstream,
+      eventStream: this.eventStream,
+      sessionId: this.sessionId,
+      strictSdk: this.strictSdk,
+      allowFallbackToSubprocess: this.allowFallbackToSubprocess,
+      onDispatchEvent: (event) => {
+        this.eventStream.emitEvent({
+          type: GSDEventType.StreamEvent,
+          timestamp: new Date().toISOString(),
+          sessionId: this.sessionId ?? '',
+          event,
+        });
+      },
+    });
+  }
+
+  /**
+   * Run a full phase lifecycle: discuss → research → plan → execute → verify → advance.
+   *
+   * Creates the necessary collaborators (GSDTools, PromptFactory, ContextEngine),
+   * loads project config, instantiates a PhaseRunner, and delegates to `runner.run()`.
+   *
+   * @param phaseNumber - The phase number to execute (e.g. "01", "02")
+   * @param options - Per-phase overrides for budget, turns, model, and callbacks
+   * @returns PhaseRunnerResult with per-step results, overall success, cost, and timing
+   */
+  async runPhase(phaseNumber: string, options?: PhaseRunnerOptions): Promise<PhaseRunnerResult> {
+    const tools = this.createTools();
+    const promptFactory = new PromptFactory({ projectDir: this.projectDir });
+    const contextEngine = new ContextEngine(this.projectDir, undefined, undefined, this.workstream);
+    const config = await loadConfig(this.projectDir, this.workstream);
+
+    // Auto mode: force auto_advance on and skip_discuss off so self-discuss kicks in
+    if (this.autoMode) {
+      config.workflow.auto_advance = true;
+      config.workflow.skip_discuss = false;
+    }
+
+    const runner = new PhaseRunner({
+      projectDir: this.projectDir,
+      tools,
+      promptFactory,
+      contextEngine,
+      eventStream: this.eventStream,
+      config,
+    });
+
+    return runner.run(phaseNumber, options);
+  }
+
+  /**
+   * Run a full milestone: discover phases, execute each incomplete one in order,
+   * re-discover after each completion to catch dynamically inserted phases.
+   *
+   * @param prompt - The user prompt describing the milestone goal
+   * @param options - Per-milestone overrides for budget, turns, model, and callbacks
+   * @returns MilestoneRunnerResult with per-phase results, overall success, cost, and timing
+   */
+  async run(prompt: string, options?: MilestoneRunnerOptions): Promise<MilestoneRunnerResult> {
+    const tools = this.createTools();
+    const startTime = Date.now();
+    const phaseResults: PhaseRunnerResult[] = [];
+    let success = true;
+
+    // Discover initial phases
+    const initialAnalysis = await tools.roadmapAnalyze();
+    const incompletePhases = this.filterAndSortPhases(initialAnalysis.phases);
+
+    // Emit MilestoneStart
+    this.eventStream.emitEvent({
+      type: GSDEventType.MilestoneStart,
+      timestamp: new Date().toISOString(),
+      sessionId: `milestone-${Date.now()}`,
+      phaseCount: incompletePhases.length,
+      prompt,
+    });
+
+    // Loop through phases, re-discovering after each completion
+    let currentPhases = incompletePhases;
+
+    while (currentPhases.length > 0) {
+      const phase = currentPhases[0];
+
+      try {
+        const result = await this.runPhase(phase.number, options);
+        phaseResults.push(result);
+
+        if (!result.success) {
+          success = false;
+          break;
+        }
+
+        // Notify callback if present; stop if requested
+        if (options?.onPhaseComplete) {
+          const verdict = await options.onPhaseComplete(result, phase);
+          if (verdict === 'stop') {
+            break;
+          }
+        }
+
+        // Re-discover phases to catch dynamically inserted ones
+        const updatedAnalysis = await tools.roadmapAnalyze();
+        currentPhases = this.filterAndSortPhases(updatedAnalysis.phases);
+      } catch (err) {
+        // Phase threw an unexpected error — record as failure and stop
+        phaseResults.push({
+          phaseNumber: phase.number,
+          phaseName: phase.phase_name,
+          steps: [],
+          success: false,
+          totalCostUsd: 0,
+          totalDurationMs: 0,
+        });
+        success = false;
+        break;
+      }
+    }
+
+    const totalCostUsd = phaseResults.reduce((sum, r) => sum + r.totalCostUsd, 0);
+    const totalDurationMs = Date.now() - startTime;
+
+    // Emit MilestoneComplete
+    this.eventStream.emitEvent({
+      type: GSDEventType.MilestoneComplete,
+      timestamp: new Date().toISOString(),
+      sessionId: `milestone-${Date.now()}`,
+      success,
+      totalCostUsd,
+      totalDurationMs,
+      phasesCompleted: phaseResults.filter(r => r.success).length,
+    });
+
+    return {
+      success,
+      phases: phaseResults,
+      totalCostUsd,
+      totalDurationMs,
+    };
+  }
+
+  /**
+   * Filter to incomplete phases and sort numerically.
+   * Uses parseFloat to handle decimal phase numbers (e.g. '5.1').
+   */
+  private filterAndSortPhases(phases: RoadmapPhaseInfo[]): RoadmapPhaseInfo[] {
+    return phases
+      .filter(p => !p.roadmap_complete)
+      .sort((a, b) => parseFloat(a.number) - parseFloat(b.number));
+  }
+
+  /**
+   * Load the gsd-executor agent definition if available.
+   * Falls back gracefully — returns undefined if not found.
+   */
+  private async loadAgentDefinition(): Promise<string | undefined> {
+    const paths = [
+      // Repo-local GSD installation
+      join(this.projectDir, '.claude', 'get-shit-done', 'agents', 'gsd-executor.md'),
+      // Repo-local agents directory
+      join(this.projectDir, '.claude', 'agents', 'gsd-executor.md'),
+      // Global home directory
+      join(homedir(), '.claude', 'agents', 'gsd-executor.md'),
+      join(this.projectDir, 'agents', 'gsd-executor.md'),
+    ];
+
+    for (const p of paths) {
+      try {
+        return await readFile(p, 'utf-8');
+      } catch {
+        // Not found at this path, try next
+      }
+    }
+
+    return undefined;
+  }
+}
+
+// ─── Re-exports for advanced usage ──────────────────────────────────────────
+
+export { parsePlan, parsePlanFile } from './plan-parser.js';
+export { loadConfig } from './config.js';
+export type { GSDConfig } from './config.js';
+export { GSDTools, GSDToolsError, resolveGsdToolsPath } from './gsd-tools.js';
+export { runPlanSession, runPhaseStepSession } from './session-runner.js';
+export { buildExecutorPrompt, parseAgentTools } from './prompt-builder.js';
+export type { ExecutorPromptOptions } from './prompt-builder.js';
+export * from './types.js';
+
+// S02: Event stream, context, prompt, and logging modules
+export { GSDEventStream } from './event-stream.js';
+export type { EventStreamContext } from './event-stream.js';
+export { ContextEngine, PHASE_FILE_MANIFEST } from './context-engine.js';
+export type { FileSpec } from './context-engine.js';
+export { truncateMarkdown, extractCurrentMilestone, DEFAULT_TRUNCATION_OPTIONS } from './context-truncation.js';
+export type { TruncationOptions } from './context-truncation.js';
+export { getToolsForPhase, PHASE_AGENT_MAP, PHASE_DEFAULT_TOOLS } from './tool-scoping.js';
+export { checkResearchGate } from './research-gate.js';
+export type { ResearchGateResult } from './research-gate.js';
+export { PromptFactory, extractBlock, extractSteps, PHASE_WORKFLOW_MAP } from './phase-prompt.js';
+export { GSDLogger } from './logger.js';
+export type { LogLevel, LogEntry, GSDLoggerOptions } from './logger.js';
+
+// S03: Phase lifecycle state machine
+export { PhaseRunner, PhaseRunnerError } from './phase-runner.js';
+export type { PhaseRunnerDeps, VerificationOutcome } from './phase-runner.js';
+
+// S05: Transports
+export { CLITransport } from './cli-transport.js';
+export { WSTransport } from './ws-transport.js';
+export type { WSTransportOptions } from './ws-transport.js';
+
+// Query registry argv normalization (matches `gsd-sdk query` and `GSDTools` hot path)
+export { createRegistry, normalizeQueryCommand } from './query/index.js';
+
+// Phase UAT predicate — programmatic API surface (#3184)
+export {
+  isPhaseUatPassed,
+  phaseUatPassed,
+  REASON_CODE,
+  ERROR_CODE,
+  PhaseUatPassedError,
+} from './query/phase-uat-passed.js';
+export type {
+  UatReason,
+  ReasonCode,
+  ErrorCode,
+} from './query/phase-uat-passed.js';
+
+// Workstream utilities
+export { validateWorkstreamName, relPlanningPath } from './workstream-utils.js';
+
+// Init workflow
+export { InitRunner } from './init-runner.js';
+export type { InitRunnerDeps } from './init-runner.js';
+export type { InitConfig, InitResult, InitStepResult, InitStepName } from './types.js';

package/sdk/src/init-e2e.integration.test.ts

@@ -0,0 +1,138 @@
+/**
+ * E2E integration test — proves InitRunner.run() drives real Agent SDK
+ * sessions for the gsd-sdk init workflow.
+ *
+ * Requires Claude Code CLI (`claude`) installed and authenticated.
+ * Skips gracefully if CLI is unavailable.
+ *
+ * This test proves the headless init pipeline can bootstrap a real project
+ * without human intervention: setup → config → PROJECT.md → research →
+ * synthesis → requirements → roadmap.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execSync } from 'node:child_process';
+import { mkdtemp, rm, readFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import { InitRunner } from './init-runner.js';
+import { GSDTools, resolveGsdToolsPath } from './gsd-tools.js';
+import { GSDEventStream } from './event-stream.js';
+import { GSDEventType } from './types.js';
+import type { GSDEvent } from './types.js';
+
+// ─── CLI availability check ─────────────────────────────────────────────────
+
+let cliAvailable = false;
+try {
+  execSync('which claude', { stdio: 'ignore' });
+  cliAvailable = true;
+} catch {
+  cliAvailable = false;
+}
+
+const e2eEnabled = process.env.GSD_ENABLE_E2E === '1';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const sdkPromptsDir = join(__dirname, '..', 'prompts');
+const GSD_TOOLS_PATH = resolveGsdToolsPath(process.cwd());
+const gsdToolsAvailable = existsSync(GSD_TOOLS_PATH);
+
+// ─── Test suite ──────────────────────────────────────────────────────────────
+
+describe.skipIf(!cliAvailable || !gsdToolsAvailable || !e2eEnabled)('E2E: InitRunner.run() full workflow', () => {
+  let tmpDir: string;
+  let events: GSDEvent[];
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-sdk-init-e2e-'));
+
+    // Initialize git in the temp dir (required by InitRunner)
+    execSync('git init', { cwd: tmpDir, stdio: 'ignore' });
+    execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'ignore' });
+    execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'ignore' });
+  }, 30_000);
+
+  afterAll(async () => {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it('InitRunner.run() bootstraps a project without human intervention', async () => {
+    events = [];
+    const eventStream = new GSDEventStream();
+    eventStream.on('event', (e: GSDEvent) => events.push(e));
+
+    const tools = new GSDTools({
+      projectDir: tmpDir,
+      gsdToolsPath: GSD_TOOLS_PATH,
+      timeoutMs: 30_000,
+    });
+
+    const runner = new InitRunner({
+      projectDir: tmpDir,
+      tools,
+      eventStream,
+      config: {
+        maxBudgetPerSession: 1.0,
+        maxTurnsPerSession: 15,
+      },
+      sdkPromptsDir,
+    });
+
+    const result = await runner.run('Build a CLI tool that prints hello world');
+
+    // ── Assert: pipeline executed (success OR at least 3+ steps completed) ──
+    const completedSteps = result.steps.filter(s => s.success);
+    const pipelineProgressed = result.success || completedSteps.length >= 3;
+    expect(pipelineProgressed).toBe(true);
+
+    // ── Assert: config.json artifact created ──
+    // config.json is written directly by InitRunner (not by Claude session)
+    // so it should always exist if the config step succeeded
+    const configStep = result.steps.find(s => s.step === 'config');
+    if (configStep?.success) {
+      const configPath = join(tmpDir, '.planning', 'config.json');
+      const configStat = await stat(configPath).catch(() => null);
+      expect(configStat).not.toBeNull();
+
+      if (configStat) {
+        const configContent = JSON.parse(await readFile(configPath, 'utf-8'));
+        expect(configContent.workflow.auto_advance).toBe(true);
+      }
+    }
+
+    // ── Assert: PROJECT.md created if project step succeeded ──
+    const projectStep = result.steps.find(s => s.step === 'project');
+    if (projectStep?.success) {
+      const projectPath = join(tmpDir, '.planning', 'PROJECT.md');
+      const projectStat = await stat(projectPath).catch(() => null);
+      expect(projectStat).not.toBeNull();
+    }
+
+    // ── Assert: events captured include InitStart and at least one InitStepComplete ──
+    const initStartEvents = events.filter(e => e.type === GSDEventType.InitStart);
+    expect(initStartEvents.length).toBe(1);
+
+    const stepCompleteEvents = events.filter(e => e.type === GSDEventType.InitStepComplete);
+    expect(stepCompleteEvents.length).toBeGreaterThanOrEqual(1);
+
+    // ── Assert: InitComplete event emitted ──
+    const initCompleteEvents = events.filter(e => e.type === GSDEventType.InitComplete);
+    expect(initCompleteEvents.length).toBe(1);
+
+    // ── Assert: cost and duration are tracked ──
+    expect(result.totalDurationMs).toBeGreaterThan(0);
+    expect(typeof result.totalCostUsd).toBe('number');
+
+    // ── Assert: artifacts list is populated ──
+    if (result.success) {
+      expect(result.artifacts.length).toBeGreaterThan(0);
+      expect(result.artifacts).toContain('.planning/config.json');
+    }
+  }, 600_000); // 10 minute timeout for the full 7-session init workflow
+});