@aku11i/phantom 0.8.1 → 1.0.0

package/dist/phantom.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/bin/phantom.ts
-import { argv, exit } from "node:process";
+import { argv, exit as exit2 } from "node:process";
 
 // src/cli/handlers/attach.ts
 import { parseArgs } from "node:util";
@@ -67,6 +67,18 @@ var err = (error) => ({
 var isOk = (result) => result.ok;
 var isErr = (result) => !result.ok;
 
+// src/core/worktree/validate.ts
+import fs from "node:fs/promises";
+
+// src/core/paths.ts
+import { join } from "node:path";
+function getPhantomDirectory(gitRoot) {
+  return join(gitRoot, ".git", "phantom", "worktrees");
+}
+function getWorktreePath(gitRoot, name) {
+  return join(getPhantomDirectory(gitRoot), name);
+}
+
 // src/core/worktree/errors.ts
 var WorktreeError = class extends Error {
   constructor(message) {
@@ -99,58 +111,39 @@ var BranchNotFoundError = class extends WorktreeError {
   }
 };
 
-// src/core/worktree/validate.ts
-import fs from "node:fs/promises";
-
-// src/core/paths.ts
-import { join } from "node:path";
-function getPhantomDirectory(gitRoot) {
-  return join(gitRoot, ".git", "phantom", "worktrees");
-}
-function getWorktreePath(gitRoot, name) {
-  return join(getPhantomDirectory(gitRoot), name);
-}
-
 // src/core/worktree/validate.ts
 async function validateWorktreeExists(gitRoot, name) {
   const worktreePath = getWorktreePath(gitRoot, name);
   try {
     await fs.access(worktreePath);
-    return {
-      exists: true,
-      path: worktreePath
-    };
+    return ok({ path: worktreePath });
   } catch {
-    return {
-      exists: false,
-      message: `Worktree '${name}' does not exist`
-    };
+    return err(new WorktreeNotFoundError(name));
   }
 }
 async function validateWorktreeDoesNotExist(gitRoot, name) {
   const worktreePath = getWorktreePath(gitRoot, name);
   try {
     await fs.access(worktreePath);
-    return {
-      exists: true,
-      message: `Worktree '${name}' already exists`
-    };
+    return err(new WorktreeAlreadyExistsError(name));
   } catch {
-    return {
-      exists: false,
-      path: worktreePath
-    };
+    return ok({ path: worktreePath });
   }
 }
 function validateWorktreeName(name) {
   if (!name || name.trim() === "") {
     return err(new Error("Phantom name cannot be empty"));
   }
-  if (name.includes("/")) {
-    return err(new Error("Phantom name cannot contain slashes"));
+  const validNamePattern = /^[a-zA-Z0-9\-_.\/]+$/;
+  if (!validNamePattern.test(name)) {
+    return err(
+      new Error(
+        "Phantom name can only contain letters, numbers, hyphens, underscores, dots, and slashes"
+      )
+    );
   }
-  if (name.startsWith(".")) {
-    return err(new Error("Phantom name cannot start with a dot"));
+  if (name.includes("..")) {
+    return err(new Error("Phantom name cannot contain consecutive dots"));
   }
   return ok(void 0);
 }
@@ -218,10 +211,10 @@ async function spawnProcess(config) {
 // src/core/process/exec.ts
 async function execInWorktree(gitRoot, worktreeName, command2, options = {}) {
   const validation = await validateWorktreeExists(gitRoot, worktreeName);
-  if (!validation.exists) {
-    return err(new WorktreeNotFoundError(worktreeName));
+  if (isErr(validation)) {
+    return err(validation.error);
   }
-  const worktreePath = validation.path;
+  const worktreePath = validation.value.path;
   const [cmd, ...args2] = command2;
   const stdio = options.interactive ? "inherit" : ["ignore", "inherit", "inherit"];
   return spawnProcess({
@@ -234,13 +227,22 @@ async function execInWorktree(gitRoot, worktreeName, command2, options = {}) {
   });
 }
 
+// src/core/process/env.ts
+function getPhantomEnv(worktreeName, worktreePath) {
+  return {
+    PHANTOM: "1",
+    PHANTOM_NAME: worktreeName,
+    PHANTOM_PATH: worktreePath
+  };
+}
+
 // src/core/process/shell.ts
 async function shellInWorktree(gitRoot, worktreeName) {
   const validation = await validateWorktreeExists(gitRoot, worktreeName);
-  if (!validation.exists) {
-    return err(new WorktreeNotFoundError(worktreeName));
+  if (isErr(validation)) {
+    return err(validation.error);
   }
-  const worktreePath = validation.path;
+  const worktreePath = validation.value.path;
   const shell = process.env.SHELL || "/bin/sh";
   return spawnProcess({
     command: shell,
@@ -249,9 +251,7 @@ async function shellInWorktree(gitRoot, worktreeName) {
       cwd: worktreePath,
       env: {
         ...process.env,
-        PHANTOM: "1",
-        PHANTOM_NAME: worktreeName,
-        PHANTOM_PATH: worktreePath
+        ...getPhantomEnv(worktreeName, worktreePath)
       }
     }
   });
@@ -406,10 +406,11 @@ async function attachHandler(args2) {
       exitWithError(shellResult.error.message, exitCodes.generalError);
     }
   } else if (values.exec) {
+    const shell = process.env.SHELL || "/bin/sh";
     const execResult = await execInWorktree(
       gitRoot,
       branchName,
-      values.exec.split(" "),
+      [shell, "-c", values.exec],
       { interactive: true }
     );
     if (isErr(execResult)) {
@@ -418,6 +419,198 @@ async function attachHandler(args2) {
   }
 }
 
+// src/cli/handlers/completion.ts
+import { exit } from "node:process";
+var FISH_COMPLETION_SCRIPT = `# Fish completion for phantom
+# Place this in ~/.config/fish/completions/phantom.fish
+
+function __phantom_list_worktrees
+    phantom list --names 2>/dev/null
+end
+
+function __phantom_using_command
+    set -l cmd (commandline -opc)
+    set -l cmd_count (count $cmd)
+    if test $cmd_count -eq 1
+        # No subcommand yet, so any command can be used
+        if test (count $argv) -eq 0
+            return 0
+        else
+            return 1
+        end
+    else if test $cmd_count -ge 2
+        # Check if we're in the context of a specific command
+        if test (count $argv) -gt 0 -a "$argv[1]" = "$cmd[2]"
+            return 0
+        end
+    end
+    return 1
+end
+
+# Disable file completion for phantom
+complete -c phantom -f
+
+# Main commands
+complete -c phantom -n "__phantom_using_command" -a "create" -d "Create a new Git worktree (phantom)"
+complete -c phantom -n "__phantom_using_command" -a "attach" -d "Attach to an existing branch by creating a new worktree"
+complete -c phantom -n "__phantom_using_command" -a "list" -d "List all Git worktrees (phantoms)"
+complete -c phantom -n "__phantom_using_command" -a "where" -d "Output the filesystem path of a specific worktree"
+complete -c phantom -n "__phantom_using_command" -a "delete" -d "Delete a Git worktree (phantom)"
+complete -c phantom -n "__phantom_using_command" -a "exec" -d "Execute a command in a worktree directory"
+complete -c phantom -n "__phantom_using_command" -a "shell" -d "Open an interactive shell in a worktree directory"
+complete -c phantom -n "__phantom_using_command" -a "version" -d "Display phantom version information"
+complete -c phantom -n "__phantom_using_command" -a "completion" -d "Generate shell completion scripts"
+
+# Global options
+complete -c phantom -l help -d "Show help (-h)"
+complete -c phantom -l version -d "Show version (-v)"
+
+# create command options
+complete -c phantom -n "__phantom_using_command create" -l shell -d "Open an interactive shell in the new worktree after creation (-s)"
+complete -c phantom -n "__phantom_using_command create" -l exec -d "Execute a command in the new worktree after creation (-x)" -x
+complete -c phantom -n "__phantom_using_command create" -l tmux -d "Open the worktree in a new tmux window (-t)"
+complete -c phantom -n "__phantom_using_command create" -l tmux-vertical -d "Open the worktree in a vertical tmux pane"
+complete -c phantom -n "__phantom_using_command create" -l tmux-horizontal -d "Open the worktree in a horizontal tmux pane"
+complete -c phantom -n "__phantom_using_command create" -l copy-file -d "Copy specified files from the current worktree" -r
+
+# attach command options
+complete -c phantom -n "__phantom_using_command attach" -l shell -d "Open an interactive shell in the worktree after attaching (-s)"
+complete -c phantom -n "__phantom_using_command attach" -l exec -d "Execute a command in the worktree after attaching (-x)" -x
+
+# list command options
+complete -c phantom -n "__phantom_using_command list" -l fzf -d "Use fzf for interactive selection"
+complete -c phantom -n "__phantom_using_command list" -l names -d "Output only phantom names (for scripts and completion)"
+
+# where command options
+complete -c phantom -n "__phantom_using_command where" -l fzf -d "Use fzf for interactive selection"
+complete -c phantom -n "__phantom_using_command where" -a "(__phantom_list_worktrees)"
+
+# delete command options
+complete -c phantom -n "__phantom_using_command delete" -l force -d "Force deletion even if worktree has uncommitted changes (-f)"
+complete -c phantom -n "__phantom_using_command delete" -l current -d "Delete the current worktree"
+complete -c phantom -n "__phantom_using_command delete" -l fzf -d "Use fzf for interactive selection"
+complete -c phantom -n "__phantom_using_command delete" -a "(__phantom_list_worktrees)"
+
+# exec command - accept worktree names and then any command
+complete -c phantom -n "__phantom_using_command exec" -a "(__phantom_list_worktrees)"
+
+# shell command options
+complete -c phantom -n "__phantom_using_command shell" -l fzf -d "Use fzf for interactive selection"
+complete -c phantom -n "__phantom_using_command shell" -a "(__phantom_list_worktrees)"
+
+# completion command - shell names
+complete -c phantom -n "__phantom_using_command completion" -a "fish zsh" -d "Shell type"`;
+var ZSH_COMPLETION_SCRIPT = `#compdef phantom
+# Zsh completion for phantom
+# Place this in a directory in your $fpath (e.g., ~/.zsh/completions/)
+# Or load dynamically with: eval "$(phantom completion zsh)"
+
+# Only define the function, don't execute it
+_phantom() {
+    local -a commands
+    commands=(
+        'create:Create a new Git worktree (phantom)'
+        'attach:Attach to an existing branch by creating a new worktree'
+        'list:List all Git worktrees (phantoms)'
+        'where:Output the filesystem path of a specific worktree'
+        'delete:Delete a Git worktree (phantom)'
+        'exec:Execute a command in a worktree directory'
+        'shell:Open an interactive shell in a worktree directory'
+        'version:Display phantom version information'
+        'completion:Generate shell completion scripts'
+    )
+
+    _arguments -C \\
+        '--help[Show help (-h)]' \\
+        '--version[Show version (-v)]' \\
+        '1:command:->command' \\
+        '*::arg:->args'
+
+    case \${state} in
+        command)
+            _describe 'phantom command' commands
+            ;;
+        args)
+            case \${line[1]} in
+                create)
+                    _arguments \\
+                        '--shell[Open an interactive shell in the new worktree after creation (-s)]' \\
+                        '--exec[Execute a command in the new worktree after creation (-x)]:command:' \\
+                        '--tmux[Open the worktree in a new tmux window (-t)]' \\
+                        '--tmux-vertical[Open the worktree in a vertical tmux pane]' \\
+                        '--tmux-horizontal[Open the worktree in a horizontal tmux pane]' \\
+                        '*--copy-file[Copy specified files from the current worktree]:file:_files' \\
+                        '1:name:'
+                    ;;
+                attach)
+                    _arguments \\
+                        '--shell[Open an interactive shell in the worktree after attaching (-s)]' \\
+                        '--exec[Execute a command in the worktree after attaching (-x)]:command:' \\
+                        '1:worktree-name:' \\
+                        '2:branch-name:'
+                    ;;
+                list)
+                    _arguments \\
+                        '--fzf[Use fzf for interactive selection]' \\
+                        '--names[Output only phantom names (for scripts and completion)]'
+                    ;;
+                where|delete|shell)
+                    local worktrees
+                    worktrees=(\${(f)"$(phantom list --names 2>/dev/null)"})
+                    if [[ \${line[1]} == "where" || \${line[1]} == "shell" ]]; then
+                        _arguments \\
+                            '--fzf[Use fzf for interactive selection]' \\
+                            '1:worktree:(\${(q)worktrees[@]})'
+                    elif [[ \${line[1]} == "delete" ]]; then
+                        _arguments \\
+                            '--force[Force deletion even if worktree has uncommitted changes (-f)]' \\
+                            '--current[Delete the current worktree]' \\
+                            '--fzf[Use fzf for interactive selection]' \\
+                            '1:worktree:(\${(q)worktrees[@]})'
+                    fi
+                    ;;
+                exec)
+                    local worktrees
+                    worktrees=(\${(f)"$(phantom list --names 2>/dev/null)"})
+                    _arguments \\
+                        '1:worktree:(\${(q)worktrees[@]})' \\
+                        '*:command:_command_names'
+                    ;;
+                completion)
+                    _arguments \\
+                        '1:shell:(fish zsh)'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+# Register the completion function if loading dynamically
+if [[ -n \${ZSH_VERSION} ]]; then
+    autoload -Uz compinit && compinit -C
+    compdef _phantom phantom
+fi`;
+function completionHandler(args2) {
+  const shell = args2[0];
+  if (!shell) {
+    output.error("Usage: phantom completion <shell>");
+    output.error("Supported shells: fish, zsh");
+    exit(1);
+  }
+  switch (shell.toLowerCase()) {
+    case "fish":
+      console.log(FISH_COMPLETION_SCRIPT);
+      break;
+    case "zsh":
+      console.log(ZSH_COMPLETION_SCRIPT);
+      break;
+    default:
+      output.error(`Unsupported shell: ${shell}`);
+      output.error("Supported shells: fish, zsh");
+      exit(1);
+  }
+}
+
 // src/cli/handlers/create.ts
 import { parseArgs as parseArgs2 } from "node:util";
 
@@ -523,11 +716,14 @@ async function isInsideTmux() {
   return process.env.TMUX !== void 0;
 }
 async function executeTmuxCommand(options) {
-  const { direction, command: command2, cwd, env } = options;
+  const { direction, command: command2, args: args2, cwd, env, windowName } = options;
   const tmuxArgs = [];
   switch (direction) {
     case "new":
       tmuxArgs.push("new-window");
+      if (windowName) {
+        tmuxArgs.push("-n", windowName);
+      }
       break;
     case "vertical":
       tmuxArgs.push("split-window", "-v");
@@ -545,6 +741,9 @@ async function executeTmuxCommand(options) {
     }
   }
   tmuxArgs.push(command2);
+  if (args2 && args2.length > 0) {
+    tmuxArgs.push(...args2);
+  }
   const result = await spawnProcess({
     command: "tmux",
     args: tmuxArgs
@@ -619,8 +818,8 @@ async function createWorktree(gitRoot, name, options = {}) {
     await fs3.mkdir(worktreesPath, { recursive: true });
   }
   const validation = await validateWorktreeDoesNotExist(gitRoot, name);
-  if (validation.exists) {
-    return err(new WorktreeAlreadyExistsError(name));
+  if (isErr(validation)) {
+    return err(validation.error);
   }
   try {
     await addWorktree({
@@ -825,11 +1024,8 @@ Opening worktree '${worktreeName}' in tmux ${tmuxDirection === "new" ? "window"
         direction: tmuxDirection,
         command: shell,
         cwd: result.value.path,
-        env: {
-          PHANTOM: "1",
-          PHANTOM_NAME: worktreeName,
-          PHANTOM_PATH: result.value.path
-        }
+        env: getPhantomEnv(worktreeName, result.value.path),
+        windowName: tmuxDirection === "new" ? worktreeName : void 0
       });
       if (isErr(tmuxResult)) {
         output.error(tmuxResult.error.message);
@@ -956,10 +1152,10 @@ async function deleteBranch(gitRoot, branchName) {
 async function deleteWorktree(gitRoot, name, options = {}) {
   const { force = false } = options;
   const validation = await validateWorktreeExists(gitRoot, name);
-  if (!validation.exists) {
-    return err(new WorktreeNotFoundError(name));
+  if (isErr(validation)) {
+    return err(validation.error);
   }
-  const worktreePath = validation.path;
+  const worktreePath = validation.value.path;
   const status = await getWorktreeStatus(worktreePath);
   if (status.hasUncommittedChanges && !force) {
     return err(
@@ -1114,7 +1310,7 @@ async function selectWorktreeWithFzf(gitRoot) {
   });
   const fzfResult = await selectWithFzf(list, {
     prompt: "Select worktree> ",
-    header: "Git Worktrees (Phantoms)"
+    header: "Git Worktrees"
   });
   if (isErr(fzfResult)) {
     return fzfResult;
@@ -1228,21 +1424,106 @@ async function deleteHandler(args2) {
 // src/cli/handlers/exec.ts
 import { parseArgs as parseArgs4 } from "node:util";
 async function execHandler(args2) {
-  const { positionals } = parseArgs4({
+  const { positionals, values } = parseArgs4({
     args: args2,
-    options: {},
+    options: {
+      fzf: {
+        type: "boolean",
+        default: false
+      },
+      tmux: {
+        type: "boolean",
+        short: "t"
+      },
+      "tmux-vertical": {
+        type: "boolean"
+      },
+      "tmux-v": {
+        type: "boolean"
+      },
+      "tmux-horizontal": {
+        type: "boolean"
+      },
+      "tmux-h": {
+        type: "boolean"
+      }
+    },
     strict: true,
     allowPositionals: true
   });
-  if (positionals.length < 2) {
-    exitWithError(
-      "Usage: phantom exec <worktree-name> <command> [args...]",
-      exitCodes.validationError
-    );
+  const useFzf = values.fzf ?? false;
+  const tmuxOption = values.tmux || values["tmux-vertical"] || values["tmux-v"] || values["tmux-horizontal"] || values["tmux-h"];
+  let tmuxDirection;
+  if (values.tmux) {
+    tmuxDirection = "new";
+  } else if (values["tmux-vertical"] || values["tmux-v"]) {
+    tmuxDirection = "vertical";
+  } else if (values["tmux-horizontal"] || values["tmux-h"]) {
+    tmuxDirection = "horizontal";
+  }
+  let commandArgs;
+  if (useFzf) {
+    if (positionals.length < 1) {
+      exitWithError(
+        "Usage: phantom exec --fzf <command> [args...]",
+        exitCodes.validationError
+      );
+    }
+    commandArgs = positionals;
+  } else {
+    if (positionals.length < 2) {
+      exitWithError(
+        "Usage: phantom exec <worktree-name> <command> [args...]",
+        exitCodes.validationError
+      );
+    }
+    commandArgs = positionals.slice(1);
   }
-  const [worktreeName, ...commandArgs] = positionals;
   try {
     const gitRoot = await getGitRoot();
+    if (tmuxOption && !await isInsideTmux()) {
+      exitWithError(
+        "The --tmux option can only be used inside a tmux session",
+        exitCodes.validationError
+      );
+    }
+    let worktreeName;
+    if (useFzf) {
+      const selectResult = await selectWorktreeWithFzf(gitRoot);
+      if (isErr(selectResult)) {
+        exitWithError(selectResult.error.message, exitCodes.generalError);
+      }
+      if (!selectResult.value) {
+        exitWithSuccess();
+      }
+      worktreeName = selectResult.value.name;
+    } else {
+      worktreeName = positionals[0];
+    }
+    const validation = await validateWorktreeExists(gitRoot, worktreeName);
+    if (isErr(validation)) {
+      exitWithError(validation.error.message, exitCodes.generalError);
+    }
+    if (tmuxDirection) {
+      output.log(
+        `Executing command in worktree '${worktreeName}' in tmux ${tmuxDirection === "new" ? "window" : "pane"}...`
+      );
+      const [command2, ...args3] = commandArgs;
+      const tmuxResult = await executeTmuxCommand({
+        direction: tmuxDirection,
+        command: command2,
+        args: args3,
+        cwd: validation.value.path,
+        env: getPhantomEnv(worktreeName, validation.value.path),
+        windowName: tmuxDirection === "new" ? worktreeName : void 0
+      });
+      if (isErr(tmuxResult)) {
+        output.error(tmuxResult.error.message);
+        const exitCode = "exitCode" in tmuxResult.error ? tmuxResult.error.exitCode ?? exitCodes.generalError : exitCodes.generalError;
+        exitWithError("", exitCode);
+      }
+      exitWithSuccess();
+    }
     const result = await execInWorktree(
       gitRoot,
       worktreeName,
@@ -1336,12 +1617,37 @@ async function shellHandler(args2) {
       fzf: {
         type: "boolean",
         default: false
+      },
+      tmux: {
+        type: "boolean",
+        short: "t"
+      },
+      "tmux-vertical": {
+        type: "boolean"
+      },
+      "tmux-v": {
+        type: "boolean"
+      },
+      "tmux-horizontal": {
+        type: "boolean"
+      },
+      "tmux-h": {
+        type: "boolean"
       }
     },
     strict: true,
     allowPositionals: true
   });
   const useFzf = values.fzf ?? false;
+  const tmuxOption = values.tmux || values["tmux-vertical"] || values["tmux-v"] || values["tmux-horizontal"] || values["tmux-h"];
+  let tmuxDirection;
+  if (values.tmux) {
+    tmuxDirection = "new";
+  } else if (values["tmux-vertical"] || values["tmux-v"]) {
+    tmuxDirection = "vertical";
+  } else if (values["tmux-horizontal"] || values["tmux-h"]) {
+    tmuxDirection = "horizontal";
+  }
   if (positionals.length === 0 && !useFzf) {
     exitWithError(
       "Usage: phantom shell <worktree-name> or phantom shell --fzf",
@@ -1357,6 +1663,12 @@ async function shellHandler(args2) {
   let worktreeName;
   try {
     const gitRoot = await getGitRoot();
+    if (tmuxOption && !await isInsideTmux()) {
+      exitWithError(
+        "The --tmux option can only be used inside a tmux session",
+        exitCodes.validationError
+      );
+    }
     if (useFzf) {
       const selectResult = await selectWorktreeWithFzf(gitRoot);
       if (isErr(selectResult)) {
@@ -1370,13 +1682,31 @@ async function shellHandler(args2) {
       worktreeName = positionals[0];
     }
     const validation = await validateWorktreeExists(gitRoot, worktreeName);
-    if (!validation.exists) {
-      exitWithError(
-        validation.message || `Worktree '${worktreeName}' not found`,
-        exitCodes.generalError
+    if (isErr(validation)) {
+      exitWithError(validation.error.message, exitCodes.generalError);
+    }
+    if (tmuxDirection) {
+      output.log(
+        `Opening worktree '${worktreeName}' in tmux ${tmuxDirection === "new" ? "window" : "pane"}...`
       );
+      const shell = process.env.SHELL || "/bin/sh";
+      const tmuxResult = await executeTmuxCommand({
+        direction: tmuxDirection,
+        command: shell,
+        cwd: validation.value.path,
+        env: getPhantomEnv(worktreeName, validation.value.path),
+        windowName: tmuxDirection === "new" ? worktreeName : void 0
+      });
+      if (isErr(tmuxResult)) {
+        output.error(tmuxResult.error.message);
+        const exitCode = "exitCode" in tmuxResult.error ? tmuxResult.error.exitCode ?? exitCodes.generalError : exitCodes.generalError;
+        exitWithError("", exitCode);
+      }
+      exitWithSuccess();
     }
-    output.log(`Entering worktree '${worktreeName}' at ${validation.path}`);
+    output.log(
+      `Entering worktree '${worktreeName}' at ${validation.value.path}`
+    );
     output.log("Type 'exit' to return to your original directory\n");
     const result = await shellInWorktree(gitRoot, worktreeName);
     if (isErr(result)) {
@@ -1399,7 +1729,7 @@ import { parseArgs as parseArgs7 } from "node:util";
 var package_default = {
   name: "@aku11i/phantom",
   packageManager: "pnpm@10.8.1",
-  version: "0.8.1",
+  version: "1.0.0",
   description: "A powerful CLI tool for managing Git worktrees for parallel development",
   keywords: [
     "git",
@@ -1479,11 +1809,11 @@ import { parseArgs as parseArgs8 } from "node:util";
 // src/core/worktree/where.ts
 async function whereWorktree(gitRoot, name) {
   const validation = await validateWorktreeExists(gitRoot, name);
-  if (!validation.exists) {
-    return err(new WorktreeNotFoundError(name));
+  if (isErr(validation)) {
+    return err(validation.error);
   }
   return ok({
-    path: validation.path
+    path: validation.value.path
   });
 }
 
@@ -1729,10 +2059,41 @@ var attachHelp = {
   ]
 };
 
+// src/cli/help/completion.ts
+var completionHelp = {
+  name: "completion",
+  usage: "phantom completion <shell>",
+  description: "Generate shell completion scripts for fish or zsh",
+  examples: [
+    {
+      command: "phantom completion fish > ~/.config/fish/completions/phantom.fish",
+      description: "Generate and install Fish completion"
+    },
+    {
+      command: "phantom completion fish | source",
+      description: "Load Fish completion in current session"
+    },
+    {
+      command: "phantom completion zsh > ~/.zsh/completions/_phantom",
+      description: "Generate and install Zsh completion"
+    },
+    {
+      command: 'eval "$(phantom completion zsh)"',
+      description: "Load Zsh completion in current session"
+    }
+  ],
+  notes: [
+    "Supported shells: fish, zsh",
+    "After installing completions, you may need to restart your shell or source the completion file",
+    "For Fish: completions are loaded automatically from ~/.config/fish/completions/",
+    "For Zsh: ensure the completion file is in a directory in your $fpath"
+  ]
+};
+
 // src/cli/help/create.ts
 var createHelp = {
   name: "create",
-  description: "Create a new Git worktree (phantom)",
+  description: "Create a new Git worktree",
   usage: "phantom create <name> [options]",
   options: [
     {
@@ -1804,7 +2165,7 @@ var createHelp = {
 // src/cli/help/delete.ts
 var deleteHelp = {
   name: "delete",
-  description: "Delete a Git worktree (phantom)",
+  description: "Delete a Git worktree",
   usage: "phantom delete <name> [options]",
   options: [
     {
@@ -1853,7 +2214,29 @@ var deleteHelp = {
 var execHelp = {
   name: "exec",
   description: "Execute a command in a worktree directory",
-  usage: "phantom exec <worktree-name> <command> [args...]",
+  usage: "phantom exec [options] <worktree-name> <command> [args...]",
+  options: [
+    {
+      name: "--fzf",
+      type: "boolean",
+      description: "Use fzf for interactive worktree selection"
+    },
+    {
+      name: "--tmux, -t",
+      type: "boolean",
+      description: "Execute command in new tmux window"
+    },
+    {
+      name: "--tmux-vertical, --tmux-v",
+      type: "boolean",
+      description: "Execute command in vertical split pane"
+    },
+    {
+      name: "--tmux-horizontal, --tmux-h",
+      type: "boolean",
+      description: "Execute command in horizontal split pane"
+    }
+  ],
   examples: [
     {
       description: "Run npm test in a worktree",
@@ -1866,19 +2249,37 @@ var execHelp = {
     {
       description: "Run a complex command with arguments",
       command: "phantom exec staging npm run build -- --production"
+    },
+    {
+      description: "Execute with interactive selection",
+      command: "phantom exec --fzf npm run dev"
+    },
+    {
+      description: "Run dev server in new tmux window",
+      command: "phantom exec --tmux feature-auth npm run dev"
+    },
+    {
+      description: "Run tests in vertical split pane",
+      command: "phantom exec --tmux-v feature-auth npm test"
+    },
+    {
+      description: "Interactive selection with tmux",
+      command: "phantom exec --fzf --tmux npm run dev"
     }
   ],
   notes: [
     "The command is executed with the worktree directory as the working directory",
     "All arguments after the worktree name are passed to the command",
-    "The exit code of the executed command is preserved"
+    "The exit code of the executed command is preserved",
+    "With --fzf, select the worktree interactively before executing the command",
+    "Tmux options require being inside a tmux session"
   ]
 };
 
 // src/cli/help/list.ts
 var listHelp = {
   name: "list",
-  description: "List all Git worktrees (phantoms)",
+  description: "List all Git worktrees",
   usage: "phantom list [options]",
   options: [
     {
@@ -1889,7 +2290,7 @@ var listHelp = {
     {
       name: "--names",
       type: "boolean",
-      description: "Output only phantom names (for scripts and completion)"
+      description: "Output only worktree names (for scripts and completion)"
     }
   ],
   examples: [
@@ -1924,6 +2325,21 @@ var shellHelp = {
       name: "--fzf",
       type: "boolean",
       description: "Use fzf for interactive selection"
+    },
+    {
+      name: "--tmux, -t",
+      type: "boolean",
+      description: "Open shell in new tmux window"
+    },
+    {
+      name: "--tmux-vertical, --tmux-v",
+      type: "boolean",
+      description: "Open shell in vertical split pane"
+    },
+    {
+      name: "--tmux-horizontal, --tmux-h",
+      type: "boolean",
+      description: "Open shell in horizontal split pane"
     }
   ],
   examples: [
@@ -1934,13 +2350,26 @@ var shellHelp = {
     {
       description: "Open a shell with interactive fzf selection",
       command: "phantom shell --fzf"
+    },
+    {
+      description: "Open a shell in a new tmux window",
+      command: "phantom shell feature-auth --tmux"
+    },
+    {
+      description: "Open a shell in a vertical tmux pane",
+      command: "phantom shell feature-auth --tmux-v"
+    },
+    {
+      description: "Interactive selection with tmux",
+      command: "phantom shell --fzf --tmux"
     }
   ],
   notes: [
     "Uses your default shell from the SHELL environment variable",
     "The shell starts with the worktree directory as the working directory",
     "Type 'exit' to return to your original directory",
-    "With --fzf, you can interactively select the worktree to enter"
+    "With --fzf, you can interactively select the worktree to enter",
+    "Tmux options require being inside a tmux session"
   ]
 };
 
@@ -2044,6 +2473,12 @@ var commands = [
     description: "Display phantom version information",
     handler: versionHandler,
     help: versionHelp
+  },
+  {
+    name: "completion",
+    description: "Generate shell completion scripts",
+    handler: completionHandler,
+    help: completionHelp
   }
 ];
 function printHelp(commands2) {
@@ -2076,18 +2511,18 @@ function findCommand(args2, commands2) {
 var args = argv.slice(2);
 if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
   printHelp(commands);
-  exit(0);
+  exit2(0);
 }
 if (args[0] === "--version" || args[0] === "-v") {
   versionHandler();
-  exit(0);
+  exit2(0);
 }
 var { command, remainingArgs } = findCommand(args, commands);
 if (!command || !command.handler) {
   console.error(`Error: Unknown command '${args.join(" ")}'
 `);
   printHelp(commands);
-  exit(1);
+  exit2(1);
 }
 if (remainingArgs.includes("--help") || remainingArgs.includes("-h")) {
   if (command.help) {
@@ -2095,7 +2530,7 @@ if (remainingArgs.includes("--help") || remainingArgs.includes("-h")) {
   } else {
     console.log(`Help not available for command '${command.name}'`);
   }
-  exit(0);
+  exit2(0);
 }
 try {
   await command.handler(remainingArgs);
@@ -2104,6 +2539,6 @@ try {
     "Error:",
     error instanceof Error ? error.message : String(error)
   );
-  exit(1);
+  exit2(1);
 }
 //# sourceMappingURL=phantom.js.map