theokit 0.12.0 → 0.12.1

package/dist/storage-manager-C4jsO0Tp.d.ts

@@ -0,0 +1,89 @@
+import { S as ServerConfig, P as PostgresDatabaseConfig, a as PoolLike, b as StorageConfig, R as RedisServerConfig, c as RedisLike, d as StorageAdapter } from './storage-types-DsDTCPbp.js';
+
+/**
+ * StorageManager — per-process singleton coordinating pluggable storage
+ * adapters (Postgres pools, Redis clients, in-memory adapters).
+ *
+ * Architectural decisions: see ADR-0007 (docs/adr/0007-storage-manager-singleton.md).
+ *
+ * Lifecycle:
+ *   1. `getStorageManager()` returns the singleton (D1).
+ *   2. `configure(storageConfig)` honored once per process (D3). Second call
+ *      warns and is ignored.
+ *   3. `usePostgres(dbName, factory)` / `useRedis(serverName, factory)`
+ *      lazily create + cache (D2). Factory invoked exactly once per name.
+ *   4. `register(adapter)` opts the adapter into the SIGTERM drain (D6).
+ *   5. `dispose()` drains in parallel — adapters + pools + Redis (D5).
+ *      Idempotent. Adapter errors logged + swallowed (do not block shutdown).
+ *
+ * Test seam: `__resetForTests()` resets state. Test files MUST call it from
+ * `beforeEach` to avoid pollution across `it` blocks (EC-3).
+ */
+
+type PostgresFactory = (server: ServerConfig, db: PostgresDatabaseConfig) => PoolLike;
+type RedisFactory = (config: RedisServerConfig) => RedisLike;
+declare class StorageManager {
+    #private;
+    /**
+     * Apply the storage config block from `theo.config.ts`. Second call warns
+     * and is ignored (D3). Reset only via `__resetForTests()`.
+     */
+    configure(config: StorageConfig): void;
+    /**
+     * Generic cache + factory for ANY client (MySQL, Mongo, Turso, DynamoDB, …).
+     * Returns the cached client OR invokes the factory and caches its return.
+     *
+     * EC-1 FIX: cache-hit check uses `Map.has(name)`, NOT `cached !== undefined`.
+     * Factories returning `null` or `undefined` are valid (lazy connect, stubs);
+     * the `!== undefined` check would re-invoke the factory infinitely for
+     * undefined returns AND silently cache `null` cast as `T`.
+     *
+     * EC-2 (documented type hole): `useStorage<A>('x', fA)` followed by
+     * `useStorage<B>('x', fB)` returns the cached A cast as B. Same trade-off
+     * as `Map<string, unknown>` — caller is responsible for using unique names
+     * per type.
+     *
+     * Lifecycle: generic clients are NOT auto-drained by `dispose()`. Call
+     * `manager.register({ name, dispose })` separately to participate.
+     *
+     * Reserved name prefixes (do NOT use): `__pg:`, `__redis:`, `__unstorage:`,
+     * `__db0:` — these are used internally by the typed helpers.
+     */
+    useStorage<T>(name: string, factory: () => T): T;
+    /**
+     * Return a Postgres pool for the named database. Lazy + cached. Factory
+     * invoked exactly once per `dbName` (D2).
+     *
+     * Throws if:
+     *   - manager is disposed
+     *   - `dbName` is not in `config.databases`
+     *   - the referenced server is not in `config.servers` (EC-2: deferred
+     *     cross-field validation surfaces here, not at configure time)
+     */
+    usePostgres(dbName: string, factory: PostgresFactory): PoolLike;
+    /**
+     * Return a Redis client for the named server. Lazy + cached. Factory
+     * invoked exactly once per `serverName`.
+     */
+    useRedis(serverName: string, factory: RedisFactory): RedisLike;
+    /**
+     * Register an adapter for graceful shutdown coordination (D6).
+     *
+     * EC-4: throws if the manager is already disposed — prevents silent
+     * leaks in test seams that reset+reuse the manager.
+     */
+    register(adapter: StorageAdapter): void;
+    /**
+     * Drain in parallel — registered adapters, then PG pools, then Redis
+     * clients. Idempotent (D5). Errors per resource are logged and swallowed
+     * — they do NOT prevent shutdown of the remaining resources.
+     *
+     * Caller must wrap in a timeout if a bound is needed (EC-7: documented).
+     * In production, `start.ts` wraps the whole shutdown sequence in a 25 s
+     * force-exit timer.
+     */
+    dispose(): Promise<void>;
+}
+declare function getStorageManager(): StorageManager;
+
+export { type PostgresFactory as P, type RedisFactory as R, StorageManager as S, getStorageManager as g };

