create-theokit 0.2.3 → 0.5.0

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

@@ -0,0 +1,47 @@
+/**
+ * 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-decorators'
+
+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

@@ -0,0 +1,14 @@
+/**
+ * TimingInterceptor — logs request duration.
+ * Applied to both controllers and agents.
+ */
+import type { Interceptor } from '@theokit/http-decorators'
+
+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

@@ -0,0 +1,12 @@
+/**
+ * LoggerMiddleware — logs every incoming request.
+ */
+import type { NestMiddleware } from '@theokit/http-decorators'
+
+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/store.ts

@@ -0,0 +1,46 @@
+/**
+ * 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

@@ -0,0 +1,58 @@
+/**
+ * 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({ namespace: 'tasks' })
+@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'
+  }
+}

package/templates/default/tsconfig.json

@@ -1,15 +1,15 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
     "strict": true,
-    "noEmit": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
-    "jsx": "react-jsx",
-    "isolatedModules": true,
-    "resolveJsonModule": true
+    "outDir": "dist"
   },
-  "include": ["app/**/*.ts", "app/**/*.tsx", "server/**/*.ts"]
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
 }

package/templates/api-only/.nvmrc

@@ -1 +0,0 @@
-22.12

package/templates/api-only/README.md.tmpl

@@ -1,78 +0,0 @@
-# {{name}}
-
-TheoKit API-only project. Backend routes with Zod validation + typed responses — no frontend bundle, no React.
-
-> 📚 **Full docs:** https://docs.theokit.dev
-
-## Quick start
-
-```bash
-# 1. Set your provider key if you wire an agent route later
-echo 'OPENROUTER_API_KEY=sk-or-v1-...' > .env
-
-# 2. Boot the dev server
-npx theokit dev
-
-# 3. Probe the health route
-curl http://localhost:3000/api/health
-```
-
-You should see `{"status":"ok"}`. The server is now serving the routes under `server/routes/`.
-
-## Templates
-
-- **default** — TheoUI chat composer + agent route.
-- **dashboard** — nested layouts + sidebar.
-- **api-only** (this one) — server routes without React.
-- **postgres** — Drizzle ORM + migrations.
-- **saas** — full app with auth, billing, sessions.
-
-## What the framework auto-loads
-
-- **`.env` → `process.env`**. Edit `.env`; restart the dev server.
-- **`.theo/` build output cleanup** on every `theokit build`.
-- **Route discovery** — every `server/routes/*.ts` becomes a wired endpoint.
-
-## Project structure
-
-```
-server/
-├── routes/
-│   ├── health.ts     GET  /api/health  — returns {status:"ok"}
-│   └── users.ts      CRUD /api/users   — Zod-validated body
-theo.config.ts        Framework config
-.env                  Secrets — never committed (.gitignore)
-```
-
-## Sample requests
-
-```bash
-# Health check
-curl http://localhost:3000/api/health
-
-# Create a user (POST with JSON body)
-curl -X POST http://localhost:3000/api/users \
-  -H 'Content-Type: application/json' \
-  -d '{"name":"Alice","email":"alice@example.com"}'
-
-# List users
-curl http://localhost:3000/api/users
-```
-
-## Common commands
-
-| Command | What it does |
-|---|---|
-| `npx theokit dev` | Dev server with HMR + structured logs |
-| `npx theokit build` | Production build → `.theo/` |
-| `npx theokit start` | Serve the production build |
-| `npx theokit routes` | List all routes detected |
-| `npm run typecheck` | TypeScript strict check (no emit) |
-
-## Add a new route
-
-Drop a `.ts` file in `server/routes/`. Use `defineRoute` from `theokit/server` for Zod-validated handlers, or export `GET`/`POST` directly.
-
-## License
-
-Apply your own. The TheoKit framework is Apache-2.0.

package/templates/api-only/_gitignore

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

package/templates/api-only/app/page.tsx

@@ -1,3 +0,0 @@
-export default function Page() {
-  return <h1>Theo API Server</h1>
-}

