@soederpop/luca 0.0.2

package/docs/reports/introspection-audit-tasks.md

@@ -0,0 +1,378 @@
+# Introspection Audit Results
+
+This audit evaluates whether the `introspectAsText()` output for each feature is sufficient for an LLM (or developer) to understand the feature's purpose and build working code with it.
+
+Generated by running `luca describe <feature>` for each feature after regenerating introspection data.
+
+## Features
+
+### [diskCache](src/node/features/disk-cache.ts)
+
+File-backed key-value cache built on top of the cacache library (the same store that powers npm). Suitable for persisting arbitrary data including very large blobs when necessary, with optional encryption support.
+
+- Securely store and retrieve encrypted secrets across processes using the vault-backed cache
+- Cache large file blobs (images, models, API responses) with `set`/`get`/`has`/`ensure` for deduplication
+- Query and manage cached keys (`ls`, `copy`, `move`, `rm`, `clearAll`)
+- Save cached content directly to disk files with `saveFile`, supporting base64 decoding
+
+### [contentDb](src/node/features/content-db.ts)
+
+ContentDb feature provides a database-like interface for working with collections of markdown/YAML files on disk. Each file is a "document" with frontmatter metadata and body content, organized into typed collections. Powered by the Contentbase library.
+
+- Load a folder of markdown files as a queryable collection with typed schemas
+- Create, update, and delete content documents with automatic frontmatter management
+- Query documents by metadata fields (e.g. find all posts with `status: draft`)
+- Watch content directories for changes and react to file updates
+
+### [downloader](src/node/features/downloader.ts)
+
+The Downloader feature downloads files from the internet. It supports downloading files from URLs and saving them to the local file system.
+
+- Download files from URLs to local paths
+- Batch download multiple files in parallel
+- Resume interrupted downloads with range request support
+- Download with progress tracking and event callbacks
+
+### [esbuild](src/node/features/esbuild.ts)
+
+The Esbuild feature provides a bundling and transpilation interface for JavaScript/TypeScript projects via esbuild. Useful for building single-file bundles, compiling TypeScript, and transforming code.
+
+- Bundle a TypeScript project into a single distributable file
+- Transpile modern JS/TS for compatibility with older runtimes
+- Build CLI tools as self-contained executables
+- Watch mode for development builds with automatic recompilation
+
+### [fileManager](src/node/features/file-manager.ts)
+
+The FileManager feature creates a database-like index of all of the files in the project, and provides metadata about these files, and also provides a way to watch for changes to the files.
+
+- Scan a project directory and build a searchable index of all files with metadata
+- Match files against glob patterns (e.g. find all `*.ts` files, all `*.test.*` files)
+- Watch the file system for real-time change notifications (create, modify, delete)
+- Get file metadata (path, extension, size) for project analysis
+
+### [fs](src/node/features/fs.ts)
+
+File system utilities for reading, writing, and managing files. Wraps Node.js fs operations with convenience methods and path resolution relative to the container's working directory.
+
+- Read and write files with automatic path resolution from the container's cwd
+- Check file existence, create directories, and manage file system operations
+- Copy, move, and delete files and directories
+- Read directory contents and walk directory trees
+
+### [git](src/node/features/git.ts)
+
+The Git feature provides utilities for interacting with Git repositories. Allows you to check repository status, list files, get branch information, and access Git metadata for projects within a Git repository.
+
+- List tracked/modified/untracked files using `lsFiles` with flexible filter options
+- Get recent commit history with `getLatestChanges` and per-file commit logs with `fileLog`
+- Diff files between branches, commits, or tags with colorized terminal output
+- Query branch name, SHA, repo root, and whether the current directory is a git repo
+
+### [grep](src/node/features/grep.ts)
+
+The Grep feature provides utilities for searching file contents using ripgrep (rg) or grep. Returns structured results as arrays of `{ file, line, column, content }` objects with paths relative to the container cwd.
+
+- Search for patterns across files with structured results (`search`)
+- Find import/require statements for a module (`imports`)
+- Find function, class, and variable definitions by name (`definitions`)
+- Find all TODO/FIXME/HACK comments in the codebase (`todos`)
+
+### [ipcSocket](src/node/features/ipc-socket.ts)
+
+IPC feature providing robust inter-process communication via Unix domain sockets. Supports both server and client modes with JSON message serialization, broadcast messaging, and automatic socket cleanup.
+
+- Stand up a local IPC server on a Unix socket for multi-process coordination
+- Connect as a client to an existing IPC server and exchange JSON messages
+- Broadcast messages to all connected clients simultaneously
+- Coordinate between a parent process and multiple worker processes
+
+### [jsonTree](src/node/features/json-tree.ts)
+
+Recursively loads JSON files from a directory structure and builds a hierarchical tree representation. Automatically processes file paths to create a nested object structure where file paths become camelCased property paths.
+
+- Load a directory of JSON config files into a single queryable tree object
+- Merge multiple JSON data sources into a unified hierarchical structure
+- Access nested configuration values using dot-notation property paths
+- Build runtime configuration from a file-based config directory structure
+
+### [networking](src/node/features/networking.ts)
+
+The Networking feature provides utilities for network-related operations including port detection and availability checking.
+
+- Find the next available port starting from a given number (`findOpenPort`)
+- Check if a specific port is in use before binding a server (`isPortOpen`)
+- Dynamically allocate ports for dev servers to avoid conflicts
+- Validate port availability before configuring service endpoints
+
+### [os](src/node/features/os.ts)
+
+Operating system utilities providing information about the current platform, CPU, memory, and environment.
+
+- Query current platform details (OS, arch, CPU count, memory)
+- Detect the runtime environment (macOS, Linux, Windows)
+- Get system-level info for adaptive behavior in scripts
+- Check available system resources before spawning heavy processes
+
+### [packageFinder](src/node/features/package-finder.ts)
+
+Discovers and indexes package.json files across a monorepo or project tree. Provides structured access to package metadata including names, versions, dependencies, and scripts.
+
+- Discover all packages in a monorepo and index their metadata
+- Query package dependencies and dev-dependencies across the workspace
+- Find which packages define a specific npm script
+- Map package names to their file system paths for tooling integration
+
+### [portExposer](src/node/features/port-exposer.ts)
+
+**NOTE**: This seems to be wrong.  ngrok is what is used not cloudflare.
+
+Expose local ports to the internet via Cloudflare Tunnel (`cloudflared`). Creates temporary public URLs for local development servers, webhook testing, and demos.
+
+- Expose a local dev server to the internet for webhook testing or demos
+- Create temporary public URLs for sharing work-in-progress with teammates
+- Set up tunnels for services like Telegram webhook mode that require public HTTPS
+- Programmatically manage tunnel lifecycle (start, stop, get URL)
+
+### [python](src/node/features/python.ts)
+
+Python integration feature for running Python scripts, managing virtual environments, and calling Python functions from TypeScript.
+
+- Run Python scripts from TypeScript with captured stdout/stderr
+- Create and manage Python virtual environments with pip package installation
+- Execute Python code inline and capture results
+- Bridge Python and TypeScript for ML/AI workflows that need Python libraries
+
+### [proc](src/node/features/proc.ts)
+
+Process execution feature for running shell commands and capturing output. Provides both fire-and-forget execution (`exec`) and output-capturing execution (`execAndCapture`, `spawnAndCapture`).
+
+- Run shell commands and capture stdout/stderr with `execAndCapture`
+- Execute commands fire-and-forget style for side effects with `exec`
+- Spawn processes with fine-grained control over stdio streams
+- Run commands in specific directories with custom environment variables
+
+### [repl](src/node/features/repl.ts)
+
+REPL feature — provides an interactive read-eval-print loop with tab completion and history. Launches a REPL session that evaluates JavaScript/TypeScript expressions in a sandboxed VM context populated with the container and its helpers.
+
+- Drop into an interactive REPL with full access to the container and all features
+- Explore the container's API interactively with tab completion for property access
+- Persist command history across sessions for rapid prototyping
+- Inject custom variables into the REPL context for debugging
+
+### [ui](src/node/features/ui.ts)
+
+Terminal UI toolkit featuring ASCII art banners, color gradients, interactive wizards (prompts), and text formatting utilities. Powered by chalk, figlet, and inquirer.
+
+- Create styled ASCII art banners with color gradients for CLI tool branding
+- Build interactive setup wizards with multi-type prompts (input, list, confirm, checkbox)
+- Apply horizontal/vertical color gradients to terminal text and ASCII art
+- Open content in the user's `$EDITOR` for interactive editing (code, config, markdown)
+
+### [vault](src/node/features/vault.ts)
+
+The Vault feature provides encryption and decryption capabilities using AES-256-GCM. Manages secret keys and provides a simple interface for cryptographic operations.
+
+- Encrypt sensitive data (API keys, tokens) before storing to disk or cache
+- Decrypt previously encrypted payloads when needed at runtime
+- Generate and manage encryption secret keys
+- Pair with diskCache for an encrypted key-value store
+
+### [vm](src/node/features/vm.ts)
+
+The VM feature provides Node.js virtual machine capabilities for executing JavaScript code in isolated contexts. Wraps Node.js's built-in `vm` module for secure sandboxed execution.
+
+- Execute untrusted or dynamic JavaScript code in a sandboxed context
+- Run code with custom variables injected into the execution context
+- Load JavaScript/TypeScript modules into isolated VM contexts with `loadModule`
+- Create reusable compiled scripts for repeated execution with different inputs
+
+### [yamlTree](src/node/features/yaml-tree.ts)
+
+Recursively loads YAML files from a directory structure and builds a hierarchical tree representation. Supports both `.yml` and `.yaml` extensions with automatic camelCase path conversion.
+
+- Load a directory of YAML config files into a single queryable tree object
+- Build hierarchical configuration from nested YAML file structures
+- Access configuration values using dot-notation paths derived from file paths
+- Hot-reload configuration by re-running `loadTree` when files change
+
+### [yaml](src/node/features/yaml.ts)
+
+YAML parsing and serialization utilities. Wraps the js-yaml library to provide convenient `parse` and `dump` methods for converting between YAML strings and JavaScript objects.
+
+- Parse YAML strings into JavaScript objects
+- Serialize JavaScript objects into YAML strings
+- Convert between YAML and JSON formats
+- Read and parse YAML configuration files
+
+### [docker](src/node/features/docker.ts)
+
+Docker container management feature for building, running, and managing Docker containers programmatically. Supports image management, container lifecycle, volume mounts, shell sessions inside containers, and Dockerfile generation.
+
+- Build Docker images from Dockerfiles and manage the image lifecycle
+- Run containers with port mapping, volume mounts, and environment variables
+- Open interactive shell sessions inside running containers with `createShell`
+- Execute commands inside running containers and capture output
+
+### [runpod](src/node/features/runpod.ts)
+
+RunPod feature — manage GPU cloud pods, templates, volumes, and SSH connections via the RunPod REST API. Provides a complete interface for provisioning and managing RunPod GPU instances.
+
+- Provision GPU pods from templates for ML training or inference workloads
+- Manage network storage volumes for persistent data across pod lifecycles
+- SSH into running pods and transfer files using the integrated SecureShell feature
+- Poll pod readiness and automate the full pod lifecycle (create, wait, use, destroy)
+
+### [secureShell](src/node/features/secure-shell.ts)
+
+SSH client feature for remote command execution and file transfer. Wraps ssh2 to provide a high-level interface for connecting to remote servers, running commands, and transferring files.
+
+- Execute commands on remote servers over SSH and capture output
+- Upload and download files to/from remote servers via SFTP
+- Test SSH connectivity before running remote operations
+- Automate deployment scripts that run commands on production servers
+
+### [tmux](src/node/features/tmux.ts)
+
+Terminal multiplexer feature that wraps tmux to provide programmatic control over terminal panes. Allows scripts to split the terminal into multiple panes, run commands in each pane with process handles, and collapse everything back when done.
+
+- Split the terminal into multiple panes and run parallel commands visually
+- Monitor long-running processes (tests, builds, servers) in separate panes
+- Programmatically send keystrokes and capture pane output
+- Build dashboards that display multiple process outputs simultaneously
+
+### [ink](src/node/features/ink.ts)
+
+React-powered Terminal UI via Ink. Exposes the Ink library (React for CLIs) so any feature or script can build rich terminal user interfaces using React components rendered directly in the terminal.
+
+- Build interactive CLI applications with React components (Box, Text, Spacer)
+- Create real-time updating terminal UIs for monitoring and dashboards
+- Use React hooks (useState, useEffect, useInput) for terminal interactivity
+- Render animated spinners, progress bars, and tables in the terminal
+
+### [telegram](src/node/features/telegram.ts)
+
+Telegram bot feature powered by grammY. Supports both long-polling and webhook modes. Exposes the grammY Bot instance directly for full API access while bridging events to Luca's event bus.
+
+- Create a Telegram bot that responds to commands and messages
+- Run the bot in long-polling mode for development or webhook mode for production
+- Register command handlers and grammY middleware for message processing
+- Bridge Telegram events to the container's event bus for integration with other features
+
+### [opener](src/node/features/opener.ts)
+
+Opens files, URLs, desktop applications, and code editors. HTTP/HTTPS URLs open in Chrome, desktop apps launch by name, and VS Code/Cursor can open to a specific path.
+
+- Open URLs in Chrome from scripts or automation workflows
+- Launch desktop applications by name (Slack, Finder, Safari)
+- Open project directories in VS Code or Cursor from the command line
+- Open files with the system default handler (images in Preview, etc.)
+
+### [postgres](src/node/features/postgres.ts)
+
+Postgres feature for safe SQL execution through Bun's native SQL client. Supports parameterized queries, tagged-template SQL, and connection lifecycle management.
+
+- Execute parameterized SELECT queries and get typed result rows
+- Run INSERT/UPDATE/DELETE statements with row count feedback
+- Use tagged template literals for safe SQL interpolation (prevents injection)
+- Manage connection lifecycle with events for monitoring query activity
+
+### [sqlite](src/node/features/sqlite.ts)
+
+SQLite feature for safe SQL execution through Bun's native sqlite binding. Supports parameterized queries, tagged-template SQL, and in-memory databases.
+
+- Create and query local SQLite databases for embedded data storage
+- Use tagged template literals for safe SQL interpolation (prevents injection)
+- Run in-memory databases for testing and ephemeral data processing
+- Execute DDL and DML statements with change tracking and row count feedback
+
+### [googleAuth](src/node/features/google-auth.ts)
+
+Google OAuth2 authentication feature. Manages OAuth2 token lifecycle including authorization URL generation, token exchange, automatic refresh, and persistent token storage via diskCache.
+
+- Authenticate with Google APIs using OAuth2 with automatic token refresh
+- Generate authorization URLs for the OAuth2 consent flow
+- Persist and restore OAuth2 tokens across process restarts via diskCache
+- Provide authenticated API clients to other Google features (Drive, Sheets, Docs)
+
+### [googleDrive](src/node/features/google-drive.ts)
+
+Google Drive feature for file and folder management. Supports listing, searching, creating folders, uploading, downloading, and deleting files via the Drive API.
+
+- List and search files in Google Drive by name, type, or folder
+- Upload local files to Google Drive with metadata
+- Download files from Google Drive to local disk
+- Create folders and manage Drive file hierarchy programmatically
+
+### [googleSheets](src/node/features/google-sheets.ts)
+
+Google Sheets feature for reading and writing spreadsheet data. Provides a high-level interface for cell/range operations, row appending, sheet management, and batch updates.
+
+- Read and write cell ranges in Google Sheets programmatically
+- Append rows of data to spreadsheets for logging or data collection
+- Create new sheets and manage spreadsheet structure
+- Batch-update multiple ranges in a single API call for performance
+
+### [googleCalendar](src/node/features/google-calendar.ts)
+
+Google Calendar feature for reading and managing calendar events. Supports listing calendars, querying events by time range, creating/updating/deleting events, and freetext search.
+
+- List calendars and query today's or upcoming events
+- Create, update, and delete calendar events programmatically
+- Search events by freetext query across summaries and descriptions
+- Build calendar-aware automation (e.g. daily briefings, scheduling bots)
+
+### [googleDocs](src/node/features/google-docs.ts)
+
+Google Docs feature for reading documents and converting them to Markdown. Handles headings, text formatting, links, lists, tables, and images.
+
+- Read Google Docs and convert to Markdown for local processing
+- Extract plain text from documents for NLP or search indexing
+- Save Google Docs as local Markdown files for documentation workflows
+- List and search Google Docs in Drive for programmatic access
+
+### [windowManager](src/node/features/window-manager.ts)
+
+Native window control via LucaVoiceLauncher IPC. Communicates over a Unix domain socket using NDJSON to spawn, navigate, focus, close, eval JavaScript in, and screenshot native browser windows.
+
+- Spawn native browser windows with configurable chrome (decorations, transparency, always-on-top)
+- Navigate, focus, close, and evaluate JavaScript in managed windows
+- Capture screenshots and record video from window contents
+- Spawn native terminal windows running commands with ANSI support
+
+### [launcherAppCommandListener](src/node/features/launcher-app-command-listener.ts)
+
+IPC transport for commands from the LucaVoiceLauncher app. Listens on a Unix domain socket for the native macOS launcher app to connect and dispatches voice/hotkey/text commands as `CommandHandle` events.
+
+- Listen for voice commands from the native macOS launcher app
+- Acknowledge, track progress, and finish command processing via the handle API
+- Bridge voice/hotkey input to container feature actions
+- Build voice-controlled automation workflows
+
+### [nlp](src/node/features/nlp.ts)
+
+Natural language processing utilities combining compromise (verb normalization, POS patterns) and wink-nlp (high-accuracy POS tagging, NER). Three levels of detail: `parse`, `analyze`, `understand`.
+
+- Parse voice commands into structured intent/target/subject for command dispatch
+- Extract named entities (people, times, places) from natural language input
+- Normalize verb forms to infinitives for consistent intent matching
+- Combine POS tagging with intent parsing for full utterance understanding
+
+### [processManager](src/node/features/process-manager.ts)
+
+Manages long-running child processes with tracking, events, and automatic cleanup. Unlike `proc`, returns a SpawnHandler immediately with its own state, events, and lifecycle methods.
+
+- Spawn and track multiple long-running processes (servers, watchers, build tools)
+- Monitor process stdout/stderr in real-time via event handlers
+- Tag processes for easy lookup and management (`getByTag`)
+- Automatically kill all tracked processes on parent exit for clean shutdown
+
+### [tts](src/node/features/tts.ts)
+
+TTS feature — synthesizes text to audio files via RunPod's Chatterbox Turbo endpoint. Supports 20 preset voices and voice cloning via a reference audio URL.
+
+- Generate speech audio files from text using 20 preset voices
+- Clone a custom voice by providing a reference audio URL
+- Save generated audio in WAV, FLAC, or OGG formats
+- Build voice-enabled applications and voice command feedback systems

