@soederpop/luca 0.1.1 → 0.1.3

package/dist/node.d.ts

@@ -0,0 +1,67 @@
+import { NodeContainer, Feature } from './node/container';
+import './introspection/generated.node';
+export * from './node/container';
+declare const servers: import("./server").ServersRegistry, features: import("@soederpop/luca/feature").FeaturesRegistry, clients: import("@soederpop/luca/client").ClientsRegistry;
+declare const _default: NodeContainer;
+export default _default;
+/**
+ * Returns the singleton container instance.
+ * LLMs love to hallucinate this function — so we provide it, but warn.
+ * If you need a separate container, use `container.subcontainer()`.
+ */
+export declare function createContainer(): NodeContainer<import("./node").NodeFeatures, {
+    started: boolean;
+    enabledFeatures: string[];
+    registries: string[];
+    factories: string[];
+}>;
+export declare const ui: import("./node").UI<{
+    [x: string]: unknown;
+    enabled: boolean;
+    fonts?: string[] | undefined;
+    colorPalette?: string[] | undefined;
+}>;
+export declare const fs: import("./node").FS;
+export declare const vm: import("./node/features/vm").VM<{
+    [x: string]: unknown;
+    enabled: boolean;
+}, {
+    context: any;
+    name?: string | undefined;
+    _cacheKey?: string | undefined;
+    cached?: boolean | undefined;
+    enable?: boolean | undefined;
+}>;
+export declare const proc: import("./node").ChildProcess;
+export { servers, features, clients };
+export { Feature };
+export { Container } from './container';
+export { Helper } from './helper';
+export { Bus } from './bus';
+export { State } from './state';
+export { Registry } from './registry';
+export { Client, ClientsRegistry } from './client';
+export { RestClient } from './clients/rest';
+export { GraphClient } from './clients/graph';
+export { WebSocketClient } from './clients/websocket';
+export { Command, CommandsRegistry, commands } from './command';
+export { Endpoint, EndpointsRegistry, endpoints } from './endpoint';
+export { Selector, SelectorsRegistry, selectors } from './selector';
+export { Server, ServersRegistry } from './server';
+export { FeaturesRegistry } from './feature';
+export { ExpressServer } from './servers/express';
+export { WebsocketServer } from './servers/socket';
+export type { ContainerContext, ContainerArgv, Plugin, Extension } from './container';
+export type { AvailableClients } from './client';
+export type { AvailableCommands, CommandHandler } from './command';
+export type { AvailableEndpoints, EndpointContext } from './endpoint';
+export type { AvailableSelectors, SelectorsInterface, SelectorRunResult, SimpleSelector } from './selector';
+export type { AvailableFeatures, FeatureOptions, FeatureState } from './feature';
+export type { NodeContainer, NodeFeatures } from './node/container';
+export type { AvailableServers, StartOptions, ServersInterface } from './server';
+export type { HelperState, HelperOptions } from './helper';
+export type { EventMap } from './bus';
+export type { SetStateValue, StateChangeType } from './state';
+export { z } from 'zod';
+export * from './schemas/base';
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AACzD,OAAO,gCAAgC,CAAA;AAEvC,cAAc,kBAAkB,CAAA;AAIhC,QAAA,MAAQ,OAAO,sCAAE,QAAQ,sDAAE,OAAO,kDAAc,CAAA;wBAEpB,aAAa;AAAzC,wBAAyC;AAEzC;;;;GAIG;AACH,wBAAgB,eAAe;;;;;GAO9B;AAGD,eAAO,MAAM,EAAE;;;;;EAA0B,CAAA;AACzC,eAAO,MAAM,EAAE,qBAA0B,CAAA;AACzC,eAAO,MAAM,EAAE;;;;;;;;;EAA0B,CAAA;AACzC,eAAO,MAAM,IAAI,+BAA4B,CAAA;AAG7C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;AAGrC,OAAO,EAAE,OAAO,EAAE,CAAA;AAClB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAC3B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAGrC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC/D,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAG5C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAGlD,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACrF,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAChD,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAClE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACrE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3G,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAChF,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACnE,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAChF,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAC1D,YAAY,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AACrC,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAG7D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,cAAc,gBAAgB,CAAA"}

package/dist/python/generated.d.ts

