worktree-add 1.0.0 → 1.1.1

package/README.md

@@ -0,0 +1,106 @@
+# 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 removing it with `rm -rf`.
+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
+- POSIX‑like shell (uses `rm -rf` for cleaning the destination)
+
+## 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,7 +15,23 @@ 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";
-async function main(branchRaw) {
+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
     const existingWorktree = findWorktreeByBranchName(branch);
@@ -39,22 +55,40 @@ async function main(branchRaw) {
     await copyUntrackedFiles(repoRoot, destinationDirectory);
     // Step 4: Install dependencies and run project-specific setup
     await setupProject(destinationDirectory);
-    // Step 6: Open the new worktree in Cursor
-    console.log("➤ Opening Cursor …");
-    spawnSync("cursor", [destinationDirectory], { stdio: "inherit" });
+    // Step 5: Open the new worktree in the editor
+    const editor = resolveEditor({
+        optionEditor: options.editor,
+        environmentEditor: process.env.WORKTREE_ADD_EDITOR,
+    });
+    // Validate editor command to prevent injection attacks
+    if (!isEditorCommandSafe(editor)) {
+        exitWithMessage("Invalid editor command: shell metacharacters not allowed.\n" +
+            "Please use a simple editor name (e.g., 'code', 'cursor', 'vim').");
+    }
+    console.log(`➤ Opening ${editor} …`);
+    const result = spawnSync(editor, [destinationDirectory], {
+        stdio: "inherit",
+    });
+    if (result.error) {
+        console.error(`Failed to open ${editor}: ${result.error.message}`);
+        console.error("The worktree was created successfully, but the editor could not be opened.");
+    }
 }
 const program = new Command()
     .name(packageJson.name)
     .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")
-    .action(async (branch) => {
+    .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);
+        await main(branch, options);
     }
     catch (error) {
         console.error(error);
         process.exitCode = 1;
     }
 });
-program.parse();
+if (!process.env.VITEST) {
+    program.parse();
+}

package/package.json

@@ -2,12 +2,16 @@
   "name": "worktree-add",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.0.0",
-  "description": "",
+  "version": "1.1.1",
+  "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,10 +39,17 @@
     "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",