@rebasepro/cli 0.16.0 → 0.16.1-canary.g041c925

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;

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

@@ -0,0 +1,93 @@
+/**
+ * The managed database's state file, and the rules for trusting it.
+ *
+ * The daemon outlives the command that started it — `rebase db push` in one
+ * terminal and `rebase dev` in another have to reach the *same* PGlite, because
+ * two processes opening one data directory would corrupt it. So the daemon
+ * records where it is, and every command reads that record.
+ *
+ * A record on disk is a claim, not a fact. The process it names may have been
+ * killed, the machine may have rebooted and handed the pid to something else,
+ * and the port may now belong to a stranger. {@link readState} therefore only
+ * parses; deciding whether a record is live is {@link isDaemonAlive}'s job, and
+ * it asks the daemon rather than the operating system.
+ */
+/** Everything under here is generated and gitignored. */
+export declare const DEV_DB_DIR = ".rebase";
+/** PGlite's own data directory. Deleting it is what `--reset` means. */
+export declare const DATA_DIR_NAME = "pgdata";
+/** The record the daemon writes once it is accepting connections. */
+export declare const STATE_FILE_NAME = "pglite.json";
+/**
+ * Held by whoever is currently starting a daemon.
+ *
+ * Without it, `rebase dev` and `rebase db push` started in the same second both
+ * see no state file, both spawn, and two processes open one PGlite data
+ * directory — the exact corruption the single-daemon design exists to prevent.
+ * Observed as `ENOTEMPTY` during cleanup, which is the harmless way for it to
+ * show up; the harmful way is a damaged database.
+ */
+export declare const START_LOCK_NAME = "starting.lock";
+export interface DaemonState {
+    /** TCP port the socket server is listening on, chosen when it started. */
+    port: number;
+    /** The daemon process. Used only as a fast negative check. */
+    pid: number;
+    /** Absolute path of the PGlite data directory this daemon has open. */
+    dataDir: string;
+    /** ISO timestamp, for diagnostics. */
+    startedAt: string;
+    /**
+     * A random token the daemon also answers with over the wire, on
+     * {@link identityPort}.
+     *
+     * Without it, "is the daemon alive?" degrades to "is something listening on
+     * that port?", which is a different question and answers yes for whatever
+     * process happened to take the port after a reboot. Rebase would then send
+     * migrations to a stranger.
+     */
+    token: string;
+    /** Loopback port that answers the identity check. */
+    identityPort: number;
+}
+export declare function devDbDir(projectRoot: string): string;
+export declare function dataDir(projectRoot: string): string;
+export declare function stateFile(projectRoot: string): string;
+export declare function startLockFile(projectRoot: string): string;
+/**
+ * Take the start lock, or report that somebody else holds it.
+ *
+ * `wx` is the whole mechanism: create-if-absent is a single atomic syscall, so
+ * exactly one of two racing processes can succeed no matter how close together
+ * they arrive.
+ *
+ * A lock older than `staleAfterMs` is broken rather than waited on — the holder
+ * may have been killed between creating it and starting anything, and a
+ * developer should never have to know this file exists in order to unstick
+ * their project.
+ */
+export declare function acquireStartLock(projectRoot: string, staleAfterMs: number): boolean;
+export declare function releaseStartLock(projectRoot: string): void;
+/**
+ * Parse the record, or `null` for anything that is not one.
+ *
+ * Every failure is the same answer — absent — because every failure has the
+ * same remedy: start a daemon. A corrupt state file is not worth an error
+ * message to a user who never wrote it.
+ */
+export declare function readState(projectRoot: string): DaemonState | null;
+export declare function writeState(projectRoot: string, state: DaemonState): void;
+export declare function clearState(projectRoot: string): void;
+/** Is *some* process with this pid running? A fast, cheap negative check. */
+export declare function pidRunning(pid: number): boolean;
+/** Can a TCP connection be opened to this port on loopback? */
+export declare function portAccepting(port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * Ask a port for a free one, then hand back the number.
+ *
+ * Deliberately not the probe `rebase init` uses: that one has a documented
+ * failure where a port is free to probe and unusable to publish. This binds on
+ * loopback only, which is also where the daemon listens, so a port that binds
+ * here binds there.
+ */
+export declare function findFreePort(): Promise<number>;

package/dist/function-portability.d.ts

@@ -0,0 +1,45 @@
+/** What a single finding is about. */
+export type PortabilityIssueKind = "node-builtin" | "node-only-package" | "module-scope-env" | "root-barrel-import" | "unknown-package";
+export interface PortabilityIssue {
+    kind: PortabilityIssueKind;
+    /** 1-based line in the function file. */
+    line: number;
+    /** One sentence, already phrased for a terminal. */
+    message: string;
+    /**
+     * Whether this is a problem *today*, on Node, rather than only a constraint
+     * on where the function could run. Exactly one kind is:
+     * `module-scope-env`, which is a latent crash on any host where a variable
+     * happens to be unset at import time, and takes every other function in the
+     * same directory down with it — the loader reports a file that throws on
+     * import as simply "skipped".
+     */
+    actionable: boolean;
+}
+export interface FunctionPortability {
+    /** Function name — the filename without extension, as it mounts. */
+    name: string;
+    /** Path relative to the project root. */
+    file: string;
+    /** Empty when the function depends on nothing host-specific. */
+    issues: PortabilityIssue[];
+    /** True when `issues` contains nothing that pins it to Node. */
+    portable: boolean;
+}
+/** Analyse one function file's source. Exported for testing. */
+export declare function analyseFunctionSource(source: string, name: string, file: string): FunctionPortability;
+/**
+ * Analyse every function in a directory.
+ *
+ * @param functionsDir Absolute path to the functions directory.
+ * @param projectRoot  For rendering paths people recognise.
+ */
+export declare function analyseFunctionsDirectory(functionsDir: string, projectRoot: string): FunctionPortability[];
+/**
+ * The lines to print after a build, or nothing at all.
+ *
+ * Silent when every function is portable and nothing is actionable, because a
+ * report that always prints is a report nobody reads. Actionable findings are
+ * always shown; the rest collapse to a single count with a pointer.
+ */
+export declare function summarisePortability(results: FunctionPortability[]): string[];

package/dist/index.d.ts

@@ -1,17 +1,17 @@
-export * from "./cli";
-export * from "./commands/init";
-export * from "./commands/schema";
-export * from "./commands/db";
-export * from "./commands/dev";
-export * from "./commands/build";
-export * from "./commands/eject";
-export * from "./commands/start";
-export * from "./commands/auth";
-export * from "./commands/doctor";
-export * from "./commands/generate_sdk";
-export * from "./commands/cloud";
-export * from "./commands/apps";
-export * from "./utils/project";
-export * from "./utils/package-manager";
-export * from "./manifest";
-export * from "./bundle";
+export * from "./cli.js";
+export * from "./commands/init.js";
+export * from "./commands/schema.js";
+export * from "./commands/db.js";
+export * from "./commands/dev.js";
+export * from "./commands/build.js";
+export * from "./commands/eject.js";
+export * from "./commands/start.js";
+export * from "./commands/auth.js";
+export * from "./commands/doctor.js";
+export * from "./commands/generate_sdk.js";
+export * from "./commands/cloud/index.js";
+export * from "./commands/apps.js";
+export * from "./utils/project.js";
+export * from "./utils/package-manager.js";
+export * from "./manifest.js";
+export * from "./bundle.js";