claude-code-merge-queue 0.1.14

package/dist/land.js

@@ -0,0 +1,144 @@
+/**
+ * land.ts — the ONLY sanctioned way for a lane to land onto the integration
+ * branch.
+ *
+ * Left to behavioral convention alone ("only one lane rebases-and-pushes at
+ * a time"), several lanes going green around the same time all rebase and
+ * push at once: pushes race, the loser's checks run against an already-stale
+ * remote, and when something breaks everyone ends up mid-push fixing the
+ * same failure. This makes "land" a single cross-worktree FIFO queue
+ * (queue-lock.ts — the same crash-safe mechanics build-lock uses) so only
+ * one lane is ever fetching, rebasing, pushing, and checking at a time.
+ *
+ * A failed attempt releases the lock rather than holding it hostage — the
+ * next lane in line lands next while the failed lane fixes and re-runs
+ * `claude-code-local-merge land` (re-entering the back of the queue). That keeps one
+ * broken lane from blocking every OTHER lane's unrelated, ready-to-land
+ * work, while still guaranteeing no two lanes are ever mid-push at once.
+ *
+ * This is only half the guarantee, though — a convention that says "always
+ * run `claude-code-local-merge land`" is exactly the kind of rule a confused agent (or a
+ * human under time pressure) eventually skips by hand-rolling `git push`.
+ * The other half lives in hooks/pre-push: it hard-rejects a direct push to
+ * the integration branch that didn't set CLAUDE_CODE_LOCAL_MERGE_LANDING=1, which this
+ * script sets right before its own push and nothing else legitimately would.
+ * Wire that hook up (see the README) and the queue isn't a convention
+ * anymore — it's the only door.
+ *
+ *   Usage:  claude-code-local-merge land   (run from a lane worktree, on its own branch)
+ */
+import { execSync, spawnSync } from "node:child_process";
+import { createQueueLock } from "./lib/queue-lock.js";
+import { hasConfig, loadConfig } from "./lib/config.js";
+import { resolveMainCheckout } from "./lib/main-checkout.js";
+import { pruneLandedLanes } from "./lib/prune-lanes.js";
+import { sync } from "./sync.js";
+const DIM = "\x1b[2m", RESET = "\x1b[0m", RED = "\x1b[31m", GREEN = "\x1b[32m";
+export async function land() {
+    if (!hasConfig()) {
+        console.error("claude-code-local-merge land: no claude-code-local-merge.config found at the repo root. Run `claude-code-local-merge init` first.");
+        process.exit(1);
+    }
+    const cfg = await loadConfig();
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8" }).trim();
+    if (branch === cfg.integrationBranch || cfg.protectedBranches.includes(branch) || branch === "HEAD") {
+        console.error(`claude-code-local-merge land: refusing to run from '${branch}' — land is for lane branches only.`);
+        process.exit(1);
+    }
+    // A rebase refuses to run at all with a dirty tree. Build-tool-regenerated
+    // noise shouldn't block landing — discard ONLY the configured
+    // regenerableFiles, exactly like sync does for the fast-forward on the
+    // other end. Any other dirty file is real work-in-progress: leave it alone
+    // and let the rebase fail loud.
+    //
+    // Checked here AND again right before the rebase itself (not just once):
+    // a build tool can regenerate one of these files at any point, including
+    // during the (possibly long) wait for the landing queue lock below. A
+    // single check up front leaves that whole wait as a window where the
+    // exact same harmless noise reappears and gets misreported as a real
+    // rebase conflict instead of silently discarded like it should be.
+    const regenerable = new Set(cfg.regenerableFiles);
+    function discardRegenerableDirt() {
+        const status = execSync("git status --porcelain", { encoding: "utf8" });
+        const dirty = status
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => line.slice(3).trim());
+        const blocking = dirty.filter((f) => !regenerable.has(f));
+        if (dirty.length > 0 && blocking.length === 0) {
+            execSync(`git checkout -- ${dirty.map((f) => `"${f}"`).join(" ")}`);
+        }
+    }
+    discardRegenerableDirt();
+    const lock = createQueueLock("land");
+    await lock.acquire({
+        label: branch,
+        onWait: ({ ahead, holder }) => {
+            if (ahead > 0) {
+                console.log(`${DIM}[land-queue] ${branch}: waiting — ${ahead} landing${ahead === 1 ? "" : "s"} ahead…${RESET}`);
+            }
+            else if (holder) {
+                console.log(`${DIM}[land-queue] ${branch}: next up — waiting for '${holder.label ?? holder.lane}' to finish landing…${RESET}`);
+            }
+        },
+    });
+    let exitCode = 0;
+    try {
+        console.log(`${DIM}[land-queue] ${branch}: lock acquired — landing…${RESET}`);
+        discardRegenerableDirt(); // re-check right before the rebase — see comment above
+        console.log(`${DIM}fetching origin/${cfg.integrationBranch}…${RESET}`);
+        execSync(`git fetch origin ${cfg.integrationBranch} --quiet`, { stdio: "inherit" });
+        console.log(`${DIM}rebasing onto origin/${cfg.integrationBranch}…${RESET}`);
+        const rebase = spawnSync("git", ["rebase", `origin/${cfg.integrationBranch}`], { stdio: "inherit" });
+        if (rebase.status !== 0) {
+            spawnSync("git", ["rebase", "--abort"], { stdio: "ignore" });
+            console.error(`\n${RED}land: rebase onto origin/${cfg.integrationBranch} conflicted — aborted, working tree left clean.${RESET}`);
+            console.error(`Resolve it yourself (git fetch origin ${cfg.integrationBranch} && git rebase origin/${cfg.integrationBranch}), then re-run 'claude-code-local-merge land'.`);
+            exitCode = 1;
+        }
+        else {
+            console.log(`${DIM}pushing to ${cfg.integrationBranch} (this is where your CI/checks hook runs)…${RESET}`);
+            const push = spawnSync("git", ["push", "origin", `HEAD:${cfg.integrationBranch}`], {
+                stdio: "inherit",
+                env: { ...process.env, CLAUDE_CODE_LOCAL_MERGE_LANDING: "1" },
+            });
+            if (push.status !== 0) {
+                console.error(`\n${RED}land: push to ${cfg.integrationBranch} failed — see output above.${RESET}`);
+                console.error(`Fix the failure, then re-run 'claude-code-local-merge land'.`);
+                exitCode = 1;
+            }
+            else {
+                console.log(`${GREEN}✓ ${branch} landed on ${cfg.integrationBranch}.${RESET}`);
+                // Landing isn't "done" until the checkout that actually serves your
+                // dev server can see it — call sync in-process rather than shelling
+                // back out to the CLI, so this doesn't depend on `claude-code-local-merge` being
+                // resolvable on PATH. Pass this lane's own already-loaded cfg through
+                // rather than letting sync() reload from MAIN — MAIN hasn't been
+                // fast-forwarded yet at this exact moment (that's what sync is about
+                // to do), so if this push just introduced or changed
+                // claude-code-local-merge.config.mjs itself, a fresh MAIN-side load would silently
+                // fall back to DEFAULTS instead of the real config.
+                exitCode = await sync(cfg);
+                // Housekeeping, never a reason to fail this landing: sweep sibling
+                // lanes whose OWN branch already made it upstream (nothing created
+                // ever tears a worktree down on the way out) so they don't
+                // accumulate on disk forever waiting for someone to remember.
+                try {
+                    const mainTop = resolveMainCheckout(process.cwd());
+                    const pruned = pruneLandedLanes(mainTop, cfg, process.cwd());
+                    if (pruned.length > 0) {
+                        const names = pruned.map((p) => p.split("/").pop()).join(", ");
+                        console.log(`${DIM}pruned ${pruned.length} already-landed lane${pruned.length === 1 ? "" : "s"}: ${names}${RESET}`);
+                    }
+                }
+                catch {
+                    /* best-effort — never block a successful landing over cleanup */
+                }
+            }
+        }
+    }
+    finally {
+        lock.release();
+    }
+    process.exit(exitCode);
+}

