create-theokit 0.4.0-beta.0 → 0.5.1

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.4.0-beta.0",
-    "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/dashboard/server/crons/cleanup-conversations.ts

@@ -1,59 +0,0 @@
-import { defineCron } from 'theokit/server/cron'
-import { readdir, stat, rm } from 'node:fs/promises'
-import type { Dirent } from 'node:fs'
-import { join, resolve } from 'node:path'
-
-/**
- * Daily GC of stale conversation transcripts.
- *
- * The `@theokit/sdk` Agent persists chat history under
- * `.theokit/agents/<agentId>/messages.jsonl`. With no TTL the directory
- * grows unbounded — production foot-gun. This cron removes any agent
- * directory whose `messages.jsonl` hasn't been touched in 30 days.
- */
-const MAX_AGE_DAYS = 30
-const AGENTS_DIR = '.theokit/agents'
-
-export default defineCron('cleanup-conversations', {
-  schedule: '0 4 * * *', // Daily 04:00 UTC
-  handler: async ({ traceId }) => {
-    const root = resolve(process.cwd(), AGENTS_DIR)
-    const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000
-    let removed = 0
-    let kept = 0
-    let entries: Dirent[]
-    try {
-      entries = (await readdir(root, { withFileTypes: true })) as unknown as Dirent[]
-    } catch {
-      console.info(JSON.stringify({ msg: 'No agents dir yet — first run', dir: root, traceId }))
-      return
-    }
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue
-      const agentDir = join(root, String(entry.name))
-      const messagesFile = join(agentDir, 'messages.jsonl')
-      try {
-        const s = await stat(messagesFile)
-        if (s.mtimeMs < cutoff) {
-          await rm(agentDir, { recursive: true, force: true })
-          removed++
-        } else {
-          kept++
-        }
-      } catch {
-        // messages.jsonl missing → orphan dir, remove
-        await rm(agentDir, { recursive: true, force: true }).catch(() => {})
-        removed++
-      }
-    }
-    console.info(
-      JSON.stringify({
-        msg: 'cleanup-conversations complete',
-        removed,
-        kept,
-        maxAgeDays: MAX_AGE_DAYS,
-        traceId,
-      }),
-    )
-  },
-})

package/templates/dashboard/server/routes/health.ts

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

package/templates/dashboard/theo.config.ts

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

package/templates/dashboard/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/default/.nvmrc

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

package/templates/default/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/default/server/crons/cleanup-conversations.ts

@@ -1,59 +0,0 @@
-import { defineCron } from 'theokit/server/cron'
-import { readdir, stat, rm } from 'node:fs/promises'
-import type { Dirent } from 'node:fs'
-import { join, resolve } from 'node:path'
-
-/**
- * Daily GC of stale conversation transcripts.
- *
- * The `@theokit/sdk` Agent persists chat history under
- * `.theokit/agents/<agentId>/messages.jsonl`. With no TTL the directory
- * grows unbounded — production foot-gun. This cron removes any agent
- * directory whose `messages.jsonl` hasn't been touched in 30 days.
- */
-const MAX_AGE_DAYS = 30
-const AGENTS_DIR = '.theokit/agents'
-
-export default defineCron('cleanup-conversations', {
-  schedule: '0 4 * * *', // Daily 04:00 UTC
-  handler: async ({ traceId }) => {
-    const root = resolve(process.cwd(), AGENTS_DIR)
-    const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000
-    let removed = 0
-    let kept = 0
-    let entries: Dirent[]
-    try {
-      entries = (await readdir(root, { withFileTypes: true })) as unknown as Dirent[]
-    } catch {
-      console.info(JSON.stringify({ msg: 'No agents dir yet — first run', dir: root, traceId }))
-      return
-    }
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue
-      const agentDir = join(root, String(entry.name))
-      const messagesFile = join(agentDir, 'messages.jsonl')
-      try {
-        const s = await stat(messagesFile)
-        if (s.mtimeMs < cutoff) {
-          await rm(agentDir, { recursive: true, force: true })
-          removed++
-        } else {
-          kept++
-        }
-      } catch {
-        // messages.jsonl missing → orphan dir, remove
-        await rm(agentDir, { recursive: true, force: true }).catch(() => {})
-        removed++
-      }
-    }
-    console.info(
-      JSON.stringify({
-        msg: 'cleanup-conversations complete',
-        removed,
-        kept,
-        maxAgeDays: MAX_AGE_DAYS,
-        traceId,
-      }),
-    )
-  },
-})

