bunderstack 0.17.0-beta.8 → 0.17.0

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

@@ -0,0 +1,197 @@
+# Application structure
+
+## Keep the entry declarative
+
+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`.
+
+Start a small API in `src/bunderstack.ts`. Split a meaningful configuration
+into `src/bunderstack/` with `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,
+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
+`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.
+
+## Define authorization on the server
+
+Use `defineAccess(schema, rules)` for generated CRUD. Give each exposed table
+an explicit operation policy and set `ownerColumn` for owner rules. Keep auth,
+internal, and administrative tables out of generated CRUD unless deliberately
+exposing the supported `user` table.
+
+Use `scope.read` and `scope.write` to enforce tenant columns on generated
+lists, reads, and writes. For example, an organization-owned table can derive
+`{ organizationId: ctx.session?.activeOrganizationId ?? '__none__' }`, keeping
+users without an active organization outside tenant rows. Use protected oRPC
+procedures built from `o.protected` when authorization depends on related rows
+or roles; hiding a UI route is not authorization.
+
+## Extend the one API graph
+
+Declare the builder once at module scope with `defineApi({ schema, env })`. It
+infers the schema and env types from the values, so no application writes
+`BunderstackApiBuilder<...>` by hand, and it reads nothing at runtime.
+
+```ts
+// src/bunderstack/api/base.ts
+export const o = defineApi({ schema, env: envSchema })
+export const publicProcedure = o.public
+export const protectedProcedure = o.protected
+```
+
+Router modules are plain objects that import the base they need, and the entry
+passes the finished router as `api`:
+
+```ts
+// src/bunderstack/api/projects.ts
+export const projectsRouter = {
+  stats: protectedProcedure.input(...).handler(...),
+}
+
+// src/bunderstack/api/index.ts
+export const api = { projects: projectsRouter }
+
+// entry
+createBunderstack({ schema, database, api })
+```
+
+Do not write a router factory that receives a bag of procedures. That shape
+only existed because `api` used to be a callback. The callback form,
+`api: (o) => ({ ... })`, still works for a router that must be built from the
+framework builder at configuration time.
+
+Use `o.public`, `o.protected`, or `o.webhook`; add `.route(...)` only when a
+stable HTTP projection is useful. Generated CRUD, custom procedures, files,
+health, and `realtime.changes` remain in the same typed oRPC graph and client.
+
+## Give a group of procedures its own base
+
+A base is an oRPC builder, so `.use()` produces another one. Declare a rule
+once instead of repeating it in every handler that depends on it:
+
+```ts
+export const adminProcedure = o.protected.use(async ({ context, next, errors }) => {
+  if (context.user.role !== 'admin') {
+    throw errors.FORBIDDEN({ message: 'Admin access required' })
+  }
+  return next()
+})
+```
+
+`next({ context })` merges into the context and types it for everything
+downstream, which is how an organization scope or a resolved tenant reaches
+handlers without an argument.
+
+## Instrument the whole graph, not one base
+
+Bunderstack builds the CRUD, storage, and realtime procedures itself, so they
+never pass through a base the application declares. A middleware attached to
+`o.protected` therefore measures the application's own procedures and leaves
+the generated CRUD — usually the larger share of traffic — unmeasured.
+
+Register cross-cutting middleware in the configuration instead:
+
+```ts
+const instrumentation = o.middleware(async ({ context, next, path }) => {
+  if (path[0] === 'realtime') return next()
+  const startedAt = performance.now()
+  try {
+    return await next()
+  } finally {
+    record(path.join('.'), performance.now() - startedAt, context.peekSession()?.user?.id)
+  }
+})
+
+createBunderstack({ schema, database, middleware: [instrumentation], api })
+```
+
+Three rules apply to a graph-wide middleware. It runs before authentication, so
+`context.user` does not exist there. Read the caller with
+`context.peekSession()` after `await next()`, never `getSession()`: forcing the
+session makes every request pay for authentication, including signed webhooks
+that never needed it, and `peekSession()` is for observability only, never for
+authorization. A realtime subscription is one long-lived call, so code after
+`await next()` runs when the stream closes, not when it starts.
+
+## Raise declared errors
+
+Every procedure carries one error map: `BAD_REQUEST`, `UNAUTHORIZED`,
+`FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `PAYLOAD_TOO_LARGE`,
+`TOO_MANY_REQUESTS`. Inside a handler or middleware, raise from the `errors`
+argument, with extra context in `data.details`:
+
+```ts
+throw errors.NOT_FOUND({ message: 'Project not found' })
+```
+
+Code outside a handler — a service function or a job — has no `errors`
+argument. Throw `BunderstackError`, which the framework maps to the same typed
+error. Do not construct `ORPCError` by hand anywhere.
+
+## Give list endpoints the shared contract
+
+`listSpec(table, options)` gives a procedure you write the same filter, sort,
+cursor, and count contract the generated CRUD list uses. Apply both parts to
+your own base, which is what preserves the row type to the client:
+
+```ts
+const logsList = listSpec(appLogs, { filterable: ['level'], sortable: ['createdAt'] })
+logs: adminProcedure.input(logsList.input).handler(logsList.handler)
+```
+
+It reads no `access` configuration; the base procedure carries the policy.
+
+## Type helpers that take the database
+
+A service module cannot reach `typeof app.db` without an import cycle back to
+the entry. Use `BunderstackDb<typeof schema>` and `BunderstackTx<typeof schema>`
+instead of `any`.
+
+## Keep the entry out of its own import graph
+
+The api router and everything it imports are evaluated when the entry is
+imported. A module in that graph that imports the app back — a bot client
+reading `db`, a logger reading `app.env` — closes a cycle and breaks module
+initialization. Load the app lazily in such a module.
+
+## Keep credentials environment-owned
+
+Declare validated server and browser-safe client variables in `env`. Server
+variables must not use the `PUBLIC_` prefix; client variables must use it.
+Use `app.env` (and `ctx.env`) rather than duplicating unchecked configuration.
+Commit `.env.example` with names and safe placeholders only. Keep production
+secrets, database URLs, storage credentials, and auth secrets in the runtime
+environment.
+
+Use local libSQL storage and console email for development when appropriate;
+declare production adapters and credentials through configuration and runtime
+environment rather than hard-coding them.
+
+## Publish direct writes
+
+Generated CRUD publishes realtime changes automatically. For a write through
+`app.db` or `ctx.db`, return the complete changed row, wait for its transaction
+to commit, then publish it with the table object:
+
+```ts
+const [task] = await ctx.db
+  .update(schema.tasks)
+  .set({ status: 'done' })
+  .where(eq(schema.tasks.id, taskId))
+  .returning()
+
+await ctx.realtime.publish(schema.tasks, 'update', task)
+```
+
+Do not publish from inside an enclosing transaction. The complete row lets the
+existing access filter evaluate owner and read-scope columns.

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

