sequant 1.20.3 → 2.0.0

package/dist/src/lib/ci/inputs.js

@@ -0,0 +1,103 @@
+/**
+ * Input parsing and validation for the GitHub Action.
+ *
+ * Parses raw string inputs from action.yml into validated ActionInputs,
+ * applying defaults and merging with repo-level configuration.
+ */
+import { CI_DEFAULTS } from "./types.js";
+const VALID_PHASES = new Set([
+    "spec",
+    "security-review",
+    "testgen",
+    "exec",
+    "test",
+    "qa",
+    "loop",
+]);
+const VALID_AGENTS = new Set(["claude-code", "aider", "codex"]);
+/**
+ * Parse and validate action inputs, merging with repo config.
+ *
+ * Merge precedence: workflow inputs > config file > action defaults
+ */
+export function parseInputs(raw, config = {}) {
+    const issues = parseIssueNumbers(raw.issues ?? "");
+    const phases = parsePhases(raw.phases, config.phases ?? CI_DEFAULTS.phases);
+    const agent = parseAgent(raw.agent, config.agent ?? CI_DEFAULTS.agent);
+    const timeout = parseTimeout(raw.timeout, config.timeout ?? CI_DEFAULTS.timeout);
+    const qualityLoop = parseBool(raw["quality-loop"], config.qualityLoop ?? CI_DEFAULTS.qualityLoop);
+    const apiKey = raw["api-key"] ?? "";
+    return { issues, phases, agent, timeout, qualityLoop, apiKey };
+}
+/**
+ * Validate that required inputs are present and well-formed.
+ * Returns an array of error messages (empty = valid).
+ */
+export function validateInputs(inputs) {
+    const errors = [];
+    if (inputs.issues.length === 0) {
+        errors.push("No valid issue numbers provided");
+    }
+    if (inputs.phases.length === 0) {
+        errors.push("No valid phases provided");
+    }
+    if (!inputs.apiKey) {
+        errors.push("API key is required — pass via api-key input mapped from a secret");
+    }
+    if (inputs.timeout < 60) {
+        errors.push("Timeout must be at least 60 seconds");
+    }
+    if (inputs.timeout > 7200) {
+        errors.push("Timeout must not exceed 7200 seconds (2 hours)");
+    }
+    return errors;
+}
+/**
+ * Parse space-separated issue numbers.
+ */
+function parseIssueNumbers(input) {
+    if (!input.trim())
+        return [];
+    return input
+        .split(/[\s,]+/)
+        .map((s) => parseInt(s.trim(), 10))
+        .filter((n) => !isNaN(n) && n > 0);
+}
+/**
+ * Parse comma-separated phase names, falling back to default.
+ */
+function parsePhases(input, fallback) {
+    if (!input?.trim())
+        return fallback;
+    const parsed = input
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => VALID_PHASES.has(p));
+    return parsed.length > 0 ? parsed : fallback;
+}
+/**
+ * Parse agent name with validation.
+ */
+function parseAgent(input, fallback) {
+    if (!input?.trim())
+        return fallback;
+    const agent = input.trim();
+    return VALID_AGENTS.has(agent) ? agent : fallback;
+}
+/**
+ * Parse timeout string to number with bounds check.
+ */
+function parseTimeout(input, fallback) {
+    if (!input?.trim())
+        return fallback;
+    const n = parseInt(input.trim(), 10);
+    return isNaN(n) ? fallback : n;
+}
+/**
+ * Parse boolean string.
+ */
+function parseBool(input, fallback) {
+    if (!input?.trim())
+        return fallback;
+    return input.trim().toLowerCase() === "true";
+}

