kilo-cms 0.1.1 → 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,27 +115,81 @@ 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
+visitors away from `/admin/*` before a page even renders — a fast filter, not the real
+security boundary (every admin page/route still validates the session and RBAC permissions
+for real). Your own `middleware.ts` re-exports it and defines `matcher` itself (Next.js
+statically analyzes `matcher` in the file it scans — it can't be re-exported through another
+module):
+
+```ts
+// middleware.ts
+export { kiloAdminMiddleware as middleware } from 'kilo-cms/middleware'
+
+export const config = {
+  matcher: ['/admin/:path*'],
+}
+```
+
+Admin pages use `requireAdminSession()` from `kilo-cms/admin/require-session` instead of
+hand-rolling `getSessionWithPermissions()` + `redirect()`:
+
+```ts
+import { requireAdminSession } from 'kilo-cms/admin/require-session'
+
+const result = await requireAdminSession((r) => r.can('projects', 'read'), '/admin/dashboard')
 ```
 
 ## CLI
@@ -140,20 +197,52 @@ export { GET, PUT } from 'kilo-cms/routes/admin/dashboard'
 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 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` 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
+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 |
@@ -162,25 +251,35 @@ tables.
 | `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 |
+| `kilo-cms/middleware` | `kiloAdminMiddleware` — Edge-safe cookie-presence pre-filter for `/admin/*` |
 | `kilo-cms/routes/*` | Route Handler logic for the admin API, public API helpers, auth, cron |
 
 ## 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:
 
-- Centralized auth middleware (every admin page currently does its own session check).
-- A single catch-all admin route instead of one thin file per page.
-- An interactive `kilo-cms init` (migrate + seed settings + create the first admin user in one
-  command).
+- A single catch-all admin route instead of one thin file per page (deliberately skipped for
+  now — today's thin per-page files are already minimal; a hand-rolled catch-all router would
+  trade that for real complexity with no proven need yet).
 - 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.1.1",
+  "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",
@@ -39,6 +39,8 @@
     "./dashboard": "./src/dashboard.ts",
     "./routes/admin/*": "./src/routes/admin/*/route.ts",
     "./routes/*": "./src/routes/*.ts",
+    "./middleware": "./src/middleware.ts",
+    "./admin/require-session": "./src/admin/require-session.ts",
     "./admin/*": "./src/admin/*.tsx",
     "./admin.css": "./src/admin/admin.css",
     "./globals.css": "./src/admin/globals.css"

package/src/admin/pages/ai-settings.tsx

@@ -1,9 +1,7 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { AiSettingsEditor } from '../AiSettingsEditor'
 
 export default async function AiSettingsPage() {
-  const result = await getSessionWithPermissions()
-  if (!result || !result.can('settings', 'read')) redirect('/admin/login')
+  const result = await requireAdminSession((r) => r.can('settings', 'read'), '/admin/login')
   return <AiSettingsEditor userName={result.session.user.name} canManageAi={result.hasSystem('ai.manage')} />
 }

package/src/admin/pages/api-tokens.tsx

@@ -1,10 +1,7 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { ApiTokensEditor } from '../ApiTokensEditor'
 
 export default async function ApiTokensPage() {
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.hasSystem('developers.manage')) redirect('/admin/settings')
+  const result = await requireAdminSession((r) => r.hasSystem('developers.manage'), '/admin/settings')
   return <ApiTokensEditor userName={result.session.user.name} />
 }

package/src/admin/pages/collection-list.tsx

