create-theokit 0.1.0-alpha.12 → 0.1.0-alpha.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.13",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

package/templates/api-only/README.md.tmpl

@@ -0,0 +1,76 @@
+# {{name}}
+
+TheoKit API-only project. Backend routes with Zod validation + typed responses — no frontend bundle, no React.
+
+## Quick start
+
+```bash
+# 1. Set your provider key if you wire an agent route later
+echo 'OPENROUTER_API_KEY=sk-or-v1-...' > .env
+
+# 2. Boot the dev server
+npx theokit dev
+
+# 3. Probe the health route
+curl http://localhost:3000/api/health
+```
+
+You should see `{"status":"ok"}`. The server is now serving the routes under `server/routes/`.
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** — nested layouts + sidebar.
+- **api-only** (this one) — server routes without React.
+- **postgres** — Drizzle ORM + migrations.
+- **saas** — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. Edit `.env`; restart the dev server.
+- **`.theo/` build output cleanup** on every `theokit build`.
+- **Route discovery** — every `server/routes/*.ts` becomes a wired endpoint.
+
+## Project structure
+
+```
+server/
+├── routes/
+│   ├── health.ts     GET  /api/health  — returns {status:"ok"}
+│   └── users.ts      CRUD /api/users   — Zod-validated body
+theo.config.ts        Framework config
+.env                  Secrets — never committed (.gitignore)
+```
+
+## Sample requests
+
+```bash
+# Health check
+curl http://localhost:3000/api/health
+
+# Create a user (POST with JSON body)
+curl -X POST http://localhost:3000/api/users \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Alice","email":"alice@example.com"}'
+
+# List users
+curl http://localhost:3000/api/users
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR + structured logs |
+| `npx theokit build` | Production build → `.theo/` |
+| `npx theokit start` | Serve the production build |
+| `npx theokit routes` | List all routes detected |
+| `npm run typecheck` | TypeScript strict check (no emit) |
+
+## Add a new route
+
+Drop a `.ts` file in `server/routes/`. Use `defineRoute` from `theokit/server` for Zod-validated handlers, or export `GET`/`POST` directly.
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/api-only/package.json.tmpl

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.12",
+    "theokit": "^0.1.0-alpha.13",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
@@ -18,5 +18,10 @@
     "typescript": "^5.7.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/dashboard/README.md.tmpl

@@ -0,0 +1,74 @@
+# {{name}}
+
+TheoKit dashboard project. Build the app your agent lives in — with nested layouts and a sidebar wired from day one.
+
+## Quick start
+
+```bash
+# 1. Set your provider key (OpenRouter recommended — one key, any model)
+echo 'OPENROUTER_API_KEY=sk-or-v1-...' > .env
+
+# 2. Boot the dev server
+npx theokit dev
+```
+
+Open the printed URL. The default surface is a dashboard shell with sidebar nav + content area, ready to host your agent panels.
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** (this one) — nested layouts + sidebar nav.
+- **api-only** — server routes without React.
+- **postgres** — Drizzle ORM + migrations.
+- **saas** — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. Edit `.env`; restart the dev server.
+- **`.theo/` build output cleanup** on every `theokit build`.
+- **Tailwind + `@usetheo/ui` styling** auto-configured for the TheoUI surface.
+
+## Project structure
+
+```
+app/                  Frontend (file-based routing with nested layouts)
+├── layout.tsx        root wrapper — TheoUI provider + theme
+├── page.tsx          /              — dashboard home
+├── dashboard/
+│   ├── layout.tsx    /dashboard/*   — sidebar shell
+│   └── page.tsx      /dashboard     — primary panel
+server/               Backend (explicit routes)
+├── routes/
+│   └── health.ts     GET /api/health
+theo.config.ts        Framework config
+tailwind.config.ts    Tailwind theme tokens
+.env                  Secrets — never committed
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR + devtools overlay |
+| `npx theokit build` | Production build → `.theo/` |
+| `npx theokit start` | Serve the production build |
+| `npx theokit check` | Lint for upgrade-readiness |
+| `npx theokit routes` | List all routes + actions detected |
+| `npm run typecheck` | TypeScript strict check (no emit) |
+
+## Add a new panel
+
+```bash
+mkdir -p app/dashboard/billing
+cat > app/dashboard/billing/page.tsx <<'EOF'
+export default function BillingPage() {
+  return <h2>Billing</h2>
+}
+EOF
+```
+
+The route appears at `/dashboard/billing` after HMR.
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/dashboard/package.json.tmpl

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.12",
+    "theokit": "^0.1.0-alpha.13",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
@@ -18,5 +18,10 @@
     "typescript": "^5.7.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/default/package.json.tmpl

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.12",
+    "theokit": "^0.1.0-alpha.13",
     "@usetheo/sdk": "^1.2.0",
     "@usetheo/ui": "^0.12.0-next.0",
     "lucide-react": "^0.469.0",
@@ -25,5 +25,10 @@
     "@types/react-dom": "^19.0.0",
     "tailwindcss": "^4.0.0",
     "@tailwindcss/vite": "^4.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/postgres/README.md.tmpl

@@ -0,0 +1,81 @@
+# {{name}}
+
+TheoKit project with Postgres + Drizzle ORM wired. Schema-first, migration-aware, typed end-to-end.
+
+## Quick start
+
+```bash
+# 0. Provision Postgres
+#    Option A — local docker (one-liner):
+docker run --name pg -e POSTGRES_PASSWORD=dev -p 5432:5432 -d postgres:16
+#    Option B — hosted: neon.tech, supabase.com, fly.io
+
+# 1. Set env
+cat > .env <<'EOF'
+DATABASE_URL=postgres://postgres:dev@localhost:5432/postgres
+OPENROUTER_API_KEY=sk-or-v1-...
+EOF
+
+# 2. Generate + apply migrations
+pnpm db:generate
+pnpm db:migrate
+
+# 3. Boot the dev server
+npx theokit dev
+```
+
+Open the printed URL. The default surface includes a sample users API backed by Postgres.
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** — nested layouts + sidebar.
+- **api-only** — server routes without React.
+- **postgres** (this one) — Drizzle ORM + migrations.
+- **saas** — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. `DATABASE_URL` must be set before `pnpm db:migrate`.
+- **`.theo/` build output cleanup** on every `theokit build`.
+- **Drizzle schema** under `db/schema.ts` drives migrations + typed query builder.
+
+## Project structure
+
+```
+app/                  Frontend
+├── page.tsx          /              — sample UI
+server/
+├── routes/
+│   ├── health.ts     GET  /api/health
+│   └── users.ts      CRUD /api/users  — backed by db.users
+db/
+├── schema.ts         Drizzle schema (tables + relations)
+├── client.ts         Drizzle client (used by routes)
+└── migrations/       Generated SQL files (committed)
+drizzle.config.ts     Drizzle CLI config
+theo.config.ts        Framework config
+.env                  Secrets — never committed
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR |
+| `npx theokit build` | Production build |
+| `npx theokit start` | Serve production build |
+| `pnpm db:generate` | Generate SQL migration from `db/schema.ts` |
+| `pnpm db:migrate` | Apply pending migrations to `DATABASE_URL` |
+| `pnpm db:studio` | Open Drizzle Studio UI |
+| `npm run typecheck` | TypeScript strict check |
+
+## Troubleshooting
+
+- **`pnpm db:migrate` fails with "ECONNREFUSED"** → check `DATABASE_URL` host:port + Postgres is running (`docker ps` or hosted dashboard).
+- **`relation "users" does not exist`** → you forgot `pnpm db:migrate`. Run it.
+- **Schema change not reflected** → `pnpm db:generate` first, then `pnpm db:migrate`.
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/postgres/package.json.tmpl

@@ -14,7 +14,7 @@
     "db:studio": "drizzle-kit studio"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.12",
+    "theokit": "^0.1.0-alpha.13",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "drizzle-orm": "^0.45.0",
@@ -26,5 +26,10 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "drizzle-kit": "^0.31.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/saas/README.md.tmpl

@@ -0,0 +1,101 @@
+# {{name}}
+
+TheoKit SaaS template — auth, sessions, billing-ready, and an agent route. The full stack for shipping an account-aware product on day one.
+
+## Quick start
+
+```bash
+# 0. Provision Postgres (sessions + users)
+docker run --name pg -e POSTGRES_PASSWORD=dev -p 5432:5432 -d postgres:16
+# Or use a hosted Postgres (neon.tech / supabase.com)
+
+# 1. Set env (generate a strong session secret)
+cat > .env <<EOF
+DATABASE_URL=postgres://postgres:dev@localhost:5432/postgres
+SESSION_SECRET=$(openssl rand -base64 32)
+OPENROUTER_API_KEY=sk-or-v1-...
+EOF
+
+# 2. Migrate the schema
+pnpm db:generate
+pnpm db:migrate
+
+# 3. Boot the dev server
+npx theokit dev
+```
+
+## Sample auth flow
+
+```bash
+# Register
+curl -X POST http://localhost:3000/api/register \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"alice@example.com","password":"strong-passphrase"}'
+
+# Login (saves session cookie)
+curl -X POST http://localhost:3000/api/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"alice@example.com","password":"strong-passphrase"}' \
+  -c cookies.txt
+
+# Authenticated request
+curl http://localhost:3000/api/me -b cookies.txt
+```
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** — nested layouts + sidebar.
+- **api-only** — server routes without React.
+- **postgres** — Drizzle ORM + migrations.
+- **saas** (this one) — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. `SESSION_SECRET`, `DATABASE_URL`, `OPENROUTER_API_KEY` all required.
+- **Encrypted sessions** (AES-256-GCM) via `SESSION_SECRET`.
+- **`.theo/` build output cleanup** on every `theokit build`.
+
+## Project structure
+
+```
+app/                  Frontend
+├── page.tsx          /            — landing
+server/
+├── routes/
+│   ├── login.ts      POST /api/login    — sets session cookie
+│   ├── logout.ts     POST /api/logout   — clears session
+│   ├── me.ts         GET  /api/me       — requireAuth() guarded
+│   └── agent.ts      POST /api/agent    — agent SSE, requireAuth()
+db/
+├── schema.ts         users + sessions tables (Drizzle)
+└── migrations/       generated SQL (committed)
+drizzle.config.ts     Drizzle config
+theo.config.ts        Framework config
+.env                  Secrets — never committed
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR + auth |
+| `npx theokit build` | Production build |
+| `npx theokit start` | Serve production build |
+| `pnpm db:generate` | Generate SQL migration |
+| `pnpm db:migrate` | Apply migrations |
+| `npm run typecheck` | TypeScript strict check |
+
+## Adding billing
+
+Stripe is the canonical path — add `STRIPE_SECRET_KEY` to `.env`, mount `server/routes/billing/webhook.ts` via `defineWebhook`, and wire plan checks into `requireAuth()`.
+
+## Troubleshooting
+
+- **`SESSION_SECRET must be at least 32 bytes`** → regenerate with `openssl rand -base64 32`.
+- **`relation "users" does not exist`** → run `pnpm db:migrate` first.
+- **`401 Unauthorized` on `/api/me`** → login first; cookie must be sent (`-b cookies.txt`).
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/saas/package.json.tmpl

@@ -14,7 +14,7 @@
     "db:studio": "drizzle-kit studio"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.12",
+    "theokit": "^0.1.0-alpha.13",
     "@usetheo/ui": "^0.12.0-next.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -28,5 +28,10 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "drizzle-kit": "^0.31.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }