create-theokit 0.2.3 → 0.5.0

package/templates/saas/README.md.tmpl

@@ -1,103 +0,0 @@
-# {{name}}
-
-TheoKit SaaS template — auth, sessions, billing-ready, and an agent route. The full stack for shipping an account-aware product on day one.
-
-> 📚 **Full docs:** https://docs.theokit.dev
-
-## Quick start
-
-```bash
-# 0. Provision Postgres (sessions + users)
-docker run --name pg -e POSTGRES_PASSWORD=dev -p 5432:5432 -d postgres:16
-# Or use a hosted Postgres (neon.tech / supabase.com)
-
-# 1. Set env (generate a strong session secret)
-cat > .env <<EOF
-DATABASE_URL=postgres://postgres:dev@localhost:5432/postgres
-SESSION_SECRET=$(openssl rand -base64 32)
-OPENROUTER_API_KEY=sk-or-v1-...
-EOF
-
-# 2. Migrate the schema
-pnpm db:generate
-pnpm db:migrate
-
-# 3. Boot the dev server
-npx theokit dev
-```
-
-## Sample auth flow
-
-```bash
-# Register
-curl -X POST http://localhost:3000/api/register \
-  -H 'Content-Type: application/json' \
-  -d '{"email":"alice@example.com","password":"strong-passphrase"}'
-
-# Login (saves session cookie)
-curl -X POST http://localhost:3000/api/login \
-  -H 'Content-Type: application/json' \
-  -d '{"email":"alice@example.com","password":"strong-passphrase"}' \
-  -c cookies.txt
-
-# Authenticated request
-curl http://localhost:3000/api/me -b cookies.txt
-```
-
-## Templates
-
-- **default** — TheoUI chat composer + agent route.
-- **dashboard** — nested layouts + sidebar.
-- **api-only** — server routes without React.
-- **postgres** — Drizzle ORM + migrations.
-- **saas** (this one) — full app with auth, billing, sessions.
-
-## What the framework auto-loads
-
-- **`.env` → `process.env`**. `SESSION_SECRET`, `DATABASE_URL`, `OPENROUTER_API_KEY` all required.
-- **Encrypted sessions** (AES-256-GCM) via `SESSION_SECRET`.
-- **`.theo/` build output cleanup** on every `theokit build`.
-
-## Project structure
-
-```
-app/                  Frontend
-├── page.tsx          /            — landing
-server/
-├── routes/
-│   ├── login.ts      POST /api/login    — sets session cookie
-│   ├── logout.ts     POST /api/logout   — clears session
-│   ├── me.ts         GET  /api/me       — requireAuth() guarded
-│   └── agent.ts      POST /api/agent    — agent SSE, requireAuth()
-db/
-├── schema.ts         users + sessions tables (Drizzle)
-└── migrations/       generated SQL (committed)
-drizzle.config.ts     Drizzle config
-theo.config.ts        Framework config
-.env                  Secrets — never committed
-```
-
-## Common commands
-
-| Command | What it does |
-|---|---|
-| `npx theokit dev` | Dev server with HMR + auth |
-| `npx theokit build` | Production build |
-| `npx theokit start` | Serve production build |
-| `pnpm db:generate` | Generate SQL migration |
-| `pnpm db:migrate` | Apply migrations |
-| `npm run typecheck` | TypeScript strict check |
-
-## Adding billing
-
-Stripe is the canonical path — add `STRIPE_SECRET_KEY` to `.env`, mount `server/routes/billing/webhook.ts` via `defineWebhook`, and wire plan checks into `requireAuth()`.
-
-## Troubleshooting
-
-- **`SESSION_SECRET must be at least 32 bytes`** → regenerate with `openssl rand -base64 32`.
-- **`relation "users" does not exist`** → run `pnpm db:migrate` first.
-- **`401 Unauthorized` on `/api/me`** → login first; cookie must be sent (`-b cookies.txt`).
-
-## License
-
-Apply your own. The TheoKit framework is Apache-2.0.

package/templates/saas/_gitignore

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

package/templates/saas/app/layout.tsx

@@ -1,5 +0,0 @@
-import type { PropsWithChildren } from 'react'
-
-export default function Layout({ children }: PropsWithChildren) {
-  return <>{children}</>
-}

package/templates/saas/app/page.tsx