@@ -0,0 +1,68 @@
+# Runtime integrations
+
+`app.handler` is the single Web Standard `Request -> Response` integration
+point. Mount it once; do not recreate routing, auth, or database layers in a
+framework adapter.
+
+## TanStack Start
+
+TanStack Start owns the web process. Use `bunderstackStart<App>()` for the
+client and mount the catch-all route with `createApiHandlers(app)`:
+
+```ts
+export const Route = createFileRoute('/api/$')({
+  server: { handlers: createApiHandlers(app) },
+})
+```
+
+Keep the client setup in `src/api.ts`, not `src/client.ts`, which is a reserved
+Start entry point. Import `App` as a type so the browser does not load server
+runtime code.
+
+## Standalone Bun and other runtimes
+
+For a standalone server, pass the handler directly:
+
+```ts
+Bun.serve({ fetch: app.handler })
+```
+
+Other server frameworks must adapt their request and response objects to the
+Web Standard pair, then delegate to `app.handler`. Astro adapters therefore
+convert to and from Web Standard requests and responses. A browser-only React
+SPA has no server request handler: run a separate Bun API process and point the
+frontend's API base URL at that process.
+
+## Background runtime
+
+Declare queue jobs with `jobs: (j) => j.define(...)`, then run them in a
+separate production process:
+
+```ts
+import { app } from './bunderstack'
+
+await app.runWorker()
+```
+
+Do not start a production worker or cron scheduler from the web entry.
+`j.cron()` is delivered by the platform over authenticated HTTP. Queue handlers
+are at-least-once, so make them idempotent and declare input validation and
+retries.
+
+If workers publish realtime events, configure the same shared Redis transport
+for web and worker processes. `realtime: true` alone is process-local and is
+only safe when the worker is embedded with `app.startWorker()` for local work.
+
+## Realtime and synced collections
+
+Clients consume the typed `realtime.changes` async iterator. Idle HTTP streams
+receive a transport-only `heartbeat` every five seconds; the Bunderstack query
+client filters it before cache callbacks and does not advance the Publisher
+resume ID. Do not add an application polling loop or publish heartbeat events
+through oRPC Publisher.
+
+`bunderstack-sync` reconciles successful mutations from the canonical row
+returned by generated CRUD, without a follow-up list refetch. Realtime echoes
+are idempotent, and reconnect performs the full refetch used to repair drift.
+Keep custom replacement procedures compatible by returning the complete row,
+including `id`.

package/skills/creating-bunderstack-apps/references/verification.md

@@ -0,0 +1,25 @@
+# Verification contract
+
+Run these gates from the application root after changing dependencies,
+configuration, or application code:
+
+```sh
+bun install
+bun test
+bun run typecheck
+bun run build
+bun run blueprint
+bun run blueprint:check
+```
+
+`bun run blueprint` generates the committed `bunderstack.blueprint.yaml` from
+the configured Bunderstack entry. Set `package.json#bunderstack.entry` when the
+entry is not `src/bunderstack.ts`. `bun run blueprint:check` must pass in CI so
+the committed declaration matches the application.
+
+Before production, generate and commit the Drizzle `migrations/` folder. With
+no migrations folder, `provision(app)` uses the development schema-push loop
+(and needs drizzle-kit). Once migrations are committed, it applies pending
+migrations without importing drizzle-kit. Keep the generated migrations,
+blueprint, tests, worker entry, API mount, and deployment scripts under version
+control; never commit secrets, databases, uploads, or build output.

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

