@gw-tools/gw 0.12.23 → 0.12.26

package/README.md

@@ -7,6 +7,10 @@ A command-line tool for managing git worktrees, built with Deno.
 - [gw - Git Worktree Tools](#gw---git-worktree-tools)
   - [Table of Contents](#table-of-contents)
   - [Quick Start](#quick-start)
+  - [Initial Setup: Secrets in the Default Branch](#initial-setup-secrets-in-the-default-branch)
+    - [First-Time Setup Flow](#first-time-setup-flow)
+    - [Why This Matters](#why-this-matters)
+    - [Keeping Secrets Updated](#keeping-secrets-updated)
   - [Features](#features)
   - [Installation](#installation)
     - [Via npm (Recommended)](#via-npm-recommended)
@@ -21,6 +25,7 @@ A command-line tool for managing git worktrees, built with Deno.
       - [Options](#options)
       - [Examples](#examples)
       - [Auto-Copy Configuration](#auto-copy-configuration)
+      - [Hooks](#hooks)
     - [cd](#cd)
       - [Arguments](#arguments-1)
       - [Examples](#examples-1)
@@ -38,18 +43,21 @@ A command-line tool for managing git worktrees, built with Deno.
     - [init](#init)
       - [Options](#options-3)
       - [Examples](#examples-5)
+      - [Hook Variables](#hook-variables)
+      - [Auto-Cleanup Configuration](#auto-cleanup-configuration)
       - [When to Use](#when-to-use)
     - [show-init](#show-init)
-      - [Options](#options-6)
-      - [Examples](#examples-8)
+      - [Options](#options-4)
+      - [Examples](#examples-6)
+      - [Output Example](#output-example)
       - [When to Use](#when-to-use-1)
     - [sync](#sync)
       - [Arguments](#arguments-2)
-      - [Options](#options-4)
-      - [Examples](#examples-6)
-    - [clean](#clean)
       - [Options](#options-5)
       - [Examples](#examples-7)
+    - [clean](#clean)
+      - [Options](#options-6)
+      - [Examples](#examples-8)
       - [How It Works](#how-it-works-3)
     - [Git Worktree Proxy Commands](#git-worktree-proxy-commands)
       - [list (ls)](#list-ls)
@@ -63,11 +71,7 @@ A command-line tool for managing git worktrees, built with Deno.
     - [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)
+      - [Shell Alias Method (Recommended)](#shell-alias-method-recommended)
     - [Available Scripts](#available-scripts)
     - [Publishing](#publishing)
       - [Automated Release (Recommended)](#automated-release-recommended)
@@ -76,6 +80,8 @@ A command-line tool for managing git worktrees, built with Deno.
       - [Version Management](#version-management)
     - [Project Structure](#project-structure)
     - [Adding New Commands](#adding-new-commands)
+      - [Custom Commands (like `add`, `copy`)](#custom-commands-like-add-copy)
+      - [Git Proxy Commands (like `list`, `remove`)](#git-proxy-commands-like-list-remove)
   - [License](#license)
 
 ## Quick Start
@@ -220,11 +226,7 @@ gw init --root /path/to/your/repo.git
 {
   "root": "/Users/username/Workspace/my-project.git",
   "defaultBranch": "main",
-  "autoCopyFiles": [
-    ".env",
-    "components/agents/.env",
-    "components/ui/.vercel/"
-  ],
+  "autoCopyFiles": [".env", "components/agents/.env", "components/ui/.vercel/"],
   "hooks": {
     "add": {
       "pre": ["echo 'Creating worktree: {worktree}'"],
@@ -283,6 +285,7 @@ If you try to add a worktree that already exists, the command will prompt you to
 #### 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
@@ -323,6 +326,7 @@ gw init --auto-copy-files .env,secrets/,components/ui/.vercel/
 ```
 
 This creates:
+
 ```json
 {
   "root": "/path/to/repo.git",
@@ -336,6 +340,7 @@ Now every time you run `gw add`, these files will be automatically copied from y
 #### Hooks
 
 You can configure pre-add and post-add hooks to run commands before and after worktree creation. This is useful for:
+
 - **Pre-add hooks**: Running validation scripts, checking prerequisites
 - **Post-add hooks**: Installing dependencies, setting up the environment
 
@@ -350,12 +355,14 @@ gw init --pre-add "echo 'Creating: {worktree}'" --post-add "pnpm install" --post
 **Hook Variables:**
 
 Hooks support variable substitution:
+
 - `{worktree}` - The worktree name (e.g., "feat/new-feature")
 - `{worktreePath}` - Full absolute path to the worktree
 - `{gitRoot}` - The git repository root path
 - `{branch}` - The branch name
 
 **Hook Behavior:**
+
 - **Pre-add hooks** run before the worktree is created (in the git root directory). If any pre-add hook fails, the worktree creation is aborted.
 - **Post-add hooks** run after the worktree is created and files are copied (in the new worktree directory). If a post-add hook fails, a warning is shown but the worktree creation is considered successful.
 
@@ -454,6 +461,7 @@ gw pull --remote upstream
 3. Creates merge commit if histories have diverged
 
 **Safety checks:**
+
 - Blocks if you have uncommitted changes (use `--force` to override)
 - Blocks if you're in a detached HEAD state
 - Handles merge conflicts gracefully with clear guidance
@@ -463,6 +471,7 @@ gw pull --remote upstream
 **Configuration:**
 
 The default branch is read from `.gw/config.json`:
+
 ```json
 {
   "defaultBranch": "main"
@@ -473,7 +482,16 @@ If not configured, defaults to "main".
 
 ### install-shell
 
-Install or remove shell integration for the `gw cd` command. This is automatically run during `npm install`, but can be run manually if needed.
+Install or remove shell integration for the `gw cd` command and enable real-time streaming output. This is automatically run during `npm install`, but can be run manually if needed.
+
+The installation creates an integration script in `~/.gw/shell/` and adds a single line to your shell configuration to source it, keeping your shell config clean and minimal.
+
+Shell integration provides:
+
+- **Navigation support**: `gw cd <worktree>` navigates directly to worktrees
+- **Real-time streaming**: Command output streams as it's generated (no buffering)
+- **Auto-navigation**: Automatically navigate after `gw add` and `gw remove` operations
+- **Multi-alias support**: Install for different command names (e.g., `gw-dev` for development)
 
 ```bash
 gw install-shell [options]
@@ -481,6 +499,8 @@ gw install-shell [options]
 
 #### Options
 
+- `--name, -n NAME`: Install under a different command name (default: `gw`)
+- `--command, -c CMD`: Actual command to run (use with `--name` for aliases/dev)
 - `--remove`: Remove shell integration
 - `--quiet, -q`: Suppress output messages
 - `-h, --help`: Show help message
@@ -491,19 +511,25 @@ gw install-shell [options]
 # Install shell integration (usually not needed - auto-installed)
 gw install-shell
 
-# Remove shell integration
-gw install-shell --remove
+# Install for development (with Deno)
+# Note: Remove any 'alias gw-dev=...' from .zshrc first!
+gw install-shell --name gw-dev \
+  --command "deno run --allow-all ~/path/to/gw-tools/packages/gw-tool/src/main.ts"
+
+# Remove shell integration for 'gw-dev'
+gw install-shell --name gw-dev --remove
 
 # Install quietly (for automation)
 gw install-shell --quiet
 ```
 
 **Supported Shells:**
-- **Zsh** (~/.zshrc)
-- **Bash** (~/.bashrc)
-- **Fish** (~/.config/fish/functions/gw.fish)
 
-The command is idempotent - running it multiple times won't create duplicate entries.
+- **Zsh** (~/.zshrc sources ~/.gw/shell/integration[-NAME].zsh)
+- **Bash** (~/.bashrc sources ~/.gw/shell/integration[-NAME].bash)
+- **Fish** (~/.config/fish/functions/[NAME].fish)
+
+The command is idempotent - running it multiple times won't create duplicate entries. It will also automatically migrate old inline installations to the new format.
 
 ### root
 
@@ -604,6 +630,7 @@ gw init --help
 #### Hook Variables
 
 Hooks support variable substitution:
+
 - `{worktree}` - The worktree name (e.g., "feat/new-feature")
 - `{worktreePath}` - Full absolute path to the worktree
 - `{gitRoot}` - The git repository root path
@@ -625,6 +652,7 @@ gw init --auto-clean --auto-copy-files .env --post-add "pnpm install"
 ```
 
 **How it works:**
+
 - Runs automatically on `gw add` and `gw list` commands (in the background, non-blocking)
 - Only runs once per 24 hours (cooldown)
 - **Never removes the `defaultBranch` worktree** - it's protected as the source for file syncing
@@ -640,6 +668,7 @@ This is an opt-in feature. Use `gw clean` for manual, interactive cleanup with m
 #### When to Use
 
 Use `gw init` to:
+
 - Configure auto-copy files for automatic file copying on worktree creation
 - Set up pre-add and post-add hooks for automation
 - Configure the clean threshold for worktree age management
@@ -682,6 +711,7 @@ echo "## Setup\n\n\`\`\`bash\n$(gw show-init)\n\`\`\`" >> README.md
 #### Output Example
 
 If your `.gw/config.json` contains:
+
 ```json
 {
   "root": "/Users/username/Workspace/repo.git",
@@ -697,6 +727,7 @@ If your `.gw/config.json` contains:
 ```
 
 Then `gw show-init` will output:
+
 ```bash
 gw init --root /Users/username/Workspace/repo.git --auto-copy-files .env,secrets/ --post-add 'pnpm install'
 ```
@@ -704,6 +735,7 @@ gw init --root /Users/username/Workspace/repo.git --auto-copy-files .env,secrets
 #### When to Use
 
 Use `gw show-init` to:
+
 - Document your setup in README files or team wikis
 - Share configuration commands with team members
 - Recreate the same configuration in another repository
@@ -788,6 +820,7 @@ gw init --clean-threshold 14
 #### How It Works
 
 The clean command:
+
 1. Checks for worktrees older than the configured threshold (default: 7 days)
 2. Verifies they have no uncommitted changes (unless `--force`)
 3. Verifies they have no unpushed commits (unless `--force`)
@@ -795,6 +828,7 @@ The clean command:
 5. Never removes bare/main repository worktrees
 
 **Safety Features:**
+
 - By default, only removes worktrees with NO uncommitted changes
 - By default, only removes worktrees with NO unpushed commits
 - Always prompts for confirmation before deletion
@@ -811,6 +845,7 @@ gw init --clean-threshold 14
 ```
 
 This creates/updates the config:
+
 ```json
 {
   "root": "/path/to/repo.git",
@@ -834,6 +869,7 @@ gw ls
 ```
 
 **Examples:**
+
 ```bash
 gw list                  # List all worktrees
 gw list --porcelain      # Machine-readable output
@@ -851,6 +887,7 @@ gw rm <worktree>
 ```
 
 **Examples:**
+
 ```bash
 gw remove feat-branch           # Remove a worktree
 gw remove --force feat-branch   # Force remove even if dirty
@@ -868,6 +905,7 @@ gw mv <worktree> <new-path>
 ```
 
 **Examples:**
+
 ```bash
 gw move feat-branch ../new-location
 gw mv feat-branch ../new-location
@@ -875,19 +913,56 @@ gw mv feat-branch ../new-location
 
 #### prune
 
-Clean up worktree information for deleted worktrees.
+Clean up worktree administrative data and optionally remove clean worktrees.
+
+**Standard Mode** (without `--clean`):
+Wraps `git worktree prune` to clean up administrative files for deleted worktrees.
+
+**Clean Mode** (with `--clean`):
+First runs `git worktree prune`, then removes ALL worktrees that have no uncommitted changes, no staged files, and no unpushed commits. Unlike `gw clean` (which is age-based), `gw prune --clean` removes worktrees regardless of age.
 
 ```bash
-gw prune
+gw prune [options]
 ```
 
+**Options:**
+
+- `--clean` - Enable clean mode (remove clean worktrees)
+- `-n, --dry-run` - Preview what would be removed
+- `-f, --force` - Skip confirmation prompt
+- `-v, --verbose` - Show detailed output
+- `-h, --help` - Show help
+
+**Safety Features** (in clean mode):
+
+- Default branch is protected (configured in `.gw/config.json`)
+- Current worktree cannot be removed
+- Bare repository is never removed
+- Confirmation prompt before removal (defaults to yes, just press Enter to confirm)
+
 **Examples:**
+
 ```bash
-gw prune                # Clean up stale worktree information
-gw prune --dry-run      # Preview what would be pruned
-gw prune --verbose      # Show detailed output
+# Standard prune (cleanup administrative data)
+gw prune
+gw prune --verbose
+
+# Clean mode (remove clean worktrees)
+gw prune --clean              # Remove all clean worktrees (with prompt)
+gw prune --clean --dry-run    # Preview what would be removed
+gw prune --clean --force      # Remove without confirmation
+gw prune --clean --verbose    # Show detailed output
 ```
 
+**Comparison with `gw clean`:**
+| Feature | `gw clean` | `gw prune --clean` |
+|---------|-----------|-------------------|
+| Age-based | Yes (configurable threshold) | No (removes all clean) |
+| Safety checks | Yes | Yes |
+| Protects default branch | No | Yes |
+| Runs `git worktree prune` | No | Yes |
+| Use case | Regular maintenance | Aggressive cleanup |
+
 #### lock
 
 Lock a worktree to prevent removal.
@@ -897,6 +972,7 @@ gw lock <worktree>
 ```
 
 **Examples:**
+
 ```bash
 gw lock feat-branch
 gw lock --reason "Work in progress" feat-branch
@@ -911,6 +987,7 @@ gw unlock <worktree>
 ```
 
 **Examples:**
+
 ```bash
 gw unlock feat-branch
 ```
@@ -924,6 +1001,7 @@ gw repair [<path>]
 ```
 
 **Examples:**
+
 ```bash
 gw repair                        # Repair all worktrees
 gw repair /path/to/worktree      # Repair specific worktree
@@ -964,117 +1042,36 @@ gw cd feat-manual
 
 ### 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.
+When developing the tool, you can test changes locally without publishing by using a shell alias. This allows you to use the `gw-dev` command with live code updates and full shell integration.
 
-#### Method 1: Shell Alias (Recommended for Active Development)
+#### Shell Alias Method (Recommended)
 
-Create a shell alias that runs the Deno version directly with watch mode:
+Create a shell alias that runs the Deno version directly for instant feedback:
 
 ```bash
-# Add to your ~/.zshrc or ~/.bashrc
-alias gw-dev='deno run --allow-all ~/path/to/gw-tools/packages/gw-tool/src/main.ts'
+# Install shell integration for gw-dev
+# IMPORTANT: Don't create an alias yourself - the install-shell command creates a function for you
+# Make sure to use your actual path to gw-tools
+deno run --allow-all ~/path/to/gw-tools/packages/gw-tool/src/main.ts install-shell \
+  --name gw-dev \
+  --command "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
+# Now you can use it anywhere with full shell integration
 cd ~/some-project
+gw-dev add feat-branch  # Output streams in real-time!
+gw-dev cd feat-branch   # Navigates to the worktree
 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)
+This gives you instant feedback - just edit the TypeScript files and run the command again. The shell integration provides the same experience as the installed version:
 
-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.
+- Real-time streaming output (no buffering)
+- `gw-dev cd` navigation support
+- Auto-navigation after `gw-dev add`
+- Auto-navigation to repo root after `gw-dev remove`
 
 ### Available Scripts
 
@@ -1190,6 +1187,7 @@ npm publish --access public
 For users who prefer Deno's native package manager.
 
 1. **Add JSR configuration to `deno.json`:**
+
    ```json
    {
      "name": "@your-scope/gw",
@@ -1281,15 +1279,16 @@ There are two types of commands you can add:
 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
    // src/commands/list.ts
    export async function executeList(args: string[]): Promise<void> {
      // Check for help flag
-     if (args.includes("--help") || args.includes("-h")) {
+     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
    `);
@@ -1302,8 +1301,9 @@ For commands with custom logic, follow the pattern used by existing commands:
    ```
 
 2. **Import and register** the command in `src/main.ts`:
+
    ```typescript
-   import { executeList } from "./commands/list.ts";
+   import { executeList } from './commands/list.ts';
 
    const COMMANDS = {
      add: executeAdd,
@@ -1333,18 +1333,18 @@ For commands with custom logic, follow the pattern used by existing commands:
 For simple pass-through commands that wrap git worktree operations, use the `git-proxy` utility:
 
 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'],
-       );
+       showProxyHelp('list', 'list', 'List all worktrees in the repository', [
+         'gw list',
+         'gw list --porcelain',
+         'gw list -v',
+       ]);
        Deno.exit(0);
      }
 
@@ -1359,6 +1359,7 @@ For simple pass-through commands that wrap git worktree operations, use the `git
 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

package/install.js

@@ -176,12 +176,28 @@ async function install() {
 async function installShellIntegration(binaryPath, retries = 3) {
   const { spawn } = require('child_process');
 
+  // Check environment before attempting shell integration
+  const hasRequiredEnv = process.env.HOME || process.env.USERPROFILE;
+  const hasShell = process.env.SHELL;
+
+  if (!hasRequiredEnv) {
+    console.log('  Skipping shell integration: HOME environment variable not set');
+    console.log('  Run "gw install-shell" manually after installation');
+    return;
+  }
+
+  if (!hasShell) {
+    console.log('  Skipping shell integration: SHELL environment variable not set');
+    console.log('  Run "gw install-shell" manually after installation');
+    return;
+  }
+
   return new Promise((resolve) => {
     let child;
 
     try {
-      child = spawn(binaryPath, ['install-shell', '--quiet'], {
-        stdio: 'inherit',
+      child = spawn(binaryPath, ['install-shell'], {
+        stdio: ['inherit', 'inherit', 'pipe'],  // stdin, stdout, stderr
       });
     } catch (err) {
       // Catch synchronous spawn errors (e.g., ETXTBSY thrown immediately)
@@ -191,20 +207,28 @@ async function installShellIntegration(binaryPath, retries = 3) {
         }, 200);
         return;
       }
-      console.log(
-        '  (Shell integration can be installed later with: gw install-shell)',
-      );
+      console.log('  Shell integration setup encountered an issue.');
+      console.log('  You can install it manually later with: gw install-shell');
       resolve();
       return;
     }
 
+    let stderrOutput = '';
+    child.stderr.on('data', (data) => {
+      stderrOutput += data.toString();
+      // Also display it immediately
+      process.stderr.write(data);
+    });
+
     child.on('close', (code) => {
       if (code === 0) {
         console.log('✓ Shell integration installed!');
       } else {
-        console.log(
-          '  (Shell integration can be installed later with: gw install-shell)',
-        );
+        console.log('  Shell integration failed with exit code:', code);
+        if (stderrOutput) {
+          console.log('  Error:', stderrOutput.trim());
+        }
+        console.log('  You can install it manually later with: gw install-shell');
       }
       resolve();
     });
@@ -215,9 +239,8 @@ async function installShellIntegration(binaryPath, retries = 3) {
         await new Promise((r) => setTimeout(r, 200));
         return installShellIntegration(binaryPath, retries - 1).then(resolve);
       }
-      console.log(
-        '  (Shell integration can be installed later with: gw install-shell)',
-      );
+      console.log('  Shell integration setup encountered an issue.');
+      console.log('  You can install it manually later with: gw install-shell');
       resolve();
     });
   });

package/package.json

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