@aku11i/phantom 1.3.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aku11i/phantom",
-  "version": "1.3.0",
+  "version": "2.1.0",
   "description": "A powerful CLI tool for managing Git worktrees for parallel development",
   "keywords": [
     "git",
@@ -31,5 +31,8 @@
     "README.md",
     "LICENSE"
   ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "dependencies": {}
 }

package/phantom.js

@@ -4203,13 +4203,16 @@ var phantomConfigSchema = external_exports.object({
     copyFiles: external_exports.array(external_exports.string()).optional(),
     commands: external_exports.array(external_exports.string()).optional()
   }).passthrough().optional(),
-  worktreesDirectory: external_exports.string().optional()
+  preDelete: external_exports.object({
+    commands: external_exports.array(external_exports.string()).optional()
+  }).passthrough().optional(),
+  worktreesDirectory: external_exports.string().optional(),
+  defaultBranch: external_exports.string().optional()
 }).passthrough();
 function validateConfig(config) {
   const result = phantomConfigSchema.safeParse(config);
   if (!result.success) {
     const error = result.error;
-    const formattedError = error.format();
     const firstError = error.errors[0];
     const path3 = firstError.path.join(".");
     const message = path3 ? `${path3}: ${firstError.message}` : firstError.message;
@@ -4403,7 +4406,7 @@ async function fetch(options = {}) {
 }
 
 // ../git/src/libs/list-worktrees.ts
-async function listWorktrees(gitRoot) {
+async function listWorktrees(_gitRoot) {
   const { stdout: stdout2 } = await executeGitCommand([
     "worktree",
     "list",
@@ -4695,7 +4698,7 @@ async function selectWithFzf(items, options = {}) {
 
 // ../core/src/worktree/validate.ts
 import fs2 from "node:fs/promises";
-async function validateWorktreeExists(gitRoot, worktreeDirectory, name) {
+async function validateWorktreeExists(_gitRoot, worktreeDirectory, name) {
   const worktreePath = getWorktreePathFromDirectory(worktreeDirectory, name);
   try {
     await fs2.access(worktreePath);
@@ -4704,7 +4707,7 @@ async function validateWorktreeExists(gitRoot, worktreeDirectory, name) {
     return err(new WorktreeNotFoundError(name));
   }
 }
-async function validateWorktreeDoesNotExist(gitRoot, worktreeDirectory, name) {
+async function validateWorktreeDoesNotExist(_gitRoot, worktreeDirectory, name) {
   const worktreePath = getWorktreePathFromDirectory(worktreeDirectory, name);
   try {
     await fs2.access(worktreePath);
@@ -4879,6 +4882,39 @@ async function createWorktree(gitRoot, worktreeDirectory, name, options, postCre
   }
 }
 
+// ../core/src/worktree/pre-delete.ts
+async function executePreDeleteCommands(options) {
+  const { gitRoot, worktreesDirectory, worktreeName, commands: commands2 } = options;
+  const executedCommands = [];
+  for (const command2 of commands2) {
+    console.log(`Executing pre-delete command: ${command2}`);
+    const shell = process.env.SHELL || "/bin/sh";
+    const cmdResult = await execInWorktree(
+      gitRoot,
+      worktreesDirectory,
+      worktreeName,
+      [shell, "-c", command2]
+    );
+    if (isErr(cmdResult)) {
+      const errorMessage = cmdResult.error instanceof Error ? cmdResult.error.message : String(cmdResult.error);
+      return err(
+        new Error(
+          `Failed to execute pre-delete command "${command2}": ${errorMessage}`
+        )
+      );
+    }
+    if (cmdResult.value.exitCode !== 0) {
+      return err(
+        new Error(
+          `Pre-delete command failed with exit code ${cmdResult.value.exitCode}: ${command2}`
+        )
+      );
+    }
+    executedCommands.push(command2);
+  }
+  return ok({ executedCommands });
+}
+
 // ../core/src/worktree/delete.ts
 async function getWorktreeChangesStatus(worktreePath) {
   try {
@@ -4900,19 +4936,14 @@ async function getWorktreeChangesStatus(worktreePath) {
   };
 }
 async function removeWorktree(gitRoot, worktreePath, force = false) {
-  try {
-    await executeGitCommand(["worktree", "remove", worktreePath], {
-      cwd: gitRoot
-    });
-  } catch (error) {
-    try {
-      await executeGitCommand(["worktree", "remove", "--force", worktreePath], {
-        cwd: gitRoot
-      });
-    } catch {
-      throw new Error("Failed to remove worktree");
-    }
+  const args2 = ["worktree", "remove"];
+  if (force) {
+    args2.push("--force");
   }
+  args2.push(worktreePath);
+  await executeGitCommand(args2, {
+    cwd: gitRoot
+  });
 }
 async function deleteBranch(gitRoot, branchName) {
   try {
@@ -4923,7 +4954,7 @@ async function deleteBranch(gitRoot, branchName) {
     return err(new WorktreeError(`branch delete failed: ${errorMessage}`));
   }
 }
-async function deleteWorktree(gitRoot, worktreeDirectory, name, options) {
+async function deleteWorktree(gitRoot, worktreeDirectory, name, options, preDeleteCommands) {
   const { force = false } = options || {};
   const validation = await validateWorktreeExists(
     gitRoot,
@@ -4942,6 +4973,18 @@ async function deleteWorktree(gitRoot, worktreeDirectory, name, options) {
       )
     );
   }
+  if (preDeleteCommands && preDeleteCommands.length > 0) {
+    console.log("\nRunning pre-delete commands...");
+    const preDeleteResult = await executePreDeleteCommands({
+      gitRoot,
+      worktreesDirectory: worktreeDirectory,
+      worktreeName: name,
+      commands: preDeleteCommands
+    });
+    if (isErr(preDeleteResult)) {
+      return err(new WorktreeError(preDeleteResult.error.message));
+    }
+  }
   try {
     await removeWorktree(gitRoot, worktreePath, force);
     const branchName = name;
@@ -5231,7 +5274,6 @@ async function attachHandler(args2) {
     }
     exitWithError(error.message, exitCodes.generalError);
   }
-  const worktreePath = result.value;
   output.log(`Attached phantom: ${branchName}`);
   if (values.shell) {
     const shellResult = await shellInWorktree(
@@ -5295,6 +5337,7 @@ complete -c phantom -n "__phantom_using_command" -a "list" -d "List all Git work
 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 "review" -d "Review changes in a worktree with a local PR review interface (experimental)"
 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 "github" -d "GitHub integration commands"
 complete -c phantom -n "__phantom_using_command" -a "gh" -d "GitHub integration commands (alias)"
@@ -5340,6 +5383,11 @@ complete -c phantom -n "__phantom_using_command exec" -l tmux-vertical -d "Execu
 complete -c phantom -n "__phantom_using_command exec" -l tmux-horizontal -d "Execute command in horizontal split pane"
 complete -c phantom -n "__phantom_using_command exec" -a "(__phantom_list_worktrees)"
 
+# review command options
+complete -c phantom -n "__phantom_using_command review" -l fzf -d "Use fzf for interactive selection"
+complete -c phantom -n "__phantom_using_command review" -l base -d "Base reference for comparison" -x
+complete -c phantom -n "__phantom_using_command review" -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" -l tmux -d "Open shell in new tmux window (-t)"
@@ -5374,6 +5422,7 @@ _phantom() {
         'where:Output the filesystem path of a specific worktree'
         'delete:Delete a Git worktree (phantom)'
         'exec:Execute a command in a worktree directory'
+        'review:Review changes in a worktree with a local PR review interface (experimental)'
         'shell:Open an interactive shell in a worktree directory'
         'github:GitHub integration commands'
         'gh:GitHub integration commands (alias)'
@@ -5416,13 +5465,18 @@ _phantom() {
                         '--fzf[Use fzf for interactive selection]' \\
                         '--names[Output only phantom names (for scripts and completion)]'
                     ;;
-                where|delete|shell)
+                where|delete|review|shell)
                     local worktrees
                     worktrees=(\${(f)"$(phantom list --names 2>/dev/null)"})
                     if [[ \${line[1]} == "where" ]]; then
                         _arguments \\
                             '--fzf[Use fzf for interactive selection]' \\
                             '1:worktree:(\${(q)worktrees[@]})'
+                    elif [[ \${line[1]} == "review" ]]; then
+                        _arguments \\
+                            '--fzf[Use fzf for interactive selection]' \\
+                            '--base[Base reference for comparison]:reference:' \\
+                            '1:worktree:(\${(q)worktrees[@]})'
                     elif [[ \${line[1]} == "shell" ]]; then
                         _arguments \\
                             '--fzf[Use fzf for interactive selection]' \\
@@ -5488,7 +5542,7 @@ _phantom_completion() {
     local cur prev words cword
     _init_completion || return
 
-    local commands="create attach list where delete exec shell github gh version completion mcp"
+    local commands="create attach list where delete exec review shell github gh version completion mcp"
     local global_opts="--help --version"
 
     if [[ \${cword} -eq 1 ]]; then
@@ -5590,6 +5644,24 @@ _phantom_completion() {
                     ;;
             esac
             ;;
+        review)
+            case "\${prev}" in
+                --base)
+                    # Don't complete anything specific for base reference
+                    return 0
+                    ;;
+                *)
+                    if [[ "\${cur}" == -* ]]; then
+                        local opts="--fzf --base"
+                        COMPREPLY=( $(compgen -W "\${opts}" -- "\${cur}") )
+                    else
+                        local worktrees=$(_phantom_list_worktrees)
+                        COMPREPLY=( $(compgen -W "\${worktrees}" -- "\${cur}") )
+                    fi
+                    return 0
+                    ;;
+            esac
+            ;;
         shell)
             case "\${prev}" in
                 --tmux|-t|--tmux-vertical|--tmux-horizontal)
@@ -5931,7 +6003,8 @@ async function deleteHandler(args2) {
       worktreeName,
       {
         force: forceDelete
-      }
+      },
+      context.config?.preDelete?.commands
     );
     if (isErr(result)) {
       const exitCode = result.error instanceof WorktreeNotFoundError ? exitCodes.validationError : result.error instanceof WorktreeError && result.error.message.includes("uncommitted changes") ? exitCodes.validationError : exitCodes.generalError;
@@ -9526,8 +9599,21 @@ async function checkoutIssue(issue, base) {
   }
   const gitRoot = await getGitRoot();
   const context = await createContext(gitRoot);
-  const worktreeName = `issue-${issue.number}`;
-  const branchName = `issue-${issue.number}`;
+  const worktreeName = `issues/${issue.number}`;
+  const branchName = `issues/${issue.number}`;
+  const existsResult = await validateWorktreeExists(
+    context.gitRoot,
+    context.worktreesDirectory,
+    worktreeName
+  );
+  if (!isErr(existsResult)) {
+    return ok({
+      message: `Issue #${issue.number} is already checked out`,
+      worktree: worktreeName,
+      path: existsResult.value.path,
+      alreadyExists: true
+    });
+  }
   const result = await createWorktree(
     context.gitRoot,
     context.worktreesDirectory,
@@ -9540,18 +9626,6 @@ async function checkoutIssue(issue, base) {
     context.config?.postCreate?.commands
   );
   if (isErr(result)) {
-    if (result.error instanceof WorktreeAlreadyExistsError) {
-      const worktreePath = getWorktreePathFromDirectory(
-        context.worktreesDirectory,
-        worktreeName
-      );
-      return ok({
-        message: `Worktree for issue #${issue.number} is already checked out`,
-        worktree: worktreeName,
-        path: worktreePath,
-        alreadyExists: true
-      });
-    }
     return err(result.error);
   }
   return ok({
@@ -9565,8 +9639,21 @@ async function checkoutIssue(issue, base) {
 async function checkoutPullRequest(pullRequest) {
   const gitRoot = await getGitRoot();
   const context = await createContext(gitRoot);
-  const worktreeName = `pr-${pullRequest.number}`;
-  const localBranch = `pr-${pullRequest.number}`;
+  const worktreeName = `pulls/${pullRequest.number}`;
+  const localBranch = `pulls/${pullRequest.number}`;
+  const existsResult = await validateWorktreeExists(
+    context.gitRoot,
+    context.worktreesDirectory,
+    worktreeName
+  );
+  if (!isErr(existsResult)) {
+    return ok({
+      message: `PR #${pullRequest.number} is already checked out`,
+      worktree: worktreeName,
+      path: existsResult.value.path,
+      alreadyExists: true
+    });
+  }
   const upstream = pullRequest.isFromFork ? `origin/pull/${pullRequest.number}/head` : `origin/${pullRequest.head.ref}`;
   const refspec = `${upstream.replace("origin/", "")}:${localBranch}`;
   const fetchResult = await fetch({ refspec });
@@ -9595,18 +9682,6 @@ async function checkoutPullRequest(pullRequest) {
     context.config?.postCreate?.commands
   );
   if (isErr(attachResult)) {
-    if (attachResult.error instanceof WorktreeAlreadyExistsError) {
-      const worktreePath = getWorktreePathFromDirectory(
-        context.worktreesDirectory,
-        worktreeName
-      );
-      return ok({
-        message: `Worktree for PR #${pullRequest.number} is already checked out`,
-        worktree: worktreeName,
-        path: worktreePath,
-        alreadyExists: true
-      });
-    }
     return err(attachResult.error);
   }
   const message = pullRequest.isFromFork ? `Checked out PR #${pullRequest.number} from fork ${pullRequest.head.repo.full_name}` : `Checked out PR #${pullRequest.number} from branch ${pullRequest.head.ref}`;
@@ -9866,8 +9941,8 @@ var githubCheckoutHelp = {
     }
   ],
   notes: [
-    "For PRs: Creates worktree named 'pr-{number}' with the PR's branch",
-    "For Issues: Creates worktree named 'issue-{number}' with a new branch",
+    "For PRs: Creates worktree named 'pulls/{number}' with the PR's branch",
+    "For Issues: Creates worktree named 'issues/{number}' with a new branch",
     "",
     "Requirements:",
     "  - GitHub CLI (gh) must be installed",
@@ -13223,7 +13298,7 @@ var StdioServerTransport = class {
 // ../mcp/package.json
 var package_default = {
   name: "@aku11i/phantom-mcp",
-  version: "1.3.0",
+  version: "2.1.0",
   private: true,
   type: "module",
   main: "./src/index.ts",
@@ -13311,7 +13386,8 @@ var deleteWorktreeTool = {
       name,
       {
         force
-      }
+      },
+      context.config?.preDelete?.commands
     );
     if (!isOk(result)) {
       throw new Error(result.error.message);
@@ -13501,10 +13577,97 @@ async function mcpHandler(args2 = []) {
   }
 }
 
-// src/handlers/shell.ts
+// src/handlers/review.ts
 import { parseArgs as parseArgs8 } from "node:util";
-async function shellHandler(args2) {
+async function reviewHandler(args2) {
   const { positionals, values } = parseArgs8({
+    args: args2,
+    options: {
+      fzf: {
+        type: "boolean",
+        default: false
+      },
+      base: {
+        type: "string"
+      }
+    },
+    strict: true,
+    allowPositionals: true
+  });
+  const useFzf = values.fzf ?? false;
+  const base = values.base;
+  if (useFzf) {
+    if (positionals.length > 0) {
+      exitWithError(
+        "Cannot specify worktree name when using --fzf",
+        exitCodes.validationError
+      );
+    }
+  } else {
+    if (positionals.length !== 1) {
+      exitWithError(
+        "Usage: phantom review <worktree-name> [--base <ref>]",
+        exitCodes.validationError
+      );
+    }
+  }
+  try {
+    const gitRoot = await getGitRoot();
+    const context = await createContext(gitRoot);
+    let worktreeName;
+    if (useFzf) {
+      const selectResult = await selectWorktreeWithFzf(
+        context.gitRoot,
+        context.worktreesDirectory
+      );
+      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(
+      context.gitRoot,
+      context.worktreesDirectory,
+      worktreeName
+    );
+    if (isErr(validation)) {
+      exitWithError(validation.error.message, exitCodes.generalError);
+    }
+    const baseRef = base ?? `origin/${context.config?.defaultBranch ?? "main"}`;
+    output.log(`Opening review for worktree '${worktreeName}'...`);
+    output.log(
+      "powered by yoshiko-pg/reviewit (https://github.com/yoshiko-pg/reviewit)"
+    );
+    const command2 = ["reviewit", ".", baseRef];
+    const result = await execInWorktree(
+      context.gitRoot,
+      context.worktreesDirectory,
+      worktreeName,
+      command2,
+      { interactive: true }
+    );
+    if (isErr(result)) {
+      const exitCode = result.error instanceof WorktreeNotFoundError ? exitCodes.notFound : result.error.exitCode || exitCodes.generalError;
+      exitWithError(result.error.message, exitCode);
+    }
+    process.exit(result.value.exitCode);
+  } catch (error) {
+    exitWithError(
+      error instanceof Error ? error.message : String(error),
+      exitCodes.generalError
+    );
+  }
+}
+
+// src/handlers/shell.ts
+import { parseArgs as parseArgs9 } from "node:util";
+async function shellHandler(args2) {
+  const { positionals, values } = parseArgs9({
     args: args2,
     options: {
       fzf: {
@@ -13628,12 +13791,12 @@ async function shellHandler(args2) {
 }
 
 // src/handlers/version.ts
-import { parseArgs as parseArgs9 } from "node:util";
+import { parseArgs as parseArgs10 } from "node:util";
 
 // package.json
 var package_default2 = {
   name: "@aku11i/phantom-cli",
-  version: "1.3.0",
+  version: "2.1.0",
   private: true,
   type: "module",
   scripts: {
@@ -13661,7 +13824,7 @@ function getVersion() {
 
 // src/handlers/version.ts
 function versionHandler(args2 = []) {
-  parseArgs9({
+  parseArgs10({
     args: args2,
     options: {},
     strict: true,
@@ -13673,9 +13836,9 @@ function versionHandler(args2 = []) {
 }
 
 // src/handlers/where.ts
-import { parseArgs as parseArgs10 } from "node:util";
+import { parseArgs as parseArgs11 } from "node:util";
 async function whereHandler(args2) {
-  const { positionals, values } = parseArgs10({
+  const { positionals, values } = parseArgs11({
     args: args2,
     options: {
       fzf: {
@@ -14044,6 +14207,55 @@ var listHelp = {
   ]
 };
 
+// src/help/review.ts
+var reviewHelp = {
+  name: "review",
+  description: "Review changes in a worktree with a local PR review interface (experimental)",
+  usage: "phantom review [options] <worktree-name>",
+  options: [
+    {
+      name: "--fzf",
+      type: "boolean",
+      description: "Use fzf for interactive worktree selection"
+    },
+    {
+      name: "--base",
+      type: "string",
+      description: "Base reference for comparison (default: origin/<defaultBranch>)"
+    }
+  ],
+  examples: [
+    {
+      description: "Review changes against default branch",
+      command: "phantom review feature-auth"
+    },
+    {
+      description: "Review changes against specific remote branch",
+      command: "phantom review feature-login --base origin/feature-auth"
+    },
+    {
+      description: "Review changes against local branch",
+      command: "phantom review feature-auth --base main"
+    },
+    {
+      description: "Interactive worktree selection",
+      command: "phantom review --fzf"
+    },
+    {
+      description: "Interactive selection with custom base",
+      command: "phantom review --fzf --base origin/staging"
+    }
+  ],
+  notes: [
+    "\u26A0\uFE0F  This is an experimental feature and may change in future versions",
+    "Uses reviewit to provide a GitHub-like PR review interface locally",
+    "Default base is origin/<defaultBranch> where defaultBranch is from config or 'main'",
+    "The --base value is passed directly to reviewit as the comparison reference",
+    "Requires reviewit to be installed separately (e.g., npm install -g reviewit)",
+    "powered by yoshiko-pg/reviewit (https://github.com/yoshiko-pg/reviewit)"
+  ]
+};
+
 // src/help/shell.ts
 var shellHelp = {
   name: "shell",
@@ -14191,6 +14403,12 @@ var commands = [
     handler: execHandler,
     help: execHelp
   },
+  {
+    name: "review",
+    description: "Review changes in a worktree with a local PR review interface (experimental)",
+    handler: reviewHandler,
+    help: reviewHelp
+  },
   {
     name: "shell",
     description: "Open an interactive shell in a worktree directory",