create-theokit 0.4.0-beta.0 → 0.5.0

package/templates/default/app/page.tsx

@@ -1,285 +1,183 @@
-'use client'
-
-import { useEffect, useMemo, useState } from 'react'
-import {
-  ChatThread,
-  ChatMessage,
-  ChatComposer,
-  ToolCallCard,
-  AgentStreaming,
-  AgentErrorCard,
-  EmptyState,
-  QuickActionChips,
-  ContextWindowBar,
-  CommandPalette,
-  Avatar,
-  Tooltip,
-  Button,
-  ScrollArea,
-  type UIMessage,
-  type QuickAction,
-  type CommandItem,
-  type ToolCallStatus,
-} from '@theokit/ui'
-import { Sparkles, Wrench, RotateCcw, Command } from 'lucide-react'
-import { useAgentStream } from 'theokit/client'
-
 /**
- * Default scaffold — an Agent Surface, composed entirely from TheoUI.
+ * Main page — Task Manager + AI Chat.
  *
- *   ChatThread / ChatMessage  → conversation
- *   ToolCallCard              → expandable tool invocations
- *   AgentStreaming            → streaming indicator
- *   AgentErrorCard            → error display
- *   ChatComposer              → bottom input bar
- *   EmptyState                → first-load screen
- *   ContextWindowBar          → context usage at top
- *   CommandPalette            → ⌘K quick actions
- *   Avatar                    → assistant face in messages
- *   Tooltip                   → hints on icons
- *
- * `useAgentStream` handles SSE consumption, AbortController cleanup, and
- * StrictMode safety. Replace the mock at server/routes/chat.ts with your
- * real LLM provider (OpenAI / Anthropic / local).
+ * Split layout: left side CRUD, right side AI agent chat.
+ * SSE streaming renders token-by-token with tool call visualization.
  */
+export default function Page() {
+  return (
+    <div id="app">
+      <header>
+        <h1><span className="accent">TheoKit</span> Task Manager</h1>
+        <p className="subtitle">HTTP Controllers + AI Agent — same pipeline, same guards</p>
+        <div className="role-bar">
+          <label>Role: </label>
+          <select id="role">
+            <option value="">None (public only)</option>
+            <option value="user" selected>User</option>
+            <option value="admin">Admin</option>
+          </select>
+        </div>
+      </header>
+
+      <main className="grid">
+        {/* Left: CRUD Panel */}
+        <section className="card">
+          <h2>📋 Tasks <span className="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" className="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" className="error"></p>
+        </section>
+
+        {/* Right: AI Chat */}
+        <section className="card">
+          <h2>🤖 AI Assistant <span className="badge badge-ai">@Agent + SSE</span></h2>
+          <div id="chat" className="chat-box">
+            <div className="msg system">Ask me to list, create, or complete tasks...</div>
+          </div>
+          <div className="chat-bar">
+            <input id="chat-input" placeholder="Message the AI assistant..." />
+            <button id="chat-send" onClick={() => {}}>Send</button>
+          </div>
+          <p id="chat-cost" className="cost"></p>
+        </section>
+      </main>
+
+      <ClientScript />
+    </div>
+  )
+}
 
-type ConversationItem =
-  | { kind: 'message'; id: string; role: 'user' | 'assistant'; content: string; timestamp: string }
-  | {
-      kind: 'tool'
-      id: string
-      tool: string
-      target?: string
-      status: ToolCallStatus
-      output?: string
-      timestamp: string
-    }
-  | { kind: 'error'; id: string; message: string; timestamp: string }
-
-const QUICK_ACTIONS: QuickAction[] = [
-  { id: 'summarize', label: 'Summarize this page', icon: Sparkles },
-  { id: 'tools', label: 'Show available tools', icon: Wrench },
-  { id: 'reset', label: 'Start a new conversation', icon: RotateCcw },
-]
-
-const COMMAND_ITEMS: CommandItem[] = QUICK_ACTIONS.map((a) => ({
-  id: a.id,
-  label: a.label,
-  icon: a.icon,
-  group: 'Quick actions',
-}))
-
-// Mock context-window usage — replace with real model state.
-const CONTEXT_USED = 4_200
-const CONTEXT_TOTAL = 200_000
-const MODEL_NAME = 'mock-llm'
-
-// Modern chat UX: only the assistant carries an avatar. User messages are
-// right-aligned with a distinct bubble style — that's enough signal.
-// (TheoUI's ChatMessage uses flex-col, so a user avatar would land BELOW
-// the bubble, not above — visually unusual.)
-const ASSISTANT_AVATAR = (
-  <Avatar size="sm" tone="primary">
-    <Avatar.Fallback>TH</Avatar.Fallback>
-  </Avatar>
-)
+function ClientScript() {
+  return (
+    <script dangerouslySetInnerHTML={{ __html: CLIENT_JS }} />
+  )
+}
 
