@jasonfutch/worktree-manager 1.0.0

package/dist/git/worktree.d.ts

@@ -0,0 +1,57 @@
+import type { Worktree, CreateWorktreeOptions } from '../types.js';
+export declare class GitWorktree {
+    private repoPath;
+    constructor(repoPath: string);
+    /**
+     * Check if path is a valid git repository
+     */
+    static isGitRepo(dirPath: string): boolean;
+    /**
+     * Get the root of the git repository
+     */
+    static getRepoRoot(dirPath: string): string | null;
+    /**
+     * List all worktrees for this repository
+     */
+    list(): Promise<Worktree[]>;
+    /**
+     * Create a new worktree
+     */
+    create(options: CreateWorktreeOptions): Promise<Worktree>;
+    /**
+     * Remove a worktree
+     */
+    remove(worktreePath: string, force?: boolean): Promise<void>;
+    /**
+     * Prune worktrees (clean up stale entries)
+     */
+    prune(): Promise<void>;
+    /**
+     * Delete a branch
+     * @param branch - Branch name to delete
+     * @param force - If true, use -D (force delete) instead of -d
+     */
+    deleteBranch(branch: string, force?: boolean): Promise<void>;
+    /**
+     * Check if a branch exists
+     * @returns true if branch exists, false otherwise
+     * @note This method returns false on any error (including invalid branch names)
+     */
+    private branchExists;
+    /**
+     * Get list of all local branches
+     * @returns Array of branch names, empty array on error
+     * @note This method returns empty array on any error
+     */
+    getBranches(): Promise<string[]>;
+    /**
+     * Get current branch name
+     * @returns Current branch name, or 'unknown' on error
+     * @note This method returns 'unknown' on any error
+     */
+    getCurrentBranch(): Promise<string>;
+    /**
+     * Get repo name
+     */
+    getRepoName(): string;
+}

package/dist/git/worktree.js

