bunderstack 0.12.0 → 0.14.0

package/README.md

@@ -52,20 +52,25 @@ through env vars alone — no code changes required.
 Plain `DATABASE_URL` / `S3_*` vars keep their usual role: fallbacks that
 code-level config wins over.
 
-### Introspection
+### Committed deployment blueprint
 
-Set `BUNDERSTACK_INTROSPECT=1` and import the app declaration: the boot is
-guaranteed offline (the selected adapter returns its `drizzle.mock({ schema })`
-database, no Redis) and missing user env vars don't throw. Then read
-`app.manifest`:
+Generate a deterministic, provider-neutral declaration that a host can read
+without importing the application at deploy time. Version 1 supports TanStack
+Start apps and records database tables and migration mode, storage buckets,
+environment requirements, realtime, jobs, cron, and maintenance schedules.
 
-```ts
-process.env.BUNDERSTACK_INTROSPECT = '1'
-const { app } = await import('./src/bunderstack')
-console.log(JSON.stringify(app.manifest))
-// { version: 2, dialect, tables, tableMap, systemTables, background, ... }
+```sh
+bunx bunderstack blueprint
+bunx bunderstack blueprint --check
 ```
 
+The command imports `src/bunderstack.ts` by default (or
+`package.json#bunderstack.entry`) with `BUNDERSTACK_INTROSPECT=1`, so it never
+opens external database, storage, or realtime connections. Commit the generated
+`bunderstack.blueprint.yaml`; CI should run the `--check` form. The public
+`bunderstack/blueprint` module exposes the strict parser and conversion helpers
+for hosts and other tooling.
+
 Real database clients belong to the app. Call `await app.close()` when a
 standalone process or test is finished; it closes the real libSQL, PGlite,
 postgres.js, or Bun SQL client selected by `database.adapter`. Introspection
