claude-code-merge-queue 0.1.14

package/dist/bin/mergequeue.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+/**
+ * The mergequeue CLI. Every subcommand reads mergequeue.config from the
+ * current repo — see src/lib/config.ts — so none of this is hardcoded to
+ * any one project's branch names.
+ */
+import { readFileSync } from "node:fs";
+import { land } from "../land.js";
+import { sync } from "../sync.js";
+import { promote } from "../promote.js";
+import { runPreview } from "../preview.js";
+import { buildLock } from "../build-lock.js";
+import { findRepoRoot, hasConfig, loadConfig, detectCurrentBranch, DEFAULTS } from "../lib/config.js";
+import { checkPush, parseRefUpdates } from "../lib/check-push.js";
+import { runWorktreeCreateHook } from "../hooks/worktree-create.js";
+import { lanePort } from "../lib/lane-port.js";
+import { claudeMdSnippet, MARKER } from "../lib/claude-md-snippet.js";
+import { detectCheckCommand, runCheckCommand } from "../lib/check-command.js";
+import { wireClaudeSettings, wireHuskyPrePush, ensureHooksPath, wirePackageJsonScripts } from "../lib/wire-hooks.js";
+import { resolveMainCheckout } from "../lib/main-checkout.js";
+import { pruneLandedLanes } from "../lib/prune-lanes.js";
+const [, , command, ...rest] = process.argv;
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function init() {
+    const root = findRepoRoot();
+    if (!root) {
+        console.error("mergequeue init: not inside a git repo.");
+        process.exit(1);
+    }
+    const { writeFileSync, readFileSync: read, existsSync, appendFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    // What actually got newly written or modified this run — only these need
+    // committing. If everything below was already wired from a previous run,
+    // there's nothing new to tell you to commit.
+    const writtenFiles = [];
+    if (hasConfig(root)) {
+        console.log("mergequeue init: mergequeue.config.mjs already exists — leaving it alone.");
+    }
+    else {
+        writtenFiles.push("mergequeue.config.mjs");
+        const detectedBranch = detectCurrentBranch(root);
+        const detectedCheck = detectCheckCommand(root);
+        const generated = {
+            ...DEFAULTS,
+            ...(detectedBranch ? { integrationBranch: detectedBranch } : {}),
+            ...(detectedCheck ? { checkCommand: detectedCheck } : {}),
+        };
+        const template = `// mergequeue.config.mjs — generated by \`mergequeue init\`. Edit freely.
+// Its presence here is what turns MergeQueue ON for this repo.
+
+/** @type {import("mergequeue").MergeQueueConfig} */
+export default ${JSON.stringify(generated, null, 2)};
+`;
+        writeFileSync(join(root, "mergequeue.config.mjs"), template);
+        console.log(`mergequeue init: wrote ${join(root, "mergequeue.config.mjs")}`);
+        if (detectedBranch && detectedBranch !== DEFAULTS.integrationBranch) {
+            console.log(`  (detected current branch "${detectedBranch}" — set as integrationBranch instead of the "${DEFAULTS.integrationBranch}" default)`);
+        }
+        else if (!detectedBranch) {
+            console.log("");
+            console.log(`  ⚠️  Couldn't detect the current branch (detached HEAD?) — integrationBranch`);
+            console.log(`      defaulted to "${DEFAULTS.integrationBranch}". Verify that's actually right`);
+            console.log(`      in mergequeue.config.mjs before committing it.`);
+        }
+        if (detectedCheck) {
+            console.log(`  (detected "${detectedCheck}" from package.json — set as checkCommand)`);
+        }
+        else {
+            console.log("");
+            console.log("  ⚠️  No checkCommand detected (no check:push/check/ci/test script found in");
+            console.log("      package.json). Every push is BLOCKED until you set one — or set");
+            console.log("      checksRequired: false to deliberately run with no checks.");
+        }
+    }
+    // This is the part that actually makes agents use the workflow without a
+    // human reminding them every session — see claude-md-snippet.ts.
+    const claudeMdPath = join(root, "CLAUDE.md");
+    const cfg = hasConfig(root) ? await loadConfig(root) : DEFAULTS;
+    const snippet = claudeMdSnippet(cfg);
+    if (!existsSync(claudeMdPath)) {
+        writeFileSync(claudeMdPath, `# Project instructions for Claude Code\n\n${snippet}`);
+        console.log(`mergequeue init: wrote ${claudeMdPath}`);
+        writtenFiles.push("CLAUDE.md");
+    }
+    else if (!read(claudeMdPath, "utf8").includes(MARKER)) {
+        appendFileSync(claudeMdPath, `\n${snippet}`);
+        console.log(`mergequeue init: appended the MergeQueue workflow section to ${claudeMdPath}`);
+        writtenFiles.push("CLAUDE.md");
+    }
+    else {
+        console.log(`mergequeue init: ${claudeMdPath} already has the MergeQueue workflow section — leaving it alone.`);
+    }
+    const claudeSettingsResult = wireClaudeSettings(root);
+    switch (claudeSettingsResult) {
+        case "created":
+            console.log(`mergequeue init: wrote ${join(root, ".claude", "settings.json")} with the WorktreeCreate hook.`);
+            writtenFiles.push(".claude/settings.json");
+            break;
+        case "merged":
+            console.log(`mergequeue init: added the WorktreeCreate hook to your existing ${join(root, ".claude", "settings.json")}.`);
+            writtenFiles.push(".claude/settings.json");
+            break;
+        case "already-wired":
+            console.log("mergequeue init: .claude/settings.json already has the WorktreeCreate hook — leaving it alone.");
+            break;
+        case "unparseable":
+            console.log("mergequeue init: .claude/settings.json exists but isn't valid JSON — left untouched. Wire it manually,");
+            console.log("  see node_modules/mergequeue/hooks/claude-settings.example.json.");
+            break;
+    }
+    const prePushResult = wireHuskyPrePush(root);
+    switch (prePushResult) {
+        case "created":
+            console.log("mergequeue init: wrote .husky/pre-push.");
+            writtenFiles.push(".husky/pre-push");
+            break;
+        case "merged":
+            console.log("mergequeue init: appended MergeQueue's checks to your existing .husky/pre-push.");
+            writtenFiles.push(".husky/pre-push");
+            break;
+        case "already-wired":
+            console.log("mergequeue init: .husky/pre-push already wired — leaving it alone.");
+            break;
+        case "no-husky":
+            console.log("mergequeue init: no .husky/ directory found — pre-push hook NOT wired automatically.");
+            console.log("  Install Husky, or copy node_modules/mergequeue/hooks/pre-push to .git/hooks/pre-push");
+            console.log("  yourself (note: .git/hooks isn't version-controlled — only Husky's is shared with your team).");
+            break;
+    }
+    if (prePushResult === "created" || prePushResult === "merged" || prePushResult === "already-wired") {
+        // A .husky/pre-push file enforces nothing until core.hooksPath actually
+        // points at .husky — normally a side effect of the package manager's
+        // install step, which may not have run yet (e.g. a fresh clone, right
+        // where Quickstart leaves you). Without this, a direct push sails
+        // through uncontested with no indication anything's wrong.
+        switch (ensureHooksPath(root)) {
+            case "set":
+                console.log("mergequeue init: set core.hooksPath=.husky so the pre-push hook actually runs (normally set by your package manager's install step, which may not have run yet).");
+                break;
+            case "already-set":
+                break; // the common case once installed — nothing to say
+            case "custom-path":
+                console.log("mergequeue init: core.hooksPath is set to something other than .husky — leaving it alone.");
+                console.log("  Wrote .husky/pre-push, but it won't run until your hooks path points there. Reconcile this yourself.");
+                break;
+        }
+    }
+    const scriptsResult = wirePackageJsonScripts(root);
+    switch (scriptsResult.result) {
+        case "added":
+            console.log(`mergequeue init: added "${scriptsResult.added.join('", "')}" to package.json scripts.`);
+            writtenFiles.push("package.json");
+            break;
+        case "already-wired":
+            console.log("mergequeue init: package.json already has all five scripts — leaving them alone.");
+            break;
+        case "no-package-json":
+            console.log("mergequeue init: no package.json found — scripts NOT wired automatically.");
+            console.log('  Add "land"/"sync"/"promote"/"preview"/"preview:restore" -> "mergequeue <name>" yourself.');
+            break;
+        case "unparseable":
+            console.log("mergequeue init: package.json exists but isn't valid JSON — left untouched. Wire the scripts manually.");
+            break;
+    }
+    console.log("");
+    console.log("Next steps:");
+    if (writtenFiles.length > 0) {
+        console.log(`  1. Commit what it wrote — ${writtenFiles.join(", ")}.`);
+        console.log("  2. claude --worktree <name> — the agent takes it from there.");
+    }
+    else {
+        console.log("  1. claude --worktree <name> — the agent takes it from there.");
+        console.log("     (everything was already wired — nothing new to commit)");
+    }
+}
+async function main() {
+    switch (command) {
+        case "init":
+            return init();
+        case "hook": {
+            const sub = rest[0];
+            if (sub === "worktree-create")
+                return runWorktreeCreateHook();
+            console.error(`mergequeue hook: unknown hook "${sub ?? ""}". Only "worktree-create" is supported.`);
+            process.exit(1);
+            return;
+        }
+        case "port": {
+            const root = findRepoRoot();
+            if (!root || !hasConfig(root)) {
+                console.error("mergequeue port: no mergequeue.config found — not a lane.");
+                process.exit(1);
+            }
+            const cfg = await loadConfig(root);
+            const port = lanePort(process.cwd(), cfg);
+            if (port === null) {
+                console.error("mergequeue port: current directory doesn't look like a lane worktree.");
+                process.exit(1);
+            }
+            console.log(port);
+            return;
+        }
+        case "land":
+            return land();
+        case "sync":
+            process.exit(await sync());
+            return;
+        case "promote":
+            process.exit(await promote());
+            return;
+        case "prune": {
+            // `land` already does this automatically as a side effect of every
+            // successful landing — this is the on-demand escape hatch for
+            // "clean these up right now" instead of waiting for the next lane to
+            // land something. Same safety rules apply: only already-merged
+            // branches, never anything with a live process inside, never the
+            // worktree this command itself is running from.
+            const root = findRepoRoot();
+            if (!root || !hasConfig(root)) {
+                console.error("mergequeue prune: no mergequeue.config found — nothing to do.");
+                process.exit(0);
+            }
+            const cfg = await loadConfig(root);
+            const mainTop = resolveMainCheckout(process.cwd());
+            const pruned = pruneLandedLanes(mainTop, cfg, process.cwd());
+            if (pruned.length === 0) {
+                console.log("mergequeue prune: nothing to clean up — no already-landed sibling lanes found.");
+            }
+            else {
+                const names = pruned.map((p) => p.split("/").pop()).join(", ");
+                console.log(`mergequeue prune: removed ${pruned.length} already-landed lane${pruned.length === 1 ? "" : "s"}: ${names}`);
+            }
+            return;
+        }
+        case "preview":
+            return runPreview(rest);
+        case "build-lock": {
+            const parts = rest[0] === "--" ? rest.slice(1) : rest;
+            return buildLock(parts);
+        }
+        case "check-push": {
+            const root = findRepoRoot();
+            if (!root || !hasConfig(root)) {
+                // No config means MergeQueue isn't enabled for this repo — nothing to enforce.
+                process.exit(0);
+            }
+            const cfg = await loadConfig(root);
+            const stdin = await readStdin();
+            const refUpdates = parseRefUpdates(stdin);
+            // git still invokes pre-push (with empty stdin) for a push that
+            // updates zero refs — e.g. re-pushing a branch that's already exactly
+            // up to date on the remote. There's nothing to block (nothing is
+            // actually changing on the remote either way) and nothing meaningful
+            // for checkCommand to verify — running it anyway just produces a
+            // confusing, unrelated failure (a missing devDependency, say) that
+            // looks exactly like a real block but isn't one. Recognize "nothing
+            // to push" explicitly instead of silently falling through both checks.
+            if (refUpdates.length === 0) {
+                console.log("mergequeue check-push: nothing being pushed (already up to date) — skipping checks.");
+                process.exit(0);
+            }
+            if (process.env.MERGEQUEUE_EMERGENCY_PUSH === "1") {
+                console.log("\n🚨 MERGEQUEUE_EMERGENCY_PUSH is set — bypassing the landing queue.\n");
+            }
+            const result = checkPush(refUpdates, cfg, process.env);
+            if (!result.ok) {
+                console.error(result.message);
+                process.exit(1);
+            }
+            process.exit(runCheckCommand(cfg, root));
+            return;
+        }
+        case "--version":
+        case "-v": {
+            const { join, dirname } = await import("node:path");
+            const { fileURLToPath } = await import("node:url");
+            const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            console.log(pkg.version);
+            return;
+        }
+        default:
+            console.log(`mergequeue — keep parallel coding agents in their lane.
+
+Usage:
+  mergequeue init                  write a starter mergequeue.config.mjs
+  mergequeue land                  rebase + push this lane onto the integration branch (queued)
+  mergequeue sync                  fast-forward the MAIN checkout to its upstream
+  mergequeue promote               ship the integration branch to production (human-only — never script this)
+  mergequeue preview [--restore]   swap the MAIN checkout to this lane's working tree, or restore it
+  mergequeue build-lock -- <cmd>   run <cmd>, serialized across every lane
+  mergequeue port                  print this lane's dev-server port
+  mergequeue hook worktree-create  (Claude Code WorktreeCreate hook — not for direct use)
+  mergequeue check-push            (used by the pre-push hook — not for direct use)
+`);
+            process.exit(command ? 1 : 0);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/build-lock.d.ts

@@ -0,0 +1 @@
+export declare function buildLock(commandParts: string[]): Promise<void>;

package/dist/build-lock.js

@@ -0,0 +1,70 @@
+/**
+ * build-lock.ts — wrap any command so only ONE runs at a time, machine-wide,
+ * across every lane of this repo.
+ *
+ * A full production build is CPU/RAM-heavy. Run one per lane and four
+ * parallel agents will thrash a laptop into a death spiral. This doesn't
+ * make builds faster — it makes them take turns, via the same cross-worktree
+ * FIFO lock everything else in this repo shares (queue-lock.ts).
+ *
+ *   Usage:  claude-code-local-merge build-lock -- <shell command>
+ *
+ * Crash-safe with no timeouts: a lock whose holder PID has died is reclaimed
+ * deterministically, so a killed build can't wedge the queue for anyone
+ * else. That's also why the child is spawned detached — SIGKILLing this
+ * process still leaves an orphaned build running unless something can reach
+ * its whole process group, so a caller that wants to hard-kill a build (a CI
+ * runner enforcing a deadline, say) needs a group to signal, not just a PID.
+ */
+import { spawn } from "node:child_process";
+import { createQueueLock } from "./lib/queue-lock.js";
+export async function buildLock(commandParts) {
+    const command = commandParts.join(" ").trim();
+    if (!command) {
+        console.error("claude-code-local-merge build-lock: no command given. Usage: claude-code-local-merge build-lock -- <command>");
+        process.exit(2);
+    }
+    const lock = createQueueLock("build");
+    await lock.acquire({
+        label: command,
+        onWait: ({ ahead, holder }) => {
+            if (ahead > 0) {
+                console.log(`\x1b[2m[build-queue] ${lock.lane}: waiting — ${ahead} build${ahead === 1 ? "" : "s"} ahead…\x1b[0m`);
+            }
+            else if (holder) {
+                console.log(`\x1b[2m[build-queue] ${lock.lane}: next up — waiting for the running build to finish…\x1b[0m`);
+            }
+        },
+    });
+    console.log(`\x1b[2m[build-queue] ${lock.lane}: lock acquired — building…\x1b[0m`);
+    const child = spawn(command, { shell: true, stdio: "inherit", detached: true });
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.on(sig, () => {
+            try {
+                // detached:true made the child its own process-group leader, so a
+                // negative pid signals the whole tree, not just the shell wrapper.
+                if (child.pid)
+                    process.kill(-child.pid, sig);
+            }
+            catch {
+                /* noop */
+            }
+            lock.release();
+            process.exit(130);
+        });
+    }
+    child.on("exit", (code, signal) => {
+        lock.release();
+        if (signal) {
+            process.kill(process.pid, signal);
+        }
+        else {
+            process.exit(code ?? 1);
+        }
+    });
+    child.on("error", (err) => {
+        console.error(`claude-code-local-merge build-lock: failed to start command: ${err.message}`);
+        lock.release();
+        process.exit(1);
+    });
+}

package/dist/hooks/worktree-create.d.ts

@@ -0,0 +1,15 @@
+import { type ClaudeCodeLocalMergeConfig } from "../lib/config.js";
+/**
+ * Claim the lowest free lane, create its worktree, and symlink the
+ * configured git-ignored paths into it. Throws with a human-readable
+ * message on failure — the caller turns that into the hook's stderr +
+ * non-zero exit.
+ */
+export declare function createLane(mainTop: string, cfg: ClaudeCodeLocalMergeConfig): {
+    wt: string;
+    branch: string;
+    lane: number;
+};
+export declare function isEphemeralNpxCopy(selfPath: string): boolean;
+export declare function expectsLocalInstall(mainTop: string): boolean;
+export declare function runWorktreeCreateHook(): Promise<void>;

package/dist/hooks/worktree-create.js

@@ -0,0 +1,192 @@
+/**
+ * The Claude Code WorktreeCreate hook. Claude Code already isolates agents
+ * in worktrees natively (`--worktree`, `isolation: "worktree"`) — this hook
+ * doesn't compete with that, it plugs into it. A WorktreeCreate hook
+ * "replaces default git behavior entirely" (Claude Code's own docs), so
+ * this script is responsible for actually creating the worktree; what it
+ * adds on top of the native flow is Claude Code Local Merge's numbered-lane convention
+ * and a `node_modules` SYMLINK instead of a copy — Claude Code's own
+ * `.worktreeinclude` mechanism copies gitignored files in, which is fine
+ * for a `.env` file and genuinely expensive for `node_modules`.
+ *
+ * Per Claude Code's hook contract: print the new worktree's absolute path
+ * on stdout and exit 0, or print an error to stderr and exit non-zero to
+ * abort creation (WorktreeCreate is the one hook event that can block).
+ *
+ * There's no long-lived process behind this the way there was behind the
+ * old standalone launcher — the hook runs once and exits. So lane claiming
+ * can't be PID-liveness-based here; there's no PID to track. Instead the
+ * claim IS the worktree: a lane is free iff `<repo><worktreeSuffix><n>`
+ * doesn't exist on disk, and `git worktree add` failing on an
+ * already-claimed path is the same atomicity guarantee a `mkdir` race gave
+ * the old launcher, just delegated to git itself. When Claude Code (or you,
+ * or its cleanup sweep) removes a worktree, that lane number is free again
+ * automatically — nothing to release by hand.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, symlinkSync } from "node:fs";
+import { dirname, join, basename, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig, hasConfig, DEFAULTS } from "../lib/config.js";
+import { resolveMainCheckout } from "../lib/main-checkout.js";
+// A lane-claim loop with no upper bound is exactly one path-resolution bug
+// away from spinning the CPU forever instead of failing loud — which is
+// precisely what happened here: an earlier, separate implementation of what
+// is now resolveMainCheckout used path.join instead of path.resolve, so
+// invoking this hook from INSIDE an already-created linked worktree (where
+// git reports an ABSOLUTE git-common-dir, not the relative ".git" a fresh
+// checkout reports) produced a nonsense path that never matched an existing
+// lane and never let `git worktree add` succeed either — an infinite loop,
+// confirmed burning 80%+ CPU indefinitely in production use. Fixing the path
+// bug alone doesn't rule out some other future bug in this class; capping
+// the loop means any of them fails loud instead of hanging.
+const MAX_LANE_ATTEMPTS = 1000;
+// Trying a lane number that turns out to already be claimed (the expected,
+// routine race with another concurrent hook invocation) is not an error
+// worth showing anyone — git's own "fatal: cannot lock ref" on that attempt
+// would otherwise leak to the terminal even though the hook recovers and
+// succeeds. Force stdout/stderr into pipes explicitly rather than trusting
+// the ambient default, so a probing attempt is always silent until we
+// decide it's actually fatal.
+function tryGit(args, cwd) {
+    try {
+        return {
+            ok: true,
+            out: execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(),
+        };
+    }
+    catch (e) {
+        const err = e;
+        return { ok: false, out: `${err.stdout ?? ""}${err.stderr ?? ""}` };
+    }
+}
+/**
+ * Claim the lowest free lane, create its worktree, and symlink the
+ * configured git-ignored paths into it. Throws with a human-readable
+ * message on failure — the caller turns that into the hook's stderr +
+ * non-zero exit.
+ */
+export function createLane(mainTop, cfg) {
+    // Clean up administrative entries for worktrees whose directories are
+    // already gone (e.g. someone `rm -rf`'d one instead of `git worktree
+    // remove`) so reusing that lane number's branch name doesn't fail with
+    // "already checked out elsewhere."
+    tryGit(["worktree", "prune"], mainTop);
+    const repoName = basename(mainTop);
+    let lane = 0;
+    for (;;) {
+        lane += 1;
+        if (lane > MAX_LANE_ATTEMPTS) {
+            throw new Error(`could not claim a lane after ${MAX_LANE_ATTEMPTS} attempts — is mainTop ('${mainTop}') actually the repo root?`);
+        }
+        const wt = join(dirname(mainTop), `${repoName}${cfg.worktreeSuffix}${lane}`);
+        if (existsSync(wt))
+            continue; // still claimed — try the next lane
+        const branch = `${cfg.branchPrefix}${lane}`;
+        const branchExists = tryGit(["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], mainTop).ok;
+        // Base every new lane on the main checkout's own current HEAD — never on
+        // origin/integrationBranch. The main checkout is kept fast-forwarded by
+        // `sync` precisely so its local HEAD IS the trusted, up-to-date view;
+        // reading origin directly instead can be *behind* local HEAD (a commit
+        // made here but not yet pushed) and silently drop it from every new
+        // lane. That's not a hypothetical: it breaks the literal Quickstart —
+        // `init` writes claude-code-local-merge.config.mjs/CLAUDE.md/.claude locally, and the
+        // very first lane created before that commit is pushed anywhere would
+        // otherwise come up with none of it.
+        let add;
+        if (branchExists) {
+            add = tryGit(["worktree", "add", wt, branch], mainTop);
+        }
+        else {
+            add = tryGit(["worktree", "add", wt, "-b", branch], mainTop);
+        }
+        if (!add.ok) {
+            // Someone else claimed this exact lane between our existsSync check
+            // and `git worktree add` — the same race a `mkdir` guards against.
+            // Try the next one.
+            continue;
+        }
+        for (const rel of cfg.symlinks) {
+            const src = join(mainTop, rel);
+            const dest = join(wt, rel);
+            if (!existsSync(src) || existsSync(dest))
+                continue;
+            try {
+                mkdirSync(dirname(dest), { recursive: true });
+                symlinkSync(src, dest);
+            }
+            catch {
+                /* best-effort — a missing symlink degrades to "run npm install," not a hard failure */
+            }
+        }
+        return { wt, branch, lane };
+    }
+}
+// `.claude/settings.json` invokes this hook via `npx claude-code-local-merge hook
+// worktree-create` rather than a project script, precisely because a raw
+// hook command has no `node_modules/.bin` on its PATH the way `npm run`
+// does — npx's own directory-walking local resolution is what makes that
+// work at all. The problem: npx treats a package it can't resolve locally as
+// license to silently fetch an ephemeral, unpinned copy from the registry
+// and run *that* instead of failing — which is exactly what happens when the
+// host project's own install of claude-code-local-merge is missing or mid-upgrade (npm
+// removes the old version's files before extracting the new one; anything
+// that interrupts that leaves precisely this state). That fallback ran
+// silently for long enough in production to block two lanes from landing
+// before anyone noticed node_modules was broken. Refuse to proceed if this
+// module is executing from npx's ephemeral cache instead of the project's
+// own installed copy, so a broken install fails loud immediately instead of
+// limping along on a stand-in version nobody asked for.
+export function isEphemeralNpxCopy(selfPath) {
+    return selfPath.includes(`${sep}_npx${sep}`);
+}
+// The guard above only makes sense for a host project that's an npm project
+// with claude-code-local-merge as a real dependency — hola, say. A non-Node host repo
+// (a Haskell/Lua/Rust/whatever project with no package.json at all) has
+// nowhere to install claude-code-local-merge INTO; npx's ephemeral cache is the only way
+// it can ever run claude-code-local-merge commands, not a fallback masking a broken
+// local install. Only expect a local install — and therefore only treat
+// ephemeral execution as suspicious — when the host's own package.json
+// actually lists claude-code-local-merge as a dependency. No package.json, or one that
+// doesn't mention claude-code-local-merge: ephemeral execution is completely normal.
+export function expectsLocalInstall(mainTop) {
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(join(mainTop, "package.json"), "utf8"));
+    }
+    catch {
+        return false; // no package.json, or unreadable/invalid — nothing "expected" to be there
+    }
+    return Boolean(pkg.dependencies?.["claude-code-local-merge"] || pkg.devDependencies?.["claude-code-local-merge"]);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function runWorktreeCreateHook() {
+    let input = {};
+    try {
+        input = JSON.parse(await readStdin());
+    }
+    catch {
+        /* no/invalid stdin — fall back to process.cwd() below */
+    }
+    const fromCwd = input.cwd ?? process.cwd();
+    try {
+        const mainTop = resolveMainCheckout(fromCwd);
+        if (expectsLocalInstall(mainTop) && isEphemeralNpxCopy(fileURLToPath(import.meta.url))) {
+            throw new Error("running from npx's ephemeral cache, not this project's own installed dependency — " +
+                "node_modules is missing or broken. Run `npm install` in the main checkout and try again.");
+        }
+        const cfg = hasConfig(mainTop) ? await loadConfig(mainTop) : { ...DEFAULTS };
+        const { wt } = createLane(mainTop, cfg);
+        process.stdout.write(wt + "\n");
+        process.exit(0);
+    }
+    catch (err) {
+        process.stderr.write(`claude-code-local-merge worktree-create hook failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+}

package/dist/land.d.ts

@@ -0,0 +1 @@
+export declare function land(): Promise<void>;