@soederpop/luca 0.0.2

package/docs/documentation-audit.md

@@ -0,0 +1,134 @@
+# Documentation Audit
+
+Periodically do an audit of all Feature, Server, Client subclasses to make sure they are completely documented.
+
+
+## Files
+
+- `src/node/features/*.ts` NodeContainer features
+- `src/clients/*/index.ts` Client subclasses
+- `src/agi/features.ts` AGIContainer features
+
+## Generating Introspection Data for Runtime consumption
+
+After any changes to the above files, make sure to run:
+
+```shell
+bun run build:introspection 
+```
+
+## Documentation Guidelines
+
+Here is a good example of a well documented feature, notice that:
+
+- All of the Options, State, Event schema items have `describe()` calls
+- There is a docblock above the class which uses a simple example with no imports, using the factory pattern
+- getters are documented
+- methods have jsdoc also with an example
+- method options have jsdoc comments for typescript consumers
+
+```ts
+
+export const TTSOptionsSchema = FeatureOptionsSchema.extend({
+  apiKey: z.string().optional().describe('RunPod API key (falls back to RUNPOD_API_KEY env var)'),
+  voice: z.string().optional().describe('Default preset voice name'),
+  outputDir: z.string().optional().describe('Directory to save generated audio files'),
+  format: z.enum(['wav', 'flac', 'ogg']).default('wav').describe('Audio output format'),
+})
+export type TTSOptions = z.infer<typeof TTSOptionsSchema>
+
+export const TTSStateSchema = FeatureStateSchema.extend({
+  lastFile: z.string().optional().describe('Path to the last generated audio file'),
+  lastText: z.string().optional().describe('Text of the last synthesis request'),
+  generating: z.boolean().default(false).describe('Whether audio is currently being generated'),
+})
+export type TTSState = z.infer<typeof TTSStateSchema>
+
+export const TTSEventsSchema = FeatureEventsSchema.extend({
+  synthesized: z.tuple([
+    z.string().describe('The text that was synthesized'),
+    z.string().describe('Path to the generated audio file'),
+    z.string().describe('Voice used'),
+    z.number().describe('Duration of the API call in milliseconds'),
+  ]).describe('Emitted when audio synthesis completes'),
+  error: z.tuple([
+    z.any().describe('The error'),
+  ]).describe('Emitted when synthesis fails'),
+})
+
+/**
+ * TTS feature — synthesizes text to audio files via RunPod's Chatterbox Turbo endpoint.
+ *
+ * Generates high-quality speech audio by calling the Chatterbox Turbo public endpoint
+ * on RunPod, downloads the resulting audio, and saves it locally. Supports 20 preset
+ * voices and voice cloning via a reference audio URL.
+ *
+ * @example
+ * ```typescript
+ * const tts = container.feature('tts', { enable: true })
+ * const path = await tts.synthesize('Hello, how are you?', { voice: 'lucy' })
+ * console.log(`Audio saved to: ${path}`)
+ * ```
+ */
+export class TTS extends Feature<TTSState, TTSOptions> {
+  static override shortcut = 'features.tts' as const
+  static override envVars = ['RUNPOD_API_KEY']
+  static override stateSchema = TTSStateSchema
+  static override optionsSchema = TTSOptionsSchema
+  static override eventsSchema = TTSEventsSchema
+
+  /** RunPod API key from options or environment. */
+  get apiKey(): string {
+    return this.options.apiKey || process.env.RUNPOD_API_KEY || ''
+  }
+
+  /** Directory where generated audio files are saved. */
+  get outputDir(): string {
+    return this.options.outputDir || join(homedir(), '.luca', 'tts-cache')
+  }
+
+  /** The 20 preset voice names available in Chatterbox Turbo. */
+  get voices(): readonly string[] {
+    return PRESET_VOICES
+  }
+
+  /**
+   * Synthesize text to an audio file using Chatterbox Turbo.
+   *
+   * Calls the RunPod public endpoint, downloads the generated audio,
+   * and saves it to the output directory.
+   *
+   * @param text - The text to synthesize into speech
+   * @param options - Override voice, format, or provide a voiceUrl for cloning
+   * @returns Absolute path to the generated audio file
+   *
+   * @example
+   * ```typescript
+   * // Use a preset voice
+   * const path = await tts.synthesize('Good morning!', { voice: 'ethan' })
+   *
+   * // Clone a voice from a reference audio URL
+   * const path = await tts.synthesize('Hello world', {
+   *   voiceUrl: 'https://example.com/reference.wav'
+   * })
+   * ```
+   */
+  async synthesize(text: string, options?: {
+		/* which voice to use */
+    voice?: string
+		/* which format to save the output in */
+    format?: 'wav' | 'flac' | 'ogg'
+		/* an optional url to use for voice cloning */
+    voiceUrl?: string
+  }): Promise<string> {
+    if (!this.apiKey) {
+      throw new Error('TTS requires a RunPod API key. Set RUNPOD_API_KEY or pass apiKey in options.')
+    }
+		// omitted
+	}
+
+}
+
+```
+
+

