@eldrforge/kodrdriv 1.2.29 → 1.2.124

package/AUDIT-BRANCHES-PROGRESS-FIX.md

@@ -1,90 +0,0 @@
-# Branch Audit Progress Feedback Improvements
-
-## Problem
-
-The `kodrdriv tree publish --audit-branches` command takes a long time to run (several minutes for large monorepos) with no progress feedback, making it difficult to know if the command is actually running or stuck.
-
-## Root Cause
-
-The `auditBranchState` function in `src/utils/branchState.ts` performs extensive checks on every package:
-- Git operations (fetch, ls-remote, rev-list, merge-tree)
-- GitHub API calls to check for existing PRs
-- Version validation
-- Target branch sync checks
-
-For a monorepo with 50+ packages, these sequential operations can take 2-3 seconds per package (100-150 seconds total) with no feedback during execution.
-
-## Changes Made
-
-### 1. Phase-based Progress Reporting
-
-Added two-phase execution with clear messaging:
-
-```
-Phase 1/2: Detecting most common branch across packages...
-  [1/50] Checking branch: package-a
-  [2/50] Checking branch: package-b
-  ...
-✓ Most common branch: development (48/50 packages)
-
-Phase 2/2: Auditing package state (checking git status, conflicts, PRs, versions)...
-  [1/50] Auditing: package-a
-  [2/50] Auditing: package-b
-  ...
-✓ Audit complete: 45/50 packages have no issues
-  Issues found in 5 package(s)
-```
-
-### 2. Per-Package Progress Counters
-
-Each package now shows its position in the queue `[N/Total]` so users can track overall progress.
-
-### 3. Verbose Operation Logging
-
-Added verbose logging for expensive operations within each package check:
-- "Fetching latest from origin..."
-- "Checking for merge conflicts..."
-- "Checking GitHub for existing PRs..."
-- "Found existing PR #123..."
-
-These only appear when `--verbose` or `--debug` flags are used, providing more detailed feedback without cluttering default output.
-
-### 4. Completion Summary
-
-Added clear completion message showing:
-- Number of packages with no issues
-- Number of packages with issues (if any)
-
-## Impact
-
-Users can now:
-1. **See that the command is running** - immediate feedback with progress counters
-2. **Estimate completion time** - `[15/50]` indicates 30% complete
-3. **Identify slow operations** - verbose mode shows which operation is taking time
-4. **Know when it's done** - clear completion message
-
-## Files Modified
-
-- `src/utils/branchState.ts` - Added progress logging to `auditBranchState` and `checkBranchStatus` functions
-
-## Testing
-
-Compile check: ✅ Passed (`tsc --noEmit`)
-
-Manual testing recommended:
-```bash
-kodrdriv tree publish --audit-branches
-kodrdriv tree publish --audit-branches --verbose
-kodrdriv tree publish --audit-branches --debug
-```
-
-## Future Optimizations (Not Implemented)
-
-Potential future improvements for faster execution:
-1. **Parallel package checks** - Process multiple packages simultaneously (requires careful handling of git operations)
-2. **Batch GitHub API calls** - Use GraphQL to query multiple PRs at once
-3. **Cache git fetch results** - Avoid fetching the same remote multiple times
-4. **Skip checks for packages with no changes** - Use git status to detect unchanged packages early
-
-These optimizations would require more significant refactoring and testing.
-

package/AUDIT-EXAMPLE-OUTPUT.md

