theokit 0.7.0 → 0.8.0

package/dist/health-route-C0hk64_U.d.ts

@@ -0,0 +1,57 @@
+/**
+ * M7-2 — health/ready reserved routes for the convention/filesystem-route
+ * server. Liveness (`/__theo/health`, always 200) and readiness
+ * (`/__theo/ready`, 200/503 from a probe) are registered on a reserved
+ * namespace BEFORE the user-route catch-all + 404 branch — mirroring nitro's
+ * `/_nitro/*` reserved-namespace pattern (knowledge-base/references/nitro/src/
+ * runtime/internal/routes/dev-tasks.ts). Liveness and readiness are kept
+ * separate by design: liveness says "the process is up", readiness says
+ * "dependencies are up".
+ *
+ * @public
+ */
+/** Reserved path for the liveness endpoint. */
+declare const HEALTH_PATH = "/__theo/health";
+/** Reserved path for the readiness endpoint. */
+declare const READY_PATH = "/__theo/ready";
+/** Config produced by {@link defineHealthRoute}. */
+interface HealthRouteConfig {
+    readonly kind: 'health';
+    /** Returns the liveness body (auto-serialized to JSON). Default: `{ status: 'ok' }`. */
+    readonly handler: () => unknown;
+}
+/** Config produced by {@link defineReadyRoute}. */
+interface ReadyRouteConfig {
+    readonly kind: 'ready';
+    /** Resolves `true` when dependencies are ready. A throw/reject is treated as not-ready (503). */
+    readonly probe: () => boolean | Promise<boolean>;
+}
+/** The reserved-route registry consulted by {@link serveReservedRoute}. */
+interface ReservedRoutes {
+    readonly health?: HealthRouteConfig;
+    readonly ready?: ReadyRouteConfig;
+}
+/** A reserved-route response: an HTTP status + a JSON-serializable body. */
+interface ReservedResponse {
+    readonly status: number;
+    readonly body: unknown;
+}
+/**
+ * Define the liveness route. The default handler returns `{ status: 'ok' }`.
+ * Liveness is always 200 — it asserts the process is up, not that dependencies are.
+ */
+declare function defineHealthRoute(handler?: () => unknown): HealthRouteConfig;
+/**
+ * Define the readiness route. The `probe` decides 200 (ready) vs 503 (not-ready).
+ * A probe that throws/rejects is treated as not-ready (503) — never a 500 crash.
+ */
+declare function defineReadyRoute(probe: () => boolean | Promise<boolean>): ReadyRouteConfig;
+/**
+ * Pure dispatcher: map a request pathname to a reserved-route response, or
+ * `null` when the path is not reserved (so the user catch-all + 404 take over).
+ * Liveness defaults to 200 `{status:'ok'}`; readiness without a probe is
+ * trivially ready (200). Registered BEFORE the user catch-all by the caller.
+ */
+declare function serveReservedRoute(pathname: string, routes?: ReservedRoutes): Promise<ReservedResponse | null>;
+
+export { HEALTH_PATH as H, type ReservedRoutes as R, type HealthRouteConfig as a, READY_PATH as b, type ReadyRouteConfig as c, type ReservedResponse as d, defineHealthRoute as e, defineReadyRoute as f, serveReservedRoute as s };

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

@@ -1,6 +1,8 @@
+import { a as TheoErrorCode, T as TheoErrorEnvelope } from './error-envelope-BsNzzAV5.js';
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { J as JobBackend } from './job-backend-CgC8Xf33.js';
+import { P as PluginContext } from './plugin-types-DNJGxr4Z.js';
 import { P as PluginRunner } from './plugin-runner-BGBkzgi0.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';
 import { z } from 'zod';
@@ -294,6 +296,180 @@ declare function extractTraceId(req: IncomingMessage): string;
  */
 declare function extractTraceIdFromRequest(request: Request): string;
 
