@eldrforge/kodrdriv 1.2.29 → 1.2.124

package/PUBLISH_IMPROVEMENTS_IMPLEMENTED.md

@@ -1,294 +0,0 @@
-# Kodrdriv Publish Improvements - Implementation Summary
-
-**Date:** December 11, 2025
-
-## Overview
-
-This document summarizes the improvements made to kodrdriv's publish workflow based on feedback from a catastrophic parallel publish failure in another project. The improvements focus on better error handling, user feedback, and git operations.
-
-## Critical Issues Addressed
-
-### 1. ✅ PR Already Exists Error (P0 - Blocker)
-
-**Problem:** When a PR already existed from a previous run, the publish command would:
-- Run expensive build operations
-- Generate release notes with OpenAI (27+ seconds, API costs)
-- Push changes
-- THEN fail with "PR already exists" error
-
-**Solution Implemented:**
-
-Modified `github-tools/src/github.ts` to make PR creation more resilient:
-
-```typescript
-// Enhanced error handling in createPullRequest()
-if (existingPR && existingPR.base.ref === base) {
-    logger.info(`♻️  Found and reusing existing PR #${existingPR.number} (created after initial check)`);
-    logger.info(`   URL: ${existingPR.html_url}`);
-    logger.info(`   This can happen when PRs are created in parallel or from a previous failed run`);
-    return existingPR;
-}
-```
-
-**Impact:**
-- No more wasted build time or API costs
-- Automatically resumes existing PRs
-- Better handling of parallel publish operations
-
-### 2. ✅ Silent Long Operations (P0 - Critical UX)
-
-**Problem:** During 27-second OpenAI API call, there was zero terminal output, making users think the command was frozen.
-
-**Solution Implemented:**
-
-Added progress indicator to `ai-service/src/ai.ts`:
-
-```typescript
-// Progress indicator that updates every 5 seconds
-let progressIntervalId: NodeJS.Timeout | null = null;
-progressIntervalId = setInterval(() => {
-    const elapsed = Math.round((Date.now() - startTime) / 1000);
-    logger.info('   ⏳ Waiting for response... %ds', elapsed);
-}, 5000);
-```
-
-**Example Output:**
-```
-🤖 Making request to OpenAI
-   Model: gpt-5-mini | Reasoning: low
-   Request size: 104.93 KB (107,446 bytes)
-   ⏳ Waiting for response... 5s
-   ⏳ Waiting for response... 10s
-   ⏳ Waiting for response... 15s
-   ⏳ Waiting for response... 20s
-   ⏳ Waiting for response... 25s
-   Response size: 7.22 KB (7,394 bytes)
-   Time: 27.2s
-   Token usage: 25,089 prompt + 1,926 completion = 27,015 total
-```
-
-**Impact:**
-- Users know the command is still running
-- Clear indication of progress
-- No more "is it frozen?" confusion
-
-### 3. ✅ Git Rebase Errors (P1 - Configuration Conflicts)
-
-**Problem:** `git pull origin branch --no-edit` conflicted with users who have `pull.rebase = true` in their git config, causing "Cannot rebase onto multiple branches" errors.
-
-**Solution Implemented:**
-
-Replaced all `git pull` commands with explicit `git fetch` + `git merge`:
-
-**Files Updated:**
-- `kodrdriv/src/commands/publish.ts` (2 occurrences)
-- `kodrdriv/src/commands/development.ts` (1 occurrence)
-
-```typescript
-// Old (problematic):
-await run(`git pull origin ${branch} --no-edit`);
-
-// New (explicit and config-independent):
-await run(`git fetch origin ${branch}`);
-await run(`git merge origin/${branch} --no-ff --no-edit`);
-```
-
-**Impact:**
-- Works with any git config (`pull.rebase = true` or `false`)
-- No more mysterious rebase errors
-- Explicit merge behavior
-
-### 4. ✅ Better Skip Messages (P1 - UX)
-
-**Problem:** Skip messages were cryptic:
-```
-Skipping publish: Only version changed in package.json (plus lockfile).
-```
-
-**Solution Implemented:**
-
-Enhanced skip messages in `kodrdriv/src/commands/publish.ts`:
-
-```typescript
-return {
-    necessary: false,
-    reason: `No meaningful changes detected:
-   • Current version: ${currentVersion}
-   • Target branch version: ${targetVersion}
-   • Only package.json version field differs
-
-   To force republish: Add meaningful code changes or use --force (not yet implemented)`
-};
-```
-
-**Example Output:**
-```
-⏭️  Skipping publish: No meaningful changes detected:
-   • Current version: 0.0.133-dev.0
-   • Target branch version: 0.0.132
-   • Only package.json version field differs
-
-   To force republish: Add meaningful code changes or use --force (not yet implemented)
-```
-
-**Impact:**
-- Clear explanation of why skipped
-- Shows version information
-- Provides actionable next steps
-
-### 5. ✅ Enhanced Summary (P1 - UX)
-
-**Problem:** Tree publish summary was minimal and didn't provide enough context after execution.
-
-**Solution Implemented:**
-
-Complete rewrite of `formatParallelResult()` in `kodrdriv/src/execution/TreeExecutionAdapter.ts`:
-
-**Example Output:**
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📊 Publish Summary
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-✅ Published (2):
-   - @project/lib
-   - @project/hooks
-
-⏭️  Skipped (6) - no code changes:
-   - @project/interfaces
-   - @project/core
-   - @project/calc
-   - @project/client-api
-   - @project/cache
-   - @project/providers
-
-❌ Failed (1):
-   - @project/api
-
-⊘ Skipped due to dependencies (2):
-   - @project/ullr
-   - @project/e2e
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Total time: 8m 34s
-Success rate: 75% (8/11 packages processed)
-Peak concurrency: 4 packages
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-📋 Next steps:
-1. Review the errors above for each failed package
-2. Fix the issues in the failed packages
-3. Retry the publish command
-
-Note: Once failed packages are fixed, their dependent packages will also be published.
-```
-
-**Impact:**
-- Clear categorization of results
-- Shows all packages and their status
-- Time and success rate metrics
-- Actionable next steps
-
-## Features Already Implemented
-
-### 6. ✅ Dry Run Mode
-
-**Status:** Already implemented in tree commands
-
-The feedback suggested adding `--dry-run`, but it's already fully implemented:
-- Propagates to all subcommands
-- Shows preview of what would be published
-- Prevents actual execution
-
-**Usage:**
-```bash
-kodrdriv tree publish --parallel --dry-run
-```
-
-### 7. ✅ Resume/Continue from Failure
-
-**Status:** Already implemented via multiple options
-
-The feedback suggested adding `--continue-from`, but equivalent functionality exists:
-- `--skip <packages>` - Skip specific packages and their dependents
-- `--retry-failed` - Retry all previously failed packages
-- `--skip-failed` - Skip failed packages and continue with remaining
-- `--mark-completed <packages>` - Mark packages as completed for recovery
-
-**Usage:**
-```bash
-# Skip a problematic package
-kodrdriv tree publish --skip lib
-
-# Retry after fixing failures
-kodrdriv tree publish --retry-failed
-
-# Mark a package as completed and continue
-kodrdriv tree publish --mark-completed lib
-```
-
-## Testing
-
-All changes have been compiled and tested:
-
-```bash
-# ai-service
-cd ~gitw/calenvarek/ai-service
-npm run build  # ✅ Success
-
-# github-tools
-cd ~gitw/calenvarek/github-tools
-npm run build  # ✅ Success
-
-# kodrdriv
-cd ~gitw/calenvarek/kodrdriv
-npm run build  # ✅ Success
-```
-
-No linter errors detected in any of the modified files.
-
-## Files Modified
-
-### ai-service
-- `src/ai.ts` - Added progress indicator for long-running OpenAI API calls
-
-### github-tools
-- `src/github.ts` - Enhanced PR creation error handling to reuse existing PRs
-
-### kodrdriv
-- `src/commands/publish.ts` - Fixed git sync, improved skip messages
-- `src/commands/development.ts` - Fixed git sync
-- `src/execution/TreeExecutionAdapter.ts` - Enhanced summary formatting
-
-## Impact Summary
-
-| Issue | Priority | Status | Impact |
-|-------|----------|--------|--------|
-| PR Already Exists | P0 | ✅ Fixed | Saves build time and API costs, auto-resumes |
-| Silent Long Operations | P0 | ✅ Fixed | Users know command is running, eliminates confusion |
-| Git Rebase Errors | P1 | ✅ Fixed | Works with any git config, no more errors |
-| Better Skip Messages | P1 | ✅ Fixed | Clear explanations with version info and next steps |
-| Enhanced Summary | P1 | ✅ Fixed | Complete view of results with metrics and guidance |
-| Dry Run Mode | P2 | ✅ Exists | Already fully implemented |
-| Resume from Failure | P2 | ✅ Exists | Multiple options available |
-
-## Recommendations for Future Improvements
-
-Based on the feedback document, these could be considered for future releases:
-
-1. **Cost Estimation** - Show estimated API costs before running expensive operations
-2. **Interactive Prompts** - Add confirmation prompts for expensive operations in non-sendit mode
-3. **Parallel Progress Dashboard** - Real-time dashboard showing status of all packages during parallel execution
-4. **--force flag** - Force republish even when no code changes detected
-
-## Conclusion
-
-All critical and high-priority issues from the feedback have been addressed. The kodrdriv publish system now provides:
-- ✅ Better error recovery (auto-resume existing PRs)
-- ✅ Better user feedback (progress indicators during long operations)
-- ✅ Better reliability (git operations work with any config)
-- ✅ Better UX (clear skip messages and comprehensive summaries)
-
-The changes maintain backward compatibility while significantly improving the user experience during publish operations.
-

