create-theokit 0.1.0-alpha.13 → 0.1.0-alpha.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.15",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

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

@@ -2,6 +2,8 @@
 
 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

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

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.13",
+    "theokit": "^0.1.0-alpha.15",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },

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

@@ -0,0 +1,34 @@
+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/dashboard/README.md.tmpl

@@ -2,6 +2,8 @@
 
 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

package/templates/dashboard/package.json.tmpl

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.13",
+    "theokit": "^0.1.0-alpha.15",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },

package/templates/dashboard/server/crons/cleanup-conversations.ts

@@ -0,0 +1,51 @@
+import { defineCron } from 'theokit/server/cron'
+import { readdir, stat, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+/**
+ * Daily GC of stale conversation transcripts.
+ *
+ * The `@usetheo/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({
+  name: 'cleanup-conversations',
+  schedule: '0 4 * * *', // Daily 04:00 UTC
+  handler: async ({ log }) => {
+    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: Awaited<ReturnType<typeof readdir>>
+    try {
+      entries = await readdir(root, { withFileTypes: true })
+    } catch {
+      log.info({ msg: 'No agents dir yet — first run', dir: root })
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const agentDir = join(root, 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++
+      }
+    }
+    log.info({ msg: 'cleanup-conversations complete', removed, kept, maxAgeDays: MAX_AGE_DAYS })
+  },
+})

package/templates/default/README.md.tmpl

@@ -2,6 +2,8 @@
 
 TheoKit project. Build the app your agent lives in — routing, auth, real-time, deploy — wired.
 
+> 📚 **Full docs:** https://docs.theokit.dev
+
 ## Quick start
 
 ```bash

package/templates/default/package.json.tmpl

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.13",
+    "theokit": "^0.1.0-alpha.15",
     "@usetheo/sdk": "^1.2.0",
     "@usetheo/ui": "^0.12.0-next.0",
     "lucide-react": "^0.469.0",

package/templates/default/server/crons/cleanup-conversations.ts

@@ -0,0 +1,51 @@
+import { defineCron } from 'theokit/server/cron'
+import { readdir, stat, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+/**
+ * Daily GC of stale conversation transcripts.
+ *
+ * The `@usetheo/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({
+  name: 'cleanup-conversations',
+  schedule: '0 4 * * *', // Daily 04:00 UTC
+  handler: async ({ log }) => {
+    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: Awaited<ReturnType<typeof readdir>>
+    try {
+      entries = await readdir(root, { withFileTypes: true })
+    } catch {
+      log.info({ msg: 'No agents dir yet — first run', dir: root })
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const agentDir = join(root, 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++
+      }
+    }
+    log.info({ msg: 'cleanup-conversations complete', removed, kept, maxAgeDays: MAX_AGE_DAYS })
+  },
+})

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

@@ -39,19 +39,28 @@ export const POST = defineAgentEndpoint({
     // 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.
-    const { agent } = await createConversationHistory({
-      request,
-      response: { headers: cookieHeaders },
-      options: {
-        // model id literal — provider resolution NÃO depende de prefix inference.
-        // Stranger pode trocar livremente sem mexer em routing.
-        model: { id: '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).
+    // 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 literal — provider resolution NÃO depende de prefix inference.
+          // Stranger pode trocar livremente sem mexer em routing.
+          model: { id: '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/postgres/README.md.tmpl

@@ -2,6 +2,8 @@
 
 TheoKit project with Postgres + Drizzle ORM wired. Schema-first, migration-aware, typed end-to-end.
 
+> 📚 **Full docs:** https://docs.theokit.dev
+
 ## Quick start
 
 ```bash

package/templates/postgres/package.json.tmpl

@@ -14,7 +14,7 @@
     "db:studio": "drizzle-kit studio"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.13",
+    "theokit": "^0.1.0-alpha.15",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "drizzle-orm": "^0.45.0",

package/templates/postgres/server/jobs/log-message.ts

@@ -0,0 +1,27 @@
+import { defineJob } from 'theokit/server/jobs'
+import { z } from 'zod'
+import { appendFile, mkdir } from 'node:fs/promises'
+import { resolve, dirname } from 'node:path'
+
+/**
+ * Background job demonstrating `defineJob` + `ctx.queue.enqueue` pattern.
+ *
+ * Triggered from `server/routes/users.ts` POST handler via:
+ *   await ctx.queue.enqueue('log-message', { userId, message })
+ *
+ * Per ADR-0003 (transactional outbox), enqueue is deferred until the
+ * route handler commits successfully — handler throws → 0 jobs dispatched.
+ */
+export default defineJob({
+  name: 'log-message',
+  input: z.object({ userId: z.string(), message: z.string() }),
+  handler: async ({ input, log }) => {
+    // v1.1 EC-9: anchor path to process.cwd() — handler CWD may differ from
+    // project root when running via external job runner.
+    const auditPath = resolve(process.cwd(), '.theo/audit.log')
+    await mkdir(dirname(auditPath), { recursive: true })
+    const line = `${new Date().toISOString()} user=${input.userId} msg=${input.message}\n`
+    await appendFile(auditPath, line)
+    log.info({ msg: 'audit logged', userId: input.userId, path: auditPath })
+  },
+})

package/templates/saas/README.md.tmpl

@@ -2,6 +2,8 @@
 
 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

package/templates/saas/package.json.tmpl

@@ -14,7 +14,7 @@
     "db:studio": "drizzle-kit studio"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.13",
+    "theokit": "^0.1.0-alpha.15",
     "@usetheo/ui": "^0.12.0-next.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

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

@@ -1,10 +1,20 @@
 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
+ * `@usetheo/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>({
@@ -12,10 +22,28 @@ export const POST = defineAgentEndpoint<{ message: string }, RequestContext>({
     requireAuth(ctx.session)
     const body = (await request.json()) as { message?: string }
     const msg = body.message ?? ''
-    yield {
-      type: 'message',
-      content: `Hello ${ctx.session.email}, you said: "${msg}"`,
+    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 },
+      )
     }
-    yield { type: 'message', content: '(Replace this mock with your LLM.)' }
   },
 })

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

@@ -0,0 +1,49 @@
+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 })
+  },
+})