package/templates/api-only/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Theo App</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/@theo/entry-client"></script>
-  </body>
-</html>

package/templates/api-only/package.json.tmpl

@@ -1,28 +0,0 @@
-{
-  "name": "{{name}}",
-  "version": "0.1.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "theokit dev",
-    "build": "theokit build",
-    "start": "theokit start",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "theokit": "^0.2.2",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "typescript": "^5.7.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
-  }
-}

package/templates/api-only/server/routes/health.ts

@@ -1,5 +0,0 @@
-import { defineRoute } from 'theokit/server'
-
-export const GET = defineRoute({
-  handler: () => ({ ok: true }),
-})

package/templates/api-only/server/routes/users.ts

@@ -1,27 +0,0 @@
-import { defineRoute } from 'theokit/server'
-import { z } from 'zod'
-
-const users = [
-  { id: '1', name: 'Alice', email: 'alice@example.com' },
-  { id: '2', name: 'Bob', email: 'bob@example.com' },
-]
-
-export const GET = defineRoute({
-  query: z.object({ search: z.string().optional() }),
-  handler: ({ query }) => {
-    if (query.search) {
-      return users.filter((u) => u.name.toLowerCase().includes(query.search!.toLowerCase()))
-    }
-    return users
-  },
-})
-
-export const POST = defineRoute({
-  body: z.object({ name: z.string().min(1), email: z.string().email() }),
-  status: 201,
-  handler: ({ body }) => ({
-    id: String(users.length + 1),
-    name: body.name,
-    email: body.email,
-  }),
-})

package/templates/api-only/server/routes/webhooks/echo.ts

@@ -1,34 +0,0 @@
-import { defineWebhook } from 'theokit/server'
-import { createHmac, timingSafeEqual } from 'node:crypto'
-import { z } from 'zod'
-
-/**
- * Echo webhook — demonstrates `defineWebhook` HMAC-SHA256 pattern
- * without depending on an external provider (Stripe, GitHub, etc.).
- *
- * Self-test:
- *   SECRET=$(openssl rand -base64 32)
- *   echo -n '{"message":"hi"}' | openssl dgst -sha256 -hmac "$SECRET"
- *   curl -X POST localhost:3000/api/webhooks/echo \
- *     -H "x-echo-signature: <hex from above>" \
- *     -H "Content-Type: application/json" \
- *     -d '{"message":"hi"}'
- */
-const ECHO_SECRET = process.env.ECHO_WEBHOOK_SECRET ?? ''
-
-export const POST = defineWebhook({
-  verify: ({ rawBody, headers }) => {
-    if (ECHO_SECRET === '') return false
-    const sig = headers.get('x-echo-signature') ?? ''
-    const expected = createHmac('sha256', ECHO_SECRET).update(rawBody).digest('hex')
-    try {
-      return timingSafeEqual(Buffer.from(sig, 'utf-8'), Buffer.from(expected, 'utf-8'))
-    } catch {
-      return false
-    }
-  },
-  inputSchema: z.object({ message: z.string() }),
-  handler: async ({ input }) => {
-    return Response.json({ echoed: input.message, timestamp: new Date().toISOString() })
-  },
-})

package/templates/api-only/theo.config.ts

@@ -1,3 +0,0 @@
-import { defineConfig } from 'theokit'
-
-export default defineConfig({})

package/templates/api-only/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noEmit": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "jsx": "react-jsx",
-    "isolatedModules": true,
-    "resolveJsonModule": true
-  },
-  "include": ["app/**/*.ts", "app/**/*.tsx", "server/**/*.ts"]
-}

package/templates/dashboard/.nvmrc

@@ -1 +0,0 @@
-22.12

package/templates/dashboard/README.md.tmpl