@@ -0,0 +1,2 @@
+export declare const bridgeScript = "#!/usr/bin/env python3\n\"\"\"Luca Python Bridge - persistent interactive Python session.\n\nCommunicates via JSON lines over stdin/stdout. Each request is a single\nJSON object per line on stdin; each response is a single JSON object per\nline on stdout. User print() output is captured per-execution via\nio.StringIO so it never corrupts the protocol.\n\nPython 3.8+ compatible (stdlib only).\n\"\"\"\nimport sys\nimport json\nimport io\nimport traceback\nimport os\n\n# Persistent namespace shared across all exec/eval calls\n_namespace = {\"__builtins__\": __builtins__}\n\n\ndef setup_sys_path(project_dir):\n    \"\"\"Insert project_dir and common sub-paths into sys.path.\"\"\"\n    paths_to_add = [project_dir]\n\n    # src/ layout (PEP 621 / setuptools)\n    src_dir = os.path.join(project_dir, \"src\")\n    if os.path.isdir(src_dir):\n        paths_to_add.append(src_dir)\n\n    # lib/ layout (less common but exists)\n    lib_dir = os.path.join(project_dir, \"lib\")\n    if os.path.isdir(lib_dir):\n        paths_to_add.append(lib_dir)\n\n    for p in reversed(paths_to_add):\n        if p not in sys.path:\n            sys.path.insert(0, p)\n\n\ndef _safe_serialize(value):\n    \"\"\"Attempt JSON serialization; fall back to repr().\"\"\"\n    try:\n        json.dumps(value, default=str)\n        return value\n    except (TypeError, ValueError, OverflowError):\n        return repr(value)\n\n\ndef handle_exec(req):\n    \"\"\"Execute code in the persistent namespace.\"\"\"\n    code = req.get(\"code\", \"\")\n    variables = req.get(\"variables\", {})\n    _namespace.update(variables)\n\n    old_stdout = sys.stdout\n    captured = io.StringIO()\n    sys.stdout = captured\n    try:\n        exec(code, _namespace)\n        sys.stdout = old_stdout\n        return {\"ok\": True, \"stdout\": captured.getvalue(), \"result\": None}\n    except Exception as e:\n        sys.stdout = old_stdout\n        return {\n            \"ok\": False,\n            \"error\": str(e),\n            \"traceback\": traceback.format_exc(),\n            \"stdout\": captured.getvalue(),\n        }\n\n\ndef handle_eval(req):\n    \"\"\"Evaluate an expression and return its value.\"\"\"\n    expression = req.get(\"expression\", \"\")\n\n    old_stdout = sys.stdout\n    captured = io.StringIO()\n    sys.stdout = captured\n    try:\n        result = eval(expression, _namespace)\n        sys.stdout = old_stdout\n        return {\n            \"ok\": True,\n            \"result\": _safe_serialize(result),\n            \"stdout\": captured.getvalue(),\n        }\n    except Exception as e:\n        sys.stdout = old_stdout\n        return {\n            \"ok\": False,\n            \"error\": str(e),\n            \"traceback\": traceback.format_exc(),\n            \"stdout\": captured.getvalue(),\n        }\n\n\ndef handle_import(req):\n    \"\"\"Import a module into the namespace.\"\"\"\n    module_name = req.get(\"module\", \"\")\n    alias = req.get(\"alias\", module_name.split(\".\")[-1])\n    try:\n        mod = __import__(\n            module_name,\n            fromlist=[module_name.split(\".\")[-1]] if \".\" in module_name else [],\n        )\n        _namespace[alias] = mod\n        return {\"ok\": True, \"result\": \"Imported {} as {}\".format(module_name, alias)}\n    except Exception as e:\n        return {\n            \"ok\": False,\n            \"error\": str(e),\n            \"traceback\": traceback.format_exc(),\n        }\n\n\ndef handle_call(req):\n    \"\"\"Call a function by dotted path in the namespace.\"\"\"\n    func_path = req.get(\"function\", \"\")\n    args = req.get(\"args\", [])\n    kwargs = req.get(\"kwargs\", {})\n\n    old_stdout = sys.stdout\n    captured = io.StringIO()\n    sys.stdout = captured\n    try:\n        parts = func_path.split(\".\")\n        obj = _namespace[parts[0]]\n        for part in parts[1:]:\n            obj = getattr(obj, part)\n        result = obj(*args, **kwargs)\n        sys.stdout = old_stdout\n        return {\n            \"ok\": True,\n            \"result\": _safe_serialize(result),\n            \"stdout\": captured.getvalue(),\n        }\n    except Exception as e:\n        sys.stdout = old_stdout\n        return {\n            \"ok\": False,\n            \"error\": str(e),\n            \"traceback\": traceback.format_exc(),\n            \"stdout\": captured.getvalue(),\n        }\n\n\ndef handle_get_locals(req):\n    \"\"\"Return all non-dunder keys from the namespace.\"\"\"\n    safe = {}\n    for k, v in _namespace.items():\n        if k.startswith(\"__\"):\n            continue\n        safe[k] = _safe_serialize(v)\n    return {\"ok\": True, \"result\": safe}\n\n\ndef handle_reset(req):\n    \"\"\"Clear the namespace.\"\"\"\n    _namespace.clear()\n    _namespace[\"__builtins__\"] = __builtins__\n    return {\"ok\": True, \"result\": \"Session reset\"}\n\n\nHANDLERS = {\n    \"exec\": handle_exec,\n    \"eval\": handle_eval,\n    \"import\": handle_import,\n    \"call\": handle_call,\n    \"get_locals\": handle_get_locals,\n    \"reset\": handle_reset,\n}\n\n\ndef main():\n    # First line from stdin is the init handshake with project_dir\n    init_line = sys.stdin.readline().strip()\n    if init_line:\n        try:\n            init = json.loads(init_line)\n            if \"project_dir\" in init:\n                setup_sys_path(init[\"project_dir\"])\n        except json.JSONDecodeError:\n            pass\n\n    # Signal ready\n    sys.stdout.write(json.dumps({\"ok\": True, \"type\": \"ready\"}) + \"\\n\")\n    sys.stdout.flush()\n\n    # Main loop: read JSON commands, execute, respond\n    for line in sys.stdin:\n        line = line.strip()\n        if not line:\n            continue\n\n        try:\n            req = json.loads(line)\n        except json.JSONDecodeError as e:\n            resp = {\"ok\": False, \"error\": \"Invalid JSON: {}\".format(e)}\n            sys.stdout.write(json.dumps(resp) + \"\\n\")\n            sys.stdout.flush()\n            continue\n\n        req_id = req.get(\"id\")\n        req_type = req.get(\"type\", \"exec\")\n        handler = HANDLERS.get(req_type)\n\n        if not handler:\n            resp = {\"ok\": False, \"error\": \"Unknown request type: {}\".format(req_type)}\n        else:\n            resp = handler(req)\n\n        if req_id:\n            resp[\"id\"] = req_id\n\n        sys.stdout.write(json.dumps(resp, default=str) + \"\\n\")\n        sys.stdout.flush()\n\n\nif __name__ == \"__main__\":\n    main()\n";
+//# sourceMappingURL=generated.d.ts.map

