@camaradesuk/git-worktree-tools 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CAMARADES UK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+# git-worktree-tools
+
+Cross-platform CLI tools for git worktree workflow management. Create PRs with dedicated worktrees, sync gitignored files, and manage your development workflow.
+
+## Features
+
+- **Cross-platform**: Works natively on Windows, macOS, and Linux (no bash/WSL required)
+- **Smart State Detection**: Intelligently handles 10+ git scenarios (uncommitted changes, local commits, existing branches, etc.)
+- **PR + Worktree Workflow**: Create PRs and dedicated worktrees in one command
+- **Shared Repos**: Automatically create worktrees in related repositories
+- **Config Syncing**: Share gitignored config files (.env, .vscode, etc.) between worktrees via hard links
+- **Configurable**: Per-repo settings via `.worktreerc`
+
+## Installation
+
+```bash
+npm install -g @camaradesuk/git-worktree-tools
+```
+
+**Prerequisites**:
+
+- Node.js 18+
+- Git
+- GitHub CLI (`gh`) for PR operations
+
+## Quick Start
+
+```bash
+# Create a new PR with worktree
+newpr "Add user authentication feature"
+
+# List all worktrees
+lswt
+
+# Clean up merged/closed PR worktrees
+cleanpr
+
+# Manage shared config files between worktrees
+wtlink
+```
+
+## Commands
+
+### newpr
+
+Create a new PR with an associated worktree.
+
+```bash
+newpr "Description of the feature"
+newpr --branch my-feature "Feature description"
+newpr --pr 123  # Work on existing PR
+newpr --draft "WIP feature"
+```
+
+**Smart State Handling**: The tool detects your current git state and offers appropriate options:
+
+- Uncommitted changes? Choose to commit, stash, or leave them
+- Local commits on main? Include them or start fresh
+- On a feature branch? Create PR for it or start new
+- Detached HEAD? Create branch from current commit or main
+
+### cleanpr
+
+Clean up worktrees for merged or closed PRs.
+
+```bash
+cleanpr           # Interactive cleanup
+cleanpr --all     # Clean all merged/closed automatically
+cleanpr --force   # Force remove even if not merged
+```
+
+### lswt
+
+List all worktrees with status information.
+
+```bash
+lswt              # List all worktrees
+lswt --status     # Include PR status (open/merged/closed)
+lswt --json       # Output as JSON for scripting
+lswt --verbose    # Show more details (commit hashes, full paths)
+```
+
+### wtlink
+
+Interactive CLI for managing configuration file links between git worktrees. Share config files while keeping build artifacts separate using hard links and a manifest file.
+
+```bash
+wtlink                    # Interactive main menu
+wtlink manage             # Interactive file browser to select files to share
+wtlink link               # Create hard links based on manifest
+wtlink link ../my-app.pr42  # Link to specific worktree
+wtlink validate           # Verify manifest integrity
+```
+
+**Command options:**
+
+```bash
+# manage - Discover and manage the manifest
+wtlink manage                   # Interactive mode
+wtlink manage --non-interactive # Auto-add new files as commented
+wtlink manage --clean           # Remove stale entries automatically
+wtlink manage --dry-run         # Preview changes without writing
+wtlink manage --backup          # Create .wtlinkrc.bak before updating
+
+# link - Create links between worktrees
+wtlink link [source] [dest]     # Link from source to destination
+wtlink link --dry-run           # Preview what would be linked
+wtlink link --type symbolic     # Use symlinks instead of hard links
+wtlink link --yes               # Skip confirmation prompts
+
+# validate - Check manifest integrity
+wtlink validate                 # Validate against current worktree
+wtlink validate ../other-wt     # Validate against specific source
+```
+
+**How it works:**
+
+1. **Discover** — Scans for git-ignored files in your repository
+2. **Decide** — Interactive UI to categorize each file (link, track, or skip)
+3. **Link** — Creates hard links from main worktree to feature worktrees
+4. **Validate** — Ensures manifest entries exist and remain git-ignored
+
+**Interactive UI navigation:**
+
+| Key | Action                                           |
+| --- | ------------------------------------------------ |
+| ↑/↓ | Navigate file list                               |
+| ←/→ | Navigate into/out of folders (hierarchical view) |
+| A   | Mark as "Will Link" (added to manifest)          |
+| C   | Mark as "Track" (commented in manifest)          |
+| S   | Mark as "Skip" (not in manifest)                 |
+| 0   | Toggle showing undecided items                   |
+| 1   | Toggle showing "Will Link" items                 |
+| 2   | Toggle showing "Track" items                     |
+| 3   | Toggle showing "Skip" items                      |
+| V   | Toggle hierarchical/flat view                    |
+| ?   | Show help                                        |
+| Q   | Save and quit                                    |
+| X   | Cancel without saving                            |
+
+**Folder operations:** Actions on folders apply to all files inside. The UI shows a breakdown of child states for each folder.
+
+**Conflict detection:** When linking, if a file already exists at the destination with different content, you'll be prompted to:
+
+- **Replace** — Delete destination and create link
+- **Ignore** — Keep destination file as-is
+- **Remove** — Remove entry from manifest
+
+**Manifest format (`.wtlinkrc`):**
+
+The manifest lives in your repository root and tracks which files to share:
+
+```text
+.vscode/settings.json
+.editorconfig
+.env.local
+# .vscode/launch.json
+```
+
+- Active entries (no `#`) are hard-linked between worktrees
+- Commented entries (`#`) are tracked but not currently linked
+- Files marked "Skip" are not added to the manifest at all
+
+**Best practices:**
+
+✅ **Good candidates for linking:**
+
+- `.vscode/settings.json`, `.editorconfig` — Editor config
+- `.env.local`, `.env.development` — Local environment variables
+- `certificates/`, `credentials/` — Local dev certificates
+
+❌ **Not suitable for linking:**
+
+- `node_modules/` — Use [pnpm](https://pnpm.io) for shared dependencies instead
+- `dist/`, `build/` — Build artifacts should be separate per worktree
+- `.git/` — Never link git internals
+
+## Configuration
+
+Create a `.worktreerc` file in your repository root:
+
+```json
+{
+  "sharedRepos": ["cluster-gitops", "infrastructure"],
+  "baseBranch": "main",
+  "draftPr": true
+}
+```
+
+### Options
+
+| Option            | Type     | Default               | Description                                |
+| ----------------- | -------- | --------------------- | ------------------------------------------ |
+| `sharedRepos`     | string[] | `[]`                  | Sibling repos to also create worktrees for |
+| `baseBranch`      | string   | `"main"`              | Base branch for new PRs                    |
+| `draftPr`         | boolean  | `false`               | Create PRs as drafts by default            |
+| `worktreePattern` | string   | `"{repo}.pr{number}"` | Worktree directory naming pattern          |
+| `worktreeParent`  | string   | `".."`                | Parent directory for worktrees             |
+| `branchPrefix`    | string   | `"claude"`            | Prefix for auto-generated branch names     |
+
+> **Note:** File syncing between worktrees is managed by `wtlink` using its own `.wtlinkrc` manifest. See the [wtlink section](#wtlink) for details.
+
+## Example Workflow
+
+```bash
+# Start in your main repo
+cd ~/projects/my-app
+
+# Create a new feature PR
+newpr "Add dark mode support"
+# → Creates branch: claude/add-dark-mode-support-xyz123
+# → Creates PR: #42
+# → Creates worktree: ~/projects/my-app.pr42
+# → Switches to worktree
+
+# Work on the feature in the dedicated worktree
+# ... make changes, commit, push ...
+
+# Need to work on another feature? No problem!
+cd ~/projects/my-app
+newpr "Fix login bug"
+# → Creates another worktree: ~/projects/my-app.pr43
+
+# List your worktrees
+lswt
+# WORKTREE              BRANCH                         PR     STATUS
+# ~/projects/my-app     main                           -      -
+# ~/projects/my-app.pr42 claude/add-dark-mode-xyz123  #42    open
+# ~/projects/my-app.pr43 claude/fix-login-bug-abc456  #43    open
+
+# After PRs are merged, clean up
+cleanpr
+# → Removes worktrees for merged PRs
+# → Deletes local branches
+```
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/camaradesuk/git-worktree-tools.git
+cd git-worktree-tools
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test
+npm test
+
+# Link for local development
+npm link
+```
+
+## License
+
+MIT

package/dist/cli/cleanpr.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * cleanpr - Clean up PR worktrees after merge/close
+ *
+ * Usage:
+ *   cleanpr                    # Interactive cleanup of merged/closed PRs
+ *   cleanpr <PR_NUMBER>        # Clean specific PR worktree
+ *   cleanpr --all              # Clean all merged/closed PRs
+ *   cleanpr <PR_NUMBER> -r     # Also delete remote branch
+ *   cleanpr <PR_NUMBER> -f     # Force removal with uncommitted changes
+ */
+export {};
+//# sourceMappingURL=cleanpr.d.ts.map

package/dist/cli/cleanpr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanpr.d.ts","sourceRoot":"","sources":["../../src/cli/cleanpr.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG"}