@nathapp/nax 0.18.1

package/src/worktree/merge.ts

@@ -0,0 +1,301 @@
+import { getSafeLogger } from "../logger";
+import type { WorktreeManager } from "./manager";
+
+export interface MergeResult {
+  success: boolean;
+  storyId: string;
+  conflictFiles?: string[];
+  retryCount?: number;
+}
+
+export interface StoryDependencies {
+  [storyId: string]: string[];
+}
+
+export class MergeEngine {
+  constructor(private worktreeManager: WorktreeManager) {}
+
+  /**
+   * Merges branch nax/<storyId> into current branch with --no-ff
+   * Returns { success: true } on clean merge
+   * Returns { success: false, conflictFiles: [...] } on conflict
+   * Cleans up worktree after successful merge
+   */
+  async merge(projectRoot: string, storyId: string): Promise<Omit<MergeResult, "storyId">> {
+    const branchName = `nax/${storyId}`;
+
+    try {
+      // Perform merge with --no-ff
+      const mergeProc = Bun.spawn(["git", "merge", "--no-ff", branchName, "-m", `Merge branch '${branchName}'`], {
+        cwd: projectRoot,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const exitCode = await mergeProc.exited;
+      const stderr = await new Response(mergeProc.stderr).text();
+      const stdout = await new Response(mergeProc.stdout).text();
+
+      if (exitCode === 0) {
+        // Clean merge - cleanup worktree
+        try {
+          await this.worktreeManager.remove(projectRoot, storyId);
+        } catch (error) {
+          // Log warning but don't fail the merge
+          const logger = getSafeLogger();
+          logger?.warn("worktree", `Failed to cleanup worktree for ${storyId}`, {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+
+        return { success: true };
+      }
+
+      // Merge failed - check for conflicts
+      const output = `${stdout}\n${stderr}`;
+      if (output.includes("CONFLICT") || output.includes("conflict") || output.includes("Automatic merge failed")) {
+        // Extract conflict files
+        const conflictFiles = await this.getConflictFiles(projectRoot);
+
+        // Abort the merge
+        await this.abortMerge(projectRoot);
+
+        return {
+          success: false,
+          conflictFiles,
+        };
+      }
+
+      // Other error
+      throw new Error(`Merge failed: ${stderr || stdout || "unknown error"}`);
+    } catch (error) {
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new Error(`Failed to merge branch ${branchName}: ${String(error)}`);
+    }
+  }
+
+  /**
+   * Merges stories in topological order based on dependencies
+   * On conflict: retries once after rebasing worktree on updated base
+   * On 2nd conflict: marks story as failed, continues with remaining stories
+   */
+  async mergeAll(projectRoot: string, storyIds: string[], dependencies: StoryDependencies): Promise<MergeResult[]> {
+    // Sort stories in topological order
+    const orderedStories = this.topologicalSort(storyIds, dependencies);
+    const results: MergeResult[] = [];
+    const failedStories = new Set<string>();
+
+    for (const storyId of orderedStories) {
+      // Check if any dependencies failed
+      const deps = dependencies[storyId] || [];
+      const hasFailedDeps = deps.some((dep) => failedStories.has(dep));
+
+      if (hasFailedDeps) {
+        results.push({
+          success: false,
+          storyId,
+          conflictFiles: [],
+        });
+        failedStories.add(storyId);
+        continue;
+      }
+
+      // Try to merge
+      let result = await this.merge(projectRoot, storyId);
+
+      // If conflict, retry once after rebasing
+      if (!result.success && result.conflictFiles) {
+        try {
+          // Rebase worktree on updated base
+          await this.rebaseWorktree(projectRoot, storyId);
+
+          // Retry merge
+          result = await this.merge(projectRoot, storyId);
+
+          // If still fails, mark as failed
+          if (!result.success) {
+            results.push({
+              success: false,
+              storyId,
+              conflictFiles: result.conflictFiles,
+              retryCount: 1,
+            });
+            failedStories.add(storyId);
+            continue;
+          }
+
+          // Success after retry
+          results.push({
+            success: true,
+            storyId,
+            retryCount: 1,
+          });
+        } catch (error) {
+          // Rebase failed, mark as failed
+          results.push({
+            success: false,
+            storyId,
+            conflictFiles: result.conflictFiles,
+            retryCount: 1,
+          });
+          failedStories.add(storyId);
+        }
+      } else if (result.success) {
+        // First attempt succeeded
+        results.push({
+          success: true,
+          storyId,
+          retryCount: 0,
+        });
+      } else {
+        // Failed without conflicts (shouldn't happen normally)
+        results.push({
+          success: false,
+          storyId,
+          retryCount: 0,
+        });
+        failedStories.add(storyId);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Topological sort of stories based on dependencies
+   * Returns stories in order where dependencies come before dependents
+   */
+  private topologicalSort(storyIds: string[], dependencies: StoryDependencies): string[] {
+    const visited = new Set<string>();
+    const sorted: string[] = [];
+    const visiting = new Set<string>();
+
+    const visit = (storyId: string) => {
+      if (visited.has(storyId)) {
+        return;
+      }
+
+      if (visiting.has(storyId)) {
+        throw new Error(`Circular dependency detected involving ${storyId}`);
+      }
+
+      visiting.add(storyId);
+
+      // Visit dependencies first
+      const deps = dependencies[storyId] || [];
+      for (const dep of deps) {
+        if (storyIds.includes(dep)) {
+          visit(dep);
+        }
+      }
+
+      visiting.delete(storyId);
+      visited.add(storyId);
+      sorted.push(storyId);
+    };
+
+    for (const storyId of storyIds) {
+      visit(storyId);
+    }
+
+    return sorted;
+  }
+
+  /**
+   * Rebases worktree on current base branch
+   */
+  private async rebaseWorktree(projectRoot: string, storyId: string): Promise<void> {
+    const worktreePath = `${projectRoot}/.nax-wt/${storyId}`;
+
+    try {
+      // Get current branch name from main repo
+      const currentBranchProc = Bun.spawn(["git", "rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd: projectRoot,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const exitCode = await currentBranchProc.exited;
+      if (exitCode !== 0) {
+        throw new Error("Failed to get current branch");
+      }
+
+      const currentBranch = (await new Response(currentBranchProc.stdout).text()).trim();
+
+      // Rebase worktree branch onto current branch
+      const rebaseProc = Bun.spawn(["git", "rebase", currentBranch], {
+        cwd: worktreePath,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const rebaseExitCode = await rebaseProc.exited;
+      if (rebaseExitCode !== 0) {
+        const stderr = await new Response(rebaseProc.stderr).text();
+
+        // Abort rebase on failure
+        await Bun.spawn(["git", "rebase", "--abort"], {
+          cwd: worktreePath,
+          stdout: "pipe",
+          stderr: "pipe",
+        }).exited;
+
+        throw new Error(`Rebase failed: ${stderr || "unknown error"}`);
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new Error(`Failed to rebase worktree ${storyId}: ${String(error)}`);
+    }
+  }
+
+  /**
+   * Gets list of conflicted files
+   */
+  private async getConflictFiles(projectRoot: string): Promise<string[]> {
+    try {
+      const proc = Bun.spawn(["git", "diff", "--name-only", "--diff-filter=U"], {
+        cwd: projectRoot,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const exitCode = await proc.exited;
+      if (exitCode !== 0) {
+        return [];
+      }
+
+      const stdout = await new Response(proc.stdout).text();
+      return stdout
+        .trim()
+        .split("\n")
+        .filter((line) => line.length > 0);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Aborts an in-progress merge
+   */
+  private async abortMerge(projectRoot: string): Promise<void> {
+    try {
+      const proc = Bun.spawn(["git", "merge", "--abort"], {
+        cwd: projectRoot,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      await proc.exited;
+    } catch (error) {
+      // Log warning but don't throw - merge might already be aborted
+      const logger = getSafeLogger();
+      logger?.warn("worktree", "Failed to abort merge", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}

package/src/worktree/types.ts

@@ -0,0 +1,4 @@
+export interface WorktreeInfo {
+  path: string;
+  branch: string;
+}

package/test/TEST_COVERAGE_US001.md

@@ -0,0 +1,217 @@
+# Test Coverage for US-001: Precheck types and check implementations
+
+## Summary
+
+Created comprehensive failing tests for the precheck system. All tests fail with "Not implemented" errors as expected.
+
+## Test Files Created/Verified
+
+### 1. `test/unit/precheck-types.test.ts` (13 tests) ✅ PASSING
+Tests the type definitions only - these pass because TypeScript validates structure at compile time.
+
+**Coverage:**
+- PrecheckResult type structure (blockers[], warnings[] arrays)
+- Check type structure (name, tier, passed, message fields)
+- CheckTier type values ("blocker", "warning")
+- CheckStatus type values ("passed", "failed", "skipped")
+
+### 2. `test/unit/precheck-checks.test.ts` (55 tests) ❌ FAILING (as expected)
+Tests individual check implementations.
+
+#### Tier 1 Blocker Tests (33 tests):
+1. **checkGitRepoExists** (3 tests)
+   - ✅ Passes when .git directory exists
+   - ✅ Fails when .git directory does not exist
+   - ✅ Uses git rev-parse --git-dir command
+
+2. **checkWorkingTreeClean** (3 tests)
+   - ✅ Uses git status --porcelain command
+   - ✅ Returns blocker tier
+   - ✅ Includes helpful message
+
+3. **checkStaleLock** (4 tests)
+   - ✅ Passes when no lock file exists
+   - ✅ Passes when lock file is fresh (< 2 hours old)
+   - ✅ Fails when lock file is stale (> 2 hours old)
+   - ✅ Detects exactly 2 hours as the threshold
+
+4. **checkPRDValid** (6 tests)
+   - ✅ Passes when all stories have required fields
+   - ✅ Fails when story is missing id
+   - ✅ Fails when story is missing title
+   - ✅ Fails when story is missing description
+   - ✅ Auto-defaults missing tags to empty array in-memory
+   - ✅ Auto-defaults missing status to pending in-memory
+   - ✅ Auto-defaults missing storyPoints to 1 in-memory
+   - ✅ Checks all required fields per story
+
+5. **checkClaudeCLI** (3 tests)
+   - ✅ Runs claude --version command
+   - ✅ Returns blocker tier
+   - ✅ Provides helpful error message on failure
+
+6. **checkDependenciesInstalled** (6 tests)
+   - ✅ Detects Node.js dependencies via node_modules
+   - ✅ Detects Rust dependencies via target directory
+   - ✅ Detects Python dependencies via venv directory
+   - ✅ Detects PHP dependencies via vendor directory
+   - ✅ Fails when no dependency directories exist
+   - ✅ Is language-aware and checks all supported package managers
+
+7. **checkTestCommand** (4 tests)
+   - ✅ Passes when test command is configured
+   - ✅ Skips silently when test command is null
+   - ✅ Skips silently when test command is false
+   - ✅ Reads command from config.execution
+
+8. **checkLintCommand** (4 tests)
+   - ✅ Passes when lint command is configured
+   - ✅ Skips silently when lint command is null
+   - ✅ Skips silently when lint command is false
+   - ✅ Reads command from config.execution
+
+9. **checkTypecheckCommand** (4 tests)
+   - ✅ Passes when typecheck command is configured
+   - ✅ Skips silently when typecheck command is null
+   - ✅ Skips silently when typecheck command is false
+   - ✅ Reads command from config.execution
+
+10. **checkGitUserConfigured** (3 tests)
+    - ✅ Checks git config user.name and user.email
+    - ✅ Returns blocker tier
+    - ✅ Provides helpful message
+
+#### Tier 2 Warning Tests (22 tests):
+1. **checkClaudeMdExists** (3 tests)
+   - ✅ Passes when CLAUDE.md exists
+   - ✅ Fails when CLAUDE.md does not exist
+   - ✅ Returns warning tier not blocker
+
+2. **checkDiskSpace** (4 tests)
+   - ✅ Passes when disk space is above 1GB
+   - ✅ Fails when disk space is below 1GB
+   - ✅ Triggers warning below 1GB threshold
+   - ✅ Provides disk space information in message
+
+3. **checkPendingStories** (3 tests)
+   - ✅ Passes when there are pending stories
+   - ✅ Warns when all stories are passed
+   - ✅ Counts pending and in-progress as actionable
+
+4. **checkOptionalCommands** (3 tests)
+   - ✅ Warns when optional commands are missing
+   - ✅ Passes when all optional commands are configured
+   - ✅ Lists which commands are missing
+
+5. **checkGitignoreCoversNax** (6 tests)
+   - ✅ Passes when .gitignore exists and covers nax runtime files
+   - ✅ Fails when .gitignore does not exist
+   - ✅ Fails when .gitignore exists but does not cover nax.lock
+   - ✅ Fails when .gitignore exists but does not cover runs directories
+   - ✅ Fails when .gitignore exists but does not cover test/tmp
+   - ✅ Checks all three nax runtime file patterns
+
+### 3. `test/integration/precheck.test.ts` (25 tests) ❌ FAILING (as expected)
+Integration tests for the complete precheck workflow.
+
+**Coverage:**
+- ✅ Returns PrecheckResult with blockers and warnings arrays
+- ✅ Separates blocker checks from warning checks
+- ✅ Includes all 10 blocker checks
+- ✅ Includes all 5 warning checks
+- ✅ Auto-defaults missing PRD fields in-memory during validation
+- ✅ Handles PRD with multiple stories
+- ✅ Detects invalid PRD with missing required fields
+- ✅ Skips command checks when commands are set to null
+- ✅ Completes all checks even if some fail
+- ✅ Provides detailed messages for each check
+- ✅ Stale lock detection (2 tests)
+- ✅ .gitignore validation (4 tests)
+
+## Source Files Created
+
+### 1. `src/precheck/types.ts`
+Type definitions for:
+- `CheckTier` = "blocker" | "warning"
+- `CheckStatus` = "passed" | "failed" | "skipped"
+- `Check` interface (name, tier, passed, message)
+- `PrecheckResult` interface (blockers[], warnings[])
+
+### 2. `src/precheck/checks.ts`
+Stub implementations for all check functions:
+- 10 Tier 1 blocker checks
+- 5 Tier 2 warning checks
+- All throw "Not implemented" errors
+
+### 3. `src/precheck/index.ts`
+Stub for runPrecheck orchestrator (US-002):
+- `runPrecheck(config, prd)` - throws "Not implemented" with note about US-002
+
+## Acceptance Criteria Coverage
+
+✅ **AC1:** PrecheckResult type includes blockers[] and warnings[] arrays
+- Verified in test/unit/precheck-types.test.ts
+
+✅ **AC2:** Git repo check uses git rev-parse --git-dir
+- Verified in test/unit/precheck-checks.test.ts
+
+✅ **AC3:** Working tree check uses git status --porcelain
+- Verified in test/unit/precheck-checks.test.ts
+
+✅ **AC4:** Stale lock detection: nax.lock older than 2 hours
+- Verified in test/unit/precheck-checks.test.ts (4 tests)
+
+✅ **AC5:** PRD validation checks id, title, description per story
+- Verified in test/unit/precheck-checks.test.ts (8 tests)
+
+✅ **AC6:** PRD auto-defaults missing optional fields in-memory
+- Verified in test/unit/precheck-checks.test.ts (3 tests)
+- tags=[], status=pending, storyPoints=1
+
+✅ **AC7:** Claude CLI check runs claude --version
+- Verified in test/unit/precheck-checks.test.ts
+
+✅ **AC8:** Dependency detection is language-aware
+- Verified in test/unit/precheck-checks.test.ts (6 tests)
+- node_modules, target, venv, vendor
+
+✅ **AC9:** Test/lint/typecheck commands read from config.execution
+- Verified in test/unit/precheck-checks.test.ts (12 tests)
+
+✅ **AC10:** Commands set to null/false are skipped silently
+- Verified in test/unit/precheck-checks.test.ts (6 tests)
+
+✅ **AC11:** Disk space warning triggers below 1GB
+- Verified in test/unit/precheck-checks.test.ts (4 tests)
+
+✅ **AC12:** .gitignore warning if missing or does not cover nax runtime files
+- Verified in test/unit/precheck-checks.test.ts (6 tests)
+- Checks: nax.lock, nax/features/*/runs/, test/tmp/
+
+## Test Execution Results
+
+### Unit Tests - Types
+```
+bun test ./test/unit/precheck-types.test.ts
+✅ 13 pass, 0 fail, 20 expect() calls
+```
+
+### Unit Tests - Checks
+```
+bun test ./test/unit/precheck-checks.test.ts
+❌ All tests fail with "Not implemented" errors (expected behavior)
+```
+
+### Integration Tests
+```
+bun test ./test/integration/precheck.test.ts
+❌ All tests fail with "Not implemented" errors (expected behavior)
+```
+
+## Next Steps
+
+The implementer (Session 2) should now implement:
+1. All check functions in `src/precheck/checks.ts`
+2. The `runPrecheck` orchestrator in `src/precheck/index.ts` (for US-002)
+
+All tests are ready and will validate correct implementation behavior.

package/test/TEST_COVERAGE_US003.md

@@ -0,0 +1,84 @@
+# Test Coverage: US-003 - CLI nax precheck command
+
+## Story: US-003
+CLI nax precheck command with --json flag
+
+## Test File
+`test/integration/cli-precheck.test.ts` - 7 tests
+
+## Coverage
+
+### 1. Command Registration
+✅ Command is registered as `nax precheck`
+✅ Supports `-f, --feature <name>` flag
+✅ Supports `-d, --dir <path>` flag
+✅ Supports `--json` flag
+
+### 2. Project Resolution
+✅ Uses `resolveProject()` from common.ts (US-001)
+✅ Resolves project directory with `-d` flag
+✅ Resolves feature directory from `-f` flag or config.json
+✅ Validates nax/ directory exists
+✅ Validates prd.json exists
+
+### 3. Output Formats
+✅ Human-readable format (default) - emoji indicators (✓/✗/⚠)
+✅ Machine-readable JSON format (--json flag)
+✅ JSON includes: passed, blockers, warnings, summary, feature
+
+### 4. Exit Codes
+✅ Exit code 0 - All checks passed (or warnings only)
+✅ Exit code 1 - Blocker detected
+✅ Exit code 2 - Invalid PRD (missing prd.json or invalid structure)
+
+### 5. Error Handling
+✅ Missing feature flag with no config.json feature - exit 1
+✅ Missing prd.json - exit 2
+✅ Invalid PRD structure - exit 2
+✅ Missing feature directory - proper error message
+
+## Test Structure
+- Uses temp directories for isolation
+- Sets up minimal git repo to satisfy checks
+- Mocks process.exit to capture exit codes
+- Tests both human and JSON output formats
+
+## Integration Points
+- ✅ Uses resolveProject() from src/commands/common.ts
+- ✅ Uses runPrecheck() from src/precheck/index.ts
+- ✅ Uses loadConfig() from src/config
+- ✅ Uses loadPRD() from src/prd
+- ✅ Respects EXIT_CODES from src/precheck
+
+## Verified Behavior
+1. Command registered in bin/nax.ts
+2. Exported from src/commands/index.ts
+3. Uses same project resolution as `nax status` and `nax logs`
+4. Fail-fast on Tier 1 blockers
+5. Collects all Tier 2 warnings
+6. Proper exit codes for automation/CI
+
+## Manual Testing
+```bash
+# Human format (default)
+nax precheck -f precheck
+# Exit code: 0 (warnings only)
+
+# JSON format
+nax precheck -f precheck --json
+# Output: {"passed":true,"feature":"precheck","summary":{...}}
+
+# Explicit directory
+nax precheck -f precheck -d /path/to/project
+
+# Missing feature
+nax precheck
+# Error: No feature specified
+```
+
+## Coverage Summary
+- 7 integration tests
+- All acceptance criteria verified
+- All flags tested
+- All exit codes tested
+- Error paths covered

package/test/TEST_COVERAGE_US005.md

@@ -0,0 +1,86 @@
+# Test Coverage: US-005 Config-Driven Review Commands
+
+## Story
+Config-driven review commands replacing hardcoded lint
+
+## Implementation Summary
+
+### Files Modified
+1. **src/config/schema.ts**
+   - Added `lintCommand?: string | null` to `ExecutionConfig`
+   - Added `typecheckCommand?: string | null` to `ExecutionConfig`
+   - Updated `ExecutionConfigSchema` to validate these fields
+
+2. **src/review/runner.ts**
+   - Added `loadPackageJson()` - loads package.json from workdir
+   - Added `hasScript()` - checks if package.json has a script
+   - Added `resolveCommand()` - implements resolution strategy
+   - Modified `runReview()` - accepts optional `executionConfig` parameter
+   - Implements command resolution order:
+     1. `executionConfig.lintCommand` / `executionConfig.typecheckCommand` (null = disabled)
+     2. `config.review.commands[check]` (legacy, backwards compat)
+     3. package.json scripts -> `bun run <script>`
+     4. Not found -> skip with warning
+
+3. **src/pipeline/stages/review.ts**
+   - Updated `runReview()` call to pass `ctx.config.execution`
+
+### Test Coverage
+
+**New Tests: test/integration/review-config-commands.test.ts (12 tests)**
+- ✅ uses explicit executionConfig.lintCommand when provided
+- ✅ uses explicit executionConfig.typecheckCommand when provided
+- ✅ skips check when executionConfig command is null (explicitly disabled)
+- ✅ uses package.json script when no executionConfig override
+- ✅ skips check when package.json script not found
+- ✅ executionConfig takes precedence over package.json
+- ✅ reviewConfig.commands takes precedence over package.json (backwards compat)
+- ✅ executionConfig takes precedence over reviewConfig.commands
+- ✅ handles missing package.json gracefully
+- ✅ handles invalid package.json gracefully
+- ✅ resolution order: executionConfig > reviewConfig > package.json
+- ✅ test command ignores executionConfig (not affected by this story)
+
+**Updated Tests: test/integration/review.test.ts**
+- ✅ Modified "uses default commands when not specified" test to match new behavior
+
+## Acceptance Criteria Coverage
+
+| Criterion | Status | Evidence |
+|-----------|--------|----------|
+| Review stage reads lintCommand from config.execution | ✅ | `test/integration/review-config-commands.test.ts:23-37` |
+| Review stage reads typecheckCommand from config.execution | ✅ | `test/integration/review-config-commands.test.ts:39-53` |
+| Resolution order: config -> package.json -> skip | ✅ | `test/integration/review-config-commands.test.ts:185-214` |
+| Setting command to null/false explicitly disables it | ✅ | `test/integration/review-config-commands.test.ts:55-71` |
+| Missing command logs warning instead of failing | ✅ | `src/review/runner.ts:140-143` + test output shows warnings |
+| Config schema updated with lintCommand and typecheckCommand fields | ✅ | `src/config/schema.ts:113-114` |
+| BUG-005 (hardcoded bun run lint) is resolved | ✅ | No hardcoded commands, all resolved via strategy |
+
+## Behavior Changes
+
+### Before
+- Always used hardcoded defaults: `bun run lint`, `bun run typecheck`, `bun test`
+- Commands from `config.review.commands` could override defaults
+- No way to explicitly disable a check without removing it from `checks` array
+
+### After
+- Command resolution follows priority:
+  1. `config.execution.lintCommand` / `typecheckCommand` (highest priority)
+  2. `config.review.commands[check]` (legacy, for backwards compatibility)
+  3. package.json scripts (auto-detected)
+  4. Skip with warning (no command found)
+- Setting `lintCommand: null` explicitly disables lint check
+- Missing commands no longer fail - they skip with a warning
+
+## Backwards Compatibility
+
+✅ **Fully backwards compatible**
+- Existing configs using `config.review.commands` continue to work
+- Projects without explicit config fall back to package.json detection
+- No breaking changes to existing APIs
+
+## Notes
+
+- `test` command intentionally NOT added to `ExecutionConfig` (not part of this story scope)
+- Resolution order ensures maximum flexibility: explicit config > legacy config > auto-detect > skip
+- Warning messages logged when commands are skipped for debugging visibility