@rebasepro/cli 0.22.0 → 0.24.0

package/dist/{resolve-Y56osuQH.js → resolve-BAeRUBhg.js}

@@ -42,7 +42,7 @@ function resolveDevDatabase(input = {}) {
 		url: fromEnvFile,
 		source: "env-file"
 	};
-	if (input.flagDocker || input.manifestPreference === "docker") return {
+	if (input.flagDocker) return {
 		kind: "docker",
 		source: "docker",
 		url: present(input.composeUrl)
@@ -71,4 +71,4 @@ function describeDevDatabase(database) {
 //#endregion
 export { resolveDevDatabase as n, resolve_exports as r, describeDevDatabase as t };
 
-//# sourceMappingURL=resolve-Y56osuQH.js.map
+//# sourceMappingURL=resolve-BAeRUBhg.js.map

package/dist/resolve-BAeRUBhg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-BAeRUBhg.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`\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`. */\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    /**\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) {\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":";;;;;;;;;;;;;AA+GA,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,YACN,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/upgrade.d.ts

@@ -25,6 +25,11 @@ export type SpecClass =
     kind: "local";
     protocol: "link:" | "file:" | "portal:";
 }
+/** A pnpm `catalog:` reference: the version is in pnpm-workspace.yaml's catalog, and moves there. */
+ | {
+    kind: "catalog";
+    catalog: string;
+}
 /** Anything else, with the reason it is left alone. */
  | {
     kind: "other";
@@ -53,13 +58,27 @@ export interface ProjectFiles {
     packageJsons: string[];
     workspaceYamls: string[];
 }
-/** Every `package.json` and `pnpm-workspace.yaml` under the project root. */
-export declare function discoverProjectFiles(projectRoot: string): ProjectFiles;
+/** `git -C <cwd> …`, returning stdout. Throws when git is missing or refuses. */
+export type GitRunner = (cwd: string, args: string[]) => string;
+/**
+ * Every `package.json` and `pnpm-workspace.yaml` under the project root that
+ * belongs to the project.
+ *
+ * In a git repository that means what git lists: a gitignored build context,
+ * scratch copy or vendored package is not the project's, and rewriting it
+ * would change files nobody committed. The walk enters only directories that
+ * hold a listed file, so an ignored tree is not read at all. Outside a
+ * repository every directory is walked. {@link skipDirectory} applies either
+ * way.
+ */
+export declare function discoverProjectFiles(projectRoot: string, git?: GitRunner): ProjectFiles;
+/** Where a catalog pin sits: `catalog`, or `catalogs.<name>` for a named one. */
+export type CatalogField = "catalog" | `catalogs.${string}`;
 export interface ChangedPin {
     /** Relative to the project root, POSIX separators. */
     file: string;
     name: string;
-    field: PinField;
+    field: PinField | CatalogField;
     from: string;
     to: string;
 }
@@ -97,6 +116,8 @@ export interface UpgradePlan {
         absolute: string;
         content: string;
     }>;
+    /** Pins, overrides and catalog entries that were already on the target. */
+    unchanged: number;
 }
 export interface PlanOptions {
     /** Remove `link:`/`file:` overrides of framework packages instead of reporting them. */

package/dist/utils/path-flags.d.ts

@@ -0,0 +1,18 @@
+/** The rule, as every help page and error states it. */
+export declare const COLLECTIONS_PATH_RULE = "relative paths are resolved from where you run the command";
+/** The `--collections` line of a help page. */
+export declare const COLLECTIONS_FLAG_HELP = "Collections directory (default: config/collections); relative paths are resolved from where you run the command";
+/**
+ * The refusal for a `--collections` path that does not exist, or `null`.
+ *
+ * Checked by the CLI, in the reader's terms, before the driver is spawned: the
+ * driver's own check runs in `backend/` and can only describe the path it was
+ * handed. A generator pointed at a directory that is not there writes an empty
+ * schema, and a push of an empty schema drops every table — so nothing runs.
+ *
+ * Scripts written for the old rule (`--collections ../config/collections`,
+ * run from the root) land here, and the message says exactly what to change.
+ */
+export declare function missingCollectionsPath(args: readonly string[], cwd: string, backendDir: string): string[] | null;
+/** Print {@link missingCollectionsPath}'s refusal and exit 1, or return. */
+export declare function refuseMissingCollectionsPath(args: readonly string[], cwd: string, backendDir: string): void;

package/dist/utils/tool-stdio.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The stdio a build tool the CLI runs in the foreground gets: a static app's
+ * build command, `tsc`, `tar`.
+ *
+ * Inherited, so its output streams as it happens. With `quietStdout` its stdout
+ * goes to stderr instead, for a command whose own stdout carries a result:
+ * `rebase cloud deploy` in JSON mode — every piped run — owes stdout exactly one
+ * JSON value, and a `vite v6 building…` line in front of it is a result no
+ * parser can read. The tool's output still reaches the person watching.
+ */
+export declare function toolStdio(quietStdout: boolean | undefined): "inherit" | ["ignore", 2, "inherit"];

package/dist/version-DsgBmP22.js

@@ -0,0 +1,58 @@
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+//#region src/utils/version.ts
+/**
+* This CLI's own version, and the User-Agent built from it.
+*
+* Four call sites used to answer "what version am I?" and each answered it
+* differently. `cli.ts` walked one directory up from `__dirname`. `init.ts`
+* walked up looking for a folder literally named `cli`. `bundle.ts` had
+* `resolveCliVersion`, which walked up at most five levels for a manifest whose
+* `name` matched — the only one of the three that was actually correct, and the
+* one the other two did not know existed. Every HTTP request to the control
+* plane answered it not at all, which is the expensive gap: a control plane
+* cannot refuse a CLI that is too old for its wire format if no request ever
+* says which CLI is calling.
+*
+* One answer now, and it is `bundle.ts`'s: walk up for the manifest that names
+* this package, rather than counting directories or matching a folder name.
+* `dist/` is one level down in a published install and two in a source
+* checkout, and a folder called `cli` is not guaranteed to be ours. Two
+* differences from that original — `fileURLToPath` instead of `new
+* URL().pathname`, which is what makes it survive a path containing a space,
+* and no five-level ceiling.
+*/
+function readVersion() {
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	const root = path.parse(dir).root;
+	while (dir && dir !== root) {
+		const manifest = path.join(dir, "package.json");
+		if (fs.existsSync(manifest)) try {
+			const pkg = JSON.parse(fs.readFileSync(manifest, "utf-8"));
+			if (pkg.name === "@rebasepro/cli" && typeof pkg.version === "string") return pkg.version;
+		} catch {}
+		dir = path.dirname(dir);
+	}
+	return "unknown";
+}
+var cached;
+/** The CLI's version, or `"unknown"` when it cannot be read. Memoized. */
+function cliVersion() {
+	if (cached === void 0) cached = readVersion();
+	return cached;
+}
+/**
+* `rebase-cli/0.17.3` — sent on every control-plane request.
+*
+* The control plane needs it to answer `CLI_TOO_OLD` with a minimum version
+* instead of failing somewhere further in with a shape error. A client that
+* does not identify itself can only ever be refused generically.
+*/
+function cliUserAgent() {
+	return `rebase-cli/${cliVersion()}`;
+}
+//#endregion
+export { cliVersion as n, cliUserAgent as t };
+
+//# sourceMappingURL=version-DsgBmP22.js.map

package/dist/version-DsgBmP22.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-DsgBmP22.js","names":[],"sources":["../src/utils/version.ts"],"sourcesContent":["import fs from \"fs\";\nimport path from \"path\";\nimport { fileURLToPath } from \"url\";\n\n/**\n * This CLI's own version, and the User-Agent built from it.\n *\n * Four call sites used to answer \"what version am I?\" and each answered it\n * differently. `cli.ts` walked one directory up from `__dirname`. `init.ts`\n * walked up looking for a folder literally named `cli`. `bundle.ts` had\n * `resolveCliVersion`, which walked up at most five levels for a manifest whose\n * `name` matched — the only one of the three that was actually correct, and the\n * one the other two did not know existed. Every HTTP request to the control\n * plane answered it not at all, which is the expensive gap: a control plane\n * cannot refuse a CLI that is too old for its wire format if no request ever\n * says which CLI is calling.\n *\n * One answer now, and it is `bundle.ts`'s: walk up for the manifest that names\n * this package, rather than counting directories or matching a folder name.\n * `dist/` is one level down in a published install and two in a source\n * checkout, and a folder called `cli` is not guaranteed to be ours. Two\n * differences from that original — `fileURLToPath` instead of `new\n * URL().pathname`, which is what makes it survive a path containing a space,\n * and no five-level ceiling.\n */\nfunction readVersion(): string {\n    let dir = path.dirname(fileURLToPath(import.meta.url));\n    const root = path.parse(dir).root;\n    while (dir && dir !== root) {\n        const manifest = path.join(dir, \"package.json\");\n        if (fs.existsSync(manifest)) {\n            try {\n                const pkg = JSON.parse(fs.readFileSync(manifest, \"utf-8\"));\n                if (pkg.name === \"@rebasepro/cli\" && typeof pkg.version === \"string\") return pkg.version;\n            } catch {\n                // A malformed manifest on the way up is not ours to complain\n                // about; keep walking.\n            }\n        }\n        dir = path.dirname(dir);\n    }\n    return \"unknown\";\n}\n\nlet cached: string | undefined;\n\n/** The CLI's version, or `\"unknown\"` when it cannot be read. Memoized. */\nexport function cliVersion(): string {\n    if (cached === undefined) cached = readVersion();\n    return cached;\n}\n\n/**\n * `rebase-cli/0.17.3` — sent on every control-plane request.\n *\n * The control plane needs it to answer `CLI_TOO_OLD` with a minimum version\n * instead of failing somewhere further in with a shape error. A client that\n * does not identify itself can only ever be refused generically.\n */\nexport function cliUserAgent(): string {\n    return `rebase-cli/${cliVersion()}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAS,cAAsB;CAC3B,IAAI,MAAM,KAAK,QAAQ,cAAc,OAAO,KAAK,GAAG,CAAC;CACrD,MAAM,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC;CAC7B,OAAO,OAAO,QAAQ,MAAM;EACxB,MAAM,WAAW,KAAK,KAAK,KAAK,cAAc;EAC9C,IAAI,GAAG,WAAW,QAAQ,GACtB,IAAI;GACA,MAAM,MAAM,KAAK,MAAM,GAAG,aAAa,UAAU,OAAO,CAAC;GACzD,IAAI,IAAI,SAAS,oBAAoB,OAAO,IAAI,YAAY,UAAU,OAAO,IAAI;EACrF,QAAQ,CAGR;EAEJ,MAAM,KAAK,QAAQ,GAAG;CAC1B;CACA,OAAO;AACX;AAEA,IAAI;;AAGJ,SAAgB,aAAqB;CACjC,IAAI,WAAW,KAAA,GAAW,SAAS,YAAY;CAC/C,OAAO;AACX;;;;;;;;AASA,SAAgB,eAAuB;CACnC,OAAO,cAAc,WAAW;AACpC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/cli",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Developer tools for Rebase projects",
   "keywords": [
     "cli",
@@ -43,12 +43,12 @@
     "inquirer": "14.0.2",
     "jiti": "^2.7.0",
     "pg": "^8.22.0",
-    "@rebasepro/agent-skills": "0.22.0",
-    "@rebasepro/codegen": "0.22.0",
-    "@rebasepro/server-postgres": "0.22.0",
-    "@rebasepro/types": "0.22.0",
-    "@rebasepro/server": "0.22.0",
-    "@rebasepro/client": "0.22.0"
+    "@rebasepro/agent-skills": "0.24.0",
+    "@rebasepro/codegen": "0.24.0",
+    "@rebasepro/server": "0.24.0",
+    "@rebasepro/types": "0.24.0",
+    "@rebasepro/server-postgres": "0.24.0",
+    "@rebasepro/client": "0.24.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -56,7 +56,7 @@
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vite": "^8.1.5",
-    "vitest": "4.1.10",
+    "vitest": "4.1.11",
     "ws": "^8.21.1"
   },
   "files": [

package/templates/eject/backend/src/index.ts

@@ -81,7 +81,20 @@ app.use("/*", cors({
         if (!origin) return "*";
         return isLocalhostOrigin(origin) ? origin : null;
     },
-    credentials: true
+    credentials: true,
+    // A frontend on another origin reads only the response headers named here.
+    // Without `ETag` the SDK's `etagOf(row)` is always undefined there, and an
+    // `ifMatch` write silently goes out unconditional; without `Retry-After`
+    // and `X-Request-ID` a 429 or an error loses what it reports.
+    exposeHeaders: [
+        "ETag",
+        "Retry-After",
+        "X-Request-ID",
+        "X-RateLimit-Limit",
+        "X-RateLimit-Remaining",
+        "X-RateLimit-Reset",
+        "Preference-Applied"
+    ]
 }));
 
 app.use("/*", secureHeaders());

package/templates/overlays/baas/ai-instructions.md

@@ -12,7 +12,7 @@ This is a **headless** Rebase project: a REST API, auth, storage and realtime ov
 | `rebase db url` | Print the connection string in use — it pipes straight into `psql` |
 | `pnpm db:migrate` | Apply the migration files in `backend/drizzle/migrations`. Needs your own PostgreSQL, not the managed development database |
 | `pnpm schema:introspect` | Existing tables → collection definitions in `config/collections/`. That directory ends headless mode; see rule 1 |
-| `pnpm generate:sdk` | Regenerate the typed client from `config/collections/` — so in a headless project it has nothing to read until you introspect |
+| `pnpm generate:sdk` | Regenerate the typed client from `config/collections/` — so in a headless project it has nothing to read until you introspect. Once there are collections, `pnpm dev` does this on start and on every save; the script is for CI and for when `pnpm dev` is not running |
 | `pnpm build` then `pnpm start` | Build the deployable bundle, then run it |
 | `pnpm skills:install` | Install the Rebase skills for your assistant |
 | `pnpm example` | Run `scripts/example.ts` against the running backend — the SDK, end to end |

package/templates/overlays/baas/config/storage.ts

@@ -1,4 +1,4 @@
-import { isPublicStoragePath, type StorageAuthorize } from "@rebasepro/types";
+import type { StorageAuthorize } from "@rebasepro/types";
 
 /**
  * Who may do what to files in storage.
@@ -39,7 +39,7 @@ import { isPublicStoragePath, type StorageAuthorize } from "@rebasepro/types";
  *
  * ```ts
  * export const storageAuthorize: StorageAuthorize = async ({ key, user, operation, data }) => {
- *     if (operation === "read" && isPublicStoragePath(key)) return true;
+ *     if (operation === "read" && key.startsWith("public/")) return true;
  *     if (!user) return false;
  *     const row = (await data?.collection("attachments").find({
  *         where: { storage_key: ["==", key] }, limit: 1
@@ -55,7 +55,9 @@ import { isPublicStoragePath, type StorageAuthorize } from "@rebasepro/types";
  */
 export const storageAuthorize: StorageAuthorize = ({ key, user, operation }) => {
     // The `public/` prefix is the framework's convention for world-readable objects.
-    if (operation === "read" && isPublicStoragePath(key)) {
+    // `key` is the canonical key the server serves, so a prefix test is exact:
+    // `default/public/x` is a private object in a folder named `default`.
+    if (operation === "read" && key.startsWith("public/")) {
         return true;
     }
 

package/templates/template/.cursorrules

@@ -1,3 +1,3 @@
 # Rebase AI Rules
 Please refer to and follow the instructions defined in [ai-instructions.md](./ai-instructions.md).
-Install the Rebase skills for this assistant: `rebase skills install --agent cursor`.
+The Rebase skills for this assistant live in `.cursor/rules/`. If they are not there yet, install them, with the Rebase MCP server: `rebase skills install --agent cursor --mcp`.

package/templates/template/.env.example

@@ -51,10 +51,12 @@ DATABASE_URL=postgresql://rebase_app:changeme@localhost:5432/rebase?options=-c%2
 # DB_POOL_CONNECT_TIMEOUT=10000
 
 # ── Server ────────────────────────────────────────────────────────────────────
-# Used by `rebase start` (production). `rebase dev` IGNORES this and binds a
+# Used by `rebase start`. `rebase dev` IGNORES this and binds a
 # port derived from the project path, so several projects can run at once —
 # trust the URL `rebase dev` prints, or pin one with `rebase dev --port 3001`.
 PORT=3001
+# `rebase start` runs in this mode too, and warns that it is not a production
+# server: set NODE_ENV=production (here or in the shell) for one.
 NODE_ENV=development
 # Allow connecting to localhost / 127.0.0.1 in production mode (for local testing of prod builds)
 # ALLOW_LOCALHOST_IN_PRODUCTION=false
@@ -222,7 +224,7 @@ VITE_API_URL=
 # BACKUP_DESTINATION=./backups        # local path, or s3://bucket/prefix / gs://bucket/prefix
 # BACKUP_RETENTION_DAYS=14            # delete backups older than N days (unset/0 ⇒ keep all)
 # BACKUP_KEEP_MINIMUM=3               # always retain at least N most-recent backups
-# PG_DUMP_PATH=                       # override pg_dump binary (must match server major version)
+# PG_DUMP_PATH=                       # override pg_dump binary (server's major version or newer)
 # PG_RESTORE_PATH=                    # override pg_restore binary
 
 # ── Admin Service Key (optional) ──────────────────────────────────────────────
@@ -250,9 +252,11 @@ VITE_API_URL=
 # unset. To upgrade, change this and restart — your bundle is untouched.
 REBASE_VERSION=latest
 
-# What boot does about versioned migrations in `backend/migrations`.
-#   ensure   create missing tables and columns from your collections (the default)
-#   migrate  run the migration files, then ensure
-#   off      neither
+# Whether boot provisions the schema your collections describe.
+#   ensure   create missing tables, columns and enum types, additively (the default)
+#   none     leave the schema alone
+# Any other value refuses to boot. Boot never runs migration files: the ones
+# `rebase db generate` writes to `backend/drizzle/migrations` are applied with
+# `rebase db migrate`.
 # REBASE_MIGRATE_ON_BOOT=ensure
 

package/templates/template/.github/copilot-instructions.md

@@ -1,3 +1,3 @@
 # Rebase AI Rules
 Please refer to and follow the instructions defined in [ai-instructions.md](../ai-instructions.md).
-Install the Rebase skills for this assistant: `rebase skills install --agent copilot`.
+The Rebase skills for this assistant live in `.github/instructions/`. If they are not there yet, install them, with the Rebase MCP server: `rebase skills install --agent copilot --mcp`.

package/templates/template/.mcp.json

@@ -1,8 +1,8 @@
 {
     "mcpServers": {
         "rebase": {
-            "command": "npx",
-            "args": ["-y", "@rebasepro/mcp"],
+            "command": "pnpm",
+            "args": ["exec", "rebase-mcp"],
             "env": {
                 "REBASE_PROJECT_DIR": "."
             }

package/templates/template/.windsurfrules

@@ -1,3 +1,3 @@
 # Rebase AI Rules
 Please refer to and follow the instructions defined in [ai-instructions.md](./ai-instructions.md).
-Install the Rebase skills for this assistant: `rebase skills install --agent windsurf`.
+The Rebase skills for this assistant live in `.windsurf/rules/`. If they are not there yet, install them, with the Rebase MCP server: `rebase skills install --agent windsurf --mcp`.

package/templates/template/AGENTS.md

@@ -1,3 +1,3 @@
 # Rebase AI Rules
 Please refer to and follow the instructions defined in [ai-instructions.md](ai-instructions.md).
-Install the Rebase skills for this assistant: `rebase skills install --agent codex`.
+The Rebase skills for this assistant live in `.agents/skills/`. If they are not there yet, install them, with the Rebase MCP server: `rebase skills install --agent codex --mcp`.

package/templates/template/CLAUDE.md

@@ -1,3 +1,3 @@
 # Rebase AI Rules
 Please refer to and follow the instructions defined in [ai-instructions.md](./ai-instructions.md).
-Install the Rebase skills for this assistant: `rebase skills install --agent claude`.
+The Rebase skills for this assistant live in `.claude/skills/`. If they are not there yet, install them, with the Rebase MCP server: `rebase skills install --agent claude --mcp`.

package/templates/template/README.md

@@ -33,9 +33,9 @@ pnpm install   # or: npm install
 pnpm dev   # or: npm run dev
 ```
 
-That is the whole first run. `rebase dev` generates the Drizzle schema from
-`config/collections`, starts the database, creates a table for every collection
-declared there, and serves the API and the admin panel.
+That is the whole first run. `rebase dev` generates the Drizzle schema and the
+SDK types from `config/collections`, starts the database, creates a table for
+every collection declared there, and serves the API and the admin panel.
 
 `rebase dev` prints the two URLs it actually bound. The first account you
 register becomes the admin. `REBASE_ADMIN_EMAIL` and `REBASE_ADMIN_PASSWORD` in
@@ -45,8 +45,8 @@ is shut — see [Self-hosting](#self-hosting-with-docker).
 Ports are **derived from this project's path**, not fixed at 3001/5173, so
 several Rebase projects can run at once without colliding. That is why the URL
 in your terminal is the one to trust — and why the `PORT` and `VITE_API_URL` in
-`.env` are ignored by `rebase dev` (they apply to `rebase start`, the production
-server). Pin a port with `rebase dev --port 3001` if you need a stable one.
+`.env` are ignored by `rebase dev` (they apply to `rebase start`, which runs the
+built bundle). Pin a port with `rebase dev --port 3001` if you need a stable one.
 
 ### Variant: your own PostgreSQL
 
@@ -61,10 +61,9 @@ database to compare against, and PGlite serves exactly one:
 pnpm run db:push
 ```
 
-Boot already creates missing tables and columns additively, so `db push` is for
-what it deliberately leaves alone: junction-table RLS on many-to-many relations,
-and any change that is not purely additive — a renamed column, a narrowed type,
-a removed field.
+Boot already creates missing tables and columns, and their row-level security,
+additively, so `db push` is for what it deliberately leaves alone: any change
+that is not purely additive — a renamed column, a narrowed type, a removed field.
 
 The `docker-compose.yml` in this project runs PostgreSQL in a container if you
 would rather not install one:
@@ -163,8 +162,8 @@ compose database is a database of your own, so step 0 is the same one line.
 pnpm run build          # or: npm run build
 
 # 2. Start the database. Boot creates the tables from your collections;
-#    `db:push` is for what it leaves alone — junction-table RLS, and any
-#    change that is not purely additive.
+#    `db:push` is for what it leaves alone — any change that is not purely
+#    additive.
 docker compose up -d db
 pnpm run db:push        # or: npm run db:push
 

package/templates/template/ai-instructions.md

@@ -10,7 +10,7 @@
 | `pnpm schema:generate` then `pnpm db:push` | The same loop with `pnpm dev` not running, plus the changes boot leaves alone: collections → Drizzle schema → development database |
 | `pnpm db:generate` then `pnpm db:migrate` | The production path — write the migration file, then apply it |
 | `pnpm schema:introspect` | The other direction: existing tables → collection definitions |
-| `pnpm generate:sdk` | Regenerate the typed client from the collections |
+| `pnpm generate:sdk` | Regenerate the typed client in `generated/sdk/` from the collections. `pnpm dev` already does this on start and on every save; the script is for CI and for when `pnpm dev` is not running |
 | `pnpm build` then `pnpm start` | Build the deployable bundle, then run it |
 | `pnpm skills:install` | Install the Rebase skills for your assistant |
 | `pnpm example` | Run `scripts/example.ts` against the running backend — the SDK, end to end |
@@ -29,8 +29,8 @@
 
 ## Core rules
 
-1. **Schema-as-code**: define and edit collections in `config/collections/` with `defineCollection` from `@rebasepro/cms-types`, and register each one in that directory's `index.ts` — a collection missing from the barrel does not exist. Never hand-edit generated schemas or Postgres tables.
-2. **Applying a collection change**: while `pnpm dev` is running, saving a file in `config/collections/` is the whole step — it regenerates `backend/src/schema.generated.ts`, restarts the backend, and boot creates the tables and columns that are missing. With `pnpm dev` stopped, that is `pnpm schema:generate`. `pnpm db:push` is only for what boot deliberately leaves alone — a renamed column, a narrowed type, a removed field, junction-table RLS — and it needs your own PostgreSQL, not the managed development database. In production the pair is `pnpm db:generate` then `pnpm db:migrate`.
+1. **Schema-as-code**: define and edit collections in `config/collections/` with `defineCollection` from `@rebasepro/cms-types`, one collection per file, default-exported. Every file in that directory is loaded — by the backend, the admin panel and the SDK generator — whether or not `index.ts` lists it: the barrel is a sort order for the admin navigation (and holds `defaultSecurityRules`), not a registry. To remove a collection, delete its file. Never hand-edit generated schemas or Postgres tables.
+2. **Applying a collection change**: while `pnpm dev` is running, saving a file in `config/collections/` is the whole step — it regenerates `backend/src/schema.generated.ts` and the SDK types in `generated/sdk/`, restarts the backend, and boot creates the tables and columns that are missing. With `pnpm dev` stopped, that is `pnpm schema:generate` and `pnpm generate:sdk`. `pnpm db:push` is only for what boot deliberately leaves alone — a renamed column, a narrowed type, a removed field — and it needs your own PostgreSQL, not the managed development database. In production the pair is `pnpm db:generate` then `pnpm db:migrate`.
 3. **Use the SDK**: server-side that is `rebase.dataAsAdmin.<slug>` for work done as the service identity, or `getDriver(c)` inside a function when the read should run as the caller. The server client has no plain `data` accessor — it is omitted precisely so that the choice of identity is written down.
 4. **Guard every custom route**: routes in `backend/functions/` are mounted **without** an auth requirement — webhook receivers need that — so each one is public until you guard it. Import `requireAuth` / `requireAdmin` from `@rebasepro/server/functions` and pass them in the route's own middleware slot (`app.post("/", requireAuth, handler)`), not via `app.use()`, which only covers routes declared below it. Reading `getUser(c)` is not a guard: an anonymous caller gets `undefined` and the handler still runs. See `backend/functions/hello.ts` for all three tiers.
 5. **In `backend/functions/`, always import from `@rebasepro/server/functions`** — never from `@rebasepro/server`. Both work today; the subpath is the portable one, and it also gives you the typed context accessors (`getUser`, `getDriver`, `requireDriver`) instead of casting `c.get("user")`. The package root is for a server entrypoint, not for route handlers.

package/templates/template/backend/functions/hello.ts

@@ -47,6 +47,14 @@ import {
  * slot over `app.use("/*", requireAuth)`: `use()` only covers routes declared
  * *below* it, so a route appended later above it is silently unprotected.
  *
+ * An API key is a caller too. It reaches this file only if it holds the
+ * `functions:invoke` scope (or `functions:invoke:hello`), it passes
+ * `requireAuth`, and a service key created with `--roles admin` passes
+ * `requireAdmin`. To let a key do one thing here and not another, declare a
+ * scope under `auth.scopes` on the users collection and add
+ * `requireScope("reports:read")` to that route — every signed-in person holds
+ * every app scope, so it narrows keys, not people.
+ *
  * `rebase.dataAsAdmin` gives you admin-level access to your data: it runs as
  * `{ uid: "service", roles: ["admin"] }`, which is **admin-scoped, not an RLS
  * bypass** — your policies are still evaluated, just against that identity. So

package/templates/template/backend/package.json

@@ -4,7 +4,7 @@
     "description": "Rebase backend with PostgreSQL",
     "type": "module",
     "scripts": {
-        "build": "rebase schema generate --collections ../config/collections && tsc && rebase normalize-imports dist"
+        "build": "rebase schema generate && tsc && rebase normalize-imports dist"
     },
     "dependencies": {
         "@ariga/atlas": "^1.2.3",

package/templates/template/config/storage.ts

@@ -1,4 +1,4 @@
-import { isPublicStoragePath, type StorageAuthorize } from "@rebasepro/types";
+import type { StorageAuthorize } from "@rebasepro/types";
 
 /**
  * Who may do what to files in storage.
@@ -37,7 +37,7 @@ import { isPublicStoragePath, type StorageAuthorize } from "@rebasepro/types";
  *
  * ```ts
  * export const storageAuthorize: StorageAuthorize = async ({ key, user, operation, data }) => {
- *     if (operation === "read" && isPublicStoragePath(key)) return true;
+ *     if (operation === "read" && key.startsWith("public/")) return true;
  *     if (!user) return false;
  *
  *     // Writes land under the caller's own prefix.
@@ -66,7 +66,9 @@ import { isPublicStoragePath, type StorageAuthorize } from "@rebasepro/types";
 export const storageAuthorize: StorageAuthorize = ({ key, user, operation }) => {
     // The `public/` prefix is the framework's convention for world-readable
     // objects, and it is what signed download URLs for public assets rely on.
-    if (operation === "read" && isPublicStoragePath(key)) {
+    // `key` is the canonical key the server serves, so a prefix test is exact:
+    // `default/public/x` is a private object in a folder named `default`.
+    if (operation === "read" && key.startsWith("public/")) {
         return true;
     }
 

package/templates/template/docker-compose.yml

@@ -15,7 +15,7 @@
 #   docker compose up         # boot creates the tables it is missing
 #
 # `rebase db push` is the separate step for what boot deliberately leaves
-# alone: junction-table RLS, and any change that is not purely additive.
+# alone: any change that is not purely additive.
 #
 # One container then serves the API at /api and the admin at / — same origin, so
 # there is no CORS to configure between them and no second web server.
@@ -132,12 +132,12 @@ services:
       DISABLE_SELF_REGISTRATION: ${DISABLE_SELF_REGISTRATION:-true}
 
       # `ensure` (the default) creates missing tables and columns at boot —
-      # your collections' as well as auth's — and is additive only: nothing is
-      # dropped, narrowed or rewritten, because that must never happen as a
-      # side effect of a container restart.
+      # your collections' as well as auth's — with their row-level security,
+      # and is additive only: nothing is dropped, narrowed or rewritten,
+      # because that must never happen as a side effect of a container restart.
       #
-      # `rebase db push` is still what applies the rest: junction-table RLS on
-      # many-to-many relations, and any change that is not purely additive.
+      # `rebase db push` is still what applies the rest: any change that is not
+      # purely additive.
       # Set this to `none` to take a deployment out of provisioning entirely.
       REBASE_MIGRATE_ON_BOOT: ${REBASE_MIGRATE_ON_BOOT:-ensure}
 

package/templates/template/gitignore

@@ -11,8 +11,13 @@ build/
 !.env.example
 
 # IDE
+#
+# `.vscode/*` rather than `.vscode/`: git cannot re-include a file inside an
+# ignored directory, and `.vscode/mcp.json` is the Rebase MCP server
+# `rebase init --agent copilot` registers for the whole team.
 .idea/
-.vscode/
+.vscode/*
+!.vscode/mcp.json
 *.swp
 *.swo
 

package/templates/template/package.json

@@ -13,11 +13,11 @@
         "dev": "rebase dev",
         "build": "rebase build",
         "start": "rebase start",
-        "db:generate": "rebase db generate --collections ../config/collections",
+        "db:generate": "rebase db generate",
         "db:migrate": "rebase db migrate",
         "schema:introspect": "rebase schema introspect",
-        "db:push": "rebase db push --collections ../config/collections",
-        "schema:generate": "rebase schema generate --collections ../config/collections",
+        "db:push": "rebase db push",
+        "schema:generate": "rebase schema generate",
         "generate:sdk": "rebase generate-sdk",
         "skills:install": "rebase skills install",
         "example": "tsx scripts/example.ts",
@@ -25,6 +25,7 @@
     },
     "devDependencies": {
         "@rebasepro/cli": "workspace:*",
+        "@rebasepro/mcp": "workspace:*",
         "@rebasepro/types": "workspace:*",
         "tsx": "^4.20.6",
         "typescript": "^6.0.3"

package/templates/template/scripts/example.ts

@@ -23,9 +23,10 @@ import fs from "node:fs";
 import path from "node:path";
 import * as dotenv from "dotenv";
 import { createRebaseClient } from "@rebasepro/client";
-// Optional: fully typed collections. `rebase generate-sdk` writes these under
-// ./generated/sdk — the dictionary is what maps a hyphenated slug to the
-// property name, so a client built without it 404s at runtime.
+// Optional: fully typed collections. `rebase dev` writes these under
+// ./generated/sdk (`rebase generate-sdk` outside it) — the dictionary is what
+// maps a hyphenated slug to the property name, so a client built without it
+// 404s at runtime.
 // import { collectionsDictionary, type Database } from "../generated/sdk/database.types";
 
 // Load .env from project root (same file the backend uses)