@aku11i/phantom 0.9.0 → 1.0.0

package/dist/phantom.js

@@ -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)) {
@@ -715,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");
@@ -737,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
@@ -811,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({
@@ -1017,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);
@@ -1148,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(
@@ -1306,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;
@@ -1420,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,
@@ -1528,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",
@@ -1549,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)) {
@@ -1562,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)) {
@@ -1591,7 +1729,7 @@ import { parseArgs as parseArgs7 } from "node:util";
 var package_default = {
   name: "@aku11i/phantom",
   packageManager: "pnpm@10.8.1",
-  version: "0.9.0",
+  version: "1.0.0",
   description: "A powerful CLI tool for managing Git worktrees for parallel development",
   keywords: [
     "git",
@@ -1671,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
   });
 }
 
@@ -1955,7 +2093,7 @@ var completionHelp = {
 // 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: [
     {
@@ -2027,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: [
     {
@@ -2076,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",
@@ -2089,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: [
     {
@@ -2112,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: [
@@ -2147,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: [
@@ -2157,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"
   ]
 };