luca 3.0.0 → 3.1.0

package/docs/apis/servers/mcp.md

@@ -1,238 +0,0 @@
-# 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

@@ -1,170 +0,0 @@
-# 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

@@ -1,101 +0,0 @@
-# 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.