@rebasepro/cli 0.16.0 → 0.16.1-canary.g041c925

package/dist/daemon-entry-Brq-S8XX.js

@@ -0,0 +1,378 @@
+import { a as findFreePort, d as writeState, n as clearState, r as dataDir } from "./state-c0CJ6Kwb.js";
+import { n as PGLITE_EXTENSION_NAMES } from "./constraints-BK1_4vci.js";
+import fs from "fs";
+import net from "net";
+//#region src/dev-db/notification-proxy.ts
+/**
+* A transparent Postgres proxy that puts LISTEN/NOTIFY back.
+*
+* Without this, realtime does not work against the managed database — and it
+* fails silently, which is worse than failing. The reason is specific and
+* measurable:
+*
+* PGlite is a *single* backend session, and `PGLiteSocketServer` multiplexes
+* every client connection onto it. `LISTEN` is therefore session-wide: whichever
+* client issues it arms the whole database. But a `NotificationResponse` is an
+* asynchronous message with no request to answer, so the multiplexer hands it to
+* whichever socket happens to be reading the protocol stream at that moment —
+* which is the client that *caused* the notification, not the one that asked for
+* it.
+*
+* Measured against pglite-socket 0.2.9:
+*
+*   LISTEN and NOTIFY on one connection      → delivered
+*   trigger-fired pg_notify, same connection → delivered
+*   another connection causes the notify     → NOT delivered to the listener
+*   …and the same notification IS delivered to the notifier, which never asked
+*
+* The realtime engine listens on a dedicated connection and the writes come
+* from request connections, so it is exactly the broken case, every time.
+*
+* The fix is to stop treating a notification as belonging to one connection,
+* which for a single-session database is the truth anyway: this proxy watches
+* the server→client direction, and every `NotificationResponse` frame it sees is
+* copied to every other connected client. A client that never issued `LISTEN`
+* may receive one it did not ask for; `pg` raises a `notification` event nobody
+* has subscribed to, which costs nothing. A client that *did* ask now always
+* gets it, which is the whole point.
+*
+* Two properties make this safe rather than clever:
+*
+* - **It never parses SQL and never rewrites a byte.** Frames are forwarded
+*   verbatim; the only edit is delivering a copy of one to more sockets.
+* - **Injection only happens on a message boundary.** The server→client stream
+*   is reassembled into whole protocol messages before anything is written on,
+*   so an injected frame can never land inside another message.
+*
+* This exists only for the managed development database. Against a real Postgres
+* there is no proxy, because there is no defect to correct.
+*/
+/** `NotificationResponse`. The one message type this proxy treats specially. */
+var NOTIFICATION_RESPONSE = 65;
+/**
+* The SSL negotiation request, which is the one thing on the wire that is not
+* a typed message.
+*
+* A client may open with an 8-byte `SSLRequest` (length 8, code 80877103), and
+* the server answers with a *single untyped byte* — `N` or `S`. Feeding that
+* byte to a parser expecting `type + Int32 length` would desynchronise the
+* stream for the rest of the connection, so it is recognised and passed through.
+*/
+var SSL_REQUEST_LENGTH = 8;
+var SSL_REQUEST_CODE = 80877103;
+function isSslRequest(chunk) {
+	return chunk.length >= SSL_REQUEST_LENGTH && chunk.readInt32BE(0) === SSL_REQUEST_LENGTH && chunk.readInt32BE(4) === SSL_REQUEST_CODE;
+}
+/**
+* Reassembles a server→client byte stream into whole protocol messages.
+*
+* Every backend message is `Int8 type` + `Int32 length` + payload, where the
+* length counts itself but not the type byte. Anything shorter than a full
+* message is held until the rest arrives — TCP offers no guarantee that a
+* message arrives in one chunk, and a proxy that assumed otherwise would inject
+* into the middle of a row description under load.
+*/
+var BackendMessageParser = class {
+	buffered = Buffer.alloc(0);
+	/** Set once the untyped SSL negotiation byte has been dealt with. */
+	awaitingSslReply = false;
+	expectSslReply() {
+		this.awaitingSslReply = true;
+	}
+	/** Feed bytes in; get whole messages out, in order. */
+	push(chunk) {
+		const messages = [];
+		this.buffered = this.buffered.length === 0 ? chunk : Buffer.concat([this.buffered, chunk]);
+		if (this.awaitingSslReply && this.buffered.length >= 1) {
+			messages.push(this.buffered.subarray(0, 1));
+			this.buffered = this.buffered.subarray(1);
+			this.awaitingSslReply = false;
+		}
+		while (this.buffered.length >= 5) {
+			const length = this.buffered.readInt32BE(1);
+			if (length < 4) break;
+			const total = length + 1;
+			if (this.buffered.length < total) break;
+			messages.push(this.buffered.subarray(0, total));
+			this.buffered = this.buffered.subarray(total);
+		}
+		return messages;
+	}
+	/** Bytes held back because they are not yet a whole message. */
+	get pending() {
+		return this.buffered.length;
+	}
+};
+function isNotificationFrame(message) {
+	return message.length > 0 && message[0] === NOTIFICATION_RESPONSE;
+}
+/** Channel and payload of a NotificationResponse, for logging and tests. */
+function decodeNotification(message) {
+	if (!isNotificationFrame(message) || message.length < 10) return null;
+	const body = message.subarray(9);
+	const split = body.indexOf(0);
+	if (split === -1) return null;
+	const channel = body.subarray(0, split).toString("utf8");
+	const rest = body.subarray(split + 1);
+	const end = rest.indexOf(0);
+	return {
+		channel,
+		payload: (end === -1 ? rest : rest.subarray(0, end)).toString("utf8")
+	};
+}
+/**
+* The proxy itself.
+*
+* One upstream connection per client connection, so the multiplexer downstream
+* sees exactly what it would have seen without the proxy.
+*/
+var NotificationProxy = class {
+	options;
+	server = null;
+	connections = /* @__PURE__ */ new Set();
+	constructor(options) {
+		this.options = options;
+	}
+	get connectionCount() {
+		return this.connections.size;
+	}
+	start() {
+		const host = this.options.host ?? "127.0.0.1";
+		return new Promise((resolve, reject) => {
+			const server = net.createServer((client) => this.accept(client, host));
+			server.once("error", reject);
+			server.listen(this.options.listenPort, host, () => {
+				this.server = server;
+				resolve();
+			});
+		});
+	}
+	accept(client, host) {
+		const upstream = net.connect(this.options.upstreamPort, host);
+		const connection = {
+			client,
+			upstream,
+			parser: new BackendMessageParser()
+		};
+		this.connections.add(connection);
+		client.setNoDelay(true);
+		upstream.setNoDelay(true);
+		client.on("data", (chunk) => {
+			if (isSslRequest(chunk)) connection.parser.expectSslReply();
+			upstream.write(chunk);
+		});
+		upstream.on("data", (chunk) => {
+			for (const message of connection.parser.push(chunk)) {
+				client.write(message);
+				if (isNotificationFrame(message)) this.broadcast(message, connection);
+			}
+		});
+		const close = () => {
+			this.connections.delete(connection);
+			client.destroy();
+			upstream.destroy();
+		};
+		client.on("close", close);
+		client.on("error", close);
+		upstream.on("close", close);
+		upstream.on("error", close);
+	}
+	/**
+	* Copy a notification to every other client.
+	*
+	* Written directly rather than through a parser: it is already a whole
+	* message, and every other socket is only ever written whole messages, so
+	* there is no boundary to land inside.
+	*/
+	broadcast(message, origin) {
+		let copies = 0;
+		for (const connection of this.connections) {
+			if (connection === origin) continue;
+			if (connection.client.destroyed || !connection.client.writable) continue;
+			connection.client.write(message);
+			copies += 1;
+		}
+		const decoded = decodeNotification(message);
+		if (decoded) this.options.onNotification?.(decoded.channel, decoded.payload, copies);
+	}
+	async stop() {
+		for (const connection of [...this.connections]) {
+			connection.client.destroy();
+			connection.upstream.destroy();
+		}
+		this.connections.clear();
+		const server = this.server;
+		this.server = null;
+		if (!server) return;
+		await new Promise((resolve) => server.close(() => resolve()));
+	}
+};
+//#endregion
+//#region src/dev-db/daemon-entry.ts
+/**
+* The managed database process: one PGlite instance behind a Postgres socket.
+*
+* Runs as `rebase __dev-db-daemon`, a hidden subcommand rather than a separate
+* build entry point, so the same resolution works from `src` under tsx and from
+* the bundled `dist` a published CLI ships — there is no second file for a
+* build config to forget.
+*
+* It is deliberately detached from whoever started it. `rebase db push` in one
+* terminal and `rebase dev` in another must reach the same database, because
+* two processes opening one PGlite data directory would corrupt it, so the
+* daemon belongs to the *project* rather than to a command. What starts it is
+* incidental; what stops it is an explicit `rebase db stop`, an idle timeout,
+* or the machine going away.
+*
+* PGlite is imported dynamically. It is an optional dependency carrying a 25MB
+* WASM build, and the cost of that must fall only on someone who actually uses
+* the managed database — never on `rebase init`, and never on a CLI startup
+* that is about to print help.
+*/
+/** Shut down after this long with nothing connected. */
+var DEFAULT_IDLE_TIMEOUT_MS = 30 * 6e4;
+/** How often to check for idleness. */
+var IDLE_CHECK_INTERVAL_MS = 6e4;
+/**
+* `--project <dir> --port <n> --token <t> [--idle-timeout <ms>]`.
+*
+* Every field is required and unvalidated input is fatal: this process is
+* spawned by the CLI, never typed by a person, so a malformed argument is a bug
+* in the caller and guessing would hide it.
+*/
+function parseDaemonArgs(argv) {
+	const take = (flag) => {
+		const index = argv.indexOf(flag);
+		return index >= 0 && index + 1 < argv.length ? argv[index + 1] : null;
+	};
+	const projectRoot = take("--project");
+	const port = Number(take("--port"));
+	const token = take("--token");
+	const idleRaw = take("--idle-timeout");
+	if (!projectRoot) throw new Error("__dev-db-daemon: --project is required");
+	if (!Number.isInteger(port) || port <= 0 || port > 65535) throw new Error("__dev-db-daemon: --port must be a valid port");
+	if (!token) throw new Error("__dev-db-daemon: --token is required");
+	const idleTimeoutMs = idleRaw === null ? DEFAULT_IDLE_TIMEOUT_MS : Number(idleRaw);
+	if (!Number.isFinite(idleTimeoutMs) || idleTimeoutMs < 0) throw new Error("__dev-db-daemon: --idle-timeout must be a non-negative number of milliseconds");
+	return {
+		projectRoot,
+		port,
+		token,
+		idleTimeoutMs
+	};
+}
+/**
+* Load the extension bundles PGlite needs by name.
+*
+* `CREATE EXTENSION pg_trgm` cannot install anything on its own here — PGlite
+* resolves extensions from bundles handed to the constructor, and a missing one
+* fails at migration time with `extension "pg_trgm" is not available`, which
+* reads like a broken database rather than a missing import.
+*/
+async function loadExtensions() {
+	const extensions = {};
+	for (const name of PGLITE_EXTENSION_NAMES) {
+		const bundle = (await import(`@electric-sql/pglite/contrib/${name}`))[name];
+		if (!bundle) throw new Error(`@electric-sql/pglite/contrib/${name} did not export "${name}". The installed PGlite version may not ship this extension.`);
+		extensions[name] = bundle;
+	}
+	return extensions;
+}
+/**
+* A tiny sidecar listener that answers one question: "are you the daemon this
+* state file describes?"
+*
+* Liveness cannot be answered by the pid — after a reboot the number belongs to
+* something else — nor by the port alone, for the same reason. Both would let
+* Rebase send a migration to a stranger. So the daemon publishes a token on a
+* second loopback port and the answer is only yes when the token matches.
+*/
+function startIdentityServer(token, onConnection) {
+	return new Promise((resolve, reject) => {
+		const server = net.createServer((socket) => {
+			onConnection();
+			socket.end(`rebase-dev-db ${token}\n`);
+		});
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", () => resolve(server));
+	});
+}
+async function runDaemon(args) {
+	const directory = dataDir(args.projectRoot);
+	fs.mkdirSync(directory, { recursive: true });
+	const { PGlite } = await import("@electric-sql/pglite");
+	const { PGLiteSocketServer } = await import("@electric-sql/pglite-socket");
+	const extensions = await loadExtensions();
+	const db = await PGlite.create({
+		dataDir: directory,
+		extensions
+	});
+	const upstreamPort = await findFreePort();
+	const server = new PGLiteSocketServer({
+		db,
+		port: upstreamPort,
+		host: "127.0.0.1",
+		maxConnections: 4
+	});
+	await server.start();
+	const proxy = new NotificationProxy({
+		listenPort: args.port,
+		upstreamPort,
+		onNotification: (channel, _payload, copies) => {
+			if (copies > 0) process.stdout.write(`dev-db: relayed notification on ${channel} to ${copies} client(s)\n`);
+		}
+	});
+	await proxy.start();
+	let idleSince = Date.now();
+	const identity = await startIdentityServer(args.token, () => {
+		idleSince = null;
+	});
+	const identityAddress = identity.address();
+	const identityPort = identityAddress !== null && typeof identityAddress !== "string" ? identityAddress.port : 0;
+	writeState(args.projectRoot, {
+		port: args.port,
+		pid: process.pid,
+		dataDir: directory,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		token: args.token,
+		identityPort
+	});
+	let shuttingDown = false;
+	const shutdown = async (reason) => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		process.stdout.write(`dev-db: stopping (${reason})\n`);
+		clearState(args.projectRoot);
+		try {
+			await proxy.stop();
+		} catch {}
+		try {
+			await server.stop();
+		} catch {}
+		identity.close();
+		try {
+			await db.close();
+		} catch {}
+		process.exit(0);
+	};
+	process.on("SIGINT", () => void shutdown("SIGINT"));
+	process.on("SIGTERM", () => void shutdown("SIGTERM"));
+	process.on("disconnect", () => {});
+	if (args.idleTimeoutMs > 0) setInterval(() => {
+		const stats = server.getStats();
+		if (stats.activeConnections > 0 || stats.queuedQueries > 0) {
+			idleSince = null;
+			return;
+		}
+		if (idleSince === null) {
+			idleSince = Date.now();
+			return;
+		}
+		if (Date.now() - idleSince >= args.idleTimeoutMs) shutdown(`idle for ${Math.round(args.idleTimeoutMs / 6e4)} minutes`);
+	}, IDLE_CHECK_INTERVAL_MS).unref();
+	process.stdout.write(`dev-db: ready on 127.0.0.1:${args.port}\n`);
+}
+//#endregion
+export { parseDaemonArgs, runDaemon };
+
+//# sourceMappingURL=daemon-entry-Brq-S8XX.js.map