package/docs/reports/luca-mcp-improvements.md

@@ -0,0 +1,128 @@
+---
+tags:
+  - mcp
+  - testing
+  - scaffolding
+---
+
+## Problem
+
+The luca MCP server (`luca sandbox-mcp`) had 5 introspection tools that Claude Code rarely used. When given tasks in luca projects, Claude Code would default to vanilla Node.js patterns — importing `fs`, `path`, installing npm packages — instead of using the container. The MCP wasn't teaching Claude Code *how* to work in the luca ecosystem.
+
+The root cause: tool descriptions were informational but not prescriptive. They described what the tools do, but didn't tell Claude Code *when* to use them or *what workflow to follow*.
+
+## What We Changed
+
+### New MCP Tools
+
+| Tool | Purpose | Why It Matters |
+|---|---|---|
+| `read_me` | Returns the behavioral contract — import rules, capability map, workflow | Gives Claude Code the "rules of the road" at session start. Verbose description tells it to call this BEFORE writing code. |
+| `find_capability` | Returns full catalog of all features/clients/servers with descriptions | Single call that shows everything the container provides. Prevents the "I don't know what's available so I'll use npm" failure mode. |
+| `scaffold` | Generates convention-correct boilerplate for any helper type | Eliminates guessing at patterns. Output includes schemas, JSDoc, module augmentation, registration — all the pieces Claude Code would otherwise get wrong. |
+
+### Improved Existing Tools
+
+- **`eval`**: Added "Use this to prototype and test container API calls before writing them into files" to the description
+- **`describe_helper`**: Added "This is the API documentation — there is no other documentation available" to make it the authoritative source
+- **`inspect_helper_instance`**: Added "Use this to inspect a live, running instance" to distinguish from static docs
+
+### Scaffold System
+
+Created `docs/scaffolds/` with tutorial+template markdown files for each helper type:
+- `feature.md`, `client.md`, `server.md`, `command.md`, `endpoint.md`
+
+Each scaffold:
+- Explains WHY each section exists (for human learning)
+- Uses `{{PascalName}}`, `{{camelName}}`, `{{description}}` template variables
+- Includes a "Complete Example" that becomes the scaffold output
+- Lists conventions and common mistakes
+
+Build pipeline: `luca build-scaffolds` reads the markdown, extracts code blocks, generates `src/scaffolds/generated.ts`. This is imported by `sandbox-mcp.ts` and baked into the binary.
+
+### z Re-export
+
+Added `export { z } from 'zod'` to `src/node.ts` so consumer code can write `import { z } from '@soederpop/luca'` without needing zod installed.
+
+### CLI Command
+
+`luca scaffold <type> <name>` also available from the terminal, not just the MCP. Supports `--output` to write directly to a file and `--tutorial` to show the full teaching doc.
+
+## Design Principles
+
+1. **Prescriptive over informational** — Tool descriptions tell Claude Code exactly when and why to call each tool, not just what it returns
+2. **One call to orient** — `read_me` + `find_capability` in two calls gives a complete picture. No need to explore incrementally.
+3. **Correct by construction** — `scaffold` output is valid, convention-following code. The LLM fills in implementation, not boilerplate.
+4. **Source of truth in markdown** — Scaffold templates live in `docs/scaffolds/*.md` as human-readable tutorials. The build script extracts code. One source, two consumers.
+
+## Testing Approach
+
+### Test Harness
+
+Located in `playground/mcp-test/`. Simulates a consumer project:
+- `.mcp.json` pointing at `luca sandbox-mcp`
+- Minimal `CLAUDE.md` saying "this is a luca project, use the MCP"
+- No luca source to read — the MCP is the only interface
+
+### Challenges (Progressive Difficulty)
+
+| # | Challenge | What It Tests |
+|---|---|---|
+| 01 | Build a `greet` command | Basic: Does it use the command pattern? Correct imports? |
+| 02 | Build a `stopwatch` feature | Medium: Schemas, state, events, JSDoc, module augmentation |
+| 03 | Build a todo REST API with endpoints | Hard: File-based routing, Zod validation, endpoint conventions |
+| 04 | Build a REST client + command that uses it | Expert: Client pattern, cross-helper composition |
+
+### Workflow
+
+```
+# 1. Run a challenge (Claude Code session in the test folder)
+luca run-test --challenge 01-easy-command --clean
+
+# 2. Review the output (separate Claude Code session grades it)  
+luca run-test --challenge 01-easy-command --review
+
+# 3. Read the review
+cat output/review-01-easy-command.md
+
+# 4. Apply MCP improvements based on findings
+# Edit docs/mcp/readme.md, docs/scaffolds/*.md, or tool descriptions
+
+# 5. Rebuild scaffolds
+luca build-scaffolds
+
+# 6. Re-run the same challenge to see if improvements helped
+luca run-test --challenge 01-easy-command --clean
+```
+
+### Grading Criteria
+
+Each review evaluates:
+- **Import compliance** — Only `@soederpop/luca` imports, no Node builtins, no npm
+- **Pattern compliance** — Correct base class, schemas, static properties, registration
+- **Convention compliance** — `.describe()` on Zod fields, JSDoc, naming conventions
+- **MCP tool usage** — Did it call `read_me` first? Use `scaffold`? Use `find_capability`?
+
+### Success Criteria
+
+The MCP is "done" when:
+1. All four challenges pass import + pattern compliance on the first run
+2. Claude Code calls `read_me` and at least one discovery tool before writing code
+3. The generated code could be copy-pasted into any luca project and work
+
+## Files Created/Modified
+
+### New files
+- `docs/mcp/readme.md` — Behavioral contract
+- `docs/scaffolds/{feature,client,server,command,endpoint}.md` — Scaffold templates
+- `commands/build-scaffolds.ts` — Build script
+- `src/scaffolds/generated.ts` — Generated template data
+- `src/scaffolds/template.ts` — Shared template helpers
+- `src/commands/scaffold.ts` — CLI scaffold command
+- `playground/mcp-test/` — End-to-end test harness
+
+### Modified files
+- `src/commands/sandbox-mcp.ts` — Added 3 tools, improved descriptions
+- `src/commands/index.ts` — Registered scaffold command
+- `src/node.ts` — Added z re-export
+- `package.json` — Added build:scaffolds to pipeline