@@ -0,0 +1,84 @@
+---
+name: migrating-to-bunderstack
+description: Use when moving an existing or partially migrated application onto Bunderstack and replacing its separate auth, database, API, storage, email, jobs, cron, or realtime infrastructure, or when finishing a migration that stalled part-way.
+---
+
+# Migrating to Bunderstack
+
+Migration deletes infrastructure rather than wrapping it, and the application
+stays working at every phase. For a new application with no existing
+infrastructure, use `creating-bunderstack-apps` instead.
+
+## Workflow
+
+1. Inventory current auth, database, API, storage, email, jobs, cron, realtime,
+   env, migrations, and deployment ownership. Record which module owns each
+   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.
+4. Move auth and access without creating duplicate instances.
+5. Replace infrastructure capability by capability.
+6. Mount one handler and separate the production worker.
+7. Remove wrappers only after call sites and tests move.
+8. Generate migrations and the blueprint, then verify production topology.
+
+## One live instance per capability
+
+The most damaging migration state is two working implementations of the same
+capability. A second Better Auth instance splits session validation. A second
+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
+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.
+
+## Replacements
+
+| Legacy shape                                                  | Current contract                                                                  |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Hand-written `ALL: ({ request }) => app.handler(request)` map | `createApiHandlers(app)` on one `/api/$` route                                    |
+| Separate `/api/auth/$` or `/api/trpc/$` mounts                | Deleted; the catch-all serves Better Auth and the unified oRPC `/api/rpc/*` graph |
+| tRPC router and procedure clients                             | Router modules over `defineApi` bases, passed as `api`, with one inferred client   |
+| Per-file router factories taking a bag of procedures          | Bases exported from one module, imported by plain router objects                   |
+| Hand-built `ORPCError` or a second error model                | `errors.CODE({ message })`, or `BunderstackError` outside a handler                |
+| Tracing attached to an application base                       | `middleware: [...]`, which also covers the generated CRUD                          |
+| Hand-rolled limit/offset/count blocks                         | `listSpec(table, options)` applied to your own base                                |
+| `any`-typed db parameters in helpers                          | `BunderstackDb<typeof schema>` and `BunderstackTx<typeof schema>`                  |
+| Worker started from the web entry                             | `src/worker.ts` owning `app.runWorker()`                                          |
+| `/api/cron/*` guarded by a shared secret                      | `jobs.cron()` with platform delivery                                              |
+| 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()`                                             |
+| 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                          |
+
+Read [runtime replacements](references/runtime-replacements.md) before writing
+any replacement above; it holds the current snippets and the realtime transport
+rule for multi-process deployments. Read the
+[audit checklist](references/audit-checklist.md) during phase 1 to inventory
+ownership, and again at phase 7 before each deletion.
+
+## Deletion gate
+
+Do not delete a legacy module until its replacement is mounted, every call site
+imports the replacement, a migration contract test covers the behaviour, and
+`bun run typecheck` reports no remaining importers. A one-release re-export
+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()`.
+
+## Production gate
+
+Before the cutover deploy: committed migrations exist, the worker runs as its
+own process, web and worker share a realtime transport if jobs publish events,
+`package.json#bunderstack.entry` points at the entry, and
+`bun run blueprint:check` passes in CI.

package/skills/migrating-to-bunderstack/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Migrating to Bunderstack"
+  short_description: "Move existing applications onto Bunderstack"
+  default_prompt: "Use $migrating-to-bunderstack to migrate this application to Bunderstack."

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

@@ -0,0 +1,57 @@
+# Audit checklist
+
+Use this table at phase 1 to record who owns each capability today, and again
+at phase 7 before deleting anything. Fill the evidence column with a command
+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 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                      |
+| 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           |
+| 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                                                                    | —                                                                   |
+
+## Reading a partially migrated application
+
+Some applications are already on Bunderstack for part of their surface. The
+audit is the same, but the answer to "who owns this capability" is often _both_,
+which is the state that causes production incidents.
+
+A real example: an application whose Bunderstack modules live in
+`src/bunderstack/` while `src/lib/` still holds an auth config, a schema
+directory, and SDK wrappers, whose `package.json` has no `bunderstack.entry`,
+no worker command, and no blueprint scripts, and whose deployment runs a single
+web command. Nothing there is broken in development. In production it means the
+declared entry is unknown to the host, queue jobs run inside web replicas or
+not at all, and two auth configurations disagree about sessions.
+
+Treat that shape as a sequence of the gates above, not as a file list to copy.
+The directory names in any one application are incidental; the ownership
+question is not.
+
+## Order that keeps the application working
+
+Auth and database first, because everything else reads them. Then access and
+API mounting, so authorization is enforced in one place before routes move.
+Then storage, email, jobs, and cron, which are independent of each other. Then
+realtime, which depends on the write paths already being correct. Migrations
+and the blueprint last, because they declare the finished shape.
+
+Deleting in the reverse order of adoption keeps the system reversible: the
+replacement is live and tested before its predecessor stops existing.