package/dist/daemon-entry-Brq-S8XX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-entry-Brq-S8XX.js","names":[],"sources":["../src/dev-db/notification-proxy.ts","../src/dev-db/daemon-entry.ts"],"sourcesContent":["/**\n * A transparent Postgres proxy that puts LISTEN/NOTIFY back.\n *\n * Without this, realtime does not work against the managed database — and it\n * fails silently, which is worse than failing. The reason is specific and\n * measurable:\n *\n * PGlite is a *single* backend session, and `PGLiteSocketServer` multiplexes\n * every client connection onto it. `LISTEN` is therefore session-wide: whichever\n * client issues it arms the whole database. But a `NotificationResponse` is an\n * asynchronous message with no request to answer, so the multiplexer hands it to\n * whichever socket happens to be reading the protocol stream at that moment —\n * which is the client that *caused* the notification, not the one that asked for\n * it.\n *\n * Measured against pglite-socket 0.2.9:\n *\n *   LISTEN and NOTIFY on one connection      → delivered\n *   trigger-fired pg_notify, same connection → delivered\n *   another connection causes the notify     → NOT delivered to the listener\n *   …and the same notification IS delivered to the notifier, which never asked\n *\n * The realtime engine listens on a dedicated connection and the writes come\n * from request connections, so it is exactly the broken case, every time.\n *\n * The fix is to stop treating a notification as belonging to one connection,\n * which for a single-session database is the truth anyway: this proxy watches\n * the server→client direction, and every `NotificationResponse` frame it sees is\n * copied to every other connected client. A client that never issued `LISTEN`\n * may receive one it did not ask for; `pg` raises a `notification` event nobody\n * has subscribed to, which costs nothing. A client that *did* ask now always\n * gets it, which is the whole point.\n *\n * Two properties make this safe rather than clever:\n *\n * - **It never parses SQL and never rewrites a byte.** Frames are forwarded\n *   verbatim; the only edit is delivering a copy of one to more sockets.\n * - **Injection only happens on a message boundary.** The server→client stream\n *   is reassembled into whole protocol messages before anything is written on,\n *   so an injected frame can never land inside another message.\n *\n * This exists only for the managed development database. Against a real Postgres\n * there is no proxy, because there is no defect to correct.\n */\n\nimport net from \"net\";\n\n/** `NotificationResponse`. The one message type this proxy treats specially. */\nconst NOTIFICATION_RESPONSE = 0x41; // 'A'\n\n/**\n * The SSL negotiation request, which is the one thing on the wire that is not\n * a typed message.\n *\n * A client may open with an 8-byte `SSLRequest` (length 8, code 80877103), and\n * the server answers with a *single untyped byte* — `N` or `S`. Feeding that\n * byte to a parser expecting `type + Int32 length` would desynchronise the\n * stream for the rest of the connection, so it is recognised and passed through.\n */\nconst SSL_REQUEST_LENGTH = 8;\nconst SSL_REQUEST_CODE = 80877103;\n\nfunction isSslRequest(chunk: Buffer): boolean {\n    return (\n        chunk.length >= SSL_REQUEST_LENGTH &&\n        chunk.readInt32BE(0) === SSL_REQUEST_LENGTH &&\n        chunk.readInt32BE(4) === SSL_REQUEST_CODE\n    );\n}\n\n/**\n * Reassembles a server→client byte stream into whole protocol messages.\n *\n * Every backend message is `Int8 type` + `Int32 length` + payload, where the\n * length counts itself but not the type byte. Anything shorter than a full\n * message is held until the rest arrives — TCP offers no guarantee that a\n * message arrives in one chunk, and a proxy that assumed otherwise would inject\n * into the middle of a row description under load.\n */\nexport class BackendMessageParser {\n    private buffered: Buffer = Buffer.alloc(0);\n    /** Set once the untyped SSL negotiation byte has been dealt with. */\n    private awaitingSslReply = false;\n\n    expectSslReply(): void {\n        this.awaitingSslReply = true;\n    }\n\n    /** Feed bytes in; get whole messages out, in order. */\n    push(chunk: Buffer): Buffer[] {\n        const messages: Buffer[] = [];\n        this.buffered = this.buffered.length === 0 ? chunk : Buffer.concat([this.buffered, chunk]);\n\n        if (this.awaitingSslReply && this.buffered.length >= 1) {\n            // Single untyped byte: 'N' (no SSL) or 'S' (proceed).\n            messages.push(this.buffered.subarray(0, 1));\n            this.buffered = this.buffered.subarray(1);\n            this.awaitingSslReply = false;\n        }\n\n        while (this.buffered.length >= 5) {\n            const length = this.buffered.readInt32BE(1);\n            // A length below 4 cannot describe itself; the stream is not one we\n            // understand, so stop parsing and let the rest through untouched\n            // rather than guessing.\n            if (length < 4) break;\n            const total = length + 1;\n            if (this.buffered.length < total) break;\n            messages.push(this.buffered.subarray(0, total));\n            this.buffered = this.buffered.subarray(total);\n        }\n\n        return messages;\n    }\n\n    /** Bytes held back because they are not yet a whole message. */\n    get pending(): number {\n        return this.buffered.length;\n    }\n}\n\nexport function isNotificationFrame(message: Buffer): boolean {\n    return message.length > 0 && message[0] === NOTIFICATION_RESPONSE;\n}\n\n/** Channel and payload of a NotificationResponse, for logging and tests. */\nexport function decodeNotification(message: Buffer): { channel: string; payload: string } | null {\n    if (!isNotificationFrame(message) || message.length < 10) return null;\n    // 1 type byte + 4 length + 4 process id, then two null-terminated strings.\n    const body = message.subarray(9);\n    const split = body.indexOf(0);\n    if (split === -1) return null;\n    const channel = body.subarray(0, split).toString(\"utf8\");\n    const rest = body.subarray(split + 1);\n    const end = rest.indexOf(0);\n\n    return { channel, payload: (end === -1 ? rest : rest.subarray(0, end)).toString(\"utf8\") };\n}\n\nexport interface NotificationProxyOptions {\n    /** Port clients connect to. */\n    listenPort: number;\n    /** Port the real PGlite socket server is on. */\n    upstreamPort: number;\n    host?: string;\n    /** Called for every notification broadcast. For diagnostics and tests. */\n    onNotification?: (channel: string, payload: string, copies: number) => void;\n}\n\ninterface Connection {\n    client: net.Socket;\n    upstream: net.Socket;\n    parser: BackendMessageParser;\n}\n\n/**\n * The proxy itself.\n *\n * One upstream connection per client connection, so the multiplexer downstream\n * sees exactly what it would have seen without the proxy.\n */\nexport class NotificationProxy {\n    private server: net.Server | null = null;\n    private readonly connections = new Set<Connection>();\n\n    constructor(private readonly options: NotificationProxyOptions) {}\n\n    get connectionCount(): number {\n        return this.connections.size;\n    }\n\n    start(): Promise<void> {\n        const host = this.options.host ?? \"127.0.0.1\";\n\n        return new Promise((resolve, reject) => {\n            const server = net.createServer((client) => this.accept(client, host));\n            server.once(\"error\", reject);\n            server.listen(this.options.listenPort, host, () => {\n                this.server = server;\n                resolve();\n            });\n        });\n    }\n\n    private accept(client: net.Socket, host: string): void {\n        const upstream = net.connect(this.options.upstreamPort, host);\n        const connection: Connection = { client, upstream, parser: new BackendMessageParser() };\n        this.connections.add(connection);\n\n        // Nagle would batch a notification behind nothing at all, adding latency\n        // to the one message whose entire value is arriving promptly.\n        client.setNoDelay(true);\n        upstream.setNoDelay(true);\n\n        client.on(\"data\", (chunk: Buffer) => {\n            if (isSslRequest(chunk)) connection.parser.expectSslReply();\n            upstream.write(chunk);\n        });\n\n        upstream.on(\"data\", (chunk: Buffer) => {\n            for (const message of connection.parser.push(chunk)) {\n                client.write(message);\n                if (isNotificationFrame(message)) this.broadcast(message, connection);\n            }\n        });\n\n        const close = () => {\n            this.connections.delete(connection);\n            client.destroy();\n            upstream.destroy();\n        };\n        client.on(\"close\", close);\n        client.on(\"error\", close);\n        upstream.on(\"close\", close);\n        upstream.on(\"error\", close);\n    }\n\n    /**\n     * Copy a notification to every other client.\n     *\n     * Written directly rather than through a parser: it is already a whole\n     * message, and every other socket is only ever written whole messages, so\n     * there is no boundary to land inside.\n     */\n    private broadcast(message: Buffer, origin: Connection): void {\n        let copies = 0;\n        for (const connection of this.connections) {\n            if (connection === origin) continue;\n            if (connection.client.destroyed || !connection.client.writable) continue;\n            connection.client.write(message);\n            copies += 1;\n        }\n\n        const decoded = decodeNotification(message);\n        if (decoded) this.options.onNotification?.(decoded.channel, decoded.payload, copies);\n    }\n\n    async stop(): Promise<void> {\n        for (const connection of [...this.connections]) {\n            connection.client.destroy();\n            connection.upstream.destroy();\n        }\n        this.connections.clear();\n\n        const server = this.server;\n        this.server = null;\n        if (!server) return;\n\n        await new Promise<void>((resolve) => server.close(() => resolve()));\n    }\n}\n","/**\n * The managed database process: one PGlite instance behind a Postgres socket.\n *\n * Runs as `rebase __dev-db-daemon`, a hidden subcommand rather than a separate\n * build entry point, so the same resolution works from `src` under tsx and from\n * the bundled `dist` a published CLI ships — there is no second file for a\n * build config to forget.\n *\n * It is deliberately detached from whoever started it. `rebase db push` in one\n * terminal and `rebase dev` in another must reach the same database, because\n * two processes opening one PGlite data directory would corrupt it, so the\n * daemon belongs to the *project* rather than to a command. What starts it is\n * incidental; what stops it is an explicit `rebase db stop`, an idle timeout,\n * or the machine going away.\n *\n * PGlite is imported dynamically. It is an optional dependency carrying a 25MB\n * WASM build, and the cost of that must fall only on someone who actually uses\n * the managed database — never on `rebase init`, and never on a CLI startup\n * that is about to print help.\n */\n\nimport fs from \"fs\";\nimport net from \"net\";\n\nimport {\n    MANAGED_SERVER_MAX_CONNECTIONS,\n    PGLITE_EXTENSION_NAMES\n} from \"./constraints\";\nimport { NotificationProxy } from \"./notification-proxy\";\nimport { clearState, dataDir, findFreePort, writeState } from \"./state\";\n\n/** Shut down after this long with nothing connected. */\nconst DEFAULT_IDLE_TIMEOUT_MS = 30 * 60_000;\n\n/** How often to check for idleness. */\nconst IDLE_CHECK_INTERVAL_MS = 60_000;\n\nexport interface DaemonArgs {\n    projectRoot: string;\n    port: number;\n    token: string;\n    idleTimeoutMs: number;\n}\n\n/**\n * `--project <dir> --port <n> --token <t> [--idle-timeout <ms>]`.\n *\n * Every field is required and unvalidated input is fatal: this process is\n * spawned by the CLI, never typed by a person, so a malformed argument is a bug\n * in the caller and guessing would hide it.\n */\nexport function parseDaemonArgs(argv: readonly string[]): DaemonArgs {\n    const take = (flag: string): string | null => {\n        const index = argv.indexOf(flag);\n\n        return index >= 0 && index + 1 < argv.length ? argv[index + 1] : null;\n    };\n\n    const projectRoot = take(\"--project\");\n    const port = Number(take(\"--port\"));\n    const token = take(\"--token\");\n    const idleRaw = take(\"--idle-timeout\");\n\n    if (!projectRoot) throw new Error(\"__dev-db-daemon: --project is required\");\n    if (!Number.isInteger(port) || port <= 0 || port > 65535) {\n        throw new Error(\"__dev-db-daemon: --port must be a valid port\");\n    }\n    if (!token) throw new Error(\"__dev-db-daemon: --token is required\");\n\n    const idleTimeoutMs = idleRaw === null ? DEFAULT_IDLE_TIMEOUT_MS : Number(idleRaw);\n    if (!Number.isFinite(idleTimeoutMs) || idleTimeoutMs < 0) {\n        throw new Error(\"__dev-db-daemon: --idle-timeout must be a non-negative number of milliseconds\");\n    }\n\n    return { projectRoot, port, token, idleTimeoutMs };\n}\n\n/**\n * Load the extension bundles PGlite needs by name.\n *\n * `CREATE EXTENSION pg_trgm` cannot install anything on its own here — PGlite\n * resolves extensions from bundles handed to the constructor, and a missing one\n * fails at migration time with `extension \"pg_trgm\" is not available`, which\n * reads like a broken database rather than a missing import.\n */\nasync function loadExtensions(): Promise<Record<string, unknown>> {\n    const extensions: Record<string, unknown> = {};\n    for (const name of PGLITE_EXTENSION_NAMES) {\n        const module = (await import(`@electric-sql/pglite/contrib/${name}`)) as Record<string, unknown>;\n        const bundle = module[name];\n        if (!bundle) {\n            throw new Error(\n                `@electric-sql/pglite/contrib/${name} did not export \"${name}\". ` +\n                \"The installed PGlite version may not ship this extension.\"\n            );\n        }\n        extensions[name] = bundle;\n    }\n\n    return extensions;\n}\n\n/**\n * A tiny sidecar listener that answers one question: \"are you the daemon this\n * state file describes?\"\n *\n * Liveness cannot be answered by the pid — after a reboot the number belongs to\n * something else — nor by the port alone, for the same reason. Both would let\n * Rebase send a migration to a stranger. So the daemon publishes a token on a\n * second loopback port and the answer is only yes when the token matches.\n */\nfunction startIdentityServer(token: string, onConnection: () => void): Promise<net.Server> {\n    return new Promise((resolve, reject) => {\n        const server = net.createServer((socket) => {\n            onConnection();\n            socket.end(`rebase-dev-db ${token}\\n`);\n        });\n        server.once(\"error\", reject);\n        server.listen(0, \"127.0.0.1\", () => resolve(server));\n    });\n}\n\nexport async function runDaemon(args: DaemonArgs): Promise<void> {\n    const directory = dataDir(args.projectRoot);\n    fs.mkdirSync(directory, { recursive: true });\n\n    const { PGlite } = (await import(\"@electric-sql/pglite\")) as {\n        PGlite: { create(options: unknown): Promise<unknown> };\n    };\n    const { PGLiteSocketServer } = (await import(\"@electric-sql/pglite-socket\")) as {\n        PGLiteSocketServer: new (options: unknown) => {\n            start(): Promise<void>;\n            stop(): Promise<void>;\n            getStats(): { activeConnections: number; queuedQueries: number };\n        };\n    };\n\n    const extensions = await loadExtensions();\n    const db = (await PGlite.create({ dataDir: directory, extensions })) as { close(): Promise<void> };\n\n    // The socket server listens privately; clients reach it through the\n    // notification proxy on `args.port`. Realtime does not work otherwise —\n    // PGlite is one session, so a NotificationResponse is handed to whichever\n    // socket is reading rather than to the one that issued LISTEN. See\n    // `notification-proxy.ts` for the measurements.\n    const upstreamPort = await findFreePort();\n    const server = new PGLiteSocketServer({\n        db,\n        port: upstreamPort,\n        host: \"127.0.0.1\",\n        // Above the client pool limit so a second *non-transactional* client is\n        // refused with a connection error rather than deadlocking the\n        // multiplexer. See `constraints.ts` — the pool limit is what actually\n        // prevents overlapping transactions.\n        maxConnections: MANAGED_SERVER_MAX_CONNECTIONS\n    });\n    await server.start();\n\n    const proxy = new NotificationProxy({\n        listenPort: args.port,\n        upstreamPort,\n        onNotification: (channel, _payload, copies) => {\n            if (copies > 0) process.stdout.write(`dev-db: relayed notification on ${channel} to ${copies} client(s)\\n`);\n        }\n    });\n    await proxy.start();\n\n    // \"Idle\" means nothing is connected to the *database*. An earlier version\n    // tracked identity pings instead, which meant a daemon serving queries\n    // steadily for an hour would decide it was idle and shut down under a\n    // running dev server.\n    let idleSince: number | null = Date.now();\n    const identity = await startIdentityServer(args.token, () => {\n        idleSince = null;\n    });\n    const identityAddress = identity.address();\n    const identityPort = identityAddress !== null && typeof identityAddress !== \"string\" ? identityAddress.port : 0;\n\n    writeState(args.projectRoot, {\n        port: args.port,\n        pid: process.pid,\n        dataDir: directory,\n        startedAt: new Date().toISOString(),\n        token: args.token,\n        identityPort\n    });\n\n    let shuttingDown = false;\n    const shutdown = async (reason: string) => {\n        if (shuttingDown) return;\n        shuttingDown = true;\n        process.stdout.write(`dev-db: stopping (${reason})\\n`);\n        // The state file goes first: a command that reads it during shutdown\n        // should conclude \"not running\" and start a fresh daemon, rather than\n        // connect to a socket that is closing under it.\n        clearState(args.projectRoot);\n        try {\n            await proxy.stop();\n        } catch { /* already down */ }\n        try {\n            await server.stop();\n        } catch { /* already down */ }\n        identity.close();\n        try {\n            await db.close();\n        } catch { /* already closed */ }\n        process.exit(0);\n    };\n\n    process.on(\"SIGINT\", () => void shutdown(\"SIGINT\"));\n    process.on(\"SIGTERM\", () => void shutdown(\"SIGTERM\"));\n    // The parent going away must not take the database with it — the daemon\n    // belongs to the project. But an orphan with nobody left to serve should\n    // not outlive the session either, which is what the idle timer is for.\n    process.on(\"disconnect\", () => { /* detached on purpose */ });\n\n    if (args.idleTimeoutMs > 0) {\n        const timer = setInterval(() => {\n            const stats = server.getStats();\n            const busy = stats.activeConnections > 0 || stats.queuedQueries > 0;\n            if (busy) {\n                idleSince = null;\n\n                return;\n            }\n            if (idleSince === null) {\n                idleSince = Date.now();\n\n                return;\n            }\n            if (Date.now() - idleSince >= args.idleTimeoutMs) {\n                void shutdown(`idle for ${Math.round(args.idleTimeoutMs / 60_000)} minutes`);\n            }\n        }, IDLE_CHECK_INTERVAL_MS);\n        timer.unref();\n    }\n\n    process.stdout.write(`dev-db: ready on 127.0.0.1:${args.port}\\n`);\n}\n"],"mappings":"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"}

