@cedarjs/pg 0.2.0-alpha.0 → 0.3.0

package/dist/lifecycle-2BZgSVz2.mjs

@@ -0,0 +1,1072 @@
+import { a as leaseDir, d as resolveRoot, f as resolveWorktreeIdentity, i as isOrphanLease, l as readLease, m as PASSWORD_SALT_PREFIX, n as envPath, p as CLI_NAME, r as forgetLease, s as listRegistryLeases, u as writeLease } from "./lease-DS1SX8U_.mjs";
+import { closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, 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;
+}
+/**
+* Append `suffix` to a database name, staying ≤63 chars. When it does not fit,
+* cut the readable head (`cpg_<repo>_<worktree>`) and keep the trailing
+* `_<mode>_<pathHash8>` whole: that hash is what keeps worktrees apart.
+*/
+function appendKeepingHash(databaseName, suffix) {
+	const full = `${databaseName}${suffix}`;
+	if (full.length <= PG_MAX) return full;
+	const tail = /_[^_]+_[^_]+$/.exec(databaseName)?.[0] ?? "";
+	return `${databaseName.slice(0, Math.max(0, PG_MAX - tail.length - suffix.length)).replace(/_+$/, "")}${tail}${suffix}`.slice(0, PG_MAX);
+}
+/** Role for a database name: `<databaseName>_role`, cut by `appendKeepingHash`. */
+function buildRoleName(databaseName) {
+	return appendKeepingHash(databaseName, "_role");
+}
+/**
+* Build a worker clone datname from a TEMPLATE database name.
+* Layout: `<template>_c_<suffix>`, cut by `appendKeepingHash` (keeps mode, hash, and suffix).
+*/
+function buildCloneDatabaseName(templateName, suffix) {
+	const safe = suffix.toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 24);
+	return appendKeepingHash(templateName, `_c_${safe.length > 0 ? safe : "w"}`);
+}
+//#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
+/** autopg release cedar-pg is tested against (`scripts/autopg-version`, inlined at build). */
+const AUTOPG_PINNED_VERSION = "v3.2.2";
+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;
+}
+function optionalNonEmptyString(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+/**
+* Parse `autopg status --json` → the **registered** port (and data/socket/logs
+* dirs when present). 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` / `ready` describe the supervisor (autopg ≥ v3.2: `ready` needs
+* pm2 `online`; pm2's raw state is `supervisorStatus`). Neither, nor `runtime.live`,
+* is the attach gate — a bare postmaster (e.g. one cedar-pg revived) is
+* query-ready while status stays `stopped` / `ready: false`.
+* Liveness is a TCP accept on the port, proven by the caller (`acquire`).
+*/
+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}`);
+	const result = { port: parsed.port };
+	for (const key of [
+		"dataDir",
+		"socketDir",
+		"logsDir"
+	]) {
+		const value = optionalNonEmptyString(parsed[key]);
+		if (value) result[key] = value;
+	}
+	return result;
+}
+/**
+* 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`;
+}
+/** `[major, minor, patch]` from `autopg --version` output or a `vX.Y.Z` tag; `null` if absent. */
+function parseAutopgVersion(text) {
+	const m = /(\d+)\.(\d+)\.(\d+)/.exec(text);
+	return m ? [
+		Number(m[1]),
+		Number(m[2]),
+		Number(m[3])
+	] : null;
+}
+/**
+* Upgrade warning when `autopg --version` output is older than `pin`. `null` when
+* current, newer, or unreadable — never nag on what cannot be parsed. Upgrading
+* is the user's call: it restarts the host every worktree shares.
+*/
+function outdatedAutopgWarning(versionOutput, pin = AUTOPG_PINNED_VERSION) {
+	const have = parseAutopgVersion(versionOutput);
+	const want = parseAutopgVersion(pin);
+	if (!have || !want) return null;
+	if ((have[0] - want[0] || have[1] - want[1] || have[2] - want[2]) >= 0) return null;
+	return `[cedar-pg] warning: autopg ${have.join(".")} is older than ${pin}, the version @cedarjs/pg is tested with.\nUpgrade (restarts the shared host; open connections from other worktrees drop):
+  curl -fsSL https://raw.githubusercontent.com/automagik-dev/autopg/${pin}/install.sh | AUTOPG_VERSION=${pin} bash\n  autopg update
+`;
+}
+/** `autopg --version` stdout; `""` when it cannot run (treated as unknown). */
+function readAutopgVersion(bin) {
+	return spawnSync(bin, ["--version"], {
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		],
+		timeout: 5e3
+	}).stdout ?? "";
+}
+function readStatusJson(bin) {
+	try {
+		return 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}`);
+	}
+}
+/**
+* Discover the registered autopg host (attach target + reported data/socket/logs
+* dirs) 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 discoverRegistration(bin = requireAutopgBin()) {
+	const { port, ...paths } = parseHostStatus(readStatusJson(bin));
+	return {
+		host: {
+			port,
+			adminUrl: adminUrlFor(port),
+			bin
+		},
+		...paths
+	};
+}
+/**
+* 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()) {
+	return discoverRegistration(bin).host;
+}
+function quoteIdent(name) {
+	return `"${name.replace(/"/g, "\"\"")}"`;
+}
+function quoteLiteral(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+/** Grace for a postmaster that accepts TCP but still answers 57P03 (startup / recovery). */
+const ADMIN_CONNECT_READY_MS = 3e4;
+const ADMIN_CONNECT_POLL_MS = 200;
+/**
+* Retry `connect` while Postgres answers `57P03` (cannot_connect_now: "the
+* database system is starting up" / in recovery). TCP accept — the host
+* liveness gate — comes before query-ready, so a freshly revived or crash-
+* recovering postmaster needs this. Any other error is thrown immediately.
+*/
+async function connectWhileStartingUp(connect, opts = {}) {
+	const now = opts.now ?? Date.now;
+	const pause = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+	const deadline = now() + (opts.readyMs ?? ADMIN_CONNECT_READY_MS);
+	for (;;) {
+		try {
+			return await connect();
+		} catch (err) {
+			if (err.code !== "57P03" || now() >= deadline) throw err;
+		}
+		await pause(opts.pollMs ?? ADMIN_CONNECT_POLL_MS);
+	}
+}
+async function withAdminClient(adminUrl, fn) {
+	const client = await connectWhileStartingUp(async () => {
+		const attempt = new pg.Client({ connectionString: adminUrl });
+		try {
+			await attempt.connect();
+			return attempt;
+		} catch (err) {
+			await attempt.end().catch(() => {});
+			throw err;
+		}
+	});
+	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}`);
+	});
+}
+/** Postgres `duplicate_database`: CREATE DATABASE hit an existing datname. */
+const DUPLICATE_DATABASE = "42P04";
+/**
+* CREATE DATABASE … TEMPLATE … OWNER via admin connection.
+* Test roles are LOGIN-only; workers cannot CREATE DATABASE themselves.
+*
+* With `reuse`, an existing `databaseName` owned by `roleName` is kept as-is:
+* a worker clone made earlier in this run by another test file.
+* An existing datname owned by any other role always fails: it is not ours.
+*/
+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}`);
+		try {
+			await client.query(`CREATE DATABASE ${quoteIdent(opts.databaseName)} WITH TEMPLATE ${quoteIdent(opts.templateName)} OWNER ${quoteIdent(opts.roleName)}`);
+			return;
+		} catch (err) {
+			if (err.code !== DUPLICATE_DATABASE) throw err;
+		}
+		const owner = (await client.query(`SELECT pg_get_userbyid(datdba) AS owner FROM pg_database WHERE datname = $1`, [opts.databaseName])).rows[0]?.owner;
+		if (opts.reuse && owner === opts.roleName) return;
+		throw new Error(`database already exists: ${opts.databaseName} (owned by ${owner ?? "unknown"})`);
+	});
+}
+/**
+* Empty every user table in `databaseName` with one
+* `TRUNCATE … RESTART IDENTITY`, so serial / identity columns start at 1 again.
+*
+* Runs as admin against that database. Skips system schemas, temp tables, and
+* tables an extension owns (e.g. PostGIS `spatial_ref_sys`); partitions are covered by
+* their parent. No `CASCADE`: every user table is in the one statement, so no
+* FK target is missing from it.
+*/
+async function truncateUserTables(opts) {
+	const url = new URL(opts.adminUrl);
+	url.pathname = `/${opts.databaseName}`;
+	return withAdminClient(url.toString(), async (client) => {
+		const tables = (await client.query(`SELECT format('%I.%I', n.nspname, c.relname) AS name
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE c.relkind IN ('r', 'p')
+         AND NOT c.relispartition
+         AND c.relpersistence <> 't'
+         AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+         AND NOT EXISTS (
+           SELECT 1 FROM pg_depend d
+           WHERE d.classid = 'pg_class'::regclass AND d.objid = c.oid AND d.deptype = 'e'
+         )
+       ORDER BY 1`)).rows.map((r) => r.name);
+		if (tables.length > 0) await client.query(`TRUNCATE TABLE ${tables.join(", ")} RESTART IDENTITY`);
+		return tables;
+	});
+}
+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 restart` exits 0 only once ready; grace covers older autopg that returned early. */
+const LOCAL_RESTART_READY_MS = 1e4;
+/** 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. cedar-pg already removes its own leftover dir (/dev/shm/cedar-pg-<uid>) on cold start.\n     Never rm /dev/shm/PostgreSQL.*: those segments belong to every running Postgres,\n     and deleting a live one breaks new connections to that host (58P01).";
+/**
+* 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 an ephemeral postmaster, local registered host 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}` : ""}`;
+}
+/** 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;
+	const output = `${result.stderr ?? ""}${result.stdout ?? ""}`;
+	return `exit ${result.status}\n${output.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;
+}
+/** Appended by the revived registered postmaster (next to autopg's own pm2 logs). */
+const REVIVED_POSTMASTER_LOG = "cedarpg-postmaster.log";
+function errorDetail(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
+* Live PID from `<dataDir>/postmaster.pid`, else `null`. Postgres writes it before
+* binding, so a live owner means another postmaster (pm2 still recovering, or a
+* concurrent acquire) already holds the data dir — wait for it, never compete.
+*/
+function liveDataDirOwner(dataDir) {
+	return livePidIn(join(dataDir, "postmaster.pid"));
+}
+/** Live PID from the first line of `file`, else `null` (missing, garbage, or dead). */
+function livePidIn(file) {
+	let pid;
+	try {
+		pid = Number.parseInt(readFileSync(file, "utf8"), 10);
+	} catch {
+		return null;
+	}
+	if (!Number.isInteger(pid) || pid <= 0) return null;
+	try {
+		process.kill(pid, 0);
+		return pid;
+	} catch (err) {
+		return err.code === "EPERM" ? pid : null;
+	}
+}
+/**
+* Exclusive cold-start lock `<dataDir>.lock` holding our PID. Returns `null` once
+* we hold it, else the live holder's PID. `postmaster.pid` alone cannot guard an
+* ephemeral cold start: it does not exist yet while a peer runs initdb, which is
+* exactly when a second `rm -rf` would destroy the peer's cluster.
+*
+* The PID is written to a private file and hard-linked into place, so the lock
+* never exists without its PID. A dead holder's lock is stale and taken over.
+*/
+function tryColdStartLock(lockPath) {
+	const mine = `${lockPath}.${process.pid}`;
+	writeFileSync(mine, String(process.pid));
+	try {
+		for (;;) {
+			try {
+				linkSync(mine, lockPath);
+				return null;
+			} catch (err) {
+				if (err.code !== "EEXIST") throw err;
+			}
+			const holder = livePidIn(lockPath);
+			if (holder != null) return holder;
+			rmSync(lockPath, { force: true });
+		}
+	} finally {
+		rmSync(mine, { force: true });
+	}
+}
+/**
+* Detached `autopg postmaster`. Success: child is unref'd (survives this process).
+* Failure: child is killed, throws a one-line detail (caller wraps / aggregates).
+* `logFile` (appended) keeps output from a postmaster nothing else supervises;
+* otherwise stdio is fully ignored (caller exit must not close pipes under it).
+*/
+async function spawnDetachedPostmaster(opts) {
+	const { readyMs } = opts;
+	const logFd = opts.logFile ? openSync(opts.logFile, "a") : null;
+	let child;
+	try {
+		child = spawn(opts.bin, opts.args, {
+			detached: true,
+			stdio: logFd == null ? "ignore" : [
+				"ignore",
+				logFd,
+				logFd
+			]
+		});
+	} finally {
+		if (logFd != null) closeSync(logFd);
+	}
+	let died = null;
+	child.on("error", (err) => {
+		died = /* @__PURE__ */ new Error(`Failed to spawn autopg postmaster.\n${err.message}`);
+	});
+	child.on("exit", (code, signal) => {
+		died ??= /* @__PURE__ */ new Error(`autopg postmaster exited before ready (code=${code}, signal=${signal}).`);
+	});
+	try {
+		if (!await waitForListener({
+			port: opts.port,
+			readyMs,
+			failure: () => died
+		})) throw new Error(`autopg postmaster did not accept 127.0.0.1:${opts.port} within ${readyMs}ms.`);
+	} catch (err) {
+		killOwnedChild(child);
+		throw err;
+	}
+	child.unref();
+}
+/**
+* Detached `autopg postmaster` on the registered port / data dir (socket dir when
+* autopg reports one; otherwise the postmaster resolves autopg's own default).
+* Returns failure detail, or `null` once TCP accepts.
+*
+* No reported `dataDir` → not attempted: a postmaster without `--data` is not
+* persistent, and guessing autopg's path is how a second Postgres happens.
+*/
+async function reviveRegisteredPostmaster(bin, reg) {
+	const { dataDir, socketDir, logsDir } = reg;
+	const { port } = reg.host;
+	if (!dataDir) return "autopg postmaster: not attempted (autopg status --json reports no dataDir)";
+	const args = [
+		"postmaster",
+		"--port",
+		String(port),
+		"--data",
+		dataDir,
+		...socketDir ? ["--socket-dir", socketDir] : []
+	];
+	const label = `autopg ${args.join(" ")}`;
+	const logFile = logsDir ? join(logsDir, REVIVED_POSTMASTER_LOG) : void 0;
+	if (liveDataDirOwner(dataDir) == null) try {
+		mkdirSync(dataDir, {
+			recursive: true,
+			mode: 448
+		});
+		if (logsDir) mkdirSync(logsDir, { recursive: true });
+		await spawnDetachedPostmaster({
+			bin,
+			args,
+			port,
+			readyMs: HOST_READY_MS,
+			...logFile ? { logFile } : {}
+		});
+		return null;
+	} catch (err) {
+		if (liveDataDirOwner(dataDir) == null) return `${label}: ${errorDetail(err)}${logFile ? `\nPostmaster log: ${logFile}` : ""}`;
+	}
+	if (await waitForListener({
+		port,
+		readyMs: HOST_READY_MS
+	})) return null;
+	return `${label}: postmaster pid ${liveDataDirOwner(dataDir) ?? "?"} owns ${dataDir} but did not accept 127.0.0.1:${port} within ${HOST_READY_MS}ms`;
+}
+/**
+* Revive the user's registered autopg host — same port, same `~/.autopg/data`,
+* still running after this process exits. Never a second local Postgres.
+*
+* `restart` drives pm2 only and exits 0 once ready; without pm2 (or under another
+* supervisor) it exits 1. Either way TCP is the gate: if still dark,
+* {@link reviveRegisteredPostmaster} on the registered port/data. Do not
+* `install` on an already-registered host (wants pm2, refuses a port change).
+* `install` is only for a never-registered machine.
+*/
+async function startLocalHost(bin, registered) {
+	const failures = [];
+	const restartFailure = runAutopg(bin, ["restart"]);
+	if (restartFailure) failures.push(`autopg restart: ${restartFailure}`);
+	else {
+		const attached = await attachLiveHost(bin, LOCAL_RESTART_READY_MS);
+		if (attached) return attached;
+		failures.push(`autopg restart: no listener within ${LOCAL_RESTART_READY_MS}ms`);
+	}
+	if (registered) {
+		const failure = await reviveRegisteredPostmaster(bin, registered);
+		if (!failure) return registered.host;
+		failures.push(failure);
+	} else {
+		const installFailure = runAutopg(bin, ["install"]);
+		if (installFailure) failures.push(`autopg install: ${installFailure}`);
+		else {
+			const attached = await attachLiveHost(bin, HOST_READY_MS);
+			if (attached) return attached;
+			failures.push(`autopg install: no listener within ${HOST_READY_MS}ms`);
+		}
+	}
+	const where = registered != null ? `autopg host is registered on 127.0.0.1:${registered.host.port} 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. Concurrent cold starts (Nx running several
+* `db:ready` on one runner) serialize on {@link tryColdStartLock}: only the
+* holder prunes and starts; everyone else waits for the listener.
+*/
+async function startEphemeralHost(bin, recipe = ephemeralHostRecipe()) {
+	const { dataDir, port } = recipe;
+	if (await canConnect(port)) return discoveryFromRecipe(bin, recipe);
+	const useRamShm = recipe.postmasterArgs.includes("--ram");
+	const lockPath = `${dataDir}.lock`;
+	const holder = tryColdStartLock(lockPath);
+	if (holder == null) try {
+		if (!await canConnect(port) && liveDataDirOwner(dataDir) == null) await coldStartEphemeral(bin, recipe, useRamShm);
+	} finally {
+		rmSync(lockPath, { force: true });
+	}
+	if (await waitForListener({
+		port,
+		readyMs: HOST_READY_MS
+	})) return discoveryFromRecipe(bin, recipe);
+	const owner = holder != null ? `cold start pid ${holder}` : `postmaster pid ${liveDataDirOwner(dataDir) ?? "?"}`;
+	throw new Error(formatHostStartError(`${owner} owns ${dataDir} but did not accept 127.0.0.1:${port} within ${HOST_READY_MS}ms`, useRamShm));
+}
+/** Prune our dead leftover data dir and start the postmaster. Caller holds the cold-start lock. */
+async function coldStartEphemeral(bin, recipe, useRamShm) {
+	rmSync(recipe.dataDir, {
+		recursive: true,
+		force: true
+	});
+	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 });
+	try {
+		await spawnDetachedPostmaster({
+			bin,
+			args: recipe.postmasterArgs,
+			port: recipe.port,
+			readyMs: HOST_READY_MS
+		});
+	} catch (err) {
+		if (liveDataDirOwner(recipe.dataDir) != null) return;
+		throw new Error(formatHostStartError(errorDetail(err), useRamShm));
+	}
+}
+let autopgVersionChecked = false;
+/** Once per process: warn (never fail, never upgrade) when autopg is older than the pin. */
+function warnIfAutopgOutdated(bin) {
+	if (autopgVersionChecked) return;
+	autopgVersionChecked = true;
+	const warning = outdatedAutopgWarning(readAutopgVersion(bin));
+	if (warning) process.stderr.write(warning);
+}
+/**
+* Attach to a listening autopg host, else start one per
+* {@link resolveHostStartPolicy}. Internal: callers use `acquire` / `adminUrl`.
+*/
+async function ensureHostRunning(bin = requireAutopgBin()) {
+	warnIfAutopgOutdated(bin);
+	let registered = null;
+	try {
+		registered = discoverRegistration(bin);
+	} catch {}
+	if (registered && await waitForListener({ port: registered.host.port })) return registered.host;
+	return resolveHostStartPolicy() === "ephemeral" ? startEphemeralHost(bin) : startLocalHost(bin, registered);
+}
+//#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 leased = readLease(identity.root, mode);
+	const roleName = leased?.databaseName === databaseName ? leased.roleName : buildRoleName(databaseName);
+	const host = await ensureHostRunning();
+	if (options.fresh) await dropDatabasesOwnedByRole({
+		adminUrl: host.adminUrl,
+		roleName,
+		preferLast: databaseName
+	});
+	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
+	};
+}
+/**
+* Attach-only: connection info from the lease a prior `acquire` wrote. Never
+* acquires, never runs role/database DDL, never starts or revives the host —
+* safe for many concurrent children after one `db:ready`. Throws when there is
+* no lease or nothing accepts TCP on the leased port.
+*/
+async function attach(options) {
+	const root = resolveRoot(options.root);
+	const { mode } = options;
+	const lease = readLease(root, mode);
+	if (!lease) throw new Error(`no ${mode} lease in ${root}; run \`${CLI_NAME} acquire --mode=${mode}\` (or your db:ready target) first — attach never acquires`);
+	if (!await waitForListener({ port: lease.port })) throw new Error(`${mode} lease ${lease.databaseName} points at 127.0.0.1:${lease.port}, but nothing is listening; re-run \`${CLI_NAME} acquire --mode=${mode}\` to bring the host back`);
+	return {
+		lease,
+		databaseUrl: urlFromLease(lease)
+	};
+}
+/**
+* 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,
+		fresh: options.fresh
+	}));
+	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 mode = options.mode ?? "test";
+	const lease = readLease(resolveRoot(options.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 { resolveAcquireSkip as C, buildRoleName as D, buildDatabaseName as E, isExternalDatabaseEscapeHatch as S, buildCloneDatabaseName as T, rolePasswordFor as _, gc as a, applyDatabaseUrlEnv as b, ROLE_PASSWORD_SCHEME as c, cloneDatabaseFromTemplate as d, discoverHost as f, resolveAutopgBin as g, requireAutopgBin as h, dispose as i, adminUrlFor as l, parseHostStatus as m, acquireIfNeeded as n, urlFromLease as o, dropDatabase as p, attach as r, INSTALL_HINT as s, acquire as t, buildDatabaseUrl as u, setDatabaseIsTemplate as v, runIfNeeded as w, isCedarPgManagedUrl as x, truncateUserTables as y };
+
+//# sourceMappingURL=lifecycle-2BZgSVz2.mjs.map