@@ -1,104 +0,0 @@
-'use client'
-
-import { useEffect, useState } from 'react'
-import { AgentComposer, AgentTimeline, type AgentEvent as AgentRow } from '@theokit/ui'
-import { useAgentStream } from 'theokit/client'
-
-interface Me {
-  userId: string
-  email: string
-}
-
-export default function Page() {
-  const [me, setMe] = useState<Me | null>(null)
-  const [email, setEmail] = useState('demo@example.com')
-  const [composer, setComposer] = useState('')
-
-  const { events, send, status } = useAgentStream<{ message: string }>('/api/agent')
-
-  async function refreshMe() {
-    const res = await fetch('/api/me')
-    setMe(res.ok ? ((await res.json()) as Me) : null)
-  }
-
-  useEffect(() => {
-    refreshMe()
-  }, [])
-
-  async function login() {
-    await fetch('/api/login', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ email, password: 'demo' }),
-    })
-    refreshMe()
-  }
-  async function logout() {
-    await fetch('/api/logout', { method: 'POST' })
-    refreshMe()
-  }
-
-  if (!me) {
-    return (
-      <main
-        style={{ padding: 24, display: 'flex', flexDirection: 'column', gap: 8, maxWidth: 360 }}
-      >
-        <h1>Sign in</h1>
-        <input value={email} onChange={(e) => setEmail(e.target.value)} placeholder="email" />
-        <button type="button" onClick={login}>
-          Sign in (demo)
-        </button>
-      </main>
-    )
-  }
-
-  const rows: AgentRow[] = events.map((e, i) => ({
-    id: `e-${i}`,
-    type: e.type === 'tool_call' ? 'tool' : 'command',
-    label:
-      e.type === 'message'
-        ? e.content
-        : e.type === 'tool_call'
-          ? `tool: ${e.name}`
-          : e.type === 'error'
-            ? `error: ${e.message}`
-            : e.type,
-    status: e.type === 'error' ? 'failed' : 'success',
-    timestamp: new Date().toISOString(),
-  }))
-
-  return (
-    <main
-      style={{ display: 'flex', flexDirection: 'column', height: '100vh', padding: 24, gap: 16 }}
-    >
-      <header style={{ display: 'flex', justifyContent: 'space-between' }}>
-        <div>
-          <h1>SaaS Agent</h1>
-          <p style={{ color: '#888', fontSize: 14 }}>
-            Signed in as {me.email} · status: <code>{status}</code>
-          </p>
-        </div>
-        <button type="button" onClick={logout}>
-          Sign out
-        </button>
-      </header>
-      <section style={{ flex: 1, overflowY: 'auto' }}>
-        <AgentTimeline events={rows} />
-      </section>
-      <footer>
-        <AgentComposer
-          value={composer}
-          onValueChange={setComposer}
-          onSubmit={() => {
-            const v = composer.trim()
-            if (v) {
-              send({ message: v })
-              setComposer('')
-            }
-          }}
-          placeholder="Ask your agent…"
-        />
-      </footer>
-    </main>
-  )
-}

package/templates/saas/db/index.ts

@@ -1,6 +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/saas/db/schema.ts

@@ -1,20 +0,0 @@
-import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
-
-export const users = pgTable('users', {
-  id: uuid('id').primaryKey().defaultRandom(),
-  email: text('email').notNull().unique(),
-  passwordHash: text('password_hash').notNull(),
-  createdAt: timestamp('created_at').defaultNow().notNull(),
-})
-
-export const sessions = pgTable('sessions', {
-  id: uuid('id').primaryKey().defaultRandom(),
-  userId: uuid('user_id')
-    .references(() => users.id)
-    .notNull(),
-  expiresAt: timestamp('expires_at').notNull(),
-  createdAt: timestamp('created_at').defaultNow().notNull(),
-})
-
-export type User = typeof users.$inferSelect
-export type Session = typeof sessions.$inferSelect

package/templates/saas/drizzle.config.ts

@@ -1,10 +0,0 @@
-import type { Config } from 'drizzle-kit'
-
-export default {
-  schema: './db/schema.ts',
-  out: './drizzle',
-  dialect: 'postgresql',
-  dbCredentials: {
-    url: process.env.DATABASE_URL ?? '',
-  },
-} satisfies Config

package/templates/saas/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>SaaS Starter</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/@theo/entry-client"></script>
-  </body>
-</html>

package/templates/saas/package.json.tmpl

