sequant 1.10.1 → 1.11.0

package/dist/src/commands/state.js

@@ -0,0 +1,267 @@
+/**
+ * sequant state - Manage workflow state for existing worktrees
+ *
+ * Provides commands to bootstrap, rebuild, and clean up workflow state:
+ * - init: Populate state for untracked worktrees
+ * - rebuild: Recreate entire state from git worktrees + logs
+ * - clean: Remove entries for worktrees that no longer exist
+ */
+import chalk from "chalk";
+import { StateManager } from "../lib/workflow/state-manager.js";
+import { rebuildStateFromLogs, cleanupStaleEntries, discoverUntrackedWorktrees, } from "../lib/workflow/state-utils.js";
+import { createIssueState } from "../lib/workflow/state-schema.js";
+/**
+ * Initialize state for untracked worktrees
+ *
+ * Scans for worktrees with issue-* or feature/* patterns,
+ * extracts issue numbers, fetches titles from GitHub,
+ * and populates state file with reasonable defaults.
+ */
+export async function stateInitCommand(options = {}) {
+    if (!options.json) {
+        console.log(chalk.bold("\n🔍 Discovering untracked worktrees...\n"));
+    }
+    const discoverOptions = {
+        verbose: options.verbose && !options.json,
+    };
+    const result = await discoverUntrackedWorktrees(discoverOptions);
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (!result.success) {
+        console.log(chalk.red(`✗ Discovery failed: ${result.error}`));
+        return;
+    }
+    if (result.discovered.length === 0) {
+        console.log(chalk.green("✓ All worktrees are already tracked"));
+        console.log(chalk.gray(`  Worktrees scanned: ${result.worktreesScanned}`));
+        return;
+    }
+    // Initialize state for discovered worktrees
+    const stateManager = new StateManager({ verbose: options.verbose });
+    for (const worktree of result.discovered) {
+        try {
+            // Create issue state with worktree info
+            const issueState = createIssueState(worktree.issueNumber, worktree.title, {
+                worktree: worktree.worktreePath,
+                branch: worktree.branch,
+            });
+            // Set status based on inferred phase
+            if (worktree.inferredPhase) {
+                issueState.currentPhase = worktree.inferredPhase;
+                issueState.status = "in_progress";
+            }
+            // Save to state
+            const state = await stateManager.getState();
+            state.issues[String(worktree.issueNumber)] = issueState;
+            await stateManager.saveState(state);
+            console.log(chalk.green(`✓ Added #${worktree.issueNumber}: ${worktree.title}`));
+            console.log(chalk.gray(`  Branch: ${worktree.branch}`));
+            if (worktree.inferredPhase) {
+                console.log(chalk.gray(`  Inferred phase: ${worktree.inferredPhase}`));
+            }
+            console.log("");
+        }
+        catch (error) {
+            console.log(chalk.yellow(`⚠ Failed to add #${worktree.issueNumber}: ${error}`));
+        }
+    }
+    console.log(chalk.bold("\nSummary:"));
+    console.log(chalk.gray(`  Worktrees scanned: ${result.worktreesScanned}`));
+    console.log(chalk.gray(`  Already tracked: ${result.alreadyTracked}`));
+    console.log(chalk.green(`  Newly added: ${result.discovered.length}`));
+    if (result.skipped.length > 0) {
+        console.log(chalk.yellow(`  Skipped: ${result.skipped.length}`));
+        for (const skip of result.skipped) {
+            console.log(chalk.gray(`    - ${skip.path}: ${skip.reason}`));
+        }
+    }
+}
+/**
+ * Rebuild entire state from scratch
+ *
+ * Combines worktree discovery with log-based state reconstruction.
+ * Creates backup of existing state before rebuilding.
+ */
+export async function stateRebuildCommand(options = {}) {
+    if (!options.json) {
+        console.log(chalk.bold("\n🔄 Rebuilding state from scratch...\n"));
+        if (!options.force) {
+            console.log(chalk.yellow("⚠ This will replace the existing state file. Use --force to proceed.\n"));
+            return;
+        }
+    }
+    // Step 1: Rebuild from logs
+    if (!options.json) {
+        console.log(chalk.gray("Step 1: Rebuilding from run logs..."));
+    }
+    const logResult = await rebuildStateFromLogs({
+        verbose: options.verbose && !options.json,
+    });
+    if (!logResult.success) {
+        if (options.json) {
+            console.log(JSON.stringify({ success: false, error: logResult.error }, null, 2));
+        }
+        else {
+            console.log(chalk.red(`✗ Log rebuild failed: ${logResult.error}`));
+        }
+        return;
+    }
+    // Step 2: Discover and add untracked worktrees
+    if (!options.json) {
+        console.log(chalk.gray("Step 2: Discovering untracked worktrees..."));
+    }
+    const discoverResult = await discoverUntrackedWorktrees({
+        verbose: options.verbose && !options.json,
+    });
+    if (!discoverResult.success) {
+        if (options.json) {
+            console.log(JSON.stringify({ success: false, error: discoverResult.error }, null, 2));
+        }
+        else {
+            console.log(chalk.yellow(`⚠ Worktree discovery failed: ${discoverResult.error}`));
+            console.log(chalk.gray("  State rebuilt from logs only."));
+        }
+    }
+    else {
+        // Add discovered worktrees to state
+        const stateManager = new StateManager({ verbose: options.verbose });
+        for (const worktree of discoverResult.discovered) {
+            try {
+                const issueState = createIssueState(worktree.issueNumber, worktree.title, {
+                    worktree: worktree.worktreePath,
+                    branch: worktree.branch,
+                });
+                if (worktree.inferredPhase) {
+                    issueState.currentPhase = worktree.inferredPhase;
+                    issueState.status = "in_progress";
+                }
+                const state = await stateManager.getState();
+                // Only add if not already present from logs
+                if (!state.issues[String(worktree.issueNumber)]) {
+                    state.issues[String(worktree.issueNumber)] = issueState;
+                    await stateManager.saveState(state);
+                }
+                else {
+                    // Update worktree info if missing
+                    const existing = state.issues[String(worktree.issueNumber)];
+                    if (!existing.worktree) {
+                        existing.worktree = worktree.worktreePath;
+                        existing.branch = worktree.branch;
+                        await stateManager.saveState(state);
+                    }
+                }
+            }
+            catch {
+                // Continue with other worktrees
+            }
+        }
+    }
+    // Output results
+    if (options.json) {
+        console.log(JSON.stringify({
+            success: true,
+            logsProcessed: logResult.logsProcessed,
+            issuesFromLogs: logResult.issuesFound,
+            worktreesScanned: discoverResult.worktreesScanned,
+            worktreesAdded: discoverResult.discovered.length,
+        }, null, 2));
+        return;
+    }
+    console.log(chalk.green("\n✓ State rebuilt successfully"));
+    console.log(chalk.gray(`  Logs processed: ${logResult.logsProcessed}`));
+    console.log(chalk.gray(`  Issues from logs: ${logResult.issuesFound}`));
+    console.log(chalk.gray(`  Worktrees scanned: ${discoverResult.worktreesScanned}`));
+    console.log(chalk.gray(`  Worktrees added: ${discoverResult.discovered.length}`));
+    console.log(chalk.gray("\nRun `sequant status --issues` to see the rebuilt state."));
+}
+/**
+ * Clean up orphaned state entries
+ *
+ * Removes entries for worktrees that no longer exist.
+ * Detects merged PRs and auto-removes them.
+ */
+export async function stateCleanCommand(options = {}) {
+    const dryRun = options.dryRun ?? false;
+    const removeAll = options.all ?? false;
+    if (!options.json) {
+        if (dryRun) {
+            console.log(chalk.bold("\n🧹 Cleanup preview (dry run)...\n"));
+        }
+        else if (removeAll) {
+            console.log(chalk.bold("\n🧹 Cleaning up all orphaned entries...\n"));
+        }
+        else {
+            console.log(chalk.bold("\n🧹 Cleaning up orphaned entries...\n"));
+        }
+    }
+    const result = await cleanupStaleEntries({
+        dryRun,
+        maxAgeDays: options.maxAge,
+        removeAll,
+        verbose: options.verbose && !options.json,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (!result.success) {
+        console.log(chalk.red(`✗ Cleanup failed: ${result.error}`));
+        return;
+    }
+    const orphanedCount = result.orphaned.length;
+    const removedCount = result.removed.length;
+    const mergedCount = result.merged.length;
+    if (orphanedCount === 0 && removedCount === 0 && mergedCount === 0) {
+        console.log(chalk.green("✓ No orphaned entries found"));
+        return;
+    }
+    if (dryRun) {
+        console.log(chalk.yellow("Preview (no changes made):"));
+    }
+    else {
+        console.log(chalk.green("✓ Cleanup completed"));
+    }
+    if (mergedCount > 0) {
+        console.log(chalk.green(`  Merged PRs (auto-removed): ${result.merged.map((n) => `#${n}`).join(", ")}`));
+    }
+    if (orphanedCount > 0) {
+        const orphanedNotMerged = result.orphaned.filter((n) => !result.merged.includes(n));
+        if (orphanedNotMerged.length > 0) {
+            console.log(chalk.yellow(`  Abandoned (no merge): ${orphanedNotMerged.map((n) => `#${n}`).join(", ")}`));
+        }
+    }
+    if (removedCount > 0) {
+        const removedNotMerged = result.removed.filter((n) => !result.merged.includes(n));
+        if (removedNotMerged.length > 0) {
+            console.log(chalk.gray(`  Removed: ${removedNotMerged.map((n) => `#${n}`).join(", ")}`));
+        }
+    }
+    if (dryRun) {
+        console.log(chalk.gray("\nRun without --dry-run to apply these changes."));
+        if (!removeAll && orphanedCount > 0) {
+            console.log(chalk.gray("Use --all to remove both merged and abandoned entries."));
+        }
+    }
+}
+/**
+ * Main state command handler (routes to subcommands)
+ */
+export async function stateCommand(subcommand, options = {}) {
+    switch (subcommand) {
+        case "init":
+            return stateInitCommand(options);
+        case "rebuild":
+            return stateRebuildCommand(options);
+        case "clean":
+            return stateCleanCommand(options);
+        default:
+            console.log(chalk.bold("\n📊 sequant state - Manage workflow state\n"));
+            console.log("Available subcommands:");
+            console.log(chalk.gray("  init     Populate state for untracked worktrees"));
+            console.log(chalk.gray("  rebuild  Recreate state from logs + worktrees"));
+            console.log(chalk.gray("  clean    Remove entries for deleted worktrees"));
+            console.log(chalk.gray("\nRun `sequant state <subcommand> --help` for more information."));
+    }
+}

package/dist/src/commands/stats.d.ts

@@ -1,7 +1,8 @@
 /**
- * sequant stats - Aggregate analysis of workflow run logs
+ * sequant stats - Local workflow analytics
  *
- * Provides success/failure rates, phase durations, and common failure patterns.
+ * Provides success/failure rates, workflow insights, and aggregate statistics.
+ * All data is local - no telemetry is ever sent remotely.
  */
 interface StatsOptions {
     path?: string;

package/dist/src/commands/stats.js

@@ -1,13 +1,15 @@
 /**
- * sequant stats - Aggregate analysis of workflow run logs
+ * sequant stats - Local workflow analytics
  *
- * Provides success/failure rates, phase durations, and common failure patterns.
+ * Provides success/failure rates, workflow insights, and aggregate statistics.
+ * All data is local - no telemetry is ever sent remotely.
  */
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 import { RunLogSchema, LOG_PATHS, } from "../lib/workflow/run-log-schema.js";
+import { MetricsSchema, METRICS_FILE_PATH, } from "../lib/workflow/metrics-schema.js";
 /**
  * Resolve the log directory path
  */
@@ -201,55 +203,219 @@ function displayStats(stats, logDir) {
     console.log("");
 }
 /**
- * Main stats command
+ * Load metrics from file
  */
-export async function statsCommand(options) {
-    const logDir = resolveLogPath(options.path);
-    // List log files
-    const logFiles = listLogFiles(logDir);
-    if (logFiles.length === 0) {
-        if (options.json) {
-            console.log(JSON.stringify({ error: "No logs found", runs: [] }));
+function loadMetrics() {
+    if (!fs.existsSync(METRICS_FILE_PATH)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(METRICS_FILE_PATH, "utf-8");
+        const data = JSON.parse(content);
+        return MetricsSchema.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Calculate analytics from metrics
+ */
+function calculateMetricsAnalytics(metrics) {
+    const runs = metrics.runs;
+    if (runs.length === 0) {
+        return {
+            totalRuns: 0,
+            successCount: 0,
+            partialCount: 0,
+            failedCount: 0,
+            successRate: 0,
+            avgTokensPerRun: 0,
+            avgFilesChanged: 0,
+            avgLinesAdded: 0,
+            avgDuration: 0,
+            chainModeSuccessRate: 0,
+            singleIssueSuccessRate: 0,
+            insights: [],
+        };
+    }
+    const successCount = runs.filter((r) => r.outcome === "success").length;
+    const partialCount = runs.filter((r) => r.outcome === "partial").length;
+    const failedCount = runs.filter((r) => r.outcome === "failed").length;
+    const successRate = (successCount / runs.length) * 100;
+    const avgTokensPerRun = runs.reduce((sum, r) => sum + r.metrics.tokensUsed, 0) / runs.length;
+    const avgFilesChanged = runs.reduce((sum, r) => sum + r.metrics.filesChanged, 0) / runs.length;
+    const avgLinesAdded = runs.reduce((sum, r) => sum + r.metrics.linesAdded, 0) / runs.length;
+    const avgDuration = runs.reduce((sum, r) => sum + r.duration, 0) / runs.length;
+    // Chain mode vs single issue analysis
+    const chainRuns = runs.filter((r) => r.flags.includes("--chain"));
+    const singleIssueRuns = runs.filter((r) => r.issues.length === 1);
+    const chainModeSuccessRate = chainRuns.length > 0
+        ? (chainRuns.filter((r) => r.outcome === "success").length /
+            chainRuns.length) *
+            100
+        : 0;
+    const singleIssueSuccessRate = singleIssueRuns.length > 0
+        ? (singleIssueRuns.filter((r) => r.outcome === "success").length /
+            singleIssueRuns.length) *
+            100
+        : 0;
+    // Generate insights
+    const insights = generateInsights(runs, successRate, avgFilesChanged, avgLinesAdded, chainModeSuccessRate, singleIssueSuccessRate);
+    return {
+        totalRuns: runs.length,
+        successCount,
+        partialCount,
+        failedCount,
+        successRate,
+        avgTokensPerRun,
+        avgFilesChanged,
+        avgLinesAdded,
+        avgDuration,
+        chainModeSuccessRate,
+        singleIssueSuccessRate,
+        insights,
+    };
+}
+/**
+ * Generate insights from metrics data
+ */
+function generateInsights(runs, successRate, avgFilesChanged, avgLinesAdded, chainModeSuccessRate, singleIssueSuccessRate) {
+    const insights = [];
+    // Success rate insight
+    if (successRate >= 80) {
+        insights.push(`Strong success rate: ${successRate.toFixed(0)}%`);
+    }
+    else if (successRate >= 60) {
+        insights.push(`Moderate success rate: ${successRate.toFixed(0)}% - consider simpler AC`);
+    }
+    else if (runs.length >= 5) {
+        insights.push(`Low success rate: ${successRate.toFixed(0)}% - review issue complexity`);
+    }
+    // Optimal file change range (based on common patterns)
+    if (avgFilesChanged > 0) {
+        if (avgFilesChanged <= 5) {
+            insights.push(`Your sweet spot: ${avgFilesChanged.toFixed(1)} files changed avg`);
         }
-        else if (options.csv) {
-            console.log("runId,startTime,duration,issues,passed,failed,phases");
+        else if (avgFilesChanged <= 10) {
+            insights.push(`Avg files changed: ${avgFilesChanged.toFixed(1)} (moderate scope)`);
         }
         else {
-            console.log(chalk.blue("\n📊 Sequant Run Statistics\n"));
-            console.log(chalk.yellow("  No logs found."));
-            console.log(chalk.gray("  Run `npx sequant run <issues>` to generate logs."));
-            console.log("");
+            insights.push(`High avg files (${avgFilesChanged.toFixed(1)}) - consider smaller issues`);
         }
-        return;
     }
-    // Parse all logs
-    const logs = logFiles
-        .map((filename) => {
-        const filePath = path.join(logDir, filename);
-        return parseLogFile(filePath);
-    })
-        .filter((log) => log !== null);
-    if (logs.length === 0) {
-        if (options.json) {
-            console.log(JSON.stringify({ error: "No valid logs found", runs: [] }));
+    // Lines of code insight
+    if (avgLinesAdded > 0) {
+        if (avgLinesAdded >= 200 && avgLinesAdded <= 400) {
+            insights.push(`Optimal LOC range: ~${avgLinesAdded.toFixed(0)} lines avg`);
         }
-        else if (options.csv) {
-            console.log("runId,startTime,duration,issues,passed,failed,phases");
+        else if (avgLinesAdded > 500) {
+            insights.push(`Large changes (${avgLinesAdded.toFixed(0)} LOC avg) - consider splitting issues`);
         }
-        else {
-            console.log(chalk.yellow("\n  No valid log files found.\n"));
+    }
+    // Chain mode comparison
+    if (chainModeSuccessRate > 0 && singleIssueSuccessRate > 0) {
+        const diff = singleIssueSuccessRate - chainModeSuccessRate;
+        if (diff > 10) {
+            insights.push(`Chain mode: ${chainModeSuccessRate.toFixed(0)}% (vs ${singleIssueSuccessRate.toFixed(0)}% single issue)`);
         }
-        return;
     }
-    // CSV output
-    if (options.csv) {
-        console.log(generateCsv(logs));
-        return;
+    // Multi-issue runs
+    const multiIssueRuns = runs.filter((r) => r.issues.length > 1);
+    if (multiIssueRuns.length >= 3) {
+        const multiIssueSuccess = multiIssueRuns.filter((r) => r.outcome === "success").length;
+        const multiSuccessRate = (multiIssueSuccess / multiIssueRuns.length) * 100;
+        if (multiSuccessRate < singleIssueSuccessRate - 15) {
+            insights.push(`Multi-issue runs less successful (${multiSuccessRate.toFixed(0)}%)`);
+        }
     }
-    // JSON output
+    return insights;
+}
+/**
+ * Display local metrics analytics
+ */
+function displayMetricsAnalytics(analytics) {
+    console.log(chalk.blue("\n📊 Sequant Analytics (local data only)\n"));
+    // Overall summary
+    console.log(chalk.gray(`  Runs: ${analytics.totalRuns} total`));
+    console.log(chalk.green(`    Success: ${analytics.successCount} (${analytics.successRate.toFixed(0)}%)`));
+    if (analytics.partialCount > 0) {
+        console.log(chalk.yellow(`    Partial: ${analytics.partialCount}`));
+    }
+    if (analytics.failedCount > 0) {
+        console.log(chalk.red(`    Failed: ${analytics.failedCount}`));
+    }
+    // Averages
+    console.log(chalk.blue("\n  Averages"));
+    console.log(chalk.gray(`  ─────────────────────────────────`));
+    if (analytics.avgTokensPerRun > 0) {
+        console.log(chalk.gray(`  Tokens per run: ${analytics.avgTokensPerRun.toLocaleString()}`));
+    }
+    console.log(chalk.gray(`  Files changed: ${analytics.avgFilesChanged.toFixed(1)}`));
+    if (analytics.avgLinesAdded > 0) {
+        console.log(chalk.gray(`  Lines added: ${analytics.avgLinesAdded.toFixed(0)}`));
+    }
+    console.log(chalk.gray(`  Duration: ${formatDuration(analytics.avgDuration)}`));
+    // Insights
+    if (analytics.insights.length > 0) {
+        console.log(chalk.blue("\n  Insights"));
+        console.log(chalk.gray(`  ─────────────────────────────────`));
+        for (const insight of analytics.insights) {
+            console.log(chalk.gray(`  • ${insight}`));
+        }
+    }
+    console.log(chalk.gray("\n  Data stored locally in .sequant/metrics.json"));
+    console.log("");
+}
+/**
+ * Main stats command
+ */
+export async function statsCommand(options) {
+    // Try to load local metrics first
+    const metrics = loadMetrics();
+    // If JSON output requested
     if (options.json) {
+        if (metrics && metrics.runs.length > 0) {
+            const analytics = calculateMetricsAnalytics(metrics);
+            const output = {
+                source: "metrics",
+                totalRuns: analytics.totalRuns,
+                successCount: analytics.successCount,
+                partialCount: analytics.partialCount,
+                failedCount: analytics.failedCount,
+                successRate: analytics.successRate,
+                avgTokensPerRun: analytics.avgTokensPerRun,
+                avgFilesChanged: analytics.avgFilesChanged,
+                avgLinesAdded: analytics.avgLinesAdded,
+                avgDuration: analytics.avgDuration,
+                chainModeSuccessRate: analytics.chainModeSuccessRate,
+                singleIssueSuccessRate: analytics.singleIssueSuccessRate,
+                insights: analytics.insights,
+                runs: metrics.runs,
+            };
+            console.log(JSON.stringify(output, null, 2));
+            return;
+        }
+        // Fall back to run logs for JSON
+        const logDir = resolveLogPath(options.path);
+        const logFiles = listLogFiles(logDir);
+        if (logFiles.length === 0) {
+            console.log(JSON.stringify({ error: "No data found", runs: [] }));
+            return;
+        }
+        const logs = logFiles
+            .map((filename) => {
+            const filePath = path.join(logDir, filename);
+            return parseLogFile(filePath);
+        })
+            .filter((log) => log !== null);
+        if (logs.length === 0) {
+            console.log(JSON.stringify({ error: "No valid logs found", runs: [] }));
+            return;
+        }
         const stats = calculateStats(logs);
         const output = {
+            source: "logs",
             totalRuns: stats.totalRuns,
             totalIssues: stats.totalIssues,
             passed: stats.passed,
@@ -264,7 +430,49 @@ export async function statsCommand(options) {
         console.log(JSON.stringify(output, null, 2));
         return;
     }
-    // Human-readable output
+    // CSV output - use run logs
+    if (options.csv) {
+        const logDir = resolveLogPath(options.path);
+        const logFiles = listLogFiles(logDir);
+        if (logFiles.length === 0) {
+            console.log("runId,startTime,duration,issues,passed,failed,phases");
+            return;
+        }
+        const logs = logFiles
+            .map((filename) => {
+            const filePath = path.join(logDir, filename);
+            return parseLogFile(filePath);
+        })
+            .filter((log) => log !== null);
+        console.log(generateCsv(logs));
+        return;
+    }
+    // Human-readable output - prefer metrics, fall back to logs
+    if (metrics && metrics.runs.length > 0) {
+        const analytics = calculateMetricsAnalytics(metrics);
+        displayMetricsAnalytics(analytics);
+        return;
+    }
+    // Fall back to run logs display
+    const logDir = resolveLogPath(options.path);
+    const logFiles = listLogFiles(logDir);
+    if (logFiles.length === 0) {
+        console.log(chalk.blue("\n📊 Sequant Analytics (local data only)\n"));
+        console.log(chalk.yellow("  No data found."));
+        console.log(chalk.gray("  Run `npx sequant run <issues>` to collect metrics."));
+        console.log("");
+        return;
+    }
+    const logs = logFiles
+        .map((filename) => {
+        const filePath = path.join(logDir, filename);
+        return parseLogFile(filePath);
+    })
+        .filter((log) => log !== null);
+    if (logs.length === 0) {
+        console.log(chalk.yellow("\n  No valid log files found.\n"));
+        return;
+    }
     const stats = calculateStats(logs);
     displayStats(stats, logDir);
 }

package/dist/src/commands/status.d.ts

@@ -16,5 +16,7 @@ export interface StatusCommandOptions {
     dryRun?: boolean;
     /** Remove entries older than this many days (used with --cleanup) */
     maxAge?: number;
+    /** Remove all orphaned entries (both merged and abandoned) in one step */
+    all?: boolean;
 }
 export declare function statusCommand(options?: StatusCommandOptions): Promise<void>;