@soederpop/luca 0.1.1 → 0.1.3

package/dist/selector.d.ts

@@ -0,0 +1,130 @@
+import { Helper } from './helper.js';
+import type { Container, ContainerContext } from './container.js';
+import { Registry } from './registry.js';
+import { SelectorStateSchema, SelectorOptionsSchema, type SelectorRunResult } from './schemas/base.js';
+import { z } from 'zod';
+export type { SelectorRunResult };
+export type SelectorState = z.infer<typeof SelectorStateSchema>;
+export type SelectorOptions = z.infer<typeof SelectorOptionsSchema>;
+export interface AvailableSelectors {
+}
+export type SelectorFactory = <T extends keyof AvailableSelectors>(key: T, options?: ConstructorParameters<AvailableSelectors[T]>[0]) => NonNullable<InstanceType<AvailableSelectors[T]>>;
+export interface SelectorsInterface {
+    selectors: SelectorsRegistry;
+    select: SelectorFactory;
+}
+/**
+ * Type helper for module-augmentation of AvailableSelectors when using the
+ * module-based pattern.
+ *
+ * @example
+ * ```typescript
+ * declare module '@soederpop/luca' {
+ *   interface AvailableSelectors {
+ *     packageInfo: SimpleSelector<typeof argsSchema>
+ *   }
+ * }
+ * ```
+ */
+export type SimpleSelector<Schema extends z.ZodType = z.ZodType> = typeof Selector & {
+    argsSchema: Schema;
+};
+/**
+ * A Selector is a helper that returns data. Where Commands perform actions,
+ * Selectors query and return structured results with built-in caching.
+ *
+ * Module authors export a `run(args, context)` function that returns data.
+ * The `select()` dispatch method wraps `run()` with cache check/store and
+ * returns `{ data, cached, cacheKey }`.
+ *
+ * Caching is on by default and keyed by `hashObject({ selectorName, args, gitSha })`.
+ * Export a `cacheKey(args, context)` function to customize, or set `cacheable = false`
+ * to disable.
+ *
+ * @example
+ * ```typescript
+ * // selectors/package-info.ts
+ * export const description = 'Returns parsed package.json data'
+ * export const argsSchema = z.object({ field: z.string().optional() })
+ *
+ * export function cacheKey(args, context) {
+ *   return context.container.git.sha
+ * }
+ *
+ * export async function run(args, context) {
+ *   const manifest = context.container.manifest
+ *   return args.field ? manifest[args.field] : manifest
+ * }
+ * ```
+ */
+export declare class Selector<T extends SelectorState = SelectorState, K extends SelectorOptions = SelectorOptions> extends Helper<T, K> {
+    static shortcut: string;
+    static description: string;
+    static stateSchema: z.ZodObject<{
+        running: z.ZodDefault<z.ZodBoolean>;
+        lastRanAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        dispatchSource: z.ZodDefault<z.ZodEnum<{
+            cli: "cli";
+            headless: "headless";
+            mcp: "mcp";
+            rpc: "rpc";
+        }>>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        started: z.ZodTuple<[], null>;
+        completed: z.ZodTuple<[z.ZodAny], null>;
+        failed: z.ZodTuple<[z.ZodAny], null>;
+    }, z.core.$strip>;
+    static selectorDescription: string;
+    static argsSchema: z.ZodType;
+    static cacheable: boolean;
+    /** Self-register a Selector subclass from a static initialization block. */
+    static register: (SubClass: typeof Selector, id?: string) => typeof Selector;
+    get initialState(): T;
+    /**
+     * The user-defined selector payload. Override this in module-based selectors
+     * by exporting a `run` function.
+     *
+     * Receives validated args and the container context. Must return data.
+     */
+    run(_args: any, _context: ContainerContext): Promise<any>;
+    /**
+     * Compute the cache key for a given set of args.
+     * Override by exporting a `cacheKey(args, context)` function in the module.
+     *
+     * Default: hashObject({ selectorName, args, gitSha })
+     */
+    resolveCacheKey(args: any, _context: ContainerContext): string;
+    /**
+     * The public dispatch method. Checks cache, calls run(), stores result.
+     *
+     * @returns `{ data, cached, cacheKey }` — the result and cache metadata
+     */
+    select(args?: Record<string, any>): Promise<SelectorRunResult>;
+    /** Lazily access diskCache. */
+    private _getCache;
+    static attach(container: Container<any> & SelectorsInterface): Container<any, any> & SelectorsInterface;
+}
+export declare class SelectorsRegistry extends Registry<Selector<any>> {
+    scope: string;
+    baseClass: any;
+    /**
+     * Discover and register selectors from a directory.
+     * Detection order:
+     *   1. Default export is a class extending Selector -> register directly
+     *   2. Module exports a `run` function -> graft as SimpleSelector
+     */
+    discover(options: {
+        directory: string;
+    }): Promise<void>;
+}
+export declare const selectors: SelectorsRegistry;
+export declare const selectorHelperCache: Map<any, any>;
+export { graftModule, isNativeHelperClass } from './graft.js';
+export default Selector;
+//# sourceMappingURL=selector.d.ts.map