package/docs/examples/content-db.md

@@ -0,0 +1,77 @@
+---
+title: "Content Database"
+tags: [contentDb, markdown, content, database]
+lastTested: null
+lastTestPassed: null
+---
+
+# contentDb
+
+Treat folders of structured markdown files as queryable databases. Each markdown file is a document with frontmatter metadata and content.
+
+## Overview
+
+The `contentDb` feature is on-demand. Enable it with a `rootPath` pointing to a directory that contains a `models.ts` file and subfolders of markdown documents. It is perfect for documentation sites, knowledge bases, or any content-driven application where markdown is the source of truth.
+
+## Loading a Collection
+
+We point the feature at the project's docs directory, which already has models and content.
+
+```ts
+const contentDb = container.feature('contentDb', { rootPath: '.' })
+await contentDb.load()
+console.log('Loaded:', contentDb.isLoaded)
+```
+
+The `load()` call discovers the models defined in `models.ts` and parses every markdown file in the matching prefix directories.
+
+## Discovering Models
+
+Each collection has named models. Let us see what is available.
+
+```ts
+const names = contentDb.modelNames
+console.log('Available models:', names)
+```
+
+Models correspond to subdirectories. Each model defines a schema for the frontmatter metadata its documents must conform to.
+
+## Querying Documents
+
+Use `query()` to fetch documents belonging to a model. Here we query the Tutorial model.
+
+```ts
+const tutorials = await contentDb.query(contentDb.models.Tutorial).fetchAll()
+console.log('Tutorial count:', tutorials.length)
+tutorials.slice(0, 3).forEach(doc => {
+  console.log('-', doc.id, '|', doc.meta?.title)
+})
+```
+
+Documents come back with their parsed frontmatter, content, and a unique id derived from the file path.
+
+## Parsing a Single File
+
+You can also parse any markdown file directly without going through the query system.
+
+```ts
+const doc = contentDb.parseMarkdownAtPath('./docs/tutorials/01-getting-started.md')
+console.log('Title:', doc.meta?.title)
+console.log('Tags:', doc.meta?.tags)
+```
+
+This is useful when you know exactly which file you want and do not need to iterate over a collection.
+
+## Collection Summary
+
+The feature tracks a model summary in its state, giving you a quick overview of the entire collection.
+
+```ts
+console.log(contentDb.state.get('modelSummary'))
+```
+
+This summary shows each model and how many documents belong to it.
+
+## Summary
+
+This demo covered loading a contentbase collection, listing models, querying documents by model, parsing individual markdown files, and inspecting the collection summary. The `contentDb` feature turns your markdown files into a lightweight, schema-validated content database.

package/docs/examples/disk-cache.md

