@rebasepro/cli 0.24.0 → 0.24.1-canary.g19596ef

package/dist/collection-drift-BKj_BoMq.js

@@ -0,0 +1,106 @@
+import fs from "fs";
+import path from "path";
+import { DEFAULT_DATA_SOURCE_KEY, getDataSourceCapabilities } from "@rebasepro/types";
+//#region src/utils/collection-drift.ts
+/**
+* Which edits under `config/collections` can put the *SQL* schema out of date.
+*
+* `rebase dev` watches that directory and, on any change, either tells the
+* developer to run `rebase schema generate` / `rebase db push` or runs them.
+* The watcher is recursive and knows nothing about what it is watching, so it
+* said that about every file under the directory — including a
+* `collections/firestore/exercises.ts`, whose documents live in Firestore and
+* for which there is no Drizzle schema to regenerate and no database to push
+* to. Advice that is wrong on every edit is advice a developer learns to
+* ignore, which is worse than none: the same box is the only warning for the
+* Postgres collection next to it, where it is real.
+*
+* Two independent reasons a change cannot affect the SQL schema, both checked
+* here:
+*
+* 1. **The loader would never read the file.** `loadCollectionsFromDirectory`
+*    reads the top level of the collections directory only — no recursion, no
+*    `index`, no tests, no declarations. A file it does not read cannot change
+*    what it returns, and the watcher must not claim otherwise.
+* 2. **Every collection in it is served by another engine.** A Firestore or
+*    MongoDB collection has no table, no migration and no policies.
+*
+* The engine check reads the source text rather than importing the module: the
+* CLI runs as plain Node and cannot evaluate a project's TypeScript, and a
+* watcher must answer in the time between two keystrokes. Anything it cannot
+* read confidently counts as SQL-affecting — a spurious warning is a nuisance,
+* a suppressed one hides real drift.
+*/
+/**
+* Would `loadCollectionsFromDirectory` load this file?
+*
+* Mirrors that loader's own `isCollectionFile` plus its flat (non-recursive)
+* scan. `relativePath` is relative to the collections directory, as `fs.watch`
+* reports it.
+*/
+function isLoadedCollectionFile(relativePath) {
+	const normalized = relativePath.split(path.sep).join("/");
+	if (normalized.includes("/")) return false;
+	const file = normalized;
+	if (!file.endsWith(".ts") && !file.endsWith(".js")) return false;
+	if (file.startsWith(".")) return false;
+	if (file.includes(".test.")) return false;
+	if (file.endsWith(".d.ts")) return false;
+	if (file === "index.ts" || file === "index.js") return false;
+	return true;
+}
+var ENGINE_LITERAL = /\bengine\s*:\s*["'`]([^"'`]+)["'`]/g;
+var DATA_SOURCE_LITERAL = /\bdataSource\s*:\s*["'`]([^"'`]+)["'`]/g;
+/**
+* Drop comments, so a `// engine: "firestore"` in a docblock cannot silence a
+* warning about the Postgres collection the file actually declares.
+*
+* Deliberately naive — it does not understand strings, so a `//` inside one
+* (a URL in a default value) eats the rest of that line. That only ever removes
+* text, and removing an engine literal makes this file *more* likely to warn,
+* which is the side to be wrong on.
+*/
+function stripComments(source) {
+	return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ");
+}
+function literals(source, pattern) {
+	const found = [];
+	for (const match of source.matchAll(pattern)) found.push(match[1]);
+	return found;
+}
+/**
+* Does this collection source declare anything a SQL toolchain would own?
+*
+* The fallback order matches `resolveDataSource`: an explicit `engine` wins,
+* and a collection that only names a `dataSource` is resolved as if the key
+* were the engine — which is what that function does when no registry is
+* available, and the CLI has none. An engine nobody recognises counts as
+* relational, for the reason `isRelationalCollection` gives.
+*
+* A file declaring several collections is SQL-affecting if *any* of them is.
+*/
+function declaresRelationalCollection(rawSource) {
+	const source = stripComments(rawSource);
+	const engines = literals(source, ENGINE_LITERAL);
+	const declared = engines.length > 0 ? engines : literals(source, DATA_SOURCE_LITERAL).filter((key) => key !== DEFAULT_DATA_SOURCE_KEY);
+	if (declared.length === 0) return true;
+	return declared.some((engine) => getDataSourceCapabilities(engine).supportsRelations);
+}
+/**
+* Can this edit have changed the generated SQL schema?
+*
+* Answers `true` when it cannot tell — an unreadable file is a reason to warn,
+* not a reason to go quiet.
+*/
+function affectsSqlSchema(collectionsDir, relativePath) {
+	if (!isLoadedCollectionFile(relativePath)) return false;
+	try {
+		return declaresRelationalCollection(fs.readFileSync(path.join(collectionsDir, relativePath), "utf8"));
+	} catch {
+		return true;
+	}
+}
+//#endregion
+export { isLoadedCollectionFile as n, affectsSqlSchema as t };
+
+//# sourceMappingURL=collection-drift-BKj_BoMq.js.map

package/dist/collection-drift-BKj_BoMq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-drift-BKj_BoMq.js","names":[],"sources":["../src/utils/collection-drift.ts"],"sourcesContent":["/**\n * Which edits under `config/collections` can put the *SQL* schema out of date.\n *\n * `rebase dev` watches that directory and, on any change, either tells the\n * developer to run `rebase schema generate` / `rebase db push` or runs them.\n * The watcher is recursive and knows nothing about what it is watching, so it\n * said that about every file under the directory — including a\n * `collections/firestore/exercises.ts`, whose documents live in Firestore and\n * for which there is no Drizzle schema to regenerate and no database to push\n * to. Advice that is wrong on every edit is advice a developer learns to\n * ignore, which is worse than none: the same box is the only warning for the\n * Postgres collection next to it, where it is real.\n *\n * Two independent reasons a change cannot affect the SQL schema, both checked\n * here:\n *\n * 1. **The loader would never read the file.** `loadCollectionsFromDirectory`\n *    reads the top level of the collections directory only — no recursion, no\n *    `index`, no tests, no declarations. A file it does not read cannot change\n *    what it returns, and the watcher must not claim otherwise.\n * 2. **Every collection in it is served by another engine.** A Firestore or\n *    MongoDB collection has no table, no migration and no policies.\n *\n * The engine check reads the source text rather than importing the module: the\n * CLI runs as plain Node and cannot evaluate a project's TypeScript, and a\n * watcher must answer in the time between two keystrokes. Anything it cannot\n * read confidently counts as SQL-affecting — a spurious warning is a nuisance,\n * a suppressed one hides real drift.\n */\nimport fs from \"fs\";\nimport path from \"path\";\nimport { DEFAULT_DATA_SOURCE_KEY, getDataSourceCapabilities } from \"@rebasepro/types\";\n\n/**\n * Would `loadCollectionsFromDirectory` load this file?\n *\n * Mirrors that loader's own `isCollectionFile` plus its flat (non-recursive)\n * scan. `relativePath` is relative to the collections directory, as `fs.watch`\n * reports it.\n */\nexport function isLoadedCollectionFile(relativePath: string): boolean {\n    const normalized = relativePath.split(path.sep).join(\"/\");\n    // A nested path is a subdirectory, which the loader does not descend into.\n    if (normalized.includes(\"/\")) return false;\n\n    const file = normalized;\n    if (!file.endsWith(\".ts\") && !file.endsWith(\".js\")) return false;\n    if (file.startsWith(\".\")) return false;\n    if (file.includes(\".test.\")) return false;\n    if (file.endsWith(\".d.ts\")) return false;\n    // The directory's own module: defaults live there, not a collection.\n    if (file === \"index.ts\" || file === \"index.js\") return false;\n    return true;\n}\n\nconst ENGINE_LITERAL = /\\bengine\\s*:\\s*[\"'`]([^\"'`]+)[\"'`]/g;\nconst DATA_SOURCE_LITERAL = /\\bdataSource\\s*:\\s*[\"'`]([^\"'`]+)[\"'`]/g;\n\n/**\n * Drop comments, so a `// engine: \"firestore\"` in a docblock cannot silence a\n * warning about the Postgres collection the file actually declares.\n *\n * Deliberately naive — it does not understand strings, so a `//` inside one\n * (a URL in a default value) eats the rest of that line. That only ever removes\n * text, and removing an engine literal makes this file *more* likely to warn,\n * which is the side to be wrong on.\n */\nfunction stripComments(source: string): string {\n    return source.replace(/\\/\\*[\\s\\S]*?\\*\\//g, \" \").replace(/\\/\\/[^\\n]*/g, \" \");\n}\n\nfunction literals(source: string, pattern: RegExp): string[] {\n    const found: string[] = [];\n    for (const match of source.matchAll(pattern)) found.push(match[1]);\n    return found;\n}\n\n/**\n * Does this collection source declare anything a SQL toolchain would own?\n *\n * The fallback order matches `resolveDataSource`: an explicit `engine` wins,\n * and a collection that only names a `dataSource` is resolved as if the key\n * were the engine — which is what that function does when no registry is\n * available, and the CLI has none. An engine nobody recognises counts as\n * relational, for the reason `isRelationalCollection` gives.\n *\n * A file declaring several collections is SQL-affecting if *any* of them is.\n */\nexport function declaresRelationalCollection(rawSource: string): boolean {\n    const source = stripComments(rawSource);\n    const engines = literals(source, ENGINE_LITERAL);\n    const declared = engines.length > 0\n        ? engines\n        : literals(source, DATA_SOURCE_LITERAL).filter(key => key !== DEFAULT_DATA_SOURCE_KEY);\n\n    if (declared.length === 0) return true;\n    return declared.some(engine => getDataSourceCapabilities(engine).supportsRelations);\n}\n\n/**\n * Can this edit have changed the generated SQL schema?\n *\n * Answers `true` when it cannot tell — an unreadable file is a reason to warn,\n * not a reason to go quiet.\n */\nexport function affectsSqlSchema(collectionsDir: string, relativePath: string): boolean {\n    if (!isLoadedCollectionFile(relativePath)) return false;\n    try {\n        return declaresRelationalCollection(\n            fs.readFileSync(path.join(collectionsDir, relativePath), \"utf8\")\n        );\n    } catch {\n        // Deleted between the event and the read, or unreadable. Both leave the\n        // schema genuinely in question.\n        return true;\n    }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,uBAAuB,cAA+B;CAClE,MAAM,aAAa,aAAa,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG;CAExD,IAAI,WAAW,SAAS,GAAG,GAAG,OAAO;CAErC,MAAM,OAAO;CACb,IAAI,CAAC,KAAK,SAAS,KAAK,KAAK,CAAC,KAAK,SAAS,KAAK,GAAG,OAAO;CAC3D,IAAI,KAAK,WAAW,GAAG,GAAG,OAAO;CACjC,IAAI,KAAK,SAAS,QAAQ,GAAG,OAAO;CACpC,IAAI,KAAK,SAAS,OAAO,GAAG,OAAO;CAEnC,IAAI,SAAS,cAAc,SAAS,YAAY,OAAO;CACvD,OAAO;AACX;AAEA,IAAM,iBAAiB;AACvB,IAAM,sBAAsB;;;;;;;;;;AAW5B,SAAS,cAAc,QAAwB;CAC3C,OAAO,OAAO,QAAQ,qBAAqB,GAAG,CAAC,CAAC,QAAQ,eAAe,GAAG;AAC9E;AAEA,SAAS,SAAS,QAAgB,SAA2B;CACzD,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,SAAS,OAAO,SAAS,OAAO,GAAG,MAAM,KAAK,MAAM,EAAE;CACjE,OAAO;AACX;;;;;;;;;;;;AAaA,SAAgB,6BAA6B,WAA4B;CACrE,MAAM,SAAS,cAAc,SAAS;CACtC,MAAM,UAAU,SAAS,QAAQ,cAAc;CAC/C,MAAM,WAAW,QAAQ,SAAS,IAC5B,UACA,SAAS,QAAQ,mBAAmB,CAAC,CAAC,QAAO,QAAO,QAAQ,uBAAuB;CAEzF,IAAI,SAAS,WAAW,GAAG,OAAO;CAClC,OAAO,SAAS,MAAK,WAAU,0BAA0B,MAAM,CAAC,CAAC,iBAAiB;AACtF;;;;;;;AAQA,SAAgB,iBAAiB,gBAAwB,cAA+B;CACpF,IAAI,CAAC,uBAAuB,YAAY,GAAG,OAAO;CAClD,IAAI;EACA,OAAO,6BACH,GAAG,aAAa,KAAK,KAAK,gBAAgB,YAAY,GAAG,MAAM,CACnE;CACJ,QAAQ;EAGJ,OAAO;CACX;AACJ"}

package/dist/commands/api-keys.d.ts

@@ -1,6 +1,8 @@
 import { type ApiKeyMasked, type ScopeSummary } from "@rebasepro/types";
 /** Everything the switch below dispatches, for the did-you-mean. */
 export declare const API_KEYS_SUBCOMMANDS: readonly ["list", "get", "create", "revoke", "scopes"];
+/** The running backend's URL. Shared with `rebase storage`. */
+export declare function resolveBaseUrl(env: Record<string, string>, projectRoot?: string): string;
 /**
  * What to print when a request fails: the server's error code and message,
  * which is what says why — `SCOPE_EXCEEDS_CREATOR`, `INVALID_SCOPES`,

package/dist/commands/console.d.ts

@@ -0,0 +1,12 @@
+export declare const CONSOLE_FLAGS: {
+    readonly "--eval": StringConstructor;
+    readonly "-e": "--eval";
+    readonly "--collections": StringConstructor;
+    readonly "-c": "--collections";
+    readonly "--database-url": StringConstructor;
+    readonly "--docker": BooleanConstructor;
+};
+/** Where the REPL keeps its history: the project's own `.rebase/`, which the scaffold ignores. */
+export declare function consoleHistoryPath(projectRoot: string): string;
+export declare function printConsoleHelp(): void;
+export declare function consoleCommand(rawArgs: string[]): Promise<void>;

package/dist/commands/db.d.ts

@@ -1,5 +1,6 @@
 import { type PreparedDatabase } from "../dev-db/prepare.js";
 import { type DevDatabase } from "../dev-db/resolve.js";
+import type { AtlasDevDatabase } from "../dev-db/atlas-dev-database.js";
 /**
  * The connection string a prepared database actually answers on.
  *
@@ -69,30 +70,35 @@ export declare class ManagedDatabaseRefusal extends Error {
 /** Print a refusal exactly as the guards used to print it themselves. */
 export declare function printManagedDatabaseRefusal(refusal: ManagedDatabaseRefusal): void;
 /**
- * Stop an Atlas-backed subcommand before it fails inside Atlas on the managed
+ * The variable the driver reads for Atlas's dev database
+ * (`ATLAS_DEV_URL_ENV` in `@rebasepro/server-postgres`, which this CLI does not
+ * depend on).
+ */
+export declare const ATLAS_DEV_URL_ENV = "REBASE_ATLAS_DEV_URL";
+/**
+ * The empty database an Atlas-backed subcommand plans against, on the managed
  * development database.
  *
- * **PGlite serves exactly one database.** `CREATE DATABASE "postgres_dev_diff"`
- * against it reports success and creates nothing, so Atlas connects its dev-url
- * straight back to the database it is meant to be comparing against, finds the
- * project's own tables there, and stops with
- * `connected database is not clean: found schema "public"`. Verified on a
- * completely fresh scaffold, so this is not a leftover-state problem that a
- * reset would fix — the model does not fit the engine.
- *
- * Before this guard the failure was worse than unhelpful. The first thing the
- * reader hit was `pq: SSL is not enabled on the server`, whose remedy box said
- * to append `sslmode=disable` to `DATABASE_URL` — a variable `rebase init`
- * deliberately leaves unset, which is the very reason the managed database was
- * in use. Two errors deep, about a variable that does not exist, for a command
- * the quickstart told them to run.
- *
- * There is nothing to fix by trying harder here: Atlas's other dev-url option
- * is `docker://`, and needing Docker is precisely what the managed database
- * exists to avoid. So this says what the managed database can and cannot do,
- * and names the two things that work.
+ * **PGlite serves exactly one database.** Atlas computes a change by replaying
+ * the desired schema into a second, empty one; on a real server the driver
+ * makes it as `<db>_dev_diff`, but `CREATE DATABASE` against PGlite reports
+ * success and creates nothing, so Atlas connected straight back to the
+ * database it was comparing and stopped with `connected database is not
+ * clean`. These commands were refused outright on the managed database — and
+ * with them every way to drop, rename or narrow a column there, since boot
+ * only adds.
+ *
+ * So a throwaway second PGlite is started for the command instead — in
+ * memory, in this process, gone when the command ends — and handed to the
+ * driver as `REBASE_ATLAS_DEV_URL`. Nothing else about the push changes: the
+ * destructive gate is the driver's, and holds as it does everywhere.
+ *
+ * `undefined` when none is needed: another database kind (the driver makes its
+ * own), a subcommand that is not Atlas's, or a `REBASE_ATLAS_DEV_URL` the
+ * developer set. When one cannot be started — PGlite is an optional
+ * dependency — the old refusal stands, with the reason.
  */
-export declare function refuseAtlasOnManagedDatabase(rawArgs: string[], kind: string): void;
+export declare function atlasDevDatabaseFor(rawArgs: string[], kind: string, env: Readonly<Record<string, string | undefined>>, start?: () => Promise<AtlasDevDatabase>): Promise<AtlasDevDatabase | undefined>;
 /**
  * Stop `rebase db branch` before it reports a branch that is not one.
  *
@@ -121,11 +127,25 @@ export declare function refuseAtlasOnManagedDatabase(rawArgs: string[], kind: st
  * an invitation to do the broken thing, and `info` would confirm a size for a
  * database that was never made.
  *
- * `refuseAtlasOnManagedDatabase` above is the same shape for a different
- * reason, and its comment named `branch` as one of the subcommands it does not
- * cover. It does now.
+ * Push, generate and migrate had the same problem — Atlas's scratch database
+ * is a second database too — and get a throwaway PGlite of their own instead
+ * (`atlasDevDatabaseFor` above). A branch cannot: it is meant to keep the
+ * project's data, and a throwaway instance has none.
  */
 export declare function refuseBranchOnManagedDatabase(rawArgs: string[], kind: string): void;
+/**
+ * Resolve the active driver's CLI and the environment it should run in.
+ *
+ * Shared by the two runners below. Deliberately does NOT resolve a database:
+ * `schema generate` reads collection files and writes one file, and starting a
+ * database to run it would be a side effect nobody asked for.
+ */
+export declare function resolveDriverCli(): Promise<{
+    projectRoot: string;
+    backendDir: string;
+    pluginCli: string;
+    env: Record<string, string>;
+}>;
 /**
  * The one place this CLI spawns the driver's own CLI.
  *
@@ -147,6 +167,12 @@ export declare function refuseBranchOnManagedDatabase(rawArgs: string[], kind: s
  * tsx whenever it is installed — a devDependency of every scaffold, for exactly
  * this reason. Without it a `.ts` entry cannot run at all; a built entry still
  * runs, and the subcommands that never touch the project's TypeScript still work.
+ *
+ * tsx's loader in one Node (`node --import`) rather than the `tsx` binary,
+ * which is a shell shim and a relay Node in front of the same loader: one Node
+ * start instead of two, ~50–100 ms on each of the driver runs every `rebase
+ * dev` start and every collection save makes. The binary stays the fallback for
+ * a tsx whose loader does not resolve as a package — a global install.
  */
 export declare function spawnDriverCli(resolved: {
     projectRoot: string;
@@ -171,6 +197,20 @@ export declare function runDriverDbCommand(rawArgs: string[], options?: {
     quiet?: boolean;
 }): Promise<void>;
 export declare function dbCommand(subcommand: string | undefined, rawArgs: string[]): Promise<void>;
+/**
+ * Start the compose database a `db … --docker` was asked to talk to.
+ *
+ * `--docker` resolved the compose URL and stopped there, so every `db`
+ * subcommand carrying it reached a container nobody had started —
+ * `ECONNREFUSED 127.0.0.1:5436`, two lines, no diagnosis — including the
+ * commands the managed-database refusals send readers to `--docker` for.
+ *
+ * `rebase dev --docker`'s preflight, called with the compose URL and nothing
+ * to push: this is not a schema step, and `rebase db push --docker` is the
+ * push. A failure here is reported and not fatal — the command runs and its
+ * own connection error follows, which is the same contract `dev` keeps.
+ */
+export declare function ensureDockerDatabase(projectRoot: string, rawArgs: readonly string[]): Promise<void>;
 /** Every subcommand the family dispatches — the help table's keys. */
 export declare const DB_SUBCOMMANDS: string[];
 /**

package/dist/commands/dev.d.ts

@@ -30,6 +30,21 @@ import { type PreparedDatabase } from "../dev-db/prepare.js";
  * Exported so `dev-crash-marker.test.ts` can hold the running tsx to it.
  */
 export declare const WATCHER_RESTART_MARKER: RegExp;
+/**
+ * Calls `onLine` with each line a child process writes to `stream`.
+ *
+ * A pipe hands over whatever has been written so far, so one line can arrive
+ * in two chunks. Split chunk by chunk, "Server running at http://localhost:3001"
+ * could read as two fragments that neither matched, and `rebase dev` then
+ * never announced the backend or started the admin panel. So the piece after
+ * the last newline is held for the next chunk, decoded as UTF-8 across chunk
+ * boundaries. A held piece is handed over at the end of the stream, or after
+ * `idleFlushMs` with nothing more written, so a prompt or a progress line
+ * still shows when it is written.
+ *
+ * Exported for its test.
+ */
+export declare function forEachOutputLine(stream: NodeJS.ReadableStream | null | undefined, onLine: (line: string) => void, idleFlushMs?: number): void;
 /**
  * The corrected banner line, when the backend says it moved port.
  *
@@ -95,6 +110,16 @@ export declare function devRestartTrigger(projectRoot: string): string | null;
  * collections directory alone (`--exclude` wins over its dependency tracking),
  * and dev restarts the backend itself, once, after the regeneration — through
  * `restartTrigger`, which tsx watches.
+ *
+ * Every included directory also gets tsx's own default ignores, made absolute.
+ * tsx resolves those defaults (`**\/node_modules/**`, `**\/.*`, …) against its
+ * cwd, which is `backend/`, so they never reached `config/`, a sibling: chokidar
+ * walked `config/node_modules` — following symlinks — before tsx spawned the
+ * backend at all, and kept every file in it watched. In the monorepo's example
+ * app that was 17 s before the first backend line and 1,400 open files, and any
+ * install (or another checkout's Vite build writing `.vite-temp` deep inside
+ * that tree) restarted the backend. A `.DS_Store` or an editor swap file in
+ * `config/` restarted it too.
  */
 export declare function devWatchArgs(projectRoot: string, paths: {
     REBASE_DEV_FUNCTIONS?: string;
@@ -110,12 +135,6 @@ export declare const DEV_PORT_FILENAME = ".rebase-dev-port";
  * template still says this number, so the two cannot drift apart in silence.
  */
 export declare const SCAFFOLD_DEFAULT_PORT = 3001;
-/**
- * Compute a deterministic port from the project root path.
- * Range: 3001–3999 (avoids privileged ports and common services).
- * Two different project directories will almost always get different ports.
- */
-export declare function getProjectPort(projectRoot: string): number;
 /**
  * Which rung of the ladder below decided the port.
  *
@@ -294,6 +313,21 @@ export declare const DEV_FLAGS: {
     readonly "-P": "--port";
     readonly "--no-db": BooleanConstructor;
 };
+/** What {@link ensureGeneratedSchema} did at startup. */
+export type SchemaGeneration = "generated" | "skipped" | "failed";
+/**
+ * Whether dev must still run the driver's `schema stale --fix` before the
+ * backend boots.
+ *
+ * Not after a regeneration that succeeded: that wrote `schema.generated.ts`
+ * from these collections with this driver, moments earlier, and `stale`
+ * compares the file against the same generator — it can only answer "nothing
+ * stale", and it cost a driver process (~0.6 s) on every start. The repair it
+ * exists for, a library upgrade that changed what the generator derives, is
+ * exactly what the regeneration already did. When generation was skipped or
+ * failed, the preflight is the remaining safety net and still runs.
+ */
+export declare function needsStaleSchemaPreflight(generation: SchemaGeneration): boolean;
 /**
  * One variable's value out of `.env` text, or undefined when it has none.
  *
@@ -322,4 +356,67 @@ export declare function readEnvValue(envText: string, key: string): string | und
  * it is invisible in any assertion about the push's *outcome*.
  */
 export declare function schemaPushArgv(databaseUrl: string | undefined): string[];
+/**
+ * Start-up's independent halves, overlapped rather than run one after another.
+ *
+ * `rebase dev` used to regenerate the schema and the SDK, then derive the
+ * resource graph (every collection evaluated again, in this process), then
+ * start the managed database and wait for it — about a second when it was not
+ * already running — and only then spawn the backend. None of the three reads
+ * what another writes: the generators read `config/` and write
+ * `backend/src/schema.generated.ts` and `generated/sdk/`; the derivation reads
+ * `config/resources.ts` and the collections; the database needs neither, and
+ * `schema generate` never connects to one. So `database` starts first and is
+ * collected last.
+ *
+ * `preflight` is the exception, and the reason this is not one `Promise.all`:
+ * on the `--docker` path it pushes the schema the generators have just written,
+ * so it still runs after them.
+ *
+ * A database that fails to start is reported where it always was — after the
+ * generators' and the preflight's output — rather than ahead of it, and it is
+ * never an unhandled rejection while they run.
+ *
+ * Exported for its test.
+ */
+export declare function overlapDevStartup<T>(steps: {
+    generate: () => Promise<SchemaGeneration>;
+    preflight: () => Promise<void>;
+    /** Resolve and, for the managed database, start it. `null` when this run starts none. */
+    database: (() => Promise<T>) | null;
+}): Promise<{
+    schemaGeneration: SchemaGeneration;
+    database: T | null;
+}>;
+/**
+ * Whether the admin panel can start beside the backend instead of after it.
+ *
+ * Vite has to be told the backend's URL when it starts (`VITE_API_URL`), and
+ * the backend's port is only certain once it has bound — so the admin panel
+ * used to wait for "Server running at", and the time to it was the backend's
+ * whole boot plus Vite's start. It can start beside the backend whenever the
+ * port the backend will bind is known in advance:
+ *
+ * - **named with `--port`**: the server binds it or refuses to start, never
+ *   walks past it (`REBASE_DEV_PORT_EXPLICIT`), and `pinnedPortRefusal` has
+ *   already checked that nothing answers there;
+ * - **free, and the port the backend tries first**: the server tries the port
+ *   its last run landed on before the one it is given (`.rebase-dev-port`), so
+ *   a remembered port must be this one — the "kept from the last run" rung —
+ *   or absent, which it is after every clean exit, and the derived port is
+ *   then the one tried. A port something already answers on would make the
+ *   backend move, so that case keeps the old order.
+ *
+ * Nothing here can rule out another process taking the port in the second the
+ * backend boots, so `devCommand` still compares the announced port with the
+ * one Vite was given and restarts the admin panel when they differ.
+ *
+ * Exported for its test.
+ */
+export declare function frontendCanStartWithBackend(options: {
+    projectRoot: string;
+    port: number;
+    pinned: boolean;
+    probe?: (host: string, port: number) => Promise<boolean>;
+}): Promise<boolean>;
 export declare function devCommand(rawArgs: string[]): Promise<void>;

package/dist/commands/generate_sdk.d.ts

@@ -22,8 +22,34 @@ interface GenerateSDKArgs {
     from?: string;
     /** Bearer token for the contract endpoint. Falls back to REBASE_SERVICE_KEY. */
     token?: string;
+    /**
+     * Also register the generated `Database` for server-side code: write the
+     * types and the `Register` augmentation into `config/generated/`. See
+     * {@link writeRegistration}.
+     */
+    register?: boolean;
+    /**
+     * The directory holding `rebase.json`, where `--register` is remembered.
+     * Found from `cwd` when not given.
+     */
+    projectRoot?: string;
     help?: boolean;
 }
+/** What `--register` writes, and what marks a project as having opted in. */
+export declare const REGISTER_FILE = "register.ts";
+/**
+ * Where `--register` writes: `generated/` beside the collections directory,
+ * which is `config/generated/` in a scaffolded project.
+ *
+ * Inside `config/` because that is the one directory both compiles of a
+ * collection file include: the backend's program (it includes
+ * `../config/**`) and the `config` package's own `tsc`. A registration
+ * there that imported `../generated/sdk/database.types` pulled a file from
+ * outside `config/` into that package's program, which TypeScript refuses
+ * (the file is not under its `rootDir`) — so the types are copied in beside
+ * the registration rather than imported from the SDK.
+ */
+export declare function registrationDir(collectionsDir: string): string;
 /**
  * The base URL to show in the printed usage example.
  *

package/dist/commands/init.d.ts

@@ -96,6 +96,14 @@ export type InitQuestion = {
     default: unknown;
     when?: (answers: Record<string, unknown>) => boolean;
 };
+/**
+ * Why `input` cannot be this project's `DATABASE_URL`, or null when it can.
+ *
+ * The runtime refuses anything that is not a URL, and only a Postgres one can
+ * work, so `init` refuses the same — before the scaffold is written around it.
+ * The value itself is never repeated back: it may hold a password.
+ */
+export declare function databaseUrlProblem(input: string): string | null;
 export declare function buildInitQuestions(params: BuildQuestionsParams): InitQuestion[];
 /**
  * The `cd` a user must type to enter the new project.
@@ -127,6 +135,33 @@ export declare const INIT_FLAGS: {
     "-t": string;
     "-y": string;
 };
+/** What the closing "Next steps" depend on: the project's shape, and what `init` managed to do. */
+export interface InitNextStepsInput {
+    headless: boolean;
+    /** `--database-url` was given, so `.env` names the user's own database. */
+    ownDatabase: boolean;
+    /** Introspection was asked for. */
+    introspect: boolean;
+    /** Introspection ran and produced collections. */
+    introspected: boolean;
+    /** Dependencies were installed. */
+    installed: boolean;
+    /** What the reader types to enter the project; "" when they are in it. */
+    cdTarget: string;
+    pm: PMCommands;
+}
+/**
+ * The "Next steps" `init` closes on, every command one that works as printed.
+ *
+ * Each flavour has its own steps, and the branch for one flavour must not run
+ * for another. The `--database-url` branch was checked before the headless one,
+ * so `init --headless --database-url` — the documented BaaS path — opened on
+ * `pnpm run db:push`: a script the headless scaffold does not have, for a
+ * schema it does not declare (its tables are the developer's own), with an
+ * Atlas it does not install. `init-next-steps.test.ts` holds every script
+ * named here to the scaffold it is printed for.
+ */
+export declare function initNextSteps(input: InitNextStepsInput): string[];
 /**
  * The closing "AI Agent Skills" lines, each command one its reader can run.
  *
@@ -163,6 +198,29 @@ export declare function scaffoldConflictMessage(projectName: string, displayPath
  * function created is pointed at `main`.
  */
 export declare function initGitRepository(targetDirectory: string): Promise<boolean>;
+/**
+ * Where the generated Drizzle schema for each preset ships, beside the template.
+ *
+ * `rebase dev` regenerates `backend/src/schema.generated.ts` on every start, and
+ * the Studio's schema editor refuses to commit over a dirty copy of it — a
+ * schema change must not sweep up somebody's work in progress. So whatever
+ * `init` writes there, and commits under `--git`, has to be byte-for-byte what
+ * that first regeneration produces. A stub (`export const tables = {}`) was
+ * rewritten on the first `rebase dev`, and every new project's first Studio
+ * edit was refused with `SCHEMA_EDIT_DIRTY_TREE` before its owner had changed
+ * a thing.
+ *
+ * The file cannot be generated here: generation loads the collection files,
+ * and they import `@rebasepro/cms-types`, which the project does not have
+ * until it is installed — `init --git` without `--install` commits first. So
+ * each preset's output is generated in this repository and shipped, and
+ * `init-generated-schema.test.ts` fails the moment one of them differs from
+ * what the generator writes for that preset's collections.
+ *
+ * Outside `templates/template` on purpose: a preset's schema must not be
+ * copied into a project that chose another preset.
+ */
+export declare function shippedSchemaPath(preset: TemplatePreset): string;
 /**
  * Whether `port` is free — on the wildcard address *and* on both loopback addresses.
  *

package/dist/commands/skills.d.ts

@@ -215,15 +215,27 @@ export interface InstalledAgent {
  */
 export declare function detectInstalledAgents(home?: string): InstalledAgent[];
 /** Install skills for a specific agent into the project directory. */
-export declare function installForAgent(agentKey: AgentKey, skills: LoadedSkill[], projectDir: string): {
+/**
+ * The file in each target directory that records what the installer wrote:
+ * relative path → sha256 of the bytes written. A dotfile, so no agent loads it
+ * as a rule.
+ */
+export declare const SKILLS_MANIFEST = ".rebase-skills.json";
+/** What one agent's install did. */
+export interface AgentInstallResult {
     skills: number;
     assets: number;
-};
+    /** Files left as they are because they were edited since the last install (relative to the target dir). */
+    kept: string[];
+    /** Files of skills the bundle no longer ships, removed because nobody edited them. */
+    removed: string[];
+}
+export declare function installForAgent(agentKey: AgentKey, skills: LoadedSkill[], projectDir: string, options?: {
+    force?: boolean;
+}): AgentInstallResult;
 /** What `installSkills` did for one agent. */
-export interface SkillsInstallResult {
+export interface SkillsInstallResult extends AgentInstallResult {
     agent: AgentKey;
-    skills: number;
-    assets: number;
     /** An earlier agent in the same run that already wrote this directory. */
     sharedWith?: AgentKey;
 }
@@ -233,7 +245,9 @@ export interface SkillsInstallResult {
  * Gemini and Codex both read `.agents/skills`; installing twice would write the
  * same 21 files twice and report two installs of one directory.
  */
-export declare function installSkills(agents: readonly AgentKey[], skills: LoadedSkill[], projectDir: string): SkillsInstallResult[];
+export declare function installSkills(agents: readonly AgentKey[], skills: LoadedSkill[], projectDir: string, options?: {
+    force?: boolean;
+}): SkillsInstallResult[];
 /** Everything the switch below dispatches, for the did-you-mean. */
 export declare const SKILLS_SUBCOMMANDS: readonly ["install"];
 export declare function skillsCommand(subcommand: string | undefined, rawArgs: string[]): Promise<void>;
@@ -243,10 +257,11 @@ export declare function skillsCommand(subcommand: string | undefined, rawArgs: s
  * given.
  */
 export declare function parseAgentFlags(rawArgs: string[]): AgentKey[] | null;
-/** `rebase skills install`'s whole line: the agents it names, and `--mcp`. */
+/** `rebase skills install`'s whole line: the agents it names, `--mcp` and `--force`. */
 export declare function parseSkillsInstallLine(rawArgs: string[]): {
     agents: AgentKey[] | null;
     mcp: boolean;
+    force: boolean;
 };
 /**
  * The agents a list of `--agent` values names, or null when it names none.

package/dist/commands/start.d.ts

@@ -1,4 +1,5 @@
 import type { RebaseBundleStatic } from "@rebasepro/types";
+import type { DevDatabase } from "../dev-db/resolve.js";
 /** The NODE_ENV the runtime will see, and where it comes from. */
 export interface StartNodeEnv {
     value: string | undefined;
@@ -27,4 +28,18 @@ export declare function nonProductionWarning(nodeEnv: StartNodeEnv): string[] |
  * and nothing said why. One line per such app, with a command that reaches it.
  */
 export declare function hostRoutedNotice(staticApps: readonly RebaseBundleStatic[], port: string | undefined): string[];
+/**
+ * What to say when there is no DATABASE_URL for the runtime, or `null`.
+ *
+ * The runtime requires one, and its refusal — `DATABASE_URL: is required`, and
+ * a link to the self-hosting docs — is right for a deployment and says nothing
+ * to the reader most likely to see it: someone running the scaffold's own
+ * `.env`, which leaves DATABASE_URL commented out because `rebase dev` brings a
+ * database of its own. That database is one command away, so this names it.
+ *
+ * `kind` is what `rebase dev` runs this project on, so the line can say which
+ * database `rebase db url` will print. A blank value is unset, as the runtime
+ * reads it.
+ */
+export declare function missingDatabaseUrl(env: Record<string, string | undefined>, kind: DevDatabase["kind"] | null): string[] | null;
 export declare function startCommand(rawArgs?: string[]): Promise<void>;