package/dist/selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../src/selector.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,89 @@
+import type { NodeContainer } from './node/container.js';
+import { Helper } from './helper.js';
+import { Registry } from './registry.js';
+import { z } from 'zod';
+import { ServerStateSchema, ServerOptionsSchema } from './schemas/base.js';
+export type ServerState = z.infer<typeof ServerStateSchema>;
+export type ServerOptions = z.infer<typeof ServerOptionsSchema>;
+export type StartOptions = {
+    port?: number;
+    host?: string;
+};
+export type ServerFactory = <T extends keyof AvailableServers>(key: T, options?: ConstructorParameters<AvailableServers[T]>[0]) => NonNullable<InstanceType<AvailableServers[T]>>;
+export interface ServersInterface {
+    servers: ServersRegistry;
+    server: ServerFactory;
+}
+export interface AvailableServers {
+}
+export declare class Server<T extends ServerState = ServerState, K extends ServerOptions = ServerOptions> extends Helper<T, K> {
+    static stateSchema: z.ZodObject<{
+        port: z.ZodOptional<z.ZodNumber>;
+        listening: z.ZodDefault<z.ZodBoolean>;
+        configured: z.ZodDefault<z.ZodBoolean>;
+        stopped: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodNumber>;
+        host: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+    }, z.core.$strip>;
+    /** Self-register a Server subclass from a static initialization block. */
+    static register: (SubClass: typeof Server, id?: string) => typeof Server;
+    get initialState(): T;
+    get options(): K;
+    static attach(container: NodeContainer & ServersInterface): NodeContainer<import("./node.js").NodeFeatures, {
+        started: boolean;
+        enabledFeatures: string[];
+        registries: string[];
+        factories: string[];
+    }> & ServersInterface;
+    get container(): NodeContainer;
+    /** Async functions passed to `.use()` before `start()` — drained in `start()`. */
+    _pendingPlugins: Promise<void>[];
+    /**
+     * Register a setup function against this server. The function receives the
+     * server instance and can configure it however it likes.
+     *
+     * - If the server hasn't started yet, async return values are queued and
+     *   awaited when `start()` is called.
+     * - If the server is already listening, the function is fire-and-forget.
+     * - Always returns `this` synchronously for chaining.
+     *
+     * @example
+     * ```typescript
+     * server
+     *   .use((s) => s.app.use(cors()))
+     *   .use(async (s) => { await loadRoutes(s) })
+     * await server.start()
+     * ```
+     */
+    use(fn: (server: this) => void | Promise<void>): this;
+    /** Drain all pending `.use()` promises. Subclasses should call this at the top of `start()`. */
+    protected _drainPendingPlugins(): Promise<void>;
+    get isListening(): boolean;
+    get isConfigured(): boolean;
+    get isStopped(): boolean;
+    /** The port this server will bind to. Reads from state first (set by start() or configure()), then constructor options, then defaults to 3000. */
+    get port(): number;
+    stop(): Promise<this>;
+    /**
+     * Start the server. Runtime options override constructor options and update state
+     * so that `server.port` always reflects the actual listening port.
+     *
+     * @param options - Optional runtime overrides for port and host
+     */
+    start(options?: StartOptions): Promise<this>;
+    configure(): Promise<this>;
+}
+export declare class ServersRegistry extends Registry<Server<any>> {
+    scope: string;
+    baseClass: typeof Server;
+}
+export declare const servers: ServersRegistry;
+export declare const helperCache: Map<any, any>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAsB,MAAM,mBAAmB,CAAA;AAE9F,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAC3D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,SAAS,MAAM,gBAAgB,EACvD,GAAG,EAAE,CAAC,EACN,OAAO,CAAC,EAAE,qBAAqB,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KACxD,WAAW,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,aAAa,CAAA;CACtB;AAED,MAAM,WAAW,gBAAgB;CAAG;AAEpC,qBAAa,MAAM,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,CAAC,SAAS,aAAa,GAAG,aAAa,CAAE,SAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAClH,OAAgB,WAAW;;;;;sBAAoB;IAC/C,OAAgB,aAAa;;;;;sBAAsB;IACnD,OAAgB,YAAY;;sBAAqB;IAEjD,0EAA0E;IAC1E,MAAM,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,MAAM,CAAA;IAExE,IAAa,YAAY,IAAK,CAAC,CAO9B;IAED,IAAa,OAAO,IAAK,CAAC,CAMzB;IAED,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,aAAa,GAAG,gBAAgB;;;;;;IA0BzD,IAAa,SAAS,IAAK,aAAa,CAEvC;IAED,kFAAkF;IAClF,eAAe,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAK;IAErC;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAUrD,gGAAgG;cAChF,oBAAoB;IAOpC,IAAI,WAAW,YAEd;IAED,IAAI,YAAY,YAEf;IAED,IAAI,SAAS,YAEZ;IAED,kJAAkJ;IAClJ,IAAI,IAAI,WAEP;IAEK,IAAI;IAUV;;;;;OAKG;IACG,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY;IAgB5B,SAAS;CAWlB;AAED,qBAAa,eAAgB,SAAQ,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/C,KAAK,SAAY;IACjB,SAAS,gBAAS;CAC5B;AAED,eAAO,MAAM,OAAO,iBAAwB,CAAA;AAE5C,eAAO,MAAM,WAAW,eAAY,CAAA"}