@@ -1,38 +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",
-    "db:push": "drizzle-kit push",
-    "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
-    "db:studio": "drizzle-kit studio"
-  },
-  "dependencies": {
-    "theokit": "^0.2.2",
-    "@theokit/ui": "^0.13.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "react-router": "^7.0.0",
-    "drizzle-orm": "^0.45.0",
-    "postgres": "^3.4.0",
-    "zod": "^3.24.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "typescript": "^5.7.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "drizzle-kit": "^0.31.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
-  }
-}

package/templates/saas/server/context.ts

@@ -1,37 +0,0 @@
-import { assertProductionSecret, createSessionManager, type SessionManager } from 'theokit/server'
-import type { IncomingMessage, ServerResponse } from 'node:http'
-import { db } from '../db/index.js'
-
-export interface UserSession {
-  userId: string
-  email: string
-}
-
-const SECRET = process.env.SECRET ?? 'CHANGE_ME_TO_RANDOM_32_PLUS_CHARS_FOR_REAL'
-
-// EC-2: dev warns + prod refuses to boot if SECRET is a placeholder.
-// Replace .env.example secret with `openssl rand -hex 32` before deploying.
-assertProductionSecret(SECRET)
-
-const sessions: SessionManager<UserSession> = createSessionManager({
-  secret: SECRET,
-  cookieName: 'theo_session',
-})
-
-export interface RequestContext {
-  sessions: SessionManager<UserSession>
-  session: UserSession | null
-  res: ServerResponse
-  db: typeof db
-}
-
-export async function createContext({
-  request,
-  response,
-}: {
-  request: IncomingMessage
-  response: ServerResponse
-}): Promise<RequestContext> {
-  const session = await sessions.getSession(request)
-  return { sessions, session, res: response, db }
-}

package/templates/saas/server/routes/agent.ts

@@ -1,49 +0,0 @@
-import { defineAgentEndpoint, requireAuth, type AgentEvent } from 'theokit/server'
-import { trackAgentRun } from 'theokit/server/cost'
-import type { RequestContext } from '../context.js'
-
-/**
- * Protected agent endpoint. `requireAuth` fires BEFORE the stream starts;
- * unauthorized requests get 401 immediately — no SSE bytes leak.
- *
- * Observability: wraps the run with `trackAgentRun` to surface per-user
- * cost + token usage to the configured `UsageStorageAdapter` (configure via
- * `theo.config.ts > cost.storage`). Also feeds the devtools `Agents` tab
- * (when running in dev).
- *
- * NOTE: `costUsd: 0` is a v1 stub. Pricing table integration is a
- * `@theokit/sdk` follow-up (R0.5.11). Devtools tab renders "$0.0000" —
- * indicates "cost tracking not yet calibrated for this model".
- *
- * Replace the mock generator with your LLM provider call.
- */
-export const POST = defineAgentEndpoint<{ message: string }, RequestContext>({
-  async *handler({ ctx, request }): AsyncGenerator<AgentEvent> {
-    requireAuth(ctx.session)
-    const body = (await request.json()) as { message?: string }
-    const msg = body.message ?? ''
-    try {
-      yield {
-        type: 'message',
-        content: `Hello ${ctx.session.email}, you said: "${msg}"`,
-      }
-      yield { type: 'message', content: '(Replace this mock with your LLM.)' }
-    } finally {
-      // Always emit observability — even on stream error / abort.
-      // `storage` resolved from theo.config.ts > cost.storage (undefined =
-      // no-op; configure to enable persistence + devtools tab visibility).
-      // To enable persistent cost tracking: wire `cost: { storage }` into
-      // `theo.config.ts` and forward via context. Demo passes `undefined`
-      // (no-op storage; still fires devtools dispatcher in dev mode).
-      await trackAgentRun(
-        {
-          userId: ctx.session.email,
-          model: 'mock/echo',
-          tokens: { input: msg.length, output: 0 }, // crude — real impl uses tokenizer
-          costUsd: 0, // v1 stub
-        },
-        { storage: undefined },
-      )
-    }
-  },
-})

package/templates/saas/server/routes/billing/stripe-webhook.ts

