claude-code-merge-queue 0.1.14

package/dist/sync.js

@@ -0,0 +1,161 @@
+/**
+ * sync.ts — fast-forward the MAIN checkout to its upstream branch.
+ *
+ * Your dev server (or whatever's watching the filesystem) runs on the MAIN
+ * checkout, which tracks the integration branch. Lanes land onto that branch
+ * via a push, but the MAIN checkout's working tree only advances on a pull —
+ * so it serves stale files until something fast-forwards it. `land` runs
+ * this immediately after every successful push, so the dev server picks up
+ * landed work with zero manual `git pull`.
+ *
+ * Safe by construction:
+ *   - Fast-forward ONLY. If the checkout has diverged from its upstream, it
+ *     warns and leaves it untouched — never a force, never a merge commit.
+ *   - Retries transient index.lock contention (two lanes landing near-simultaneously).
+ *   - If a fast-forward is blocked only by a locally-modified *regenerable*
+ *     file (configured in claude-code-local-merge.config), it discards that file and
+ *     retries. Any other dirty file → warn and skip.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { loadConfig } from "./lib/config.js";
+import { resolveMainCheckout } from "./lib/main-checkout.js";
+import { detectPackageManager } from "./lib/check-command.js";
+const LOCK_RETRIES = 3;
+// Keyed by detectPackageManager's return value. bun writes either lockfile
+// name depending on version, so both are checked.
+const LOCKFILES = {
+    npm: ["package-lock.json"],
+    pnpm: ["pnpm-lock.yaml"],
+    yarn: ["yarn.lock"],
+    bun: ["bun.lockb", "bun.lock"],
+};
+/**
+ * The main checkout's node_modules is the one every lane symlinks from
+ * (see claude-code-local-merge.config's `symlinks`). Fast-forwarding its git state does
+ * nothing to that directory — if the range we just pulled in changed the
+ * lockfile, every lane is now silently running on stale dependencies until
+ * someone happens to run `npm install` here by hand. Do it automatically,
+ * the same moment the git state lands, so the gap never opens.
+ */
+function refreshDependenciesIfChanged(root, before, after) {
+    const pm = detectPackageManager(root);
+    const lockfiles = LOCKFILES[pm] ?? [];
+    const changed = git(root, ["diff", "--name-only", before, after], { allowFail: true }).out.split("\n");
+    if (!lockfiles.some((f) => changed.includes(f)))
+        return;
+    console.log(`claude-code-local-merge sync: lockfile changed — running "${pm} install" so the shared node_modules (symlinked into every lane) stays in sync…`);
+    const result = spawnSync(pm, ["install"], { cwd: root, stdio: "inherit" });
+    if (result.status !== 0) {
+        console.error(`claude-code-local-merge sync: "${pm} install" failed (exit ${result.status ?? 1}) — shared node_modules may be stale. Run it manually in ${root}.`);
+    }
+    else {
+        console.log("claude-code-local-merge sync: dependencies refreshed.");
+    }
+}
+function git(cwd, args, { allowFail = false } = {}) {
+    try {
+        return {
+            ok: true,
+            out: execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }),
+        };
+    }
+    catch (e) {
+        if (!allowFail)
+            throw e;
+        const err = e;
+        return { ok: false, out: `${err.stdout ?? ""}${err.stderr ?? ""}` };
+    }
+}
+function sleep(ms) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        /* tiny synchronous backoff for index.lock */
+    }
+}
+/**
+ * Fast-forwards the MAIN checkout. Returns a process exit code; never throws.
+ *
+ * Accepts an already-loaded config, for `land` calling this immediately
+ * after a push that ITSELF introduced or changed claude-code-local-merge.config.mjs: the
+ * MAIN checkout hasn't been fast-forwarded yet at that exact moment (that's
+ * this function's whole job), so loading fresh from MAIN would silently
+ * fall back to DEFAULTS and could reject a perfectly good sync — the same
+ * bootstrap gap createLane had to be fixed for. The lane's own config,
+ * which just successfully rebased onto and pushed to the real
+ * integrationBranch, is the more trustworthy answer at that moment. A bare
+ * `claude-code-local-merge sync` (no caller-provided config) still loads fresh from
+ * MAIN, same as before.
+ */
+export async function sync(providedCfg) {
+    let MAIN;
+    try {
+        MAIN = resolveMainCheckout(process.cwd());
+    }
+    catch {
+        console.error("claude-code-local-merge sync: not inside a git repo — nothing to do.");
+        return 0;
+    }
+    const cfg = providedCfg ?? (await loadConfig(MAIN));
+    const regenerable = new Set(cfg.regenerableFiles);
+    const branchRes = git(MAIN, ["rev-parse", "--abbrev-ref", "HEAD"], { allowFail: true });
+    const branch = branchRes.out.trim();
+    if (!branch || branch === "HEAD") {
+        console.error("claude-code-local-merge sync: the checkout is detached or unresolved — left untouched.");
+        return 0;
+    }
+    // The main checkout is meant to stay parked on integrationBranch permanently
+    // (that's what makes "fast-forward it" a safe, unattended operation). If
+    // it's on something else — someone switched branches in it by hand, or ran
+    // `land` from a single non-worktree checkout instead of a lane worktree —
+    // fast-forwarding "whatever HEAD happens to be" silently does the wrong
+    // thing. Say so plainly instead of surfacing a raw git error later.
+    if (branch !== cfg.integrationBranch) {
+        console.error(`claude-code-local-merge sync: this checkout is on '${branch}', not the configured integrationBranch ` +
+            `('${cfg.integrationBranch}'). sync only fast-forwards the main checkout — run it from ` +
+            `there, or check out '${cfg.integrationBranch}' here first. Left untouched.`);
+        return 0;
+    }
+    const upstream = `origin/${branch}`;
+    const before = git(MAIN, ["rev-parse", "--short", "HEAD"], { allowFail: true }).out.trim();
+    git(MAIN, ["fetch", "origin", "--quiet"], { allowFail: true });
+    const tryFastForward = () => git(MAIN, ["merge", "--ff-only", upstream], { allowFail: true });
+    let res = tryFastForward();
+    // Retry transient lock contention (another lane landing at the same instant).
+    for (let i = 0; i < LOCK_RETRIES && !res.ok && /index\.lock|Unable to create|another git process/i.test(res.out); i++) {
+        sleep(400);
+        res = tryFastForward();
+    }
+    // Blocked by a locally-modified regenerable file? Discard it and retry once.
+    if (!res.ok && /would be overwritten by merge/i.test(res.out)) {
+        const files = res.out
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l && !/would be overwritten|please commit|aborting|^error:/i.test(l));
+        const blocking = files.filter((f) => !regenerable.has(f));
+        if (blocking.length === 0 && files.length > 0) {
+            git(MAIN, ["checkout", "--", ...files], { allowFail: true });
+            res = tryFastForward();
+        }
+        else {
+            console.error(`claude-code-local-merge sync: ${branch} has local changes blocking fast-forward (${blocking.join(", ")}). Left untouched — resolve in the checkout.`);
+            return 0;
+        }
+    }
+    if (res.ok) {
+        const after = git(MAIN, ["rev-parse", "--short", "HEAD"], { allowFail: true }).out.trim();
+        if (before === after) {
+            console.log(`claude-code-local-merge sync: ${branch} already current at ${after}.`);
+        }
+        else {
+            console.log(`claude-code-local-merge sync: fast-forwarded ${branch} ${before} → ${after} — the dev server will pick it up.`);
+            refreshDependenciesIfChanged(MAIN, before, after);
+        }
+        return 0;
+    }
+    if (/Not possible to fast-forward|diverging|non-fast-forward/i.test(res.out)) {
+        console.error(`claude-code-local-merge sync: local ${branch} has DIVERGED from ${upstream} (something was committed directly on the checkout). Left untouched — reconcile it manually.`);
+        return 0;
+    }
+    console.error(`claude-code-local-merge sync: could not fast-forward ${branch} — left untouched.\n${res.out.trim()}`);
+    return 0;
+}