package/dist/servers/express.d.ts

@@ -0,0 +1,104 @@
+import express from 'express';
+import type { Express } from 'express';
+import { z } from 'zod';
+import { type StartOptions, Server, type ServerState } from '../server.js';
+import { Endpoint, type EndpointModule } from '../endpoint.js';
+declare module '../server' {
+    interface AvailableServers {
+        express: typeof ExpressServer;
+    }
+}
+export declare const ExpressServerOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    host: z.ZodOptional<z.ZodString>;
+    cors: z.ZodOptional<z.ZodBoolean>;
+    static: z.ZodOptional<z.ZodString>;
+    historyFallback: z.ZodOptional<z.ZodBoolean>;
+    create: z.ZodOptional<z.ZodAny>;
+    beforeStart: z.ZodOptional<z.ZodAny>;
+}, z.core.$strip>;
+export type ExpressServerOptions = z.infer<typeof ExpressServerOptionsSchema>;
+/**
+ * Express.js HTTP server with automatic endpoint mounting, CORS, and SPA history fallback.
+ *
+ * Wraps an Express application with convention-based endpoint discovery. Endpoints
+ * defined as modules are automatically mounted as routes. Supports static file serving,
+ * CORS configuration, and single-page app history fallback out of the box.
+ *
+ * @extends Server
+ *
+ * @example
+ * ```typescript
+ * const server = container.server('express', { cors: true, static: './public' })
+ * await server.start({ port: 3000 })
+ *
+ * // Mount endpoints programmatically
+ * server.mount(myEndpoint)
+ *
+ * // Access the underlying Express app
+ * server.app.get('/health', (req, res) => res.json({ ok: true }))
+ * ```
+ */
+export declare class ExpressServer<T extends ServerState = ServerState, K extends ExpressServerOptions = ExpressServerOptions> extends Server<T, K> {
+    static shortcut: "servers.express";
+    static stateSchema: z.ZodObject<{
+        port: z.ZodOptional<z.ZodNumber>;
+        listening: z.ZodDefault<z.ZodBoolean>;
+        configured: z.ZodDefault<z.ZodBoolean>;
+        stopped: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodNumber>;
+        host: z.ZodOptional<z.ZodString>;
+        cors: z.ZodOptional<z.ZodBoolean>;
+        static: z.ZodOptional<z.ZodString>;
+        historyFallback: z.ZodOptional<z.ZodBoolean>;
+        create: z.ZodOptional<z.ZodAny>;
+        beforeStart: z.ZodOptional<z.ZodAny>;
+    }, z.core.$strip>;
+    _app?: Express;
+    _listener?: any;
+    _mountedEndpoints: Endpoint[];
+    get express(): typeof express;
+    get hooks(): {
+        create: (app: Express, server: Server) => Express;
+        beforeStart: (options: any, server: Server) => any;
+    };
+    get app(): Express;
+    /**
+     * Start the Express HTTP server. A runtime `port` overrides the constructor
+     * option and is written to state so `server.port` always reflects reality.
+     *
+     * @param options - Optional runtime overrides for port and host
+     */
+    start(options?: StartOptions): Promise<this>;
+    stop(): Promise<this>;
+    configure(): Promise<this>;
+    useEndpoint(endpoint: Endpoint): this;
+    useEndpoints(dir: string): Promise<this>;
+    /**
+     * Reload a mounted endpoint by its file path. Re-reads the module through
+     * the helpers VM loader so the next request picks up the new handlers.
+     *
+     * @param filePath - Absolute path to the endpoint file
+     * @returns The reloaded Endpoint, or null if no mounted endpoint matches
+     */
+    reloadEndpoint(filePath: string): Promise<Endpoint | null>;
+    useEndpointModules(modules: EndpointModule[]): Promise<this>;
+    serveOpenAPISpec(options?: {
+        title?: string;
+        version?: string;
+        description?: string;
+    }): this;
+    generateOpenAPISpec(options?: {
+        title?: string;
+        version?: string;
+        description?: string;
+    }): Record<string, any>;
+}
+export default ExpressServer;
+//# sourceMappingURL=express.d.ts.map