package/dist/lib/check-command.d.ts

@@ -0,0 +1,29 @@
+import type { ClaudeCodeLocalMergeConfig } from "./config.js";
+/**
+ * Which package manager actually installed this project — detected from its
+ * lockfile, since that's the one signal that's always there regardless of
+ * what's on PATH. Defaulting straight to npm regardless of the real answer
+ * isn't a hypothetical: a pnpm workspace's scripts can rely on pnpm-specific
+ * behavior (workspace: protocol deps, `--filter`), and `npm run` may not
+ * even be installed on a pnpm/yarn/bun-only machine.
+ */
+export declare function detectPackageManager(root: string): "npm" | "pnpm" | "yarn" | "bun";
+/** Look at package.json's own scripts for something to run — best-effort, never throws. */
+export declare function detectCheckCommand(root: string): string | null;
+/**
+ * Run the configured check command. Returns the exit code to propagate.
+ *
+ * A null checkCommand is only ever silent if checksRequired was explicitly
+ * turned off — the default is to FAIL the push, because a merge queue that
+ * lets unverified code through by default isn't one, it's a false sense of
+ * safety.
+ *
+ * Always runs from `root`, not whatever the caller's cwd happens to be. In
+ * the real git-push flow that's moot — git always resets cwd to the repo
+ * root before running a hook — but `check-push` is also a directly
+ * user-runnable command, and silently depending on git's hook behavior for
+ * correctness (instead of just being correct on its own) is exactly the
+ * kind of implicit assumption that bites the first time someone runs it by
+ * hand from a subdirectory.
+ */
+export declare function runCheckCommand(cfg: Pick<ClaudeCodeLocalMergeConfig, "checkCommand" | "checksRequired">, root: string): number;