package/dist/storage-types-DsDTCPbp.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Canonical structural types for the StorageManager (ADR-0007).
+ *
+ * `PoolLike` is the minimal pg.Pool subset TheoKit consumes — defined here as
+ * single source of truth (D7). Adapters that need a Postgres pool import this
+ * type instead of duplicating the shape.
+ *
+ * `RedisLike` is the minimal ioredis subset the manager calls during dispose.
+ *
+ * `StorageAdapter` is the lifecycle contract — anything that wants to
+ * participate in the StorageManager drain on SIGTERM implements this.
+ */
+/**
+ * Minimal subset of `pg.Pool` we depend on. Accepting this narrower interface
+ * lets us:
+ *   - test with `pg-mem` (in-memory) without dragging real Postgres into CI
+ *   - swap to any wire-compatible client (postgres.js, slonik, etc.)
+ *
+ * Optional `end()` lets the manager call it during dispose; not required for
+ * pools that handle their own lifecycle (e.g., serverless drivers).
+ */
+interface PoolLike {
+    query<R = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: R[];
+        rowCount?: number | null;
+    }>;
+    /** Optional — manager calls this during dispose(). Pools without end() are silently skipped (EC-5). */
+    end?: () => Promise<void>;
+}
+/**
+ * Minimal subset of ioredis we depend on during graceful shutdown. The full
+ * Redis API is the user's responsibility — manager only needs lifecycle.
+ */
+interface RedisLike {
+    /** Graceful close — drains pending commands. */
+    quit(): Promise<unknown>;
+    /** Hard close — used as fallback if `quit()` rejects. */
+    disconnect(): void;
+}
+/**
+ * Lifecycle contract for any adapter that participates in StorageManager
+ * graceful shutdown. Call `manager.register(this)` from your adapter's
+ * constructor to opt in.
+ *
+ * Errors thrown from `dispose()` are swallowed by the manager (D5/D6 — log +
+ * continue). Do not rely on `dispose()` rejection propagating.
+ */
+interface StorageAdapter {
+    readonly name: string;
+    dispose(): Promise<void>;
+}
+/**
+ * Generic factory signature for `StorageManager.useStorage<T>(name, factory)`.
+ * Useful for typing externally-defined factory functions:
+ *
+ * ```ts
+ * const mongoFactory: GenericFactory<MongoClient> = () => new MongoClient({...})
+ * manager.useStorage('mongo', mongoFactory)
+ * ```
+ */
+type GenericFactory<T> = () => T;
+interface TlsConfig {
+    rejectUnauthorized?: boolean;
+    caCert?: string;
+    clientCert?: string;
+    clientKey?: string;
+}
+interface ServerConfig {
+    host: string;
+    port?: number;
+    user: string;
+    password: string;
+    tls?: TlsConfig;
+}
+interface PostgresDatabaseConfig {
+    /** References a key in `StorageConfig.servers`. */
+    server: string;
+    database: string;
+    pool?: {
+        min?: number;
+        max?: number;
+        connectionTimeoutMillis?: number;
+        idleTimeoutMillis?: number;
+    };
+}
+interface RedisServerConfig extends ServerConfig {
+    db?: number;
+    maxRetriesPerRequest?: number;
+}
+interface StorageConfig {
+    servers?: Record<string, ServerConfig>;
+    databases?: Record<string, PostgresDatabaseConfig>;
+    redis?: Record<string, RedisServerConfig>;
+}
+
+export type { GenericFactory as G, PostgresDatabaseConfig as P, RedisServerConfig as R, ServerConfig as S, TlsConfig as T, PoolLike as a, StorageConfig as b, RedisLike as c, StorageAdapter as d };

package/dist/vite-plugin/index.d.ts