package/dist/servers/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/servers/express.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAA;AAC7B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1E,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAsB,MAAM,gBAAgB,CAAA;AAElF,OAAO,QAAQ,WAAW,CAAC;IACzB,UAAU,gBAAgB;QACxB,OAAO,EAAE,OAAO,aAAa,CAAA;KAC9B;CACF;AAED,eAAO,MAAM,0BAA0B;;;;;;;;;;iBAMrC,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAI7E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,CAAC,SAAS,oBAAoB,GAAG,oBAAoB,CAAE,SAAQ,MAAM,CAAC,CAAC,EAAC,CAAC,CAAC;IACtI,OAAgB,QAAQ,EAAG,iBAAiB,CAAS;IACrD,OAAgB,WAAW;;;;;sBAAoB;IAC/C,OAAgB,aAAa;;;;;;;;;;sBAA6B;IAI1D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,GAAG,CAAA;IACf,iBAAiB,EAAE,QAAQ,EAAE,CAAK;IAElC,IAAI,OAAO,IAAI,OAAO,OAAO,CAE5B;IAED,IAAI,KAAK,IAAI;QAAE,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;QAAC,WAAW,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,KAAK,GAAG,CAAA;KAAE,CAOrH;IAED,IAAI,GAAG,IAAI,OAAO,CAuBjB;IAED;;;;;OAKG;IACY,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BrB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAKzC,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAM/B,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC9C;;;;;;OAMG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAW1D,kBAAkB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBlE,gBAAgB,CAAC,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI;IAQhG,mBAAmB,CAAC,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAkBrH;AAED,eAAe,aAAa,CAAA"}

package/dist/servers/mcp.d.ts

