@rebasepro/cli 0.16.0 → 0.16.1-canary.g0d7af95

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>;

package/dist/dev-db/notification-proxy.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+export declare class BackendMessageParser {
+    private buffered;
+    /** Set once the untyped SSL negotiation byte has been dealt with. */
+    private awaitingSslReply;
+    expectSslReply(): void;
+    /** Feed bytes in; get whole messages out, in order. */
+    push(chunk: Buffer): Buffer[];
+    /** Bytes held back because they are not yet a whole message. */
+    get pending(): number;
+}
+export declare function isNotificationFrame(message: Buffer): boolean;
+/** Channel and payload of a NotificationResponse, for logging and tests. */
+export declare function decodeNotification(message: Buffer): {
+    channel: string;
+    payload: string;
+} | null;
+export interface NotificationProxyOptions {
+    /** Port clients connect to. */
+    listenPort: number;
+    /** Port the real PGlite socket server is on. */
+    upstreamPort: number;
+    host?: string;
+    /** Called for every notification broadcast. For diagnostics and tests. */
+    onNotification?: (channel: string, payload: string, copies: number) => void;
+}
+/**
+ * The proxy itself.
+ *
+ * One upstream connection per client connection, so the multiplexer downstream
+ * sees exactly what it would have seen without the proxy.
+ */
+export declare class NotificationProxy {
+    private readonly options;
+    private server;
+    private readonly connections;
+    constructor(options: NotificationProxyOptions);
+    get connectionCount(): number;
+    start(): Promise<void>;
+    private accept;
+    /**
+     * 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.
+     */
+    private broadcast;
+    stop(): Promise<void>;
+}

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

@@ -0,0 +1,63 @@
+/**
+ * The one place a command asks "which database, and how do I reach it?".
+ *
+ * Every command that touches Postgres — `dev`, and the whole `db` namespace
+ * through the driver plugin — goes through {@link prepareDatabaseEnv}. It
+ * resolves the ordering in `resolve.ts`, starts the managed database if that is
+ * what the ordering chose, and hands back the environment additions the child
+ * process needs.
+ *
+ * Two things it deliberately does *not* do:
+ *
+ * - **It never overwrites an existing `DATABASE_URL`.** When the developer has
+ *   named a database, the returned environment is empty and the child inherits
+ *   exactly what it would have inherited before this feature existed. A
+ *   migration must never be redirected away from the database its author meant.
+ *
+ * - **It never starts anything for a command that is not going to connect.**
+ *   `--help` and argument errors are handled by the caller before this is
+ *   reached, because booting a Postgres to print usage would be absurd.
+ */
+import { type DevDatabase } from "./resolve.js";
+export interface PrepareOptions {
+    /** `--database-url <url>`. */
+    flagUrl?: string | null;
+    /** `--docker`. */
+    flagDocker?: boolean;
+    /** Suppress the "starting…" progress line. */
+    quiet?: boolean;
+    /** Where human-facing lines go. Defaults to stdout via the caller. */
+    onProgress?: (message: string) => void;
+}
+export interface PreparedDatabase {
+    /** What the resolver chose, for the banner and for tests. */
+    database: DevDatabase;
+    /**
+     * Variables to add to a child process's environment.
+     *
+     * Empty for an external database: the child already has what it needs, and
+     * adding to it could only do harm.
+     */
+    env: Record<string, string>;
+    /** One line naming the database, suitable for a startup banner. */
+    description: string;
+    /** Absolute path of the managed data directory, when there is one. */
+    dataDir?: string;
+    /** True when this call started the managed database rather than finding it. */
+    startedDaemon?: boolean;
+}
+/**
+ * Resolve, start if needed, and describe the database for this command.
+ *
+ * `projectRoot` is where the managed database's data lives, so two projects on
+ * one machine get two databases without either being told about the other.
+ */
+export declare function prepareDatabaseEnv(projectRoot: string, options?: PrepareOptions): Promise<PreparedDatabase>;
+/**
+ * The lines to print about a managed database, in the order to print them.
+ *
+ * Returned rather than printed so the caller decides where they go — `dev` has
+ * a banner, `db push` has a single line above its own output — and so a test can
+ * assert on them without capturing a stream.
+ */
+export declare function managedNotices(prepared: PreparedDatabase): string[];

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

