@soederpop/luca 0.0.5 → 0.0.7

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

@@ -1,6 +1,6 @@
 # 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.
+Sandboxed JavaScript execution environment for the browser. Automatically injects the container's context object into the global scope, so evaluated code can use anything provided by the container. Useful for live code playgrounds, plugin systems, and dynamic script evaluation.
 
 ## Usage
 
@@ -69,16 +69,7 @@ container.feature('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'
+const result = vm.run('1 + 2 + 3') // 6
+const greeting = vm.run('container.uuid') // accesses container globals
 ```
 

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

@@ -1,6 +1,6 @@
 # VoiceRecognition (features.voice)
 
-VoiceRecognition helper
+Speech-to-text recognition using the Web Speech API (SpeechRecognition). Wraps the browser's built-in speech recognition, supporting continuous listening, interim results, and language selection. Recognized text is accumulated in state and emitted as events for real-time transcription UIs.
 
 ## Usage
 
@@ -65,3 +65,20 @@ Event emitted by VoiceRecognition
 
 Event emitted by VoiceRecognition
 
+
+
+## Examples
+
+**features.voice**
+
+```ts
+const voice = container.feature('voice', { continuous: true, autoListen: true })
+
+voice.on('transcript', ({ text }) => {
+ console.log('Heard:', text)
+})
+
+// Or start manually
+voice.start()
+```
+

package/docs/apis/servers/express.md

@@ -1,6 +1,6 @@
 # ExpressServer (servers.express)
 
-ExpressServer helper
+Express.js HTTP server with automatic endpoint mounting, CORS, and SPA history fallback. Wraps an Express application with convention-based endpoint discovery. Endpoints defined as modules are automatically mounted as routes. Supports static file serving, CORS configuration, and single-page app history fallback out of the box.
 
 ## Usage
 
@@ -124,4 +124,20 @@ container.server('express', {
 | `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 |
+| `stopped` | `boolean` | Whether the server has been stopped |
+
+## Examples
+
+**servers.express**
+
+```ts
+const server = container.server('express', { cors: true, static: './public' })
+await server.start({ port: 3000 })
+
+// Mount endpoints programmatically
+server.mount(myEndpoint)
+
+// Access the underlying Express app
+server.app.get('/health', (req, res) => res.json({ ok: true }))
+```
+

package/docs/apis/servers/mcp.md

@@ -158,25 +158,50 @@ Stop the MCP server and close all connections.
 
 ### toolRegistered
 
-Event emitted by MCPServer
+Emitted when a tool is registered
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Tool name |
 
 
 
 ### resourceRegistered
 
-Event emitted by MCPServer
+Emitted when a resource is registered
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Resource URI |
 
 
 
 ### promptRegistered
 
-Event emitted by MCPServer
+Emitted when a prompt is registered
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Prompt name |
 
 
 
 ### toolCalled
 
-Event emitted by MCPServer
+Emitted when a tool is called
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Tool name |
+| `arg1` | `any` | Arguments |
 
 
 

package/docs/apis/servers/websocket.md

@@ -1,6 +1,6 @@
 # WebsocketServer (servers.websocket)
 
-WebsocketServer helper
+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.
 
 ## Usage
 
@@ -10,7 +10,7 @@ container.server('websocket', {
   port,
   // Hostname or IP address to bind to
   host,
-  // Whether to automatically JSON parse/stringify messages
+  // When enabled, incoming messages are automatically JSON-parsed before emitting the message event, and outgoing send/broadcast calls JSON-stringify the payload
   json,
 })
 ```
@@ -21,7 +21,7 @@ container.server('websocket', {
 |----------|------|-------------|
 | `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 |
+| `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
 
@@ -79,13 +79,26 @@ container.server('websocket', {
 
 ### connection
 
-Event emitted by WebsocketServer
+Fires when a new client connects
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The raw WebSocket client instance from the ws library |
 
 
 
 ### message
 
-Event emitted by WebsocketServer
+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 |
 
 
 
@@ -96,4 +109,19 @@ Event emitted by WebsocketServer
 | `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 |
+| `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 })
+})
+```
+

package/docs/bootstrap/CLAUDE.md

@@ -0,0 +1,100 @@
+# 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 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. 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** — Browse `.claude/skills/luca-framework/references/api-docs/` for pre-generated API docs
+
+## 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.

package/docs/bootstrap/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: Using the luca framework
+description: Learn the luca container — discover what's available with luca describe, build new helpers with luca scaffold, and prototype with luca eval
+---
+# Luca: Learning the Container
+
+The Luca framework `@soederpop/luca` ships a `luca` binary — a bun-based CLI for a dependency injection container. This project is based on it if this skill is present. The container auto-discovers modules in `commands/`, `clients/`, `servers/`, `features/`, and `endpoints/` folders.
+
+There are three things to learn, in this order:
+
+1. **Discover** what the container can do — `luca describe`
+2. **Build** new helpers when your project needs them — `luca scaffold`
+3. **Prototype** and debug with live code — `luca eval`
+
+---
+
+## Phase 1: Discover with `luca describe`
+
+This is your primary tool. Before reading source files, searching for APIs, or writing any code — ask describe. It outputs full documentation for any part of the container: methods, options, events, state, examples.
+
+### See what's available
+
+```shell
+luca describe features     # index of all available features
+luca describe clients      # index of all available clients
+luca describe servers      # index of all available servers
+```
+
+### Learn about specific helpers
+
+```shell
+luca describe fs           # full docs for the fs feature
+luca describe git          # full docs for git
+luca describe rest         # full docs for the rest client
+luca describe express      # full docs for the express server
+luca describe git fs proc  # multiple helpers in one shot
+```
+
+### Get targeted documentation
+
+You can filter to only the sections you need:
+
+```shell
+luca describe fs --methods          # just the methods
+luca describe git --events          # just the events it emits
+luca describe express --options     # just the constructor options
+luca describe fs git --examples     # just examples for both
+luca describe fs --usage --methods  # combine sections
+```
+
+### Describe the container itself
+
+```shell
+luca describe              # overview of the container
+luca describe self         # same thing
+```
+
+### Get help on any command
+
+```shell
+luca                       # list all available commands
+luca describe --help       # full flag reference for describe
+luca help scaffold         # help for any command
+```
+
+**Use `luca describe` liberally.** It is the fastest, safest way to understand what the container provides. Every feature, client, and server is self-describing — if you know a name, describe will tell you everything about it.
+
+---
+
+## Phase 2: Build with `luca scaffold`
+
+When your project needs a new helper, scaffold it. The `scaffold` command generates correct boilerplate — you fill in the logic.
+
+### Learn how to build each type
+
+Before creating anything, read the tutorial for that helper type:
+
+```shell
+luca scaffold feature --tutorial    # how features work, full guide
+luca scaffold command --tutorial    # how commands work
+luca scaffold endpoint --tutorial   # how endpoints work
+luca scaffold client --tutorial     # how clients work
+luca scaffold server --tutorial     # how servers work
+```
+
+These tutorials are the authoritative reference for each helper type. They cover imports, schemas, class structure, registration, conventions, and complete examples.
+
+### Generate a helper
+
+```shell
+luca scaffold <type> <name> --description "What it does"
+```
+
+The workflow after scaffolding:
+
+```shell
+luca scaffold command sync-data --description "Pull data from staging"
+# edit commands/sync-data.ts — add your logic
+luca describe sync-data            # verify it shows up and reads correctly
+```
+
+Every scaffolded helper is auto-discovered by the container at runtime.
+
+### When to use each type
+
+| You need to...                                     | Scaffold a...  | Example                                                        |
+|----------------------------------------------------|----------------|----------------------------------------------------------------|
+| Add a reusable local capability (caching, crypto)  | **feature**    | `luca scaffold feature disk-cache --description "File-backed key-value cache"` |
+| Add a CLI task (build, deploy, generate)           | **command**    | `luca scaffold command deploy --description "Deploy to production"` |
+| Talk to an external API or service                 | **client**     | `luca scaffold client github --description "GitHub API wrapper"` |
+| Accept incoming connections (HTTP, WS)             | **server**     | `luca scaffold server mqtt --description "MQTT broker"` |
+| Add a REST route to `luca serve`                   | **endpoint**   | `luca scaffold endpoint users --description "User management API"` |
+
+### Scaffold options
+
+```shell
+luca scaffold command deploy --description "..."    # writes to commands/deploy.ts
+luca scaffold endpoint users --print                # print to stdout instead of writing
+luca scaffold feature cache --output lib/cache.ts   # override output path
+```
+
+---
+
+## Phase 3: Prototype with `luca eval`
+
+Once you know what's available (describe) and how to build things (scaffold), use `luca eval` to test ideas, verify behavior, and debug.
+
+```shell
+luca eval "container.features.available"
+luca eval "container.feature('proc').exec('ls')"
+luca eval "container.feature('fs').readFile('package.json')"
+```
+
+The eval command boots a full container with all helpers discovered and registered. Core features are available as top-level shortcuts:
+
+```shell
+luca eval "fs.readFile('package.json')"
+luca eval "git.branch"
+luca eval "proc.exec('ls')"
+```
+
+**Reach for eval when you're stuck.** It gives you full control of the container at runtime — you can test method calls, inspect state, verify event behavior, and debug issues that are hard to reason about from docs alone.
+
+**Use eval as a testing tool.** Before wiring up a full command handler or feature, test your logic in eval first. Want to verify how `fs.moveAsync` behaves, or whether a watcher event fires the way you expect? Run it in eval. This is the fastest way to validate container code without the overhead of building the full command around it.
+
+```shell
+# Test file operations before building a command around them
+luca eval "await fs.moveAsync('inbox/test.json', 'inbox/valid/test.json')"
+
+# First: luca describe fileManager --events  (to learn what events exist)
+# Then test the behavior:
+luca eval "const fm = container.feature('fileManager'); fm.on('file:change', (e) => console.log(e)); await fm.watch({ paths: ['inbox'] })"
+```
+
+### The REPL
+
+For interactive exploration, `luca console` opens a persistent REPL with the container in scope. Useful when you need to try multiple things in sequence.
+
+---
+
+## Key Concepts
+
+### The Container
+
+The container is a singleton that holds everything your application needs. It organizes components into **registries**: features, clients, servers, commands, and endpoints. Use the factory functions to get instances:
+
+```js
+const fs = container.feature('fs')
+const rest = container.client('rest')
+const server = container.server('express')
+```
+
+### State
+
+Every helper and the container itself have observable state:
+
+```js
+const feature = container.feature('fs')
+
+feature.state.current              // snapshot of all state
+feature.state.get('someKey')       // single value
+feature.state.set('key', 'value')  // update
+
+// Watch for changes
+feature.state.observe((changeType, key, value) => {
+  // changeType: 'add' | 'update' | 'delete'
+})
+```
+
+The container has state too: `container.state.current`, `container.state.observe()`.
+
+### Events
+
+Every helper and the container are event emitters — `on`, `once`, `emit`, `waitFor` all work as expected. Use `luca describe <name> --events` to see what a helper emits.
+
+### Utilities
+
+The container provides common utilities at `container.utils` — no external imports needed:
+
+- `container.utils.uuid()` — v4 UUID
+- `container.utils.hashObject(obj)` — deterministic hash
+- `container.utils.stringUtils` — camelCase, kebabCase, pluralize, etc.
+- `container.utils.lodash` — groupBy, keyBy, pick, omit, debounce, etc.
+- `container.paths.resolve()` / `container.paths.join()` — path operations
+
+### Programmatic introspection
+
+Everything `luca describe` outputs is also available at runtime in code:
+
+```js
+container.features.describe('fs')   // markdown docs (same as the CLI)
+feature.introspect()                // structured object: { methods, events, state, options }
+container.inspectAsText()           // full container overview as markdown
+```
+
+This is useful inside commands and scripts where you need introspection data programmatically.
+
+---
+
+## Reference
+
+See `references/api-docs/` for the full pre-generated API reference for every built-in feature, client, and server.

package/docs/bootstrap/templates/about-command.ts

@@ -0,0 +1,41 @@
+/**
+ * about — Display project information and discovered helpers.
+ * Run with: luca about
+ *
+ * Positional words after the command name are available as options._
+ * For example: `luca about commands` → options._[1] === 'commands'
+ */
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+
+export const description = 'Display project information and discovered helpers'
+
+export const argsSchema = z.object({})
+
+export default async function about(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+  const ui = container.feature('ui')
+
+  // Discover all project-level helpers (commands, features, endpoints, etc.)
+  const discovered = await container.helpers.discoverAll()
+
+  const projectName = container.paths.resolve('.').split('/').pop() || 'project'
+
+  ui.print.cyan(`\n  ${projectName}\n`)
+  ui.print('  Powered by luca — Lightweight Universal Conversational Architecture\n')
+
+  const types = ['features', 'clients', 'servers', 'commands', 'endpoints']
+
+  for (const type of types) {
+    const names = discovered[type] || []
+    if (names.length > 0) {
+      ui.print.green(`  ${type} (${names.length})`)
+      for (const name of names) {
+        ui.print(`    • ${name}`)
+      }
+    }
+  }
+
+  const totalBuiltIn = types.reduce((sum: number, t: string) => sum + (container[t]?.available?.length || 0), 0)
+  ui.print.dim(`\n  ${totalBuiltIn} built-in helpers available. Run \`luca describe\` for details.\n`)
+}

package/docs/bootstrap/templates/docs-models.ts

@@ -0,0 +1,22 @@
+import { defineModel, z } from 'contentbase'
+
+/**
+ * Define your content models here. Each model maps to a folder prefix
+ * inside the docs/ directory. Documents in those folders follow the
+ * model's metadata schema.
+ *
+ * Access documents at runtime:
+ *   const docs = container.docs          // contentDb feature
+ *   if (!docs.isLoaded) await docs.load()
+ *   const notes = await docs.query(docs.models.Note).fetchAll()
+ *
+ * See https://github.com/soederpop/contentbase for full documentation.
+ */
+
+export const Note = defineModel('Note', {
+  prefix: 'notes',
+  meta: z.object({
+    tags: z.array(z.string()).default([]),
+    status: z.enum(['draft', 'published']).default('draft'),
+  }),
+})

package/docs/bootstrap/templates/docs-readme.md

@@ -0,0 +1,43 @@
+# Docs
+
+This folder contains structured content documents managed by the [contentbase](https://github.com/soederpop/contentbase) system.
+
+## How it works
+
+Documents are markdown files with YAML frontmatter. Each document belongs to a **model** defined in `docs/models.ts`. Models specify:
+- A **prefix** (subfolder name, e.g. `notes/`)
+- A **metadata schema** (validated frontmatter fields)
+
+## Accessing documents at runtime
+
+The `contentDb` feature (aliased to `container.docs`) loads and queries documents:
+
+```typescript
+const docs = container.docs
+if (!docs.isLoaded) await docs.load()
+
+// Query all notes
+const notes = await docs.query(docs.models.Note).fetchAll()
+
+// Get a specific document
+const doc = docs.collection('notes').document('my-note')
+```
+
+## Creating a new document
+
+Add a markdown file in the appropriate subfolder:
+
+```markdown
+---
+title: My First Note
+tags: [example]
+status: draft
+---
+
+Content goes here.
+```
+
+## Learn more
+
+- [Contentbase GitHub](https://github.com/soederpop/contentbase) — full documentation and API reference
+- `luca describe contentDb` — runtime docs for the contentDb feature