@repo-os/repoos 0.5.45

package/dist/core/tunnel-registry.js

@@ -0,0 +1,267 @@
+/**
+ * Machine-level tunnel app registry.
+ *
+ * `cloudflared` on a machine runs as ONE system service reading ONE ingress
+ * config — but each RepoOS repo checkout only knows about its own
+ * `repoos.toml [tunnel.apps.*]`. Without a shared machine view, the second
+ * repo to `repoos tunnel install` clobbers the first repo's ingress routes.
+ *
+ * This registry (`~/.config/repoos/tunnel-apps.toml` by default) is the
+ * union of every repo's published apps on this box, keyed by app name, each
+ * entry tagged with the repo checkout (`ownerRoot`) that contributed it.
+ * `repoos.toml [tunnel.apps.*]` in each repo stays the per-repo, git-tracked
+ * source of truth for that repo's own apps — this file is a derived,
+ * machine-local cache that `repoos tunnel install`/`start` render the actual
+ * `cloudflared` ingress from, so bringing up the service from ANY repo on the
+ * machine serves every app published by any repo.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseToml, tomlQuote } from "./tunnel.js";
+export function emptyRegistry() {
+    return { tunnelId: "", tunnelName: "", domain: "", apps: {} };
+}
+/** Default location — one registry per machine, outside any repo. */
+export function registryPath() {
+    return join(homedir(), ".config", "repoos", "tunnel-apps.toml");
+}
+export function parseRegistry(text) {
+    const root = parseToml(text);
+    const reg = emptyRegistry();
+    if (typeof root.tunnel_id === "string")
+        reg.tunnelId = root.tunnel_id;
+    if (typeof root.tunnel_name === "string")
+        reg.tunnelName = root.tunnel_name;
+    if (typeof root.domain === "string")
+        reg.domain = root.domain;
+    const rawApps = (root.apps ?? {});
+    for (const [name, a] of Object.entries(rawApps)) {
+        if (typeof a !== "object" || a === null)
+            continue;
+        const hostname = String(a.hostname ?? "");
+        const service = String(a.service ?? "");
+        // A corrupt/partial entry (hand-edited despite the "do not" header, or
+        // written by some future bug) must never reach `renderCloudflaredConfig`
+        // — an empty hostname/service would render a blank ingress rule into
+        // cloudflared's config. Drop it rather than pass it through silently.
+        if (!hostname || !service)
+            continue;
+        reg.apps[name] = {
+            hostname,
+            service,
+            access: Array.isArray(a.access) ? a.access.map(String) : [],
+            ...(a.noAccess === true ? { noAccess: true } : {}),
+            ownerRoot: String(a.ownerRoot ?? ""),
+        };
+    }
+    return reg;
+}
+export function serializeRegistry(reg) {
+    const lines = [];
+    lines.push("# Generated by repoos tunnel — machine-level registry of every repo's published apps on this box.");
+    lines.push("# Do not hand-edit; see docs/tunnel-registry.md.");
+    if (reg.tunnelId)
+        lines.push(`tunnel_id = ${tomlQuote(reg.tunnelId)}`);
+    if (reg.tunnelName)
+        lines.push(`tunnel_name = ${tomlQuote(reg.tunnelName)}`);
+    if (reg.domain)
+        lines.push(`domain = ${tomlQuote(reg.domain)}`);
+    for (const name of Object.keys(reg.apps).sort()) {
+        const app = reg.apps[name];
+        lines.push("");
+        lines.push(`[apps.${name}]`);
+        lines.push(`hostname = ${tomlQuote(app.hostname)}`);
+        lines.push(`service = ${tomlQuote(app.service)}`);
+        lines.push(`access = [${app.access.map(tomlQuote).join(", ")}]`);
+        if (app.noAccess)
+            lines.push(`noAccess = true`);
+        lines.push(`ownerRoot = ${tomlQuote(app.ownerRoot)}`);
+    }
+    return lines.join("\n") + "\n";
+}
+/** Read the machine registry. Missing file reads as an empty registry. */
+export function readRegistry(path = registryPath()) {
+    const text = existsSync(path) ? readFileSync(path, "utf8") : "";
+    return parseRegistry(text);
+}
+/**
+ * Persist the machine registry (0600 — same treatment as the derived ingress
+ * config). Writes to a sibling temp file and renames it over the real path
+ * (atomic on POSIX) so a concurrent reader (another repo's `tunnel list`, or
+ * this same read done mid-write) never observes a truncated/partial file.
+ */
+export function writeRegistry(reg, path = registryPath()) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, serializeRegistry(reg), { encoding: "utf8", mode: 0o600 });
+    renameSync(tmp, path);
+}
+const LOCK_RETRY_MS = 25;
+const LOCK_STALE_MS = 5_000;
+/** Block the calling thread for `ms` without busy-spinning (a real syscall wait). */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Hold an exclusive lock on the registry while running `fn`. Two `repoos
+ * tunnel` processes on the same machine — the exact scenario this registry
+ * exists for — can otherwise race a read-modify-write and silently drop one
+ * another's change (last write wins). A sibling `<path>.lock` file created
+ * with the atomic create-if-absent (`wx`) flag serves as a simple
+ * cross-process mutex: a lock older than {@link LOCK_STALE_MS} is assumed to
+ * be left behind by a crashed process and is stolen rather than waited on
+ * forever.
+ */
+export function withRegistryLock(path, fn) {
+    const lockPath = `${path}.lock`;
+    mkdirSync(dirname(path), { recursive: true });
+    const start = Date.now();
+    for (;;) {
+        try {
+            closeSync(openSync(lockPath, "wx"));
+            break;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            if (Date.now() - start > LOCK_STALE_MS) {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    // another waiter already stole/removed it — just retry the create
+                }
+                continue;
+            }
+            sleepSync(LOCK_RETRY_MS);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            // already gone (shouldn't happen — we're the holder)
+        }
+    }
+}
+/**
+ * Reconcile a repo's tunnel identity against the registry's. A machine runs
+ * ONE Cloudflare Tunnel, so if the registry already has an identity and this
+ * repo's disagrees, refuse rather than silently picking one — returns an
+ * error message. When the registry has no identity yet, adopts the repo's
+ * (mutates `reg` in place). No-ops when the repo itself isn't set up yet.
+ */
+export function reconcileIdentity(reg, tunnel) {
+    if (!tunnel.tunnelId)
+        return null;
+    if (!reg.tunnelId) {
+        reg.tunnelId = tunnel.tunnelId;
+        reg.tunnelName = tunnel.name;
+        if (!reg.domain)
+            reg.domain = tunnel.domain;
+        return null;
+    }
+    if (reg.tunnelId !== tunnel.tunnelId) {
+        return (`This repo's tunnel (${tunnel.name || "unnamed"}, ${tunnel.tunnelId}) does not match ` +
+            `the machine's registered tunnel (${reg.tunnelName || "unnamed"}, ${reg.tunnelId}). ` +
+            `A machine runs ONE Cloudflare Tunnel — \`repoos tunnel setup\` reuses a tunnel by NAME, ` +
+            `so it won't join this one unless the names happen to match. To join it, edit this repo's ` +
+            `repoos.toml [tunnel] block by hand: set tunnel_id = ${tomlQuote(reg.tunnelId)}` +
+            (reg.tunnelName ? ` and name = ${tomlQuote(reg.tunnelName)}` : "") +
+            `, or resolve the conflict the other way in ${registryPath()}.`);
+    }
+    return null;
+}
+/** Add or replace a registry entry, tagging it with its owning repo. */
+export function upsertApp(reg, name, app, ownerRoot) {
+    reg.apps[name] = { ...app, ownerRoot };
+}
+/** Remove a registry entry (no-ops when absent). */
+export function removeApp(reg, name) {
+    delete reg.apps[name];
+}
+/** Strip `ownerRoot` back to plain `TunnelApp`s — the shape `renderCloudflaredConfig` expects. */
+export function unionApps(reg) {
+    const out = {};
+    for (const [name, app] of Object.entries(reg.apps)) {
+        out[name] = {
+            hostname: app.hostname,
+            service: app.service,
+            access: app.access,
+            ...(app.noAccess ? { noAccess: true } : {}),
+        };
+    }
+    return out;
+}
+/**
+ * Reconcile the registry against THIS repo's own `repoos.toml [tunnel.apps]`
+ * — still the git-tracked, hand-edited source of truth for the apps this
+ * repo publishes. Mutates `reg` in place and returns the names that were
+ * newly seeded (for the same one-time log line callers have always printed).
+ * Three cases, keyed entirely on `ownerRoot` so another repo's entries are
+ * never touched:
+ *
+ *  - in `tunnel.apps`, missing from the registry → seed it (first run after
+ *    upgrade, or a brand-new `create` on an otherwise-synced registry).
+ *  - in `tunnel.apps` AND already registered under THIS repo's `ownerRoot`,
+ *    but with different fields (hostname/port/access edited by hand in
+ *    repoos.toml rather than through `repoos tunnel`) → overwrite the
+ *    registry entry so it can't drift from the file that's supposed to be
+ *    authoritative for it.
+ *  - registered under THIS repo's `ownerRoot` but no longer in `tunnel.apps`
+ *    (deleted by hand rather than via `repoos tunnel destroy`) → drop it,
+ *    since this repo no longer declares it.
+ *
+ * An entry owned by a DIFFERENT repo is left alone in every case, even when
+ * this repo's own `tunnel.apps` happens to declare the same name (a
+ * pre-existing collision — surfaced to the user elsewhere, not silently
+ * resolved here).
+ *
+ * Deliberately per-app rather than gated on "registry is totally empty": on
+ * a machine with multiple PRE-EXISTING repos (each already publishing its
+ * own apps before this registry existed), each repo seeds its own apps into
+ * the registry the first time IT runs `create`/`install`/`start`, regardless
+ * of whether another repo got there first and seeded its own — that's
+ * exactly the scenario (celleris + dev on one tunnel) this registry exists
+ * to fix. For the common single-repo case this still behaves like a
+ * one-time full migration, since every app is missing on the first run and
+ * every run after that is a no-op unless repoos.toml itself changed.
+ */
+export function syncFromRepo(reg, tunnel, root) {
+    const seeded = [];
+    for (const [name, app] of Object.entries(tunnel.apps)) {
+        const existing = reg.apps[name];
+        if (!existing) {
+            reg.apps[name] = { ...app, ownerRoot: root };
+            seeded.push(name);
+            continue;
+        }
+        if (existing.ownerRoot !== root)
+            continue; // another repo's entry — never touched here
+        const { ownerRoot: _ownerRoot, ...current } = existing;
+        if (JSON.stringify(current) !== JSON.stringify(app)) {
+            reg.apps[name] = { ...app, ownerRoot: root };
+        }
+    }
+    for (const [name, existing] of Object.entries(reg.apps)) {
+        if (existing.ownerRoot === root && !tunnel.apps[name]) {
+            delete reg.apps[name];
+        }
+    }
+    return seeded;
+}
+/** Every registry app, sorted by name, annotated with staleness. */
+export function annotateStale(reg) {
+    return Object.entries(reg.apps)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, app]) => ({
+        name,
+        app,
+        stale: !!app.ownerRoot && !existsSync(app.ownerRoot),
+    }));
+}