@@ -1,113 +0,0 @@
-# Example Output: Branch Audit with Progress Feedback
-
-## Before (No Feedback)
-
-```bash
-$ kodrdriv tree publish --audit-branches
-🔍 Auditing branch state across all packages...
-BRANCH_STATE_AUDIT: Auditing branch state for packages | Package Count: 50 | Purpose: Verify synchronization
-Checking for merge conflicts with 'main' and existing pull requests...
-
-[... 2-3 minutes of silence ...]
-
-✅ All 45 package(s) are in good state!
-```
-
-**Problem:** Users don't know if the command is running or stuck.
-
----
-
-## After (With Progress Feedback)
-
-### Default Output
-
-```bash
-$ kodrdriv tree publish --audit-branches
-🔍 Auditing branch state across all packages...
-BRANCH_STATE_AUDIT: Auditing branch state for packages | Package Count: 50 | Purpose: Verify synchronization
-Checking for merge conflicts with 'main' and existing pull requests...
-
-📋 Phase 1/2: Detecting most common branch across packages...
-  [1/50] Checking branch: @myorg/core
-  [2/50] Checking branch: @myorg/utils
-  [3/50] Checking branch: @myorg/api
-  ...
-  [48/50] Checking branch: @myorg/tests
-  [49/50] Checking branch: @myorg/docs
-  [50/50] Checking branch: @myorg/cli
-✓ Most common branch: development (48/50 packages)
-
-📋 Phase 2/2: Auditing package state (checking git status, conflicts, PRs, versions)...
-  [1/50] Auditing: @myorg/core
-  [2/50] Auditing: @myorg/utils
-  [3/50] Auditing: @myorg/api
-  ...
-  [48/50] Auditing: @myorg/tests
-  [49/50] Auditing: @myorg/docs
-  [50/50] Auditing: @myorg/cli
-✓ Audit complete: 45/50 packages have no issues
-  Issues found in 5 package(s)
-
-[... detailed issue report ...]
-
-⚠️  Found issues in 5 package(s). Review the fixes above.
-```
-
-### Verbose Output (`--verbose`)
-
-```bash
-$ kodrdriv tree publish --audit-branches --verbose
-🔍 Auditing branch state across all packages...
-BRANCH_STATE_AUDIT: Auditing branch state for packages | Package Count: 50 | Purpose: Verify synchronization
-Checking for merge conflicts with 'main' and existing pull requests...
-
-📋 Phase 1/2: Detecting most common branch across packages...
-  [1/50] Checking branch: @myorg/core
-  [2/50] Checking branch: @myorg/utils
-  ...
-✓ Most common branch: development (48/50 packages)
-
-📋 Phase 2/2: Auditing package state (checking git status, conflicts, PRs, versions)...
-  [1/50] Auditing: @myorg/core
-    Fetching latest from origin for /path/to/core...
-    Checking for merge conflicts with main...
-    Checking GitHub for existing PRs...
-  [2/50] Auditing: @myorg/utils
-    Fetching latest from origin for /path/to/utils...
-    Checking for merge conflicts with main...
-    Checking GitHub for existing PRs...
-    Found existing PR #123: https://github.com/myorg/utils/pull/123
-  [3/50] Auditing: @myorg/api
-    Fetching latest from origin for /path/to/api...
-    Checking for merge conflicts with main...
-    ⚠️  Merge conflicts detected with main
-    Checking GitHub for existing PRs...
-  ...
-✓ Audit complete: 45/50 packages have no issues
-  Issues found in 5 package(s)
-```
-
-## Benefits
-
-1. **Immediate Feedback:** Users see progress start immediately
-2. **Progress Tracking:** `[N/Total]` shows exactly where you are
-3. **Time Estimation:** If `[10/50]` takes 30 seconds, expect ~2.5 minutes total
-4. **Debug Support:** Verbose mode shows which operations are slow
-5. **Clear Completion:** Final summary shows results at a glance
-
-## Testing the Changes
-
-```bash
-# Test in a monorepo with multiple packages
-cd /path/to/your/monorepo
-
-# Default output (progress with package names)
-kodrdriv tree publish --audit-branches
-
-# Verbose output (shows git operations)
-kodrdriv tree publish --audit-branches --verbose
-
-# Debug output (most detailed)
-kodrdriv tree publish --audit-branches --debug
-```
-

package/CHECKPOINT-RECOVERY-FIX.md

