nucleus-core-ts 0.9.745 → 0.9.747

package/bin/cli.ts

@@ -1,110 +1,131 @@
 #!/usr/bin/env bun
 
 /**
- * Nucleus CLI — unified entry point for all nucleus-core-ts commands.
+ * Nucleus CLI — the single front door to nucleus-core-ts.
  *
- * Usage:
- *   npx nucleus-core-ts scaffold    — Interactive project scaffolding
- *   npx nucleus-core-ts generate    — Generate schema from config.json
- *   npx nucleus-core-ts help        — Show available commands
+ *   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
 
-const BOLD = '\x1b[1m'
-const CYAN = '\x1b[36m'
-const DIM = '\x1b[2m'
-const RED = '\x1b[31m'
-const RESET = '\x1b[0m'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-const rootDir = join(__dirname, '..')
+async function pkgVersion(): Promise<string> {
+  try {
+    return (JSON.parse(await Bun.file(join(rootDir, 'package.json')).text()) as { version: string }).version
+  } catch {
+    return '?'
+  }
+}
 
-const firstArg = process.argv[2] ?? ''
-const looksLikeFile =
-  firstArg.endsWith('.json') || firstArg.startsWith('./') || firstArg.startsWith('/')
-const command = looksLikeFile ? 'generate' : firstArg
+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]')}
 
-function showHelp() {
-  console.log(`
-${CYAN}${BOLD}Nucleus CLI${RESET} ${DIM}(nucleus-core-ts)${RESET}
+${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
 
-${BOLD}Usage:${RESET}
-  npx nucleus-core-ts ${CYAN}<command>${RESET}
+${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
 
-${BOLD}Commands:${RESET}
-  ${CYAN}scaffold${RESET}            Interactive project scaffolding (API + frontend + k8s + pipelines)
-  ${CYAN}generate${RESET}            Generate Drizzle schema from config.json
-  ${CYAN}audit:purge-noise${RESET}   Delete historical low-signal audit_logs rows (dry-run by default)
-  ${CYAN}help${RESET}                Show this help message
+${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
 
-${BOLD}Examples:${RESET}
-  ${DIM}npx nucleus-core-ts scaffold${RESET}
-  ${DIM}npx nucleus-core-ts generate src/config.json src/drizzle${RESET}
-  ${DIM}npx nucleus-core-ts audit:purge-noise            # dry run, all schemas${RESET}
-  ${DIM}npx nucleus-core-ts audit:purge-noise --execute  # actually delete${RESET}
+${c.dim('init = preset → runnable backend · scaffold (= new) = full project · Aliases: generate = gen, validate = check')}
 `)
 }
 
-async function runScript(scriptRelPath: string, args: string[]) {
-  return new Promise<void>(() => {
-    const proc = spawn('bun', ['run', join(rootDir, scriptRelPath), ...args], {
-      cwd: process.cwd(),
-      stdio: 'inherit',
-    })
-    proc.on('close', (code) => {
-      process.exit(code ?? 1)
-    })
-  })
-}
-
-async function runGenerate(args: string[]) {
-  return new Promise<void>(() => {
-    const proc = spawn('bun', ['run', join(rootDir, 'scripts', 'generate-schema.ts'), ...args], {
-      cwd: process.cwd(),
-      stdio: 'inherit',
-    })
-    proc.on('close', (code) => {
-      process.exit(code ?? 1)
-    })
+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 'scaffold':
   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'))
-    const infraDir = join(rootDir, 'infra')
-    await scaffold(infraDir)
+    await scaffold(join(rootDir, 'infra'))
     break
   }
 
   case 'generate':
   case 'gen': {
-    const genArgs = looksLikeFile ? process.argv.slice(2) : process.argv.slice(3)
-    await runGenerate(genArgs)
+    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'), process.argv.slice(3))
+  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()
+    showHelp(await pkgVersion())
     break
 
   default:
-    console.error(`${RED}Unknown command: ${command}${RESET}`)
-    showHelp()
+    log(`${c.red('Unknown command:')} ${command}\n`)
+    showHelp(await pkgVersion())
     process.exit(1)
 }

package/bin/lib/commands/add.ts

@@ -0,0 +1,235 @@
+/**
+ * `nucleus add <thing>` — extend an existing project's config.json in place.
+ *
+ *   nucleus add entity            interactively add one or more entities
+ *   nucleus add feature <name>    enable a feature block (storage, chat,
+ *                                 payment, notification, verification, audit,
+ *                                 captcha, pubsub) with schema-valid defaults
+ *   nucleus add oauth <provider>  add an OAuth provider to authentication
+ *
+ * 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 { loadConfigSchema, validateAgainstSchema } from '../schema'
+
+type Cfg = Record<string, unknown>
+
+/** Feature blocks keyed by name — each returns a schema-valid default config fragment. */
+const FEATURES: Record<string, { summary: string; apply: (cfg: Cfg) => void | Promise<void> }> = {
+  storage: {
+    summary: 'file storage + CDN (upload/serve, ownership-scoped)',
+    apply: (cfg) => {
+      cfg.storage = {
+        enabled: true,
+        provider: 'local',
+        local: { basePath: './.storage' },
+        cdn: { enabled: true },
+      }
+    },
+  },
+  chat: {
+    summary: 'realtime chat channels + messages',
+    apply: (cfg) => {
+      cfg.chat = { enabled: true, attachments: { enabled: false } }
+    },
+  },
+  notification: {
+    summary: 'notification channels (email/telegram/webhook)',
+    apply: (cfg) => {
+      cfg.notification = { enabled: true, channels: { email: false } }
+    },
+  },
+  verification: {
+    summary: 'signed verification / approval flows',
+    apply: (cfg) => {
+      cfg.verification = { enabled: true }
+    },
+  },
+  audit: {
+    summary: 'audit logging of mutations',
+    apply: (cfg) => {
+      cfg.audit = { enabled: true }
+    },
+  },
+  captcha: {
+    summary: 'CAPTCHA challenge on sensitive endpoints',
+    apply: (cfg) => {
+      cfg.captcha = { enabled: true, provider: 'turnstile', secretKey: 'CAPTCHA_SECRET_KEY' }
+    },
+  },
+  pubsub: {
+    summary: 'Dapr pub/sub event fan-out',
+    apply: (cfg) => {
+      cfg.pubsub = { enabled: true }
+    },
+  },
+  payment: {
+    summary: 'payment provider (iyzico | stripe)',
+    apply: async (cfg) => {
+      const p = prompts()
+      try {
+        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' }
+        cfg.payment = block
+      } finally {
+        p.close()
+      }
+    },
+  },
+}
+
+const OAUTH_PROVIDERS = ['google', 'microsoft', 'github', 'apple']
+
+async function readConfig(): Promise<{ path: string; cfg: Cfg } | null> {
+  const path = findConfigPath()
+  if (!path) {
+    fail('No config.json found here — run this from a Nucleus project (or `nucleus init` first)')
+    return null
+  }
+  try {
+    return { path, cfg: JSON.parse(await Bun.file(path).text()) as Cfg }
+  } catch {
+    fail(`Config ${path} is not valid JSON`)
+    return null
+  }
+}
+
+/** Persist, validate, and (if schema-affecting) regenerate Drizzle. */
+async function persist(path: string, cfg: Cfg, regen: boolean): Promise<number> {
+  const schema = await loadConfigSchema()
+  const res = validateAgainstSchema(cfg, schema)
+  const cross = crossFieldChecks(cfg)
+  if (res.errors.length + cross.length > 0) {
+    for (const e of [...res.errors, ...cross]) fail(`${c.bold(e.path || '(root)')} — ${e.message}`)
+    fail('Change would make the config invalid — nothing written')
+    return 1
+  }
+  await Bun.write(path, JSON.stringify(cfg, null, 2) + '\n')
+  ok(`Updated ${c.cyan(relative(process.cwd(), path))}`)
+
+  if (regen) {
+    const outDir = join(dirname(path), 'drizzle')
+    step(`Regenerating Drizzle schema → ${c.dim(relative(process.cwd(), outDir))}`)
+    const r = spawnSync('bunx', ['nucleus-core-ts', 'generate', path, outDir], { stdio: 'inherit' })
+    if (r.status !== 0) {
+      warn('Schema regeneration failed — run `bunx nucleus-core-ts generate` manually')
+      return 1
+    }
+    ok('Schema regenerated')
+  }
+  return 0
+}
+
+async function addEntity(): Promise<number> {
+  const loaded = await readConfig()
+  if (!loaded) return 1
+  const { path, cfg } = loaded
+  const entities = Array.isArray(cfg.entities) ? (cfg.entities as Cfg[]) : []
+  const existing = new Set(entities.map((e) => (e as { table_name?: string }).table_name))
+
+  step('Add entities (blank table name to finish)')
+  const p = prompts()
+  let added = 0
+  try {
+    let e = await buildEntity(p)
+    while (e) {
+      const tn = (e as { table_name: string }).table_name
+      if (existing.has(tn)) warn(`Entity "${tn}" already exists — skipped`)
+      else {
+        entities.push(e)
+        existing.add(tn)
+        ok(`Queued entity "${tn}"`)
+        added++
+      }
+      e = await buildEntity(p)
+    }
+  } finally {
+    p.close()
+  }
+  if (added === 0) {
+    info('No entities added')
+    return 0
+  }
+  cfg.entities = entities
+  return persist(path, cfg, true)
+}
+
+async function addFeature(name?: string): Promise<number> {
+  const key = (name || '').toLowerCase()
+  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)}`)
+    return 1
+  }
+  const loaded = await readConfig()
+  if (!loaded) return 1
+  const { path, cfg } = loaded
+  if ((cfg[key] as Cfg | undefined)?.enabled) {
+    info(`Feature "${key}" is already enabled — leaving it as-is`)
+    return 0
+  }
+  step(`Enabling feature: ${c.cyan(key)} ${c.dim(`— ${FEATURES[key].summary}`)}`)
+  await FEATURES[key].apply(cfg)
+  const rc = await persist(path, cfg, false)
+  if (rc === 0) info('Secrets are referenced by ENV-VAR NAME — set them in .env before running.')
+  return rc
+}
+
+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(', ')}`)
+    return 1
+  }
+  const loaded = await readConfig()
+  if (!loaded) return 1
+  const { path, cfg } = loaded
+  const auth = (cfg.authentication as Cfg | undefined) ?? {}
+  if (!auth.enabled) {
+    fail('authentication is not enabled — enable it first (an `api` or `saas` preset has it on)')
+    return 1
+  }
+  const oauth = (auth.oauth as Cfg | undefined) ?? {}
+  if (oauth[prov]) {
+    info(`OAuth provider "${prov}" is already configured`)
+    return 0
+  }
+  const up = prov.toUpperCase()
+  oauth[prov] = { clientId: `${up}_CLIENT_ID`, clientSecret: `${up}_CLIENT_SECRET` }
+  auth.oauth = oauth
+  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.`)
+  return rc
+}
+
+export async function addCommand(args: string[]): Promise<number> {
+  const thing = args[0]
+  switch (thing) {
+    case 'entity':
+    case 'entities':
+      return addEntity()
+    case 'feature':
+      return addFeature(args[1])
+    case 'oauth':
+      return addOauth(args[1])
+    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 feature <name>')}    ${c.dim('enable a feature block')}`)
+      log(`    ${c.cyan('nucleus add oauth <provider>')}  ${c.dim(`add OAuth (${OAUTH_PROVIDERS.join('|')})`)}`)
+      return 1
+  }
+}