package/dist/core/tunnel-registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/tunnel-registry.test.js

@@ -0,0 +1,309 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { existsSync, mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { emptyTunnelConfig, renderCloudflaredConfig } from "./tunnel.js";
+import { annotateStale, emptyRegistry, parseRegistry, readRegistry, reconcileIdentity, removeApp, serializeRegistry, syncFromRepo, unionApps, upsertApp, withRegistryLock, writeRegistry, } from "./tunnel-registry.js";
+const dirs = [];
+afterEach(() => {
+    for (const d of dirs)
+        rmSync(d, { recursive: true, force: true });
+    dirs.length = 0;
+});
+function tmpDir(prefix) {
+    const d = mkdtempSync(join(tmpdir(), prefix));
+    dirs.push(d);
+    return d;
+}
+function tunnelWithApps(tunnelId, name, apps) {
+    return { ...emptyTunnelConfig(), tunnelId, name, apps };
+}
+describe("registry parse/serialize round-trip", () => {
+    it("round-trips identity and apps through TOML", () => {
+        const reg = {
+            tunnelId: "tunnel-abc",
+            tunnelName: "repoos-bee",
+            domain: "repoos.org",
+            apps: {
+                dashboard: {
+                    hostname: "dashboard.repoos.org",
+                    service: "http://localhost:3000",
+                    access: ["alice@example.com"],
+                    ownerRoot: "/repos/a",
+                },
+                dev: {
+                    hostname: "dev.repoos.org",
+                    service: "http://localhost:7171",
+                    access: [],
+                    noAccess: true,
+                    ownerRoot: "/repos/b",
+                },
+            },
+        };
+        const parsed = parseRegistry(serializeRegistry(reg));
+        expect(parsed).toEqual(reg);
+    });
+    it("reads a missing file as an empty registry", () => {
+        const dir = tmpDir("repoos-registry-missing-");
+        const reg = readRegistry(join(dir, "does-not-exist.toml"));
+        expect(reg).toEqual(emptyRegistry());
+    });
+    it("persists and re-reads via an explicit path", () => {
+        const dir = tmpDir("repoos-registry-io-");
+        const path = join(dir, "tunnel-apps.toml");
+        const reg = emptyRegistry();
+        reg.tunnelId = "t-1";
+        reg.tunnelName = "repoos-box";
+        upsertApp(reg, "dev", { hostname: "dev.repoos.org", service: "http://localhost:7171", access: [] }, "/repos/a");
+        writeRegistry(reg, path);
+        expect(readRegistry(path)).toEqual(reg);
+    });
+});
+describe("reconcileIdentity", () => {
+    it("adopts the repo's identity when the registry has none yet", () => {
+        const reg = emptyRegistry();
+        const tunnel = tunnelWithApps("tunnel-1", "repoos-box", {});
+        tunnel.domain = "repoos.org";
+        const conflict = reconcileIdentity(reg, tunnel);
+        expect(conflict).toBeNull();
+        expect(reg.tunnelId).toBe("tunnel-1");
+        expect(reg.tunnelName).toBe("repoos-box");
+        expect(reg.domain).toBe("repoos.org");
+    });
+    it("no-ops when the repo isn't set up yet (no tunnelId)", () => {
+        const reg = emptyRegistry();
+        reg.tunnelId = "existing";
+        const tunnel = tunnelWithApps("", "", {});
+        expect(reconcileIdentity(reg, tunnel)).toBeNull();
+        expect(reg.tunnelId).toBe("existing");
+    });
+    it("passes silently when the repo's identity matches the registry's", () => {
+        const reg = emptyRegistry();
+        reg.tunnelId = "tunnel-1";
+        reg.tunnelName = "repoos-box";
+        const tunnel = tunnelWithApps("tunnel-1", "repoos-box", {});
+        expect(reconcileIdentity(reg, tunnel)).toBeNull();
+    });
+    it("refuses (never silently picks one) when tunnelIds disagree", () => {
+        const reg = emptyRegistry();
+        reg.tunnelId = "tunnel-1";
+        reg.tunnelName = "repoos-box";
+        const tunnel = tunnelWithApps("tunnel-2", "repoos-other", {});
+        const conflict = reconcileIdentity(reg, tunnel);
+        expect(conflict).toMatch(/does not match/);
+        expect(conflict).toContain("tunnel-1");
+        expect(conflict).toContain("tunnel-2");
+        // registry identity must be left untouched
+        expect(reg.tunnelId).toBe("tunnel-1");
+    });
+});
+describe("syncFromRepo (seed / update / drop)", () => {
+    it("seeds every app from an empty registry (single pre-existing repo)", () => {
+        const reg = emptyRegistry();
+        const tunnel = tunnelWithApps("tunnel-1", "repoos-box", {
+            dashboard: { hostname: "dashboard.repoos.org", service: "http://localhost:3000", access: [] },
+            api: { hostname: "api.repoos.org", service: "http://localhost:4000", access: [] },
+        });
+        const seeded = syncFromRepo(reg, tunnel, "/repos/a");
+        expect(seeded.sort()).toEqual(["api", "dashboard"]);
+        expect(reg.apps.dashboard).toMatchObject({
+            hostname: "dashboard.repoos.org",
+            ownerRoot: "/repos/a",
+        });
+        expect(reg.apps.api).toMatchObject({ hostname: "api.repoos.org", ownerRoot: "/repos/a" });
+    });
+    it("is a no-op on a second call — never re-seeds or duplicates", () => {
+        const reg = emptyRegistry();
+        const tunnel = tunnelWithApps("tunnel-1", "repoos-box", {
+            dashboard: { hostname: "dashboard.repoos.org", service: "http://localhost:3000", access: [] },
+        });
+        syncFromRepo(reg, tunnel, "/repos/a");
+        const secondPass = syncFromRepo(reg, tunnel, "/repos/a");
+        expect(secondPass).toEqual([]);
+        expect(Object.keys(reg.apps)).toEqual(["dashboard"]);
+    });
+    it("seeds a SECOND pre-existing repo's own apps without touching the first repo's", () => {
+        // The exact "celleris + dev" bug scenario: two repos already publishing
+        // apps before this registry existed. Repo A migrates first...
+        const reg = emptyRegistry();
+        const repoA = tunnelWithApps("tunnel-1", "repoos-box", {
+            celleris: { hostname: "celleris.repoos.org", service: "http://localhost:3000", access: [] },
+        });
+        syncFromRepo(reg, repoA, "/repos/celleris");
+        // ...then repo B, independently, also has its own pre-existing app that
+        // was never in the registry. It must get folded in too, not skipped
+        // just because the registry is no longer empty.
+        const repoB = tunnelWithApps("tunnel-1", "repoos-box", {
+            dev: { hostname: "dev.repoos.org", service: "http://localhost:7171", access: [] },
+        });
+        const seeded = syncFromRepo(reg, repoB, "/repos/dev");
+        expect(seeded).toEqual(["dev"]);
+        expect(reg.apps.celleris).toMatchObject({ ownerRoot: "/repos/celleris" });
+        expect(reg.apps.dev).toMatchObject({ ownerRoot: "/repos/dev" });
+    });
+    it("never overwrites an entry owned by a different repo", () => {
+        const reg = emptyRegistry();
+        upsertApp(reg, "dev", { hostname: "dev.repoos.org", service: "http://localhost:7171", access: [] }, "/repos/a");
+        const tunnel = tunnelWithApps("tunnel-1", "repoos-box", {
+            dev: { hostname: "dev-imposter.repoos.org", service: "http://localhost:9999", access: [] },
+        });
+        const seeded = syncFromRepo(reg, tunnel, "/repos/b");
+        expect(seeded).toEqual([]);
+        expect(reg.apps.dev).toMatchObject({ hostname: "dev.repoos.org", ownerRoot: "/repos/a" });
+    });
+    it("re-upserts an entry it owns when repoos.toml changed (port/hostname edited by hand)", () => {
+        const reg = emptyRegistry();
+        const tunnel = tunnelWithApps("tunnel-1", "repoos-box", {
+            dashboard: { hostname: "dashboard.repoos.org", service: "http://localhost:3000", access: [] },
+        });
+        syncFromRepo(reg, tunnel, "/repos/a");
+        // repoos.toml is hand-edited (or re-created via `create`) to a new port —
+        // a stale registry copy must not survive a second sync from its own repo.
+        tunnel.apps.dashboard.service = "http://localhost:4000";
+        const seeded = syncFromRepo(reg, tunnel, "/repos/a");
+        expect(seeded).toEqual([]); // not newly seeded — updated in place
+        expect(reg.apps.dashboard).toMatchObject({
+            service: "http://localhost:4000",
+            ownerRoot: "/repos/a",
+        });
+    });
+    it("drops an entry it owns once repoos.toml no longer declares it", () => {
+        const reg = emptyRegistry();
+        const tunnel = tunnelWithApps("tunnel-1", "repoos-box", {
+            dashboard: { hostname: "dashboard.repoos.org", service: "http://localhost:3000", access: [] },
+        });
+        syncFromRepo(reg, tunnel, "/repos/a");
+        delete tunnel.apps.dashboard; // hand-deleted from repoos.toml, not via `destroy`
+        syncFromRepo(reg, tunnel, "/repos/a");
+        expect(reg.apps.dashboard).toBeUndefined();
+    });
+    it("never touches or drops another repo's entries even when this repo's toml is empty", () => {
+        const reg = emptyRegistry();
+        upsertApp(reg, "other", { hostname: "other.repoos.org", service: "http://localhost:9000", access: [] }, "/repos/b");
+        const tunnel = tunnelWithApps("tunnel-1", "repoos-box", {});
+        syncFromRepo(reg, tunnel, "/repos/a");
+        expect(reg.apps.other).toMatchObject({ ownerRoot: "/repos/b" });
+    });
+});
+describe("parseRegistry — corrupt entries", () => {
+    it("drops an entry with an empty hostname or service rather than rendering a blank rule", () => {
+        const text = [
+            'tunnel_id = "tunnel-1"',
+            "",
+            "[apps.good]",
+            'hostname = "good.repoos.org"',
+            'service = "http://localhost:3000"',
+            "access = []",
+            'ownerRoot = "/repos/a"',
+            "",
+            "[apps.corrupt]",
+            'hostname = ""',
+            'service = "http://localhost:4000"',
+            "access = []",
+            'ownerRoot = "/repos/a"',
+        ].join("\n");
+        const reg = parseRegistry(text);
+        expect(Object.keys(reg.apps)).toEqual(["good"]);
+    });
+});
+describe("withRegistryLock", () => {
+    it("runs the callback and releases the lock file afterward", () => {
+        const dir = tmpDir("repoos-registry-lock-");
+        const path = join(dir, "tunnel-apps.toml");
+        const result = withRegistryLock(path, () => 42);
+        expect(result).toBe(42);
+        expect(existsSync(`${path}.lock`)).toBe(false);
+    });
+    it("releases the lock even when the callback throws", () => {
+        const dir = tmpDir("repoos-registry-lock-throw-");
+        const path = join(dir, "tunnel-apps.toml");
+        expect(() => withRegistryLock(path, () => {
+            throw new Error("boom");
+        })).toThrow("boom");
+        expect(existsSync(`${path}.lock`)).toBe(false);
+    });
+    it("serializes a read-modify-write so neither writer's entry is lost", () => {
+        // The exact race this lock exists to prevent: two "processes" (here,
+        // just two sequential calls, since a true concurrent-process test would
+        // need real subprocesses) each read, add their own app, and write —
+        // without the lock this pattern is exactly how a naive read/mutate/write
+        // loses an entry. Locking each one's full cycle assures nothing overlaps.
+        const dir = tmpDir("repoos-registry-lock-race-");
+        const path = join(dir, "tunnel-apps.toml");
+        writeRegistry(emptyRegistry(), path);
+        function addOne(name, root) {
+            withRegistryLock(path, () => {
+                const reg = readRegistry(path);
+                upsertApp(reg, name, { hostname: `${name}.repoos.org`, service: "http://localhost:1", access: [] }, root);
+                writeRegistry(reg, path);
+            });
+        }
+        addOne("a", "/repos/a");
+        addOne("b", "/repos/b");
+        const final = readRegistry(path);
+        expect(Object.keys(final.apps).sort()).toEqual(["a", "b"]);
+    });
+});
+describe("unionApps + renderCloudflaredConfig (the actual fix)", () => {
+    it("two repos' apps both survive a single render — neither clobbers the other", () => {
+        const reg = emptyRegistry();
+        reg.tunnelId = "tunnel-1";
+        upsertApp(reg, "celleris", { hostname: "celleris.repoos.org", service: "http://localhost:3000", access: [] }, "/repos/celleris");
+        upsertApp(reg, "dev", { hostname: "dev.repoos.org", service: "http://localhost:7171", access: [] }, "/repos/dev");
+        const yaml = renderCloudflaredConfig({ ...emptyTunnelConfig(), tunnelId: reg.tunnelId, apps: unionApps(reg) }, "/home/user/.cloudflared/tunnel-1.json");
+        expect(yaml).toContain("hostname: celleris.repoos.org");
+        expect(yaml).toContain("hostname: dev.repoos.org");
+        expect(yaml.trim().endsWith("- service: http_status:404")).toBe(true);
+    });
+    it("installing from repo B after repo A no longer drops repo A's route", () => {
+        // Simulates: repo A creates its app (registry seeded with A's app), then
+        // repo B runs `install` — B's own syncFromRepo pass must not remove A's
+        // entry, and the union render must still contain both.
+        const reg = emptyRegistry();
+        reg.tunnelId = "tunnel-1";
+        const repoA = tunnelWithApps("tunnel-1", "repoos-box", {
+            a: { hostname: "a.repoos.org", service: "http://localhost:1111", access: [] },
+        });
+        syncFromRepo(reg, repoA, "/repos/a");
+        const repoB = tunnelWithApps("tunnel-1", "repoos-box", {
+            b: { hostname: "b.repoos.org", service: "http://localhost:2222", access: [] },
+        });
+        syncFromRepo(reg, repoB, "/repos/b");
+        const apps = unionApps(reg);
+        expect(Object.keys(apps).sort()).toEqual(["a", "b"]);
+    });
+});
+describe("removeApp", () => {
+    it("removes an entry and leaves the rest untouched", () => {
+        const reg = emptyRegistry();
+        upsertApp(reg, "a", { hostname: "a.repoos.org", service: "http://localhost:1", access: [] }, "/repos/a");
+        upsertApp(reg, "b", { hostname: "b.repoos.org", service: "http://localhost:2", access: [] }, "/repos/b");
+        removeApp(reg, "a");
+        expect(Object.keys(reg.apps)).toEqual(["b"]);
+    });
+    it("no-ops on an absent name", () => {
+        const reg = emptyRegistry();
+        expect(() => removeApp(reg, "missing")).not.toThrow();
+    });
+});
+describe("annotateStale", () => {
+    it("flags entries whose ownerRoot no longer exists on disk", () => {
+        const dir = tmpDir("repoos-registry-stale-");
+        const liveRoot = join(dir, "live-repo");
+        mkdirSync(liveRoot);
+        const goneRoot = join(dir, "gone-repo"); // never created
+        const reg = emptyRegistry();
+        upsertApp(reg, "live", { hostname: "live.repoos.org", service: "http://localhost:1", access: [] }, liveRoot);
+        upsertApp(reg, "gone", { hostname: "gone.repoos.org", service: "http://localhost:2", access: [] }, goneRoot);
+        const rows = annotateStale(reg);
+        const byName = Object.fromEntries(rows.map((r) => [r.name, r.stale]));
+        expect(byName.live).toBe(false);
+        expect(byName.gone).toBe(true);
+    });
+    it("sorts by app name", () => {
+        const reg = emptyRegistry();
+        upsertApp(reg, "zebra", { hostname: "z.repoos.org", service: "http://localhost:1", access: [] }, "/repos/z");
+        upsertApp(reg, "alpha", { hostname: "a.repoos.org", service: "http://localhost:2", access: [] }, "/repos/a");
+        expect(annotateStale(reg).map((r) => r.name)).toEqual(["alpha", "zebra"]);
+    });
+});