@aku11i/phantom 0.6.0 → 0.8.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 {
@@ -953,6 +995,154 @@ ${message}`;
   }
 }
 
+// src/core/utils/fzf.ts
+import { spawn } from "node:child_process";
+async function selectWithFzf(items, options = {}) {
+  return new Promise((resolve2) => {
+    const args2 = [];
+    if (options.prompt) {
+      args2.push("--prompt", options.prompt);
+    }
+    if (options.header) {
+      args2.push("--header", options.header);
+    }
+    if (options.previewCommand) {
+      args2.push("--preview", options.previewCommand);
+    }
+    const fzf = spawn("fzf", args2, {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let result = "";
+    let errorOutput = "";
+    fzf.stdout.on("data", (data) => {
+      result += data.toString();
+    });
+    if (fzf.stderr) {
+      fzf.stderr.on("data", (data) => {
+        errorOutput += data.toString();
+      });
+    }
+    fzf.on("error", (error) => {
+      if (error.message.includes("ENOENT")) {
+        resolve2(
+          err(new Error("fzf command not found. Please install fzf first."))
+        );
+      } else {
+        resolve2(err(error));
+      }
+    });
+    fzf.on("close", (code) => {
+      if (code === 0) {
+        const selected = result.trim();
+        resolve2(ok(selected || null));
+      } else if (code === 1) {
+        resolve2(ok(null));
+      } else if (code === 130) {
+        resolve2(ok(null));
+      } else {
+        resolve2(err(new Error(`fzf exited with code ${code}: ${errorOutput}`)));
+      }
+    });
+    fzf.stdin.write(items.join("\n"));
+    fzf.stdin.end();
+  });
+}
+
+// src/core/worktree/list.ts
+async function getWorktreeStatus2(worktreePath) {
+  try {
+    const { stdout: stdout2 } = await executeGitCommandInDirectory(worktreePath, [
+      "status",
+      "--porcelain"
+    ]);
+    return !stdout2;
+  } catch {
+    return true;
+  }
+}
+async function listWorktrees2(gitRoot) {
+  try {
+    const gitWorktrees = await listWorktrees(gitRoot);
+    const phantomDir = getPhantomDirectory(gitRoot);
+    const phantomWorktrees = gitWorktrees.filter(
+      (worktree) => worktree.path.startsWith(phantomDir)
+    );
+    if (phantomWorktrees.length === 0) {
+      return ok({
+        worktrees: [],
+        message: "No worktrees found"
+      });
+    }
+    const worktrees = await Promise.all(
+      phantomWorktrees.map(async (gitWorktree) => {
+        const name = gitWorktree.path.substring(phantomDir.length + 1);
+        const isClean = await getWorktreeStatus2(gitWorktree.path);
+        return {
+          name,
+          path: gitWorktree.path,
+          branch: gitWorktree.branch || "(detached HEAD)",
+          isClean
+        };
+      })
+    );
+    return ok({
+      worktrees
+    });
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to list worktrees: ${errorMessage}`);
+  }
+}
+
+// src/core/worktree/select.ts
+async function selectWorktreeWithFzf(gitRoot) {
+  const listResult = await listWorktrees2(gitRoot);
+  if (isErr(listResult)) {
+    return listResult;
+  }
+  const { worktrees } = listResult.value;
+  if (worktrees.length === 0) {
+    return {
+      ok: true,
+      value: null
+    };
+  }
+  const list = worktrees.map((wt) => {
+    const branchInfo = wt.branch ? `(${wt.branch})` : "";
+    const status = !wt.isClean ? " [dirty]" : "";
+    return `${wt.name} ${branchInfo}${status}`;
+  });
+  const fzfResult = await selectWithFzf(list, {
+    prompt: "Select worktree> ",
+    header: "Git Worktrees (Phantoms)"
+  });
+  if (isErr(fzfResult)) {
+    return fzfResult;
+  }
+  if (!fzfResult.value) {
+    return {
+      ok: true,
+      value: null
+    };
+  }
+  const selectedName = fzfResult.value.split(" ")[0];
+  const selectedWorktree = worktrees.find((wt) => wt.name === selectedName);
+  if (!selectedWorktree) {
+    return {
+      ok: false,
+      error: new Error("Selected worktree not found")
+    };
+  }
+  return {
+    ok: true,
+    value: {
+      name: selectedWorktree.name,
+      branch: selectedWorktree.branch,
+      isClean: selectedWorktree.isClean
+    }
+  };
+}
+
 // src/cli/handlers/delete.ts
 async function deleteHandler(args2) {
   const { values, positionals } = parseArgs3({
@@ -964,21 +1154,32 @@ async function deleteHandler(args2) {
       },
       current: {
         type: "boolean"
+      },
+      fzf: {
+        type: "boolean",
+        default: false
       }
     },
     strict: true,
     allowPositionals: true
   });
   const deleteCurrent = values.current ?? false;