package/docs/scaffolds/client.md

@@ -0,0 +1,140 @@
+# Building a Client
+
+A client is a container-managed connection to an external service. Clients handle network communication — HTTP APIs, WebSocket connections, GraphQL endpoints. They extend `RestClient` (for HTTP), `WebSocketClient` (for WS), or the base `Client` class.
+
+When to build a client:
+- You need to talk to an external API or service
+- You want connection management, error handling, and observability for free
+- You're wrapping an API so the rest of the codebase uses `container.client('name')`
+
+## Imports
+
+```ts
+import { z } from 'zod'
+import { Client, clients, RestClient } from '@soederpop/luca/client'
+import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca'
+import type { ContainerContext } from '@soederpop/luca'
+```
+
+Use `RestClient` for HTTP APIs (most common). It gives you `get`, `post`, `put`, `patch`, `delete` methods that handle JSON, headers, and error wrapping.
+
+## Schemas
+
+```ts
+export const {{PascalName}}StateSchema = ClientStateSchema.extend({
+  // Add your state fields here.
+  // Example: authenticated: z.boolean().default(false).describe('Whether API auth is configured'),
+})
+export type {{PascalName}}State = z.infer<typeof {{PascalName}}StateSchema>
+
+export const {{PascalName}}OptionsSchema = ClientOptionsSchema.extend({
+  // Add constructor options here.
+  // Example: apiKey: z.string().optional().describe('API key for authentication'),
+})
+export type {{PascalName}}Options = z.infer<typeof {{PascalName}}OptionsSchema>
+```
+
+## Class
+
+```ts
+/**
+ * {{description}}
+ *
+ * @example
+ * ```typescript
+ * const {{camelName}} = container.client('{{camelName}}')
+ * ```
+ *
+ * @extends RestClient
+ */
+export class {{PascalName}} extends RestClient<{{PascalName}}State, {{PascalName}}Options> {
+  static override shortcut = 'clients.{{camelName}}' as const
+  static override stateSchema = {{PascalName}}StateSchema
+  static override optionsSchema = {{PascalName}}OptionsSchema
+  static override description = '{{description}}'
+
+  constructor(options: {{PascalName}}Options, context: ContainerContext) {
+    options = {
+      ...options,
+      baseURL: options.baseURL || 'https://api.example.com',
+    }
+    super(options, context)
+  }
+
+  // Add API methods here. Each wraps an endpoint.
+  // Example:
+  // async listItems(): Promise<Item[]> {
+  //   return this.get('/items')
+  // }
+}
+```
+
+## Module Augmentation
+
+```ts
+declare module '@soederpop/luca/client' {
+  interface AvailableClients {
+    {{camelName}}: typeof {{PascalName}}
+  }
+}
+```
+
+## Registration
+
+```ts
+export default clients.register('{{camelName}}', {{PascalName}})
+```
+
+## Complete Example
+
+```ts
+import { z } from 'zod'
+import { clients, RestClient } from '@soederpop/luca/client'
+import { ClientStateSchema, ClientOptionsSchema } from '@soederpop/luca'
+import type { ContainerContext } from '@soederpop/luca'
+
+declare module '@soederpop/luca/client' {
+  interface AvailableClients {
+    {{camelName}}: typeof {{PascalName}}
+  }
+}
+
+export const {{PascalName}}StateSchema = ClientStateSchema.extend({})
+export type {{PascalName}}State = z.infer<typeof {{PascalName}}StateSchema>
+
+export const {{PascalName}}OptionsSchema = ClientOptionsSchema.extend({
+  baseURL: z.string().default('https://api.example.com').describe('API base URL'),
+})
+export type {{PascalName}}Options = z.infer<typeof {{PascalName}}OptionsSchema>
+
+/**
+ * {{description}}
+ *
+ * @example
+ * ```typescript
+ * const {{camelName}} = container.client('{{camelName}}')
+ * ```
+ *
+ * @extends RestClient
+ */
+export class {{PascalName}} extends RestClient<{{PascalName}}State, {{PascalName}}Options> {
+  static override shortcut = 'clients.{{camelName}}' as const
+  static override stateSchema = {{PascalName}}StateSchema
+  static override optionsSchema = {{PascalName}}OptionsSchema
+  static override description = '{{description}}'
+
+  constructor(options: {{PascalName}}Options, context: ContainerContext) {
+    super({ ...options, baseURL: options.baseURL }, context)
+  }
+}
+
+export default clients.register('{{camelName}}', {{PascalName}})
+```
+
+## Conventions
+
+- **Extend RestClient for HTTP**: It gives you typed HTTP methods. Only use base `Client` if you need a non-HTTP protocol.
+- **Set baseURL in constructor**: Override options to hardcode or default the API base URL.
+- **Wrap endpoints as methods**: Each API endpoint gets a method. Keep them thin — just map to HTTP calls.
+- **JSDoc everything**: Every public method needs `@param`, `@returns`, `@example`.
+- **Auth in options**: Pass API keys, tokens via options schema. Check them in the constructor or a setup method.