sequant 1.20.2 → 2.0.0

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

@@ -10,6 +10,7 @@ import { existsSync, readFileSync } from "fs";
 import path from "path";
 import { PM_CONFIG } from "../stacks.js";
 import { getResumablePhasesForIssue } from "./phase-detection.js";
+import { GitHubProvider } from "./platforms/github.js";
 /**
  * Lockfile names for different package managers
  */
@@ -797,26 +798,19 @@ export function rebaseBeforePR(worktreePath, issueNumber, packageManager, verbos
  * @internal Exported for testing
  */
 export function createPR(worktreePath, issueNumber, issueTitle, branch, verbose, labels) {
+    const github = new GitHubProvider();
     // Step 1: Check for existing PR on this branch
-    const existingPR = spawnSync("gh", ["pr", "view", branch, "--json", "number,url"], { stdio: "pipe", cwd: worktreePath, timeout: 15000 });
-    if (existingPR.status === 0 && existingPR.stdout) {
-        try {
-            const prInfo = JSON.parse(existingPR.stdout.toString());
-            if (prInfo.number && prInfo.url) {
-                if (verbose) {
-                    console.log(chalk.gray(`    ℹ️  PR #${prInfo.number} already exists for branch ${branch}`));
-                }
-                return {
-                    attempted: true,
-                    success: true,
-                    prNumber: prInfo.number,
-                    prUrl: prInfo.url,
-                };
-            }
-        }
-        catch {
-            // JSON parse failed — no existing PR, continue to create
+    const existingPRInfo = github.viewPRByBranchSync(branch, worktreePath);
+    if (existingPRInfo) {
+        if (verbose) {
+            console.log(chalk.gray(`    ℹ️  PR #${existingPRInfo.number} already exists for branch ${branch}`));
         }
+        return {
+            attempted: true,
+            success: true,
+            prNumber: existingPRInfo.number,
+            prUrl: existingPRInfo.url,
+        };
     }
     // Step 2: Push branch to remote
     if (verbose) {
@@ -849,25 +843,19 @@ export function createPR(worktreePath, issueNumber, issueTitle, branch, verbose,
         `---`,
         `🤖 Generated by \`sequant run\``,
     ].join("\n");
-    const prResult = spawnSync("gh", ["pr", "create", "--title", prTitle, "--body", prBody, "--head", branch], { stdio: "pipe", cwd: worktreePath, timeout: 30000 });
-    if (prResult.status !== 0) {
-        const prError = prResult.stderr?.toString().trim() ?? "Unknown error";
+    const prResult = github.createPRCliSync(prTitle, prBody, branch, worktreePath);
+    if (prResult.exitCode !== 0) {
+        const prError = prResult.stderr.trim() || "Unknown error";
         // Check if PR already exists (race condition or push-before-PR scenarios)
         if (prError.includes("already exists")) {
-            const retryView = spawnSync("gh", ["pr", "view", branch, "--json", "number,url"], { stdio: "pipe", cwd: worktreePath, timeout: 15000 });
-            if (retryView.status === 0 && retryView.stdout) {
-                try {
-                    const prInfo = JSON.parse(retryView.stdout.toString());
-                    return {
-                        attempted: true,
-                        success: true,
-                        prNumber: prInfo.number,
-                        prUrl: prInfo.url,
-                    };
-                }
-                catch {
-                    // Fall through to error
-                }
+            const retryInfo = github.viewPRByBranchSync(branch, worktreePath);
+            if (retryInfo) {
+                return {
+                    attempted: true,
+                    success: true,
+                    prNumber: retryInfo.number,
+                    prUrl: retryInfo.url,
+                };
             }
         }
         console.log(chalk.yellow(`    ⚠️  PR creation failed: ${prError}`));
@@ -878,7 +866,7 @@ export function createPR(worktreePath, issueNumber, issueTitle, branch, verbose,
         };
     }
     // Step 4: Extract PR URL from output and get PR details
-    const prOutput = prResult.stdout?.toString().trim() ?? "";
+    const prOutput = prResult.stdout.trim();
     const prUrlMatch = prOutput.match(/https:\/\/github\.com\/[^\s]+\/pull\/(\d+)/);
     if (prUrlMatch) {
         const prNumber = parseInt(prUrlMatch[1], 10);
@@ -892,21 +880,15 @@ export function createPR(worktreePath, issueNumber, issueTitle, branch, verbose,
         };
     }
     // Fallback: try gh pr view to get details
-    const viewResult = spawnSync("gh", ["pr", "view", branch, "--json", "number,url"], { stdio: "pipe", cwd: worktreePath, timeout: 15000 });
-    if (viewResult.status === 0 && viewResult.stdout) {
-        try {
-            const prInfo = JSON.parse(viewResult.stdout.toString());
-            console.log(chalk.green(`    ✅ PR #${prInfo.number} created: ${prInfo.url}`));
-            return {
-                attempted: true,
-                success: true,
-                prNumber: prInfo.number,
-                prUrl: prInfo.url,
-            };
-        }
-        catch {
-            // Fall through
-        }
+    const viewInfo = github.viewPRByBranchSync(branch, worktreePath);
+    if (viewInfo) {
+        console.log(chalk.green(`    ✅ PR #${viewInfo.number} created: ${viewInfo.url}`));
+        return {
+            attempted: true,
+            success: true,
+            prNumber: viewInfo.number,
+            prUrl: viewInfo.url,
+        };
     }
     // PR was created but we couldn't parse the URL
     console.log(chalk.yellow(`    ⚠️  PR created but could not extract URL from output: ${prOutput}`));

package/dist/src/mcp/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * MCP server public API
+ */
+export { createServer } from "./server.js";

package/dist/src/mcp/index.js

@@ -0,0 +1,4 @@
+/**
+ * MCP server public API
+ */
+export { createServer } from "./server.js";

package/dist/src/mcp/resources.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP Resources for Sequant
+ *
+ * Exposes workflow state and configuration as readable resources.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResources(server: McpServer): void;

package/dist/src/mcp/resources.js

@@ -0,0 +1,111 @@
+/**
+ * MCP Resources for Sequant
+ *
+ * Exposes workflow state and configuration as readable resources.
+ */
+import * as fs from "fs";
+import { StateManager } from "../lib/workflow/state-manager.js";
+import { SETTINGS_PATH } from "../lib/settings.js";
+export function registerResources(server) {
+    // sequant://state — current workflow state
+    server.registerResource("state", "sequant://state", {
+        description: "Dashboard view of all tracked GitHub issues and their workflow progress. " +
+            "Contains per-issue phase status (spec/exec/qa), worktree paths, PR links, and QA verdicts. " +
+            "Read this to understand which issues are in-flight before starting new work.",
+        mimeType: "application/json",
+    }, async () => {
+        try {
+            const stateManager = new StateManager();
+            if (!stateManager.stateExists()) {
+                return {
+                    contents: [
+                        {
+                            uri: "sequant://state",
+                            mimeType: "application/json",
+                            text: JSON.stringify({ issues: {} }),
+                        },
+                    ],
+                };
+            }
+            // Use getAllIssueStates() which applies TTL filtering
+            const filteredIssues = await stateManager.getAllIssueStates();
+            const state = await stateManager.getState();
+            const output = {
+                version: state.version,
+                lastUpdated: state.lastUpdated,
+                lastSynced: state.lastSynced,
+                issues: Object.fromEntries(Object.values(filteredIssues).map((v) => [String(v.number), v])),
+            };
+            return {
+                contents: [
+                    {
+                        uri: "sequant://state",
+                        mimeType: "application/json",
+                        text: JSON.stringify(output, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                contents: [
+                    {
+                        uri: "sequant://state",
+                        mimeType: "application/json",
+                        text: JSON.stringify({
+                            error: "Failed to read state",
+                            message: error instanceof Error ? error.message : String(error),
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+    // sequant://config — current Sequant configuration
+    server.registerResource("config", "sequant://config", {
+        description: "Current Sequant workflow settings including default phases, timeout limits, " +
+            "quality loop configuration, and agent preferences. " +
+            "Read this to understand how sequant_run will behave before invoking it.",
+        mimeType: "application/json",
+    }, async () => {
+        try {
+            if (!fs.existsSync(SETTINGS_PATH)) {
+                return {
+                    contents: [
+                        {
+                            uri: "sequant://config",
+                            mimeType: "application/json",
+                            text: JSON.stringify({
+                                message: "No settings file found. Run `sequant init` to create one.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            const content = fs.readFileSync(SETTINGS_PATH, "utf-8");
+            return {
+                contents: [
+                    {
+                        uri: "sequant://config",
+                        mimeType: "application/json",
+                        text: content,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                contents: [
+                    {
+                        uri: "sequant://config",
+                        mimeType: "application/json",
+                        text: JSON.stringify({
+                            error: "Failed to read config",
+                            message: error instanceof Error ? error.message : String(error),
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/src/mcp/run-registry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Active run registry for MCP server
+ *
+ * Tracks which workflow runs are currently active so that
+ * sequant_status can report isRunning state in real time.
+ *
+ * Module-level singleton — all tools in the same process share one registry.
+ */
+export interface ActiveRun {
+    startedAt: string;
+}
+/**
+ * Register an active run for an issue.
+ * If a run is already registered for this issue, it is replaced.
+ */
+export declare function registerRun(issue: number): void;
+/**
+ * Unregister a run for an issue (called on process exit/error/abort).
+ */
+export declare function unregisterRun(issue: number): void;
+/**
+ * Check if a run is currently active for the given issue.
+ * Returns false for untracked issues.
+ */
+export declare function isRunning(issue: number): boolean;
+/**
+ * Get info about all currently active runs.
+ */
+export declare function getActiveRuns(): ReadonlyMap<number, ActiveRun>;
+/**
+ * Clear all active runs. Intended for testing only.
+ * @internal
+ */
+export declare function clearRegistry(): void;

package/dist/src/mcp/run-registry.js

@@ -0,0 +1,42 @@
+/**
+ * Active run registry for MCP server
+ *
+ * Tracks which workflow runs are currently active so that
+ * sequant_status can report isRunning state in real time.
+ *
+ * Module-level singleton — all tools in the same process share one registry.
+ */
+const activeRuns = new Map();
+/**
+ * Register an active run for an issue.
+ * If a run is already registered for this issue, it is replaced.
+ */
+export function registerRun(issue) {
+    activeRuns.set(issue, { startedAt: new Date().toISOString() });
+}
+/**
+ * Unregister a run for an issue (called on process exit/error/abort).
+ */
+export function unregisterRun(issue) {
+    activeRuns.delete(issue);
+}
+/**
+ * Check if a run is currently active for the given issue.
+ * Returns false for untracked issues.
+ */
+export function isRunning(issue) {
+    return activeRuns.has(issue);
+}
+/**
+ * Get info about all currently active runs.
+ */
+export function getActiveRuns() {
+    return activeRuns;
+}
+/**
+ * Clear all active runs. Intended for testing only.
+ * @internal
+ */
+export function clearRegistry() {
+    activeRuns.clear();
+}

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sequant MCP Server
+ *
+ * Exposes Sequant workflow orchestration as an MCP server.
+ * Any MCP client (Claude Desktop, Cursor, VS Code, etc.) can invoke
+ * Sequant tools to drive structured AI workflows.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Create and configure the Sequant MCP server instance.
+ */
+export declare function createServer(version: string): McpServer;

package/dist/src/mcp/server.js

@@ -0,0 +1,50 @@
+/**
+ * Sequant MCP Server
+ *
+ * Exposes Sequant workflow orchestration as an MCP server.
+ * Any MCP client (Claude Desktop, Cursor, VS Code, etc.) can invoke
+ * Sequant tools to drive structured AI workflows.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerRunTool } from "./tools/run.js";
+import { registerStatusTool } from "./tools/status.js";
+import { registerLogsTool } from "./tools/logs.js";
+import { registerResources } from "./resources.js";
+/**
+ * Create and configure the Sequant MCP server instance.
+ */
+export function createServer(version) {
+    const options = {
+        instructions: [
+            "Sequant orchestrates AI-driven development workflows for GitHub issues.",
+            "Each issue progresses through phases: spec (plan) → exec (implement) → qa (review).",
+            "",
+            "Tools:",
+            "- sequant_status: Check issue progress. Poll every 5-10s during active runs. Always check before calling sequant_run.",
+            "- sequant_run: Execute workflow phases. Long-running (up to 30 min). Returns structured JSON on completion.",
+            "- sequant_logs: Review past run results and debug failures.",
+            "",
+            "Resources:",
+            "- sequant://state: Dashboard view of all tracked issues and their phases.",
+            "- sequant://config: Current workflow settings (timeout, phases, quality loop).",
+            "",
+            "Workflow: Check sequant_status first → sequant_run if needed → poll sequant_status → review sequant_logs on failure.",
+            "Do NOT call sequant_run for issues that are already merged or completed.",
+        ].join("\n"),
+        capabilities: {
+            tools: {},
+            resources: {},
+        },
+    };
+    const server = new McpServer({
+        name: "sequant",
+        version,
+    }, options);
+    // Register tools
+    registerRunTool(server);
+    registerStatusTool(server);
+    registerLogsTool(server);
+    // Register resources
+    registerResources(server);
+    return server;
+}

package/dist/src/mcp/tools/logs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * sequant_logs MCP tool
+ *
+ * Get run logs and metrics.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerLogsTool(server: McpServer): void;

package/dist/src/mcp/tools/logs.js

@@ -0,0 +1,149 @@
+/**
+ * sequant_logs MCP tool
+ *
+ * Get run logs and metrics.
+ */
+import { z } from "zod";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { LOG_PATHS, RunLogSchema } from "../../lib/workflow/run-log-schema.js";
+function resolveLogPath() {
+    const projectPath = LOG_PATHS.project;
+    if (fs.existsSync(projectPath)) {
+        return projectPath;
+    }
+    const userPath = LOG_PATHS.user.replace("~", os.homedir());
+    if (fs.existsSync(userPath)) {
+        return userPath;
+    }
+    return projectPath;
+}
+function parseLogFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const data = JSON.parse(content);
+        return RunLogSchema.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+export function registerLogsTool(server) {
+    server.registerTool("sequant_logs", {
+        title: "Sequant Logs",
+        description: "Get structured run logs for recent workflow executions. " +
+            "Each log contains per-issue phase results (duration, status, errors) and QA verdicts. " +
+            "Use after a sequant_run completes or fails to understand what happened. " +
+            "Logs are stored as run-<ISO-timestamp>-<uuid>.json files.",
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+        inputSchema: {
+            runId: z
+                .string()
+                .optional()
+                .describe("Specific run ID prefix to filter by (e.g. 'run-2026-03-24'). " +
+                "Omit to return the most recent runs."),
+            limit: z
+                .number()
+                .optional()
+                .describe("Number of recent runs to return (default: 5, max: all available)"),
+        },
+    }, async ({ runId, limit }) => {
+        try {
+            const logDir = resolveLogPath();
+            if (!fs.existsSync(logDir)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                logs: [],
+                                message: "No log directory found. Run `sequant run` to generate logs.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            const logFiles = fs
+                .readdirSync(logDir)
+                .filter((f) => f.startsWith("run-") && f.endsWith(".json"))
+                .sort()
+                .reverse();
+            if (logFiles.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                logs: [],
+                                message: "No logs found.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            let logs = [];
+            for (const filename of logFiles) {
+                const filePath = path.join(logDir, filename);
+                const log = parseLogFile(filePath);
+                if (log) {
+                    // Filter by runId if specified
+                    if (runId && !log.runId.startsWith(runId)) {
+                        continue;
+                    }
+                    logs.push(log);
+                }
+            }
+            // Apply limit
+            const maxResults = limit && limit > 0 ? limit : 5;
+            logs = logs.slice(0, maxResults);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            count: logs.length,
+                            logs: logs.map((log) => ({
+                                runId: log.runId,
+                                startTime: log.startTime,
+                                config: log.config,
+                                summary: log.summary,
+                                issues: log.issues.map((issue) => ({
+                                    issueNumber: issue.issueNumber,
+                                    title: issue.title,
+                                    status: issue.status,
+                                    totalDurationSeconds: issue.totalDurationSeconds,
+                                    phases: issue.phases.map((p) => ({
+                                        phase: p.phase,
+                                        status: p.status,
+                                        durationSeconds: p.durationSeconds,
+                                        error: p.error,
+                                        ...(p.verdict && { verdict: p.verdict }),
+                                        ...(p.summary && { summary: p.summary }),
+                                    })),
+                                })),
+                            })),
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "LOGS_ERROR",
+                            message: error instanceof Error ? error.message : String(error),
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/src/mcp/tools/run.d.ts

@@ -0,0 +1,121 @@
+/**
+ * sequant_run MCP tool
+ *
+ * Execute workflow phases for GitHub issues.
+ * Returns structured JSON with per-issue summaries parsed from run logs.
+ * Uses async spawn to keep the MCP server responsive during execution.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RunLog } from "../../lib/workflow/run-log-schema.js";
+/**
+ * Per-issue summary in the structured response
+ */
+interface RunToolIssueSummary {
+    issueNumber: number;
+    status: "success" | "failure" | "partial";
+    phases: Array<{
+        phase: string;
+        status: string;
+        durationSeconds: number;
+    }>;
+    verdict?: string;
+    durationSeconds: number;
+}
+/**
+ * Structured response from sequant_run
+ */
+interface RunToolResponse {
+    status: "success" | "failure";
+    exitCode?: number;
+    issues: RunToolIssueSummary[];
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        durationSeconds: number;
+    };
+    phases: string;
+    rawOutput?: string;
+    error?: string;
+}
+/**
+ * Resolve the CLI binary path to avoid nested npx version mismatches (#389).
+ *
+ * Priority:
+ * 1. process.argv[1] — the script currently running (works for npx, global, local node)
+ * 2. __dirname-relative resolution — fallback for bundled/compiled entry points
+ * 3. "npx" + "sequant" — last resort if nothing else resolves
+ *
+ * Returns [command, prefixArgs] where the full invocation is:
+ *   spawnAsync(command, [...prefixArgs, "run", ...userArgs])
+ */
+export declare function resolveCliBinary(): [string, string[]];
+/**
+ * Find and parse the most recent run log file.
+ *
+ * When runStartTime is provided, only log files created within
+ * MAX_LOG_AGE_MS of that timestamp are considered, preventing
+ * stale logs from a previous run being returned.
+ */
+export declare function readLatestRunLog(runStartTime?: Date): Promise<RunLog | null>;
+/**
+ * Build a structured response from a parsed RunLog
+ */
+export declare function buildStructuredResponse(runLog: RunLog, rawOutput: string, overallStatus: "success" | "failure", exitCode?: number | null, errorOutput?: string): RunToolResponse;
+/** Parsed progress event from a SEQUANT_PROGRESS line. */
+export interface ProgressEvent {
+    issue: number;
+    phase: string;
+    event: "start" | "complete" | "failed";
+    durationSeconds?: number;
+    error?: string;
+}
+/**
+ * Parse a SEQUANT_PROGRESS line emitted by the batch executor.
+ * Returns the parsed event or null if the line isn't a progress line.
+ */
+export declare function parseProgressLine(line: string): ProgressEvent | null;
+/**
+ * Build a human-readable message for a progress notification (AC-3).
+ * @internal Exported for testing only.
+ */
+export declare function formatProgressMessage(event: ProgressEvent): string;
+/**
+ * Create a line buffer that accumulates stream chunks and yields complete lines.
+ * Handles the case where a single `data` event spans partial lines.
+ */
+export declare function createLineBuffer(onLine: (line: string) => void): (chunk: string) => void;
+export declare function registerRunTool(server: McpServer): void;
+export interface SpawnResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Per-phase timeout ceiling (30 minutes) */
+export declare const PHASE_TIMEOUT = 1800000;
+/** Absolute maximum run duration (2 hours), even with progress resets */
+export declare const MAX_TOTAL_TIMEOUT = 7200000;
+export interface SpawnOptions {
+    timeout: number;
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    /** Called with each stderr chunk (real-time, before process exits) */
+    onStderr?: (chunk: string) => void;
+    /** Called with each stdout chunk (real-time, before process exits) */
+    onStdout?: (chunk: string) => void;
+    /**
+     * Called when a progress event is detected from stderr.
+     * When set, enables resettable timeout: the per-phase timeout resets on
+     * each SEQUANT_PROGRESS line, but the absolute ceiling still applies.
+     */
+    onProgress?: () => void;
+    /**
+     * Override the absolute timeout ceiling (defaults to MAX_TOTAL_TIMEOUT).
+     * Only applies when onProgress is set. Useful for testing.
+     * @internal
+     */
+    maxTotalTimeout?: number;
+}
+/** @internal Exported for testing only */
+export declare function spawnAsync(command: string, args: string[], options: SpawnOptions): Promise<SpawnResult>;
+export {};