@aku11i/phantom 0.6.0 → 0.7.0

package/dist/phantom.js

@@ -44,9 +44,9 @@ async function executeGitCommandInDirectory(directory, args2) {
 
 // src/core/git/libs/get-git-root.ts
 async function getGitRoot() {
-  const { stdout } = await executeGitCommand(["rev-parse", "--git-common-dir"]);
-  if (stdout.endsWith("/.git") || stdout === ".git") {
-    return resolve(process.cwd(), dirname(stdout));
+  const { stdout: stdout2 } = await executeGitCommand(["rev-parse", "--git-common-dir"]);
+  if (stdout2.endsWith("/.git") || stdout2 === ".git") {
+    return resolve(process.cwd(), dirname(stdout2));
   }
   const { stdout: toplevel } = await executeGitCommand([
     "rev-parse",
@@ -216,18 +216,20 @@ async function spawnProcess(config) {
 }
 
 // src/core/process/exec.ts
-async function execInWorktree(gitRoot, worktreeName, command2) {
+async function execInWorktree(gitRoot, worktreeName, command2, options = {}) {
   const validation = await validateWorktreeExists(gitRoot, worktreeName);
   if (!validation.exists) {
     return err(new WorktreeNotFoundError(worktreeName));
   }
   const worktreePath = validation.path;
   const [cmd, ...args2] = command2;
+  const stdio = options.interactive ? "inherit" : ["ignore", "inherit", "inherit"];
   return spawnProcess({
     command: cmd,
     args: args2,
     options: {
-      cwd: worktreePath
+      cwd: worktreePath,
+      stdio
     }
   });
 }
@@ -407,7 +409,8 @@ async function attachHandler(args2) {
     const execResult = await execInWorktree(
       gitRoot,
       branchName,
-      values.exec.split(" ")
+      values.exec.split(" "),
+      { interactive: true }
     );
     if (isErr(execResult)) {
       exitWithError(execResult.error.message, exitCodes.generalError);
@@ -458,6 +461,20 @@ function validateConfig(config) {
         );
       }
     }
+    if (postCreate.commands !== void 0) {
+      if (!Array.isArray(postCreate.commands)) {
+        return err(
+          new ConfigValidationError("postCreate.commands must be an array")
+        );
+      }
+      if (!postCreate.commands.every((c) => typeof c === "string")) {
+        return err(
+          new ConfigValidationError(
+            "postCreate.commands must contain only strings"
+          )
+        );
+      }
+    }
   }
   return ok(config);
 }
@@ -741,17 +758,42 @@ async function createHandler(args2) {
 Warning: Failed to copy some files: ${result.value.copyError}`
       );
     }
+    if (isOk(configResult) && configResult.value.postCreate?.commands) {
+      const commands2 = configResult.value.postCreate.commands;
+      output.log("\nRunning post-create commands...");
+      for (const command2 of commands2) {
+        output.log(`Executing: ${command2}`);
+        const shell = process.env.SHELL || "/bin/sh";
+        const cmdResult = await execInWorktree(gitRoot, worktreeName, [
+          shell,
+          "-c",
+          command2
+        ]);
+        if (isErr(cmdResult)) {
+          output.error(`Failed to execute command: ${cmdResult.error.message}`);
+          const exitCode = "exitCode" in cmdResult.error ? cmdResult.error.exitCode ?? exitCodes.generalError : exitCodes.generalError;
+          exitWithError(`Post-create command failed: ${command2}`, exitCode);
+        }
+        if (cmdResult.value.exitCode !== 0) {
+          exitWithError(
+            `Post-create command failed: ${command2}`,
+            cmdResult.value.exitCode
+          );
+        }
+      }
+    }
     if (execCommand && isOk(result)) {
       output.log(
         `
 Executing command in worktree '${worktreeName}': ${execCommand}`
       );
       const shell = process.env.SHELL || "/bin/sh";
-      const execResult = await execInWorktree(gitRoot, worktreeName, [
-        shell,
-        "-c",
-        execCommand
-      ]);
+      const execResult = await execInWorktree(
+        gitRoot,
+        worktreeName,
+        [shell, "-c", execCommand],
+        { interactive: true }
+      );
       if (isErr(execResult)) {
         output.error(execResult.error.message);
         const exitCode = "exitCode" in execResult.error ? execResult.error.exitCode ?? exitCodes.generalError : exitCodes.generalError;
@@ -809,14 +851,14 @@ import { parseArgs as parseArgs3 } from "node:util";
 
 // src/core/git/libs/list-worktrees.ts
 async function listWorktrees(gitRoot) {
-  const { stdout } = await executeGitCommand([
+  const { stdout: stdout2 } = await executeGitCommand([
     "worktree",
     "list",
     "--porcelain"
   ]);
   const worktrees = [];
   let currentWorktree = {};
-  const lines = stdout.split("\n").filter((line) => line.length > 0);
+  const lines = stdout2.split("\n").filter((line) => line.length > 0);
   for (const line of lines) {
     if (line.startsWith("worktree ")) {
       if (currentWorktree.path) {
@@ -870,14 +912,14 @@ async function getCurrentWorktree(gitRoot) {
 // src/core/worktree/delete.ts
 async function getWorktreeStatus(worktreePath) {
   try {
-    const { stdout } = await executeGitCommandInDirectory(worktreePath, [
+    const { stdout: stdout2 } = await executeGitCommandInDirectory(worktreePath, [
       "status",
       "--porcelain"
     ]);
-    if (stdout) {
+    if (stdout2) {
       return {
         hasUncommittedChanges: true,
-        changedFiles: stdout.split("\n").length
+        changedFiles: stdout2.split("\n").length
       };
     }
   } catch {
@@ -1033,7 +1075,12 @@ async function execHandler(args2) {
   const [worktreeName, ...commandArgs] = positionals;
   try {
     const gitRoot = await getGitRoot();
-    const result = await execInWorktree(gitRoot, worktreeName, commandArgs);
+    const result = await execInWorktree(
+      gitRoot,
+      worktreeName,
+      commandArgs,
+      { interactive: true }
+    );
     if (isErr(result)) {
       const exitCode = result.error instanceof WorktreeNotFoundError ? exitCodes.notFound : result.error.exitCode || exitCodes.generalError;
       exitWithError(result.error.message, exitCode);
@@ -1053,11 +1100,11 @@ import { parseArgs as parseArgs5 } from "node:util";
 // src/core/worktree/list.ts
 async function getWorktreeStatus2(worktreePath) {
   try {
-    const { stdout } = await executeGitCommandInDirectory(worktreePath, [
+    const { stdout: stdout2 } = await executeGitCommandInDirectory(worktreePath, [
       "status",
       "--porcelain"
     ]);
-    return !stdout;
+    return !stdout2;
   } catch {
     return true;
   }
@@ -1179,7 +1226,7 @@ import { parseArgs as parseArgs7 } from "node:util";
 var package_default = {
   name: "@aku11i/phantom",
   packageManager: "pnpm@10.8.1",
-  version: "0.6.0",
+  version: "0.7.0",
   description: "A powerful CLI tool for managing Git worktrees for parallel development",
   keywords: [
     "git",
@@ -1295,55 +1342,446 @@ async function whereHandler(args2) {
   }
 }
 
+// src/cli/help.ts
+import { stdout } from "node:process";
+var HelpFormatter = class {
+  width;
+  indent = "  ";
+  constructor() {
+    this.width = stdout.columns || 80;
+  }
+  formatMainHelp(commands2) {
+    const lines = [];
+    lines.push(this.bold("Phantom - Git Worktree Manager"));
+    lines.push("");
+    lines.push(
+      this.dim(
+        "A CLI tool for managing Git worktrees with enhanced functionality"
+      )
+    );
+    lines.push("");
+    lines.push(this.section("USAGE"));
+    lines.push(`${this.indent}phantom <command> [options]`);
+    lines.push("");
+    lines.push(this.section("COMMANDS"));
+    const maxNameLength = Math.max(...commands2.map((cmd) => cmd.name.length));
+    for (const cmd of commands2) {
+      const paddedName = cmd.name.padEnd(maxNameLength + 2);
+      lines.push(`${this.indent}${this.cyan(paddedName)}${cmd.description}`);
+    }
+    lines.push("");
+    lines.push(this.section("GLOBAL OPTIONS"));
+    const helpOption = "-h, --help";
+    const versionOption = "-v, --version";
+    const globalOptionWidth = Math.max(helpOption.length, versionOption.length) + 2;
+    lines.push(
+      `${this.indent}${this.cyan(helpOption.padEnd(globalOptionWidth))}Show help`
+    );
+    lines.push(
+      `${this.indent}${this.cyan(versionOption.padEnd(globalOptionWidth))}Show version`
+    );
+    lines.push("");
+    lines.push(
+      this.dim(
+        "Run 'phantom <command> --help' for more information on a command."
+      )
+    );
+    return lines.join("\n");
+  }
+  formatCommandHelp(help) {
+    const lines = [];
+    lines.push(this.bold(`phantom ${help.name}`));
+    lines.push(this.dim(help.description));
+    lines.push("");
+    lines.push(this.section("USAGE"));
+    lines.push(`${this.indent}${help.usage}`);
+    lines.push("");
+    if (help.options && help.options.length > 0) {
+      lines.push(this.section("OPTIONS"));
+      const maxOptionLength = Math.max(
+        ...help.options.map((opt) => this.formatOptionName(opt).length)
+      );
+      for (const option of help.options) {
+        const optionName = this.formatOptionName(option);
+        const paddedName = optionName.padEnd(maxOptionLength + 2);
+        const description = this.wrapText(
+          option.description,
+          maxOptionLength + 4
+        );
+        lines.push(`${this.indent}${this.cyan(paddedName)}${description[0]}`);
+        for (let i = 1; i < description.length; i++) {
+          lines.push(
+            `${this.indent}${" ".repeat(maxOptionLength + 2)}${description[i]}`
+          );
+        }
+        if (option.example) {
+          const exampleIndent = " ".repeat(maxOptionLength + 4);
+          lines.push(
+            `${this.indent}${exampleIndent}${this.dim(`Example: ${option.example}`)}`
+          );
+        }
+      }
+      lines.push("");
+    }
+    if (help.examples && help.examples.length > 0) {
+      lines.push(this.section("EXAMPLES"));
+      for (const example of help.examples) {
+        lines.push(`${this.indent}${this.dim(example.description)}`);
+        lines.push(`${this.indent}${this.indent}$ ${example.command}`);
+        lines.push("");
+      }
+    }
+    if (help.notes && help.notes.length > 0) {
+      lines.push(this.section("NOTES"));
+      for (const note of help.notes) {
+        const wrappedNote = this.wrapText(note, 2);
+        for (const line of wrappedNote) {
+          lines.push(`${this.indent}${line}`);
+        }
+      }
+      lines.push("");
+    }
+    return lines.join("\n");
+  }
+  formatOptionName(option) {
+    const parts = [];
+    if (option.short) {
+      parts.push(`-${option.short},`);
+    }
+    parts.push(`--${option.name}`);
+    if (option.type === "string") {
+      parts.push(option.multiple ? "<value>..." : "<value>");
+    }
+    return parts.join(" ");
+  }
+  wrapText(text, indent) {
+    const maxWidth = this.width - indent - 2;
+    const words = text.split(" ");
+    const lines = [];
+    let currentLine = "";
+    for (const word of words) {
+      if (currentLine.length + word.length + 1 > maxWidth) {
+        lines.push(currentLine);
+        currentLine = word;
+      } else {
+        currentLine = currentLine ? `${currentLine} ${word}` : word;
+      }
+    }
+    if (currentLine) {
+      lines.push(currentLine);
+    }
+    return lines;
+  }
+  section(text) {
+    return this.bold(text);
+  }
+  bold(text) {
+    return `\x1B[1m${text}\x1B[0m`;
+  }
+  dim(text) {
+    return `\x1B[2m${text}\x1B[0m`;
+  }
+  cyan(text) {
+    return `\x1B[36m${text}\x1B[0m`;
+  }
+};
+var helpFormatter = new HelpFormatter();
+
+// src/cli/help/attach.ts
+var attachHelp = {
+  name: "attach",
+  description: "Attach to an existing branch by creating a new worktree",
+  usage: "phantom attach <worktree-name> <branch-name> [options]",
+  options: [
+    {
+      name: "shell",
+      short: "s",
+      type: "boolean",
+      description: "Open an interactive shell in the worktree after attaching"
+    },
+    {
+      name: "exec",
+      short: "x",
+      type: "string",
+      description: "Execute a command in the worktree after attaching",
+      example: "--exec 'git pull'"
+    }
+  ],
+  examples: [
+    {
+      description: "Attach to an existing branch",
+      command: "phantom attach review-pr main"
+    },
+    {
+      description: "Attach to a remote branch and open a shell",
+      command: "phantom attach hotfix origin/hotfix-v1.2 --shell"
+    },
+    {
+      description: "Attach to a branch and pull latest changes",
+      command: "phantom attach staging origin/staging --exec 'git pull'"
+    }
+  ],
+  notes: [
+    "The branch must already exist (locally or remotely)",
+    "If attaching to a remote branch, it will be checked out locally",
+    "Only one of --shell or --exec options can be used at a time"
+  ]
+};
+
+// src/cli/help/create.ts
+var createHelp = {
+  name: "create",
+  description: "Create a new Git worktree (phantom)",
+  usage: "phantom create <name> [options]",
+  options: [
+    {
+      name: "shell",
+      short: "s",
+      type: "boolean",
+      description: "Open an interactive shell in the new worktree after creation"
+    },
+    {
+      name: "exec",
+      short: "x",
+      type: "string",
+      description: "Execute a command in the new worktree after creation",
+      example: "--exec 'npm install'"
+    },
+    {
+      name: "tmux",
+      short: "t",
+      type: "boolean",
+      description: "Open the worktree in a new tmux window (requires being inside tmux)"
+    },
+    {
+      name: "tmux-vertical",
+      type: "boolean",
+      description: "Open the worktree in a vertical tmux pane (requires being inside tmux)"
+    },
+    {
+      name: "tmux-horizontal",
+      type: "boolean",
+      description: "Open the worktree in a horizontal tmux pane (requires being inside tmux)"
+    },
+    {
+      name: "copy-file",
+      type: "string",
+      multiple: true,
+      description: "Copy specified files from the current worktree to the new one. Can be used multiple times",
+      example: "--copy-file .env --copy-file config.local.json"
+    }
+  ],
+  examples: [
+    {
+      description: "Create a new worktree named 'feature-auth'",
+      command: "phantom create feature-auth"
+    },
+    {
+      description: "Create a worktree and open a shell in it",
+      command: "phantom create bugfix-123 --shell"
+    },
+    {
+      description: "Create a worktree and run npm install",
+      command: "phantom create new-feature --exec 'npm install'"
+    },
+    {
+      description: "Create a worktree in a new tmux window",
+      command: "phantom create experiment --tmux"
+    },
+    {
+      description: "Create a worktree and copy environment files",
+      command: "phantom create staging --copy-file .env --copy-file database.yml"
+    }
+  ],
+  notes: [
+    "The worktree name will be used as the branch name",
+    "Only one of --shell, --exec, or --tmux options can be used at a time",
+    "File copying can also be configured in phantom.config.json"
+  ]
+};
+
+// src/cli/help/delete.ts
+var deleteHelp = {
+  name: "delete",
+  description: "Delete a Git worktree (phantom)",
+  usage: "phantom delete <name> [options]",
+  options: [
+    {
+      name: "force",
+      short: "f",
+      type: "boolean",
+      description: "Force deletion even if the worktree has uncommitted or unpushed changes"
+    }
+  ],
+  examples: [
+    {
+      description: "Delete a worktree",
+      command: "phantom delete feature-auth"
+    },
+    {
+      description: "Force delete a worktree with uncommitted changes",
+      command: "phantom delete experimental --force"
+    }
+  ],
+  notes: [
+    "By default, deletion will fail if the worktree has uncommitted changes",
+    "The associated branch will also be deleted if it's not checked out elsewhere"
+  ]
+};
+
+// src/cli/help/exec.ts
+var execHelp = {
+  name: "exec",
+  description: "Execute a command in a worktree directory",
+  usage: "phantom exec <worktree-name> <command> [args...]",
+  examples: [
+    {
+      description: "Run npm test in a worktree",
+      command: "phantom exec feature-auth npm test"
+    },
+    {
+      description: "Check git status in a worktree",
+      command: "phantom exec bugfix-123 git status"
+    },
+    {
+      description: "Run a complex command with arguments",
+      command: "phantom exec staging npm run build -- --production"
+    }
+  ],
+  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"
+  ]
+};
+
+// src/cli/help/list.ts
+var listHelp = {
+  name: "list",
+  description: "List all Git worktrees (phantoms)",
+  usage: "phantom list",
+  examples: [
+    {
+      description: "List all worktrees",
+      command: "phantom list"
+    }
+  ],
+  notes: [
+    "Shows all worktrees with their paths and associated branches",
+    "The main worktree is marked as '(bare)' if using a bare repository"
+  ]
+};
+
+// src/cli/help/shell.ts
+var shellHelp = {
+  name: "shell",
+  description: "Open an interactive shell in a worktree directory",
+  usage: "phantom shell <worktree-name>",
+  examples: [
+    {
+      description: "Open a shell in a worktree",
+      command: "phantom shell feature-auth"
+    }
+  ],
+  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"
+  ]
+};
+
+// src/cli/help/version.ts
+var versionHelp = {
+  name: "version",
+  description: "Display phantom version information",
+  usage: "phantom version",
+  examples: [
+    {
+      description: "Show version",
+      command: "phantom version"
+    }
+  ],
+  notes: ["Also accessible via 'phantom --version' or 'phantom -v'"]
+};
+
+// src/cli/help/where.ts
+var whereHelp = {
+  name: "where",
+  description: "Output the filesystem path of a specific worktree",
+  usage: "phantom where <worktree-name>",
+  examples: [
+    {
+      description: "Get the path of a worktree",
+      command: "phantom where feature-auth"
+    },
+    {
+      description: "Change directory to a worktree",
+      command: "cd $(phantom where staging)"
+    }
+  ],
+  notes: [
+    "Outputs only the path, making it suitable for use in scripts",
+    "Exits with an error code if the worktree doesn't exist"
+  ]
+};
+
 // src/bin/phantom.ts
 var commands = [
   {
     name: "create",
-    description: "Create a new worktree [--shell | --exec <command> | --tmux | --tmux-vertical | --tmux-horizontal] [--copy-file <file>]...",
-    handler: createHandler
+    description: "Create a new Git worktree (phantom)",
+    handler: createHandler,
+    help: createHelp
   },
   {
     name: "attach",
-    description: "Attach to an existing branch [--shell | --exec <command>]",
-    handler: attachHandler
+    description: "Attach to an existing branch by creating a new worktree",
+    handler: attachHandler,
+    help: attachHelp
   },
   {
     name: "list",
-    description: "List all worktrees",
-    handler: listHandler
+    description: "List all Git worktrees (phantoms)",
+    handler: listHandler,
+    help: listHelp
   },
   {
     name: "where",
-    description: "Output the path of a specific worktree",
-    handler: whereHandler
+    description: "Output the filesystem path of a specific worktree",
+    handler: whereHandler,
+    help: whereHelp
   },
   {
     name: "delete",
-    description: "Delete a worktree (use --force for uncommitted changes)",
-    handler: deleteHandler
+    description: "Delete a Git worktree (phantom)",
+    handler: deleteHandler,
+    help: deleteHelp
   },
   {
     name: "exec",
     description: "Execute a command in a worktree directory",
-    handler: execHandler
+    handler: execHandler,
+    help: execHelp
   },
   {
     name: "shell",
-    description: "Open interactive shell in a worktree directory",
-    handler: shellHandler
+    description: "Open an interactive shell in a worktree directory",
+    handler: shellHandler,
+    help: shellHelp
   },
   {
     name: "version",
-    description: "Display phantom version",
-    handler: versionHandler
+    description: "Display phantom version information",
+    handler: versionHandler,
+    help: versionHelp
   }
 ];
 function printHelp(commands2) {
-  console.log("Usage: phantom <command> [options]\n");
-  console.log("Commands:");
-  for (const cmd of commands2) {
-    console.log(`  ${cmd.name.padEnd(12)} ${cmd.description}`);
-  }
+  const simpleCommands = commands2.map((cmd) => ({
+    name: cmd.name,
+    description: cmd.description
+  }));
+  console.log(helpFormatter.formatMainHelp(simpleCommands));
 }
 function findCommand(args2, commands2) {
   if (args2.length === 0) {
@@ -1381,6 +1819,14 @@ if (!command || !command.handler) {
   printHelp(commands);
   exit(1);
 }
+if (remainingArgs.includes("--help") || remainingArgs.includes("-h")) {
+  if (command.help) {
+    console.log(helpFormatter.formatCommandHelp(command.help));
+  } else {
+    console.log(`Help not available for command '${command.name}'`);
+  }
+  exit(0);
+}
 try {
   await command.handler(remainingArgs);
 } catch (error) {