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

package/dist/lifecycle-BvIx0xqq.mjs

@@ -0,0 +1,781 @@
+import { a as leaseDir, f as resolveWorktreeIdentity, i as isOrphanLease, l as readLease, m as PASSWORD_SALT_PREFIX, n as envPath, r as forgetLease, s as listRegistryLeases, u as writeLease } from "./lease-DS1SX8U_.mjs";
+import { existsSync, mkdirSync, readdirSync, rmSync, statfsSync, 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` → the **registered** port. Throws only when the
+* output is not autopg status JSON.
+*
+* Registration is not liveness: autopg reports a port for a stopped host too,
+* and its `status` string is supervisor-specific (pm2 `online`, systemd-user /
+* launchd differ). Liveness is a TCP accept on the port, proven by the caller —
+* `acquire` does that before it connects.
+*/
+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}`);
+	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 the registered autopg host (port + admin URL) via `autopg status --json`.
+* Throws when autopg cannot be queried; does **not** prove a listener — probe TCP
+* (or use `acquire`, which does) before connecting.
+*/
+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
+const EPHEMERAL_PORT = 55432;
+const HOST_READY_MS = 3e4;
+const HOST_POLL_MS = 200;
+/**
+* autopg verbs that can bring the *registered* local host up, cheapest fix first.
+*
+* `restart` exit 0 is not evidence of a listener: when pm2 is missing or does not
+* list `autopg-server`, autopg still prints "respawned daemon" and returns 0.
+* That is why every verb is followed by a TCP wait, not trusted on exit status.
+*
+* `install` covers a never-registered machine (postinstall ships the binary only)
+* and a reboot whose pm2 list is empty (`pm2 start`). On an already-registered
+* host it is a no-op for the server process but may `pm2 start` the autopg UI —
+* so it runs only after `restart` failed to produce a listener.
+*/
+const LOCAL_START = [{
+	argv: ["restart"],
+	readyMs: 1e4
+}, {
+	argv: ["install"],
+	readyMs: HOST_READY_MS
+}];
+/** Soft minimum free bytes on /dev/shm before RAM-backed ephemeral start (warns only). */
+const EPHEMERAL_SHM_MIN_FREE_BYTES = 512 * 1024 * 1024;
+/**
+* Hint when ephemeral `--ram` initdb fails for space / leftover dirs under `/dev/shm`.
+* Cloud VMs often ship with a tiny default tmpfs (e.g. 64MB).
+*/
+const EPHEMERAL_SHM_HINT = "Ephemeral autopg uses /dev/shm with --ram. If initdb fails with Disk quota / No space (Postgres 53100):\n  1. Enlarge tmpfs (cloud VMs often default to ~64MB): sudo mount -o remount,size=6G /dev/shm\n  2. Clear leftovers from OOM-killed runs (your test data only):\n     rm -rf /dev/shm/cedar-pg-* /dev/shm/pgserve-* /dev/shm/PostgreSQL.*";
+/**
+* Resolve how to start a host when none is listening.
+*
+* - `CEDAR_PG_EPHEMERAL_HOST=1` → ephemeral owned postmaster
+* - `CEDAR_PG_EPHEMERAL_HOST=0` → never own a postmaster, local autopg only (even in CI)
+* - unset + `CI=true` → ephemeral
+* - otherwise → local
+*/
+function resolveHostStartPolicy(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";
+}
+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,
+		postmasterArgs: [
+			"postmaster",
+			...useRam ? ["--ram"] : [],
+			"--port",
+			String(port),
+			"--socket-dir",
+			dataDir,
+			"--data",
+			dataDir
+		]
+	};
+}
+function discoveryFromRecipe(bin, recipe) {
+	return {
+		port: recipe.port,
+		adminUrl: adminUrlFor(recipe.port),
+		bin
+	};
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** True when stderr/stdout looks like a /dev/shm quota or ENOSPC failure. */
+function looksLikeShmSpaceError(text) {
+	return /Disk quota exceeded|No space left on device|ENOSPC|\b53100\b/i.test(text);
+}
+function formatHostStartError(detail, useRamShm = false) {
+	return `Failed to start autopg host.\n${detail}\n${INSTALL_HINT}${useRamShm && looksLikeShmSpaceError(detail) ? `\n${EPHEMERAL_SHM_HINT}` : ""}`;
+}
+/**
+* Remove leftover ephemeral data dirs under `/dev/shm` (and the recipe dataDir).
+* Safe for OOM-killed CI/cloud runs that leave `cedar-pg-*` / `pgserve-*` /
+* `PostgreSQL.*` filling tmpfs.
+*
+* Only called on ephemeral cold start, i.e. when the recipe port has no listener —
+* never while a host owns those dirs.
+*/
+function pruneStaleEphemeralDataDirs(opts) {
+	const removed = [];
+	const tryRm = (path) => {
+		if (!existsSync(path)) return;
+		try {
+			rmSync(path, {
+				recursive: true,
+				force: true
+			});
+			removed.push(path);
+		} catch {}
+	};
+	tryRm(opts.dataDir);
+	const shmRoot = opts.shmRoot ?? (existsSync("/dev/shm") ? "/dev/shm" : void 0);
+	if (!shmRoot) return removed;
+	let entries = [];
+	try {
+		entries = readdirSync(shmRoot);
+	} catch {
+		return removed;
+	}
+	for (const name of entries) if (name.startsWith("cedar-pg-") || name.startsWith("pgserve-") || name.startsWith("PostgreSQL.")) tryRm(join(shmRoot, name));
+	return removed;
+}
+/** Free bytes on `path`, or `null` if unavailable. */
+function freeBytesOn(path) {
+	try {
+		const s = statfsSync(path);
+		return Number(s.bavail) * Number(s.bsize);
+	} catch {
+		return null;
+	}
+}
+/** Run a one-shot autopg verb. Returns failure detail, or `null` on exit 0. */
+function runAutopg(bin, argv) {
+	const result = spawnSync(bin, argv, {
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	if (result.error) return result.error.message;
+	if (result.status === 0) return null;
+	return `exit ${result.status}\n${(result.stderr || result.stdout || "").trim()}`.trim();
+}
+/** 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);
+		});
+	});
+}
+function killOwnedChild(child) {
+	const pid = child.pid;
+	if (pid != null) try {
+		process.kill(-pid, "SIGTERM");
+	} catch {
+		try {
+			child.kill("SIGTERM");
+		} catch {}
+	}
+	child.unref();
+}
+/**
+* The single liveness primitive: TCP accept on 127.0.0.1:port.
+*
+* Resolves `true` as soon as something is listening, `false` when the grace
+* period expires, and throws only what {@link WaitForListenerOptions.failure}
+* returns. Used for attach (one probe), local restart, and ephemeral start.
+*/
+async function waitForListener(opts) {
+	const probe = opts.canConnect ?? canConnect;
+	const now = opts.now ?? Date.now;
+	const pause = opts.sleep ?? sleep;
+	const pollMs = opts.pollMs ?? HOST_POLL_MS;
+	const deadline = now() + (opts.readyMs ?? 0);
+	for (;;) {
+		const fail = opts.failure?.();
+		if (fail) throw fail;
+		if (await probe(opts.port)) return true;
+		if (now() >= deadline) return false;
+		await pause(pollMs);
+	}
+}
+/**
+* Attach to the registered autopg host once TCP accepts on its port.
+*
+* Registration is not liveness: a stopped pm2 host still reports a port, and
+* attaching to it is the `ECONNREFUSED 127.0.0.1:25432` bug. `readyMs` > 0 is
+* the grace period after asking autopg to start.
+*/
+async function attachLiveHost(bin, readyMs = 0) {
+	let discovered;
+	try {
+		discovered = discoverHost(bin);
+	} catch {
+		return null;
+	}
+	return await waitForListener({
+		port: discovered.port,
+		readyMs
+	}) ? discovered : null;
+}
+/**
+* Bring the user's registered autopg host up and attach to it — same port, same
+* `~/.autopg/data`, still there after this process exits. cedar-pg never runs a
+* second local Postgres.
+*/
+async function startLocalHost(bin, registeredPort) {
+	const failures = [];
+	for (const { argv, readyMs } of LOCAL_START) {
+		const label = `autopg ${argv.join(" ")}`;
+		const failure = runAutopg(bin, [...argv]);
+		if (failure) {
+			failures.push(`${label}: ${failure}`);
+			continue;
+		}
+		const attached = await attachLiveHost(bin, readyMs);
+		if (attached) return attached;
+		failures.push(`${label}: no listener within ${readyMs}ms`);
+	}
+	const where = registeredPort != null ? `autopg host is registered on 127.0.0.1:${registeredPort} but nothing is listening.\n` : "";
+	throw new Error(formatHostStartError(`${where}${failures.join("\n")}`));
+}
+/**
+* Ephemeral host owned by this process/job: detached `autopg postmaster` with
+* fully ignored stdio (caller exit must not close pipes under the daemon).
+*
+* Never runs `autopg install` — that rewrites `~/.autopg/admin.json` and fails
+* with `supervisor mismatch` next to a local pm2 install. Reuses a listener
+* already on the recipe port, and prunes stale RAM dirs before a cold start.
+*/
+async function startEphemeralHost(bin) {
+	const recipe = ephemeralHostRecipe();
+	if (await canConnect(recipe.port)) return discoveryFromRecipe(bin, recipe);
+	const useRamShm = recipe.postmasterArgs.includes("--ram");
+	pruneStaleEphemeralDataDirs({ dataDir: recipe.dataDir });
+	if (useRamShm) {
+		const free = freeBytesOn("/dev/shm");
+		if (free != null && free < 536870912) process.stderr.write(`[cedar-pg] warning: /dev/shm has ~${Math.round(free / (1024 * 1024))}MB free (recommend ≥${Math.round(EPHEMERAL_SHM_MIN_FREE_BYTES / (1024 * 1024))}MB for --ram).\n${EPHEMERAL_SHM_HINT}\n`);
+	}
+	mkdirSync(recipe.dataDir, { recursive: true });
+	const child = spawn(bin, recipe.postmasterArgs, {
+		detached: true,
+		stdio: "ignore"
+	});
+	let died = null;
+	child.on("error", (err) => {
+		died = new Error(formatHostStartError(`Failed to spawn autopg postmaster.\n${err.message}`, useRamShm));
+	});
+	child.on("exit", (code, signal) => {
+		died ??= new Error(formatHostStartError(`autopg postmaster exited before ready (code=${code}, signal=${signal}).`, useRamShm));
+	});
+	try {
+		if (!await waitForListener({
+			port: recipe.port,
+			readyMs: HOST_READY_MS,
+			failure: () => died
+		})) throw new Error(formatHostStartError(`autopg postmaster did not accept 127.0.0.1:${recipe.port} within ${HOST_READY_MS}ms.`, useRamShm));
+	} catch (err) {
+		killOwnedChild(child);
+		throw err;
+	}
+	child.unref();
+	return discoveryFromRecipe(bin, recipe);
+}
+/**
+* Attach to a listening autopg host, else start one per
+* {@link resolveHostStartPolicy}. Internal: callers use `acquire` / `adminUrl`.
+*/
+async function ensureHostRunning(bin = requireAutopgBin()) {
+	let registered = null;
+	try {
+		registered = discoverHost(bin);
+	} catch {}
+	if (registered && await waitForListener({ port: registered.port })) return registered;
+	return resolveHostStartPolicy() === "ephemeral" ? startEphemeralHost(bin) : startLocalHost(bin, registered?.port);
+}
+//#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-BvIx0xqq.mjs.map