package/RECOVERY-FIXES.md

@@ -1,72 +0,0 @@
-# Recovery System Fixes
-
-## Issues Fixed
-
-### 1. Checkpoint Deleted When Packages Are Skipped
-
-**Problem**: When using `--mark-completed` to mark a failed package as done, the system would delete the checkpoint even though dependent packages were skipped. This resulted in:
-- Misleading "All X packages completed successfully! 🎉" message when packages were actually skipped
-- Lost checkpoint making it impossible to continue the execution
-- No way to resume and complete the skipped packages
-
-**Root Cause**: In `DynamicTaskPool.ts`, the cleanup logic only checked for failed packages, not skipped packages:
-
-```typescript
-// Before (WRONG)
-if (this.state.failed.length === 0) {
-    await this.checkpointManager.cleanup();  // Deletes checkpoint
-}
-
-// After (FIXED)
-const allCompleted = this.state.failed.length === 0 && this.state.skipped.length === 0;
-if (allCompleted) {
-    await this.checkpointManager.cleanup();
-}
-```
-
-**Fix**: Modified `src/execution/DynamicTaskPool.ts` to preserve the checkpoint when packages are skipped, and updated `src/execution/TreeExecutionAdapter.ts` to show the correct message when packages are skipped.
-
-### 2. Inconsistent Package Identifier Format
-
-**Problem**: The `--mark-completed` option required NPM package names (e.g., `"@eldrforge/git-tools"`), while `--start-from` accepted directory names (e.g., `"git-tools"`). This was confusing and inconsistent.
-
-**Fix**: Updated `src/execution/RecoveryManager.ts` to accept both directory names and package names for `--mark-completed`, matching the behavior of `--start-from`:
-
-```typescript
-// Now both work:
-kodrdriv tree publish --continue --mark-completed "git-tools"
-kodrdriv tree publish --continue --mark-completed "@eldrforge/git-tools"
-```
-
-The system will:
-1. Try exact package name match first
-2. Fall back to directory name match
-3. Provide helpful error with available packages if not found
-
-**Updated Files**:
-- `src/execution/RecoveryManager.ts` - Added `resolvePackageName()` helper and updated `markCompleted()`
-- `src/arguments.ts` - Updated help text
-- `src/ui/ProgressFormatter.ts` - Updated recovery guidance to use directory names
-
-## Testing
-
-All existing tests pass, including the specific RecoveryManager tests.
-
-## Usage
-
-Now you can use directory names (much simpler):
-
-```bash
-# Start a parallel publish
-kodrdriv tree publish --parallel
-
-# If git-tools fails due to merge conflict, fix it manually, then:
-kodrdriv tree publish --continue --mark-completed "git-tools"
-
-# The remaining packages (ai-service, github-tools, kodrdriv) will now execute
-```
-
-The system will:
-1. Keep the checkpoint if packages are skipped
-2. Show accurate status messages
-3. Allow you to continue execution to complete the skipped packages

