theokit 0.12.0 → 0.13.0

package/dist/{openapi-VR6AFBLJ.js → openapi-FHY6HC6I.js}

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 import "tsx/esm";
+import {
+  emitOpenApi,
+  loadRoutesForOpenApi
+} from "./chunk-JAIKGP3Q.js";
 import {
   loadConfig
 } from "./chunk-7YZHAQU7.js";
 import "./chunk-YJAUJXZS.js";
 import "./chunk-45C3WUQ7.js";
-import {
-  emitOpenApi,
-  loadRoutesForOpenApi
-} from "./chunk-JAIKGP3Q.js";
 import {
   generateManifest
-} from "./chunk-3LVRAGAZ.js";
-import "./chunk-6FYD34NX.js";
+} from "./chunk-F4YUPDJ2.js";
+import "./chunk-BQDGES7C.js";
 
 // src/cli/commands/openapi.ts
 import { mkdtempSync, rmSync } from "fs";
@@ -79,4 +79,4 @@ function emitOpenApiInMemory(manifest, config) {
 export {
   openapiCommand
 };
-//# sourceMappingURL=openapi-VR6AFBLJ.js.map
+//# sourceMappingURL=openapi-FHY6HC6I.js.map

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 };

package/dist/rate-limit-BdNDZ3vt.d.ts

@@ -0,0 +1,58 @@
+import { IncomingMessage } from 'node:http';
+import { R as RateLimitStore } from './rate-limit-store-BEJnhWdw.js';
+
+/**
+ * Rate limit configuration — basic single-bucket shape. Per ADR D2, the
+ * per-route + per-user variant is layered on top via T2.2; this base
+ * struct is the smallest unit.
+ */
+interface RateLimitConfig {
+    windowMs: number;
+    max: number;
+}
+interface RateLimitResult {
+    limited: boolean;
+    headers: Record<string, string>;
+}
+/**
+ * Create a rate limiter that consumes a pluggable `RateLimitStore`.
+ *
+ * Backwards-compatible signature: callers passing only `config` get the
+ * default `InMemoryStore`. Distributed deployments pass a Redis adapter
+ * (or any other `RateLimitStore` implementation) via `opts.store`.
+ *
+ * T2.1: synchronous return for back-compat with the current
+ * `api-middleware.ts` integration point. The async store contract is
+ * exercised lazily — we use a sync fast-path against the in-memory store
+ * (single-thread JS makes this safe). External stores remain async and
+ * would require a different async wrapper at the middleware layer.
+ */
+declare function createRateLimiter(config: RateLimitConfig, opts?: {
+    store?: RateLimitStore;
+}): (req: IncomingMessage) => RateLimitResult;
+/**
+ * T5a.2 Phase D slice 2/3 — Web-Standards single-bucket rate limiter.
+ *
+ * Mirror of `createRateLimiter(config, opts)` returning a checker that
+ * accepts `(clientIp: string)` instead of `(req: IncomingMessage)`. Web
+ * `Request` has no `req.socket.remoteAddress` — the IP is resolved by
+ * the caller per-runtime (Node adapter from socket; CF Workers from
+ * `cf-connecting-ip`; etc., same convention as Phase D slice 1/3's
+ * `DeriveKeyRequestContext.clientIp`).
+ *
+ * Same `RateLimitConfig`, same `InMemoryStore` default, same async
+ * store rejection (use a dedicated async middleware for external stores).
+ * Same `RateLimitResult` return shape.
+ *
+ * **Signature difference from `createRateLimiter`:** this Web factory's
+ * checker takes a raw IP string instead of a Request object. The IP is
+ * the ONLY input the bucket needs; passing a Request object would force
+ * the caller to populate `request.headers.get('x-forwarded-for')` or
+ * similar without giving us any safer extraction. KISS — accept the IP
+ * directly, document the per-runtime resolution at the adapter boundary.
+ */
+declare function createRateLimiterWeb(config: RateLimitConfig, opts?: {
+    store?: RateLimitStore;
+}): (clientIp: string) => RateLimitResult;
+
+export { type RateLimitConfig as R, type RateLimitResult as a, createRateLimiterWeb as b, createRateLimiter as c };