package/dist/dev-db/__fixtures__/cli-entry.d.ts

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

package/dist/dev-db/constraints.d.ts

@@ -0,0 +1,98 @@
+/**
+ * What PGlite can and cannot do as a development database, measured rather
+ * than assumed.
+ *
+ * Everything in this directory is shaped by four facts, each established by
+ * running it against `@electric-sql/pglite` 0.5.6 and
+ * `@electric-sql/pglite-socket` 0.2.9 rather than by reading their docs. They
+ * are recorded here because two of them are silent failures — the kind that
+ * make a developer lose an evening to a feature that reports success and does
+ * nothing.
+ *
+ * 1. **It is really PostgreSQL 18.3.** `select version()` over the socket
+ *    returns `PostgreSQL 18.3 (PGlite 0.5.6) on wasm32`, which is the same
+ *    major as the `postgres:18-alpine` the eject template ships. So a dev
+ *    database here and a compose database there are the same Postgres, and
+ *    schema behaviour does not diverge between them.
+ *
+ * 2. **`pg_trgm` and `unaccent` are available**, which is what search
+ *    collections need. They are not installed by a bare `CREATE EXTENSION`,
+ *    though — PGlite ships them as separate bundles that must be passed to the
+ *    constructor, and without that `CREATE EXTENSION pg_trgm` fails with
+ *    `extension "pg_trgm" is not available`. {@link PGLITE_EXTENSIONS} is that
+ *    list, and it has to stay in step with what the schema generator emits.
+ *
+ * 3. **RLS is enforced exactly as it is on a real server.** With
+ *    `SET LOCAL ROLE "rebase_user"` inside a transaction — which is how
+ *    `PostgresBackendDriver` isolates every request — `current_user` becomes
+ *    the restricted role, `session_user` stays the owner, and a policy using
+ *    `current_setting('app.tenant')` filters rows correctly, including under
+ *    `FORCE ROW LEVEL SECURITY`. Measured: an owner saw 3 rows and the
+ *    role-switched transaction saw 2, with the cross-tenant probe returning 0.
+ *    This is the one that mattered most: a dev database that quietly failed to
+ *    apply RLS would give false confidence about the product's central claim.
+ *
+ * 4. **Concurrency is the real limit, and it fails badly.** PGlite is a single
+ *    session, and `PGLiteSocketServer` multiplexes connections onto it. Two
+ *    pooled clients that hold *overlapping transactions* deadlock — not error,
+ *    hang — which is precisely what a request-per-transaction server does under
+ *    any concurrent load. {@link MANAGED_POOL_MAX} is the answer: one client
+ *    connection, so requests queue in the pool instead of deadlocking in the
+ *    multiplexer. Measured: with a pool of 1, four concurrent queries and a
+ *    role-switched RLS transaction all pass; with a pool of 5 the same script
+ *    hangs indefinitely.
+ *
+ * 5. **LISTEN/NOTIFY needed repairing, and now works.** A notification is an
+ *    asynchronous message with no request to answer, and the multiplexer hands
+ *    it to whichever socket is reading rather than to the one that issued
+ *    `LISTEN` — so a dedicated listener connection, which is exactly how the
+ *    realtime engine works, received nothing while the *writer* received
+ *    notifications it never asked for. `notification-proxy.ts` corrects that by
+ *    copying every `NotificationResponse` frame to every client, which for a
+ *    single-session database is simply the truth. Realtime therefore works
+ *    against the managed database, with no change to the server: it does
+ *    ordinary `LISTEN` over ordinary libpq.
+ */
+/**
+ * Extensions to hand PGlite's constructor.
+ *
+ * `CREATE EXTENSION` alone cannot install these — PGlite resolves them from
+ * bundles supplied at construction time, so anything missing here is missing
+ * from the database no matter what the migration says.
+ */
+export declare const PGLITE_EXTENSION_NAMES: readonly ["pg_trgm", "unaccent"];
+/**
+ * Client connections the managed database tolerates: exactly one.
+ *
+ * Not a tuning choice. Two concurrent transactions over the socket
+ * multiplexer deadlock, and a request-per-transaction server produces those
+ * the moment two requests overlap. One connection converts that deadlock into
+ * ordinary queueing, which is slower and correct.
+ */
+export declare const MANAGED_POOL_MAX = 1;
+/**
+ * Connections the socket server will accept.
+ *
+ * Above {@link MANAGED_POOL_MAX} so that a second *non-transactional* client —
+ * `rebase db push` in another terminal while `rebase dev` runs — is refused
+ * with a connection error rather than corrupting the multiplexer. The pool
+ * limit is what prevents overlapping transactions; this only stops a stampede.
+ */
+export declare const MANAGED_SERVER_MAX_CONNECTIONS = 4;
+/** What a managed PGlite database cannot do, in the words the user needs. */
+export interface ManagedLimitation {
+    /** Stable id, so a warning can be suppressed or tested for. */
+    id: string;
+    /** One line, naming the feature rather than the mechanism. */
+    summary: string;
+    /** What to do instead. Always a concrete command. */
+    remedy: string;
+}
+/**
+ * Announced at startup, every time, rather than discovered.
+ *
+ * A developer who does not know realtime is off will read the silence as a bug
+ * in their own code, which is a worse outcome than not offering the managed
+ * database at all.
+ */
+export declare const MANAGED_LIMITATIONS: readonly ManagedLimitation[];

