luca 2.0.0 → 3.0.0

package/docs/apis/servers/mcp.md

@@ -0,0 +1,238 @@
+# 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.ZodType` |  |
+| `description` | `string` |  |
+| `handler` | `Function | ((args: any, ctx: any) => 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:** `Promise<this>`
+
+
+
+### 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:** `Promise<this>`
+
+
+
+### stop
+
+Stop the MCP server and close all connections.
+
+**Returns:** `Promise<this>`
+
+
+
+## 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
+
+Emitted when a tool is registered
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Tool name |
+
+
+
+### resourceRegistered
+
+Emitted when a resource is registered
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Resource URI |
+
+
+
+### promptRegistered
+
+Emitted when a prompt is registered
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Prompt name |
+
+
+
+### toolCalled
+
+Emitted when a tool is called
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Tool name |
+| `arg1` | `any` | Arguments |
+
+
+
+## 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,170 @@
+# WebsocketServer (servers.websocket)
+
+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.
+
+## Usage
+
+```ts
+container.server('websocket', {
+  // Port number to listen on
+  port,
+  // Hostname or IP address to bind to
+  host,
+  // When enabled, incoming messages are automatically JSON-parsed before emitting the message event, and outgoing send/broadcast calls JSON-stringify the payload
+  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` | When enabled, incoming messages are automatically JSON-parsed before emitting the message event, and outgoing send/broadcast calls JSON-stringify the payload |
+
+## Methods
+
+### broadcast
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `message` | `any` | ✓ | Parameter message |
+
+**Returns:** `Promise<this>`
+
+
+
+### send
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `ws` | `any` | ✓ | Parameter ws |
+| `message` | `any` | ✓ | Parameter message |
+
+**Returns:** `Promise<this>`
+
+
+
+### ask
+
+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.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `ws` | `any` | ✓ | The WebSocket client to ask |
+| `type` | `string` | ✓ | A string identifying the request type |
+| `data` | `any` |  | Optional payload |
+| `timeout` | `any` |  | How long to wait (default 10 000 ms) |
+
+**Returns:** `Promise<R>`
+
+```ts
+ws.on('connection', async (client) => {
+ const info = await ws.ask(client, 'identify')
+ console.log('Client says:', info)
+})
+```
+
+
+
+### start
+
+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.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `StartOptions` |  | Optional runtime overrides for port and host |
+
+**Returns:** `Promise<this>`
+
+
+
+### stop
+
+**Returns:** `Promise<this>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `wss` | `BaseServer` |  |
+| `port` | `number` | The port this server will bind to. Defaults to 8081 if not set via constructor options or start(). |
+
+## Events (Zod v4 schema)
+
+### connection
+
+Fires when a new client connects
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The raw WebSocket client instance from the ws library |
+
+
+
+### message
+
+Fires when a message is received from a client. Handler signature: (data, ws)
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The message data (JSON-parsed object when json option is enabled, raw Buffer/string otherwise) |
+| `arg1` | `any` | The WebSocket client that sent the message — use with server.send(ws, data) to reply |
+
+
+
+## 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 |
+
+## Examples
+
+**servers.websocket**
+
+```ts
+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)
+})
+```
+
+
+
+**ask**
+
+```ts
+ws.on('connection', async (client) => {
+ const info = await ws.ask(client, 'identify')
+ console.log('Client says:', info)
+})
+```
+

package/docs/bootstrap/CLAUDE.md

@@ -0,0 +1,101 @@
+# Luca Project
+
+This project uses the [Luca framework](https://github.com/soederpop/luca) — Lightweight Universal Conversational Architecture.
+
+For a deep dive into the framework internals, see the [Luca GitHub repository](https://github.com/soederpop/luca).
+
+## Runtime
+
+The runtime is **bun**. Use `bun run` for scripts, `bun test` for tests.
+
+## The `luca` CLI
+
+The `luca` binary is available in the path. Key commands:
+
+- `luca` — list available commands (built-in + project commands)
+- `luca eval "expression"` — evaluate JS with the container in scope
+- `luca describe <name>` — full docs for any feature, client, or server (e.g. `luca describe fs`)
+- `luca describe <name>.<member>` — docs for a specific method or getter (e.g. `luca describe ui.banner`, `luca describe fs.readFile`)
+- `luca describe features` — index of all available features (also: `clients`, `servers`)
+- `luca serve` — start a local server using `endpoints/` folder
+- `luca run script.ts` — run a script with the container
+- `luca scaffold <type> <name>` — generate boilerplate for a new helper (run `luca scaffold` for full help)
+
+## Container Rules
+
+- **NEVER import from `fs`, `path`, or other Node builtins.** Use `container.feature('fs')` for file operations, `container.paths` for path operations.
+- The container should provide everything you need. If something is missing, raise the concern rather than pulling in external dependencies.
+- Use `container.utils` for common utilities (uuid, lodash helpers, string utils).
+
+## Learning the Framework
+
+1. **Discover** — Run `luca describe features`, `luca describe clients`, `luca describe servers` to see what's available. Then `luca describe <name>` for full docs on any helper, or `luca describe <name>.<member>` to drill into a specific method or getter. This is your first move, always. (See `.claude/skills/luca-framework/SKILL.md` for the full mental model.)
+2. **Build** — Run `luca scaffold <type> --tutorial` before creating a new helper. It covers the full guide for that type.
+3. **Prototype** — Use `luca eval "expression"` to test container code before wiring up full handlers. Reach for eval when you're stuck — it gives you full runtime access.
+4. **Reference** — The skill file (`.claude/skills/luca-framework/SKILL.md`) includes a full Framework Index with every feature, client, and server organized by category
+
+## Project Structure
+
+- `commands/` — custom CLI commands, run via `luca <commandName>` (auto-discovered)
+- `endpoints/` — file-based HTTP routes, served via `luca serve` (auto-discovered)
+- `features/` — custom container features, discovered via `container.helpers.discoverAll()` (auto-discovered)
+- `docs/` — content documents managed by the `contentDb` feature (`container.docs`). See [contentbase](https://github.com/soederpop/contentbase) for the document model system.
+- `luca.cli.ts` — optional project-level CLI customization (runs before any command)
+
+## Command Arguments
+
+Command handlers receive `(options, context)`. The `options` object contains:
+- **Named flags** from `argsSchema`: `--verbose` → `options.verbose`
+- **Positional args** mapped via `positionals` export: `luca cmd ./src` → `options.target`
+- **Raw positionals** in `options._`: array where `_[0]` is the command name, `_[1+]` are positional args
+
+To accept positional arguments, export a `positionals` array that maps them to named fields in `argsSchema`:
+
+```ts
+export const positionals = ['target']  // luca myCmd ./src => options.target === './src'
+export const argsSchema = z.object({
+  target: z.string().optional().describe('The target to operate on'),
+  verbose: z.boolean().default(false).describe('Enable verbose output'),
+})
+```
+
+## What's Available
+
+The container provides more than you might expect. Before importing anything external, check here:
+
+- **YAML** — `container.feature('yaml')` wraps `js-yaml`. Use `.parse(str)` and `.stringify(obj)`.
+- **SQLite** — `container.feature('sqlite')` for databases. Parameterized queries, tagged templates.
+- **REST client** — `container.client('rest', { baseURL })`. Methods (`get`, `post`, etc.) return **parsed JSON directly**, not `{ data, status, headers }`. On HTTP errors, the error is returned (not thrown).
+- **Content DB** — `container.docs` (alias for `container.feature('contentDb')`) manages markdown documents with frontmatter. Query with `docs.query(docs.models.MyModel).fetchAll()`.
+- **Grep** — `container.feature('grep')` has `search()` and `codeAnnotations()` for finding TODOs/FIXMEs/etc.
+- **chalk** — available as `container.feature('ui').colors`, not via `import('chalk')`.
+- **figlet** — available as `container.feature('ui').asciiArt(text)`.
+- **uuid** — `container.utils.uuid()`
+- **lodash** — `container.utils.lodash` (groupBy, keyBy, pick, omit, debounce, etc.)
+- **string utils** — `container.utils.stringUtils` (camelCase, kebabCase, pluralize, etc.)
+
+## Known Gotchas
+
+- **For DELETE endpoint handlers, use `export { del as delete }`** — `delete` is a JS reserved word. Define your function with any name, then re-export it as `delete`.
+- **Bun globals (`Bun.spawn`, `Bun.serve`) are unavailable** in command/endpoint handlers. Use Node's `child_process` for spawning processes, or use `container.feature('proc').exec()`.
+- **`ui.print.*` writes to stdout** — if your command supports `--json`, gate UI output behind `if (!options.json)`.
+- **VM contexts start empty** — when using `container.feature('vm')`, inject globals explicitly (`console`, `Date`, `Promise`, `crypto`, `TextEncoder`, `setTimeout`).
+- **Long-running commands** (servers, watchers) need `await new Promise(() => {})` at the end with a `process.on('SIGINT', ...)` handler for cleanup.
+- **Shared state between endpoints**: use `ctx.request.app.locals` to share data across endpoint files.
+- **Database init**: use `luca.cli.ts` `main()` hook for table creation and seeding — it runs before any command or server starts.
+
+## Extending the Container
+
+Use `luca scaffold` to generate new helpers:
+
+```sh
+luca scaffold command myTask --description "Automate something"
+luca scaffold feature myCache --description "Custom caching layer"
+luca scaffold endpoint users --description "User management API"
+```
+
+Run `luca scaffold` with no arguments for full usage and examples.
+
+## Git Strategy
+
+Roll on main. Commit with good messages that explain why, not just what.