package/dist/rate-limit-store-BEJnhWdw.d.ts

@@ -0,0 +1,72 @@
+/**
+ * T2.1 — RateLimitStore interface.
+ *
+ * Pluggable backend for the rate limiter. The default `InMemoryStore`
+ * preserves current single-instance behavior. Multi-instance deployments
+ * (TheoCloud canary, K8s replicas) opt in to a distributed adapter
+ * (Redis, Cloudflare KV) without bloating single-instance apps.
+ *
+ * Contract per ADR D1:
+ *   - `incr` is atomic — concurrent calls for the same key both observe
+ *     the same `resetAt` and increment count by 1.
+ *   - `get` returns `null` for expired entries (not just absent — checks
+ *     `now > resetAt`).
+ *   - `reset` removes the key entirely; next `incr` creates fresh.
+ *
+ * Async signature is honest about Redis adapters even though in-memory
+ * implementation is synchronous. Callers MUST await.
+ */
+interface RateLimitState {
+    /** Number of requests counted in the current window. */
+    count: number;
+    /** Absolute timestamp (ms since epoch) when this window expires. */
+    resetAt: number;
+}
+interface RateLimitStore {
+    /**
+     * Atomic increment-and-get. If the key is missing OR the previous
+     * window expired (`now >= resetAt`), create with `count=1, resetAt=now+windowMs`.
+     * Otherwise increment count by 1, preserving the original resetAt.
+     */
+    incr(key: string, windowMs: number): Promise<RateLimitState>;
+    /** Read current state. Returns `null` for missing or expired entries. */
+    get(key: string): Promise<RateLimitState | null>;
+    /** Remove a key. Used by login throttling on success (T6.1). */
+    reset(key: string): Promise<void>;
+}
+/**
+ * Default in-memory store. Backed by `Map<string, RateLimitState>`.
+ *
+ * GC: every 1000 `incr` calls, expired entries are removed. Pathological
+ * key explosion is bounded by `MAX_ENTRIES` (LRU-evict oldest insertion).
+ *
+ * Single-thread by virtue of Node's event loop — `incr` is atomic at the
+ * JavaScript level (no preemption between Map.get and Map.set).
+ */
+declare class InMemoryStore implements RateLimitStore {
+    private store;
+    /** Bound the map to prevent unbounded growth from pathological inputs. */
+    static readonly MAX_ENTRIES = 100000;
+    /** GC sweep interval, milliseconds. */
+    static readonly GC_INTERVAL_MS = 30000;
+    private gcTimer;
+    constructor();
+    /**
+     * Synchronous fast-path used by the legacy sync `createRateLimiter`
+     * surface (`api-middleware.ts` is sync). The async `incr` delegates to
+     * this for in-memory; external adapters override `incr` directly.
+     */
+    incrSync(key: string, windowMs: number): RateLimitState;
+    /** Sweep expired entries. Called by the GC timer; safe to call manually. */
+    sweepExpired(): void;
+    /**
+     * Stop the GC timer. Call from tests or when discarding the store. After
+     * `dispose`, the store still works but no longer auto-sweeps.
+     */
+    dispose(): void;
+    incr(key: string, windowMs: number): Promise<RateLimitState>;
+    get(key: string): Promise<RateLimitState | null>;
+    reset(key: string): Promise<void>;
+}
+
+export { InMemoryStore as I, type RateLimitStore as R, type RateLimitState as a };

