create-theokit 1.0.9 → 1.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

package/templates/default/AGENTS.md

@@ -10,18 +10,14 @@ This is a **full-stack TypeScript app** built with TheoKit — a framework for A
 server/
   routes/             → HTTP API routes (defineRoute + Zod validation)
     health.ts         → GET /api/health
-    tasks/
-      index.ts        → GET /api/tasks (list) + POST /api/tasks (create)
-      [id].ts         → GET/PUT/DELETE /api/tasks/:id
   db/
-    schema.ts         → Drizzle ORM schema (SQLite)
-    index.ts          → DB connection + auto-create tables
-    seed.ts           → Seed data (run with `npm run seed`)
+    schema.ts         → Drizzle ORM schema (SQLite) — empty, add your tables
+    index.ts          → DB connection (better-sqlite3, WAL mode)
 app/
   page.tsx            → React frontend
   layout.tsx          → Root layout
 tests/
-  tasks.test.ts       → Example API smoke test
+  tasks.test.ts       → Example unit test
 ```
 
 ## Key Patterns
@@ -32,13 +28,13 @@ import { defineRoute } from 'theokit/server/define'
 import { z } from 'zod'
 
 export const GET = defineRoute({
-  handler: () => db.select().from(tasks).all(),
+  handler: () => db.select().from(posts).all(),
 })
 
 export const POST = defineRoute({
   body: z.object({ title: z.string().min(3) }),
   status: 201,
-  handler: ({ body }) => db.insert(tasks).values(body).returning().get(),
+  handler: ({ body }) => db.insert(posts).values(body).returning().get(),
 })
 ```
 
@@ -46,25 +42,30 @@ export const POST = defineRoute({
 ```typescript
 import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
 
-export const tasks = sqliteTable('tasks', {
+export const posts = sqliteTable('posts', {
   id: integer('id').primaryKey({ autoIncrement: true }),
   title: text('title').notNull(),
-  done: integer('done', { mode: 'boolean' }).notNull().default(false),
+  published: integer('published', { mode: 'boolean' }).notNull().default(false),
 })
 ```
 
+### Scaffold a Resource
+```bash
+npx theokit generate resource posts title:string published:boolean
+# Creates: schema table + routes (CRUD) + test
+```
+
 ### Validation
 - **Zod is the single source of truth** — define schema once, get types + validation + OpenAPI
 - `body: z.object(...)` in defineRoute validates automatically, returns 422 on failure
 - Use `z.infer<typeof schema>` for TypeScript types
 
 ### Dynamic Routes
-- `server/routes/tasks/[id].ts` → `/api/tasks/:id`
+- `server/routes/posts/[id].ts` → `/api/posts/:id`
 - Params validated with `params: z.object({ id: z.coerce.number() })`
 
 ### Path Aliases
 - `@/*` → project root (configured in tsconfig.json)
-- `@/server/*` → `./server/*`
 
 ## Commands
 
@@ -73,10 +74,12 @@ npm run dev          # Start dev server
 npm run build        # Build for production
 npm run start        # Run production build
 npm run test         # Run tests (vitest)
-npm run seed         # Seed database with sample data
 npm run lint         # ESLint check
 npm run format       # Prettier format
 npm run typecheck    # TypeScript type check
+npx theokit generate resource <name> <fields...>  # Scaffold CRUD resource
+npx drizzle-kit push      # Apply schema changes (dev)
+npx drizzle-kit generate  # Generate migration files (prod)
 ```
 
 ## Don't
@@ -84,3 +87,5 @@ npm run typecheck    # TypeScript type check
 - Don't use `any` — use Zod schemas + `z.infer<>`
 - Don't write raw `res.status().json()` — use defineRoute with status option
 - Don't parse request body manually — use `body: z.object(...)` in defineRoute
+- Don't import from `theokit/dist/...` or `theokit/src/...` — use public exports only
+- Don't call LLM APIs directly — use @Agent + @Tool decorators

package/templates/default/app/page.tsx

@@ -1,51 +1,7 @@
-'use client'
-
-import { useState, useEffect, useCallback, type FormEvent } from 'react'
-
-interface Task {
-  id: number
-  title: string
-  priority: 'high' | 'medium' | 'low'
-  done: boolean
-}
-
 export default function Page() {
-  const [tasks, setTasks] = useState<Task[]>([])
-  const [title, setTitle] = useState('')
-  const [priority, setPriority] = useState<Task['priority']>('medium')
-  const [formError, setFormError] = useState('')
-
-  const loadTasks = useCallback(async () => {
-    const res = await fetch('/api/tasks')
-    if (res.ok) setTasks(await res.json())
-  }, [])
-
-  useEffect(() => {
-    loadTasks()
-  }, [loadTasks])
-
-  const createTask = async (e: FormEvent) => {
-    e.preventDefault()
-    setFormError('')
-    if (!title.trim()) return
-    const res = await fetch('/api/tasks', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ title, priority }),
-    })
-    if (!res.ok) {
-      const b = await res.json()
-      setFormError(b.error?.issues?.[0]?.message ?? `Error ${res.status}`)
-      return
-    }
-    setTitle('')
-    loadTasks()
-  }
-
   return (
     <div className="page">
       <div className="main">
-        {/* Hero */}
         <header className="hero">
           <img src="/logo.png" alt="TheoKit" width={72} height={72} className="hero-logo" />
           <h1>TheoKit</h1>
@@ -73,61 +29,11 @@ export default function Page() {
           </p>
         </header>
 
-        {/* Tasks */}
-        <section className="card">
-          <h2>
-            Tasks <span className="badge">defineRoute + Drizzle</span>
-          </h2>
-          <table>
-            <thead>
-              <tr>
-                <th>Task</th>
-                <th>Priority</th>
-                <th>Status</th>
-              </tr>
-            </thead>
-            <tbody>
-              {tasks.map((t) => (
-                <tr key={t.id} className={t.done ? 'done' : ''}>
-                  <td>
-                    {t.done ? '✅ ' : '○ '}
-                    {t.title}
-                  </td>
-                  <td>
-                    <span className={`prio prio-${t.priority}`}>{t.priority}</span>
-                  </td>
-                  <td>{t.done ? 'Done' : 'To do'}</td>
-                </tr>
-              ))}
-            </tbody>
-          </table>
-          <form onSubmit={createTask} className="create-bar">
-            <input
-              value={title}
-              onChange={(e) => setTitle(e.target.value)}
-              placeholder="New task..."
-              required
-              minLength={3}
-            />
-            <select
-              value={priority}
-              onChange={(e) => setPriority(e.target.value as Task['priority'])}
-            >
-              <option value="medium">Medium</option>
-              <option value="high">High</option>
-              <option value="low">Low</option>
-            </select>
-            <button type="submit">Add</button>
-          </form>
-          {formError && <p className="error">{formError}</p>}
-        </section>
-
-        {/* Features */}
         <div className="grid features">
           <div className="feature">
             <h3>defineRoute</h3>
             <p>
-              Typed API routes with Zod validation. See <code>server/routes/tasks/</code>
+              Typed API routes with Zod validation. See <code>server/routes/</code>
             </p>
           </div>
           <div className="feature">
@@ -146,7 +52,6 @@ export default function Page() {
           </div>
         </div>
 
-        {/* Footer */}
         <footer className="footer">
           Powered by{' '}
           <a href="https://usetheo.dev" target="_blank" rel="noopener noreferrer">
@@ -156,10 +61,6 @@ export default function Page() {
           <a href="https://github.com/usetheodev/theokit" target="_blank" rel="noopener noreferrer">
             GitHub
           </a>
-          {' · '}
-          <a href="https://discord.usetheo.dev" target="_blank" rel="noopener noreferrer">
-            Discord
-          </a>
         </footer>
       </div>
     </div>

package/templates/default/app.ts

@@ -1,24 +1,15 @@
 /**
- * TheoKit App — convention over configuration.
+ * TheoKit App — manual bootstrap (optional).
  *
- * "The framework that reduces noise for humans + AI."
+ * `theokit dev` auto-discovers server/routes/ — you don't need this file
+ * for basic usage. Use it when you need explicit controller/agent registration.
  *
- * Backend classes registered in server/index.ts (one barrel, like Rails).
- * Routes inferred from class names. Zero manual wiring.
+ * Example with controllers + agents:
+ *
+ *   import 'reflect-metadata'
+ *   import { TheoApp } from '@theokit/http/app'
+ *   import { MyController } from './server/controllers/my.controller.js'
+ *
+ *   const app = await TheoApp.create({ controllers: [MyController] })
+ *   await app.listen(3000)
  */
-import 'reflect-metadata'
-import { readFileSync } from 'node:fs'
-import { TheoApp } from '@theokit/http/app'
-import { TasksController, AssistantAgent, TaskTools } from './server/index.js'
-
-let html: string | undefined
-try { html = readFileSync(new URL('./public/index.html', import.meta.url), 'utf-8') } catch { /* no frontend */ }
-
-const app = await TheoApp.create({
-  controllers: [TasksController],
-  agents: [AssistantAgent],
-  providers: [TaskTools],
-  html,
-})
-
-await app.listen(3000)

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

@@ -1,6 +1,6 @@
 ---
 name: theokit-agents
-description: TheoKit agent/LLM integration — @Agent, @Tool, @Toolbox decorators, streaming, memory
+description: TheoKit agent/LLM integration — two streaming surfaces (decorator vs manual), @Tool, @Toolbox, memory
 user-invocable: false
 paths:
   - "**/*agent*"
@@ -13,31 +13,51 @@ paths:
 
 # TheoKit Agents & Tools
 
-## @Agent Decorator
+## Two Streaming Surfaces — pick one per endpoint
+
+TheoKit ships two ways to create agent endpoints. Use ONE per endpoint, not both.
+
+| Surface | Server | Events | Client | When to use |
+|---------|--------|--------|--------|-------------|
+| **Manual** (recommended for most apps) | `defineAgentEndpoint({ handler: async function* })` | `AgentEvent` (Message, ToolCall, Result, Error) | `useAgentStream()` / `consumeAgentStream()` | Full control over the LLM loop — you write the generator |
+| **Decorator** (`@theokit/agents`) | `@Agent` class → auto-generated route | `AgentStreamEvent` (TextDelta, ToolCall, Done...) | (same client hooks work) | Declarative — framework manages LLM loop via `@MainLoop` |
+
+### Surface 1: Manual (defineAgentEndpoint)
 
 ```typescript
-import { Agent, MainLoop, Hook, Memory, Budget } from '@theokit/agents'
+// server/routes/agents/assistant.ts
+import { defineAgentEndpoint } from 'theokit/server/define'
+import type { AgentEvent } from 'theokit'
+
+export const POST = defineAgentEndpoint({
+  handler: async function* ({ body }): AsyncGenerator<AgentEvent> {
+    // You control the LLM loop
+    yield { type: 'message', content: 'Thinking...' }
+    const result = await callLLM(body.message)
+    yield { type: 'message', content: result }
+  },
+})
+```
+
+### Surface 2: Decorator (@Agent)
+
+```typescript
+// server/agents/assistant.agent.ts
+import { Agent, MainLoop, Tool, Toolbox } from '@theokit/agents'
 
 @Agent({
-  model: 'openai/gpt-4o-mini',     // Required: LLM model
-  systemPrompt: 'You are a helpful task assistant.',
+  model: 'openai/gpt-4o-mini',
+  systemPrompt: 'You are a helpful assistant.',
 })
-@Memory({ provider: 'built-in', scope: 'per-user' })  // Optional
-@Budget({ maxCostUsd: 1.00, window: 'daily' })         // Optional
 export class AssistantAgent {
   @MainLoop({ strategy: 'react', maxIterations: 5 })
   async run() {
-    // Framework handles the LLM loop
-  }
-
-  @Hook('before:llm-call')
-  async onBeforeLLM(ctx) {
-    // Intercept before each LLM call
+    // Framework handles the LLM loop via @theokit/sdk
   }
 }
 ```
 
-Convention: `AssistantAgent` class name maps to `GET/POST /api/agents/assistant`.
+Convention: `AssistantAgent` → `POST /api/agents/assistant`
 
 ## @Tool Decorator
 
@@ -50,56 +70,63 @@ export class TaskTools {
   @Tool({
     name: 'list_tasks',
     description: 'List all tasks, optionally filtered by status',
-    input: z.object({
-      done: z.boolean().optional(),
-    }),
+    input: z.object({ done: z.boolean().optional() }),
   })
   async listTasks({ done }: { done?: boolean }) {
-    const all = db.select().from(tasks).all()
-    return done !== undefined ? all.filter(t => t.done === done) : all
-  }
-
-  @Tool({
-    name: 'create_task',
-    description: 'Create a new task with a title',
-    input: z.object({
-      title: z.string().min(1),
-    }),
-  })
-  async createTask({ title }: { title: string }) {
-    return db.insert(tasks).values({ title }).returning().get()
+    return db.select().from(tasks).all()
   }
 }
 ```
 
-## Frontend — useAgentStream
+## Client — useAgentStream (React hook)
+
+Works with BOTH surfaces. Transport: `fetch` POST + `ReadableStream` (SSE).
 
 ```typescript
 import { useAgentStream } from 'theokit/client'
 
 function ChatUI() {
-  const { status, events, send } = useAgentStream('/api/agents/assistant')
+  const { status, events, send, reset } = useAgentStream('/api/agents/assistant')
 
   return (
     <div>
-      {events.map(e => <p key={e.id}>{e.content}</p>)}
+      {status === 'streaming' && <p>Thinking...</p>}
+      {events.map(e => (
+        <div key={e.id}>
+          {e.type === 'message' && <p>{e.content}</p>}
+          {e.type === 'tool_call' && <p>Using tool: {e.name}</p>}
+        </div>
+      ))}
       <button onClick={() => send({ message: 'Hello' })}>Send</button>
     </div>
   )
 }
 ```
 
+### Non-React: consumeAgentStream
+
+```typescript
+import { consumeAgentStream } from 'theokit/client'
+
+const stream = consumeAgentStream('/api/agents/assistant', { body: { message: 'Hi' } })
+for await (const event of stream) {
+  console.log(event.type, event.content)
+}
+```
+
 ## Rules
 
 - Tool `name` and `description` are ALWAYS explicit — never inferred from method names (G4)
 - Tool `input` uses Zod schema — same pattern as defineRoute
 - `@UseGuards()` works on agents (shared with HTTP pipeline)
-- `@UseInterceptors()` and `@UseFilters()` on agents are metadata-only (emit warnings, not enforced at runtime)
+- `@UseInterceptors()` and `@UseFilters()` on agents are metadata-only (emit warnings)
 - Agent runtime is `@theokit/sdk` — NEVER call LLM APIs directly via fetch
+- Pick ONE surface per endpoint — don't mix defineAgentEndpoint with @Agent for the same route
 
 ## Anti-patterns
 
-- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use @Agent + @Tool
+- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use @Agent or defineAgentEndpoint
 - NEVER reimplement tool calling loop — the SDK handles it
-- NEVER store conversations manually — use @Memory
+- NEVER store conversations manually — use @Memory (decorator) or SDK persistence
 - NEVER infer tool capability from method name — always provide explicit `name` + `description`
+- NEVER mix both surfaces for the same endpoint — pick manual OR decorator

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

@@ -43,18 +43,21 @@ 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)
+## Agent Streaming
+
+Three client APIs, all from `theokit/client`:
+
+### useAgentStream (React hook — most common)
 
 ```typescript
 import { useAgentStream } from 'theokit/client'
 
-function ChatComponent() {
+function ChatUI() {
   const { status, events, send, reset } = useAgentStream('/api/agents/assistant')
 
   return (
@@ -66,12 +69,34 @@ function ChatComponent() {
           {event.type === 'tool_call' && <p>Using tool: {event.name}</p>}
         </div>
       ))}
-      <input onSubmit={e => send({ message: e.target.value })} />
+      <button onClick={() => send({ message: 'Hello' })}>Send</button>
     </div>
   )
 }
 ```
 
+### consumeAgentStream (non-React, async iterable)
+
+```typescript
+import { consumeAgentStream } from 'theokit/client'
+
+const stream = consumeAgentStream('/api/agents/assistant', {
+  body: { message: 'Hello' },
+})
+for await (const event of stream) {
+  console.log(event.type, event.content)
+}
+```
+
+### parseSSEChunk (low-level SSE parser)
+
+```typescript
+import { parseSSEChunk } from 'theokit/client'
+
+// Parse a single SSE line into an AgentEvent (or null)
+const event = parseSSEChunk('data: {"type":"message","content":"Hello"}')
+```
+
 ## Path Aliases
 
 ```typescript
@@ -83,7 +108,7 @@ Configured in `tsconfig.json` — works in both server and app code.
 
 ## Anti-patterns
 
-- NEVER use `fetch('/api/...')` directly — use `theoFetch` for type safety
+- NEVER use raw `fetch('/api/...')` — 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/package.json.tmpl

@@ -8,10 +8,8 @@
     "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 .",

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

@@ -8,14 +8,3 @@ 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

@@ -1,13 +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]),
-})
+// Define your Drizzle tables here. Example:
+//
+// import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
+//
+// export const posts = sqliteTable('posts', {
+//   id: integer('id').primaryKey({ autoIncrement: true }),
+//   title: text('title').notNull(),
+//   published: integer('published', { mode: 'boolean' }).notNull().default(false),
+//   createdAt: text('created_at').notNull().$defaultFn(() => new Date().toISOString()),
+// })
+//
+// Or scaffold a full resource (schema + routes + test):
+//   npx theokit generate resource posts title:string published:boolean

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

@@ -1,38 +1,18 @@
 import { describe, it, expect } from 'vitest'
-import { z } from 'zod'
 
-// Schema mirrors server/routes/tasks/index.ts POST body validation.
-// Unit test — no server dependency.
-const taskBodySchema = z.object({
-  title: z.string().min(3),
-  done: z.boolean().default(false),
-})
-
-describe('Task body validation', () => {
-  it('accepts valid task', () => {
-    const result = taskBodySchema.safeParse({ title: 'Buy groceries' })
-    expect(result.success).toBe(true)
-    if (result.success) {
-      expect(result.data.title).toBe('Buy groceries')
-      expect(result.data.done).toBe(false)
+describe('Health route response shape', () => {
+  it('returns expected fields', () => {
+    // Mirrors the shape returned by server/routes/health.ts GET handler.
+    // Unit test — no server dependency.
+    const response = {
+      status: 'ok',
+      timestamp: Date.now(),
+      framework: 'TheoKit',
     }
-  })
-
-  it('defaults done to false', () => {
-    const result = taskBodySchema.safeParse({ title: 'New task' })
-    expect(result.success).toBe(true)
-    if (result.success) expect(result.data.done).toBe(false)
-  })
-
-  it('rejects title shorter than 3 characters', () => {
-    expect(taskBodySchema.safeParse({ title: 'ab' }).success).toBe(false)
-  })
-
-  it('rejects empty title', () => {
-    expect(taskBodySchema.safeParse({ title: '' }).success).toBe(false)
-  })
 
-  it('rejects missing title', () => {
-    expect(taskBodySchema.safeParse({ done: true }).success).toBe(false)
+    expect(response.status).toBe('ok')
+    expect(response.framework).toBe('TheoKit')
+    expect(typeof response.timestamp).toBe('number')
+    expect(response.timestamp).toBeGreaterThan(0)
   })
 })

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

@@ -1,43 +0,0 @@
-/**
- * AssistantAgent — AI-powered task management assistant.
- *
- * Uses the SAME guards and pipeline as HTTP controllers.
- * Tools from @Mixin(TaskTools) are available to the LLM.
- */
-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'
-import { TaskTools } from '../toolboxes/task.tools.js'
-
-@Agent({
-  // Convention: AssistantAgent → name: 'assistant', route: /api/agents/assistant
-  model: 'openai/gpt-4o-mini',
-  systemPrompt: `You are a helpful task management assistant.
-Use the tasks.* tools to list, search, create, and complete tasks.
-Be concise and actionable.`,
-})
-@UseGuards(RolesGuard)
-@UseInterceptors(TimingInterceptor)
-@Roles([Role.User])
-@Memory({ provider: 'built-in', scope: 'per-user' })
-@Budget({ maxCostUsd: 1.00, window: 'daily' })
-@Mixin(TaskTools)
-export class AssistantAgent {
-  @MainLoop({ strategy: 'react', maxIterations: 5 })
-  async run() {}
-
-  @Hook('before:llm-call')
-  async onBeforeLLM() {
-    console.log('  🧠 Agent thinking...')
-  }
-
-  @Hook('after:tool-call')
-  async onToolDone() {
-    console.log('  🔧 Tool executed')
-  }
-}

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

@@ -1,70 +0,0 @@
-/**
- * TasksController — CRUD API for tasks.
- *
- * Demonstrates: @Controller, @Get/@Post/@Delete, @Body with Zod,
- * @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,
-  NotFoundException,
-} from '@theokit/http'
-import { RolesGuard, Roles, Role, IsPublic } from '../guards/auth.guard.js'
-import { TimingInterceptor } from '../interceptors/timing.interceptor.js'
-import { HttpErrorFilter } from '../filters/http-error.filter.js'
-import { taskStore } from '../store.js'
-
-const zCreateTask = z.object({
-  title: z.string().min(3, 'Title must be at least 3 characters'),
-  priority: z.enum(['low', 'medium', 'high']).default('medium'),
-})
-
-@Controller()  // → /api/tasks (convention: inferred from TasksController)
-@UseGuards(RolesGuard)
-@UseInterceptors(TimingInterceptor)
-@UseFilters(HttpErrorFilter)
-@Roles([Role.User])
-export class TasksController {
-  @Get()
-  @IsPublic(true)
-  list() {
-    return taskStore.list()
-  }
-
-  @Get('search')
-  @IsPublic(true)
-  search(@Query('q') q: string) {
-    return taskStore.search(q ?? '')
-  }
-
-  @Get(':id')
-  @IsPublic(true)
-  findById(@Param('id') id: string) {
-    const task = taskStore.get(Number(id))
-    if (!task) throw new NotFoundException(`Task ${id} not found`)
-    return task
-  }
-
-  @Post()
-  create(@Body(zCreateTask) body: z.infer<typeof zCreateTask>) {
-    return taskStore.create(body)
-  }
-
-  @Put(':id')
-  update(@Param('id') id: string, @Body(z.object({ done: z.boolean() })) body: { done: boolean }) {
-    const task = taskStore.update(Number(id), body)
-    if (!task) throw new NotFoundException(`Task ${id} not found`)
-    return task
-  }
-
-  @Delete(':id')
-  @HttpCode(204)
-  @Roles([Role.Admin])
-  remove(@Param('id') id: string) {
-    if (!taskStore.remove(Number(id))) throw new NotFoundException(`Task ${id} not found`)
-  }
-}

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

@@ -1,29 +0,0 @@
-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/filters/http-error.filter.ts

@@ -1,20 +0,0 @@
-/**
- * HttpErrorFilter — custom error response format.
- * Catches HttpException and returns structured JSON.
- */
-import { Catch, HttpException, type ExceptionFilter, type ArgumentsHost } from '@theokit/http'
-
-@Catch(HttpException)
-export class HttpErrorFilter implements ExceptionFilter {
-  catch(exception: unknown, _host: ArgumentsHost): Response {
-    const ex = exception as HttpException
-    return new Response(JSON.stringify({
-      success: false,
-      error: { code: ex.statusCode, message: ex.message },
-      timestamp: new Date().toISOString(),
-    }), {
-      status: ex.statusCode,
-      headers: { 'content-type': 'application/json' },
-    })
-  }
-}

package/templates/default/server/guards/auth.guard.ts

@@ -1,47 +0,0 @@
-/**
- * RolesGuard — RBAC authorization for controllers AND agents.
- *
- * Same guard, same pipeline, same behavior on both HTTP and AI routes.
- * Uses @Roles([Role.Admin]) on class/method and @IsPublic(true) to skip.
- */
-import {
-  createDecorator, Reflector,
-  type CanActivate, type ExecutionContext,
-} from '@theokit/http'
-
-export enum Role {
-  User = 'user',
-  Admin = 'admin',
-}
-
-/** Declare required roles for a route or agent. */
-export const Roles = createDecorator<Role[]>()
-
-/** Mark a route as public — skips auth entirely. */
-export const IsPublic = createDecorator<boolean>()
-
-const reflector = new Reflector()
-
-export class RolesGuard implements CanActivate {
-  canActivate(context: ExecutionContext): boolean {
-    // Public routes skip auth
-    const isPublic = reflector.getAllAndOverride(
-      IsPublic,
-      context.getClass(),
-      context.getMethodName(),
-    )
-    if (isPublic) return true
-
-    // Check required roles
-    const roles = reflector.getAllAndOverride(
-      Roles,
-      context.getClass(),
-      context.getMethodName(),
-    )
-    if (!roles) return true // no roles required
-
-    // Read role from request header (replace with JWT/session in production)
-    const userRole = context.getRequest().headers.get('x-role') ?? ''
-    return roles.some((r) => r === userRole)
-  }
-}

package/templates/default/server/interceptors/timing.interceptor.ts

@@ -1,14 +0,0 @@
-/**
- * TimingInterceptor — logs request duration.
- * Applied to both controllers and agents.
- */
-import type { Interceptor } from '@theokit/http'
-
-export class TimingInterceptor implements Interceptor {
-  async intercept(_request: Request, next: () => Promise<unknown>): Promise<unknown> {
-    const start = Date.now()
-    const result = await next()
-    console.log(`  ${Date.now() - start}ms`)
-    return result
-  }
-}

package/templates/default/server/middleware/logger.middleware.ts

@@ -1,12 +0,0 @@
-/**
- * LoggerMiddleware — logs every incoming request.
- */
-import type { NestMiddleware } from '@theokit/http'
-
-export class LoggerMiddleware implements NestMiddleware {
-  use(request: Request, next: () => Promise<Response | null>): Promise<Response | null> {
-    const url = new URL(request.url)
-    console.log(`  ${new Date().toLocaleTimeString()} ${request.method} ${url.pathname}`)
-    return next()
-  }
-}

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

@@ -1,36 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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/store.ts

@@ -1,46 +0,0 @@
-/**
- * In-memory data store.
- * Replace with Drizzle + PostgreSQL for production.
- */
-
-export interface Task {
-  id: number
-  title: string
-  priority: 'low' | 'medium' | 'high'
-  done: boolean
-  createdAt: string
-}
-
-let seq = 0
-
-const tasks: Task[] = [
-  { id: ++seq, title: 'Set up TheoKit project', priority: 'high', done: true, createdAt: '2026-01-01' },
-  { id: ++seq, title: 'Create first controller', priority: 'high', done: true, createdAt: '2026-01-02' },
-  { id: ++seq, title: 'Add AI agent', priority: 'medium', done: false, createdAt: '2026-01-03' },
-  { id: ++seq, title: 'Deploy to production', priority: 'low', done: false, createdAt: '2026-01-04' },
-]
-
-export const taskStore = {
-  list: () => [...tasks],
-  get: (id: number) => tasks.find((t) => t.id === id),
-  search: (q: string) => tasks.filter((t) => t.title.toLowerCase().includes(q.toLowerCase())),
-  create: (data: { title: string; priority?: Task['priority'] }) => {
-    const task: Task = { id: ++seq, title: data.title, priority: data.priority ?? 'medium', done: false, createdAt: new Date().toISOString().split('T')[0] }
-    tasks.push(task)
-    return task
-  },
-  update: (id: number, data: Partial<Pick<Task, 'title' | 'priority' | 'done'>>) => {
-    const t = tasks.find((x) => x.id === id)
-    if (!t) return null
-    if (data.title !== undefined) t.title = data.title
-    if (data.priority !== undefined) t.priority = data.priority
-    if (data.done !== undefined) t.done = data.done
-    return t
-  },
-  remove: (id: number) => {
-    const idx = tasks.findIndex((t) => t.id === id)
-    if (idx === -1) return false
-    tasks.splice(idx, 1)
-    return true
-  },
-}

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

@@ -1,58 +0,0 @@
-/**
- * TaskTools — agent toolbox for task management.
- *
- * These tools are called by the LLM when the agent decides
- * 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'
-@Trace(true)
-export class TaskTools {
-  @Tool({
-    name: 'list',
-    description: 'List all tasks with their status and priority',
-    input: z.object({}),
-  })
-  async list() {
-    return JSON.stringify(taskStore.list())
-  }
-
-  @Tool({
-    name: 'search',
-    description: 'Search tasks by keyword in title',
-    input: z.object({ query: z.string() }),
-  })
-  async search(input: { query: string }) {
-    return JSON.stringify(taskStore.search(input.query))
-  }
-
-  @Tool({
-    name: 'create',
-    description: 'Create a new task',
-    input: z.object({
-      title: z.string(),
-      priority: z.enum(['low', 'medium', 'high']).default('medium'),
-    }),
-    risk: 'medium',
-  })
-  @Audit(true)
-  async create(input: { title: string; priority?: 'low' | 'medium' | 'high' }) {
-    return JSON.stringify(taskStore.create(input))
-  }
-
-  @Tool({
-    name: 'complete',
-    description: 'Mark a task as done by its ID',
-    input: z.object({ taskId: z.number() }),
-  })
-  @Audit(true)
-  async complete(input: { taskId: number }) {
-    const task = taskStore.update(input.taskId, { done: true })
-    return task ? JSON.stringify(task) : 'Task not found'
-  }
-}