sequant 1.12.0 → 1.13.1

package/dist/src/lib/phase-spinner.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Phase Spinner - Animated spinner with elapsed time for phase execution
+ *
+ * Wraps the cli-ui spinner with:
+ * - Elapsed time tracking (updates every 5 seconds)
+ * - Phase progress indicator (e.g., "spec (1/3)")
+ * - Integration with ShutdownManager for graceful cleanup
+ *
+ * @example
+ * ```typescript
+ * const spinner = new PhaseSpinner({
+ *   phase: 'exec',
+ *   phaseIndex: 2,
+ *   totalPhases: 3,
+ *   shutdownManager,
+ * });
+ *
+ * spinner.start();
+ * // ... phase execution
+ * spinner.succeed(); // Shows "✓ exec (2/3) (45s)"
+ * ```
+ */
+import type { ShutdownManager } from "./shutdown.js";
+/**
+ * Options for creating a PhaseSpinner
+ */
+export interface PhaseSpinnerOptions {
+    /** Phase name (e.g., "spec", "exec", "qa") */
+    phase: string;
+    /** Current phase index (1-based) */
+    phaseIndex: number;
+    /** Total number of phases */
+    totalPhases: number;
+    /** Optional ShutdownManager for graceful cleanup */
+    shutdownManager?: ShutdownManager;
+    /** Optional prefix for indentation (default: "    ") */
+    prefix?: string;
+    /** Optional quality loop iteration (shows "iteration N" if > 1) */
+    iteration?: number;
+}
+/**
+ * Format elapsed time in human-readable format
+ *
+ * @param seconds - Elapsed time in seconds
+ * @returns Formatted string (e.g., "45s", "2m 15s", "1h 5m")
+ */
+export declare function formatElapsedTime(seconds: number): string;
+/**
+ * PhaseSpinner - Animated spinner with elapsed time and phase progress
+ *
+ * Features:
+ * - Animated spinner (or text fallback) via cli-ui
+ * - Elapsed time tracking with automatic updates
+ * - Phase progress indicator (e.g., "exec (2/3)")
+ * - ShutdownManager integration for graceful Ctrl+C cleanup
+ * - Pause/resume for verbose streaming output
+ */
+export declare class PhaseSpinner {
+    private spinner;
+    private startTime;
+    private intervalId;
+    private disposed;
+    private paused;
+    private readonly phase;
+    private readonly phaseIndex;
+    private readonly totalPhases;
+    private readonly shutdownManager?;
+    private readonly prefix;
+    private readonly iteration?;
+    private readonly cleanupName;
+    constructor(options: PhaseSpinnerOptions);
+    /**
+     * Format the spinner text with phase, progress, and elapsed time
+     */
+    private formatText;
+    /**
+     * Update the spinner text with current elapsed time
+     */
+    private updateElapsedTime;
+    /**
+     * Start the spinner
+     *
+     * Begins the animation and elapsed time tracking.
+     */
+    start(): PhaseSpinner;
+    /**
+     * Mark the phase as succeeded
+     *
+     * Stops the spinner and shows a checkmark with total duration.
+     */
+    succeed(customText?: string): PhaseSpinner;
+    /**
+     * Mark the phase as failed
+     *
+     * Stops the spinner and shows an error indicator with message.
+     */
+    fail(error?: string): PhaseSpinner;
+    /**
+     * Stop the spinner without success/fail indication
+     *
+     * Use this for cleanup or when the phase is interrupted.
+     */
+    stop(): PhaseSpinner;
+    /**
+     * Pause the spinner (for verbose streaming output)
+     *
+     * Temporarily stops the animation without disposing.
+     * Call resume() to continue.
+     */
+    pause(): PhaseSpinner;
+    /**
+     * Resume the spinner after pause
+     *
+     * Restarts the animation with updated elapsed time.
+     */
+    resume(): PhaseSpinner;
+    /**
+     * Check if the spinner is currently active
+     */
+    get isSpinning(): boolean;
+    /**
+     * Get the total elapsed time in seconds
+     */
+    get elapsedSeconds(): number;
+    /**
+     * Dispose of the spinner and clean up resources
+     *
+     * Called automatically by succeed(), fail(), or stop().
+     * Safe to call multiple times.
+     */
+    dispose(): void;
+    /**
+     * Clear the elapsed time update interval
+     */
+    private clearInterval;
+    /**
+     * Unregister from ShutdownManager
+     */
+    private unregisterCleanup;
+}
+/**
+ * Create a PhaseSpinner with the given options
+ *
+ * Convenience function matching the pattern of cli-ui.spinner().
+ */
+export declare function phaseSpinner(options: PhaseSpinnerOptions): PhaseSpinner;