+/**
+ * `TheoError` — envelope-emitting `Error` subclass per plan
+ * g5-error-envelope-cross-layer v1.0 § Phase 1 / T1.2.
+ *
+ * Mirrors trpc's TRPCError ergonomic pattern (referencia:
+ * trpc/packages/server/src/unstable-core-do-not-import/error/TRPCError.ts:65-87)
+ * adapted for theokit's hybrid envelope model (blueprint Form 4).
+ *
+ * Per ADR D5: `meta.stack` is auto-stripped in non-dev builds when serialized
+ * via `toJSON()` — defense against accidental stack leak to clients (encore
+ * `json:"-"` analog).
+ *
+ * Lives in `core/contracts/` per architecture.md v3 invariant #3.
+ */
+
+/**
+ * Constructor options. `code` and `message` are required; `cause` follows TC39
+ * proposal-error-cause; `meta` and `ext` are opt-in per blueprint ADR D2.
+ */
+interface TheoErrorOptions<TExt = unknown> {
+    readonly code: TheoErrorCode;
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly meta?: Record<string, unknown>;
+    readonly ext?: TExt;
+}
+/**
+ * `TheoError` — envelope-emitting Error subclass. Use this anywhere in
+ * `theokit/server`, route handlers, or middleware to emit a typed,
+ * cross-layer-compatible error.
+ *
+ * Mirrors TRPCError pattern: `code` is required, `message` defaults to
+ * code if omitted, `cause` chain is preserved via TC39 proposal-error-cause.
+ */
+declare class TheoError<TExt = unknown> extends Error {
+    readonly name = "TheoError";
+    readonly code: TheoErrorCode;
+    readonly meta?: Record<string, unknown>;
+    readonly ext?: TExt;
+    constructor(opts: TheoErrorOptions<TExt>);
+    /**
+     * The canonical envelope view of this error. Use when crossing the wire
+     * boundary or feeding telemetry — exposes the shape consumers can rely on
+     * without depending on the class identity.
+     */
+    get envelope(): TheoErrorEnvelope<TExt>;
+    /**
+     * JSON serialization — emits envelope shape only (no name/stack class
+     * internals). Per ADR D5, `meta.stack` is auto-stripped in non-dev to
+     * prevent accidental leak; other meta keys are preserved.
+     */
+    toJSON(): TheoErrorEnvelope<TExt>;
+}
+/**
+ * Coerce any unknown value into a TheoError envelope.
+ *
+ * - If value is already a TheoError, returns it unchanged (no double-wrap).
+ * - If value is a plain Error, wraps it as `INTERNAL_SERVER_ERROR` with
+ *   `cause` chain preserving the original.
+ * - Other values (string, undefined, object) are coerced safely with a
+ *   meaningful message.
+ *
+ * Use at framework boundaries (route handler catch-all, middleware catch,
+ * SDK egress) to ensure every error crossing the wire carries an envelope.
+ */
+/**
+ * `NotFoundError` — typed 404. A `TheoError` with code `NOT_FOUND`, so it
+ * carries a stable `code` (not a bare status literal) and maps to HTTP 404 via
+ * `envelopeCodeToStatus`. Throw it from a `defineRoute` handler for ergonomic
+ * 404s (M7-1).
+ */
+declare class NotFoundError extends TheoError {
+    constructor(message?: string, meta?: Record<string, unknown>);
+}
+declare function fromUnknown(value: unknown): TheoError;
+
+/**
+ * G5 T2.5 — server-side boundary translation per blueprint ADR D3.
+ *
+ * Translates ad-hoc Error class instances (FileTooLargeError,
+ * AuthRequiredError, RouterConventionError, etc.) into the canonical
+ * `TheoErrorEnvelope` shape at the wire boundary. This is the SINGLE
+ * boundary translation point — class identities stay in place inside the
+ * codebase (no invasive call-site rewrites), but the envelope is what
+ * crosses to clients.
+ *
+ * Pure; no I/O. Lives in `core/contracts/` per architecture.md v3
+ * invariant #3 (canonical home for shared client↔server types). This file
+ * is the EXCEPTION-of-an-exception: it intentionally inspects Error names
+ * by string instead of `instanceof` to avoid `core/contracts/` taking a
+ * dependency on `server/`. The mapping table is small and grep-discoverable.
+ */
+
+/**
+ * Translate any server-side Error instance into a canonical envelope.
+ *
+ * Pass-through behavior:
+ * - `TheoError` instances return their `.envelope` unchanged.
+ * - Plain `Error` with unknown name → `INTERNAL_SERVER_ERROR`.
+ * - Non-Error values → wrapped via `TheoError.fromUnknown` semantics.
+ *
+ * Meta carries the source class `name` plus class-specific fields when an
+ * extractor is registered. This keeps wire-side telemetry useful without
+ * leaking implementation details.
+ */
+declare function serverErrorToEnvelope(value: unknown): TheoErrorEnvelope;
+
+/**
+ * Maps a TheoErrorEnvelope `code` to its canonical HTTP status.
+ *
+ * Single source of truth — previously duplicated in `web-handler.ts` and
+ * `handle-request-error.ts` (architecture-remediation plan T1.2, 2026-06-12).
+ *
+ * Every TheoErrorCode value MUST have an explicit entry here. SDK-domain codes
+ * (AGENT_RUN_ERROR, PROVIDER_KEY_MISSING, BUDGET_EXCEEDED, CREDENTIAL_POOL_EXHAUSTED)
+ * intentionally map to 500 — they represent internal failures, not client errors.
+ */
+declare function envelopeCodeToStatus(code: string): number;
+
+/**
+ * Canonical error handler for HTTP request pipelines (T3.4 of
+ * architecture-review-remediation-plan, PV-9 DRY).
+ *
+ * Replaces the duplicated catch-block logic in `executeRoute` (1 site) and
+ * `executeAction` (1 site, via `handleActionError`). Both code paths now
+ * share this implementation.
+ *
+ * Behavior contract (preserved from previous inline catches):
+ * - Plugin `onError` fires first (swallowed if it throws — never amplify failure).
+ * - `AuthRequiredError` is detected via `instanceof` AND a duck-type shape
+ *   check (`code === 'AUTH_REQUIRED' && status === 401`) — required because
+ *   under Vite dev / vitest the module-loader can produce a duplicate
+ *   AuthRequiredError class identity, breaking `instanceof`.
+ * - `onResponse({ inErrorPath: true })` always fires at the end (swallowed
+ *   if it throws — EC-9).
+ */
+interface HandleRequestErrorCtx {
+    req: IncomingMessage;
+    res: ServerResponse;
+    requestId: string | undefined;
+    pluginRunner: PluginRunner | undefined;
+    buildPluginCtx: (ctxObj: Record<string, unknown>) => PluginContext;
+}
+declare function handleRequestError(err: unknown, c: HandleRequestErrorCtx): Promise<void>;
+/**
+ * T5a.2 Phase G slice 3/N — Web-Standards request error handler.
+ *
+ * Mirror of `handleRequestError(err, c: HandleRequestErrorCtx)` for the
+ * Web `Request` shape. Returns a native `Response` directly instead of
+ * mutating `res`. Same behavioral contract:
+ *
+ *   1. Auth-error detection via `instanceof AuthRequiredError` PLUS a
+ *      duck-type fallback (`code === 'AUTH_REQUIRED' && status === 401`)
+ *      — needed because Vite dev / vitest can produce duplicate class
+ *      identities, breaking `instanceof`.
+ *   2. Envelope-shaped JSON body using `serverErrorToEnvelope` (G5 D3
+ *      boundary translation).
+ *   3. Status code derived from envelope.code via `envelopeCodeToStatus`
+ *      mirror (already implemented inline in web-handler.ts; this slice
+ *      uses the same mapping table).
+ *
+ * **Difference vs IncomingMessage path:** the Web path's plugin runner
+ * orchestration lives in `executeWebRequest`'s `runWithHooks` /
+ * `runErrorHooks` (Phase G slice 1/N) — `handleWebRequestError` is the
+ * leaf that builds the error Response WITHOUT touching plugin hooks.
+ * Callers compose: `executeWebRequest` (or future Web execute pipeline)
+ * catches a throw, calls `handleWebRequestError(err, { requestId })` to
+ * build the Response, then routes through onError hooks separately.
+ */
+interface HandleWebRequestErrorCtx {
+    requestId?: string;
+}
+declare function handleWebRequestError(err: unknown, ctx?: HandleWebRequestErrorCtx): Promise<Response>;
+
 interface MiddlewareResult {
     ctx: unknown;
     aborted: boolean;
@@ -396,4 +572,4 @@ declare function loadCustomErrorPages(clientDir: string): CustomErrorPages;
 
 declare function serveStaticFile(req: IncomingMessage, res: ServerResponse, clientDir: string): boolean;
 
-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 };
+export { serveStaticFile as $, extractTraceId as A, BATCH_PATH as B, type CookieOptions as C, extractTraceIdFromRequest as D, type ExecuteActionOptions as E, fromUnknown as F, getCookie as G, type HandleBatchOptions as H, getCookieFromRequest as I, handleBatchRequest as J, handleRequestError as K, handleWebRequestError as L, MAX_ERROR_HTML_BYTES as M, NotFoundError as N, jsonTransformer as O, loadCustomErrorPages as P, matchesOrigin as Q, parseCookieHeader as R, STRIPPED_HEADERS as S, TRACE_HEADER as T, parseTraceparent as U, resolveTransformer as V, runMiddlewareAndContext as W, sendError as X, sendJson as Y, serializeCookie as Z, _resetMiddlewareCacheForTests as _, type BatchExecuteFn as a, serverErrorToEnvelope as a0, setCookie as a1, superjsonTransformer as a2, 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, TheoError as q, type TheoTransformer as r, appendCookieToHeaders as s, appendDeleteCookieToHeaders as t, createCorsHandler as u, createCorsWebHandler as v, deleteCookie as w, envelopeCodeToStatus as x, executeAction as y, executeRoute as z };

