@rebasepro/cli 0.16.0 → 0.16.1-canary.g0d7af95

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

@@ -15,11 +15,14 @@ import {
     HonoEnv,
     listenWithPortRetry,
     cleanupDevPortFile,
-    loadDeclaredStorageSources,
     resolveStorageSources,
     logger
 } from "@rebasepro/server";
 import { createPostgresDatabaseConnection, createPostgresAdapter } from "@rebasepro/server-postgres";
+import { declaredStorageSources } from "@rebasepro/types";
+// Side-effect import: declaring is what registers, so anything that dropped
+// this as "unused" would leave the backend with no buckets — silently.
+import "../../config/resources.js";
 // {{#collections}}
 import { enums, relations, tables } from "./schema.generated.js";
 // {{/collections}}
@@ -32,12 +35,11 @@ import usersCollection from "../../config/collections/users.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-// Which buckets this project has, read from the `storage` block of its own
-// `rebase.json`. Declared there rather than here so the platform, the console
-// and this process all read one list — a custom image ships the repository, so
-// the file it already contains is the natural place for it. Absent means one
-// default source, configured from the plain S3_*/GCS_* variables.
-const storageSources = loadDeclaredStorageSources(__dirname);
+// Which buckets this project has, read from the declarations in
+// `config/resources.ts`. One declaration site, so this process, the platform
+// and the frontend all read the same list. A project that declares none gets
+// one default source from the plain, unsuffixed S3_*/GCS_* variables.
+const storageSources = declaredStorageSources();
 
 // ─── App ─────────────────────────────────────────────────────────────
 const app: Hono<HonoEnv> = new Hono<HonoEnv>();
@@ -181,7 +183,6 @@ pass: env.SMTP_PASS! }
             storageSources,
             path.resolve(__dirname, "../../uploads")
         ),
-        storageSources,
         // Storage is not under row-level security, so this hook IS its access
         // model — the server refuses to boot in production without one, because
         // "signed in" would otherwise be the only thing between a visitor and
@@ -201,6 +202,12 @@ pass: env.SMTP_PASS! }
     //   import { requireAuth, requireAdmin } from "@rebasepro/server";
     //   app.get("/admin/report", requireAuth, requireAdmin, handler);
     //
+    // From the package root here, deliberately — **not** from
+    // `@rebasepro/server/functions`. The guards on that subpath read an
+    // identity that a Rebase router has already resolved, which is the right
+    // thing inside `backend/functions/` and useless out here, where no such
+    // middleware ran. These verify the token themselves.
+    //
     // `requireAuth` answers 401 without a valid token; `requireAdmin` answers
     // 403 without the `admin` role and must follow `requireAuth`. Note that
     // `c.get("driver")` — the driver carrying the caller's identity — is only

package/templates/eject/config/resources.ts

@@ -0,0 +1,24 @@
+/**
+ * What this project needs from wherever it runs.
+ *
+ * One declaration per resource, and this is the only place they are declared.
+ * The backend reads them, `rebase resources --write` records them in
+ * `rebase.resources.json` for a host to read before it runs anything, and the
+ * frontend can be handed the same list with `declaredStorageSources()`.
+ *
+ * A database is implicit: a backend has one whether or not this file says so,
+ * bound from DATABASE_URL. Name a second one to get a second.
+ */
+import { bucket, database } from "@rebasepro/types";
+
+/** The project's database. Bound from DATABASE_URL. */
+export const main = database();
+
+/**
+ * The default bucket, bound from the plain unsuffixed storage variables
+ * (`S3_BUCKET`, `GCS_BUCKET`, `STORAGE_BUCKET`).
+ *
+ * Name more of them to get more — `bucket("media")` reads `S3_BUCKET__MEDIA`,
+ * and so on for every variable that kind uses.
+ */
+export const files = bucket();

package/templates/template/AGENTS.md

@@ -1,2 +1,2 @@
 # Rebase AI Rules
-Please refer to and follow the instructions defined in [ai-instructions.md](./ai-instructions.md).
+Please refer to and follow the instructions defined in [ai-instructions.md](ai-instructions.md).

package/templates/template/CLAUDE.md

@@ -1,2 +1,2 @@
 # Rebase AI Rules
-Please refer to and follow the instructions defined in [ai-instructions.md](./ai-instructions.md).
+Please refer to and follow the instructions defined in [ai-instructions.md](ai-instructions.md).