package/dist/src/lib/ci/labels.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Label lifecycle management for CI-triggered workflows.
+ *
+ * Manages the sequant:solving → sequant:done / sequant:failed label
+ * transitions on GitHub issues during and after workflow execution.
+ */
+/**
+ * Get labels to add when a workflow run starts.
+ */
+export declare function getStartLabels(): string[];
+/**
+ * Get labels to remove when a workflow run starts.
+ * Removes the trigger label that initiated the run.
+ */
+export declare function getStartRemoveLabels(triggerLabel?: string): string[];
+/**
+ * Get labels to apply when a workflow completes successfully.
+ */
+export declare function getSuccessLabels(): {
+    add: string[];
+    remove: string[];
+};
+/**
+ * Get labels to apply when a workflow fails.
+ */
+export declare function getFailureLabels(): {
+    add: string[];
+    remove: string[];
+};
+/**
+ * Generate gh CLI commands for label transitions.
+ * Useful for composite action shell steps.
+ */
+export declare function labelCommands(issueNumber: number, transition: "start" | "success" | "failure", triggerLabel?: string): string[];

package/dist/src/lib/ci/labels.js

@@ -0,0 +1,101 @@
+/**
+ * Label lifecycle management for CI-triggered workflows.
+ *
+ * Manages the sequant:solving → sequant:done / sequant:failed label
+ * transitions on GitHub issues during and after workflow execution.
+ */
+import { LIFECYCLE_LABELS, TRIGGER_LABELS } from "./types.js";
+/**
+ * All trigger labels that should be removed when a run starts.
+ */
+const TRIGGER_LABEL_SET = new Set(Object.values(TRIGGER_LABELS));
+/**
+ * Trigger label aliases — labels that trigger the same workflow.
+ * When one is used, all aliases should also be removed to prevent
+ * stale labels during migration (e.g. sequant:solve → sequant:assess).
+ */
+const TRIGGER_ALIASES = new Map([
+    [TRIGGER_LABELS.ASSESS, [TRIGGER_LABELS.SOLVE]],
+    [TRIGGER_LABELS.SOLVE, [TRIGGER_LABELS.ASSESS]],
+]);
+/**
+ * Get labels to add when a workflow run starts.
+ */
+export function getStartLabels() {
+    return [LIFECYCLE_LABELS.SOLVING];
+}
+/**
+ * Get labels to remove when a workflow run starts.
+ * Removes the trigger label that initiated the run.
+ */
+export function getStartRemoveLabels(triggerLabel) {
+    const labels = [];
+    // Remove the trigger label and any aliases (e.g. assess ↔ solve)
+    if (triggerLabel && TRIGGER_LABEL_SET.has(triggerLabel)) {
+        labels.push(triggerLabel);
+        const aliases = TRIGGER_ALIASES.get(triggerLabel);
+        if (aliases) {
+            labels.push(...aliases);
+        }
+    }
+    // Remove any stale outcome labels from prior runs
+    labels.push(LIFECYCLE_LABELS.DONE, LIFECYCLE_LABELS.FAILED);
+    return labels;
+}
+/**
+ * Get labels to apply when a workflow completes successfully.
+ */
+export function getSuccessLabels() {
+    return {
+        add: [LIFECYCLE_LABELS.DONE],
+        remove: [LIFECYCLE_LABELS.SOLVING],
+    };
+}
+/**
+ * Get labels to apply when a workflow fails.
+ */
+export function getFailureLabels() {
+    return {
+        add: [LIFECYCLE_LABELS.FAILED],
+        remove: [LIFECYCLE_LABELS.SOLVING],
+    };
+}
+/**
+ * Generate gh CLI commands for label transitions.
+ * Useful for composite action shell steps.
+ */
+export function labelCommands(issueNumber, transition, triggerLabel) {
+    const commands = [];
+    switch (transition) {
+        case "start": {
+            for (const label of getStartLabels()) {
+                commands.push(`gh issue edit ${issueNumber} --add-label "${label}"`);
+            }
+            for (const label of getStartRemoveLabels(triggerLabel)) {
+                commands.push(`gh issue edit ${issueNumber} --remove-label "${label}" 2>/dev/null || true`);
+            }
+            break;
+        }
+        case "success": {
+            const { add, remove } = getSuccessLabels();
+            for (const label of add) {
+                commands.push(`gh issue edit ${issueNumber} --add-label "${label}"`);
+            }
+            for (const label of remove) {
+                commands.push(`gh issue edit ${issueNumber} --remove-label "${label}" 2>/dev/null || true`);
+            }
+            break;
+        }
+        case "failure": {
+            const { add, remove } = getFailureLabels();
+            for (const label of add) {
+                commands.push(`gh issue edit ${issueNumber} --add-label "${label}"`);
+            }
+            for (const label of remove) {
+                commands.push(`gh issue edit ${issueNumber} --remove-label "${label}" 2>/dev/null || true`);
+            }
+            break;
+        }
+    }
+    return commands;
+}

