@gw-tools/gw 0.2.0 → 0.6.1

package/README.md

@@ -2,22 +2,87 @@
 
 A command-line tool for managing git worktrees, built with Deno.
 
+## Table of Contents
+
+- [gw - Git Worktree Tools](#gw---git-worktree-tools)
+  - [Table of Contents](#table-of-contents)
+  - [Quick Start](#quick-start)
+  - [Features](#features)
+  - [Installation](#installation)
+    - [Via npm (Recommended)](#via-npm-recommended)
+    - [Build from source](#build-from-source)
+  - [Configuration](#configuration)
+    - [Auto-Detection](#auto-detection)
+    - [Example Configuration](#example-configuration)
+    - [Configuration Options](#configuration-options)
+  - [Commands](#commands)
+    - [add](#add)
+      - [Arguments](#arguments)
+      - [Options](#options)
+      - [Examples](#examples)
+      - [Auto-Copy Configuration](#auto-copy-configuration)
+    - [root](#root)
+      - [Examples](#examples-1)
+      - [How It Works](#how-it-works)
+    - [init](#init)
+      - [Options](#options-1)
+      - [Examples](#examples-2)
+      - [When to Use](#when-to-use)
+    - [sync](#sync)
+      - [Arguments](#arguments-1)
+      - [Options](#options-2)
+      - [Examples](#examples-3)
+    - [Git Worktree Proxy Commands](#git-worktree-proxy-commands)
+      - [list (ls)](#list-ls)
+      - [remove (rm)](#remove-rm)
+      - [move (mv)](#move-mv)
+      - [prune](#prune)
+      - [lock](#lock)
+      - [unlock](#unlock)
+      - [repair](#repair)
+  - [Use Case](#use-case)
+    - [Typical Workflow](#typical-workflow)
+  - [Development](#development)
+    - [Local Development \& Testing](#local-development--testing)
+      - [Method 1: Shell Alias (Recommended for Active Development)](#method-1-shell-alias-recommended-for-active-development)
+      - [Method 2: Symlink to Compiled Binary (Faster Execution)](#method-2-symlink-to-compiled-binary-faster-execution)
+      - [Method 3: Development Wrapper Script (Best of Both Worlds)](#method-3-development-wrapper-script-best-of-both-worlds)
+      - [Method 4: npm link (For Testing Installation)](#method-4-npm-link-for-testing-installation)
+      - [Watch Mode for Active Development](#watch-mode-for-active-development)
+    - [Available Scripts](#available-scripts)
+    - [Publishing](#publishing)
+      - [Automated Release (Recommended)](#automated-release-recommended)
+      - [Manual Publishing](#manual-publishing)
+      - [Publishing to JSR (Optional)](#publishing-to-jsr-optional)
+      - [Version Management](#version-management)
+    - [Project Structure](#project-structure)
+    - [Adding New Commands](#adding-new-commands)
+  - [License](#license)
+
 ## Quick Start
 
 ```bash
 # Install
 npm install -g @gw-tools/gw
 
-# Create a new worktree
-git worktree add feat-new-feature
-
-# Copy secrets from main to the new worktree
-gw copy feat-new-feature .env
+# Create a new worktree and copy files
+gw add feat-new-feature .env secrets/
 
-# Done! Your new worktree has all the secrets it needs
+# Done! Your new worktree has the files it needs
 cd feat-new-feature
 ```
 
+**Or with auto-copy (one-time setup):**
+
+```bash
+# Configure auto-copy files once per repository
+gw init --root $(gw root) --auto-copy-files .env,secrets/
+
+# Now just create worktrees - files are copied automatically
+gw add feat-another-feature
+cd feat-another-feature
+```
+
 ## Features
 
 - **Copy files between worktrees**: Easily copy secrets, environment files, and configurations from one worktree to another
@@ -63,65 +128,478 @@ cp dist/packages/gw-tool/gw /usr/local/bin/gw
 
 ## Configuration
 
-On first run, `gw` will automatically create a configuration file at `<git-root>/.gw/config.json` in your repository. The tool finds the git repository root by walking up the directory tree from your current location.
+On first run, `gw` will automatically detect your git repository root and create a configuration file at `.gw/config.json`. The tool finds the config by walking up the directory tree from your current location, so you can run `gw` commands from anywhere within your repository.
+
+### Auto-Detection
+
+The tool automatically:
+
+1. **Searches for existing config**: Walks up from your current directory looking for `.gw/config.json`
+2. **Auto-detects git root**: If no config is found, detects the repository root automatically
+3. **Creates config**: Saves the detected root and default settings to `.gw/config.json`
+
+If auto-detection fails (rare edge cases), you can manually initialize:
+
+```bash
+gw init --root /path/to/your/repo.git
+```
 
 ### Example Configuration
 
 ```json
 {
-  "defaultSource": "main"
+  "root": "/Users/username/Workspace/my-project.git",
+  "defaultBranch": "main",
+  "autoCopyFiles": [
+    ".env",
+    "components/agents/.env",
+    "components/ui/.vercel/"
+  ]
 }
 ```
 
 ### Configuration Options
 
-- **defaultSource**: Default source worktree name (optional, defaults to "main")
+- **root**: Absolute path to the git repository root (automatically detected or manually set with `gw init`)
+- **defaultBranch**: Default source worktree name (optional, defaults to "main")
+- **autoCopyFiles**: Array of file/directory paths to automatically copy when creating worktrees with `gw add` (optional, only set via `gw init --auto-copy-files`)
 
 ## Commands
 
-### copy
+### add
+
+Create a new git worktree with optional automatic file copying.
+
+```bash
+gw add <worktree-name> [files...]
+```
+
+This command wraps `git worktree add` and optionally copies files to the new worktree. If `autoCopyFiles` is configured, those files are automatically copied. You can override this by specifying files as arguments.
+
+#### Arguments
+
+- `<worktree-name>`: Name or path for the new worktree
+- `[files...]`: Optional files to copy (overrides `autoCopyFiles` config)
+
+#### Options
+
+All `git worktree add` options are supported:
+- `-b <branch>`: Create a new branch
+- `-B <branch>`: Create or reset a branch
+- `--detach`: Detach HEAD in new worktree
+- `--force, -f`: Force checkout even if already checked out
+- `--track`: Track branch from remote
+- `-h, --help`: Show help message
+
+#### Examples
+
+```bash
+# Create worktree (auto-copies files if autoCopyFiles is configured)
+gw add feat/new-feature
+
+# Create worktree with new branch
+gw add feat/new-feature -b my-branch
+
+# Create worktree and copy specific files (overrides config)
+gw add feat/new-feature .env secrets/
+
+# Force create even if branch exists elsewhere
+gw add feat/bugfix -f
+```
+
+#### Auto-Copy Configuration
+
+To enable automatic file copying, configure `autoCopyFiles` using `gw init`:
+
+```bash
+gw init --root /path/to/repo.git --auto-copy-files .env,secrets/,components/ui/.vercel/
+```
+
+This creates:
+```json
+{
+  "root": "/path/to/repo.git",
+  "defaultBranch": "main",
+  "autoCopyFiles": [".env", "secrets/", "components/ui/.vercel/"]
+}
+```
+
+Now every time you run `gw add`, these files will be automatically copied from your default source worktree (usually `main`) to the new worktree.
+
+### root
+
+Get the root directory of the current git repository. For git worktrees, returns the parent directory containing all worktrees.
+
+```bash
+gw root
+```
+
+This command is useful when working with git worktrees to find the main repository directory that contains all worktrees, regardless of how deeply nested you are in the directory structure.
+
+#### Examples
+
+```bash
+# Get repository root path
+gw root
+# Output: /Users/username/Workspace/my-project.git
+
+# Navigate to repository root
+cd "$(gw root)"
+
+# List all worktrees
+ls "$(gw root)"
+
+# Use in scripts
+REPO_ROOT=$(gw root)
+echo "Repository is at: $REPO_ROOT"
+
+# Works from any depth
+cd /Users/username/Workspace/my-project.git/feat/deeply/nested/folder
+gw root
+# Output: /Users/username/Workspace/my-project.git
+```
+
+#### How It Works
+
+- **In a worktree**: Returns the parent directory containing all worktrees (e.g., `/path/to/repo.git`)
+- **In a regular repo**: Returns the directory containing the `.git` directory
+- **From nested directories**: Walks up the directory tree to find the repository root
+
+### init
+
+Initialize gw configuration for a git repository. This command is only needed if auto-detection fails or if you want to manually specify the repository root.
+
+```bash
+gw init --root <path> [options]
+```
+
+#### Options
+
+- `--root <path>`: Specify the git repository root path (required)
+- `--default-source <name>`: Set the default source worktree (default: "main")
+- `--auto-copy-files <files>`: Comma-separated list of files to auto-copy when creating worktrees with `gw add`
+- `-h, --help`: Show help message
+
+#### Examples
+
+```bash
+# Initialize with repository root
+gw init --root /Users/username/Workspace/my-project.git
+
+# Initialize with custom default source
+gw init --root /Users/username/Workspace/my-project.git --default-source master
+
+# Initialize with auto-copy files
+gw init --root /Users/username/Workspace/my-project.git --auto-copy-files .env,secrets/,components/ui/.vercel/
+
+# Show help
+gw init --help
+```
+
+#### When to Use
+
+In most cases, you won't need to run `gw init` manually because the tool auto-detects your repository root on first run. However, you may need it when:
+
+- Auto-detection fails (rare edge cases with non-standard repository structures)
+- You want to override the auto-detected root
+- You're setting up configuration before the repository has standard git structures
 
-Copy files and directories between worktrees, preserving directory structure.
+The config file is created at `.gw/config.json` in your current directory, so you can run this command from wherever makes sense for your workflow (typically the repository root).
+
+### sync
+
+Sync files and directories between worktrees, preserving directory structure.
 
 ```bash
-gw copy [options] <target-worktree> <files...>
+gw sync [options] <target-worktree> <files...>
 ```
 
 #### Arguments
 
 - `<target-worktree>`: Name or full path of the target worktree
-- `<files...>`: One or more files or directories to copy (paths relative to worktree root)
+- `<files...>`: One or more files or directories to sync (paths relative to worktree root)
 
 #### Options
 
 - `--from <source>`: Source worktree name (default: from config or "main")
-- `-n, --dry-run`: Show what would be copied without actually copying
+- `-n, --dry-run`: Show what would be synced without actually syncing
 - `-h, --help`: Show help message
 
 #### Examples
 
 ```bash
-# Copy .env file from main to feat-branch
-gw copy feat-branch .env
+# Sync .env file from main to feat-branch
+gw sync feat-branch .env
 
-# Copy multiple files
-gw copy feat-branch .env components/agents/.env components/agents/agents.yaml
+# Sync multiple files
+gw sync feat-branch .env components/agents/.env components/agents/agents.yaml
 
-# Copy entire directory
-gw copy feat-branch components/ui/.vercel
+# Sync entire directory
+gw sync feat-branch components/ui/.vercel
 
 # Use custom source worktree
-gw copy --from develop feat-branch .env
+gw sync --from develop feat-branch .env
 
 # Dry run to preview changes
-gw copy --dry-run feat-branch .env
+gw sync --dry-run feat-branch .env
 
 # Use absolute path as target
-gw copy /full/path/to/repo/feat-branch .env
+gw sync /full/path/to/repo/feat-branch .env
+```
+
+### Git Worktree Proxy Commands
+
+These commands wrap native `git worktree` operations, providing consistent colored output and help messages. All git flags and options are passed through transparently.
+
+#### list (ls)
+
+List all worktrees in the repository.
+
+```bash
+gw list
+# or
+gw ls
+```
+
+**Examples:**
+```bash
+gw list                  # List all worktrees
+gw list --porcelain      # Machine-readable output
+gw list -v               # Verbose output
+```
+
+#### remove (rm)
+
+Remove a worktree from the repository.
+
+```bash
+gw remove <worktree>
+# or
+gw rm <worktree>
+```
+
+**Examples:**
+```bash
+gw remove feat-branch           # Remove a worktree
+gw remove --force feat-branch   # Force remove even if dirty
+gw rm feat-branch               # Using alias
+```
+
+#### move (mv)
+
+Move a worktree to a new location.
+
+```bash
+gw move <worktree> <new-path>
+# or
+gw mv <worktree> <new-path>
+```
+
+**Examples:**
+```bash
+gw move feat-branch ../new-location
+gw mv feat-branch ../new-location
+```
+
+#### prune
+
+Clean up worktree information for deleted worktrees.
+
+```bash
+gw prune
+```
+
+**Examples:**
+```bash
+gw prune                # Clean up stale worktree information
+gw prune --dry-run      # Preview what would be pruned
+gw prune --verbose      # Show detailed output
+```
+
+#### lock
+
+Lock a worktree to prevent removal.
+
+```bash
+gw lock <worktree>
+```
+
+**Examples:**
+```bash
+gw lock feat-branch
+gw lock --reason "Work in progress" feat-branch
+```
+
+#### unlock
+
+Unlock a worktree to allow removal.
+
+```bash
+gw unlock <worktree>
+```
+
+**Examples:**
+```bash
+gw unlock feat-branch
+```
+
+#### repair
+
+Repair worktree administrative files.
+
+```bash
+gw repair [<path>]
+```
+
+**Examples:**
+```bash
+gw repair                        # Repair all worktrees
+gw repair /path/to/worktree      # Repair specific worktree
+```
+
+## Use Case
+
+This tool was originally created to simplify the workflow of copying secrets and environment files when creating new git worktrees. When you create a new worktree for a feature branch, you often need to copy `.env` files, credentials, and other configuration files from your main worktree to the new one. This tool automates that process.
+
+The tool automatically detects which git repository you're working in and creates a local config file (`.gw/config.json`) on first use. The config stores the repository root and other settings, so subsequent runs are fast and don't need to re-detect the repository structure. Each repository has its own configuration, and you can customize the default source worktree per repository.
+
+### Typical Workflow
+
+```bash
+# One-time setup: Configure auto-copy files
+gw init --root $(gw root) --auto-copy-files .env,components/agents/.env,components/ui/.vercel/
+
+# From within any worktree of your repository
+# Create a new worktree with auto-copy
+gw add feat-new-feature
+
+# Done! Files are automatically copied
+cd feat-new-feature
+
+# Alternative: Create worktree and copy specific files
+gw add feat-bugfix .env custom-config.json
+
+# Alternative: Use the manual sync command
+git worktree add feat-manual
+gw sync feat-manual .env
 ```
 
 ## Development
 
+### Local Development & Testing
+
+When developing the tool, you can test changes locally without publishing by creating a global symlink. This allows you to use the `gw` command with live code updates.
+
+#### Method 1: Shell Alias (Recommended for Active Development)
+
+Create a shell alias that runs the Deno version directly with watch mode:
+
+```bash
+# Add to your ~/.zshrc or ~/.bashrc
+alias gw-dev='deno run --allow-all ~/path/to/gw-tools/packages/gw-tool/src/main.ts'
+
+# Reload your shell
+source ~/.zshrc  # or ~/.bashrc
+
+# Now you can use it anywhere
+cd ~/some-project
+gw-dev copy feat-branch .env
+```
+
+This gives you instant feedback - just edit the TypeScript files and run the command again.
+
+#### Method 2: Symlink to Compiled Binary (Faster Execution)
+
+Create a symlink to the compiled binary and recompile when needed:
+
+```bash
+# From the workspace root
+nx run gw-tool:compile
+
+# Create global symlink (one-time setup)
+sudo ln -sf ~/path/to/gw-tools/dist/packages/gw-tool/gw /usr/local/bin/gw
+
+# Now you can use `gw` globally
+cd ~/some-project
+gw sync feat-branch .env
+
+# When you make changes, recompile
+nx run gw-tool:compile
+# The symlink automatically points to the new binary
+```
+
+#### Method 3: Development Wrapper Script (Best of Both Worlds)
+
+Create a wrapper script that provides both speed and live updates:
+
+```bash
+# Create ~/bin/gw (make sure ~/bin is in your PATH)
+cat > ~/bin/gw << 'EOF'
+#!/bin/bash
+# Check if we're in development mode (set GW_DEV=1 to use source)
+if [ "$GW_DEV" = "1" ]; then
+  exec deno run --allow-all ~/path/to/gw-tools/packages/gw-tool/src/main.ts "$@"
+else
+  exec ~/path/to/gw-tools/dist/packages/gw-tool/gw "$@"
+fi
+EOF
+
+chmod +x ~/bin/gw
+
+# Use compiled version (fast)
+gw sync feat-branch .env
+
+# Use development version with live updates
+GW_DEV=1 gw sync feat-branch .env
+
+# Or set it for your entire session
+export GW_DEV=1
+gw sync feat-branch .env
+```
+
+#### Method 4: npm link (For Testing Installation)
+
+Test the npm package installation flow locally:
+
+```bash
+# Compile binaries
+nx run gw-tool:compile-all
+
+# Prepare npm package
+nx run gw-tool:npm-pack
+
+# Link the package globally
+cd dist/packages/gw-tool/npm
+npm link
+
+# Now `gw` is available globally via npm
+gw sync feat-branch .env
+
+# When you make changes
+cd ~/path/to/gw-tools
+nx run gw-tool:compile-all
+nx run gw-tool:npm-pack
+# The link automatically uses the updated binaries
+
+# To unlink when done
+npm unlink -g @gw-tools/gw
+```
+
+#### Watch Mode for Active Development
+
+Use the watch mode to automatically restart when files change:
+
+```bash
+# Terminal 1: Run in watch mode
+nx run gw-tool:dev
+
+# Terminal 2: Test in another project
+cd ~/some-project
+~/path/to/gw-tools/dist/packages/gw-tool/gw sync feat-branch .env
+```
+
+**Pro tip**: Combine Method 3 (wrapper script) with watch mode by setting `GW_DEV=1` in your development shell.
+
 ### Available Scripts
 
 ```bash
@@ -287,13 +765,32 @@ packages/gw-tool/
 │   ├── main.ts              # CLI entry point and command dispatcher
 │   ├── index.ts             # Public API exports
 │   ├── commands/            # Command implementations
-│   │   └── copy.ts          # Copy command
+│   │   ├── add.ts           # Add command (create worktree with auto-copy)
+│   │   ├── copy.ts          # Sync command (sync files between worktrees)
+│   │   ├── init.ts          # Init command
+│   │   ├── root.ts          # Root command
+│   │   ├── list.ts          # List command (proxy)
+│   │   ├── remove.ts        # Remove command (proxy)
+│   │   ├── move.ts          # Move command (proxy)
+│   │   ├── prune.ts         # Prune command (proxy)
+│   │   ├── lock.ts          # Lock command (proxy)
+│   │   ├── unlock.ts        # Unlock command (proxy)
+│   │   └── repair.ts        # Repair command (proxy)
 │   └── lib/                 # Shared utilities
 │       ├── types.ts         # TypeScript type definitions
 │       ├── config.ts        # Configuration management
-│       ├── cli.ts           # CLI argument parsing
+│       ├── cli.ts           # CLI argument parsing & help
 │       ├── file-ops.ts      # File/directory operations
-│       └── path-resolver.ts # Path resolution utilities
+│       ├── path-resolver.ts # Path resolution utilities
+│       ├── output.ts        # Colored output formatting
+│       └── git-proxy.ts     # Git command proxy utilities
+├── npm/                     # npm package files
+│   ├── package.json         # npm package metadata
+│   ├── install.js           # Binary installation script
+│   └── bin/
+│       └── gw.js            # Binary wrapper
+├── scripts/
+│   └── release.sh           # Automated release script
 ├── deno.json                # Deno configuration
 ├── project.json             # Nx project configuration
 └── README.md                # This file
@@ -301,43 +798,94 @@ packages/gw-tool/
 
 ### Adding New Commands
 
-To add a new command:
+There are two types of commands you can add:
 
-1. Create a new file in `src/commands/` (e.g., `init.ts`)
-2. Implement your command function:
+#### Custom Commands (like `add`, `copy`)
+
+For commands with custom logic, follow the pattern used by existing commands:
+
+1. **Create a new file** in `src/commands/` (e.g., `list.ts`):
    ```typescript
-   export async function executeInit(args: string[]): Promise<void> {
+   // src/commands/list.ts
+   export async function executeList(args: string[]): Promise<void> {
+     // Check for help flag
+     if (args.includes("--help") || args.includes("-h")) {
+       console.log(`Usage: gw list
+
+   List all git worktrees in the current repository.
+
+   Options:
+     -h, --help    Show this help message
+   `);
+       Deno.exit(0);
+     }
+
      // Command implementation
+     // ...
    }
    ```
-3. Add the command to the `COMMANDS` object in `src/main.ts`:
+
+2. **Import and register** the command in `src/main.ts`:
    ```typescript
+   import { executeList } from "./commands/list.ts";
+
    const COMMANDS = {
-     copy: executeCopy,
-     init: executeInit, // Add your new command
+     add: executeAdd,
+     sync: executeCopy,
+     init: executeInit,
+     root: executeRoot,
+     list: executeList, // Add your new command
    };
    ```
 
-## Use Case
+3. **Update global help** in `src/lib/cli.ts`:
+   ```typescript
+   export function showGlobalHelp(): void {
+     console.log(`
+   Commands:
+     add      Create a new worktree with optional auto-copy
+     sync     Sync files/directories between worktrees
+     init     Initialize gw configuration for a repository
+     root     Get the root directory of the current git repository
+     list     List all git worktrees in the repository
+   `);
+   }
+   ```
 
-This tool was originally created to simplify the workflow of copying secrets and environment files when creating new git worktrees. When you create a new worktree for a feature branch, you often need to copy `.env` files, credentials, and other configuration files from your main worktree to the new one. This tool automates that process.
+#### Git Proxy Commands (like `list`, `remove`)
 
-The tool automatically detects which git repository you're working in by finding the `.git` directory, and creates a local config file (`.gw/config.json`) at the repository root on first use. This means each repository has its own configuration, and you can customize the default source worktree per repository.
+For simple pass-through commands that wrap git worktree operations, use the `git-proxy` utility:
 
-### Typical Workflow
+1. **Create a new file** in `src/commands/` (e.g., `list.ts`):
+   ```typescript
+   // src/commands/list.ts
+   import { executeGitWorktree, showProxyHelp } from '../lib/git-proxy.ts';
+
+   export async function executeList(args: string[]): Promise<void> {
+     if (args.includes('--help') || args.includes('-h')) {
+       showProxyHelp(
+         'list',
+         'list',
+         'List all worktrees in the repository',
+         ['gw list', 'gw list --porcelain', 'gw list -v'],
+       );
+       Deno.exit(0);
+     }
+
+     await executeGitWorktree('list', args);
+   }
+   ```
 
-```bash
-# From within any worktree of your repository
-# Create a new worktree
-git worktree add feat-new-feature
+2. **Register** in `src/main.ts` (same as above)
 
-# Copy secrets from main worktree to the new one
-# gw automatically detects your repository and uses its config
-gw copy feat-new-feature .env components/agents/.env components/ui/.vercel
+3. **Update global help** in `src/lib/cli.ts` (same as above)
 
-# Start working in the new worktree
-cd feat-new-feature
-```
+This approach requires minimal maintenance as it simply forwards all arguments to git.
+
+**Tips**:
+- Look at [src/commands/root.ts](src/commands/root.ts) for a simple custom command
+- Look at [src/commands/copy.ts](src/commands/copy.ts) for a complex command with argument parsing
+- Look at [src/commands/list.ts](src/commands/list.ts) for a simple proxy command
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gw-tools/gw",
-  "version": "0.2.0",
+  "version": "0.6.1",
   "description": "A command-line tool for managing git worktrees - copy files between worktrees with ease",
   "keywords": [
     "git",