worktree-add 1.1.0 → 1.2.0

package/README.md

@@ -0,0 +1,105 @@
+# worktree-add
+
+Create a Git worktree next to your current repo for a branch, copy useful local files, install deps, and open it in your editor.
+
+## What it does
+
+Running `worktree-add <branch>` from inside a repo:
+
+1. Normalizes `<branch>` (supports `origin/foo`, `refs/heads/foo`, etc.).
+2. Refuses if that branch is already checked out in any worktree.
+3. Picks a destination next to your current repo: `../<repo>-<safe-branch>`.
+4. If the destination exists, asks before moving it to the system trash.
+5. Fetches `origin/<branch>` when needed and creates a git worktree:
+   - reuses an existing local branch
+   - or creates a tracking branch from `origin/<branch>`
+   - or creates a new branch from the current `HEAD`
+6. Copies untracked / ignored files into the new worktree, skipping heavy stuff
+   (`node_modules`, `dist`, `.next`, caches, virtualenvs, etc.).
+7. Detects your package manager and installs dependencies with lockfile‑safe flags
+   (`npm ci`, `pnpm install --frozen-lockfile`, `yarn install --immutable`, etc.).
+8. If the project uses Next.js and supports it, runs `next typegen`.
+9. Opens the new worktree in your editor.
+
+Your original checkout is left untouched.
+
+## Requirements
+
+- Node.js ≥ 22.14.0
+- Git with `git worktree` support
+
+## Install / run
+
+You usually don’t need a global install.
+
+```bash
+# inside /my/path/my-app
+# one‑off
+npx worktree-add feature/my-branch
+
+# or install globally
+pnpm add -g worktree-add   # or: npm i -g worktree-add
+worktree-add feature/my-branch
+```
+
+Run it from anywhere inside an existing worktree of the repo.
+
+## Usage
+
+```bash
+# inside /my/path/my-app
+worktree-add <branch>
+```
+
+Run this inside an existing worktree of your project—the tool discovers the repo root from your current directory and creates the sibling worktree next to it.
+
+Example:
+
+```bash
+# inside /my/path/my-app
+# reuses a local branch, tracks origin/<branch> if it exists, otherwise creates a new branch from current HEAD
+worktree-add feature/login-form
+```
+
+A new branch from the current HEAD is created only when the branch does not already
+exist locally or on `origin/`.
+
+Destination directory (assuming repo named `my-app`):
+
+```text
+/my/path/my-app                     # current checkout
+/my/path/my-app-feature-login-form  # new worktree for branch "feature/login-form"
+```
+
+## Editor control
+
+By default the tool opens the new worktree in:
+
+1. `--editor <command>` if passed
+2. `WORKTREE_ADD_EDITOR` env var
+3. otherwise `code`
+
+Only simple command names are allowed (no `;`, `&`, pipes, etc.) to avoid shell injection. Examples:
+
+```bash
+worktree-add feature/foo -e code
+WORKTREE_ADD_EDITOR=vim worktree-add feature/foo
+```
+
+If launching the editor fails, the worktree still stays created and ready.
+
+Tip: add a shell helper with your preferred editor in your shell profile. Example snippet to add:
+
+```bash
+worktree-add() { WORKTREE_ADD_EDITOR=cursor command worktree-add "$@" }
+```
+
+Add it to your shell profile:
+
+- zsh: `~/.zshrc` or `~/.zprofile`
+- bash: `~/.bashrc` or `~/.bash_profile`
+- fish: `~/.config/fish/config.fish`
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -6,4 +6,10 @@
  * Note: the destination is placed next to whichever worktree you run this from,
  * not necessarily the original "main" checkout.
  */
+interface ResolveEditorInput {
+    optionEditor?: string;
+    environmentEditor?: string;
+}
+export declare function resolveEditor({ optionEditor, environmentEditor, }?: ResolveEditorInput): string;
+export declare function isEditorCommandSafe(editor: string): boolean;
 export {};

package/dist/cli.js

@@ -15,6 +15,22 @@ import { copyUntrackedFiles } from "./worktree/untracked-file-copy.js";
 import { fetchRemoteBranch, createWorktree } from "./git/worktree-creation.js";
 import { handleExistingDirectory } from "./worktree/destination-directory.js";
 import { setupProject } from "./project/setup.js";
