@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdk/src/cli.ts

@@ -0,0 +1,589 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for sdd-sdk.
+ *
+ * Usage: sdd-sdk run "<prompt>" [--project-dir <dir>] [--ws-port <port>]
+ *                                [--model <model>] [--max-budget <n>]
+ */
+
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { resolve, join, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { SDD } from './index.js';
+import { CLITransport } from './cli-transport.js';
+import { WSTransport } from './ws-transport.js';
+import { InitRunner } from './init-runner.js';
+import { validateWorkstreamName } from './workstream-utils.js';
+import { loadConfig } from './config.js';
+import { assertRuntimeSupportsAutoMode } from './runtime-gate.js';
+import { runQueryCliCommand } from './query/query-cli-adapter.js';
+
+// ─── Parsed CLI args ─────────────────────────────────────────────────────────
+
+export interface ParsedCliArgs {
+  command: string | undefined;
+  prompt: string | undefined;
+  /** For 'init' command: the raw input source (@file, text, or undefined for stdin). */
+  initInput: string | undefined;
+  /** For 'auto --init': bootstrap from a PRD before running the autonomous loop. */
+  init: string | undefined;
+  projectDir: string;
+  wsPort: number | undefined;
+  model: string | undefined;
+  maxBudget: number | undefined;
+  /** Workstream name for multi-workstream projects. Routes .planning/ to .planning/workstreams/<name>/. */
+  ws: string | undefined;
+  help: boolean;
+  version: boolean;
+  /**
+   * When `command === 'query'`, tokens after `query` with only known SDK flags removed.
+   * Extra flags are kept so handlers that share sdd-tools-style argv (e.g. `--pick`) still receive them.
+   */
+  queryArgv?: string[];
+}
+
+/**
+ * Parse `sdd-sdk query …` without rejecting unknown flags (query argv is forwarded to the registry).
+ */
+function parseCliArgsQueryPermissive(argv: string[]): ParsedCliArgs {
+  let projectDir = process.cwd();
+  let ws: string | undefined;
+  let wsPort: number | undefined;
+  let model: string | undefined;
+  let maxBudget: number | undefined;
+  let help = false;
+  let version = false;
+  const queryArgv: string[] = [];
+
+  let i = 1;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === '--project-dir' && argv[i + 1]) {
+      projectDir = argv[i + 1];
+      i += 2;
+      continue;
+    }
+    if (a === '--ws' && argv[i + 1]) {
+      ws = argv[i + 1];
+      i += 2;
+      continue;
+    }
+    if (a === '--ws-port' && argv[i + 1]) {
+      wsPort = Number(argv[i + 1]);
+      i += 2;
+      continue;
+    }
+    if (a === '--model' && argv[i + 1]) {
+      model = argv[i + 1];
+      i += 2;
+      continue;
+    }
+    if (a === '--max-budget' && argv[i + 1]) {
+      maxBudget = Number(argv[i + 1]);
+      i += 2;
+      continue;
+    }
+    // #3019: do NOT consume -h / --help here unconditionally. Pushing the
+    // flag onto queryArgv lets the registered handler (or the sdd-tools.cjs
+    // fallback) render contextual subcommand help. We still set the global
+    // `help` flag when the flag appears, but only short-circuit dispatch in
+    // main() when there is no real subcommand to dispatch to (i.e. the only
+    // tokens in queryArgv are the help flags themselves). That preserves
+    // `sdd-sdk query --help` → top-level USAGE while letting
+    // `sdd-sdk query phase add --help` reach the handler.
+    if (a === '-h' || a === '--help') {
+      help = true;
+      queryArgv.push(a);
+      i += 1;
+      continue;
+    }
+    if (a === '-v' || a === '--version') {
+      version = true;
+      i += 1;
+      continue;
+    }
+    queryArgv.push(a);
+    i += 1;
+  }
+
+  // If the user typed a real subcommand (anything other than help flags
+  // alone in queryArgv), do NOT short-circuit to top-level USAGE on help.
+  // The handler/fallback will render contextual help.
+  const nonHelpTokens = queryArgv.filter((t) => t !== '-h' && t !== '--help');
+  if (help && nonHelpTokens.length > 0) {
+    help = false;
+  }
+
+  return {
+    command: 'query',
+    prompt: undefined,
+    initInput: undefined,
+    init: undefined,
+    projectDir,
+    wsPort,
+    model,
+    maxBudget,
+    ws,
+    help,
+    version,
+    queryArgv,
+  };
+}
+
+/**
+ * Parse CLI arguments into a structured object.
+ * Exported for testing — the main() function uses this internally.
+ */
+export function parseCliArgs(argv: string[]): ParsedCliArgs {
+  if (argv[0] === 'query') {
+    return parseCliArgsQueryPermissive(argv);
+  }
+
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: {
+      'project-dir': { type: 'string', default: process.cwd() },
+      'ws-port': { type: 'string' },
+      ws: { type: 'string' },
+      model: { type: 'string' },
+      'max-budget': { type: 'string' },
+      init: { type: 'string' },
+      help: { type: 'boolean', short: 'h', default: false },
+      version: { type: 'boolean', short: 'v', default: false },
+    },
+    allowPositionals: true,
+    strict: true,
+  });
+
+  const command = positionals[0] as string | undefined;
+  const prompt = positionals.slice(1).join(' ') || undefined;
+
+  // For 'init' command, the positional after 'init' is the input source.
+  // For 'run' command, it's the prompt. Both use positionals[1+].
+  const initInput = command === 'init' ? prompt : undefined;
+
+  return {
+    command,
+    prompt,
+    initInput,
+    init: values.init as string | undefined,
+    projectDir: values['project-dir'] as string,
+    wsPort: values['ws-port'] ? Number(values['ws-port']) : undefined,
+    model: values.model as string | undefined,
+    maxBudget: values['max-budget'] ? Number(values['max-budget']) : undefined,
+    ws: values.ws as string | undefined,
+    help: values.help as boolean,
+    version: values.version as boolean,
+  };
+}
+
+// ─── Usage ───────────────────────────────────────────────────────────────────
+
+export const USAGE = `
+Usage: sdd-sdk <command> [args] [options]
+
+Commands:
+  run <prompt>          Run a full milestone from a text prompt
+  auto                  Run the full autonomous lifecycle (discover -> execute -> advance)
+  init [input]          Bootstrap a new project from a PRD or description
+                        input can be:
+                          @path/to/prd.md   Read input from a file
+                          "description"     Use text directly
+                          (empty)           Read from stdin
+  query <argv...>       Registered query handlers only (longest-prefix argv match; see QUERY-HANDLERS.md)
+                        Use --pick <field> to extract a specific field from JSON output
+
+Options:
+  --init <input>        Bootstrap from a PRD before running (auto only)
+                        Accepts @path/to/prd.md or "description text"
+  --project-dir <dir>   Project directory (default: cwd)
+  --ws <name>           Route .planning/ to .planning/workstreams/<name>/
+  --ws-port <port>      Enable WebSocket transport on <port>
+  --model <model>       Override LLM model
+  --max-budget <n>      Max budget per step in USD
+  -h, --help            Show this help
+  -v, --version         Show version
+`.trim();
+
+/**
+ * Read the package version from package.json.
+ */
+async function getVersion(): Promise<string> {
+  try {
+    const pkgPath = resolve(fileURLToPath(import.meta.url), '..', '..', 'package.json');
+    const raw = await readFile(pkgPath, 'utf-8');
+    const pkg = JSON.parse(raw) as { version?: string };
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+// ─── Init input resolution ───────────────────────────────────────────────────
+
+/**
+ * Resolve the init command input to a string.
+ *
+ * - `@path/to/file.md` → reads the file contents
+ * - Raw text → returns as-is
+ * - No input → reads from stdin (with TTY detection)
+ *
+ * Exported for testing.
+ */
+export async function resolveInitInput(args: ParsedCliArgs): Promise<string> {
+  const input = args.initInput;
+
+  if (input && input.startsWith('@')) {
+    // File path: strip @ prefix, resolve relative to projectDir
+    const filePath = resolve(args.projectDir, input.slice(1));
+    try {
+      return await readFile(filePath, 'utf-8');
+    } catch (err) {
+      throw new Error(`Cannot read input file "${filePath}": ${(err as NodeJS.ErrnoException).code === 'ENOENT' ? 'file not found' : (err as Error).message}`);
+    }
+  }
+
+  if (input) {
+    // Raw text
+    return input;
+  }
+
+  // No input — read from stdin
+  return readStdin();
+}
+
+/**
+ * Read all data from stdin. Rejects if stdin is a TTY with no piped data.
+ */
+async function readStdin(): Promise<string> {
+  const { stdin } = process;
+
+  if (stdin.isTTY) {
+    throw new Error(
+      'No input provided. Usage:\n' +
+      '  sdd-sdk init @path/to/prd.md\n' +
+      '  sdd-sdk init "build a todo app"\n' +
+      '  cat prd.md | sdd-sdk init'
+    );
+  }
+
+  return new Promise<string>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    stdin.on('data', (chunk: Buffer) => chunks.push(chunk));
+    stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+    stdin.on('error', reject);
+  });
+}
+
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
+  let args: ParsedCliArgs;
+
+  try {
+    args = parseCliArgs(argv);
+  } catch (err) {
+    console.error(`Error: ${(err as Error).message}`);
+    console.error(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (args.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  if (args.version) {
+    const ver = await getVersion();
+    console.log(`sdd-sdk v${ver}`);
+    return;
+  }
+
+  // Validate --ws flag if provided
+  if (args.ws !== undefined && !validateWorkstreamName(args.ws)) {
+    console.error(`Error: Invalid workstream name "${args.ws}". Use alphanumeric, hyphens, underscores, or dots only.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // ─── Query command ──────────────────────────────────────────────────────
+  if (args.command === 'query') {
+    const result = await runQueryCliCommand({
+      projectDir: args.projectDir,
+      ws: args.ws,
+      queryArgv: args.queryArgv,
+    });
+    for (const line of result.stderrLines) console.error(line);
+    for (const chunk of result.stdoutChunks) process.stdout.write(chunk);
+    process.exitCode = result.exitCode;
+    return;
+  }
+
+  // Fall back to SDD_WORKSTREAM env var when --ws is not supplied (#2791).
+  // sdd-tools.cjs resolves the active workstream via this env var; parity
+  // means sdd-sdk command paths see the same .planning/ path as sdd-tools.
+  if (args.ws === undefined && process.env.SDD_WORKSTREAM) {
+    const envWs = process.env.SDD_WORKSTREAM;
+    if (validateWorkstreamName(envWs)) {
+      args = { ...args, ws: envWs };
+    }
+  }
+
+  // Multi-repo project-root resolution (issue #2623).
+  {
+    const { findProjectRoot } = await import('./query/helpers.js');
+    args = { ...args, projectDir: findProjectRoot(args.projectDir) };
+  }
+
+  if (args.command !== 'run' && args.command !== 'init' && args.command !== 'auto') {
+    console.error('Error: Expected "sdd-sdk run <prompt>", "sdd-sdk auto", "sdd-sdk init [input]", or "sdd-sdk query <command>"');
+    console.error(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (args.command === 'run' && !args.prompt) {
+    console.error('Error: "sdd-sdk run" requires a prompt');
+    console.error(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+
+  // ─── Init command ─────────────────────────────────────────────────────────
+  if (args.command === 'init') {
+    let input: string;
+    try {
+      input = await resolveInitInput(args);
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    console.log(`[init] Resolved input: ${input.length} chars`);
+
+    // Build SDD instance for tools and event stream
+    const sdd = new SDD({
+      projectDir: args.projectDir,
+      model: args.model,
+      maxBudgetUsd: args.maxBudget,
+      workstream: args.ws,
+    });
+
+    // Wire CLI transport
+    const cliTransport = new CLITransport();
+    sdd.addTransport(cliTransport);
+
+    // Optional WebSocket transport
+    let wsTransport: WSTransport | undefined;
+    if (args.wsPort !== undefined) {
+      wsTransport = new WSTransport({ port: args.wsPort });
+      await wsTransport.start();
+      sdd.addTransport(wsTransport);
+      console.log(`WebSocket transport listening on port ${args.wsPort}`);
+    }
+
+    try {
+      const tools = sdd.createTools();
+      const runner = new InitRunner({
+        projectDir: args.projectDir,
+        tools,
+        eventStream: sdd.eventStream,
+        config: {
+          maxBudgetPerSession: args.maxBudget,
+          orchestratorModel: args.model,
+        },
+      });
+
+      const result = await runner.run(input);
+
+      // Print completion summary
+      const status = result.success ? 'SUCCESS' : 'FAILED';
+      const stepCount = result.steps.length;
+      const passedSteps = result.steps.filter(s => s.success).length;
+      const cost = result.totalCostUsd.toFixed(2);
+      const duration = (result.totalDurationMs / 1000).toFixed(1);
+      const artifactList = result.artifacts.join(', ');
+
+      console.log(`\n[${status}] ${passedSteps}/${stepCount} steps, $${cost}, ${duration}s`);
+      if (result.artifacts.length > 0) {
+        console.log(`Artifacts: ${artifactList}`);
+      }
+
+      if (!result.success) {
+        // Log failed steps
+        for (const step of result.steps) {
+          if (!step.success && step.error) {
+            console.error(`  ✗ ${step.step}: ${step.error}`);
+          }
+        }
+        process.exitCode = 1;
+      }
+    } catch (err) {
+      console.error(`Fatal error: ${(err as Error).message}`);
+      process.exitCode = 1;
+    } finally {
+      cliTransport.close();
+      if (wsTransport) {
+        wsTransport.close();
+      }
+    }
+    return;
+  }
+
+  // ─── Auto command ─────────────────────────────────────────────────────────
+  if (args.command === 'auto') {
+    // #2832: refuse to silently route non-Claude runtime projects through the
+    // Claude Agent SDK. Load project config (best effort — falls back to
+    // defaults when missing) and gate before constructing SDD/InitRunner.
+    try {
+      const cfg = await loadConfig(args.projectDir, args.ws);
+      assertRuntimeSupportsAutoMode(cfg);
+    } catch (err) {
+      console.error(`Fatal error: ${(err as Error).message}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const sdd = new SDD({
+      projectDir: args.projectDir,
+      model: args.model,
+      maxBudgetUsd: args.maxBudget,
+      autoMode: true,
+      workstream: args.ws,
+    });
+
+    // Wire CLI transport (always active)
+    const cliTransport = new CLITransport();
+    sdd.addTransport(cliTransport);
+
+    // Optional WebSocket transport
+    let wsTransport: WSTransport | undefined;
+    if (args.wsPort !== undefined) {
+      wsTransport = new WSTransport({ port: args.wsPort });
+      await wsTransport.start();
+      sdd.addTransport(wsTransport);
+      console.log(`WebSocket transport listening on port ${args.wsPort}`);
+    }
+
+    try {
+      // If --init provided, bootstrap project first
+      if (args.init) {
+        const initInput = await resolveInitInput({
+          ...args,
+          command: 'init',
+          initInput: args.init,
+        });
+
+        console.log(`[auto] Bootstrapping project from --init (${initInput.length} chars)`);
+
+        const tools = sdd.createTools();
+        const runner = new InitRunner({
+          projectDir: args.projectDir,
+          tools,
+          eventStream: sdd.eventStream,
+          config: {
+            maxBudgetPerSession: args.maxBudget,
+            orchestratorModel: args.model,
+          },
+        });
+
+        const initResult = await runner.run(initInput);
+
+        const initStatus = initResult.success ? 'SUCCESS' : 'FAILED';
+        const stepCount = initResult.steps.length;
+        const passedSteps = initResult.steps.filter(s => s.success).length;
+        const initCost = initResult.totalCostUsd.toFixed(2);
+        const initDuration = (initResult.totalDurationMs / 1000).toFixed(1);
+        console.log(`[init ${initStatus}] ${passedSteps}/${stepCount} steps, $${initCost}, ${initDuration}s`);
+
+        if (!initResult.success) {
+          for (const step of initResult.steps) {
+            if (!step.success && step.error) {
+              console.error(`  ✗ ${step.step}: ${step.error}`);
+            }
+          }
+          process.exitCode = 1;
+          return;
+        }
+      }
+
+      const result = await sdd.run('');
+
+      // Final summary
+      const status = result.success ? 'SUCCESS' : 'FAILED';
+      const phases = result.phases.length;
+      const cost = result.totalCostUsd.toFixed(2);
+      const duration = (result.totalDurationMs / 1000).toFixed(1);
+      console.log(`\n[${status}] ${phases} phase(s), $${cost}, ${duration}s`);
+
+      if (!result.success) {
+        process.exitCode = 1;
+      }
+    } catch (err) {
+      console.error(`Fatal error: ${(err as Error).message}`);
+      process.exitCode = 1;
+    } finally {
+      cliTransport.close();
+      if (wsTransport) {
+        wsTransport.close();
+      }
+    }
+    return;
+  }
+
+  // ─── Run command ─────────────────────────────────────────────────────────
+
+  // Build SDD instance
+  const sdd = new SDD({
+    projectDir: args.projectDir,
+    model: args.model,
+    maxBudgetUsd: args.maxBudget,
+    workstream: args.ws,
+  });
+
+  // Wire CLI transport (always active)
+  const cliTransport = new CLITransport();
+  sdd.addTransport(cliTransport);
+
+  // Optional WebSocket transport
+  let wsTransport: WSTransport | undefined;
+  if (args.wsPort !== undefined) {
+    wsTransport = new WSTransport({ port: args.wsPort });
+    await wsTransport.start();
+    sdd.addTransport(wsTransport);
+    console.log(`WebSocket transport listening on port ${args.wsPort}`);
+  }
+
+  try {
+    const result = await sdd.run(args.prompt!);
+
+    // Final summary
+    const status = result.success ? 'SUCCESS' : 'FAILED';
+    const phases = result.phases.length;
+    const cost = result.totalCostUsd.toFixed(2);
+    const duration = (result.totalDurationMs / 1000).toFixed(1);
+    console.log(`\n[${status}] ${phases} phase(s), $${cost}, ${duration}s`);
+
+    if (!result.success) {
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    console.error(`Fatal error: ${(err as Error).message}`);
+    process.exitCode = 1;
+  } finally {
+    // Clean up transports
+    cliTransport.close();
+    if (wsTransport) {
+      wsTransport.close();
+    }
+  }
+}
+
+// ─── Auto-run when invoked directly ──────────────────────────────────────────
+
+main();