luca 3.0.0 → 3.1.0

package/docs/examples/content-db.md

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

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

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

@@ -1,70 +0,0 @@
----
-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/entity.md

@@ -1,124 +0,0 @@
----
-title: "Entity"
-tags: [entity, state, events, tools, core]
-lastTested: null
-lastTestPassed: null
----
-
-# entity
-
-Lightweight, composable objects with observable state, a typed event bus, and an optional tool interface.
-
-## Overview
-
-An entity is a plain object — not a class — created via `container.entity(id, options?)`. Same id + options always returns the same underlying state and bus instance. Entities are designed to be extended with methods and getters via `.extend()`, and can expose those methods as AI tools via `.expose()`.
-
-## Basic Entity with Observable State
-
-Create an entity and read/write state through the observable `state` property.
-
-```ts
-const counter = container.entity<{ count: number }>('counter')
-counter.setState({ count: 0 })
-
-counter.state.observe((next) => {
-  console.log('count changed to', next.count)
-})
-
-counter.setState(s => ({ count: s.count + 1 }))
-counter.setState(s => ({ count: s.count + 1 }))
-console.log('final count:', counter.state.get('count'))
-```
-
-`setState` accepts either a partial object or a function that receives the current state. Observers fire synchronously after each change.
-
-## Typed Event Bus
-
-Every entity has a built-in event bus. Declare the event map as the third type parameter.
-
-```ts
-type TimerEvents = {
-  tick: [elapsed: number]
-  done: []
-}
-
-const timer = container.entity<{}, {}, TimerEvents>('timer')
-
-timer.on('tick', (elapsed) => {
-  console.log('tick at', elapsed, 'ms')
-})
-
-timer.once('done', () => {
-  console.log('timer finished')
-})
-
-timer.emit('tick', 100)
-timer.emit('tick', 200)
-timer.emit('done')
-```
-
-`once` auto-detaches after the first fire. `waitFor` returns a promise that resolves on the next emit of that event.
-
-## Extending with Methods
-
-Use `.extend()` to graft methods and getters onto an entity. All base properties — `state`, `options`, `container`, and the event methods — are available via `this`.
-
-```ts
-const session = container.entity('session', { userId: '42' })
-  .extend({
-    greet() {
-      return `Hello user ${this.options.userId}`
-    },
-    get label() {
-      return `Session ${this.id} (user ${this.options.userId})`
-    },
-    bump() {
-      const visits = (this.state.get('visits') ?? 0) + 1
-      this.setState({ visits })
-      this.emit('visited', visits)
-      return visits
-    },
-  })
-
-console.log(session.greet())
-console.log(session.label)
-console.log('visits:', session.bump())
-console.log('visits:', session.bump())
-```
-
-Extensions are chained via prototype delegation — each layer can see everything below it.
-
-## Exposing Methods as AI Tools
-
-Use `.expose(methodName, zodSchema)` to register methods as tools. `.toTools()` returns `{ schemas, handlers }` compatible with `assistant.addTools()`.
-
-```ts
-const search = container.entity('search', {})
-  .extend({
-    async lookup({ query }: { query: string }) {
-      return `Results for: ${query}`
-    },
-    async summarize({ text, maxWords }: { text: string; maxWords: number }) {
-      return text.split(' ').slice(0, maxWords).join(' ')
-    },
-  })
-  .expose('lookup', z.object({
-    query: z.string().describe('The search query'),
-  }))
-  .expose('summarize', z.object({
-    text: z.string().describe('Text to summarize'),
-    maxWords: z.number().describe('Maximum words in summary'),
-  }))
-
-const { schemas, handlers } = search.toTools()
-console.log('registered tools:', Object.keys(schemas))
-
-// Pass directly to an assistant
-// assistant.addTools(search)
-```
-
-`.expose()` is chainable and returns `this`, so you can stack as many as you need.
-
-## Summary
-
-Entities give you observable state, a typed event bus, and prototype-safe method extension — all as a plain object with no class overhead. The `.expose()` / `.toTools()` interface makes it straightforward to surface entity methods as AI tools.

package/docs/examples/esbuild.md

@@ -1,80 +0,0 @@
----
-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/feature-as-tool-provider.md