+export function resolveEditor({ optionEditor, environmentEditor, } = {}) {
+    const normalizedOption = optionEditor?.trim();
+    const normalizedEnvironment = environmentEditor?.trim();
+    return normalizedOption || normalizedEnvironment || "code";
+}
+export function isEditorCommandSafe(editor) {
+    const normalized = editor.normalize("NFKC");
+    const trimmed = normalized.trim();
+    // Reject empty or excessively long commands
+    if (trimmed.length === 0 || trimmed.length > 256) {
+        return false;
+    }
+    // Reject common shell metacharacters, whitespace, and control characters to prevent injection
+    const unsafeCharacters = /[\\;&|`$(){}<>\s]|\p{Cc}/u;
+    return !unsafeCharacters.test(trimmed);
+}
 async function main(branchRaw, options) {
     const branch = normalizeBranchName(branchRaw);
     // Prevent attempting to add a worktree for a branch that is already checked out
@@ -40,14 +56,12 @@ async function main(branchRaw, options) {
     // Step 4: Install dependencies and run project-specific setup
     await setupProject(destinationDirectory);
     // Step 5: Open the new worktree in the editor
-    const editor = options.editor ?? process.env.WORKTREE_ADD_EDITOR ?? "cursor";
+    const editor = resolveEditor({
+        optionEditor: options.editor,
+        environmentEditor: process.env.WORKTREE_ADD_EDITOR,
+    });
     // Validate editor command to prevent injection attacks
-    if (editor.includes(";") ||
-        editor.includes("&") ||
-        editor.includes("|") ||
-        editor.includes("`") ||
-        editor.includes("$") ||
-        editor.includes("\n")) {
+    if (!isEditorCommandSafe(editor)) {
         exitWithMessage("Invalid editor command: shell metacharacters not allowed.\n" +
             "Please use a simple editor name (e.g., 'code', 'cursor', 'vim').");
     }
@@ -65,7 +79,7 @@ const program = new Command()
     .description("Create or reuse a Git worktree for a branch as a sibling of the current worktree")
     .version(packageJson.version)
     .argument("<branch>", "branch name for the worktree")
-    .option("-e, --editor <command>", "Editor to open the worktree with (default: WORKTREE_ADD_EDITOR env var or 'cursor')")
+    .option("-e, --editor <command>", "Editor to open the worktree with (default: WORKTREE_ADD_EDITOR env var or 'code')")
     .action(async (branch, options) => {
     try {
         await main(branch, options);
@@ -75,4 +89,6 @@ const program = new Command()
         process.exitCode = 1;
     }
 });
-program.parse();
+if (!process.env.VITEST) {
+    program.parse();
+}

package/dist/worktree/destination-directory.js

@@ -3,7 +3,19 @@
  *
  * Utilities for managing worktree directories
  */
-import { spawnSync } from "node:child_process";
+/**
+ * Cross-platform trash functionality using the trash package.
+ *
+ * Platform-specific behavior:
+ * - macOS: Uses Finder's trash (~/.Trash)
+ * - Windows: Uses Recycle Bin
+ * - Linux: Uses freedesktop.org trash specification (~/.local/share/Trash)
+ *
+ * Note: On headless/CI systems, the trash directory is still created but
+ * may not be visible in a GUI. Files can be recovered by navigating to
+ * the platform-specific trash location.
+ */
+import trash from "trash";
 import path from "node:path";
 import { fileExists, confirm, exitWithMessage } from "../git/git.js";
 /**
@@ -14,20 +26,20 @@ export async function handleExistingDirectory(destinationDirectory) {
     if (!(await fileExists(destinationDirectory))) {
         return;
     }
-    const proceed = await confirm(`Directory '${path.basename(destinationDirectory)}' already exists. Remove and recreate?`);
+    const proceed = await confirm(`Directory '${path.basename(destinationDirectory)}' already exists. Move to trash and recreate? (You can restore it from your system trash if needed)`);
     if (!proceed) {
         console.log("Operation cancelled.");
         // eslint-disable-next-line unicorn/no-process-exit -- User requested cancellation
         process.exit(0);
     }
-    // Remove the existing directory
-    console.log(`➤ Removing existing directory...`);
-    const result = spawnSync("rm", ["-rf", destinationDirectory], {
-        encoding: "utf8",
-    });
-    if (result.error)
-        throw result.error;
-    if (result.status !== 0) {
-        exitWithMessage(`Failed to remove existing directory: ${result.stderr}`);
+    // Move the existing directory to trash
+    console.log(`➤ Moving existing directory to trash...`);
+    try {
+        await trash(destinationDirectory);
+        console.log("✓ Directory moved to trash successfully");
+    }
+    catch (error) {
+        console.error("Error details:", error);
+        exitWithMessage(`Failed to move existing directory to trash: ${error instanceof Error ? error.message : String(error)}`);
     }
 }

package/package.json

@@ -2,12 +2,16 @@
   "name": "worktree-add",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.1.0",
-  "description": "",
+  "version": "1.2.0",
+  "description": "Create a Git worktree next to your current repo for a branch, copy useful local files, install deps, and open it in your editor.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Jercik/worktree-add.git"
   },
+  "homepage": "https://github.com/Jercik/worktree-add#readme",
+  "bugs": {
+    "url": "https://github.com/Jercik/worktree-add/issues"
+  },
   "type": "module",
   "bin": {
     "worktree-add": "bin/worktree-add"
@@ -35,14 +39,22 @@
     "knip": "knip",
     "fta:check": "fta-check --threshold 55"
   },
-  "keywords": [],
+  "keywords": [
+    "git",
+    "worktree",
+    "cli",
+    "workflow",
+    "git-worktree",
+    "development"
+  ],
   "packageManager": "pnpm@10.22.0",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.14.0"
   },
   "dependencies": {
     "commander": "^14.0.2",
-    "package-manager-detector": "^1.5.0"
+    "package-manager-detector": "^1.5.0",
+    "trash": "^10.0.0"
   },
   "devDependencies": {
     "@commitlint/cli": "^20.1.0",