bunderstack 0.21.1 → 0.22.1

package/skills/creating-bunderstack-apps/references/application-structure.md

@@ -1,23 +1,27 @@
 # Application structure
 
-## Keep the entry declarative
+## Separate declaration from runtime
 
-The Bunderstack entry constructs and exports `app` (and usually `type App =
-typeof app`), configures the declared capabilities, and calls `provision(app)`
-when the application owns provisioning. Keep unrelated external side effects
-out of its import graph: the blueprint command imports this entry with
-`BUNDERSTACK_INTROSPECT=1`.
+`src/bunderstack/backend.ts` synchronously constructs and exports `backend =
+bunderstack({...})`. It is pure: it validates the declaration and exposes
+`backend.manifest`, but it does not connect to infrastructure. The blueprint
+imports this declaration without starting the application.
+
+`src/bunderstack/index.ts` owns the production runtime: it imports `backend`,
+calls `await backend.start()`, exports `app`, and calls `provision(app)` when the
+application owns provisioning. Keep unrelated external side effects out of the
+backend import graph.
 
 Start a small API in `src/bunderstack.ts`. Split a meaningful configuration
-into `src/bunderstack/` with `index.ts`, `schema/`, `access.ts`, `auth.ts`,
+into `src/bunderstack/` with `backend.ts`, `index.ts`, `schema/`, `access.ts`, `auth.ts`,
 `env.ts`, `jobs/`, and `api/` as needed. The entry remains the one place that
-assembles those modules into `createBunderstack()`; do not create parallel app,
+starts the declared backend; do not create parallel app,
 database, or auth instances.
 
 ## Aggregate the schema
 
 Export every domain, Better Auth, plugin, and Bunderstack internal table from
-the schema object passed to `createBunderstack()`. Include
+the schema object passed to `bunderstack()`. Include
 `export * from 'bunderstack/schema'` so migrations include the internal tables.
 Define Better Auth tables required by the selected auth flows and plugins; do
 not assume a minimal auth configuration needs every optional provider table.
