create-theokit 0.4.0-beta.0 → 0.5.0

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "create-theokit",
-  "version": "0.4.0-beta.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsup"
+  },
   "bin": {
     "create-theokit": "./dist/cli.js"
   },
@@ -14,7 +17,8 @@
   "dependencies": {
     "cross-spawn": "^7.0.6"
   },
-  "scripts": {
-    "build": "tsup"
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
   }
-}
+}

package/templates/default/.env.example

@@ -0,0 +1,5 @@
+# LLM API key (OpenRouter, Anthropic, or OpenAI)
+OPENROUTER_API_KEY=sk-or-v1-your-key-here
+
+# Optional: override the model declared in @Agent({ model })
+# LLM_MODEL=openai/gpt-4o-mini

package/templates/default/README.md.tmpl

@@ -1,75 +1,89 @@
 # {{name}}
 
-TheoKit project. Build the app your agent lives in — routing, auth, real-time, deploy — wired.
+Built with [TheoKit](https://theokit.dev) — Full-Stack TypeScript for AI Agents.
 
-> 📚 **Full docs:** https://docs.theokit.dev
-
-## Quick start
+## Getting Started
 
 ```bash
-# 1. Set your provider key (OpenRouter recommended — one key, any model)
-cp .env.example .env  # if .env.example shipped; otherwise:
-echo 'OPENROUTER_API_KEY=sk-or-v1-...' > .env
-
-# 2. Boot the dev server
-npx theokit dev
-```
-
-Open the printed URL. The default surface is a chat composer wired to `server/routes/chat.ts`. Drop in your real key in `.env` and the agent responds.
-
-## Templates
-
-- **default** (this one) — TheoUI chat composer + agent route.
-- **`--bare`** — Hello Theo with no `@theokit/*` deps. Use this when you want a clean structure to grow into or when the SDK isn't on your registry yet.
-- **dashboard** — nested layouts + sidebar.
-- **api-only** — server routes without React.
-- **postgres** — Drizzle ORM + migrations.
-- **saas** — full app with auth, billing, sessions.
+# Install dependencies
+npm install
 
-## What the framework auto-loads
+# Set your LLM API key
+cp .env.example .env
+# Edit .env with your OpenRouter/Anthropic/OpenAI key
 
-- **`.env` → `process.env`**. Edit `.env`; restart the dev server. Server routes read `process.env.MY_KEY` directly.
-- **`.theo/` build output cleanup** on every `theokit build`.
-- **`.theokit/agents/` LRU GC** on every `theokit dev` startup (default cap: 100 agents).
-- **Tailwind + `@theokit/ui` styling** auto-configured when `@theokit/ui` is in your `package.json` AND no consumer `tailwind.config.*` is present. This project ships an explicit `tailwind.config.ts` because the TheoUI v3 surface still requires it. The zero-config path lands when `@theokit/ui` ships its Vite plugin (cross-repo work, pending sign-off).
-
-For the full story of what's automatic vs deliberate, see [docs.usetheo.dev/zero-config](https://docs.usetheo.dev/zero-config) (or your local `node_modules/theokit/docs/concepts/zero-config.md`).
+# Start development server
+bun dev
+# or: npm run dev:node
+```
 
-## Project structure
+## Project Structure
 
 ```
-app/                  Frontend (file-based routing)
-├── page.tsx          /              — chat composer
-├── layout.tsx        wrapper        — TheoUI provider + theme
-server/               Backend (explicit routes & actions)
-├── routes/
-│   ├── chat.ts       POST /api/chat — agent SSE stream
-│   └── health.ts     GET  /api/health
-theo.config.ts        Framework config
-tailwind.config.ts    Tailwind theme tokens (TheoUI)
-postcss.config.js     PostCSS pipeline (Tailwind + autoprefixer)
-.env                  Secrets — never committed (.gitignore)
+{{name}}/
+├── app.ts                          # Entry point (TheoApp.create)
+├── server/
+│   ├── controllers/
+│   │   └── tasks.controller.ts     # HTTP CRUD (@Controller)
+│   ├── agents/
+│   │   └── assistant.agent.ts      # AI Agent (@Agent + @MainLoop)
+│   ├── toolboxes/
+│   │   └── task.tools.ts           # Agent tools (@Toolbox + @Tool)
+│   ├── guards/
+│   │   └── auth.guard.ts           # RBAC (@Roles + RolesGuard)
+│   ├── interceptors/
+│   │   └── timing.interceptor.ts   # Request timing
+│   ├── filters/
+│   │   └── http-error.filter.ts    # Error formatting
+│   ├── middleware/
+│   │   └── logger.middleware.ts     # Request logging
+│   └── store.ts                    # In-memory data store
+└── .env.example                    # Environment variables
 ```
 
-## Common commands
+## API Endpoints
+
+### HTTP Controllers
 
-| Command | What it does |
-|---|---|
-| `npx theokit dev` | Dev server with HMR, devtools overlay, structured logs |
-| `npx theokit build` | Production build → `.theo/` |
-| `npx theokit start` | Serve the production build |
-| `npx theokit check` | Lint for upgrade-readiness (CSRF, CSP, zero-config migration hints) |
-| `npx theokit generate route foo` | Scaffold a new server route |
-| `npx theokit routes` | List all routes + actions detected |
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | /api/tasks | Public | List all tasks |
+| GET | /api/tasks/search?q= | Public | Search tasks |
+| GET | /api/tasks/:id | Public | Get task by ID |
+| POST | /api/tasks | User | Create task |
+| PUT | /api/tasks/:id | User | Update task |
+| DELETE | /api/tasks/:id | Admin | Delete task |
 
-## What if `npm install` fails on `@theokit/sdk`?
+### AI Agent
 
-The agent SDK is in soft-release while the npm publish is operator-deferred. If you hit `404 Not Found` for `@theokit/sdk`:
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | /api/agents/assistant/chat | User | Chat with AI (SSE stream) |
 
-- **Quick path**: re-scaffold with `--bare` — Hello Theo without any `@theokit/*` deps.
-- **Inside the TheoKit monorepo**: replace `"@theokit/sdk": "^1.0.0"` with `"workspace:*"` in `package.json`.
-- **Wait**: track the publish at https://github.com/usetheo/theokit-sdk.
+## Examples
+
+```bash
+# List tasks
+curl http://localhost:3000/api/tasks
+
+# Create a task (requires user role)
+curl -X POST http://localhost:3000/api/tasks \
+  -H "Content-Type: application/json" \
+  -H "x-role: user" \
+  -d '{"title":"New task","priority":"high"}'
+
+# Chat with AI agent (SSE streaming)
+curl -N -X POST http://localhost:3000/api/agents/assistant/chat \
+  -H "Content-Type: application/json" \
+  -H "x-role: user" \
+  -d '{"message":"List all tasks and mark the first one as done"}'
+```
 
-## License
+## Key Concepts
 
-Apply your own. The TheoKit framework is Apache-2.0.
+- **@Controller** — HTTP routes with Zod validation
+- **@Agent** — AI agent with LLM + tool calling + SSE streaming
+- **@Toolbox** + **@Tool** — Functions the AI can call
+- **@UseGuards** — Same auth for controllers AND agents
+- **@Mixin** — Compose toolboxes into agents
+- **TheoApp.create()** — Zero-wiring bootstrap (like NestFactory.create)

package/templates/default/_gitignore

@@ -1,5 +1,4 @@
-node_modules
-.theo
-dist
+node_modules/
+dist/
 .env
 .env.local

package/templates/default/app/layout.tsx

@@ -1,85 +1,54 @@
-import '@theokit/ui/styles.css'
-
-import { Outlet } from 'react-router'
-import {
-  Sidebar,
-  TopNav,
-  AgentProfile,
-  ThemeSwitcher,
-  ThemeScript,
-  Tooltip,
-  Badge,
-  CostMeter,
-  type AgentProfileDescriptor,
-} from '@theokit/ui'
-import { Bot, MessageSquare, History, Settings } from 'lucide-react'
-
-const AGENTS: AgentProfileDescriptor[] = [
-  {
-    id: 'theo',
-    name: 'Theo',
-    description: 'Mock LLM — replace at server/routes/chat.ts.',
-    tone: 'primary',
-    initials: 'TH',
-    badge: 'Online',
-  },
-]
-
-export default function RootLayout() {
+export default function Layout({ children }: { children: React.ReactNode }) {
   return (
-    <>
-      <ThemeScript />
-      <div className="grid h-screen w-screen grid-rows-[auto_1fr] bg-background text-foreground">
-        <TopNav className="border-border/60 border-b px-4 py-2">
-          <TopNav.Left>
-            <Tooltip label="TheoKit agent surface" side="bottom">
-              <span className="inline-flex items-center gap-2">
-                <Bot className="size-5 text-primary" aria-hidden />
-                <span className="font-semibold text-sm tracking-tight">Theo Agent</span>
-                <Badge variant="outline" size="sm">
-                  v0.1
-                </Badge>
-              </span>
-            </Tooltip>
-          </TopNav.Left>
-          <TopNav.Right>
-            <Tooltip label="Toggle theme" side="bottom" align="end">
-              <span>
-                <ThemeSwitcher />
-              </span>
-            </Tooltip>
-          </TopNav.Right>
-        </TopNav>
-
-        <div className="grid h-full grid-cols-[260px_1fr] overflow-hidden">
-          <Sidebar className="flex flex-col border-border/60 border-r p-3">
-            <Sidebar.Header>
-              <AgentProfile agents={AGENTS} activeId="theo" />
-            </Sidebar.Header>
-
-            <Sidebar.Section title="Workspace">
-              <Sidebar.Item icon={MessageSquare} active>
-                New conversation
-              </Sidebar.Item>
-              <Sidebar.Item icon={History}>History</Sidebar.Item>
-              <Sidebar.Item icon={Settings}>Settings</Sidebar.Item>
-            </Sidebar.Section>
-
-            <Sidebar.Footer className="mt-auto">
-              <CostMeter
-                compact
-                title="This session"
-                cost={0.0023}
-                delta={{ value: 0.0023, period: 'now' }}
-              />
-            </Sidebar.Footer>
-          </Sidebar>
-
-          <main className="flex h-full flex-col overflow-hidden">
-            <Outlet />
-          </main>
-        </div>
-      </div>
-    </>
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>TheoKit App</title>
+        <style dangerouslySetInnerHTML={{ __html: STYLES }} />
+      </head>
+      <body>{children}</body>
+    </html>
   )
 }
+
+const STYLES = `
+  :root { --bg: #0a0a0a; --card: #141414; --border: #2a2a2a; --text: #e0e0e0; --muted: #888; --accent: #6366f1; --green: #22c55e; --red: #ef4444; --yellow: #eab308; }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: var(--bg); color: var(--text); min-height: 100vh; }
+  #app { max-width: 1200px; margin: 0 auto; padding: 20px; }
+  header { margin-bottom: 24px; }
+  h1 { font-size: 1.6rem; } .accent { color: var(--accent); }
+  .subtitle { color: var(--muted); font-size: 0.85rem; margin-top: 2px; }
+  .role-bar { margin-top: 12px; }
+  .role-bar select { padding: 6px 12px; background: #1a1a1a; border: 1px solid var(--border); border-radius: 6px; color: var(--text); font-size: 0.8rem; }
+  .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; } @media(max-width:768px){.grid{grid-template-columns:1fr;}}
+  .card { background: var(--card); border: 1px solid var(--border); border-radius: 12px; padding: 20px; }
+  h2 { font-size: 1rem; margin-bottom: 14px; display: flex; align-items: center; gap: 8px; }
+  .badge { font-size: 0.65rem; padding: 2px 8px; border-radius: 99px; background: #6366f122; color: var(--accent); }
+  .badge-ai { background: #eab30822; color: var(--yellow); }
+  table { width: 100%; border-collapse: collapse; font-size: 0.85rem; }
+  th { text-align: left; padding: 8px 4px; color: var(--muted); border-bottom: 1px solid var(--border); font-weight: 500; }
+  td { padding: 8px 4px; border-bottom: 1px solid var(--border); }
+  tr.done td { opacity: 0.5; text-decoration: line-through; }
+  .prio { font-size: 0.7rem; padding: 2px 8px; border-radius: 99px; }
+  .prio-high { background: #ef444422; color: var(--red); } .prio-med { background: #eab30822; color: var(--yellow); } .prio-low { background: #22c55e22; color: var(--green); }
+  .create-bar { display: flex; gap: 8px; margin-top: 14px; }
+  .create-bar input { flex: 1; padding: 8px 12px; background: #1a1a1a; border: 1px solid var(--border); border-radius: 6px; color: var(--text); font-size: 0.85rem; }
+  .create-bar select { padding: 8px; background: #1a1a1a; border: 1px solid var(--border); border-radius: 6px; color: var(--text); font-size: 0.8rem; }
+  .create-bar button { padding: 8px 16px; background: var(--accent); color: white; border: none; border-radius: 6px; cursor: pointer; font-weight: 600; }
+  .error { color: var(--red); font-size: 0.8rem; margin-top: 4px; }
+  .chat-box { height: 400px; overflow-y: auto; padding: 12px; background: #0d0d0d; border-radius: 8px; margin-bottom: 10px; font-size: 0.85rem; line-height: 1.6; }
+  .msg { margin-bottom: 10px; padding: 8px 12px; border-radius: 8px; }
+  .msg.user { background: #6366f118; color: var(--accent); }
+  .msg.agent { background: #1a1a1a; }
+  .msg.tool { background: #eab30810; color: var(--yellow); font-size: 0.78rem; font-family: monospace; }
+  .msg.system { color: var(--muted); font-size: 0.78rem; font-style: italic; }
+  .msg.error { color: var(--red); font-size: 0.8rem; }
+  .chat-bar { display: flex; gap: 8px; }
+  .chat-bar input { flex: 1; padding: 10px 14px; background: #1a1a1a; border: 1px solid var(--border); border-radius: 8px; color: var(--text); font-size: 0.9rem; outline: none; }
+  .chat-bar input:focus { border-color: var(--accent); }
+  .chat-bar button { padding: 10px 20px; background: var(--accent); color: white; border: none; border-radius: 8px; cursor: pointer; font-weight: 600; }
+  .chat-bar button:disabled { opacity: 0.4; cursor: not-allowed; }
+  .cost { color: var(--muted); font-size: 0.75rem; margin-top: 6px; text-align: right; }
+`