sequant 1.16.1 → 1.18.0

package/dist/src/lib/workflow/state-cleanup.js

@@ -0,0 +1,250 @@
+/**
+ * State cleanup and reconciliation utilities
+ *
+ * @module state-cleanup
+ * @example
+ * ```typescript
+ * import { cleanupStaleEntries, reconcileStateAtStartup } from './state-cleanup';
+ *
+ * // Clean up orphaned entries
+ * const result = await cleanupStaleEntries({ dryRun: true });
+ * console.log(`Would remove ${result.removed.length} entries`);
+ *
+ * // Reconcile state at startup
+ * const reconcileResult = await reconcileStateAtStartup();
+ * console.log(`Advanced ${reconcileResult.advanced.length} issues to merged`);
+ * ```
+ */
+import { spawnSync } from "child_process";
+import { StateManager } from "./state-manager.js";
+import { checkPRMergeStatus, isIssueMergedIntoMain } from "./pr-status.js";
+/**
+ * Get list of active worktree paths
+ */
+function getActiveWorktrees() {
+    const result = spawnSync("git", ["worktree", "list", "--porcelain"], {
+        stdio: "pipe",
+    });
+    if (result.status !== 0) {
+        return [];
+    }
+    const output = result.stdout.toString();
+    const paths = [];
+    for (const line of output.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            paths.push(line.substring(9));
+        }
+    }
+    return paths;
+}
+/**
+ * Clean up stale and orphaned entries from workflow state
+ *
+ * - Checks GitHub to detect if associated PR was merged
+ * - Orphaned entries with merged PRs get status "merged" and are removed automatically
+ * - Orphaned entries without merged PRs get status "abandoned" (kept for review)
+ * - Use removeAll to remove both merged and abandoned orphaned entries in one step
+ * - Use maxAgeDays to remove old merged/abandoned issues
+ */
+export async function cleanupStaleEntries(options = {}) {
+    const manager = new StateManager({
+        statePath: options.statePath,
+        verbose: options.verbose,
+    });
+    if (!manager.stateExists()) {
+        return {
+            success: true,
+            removed: [],
+            orphaned: [],
+            merged: [],
+        };
+    }
+    try {
+        const state = await manager.getState();
+        const removed = [];
+        const orphaned = [];
+        const merged = [];
+        // Get list of active worktrees
+        const activeWorktrees = getActiveWorktrees();
+        for (const [issueNumStr, issueState] of Object.entries(state.issues)) {
+            const issueNum = parseInt(issueNumStr, 10);
+            // Check if worktree exists (if issue has one)
+            if (issueState.worktree &&
+                !activeWorktrees.includes(issueState.worktree)) {
+                if (options.verbose) {
+                    console.log(`🔍 Orphaned: #${issueNum} (worktree not found: ${issueState.worktree})`);
+                }
+                // Check if this issue has a PR and if it's merged
+                let prMerged = false;
+                if (issueState.pr?.number) {
+                    if (options.verbose) {
+                        console.log(`   Checking PR #${issueState.pr.number} status...`);
+                    }
+                    const prStatus = checkPRMergeStatus(issueState.pr.number);
+                    prMerged = prStatus === "MERGED";
+                    if (options.verbose) {
+                        console.log(`   PR status: ${prStatus ?? "unknown"}`);
+                    }
+                }
+                if (!options.dryRun) {
+                    if (prMerged || issueState.status === "merged") {
+                        // Merged PRs are auto-removed
+                        merged.push(issueNum);
+                        removed.push(issueNum);
+                        if (options.verbose) {
+                            console.log(`   ✓ Merged PR detected, removing entry`);
+                        }
+                        delete state.issues[issueNumStr];
+                    }
+                    else if (issueState.status === "abandoned" || options.removeAll) {
+                        // Already abandoned or removeAll flag - remove it
+                        orphaned.push(issueNum);
+                        removed.push(issueNum);
+                        if (options.verbose) {
+                            console.log(`   ✓ Removing abandoned entry`);
+                        }
+                        delete state.issues[issueNumStr];
+                    }
+                    else {
+                        // Mark as abandoned (kept for review)
+                        orphaned.push(issueNum);
+                        issueState.status = "abandoned";
+                        if (options.verbose) {
+                            console.log(`   → Marked as abandoned (kept for review)`);
+                        }
+                    }
+                }
+                else {
+                    // Dry run - report what would happen
+                    if (prMerged || issueState.status === "merged") {
+                        merged.push(issueNum);
+                        removed.push(issueNum);
+                    }
+                    else if (issueState.status === "abandoned" || options.removeAll) {
+                        orphaned.push(issueNum);
+                        removed.push(issueNum);
+                    }
+                    else {
+                        orphaned.push(issueNum);
+                    }
+                }
+                continue;
+            }
+            // Check age for merged/abandoned issues
+            if (options.maxAgeDays &&
+                (issueState.status === "merged" || issueState.status === "abandoned")) {
+                const lastActivity = new Date(issueState.lastActivity);
+                const ageDays = (Date.now() - lastActivity.getTime()) / (1000 * 60 * 60 * 24);
+                if (ageDays > options.maxAgeDays) {
+                    removed.push(issueNum);
+                    if (options.verbose) {
+                        console.log(`🗑️  Stale: #${issueNum} (${Math.floor(ageDays)} days old)`);
+                    }
+                    if (!options.dryRun) {
+                        delete state.issues[issueNumStr];
+                    }
+                }
+            }
+        }
+        // Save updated state
+        if (!options.dryRun && (removed.length > 0 || orphaned.length > 0)) {
+            await manager.saveState(state);
+        }
+        return {
+            success: true,
+            removed,
+            orphaned,
+            merged,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            removed: [],
+            orphaned: [],
+            merged: [],
+            error: String(error),
+        };
+    }
+}
+/**
+ * Lightweight state reconciliation at run start
+ *
+ * Checks issues in `ready_for_merge` state and advances them to `merged`
+ * if their PRs are merged or their branches are in main.
+ *
+ * This prevents re-running already completed issues.
+ *
+ * @param options - Reconciliation options
+ * @returns Result with lists of advanced and still-pending issues
+ */
+export async function reconcileStateAtStartup(options = {}) {
+    const manager = new StateManager({
+        statePath: options.statePath,
+        verbose: options.verbose,
+    });
+    // Graceful degradation: if state file doesn't exist, skip
+    if (!manager.stateExists()) {
+        return {
+            success: true,
+            advanced: [],
+            stillPending: [],
+        };
+    }
+    try {
+        const state = await manager.getState();
+        const advanced = [];
+        const stillPending = [];
+        // Find issues in ready_for_merge state
+        for (const [issueNumStr, issueState] of Object.entries(state.issues)) {
+            if (issueState.status !== "ready_for_merge") {
+                continue;
+            }
+            const issueNum = parseInt(issueNumStr, 10);
+            let isMerged = false;
+            // Check 1: If we have PR info, check PR status via gh
+            if (issueState.pr?.number) {
+                const prStatus = checkPRMergeStatus(issueState.pr.number);
+                if (prStatus === "MERGED") {
+                    isMerged = true;
+                    if (options.verbose) {
+                        console.log(`  #${issueNum}: PR #${issueState.pr.number} is merged`);
+                    }
+                }
+            }
+            // Check 2: If no PR or PR check failed, check git for merged branch
+            if (!isMerged) {
+                isMerged = isIssueMergedIntoMain(issueNum);
+                if (isMerged && options.verbose) {
+                    console.log(`  #${issueNum}: Branch merged into main (git check)`);
+                }
+            }
+            if (isMerged) {
+                // Advance state to merged
+                issueState.status = "merged";
+                issueState.lastActivity = new Date().toISOString();
+                advanced.push(issueNum);
+            }
+            else {
+                stillPending.push(issueNum);
+            }
+        }
+        // Save state if any issues were advanced
+        if (advanced.length > 0) {
+            await manager.saveState(state);
+        }
+        return {
+            success: true,
+            advanced,
+            stillPending,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            advanced: [],
+            stillPending: [],
+            error: String(error),
+        };
+    }
+}

