gsd-pi 2.23.0 → 2.25.0

package/dist/resources/extensions/gsd/parallel-merge.ts

@@ -0,0 +1,156 @@
+/**
+ * GSD Parallel Merge — Worktree reconciliation for parallel milestones.
+ *
+ * Handles merging completed milestone worktrees back to main branch
+ * with safety checks for parallel execution context.
+ */
+
+import { loadFile } from "./files.js";
+import { resolveMilestoneFile } from "./paths.js";
+import { mergeMilestoneToMain } from "./auto-worktree.js";
+import { MergeConflictError } from "./git-service.js";
+import { removeSessionStatus } from "./session-status-io.js";
+import type { WorkerInfo } from "./parallel-orchestrator.js";
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+export interface MergeResult {
+  milestoneId: string;
+  success: boolean;
+  commitMessage?: string;
+  pushed?: boolean;
+  error?: string;
+  conflictFiles?: string[];
+}
+
+export type MergeOrder = "sequential" | "by-completion";
+
+// ─── Merge Queue ───────────────────────────────────────────────────────────
+
+/**
+ * Determine safe merge order for completed milestones.
+ * Sequential: merge in milestone ID order (M001 before M002).
+ * By-completion: merge in the order milestones finished.
+ */
+export function determineMergeOrder(
+  workers: WorkerInfo[],
+  order: MergeOrder = "sequential",
+): string[] {
+  const completed = workers.filter(w => w.state === "stopped" && w.completedUnits > 0);
+  if (order === "by-completion") {
+    return completed
+      .sort((a, b) => a.startedAt - b.startedAt) // earliest first
+      .map(w => w.milestoneId);
+  }
+  return completed
+    .sort((a, b) => a.milestoneId.localeCompare(b.milestoneId))
+    .map(w => w.milestoneId);
+}
+
+/**
+ * Attempt to merge a single milestone's worktree back to main.
+ * Wraps mergeMilestoneToMain with error handling for parallel context.
+ */
+export async function mergeCompletedMilestone(
+  basePath: string,
+  milestoneId: string,
+): Promise<MergeResult> {
+  try {
+    // Load the roadmap content (needed by mergeMilestoneToMain)
+    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    if (!roadmapPath) {
+      return {
+        milestoneId,
+        success: false,
+        error: `No roadmap found for ${milestoneId}`,
+      };
+    }
+
+    const roadmapContent = await loadFile(roadmapPath);
+    if (!roadmapContent) {
+      return {
+        milestoneId,
+        success: false,
+        error: `Could not read roadmap for ${milestoneId}`,
+      };
+    }
+
+    // Attempt the merge
+    const result = mergeMilestoneToMain(basePath, milestoneId, roadmapContent);
+
+    // Clean up parallel session status
+    removeSessionStatus(basePath, milestoneId);
+
+    return {
+      milestoneId,
+      success: true,
+      commitMessage: result.commitMessage,
+      pushed: result.pushed,
+    };
+  } catch (err) {
+    if (err instanceof MergeConflictError) {
+      return {
+        milestoneId,
+        success: false,
+        error: `Merge conflict: ${err.conflictedFiles.length} conflicting file(s)`,
+        conflictFiles: err.conflictedFiles,
+      };
+    }
+    return {
+      milestoneId,
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Merge all completed milestones in sequence.
+ * Stops on first conflict and returns results so far.
+ */
+export async function mergeAllCompleted(
+  basePath: string,
+  workers: WorkerInfo[],
+  order: MergeOrder = "sequential",
+): Promise<MergeResult[]> {
+  const mergeOrder = determineMergeOrder(workers, order);
+  const results: MergeResult[] = [];
+
+  for (const mid of mergeOrder) {
+    const result = await mergeCompletedMilestone(basePath, mid);
+    results.push(result);
+
+    // Stop on first conflict — later merges may depend on this one
+    if (!result.success && result.conflictFiles) {
+      break;
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Format merge results for display.
+ */
+export function formatMergeResults(results: MergeResult[]): string {
+  if (results.length === 0) return "No completed milestones to merge.";
+
+  const lines: string[] = ["# Merge Results\n"];
+
+  for (const r of results) {
+    if (r.success) {
+      const pushStatus = r.pushed ? " (pushed)" : "";
+      lines.push(`- **${r.milestoneId}** — merged successfully${pushStatus}`);
+    } else if (r.conflictFiles) {
+      lines.push(`- **${r.milestoneId}** — CONFLICT (${r.conflictFiles.length} file(s)):`);
+      for (const f of r.conflictFiles) {
+        lines.push(`  - \`${f}\``);
+      }
+      lines.push(`  Resolve conflicts manually and run \`/gsd parallel merge ${r.milestoneId}\` to retry.`);
+    } else {
+      lines.push(`- **${r.milestoneId}** — failed: ${r.error}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/dist/resources/extensions/gsd/parallel-orchestrator.ts

@@ -0,0 +1,496 @@
+/**
+ * GSD Parallel Orchestrator — Core engine for parallel milestone orchestration.
+ *
+ * Manages worker lifecycle, budget tracking, and coordination. Workers are
+ * separate processes spawned via child_process, each running in its own git
+ * worktree with GSD_MILESTONE_LOCK env var set. The coordinator monitors
+ * workers via session status files (see session-status-io.ts).
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gsdRoot } from "./paths.js";
+import { createWorktree, worktreePath } from "./worktree-manager.js";
+import { autoWorktreeBranch, runWorktreePostCreateHook } from "./auto-worktree.js";
+import { nativeBranchExists } from "./native-git-bridge.js";
+import { readIntegrationBranch } from "./git-service.js";
+import { resolveParallelConfig } from "./preferences.js";
+import type { GSDPreferences } from "./preferences.js";
+import type { ParallelConfig } from "./types.js";
+import {
+  writeSessionStatus,
+  readAllSessionStatuses,
+  removeSessionStatus,
+  sendSignal,
+  cleanupStaleSessions,
+  type SessionStatus,
+} from "./session-status-io.js";
+import {
+  analyzeParallelEligibility,
+  type ParallelCandidates,
+} from "./parallel-eligibility.js";
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+export interface WorkerInfo {
+  milestoneId: string;
+  title: string;
+  pid: number;
+  process: ChildProcess | null; // null after process exits
+  worktreePath: string;
+  startedAt: number;
+  state: "running" | "paused" | "stopped" | "error";
+  completedUnits: number;
+  cost: number;
+}
+
+export interface OrchestratorState {
+  active: boolean;
+  workers: Map<string, WorkerInfo>;
+  config: ParallelConfig;
+  totalCost: number;
+  startedAt: number;
+}
+
+// ─── Module State ──────────────────────────────────────────────────────────
+
+let state: OrchestratorState | null = null;
+
+// ─── Accessors ─────────────────────────────────────────────────────────────
+
+/** Returns true if the orchestrator is active and has been initialized. */
+export function isParallelActive(): boolean {
+  return state?.active ?? false;
+}
+
+/** Returns the current orchestrator state, or null if not initialized. */
+export function getOrchestratorState(): OrchestratorState | null {
+  return state;
+}
+
+/** Returns a snapshot of all tracked workers as an array. */
+export function getWorkerStatuses(): WorkerInfo[] {
+  if (!state) return [];
+  return [...state.workers.values()];
+}
+
+// ─── Preparation ───────────────────────────────────────────────────────────
+
+/**
+ * Analyze eligibility and prepare for parallel start.
+ * Returns the candidates report without actually starting workers.
+ */
+export async function prepareParallelStart(
+  basePath: string,
+  _prefs: GSDPreferences | undefined,
+): Promise<ParallelCandidates> {
+  return analyzeParallelEligibility(basePath);
+}
+
+// ─── Start ─────────────────────────────────────────────────────────────────
+
+/**
+ * Start parallel execution with the given eligible milestones.
+ * Creates worktrees, spawns worker processes, and begins monitoring.
+ */
+export async function startParallel(
+  basePath: string,
+  milestoneIds: string[],
+  prefs: GSDPreferences | undefined,
+): Promise<{ started: string[]; errors: Array<{ mid: string; error: string }> }> {
+  // Prevent workers from spawning nested parallel sessions
+  if (process.env.GSD_PARALLEL_WORKER) {
+    return { started: [], errors: [{ mid: "all", error: "Cannot start parallel from within a parallel worker" }] };
+  }
+
+  const config = resolveParallelConfig(prefs);
+  const now = Date.now();
+
+  // Initialize orchestrator state
+  state = {
+    active: true,
+    workers: new Map(),
+    config,
+    totalCost: 0,
+    startedAt: now,
+  };
+
+  const started: string[] = [];
+  const errors: Array<{ mid: string; error: string }> = [];
+
+  // Cap to max_workers
+  const toStart = milestoneIds.slice(0, config.max_workers);
+
+  for (const mid of toStart) {
+    try {
+      // Create the worktree (without chdir — coordinator stays in project root)
+      let wtPath: string;
+      try {
+        wtPath = createMilestoneWorktree(basePath, mid);
+      } catch {
+        // Worktree creation may fail in test environments or when git
+        // is not available. Fall back to a placeholder path.
+        wtPath = worktreePath(basePath, mid);
+      }
+
+      const worker: WorkerInfo = {
+        milestoneId: mid,
+        title: mid,
+        pid: process.pid,
+        process: null,
+        worktreePath: wtPath,
+        startedAt: now,
+        state: "running",
+        completedUnits: 0,
+        cost: 0,
+      };
+
+      state.workers.set(mid, worker);
+
+      // Write initial session status
+      const sessionStatus: SessionStatus = {
+        milestoneId: mid,
+        pid: worker.pid,
+        state: "running",
+        currentUnit: null,
+        completedUnits: 0,
+        cost: 0,
+        lastHeartbeat: now,
+        startedAt: now,
+        worktreePath: wtPath,
+      };
+      writeSessionStatus(basePath, sessionStatus);
+
+      // Attempt to spawn the worker process.
+      // Spawning may fail if the CLI binary is not available (e.g., in tests).
+      // The worker is still tracked and can be spawned later via spawnWorker().
+      const spawned = spawnWorker(basePath, mid);
+      if (!spawned) {
+        // Worker tracked but not yet running a process.
+        // State stays "running" so coordinator can retry or user can investigate.
+      }
+
+      started.push(mid);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push({ mid, error: message });
+    }
+  }
+
+  // If nothing started successfully, deactivate
+  if (started.length === 0) {
+    state.active = false;
+  }
+
+  return { started, errors };
+}
+
+// ─── Worktree Creation ────────────────────────────────────────────────────
+
+/**
+ * Create a git worktree for a milestone without changing the coordinator's cwd.
+ * Uses milestone/<MID> branch naming (same as auto-worktree.ts).
+ */
+function createMilestoneWorktree(basePath: string, milestoneId: string): string {
+  const branch = autoWorktreeBranch(milestoneId);
+  const branchExists = nativeBranchExists(basePath, branch);
+
+  let info: { name: string; path: string; branch: string; exists: boolean };
+  if (branchExists) {
+    info = createWorktree(basePath, milestoneId, { branch, reuseExistingBranch: true });
+  } else {
+    const integrationBranch = readIntegrationBranch(basePath, milestoneId) ?? undefined;
+    info = createWorktree(basePath, milestoneId, { branch, startPoint: integrationBranch });
+  }
+
+  // Run post-create hook if configured
+  runWorktreePostCreateHook(basePath, info.path);
+
+  return info.path;
+}
+
+// ─── Worker Spawning ───────────────────────────────────────────────────
+
+/**
+ * Spawn a worker process for a milestone.
+ * The worker runs `gsd --print "/gsd auto"` in the milestone's worktree
+ * with GSD_MILESTONE_LOCK set to isolate state derivation.
+ */
+export function spawnWorker(
+  basePath: string,
+  milestoneId: string,
+): boolean {
+  if (!state) return false;
+  const worker = state.workers.get(milestoneId);
+  if (!worker) return false;
+  if (worker.process) return true; // already spawned
+
+  // Resolve the GSD CLI binary path
+  const binPath = resolveGsdBin();
+  if (!binPath) return false;
+
+  let child: ChildProcess;
+  try {
+    child = spawn(process.execPath, [binPath, "--print", "/gsd auto"], {
+      cwd: worker.worktreePath,
+      env: {
+        ...process.env,
+        GSD_MILESTONE_LOCK: milestoneId,
+        // Prevent workers from spawning their own parallel sessions
+        GSD_PARALLEL_WORKER: "1",
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false,
+    });
+  } catch {
+    return false;
+  }
+
+  // Handle spawn errors (e.g., ENOENT when binary doesn't exist)
+  child.on("error", () => {
+    if (!state) return;
+    const w = state.workers.get(milestoneId);
+    if (w) {
+      w.process = null;
+      // Don't change state — spawn failure is non-fatal, coordinator can retry
+    }
+  });
+
+  worker.process = child;
+  worker.pid = child.pid ?? 0;
+
+  if (!child.pid) {
+    // Spawn returned but no PID — process failed to start
+    worker.process = null;
+    return false;
+  }
+
+  // Update session status with real PID
+  writeSessionStatus(basePath, {
+    milestoneId,
+    pid: worker.pid,
+    state: "running",
+    currentUnit: null,
+    completedUnits: worker.completedUnits,
+    cost: worker.cost,
+    lastHeartbeat: Date.now(),
+    startedAt: worker.startedAt,
+    worktreePath: worker.worktreePath,
+  });
+
+  // Handle worker exit
+  child.on("exit", (code) => {
+    if (!state) return;
+    const w = state.workers.get(milestoneId);
+    if (!w) return;
+
+    w.process = null;
+    if (w.state === "stopped") return; // graceful stop, already handled
+
+    if (code === 0) {
+      w.state = "stopped";
+    } else {
+      w.state = "error";
+    }
+
+    // Update session status
+    writeSessionStatus(basePath, {
+      milestoneId,
+      pid: w.pid,
+      state: w.state,
+      currentUnit: null,
+      completedUnits: w.completedUnits,
+      cost: w.cost,
+      lastHeartbeat: Date.now(),
+      startedAt: w.startedAt,
+      worktreePath: w.worktreePath,
+    });
+  });
+
+  return true;
+}
+
+/**
+ * Resolve the GSD CLI binary path.
+ * Uses GSD_BIN_PATH env var (set by loader.ts) or falls back to
+ * finding the binary relative to the current module.
+ */
+function resolveGsdBin(): string | null {
+  // GSD_BIN_PATH is set by loader.ts to the absolute path of dist/loader.js
+  if (process.env.GSD_BIN_PATH && existsSync(process.env.GSD_BIN_PATH)) {
+    return process.env.GSD_BIN_PATH;
+  }
+
+  // Fallback: try to find loader.js relative to this file
+  // This file is at dist/resources/extensions/gsd/parallel-orchestrator.js
+  // loader.js is at dist/loader.js
+  let thisDir: string;
+  try {
+    thisDir = dirname(fileURLToPath(import.meta.url));
+  } catch {
+    thisDir = process.cwd();
+  }
+  const candidates = [
+    join(thisDir, "..", "..", "..", "loader.js"),
+    join(thisDir, "..", "..", "..", "..", "dist", "loader.js"),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+// ─── Stop ──────────────────────────────────────────────────────────────────
+
+/**
+ * Stop all workers or a specific milestone's worker.
+ * Sends stop signals and updates tracking state.
+ */
+export async function stopParallel(
+  basePath: string,
+  milestoneId?: string,
+): Promise<void> {
+  if (!state) return;
+
+  const targets = milestoneId
+    ? [milestoneId]
+    : [...state.workers.keys()];
+
+  for (const mid of targets) {
+    const worker = state.workers.get(mid);
+    if (!worker) continue;
+
+    // Send stop signal via file-based IPC (worker checks on next dispatch)
+    sendSignal(basePath, mid, "stop");
+
+    // Also send SIGTERM to the process for immediate response
+    if (worker.process && worker.pid > 0) {
+      try {
+        worker.process.kill("SIGTERM");
+      } catch { /* process may already be dead */ }
+    }
+
+    // Update in-memory state
+    worker.state = "stopped";
+    worker.process = null;
+
+    // Clean up session status file
+    removeSessionStatus(basePath, mid);
+  }
+
+  // If stopping all workers, deactivate the orchestrator
+  if (!milestoneId) {
+    state.active = false;
+  }
+}
+
+// ─── Pause / Resume ────────────────────────────────────────────────────────
+
+/** Pause a specific worker or all workers. */
+export function pauseWorker(
+  basePath: string,
+  milestoneId?: string,
+): void {
+  if (!state) return;
+
+  const targets = milestoneId
+    ? [milestoneId]
+    : [...state.workers.keys()];
+
+  for (const mid of targets) {
+    const worker = state.workers.get(mid);
+    if (!worker || worker.state !== "running") continue;
+
+    sendSignal(basePath, mid, "pause");
+    worker.state = "paused";
+  }
+}
+
+/** Resume a specific worker or all workers. */
+export function resumeWorker(
+  basePath: string,
+  milestoneId?: string,
+): void {
+  if (!state) return;
+
+  const targets = milestoneId
+    ? [milestoneId]
+    : [...state.workers.keys()];
+
+  for (const mid of targets) {
+    const worker = state.workers.get(mid);
+    if (!worker || worker.state !== "paused") continue;
+
+    sendSignal(basePath, mid, "resume");
+    worker.state = "running";
+  }
+}
+
+// ─── Status Refresh ────────────────────────────────────────────────────────
+
+/**
+ * Poll worker statuses from disk and update orchestrator state.
+ * Call this periodically from the dashboard refresh cycle.
+ */
+export function refreshWorkerStatuses(basePath: string): void {
+  if (!state) return;
+
+  // Clean up stale sessions first
+  const staleIds = cleanupStaleSessions(basePath);
+  for (const mid of staleIds) {
+    const worker = state.workers.get(mid);
+    if (worker) {
+      worker.state = "error";
+      worker.process = null;
+    }
+  }
+
+  // Read all live session statuses from disk
+  const statuses = readAllSessionStatuses(basePath);
+  const statusMap = new Map<string, SessionStatus>();
+  for (const s of statuses) {
+    statusMap.set(s.milestoneId, s);
+  }
+
+  // Update in-memory worker state from disk data
+  for (const [mid, worker] of state.workers) {
+    const diskStatus = statusMap.get(mid);
+    if (!diskStatus) continue;
+
+    worker.state = diskStatus.state;
+    worker.completedUnits = diskStatus.completedUnits;
+    worker.cost = diskStatus.cost;
+    worker.pid = diskStatus.pid;
+  }
+
+  // Recalculate aggregate cost
+  state.totalCost = 0;
+  for (const worker of state.workers.values()) {
+    state.totalCost += worker.cost;
+  }
+}
+
+// ─── Budget ────────────────────────────────────────────────────────────────
+
+/** Get aggregate cost across all workers. */
+export function getAggregateCost(): number {
+  if (!state) return 0;
+  return state.totalCost;
+}
+
+/** Check if budget ceiling has been reached. */
+export function isBudgetExceeded(): boolean {
+  if (!state) return false;
+  if (state.config.budget_ceiling == null) return false;
+  return state.totalCost >= state.config.budget_ceiling;
+}
+
+// ─── Reset ─────────────────────────────────────────────────────────────────
+
+/** Reset orchestrator state. Called on clean shutdown. */
+export function resetOrchestrator(): void {
+  state = null;
+}