@@ -1,143 +0,0 @@
----
-title: "Features as Tool Providers for Assistants"
-tags: [feature, tools, assistant, composition, use, setupToolsConsumer]
-lastTested: null
-lastTestPassed: null
----
-
-# Features as Tool Providers for Assistants
-
-Any feature can expose tools that assistants pick up via `assistant.use(feature)`. This is how you compose lower-level container capabilities into an assistant-ready tool surface. The built-in `fileTools` feature is the canonical example — it wraps `fs` and `grep` into a focused set of tools modeled on what coding assistants need.
-
-## The Pattern
-
-A feature becomes a tool provider by defining three things:
-
-1. **`static tools`** — a record mapping tool names to Zod schemas with descriptions
-2. **Matching methods** — instance methods whose names match the keys in `static tools`
-3. **`setupToolsConsumer()`** (optional) — a hook that runs when an assistant calls `use()`, perfect for injecting system prompt guidance
-
-When an assistant calls `assistant.use(feature)`, the framework:
-- Reads `static tools` to register each tool with its schema
-- Routes tool calls to the matching instance methods
-- Calls `setupToolsConsumer()` so the feature can configure the assistant (e.g. add system prompt extensions)
-
-## Anatomy of fileTools
-
-Here's the structure of the built-in `fileTools` feature (simplified for clarity):
-
-```ts
-import { z } from 'zod'
-import { Feature } from '@soederpop/luca/feature'
-
-export class FileTools extends Feature {
-  static { Feature.register(this, 'fileTools') }
-
-  // ── 1. Declare tools with Zod schemas ──────────────────────────
-  static tools = {
-    readFile: {
-      description: 'Read the contents of a file.',
-      schema: z.object({
-        path: z.string().describe('File path relative to the project root'),
-        offset: z.number().optional().describe('Line number to start reading from'),
-        limit: z.number().optional().describe('Maximum number of lines to read'),
-      }),
-    },
-    searchFiles: {
-      description: 'Search file contents for a pattern using ripgrep.',
-      schema: z.object({
-        pattern: z.string().describe('Search pattern (regex supported)'),
-        path: z.string().optional().describe('Directory to search in'),
-        include: z.string().optional().describe('Glob pattern to filter files'),
-      }),
-    },
-    editFile: {
-      description: 'Replace an exact string match in a file.',
-      schema: z.object({
-        path: z.string().describe('File path relative to the project root'),
-        oldString: z.string().describe('The exact text to find and replace'),
-        newString: z.string().describe('The replacement text'),
-      }),
-    },
-    // ... more tools
-  }
-
-  // ── 2. Implement each tool as an instance method ───────────────
-  // Method names must match the keys in static tools exactly.
-  // Each receives the parsed args object and returns a string.
-
-  async readFile(args: { path: string; offset?: number; limit?: number }) {
-    const fs = this.container.feature('fs')
-    const content = await fs.readFileAsync(args.path)
-    // ... handle offset/limit
-    return content
-  }
-
-  async searchFiles(args: { pattern: string; path?: string; include?: string }) {
-    const grep = this.container.feature('grep')
-    const results = await grep.search({ pattern: args.pattern, path: args.path, include: args.include })
-    return JSON.stringify(results.map(r => ({ file: r.file, line: r.line, content: r.content })))
-  }
-
-  async editFile(args: { path: string; oldString: string; newString: string }) {
-    const fs = this.container.feature('fs')
-    const content = await fs.readFileAsync(args.path)
-    const updated = content.replace(args.oldString, args.newString)
-    await fs.writeFileAsync(args.path, updated)
-    return `Edited ${args.path}`
-  }
-
-  // ── 3. Configure the assistant when it calls use() ─────────────
-  override setupToolsConsumer(consumer) {
-    // If the consumer is an assistant, inject guidance into its system prompt
-    if (typeof consumer.addSystemPromptExtension === 'function') {
-      consumer.addSystemPromptExtension('fileTools', [
-        '## File Tools',
-        '- All file paths are relative to the project root unless they start with /',
-        '- Use searchFiles to understand code before modifying it',
-        '- Use editFile for surgical changes — prefer it over writeFile',
-      ].join('\n'))
-    }
-  }
-}
-```
-
-## Using It
-
-```ts
-const assistant = container.feature('assistant', {
-  systemPrompt: 'You are a coding assistant.',
-  model: 'gpt-4.1-mini',
-})
-
-const fileTools = container.feature('fileTools')
-assistant.use(fileTools)
-await assistant.start()
-
-// The assistant now has readFile, searchFiles, editFile, etc.
-// and its system prompt includes the fileTools guidance.
-console.log(Object.keys(assistant.tools))
-```
-
-### Selective tool registration
-
-You can expose only a subset of tools:
-
-```ts
-assistant.use(fileTools.toTools({ only: ['readFile', 'searchFiles', 'listDirectory'] }))
-```
-
-## Why This Pattern Matters
-
-This is how features compose for AI. Instead of the assistant importing `fs` and `grep` directly:
-
-- The **feature** owns the tool surface — schemas, descriptions, and implementations in one place
-- The **assistant** gets a curated interface, not raw container access
-- **`setupToolsConsumer()`** lets the feature teach the assistant how to use the tools well
-- **`toTools({ only })`** lets you scope down what the assistant can do
-
-Any feature you build can follow this same pattern. Define `static tools`, implement matching methods, optionally override `setupToolsConsumer()`, and assistants can `use()` it.
-
-## Summary
-
-Features are the natural place to package tools for assistants. The `static tools` record declares the schema, instance methods implement the logic, and `setupToolsConsumer()` wires up assistant-specific configuration like system prompt extensions. This keeps tool definitions, implementations, and assistant guidance co-located in a single feature class.