-export default function Page() {
-  const [composerValue, setComposerValue] = useState('')
-  const [userMessages, setUserMessages] = useState<ConversationItem[]>([])
-  const [paletteOpen, setPaletteOpen] = useState(false)
-  const { events, send, status, reset } = useAgentStream<{ message: string }>('/api/chat')
+const CLIENT_JS = `
+const API = '';
+let sessionId = 'session-' + Date.now();
+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;
+};
+
+// ─── Tasks CRUD ─────────────────────────────────────
+
+async function loadTasks() {
+  const res = await fetch(API + '/api/tasks');
+  const tasks = await res.json();
+  document.getElementById('task-list').innerHTML = tasks.map(t => {
+    const statusClass = t.done ? 'done' : 'pending';
+    const prioClass = t.priority === 'high' ? 'prio-high' : t.priority === 'low' ? 'prio-low' : 'prio-med';
+    return '<tr class="' + statusClass + '"><td>' + (t.done ? '✅ ' : '○ ') + t.title + '</td><td><span class="prio ' + prioClass + '">' + t.priority + '</span></td><td>' + (t.done ? 'Done' : 'To do') + '</td></tr>';
+  }).join('');
+}
 
-  // ⌘K / Ctrl+K opens the CommandPalette.
-  useEffect(() => {
-    function onKey(e: KeyboardEvent) {
-      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
-        e.preventDefault()
-        setPaletteOpen((v) => !v)
-      }
+document.getElementById('create-form').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  const title = document.getElementById('new-title').value.trim();
+  const priority = document.getElementById('new-priority').value;
+  const err = document.getElementById('form-error');
+  err.textContent = '';
+  if (!title) return;
+  const res = await fetch(API + '/api/tasks', { method: 'POST', headers: headers(), body: JSON.stringify({ title, priority }) });
+  if (res.status === 403) { err.textContent = '403 — Need User role'; return; }
+  if (res.status === 422) { const e = await res.json(); err.textContent = e.error?.issues?.[0]?.message || 'Validation error'; return; }
+  if (!res.ok) { err.textContent = 'Error ' + res.status; return; }
+  document.getElementById('new-title').value = '';
+  loadTasks();
+});
+
+// ─── AI Chat (SSE) ──────────────────────────────────
+
+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: ' + escapeHtml(msg) + '</div>';
+  document.getElementById('chat-send').disabled = true;
+
+  try {
+    const res = await fetch(API + '/api/agents/assistant/chat', {
+      method: 'POST', headers: headers(),
+      body: JSON.stringify({ message: msg, sessionId })
+    });
+
+    if (res.status === 403) {
+      chat.innerHTML += '<div class="msg system">403 — Need User role to chat</div>';
+      document.getElementById('chat-send').disabled = false;
+      return;
     }
-    window.addEventListener('keydown', onKey)
-    return () => window.removeEventListener('keydown', onKey)
-  }, [])
 
-  const items = useMemo<ConversationItem[]>(() => {
-    const ts = new Date().toISOString()
-    const agentItems: ConversationItem[] = events.map((event, i) => {
-      const id = `e-${i}`
-      switch (event.type) {
-        case 'message':
-          return { kind: 'message', id, role: 'assistant', content: event.content, timestamp: ts }
-        case 'tool_call':
-          return {
-            kind: 'tool',
-            id,
-            tool: event.name,
-            target:
-              typeof event.args === 'object' && event.args !== null
-                ? Object.entries(event.args as Record<string, unknown>)
-                    .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
-                    .join(' ')
-                : undefined,
-            status: 'running',
-            timestamp: ts,
-          }
-        case 'tool_result':
-          return {
-            kind: 'tool',
-            id,
-            tool: event.name,
-            status: 'success',
-            output:
-              typeof event.data === 'string' ? event.data : JSON.stringify(event.data, null, 2),
-            timestamp: ts,
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let agentDiv = document.createElement('div');
+    agentDiv.className = 'msg agent';
+    agentDiv.textContent = '';
+    chat.appendChild(agentDiv);
+
+    let buffer = '';
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\\n');
+      buffer = 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') {
+            agentDiv.innerHTML += formatMarkdown(ev.content);
+          } else if (ev.type === 'tool_call') {
+            chat.insertBefore(toolMsg('🔧 Calling: ' + ev.toolName), agentDiv);
+          } else if (ev.type === 'tool_result') {
+            chat.insertBefore(toolMsg('✅ ' + (ev.output || '').substring(0, 80)), agentDiv);
+          } else if (ev.type === 'thinking') {
+            chat.insertBefore(sysMsg('💭 ' + ev.content), agentDiv);
+          } else if (ev.type === 'done') {
+            const cost = ev.cost ? ' · $' + ev.cost.toFixed(6) : '';
+            document.getElementById('chat-cost').textContent = ev.usage.totalTokens + ' tokens · ' + ev.durationMs + 'ms' + cost;
+          } else if (ev.type === 'error') {
+            chat.innerHTML += '<div class="msg error">' + ev.message + '</div>';
           }
-        case 'error':
-          return { kind: 'error', id, message: event.message, timestamp: ts }
+        } catch {}
       }
-    })
-    return [...userMessages, ...agentItems]
-  }, [userMessages, events])
-
-  function handleSubmit(value: string) {
-    const trimmed = value.trim()
-    if (!trimmed) return
-    const id = `u-${userMessages.length}`
-    setUserMessages((prev) => [
-      ...prev,
-      { kind: 'message', id, role: 'user', content: trimmed, timestamp: new Date().toISOString() },
-    ])
-    send({ message: trimmed })
-    setComposerValue('')
-  }
-
-  function handleQuickAction(id: string) {
-    setPaletteOpen(false)
-    if (id === 'reset') {
-      setUserMessages([])
-      reset()
-      return
+      chat.scrollTop = chat.scrollHeight;
     }
-    const action = QUICK_ACTIONS.find((a) => a.id === id)
-    if (action) handleSubmit(typeof action.label === 'string' ? action.label : '')
+    loadTasks(); // refresh after agent actions
+  } catch (e) {
+    chat.innerHTML += '<div class="msg error">Error: ' + e.message + '</div>';
   }
+  document.getElementById('chat-send').disabled = false;
+  chat.scrollTop = chat.scrollHeight;
+}
 
-  const isStreaming = status === 'streaming'
-  const isEmpty = items.length === 0 && !isStreaming
-  const hasError = status === 'error'
-
-  return (
-    <>
-      <ContextWindowBar
-        used={CONTEXT_USED}
-        total={CONTEXT_TOTAL}
-        trailing={MODEL_NAME}
-        label="Context window"
-        compact
-        className="border-border/60 border-b px-6 py-2"
-      />
-
-      <ScrollArea className="flex-1">
-        <div className="mx-auto flex w-full max-w-3xl flex-col gap-4 px-6 py-6">
-          {isEmpty ? (
-            <EmptyState
-              eyebrow="Theo Agent"
-              icon={Sparkles}
-              title="What should we build today?"
-              description="Ask anything. This scaffold ships with a mock LLM at server/routes/chat.ts so you can see the wiring before plugging in a real model."
-              action={<QuickActionChips actions={QUICK_ACTIONS} onSelect={handleQuickAction} />}
-            />
-          ) : (
-            <ChatThread>
-              {items.map((item) => {
-                if (item.kind === 'message') {
-                  const message: UIMessage = {
-                    id: item.id,
-                    role: item.role,
-                    parts: [{ type: 'text', text: item.content, state: 'done' }],
-                  }
-                  return (
-                    <ChatMessage
-                      key={item.id}
-                      message={message}
-                      avatar={item.role === 'assistant' ? ASSISTANT_AVATAR : undefined}
-                    />
-                  )
-                }
-                if (item.kind === 'tool') {
-                  return (
-                    <ToolCallCard
-                      key={item.id}
-                      tool={item.tool}
-                      icon={Wrench}
-                      target={item.target}
-                      status={item.status}
-                      output={item.output}
-                      timestamp={item.timestamp}
-                    />
-                  )
-                }
-                return (
-                  <AgentErrorCard
-                    key={item.id}
-                    kind="tool-failure"
-                    title="Agent error"
-                    detail={item.message}
-                  />
-                )
-              })}
-              {isStreaming && <AgentStreaming model={MODEL_NAME} />}
-            </ChatThread>
-          )}
-        </div>
-      </ScrollArea>
-
-      <div className="border-border/60 border-t bg-background/50 backdrop-blur">
-        <div className="mx-auto w-full max-w-3xl px-6 py-4">
-          {hasError && (
-            <div className="mb-3">
-              <AgentErrorCard
-                kind="network"
-                title="Stream ended with an error"
-                detail="The connection to the agent endpoint was interrupted. Reset to try again."
-                actions={
-                  <Button variant="ghost" size="sm" onClick={() => reset()}>
-                    Reset
-                  </Button>
-                }
-              />
-            </div>
-          )}
-          <ChatComposer
-            value={composerValue}
-            onValueChange={setComposerValue}
-            onSubmit={handleSubmit}
-            running={isStreaming}
-            placeholder="Ask the agent…"
-            leadingActions={
-              <Tooltip label="Open command palette (⌘K)" side="top">
-                <Button
-                  type="button"
-                  variant="ghost"
-                  size="icon"
-                  onClick={() => setPaletteOpen(true)}
-                  aria-label="Open command palette"
-                >
-                  <Command className="size-4" />
-                </Button>
-              </Tooltip>
-            }
-          />
-        </div>
-      </div>
+function toolMsg(text) { const d = document.createElement('div'); d.className = 'msg tool'; d.textContent = text; return d; }
+function sysMsg(text) { const d = document.createElement('div'); d.className = 'msg system'; d.textContent = text; return d; }
+function escapeHtml(s) { return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;'); }
+function formatMarkdown(s) { return escapeHtml(s).replace(/\\*\\*(.+?)\\*\\*/g, '<strong>$1</strong>').replace(/\\n/g, '<br>'); }
 
-      <CommandPalette
-        open={paletteOpen}
-        onOpenChange={setPaletteOpen}
-        items={COMMAND_ITEMS}
-        onSelect={handleQuickAction}
-        placeholder="Run a command…"
-        emptyMessage="No matching commands."
-      />
-    </>
-  )
-}
+loadTasks();
+`

package/templates/default/app.ts

@@ -0,0 +1,23 @@
+/**
+ * TheoKit App — entry point.
+ *
+ * That's it. No manual wiring. No plumbing.
+ * TheoApp.create() handles everything:
+ *   - Controller routes (HTTP CRUD)
+ *   - Agent routes (SSE streaming + tool calling)
+ *   - DI (providers injected into controllers + agents)
+ *   - Shared pipeline (guards, interceptors, filters)
+ */
+import 'reflect-metadata'
+import { TheoApp } from '@theokit/http-decorators/app'
+import { TasksController } from './server/controllers/tasks.controller.js'
+import { AssistantAgent } from './server/agents/assistant.agent.js'
+import { TaskTools } from './server/toolboxes/task.tools.js'
+
+const app = await TheoApp.create({
+  controllers: [TasksController],
+  agents: [AssistantAgent],
+  providers: [TaskTools],
+})
+
+await app.listen(3000)

package/templates/default/package.json.tmpl

@@ -4,32 +4,19 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "theokit dev",
-    "build": "theokit build",
-    "start": "theokit start",
-    "typecheck": "tsc --noEmit"
+    "dev": "bun app.ts",
+    "dev:node": "npx tsx app.ts",
+    "test": "bun test"
   },
   "dependencies": {
-    "theokit": "^0.4.0-beta.0",
-    "@theokit/sdk": "^1.6.2",
-    "@theokit/ui": "^0.14.0",
-    "lucide-react": "^0.469.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "react-router": "^7.0.0",
-    "zod": "^3.24.0"
+    "theokit": "^0.4.0",
+    "@theokit/http-decorators": "^0.1.0",
+    "@theokit/agents": "^0.1.0",
+    "reflect-metadata": "^0.2.0",
+    "zod": "^3.22.0"
   },
   "devDependencies": {
-    "@types/node": "^22.10.0",
-    "typescript": "^5.7.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "tailwindcss": "^4.0.0",
-    "@tailwindcss/vite": "^4.0.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
+    "typescript": "^5.5.0",
+    "@swc/core": "^1.3.0"
   }
 }

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

@@ -0,0 +1,46 @@
+/**
+ * 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-decorators'
+import { RolesGuard, Roles, Role } from '../guards/auth.guard.js'
+import { TimingInterceptor } from '../interceptors/timing.interceptor.js'
+import { TaskTools } from '../toolboxes/task.tools.js'
+
+@Agent({
+  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.`,
+  stream: true,
+  maxIterations: 5,
+})
+@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

@@ -0,0 +1,70 @@
+/**
+ * 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-decorators'
+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')
+@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/filters/http-error.filter.ts

@@ -0,0 +1,20 @@
+/**
+ * HttpErrorFilter — custom error response format.
+ * Catches HttpException and returns structured JSON.
+ */
+import { Catch, HttpException, type ExceptionFilter, type ArgumentsHost } from '@theokit/http-decorators'
+
+@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' },
+    })
+  }
+}