bunderstack 0.1.0 → 0.3.0

package/src/index.ts

@@ -1,26 +1,31 @@
 // src/index.ts
 import type { AnyRouter } from '@trpc/server'
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
 import type { Hono as HonoType } from 'hono'
 
 import { fetchRequestHandler } from '@trpc/server/adapters/fetch'
 
 import type { StorageAdapter } from './storage/index'
 import type { TableAccessInput } from './access'
+import type { DbFor } from './db'
 import type { StorageConfigInput } from './storage/buckets'
 
 import { resolveAccessUser, validateAndResolveAccess } from './access'
 import { createAuth, toAuthSessionResolver, withEmailAuthDefaults } from './auth'
 import { resolveConfig, type BunderstackConfig } from './config'
 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'
 import { buildHandler } from './handler'
 import { withInternalTables } from './internal-tables'
-import { provisionSchema } from './provision'
+import {
+  PROVISION_INTERNALS,
+  type WithProvisionInternals,
+} from './provision-internals'
 import { createRealtimeBroker, buildRealtimeRouter } from './realtime/index'
 import { createRedisRealtimeBroker } from './realtime/redis'
 import { deleteFileWithDerivatives } from './storage/delete'
@@ -70,7 +75,7 @@ export type BunderstackApp<
   TRouter = undefined,
 > = {
   handler: (req: Request) => Promise<Response>
-  db: LibSQLDatabase<TSchema>
+  db: DbFor<TSchema>
   auth: AuthInstance
   storage: StorageFacade
   router: HonoType
@@ -80,8 +85,8 @@ export type BunderstackApp<
   env: ValidatedEnv<TEnv>
   /** Email facade; always present — send() throws when email isn't configured. */
   email: EmailFacade
-  /** Push the merged schema (user + internal tables) to the database. */
-  provision: (options?: { force?: boolean }) => Promise<void>
+  /** Deploy-time introspection: what this app needs provisioned. */
+  manifest: BunderstackManifest
   /**
    * Type-only carrier for client inference (`createClient<typeof app>()`).
    * Never assigned at runtime.
@@ -110,7 +115,7 @@ export function createBunderstack<
     /** Builder callback receiving the pre-wired `t` instance. */
     trpc: (t: BunderstackTRPC<TSchema, ValidatedEnv<TEnv>>) => TRouter
   },
-): BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter>
+): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter>>
 export function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
@@ -123,8 +128,8 @@ export function createBunderstack<
     /** Prebuilt tRPC router (escape hatch for multi-file setups). */
     trpc?: TRouter
   },
-): BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter>
-export function createBunderstack<
+): Promise<BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, TRouter>>
+export async function createBunderstack<
   TSchema extends Record<string, unknown>,
   const TAccess extends Record<string, TableAccessInput> | undefined =
     undefined,
@@ -136,35 +141,47 @@ export function createBunderstack<
       | AnyRouter
       | ((t: BunderstackTRPC<TSchema, ValidatedEnv<TEnv>>) => AnyRouter)
   },
