create-theokit 1.0.6 → 1.0.8

package/templates/default/dot-claude/skills/theokit-database/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: theokit-database
+description: TheoKit database — Drizzle ORM, SQLite schema, migrations, seeds, db commands
+user-invocable: false
+paths:
+  - "**/*schema*"
+  - "**/*db*"
+  - "**/drizzle*"
+  - "**/*migration*"
+  - "**/*seed*"
+---
+
+# TheoKit Database (Drizzle + SQLite)
+
+## Schema Definition
+
+```typescript
+// server/db/schema.ts
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
+
+export const tasks = sqliteTable('tasks', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  title: text('title').notNull(),
+  done: integer('done', { mode: 'boolean' }).notNull().default(false),
+  createdAt: text('created_at').notNull().default(sql`CURRENT_TIMESTAMP`),
+})
+
+export const users = sqliteTable('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  email: text('email').notNull().unique(),
+  name: text('name').notNull(),
+})
+```
+
+## DB Connection
+
+```typescript
+// server/db/index.ts
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import Database from 'better-sqlite3'
+import * as schema from './schema.js'
+
+const sqlite = new Database('data/dev.db')
+export const db = drizzle(sqlite, { schema })
+```
+
+## Common Queries
+
+```typescript
+import { db } from '@/server/db'
+import { tasks } from '@/server/db/schema'
+import { eq } from 'drizzle-orm'
+
+// Select all
+db.select().from(tasks).all()
+
+// Select by ID
+db.select().from(tasks).where(eq(tasks.id, 1)).get()
+
+// Insert + return
+db.insert(tasks).values({ title: 'New task' }).returning().get()
+
+// Update
+db.update(tasks).set({ done: true }).where(eq(tasks.id, 1)).run()
+
+// Delete
+db.delete(tasks).where(eq(tasks.id, 1)).run()
+```
+
+## Seeds
+
+```typescript
+// server/db/seed.ts
+import { db } from './index.js'
+import { tasks } from './schema.js'
+
+await db.insert(tasks).values([
+  { title: 'Learn TheoKit', done: false },
+  { title: 'Build an agent', done: false },
+]).run()
+
+console.log('Seeded database')
+```
+
+Run: `npm run seed` or `npx tsx server/db/seed.ts`
+
+## CLI Commands
+
+```bash
+npx drizzle-kit push    # Apply schema changes to dev DB (no migration files)
+npx drizzle-kit generate # Generate SQL migration files (for production)
+npm run seed             # Run seed script
+```
+
+## Scaffolding Resources
+
+```bash
+npx theokit generate resource posts title:string published:boolean
+# Creates: server/db/schema.ts (appends table)
+#          server/routes/posts/index.ts (GET + POST)
+#          server/routes/posts/[id].ts (GET + PUT + DELETE)
+#          tests/posts.test.ts (smoke test)
+```
+
+Supported field types: `string`, `text`, `number`, `boolean`
+
+## Anti-patterns
+
+- NEVER use raw SQL for schema — use Drizzle's schema builder
+- NEVER delete `data/dev.db` to apply changes — use `npx drizzle-kit push`
+- NEVER put DB connection logic in route files — import from `server/db/index.ts`
+- NEVER use `id`, `createdAt`, or `created_at` as field names in `generate resource` — they're auto-added