package/dist/src/lib/ci/outputs.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Output formatting for GitHub Actions.
+ *
+ * Formats IssueResult into structured outputs that can be consumed
+ * by downstream workflow steps via $GITHUB_OUTPUT.
+ */
+import type { IssueResult } from "../workflow/types.js";
+import type { ActionOutputs } from "./types.js";
+/**
+ * Format an IssueResult into GitHub Actions outputs.
+ */
+export declare function formatOutputs(result: IssueResult): ActionOutputs;
+/**
+ * Format multiple issue results into combined outputs.
+ */
+export declare function formatMultiOutputs(results: IssueResult[]): ActionOutputs;
+/**
+ * Generate shell commands to set GitHub Actions outputs.
+ * Each output is written to $GITHUB_OUTPUT file.
+ */
+export declare function outputCommands(outputs: ActionOutputs): string[];
+/**
+ * Generate a GitHub Actions step summary (Markdown).
+ */
+export declare function formatSummary(results: IssueResult[]): string;

package/dist/src/lib/ci/outputs.js

@@ -0,0 +1,84 @@
+/**
+ * Output formatting for GitHub Actions.
+ *
+ * Formats IssueResult into structured outputs that can be consumed
+ * by downstream workflow steps via $GITHUB_OUTPUT.
+ */
+/**
+ * Format an IssueResult into GitHub Actions outputs.
+ */
+export function formatOutputs(result) {
+    return {
+        issue: String(result.issueNumber),
+        success: String(result.success),
+        phases: JSON.stringify(formatPhaseResults(result.phaseResults)),
+        "pr-url": result.prUrl ?? "",
+        duration: String(result.durationSeconds ?? 0),
+    };
+}
+/**
+ * Format multiple issue results into combined outputs.
+ */
+export function formatMultiOutputs(results) {
+    const allSuccess = results.every((r) => r.success);
+    const totalDuration = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
+    const prUrls = results
+        .map((r) => r.prUrl)
+        .filter(Boolean)
+        .join(",");
+    const allPhases = results.flatMap((r) => formatPhaseResults(r.phaseResults));
+    return {
+        issue: results.map((r) => r.issueNumber).join(" "),
+        success: String(allSuccess),
+        phases: JSON.stringify(allPhases),
+        "pr-url": prUrls,
+        duration: String(totalDuration),
+    };
+}
+/**
+ * Format phase results for JSON output.
+ */
+function formatPhaseResults(phases) {
+    return phases.map((p) => ({
+        phase: p.phase,
+        success: p.success,
+        duration: p.durationSeconds ?? 0,
+    }));
+}
+/**
+ * Generate shell commands to set GitHub Actions outputs.
+ * Each output is written to $GITHUB_OUTPUT file.
+ */
+export function outputCommands(outputs) {
+    return Object.entries(outputs).map(([key, value]) => `echo "${key}=${value}" >> "$GITHUB_OUTPUT"`);
+}
+/**
+ * Generate a GitHub Actions step summary (Markdown).
+ */
+export function formatSummary(results) {
+    const lines = [];
+    lines.push("## Sequant Workflow Results\n");
+    for (const result of results) {
+        const icon = result.success ? "✅" : "❌";
+        lines.push(`### ${icon} Issue #${result.issueNumber}\n`);
+        lines.push("| Phase | Status | Duration |");
+        lines.push("|-------|--------|----------|");
+        for (const phase of result.phaseResults) {
+            const status = phase.success ? "✅ Passed" : "❌ Failed";
+            const duration = phase.durationSeconds
+                ? `${phase.durationSeconds}s`
+                : "-";
+            lines.push(`| ${phase.phase} | ${status} | ${duration} |`);
+        }
+        if (result.prUrl) {
+            lines.push(`\n**PR:** ${result.prUrl}`);
+        }
+        if (result.abortReason) {
+            lines.push(`\n**Abort reason:** ${result.abortReason}`);
+        }
+        lines.push("");
+    }
+    const total = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
+    lines.push(`**Total duration:** ${total}s`);
+    return lines.join("\n");
+}