package/dist/src/lib/phase-spinner.js

@@ -0,0 +1,255 @@
+/**
+ * Phase Spinner - Animated spinner with elapsed time for phase execution
+ *
+ * Wraps the cli-ui spinner with:
+ * - Elapsed time tracking (updates every 5 seconds)
+ * - Phase progress indicator (e.g., "spec (1/3)")
+ * - Integration with ShutdownManager for graceful cleanup
+ *
+ * @example
+ * ```typescript
+ * const spinner = new PhaseSpinner({
+ *   phase: 'exec',
+ *   phaseIndex: 2,
+ *   totalPhases: 3,
+ *   shutdownManager,
+ * });
+ *
+ * spinner.start();
+ * // ... phase execution
+ * spinner.succeed(); // Shows "✓ exec (2/3) (45s)"
+ * ```
+ */
+import { spinner as createSpinner } from "./cli-ui.js";
+/**
+ * Elapsed time update interval in milliseconds
+ */
+const ELAPSED_UPDATE_INTERVAL_MS = 5000;
+/**
+ * Format elapsed time in human-readable format
+ *
+ * @param seconds - Elapsed time in seconds
+ * @returns Formatted string (e.g., "45s", "2m 15s", "1h 5m")
+ */
+export function formatElapsedTime(seconds) {
+    if (seconds < 60) {
+        return `${Math.floor(seconds)}s`;
+    }
+    if (seconds < 3600) {
+        const minutes = Math.floor(seconds / 60);
+        const remainingSeconds = Math.floor(seconds % 60);
+        return remainingSeconds > 0
+            ? `${minutes}m ${remainingSeconds}s`
+            : `${minutes}m`;
+    }
+    const hours = Math.floor(seconds / 3600);
+    const remainingMinutes = Math.floor((seconds % 3600) / 60);
+    return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
+}
+/**
+ * PhaseSpinner - Animated spinner with elapsed time and phase progress
+ *
+ * Features:
+ * - Animated spinner (or text fallback) via cli-ui
+ * - Elapsed time tracking with automatic updates
+ * - Phase progress indicator (e.g., "exec (2/3)")
+ * - ShutdownManager integration for graceful Ctrl+C cleanup
+ * - Pause/resume for verbose streaming output
+ */
+export class PhaseSpinner {
+    spinner;
+    startTime = 0;
+    intervalId = null;
+    disposed = false;
+    paused = false;
+    phase;
+    phaseIndex;
+    totalPhases;
+    shutdownManager;
+    prefix;
+    iteration;
+    cleanupName;
+    constructor(options) {
+        this.phase = options.phase;
+        this.phaseIndex = options.phaseIndex;
+        this.totalPhases = options.totalPhases;
+        this.shutdownManager = options.shutdownManager;
+        this.prefix = options.prefix ?? "    ";
+        this.iteration = options.iteration;
+        this.cleanupName = `phase-spinner-${options.phase}`;
+        // Create the underlying spinner with initial text
+        this.spinner = createSpinner(this.formatText(0));
+    }
+    /**
+     * Format the spinner text with phase, progress, and elapsed time
+     */
+    formatText(elapsedSeconds) {
+        const progress = `(${this.phaseIndex}/${this.totalPhases})`;
+        const elapsed = elapsedSeconds > 0 ? ` ${formatElapsedTime(elapsedSeconds)}` : "";
+        const iterationSuffix = this.iteration && this.iteration > 1
+            ? ` [iteration ${this.iteration}]`
+            : "";
+        return `${this.prefix}${this.phase} ${progress}...${elapsed}${iterationSuffix}`;
+    }
+    /**
+     * Update the spinner text with current elapsed time
+     */
+    updateElapsedTime() {
+        if (this.disposed || this.paused)
+            return;
+        const elapsedSeconds = (Date.now() - this.startTime) / 1000;
+        this.spinner.text = this.formatText(elapsedSeconds);
+    }
+    /**
+     * Start the spinner
+     *
+     * Begins the animation and elapsed time tracking.
+     */
+    start() {
+        if (this.disposed)
+            return this;
+        this.startTime = Date.now();
+        this.spinner.start(this.formatText(0));
+        // Start elapsed time update interval
+        this.intervalId = setInterval(() => {
+            this.updateElapsedTime();
+        }, ELAPSED_UPDATE_INTERVAL_MS);
+        // Register with ShutdownManager for graceful cleanup
+        if (this.shutdownManager) {
+            this.shutdownManager.registerCleanup(this.cleanupName, async () => {
+                this.stop();
+            });
+        }
+        return this;
+    }
+    /**
+     * Mark the phase as succeeded
+     *
+     * Stops the spinner and shows a checkmark with total duration.
+     */
+    succeed(customText) {
+        if (this.disposed)
+            return this;
+        this.clearInterval();
+        this.unregisterCleanup();
+        const elapsedSeconds = (Date.now() - this.startTime) / 1000;
+        const duration = formatElapsedTime(elapsedSeconds);
+        const progress = `(${this.phaseIndex}/${this.totalPhases})`;
+        const text = customText ?? `${this.prefix}${this.phase} ${progress} (${duration})`;
+        this.spinner.succeed(text);
+        this.disposed = true;
+        return this;
+    }
+    /**
+     * Mark the phase as failed
+     *
+     * Stops the spinner and shows an error indicator with message.
+     */
+    fail(error) {
+        if (this.disposed)
+            return this;
+        this.clearInterval();
+        this.unregisterCleanup();
+        const elapsedSeconds = (Date.now() - this.startTime) / 1000;
+        const duration = formatElapsedTime(elapsedSeconds);
+        const progress = `(${this.phaseIndex}/${this.totalPhases})`;
+        const errorSuffix = error ? `: ${error}` : "";
+        const text = `${this.prefix}${this.phase} ${progress} (${duration})${errorSuffix}`;
+        this.spinner.fail(text);
+        this.disposed = true;
+        return this;
+    }
+    /**
+     * Stop the spinner without success/fail indication
+     *
+     * Use this for cleanup or when the phase is interrupted.
+     */
+    stop() {
+        if (this.disposed)
+            return this;
+        this.clearInterval();
+        this.unregisterCleanup();
+        this.spinner.stop();
+        this.disposed = true;
+        return this;
+    }
+    /**
+     * Pause the spinner (for verbose streaming output)
+     *
+     * Temporarily stops the animation without disposing.
+     * Call resume() to continue.
+     */
+    pause() {
+        if (this.disposed || this.paused)
+            return this;
+        this.paused = true;
+        this.spinner.stop();
+        return this;
+    }
+    /**
+     * Resume the spinner after pause
+     *
+     * Restarts the animation with updated elapsed time.
+     */
+    resume() {
+        if (this.disposed || !this.paused)
+            return this;
+        this.paused = false;
+        const elapsedSeconds = (Date.now() - this.startTime) / 1000;
+        this.spinner.start(this.formatText(elapsedSeconds));
+        return this;
+    }
+    /**
+     * Check if the spinner is currently active
+     */
+    get isSpinning() {
+        return this.spinner.isSpinning && !this.disposed && !this.paused;
+    }
+    /**
+     * Get the total elapsed time in seconds
+     */
+    get elapsedSeconds() {
+        if (this.startTime === 0)
+            return 0;
+        return (Date.now() - this.startTime) / 1000;
+    }
+    /**
+     * Dispose of the spinner and clean up resources
+     *
+     * Called automatically by succeed(), fail(), or stop().
+     * Safe to call multiple times.
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.clearInterval();
+        this.unregisterCleanup();
+        this.spinner.stop();
+        this.disposed = true;
+    }
+    /**
+     * Clear the elapsed time update interval
+     */
+    clearInterval() {
+        if (this.intervalId !== null) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+    }
+    /**
+     * Unregister from ShutdownManager
+     */
+    unregisterCleanup() {
+        if (this.shutdownManager) {
+            this.shutdownManager.unregisterCleanup(this.cleanupName);
+        }
+    }
+}
+/**
+ * Create a PhaseSpinner with the given options
+ *
+ * Convenience function matching the pattern of cli-ui.spinner().
+ */
+export function phaseSpinner(options) {
+    return new PhaseSpinner(options);
+}