package/dist/index.js

@@ -8,27 +8,29 @@ import {
   scanRoutes,
   theoConfigSchema,
   theoPlugin
-} from "./chunk-6VSKLYT6.js";
+} from "./chunk-7BJ6YLKV.js";
+import "./chunk-7BIM27LV.js";
 import "./chunk-D7ZH7DTG.js";
 import "./chunk-PPPR5DGR.js";
-import "./chunk-7BIM27LV.js";
 import "./chunk-PIVX3DYW.js";
+import "./chunk-BB4ISKOB.js";
+import "./chunk-GY5Q27BJ.js";
 import "./chunk-5QW7IQQU.js";
+import "./chunk-WFNLNIJX.js";
 import "./chunk-IAJ2JVEH.js";
 import "./chunk-VMEWD57H.js";
 import "./chunk-JQSKBMXP.js";
 import "./chunk-223EFY5X.js";
 import "./chunk-WSJKACWB.js";
+import "./chunk-ZEGYW52B.js";
 import "./chunk-JBCHWRKF.js";
+import "./chunk-TSLSIRBR.js";
+import "./chunk-UD3LFGDL.js";
+import "./chunk-X32XEJXR.js";
+import "./chunk-UVXB2ER7.js";
 import "./chunk-C3ZZ56YZ.js";
 import "./chunk-7MQOHNHE.js";
 import "./chunk-X2VVCJ4V.js";