package/bin/lib/commands/dev.ts

@@ -0,0 +1,174 @@
+/**
+ * `nucleus dev [up|down]` — the local run loop.
+ *
+ *   nucleus dev up     ensure Postgres + Redis are reachable; if not, start
+ *                      throwaway Docker containers for the missing one(s).
+ *   nucleus dev        pre-flight the datastores, then run the backend
+ *                      (`bun run dev`), streaming its output.
+ *   nucleus dev down   stop + remove the Docker containers `dev up` started.
+ *
+ * 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 { pgConn, readEnv, redisConn, tcpReachable } from '../env'
+
+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[] }
+
+function services(env: Record<string, string>): Svc[] {
+  const pg = pgConn(env)
+  const r = redisConn(env)
+  return [
+    {
+      name: 'Postgres',
+      container: PG_CONTAINER,
+      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`,
+        'postgres:16-alpine',
+      ],
+    },
+    {
+      name: 'Redis',
+      container: REDIS_CONTAINER,
+      host: r.host,
+      port: r.port,
+      run: (port) => ['run', '-d', '--name', REDIS_CONTAINER, '-p', `${port}:6379`, 'redis:7-alpine'],
+    },
+  ]
+}
+
+const isLocal = (host: string) => host === 'localhost' || host === '127.0.0.1' || host === '::1'
+
+async function waitReachable(host: string, port: number, tries = 30): Promise<boolean> {
+  for (let i = 0; i < tries; i++) {
+    if (await tcpReachable(host, port, 1000)) return true
+    await new Promise((r) => setTimeout(r, 1000))
+  }
+  return false
+}
+
+async function devUp(): Promise<number> {
+  step('nucleus dev up — ensuring datastores')
+  const env = readEnv()
+  const svcs = services(env)
+  const need: Svc[] = []
+
+  for (const s of svcs) {
+    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)`)
+      return 1
+    } else {
+      need.push(s)
+    }
+  }
+
+  if (need.length === 0) {
+    log()
+    ok(c.green('All datastores up.') + c.dim(' Run `nucleus dev` to start the app.'))
+    return 0
+  }
+
+  if (!Bun.which('docker')) {
+    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 id = (existing.stdout || '').trim()
+    if (id) {
+      info(`Starting existing container ${c.dim(s.container)}`)
+      spawnSync('docker', ['start', s.container], { stdio: 'ignore' })
+    } else {
+      info(`Starting ${s.name} container ${c.dim(s.container)} (${s.host}:${s.port})`)
+      const res = spawnSync('docker', s.run(s.port), { encoding: 'utf-8' })
+      if (res.status !== 0) {
+        fail(`Failed to start ${s.name}: ${(res.stderr || '').trim()}`)
+        return 1
+      }
+    }
+  }
+
+  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}`)}`)
+    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.'))
+  return 0
+}
+
+function devDown(): number {
+  step('nucleus dev down — stopping dev containers')
+  if (!Bun.which('docker')) {
+    warn('docker not found — nothing to stop')
+    return 0
+  }
+  let stopped = 0
+  for (const container of [PG_CONTAINER, REDIS_CONTAINER]) {
+    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)}`)
+      stopped++
+    }
+  }
+  if (stopped === 0) info('No nucleus dev containers were running')
+  return 0
+}
+
+async function devRun(): Promise<number> {
+  if (!existsSync('package.json')) {
+    fail('No package.json here — run this from a Nucleus project (or `nucleus init` first)')
+    return 1
+  }
+  // Pre-flight the datastores so failures are obvious before the app boots.
+  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)`)
+  }
+
+  // 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']
+  } catch {
+    /* use default */
+  }
+
+  step(`Running ${c.cyan(cmd.join(' '))} ${c.dim('(Ctrl-C to stop)')}`)
+  const [bin = 'bun', ...rest] = cmd
+  const res = spawnSync(bin, rest, { stdio: 'inherit' })
+  return res.status ?? 0
+}
+
+export async function devCommand(args: string[]): Promise<number> {
+  const sub = args[0]
+  if (sub === 'up') return devUp()
+  if (sub === 'down') return devDown()
+  if (sub && sub !== 'run') {
+    fail(`Unknown: nucleus dev ${sub} (expected up | down | run)`)
+    return 1
+  }
+  return devRun()
+}