package/dist/src/lib/solve-comment-parser.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Solve Comment Parser
+ *
+ * Detects and parses /solve command output from GitHub issue comments.
+ * When a solve comment exists, its phase recommendations take precedence
+ * over content analysis (but not over labels).
+ *
+ * @example
+ * ```typescript
+ * import { findSolveComment, parseSolveWorkflow } from './solve-comment-parser';
+ *
+ * const comments = [
+ *   { body: "Some regular comment" },
+ *   { body: "## Solve Workflow for Issues: 123\n..." },
+ * ];
+ *
+ * const solveComment = findSolveComment(comments);
+ * if (solveComment) {
+ *   const phases = parseSolveWorkflow(solveComment.body);
+ *   // phases: { phases: ['spec', 'exec', 'test', 'qa'], qualityLoop: false }
+ * }
+ * ```
+ */
+import type { Phase } from "./workflow/types.js";
+import type { PhaseSignal } from "./phase-signal.js";
+/**
+ * Result of parsing a solve comment
+ */
+export interface SolveWorkflowResult {
+    /** Phases recommended by solve */
+    phases: Phase[];
+    /** Whether quality loop is recommended */
+    qualityLoop: boolean;
+    /** The issue numbers mentioned in the solve comment */
+    issueNumbers: number[];
+    /** Raw workflow string (e.g., "spec → exec → test → qa") */
+    workflowString?: string;
+}
+/**
+ * Comment structure (simplified from GitHub API)
+ */
+export interface IssueComment {
+    body: string;
+    author?: {
+        login: string;
+    };
+    createdAt?: string;
+}
+/**
+ * Check if a comment is a solve command output
+ *
+ * @param body - The comment body
+ * @returns True if this appears to be a solve comment
+ */
+export declare function isSolveComment(body: string): boolean;
+/**
+ * Find the most recent solve comment from a list of comments
+ *
+ * @param comments - Array of issue comments
+ * @returns The solve comment if found, null otherwise
+ */
+export declare function findSolveComment(comments: IssueComment[]): IssueComment | null;
+/**
+ * Parse a solve comment to extract workflow information
+ *
+ * @param body - The solve comment body
+ * @returns Parsed workflow result
+ */
+export declare function parseSolveWorkflow(body: string): SolveWorkflowResult;
+/**
+ * Convert solve workflow result to phase signals
+ *
+ * @param workflow - The parsed solve workflow
+ * @returns Array of phase signals with 'solve' source
+ */
+export declare function solveWorkflowToSignals(workflow: SolveWorkflowResult): PhaseSignal[];
+/**
+ * Check if solve comment covers the current issue
+ *
+ * @param workflow - The parsed solve workflow
+ * @param issueNumber - The current issue number
+ * @returns True if the solve comment includes this issue
+ */
+export declare function solveCoversIssue(workflow: SolveWorkflowResult, issueNumber: number): boolean;