-import "./chunk-3FYJ7R7N.js";
-import "./chunk-GY5Q27BJ.js";
-import "./chunk-Z5IGLBWE.js";
-import "./chunk-ZEGYW52B.js";
-import "./chunk-TSLSIRBR.js";
-import "./chunk-UD3LFGDL.js";
 import "./chunk-DGUM43GV.js";
 
 // src/config/define-config.ts

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_DIRS: ValidationRule[] = [\n  {\n    path: 'app',\n    errorMessage: 'Missing required directory: app/',\n  },\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\nexport function validateProjectStructure(rootDir: string): void {\n  if (!existsSync(rootDir)) {\n    throw new TheoProjectError([`Project directory does not exist: ${rootDir}`], rootDir)\n  }\n\n  const errors: string[] = []\n\n  for (const rule of REQUIRED_DIRS) {\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,gBAAkC;AAAA,EACtC;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AACF;AAEA,IAAM,iBAAmC;AAAA,EACvC;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AACF;AAEO,SAAS,yBAAyB,SAAuB;AAC9D,MAAI,CAAC,WAAW,OAAO,GAAG;AACxB,UAAM,IAAI,iBAAiB,CAAC,qCAAqC,OAAO,EAAE,GAAG,OAAO;AAAA,EACtF;AAEA,QAAM,SAAmB,CAAC;AAE1B,aAAW,QAAQ,eAAe;AAChC,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/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_DIRS: ValidationRule[] = [\n  {\n    path: 'app',\n    errorMessage: 'Missing required directory: app/',\n  },\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\nexport function validateProjectStructure(rootDir: string): void {\n  if (!existsSync(rootDir)) {\n    throw new TheoProjectError([`Project directory does not exist: ${rootDir}`], rootDir)\n  }\n\n  const errors: string[] = []\n\n  for (const rule of REQUIRED_DIRS) {\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,gBAAkC;AAAA,EACtC;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AACF;AAEA,IAAM,iBAAmC;AAAA,EACvC;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,cAAc;AAAA,EAChB;AACF;AAEO,SAAS,yBAAyB,SAAuB;AAC9D,MAAI,CAAC,WAAW,OAAO,GAAG;AACxB,UAAM,IAAI,iBAAiB,CAAC,qCAAqC,OAAO,EAAE,GAAG,OAAO;AAAA,EACtF;AAEA,QAAM,SAAmB,CAAC;AAE1B,aAAW,QAAQ,eAAe;AAChC,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":[]}

package/dist/server/auth/index.js

@@ -24,10 +24,10 @@ import {
   verifyOAuthState,
   verifyTotp
 } from "../../chunk-SJIRP73B.js";
+import "../../chunk-ZJQ4O76G.js";
 import {
   generateNonce
 } from "../../chunk-C3ZZ56YZ.js";
-import "../../chunk-ZJQ4O76G.js";
 import "../../chunk-DGUM43GV.js";
 export {
   AuthRequiredError,

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

@@ -4,6 +4,7 @@ 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';
 
 /**
  * core/contracts/route-config.ts

package/dist/server/define/index.js

@@ -9,18 +9,30 @@ import {
   defineWebChannel,
   defineWebSocket,
   defineWebSocketWeb
-} from "../../chunk-6BUUZ2PK.js";
+} from "../../chunk-4EL6OX3P.js";
+import {
+  HEALTH_PATH,
+  READY_PATH,
+  defineHealthRoute,
+  defineReadyRoute,
+  serveReservedRoute
+} from "../../chunk-V3LJN2GS.js";
 import "../../chunk-DGUM43GV.js";
 export {
+  HEALTH_PATH,
+  READY_PATH,
   defineAction,
   defineAgentEndpoint,
   defineAgentTool,
   defineChannel,
+  defineHealthRoute,
   defineMiddleware,
+  defineReadyRoute,
   defineRoute,
   defineTheoPlugin,
   defineWebChannel,
   defineWebSocket,
-  defineWebSocketWeb
+  defineWebSocketWeb,
+  serveReservedRoute
 };
 //# sourceMappingURL=index.js.map

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

@@ -1,8 +1,9 @@
-export { B as BATCH_PATH, a as BatchExecuteFn, b as BatchPathConflictError, c as BatchPayload, d as BatchRequestItem, e as BatchResponse, f as BatchResultItem, C as CookieOptions, g as CorsConfig, h as CorsHandler, i as CorsOrigin, j as CorsWebHandler, k as CustomErrorPages, E as ExecuteActionOptions, l as ExecuteRouteContext, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, m as MiddlewareResult, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, _ as _resetMiddlewareCacheForTests, r as appendCookieToHeaders, s as appendDeleteCookieToHeaders, t as createCorsHandler, u as createCorsWebHandler, v as deleteCookie, w as executeAction, x as executeRoute, y as extractTraceId, z as extractTraceIdFromRequest, A as getCookie, D as getCookieFromRequest, F as handleBatchRequest, I as loadCustomErrorPages, J as matchesOrigin, K as parseCookieHeader, L as parseTraceparent, O as runMiddlewareAndContext, P as sendError, Q as sendJson, R as serializeCookie, U as serveStaticFile, V as setCookie } from '../../index-DWZF8uQD.js';
+export { B as BATCH_PATH, a as BatchExecuteFn, b as BatchPathConflictError, c as BatchPayload, d as BatchRequestItem, e as BatchResponse, f as BatchResultItem, C as CookieOptions, g as CorsConfig, h as CorsHandler, i as CorsOrigin, j as CorsWebHandler, k as CustomErrorPages, E as ExecuteActionOptions, l as ExecuteRouteContext, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, m as MiddlewareResult, N as NotFoundError, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, q as TheoError, _ as _resetMiddlewareCacheForTests, s as appendCookieToHeaders, t as appendDeleteCookieToHeaders, u as createCorsHandler, v as createCorsWebHandler, w as deleteCookie, x as envelopeCodeToStatus, y as executeAction, z as executeRoute, A as extractTraceId, D as extractTraceIdFromRequest, F as fromUnknown, G as getCookie, I as getCookieFromRequest, J as handleBatchRequest, K as handleRequestError, L as handleWebRequestError, P as loadCustomErrorPages, Q as matchesOrigin, R as parseCookieHeader, U as parseTraceparent, W as runMiddlewareAndContext, X as sendError, Y as sendJson, Z as serializeCookie, $ as serveStaticFile, a0 as serverErrorToEnvelope, a1 as setCookie } from '../../index-B40qUSrQ.js';
+import '../../error-envelope-BsNzzAV5.js';
 import 'node:http';
-import '../../job-backend-CgC8Xf33.js';
-import '../../plugin-runner-BGBkzgi0.js';
 import '../../plugin-types-DNJGxr4Z.js';
+import '../../plugin-runner-BGBkzgi0.js';
+import '../../job-backend-CgC8Xf33.js';
 import '../../match-CfbEFRG4.js';
 import 'vite';
 import '../../csrf-BBrEZSBW.js';

package/dist/server/http/index.js

@@ -2,7 +2,7 @@ import {
   MAX_ERROR_HTML_BYTES,
   loadCustomErrorPages,
   serveStaticFile
-} from "../../chunk-3IOFTG3L.js";
+} from "../../chunk-OPLICDUB.js";
 import {
   BATCH_PATH,
   BatchPathConflictError,
@@ -17,17 +17,28 @@ import {
   extractTraceId,
   extractTraceIdFromRequest,
   handleBatchRequest,
+  handleRequestError,
+  handleWebRequestError,
   matchesOrigin,
   parseTraceparent,
   runMiddlewareAndContext,
   sendError,
   sendJson
-} from "../../chunk-3FYJ7R7N.js";
+} from "../../chunk-BB4ISKOB.js";
 import "../../chunk-GY5Q27BJ.js";
-import "../../chunk-Z5IGLBWE.js";
+import "../../chunk-WFNLNIJX.js";
 import "../../chunk-ZEGYW52B.js";
 import "../../chunk-TSLSIRBR.js";
 import "../../chunk-UD3LFGDL.js";
+import {
+  envelopeCodeToStatus
+} from "../../chunk-X32XEJXR.js";
+import {
+  NotFoundError,
+  TheoError,
+  fromUnknown,
+  serverErrorToEnvelope
+} from "../../chunk-UVXB2ER7.js";
 import {
   appendCookieToHeaders,
   appendDeleteCookieToHeaders,
@@ -43,22 +54,28 @@ export {
   BATCH_PATH,
   BatchPathConflictError,
   MAX_ERROR_HTML_BYTES,
+  NotFoundError,
   STRIPPED_HEADERS,
   TRACE_HEADER,
   TRACE_PARENT_HEADER,
+  TheoError,
   _resetMiddlewareCacheForTests,
   appendCookieToHeaders,
   appendDeleteCookieToHeaders,
   createCorsHandler,
   createCorsWebHandler,
   deleteCookie,
+  envelopeCodeToStatus,
   executeAction,
   executeRoute,
   extractTraceId,
   extractTraceIdFromRequest,
+  fromUnknown,
   getCookie,
   getCookieFromRequest,
   handleBatchRequest,
+  handleRequestError,
+  handleWebRequestError,
   loadCustomErrorPages,
   matchesOrigin,
   parseCookieHeader,
@@ -68,6 +85,7 @@ export {
   sendJson,
   serializeCookie,
   serveStaticFile,
+  serverErrorToEnvelope,
   setCookie
 };
 //# sourceMappingURL=index.js.map

package/dist/server/index.d.ts

@@ -1,7 +1,8 @@
 import { RouteConfig } from './define/index.js';
 export { ActionAccept, ActionConfig, AgentEndpointConfig, AgentEndpointHandlerArgs, ChannelHandler, CustomTool, DefineAgentToolSpec, MiddlewareHandler, WebChannelHandler, defineAction, defineAgentEndpoint, defineAgentTool, defineChannel, defineMiddleware, defineRoute, defineTheoPlugin, defineWebChannel } from './define/index.js';
 export { W as WebSocketHandler, a as WebSocketHandlerWeb, b as WebSocketLike, d as defineWebSocket, c as defineWebSocketWeb } from '../define-websocket-CdK94O-D.js';
-export { B as BATCH_PATH, a as BatchExecuteFn, b as BatchPathConflictError, c as BatchPayload, d as BatchRequestItem, e as BatchResponse, f as BatchResultItem, C as CookieOptions, g as CorsConfig, h as CorsHandler, i as CorsOrigin, j as CorsWebHandler, k as CustomErrorPages, E as ExecuteActionOptions, l as ExecuteRouteContext, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, m as MiddlewareResult, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, q as TheoTransformer, _ as _resetMiddlewareCacheForTests, r as appendCookieToHeaders, s as appendDeleteCookieToHeaders, t as createCorsHandler, u as createCorsWebHandler, v as deleteCookie, w as executeAction, x as executeRoute, y as extractTraceId, z as extractTraceIdFromRequest, A as getCookie, D as getCookieFromRequest, F as handleBatchRequest, G as jsonTransformer, I as loadCustomErrorPages, J as matchesOrigin, K as parseCookieHeader, L as parseTraceparent, N as resolveTransformer, O as runMiddlewareAndContext, P as sendError, Q as sendJson, R as serializeCookie, U as serveStaticFile, V as setCookie, W as superjsonTransformer } from '../index-DWZF8uQD.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';
+export { B as BATCH_PATH, a as BatchExecuteFn, b as BatchPathConflictError, c as BatchPayload, d as BatchRequestItem, e as BatchResponse, f as BatchResultItem, C as CookieOptions, g as CorsConfig, h as CorsHandler, i as CorsOrigin, j as CorsWebHandler, k as CustomErrorPages, E as ExecuteActionOptions, l as ExecuteRouteContext, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, m as MiddlewareResult, N as NotFoundError, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, q as TheoError, r as TheoTransformer, _ as _resetMiddlewareCacheForTests, s as appendCookieToHeaders, t as appendDeleteCookieToHeaders, u as createCorsHandler, v as createCorsWebHandler, w as deleteCookie, x as envelopeCodeToStatus, y as executeAction, z as executeRoute, A as extractTraceId, D as extractTraceIdFromRequest, F as fromUnknown, G as getCookie, I as getCookieFromRequest, J as handleBatchRequest, K as handleRequestError, L as handleWebRequestError, O as jsonTransformer, P as loadCustomErrorPages, Q as matchesOrigin, R as parseCookieHeader, U as parseTraceparent, V as resolveTransformer, W as runMiddlewareAndContext, X as sendError, Y as sendJson, Z as serializeCookie, $ as serveStaticFile, a0 as serverErrorToEnvelope, a1 as setCookie, a2 as superjsonTransformer } from '../index-B40qUSrQ.js';
 export { ActionNode, ActionScanError, LoadedManifest, ManifestAction, ManifestRoute, ManifestWebSocket, TheoManifest, WebSocketRouteNode, generateManifest, loadManifest, scanMiddlewares, scanServerActions, scanServerActionsEnriched, scanServerRoutes, scanWebSocketRoutes, writeManifest } from './scan/index.js';
 export { L as LoadModule, S as ServerRouteNode, c as compilePattern, a as createProductionLoader, b as createViteLoader, m as matchRoute } from '../match-CfbEFRG4.js';
 import { T as TheoErrorEnvelope, a as TheoErrorCode, V as ValidationFieldsExt } from '../error-envelope-BsNzzAV5.js';