@@ -61,8 +65,8 @@ export const projectsRouter = {
 // src/bunderstack/api/index.ts
 export const api = { projects: projectsRouter }
 
-// entry
-createBunderstack({ schema, database, api })
+// backend.ts
+bunderstack({ schema, database, api })
 ```
 
 Do not write a router factory that receives a bag of procedures. That shape
@@ -118,7 +122,7 @@ const instrumentation = o.middleware(async ({ context, next, path }) => {
   }
 })
 
-createBunderstack({ schema, database, middleware: [instrumentation], api })
+bunderstack({ schema, database, middleware: [instrumentation], api })
 ```
 
 Three rules apply to a graph-wide middleware. It runs before authentication, so

package/skills/creating-bunderstack-apps/references/runtime-integrations.md

@@ -39,8 +39,11 @@ Declare queue jobs with `jobs: (j) => j.define(...)`, then run them in a
 separate production process:
 
 ```ts
-import { app } from './bunderstack'
+import { backend } from './bunderstack/backend'
 
+const app = await backend.start({
+  env: { ...process.env, BUNDERSTACK_ROLE: 'web' },
+})
 await app.runWorker()
 ```
 

package/skills/migrating-to-bunderstack/SKILL.md

@@ -16,7 +16,7 @@ infrastructure, use `creating-bunderstack-apps` instead.
    capability today and which call sites depend on it.
 2. Add a migration contract test before removing legacy paths, so every
    deletion has a gate that fails when behaviour is lost.
-3. Establish one Bunderstack app and one schema aggregate.
+3. Establish one Bunderstack backend declaration, one runtime, and one schema aggregate.
 4. Move auth and access without creating duplicate instances.
 5. Replace infrastructure capability by capability.
 6. Mount one handler and separate the production worker.
@@ -31,8 +31,9 @@ database client sits outside provisioning, migration state, and request
 transactions. A second env schema drifts from the validated one and passes
 locally while failing at boot.
 
-Pass `authConfig` into `createBunderstack()`, re-export `app.auth` and `app.db`
-from the entry, and let the `env` passed to `createBunderstack()` be the only
+Pass `authConfig` into `bunderstack()`, start that declaration once in the web
+entry, and re-export `app.auth` and `app.db` from the runtime entry. Let the
+declared `env` schema plus the source passed to `backend.start()` be the only
 validated source. A more specific file route also shadows the catch-all, so a
 surviving `/api/auth/$` silently keeps serving the instance you meant to delete.
 
@@ -53,7 +54,7 @@ surviving `/api/auth/$` silently keeps serving the instance you meant to delete.
 | Channel-and-payload realtime publishing                       | `ctx.realtime.publish(schema.tasks, 'update', row)` after the write commits       |
 | AWS or Tigris SDK wrapper                                     | `app.storage` buckets                                                             |
 | Resend SDK wrapper                                            | `app.email.send(...)`                                                             |
-| `createEnv()` beside the app                                  | `env` passed to `createBunderstack()`                                             |
+| `createEnv()` beside the app                                  | `env` schema in `bunderstack()` and source in `backend.start()`                   |
 | Implicit database driver                                      | Explicit adapter, `database: { adapter: libsql(), url }`                          |
 | Schema push in production                                     | Committed Drizzle `migrations/`, applied by `provision(app)`                      |
 | Undeclared deployment                                         | `package.json#bunderstack.entry` and a checked blueprint                          |
@@ -73,8 +74,8 @@ shim is acceptable when call sites are numerous; the shim is deleted under this
 same gate. Uninstall the replaced SDK package in the commit that removes its
 last importer, so a stale wrapper cannot be reintroduced silently.
 
-Tests and scripts that construct their own app instance must call
-`app.close()`.
+Tests should use lexically scoped `await using` fixtures from `backend.test()`;
+scripts that explicitly start a runtime must close the runtime they own.
 
 ## Production gate
 

package/skills/migrating-to-bunderstack/references/audit-checklist.md

@@ -6,26 +6,26 @@ output or a file reference, not an assertion.
 
 | Capability             | Legacy shape to find                                                                 | Authoritative replacement                                                            | Evidence that the move is done                                                                        | Deletion gate                                                       |
 | ---------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| Auth instance          | A second `betterAuth({...})` call, a custom session resolver, a patched `getSession` | `authConfig` passed to `createBunderstack()`; consumers import `app.auth`            | One `betterAuth` construction in the repository; a protected route rejects an unauthenticated request | No importer of the legacy auth module remains                       |
+| Auth instance          | A second `betterAuth({...})` call, a custom session resolver, a patched `getSession` | `authConfig` passed to `bunderstack()`; consumers import `app.auth`                  | One `betterAuth` construction in the repository; a protected route rejects an unauthenticated request | No importer of the legacy auth module remains                       |
 | Auth schema            | Auth tables generated into a legacy schema directory                                 | Auth tables in the one schema aggregate                                              | Generated migration includes `user`, `session`, `account`, `verification`                             | Legacy schema directory has no importers                            |
 | Database client        | A module constructing its own libSQL/Postgres client                                 | `app.db`, re-exported from the entry                                                 | The entry is the only place calling the adapter factory                                               | Legacy `db` module deleted or reduced to a re-export, then deleted  |
 | API mounting           | Hand-written handler maps; separate `/api/auth/$`, `/api/trpc/$`                     | `createApiHandlers(app)` on one `/api/$`                                             | Auth and oRPC requests succeed with only the catch-all present                                        | Shadowing route files deleted                                       |
 | Custom API routes      | Route files doing CRUD the framework can generate                                    | Generated CRUD plus `defineAccess`, or an `o.protected` procedure                    | Access rules cover each exposed table; a cross-owner request is denied                                | Route file has no client callers                                    |
 | Access control         | Per-endpoint session checks and hand-written SQL filters                             | `defineAccess(schema, rules)` with `scope.read` / `scope.write`                      | A test asserts a second user cannot read or write the first user's rows                               | Manual filter helpers unused                                        |
-| Jobs                   | BullMQ or a bespoke queue module                                                     | `jobs.define({ ... })` and `app.jobs.enqueue(...)`                                   | Job appears in `app.manifest.background.jobs`                                                         | No queue library importer; package uninstalled                      |
+| Jobs                   | BullMQ or a bespoke queue module                                                     | `jobs.define({ ... })` and `app.jobs.enqueue(...)`                                   | Job appears in `backend.manifest.background.jobs`                                                     | No queue library importer; package uninstalled                      |
 | Cron                   | `/api/cron/*` guarded by a shared secret                                             | `jobs.cron({ schedule, handler })`                                                   | Cron task appears in the blueprint                                                                    | Cron route file and its secret removed from env                     |
 | Worker topology        | `startWorker()` or a queue bootstrap in the web entry                                | `src/worker.ts` calling `app.runWorker()`, run as its own process                    | Web entry starts no worker; the worker command exists in deployment config                            | Worker process is deployed before the embedded call is removed      |
 | Realtime               | Custom WebSocket server, manual pub/sub, channel-and-payload publishing              | `realtime` config plus `ctx.realtime.publish(table, event, row)` after commit        | A direct write reaches a subscriber with the complete row                                             | Custom transport deleted; shared Redis configured for multi-process |
 | Storage                | AWS or Tigris SDK wrapper, custom multipart upload route                             | Declared buckets and `app.storage`                                                   | Upload, signed URL, and delete work through the facade                                                | Wrapper deleted and SDK uninstalled                                 |
 | Email                  | Resend or SMTP SDK wrapper                                                           | `email` config and `app.email.send(...)`                                             | A send succeeds through the configured provider                                                       | Wrapper deleted and SDK uninstalled                                 |
-| Env                    | `createEnv()` beside the app, `dotenv`, unchecked `process.env` reads                | `env` passed to `createBunderstack()`; `app.env` / `ctx.env`                         | Boot fails with a clear message when a required variable is missing                                   | Legacy env module unused; `.env.example` lists names only           |
+| Env                    | `createEnv()` beside the app, `dotenv`, unchecked `process.env` reads                | `env` schema in `bunderstack()`; source in `backend.start()`; `app.env` / `ctx.env`  | Boot fails with a clear message when a required variable is missing                                   | Legacy env module unused; `.env.example` lists names only           |
 | API declaration        | Router factories taking a bag of procedures; hand-written builder generics           | `defineApi({ schema, env })` bases in one module, plain router objects, `api` object | A router module imports its base and exports an object; no factory remains                            | `BunderstackApiBuilder<...>` and `os.$context<...>()` deleted       |
 | Observability          | Tracing or logging attached to an application procedure base                         | `middleware: [...]` in the config, which also reaches the generated CRUD             | A generated CRUD request produces a span or log line                                                  | Per-base instrumentation removed                                    |
 | Errors                 | `new ORPCError(...)` at call sites, or a second error model                          | `errors.CODE({ message })`; `BunderstackError` outside a handler                     | A failing request answers the declared status, not 500                                                | `ORPCError` import gone from the api layer                          |
 | List endpoints         | Hand-rolled limit/offset/filter/count blocks repeated per table                      | `listSpec(table, options)` applied to your own base                                  | The endpoint accepts cursor and `count: true` and answers `ListResult`                                | Duplicated paging helpers deleted                                   |
 | Migrations             | Schema push against production                                                       | Committed Drizzle `migrations/`, applied by `provision(app)`                         | `migrations/` is under version control and applies cleanly to an empty database                       | Push command removed from deployment                                |
 | Deployment declaration | No `bunderstack.entry`, no blueprint                                                 | `package.json#bunderstack.entry` and a committed blueprint                           | `bun run blueprint:check` passes in CI                                                                | Deployment reads the blueprint rather than ad-hoc process config    |
-| App lifetime           | Tests and scripts leaking app instances                                              | `app.close()` in a `finally` or `afterEach`                                          | The test run exits without hanging                                                                    | —                                                                   |
+| App lifetime           | Tests and scripts leaking app instances                                              | Lexical `await using` fixture from `backend.test()`                                  | Concurrent tests own independent fixtures and the run exits without hanging                           | —                                                                   |
 
 ## Reading a partially migrated application
 

package/skills/migrating-to-bunderstack/references/runtime-replacements.md

@@ -6,13 +6,12 @@ names; do not change the contracts.
 ## Modular entry
 
 A migrated application has enough configuration to justify `src/bunderstack/`
-with `index.ts`, `schema/`, `access.ts`, `auth.ts`, `env.ts`, `jobs/`, and
-`api/`. The entry is the only place that assembles them:
+with `backend.ts`, `index.ts`, `schema/`, `access.ts`, `auth.ts`, `env.ts`,
+`jobs/`, and `api/`. The declaration is the only place that assembles them:
 
 ```ts
-import { createBunderstack } from 'bunderstack'
-import { libsql } from 'bunderstack/database/libsql'
-import { provision } from 'bunderstack/provision'
+import { bunderstack } from 'bunderstack'
+import { libsql } from 'bunderstack/libsql'
 import { access } from './access'
 import { authConfig } from './auth'
 import { envSchema } from './env'
@@ -20,33 +19,31 @@ import { defineJobs } from './jobs'
 import { schema } from './schema'
 import * as v from 'valibot'
 
-export async function createApp(options: { databaseUrl?: string } = {}) {
-  return createBunderstack({
-    schema,
-    access,
-    env: envSchema,
-    database: {
-      adapter: libsql(),
-      url: options.databaseUrl ?? process.env.DATABASE_URL ?? 'file:./data.db',
-    },
-    auth: authConfig,
-    email: { from: process.env.EMAIL_FROM ?? 'App <no-reply@example.com>' },
-    storage: {
-      local: './uploads',
-      defaultBucket: 'files',
-      buckets: {
-        files: {
-          visibility: 'private',
-          access: { create: 'authenticated', get: 'owner', delete: 'owner' },
-        },
+export const backend = bunderstack({
+  schema,
+  access,
+  env: envSchema,
+  database: {
+    adapter: libsql(),
+    url: 'file:./data.db',
+  },
+  auth: authConfig,
+  email: { from: 'App <no-reply@example.com>' },
+  storage: {
+    local: './uploads',
+    defaultBucket: 'files',
+    buckets: {
+      files: {
+        visibility: 'private',
+        access: { create: 'authenticated', get: 'owner', delete: 'owner' },
       },
     },
-    realtime: process.env.REDIS_URL ? { redis: process.env.REDIS_URL } : true,
-    jobs: defineJobs,
-    middleware: [instrumentation],
-    api,
-  })
-}
+  },
+  realtime: true,
+  jobs: defineJobs,
+  middleware: [instrumentation],
+  api,
+})
 
 // api/base.ts — the builder is a module value, so router modules import the
 // bases they need instead of receiving them through the config callback.
@@ -59,7 +56,11 @@ export async function createApp(options: { databaseUrl?: string } = {}) {
 //
 //   export const api = { projects: projectsRouter }
 
-export const app = await createApp()
+// index.ts
+import { provision } from 'bunderstack/provision'
+import { backend } from './backend'
+
+export const app = await backend.start()
 export const { db, auth, env } = app
 export type App = typeof app
 
@@ -67,12 +68,9 @@ await provision(app)
 ```
 
 The database adapter is imported explicitly; there is no implicit driver. Keep
-the factory for tests that need an isolated `file::memory:` database.
-
-Keep unrelated external side effects out of this import graph. The blueprint
-command imports the entry with `BUNDERSTACK_INTROSPECT=1`, so a module that
-connects to a queue or calls a third-party API at import time breaks
-introspection.
+unrelated external side effects out of the backend import graph. The blueprint
+imports the declaration and reads `backend.manifest`; it never starts the app,
+connects to a queue, or needs a special environment flag.
 
 Aggregate every domain, Better Auth, plugin, and internal table in the schema
 object, including `export * from 'bunderstack/schema'`, so migrations cover the
@@ -116,8 +114,11 @@ Production queue work is its own process:
 
 ```ts
 // src/worker.ts
-import { app } from './bunderstack'
+import { backend } from './bunderstack/backend'
 
+const app = await backend.start({
+  env: { ...process.env, BUNDERSTACK_ROLE: 'web' },
+})
 await app.runWorker()
 ```
 
@@ -224,7 +225,7 @@ const url = await app.storage.getUrl(key, { expiresIn: 3600 })
 await app.storage.delete(fileId)
 ```
 
-Buckets are declared in `createBunderstack()` with their own visibility and
+Buckets are declared in `bunderstack()` with their own visibility and
 access rules. Delete the AWS or Tigris wrapper and uninstall the SDK. A custom
 multipart upload route is replaced by the bucket's own upload route unless it
 performs domain work that cannot move into a job.
@@ -241,7 +242,7 @@ Standard `fetch`, so the `resend` package is uninstalled.
 
 ## Env
 
-Pass `envSchema` to `createBunderstack({ env: envSchema })` and read `app.env`
+Pass `envSchema` to `bunderstack({ env: envSchema })` and read `app.env`
 or `ctx.env`. Remove `@t3-oss/env-core` `createEnv()` calls and `dotenv`; Bun
 loads `.env` itself. Server variables must not use the `PUBLIC_` prefix, and
 browser-safe variables must. Declared env appears in the deployment blueprint,
@@ -256,7 +257,7 @@ commit migrations before production:
 
 ```json
 {
-  "bunderstack": { "entry": "src/bunderstack/index.ts" },
+  "bunderstack": { "entry": "src/bunderstack/backend.ts" },
   "scripts": {
     "worker": "bun src/worker.ts",
     "db:generate": "drizzle-kit generate",
@@ -273,14 +274,19 @@ or build output.
 
 ## Test and script ownership
 
-A test or script that constructs its own app owns its lifetime:
+A test or script owns its fixture lexically:
 
 ```ts
-const app = await createApp({ databaseUrl: 'file::memory:' })
-try {
-  await provision(app, { force: true })
-  // ...
-} finally {
-  await app.close()
-}
+await using t = await backend.test({ database: { schema: 'push' } })
+const identity = t.auth.mockSession({
+  id: 'user-1',
+  email: 'dev@example.com',
+  name: 'Developer',
+})
+const client = t.client(identity)
+// ...
 ```
+
+The fixture isolates database, email, storage, realtime, and queue state and is
+disposed at the end of the block. Keep application-specific organization setup
+in a typed helper layered on top of the base user/session auth helper.