@eldrforge/kodrdriv 1.2.28 → 1.2.123

package/PARALLEL-PUBLISH-QUICK-REFERENCE.md

@@ -1,375 +0,0 @@
-# Parallel Publish Quick Reference Guide
-
-## 🚨 When Parallel Publish Fails
-
-### Scenario 1: Target Branch Out of Sync
-
-**Error**: `❌ Target branch 'main' is not in sync with remote`
-
-**Solution**:
-```bash
-# Run audit to see which packages have sync issues
-kodrdriv tree publish --audit-branches
-
-# Follow the "SYNC TARGET BRANCHES" instructions, e.g.:
-cd ~/gitw/getfjell/logging
-git checkout main
-git reset --hard origin/main  # or git pull origin main if can fast-forward
-git checkout working
-
-# Repeat for each package with sync issues
-# Then retry publish
-kodrdriv tree publish --parallel --model "gpt-5-mini"
-```
-
----
-
-### Scenario 2: npm Install Race Condition
-
-**Error**: `npm error code ENOTEMPTY` or `directory not empty` during parallel publish
-
-**Solution**:
-```bash
-# Clean and reinstall in the affected package
-cd ~/gitw/getfjell/<failed-package>
-rm -rf node_modules
-npm install
-git add package-lock.json
-git commit -m "Fix lockfile after npm install"
-git push origin working
-
-# Then publish with dependency updates
-kodrdriv publish --update-deps @fjell --model "gpt-5-mini"
-```
-
----
-
-### Scenario 3: Package Failed, Need to Publish Manually
-
-**⚠️ CRITICAL**: Don't just run `kodrdriv publish` - it will skip dependency updates!
-
-**Wrong**:
-```bash
-cd ~/gitw/getfjell/cache
-kodrdriv publish --model "gpt-5-mini"
-# ❌ Publishes with OLD dependency versions
-```
-
-**Correct**:
-```bash
-cd ~/gitw/getfjell/cache
-kodrdriv publish --update-deps @fjell --model "gpt-5-mini"
-# ✅ Updates dependencies, then publishes
-```
-
----
-
-### Scenario 4: Multiple Packages Failed
-
-**Option A**: Update all dependencies, then retry
-```bash
-cd ~/gitw/getfjell
-kodrdriv tree updates --inter-project @fjell
-kodrdriv tree publish --continue
-```
-
-**Option B**: Fall back to serial mode
-```bash
-cd ~/gitw/getfjell
-kodrdriv tree publish --model "gpt-5-mini"
-# Slow but reliable
-```
-
----
-
-## 🔍 Pre-Flight Checklist
-
-Before running parallel publish:
-
-```bash
-# 1. Run enhanced audit
-kodrdriv tree publish --audit-branches
-
-# 2. Check for critical issues:
-#    - 🚨 Target branch sync issues
-#    - ⚠️  Merge conflicts
-#    - 📋 Existing PRs
-#    - ⚠️  Version consistency issues
-
-# 3. Fix all issues (follow audit output)
-
-# 4. Re-run audit to verify
-kodrdriv tree publish --audit-branches
-# Should show: "✅ All X package(s) are in good state!"
-
-# 5. Run parallel publish
-kodrdriv tree publish --parallel --model "gpt-5-mini"
-```
-
----
-
-## 📋 New Commands Reference
-
-### Update Inter-Project Dependencies
-
-```bash
-# Update dependencies in current package
-kodrdriv updates --inter-project @fjell
-
-# Update dependencies across all packages in tree
-kodrdriv tree updates --inter-project @fjell
-
-# Publish with dependency update
-kodrdriv publish --update-deps @fjell --model "gpt-5-mini"
-```
-
-### Enhanced Audit
-
-```bash
-# Run comprehensive audit (now includes target branch sync check)
-kodrdriv tree publish --audit-branches
-
-# Audit output now shows:
-# - ✅ Good State packages
-# - 🚨 Target Branch Sync Issues (NEW)
-# - ⚠️  Version Issues
-# - 🚨 CRITICAL ISSUES (conflicts, PRs, sync)
-# - 📝 RECOMMENDED WORKFLOW (step-by-step fixes)
-```
-
----
-
-## 🎯 Recommended Workflow
-
-### For Clean Releases (No Issues)
-
-```bash
-cd ~/gitw/getfjell
-
-# 1. Audit
-kodrdriv tree publish --audit-branches
-
-# 2. Parallel publish
-kodrdriv tree publish --parallel --model "gpt-5-mini"
-```
-
-### For Releases with Issues
-
-```bash
-cd ~/gitw/getfjell
-
-# 1. Audit
-kodrdriv tree publish --audit-branches
-
-# 2. Fix issues (follow numbered steps in audit output)
-# Priority order:
-#   1️⃣ SYNC TARGET BRANCHES (most critical)
-#   2️⃣ RESOLVE MERGE CONFLICTS
-#   3️⃣ FIX VERSION ISSUES
-#   4️⃣ SYNC WITH REMOTE
-#   5️⃣ PUSH LOCAL COMMITS
-
-# 3. Re-audit to verify
-kodrdriv tree publish --audit-branches
-
-# 4. Parallel publish
-kodrdriv tree publish --parallel --model "gpt-5-mini"
-```
-
-### Recovery from Failed Parallel Publish
-
-```bash
-cd ~/gitw/getfjell
-
-# Option 1: Update all deps and retry
-kodrdriv tree updates --inter-project @fjell
-kodrdriv tree publish --continue
-
-# Option 2: Manual publish with dep updates
-cd <failed-package>
-kodrdriv publish --update-deps @fjell --model "gpt-5-mini"
-
-# Option 3: Serial fallback
-kodrdriv tree publish --model "gpt-5-mini"
-```
-
----
-
-## 🔧 Troubleshooting
-
-### "All packages in good state" but parallel publish still fails
-
-This shouldn't happen with the new audit, but if it does:
-
-1. Check if main branches are EXACTLY in sync:
-   ```bash
-   cd <package>
-   git fetch origin
-   git rev-parse main
-   git rev-parse origin/main
-   # These should match exactly
-   ```
-
-2. If they don't match:
-   ```bash
-   git checkout main
-   git reset --hard origin/main
-   git checkout working
-   ```
-
-### Checkpoint shows old failures after manual fix
-
-```bash
-# Mark packages as completed
-kodrdriv tree publish --continue --mark-completed "pkg1,pkg2"
-
-# Or reset checkpoint and start fresh
-rm .kodrdriv-checkpoint.json
-kodrdriv tree publish --parallel --model "gpt-5-mini"
-```
-
-### Package published but checkpoint still shows failure
-
-This is a known issue. Workarounds:
-
-```bash
-# Option 1: Mark as completed
-kodrdriv tree publish --continue --mark-completed "<package-name>"
-
-# Option 2: Skip and continue
-kodrdriv tree publish --continue --skip-packages "<package-name>"
-```
-
----
-
-## ⚡ Performance Tips
-
-### Speed Up Audit
-
-```bash
-# Audit is now ~2-3 seconds slower per package due to target branch sync check
-# For large repos (50+ packages), this adds ~2-3 minutes
-# This is acceptable given the failures it prevents
-```
-
-### Speed Up Parallel Publish
-
-```bash
-# Pre-build all packages first (avoids build races)
-kodrdriv tree run "npm run build"
-
-# Then publish without build
-kodrdriv tree publish --parallel --model "gpt-5-mini"
-```
-
-### When to Use Serial Mode
-
-Use serial mode (`kodrdriv tree publish`) when:
-- Critical production release (can't afford failures)
-- First time publishing a new monorepo
-- Packages have complex interdependencies
-- You don't have time to babysit parallel mode
-
-Use parallel mode when:
-- Development/testing releases
-- Packages are mostly independent
-- You're available to handle failures
-- Time savings matter (30-60 min vs 60-120 min)
-
----
-
-## 📊 Success Indicators
-
-### Audit Should Show
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  Branch State Audit (16 packages)
-║  All packages on: working
-╠══════════════════════════════════════════════════════════════╣
-
-✅ Good State (16 packages):
-   @fjell/logging (v4.4.65-dev.0)
-   @fjell/common-config (v1.1.38-dev.0)
-   ...
-
-✅ All 16 package(s) are in good state!
-```
-
-### Parallel Publish Should Complete
-
-```
-📦 Executing 16 packages in parallel
-
-[1/16] ✅ @fjell/logging
-[2/16] ✅ @fjell/common-config
-...
-[16/16] ✅ @fjell/sample-app
-
-✨ Parallel execution completed in 45s
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📊 Publish Summary
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-✅ Published (16):
-   - @fjell/logging
-   - @fjell/common-config
-   ...
-
-Total time: 45s
-Success rate: 100% (16/16 packages processed)
-Peak concurrency: 4 packages
-```
-
----
-
-## 🆘 When All Else Fails
-
-```bash
-# Nuclear option: Reset everything and use serial mode
-cd ~/gitw/getfjell
-
-# 1. Sync all main branches
-for dir in */; do
-  cd "$dir"
-  git checkout main
-  git reset --hard origin/main
-  git checkout working
-  cd ..
-done
-
-# 2. Update all dependencies
-kodrdriv tree updates --inter-project @fjell
-
-# 3. Serial publish (slow but reliable)
-kodrdriv tree publish --model "gpt-5-mini"
-```
-
----
-
-## 📞 Getting Help
-
-If you encounter issues not covered here:
-
-1. Run audit with verbose output:
-   ```bash
-   kodrdriv tree publish --audit-branches --verbose
-   ```
-
-2. Check the checkpoint file:
-   ```bash
-   cat .kodrdriv-checkpoint.json | jq
-   ```
-
-3. Review the implementation report:
-   ```bash
-   cat PARALLEL-PUBLISH-FIXES-IMPLEMENTED.md
-   ```
-
-4. File an issue with:
-   - Audit output
-   - Error messages
-   - Checkpoint state
-   - Steps to reproduce
-

package/PARALLEL_EXECUTION_FIX.md

@@ -1,146 +0,0 @@
-# Parallel Execution Freeze Fix
-
-## Problem
-
-When running `kodrdriv tree publish --parallel`, the execution would freeze because:
-
-1. **Multiple child processes** were spawned (one per package)
-2. All packages were in the **same git repository** (`~gitw/calenvarek`)
-3. Each child process had its own **in-memory mutex** (SimpleMutex)
-4. In-memory mutexes **cannot coordinate across separate processes**
-5. Multiple processes tried to run git operations concurrently
-6. Git created `.git/index.lock` files, causing conflicts and hangs
-
-## Root Cause
-
-The `SimpleMutex` class in `src/util/mutex.ts` was designed for **single-process** synchronization. It uses in-memory state that cannot be shared between separate Node.js processes.
-
-When `kodrdriv tree publish --parallel` spawns child processes using `exec()`, each child process:
-- Gets its own memory space
-- Creates its own `RepositoryMutexManager` singleton
-- Has no way to coordinate with other processes
-
-## Solution
-
-Implemented a **file-based locking mechanism** in `src/util/fileLock.ts`:
-
-### Key Features
-
-1. **Cross-Process Safety**: Uses atomic file operations (`wx` flag) that work across processes
-2. **Exponential Backoff**: Retries lock acquisition with increasing delays (100ms → 2000ms max)
-3. **Stale Lock Detection**: Automatically removes locks older than 30 seconds
-4. **Automatic Cleanup**: Releases locks on process exit (normal, SIGINT, SIGTERM, uncaughtException)
-5. **Per-Repository Locking**: Creates `.git/kodrdriv.lock` file in each repository
-
-### Implementation Details
-
-#### FileLock Class
-```typescript
-class FileLock {
-    async lock(): Promise<void> {
-        // Attempts to create lock file atomically with 'wx' flag
-        // Retries with exponential backoff if file exists
-        // Detects and removes stale locks (>30 seconds old)
-    }
-
-    unlock(): void {
-        // Removes lock file
-    }
-}
-```
-
-#### RepositoryFileLockManager Class
-```typescript
-class RepositoryFileLockManager {
-    getRepositoryLock(repoPath: string): FileLock {
-        // Returns file lock for .git/kodrdriv.lock
-    }
-
-    async withGitLock<T>(repoPath, operation, operationName): Promise<T> {
-        // Acquires lock, executes operation, releases lock
-    }
-}
-```
-
-### Changes Made
-
-1. **Created** `src/util/fileLock.ts` - New file-based locking implementation
-2. **Modified** `src/util/gitMutex.ts` - Now uses FileLock instead of SimpleMutex
-3. **No Breaking Changes** - API remains the same, only implementation changed
-
-### How It Works
-
-```
-Parent Process (kodrdriv tree publish --parallel)
-├── Spawns: kodrdriv publish [git-tools]
-│   └── Tries to acquire .git/kodrdriv.lock
-│       ✓ Success! Executes git operations
-│       ✓ Releases lock
-├── Spawns: kodrdriv publish [ai-service]
-│   └── Tries to acquire .git/kodrdriv.lock
-│       ⏳ Waits... lock file exists
-│       ✓ Previous process released lock
-│       ✓ Acquires lock, executes, releases
-├── Spawns: kodrdriv publish [github-tools]
-│   └── (same pattern)
-└── Spawns: kodrdriv publish [kodrdriv]
-    └── (same pattern)
-```
-
-### Testing
-
-- ✅ All 283 existing tests pass
-- ✅ Build succeeds with no linter errors
-- ✅ Lock files are automatically cleaned up on exit
-- ✅ Stale locks (>30s) are automatically removed
-
-## Usage
-
-No changes needed! The fix is transparent:
-
-```bash
-# This now works without freezing
-kodrdriv tree publish --parallel
-
-# Same for other commands that use git operations
-kodrdriv tree commit --parallel
-```
-
-## Lock File Location
-
-Lock files are created at:
-```
-/path/to/repo/.git/kodrdriv.lock
-```
-
-These files:
-- Are automatically created/removed
-- Are gitignored (in .git directory)
-- Are safe to manually delete if stale
-- Contain diagnostic info (PID, timestamp, hostname)
-
-## Performance Impact
-
-- **Minimal overhead**: File operations are fast (microseconds)
-- **Better than deadlock**: Small delay is better than infinite freeze
-- **Automatic backoff**: Reduces contention with exponential delays
-- **Stale lock cleanup**: Prevents indefinite blocking
-
-## Future Improvements
-
-Potential enhancements:
-1. Make lock timeout configurable
-2. Add lock health monitoring/metrics
-3. Implement lock priority/queueing
-4. Add verbose lock acquisition logging
-
-## Verification
-
-To verify the fix works:
-```bash
-cd ~gitw/calenvarek/kodrdriv
-npm run build
-kodrdriv tree publish --parallel --dry-run
-```
-
-The parallel execution should now proceed without freezing.