@@ -93,8 +98,9 @@ queue handlers never publish realtime events, acknowledge the process-local
 behavior with `app.runWorker({ allowProcessLocalRealtime: true })`.
 
 Inspect the active runtime with `app.realtime.transport` (`'disabled'`,
-`'memory'`, or `'redis'`). Deploy tooling can read the configured transport
-from `app.manifest.realtimeTransport`.
+`'memory'`, or `'redis'`). The generated blueprint declares only whether
+realtime is required; the host chooses its shared transport and injects its
+runtime configuration.
 
 ```ts
 const app = await createBunderstack({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.12.0",
+  "version": "0.14.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",
@@ -30,6 +30,9 @@
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "types": "./src/index.ts",
+  "bin": {
+    "bunderstack": "./src/cli.ts"
+  },
   "exports": {
     ".": "./src/index.ts",
     "./access": "./src/access.ts",
@@ -43,6 +46,7 @@
     "./typeid": "./src/typeid.ts",
     "./typeid/pg": "./src/typeid-pg.ts",
     "./env": "./src/env.ts",
+    "./blueprint": "./src/blueprint.ts",
     "./trpc": "./src/trpc.ts",
     "./cron": "./src/cron.ts",
     "./email/smtp": "./src/email/smtp.ts"
@@ -54,7 +58,8 @@
     "db:migrate": "drizzle-kit migrate"
   },
   "dependencies": {
-    "superjson": "^2.2.0"
+    "superjson": "^2.2.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": ">=0.3.0",

package/src/blueprint-generator.ts

@@ -0,0 +1,157 @@
+import { mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import {
+  blueprintFromManifest,
+  serializeBlueprint,
+  type BunderstackBlueprint,
+} from './blueprint'
+import { parseManifest } from './manifest'
+
+export type GenerateBlueprintOptions = {
+  directory: string
+  entry?: string
+  output?: string
+  check?: boolean
+}
+
+export type GenerateBlueprintResult = {
+  path: string
+  blueprint: BunderstackBlueprint
+  source: string
+  changed: boolean
+}
+
+export class BlueprintCheckError extends Error {
+  constructor() {
+    super('bunderstack.blueprint.yaml is missing or stale; run `bunderstack blueprint`')
+    this.name = 'BlueprintCheckError'
+  }
+}
+
+type AppPackage = {
+  scripts?: Record<string, unknown>
+  dependencies?: Record<string, unknown>
+  devDependencies?: Record<string, unknown>
+  bunderstack?: { entry?: unknown }
+}
+
+function requireRelativePath(value: string, label: string): string {
+  const normalized = value.replaceAll('\\', '/')
+  if (
+    !normalized ||
+    isAbsolute(normalized) ||
+    normalized.split('/').some((part) => !part || part === '..')
+  ) {
+    throw new Error(`[bunderstack] ${label} must be a relative path without traversal`)
+  }
+  return normalized
+}
+
+function resolveWithin(root: string, value: string, label: string): string {
+  const path = resolve(root, requireRelativePath(value, label))
+  const pathFromRoot = relative(root, path)
+  if (pathFromRoot === '..' || pathFromRoot.startsWith('../') || isAbsolute(pathFromRoot)) {
+    throw new Error(`[bunderstack] ${label} must stay within the application directory`)
+  }
+  return path
+}
+
+function normalizeProjectPath(root: string, value: string, label: string): string {
+  if (!isAbsolute(value)) return requireRelativePath(value, label)
+  const pathFromRoot = relative(root, resolve(value)) || '.'
+  return requireRelativePath(pathFromRoot, label)
+}
+
+function requireScript(pkg: AppPackage, name: 'build' | 'start' | 'worker', required: boolean): boolean {
+  const value = pkg.scripts?.[name]
+  if (typeof value === 'string' && value.trim()) return true
+  if (required) throw new Error(`[bunderstack] package.json requires a non-empty "${name}" script`)
+  return false
+}
+
+async function packageVersion(): Promise<string> {
+  const pkg = (await Bun.file(new URL('../package.json', import.meta.url)).json()) as { version: string }
+  return pkg.version
+}
+
+export async function generateBlueprint(
+  options: GenerateBlueprintOptions,
+): Promise<GenerateBlueprintResult> {
+  const directory = await realpath(resolve(options.directory))
+  const packagePath = join(directory, 'package.json')
+  const pkg = JSON.parse(await readFile(packagePath, 'utf8')) as AppPackage
+  const allDependencies = { ...pkg.dependencies, ...pkg.devDependencies }
+  if (typeof allDependencies['@tanstack/react-start'] !== 'string') {
+    throw new Error('[bunderstack] package.json must depend on @tanstack/react-start')
+  }
+  requireScript(pkg, 'build', true)
+  requireScript(pkg, 'start', true)
+
+  const configuredEntry = pkg.bunderstack?.entry
+  const entry = requireRelativePath(
+    options.entry ?? (typeof configuredEntry === 'string' ? configuredEntry : 'src/bunderstack.ts'),
+    'entry',
+  )
+  const entryPath = resolveWithin(directory, entry, 'entry')
+  if (!(await Bun.file(entryPath).exists())) {
+    throw new Error(`[bunderstack] entry does not exist: ${entry}`)
+  }
+  const output = requireRelativePath(options.output ?? 'bunderstack.blueprint.yaml', 'output')
+  const outputPath = resolveWithin(directory, output, 'output')
+
+  const previousIntrospection = process.env.BUNDERSTACK_INTROSPECT
+  process.env.BUNDERSTACK_INTROSPECT = '1'
+  let app: { manifest?: unknown; close?: () => Promise<void> } | undefined
+  try {
+    const module = (await import(`${pathToFileURL(entryPath).href}?blueprint=${Date.now()}`)) as {
+      app?: typeof app
+    }
+    app = module.app
+    if (!app) throw new Error(`[bunderstack] ${entry} must export app`)
+    const manifest = parseManifest(app.manifest)
+    const workerRequired = manifest.background.jobs.length > 0
+    requireScript(pkg, 'worker', workerRequired)
+    const migrationsDirectory = normalizeProjectPath(
+      directory,
+      manifest.database.migrationsDirectory,
+      'migrationsDirectory',
+    )
+    const migrationJournal = join(
+      resolveWithin(directory, migrationsDirectory, 'migrationsDirectory'),
+      'meta',
+      '_journal.json',
+    )
+    const migrationMode = (await Bun.file(migrationJournal).exists()) ? 'migrations' : 'push'
+    const blueprint = blueprintFromManifest({
+      manifest: {
+        ...manifest,
+        database: { ...manifest.database, migrationsDirectory },
+      },
+      generatorVersion: await packageVersion(),
+      entry,
+      migrationMode,
+    })
+    const source = serializeBlueprint(blueprint)
+    const existing = (await Bun.file(outputPath).exists()) ? await Bun.file(outputPath).text() : undefined
+    if (options.check) {
+      if (existing !== source) throw new BlueprintCheckError()
+      return { path: outputPath, blueprint, source, changed: false }
+    }
+    if (existing === source) return { path: outputPath, blueprint, source, changed: false }
+    await mkdir(dirname(outputPath), { recursive: true })
+    const temporary = `${outputPath}.${process.pid}.${Date.now()}.tmp`
+    try {
+      await writeFile(temporary, source, { mode: 0o600 })
+      await rename(temporary, outputPath)
+    } finally {
+      await rm(temporary, { force: true })
+    }
+    return { path: outputPath, blueprint, source, changed: true }
+  } finally {
+    await app?.close?.()
+    if (previousIntrospection === undefined) delete process.env.BUNDERSTACK_INTROSPECT
+    else process.env.BUNDERSTACK_INTROSPECT = previousIntrospection
+  }
+}

package/src/blueprint.ts

@@ -0,0 +1,188 @@
+import { parse, stringify } from 'yaml'
+import { z } from 'zod'
+
+import { parseCron } from './jobs/cron'
+import type { BunderstackManifest } from './manifest'
+
+export type MigrationMode = 'migrations' | 'push'
+
+export type BunderstackBlueprint = {
+  version: 1
+  generator: { name: 'bunderstack'; version: string }
+  application: {
+    framework: 'tanstack-start'
+    scripts: { build: 'build'; start: 'start'; worker?: 'worker' }
+  }
+  bunderstack: { entry: string; manifestVersion: 3 }
+  resources: {
+    database: BunderstackManifest['database'] & { migrationMode: MigrationMode }
+    storage: BunderstackManifest['storage']
+    realtime?: { required: true }
+  }
+  environment: BunderstackManifest['environment']
+  background: BunderstackManifest['background'] & {
+    worker: { required: boolean }
+  }
+}
+
+const nonEmpty = z.string().min(1)
+const relativePath = nonEmpty.refine(
+  (value) =>
+    !value.startsWith('/') &&
+    !value.includes('\\') &&
+    value.split('/').every((part) => part !== '' && part !== '..'),
+  { message: 'entry must be a relative path without traversal' },
+)
+const cronSchedule = nonEmpty.refine(
+  (value) => {
+    try {
+      parseCron(value)
+      return true
+    } catch {
+      return false
+    }
+  },
+  { message: 'invalid cron schedule' },
+)
+
+const blueprintSchema = z
+  .object({
+    version: z.literal(1),
+    generator: z.object({ name: z.literal('bunderstack'), version: nonEmpty }).strict(),
+    application: z
+      .object({
+        framework: z.literal('tanstack-start'),
+        scripts: z
+          .object({ build: z.literal('build'), start: z.literal('start'), worker: z.literal('worker').optional() })
+          .strict(),
+      })
+      .strict(),
+    bunderstack: z
+      .object({ entry: relativePath, manifestVersion: z.literal(3) })
+      .strict(),
+    resources: z
+      .object({
+        database: z
+          .object({
+            dialect: z.enum(['sqlite', 'pg']),
+            migrationsDirectory: relativePath,
+            migrationMode: z.enum(['migrations', 'push']),
+            tables: z.array(
+              z.object({ exportName: nonEmpty, physicalName: nonEmpty, system: z.boolean() }).strict(),
+            ),
+          })
+          .strict(),
+        storage: z
+          .object({
+            defaultBucket: nonEmpty,
+            buckets: z.array(z.object({ name: nonEmpty, visibility: z.enum(['public', 'private']) }).strict()),
+          })
+          .strict(),
+        realtime: z.object({ required: z.literal(true) }).strict().optional(),
+      })
+      .strict(),
+    environment: z.array(
+      z.object({ key: nonEmpty, required: z.boolean(), scope: z.enum(['server', 'client']) }).strict(),
+    ),
+    background: z
+      .object({
+        worker: z.object({ required: z.boolean() }).strict(),
+        jobs: z.array(z.object({ name: nonEmpty }).strict()),
+        cron: z.array(z.object({ name: nonEmpty, schedule: cronSchedule, timezone: z.literal('UTC') }).strict()),
+        maintenance: z.array(
+          z.object({ name: z.literal('storage-sweep'), schedule: cronSchedule, timezone: z.literal('UTC') }).strict(),
+        ),
+      })
+      .strict(),
+  })
+  .strict()
+
+function sortBy<T>(entries: readonly T[], key: (entry: T) => string): T[] {
+  return [...entries].sort((left, right) => key(left).localeCompare(key(right)))
+}
+
+function rejectDuplicates(collection: string, values: readonly string[]): void {
+  const seen = new Set<string>()
+  for (const value of values) {
+    if (seen.has(value)) throw new Error(`[bunderstack] duplicate ${collection} "${value}"`)
+    seen.add(value)
+  }
+}
+
+export function parseBlueprint(value: unknown): BunderstackBlueprint {
+  const blueprint = blueprintSchema.parse(value) as BunderstackBlueprint
+  rejectDuplicates('database physical table', blueprint.resources.database.tables.map((entry) => entry.physicalName))
+  rejectDuplicates('database export table', blueprint.resources.database.tables.map((entry) => entry.exportName))
+  rejectDuplicates('storage bucket', blueprint.resources.storage.buckets.map((entry) => entry.name))
+  rejectDuplicates('environment key', blueprint.environment.map((entry) => entry.key))
+  rejectDuplicates('background job', blueprint.background.jobs.map((entry) => entry.name))
+  rejectDuplicates('background cron', blueprint.background.cron.map((entry) => entry.name))
+  rejectDuplicates('background maintenance', blueprint.background.maintenance.map((entry) => entry.name))
+  if (!blueprint.resources.storage.buckets.some((bucket) => bucket.name === blueprint.resources.storage.defaultBucket)) {
+    throw new Error('[bunderstack] storage defaultBucket must be declared in storage buckets')
+  }
+  const workerRequired = blueprint.background.jobs.length > 0
+  if (blueprint.background.worker.required !== workerRequired) {
+    throw new Error('[bunderstack] background worker.required must match declared queue jobs')
+  }
+  if (Boolean(blueprint.application.scripts.worker) !== workerRequired) {
+    throw new Error('[bunderstack] application worker script must match declared queue jobs')
+  }
+  return blueprint
+}
+
+export function blueprintFromManifest(args: {
+  manifest: BunderstackManifest
+  generatorVersion: string
+  entry: string
+  migrationMode: MigrationMode
+}): BunderstackBlueprint {
+  const workerRequired = args.manifest.background.jobs.length > 0
+  return parseBlueprint({
+    version: 1,
+    generator: { name: 'bunderstack', version: args.generatorVersion },
+    application: {
+      framework: 'tanstack-start',
+      scripts: { build: 'build', start: 'start', ...(workerRequired ? { worker: 'worker' } : {}) },
+    },
+    bunderstack: { entry: args.entry, manifestVersion: 3 },
+    resources: {
+      database: {
+        ...args.manifest.database,
+        migrationMode: args.migrationMode,
+        tables: sortBy(args.manifest.database.tables, (entry) => entry.physicalName),
+      },
+      storage: {
+        ...args.manifest.storage,
+        buckets: sortBy(args.manifest.storage.buckets, (entry) => entry.name),
+      },
+      ...(args.manifest.realtime.required ? { realtime: { required: true } } : {}),
+    },
+    environment: sortBy(args.manifest.environment, (entry) => entry.key),
+    background: {
+      worker: { required: workerRequired },
+      jobs: sortBy(args.manifest.background.jobs, (entry) => entry.name),
+      cron: sortBy(args.manifest.background.cron, (entry) => entry.name),
+      maintenance: sortBy(args.manifest.background.maintenance, (entry) => entry.name),
+    },
+  })
+}
+
+export function parseBlueprintYaml(source: string): BunderstackBlueprint {
+  return parseBlueprint(parse(source) as unknown)
+}
+
+export function serializeBlueprint(value: BunderstackBlueprint): string {
+  const blueprint = parseBlueprint(value)
+  const options = {
+    aliasDuplicateObjects: false,
+    defaultKeyType: 'PLAIN',
+    defaultStringType: 'PLAIN',
+    lineWidth: 0,
+  } as const
+  const source = stringify(parseBlueprintYaml(stringify(blueprint, options)), options)
+  return source.replace(/^(\s*schedule: )(.+)$/gm, (_match, prefix: string, value: string) => {
+    const schedule = value.startsWith('"') ? JSON.parse(value) : value
+    return `${prefix}${JSON.stringify(schedule)}`
+  })
+}

package/src/cli.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+import {
+  BlueprintCheckError,
+  generateBlueprint,
+  type GenerateBlueprintOptions,
+} from './blueprint-generator'
+
+export type CliIo = {
+  stdout(message: string): void
+  stderr(message: string): void
+}
+
+const help = `Usage: bunderstack blueprint [directory] [--entry <path>] [--output <path>] [--check]
+
+Generate a committed deployment declaration for a TanStack Start application.
+Entry precedence: --entry, package.json#bunderstack.entry, src/bunderstack.ts.`
+
+export async function runCli(
+  args: string[],
+  io: CliIo,
+  generate: typeof generateBlueprint = generateBlueprint,
+): Promise<number> {
+  if (args[0] === '--help' || args[0] === '-h') {
+    io.stdout(help)
+    return 0
+  }
+  if (args[0] === '--version') {
+    io.stdout((await Bun.file(new URL('../package.json', import.meta.url)).json() as { version: string }).version)
+    return 0
+  }
+  if (args[0] !== 'blueprint') {
+    io.stderr('Usage: bunderstack blueprint [directory] [--entry <path>] [--output <path>] [--check]')
+    return 2
+  }
+  const options: GenerateBlueprintOptions = { directory: process.cwd() }
+  for (let index = 1; index < args.length; index++) {
+    const argument = args[index]!
+    if (argument === '--check') {
+      options.check = true
+      continue
+    }
+    if (argument === '--entry' || argument === '--output') {
+      const value = args[++index]
+      if (!value || value.startsWith('--')) {
+        io.stderr(`[bunderstack] missing value for ${argument}`)
+        return 2
+      }
+      if (argument === '--entry') options.entry = value
+      else options.output = value
+      continue
+    }
+    if (argument.startsWith('-')) {
+      io.stderr(`[bunderstack] unknown option: ${argument}`)
+      return 2
+    }
+    if (options.directory !== process.cwd()) {
+      io.stderr('[bunderstack] only one application directory is allowed')
+      return 2
+    }
+    options.directory = argument
+  }
+  try {
+    const result = await generate(options)
+    io.stdout(
+      options.check || !result.changed
+        ? 'bunderstack.blueprint.yaml is current'
+        : 'Generated bunderstack.blueprint.yaml',
+    )
+    return 0
+  } catch (error) {
+    io.stderr(error instanceof Error ? error.message : String(error))
+    return error instanceof BlueprintCheckError ? 1 : 1
+  }
+}
+
+if (import.meta.main) {
+  const exitCode = await runCli(process.argv.slice(2), {
+    stdout: (message) => console.log(message),
+    stderr: (message) => console.error(message),
+  })
+  process.exit(exitCode)
+}