package/dist/src/lib/ci/triggers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Trigger detection — parses GitHub event payloads into structured
+ * trigger results that determine which issues and phases to run.
+ */
+import { type GitHubContext, type TriggerResult } from "./types.js";
+/**
+ * Detect the trigger type and extract issue/phases from a GitHub event.
+ */
+export declare function detectTrigger(context: GitHubContext): TriggerResult;

package/dist/src/lib/ci/triggers.js

@@ -0,0 +1,86 @@
+/**
+ * Trigger detection — parses GitHub event payloads into structured
+ * trigger results that determine which issues and phases to run.
+ */
+import { COMMENT_TRIGGER_PATTERN, TRIGGER_LABELS, } from "./types.js";
+const VALID_PHASES = new Set([
+    "spec",
+    "security-review",
+    "testgen",
+    "exec",
+    "test",
+    "qa",
+    "loop",
+]);
+/**
+ * Map trigger labels to their corresponding phase lists.
+ */
+const LABEL_PHASE_MAP = {
+    [TRIGGER_LABELS.ASSESS]: ["spec", "exec", "qa"],
+    [TRIGGER_LABELS.SOLVE]: ["spec", "exec", "qa"],
+    [TRIGGER_LABELS.SPEC_ONLY]: ["spec"],
+    [TRIGGER_LABELS.EXEC]: ["exec"],
+    [TRIGGER_LABELS.QA]: ["qa"],
+};
+/**
+ * Detect the trigger type and extract issue/phases from a GitHub event.
+ */
+export function detectTrigger(context) {
+    switch (context.eventName) {
+        case "workflow_dispatch":
+            return {
+                trigger: "workflow_dispatch",
+                phases: ["spec", "exec", "qa"],
+                issue: null,
+            };
+        case "issues":
+            return detectLabelTrigger(context);
+        case "issue_comment":
+            return detectCommentTrigger(context);
+        default:
+            return { trigger: "unknown", phases: [], issue: null };
+    }
+}
+/**
+ * Detect label-based trigger from an issues event.
+ */
+function detectLabelTrigger(context) {
+    const { payload } = context;
+    if (payload.action !== "labeled" || !payload.label) {
+        return { trigger: "unknown", phases: [], issue: null };
+    }
+    const labelName = payload.label.name;
+    const phases = LABEL_PHASE_MAP[labelName];
+    if (!phases) {
+        return { trigger: "unknown", phases: [], issue: null };
+    }
+    return {
+        trigger: "label",
+        phases,
+        issue: payload.issue?.number ?? null,
+        label: labelName,
+    };
+}
+/**
+ * Detect @sequant command trigger from an issue comment.
+ */
+function detectCommentTrigger(context) {
+    const { payload } = context;
+    if (payload.action !== "created" || !payload.comment?.body) {
+        return { trigger: "unknown", phases: [], issue: null };
+    }
+    const match = payload.comment.body.match(COMMENT_TRIGGER_PATTERN);
+    if (!match) {
+        return { trigger: "unknown", phases: [], issue: null };
+    }
+    const rawPhases = match[1].split(",").map((p) => p.trim());
+    const phases = rawPhases.filter((p) => VALID_PHASES.has(p));
+    if (phases.length === 0) {
+        return { trigger: "unknown", phases: [], issue: null };
+    }
+    return {
+        trigger: "comment",
+        phases,
+        issue: payload.issue?.number ?? null,
+    };
+}

