bunderstack 0.2.0 → 0.3.0

package/README.md

@@ -27,6 +27,39 @@ Bun.serve({ fetch: app.handler })
 Full documentation and examples:
 [github.com/kirill-dev-pro/bunderstack](https://github.com/kirill-dev-pro/bunderstack)
 
+## Platform deployment contract
+
+Deployment platforms (like Bunderhost) integrate with any bunderstack app
+through env vars alone — no code changes required.
+
+### Overrides (beat code-level config)
+
+| Var | Effect |
+| --- | --- |
+| `BUNDERSTACK_DATABASE_URL` | Database URL; wins over `database.url` in code |
+| `BUNDERSTACK_DATABASE_AUTH_TOKEN` | Auth token for the database |
+| `BUNDERSTACK_S3_ENDPOINT` | Forces ALL buckets onto this S3 backend (code-level `local`/per-bucket `s3` blocks are ignored) |
+| `BUNDERSTACK_S3_BUCKET` | Physical bucket name (logical buckets become key prefixes) |
+| `BUNDERSTACK_S3_ACCESS_KEY_ID` / `BUNDERSTACK_S3_SECRET_ACCESS_KEY` | Credentials |
+| `BUNDERSTACK_S3_REGION` | Region (default `auto`) |
+| `BUNDERSTACK_S3_PUBLIC_URL` | Public base URL for `visibility: 'public'` buckets |
+
+Plain `DATABASE_URL` / `S3_*` vars keep their usual role: fallbacks that
+code-level config wins over.
+
+### Introspection
+
+Set `BUNDERSTACK_INTROSPECT=1` and import the app declaration: the boot is
+guaranteed offline (in-memory database, no Redis) and missing user env vars
+don't throw. Then read `app.manifest`:
+
+```ts
+process.env.BUNDERSTACK_INTROSPECT = '1'
+const { app } = await import('./src/bunderstack')
+console.log(JSON.stringify(app.manifest))
+// { dialect, tables, defaultBucket, buckets, realtime, env: { server, client } }
+```
+
 ## Shipping TypeScript source
 
 This package publishes raw TypeScript (`exports` point at `.ts` files). Bun

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Batteries-included backend framework for Bun: CRUD APIs, auth, file storage, realtime, tRPC, email, and validated env from a single Drizzle schema and config object.",
   "keywords": [
     "backend",

package/src/config.ts

@@ -118,6 +118,12 @@ export type ResolvedConfig = {
 export function resolveConfig<TSchema extends Record<string, unknown>>(
   options: BunderstackConfig<TSchema>,
   env?: BaseEnv,
+  // Platform-injected overrides (Bunderhost & co.) beat code-level config so
+  // apps with hardcoded local urls deploy unchanged.
+  platformSource: Record<string, string | undefined> = process.env as Record<
+    string,
+    string | undefined
+  >,
 ): ResolvedConfig {
   const parsed = BunderstackOptionsSchema.parse(options)
   // Self-validate when the caller didn't pass a pre-validated env, so
@@ -127,8 +133,14 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
 
   return {
     database: {
-      url: parsed.database?.url ?? resolvedEnv.DATABASE_URL,
-      authToken: parsed.database?.authToken ?? resolvedEnv.DATABASE_AUTH_TOKEN,
+      url:
+        platformSource['BUNDERSTACK_DATABASE_URL'] ??
+        parsed.database?.url ??
+        resolvedEnv.DATABASE_URL,
+      authToken:
+        platformSource['BUNDERSTACK_DATABASE_AUTH_TOKEN'] ??
+        parsed.database?.authToken ??
+        resolvedEnv.DATABASE_AUTH_TOKEN,
       migrations: parsed.database?.migrations ?? './migrations',
     },
     auth: (() => {
@@ -138,7 +150,7 @@ export function resolveConfig<TSchema extends Record<string, unknown>>(
         secret: authInput.secret ?? resolvedEnv.AUTH_SECRET,
       }
     })(),
-    storage: resolveBuckets(options.storage),
+    storage: resolveBuckets(options.storage, platformSource),
     realtime: parsed.realtime,
   }
 }

package/src/env.ts

@@ -120,7 +120,10 @@ export function validateEnv<TEnv extends EnvConfigInput | undefined>(
   validateSection(envConfig?.server, 'server', source, issues, userVars)
   validateSection(envConfig?.client, 'client', source, issues, userVars)
 
-  if (issues.length > 0) throw new BunderstackEnvError(issues)
+  // Introspection (Bunderhost builder) imports the app declaration to read
+  // its manifest; missing user env must not kill the boot there.
+  const lenient = source.BUNDERSTACK_INTROSPECT === '1'
+  if (issues.length > 0 && !lenient) throw new BunderstackEnvError(issues)
   return { ...base, ...userVars } as ValidatedEnv<TEnv>
 }
 

package/src/index.ts

@@ -16,6 +16,7 @@ import { resolveRealtimeRedisUrl } from './config'
 import { detectDialect } from './dialect'
 import { createEmail, emailProviderTag, type EmailFacade } from './email'
 import { validateEnv, type EnvConfigInput, type ValidatedEnv } from './env'
+import { buildManifest, type BunderstackManifest } from './manifest'
 import { createTRPC, type BunderstackTRPC } from './trpc'
 import { buildCrudRouter } from './crud'
 import { createDb } from './db'
@@ -84,6 +85,8 @@ export type BunderstackApp<
   env: ValidatedEnv<TEnv>
   /** Email facade; always present — send() throws when email isn't configured. */
   email: EmailFacade
+  /** Deploy-time introspection: what this app needs provisioned. */
+  manifest: BunderstackManifest
   /**
    * Type-only carrier for client inference (`createClient<typeof app>()`).
    * Never assigned at runtime.
@@ -150,6 +153,15 @@ export async function createBunderstack<
       dialect === 'pg' ? 'file:./data.pglite' : 'file:./data.db',
   })
   const config = resolveConfig(options, env)
+  // Introspection mode (BUNDERSTACK_INTROSPECT=1): deployment platforms import
+  // the app declaration only to read `app.manifest`. The boot must never touch
+  // the outside world — force an in-memory db (':memory:' is valid for both
+  // dialects) and skip Redis below. Env validation is already lenient (env.ts).
+  const introspect = process.env.BUNDERSTACK_INTROSPECT === '1'
+  if (introspect) {
+    config.database.url = ':memory:'
+    config.database.authToken = undefined
+  }
   const email = createEmail(options.email, { env })
   // Merge bunderstack's internal tables (file-meta, idempotency) into the
   // schema used for the db client + provisioning. CRUD/access stay on the USER
@@ -180,9 +192,10 @@ export async function createBunderstack<
   )
   const realtimeBufferSize =
     typeof config.realtime === 'object' ? config.realtime.bufferSize : undefined
-  const redisUrl = config.realtime
-    ? resolveRealtimeRedisUrl(config.realtime, env)
-    : undefined
+  const redisUrl =
+    config.realtime && !introspect
+      ? resolveRealtimeRedisUrl(config.realtime, env)
+      : undefined
   const broker = config.realtime
     ? redisUrl
       ? createRedisRealtimeBroker({
@@ -302,6 +315,13 @@ export async function createBunderstack<
     env,
     email,
     trpcRouter,
+    manifest: buildManifest({
+      schema: options.schema,
+      dialect,
+      storage: config.storage,
+      envConfig: options.env as EnvConfigInput | undefined,
+      realtime: Boolean(config.realtime),
+    }),
   }
 
   // Hidden handle for the optional `bunderstack/provision` entry. Kept off the
@@ -328,6 +348,8 @@ export type {
 } from './config'
 export { validateEnv, createClientEnv, BunderstackEnvError } from './env'
 export type { EnvConfigInput, BaseEnv, ValidatedEnv } from './env'
+export { buildManifest } from './manifest'
+export type { BunderstackManifest, ManifestEnvVar } from './manifest'
 export { createEmail } from './email'
 export type {
   EmailMessage,

package/src/manifest.ts

@@ -0,0 +1,52 @@
+// src/manifest.ts — deploy-time introspection surface. Pure: consumes already
+// resolved config pieces, never reads process.env or touches the network.
+// Deployment platforms (Bunderhost) import the app declaration with
+// BUNDERSTACK_INTROSPECT=1 and read `app.manifest` to learn what to provision.
+import type { ZodType } from 'zod'
+
+import type { Dialect } from './dialect'
+import type { EnvConfigInput } from './env'
+import type { ResolvedBucket, ResolvedStorageBuckets } from './storage/buckets'
+
+export type ManifestEnvVar = { key: string; required: boolean }
+
+export type BunderstackManifest = {
+  dialect: Dialect
+  tables: string[]
+  defaultBucket: string
+  buckets: { name: string; visibility: ResolvedBucket['visibility'] }[]
+  realtime: boolean
+  env: { server: ManifestEnvVar[]; client: ManifestEnvVar[] }
+}
+
+function describeSection(
+  section: Record<string, ZodType> | undefined,
+): ManifestEnvVar[] {
+  return Object.entries(section ?? {}).map(([key, schema]) => ({
+    key,
+    required: !schema.safeParse(undefined).success,
+  }))
+}
+
+export function buildManifest(args: {
+  schema: Record<string, unknown>
+  dialect: Dialect
+  storage: ResolvedStorageBuckets
+  envConfig: EnvConfigInput | undefined
+  realtime: boolean
+}): BunderstackManifest {
+  return {
+    dialect: args.dialect,
+    tables: Object.keys(args.schema),
+    defaultBucket: args.storage.defaultBucket,
+    buckets: [...args.storage.buckets.values()].map((bucket) => ({
+      name: bucket.name,
+      visibility: bucket.visibility,
+    })),
+    realtime: args.realtime,
+    env: {
+      server: describeSection(args.envConfig?.server),
+      client: describeSection(args.envConfig?.client),
+    },
+  }
+}

package/src/storage/buckets.ts

@@ -108,6 +108,32 @@ export function parseSize(value: string | number): number {
   return Math.floor(num * multiplier)
 }
 
+// ---------------------------------------------------------------------------
+// Platform override (Bunderhost & co.)
+// ---------------------------------------------------------------------------
+
+/**
+ * A deployment platform that injects BUNDERSTACK_S3_ENDPOINT forces every
+ * bucket onto that backend — code-level `local`/per-bucket `s3` blocks are
+ * ignored so apps deploy unchanged. Logical buckets already prefix object
+ * keys ("<bucket>/<uuid>"), so one physical bucket per environment suffices.
+ */
+function platformS3Backend(
+  env: Record<string, string | undefined>,
+): ResolvedBackend | undefined {
+  const endpoint = env['BUNDERSTACK_S3_ENDPOINT']
+  if (!endpoint) return undefined
+  return {
+    type: 's3',
+    bucket: env['BUNDERSTACK_S3_BUCKET'] ?? '',
+    region: env['BUNDERSTACK_S3_REGION'] ?? 'auto',
+    endpoint,
+    accessKeyId: env['BUNDERSTACK_S3_ACCESS_KEY_ID'] ?? '',
+    secretAccessKey: env['BUNDERSTACK_S3_SECRET_ACCESS_KEY'] ?? '',
+    publicUrl: env['BUNDERSTACK_S3_PUBLIC_URL'],
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Shared backend resolution
 // ---------------------------------------------------------------------------
@@ -149,6 +175,9 @@ function resolveBucketBackend(
   sharedBackend: ResolvedBackend,
   env: Record<string, string | undefined>,
 ): ResolvedBackend {
+  // Platform override active → sharedBackend IS the platform backend and
+  // code-level per-bucket backends are ignored.
+  if (env['BUNDERSTACK_S3_ENDPOINT']) return sharedBackend
   if ('s3' in bucketInput && bucketInput.s3 !== undefined) {
     const block = bucketInput.s3
     return {
@@ -232,7 +261,7 @@ export function resolveBuckets(
   input: StorageConfigInput | undefined,
   env: Record<string, string | undefined> = process.env,
 ): ResolvedStorageBuckets {
-  const sharedBackend = resolveSharedBackend(input, env)
+  const sharedBackend = platformS3Backend(env) ?? resolveSharedBackend(input, env)
   const bucketsInput = input?.buckets
 
   const declaredNames = bucketsInput ? Object.keys(bucketsInput) : []