-  if (positionals.length === 0 && !deleteCurrent) {
+  const useFzf = values.fzf ?? false;
+  if (positionals.length === 0 && !deleteCurrent && !useFzf) {
     exitWithError(
-      "Please provide a worktree name to delete or use --current to delete the current worktree",
+      "Please provide a worktree name to delete, use --current to delete the current worktree, or use --fzf for interactive selection",
       exitCodes.validationError
     );
   }
-  if (positionals.length > 0 && deleteCurrent) {
+  if ((positionals.length > 0 || useFzf) && deleteCurrent) {
     exitWithError(
-      "Cannot specify both a worktree name and --current option",
+      "Cannot specify --current with a worktree name or --fzf option",
+      exitCodes.validationError
+    );
+  }
+  if (positionals.length > 0 && useFzf) {
+    exitWithError(
+      "Cannot specify both a worktree name and --fzf option",
       exitCodes.validationError
     );
   }
@@ -995,6 +1196,15 @@ async function deleteHandler(args2) {
         );
       }
       worktreeName = currentWorktree;
+    } else 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];
     }
@@ -1033,7 +1243,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);
@@ -1049,78 +1264,45 @@ async function execHandler(args2) {
 
 // src/cli/handlers/list.ts
 import { parseArgs as parseArgs5 } from "node:util";
-
-// src/core/worktree/list.ts
-async function getWorktreeStatus2(worktreePath) {
-  try {
-    const { stdout } = await executeGitCommandInDirectory(worktreePath, [
-      "status",
-      "--porcelain"
-    ]);
-    return !stdout;
-  } catch {
-    return true;
-  }
-}
-async function listWorktrees2(gitRoot) {
-  try {
-    const gitWorktrees = await listWorktrees(gitRoot);
-    const phantomDir = getPhantomDirectory(gitRoot);
-    const phantomWorktrees = gitWorktrees.filter(
-      (worktree) => worktree.path.startsWith(phantomDir)
-    );
-    if (phantomWorktrees.length === 0) {
-      return ok({
-        worktrees: [],
-        message: "No worktrees found"
-      });
-    }
-    const worktrees = await Promise.all(
-      phantomWorktrees.map(async (gitWorktree) => {
-        const name = gitWorktree.path.substring(phantomDir.length + 1);
-        const isClean = await getWorktreeStatus2(gitWorktree.path);
-        return {
-          name,
-          path: gitWorktree.path,
-          branch: gitWorktree.branch || "(detached HEAD)",
-          isClean
-        };
-      })
-    );
-    return ok({
-      worktrees
-    });
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to list worktrees: ${errorMessage}`);
-  }
-}
-
-// src/cli/handlers/list.ts
 async function listHandler(args2 = []) {
-  parseArgs5({
+  const { values } = parseArgs5({
     args: args2,
-    options: {},
+    options: {
+      fzf: {
+        type: "boolean",
+        default: false
+      }
+    },
     strict: true,
     allowPositionals: false
   });
   try {
     const gitRoot = await getGitRoot();
-    const result = await listWorktrees2(gitRoot);
-    if (isErr(result)) {
-      exitWithError("Failed to list worktrees", exitCodes.generalError);
-    }
-    const { worktrees, message } = result.value;
-    if (worktrees.length === 0) {
-      output.log(message || "No worktrees found.");
-      process.exit(exitCodes.success);
-    }
-    const maxNameLength = Math.max(...worktrees.map((wt) => wt.name.length));
-    for (const worktree of worktrees) {
-      const paddedName = worktree.name.padEnd(maxNameLength + 2);
-      const branchInfo = worktree.branch ? `(${worktree.branch})` : "";
-      const status = !worktree.isClean ? " [dirty]" : "";
-      output.log(`${paddedName} ${branchInfo}${status}`);
+    if (values.fzf) {
+      const selectResult = await selectWorktreeWithFzf(gitRoot);
+      if (isErr(selectResult)) {
+        exitWithError(selectResult.error.message, exitCodes.generalError);
+      }
+      if (selectResult.value) {
+        output.log(selectResult.value.name);
+      }
+    } else {
+      const result = await listWorktrees2(gitRoot);
+      if (isErr(result)) {
+        exitWithError("Failed to list worktrees", exitCodes.generalError);
+      }
+      const { worktrees, message } = result.value;
+      if (worktrees.length === 0) {
+        output.log(message || "No worktrees found.");
+        process.exit(exitCodes.success);
+      }
+      const maxNameLength = Math.max(...worktrees.map((wt) => wt.name.length));
+      for (const worktree of worktrees) {
+        const paddedName = worktree.name.padEnd(maxNameLength + 2);
+        const branchInfo = worktree.branch ? `(${worktree.branch})` : "";
+        const status = !worktree.isClean ? " [dirty]" : "";
+        output.log(`${paddedName} ${branchInfo}${status}`);
+      }
     }
     process.exit(exitCodes.success);
   } catch (error) {
@@ -1134,21 +1316,45 @@ async function listHandler(args2 = []) {
 // src/cli/handlers/shell.ts
 import { parseArgs as parseArgs6 } from "node:util";
 async function shellHandler(args2) {
-  const { positionals } = parseArgs6({
+  const { positionals, values } = parseArgs6({
     args: args2,
-    options: {},
+    options: {
+      fzf: {
+        type: "boolean",
+        default: false
+      }
+    },
     strict: true,
     allowPositionals: true
   });
-  if (positionals.length === 0) {
+  const useFzf = values.fzf ?? false;
+  if (positionals.length === 0 && !useFzf) {
     exitWithError(
-      "Usage: phantom shell <worktree-name>",
+      "Usage: phantom shell <worktree-name> or phantom shell --fzf",
       exitCodes.validationError
     );
   }
-  const worktreeName = positionals[0];
+  if (positionals.length > 0 && useFzf) {
+    exitWithError(
+      "Cannot specify both a worktree name and --fzf option",
+      exitCodes.validationError
+    );
+  }
+  let worktreeName;
   try {
     const gitRoot = await getGitRoot();
+    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 (!validation.exists) {
       exitWithError(
@@ -1179,7 +1385,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.8.0",
   description: "A powerful CLI tool for managing Git worktrees for parallel development",
   keywords: [
     "git",
@@ -1269,81 +1475,559 @@ async function whereWorktree(gitRoot, name) {
 
 // src/cli/handlers/where.ts
 async function whereHandler(args2) {
-  const { positionals } = parseArgs8({
+  const { positionals, values } = parseArgs8({
     args: args2,
-    options: {},
+    options: {
+      fzf: {
+        type: "boolean",
+        default: false
+      }
+    },
     strict: true,
     allowPositionals: true
   });
-  if (positionals.length === 0) {
-    exitWithError("Please provide a worktree name", exitCodes.validationError);
+  const useFzf = values.fzf ?? false;
+  if (positionals.length === 0 && !useFzf) {
+    exitWithError(
+      "Usage: phantom where <worktree-name> or phantom where --fzf",
+      exitCodes.validationError
+    );
   }
-  const worktreeName = positionals[0];
+  if (positionals.length > 0 && useFzf) {
+    exitWithError(
+      "Cannot specify both a worktree name and --fzf option",
+      exitCodes.validationError
+    );
+  }
+  let worktreeName;
+  let gitRoot;
   try {
-    const gitRoot = await getGitRoot();
-    const result = await whereWorktree(gitRoot, worktreeName);
-    if (isErr(result)) {
-      exitWithError(result.error.message, exitCodes.notFound);
-    }
-    output.log(result.value.path);
-    exitWithSuccess();
+    gitRoot = await getGitRoot();
   } catch (error) {
     exitWithError(
       error instanceof Error ? error.message : String(error),
       exitCodes.generalError
     );
   }
+  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 result = await whereWorktree(gitRoot, worktreeName);
+  if (isErr(result)) {
+    exitWithError(result.error.message, exitCodes.notFound);
+  }
+  output.log(result.value.path);
+  exitWithSuccess();
 }
 
+// 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"
+    },
+    {
+      name: "--current",
+      type: "boolean",
+      description: "Delete the current worktree"
+    },
+    {
+      name: "--fzf",
+      type: "boolean",
+      description: "Use fzf for interactive selection"
+    }
+  ],
+  examples: [
+    {
+      description: "Delete a worktree",
+      command: "phantom delete feature-auth"
+    },
+    {
+      description: "Force delete a worktree with uncommitted changes",
+      command: "phantom delete experimental --force"
+    },
+    {
+      description: "Delete the current worktree",
+      command: "phantom delete --current"
+    },
+    {
+      description: "Delete a worktree with interactive fzf selection",
+      command: "phantom delete --fzf"
+    }
+  ],
+  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",
+    "With --fzf, you can interactively select the worktree to delete"
+  ]
+};
+
+// 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 [options]",
+  options: [
+    {
+      name: "--fzf",
+      type: "boolean",
+      description: "Use fzf for interactive selection"
+    }
+  ],
+  examples: [
+    {
+      description: "List all worktrees",
+      command: "phantom list"
+    },
+    {
+      description: "List worktrees with interactive fzf selection",
+      command: "phantom list --fzf"
+    }
+  ],
+  notes: [
+    "Shows all worktrees with their paths and associated branches",
+    "The main worktree is marked as '(bare)' if using a bare repository",
+    "With --fzf, outputs only the selected worktree name"
+  ]
+};
+
+// src/cli/help/shell.ts
+var shellHelp = {
+  name: "shell",
+  description: "Open an interactive shell in a worktree directory",
+  usage: "phantom shell <worktree-name> [options]",
+  options: [
+    {
+      name: "--fzf",
+      type: "boolean",
+      description: "Use fzf for interactive selection"
+    }
+  ],
+  examples: [
+    {
+      description: "Open a shell in a worktree",
+      command: "phantom shell feature-auth"
+    },
+    {
+      description: "Open a shell with interactive fzf selection",
+      command: "phantom shell --fzf"
+    }
+  ],
+  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"
+  ]
+};
+
+// 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> [options]",
+  options: [
+    {
+      name: "--fzf",
+      type: "boolean",
+      description: "Use fzf for interactive selection"
+    }
+  ],
+  examples: [
+    {
+      description: "Get the path of a worktree",
+      command: "phantom where feature-auth"
+    },
+    {
+      description: "Change directory to a worktree",
+      command: "cd $(phantom where staging)"
+    },
+    {
+      description: "Get path with interactive fzf selection",
+      command: "phantom where --fzf"
+    },
+    {
+      description: "Change directory using fzf selection",
+      command: "cd $(phantom where --fzf)"
+    }
+  ],
+  notes: [
+    "Outputs only the path, making it suitable for use in scripts",
+    "Exits with an error code if the worktree doesn't exist",
+    "With --fzf, you can interactively select the worktree"
+  ]
+};
+
 // 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 +2065,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) {