package/templates/default/dot-claude/skills/theokit-frontend/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: theokit-frontend
+description: TheoKit frontend — file-based routing, layouts, theoFetch typed client, useAgentStream, React patterns
+user-invocable: false
+paths:
+  - "app/**"
+---
+
+# TheoKit Frontend (React + File-Based Routing)
+
+## File-Based Routing
+
+| File | URL | Purpose |
+|------|-----|---------|
+| `app/page.tsx` | `/` | Home page |
+| `app/layout.tsx` | (wrapper) | Root layout (wraps all pages) |
+| `app/error.tsx` | (error) | Error boundary |
+| `app/loading.tsx` | (loading) | Suspense fallback |
+| `app/not-found.tsx` | (404) | Not found page |
+| `app/about/page.tsx` | `/about` | Nested route |
+| `app/tasks/[id]/page.tsx` | `/tasks/:id` | Dynamic route |
+
+## Typed API Client (theoFetch)
+
+```typescript
+import { theoFetch } from 'theokit/client'
+
+// Typed fetch — params and response inferred from server routes
+const tasks = await theoFetch('/api/tasks')
+const task = await theoFetch('/api/tasks/:id', { params: { id: 1 } })
+
+// POST with body
+const created = await theoFetch('/api/tasks', {
+  method: 'POST',
+  body: { title: 'New task' },
+})
+```
+
+## App Client (proxy-based)
+
+```typescript
+import { createAppClient } from 'theokit/client'
+
+const client = createAppClient()
+
+// Proxy pattern — method names match route structure
+const tasks = await client.tasks.GET()
+const task = await client.tasks[':id'].GET({ params: { id: 1 } })
+const created = await client.tasks.POST({ body: { title: 'New' } })
+```
+
+## Agent Streaming (useAgentStream)
+
+```typescript
+import { useAgentStream } from 'theokit/client'
+
+function ChatComponent() {
+  const { status, events, send, reset } = useAgentStream('/api/agents/assistant')
+
+  return (
+    <div>
+      {status === 'streaming' && <p>Thinking...</p>}
+      {events.map(event => (
+        <div key={event.id}>
+          {event.type === 'message' && <p>{event.content}</p>}
+          {event.type === 'tool_call' && <p>Using tool: {event.name}</p>}
+        </div>
+      ))}
+      <input onSubmit={e => send({ message: e.target.value })} />
+    </div>
+  )
+}
+```
+
+## Path Aliases
+
+```typescript
+import { db } from '@/server/db'          // @/ = project root
+import { tasks } from '@/server/db/schema'
+```
+
+Configured in `tsconfig.json` — works in both server and app code.
+
+## Anti-patterns
+
+- NEVER use `fetch('/api/...')` directly — use `theoFetch` for type safety
+- NEVER create pages outside `app/` — they won't be discovered by the router
+- NEVER import server code directly in `app/` — use theoFetch or server actions
+- NEVER use `useEffect` + `fetch` for data loading — use theoFetch or useAgentStream

package/templates/default/dot-claude/skills/theokit-routes/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: theokit-routes
+description: TheoKit server routes — defineRoute, Zod validation, HTTP methods, dynamic params, error handling
+user-invocable: false
+paths:
+  - "server/routes/**"
+  - "server/actions/**"
+---
+
+# TheoKit Routes
+
+## defineRoute API
+
+```typescript
+import { defineRoute } from 'theokit/server/define'
+import { z } from 'zod'
+
+// GET handler — no body, optional params/query
+export const GET = defineRoute({
+  params: z.object({ id: z.coerce.number() }),   // URL params
+  query: z.object({ page: z.coerce.number().optional() }), // Query string
+  handler: ({ params, query }) => {
+    return { id: params.id, page: query?.page }
+  },
+})
+
+// POST handler — with body validation + custom status
+export const POST = defineRoute({
+  body: z.object({
+    title: z.string().min(3),
+    done: z.boolean().default(false),
+  }),
+  status: 201,
+  handler: ({ body }) => {
+    // body is fully typed from Zod schema
+    return db.insert(tasks).values(body).returning().get()
+  },
+})
+
+// PUT, DELETE follow the same pattern
+export const PUT = defineRoute({ body: z.object({...}), handler: ({body, params}) => {...} })
+export const DELETE = defineRoute({ params: z.object({id: z.coerce.number()}), handler: ({params}) => {...} })
+```
+
+## File-to-URL Mapping
+
+| File path | URL | Notes |
+|-----------|-----|-------|
+| `server/routes/health.ts` | `GET /api/health` | Static route |
+| `server/routes/tasks/index.ts` | `/api/tasks` | Index route (GET + POST) |
+| `server/routes/tasks/[id].ts` | `/api/tasks/:id` | Dynamic param |
+| `server/routes/users/[...slug].ts` | `/api/users/*` | Catch-all |
+
+## defineAction (Server Actions)
+
+```typescript
+import { defineAction } from 'theokit/server/define'
+import { z } from 'zod'
+
+export const createTask = defineAction({
+  input: z.object({ title: z.string() }),
+  handler: ({ input }) => {
+    return db.insert(tasks).values(input).returning().get()
+  },
+})
+```
+
+## Error Handling
+
+```typescript
+import { TheoError } from 'theokit'
+
+export const GET = defineRoute({
+  handler: ({ params }) => {
+    const task = db.select().from(tasks).where(eq(tasks.id, params.id)).get()
+    if (!task) throw new TheoError({ code: 'NOT_FOUND', message: 'Task not found' })
+    return task
+  },
+})
+```
+
+Valid error codes: `BAD_REQUEST` (400), `UNAUTHORIZED` (401), `FORBIDDEN` (403), `NOT_FOUND` (404), `CONFLICT` (409), `UNPROCESSABLE_ENTITY` (422), `TOO_MANY_REQUESTS` (429), `INTERNAL_SERVER_ERROR` (500).
+
+## Anti-patterns
+
+- NEVER use `res.status().json()` — use defineRoute with `status:` option
+- NEVER parse `req.body` manually — use `body: z.object(...)` in defineRoute
+- NEVER create routes outside `server/routes/` — they won't be discovered
+- NEVER export non-HTTP-method names — only `GET`, `POST`, `PUT`, `DELETE`, `PATCH`

