theokit 0.4.0-beta.0 → 0.5.0

package/dist/error-envelope-BsNzzAV5.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Error envelope — canonical cross-layer contract for theokit framework, SDK,
+ * and UI per plan g5-error-envelope-cross-layer v1.0 § Phase 1 / T1.1.
+ *
+ * Blueprint G5 (SHIPPABLE_WITH_CAVEATS 89/100) — Form 4 Hybrid: shared CODE
+ * enum + per-domain extensions + 2-layer SDK boundary translation.
+ *
+ * 3/3 references convergence: code + message + cause base (trpc TRPCError
+ * + hono HTTPException + encore Error). Wasp confirms ecosystem gap.
+ *
+ * Reference anchors (verified file:line):
+ * - referencia: trpc/packages/server/src/unstable-core-do-not-import/error/TRPCError.ts:65-87
+ * - referencia: trpc/packages/server/src/unstable-core-do-not-import/rpc/codes.ts:11-44,76-81
+ * - referencia: hono/src/http-exception.ts:46-78
+ * - referencia: encore/runtimes/go/beta/errs/error.go:38-55 (Go — D4 disclaimer applied)
+ *
+ * Per blueprint ADR D2: retryable + hint are extension slots, NOT base fields
+ * (3/3 references derive retryability from code identity; no reference ships
+ * a `retryable: boolean` on envelope; `hint` is novel).
+ *
+ * Per blueprint ADR D5: server-only `meta` filtered at serializer boundary
+ * (encore `json:"-"` analog).
+ *
+ * Lives in `core/contracts/` per architecture.md v3 — canonical home for
+ * shared client↔server types. Zero intra-monorepo deps; zero runtime deps
+ * (trpc + hono ship envelope with zero runtime deps per blueprint Q5).
+ */
+/**
+ * Canonical TheoKit error code union. HTTP-status flavor + SDK/agent-domain
+ * additions per blueprint Recommendations § concrete shape.
+ *
+ * String-literal union mirrors trpc's TRPC_ERROR_CODE_KEY pattern — enables
+ * exhaustive `switch (env.code)` narrowing in consumer code (UI display
+ * dispatch, retry-policy gates, telemetry classification).
+ */
+type TheoErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'CONFLICT' | 'PRECONDITION_FAILED' | 'PAYLOAD_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'TOO_MANY_REQUESTS' | 'INTERNAL_SERVER_ERROR' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'GATEWAY_TIMEOUT' | 'AGENT_RUN_ERROR' | 'PROVIDER_KEY_MISSING' | 'BUDGET_EXCEEDED' | 'RATE_LIMITED' | 'CREDENTIAL_POOL_EXHAUSTED';
+/**
+ * Base envelope shape — `{ code, message, cause?, meta?, ext? }`.
+ *
+ * `cause` follows TC39 proposal-error-cause (universal pattern, 3/3 references).
+ * `meta` is server-only metadata filtered at serializer boundary per ADR D5
+ * (`stack` is auto-stripped in non-dev builds — see T1.2 `TheoError.toJSON()`).
+ * `ext` carries opt-in per-domain extensions (`ValidationFieldsExt`,
+ * `RetryableExt`, `HintExt`, or arbitrary user-defined types via formatter hook).
+ */
+interface TheoErrorEnvelope<TExt = unknown> {
+    readonly code: TheoErrorCode;
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly meta?: Record<string, unknown>;
+    readonly ext?: TExt;
+}
+/**
+ * `ValidationFieldsExt` — validation-failure extension carrying the dot-notation
+ * field map identical to G3 `ActionInputError.fields`. Empty-string key for
+ * root-level errors (mirrors G3 EC-7). Multiple messages per key are preserved.
+ */
+interface ValidationFieldsExt {
+    readonly fields: Record<string, string[]>;
+}
+
+export type { TheoErrorEnvelope as T, ValidationFieldsExt as V, TheoErrorCode as a };

package/dist/{generate-DT4IIAHF.js → generate-AZ2K6Z2Z.js}

@@ -5,7 +5,7 @@ import "./chunk-KT3MWNZG.js";
 // src/cli/commands/generate.ts
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { resolve, dirname } from "path";
-var VALID_TYPES = ["route", "action", "page", "ws"];
+var VALID_TYPES = ["route", "action", "page", "ws", "controller", "agent", "toolbox"];
 function toKebabCase(name) {
   return /^[a-z][a-z0-9/-]*$/.test(name);
 }
@@ -48,6 +48,23 @@ function generateRouteTemplate(name) {
     ``
   ].join("\n");
 }
