nucleus-core-ts 0.9.744 → 0.9.746

package/bin/lib/commands/init.ts

@@ -0,0 +1,128 @@
+/**
+ * `nucleus init` — the front door. Build a config (from a preset, an existing
+ * file, or the interactive builder), scaffold a runnable Bun/Elysia backend,
+ * install deps and generate the Drizzle schema — so a new service boots in one
+ * command.
+ *
+ * Flags:
+ *   --preset <minimal|api|saas|marketplace>   non-interactive: seed from a preset
+ *   --config <path>                           use an existing config.json (no builder)
+ *   --app-id <id>                             app id (else prompted / from config)
+ *   --output, -o <dir>                        target dir (default ./<appId>)
+ *   --yes, -y                                 no prompts (defaults to the saas preset)
+ *   --no-install                              skip bun install + generate
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { banner, c, fail, info, log, ok, prompts, step, warn } from '../ui'
+import { buildPreset, PRESET_NAMES, type PresetName } from '../presets'
+import { buildConfigInteractive } from '../config-builder'
+import { writeBackend } from '../templates'
+import { crossFieldChecks } from './validate'
+import { loadConfigSchema, validateAgainstSchema } from '../schema'
+
+type Flags = { preset?: string; config?: string; appId?: string; output?: string; yes: boolean; install: boolean }
+
+function parseFlags(args: string[]): Flags {
+  const f: Flags = { yes: false, install: true }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--preset') f.preset = args[++i]
+    else if (a === '--config') f.config = args[++i]
+    else if (a === '--app-id') f.appId = args[++i]
+    else if (a === '--output' || a === '-o') f.output = args[++i]
+    else if (a === '--yes' || a === '-y') f.yes = true
+    else if (a === '--no-install') f.install = false
+  }
+  return f
+}
+
+const slug = (s: string) => s.toLowerCase().replace(/[^a-z0-9_-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '')
+
+export async function initCommand(args: string[]): Promise<number> {
+  const f = parseFlags(args)
+  const version = 'nucleus init'
+  banner(version, 'scaffold a runnable Nucleus backend')
+
+  let config: Record<string, unknown>
+  let appId: string
+
+  if (f.config) {
+    // Use an existing config (skip the builder).
+    const path = resolve(f.config)
+    if (!existsSync(path)) return fail(`Config not found: ${f.config}`), 1
+    config = JSON.parse(await Bun.file(path).text()) as Record<string, unknown>
+    appId = slug((config.appId as string) || f.appId || 'my-app')
+  } else if (f.preset || f.yes) {
+    const name = (f.preset || 'saas') as PresetName
+    if (!PRESET_NAMES.includes(name)) return fail(`Unknown preset "${name}" (choose ${PRESET_NAMES.join(', ')})`), 1
+    appId = slug(f.appId || 'my-app')
+    config = buildPreset(name, appId)
+    step(`Seeded a "${name}" config for ${c.cyan(appId)}`)
+  } else {
+    // Interactive.
+    const p = prompts()
+    try {
+      config = await buildConfigInteractive(p)
+      appId = slug((config.appId as string) || 'my-app')
+    } finally {
+      p.close()
+    }
+  }
+
+  // Validate before writing anything.
+  step('Validating config')
+  const res = validateAgainstSchema(config, await loadConfigSchema())
+  const cross = crossFieldChecks(config)
+  for (const e of [...res.errors, ...cross]) fail(`${c.bold(e.path || '(root)')} — ${e.message}`)
+  if (res.errors.length + cross.length > 0) {
+    fail('Config is invalid — aborting.')
+    return 1
+  }
+  ok('Config is valid')
+
+  // Resolve + guard the output directory.
+  const outDir = resolve(f.output || appId)
+  if (existsSync(outDir) && readdirSync(outDir).length > 0) {
+    if (f.yes || f.preset || f.config) {
+      warn(`Output dir not empty: ${outDir} — writing into it anyway (--yes/non-interactive)`)
+    } else {
+      const p = prompts()
+      const cont = await p.confirm(`Directory ${outDir} is not empty. Continue?`, false)
+      p.close()
+      if (!cont) return log('\nAborted.'), 0
+    }
+  }
+
+  step(`Generating backend at ${c.cyan(outDir)}`)
+  const missing = writeBackend(outDir, appId, config)
+  ok('package.json, src/index.ts, src/config.json, tsconfig, .env written')
+  if (missing.length) warn(`.env has ${missing.length} secret(s) to fill: ${c.dim(missing.join(', '))}`)
+
+  if (f.install) {
+    step('Installing dependencies')
+    const inst = spawnSync('bun', ['install'], { cwd: outDir, stdio: 'inherit' })
+    if (inst.status !== 0) {
+      fail('bun install failed — fix and re-run `bun install` in the project')
+    } else {
+      ok('dependencies installed')
+      step('Generating Drizzle schema')
+      const gen = spawnSync('bunx', ['nucleus-core-ts', 'generate', 'src/config.json', 'src/drizzle'], {
+        cwd: outDir,
+        stdio: 'inherit',
+      })
+      if (gen.status === 0) ok('schema generated')
+      else warn('schema generation skipped/failed — run `bun run generate` after setting DATABASE_URL')
+    }
+  }
+
+  log()
+  ok(c.green(c.bold('Project ready')))
+  info(`Next:`)
+  log(`  ${c.cyan(`cd ${f.output || appId}`)}`)
+  if (!f.install) log(`  ${c.cyan('bun install && bun run generate')}`)
+  log(`  ${c.cyan('nucleus doctor')}   ${c.dim('# verify Postgres/Redis are up')}`)
+  log(`  ${c.cyan('bun run dev')}      ${c.dim('# http://localhost:4000/docs')}`)
+  return 0
+}

package/bin/lib/commands/validate.ts

@@ -0,0 +1,113 @@
+/**
+ * `nucleus validate [config.json]` — validate a Nucleus config against the
+ * generated JSON-Schema, plus cross-field rules the schema can't express and an
+ * env-var reference report. Exit code 1 on any error (CI-friendly).
+ */
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { c, fail, info, log, ok, step, warn } from '../ui'
+import { loadConfigSchema, validateAgainstSchema, type ValidationIssue } from '../schema'
+
+const CANDIDATES = ['src/config.json', 'config.json', 'src/config.nucleus.json']
+
+export function findConfigPath(arg?: string): string | null {
+  if (arg) return existsSync(resolve(arg)) ? resolve(arg) : null
+  for (const cand of CANDIDATES) if (existsSync(resolve(cand))) return resolve(cand)
+  return null
+}
+
+type AnyRec = Record<string, unknown>
+const isOn = (s: unknown): boolean => typeof s === 'object' && s !== null && (s as AnyRec).enabled === true
+
+/** Rules the JSON-Schema can't express (conditional dependencies between keys). */
+export function crossFieldChecks(cfg: AnyRec): ValidationIssue[] {
+  const issues: ValidationIssue[] = []
+  const add = (path: string, message: string) => issues.push({ path, message })
+
+  // Genuinely-required top-level keys (no runtime default).
+  if (!cfg.appId || typeof cfg.appId !== 'string') add('appId', 'is required (a unique, stable app id)')
+  const db = cfg.database as AnyRec | undefined
+  if (!db || !db.url) add('database.url', 'is required (connection string or env-var name)')
+
+  const auth = cfg.authentication as AnyRec | undefined
+  if (auth?.enabled) {
+    if (!auth.mode) add('authentication.mode', 'set "full" (IDP) or "consumer" (resource server)')
+    if (auth.mode === 'consumer' && isOn(cfg.authorization) && !auth.idpUrl)
+      add('authentication.idpUrl', 'consumer mode with authorization needs idpUrl for /auth/check')
+  }
+  if (!Array.isArray(cfg.entities) || (cfg.entities as unknown[]).length === 0)
+    add('entities', 'no entities — no CRUD endpoints will be generated')
+
+  const payment = cfg.payment as AnyRec | undefined
+  if (payment?.enabled) {
+    if (!payment.provider) add('payment.provider', 'required ("iyzico" or "stripe") when payment.enabled')
+    else if (!payment[payment.provider as string]) add(`payment.${payment.provider}`, 'provider config block is missing')
+  }
+
+  const notif = cfg.notification as AnyRec | undefined
+  const channels = notif?.channels as AnyRec | undefined
+  if (notif?.enabled && channels) {
+    const tg = channels.telegram as AnyRec | undefined
+    if (isOn(tg) && (!tg?.botToken || !tg?.chatId)) add('notification.channels.telegram', 'enabled but botToken/chatId missing')
+    const wh = channels.webhook as AnyRec | undefined
+    if (isOn(wh) && !wh?.url) add('notification.channels.webhook', 'enabled but url missing')
+    if (channels.email === true && !cfg.email) add('notification.channels.email', 'enabled but no config.email provider set')
+  }
+
+  const chat = cfg.chat as AnyRec | undefined
+  const storage = cfg.storage as AnyRec | undefined
+  if (isOn(chat) && isOn((chat as AnyRec)?.attachments) && !(isOn(storage) && isOn((storage as AnyRec)?.cdn)))
+    add('chat.attachments', 'requires storage.enabled and storage.cdn.enabled')
+
+  return issues
+}
+
+const ENV_RE = /^[A-Z][A-Z0-9_]{2,}$/
+const ENV_SKIP = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'TOGGLE', 'VERIFICATION', 'OPTIONS', 'HEAD'])
+const ENV_SKIP_KEYS = new Set(['entities', 'externalEntities', 'seed'])
+
+export function collectEnvRefs(v: unknown, found = new Set<string>()): Set<string> {
+  if (typeof v === 'string') {
+    if (ENV_RE.test(v) && !ENV_SKIP.has(v)) found.add(v)
+  } else if (Array.isArray(v)) for (const i of v) collectEnvRefs(i, found)
+  else if (typeof v === 'object' && v !== null)
+    for (const [k, val] of Object.entries(v)) if (!ENV_SKIP_KEYS.has(k)) collectEnvRefs(val, found)
+  return found
+}
+
+export async function validateCommand(args: string[]): Promise<number> {
+  const path = findConfigPath(args[0])
+  if (!path) {
+    fail(args[0] ? `Config not found: ${args[0]}` : `No config found (looked for ${CANDIDATES.join(', ')})`)
+    return 1
+  }
+  step(`Validating ${c.cyan(path)}`)
+
+  let cfg: AnyRec
+  try {
+    cfg = JSON.parse(await Bun.file(path).text()) as AnyRec
+  } catch (e) {
+    fail(`Invalid JSON: ${e instanceof Error ? e.message : String(e)}`)
+    return 1
+  }
+
+  const schema = await loadConfigSchema()
+  const res = validateAgainstSchema(cfg, schema)
+  const cross = crossFieldChecks(cfg)
+
+  for (const e of res.errors) fail(`${c.bold(e.path || '(root)')} — ${e.message}`)
+  for (const e of cross) fail(`${c.bold(e.path)} — ${e.message}`)
+  for (const w of res.warnings) warn(`${c.bold(w.path)} — ${w.message}`)
+
+  const envRefs = [...collectEnvRefs(cfg)].sort()
+  if (envRefs.length) info(`${envRefs.length} env var(s) referenced: ${c.dim(envRefs.join(', '))}`)
+
+  const errCount = res.errors.length + cross.length
+  log()
+  if (errCount === 0) {
+    ok(`${c.green(c.bold('Valid'))} — ${res.warnings.length} warning(s)`)
+    return 0
+  }
+  fail(`${c.red(c.bold(`${errCount} error(s)`))}, ${res.warnings.length} warning(s)`)
+  return 1
+}

