@orchestrator-claude/cli 3.25.1 → 3.26.0

package/templates/base/scripts/sprint-launch.ts

@@ -0,0 +1,285 @@
+#!/usr/bin/env npx tsx
+/**
+ * sprint-launch.ts — TypeScript CLI entry point for RFC-025 Sprint Launcher
+ *
+ * Usage:
+ *   npx tsx scripts/sprint-launch.ts <preset> [workflowId]
+ *
+ * Presets:
+ *   duo          — 1 implementer pane
+ *   duo-doc      — 1 implementer + 1 doc-sidecar pane
+ *   squad        — 2 implementers + 1 debug-sidecar pane
+ *   squad-review — 1 implementer + 1 debug-sidecar + 1 doc-sidecar pane
+ *   platoon      — 3 implementers + 1 reviewer + 1 debug-sidecar pane
+ *   platoon-full — 2 implementers + 2 doc-sidecars + 1 debug-sidecar + 1 test-sidecar + 1 reviewer pane
+ */
+
+import * as childProcess from 'child_process';
+import * as crypto from 'crypto';
+import { createWorktreeManager } from './lib/WorktreeManager.js';
+import { createWorktreeIsolator } from './lib/WorktreeIsolator.js';
+import { createTmuxManager } from './lib/TmuxManager.js';
+import { createSprintLauncher } from './lib/SprintLauncher.js';
+import type { SprintTask } from './lib/SprintLauncher.js';
+import { createMailboxManager } from './lib/mailbox/MailboxManager.js';
+import { generateLayout } from '../src/domain/value-objects/generateLayout.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const VERSION = '1.0.0';
+const VALID_PRESETS = [
+  'duo',
+  'duo-doc',
+  'squad',
+  'squad-review',
+  'platoon',
+  'platoon-full',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * parseTaskFlags — Extract SprintTask objects from CLI args.
+ *
+ * Supports:
+ *   --task "TASK-001: Title text"  (separate value)
+ *   --task=TASK-001: Title text    (equals-sign form)
+ *
+ * When the value has a colon, everything before the first colon is the taskId
+ * (trimmed) and everything after is the title (trimmed).
+ * When there is no colon, a generated taskId is used and the full string is the title.
+ */
+export function parseTaskFlags(args: string[]): SprintTask[] {
+  const tasks: SprintTask[] = [];
+  let taskCounter = 0;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    let value: string | undefined;
+
+    if (arg === '--task' && i + 1 < args.length) {
+      value = args[i + 1];
+      i++; // consume next arg
+    } else if (arg.startsWith('--task=')) {
+      value = arg.slice('--task='.length);
+    }
+
+    if (value !== undefined) {
+      const colonIdx = value.indexOf(':');
+      let taskId: string;
+      let title: string;
+      if (colonIdx !== -1) {
+        taskId = value.slice(0, colonIdx).trim();
+        title = value.slice(colonIdx + 1).trim();
+      } else {
+        taskCounter++;
+        taskId = `task-${taskCounter}`;
+        title = value.trim();
+      }
+      tasks.push({ taskId, title, description: '', acceptanceCriteria: [] });
+    }
+  }
+
+  return tasks;
+}
+
+function printUsage(): void {
+  console.log(`sprint-launch.ts v${VERSION} — RFC-025 Sprint Launcher
+
+Usage:
+  npx tsx scripts/sprint-launch.ts <preset> [workflowId] [--mailbox] [--task "..."]
+
+Presets:
+  duo          1 implementer pane (orchestrator = calling session)
+  duo-doc      1 implementer + 1 doc-sidecar pane (orchestrator = calling session)
+  squad        2 implementers + 1 debug-sidecar pane
+  squad-review 1 implementer + 1 debug-sidecar + 1 doc-sidecar pane
+  platoon      3 implementers + 1 reviewer + 1 debug-sidecar pane
+  platoon-full 2 implementers + 2 doc-sidecars + 1 debug-sidecar + 1 test-sidecar + 1 reviewer pane
+
+Arguments:
+  preset      Required. One of: ${VALID_PRESETS.join(', ')}
+  workflowId  Optional. UUID of the active workflow (default: generated random UUID)
+
+Flags:
+  --mailbox              Enable mailbox protocol: creates /tmp/<session>/mailbox/<role>/inbox/ for each pane.
+  --task "ID: Title"     Assign a task to the next implementer pane (repeatable, round-robin).
+                         Example: --task "TASK-001: Implement auth" --task "TASK-002: Write tests"
+  --fetch-tasks          Fetch tasks from the REST API (graceful fallback if unavailable).
+
+Task Distribution:
+  Tasks are distributed round-robin to implementer panes only.
+  Sidecar agents (doc-sidecar, debug-sidecar, test-sidecar) receive tasks via mailbox reactions,
+  not via direct assignment. Each implementer pane gets one task per round.
+  Reference: sprint-teammate skill for agent-side protocol.
+
+Examples:
+  npx tsx scripts/sprint-launch.ts duo
+  npx tsx scripts/sprint-launch.ts duo-doc adaaa9a4-ef49-4e26-af14-2b239f62b40c
+  npx tsx scripts/sprint-launch.ts squad --mailbox
+  npx tsx scripts/sprint-launch.ts squad --mailbox --task "TASK-001: Implement feature X" --task "TASK-002: Write docs"
+
+Notes:
+  - Agent panes use 'claude --agent <role>' — compatible with Claude Max (OAuth) and API key.
+  - The calling session (orchestrator) is NOT included in tmux — you continue orchestrating here.
+  - Worktrees are created at ../wt-{session}-{index} (0-indexed).
+  - The tmux session is named sprint-{workflowId_prefix}.
+  - Bash MVP removed (v2) — TypeScript is the only launcher
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  // Help flag
+  if (args.includes('--help') || args.includes('-h')) {
+    printUsage();
+    process.exit(0);
+  }
+
+  const mailboxFlag = args.includes('--mailbox');
+  const fetchTasksFlag = args.includes('--fetch-tasks');
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const presetArg = positional[0];
+  const workflowIdArg = positional[1];
+
+  // Require preset
+  if (!presetArg) {
+    console.error('Error: preset argument is required.\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  // Validate preset early (before creating deps) to give a clean error
+  if (!VALID_PRESETS.includes(presetArg as (typeof VALID_PRESETS)[number])) {
+    console.error(
+      `Error: invalid preset '${presetArg}'. Valid presets: ${VALID_PRESETS.join(', ')}`,
+    );
+    process.exit(1);
+  }
+
+  // SEC-002: Validate workflowId format if provided by the caller
+  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (workflowIdArg && !UUID_RE.test(workflowIdArg)) {
+    console.error('Error: workflowId must be a valid UUID');
+    process.exit(1);
+  }
+
+  // Default workflowId to a fresh UUID
+  const workflowId = workflowIdArg ?? crypto.randomUUID();
+  if (!workflowIdArg) {
+    console.warn(`[sprint-launch] No workflowId provided — using generated: ${workflowId}`);
+  }
+
+  // Resolve project root (one level up from scripts/)
+  const projectRoot = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
+
+  // Build real dependencies
+  const worktreeManager = createWorktreeManager(projectRoot, {
+    execSync: childProcess.execSync,
+  });
+  const worktreeIsolator = createWorktreeIsolator(projectRoot);
+  const tmuxManager = createTmuxManager({ execSync: childProcess.execSync });
+
+  const sessionName = `sprint-${workflowId.slice(0, 8)}`;
+  const mailboxBaseDir = `/tmp/${sessionName}/mailbox`;
+  const mailboxManager = mailboxFlag ? createMailboxManager(mailboxBaseDir) : undefined;
+  if (mailboxFlag) {
+    console.log(`[sprint-launch] Mailbox enabled — inbox directories at ${mailboxBaseDir}/`);
+  }
+
+  // Collect tasks from --task flags
+  let tasks = parseTaskFlags(args);
+
+  // Fetch tasks from REST API if --fetch-tasks flag provided
+  if (fetchTasksFlag) {
+    try {
+      const apiUrl = process.env['ORCHESTRATOR_API_URL'] ?? 'http://localhost:3000';
+      const response = await fetch(`${apiUrl}/api/workflows/${workflowId}/tasks`);
+      if (!response.ok) {
+        console.warn(`[sprint-launch] --fetch-tasks: API returned ${response.status} — continuing with ${tasks.length} CLI tasks`);
+      } else {
+        const data = await response.json() as { tasks?: SprintTask[] };
+        const fetchedTasks = data.tasks ?? [];
+        tasks = [...tasks, ...fetchedTasks];
+        console.log(`[sprint-launch] --fetch-tasks: loaded ${fetchedTasks.length} tasks from API`);
+      }
+    } catch (err) {
+      console.warn(`[sprint-launch] --fetch-tasks: failed to reach API (${err instanceof Error ? err.message : String(err)}) — continuing with ${tasks.length} CLI tasks`);
+    }
+  }
+
+  if (tasks.length > 0) {
+    console.log(`[sprint-launch] Task distribution: ${tasks.length} task(s) → round-robin to implementer panes`);
+  }
+
+  const launcher = createSprintLauncher({
+    worktreeManager,
+    worktreeIsolator,
+    tmuxManager,
+    generateLayout,
+    execSync: childProcess.execSync,
+    projectRoot,
+    mailboxManager,
+  });
+
+  // Register cleanup handlers for SIGINT / SIGTERM
+  let launched = false;
+
+  function onSignal(): void {
+    if (launched) {
+      console.warn('\n[sprint-launch] Interrupted — cleaning up...');
+      launcher.cleanup(sessionName);
+    }
+    process.exit(1);
+  }
+
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+
+  // Launch
+  let result: Awaited<ReturnType<typeof launcher.launch>>;
+  try {
+    result = await launcher.launch(presetArg, workflowId, tasks.length > 0 ? tasks : undefined);
+    launched = true;
+  } catch (err) {
+    launcher.cleanup(sessionName);
+    throw err;
+  }
+
+  // Print summary
+  console.log('');
+  console.log(`[sprint-launch] Sprint session launched: ${result.sessionName}`);
+  console.log('');
+  console.log(`  Preset:     ${result.preset}`);
+  console.log(`  WorkflowId: ${result.workflowId}`);
+  console.log(`  Session:    ${result.sessionName}`);
+  console.log(`  Worktrees:`);
+  for (const wt of result.worktreePaths) {
+    console.log(`    ${wt}`);
+  }
+  console.log('');
+  console.log('Attach to agent panes with:');
+  console.log(`  tmux attach -t ${result.sessionName}`);
+  console.log('');
+  console.log('You (orchestrator) continue in this session.');
+
+}
+
+// Guard: only run main() when this file is the entry point (not when imported for tests)
+const isMain = process.argv[1]?.endsWith('sprint-launch.ts') ||
+  process.argv[1]?.endsWith('sprint-launch.js');
+if (isMain) {
+  main().catch((err: unknown) => {
+    console.error('[sprint-launch] Error:', err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });
+}