@soederpop/luca 0.0.2

package/docs/apis/features/web/vm.md

@@ -0,0 +1,84 @@
+# VM (features.vm)
+
+The VM features providers a virtual machine for executing JavaScript code in a sandboxed environment. The Vm feature automatically injects the container.context object into the global scope, so these things can be referenced in the code and the code can use anything provided by the container.
+
+## Usage
+
+```ts
+container.feature('vm', {
+  // Default context object to inject into the VM execution environment
+  context,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `context` | `any` | Default context object to inject into the VM execution environment |
+
+## Methods
+
+### createScript
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✓ | Parameter code |
+
+**Returns:** `void`
+
+
+
+### createContext
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `ctx` | `any` |  | Parameter ctx |
+
+**Returns:** `void`
+
+
+
+### run
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✓ | Parameter code |
+| `ctx` | `any` |  | Parameter ctx |
+| `options` | `any` |  | Parameter options |
+
+**Returns:** `void`
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.vm**
+
+```ts
+const vm = container.feature('vm')
+
+// Execute simple code
+const result = vm.run('1 + 2 + 3')
+console.log(result) // 6
+
+// Execute code with custom context
+const result2 = vm.run('greeting + " " + name', { 
+ greeting: 'Hello', 
+ name: 'World' 
+})
+console.log(result2) // 'Hello World'
+```
+

package/docs/apis/features/web/voice.md

@@ -0,0 +1,67 @@
+# VoiceRecognition (features.voice)
+
+VoiceRecognition helper
+
+## Usage
+
+```ts
+container.feature('voice')
+```
+
+## Methods
+
+### whenFinished
+
+**Returns:** `void`
+
+
+
+### start
+
+**Returns:** `void`
+
+
+
+### stop
+
+**Returns:** `void`
+
+
+
+### abort
+
+**Returns:** `void`
+
+
+
+### clearTranscript
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `listening` | `any` | Whether the speech recognizer is currently listening for audio input. |
+| `transcript` | `any` | Returns the accumulated final transcript text from recognition results. |
+
+## Events (Zod v4 schema)
+
+### start
+
+Event emitted by VoiceRecognition
+
+
+
+### stop
+
+Event emitted by VoiceRecognition
+
+
+
+### abort
+
+Event emitted by VoiceRecognition
+

package/docs/apis/servers/express.md

@@ -0,0 +1,127 @@
+# ExpressServer (servers.express)
+
+ExpressServer helper
+
+## Usage
+
+```ts
+container.server('express', {
+  // Port number to listen on
+  port,
+  // Hostname or IP address to bind to
+  host,
+  // Whether to enable CORS middleware
+  cors,
+  // Path to serve static files from
+  static,
+  // Serve index.html for unmatched routes (SPA history fallback)
+  historyFallback,
+  // (app: Express, server: Server) => Express
+  create,
+  // (options: StartOptions, server: Server) => Promise<any>
+  beforeStart,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `port` | `number` | Port number to listen on |
+| `host` | `string` | Hostname or IP address to bind to |
+| `cors` | `boolean` | Whether to enable CORS middleware |
+| `static` | `string` | Path to serve static files from |
+| `historyFallback` | `boolean` | Serve index.html for unmatched routes (SPA history fallback) |
+| `create` | `any` | (app: Express, server: Server) => Express |
+| `beforeStart` | `any` | (options: StartOptions, server: Server) => Promise<any> |
+
+## Methods
+
+### start
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `StartOptions` |  | Parameter options |
+
+**Returns:** `void`
+
+
+
+### stop
+
+**Returns:** `void`
+
+
+
+### configure
+
+**Returns:** `void`
+
+
+
+### useEndpoint
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `endpoint` | `Endpoint` | ✓ | Parameter endpoint |
+
+**Returns:** `this`
+
+
+
+### useEndpoints
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dir` | `string` | ✓ | Parameter dir |
+
+**Returns:** `Promise<this>`
+
+
+
+### serveOpenAPISpec
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{ title?: string; version?: string; description?: string }` |  | Parameter options |
+
+**Returns:** `this`
+
+
+
+### generateOpenAPISpec
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{ title?: string; version?: string; description?: string }` |  | Parameter options |
+
+**Returns:** `Record<string, any>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `express` | `any` |  |
+| `hooks` | `any` |  |
+| `app` | `any` |  |
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `port` | `number` | The port the server is bound to |
+| `listening` | `boolean` | Whether the server is actively listening for connections |
+| `configured` | `boolean` | Whether the server has been configured |
+| `stopped` | `boolean` | Whether the server has been stopped |

package/docs/apis/servers/mcp.md

@@ -0,0 +1,213 @@
+# MCPServer (servers.mcp)
+
+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).
+
+## Usage
+
+```ts
+container.server('mcp', {
+  // Port number to listen on
+  port,
+  // Hostname or IP address to bind to
+  host,
+  // Transport type for MCP communication
+  transport,
+  // Server name reported to MCP clients
+  serverName,
+  // Server version reported to MCP clients
+  serverVersion,
+  // HTTP compatibility profile for MCP clients
+  mcpCompat,
+  // Stdio framing compatibility profile for MCP clients
+  stdioCompat,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `port` | `number` | Port number to listen on |
+| `host` | `string` | Hostname or IP address to bind to |
+| `transport` | `string` | Transport type for MCP communication |
+| `serverName` | `string` | Server name reported to MCP clients |
+| `serverVersion` | `string` | Server version reported to MCP clients |
+| `mcpCompat` | `string` | HTTP compatibility profile for MCP clients |
+| `stdioCompat` | `string` | Stdio framing compatibility profile for MCP clients |
+
+## Methods
+
+### tool
+
+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).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | Unique tool name |
+| `options` | `ToolRegistrationOptions` | ✓ | Tool schema, description, and handler |
+
+`ToolRegistrationOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `schema` | `z.ZodObject<any>` |  |
+| `description` | `string` |  |
+| `handler` | `(args: any, ctx: MCPContext) => any` |  |
+
+**Returns:** `this`
+
+
+
+### resource
+
+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).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `uri` | `string` | ✓ | Unique resource URI (e.g. "project://readme") |
+| `handlerOrOptions` | `ResourceRegistrationOptions['handler'] | ResourceRegistrationOptions` | ✓ | Handler function or options object with handler |
+
+**Returns:** `this`
+
+
+
+### prompt
+
+Register an MCP prompt. Prompts are reusable message templates that AI clients can invoke with optional string arguments.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | Unique prompt name |
+| `options` | `PromptRegistrationOptions` | ✓ | Prompt handler, optional args schema, and description |
+
+`PromptRegistrationOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `description` | `string` |  |
+| `args` | `Record<string, z.ZodType>` |  |
+| `handler` | `(args: Record<string, string | undefined>, ctx: MCPContext) => Promise<PromptMessage[]> | PromptMessage[]` |  |
+
+**Returns:** `this`
+
+
+
+### configure
+
+Configure the MCP protocol server and register all protocol handlers. Called automatically before start() if not already configured.
+
+**Returns:** `void`
+
+
+
+### start
+
+Start the MCP server with the specified transport.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{
+    transport?: 'stdio' | 'http'
+    port?: number
+    host?: string
+    mcpCompat?: MCPCompatMode
+    stdioCompat?: StdioCompatMode
+  }` |  | Transport configuration. Defaults to stdio. |
+
+`{
+    transport?: 'stdio' | 'http'
+    port?: number
+    host?: string
+    mcpCompat?: MCPCompatMode
+    stdioCompat?: StdioCompatMode
+  }` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `transport` | `any` | 'stdio' for CLI integration, 'http' for remote access |
+| `port` | `any` | Port for HTTP transport (default 3001) |
+
+**Returns:** `void`
+
+
+
+### stop
+
+Stop the MCP server and close all connections.
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `mcpServer` | `MCPProtocolServer` | The underlying MCP protocol server instance. Created during configure(). |
+| `handlerContext` | `MCPContext` | The handler context passed to all tool, resource, and prompt handlers. |
+
+## Events (Zod v4 schema)
+
+### toolRegistered
+
+Event emitted by MCPServer
+
+
+
+### resourceRegistered
+
+Event emitted by MCPServer
+
+
+
+### promptRegistered
+
+Event emitted by MCPServer
+
+
+
+### toolCalled
+
+Event emitted by MCPServer
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `port` | `number` | The port the server is bound to |
+| `listening` | `boolean` | Whether the server is actively listening for connections |
+| `configured` | `boolean` | Whether the server has been configured |
+| `stopped` | `boolean` | Whether the server has been stopped |
+| `transport` | `string` | Active transport type |
+| `toolCount` | `number` | Number of registered tools |
+| `resourceCount` | `number` | Number of registered resources |
+| `promptCount` | `number` | Number of registered prompts |
+
+## Examples
+
+**servers.mcp**
+
+```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()
+```
+