package/dist/src/lib/ci/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Types for GitHub Actions CI integration.
+ *
+ * These types model the inputs, outputs, triggers, and configuration
+ * that the sequant GitHub Action uses to bridge GitHub events to
+ * sequant workflow execution.
+ */
+import type { Phase } from "../workflow/types.js";
+/**
+ * Validated action inputs after parsing from GitHub Actions context.
+ */
+export interface ActionInputs {
+    /** Issue numbers to process */
+    issues: number[];
+    /** Workflow phases to execute */
+    phases: Phase[];
+    /** Agent backend name */
+    agent: string;
+    /** Phase timeout in seconds */
+    timeout: number;
+    /** Enable quality loop */
+    qualityLoop: boolean;
+    /** API key for the selected agent */
+    apiKey: string;
+}
+/**
+ * Supported GitHub event triggers for the action.
+ */
+export type TriggerType = "workflow_dispatch" | "label" | "comment" | "unknown";
+/**
+ * Labels that map to specific phase configurations.
+ */
+export declare const TRIGGER_LABELS: {
+    /** Full workflow: spec → exec → qa */
+    readonly ASSESS: "sequant:assess";
+    /** @deprecated Use ASSESS instead */
+    readonly SOLVE: "sequant:solve";
+    /** Spec phase only */
+    readonly SPEC_ONLY: "sequant:spec-only";
+    /** Exec phase only */
+    readonly EXEC: "sequant:exec";
+    /** QA phase only */
+    readonly QA: "sequant:qa";
+};
+/**
+ * Labels used for lifecycle tracking.
+ */
+export declare const LIFECYCLE_LABELS: {
+    /** Applied when a run starts */
+    readonly SOLVING: "sequant:solving";
+    /** Applied on successful completion */
+    readonly DONE: "sequant:done";
+    /** Applied on failure */
+    readonly FAILED: "sequant:failed";
+};
+/**
+ * Result of parsing a GitHub event into a trigger.
+ */
+export interface TriggerResult {
+    /** Type of trigger detected */
+    trigger: TriggerType;
+    /** Phases to execute */
+    phases: Phase[];
+    /** Issue number extracted from the event */
+    issue: number | null;
+    /** The label that triggered the action (if label trigger) */
+    label?: string;
+}
+/**
+ * GitHub Actions event payload (subset of fields we use).
+ */
+export interface GitHubEventPayload {
+    action?: string;
+    issue?: {
+        number: number;
+        labels?: Array<{
+            name: string;
+        }>;
+    };
+    label?: {
+        name: string;
+    };
+    comment?: {
+        body: string;
+    };
+}
+/**
+ * GitHub Actions context (subset of fields we use).
+ */
+export interface GitHubContext {
+    eventName: string;
+    payload: GitHubEventPayload;
+}
+/**
+ * Structured action outputs set via $GITHUB_OUTPUT.
+ */
+export interface ActionOutputs {
+    /** The issue number(s) processed */
+    issue: string;
+    /** Whether all phases passed */
+    success: string;
+    /** JSON array of phase results */
+    phases: string;
+    /** URL of created PR (empty if no PR) */
+    "pr-url": string;
+    /** Total duration in seconds */
+    duration: string;
+}
+/**
+ * Repository-level CI configuration from .github/sequant.yml.
+ */
+export interface CIConfig {
+    /** Default agent backend */
+    agent?: string;
+    /** Default phases to execute */
+    phases?: Phase[];
+    /** Default phase timeout in seconds */
+    timeout?: number;
+    /** Enable quality loop by default */
+    qualityLoop?: boolean;
+    /** Maximum concurrent workflow runs */
+    maxConcurrentRuns?: number;
+}
+/**
+ * Merge precedence: workflow inputs > config file > action defaults.
+ */
+export declare const CI_DEFAULTS: Required<CIConfig>;
+/**
+ * Pattern for matching @sequant commands in issue comments.
+ */
+export declare const COMMENT_TRIGGER_PATTERN: RegExp;

