@rebasepro/cli 0.17.3 → 0.18.1

package/dist/resolve-Y56osuQH.js

@@ -0,0 +1,74 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+//#region src/dev-db/resolve.ts
+var resolve_exports = /* @__PURE__ */ __exportAll({
+	describeDevDatabase: () => describeDevDatabase,
+	resolveDevDatabase: () => resolveDevDatabase
+});
+/**
+* A value that is present but empty is treated as absent.
+*
+* `DATABASE_URL=` in a `.env` is what a developer writes when they mean "not
+* this one" — honouring it literally would hand an empty connection string to
+* libpq and produce an error about a missing host, which explains nothing.
+*/
+function present(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+function resolveDevDatabase(input = {}) {
+	const flagUrl = present(input.flagUrl);
+	if (flagUrl) return {
+		kind: "external",
+		url: flagUrl,
+		source: "flag"
+	};
+	const fromEnvironment = present(input.env?.DATABASE_URL);
+	if (fromEnvironment) return {
+		kind: "external",
+		url: fromEnvironment,
+		source: "environment"
+	};
+	const fromBranch = present(input.branch?.url);
+	if (fromBranch && input.branch) return {
+		kind: "external",
+		url: fromBranch,
+		source: "branch",
+		branch: input.branch.name
+	};
+	const fromEnvFile = present(input.envFile?.DATABASE_URL);
+	if (fromEnvFile) return {
+		kind: "external",
+		url: fromEnvFile,
+		source: "env-file"
+	};
+	if (input.flagDocker || input.manifestPreference === "docker") return {
+		kind: "docker",
+		source: "docker",
+		url: present(input.composeUrl)
+	};
+	return {
+		kind: "managed",
+		source: "managed"
+	};
+}
+/** One line for the startup banner, naming both the database and why. */
+function describeDevDatabase(database) {
+	switch (database.kind) {
+		case "external":
+			switch (database.source) {
+				case "flag": return "your database (--database-url)";
+				case "environment": return "your database (DATABASE_URL in the environment)";
+				case "env-file": return "your database (DATABASE_URL in .env)";
+				case "branch": return `branch "${database.branch}" (rebase db branch switch)`;
+			}
+			break;
+		case "docker": return "Postgres in Docker";
+		case "managed": return "the managed development database (PGlite)";
+	}
+	throw new Error(`Unhandled dev database: ${JSON.stringify(database)}`);
+}
+//#endregion
+export { resolveDevDatabase as n, resolve_exports as r, describeDevDatabase as t };
+
+//# sourceMappingURL=resolve-Y56osuQH.js.map

package/dist/resolve-Y56osuQH.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-Y56osuQH.js","names":[],"sources":["../src/dev-db/resolve.ts"],"sourcesContent":["/**\n * Which database a command should talk to, decided in one place.\n *\n * Before this existed every command that needed Postgres read `DATABASE_URL`\n * for itself, which was fine while there was exactly one answer. Introducing a\n * managed database makes the question real: a project may have no\n * `DATABASE_URL` at all and still expect `rebase db push` to work, and a\n * project that *does* set one must never be quietly redirected somewhere else.\n *\n * So the rule is ordered and boring, and the order is the promise:\n *\n *   1. `--database-url <url>`   — said on this command line, wins over everything\n *   2. `DATABASE_URL` in the shell environment\n *   3. the database branch this checkout is switched to\n *   4. `DATABASE_URL` in the project's `.env`\n *   5. `--docker` / a manifest preference of `docker`\n *   6. the managed PGlite database\n *\n * An explicit connection string always wins. That is the whole point of the\n * override: someone pointing Rebase at their own Postgres — a colleague's\n * staging box, a Neon branch, a container they manage — must get exactly that,\n * with no cleverness in between. The managed database is what fills the vacuum\n * when nobody has said anything, and it is the only case where the CLI picks.\n *\n * The branch at (3) is the one addition that is not an explicit connection\n * string, and it sits where it does deliberately. It has to outrank `.env` or\n * `rebase db branch switch` would silently do nothing on every project that\n * sets `DATABASE_URL` — which is every project not on the managed database.\n * It must not outrank (1) or (2), because a flag on this command line and a\n * variable in this shell are more immediate than a switch made yesterday.\n *\n * {@link resolveDevDatabase} is pure: inputs in, decision out, no filesystem\n * and no process. Reading `.env`, reading the branch pointer and starting a\n * daemon happen elsewhere, so the ordering above can be tested without any of\n * them.\n */\n\n/** Where the answer came from. Carried so diagnostics can name it. */\nexport type DevDatabaseSource =\n    /** `--database-url` on the command line. */\n    | \"flag\"\n    /** `DATABASE_URL` in the shell environment. */\n    | \"environment\"\n    /** `DATABASE_URL` in the project's `.env`. */\n    | \"env-file\"\n    /** The branch this checkout is switched to, over the base connection. */\n    | \"branch\"\n    /** `--docker`, or `devDatabase: \"docker\"` in the manifest. */\n    | \"docker\"\n    /** Nobody said anything, so the managed database fills in. */\n    | \"managed\";\n\nexport type DevDatabase =\n    | {\n        kind: \"external\";\n        /** The connection string, exactly as given. Never rewritten. */\n        url: string;\n        source: Extract<DevDatabaseSource, \"flag\" | \"environment\" | \"env-file\" | \"branch\">;\n        /** The branch name, when this checkout is switched to one. */\n        branch?: string;\n    }\n    | {\n        kind: \"docker\";\n        source: \"docker\";\n        /**\n         * The compose `db` service's connection string, derived by the caller.\n         *\n         * Null when the project has no compose file to derive one from, which\n         * is a `--docker` that cannot be honoured rather than a fallback: the\n         * caller says so instead of guessing at `localhost:5432`.\n         */\n        url: string | null;\n    }\n    | {\n        kind: \"managed\";\n        source: \"managed\";\n    };\n\nexport interface ResolveDevDatabaseInput {\n    /** `--database-url <url>`, if given. */\n    flagUrl?: string | null;\n    /** `--docker`, if given. */\n    flagDocker?: boolean;\n    /** The shell environment. Only `DATABASE_URL` is read. */\n    env?: Record<string, string | undefined>;\n    /** Parsed `.env` from the project root. Only `DATABASE_URL` is read. */\n    envFile?: Record<string, string> | null;\n    /** `devDatabase` from `rebase.json`, if the project recorded a preference. */\n    manifestPreference?: \"managed\" | \"docker\" | null;\n    /**\n     * The compose `db` service's connection string, when the project has one.\n     *\n     * Passed in rather than read here so this function stays pure. Only\n     * consulted for the Docker case; an explicit `DATABASE_URL` still wins.\n     */\n    composeUrl?: string | null;\n    /**\n     * The branch this checkout is switched to, already resolved to a URL.\n     *\n     * Resolved by the caller rather than here so this stays pure: deriving it\n     * needs the base connection string, which needs the `.env` this function is\n     * handed rather than reads.\n     */\n    branch?: { name: string; url: string } | null;\n}\n\n/**\n * A value that is present but empty is treated as absent.\n *\n * `DATABASE_URL=` in a `.env` is what a developer writes when they mean \"not\n * this one\" — honouring it literally would hand an empty connection string to\n * libpq and produce an error about a missing host, which explains nothing.\n */\nfunction present(value: string | undefined | null): string | null {\n    if (typeof value !== \"string\") return null;\n    const trimmed = value.trim();\n\n    return trimmed.length > 0 ? trimmed : null;\n}\n\nexport function resolveDevDatabase(input: ResolveDevDatabaseInput = {}): DevDatabase {\n    const flagUrl = present(input.flagUrl);\n    if (flagUrl) return { kind: \"external\", url: flagUrl, source: \"flag\" };\n\n    const fromEnvironment = present(input.env?.DATABASE_URL);\n    if (fromEnvironment) return { kind: \"external\", url: fromEnvironment, source: \"environment\" };\n\n    // Above `.env`, below anything said explicitly — see the ordering note at\n    // the top of this file.\n    const fromBranch = present(input.branch?.url);\n    if (fromBranch && input.branch) {\n        return { kind: \"external\", url: fromBranch, source: \"branch\", branch: input.branch.name };\n    }\n\n    const fromEnvFile = present(input.envFile?.DATABASE_URL);\n    if (fromEnvFile) return { kind: \"external\", url: fromEnvFile, source: \"env-file\" };\n\n    // Only consulted once every explicit connection string is exhausted: asking\n    // for Docker is a choice about *how to get* a database, not which one, so a\n    // DATABASE_URL that already names one outranks it.\n    if (input.flagDocker || input.manifestPreference === \"docker\") {\n        return { kind: \"docker\", source: \"docker\", url: present(input.composeUrl) };\n    }\n\n    return { kind: \"managed\", source: \"managed\" };\n}\n\n/** One line for the startup banner, naming both the database and why. */\nexport function describeDevDatabase(database: DevDatabase): string {\n    switch (database.kind) {\n        case \"external\":\n            switch (database.source) {\n                case \"flag\":\n                    return \"your database (--database-url)\";\n                case \"environment\":\n                    return \"your database (DATABASE_URL in the environment)\";\n                case \"env-file\":\n                    return \"your database (DATABASE_URL in .env)\";\n                case \"branch\":\n                    return `branch \"${database.branch}\" (rebase db branch switch)`;\n            }\n            break;\n        case \"docker\":\n            return \"Postgres in Docker\";\n        case \"managed\":\n            return \"the managed development database (PGlite)\";\n    }\n\n    // Unreachable while the union is exhaustive; kept so a future variant fails\n    // loudly in review rather than printing \"undefined\" to a user.\n    throw new Error(`Unhandled dev database: ${JSON.stringify(database)}`);\n}\n"],"mappings":";;;;;;;;;;;;;AAiHA,SAAS,QAAQ,OAAiD;CAC9D,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,MAAM,UAAU,MAAM,KAAK;CAE3B,OAAO,QAAQ,SAAS,IAAI,UAAU;AAC1C;AAEA,SAAgB,mBAAmB,QAAiC,CAAC,GAAgB;CACjF,MAAM,UAAU,QAAQ,MAAM,OAAO;CACrC,IAAI,SAAS,OAAO;EAAE,MAAM;EAAY,KAAK;EAAS,QAAQ;CAAO;CAErE,MAAM,kBAAkB,QAAQ,MAAM,KAAK,YAAY;CACvD,IAAI,iBAAiB,OAAO;EAAE,MAAM;EAAY,KAAK;EAAiB,QAAQ;CAAc;CAI5F,MAAM,aAAa,QAAQ,MAAM,QAAQ,GAAG;CAC5C,IAAI,cAAc,MAAM,QACpB,OAAO;EAAE,MAAM;EAAY,KAAK;EAAY,QAAQ;EAAU,QAAQ,MAAM,OAAO;CAAK;CAG5F,MAAM,cAAc,QAAQ,MAAM,SAAS,YAAY;CACvD,IAAI,aAAa,OAAO;EAAE,MAAM;EAAY,KAAK;EAAa,QAAQ;CAAW;CAKjF,IAAI,MAAM,cAAc,MAAM,uBAAuB,UACjD,OAAO;EAAE,MAAM;EAAU,QAAQ;EAAU,KAAK,QAAQ,MAAM,UAAU;CAAE;CAG9E,OAAO;EAAE,MAAM;EAAW,QAAQ;CAAU;AAChD;;AAGA,SAAgB,oBAAoB,UAA+B;CAC/D,QAAQ,SAAS,MAAjB;EACI,KAAK;GACD,QAAQ,SAAS,QAAjB;IACI,KAAK,QACD,OAAO;IACX,KAAK,eACD,OAAO;IACX,KAAK,YACD,OAAO;IACX,KAAK,UACD,OAAO,WAAW,SAAS,OAAO;GAC1C;GACA;EACJ,KAAK,UACD,OAAO;EACX,KAAK,WACD,OAAO;CACf;CAIA,MAAM,IAAI,MAAM,2BAA2B,KAAK,UAAU,QAAQ,GAAG;AACzE"}