package/bin/lib/config-builder.ts

@@ -0,0 +1,66 @@
+/**
+ * Interactive config builder for `nucleus init` (TTY). Starts from a preset,
+ * then optionally layers on entities via a column-by-column entity builder.
+ * Returns a NucleusConfigOptions object ready to write to config.json.
+ */
+import { c, info, log, ok, step } from './ui'
+import type { prompts as promptsFactory } from './ui'
+import { buildPreset, PRESET_NAMES, PRESET_SUMMARY, type PresetName } from './presets'
+
+type P = ReturnType<typeof promptsFactory>
+type Cfg = Record<string, unknown>
+
+const COLUMN_TYPES = ['varchar', 'text', 'integer', 'numeric', 'boolean', 'timestamp', 'uuid', 'json', 'jsonb']
+
+export function slug(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9_]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '')
+}
+
+export async function buildEntity(p: P): Promise<Cfg | null> {
+  const name = slug(await p.ask('  Table name (snake_case, blank to finish)'))
+  if (!name) return null
+  const columns: Cfg[] = []
+  log(`    ${c.dim('Add columns (blank name to finish):')}`)
+  while (true) {
+    const cname = slug(await p.ask('    · column name'))
+    if (!cname) break
+    const type = await p.choose(`      type of "${cname}"`, COLUMN_TYPES, 0)
+    const notNull = await p.confirm('      required (NOT NULL)?', false)
+    const col: Cfg = { name: cname, type }
+    if (notNull) col.notNull = true
+    columns.push(col)
+  }
+  if (columns.length === 0) columns.push({ name: 'name', type: 'varchar', length: 200, notNull: true })
+  const isPublic = await p.confirm('    make GET public (readable without auth)?', false)
+  const bulk = await p.confirm('    enable bulk endpoints?', false)
+  const entity: Cfg = { table_name: name, add_base_columns: true, columns }
+  if (isPublic) entity.is_public = { GET: true }
+  if (bulk) entity.bulk_endpoints_enabled = true
+  return entity
+}
+
+export async function buildConfigInteractive(p: P): Promise<Cfg> {
+  step('Build your config')
+  const appId = slug((await p.askRequired('App id (unique, stable — e.g. shop-api)')) || 'my-app')
+
+  log(`\n  ${c.bold('Start from a preset:')}`)
+  for (const name of PRESET_NAMES) log(`    ${c.cyan(name)} — ${c.dim(PRESET_SUMMARY[name])}`)
+  const preset = (await p.choose('\n  Preset', [...PRESET_NAMES], 2)) as PresetName
+
+  const cfg = buildPreset(preset, appId)
+  ok(`Seeded a "${preset}" config`)
+
+  if (await p.confirm('\n  Replace the example entity with your own?', false)) {
+    const entities: Cfg[] = []
+    let e = await buildEntity(p)
+    while (e) {
+      entities.push(e)
+      ok(`Added entity "${(e as { table_name: string }).table_name}"`)
+      e = await buildEntity(p)
+    }
+    if (entities.length > 0) cfg.entities = entities
+  }
+
+  info(`Deeper options: edit config.json after — the $schema ref gives editor autocomplete for every key.`)
+  return cfg
+}