@@ -1,5 +1,5 @@
-import { notFound, redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { notFound } from 'next/navigation'
+import { requireAdminSession } from '../require-session'
 import { getCollection } from '../../collections'
 import { CollectionListEditor } from '../CollectionListEditor'
 
@@ -7,9 +7,7 @@ export default async function CollectionListPage({ params }: { params: Promise<{
   const { collection } = await params
   const config = getCollection(collection)
   if (!config) notFound()
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.can(config.slug, 'read')) redirect('/admin/dashboard')
+  const result = await requireAdminSession((r) => r.can(config.slug, 'read'), '/admin/dashboard')
   return (
     <CollectionListEditor
       config={config}

package/src/admin/pages/collection-record.tsx

@@ -1,5 +1,5 @@
-import { notFound, redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { notFound } from 'next/navigation'
+import { requireAdminSession } from '../require-session'
 import { getCollection } from '../../collections'
 import { CollectionRecordEditor } from '../CollectionRecordEditor'
 
@@ -7,9 +7,7 @@ export default async function CollectionRecordPage({ params }: { params: Promise
   const { collection, id } = await params
   const config = getCollection(collection)
   if (!config) notFound()
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.can(config.slug, 'read')) redirect('/admin/dashboard')
+  const result = await requireAdminSession((r) => r.can(config.slug, 'read'), '/admin/dashboard')
   return (
     <CollectionRecordEditor
       config={config}

package/src/admin/pages/dashboard.tsx

@@ -1,10 +1,8 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { getDashboardSources } from '../../dashboard'
 import { DashboardBuilder } from '../DashboardBuilder'
 
 export default async function DashboardPage() {
-  const result = await getSessionWithPermissions()
-  if (!result || !result.can('settings', 'read')) redirect('/admin/login')
+  const result = await requireAdminSession((r) => r.can('settings', 'read'), '/admin/login')
   return <DashboardBuilder userName={result.session.user.name} canUpdate={result.can('settings', 'update')} dashboardSources={getDashboardSources()} />
 }

package/src/admin/pages/email-settings.tsx

@@ -1,10 +1,7 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { EmailSettingsEditor } from '../EmailSettingsEditor'
 
 export default async function EmailSettingsPage() {
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.hasSystem('developers.manage')) redirect('/admin/settings')
+  const result = await requireAdminSession((r) => r.hasSystem('developers.manage'), '/admin/settings')
   return <EmailSettingsEditor userName={result.session.user.name} />
 }

package/src/admin/pages/locales-settings.tsx

@@ -1,10 +1,7 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { LocalesEditor } from '../LocalesEditor'
 
 export default async function LocalesPage() {
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.hasSystem('locales.manage')) redirect('/admin/settings')
+  const result = await requireAdminSession((r) => r.hasSystem('locales.manage'), '/admin/settings')
   return <LocalesEditor userName={result.session.user.name} />
 }

package/src/admin/pages/media.tsx

@@ -1,9 +1,7 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { MediaLibrary } from '../MediaLibrary'
 
 export default async function MediaPage() {
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
+  const result = await requireAdminSession()
   return <MediaLibrary userName={result.session.user.name} />
 }

package/src/admin/pages/review-queue.tsx

@@ -1,11 +1,10 @@
 import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { getCollection, isCollectionSlug, reviewableSlugs, type CollectionSlug } from '../../collections'
 import { ReviewQueueEditor, type ReviewCollectionMeta } from '../ReviewQueueEditor'
 
 export default async function ReviewQueuePage() {
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
+  const result = await requireAdminSession()
   const reviewSlugs = reviewableSlugs.filter((slug): slug is CollectionSlug => isCollectionSlug(slug))
   const canReview = Object.fromEntries(reviewSlugs.map((slug) => [slug, result.can(slug, 'review')])) as Record<CollectionSlug, boolean>
   const canApprove = Object.fromEntries(reviewSlugs.map((slug) => [slug, result.can(slug, 'approve')])) as Record<CollectionSlug, boolean>

package/src/admin/pages/role-edit.tsx

@@ -1,11 +1,8 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { RoleEditor } from '../RoleEditor'
 
 export default async function RoleEditPage({ params }: { params: Promise<{ id: string }> }) {
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.hasSystem('roles.manage')) redirect('/admin')
+  const result = await requireAdminSession((r) => r.hasSystem('roles.manage'), '/admin')
   const { id } = await params
   return <RoleEditor id={id} userName={result.session.user.name} />
 }

package/src/admin/pages/roles.tsx

@@ -1,10 +1,7 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { RolesEditor } from '../RolesEditor'
 
 export default async function RolesPage() {
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.hasSystem('roles.manage')) redirect('/admin')
+  const result = await requireAdminSession((r) => r.hasSystem('roles.manage'), '/admin')
   return <RolesEditor userName={result.session.user.name} />
 }

package/src/admin/pages/scheduled.tsx

@@ -1,12 +1,10 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { getCollection, schedulingSlugs, type CollectionSlug } from '../../collections'
 import { ScheduledEditor, type ScheduledCollectionMeta } from '../ScheduledEditor'
 
 export default async function ScheduledPage() {
-  const result = await getSessionWithPermissions()
-  const readableSlugs = schedulingSlugs.filter((slug): slug is CollectionSlug => Boolean(result?.can(slug, 'read')))
-  if (!result || !readableSlugs.length) redirect('/admin/login')
+  const result = await requireAdminSession((r) => schedulingSlugs.some((slug) => r.can(slug, 'read')), '/admin/login')
+  const readableSlugs = schedulingSlugs.filter((slug): slug is CollectionSlug => result.can(slug, 'read'))
   const meta: ScheduledCollectionMeta = Object.fromEntries(
     readableSlugs.map((slug) => {
       const config = getCollection(slug)!

package/src/admin/pages/seo-settings.tsx

@@ -1,9 +1,7 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { SeoSettingsEditor } from '../SeoSettingsEditor'
 
 export default async function SeoSettingsPage() {
-  const result = await getSessionWithPermissions()
-  if (!result || !result.can('settings', 'read')) redirect('/admin/login')
+  const result = await requireAdminSession((r) => r.can('settings', 'read'), '/admin/login')
   return <SeoSettingsEditor userName={result.session.user.name} />
 }

package/src/admin/pages/single-record.tsx

@@ -1,5 +1,5 @@
-import { notFound, redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { notFound } from 'next/navigation'
+import { requireAdminSession } from '../require-session'
 import { getSingle } from '../../collections'
 import { SingleRecordEditor } from '../SingleRecordEditor'
 
@@ -7,9 +7,7 @@ export default async function SingleRecordPage({ params }: { params: Promise<{ t
   const { type } = await params
   const config = getSingle(type)
   if (!config) notFound()
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.can(config.slug, 'read')) redirect('/admin/dashboard')
+  const result = await requireAdminSession((r) => r.can(config.slug, 'read'), '/admin/dashboard')
   return (
     <SingleRecordEditor
       config={config}

package/src/admin/pages/site-settings.tsx

@@ -1,9 +1,7 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { SiteSettingsEditor } from '../SiteSettingsEditor'
 
 export default async function SettingsPage() {
-  const result = await getSessionWithPermissions()
-  if (!result || !result.can('settings', 'read')) redirect('/admin/login')
+  const result = await requireAdminSession((r) => r.can('settings', 'read'), '/admin/login')
   return <SiteSettingsEditor userName={result.session.user.name} />
 }

package/src/admin/pages/user-edit.tsx

@@ -1,11 +1,8 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { UserEditor } from '../UserEditor'
 
 export default async function UserEditPage({ params }: { params: Promise<{ id: string }> }) {
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.hasSystem('users.manage')) redirect('/admin')
+  const result = await requireAdminSession((r) => r.hasSystem('users.manage'), '/admin')
   const { id } = await params
   return <UserEditor id={id} userName={result.session.user.name} />
 }

package/src/admin/pages/user-new.tsx

@@ -1,10 +1,7 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { UserEditor } from '../UserEditor'
 
 export default async function NewUserPage() {
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.hasSystem('users.manage')) redirect('/admin')
+  const result = await requireAdminSession((r) => r.hasSystem('users.manage'), '/admin')
   return <UserEditor id="new" userName={result.session.user.name} />
 }

package/src/admin/pages/users.tsx

@@ -1,10 +1,7 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { UsersEditor } from '../UsersEditor'
 
 export default async function UsersPage() {
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.hasSystem('users.manage')) redirect('/admin')
+  const result = await requireAdminSession((r) => r.hasSystem('users.manage'), '/admin')
   return <UsersEditor userName={result.session.user.name} />
 }

package/src/admin/pages/webhooks-settings.tsx

@@ -1,10 +1,7 @@
-import { redirect } from 'next/navigation'
-import { getSessionWithPermissions } from '../../permissions'
+import { requireAdminSession } from '../require-session'
 import { WebhooksEditor } from '../WebhooksEditor'
 
 export default async function WebhooksPage() {
-  const result = await getSessionWithPermissions()
-  if (!result) redirect('/admin/login')
-  if (!result.hasSystem('developers.manage')) redirect('/admin/settings')
+  const result = await requireAdminSession((r) => r.hasSystem('developers.manage'), '/admin/settings')
   return <WebhooksEditor userName={result.session.user.name} />
 }

package/src/admin/require-session.ts

@@ -0,0 +1,21 @@
+import { redirect } from 'next/navigation'
+import { getSessionWithPermissions, type SessionWithPermissions } from '../permissions'
+
+/** For Server Component admin pages only — `redirect()` from `next/navigation` only works
+ *  inside the RSC render tree, never call this from a Route Handler (use `requireAction`/
+ *  `requireSystem` from `../permissions` there instead, which return null on failure and let
+ *  the route decide how to respond).
+ *
+ *  Replaces the repeated
+ *    const result = await getSessionWithPermissions()
+ *    if (!result) redirect('/admin/login')
+ *    if (!result.can(...)) redirect('/admin/dashboard')
+ *  pattern with one call. `check` is optional — omit it for a page that only needs "is logged
+ *  in" (its real authorization logic is more than a single predicate, e.g. it depends on data
+ *  computed from the session first). */
+export async function requireAdminSession(check?: (result: SessionWithPermissions) => boolean, redirectTo = '/admin/dashboard'): Promise<SessionWithPermissions> {
+  const result = await getSessionWithPermissions()
+  if (!result) redirect('/admin/login')
+  if (check && !check(result)) redirect(redirectTo)
+  return result
+}

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,
 }))
 `
@@ -128,11 +262,92 @@ function migrate() {
   console.log('\nRun your own `db:generate`/`db:migrate` next for this app\'s own content tables.')
 }
 
+// --- init -----------------------------------------------------------------------------------
+
+function parseFlags(argv) {
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg.startsWith('--')) flags[arg.slice(2)] = argv[i + 1]
+  }
+  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
+
+  if (!token) fail('missing --token (or set CMS_SETUP_TOKEN in your environment before running this).')
+  if (!name || !email || !password) fail('usage: kilo-cms init --name "..." --email you@example.com --password "..." [--url http://localhost:3000] [--token ...]')
+
+  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.)')
+
+  let response
+  try {
+    response = await fetch(`${url}/api/setup/admin`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+      body: JSON.stringify({ name, email, password }),
+    })
+  } catch (error) {
+    fail(`could not reach ${url} — is the app running? (${error instanceof Error ? error.message : String(error)})`)
+    return
+  }
+
+  const body = await response.json().catch(() => null)
+  if (!response.ok) fail(`setup failed (${response.status}): ${body?.error ?? 'unknown error'}`)
+
+  console.log(`\nDone — admin user created (${email}). You can log in at ${url}/admin/login.`)
+}
+
 // --- dispatch -------------------------------------------------------------------------------
 
 switch (command) {
   case 'add-collection':
-    addCollection(args[0])
+    addCollection(args[0], parseFlags(args.slice(1)))
     break
   case 'sync':
     sync()
@@ -140,10 +355,27 @@ switch (command) {
   case 'migrate':
     migrate()
     break
+  case 'init':
+    await init(args)
+    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 migrate                 apply kilo-cms's own package-owned migrations
+  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/middleware.ts

@@ -0,0 +1,28 @@
+import { NextResponse, type NextRequest } from 'next/server'
+import { getSessionCookie } from 'better-auth/cookies'
+
+/** Optimistic, Edge-safe redirect for unauthenticated requests to admin pages — a fast
+ *  pre-filter based on cookie PRESENCE only (`getSessionCookie` reads the cookie, no DB call,
+ *  safe to run in Edge middleware where a raw Postgres connection isn't available). This is
+ *  NOT the real security boundary: a forged or expired cookie passes this check. Every admin
+ *  page still calls `requireAdminSession()` (pages) or `requireAction`/`requireSystem` (API
+ *  routes), which validate the session for real and check actual RBAC permissions — this only
+ *  saves an unauthenticated visitor the round trip of hitting a page that would reject them
+ *  anyway, and centralizes what used to be an `if (!result) redirect('/admin/login')` repeated
+ *  on every single admin page.
+ *
+ *  The host's own `middleware.ts` re-exports this as `middleware` and defines `config.matcher`
+ *  itself (Next.js statically analyzes `matcher` at build time — it has to be a literal array
+ *  in the file Next.js is scanning, not re-exported through another module). */
+export function kiloAdminMiddleware(request: NextRequest): NextResponse {
+  const { pathname } = request.nextUrl
+  if (pathname === '/admin/login') return NextResponse.next()
+
+  const sessionCookie = getSessionCookie(request)
+  if (!sessionCookie) {
+    const url = request.nextUrl.clone()
+    url.pathname = '/admin/login'
+    return NextResponse.redirect(url)
+  }
+  return NextResponse.next()
+}

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 }
+}