package/dist/resources/derive.d.ts

@@ -1,4 +1,4 @@
-import { type ResourceGraph } from "@rebasepro/types";
+import { type RebaseBackendAppConfig, type ResourceDeclaration, type ResourceGraph } from "@rebasepro/types";
 /** The committed, generated record of what a project needs. */
 export declare const RESOURCE_GRAPH_FILENAME = "rebase.resources.json";
 /** A problem found while deriving, reported with the rest rather than thrown one at a time. */
@@ -6,6 +6,20 @@ export interface ResourceIssue {
     path: string;
     message: string;
 }
+/**
+ * The message an issue carries, with the skew named when there is one.
+ *
+ * `main` runs 497 commits ahead of npm `latest` and the docs site publishes from
+ * `main`, so the shape this exists for is routine: a scaffold pinned to the
+ * published version, config code written against today's documentation, and an
+ * error about the config file. The fix is one command and the error named none
+ * of it — the same failure as `404 No PUT route on collection 'projects'`, one
+ * layer down.
+ *
+ * Says nothing extra when the two versions agree, or when either is unreadable:
+ * a sentence naming one version twice is worse than no sentence.
+ */
+export declare function describeIssue(err: unknown, projectRoot: string, ownVersion?: string): string;
 export interface DeriveOptions {
     /** Absolute path to the project's config directory. */
     configDir: string;
@@ -16,7 +30,23 @@ export interface DeriveOptions {
      * would under-report what the project needs.
      */
     includeCollections?: boolean;
+    /**
+     * Absolute path to the crons directory. Each file is evaluated through the
+     * same loader the runtime uses, which declares the cron under the same id
+     * the scheduler runs it as. Absent, or missing on disk: no crons.
+     */
+    cronsDir?: string;
+    /**
+     * Absolute path to the functions directory. Read statically — the
+     * bundler's portability analysis — never evaluated: a function's module
+     * scope belongs to a running backend, not a build.
+     */
+    functionsDir?: string;
+    /** The project root, for the paths a graph records. Defaults to the config directory's parent. */
+    projectRoot?: string;
 }
+/** The derive options for a backend app, from its manifest entry. */
+export declare function deriveOptionsFor(projectRoot: string, app: RebaseBackendAppConfig): DeriveOptions;
 /**
  * Evaluate a project's config and return the graph it declares.
  *
@@ -45,3 +75,39 @@ export declare function writeResourceGraphFile(projectRoot: string, graph: Resou
 };
 /** Parse a committed graph file, tolerating the `$generated` banner. */
 export declare function parseResourceGraph(contents: string): ResourceGraph;
+/**
+ * Add the resources a project has without declaring them.
+ *
+ * A backend has a database whether or not anyone said so, and a project that
+ * declares no buckets still gets one default storage source from the plain
+ * unsuffixed variables. Both are load-bearing defaults and both are invisible
+ * in the graph, so a status view built only from declarations would show an
+ * empty screen to the majority of projects — the ones that most need to be told
+ * which variable their one database reads.
+ */
+export declare function withImplicitDefaults(graph: ResourceGraph): {
+    declaration: ResourceDeclaration;
+    implicit: boolean;
+}[];
+/**
+ * The resources a project *has*, which is what a person is asking about.
+ *
+ * One projection, because two of them disagreed. `rebase status` built its
+ * rows from {@link withImplicitDefaults} and listed `buckets ✓ (default) local
+ * · implicit`; `rebase resources` and `rebase resources --json` built theirs
+ * from the raw graph and listed only the database and the function. Two
+ * commands whose whole job is to answer "what does this project need", on the
+ * same stock scaffold, giving different answers.
+ *
+ * The implicit entries are marked rather than hidden, because the distinction
+ * is real and load-bearing: a declared resource is recorded in
+ * `rebase.resources.json` for a host to provision, and an implicit one is a
+ * default the runtime supplies whether or not anyone wrote it down. That file
+ * still holds declarations only — it is a wire contract a host reads, and
+ * putting defaults in it would ask for something to be provisioned that
+ * nobody declared.
+ */
+export type ProjectedResource = ResourceDeclaration & {
+    implicit?: true;
+};
+export declare function projectResourceGraph(graph: ResourceGraph): ProjectedResource[];

package/dist/resources/status.d.ts

@@ -0,0 +1,128 @@
+import { type ResourceDeclaration, type ResourceGraph } from "@rebasepro/types";
+/** One environment variable a resource reads, and whether it is there. */
+export interface ResourceBinding {
+    /** The variable this resource reads, suffix included. */
+    name: string;
+    set: boolean;
+    /**
+     * The account-scoped name consulted when `name` is unset.
+     *
+     * Only provider-level bindings have one, and only when the resource named
+     * an `account`. Shown because a developer looking at an unset
+     * `S3_ACCESS_KEY_ID__MEDIA` needs to know it is not the whole story.
+     */
+    fallback?: {
+        name: string;
+        set: boolean;
+    };
+}
+/** Whether a declared resource can actually be reached. */
+export type ResourceState = 
+/** Bound and usable. */
+"ready"
+/** Nothing set for it. Legal for a bucket, fatal for a database. */
+ | "unconfigured"
+/** Set, and set wrongly. The deployment refuses to start. */
+ | "broken";
+export interface ResourceStatus {
+    kind: string;
+    key: string;
+    engine: string;
+    transport: string;
+    /** Present when this resource shares another's credentials. */
+    account?: string;
+    /** True for a resource nobody declared, which exists anyway. */
+    implicit: boolean;
+    bindings: ResourceBinding[];
+    state: ResourceState;
+    /** What this means, in the terms the developer will meet it in. */
+    detail: string;
+    /** Set when a local directory stands in for this engine, in development. */
+    standsIn?: string;
+    /** What in the project reaches this resource, from the graph. */
+    usedBy?: readonly string[];
+}
+export type EnvBag = Record<string, string | undefined>;
+/**
+ * The bindings one declaration reads, in the order a reader should scan them.
+ *
+ * A `direct`-transport resource gets none: the browser reaches it with a
+ * provider SDK and the backend binds nothing for it, so listing variables would
+ * invite someone to set variables that are never read.
+ */
+export declare function bindingsFor(declaration: ResourceDeclaration, env: EnvBag, accountScopedBases: readonly string[]): ResourceBinding[];
+/**
+ * What the managed development database covers, when a project is on it.
+ *
+ * `rebase init` leaves `DATABASE_URL` commented out on purpose and the managed
+ * PGlite fills the vacuum — the documented first-run state. Judging that state
+ * by the environment alone produced `○ (default) postgres · DATABASE_URL not
+ * set` and the remedy "set DATABASE_URL", at the same moment `rebase db url`
+ * was printing a working connection string for the same project and
+ * `rebase dev` was serving from it. The status view was reading the one place
+ * the answer deliberately is not.
+ *
+ * Resolved by the caller, because deciding it needs the project's `.env`, its
+ * branch pointer and its compose file, and this module stays free of all three.
+ */
+export interface ManagedDatabaseStatus {
+    /**
+     * The daemon's connection string, or null when it is not running.
+     *
+     * Null is not an error: the managed database exists per project and starts
+     * on demand. It only means there is nothing to run the whole-set check
+     * against, and the row says so rather than implying a misconfiguration.
+     */
+    url: string | null;
+}
+/**
+ * The resolver-side of status, as `@rebasepro/server` registers it per kind.
+ *
+ * Passed in rather than imported so this module stays testable without a
+ * server, and so a kind registered by a plugin is judged by the resolver the
+ * plugin brought with it rather than by a switch here.
+ */
+export interface StatusResolvers {
+    /** `resourceResolver(kind)` from `@rebasepro/server`. */
+    resolverFor: (kind: string) => {
+        accountScoped?: readonly string[];
+        resolve: (declaration: ResourceDeclaration, env: EnvBag, context: {
+            production: boolean;
+            defaultBasePath: string;
+        }) => {
+            state: "ready" | "unbound" | "blocked" | "code";
+            detail?: string;
+            standsIn?: string;
+        };
+    } | undefined;
+    /** `resolveDataSources` from `@rebasepro/server`, for the whole-set check. */
+    resolveDataSources: (env: EnvBag, definitions: unknown) => unknown;
+    /** Whether the process being judged is production. Status judges for development by default. */
+    production?: boolean;
+    /**
+     * Set when this project runs on the managed development database.
+     *
+     * Absent for a project that named its own connection string, and absent in
+     * production — where an unset `DATABASE_URL` is the failure it has always
+     * been.
+     */
+    managedDatabase?: ManagedDatabaseStatus;
+}
+/**
+ * Resolve every declared resource against an environment.
+ *
+ * Each kind's verdict comes from the resolver `@rebasepro/server` registered
+ * for it — the same one boot calls — so this view cannot say "ready" about a
+ * binding boot would refuse. A kind with no resolver is reported as such
+ * rather than skipped: a resource nobody shows is one nobody remembers to
+ * configure, and a kind this runtime cannot bind is exactly what boot will
+ * refuse by name.
+ *
+ * `resolveDataSources` is then run once over the whole set, so anything it
+ * would refuse across sources (a driver package it cannot resolve for a custom
+ * engine) is reported rather than missed by a view that only looked per row.
+ */
+export declare function computeStatus(graph: ResourceGraph, env: EnvBag, resolvers: StatusResolvers): {
+    resources: ResourceStatus[];
+    blocked?: string;
+};

package/dist/rolldown-runtime-D7D4PA-g.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/dist/{state-c0CJ6Kwb.js → state-C59Elrnt.js}

@@ -1,18 +1,8 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import path from "path";
 import fs from "fs";
 import net from "net";
-//#region \0rolldown/runtime.js
-var __defProp = Object.defineProperty;
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
-//#endregion
+import { resourceEnvSuffix } from "@rebasepro/types";
 //#region src/dev-db/state.ts
 /**
 * The managed database's state file, and the rules for trusting it.
@@ -34,6 +24,7 @@ var state_exports = /* @__PURE__ */ __exportAll({
 	START_LOCK_NAME: () => START_LOCK_NAME,
 	STATE_FILE_NAME: () => STATE_FILE_NAME,
 	acquireStartLock: () => acquireStartLock,
+	additionalDataDir: () => additionalDataDir,
 	clearState: () => clearState,
 	dataDir: () => dataDir,
 	devDbDir: () => devDbDir,
@@ -67,6 +58,16 @@ function devDbDir(projectRoot) {
 function dataDir(projectRoot) {
 	return path.join(devDbDir(projectRoot), DATA_DIR_NAME);
 }
+/**
+* The data directory for an additional declared database.
+*
+* `pgdata__analytics`: the key spelled the way its variable is, so the
+* directory beside `pgdata` and `DATABASE_URL__ANALYTICS` are visibly the
+* same thing.
+*/
+function additionalDataDir(projectRoot, key) {
+	return path.join(devDbDir(projectRoot), `${DATA_DIR_NAME}${resourceEnvSuffix(key).toLowerCase()}`);
+}
 function stateFile(projectRoot) {
 	return path.join(devDbDir(projectRoot), STATE_FILE_NAME);
 }
@@ -128,13 +129,21 @@ function readState(projectRoot) {
 	try {
 		const parsed = JSON.parse(raw);
 		if (typeof parsed.port !== "number" || !Number.isInteger(parsed.port) || parsed.port <= 0 || parsed.port > 65535 || typeof parsed.pid !== "number" || typeof parsed.dataDir !== "string" || typeof parsed.token !== "string" || parsed.token.length === 0 || typeof parsed.identityPort !== "number" || !Number.isInteger(parsed.identityPort) || parsed.identityPort <= 0 || parsed.identityPort > 65535) return null;
+		const databases = {};
+		if (parsed.databases && typeof parsed.databases === "object") {
+			for (const [key, entry] of Object.entries(parsed.databases)) if (entry && typeof entry.port === "number" && Number.isInteger(entry.port) && entry.port > 0 && entry.port <= 65535 && typeof entry.dataDir === "string") databases[key] = {
+				port: entry.port,
+				dataDir: entry.dataDir
+			};
+		}
 		return {
 			port: parsed.port,
 			pid: parsed.pid,
 			dataDir: parsed.dataDir,
 			startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : "",
 			token: parsed.token,
-			identityPort: parsed.identityPort
+			identityPort: parsed.identityPort,
+			...Object.keys(databases).length > 0 ? { databases } : {}
 		};
 	} catch {
 		return null;
@@ -185,6 +194,6 @@ function findFreePort() {
 	});
 }
 //#endregion
-export { findFreePort as a, releaseStartLock as c, writeState as d, __exportAll as f, devDbDir as i, stateFile as l, clearState as n, pidRunning as o, dataDir as r, readState as s, acquireStartLock as t, state_exports as u };
+export { devDbDir as a, readState as c, state_exports as d, writeState as f, dataDir as i, releaseStartLock as l, additionalDataDir as n, findFreePort as o, clearState as r, pidRunning as s, acquireStartLock as t, stateFile as u };
 
-//# sourceMappingURL=state-c0CJ6Kwb.js.map
+//# sourceMappingURL=state-C59Elrnt.js.map

package/dist/state-C59Elrnt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-C59Elrnt.js","names":[],"sources":["../src/dev-db/state.ts"],"sourcesContent":["/**\n * The managed database's state file, and the rules for trusting it.\n *\n * The daemon outlives the command that started it — `rebase db push` in one\n * terminal and `rebase dev` in another have to reach the *same* PGlite, because\n * two processes opening one data directory would corrupt it. So the daemon\n * records where it is, and every command reads that record.\n *\n * A record on disk is a claim, not a fact. The process it names may have been\n * killed, the machine may have rebooted and handed the pid to something else,\n * and the port may now belong to a stranger. {@link readState} therefore only\n * parses; deciding whether a record is live is {@link isDaemonAlive}'s job, and\n * it asks the daemon rather than the operating system.\n */\n\nimport fs from \"fs\";\nimport { resourceEnvSuffix } from \"@rebasepro/types\";\nimport net from \"net\";\nimport path from \"path\";\n\n/** Everything under here is generated and gitignored. */\nexport const DEV_DB_DIR = \".rebase\";\n/** PGlite's own data directory. Deleting it is what `--reset` means. */\nexport const DATA_DIR_NAME = \"pgdata\";\n/** The record the daemon writes once it is accepting connections. */\nexport const STATE_FILE_NAME = \"pglite.json\";\n/**\n * Held by whoever is currently starting a daemon.\n *\n * Without it, `rebase dev` and `rebase db push` started in the same second both\n * see no state file, both spawn, and two processes open one PGlite data\n * directory — the exact corruption the single-daemon design exists to prevent.\n * Observed as `ENOTEMPTY` during cleanup, which is the harmless way for it to\n * show up; the harmful way is a damaged database.\n */\nexport const START_LOCK_NAME = \"starting.lock\";\n\nexport interface DaemonState {\n    /** TCP port the socket server is listening on, chosen when it started. */\n    port: number;\n    /** The daemon process. Used only as a fast negative check. */\n    pid: number;\n    /** Absolute path of the PGlite data directory this daemon has open. */\n    dataDir: string;\n    /** ISO timestamp, for diagnostics. */\n    startedAt: string;\n    /**\n     * A random token the daemon also answers with over the wire, on\n     * {@link identityPort}.\n     *\n     * Without it, \"is the daemon alive?\" degrades to \"is something listening on\n     * that port?\", which is a different question and answers yes for whatever\n     * process happened to take the port after a reboot. Rebase would then send\n     * migrations to a stranger.\n     */\n    token: string;\n    /** Loopback port that answers the identity check. */\n    identityPort: number;\n    /**\n     * The additional databases this daemon serves, by declared key.\n     *\n     * One PGlite instance each — PGlite is one database per instance, so\n     * `database(\"analytics\")` is a second data directory and a second port,\n     * not a `CREATE DATABASE`. Started on demand when a command asks for the\n     * key over the identity socket, and recorded here so `rebase status` and\n     * a reset can see them. The default database is the fields above.\n     */\n    databases?: Record<string, { port: number; dataDir: string }>;\n}\n\nexport function devDbDir(projectRoot: string): string {\n    return path.join(projectRoot, DEV_DB_DIR);\n}\n\nexport function dataDir(projectRoot: string): string {\n    return path.join(devDbDir(projectRoot), DATA_DIR_NAME);\n}\n\n/**\n * The data directory for an additional declared database.\n *\n * `pgdata__analytics`: the key spelled the way its variable is, so the\n * directory beside `pgdata` and `DATABASE_URL__ANALYTICS` are visibly the\n * same thing.\n */\nexport function additionalDataDir(projectRoot: string, key: string): string {\n    return path.join(devDbDir(projectRoot), `${DATA_DIR_NAME}${resourceEnvSuffix(key).toLowerCase()}`);\n}\n\nexport function stateFile(projectRoot: string): string {\n    return path.join(devDbDir(projectRoot), STATE_FILE_NAME);\n}\n\nexport function startLockFile(projectRoot: string): string {\n    return path.join(devDbDir(projectRoot), START_LOCK_NAME);\n}\n\n/**\n * Take the start lock, or report that somebody else holds it.\n *\n * `wx` is the whole mechanism: create-if-absent is a single atomic syscall, so\n * exactly one of two racing processes can succeed no matter how close together\n * they arrive.\n *\n * A lock older than `staleAfterMs` is broken rather than waited on — the holder\n * may have been killed between creating it and starting anything, and a\n * developer should never have to know this file exists in order to unstick\n * their project.\n */\nexport function acquireStartLock(projectRoot: string, staleAfterMs: number): boolean {\n    const target = startLockFile(projectRoot);\n    fs.mkdirSync(devDbDir(projectRoot), { recursive: true });\n\n    const attempt = (): boolean => {\n        try {\n            const handle = fs.openSync(target, \"wx\");\n            fs.writeSync(handle, `${process.pid} ${new Date().toISOString()}\\n`);\n            fs.closeSync(handle);\n\n            return true;\n        } catch (error) {\n            if ((error as NodeJS.ErrnoException).code !== \"EEXIST\") throw error;\n\n            return false;\n        }\n    };\n\n    if (attempt()) return true;\n\n    try {\n        // Clamped at zero: a filesystem whose timestamp granularity rounds the\n        // mtime *up* reports a negative age for a lock created moments ago,\n        // and a negative age is below every threshold — so `staleAfterMs: 0`,\n        // which means \"break any lock\", would refuse to break one.\n        const age = Math.max(0, Date.now() - fs.statSync(target).mtimeMs);\n        if (age < staleAfterMs) return false;\n        fs.unlinkSync(target);\n    } catch {\n        // Vanished under us, which means the holder finished. Either way the\n        // next attempt is the answer.\n    }\n\n    return attempt();\n}\n\nexport function releaseStartLock(projectRoot: string): void {\n    try {\n        fs.unlinkSync(startLockFile(projectRoot));\n    } catch {\n        // Already released is the desired end state.\n    }\n}\n\n/**\n * Parse the record, or `null` for anything that is not one.\n *\n * Every failure is the same answer — absent — because every failure has the\n * same remedy: start a daemon. A corrupt state file is not worth an error\n * message to a user who never wrote it.\n */\nexport function readState(projectRoot: string): DaemonState | null {\n    let raw: string;\n    try {\n        raw = fs.readFileSync(stateFile(projectRoot), \"utf8\");\n    } catch {\n        return null;\n    }\n\n    try {\n        const parsed = JSON.parse(raw) as Partial<DaemonState>;\n        if (\n            typeof parsed.port !== \"number\" ||\n            !Number.isInteger(parsed.port) ||\n            parsed.port <= 0 ||\n            parsed.port > 65535 ||\n            typeof parsed.pid !== \"number\" ||\n            typeof parsed.dataDir !== \"string\" ||\n            typeof parsed.token !== \"string\" ||\n            parsed.token.length === 0 ||\n            typeof parsed.identityPort !== \"number\" ||\n            !Number.isInteger(parsed.identityPort) ||\n            parsed.identityPort <= 0 ||\n            parsed.identityPort > 65535\n        ) {\n            return null;\n        }\n\n        // Only well-formed entries survive: a malformed one is treated as\n        // absent, and the next ensure asks the daemon for it again.\n        const databases: Record<string, { port: number; dataDir: string }> = {};\n        if (parsed.databases && typeof parsed.databases === \"object\") {\n            for (const [key, entry] of Object.entries(parsed.databases)) {\n                if (\n                    entry && typeof entry.port === \"number\" && Number.isInteger(entry.port)\n                    && entry.port > 0 && entry.port <= 65535 && typeof entry.dataDir === \"string\"\n                ) {\n                    databases[key] = { port: entry.port, dataDir: entry.dataDir };\n                }\n            }\n        }\n\n        return {\n            port: parsed.port,\n            pid: parsed.pid,\n            dataDir: parsed.dataDir,\n            startedAt: typeof parsed.startedAt === \"string\" ? parsed.startedAt : \"\",\n            token: parsed.token,\n            identityPort: parsed.identityPort,\n            ...(Object.keys(databases).length > 0 ? { databases } : {})\n        };\n    } catch {\n        return null;\n    }\n}\n\nexport function writeState(projectRoot: string, state: DaemonState): void {\n    fs.mkdirSync(devDbDir(projectRoot), { recursive: true });\n    // Written whole then moved, so a reader never sees half a record — commands\n    // poll this file while the daemon is starting.\n    const target = stateFile(projectRoot);\n    const temporary = `${target}.${process.pid}.tmp`;\n    fs.writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\\n`, \"utf8\");\n    fs.renameSync(temporary, target);\n}\n\nexport function clearState(projectRoot: string): void {\n    try {\n        fs.unlinkSync(stateFile(projectRoot));\n    } catch {\n        // Already gone is the desired end state.\n    }\n}\n\n/** Is *some* process with this pid running? A fast, cheap negative check. */\nexport function pidRunning(pid: number): boolean {\n    try {\n        // Signal 0 performs the permission and existence checks without\n        // delivering anything.\n        process.kill(pid, 0);\n\n        return true;\n    } catch (error) {\n        // EPERM means it exists and belongs to someone else, which for our\n        // purposes is still \"running\".\n        return (error as NodeJS.ErrnoException).code === \"EPERM\";\n    }\n}\n\n/** Can a TCP connection be opened to this port on loopback? */\nexport function portAccepting(port: number, timeoutMs = 1000): Promise<boolean> {\n    return new Promise((resolve) => {\n        const socket = new net.Socket();\n        const settle = (answer: boolean) => {\n            socket.removeAllListeners();\n            socket.destroy();\n            resolve(answer);\n        };\n        socket.setTimeout(timeoutMs);\n        socket.once(\"connect\", () => settle(true));\n        socket.once(\"timeout\", () => settle(false));\n        socket.once(\"error\", () => settle(false));\n        socket.connect(port, \"127.0.0.1\");\n    });\n}\n\n/**\n * Ask a port for a free one, then hand back the number.\n *\n * Deliberately not the probe `rebase init` uses: that one has a documented\n * failure where a port is free to probe and unusable to publish. This binds on\n * loopback only, which is also where the daemon listens, so a port that binds\n * here binds there.\n */\nexport function findFreePort(): Promise<number> {\n    return new Promise((resolve, reject) => {\n        const server = net.createServer();\n        server.once(\"error\", reject);\n        server.listen(0, \"127.0.0.1\", () => {\n            const address = server.address();\n            if (address === null || typeof address === \"string\") {\n                server.close(() => reject(new Error(\"Could not determine a free port.\")));\n\n                return;\n            }\n            const { port } = address;\n            server.close(() => resolve(port));\n        });\n    });\n}\n"],"mappings":"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"}

package/dist/utils/args.d.ts

@@ -53,6 +53,24 @@ export interface ParsedCommand<S extends arg.Spec> {
 }
 /** Did the line ask for help? Answered before dispatch, never by a handler. */
 export declare function wantsHelp(rawArgs: string[]): boolean;
+/**
+ * The command line was wrong — nothing ran, and there is no stack to want.
+ *
+ * `bin/rebase.js` ends every failure with "Re-run with --debug for the stack
+ * trace.", which is right when something broke inside a command and absurd for
+ * a typo: the stack points at `arg` and this file, neither of which the person
+ * who mistyped `--ouput` has any interest in. Worse, `--debug` is a flag, so
+ * the suggested next command is *another* command line — and the one thing we
+ * have just established is that the command line is what went wrong.
+ *
+ * Marked with a property rather than left to `instanceof`, because the reader
+ * is `bin/rebase.js`: it imports the bundle, so the class object it would test
+ * against is not the one this file compiled to.
+ */
+export declare class UsageError extends Error {
+    readonly isUsageError = true;
+    constructor(message: string);
+}
 /**
  * Resolve a command's flags and positionals from the full `process.argv`.
  *

package/dist/utils/command-words.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The words that name a command, with the flags taken back out.
+ *
+ * `rawArgs` is the whole of `process.argv`, and reading the command's words at
+ * fixed indices off it assumes nothing precedes them. Something routinely does:
+ * `--debug` is what `bin/rebase.js` prints after every failure as the thing to
+ * re-run with, so it is the single most likely token to appear before a command
+ * word, and it shifted every index by one.
+ *
+ * What that cost is not a bad error message. `rebase db branch switch feature`
+ * writes a per-checkout pointer that the CLI owns; the driver, running as a
+ * child process, cannot persist it and does not try. The dispatch found
+ * `switch` by position, so `rebase --debug db branch switch feature` missed the
+ * CLI's branch and handed the line to the driver — which reported success and
+ * left the checkout on the main database. Every subsequent `dev`, `push` and
+ * `backup` then ran against the wrong database, believing it was the branch,
+ * which is the exact failure branching exists to prevent.
+ *
+ * The words are anchored on the command name rather than taken from position
+ * zero, because a flag written in the space form (`--database-url <url>`) leaves
+ * its value behind as a bare token and no parser at this level knows which
+ * flags take values. Anchoring survives that: the value would have to be the
+ * literal command name to fool it.
+ *
+ * Returns `[]` when the command name is not on the line at all.
+ */
+export declare function commandWords(rawArgs: readonly string[], command: string): string[];
+/**
+ * The line to hand a spawned driver, starting at the command word.
+ *
+ * The same defect one layer down, and it does not degrade gracefully: the
+ * driver reads its domain from `args[0]`, so `rebase --debug db push` spawned
+ * it with `["--debug", "db", "push"]` and it answered "Unknown domain command:
+ * --debug" — for a flag the CLI itself tells you to add after any failure.
+ *
+ * Tokens written *before* the command word are moved after it rather than
+ * dropped. Dropping them would be the same class of bug in the other direction:
+ * `rebase --database-url postgres://… db push` would silently lose the flag that
+ * says which database to touch. Appending keeps each flag next to its value, and
+ * `arg` reads flags wherever they appear.
+ *
+ * Falls back to `rawArgs.slice(2)` when the command word is not on the line,
+ * which is what an internally synthesised argv looks like.
+ */
+export declare function argsFromCommand(rawArgs: readonly string[], command: string): string[];

package/dist/utils/dev-preflight.d.ts

@@ -18,6 +18,11 @@ export type PreflightOutcome = {
 } | {
     action: "start-failed";
     hint: string;
+} | {
+    action: "wrong-port";
+    hint: string;
+    port: number;
+    composePort: number;
 } | {
     action: "started";
     port: number;
@@ -43,6 +48,40 @@ export declare function parseLoopbackDsn(dsn: string | undefined): {
  * manual steps, which are correct.
  */
 export declare function composeDeclaresDbService(yamlText: string): boolean;
+/**
+ * The connection string the compose file's `db` service will answer on.
+ *
+ * `--docker` used to be a flag that changed a banner and nothing else: it
+ * resolved to `kind: "docker"`, and every caller then had no URL to reach the
+ * container with, so the backend booted with no `DATABASE_URL` at all and died
+ * on the message a project with no database gets. The container it had just
+ * been asked for was never started, because the preflight that starts it needs
+ * a DSN to decide the database is local and not running.
+ *
+ * So the URL is derived rather than required: the compose file names the user,
+ * the database and the published host port, and `.env` holds the password
+ * compose itself interpolates. That is the same string `rebase init` writes as
+ * the commented-out `DATABASE_URL`, which is what makes uncommenting that line
+ * and passing `--docker` reach the same database.
+ *
+ * Returns null when the file declares no `db` service, or declares one this
+ * scan cannot read — a `--docker` that cannot be honoured has to say so, and
+ * a guess would point at somebody else's Postgres on 5432.
+ *
+ * Same text scan as {@link composeDeclaresDbService}, for the same reason.
+ */
+export declare function composeDatabaseUrl(yamlText: string, env?: Record<string, string | undefined>): string | null;
+/**
+ * The host port the compose `db` service publishes, or null.
+ *
+ * Separate from {@link composeDatabaseUrl} because the port is answerable on
+ * its own: the URL needs the user, the password and the database name too, and
+ * a compose file missing any of them still says which port a container would
+ * listen on. That is the question "would starting this container answer the
+ * DSN in `.env`?" — see the `wrong-port` branch of {@link ensureDevDatabase},
+ * where getting it wrong meant starting a container nobody asked for.
+ */
+export declare function composeHostPort(yamlText: string): number | null;
 /** Is something accepting connections there right now? */
 export declare function probeTcp(host: string, port: number, timeoutMs?: number): Promise<boolean>;
 /**
@@ -64,6 +103,13 @@ export interface EnsureDevDatabaseOptions {
     hasCollections: boolean;
     /** Runs `rebase db push` for this project. Injected so tests need no database. */
     pushSchema: () => Promise<void>;
+    /**
+     * Brings the compose `db` service up. Injected for the same reason
+     * `pushSchema` is: what happens *after* a start — a push that fails without
+     * taking the dev server with it — is the part worth asserting, and it was
+     * untestable while the only way in was a real `docker compose up`.
+     */
+    startDatabase?: (projectRoot: string) => Promise<void>;
     log?: (message: string) => void;
 }
 /**

package/dist/utils/package-manager.d.ts

@@ -1,3 +1,26 @@
+/**
+ * The two package managers the CLI can scaffold for.
+ *
+ * Yarn and bun are deliberately absent, and this is the note that says so
+ * rather than leaving it to be discovered. A yarn or bun user gets an npm
+ * project: `detectPackageManager` finds no `pnpm-lock.yaml` and no
+ * `package-lock.json`, falls through to the pnpm probe, and lands on npm —
+ * silently, and with a `yarn.lock` or `bun.lockb` sitting right there in the
+ * directory it was asked about.
+ *
+ * The reason is not indifference. Every generated project is a workspace, and
+ * the scaffold writes one protocol for the workspace links —
+ * `workspaceProtocol` below is `"workspace:*"` or `"*"`. Yarn understands
+ * `workspace:*` and bun does not; the two also disagree with pnpm about where
+ * `node_modules` goes, which is what `rebase dev` walks to find the backend.
+ * Supporting them means a fourth and fifth scaffold shape, each needing its own
+ * end-to-end test, and neither exists.
+ *
+ * So the honest position is: pnpm (recommended) or npm. A yarn or bun user is
+ * better served knowing they will get an npm workspace than finding out from
+ * the lockfile that appears after their first install. See
+ * {@link detectPackageManager}, which now says so out loud.
+ */
 export type PackageManager = "pnpm" | "npm";
 export interface PMCommands {
     /** The binary name ("pnpm" | "npm"). */