package/src/index.ts

@@ -58,7 +58,7 @@ import {
 import { createRealtimeBroker, buildRealtimeRouter } from './realtime/index'
 import { createRedisRealtimeBroker } from './realtime/redis'
 import { deleteFileWithDerivatives } from './storage/delete'
-import { deleteFileMetaRow } from './storage/file-meta'
+import { deleteFileMetaRow, insertReadyFile } from './storage/file-meta'
 import { createBucketStorages } from './storage/registry'
 import { buildBucketStorageRouter } from './storage/router'
 import { sweepOrphans } from './storage/sweep'
@@ -115,6 +115,17 @@ export interface StorageFacade {
     key: string,
     opts?: { bucket?: string; expiresIn?: number },
   ): Promise<string>
+  /**
+   * Upload bytes as a ready file and register it in file_meta so it is
+   * accessible via `GET /api/files/<key>`. Use this for server-generated
+   * files (e.g. generated PDFs) that are not uploaded by end-users.
+   */
+  upload(
+    key: string,
+    body: ArrayBuffer | Uint8Array,
+    contentType: string,
+    opts?: { ownerId?: string; filename?: string },
+  ): Promise<void>
 }
 
 export type AppStartWorkerOptions = Omit<StartWorkerOptions, 'tick'>
@@ -487,6 +498,23 @@ export async function createBunderstack<
         }
         return `/api/files/${key}`
       },