@@ -0,0 +1,83 @@
+---
+title: "Disk Cache"
+tags: [diskCache, storage, caching]
+lastTested: null
+lastTestPassed: null
+---
+
+# diskCache
+
+A file-backed key-value cache powered by cacache (the same store behind npm). Persist arbitrary data to disk with a simple get/set interface.
+
+## Overview
+
+The `diskCache` feature is on-demand. Enable it with a `path` option pointing to a cache directory. It is ideal for persisting computed results, downloaded assets, or any data you want to survive across process restarts without setting up a full database.
+
+## Creating a Cache
+
+We start by enabling the feature and pointing it at a temporary directory.
+
+```ts
+const cache = container.feature('diskCache', { path: '/tmp/luca-example-cache' })
+console.log('diskCache enabled:', cache.state.get('enabled'))
+```
+
+The cache directory is created automatically when the first entry is written.
+
+## Storing and Retrieving Values
+
+Use `set()` to write a key and `get()` to read it back.
+
+```ts
+await cache.set('greeting', 'Hello from Luca!')
+const value = await cache.get('greeting')
+console.log('Retrieved:', value)
+```
+
+The value comes back exactly as stored.
+
+## Checking for Keys
+
+Use `has()` to check whether a key exists without reading it.
+
+```ts
+const exists = await cache.has('greeting')
+console.log('Has greeting?', exists)
+const missing = await cache.has('nonexistent')
+console.log('Has nonexistent?', missing)
+```
+
+This is useful for conditional caching patterns where you want to skip expensive work if a result is already stored.
+
+## Listing All Keys
+
+Use `keys()` to enumerate everything in the cache.
+
+```ts
+await cache.set('user:1', JSON.stringify({ name: 'Alice' }))
+await cache.set('user:2', JSON.stringify({ name: 'Bob' }))
+const allKeys = await cache.keys()
+console.log('All keys:', allKeys)
+```
+
+Keys are plain strings, so you can use naming conventions like prefixes to organize entries.
+
+## Removing Entries
+
+Use `rm()` to delete a single key, or `clearAll(true)` to wipe the entire cache.
+
+```ts
+await cache.rm('user:2')
+const afterRemove = await cache.keys()
+console.log('After removing user:2:', afterRemove)
+
+await cache.clearAll(true)
+const afterClear = await cache.keys()
+console.log('After clearAll:', afterClear)
+```
+
+Note that `clearAll` requires passing `true` as a confirmation safeguard.
+
+## Summary
+
+This demo covered creating a disk cache, storing and retrieving values, checking key existence, listing keys, and removing entries. The `diskCache` feature provides a lightweight persistence layer without any external dependencies.

package/docs/examples/docker.md

@@ -0,0 +1,101 @@
+---
+title: "Docker"
+tags: [docker, containers, images, devops]
+lastTested: null
+lastTestPassed: null
+---
+
+# docker
+
+Docker CLI interface for managing containers, images, and executing commands inside running containers. Provides comprehensive Docker operations including build, run, exec, logs, and system pruning.
+
+## Overview
+
+The `docker` feature wraps the Docker CLI to give you programmatic control over containers and images. It requires Docker to be installed and the Docker daemon to be running on the host machine. All methods return structured data rather than raw CLI output.
+
+## Enabling the Feature
+
+```ts
+const docker = container.feature('docker', { enable: true })
+console.log('Docker feature enabled:', docker.state.get('enabled'))
+```
+
+## Exploring the API
+
+```ts
+const docs = container.features.describe('docker')
+console.log(docs)
+```
+
+## Checking Availability
+
+```ts
+const docker = container.feature('docker')
+const available = await docker.checkDockerAvailability()
+console.log('Docker available:', available)
+console.log('State:', docker.state.get('isDockerAvailable'))
+```
+
+## Building an Image
+
+Build a Docker image from a Dockerfile in a project directory.
+
+```ts skip
+await docker.buildImage('./my-project', {
+  tag: 'my-app:latest',
+  buildArgs: { NODE_ENV: 'production' },
+  nocache: true
+})
+console.log('Image built successfully')
+```
+
+If the build succeeds, the image appears in `docker.listImages()`. The `buildArgs` option passes `--build-arg` flags to the Docker build command.
+
+## Running a Container
+
+Create and start a container from an image with port mappings, volumes, and environment variables.
+
+```ts skip
+const containerId = await docker.runContainer('nginx:latest', {
+  name: 'web-server',
+  ports: ['8080:80'],
+  detach: true,
+  environment: { NGINX_HOST: 'localhost' }
+})
+console.log('Container started:', containerId)
+```
+
+The `detach: true` option runs the container in the background and returns its ID. Without it, the call blocks until the container exits.
+
+## Executing Commands in a Container
+
+Run commands inside a running container and capture the output.
+
+```ts skip
+const result = await docker.execCommand('web-server', ['ls', '-la', '/usr/share/nginx/html'])
+console.log('stdout:', result.stdout)
+console.log('exit code:', result.exitCode)
+```
+
+The command array avoids shell interpretation issues. The returned object includes `stdout`, `stderr`, and `exitCode`.
+
+## Creating a Shell
+
+The `createShell` method returns a shell-like wrapper for running multiple commands against the same container.
+
+```ts skip
+const shell = await docker.createShell('web-server', {
+  workdir: '/app'
+})
+await shell.run('ls -la')
+console.log(shell.last.stdout)
+await shell.run('cat package.json')
+console.log(shell.last.stdout)
+await shell.destroy()
+```
+
+Call `destroy()` when finished to clean up any helper containers created for volume-mounted shells.
+
+## Summary
+
+The `docker` feature provides a complete programmatic interface to Docker: build images, run and manage containers, execute commands inside them, retrieve logs, and prune unused resources. All operations require the Docker daemon to be running on the host.