package/SUBMODULE-LOCK-FIX.md

@@ -1,132 +0,0 @@
-# Git Submodule Lock File Fix
-
-## Problem
-
-The file-based lock mechanism used to prevent concurrent git operations was failing when used with git submodules. The issue occurred because:
-
-1. In regular git repositories, `.git` is a directory
-2. In git submodules, `.git` is a file containing a `gitdir:` reference pointing to the actual git directory
-3. The code assumed `.git` was always a directory and tried to create lock files in `.git/kodrdriv.lock`
-4. This caused `ENOTDIR` errors when operating on submodules
-
-## Example Submodule Structure
-
-```
-my-submodule/
-├── .git              # FILE (not directory) containing: "gitdir: ../.git/modules/my-submodule"
-├── src/
-└── package.json
-
-parent-repo/
-└── .git/
-    └── modules/
-        └── my-submodule/  # Actual git directory for the submodule
-            ├── HEAD
-            ├── refs/
-            └── objects/
-```
-
-## Solution
-
-Modified `src/util/fileLock.ts` to handle both regular repositories and submodules:
-
-### Key Changes
-
-1. **Added `resolveGitDirectory()` method** that:
-   - Checks if `.git` is a directory (regular repo) or file (submodule)
-   - If it's a file, reads and parses the `gitdir:` reference
-   - Resolves the gitdir path (handles both relative and absolute paths)
-   - Returns the actual git directory path where locks can be created
-
-2. **Updated `getRepositoryLock()` method** to:
-   - Use `resolveGitDirectory()` instead of assuming `.git` is a directory
-   - Create lock files in the resolved git directory
-   - Log the actual lock path for debugging
-
-### Code Implementation
-
-```typescript
-private resolveGitDirectory(repoPath: string): string {
-    const gitPath = path.join(repoPath, '.git');
-
-    try {
-        const stat = fs.statSync(gitPath);
-
-        if (stat.isDirectory()) {
-            // Regular git repository
-            return gitPath;
-        } else if (stat.isFile()) {
-            // Git submodule - .git is a file with format: gitdir: <path>
-            const gitFileContent = fs.readFileSync(gitPath, 'utf-8').trim();
-            const match = gitFileContent.match(/^gitdir:\s*(.+)$/);
-
-            if (match && match[1]) {
-                // Resolve the gitdir path (it's relative to the repo path)
-                const gitDirPath = path.resolve(repoPath, match[1]);
-                this.logger.debug(`Resolved submodule gitdir: ${gitDirPath}`);
-
-                // Ensure the git directory exists
-                if (!fs.existsSync(gitDirPath)) {
-                    throw new Error(`Submodule git directory does not exist: ${gitDirPath}`);
-                }
-
-                return gitDirPath;
-            }
-
-            throw new Error(`Invalid .git file format in ${gitPath}: ${gitFileContent}`);
-        }
-    } catch (error: any) {
-        // Check if error is from statSync (file doesn't exist)
-        if (error.code === 'ENOENT') {
-            throw new Error(`No .git directory or file found in ${repoPath}`);
-        }
-        throw new Error(`Failed to resolve git directory for ${repoPath}: ${error.message}`);
-    }
-
-    throw new Error(`No .git directory or file found in ${repoPath}`);
-}
-```
-
-## Testing
-
-Comprehensive test suite added in `tests/fileLock.test.ts` covering:
-
-1. **Basic lock operations**
-   - Acquire and release locks
-   - Block concurrent lock acquisition
-   - Handle stale locks
-
-2. **Regular repository support**
-   - Create locks in `.git` directory
-
-3. **Submodule support** (NEW)
-   - Handle `.git` file with `gitdir:` reference
-   - Resolve relative gitdir paths
-   - Create locks in the actual git directory
-   - Proper error handling for missing submodule directories
-   - Proper error handling for invalid `.git` file format
-
-4. **Lock manager functionality**
-   - Execute operations under lock
-   - Release locks on operation failure
-   - Serialize multiple operations on same repo
-
-All 12 tests pass successfully with 86%+ coverage on the fileLock module.
-
-## Impact
-
-This fix enables kodrdriv to work correctly in monorepo setups where packages are organized as git submodules, such as:
-
-- Multi-repository projects using git submodules for shared libraries
-- Projects with external dependencies included as submodules
-- Monorepos with complex submodule hierarchies
-
-The fix maintains backward compatibility with regular git repositories while adding robust support for submodules.
-
-## Related Files
-
-- `src/util/fileLock.ts` - Core fix implementation
-- `tests/fileLock.test.ts` - Comprehensive test suite
-- `src/util/gitMutex.ts` - Uses RepositoryFileLockManager
-- `src/commands/publish.ts` - Uses git locks during publish operations
-