@@ -0,0 +1,272 @@
+import { execSync, exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+import fs from 'fs';
+import { WorktreeNotFoundError, InvalidBranchError, InvalidPathError, parseGitError, } from '../errors.js';
+import { isPathSafe, isValidBranchName, escapeShellArg } from '../utils/shell.js';
+import { GIT } from '../constants.js';
+const execAsync = promisify(exec);
+export class GitWorktree {
+    repoPath;
+    constructor(repoPath) {
+        this.repoPath = repoPath;
+    }
+    /**
+     * Check if path is a valid git repository
+     */
+    static isGitRepo(dirPath) {
+        try {
+            execSync('git rev-parse --git-dir', { cwd: dirPath, stdio: 'pipe' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get the root of the git repository
+     */
+    static getRepoRoot(dirPath) {
+        try {
+            const result = execSync('git rev-parse --show-toplevel', {
+                cwd: dirPath,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe']
+            });
+            return result.trim();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * List all worktrees for this repository
+     */
+    async list() {
+        const command = 'git worktree list --porcelain';
+        try {
+            const { stdout } = await execAsync(command, {
+                cwd: this.repoPath
+            });
+            const worktrees = [];
+            const entries = stdout.trim().split('\n\n');
+            for (const entry of entries) {
+                if (!entry.trim())
+                    continue;
+                const lines = entry.split('\n');
+                const worktree = {
+                    isMain: false,
+                    isBare: false,
+                    isLocked: false,
+                    prunable: false,
+                };
+                for (const line of lines) {
+                    if (line.startsWith('worktree ')) {
+                        worktree.path = line.substring(9);
+                        worktree.name = path.basename(worktree.path);
+                    }
+                    else if (line.startsWith('HEAD ')) {
+                        // Extract SHA safely - handle variable length commits
+                        const sha = line.substring(5);
+                        worktree.commit = sha.substring(0, GIT.SHORT_SHA_LENGTH);
+                    }
+                    else if (line.startsWith('branch ')) {
+                        // Parse branch reference more robustly
+                        const ref = line.substring(7);
+                        worktree.branch = ref.replace(/^refs\/heads\//, '');
+                    }
+                    else if (line === 'bare') {
+                        worktree.isBare = true;
+                    }
+                    else if (line === 'locked') {
+                        worktree.isLocked = true;
+                    }
+                    else if (line.startsWith('locked ')) {
+                        worktree.isLocked = true;
+                        worktree.lockedReason = line.substring(7);
+                    }
+                    else if (line === 'prunable') {
+                        worktree.prunable = true;
+                    }
+                    else if (line === 'detached') {
+                        worktree.branch = 'HEAD (detached)';
+                    }
+                }
+                // Check if this is the main worktree
+                if (worktree.path === this.repoPath) {
+                    worktree.isMain = true;
+                }
+                if (worktree.path && worktree.commit) {
+                    worktrees.push(worktree);
+                }
+            }
+            return worktrees;
+        }
+        catch (error) {
+            throw parseGitError(error, command);
+        }
+    }
+    /**
+     * Create a new worktree
+     */
+    async create(options) {
+        const { branch, baseBranch = GIT.DEFAULT_BASE_BRANCH, path: customPath } = options;
+        // Validate branch name
+        if (!isValidBranchName(branch)) {
+            throw new InvalidBranchError(branch, 'Branch names cannot contain spaces, .., or special characters');
+        }
+        // Generate worktree path if not provided
+        const worktreePath = customPath || path.join(path.dirname(this.repoPath), GIT.WORKTREES_DIR, branch.replace(/\//g, '-'));
+        // Validate path doesn't contain traversal attempts
+        const repoParent = path.dirname(this.repoPath);
+        if (!isPathSafe(worktreePath, repoParent)) {
+            throw new InvalidPathError(worktreePath, 'Path contains invalid characters or traversal attempts');
+        }
+        // Ensure parent directory exists
+        const parentDir = path.dirname(worktreePath);
+        if (!fs.existsSync(parentDir)) {
+            fs.mkdirSync(parentDir, { recursive: true });
+        }
+        try {
+            // Check if branch exists
+            const branchExists = await this.branchExists(branch);
+            // Use escaped arguments for safety
+            const escapedPath = escapeShellArg(worktreePath);
+            const escapedBranch = escapeShellArg(branch);
+            const escapedBase = escapeShellArg(baseBranch);
+            let command;
+            if (branchExists) {
+                // Checkout existing branch
+                command = `git worktree add ${escapedPath} ${escapedBranch}`;
+            }
+            else {
+                // Create new branch from base
+                command = `git worktree add -b ${escapedBranch} ${escapedPath} ${escapedBase}`;
+            }
+            await execAsync(command, { cwd: this.repoPath });
+            // Get the created worktree info
+            const worktrees = await this.list();
+            const created = worktrees.find(wt => wt.path === worktreePath);
+            if (!created) {
+                throw new WorktreeNotFoundError(worktreePath);
+            }
+            return created;
+        }
+        catch (error) {
+            if (error instanceof WorktreeNotFoundError) {
+                throw error;
+            }
+            throw parseGitError(error, `git worktree add ${branch}`);
+        }
+    }
+    /**
+     * Remove a worktree
+     */
+    async remove(worktreePath, force = false) {
+        // Validate path
+        if (!isPathSafe(worktreePath)) {
+            throw new InvalidPathError(worktreePath, 'Path contains invalid characters');
+        }
+        const escapedPath = escapeShellArg(worktreePath);
+        const forceFlag = force ? '--force' : '';
+        const command = `git worktree remove ${forceFlag} ${escapedPath}`;
+        try {
+            await execAsync(command, { cwd: this.repoPath });
+        }
+        catch (error) {
+            const gitError = parseGitError(error, command);
+            // Check if it's a not-found error
+            if (gitError.stderr.includes('is not a working tree')) {
+                throw new WorktreeNotFoundError(worktreePath);
+            }
+            throw gitError;
+        }
+    }
+    /**
+     * Prune worktrees (clean up stale entries)
+     */
+    async prune() {
+        const command = 'git worktree prune';
+        try {
+            await execAsync(command, { cwd: this.repoPath });
+        }
+        catch (error) {
+            throw parseGitError(error, command);
+        }
+    }
+    /**
+     * Delete a branch
+     * @param branch - Branch name to delete
+     * @param force - If true, use -D (force delete) instead of -d
+     */
+    async deleteBranch(branch, force = false) {
+        if (!isValidBranchName(branch)) {
+            throw new InvalidBranchError(branch, 'Invalid branch name');
+        }
+        const escapedBranch = escapeShellArg(branch);
+        const flag = force ? '-D' : '-d';
+        const command = `git branch ${flag} ${escapedBranch}`;
+        try {
+            await execAsync(command, { cwd: this.repoPath });
+        }
+        catch (error) {
+            throw parseGitError(error, command);
+        }
+    }
+    /**
+     * Check if a branch exists
+     * @returns true if branch exists, false otherwise
+     * @note This method returns false on any error (including invalid branch names)
+     */
+    async branchExists(branch) {
+        try {
+            const escapedBranch = escapeShellArg(branch);
+            await execAsync(`git rev-parse --verify ${escapedBranch}`, {
+                cwd: this.repoPath
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get list of all local branches
+     * @returns Array of branch names, empty array on error
+     * @note This method returns empty array on any error
+     */
+    async getBranches() {
+        try {
+            const { stdout } = await execAsync('git branch -a --format="%(refname:short)"', {
+                cwd: this.repoPath
+            });
+            return stdout.trim().split('\n').filter(b => b && !b.startsWith('origin/'));
+        }
+        catch {
+            // Return empty array on error - caller should handle empty results
+            return [];
+        }
+    }
+    /**
+     * Get current branch name
+     * @returns Current branch name, or 'unknown' on error
+     * @note This method returns 'unknown' on any error
+     */
+    async getCurrentBranch() {
+        try {
+            const { stdout } = await execAsync('git branch --show-current', {
+                cwd: this.repoPath
+            });
+            return stdout.trim();
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    /**
+     * Get repo name
+     */
+    getRepoName() {
+        return path.basename(this.repoPath);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { GitWorktree } from './git/worktree.js';
+import { WorktreeManagerTUI } from './tui/app.js';
+import { runStartupChecks } from './utils/checks.js';
+import { openEditor, openTerminal, launchAI, validEditors, validAITools } from './utils/launch.js';
+import chalk from 'chalk';
+import path from 'path';
+import fs from 'fs';
+import readline from 'readline';
+import { GIT } from './constants.js';
+import { VERSION, PACKAGE_NAME, pkg } from './version.js';
+import updateNotifier from 'update-notifier';
+import { execSync } from 'child_process';
+// Check dependencies before anything else
+runStartupChecks();
+// Check for updates (runs in background, notifies if update available)
+const notifier = updateNotifier({ pkg, updateCheckInterval: 1000 * 60 * 60 * 24 }); // Check daily
+notifier.notify({ isGlobal: true });
+// Helper to prompt user for input
+function promptUser(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+// Helper to check if a branch is protected
+function isProtectedBranch(branch) {
+    const normalizedBranch = branch.toLowerCase();
+    return GIT.PROTECTED_BRANCHES.some(protectedBranch => normalizedBranch === protectedBranch.toLowerCase());
+}
+const program = new Command();
+program
+    .name('worktree-manager')
+    .description('Terminal app for managing git worktrees with AI assistance')
+    .version(VERSION)
+    .argument('[path]', 'Path to git repository', '.')
+    .action(async (repoPath) => {
+    const resolvedPath = path.resolve(repoPath);
+    // Validate path exists
+    if (!fs.existsSync(resolvedPath)) {
+        console.error(chalk.red(`Error: Path does not exist: ${resolvedPath}`));
+        process.exit(1);
+    }
+    // Validate it's a git repo
+    if (!GitWorktree.isGitRepo(resolvedPath)) {
+        console.error(chalk.red(`Error: Not a git repository: ${resolvedPath}`));
+        process.exit(1);
+    }
+    // Get the repo root (in case user passed a subdirectory)
+    const repoRoot = GitWorktree.getRepoRoot(resolvedPath);
+    if (!repoRoot) {
+        console.error(chalk.red(`Error: Could not determine git repository root`));
+        process.exit(1);
+    }
+    // Launch TUI
+    const tui = new WorktreeManagerTUI(repoRoot);
+    await tui.start();
+});
+// Subcommand: list worktrees (non-interactive)
+program
+    .command('list')
+    .description('List all worktrees (non-interactive)')
+    .argument('[path]', 'Path to git repository', '.')
+    .action(async (repoPath) => {
+    const resolvedPath = path.resolve(repoPath);
+    const repoRoot = GitWorktree.getRepoRoot(resolvedPath);
+    if (!repoRoot) {
+        console.error(chalk.red('Not a git repository'));
+        process.exit(1);
+    }
+    const git = new GitWorktree(repoRoot);
+    const worktrees = await git.list();
+    console.log(chalk.cyan.bold('\n  Git Worktrees\n'));
+    for (const wt of worktrees) {
+        const mainBadge = wt.isMain ? chalk.green(' [main]') : '';
+        const lockBadge = wt.isLocked ? chalk.red(' [locked]') : '';
+        console.log(`  ${chalk.yellow('●')} ${chalk.bold(wt.branch)}${mainBadge}${lockBadge}`);
+        console.log(`    ${chalk.gray('Path:')} ${wt.path}`);
+        console.log(`    ${chalk.gray('Commit:')} ${wt.commit}\n`);
+    }
+});
+// Subcommand: create worktree
+program
+    .command('create <branch>')
+    .description('Create a new worktree')
+    .argument('[path]', 'Path to git repository', '.')
+    .option('-b, --base <branch>', 'Base branch to create from', 'main')
+    .option('-p, --path <path>', 'Custom path for the worktree')
+    .action(async (branch, repoPath, options) => {
+    const resolvedPath = path.resolve(repoPath || '.');
+    const repoRoot = GitWorktree.getRepoRoot(resolvedPath);
+    if (!repoRoot) {
+        console.error(chalk.red('Not a git repository'));
+        process.exit(1);
+    }
+    const git = new GitWorktree(repoRoot);
+    console.log(chalk.cyan(`Creating worktree for branch: ${branch}...`));
+    try {
+        const wt = await git.create({
+            branch,
+            baseBranch: options.base,
+            path: options.path
+        });
+        console.log(chalk.green(`✓ Created worktree: ${wt.path}`));
+    }
+    catch (error) {
+        console.error(chalk.red(`Error: ${error}`));
+        process.exit(1);
+    }
+});
+// Subcommand: remove worktree
+program
+    .command('remove <branch-or-path>')
+    .description('Remove a worktree')
+    .argument('[repo-path]', 'Path to git repository', '.')
+    .option('-f, --force', 'Force removal even with local changes')
+    .action(async (branchOrPath, repoPath, options) => {
+    const resolvedPath = path.resolve(repoPath || '.');
+    const repoRoot = GitWorktree.getRepoRoot(resolvedPath);
+    if (!repoRoot) {
+        console.error(chalk.red('Not a git repository'));
+        process.exit(1);
+    }
+    const git = new GitWorktree(repoRoot);
+    const worktrees = await git.list();
+    // Find worktree by branch name or path
+    const wt = worktrees.find(w => w.branch === branchOrPath ||
+        w.path === branchOrPath ||
+        w.path.endsWith(branchOrPath));
+    if (!wt) {
+        console.error(chalk.red(`Worktree not found: ${branchOrPath}`));
+        process.exit(1);
+    }
+    if (wt.isMain) {
+        console.error(chalk.red('Cannot remove main worktree'));
+        process.exit(1);
+    }
+    const branchName = wt.branch;
+    console.log(chalk.yellow(`Removing worktree: ${branchName}...`));
+    try {
+        await git.remove(wt.path, options.force);
+        console.log(chalk.green(`✓ Removed worktree: ${branchName}`));
+        // Ask about branch deletion (only for non-protected branches)
+        if (!isProtectedBranch(branchName)) {
+            const answer = await promptUser(chalk.yellow(`\nAlso delete branch "${branchName}"? Type "yes" to confirm (or press Enter to skip): `));
+            if (answer === 'yes') {
+                console.log(chalk.yellow(`Deleting branch: ${branchName}...`));
+                try {
+                    await git.deleteBranch(branchName, true);
+                    console.log(chalk.green(`✓ Deleted branch: ${branchName}`));
+                }
+                catch (branchError) {
+                    console.error(chalk.yellow(`⚠ Branch deletion failed: ${branchError}`));
+                }
+            }
+            else {
+                console.log(chalk.gray(`Branch "${branchName}" kept.`));
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red(`Error: ${error}`));
+        process.exit(1);
+    }
+});
+// Helper to find worktree by branch or path
+async function findWorktree(branchOrPath, repoPath) {
+    const resolvedPath = path.resolve(repoPath || '.');
+    const repoRoot = GitWorktree.getRepoRoot(resolvedPath);
+    if (!repoRoot) {
+        console.error(chalk.red('Not a git repository'));
+        process.exit(1);
+    }
+    const git = new GitWorktree(repoRoot);
+    const worktrees = await git.list();
+    const wt = worktrees.find(w => w.branch === branchOrPath ||
+        w.path === branchOrPath ||
+        w.path.endsWith(branchOrPath) ||
+        w.name === branchOrPath);
+    if (!wt) {
+        console.error(chalk.red(`Worktree not found: ${branchOrPath}`));
+        process.exit(1);
+    }
+    return wt;
+}
+// Subcommand: open worktree in editor
+program
+    .command('open <branch-or-path>')
+    .description('Open a worktree in an editor')
+    .argument('[repo-path]', 'Path to git repository', '.')
+    .option('-e, --editor <editor>', `Editor to use (${validEditors.join(', ')})`, 'code')
+    .action(async (branchOrPath, repoPath, options) => {
+    const editor = options.editor;
+    if (!validEditors.includes(editor)) {
+        console.error(chalk.red(`Invalid editor: ${editor}`));
+        console.error(chalk.gray(`Valid options: ${validEditors.join(', ')}`));
+        process.exit(1);
+    }
+    const wt = await findWorktree(branchOrPath, repoPath);
+    console.log(chalk.cyan(`Opening ${wt.branch} in ${editor}...`));
+    openEditor(wt.path, editor);
+});
+// Subcommand: open terminal in worktree
+program
+    .command('terminal <branch-or-path>')
+    .alias('term')
+    .description('Open a terminal in a worktree')
+    .argument('[repo-path]', 'Path to git repository', '.')
+    .action(async (branchOrPath, repoPath) => {
+    const wt = await findWorktree(branchOrPath, repoPath);
+    console.log(chalk.cyan(`Opening terminal in ${wt.branch}...`));
+    openTerminal(wt.path);
+});
+// Subcommand: launch AI tool in worktree
+program
+    .command('ai <branch-or-path>')
+    .description('Launch an AI tool in a worktree')
+    .argument('[repo-path]', 'Path to git repository', '.')
+    .option('-t, --tool <tool>', `AI tool to use (${validAITools.join(', ')})`, 'claude')
+    .action(async (branchOrPath, repoPath, options) => {
+    const tool = options.tool;
+    if (!validAITools.includes(tool)) {
+        console.error(chalk.red(`Invalid AI tool: ${tool}`));
+        console.error(chalk.gray(`Valid options: ${validAITools.join(', ')}`));
+        process.exit(1);
+    }
+    const wt = await findWorktree(branchOrPath, repoPath);
+    console.log(chalk.cyan(`Launching ${tool} in ${wt.branch}...`));
+    launchAI(wt.path, tool);
+});
+// Subcommand: help with examples
+program
+    .command('help')
+    .description('Show detailed help and examples')
+    .action(() => {
+    console.log(`
+${chalk.cyan.bold('Worktree Manager')} - Terminal app for managing git worktrees
+
+${chalk.yellow.bold('QUICK START')}
+  ${chalk.gray('Launch TUI in current repo:')}
+  $ ${chalk.green('wtm')}
+
+  ${chalk.gray('Launch TUI for specific repo:')}
+  $ ${chalk.green('wtm /path/to/repo')}
+
+${chalk.yellow.bold('CLI COMMANDS')}
+
+  ${chalk.cyan('wtm list')} ${chalk.gray('[path]')}
+    List all worktrees
+    $ wtm list
+    $ wtm list /path/to/repo
+
+  ${chalk.cyan('wtm create')} ${chalk.white('<branch>')} ${chalk.gray('[path] [-b base] [-p path]')}
+    Create a new worktree
+    $ wtm create feature/login
+    $ wtm create feature/api -b develop
+    $ wtm create bugfix/issue-42 -p /custom/path
+
+  ${chalk.cyan('wtm remove')} ${chalk.white('<branch>')} ${chalk.gray('[path] [-f]')}
+    Remove a worktree
+    $ wtm remove feature/login
+    $ wtm remove feature/old --force
+
+  ${chalk.cyan('wtm open')} ${chalk.white('<branch>')} ${chalk.gray('[path] [-e editor]')}
+    Open worktree in editor
+    $ wtm open feature/login
+    $ wtm open main -e cursor
+    ${chalk.gray('Editors: code, cursor, zed, webstorm, subl, nvim')}
+
+  ${chalk.cyan('wtm terminal')} ${chalk.white('<branch>')} ${chalk.gray('[path]')}
+    Open terminal in worktree
+    $ wtm terminal feature/login
+    $ wtm term main
+
+  ${chalk.cyan('wtm ai')} ${chalk.white('<branch>')} ${chalk.gray('[path] [-t tool]')}
+    Launch AI tool in worktree
+    $ wtm ai feature/login
+    $ wtm ai main -t gemini
+    ${chalk.gray('Tools: claude, gemini, codex')}
+
+  ${chalk.cyan('wtm update')}
+    Update to the latest version
+    $ wtm update
+
+${chalk.yellow.bold('TUI KEYBINDINGS')}
+  ${chalk.cyan('↑/k, ↓/j')}    Navigate worktrees
+  ${chalk.cyan('Enter')}       Show details
+  ${chalk.cyan('n')}           Create new worktree
+  ${chalk.cyan('d')}           Delete worktree
+  ${chalk.cyan('e')}           Open in editor
+  ${chalk.cyan('t')}           Open terminal
+  ${chalk.cyan('a')}           Launch AI tool
+  ${chalk.cyan('r')}           Refresh list
+  ${chalk.cyan('?')}           Show help
+  ${chalk.cyan('q')}           Quit
+`);
+});
+// Subcommand: update to latest version
+program
+    .command('update')
+    .description('Update to the latest version')
+    .action(() => {
+    console.log(chalk.cyan(`\nCurrent version: ${VERSION}`));
+    console.log(chalk.gray('Checking for updates...\n'));
+    try {
+        // Check npm for latest version
+        const latestVersion = execSync(`npm view ${PACKAGE_NAME} version`, { encoding: 'utf-8' }).trim();
+        if (latestVersion === VERSION) {
+            console.log(chalk.green(`✓ Already on the latest version (${VERSION})`));
+            return;
+        }
+        console.log(chalk.yellow(`New version available: ${latestVersion}`));
+        console.log(chalk.gray(`Updating ${PACKAGE_NAME}...\n`));
+        // Run the update
+        execSync(`npm install -g ${PACKAGE_NAME}@latest`, { stdio: 'inherit' });
+        console.log(chalk.green(`\n✓ Successfully updated to ${latestVersion}`));
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('npm view')) {
+            console.error(chalk.red('Error: Could not check for updates. Package may not be published yet.'));
+        }
+        else {
+            console.error(chalk.red(`Error updating: ${error instanceof Error ? error.message : error}`));
+            console.log(chalk.gray(`\nTry manually: npm install -g ${PACKAGE_NAME}@latest`));
+        }
+        process.exit(1);
+    }
+});
+program.parse();