+function generateControllerTemplate(name) {
+  const className = toPascalCase(name) + "Controller";
+  const baseName = name.split("/").pop() ?? name;
+  return [
+    `// AUTO-GENERATED by \`theokit generate controller ${name}\``,
+    `import { Controller, Get } from '@theokit/http'`,
+    ``,
+    `@Controller('${baseName}')`,
+    `export class ${className} {`,
+    `  @Get()`,
+    `  findAll(): string {`,
+    `    return 'This action returns all ${baseName}'`,
+    `  }`,
+    `}`,
+    ``
+  ].join("\n");
+}
 function generateActionTemplate(name) {
   const camel = toCamelCase(name);
   return [
@@ -63,6 +80,47 @@ function generateActionTemplate(name) {
     ``
   ].join("\n");
 }
+function generateAgentTemplate(name) {
+  const pascal = toPascalCase(name);
+  return [
+    `import 'reflect-metadata'`,
+    `import { Agent, MainLoop } from '@theokit/agents'`,
+    `import { UseGuards } from '@theokit/http'`,
+    ``,
+    `@Agent({`,
+    `  name: '${name}',`,
+    `  route: '/api/agents/${name}',`,
+    `  model: 'openai/gpt-4o-mini',`,
+    `  systemPrompt: 'You are a helpful ${name} assistant.',`,
+    `})`,
+    `export class ${pascal}Agent {`,
+    `  @MainLoop({ strategy: 'react', maxIterations: 5 })`,
+    `  async run() {}`,
+    `}`,
+    ``
+  ].join("\n");
+}
+function generateToolboxTemplate(name) {
+  const pascal = toPascalCase(name);
+  return [
+    `import 'reflect-metadata'`,
+    `import { z } from 'zod'`,
+    `import { Toolbox, Tool } from '@theokit/agents'`,
+    ``,
+    `@Toolbox({ namespace: '${name}' })`,
+    `export class ${pascal}Tools {`,
+    `  @Tool({`,
+    `    name: 'hello',`,
+    `    description: 'Say hello',`,
+    `    input: z.object({ name: z.string() }),`,
+    `  })`,
+    `  async hello(input: { name: string }) {`,
+    `    return \`Hello, \${input.name}!\``,
+    `  }`,
+    `}`,
+    ``
+  ].join("\n");
+}
 function resolveTemplate(cwd, type, name) {
   switch (type) {
     case "route":
@@ -82,6 +140,21 @@ function resolveTemplate(cwd, type, name) {
         filePath: resolve(cwd, "server/ws", `${name}.ts`),
         content: generateWsTemplate(name)
       };
+    case "controller":
+      return {
+        filePath: resolve(cwd, "server/controllers", `${name}.controller.ts`),
+        content: generateControllerTemplate(name)
+      };
+    case "agent":
+      return {
+        filePath: resolve(cwd, "server/agents", `${name}.agent.ts`),
+        content: generateAgentTemplate(name)
+      };
+    case "toolbox":
+      return {
+        filePath: resolve(cwd, "server/toolboxes", `${name}.tools.ts`),
+        content: generateToolboxTemplate(name)
+      };
     default:
       return null;
   }
@@ -205,4 +278,4 @@ export {
   generate,
   generateCommand
 };
-//# sourceMappingURL=generate-DT4IIAHF.js.map
+//# sourceMappingURL=generate-AZ2K6Z2Z.js.map

package/dist/generate-AZ2K6Z2Z.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/commands/generate.ts"],"sourcesContent":["/* eslint-disable security/detect-non-literal-fs-filename --\n * CLI `theo generate`. Writes scaffolded files under `cwd` + a generator\n * name from CLI args. Build-time tool. No HTTP input.\n */\nimport { existsSync, mkdirSync, writeFileSync } from 'node:fs'\nimport { resolve, dirname } from 'node:path'\n\nexport const VALID_TYPES = ['route', 'action', 'page', 'ws', 'controller', 'agent', 'toolbox'] as const\nexport type GeneratorType = (typeof VALID_TYPES)[number]\n\nexport interface GenerateOptions {\n  cwd: string\n  type: string\n  name: string\n}\n\nexport type GenerateStatus =\n  | 'created'\n  | 'already_exists'\n  | 'invalid_kind'\n  | 'invalid_name'\n  | 'not_a_project'\n\nexport interface GenerateResult {\n  status: GenerateStatus\n  filePath?: string\n  kind?: GeneratorType\n  name?: string\n  message?: string\n}\n\nfunction toKebabCase(name: string): boolean {\n  return /^[a-z][a-z0-9/-]*$/.test(name)\n}\n\n/**\n * Reserved JS identifier names that conflict with object prototype machinery\n * or would shadow built-in module shapes if used as action/route names.\n * Mirrors action-scan's RESERVED_NAMES (T1.4).\n */\nconst RESERVED_BASENAMES = new Set([\n  'index',\n  'constructor',\n  '__proto__',\n  'prototype',\n  'hasOwnProperty',\n])\n\n/**\n * Validate that a name segment doesn't hit the reserved-identifier list.\n * Checks the BASENAME (last `/` segment) — nested `admin/constructor` still\n * rejected because the file `constructor.ts` would be the conflict.\n */\nfunction hasReservedSegment(name: string): boolean {\n  const basename = name.includes('/') ? (name.split('/').pop() ?? name) : name\n  return RESERVED_BASENAMES.has(basename)\n}\n\n/**\n * EC-4: validate that resolving `targetSubpath` under `cwd` stays inside `cwd`.\n * Returns `true` when path is safe (stays inside), `false` when it escapes via\n * `..`, absolute path, null byte, or similar traversal vector.\n */\nfunction isPathInside(cwd: string, targetSubpath: string): boolean {\n  if (targetSubpath.includes('\\x00')) return false\n  if (targetSubpath.startsWith('/') || targetSubpath.startsWith('\\\\')) return false\n  const resolved = resolve(cwd, targetSubpath)\n  const cwdResolved = resolve(cwd)\n  const sep = process.platform === 'win32' ? '\\\\' : '/'\n  return resolved === cwdResolved || resolved.startsWith(cwdResolved + sep)\n}\n\nfunction toPascalCase(name: string): string {\n  return name\n    .split(/[-/]/)\n    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))\n    .join('')\n}\n\nfunction toCamelCase(name: string): string {\n  const pascal = toPascalCase(name)\n  return pascal.charAt(0).toLowerCase() + pascal.slice(1)\n}\n\nfunction generateRouteTemplate(name: string): string {\n  return [\n    `import { defineRoute } from 'theokit/server'`,\n    `import { z } from 'zod'`,\n    ``,\n    `export const GET = defineRoute({`,\n    `  handler: ({ ctx }) => {`,\n    `    return { message: 'TODO: implement ${name} GET' }`,\n    `  },`,\n    `})`,\n    ``,\n  ].join('\\n')\n}\n\nfunction generateControllerTemplate(name: string): string {\n  const className = toPascalCase(name) + 'Controller'\n  const baseName = name.split('/').pop() ?? name\n  return [\n    `// AUTO-GENERATED by \\`theokit generate controller ${name}\\``,\n    `import { Controller, Get } from '@theokit/http'`,\n    ``,\n    `@Controller('${baseName}')`,\n    `export class ${className} {`,\n    `  @Get()`,\n    `  findAll(): string {`,\n    `    return 'This action returns all ${baseName}'`,\n    `  }`,\n    `}`,\n    ``,\n  ].join('\\n')\n}\n\nfunction generateActionTemplate(name: string): string {\n  const camel = toCamelCase(name)\n  return [\n    `import { defineAction } from 'theokit/server'`,\n    `import { z } from 'zod'`,\n    ``,\n    `export const ${camel} = defineAction({`,\n    `  input: z.object({}),`,\n    `  handler: ({ input, ctx }) => {`,\n    `    return { message: 'TODO: implement ${name}' }`,\n    `  },`,\n    `})`,\n    ``,\n  ].join('\\n')\n}\n\n/**\n * Co-located test template for `theokit generate action <name>` (T5.2 +\n * plan Q4 cenário 1: roundtrip serialize). Skeleton uses vitest BDD shape\n * per testing.md.\n */\nfunction generateAgentTemplate(name: string): string {\n  const pascal = toPascalCase(name)\n  return [\n    `import 'reflect-metadata'`,\n    `import { Agent, MainLoop } from '@theokit/agents'`,\n    `import { UseGuards } from '@theokit/http'`,\n    ``,\n    `@Agent({`,\n    `  name: '${name}',`,\n    `  route: '/api/agents/${name}',`,\n    `  model: 'openai/gpt-4o-mini',`,\n    `  systemPrompt: 'You are a helpful ${name} assistant.',`,\n    `})`,\n    `export class ${pascal}Agent {`,\n    `  @MainLoop({ strategy: 'react', maxIterations: 5 })`,\n    `  async run() {}`,\n    `}`,\n    ``,\n  ].join('\\n')\n}\n\nfunction generateToolboxTemplate(name: string): string {\n  const pascal = toPascalCase(name)\n  return [\n    `import 'reflect-metadata'`,\n    `import { z } from 'zod'`,\n    `import { Toolbox, Tool } from '@theokit/agents'`,\n    ``,\n    `@Toolbox({ namespace: '${name}' })`,\n    `export class ${pascal}Tools {`,\n    `  @Tool({`,\n    `    name: 'hello',`,\n    `    description: 'Say hello',`,\n    `    input: z.object({ name: z.string() }),`,\n    `  })`,\n    `  async hello(input: { name: string }) {`,\n    `    return \\`Hello, \\${input.name}!\\``,\n    `  }`,\n    `}`,\n    ``,\n  ].join('\\n')\n}\n\nfunction resolveTemplate(\n  cwd: string,\n  type: GeneratorType,\n  name: string,\n): { filePath: string; content: string } | null {\n  switch (type) {\n    case 'route':\n      return {\n        filePath: resolve(cwd, 'server/routes', `${name}.ts`),\n        content: generateRouteTemplate(name),\n      }\n    case 'action':\n      return {\n        filePath: resolve(cwd, 'server/actions', `${name}.ts`),\n        content: generateActionTemplate(name),\n      }\n    case 'page':\n      return { filePath: resolve(cwd, `app/${name}/page.tsx`), content: generatePageTemplate(name) }\n    case 'ws':\n      return {\n        filePath: resolve(cwd, 'server/ws', `${name}.ts`),\n        content: generateWsTemplate(name),\n      }\n    case 'controller':\n      return {\n        filePath: resolve(cwd, 'server/controllers', `${name}.controller.ts`),\n        content: generateControllerTemplate(name),\n      }\n    case 'agent':\n      return {\n        filePath: resolve(cwd, 'server/agents', `${name}.agent.ts`),\n        content: generateAgentTemplate(name),\n      }\n    case 'toolbox':\n      return {\n        filePath: resolve(cwd, 'server/toolboxes', `${name}.tools.ts`),\n        content: generateToolboxTemplate(name),\n      }\n    default:\n      return null\n  }\n}\n\nfunction generateActionTestTemplate(name: string): string {\n  const camel = toCamelCase(name)\n  return [\n    `import { describe, it, expect } from 'vitest'`,\n    ``,\n    `import { ${camel} } from './${name.split('/').pop()}.js'`,\n    ``,\n    `describe('${name} action', () => {`,\n    `  it('should accept a valid input shape', () => {`,\n    `    expect(${camel}.input).toBeDefined()`,\n    `    expect(typeof ${camel}.handler).toBe('function')`,\n    `  })`,\n    ``,\n    `  it('should reject invalid input via zod schema', () => {`,\n    `    const parsed = ${camel}.input.safeParse({ __invalid: true })`,\n    `    // Empty object schema accepts {}; tighten this assertion when adding fields.`,\n    `    expect(parsed.success).toBe(true)`,\n    `  })`,\n    `})`,\n    ``,\n  ].join('\\n')\n}\n\nfunction generatePageTemplate(name: string): string {\n  const pascal = toPascalCase(name)\n  return [`export default function ${pascal}Page() {`, `  return <h1>${pascal}</h1>`, `}`, ``].join(\n    '\\n',\n  )\n}\n\nfunction generateWsTemplate(_name: string): string {\n  return [\n    `import { defineWebSocket } from 'theokit/server'`,\n    ``,\n    `export default defineWebSocket({`,\n    `  onMessage(ws, data) {`,\n    `    ws.send(\\`echo: \\${data}\\`)`,\n    `  },`,\n    `})`,\n    ``,\n  ].join('\\n')\n}\n\n/**\n * Programmatic generate. Returns a structured result instead of throwing —\n * Studio (`theokit_generate` tool) consumes this directly. The CLI wrapper\n * below maps the structured result to console output + exit code semantics.\n */\n// eslint-disable-next-line @typescript-eslint/require-await\nexport async function generate(opts: GenerateOptions): Promise<GenerateResult> {\n  const { cwd, type, name } = opts\n\n  if (!existsSync(resolve(cwd, 'theo.config.ts')) && !existsSync(resolve(cwd, 'theo.config.js'))) {\n    return {\n      status: 'not_a_project',\n      message: 'Not a Theo project. cwd has no theo.config.ts or theo.config.js',\n    }\n  }\n\n  if (!VALID_TYPES.includes(type as GeneratorType)) {\n    return {\n      status: 'invalid_kind',\n      message: `Invalid generator type \"${type}\". Available: ${VALID_TYPES.join(', ')}`,\n    }\n  }\n\n  if (!name || !toKebabCase(name)) {\n    return {\n      status: 'invalid_name',\n      message: `Invalid name \"${name}\". Use kebab-case: lowercase letters, numbers, hyphens.`,\n    }\n  }\n\n  // EC-2-related: reject reserved JS identifier basenames (would shadow\n  // built-in prototype machinery in virtual module emit or scan).\n  if (hasReservedSegment(name)) {\n    return {\n      status: 'invalid_name',\n      message: `Reserved name \"${name}\" — basename collides with built-in identifier (index/constructor/__proto__/prototype/hasOwnProperty).`,\n    }\n  }\n\n  const resolved = resolveTemplate(cwd, type as GeneratorType, name)\n  if (resolved === null) {\n    return { status: 'invalid_kind', message: `Unknown type: ${type}` }\n  }\n  const { filePath, content } = resolved\n\n  // EC-4: confirm the resolved filePath stays inside cwd. `toKebabCase`\n  // already rejects most traversal vectors but a defense-in-depth check\n  // against `..` slipping in via valid-looking segments is cheap.\n  const relativeFromCwd = filePath.startsWith(resolve(cwd))\n    ? filePath.slice(resolve(cwd).length + 1)\n    : filePath\n  if (!isPathInside(cwd, relativeFromCwd)) {\n    return {\n      status: 'invalid_name',\n      message: `Path traversal denied: \"${name}\" would escape project root.`,\n    }\n  }\n\n  if (existsSync(filePath)) {\n    return { status: 'already_exists', filePath, kind: type as GeneratorType, name }\n  }\n\n  mkdirSync(dirname(filePath), { recursive: true })\n  writeFileSync(filePath, content)\n\n  // T5.2 + plan Q4: emit co-located test file alongside actions (only\n  // for action type; routes/pages/ws keep prior single-file behavior).\n  // Skip if existing test file present (preserve user-customized tests).\n  if (type === 'action') {\n    const testPath = filePath.replace(/\\.ts$/, '.test.ts')\n    if (!existsSync(testPath)) {\n      writeFileSync(testPath, generateActionTestTemplate(name))\n    }\n  }\n\n  return { status: 'created', filePath, kind: type as GeneratorType, name }\n}\n\n/**\n * CLI entry point — preserves the original surface (throws + console.log).\n * Wraps the programmatic `generate` function.\n */\nexport async function generateCommand(type: string, name: string): Promise<void> {\n  const result = await generate({ cwd: process.cwd(), type, name })\n  switch (result.status) {\n    case 'not_a_project':\n      throw new Error('Not a Theo project. Run this from a project root with theo.config.ts')\n    case 'invalid_kind':\n      throw new Error(result.message ?? 'Invalid kind')\n    case 'invalid_name':\n      throw new Error(\n        `Invalid name \"${name}\". Use kebab-case: lowercase letters, numbers, hyphens. Example: my-route`,\n      )\n    case 'already_exists':\n      console.log(`\\n  ⚠ ${result.filePath} already exists. Skipping.\\n`)\n      return\n    case 'created':\n      console.log(`\\n  ✓ Created ${type}: ${result.filePath}\\n`)\n      return\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index-DWWEdFh5.d.ts