package/templates/default/server/routes/chat.ts

@@ -1,69 +0,0 @@
-import { z } from 'zod'
-import {
-  defineAgentEndpoint,
-  defineAgentTool,
-  streamAgentRun,
-  createConversationHistory,
-  type AgentEvent,
-} from 'theokit/server'
-
-/**
- * Chat agent endpoint — persistent conversation via createConversationHistory.
- *
- * Each browser tab gets a stable conversation id cookie on first visit;
- * subsequent requests resume the same agent. Conversation turns auto-persist
- * in `<cwd>/.theokit/agents/<conversationId>/messages.jsonl` (SDK owns
- * storage). Tools: current_time example. Memory facts: opt-in via
- * options.memory (off by default).
- *
- * Provider: OPENROUTER_API_KEY (preferred — gateway to many models) OR
- * ANTHROPIC_API_KEY (direct Anthropic).
- */
-
-const currentTime = defineAgentTool({
-  name: 'current_time',
-  description: 'Get the current ISO timestamp on the server.',
-  inputSchema: z.object({}),
-  handler: () => new Date().toISOString(),
-})
-
-export const POST = defineAgentEndpoint({
-  async *handler({ body, request, cookieHeaders, signal }): AsyncGenerator<AgentEvent> {
-    const safeBody =
-      body !== null && typeof body === 'object' && !Array.isArray(body)
-        ? (body as { message?: string })
-        : {}
-    const { message = '' } = safeBody
-    // Provider resolution centralizada (Strategy pattern) — theokit/server resolve
-    // apiKey + baseUrl + provider automático via OPENROUTER_API_KEY / OPENAI_API_KEY /
-    // ANTHROPIC_API_KEY presente no env. Wire protocol: OpenAI Chat Completions
-    // (universal — todos os providers implementam essa API). Consumer NÃO tem
-    // conditionals sobre provider — é responsabilidade do framework.
-    // Wrap full agent lifecycle in try/catch — provider errors (invalid KEY,
-    // 401, rate-limit, model-not-found, 5xx) MUST surface as AgentEvent
-    // 'error' so the client renders an actionable message instead of a
-    // silent SSE closure. Dogfood chaos Phase 12 validates this contract.
-    try {
-      const { agent } = await createConversationHistory({
-        request,
-        response: { headers: cookieHeaders },
-        options: {
-          // Model id is prefixed with the provider namespace. When using
-          // OPENROUTER_API_KEY (default), prefixes route to the correct
-          // upstream — `openai/`, `anthropic/`, `google/`, `meta-llama/`,
-          // `mistralai/`, `groq/`, etc. See https://openrouter.ai/models.
-          // Without the prefix the SDK falls back to a stub response.
-          model: { id: 'openai/gpt-4o-mini' },
-          tools: [currentTime],
-        },
-      })
-      const run = await agent.send(message, { signal })
-      yield* streamAgentRun(run)
-      // Intentionally NO agent.dispose() — the agent stays registered so the
-      // next request from the same conversation resumes it (continuity).
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err)
-      yield { type: 'error', message: `Agent error: ${msg}` }
-    }
-  },
-})

package/templates/default/server/routes/health.ts

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

package/templates/default/theo.config.ts

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

package/templates/default/types/jobs.d.ts

@@ -1,25 +0,0 @@
-/**
- * JobRegistry augmentation — REQUIRED for typed `ctx.queue.enqueue` calls.
- *
- * Without this augmentation, `ctx.queue.enqueue('foo', ...)` errors with:
- *   "Type 'foo' is not assignable to type 'never'"
- *
- * This is the canonical TheoKit jobs onboarding bug (EC-110). To add a
- * job:
- *
- * 1. Create `server/jobs/<name>.ts` exporting `defineJob('<name>', ...)`
- * 2. Add `'<name>': { ...inputShape }` below
- * 3. Use `ctx.queue.enqueue('<name>', { ...input })` from any route handler
- *
- * See: docs/concepts/jobs.md
- */
-declare module 'theokit/server' {
-  interface JobRegistry {
-    // Add your jobs here. Examples (uncomment and customize):
-    //
-    // 'process-document': { documentId: string }
-    // 'send-email': { to: string; subject: string; body: string }
-  }
-}
-
-export {}

package/templates/postgres/.env.example

