sequant 1.7.0 → 1.9.0

package/dist/bin/cli.js

@@ -10,6 +10,7 @@ import { fileURLToPath } from "url";
 import { dirname, resolve } from "path";
 import { readFileSync } from "fs";
 import { initCommand } from "../src/commands/init.js";
+import { isLocalNodeModulesInstall } from "../src/lib/version-check.js";
 // Read version from package.json dynamically
 // Works from both source (bin/) and compiled (dist/bin/) locations
 function getVersion() {
@@ -43,6 +44,13 @@ const program = new Command();
 if (process.argv.includes("--no-color")) {
     process.env.FORCE_COLOR = "0";
 }
+// Warn if running from local node_modules (not npx cache or global)
+// This helps users who accidentally have a stale local install
+if (!process.argv.includes("--quiet") && isLocalNodeModulesInstall()) {
+    console.warn(chalk.yellow("⚠️  Running sequant from local node_modules\n" +
+        "   For latest version: npx sequant@latest\n" +
+        "   To remove local: npm uninstall sequant\n"));
+}
 program
     .name("sequant")
     .description("Quantize your development workflow - Sequential AI phases with quality gates")
@@ -90,6 +98,7 @@ program
     .option("--no-smart-tests", "Disable smart test detection")
     .option("--testgen", "Run testgen phase after spec")
     .option("--quiet", "Suppress version warnings and non-essential output")
+    .option("--chain", "Chain issues: each branches from previous (requires --sequential)")
     .action(runCommand);
 program
     .command("logs")

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

@@ -17,6 +17,12 @@ export declare function listWorktrees(): Array<{
  * Get changed files in a worktree compared to main
  */
 export declare function getWorktreeChangedFiles(worktreePath: string): string[];
+/**
+ * Create a checkpoint commit in the worktree after QA passes
+ * This allows recovery in case later issues in the chain fail
+ * @internal Exported for testing
+ */
+export declare function createCheckpointCommit(worktreePath: string, issueNumber: number, verbose: boolean): boolean;
 /**
  * Detect phases based on issue labels (like /solve logic)
  */
@@ -58,6 +64,8 @@ interface RunOptions {
     reuseWorktrees?: boolean;
     /** Suppress version warnings and non-essential output */
     quiet?: boolean;
+    /** Chain issues: each branches from previous (requires --sequential) */
+    chain?: boolean;
 }
 /**
  * Main run command

package/dist/src/commands/run.js

@@ -105,8 +105,9 @@ export function getWorktreeChangedFiles(worktreePath) {
 }
 /**
  * Create or reuse a worktree for an issue
+ * @param baseBranch - Optional branch to use as base instead of origin/main (for chain mode)
  */
-async function ensureWorktree(issueNumber, title, verbose, packageManager) {
+async function ensureWorktree(issueNumber, title, verbose, packageManager, baseBranch) {
     const gitRoot = getGitRoot();
     if (!gitRoot) {
         console.log(chalk.red("    ❌ Not in a git repository"));
@@ -135,15 +136,22 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager) {
     if (verbose) {
         console.log(chalk.gray(`    🌿 Creating worktree for #${issueNumber}...`));
     }
-    // Fetch latest main to ensure worktree starts from fresh baseline
-    if (verbose) {
-        console.log(chalk.gray(`    🔄 Fetching latest main...`));
+    // Determine the base for the new branch
+    const baseRef = baseBranch || "origin/main";
+    // Fetch latest main to ensure worktree starts from fresh baseline (unless using local branch)
+    if (!baseBranch) {
+        if (verbose) {
+            console.log(chalk.gray(`    🔄 Fetching latest main...`));
+        }
+        const fetchResult = spawnSync("git", ["fetch", "origin", "main"], {
+            stdio: "pipe",
+        });
+        if (fetchResult.status !== 0 && verbose) {
+            console.log(chalk.yellow(`    ⚠️  Could not fetch origin/main, using local state`));
+        }
     }
-    const fetchResult = spawnSync("git", ["fetch", "origin", "main"], {
-        stdio: "pipe",
-    });
-    if (fetchResult.status !== 0 && verbose) {
-        console.log(chalk.yellow(`    ⚠️  Could not fetch origin/main, using local state`));
+    else if (verbose) {
+        console.log(chalk.gray(`    🔗 Chaining from branch: ${baseBranch}`));
     }
     // Ensure worktrees directory exists
     if (!existsSync(worktreesDir)) {
@@ -158,8 +166,8 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager) {
         });
     }
     else {
-        // Create new branch from origin/main (fresh baseline)
-        createResult = spawnSync("git", ["worktree", "add", worktreePath, "-b", branch, "origin/main"], { stdio: "pipe" });
+        // Create new branch from base reference (origin/main or previous branch in chain)
+        createResult = spawnSync("git", ["worktree", "add", worktreePath, "-b", branch, baseRef], { stdio: "pipe" });
     }
     if (createResult.status !== 0) {
         const error = createResult.stderr.toString();
@@ -225,6 +233,90 @@ async function ensureWorktrees(issues, verbose, packageManager) {
     }
     return worktrees;
 }
+/**
+ * Ensure worktrees exist for all issues in chain mode
+ * Each issue branches from the previous issue's branch
+ */
+async function ensureWorktreesChain(issues, verbose, packageManager) {
+    const worktrees = new Map();
+    console.log(chalk.blue("\n  🔗 Preparing chained worktrees..."));
+    let previousBranch;
+    for (const issue of issues) {
+        const worktree = await ensureWorktree(issue.number, issue.title, verbose, packageManager, previousBranch);
+        if (worktree) {
+            worktrees.set(issue.number, worktree);
+            previousBranch = worktree.branch; // Next issue will branch from this
+        }
+        else {
+            // If worktree creation fails, stop the chain
+            console.log(chalk.red(`  ❌ Chain broken: could not create worktree for #${issue.number}`));
+            break;
+        }
+    }
+    const created = Array.from(worktrees.values()).filter((w) => !w.existed).length;
+    const reused = Array.from(worktrees.values()).filter((w) => w.existed).length;
+    if (created > 0 || reused > 0) {
+        console.log(chalk.gray(`  Chained worktrees: ${created} created, ${reused} reused`));
+    }
+    // Show chain structure
+    if (worktrees.size > 0) {
+        const chainOrder = issues
+            .filter((i) => worktrees.has(i.number))
+            .map((i) => `#${i.number}`)
+            .join(" → ");
+        console.log(chalk.gray(`  Chain: origin/main → ${chainOrder}`));
+    }
+    return worktrees;
+}
+/**
+ * Create a checkpoint commit in the worktree after QA passes
+ * This allows recovery in case later issues in the chain fail
+ * @internal Exported for testing
+ */
+export function createCheckpointCommit(worktreePath, issueNumber, verbose) {
+    // Check if there are uncommitted changes
+    const statusResult = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { stdio: "pipe" });
+    if (statusResult.status !== 0) {
+        if (verbose) {
+            console.log(chalk.yellow(`    ⚠️  Could not check git status for checkpoint`));
+        }
+        return false;
+    }
+    const hasChanges = statusResult.stdout.toString().trim().length > 0;
+    if (!hasChanges) {
+        if (verbose) {
+            console.log(chalk.gray(`    📌 No changes to checkpoint (already committed)`));
+        }
+        return true;
+    }
+    // Stage all changes
+    const addResult = spawnSync("git", ["-C", worktreePath, "add", "-A"], {
+        stdio: "pipe",
+    });
+    if (addResult.status !== 0) {
+        if (verbose) {
+            console.log(chalk.yellow(`    ⚠️  Could not stage changes for checkpoint`));
+        }
+        return false;
+    }
+    // Create checkpoint commit
+    const commitMessage = `checkpoint(#${issueNumber}): QA passed
+
+This is an automatic checkpoint commit created after issue #${issueNumber}
+passed QA in chain mode. It serves as a recovery point if later issues fail.
+
+Co-Authored-By: Sequant <noreply@sequant.dev>`;
+    const commitResult = spawnSync("git", ["-C", worktreePath, "commit", "-m", commitMessage], { stdio: "pipe" });
+    if (commitResult.status !== 0) {
+        const error = commitResult.stderr.toString();
+        if (verbose) {
+            console.log(chalk.yellow(`    ⚠️  Could not create checkpoint commit: ${error}`));
+        }
+        return false;
+    }
+    console.log(chalk.green(`    📌 Checkpoint commit created for #${issueNumber}`));
+    return true;
+}
 /**
  * Natural language prompts for each phase
  * These prompts will invoke the corresponding skills via natural language
@@ -793,8 +885,30 @@ export async function runCommand(issues, options) {
         console.log(chalk.gray("\nUsage: npx sequant run <issues...> [options]"));
         console.log(chalk.gray("Example: npx sequant run 1 2 3 --sequential"));
         console.log(chalk.gray('Batch example: npx sequant run --batch "1 2" --batch "3"'));
+        console.log(chalk.gray("Chain example: npx sequant run 1 2 3 --sequential --chain"));
         return;
     }
+    // Validate chain mode requirements
+    if (mergedOptions.chain) {
+        if (!mergedOptions.sequential) {
+            console.log(chalk.red("❌ --chain requires --sequential flag"));
+            console.log(chalk.gray("   Chain mode executes issues sequentially, each branching from the previous."));
+            console.log(chalk.gray("   Usage: npx sequant run 1 2 3 --sequential --chain"));
+            return;
+        }
+        if (batches) {
+            console.log(chalk.red("❌ --chain cannot be used with --batch"));
+            console.log(chalk.gray("   Chain mode creates a linear dependency chain between issues."));
+            return;
+        }
+        // Warn about long chains
+        if (issueNumbers.length > 5) {
+            console.log(chalk.yellow(`  ⚠️  Warning: Chain has ${issueNumbers.length} issues (recommended max: 5)`));
+            console.log(chalk.yellow("     Long chains increase merge complexity and review difficulty."));
+            console.log(chalk.yellow("     Consider breaking into smaller chains or using batch mode."));
+            console.log("");
+        }
+    }
     // Sort issues by dependencies (if more than one issue)
     if (issueNumbers.length > 1 && !batches) {
         const originalOrder = [...issueNumbers];
@@ -878,6 +992,9 @@ export async function runCommand(issues, options) {
     if (useWorktreeIsolation) {
         console.log(chalk.gray(`  Worktree isolation: enabled`));
     }
+    if (mergedOptions.chain) {
+        console.log(chalk.gray(`  Chain mode: enabled (each issue branches from previous)`));
+    }
     // Fetch issue info for all issues first
     const issueInfoMap = new Map();
     for (const issueNumber of issueNumbers) {
@@ -890,7 +1007,13 @@ export async function runCommand(issues, options) {
             number: num,
             title: issueInfoMap.get(num)?.title || `Issue #${num}`,
         }));
-        worktreeMap = await ensureWorktrees(issueData, config.verbose, manifest.packageManager);
+        // Use chain mode or standard worktree creation
+        if (mergedOptions.chain) {
+            worktreeMap = await ensureWorktreesChain(issueData, config.verbose, manifest.packageManager);
+        }
+        else {
+            worktreeMap = await ensureWorktrees(issueData, config.verbose, manifest.packageManager);
+        }
         // Register cleanup tasks for newly created worktrees (not pre-existing ones)
         for (const [issueNum, worktree] of worktreeMap.entries()) {
             if (!worktree.existed) {
@@ -937,7 +1060,7 @@ export async function runCommand(issues, options) {
                 if (logWriter) {
                     logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
                 }
-                const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, mergedOptions, worktreeInfo?.path, shutdown);
+                const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, mergedOptions, worktreeInfo?.path, shutdown, mergedOptions.chain);
                 results.push(result);
                 // Complete issue logging
                 if (logWriter) {
@@ -948,7 +1071,8 @@ export async function runCommand(issues, options) {
                     break;
                 }
                 if (!result.success) {
-                    console.log(chalk.yellow(`\n  ⚠️  Issue #${issueNumber} failed, stopping sequential execution`));
+                    const chainInfo = mergedOptions.chain ? " (chain stopped)" : "";
+                    console.log(chalk.yellow(`\n  ⚠️  Issue #${issueNumber} failed, stopping sequential execution${chainInfo}`));
                     break;
                 }
             }
@@ -970,7 +1094,7 @@ export async function runCommand(issues, options) {
                 if (logWriter) {
                     logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
                 }
-                const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, mergedOptions, worktreeInfo?.path, shutdown);
+                const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, mergedOptions, worktreeInfo?.path, shutdown, false);
                 results.push(result);
                 // Complete issue logging
                 if (logWriter) {
@@ -1043,7 +1167,7 @@ async function executeBatch(issueNumbers, config, logWriter, options, issueInfoM
         if (logWriter) {
             logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
         }
-        const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, options, worktreeInfo?.path, shutdownManager);
+        const result = await runIssueWithLogging(issueNumber, config, logWriter, issueInfo.labels, options, worktreeInfo?.path, shutdownManager, false);
         results.push(result);
         // Complete issue logging
         if (logWriter) {
@@ -1055,7 +1179,7 @@ async function executeBatch(issueNumbers, config, logWriter, options, issueInfoM
 /**
  * Execute all phases for a single issue with logging and quality loop
  */
-async function runIssueWithLogging(issueNumber, config, logWriter, labels, options, worktreePath, shutdownManager) {
+async function runIssueWithLogging(issueNumber, config, logWriter, labels, options, worktreePath, shutdownManager, chainMode) {
     const startTime = Date.now();
     const phaseResults = [];
     let loopTriggered = false;
@@ -1231,6 +1355,10 @@ async function runIssueWithLogging(issueNumber, config, logWriter, labels, optio
     // Success is determined by whether all phases completed in any iteration,
     // not whether all accumulated phase results passed (which would fail after loop recovery)
     const success = completedSuccessfully;
+    // Create checkpoint commit in chain mode after QA passes
+    if (success && chainMode && worktreePath) {
+        createCheckpointCommit(worktreePath, issueNumber, config.verbose);
+    }
     return {
         issueNumber,
         success,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {

package/templates/scripts/new-feature.sh

@@ -162,8 +162,46 @@ fi
 
 # Install dependencies if needed
 if [ ! -d "node_modules" ]; then
-    echo -e "${BLUE}📦 Installing dependencies...${NC}"
-    npm install --silent
+    # Check for npm install cache optimization (opt-in via SEQUANT_NPM_CACHE=true)
+    if [ "${SEQUANT_NPM_CACHE:-false}" = "true" ]; then
+        CACHE_DIR="../worktrees/.npm-cache"
+        HASH_FILE="${CACHE_DIR}/.package-lock-hash"
+
+        # Calculate current package-lock hash (cross-platform)
+        if command -v md5sum &> /dev/null; then
+            CURRENT_HASH=$(md5sum "${MAIN_REPO_DIR}/package-lock.json" | cut -d' ' -f1)
+        elif command -v md5 &> /dev/null; then
+            CURRENT_HASH=$(md5 -q "${MAIN_REPO_DIR}/package-lock.json")
+        else
+            CURRENT_HASH=""
+        fi
+
+        # Check if cache is valid
+        if [ -n "$CURRENT_HASH" ] && [ -f "$HASH_FILE" ] && [ -d "${MAIN_REPO_DIR}/node_modules" ]; then
+            CACHED_HASH=$(cat "$HASH_FILE" 2>/dev/null || echo "")
+            if [ "$CURRENT_HASH" = "$CACHED_HASH" ]; then
+                echo -e "${GREEN}⚡ Using cached node_modules (package-lock unchanged)${NC}"
+                cp -r "${MAIN_REPO_DIR}/node_modules" ./node_modules
+            else
+                echo -e "${BLUE}📦 Installing dependencies (package-lock changed)...${NC}"
+                npm install --silent
+                # Update cache hash
+                mkdir -p "$CACHE_DIR"
+                echo "$CURRENT_HASH" > "$HASH_FILE"
+            fi
+        else
+            echo -e "${BLUE}📦 Installing dependencies (initializing cache)...${NC}"
+            npm install --silent
+            # Initialize cache hash
+            if [ -n "$CURRENT_HASH" ]; then
+                mkdir -p "$CACHE_DIR"
+                echo "$CURRENT_HASH" > "$HASH_FILE"
+            fi
+        fi
+    else
+        echo -e "${BLUE}📦 Installing dependencies...${NC}"
+        npm install --silent
+    fi
 fi
 
 echo ""