nucleus-core-ts 0.9.994 → 0.10.0

package/README.md

@@ -0,0 +1,177 @@
+# nucleus-core-ts
+
+A TypeScript framework for multi-tenant APIs on Bun: authentication and
+authorization, entity CRUD generated from a config file, storage, payments,
+chat, pub/sub, monitoring — and a typed client generated from the same
+declarations the server serves.
+
+```bash
+bunx nucleus-core-ts init
+```
+
+## Where the documentation is
+
+This file is an index, not a manual. The maintained documentation is:
+
+- **`.claude/skills/`** — 21 skills, one per subsystem (`nucleus-authentication`,
+  `nucleus-entities`, `nucleus-payment`, …). These are the reference.
+- **`public/`** — the docs site shipped in the package.
+- **`src/types.ts`** — the configuration surface, and the last word when a
+  document and the code disagree.
+
+Other `.md` files in the repo are working notes or historical audit records.
+`docs/` in particular is an archive: it records what was true when it was
+written and is not updated.
+
+## Entry points
+
+| import | what |
+|---|---|
+| `nucleus-core-ts` | the server plugin and the services it lends a host app |
+| `nucleus-core-ts/client` | the generated, typed API client |
+| `nucleus-core-ts/fe` | React components (auth pages, admin panels) |
+| `nucleus-core-ts/proxy` | server-side proxy client |
+
+`client`, `fe` and `proxy` are independent of the HTTP layer below.
+
+## The HTTP layer is ours
+
+The server half used to run on [Elysia](https://elysiajs.com). It does not any
+more, and not partially: there is no adapter, no swagger plugin, no static
+plugin, no peer dependency, no import anywhere in the source, and nothing in
+`node_modules`. The reason was never performance — nucleus-core is a product of
+its own, and a product's HTTP layer, type system and public API shape should not
+belong to a third project we do not control.
+
+**What that means, concretely:**
+
+- **One entry point.** `createNucleusServer({ config, port })` serves the whole
+  product on `Bun.serve`. `NucleusElysiaPlugin` is gone; a consumer that used it
+  changes its boot line and its route modules and keeps everything else.
+
+- **A host brings its own routes.** This is what took longest and it is what
+  every consumer was blocked on:
+
+  ```ts
+  await createNucleusServer({
+    config: { options, schema, relations },
+    port: 3000,
+    routes: [{ prefix: '/reports', routes: [defineRoute({ … })] }],
+    onRequest: (ctx) => Response | undefined,  // BEFORE the inbound guard and auth
+    socket: defineWebSocketRoute({ … }),
+    onStop: [async () => { /* close your pool */ }],
+  })
+  ```
+
+  A group's routes sit behind nucleus's auth, exactly as they did when mounted on
+  an Elysia carrying the plugin — that is the inherited contract. Something that
+  must answer without authentication goes in `onRequest`, which runs first: a
+  public webhook that needs a verbatim body, an anonymous share link.
+
+- **"No Elysia" is measured, not asserted.** `noFrameworkGraph.test.ts` checks it
+  two ways that miss different things: every entry point is bundled with packages
+  left external and must contain no `from "elysia"`, and every source file plus
+  the manifest is scanned, because a dynamic import never reaches a bundle.
+
+- **The suites that compared two servers now state one.** With no second arm to
+  agree with, "the two answer alike" became "this is the answer" — and the claims
+  got stronger doing it, from 53 tests and 189 assertions to 74 and 422. Parity
+  passed whenever both arms were wrong in the same way; an absolute cannot.
+
+- `src/Server/` holds the replacement — response semantics, `defineRoute`, the
+  router, the WebSocket upgrade — and every route in the repo declares against
+  it. See the `nucleus-routing` skill for how to declare one.
+
+- The work, its measurements and its open questions live in
+  [`ELYSIA_MIGRATION.md`](./ELYSIA_MIGRATION.md). Read that before touching the
+  server's HTTP edge.
+
+**What the migration found.** Twenty defects that existed in the shipped product
+and that no test caught. Seventeen came from making the two paths answer the same
+question; the last three came from removing Elysia from the TESTS, which moved
+~58 suites off Elysia's routing and validation and onto the router that actually
+serves them. The ones worth naming:
+
+| | |
+|---|---|
+| login sent ONE cookie | `access_token` and `refresh_token` never reached the browser |
+| the 3-D Secure callback was dead | `Body already used` since the bridge landed |
+| a resumable upload wrote nothing | `application/octet-stream` bodies arrived as `undefined`, so the chunk was appended as nothing and the request answered success |
+| auth ran AFTER validation | an unauthenticated caller was handed the schema of a protected endpoint — property names, types, and the sample the validator builds |
+| a thrown handler *or guard* leaked | Bun's `DevErrorPage` carried the raw error text where the product answers a JSON envelope whose whole job is withholding it |
+| 422s and 404s shipped bare | no `nosniff`, no HSTS, no `x-frame-options`, no request id — on 151 routes |
+| `stop()` leaked and killed | the DB pool, Redis and a live interval survived every restart, and in-flight requests were cut where Elysia drains them |
+| monitoring was blind | the request log, the collector and the live store recorded nothing on the Bun path |
+| form bodies were not parsed | `application/x-www-form-urlencoded` fell through every branch |
+| schema `default:` never applied | a defaulted field left out became a 422; so did an extra property, an absent optional body, and a malformed one |
+| nested form keys stayed flat | `a.b=1` arrived as a key called `a.b`, so `body.a.b` found nothing |
+| a WebSocket upgrade skipped the guards | no rate limit, no tenant resolution, no header strip |
+
+Two of those were the OTHER way round, with the SHIPPED path broken and the
+replacement correct: multipart uploads never worked on Elysia at all, and a
+failed insert came back from it as `500 text/plain` carrying the schema name,
+the table name and every column, because Elysia discarded the `Response` the
+product's error responder returned. Both are gone with the path that had them.
+
+**And three found by taking Elysia out of the tests** — all of them live on the
+only path that remains, all now fixed:
+
+| | |
+|---|---|
+| the 422 handed the caller their own submitted values | `POST /login` with a bad email answered `"password": "hunter2-the-real-one"` — into the response, and into any log that records one. Every value in a refusal is its TYPE now. The parity walk could not see it: it sends an empty body, so `found` was always `{}` |
+| a malformed body on a route with NO body schema | reached the handler as `undefined` and 500'd where the handler dereferenced it. 69 of 134 write declarations carry no body schema and 36 read the body anyway — a client error was becoming a server error. Now a 400 |
+| a JSON body claimed to be `text/plain` | seventeen returned-`Error` sites, including the whole authentication middleware. Copied from Elysia so the two arms agreed byte for byte; with Elysia gone the only argument for it went too |
+
+`ELYSIA_MIGRATION.md` §11 has the rest, including the four audit claims that did
+NOT reproduce when measured, and one regression this work introduced and then
+removed.
+
+Breaking changes will be announced here first. There is no 1.0 date; the 0.9.x
+line continues.
+
+## Gates
+
+Every push runs, and all of these block:
+
+```bash
+bun test src scripts fe                   # unit tests
+bunx tsc --noEmit -p tsconfig.check.json  # the core library must type-check clean
+```
+
+**The lint gate is currently not one of them.** CI runs `bunx biome check .`,
+and `biome` on npm is not Biome — it is an unrelated 0.3.3 package for managing
+environment variables. `@biomejs/biome` is the real one and is not declared as a
+dependency, so the step resolves the wrong package, prints no findings and exits
+0. It passes on every commit and checks nothing. Locally it works only for
+whoever has Biome installed globally.
+
+Repairing it means declaring `@biomejs/biome`, pointing CI at it, and then
+making the repo clean under the real tool — which is a repo-wide change, so it
+is written down here rather than done quietly. See `ELYSIA_MIGRATION.md` §7.
+
+**What that costs, measured** (`bunx @biomejs/biome check .`, 1144 files):
+
+| | count |
+|---|---|
+| errors today | 234 |
+| fixed by `--write` | 90, touching 83 files |
+| left needing a judgement call | 144 errors + 29 warnings + 9 infos |
+
+The biggest groups are `assist/source/organizeImports` (33) and
+`lint/suspicious/noThenProperty` (12 — mostly chainable drizzle stubs in tests,
+where a `then` property is the point). So the repair is two commits, not one: a
+mechanical `--write` pass, then a smaller pass that decides what to keep.
+
+CI additionally runs every `*.integration.test.ts` against a real Postgres and
+Redis (`RUN_INTEGRATION=1`); they self-skip otherwise, because the races they
+catch — over-commit, non-atomic payout
+bookkeeping — cannot be reproduced against a fake backend.
+
+`tsconfig.check.json` covers `src` only — `fe/` imports from the package root,
+which only exists after a build, so it cannot be type-checked on a fresh
+checkout. The build emits its declarations best-effort.
+
+A local green is not a CI green. Path separators, case sensitivity, musl memory
+behaviour and `/proc` fixtures all differ between a developer machine and the
+Alpine image that runs in production; `ELYSIA_MIGRATION.md` §6 has the matrix
+and the container command that reproduces it.

package/bin/cli.ts

@@ -14,24 +14,26 @@
 import { spawn } from 'node:child_process'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { banner, c, log } from './lib/ui'
+import { addCommand } from './lib/commands/add'
+import { devCommand } from './lib/commands/dev'
 import { doctorCommand } from './lib/commands/doctor'
-import { validateCommand } from './lib/commands/validate'
 import { initCommand } from './lib/commands/init'
-import { devCommand } from './lib/commands/dev'
-import { addCommand } from './lib/commands/add'
+import { validateCommand } from './lib/commands/validate'
+import { banner, c, log } from './lib/ui'
 
 const here = dirname(fileURLToPath(import.meta.url))
 const rootDir = join(here, '..')
 
 const argv = process.argv.slice(2)
 const firstArg = argv[0] ?? ''
-const looksLikeFile = firstArg.endsWith('.json') || firstArg.startsWith('./') || firstArg.startsWith('/')
+const looksLikeFile =
+  firstArg.endsWith('.json') || firstArg.startsWith('./') || firstArg.startsWith('/')
 const command = looksLikeFile ? 'generate' : firstArg
 
 async function pkgVersion(): Promise<string> {
   try {
-    return (JSON.parse(await Bun.file(join(rootDir, 'package.json')).text()) as { version: string }).version
+    return (JSON.parse(await Bun.file(join(rootDir, 'package.json')).text()) as { version: string })
+      .version
   } catch {
     return '?'
   }
@@ -63,7 +65,10 @@ ${c.dim('init = preset → runnable backend · scaffold (= new) = full project
 
 function runScript(scriptRelPath: string, args: string[]): Promise<never> {
   return new Promise<never>(() => {
-    const proc = spawn('bun', ['run', join(rootDir, scriptRelPath), ...args], { cwd: process.cwd(), stdio: 'inherit' })
+    const proc = spawn('bun', ['run', join(rootDir, scriptRelPath), ...args], {
+      cwd: process.cwd(),
+      stdio: 'inherit',
+    })
     proc.on('close', (code) => process.exit(code ?? 1))
   })
 }

package/bin/lib/commands/add.ts

@@ -10,13 +10,13 @@
  * After editing, it re-validates and (for schema-affecting changes) regenerates
  * the Drizzle schema so `nucleus dev` picks the change up.
  */
-import { dirname, join, relative } from 'node:path'
+
 import { spawnSync } from 'node:child_process'
-import { c, fail, info, log, ok, step, warn } from '../ui'
-import { prompts } from '../ui'
-import { buildEntity, slug } from '../config-builder'
-import { findConfigPath, crossFieldChecks } from './validate'
+import { dirname, join, relative } from 'node:path'
+import { buildEntity } from '../config-builder'
 import { loadConfigSchema, validateAgainstSchema } from '../schema'
+import { c, fail, info, log, ok, prompts, step, warn } from '../ui'
+import { crossFieldChecks, findConfigPath } from './validate'
 
 type Cfg = Record<string, unknown>
 
@@ -77,8 +77,13 @@ const FEATURES: Record<string, { summary: string; apply: (cfg: Cfg) => void | Pr
         const provider = await p.choose('  Provider', ['iyzico', 'stripe'], 0)
         const block: Cfg = { enabled: true, provider }
         if (provider === 'iyzico')
-          block.iyzico = { apiKey: 'IYZICO_API_KEY', secretKey: 'IYZICO_SECRET_KEY', baseUrl: 'IYZICO_BASE_URL' }
-        else block.stripe = { secretKey: 'STRIPE_SECRET_KEY', webhookSecret: 'STRIPE_WEBHOOK_SECRET' }
+          block.iyzico = {
+            apiKey: 'IYZICO_API_KEY',
+            secretKey: 'IYZICO_SECRET_KEY',
+            baseUrl: 'IYZICO_BASE_URL',
+          }
+        else
+          block.stripe = { secretKey: 'STRIPE_SECRET_KEY', webhookSecret: 'STRIPE_WEBHOOK_SECRET' }
         cfg.payment = block
       } finally {
         p.close()
@@ -113,7 +118,7 @@ async function persist(path: string, cfg: Cfg, regen: boolean): Promise<number>
     fail('Change would make the config invalid — nothing written')
     return 1
   }
-  await Bun.write(path, JSON.stringify(cfg, null, 2) + '\n')
+  await Bun.write(path, `${JSON.stringify(cfg, null, 2)}\n`)
   ok(`Updated ${c.cyan(relative(process.cwd(), path))}`)
 
   if (regen) {
@@ -168,7 +173,8 @@ async function addFeature(name?: string): Promise<number> {
   if (!key || !FEATURES[key]) {
     fail(`Unknown feature "${name ?? ''}"`)
     log(`  Available features:`)
-    for (const [k, v] of Object.entries(FEATURES)) log(`    ${c.cyan(k.padEnd(14))} ${c.dim(v.summary)}`)
+    for (const [k, v] of Object.entries(FEATURES))
+      log(`    ${c.cyan(k.padEnd(14))} ${c.dim(v.summary)}`)
     return 1
   }
   const loaded = await readConfig()
@@ -188,7 +194,9 @@ async function addFeature(name?: string): Promise<number> {
 async function addOauth(provider?: string): Promise<number> {
   const prov = (provider || '').toLowerCase()
   if (!prov || !OAUTH_PROVIDERS.includes(prov)) {
-    fail(`Unknown OAuth provider "${provider ?? ''}" — expected one of ${OAUTH_PROVIDERS.join(', ')}`)
+    fail(
+      `Unknown OAuth provider "${provider ?? ''}" — expected one of ${OAUTH_PROVIDERS.join(', ')}`
+    )
     return 1
   }
   const loaded = await readConfig()
@@ -210,7 +218,8 @@ async function addOauth(provider?: string): Promise<number> {
   cfg.authentication = auth
   step(`Adding OAuth provider: ${c.cyan(prov)}`)
   const rc = await persist(path, cfg, false)
-  if (rc === 0) info(`Set ${up}_CLIENT_ID and ${up}_CLIENT_SECRET in .env, plus the provider redirect URI.`)
+  if (rc === 0)
+    info(`Set ${up}_CLIENT_ID and ${up}_CLIENT_SECRET in .env, plus the provider redirect URI.`)
   return rc
 }
 
@@ -227,9 +236,13 @@ export async function addCommand(args: string[]): Promise<number> {
     default:
       fail(`Unknown: nucleus add ${thing ?? ''}`)
       log(`  Usage:`)
-      log(`    ${c.cyan('nucleus add entity')}            ${c.dim('add one or more entities (interactive)')}`)
+      log(
+        `    ${c.cyan('nucleus add entity')}            ${c.dim('add one or more entities (interactive)')}`
+      )
       log(`    ${c.cyan('nucleus add feature <name>')}    ${c.dim('enable a feature block')}`)
-      log(`    ${c.cyan('nucleus add oauth <provider>')}  ${c.dim(`add OAuth (${OAUTH_PROVIDERS.join('|')})`)}`)
+      log(
+        `    ${c.cyan('nucleus add oauth <provider>')}  ${c.dim(`add OAuth (${OAUTH_PROVIDERS.join('|')})`)}`
+      )
       return 1
   }
 }

package/bin/lib/commands/dev.ts

@@ -10,15 +10,22 @@
  * If your Postgres/Redis are already running (the common local case) `dev up`
  * detects them and starts nothing — Docker is only a fallback.
  */
-import { existsSync } from 'node:fs'
+
 import { spawnSync } from 'node:child_process'
-import { c, fail, info, log, ok, step, warn } from '../ui'
+import { existsSync } from 'node:fs'
 import { pgConn, readEnv, redisConn, tcpReachable } from '../env'
+import { c, fail, info, log, ok, step, warn } from '../ui'
 
 const PG_CONTAINER = 'nucleus-dev-postgres'
 const REDIS_CONTAINER = 'nucleus-dev-redis'
 
-type Svc = { name: string; container: string; host: string; port: number; run: (port: number) => string[] }
+type Svc = {
+  name: string
+  container: string
+  host: string
+  port: number
+  run: (port: number) => string[]
+}
 
 function services(env: Record<string, string>): Svc[] {
   const pg = pgConn(env)
@@ -30,11 +37,18 @@ function services(env: Record<string, string>): Svc[] {
       host: pg.host,
       port: pg.port,
       run: (port) => [
-        'run', '-d', '--name', PG_CONTAINER,
-        '-e', 'POSTGRES_PASSWORD=postgres',
-        '-e', 'POSTGRES_USER=postgres',
-        '-e', 'POSTGRES_DB=nucleus',
-        '-p', `${port}:5432`,
+        'run',
+        '-d',
+        '--name',
+        PG_CONTAINER,
+        '-e',
+        'POSTGRES_PASSWORD=postgres',
+        '-e',
+        'POSTGRES_USER=postgres',
+        '-e',
+        'POSTGRES_DB=nucleus',
+        '-p',
+        `${port}:5432`,
         'postgres:16-alpine',
       ],
     },
@@ -43,7 +57,15 @@ function services(env: Record<string, string>): Svc[] {
       container: REDIS_CONTAINER,
       host: r.host,
       port: r.port,
-      run: (port) => ['run', '-d', '--name', REDIS_CONTAINER, '-p', `${port}:6379`, 'redis:7-alpine'],
+      run: (port) => [
+        'run',
+        '-d',
+        '--name',
+        REDIS_CONTAINER,
+        '-p',
+        `${port}:6379`,
+        'redis:7-alpine',
+      ],
     },
   ]
 }
@@ -68,7 +90,9 @@ async function devUp(): Promise<number> {
     if (await tcpReachable(s.host, s.port)) {
       ok(`${s.name} already reachable at ${c.dim(`${s.host}:${s.port}`)}`)
     } else if (!isLocal(s.host)) {
-      fail(`${s.name} not reachable at ${s.host}:${s.port} (remote host — can't start a container for it)`)
+      fail(
+        `${s.name} not reachable at ${s.host}:${s.port} (remote host — can't start a container for it)`
+      )
       return 1
     } else {
       need.push(s)
@@ -82,13 +106,17 @@ async function devUp(): Promise<number> {
   }
 
   if (!Bun.which('docker')) {
-    fail(`docker not found — install Docker, or start ${need.map((s) => s.name).join(' + ')} yourself`)
+    fail(
+      `docker not found — install Docker, or start ${need.map((s) => s.name).join(' + ')} yourself`
+    )
     return 1
   }
 
   for (const s of need) {
     // Reuse a stopped container of the same name if present, else create one.
-    const existing = spawnSync('docker', ['ps', '-aq', '-f', `name=^${s.container}$`], { encoding: 'utf-8' })
+    const existing = spawnSync('docker', ['ps', '-aq', '-f', `name=^${s.container}$`], {
+      encoding: 'utf-8',
+    })
     const id = (existing.stdout || '').trim()
     if (id) {
       info(`Starting existing container ${c.dim(s.container)}`)
@@ -105,14 +133,18 @@ async function devUp(): Promise<number> {
 
   step('Waiting for datastores to accept connections')
   for (const s of need) {
-    if (await waitReachable(s.host, s.port)) ok(`${s.name} ready at ${c.dim(`${s.host}:${s.port}`)}`)
+    if (await waitReachable(s.host, s.port))
+      ok(`${s.name} ready at ${c.dim(`${s.host}:${s.port}`)}`)
     else {
       fail(`${s.name} did not become reachable — check \`docker logs ${s.container}\``)
       return 1
     }
   }
   log()
-  ok(c.green('Datastores up.') + c.dim(' Run `nucleus dev` to start the app, `nucleus dev down` to stop them.'))
+  ok(
+    c.green('Datastores up.') +
+      c.dim(' Run `nucleus dev` to start the app, `nucleus dev down` to stop them.')
+  )
   return 0
 }
 
@@ -124,7 +156,9 @@ function devDown(): number {
   }
   let stopped = 0
   for (const container of [PG_CONTAINER, REDIS_CONTAINER]) {
-    const found = spawnSync('docker', ['ps', '-aq', '-f', `name=^${container}$`], { encoding: 'utf-8' })
+    const found = spawnSync('docker', ['ps', '-aq', '-f', `name=^${container}$`], {
+      encoding: 'utf-8',
+    })
     if ((found.stdout || '').trim()) {
       spawnSync('docker', ['rm', '-f', container], { stdio: 'ignore' })
       ok(`Removed ${c.dim(container)}`)
@@ -144,14 +178,19 @@ async function devRun(): Promise<number> {
   const env = readEnv()
   for (const s of services(env)) {
     if (!(await tcpReachable(s.host, s.port)))
-      warn(`${s.name} not reachable at ${s.host}:${s.port} — run \`nucleus dev up\` first (the app may fail to boot)`)
+      warn(
+        `${s.name} not reachable at ${s.host}:${s.port} — run \`nucleus dev up\` first (the app may fail to boot)`
+      )
   }
 
   // Prefer the project's own dev script; fall back to running the entrypoint.
   let cmd = ['bun', 'run', 'dev']
   try {
-    const pkg = JSON.parse(await Bun.file('package.json').text()) as { scripts?: Record<string, string> }
-    if (!pkg.scripts?.dev) cmd = ['bun', '--watch', existsSync('src/index.ts') ? 'src/index.ts' : 'index.ts']
+    const pkg = JSON.parse(await Bun.file('package.json').text()) as {
+      scripts?: Record<string, string>
+    }
+    if (!pkg.scripts?.dev)
+      cmd = ['bun', '--watch', existsSync('src/index.ts') ? 'src/index.ts' : 'index.ts']
   } catch {
     /* use default */
   }

package/bin/lib/commands/doctor.ts

@@ -4,10 +4,11 @@
  * config. Prints a green/red checklist with fix hints. Exit 1 if a REQUIRED
  * check fails.
  */
-import { c, fail, info, log, ok, step, warn } from '../ui'
+
 import { pgConn, readEnv, redisConn, tcpReachable } from '../env'
-import { collectEnvRefs, crossFieldChecks, findConfigPath } from './validate'
 import { loadConfigSchema, validateAgainstSchema } from '../schema'
+import { c, fail, info, log, ok, step, warn } from '../ui'
+import { collectEnvRefs, crossFieldChecks, findConfigPath } from './validate'
 
 export async function doctorCommand(): Promise<number> {
   step('Nucleus doctor — local environment check')
@@ -24,9 +25,12 @@ export async function doctorCommand(): Promise<number> {
 
   // Postgres
   const pg = pgConn(env)
-  if (await tcpReachable(pg.host, pg.port)) ok(`Postgres reachable at ${c.dim(`${pg.host}:${pg.port}`)}`)
+  if (await tcpReachable(pg.host, pg.port))
+    ok(`Postgres reachable at ${c.dim(`${pg.host}:${pg.port}`)}`)
   else {
-    fail(`Postgres NOT reachable at ${pg.host}:${pg.port} — start it (\`nucleus dev up\`) or set DATABASE_URL`)
+    fail(
+      `Postgres NOT reachable at ${pg.host}:${pg.port} — start it (\`nucleus dev up\`) or set DATABASE_URL`
+    )
     requiredFailures++
   }
 
@@ -34,13 +38,19 @@ export async function doctorCommand(): Promise<number> {
   const r = redisConn(env)
   if (await tcpReachable(r.host, r.port)) ok(`Redis reachable at ${c.dim(`${r.host}:${r.port}`)}`)
   else {
-    fail(`Redis NOT reachable at ${r.host}:${r.port} — start it (\`nucleus dev up\`) or set REDIS_URL / REDIS_HOST`)
+    fail(
+      `Redis NOT reachable at ${r.host}:${r.port} — start it (\`nucleus dev up\`) or set REDIS_URL / REDIS_HOST`
+    )
     requiredFailures++
   }
 
   // Optional tooling
-  Bun.which('docker') ? ok(`docker ${c.dim('(for nucleus dev up)')}`) : warn('docker not found — needed only for `nucleus dev up`')
-  Bun.which('dapr') ? ok(`dapr ${c.dim('(optional pub/sub sidecar)')}`) : info('dapr not found (optional — only for Dapr pub/sub)')
+  Bun.which('docker')
+    ? ok(`docker ${c.dim('(for nucleus dev up)')}`)
+    : warn('docker not found — needed only for `nucleus dev up`')
+  Bun.which('dapr')
+    ? ok(`dapr ${c.dim('(optional pub/sub sidecar)')}`)
+    : info('dapr not found (optional — only for Dapr pub/sub)')
   Bun.which('createdb')
     ? ok(`createdb ${c.dim('(for nucleus db create)')}`)
     : info('createdb not found (optional — psql client tools)')
@@ -59,7 +69,8 @@ export async function doctorCommand(): Promise<number> {
         requiredFailures++
       }
       const missing = [...collectEnvRefs(cfg)].filter((e) => !env[e])
-      if (missing.length) warn(`${missing.length} referenced env var(s) unset: ${c.dim(missing.join(', '))}`)
+      if (missing.length)
+        warn(`${missing.length} referenced env var(s) unset: ${c.dim(missing.join(', '))}`)
     } catch {
       fail(`Config ${cfgPath} is not valid JSON`)
       requiredFailures++
@@ -73,6 +84,8 @@ export async function doctorCommand(): Promise<number> {
     ok(c.green(c.bold('Environment ready ✔')))
     return 0
   }
-  fail(c.red(c.bold(`${requiredFailures} blocking issue(s) — fix the above before running the app`)))
+  fail(
+    c.red(c.bold(`${requiredFailures} blocking issue(s) — fix the above before running the app`))
+  )
   return 1
 }

package/bin/lib/commands/init.ts

@@ -15,14 +15,21 @@
 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 { buildPreset, PRESET_NAMES, type PresetName } from '../presets'
+import { loadConfigSchema, validateAgainstSchema } from '../schema'
 import { writeBackend } from '../templates'
+import { banner, c, fail, info, log, ok, prompts, step, warn } from '../ui'
 import { crossFieldChecks } from './validate'
-import { loadConfigSchema, validateAgainstSchema } from '../schema'
 
-type Flags = { preset?: string; config?: string; appId?: string; output?: string; yes: boolean; install: boolean }
+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 }
@@ -38,7 +45,12 @@ function parseFlags(args: string[]): Flags {
   return f
 }
 
-const slug = (s: string) => s.toLowerCase().replace(/[^a-z0-9_-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '')
+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)
@@ -56,7 +68,8 @@ export async function initCommand(args: string[]): Promise<number> {
     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
+    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)}`)
@@ -98,7 +111,8 @@ export async function initCommand(args: string[]): Promise<number> {
   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 (missing.length)
+    warn(`.env has ${missing.length} secret(s) to fill: ${c.dim(missing.join(', '))}`)
 
   if (f.install) {
     step('Installing dependencies')
@@ -108,12 +122,17 @@ export async function initCommand(args: string[]): Promise<number> {
     } 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',
-      })
+      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')
+      else
+        warn('schema generation skipped/failed — run `bun run generate` after setting DATABASE_URL')
     }
   }