package/dist/dev-db/daemon-entry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The managed database process: one PGlite instance behind a Postgres socket.
+ *
+ * Runs as `rebase __dev-db-daemon`, a hidden subcommand rather than a separate
+ * build entry point, so the same resolution works from `src` under tsx and from
+ * the bundled `dist` a published CLI ships — there is no second file for a
+ * build config to forget.
+ *
+ * It is deliberately detached from whoever started it. `rebase db push` in one
+ * terminal and `rebase dev` in another must reach the same database, because
+ * two processes opening one PGlite data directory would corrupt it, so the
+ * daemon belongs to the *project* rather than to a command. What starts it is
+ * incidental; what stops it is an explicit `rebase db stop`, an idle timeout,
+ * or the machine going away.
+ *
+ * PGlite is imported dynamically. It is an optional dependency carrying a 25MB
+ * WASM build, and the cost of that must fall only on someone who actually uses
+ * the managed database — never on `rebase init`, and never on a CLI startup
+ * that is about to print help.
+ */
+export interface DaemonArgs {
+    projectRoot: string;
+    port: number;
+    token: string;
+    idleTimeoutMs: number;
+}
+/**
+ * `--project <dir> --port <n> --token <t> [--idle-timeout <ms>]`.
+ *
+ * Every field is required and unvalidated input is fatal: this process is
+ * spawned by the CLI, never typed by a person, so a malformed argument is a bug
+ * in the caller and guessing would hide it.
+ */
+export declare function parseDaemonArgs(argv: readonly string[]): DaemonArgs;
+export declare function runDaemon(args: DaemonArgs): Promise<void>;