package/dist/python/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../src/python/generated.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,YAAY,02MA4NxB,CAAA"}

package/dist/react/index.d.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+import type { Container, AvailableFeatures } from '../container';
+import type { Helper } from '../helper';
+import type { StateChangeType } from '../state';
+declare const ContainerContext: import("react").Context<Container<AvailableFeatures, any> | null>;
+declare function ContainerProvider({ container, children }: {
+    container: Container;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<Container<AvailableFeatures, any> | null>>;
+declare function useContainer<T extends Container = Container>(): T;
+type HasState = {
+    state: {
+        current: any;
+        version: number;
+        observe: (cb: (changeType: StateChangeType, key: any, value?: any) => void) => () => void;
+    };
+};
+declare function useContainerState<T extends object = any>(target?: HasState): T;
+declare function useStateValue<V = any>(target: HasState, key: string): V | undefined;
+declare function useStateVersion(target?: HasState): number;
+type HasEvents = {
+    on: (event: string, listener: (...args: any[]) => void) => any;
+    off: (event: string, listener?: (...args: any[]) => void) => any;
+};
+declare function useEvent(target: HasEvents, event: string, handler: (...args: any[]) => void): void;
+declare function useWaitFor<T = any>(target: HasEvents & {
+    waitFor: (event: string) => Promise<any>;
+}, event: string): {
+    data: T | undefined;
+    pending: boolean;
+    error: Error | undefined;
+};
+declare function useFeature<K extends keyof AvailableFeatures>(name: K, options?: ConstructorParameters<AvailableFeatures[K]>[0]): InstanceType<AvailableFeatures[K]>;
+declare function useHelperState<T extends object = any>(helper: Helper): [T, (value: any) => void];
+export { ContainerContext, ContainerProvider, useContainer, useContainerState, useStateValue, useStateVersion, useEvent, useWaitFor, useFeature, useHelperState, };
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAI/C,QAAA,MAAM,gBAAgB,mEAAwC,CAAA;AAE9D,iBAAS,iBAAiB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,qHAEhG;AAED,iBAAS,YAAY,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,KAAK,CAAC,CAM1D;AAID,KAAK,QAAQ,GAAG;IAAE,KAAK,EAAE;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;KAAE,CAAA;CAAE,CAAA;AAEvJ,iBAAS,iBAAiB,CAAC,CAAC,SAAS,MAAM,GAAG,GAAG,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,CAAC,CAiBvE;AAED,iBAAS,aAAa,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAc5E;AAED,iBAAS,eAAe,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,CAiBlD;AAID,KAAK,SAAS,GAAG;IAAE,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,GAAG,CAAC;IAAC,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,GAAG,CAAA;CAAE,CAAA;AAErJ,iBAAS,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI,CAS3F;AAED,iBAAS,UAAU,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,SAAS,GAAG;IAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;CAAE,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAA;CAAE,CA8BjL;AAID,iBAAS,UAAU,CAAC,CAAC,SAAS,MAAM,iBAAiB,EACnD,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,qBAAqB,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACvD,YAAY,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAMpC;AAID,iBAAS,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC,CAiBzF;AAID,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,QAAQ,EACR,UAAU,EACV,UAAU,EACV,cAAc,GACf,CAAA"}

package/dist/registry.d.ts

@@ -0,0 +1,97 @@
+import type { Helper } from './helper.js';
+import type { ContainerContext } from './container.js';
+import type { HelperIntrospection } from './introspection/index.js';
+export type { HelperIntrospection };
+declare abstract class Registry<T extends Helper> {
+    scope: string;
+    baseClass?: new (options: any, context: ContainerContext) => T;
+    private readonly members;
+    private readonly _events;
+    constructor();
+    /**
+     * Lists the keys of all available helpers in this registry.
+    */
+    get available(): string[];
+    /**
+     * Register a new helper in this registry.
+     *
+     * @param id - The id of the helper to register.
+     * @param constructor - The constructor for the helper.
+     * @returns The constructor for the helper.
+    */
+    register(id: string, constructor: new (options: any, context: ContainerContext) => T): new (options: any, context: ContainerContext) => T;
+    /**
+     * Remove a helper from this registry.
+     *
+     * @param id - The id of the helper to unregister.
+     * @returns True if the helper was removed, false if it wasn't registered.
+    */
+    unregister(id: string): boolean;
+    /**
+     * Check if a helper is registered in this registry.
+     *
+     * @param id - The id of the helper to check.
+     * @returns True if the helper is registered, false otherwise.
+    */
+    has(id: string): boolean;
+    /**
+     * Lookup a helper by id.
+     *
+     * @param id - The id of the helper to lookup.
+     * @returns The constructor for the helper.
+    */
+    lookup(id: string): new (options: any, context: ContainerContext) => T;
+    /**
+     * View data about the interface for a particular Helper.  Will tell you about the options
+     * to create one, the state it maintains, the methods and properties it has, and the events it emits.
+    */
+    introspect(id: string): HelperIntrospection | undefined;
+    /**
+     * Learn about the interface for a particular Helper.  Will tell you about the options
+     * to create one, the state it maintains, the methods and properties it has, and the events it emits.
+     *
+     * Will return information as a markdown string.
+    */
+    describe(id: string): string;
+    /**
+     * Returns a condensed overview of all available helpers in this registry.
+     * Shows each helper's name and description, without the full introspection details.
+     *
+     * Use `describe(id)` to get the full details for a specific helper.
+    */
+    describeAll(): string;
+    /**
+     * Emit an event on the registry's event bus.
+     *
+     * @param event - The event to emit.
+     * @param args - The arguments to pass to the event listener.
+     * @returns The registry instance.
+    */
+    emit(event: string, ...args: any[]): this;
+    /**
+     * Subscribe to an event on the registry's event bus.
+     *
+     * @param event - The event to subscribe to.
+     * @param listener - The listener to call when the event is emitted.
+     * @returns The registry instance.
+    */
+    on(event: string, listener: (...args: any[]) => void): this;
+    /**
+     * Unsubscribe a listener from an event on the registry's event bus.
+     *
+     * @param event - The event to unsubscribe from.
+     * @param listener - The listener to unsubscribe.
+     * @returns The registry instance.
+    */
+    off(event: string, listener: (...args: any[]) => void): this;
+    /**
+     * Subscribe to an event on the registry's event bus, but only fire once.
+     *
+     * @param event - The event to subscribe to.
+     * @param listener - The listener to call when the event is emitted.
+     * @returns The registry instance.
+    */
+    once(event: string, listener: (...args: any[]) => void): this;
+}
+export { Registry };
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAKvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,YAAY,EAAE,mBAAmB,EAAE,CAAA;AAEnC,uBAAe,QAAQ,CAAC,CAAC,SAAS,MAAM;IACtC,KAAK,EAAE,MAAM,CAAgB;IAE7B,SAAS,CAAC,EAAE,KAAK,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB,KAAK,CAAC,CAAA;IAE9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmE;IAE3F,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAO;;IAiC/B;;MAEE;IACF,IAAI,SAAS,IAAK,MAAM,EAAE,CAEzB;IAED;;;;;;MAME;IACF,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB,KAAK,CAAC,iBAApC,GAAG,WAAW,gBAAgB,KAAK,CAAC;IAOpF;;;;;MAKE;IACF,UAAU,CAAC,EAAE,EAAE,MAAM,GAAI,OAAO;IAKhC;;;;;MAKE;IACF,GAAG,CAAC,EAAE,EAAE,MAAM,GAAI,OAAO;IAIzB;;;;;MAKE;IACF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAI,KAAK,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB,KAAK,CAAC;IAuBvE;;;MAGE;IACF,UAAU,CAAC,EAAE,EAAE,MAAM,GAAI,mBAAmB,GAAG,SAAS;IAIxD;;;;;MAKE;IACF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAI,MAAM;IAM7B;;;;;MAKE;IACF,WAAW,IAAK,MAAM;IAatB;;;;;;MAME;IACF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;IAKlC;;;;;;MAME;IACF,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI;IAKpD;;;;;;MAME;IACF,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI;IAKrD;;;;;;MAME;IACF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI;CAIvD;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/scaffolds/generated.d.ts

@@ -0,0 +1,13 @@
+export interface ScaffoldSection {
+    heading: string;
+    code: string;
+}
+export interface ScaffoldData {
+    sections: ScaffoldSection[];
+    full: string;
+    tutorial: string;
+}
+export declare const scaffolds: Record<string, ScaffoldData>;
+export declare const assistantFiles: Record<string, string>;
+export declare const mcpReadme = "# Luca Development Guide\n\nYou are working in a **luca project**. The luca container provides all capabilities your code needs. Do not install npm packages or import Node.js builtins directly.\n\n## The Contract\n\nEvery capability goes through the container. If you need something that doesn't exist, build it as a feature, client, or server. If it wraps a third-party library, the helper IS the interface \u2014 consumer code never imports the library directly.\n\n## Import Rule\n\nAll consumer code imports from `@soederpop/luca` only:\n\n```ts\nimport { Feature, features, z, FeatureStateSchema, FeatureOptionsSchema } from '@soederpop/luca'\nimport { Client, clients, RestClient, ClientStateSchema } from '@soederpop/luca/client'\nimport { Server, servers, ServerStateSchema } from '@soederpop/luca'\nimport { commands, CommandOptionsSchema } from '@soederpop/luca'\n```\n\nNever import from `fs`, `path`, `crypto`, or other Node builtins. Never import third-party packages in consumer code. If a container feature wraps the functionality, use it.\n\n## Zod v4\n\nThis project uses **Zod v4** \u2014 import `z` from `@soederpop/luca`, never from `'zod'` directly. All option, state, and event schemas use Zod v4 syntax. Key patterns:\n\n```ts\n// Extending base schemas (options, state, events)\nexport const MyStateSchema = FeatureStateSchema.extend({\n  count: z.number().default(0).describe('Number of items'),\n  label: z.string().optional().describe('Display label'),\n})\n\n// Events use z.tuple() for listener arguments\nexport const MyEventsSchema = FeatureEventsSchema.extend({\n  itemAdded: z.tuple([z.string().describe('key'), z.number().describe('index')]),\n})\n\n// Type inference\nexport type MyState = z.infer<typeof MyStateSchema>\n```\n\nZod v4 differences from v3 that matter:\n- `z.string().check(...)` replaces some v3 refinement patterns\n- `.toJSONSchema()` is built-in on any schema \u2014 no external library needed\n- Error customization uses `z.string({ error: \"message\" })` not `.refine()` for simple cases\n- `z.interface()` exists for recursive/lazy object types\n- Do NOT use `z.nativeEnum()` \u2014 use `z.enum()` instead\n\n## Dependencies\n\nIf the project has `node_modules` and a package manager, helper implementations can import third-party libraries internally. If not (e.g. running via the `luca` binary's VM), all code must import only from `@soederpop/luca`.\n\n## Discovering Capabilities\n\nThe container has registries for features, clients, servers, commands, and endpoints. **Do not guess** what is available \u2014 use your MCP tools to discover it:\n\n1. **`find_capability`** \u2014 Overview of all features, clients, and servers with descriptions. Start here.\n2. **`list_registry`** \u2014 List all names in a specific registry (features, clients, servers, commands, endpoints).\n3. **`describe_helper`** \u2014 Full API docs for a specific helper (methods, options, state, events). Call this before writing code that uses a helper.\n4. **`eval`** \u2014 Once you know what you need, prototype calls in the live sandbox before writing them into files.\n\n## Mini Examples\n\n### Feature with composition\n\nFeatures access other features via `this.container.feature(...)`:\n\n```ts\nimport { z } from 'zod'\nimport { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '@soederpop/luca'\nimport { Feature, features } from '@soederpop/luca'\nimport type { ContainerContext } from '@soederpop/luca'\n\nexport const ConfigStateSchema = FeatureStateSchema.extend({\n  loaded: z.boolean().default(false).describe('Whether config has been loaded'),\n})\n\nexport const ConfigOptionsSchema = FeatureOptionsSchema.extend({\n  filePath: z.string().default('config.json').describe('Path to config file'),\n})\n\nexport const ConfigEventsSchema = FeatureEventsSchema.extend({\n  configLoaded: z.tuple([z.record(z.unknown()).describe('parsed config')]),\n})\n\nexport class Config extends Feature<z.infer<typeof ConfigStateSchema>, z.infer<typeof ConfigOptionsSchema>> {\n  static override shortcut = 'features.config' as const\n  static override stateSchema = ConfigStateSchema\n  static override optionsSchema = ConfigOptionsSchema\n  static override eventsSchema = ConfigEventsSchema\n  static override description = 'Loads and manages project configuration'\n\n  /** Load and parse the config file */\n  async load() {\n    const fs = this.container.feature('fs')\n    const raw = await fs.readFile(this.options.filePath)\n    const data = JSON.parse(raw)\n    this.state.set('loaded', true)\n    this.emit('configLoaded', data)\n    return data\n  }\n}\n\ndeclare module '@soederpop/luca' {\n  interface AvailableFeatures { config: typeof Config }\n}\nexport default features.register('config', Config)\n```\n\n### Client with composition\n\nClients access features and other clients via `this.container`:\n\n```ts\nimport { z } from 'zod'\nimport { Client, clients, ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca'\nimport type { ContainerContext } from '@soederpop/luca'\n\nexport const GithubOptionsSchema = ClientOptionsSchema.extend({\n  token: z.string().describe('GitHub personal access token'),\n  owner: z.string().describe('Repository owner'),\n  repo: z.string().describe('Repository name'),\n})\n\nexport const GithubEventsSchema = ClientEventsSchema.extend({\n  issuesFetched: z.tuple([z.number().describe('count')]),\n})\n\nexport class GithubClient extends Client<z.infer<typeof ClientStateSchema>, z.infer<typeof GithubOptionsSchema>> {\n  static override shortcut = 'clients.github' as const\n  static override optionsSchema = GithubOptionsSchema\n  static override eventsSchema = GithubEventsSchema\n  static override description = 'GitHub API client using container REST client'\n\n  /** Fetch open issues */\n  async issues() {\n    const rest = this.container.client('rest')\n    const res = await rest.get(`https://api.github.com/repos/${this.options.owner}/${this.options.repo}/issues`, {\n      headers: { Authorization: `token ${this.options.token}` },\n    })\n    this.emit('issuesFetched', res.data.length)\n    return res.data\n  }\n}\n\ndeclare module '@soederpop/luca' {\n  interface AvailableClients { github: typeof GithubClient }\n}\nexport default clients.register('github', GithubClient)\n```\n\n## Workflow\n\n1. **`find_capability`** \u2014 Search what already exists before writing anything\n2. **`describe_helper`** \u2014 Read the full API docs for the helper you need\n3. **`eval`** \u2014 Prototype and test container API calls in the sandbox\n4. **`scaffold`** \u2014 Generate correct boilerplate when building something new\n5. **Write the file** \u2014 Using the patterns from the scaffold\n\n## Portability\n\nCode that only imports from `@soederpop/luca` can be copied between any luca project. That's the goal. Features, clients, servers, and commands written this way are portable building blocks.\n";
+//# sourceMappingURL=generated.d.ts.map

package/dist/scaffolds/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../src/scaffolds/generated.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,eAAe,EAAE,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CA4jDlD,CAAA;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAmCjD,CAAA;AAED,eAAO,MAAM,SAAS,gzNAkKrB,CAAA"}

package/dist/scaffolds/template.d.ts

@@ -0,0 +1,11 @@
+/** Convert a string to PascalCase */
+export declare function toPascalCase(str: string): string;
+/** Convert a string to camelCase */
+export declare function toCamelCase(str: string): string;
+/** Convert a string to kebab-case */
+export declare function toKebabCase(str: string): string;
+/** Apply mustache-style template variables to scaffold code */
+export declare function applyTemplate(template: string, vars: Record<string, string>): string;
+/** Generate scaffolded code for a given helper type */
+export declare function generateScaffold(type: string, name: string, description?: string): string | null;
+//# sourceMappingURL=template.d.ts.map

package/dist/scaffolds/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/scaffolds/template.ts"],"names":[],"mappings":"AAEA,qCAAqC;AACrC,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,oCAAoC;AACpC,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED,qCAAqC;AACrC,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAMpF;AAED,uDAAuD;AACvD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYhG"}

package/dist/schemas/base.d.ts

@@ -0,0 +1,254 @@
+import { z } from 'zod';
+export declare const HelperStateSchema: z.ZodObject<{}, z.core.$loose>;
+export declare const HelperOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type InferState<T extends z.ZodType> = z.infer<T>;
+export type InferOptions<T extends z.ZodType> = z.infer<T>;
+/**
+ * Infer an EventMap from an events schema where each key is an event name
+ * and each value is a z.tuple() describing the listener arguments.
+ *
+ * e.g. z.object({ ready: z.tuple([]), message: z.tuple([z.string()]) })
+ *   => { ready: [], message: [string] }
+ */
+export type InferEvents<T extends z.ZodType> = z.infer<T> extends infer E ? {
+    [K in keyof E]: E[K] extends any[] ? E[K] : any[];
+} : Record<string, any[]>;
+export declare const createHelperSchemas: <StateSchema extends z.ZodType, OptionsSchema extends z.ZodType>(stateSchema: StateSchema, optionsSchema: OptionsSchema) => {
+    state: StateSchema;
+    options: OptionsSchema;
+    types: {
+        State: InferState<StateSchema>;
+        Options: InferOptions<OptionsSchema>;
+    };
+};
+export declare const ContainerStateSchema: z.ZodObject<{
+    started: z.ZodDefault<z.ZodBoolean>;
+    enabledFeatures: z.ZodArray<z.ZodString>;
+    registries: z.ZodArray<z.ZodString>;
+    factories: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const FeatureStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$loose>;
+export declare const FeatureOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const ClientStateSchema: z.ZodObject<{
+    connected: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$loose>;
+export declare const ClientOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    baseURL: z.ZodOptional<z.ZodString>;
+    json: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const ServerStateSchema: 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>;
+export declare const ServerOptionsSchema: 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>;
+export declare const HelperEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+export declare const FeatureEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+}, z.core.$strip>;
+export declare const ClientEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    failure: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+export declare const WebSocketClientStateSchema: z.ZodObject<{
+    connected: z.ZodDefault<z.ZodBoolean>;
+    connectionError: z.ZodOptional<z.ZodAny>;
+    reconnectAttempts: z.ZodDefault<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const WebSocketClientOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    baseURL: z.ZodOptional<z.ZodString>;
+    json: z.ZodOptional<z.ZodBoolean>;
+    reconnect: z.ZodOptional<z.ZodBoolean>;
+    reconnectInterval: z.ZodOptional<z.ZodNumber>;
+    maxReconnectAttempts: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const WebSocketClientEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    failure: z.ZodTuple<[z.ZodAny], null>;
+    message: z.ZodTuple<[z.ZodAny], null>;
+    open: z.ZodTuple<[], null>;
+    close: z.ZodTuple<[z.ZodOptional<z.ZodNumber>, z.ZodOptional<z.ZodString>], null>;
+    error: z.ZodTuple<[z.ZodAny], null>;
+    reconnecting: z.ZodTuple<[z.ZodNumber], null>;
+}, z.core.$strip>;
+export declare const GraphClientOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    baseURL: z.ZodOptional<z.ZodString>;
+    json: z.ZodOptional<z.ZodBoolean>;
+    endpoint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const GraphClientEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    failure: z.ZodTuple<[z.ZodAny], null>;
+    graphqlError: z.ZodTuple<[z.ZodArray<z.ZodAny>], null>;
+}, z.core.$strip>;
+export declare const ServerEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+export declare const MCPServerOptionsSchema: 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>;
+export declare const MCPServerStateSchema: 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>;
+export declare const MCPServerEventsSchema: 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>;
+export declare const CommandStateSchema: z.ZodObject<{
+    running: z.ZodDefault<z.ZodBoolean>;
+    exitCode: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const CommandOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    _: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    dispatchSource: z.ZodDefault<z.ZodEnum<{
+        cli: "cli";
+        headless: "headless";
+        mcp: "mcp";
+        rpc: "rpc";
+    }>>;
+}, z.core.$strip>;
+export type DispatchSource = 'cli' | 'headless' | 'mcp' | 'rpc';
+export interface CommandRunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export declare const CommandEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    started: z.ZodTuple<[], null>;
+    completed: z.ZodTuple<[z.ZodNumber], null>;
+    failed: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+export declare const SelectorStateSchema: z.ZodObject<{
+    running: z.ZodDefault<z.ZodBoolean>;
+    lastRanAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const SelectorOptionsSchema: 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>;
+export interface SelectorRunResult<T = any> {
+    data: T;
+    cached: boolean;
+    cacheKey: string;
+}
+export declare const SelectorEventsSchema: 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>;
+export declare const EndpointStateSchema: z.ZodObject<{
+    mounted: z.ZodDefault<z.ZodBoolean>;
+    path: z.ZodDefault<z.ZodString>;
+    methods: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    requestCount: z.ZodDefault<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const EndpointOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    filePath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const EndpointEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    loaded: z.ZodTuple<[z.ZodAny], null>;
+    mounted: z.ZodTuple<[z.ZodString], null>;
+    request: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodAny], null>;
+    error: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+/**
+ * Converts a ZodObject into an introspection-friendly record.
+ * Uses Zod v4's native toJSONSchema() and transforms properties
+ * into { fieldName: { type, description } } for the introspection system.
+ */
+export declare function describeZodShape(schema: z.ZodType): Record<string, {
+    type: string;
+    description: string;
+}>;
+/**
+ * Converts an events ZodObject schema into introspection-friendly EventIntrospection records.
+ *
+ * Each top-level key is an event name, and its value should be a z.tuple() describing
+ * the positional arguments passed to listeners.
+ *
+ * Merges with existing build-time event data (e.g. descriptions from AST scanning)
+ * while adding argument type information from the Zod schema.
+ */
+export declare function describeEventsSchema(schema: z.ZodType, existing?: Record<string, {
+    name: string;
+    description: string;
+    arguments: Record<string, {
+        type: string;
+        description: string;
+    }>;
+}>): Record<string, {
+    name: string;
+    description: string;
+    arguments: Record<string, {
+        type: string;
+        description: string;
+    }>;
+}>;
+//# sourceMappingURL=base.d.ts.map

package/dist/schemas/base.d.ts.map

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