lanekeeper 0.1.0

package/dist/lib/config.js

@@ -0,0 +1,137 @@
+/**
+ * lanekeeper.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."
+ *
+ * `lanekeeper 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 LaneKeeper'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 lanekeeper 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, "lanekeeper.config.mjs"), join(root, "lanekeeper.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 lanekeeper.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 lanekeeper.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>;

package/dist/lib/ephemeral.js

@@ -0,0 +1,100 @@
+/**
+ * The extension point for per-run ephemeral test resources — a throwaway
+ * database branch, a scratch bucket, a sandboxed queue, whatever your test
+ * suite needs that would otherwise race across concurrent lanes.
+ *
+ * This file is deliberately NOT wired to any specific provider. Everyone's
+ * test setup is different (Neon, a local Postgres with template databases, a
+ * Docker container per run, nothing at all) and shipping one company's
+ * choice as the default would make this less useful, not more. What's
+ * shipped instead is the *shape* — the same claim → use → release, and the
+ * same PID-liveness self-heal, that queue-lock.ts and launch.ts already use
+ * for the lock and the lane. One pattern, three places, so a crashed run
+ * never needs a human to notice and clean up after it.
+ *
+ * See examples/ephemeral-tmp-dir.example.ts for a complete, runnable
+ * implementation (a scratch directory per run, no external service) — copy
+ * its shape when you wire this to your own database or resource provider.
+ */
+import { mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+/**
+ * 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 class ClaimRegistry {
+    dir;
+    constructor(registryDir) {
+        this.dir = registryDir;
+        mkdirSync(this.dir, { recursive: true });
+    }
+    record(claim) {
+        writeFileSync(join(this.dir, claim.id), JSON.stringify(claim));
+    }
+    release(id) {
+        try {
+            unlinkSync(join(this.dir, id));
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    /** Every claim whose owning PID is no longer alive — safe to destroy. */
+    orphans() {
+        let names;
+        try {
+            names = readdirSync(this.dir);
+        }
+        catch {
+            return [];
+        }
+        const found = [];
+        for (const name of names) {
+            try {
+                const claim = JSON.parse(readFileSync(join(this.dir, name), "utf8"));
+                if (!alive(claim.pid))
+                    found.push(claim);
+            }
+            catch {
+                /* unreadable claim file — leave it, don't guess */
+            }
+        }
+        return found;
+    }
+}
+/**
+ * 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 async function withEphemeralResource(provider, registry, fn) {
+    for (const orphan of registry.orphans()) {
+        await provider.destroyOrphan(orphan);
+        registry.release(orphan.id);
+    }
+    const id = `${Date.now()}-${process.pid}`;
+    const claim = { id, pid: process.pid, createdAt: Date.now() };
+    registry.record(claim);
+    const resource = await provider.create();
+    try {
+        await fn(resource);
+    }
+    finally {
+        await provider.destroy(resource);
+        registry.release(id);
+    }
+}

package/dist/lib/lane-port.d.ts

@@ -0,0 +1,3 @@
+import type { LaneKeeperConfig } from "./config.js";
+export declare function laneNumberFromPath(path: string, cfg: Pick<LaneKeeperConfig, "worktreeSuffix">): number | null;
+export declare function lanePort(path: string, cfg: Pick<LaneKeeperConfig, "worktreeSuffix" | "portBase">): number | null;

package/dist/lib/lane-port.js

@@ -0,0 +1,25 @@
+/**
+ * A lane's dev-server port, derived from where it's sitting on disk rather
+ * than an injected environment variable. Claude Code's WorktreeCreate hook
+ * has no mechanism to hand environment variables to the session that runs
+ * in the worktree it creates — only the directory path. So instead of
+ * betting on a second, less-certain hook (SessionStart + CLAUDE_ENV_FILE)
+ * to smuggle a port in, the worktree's own name already carries it: Lane
+ * Keeper names worktrees "<repo><worktreeSuffix><n>", so any script running
+ * inside one can read its own lane number straight off `process.cwd()`.
+ * Self-describing beats injected, when the information's already sitting
+ * right there in the path.
+ */
+import { basename } from "node:path";
+export function laneNumberFromPath(path, cfg) {
+    const name = basename(path);
+    const idx = name.lastIndexOf(cfg.worktreeSuffix);
+    if (idx === -1)
+        return null;
+    const n = Number(name.slice(idx + cfg.worktreeSuffix.length));
+    return Number.isInteger(n) && n > 0 ? n : null;
+}
+export function lanePort(path, cfg) {
+    const lane = laneNumberFromPath(path, cfg);
+    return lane === null ? null : cfg.portBase + lane;
+}