package/dist/src/lib/solve-comment-parser.js

@@ -0,0 +1,200 @@
+/**
+ * Solve Comment Parser
+ *
+ * Detects and parses /solve command output from GitHub issue comments.
+ * When a solve comment exists, its phase recommendations take precedence
+ * over content analysis (but not over labels).
+ *
+ * @example
+ * ```typescript
+ * import { findSolveComment, parseSolveWorkflow } from './solve-comment-parser';
+ *
+ * const comments = [
+ *   { body: "Some regular comment" },
+ *   { body: "## Solve Workflow for Issues: 123\n..." },
+ * ];
+ *
+ * const solveComment = findSolveComment(comments);
+ * if (solveComment) {
+ *   const phases = parseSolveWorkflow(solveComment.body);
+ *   // phases: { phases: ['spec', 'exec', 'test', 'qa'], qualityLoop: false }
+ * }
+ * ```
+ */
+/**
+ * Markers that indicate a solve comment
+ */
+const SOLVE_MARKERS = [
+    "## Solve Workflow for Issues:",
+    "## Solve Workflow for Issue:",
+    "### Recommended Workflow",
+    "*📝 Generated by `/solve",
+];
+/**
+ * Pattern to extract phases from solve workflow
+ * Matches: `/spec`, `/exec`, `/test`, `/qa`, etc.
+ * Also matches without slash: `spec`, `exec`, `test`, `qa` (for arrow notation)
+ */
+const PHASE_PATTERN = /\/?(?<!\w)(spec|exec|test|qa|security-review|testgen|loop)(?!\w)/g;
+/**
+ * Pattern to detect quality loop recommendation
+ */
+const QUALITY_LOOP_PATTERNS = [
+    /quality\s*loop.*auto-enable/i,
+    /--quality-loop/i,
+    /quality\s*loop.*recommended/i,
+    /enable.*quality\s*loop/i,
+];
+/**
+ * Pattern to extract issue numbers from solve header
+ * Matches: "## Solve Workflow for Issues: 123, 456"
+ */
+const ISSUE_NUMBER_PATTERN = /#?(\d+)/g;
+/**
+ * Check if a comment is a solve command output
+ *
+ * @param body - The comment body
+ * @returns True if this appears to be a solve comment
+ */
+export function isSolveComment(body) {
+    return SOLVE_MARKERS.some((marker) => body.includes(marker));
+}
+/**
+ * Find the most recent solve comment from a list of comments
+ *
+ * @param comments - Array of issue comments
+ * @returns The solve comment if found, null otherwise
+ */
+export function findSolveComment(comments) {
+    // Search from most recent to oldest (assuming comments are in chronological order)
+    for (let i = comments.length - 1; i >= 0; i--) {
+        if (isSolveComment(comments[i].body)) {
+            return comments[i];
+        }
+    }
+    return null;
+}
+/**
+ * Parse phases from a solve workflow string
+ *
+ * @param workflowString - String like "spec → exec → test → qa"
+ * @returns Array of phases
+ */
+function parseWorkflowString(workflowString) {
+    const phases = [];
+    const matches = workflowString.matchAll(PHASE_PATTERN);
+    for (const match of matches) {
+        const phase = match[1];
+        if (!phases.includes(phase)) {
+            phases.push(phase);
+        }
+    }
+    return phases;
+}
+/**
+ * Parse a solve comment to extract workflow information
+ *
+ * @param body - The solve comment body
+ * @returns Parsed workflow result
+ */
+export function parseSolveWorkflow(body) {
+    const result = {
+        phases: [],
+        qualityLoop: false,
+        issueNumbers: [],
+    };
+    // Extract issue numbers from header
+    const headerMatch = body.match(/## Solve Workflow for Issues?:\s*([^\n]+)/i);
+    if (headerMatch) {
+        const numberMatches = headerMatch[1].matchAll(ISSUE_NUMBER_PATTERN);
+        for (const match of numberMatches) {
+            const num = parseInt(match[1], 10);
+            if (!isNaN(num) && !result.issueNumbers.includes(num)) {
+                result.issueNumbers.push(num);
+            }
+        }
+    }
+    // Find workflow lines (e.g., "/spec 152" or "spec → exec → qa")
+    const lines = body.split("\n");
+    // First pass: look for arrow notation (most reliable)
+    for (const line of lines) {
+        if (line.includes("→") || line.includes("->")) {
+            const phases = parseWorkflowString(line);
+            if (phases.length > 0) {
+                result.phases = phases;
+                result.workflowString = line.trim();
+                break;
+            }
+        }
+    }
+    // Second pass: if no arrow notation found, collect phases from multiple lines
+    if (result.phases.length === 0) {
+        const collectedPhases = [];
+        for (const line of lines) {
+            // Look for slash command patterns on individual lines
+            if (line.includes("/spec") ||
+                line.includes("/exec") ||
+                line.includes("/test") ||
+                line.includes("/qa")) {
+                const linePhases = parseWorkflowString(line);
+                for (const phase of linePhases) {
+                    if (!collectedPhases.includes(phase)) {
+                        collectedPhases.push(phase);
+                    }
+                }
+            }
+        }
+        if (collectedPhases.length > 0) {
+            result.phases = collectedPhases;
+            result.workflowString = collectedPhases.map((p) => `/${p}`).join(" → ");
+        }
+    }
+    // If no phases found from lines, try full body
+    if (result.phases.length === 0) {
+        result.phases = parseWorkflowString(body);
+    }
+    // Check for quality loop recommendation
+    for (const pattern of QUALITY_LOOP_PATTERNS) {
+        if (pattern.test(body)) {
+            result.qualityLoop = true;
+            break;
+        }
+    }
+    return result;
+}
+/**
+ * Convert solve workflow result to phase signals
+ *
+ * @param workflow - The parsed solve workflow
+ * @returns Array of phase signals with 'solve' source
+ */
+export function solveWorkflowToSignals(workflow) {
+    const signals = [];
+    for (const phase of workflow.phases) {
+        signals.push({
+            phase,
+            source: "solve",
+            confidence: "high",
+            reason: `Recommended by /solve command: ${workflow.workflowString || phase}`,
+        });
+    }
+    if (workflow.qualityLoop) {
+        signals.push({
+            phase: "quality-loop",
+            source: "solve",
+            confidence: "high",
+            reason: "Quality loop recommended by /solve command",
+        });
+    }
+    return signals;
+}
+/**
+ * Check if solve comment covers the current issue
+ *
+ * @param workflow - The parsed solve workflow
+ * @param issueNumber - The current issue number
+ * @returns True if the solve comment includes this issue
+ */
+export function solveCoversIssue(workflow, issueNumber) {
+    return workflow.issueNumbers.includes(issueNumber);
+}