+      async upload(key, body, contentType, opts = {}) {
+        const bucketName = key.split('/')[0] ?? ''
+        const adapter = registry.get(bucketName)?.adapter
+        if (!adapter) throw new Error(`Unknown bucket: ${bucketName}`)
+        const u8 = body instanceof Uint8Array ? body : new Uint8Array(body)
+        const buf: ArrayBuffer = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength) as ArrayBuffer
+        await adapter.upload(key, buf, contentType)
+        await insertReadyFile(db, {
+          fileId: key,
+          bucket: bucketName,
+          ownerId: opts.ownerId ?? null,
+          scopeJson: null,
+          filename: opts.filename ?? key.split('/').at(-1) ?? null,
+          contentType,
+          size: buf.byteLength,
+        })
+      },
     }
     const jobRunner = jobsDefs
       ? createJobRunner({
@@ -513,6 +541,9 @@ export async function createBunderstack<
     const startWorker = async (
       options: AppStartWorkerOptions = {},
     ): Promise<WorkerHandle> => {
+      if (introspect) {
+        return { closed: Promise.resolve(), close: async () => {} }
+      }
       if (!jobRunner) {
         throw new Error('[bunderstack] no queue jobs configured')
       }
@@ -534,6 +565,9 @@ export async function createBunderstack<
     const startCronScheduler = async (
       options: AppStartCronSchedulerOptions = {},
     ): Promise<LocalCronScheduler> => {
+      if (introspect) {
+        return { tick: async () => {}, close: async () => {} }
+      }
       const cron = Object.entries(jobsDefs ?? {}).flatMap(
         ([name, definition]) =>
           definition.kind === 'cron'
@@ -573,6 +607,7 @@ export async function createBunderstack<
     const runWorker = async (
       options: AppRunWorkerOptions = {},
     ): Promise<void> => {
+      if (introspect) return
       if (
         realtime.transport === 'memory' &&
         !options.allowProcessLocalRealtime
@@ -670,10 +705,11 @@ export async function createBunderstack<
       manifest: buildManifest({
         schema: options.schema,
         dialect,
+        migrationsDirectory: config.database.migrations,
         storage: config.storage,
         envConfig: options.env as EnvConfigInput | undefined,
+        emailProvider: emailProviderTag(options.email),
         realtime: Boolean(config.realtime),
-        realtimeTransport: configuredRealtimeTransport,
         jobs: jobsDefs,
       }),
     }
@@ -714,7 +750,7 @@ export type {
 } from './config'
 export { validateEnv, createClientEnv, BunderstackEnvError } from './env'
 export type { EnvConfigInput, BaseEnv, ValidatedEnv } from './env'
-export { buildManifest } from './manifest'
+export { buildManifest, parseManifest } from './manifest'
 export type { BunderstackManifest, ManifestEnvVar } from './manifest'
 export { createEmail } from './email'
 export type {

package/src/manifest.ts

@@ -1,103 +1,256 @@
-// 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 { getTableName, isTable } from 'drizzle-orm'
+import { z, type ZodType } from 'zod'
 
 import type { Dialect } from './dialect'
 import type { EnvConfigInput } from './env'
 import type { JobsDefs } from './jobs/define'
-import type { RealtimeTransport } from './realtime/facade'
 import type { ResolvedBucket, ResolvedStorageBuckets } from './storage/buckets'
+import { parseCron } from './jobs/cron'
 import {
   bunderstackCronRuns,
   bunderstackFiles,
+  bunderstackIdempotency,
   bunderstackJobs,
 } from './internal-tables'
 
-export type ManifestEnvVar = { key: string; required: boolean }
+export type ManifestEnvVar = {
+  key: string
+  required: boolean
+  scope: 'server' | 'client'
+}
+
 export type BunderstackManifest = {
-  version: 2
-  dialect: Dialect
-  tables: string[]
-  tableMap: Record<string, string>
-  systemTables: {
-    jobs: string
-    files: string
-    scheduledRuns: string
+  version: 3
+  database: {
+    dialect: Dialect
+    migrationsDirectory: string
+    tables: { exportName: string; physicalName: string; system: boolean }[]
   }
-  defaultBucket: string
-  buckets: { name: string; visibility: ResolvedBucket['visibility'] }[]
-  realtime: boolean
-  realtimeTransport: RealtimeTransport
-  env: { server: ManifestEnvVar[]; client: ManifestEnvVar[] }
+  storage: {
+    defaultBucket: string
+    buckets: { name: string; visibility: ResolvedBucket['visibility'] }[]
+  }
+  realtime: { required: boolean }
+  environment: ManifestEnvVar[]
   background: {
     jobs: { name: string }[]
     cron: { name: string; schedule: string; timezone: 'UTC' }[]
-    maintenance: { name: 'storage-sweep'; schedule: string }[]
+    maintenance: {
+      name: 'storage-sweep'
+      schedule: string
+      timezone: 'UTC'
+    }[]
   }
 }
 
-function describeTables(schema: Record<string, unknown>): Record<string, string> {
-  return Object.fromEntries(
-    Object.entries(schema).flatMap(([key, value]) =>
-      isTable(value) ? [[key, getTableName(value)]] : [],
+const nonEmpty = z.string().min(1)
+const migrationDirectory = nonEmpty.refine(
+  (value) =>
+    value.startsWith('/') ||
+    (!value.includes('\\') && value.split('/').every((part) => part !== '..' && part !== '')),
+  { message: 'migrationsDirectory must be an absolute path or a relative path without traversal' },
+)
+const cronSchedule = nonEmpty.refine(
+  (value) => {
+    try {
+      parseCron(value)
+      return true
+    } catch {
+      return false
+    }
+  },
+  { message: 'invalid cron schedule' },
+)
+
+const manifestSchema = z
+  .object({
+    version: z.literal(3),
+    database: z
+      .object({
+        dialect: z.enum(['sqlite', 'pg']),
+        migrationsDirectory: migrationDirectory,
+        tables: z.array(
+          z
+            .object({
+              exportName: nonEmpty,
+              physicalName: nonEmpty,
+              system: z.boolean(),
+            })
+            .strict(),
+        ),
+      })
+      .strict(),
+    storage: z
+      .object({
+        defaultBucket: nonEmpty,
+        buckets: z.array(
+          z
+            .object({ name: nonEmpty, visibility: z.enum(['public', 'private']) })
+            .strict(),
+        ),
+      })
+      .strict(),
+    realtime: z.object({ required: z.boolean() }).strict(),
+    environment: z.array(
+      z
+        .object({
+          key: nonEmpty,
+          required: z.boolean(),
+          scope: z.enum(['server', 'client']),
+        })
+        .strict(),
     ),
+    background: z
+      .object({
+        jobs: z.array(z.object({ name: nonEmpty }).strict()),
+        cron: z.array(
+          z
+            .object({
+              name: nonEmpty,
+              schedule: cronSchedule,
+              timezone: z.literal('UTC'),
+            })
+            .strict(),
+        ),
+        maintenance: z.array(
+          z
+            .object({
+              name: z.literal('storage-sweep'),
+              schedule: cronSchedule,
+              timezone: z.literal('UTC'),
+            })
+            .strict(),
+        ),
+      })
+      .strict(),
+  })
+  .strict()
+
+function sortBy<T>(entries: readonly T[], key: (entry: T) => string): T[] {
+  return [...entries].sort((left, right) => key(left).localeCompare(key(right)))
+}
+
+function rejectDuplicates(collection: string, values: readonly string[]): void {
+  const seen = new Set<string>()
+  for (const value of values) {
+    if (seen.has(value)) throw new Error(`[bunderstack] duplicate ${collection} "${value}"`)
+    seen.add(value)
+  }
+}
+
+function describeTables(schema: Record<string, unknown>) {
+  const systemNames = new Set<string>(systemTables().map((table) => table.physicalName))
+  return sortBy(
+    Object.entries(schema).flatMap(([exportName, value]) =>
+      isTable(value) && !systemNames.has(getTableName(value))
+        ? [{ exportName, physicalName: getTableName(value), system: false }]
+        : [],
+    ),
+    (entry) => entry.physicalName,
   )
 }
 
 function describeSection(
   section: Record<string, ZodType> | undefined,
+  scope: ManifestEnvVar['scope'],
 ): ManifestEnvVar[] {
   return Object.entries(section ?? {}).map(([key, schema]) => ({
     key,
     required: !schema.safeParse(undefined).success,
+    scope,
   }))
 }
 
+function systemTables() {
+  return [
+    { exportName: '_system.files', physicalName: getTableName(bunderstackFiles), system: true },
+    {
+      exportName: '_system.idempotency',
+      physicalName: getTableName(bunderstackIdempotency),
+      system: true,
+    },
+    { exportName: '_system.jobs', physicalName: getTableName(bunderstackJobs), system: true },
+    {
+      exportName: '_system.scheduledRuns',
+      physicalName: getTableName(bunderstackCronRuns),
+      system: true,
+    },
+  ]
+}
+
+export function parseManifest(value: unknown): BunderstackManifest {
+  const manifest = manifestSchema.parse(value) as BunderstackManifest
+  rejectDuplicates('database physical table', manifest.database.tables.map((entry) => entry.physicalName))
+  rejectDuplicates('database export table', manifest.database.tables.map((entry) => entry.exportName))
+  rejectDuplicates('storage bucket', manifest.storage.buckets.map((entry) => entry.name))
+  rejectDuplicates('environment key', manifest.environment.map((entry) => entry.key))
+  rejectDuplicates('background job', manifest.background.jobs.map((entry) => entry.name))
+  rejectDuplicates('background cron', manifest.background.cron.map((entry) => entry.name))
+  rejectDuplicates('background maintenance', manifest.background.maintenance.map((entry) => entry.name))
+  return manifest
+}
+
 export function buildManifest(args: {
   schema: Record<string, unknown>
   dialect: Dialect
+  migrationsDirectory: string
   storage: ResolvedStorageBuckets
   envConfig: EnvConfigInput | undefined
+  emailProvider: string | undefined
   realtime: boolean
-  realtimeTransport: RealtimeTransport
   jobs: JobsDefs | undefined
 }): BunderstackManifest {
-  return {
-    version: 2,
-    dialect: args.dialect,
-    tables: Object.keys(args.schema),
-    tableMap: describeTables(args.schema),
-    systemTables: {
-      jobs: getTableName(bunderstackJobs),
-      files: getTableName(bunderstackFiles),
-      scheduledRuns: getTableName(bunderstackCronRuns),
+  const environment = [
+    ...describeSection(args.envConfig?.server, 'server'),
+    ...describeSection(args.envConfig?.client, 'client'),
+    ...(args.emailProvider === 'resend'
+      ? [{ key: 'RESEND_API_KEY', required: true, scope: 'server' as const }]
+      : []),
+    ...(args.emailProvider === 'smtp'
+      ? [{ key: 'SMTP_URL', required: true, scope: 'server' as const }]
+      : []),
+  ]
+  rejectDuplicates('environment key', environment.map((entry) => entry.key))
+
+  return parseManifest({
+    version: 3,
+    database: {
+      dialect: args.dialect,
+      migrationsDirectory: args.migrationsDirectory,
+      tables: sortBy([...systemTables(), ...describeTables(args.schema)], (entry) => entry.physicalName),
     },
-    defaultBucket: args.storage.defaultBucket,
-    buckets: [...args.storage.buckets.values()].map((bucket) => ({
-      name: bucket.name,
-      visibility: bucket.visibility,
-    })),
-    realtime: args.realtime,
-    realtimeTransport: args.realtimeTransport,
-    env: {
-      server: describeSection(args.envConfig?.server),
-      client: describeSection(args.envConfig?.client),
+    storage: {
+      defaultBucket: args.storage.defaultBucket,
+      buckets: sortBy(
+        [...args.storage.buckets.values()].map((bucket) => ({
+          name: bucket.name,
+          visibility: bucket.visibility,
+        })),
+        (bucket) => bucket.name,
+      ),
     },
+    realtime: { required: args.realtime },
+    environment: sortBy(environment, (entry) => entry.key),
     background: {
-      jobs: Object.entries(args.jobs ?? {})
-        .filter(([, def]) => def.kind === 'job')
-        .map(([name]) => ({ name })),
-      cron: Object.entries(args.jobs ?? {})
-        .filter(([, def]) => def.kind === 'cron')
-        .map(([name, def]) => ({
-          name,
-          schedule: def.kind === 'cron' ? def.schedule : '',
-          timezone: 'UTC' as const,
-        })),
-      maintenance: [{ name: 'storage-sweep', schedule: '0 4 * * *' }],
+      jobs: sortBy(
+        Object.entries(args.jobs ?? {})
+          .filter(([, def]) => def.kind === 'job')
+          .map(([name]) => ({ name })),
+        (entry) => entry.name,
+      ),
+      cron: sortBy(
+        Object.entries(args.jobs ?? {})
+          .filter(([, def]) => def.kind === 'cron')
+          .map(([name, def]) => ({
+            name,
+            schedule: def.kind === 'cron' ? def.schedule : '',
+            timezone: 'UTC' as const,
+          })),
+        (entry) => entry.name,
+      ),
+      maintenance: [
+        { name: 'storage-sweep', schedule: '0 4 * * *', timezone: 'UTC' as const },
+      ],
     },
-  }
+  })
 }

package/src/provision.ts

@@ -105,6 +105,8 @@ export async function provision(
   app: object,
   options?: { force?: boolean },
 ): Promise<void> {
+  if (process.env.BUNDERSTACK_INTROSPECT === '1') return
+
   const internals = (app as WithProvisionInternals)[PROVISION_INTERNALS]
   if (!internals) {
     throw new Error(

package/src/storage/router.ts

@@ -371,14 +371,16 @@ export function buildBucketStorageRouter(
     return c.json({ fileId, url }, 200)
   })
 
-  // ─── GET /:bucket/:id ─────────────────────────────────────────────────────
-  router.get('/:bucket/:id', async (c) => {
+  // ─── GET /:bucket/* ──────────────────────────────────────────────────────
+  // NOTE: wildcard captures nested paths like `adaptations/uuid/resume.pdf`.
+  router.get('/:bucket/*', async (c) => {
     const bucketName = c.req.param('bucket')
     const entry = registry.get(bucketName)
     if (!entry) return apiError(c, ErrorCode.NOT_FOUND, 'Unknown bucket', 404)
     const { bucket, adapter } = entry
 
-    const id = c.req.param('id')
+    const mountPrefix = c.req.routePath.replace(/\/:[^\/]+\/\*$/, '')
+    const id = c.req.path.slice(`${mountPrefix}/${bucketName}/`.length)
     const fileId = `${bucketName}/${id}`
 
     const row = await getFileMeta(db, fileId)
@@ -467,14 +469,15 @@ export function buildBucketStorageRouter(
     return new Response(res.body, { status: res.status, headers })
   })
 
-  // ─── DELETE /:bucket/:id ──────────────────────────────────────────────────
-  router.delete('/:bucket/:id', async (c) => {
+  // ─── DELETE /:bucket/* ─────────────────────────────────────────────────
+  router.delete('/:bucket/*', async (c) => {
     const bucketName = c.req.param('bucket')
     const entry = registry.get(bucketName)
     if (!entry) return apiError(c, ErrorCode.NOT_FOUND, 'Unknown bucket', 404)
     const { bucket, adapter } = entry
 
-    const id = c.req.param('id')
+    const mountPrefix = c.req.routePath.replace(/\/:[^/]+\/\*$/, '')
+    const id = c.req.path.slice(`${mountPrefix}/${bucketName}/`.length)
     const fileId = `${bucketName}/${id}`
 
     const row = await getFileMeta(db, fileId)