package/dist/lib/main-checkout.d.ts

@@ -0,0 +1 @@
+export declare function resolveMainCheckout(cwd?: string): string;

package/dist/lib/main-checkout.js

@@ -0,0 +1,19 @@
+/**
+ * Resolve the MAIN checkout — the one non-lane checkout your dev server (or
+ * CI, or whatever's watching the filesystem) actually runs from — starting
+ * from any lane worktree.
+ *
+ * git-common-dir is ".git" (relative) from the main checkout itself, or an
+ * absolute path to <main>/.git from a linked worktree — either way its
+ * parent is MAIN. Shared by sync and preview so they agree on the one true
+ * answer.
+ */
+import { execFileSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+export function resolveMainCheckout(cwd = process.cwd()) {
+    const common = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+        cwd,
+        encoding: "utf8",
+    }).trim();
+    return dirname(resolve(cwd, common));
+}

package/dist/lib/prune-lanes.d.ts

@@ -0,0 +1,8 @@
+import type { LaneKeeperConfig } from "./config.js";
+/**
+ * Removes already-landed sibling lane worktrees. Returns the paths it
+ * actually removed. Best-effort throughout — any failure for a given
+ * worktree (dirty, diverged, busy) just skips that one; this never blocks
+ * or fails the `land` it's running as part of.
+ */
+export declare function pruneLandedLanes(mainTop: string, cfg: Pick<LaneKeeperConfig, "worktreeSuffix" | "branchPrefix" | "integrationBranch">, currentWorktree: string): string[];

package/dist/lib/prune-lanes.js