package/examples/claude-code-local-merge.config.mjs

@@ -0,0 +1,67 @@
+// claude-code-local-merge.config.mjs — lives at your repo root. `claude-code-local-merge init` writes a
+// copy of this for you; edit the values below for your project.
+//
+// Worktree isolation is Claude Code's job (native `--worktree` /
+// `isolation: "worktree"`) — this file is what the WorktreeCreate hook
+// (see hooks/claude-settings.example.json) reads to name and shape the lane
+// it creates, and what everything downstream (build queue, landing queue,
+// preview) reads too.
+
+/** @type {import("claude-code-local-merge").ClaudeCodeLocalMergeConfig} */
+export default {
+  // Lane branches: lane/1, lane/2, ...
+  branchPrefix: "lane/",
+
+  // Sibling worktree dirs: ../<your-repo>-lane-1, -lane-2, ...
+  worktreeSuffix: "-lane-",
+
+  // Lane 1 gets this port, lane 2 gets portBase + 2, and so on — handy if
+  // each lane also runs its own throwaway dev server.
+  portBase: 3000,
+
+  // The branch `claude-code-local-merge land` rebases onto and pushes to. Agents land
+  // here continuously and autonomously — see the CLAUDE.md workflow section
+  // `claude-code-local-merge init` writes.
+  integrationBranch: "main",
+
+  // Set this if you run a two-stage model: agents land on integrationBranch,
+  // a human ships to productionBranch on their own schedule with
+  // `claude-code-local-merge promote`. null (the default) means integrationBranch IS
+  // production — no separate promotion step. Example: integrationBranch
+  // "dev", productionBranch "main". Automatically protected by the pre-push
+  // hook when set — you don't need to also list it below.
+  productionBranch: null,
+
+  // Extra branches the pre-push hook refuses a *direct* push to, beyond
+  // integrationBranch and productionBranch. Most repos need nothing here.
+  protectedBranches: [],
+
+  // Files your build tool rewrites on its own that should never block a
+  // rebase or a fast-forward. Next.js projects typically want
+  // ["next-env.d.ts"] here at minimum — add to this list the first time a
+  // regenerated file blocks a landing, and never think about it again.
+  regenerableFiles: [],
+
+  // Git-ignored paths symlinked into every new lane so it needs no fresh
+  // install and no copy of your secrets.
+  symlinks: [".env", ".env.local", "node_modules"],
+
+  // Build-output dirs `claude-code-local-merge preview` never copies onto your dev
+  // checkout. preview is framework-agnostic (it's an rsync, not a build
+  // step) — this is the one place your framework's name shows up. Add
+  // ".output" for Nuxt, ".svelte-kit" for SvelteKit, etc.
+  buildOutputDirs: ["dist", "build", ".next"],
+
+  // The command that actually gates a landing — your lint/typecheck/test/
+  // build. `claude-code-local-merge init` tries to detect this from package.json
+  // (check:push, check, ci, or test, in that order) and fills it in for
+  // you. null means nothing runs, which is only allowed if checksRequired
+  // is also false — see below.
+  checkCommand: "npm run check",
+
+  // true (the default): a null checkCommand FAILS every push rather than
+  // landing unverified code. Set to false yourself to deliberately run
+  // with no checks — a real state for a repo with nothing to test yet, but
+  // one that should be a visible, committed choice, not a silent default.
+  checksRequired: true,
+};