package/templates/template/README.md

@@ -87,7 +87,7 @@ Drop a Hono app in `backend/functions/` and it's auto-mounted at `/api/functions
 
 ```typescript
 // backend/functions/hello.ts
-import { defineFunction, requireAuth, requireAdmin } from "@rebasepro/server";
+import { defineFunction, requireAuth, requireAdmin } from "@rebasepro/server/functions";
 
 export default defineFunction((app) => {
     // Deliberately public — anyone can call this.

package/templates/template/ai-instructions.md

@@ -15,5 +15,8 @@ rebase skills install
    - Step 1: Run `rebase schema generate` to compile collections to the Drizzle schema.
    - Step 2: Run `rebase db push` (development) or `rebase db generate && rebase db migrate` (production) to apply schema changes to the database.
 3. **Use the SDK**: Always use the Rebase SDK (`rebase.data.<slug>`) to fetch or modify data. Bypassing it with raw SQL or direct Drizzle/PG queries circumvents model validations, lifecycle hooks, and Row-Level Security (RLS).
-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` 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 `c.get("user")` is not a guard: an anonymous caller gets `undefined` and the handler still runs. See `backend/functions/hello.ts` for all three tiers.
-5. **Build UI from the kit, never from scratch**: any custom view, home page, dashboard or entity tab must be composed from `@rebasepro/ui` components (`Card`, `Typography`, `Button`, `Chip`, `Alert`, …) and the theme's colour tokens (`text-surface-*`, `bg-surface-accent-*`, `text-primary`), with a `dark:` value beside every light one. Do **not** invent a palette, a type scale, or hand-written CSS: a hardcoded colour like `#111` is invisible in one of the two themes and nothing will catch it. The live reference ships in your `node_modules` — read `@rebasepro/app/src/components/Debug/UIReferenceView.tsx` before building a view, and see [Styling Custom UI](https://rebase.pro/docs/frontend/styling). The `rebase-design-language` and `rebase-ui-components` skills cover this in full; install them with `rebase skills install`.
+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.
+6. **Never read `process.env` at the top of a function file.** A module-scope read that comes back undefined throws at import time, and the loader reports that as a *skipped function* — the route simply 404s with no error attached to it. Read configuration inside the handler with `requireEnv(c, "NAME")`, or build a client once with `lazyResource(env => new Client(env.KEY))`.
+7. **Work that outlives the response goes in `waitUntil(c, promise)`**, not a floating promise. A floating promise is dropped when the process shuts down mid-deploy; `waitUntil` is what a graceful shutdown waits for.
+8. **Build UI from the kit, never from scratch**: any custom view, home page, dashboard or entity tab must be composed from `@rebasepro/ui` components (`Card`, `Typography`, `Button`, `Chip`, `Alert`, …) and the theme's colour tokens (`text-surface-*`, `bg-surface-accent-*`, `text-primary`), with a `dark:` value beside every light one. Do **not** invent a palette, a type scale, or hand-written CSS: a hardcoded colour like `#111` is invisible in one of the two themes and nothing will catch it. The live reference ships in your `node_modules` — read `@rebasepro/app/src/components/Debug/UIReferenceView.tsx` before building a view, and see [Styling Custom UI](https://rebase.pro/docs/frontend/styling). The `rebase-design-language` and `rebase-ui-components` skills cover this in full; install them with `rebase skills install`.

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