@@ -0,0 +1,399 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { J as JobBackend } from './job-backend-CgC8Xf33.js';
+import { P as PluginRunner } from './plugin-runner-BGBkzgi0.js';
+import { S as ServerRouteNode, L as LoadModule } from './module-loader-Cfz7dgCP.js';
+import { c as CsrfMode, D as DisallowedConfig } from './csrf-BBrEZSBW.js';
+import { z } from 'zod';
+
+/**
+ * T5.2 — pluggable response/request transformer.
+ *
+ * `superjson` is the default, preserving Date/Map/Set/BigInt/etc.
+ * `json` is the lightweight option (plain JSON.stringify/parse).
+ * Users can supply a custom object implementing this contract.
+ */
+interface TheoTransformer {
+    name: string;
+    serialize: (value: unknown) => string;
+    deserialize: (raw: string) => unknown;
+}
+declare const superjsonTransformer: TheoTransformer;
+declare const jsonTransformer: TheoTransformer;
+declare function resolveTransformer(selector: 'json' | 'superjson' | TheoTransformer): TheoTransformer;
+
+/**
+ * server/http/execute-context.ts
+ *
+ * `ExecuteRouteContext` — the parameter object passed to `executeRoute()`
+ * and `executeAction()` per ADR-0016 (T3.1 of architecture-cleanup).
+ *
+ * Replaces the 12-positional-param signature with a single named-field
+ * object, eliminating 3 of 4 eslint-disable comments on `executeRoute`.
+ *
+ * Location: lives in `server/http/` (not `core/contracts/`) because the
+ * shape references server-side types (CsrfMode, JobBackend, PluginRunner,
+ * TheoTransformer, ServerRouteNode, LoadModule, DisallowedConfig). Keeping
+ * the type here preserves the existing module direction graph — no new
+ * `core → server` edges.
+ *
+ * Consumers within server/ build this object once per request; external
+ * callers (router-runner) see the same shape via the `ExecuteRouteContext`
+ * named export.
+ */
+
+/**
+ * The request-execution context. Each request builds one of these and passes
+ * it to `executeRoute(ctx)`.
+ *
+ * All fields are required EXCEPT those with optional `?` markers; defaults
+ * are applied inside `executeRoute` via destructure (e.g., `csrfMode = 'strict'`).
+ */
+interface ExecuteRouteContext {
+    route: ServerRouteNode;
+    method: string;
+    params: Record<string, string>;
+    req: IncomingMessage;
+    res: ServerResponse;
+    loadModule: LoadModule;
+    serverDir?: string;
+    requestId?: string;
+    pluginRunner?: PluginRunner;
+    transformer?: TheoTransformer;
+    /** Defaults to `'strict'` when omitted. */
+    csrfMode?: CsrfMode;
+    disallowed?: DisallowedConfig;
+    /** When provided, `ctx.queue` auto-injects + outbox lifecycle hooks attach. */
+    jobBackend?: JobBackend;
+}
+
+/**
+ * Canonical HTTP response helpers (T5.1 extraction).
+ *
+ * Moved out of execute.ts so request-pipeline stages (execute-stages.ts,
+ * handle-request-error.ts, etc.) can depend on these helpers without
+ * creating a cycle through execute.ts.
+ *
+ * Public surface re-exported from execute.ts for backward compat — every
+ * existing caller of `sendError` / `sendJson` continues to work via the
+ * `theokit/server` barrel.
+ */
+declare function sendJson(res: ServerResponse, data: unknown, status?: number, transformer?: TheoTransformer): void;
+interface SendErrorOptions {
+    custom404Html?: string;
+    custom500Html?: string;
+}
+/**
+ * Canonical error response.
+ *
+ * T6.3 (PV-17): the positional 7-param signature is preserved for backward
+ * compat. New call sites should use the options-bag form:
+ *
+ *   sendError(res, { code, message, status, issues?, requestId?, options? })
+ *
+ * Both shapes resolve to the same implementation.
+ */
+interface SendErrorInput {
+    code: string;
+    message: string;
+    status: number;
+    issues?: unknown[];
+    requestId?: string;
+    options?: SendErrorOptions;
+}
+declare function sendError(res: ServerResponse, input: SendErrorInput): void;
+declare function sendError(res: ServerResponse, code: string, message: string, status: number, issues?: unknown[], requestId?: string, options?: SendErrorOptions): void;
+
+declare function executeRoute(ctx: ExecuteRouteContext): Promise<void>;
+
+interface ExecuteActionOptions {
+    filePath: string;
+    exportName: string;
+    req: IncomingMessage;
+    res: ServerResponse;
+    loadModule: LoadModule;
+    serverDir?: string;
+    requestId?: string;
+    pluginRunner?: PluginRunner;
+    csrfMode?: CsrfMode;
+    disallowed?: DisallowedConfig;
+}
+declare function executeAction(filePath: string, exportName: string, req: IncomingMessage, res: ServerResponse, loadModule: LoadModule, serverDir?: string, requestId?: string, pluginRunner?: PluginRunner, csrfMode?: CsrfMode, disallowed?: DisallowedConfig): Promise<void>;
+
+interface MiddlewareResult {
+    ctx: unknown;
+    aborted: boolean;
+}
+declare function _resetMiddlewareCacheForTests(): void;
+declare function runMiddlewareAndContext(req: IncomingMessage, res: ServerResponse, loadModule: LoadModule, serverDir: string): Promise<MiddlewareResult>;
+
+/**
+ * T1.2 — CORS middleware.
+ *
+ * Single global middleware that runs FIRST in the request pipeline:
+ *   CORS preflight → rate limit → CSRF → security headers → handler
+ *
+ * Preflight (`OPTIONS` with `Access-Control-Request-Method`) is handled
+ * by `handlePreflight`, which short-circuits the response with 204 +
+ * Access-Control-* headers.
+ *
+ * Non-preflight requests pass through; `applyHeaders` adds
+ * `Access-Control-Allow-Origin` (echoing the request's Origin),
+ * `Access-Control-Expose-Headers`, and `Access-Control-Allow-Credentials`.
+ *
+ * Per ADR D3: preflight responses are deterministic and only the matched
+ * origin is echoed back (never `'*'` when credentials are enabled —
+ * required by the CORS spec).
+ */
+type CorsOrigin = string | RegExp | readonly (string | RegExp)[] | ((origin: string) => boolean);
+interface CorsConfig {
+    origins: CorsOrigin;
+    methods?: readonly ('GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD')[];
+    allowedHeaders?: readonly string[];
+    exposedHeaders?: readonly string[];
+    credentials?: boolean;
+    maxAge?: number;
+}
+interface CorsHandler {
+    handlePreflight(req: IncomingMessage, res: ServerResponse): boolean;
+    applyHeaders(req: IncomingMessage, res: ServerResponse): void;
+}
+/**
+ * Test whether `origin` is allowed by `allowed`. Pure function — no I/O.
+ *
+ * EC-8: callback variants that throw are fail-closed (deny). Without
+ * this, a transient datastore outage would silently widen CORS during
+ * the failure window.
+ */
+declare function matchesOrigin(origin: string, allowed: CorsOrigin): boolean;
+declare function createCorsHandler(config: CorsConfig): CorsHandler;
+/**
+ * T5a.2 Phase B slice 5/6 — Web-Standards CORS handler.
+ *
+ * Mirror of `createCorsHandler(config): CorsHandler` for the Web `Request`
+ * shape. Same `CorsConfig`, same `matchesOrigin` logic (pure helper
+ * already), same security guarantees (echo matched origin only — never
+ * `'*'` when credentials enabled; EC-8 fail-closed on callback throw).
+ *
+ * Signature differences vs the IncomingMessage pair:
+ *   - `handlePreflightRequest(request, config): Response | null` — returns
+ *     `Response` when this is a CORS preflight; `null` when not. Caller
+ *     short-circuits accordingly (same control-flow semantic as boolean).
+ *   - `applyCorsHeaders(request, target, config): void` — mutates a
+ *     `Headers` instance in place. Caller passes the headers they're
+ *     building for their Response.
+ */
+interface CorsWebHandler {
+    handlePreflightRequest(request: Request): Response | null;
+    applyCorsHeaders(request: Request, target: Headers): void;
+}
+declare function createCorsWebHandler(config: CorsConfig): CorsWebHandler;
+
+interface CookieOptions {
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+}
+/**
+ * Parse a `Cookie` header into a Map (RFC 6265 §5.4).
+ * - Empty/missing input → empty Map.
+ * - Malformed entries (no `=`) skipped silently (defensive).
+ * - Duplicate names → last-wins.
+ * - Values URL-decoded if possible; raw on decode failure (CR-009 protection).
+ *
+ * Canonical helper (T3.2 of architecture-review-remediation-plan; PV-4 DRY).
+ * Consumed by `getCookie` here AND by `rate-limit/rate-limit-per-route.ts`.
+ */
+declare function parseCookieHeader(header: string | undefined): Map<string, string>;
+declare function getCookie(req: IncomingMessage, name: string): string | undefined;
+/**
+ * T5a.2 Phase B slice 6/6 — pure Set-Cookie serializer. Extracted from
+ * `setCookie(res, ...)` so the IncomingMessage path AND the Web Headers
+ * path can share the cookie attribute composition.
+ *
+ * Returns the canonical `Set-Cookie` header value string (no surrounding
+ * `Set-Cookie:` prefix — caller wraps via `res.setHeader('Set-Cookie', ...)`
+ * or `headers.append('Set-Cookie', ...)`).
+ *
+ * Defaults: `httpOnly: true`, `secure: NODE_ENV === 'production'`,
+ * `sameSite: 'lax'`, `path: '/'`.
+ */
+declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+declare function setCookie(res: ServerResponse, name: string, value: string, options?: CookieOptions): void;
+declare function deleteCookie(res: ServerResponse, name: string, options?: {
+    path?: string;
+}): void;
+/**
+ * T5a.2 Phase B slice 6/6 — Web-Standards cookie getter.
+ *
+ * Mirror of `getCookie(req: IncomingMessage, name)` for the Web `Request`
+ * shape. Consumes `request.headers.get('cookie')` (native `Headers` API)
+ * instead of `req.headers.cookie`. Same parse logic + same malformed
+ * percent-encoding sanity (returns undefined when raw value contains a
+ * lone `%` that didn't decode, preserving the IncomingMessage path's
+ * "treat as unreadable" CR-009 semantics).
+ */
+declare function getCookieFromRequest(request: Request, name: string): string | undefined;
+/**
+ * T5a.2 Phase B slice 6/6 — Web-Standards cookie setter.
+ *
+ * Mirror of `setCookie(res, name, value, options)` for the Web `Headers`
+ * shape. Appends a `Set-Cookie` entry to the caller's `Headers` instance
+ * via `headers.append('Set-Cookie', ...)`. Multiple appends produce
+ * multiple `Set-Cookie` headers per the Web spec; `headers.getSetCookie()`
+ * retrieves them as an array (the one multi-value header the Web API
+ * exposes natively).
+ *
+ * Uses the shared `serializeCookie` pure helper — same defaults and
+ * attribute composition as the IncomingMessage path.
+ */
+declare function appendCookieToHeaders(target: Headers, name: string, value: string, options?: CookieOptions): void;
+/**
+ * T5a.2 Phase B slice 6/6 — Web-Standards cookie deleter.
+ *
+ * Mirror of `deleteCookie(res, name, options)` — emits a Set-Cookie with
+ * `Max-Age=0` so the browser drops the cookie immediately.
+ */
+declare function appendDeleteCookieToHeaders(target: Headers, name: string, options?: {
+    path?: string;
+}): void;
+
+/**
+ * T1.4 — Server-side batch handler.
+ *
+ * Receives `{ requests: [...] }` POSTed to `/api/__theo_batch__` and returns
+ * `{ results: [...] }` with per-item error isolation. EC-2: items cannot
+ * override auth/forwarded headers (would be a session-bypass vector).
+ */
+
+declare const STRIPPED_HEADERS: readonly ["authorization", "cookie", "x-forwarded-for", "x-forwarded-host", "x-forwarded-proto", "x-real-ip", "host"];
+declare const BATCH_PATH = "/api/__theo_batch__";
+declare class BatchPathConflictError extends Error {
+    constructor(path: string);
+}
+declare const batchRequestSchema: z.ZodObject<{
+    path: z.ZodString;
+    method: z.ZodString;
+    query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    body: z.ZodOptional<z.ZodUnknown>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+declare const batchPayloadSchema: z.ZodObject<{
+    requests: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        method: z.ZodString;
+        query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        body: z.ZodOptional<z.ZodUnknown>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type BatchRequestItem = z.infer<typeof batchRequestSchema>;
+type BatchPayload = z.infer<typeof batchPayloadSchema>;
+type BatchExecuteFn = (req: BatchRequestItem) => Promise<{
+    data: unknown;
+} | {
+    error: {
+        message: string;
+        code?: string;
+    };
+}>;
+interface HandleBatchOptions {
+    execute: BatchExecuteFn;
+    /** Max number of items per batch. Default 32. */
+    max?: number;
+    /** Outer-request headers that override per-item headers in STRIPPED_HEADERS. */
+    outerHeaders?: Record<string, string>;
+}
+type BatchResultItem = {
+    data: unknown;
+} | {
+    error: {
+        message: string;
+        code?: string;
+    };
+};
+interface BatchResponse {
+    results: BatchResultItem[];
+}
+/**
+ * Validate + execute a batch request.
+ *
+ * CR-028 fix: previously the signature was `payload: BatchPayload`,
+ * suggesting the caller had already validated. In reality `api-middleware`
+ * passes `JSON.parse(rawBody) as BatchPayload` — an unsafe cast over raw
+ * HTTP input. We widen the input type to `unknown` so the type system
+ * forces validation, then run Zod once at this single trust boundary.
+ */
+declare function handleBatchRequest(payload: unknown, options: HandleBatchOptions): Promise<BatchResponse>;
+
+/**
+ * T2.4 — Custom error pages loader.
+ *
+ * Loads optional `.theo/client/404.html` and `500.html` from disk so adapters
+ * (Node, CF, Vercel, Bun, Netlify, AWS Lambda, Deno) can pass them to the
+ * shared `sendError` pipeline.
+ *
+ * EC-9: caps file size at 1MB. Files beyond the limit are skipped with a
+ * console.warn and the default JSON error path is used.
+ */
+declare const MAX_ERROR_HTML_BYTES = 1048576;
+interface CustomErrorPages {
+    custom404Html?: string;
+    custom500Html?: string;
+}
+/**
+ * Load `.theo/client/{404,500}.html` from the given client directory.
+ * Returns object with both fields when present; missing pages remain undefined.
+ */
+declare function loadCustomErrorPages(clientDir: string): CustomErrorPages;
+
+declare function serveStaticFile(req: IncomingMessage, res: ServerResponse, clientDir: string): boolean;
+
+/**
+ * Phase 7 — Observability: traceId propagation (D7).
+ *
+ * Extract a stable identifier from incoming requests so a single value
+ * correlates the client request, every server log line, the response
+ * envelope, and any downstream span. Precedence:
+ *
+ *   1. `traceparent` (W3C Trace Context — `00-{32-hex}-{16-hex}-{flags}`)
+ *   2. `x-request-id` (Heroku / GCP / generic proxy header)
+ *   3. Generated UUID (fresh per request)
+ *
+ * UUIDs are accepted as trace identifiers by every major vendor that
+ * does not enforce strict 32-hex (Datadog, Honeycomb, Sentry, Logflare,
+ * Axiom, etc). We don't need ULIDs to ship this surface.
+ */
+declare const TRACE_HEADER = "x-trace-id";
+declare const TRACE_PARENT_HEADER = "traceparent";
+/**
+ * Parse a W3C Trace Context `traceparent` header value. Returns the
+ * 32-hex trace-id when valid (and not the reserved all-zeros), else
+ * `null`.
+ */
+declare function parseTraceparent(value: string): string | null;
+/**
+ * Resolve the request's traceId following the precedence above.
+ */
+declare function extractTraceId(req: IncomingMessage): string;
+/**
+ * T5a.2 Phase C slice 1/2 — Web-Standards-shaped traceId resolver.
+ *
+ * Mirror of `extractTraceId(req: IncomingMessage)` for the Web `Request`
+ * shape. Same precedence (`traceparent` → `x-request-id` → generated
+ * UUID). Uses `request.headers.get(name)` (native Web `Headers` API)
+ * instead of the Node indexer.
+ *
+ * **Multi-value note:** Web `Headers` collapses repeated headers into a
+ * single comma-separated string at parse. The IncomingMessage path's
+ * `pickHeader` "first non-empty value" semantic is naturally satisfied
+ * because there's no array to pick from on the Web side — `.get()`
+ * returns the comma-joined value, which for `traceparent` / `x-request-id`
+ * is treated as a single string anyway (both headers are conventionally
+ * single-valued).
+ */
+declare function extractTraceIdFromRequest(request: Request): string;
+
+export { getCookie as A, BATCH_PATH as B, type CookieOptions as C, getCookieFromRequest as D, type ExecuteActionOptions as E, handleBatchRequest as F, jsonTransformer as G, type HandleBatchOptions as H, loadCustomErrorPages as I, matchesOrigin as J, parseCookieHeader as K, parseTraceparent as L, MAX_ERROR_HTML_BYTES as M, resolveTransformer as N, runMiddlewareAndContext as O, sendError as P, sendJson as Q, serializeCookie as R, STRIPPED_HEADERS as S, TRACE_HEADER as T, serveStaticFile as U, setCookie as V, superjsonTransformer as W, _resetMiddlewareCacheForTests as _, type BatchExecuteFn as a, BatchPathConflictError as b, type BatchPayload as c, type BatchRequestItem as d, type BatchResponse as e, type BatchResultItem as f, type CorsConfig as g, type CorsHandler as h, type CorsOrigin as i, type CorsWebHandler as j, type CustomErrorPages as k, type ExecuteRouteContext as l, type MiddlewareResult as m, type SendErrorInput as n, type SendErrorOptions as o, TRACE_PARENT_HEADER as p, type TheoTransformer as q, appendCookieToHeaders as r, appendDeleteCookieToHeaders as s, createCorsHandler as t, createCorsWebHandler as u, deleteCookie as v, executeAction as w, executeRoute as x, extractTraceId as y, extractTraceIdFromRequest as z };