package/docs/examples/downloader.md

@@ -0,0 +1,70 @@
+---
+title: "Downloader"
+tags: [downloader, network, files, http]
+lastTested: null
+lastTestPassed: null
+---
+
+# downloader
+
+Download files from remote URLs and save them to the local filesystem.
+
+## Overview
+
+The `downloader` feature is an on-demand feature that fetches files from HTTP/HTTPS URLs and writes them to disk. It handles the network request, buffering, and file writing automatically. Use it when you need to programmatically pull remote assets -- images, documents, data files -- into your project.
+
+## Feature Documentation
+
+Let us inspect the feature's built-in documentation to understand its API.
+
+```ts
+const desc = container.features.describe('downloader')
+console.log(desc)
+```
+
+The feature exposes a single `download(url, targetPath)` method that fetches a URL and writes the response body to the specified path.
+
+## Enabling the Feature
+
+Enable the downloader and inspect its initial state.
+
+```ts
+const downloader = container.feature('downloader', { enable: true })
+console.log('Downloader enabled:', downloader.state.enabled)
+```
+
+Once enabled, the feature is ready to accept download requests.
+
+## Inspecting the API
+
+The downloader has a straightforward interface: one method for downloading.
+
+```ts
+const methods = Object.getOwnPropertyNames(Object.getPrototypeOf(downloader))
+  .filter(m => !m.startsWith('_') && m !== 'constructor')
+console.log('Available methods:', methods.join(', '))
+```
+
+The `download` method takes two arguments: a URL string and a target file path. The target path is resolved relative to the container's working directory.
+
+## How Downloading Works
+
+Here is what happens when you call `download()`:
+
+1. The feature makes an HTTP fetch to the provided URL
+2. The response is buffered into memory
+3. The buffer is written to the filesystem at the target path
+4. The path is resolved using the container's path resolution
+
+```ts
+// Example usage (not executed to avoid network calls):
+//   await downloader.download(
+//     'https://example.com/data.json',
+//     'downloads/data.json'
+//   )
+console.log('Downloader is ready. Call downloader.download(url, path) to fetch files.')
+```
+
+## Summary
+
+This demo covered the `downloader` feature, which provides a simple one-method API for fetching remote files and saving them locally. It handles HTTP requests, buffering, and file writing, making it the right choice for any task that involves pulling assets from the network.

package/docs/examples/esbuild.md