@@ -1,76 +0,0 @@
-# {{name}}
-
-TheoKit dashboard project. Build the app your agent lives in — with nested layouts and a sidebar wired from day one.
-
-> 📚 **Full docs:** https://docs.theokit.dev
-
-## Quick start
-
-```bash
-# 1. Set your provider key (OpenRouter recommended — one key, any model)
-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 dashboard shell with sidebar nav + content area, ready to host your agent panels.
-
-## Templates
-
-- **default** — TheoUI chat composer + agent route.
-- **dashboard** (this one) — nested layouts + sidebar nav.
-- **api-only** — server routes without React.
-- **postgres** — Drizzle ORM + migrations.
-- **saas** — full app with auth, billing, sessions.
-
-## What the framework auto-loads
-
-- **`.env` → `process.env`**. Edit `.env`; restart the dev server.
-- **`.theo/` build output cleanup** on every `theokit build`.
-- **Tailwind + `@theokit/ui` styling** auto-configured for the TheoUI surface.
-
-## Project structure
-
-```
-app/                  Frontend (file-based routing with nested layouts)
-├── layout.tsx        root wrapper — TheoUI provider + theme
-├── page.tsx          /              — dashboard home
-├── dashboard/
-│   ├── layout.tsx    /dashboard/*   — sidebar shell
-│   └── page.tsx      /dashboard     — primary panel
-server/               Backend (explicit routes)
-├── routes/
-│   └── health.ts     GET /api/health
-theo.config.ts        Framework config
-tailwind.config.ts    Tailwind theme tokens
-.env                  Secrets — never committed
-```
-
-## Common commands
-
-| Command | What it does |
-|---|---|
-| `npx theokit dev` | Dev server with HMR + devtools overlay |
-| `npx theokit build` | Production build → `.theo/` |
-| `npx theokit start` | Serve the production build |
-| `npx theokit check` | Lint for upgrade-readiness |
-| `npx theokit routes` | List all routes + actions detected |
-| `npm run typecheck` | TypeScript strict check (no emit) |
-
-## Add a new panel
-
-```bash
-mkdir -p app/dashboard/billing
-cat > app/dashboard/billing/page.tsx <<'EOF'
-export default function BillingPage() {
-  return <h2>Billing</h2>
-}
-EOF
-```
-
-The route appears at `/dashboard/billing` after HMR.
-
-## License
-
-Apply your own. The TheoKit framework is Apache-2.0.

package/templates/dashboard/_gitignore

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

package/templates/dashboard/app/about/page.tsx

@@ -1,3 +0,0 @@
-export default function AboutPage() {
-  return <h1>About</h1>
-}

package/templates/dashboard/app/dashboard/layout.tsx

@@ -1,10 +0,0 @@
-import { Outlet } from 'react-router'
-
-export default function DashboardLayout() {
-  return (
-    <div>
-      <h2>Dashboard Area</h2>
-      <Outlet />
-    </div>
-  )
-}

package/templates/dashboard/app/dashboard/page.tsx

@@ -1,3 +0,0 @@
-export default function DashboardPage() {
-  return <h1>Dashboard</h1>
-}

package/templates/dashboard/app/layout.tsx

@@ -1,14 +0,0 @@
-import { Outlet } from 'react-router'
-
-export default function RootLayout() {
-  return (
-    <div>
-      <nav>
-        <a href="/">Home</a> | <a href="/about">About</a> | <a href="/dashboard">Dashboard</a>
-      </nav>
-      <main>
-        <Outlet />
-      </main>
-    </div>
-  )
-}

package/templates/dashboard/app/page.tsx

@@ -1,8 +0,0 @@
-export default function HomePage() {
-  return (
-    <div>
-      <h1>Welcome to Theo</h1>
-      <p>Your fullstack TypeScript framework.</p>
-    </div>
-  )
-}

package/templates/dashboard/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Theo App</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/@theo/entry-client"></script>
-  </body>
-</html>

package/templates/dashboard/package.json.tmpl

@@ -1,28 +0,0 @@
-{
-  "name": "{{name}}",
-  "version": "0.1.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "theokit dev",
-    "build": "theokit build",
-    "start": "theokit start",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "theokit": "^0.2.2",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "typescript": "^5.7.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
-  }
-}