package/dist/dev-db/daemon.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Starting, finding and stopping the managed database, from the caller's side.
+ *
+ * Every command that needs Postgres calls {@link ensureManagedDatabase} and
+ * gets a connection string back. Whether that started a process or found one
+ * already running is not the caller's business, which is the point: `rebase
+ * db push`, `rebase dev` and `rebase studio` in three terminals must all reach
+ * the same database without coordinating, because two processes opening one
+ * PGlite data directory would corrupt it.
+ *
+ * The hard part is not starting the daemon; it is deciding whether the one the
+ * state file describes is still there. A pid can be recycled after a reboot and
+ * a port can be taken by a stranger, so believing either on its own would let
+ * Rebase send a migration somewhere unintended. {@link isDaemonAlive} asks the
+ * daemon to identify itself instead.
+ */
+import { type DaemonState } from "./state.js";
+export interface ManagedDatabase {
+    /** Connection string for this project's managed database. */
+    url: string;
+    /** Where the data lives, for diagnostics and `--reset`. */
+    dataDir: string;
+    port: number;
+    pid: number;
+    /** True when this call started the daemon rather than finding it. */
+    started: boolean;
+}
+export declare function managedUrl(port: number): string;
+/**
+ * Ask the process behind a state record to prove it is the one we wrote down.
+ *
+ * A pid check alone answers "is *a* process running", and a port check alone
+ * answers "is *something* listening" — after a reboot both say yes about
+ * strangers. The daemon answers with the token from its own state file, so a
+ * match is the only evidence accepted.
+ */
+export declare function isDaemonAlive(state: DaemonState): Promise<boolean>;
+/** The running daemon for this project, or `null`. Never starts anything. */
+export declare function findRunningDaemon(projectRoot: string): Promise<DaemonState | null>;
+/**
+ * How to re-invoke ourselves, which differs between a published CLI and this
+ * repository.
+ *
+ * A published `rebase` is `node bin/rebase.js`, and re-running that is trivial.
+ * Inside the monorepo the entry is TypeScript, which plain `node` cannot load —
+ * so the daemon has to be started through the same loader that is running now.
+ * Getting this wrong fails as a spawn that exits instantly with a syntax error,
+ * which is why the caller reads `pglite.log` on failure.
+ */
+export declare function resolveSpawn(entry: string): {
+    execPath: string;
+    prefixArgs: string[];
+};
+export interface EnsureOptions {
+    /** Silence the "starting…" progress line. */
+    quiet?: boolean;
+    /** Milliseconds of inactivity before the daemon exits. 0 disables. */
+    idleTimeoutMs?: number;
+    /** Where progress goes. Injected for tests. */
+    onProgress?: (message: string) => void;
+    /** Override how the daemon process is launched. For tests. */
+    spawn?: {
+        execPath: string;
+        prefixArgs: string[];
+    };
+    /**
+     * Override the CLI entry to re-invoke. For tests.
+     *
+     * Necessary because under a test runner `process.argv[1]` is the runner
+     * itself, which exists and is therefore accepted by {@link resolveCliEntry}
+     * — spawning vitest with `__dev-db-daemon` rather than the CLI.
+     */
+    entry?: string;
+}
+/**
+ * The project's managed database, started if it is not already running.
+ *
+ * Safe to call concurrently from several commands: the loser of the race finds
+ * the winner's state file during its poll and adopts it rather than starting a
+ * second daemon.
+ */
+export declare function ensureManagedDatabase(projectRoot: string, options?: EnsureOptions): Promise<ManagedDatabase>;
+/** Stop the daemon. Returns false when there was nothing running. */
+export declare function stopManagedDatabase(projectRoot: string): Promise<boolean>;
+/**
+ * Stop the daemon and delete the data directory.
+ *
+ * Destructive and deliberately not clever: it removes the whole directory
+ * rather than dropping schemas, because "give me an empty database" is the only
+ * thing anyone means by it.
+ */
+export declare function resetManagedDatabase(projectRoot: string): Promise<void>;