@aku11i/phantom 0.5.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
     }
   });
 }
@@ -327,6 +329,9 @@ var output = {
   error: (message) => {
     console.error(message);
   },
+  warn: (message) => {
+    console.warn(message);
+  },
   table: (data) => {
     console.table(data);
   },
@@ -404,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);
@@ -415,13 +421,187 @@ async function attachHandler(args2) {
 // src/cli/handlers/create.ts
 import { parseArgs as parseArgs2 } from "node:util";
 
-// src/core/worktree/create.ts
+// src/core/config/loader.ts
 import fs2 from "node:fs/promises";
+import path from "node:path";
+
+// src/core/utils/type-guards.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/core/config/validate.ts
+var ConfigValidationError = class extends Error {
+  constructor(message) {
+    super(`Invalid phantom.config.json: ${message}`);
+    this.name = "ConfigValidationError";
+  }
+};
+function validateConfig(config) {
+  if (!isObject(config)) {
+    return err(new ConfigValidationError("Configuration must be an object"));
+  }
+  const cfg = config;
+  if (cfg.postCreate !== void 0) {
+    if (!isObject(cfg.postCreate)) {
+      return err(new ConfigValidationError("postCreate must be an object"));
+    }
+    const postCreate = cfg.postCreate;
+    if (postCreate.copyFiles !== void 0) {
+      if (!Array.isArray(postCreate.copyFiles)) {
+        return err(
+          new ConfigValidationError("postCreate.copyFiles must be an array")
+        );
+      }
+      if (!postCreate.copyFiles.every((f) => typeof f === "string")) {
+        return err(
+          new ConfigValidationError(
+            "postCreate.copyFiles must contain only strings"
+          )
+        );
+      }
+    }
+    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);
+}
+
+// src/core/config/loader.ts
+var ConfigNotFoundError = class extends Error {
+  constructor() {
+    super("phantom.config.json not found");
+    this.name = "ConfigNotFoundError";
+  }
+};
+var ConfigParseError = class extends Error {
+  constructor(message) {
+    super(`Failed to parse phantom.config.json: ${message}`);
+    this.name = "ConfigParseError";
+  }
+};
+async function loadConfig(gitRoot) {
+  const configPath = path.join(gitRoot, "phantom.config.json");
+  try {
+    const content = await fs2.readFile(configPath, "utf-8");
+    try {
+      const parsed = JSON.parse(content);
+      const validationResult = validateConfig(parsed);
+      if (!validationResult.ok) {
+        return err(validationResult.error);
+      }
+      return ok(validationResult.value);
+    } catch (error) {
+      return err(
+        new ConfigParseError(
+          error instanceof Error ? error.message : String(error)
+        )
+      );
+    }
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return err(new ConfigNotFoundError());
+    }
+    throw error;
+  }
+}
+
+// src/core/process/tmux.ts
+async function isInsideTmux() {
+  return process.env.TMUX !== void 0;
+}
+async function executeTmuxCommand(options) {
+  const { direction, command: command2, cwd, env } = options;
+  const tmuxArgs = [];
+  switch (direction) {
+    case "new":
+      tmuxArgs.push("new-window");
+      break;
+    case "vertical":
+      tmuxArgs.push("split-window", "-v");
+      break;
+    case "horizontal":
+      tmuxArgs.push("split-window", "-h");
+      break;
+  }
+  if (cwd) {
+    tmuxArgs.push("-c", cwd);
+  }
+  if (env) {
+    for (const [key, value] of Object.entries(env)) {
+      tmuxArgs.push("-e", `${key}=${value}`);
+    }
+  }
+  tmuxArgs.push(command2);
+  const result = await spawnProcess({
+    command: "tmux",
+    args: tmuxArgs
+  });
+  return result;
+}
+
+// src/core/worktree/create.ts
+import fs3 from "node:fs/promises";
 
 // src/core/git/libs/add-worktree.ts
 async function addWorktree(options) {
-  const { path, branch, commitish = "HEAD" } = options;
-  await executeGitCommand(["worktree", "add", path, "-b", branch, commitish]);
+  const { path: path3, branch, commitish = "HEAD" } = options;
+  await executeGitCommand(["worktree", "add", path3, "-b", branch, commitish]);
+}
+
+// src/core/worktree/file-copier.ts
+import { copyFile, mkdir, stat } from "node:fs/promises";
+import path2 from "node:path";
+var FileCopyError = class extends Error {
+  file;
+  constructor(file, message) {
+    super(`Failed to copy ${file}: ${message}`);
+    this.name = "FileCopyError";
+    this.file = file;
+  }
+};
+async function copyFiles(sourceDir, targetDir, files) {
+  const copiedFiles = [];
+  const skippedFiles = [];
+  for (const file of files) {
+    const sourcePath = path2.join(sourceDir, file);
+    const targetPath = path2.join(targetDir, file);
+    try {
+      const stats = await stat(sourcePath);
+      if (!stats.isFile()) {
+        skippedFiles.push(file);
+        continue;
+      }
+      const targetDirPath = path2.dirname(targetPath);
+      await mkdir(targetDirPath, { recursive: true });
+      await copyFile(sourcePath, targetPath);
+      copiedFiles.push(file);
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+        skippedFiles.push(file);
+      } else {
+        return err(
+          new FileCopyError(
+            file,
+            error instanceof Error ? error.message : String(error)
+          )
+        );
+      }
+    }
+  }
+  return ok({ copiedFiles, skippedFiles });
 }
 
 // src/core/worktree/create.ts
