theokit 0.12.0 → 0.12.1

package/dist/index.d.ts

@@ -0,0 +1,361 @@
+import { z } from 'zod';
+import { T as TheoErrorEnvelope } from './error-envelope-BsNzzAV5.js';
+export { theoPlugin } from './vite-plugin/index.js';
+import 'vite';
+import './rate-limit-BdNDZ3vt.js';
+import 'node:http';
+import './rate-limit-store-BEJnhWdw.js';
+import './csrf-readiness-store-CjIoub3U.js';
+import './schema-BpH6ivDY.js';
+
+/**
+ * G5 T1.3 — formatError hook signature (blueprint ADR D3).
+ *
+ * Type-inferred functional transformer that runs at framework error-boundary
+ * time. Producer-side analog of trpc's `errorFormatter`. The return type is
+ * `TheoErrorEnvelope<TExt>` for arbitrary `TExt` so the inference flows into
+ * `@theo/client` codegen + UI consumers.
+ */
+interface FormatErrorContext {
+    readonly route?: string;
+    readonly action?: string;
+    readonly agentRunId?: string;
+}
+type FormatErrorHook = (envelope: TheoErrorEnvelope, ctx: FormatErrorContext) => TheoErrorEnvelope;
+
+/**
+ * Root `theo.config.ts` schema — composer assembled from the per-concern
+ * primitives re-exported above.
+ *
+ * Embedded blocks that exist ONLY as part of the root config (`agents`,
+ * `ui`, `devtools`, `jobs`, `openapi`) stay inline below. They have no
+ * external consumers; splitting them would create lonely files (M5
+ * smell) without comprehension benefit.
+ */
+declare const theoConfigSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    appDir: z.ZodDefault<z.ZodString>;
+    serverDir: z.ZodDefault<z.ZodString>;
+    distDir: z.ZodDefault<z.ZodString>;
+    agents: z.ZodOptional<z.ZodObject<{
+        maxRegistries: z.ZodDefault<z.ZodNumber>;
+        registry: z.ZodOptional<z.ZodObject<{
+            maxAgents: z.ZodDefault<z.ZodNumber>;
+            idleTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    port: z.ZodDefault<z.ZodNumber>;
+    host: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
+    open: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    strictPort: z.ZodDefault<z.ZodBoolean>;
+    forwardConsole: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        unhandledErrors: z.ZodOptional<z.ZodBoolean>;
+        logLevels: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            error: "error";
+            info: "info";
+            warn: "warn";
+            debug: "debug";
+            log: "log";
+        }>>>;
+    }, z.core.$strip>]>>;
+    warmup: z.ZodOptional<z.ZodObject<{
+        clientFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ssrFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    ssr: z.ZodDefault<z.ZodBoolean>;
+    ssrStreaming: z.ZodDefault<z.ZodBoolean>;
+    rateLimit: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        windowMs: z.ZodNumber;
+        max: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        default: z.ZodOptional<z.ZodObject<{
+            windowMs: z.ZodNumber;
+            max: z.ZodNumber;
+        }, z.core.$strip>>;
+        routes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            windowMs: z.ZodNumber;
+            max: z.ZodNumber;
+        }, z.core.$strip>>>;
+        keyBy: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            ip: "ip";
+            session: "session";
+            user: "user";
+        }>, z.ZodFunction<z.ZodTuple<[z.ZodUnknown], null>, z.ZodString>]>>;
+        cookieName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    upload: z.ZodOptional<z.ZodObject<{
+        maxFileSize: z.ZodDefault<z.ZodNumber>;
+        maxFiles: z.ZodDefault<z.ZodNumber>;
+        maxFieldSize: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    logging: z.ZodOptional<z.ZodObject<{
+        level: z.ZodDefault<z.ZodEnum<{
+            error: "error";
+            info: "info";
+            warn: "warn";
+            debug: "debug";
+            silent: "silent";
+        }>>;
+    }, z.core.$strip>>;
+    security: z.ZodOptional<z.ZodObject<{
+        csrf: z.ZodDefault<z.ZodEnum<{
+            warn: "warn";
+            off: "off";
+            strict: "strict";
+        }>>;
+        headers: z.ZodOptional<z.ZodObject<{
+            csp: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+            cspMode: z.ZodDefault<z.ZodEnum<{
+                enforce: "enforce";
+                "report-only": "report-only";
+                off: "off";
+            }>>;
+            hsts: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+            frameOptions: z.ZodDefault<z.ZodEnum<{
+                DENY: "DENY";
+                SAMEORIGIN: "SAMEORIGIN";
+            }>>;
+            contentTypeOptions: z.ZodDefault<z.ZodLiteral<"nosniff">>;
+            referrerPolicy: z.ZodDefault<z.ZodString>;
+            permissionsPolicy: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+        }, z.core.$strip>>;
+        disallowed: z.ZodOptional<z.ZodObject<{
+            routes: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>]>>;
+            behavior: z.ZodDefault<z.ZodEnum<{
+                warn: "warn";
+                raise: "raise";
+            }>>;
+        }, z.core.$strip>>;
+        cors: z.ZodOptional<z.ZodObject<{
+            origins: z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodString, z.ZodCustom<RegExp, RegExp>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RegExp, RegExp>]>>, z.ZodFunction<z.ZodTuple<[z.ZodString], null>, z.ZodBoolean>]>;
+            methods: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                GET: "GET";
+                HEAD: "HEAD";
+                OPTIONS: "OPTIONS";
+                POST: "POST";
+                PUT: "PUT";
+                PATCH: "PATCH";
+                DELETE: "DELETE";
+            }>>>;
+            allowedHeaders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            exposedHeaders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            credentials: z.ZodDefault<z.ZodBoolean>;
+            maxAge: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    serialization: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        superjson: "superjson";
+    }>>;
+    plugins: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    batching: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        max: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>>;
+    audit: z.ZodOptional<z.ZodObject<{
+        logger: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+    ui: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+        theme: z.ZodOptional<z.ZodEnum<{
+            "violet-forge": "violet-forge";
+            noir: "noir";
+            paper: "paper";
+        }>>;
+        fonts: z.ZodOptional<z.ZodEnum<{
+            bundled: "bundled";
+            cdn: "cdn";
+        }>>;
+    }, z.core.$strip>]>>;
+    cache: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        storage: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"memory">, z.ZodCustom<unknown, unknown>]>>;
+        maxEntries: z.ZodDefault<z.ZodNumber>;
+        defaults: z.ZodDefault<z.ZodObject<{
+            maxAge: z.ZodDefault<z.ZodNumber>;
+            swr: z.ZodOptional<z.ZodNumber>;
+            cacheErrors: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        keyDerivation: z.ZodDefault<z.ZodObject<{
+            excludeQuery: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            sortQuery: z.ZodDefault<z.ZodBoolean>;
+            lowercaseHost: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        routeRules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            maxAge: z.ZodOptional<z.ZodNumber>;
+            swr: z.ZodOptional<z.ZodNumber>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    devtools: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+        position: z.ZodOptional<z.ZodEnum<{
+            "top-left": "top-left";
+            "top-right": "top-right";
+            "bottom-left": "bottom-left";
+            "bottom-right": "bottom-right";
+        }>>;
+        theme: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            system: "system";
+        }>>;
+    }, z.core.$strip>]>>;
+    adapters: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    viteOptimizeDeps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    jobs: z.ZodOptional<z.ZodObject<{
+        backend: z.ZodCustom<unknown, unknown>;
+    }, z.core.$strip>>;
+    storage: z.ZodOptional<z.ZodObject<{
+        servers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            host: z.ZodString;
+            port: z.ZodOptional<z.ZodNumber>;
+            user: z.ZodString;
+            password: z.ZodString;
+            tls: z.ZodOptional<z.ZodObject<{
+                rejectUnauthorized: z.ZodOptional<z.ZodBoolean>;
+                caCert: z.ZodOptional<z.ZodString>;
+                clientCert: z.ZodOptional<z.ZodString>;
+                clientKey: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        databases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            server: z.ZodString;
+            database: z.ZodString;
+            pool: z.ZodOptional<z.ZodObject<{
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+                connectionTimeoutMillis: z.ZodOptional<z.ZodNumber>;
+                idleTimeoutMillis: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        redis: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            host: z.ZodString;
+            port: z.ZodOptional<z.ZodNumber>;
+            user: z.ZodString;
+            password: z.ZodString;
+            tls: z.ZodOptional<z.ZodObject<{
+                rejectUnauthorized: z.ZodOptional<z.ZodBoolean>;
+                caCert: z.ZodOptional<z.ZodString>;
+                clientCert: z.ZodOptional<z.ZodString>;
+                clientKey: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            db: z.ZodOptional<z.ZodNumber>;
+            maxRetriesPerRequest: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    services: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        runtime: z.ZodEnum<{
+            python: "python";
+            node: "node";
+        }>;
+        type: z.ZodOptional<z.ZodEnum<{
+            server: "server";
+            worker: "worker";
+        }>>;
+        port: z.ZodNumber;
+        proxy: z.ZodString;
+        dev: z.ZodString;
+        build: z.ZodOptional<z.ZodString>;
+        start: z.ZodString;
+        openapi: z.ZodOptional<z.ZodURL>;
+        healthcheck: z.ZodDefault<z.ZodString>;
+        cors: z.ZodDefault<z.ZodBoolean>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        passSetCookie: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    openapi: z.ZodOptional<z.ZodObject<{
+        servers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            url: z.ZodURL;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        specVersion: z.ZodDefault<z.ZodEnum<{
+            "3.1.0": "3.1.0";
+            "3.0.3": "3.0.3";
+        }>>;
+        title: z.ZodDefault<z.ZodString>;
+        version: z.ZodDefault<z.ZodString>;
+        outDir: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    formatError: z.ZodOptional<z.ZodCustom<FormatErrorHook, FormatErrorHook>>;
+}, z.core.$strip>;
+type TheoConfig = z.infer<typeof theoConfigSchema>;
+
+/**
+ * Define Theo framework configuration.
+ * Identity function — provides type inference for theo.config.ts.
+ * Runtime validation happens in loadConfig(), not here.
+ */
+declare function defineConfig(config: Partial<TheoConfig>): Partial<TheoConfig>;
+
+/**
+ * Deep merges two plain objects. Override values take precedence.
+ * Arrays are replaced (not concatenated).
+ * Protects against prototype pollution (EC-4).
+ */
+declare function deepMerge(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown>;
+declare function loadConfig(dir: string): Promise<TheoConfig>;
+
+interface ConfigIssue {
+    field: string;
+    message: string;
+}
+declare class TheoConfigError extends Error {
+    readonly issues: ConfigIssue[];
+    readonly configPath: string;
+    constructor(issues: ConfigIssue[], configPath: string);
+}
+
+declare function validateProjectStructure(rootDir: string): void;
+
+declare class TheoProjectError extends Error {
+    readonly errors: string[];
+    readonly rootDir: string;
+    constructor(errors: string[], rootDir: string);
+}
+
+/**
+ * core/contracts/route-node.ts
+ *
+ * Canonical home for `RouteNode` (file-system route tree shape) — consumed
+ * by `router/`, `vite-plugin/`, AND `devtools/server-side/`. Moved here in
+ * T2.2 of architecture-cleanup so `devtools → core/contracts` is the legal
+ * edge (replacing the prior `devtools → router` violation).
+ */
+/**
+ * Dynamic-segment metadata for a file-system route node.
+ * Set when the directory name is `[param]` (single segment) or `[...slug]`
+ * (catch-all). `generate.ts` turns this into react-router `:param` / `*` syntax.
+ */
+interface RouteNodeDynamic {
+    /** The param name (`slug` for `[slug]` / `[...slug]`). Always `[A-Za-z0-9_]+`. */
+    paramName: string;
+    /** True for catch-all `[...slug]`, false for single dynamic `[slug]`. */
+    catchAll: boolean;
+}
+interface RouteNode {
+    segment: string;
+    path: string;
+    page?: string;
+    layout?: string;
+    error?: string;
+    loading?: string;
+    notFound?: string;
+    /** Present only for dynamic / catch-all segments (additive — static routes omit it). */
+    dynamic?: RouteNodeDynamic;
+    children: RouteNode[];
+}
+
+declare function isRouteFile(filename: string): boolean;
+
+declare function scanRoutes(appDir: string): RouteNode;
+
+declare function generateRouteManifest(tree: RouteNode): string;
+
+interface EntryClientOptions {
+    theoUi?: {
+        fonts?: 'bundled' | 'cdn';
+        theme?: 'violet-forge' | 'noir' | 'paper';
+    };
+}
+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 };

package/dist/job-backend-CgC8Xf33.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Neutral `JobBackend` interface per ADR-0002.
+ *
+ * Implementations ship in core:
+ *   - `InMemoryJobBackend` (T2.2) — dev + tests; no external deps
+ *   - `PostgresJobBackend` (T3.1) — production; requires `pg` peer dep
+ *
+ * Community packages (`@theokit/jobs-redis`, `@theokit/jobs-sqs`, etc.)
+ * implement this same interface to plug in alternate substrates without
+ * modifying TheoKit core.
+ */
+interface JobEnqueueInput {
+    /** The job name (matches a `defineJob` declaration). */
+    name: string;
+    /** Validated input (already passed through Zod or equivalent at the queue-client layer). */
+    input: unknown;
+    /** Optional idempotency key for at-most-once dispatch within TTL. */
+    idempotencyKey?: string;
+    /** Optional delay before the job becomes available for dispatch. */
+    delaySeconds?: number;
+    /** W3C Trace Context propagation per ADR/R0.5.9. */
+    traceparent?: string;
+    /** Maximum dispatch attempts (read from JobDefinition by the queue client). */
+    maxAttempts?: number;
+}
+interface JobLease {
+    readonly jobId: string;
+    readonly name: string;
+    readonly input: unknown;
+    readonly attempts: number;
+    readonly maxAttempts: number;
+    readonly traceparent?: string;
+    readonly lockExpiresAt: Date;
+}
+interface JobBackend {
+    /** Human-readable name for logging (e.g., "memory", "postgres"). */
+    readonly name: string;
+    /** Persist a job for later dispatch. Returns the generated jobId. */
+    enqueue(input: JobEnqueueInput): Promise<{
+        jobId: string;
+    }>;
+    /** Worker loop polls for the next available leases. */
+    dequeue(opts: {
+        batchSize?: number;
+        lockSeconds?: number;
+    }): Promise<JobLease[]>;
+    /** Mark a job complete (success). */
+    ack(jobId: string): Promise<void>;
+    /** Mark a job failed; backend decides retry vs DLQ via attempts. */
+    nack(jobId: string, opts: {
+        error: string;
+        nonRetryable?: boolean;
+    }): Promise<void>;
+    /** Optional: return existing jobId if `key` was enqueued within `ttlSeconds`. */
+    idempotency?(key: string, ttlSeconds: number): Promise<{
+        jobId: string;
+    } | null>;
+}
+/**
+ * Thrown from a job handler to opt out of retry policy. The backend MUST
+ * nack with `nonRetryable: true` and permanently remove the job.
+ */
+declare class NonRetryableError extends Error {
+    readonly code = "NON_RETRYABLE";
+    constructor(message: string);
+}
+
+export { type JobBackend as J, NonRetryableError as N, type JobEnqueueInput as a, type JobLease as b };

package/dist/match-CfbEFRG4.d.ts

@@ -0,0 +1,26 @@
+import { ViteDevServer } from 'vite';
+
+type LoadModule = (path: string) => Promise<Record<string, unknown>>;
+declare function createViteLoader(vite: ViteDevServer): LoadModule;
+declare function createProductionLoader(): LoadModule;
+
+interface ServerRouteNode {
+    filePath: string;
+    routePath: string;
+    paramNames: string[];
+    pattern: RegExp;
+    /** HTTP methods (uppercase) the route file exports. Optional for backward
+     * compatibility with manifests generated before G1. Empty array means the
+     * file has no HTTP exports (util-only); undefined means "not detected". */
+    methods?: string[];
+}
+declare function compilePattern(routePath: string): {
+    pattern: RegExp;
+    paramNames: string[];
+};
+declare function matchRoute(url: string, routes: ServerRouteNode[]): {
+    route: ServerRouteNode;
+    params: Record<string, string>;
+} | null;
+
+export { type LoadModule as L, type ServerRouteNode as S, createProductionLoader as a, createViteLoader as b, compilePattern as c, matchRoute as m };

package/dist/plugin-runner-BGBkzgi0.d.ts

@@ -0,0 +1,95 @@
+import { T as TheoPlugin, a as TheoApp, P as PluginContext, H as HookResult, R as RunHookOptions } from './plugin-types-DNJGxr4Z.js';
+
+declare class DuplicatePluginError extends Error {
+    constructor(name: string);
+}
+/**
+ * @deprecated Per T3.1 (C1 plugin scope encapsulation) — duplicate decoration
+ * keys across sibling plugins are now PERMITTED because each plugin gets its
+ * own child scope via `Object.create(parent)` (Fastify pattern, ADR-0028
+ * blueprint D1). This class is retained for one minor cycle so consumers who
+ * `instanceof DuplicateDecorationError` continue to compile; the constructor
+ * is no longer reachable from `PluginRunner.register()`. Removal scheduled
+ * for 0.x+2 per CHANGELOG.
+ */
+declare class DuplicateDecorationError extends Error {
+    constructor(key: string, existingPlugin: string, newPlugin: string);
+}
+declare class PluginRunner {
+    private plugins;
+    private pluginScopes;
+    private onRequestHooks;
+    private preHandlerHooks;
+    private onResponseHooks;
+    private onErrorHooks;
+    /**
+     * Parent app — proto-chain root for all child scopes. Has its OWN empty
+     * decorations map (parent never receives `decorateRequest` calls under
+     * the T3.1 contract; only child scopes do).
+     */
+    private parentDecorations;
+    private parentApp;
+    has(name: string): boolean;
+    /**
+     * Per T3.1 (C1 plugin scope encapsulation):
+     * 1. Reserve the plugin name (still rejects duplicates).
+     * 2. Build a CHILD TheoApp via `Object.create(parentApp)` — Fastify
+     *    `plugin-override.js:38` pattern. The child's own `decorateRequest`
+     *    populates per-scope `decorations`; the child's `addHook` still
+     *    forwards into the shared hook lists (hooks ARE process-global —
+     *    only decorations are scoped, mirroring Fastify's decoration vs
+     *    hook semantics).
+     * 3. Invoke `plugin.register(childApp)`.
+     *
+     * Cross-plugin decoration-key collisions are PERMITTED (per blueprint
+     * D1). The legacy `DuplicateDecorationError` is no longer thrown.
+     */
+    register(plugin: TheoPlugin): Promise<void>;
+    /**
+     * Build the parent app facade. Hooks forward to shared lists.
+     * `decorateRequest` writes into the parent decorations map — used only
+     * if a future consumer registers a non-plugin "app-level" decoration
+     * directly. T3.1 contract: plugins decorate ONLY through child scopes.
+     */
+    private buildParentAppFacade;
+    /**
+     * Build a child scope via `Object.create(parentApp)` so the child
+     * inherits the parent's facade methods through the prototype chain.
+     * Then override `decorateRequest` on the child instance so writes
+     * land in the per-scope `decorations` map (parent is NOT mutated).
+     */
+    private buildPluginScope;
+    private routeHookByName;
+    /**
+     * Apply ALL plugin scopes' decorations into the request ctx. Per T3.1,
+     * sibling plugins MAY decorate the same key — last-writer-wins at apply
+     * time (ordering = registration order). This keeps the legacy
+     * `ctx.<key>` flat surface working for consumers that already aggregate
+     * decorations into a single bag.
+     */
+    applyDecorations(ctx: Record<string, unknown>): void;
+    /**
+     * Apply ONLY one plugin's scoped decorations into `target`. Used by
+     * the T1.1 RED-3 test (sibling isolation proof) and by future scope-aware
+     * dispatch paths. Throws if the plugin name isn't registered.
+     */
+    applyScopedDecorations(pluginName: string, target: Record<string, unknown>): void;
+    /** T1.1 RED-1/RED-4 introspection: returns the child TheoApp built for `pluginName`. */
+    getPluginScope(pluginName: string): TheoApp;
+    /** T1.1 RED-4: returns the parent TheoApp (root of every child's proto chain). */
+    getParentApp(): TheoApp;
+    /** T1.1 RED-2: returns the parent's decorations map (NEVER touched by plugin decorate calls under T3.1 contract). */
+    getParentDecorations(): Map<string, unknown>;
+    runOnRequest(ctx: PluginContext): Promise<HookResult>;
+    runPreHandler(ctx: PluginContext): Promise<HookResult>;
+    runOnResponse(ctx: PluginContext, options?: RunHookOptions): Promise<HookResult>;
+    /**
+     * Run all onError hooks. Swallows errors thrown inside hooks themselves to
+     * prevent recursion (an error in an error handler must not trigger onError
+     * again).
+     */
+    runOnError(ctx: PluginContext, error: unknown): Promise<HookResult>;
+    private runHookList;
+}
+
+export { DuplicateDecorationError as D, PluginRunner as P, DuplicatePluginError as a };

package/dist/plugin-types-DNJGxr4Z.d.ts

@@ -0,0 +1,79 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+interface PluginContext {
+    request: IncomingMessage;
+    response: ServerResponse;
+    ctx: Record<string, unknown>;
+    requestId: string;
+}
+interface PluginErrorContext extends PluginContext {
+    error: unknown;
+}
+interface RunHookOptions {
+    inErrorPath?: boolean;
+}
+interface HookResult {
+    shortCircuited: boolean;
+}
+type OnRequestHook = (ctx: PluginContext) => void | Promise<void>;
+type PreHandlerHook = (ctx: PluginContext) => void | Promise<void>;
+type OnResponseHook = (ctx: PluginContext) => void | Promise<void>;
+type OnErrorHook = (ctx: PluginErrorContext) => void | Promise<void>;
+type HookName = 'onRequest' | 'preHandler' | 'onResponse' | 'onError';
+type HookByName<K extends HookName> = K extends 'onError' ? OnErrorHook : K extends 'onRequest' ? OnRequestHook : K extends 'preHandler' ? PreHandlerHook : K extends 'onResponse' ? OnResponseHook : never;
+interface TheoApp {
+    addHook<K extends HookName>(name: K, fn: HookByName<K>): void;
+    decorateRequest<T>(key: string, value: T): void;
+}
+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).
+ *
+ * - `request` — the incoming Web Request (read-only at the runtime level;
+ *   plugins can call `request.headers.get()`, `request.clone()`, etc.).
+ * - `responseHeaders` — a mutable `Headers` instance the runtime threads
+ *   through the hook chain. Plugins append (e.g., CORS, Set-Cookie); the
+ *   final Response composes these.
+ * - `response` — set to the handler's Response AFTER the handler returns.
+ *   Available during `onResponse` / `onError`. `undefined` during
+ *   `onRequest` / `preHandler` (which fire before the handler runs).
+ * - `ctx` / `requestId` — same semantics as the IncomingMessage path.
+ */
+interface WebPluginContext {
+    request: Request;
+    responseHeaders: Headers;
+    response?: Response;
+    ctx: Record<string, unknown>;
+    requestId: string;
+}
+interface WebPluginErrorContext extends WebPluginContext {
+    error: unknown;
+}
+type WebOnRequestHook = (ctx: WebPluginContext) => void | Promise<void>;
+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 };