kilo-cms 0.2.0 → 0.3.0

package/README.md

@@ -1,13 +1,16 @@
 # Kilo CMS
 
-An installable, config-driven CMS engine for Next.js — an admin panel, RBAC, a generic
-field-type engine, and an API, mounted into your own app. Define your content schema via
-config, not by hand-editing a registry. Modeled on how [Filament](https://filamentphp.com/)
-installs into a Laravel app.
+A schema-driven, config-driven CMS engine, built specifically for Next.js. Instead of
+generating code or hand-editing a central registry, you describe your content model as plain
+config — fields, relations, validation, list views — and Kilo CMS turns that into a working
+admin panel, RBAC, and API, mounted directly inside your own app's routes.
 
 > **Status**: pre-1.0, proven end-to-end against one real production app
-> ([`the-usual-dev`](https://github.com/revaldyas/the-usual-dev)'s `apps/site`), not yet used
+> ([`kilostudio.id`](https://github.com/kilostudio/kilostudio.id)'s `apps/site`), not yet used
 > by a second, independent project. API surface may still change.
+>
+> **Looking for collaborators.** The repo is currently private; reach out if you want in as a
+> collaborator.
 
 ## What you get
 
@@ -112,29 +115,56 @@ export const auth = createKiloAuth({
 export * from 'kilo-cms/schema'
 export * from '../collections/projects/table'
 
-import { schema as kiloSchema } from 'kilo-cms/schema'
+import { mergeSchema } from 'kilo-cms/schema'
 import { projects } from '../collections/projects/table'
-export const schema = { ...kiloSchema, projects }
+export const schema = mergeSchema({ projects })
 ```
 
-Registration is tied to `db.ts`'s own first import (not a `register()`-hook-only approach) —
-Next.js's build-time static generation spawns separate worker processes, and a hook like
-`instrumentation.ts` isn't guaranteed to fire in every one of them before a page module
-evaluates. Every admin page/route stub should start with `import '@/lib/db'` before its
-re-export, for the same reason:
+`mergeSchema({ ...yourTables })` is just `{ ...kiloSchema, ...yourTables }` — it exists so
+adding a content table only touches the object you pass in, never a second copy of `kiloSchema`
+hand-spread somewhere else. The `export * from '../collections/projects/table'` line above it
+still has to stay, though: drizzle-kit finds tables by scanning a schema file's *top-level
+exports*, not by evaluating a merged object at its own config-load time. If you'd rather not
+maintain that re-export line per collection either, point drizzle-kit's own `schema` option at
+a glob instead — it accepts an array of paths/globs natively:
 
 ```ts
-// app/(admin)/admin/dashboard/page.tsx
-import '@/lib/db'
-export { default } from 'kilo-cms/admin/pages/dashboard'
+// drizzle.config.ts
+export default defineConfig({
+  schema: ['./src/lib/schema.ts', './src/collections/*/table.ts'],
+  // ...
+})
 ```
 
+That way `src/lib/schema.ts` only needs to exist for `export * from 'kilo-cms/schema'` and the
+`mergeSchema(...)` runtime object — every host content table is picked up by the glob
+automatically the moment its `table.ts` exists, with no per-collection edit to this file at all.
+
+### Registration: `instrumentation.ts`
+
+Call `defineKiloConfig()` once, as early as possible, from Next.js's
+[`instrumentation.ts`](https://nextjs.org/docs/app/guides/instrumentation) `register()` hook —
+it runs once per server process, before any request is handled:
+
 ```ts
-// app/api/admin/dashboard/route.ts
-import '@/lib/db'
-export { GET, PUT } from 'kilo-cms/routes/admin/dashboard'
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('@/lib/db')
+  }
+}
 ```
 
+This is enough for every *dynamic* route (every admin page/route, since none of them are
+statically generated) — the process instrumentation ran in is the same one that later serves
+those requests. It is **not** enough on its own for anything reachable from
+`generateStaticParams` on your public-facing pages: Next's build-time static generation spawns
+separate worker processes, and `instrumentation.ts` isn't guaranteed to have run in all of
+them before a page module evaluates. For those pages, importing `@/lib/db` (directly, or
+transitively through whatever data-fetching module they already import) is what actually
+guarantees registration in that worker — `instrumentation.ts` is a convenience for the admin
+side, not a replacement for that.
+
 ### Middleware
 
 Kilo CMS ships an Edge-safe, cookie-presence-only pre-filter that redirects unauthenticated
@@ -167,29 +197,52 @@ const result = await requireAdminSession((r) => r.can('projects', 'read'), '/adm
 Run from your own app's directory:
 
 ```sh
-npx kilo-cms add-collection <slug>   # scaffold a new collection's fields.ts + table.ts
-npx kilo-cms sync                    # regenerate .kilo/types.gen.ts from src/collections/*
-npx kilo-cms migrate                 # apply Kilo CMS's own package-owned migrations
-npx kilo-cms init                    # migrate, then create the first admin user
+npx kilo-cms add-collection <slug> [--fields "..."]  # scaffold a new collection's fields.ts + table.ts
+npx kilo-cms sync                                    # regenerate .kilo/types.gen.ts from src/collections/*
+npx kilo-cms migrate                                 # apply Kilo CMS's own package-owned migrations
+npx kilo-cms init                                    # fill in missing .env secrets, migrate, create the first admin user
 ```
 
 `add-collection` scaffolds the two files and prints the exact lines to paste into
 `kilo.config.ts` — deliberately not an auto-codemod (a script that edits your config file
-wrong is worse than a 10-second copy-paste).
+wrong is worse than a 10-second copy-paste). Without `--fields`, you get the same
+title/slug/sortOrder starter as before. With `--fields`, it builds exactly the fields you list
+instead — a plain-text shorthand for the common case, not a substitute for hand-editing
+`fields.ts` afterward for anything it doesn't cover:
+
+```sh
+npx kilo-cms add-collection testimonials \
+  --fields "quote:textarea(required,rows=4),author:text(required,listPrimary,maxLength=80),rating:rating(max=5),featured:boolean,logo:image"
+```
+
+Each entry is `key:type` or `key:type(opt,opt2=value)`. Supported types: `text`, `textarea`,
+`richtext`, `number`, `boolean`, `select`, `multiselect`, `tags`, `image`, `file`, `date`,
+`datetime`, `color`, `rating`. Options: `required`, `nullable`, `listColumn`, `listPrimary`,
+`searchable`, `sortable`, `filterable`, `readOnly`, `maxLength=N`, `rows=N`,
+`format=slug|email|url|password|tel`, `options=a|b|c` (select/multiselect). Relations, joins,
+arrays, blocks, groups, and JSON fields aren't part of this shorthand — add those by hand, same
+as you'd tune anything else the generator scaffolds.
 
 `migrate` applies Kilo CMS's own schema (auth, RBAC, media, settings, dev-tools, admin-ui,
 locales — see `src/schema/`) against your `DATABASE_URL`, tracked in its own
 `kilo_cms_migrations` table, independent of your own app's migration history for its content
 tables.
 
-`init` runs `migrate`, then creates your first admin user via the existing
-`/api/setup/admin` route — it needs your app already running (`npm run dev` in another
-terminal) since that route executes inside your app's own Next.js runtime:
+`init` fills in `BETTER_AUTH_SECRET` and `CMS_SETUP_TOKEN` in your `.env` if either is missing
+(generated, never overwriting a value that's already there), runs `migrate`, then creates your
+first admin user via the existing `/api/setup/admin` route — it needs your app already running
+(`npm run dev` in another terminal) since that route executes inside your app's own Next.js
+runtime:
 
 ```sh
-CMS_SETUP_TOKEN=... npx kilo-cms init --name "Your Name" --email you@example.com --password "at least 12 characters" [--url http://localhost:3000]
+npx kilo-cms init --name "Your Name" --email you@example.com --password "at least 12 characters" [--url http://localhost:3000]
 ```
 
+The only variable you're still expected to set yourself is `DATABASE_URL`. If `init` had to
+generate a fresh `CMS_SETUP_TOKEN`, it stops after `migrate` and asks you to restart your dev
+server first — the already-running process only read `.env` once, at its own startup, so it
+can't see a token that didn't exist yet. Run the same `init` command again after restarting.
+
 ## Package layout
 
 | Export | What it is |
@@ -198,7 +251,7 @@ CMS_SETUP_TOKEN=... npx kilo-cms init --name "Your Name" --email you@example.com
 | `kilo-cms/collections` | Client-safe: field types, `defineCollectionFields()`, the registry, value helpers |
 | `kilo-cms/collections/table` | Server-only: `defineCollectionTable()` |
 | `kilo-cms/collections/server` | Server-only: validation, workflow, filters, the query engine |
-| `kilo-cms/schema` | Kilo CMS's own drizzle tables (auth, RBAC, media, settings, dev-tools, admin-ui, locales) |
+| `kilo-cms/schema` | Kilo CMS's own drizzle tables (auth, RBAC, media, settings, dev-tools, admin-ui, locales) + `mergeSchema()` |
 | `kilo-cms/auth`, `kilo-cms/auth-client` | `createKiloAuth()` factory + the better-auth React client |
 | `kilo-cms/admin/*` | Admin UI pages and shared components |
 | `kilo-cms/admin/require-session` | `requireAdminSession()` — the shared session/RBAC guard for admin pages |
@@ -208,7 +261,7 @@ CMS_SETUP_TOKEN=... npx kilo-cms init --name "Your Name" --email you@example.com
 ## Status / roadmap
 
 Built by extracting a working, in-production CMS out of the app it was originally embedded
-in — see [`the-usual-dev`'s `WORKLOG.md`](https://github.com/revaldyas/the-usual-dev) for the
+in — see [`kilostudio.id`'s `WORKLOG.md`](https://github.com/kilostudio/kilostudio.id) for the
 full history of that extraction. Not yet done:
 
 - A single catch-all admin route instead of one thin file per page (deliberately skipped for
@@ -217,7 +270,16 @@ full history of that extraction. Not yet done:
 - A second, independent consumer project to prove the install story beyond the one app this
   was extracted from.
 
+## Versioning
+
+Semantic versioning, while the major version stays `0`: a **minor** bump (`0.x.0`) means new or
+changed public API surface (a new export, a new CLI command); a **patch** bump (`0.x.y`) means
+a bug fix with no public API change. Every release is documented in
+[`CHANGELOG.md`](./CHANGELOG.md) and tagged in git (`v0.1.0`, `v0.1.1`, `v0.2.0`, ...) — check
+the changelog before upgrading a consumer's dependency range, especially across a minor bump.
+
 ## License
 
-Proprietary — all rights reserved. Not yet licensed for redistribution; contact the author
-before using this outside of an explicitly authorized project.
+Proprietary — all rights reserved. This is not an open-source project: the repo is private,
+and access is by invitation as a collaborator, not by public license. Contact the author before
+using this outside of an explicitly authorized project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kilo-cms",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "An installable, config-driven CMS engine for Next.js — admin panel, RBAC, a generic field-type engine, and an API, mounted into your own app. Define your content schema via config, not a hand-maintained registry.",
   "keywords": [
     "cms",

package/src/cli/index.mjs

@@ -2,10 +2,11 @@
 // Plain ESM — deliberately not TypeScript, so this runs on any Node (22.6+) without a loader,
 // build step, or dependency on how the host project executes TS. Run from the HOST app's own
 // directory (e.g. `cd apps/site && npx kilo-cms <command>`), same way `drizzle-kit` is run.
-import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { spawnSync } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
 
 const cliDir = dirname(fileURLToPath(import.meta.url))
 const packageRoot = join(cliDir, '..', '..') // packages/kilo-cms
@@ -29,8 +30,120 @@ function singularize(label) {
 
 // --- add-collection ---------------------------------------------------------------------
 
-function addCollection(slug) {
-  if (!slug) fail('usage: kilo-cms add-collection <slug>')
+function keyToLabel(key) {
+  const words = key.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[-_]/g, ' ').trim()
+  return words.charAt(0).toUpperCase() + words.slice(1)
+}
+
+// `title:text(required,listPrimary),summary:textarea(rows=4),cover:image` — a plain-text
+// shorthand for the common case, not a replacement for hand-editing fields.ts for anything
+// past what this covers (relation/join/array/blocks/group/json/point aren't supported here;
+// add those by hand afterward, same as the reviewer's own guidance: generate the shape, then
+// adjust it, rather than have a generator so clever it becomes its own thing to debug).
+const SUPPORTED_FIELD_TYPES = new Set(['text', 'textarea', 'richtext', 'number', 'boolean', 'select', 'multiselect', 'tags', 'image', 'file', 'date', 'datetime', 'color', 'rating'])
+
+// Splits on top-level commas only — a plain `.split(',')` would also cut apart the
+// comma-separated options list inside a field's own `(...)`, e.g. "quote:textarea(required,rows=4)".
+function splitTopLevel(raw) {
+  const parts = []
+  let depth = 0
+  let current = ''
+  for (const char of raw) {
+    if (char === '(') depth++
+    if (char === ')') depth--
+    if (char === ',' && depth === 0) {
+      parts.push(current)
+      current = ''
+    } else {
+      current += char
+    }
+  }
+  if (current) parts.push(current)
+  return parts
+}
+
+function parseFieldSpecs(raw) {
+  return splitTopLevel(raw).map((entry) => {
+    const match = entry.trim().match(/^([a-zA-Z][a-zA-Z0-9]*):([a-z]+)(?:\(([^)]*)\))?$/)
+    if (!match) fail(`could not parse field "${entry.trim()}" — expected "key:type" or "key:type(opt,opt2=value)".`)
+    const [, key, type, optsRaw] = match
+    if (!SUPPORTED_FIELD_TYPES.has(type)) fail(`"${type}" (on field "${key}") isn't a type this generator scaffolds — supported: ${[...SUPPORTED_FIELD_TYPES].join(', ')}. Add it by hand instead.`)
+    const opts = {}
+    for (const pair of (optsRaw ?? '').split(',').map((s) => s.trim()).filter(Boolean)) {
+      const [optKey, optValue] = pair.split('=')
+      opts[optKey] = optValue ?? true
+    }
+    return { key, type, opts }
+  })
+}
+
+// One field spec -> its `fields: [...]` entry (defineCollectionFields shape).
+function fieldConfigFor(spec) {
+  const { key, type, opts } = spec
+  const base = { key, type, label: keyToLabel(key), group: 'overview' }
+  if (opts.required) base.required = true
+  if (opts.nullable) base.nullable = true
+  if (opts.listColumn || opts.listPrimary) base.listColumn = true
+  if (opts.listPrimary) base.listPrimary = true
+  if (opts.searchable) base.searchable = true
+  if (opts.sortable) base.sortable = true
+  if (opts.filterable) base.filterable = true
+  if (opts.readOnly) base.readOnly = true
+
+  if (type === 'text' || type === 'textarea') {
+    if (opts.maxLength) base.maxLength = Number(opts.maxLength)
+    if (type === 'textarea' && opts.rows) base.rows = Number(opts.rows)
+    if (type === 'text' && opts.format) base.format = opts.format
+  }
+  if (type === 'number' && opts.integer) base.integer = true
+  if (type === 'rating' && opts.max) base.max = Number(opts.max)
+  if ((type === 'select' || type === 'multiselect') && opts.options) {
+    const values = String(opts.options).split('|').filter(Boolean)
+    base.options = values.map((value) => ({ value, label: keyToLabel(value) }))
+  } else if (type === 'select' || type === 'multiselect') {
+    base.options = [{ value: 'value-one', label: 'Value one' }, { value: 'value-two', label: 'Value two' }]
+  }
+
+  const entries = Object.entries(base).map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+  return `    { ${entries.join(', ')} }`
+}
+
+// One field spec -> its Drizzle column (table.ts shape). Deliberately conservative: every
+// column defaults to nullable text/jsonb unless `required` was set, since guessing wrong here
+// means a migration to fix later — safer to under-commit and let the user tighten it by hand.
+function columnFor(spec) {
+  const { key, type, opts } = spec
+  const notNull = opts.required && !opts.nullable
+  switch (type) {
+    case 'text':
+    case 'select':
+    case 'image':
+    case 'file':
+    case 'color':
+      return `  ${key}: text('${key}')${notNull ? '.notNull()' : ''},`
+    case 'textarea':
+      return `  ${key}: text('${key}')${notNull ? '.notNull()' : ".default('')"},`
+    case 'richtext':
+      return `  ${key}: jsonb('${key}').$type<RichTextDocument>().notNull().default({ type: 'doc', content: [{ type: 'paragraph' }] }),`
+    case 'number':
+    case 'rating':
+      return `  ${key}: integer('${key}')${notNull ? '.notNull()' : '.default(0)'},`
+    case 'boolean':
+      return `  ${key}: boolean('${key}').notNull().default(false),`
+    case 'multiselect':
+    case 'tags':
+      return `  ${key}: jsonb('${key}').$type<string[]>().notNull().default([]),`
+    case 'date':
+      return `  ${key}: date('${key}')${notNull ? '.notNull()' : ''},`
+    case 'datetime':
+      return `  ${key}: timestamp('${key}')${notNull ? '.notNull()' : ''},`
+    default:
+      throw new Error(`kilo-cms internal error: field type "${type}" is in SUPPORTED_FIELD_TYPES but columnFor() doesn't handle it.`)
+  }
+}
+
+function addCollection(slug, flags) {
+  if (!slug) fail('usage: kilo-cms add-collection <slug> [--fields "key:type(opt,opt2),key2:type"]')
   if (!/^[a-z][a-zA-Z0-9]*$/.test(slug)) fail(`"${slug}" should be camelCase, starting with a lowercase letter (e.g. "projectCategories").`)
 
   const collectionsDir = join(cwd, 'src', 'collections')
@@ -42,6 +155,16 @@ function addCollection(slug) {
   const label = slugToLabel(slug)
   const labelSingular = singularize(label)
   const varName = `${slug}Fields`
+  const tableName = `cms_${slug.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()}`
+
+  const customSpecs = flags?.fields ? parseFieldSpecs(flags.fields) : null
+
+  const fieldsBody = customSpecs
+    ? customSpecs.map(fieldConfigFor).join(',\n')
+    : `    { key: 'title', type: 'text', label: 'Title', group: 'overview', required: true, maxLength: 120, listColumn: true, listPrimary: true, searchable: true, sortable: true },
+    { key: 'slug', type: 'text', label: 'Slug', group: 'overview', width: 'half', required: true, format: 'slug', slugFrom: 'title', maxLength: 120, listColumn: true, searchable: true, sortable: true },
+    { key: 'sortOrder', type: 'number', label: 'Sort order', group: 'overview', integer: true, readOnly: true }`
+  const titleFieldKey = customSpecs ? customSpecs[0]?.key ?? 'title' : 'title'
 
   const fieldsFile = `import { defineCollectionFields } from 'kilo-cms/collections'
 
@@ -50,7 +173,7 @@ export const ${varName} = defineCollectionFields({
   slug: '${slug}',
   label: '${label}',
   labelSingular: '${labelSingular}',
-  titleField: 'title',
+  titleField: '${titleFieldKey}',
   defaultSort: { field: 'sortOrder', dir: 'asc' },
   touchUpdatedAt: true,
   groups: [
@@ -58,25 +181,36 @@ export const ${varName} = defineCollectionFields({
     { id: 'record', label: 'Record', description: 'Managed by the CMS' },
   ],
   fields: [
-    { key: 'title', type: 'text', label: 'Title', group: 'overview', required: true, maxLength: 120, listColumn: true, listPrimary: true, searchable: true, sortable: true },
-    { key: 'slug', type: 'text', label: 'Slug', group: 'overview', width: 'half', required: true, format: 'slug', slugFrom: 'title', maxLength: 120, listColumn: true, searchable: true, sortable: true },
-    { key: 'sortOrder', type: 'number', label: 'Sort order', group: 'overview', integer: true, readOnly: true },
+${fieldsBody},
     { key: 'createdAt', type: 'datetime', label: 'Created', group: 'record', readOnly: true, nullable: true, width: 'half', sortable: true },
     { key: 'updatedAt', type: 'datetime', label: 'Last updated', group: 'record', readOnly: true, nullable: true, width: 'half', sortable: true, listColumn: true },
   ],
 })
 `
 
+  const needsRichText = customSpecs?.some((s) => s.type === 'richtext')
+  const needsJsonb = customSpecs?.some((s) => ['richtext', 'multiselect', 'tags'].includes(s.type))
+  const needsBoolean = customSpecs?.some((s) => s.type === 'boolean')
+  const needsDate = customSpecs?.some((s) => s.type === 'date')
+  const needsTimestamp = customSpecs?.some((s) => s.type === 'datetime')
+
+  const columnImports = ['pgTable', 'text', 'integer']
+  if (needsJsonb) columnImports.push('jsonb')
+  if (needsBoolean) columnImports.push('boolean')
+  if (needsDate) columnImports.push('date')
+  if (needsTimestamp) columnImports.push('timestamp')
+
+  const customColumns = customSpecs ? customSpecs.map(columnFor).join('\n') : null
+  const defaultColumns = `  slug: text('slug').notNull().unique(),\n  title: text('title').notNull(),\n  sortOrder: integer('sort_order').notNull().default(0),`
+
   const tableFile = `import 'server-only'
-import { pgTable, text, integer } from 'drizzle-orm/pg-core'
+import { ${[...new Set(columnImports)].join(', ')} } from 'drizzle-orm/pg-core'
 import { timestamps } from 'kilo-cms/schema'
-import { defineCollectionTable } from 'kilo-cms/collections/table'
+import { defineCollectionTable } from 'kilo-cms/collections/table'${needsRichText ? "\nimport type { RichTextDocument } from 'kilo-cms/richtext'" : ''}
 
-export const ${slug} = defineCollectionTable('${slug}', pgTable('cms_${slug.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()}', {
+export const ${slug} = defineCollectionTable('${slug}', pgTable('${tableName}', {
   id: text('id').primaryKey(),
-  slug: text('slug').notNull().unique(),
-  title: text('title').notNull(),
-  sortOrder: integer('sort_order').notNull().default(0),
+${customColumns ?? defaultColumns}
   ...timestamps,
 }))
 `
@@ -139,8 +273,36 @@ function parseFlags(argv) {
   return flags
 }
 
+/**
+ * Fills in `BETTER_AUTH_SECRET` and `CMS_SETUP_TOKEN` in the host's `.env` if either is
+ * missing — the two secrets a fresh install needs before it can even start, that otherwise
+ * have nothing meaningful to default to, so a new user has to know to invent them by hand.
+ * Never touches a key that's already present (in the file OR already set in the environment) —
+ * this only fills gaps, it doesn't rotate or overwrite anything.
+ */
+function ensureEnvSecrets() {
+  const envPath = join(cwd, '.env')
+  const existing = existsSync(envPath) ? readFileSync(envPath, 'utf8') : ''
+  const hasKey = (key) => new RegExp(`^${key}=`, 'm').test(existing) || Boolean(process.env[key])
+
+  const missing = []
+  if (!hasKey('BETTER_AUTH_SECRET')) missing.push(['BETTER_AUTH_SECRET', randomBytes(32).toString('hex')])
+  if (!hasKey('CMS_SETUP_TOKEN')) missing.push(['CMS_SETUP_TOKEN', randomBytes(24).toString('hex')])
+
+  if (!missing.length) return []
+
+  const block = `\n# Added by \`npx kilo-cms init\` on ${new Date().toISOString().slice(0, 10)}\n${missing.map(([key, value]) => `${key}=${value}`).join('\n')}\n`
+  appendFileSync(envPath, block)
+  for (const [key, value] of missing) process.env[key] = value
+
+  const keys = missing.map(([key]) => key)
+  console.log(`Added ${keys.join(' and ')} to .env (generated — not written anywhere else, keep this file out of version control).`)
+  return keys
+}
+
 async function init(argv) {
   const flags = parseFlags(argv)
+  const addedSecrets = ensureEnvSecrets()
   const url = flags.url ?? 'http://localhost:3000'
   const token = flags.token ?? process.env.CMS_SETUP_TOKEN
   const { name, email, password } = flags
@@ -150,6 +312,16 @@ async function init(argv) {
 
   migrate()
 
+  // A freshly generated CMS_SETUP_TOKEN only exists in .env, not in whatever process is already
+  // running the host app — that process read its env once, at its own startup. Calling
+  // /api/setup/admin right now would fail with a confusing "Unauthorized" (it's still checking
+  // the OLD, unset value), so stop here and have the user restart the app first.
+  if (addedSecrets.includes('CMS_SETUP_TOKEN')) {
+    console.log('\nCMS_SETUP_TOKEN was just generated, so it\'s not loaded into your already-running app yet.')
+    console.log('Restart your dev server (so it picks up the new .env), then run this same `kilo-cms init` command again.')
+    return
+  }
+
   console.log(`\nCreating first admin at ${url}/api/setup/admin ...`)
   console.log('(this requires your app to already be running — start it in another terminal first if it isn\'t.)')
 
@@ -175,7 +347,7 @@ async function init(argv) {
 
 switch (command) {
   case 'add-collection':
-    addCollection(args[0])
+    addCollection(args[0], parseFlags(args.slice(1)))
     break
   case 'sync':
     sync()
@@ -188,10 +360,22 @@ switch (command) {
     break
   default:
     console.log(`kilo-cms — usage:
-  kilo-cms add-collection <slug>   scaffold a new collection's fields.ts + table.ts
+  kilo-cms add-collection <slug> [--fields "key:type(opt,opt2),key2:type"]
+                                    scaffold a new collection's fields.ts + table.ts.
+                                    Without --fields: the default title/slug/sortOrder template.
+                                    With --fields: builds exactly the fields you list (plus id/
+                                    createdAt/updatedAt, always added). Supported types: text,
+                                    textarea, richtext, number, boolean, select, multiselect,
+                                    tags, image, file, date, datetime, color, rating. Options:
+                                    required, nullable, listColumn, listPrimary, searchable,
+                                    sortable, filterable, readOnly, maxLength=N, rows=N,
+                                    format=slug|email|url, options=a|b|c.
+                                    Example: --fields "title:text(required,listPrimary),
+                                    summary:textarea(rows=4),cover:image"
   kilo-cms sync                    regenerate .kilo/types.gen.ts from src/collections/*
   kilo-cms migrate                 apply kilo-cms's own package-owned migrations
-  kilo-cms init                    migrate, then create the first admin user
+  kilo-cms init                    generate missing secrets into .env, migrate, then create
+                                    the first admin user
                                     (--name, --email, --password, [--url], [--token or $CMS_SETUP_TOKEN])`)
     process.exit(command ? 1 : 0)
 }

package/src/schema/index.ts

@@ -31,3 +31,21 @@ export const schema = {
   contentViews, dashboards,
   cmsLocales,
 }
+
+/**
+ * Merges kilo-cms's own tables with a host's content tables into the one object both
+ * `drizzle({ client, schema })` and drizzle-kit's config need. Purely `{ ...schema, ...tables }`
+ * under the hood — the value isn't the logic, it's giving the host ONE call instead of
+ * hand-spreading `schema` themselves, so adding a content table only touches the `tables`
+ * object passed in here, never a second place in the host's own schema file.
+ *
+ * This does NOT replace `export * from '../collections/<slug>/table'` re-exports in the host's
+ * own schema barrel — drizzle-kit's schema introspection needs each table as a real top-level
+ * export it can find by scanning the module (or, more simply, point drizzle-kit's own `schema`
+ * config option at a glob like `['./src/lib/schema.ts', './src/collections/*\/table.ts']`,
+ * which drizzle-kit supports natively and removes the re-export lines entirely — see this
+ * package's README "Quickstart" section).
+ */
+export function mergeSchema<T extends Record<string, unknown>>(tables: T): typeof schema & T {
+  return { ...schema, ...tables }
+}