lanekeeper 0.1.0

package/dist/lib/queue-lock.js

@@ -0,0 +1,212 @@
+/**
+ * A generic, cross-worktree FIFO lock: the one primitive every other command
+ * in this repo is built on. `build-lock` and `land` are the same core idea —
+ * "serialize one action, machine-wide" — wearing two different hats.
+ *
+ * One queue name = one global mutex for this repo, shared by every worktree
+ * of it (keyed off git's common dir, so a different clone gets its own queue
+ * and two unrelated repos never contend with each other).
+ *
+ * Design:
+ *   - FIFO: each waiter enrolls a timestamped ticket and only competes for
+ *     the lock once it owns the oldest still-live ticket. No starvation, no
+ *     "whoever polls fastest wins."
+ *   - Crash-safe with NO timeouts, so there's no magic staleness threshold to
+ *     tune: a lock or ticket whose holder PID is no longer alive is reclaimed
+ *     the instant another waiter checks. Kill -9 the holder mid-lock and the
+ *     queue heals itself on the next poll.
+ */
+import { mkdirSync, writeFileSync, readFileSync, linkSync, unlinkSync, readdirSync, } from "node:fs";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join, basename } from "node:path";
+import { execSync } from "node:child_process";
+// How often a waiter re-checks whether it's its turn. Not a behavioral cap —
+// just poll granularity.
+const POLL_MS = 200;
+function repoKey() {
+    try {
+        const commonDir = execSync("git rev-parse --git-common-dir", {
+            encoding: "utf8",
+        }).trim();
+        // Resolve to an absolute, worktree-independent path so every worktree of
+        // the same repo hashes to the same queue.
+        return execSync(`cd "${commonDir}" && pwd -P`, { encoding: "utf8" }).trim();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+/**
+ * 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 function createQueueLock(queueName) {
+    const QUEUE_DIR = join(tmpdir(), `lanekeeper-${queueName}-queue-${createHash("sha1").update(repoKey()).digest("hex").slice(0, 12)}`);
+    const TICKETS_DIR = join(QUEUE_DIR, "tickets");
+    const LOCK_FILE = join(QUEUE_DIR, "lock");
+    mkdirSync(TICKETS_DIR, { recursive: true });
+    const lane = basename(process.cwd());
+    const ME = process.pid;
+    const TICKET_TS = Date.now();
+    const TICKET_NAME = `${TICKET_TS}-${ME}`;
+    const TICKET_FILE = join(TICKETS_DIR, TICKET_NAME);
+    function alive(pid) {
+        if (!pid || pid === ME)
+            return pid === ME;
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (e) {
+            return e.code === "EPERM"; // exists but owned by someone else
+        }
+    }
+    function pidOf(name) {
+        const dash = name.lastIndexOf("-");
+        return dash === -1 ? 0 : Number(name.slice(dash + 1));
+    }
+    function pruneDeadTickets() {
+        let names;
+        try {
+            names = readdirSync(TICKETS_DIR);
+        }
+        catch {
+            return [];
+        }
+        const live = [];
+        for (const name of names) {
+            if (alive(pidOf(name))) {
+                live.push(name);
+            }
+            else {
+                try {
+                    unlinkSync(join(TICKETS_DIR, name));
+                }
+                catch {
+                    /* someone else cleaned it */
+                }
+            }
+        }
+        live.sort((a, b) => {
+            const [ta, pa] = a.split("-").map(Number);
+            const [tb, pb] = b.split("-").map(Number);
+            return ta - tb || pa - pb;
+        });
+        return live;
+    }
+    function readLockHolder() {
+        try {
+            return JSON.parse(readFileSync(LOCK_FILE, "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    // Atomically take the lock via link() (fails if it already exists). Reclaim
+    // a lock whose holder is dead. Returns true iff we now hold it.
+    function tryTakeLock(info) {
+        const tmp = `${LOCK_FILE}.${ME}.tmp`;
+        writeFileSync(tmp, JSON.stringify(info));
+        try {
+            linkSync(tmp, LOCK_FILE);
+            unlinkSync(tmp);
+            return true;
+        }
+        catch (e) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                /* noop */
+            }
+            if (e.code !== "EEXIST")
+                throw e;
+            const holder = readLockHolder();
+            if (!holder || !alive(holder.pid)) {
+                try {
+                    unlinkSync(LOCK_FILE);
+                }
+                catch {
+                    /* another waiter beat us to it */
+                }
+            }
+            return false;
+        }
+    }
+    let HOLD = false;
+    function release() {
+        if (HOLD) {
+            const holder = readLockHolder();
+            if (holder && holder.pid === ME) {
+                try {
+                    unlinkSync(LOCK_FILE);
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            HOLD = false;
+        }
+        try {
+            unlinkSync(TICKET_FILE);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    /**
+     * Wait for and take the lock. `onWait({ahead, holder})` fires whenever the
+     * queue position changes, so callers can print progress.
+     */
+    async function acquire({ label, onWait } = {}) {
+        writeFileSync(TICKET_FILE, JSON.stringify({ pid: ME, lane, label, ts: TICKET_TS }));
+        let announced = -1;
+        for (;;) {
+            const queue = pruneDeadTickets();
+            const ahead = queue.indexOf(TICKET_NAME); // 0 = our turn
+            const holder = readLockHolder();
+            const lockFree = !holder || !alive(holder.pid);
+            if (ahead <= 0 && lockFree) {
+                if (tryTakeLock({ pid: ME, lane, label, ts: Date.now() })) {
+                    HOLD = true;
+                    try {
+                        unlinkSync(TICKET_FILE);
+                    }
+                    catch {
+                        /* noop */
+                    }
+                    return;
+                }
+            }
+            if (ahead > 0 && ahead !== announced) {
+                announced = ahead;
+                onWait?.({ ahead, holder: null });
+            }
+            else if (ahead <= 0 && holder && alive(holder.pid) && announced !== 0) {
+                announced = 0;
+                onWait?.({ ahead: 0, holder });
+            }
+            await sleep(POLL_MS);
+        }
+    }
+    // Best-effort release on graceful exit. Deliberately NOT registering
+    // SIGINT/SIGTERM/SIGHUP handlers here: adding any listener for those
+    // signals cancels Node's default "terminate the process" behavior, and
+    // this module doesn't own whether/how a caller's process should exit
+    // (build-lock.ts needs its OWN signal handler to kill a child's process
+    // group first). Correctness doesn't depend on this firing anyway — a
+    // lock/ticket left behind by a killed process is reclaimed deterministically
+    // by the next acquire() via the PID-liveness check above, same as a SIGKILL.
+    process.on("exit", release);
+    return {
+        acquire,
+        release,
+        lane,
+        get held() {
+            return HOLD;
+        },
+    };
+}

package/dist/lib/tty-confirm.d.ts

@@ -0,0 +1 @@
+export declare function promptTtyConfirm(promptText: string): string | null;

package/dist/lib/tty-confirm.js

@@ -0,0 +1,44 @@
+/**
+ * A synchronous, type-the-exact-word confirmation prompt read straight from
+ * /dev/tty — the same trick interactive git hooks use, since stdin during a
+ * `git push` is git's own protocol, not free for a hook to read from.
+ *
+ * Used exactly once: the emergency bypass for a blocked push (see
+ * check-push.ts). Returns null if there's no interactive terminal to prompt
+ * on at all (CI, a piped/non-interactive push) — the caller treats that as
+ * "can't confirm," not "confirmed."
+ */
+import { openSync, closeSync, readSync, writeSync } from "node:fs";
+export function promptTtyConfirm(promptText) {
+    let fd;
+    try {
+        fd = openSync("/dev/tty", "r+");
+    }
+    catch {
+        return null;
+    }
+    try {
+        writeSync(fd, promptText);
+        const buf = Buffer.alloc(1);
+        let input = "";
+        for (;;) {
+            let bytesRead;
+            try {
+                bytesRead = readSync(fd, buf, 0, 1, null);
+            }
+            catch {
+                break;
+            }
+            if (bytesRead <= 0)
+                break;
+            const ch = buf.toString("utf8");
+            if (ch === "\n" || ch === "\r")
+                break;
+            input += ch;
+        }
+        return input.trim();
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/lib/wire-hooks.d.ts

@@ -0,0 +1,26 @@
+export type WireResult = "created" | "merged" | "already-wired" | "unparseable" | "no-husky";
+export declare function wireClaudeSettings(root: string): WireResult;
+export declare function wireHuskyPrePush(root: string): WireResult;
+export type HooksPathResult = "set" | "already-set" | "custom-path";
+/**
+ * A `.husky/pre-push` file on disk enforces nothing on its own — git only
+ * runs it if `core.hooksPath` points somewhere that resolves to it, which is
+ * normally set as a side effect of the package manager's install step
+ * (husky's own `prepare` script). On a freshly cloned repo where nobody's
+ * run that install yet — the exact state Quickstart leaves you in right
+ * after `init` — the file is silently inert and a direct push sails through
+ * uncontested. Since LaneKeeper is the one promising "pushes are gated now,"
+ * it sets this itself instead of depending on a step that may not have
+ * happened yet, mirroring exactly what `husky install` itself does.
+ *
+ * Husky v9 changed its own convention mid-flight: v6–v8 point
+ * core.hooksPath directly at `.husky` (hook files run as-is); v9 points it
+ * at `.husky/_`, a generated wrapper directory that then execs the real
+ * `.husky/<hookname>` file. Both are legitimate, already-correct setups —
+ * only treat something OTHER than either as a deliberate custom path worth
+ * warning about. `.husky/_` doesn't exist yet on the fresh-clone/no-install
+ * case this function exists for, so `.husky` remains the right thing to set
+ * when nothing's configured at all; if the project turns out to be v9,
+ * husky's own next real install corrects it to `.husky/_`.
+ */
+export declare function ensureHooksPath(root: string): HooksPathResult;

package/dist/lib/wire-hooks.js

@@ -0,0 +1,123 @@
+/**
+ * The rest of `init`'s job: safely wire the WorktreeCreate hook into
+ * `.claude/settings.json` and the pre-push hook into `.husky/pre-push`,
+ * instead of leaving them as "copy this file yourself" — the exact kind of
+ * manual step that undercuts a tool whose whole point is fewer manual steps.
+ *
+ * Both merges are additive and idempotent: creating the file if it's
+ * missing, adding just our entry without touching anything else if the
+ * file already exists, and doing nothing (safely) if our entry's already
+ * there. Neither ever overwrites content that isn't ours.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, chmodSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const HOOK_COMMAND = "npx lanekeeper hook worktree-create";
+const PRE_PUSH_MARKER = "lanekeeper check-push";
+export function wireClaudeSettings(root) {
+    const dir = join(root, ".claude");
+    const path = join(dir, "settings.json");
+    if (!existsSync(path)) {
+        mkdirSync(dir, { recursive: true });
+        const settings = {
+            hooks: { WorktreeCreate: [{ hooks: [{ type: "command", command: HOOK_COMMAND }] }] },
+        };
+        writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
+        return "created";
+    }
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return "unparseable"; // leave it alone — don't guess at broken JSON
+    }
+    settings.hooks ??= {};
+    settings.hooks.WorktreeCreate ??= [];
+    const alreadyWired = settings.hooks.WorktreeCreate.some((group) => group.hooks?.some((h) => h.command?.includes(HOOK_COMMAND)));
+    if (alreadyWired)
+        return "already-wired";
+    settings.hooks.WorktreeCreate.push({ hooks: [{ type: "command", command: HOOK_COMMAND }] });
+    writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
+    return "merged";
+}
+function shippedPrePushTemplate() {
+    // dist/lib/wire-hooks.js -> ../../hooks/pre-push at the package root.
+    const here = dirname(fileURLToPath(import.meta.url));
+    return readFileSync(join(here, "..", "..", "hooks", "pre-push"), "utf8");
+}
+// The template file is written to stand alone (shebang + comments explaining
+// itself to a human reading it fresh). Appending it whole into an *existing*
+// hook file would duplicate the shebang mid-script and leave behind prose
+// like "copy this file to .husky/pre-push" that's nonsensical once it's
+// already there. So strip the shebang and the leading comment block, and
+// append only the functional part — the same source of truth, no second
+// copy to drift out of sync.
+function functionalSnippet(template) {
+    const lines = template.split("\n");
+    let i = 0;
+    if (lines[0]?.startsWith("#!"))
+        i++;
+    for (; i < lines.length; i++) {
+        const trimmed = lines[i]?.trim() ?? "";
+        if (trimmed !== "" && !trimmed.startsWith("#"))
+            break;
+    }
+    return lines.slice(i).join("\n").trimEnd() + "\n";
+}
+export function wireHuskyPrePush(root) {
+    const huskyDir = join(root, ".husky");
+    if (!existsSync(huskyDir))
+        return "no-husky";
+    const path = join(huskyDir, "pre-push");
+    const template = shippedPrePushTemplate();
+    if (!existsSync(path)) {
+        writeFileSync(path, template);
+        chmodSync(path, 0o755);
+        return "created";
+    }
+    const existing = readFileSync(path, "utf8");
+    if (existing.includes(PRE_PUSH_MARKER))
+        return "already-wired";
+    const marker = "# --- LaneKeeper (appended by `lanekeeper init`) — see node_modules/lanekeeper/hooks/pre-push for the full comments ---";
+    appendFileSync(path, `\n${marker}\n${functionalSnippet(template)}`);
+    chmodSync(path, 0o755);
+    return "merged";
+}
+/**
+ * A `.husky/pre-push` file on disk enforces nothing on its own — git only
+ * runs it if `core.hooksPath` points somewhere that resolves to it, which is
+ * normally set as a side effect of the package manager's install step
+ * (husky's own `prepare` script). On a freshly cloned repo where nobody's
+ * run that install yet — the exact state Quickstart leaves you in right
+ * after `init` — the file is silently inert and a direct push sails through
+ * uncontested. Since LaneKeeper is the one promising "pushes are gated now,"
+ * it sets this itself instead of depending on a step that may not have
+ * happened yet, mirroring exactly what `husky install` itself does.
+ *
+ * Husky v9 changed its own convention mid-flight: v6–v8 point
+ * core.hooksPath directly at `.husky` (hook files run as-is); v9 points it
+ * at `.husky/_`, a generated wrapper directory that then execs the real
+ * `.husky/<hookname>` file. Both are legitimate, already-correct setups —
+ * only treat something OTHER than either as a deliberate custom path worth
+ * warning about. `.husky/_` doesn't exist yet on the fresh-clone/no-install
+ * case this function exists for, so `.husky` remains the right thing to set
+ * when nothing's configured at all; if the project turns out to be v9,
+ * husky's own next real install corrects it to `.husky/_`.
+ */
+export function ensureHooksPath(root) {
+    let current;
+    try {
+        current = execFileSync("git", ["config", "core.hooksPath"], { cwd: root, encoding: "utf8" }).trim();
+    }
+    catch {
+        current = null; // unset
+    }
+    if (current === ".husky" || current === ".husky/_")
+        return "already-set";
+    if (current)
+        return "custom-path"; // respect an existing deliberate setup — don't override it
+    execFileSync("git", ["config", "core.hooksPath", ".husky"], { cwd: root });
+    return "set";
+}

package/dist/preview.d.ts

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

package/dist/preview.js

@@ -0,0 +1,119 @@
+/**
+ * preview.ts — instantly preview a lane's working tree on the ONE shared dev
+ * server, no build, no deploy.
+ *
+ * A hosted preview deployment is too slow for "let me glance at this." A dev
+ * server is just files on disk being watched by your framework's bundler —
+ * so this copies a lane's working tree (including uncommitted changes,
+ * exactly what's being iterated on) straight onto the MAIN checkout. The
+ * bundler picks up the change and hot-reloads in seconds.
+ *
+ * This is framework-agnostic by construction: it's an rsync, not a build
+ * step, so it has no opinion about Next.js, Vite, or anything else — your
+ * own dev server does the actual watching and reloading. The one place a
+ * framework's fingerprints show up is `buildOutputDirs` in your config
+ * (never copy someone's stale ".next" or "dist" over a live checkout).
+ *
+ *   lanekeeper preview            from a lane worktree — swap the dev server
+ *                                 to show THIS lane's current working tree.
+ *   lanekeeper preview --restore  from anywhere — put the dev server back on
+ *                                 the integration branch's real HEAD.
+ *
+ * Safety:
+ *   - Refuses to start a new preview if the MAIN checkout isn't clean (a
+ *     previous preview wasn't restored, or it has real local changes) —
+ *     never silently overwrites unknown state.
+ *   - Additive only (no rsync --delete): a file the lane DELETED won't show
+ *     up deleted in the preview. Deleting untracked files in a live checkout
+ *     with no git record to recover them isn't a risk worth taking for a
+ *     "quick look" tool — this only ever adds or modifies files.
+ *   - Exact restore, not a guessed `git clean`: every newly-created
+ *     untracked path introduced by the swap is recorded in a manifest up
+ *     front, and restore removes precisely those paths, then
+ *     `git checkout -- .` to revert every modified TRACKED file to HEAD.
+ *   - Never touches .git, node_modules, build output, or env files in the
+ *     target — only the source tree itself moves.
+ */
+import { execSync, execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, unlinkSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveMainCheckout } from "./lib/main-checkout.js";
+import { loadConfig } from "./lib/config.js";
+const DIM = "\x1b[2m", RESET = "\x1b[0m", RED = "\x1b[31m", GREEN = "\x1b[32m";
+// Always excluded, regardless of framework — never rsync git internals,
+// dependencies, or secrets over a live checkout.
+const BASE_EXCLUDES = [".git", "node_modules", ".env", ".env.local"];
+function gitStatus(dir) {
+    return execFileSync("git", ["status", "--porcelain"], { cwd: dir, encoding: "utf8" });
+}
+function restore(target, manifestPath) {
+    if (!existsSync(manifestPath)) {
+        console.log(`${DIM}preview: no active preview to restore.${RESET}`);
+        return;
+    }
+    const { addedPaths } = JSON.parse(readFileSync(manifestPath, "utf8"));
+    console.log(`${DIM}reverting tracked-file changes on the dev checkout…${RESET}`);
+    execFileSync("git", ["checkout", "--", "."], { cwd: target, stdio: "inherit" });
+    for (const p of addedPaths) {
+        rmSync(join(target, p), { recursive: true, force: true });
+    }
+    unlinkSync(manifestPath);
+    const head = execFileSync("git", ["rev-parse", "--short", "HEAD"], { cwd: target, encoding: "utf8" }).trim();
+    console.log(`${GREEN}✓ dev server restored to HEAD @ ${head}.${RESET}`);
+}
+function preview(source, target, manifestPath, excludes) {
+    if (source === target) {
+        console.error("lanekeeper preview: refusing to run from the dev-server checkout itself — run this from a lane worktree.");
+        process.exit(1);
+    }
+    if (existsSync(manifestPath)) {
+        console.error(`${RED}preview: a preview is already active on the dev server.${RESET} Run 'lanekeeper preview --restore' first.`);
+        process.exit(1);
+    }
+    const before = gitStatus(target);
+    if (before.trim() !== "") {
+        console.error(`${RED}preview: the dev-server checkout isn't clean — refusing to swap over unknown local changes.${RESET}`);
+        console.error(before);
+        process.exit(1);
+    }
+    const branch = execFileSync("git", ["-C", source, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" }).trim();
+    console.log(`${DIM}copying ${branch}'s working tree onto the dev server…${RESET}`);
+    const rsyncArgs = ["-a", ...excludes.flatMap((e) => ["--exclude", e]), `${source}/`, `${target}/`];
+    const rsync = spawnSync("rsync", rsyncArgs, { stdio: "inherit" });
+    if (rsync.status !== 0) {
+        console.error(`${RED}preview: rsync failed.${RESET}`);
+        process.exit(1);
+    }
+    const after = gitStatus(target);
+    const addedPaths = after
+        .split("\n")
+        .filter((l) => l.startsWith("??"))
+        .map((l) => l.slice(3).trim());
+    writeFileSync(manifestPath, JSON.stringify({ branch, addedPaths }, null, 2));
+    console.log(`${GREEN}✓ dev server now showing ${branch}.${RESET} Refresh the browser.`);
+    console.log(`${DIM}Run 'lanekeeper preview --restore' when done.${RESET}`);
+}
+export async function runPreview(args) {
+    const source = process.cwd();
+    const target = resolveMainCheckout(source);
+    const manifestPath = join(tmpdir(), `lanekeeper-preview-manifest-${createHash("sha1").update(target).digest("hex").slice(0, 12)}.json`);
+    // Fail fast and legibly if rsync isn't available, rather than a cryptic
+    // spawn ENOENT partway through copying files.
+    try {
+        execSync("command -v rsync", { stdio: "ignore" });
+    }
+    catch {
+        console.error("lanekeeper preview: rsync is required and wasn't found on PATH.");
+        process.exit(1);
+    }
+    if (args.includes("--restore")) {
+        restore(target, manifestPath);
+    }
+    else {
+        const cfg = await loadConfig(source);
+        const excludes = [...BASE_EXCLUDES, ...cfg.buildOutputDirs];
+        preview(source, target, manifestPath, excludes);
+    }
+}

package/dist/promote.d.ts

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

package/dist/promote.js

@@ -0,0 +1,77 @@
+/**
+ * promote.ts — ship the integration branch to production by fast-forwarding
+ * origin/<productionBranch> to origin/<integrationBranch>.
+ *
+ * This is the one command in LaneKeeper that's deliberately NOT part of the
+ * automated workflow. Agents land on `integrationBranch` continuously and
+ * autonomously (see the CLAUDE.md workflow section `lanekeeper init` writes) —
+ * production only moves when a human decides to run this. If your
+ * lanekeeper.config has no `productionBranch` set, there's nothing to
+ * promote: `integrationBranch` already IS production, and this is a no-op.
+ *
+ *   Usage:  lanekeeper promote   (run from anywhere in the repo)
+ *
+ * Safe by construction:
+ *   - Fetches first, then verifies origin/productionBranch is an ANCESTOR of
+ *     origin/integrationBranch — a pure fast-forward, linear history, no
+ *     merge commit. If production has commits not on the integration branch
+ *     (someone pushed it directly), it ABORTS rather than force anything.
+ *   - No local checkout needed: pushes the remote ref straight across.
+ *   - --no-verify on the push: every commit on the integration branch
+ *     already passed the full pre-push check when it landed, so re-running
+ *     that suite here is pure waste. Your own CI still gates whatever runs
+ *     on the production branch on its side.
+ *   - Nothing to promote (already equal) → reports and exits 0.
+ */
+import { execFileSync } from "node:child_process";
+import { hasConfig, loadConfig } from "./lib/config.js";
+function git(args, { allowFail = false } = {}) {
+    try {
+        return { ok: true, out: execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim() };
+    }
+    catch (e) {
+        const err = e;
+        if (!allowFail)
+            throw e;
+        return { ok: false, out: `${err.stdout ?? ""}${err.stderr ?? ""}`.trim() };
+    }
+}
+export async function promote() {
+    if (!hasConfig()) {
+        console.error("lanekeeper promote: no lanekeeper.config found at the repo root.");
+        return 1;
+    }
+    const cfg = await loadConfig();
+    if (!cfg.productionBranch) {
+        console.log(`lanekeeper promote: no productionBranch configured — '${cfg.integrationBranch}' already IS production. Nothing to do.`);
+        return 0;
+    }
+    const { integrationBranch, productionBranch } = cfg;
+    git(["fetch", "origin", "--quiet"], { allowFail: true });
+    const prod = git(["rev-parse", `origin/${productionBranch}`], { allowFail: true });
+    const integ = git(["rev-parse", `origin/${integrationBranch}`], { allowFail: true });
+    if (!prod.ok || !integ.ok) {
+        console.error(`lanekeeper promote: could not resolve origin/${productionBranch} or origin/${integrationBranch} — are both branches created and fetched?`);
+        return 1;
+    }
+    if (prod.out === integ.out) {
+        console.log(`lanekeeper promote: ${productionBranch} already at ${integrationBranch} (${integ.out.slice(0, 7)}) — nothing to ship.`);
+        return 0;
+    }
+    // Pure fast-forward only: origin/productionBranch must be an ancestor of
+    // origin/integrationBranch.
+    const ff = git(["merge-base", "--is-ancestor", `origin/${productionBranch}`, `origin/${integrationBranch}`], { allowFail: true });
+    if (!ff.ok) {
+        console.error(`lanekeeper promote: origin/${productionBranch} has commits NOT on origin/${integrationBranch} — history has diverged.\n` +
+            `Someone pushed ${productionBranch} directly. Reconcile manually before promoting.\n` +
+            "Left untouched — refusing to force-push production.");
+        return 1;
+    }
+    const push = git(["push", "--no-verify", "origin", `origin/${integrationBranch}:${productionBranch}`], { allowFail: true });
+    if (!push.ok) {
+        console.error(`lanekeeper promote: push to ${productionBranch} FAILED — production NOT updated.\n${push.out}`);
+        return 1;
+    }
+    console.log(`lanekeeper promote: shipped ${integrationBranch} → ${productionBranch}  ${prod.out.slice(0, 7)} → ${integ.out.slice(0, 7)}`);
+    return 0;
+}

package/dist/sync.d.ts

@@ -0,0 +1,2 @@
+/** Fast-forwards the MAIN checkout. Returns a process exit code; never throws. */
+export declare function sync(): Promise<number>;