@jasonfutch/worktree-manager 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jason Futch
+
+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,186 @@
+# Worktree Manager TUI/CLI
+
+A terminal app for managing git worktrees with AI assistance.
+
+## Features
+
+- **TUI Interface** - Full terminal UI built with blessed
+- **Git Worktree Management** - Create, list, and remove worktrees
+- **IDE Integration** - Open worktrees in VS Code, Cursor, Zed, and more
+- **AI Integration** - Launch Claude, Gemini, or Codex in any worktree
+- **Parallel Development** - Work on multiple features simultaneously
+- **Auto-Update Notifications** - Get notified when a new version is available
+
+## Requirements
+
+- Node.js >= 18
+- Git
+- Optional: VS Code, Cursor, Zed, Claude CLI
+
+## Installation
+
+```bash
+npm install -g @jasonfutch/worktree-manager
+```
+
+## Usage
+
+### Interactive TUI Mode
+
+```bash
+# Launch TUI in current directory
+wtm
+
+# Launch TUI for a specific repo
+wtm /path/to/repo
+```
+
+### Keybindings
+
+| Key     | Action                    |
+| ------- | ------------------------- |
+| `↑/k`   | Move up                   |
+| `↓/j`   | Move down                 |
+| `Enter` | Select/Details            |
+| `n`     | Create new worktree       |
+| `d`     | Delete worktree           |
+| `e`     | Open in editor (selector) |
+| `t`     | Open terminal             |
+| `a`     | Launch AI tool (selector) |
+| `r`     | Refresh                   |
+| `?`     | Help                      |
+| `q`     | Quit                      |
+
+### CLI Commands
+
+```bash
+# List all worktrees
+wtm list
+wtm list /path/to/repo
+
+# Create a new worktree
+wtm create feature/my-feature
+wtm create feature/my-feature -b main
+wtm create feature/my-feature -p /custom/path
+
+# Remove a worktree
+wtm remove feature/my-feature
+wtm remove feature/my-feature --force
+
+# Open worktree in editor
+wtm open feature/my-feature
+wtm open main -e cursor
+# Editors: code, cursor, zed, webstorm, subl, nvim
+
+# Open terminal in worktree
+wtm terminal feature/my-feature
+wtm term main
+
+# Launch AI tool in worktree
+wtm ai feature/my-feature
+wtm ai main -t gemini
+# Tools: claude, gemini, codex
+
+# Update to latest version
+wtm update
+
+# Show detailed help
+wtm help
+```
+
+## How It Works
+
+1. **Worktrees** - Uses `git worktree` to create isolated working directories for each branch
+2. **Parallel Development** - Each worktree is independent, allowing you to run different AI coding sessions
+3. **IDE Integration** - Opens editors in the worktree directory so your AI assistant has the right context
+4. **Terminal Sessions** - Opens new terminal windows/tabs in the worktree directory
+
+## Updating
+
+The CLI automatically checks for updates once per day and notifies you when a new version is available:
+
+```
+╭─────────────────────────────────────────────────╮
+│                                                 │
+│   Update available 1.0.0 → 1.1.0                │
+│   Run npm i -g @jasonfutch/worktree-manager     │
+│                                                 │
+╰─────────────────────────────────────────────────╯
+```
+
+You can also manually update at any time:
+
+```bash
+wtm update
+```
+
+## Screenshots
+
+### Main Interface
+
+![Main TUI](assets/screenshots/main-view.png)
+
+### Create New Worktree
+
+![Create Worktree](assets/screenshots/create-worktree.png)
+
+### Open In Editor
+
+![Editor Selector](assets/screenshots/editor-selector.png)
+
+### Open In AI Tool
+
+![AI Selector](assets/screenshots/ai-selector.png)
+
+---
+
+## Development
+
+### Installation from Source
+
+```bash
+git clone https://github.com/jasonfutch/worktree-manager
+cd worktree-manager
+npm install
+npm run build
+
+# Link globally for testing
+npm link
+```
+
+### Commands
+
+```bash
+npm run dev      # Run in development mode
+npm run build    # Build TypeScript
+npm run clean    # Clean build artifacts
+```
+
+## Architecture
+
+```
+worktree-manager/
+├── src/
+│   ├── index.ts          # CLI entry point
+│   ├── types.ts          # TypeScript types
+│   ├── errors.ts         # Custom error classes
+│   ├── constants.ts      # Application constants
+│   ├── version.ts        # Version from package.json
+│   ├── git/
+│   │   └── worktree.ts   # Git worktree operations
+│   ├── tui/
+│   │   └── app.ts        # Blessed TUI application
+│   └── utils/
+│       ├── helpers.ts    # Utility functions
+│       ├── shell.ts      # Shell escaping utilities
+│       ├── launch.ts     # Editor/terminal launchers
+│       └── checks.ts     # Startup validation
+├── dist/                 # Compiled output
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## License
+
+MIT

package/dist/constants.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Constants used throughout the worktree manager application
+ */
+/**
+ * UI-related constants
+ */
+export declare const UI: {
+    /** Maximum length for branch names in list display */
+    readonly BRANCH_TRUNCATE_LENGTH: 30;
+    /** Height of the help modal in lines */
+    readonly HELP_MODAL_HEIGHT: 26;
+    /** Height of the create worktree form in lines */
+    readonly CREATE_FORM_HEIGHT: 20;
+    /** Width of modal dialogs */
+    readonly MODAL_WIDTH: 50;
+    /** Width of the editor/AI selection dialog */
+    readonly SELECTOR_WIDTH: 40;
+    /** Height of the editor selection dialog */
+    readonly EDITOR_SELECTOR_HEIGHT: 12;
+    /** Height of the AI tool selection dialog */
+    readonly AI_SELECTOR_HEIGHT: 9;
+};
+/**
+ * Git-related constants
+ */
+export declare const GIT: {
+    /** Length of short SHA commit hash */
+    readonly SHORT_SHA_LENGTH: 7;
+    /** Default base branch name */
+    readonly DEFAULT_BASE_BRANCH: "main";
+    /** Directory name for worktrees relative to repo */
+    readonly WORKTREES_DIR: "worktrees";
+    /** Branches that should never be offered for deletion */
+    readonly PROTECTED_BRANCHES: readonly ["main", "master", "production", "prod", "dev", "develop", "development", "qa", "stage", "staging", "release", "hotfix"];
+};
+/**
+ * Regex patterns for parsing git output
+ */
+export declare const PATTERNS: {
+    /** Match commit SHA from porcelain output */
+    readonly COMMIT_SHA: RegExp;
+    /** Match worktree path from porcelain output */
+    readonly WORKTREE_PATH: RegExp;
+    /** Match branch from porcelain output */
+    readonly BRANCH_REF: RegExp;
+};
+/**
+ * Platform detection
+ */
+export declare const PLATFORM: {
+    readonly IS_MAC: boolean;
+    readonly IS_WIN: boolean;
+    readonly IS_LINUX: boolean;
+    readonly IS_WSL: boolean;
+};
+/**
+ * Editor types and their display names
+ */
+export declare const EDITORS: {
+    readonly code: {
+        readonly name: "VS Code";
+        readonly terminal: false;
+    };
+    readonly cursor: {
+        readonly name: "Cursor";
+        readonly terminal: false;
+    };
+    readonly zed: {
+        readonly name: "Zed";
+        readonly terminal: false;
+    };
+    readonly webstorm: {
+        readonly name: "WebStorm";
+        readonly terminal: false;
+    };
+    readonly subl: {
+        readonly name: "Sublime Text";
+        readonly terminal: false;
+    };
+    readonly nvim: {
+        readonly name: "Neovim";
+        readonly terminal: true;
+    };
+};
+/**
+ * AI tools and their display names
+ */
+export declare const AI_TOOLS: {
+    readonly claude: {
+        readonly name: "Claude";
+    };
+    readonly gemini: {
+        readonly name: "Gemini";
+    };
+    readonly codex: {
+        readonly name: "Codex";
+    };
+};
+/**
+ * Installation instructions by platform
+ */
+export declare const INSTALL_INSTRUCTIONS: {
+    readonly code: {
+        readonly darwin: "Open VS Code → Cmd+Shift+P → 'Shell Command: Install code'";
+        readonly win32: "Add VS Code to PATH during installation";
+        readonly linux: "Install via package manager or add to PATH";
+    };
+    readonly cursor: {
+        readonly darwin: "Open Cursor → Cmd+Shift+P → 'Shell Command: Install cursor'";
+        readonly win32: "Add Cursor to PATH during installation";
+        readonly linux: "Add Cursor to PATH";
+    };
+    readonly zed: {
+        readonly darwin: "Open Zed → Cmd+Shift+P → 'zed: Install CLI'";
+        readonly win32: "Zed CLI installation varies by setup";
+        readonly linux: "Zed CLI installation varies by setup";
+    };
+    readonly webstorm: {
+        readonly darwin: "Open WebStorm → Tools → Create Command-line Launcher";
+        readonly win32: "Add WebStorm to PATH";
+        readonly linux: "Add WebStorm to PATH";
+    };
+    readonly subl: {
+        readonly darwin: "See sublimetext.com/docs/command_line.html";
+        readonly win32: "See sublimetext.com/docs/command_line.html";
+        readonly linux: "See sublimetext.com/docs/command_line.html";
+    };
+    readonly nvim: {
+        readonly darwin: "Install via: brew install neovim";
+        readonly win32: "Install via: choco install neovim or scoop install neovim";
+        readonly linux: "Install via: apt install neovim or dnf install neovim";
+    };
+    readonly claude: {
+        readonly darwin: "Install Claude CLI: npm install -g @anthropic-ai/claude-code";
+        readonly win32: "Install Claude CLI: npm install -g @anthropic-ai/claude-code";
+        readonly linux: "Install Claude CLI: npm install -g @anthropic-ai/claude-code";
+    };
+    readonly gemini: {
+        readonly darwin: "Install Gemini CLI from Google";
+        readonly win32: "Install Gemini CLI from Google";
+        readonly linux: "Install Gemini CLI from Google";
+    };
+    readonly codex: {
+        readonly darwin: "Install Codex CLI from OpenAI";
+        readonly win32: "Install Codex CLI from OpenAI";
+        readonly linux: "Install Codex CLI from OpenAI";
+    };
+};
+/**
+ * Get install instruction for a tool on the current platform
+ */
+export declare function getInstallInstruction(tool: string): string;

package/dist/constants.js

@@ -0,0 +1,148 @@
+/**
+ * Constants used throughout the worktree manager application
+ */
+/**
+ * UI-related constants
+ */
+export const UI = {
+    /** Maximum length for branch names in list display */
+    BRANCH_TRUNCATE_LENGTH: 30,
+    /** Height of the help modal in lines */
+    HELP_MODAL_HEIGHT: 26,
+    /** Height of the create worktree form in lines */
+    CREATE_FORM_HEIGHT: 20,
+    /** Width of modal dialogs */
+    MODAL_WIDTH: 50,
+    /** Width of the editor/AI selection dialog */
+    SELECTOR_WIDTH: 40,
+    /** Height of the editor selection dialog */
+    EDITOR_SELECTOR_HEIGHT: 12,
+    /** Height of the AI tool selection dialog */
+    AI_SELECTOR_HEIGHT: 9,
+};
+/**
+ * Git-related constants
+ */
+export const GIT = {
+    /** Length of short SHA commit hash */
+    SHORT_SHA_LENGTH: 7,
+    /** Default base branch name */
+    DEFAULT_BASE_BRANCH: 'main',
+    /** Directory name for worktrees relative to repo */
+    WORKTREES_DIR: 'worktrees',
+    /** Branches that should never be offered for deletion */
+    PROTECTED_BRANCHES: [
+        'main',
+        'master',
+        'production',
+        'prod',
+        'dev',
+        'develop',
+        'development',
+        'qa',
+        'stage',
+        'staging',
+        'release',
+        'hotfix',
+    ],
+};
+/**
+ * Regex patterns for parsing git output
+ */
+export const PATTERNS = {
+    /** Match commit SHA from porcelain output */
+    COMMIT_SHA: /^HEAD ([a-f0-9]+)$/,
+    /** Match worktree path from porcelain output */
+    WORKTREE_PATH: /^worktree (.+)$/,
+    /** Match branch from porcelain output */
+    BRANCH_REF: /^branch refs\/heads\/(.+)$/,
+};
+/**
+ * Platform detection
+ */
+export const PLATFORM = {
+    IS_MAC: process.platform === 'darwin',
+    IS_WIN: process.platform === 'win32',
+    IS_LINUX: process.platform === 'linux',
+    IS_WSL: process.platform === 'linux' && !!process.env.WSL_DISTRO_NAME,
+};
+/**
+ * Editor types and their display names
+ */
+export const EDITORS = {
+    code: { name: 'VS Code', terminal: false },
+    cursor: { name: 'Cursor', terminal: false },
+    zed: { name: 'Zed', terminal: false },
+    webstorm: { name: 'WebStorm', terminal: false },
+    subl: { name: 'Sublime Text', terminal: false },
+    nvim: { name: 'Neovim', terminal: true },
+};
+/**
+ * AI tools and their display names
+ */
+export const AI_TOOLS = {
+    claude: { name: 'Claude' },
+    gemini: { name: 'Gemini' },
+    codex: { name: 'Codex' },
+};
+/**
+ * Installation instructions by platform
+ */
+export const INSTALL_INSTRUCTIONS = {
+    code: {
+        darwin: "Open VS Code → Cmd+Shift+P → 'Shell Command: Install code'",
+        win32: 'Add VS Code to PATH during installation',
+        linux: 'Install via package manager or add to PATH',
+    },
+    cursor: {
+        darwin: "Open Cursor → Cmd+Shift+P → 'Shell Command: Install cursor'",
+        win32: 'Add Cursor to PATH during installation',
+        linux: 'Add Cursor to PATH',
+    },
+    zed: {
+        darwin: "Open Zed → Cmd+Shift+P → 'zed: Install CLI'",
+        win32: 'Zed CLI installation varies by setup',
+        linux: 'Zed CLI installation varies by setup',
+    },
+    webstorm: {
+        darwin: 'Open WebStorm → Tools → Create Command-line Launcher',
+        win32: 'Add WebStorm to PATH',
+        linux: 'Add WebStorm to PATH',
+    },
+    subl: {
+        darwin: 'See sublimetext.com/docs/command_line.html',
+        win32: 'See sublimetext.com/docs/command_line.html',
+        linux: 'See sublimetext.com/docs/command_line.html',
+    },
+    nvim: {
+        darwin: 'Install via: brew install neovim',
+        win32: 'Install via: choco install neovim or scoop install neovim',
+        linux: 'Install via: apt install neovim or dnf install neovim',
+    },
+    claude: {
+        darwin: 'Install Claude CLI: npm install -g @anthropic-ai/claude-code',
+        win32: 'Install Claude CLI: npm install -g @anthropic-ai/claude-code',
+        linux: 'Install Claude CLI: npm install -g @anthropic-ai/claude-code',
+    },
+    gemini: {
+        darwin: 'Install Gemini CLI from Google',
+        win32: 'Install Gemini CLI from Google',
+        linux: 'Install Gemini CLI from Google',
+    },
+    codex: {
+        darwin: 'Install Codex CLI from OpenAI',
+        win32: 'Install Codex CLI from OpenAI',
+        linux: 'Install Codex CLI from OpenAI',
+    },
+};
+/**
+ * Get install instruction for a tool on the current platform
+ */
+export function getInstallInstruction(tool) {
+    const instructions = INSTALL_INSTRUCTIONS[tool];
+    if (!instructions) {
+        return `Install ${tool}`;
+    }
+    const platform = process.platform;
+    return instructions[platform] || instructions.darwin || `Install ${tool}`;
+}

package/dist/errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Custom error classes for better error handling and debugging
+ */
+/**
+ * Base error class for all worktree manager errors
+ */
+export declare class WorktreeManagerError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a git command fails
+ */
+export declare class GitCommandError extends WorktreeManagerError {
+    readonly command: string;
+    readonly stderr: string;
+    readonly exitCode: number | undefined;
+    constructor(message: string, command: string, stderr?: string, exitCode?: number);
+    /**
+     * Get a user-friendly error message
+     */
+    getUserMessage(): string;
+}
+/**
+ * Error thrown when a worktree is not found
+ */
+export declare class WorktreeNotFoundError extends WorktreeManagerError {
+    readonly worktreePath: string;
+    constructor(worktreePath: string);
+}
+/**
+ * Error thrown when a branch name is invalid
+ */
+export declare class InvalidBranchError extends WorktreeManagerError {
+    readonly branch: string;
+    readonly reason: string;
+    constructor(branch: string, reason?: string);
+}
+/**
+ * Error thrown when a path is invalid or contains traversal attempts
+ */
+export declare class InvalidPathError extends WorktreeManagerError {
+    readonly invalidPath: string;
+    readonly reason: string;
+    constructor(invalidPath: string, reason?: string);
+}
+/**
+ * Error thrown when an external tool (editor, terminal, AI) is not found
+ */
+export declare class ToolNotFoundError extends WorktreeManagerError {
+    readonly toolName: string;
+    readonly installHint: string;
+    constructor(toolName: string, installHint?: string);
+}
+/**
+ * Parse an error from git command execution into a GitCommandError
+ */
+export declare function parseGitError(error: unknown, command: string): GitCommandError;

package/dist/errors.js

@@ -0,0 +1,117 @@
+/**
+ * Custom error classes for better error handling and debugging
+ */
+/**
+ * Base error class for all worktree manager errors
+ */
+export class WorktreeManagerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WorktreeManagerError';
+        // Maintains proper stack trace for where error was thrown (V8 engines)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Error thrown when a git command fails
+ */
+export class GitCommandError extends WorktreeManagerError {
+    command;
+    stderr;
+    exitCode;
+    constructor(message, command, stderr = '', exitCode) {
+        super(message);
+        this.name = 'GitCommandError';
+        this.command = command;
+        this.stderr = stderr;
+        this.exitCode = exitCode;
+    }
+    /**
+     * Get a user-friendly error message
+     */
+    getUserMessage() {
+        // Parse common git errors into friendly messages
+        if (this.stderr.includes('not a git repository')) {
+            return 'This directory is not a git repository';
+        }
+        if (this.stderr.includes('already exists')) {
+            return 'A worktree or branch with this name already exists';
+        }
+        if (this.stderr.includes('is not a valid branch name')) {
+            return 'Invalid branch name. Branch names cannot contain spaces or special characters';
+        }
+        if (this.stderr.includes('invalid reference')) {
+            return 'The specified branch or commit does not exist';
+        }
+        if (this.stderr.includes('contains modified or untracked files')) {
+            return 'Worktree has uncommitted changes. Use force to delete anyway';
+        }
+        // Return original message if no specific parsing applies
+        return this.message;
+    }
+}
+/**
+ * Error thrown when a worktree is not found
+ */
+export class WorktreeNotFoundError extends WorktreeManagerError {
+    worktreePath;
+    constructor(worktreePath) {
+        super(`Worktree not found: ${worktreePath}`);
+        this.name = 'WorktreeNotFoundError';
+        this.worktreePath = worktreePath;
+    }
+}
+/**
+ * Error thrown when a branch name is invalid
+ */
+export class InvalidBranchError extends WorktreeManagerError {
+    branch;
+    reason;
+    constructor(branch, reason = 'Invalid branch name') {
+        super(`Invalid branch name "${branch}": ${reason}`);
+        this.name = 'InvalidBranchError';
+        this.branch = branch;
+        this.reason = reason;
+    }
+}
+/**
+ * Error thrown when a path is invalid or contains traversal attempts
+ */
+export class InvalidPathError extends WorktreeManagerError {
+    invalidPath;
+    reason;
+    constructor(invalidPath, reason = 'Invalid path') {
+        super(`Invalid path "${invalidPath}": ${reason}`);
+        this.name = 'InvalidPathError';
+        this.invalidPath = invalidPath;
+        this.reason = reason;
+    }
+}
+/**
+ * Error thrown when an external tool (editor, terminal, AI) is not found
+ */
+export class ToolNotFoundError extends WorktreeManagerError {
+    toolName;
+    installHint;
+    constructor(toolName, installHint = '') {
+        super(`${toolName} not found${installHint ? `. ${installHint}` : ''}`);
+        this.name = 'ToolNotFoundError';
+        this.toolName = toolName;
+        this.installHint = installHint;
+    }
+}
+/**
+ * Parse an error from git command execution into a GitCommandError
+ */
+export function parseGitError(error, command) {
+    if (error instanceof GitCommandError) {
+        return error;
+    }
+    const err = error;
+    const message = err.message || String(error);
+    const stderr = err.stderr || '';
+    const exitCode = typeof err.code === 'number' ? err.code : undefined;
+    return new GitCommandError(message, command, stderr, exitCode);
+}