package/examples/ephemeral-tmp-dir.example.ts

@@ -0,0 +1,66 @@
+/**
+ * A complete, runnable EphemeralResourceProvider — a scratch directory per
+ * test run instead of a database branch, so this example works with zero
+ * external services and zero cost. Swap `create`/`destroy`/`destroyOrphan`
+ * for calls to your actual provider (a Neon branch-create/delete API, a
+ * `CREATE DATABASE ... TEMPLATE ...`, a Docker container) and everything
+ * else — the claim registry, the orphan pruning, the finally-block release —
+ * carries over unchanged.
+ *
+ * Run it:  node --import tsx examples/ephemeral-tmp-dir.example.ts
+ * Simulate a crash:  node --import tsx examples/ephemeral-tmp-dir.example.ts --crash
+ *   then run it again without --crash and watch it prune the orphan first.
+ */
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ClaimRegistry, withEphemeralResource, type EphemeralResourceProvider } from "../src/lib/ephemeral.js";
+
+const REGISTRY_DIR = join(tmpdir(), "claude-code-local-merge-example-ephemeral-registry");
+const RESOURCE_ROOT = join(tmpdir(), "claude-code-local-merge-example-ephemeral-resources");
+mkdirSync(RESOURCE_ROOT, { recursive: true });
+
+const tmpDirProvider: EphemeralResourceProvider<string> = {
+  async create() {
+    const dir = mkdtempSync(join(RESOURCE_ROOT, "run-"));
+    console.log(`  created scratch dir: ${dir}`);
+    return dir;
+  },
+  async destroy(dir) {
+    rmSync(dir, { recursive: true, force: true });
+    console.log(`  destroyed scratch dir: ${dir}`);
+  },
+  async destroyOrphan(claim) {
+    // The claim only tells us WHO made it and WHEN, not which directory it
+    // owned — in a real provider you'd store that mapping yourself (e.g. the
+    // resource's ID inside the claim record). For this example, orphaned
+    // "run-*" directories are swept by age instead.
+    console.log(`  pruning orphan left by dead pid ${claim.pid} (claimed at ${new Date(claim.createdAt).toISOString()})`);
+    for (const name of readdirSync(RESOURCE_ROOT)) {
+      const path = join(RESOURCE_ROOT, name);
+      if (existsSync(join(path, ".orphan-sweep-safe"))) {
+        rmSync(path, { recursive: true, force: true });
+      }
+    }
+  },
+};
+
+const registry = new ClaimRegistry(REGISTRY_DIR);
+
+if (process.argv.includes("--crash")) {
+  // Simulate a run that claims a resource and then dies before its finally
+  // block runs — no rmSync, no registry.release(). The NEXT run should find
+  // and prune this.
+  const dir = mkdtempSync(join(RESOURCE_ROOT, "run-"));
+  writeFileSync(join(dir, ".orphan-sweep-safe"), "");
+  registry.record({ id: `${Date.now()}-${process.pid}`, pid: process.pid, createdAt: Date.now() });
+  console.log(`simulated crash: claimed ${dir} and exiting without cleanup (pid ${process.pid})`);
+  process.exit(1);
+}
+
+await withEphemeralResource(tmpDirProvider, registry, async (dir) => {
+  writeFileSync(join(dir, "example.txt"), "this file only exists for the run's lifetime\n");
+  console.log(`  running your tests against ${dir}…`);
+});
+
+console.log("done — resource was created, used, and torn down; any prior orphan was pruned first.");