package/dist/src/lib/ci/types.js

@@ -0,0 +1,47 @@
+/**
+ * Types for GitHub Actions CI integration.
+ *
+ * These types model the inputs, outputs, triggers, and configuration
+ * that the sequant GitHub Action uses to bridge GitHub events to
+ * sequant workflow execution.
+ */
+/**
+ * Labels that map to specific phase configurations.
+ */
+export const TRIGGER_LABELS = {
+    /** Full workflow: spec → exec → qa */
+    ASSESS: "sequant:assess",
+    /** @deprecated Use ASSESS instead */
+    SOLVE: "sequant:solve",
+    /** Spec phase only */
+    SPEC_ONLY: "sequant:spec-only",
+    /** Exec phase only */
+    EXEC: "sequant:exec",
+    /** QA phase only */
+    QA: "sequant:qa",
+};
+/**
+ * Labels used for lifecycle tracking.
+ */
+export const LIFECYCLE_LABELS = {
+    /** Applied when a run starts */
+    SOLVING: "sequant:solving",
+    /** Applied on successful completion */
+    DONE: "sequant:done",
+    /** Applied on failure */
+    FAILED: "sequant:failed",
+};
+/**
+ * Merge precedence: workflow inputs > config file > action defaults.
+ */
+export const CI_DEFAULTS = {
+    agent: "claude-code",
+    phases: ["spec", "exec", "qa"],
+    timeout: 1800,
+    qualityLoop: false,
+    maxConcurrentRuns: 1,
+};
+/**
+ * Pattern for matching @sequant commands in issue comments.
+ */
+export const COMMENT_TRIGGER_PATTERN = /^@sequant\s+run\s+([\w,-]+)\s*$/m;

package/dist/src/lib/mcp-config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * MCP client detection and configuration
+ *
+ * Detects installed MCP clients (Claude Desktop, Cursor, VS Code)
+ * and generates appropriate configuration entries for Sequant MCP server.
+ */
+/** Path to the project-level MCP config file used by Claude Code */
+export declare const PROJECT_MCP_JSON = ".mcp.json";
+export type McpClientType = "claude-desktop" | "cursor" | "vscode-continue";
+export interface McpClientInfo {
+    name: string;
+    clientType: McpClientType;
+    configPath: string;
+    exists: boolean;
+}
+/**
+ * Sequant MCP server configuration entry.
+ *
+ * @param options.projectDir - Absolute project path (used as cwd for clients that need it)
+ * @param options.clientType - Target client; determines whether cwd/env are included
+ */
+export declare function getSequantMcpConfig(options?: {
+    projectDir?: string;
+    clientType?: McpClientType;
+}): Record<string, unknown>;
+/**
+ * Detect which MCP-compatible clients are installed
+ */
+export declare function detectMcpClients(): McpClientInfo[];
+/**
+ * Add Sequant MCP server to a client's config file.
+ * Returns true if written, false if already configured.
+ */
+export declare function addSequantToMcpConfig(configPath: string, clientType?: McpClientType): boolean;
+/**
+ * Check whether .mcp.json already has a sequant server entry.
+ */
+export declare function isSequantInProjectMcpJson(projectDir?: string): boolean;
+export interface ProjectMcpJsonResult {
+    created: boolean;
+    merged: boolean;
+    skipped: boolean;
+}
+/**
+ * Create or update .mcp.json in the project root for Claude Code.
+ *
+ * - If .mcp.json doesn't exist → create it with the sequant server entry
+ * - If .mcp.json exists with a sequant entry → skip (already configured)
+ * - If .mcp.json exists without a sequant entry → merge it in
+ *
+ * Unlike global client configs, .mcp.json does NOT include cwd or env
+ * because Claude Code runs from the project root.
+ */
+export declare function createProjectMcpJson(projectDir?: string): ProjectMcpJsonResult;