@@ -0,0 +1,115 @@
+import { Plugin } from 'vite';
+import { R as RateLimitConfig } from '../rate-limit-BdNDZ3vt.js';
+import { C as CsrfReadinessStore } from '../csrf-readiness-store-CjIoub3U.js';
+import { S as ServicesConfig } from '../schema-BpH6ivDY.js';
+import 'node:http';
+import '../rate-limit-store-BEJnhWdw.js';
+import 'zod';
+
+/**
+ * T3.1 — Vite integration extension API (`defineTheoIntegration`).
+ *
+ * Build-time extension system (mirrors Astro Integrations). Lets third
+ * parties hook into Theo's Vite lifecycle without forking the plugin.
+ *
+ * Strictly separated from runtime `defineTheoPlugin` (Phase 4) — different
+ * concerns, different surfaces. See ADR D7 in the plan.
+ */
+type HookName = 'theo:config:setup' | 'theo:build:start' | 'theo:build:done' | 'theo:dev:start';
+interface HookContext {
+    addVirtualModule?: (id: string, code: string) => void;
+    addRoute?: (path: string, handler: RouteHandler) => void;
+    [key: string]: unknown;
+}
+type Hook = (ctx: HookContext) => void | Promise<void>;
+type RouteHandler = (request: Request) => Response | Promise<Response>;
+interface TheoIntegration {
+    name: string;
+    hooks: Partial<Record<HookName, Hook>>;
+}
+/**
+ * Identity factory for type-checking against TheoIntegration shape.
+ */
+declare function defineTheoIntegration(integration: TheoIntegration): TheoIntegration;
+declare class IntegrationVirtualModulePrefixError extends Error {
+    constructor(integrationName: string, id: string);
+}
+declare class IntegrationRouteCollisionError extends Error {
+    constructor(integrationName: string, path: string);
+}
+interface IntegrationRegistryOptions {
+    /** Routes already scanned from `server/routes/`. Used to detect collisions. */
+    existingRoutes: string[];
+}
+interface IntegrationRoute {
+    path: string;
+    owner: string;
+}
+interface IntegrationRegistry {
+    registerIntegration(integration: TheoIntegration): void;
+    fire(hookName: HookName, baseCtx: Record<string, unknown>): Promise<void>;
+    addVirtualModule(integrationName: string, id: string, code: string): void;
+    addRoute(integrationName: string, path: string, handler: RouteHandler): void;
+    getVirtualModule(id: string): string | undefined;
+    listVirtualModules(): string[];
+    listRoutes(): IntegrationRoute[];
+    /** Test helper: invoke hook surface directly without firing the lifecycle. */
+    callHook(integrationName: string, hookName: HookName, extraCtx: Partial<HookContext>): Promise<void>;
+}
+declare function createIntegrationRegistry(options: IntegrationRegistryOptions): IntegrationRegistry;
+
+interface TheoPluginOptions {
+    root?: string;
+    rateLimit?: RateLimitConfig;
+    ssr?: boolean;
+    ssrStreaming?: boolean;
+    /**
+     * Wave 2 (T3.1) — polyglot services config. When passed, the
+     * services-typed-client plugin is wired and generates `clients/<name>.ts`
+     * per service with an OpenAPI URL. Empty `{}` → no-op.
+     */
+    services?: ServicesConfig;
+    /**
+     * T4.1 (canvas-ecosystem-refactor / ADR D6) — extra package names appended
+     * to Vite `optimizeDeps.include`. Required when an installed plugin
+     * peer-dep is consumed via a literal `import('<pkg>')` (dynamic specifier)
+     * — Vite cannot trace those without a hint, and the browser receives a
+     * `Failed to resolve module specifier '<pkg>'` error.
+     *
+     * Default targets pre-bundled regardless: `@theokit/ui`, `lucide-react`.
+     *
+     * Example:
+     *   viteOptimizeDeps: ['mermaid']
+     */
+    viteOptimizeDeps?: string[];
+    /**
+     * Optional override for the in-memory CSRF readiness store consumed by
+     * the `/__theo/csrf-readiness` endpoint and the devtools CSRF Readiness
+     * tab. When omitted, the plugin auto-instantiates a default in-process
+     * `CsrfReadinessStore` so the tab works out-of-the-box in dev.
+     *
+     * Override with a custom impl when you need cross-worker telemetry
+     * (e.g., Redis-backed store) or want to silence the tab entirely
+     * (pass an inert store that discards writes).
+     */
+    csrfReadinessStore?: CsrfReadinessStore;
+}
+/**
+ * Async factory companion. Returns `[theoPlugin, ...autoChainedPlugins]`.
+ *
+ * Why this exists alongside the sync `theoPlugin()` factory: Vite does NOT
+ * reliably merge plugins returned from a child plugin's `config()` hook
+ * (verified empirically 2026-05-23 — plugins were silently dropped from
+ * the resolved chain despite being returned correctly). The canonical
+ * Vite pattern for plugin-from-plugin is to return `Plugin[]` from the
+ * plugin factory itself, which Vite flattens into the consumer's
+ * `plugins` array.
+ *
+ * Consumers should prefer `await theoPluginAsync(...)` over `theoPlugin(...)`
+ * when they want @theokit/ui + @tailwindcss/vite auto-chaining. The sync
+ * factory remains for backward compatibility and tests.
+ */
+declare function theoPluginAsync(rootOrOptions?: string | TheoPluginOptions): Promise<Plugin[]>;
+declare function theoPlugin(rootOrOptions?: string | TheoPluginOptions): Plugin;
+
+export { type Hook as IntegrationHook, type HookContext as IntegrationHookContext, type HookName as IntegrationHookName, type IntegrationRegistry, type IntegrationRegistryOptions, type IntegrationRoute, IntegrationRouteCollisionError, type RouteHandler as IntegrationRouteHandler, IntegrationVirtualModulePrefixError, type TheoIntegration, type TheoPluginOptions, createIntegrationRegistry, defineTheoIntegration, theoPlugin, theoPluginAsync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theokit",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "type": "module",
   "sideEffects": false,
   "license": "Apache-2.0",
@@ -105,8 +105,6 @@
     "dist"
   ],
   "dependencies": {
-    "@theokit/agents": "^0.27.0",
-    "@theokit/http": "^0.5.4",
     "@vitejs/plugin-react": "^4.7.0",
     "busboy": "^1.6.0",
     "cac": "^6.7.14",
@@ -120,7 +118,9 @@
     "superjson": "^2.2.6",
     "tsx": "^4.22.4",
     "typescript": "^5.9.3",
-    "vite": "^6.4.3"
+    "vite": "^6.4.3",
+    "@theokit/http": "^0.5.4",
+    "@theokit/agents": "^0.28.0"
   },
   "peerDependencies": {
     "@theokit/sdk": ">=2.9.0",