package/docs/apis/servers/websocket.md

@@ -0,0 +1,99 @@
+# WebsocketServer (servers.websocket)
+
+WebsocketServer helper
+
+## Usage
+
+```ts
+container.server('websocket', {
+  // Port number to listen on
+  port,
+  // Hostname or IP address to bind to
+  host,
+  // Whether to automatically JSON parse/stringify messages
+  json,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `port` | `number` | Port number to listen on |
+| `host` | `string` | Hostname or IP address to bind to |
+| `json` | `boolean` | Whether to automatically JSON parse/stringify messages |
+
+## Methods
+
+### broadcast
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `message` | `any` | ✓ | Parameter message |
+
+**Returns:** `void`
+
+
+
+### send
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `ws` | `any` | ✓ | Parameter ws |
+| `message` | `any` | ✓ | Parameter message |
+
+**Returns:** `void`
+
+
+
+### start
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `StartOptions` |  | Parameter options |
+
+**Returns:** `void`
+
+
+
+### stop
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `wss` | `any` |  |
+| `port` | `any` |  |
+
+## Events (Zod v4 schema)
+
+### connection
+
+Event emitted by WebsocketServer
+
+
+
+### message
+
+Event emitted by WebsocketServer
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `port` | `number` | The port the server is bound to |
+| `listening` | `boolean` | Whether the server is actively listening for connections |
+| `configured` | `boolean` | Whether the server has been configured |
+| `stopped` | `boolean` | Whether the server has been stopped |