create-theokit 1.0.6 → 1.0.8

package/templates/default/app/globals.css

@@ -220,6 +220,7 @@ code, pre { font-family: var(--font-mono); }
   border: 1px solid var(--border);
   border-radius: 12px;
   padding: 24px;
+  width: 100%;
 }
 
 .card h2 {
@@ -314,6 +315,41 @@ tr.done td { opacity: 0.4; text-decoration: line-through; }
 }
 .chat-bar input:focus { border-color: var(--accent); }
 
+/* ─── Features grid ─────────────────────────────────── */
+
+.features {
+  margin-top: 32px;
+}
+
+.feature {
+  padding: 20px;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  background: var(--card);
+}
+
+.feature h3 {
+  font-size: 14px;
+  font-weight: 600;
+  margin-bottom: 6px;
+  font-family: var(--font-mono);
+  color: var(--accent);
+}
+
+.feature p {
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--text-secondary);
+}
+
+.feature code {
+  background: var(--bg);
+  border: 1px solid var(--border);
+  padding: 1px 5px;
+  border-radius: 4px;
+  font-size: 12px;
+}
+
 /* ─── Footer ────────────────────────────────────────── */
 
 .footer {

package/templates/default/app/page.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { useState, useEffect, useCallback, useRef, type FormEvent } from 'react'
+import { useState, useEffect, useCallback, type FormEvent } from 'react'
 
 interface Task {
   id: number
@@ -8,30 +8,12 @@ interface Task {
   priority: 'high' | 'medium' | 'low'
   done: boolean
 }
-type Role = '' | 'user' | 'admin'
-interface ChatMsg {
-  role: 'user' | 'agent' | 'tool' | 'system' | 'error'
-  text: string
-}
 
 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 [chat, setChat] = useState<ChatMsg[]>([
-    { role: 'system', text: 'Ask me to list, create, or complete tasks...' },
-  ])
-  const [chatInput, setChatInput] = useState('')
-  const [chatBusy, setChatBusy] = useState(false)
-  const chatRef = useRef<HTMLDivElement>(null)
-
-  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')
@@ -48,13 +30,9 @@ export default function Page() {
     if (!title.trim()) return
     const res = await fetch('/api/tasks', {
       method: 'POST',
-      headers: hdrs(),
+      headers: { 'Content-Type': 'application/json' },
       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}`)
@@ -64,65 +42,6 @@ export default function Page() {
     loadTasks()
   }
 
-  const sendChat = async () => {
-    const msg = chatInput.trim()
-    if (!msg || chatBusy) return
-    setChatInput('')
-    setChat((c) => [...c, { role: 'user', text: msg }])
-    setChatBusy(true)
-    try {
-      const res = await fetch('/api/agents/assistant/chat', {
-        method: 'POST',
-        headers: hdrs(),
-        body: JSON.stringify({ message: msg, sessionId: 'session-' + Date.now() }),
-      })
-      if (res.status === 403) {
-        setChat((c) => [...c, { role: 'error', text: '403 — Need User role' }])
-        return
-      }
-      const reader = res.body?.getReader()
-      if (!reader) return
-      const decoder = new TextDecoder()
-      let buf = '',
-        agentText = ''
-      while (true) {
-        const { done, value } = await reader.read()
-        if (done) break
-        buf += decoder.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') agentText += ev.content
-            else if (ev.type === 'tool_call')
-              setChat((c) => [...c, { role: 'tool', text: `🔧 ${ev.toolName}` }])
-            else if (ev.type === 'tool_result')
-              setChat((c) => [...c, { role: 'tool', text: `✅ ${(ev.output ?? '').slice(0, 80)}` }])
-            else if (ev.type === 'error')
-              setChat((c) => [...c, { role: 'error', text: ev.message }])
-          } catch {
-            /* partial */
-          }
-        }
-      }
-      if (agentText) setChat((c) => [...c, { role: 'agent', text: agentText }])
-      loadTasks()
-    } catch (err) {
-      setChat((c) => [
-        ...c,
-        { role: 'error', text: `Error: ${err instanceof Error ? err.message : String(err)}` },
-      ])
-    } finally {
-      setChatBusy(false)
-    }
-  }
-
-  useEffect(() => {
-    chatRef.current?.scrollTo(0, chatRef.current.scrollHeight)
-  }, [chat])
-
   return (
     <div className="page">
       <div className="main">
@@ -150,94 +69,81 @@ export default function Page() {
             </a>
           </nav>
           <p className="hint">
-            Edit <code>app/page.tsx</code> to get started.
+            Edit <code>app/page.tsx</code> to get started. Changes hot-reload instantly.
           </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>
-
-        {/* Content */}
-        <div className="grid">
-          <section className="card">
-            <h2>
-              Tasks <span className="badge">@Controller</span>
-            </h2>
-            <table>
-              <thead>
-                <tr>
-                  <th>Task</th>
-                  <th>Priority</th>
-                  <th>Status</th>
+        {/* 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>
-              </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>
-
-          <section className="card">
-            <h2>
-              AI Assistant <span className="badge badge-ai">@Agent + SSE</span>
-            </h2>
-            <div ref={chatRef} className="chat-box">
-              {chat.map((m, i) => (
-                <div key={i} className={`msg ${m.role}`}>
-                  {m.role === 'user' ? `You: ${m.text}` : m.text}
-                </div>
               ))}
-            </div>
-            <div className="chat-bar">
-              <input
-                value={chatInput}
-                onChange={(e) => setChatInput(e.target.value)}
-                onKeyDown={(e) => e.key === 'Enter' && sendChat()}
-                placeholder="Message the AI assistant..."
-                disabled={chatBusy}
-              />
-              <button type="button" onClick={sendChat} disabled={chatBusy}>
-                Send
-              </button>
-            </div>
-          </section>
+            </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>
+            </p>
+          </div>
+          <div className="feature">
+            <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>
+            <p>AI agents with SSE streaming, budget control, and human-in-the-loop approval.</p>
+          </div>
+          <div className="feature">
+            <h3>React + Vite</h3>
+            <p>File-based routing, HMR, SSR streaming. Edit and see changes instantly.</p>
+          </div>
         </div>
 
         {/* Footer */}

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