@@ -1,4 +1,10 @@
-import { defineFunction, requireAuth, requireAdmin } from "@rebasepro/server";
+import {
+    defineFunction,
+    requireAuth,
+    requireAdmin,
+    getUser,
+    getUserId
+} from "@rebasepro/server/functions";
 
 /**
  * Example custom function route.
@@ -11,17 +17,24 @@ import { defineFunction, requireAuth, requireAdmin } from "@rebasepro/server";
  * Call from the client SDK:
  *   const result = await client.call("functions/hello", { name: "World" });
  *
- * Authored with `defineFunction`, which hands you a pre-typed Hono app
- * (so `c.get("user")` / `c.get("driver")` are typed) and the `rebase`
- * singleton via the injected context — use any Hono middleware, define any
- * HTTP methods, access the request/response directly.
+ * Authored with `defineFunction`, which hands you a pre-typed Hono app (so
+ * `c.get("user")` / `c.get("driver")` are typed) and the `rebase` singleton via
+ * the injected context — use any Hono middleware, define any HTTP methods,
+ * access the request/response directly.
+ *
+ * **Import from `@rebasepro/server/functions`, not `@rebasepro/server`.** Same
+ * code, but that entry point is the portable one: it pulls in nothing that
+ * needs Node, so a function written against it can run on any JavaScript
+ * runtime. The package root reaches the whole framework — the boot sequence,
+ * the file loaders, the WebSocket layer — which is correct for a server
+ * entrypoint and is not what a route handler needs.
  *
  * **Custom functions are not authenticated for you.** The functions router
  * parses the caller's token and puts the result in the context, but it does
  * not reject anonymous requests — a webhook receiver (Stripe, GitHub) has no
  * token to send, and that has to keep working. So every route in this folder
- * is public until you say otherwise, and reading `c.get("user")` is not a
- * check: an anonymous caller just gets `undefined` and the handler runs anyway.
+ * is public until you say otherwise, and reading `getUser(c)` is not a check:
+ * an anonymous caller just gets `undefined` and the handler runs anyway.
  *
  * Say otherwise with `requireAuth` / `requireAdmin`, in the route's own
  * middleware slot as below. `requireAuth` answers 401 without a valid token.
@@ -35,19 +48,25 @@ import { defineFunction, requireAuth, requireAdmin } from "@rebasepro/server";
  * bypass** — your policies are still evaluated, just against that identity. So
  * `policy.serverContext()` is false for it (that arm means "no uid at all"),
  * and anything an `admin` user can reach, it can reach too. For request-scoped
- * data access use c.get("user") and c.get("driver"), which carry the caller's
- * identity. `rebase.sql()` is the real bypass — owner connection, no policies.
- * (`rebase` also exposes auth, storage, email.)
+ * data access use `getUser(c)` and `getDriver(c)`, which carry the caller's
+ * identity. `rebase.sql()` is the real bypass — owner connection, no policies,
+ * and the one accessor that is Node-only. (`rebase` also exposes auth, storage,
+ * email.)
+ *
+ * Two habits worth keeping from the start, because both are free here and
+ * expensive to retrofit later:
+ *
+ *   - Read configuration **inside** a handler — `requireEnv(c, "STRIPE_KEY")`
+ *     or `lazyResource(...)` — never `process.env.X` at the top of the file. A
+ *     module-scope read that comes back undefined takes the whole file down at
+ *     import time, and the loader reports that only as "skipped".
+ *   - Wrap work that outlives the response in `waitUntil(c, promise)` rather
+ *     than leaving a floating promise. It is what lets a graceful shutdown wait
+ *     for your webhook instead of dropping it.
  */
 export default defineFunction((app, { rebase }) => {
     void rebase; // available for dataAsAdmin/auth/storage/email — see commented usage below
 
-    /** The caller's id, or undefined when nobody is signed in. */
-    const uidOf = (user: unknown): string | undefined =>
-        (typeof user === "object" && user !== null && "uid" in user)
-            ? (user as { uid?: string }).uid
-            : undefined;
-
     // ── Public ────────────────────────────────────────────────────────────
     // Deliberately public: no guard, so anyone can call it. That is a fine
     // choice for health probes, webhook receivers and public content — the
@@ -68,17 +87,17 @@ export default defineFunction((app, { rebase }) => {
         // await rebase.email.send({
         //     to: "admin@example.com",
         //     subject: "Function called",
-        //     html: `<p>Hello from ${uidOf(c.get("user"))}!</p>`,
+        //     html: `<p>Hello from ${getUserId(c)}!</p>`,
         // });
         //
-        // Admin-scoped data (bypasses RLS — trusted work only):
+        // Admin-scoped data (RLS evaluated as the `admin` role — trusted work
+        // only):
         // const authors = await rebase.dataAsAdmin.authors.find({ limit: 5 });
-        // For user-scoped data (RLS applies), use the request-scoped driver
-        // (c.get("driver")), which carries the caller's identity.
+        // For user-scoped data (RLS applies as the caller), use getDriver(c).
 
         return c.json({
             message: `Hello, ${body.name || "World"}!`,
-            user: uidOf(c.get("user"))
+            user: getUserId(c)
         });
     });
 
@@ -86,6 +105,8 @@ export default defineFunction((app, { rebase }) => {
     // Order matters: `requireAuth` first (401 for anonymous), then
     // `requireAdmin` (403 for a signed-in non-admin).
     app.get("/stats", requireAuth, requireAdmin, (c) => {
-        return c.json({ admin: uidOf(c.get("user")) });
+        // `getUser` returns a narrowed `{ uid, roles, ...claims }` — no cast,
+        // and `roles` is always an array.
+        return c.json({ admin: getUser(c)?.uid });
     });
 });

package/templates/template/config/resources.ts

@@ -0,0 +1,57 @@
+/**
+ * What this project needs from wherever it runs.
+ *
+ * A resource is declared here once — that a database exists, that a bucket
+ * exists, what engine backs it — and bound somewhere else: to a real connection
+ * string and a real bucket name, per environment, from the environment. The
+ * split is the point. Your staging and your production run the same commit and
+ * must not share a bucket, so *which* bucket can never live in a committed file;
+ * *that* there is one is a property of your code and belongs beside it.
+ *
+ * The runtime reads this file at boot and reports, for every declaration,
+ * whether it is bound. Nothing here is silent.
+ */
+import { bucket, database } from "@rebasepro/types";
+
+/**
+ * The project's database, bound from `DATABASE_URL`.
+ *
+ * Implicit — a backend has one whether or not this line is here. It is written
+ * out so that the second one has somewhere obvious to go.
+ */
+export const main = database();
+
+/**
+ * A second database, if you ever want one.
+ *
+ * Bound from `DATABASE_URL__ANALYTICS`: the key, uppercased, after a double
+ * underscore. Every resource follows that rule, and the default-keyed one reads
+ * the plain unsuffixed variable.
+ *
+ * export const analytics = database("analytics");
+ */
+
+/**
+ * Object storage.
+ *
+ * Uncomment to give this project a bucket. The default-keyed one binds from the
+ * plain `S3_BUCKET` / `GCS_BUCKET` / `STORAGE_BUCKET`; a named one appends its
+ * key, so `bucket("media")` reads `S3_BUCKET__MEDIA`.
+ *
+ * export const files = bucket({ engine: "s3" });
+ * export const media = bucket("media", { engine: "s3" });
+ *
+ * ## When you have several on one provider
+ *
+ * Name an `account` and they share one credential set instead of repeating it:
+ *
+ * export const media   = bucket("media",   { engine: "s3", account: "minio" });
+ * export const avatars = bucket("avatars", { engine: "s3", account: "minio" });
+ *
+ * That reads `S3_BUCKET__MEDIA` and `S3_BUCKET__AVATARS` — each bucket keeps its
+ * own name — while `S3_ACCESS_KEY_ID__MINIO`, `S3_SECRET_ACCESS_KEY__MINIO` and
+ * `S3_ENDPOINT__MINIO` are read once for both. Rotating that key is then one
+ * edit rather than one per bucket. A per-bucket value still wins where you set
+ * one, so a single source can be moved to another provider without breaking the
+ * rest off their shared account.
+ */

package/templates/template/docker-compose.yml

@@ -30,7 +30,16 @@ name: {{PROJECT_NAME}}
 services:
   # ── PostgreSQL ───────────────────────────────────────────────────────
   db:
-    image: postgres:18-alpine
+    # pgvector's image rather than the plain `postgres:18-alpine`: it is the
+    # official Postgres image with the `vector` extension already built in, on
+    # the same major. A `{ type: "vector" }` property compiles to `VECTOR(n)`,
+    # which a stock Postgres answers with `type "vector" does not exist` — a
+    # boot failure whose cause is an image, not a config. Nothing here installs
+    # extensions on your behalf, so the image is where that decision lives.
+    #
+    # Swapping this for `postgres:18-alpine` is safe on the same major if you
+    # never declare a vector property.
+    image: pgvector/pgvector:pg18
     restart: unless-stopped
     environment:
       POSTGRES_USER: rebase_app

package/templates/template/gitignore

@@ -29,6 +29,7 @@ uploads/
 # Rebase dev
 .rebase-dev-url
 .rebase-dev-port
+.rebase-dev-secrets.json
 
 # Built project bundle (`rebase build`)
 dist-bundle/