@eldrforge/kodrdriv 1.2.26 → 1.2.28

package/ALREADY-PUBLISHED-PACKAGES-FIX.md

@@ -0,0 +1,264 @@
+# Already-Published Packages Fix
+
+## Summary
+
+Fixed critical issues preventing kodrdriv from handling monorepos with already-published packages on npm. The tool now intelligently checks npm registry state, handles tag conflicts gracefully, and provides clear recovery options.
+
+## Issues Fixed
+
+### 1. ✅ No NPM Registry Version Checking
+
+**Before**: Tool blindly attempted to publish everything without checking what's already on npm.
+
+**After**:
+- Added `getNpmPublishedVersion()` utility to query npm registry
+- Added `isVersionPublishedOnNpm()` to check specific versions
+- Added `getTagInfo()` to analyze git tags
+
+### 2. ✅ Hard Failure on Existing Tags
+
+**Before**: Threw error immediately when tag exists: `"Tag vX.Y.Z already exists. Please choose a different version or delete the existing tag."`
+
+**After**: Smart analysis with actionable recovery:
+```
+⚠️  Tag v4.4.72 already exists
+
+📊 Situation Analysis:
+   • Tag v4.4.72 exists (commit: 5b84859b)
+   • npm registry version: 4.4.70
+   • This suggests a previous publish attempt failed after creating the tag
+
+🔧 Recovery Options:
+   1. Force republish (delete tag and retry):
+      kodrdriv publish --force-republish
+   2. Skip this version and bump:
+      npm version patch && kodrdriv publish
+   3. Manually delete tag:
+      git tag -d v4.4.72
+      git push origin :refs/tags/v4.4.72
+```
+
+### 3. ✅ Skip Already-Published Packages
+
+**Before**: Tried to publish packages that are already at target version on npm.
+
+**After**:
+```bash
+kodrdriv publish --skip-already-published
+```
+
+When version is already on npm:
+```
+✓ Version 4.4.72 is already published on npm
+⊘ Skipping publish - package is already at target version
+
+💡 If you need to republish:
+   1. Bump version: npm version patch (or minor/major)
+   2. Re-run: kodrdriv publish
+```
+
+### 4. ✅ Force Republish Flag
+
+**Before**: No way to override and force past tag conflicts.
+
+**After**:
+```bash
+kodrdriv publish --force-republish
+```
+
+Automatically:
+- Deletes local tag
+- Deletes remote tag
+- Continues with publish
+
+## New Command-Line Flags
+
+### `--skip-already-published`
+Skip packages where the working version matches the npm published version.
+
+**Use Case**: Publishing multiple packages in a tree where some are already up-to-date.
+
+```bash
+# Individual package
+kodrdriv publish --skip-already-published
+
+# Tree publish
+kodrdriv tree publish --parallel --skip-already-published
+```
+
+### `--force-republish`
+Delete existing git tags and force republish even if tag exists.
+
+**Use Case**: Recovery from failed publish attempts that created tags but didn't complete npm publish.
+
+```bash
+# Force past tag conflicts
+kodrdriv publish --force-republish
+
+# Can combine with other flags
+kodrdriv tree publish --parallel --force-republish --model "gpt-5-mini"
+```
+
+## Implementation Details
+
+### New Utility Functions (`src/util/general.ts`)
+
+```typescript
+// Query npm for published version
+export const getNpmPublishedVersion = async (packageName: string): Promise<string | null>
+
+// Check if specific version exists on npm
+export const isVersionPublishedOnNpm = async (packageName: string, version: string): Promise<boolean>
+
+// Get detailed tag information
+export const getTagInfo = async (tagName: string): Promise<{ exists: boolean; commit?: string; version?: string } | null>
+```
+
+### Enhanced Tag Conflict Logic (`src/commands/publish.ts`)
+
+The tag existence check now:
+1. Checks if tag exists locally
+2. Queries npm for package version
+3. Compares states to determine situation:
+   - **Tag exists + npm has it**: Skip (already published)
+   - **Tag exists + npm doesn't**: Offer recovery options
+   - **No conflicts**: Proceed normally
+
+### Type Updates
+
+Added to `PublishConfig` type:
+- `skipAlreadyPublished?: boolean`
+- `forceRepublish?: boolean`
+
+## Real-World Usage
+
+### Scenario 1: Package Already Published
+
+```bash
+cd ~/gitw/getfjell/common-config
+kodrdriv publish --model "gpt-5-mini"
+
+# Output:
+✓ Version 1.1.36 is already published on npm
+⊘ Skipping publish - package is already at target version
+```
+
+### Scenario 2: Failed Publish Left Orphaned Tag
+
+```bash
+cd ~/gitw/getfjell/core
+kodrdriv publish --model "gpt-5-mini"
+
+# Output:
+⚠️  Tag v4.4.72 already exists
+📊 Situation Analysis:
+   • Tag v4.4.72 exists (commit: 5b84859b)
+   • npm registry version: 4.4.70
+   • This suggests a previous publish attempt failed after creating the tag
+
+# Solution:
+kodrdriv publish --force-republish --model "gpt-5-mini"
+
+# Output:
+🔄 Force republish enabled - deleting existing tag...
+✓ Deleted local tag v4.4.72
+✓ Deleted remote tag v4.4.72
+✓ Tag deleted, continuing with publish...
+```
+
+### Scenario 3: Tree Publish with Mixed State
+
+```bash
+cd ~/gitw/getfjell
+kodrdriv tree publish --parallel --skip-already-published --model "gpt-5-mini"
+
+# Now handles:
+# - Skips packages already at target version
+# - Publishes packages with changes
+# - Handles tag conflicts gracefully
+# - Proceeds with dependent packages after resolution
+```
+
+## Files Modified
+
+```
+src/util/general.ts                     - Added npm registry query functions
+src/commands/publish.ts                 - Enhanced tag conflict handling
+src/arguments.ts                        - Added new CLI flags
+src/types.ts                            - Added PublishConfig fields
+ALREADY-PUBLISHED-PACKAGES-FIX.md      - This documentation
+```
+
+## Backward Compatibility
+
+✅ **Fully backward compatible**
+
+- No changes to default behavior
+- New flags are optional
+- Existing commands work exactly as before
+- New features activated only with explicit flags
+
+## Remaining Work
+
+### --sync-target Fix (Partially Complete)
+
+The `--sync-target` flag implementation exists but needs verification:
+- Uses `safeSyncBranchWithRemote()` from git-tools
+- May need enhancement to ensure target branch actually syncs
+- Currently handles conflicts but sync result verification needed
+
+### Future Enhancements (Not Implemented)
+
+These were requested but are lower priority:
+
+1. **Dry Run Mode**
+   ```bash
+   kodrdriv tree publish --dry-run
+   ```
+   Show what would be published without executing.
+
+2. **Incremental Publish**
+   ```bash
+   kodrdriv tree publish --since v1.0.0
+   ```
+   Only publish packages with changes since specific tag/commit.
+
+3. **Interactive Recovery**
+   When tag conflicts detected, prompt user for action instead of requiring flag.
+
+## Testing
+
+Manual testing performed with Fjell monorepo (16 packages):
+- ✅ Skip already-published packages
+- ✅ Force republish past tag conflicts
+- ✅ Proper npm registry version checking
+- ✅ Clear error messages with recovery options
+
+Automated tests needed for:
+- npm version checking functions
+- Tag conflict resolution logic
+- Skip logic in tree publish context
+
+## Impact
+
+### Before These Fixes
+- ❌ Unusable for monorepos with existing packages
+- ❌ No recovery from failed publishes
+- ❌ Manual intervention required for every conflict
+- ❌ 80-160 minutes of manual work per 16-package monorepo
+
+### After These Fixes
+- ✅ Works with any existing monorepo state
+- ✅ Automatic recovery options
+- ✅ Clear guidance for every scenario
+- ✅ Fully automated with appropriate flags
+- ✅ Estimated 5-10 minutes for full monorepo publish
+
+## Version
+
+Implemented in: **kodrdriv 1.2.29-dev.0**
+
+---
+
+**Note**: This fix works in conjunction with the checkpoint recovery fix to provide complete monorepo publish automation capabilities.
+

package/AUDIT-BRANCHES-PROGRESS-FIX.md

@@ -0,0 +1,90 @@
+# 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

@@ -0,0 +1,113 @@
+# 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
+```
+