@@ -0,0 +1,120 @@
+/**
+ * After a lane lands, sibling lanes that were ALSO already fully landed have
+ * no more reason to keep a worktree around — nothing created one on the way
+ * in tore it down on the way out (Claude Code's own worktree lifecycle
+ * doesn't either), so directories silently accumulate on disk forever
+ * unless something sweeps them. This runs that sweep as a side effect of
+ * every successful `land`, never touching the worktree currently running
+ * this process or the main checkout itself.
+ *
+ * Safety:
+ *   1. Only prune a worktree whose branch is a git ANCESTOR of
+ *      origin/<integrationBranch> — the authoritative, already-pushed
+ *      truth — not the local integration branch, which may not be
+ *      fast-forwarded yet at the exact moment this runs. That's the literal
+ *      definition of "nothing to lose": the work already made it upstream
+ *      under its own name.
+ *   2. `git worktree remove` (no `--force`) refuses on its own if the
+ *      worktree has uncommitted changes — dirty work is never discarded
+ *      just because its branch happens to be merged.
+ * Deleting the now-redundant local branch (`git branch -d`, never `-D`) is a
+ * separate, best-effort tidiness step AFTER the worktree is already gone —
+ * it checks merge state against local HEAD rather than origin, so it can
+ * legitimately fail if the local integration branch hasn't caught up yet.
+ * That failure doesn't undo the (already-safe) worktree removal or keep it
+ * out of the returned list; it just leaves a harmless leftover branch ref.
+ */
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { basename, dirname } from "node:path";
+// Best-effort realpath — a "current worktree" that's already gone (or was
+// never real to begin with) shouldn't crash the sweep over one path.
+function existsRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function listWorktrees(mainTop) {
+    const out = execFileSync("git", ["worktree", "list", "--porcelain"], { cwd: mainTop, encoding: "utf8" });
+    const entries = [];
+    let current = {};
+    const flush = () => {
+        if (current.path)
+            entries.push({ path: current.path, branch: current.branch ?? null });
+        current = {};
+    };
+    for (const line of out.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            flush();
+            current.path = line.slice("worktree ".length);
+        }
+        else if (line.startsWith("branch ")) {
+            current.branch = line.slice("branch ".length).replace("refs/heads/", "");
+        }
+        else if (line === "") {
+            flush();
+        }
+    }
+    flush();
+    return entries;
+}
+/**
+ * Removes already-landed sibling lane worktrees. Returns the paths it
+ * actually removed. Best-effort throughout — any failure for a given
+ * worktree (dirty, diverged, busy) just skips that one; this never blocks
+ * or fails the `land` it's running as part of.
+ */
+export function pruneLandedLanes(mainTop, cfg, currentWorktree) {
+    const pruned = [];
+    // `git worktree list` reports fully realpath-resolved paths (symlinks like
+    // macOS's /var -> /private/var followed) — resolve our own reference
+    // points the same way, or every comparison below silently never matches.
+    const mainTopReal = realpathSync(mainTop);
+    const currentWorktreeReal = existsRealpath(currentWorktree);
+    const laneDirPrefix = `${basename(mainTopReal)}${cfg.worktreeSuffix}`;
+    const parent = dirname(mainTopReal);
+    const upstream = `origin/${cfg.integrationBranch}`;
+    let worktrees;
+    try {
+        worktrees = listWorktrees(mainTop);
+    }
+    catch {
+        return pruned;
+    }
+    for (const { path: wt, branch } of worktrees) {
+        if (wt === mainTopReal || wt === currentWorktreeReal)
+            continue;
+        if (dirname(wt) !== parent || !basename(wt).startsWith(laneDirPrefix))
+            continue; // not one of ours
+        if (!branch || !branch.startsWith(cfg.branchPrefix))
+            continue;
+        try {
+            execFileSync("git", ["merge-base", "--is-ancestor", branch, upstream], {
+                cwd: mainTop,
+                stdio: "ignore",
+            }); // throws (non-zero exit) if NOT an ancestor — caught below, left alone
+        }
+        catch {
+            continue; // not safe to touch — leave this lane exactly as it is
+        }
+        try {
+            execFileSync("git", ["worktree", "remove", wt], { cwd: mainTop, stdio: "ignore" });
+        }
+        catch {
+            continue; // dirty or busy — worktree remove refused on its own, nothing removed
+        }
+        // The worktree is gone — this is now unconditionally a pruned lane,
+        // regardless of what happens to the branch ref below.
+        pruned.push(wt);
+        try {
+            execFileSync("git", ["branch", "-d", branch], { cwd: mainTop, stdio: "ignore" });
+        }
+        catch {
+            /* local integration branch may not be fast-forwarded yet — harmless, leaves the ref behind */
+        }
+    }
+    return pruned;
+}

package/dist/lib/queue-lock.d.ts

@@ -0,0 +1,26 @@
+interface LockHolder {
+    pid: number;
+    lane: string;
+    label?: string;
+    ts: number;
+}
+export interface AcquireOptions {
+    label?: string;
+    onWait?: (info: {
+        ahead: number;
+        holder: LockHolder | null;
+    }) => void;
+}
+export interface QueueLock {
+    acquire(options?: AcquireOptions): Promise<void>;
+    release(): void;
+    readonly lane: string;
+    readonly held: boolean;
+}
+/**
+ * Create a named FIFO lock. Each distinct `queueName` is an independent
+ * mutex — "build" and "land" never contend with each other even though
+ * they share this exact same code.
+ */
+export declare function createQueueLock(queueName: string): QueueLock;
+export {};