@rebasepro/cli 0.24.0 → 0.24.1-canary.gcb918fc

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;
@@ -294,6 +319,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 +362,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/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/storage.d.ts

@@ -0,0 +1,46 @@
+/** Everything the switch below dispatches, for the did-you-mean. */
+export declare const STORAGE_SUBCOMMANDS: readonly ["orphans", "move"];
+/** The flags `rebase storage orphans` takes. */
+export declare const ORPHANS_FLAGS: {
+    readonly "--source": StringConstructor;
+    readonly "--older-than": NumberConstructor;
+    readonly "--delete": BooleanConstructor;
+    readonly "--yes": BooleanConstructor;
+    readonly "-y": "--yes";
+    readonly "--json": BooleanConstructor;
+};
+/** The flags `rebase storage move` takes. */
+export declare const MOVE_FLAGS: {
+    readonly "--from": StringConstructor;
+    readonly "--to": StringConstructor;
+    readonly "--prefix": StringConstructor;
+    readonly "--delete-source": BooleanConstructor;
+    readonly "--json": BooleanConstructor;
+};
+/** One stored object, as the backend lists it. */
+interface StoredObjectEntry {
+    key: string;
+    size?: number;
+    updated?: string;
+}
+/** What `GET /admin/storage/orphans` answers. */
+export interface OrphanReport {
+    storageId: string;
+    objects: number;
+    orphans: StoredObjectEntry[];
+    recent: number;
+    scanned: string[];
+    unscanned: {
+        collection: string;
+        reason: string;
+    }[];
+}
+/** Bytes, as a person reads them. */
+export declare function formatBytes(bytes: number): string;
+/**
+ * The lines that describe an orphan scan. Exported so its tests can read them
+ * without a server.
+ */
+export declare function describeOrphanReport(report: OrphanReport, olderThanHours: number): string[];
+export declare function storageCommand(subcommand: string | undefined, rawArgs: string[]): Promise<void>;
+export {};

package/dist/consent-BWHaYx5p.js

@@ -0,0 +1,76 @@
+import { a as setConsent, c as buildEvent, f as readConfig, o as suppressionReason } from "./telemetry-CAWNCugs.js";
+import chalk from "chalk";
+import inquirer from "inquirer";
+//#region src/telemetry/consent.ts
+/** True when we may ask: nothing forbids it, and there is a question to ask. */
+function shouldPrompt(env = process.env, { reAskDeclined = false } = {}) {
+	if (!process.stdin.isTTY) return false;
+	const reason = suppressionReason(env);
+	if (reason === "not_asked") return true;
+	return reAskDeclined && reason === "declined";
+}
+function renderPreview(event, properties) {
+	const preview = buildEvent(event, properties, {
+		machineId: "<random uuid, generated only if you say yes>",
+		projectId: "<random uuid, per checkout>"
+	});
+	return JSON.stringify(preview, null, 2);
+}
+/**
+* Ask, record the answer, and report it.
+*
+* Never throws and never blocks a non-interactive run: `rebase init --yes` in
+* CI must behave exactly as it does today, which means not asking and not
+* sending.
+*/
+async function promptForConsent(options = {}) {
+	if (!shouldPrompt(process.env, options)) return false;
+	const askedBefore = suppressionReason(process.env) === "declined";
+	try {
+		console.log("");
+		console.log(chalk.bold("Help improve Rebase?"));
+		console.log("");
+		console.log(chalk.gray("  Rebase is self-hosted, so we only learn what works if you tell us."));
+		console.log(chalk.gray("  Anonymous: random ids, the CLI version, your OS, and which template and"));
+		console.log(chalk.gray("  package manager you used. Never project names, paths, schemas, URLs or"));
+		console.log(chalk.gray("  error messages."));
+		console.log("");
+		console.log(chalk.gray(`  Print the exact payload with ${chalk.cyan("rebase telemetry show")}; change your mind`));
+		console.log(chalk.gray(`  any time with ${chalk.cyan("rebase telemetry disable")}.`));
+		if (askedBefore) {
+			console.log("");
+			console.log(chalk.gray("  You declined before; that stands unless you change it here."));
+		}
+		console.log("");
+		const { accepted } = await inquirer.prompt([{
+			type: "confirm",
+			name: "accepted",
+			message: "Share anonymous usage data?",
+			default: true
+		}]);
+		setConsent(Boolean(accepted));
+		console.log(accepted ? chalk.green("  Thank you — sharing enabled.") : chalk.gray("  Nothing will be sent." + (options.reAskDeclined ? " You will be asked again the next time you scaffold a project." : " You will not be asked again.")));
+		console.log("");
+		return Boolean(accepted);
+	} catch {
+		return false;
+	}
+}
+/** Human-readable current state, for `rebase telemetry status`. */
+function describeState(env = process.env) {
+	const reason = suppressionReason(env);
+	const config = readConfig();
+	switch (reason) {
+		case null: return `${chalk.green("enabled")} — schema v1, machine id ${chalk.gray(config.machineId ?? "unset")}`;
+		case "not_asked": return `${chalk.yellow("not configured")} — nothing has been sent, and you have not been asked yet`;
+		case "declined": return `${chalk.gray("disabled")} — you declined${config.decidedAt ? ` on ${config.decidedAt.slice(0, 10)}` : ""}`;
+		case "do_not_track": return `${chalk.gray("disabled")} — the ${chalk.cyan("DO_NOT_TRACK")} environment variable is set`;
+		case "rebase_telemetry_disabled": return `${chalk.gray("disabled")} — the ${chalk.cyan("REBASE_TELEMETRY_DISABLED")} environment variable is set`;
+		case "ci": return `${chalk.gray("disabled")} — this looks like CI (${chalk.cyan("CI")} is set), which is never counted`;
+		case "project_opt_out": return `${chalk.gray("disabled")} — this project's ${chalk.cyan("rebase.json")} sets ${chalk.cyan("\"telemetry\": false")}`;
+	}
+}
+//#endregion
+export { promptForConsent as n, renderPreview as r, describeState as t };
+
+//# sourceMappingURL=consent-BWHaYx5p.js.map