@@ -434,9 +614,9 @@ async function createWorktree(gitRoot, name, options = {}) {
   const worktreesPath = getPhantomDirectory(gitRoot);
   const worktreePath = getWorktreePath(gitRoot, name);
   try {
-    await fs2.access(worktreesPath);
+    await fs3.access(worktreesPath);
   } catch {
-    await fs2.mkdir(worktreesPath, { recursive: true });
+    await fs3.mkdir(worktreesPath, { recursive: true });
   }
   const validation = await validateWorktreeDoesNotExist(gitRoot, name);
   if (validation.exists) {
@@ -448,9 +628,28 @@ async function createWorktree(gitRoot, name, options = {}) {
       branch,
       commitish
     });
+    let copiedFiles;
+    let skippedFiles;
+    let copyError;
+    if (options.copyFiles && options.copyFiles.length > 0) {
+      const copyResult = await copyFiles(
+        gitRoot,
+        worktreePath,
+        options.copyFiles
+      );
+      if (isOk(copyResult)) {
+        copiedFiles = copyResult.value.copiedFiles;
+        skippedFiles = copyResult.value.skippedFiles;
+      } else {
+        copyError = copyResult.error.message;
+      }
+    }
     return ok({
       message: `Created worktree '${name}' at ${worktreePath}`,
-      path: worktreePath
+      path: worktreePath,
+      copiedFiles,
+      skippedFiles,
+      copyError
     });
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
@@ -470,6 +669,26 @@ async function createHandler(args2) {
       exec: {
         type: "string",
         short: "x"
+      },
+      tmux: {
+        type: "boolean",
+        short: "t"
+      },
+      "tmux-vertical": {
+        type: "boolean"
+      },
+      "tmux-v": {
+        type: "boolean"
+      },
+      "tmux-horizontal": {
+        type: "boolean"
+      },
+      "tmux-h": {
+        type: "boolean"
+      },
+      "copy-file": {
+        type: "string",
+        multiple: true
       }
     },
     strict: true,
@@ -484,31 +703,97 @@ async function createHandler(args2) {
   const worktreeName = positionals[0];
   const openShell = values.shell ?? false;
   const execCommand = values.exec;
-  if (openShell && execCommand) {
+  const copyFileOptions = values["copy-file"];
+  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 ([openShell, execCommand !== void 0, tmuxOption].filter(Boolean).length > 1) {
+    exitWithError(
+      "Cannot use --shell, --exec, and --tmux options together",
+      exitCodes.validationError
+    );
+  }
+  if (tmuxOption && !await isInsideTmux()) {
     exitWithError(
-      "Cannot use --shell and --exec together",
+      "The --tmux option can only be used inside a tmux session",
       exitCodes.validationError
     );
   }
   try {
     const gitRoot = await getGitRoot();
-    const result = await createWorktree(gitRoot, worktreeName);
+    let filesToCopy = [];
+    const configResult = await loadConfig(gitRoot);
+    if (isOk(configResult)) {
+      if (configResult.value.postCreate?.copyFiles) {
+        filesToCopy = [...configResult.value.postCreate.copyFiles];
+      }
+    } else {
+      if (configResult.error instanceof ConfigValidationError) {
+        output.warn(`Configuration warning: ${configResult.error.message}`);
+      } else if (configResult.error instanceof ConfigParseError) {
+        output.warn(`Configuration warning: ${configResult.error.message}`);
+      }
+    }
+    if (copyFileOptions && copyFileOptions.length > 0) {
+      const cliFiles = Array.isArray(copyFileOptions) ? copyFileOptions : [copyFileOptions];
+      filesToCopy = [.../* @__PURE__ */ new Set([...filesToCopy, ...cliFiles])];
+    }
+    const result = await createWorktree(gitRoot, worktreeName, {
+      copyFiles: filesToCopy.length > 0 ? filesToCopy : void 0
+    });
     if (isErr(result)) {
       const exitCode = result.error instanceof WorktreeAlreadyExistsError ? exitCodes.validationError : exitCodes.generalError;
       exitWithError(result.error.message, exitCode);
     }
     output.log(result.value.message);
+    if (result.value.copyError) {
+      output.error(
+        `
+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;
@@ -530,6 +815,28 @@ Entering worktree '${worktreeName}' at ${result.value.path}`
       }
       process.exit(shellResult.value.exitCode ?? 0);
     }
+    if (tmuxDirection && isOk(result)) {
+      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: result.value.path,
+        env: {
+          PHANTOM: "1",
+          PHANTOM_NAME: worktreeName,
+          PHANTOM_PATH: result.value.path
+        }
+      });
+      if (isErr(tmuxResult)) {
+        output.error(tmuxResult.error.message);
+        const exitCode = "exitCode" in tmuxResult.error ? tmuxResult.error.exitCode ?? exitCodes.generalError : exitCodes.generalError;
+        exitWithError("", exitCode);
+      }
+    }
     exitWithSuccess();
   } catch (error) {
     exitWithError(
@@ -542,17 +849,77 @@ Entering worktree '${worktreeName}' at ${result.value.path}`
 // src/cli/handlers/delete.ts
 import { parseArgs as parseArgs3 } from "node:util";
 
+// src/core/git/libs/list-worktrees.ts
+async function listWorktrees(gitRoot) {
+  const { stdout: stdout2 } = await executeGitCommand([
+    "worktree",
+    "list",
+    "--porcelain"
+  ]);
+  const worktrees = [];
+  let currentWorktree = {};
+  const lines = stdout2.split("\n").filter((line) => line.length > 0);
+  for (const line of lines) {
+    if (line.startsWith("worktree ")) {
+      if (currentWorktree.path) {
+        worktrees.push(currentWorktree);
+      }
+      currentWorktree = {
+        path: line.substring("worktree ".length),
+        isLocked: false,
+        isPrunable: false
+      };
+    } else if (line.startsWith("HEAD ")) {
+      currentWorktree.head = line.substring("HEAD ".length);
+    } else if (line.startsWith("branch ")) {
+      const fullBranch = line.substring("branch ".length);
+      currentWorktree.branch = fullBranch.startsWith("refs/heads/") ? fullBranch.substring("refs/heads/".length) : fullBranch;
+    } else if (line === "detached") {
+      currentWorktree.branch = "(detached HEAD)";
+    } else if (line === "locked") {
+      currentWorktree.isLocked = true;
+    } else if (line === "prunable") {
+      currentWorktree.isPrunable = true;
+    }
+  }
+  if (currentWorktree.path) {
+    worktrees.push(currentWorktree);
+  }
+  return worktrees;
+}
+
+// src/core/git/libs/get-current-worktree.ts
+async function getCurrentWorktree(gitRoot) {
+  try {
+    const { stdout: currentPath } = await executeGitCommand([
+      "rev-parse",
+      "--show-toplevel"
+    ]);
+    const currentPathTrimmed = currentPath.trim();
+    const worktrees = await listWorktrees(gitRoot);
+    const currentWorktree = worktrees.find(
+      (wt) => wt.path === currentPathTrimmed
+    );
+    if (!currentWorktree || currentWorktree.path === gitRoot) {
+      return null;
+    }
+    return currentWorktree.branch;
+  } catch {
+    return null;
+  }
+}
+
 // 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 {
@@ -636,21 +1003,43 @@ async function deleteHandler(args2) {
       force: {
         type: "boolean",
         short: "f"
+      },
+      current: {
+        type: "boolean"
       }
     },
     strict: true,
     allowPositionals: true
   });
-  if (positionals.length === 0) {
+  const deleteCurrent = values.current ?? false;
+  if (positionals.length === 0 && !deleteCurrent) {
     exitWithError(
-      "Please provide a worktree name to delete",
+      "Please provide a worktree name to delete or use --current to delete the current worktree",
+      exitCodes.validationError
+    );
+  }
+  if (positionals.length > 0 && deleteCurrent) {
+    exitWithError(
+      "Cannot specify both a worktree name and --current option",
       exitCodes.validationError
     );
   }
-  const worktreeName = positionals[0];
   const forceDelete = values.force ?? false;
   try {
     const gitRoot = await getGitRoot();
+    let worktreeName;
+    if (deleteCurrent) {
+      const currentWorktree = await getCurrentWorktree(gitRoot);
+      if (!currentWorktree) {
+        exitWithError(
+          "Not in a worktree directory. The --current option can only be used from within a worktree.",
+          exitCodes.validationError
+        );
+      }
+      worktreeName = currentWorktree;
+    } else {
+      worktreeName = positionals[0];
+    }
     const result = await deleteWorktree(gitRoot, worktreeName, {
       force: forceDelete
     });
@@ -686,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);
@@ -703,53 +1097,14 @@ async function execHandler(args2) {
 // src/cli/handlers/list.ts
 import { parseArgs as parseArgs5 } from "node:util";
 
-// src/core/git/libs/list-worktrees.ts
-async function listWorktrees(gitRoot) {
-  const { stdout } = await executeGitCommand([
-    "worktree",
-    "list",
-    "--porcelain"
-  ]);
-  const worktrees = [];
-  let currentWorktree = {};
-  const lines = stdout.split("\n").filter((line) => line.length > 0);
-  for (const line of lines) {
-    if (line.startsWith("worktree ")) {
-      if (currentWorktree.path) {
-        worktrees.push(currentWorktree);
-      }
-      currentWorktree = {
-        path: line.substring("worktree ".length),
-        isLocked: false,
-        isPrunable: false
-      };
-    } else if (line.startsWith("HEAD ")) {
-      currentWorktree.head = line.substring("HEAD ".length);
-    } else if (line.startsWith("branch ")) {
-      const fullBranch = line.substring("branch ".length);
-      currentWorktree.branch = fullBranch.startsWith("refs/heads/") ? fullBranch.substring("refs/heads/".length) : fullBranch;
-    } else if (line === "detached") {
-      currentWorktree.branch = "(detached HEAD)";
-    } else if (line === "locked") {
-      currentWorktree.isLocked = true;
-    } else if (line === "prunable") {
-      currentWorktree.isPrunable = true;
-    }
-  }
-  if (currentWorktree.path) {
-    worktrees.push(currentWorktree);
-  }
-  return worktrees;
-}
-
 // 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;
   }
@@ -871,7 +1226,7 @@ import { parseArgs as parseArgs7 } from "node:util";
 var package_default = {
   name: "@aku11i/phantom",
   packageManager: "pnpm@10.8.1",
-  version: "0.5.0",
+  version: "0.7.0",
   description: "A powerful CLI tool for managing Git worktrees for parallel development",
   keywords: [
     "git",
@@ -901,7 +1256,9 @@ var package_default = {
     phantom: "node ./src/bin/phantom.ts",
     build: "node build.ts",
     typecheck: "tsgo --noEmit",
-    test: "node --test --experimental-strip-types --experimental-test-module-mocks src/**/*.test.ts",
+    test: 'node --test --experimental-strip-types --experimental-test-module-mocks "src/**/*.test.js"',
+    "test:coverage": 'node --experimental-test-coverage --test --experimental-strip-types --experimental-test-module-mocks "src/**/*.test.js"',
+    "test:file": "node --test --experimental-strip-types --experimental-test-module-mocks",
     lint: "biome check .",
     fix: "biome check --write .",
     ready: "pnpm fix && pnpm typecheck && pnpm test",
@@ -985,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>]",
-    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) {
@@ -1071,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) {