package/templates/default/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  schema: './server/db/schema.ts',
+  out: './drizzle',
+  dialect: 'sqlite',
+  dbCredentials: {
+    url: './data/dev.db',
+  },
+})

package/templates/default/eslint.config.mjs

@@ -1,14 +1,18 @@
 import tseslint from 'typescript-eslint'
 import prettierConfig from 'eslint-config-prettier'
+import drizzle from 'eslint-plugin-drizzle'
 
 export default tseslint.config(
-  { ignores: ['dist/', 'node_modules/'] },
+  { ignores: ['dist/', 'node_modules/', 'drizzle/'] },
   ...tseslint.configs.recommended,
   prettierConfig,
   {
+    plugins: { drizzle },
     rules: {
       '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
       '@typescript-eslint/no-explicit-any': 'warn',
+      'drizzle/enforce-delete-with-where': 'error',
+      'drizzle/enforce-update-with-where': 'error',
     },
   },
 )

package/templates/default/package.json.tmpl

@@ -7,6 +7,11 @@
     "dev": "theokit dev",
     "build": "theokit build",
     "start": "theokit start",
+    "test": "vitest run",
+    "seed": "npx tsx server/db/seed.ts",
+    "db:migrate": "theokit db migrate",
+    "db:generate": "theokit db generate",
+    "db:seed": "npx tsx server/db/seed.ts",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
@@ -18,16 +23,21 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-router": "^7.0.0",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "drizzle-orm": "^0.44.0",
+    "better-sqlite3": "^12.0.0"
   },
   "devDependencies": {
-    "@swc/core": "^1.3.0",
+    "@types/better-sqlite3": "^7.6.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "drizzle-kit": "^0.30.0",
     "eslint": "^9.0.0",
     "eslint-config-prettier": "^10.0.0",
+    "eslint-plugin-drizzle": "^0.2.0",
     "prettier": "^3.0.0",
     "typescript": "^5.5.0",
-    "typescript-eslint": "^8.0.0"
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0"
   }
 }

package/templates/default/public/index.html