package/dist/react-query/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * T5.3 — React Query adapter primitives.
+ *
+ * Exposes:
+ *  - `stableQueryKey(path, options)` — produces a deterministic queryKey
+ *    that is equal across calls when the logical content of query/body is
+ *    equal, regardless of property order or inline-object identity. Solves
+ *    EC-10 (inline-object → infinite refetch).
+ *  - `buildUseTheoQueryConfig(path, options, fetcher)` — produces the
+ *    `{ queryKey, queryFn }` pair that consumers pass to `useQuery` from
+ *    `@tanstack/react-query`.
+ *
+ * The canonical implementation lives here in `theokit/client`. The
+ * dedicated subpath `theokit/react-query` re-exports this surface so
+ * consumers who only need the React Query bridge can import from a
+ * clearly named entry point — same shape as `theokit/server`,
+ * `theokit/vite-plugin`, etc. No separate npm package.
+ */
+interface FetchOptionsLike {
+    query?: unknown;
+    body?: unknown;
+    params?: unknown;
+}
+type QueryKey = readonly unknown[];
+declare function stableQueryKey(path: string, options: FetchOptionsLike): QueryKey;
+type Fetcher<TResult = unknown> = (path: string, options: FetchOptionsLike) => Promise<TResult>;
+interface UseTheoQueryConfig<TResult = unknown> {
+    queryKey: QueryKey;
+    queryFn: () => Promise<TResult>;
+}
+declare function buildUseTheoQueryConfig<TResult = unknown>(path: string, options: FetchOptionsLike, fetcher: Fetcher<TResult>): UseTheoQueryConfig<TResult>;
+
+export { type FetchOptionsLike, type Fetcher, type Fetcher as FetcherFn, type QueryKey, type UseTheoQueryConfig, type UseTheoQueryConfig as UseTheoQueryInternals, buildUseTheoQueryConfig, buildUseTheoQueryConfig as buildUseTheoQueryInternals, stableQueryKey };

package/dist/{registry-Q2TZQLUH.js → registry-34LL7NF4.js}

@@ -21,4 +21,4 @@ export {
   adapterRegistry,
   resolveAdapter
 };
-//# sourceMappingURL=registry-Q2TZQLUH.js.map
+//# sourceMappingURL=registry-34LL7NF4.js.map

package/dist/{routes-LRYOIIAI.js → routes-EW7TP7NJ.js}

@@ -12,7 +12,7 @@ import {
   scanServerActions,
   scanServerRoutes,
   scanWebSocketRoutes
-} from "./chunk-6FYD34NX.js";
+} from "./chunk-BQDGES7C.js";
 
 // src/cli/commands/routes.ts
 import { resolve, relative } from "path";
@@ -60,4 +60,4 @@ async function routesCommand() {
 export {
   routesCommand
 };
-//# sourceMappingURL=routes-LRYOIIAI.js.map
+//# sourceMappingURL=routes-EW7TP7NJ.js.map

package/dist/schema-BpH6ivDY.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+
+/**
+ * Wave 2 — Polyglot Services Orchestration (T1.1).
+ *
+ * Declarative `services: {}` primitive for `theo.config.ts`. Each entry
+ * declares an external sidecar process (Python FastAPI / Node Hono) that
+ * boots alongside the TheoKit TS app. Empty `services: {}` is the default
+ * and preserves Wave 1 behavior (no impact on TS-only apps).
+ *
+ * See ADRs 0012-0015 + plan: docs/plans/wave-2-polyglot-services-plan.md
+ */
+
+/**
+ * Single service definition. All commands run from `services/<name>/` cwd.
+ *
+ * EC-4 fix: `proxy` regex requires NON-EMPTY path after `/` (the `+` quantifier)
+ * to reject `/` which would catch-all and conflict with TheoKit's own routing.
+ */
+declare const ServiceDefinitionSchema: 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>;
+type ServiceDefinition = z.infer<typeof ServiceDefinitionSchema>;
+type ServicesConfig = Record<string, ServiceDefinition>;
+/**
+ * Full services config schema with cross-service refines.
+ *
+ * EC-1 fix: detect duplicate ports across services.
+ * EC-13: empty `dependsOn: []` accepted as no-deps.
+ * Self-dep, missing-ref, and cycles rejected via topological check.
+ */
+declare const servicesConfigSchema: 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>>>;
+type ServicesConfigInput = z.input<typeof servicesConfigSchema>;
+type ServicesConfigOutput = z.output<typeof servicesConfigSchema>;
+
+export type { ServicesConfig as S, ServiceDefinition as a, ServicesConfigInput as b, ServicesConfigOutput as c };