nucleus-core-ts 0.9.993 → 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

@@ -1,131 +1,136 @@
-#!/usr/bin/env bun
-
-/**
- * Nucleus CLI — the single front door to nucleus-core-ts.
- *
- *   nucleus init          scaffold a new project (interactive)
- *   nucleus dev …         run locally (up | down | run)
- *   nucleus add …         extend an existing project (entity | feature | oauth)
- *   nucleus validate      validate config.json against the schema
- *   nucleus doctor        check the local environment (bun, postgres, redis, …)
- *   nucleus generate      generate the Drizzle schema from config.json
- */
-
-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 { 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'
-
-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 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
-  } catch {
-    return '?'
-  }
-}
-
-function showHelp(version: string) {
-  banner(`Nucleus CLI  v${version}`, 'nucleus-core-ts — config-driven backend framework')
-  log(`
-${c.bold('Usage')}  ${c.cyan('nucleus')} ${c.dim('<command> [options]')}
-
-${c.bold('Create & evolve')}
-  ${c.cyan('init')} ${c.dim('[--preset <p>] [-o <dir>] [-y]')}       build a config + scaffold a runnable backend (zero-to-running)
-  ${c.cyan('add')} ${c.dim('entity | feature <n> | oauth <p>')}    extend this project's config in place (+ regenerate)
-  ${c.cyan('scaffold')}                               full-project scaffold (backend+frontend+k8s+pipelines) from a config.json
-  ${c.cyan('generate')} ${c.dim('<config.json> <outDir>')}           generate the Drizzle schema + relations from config
-  ${c.cyan('validate')} ${c.dim('[config.json]')}                    validate a config against the JSON-Schema + cross-field rules
-
-${c.bold('Local dev')}
-  ${c.cyan('dev')} ${c.dim('[up | down]')}                          run the app; ${c.dim('up')} starts Postgres+Redis, ${c.dim('down')} stops them
-  ${c.cyan('doctor')}                                 check the local environment can run a Nucleus project
-
-${c.bold('Maintenance')}
-  ${c.cyan('audit:purge-noise')} ${c.dim('[--execute]')}            delete historical low-signal audit_logs rows (dry-run by default)
-  ${c.cyan('help')}${c.dim(', ')}${c.cyan('--version')}                        this help / the installed version
-
-${c.dim('init = preset → runnable backend · scaffold (= new) = full project · Aliases: generate = gen, validate = check')}
-`)
-}
-
-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' })
-    proc.on('close', (code) => process.exit(code ?? 1))
-  })
-}
-
-switch (command) {
-  case 'init':
-    process.exit(await initCommand(argv.slice(1)))
-    break
-
-  case 'dev':
-    process.exit(await devCommand(argv.slice(1)))
-    break
-
-  case 'add':
-    process.exit(await addCommand(argv.slice(1)))
-    break
-
-  case 'scaffold':
-  case 'new': {
-    // Full-project scaffold (backend + frontend + k8s + pipelines) from an
-    // existing config.json. `init` is the leaner, config-building local-dev path.
-    const { scaffold } = await import(join(rootDir, 'infra', 'scripts', 'generate-project.ts'))
-    await scaffold(join(rootDir, 'infra'))
-    break
-  }
-
-  case 'generate':
-  case 'gen': {
-    const genArgs = looksLikeFile ? argv : argv.slice(1)
-    await runScript(join('scripts', 'generate-schema.ts'), genArgs)
-    break
-  }
-
-  case 'validate':
-  case 'check':
-    process.exit(await validateCommand(argv.slice(1)))
-    break
-
-  case 'doctor':
-    process.exit(await doctorCommand())
-    break
-
-  case 'audit:purge-noise':
-  case 'audit-purge-noise':
-    await runScript(join('scripts', 'audit-purge-noise.ts'), argv.slice(1))
-    break
-
-  case '--version':
-  case '-v':
-    log(await pkgVersion())
-    break
-
-  case 'help':
-  case '--help':
-  case '-h':
-  case '':
-  case undefined:
-    showHelp(await pkgVersion())
-    break
-
-  default:
-    log(`${c.red('Unknown command:')} ${command}\n`)
-    showHelp(await pkgVersion())
-    process.exit(1)
-}
+#!/usr/bin/env bun
+
+/**
+ * Nucleus CLI — the single front door to nucleus-core-ts.
+ *
+ *   nucleus init          scaffold a new project (interactive)
+ *   nucleus dev …         run locally (up | down | run)
+ *   nucleus add …         extend an existing project (entity | feature | oauth)
+ *   nucleus validate      validate config.json against the schema
+ *   nucleus doctor        check the local environment (bun, postgres, redis, …)
+ *   nucleus generate      generate the Drizzle schema from config.json
+ */
+
+import { spawn } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { addCommand } from './lib/commands/add'
+import { devCommand } from './lib/commands/dev'
+import { doctorCommand } from './lib/commands/doctor'
+import { initCommand } from './lib/commands/init'
+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 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
+  } catch {
+    return '?'
+  }
+}
+
+function showHelp(version: string) {
+  banner(`Nucleus CLI  v${version}`, 'nucleus-core-ts — config-driven backend framework')
+  log(`
+${c.bold('Usage')}  ${c.cyan('nucleus')} ${c.dim('<command> [options]')}
+
+${c.bold('Create & evolve')}
+  ${c.cyan('init')} ${c.dim('[--preset <p>] [-o <dir>] [-y]')}       build a config + scaffold a runnable backend (zero-to-running)
+  ${c.cyan('add')} ${c.dim('entity | feature <n> | oauth <p>')}    extend this project's config in place (+ regenerate)
+  ${c.cyan('scaffold')}                               full-project scaffold (backend+frontend+k8s+pipelines) from a config.json
+  ${c.cyan('generate')} ${c.dim('<config.json> <outDir>')}           generate the Drizzle schema + relations from config
+  ${c.cyan('validate')} ${c.dim('[config.json]')}                    validate a config against the JSON-Schema + cross-field rules
+
+${c.bold('Local dev')}
+  ${c.cyan('dev')} ${c.dim('[up | down]')}                          run the app; ${c.dim('up')} starts Postgres+Redis, ${c.dim('down')} stops them
+  ${c.cyan('doctor')}                                 check the local environment can run a Nucleus project
+
+${c.bold('Maintenance')}
+  ${c.cyan('audit:purge-noise')} ${c.dim('[--execute]')}            delete historical low-signal audit_logs rows (dry-run by default)
+  ${c.cyan('help')}${c.dim(', ')}${c.cyan('--version')}                        this help / the installed version
+
+${c.dim('init = preset → runnable backend · scaffold (= new) = full project · Aliases: generate = gen, validate = check')}
+`)
+}
+
+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',
+    })
+    proc.on('close', (code) => process.exit(code ?? 1))
+  })
+}
+
+switch (command) {
+  case 'init':
+    process.exit(await initCommand(argv.slice(1)))
+    break
+
+  case 'dev':
+    process.exit(await devCommand(argv.slice(1)))
+    break
+
+  case 'add':
+    process.exit(await addCommand(argv.slice(1)))
+    break
+
+  case 'scaffold':
+  case 'new': {
+    // Full-project scaffold (backend + frontend + k8s + pipelines) from an
+    // existing config.json. `init` is the leaner, config-building local-dev path.
+    const { scaffold } = await import(join(rootDir, 'infra', 'scripts', 'generate-project.ts'))
+    await scaffold(join(rootDir, 'infra'))
+    break
+  }
+
+  case 'generate':
+  case 'gen': {
+    const genArgs = looksLikeFile ? argv : argv.slice(1)
+    await runScript(join('scripts', 'generate-schema.ts'), genArgs)
+    break
+  }
+
+  case 'validate':
+  case 'check':
+    process.exit(await validateCommand(argv.slice(1)))
+    break
+
+  case 'doctor':
+    process.exit(await doctorCommand())
+    break
+
+  case 'audit:purge-noise':
+  case 'audit-purge-noise':
+    await runScript(join('scripts', 'audit-purge-noise.ts'), argv.slice(1))
+    break
+
+  case '--version':
+  case '-v':
+    log(await pkgVersion())
+    break
+
+  case 'help':
+  case '--help':
+  case '-h':
+  case '':
+  case undefined:
+    showHelp(await pkgVersion())
+    break
+
+  default:
+    log(`${c.red('Unknown command:')} ${command}\n`)
+    showHelp(await pkgVersion())
+    process.exit(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
   }
 }