sequant 2.1.1 → 2.2.0

package/dist/src/lib/workflow/run-orchestrator.js

@@ -0,0 +1,510 @@
+/**
+ * RunOrchestrator — CLI-free execution engine for sequant workflows.
+ *
+ * Owns the full lifecycle: config → issue discovery → dispatch → results.
+ * Importable and usable without Commander.js or CLI context.
+ *
+ * @module
+ */
+import chalk from "chalk";
+import { spawnSync } from "child_process";
+import pLimit from "p-limit";
+import { detectDefaultBranch, ensureWorktrees, ensureWorktreesChain, getWorktreeDiffStats, } from "./worktree-manager.js";
+import { LogWriter } from "./log-writer.js";
+import { StateManager } from "./state-manager.js";
+import { ShutdownManager } from "../shutdown.js";
+import { getIssueInfo, sortByDependencies, parseBatches, runIssueWithLogging, } from "./batch-executor.js";
+import { reconcileStateAtStartup } from "./state-utils.js";
+import { getCommitHash } from "./git-diff-utils.js";
+import { MetricsWriter } from "./metrics-writer.js";
+import { determineOutcome } from "./metrics-schema.js";
+import { getTokenUsageForRun } from "./token-utils.js";
+import { resolveRunOptions, buildExecutionConfig } from "./config-resolver.js";
+// ── Orchestrator ────────────────────────────────────────────────────────────
+/**
+ * CLI-free workflow execution engine.
+ *
+ * Two usage modes:
+ * 1. Full lifecycle: `RunOrchestrator.run(init, issueNumbers)` — handles
+ *    services, worktrees, state guard, execution, and metrics.
+ * 2. Low-level: `new RunOrchestrator(config).execute(issueNumbers)` — caller
+ *    manages setup/teardown.
+ */
+export class RunOrchestrator {
+    cfg;
+    constructor(config) {
+        this.validate(config);
+        this.cfg = config;
+    }
+    /**
+     * Pure config resolution — no side effects.
+     *
+     * Produces a `ResolvedRun` containing merged options, execution config,
+     * parsed/sorted issue numbers, base branch, and display-only flags. Safe
+     * to call for preview purposes (e.g. CLI config display before run).
+     *
+     * `run()` uses this internally to avoid duplicating resolution logic.
+     */
+    static resolveConfig(init, issueArgs, batches) {
+        const { options, settings, manifest } = init;
+        const mergedOptions = resolveRunOptions(options, settings);
+        const baseBranch = init.baseBranch ??
+            options.base ??
+            settings.run.defaultBase ??
+            detectDefaultBranch(mergedOptions.verbose ?? false);
+        let issueNumbers;
+        let resolvedBatches = batches ?? null;
+        if (mergedOptions.batch &&
+            mergedOptions.batch.length > 0 &&
+            !resolvedBatches) {
+            resolvedBatches = parseBatches(mergedOptions.batch);
+            issueNumbers = resolvedBatches.flat();
+        }
+        else if (resolvedBatches) {
+            issueNumbers = resolvedBatches.flat();
+        }
+        else {
+            issueNumbers = issueArgs
+                .map((i) => parseInt(i, 10))
+                .filter((n) => !isNaN(n));
+        }
+        if (issueNumbers.length > 1 && !resolvedBatches) {
+            issueNumbers = sortByDependencies(issueNumbers);
+        }
+        const config = buildExecutionConfig(mergedOptions, settings, issueNumbers.length);
+        const logEnabled = !mergedOptions.noLog &&
+            !config.dryRun &&
+            (mergedOptions.logJson ?? settings.run.logJson ?? false);
+        return {
+            mergedOptions,
+            config,
+            issueNumbers,
+            batches: resolvedBatches,
+            baseBranch,
+            stack: manifest.stack,
+            autoDetectPhases: mergedOptions.autoDetectPhases ?? false,
+            worktreeIsolationEnabled: mergedOptions.worktreeIsolation !== false && issueNumbers.length > 0,
+            logEnabled,
+            stateEnabled: !config.dryRun,
+        };
+    }
+    /**
+     * Full lifecycle execution — the primary entry point for programmatic use.
+     *
+     * Handles: config resolution → services setup → state guard →
+     * issue discovery → worktree creation → execution → metrics → cleanup.
+     */
+    static async run(init, issueArgs, batches) {
+        const { manifest, onProgress, settings } = init;
+        // ── Config resolution ──────────────────────────────────────────────
+        const resolved = RunOrchestrator.resolveConfig(init, issueArgs, batches);
+        const { mergedOptions, config, baseBranch } = resolved;
+        let { issueNumbers } = resolved;
+        const resolvedBatches = resolved.batches;
+        if (issueNumbers.length === 0) {
+            return {
+                results: [],
+                logPath: null,
+                exitCode: 0,
+                worktreeMap: new Map(),
+                issueInfoMap: new Map(),
+                config,
+                mergedOptions,
+                logWriter: null,
+            };
+        }
+        // ── Services setup ─────────────────────────────────────────────────
+        let logWriter = null;
+        const shouldLog = !mergedOptions.noLog &&
+            !config.dryRun &&
+            (mergedOptions.logJson ?? settings.run.logJson);
+        if (shouldLog) {
+            const runConfig = {
+                phases: config.phases,
+                sequential: config.sequential,
+                qualityLoop: config.qualityLoop,
+                maxIterations: config.maxIterations,
+                chain: mergedOptions.chain,
+                qaGate: mergedOptions.qaGate,
+            };
+            try {
+                logWriter = new LogWriter({
+                    logPath: mergedOptions.logPath ?? settings.run.logPath,
+                    verbose: config.verbose,
+                    startCommit: getCommitHash(process.cwd()),
+                });
+                await logWriter.initialize(runConfig);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.log(chalk.yellow(`  ! Log initialization failed, continuing without logging: ${msg}`));
+                logWriter = null;
+            }
+        }
+        let stateManager = null;
+        if (!config.dryRun) {
+            stateManager = new StateManager({ verbose: config.verbose });
+        }
+        const shutdown = new ShutdownManager();
+        if (logWriter) {
+            const writer = logWriter;
+            shutdown.registerCleanup("Finalize run logs", async () => {
+                await writer.finalize();
+            });
+        }
+        // ── Pre-flight state guard ─────────────────────────────────────────
+        if (stateManager && !config.dryRun) {
+            try {
+                const reconcileResult = await reconcileStateAtStartup({
+                    verbose: config.verbose,
+                });
+                if (reconcileResult.success && reconcileResult.advanced.length > 0) {
+                    console.log(chalk.gray(`  State reconciled: ${reconcileResult.advanced.map((n) => `#${n}`).join(", ")} → merged`));
+                }
+            }
+            catch (error) {
+                logNonFatalWarning("  !  State reconciliation failed, continuing...", error, config.verbose);
+            }
+        }
+        if (stateManager && !config.dryRun && !mergedOptions.force) {
+            const activeIssues = [];
+            for (const issueNumber of issueNumbers) {
+                try {
+                    const issueState = await stateManager.getIssueState(issueNumber);
+                    if (issueState &&
+                        (issueState.status === "ready_for_merge" ||
+                            issueState.status === "merged")) {
+                        console.log(chalk.yellow(`  !  #${issueNumber}: already ${issueState.status} — skipping (use --force to re-run)`));
+                    }
+                    else {
+                        activeIssues.push(issueNumber);
+                    }
+                }
+                catch (error) {
+                    logNonFatalWarning(`  !  State lookup failed for #${issueNumber}, including anyway...`, error, config.verbose);
+                    activeIssues.push(issueNumber);
+                }
+            }
+            if (activeIssues.length < issueNumbers.length) {
+                issueNumbers = activeIssues;
+                if (issueNumbers.length === 0) {
+                    console.log(chalk.yellow(`\n  All issues already completed. Use --force to re-run.`));
+                    shutdown.dispose();
+                    return {
+                        results: [],
+                        logPath: null,
+                        exitCode: 0,
+                        worktreeMap: new Map(),
+                        issueInfoMap: new Map(),
+                        config,
+                        mergedOptions,
+                        logWriter: null,
+                    };
+                }
+            }
+        }
+        // ── Issue info + worktree setup ────────────────────────────────────
+        const issueInfoMap = new Map();
+        for (const issueNumber of issueNumbers) {
+            issueInfoMap.set(issueNumber, await getIssueInfo(issueNumber));
+        }
+        const useWorktreeIsolation = mergedOptions.worktreeIsolation !== false && issueNumbers.length > 0;
+        let worktreeMap = new Map();
+        if (useWorktreeIsolation && !config.dryRun) {
+            const issueData = issueNumbers.map((num) => ({
+                number: num,
+                title: issueInfoMap.get(num)?.title || `Issue #${num}`,
+            }));
+            if (mergedOptions.chain) {
+                worktreeMap = await ensureWorktreesChain(issueData, config.verbose, manifest.packageManager, baseBranch);
+            }
+            else {
+                worktreeMap = await ensureWorktrees(issueData, config.verbose, manifest.packageManager, baseBranch);
+            }
+            for (const [issueNum, worktree] of worktreeMap.entries()) {
+                if (!worktree.existed) {
+                    shutdown.registerCleanup(`Cleanup worktree for #${issueNum}`, async () => {
+                        spawnSync("git", ["worktree", "remove", "--force", worktree.path], {
+                            stdio: "pipe",
+                        });
+                    });
+                }
+            }
+        }
+        // ── Execute ────────────────────────────────────────────────────────
+        let results = [];
+        try {
+            const orchestrator = new RunOrchestrator({
+                config,
+                options: mergedOptions,
+                issueInfoMap,
+                worktreeMap,
+                services: { logWriter, stateManager, shutdownManager: shutdown },
+                packageManager: manifest.packageManager,
+                baseBranch,
+                onProgress,
+            });
+            if (resolvedBatches) {
+                for (let batchIdx = 0; batchIdx < resolvedBatches.length; batchIdx++) {
+                    const batch = resolvedBatches[batchIdx];
+                    console.log(chalk.blue(`\n  Batch ${batchIdx + 1}/${resolvedBatches.length}: Issues ${batch.map((n) => `#${n}`).join(", ")}`));
+                    const batchResults = await orchestrator.execute(batch);
+                    results.push(...batchResults);
+                    const batchFailed = batchResults.some((r) => !r.success);
+                    if (batchFailed && config.sequential) {
+                        console.log(chalk.yellow(`\n  !  Batch ${batchIdx + 1} failed, stopping batch execution`));
+                        break;
+                    }
+                }
+            }
+            else {
+                results = await orchestrator.execute(issueNumbers);
+            }
+            // ── Finalize logs ──────────────────────────────────────────────
+            let logPath = null;
+            if (logWriter) {
+                logPath = await logWriter.finalize({
+                    endCommit: getCommitHash(process.cwd()),
+                });
+            }
+            // ── Record metrics ─────────────────────────────────────────────
+            if (!config.dryRun && results.length > 0) {
+                try {
+                    await RunOrchestrator.recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers);
+                }
+                catch (metricsError) {
+                    logNonFatalWarning("  !  Metrics recording failed, continuing...", metricsError, config.verbose);
+                }
+            }
+            return {
+                results,
+                logPath,
+                exitCode: results.some((r) => !r.success) && !config.dryRun ? 1 : 0,
+                worktreeMap,
+                issueInfoMap,
+                config,
+                mergedOptions,
+                logWriter,
+            };
+        }
+        finally {
+            shutdown.dispose();
+        }
+    }
+    /**
+     * Execute workflow for the given issue numbers.
+     * Returns one IssueResult per issue.
+     */
+    async execute(issueNumbers) {
+        if (issueNumbers.length === 0) {
+            return [];
+        }
+        const batchCtx = this.buildBatchContext();
+        const { config } = this.cfg;
+        const options = this.cfg.options;
+        // Chain mode implies sequential
+        if (options.chain) {
+            config.sequential = true;
+        }
+        if (config.sequential) {
+            return this.executeSequential(issueNumbers, batchCtx, options);
+        }
+        return this.executeParallel(issueNumbers, batchCtx);
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────
+    validate(config) {
+        if (!config.config) {
+            throw new Error("OrchestratorConfig.config is required");
+        }
+        if (!config.config.phases ||
+            !Array.isArray(config.config.phases) ||
+            config.config.phases.length === 0) {
+            throw new Error("OrchestratorConfig.config.phases must be a non-empty array");
+        }
+    }
+    buildBatchContext() {
+        const { config, options, issueInfoMap, worktreeMap, services } = this.cfg;
+        return {
+            config,
+            options,
+            issueInfoMap,
+            worktreeMap,
+            logWriter: services.logWriter ?? null,
+            stateManager: services.stateManager ?? null,
+            shutdownManager: services.shutdownManager,
+            packageManager: this.cfg.packageManager,
+            baseBranch: this.cfg.baseBranch,
+            onProgress: this.cfg.onProgress,
+        };
+    }
+    async executeSequential(issueNumbers, batchCtx, options) {
+        const results = [];
+        const shutdown = this.cfg.services.shutdownManager;
+        for (let i = 0; i < issueNumbers.length; i++) {
+            const issueNumber = issueNumbers[i];
+            if (shutdown?.shuttingDown) {
+                break;
+            }
+            const result = await this.executeOneIssue({
+                issueNumber,
+                batchCtx,
+                chain: options.chain
+                    ? { enabled: true, isLast: i === issueNumbers.length - 1 }
+                    : undefined,
+            });
+            results.push(result);
+            if (!result.success) {
+                if (options.qaGate && options.chain) {
+                    const qaFailed = result.phaseResults.some((p) => p.phase === "qa" && !p.success);
+                    if (qaFailed)
+                        break;
+                }
+                break;
+            }
+        }
+        return results;
+    }
+    async executeParallel(issueNumbers, batchCtx) {
+        const limit = pLimit(this.cfg.config.concurrency);
+        const shutdown = this.cfg.services.shutdownManager;
+        const settledResults = await Promise.allSettled(issueNumbers.map((issueNumber) => limit(async () => {
+            if (shutdown?.shuttingDown) {
+                return {
+                    issueNumber,
+                    success: false,
+                    phaseResults: [],
+                    durationSeconds: 0,
+                    loopTriggered: false,
+                };
+            }
+            return this.executeOneIssue({
+                issueNumber,
+                batchCtx: { ...batchCtx, onProgress: this.cfg.onProgress },
+                parallelIssueNumber: issueNumber,
+            });
+        })));
+        return settledResults.map((settled, i) => {
+            if (settled.status === "fulfilled") {
+                return settled.value;
+            }
+            return {
+                issueNumber: issueNumbers[i],
+                success: false,
+                phaseResults: [],
+                durationSeconds: 0,
+                loopTriggered: false,
+            };
+        });
+    }
+    async executeOneIssue(args) {
+        const { issueNumber, batchCtx, chain, parallelIssueNumber } = args;
+        const { config, options, issueInfoMap, worktreeMap, logWriter, stateManager, shutdownManager, packageManager, baseBranch, onProgress, } = batchCtx;
+        const issueInfo = issueInfoMap.get(issueNumber) ?? {
+            title: `Issue #${issueNumber}`,
+            labels: [],
+        };
+        const worktreeInfo = worktreeMap.get(issueNumber);
+        if (logWriter) {
+            logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
+        }
+        const ctx = {
+            issueNumber,
+            title: issueInfo.title,
+            labels: issueInfo.labels,
+            config,
+            options,
+            services: { logWriter, stateManager, shutdownManager },
+            worktree: worktreeInfo
+                ? { path: worktreeInfo.path, branch: worktreeInfo.branch }
+                : undefined,
+            chain,
+            packageManager,
+            baseBranch,
+            onProgress,
+        };
+        const result = await runIssueWithLogging(ctx);
+        if (logWriter && result.prNumber && result.prUrl) {
+            logWriter.setPRInfo(result.prNumber, result.prUrl, parallelIssueNumber);
+        }
+        if (logWriter) {
+            logWriter.completeIssue(parallelIssueNumber);
+        }
+        return result;
+    }
+    static async recordMetrics(config, mergedOptions, results, worktreeMap, issueNumbers) {
+        const metricsWriter = new MetricsWriter({ verbose: config.verbose });
+        const totalDuration = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
+        const allPhases = new Set();
+        for (const result of results) {
+            for (const pr of result.phaseResults) {
+                const phase = pr.phase;
+                if ([
+                    "spec",
+                    "security-review",
+                    "testgen",
+                    "exec",
+                    "test",
+                    "qa",
+                    "loop",
+                ].includes(phase)) {
+                    allPhases.add(phase);
+                }
+            }
+        }
+        let totalFilesChanged = 0;
+        let totalLinesAdded = 0;
+        let totalQaIterations = 0;
+        for (const result of results) {
+            const wt = worktreeMap.get(result.issueNumber);
+            if (wt?.path) {
+                const s = getWorktreeDiffStats(wt.path);
+                totalFilesChanged += s.filesChanged;
+                totalLinesAdded += s.linesAdded;
+            }
+            if (result.loopTriggered) {
+                totalQaIterations += result.phaseResults.filter((p) => p.phase === "loop").length;
+            }
+        }
+        const cliFlags = [];
+        if (mergedOptions.sequential)
+            cliFlags.push("--sequential");
+        if (mergedOptions.chain)
+            cliFlags.push("--chain");
+        if (mergedOptions.qaGate)
+            cliFlags.push("--qa-gate");
+        if (mergedOptions.qualityLoop)
+            cliFlags.push("--quality-loop");
+        if (mergedOptions.testgen)
+            cliFlags.push("--testgen");
+        const tokenUsage = getTokenUsageForRun(undefined, true);
+        const passed = results.filter((r) => r.success).length;
+        await metricsWriter.recordRun({
+            issues: issueNumbers,
+            phases: Array.from(allPhases),
+            outcome: determineOutcome(passed, results.length),
+            duration: totalDuration,
+            model: process.env.ANTHROPIC_MODEL ?? "opus",
+            flags: cliFlags,
+            metrics: {
+                tokensUsed: tokenUsage.tokensUsed,
+                filesChanged: totalFilesChanged,
+                linesAdded: totalLinesAdded,
+                acceptanceCriteria: 0,
+                qaIterations: totalQaIterations,
+                inputTokens: tokenUsage.inputTokens || undefined,
+                outputTokens: tokenUsage.outputTokens || undefined,
+                cacheTokens: tokenUsage.cacheTokens || undefined,
+            },
+        });
+        if (config.verbose) {
+            console.log(chalk.gray("  Metrics recorded to .sequant/metrics.json"));
+        }
+    }
+}
+/** Log a non-fatal warning: one-line summary always, detail in verbose. */
+export function logNonFatalWarning(message, error, verbose) {
+    console.log(chalk.yellow(message));
+    if (verbose) {
+        console.log(chalk.gray(`    ${error}`));
+    }
+}

package/dist/src/lib/workflow/worktree-manager.d.ts

@@ -156,11 +156,12 @@ export declare function ensureWorktreesChain(issues: Array<{
     title: string;
 }>, verbose: boolean, packageManager?: string, baseBranch?: string): Promise<Map<number, WorktreeInfo>>;
 /**
- * Create a checkpoint commit in the worktree after QA passes
- * This allows recovery in case later issues in the chain fail
+ * Create a checkpoint commit in the worktree after QA passes.
+ * Only stages files that were touched by the issue's commits (diff vs baseBranch).
+ * If unrelated dirty files exist, emits a warning and skips the checkpoint.
  * @internal Exported for testing
  */
-export declare function createCheckpointCommit(worktreePath: string, issueNumber: number, verbose: boolean): boolean;
+export declare function createCheckpointCommit(worktreePath: string, issueNumber: number, verbose: boolean, baseBranch?: string): boolean;
 /**
  * Check if any lockfile changed during a rebase and re-run install if needed.
  * This prevents dependency drift when the lockfile was updated on main.

package/dist/src/lib/workflow/worktree-manager.js

@@ -612,30 +612,80 @@ export async function ensureWorktreesChain(issues, verbose, packageManager, base
     return worktrees;
 }
 /**
- * Create a checkpoint commit in the worktree after QA passes
- * This allows recovery in case later issues in the chain fail
+ * Create a checkpoint commit in the worktree after QA passes.
+ * Only stages files that were touched by the issue's commits (diff vs baseBranch).
+ * If unrelated dirty files exist, emits a warning and skips the checkpoint.
  * @internal Exported for testing
  */
-export function createCheckpointCommit(worktreePath, issueNumber, verbose) {
-    // Check if there are uncommitted changes
-    const statusResult = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { stdio: "pipe" });
+export function createCheckpointCommit(worktreePath, issueNumber, verbose, baseBranch) {
+    // Check if there are uncommitted changes.
+    // Use -z (NUL-terminated) so paths with unicode or special chars aren't quoted/escaped.
+    const statusResult = spawnSync("git", ["-C", worktreePath, "status", "--porcelain", "-z"], { stdio: "pipe" });
     if (statusResult.status !== 0) {
         if (verbose) {
             console.log(chalk.yellow(`    !  Could not check git status for checkpoint`));
         }
         return false;
     }
-    const hasChanges = statusResult.stdout.toString().trim().length > 0;
-    if (!hasChanges) {
+    const statusRaw = statusResult.stdout.toString();
+    if (statusRaw.length === 0) {
         if (verbose) {
             console.log(chalk.gray(`    📌 No changes to checkpoint (already committed)`));
         }
         return true;
     }
-    // Stage all changes
-    const addResult = spawnSync("git", ["-C", worktreePath, "add", "-A"], {
-        stdio: "pipe",
-    });
+    // Parse NUL-separated porcelain entries. Each entry is "XY path".
+    // For renames/copies, the next entry is the old path and must be consumed.
+    const entries = statusRaw.split("\0").filter((e) => e.length > 0);
+    const dirtyFiles = [];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const xy = entry.slice(0, 2);
+        const path = entry.slice(3);
+        if (path)
+            dirtyFiles.push(path);
+        // Rename (R) and copy (C) entries are followed by the original path — skip it
+        if (xy[0] === "R" || xy[0] === "C") {
+            i++;
+        }
+    }
+    // Determine which files to stage.
+    // When baseBranch is provided (chain mode), scope to feature paths only.
+    // When baseBranch is absent (non-chain), treat all dirty files as in-scope.
+    let inScope;
+    if (baseBranch) {
+        const diffResult = spawnSync("git", ["-C", worktreePath, "diff", "--name-only", "-z", `${baseBranch}...HEAD`], { stdio: "pipe" });
+        const featurePaths = new Set();
+        if (diffResult.status === 0) {
+            diffResult.stdout
+                .toString()
+                .split("\0")
+                .filter((p) => p.length > 0)
+                .forEach((p) => featurePaths.add(p));
+        }
+        inScope = dirtyFiles.filter((f) => featurePaths.has(f));
+        const outOfScope = dirtyFiles.filter((f) => !featurePaths.has(f));
+        // AC-2: If unrelated dirty files exist, warn and skip checkpoint
+        if (outOfScope.length > 0) {
+            console.log(chalk.yellow(`    ⚠  Skipping checkpoint for #${issueNumber}: ${outOfScope.length} unrelated dirty file(s) in worktree:`));
+            for (const f of outOfScope) {
+                console.log(chalk.yellow(`       - ${f}`));
+            }
+            return false;
+        }
+    }
+    else {
+        // Non-chain mode: all dirty files are in-scope
+        inScope = dirtyFiles;
+    }
+    if (inScope.length === 0) {
+        if (verbose) {
+            console.log(chalk.gray(`    📌 No in-scope changes to checkpoint`));
+        }
+        return true;
+    }
+    // AC-1: Stage only in-scope feature paths
+    const addResult = spawnSync("git", ["-C", worktreePath, "add", "--", ...inScope], { stdio: "pipe" });
     if (addResult.status !== 0) {
         if (verbose) {
             console.log(chalk.yellow(`    !  Could not stage changes for checkpoint`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {