create-theokit 1.0.7 → 1.0.8

package/templates/default/app/page.tsx

@@ -2,36 +2,42 @@
 
 import { useState, useEffect, useCallback, type FormEvent } from 'react'
 
-interface Task { id: number; title: string; priority: 'high' | 'medium' | 'low'; done: boolean }
-type Role = '' | 'user' | 'admin'
+interface Task {
+  id: number
+  title: string
+  priority: 'high' | 'medium' | 'low'
+  done: boolean
+}
 
 export default function Page() {
   const [tasks, setTasks] = useState<Task[]>([])
-  const [role, setRole] = useState<Role>('user')
   const [title, setTitle] = useState('')
   const [priority, setPriority] = useState<Task['priority']>('medium')
   const [formError, setFormError] = useState('')
 
-  const hdrs = useCallback((): Record<string, string> => {
-    const h: Record<string, string> = { 'Content-Type': 'application/json' }
-    if (role) h['x-role'] = role
-    return h
-  }, [role])
-
   const loadTasks = useCallback(async () => {
     const res = await fetch('/api/tasks')
     if (res.ok) setTasks(await res.json())
   }, [])
 
-  useEffect(() => { loadTasks() }, [loadTasks])
+  useEffect(() => {
+    loadTasks()
+  }, [loadTasks])
 
   const createTask = async (e: FormEvent) => {
     e.preventDefault()
     setFormError('')
     if (!title.trim()) return
-    const res = await fetch('/api/tasks', { method: 'POST', headers: hdrs(), body: JSON.stringify({ title, priority }) })
-    if (res.status === 403) { setFormError('403 — Need User role'); return }
-    if (!res.ok) { const b = await res.json(); setFormError(b.error?.issues?.[0]?.message ?? `Error ${res.status}`); 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()
   }
@@ -45,10 +51,20 @@ export default function Page() {
           <h1>TheoKit</h1>
           <p className="tagline">Build the app your agent lives in.</p>
           <nav className="ctas">
-            <a href="https://usetheo.dev" target="_blank" rel="noopener noreferrer" className="btn primary">
+            <a
+              href="https://usetheo.dev"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="btn primary"
+            >
               Get Started
             </a>
-            <a href="https://github.com/usetheodev/theokit" target="_blank" rel="noopener noreferrer" className="btn secondary">
+            <a
+              href="https://github.com/usetheodev/theokit"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="btn secondary"
+            >
               Documentation
             </a>
           </nav>
@@ -57,34 +73,46 @@ export default function Page() {
           </p>
         </header>
 
-        {/* Role */}
-        <div className="role-bar">
-          <label htmlFor="role">Role:</label>
-          <select id="role" value={role} onChange={e => setRole(e.target.value as Role)}>
-            <option value="">None (public)</option>
-            <option value="user">User</option>
-            <option value="admin">Admin</option>
-          </select>
-        </div>
-
         {/* Tasks */}
         <section className="card">
-          <h2>Tasks <span className="badge">@Controller</span></h2>
+          <h2>
+            Tasks <span className="badge">defineRoute + Drizzle</span>
+          </h2>
           <table>
-            <thead><tr><th>Task</th><th>Priority</th><th>Status</th></tr></thead>
+            <thead>
+              <tr>
+                <th>Task</th>
+                <th>Priority</th>
+                <th>Status</th>
+              </tr>
+            </thead>
             <tbody>
-              {tasks.map(t => (
+              {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 ? '✅ ' : '○ '}
+                    {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'])}>
+            <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>
@@ -97,12 +125,16 @@ export default function Page() {
         {/* Features */}
         <div className="grid features">
           <div className="feature">
-            <h3>@Controller</h3>
-            <p>NestJS-style decorators with convention naming. <code>TasksController</code> → <code>/api/tasks</code></p>
+            <h3>defineRoute</h3>
+            <p>
+              Typed API routes with Zod validation. See <code>server/routes/tasks/</code>
+            </p>
           </div>
           <div className="feature">
-            <h3>defineRoute</h3>
-            <p>Typed API routes with Zod validation. See <code>server/routes/health.ts</code></p>
+            <h3>Drizzle + SQLite</h3>
+            <p>
+              Type-safe database with zero config. Schema in <code>server/db/schema.ts</code>
+            </p>
           </div>
           <div className="feature">
             <h3>@Agent + @Tool</h3>
@@ -116,11 +148,18 @@ export default function Page() {
 
         {/* Footer */}
         <footer className="footer">
-          Powered by <a href="https://usetheo.dev" target="_blank" rel="noopener noreferrer">TheoKit</a>
+          Powered by{' '}
+          <a href="https://usetheo.dev" target="_blank" rel="noopener noreferrer">
+            TheoKit
+          </a>
           {' · '}
-          <a href="https://github.com/usetheodev/theokit" target="_blank" rel="noopener noreferrer">GitHub</a>
+          <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>
+          <a href="https://discord.usetheo.dev" target="_blank" rel="noopener noreferrer">
+            Discord
+          </a>
         </footer>
       </div>
     </div>

package/templates/default/app.ts

@@ -0,0 +1,24 @@
+/**
+ * TheoKit App — convention over configuration.
+ *
+ * "The framework that reduces noise for humans + AI."
+ *
+ * Backend classes registered in server/index.ts (one barrel, like Rails).
+ * Routes inferred from class names. Zero manual wiring.
+ */
+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/rules/theokit-conventions.md

@@ -0,0 +1,36 @@
+# TheoKit Conventions
+
+## Imports
+
+- Use `theokit/server/define` for defineRoute, defineAction, defineWebSocket
+- Use `theokit/client` for theoFetch, createAppClient
+- Use `theokit/server/auth` for session/auth APIs
+- NEVER import from `theokit/dist/...` or `theokit/src/...`
+- NEVER import internal modules: `theokit/core`, `theokit/vite-plugin`, `theokit/adapters/*`
+
+## Validation
+
+- Zod is the single source of truth for types and validation
+- Define schema ONCE with `z.object(...)`, derive types with `z.infer<>`
+- NEVER duplicate a Zod schema as a manual TypeScript interface
+- NEVER parse request body manually — use `body:` in defineRoute
+
+## Routes
+
+- File at `server/routes/tasks/[id].ts` maps to `/api/tasks/:id`
+- Export HTTP method handlers: `export const GET = defineRoute({...})`
+- Use `params: z.object({...})` for URL params, `body:` for request body
+- Use `status: 201` for creation responses, not manual `res.status()`
+
+## Types
+
+- No `any` in production code
+- No `@ts-ignore` or `@ts-expect-error`
+- No `as` type assertions — use Zod schemas or type guards
+
+## Database
+
+- Schema lives in `server/db/schema.ts` (Drizzle ORM)
+- Connection in `server/db/index.ts`
+- Seeds in `server/db/seed.ts`
+- Use `npx drizzle-kit push` for dev, `npx drizzle-kit generate` for prod migrations

package/templates/default/dot-claude/settings.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Bash(npx theokit *)",
+      "Bash(npx vitest *)",
+      "Bash(npx tsc *)",
+      "Bash(npx eslint *)",
+      "Bash(npx drizzle-kit *)",
+      "Bash(git status)",
+      "Bash(git diff *)",
+      "Bash(git log *)"
+    ],
+    "deny": [
+      "Read(.env*)",
+      "Read(**/.env*)",
+      "Bash(sudo *)",
+      "Bash(rm -rf *)",
+      "Bash(git push --force *)",
+      "Bash(git reset --hard *)"
+    ]
+  }
+}

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

@@ -0,0 +1,105 @@
+---
+name: theokit-agents
+description: TheoKit agent/LLM integration — @Agent, @Tool, @Toolbox decorators, streaming, memory
+user-invocable: false
+paths:
+  - "**/*agent*"
+  - "**/*Agent*"
+  - "**/*tool*"
+  - "**/*Tool*"
+  - "**/*toolbox*"
+  - "**/*Toolbox*"
+---
+
+# TheoKit Agents & Tools
+
+## @Agent Decorator
+
+```typescript
+import { Agent, MainLoop, Hook, Memory, Budget } from '@theokit/agents'
+
+@Agent({
+  model: 'openai/gpt-4o-mini',     // Required: LLM model
+  systemPrompt: 'You are a helpful task 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
+  }
+}
+```
+
+Convention: `AssistantAgent` class name maps to `GET/POST /api/agents/assistant`.
+
+## @Tool Decorator
+
+```typescript
+import { Toolbox, Tool } from '@theokit/agents'
+import { z } from 'zod'
+
+@Toolbox()
+export class TaskTools {
+  @Tool({
+    name: 'list_tasks',
+    description: 'List all tasks, optionally filtered by status',
+    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()
+  }
+}
+```
+
+## Frontend — useAgentStream
+
+```typescript
+import { useAgentStream } from 'theokit/client'
+
+function ChatUI() {
+  const { status, events, send } = useAgentStream('/api/agents/assistant')
+
+  return (
+    <div>
+      {events.map(e => <p key={e.id}>{e.content}</p>)}
+      <button onClick={() => send({ message: 'Hello' })}>Send</button>
+    </div>
+  )
+}
+```
+
+## 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)
+- Agent runtime is `@theokit/sdk` — NEVER call LLM APIs directly via fetch
+
+## Anti-patterns
+
+- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use @Agent + @Tool
+- NEVER reimplement tool calling loop — the SDK handles it
+- NEVER store conversations manually — use @Memory
+- NEVER infer tool capability from method name — always provide explicit `name` + `description`

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

@@ -0,0 +1,128 @@
+---
+name: theokit-config
+description: TheoKit configuration — defineConfig, plugins, security, storage, agents, build targets
+user-invocable: false
+paths:
+  - "theo.config*"
+  - "**/*config*"
+---
+
+# TheoKit Configuration
+
+## theo.config.ts
+
+```typescript
+import { defineConfig } from 'theokit'
+
+export default defineConfig({
+  // Basic
+  name: 'my-app',            // DNS-1123 format (lowercase + hyphens)
+  port: 3000,                // Dev + production port
+
+  // SSR (default: false)
+  ssr: false,
+
+  // Security (defaults are secure)
+  security: {
+    csrf: true,               // CSRF protection (default: true)
+    csp: 'report-only',       // Content Security Policy
+  },
+
+  // Agent runtime
+  agents: {
+    maxRegistries: 100,
+    registry: {
+      maxAgents: 100,
+      idleTimeoutMs: 30 * 60_000,
+    },
+  },
+
+  // DevTools overlay (dev only)
+  devtools: true,
+
+  // Plugins
+  plugins: [],
+})
+```
+
+## Common Configuration Patterns
+
+### Adding CORS
+
+```typescript
+import { defineConfig } from 'theokit'
+
+export default defineConfig({
+  // CORS is handled by the framework — configure in route-level or globally
+  security: {
+    cors: {
+      origin: ['http://localhost:3000', 'https://myapp.com'],
+      credentials: true,
+    },
+  },
+})
+```
+
+### Storage (Postgres + Redis)
+
+```typescript
+export default defineConfig({
+  storage: {
+    postgres: [{ url: process.env.DATABASE_URL }],
+    redis: [{ url: process.env.REDIS_URL }],
+  },
+})
+```
+
+### Rate Limiting
+
+```typescript
+export default defineConfig({
+  rateLimit: {
+    global: { max: 100, windowMs: 60_000 },
+  },
+})
+```
+
+### OpenAPI Generation
+
+```typescript
+export default defineConfig({
+  openapi: {
+    title: 'My App API',
+    version: '1.0.0',
+    outDir: 'docs/api',
+  },
+})
+```
+
+## CLI Commands
+
+```bash
+npx theokit dev                    # Start dev server with HMR
+npx theokit build                  # Build for Node.js
+npx theokit build --target=node    # Explicit target
+npx theokit start                  # Run production build
+npx theokit routes                 # List all discovered endpoints
+npx theokit generate route tasks   # Scaffold a new route
+npx theokit generate resource posts title:string  # Scaffold CRUD resource
+npx theokit db migrate             # Run database migrations
+npx theokit db seed                # Seed database
+```
+
+## Environment Variables
+
+- `PORT` — Server port (overrides config)
+- `HOST` — Server host
+- `NODE_ENV` — `development` | `production`
+- `DATABASE_URL` — Postgres connection string (when using postgres storage)
+- `REDIS_URL` — Redis connection string (when using redis storage)
+
+Env vars are loaded from `.env` (dev) and `.env.production` (build). NEVER commit `.env` files.
+
+## Anti-patterns
+
+- NEVER hardcode secrets in theo.config.ts — use environment variables
+- NEVER set `security.csrf: false` in production
+- NEVER use `ssr: true` without understanding hydration (start with `false`)
+- NEVER add plugins that don't match `defineTheoPlugin` interface

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