package/bin/lib/commands/doctor.ts

@@ -0,0 +1,78 @@
+/**
+ * `nucleus doctor` — checks the local environment can run a Nucleus project:
+ * runtime (bun), reachable Postgres + Redis, optional Docker/Dapr, and a valid
+ * 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'
+
+export async function doctorCommand(): Promise<number> {
+  step('Nucleus doctor — local environment check')
+  const env = readEnv()
+  let requiredFailures = 0
+
+  // Runtime
+  if (typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined') ok(`bun ${c.dim(Bun.version)}`)
+  else {
+    fail('bun runtime not detected — install from https://bun.sh')
+    requiredFailures++
+  }
+  if (process.versions.node) info(`node ${c.dim(process.versions.node)} (optional)`)
+
+  // Postgres
+  const pg = pgConn(env)
+  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`)
+    requiredFailures++
+  }
+
+  // Redis
+  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`)
+    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('createdb')
+    ? ok(`createdb ${c.dim('(for nucleus db create)')}`)
+    : info('createdb not found (optional — psql client tools)')
+
+  // Config
+  const cfgPath = findConfigPath()
+  if (cfgPath) {
+    try {
+      const cfg = JSON.parse(await Bun.file(cfgPath).text()) as Record<string, unknown>
+      const res = validateAgainstSchema(cfg, await loadConfigSchema())
+      const cross = crossFieldChecks(cfg)
+      const errCount = res.errors.length + cross.length
+      if (errCount === 0) ok(`Config ${c.dim(cfgPath)} is valid`)
+      else {
+        fail(`Config ${cfgPath} has ${errCount} error(s) — run \`nucleus validate\``)
+        requiredFailures++
+      }
+      const missing = [...collectEnvRefs(cfg)].filter((e) => !env[e])
+      if (missing.length) warn(`${missing.length} referenced env var(s) unset: ${c.dim(missing.join(', '))}`)
+    } catch {
+      fail(`Config ${cfgPath} is not valid JSON`)
+      requiredFailures++
+    }
+  } else {
+    info('No config.json here yet — run `nucleus init` to create a project')
+  }
+
+  log()
+  if (requiredFailures === 0) {
+    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`)))
+  return 1
+}