@@ -1,450 +0,0 @@
-# Checkpoint Recovery Fix - Critical Bug Resolution
-
-## Issue Summary
-
-**Date**: 2025-12-12
-**Version Fixed**: kodrdriv 1.2.29-dev.0
-**Priority**: CRITICAL
-**Impact**: Parallel publish checkpoint recovery was completely broken for the primary use case
-
-### The Problem
-
-The parallel publish checkpoint/recovery system failed to proceed to dependent packages after marking a root dependency as completed, resulting in an infinite loop where all dependent packages remained "Skipped due to dependencies" even though the dependency was successfully marked as completed.
-
-This made recovery from ANY partial publish failure essentially impossible with parallel mode, defeating the entire purpose of the checkpoint/recovery system.
-
-### Real-World Scenario
-
-Publishing all packages in a monorepo after one package was already published:
-
-1. **Initial State**: Package `common-config` already published to npm as v1.1.36, working branch has v1.1.37-dev.0
-2. **Attempt 1**: Run `kodrdriv tree publish --parallel` → `common-config` fails (expected - already published), all 15 dependent packages skipped
-3. **Recovery Attempt**: Run `kodrdriv tree publish --parallel --mark-completed "common-config" --continue`
-4. **Expected**: System marks `common-config` as completed, proceeds to level 2 packages (`logging`, `docs-template`)
-5. **Actual**: All 15 packages remain perpetually skipped, execution completes immediately without attempting any publishes
-
-## Root Cause Analysis
-
-### The Bug
-
-The issue was in two places where checkpoint state was loaded without reassessing which packages could now proceed:
-
-#### 1. `DynamicTaskPool.loadCheckpoint()` (src/execution/DynamicTaskPool.ts)
-
-```typescript
-// BEFORE (BROKEN)
-private async loadCheckpoint(): Promise<void> {
-    const checkpoint = await this.checkpointManager.load();
-    // ... restore metadata ...
-
-    this.state = checkpoint.state;  // Directly assigns checkpoint state
-
-    // Clear running state
-    for (const running of this.state.running) {
-        this.state.pending.push(running.name);
-    }
-    this.state.running = [];
-}
-```
-
-**Problem**: When the checkpoint state is directly assigned, packages in the `skipped` array remain there. The subsequent `updateReadyQueue()` call only checks packages in the `pending` array, so skipped packages are never reassessed even though their dependencies might now be complete.
-
-#### 2. `RecoveryManager.updateReadyState()` (src/execution/RecoveryManager.ts)
-
-```typescript
-// BEFORE (BROKEN)
-private updateReadyState(): void {
-    // Move packages from pending to ready if dependencies met
-    const nowReady: string[] = [];
-
-    for (const pkg of this.checkpoint.state.pending) {  // Only checks pending!
-        const deps = this.graph.edges.get(pkg) || new Set();
-        const allDepsCompleted = Array.from(deps).every(dep =>
-            this.checkpoint.state.completed.includes(dep)
-        );
-
-        if (allDepsCompleted) {
-            nowReady.push(pkg);
-        }
-    }
-
-    // Move to ready
-    for (const pkg of nowReady) {
-        this.checkpoint.state.pending = this.checkpoint.state.pending.filter(p => p !== pkg);
-        this.checkpoint.state.ready.push(pkg);
-    }
-}
-```
-
-**Problem**: This method only evaluated packages in the `pending` state. Packages that were previously skipped due to failed dependencies were never reevaluated, even after their dependencies were marked as completed via `--mark-completed`.
-
-### Execution Flow Showing the Bug
-
-```
-Initial Run:
-  common-config → FAILS
-  [Dependency checker blocks all dependents]
-  → logging, docs-template, core, ... → all moved to SKIPPED
-
-User runs --mark-completed "common-config":
-  RecoveryManager.markCompleted():
-    ✓ Adds common-config to completed array
-    ✓ Calls updateReadyState()
-    ✓ updateReadyState() only checks pending array (empty!)
-    ✓ Skipped packages never reevaluated
-    ✓ Checkpoint saved with skipped=[logging, docs-template, ...]
-
-User runs --continue:
-  DynamicTaskPool.loadCheckpoint():
-    ✓ Loads checkpoint
-    ✓ this.state = checkpoint.state (skipped array restored!)
-    ✓ Calls updateReadyQueue()
-    ✓ updateReadyQueue() only checks pending array (empty!)
-    ✓ Skipped packages never reevaluated
-
-  Main execution loop:
-    ✓ pending.length === 0
-    ✓ ready.length === 0
-    ✓ runningTasks.size === 0
-    ✓ isComplete() returns true
-    ✓ Execution exits immediately
-
-  Result: "✅ Published (1): common-config, ⊘ Skipped (15): [all others]"
-```
-
-## The Fix
-
-### 1. Dynamic Dependency Resolution in `DynamicTaskPool.loadCheckpoint()`
-
-Added logic to re-evaluate skipped packages after loading checkpoint:
-
-```typescript
-// AFTER (FIXED)
-private async loadCheckpoint(): Promise<void> {
-    const checkpoint = await this.checkpointManager.load();
-    // ... restore metadata ...
-
-    this.state = checkpoint.state;
-
-    // Clear running state
-    for (const running of this.state.running) {
-        this.state.pending.push(running.name);
-    }
-    this.state.running = [];
-
-    // CRITICAL FIX: Re-evaluate skipped packages
-    // After loading checkpoint (especially with --mark-completed), packages that were
-    // skipped due to failed dependencies might now be eligible to run if those
-    // dependencies are now completed. Move them back to pending for reassessment.
-    const unblocked: string[] = [];
-    for (const packageName of this.state.skipped) {
-        // Check if all dependencies are now completed
-        const dependencies = this.graph.edges.get(packageName) || new Set();
-        const allDepsCompleted = Array.from(dependencies).every(dep =>
-            this.state.completed.includes(dep) || this.state.skippedNoChanges.includes(dep)
-        );
-
-        // Check if any dependencies are still failed
-        const anyDepsFailed = Array.from(dependencies).some(dep =>
-            this.state.failed.some(f => f.name === dep)
-        );
-
-        if (allDepsCompleted && !anyDepsFailed) {
-            unblocked.push(packageName);
-        }
-    }
-
-    // Move unblocked packages back to pending
-    if (unblocked.length > 0) {
-        this.logger.info(`✓ Unblocked ${unblocked.length} package(s): ${unblocked.join(', ')}`);
-        for (const packageName of unblocked) {
-            this.state.skipped = this.state.skipped.filter(p => p !== packageName);
-            this.state.pending.push(packageName);
-        }
-    }
-}
-```
-
-### 2. Enhanced `RecoveryManager.updateReadyState()`
-
-Modified to check skipped packages first, then move eligible ones back to pending:
-
-```typescript
-// AFTER (FIXED)
-private updateReadyState(): void {
-    // CRITICAL FIX: First, re-evaluate skipped packages
-    // Packages that were skipped due to failed dependencies might now be eligible
-    // to run if those dependencies have been completed (e.g., via --mark-completed)
-    const unblocked: string[] = [];
-    for (const pkg of this.checkpoint.state.skipped) {
-        const deps = this.graph.edges.get(pkg) || new Set();
-        const allDepsCompleted = Array.from(deps).every(dep =>
-            this.checkpoint.state.completed.includes(dep) ||
-            this.checkpoint.state.skippedNoChanges.includes(dep)
-        );
-
-        // Check if any dependencies are still failed
-        const anyDepsFailed = Array.from(deps).some(dep =>
-            this.checkpoint.state.failed.some(f => f.name === dep)
-        );
-
-        if (allDepsCompleted && !anyDepsFailed) {
-            unblocked.push(pkg);
-        }
-    }
-
-    // Move unblocked packages back to pending
-    for (const pkg of unblocked) {
-        this.checkpoint.state.skipped = this.checkpoint.state.skipped.filter(p => p !== pkg);
-        this.checkpoint.state.pending.push(pkg);
-        this.logger.info(`↻ ${pkg} unblocked (dependencies now satisfied)`);
-    }
-
-    // Move packages from pending to ready if dependencies met
-    const nowReady: string[] = [];
-
-    for (const pkg of this.checkpoint.state.pending) {
-        const deps = this.graph.edges.get(pkg) || new Set();
-        const allDepsCompleted = Array.from(deps).every(dep =>
-            this.checkpoint.state.completed.includes(dep) ||
-            this.checkpoint.state.skippedNoChanges.includes(dep)
-        );
-
-        if (allDepsCompleted) {
-            nowReady.push(pkg);
-        }
-    }
-
-    for (const pkg of nowReady) {
-        this.checkpoint.state.pending = this.checkpoint.state.pending.filter(p => p !== pkg);
-        this.checkpoint.state.ready.push(pkg);
-    }
-}
-```
-
-### 3. Improved User Feedback in `markCompleted()`
-
-Enhanced to show what was unblocked:
-
-```typescript
-// Update ready queue and count what got unblocked
-const beforeSkipped = this.checkpoint.state.skipped.length;
-const beforeReady = this.checkpoint.state.ready.length;
-
-this.updateReadyState();
-
-const afterSkipped = this.checkpoint.state.skipped.length;
-const afterReady = this.checkpoint.state.ready.length;
-
-const unblockedCount = beforeSkipped - afterSkipped;
-const newReadyCount = afterReady - beforeReady;
-
-// Save checkpoint
-await this.saveCheckpoint();
-
-this.logger.info('State updated successfully');
-
-if (unblockedCount > 0) {
-    this.logger.info(`✓ Unblocked ${unblockedCount} package(s)`);
-}
-if (newReadyCount > 0) {
-    this.logger.info(`✓ ${newReadyCount} package(s) ready to execute`);
-}
-if (unblockedCount === 0 && newReadyCount === 0 && this.checkpoint.state.skipped.length > 0) {
-    this.logger.warn(`⚠️  No packages unblocked. ${this.checkpoint.state.skipped.length} packages still blocked by dependencies.`);
-    this.logger.warn('   Use --status to see what\'s blocking them.');
-}
-```
-
-### 4. Enhanced Status Display
-
-Improved `showStatus()` to show detailed dependency states:
-
-```typescript
-// Skipped packages with dependency details
-if (skipped > 0) {
-    lines.push('🔒 Blocked Packages (dependency issues):');
-    for (const pkgName of this.checkpoint.state.skipped) {
-        const deps = this.graph.edges.get(pkgName) || new Set();
-        const depStatus = Array.from(deps).map(dep => {
-            if (this.checkpoint.state.completed.includes(dep) ||
-                this.checkpoint.state.skippedNoChanges.includes(dep)) {
-                return `${dep} ✓`;
-            } else if (this.checkpoint.state.failed.some(f => f.name === dep)) {
-                return `${dep} ❌`;
-            } else if (this.checkpoint.state.running.some(r => r.name === dep)) {
-                return `${dep} ⏳`;
-            } else if (this.checkpoint.state.skipped.includes(dep)) {
-                return `${dep} 🔒`;
-            } else if (this.checkpoint.state.pending.includes(dep) ||
-                       this.checkpoint.state.ready.includes(dep)) {
-                return `${dep} ⏳`;
-            } else {
-                return `${dep} ❓`;
-            }
-        });
-
-        lines.push(`  • ${pkgName}`);
-        if (depStatus.length > 0) {
-            lines.push(`    Dependencies: ${depStatus.join(', ')}`);
-        }
-    }
-    lines.push('');
-    lines.push('Legend: ✓ = complete, ❌ = failed, ⏳ = pending/running, 🔒 = blocked');
-    lines.push('');
-}
-
-// Ready to execute
-if (this.checkpoint.state.ready.length > 0) {
-    lines.push('⏳ Ready to Execute:');
-    for (const pkgName of this.checkpoint.state.ready) {
-        const deps = this.graph.edges.get(pkgName) || new Set();
-        if (deps.size === 0) {
-            lines.push(`  • ${pkgName} (no dependencies)`);
-        } else {
-            const depList = Array.from(deps).join(', ');
-            lines.push(`  • ${pkgName} (depends on: ${depList})`);
-        }
-    }
-    lines.push('');
-}
-```
-
-## Test Coverage
-
-Added comprehensive test cases in `tests/execution/RecoveryManager.test.ts`:
-
-### Test Case 1: Basic Unblocking
-```typescript
-it('should unblock skipped packages when dependencies are marked completed', async () => {
-    // Simulates: A fails → B,C,D skipped → A marked complete → B,C move to ready, D stays blocked
-    // Verifies packages with satisfied dependencies are immediately unblocked
-});
-```
-
-### Test Case 2: Multi-Level Dependencies
-```typescript
-it('should handle multi-level dependency unblocking', async () => {
-    // Tests cascading unblock: A → B → C
-    // When A completes, B should be ready
-    // When B completes, C should be ready
-});
-```
-
-### Test Case 3: Partial Dependency Satisfaction
-```typescript
-it('should not unblock packages if some dependencies still failed', async () => {
-    // Ensures packages stay blocked if ANY dependency is still failed
-    // C depends on A and B, A completes but B is failed → C stays blocked
-});
-```
-
-All 23 tests pass, including the 3 new critical test cases.
-
-## Expected Behavior After Fix
-
-### Scenario: Fjell Monorepo (16 packages)
-
-```bash
-# Initial attempt - common-config already published
-$ kodrdriv tree publish --parallel --model "gpt-5-mini"
-❌ @fjell/common-config (already published)
-⊘ Skipped due to dependencies (15): [all others]
-
-# Recovery with fix
-$ kodrdriv tree publish --parallel --mark-completed "common-config" --continue
-✓ Marked @fjell/common-config as completed
-↻ @fjell/logging unblocked (dependencies now satisfied)
-↻ @fjell/docs-template unblocked (dependencies now satisfied)
-✓ Unblocked 2 package(s)
-✓ 2 package(s) ready to execute
-
-📦 Executing 2 packages in parallel
-[1/15] ✅ @fjell/logging
-[2/15] ✅ @fjell/docs-template
-[3/15] ✅ @fjell/core
-[4/15] ✅ @fjell/http-api
-... continues publishing all remaining packages ...
-```
-
-### Status Output Example
-
-```bash
-$ kodrdriv tree --status-parallel
-
-═══════════════════════════════════════
-     Parallel Execution Status
-═══════════════════════════════════════
-
-Execution ID: 27ea3c44-e707-46d6-b411-bfaef689d240
-Started: 12/12/2025, 6:20:00 AM
-Last Updated: 12/12/2025, 6:21:30 AM
-
-📊 Progress:
-  Completed: 3/16 (18%)
-  Skipped (no changes): 0
-  Running:   2
-  Pending:   8
-  Failed:    0
-  Skipped (dependency failed):   3
-
-Progress: [███░░░░░░░░░░░░░░░░░] 18%
-
-🔄 Currently Running:
-  • @fjell/core (1m 23s)
-  • @fjell/http-api (45s)
-
-⏳ Ready to Execute:
-  • @fjell/registry (depends on: @fjell/core, @fjell/common-config)
-  • @fjell/lib (depends on: @fjell/core)
-
-🔒 Blocked Packages (dependency issues):
-  • @fjell/client-api
-    Dependencies: @fjell/core ⏳, @fjell/lib ⏳, @fjell/common-config ✓
-  • @fjell/sample-app
-    Dependencies: @fjell/client-api 🔒, @fjell/core ⏳
-  • @fjell/express-router
-    Dependencies: @fjell/http-api ⏳, @fjell/lib ⏳
-
-Legend: ✓ = complete, ❌ = failed, ⏳ = pending/running, 🔒 = blocked
-```
-
-## Impact
-
-### Before Fix
-- ❌ Recovery from partial failures completely broken
-- ❌ `--mark-completed` effectively useless
-- ❌ Any scenario where a package was already published blocked entire tree
-- ❌ 20+ hours wasted on manual workarounds
-
-### After Fix
-- ✅ Recovery works as designed
-- ✅ Packages unblock as soon as dependencies are satisfied
-- ✅ Clear feedback showing what was unblocked
-- ✅ Detailed status showing exactly why packages are blocked
-- ✅ Parallel publishing viable for production use
-
-## Files Modified
-
-- `src/execution/DynamicTaskPool.ts` - Added checkpoint state reassessment
-- `src/execution/RecoveryManager.ts` - Enhanced updateReadyState() and markCompleted()
-- `tests/execution/RecoveryManager.test.ts` - Added 3 critical test cases
-
-## Backward Compatibility
-
-✅ **Fully backward compatible** - No breaking changes to API or command-line interface.
-
-Existing checkpoints will automatically benefit from the fix on next `--continue` attempt.
-
-## Related Issues
-
-This fix resolves the core issue described in the user's detailed bug report, addressing:
-- ✅ Infinite loop after `--mark-completed`
-- ✅ All dependent packages remaining perpetually skipped
-- ✅ Checkpoint system defeating its own purpose
-- ✅ Impossible recovery from partial publish failures
-
-## Version
-
-Fixed in: **kodrdriv 1.2.29-dev.0**
-