nucleus-core-ts 0.10.141 → 0.10.143

package/README.md

@@ -1,177 +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.
+# 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,136 +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 { 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)
-}
+#!/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)
+}