package/bin/lib/env.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared local-environment helpers for the CLI: read a project .env, parse a
+ * host:port, and TCP-probe reachability. Used by `doctor` and `dev`.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+/** Read a project .env (KEY=VALUE) merged over process.env. */
+export function readEnv(cwd = process.cwd()): Record<string, string> {
+  const env: Record<string, string> = { ...(process.env as Record<string, string>) }
+  const envPath = resolve(cwd, '.env')
+  if (existsSync(envPath)) {
+    try {
+      for (const line of readFileSync(envPath, 'utf-8').split('\n')) {
+        const m = line.match(/^\s*([A-Z][A-Z0-9_]*)\s*=\s*(.*)\s*$/)
+        if (m?.[1]) env[m[1]] = (m[2] ?? '').replace(/^["']|["']$/g, '')
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  return env
+}
+
+export function hostPort(url: string | undefined, defHost: string, defPort: number): { host: string; port: number } {
+  if (!url) return { host: defHost, port: defPort }
+  try {
+    const u = new URL(url)
+    return { host: u.hostname || defHost, port: u.port ? Number(u.port) : defPort }
+  } catch {
+    return { host: defHost, port: defPort }
+  }
+}
+
+export async function tcpReachable(hostname: string, port: number, timeoutMs = 1500): Promise<boolean> {
+  return new Promise((res) => {
+    let done = false
+    const finish = (v: boolean) => {
+      if (!done) {
+        done = true
+        res(v)
+      }
+    }
+    const t = setTimeout(() => finish(false), timeoutMs)
+    Bun.connect({
+      hostname,
+      port,
+      socket: {
+        data() {},
+        open(sock) {
+          clearTimeout(t)
+          sock.end()
+          finish(true)
+        },
+        error() {
+          clearTimeout(t)
+          finish(false)
+        },
+        connectError() {
+          clearTimeout(t)
+          finish(false)
+        },
+      },
+    }).catch(() => {
+      clearTimeout(t)
+      finish(false)
+    })
+  })
+}
+
+/** Resolve Postgres + Redis host/port from a project's env. */
+export function pgConn(env: Record<string, string>) {
+  return hostPort(env.DATABASE_URL, 'localhost', 5432)
+}
+export function redisConn(env: Record<string, string>) {
+  return hostPort(env.REDIS_URL, env.REDIS_HOST || 'localhost', Number(env.REDIS_PORT) || 6379)
+}

package/bin/lib/presets.ts

@@ -0,0 +1,120 @@
+/**
+ * Starter config presets for `nucleus init --preset <name>`. Each returns a
+ * complete, schema-valid NucleusConfigOptions object (as a plain record) for a
+ * given appId — a sensible, runnable starting point the user then refines.
+ * Secrets are env-var NAMES (resolved at boot), never literals.
+ */
+export type PresetName = 'minimal' | 'api' | 'saas' | 'marketplace'
+export const PRESET_NAMES: PresetName[] = ['minimal', 'api', 'saas', 'marketplace']
+
+type Cfg = Record<string, unknown>
+
+const exampleEntity = {
+  table_name: 'products',
+  add_base_columns: true,
+  bulk_endpoints_enabled: true,
+  is_public: { GET: true },
+  columns: [
+    { name: 'title', type: 'varchar', length: 200, notNull: true },
+    { name: 'description', type: 'text' },
+    { name: 'price', type: 'numeric', precision: 10, scale: 2 },
+    { name: 'in_stock', type: 'boolean', default: true },
+  ],
+}
+
+function base(appId: string, mode: 'development' | 'production'): Cfg {
+  return {
+    $schema: './config.nucleus.json',
+    appId,
+    mode,
+    database: { url: 'DATABASE_URL' },
+    redis: { host: 'REDIS_HOST', port: 'REDIS_PORT', withDapr: false },
+    logging: { level: mode === 'development' ? 'debug' : 'info' },
+    entities: [exampleEntity],
+  }
+}
+
+const fullAuth = () => ({
+  enabled: true,
+  mode: 'full',
+  defaultRole: 'basic',
+  accessToken: { secret: 'ACCESS_TOKEN_SECRET', expiresIn: '15m' },
+  refreshToken: { secret: 'REFRESH_TOKEN_SECRET', expiresIn: '30d' },
+  sessionToken: { secret: 'SESSION_TOKEN_SECRET' },
+  login: { enabled: true },
+  register: { enabled: true, createProfileOnRegister: true },
+  logout: { enabled: true },
+  refresh: { enabled: true },
+  passwordReset: { enabled: true },
+})
+
+export function buildPreset(name: PresetName, appId: string): Cfg {
+  switch (name) {
+    case 'minimal':
+      return { ...base(appId, 'development'), authentication: { enabled: false } }
+
+    case 'api':
+      return {
+        ...base(appId, 'production'),
+        authentication: { enabled: true, mode: 'consumer', idpUrl: 'IDP_URL' },
+        authorization: { enabled: true, autoSeedClaims: true },
+        rateLimit: { enabled: true, strategy: 'sliding-window' },
+        monitoring: { enabled: true },
+      }
+
+    case 'saas':
+      return {
+        ...base(appId, 'production'),
+        database: { url: 'DATABASE_URL', isMultiTenant: true, tenantResolution: 'subdomain' },
+        authentication: {
+          ...fullAuth(),
+          register: {
+            enabled: true,
+            createProfileOnRegister: true,
+            emailVerification: { enabled: true },
+          },
+          sessions: { maxActiveSessions: 5, notifyOnNewDevice: true },
+        },
+        authorization: { enabled: true, autoSeedClaims: true },
+        email: { provider: 'gmail', gmail: { json_file_path: 'GMAIL_SA_JSON', from_email: 'FROM_EMAIL', from_name: appId } },
+        storage: {
+          enabled: true,
+          maxFileSizeBytes: 10485760,
+          cdn: { enabled: true, cacheMaxAge: 86400 },
+        },
+        notification: { enabled: true, channels: { portal: true, email: true } },
+        monitoring: { enabled: true },
+        audit: { enabled: true },
+        rateLimit: { enabled: true, strategy: 'sliding-window' },
+      }
+
+    case 'marketplace': {
+      const saas = buildPreset('saas', appId)
+      return {
+        ...saas,
+        payment: {
+          enabled: true,
+          provider: 'stripe',
+          defaultCurrency: 'usd',
+          threeDSecureEnabled: true,
+          savedMethodsEnabled: true,
+          subMerchantsEnabled: true,
+          stripe: { secretKey: 'STRIPE_SECRET_KEY', webhookSecret: 'STRIPE_WEBHOOK_SECRET' },
+          marketplace: {
+            defaultSettlementDelayDays: 7,
+            reserveRate: 0.1,
+            minimumPayoutAmount: 1000,
+            defaultCurrency: 'usd',
+          },
+        },
+      }
+    }
+  }
+}
+
+export const PRESET_SUMMARY: Record<PresetName, string> = {
+  minimal: 'auth off, 1 example entity — the smallest runnable API',
+  api: 'consumer-mode (resource server) + authorization + rate-limit + monitoring',
+  saas: 'full auth (login/register/email-verify) + multi-tenant + email + storage/CDN + notifications + audit',
+  marketplace: 'the SaaS stack + Stripe payments & the marketplace money layer (splits/reserves/payouts)',
+}

package/bin/lib/schema.ts

@@ -0,0 +1,119 @@
+/**
+ * Loads the generated Nucleus config JSON-Schema (`schemas/config.nucleus.json`,
+ * produced from `NucleusConfigOptions`) and validates a config object against it.
+ *
+ * A deliberately small, dependency-free validator covering the subset the
+ * generated schema actually uses: type, enum, required, properties, items,
+ * $ref (to #/$defs|#/definitions), and oneOf/anyOf. Unknown properties are NOT
+ * treated as errors (the framework tolerates forward-compatible extra keys), but
+ * they are collected as warnings so typos surface.
+ */
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+// bin/lib -> package root
+export const SCHEMA_PATH = join(here, '..', '..', 'schemas', 'config.nucleus.json')
+
+export type JsonSchema = Record<string, unknown>
+export type ValidationIssue = { path: string; message: string }
+export type ValidationResult = { valid: boolean; errors: ValidationIssue[]; warnings: ValidationIssue[] }
+
+export async function loadConfigSchema(): Promise<JsonSchema> {
+  const raw = await Bun.file(SCHEMA_PATH).text()
+  return JSON.parse(raw) as JsonSchema
+}
+
+const typeOf = (v: unknown): string => {
+  if (v === null) return 'null'
+  if (Array.isArray(v)) return 'array'
+  return typeof v // string | number | boolean | object
+}
+
+const matchesType = (v: unknown, t: string): boolean => {
+  if (t === 'integer') return typeof v === 'number' && Number.isInteger(v)
+  if (t === 'number') return typeof v === 'number'
+  return typeOf(v) === t
+}
+
+function resolveRef(root: JsonSchema, ref: string): JsonSchema | null {
+  if (!ref.startsWith('#/')) return null
+  let node: unknown = root
+  for (const part of ref.slice(2).split('/')) {
+    node = (node as Record<string, unknown>)?.[decodeURIComponent(part)]
+    if (node == null) return null
+  }
+  return node as JsonSchema
+}
+
+function validateNode(
+  value: unknown,
+  schema: JsonSchema,
+  root: JsonSchema,
+  path: string,
+  out: ValidationResult
+): void {
+  if (typeof schema.$ref === 'string') {
+    const resolved = resolveRef(root, schema.$ref)
+    if (resolved) return validateNode(value, resolved, root, path, out)
+    return
+  }
+
+  // oneOf / anyOf — pass if any branch validates cleanly.
+  for (const key of ['oneOf', 'anyOf'] as const) {
+    const branches = schema[key] as JsonSchema[] | undefined
+    if (Array.isArray(branches)) {
+      const anyValid = branches.some((b) => {
+        const probe: ValidationResult = { valid: true, errors: [], warnings: [] }
+        validateNode(value, b, root, path, probe)
+        return probe.errors.length === 0
+      })
+      if (!anyValid) out.errors.push({ path, message: `does not match any allowed ${key} variant` })
+      return
+    }
+  }
+
+  const types = schema.type
+  if (types !== undefined) {
+    const list = Array.isArray(types) ? (types as string[]) : [types as string]
+    if (!list.some((t) => matchesType(value, t))) {
+      out.errors.push({ path, message: `expected ${list.join(' | ')}, got ${typeOf(value)}` })
+      return // wrong type — deeper checks would be noise
+    }
+  }
+
+  if (Array.isArray(schema.enum) && !schema.enum.some((e) => e === value)) {
+    out.errors.push({ path, message: `must be one of ${schema.enum.map((e) => JSON.stringify(e)).join(', ')}` })
+  }
+
+  if (typeOf(value) === 'object') {
+    const obj = value as Record<string, unknown>
+    const props = (schema.properties as Record<string, JsonSchema>) ?? {}
+    for (const req of (schema.required as string[]) ?? []) {
+      // The generated schema marks every non-optional TS field `required`, but
+      // most nucleus config fields have RUNTIME defaults — so a missing "required"
+      // field is a hint (the runtime fills it), not an error. Genuinely-critical
+      // requireds (appId, database, entities, conditional feature keys) are
+      // enforced as errors by the cross-field checks instead.
+      if (!(req in obj)) out.warnings.push({ path: path ? `${path}.${req}` : req, message: 'not set (uses the runtime default)' })
+    }
+    for (const [k, v] of Object.entries(obj)) {
+      const childPath = path ? `${path}.${k}` : k
+      if (props[k]) validateNode(v, props[k], root, childPath, out)
+      else if (schema.additionalProperties === false)
+        out.warnings.push({ path: childPath, message: 'unknown property (not in schema)' })
+    }
+  }
+
+  if (typeOf(value) === 'array' && schema.items) {
+    const itemSchema = schema.items as JsonSchema
+    ;(value as unknown[]).forEach((item, i) => validateNode(item, itemSchema, root, `${path}[${i}]`, out))
+  }
+}
+
+export function validateAgainstSchema(config: unknown, schema: JsonSchema): ValidationResult {
+  const out: ValidationResult = { valid: true, errors: [], warnings: [] }
+  validateNode(config, schema, schema, '', out)
+  out.valid = out.errors.length === 0
+  return out
+}