@@ -0,0 +1,70 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>TheoKit App</title>
+<style>
+:root{--bg:#0a0a0a;--card:#141414;--border:#2a2a2a;--text:#e0e0e0;--muted:#888;--accent:#6366f1;--green:#22c55e;--red:#ef4444;--yellow:#eab308}
+*{margin:0;padding:0;box-sizing:border-box}body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;background:var(--bg);color:var(--text);min-height:100vh}
+#app{max-width:1200px;margin:0 auto;padding:20px}h1{font-size:1.6rem}.accent{color:var(--accent)}.subtitle{color:var(--muted);font-size:.85rem;margin-top:2px}
+.role-bar{margin:12px 0}.role-bar select{padding:6px 12px;background:#1a1a1a;border:1px solid var(--border);border-radius:6px;color:var(--text);font-size:.8rem}
+.grid{display:grid;grid-template-columns:1fr 1fr;gap:20px}@media(max-width:768px){.grid{grid-template-columns:1fr}}
+.card{background:var(--card);border:1px solid var(--border);border-radius:12px;padding:20px}
+h2{font-size:1rem;margin-bottom:14px;display:flex;align-items:center;gap:8px}.badge{font-size:.65rem;padding:2px 8px;border-radius:99px;background:#6366f122;color:var(--accent)}.badge-ai{background:#eab30822;color:var(--yellow)}
+table{width:100%;border-collapse:collapse;font-size:.85rem}th{text-align:left;padding:8px 4px;color:var(--muted);border-bottom:1px solid var(--border);font-weight:500}td{padding:8px 4px;border-bottom:1px solid var(--border)}
+tr.done td{opacity:.5;text-decoration:line-through}.prio{font-size:.7rem;padding:2px 8px;border-radius:99px}.prio-high{background:#ef444422;color:var(--red)}.prio-med{background:#eab30822;color:var(--yellow)}.prio-low{background:#22c55e22;color:var(--green)}
+.create-bar{display:flex;gap:8px;margin-top:14px}.create-bar input{flex:1;padding:8px 12px;background:#1a1a1a;border:1px solid var(--border);border-radius:6px;color:var(--text);font-size:.85rem}
+.create-bar select{padding:8px;background:#1a1a1a;border:1px solid var(--border);border-radius:6px;color:var(--text);font-size:.8rem}.create-bar button{padding:8px 16px;background:var(--accent);color:#fff;border:none;border-radius:6px;cursor:pointer;font-weight:600}
+.error{color:var(--red);font-size:.8rem;margin-top:4px}
+.chat-box{height:400px;overflow-y:auto;padding:12px;background:#0d0d0d;border-radius:8px;margin-bottom:10px;font-size:.85rem;line-height:1.6}
+.msg{margin-bottom:10px;padding:8px 12px;border-radius:8px}.msg.user{background:#6366f118;color:var(--accent)}.msg.agent{background:#1a1a1a}.msg.tool{background:#eab30810;color:var(--yellow);font-size:.78rem;font-family:monospace}.msg.system{color:var(--muted);font-size:.78rem;font-style:italic}.msg.error{color:var(--red)}
+.chat-bar{display:flex;gap:8px}.chat-bar input{flex:1;padding:10px 14px;background:#1a1a1a;border:1px solid var(--border);border-radius:8px;color:var(--text);font-size:.9rem;outline:none}.chat-bar input:focus{border-color:var(--accent)}
+.chat-bar button{padding:10px 20px;background:var(--accent);color:#fff;border:none;border-radius:8px;cursor:pointer;font-weight:600}.chat-bar button:disabled{opacity:.4;cursor:not-allowed}
+.cost{color:var(--muted);font-size:.75rem;margin-top:6px;text-align:right}
+</style>
+</head>
+<body>
+<div id="app">
+<header>
+<h1><span class="accent">TheoKit</span> App</h1>
+<p class="subtitle">Controllers + AI Agent — same pipeline</p>
+<div class="role-bar"><label>Role: </label><select id="role"><option value="">None</option><option value="user" selected>User</option><option value="admin">Admin</option></select></div>
+</header>
+<main class="grid">
+<section class="card">
+<h2>📋 Tasks <span class="badge">@Controller</span></h2>
+<table><thead><tr><th>Task</th><th>Priority</th><th>Status</th></tr></thead><tbody id="task-list"></tbody></table>
+<form id="create-form" class="create-bar"><input id="new-title" placeholder="New task..." required minlength="3"><select id="new-priority"><option value="medium">Medium</option><option value="high">High</option><option value="low">Low</option></select><button type="submit">Add</button></form>
+<p id="form-error" class="error"></p>
+</section>
+<section class="card">
+<h2>🤖 AI Assistant <span class="badge badge-ai">@Agent + SSE</span></h2>
+<div id="chat" class="chat-box"><div class="msg system">Ask me to list, create, or complete tasks...</div></div>
+<div class="chat-bar"><input id="chat-input" placeholder="Message the AI assistant..."><button id="chat-send">Send</button></div>
+<p id="chat-cost" class="cost"></p>
+</section>
+</main>
+</div>
+<script>
+const getRole=()=>document.getElementById('role').value
+const headers=()=>{const h={'Content-Type':'application/json'};const r=getRole();if(r)h['x-role']=r;return h}
+let sessionId='s-'+Date.now()
+
+async function loadTasks(){const r=await fetch('/api/tasks');const t=await r.json();document.getElementById('task-list').innerHTML=t.map(t=>{const s=t.done?'done':'';const p=t.priority==='high'?'prio-high':t.priority==='low'?'prio-low':'prio-med';return'<tr class="'+s+'"><td>'+(t.done?'✅ ':'○ ')+t.title+'</td><td><span class="prio '+p+'">'+t.priority+'</span></td><td>'+(t.done?'Done':'To do')+'</td></tr>'}).join('')}
+
+document.getElementById('create-form').addEventListener('submit',async e=>{e.preventDefault();const t=document.getElementById('new-title').value.trim();const p=document.getElementById('new-priority').value;const err=document.getElementById('form-error');err.textContent='';if(!t)return;const r=await fetch('/api/tasks',{method:'POST',headers:headers(),body:JSON.stringify({title:t,priority:p})});if(r.status===403){err.textContent='403 — Need User role';return}if(r.status===422){const e=await r.json();err.textContent=e.error?.issues?.[0]?.message||'Validation error';return}if(!r.ok){err.textContent='Error '+r.status;return}document.getElementById('new-title').value='';loadTasks()})
+
+document.getElementById('chat-send').addEventListener('click',sendChat)
+document.getElementById('chat-input').addEventListener('keydown',e=>{if(e.key==='Enter')sendChat()})
+
+async function sendChat(){const input=document.getElementById('chat-input');const msg=input.value.trim();if(!msg)return;input.value='';const chat=document.getElementById('chat');chat.innerHTML+='<div class="msg user">You: '+msg.replace(/</g,'&lt;')+'</div>';document.getElementById('chat-send').disabled=true
+try{const r=await fetch('/api/agents/assistant/chat',{method:'POST',headers:headers(),body:JSON.stringify({message:msg,sessionId})});if(r.status===403){chat.innerHTML+='<div class="msg system">403 — Need User role</div>';document.getElementById('chat-send').disabled=false;return}
+const reader=r.body.getReader();const dec=new TextDecoder();let div=document.createElement('div');div.className='msg agent';chat.appendChild(div);let buf=''
+while(true){const{done,value}=await reader.read();if(done)break;buf+=dec.decode(value,{stream:true});const lines=buf.split('\n');buf=lines.pop()||''
+for(const line of lines){if(!line.startsWith('data: '))continue;try{const ev=JSON.parse(line.slice(6));if(ev.type==='text_delta')div.innerHTML+=ev.content.replace(/</g,'&lt;').replace(/\*\*(.+?)\*\*/g,'<strong>$1</strong>').replace(/\n/g,'<br>');else if(ev.type==='tool_call'){const t=document.createElement('div');t.className='msg tool';t.textContent='🔧 '+ev.toolName;chat.insertBefore(t,div)}else if(ev.type==='tool_result'){const t=document.createElement('div');t.className='msg tool';t.textContent='✅ '+(ev.output||'').substring(0,80);chat.insertBefore(t,div)}else if(ev.type==='done'){document.getElementById('chat-cost').textContent=(ev.usage?.totalTokens||0)+' tokens · '+(ev.durationMs||0)+'ms'+(ev.cost?' · $'+ev.cost.toFixed(6):'')}else if(ev.type==='error'){chat.innerHTML+='<div class="msg error">'+ev.message+'</div>'}}catch{}}
+chat.scrollTop=chat.scrollHeight}loadTasks()}catch(e){chat.innerHTML+='<div class="msg error">'+e.message+'</div>'}document.getElementById('chat-send').disabled=false;chat.scrollTop=chat.scrollHeight}
+
+loadTasks()
+</script>
+</body>
+</html>

package/templates/default/server/agents/assistant.agent.ts

@@ -4,7 +4,11 @@
  * Uses the SAME guards and pipeline as HTTP controllers.
  * Tools from @Mixin(TaskTools) are available to the LLM.
  */
-import { Agent, MainLoop, Mixin, Memory, Budget, Hook } from '@theokit/agents'
+import 'reflect-metadata'
+import {
+  Agent, MainLoop, Mixin,
+  Memory, Budget, Hook,
+} from '@theokit/agents'
 import { UseGuards, UseInterceptors } from '@theokit/http'
 import { RolesGuard, Roles, Role } from '../guards/auth.guard.js'
 import { TimingInterceptor } from '../interceptors/timing.interceptor.js'
@@ -21,7 +25,7 @@ Be concise and actionable.`,
 @UseInterceptors(TimingInterceptor)
 @Roles([Role.User])
 @Memory({ provider: 'built-in', scope: 'per-user' })
-@Budget({ maxCostUsd: 1.0, window: 'daily' })
+@Budget({ maxCostUsd: 1.00, window: 'daily' })
 @Mixin(TaskTools)
 export class AssistantAgent {
   @MainLoop({ strategy: 'react', maxIterations: 5 })

package/templates/default/server/controllers/tasks.controller.ts

@@ -5,20 +5,12 @@
  * @Param, @Query, @HttpCode, @UseGuards, @Roles, @IsPublic,
  * @UseInterceptors, @UseFilters, NotFoundException.
  */
+import 'reflect-metadata'
 import { z } from 'zod'
 import {
-  Controller,
-  Get,
-  Post,
-  Put,
-  Delete,
-  Body,
-  Param,
-  Query,
-  HttpCode,
-  UseGuards,
-  UseInterceptors,
-  UseFilters,
+  Controller, Get, Post, Put, Delete,
+  Body, Param, Query, HttpCode,
+  UseGuards, UseInterceptors, UseFilters,
   NotFoundException,
 } from '@theokit/http'
 import { RolesGuard, Roles, Role, IsPublic } from '../guards/auth.guard.js'
@@ -31,7 +23,7 @@ const zCreateTask = z.object({
   priority: z.enum(['low', 'medium', 'high']).default('medium'),
 })
 
-@Controller() // → /api/tasks (convention: inferred from TasksController)
+@Controller()  // → /api/tasks (convention: inferred from TasksController)
 @UseGuards(RolesGuard)
 @UseInterceptors(TimingInterceptor)
 @UseFilters(HttpErrorFilter)

package/templates/default/server/db/index.ts

@@ -0,0 +1,21 @@
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import Database from 'better-sqlite3'
+import { mkdirSync } from 'node:fs'
+import * as schema from './schema.js'
+
+mkdirSync('data', { recursive: true })
+const sqlite = new Database('data/dev.db')
+sqlite.pragma('journal_mode = WAL')
+
+export const db = drizzle(sqlite, { schema })
+
+// Auto-create tables (simple push — no migration files needed for dev)
+sqlite.exec(`
+  CREATE TABLE IF NOT EXISTS tasks (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    priority TEXT NOT NULL DEFAULT 'medium',
+    done INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL DEFAULT (date('now'))
+  )
+`)

package/templates/default/server/db/schema.ts

@@ -0,0 +1,13 @@
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
+
+export const tasks = sqliteTable('tasks', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  title: text('title').notNull(),
+  priority: text('priority', { enum: ['low', 'medium', 'high'] })
+    .notNull()
+    .default('medium'),
+  done: integer('done', { mode: 'boolean' }).notNull().default(false),
+  createdAt: text('created_at')
+    .notNull()
+    .$defaultFn(() => new Date().toISOString().split('T')[0]),
+})

package/templates/default/server/db/seed.ts

@@ -0,0 +1,29 @@
+import { db } from './index.js'
+import { tasks } from './schema.js'
+import { sql } from 'drizzle-orm'
+
+const seedData = [
+  {
+    title: 'Set up TheoKit project',
+    priority: 'high' as const,
+    done: true,
+    createdAt: '2026-01-01',
+  },
+  { title: 'Create first route', priority: 'high' as const, done: true, createdAt: '2026-01-02' },
+  { title: 'Add AI agent', priority: 'medium' as const, done: false, createdAt: '2026-01-03' },
+  { title: 'Deploy to production', priority: 'low' as const, done: false, createdAt: '2026-01-04' },
+]
+
+// Idempotent: only insert if table is empty
+const count = db
+  .select({ count: sql<number>`count(*)` })
+  .from(tasks)
+  .get()
+if (!count || count.count === 0) {
+  for (const task of seedData) {
+    db.insert(tasks).values(task).run()
+  }
+  console.log(`Seeded ${seedData.length} tasks`)
+} else {
+  console.log(`Tasks table already has ${count.count} rows — skipping seed`)
+}

package/templates/default/server/index.ts

@@ -1,18 +1,2 @@
-/**
- * Server module — auto-exports all controllers, agents, and providers.
- *
- * Convention: add your classes here. TheoApp.create() imports this one file.
- * Like Rails' application.rb — single entry point for the backend.
- *
- * When you run `theokit generate controller/agent/toolbox`, the generated
- * file is auto-added here.
- */
-
-// Controllers — HTTP API
-export { TasksController } from './controllers/tasks.controller.js'
-
-// Agents — AI endpoints
-export { AssistantAgent } from './agents/assistant.agent.js'
-
-// Providers — DI (toolboxes, services)
-export { TaskTools } from './toolboxes/task.tools.js'
+// Routes are auto-discovered from server/routes/ by theokit dev.
+// No manual registration needed — convention over configuration.

package/templates/default/server/routes/tasks/[id].ts

@@ -0,0 +1,36 @@
+import { defineRoute } from 'theokit/server/define'
+import { z } from 'zod'
+import { db } from '../../db/index.js'
+import { tasks } from '../../db/schema.js'
+import { eq } from 'drizzle-orm'
+
+export const GET = defineRoute({
+  params: z.object({ id: z.coerce.number() }),
+  handler: ({ params }) => {
+    const task = db.select().from(tasks).where(eq(tasks.id, params.id)).get()
+    if (!task) return new Response(JSON.stringify({ error: 'Task not found' }), { status: 404 })
+    return task
+  },
+})
+
+export const PUT = defineRoute({
+  params: z.object({ id: z.coerce.number() }),
+  body: z.object({
+    title: z.string().optional(),
+    priority: z.enum(['low', 'medium', 'high']).optional(),
+    done: z.boolean().optional(),
+  }),
+  handler: ({ params, body }) => {
+    const result = db.update(tasks).set(body).where(eq(tasks.id, params.id)).returning().get()
+    if (!result) return new Response(JSON.stringify({ error: 'Task not found' }), { status: 404 })
+    return result
+  },
+})
+
+export const DELETE = defineRoute({
+  params: z.object({ id: z.coerce.number() }),
+  status: 204,
+  handler: ({ params }) => {
+    db.delete(tasks).where(eq(tasks.id, params.id)).run()
+  },
+})

package/templates/default/server/routes/tasks/index.ts

@@ -0,0 +1,20 @@
+import { defineRoute } from 'theokit/server/define'
+import { z } from 'zod'
+import { db } from '../../db/index.js'
+import { tasks } from '../../db/schema.js'
+
+export const GET = defineRoute({
+  handler: () => db.select().from(tasks).all(),
+})
+
+export const POST = defineRoute({
+  body: z.object({
+    title: z.string().min(3, 'Title must be at least 3 characters'),
+    priority: z.enum(['low', 'medium', 'high']).default('medium'),
+  }),
+  status: 201,
+  handler: ({ body }) => {
+    const result = db.insert(tasks).values(body).returning().get()
+    return result
+  },
+})

package/templates/default/server/toolboxes/task.tools.ts

@@ -5,11 +5,12 @@
  * to interact with the task data. Each @Tool method is
  * compiled to a defineTool() call at startup.
  */
+import 'reflect-metadata'
 import { z } from 'zod'
 import { Toolbox, Tool, Trace, Audit } from '@theokit/agents'
 import { taskStore } from '../store.js'
 
-@Toolbox() // Convention: TaskTools → namespace: 'task'
+@Toolbox()  // Convention: TaskTools → namespace: 'task'
 @Trace(true)
 export class TaskTools {
   @Tool({

package/templates/default/tests/tasks.test.ts

@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest'
+
+describe('Tasks API', () => {
+  it('GET /api/tasks returns array', async () => {
+    const res = await fetch('http://localhost:3000/api/tasks')
+    expect(res.status).toBe(200)
+    const tasks = await res.json()
+    expect(Array.isArray(tasks)).toBe(true)
+  })
+})