package/dist/consent-BWHaYx5p.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent-BWHaYx5p.js","names":[],"sources":["../src/telemetry/consent.ts"],"sourcesContent":["import chalk from \"chalk\";\nimport inquirer from \"inquirer\";\n\nimport { buildEvent, TELEMETRY_SCHEMA_VERSION, TelemetryEventName } from \"./payload\";\nimport { readConfig } from \"./identity\";\nimport { setConsent, suppressionReason } from \"./index\";\n\n/**\n * Asking, and what the question looks like.\n *\n * ## Why the prompt comes *after* the work\n *\n * The first `rebase init` on a machine is the event most worth having, and it\n * is the one where no consent exists yet. Asking before scaffolding puts a\n * privacy negotiation in front of someone who has not yet seen the tool do\n * anything — the worst possible moment, and a reliable way to get a reflexive\n * no.\n *\n * So the question is asked once the project exists and the user has seen it\n * work. The event's data is still in memory at that point, so nothing is lost\n * by waiting, and — this is the part that matters — **nothing has been\n * transmitted or written**. Declining leaves no id, no file, no record.\n *\n * ## Why the payload is shown rather than described\n *\n * \"Anonymous usage data\" is a phrase that has been used to mean almost\n * anything. Printing the exact JSON costs four lines of output and replaces a\n * claim the user has to take on faith with something they can read. It is also\n * the same builder the sender uses, so it cannot drift into a comfortable\n * fiction.\n */\n\n/** Where the question is being asked from, which decides how often it may be. */\nexport interface PromptOptions {\n    /**\n     * Ask again even though this machine already declined.\n     *\n     * Set by `rebase init`, and only there. Scaffolding a project is a\n     * deliberate, occasional act with a natural pause in it — not something\n     * anyone does in a loop — so asking each time is an offer rather than\n     * nagging, and it reaches the person whose first answer was a reflex before\n     * they had seen the tool do anything.\n     *\n     * It does **not** re-ask someone who accepted: they are already sharing, so\n     * the only thing another prompt could do is talk them out of it.\n     *\n     * Nothing else changes. `DO_NOT_TRACK`, `REBASE_TELEMETRY_DISABLED`, `CI`\n     * and a project's `\"telemetry\": false` are answers, not questions, and they\n     * still suppress the prompt entirely — a re-ask that could override a\n     * committed repository policy would be exactly the consent-by-proxy the\n     * policy exists to prevent.\n     */\n    reAskDeclined?: boolean;\n}\n\n/** True when we may ask: nothing forbids it, and there is a question to ask. */\nexport function shouldPrompt(\n    env: NodeJS.ProcessEnv = process.env,\n    { reAskDeclined = false }: PromptOptions = {}\n): boolean {\n    if (!process.stdin.isTTY) return false;\n\n    const reason = suppressionReason(env);\n    // `not_asked` is the only reason that is a question rather than an answer.\n    // A user who set DO_NOT_TRACK, or is on CI, has already told us — and so\n    // has one who is already sharing (`null`), whom we never re-ask.\n    if (reason === \"not_asked\") return true;\n    return reAskDeclined && reason === \"declined\";\n}\n\nexport function renderPreview(event: TelemetryEventName, properties: Record<string, unknown>): string {\n    const preview = buildEvent(event, properties, {\n        machineId: \"<random uuid, generated only if you say yes>\",\n        projectId: \"<random uuid, per checkout>\"\n    });\n    return JSON.stringify(preview, null, 2);\n}\n\n/**\n * Ask, record the answer, and report it.\n *\n * Never throws and never blocks a non-interactive run: `rebase init --yes` in\n * CI must behave exactly as it does today, which means not asking and not\n * sending.\n */\nexport async function promptForConsent(options: PromptOptions = {}): Promise<boolean> {\n    if (!shouldPrompt(process.env, options)) return false;\n\n    // Only true when this is a second (or later) asking, which the closing line\n    // needs to know: \"you will not be asked again\" is false at `init`.\n    const askedBefore = suppressionReason(process.env) === \"declined\";\n\n    try {\n        console.log(\"\");\n        console.log(chalk.bold(\"Help improve Rebase?\"));\n        console.log(\"\");\n        console.log(chalk.gray(\"  Rebase is self-hosted, so we only learn what works if you tell us.\"));\n        console.log(chalk.gray(\"  Anonymous: random ids, the CLI version, your OS, and which template and\"));\n        console.log(chalk.gray(\"  package manager you used. Never project names, paths, schemas, URLs or\"));\n        console.log(chalk.gray(\"  error messages.\"));\n        console.log(\"\");\n        console.log(chalk.gray(`  Print the exact payload with ${chalk.cyan(\"rebase telemetry show\")}; change your mind`));\n        console.log(chalk.gray(`  any time with ${chalk.cyan(\"rebase telemetry disable\")}.`));\n        if (askedBefore) {\n            console.log(\"\");\n            console.log(chalk.gray(\"  You declined before; that stands unless you change it here.\"));\n        }\n        console.log(\"\");\n\n        const { accepted } = await inquirer.prompt([\n            {\n                type: \"confirm\",\n                name: \"accepted\",\n                message: \"Share anonymous usage data?\",\n                // Defaults to yes: this is the question the project most needs\n                // answered, and a bare Enter is the commonest answer to any\n                // prompt. It is still a question — nothing is sent until it is\n                // answered, `n` is one keystroke, and the decision is\n                // reversible with the command named two lines above. What it\n                // is NOT is \"off by default\" any more; anything that used to\n                // say so had to change with it.\n                default: true\n            }\n        ] as Parameters<typeof inquirer.prompt>[0]) as { accepted: boolean };\n\n        setConsent(Boolean(accepted));\n\n        console.log(\n            accepted\n                ? chalk.green(\"  Thank you — sharing enabled.\")\n                : chalk.gray(\n                    \"  Nothing will be sent.\"\n                    + (options.reAskDeclined\n                        ? \" You will be asked again the next time you scaffold a project.\"\n                        : \" You will not be asked again.\")\n                )\n        );\n        console.log(\"\");\n        return Boolean(accepted);\n    } catch {\n        // A prompt that fails (piped stdin, a terminal that went away) is a\n        // decline, and specifically a decline we do not persist — the user\n        // never actually saw the question, so they should still get to answer\n        // it another day.\n        return false;\n    }\n}\n\n/** Human-readable current state, for `rebase telemetry status`. */\nexport function describeState(env: NodeJS.ProcessEnv = process.env): string {\n    const reason = suppressionReason(env);\n    const config = readConfig();\n    switch (reason) {\n        case null:\n            return `${chalk.green(\"enabled\")} — schema v${TELEMETRY_SCHEMA_VERSION}, machine id ${chalk.gray(config.machineId ?? \"unset\")}`;\n        case \"not_asked\":\n            return `${chalk.yellow(\"not configured\")} — nothing has been sent, and you have not been asked yet`;\n        case \"declined\":\n            return `${chalk.gray(\"disabled\")} — you declined${config.decidedAt ? ` on ${config.decidedAt.slice(0, 10)}` : \"\"}`;\n        case \"do_not_track\":\n            return `${chalk.gray(\"disabled\")} — the ${chalk.cyan(\"DO_NOT_TRACK\")} environment variable is set`;\n        case \"rebase_telemetry_disabled\":\n            return `${chalk.gray(\"disabled\")} — the ${chalk.cyan(\"REBASE_TELEMETRY_DISABLED\")} environment variable is set`;\n        case \"ci\":\n            return `${chalk.gray(\"disabled\")} — this looks like CI (${chalk.cyan(\"CI\")} is set), which is never counted`;\n        case \"project_opt_out\":\n            return `${chalk.gray(\"disabled\")} — this project's ${chalk.cyan(\"rebase.json\")} sets ${chalk.cyan('\"telemetry\": false')}`;\n    }\n}\n"],"mappings":";;;;;AAwDA,SAAgB,aACZ,MAAyB,QAAQ,KACjC,EAAE,gBAAgB,UAAyB,CAAC,GACrC;CACP,IAAI,CAAC,QAAQ,MAAM,OAAO,OAAO;CAEjC,MAAM,SAAS,kBAAkB,GAAG;CAIpC,IAAI,WAAW,aAAa,OAAO;CACnC,OAAO,iBAAiB,WAAW;AACvC;AAEA,SAAgB,cAAc,OAA2B,YAA6C;CAClG,MAAM,UAAU,WAAW,OAAO,YAAY;EAC1C,WAAW;EACX,WAAW;CACf,CAAC;CACD,OAAO,KAAK,UAAU,SAAS,MAAM,CAAC;AAC1C;;;;;;;;AASA,eAAsB,iBAAiB,UAAyB,CAAC,GAAqB;CAClF,IAAI,CAAC,aAAa,QAAQ,KAAK,OAAO,GAAG,OAAO;CAIhD,MAAM,cAAc,kBAAkB,QAAQ,GAAG,MAAM;CAEvD,IAAI;EACA,QAAQ,IAAI,EAAE;EACd,QAAQ,IAAI,MAAM,KAAK,sBAAsB,CAAC;EAC9C,QAAQ,IAAI,EAAE;EACd,QAAQ,IAAI,MAAM,KAAK,sEAAsE,CAAC;EAC9F,QAAQ,IAAI,MAAM,KAAK,2EAA2E,CAAC;EACnG,QAAQ,IAAI,MAAM,KAAK,0EAA0E,CAAC;EAClG,QAAQ,IAAI,MAAM,KAAK,mBAAmB,CAAC;EAC3C,QAAQ,IAAI,EAAE;EACd,QAAQ,IAAI,MAAM,KAAK,kCAAkC,MAAM,KAAK,uBAAuB,EAAE,mBAAmB,CAAC;EACjH,QAAQ,IAAI,MAAM,KAAK,mBAAmB,MAAM,KAAK,0BAA0B,EAAE,EAAE,CAAC;EACpF,IAAI,aAAa;GACb,QAAQ,IAAI,EAAE;GACd,QAAQ,IAAI,MAAM,KAAK,+DAA+D,CAAC;EAC3F;EACA,QAAQ,IAAI,EAAE;EAEd,MAAM,EAAE,aAAa,MAAM,SAAS,OAAO,CACvC;GACI,MAAM;GACN,MAAM;GACN,SAAS;GAQT,SAAS;EACb,CACJ,CAA0C;EAE1C,WAAW,QAAQ,QAAQ,CAAC;EAE5B,QAAQ,IACJ,WACM,MAAM,MAAM,gCAAgC,IAC5C,MAAM,KACJ,6BACG,QAAQ,gBACL,mEACA,gCACV,CACR;EACA,QAAQ,IAAI,EAAE;EACd,OAAO,QAAQ,QAAQ;CAC3B,QAAQ;EAKJ,OAAO;CACX;AACJ;;AAGA,SAAgB,cAAc,MAAyB,QAAQ,KAAa;CACxE,MAAM,SAAS,kBAAkB,GAAG;CACpC,MAAM,SAAS,WAAW;CAC1B,QAAQ,QAAR;EACI,KAAK,MACD,OAAO,GAAG,MAAM,MAAM,SAAS,EAAE,2BAAqD,MAAM,KAAK,OAAO,aAAa,OAAO;EAChI,KAAK,aACD,OAAO,GAAG,MAAM,OAAO,gBAAgB,EAAE;EAC7C,KAAK,YACD,OAAO,GAAG,MAAM,KAAK,UAAU,EAAE,iBAAiB,OAAO,YAAY,OAAO,OAAO,UAAU,MAAM,GAAG,EAAE,MAAM;EAClH,KAAK,gBACD,OAAO,GAAG,MAAM,KAAK,UAAU,EAAE,SAAS,MAAM,KAAK,cAAc,EAAE;EACzE,KAAK,6BACD,OAAO,GAAG,MAAM,KAAK,UAAU,EAAE,SAAS,MAAM,KAAK,2BAA2B,EAAE;EACtF,KAAK,MACD,OAAO,GAAG,MAAM,KAAK,UAAU,EAAE,yBAAyB,MAAM,KAAK,IAAI,EAAE;EAC/E,KAAK,mBACD,OAAO,GAAG,MAAM,KAAK,UAAU,EAAE,oBAAoB,MAAM,KAAK,aAAa,EAAE,QAAQ,MAAM,KAAK,sBAAoB;CAC9H;AACJ"}