@@ -0,0 +1,92 @@
+/**
+ * `rebase db pull` — copy a database's contents into local development.
+ *
+ * The common case is production into local, and the reason it exists is that
+ * the alternative is worse: without it people hand-roll a `pg_dump | psql` and
+ * get the flags wrong in ways that either fail loudly at 2am or, more often,
+ * quietly restore half a schema.
+ *
+ * Three things this command insists on, because copying a production database
+ * onto a laptop is a data-protection event whether or not anyone calls it one:
+ *
+ * 1. **It says what it is about to do, in full, before doing it** — which
+ *    database it will read, which one it will overwrite, and where the data will
+ *    come to rest on disk. The target path matters: people forget that
+ *    `.rebase/pgdata` is a directory their backup software may be indexing.
+ *
+ * 2. **It refuses to run unattended without being told to.** The target is
+ *    destroyed, so a mistyped `--from` with no confirmation would take the
+ *    developer's working database with it.
+ *
+ * 3. **It will not write to a remote database.** The target is always the local
+ *    development database; there is no flag that makes this push. A tool that
+ *    can copy in both directions eventually copies in the wrong one.
+ *
+ * Anonymization is opt-in (`--anonymize`), which is a deliberate choice and not
+ * an obviously safe one — the flag nobody types is the flag nobody gets. It is
+ * a best-effort pass over columns whose *names* look like personal data, and
+ * {@link ANONYMIZE_PATTERNS} says exactly which. It cannot find personal data in
+ * a column called `notes`, and this file says so rather than implying a
+ * guarantee it cannot keep.
+ */
+/**
+ * Column-name patterns the anonymizer overwrites.
+ *
+ * Names, not contents: inspecting values would be slower, and would still miss
+ * the same things. This is a reasonable-effort measure for making a local copy
+ * less dangerous, and it is not a compliance control.
+ */
+export declare const ANONYMIZE_PATTERNS: readonly {
+    pattern: RegExp;
+    replacement: string;
+}[];
+export declare function shouldAnonymize(columnName: string): boolean;
+export declare function replacementFor(columnName: string): string | null;
+/** A text-ish column the anonymizer can overwrite without a type error. */
+export interface ColumnRef {
+    schema: string;
+    table: string;
+    column: string;
+    dataType: string;
+}
+/**
+ * Anonymizable columns: name looks personal, and the type can hold the
+ * replacement.
+ *
+ * The type check is what stops this generating `UPDATE … SET user_id =
+ * 'Redacted'` for an integer column called `user_id_email_seq` and failing the
+ * whole pass on a technicality.
+ */
+export declare function anonymizableColumns(columns: readonly ColumnRef[]): ColumnRef[];
+/** `UPDATE` statements for one anonymization pass, in a stable order. */
+export declare function anonymizeStatements(columns: readonly ColumnRef[]): string[];
+/** Host and database of a connection string, with no credentials in it. */
+export declare function describeTarget(connectionString: string): string;
+export interface PullPlan {
+    /** Where the data comes from. */
+    source: string;
+    /** Where it lands. Always local. */
+    target: string;
+    anonymize: boolean;
+    /** Schemas to copy. Empty means every non-system schema. */
+    schemas: string[];
+}
+/**
+ * `pg_dump` arguments for the source.
+ *
+ * `--no-owner` and `--no-acl` because the roles on a production server do not
+ * exist locally, and without them every `ALTER … OWNER TO` in the dump fails and
+ * buries the real output in noise. `--format=custom` so `pg_restore` can be told
+ * to continue past errors selectively rather than all-or-nothing.
+ */
+export declare function dumpArgs(plan: PullPlan): string[];
+/**
+ * `pg_restore` arguments for the target.
+ *
+ * `--clean --if-exists` because a pull replaces what is there: restoring into a
+ * database that already has the tables would otherwise fail on every one of
+ * them. `--no-owner` for the same reason as the dump.
+ */
+export declare function restoreArgs(plan: PullPlan, dumpFile: string): string[];
+/** Is `pg_dump` on PATH, and what version? Checked before anything destructive. */
+export declare function findPgDump(): Promise<string | null>;

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

@@ -0,0 +1,66 @@
+/**
+ * Which database a command should talk to, decided in one place.
+ *
+ * Before this existed every command that needed Postgres read `DATABASE_URL`
+ * for itself, which was fine while there was exactly one answer. Introducing a
+ * managed database makes the question real: a project may have no
+ * `DATABASE_URL` at all and still expect `rebase db push` to work, and a
+ * project that *does* set one must never be quietly redirected somewhere else.
+ *
+ * So the rule is ordered and boring, and the order is the promise:
+ *
+ *   1. `--database-url <url>`   — said on this command line, wins over everything
+ *   2. `DATABASE_URL` in the shell environment
+ *   3. `DATABASE_URL` in the project's `.env`
+ *   4. `--docker` / a manifest preference of `docker`
+ *   5. the managed PGlite database
+ *
+ * An explicit connection string always wins. That is the whole point of the
+ * override: someone pointing Rebase at their own Postgres — a colleague's
+ * staging box, a Neon branch, a container they manage — must get exactly that,
+ * with no cleverness in between. The managed database is what fills the vacuum
+ * when nobody has said anything, and it is the only case where the CLI picks.
+ *
+ * {@link resolveDevDatabase} is pure: inputs in, decision out, no filesystem
+ * and no process. Reading `.env` and starting a daemon happen elsewhere, so
+ * the ordering above can be tested without either.
+ */
+/** Where the answer came from. Carried so diagnostics can name it. */
+export type DevDatabaseSource = 
+/** `--database-url` on the command line. */
+"flag"
+/** `DATABASE_URL` in the shell environment. */
+ | "environment"
+/** `DATABASE_URL` in the project's `.env`. */
+ | "env-file"
+/** `--docker`, or `devDatabase: "docker"` in the manifest. */
+ | "docker"
+/** Nobody said anything, so the managed database fills in. */
+ | "managed";
+export type DevDatabase = {
+    kind: "external";
+    /** The connection string, exactly as given. Never rewritten. */
+    url: string;
+    source: Extract<DevDatabaseSource, "flag" | "environment" | "env-file">;
+} | {
+    kind: "docker";
+    source: "docker";
+} | {
+    kind: "managed";
+    source: "managed";
+};
+export interface ResolveDevDatabaseInput {
+    /** `--database-url <url>`, if given. */
+    flagUrl?: string | null;
+    /** `--docker`, if given. */
+    flagDocker?: boolean;
+    /** The shell environment. Only `DATABASE_URL` is read. */
+    env?: Record<string, string | undefined>;
+    /** Parsed `.env` from the project root. Only `DATABASE_URL` is read. */
+    envFile?: Record<string, string> | null;
+    /** `devDatabase` from `rebase.json`, if the project recorded a preference. */
+    manifestPreference?: "managed" | "docker" | null;
+}
+export declare function resolveDevDatabase(input?: ResolveDevDatabaseInput): DevDatabase;
+/** One line for the startup banner, naming both the database and why. */
+export declare function describeDevDatabase(database: DevDatabase): string;