@jasonfutch/worktree-manager 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Type definitions for the worktree manager
+ */
+/**
+ * Represents a git worktree
+ */
+export interface Worktree {
+    /** Absolute filesystem path to the worktree */
+    path: string;
+    /** Branch name, or "HEAD (detached)" for detached HEAD state */
+    branch: string;
+    /** Short SHA of the current commit (7 characters) */
+    commit: string;
+    /** Whether this is the main worktree (same path as repo root) */
+    isMain: boolean;
+    /** Whether this is a bare repository */
+    isBare: boolean;
+    /** Whether the worktree is locked */
+    isLocked: boolean;
+    /** Reason for lock, if locked with a reason */
+    lockedReason?: string;
+    /** Whether the worktree is prunable (stale) */
+    prunable?: boolean;
+    /** Friendly name derived from path basename */
+    name: string;
+}
+/**
+ * Options for creating a new worktree
+ */
+export interface CreateWorktreeOptions {
+    /** Name of the branch to create or checkout */
+    branch: string;
+    /** Base branch to create new branch from (default: 'main') */
+    baseBranch?: string;
+    /** Custom path for the worktree (default: auto-generated) */
+    path?: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for the worktree manager
+ */
+export {};

package/dist/utils/checks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Check if Git is installed and accessible
+ */
+export declare function checkGitInstalled(): boolean;
+/**
+ * Check if Node.js version meets minimum requirement
+ */
+export declare function checkNodeVersion(): boolean;
+/**
+ * Run all startup checks and exit with helpful messages if any fail
+ */
+export declare function runStartupChecks(): void;

package/dist/utils/checks.js

@@ -0,0 +1,109 @@
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+const MIN_NODE_VERSION = 18;
+/**
+ * Check if Git is installed and accessible
+ */
+export function checkGitInstalled() {
+    try {
+        execSync('git --version', { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if Node.js version meets minimum requirement
+ */
+export function checkNodeVersion() {
+    const currentVersion = parseInt(process.versions.node.split('.')[0], 10);
+    return currentVersion >= MIN_NODE_VERSION;
+}
+/**
+ * Get current Node.js version string
+ */
+function getNodeVersion() {
+    return process.versions.node;
+}
+/**
+ * Detect platform for install instructions
+ */
+function getPlatform() {
+    if (process.platform === 'darwin')
+        return 'mac';
+    if (process.platform === 'win32')
+        return 'win';
+    return 'linux';
+}
+/**
+ * Run all startup checks and exit with helpful messages if any fail
+ */
+export function runStartupChecks() {
+    const errors = [];
+    const platform = getPlatform();
+    // Check Git
+    if (!checkGitInstalled()) {
+        let installInstructions = '';
+        if (platform === 'mac') {
+            installInstructions = `
+  ${chalk.cyan('macOS:')}
+    brew install git
+    ${chalk.gray('or install Xcode Command Line Tools:')} xcode-select --install`;
+        }
+        else if (platform === 'win') {
+            installInstructions = `
+  ${chalk.cyan('Windows:')}
+    Download from: ${chalk.underline('https://git-scm.com/download/win')}
+    ${chalk.gray('or use:')} winget install Git.Git`;
+        }
+        else {
+            installInstructions = `
+  ${chalk.cyan('Ubuntu/Debian:')} sudo apt install git
+  ${chalk.cyan('Fedora:')}        sudo dnf install git
+  ${chalk.cyan('Arch:')}          sudo pacman -S git`;
+        }
+        errors.push(`
+${chalk.red.bold('Git is not installed or not in PATH.')}
+
+${chalk.yellow('Install Git:')}${installInstructions}
+`);
+    }
+    // Check Node version
+    if (!checkNodeVersion()) {
+        let updateInstructions = '';
+        if (platform === 'mac') {
+            updateInstructions = `
+  ${chalk.cyan('macOS:')}
+    brew upgrade node
+    ${chalk.gray('or use nvm:')} nvm install 18`;
+        }
+        else if (platform === 'win') {
+            updateInstructions = `
+  ${chalk.cyan('Windows:')}
+    Download from: ${chalk.underline('https://nodejs.org/')}
+    ${chalk.gray('or use:')} winget upgrade OpenJS.NodeJS.LTS`;
+        }
+        else {
+            updateInstructions = `
+  ${chalk.cyan('Linux:')}
+    Download from: ${chalk.underline('https://nodejs.org/')}
+    ${chalk.gray('or use nvm:')} nvm install 18`;
+        }
+        errors.push(`
+${chalk.red.bold(`Node.js ${MIN_NODE_VERSION}+ is required.`)} ${chalk.gray(`You have: ${getNodeVersion()}`)}
+
+${chalk.yellow('Update Node.js:')}${updateInstructions}
+`);
+    }
+    // If any errors, print them and exit
+    if (errors.length > 0) {
+        console.error(chalk.red.bold('\n  Dependency Check Failed\n'));
+        console.error(chalk.gray('─'.repeat(50)));
+        for (const error of errors) {
+            console.error(error);
+        }
+        console.error(chalk.gray('─'.repeat(50)));
+        process.exit(1);
+    }
+}

package/dist/utils/helpers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Helper utilities for the worktree manager
+ */
+/**
+ * Get a truncated string with ellipsis
+ */
+export declare function truncate(str: string, maxLength: number): string;
+/**
+ * Format a relative path from a base path
+ */
+export declare function formatPath(fullPath: string, basePath: string): string;

package/dist/utils/helpers.js

@@ -0,0 +1,20 @@
+/**
+ * Helper utilities for the worktree manager
+ */
+/**
+ * Get a truncated string with ellipsis
+ */
+export function truncate(str, maxLength) {
+    if (str.length <= maxLength)
+        return str;
+    return str.slice(0, maxLength - 3) + '...';
+}
+/**
+ * Format a relative path from a base path
+ */
+export function formatPath(fullPath, basePath) {
+    if (fullPath.startsWith(basePath)) {
+        return fullPath.slice(basePath.length + 1) || '.';
+    }
+    return fullPath;
+}

package/dist/utils/launch.d.ts

@@ -0,0 +1,17 @@
+import { EDITORS, AI_TOOLS } from '../constants.js';
+export type EditorType = keyof typeof EDITORS;
+export type AIToolType = keyof typeof AI_TOOLS;
+/**
+ * Open a path in an editor
+ */
+export declare function openEditor(targetPath: string, editor: EditorType, onError?: (message: string) => void, onSuccess?: (message: string) => void): void;
+/**
+ * Open a terminal at a path
+ */
+export declare function openTerminal(targetPath: string, onError?: (message: string) => void, onSuccess?: (message: string) => void): void;
+/**
+ * Launch an AI tool at a path
+ */
+export declare function launchAI(targetPath: string, tool: AIToolType, onError?: (message: string) => void, onSuccess?: (message: string) => void): void;
+export declare const validEditors: EditorType[];
+export declare const validAITools: AIToolType[];

package/dist/utils/launch.js

@@ -0,0 +1,223 @@
+import { spawn } from 'child_process';
+import chalk from 'chalk';
+import { escapeAppleScript, escapeWindowsArg } from './shell.js';
+import { PLATFORM, getInstallInstruction, EDITORS } from '../constants.js';
+import { ToolNotFoundError } from '../errors.js';
+const editorNames = {
+    code: 'VS Code',
+    cursor: 'Cursor',
+    zed: 'Zed',
+    webstorm: 'WebStorm',
+    subl: 'Sublime Text',
+    nvim: 'Neovim'
+};
+const aiToolNames = {
+    claude: 'Claude',
+    gemini: 'Gemini',
+    codex: 'Codex'
+};
+/**
+ * Open a path in an editor
+ */
+export function openEditor(targetPath, editor, onError, onSuccess) {
+    const name = editorNames[editor];
+    const editorConfig = EDITORS[editor];
+    const isTerminalEditor = editorConfig?.terminal ?? false;
+    const handleError = (err) => {
+        if (err.code === 'ENOENT') {
+            const hint = getInstallInstruction(editor);
+            const message = `${name} not found. ${hint}`;
+            if (onError)
+                onError(message);
+            else
+                console.error(chalk.red(message));
+        }
+        else {
+            const message = `Error: ${err.message}`;
+            if (onError)
+                onError(message);
+            else
+                console.error(chalk.red(message));
+        }
+    };
+    try {
+        let proc;
+        if (isTerminalEditor) {
+            if (PLATFORM.IS_MAC) {
+                // Escape the path for AppleScript context
+                const escapedPath = escapeAppleScript(targetPath);
+                const script = `
+          tell application "Terminal"
+            do script "cd '${escapedPath}' && ${editor} ."
+            activate
+          end tell
+        `;
+                proc = spawn('osascript', ['-e', script], { detached: true, stdio: 'ignore' });
+            }
+            else if (PLATFORM.IS_WIN) {
+                // Escape the path for Windows cmd context
+                const escapedPath = escapeWindowsArg(targetPath);
+                proc = spawn('cmd', ['/c', 'start', 'cmd', '/k', `cd /d ${escapedPath} && ${editor} .`], {
+                    detached: true,
+                    stdio: 'ignore',
+                    shell: true
+                });
+            }
+            else {
+                // Linux - pass path directly to gnome-terminal which handles it safely
+                proc = spawn('gnome-terminal', ['--working-directory', targetPath, '--', editor, '.'], {
+                    detached: true,
+                    stdio: 'ignore'
+                });
+            }
+        }
+        else {
+            // GUI editors can open directly - spawn with array args (safe)
+            proc = spawn(editor, [targetPath], { detached: true, stdio: 'ignore' });
+        }
+        proc.on('error', handleError);
+        proc.unref();
+        const successMsg = `Opened in ${name}`;
+        if (onSuccess)
+            onSuccess(successMsg);
+        else
+            console.log(chalk.green(`✓ ${successMsg}`));
+    }
+    catch (error) {
+        const message = `Error: ${error instanceof Error ? error.message : error}`;
+        if (onError)
+            onError(message);
+        else
+            console.error(chalk.red(message));
+    }
+}
+/**
+ * Open a terminal at a path
+ */
+export function openTerminal(targetPath, onError, onSuccess) {
+    try {
+        if (PLATFORM.IS_MAC) {
+            // macOS Terminal.app - use open command with path as argument (safe)
+            spawn('open', ['-a', 'Terminal', targetPath], { detached: true, stdio: 'ignore' });
+        }
+        else if (PLATFORM.IS_WIN) {
+            // Windows - escape path for cmd.exe
+            const escapedPath = escapeWindowsArg(targetPath);
+            spawn('cmd', ['/c', 'start', 'cmd', '/k', `cd /d ${escapedPath}`], {
+                detached: true,
+                stdio: 'ignore',
+                shell: true
+            });
+        }
+        else if (PLATFORM.IS_WSL) {
+            // WSL - pass path directly to wt.exe
+            spawn('wt.exe', ['-d', targetPath], { detached: true, stdio: 'ignore' });
+        }
+        else {
+            // Linux - try common terminal emulators
+            const terminals = ['gnome-terminal', 'konsole', 'xterm', 'terminator'];
+            let launched = false;
+            for (const term of terminals) {
+                try {
+                    const proc = spawn(term, ['--working-directory', targetPath], {
+                        detached: true,
+                        stdio: 'ignore'
+                    });
+                    proc.on('error', () => {
+                        // Silently fail and try next terminal
+                    });
+                    proc.unref();
+                    launched = true;
+                    break;
+                }
+                catch {
+                    // Try next terminal
+                }
+            }
+            if (!launched) {
+                throw new ToolNotFoundError('Terminal emulator', 'Install gnome-terminal, konsole, xterm, or terminator');
+            }
+        }
+        const successMsg = 'Opened terminal';
+        if (onSuccess)
+            onSuccess(successMsg);
+        else
+            console.log(chalk.green(`✓ ${successMsg}`));
+    }
+    catch (error) {
+        if (error instanceof ToolNotFoundError) {
+            if (onError)
+                onError(error.message);
+            else
+                console.error(chalk.red(error.message));
+        }
+        else {
+            const message = `Error: ${error instanceof Error ? error.message : error}`;
+            if (onError)
+                onError(message);
+            else
+                console.error(chalk.red(message));
+        }
+    }
+}
+/**
+ * Launch an AI tool at a path
+ */
+export function launchAI(targetPath, tool, onError, onSuccess) {
+    const name = aiToolNames[tool];
+    try {
+        let proc;
+        if (PLATFORM.IS_MAC) {
+            // Escape the path for AppleScript context
+            const escapedPath = escapeAppleScript(targetPath);
+            const script = `
+        tell application "Terminal"
+          do script "cd '${escapedPath}' && ${tool}"
+          activate
+        end tell
+      `;
+            proc = spawn('osascript', ['-e', script], { detached: true, stdio: 'ignore' });
+        }
+        else if (PLATFORM.IS_WIN) {
+            // Escape the path for Windows cmd context
+            const escapedPath = escapeWindowsArg(targetPath);
+            proc = spawn('cmd', ['/c', 'start', 'cmd', '/k', `cd /d ${escapedPath} && ${tool}`], {
+                detached: true,
+                stdio: 'ignore',
+                shell: true
+            });
+        }
+        else {
+            // Linux - pass arguments safely via array
+            proc = spawn('gnome-terminal', ['--working-directory', targetPath, '--', tool], {
+                detached: true,
+                stdio: 'ignore'
+            });
+        }
+        proc.on('error', (err) => {
+            if (err.code === 'ENOENT') {
+                const hint = getInstallInstruction(tool);
+                const message = `${name} not found. ${hint}`;
+                if (onError)
+                    onError(message);
+                else
+                    console.error(chalk.red(message));
+            }
+        });
+        proc.unref();
+        const successMsg = `Launched ${name}`;
+        if (onSuccess)
+            onSuccess(successMsg);
+        else
+            console.log(chalk.green(`✓ ${successMsg}`));
+    }
+    catch (error) {
+        const message = `Error: ${error instanceof Error ? error.message : error}`;
+        if (onError)
+            onError(message);
+        else
+            console.error(chalk.red(message));
+    }
+}
+export const validEditors = ['code', 'cursor', 'zed', 'webstorm', 'subl', 'nvim'];
+export const validAITools = ['claude', 'gemini', 'codex'];

package/dist/utils/shell.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shell escaping utilities to prevent command injection
+ */
+/**
+ * Escape a string for use as a shell argument (POSIX shells)
+ * Wraps the argument in single quotes and escapes any existing single quotes
+ */
+export declare function escapeShellArg(arg: string): string;
+/**
+ * Escape a string for use in AppleScript
+ * Handles single quotes, double quotes, and backslashes
+ */
+export declare function escapeAppleScript(str: string): string;
+/**
+ * Escape a string for use in Windows cmd.exe
+ * Handles special characters that need escaping in batch scripts
+ */
+export declare function escapeWindowsArg(arg: string): string;
+/**
+ * Validate that a path doesn't contain path traversal attempts
+ * @returns true if the path is safe, false if it contains suspicious patterns
+ */
+export declare function isPathSafe(targetPath: string, basePath?: string): boolean;
+/**
+ * Validate a git branch name
+ * Based on git-check-ref-format rules
+ */
+export declare function isValidBranchName(branch: string): boolean;

package/dist/utils/shell.js

@@ -0,0 +1,94 @@
+/**
+ * Shell escaping utilities to prevent command injection
+ */
+import path from 'path';
+/**
+ * Escape a string for use as a shell argument (POSIX shells)
+ * Wraps the argument in single quotes and escapes any existing single quotes
+ */
+export function escapeShellArg(arg) {
+    // Replace single quotes with '\'' (end quote, escaped quote, start quote)
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Escape a string for use in AppleScript
+ * Handles single quotes, double quotes, and backslashes
+ */
+export function escapeAppleScript(str) {
+    // In AppleScript strings, escape backslashes and quotes
+    return str
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/"/g, '\\"');
+}
+/**
+ * Escape a string for use in Windows cmd.exe
+ * Handles special characters that need escaping in batch scripts
+ */
+export function escapeWindowsArg(arg) {
+    // For cmd.exe, we need to handle special characters
+    // Wrap in double quotes and escape internal double quotes
+    return `"${arg.replace(/"/g, '""')}"`;
+}
+/**
+ * Validate that a path doesn't contain path traversal attempts
+ * @returns true if the path is safe, false if it contains suspicious patterns
+ */
+export function isPathSafe(targetPath, basePath) {
+    // Check for obvious path traversal patterns
+    if (targetPath.includes('..')) {
+        return false;
+    }
+    // Check for null bytes (can be used to bypass security checks)
+    if (targetPath.includes('\0')) {
+        return false;
+    }
+    // If a base path is provided, ensure target is within it
+    if (basePath) {
+        const resolved = path.resolve(targetPath);
+        const resolvedBase = path.resolve(basePath);
+        // Target should start with base path
+        if (!resolved.startsWith(resolvedBase + path.sep) && resolved !== resolvedBase) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Validate a git branch name
+ * Based on git-check-ref-format rules
+ */
+export function isValidBranchName(branch) {
+    // Can't be empty
+    if (!branch || branch.length === 0) {
+        return false;
+    }
+    // Can't start or end with /
+    if (branch.startsWith('/') || branch.endsWith('/')) {
+        return false;
+    }
+    // Can't contain consecutive slashes
+    if (branch.includes('//')) {
+        return false;
+    }
+    // Can't contain special characters
+    const forbidden = ['..', ' ', '~', '^', ':', '?', '*', '[', '\\', '\x7f'];
+    for (const char of forbidden) {
+        if (branch.includes(char)) {
+            return false;
+        }
+    }
+    // Can't start with a dash
+    if (branch.startsWith('-')) {
+        return false;
+    }
+    // Can't end with .lock
+    if (branch.endsWith('.lock')) {
+        return false;
+    }
+    // Can't contain @{
+    if (branch.includes('@{')) {
+        return false;
+    }
+    return true;
+}

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+export declare const VERSION: string;
+export declare const PACKAGE_NAME: string;
+export declare const pkg: {
+    name: string;
+    version: string;
+};

package/dist/version.js

@@ -0,0 +1,11 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Read version from package.json
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+export const VERSION = packageJson.version;
+export const PACKAGE_NAME = packageJson.name;
+export const pkg = packageJson;

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@jasonfutch/worktree-manager",
+  "version": "1.0.0",
+  "description": "Terminal app for managing git worktrees with AI assistance",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "wtm": "dist/index.js",
+    "worktree-manager": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "clean": "rm -rf dist",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "git",
+    "worktree",
+    "terminal",
+    "tui",
+    "cli",
+    "claude",
+    "ai",
+    "vscode",
+    "cursor"
+  ],
+  "author": "jasonfutch",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jasonfutch/worktree-manager.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jasonfutch/worktree-manager/issues"
+  },
+  "homepage": "https://github.com/jasonfutch/worktree-manager#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "blessed": "^0.1.81",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "update-notifier": "^7.3.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/blessed": "^0.1.27",
+    "@types/node": "^25.0.3",
+    "@types/update-notifier": "^6.0.8",
+    "eslint": "^9.17.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.18.2"
+  }
+}