@cedarjs/pg 0.1.0-alpha.1 → 0.2.0-alpha.0

package/dist/lifecycle-BOo6xBjD.mjs

@@ -0,0 +1,684 @@
+import { n as PASSWORD_SALT_PREFIX } from "./constants-NLR0U4NR.mjs";
+import { a as leaseDir, f as resolveWorktreeIdentity, i as isOrphanLease, l as readLease, n as envPath, r as forgetLease, s as listRegistryLeases, u as writeLease } from "./lease-BSBBpaR4.mjs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import pg from "pg";
+import { createConnection } from "node:net";
+//#region src/core/naming.ts
+const PG_MAX = 63;
+const PREFIX = "cpg_";
+/**
+* Build an observable Postgres database name:
+*   cpg_<repoSlug>_<worktreeSlug>_<mode>_<pathHash8>
+*
+* Never drops `mode` or `pathHash`. Truncates slugs to fit ≤63 chars.
+*/
+function buildDatabaseName(identity, mode) {
+	const modePart = mode;
+	const hashPart = identity.pathHash;
+	const fixed = 6 + modePart.length + 1 + hashPart.length;
+	let budget = PG_MAX - fixed;
+	if (budget < 2) return `${PREFIX}${modePart}_${hashPart}`.slice(0, PG_MAX);
+	let repo = identity.repoSlug;
+	let wt = identity.worktreeSlug;
+	while (repo.length + wt.length > budget) if (repo.length >= wt.length && repo.length > 1) repo = repo.slice(0, -1);
+	else if (wt.length > 1) wt = wt.slice(0, -1);
+	else break;
+	const name = `${PREFIX}${repo}_${wt}_${modePart}_${hashPart}`;
+	if (name.length > PG_MAX) return name.slice(0, PG_MAX);
+	return name;
+}
+function buildRoleName(databaseName) {
+	const suffix = "_role";
+	const maxBase = PG_MAX - 5;
+	return `${databaseName.slice(0, maxBase)}${suffix}`;
+}
+/**
+* Build a worker clone datname from a TEMPLATE database name.
+* Layout: `<template>_c_<suffix>` truncated to ≤63 chars (keeps suffix).
+*/
+function buildCloneDatabaseName(templateName, suffix) {
+	const safe = suffix.toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 24);
+	const tag = safe.length > 0 ? safe : "w";
+	const sep = "_c_";
+	const maxTemplate = PG_MAX - 3 - tag.length;
+	return `${templateName.slice(0, Math.max(1, maxTemplate))}${sep}${tag}`.slice(0, PG_MAX);
+}
+//#endregion
+//#region src/core/policy.ts
+/**
+* Inject DATABASE_URL (and TEST_DATABASE_URL for test mode) from a resolved URL.
+* Single env path for acquire, clone, and external-url skip.
+*/
+function applyDatabaseUrlEnv(databaseUrl, options = {}) {
+	process.env.DATABASE_URL = databaseUrl;
+	if ((options.mode ?? "test") === "test") process.env.TEST_DATABASE_URL = databaseUrl;
+}
+/**
+* Shared host skip+env gate for `acquireIfNeeded` / `cloneFromTemplateIfNeeded`.
+* On external-url skip, applies env when `setEnv` is not false.
+*/
+async function runIfNeeded(options, run) {
+	const skip = resolveAcquireSkip({
+		url: options.url,
+		force: options.force,
+		disabled: options.disabled
+	});
+	if (skip.skip) {
+		if (skip.reason === "external-url") {
+			if (options.setEnv !== false) applyDatabaseUrlEnv(skip.databaseUrl, { mode: options.mode });
+			return {
+				status: "skipped",
+				reason: "external-url",
+				databaseUrl: skip.databaseUrl
+			};
+		}
+		return {
+			status: "skipped",
+			reason: "disabled"
+		};
+	}
+	return {
+		status: "ran",
+		value: await run()
+	};
+}
+/**
+* True when the URL looks like a cedarpg provisioned database (`cpg_*` name/role).
+* These must never be treated as an external escape hatch; always re-acquire so
+* disposed/stale shell env cannot skip provisioning.
+*/
+function isCedarPgManagedUrl(url) {
+	if (!url || url.startsWith("file:")) return false;
+	try {
+		const parsed = new URL(url);
+		const databaseName = decodeURIComponent((parsed.pathname.replace(/^\//, "").split("?")[0] ?? "").trim());
+		const user = decodeURIComponent(parsed.username);
+		return databaseName.startsWith("cpg_") || user.startsWith("cpg_");
+	} catch {
+		return false;
+	}
+}
+/**
+* True when `url` still looks like an unset dotenv/template value
+* (e.g. `postgresql://{yourMachine}@localhost:5432/app_test` or
+* `postgresql://<user>@localhost/db`), not a real external database.
+*/
+function isUnsetTemplateUrl(url) {
+	if (/\{[^}]+\}/.test(url)) return true;
+	if (/<[^>]+>/.test(url)) return true;
+	return false;
+}
+/**
+* True when `url` is a real external database and acquire should be skipped.
+* Sqlite `file:` URLs, cedarpg `cpg_*` URLs, and unset template placeholders
+* are not external.
+*/
+function isExternalDatabaseEscapeHatch(url) {
+	if (!url) return false;
+	if (url.startsWith("file:")) return false;
+	if (isCedarPgManagedUrl(url)) return false;
+	if (isUnsetTemplateUrl(url)) return false;
+	return true;
+}
+/**
+* Decide whether acquire should run.
+* Adapters may call with no args (env defaults). Cedar opt-in should pass `disabled: false`
+* and the relevant `url` (`DATABASE_URL` or `TEST_DATABASE_URL`).
+*/
+function resolveAcquireSkip(input = {}) {
+	if (input.disabled ?? (process.env.CEDAR_PG === "0" || process.env.CEDAR_PG === "false")) return {
+		skip: true,
+		reason: "disabled"
+	};
+	if (input.force ?? process.env.CEDAR_PG_FORCE === "1") return { skip: false };
+	const url = input.url !== void 0 ? input.url : process.env.TEST_DATABASE_URL;
+	if (url && isExternalDatabaseEscapeHatch(url)) return {
+		skip: true,
+		reason: "external-url",
+		databaseUrl: url
+	};
+	return { skip: false };
+}
+//#endregion
+//#region src/providers/autopg.ts
+const INSTALL_HINT = "autopg is required. Install with:\n  curl -fsSL https://raw.githubusercontent.com/automagik-dev/autopg/main/install.sh | bash\nThen ensure ~/.local/bin is on PATH, or set AUTOPG_BIN.";
+/** Password scheme v2: sha256(PASSWORD_SALT_PREFIX + "\\0" + roleName) hex[:32]. Frozen for URL rebuild. */
+const ROLE_PASSWORD_SCHEME = "v2";
+function candidateBins() {
+	const out = [];
+	if (process.env.AUTOPG_BIN) out.push(process.env.AUTOPG_BIN);
+	out.push("autopg");
+	out.push(join(homedir(), ".local", "bin", "autopg"));
+	return out;
+}
+function resolveAutopgBin() {
+	for (const bin of candidateBins()) {
+		if (bin === "autopg") {
+			const which = spawnSync("which", ["autopg"], { encoding: "utf8" });
+			if (which.status === 0 && which.stdout.trim()) return which.stdout.trim();
+			continue;
+		}
+		if (existsSync(bin)) return bin;
+	}
+	return null;
+}
+function requireAutopgBin() {
+	const bin = resolveAutopgBin();
+	if (!bin) throw new Error(INSTALL_HINT);
+	return bin;
+}
+/**
+* Parse `autopg status --json` output. Requires a numeric port and running !== false.
+*/
+function parseHostStatus(json) {
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch {
+		throw new Error(`autopg status --json returned invalid JSON.\n${INSTALL_HINT}`);
+	}
+	if (typeof parsed.port !== "number") throw new Error(`autopg status --json missing numeric port.\n${INSTALL_HINT}`);
+	if (parsed.running === false) throw new Error(`autopg host is not running.\n${INSTALL_HINT}`);
+	return { port: parsed.port };
+}
+/**
+* Admin URL for an autopg host on `port`.
+*
+* Credentials follow autopg's own defaults / env chain (not "any local Postgres"):
+* - user: `AUTOPG_PG_USER` / `PGSERVE_PG_USER` / `postgres`
+* - password: `AUTOPG_PG_PASSWORD` / `PGSERVE_PG_PASSWORD` / `postgres`
+*
+* Port is never scanned: callers pass the port from `autopg status` (attach) or the
+* ephemeral recipe (`55432`). That keeps us off unrelated local servers (e.g. brew on 5432).
+*/
+function adminUrlFor(port, env = process.env) {
+	return `postgresql://${encodeURIComponent(env.AUTOPG_PG_USER || env.PGSERVE_PG_USER || "postgres")}:${encodeURIComponent(env.AUTOPG_PG_PASSWORD || env.PGSERVE_PG_PASSWORD || "postgres")}@127.0.0.1:${port}/postgres`;
+}
+/**
+* Discover a live autopg host via `autopg status --json`. Throws if the host is not proven live.
+*/
+function discoverHost(bin = requireAutopgBin()) {
+	let status;
+	try {
+		status = execFileSync(bin, ["status", "--json"], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+	} catch (err) {
+		const detail = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to query autopg status.\n${detail}\n${INSTALL_HINT}`);
+	}
+	const { port } = parseHostStatus(status);
+	return {
+		port,
+		adminUrl: adminUrlFor(port),
+		bin
+	};
+}
+function quoteIdent(name) {
+	return `"${name.replace(/"/g, "\"\"")}"`;
+}
+function quoteLiteral(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+async function withAdminClient(adminUrl, fn) {
+	const client = new pg.Client({ connectionString: adminUrl });
+	await client.connect();
+	try {
+		return await fn(client);
+	} finally {
+		await client.end();
+	}
+}
+/**
+* Deterministic local-only password for an app role (Prisma/TCP need it;
+* autopg hba uses `password` for 127.0.0.1).
+*
+* Keyed by `roleName` (not databaseName) so TEMPLATE clones that reuse the
+* same role keep working when `buildDatabaseUrl` is called with a new database.
+*/
+function rolePasswordFor(roleName) {
+	return createHash("sha256").update(`${PASSWORD_SALT_PREFIX}\0${roleName}`).digest("hex").slice(0, 32);
+}
+/**
+* Idempotently CREATE ROLE + CREATE DATABASE with cedar-pg owned names.
+*/
+async function ensureDatabase(opts) {
+	const password = opts.password ?? rolePasswordFor(opts.roleName);
+	await withAdminClient(opts.adminUrl, async (client) => {
+		if ((await client.query("SELECT 1 FROM pg_roles WHERE rolname = $1", [opts.roleName])).rowCount === 0) await client.query(`CREATE ROLE ${quoteIdent(opts.roleName)} WITH LOGIN PASSWORD ${quoteLiteral(password)}`);
+		else await client.query(`ALTER ROLE ${quoteIdent(opts.roleName)} WITH LOGIN PASSWORD ${quoteLiteral(password)}`);
+		if ((await client.query("SELECT 1 FROM pg_database WHERE datname = $1", [opts.databaseName])).rowCount === 0) await client.query(`CREATE DATABASE ${quoteIdent(opts.databaseName)} OWNER ${quoteIdent(opts.roleName)}`);
+		else await client.query(`ALTER DATABASE ${quoteIdent(opts.databaseName)} OWNER TO ${quoteIdent(opts.roleName)}`);
+	});
+}
+/**
+* Mark (or unmark) a database as a PostgreSQL template (`IS_TEMPLATE`).
+* Template DBs cannot be dropped until unset.
+*/
+async function setDatabaseIsTemplate(opts) {
+	const flag = opts.isTemplate ? "true" : "false";
+	await withAdminClient(opts.adminUrl, async (client) => {
+		await client.query(`ALTER DATABASE ${quoteIdent(opts.databaseName)} WITH IS_TEMPLATE ${flag}`);
+	});
+}
+/**
+* CREATE DATABASE … TEMPLATE … OWNER via admin connection.
+* Test roles are LOGIN-only; workers cannot CREATE DATABASE themselves.
+*/
+async function cloneDatabaseFromTemplate(opts) {
+	await withAdminClient(opts.adminUrl, async (client) => {
+		const tmpl = await client.query(`SELECT datistemplate FROM pg_database WHERE datname = $1`, [opts.templateName]);
+		if (!tmpl.rowCount) throw new Error(`template database not found: ${opts.templateName}`);
+		if (!tmpl.rows[0]?.datistemplate) throw new Error(`database is not a TEMPLATE; run markTemplate first: ${opts.templateName}`);
+		const exists = await client.query("SELECT 1 FROM pg_database WHERE datname = $1", [opts.databaseName]);
+		if (exists.rowCount && exists.rowCount > 0) throw new Error(`database already exists: ${opts.databaseName}`);
+		await client.query(`CREATE DATABASE ${quoteIdent(opts.databaseName)} WITH TEMPLATE ${quoteIdent(opts.templateName)} OWNER ${quoteIdent(opts.roleName)}`);
+	});
+}
+async function listOwnedDatnames(client, roleName) {
+	return (await client.query(`SELECT datname FROM pg_database
+     WHERE datdba = (SELECT oid FROM pg_roles WHERE rolname = $1)
+     ORDER BY datname`, [roleName])).rows.map((r) => r.datname);
+}
+/** Unset IS_TEMPLATE if needed, terminate backends, DROP DATABASE (no-op if missing). */
+async function dropOneDatabase(client, databaseName) {
+	const db = await client.query(`SELECT datistemplate FROM pg_database WHERE datname = $1`, [databaseName]);
+	if (!db.rowCount || db.rowCount === 0) return;
+	if (db.rows[0]?.datistemplate) await client.query(`ALTER DATABASE ${quoteIdent(databaseName)} WITH IS_TEMPLATE false`);
+	await client.query(`
+    SELECT pg_terminate_backend(pid)
+    FROM pg_stat_activity
+    WHERE datname = $1 AND pid <> pg_backend_pid()
+    `, [databaseName]);
+	await client.query(`DROP DATABASE IF EXISTS ${quoteIdent(databaseName)}`);
+}
+/**
+* DROP every database owned by `roleName` on one admin connection, then DROP ROLE.
+* When `preferLast` is owned, it is dropped after the other owned datnames (TEMPLATE after clones).
+* Never invents a DROP target beyond role ownership.
+*/
+async function dropDatabasesOwnedByRole(opts) {
+	return withAdminClient(opts.adminUrl, async (client) => {
+		const owned = await listOwnedDatnames(client, opts.roleName);
+		const ordered = [...owned.filter((name) => name !== opts.preferLast), ...owned.filter((name) => name === opts.preferLast)];
+		const dropped = [];
+		for (const databaseName of ordered) {
+			await dropOneDatabase(client, databaseName);
+			dropped.push(databaseName);
+		}
+		await client.query(`DROP ROLE IF EXISTS ${quoteIdent(opts.roleName)}`);
+		return dropped;
+	});
+}
+/**
+* DROP DATABASE (unset IS_TEMPLATE, force terminate backends) + DROP ROLE
+* when the role owns no remaining databases.
+*/
+async function dropDatabase(opts) {
+	await withAdminClient(opts.adminUrl, async (client) => {
+		await dropOneDatabase(client, opts.databaseName);
+		if ((await client.query(`SELECT 1 FROM pg_database WHERE datdba = (SELECT oid FROM pg_roles WHERE rolname = $1) LIMIT 1`, [opts.roleName])).rowCount === 0) await client.query(`DROP ROLE IF EXISTS ${quoteIdent(opts.roleName)}`);
+	});
+}
+function buildDatabaseUrl(opts) {
+	const password = opts.password ?? rolePasswordFor(opts.roleName);
+	return `postgresql://${encodeURIComponent(opts.roleName)}:${encodeURIComponent(password)}@127.0.0.1:${opts.port}/${opts.databaseName}`;
+}
+//#endregion
+//#region src/providers/host.ts
+/** Fixed CI TCP port so install registration and postmaster listen on the same port. */
+const EPHEMERAL_PORT = 55432;
+const OWNED_POSTMASTER_READY_MS = 3e4;
+const OWNED_POSTMASTER_POLL_MS = 200;
+/**
+* Resolve whether to start an owned ephemeral postmaster or use local pm2 install.
+*
+* - `CEDAR_PG_EPHEMERAL_HOST=1` → ephemeral
+* - `CEDAR_PG_EPHEMERAL_HOST=0` → local (even when `CI=true`)
+* - unset + `CI=true` → ephemeral
+* - otherwise → local
+*/
+function resolveEphemeralHostPolicy(env = process.env) {
+	const force = env.CEDAR_PG_EPHEMERAL_HOST;
+	if (force === "1") return "ephemeral";
+	if (force === "0") return "local";
+	if (env.CI === "true") return "ephemeral";
+	return "local";
+}
+/**
+* Fixed CI recipe: shared `--port` on install + postmaster, `--no-pm2 --no-ui`,
+* and `--ram` + `/dev/shm/cedar-pg-<uid>` on Linux when shm exists.
+*/
+function ephemeralHostRecipe(ctx = {}) {
+	const platform = ctx.platform ?? process.platform;
+	const shmAvailable = ctx.shmAvailable ?? (platform === "linux" && existsSync("/dev/shm"));
+	const uid = ctx.uid ?? process.getuid?.() ?? 0;
+	const port = ctx.port ?? EPHEMERAL_PORT;
+	const useRam = platform === "linux" && shmAvailable;
+	const dataDir = useRam ? `/dev/shm/cedar-pg-${uid}` : join(ctx.tmpDir ?? tmpdir(), "cedar-pg-host");
+	return {
+		dataDir,
+		port,
+		installArgs: [
+			"install",
+			"--no-pm2",
+			"--no-ui",
+			"--port",
+			String(port),
+			"--data",
+			dataDir
+		],
+		postmasterArgs: [
+			"postmaster",
+			...useRam ? ["--ram"] : [],
+			"--port",
+			String(port),
+			"--socket-dir",
+			dataDir,
+			"--data",
+			dataDir
+		]
+	};
+}
+/** Discovery from the recipe port — TCP readiness is the authority, not `autopg status`. */
+function discoveryFromRecipe(bin, recipe) {
+	return {
+		port: recipe.port,
+		adminUrl: adminUrlFor(recipe.port),
+		bin
+	};
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function runInstall(bin, args) {
+	const install = spawnSync(bin, args, {
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	if (install.status !== 0) throw new Error(`Failed to start autopg host (exit ${install.status}).\n${install.stderr || install.stdout || ""}\n${INSTALL_HINT}`);
+}
+/** True when something accepts TCP on 127.0.0.1:port (postmaster live, not just admin.json). */
+function canConnect(port) {
+	return new Promise((resolve) => {
+		const socket = createConnection({
+			host: "127.0.0.1",
+			port
+		}, () => {
+			socket.end();
+			resolve(true);
+		});
+		socket.on("error", () => {
+			resolve(false);
+		});
+	});
+}
+/** Kill a detached owned postmaster (process group when possible) and drop our handle. */
+function killOwnedChild(child) {
+	const pid = child.pid;
+	if (pid != null) try {
+		process.kill(-pid, "SIGTERM");
+	} catch {
+		try {
+			child.kill("SIGTERM");
+		} catch {}
+	}
+	child.unref();
+}
+/**
+* Poll until TCP accepts on port, or throw on timeout / {@link WaitForOwnedPostmasterOptions.failure}.
+* Exported for tests — the readiness seam for owned ephemeral start.
+*/
+async function waitForOwnedPostmaster(opts) {
+	const probe = opts.canConnect ?? canConnect;
+	const now = opts.now ?? Date.now;
+	const pause = opts.sleep ?? sleep;
+	const readyMs = opts.readyMs ?? OWNED_POSTMASTER_READY_MS;
+	const pollMs = opts.pollMs ?? OWNED_POSTMASTER_POLL_MS;
+	const deadline = now() + readyMs;
+	let lastDetail = "TCP not accepting";
+	while (now() < deadline) {
+		const fail = opts.failure?.();
+		if (fail) throw fail;
+		if (await probe(opts.port)) return;
+		lastDetail = `127.0.0.1:${opts.port} not accepting connections`;
+		await pause(pollMs);
+	}
+	throw new Error(`Timed out waiting for autopg host after ${readyMs}ms.\n${lastDetail}\n${INSTALL_HINT}`);
+}
+/**
+* Install + detached postmaster with fully ignored stdio so the CI job owns lifetime
+* (caller exit must not close pipes under the daemon).
+*
+* Readiness is TCP accept on the recipe port — not `autopg status`, which succeeds
+* after `install --no-pm2` before postmaster is listening. On success, discovery is
+* recipe-derived (same port). On failure, the spawned child is killed.
+*/
+async function startEphemeralHost(bin) {
+	const recipe = ephemeralHostRecipe();
+	mkdirSync(recipe.dataDir, { recursive: true });
+	runInstall(bin, recipe.installArgs);
+	const state = {
+		exit: null,
+		spawnError: null
+	};
+	const child = spawn(bin, recipe.postmasterArgs, {
+		detached: true,
+		stdio: "ignore"
+	});
+	child.on("error", (err) => {
+		state.spawnError = err;
+	});
+	child.on("exit", (code, signal) => {
+		state.exit = {
+			code,
+			signal
+		};
+	});
+	try {
+		await waitForOwnedPostmaster({
+			port: recipe.port,
+			failure: () => {
+				if (state.spawnError) return /* @__PURE__ */ new Error(`Failed to spawn autopg postmaster.\n${state.spawnError.message}\n${INSTALL_HINT}`);
+				if (state.exit) return /* @__PURE__ */ new Error(`autopg postmaster exited before ready (code=${state.exit.code}, signal=${state.exit.signal}).\nautopg is required. Install with:
+  curl -fsSL https://raw.githubusercontent.com/automagik-dev/autopg/main/install.sh | bash
+Then ensure ~/.local/bin is on PATH, or set AUTOPG_BIN.`);
+				return null;
+			}
+		});
+	} catch (err) {
+		killOwnedChild(child);
+		throw err;
+	}
+	child.unref();
+	return discoveryFromRecipe(bin, recipe);
+}
+/**
+* Ensure the host postmaster is up.
+*
+* - Attaches when `autopg status --json` shows a live host.
+* - Otherwise starts from {@link resolveEphemeralHostPolicy}: local pm2 `install`,
+*   or opinionated ephemeral (`--no-pm2 --no-ui` + detached postmaster).
+* - CI job owns ephemeral postmaster lifetime on success (no cedar-pg host dispose).
+* - Failed ephemeral start kills the spawned child so ensure is atomic for the caller.
+*/
+async function ensureHostRunning(bin = requireAutopgBin()) {
+	try {
+		return discoverHost(bin);
+	} catch {}
+	if (resolveEphemeralHostPolicy() === "ephemeral") return startEphemeralHost(bin);
+	runInstall(bin, ["install"]);
+	return discoverHost(bin);
+}
+//#endregion
+//#region src/core/lifecycle.ts
+function writeEnvFile(root, mode, databaseUrl) {
+	mkdirSync(leaseDir(root), {
+		recursive: true,
+		mode: 448
+	});
+	let body = `DATABASE_URL=${databaseUrl}\n`;
+	if (mode === "test") body += `TEST_DATABASE_URL=${databaseUrl}\n`;
+	writeFileSync(envPath(root, mode), body, { mode: 384 });
+}
+function urlFromLease(lease) {
+	return buildDatabaseUrl({
+		port: lease.port,
+		databaseName: lease.databaseName,
+		roleName: lease.roleName
+	});
+}
+/**
+* DROP every DB owned by the lease role (TEMPLATE + clones), then forget lease.
+* Provider owns ordering (clones before leased datname) on one admin connection.
+*/
+async function dropThenForget(lease, adminUrl) {
+	const dropped = await dropDatabasesOwnedByRole({
+		adminUrl,
+		roleName: lease.roleName,
+		preferLast: lease.databaseName
+	});
+	forgetLease(lease);
+	return dropped;
+}
+/**
+* Acquire a worktree-scoped database and return connection info.
+*
+* - `dev`: keep DB across restarts.
+* - `test`: DROP when `dispose()` is awaited (callers / test runners own teardown).
+*/
+async function acquire(options) {
+	const identity = resolveWorktreeIdentity(options.root);
+	const mode = options.mode;
+	const databaseName = buildDatabaseName(identity, mode);
+	const roleName = buildRoleName(databaseName);
+	const host = await ensureHostRunning();
+	await ensureDatabase({
+		adminUrl: host.adminUrl,
+		databaseName,
+		roleName
+	});
+	const databaseUrl = buildDatabaseUrl({
+		port: host.port,
+		databaseName,
+		roleName
+	});
+	writeLease({
+		schemaVersion: 1,
+		mode,
+		root: identity.root,
+		repoSlug: identity.repoSlug,
+		worktreeSlug: identity.worktreeSlug,
+		pathHash: identity.pathHash,
+		databaseName,
+		roleName,
+		port: host.port,
+		pid: process.pid,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	writeEnvFile(identity.root, mode, databaseUrl);
+	if (options.setEnv !== false) applyDatabaseUrlEnv(databaseUrl, { mode });
+	const disposeFn = async () => {
+		await dispose({
+			root: identity.root,
+			mode
+		});
+	};
+	return {
+		databaseUrl,
+		adminUrl: host.adminUrl,
+		databaseName,
+		roleName,
+		repoSlug: identity.repoSlug,
+		worktreeSlug: identity.worktreeSlug,
+		pathHash: identity.pathHash,
+		root: identity.root,
+		mode,
+		port: host.port,
+		dispose: disposeFn
+	};
+}
+/**
+* Resolve skip policy then acquire. Single entry for hosts (Cedar CLI, Jest, Vitest).
+* On external-url skip, applies DATABASE_URL / TEST_DATABASE_URL when `setEnv` is not false.
+*/
+async function acquireIfNeeded(options) {
+	const outcome = await runIfNeeded(options, () => acquire({
+		root: options.root,
+		mode: options.mode,
+		setEnv: options.setEnv
+	}));
+	if (outcome.status === "skipped") return outcome;
+	return {
+		status: "acquired",
+		...outcome.value
+	};
+}
+/**
+* Role-scoped suite teardown: DROP every database owned by the lease role
+* (TEMPLATE + clones), then DROP ROLE and forget the lease. Unsets `IS_TEMPLATE`
+* as needed. This is not per-clone cleanup — use `CloneResult.dropClone` for that.
+* No-ops without a valid lease; never invents a DROP target beyond role ownership.
+* If the host is unavailable, leaves the lease so dispose/gc can retry.
+*/
+async function dispose(options = {}) {
+	const identity = resolveWorktreeIdentity(options.root);
+	const mode = options.mode ?? "test";
+	const lease = readLease(identity.root, mode);
+	if (!lease) return {
+		dropped: false,
+		reason: "no-lease"
+	};
+	let host;
+	try {
+		host = await ensureHostRunning();
+	} catch {
+		return {
+			dropped: false,
+			reason: "host-unavailable"
+		};
+	}
+	const droppedDatabases = await dropThenForget(lease, host.adminUrl);
+	return {
+		dropped: true,
+		databaseName: lease.databaseName,
+		droppedDatabases
+	};
+}
+/**
+* Drop databases whose registered worktree root no longer exists on disk.
+* Registry entries are removed only after a successful DROP (owned DBs + lease DB).
+*/
+async function gc() {
+	const dropped = [];
+	const orphans = listRegistryLeases().filter(isOrphanLease);
+	if (orphans.length === 0) return { dropped };
+	let host;
+	try {
+		host = await ensureHostRunning();
+	} catch {
+		return { dropped };
+	}
+	for (const lease of orphans) try {
+		const names = await dropThenForget(lease, host.adminUrl);
+		dropped.push(...names);
+	} catch {}
+	return { dropped };
+}
+//#endregion
+export { buildCloneDatabaseName as C, runIfNeeded as S, buildRoleName as T, setDatabaseIsTemplate as _, urlFromLease as a, isExternalDatabaseEscapeHatch as b, ROLE_PASSWORD_SCHEME as c, discoverHost as d, dropDatabase as f, rolePasswordFor as g, resolveAutopgBin as h, gc as i, buildDatabaseUrl as l, requireAutopgBin as m, acquireIfNeeded as n, ensureHostRunning as o, parseHostStatus as p, dispose as r, INSTALL_HINT as s, acquire as t, cloneDatabaseFromTemplate as u, applyDatabaseUrlEnv as v, buildDatabaseName as w, resolveAcquireSkip as x, isCedarPgManagedUrl as y };
+
+//# sourceMappingURL=lifecycle-BOo6xBjD.mjs.map