-): BunderstackApp<
-  TSchema,
-  TAccess,
-  BucketNamesOf<TStorage>,
-  TEnv,
-  AnyRouter | undefined
+): Promise<
+  BunderstackApp<TSchema, TAccess, BucketNamesOf<TStorage>, TEnv, AnyRouter | undefined>
 > {
+  const dialect = detectDialect(options.schema)
   // Env is validated FIRST: the app refuses to boot on missing/invalid vars,
   // and everything downstream (config, email, trpc ctx) consumes the result.
   const env = validateEnv(options.env, {
     emailProvider: emailProviderTag(options.email),
+    defaultDatabaseUrl:
+      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
   // schema so internal tables never get a CRUD route.
   const mergedSchema = withInternalTables(options.schema)
-  const db = createDb(mergedSchema, config.database)
+  const { db, driver } = await createDb(mergedSchema, {
+    ...config.database,
+    dialect,
+  })
   // `db` is typed with the merged schema (user tables + internal tables) so the
   // storage/idempotency code can query the internal tables. The public surface
-  // and CRUD only expose the USER schema. TS can widen `LibSQLDatabase<merged>`
-  // to `LibSQLDatabase<Record<string, unknown>>` on its own (storage/auth pass
-  // `db` directly), but it can't *narrow* a generic schema view, so this single
-  // intentional cast produces the user-facing db type. See `app.db` / crud below.
-  const userDb = db as unknown as LibSQLDatabase<TSchema>
+  // and CRUD only expose the USER schema. TS can widen the merged-schema db type
+  // on its own (storage/auth pass `db` directly), but it can't *narrow* a
+  // generic schema view, so this single intentional cast produces the
+  // user-facing, per-dialect db type. See `app.db` / crud below.
+  const userDb = db as unknown as DbFor<TSchema>
   const auth = createAuth(
     db,
     withEmailAuthDefaults(config.auth, email, Boolean(options.email)),
+    dialect,
   )
   // Internal routers consume the narrow AuthSessionResolver contract, not the
   // raw better-auth instance. app.auth still exposes `auth` unchanged.
@@ -175,9 +192,10 @@ export 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({
@@ -297,11 +315,25 @@ export function createBunderstack<
     env,
     email,
     trpcRouter,
-    provision: (opts) =>
-      provisionSchema(db, mergedSchema, {
-        force: opts?.force,
-        databaseUrl: config.database.url,
-      }),
+    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
+  // public type so provisioning stays opt-in (and drizzle-kit out of this
+  // module graph).
+  ;(app as WithProvisionInternals)[PROVISION_INTERNALS] = {
+    db,
+    schema: mergedSchema,
+    databaseUrl: config.database.url,
+    migrationsFolder: config.database.migrations,
+    dialect,
+    driver,
   }
 
   return app
@@ -314,9 +346,10 @@ export type {
   BunderstackConfig,
   ResolvedConfig,
 } from './config'
-export { provisionSchema } from './provision'
 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,
@@ -353,16 +386,3 @@ export type {
 } from './storage/buckets'
 // StorageFacade is declared+exported inline above.
 export type { TransformSpec } from './storage/thumbnails'
-
-// Re-export drizzle builders so consumers share bunderstack's drizzle-orm instance
-// and avoid type incompatibilities from duplicate installs.
-export {
-  sqliteTable,
-  integer,
-  text,
-  real,
-  blob,
-  numeric,
-  foreignKey,
-} from 'drizzle-orm/sqlite-core'
-export { eq, and, or, not, gt, gte, lt, lte, desc, asc, sql } from 'drizzle-orm'

package/src/internal-tables-pg.ts

@@ -0,0 +1,45 @@
+// src/internal-tables-pg.ts — Postgres twins of the internal tables. Same
+// table/column names and row shapes as the sqlite originals; timestamps stay
+// integer milliseconds (bigint mode:number) so shared code never branches.
+import {
+  bigint,
+  index,
+  integer,
+  pgTable,
+  primaryKey,
+  text,
+} from 'drizzle-orm/pg-core'
+
+export const bunderstackFilesPg = pgTable(
+  'bunderstack_file_meta',
+  {
+    fileId: text('file_id').primaryKey(),
+    bucket: text('bucket').notNull(),
+    ownerId: text('owner_id'),
+    scopeJson: text('scope_json'),
+    status: text('status').notNull(),
+    filename: text('filename'),
+    contentType: text('content_type'),
+    size: bigint('size', { mode: 'number' }),
+    createdAt: bigint('created_at', { mode: 'number' }).notNull(),
+    confirmedAt: bigint('confirmed_at', { mode: 'number' }),
+  },
+  (t) => [
+    index('bfm_owner').on(t.ownerId),
+    index('bfm_scope').on(t.bucket, t.scopeJson),
+    index('bfm_sweep').on(t.status, t.createdAt),
+  ],
+)
+
+export const bunderstackIdempotencyPg = pgTable(
+  '_bunderstack_idempotency',
+  {
+    key: text('key').notNull(),
+    tableName: text('table_name').notNull(),
+    bodyHash: text('body_hash').notNull(),
+    status: integer('status').notNull(),
+    response: text('response').notNull(),
+    expiresAt: bigint('expires_at', { mode: 'number' }).notNull(),
+  },
+  (t) => [primaryKey({ columns: [t.key, t.tableName] })],
+)

package/src/internal-tables.ts

@@ -1,4 +1,5 @@
-import { getTableName, isTable } from 'drizzle-orm'
+import { getTableName, is, isTable } from 'drizzle-orm'
+import { PgDatabase } from 'drizzle-orm/pg-core'
 import {
   index,
   integer,
@@ -7,6 +8,12 @@ import {
   text,
 } from 'drizzle-orm/sqlite-core'
 
+import { detectDialect } from './dialect'
+import {
+  bunderstackFilesPg,
+  bunderstackIdempotencyPg,
+} from './internal-tables-pg'
+
 export const bunderstackFiles = sqliteTable(
   'bunderstack_file_meta',
   {
@@ -51,11 +58,30 @@ export const INTERNAL_TABLE_NAMES: ReadonlySet<string> = new Set([
   '_bunderstack_idempotency',
 ])
 
-const INTERNAL_TABLE_BY_NAME = new Map<string, (typeof INTERNAL_TABLES)[keyof typeof INTERNAL_TABLES]>([
-  [getTableName(bunderstackFiles), bunderstackFiles],
-  [getTableName(bunderstackIdempotency), bunderstackIdempotency],
+export const INTERNAL_TABLES_PG = {
+  bunderstackFiles: bunderstackFilesPg,
+  bunderstackIdempotency: bunderstackIdempotencyPg,
+} as const
+
+// Both dialect twins count as "ours" for the re-export identity check.
+const INTERNAL_TABLE_CANDIDATES = new Map<string, readonly unknown[]>([
+  [getTableName(bunderstackFiles), [bunderstackFiles, bunderstackFilesPg]],
+  [
+    getTableName(bunderstackIdempotency),
+    [bunderstackIdempotency, bunderstackIdempotencyPg],
+  ],
 ])
 
+/** Internal file-meta table matching the db's dialect. */
+export function filesTableFor(db: unknown) {
+  return is(db, PgDatabase) ? bunderstackFilesPg : bunderstackFiles
+}
+
+/** Internal idempotency table matching the db's dialect. */
+export function idempotencyTableFor(db: unknown) {
+  return is(db, PgDatabase) ? bunderstackIdempotencyPg : bunderstackIdempotency
+}
+
 export function withInternalTables<TSchema extends Record<string, unknown>>(
   schema: TSchema,
 ): TSchema & typeof INTERNAL_TABLES {
@@ -66,9 +92,9 @@ export function withInternalTables<TSchema extends Record<string, unknown>>(
     const name = getTableName(value)
     if (!INTERNAL_TABLE_NAMES.has(name)) continue
 
-    const internal = INTERNAL_TABLE_BY_NAME.get(name)
-    if (internal === value) {
-      // Re-exported from bunderstack/schema — already in user schema.
+    const candidates = INTERNAL_TABLE_CANDIDATES.get(name)
+    if (candidates?.includes(value)) {
+      // Re-exported from bunderstack/schema(-pg) — already in user schema.
       continue
     }
 
@@ -77,7 +103,9 @@ export function withInternalTables<TSchema extends Record<string, unknown>>(
     )
   }
 
-  for (const [key, table] of Object.entries(INTERNAL_TABLES)) {
+  const internal =
+    detectDialect(schema) === 'pg' ? INTERNAL_TABLES_PG : INTERNAL_TABLES
+  for (const [key, table] of Object.entries(internal)) {
     if (!(key in merged)) {
       ;(merged as Record<string, unknown>)[key] = table
     }

package/src/list-query.ts

@@ -1,5 +1,3 @@
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
 import {
   and,
   asc,
@@ -7,14 +5,18 @@ import {
   eq,
   getTableColumns,
   gt,
+  ilike,
   inArray,
+  is,
   like,
   lt,
   or,
   sql,
   type SQL,
 } from 'drizzle-orm'
+import { PgTable } from 'drizzle-orm/pg-core'
 
+import type { AnyDb } from './dialect'
 import type { ResolvedTableAccess, SortOrder } from './access'
 
 import { ErrorCode, ListQueryError } from './errors'
@@ -180,9 +182,12 @@ function buildSearchWhere(
   if (!q || !searchableColumns?.length) return undefined
   const columns = getTableColumns(table)
   const pattern = `%${q.replace(/[%_\\]/g, (ch) => `\\${ch}`)}%`
+  // LIKE is case-insensitive in SQLite but case-sensitive in Postgres; use
+  // ilike there so search behaves identically across dialects.
+  const likeOp = is(table, PgTable) ? ilike : like
   const conditions = searchableColumns
     .filter((name) => name in columns)
-    .map((name) => like(columns[name]!, pattern))
+    .map((name) => likeOp(columns[name]!, pattern))
   return conditions.length ? or(...conditions) : undefined
 }
 
@@ -325,7 +330,7 @@ function buildOrderBy(
 }
 
 export async function executeList<T extends Record<string, unknown>>(
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   table: Parameters<typeof getTableColumns>[0],
   access: ResolvedTableAccess,
   params: ParsedListParams,

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/provision-internals.ts

@@ -0,0 +1,28 @@
+// src/provision-internals.ts
+import type { AnyDb, Dialect } from './dialect'
+import type { Driver } from './db'
+
+/**
+ * Hidden handle connecting `createBunderstack()` to the optional
+ * `bunderstack/provision` entry. Lives in its own module so the main entry
+ * never imports provision code (and its drizzle-kit reference).
+ */
+export const PROVISION_INTERNALS: unique symbol = Symbol.for(
+  'bunderstack.provision-internals',
+)
+
+export interface ProvisionInternals {
+  /** Runtime db typed over the MERGED schema (user + internal tables). */
+  db: AnyDb
+  /** Merged schema used for push. */
+  schema: Record<string, unknown>
+  databaseUrl: string
+  /** Resolved migrations folder (config `database.migrations`). */
+  migrationsFolder: string
+  dialect: Dialect
+  driver: Driver
+}
+
+export interface WithProvisionInternals {
+  [PROVISION_INTERNALS]?: ProvisionInternals
+}

package/src/provision.ts

@@ -1,9 +1,25 @@
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
+// src/provision.ts
+import { access, mkdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
 
-import { mkdir } from 'node:fs/promises'
-import { dirname } from 'node:path'
+import type { AnyDb, Dialect } from './dialect'
 
-async function ensureSqliteFileParent(url: string): Promise<void> {
+import { detectDialect } from './dialect'
+import {
+  PROVISION_INTERNALS,
+  type WithProvisionInternals,
+} from './provision-internals'
+
+/** Create the local backing directory for file-based urls, per dialect. */
+async function ensureLocalDataDir(url: string, dialect: Dialect): Promise<void> {
+  if (dialect === 'pg') {
+    // PGlite data dir: `file:<dir>` or a bare path; server/memory urls need nothing.
+    if (/^postgres(ql)?:\/\//.test(url)) return
+    const raw = url.startsWith('file:') ? url.slice('file:'.length) : url
+    if (raw === ':memory:' || raw.startsWith('memory://')) return
+    await mkdir(raw, { recursive: true })
+    return
+  }
   const match = /^file:(.+)$/.exec(url)
   if (!match) return
   const filePath = match[1]!
@@ -11,22 +27,50 @@ async function ensureSqliteFileParent(url: string): Promise<void> {
   await mkdir(dirname(filePath), { recursive: true })
 }
 
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const DRIZZLE_KIT_HINT =
+  '[bunderstack] Schema push requires drizzle-kit, which is not installed.\n' +
+  '  Development: run `bun add -d drizzle-kit` — provision() will push schema changes to the database on startup.\n' +
+  '  Production: generate migrations locally with `bunx drizzle-kit generate` and commit the folder — provision() applies them without drizzle-kit.'
+
 /** Push the merged schema to the database via drizzle-kit/api. */
 export async function provisionSchema<TSchema extends Record<string, unknown>>(
-  db: LibSQLDatabase<TSchema>,
+  db: AnyDb,
   schema: TSchema,
   options?: { force?: boolean; databaseUrl?: string },
 ): Promise<void> {
+  const dialect = detectDialect(schema)
   if (options?.databaseUrl) {
-    await ensureSqliteFileParent(options.databaseUrl)
+    await ensureLocalDataDir(options.databaseUrl, dialect)
   }
 
-  const { pushSQLiteSchema } = await import('drizzle-kit/api')
-  const result = await pushSQLiteSchema(schema, db)
+  let kit: typeof import('drizzle-kit/api')
+  try {
+    // Ignore comments keep bundlers (vite/nitro, webpack) from resolving
+    // drizzle-kit at build time — this branch only runs in development.
+    kit = await import(
+      /* @vite-ignore */ /* webpackIgnore: true */ 'drizzle-kit/api'
+    )
+  } catch (cause) {
+    throw new Error(DRIZZLE_KIT_HINT, { cause })
+  }
+
+  const result =
+    dialect === 'pg'
+      ? await kit.pushSchema(schema, db as never)
+      : await kit.pushSQLiteSchema(schema, db as never)
 
   if (result.hasDataLoss && !options?.force) {
     throw new Error(
-      '[bunderstack] Schema push would cause data loss. Run `bunx drizzle-kit push` or call app.provision({ force: true }).',
+      '[bunderstack] Schema push would cause data loss. Run `bunx drizzle-kit push` or call provision(app, { force: true }).',
     )
   }
 
@@ -44,3 +88,50 @@ export async function provisionSchema<TSchema extends Record<string, unknown>>(
     `[bunderstack] provisioned ${result.statementsToExecute.length} schema change(s)`,
   )
 }
+
+const MIGRATOR_MODULES = {
+  libsql: 'drizzle-orm/libsql/migrator',
+  pglite: 'drizzle-orm/pglite/migrator',
+  'bun-sql': 'drizzle-orm/bun-sql/migrator',
+  'postgres-js': 'drizzle-orm/postgres-js/migrator',
+} as const
+
+/**
+ * Provision the database for a Bunderstack app.
+ *
+ * The migrations folder is the mode switch:
+ * - `<migrations>/meta/_journal.json` exists → apply committed migrations via
+ *   drizzle-orm's migrator. Pure runtime; drizzle-kit is never imported, so a
+ *   fresh clone deploys with `bun install --production`.
+ * - No migrations → development: push the schema straight to the database via
+ *   drizzle-kit (install it with `bun add -d drizzle-kit`).
+ *
+ * Once you run `bunx drizzle-kit generate` for the first time, provision stops
+ * pushing and every schema change goes through an explicit `generate`.
+ */
+export async function provision(
+  app: object,
+  options?: { force?: boolean },
+): Promise<void> {
+  const internals = (app as WithProvisionInternals)[PROVISION_INTERNALS]
+  if (!internals) {
+    throw new Error(
+      '[bunderstack] provision() expects the app returned by createBunderstack().',
+    )
+  }
+
+  const { db, schema, databaseUrl, migrationsFolder, dialect, driver } =
+    internals
+  const journal = join(migrationsFolder, 'meta', '_journal.json')
+
+  if (await exists(journal)) {
+    await ensureLocalDataDir(databaseUrl, dialect)
+    const { migrate } = (await import(
+      /* @vite-ignore */ /* webpackIgnore: true */ MIGRATOR_MODULES[driver]
+    )) as { migrate: (db: never, cfg: { migrationsFolder: string }) => Promise<void> }
+    await migrate(db as never, { migrationsFolder })
+    return
+  }
+
+  await provisionSchema(db, schema, { force: options?.force, databaseUrl })
+}

package/src/schema-export-pg.ts

@@ -0,0 +1,6 @@
+// src/schema-export-pg.ts — pg twins under the same names bunderstack/schema
+// uses, so `export * from 'bunderstack/schema/pg'` mirrors the sqlite setup.
+export {
+  bunderstackFilesPg as bunderstackFiles,
+  bunderstackIdempotencyPg as bunderstackIdempotency,
+} from './internal-tables-pg'

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) : []

package/src/storage/delete.ts

@@ -1,6 +1,5 @@
 // src/storage/delete.ts
-import type { LibSQLDatabase } from 'drizzle-orm/libsql'
-
+import type { AnyDb } from '../dialect'
 import type { StorageAdapter } from './index'
 
 import { deleteFileMetaRow } from './file-meta'
@@ -14,7 +13,7 @@ import { deleteFileMetaRow } from './file-meta'
  */
 export async function deleteFileWithDerivatives(
   adapter: StorageAdapter,
-  db: LibSQLDatabase<Record<string, unknown>>,
+  db: AnyDb,
   fileId: string,
 ): Promise<void> {
   if (adapter.list) {