@@ -1,5 +0,0 @@
-# Database connection string
-DATABASE_URL=postgresql://user:password@localhost:5432/mydb
-
-# Session secret (min 32 characters)
-# SESSION_SECRET=change-me-to-a-random-string-at-least-32-chars

package/templates/postgres/.nvmrc

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

package/templates/postgres/README.md.tmpl

@@ -1,83 +0,0 @@
-# {{name}}
-
-TheoKit project with Postgres + Drizzle ORM wired. Schema-first, migration-aware, typed end-to-end.
-
-> 📚 **Full docs:** https://docs.theokit.dev
-
-## Quick start
-
-```bash
-# 0. Provision Postgres
-#    Option A — local docker (one-liner):
-docker run --name pg -e POSTGRES_PASSWORD=dev -p 5432:5432 -d postgres:16
-#    Option B — hosted: neon.tech, supabase.com, fly.io
-
-# 1. Set env
-cat > .env <<'EOF'
-DATABASE_URL=postgres://postgres:dev@localhost:5432/postgres
-OPENROUTER_API_KEY=sk-or-v1-...
-EOF
-
-# 2. Generate + apply migrations
-pnpm db:generate
-pnpm db:migrate
-
-# 3. Boot the dev server
-npx theokit dev
-```
-
-Open the printed URL. The default surface includes a sample users API backed by Postgres.
-
-## Templates
-
-- **default** — TheoUI chat composer + agent route.
-- **dashboard** — nested layouts + sidebar.
-- **api-only** — server routes without React.
-- **postgres** (this one) — Drizzle ORM + migrations.
-- **saas** — full app with auth, billing, sessions.
-
-## What the framework auto-loads
-
-- **`.env` → `process.env`**. `DATABASE_URL` must be set before `pnpm db:migrate`.
-- **`.theo/` build output cleanup** on every `theokit build`.
-- **Drizzle schema** under `db/schema.ts` drives migrations + typed query builder.
-
-## Project structure
-
-```
-app/                  Frontend
-├── page.tsx          /              — sample UI
-server/
-├── routes/
-│   ├── health.ts     GET  /api/health
-│   └── users.ts      CRUD /api/users  — backed by db.users
-db/
-├── schema.ts         Drizzle schema (tables + relations)
-├── client.ts         Drizzle client (used by routes)
-└── migrations/       Generated SQL files (committed)
-drizzle.config.ts     Drizzle CLI config
-theo.config.ts        Framework config
-.env                  Secrets — never committed
-```
-
-## Common commands
-
-| Command | What it does |
-|---|---|
-| `npx theokit dev` | Dev server with HMR |
-| `npx theokit build` | Production build |
-| `npx theokit start` | Serve production build |
-| `pnpm db:generate` | Generate SQL migration from `db/schema.ts` |
-| `pnpm db:migrate` | Apply pending migrations to `DATABASE_URL` |
-| `pnpm db:studio` | Open Drizzle Studio UI |
-| `npm run typecheck` | TypeScript strict check |
-
-## Troubleshooting
-
-- **`pnpm db:migrate` fails with "ECONNREFUSED"** → check `DATABASE_URL` host:port + Postgres is running (`docker ps` or hosted dashboard).
-- **`relation "users" does not exist`** → you forgot `pnpm db:migrate`. Run it.
-- **Schema change not reflected** → `pnpm db:generate` first, then `pnpm db:migrate`.
-
-## License
-
-Apply your own. The TheoKit framework is Apache-2.0.

package/templates/postgres/_gitignore

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

package/templates/postgres/app/layout.tsx

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

package/templates/postgres/app/page.tsx

@@ -1,8 +0,0 @@
-export default function Page() {
-  return (
-    <div>
-      <h1>Theo + Postgres</h1>
-      <p>Full-stack TypeScript with Drizzle ORM</p>
-    </div>
-  )
-}

package/templates/postgres/db/index.ts

@@ -1,7 +0,0 @@
-import { drizzle } from 'drizzle-orm/postgres-js'
-import postgres from 'postgres'
-import * as schema from './schema.js'
-
-const client = postgres(process.env.DATABASE_URL!)
-
-export const db = drizzle(client, { schema })

package/templates/postgres/db/schema.ts

@@ -1,8 +0,0 @@
-import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
-
-export const users = pgTable('users', {
-  id: uuid('id').primaryKey().defaultRandom(),
-  name: text('name').notNull(),
-  email: text('email').notNull().unique(),
-  createdAt: timestamp('created_at').defaultNow().notNull(),
-})