package/hooks/claude-settings.example.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx claude-code-local-merge hook worktree-create"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/pre-push

@@ -0,0 +1,23 @@
+#!/usr/bin/env sh
+# Claude Code Local Merge — landing-queue enforcement + your checks, gating every push.
+#
+# Copy this file to .husky/pre-push (recommended — Husky wires it in on
+# your package manager's install step, for every clone and every lane
+# worktree) or straight to
+# .git/hooks/pre-push (works, but isn't versioned or shared with the team).
+# If you already have a pre-push hook, append this block instead of
+# replacing the file. `claude-code-local-merge init` does all of this for you.
+#
+# `claude-code-local-merge check-push` does two things, in order:
+#   1. Blocks a direct push to your integration/protected/production
+#      branches that didn't go through `claude-code-local-merge land` / `promote`.
+#   2. Runs `checkCommand` from claude-code-local-merge.config.mjs (your lint/typecheck/
+#      test/build) and fails the push if it fails — or if checkCommand
+#      isn't set and checksRequired wasn't deliberately turned off.
+#
+# See src/land.ts and src/lib/check-push.ts for why a convention alone
+# isn't enough to guarantee either of those.
+
+if ! npx claude-code-local-merge check-push; then
+  exit 1
+fi

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "claude-code-merge-queue",
+  "version": "0.1.14",
+  "description": "The local, zero-cost merge queue for parallel Claude Code agents. Plugs into Claude Code's native worktree isolation; one build at a time, one landing at a time, zero races.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jesse Heaslip",
+  "homepage": "https://github.com/funador/claude-code-local-merge",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/funador/claude-code-local-merge.git"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "git-worktree",
+    "parallel-agents",
+    "coding-agent",
+    "merge-queue",
+    "monorepo-tooling"
+  ],
+  "bin": {
+    "claude-code-local-merge": "dist/bin/claude-code-local-merge.js"
+  },
+  "files": [
+    "dist",
+    "hooks",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/bin/claude-code-local-merge.js",
+    "prepare": "npm run build",
+    "pretest": "npm run build",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}