@@ -0,0 +1,80 @@
+---
+title: "esbuild"
+tags: [esbuild, transpilation, bundling, typescript]
+lastTested: null
+lastTestPassed: null
+---
+
+# esbuild
+
+Transpile TypeScript, TSX, and JSX to JavaScript at runtime using Bun's built-in transpiler. Compile code strings on the fly without touching the filesystem.
+
+## Overview
+
+The `esbuild` feature is a core feature, meaning it is auto-enabled on every container. You can access it directly as a global or via `container.feature('esbuild')`. It wraps Bun's transpiler and exposes both synchronous and asynchronous `transform` methods. Use it for runtime code generation, plugin systems, or any scenario where you need to compile TypeScript strings to runnable JavaScript.
+
+## Synchronous Transform
+
+Use `transformSync()` to transpile a TypeScript string to JavaScript in a single blocking call.
+
+```ts
+const result = esbuild.transformSync('const x: number = 42; console.log(x);')
+console.log('Input:  const x: number = 42; console.log(x);')
+console.log('Output:', result.code.trim())
+```
+
+The type annotations are stripped and the output is plain JavaScript.
+
+## Async Transform
+
+The async `transform()` method does the same thing but returns a promise. Prefer this in hot paths where you do not want to block.
+
+```ts
+const tsxCode = `
+interface Props { name: string }
+const Greet = (props: Props) => <h1>Hello {props.name}</h1>
+`
+const out = await esbuild.transform(tsxCode, { loader: 'tsx' })
+console.log('TSX transpiled:')
+console.log(out.code.trim())
+```
+
+Notice the `loader: 'tsx'` option tells the transpiler to handle JSX syntax.
+
+## Minification
+
+Pass `minify: true` to produce compact output with whitespace removed.
+
+```ts
+const verbose = `
+  function greet(name: string): string {
+    const greeting = "Hello, " + name + "!";
+    return greeting;
+  }
+`
+const normal = esbuild.transformSync(verbose)
+const minified = esbuild.transformSync(verbose, { minify: true })
+console.log('Normal length:', normal.code.length)
+console.log('Minified length:', minified.code.length)
+console.log('Minified:', minified.code.trim())
+```
+
+Minification is useful when generating code that will be sent to a browser or embedded in a response.
+
+## Different Loaders
+
+The feature supports multiple source languages via the `loader` option.
+
+```ts
+const jsxResult = esbuild.transformSync(
+  'const App = () => <div className="app">Content</div>',
+  { loader: 'tsx' }
+)
+console.log('JSX output:', jsxResult.code.trim())
+```
+
+Supported loaders include `ts` (default), `tsx`, `jsx`, and `js`.
+
+## Summary
+
+This demo covered synchronous and asynchronous transpilation, minification, and using different source loaders. The `esbuild` feature gives you runtime TypeScript-to-JavaScript compilation with zero configuration.

package/docs/examples/file-manager.md

@@ -0,0 +1,82 @@
+---
+title: "File Manager"
+tags: [fileManager, files, indexing, filesystem]
+lastTested: null
+lastTestPassed: null
+---
+
+# fileManager
+
+Builds an in-memory index of every file in your project with metadata and glob matching. Think of it as a fast, queryable snapshot of your file tree.
+
+## Overview
+
+The `fileManager` feature is on-demand. After enabling it and calling `start()`, it scans the project directory and indexes every file. You can then match files by glob patterns, inspect metadata, and list unique extensions. It is useful for code analysis tools, documentation generators, or any script that needs to reason about project structure.
+
+## Starting the File Manager
+
+Enable the feature and kick off the initial scan.
+
+```ts
+const fm = container.feature('fileManager')
+await fm.start()
+console.log('Scan complete:', fm.isStarted)
+console.log('Total files indexed:', fm.fileIds.length)
+```
+
+The scan respects common ignore patterns (node_modules, .git, etc.) by default.
+
+## Matching Files by Glob
+
+Use `match()` to find file paths matching a glob pattern.
+
+```ts
+const tsFiles = fm.match('**/*.ts')
+console.log('TypeScript files found:', tsFiles.length)
+tsFiles.slice(0, 5).forEach(f => console.log(' ', f))
+```
+
+This returns an array of relative file paths that match the pattern.
+
+## Inspecting File Metadata
+
+Use `matchFiles()` to get full file objects instead of just paths. Each object contains metadata about the file.
+
+```ts
+const pkgFiles = fm.matchFiles('package.json')
+pkgFiles.forEach(f => {
+  console.log('File:', f.id)
+  console.log('  Extension:', f.extension)
+  console.log('  Directory:', f.directory)
+})
+```
+
+File objects include properties like `id` (relative path), `extension`, and `directory`.
+
+## Unique Extensions
+
+The file manager tracks every file extension it encounters across the project.
+
+```ts
+const extensions = fm.uniqueExtensions
+console.log('Unique extensions:', extensions.length)
+console.log('Extensions:', extensions.slice(0, 15).join(', '))
+```
+
+This is handy for understanding the technology mix in a project at a glance.
+
+## Directory Listing
+
+You can also get the unique set of directories that contain indexed files.
+
+```ts
+const dirs = fm.directoryIds
+console.log('Directories:', dirs.length)
+dirs.slice(0, 8).forEach(d => console.log(' ', d))
+```
+
+Combined with glob matching, this gives you a complete picture of the project layout.
+
+## Summary
+
+This demo covered starting the file manager, glob matching, inspecting file metadata, listing unique extensions, and enumerating directories. The `fileManager` feature provides a fast, in-memory file index for project analysis and tooling.