@@ -1,49 +0,0 @@
-import { defineWebhook } from 'theokit/server'
-import { createHmac, timingSafeEqual } from 'node:crypto'
-import { z } from 'zod'
-
-/**
- * Stripe webhook receiver.
- *
- * Verifies `Stripe-Signature` header per Stripe's documented HMAC-SHA256
- * scheme (https://stripe.com/docs/webhooks/signatures). Real impl would
- * handle `checkout.session.completed`, `invoice.paid`, etc.
- *
- * Setup:
- *   1. Create webhook endpoint in Stripe Dashboard pointing to /api/billing/stripe-webhook
- *   2. Copy signing secret → `.env` STRIPE_WEBHOOK_SECRET
- *   3. Test locally: `stripe listen --forward-to localhost:3000/api/billing/stripe-webhook`
- */
-const STRIPE_SECRET = process.env.STRIPE_WEBHOOK_SECRET ?? ''
-
-export const POST = defineWebhook({
-  verify: ({ rawBody, headers }) => {
-    if (STRIPE_SECRET === '') return false
-    const sigHeader = headers.get('stripe-signature') ?? ''
-    // Stripe format: `t=<unix-ts>,v1=<hash>` (potentially also v0)
-    const parts: Record<string, string> = {}
-    for (const pair of sigHeader.split(',')) {
-      const [k, v] = pair.split('=')
-      if (k && v) parts[k.trim()] = v.trim()
-    }
-    const t = parts['t']
-    const v1 = parts['v1']
-    if (!t || !v1) return false
-    const signedPayload = `${t}.${rawBody}`
-    const expected = createHmac('sha256', STRIPE_SECRET).update(signedPayload).digest('hex')
-    try {
-      return timingSafeEqual(Buffer.from(v1, 'utf-8'), Buffer.from(expected, 'utf-8'))
-    } catch {
-      return false
-    }
-  },
-  inputSchema: z.object({ type: z.string(), data: z.unknown() }),
-  handler: async ({ input, log }) => {
-    log.info({ msg: 'stripe webhook received', type: input.type })
-    // TODO: dispatch by input.type:
-    //   - 'checkout.session.completed' → activate subscription
-    //   - 'invoice.paid' → extend access
-    //   - 'invoice.payment_failed' → notify user + retry plan
-    return Response.json({ received: true })
-  },
-})

package/templates/saas/server/routes/login.ts

@@ -1,25 +0,0 @@
-import { defineRoute } from 'theokit/server'
-import { z } from 'zod'
-import type { RequestContext } from '../context.js'
-
-export const POST = defineRoute<
-  z.ZodUndefined,
-  z.ZodObject<{ email: z.ZodString; password: z.ZodString }>,
-  z.ZodUndefined,
-  RequestContext
->({
-  body: z.object({
-    email: z.string().email(),
-    password: z.string().min(1),
-  }),
-  handler: async ({ body, ctx }) => {
-    // DEMO ONLY — replace with bcrypt/argon2 password comparison against
-    // the users table. This stub accepts any password.
-    const userId = `u-${body.email}`
-    await ctx.sessions.createSession(ctx.res, {
-      userId,
-      email: body.email,
-    })
-    return { ok: true, email: body.email }
-  },
-})

package/templates/saas/server/routes/logout.ts

@@ -1,10 +0,0 @@
-import { defineRoute } from 'theokit/server'
-import type { z } from 'zod'
-import type { RequestContext } from '../context.js'
-
-export const POST = defineRoute<z.ZodUndefined, z.ZodUndefined, z.ZodUndefined, RequestContext>({
-  handler: ({ ctx }) => {
-    ctx.sessions.destroySession(ctx.res)
-    return { ok: true }
-  },
-})

package/templates/saas/server/routes/me.ts

@@ -1,10 +0,0 @@
-import { defineRoute, requireAuth } from 'theokit/server'
-import type { z } from 'zod'
-import type { RequestContext } from '../context.js'
-
-export const GET = defineRoute<z.ZodUndefined, z.ZodUndefined, z.ZodUndefined, RequestContext>({
-  handler: ({ ctx }) => {
-    requireAuth(ctx.session)
-    return { userId: ctx.session.userId, email: ctx.session.email }
-  },
-})

package/templates/saas/theo.config.ts

@@ -1,5 +0,0 @@
-import { defineConfig } from 'theokit'
-
-export default defineConfig({
-  ui: { theme: 'violet-forge', fonts: 'bundled' },
-})

package/templates/saas/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "jsx": "react-jsx",
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "noEmit": true,
-    "allowImportingTsExtensions": false
-  },
-  "include": ["app", "server", "db"]
-}

package/templates/services/agent-node/Dockerfile.tmpl

