theokit 0.19.4 → 0.21.0

package/dist/generate-373DALPY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/commands/generate.ts","../src/cli/commands/generate-resource.ts","../src/cli/commands/generate-types.ts"],"sourcesContent":["import { existsSync, mkdirSync, writeFileSync } from 'node:fs'\nimport { resolve, dirname } from 'node:path'\n\nimport { generateResource } from './generate-resource.js'\nimport {\n  VALID_TYPES,\n  type GeneratorType,\n  type GenerateOptions,\n  type GenerateStatus,\n  type GenerateResult,\n} from './generate-types.js'\n\nexport {\n  VALID_TYPES,\n  type GeneratorType,\n  type GenerateOptions,\n  type GenerateStatus,\n  type GenerateResult,\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 { route } from 'theokit/server'`,\n    `import { z } from 'zod'`,\n    ``,\n    `export const GET = route()`,\n    `  .handler(({ ctx }) => {`,\n    `    return { message: 'TODO: implement ${name} GET' }`,\n    `  })`,\n    `  .build()`,\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 { action } from 'theokit/server'`,\n    `import { z } from 'zod'`,\n    ``,\n    `export const ${camel} = action()`,\n    `  .input(z.object({}))`,\n    `  .handler(({ input, ctx }) => {`,\n    `    return { message: 'TODO: implement ${name}' }`,\n    `  })`,\n    `  .build()`,\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  return [\n    `import { agent } from '@theokit/agents'`,\n    `import { z } from 'zod'`,\n    ``,\n    `// Zero-config: this file is auto-served at POST /api/agents/${name}.`,\n    `// Add tools with tool('name')...build() and chain them via .tool(...).`,\n    `export default agent()`,\n    `  .input(z.object({ message: z.string() }))`,\n    `  .model('openai/gpt-4o-mini')`,\n    `  .system('You are a helpful ${name} assistant.')`,\n    `  .build()`,\n    ``,\n  ].join('\\n')\n}\n\nfunction generateToolboxTemplate(name: string): string {\n  const camel = toCamelCase(name)\n  return [\n    `import { tool } from 'theokit/server'`,\n    `import { z } from 'zod'`,\n    ``,\n    `export const ${camel}Hello = tool('${name}_hello')`,\n    `  .describe('Say hello')`,\n    `  .input(z.object({ name: z.string() }))`,\n    `  .execute(({ name }) => \\`Hello, \\${name}!\\`)`,\n    `  .build()`,\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  // Resource generates multiple files — handle separately\n  if (type === 'resource') {\n    return generateResource(cwd, name, opts.fields ?? [])\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(\n  type: string,\n  name: string,\n  fields?: string[],\n): Promise<void> {\n  const result = await generate({ cwd: process.cwd(), type, name, fields })\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","import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'\nimport { resolve, dirname } from 'node:path'\n\nimport type { GenerateResult } from './generate-types.js'\n\n// --- Field parsing ---\n\nconst ALLOWED_FIELD_TYPES = new Set(['string', 'text', 'number', 'boolean'])\nconst RESERVED_FIELDS = new Set(['id', 'createdAt', 'created_at'])\n\nexport interface ResourceField {\n  name: string\n  type: 'string' | 'text' | 'number' | 'boolean'\n  drizzleColumn: string\n  zodType: string\n}\n\nexport function parseResourceFields(args: string[]): ResourceField[] {\n  if (args.length === 0) {\n    throw new Error(\n      'Resource requires at least one field. Example: theokit generate resource posts title:string',\n    )\n  }\n  return args.map((arg) => {\n    const parts = arg.split(':')\n    if (parts.length !== 2 || !parts[0] || !parts[1]) {\n      throw new Error(`Invalid field \"${arg}\". Use name:type format (e.g. title:string)`)\n    }\n    const [name, type] = parts\n    if (!ALLOWED_FIELD_TYPES.has(type)) {\n      throw new Error(\n        `Unknown field type \"${type}\" in \"${arg}\". Valid types: ${[...ALLOWED_FIELD_TYPES].join(', ')}`,\n      )\n    }\n    if (RESERVED_FIELDS.has(name)) {\n      throw new Error(`Field \"${name}\" is reserved (auto-generated by the framework)`)\n    }\n    const fieldType = type as ResourceField['type']\n    return {\n      name,\n      type: fieldType,\n      drizzleColumn: mapDrizzleColumn(name, fieldType),\n      zodType: mapZodType(fieldType),\n    }\n  })\n}\n\n// --- Column / type mapping ---\n\nfunction mapDrizzleColumn(name: string, type: ResourceField['type']): string {\n  switch (type) {\n    case 'string':\n    case 'text':\n      return `text('${name}').notNull()`\n    case 'number':\n      return `integer('${name}').notNull()`\n    case 'boolean':\n      return `integer('${name}', { mode: 'boolean' }).notNull().default(false)`\n  }\n}\n\nfunction mapZodType(type: ResourceField['type']): string {\n  switch (type) {\n    case 'string':\n    case 'text':\n      return 'z.string()'\n    case 'number':\n      return 'z.number()'\n    case 'boolean':\n      return 'z.boolean()'\n  }\n}\n\n// --- Template generators ---\n\nfunction generateSchemaEntry(resourceName: string, fields: ResourceField[]): string {\n  const cols = [\n    `  id: integer('id').primaryKey({ autoIncrement: true }),`,\n    ...fields.map((f) => `  ${f.name}: ${f.drizzleColumn},`),\n    `  createdAt: text('created_at')`,\n    `    .notNull()`,\n    `    .$defaultFn(() => new Date().toISOString().split('T')[0]),`,\n  ]\n  return [\n    ``,\n    `export const ${resourceName} = sqliteTable('${resourceName}', {`,\n    ...cols,\n    `})`,\n    ``,\n  ].join('\\n')\n}\n\nfunction generateRouteIndex(resourceName: string, fields: ResourceField[]): string {\n  const bodyFields = fields.map((f) => `    ${f.name}: ${f.zodType},`).join('\\n')\n  return [\n    `import { route } from 'theokit/server/define'`,\n    `import { z } from 'zod'`,\n    `import { db } from '../../db/index.js'`,\n    `import { ${resourceName} } from '../../db/schema.js'`,\n    ``,\n    `export const GET = route()`,\n    `  .handler(() => db.select().from(${resourceName}).all())`,\n    `  .build()`,\n    ``,\n    `export const POST = route()`,\n    `  .body(`,\n    `    z.object({`,\n    bodyFields,\n    `    }),`,\n    `  )`,\n    `  .status(201)`,\n    `  .handler(({ body }) => {`,\n    `    const result = db.insert(${resourceName}).values(body).returning().get()`,\n    `    return result`,\n    `  })`,\n    `  .build()`,\n    ``,\n  ].join('\\n')\n}\n\nfunction generateRouteId(resourceName: string, fields: ResourceField[]): string {\n  const updateFields = fields.map((f) => `    ${f.name}: ${f.zodType}.optional(),`).join('\\n')\n  return [\n    `import { route } from 'theokit/server/define'`,\n    `import { z } from 'zod'`,\n    `import { db } from '../../db/index.js'`,\n    `import { ${resourceName} } from '../../db/schema.js'`,\n    `import { eq } from 'drizzle-orm'`,\n    ``,\n    `export const GET = route()`,\n    `  .params(z.object({ id: z.coerce.number() }))`,\n    `  .handler(({ params }) => {`,\n    `    const item = db.select().from(${resourceName}).where(eq(${resourceName}.id, params.id)).get()`,\n    `    if (!item) return new Response(JSON.stringify({ error: 'Not found' }), { status: 404 })`,\n    `    return item`,\n    `  })`,\n    `  .build()`,\n    ``,\n    `export const PUT = route()`,\n    `  .params(z.object({ id: z.coerce.number() }))`,\n    `  .body(`,\n    `    z.object({`,\n    updateFields,\n    `    }),`,\n    `  )`,\n    `  .handler(({ params, body }) => {`,\n    `    const result = db.update(${resourceName}).set(body).where(eq(${resourceName}.id, params.id)).returning().get()`,\n    `    if (!result) return new Response(JSON.stringify({ error: 'Not found' }), { status: 404 })`,\n    `    return result`,\n    `  })`,\n    `  .build()`,\n    ``,\n    `export const DELETE = route()`,\n    `  .params(z.object({ id: z.coerce.number() }))`,\n    `  .status(204)`,\n    `  .handler(({ params }) => {`,\n    `    db.delete(${resourceName}).where(eq(${resourceName}.id, params.id)).run()`,\n    `  })`,\n    `  .build()`,\n    ``,\n  ].join('\\n')\n}\n\nfunction generateTestTemplate(resourceName: string): string {\n  return [\n    `import { describe, it, expect } from 'vitest'`,\n    ``,\n    `describe('${resourceName} API', () => {`,\n    `  it('should have a schema defined', async () => {`,\n    `    const schema = await import('../server/db/schema.js')`,\n    `    expect(schema.${resourceName}).toBeDefined()`,\n    `  })`,\n    ``,\n    `  it('should have route handlers', async () => {`,\n    `    const index = await import('../server/routes/${resourceName}/index.js')`,\n    `    expect(index.GET).toBeDefined()`,\n    `    expect(index.POST).toBeDefined()`,\n    `  })`,\n    `})`,\n    ``,\n  ].join('\\n')\n}\n\n// --- Orchestrator ---\n\nexport function generateResource(cwd: string, name: string, fieldArgs: string[]): GenerateResult {\n  let fields: ResourceField[]\n  try {\n    fields = parseResourceFields(fieldArgs)\n  } catch (err) {\n    return { status: 'invalid_name', message: err instanceof Error ? err.message : String(err) }\n  }\n\n  const schemaPath = resolve(cwd, 'server/db/schema.ts')\n  const routeIndexPath = resolve(cwd, `server/routes/${name}/index.ts`)\n  const routeIdPath = resolve(cwd, `server/routes/${name}/[id].ts`)\n  const testPath = resolve(cwd, `tests/${name}.test.ts`)\n\n  if (!existsSync(schemaPath)) {\n    return {\n      status: 'not_a_project',\n      message:\n        'server/db/schema.ts not found. Run this from a TheoKit project with database setup.',\n    }\n  }\n\n  if (existsSync(routeIndexPath)) {\n    return { status: 'already_exists', filePath: routeIndexPath, kind: 'resource', name }\n  }\n\n  const existingSchema = readFileSync(schemaPath, 'utf-8')\n  if (existingSchema.includes(`export const ${name} =`)) {\n    return {\n      status: 'already_exists',\n      filePath: schemaPath,\n      kind: 'resource',\n      name,\n      message: `Table \"${name}\" already exists in schema.ts`,\n    }\n  }\n\n  // 1. Append schema entry\n  appendFileSync(schemaPath, generateSchemaEntry(name, fields))\n\n  // 2. Create route files\n  mkdirSync(dirname(routeIndexPath), { recursive: true })\n  writeFileSync(routeIndexPath, generateRouteIndex(name, fields))\n  writeFileSync(routeIdPath, generateRouteId(name, fields))\n\n  // 3. Create test file\n  mkdirSync(dirname(testPath), { recursive: true })\n  if (!existsSync(testPath)) {\n    writeFileSync(testPath, generateTestTemplate(name))\n  }\n\n  return { status: 'created', filePath: routeIndexPath, kind: 'resource', name }\n}\n","/**\n * Shared types for the `theokit generate` CLI command family.\n *\n * Extracted to break the circular dependency between generate.ts ↔ generate-resource.ts\n * (architecture-remediation plan T1.1, 2026-06-12).\n */\n\nexport const VALID_TYPES = [\n  'route',\n  'action',\n  'page',\n  'ws',\n  'controller',\n  'agent',\n  'toolbox',\n  'resource',\n] as const\nexport type GeneratorType = (typeof VALID_TYPES)[number]\n\nexport interface GenerateOptions {\n  cwd: string\n  type: string\n  name: string\n  fields?: 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"],"mappings":"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","names":["existsSync","mkdirSync","writeFileSync","resolve","dirname","resolve","existsSync","mkdirSync","dirname","writeFileSync"]}

package/dist/{index-B40qUSrQ.d.ts → index-C3ged4mn.d.ts}

@@ -1,7 +1,7 @@
 import { a as TheoErrorCode, T as TheoErrorEnvelope } from './error-envelope-BsNzzAV5.js';
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { P as PluginContext } from './plugin-types-DNJGxr4Z.js';
-import { P as PluginRunner } from './plugin-runner-BGBkzgi0.js';
+import { P as PluginContext } from './plugin-types-L49QYMb5.js';
+import { P as PluginRunner } from './plugin-runner-CMprWWHZ.js';
 import { J as JobBackend } from './job-backend-CgC8Xf33.js';
 import { L as LoadModule, S as ServerRouteNode } from './match-CfbEFRG4.js';
 import { c as CsrfMode, D as DisallowedConfig } from './csrf-BBrEZSBW.js';

package/dist/index.d.ts

@@ -280,12 +280,33 @@ declare const theoConfigSchema: z.ZodObject<{
 }, z.core.$strip>;
 type TheoConfig = z.infer<typeof theoConfigSchema>;
 
+/** The fluent config builder. No field is required; `.set()` merges arbitrary config fields. */
+interface ConfigBuilder {
+    /** Project identifier (DNS-1123) — used by `.theokit/services.json`. */
+    name(value: TheoConfig['name']): ConfigBuilder;
+    /** Backend root dir (route/action/agent discovery). Default `'server'`. */
+    serverDir(value: TheoConfig['serverDir']): ConfigBuilder;
+    /** Frontend root dir (file-based router). Default `'app'`. */
+    appDir(value: TheoConfig['appDir']): ConfigBuilder;
+    /** Agents root dir. Default `'agents'`. */
+    agentsDir(value: TheoConfig['agentsDir']): ConfigBuilder;
+    /** Build output dir. Default `'.theokit'`. */
+    distDir(value: TheoConfig['distDir']): ConfigBuilder;
+    /** Dev/prod port. Default `3000`. */
+    port(value: TheoConfig['port']): ConfigBuilder;
+    /** Bind host. Default `'localhost'`. */
+    host(value: TheoConfig['host']): ConfigBuilder;
+    /** Enable server-side rendering. Default `false`. */
+    ssr(value: TheoConfig['ssr']): ConfigBuilder;
+    /** Escape hatch — merge any config fields not covered by a dedicated setter (rate-limit, security…). */
+    set(partial: Partial<TheoConfig>): ConfigBuilder;
+    /** Resolve to the `Partial<TheoConfig>` — the SAME value `defineConfig({...})` returns. */
+    build(): Partial<TheoConfig>;
+}
 /**
- * Define Theo framework configuration.
- * Identity function — provides type inference for theo.config.ts.
- * Runtime validation happens in loadConfig(), not here.
+ * Start a fluent config definition. Chain the common setters and/or `.set(partial)`, then `.build()`.
  */
-declare function defineConfig(config: Partial<TheoConfig>): Partial<TheoConfig>;
+declare function config(): ConfigBuilder;
 
 /**
  * Deep merges two plain objects. Override values take precedence.
@@ -359,4 +380,4 @@ interface EntryClientOptions {
 }
 declare function generateEntryClient(ssr?: boolean, opts?: EntryClientOptions): string;
 
-export { type ConfigIssue, type RouteNode, type TheoConfig, TheoConfigError, TheoProjectError, deepMerge, defineConfig, generateEntryClient, generateRouteManifest, isRouteFile, loadConfig, scanRoutes, theoConfigSchema, validateProjectStructure };
+export { type ConfigBuilder, type ConfigIssue, type RouteNode, type TheoConfig, TheoConfigError, TheoProjectError, config, deepMerge, generateEntryClient, generateRouteManifest, isRouteFile, loadConfig, scanRoutes, theoConfigSchema, validateProjectStructure };

package/dist/index.js

@@ -35,8 +35,28 @@ import "./chunk-UVXB2ER7.js";
 import "./chunk-DGUM43GV.js";
 
 // src/config/define-config.ts
-function defineConfig(config) {
-  return config;
+function defineConfig(config2) {
+  return config2;
+}
+
+// src/config/config-builder.ts
+function makeConfigBuilder(spec) {
+  const merge = (patch) => makeConfigBuilder({ ...spec, ...patch });
+  return {
+    name: (value) => merge({ name: value }),
+    serverDir: (value) => merge({ serverDir: value }),
+    appDir: (value) => merge({ appDir: value }),
+    agentsDir: (value) => merge({ agentsDir: value }),
+    distDir: (value) => merge({ distDir: value }),
+    port: (value) => merge({ port: value }),
+    host: (value) => merge({ host: value }),
+    ssr: (value) => merge({ ssr: value }),
+    set: (partial) => merge(partial),
+    build: () => defineConfig(spec)
+  };
+}
+function config() {
+  return makeConfigBuilder({});
 }
 
 // src/config/validate-structure.ts
@@ -100,8 +120,8 @@ function validateProjectStructure(rootDir, appDir = "app") {
 export {
   TheoConfigError,
   TheoProjectError,
+  config,
   deepMerge,
-  defineConfig,
   generateEntryClient,
   generateRouteManifest,
   isRouteFile,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/config/define-config.ts","../src/config/validate-structure.ts","../src/core/errors.ts"],"sourcesContent":["import type { TheoConfig } from './schema.js'\n\n/**\n * Define Theo framework configuration.\n * Identity function — provides type inference for theo.config.ts.\n * Runtime validation happens in loadConfig(), not here.\n */\nexport function defineConfig(config: Partial<TheoConfig>): Partial<TheoConfig> {\n  return config\n}\n","/* eslint-disable security/detect-non-literal-fs-filename --\n * Project-structure validator. Reads paths joined onto `projectRoot`,\n * with names from a fixed `ValidationRule[]` table. No HTTP input.\n */\nimport { existsSync } from 'node:fs'\nimport { join } from 'node:path'\n\nimport { TheoProjectError } from '../core/errors.js'\n\ninterface ValidationRule {\n  path: string\n  errorMessage: string\n}\n\nconst REQUIRED_FILES: ValidationRule[] = [\n  {\n    path: 'theo.config.ts',\n    errorMessage: 'Missing required file: theo.config.ts',\n  },\n  {\n    path: 'package.json',\n    errorMessage: 'Missing required file: package.json',\n  },\n]\n\n// #95 — honor config `appDir` (default \"app\") so a project that groups its frontend under a custom\n// directory (e.g. `apps/web`) is not rejected by a hardcoded `app/` requirement.\nexport function validateProjectStructure(rootDir: string, appDir = 'app'): void {\n  if (!existsSync(rootDir)) {\n    throw new TheoProjectError([`Project directory does not exist: ${rootDir}`], rootDir)\n  }\n\n  const errors: string[] = []\n\n  const requiredDirs: ValidationRule[] = [\n    { path: appDir, errorMessage: `Missing required directory: ${appDir}/` },\n  ]\n\n  for (const rule of requiredDirs) {\n    if (!existsSync(join(rootDir, rule.path))) {\n      errors.push(rule.errorMessage)\n    }\n  }\n\n  for (const rule of REQUIRED_FILES) {\n    if (!existsSync(join(rootDir, rule.path))) {\n      errors.push(rule.errorMessage)\n    }\n  }\n\n  if (errors.length > 0) {\n    throw new TheoProjectError(errors, rootDir)\n  }\n}\n","export class TheoProjectError extends Error {\n  public readonly errors: string[]\n  public readonly rootDir: string\n\n  constructor(errors: string[], rootDir: string) {\n    const errorLines = errors.map((e) => `  - ${e}`).join('\\n')\n\n    super(\n      `Invalid Theo project structure\\n\\n` +\n        `  Root: ${rootDir}\\n\\n` +\n        (errorLines ? `  Errors:\\n${errorLines}\\n` : ''),\n    )\n\n    this.name = 'TheoProjectError'\n    this.errors = errors\n    this.rootDir = rootDir\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOO,SAAS,aAAa,QAAkD;AAC7E,SAAO;AACT;;;ACLA,SAAS,kBAAkB;AAC3B,SAAS,YAAY;;;ACLd,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC1B;AAAA,EACA;AAAA,EAEhB,YAAY,QAAkB,SAAiB;AAC7C,UAAM,aAAa,OAAO,IAAI,CAAC,MAAM,OAAO,CAAC,EAAE,EAAE,KAAK,IAAI;AAE1D;AAAA,MACE;AAAA;AAAA,UACa,OAAO;AAAA;AAAA,KACjB,aAAa;AAAA,EAAc,UAAU;AAAA,IAAO;AAAA,IACjD;AAEA,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,UAAU;AAAA,EACjB;AACF;;;ADHA,IAAM,iBAAmC;AAAA,EACvC;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AACF;AAIO,SAAS,yBAAyB,SAAiB,SAAS,OAAa;AAC9E,MAAI,CAAC,WAAW,OAAO,GAAG;AACxB,UAAM,IAAI,iBAAiB,CAAC,qCAAqC,OAAO,EAAE,GAAG,OAAO;AAAA,EACtF;AAEA,QAAM,SAAmB,CAAC;AAE1B,QAAM,eAAiC;AAAA,IACrC,EAAE,MAAM,QAAQ,cAAc,+BAA+B,MAAM,IAAI;AAAA,EACzE;AAEA,aAAW,QAAQ,cAAc;AAC/B,QAAI,CAAC,WAAW,KAAK,SAAS,KAAK,IAAI,CAAC,GAAG;AACzC,aAAO,KAAK,KAAK,YAAY;AAAA,IAC/B;AAAA,EACF;AAEA,aAAW,QAAQ,gBAAgB;AACjC,QAAI,CAAC,WAAW,KAAK,SAAS,KAAK,IAAI,CAAC,GAAG;AACzC,aAAO,KAAK,KAAK,YAAY;AAAA,IAC/B;AAAA,EACF;AAEA,MAAI,OAAO,SAAS,GAAG;AACrB,UAAM,IAAI,iBAAiB,QAAQ,OAAO;AAAA,EAC5C;AACF;","names":[]}
+{"version":3,"sources":["../src/config/define-config.ts","../src/config/config-builder.ts","../src/config/validate-structure.ts","../src/core/errors.ts"],"sourcesContent":["import type { TheoConfig } from './schema.js'\n\n/**\n * Define Theo framework configuration.\n * Identity function — provides type inference for theo.config.ts.\n * Runtime validation happens in loadConfig(), not here.\n */\nexport function defineConfig(config: Partial<TheoConfig>): Partial<TheoConfig> {\n  return config\n}\n","/**\n * M31 Phase 3 — `config()`, the fluent builder that replaces `defineConfig({...})`.\n *\n * Config is a ~30-field flat bag — a pure setter chain would be worse DX than an object literal\n * (Vite/Nuxt/Astro keep config as identity for this reason). So `config()` is HYBRID (ADR-M31-3):\n * chainable setters for the common fields PLUS a `.set(partial)` escape hatch for the long tail.\n * `.build()` delegates to the internal {@link defineConfig} (identity) — `loadConfig` is UNCHANGED.\n *\n *   export default config()\n *     .serverDir('core')\n *     .agentsDir('core/agents')\n *     .appDir('apps/web')\n *     .set({ security: { csrf: 'strict' } })\n *     .build()\n */\nimport { defineConfig } from './define-config.js'\nimport type { TheoConfig } from './schema.js'\n\n/** The fluent config builder. No field is required; `.set()` merges arbitrary config fields. */\nexport interface ConfigBuilder {\n  /** Project identifier (DNS-1123) — used by `.theokit/services.json`. */\n  name(value: TheoConfig['name']): ConfigBuilder\n  /** Backend root dir (route/action/agent discovery). Default `'server'`. */\n  serverDir(value: TheoConfig['serverDir']): ConfigBuilder\n  /** Frontend root dir (file-based router). Default `'app'`. */\n  appDir(value: TheoConfig['appDir']): ConfigBuilder\n  /** Agents root dir. Default `'agents'`. */\n  agentsDir(value: TheoConfig['agentsDir']): ConfigBuilder\n  /** Build output dir. Default `'.theokit'`. */\n  distDir(value: TheoConfig['distDir']): ConfigBuilder\n  /** Dev/prod port. Default `3000`. */\n  port(value: TheoConfig['port']): ConfigBuilder\n  /** Bind host. Default `'localhost'`. */\n  host(value: TheoConfig['host']): ConfigBuilder\n  /** Enable server-side rendering. Default `false`. */\n  ssr(value: TheoConfig['ssr']): ConfigBuilder\n  /** Escape hatch — merge any config fields not covered by a dedicated setter (rate-limit, security…). */\n  set(partial: Partial<TheoConfig>): ConfigBuilder\n  /** Resolve to the `Partial<TheoConfig>` — the SAME value `defineConfig({...})` returns. */\n  build(): Partial<TheoConfig>\n}\n\nfunction makeConfigBuilder(spec: Partial<TheoConfig>): ConfigBuilder {\n  const merge = (patch: Partial<TheoConfig>): ConfigBuilder =>\n    makeConfigBuilder({ ...spec, ...patch })\n  return {\n    name: (value) => merge({ name: value }),\n    serverDir: (value) => merge({ serverDir: value }),\n    appDir: (value) => merge({ appDir: value }),\n    agentsDir: (value) => merge({ agentsDir: value }),\n    distDir: (value) => merge({ distDir: value }),\n    port: (value) => merge({ port: value }),\n    host: (value) => merge({ host: value }),\n    ssr: (value) => merge({ ssr: value }),\n    set: (partial) => merge(partial),\n    build: () => defineConfig(spec),\n  }\n}\n\n/**\n * Start a fluent config definition. Chain the common setters and/or `.set(partial)`, then `.build()`.\n */\nexport function config(): ConfigBuilder {\n  return makeConfigBuilder({})\n}\n","/* eslint-disable security/detect-non-literal-fs-filename --\n * Project-structure validator. Reads paths joined onto `projectRoot`,\n * with names from a fixed `ValidationRule[]` table. No HTTP input.\n */\nimport { existsSync } from 'node:fs'\nimport { join } from 'node:path'\n\nimport { TheoProjectError } from '../core/errors.js'\n\ninterface ValidationRule {\n  path: string\n  errorMessage: string\n}\n\nconst REQUIRED_FILES: ValidationRule[] = [\n  {\n    path: 'theo.config.ts',\n    errorMessage: 'Missing required file: theo.config.ts',\n  },\n  {\n    path: 'package.json',\n    errorMessage: 'Missing required file: package.json',\n  },\n]\n\n// #95 — honor config `appDir` (default \"app\") so a project that groups its frontend under a custom\n// directory (e.g. `apps/web`) is not rejected by a hardcoded `app/` requirement.\nexport function validateProjectStructure(rootDir: string, appDir = 'app'): void {\n  if (!existsSync(rootDir)) {\n    throw new TheoProjectError([`Project directory does not exist: ${rootDir}`], rootDir)\n  }\n\n  const errors: string[] = []\n\n  const requiredDirs: ValidationRule[] = [\n    { path: appDir, errorMessage: `Missing required directory: ${appDir}/` },\n  ]\n\n  for (const rule of requiredDirs) {\n    if (!existsSync(join(rootDir, rule.path))) {\n      errors.push(rule.errorMessage)\n    }\n  }\n\n  for (const rule of REQUIRED_FILES) {\n    if (!existsSync(join(rootDir, rule.path))) {\n      errors.push(rule.errorMessage)\n    }\n  }\n\n  if (errors.length > 0) {\n    throw new TheoProjectError(errors, rootDir)\n  }\n}\n","export class TheoProjectError extends Error {\n  public readonly errors: string[]\n  public readonly rootDir: string\n\n  constructor(errors: string[], rootDir: string) {\n    const errorLines = errors.map((e) => `  - ${e}`).join('\\n')\n\n    super(\n      `Invalid Theo project structure\\n\\n` +\n        `  Root: ${rootDir}\\n\\n` +\n        (errorLines ? `  Errors:\\n${errorLines}\\n` : ''),\n    )\n\n    this.name = 'TheoProjectError'\n    this.errors = errors\n    this.rootDir = rootDir\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOO,SAAS,aAAaA,SAAkD;AAC7E,SAAOA;AACT;;;ACiCA,SAAS,kBAAkB,MAA0C;AACnE,QAAM,QAAQ,CAAC,UACb,kBAAkB,EAAE,GAAG,MAAM,GAAG,MAAM,CAAC;AACzC,SAAO;AAAA,IACL,MAAM,CAAC,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC;AAAA,IACtC,WAAW,CAAC,UAAU,MAAM,EAAE,WAAW,MAAM,CAAC;AAAA,IAChD,QAAQ,CAAC,UAAU,MAAM,EAAE,QAAQ,MAAM,CAAC;AAAA,IAC1C,WAAW,CAAC,UAAU,MAAM,EAAE,WAAW,MAAM,CAAC;AAAA,IAChD,SAAS,CAAC,UAAU,MAAM,EAAE,SAAS,MAAM,CAAC;AAAA,IAC5C,MAAM,CAAC,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC;AAAA,IACtC,MAAM,CAAC,UAAU,MAAM,EAAE,MAAM,MAAM,CAAC;AAAA,IACtC,KAAK,CAAC,UAAU,MAAM,EAAE,KAAK,MAAM,CAAC;AAAA,IACpC,KAAK,CAAC,YAAY,MAAM,OAAO;AAAA,IAC/B,OAAO,MAAM,aAAa,IAAI;AAAA,EAChC;AACF;AAKO,SAAS,SAAwB;AACtC,SAAO,kBAAkB,CAAC,CAAC;AAC7B;;;AC5DA,SAAS,kBAAkB;AAC3B,SAAS,YAAY;;;ACLd,IAAM,mBAAN,cAA+B,MAAM;AAAA,EAC1B;AAAA,EACA;AAAA,EAEhB,YAAY,QAAkB,SAAiB;AAC7C,UAAM,aAAa,OAAO,IAAI,CAAC,MAAM,OAAO,CAAC,EAAE,EAAE,KAAK,IAAI;AAE1D;AAAA,MACE;AAAA;AAAA,UACa,OAAO;AAAA;AAAA,KACjB,aAAa;AAAA,EAAc,UAAU;AAAA,IAAO;AAAA,IACjD;AAEA,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,UAAU;AAAA,EACjB;AACF;;;ADHA,IAAM,iBAAmC;AAAA,EACvC;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AACF;AAIO,SAAS,yBAAyB,SAAiB,SAAS,OAAa;AAC9E,MAAI,CAAC,WAAW,OAAO,GAAG;AACxB,UAAM,IAAI,iBAAiB,CAAC,qCAAqC,OAAO,EAAE,GAAG,OAAO;AAAA,EACtF;AAEA,QAAM,SAAmB,CAAC;AAE1B,QAAM,eAAiC;AAAA,IACrC,EAAE,MAAM,QAAQ,cAAc,+BAA+B,MAAM,IAAI;AAAA,EACzE;AAEA,aAAW,QAAQ,cAAc;AAC/B,QAAI,CAAC,WAAW,KAAK,SAAS,KAAK,IAAI,CAAC,GAAG;AACzC,aAAO,KAAK,KAAK,YAAY;AAAA,IAC/B;AAAA,EACF;AAEA,aAAW,QAAQ,gBAAgB;AACjC,QAAI,CAAC,WAAW,KAAK,SAAS,KAAK,IAAI,CAAC,GAAG;AACzC,aAAO,KAAK,KAAK,YAAY;AAAA,IAC/B;AAAA,EACF;AAEA,MAAI,OAAO,SAAS,GAAG;AACrB,UAAM,IAAI,iBAAiB,QAAQ,OAAO;AAAA,EAC5C;AACF;","names":["config"]}

package/dist/{plugin-runner-BGBkzgi0.d.ts → plugin-runner-CMprWWHZ.d.ts}

@@ -1,4 +1,4 @@
-import { T as TheoPlugin, a as TheoApp, P as PluginContext, H as HookResult, R as RunHookOptions } from './plugin-types-DNJGxr4Z.js';
+import { T as TheoPlugin, a as TheoApp, P as PluginContext, H as HookResult, R as RunHookOptions } from './plugin-types-L49QYMb5.js';
 
 declare class DuplicatePluginError extends Error {
     constructor(name: string);

package/dist/{plugin-types-DNJGxr4Z.d.ts → plugin-types-L49QYMb5.d.ts}

@@ -29,24 +29,6 @@ interface TheoPlugin {
     name: string;
     register(app: TheoApp): void | Promise<void>;
 }
-/**
- * Identity function for plugin authors. Provides auto-completion + type
- * inference at the call site (TanStack/Vite/Astro pattern). Pure runtime
- * no-op — returns the input unchanged.
- *
- * @example
- *   import { definePlugin } from 'theokit/server'
- *   export default definePlugin({
- *     name: 'my-plugin',
- *     register(app) {
- *       app.addHook('onRequest', (req) => { ... })
- *     },
- *   })
- *
- * Equivalent to `const p: TheoPlugin = {...}` but more ergonomic. See
- * ADR-0008 (D1 + D6) for the rationale.
- */
-declare function definePlugin(plugin: TheoPlugin): TheoPlugin;
 /**
  * Web-Standards plugin context. Available during all 4 hook lifecycle
  * stages (onRequest, preHandler, onResponse, onError).
@@ -76,4 +58,4 @@ type WebPreHandlerHook = (ctx: WebPluginContext) => void | Promise<void>;
 type WebOnResponseHook = (ctx: WebPluginContext) => void | Promise<void>;
 type WebOnErrorHook = (ctx: WebPluginErrorContext) => void | Promise<void>;
 
-export { type HookResult as H, type OnErrorHook as O, type PluginContext as P, type RunHookOptions as R, type TheoPlugin as T, type WebOnRequestHook as W, type TheoApp as a, type WebPreHandlerHook as b, type WebOnResponseHook as c, type WebOnErrorHook as d, type HookName as e, type OnRequestHook as f, type OnResponseHook as g, type PluginErrorContext as h, type PreHandlerHook as i, definePlugin as j };
+export type { HookResult as H, OnErrorHook as O, PluginContext as P, RunHookOptions as R, TheoPlugin as T, WebOnRequestHook as W, TheoApp as a, WebPreHandlerHook as b, WebOnResponseHook as c, WebOnErrorHook as d, HookName as e, OnRequestHook as f, OnResponseHook as g, PluginErrorContext as h, PreHandlerHook as i };

package/dist/{registry-XSRSTH33.js → registry-3NB7KOUI.js}

@@ -6,7 +6,7 @@ var adapterRegistry = {
   node: async () => (await import("./node-BPJ3Z4DT.js")).nodeAdapter,
   vercel: async () => (await import("./vercel-J6G7ZHYQ.js")).vercelAdapter,
   cloudflare: async () => (await import("./cloudflare-C6E5SPAE.js")).cloudflareAdapter,
-  static: async () => (await import("./static-CYG2WGYP.js")).staticAdapter,
+  static: async () => (await import("./static-MB2CD5Y3.js")).staticAdapter,
   bun: async () => (await import("./bun-KP2KES6S.js")).bunAdapter,
   "deno-deploy": async () => (await import("./deno-deploy-RFZN56X4.js")).denoDeployAdapter,
   netlify: async () => (await import("./netlify-PMLHVPN4.js")).netlifyAdapter,
@@ -21,4 +21,4 @@ export {
   adapterRegistry,
   resolveAdapter
 };
-//# sourceMappingURL=registry-XSRSTH33.js.map
+//# sourceMappingURL=registry-3NB7KOUI.js.map

package/dist/server/define/index.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
+import { W as WebSocketHandler, b as WebSocketLike } from '../../define-websocket-CPQcQK9h.js';
+export { a as WebSocketHandlerWeb } from '../../define-websocket-CPQcQK9h.js';
+import { f as OnRequestHook, i as PreHandlerHook, g as OnResponseHook, O as OnErrorHook, T as TheoPlugin } from '../../plugin-types-L49QYMb5.js';
 import { UIMessageChunk } from 'ai';
-import { b as WebSocketLike } from '../../define-websocket-CdK94O-D.js';
-export { W as WebSocketHandler, a as WebSocketHandlerWeb, d as defineWebSocket, c as defineWebSocketWeb } from '../../define-websocket-CdK94O-D.js';
 import { IncomingMessage } from 'node:http';
-import { T as TheoPlugin } from '../../plugin-types-DNJGxr4Z.js';
 export { H as HEALTH_PATH, a as HealthRouteConfig, b as READY_PATH, c as ReadyRouteConfig, d as ReservedResponse, R as ReservedRoutes, e as defineHealthRoute, f as defineReadyRoute, s as serveReservedRoute } from '../../health-route-C0hk64_U.js';
 
 /**
@@ -58,12 +58,6 @@ interface RouteConfig<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z
     }) => TResponse | Promise<TResponse>;
 }
 
-/**
- * Define a typed HTTP route.
- * Identity function — provides type inference for route handlers.
- */
-declare function defineRoute<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z.ZodType = z.ZodUndefined, TParams extends z.ZodType = z.ZodUndefined, TCtx = unknown, TResponse = unknown>(config: RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>): RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>;
-
 /**
  * Action wire-protocol accept mode per plan g3-server-actions-and-useaction
  * v1.2 ADR D1. Default behavior (when omitted) is `'json'`. `'form'` opts the
@@ -98,28 +92,8 @@ interface ActionConfig<TInput extends z.ZodType, TCtx = unknown> {
         ctx: TCtx;
     }) => unknown;
 }
-/**
- * Define a typed server action.
- *
- * Identity function — provides type inference for action handlers. The
- * runtime that consumes the config (validation + invocation + serialization)
- * lives in `server/http/action-execute.ts`.
- *
- * Per plan g3-server-actions-and-useaction v1.2 § Phase 1 / T1.2: the new
- * `accept?: 'form' | 'json'` field is the only contract change vs the
- * pre-G3 identity. Existing callsites (`defineAction({input, handler})`)
- * continue to compile — `accept` is opt-in.
- */
-declare function defineAction<TInput extends z.ZodType, TCtx = unknown>(config: ActionConfig<TInput, TCtx>): ActionConfig<TInput, TCtx>;
 
 type MiddlewareHandler = (request: Request, next: (request: Request) => Promise<Response>) => Response | Promise<Response>;
-/**
- * Define a middleware handler.
- * Identity function — provides type annotation for middleware.
- */
-declare function defineMiddleware(handler: MiddlewareHandler): MiddlewareHandler;
-
-declare function uiMessageStreamResponse(chunks: AsyncIterable<UIMessageChunk>): Response;
 
 /**
  * Item #4 — `defineAgentTool`
@@ -201,29 +175,277 @@ interface DefineAgentToolSpec<T extends z.ZodType, R = string> {
     transform?: ToolTransform<R>;
 }
 /**
- * Build a {@link CustomTool} from a Zod 3 schema + handler.
+ * M18 — apply a tool's `transform` for a target (`display` / `transcript`). Returns the formatted
+ * value, or the raw `result` when the tool declares no transform for that target.
+ */
+declare function applyTransform(tool: CustomTool, result: unknown, target: 'display' | 'transcript'): unknown;
+
+/**
+ * M31 Phase 3 — `route()`, the fluent builder that replaces `defineRoute({...})`.
  *
- * Behavior:
- * - Validates `name` matches the LLM tool-name regex.
- * - Requires `inputSchema` to be a `ZodObject` (Anthropic + SDK contract).
- * - Warns (not throws) if `description` is empty — empty descriptions
- *   degrade LLM tool selection.
- * - Converts the Zod schema to JSON Schema 7 inline (no `$ref`s — LLMs handle
- *   inline schemas more reliably).
- * - Strips the top-level `$schema` field (Anthropic rejects schemas with
- *   `$schema` at root in some provider modes).
- * - Wraps the handler to parse the input via the Zod schema BEFORE invoking
- *   the user code — bad LLM-supplied input throws `ZodError`, which the SDK
- *   converts to `tool_result(isError)`.
+ * Pure type-state (mirrors `tool-builder.ts`). `.query/.body/.params` set Zod schemas whose
+ * `z.infer<>` flows into the handler's `ctx`; `.handler()` is required before `.build()`. `.build()`
+ * delegates to the internal {@link defineRoute} (an identity fn), emitting the identical
+ * `RouteConfig` — the scan/execute path is UNCHANGED (identity-shape delegation, blueprint §2).
  *
- * @public
+ *   export const POST = route()
+ *     .params(z.object({ id: z.string() }))
+ *     .body(z.object({ text: z.string() }))
+ *     .handler(({ params, body }) => save(params.id, body.text))
+ *     .build()
  */
-declare function defineAgentTool<T extends z.ZodType, R = string>(spec: DefineAgentToolSpec<T, R>): CustomTool;
+
+/** Compile-error carrier: `.build()` called before `.handler()`. */
+interface MissingHandlerError {
+    readonly __theokitError: 'a route needs .handler(fn) before .build()';
+}
 /**
- * M18 — apply a tool's `transform` for a target (`display` / `transcript`). Returns the formatted
- * value, or the raw `result` when the tool declares no transform for that target.
+ * The fluent route builder. `TQuery/TBody/TParams` track the input schemas (default `z.ZodUndefined`,
+ * matching {@link RouteConfig}); `TResponse` tracks the handler return; `THandlerSet` gates `.build()`.
  */
-declare function applyTransform(tool: CustomTool, result: unknown, target: 'display' | 'transcript'): unknown;
+interface RouteBuilder<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z.ZodType = z.ZodUndefined, TParams extends z.ZodType = z.ZodUndefined, TCtx = unknown, TResponse = unknown, THandlerSet extends boolean = false> {
+    /** Set the URL search-params schema. Inferred into `ctx.query`. */
+    query<S extends z.ZodType>(schema: S): RouteBuilder<S, TBody, TParams, TCtx, TResponse, THandlerSet>;
+    /** Set the request-body schema. Inferred into `ctx.body`. */
+    body<S extends z.ZodType>(schema: S): RouteBuilder<TQuery, S, TParams, TCtx, TResponse, THandlerSet>;
+    /** Set the path-params schema. Inferred into `ctx.params`. */
+    params<S extends z.ZodType>(schema: S): RouteBuilder<TQuery, TBody, S, TCtx, TResponse, THandlerSet>;
+    /** Runtime-only validation of the handler's plain-object return (500 on mismatch). Not inferred (YAGNI). */
+    response(schema: z.ZodType): RouteBuilder<TQuery, TBody, TParams, TCtx, TResponse, THandlerSet>;
+    /** Override the HTTP status for a plain-object return (default 200; 204 for void). */
+    status(code: number): RouteBuilder<TQuery, TBody, TParams, TCtx, TResponse, THandlerSet>;
+    /** Opt out of CSRF enforcement for this route (webhooks / OAuth callbacks). */
+    csrf(disabled: false): RouteBuilder<TQuery, TBody, TParams, TCtx, TResponse, THandlerSet>;
+    /**
+     * Set the handler. Its `ctx` infers `query/body/params` from the schemas set above. Required
+     * before `.build()`.
+     */
+    handler<R>(fn: (ctx: {
+        query: z.infer<TQuery>;
+        body: z.infer<TBody>;
+        params: z.infer<TParams>;
+        request: Request;
+        ctx: TCtx;
+    }) => R | Promise<R>): RouteBuilder<TQuery, TBody, TParams, TCtx, R, true>;
+    /**
+     * Resolve to the `RouteConfig` — the SAME value `defineRoute({...})` returns. COMPILE ERROR when
+     * `.handler()` was never called.
+     */
+    build(...guard: THandlerSet extends true ? [] : [error: MissingHandlerError]): RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>;
+}
+/**
+ * Start a fluent route definition. Chain `.query/.body/.params/.response/.status/.csrf` (all
+ * optional), then `.handler()` (required) and `.build()` for the `RouteConfig`.
+ */
+declare function route(): RouteBuilder;
+
+/**
+ * M31 Phase 3 — `action()`, the fluent builder that replaces `defineAction({...})`.
+ *
+ * Pure type-state (mirrors `route-builder.ts`). `.input()` (required) sets the Zod schema whose
+ * `z.infer<>` types the handler's `ctx.input`; `.handler()` (required) closes the chain. `.build()`
+ * delegates to the internal {@link defineAction} (identity) — the action-execute path is UNCHANGED.
+ *
+ *   export const createUser = action()
+ *     .input(z.object({ email: z.string().email() }))
+ *     .handler(({ input }) => createUser(input.email))
+ *     .build()
+ */
+
+/** Compile-error carrier: `.execute`/`.build()` reached before `.input()`. */
+interface MissingInputError$1 {
+    readonly __theokitError: 'call .input(schema) before .handler(fn)';
+}
+/** Compile-error carrier: `.build()` before both `.input()` and `.handler()` are set. */
+interface IncompleteActionError {
+    readonly __theokitError: 'an action needs .input(schema) and .handler(fn) before .build()';
+}
+/** A required-but-unset field. Branded so no ordinary value satisfies it (tRPC UnsetMarker). */
+type UnsetMarker$1 = 'theokit.unset' & {
+    readonly __brand: 'theokit.unset';
+};
+/**
+ * The fluent action builder. `TInput` tracks the Zod schema (drives `ctx.input` inference);
+ * `THandlerSet` gates `.build()`.
+ */
+interface ActionBuilder<TInput extends z.ZodType | UnsetMarker$1 = UnsetMarker$1, TCtx = unknown, THandlerSet extends boolean = false> {
+    /** Set the Zod input schema. Required — every action declares its input contract (zod-is-SSOT). */
+    input<S extends z.ZodType>(schema: S): ActionBuilder<S, TCtx, THandlerSet>;
+    /** Wire-protocol accept mode (`'json'` default, `'form'` for FormData multipart). */
+    accept(mode: ActionAccept): ActionBuilder<TInput, TCtx, THandlerSet>;
+    /** Opt out of CSRF enforcement for this action. */
+    csrf(disabled: false): ActionBuilder<TInput, TCtx, THandlerSet>;
+    /**
+     * Set the handler. COMPILE ERROR before `.input()` — the param type collapses to
+     * {@link MissingInputError}. `ctx.input` is inferred via `z.infer<TInput>`.
+     */
+    handler(fn: TInput extends z.ZodType ? (ctx: {
+        input: z.infer<TInput>;
+        ctx: TCtx;
+    }) => unknown : MissingInputError$1): ActionBuilder<TInput, TCtx, true>;
+    /**
+     * Resolve to the `ActionConfig` — the SAME value `defineAction({...})` returns. COMPILE ERROR when
+     * `.input()` or `.handler()` was never called.
+     */
+    build(...guard: THandlerSet extends true ? TInput extends z.ZodType ? [] : [error: IncompleteActionError] : [error: IncompleteActionError]): ActionConfig<TInput extends z.ZodType ? TInput : z.ZodType, TCtx>;
+}
+/**
+ * Start a fluent action definition. Chain `.input()` (required), optionally `.accept()` / `.csrf()`,
+ * then `.handler()` (required) and `.build()` for the `ActionConfig`.
+ */
+declare function action(): ActionBuilder;
+
+/**
+ * M31 Phase 3 — `websocket()`, the fluent builder that replaces `defineWebSocket({...})`.
+ *
+ * Lifecycle setters (`onOpen/onMessage/onClose/onError`), all optional; `.build()` delegates to the
+ * internal {@link defineWebSocket} (identity) — the ws handler loading path is UNCHANGED.
+ *
+ *   export default websocket()
+ *     .onOpen((ws) => ws.send('hi'))
+ *     .onMessage((ws, data) => ws.send(`echo:${data}`))
+ *     .build()
+ */
+
+/** The fluent WebSocket builder. Each lifecycle hook is optional; `.build()` returns the handler. */
+interface WebSocketBuilder {
+    onOpen(fn: NonNullable<WebSocketHandler['onOpen']>): WebSocketBuilder;
+    onMessage(fn: NonNullable<WebSocketHandler['onMessage']>): WebSocketBuilder;
+    onClose(fn: NonNullable<WebSocketHandler['onClose']>): WebSocketBuilder;
+    onError(fn: NonNullable<WebSocketHandler['onError']>): WebSocketBuilder;
+    /** Resolve to the `WebSocketHandler` — the SAME value `defineWebSocket({...})` returns. */
+    build(): WebSocketHandler;
+}
+/** Start a fluent WebSocket definition. Chain any of the lifecycle hooks, then `.build()`. */
+declare function websocket(): WebSocketBuilder;
+
+/**
+ * M31 Phase 3 — `middleware()`, the fluent builder that replaces `defineMiddleware(fn)`.
+ *
+ * A middleware IS a single function `(request, next) => Response`. The builder's `.handle()` sets it
+ * (required); `.build()` delegates to the internal {@link defineMiddleware} (identity) and returns
+ * the handler the runtime expects.
+ *
+ *   export default middleware()
+ *     .handle(async (request, next) => {
+ *       const res = await next(request)
+ *       res.headers.set('x-mw', '1')
+ *       return res
+ *     })
+ *     .build()
+ */
+
+/** Compile-error carrier: `.build()` called before `.handle()`. */
+interface MissingHandleError {
+    readonly __theokitError: 'middleware needs .handle(fn) before .build()';
+}
+/** The fluent middleware builder. `THandleSet` gates `.build()`. */
+interface MiddlewareBuilder<THandleSet extends boolean = false> {
+    /** Set the `(request, next) => Response` handler. Required before `.build()`. */
+    handle(fn: MiddlewareHandler): MiddlewareBuilder<true>;
+    /** Resolve to the `MiddlewareHandler`. COMPILE ERROR when `.handle()` was never called. */
+    build(...guard: THandleSet extends true ? [] : [error: MissingHandleError]): MiddlewareHandler;
+}
+/** Start a fluent middleware definition. Chain `.handle()` (required), then `.build()`. */
+declare function middleware(): MiddlewareBuilder;
+
+/**
+ * M31 Phase 1 — `tool()`, the fluent builder that replaces `defineAgentTool({...})`.
+ *
+ * Pure type-state (tRPC `UnsetMarker` technique, mirroring `agent-builder.ts`). The runtime is a
+ * plain accumulator; `.build()` delegates to the internal {@link defineAgentTool}, so the emitted
+ * `CustomTool` is byte-for-byte the legacy shape — the SDK/agent compile path is UNCHANGED
+ * (identity-shape delegation, blueprint §2).
+ *
+ * PURE metadata (G2 / sdk-runtime.md): a tool describes a capability; it NEVER calls an LLM.
+ *
+ *   tool('read')
+ *     .describe('Read a UTF-8 file')
+ *     .input(z.object({ path: z.string() }))
+ *     .execute(async ({ path }, ctx) => readFile(resolveInProject(ctx, path)))
+ *     .build()
+ */
+
+/** A required-but-unset builder field. Branded so no ordinary value satisfies it (tRPC UnsetMarker). */
+type UnsetMarker = 'theokit.unset' & {
+    readonly __brand: 'theokit.unset';
+};
+/** Compile-error carrier: `.execute()` called before `.input()`. */
+interface MissingInputError {
+    readonly __theokitError: 'call .input(schema) before .execute(handler)';
+}
+/** Compile-error carrier: `.build()` called before both `.input()` and `.execute()` are set. */
+interface IncompleteToolError {
+    readonly __theokitError: 'a tool needs .input(schema) and .execute(handler) before .build()';
+}
+/** The run context a tool handler receives (M7). */
+interface ToolCtx {
+    signal?: AbortSignal;
+    context?: unknown;
+}
+/**
+ * The fluent tool builder. Each method returns a NEW builder type with the relevant type parameter
+ * advanced. `TInput` tracks the Zod schema (drives `execute` input inference); `R` tracks the
+ * handler result; `THandlerSet` gates `.build()`.
+ */
+interface ToolBuilder<TName extends string = string, TInput extends z.ZodType | UnsetMarker = UnsetMarker, R = string, THandlerSet extends boolean = false> {
+    /** Set the LLM-facing description. Optional; an empty description warns at build (LLM selection). */
+    describe(description: string): ToolBuilder<TName, TInput, R, THandlerSet>;
+    /** Set the Zod input schema (must be `z.object(...)` at the root). Required before `.execute()`. */
+    input<S extends z.ZodType>(schema: S): ToolBuilder<TName, S, R, THandlerSet>;
+    /**
+     * Set the handler. COMPILE ERROR when `.input()` was not called first — the parameter type
+     * collapses to {@link MissingInputError}. The `input` argument is inferred via `z.infer<TInput>`.
+     */
+    execute<R2>(handler: TInput extends z.ZodType ? (input: z.infer<TInput>, ctx?: ToolCtx) => R2 | Promise<R2> : MissingInputError): ToolBuilder<TName, TInput, R2, true>;
+    /** M18 — map a rich handler result to the model-visible string. */
+    toModelOutput(fn: (result: R) => string): ToolBuilder<TName, TInput, R, THandlerSet>;
+    /** M18 — per-target formatters (`display` / `transcript`) for the app UI/transcript. */
+    transform(t: ToolTransform<R>): ToolBuilder<TName, TInput, R, THandlerSet>;
+    /**
+     * Resolve to the `CustomTool` — the SAME value `defineAgentTool({...})` returns. COMPILE ERROR
+     * when `.input()` or `.execute()` was never called.
+     */
+    build(...guard: THandlerSet extends true ? TInput extends z.ZodType ? [] : [error: IncompleteToolError] : [error: IncompleteToolError]): CustomTool;
+}
+/**
+ * Start a fluent tool definition. Chain `.input()` + `.execute()` (both required), optionally
+ * `.describe()` / `.toModelOutput()` / `.transform()`, then `.build()` for the `CustomTool`.
+ */
+declare function tool<TName extends string>(name: TName): ToolBuilder<TName>;
+
+/**
+ * M31 Phase 3 — `plugin()`, the fluent builder that replaces `definePlugin({...})`.
+ *
+ * Collects lifecycle hooks + request decorations and SYNTHESIZES the `register(app)` function, so
+ * authors never write the imperative `register` body. `.build()` returns a `TheoPlugin` the plugin
+ * runner consumes UNCHANGED.
+ *
+ *   export default plugin('request-id')
+ *     .onRequest((ctx) => { ctx.ctx.requestId = crypto.randomUUID() })
+ *     .onResponse((ctx) => { ctx.response.setHeader('x-request-id', String(ctx.ctx.requestId)) })
+ *     .build()
+ */
+
+/** The fluent plugin builder. `name` is set at entry; every hook is optional and may repeat. */
+interface PluginBuilder {
+    /** Register an `onRequest` hook (runs before the CSRF gate). May be called multiple times. */
+    onRequest(fn: OnRequestHook): PluginBuilder;
+    /** Register a `preHandler` hook (after CSRF, before the route handler). */
+    preHandler(fn: PreHandlerHook): PluginBuilder;
+    /** Register an `onResponse` hook (after the handler returns). */
+    onResponse(fn: OnResponseHook): PluginBuilder;
+    /** Register an `onError` hook (error path). */
+    onError(fn: OnErrorHook): PluginBuilder;
+    /** Decorate every request with a key/value pair (available on `ctx.ctx[key]`). */
+    decorateRequest<T>(key: string, value: T): PluginBuilder;
+    /** Resolve to the `TheoPlugin` — a synthesized `{ name, register }` the runner consumes. */
+    build(): TheoPlugin;
+}
+/** Start a fluent plugin definition. `name` is required; chain hooks/decorations, then `.build()`. */
+declare function plugin(name: string): PluginBuilder;
+
+declare function uiMessageStreamResponse(chunks: AsyncIterable<UIMessageChunk>): Response;
 
 interface ChannelHandler<TMessage = unknown> {
     onSubscribe?: (ws: WebSocketLike, room: string, req: IncomingMessage) => void;
@@ -270,13 +492,4 @@ interface WebChannelHandler<TMessage = unknown> {
  */
 declare function defineWebChannel<TMessage = unknown>(handler: WebChannelHandler<TMessage>): WebChannelHandler<TMessage>;
 
-/**
- * Identity function for defining a Theo plugin.
- *
- * **Note:** Prefer `definePlugin` (shorter, canonical name per ADR-0008 D6).
- * Both functions are identical — `defineTheoPlugin` is kept as an alias for
- * existing in-tree consumers without forcing a migration sweep.
- */
-declare function defineTheoPlugin(plugin: TheoPlugin): TheoPlugin;
-
-export { type ActionAccept, type ActionConfig, type ChannelHandler, type CustomTool, type DefineAgentToolSpec, type MiddlewareHandler, type RouteConfig, type ToolTransform, type WebChannelHandler, WebSocketLike, applyTransform, defineAction, defineAgentTool, defineChannel, defineMiddleware, defineRoute, defineTheoPlugin, defineWebChannel, uiMessageStreamResponse };
+export { type ActionAccept, type ActionBuilder, type ActionConfig, type ChannelHandler, type CustomTool, type DefineAgentToolSpec, type MiddlewareBuilder, type MiddlewareHandler, type PluginBuilder, type RouteBuilder, type RouteConfig, type ToolBuilder, type ToolTransform, type WebChannelHandler, type WebSocketBuilder, WebSocketHandler, WebSocketLike, action, applyTransform, defineChannel, defineWebChannel, middleware, plugin, route, tool, uiMessageStreamResponse, websocket };