@@ -0,0 +1,201 @@
+import type { NodeContainer } from '../node/container.js';
+import { z } from 'zod';
+import { MCPServerStateSchema, MCPServerOptionsSchema } from '../schemas/base.js';
+import { Server } from '../server.js';
+import { Server as MCPProtocolServer } from '@modelcontextprotocol/sdk/server/index.js';
+declare module '../server' {
+    interface AvailableServers {
+        mcp: typeof MCPServer;
+    }
+}
+export type MCPServerOptions = z.infer<typeof MCPServerOptionsSchema>;
+export type MCPServerState = z.infer<typeof MCPServerStateSchema>;
+/** Context object passed to all MCP tool, resource, and prompt handlers. */
+export type MCPContext = {
+    container: NodeContainer;
+};
+/** A registered MCP tool with its schema, handler, and pre-computed JSON Schema. */
+export interface RegisteredTool {
+    name: string;
+    description?: string;
+    schema?: z.ZodObject<any>;
+    jsonSchema?: Record<string, any>;
+    handler: (args: any, ctx: MCPContext) => any;
+}
+/** A registered MCP resource with its URI, metadata, and handler. */
+export interface RegisteredResource {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+    handler: (uri: string, ctx: MCPContext) => Promise<string> | string;
+}
+/** A registered MCP prompt with its argument schemas and handler. */
+export interface RegisteredPrompt {
+    name: string;
+    description?: string;
+    args?: Record<string, z.ZodType>;
+    handler: (args: Record<string, string | undefined>, ctx: MCPContext) => Promise<PromptMessage[]> | PromptMessage[];
+}
+export type PromptMessage = {
+    role: 'user' | 'assistant';
+    content: string;
+};
+type ToolRegistrationOptions = {
+    schema?: z.ZodObject<any>;
+    description?: string;
+    handler: (args: any, ctx: MCPContext) => any;
+};
+type ResourceRegistrationOptions = {
+    name?: string;
+    description?: string;
+    mimeType?: string;
+    handler: (uri: string, ctx: MCPContext) => Promise<string> | string;
+};
+type PromptRegistrationOptions = {
+    description?: string;
+    args?: Record<string, z.ZodType>;
+    handler: (args: Record<string, string | undefined>, ctx: MCPContext) => Promise<PromptMessage[]> | PromptMessage[];
+};
+type MCPCompatMode = 'standard' | 'codex';
+type StdioCompatMode = 'standard' | 'codex' | 'auto';
+/**
+ * MCP (Model Context Protocol) server for exposing tools, resources, and prompts
+ * to AI clients like Claude Code. Uses the low-level MCP SDK Server class directly
+ * with Zod 4 native JSON Schema conversion.
+ *
+ * Register tools, resources, and prompts programmatically, then start the server
+ * over stdio (for CLI integration) or HTTP (for remote access).
+ *
+ * @example
+ * ```ts
+ * const mcp = container.server('mcp', { serverName: 'my-server', serverVersion: '1.0.0' })
+ *
+ * mcp.tool('search_files', {
+ *   schema: z.object({ pattern: z.string() }),
+ *   description: 'Search for files',
+ *   handler: async (args, ctx) => {
+ *     return ctx.container.feature('fs').walk('.', { include: [args.pattern] }).files.join('\n')
+ *   }
+ * })
+ *
+ * await mcp.start()
+ * ```
+ */
+export declare class MCPServer extends Server<MCPServerState, MCPServerOptions> {
+    static shortcut: "servers.mcp";
+    static stateSchema: z.ZodObject<{
+        port: z.ZodOptional<z.ZodNumber>;
+        listening: z.ZodDefault<z.ZodBoolean>;
+        configured: z.ZodDefault<z.ZodBoolean>;
+        stopped: z.ZodDefault<z.ZodBoolean>;
+        transport: z.ZodOptional<z.ZodString>;
+        toolCount: z.ZodDefault<z.ZodNumber>;
+        resourceCount: z.ZodDefault<z.ZodNumber>;
+        promptCount: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodNumber>;
+        host: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodEnum<{
+            stdio: "stdio";
+            http: "http";
+        }>>;
+        serverName: z.ZodOptional<z.ZodString>;
+        serverVersion: z.ZodOptional<z.ZodString>;
+        mcpCompat: z.ZodOptional<z.ZodEnum<{
+            standard: "standard";
+            codex: "codex";
+        }>>;
+        stdioCompat: z.ZodOptional<z.ZodEnum<{
+            standard: "standard";
+            codex: "codex";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        toolRegistered: z.ZodTuple<[z.ZodString], null>;
+        resourceRegistered: z.ZodTuple<[z.ZodString], null>;
+        promptRegistered: z.ZodTuple<[z.ZodString], null>;
+        toolCalled: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+    }, z.core.$strip>;
+    _mcpServer?: MCPProtocolServer;
+    _tools: Map<string, RegisteredTool>;
+    _resources: Map<string, RegisteredResource>;
+    _prompts: Map<string, RegisteredPrompt>;
+    get initialState(): MCPServerState;
+    /** The underlying MCP protocol server instance. Created during configure(). */
+    get mcpServer(): MCPProtocolServer;
+    /** The handler context passed to all tool, resource, and prompt handlers. */
+    get handlerContext(): MCPContext;
+    /**
+     * Register an MCP tool. The tool's Zod schema is converted to JSON Schema
+     * for the protocol listing, and used for runtime argument validation.
+     *
+     * Tool handlers can return a string (auto-wrapped as text content) or a
+     * full CallToolResult object for advanced responses (images, errors, etc).
+     *
+     * @param name - Unique tool name
+     * @param options - Tool schema, description, and handler
+     */
+    tool(name: string, options: ToolRegistrationOptions): this;
+    /**
+     * Register an MCP resource. Resources expose data (files, configs, etc)
+     * that AI clients can read by URI.
+     *
+     * Accepts either a handler function directly or an options object with
+     * additional metadata (name, description, mimeType).
+     *
+     * @param uri - Unique resource URI (e.g. "project://readme")
+     * @param handlerOrOptions - Handler function or options object with handler
+     */
+    resource(uri: string, handlerOrOptions: ResourceRegistrationOptions['handler'] | ResourceRegistrationOptions): this;
+    /**
+     * Register an MCP prompt. Prompts are reusable message templates that
+     * AI clients can invoke with optional string arguments.
+     *
+     * @param name - Unique prompt name
+     * @param options - Prompt handler, optional args schema, and description
+     */
+    prompt(name: string, options: PromptRegistrationOptions): this;
+    /**
+     * Configure the MCP protocol server and register all protocol handlers.
+     * Called automatically before start() if not already configured.
+     */
+    configure(): Promise<this>;
+    /**
+     * Start the MCP server with the specified transport.
+     *
+     * @param options - Transport configuration. Defaults to stdio.
+     * @param options.transport - 'stdio' for CLI integration, 'http' for remote access
+     * @param options.port - Port for HTTP transport (default 3001)
+     */
+    start(options?: {
+        transport?: 'stdio' | 'http';
+        port?: number;
+        host?: string;
+        mcpCompat?: MCPCompatMode;
+        stdioCompat?: StdioCompatMode;
+    }): Promise<this>;
+    /**
+     * Stop the MCP server and close all connections.
+     */
+    stop(): Promise<this>;
+    /** Register tools/list and tools/call protocol handlers on the MCP server. */
+    private _registerToolHandlers;
+    /** Register resources/list and resources/read protocol handlers on the MCP server. */
+    private _registerResourceHandlers;
+    /** Register prompts/list and prompts/get protocol handlers on the MCP server. */
+    private _registerPromptHandlers;
+    /** Start an HTTP transport using StreamableHTTPServerTransport. */
+    private _startHTTPTransport;
+    private _resolveMCPCompat;
+    private _resolveStdioCompat;
+    private _normalizeCodexRequest;
+    private _ensureJSONContentType;
+}
+export default MCPServer;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/servers/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/servers/mcp.ts"],"names":[],"mappings":"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"}

package/dist/servers/socket.d.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { type StartOptions, Server, type ServerState } from '../server.js';
+import { WebSocketServer as BaseServer } from 'ws';
+import type { PendingRequest } from '../clients/websocket.js';
+declare module '../server' {
+    interface AvailableServers {
+        websocket: typeof WebsocketServer;
+    }
+}
+export declare const SocketServerOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    host: z.ZodOptional<z.ZodString>;
+    json: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SocketServerOptions = z.infer<typeof SocketServerOptionsSchema>;
+export declare const SocketServerEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    connection: z.ZodTuple<[z.ZodAny], null>;
+    message: z.ZodTuple<[z.ZodAny, z.ZodAny], null>;
+}, z.core.$strip>;
+/**
+ * WebSocket server built on the `ws` library with optional JSON message framing.
+ *
+ * Manages WebSocket connections, tracks connected clients, and bridges
+ * messages to Luca's event bus. When `json` mode is enabled, incoming
+ * messages are automatically JSON-parsed (with `.toString()` for Buffer data)
+ * and outgoing messages via `send()` / `broadcast()` are JSON-stringified.
+ * When `json` mode is disabled, raw message data is emitted as-is and
+ * `send()` / `broadcast()` still JSON-stringify for safety.
+ *
+ * Supports ask/reply semantics when paired with the Luca WebSocket client.
+ * The server can `ask(ws, type, data)` a connected client and await a typed
+ * response, or handle incoming asks from clients by listening for messages
+ * with a `requestId` and replying via `send(ws, { replyTo, data })`.
+ * Requests time out if no reply arrives within the configurable window.
+ *
+ * @extends Server
+ *
+ * @example
+ * ```typescript
+ * const ws = container.server('websocket', { json: true })
+ * await ws.start({ port: 8080 })
+ *
+ * ws.on('message', (data, client) => {
+ *   console.log('Received:', data)
+ *   ws.broadcast({ echo: data })
+ * })
+ *
+ * // ask/reply: request info from a connected client
+ * ws.on('connection', async (client) => {
+ *   const info = await ws.ask(client, 'identify')
+ *   console.log('Client says:', info)
+ * })
+ * ```
+ */
+export declare class WebsocketServer<T extends ServerState = ServerState, K extends SocketServerOptions = SocketServerOptions> extends Server<T, K> {
+    static shortcut: "servers.websocket";
+    static stateSchema: z.ZodObject<{
+        port: z.ZodOptional<z.ZodNumber>;
+        listening: z.ZodDefault<z.ZodBoolean>;
+        configured: z.ZodDefault<z.ZodBoolean>;
+        stopped: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodNumber>;
+        host: z.ZodOptional<z.ZodString>;
+        json: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        connection: z.ZodTuple<[z.ZodAny], null>;
+        message: z.ZodTuple<[z.ZodAny, z.ZodAny], null>;
+    }, z.core.$strip>;
+    _wss?: BaseServer;
+    get wss(): BaseServer;
+    connections: Set<any>;
+    _pending: Map<string, PendingRequest<any>>;
+    broadcast(message: any): Promise<this>;
+    send(ws: any, message: any): Promise<this>;
+    /**
+     * Send a request to a specific client and wait for a correlated response.
+     * The client is expected to reply with a message whose `replyTo` matches
+     * the `requestId` of this message.
+     *
+     * @param ws - The WebSocket client to ask
+     * @param type - A string identifying the request type
+     * @param data - Optional payload
+     * @param timeout - How long to wait (default 10 000 ms)
+     * @returns The `data` field of the response
+     *
+     * @example
+     * ```typescript
+     * ws.on('connection', async (client) => {
+     *   const info = await ws.ask(client, 'identify')
+     *   console.log('Client says:', info)
+     * })
+     * ```
+     */
+    ask<R = any>(ws: any, type: string, data?: any, timeout?: number): Promise<R>;
+    /** @internal Resolve a pending ask() if the incoming message has a replyTo field. Returns true if handled. */
+    _handleReply(message: any): boolean;
+    /** @internal Reject all pending ask() calls — used on stop. */
+    _rejectAllPending(reason: string): void;
+    /**
+     * Start the WebSocket server. A runtime `port` overrides the constructor
+     * option and is written to state before the underlying `ws.Server` is created,
+     * so the server binds to the correct port.
+     *
+     * @param options - Optional runtime overrides for port and host
+     */
+    start(options?: StartOptions): Promise<this>;
+    stop(): Promise<this>;
+    /** The port this server will bind to. Defaults to 8081 if not set via constructor options or start(). */
+    get port(): number;
+}
+export default WebsocketServer;
+//# sourceMappingURL=socket.d.ts.map