package/dist/lib/check-command.js

@@ -0,0 +1,83 @@
+/**
+ * The part of the merge queue that actually earns the name: running your
+ * lint/typecheck/test/build before a landing is allowed through. Without
+ * this, "merge queue" is just "push queue" — serialized, but blind.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+// Priority order: prefer a script that already bundles multiple checks
+// (a repo's own "check" or CI script) over a narrower "test" script, but
+// take whatever exists rather than assume one specific name.
+const CANDIDATE_SCRIPTS = ["check:push", "check", "ci", "test"];
+/**
+ * Which package manager actually installed this project — detected from its
+ * lockfile, since that's the one signal that's always there regardless of
+ * what's on PATH. Defaulting straight to npm regardless of the real answer
+ * isn't a hypothetical: a pnpm workspace's scripts can rely on pnpm-specific
+ * behavior (workspace: protocol deps, `--filter`), and `npm run` may not
+ * even be installed on a pnpm/yarn/bun-only machine.
+ */
+export function detectPackageManager(root) {
+    if (existsSync(join(root, "pnpm-lock.yaml")) || existsSync(join(root, "pnpm-workspace.yaml")))
+        return "pnpm";
+    if (existsSync(join(root, "yarn.lock")))
+        return "yarn";
+    if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock")))
+        return "bun";
+    return "npm";
+}
+/** Look at package.json's own scripts for something to run — best-effort, never throws. */
+export function detectCheckCommand(root) {
+    const pkgPath = join(root, "package.json");
+    if (!existsSync(pkgPath))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        const found = CANDIDATE_SCRIPTS.find((name) => pkg.scripts?.[name]);
+        return found ? `${detectPackageManager(root)} run ${found}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the configured check command. Returns the exit code to propagate.
+ *
+ * A null checkCommand is only ever silent if checksRequired was explicitly
+ * turned off — the default is to FAIL the push, because a merge queue that
+ * lets unverified code through by default isn't one, it's a false sense of
+ * safety.
+ *
+ * Always runs from `root`, not whatever the caller's cwd happens to be. In
+ * the real git-push flow that's moot — git always resets cwd to the repo
+ * root before running a hook — but `check-push` is also a directly
+ * user-runnable command, and silently depending on git's hook behavior for
+ * correctness (instead of just being correct on its own) is exactly the
+ * kind of implicit assumption that bites the first time someone runs it by
+ * hand from a subdirectory.
+ */
+export function runCheckCommand(cfg, root) {
+    if (!cfg.checkCommand) {
+        if (cfg.checksRequired) {
+            console.error([
+                "",
+                "✋ No checkCommand configured, and checksRequired is true (the default).",
+                "   This push would land with NOTHING verifying it — no lint, no test, no build.",
+                "   Set checkCommand in claude-code-local-merge.config.mjs, e.g. \"npm run check\".",
+                "   Or, if you really have nothing to check yet, set checksRequired: false —",
+                "   deliberately, so it's a visible, committed choice, not a silent gap.",
+                "",
+            ].join("\n"));
+            return 1;
+        }
+        console.log("claude-code-local-merge check-push: no checkCommand configured (checksRequired: false — running with no checks, on purpose).");
+        return 0;
+    }
+    console.log(`claude-code-local-merge check-push: running "${cfg.checkCommand}"…`);
+    const result = spawnSync(cfg.checkCommand, { shell: true, stdio: "inherit", cwd: root });
+    if (result.status !== 0) {
+        console.error(`\n✋ checkCommand failed (exit ${result.status ?? 1}) — landing blocked.`);
+    }
+    return result.status ?? 1;
+}

package/dist/lib/check-push.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The enforcement half of the landing queue. `land.ts` (and `promote.ts`)
+ * are *conventions* — "always land through here" — and conventions are
+ * exactly the kind of rule a confused agent, or a human moving fast,
+ * eventually skips by hand-rolling `git push`. This is the mechanism that
+ * makes the convention unnecessary to trust: it reads the same ref-update
+ * lines git's pre-push hook always gets on stdin, and rejects a direct push
+ * to the integration branch or any protected/production branch by default.
+ *
+ * `land.ts` sets CLAUDE_CODE_LOCAL_MERGE_LANDING=1 right before its own push — that's
+ * the only thing that legitimately unblocks the integration branch on the
+ * normal path. `promote.ts` pushes to productionBranch with `--no-verify`,
+ * which skips this hook entirely (same as git always does for --no-verify).
+ *
+ * Every branch here (including the integration branch, which used to have
+ * NO override at all) also has a genuine emergency hatch: set
+ * CLAUDE_CODE_LOCAL_MERGE_EMERGENCY_PUSH=1 and push. One env var, no prompts, no second
+ * factor to remember — the same trust model as CLAUDE_CODE_LOCAL_MERGE_LANDING=1 above
+ * it. This is a convention, not a hard guarantee: it stops mistakes and
+ * stray pushes, not a truly adversarial agent that sets it itself. Worth
+ * knowing, not worth building 18 hoops to (marginally) defend against.
+ */
+import type { ClaudeCodeLocalMergeConfig } from "./config.js";
+export interface RefUpdate {
+    localRef: string;
+    localSha: string;
+    remoteRef: string;
+    remoteSha: string;
+}
+export interface CheckResult {
+    ok: boolean;
+    message?: string;
+}
+export declare function parseRefUpdates(stdin: string): RefUpdate[];
+export declare function checkPush(refUpdates: RefUpdate[], cfg: Pick<ClaudeCodeLocalMergeConfig, "integrationBranch" | "productionBranch" | "protectedBranches">, env: NodeJS.ProcessEnv): CheckResult;

package/dist/lib/check-push.js

@@ -0,0 +1,46 @@
+export function parseRefUpdates(stdin) {
+    return stdin
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((line) => {
+        const [localRef, localSha, remoteRef, remoteSha] = line.split(/\s+/);
+        return { localRef: localRef ?? "", localSha: localSha ?? "", remoteRef: remoteRef ?? "", remoteSha: remoteSha ?? "" };
+    });
+}
+function emergencyConfirmed(env) {
+    return env.CLAUDE_CODE_LOCAL_MERGE_EMERGENCY_PUSH === "1";
+}
+export function checkPush(refUpdates, cfg, env) {
+    const integrationRef = `refs/heads/${cfg.integrationBranch}`;
+    const protectedBranches = cfg.productionBranch ? [...cfg.protectedBranches, cfg.productionBranch] : cfg.protectedBranches;
+    const protectedRefs = new Set(protectedBranches.map((b) => `refs/heads/${b}`));
+    for (const { remoteRef } of refUpdates) {
+        const branch = remoteRef.replace("refs/heads/", "");
+        if (protectedRefs.has(remoteRef) && !emergencyConfirmed(env)) {
+            return {
+                ok: false,
+                message: [
+                    "",
+                    `✋ Direct pushes to '${branch}' are blocked.`,
+                    `   This is a protected branch — promote it deliberately, not with a stray push.`,
+                    `   Emergency override:  CLAUDE_CODE_LOCAL_MERGE_EMERGENCY_PUSH=1 git push …`,
+                    "",
+                ].join("\n"),
+            };
+        }
+        if (remoteRef === integrationRef && env.CLAUDE_CODE_LOCAL_MERGE_LANDING !== "1" && !emergencyConfirmed(env)) {
+            return {
+                ok: false,
+                message: [
+                    "",
+                    `✋ Direct pushes to '${cfg.integrationBranch}' are blocked — landing goes through the queue.`,
+                    `   Land your work:  claude-code-local-merge land`,
+                    `   Genuine emergency:  CLAUDE_CODE_LOCAL_MERGE_EMERGENCY_PUSH=1 git push …`,
+                    "",
+                ].join("\n"),
+            };
+        }
+    }
+    return { ok: true };
+}

package/dist/lib/claude-md-snippet.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The actual "baked into Claude" mechanism — not a hook, not magic. Claude
+ * Code reads CLAUDE.md automatically at the start of every session and
+ * follows it as standing instructions. So instead of expecting a human to
+ * remember to type `claude-code-local-merge land` after every change, this snippet tells
+ * the agent itself to do it — the same way a real production setup that
+ * runs several parallel Claude Code agents keeps its own human out of the
+ * loop for anything except the final promotion to production.
+ *
+ * `claude-code-local-merge init` writes this into CLAUDE.md (creating it if missing,
+ * appending — once, idempotently, via MARKER — if one already exists) so
+ * every session in the repo picks it up with zero extra setup per agent.
+ */
+import type { ClaudeCodeLocalMergeConfig } from "./config.js";
+export declare const MARKER = "<!-- claude-code-local-merge:workflow -->";
+export declare function claudeMdSnippet(cfg: ClaudeCodeLocalMergeConfig): string;

package/dist/lib/claude-md-snippet.js

@@ -0,0 +1,18 @@
+export const MARKER = "<!-- claude-code-local-merge:workflow -->";
+export function claudeMdSnippet(cfg) {
+    const promoteBlock = cfg.productionBranch
+        ? `- **\`${cfg.productionBranch}\` is production, and it is not your call.** Only a human runs \`claude-code-local-merge promote\` (${cfg.integrationBranch} → ${cfg.productionBranch}), on their own schedule. Never run it yourself, never suggest running it as part of "finishing" a task — landing on \`${cfg.integrationBranch}\` is the finish line for you.`
+        : `- There's no separate production branch configured — \`${cfg.integrationBranch}\` already is it. Landing is the whole deal.`;
+    return `${MARKER}
+## Claude Code Local Merge workflow
+
+This repo uses [Claude Code Local Merge](https://github.com/funador/claude-code-local-merge) to run parallel Claude Code agents without them racing each other. It's not a suggestion — follow it by default, every session, without being asked:
+
+- **You're probably already in a lane.** If you were started with \`claude --worktree <name>\`, Claude Code Local Merge's \`WorktreeCreate\` hook already isolated you into your own git worktree and branch. Just work.
+- **Land the moment your change is green — don't ask first.** Run \`claude-code-local-merge land\` yourself once tests/build/lint pass. This is pre-authorized, standard workflow, not a decision that needs sign-off. It rebases onto \`${cfg.integrationBranch}\`, pushes through the FIFO landing queue, and syncs the dev checkout — that whole sequence is "done," not "pushed to a branch and waiting."
+- **Never push \`${cfg.integrationBranch}\` directly.** \`git push origin HEAD:${cfg.integrationBranch}\` is rejected by the pre-push hook anyway — always go through \`claude-code-local-merge land\`.
+- **A failed \`claude-code-local-merge land\` is not a stopping point — landed is the only "done."** A rebase conflict aborts safely and leaves your working tree clean; that's expected, not an error to report and hand back. Resolve the conflicting diff yourself the same way you'd fix any other bug, \`git add\` the result, \`git rebase --continue\`, then re-run \`claude-code-local-merge land\` — repeat until it actually lands. Don't say a change is finished, complete, or ready while it's still sitting unlanded in your lane; \`checkCommand\` still gates the real push regardless of how many attempts it took, so a wrong resolution gets caught there, not by a human reading it first.
+- **Use \`claude-code-local-merge build-lock -- <cmd>\` for anything heavy** (a full build, a slow test suite) so parallel lanes take turns instead of thrashing the machine together.
+${promoteBlock}
+`;
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,92 @@
+export interface ClaudeCodeLocalMergeConfig {
+    /** Lane branches are named "<branchPrefix><n>" — lane/1, lane/2, ... */
+    branchPrefix: string;
+    /** Sibling worktree dirs are named "<repo><worktreeSuffix><n>" — ../myapp-lane-1. */
+    worktreeSuffix: string;
+    /** First lane's dev-server port. Lane n gets portBase + n. */
+    portBase: number;
+    /** The shared branch `claude-code-local-merge land` rebases onto and pushes to. */
+    integrationBranch: string;
+    /**
+     * The production branch, if you run a two-stage model (agents land on
+     * `integrationBranch`; a human promotes that to `productionBranch` on
+     * their own schedule via `claude-code-local-merge promote`). `null` means
+     * `integrationBranch` IS production — no separate promotion step, and
+     * `claude-code-local-merge promote` is a no-op. When set, this branch is automatically
+     * protected by the pre-push hook — you don't need to also list it in
+     * `protectedBranches`.
+     */
+    productionBranch: string | null;
+    /**
+     * Extra branches the pre-push hook refuses a *direct* push to, beyond
+     * integrationBranch (always protected) and productionBranch (protected
+     * automatically when set). Most repos running the standard two-stage
+     * model don't need this at all.
+     */
+    protectedBranches: string[];
+    /**
+     * Files a build tool regenerates on its own (next-env.d.ts, a rewritten
+     * tsconfig "include" array, ...) that should never block a rebase or a
+     * fast-forward. Empty by default — you'll meet your first one the hard
+     * way, and then you add it here once, for good.
+     */
+    regenerableFiles: string[];
+    /**
+     * Git-ignored paths copied by reference (symlinked) into every new lane
+     * so it never needs a fresh install or a copy of your secrets.
+     */
+    symlinks: string[];
+    /**
+     * Build-output directories `preview` never copies onto the main checkout,
+     * on top of the fixed, always-excluded set (.git, node_modules, .env,
+     * .env.local). `preview` itself doesn't know or care what framework
+     * you're running — it just rsyncs source files onto a checkout your dev
+     * server is watching. The default list covers the common cases; add your
+     * own (".output" for Nuxt, ".svelte-kit" for SvelteKit, ...) rather than
+     * assuming this tool knows your build tool.
+     */
+    buildOutputDirs: string[];
+    /**
+     * The command `claude-code-local-merge check-push` runs (in addition to the branch
+     * protections) before a landing is allowed through — your lint/typecheck/
+     * test/build, whatever "green" means for this repo. `null` means nothing
+     * runs. That's a real, dangerous state for a tool whose whole pitch is
+     * "tested before merge," so it's only silent if `checksRequired` is
+     * explicitly set to `false` too — otherwise a null checkCommand FAILS the
+     * push rather than landing something nobody verified.
+     */
+    checkCommand: string | null;
+    /**
+     * When true (the default) and `checkCommand` is null, `check-push` fails
+     * the push instead of landing unverified code. Set to `false` yourself to
+     * deliberately run with no checks — a real repo state (nothing to test
+     * yet), but one that should be a visible, committed, code-reviewable
+     * choice, not a silent default.
+     */
+    checksRequired: boolean;
+}
+export declare const DEFAULTS: ClaudeCodeLocalMergeConfig;
+/**
+ * Fail loud on a malformed config instead of silently misbehaving three
+ * commands later. Returns a list of human-readable problems — empty means
+ * valid.
+ */
+export declare function validateConfig(cfg: ClaudeCodeLocalMergeConfig): string[];
+/**
+ * The repo's actual current branch, so `init` doesn't blindly assume "main"
+ * — plenty of real repos still default to "master" (or something else
+ * entirely), and a generated config pointing at a branch that doesn't exist
+ * is exactly the kind of out-of-the-box friction this tool exists to avoid.
+ * Returns null (letting the caller fall back to DEFAULTS) if there's no
+ * commit yet or HEAD is detached.
+ */
+export declare function detectCurrentBranch(cwd?: string): string | null;
+export declare function findRepoRoot(cwd?: string): string | null;
+export declare function configPath(cwd?: string): string | null;
+export declare function hasConfig(cwd?: string): boolean;
+/**
+ * Load claude-code-local-merge.config.(m)js from the current repo, merged over DEFAULTS.
+ * Throws with every problem listed if the merged config is invalid — a
+ * config that's silently wrong is worse than a command that refuses to run.
+ */
+export declare function loadConfig(cwd?: string): Promise<ClaudeCodeLocalMergeConfig>;

package/dist/lib/config.js

@@ -0,0 +1,137 @@
+/**
+ * claude-code-local-merge.config.ts (or .js — plain JS is fine too) is the only thing
+ * that changes between repos. Every command in here reads its knobs from
+ * here instead of hardcoding a branch name, a repo name, or a command —
+ * that's the difference between "a tool we wrote for one repo" and "a tool
+ * anyone can point at theirs."
+ *
+ * `claude-code-local-merge init` writes a starter config into the repo you run it from.
+ * Worktree isolation itself is Claude Code's job now (native `--worktree` /
+ * `isolation: worktree`) — this config is read by the WorktreeCreate hook
+ * that plugs Claude Code Local Merge's lane numbering into that, and by everything
+ * downstream of it (the build queue, the landing queue, preview).
+ */
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+export const DEFAULTS = {
+    branchPrefix: "lane/",
+    worktreeSuffix: "-lane-",
+    portBase: 3000,
+    integrationBranch: "main",
+    productionBranch: null,
+    protectedBranches: [],
+    regenerableFiles: [],
+    symlinks: [".env", ".env.local", "node_modules"],
+    buildOutputDirs: ["dist", "build", ".next"],
+    checkCommand: null,
+    checksRequired: true,
+};
+/**
+ * Fail loud on a malformed config instead of silently misbehaving three
+ * commands later. Returns a list of human-readable problems — empty means
+ * valid.
+ */
+export function validateConfig(cfg) {
+    const problems = [];
+    const nonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
+    if (!nonEmptyString(cfg.branchPrefix))
+        problems.push("branchPrefix must be a non-empty string.");
+    if (!nonEmptyString(cfg.worktreeSuffix))
+        problems.push("worktreeSuffix must be a non-empty string.");
+    if (typeof cfg.portBase !== "number" || !Number.isInteger(cfg.portBase) || cfg.portBase <= 0) {
+        problems.push("portBase must be a positive integer.");
+    }
+    if (!nonEmptyString(cfg.integrationBranch))
+        problems.push("integrationBranch must be a non-empty string.");
+    if (cfg.productionBranch !== null && !nonEmptyString(cfg.productionBranch)) {
+        problems.push("productionBranch must be null or a non-empty string.");
+    }
+    if (cfg.productionBranch !== null && cfg.productionBranch === cfg.integrationBranch) {
+        problems.push("productionBranch and integrationBranch are the same branch — that's a no-op two-stage model. Set productionBranch to null instead.");
+    }
+    if (!Array.isArray(cfg.protectedBranches) || !cfg.protectedBranches.every(nonEmptyString)) {
+        problems.push("protectedBranches must be an array of non-empty strings.");
+    }
+    else if (cfg.protectedBranches.includes(cfg.integrationBranch)) {
+        problems.push("protectedBranches contains integrationBranch — that branch is where claude-code-local-merge land pushes; it can't also be blocked.");
+    }
+    if (!Array.isArray(cfg.regenerableFiles) || !cfg.regenerableFiles.every((v) => typeof v === "string")) {
+        problems.push("regenerableFiles must be an array of strings.");
+    }
+    if (!Array.isArray(cfg.symlinks) || !cfg.symlinks.every((v) => typeof v === "string")) {
+        problems.push("symlinks must be an array of strings.");
+    }
+    if (!Array.isArray(cfg.buildOutputDirs) || !cfg.buildOutputDirs.every((v) => typeof v === "string")) {
+        problems.push("buildOutputDirs must be an array of strings.");
+    }
+    if (cfg.checkCommand !== null && !nonEmptyString(cfg.checkCommand)) {
+        problems.push("checkCommand must be null or a non-empty string.");
+    }
+    if (typeof cfg.checksRequired !== "boolean") {
+        problems.push("checksRequired must be a boolean.");
+    }
+    return problems;
+}
+/**
+ * The repo's actual current branch, so `init` doesn't blindly assume "main"
+ * — plenty of real repos still default to "master" (or something else
+ * entirely), and a generated config pointing at a branch that doesn't exist
+ * is exactly the kind of out-of-the-box friction this tool exists to avoid.
+ * Returns null (letting the caller fall back to DEFAULTS) if there's no
+ * commit yet or HEAD is detached.
+ */
+export function detectCurrentBranch(cwd = process.cwd()) {
+    try {
+        const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        return branch && branch !== "HEAD" ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function findRepoRoot(cwd = process.cwd()) {
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd,
+            encoding: "utf8",
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function candidatePaths(root) {
+    return [join(root, "claude-code-local-merge.config.mjs"), join(root, "claude-code-local-merge.config.js")];
+}
+export function configPath(cwd = process.cwd()) {
+    const root = findRepoRoot(cwd);
+    if (!root)
+        return null;
+    return candidatePaths(root).find((p) => existsSync(p)) ?? null;
+}
+export function hasConfig(cwd = process.cwd()) {
+    return configPath(cwd) !== null;
+}
+/**
+ * Load claude-code-local-merge.config.(m)js from the current repo, merged over DEFAULTS.
+ * Throws with every problem listed if the merged config is invalid — a
+ * config that's silently wrong is worse than a command that refuses to run.
+ */
+export async function loadConfig(cwd = process.cwd()) {
+    const p = configPath(cwd);
+    if (!p)
+        return { ...DEFAULTS };
+    const mod = (await import(pathToFileURL(p).href));
+    const cfg = { ...DEFAULTS, ...(mod.default ?? {}) };
+    const problems = validateConfig(cfg);
+    if (problems.length > 0) {
+        throw new Error(`Invalid claude-code-local-merge.config at ${p}:\n${problems.map((p2) => `  - ${p2}`).join("\n")}`);
+    }
+    return cfg;
+}

package/dist/lib/ephemeral.d.ts

@@ -0,0 +1,40 @@
+export interface EphemeralResourceProvider<T> {
+    /** Create one resource for this run and return whatever callers need to use it. */
+    create(): Promise<T>;
+    /** Tear down a resource this same process created. */
+    destroy(handle: T): Promise<void>;
+    /**
+     * Tear down a resource some OTHER (now-dead) process created and never got
+     * to destroy — a crash, a SIGKILL, a CI runner that got cancelled. Given
+     * only what was recorded at claim time (see ClaimRegistry below).
+     */
+    destroyOrphan(claim: Claim): Promise<void>;
+}
+export interface Claim {
+    id: string;
+    pid: number;
+    createdAt: number;
+}
+/**
+ * A tiny on-disk registry of "what's claimed, by which PID." Not a database
+ * — just enough bookkeeping to answer "is this orphaned?" the same way
+ * queue-lock.ts answers it for locks: check whether the claiming PID is
+ * still alive, with no timeout to tune.
+ */
+export declare class ClaimRegistry {
+    private readonly dir;
+    constructor(registryDir: string);
+    record(claim: Claim): void;
+    release(id: string): void;
+    /** Every claim whose owning PID is no longer alive — safe to destroy. */
+    orphans(): Claim[];
+}
+/**
+ * Run `fn` against a freshly created resource, prune any orphans left by a
+ * previous crashed run first, and always release the claim — including on
+ * a thrown error. If THIS process is killed before the `finally` runs, the
+ * resource isn't leaked forever: the next call to `withEphemeralResource`
+ * (in the next test run, from any lane) prunes it via `orphans()` before
+ * creating its own.
+ */
+export declare function withEphemeralResource<T>(provider: EphemeralResourceProvider<T>, registry: ClaimRegistry, fn: (resource: T) => Promise<void>): Promise<void>;