@@ -1,20 +0,0 @@
-FROM node:22-alpine
-
-WORKDIR /app
-
-# Install pnpm (or use npm if pnpm not available in image)
-RUN corepack enable && corepack prepare pnpm@latest --activate || true
-
-# Copy manifest and install
-COPY package.json ./
-RUN pnpm install --frozen-lockfile || npm install
-
-# Copy source
-COPY . .
-
-EXPOSE 8002
-
-HEALTHCHECK --interval=10s --timeout=5s --retries=3 \
-    CMD wget --spider -q http://localhost:8002/health || exit 1
-
-CMD ["pnpm", "start"]

package/templates/services/agent-node/README.md

@@ -1,38 +0,0 @@
-# Agent service (Node / Hono)
-
-This is a TheoKit polyglot sidecar generated by `create-theokit --backend node`.
-
-## Requirements
-
-- **Node.js 22+** (matches TheoKit's floor)
-- **pnpm** or **npm** (TheoKit's CLI prefers pnpm)
-
-## Run it
-
-The TheoKit app boots this service automatically via `pnpm dev` (per `theo.config.ts > services`).
-
-To run standalone:
-
-```bash
-cd services/agent-node
-pnpm install
-pnpm dev
-```
-
-## Endpoints
-
-- `GET /health` — healthcheck (returns `{"status":"ok"}`)
-- `POST /echo` — example: `{ "message": "..." }` → `{ "echo": "..." }`
-
-## What is wired
-
-- Native fetch handler via Hono (works on TheoCloud and local)
-- JSON-line stdout logs
-- W3C `traceparent` propagation from incoming headers
-- TheoKit injects `THEOKIT_SERVICE_NAME` + `THEOKIT_SERVICE_PORT` env vars
-
-## Add a tool the TheoKit agent can call
-
-Add another `app.post('/tool/<name>', ...)` handler. From the TheoKit TS side,
-`services.worker.<name>({...})` is auto-typed when an OpenAPI URL is reachable
-(Hey API integration — Phase 5).

package/templates/services/agent-node/package.json.tmpl

@@ -1,18 +0,0 @@
-{
-  "name": "{{name}}-agent-node",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "tsx watch src/index.ts",
-    "start": "tsx src/index.ts",
-    "build": "echo 'no build step; tsx runs TS directly'"
-  },
-  "dependencies": {
-    "hono": "^4.6.0",
-    "@hono/node-server": "^1.13.0"
-  },
-  "devDependencies": {
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
-  }
-}

package/templates/services/agent-node/src/index.ts

@@ -1,58 +0,0 @@
-/**
- * TheoKit polyglot agent service — Hono sidecar.
- *
- * Conforms to the Like-Vercel runtime contract (ADR-0015):
- *   - Fetch-handler entry (native fetch handler from Hono)
- *   - GET /health convention (200 / 503)
- *   - JSON-line stdout logs
- *   - W3C traceparent propagation
- *   - Env vars at runtime
- *
- * Generated by `create-theokit --backend node`.
- */
-import { Hono } from 'hono'
-import { serve } from '@hono/node-server'
-
-const SERVICE_NAME = process.env.THEOKIT_SERVICE_NAME ?? 'agent-node'
-const SERVICE_PORT = Number.parseInt(process.env.THEOKIT_SERVICE_PORT ?? '8002', 10)
-
-function log(
-  level: 'info' | 'warn' | 'error',
-  message: string,
-  extra: Record<string, unknown> = {},
-) {
-  // eslint-disable-next-line no-console -- structured stdout per ADR-0015 invariant #5
-  console.log(
-    JSON.stringify({
-      timestamp: new Date().toISOString(),
-      level,
-      message,
-      service: SERVICE_NAME,
-      ...extra,
-    }),
-  )
-}
-
-const app = new Hono()
-
-// ADR-0015 invariant #6 — W3C traceparent propagation
-app.use(async (c, next) => {
-  const tp = c.req.header('traceparent')
-  if (tp) {
-    log('info', 'request', { traceparent: tp, path: c.req.path })
-  }
-  await next()
-})
-
-// ADR-0015 invariant #4 — healthcheck convention
-app.get('/health', (c) => c.json({ status: 'ok' }))
-
-// Example endpoint — TheoKit proxies /api/worker/* to this service.
-app.post('/echo', async (c) => {
-  const body = (await c.req.json()) as { message: string }
-  return c.json({ echo: body.message })
-})
-
-serve({ fetch: app.fetch, port: SERVICE_PORT }, () => {
-  log('info', `agent-node listening on :${String(SERVICE_PORT)}`)
-})