package/dist/src/lib/workflow/state-rebuild.d.ts

@@ -0,0 +1,38 @@
+/**
+ * State reconstruction from run logs
+ *
+ * @module state-rebuild
+ * @example
+ * ```typescript
+ * import { rebuildStateFromLogs } from './state-rebuild';
+ *
+ * // Rebuild state from run logs
+ * const result = await rebuildStateFromLogs();
+ * console.log(`Processed ${result.logsProcessed} logs, found ${result.issuesFound} issues`);
+ * ```
+ */
+export interface RebuildOptions {
+    /** Log directory path (default: .sequant/logs) */
+    logPath?: string;
+    /** State file path (default: .sequant/state.json) */
+    statePath?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+export interface RebuildResult {
+    /** Whether rebuild was successful */
+    success: boolean;
+    /** Number of log files processed */
+    logsProcessed: number;
+    /** Number of issues found */
+    issuesFound: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Rebuild workflow state from run logs
+ *
+ * Scans all run logs in .sequant/logs/ and reconstructs state
+ * based on the most recent activity for each issue.
+ */
+export declare function rebuildStateFromLogs(options?: RebuildOptions): Promise<RebuildResult>;

package/dist/src/lib/workflow/state-rebuild.js

@@ -0,0 +1,140 @@
+/**
+ * State reconstruction from run logs
+ *
+ * @module state-rebuild
+ * @example
+ * ```typescript
+ * import { rebuildStateFromLogs } from './state-rebuild';
+ *
+ * // Rebuild state from run logs
+ * const result = await rebuildStateFromLogs();
+ * console.log(`Processed ${result.logsProcessed} logs, found ${result.issuesFound} issues`);
+ * ```
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { StateManager } from "./state-manager.js";
+import { createEmptyState, createIssueState, createPhaseState, } from "./state-schema.js";
+import { RunLogSchema, LOG_PATHS } from "./run-log-schema.js";
+/**
+ * Rebuild workflow state from run logs
+ *
+ * Scans all run logs in .sequant/logs/ and reconstructs state
+ * based on the most recent activity for each issue.
+ */
+export async function rebuildStateFromLogs(options = {}) {
+    const logPath = options.logPath ?? LOG_PATHS.project;
+    if (!fs.existsSync(logPath)) {
+        return {
+            success: false,
+            logsProcessed: 0,
+            issuesFound: 0,
+            error: `Log directory not found: ${logPath}`,
+        };
+    }
+    try {
+        // Find all log files
+        const files = fs.readdirSync(logPath).filter((f) => f.endsWith(".json"));
+        if (files.length === 0) {
+            return {
+                success: true,
+                logsProcessed: 0,
+                issuesFound: 0,
+            };
+        }
+        // Sort by timestamp (newest first)
+        files.sort().reverse();
+        // Build state from logs
+        const state = createEmptyState();
+        const issueMap = new Map();
+        for (const file of files) {
+            const filePath = path.join(logPath, file);
+            try {
+                const content = fs.readFileSync(filePath, "utf-8");
+                const logData = JSON.parse(content);
+                const log = RunLogSchema.safeParse(logData);
+                if (!log.success) {
+                    if (options.verbose) {
+                        console.log(`⚠️  Invalid log format: ${file}`);
+                    }
+                    continue;
+                }
+                const runLog = log.data;
+                // Process each issue in the log
+                for (const issueLog of runLog.issues) {
+                    // Skip if we already have newer data for this issue
+                    if (issueMap.has(issueLog.issueNumber)) {
+                        continue;
+                    }
+                    // Create issue state from log
+                    const issueState = createIssueState(issueLog.issueNumber, issueLog.title);
+                    // Determine status from log
+                    if (issueLog.status === "success") {
+                        issueState.status = "ready_for_merge";
+                    }
+                    else if (issueLog.status === "failure") {
+                        issueState.status = "in_progress";
+                    }
+                    else {
+                        issueState.status = "in_progress";
+                    }
+                    // Add phase states from log
+                    for (const phaseLog of issueLog.phases) {
+                        const phaseState = createPhaseState(phaseLog.status === "success"
+                            ? "completed"
+                            : phaseLog.status === "failure"
+                                ? "failed"
+                                : phaseLog.status === "skipped"
+                                    ? "skipped"
+                                    : "completed");
+                        phaseState.startedAt = phaseLog.startTime;
+                        phaseState.completedAt = phaseLog.endTime;
+                        if (phaseLog.error) {
+                            phaseState.error = phaseLog.error;
+                        }
+                        issueState.phases[phaseLog.phase] = phaseState;
+                        // Update current phase to last executed
+                        issueState.currentPhase = phaseLog.phase;
+                    }
+                    // Set last activity from most recent phase
+                    const lastPhase = issueLog.phases[issueLog.phases.length - 1];
+                    if (lastPhase) {
+                        issueState.lastActivity = lastPhase.endTime;
+                    }
+                    issueMap.set(issueLog.issueNumber, issueState);
+                }
+                if (options.verbose) {
+                    console.log(`✓ Processed: ${file}`);
+                }
+            }
+            catch (err) {
+                if (options.verbose) {
+                    console.log(`⚠️  Error reading ${file}: ${err}`);
+                }
+            }
+        }
+        // Copy issues to state
+        for (const [num, issueState] of issueMap) {
+            state.issues[String(num)] = issueState;
+        }
+        // Save rebuilt state
+        const manager = new StateManager({
+            statePath: options.statePath,
+            verbose: options.verbose,
+        });
+        await manager.saveState(state);
+        return {
+            success: true,
+            logsProcessed: files.length,
+            issuesFound: issueMap.size,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            logsProcessed: 0,
+            issuesFound: 0,
+            error: String(error),
+        };
+    }
+}

package/dist/src/lib/workflow/state-utils.d.ts

@@ -1,6 +1,12 @@
 /**
  * State utilities for rebuilding and cleaning up workflow state
  *
+ * This module re-exports focused utilities from dedicated modules:
+ * - pr-status: PR merge detection and branch status
+ * - state-rebuild: State reconstruction from run logs
+ * - worktree-discovery: Worktree discovery for state bootstrapping
+ * - state-cleanup: Cleanup of stale entries and startup reconciliation
+ *
  * @example
  * ```typescript
  * import { rebuildStateFromLogs, cleanupStaleEntries } from './state-utils';
@@ -12,165 +18,11 @@
  * const result = await cleanupStaleEntries({ dryRun: true });
  * ```
  */
-import { type Phase } from "./state-schema.js";
-/**
- * PR merge status from GitHub
- */
-export type PRMergeStatus = "MERGED" | "CLOSED" | "OPEN" | null;
-/**
- * Check the merge status of a PR using the gh CLI
- *
- * @param prNumber - The PR number to check
- * @returns "MERGED" | "CLOSED" | "OPEN" | null (null if PR not found or gh unavailable)
- */
-export declare function checkPRMergeStatus(prNumber: number): PRMergeStatus;
-export interface RebuildOptions {
-    /** Log directory path (default: .sequant/logs) */
-    logPath?: string;
-    /** State file path (default: .sequant/state.json) */
-    statePath?: string;
-    /** Enable verbose logging */
-    verbose?: boolean;
-}
-export interface RebuildResult {
-    /** Whether rebuild was successful */
-    success: boolean;
-    /** Number of log files processed */
-    logsProcessed: number;
-    /** Number of issues found */
-    issuesFound: number;
-    /** Error message if failed */
-    error?: string;
-}
-/**
- * Rebuild workflow state from run logs
- *
- * Scans all run logs in .sequant/logs/ and reconstructs state
- * based on the most recent activity for each issue.
- */
-export declare function rebuildStateFromLogs(options?: RebuildOptions): Promise<RebuildResult>;
-export interface CleanupOptions {
-    /** State file path (default: .sequant/state.json) */
-    statePath?: string;
-    /** Only report what would be cleaned (don't modify) */
-    dryRun?: boolean;
-    /** Enable verbose logging */
-    verbose?: boolean;
-    /** Remove issues older than this many days */
-    maxAgeDays?: number;
-    /** Remove all orphaned entries (both merged and abandoned) in one step */
-    removeAll?: boolean;
-}
-export interface CleanupResult {
-    /** Whether cleanup was successful */
-    success: boolean;
-    /** Issues that were removed or would be removed */
-    removed: number[];
-    /** Issues that were marked as orphaned (abandoned) */
-    orphaned: number[];
-    /** Issues detected as merged PRs */
-    merged: number[];
-    /** Error message if failed */
-    error?: string;
-}
-/**
- * Clean up stale and orphaned entries from workflow state
- *
- * - Checks GitHub to detect if associated PR was merged
- * - Orphaned entries with merged PRs get status "merged" and are removed automatically
- * - Orphaned entries without merged PRs get status "abandoned" (kept for review)
- * - Use removeAll to remove both merged and abandoned orphaned entries in one step
- * - Use maxAgeDays to remove old merged/abandoned issues
- */
-export declare function cleanupStaleEntries(options?: CleanupOptions): Promise<CleanupResult>;
-export interface DiscoverOptions {
-    /** State file path (default: .sequant/state.json) */
-    statePath?: string;
-    /** Enable verbose logging */
-    verbose?: boolean;
-}
-export interface DiscoveredWorktree {
-    /** Issue number extracted from branch name */
-    issueNumber: number;
-    /** Issue title (fetched from GitHub or placeholder) */
-    title: string;
-    /** Full path to the worktree */
-    worktreePath: string;
-    /** Branch name */
-    branch: string;
-    /** Inferred current phase from logs (if available) */
-    inferredPhase?: Phase;
-}
-export interface SkippedWorktree {
-    /** Path to the worktree */
-    path: string;
-    /** Reason it was skipped */
-    reason: string;
-}
-export interface DiscoverResult {
-    /** Whether discovery was successful */
-    success: boolean;
-    /** Number of worktrees scanned */
-    worktreesScanned: number;
-    /** Number of worktrees already tracked */
-    alreadyTracked: number;
-    /** Discovered worktrees not yet in state */
-    discovered: DiscoveredWorktree[];
-    /** Worktrees that were skipped (not matching pattern, etc.) */
-    skipped: SkippedWorktree[];
-    /** Error message if failed */
-    error?: string;
-}
-/**
- * Discover worktrees that are not yet tracked in state
- *
- * Scans all git worktrees, identifies those with issue-related branch names,
- * and returns information about worktrees not yet in the state file.
- */
-export declare function discoverUntrackedWorktrees(options?: DiscoverOptions): Promise<DiscoverResult>;
-export interface ReconcileOptions {
-    /** State file path (default: .sequant/state.json) */
-    statePath?: string;
-    /** Enable verbose logging */
-    verbose?: boolean;
-}
-export interface ReconcileResult {
-    /** Whether reconciliation was successful */
-    success: boolean;
-    /** Issues that were advanced from ready_for_merge to merged */
-    advanced: number[];
-    /** Issues checked but still ready_for_merge */
-    stillPending: number[];
-    /** Error message if failed */
-    error?: string;
-}
-/**
- * Check if a branch has been merged into main using git
- *
- * @param branchName - The branch name to check (e.g., "feature/33-some-title")
- * @returns true if the branch is merged into main, false otherwise
- */
-export declare function isBranchMergedIntoMain(branchName: string): boolean;
-/**
- * Check if a feature branch for an issue is merged into main
- *
- * Tries multiple detection methods:
- * 1. Check if branch exists and is merged via `git branch --merged main`
- * 2. Check for merge commits mentioning the issue
- *
- * @param issueNumber - The issue number to check
- * @returns true if the issue's work is merged into main
- */
-export declare function isIssueMergedIntoMain(issueNumber: number): boolean;
-/**
- * Lightweight state reconciliation at run start
- *
- * Checks issues in `ready_for_merge` state and advances them to `merged`
- * if their PRs are merged or their branches are in main.
- *
- * This prevents re-running already completed issues.
- *
- * @param options - Reconciliation options
- * @returns Result with lists of advanced and still-pending issues
- */
-export declare function reconcileStateAtStartup(options?: ReconcileOptions): Promise<ReconcileResult>;
+export type { PRMergeStatus } from "./pr-status.js";
+export { checkPRMergeStatus, isBranchMergedIntoMain, isIssueMergedIntoMain, } from "./pr-status.js";
+export type { RebuildOptions, RebuildResult } from "./state-rebuild.js";
+export { rebuildStateFromLogs } from "./state-rebuild.js";
+export type { DiscoverOptions, DiscoveredWorktree, SkippedWorktree, DiscoverResult, } from "./worktree-discovery.js";
+export { discoverUntrackedWorktrees } from "./worktree-discovery.js";
+export type { CleanupOptions, CleanupResult, ReconcileOptions, ReconcileResult, } from "./state-cleanup.js";
+export { cleanupStaleEntries, reconcileStateAtStartup, } from "./state-cleanup.js";