luca 2.0.0 → 3.0.0

package/docs/apis/features/node/container-link.md

@@ -0,0 +1,192 @@
+# ContainerLink (features.containerLink)
+
+ContainerLink (Web-side) — WebSocket client that connects to a node host. Connects to a ContainerLink host over WebSocket. The host can evaluate code in this container, and the web side can emit structured events to the host. The web side can NEVER eval code in the host — trust is strictly one-way.
+
+## Usage
+
+```ts
+container.feature('containerLink', {
+  // Port for the WebSocket server
+  port,
+  // Interval in ms between heartbeat pings
+  heartbeatInterval,
+  // Max missed pongs before disconnecting a client
+  maxMissedHeartbeats,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `port` | `number` | Port for the WebSocket server |
+| `heartbeatInterval` | `number` | Interval in ms between heartbeat pings |
+| `maxMissedHeartbeats` | `number` | Max missed pongs before disconnecting a client |
+
+## Methods
+
+### connect
+
+Connect to the host WebSocket server and perform registration.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `hostUrl` | `string` |  | Override the configured host URL |
+
+**Returns:** `Promise<this>`
+
+
+
+### disconnect
+
+Disconnect from the host.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `reason` | `string` |  | Optional reason string |
+
+**Returns:** `void`
+
+
+
+### emitToHost
+
+Send a structured event to the host container.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `eventName` | `string` | ✓ | Name of the event |
+| `data` | `any` |  | Optional event data |
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isConnected` | `boolean` | Whether currently connected to the host. |
+| `token` | `string | undefined` | The auth token received from the host. |
+| `hostId` | `string | undefined` | The host container's UUID. |
+
+## Events (Zod v4 schema)
+
+### connected
+
+Event emitted by ContainerLink
+
+
+
+### disconnected
+
+Event emitted by ContainerLink
+
+
+
+### evalRequest
+
+Event emitted by ContainerLink
+
+
+
+### reconnecting
+
+Event emitted by ContainerLink
+
+
+
+### disconnection
+
+Emitted when a web container disconnects
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Container UUID |
+| `arg1` | `string` | Reason |
+
+
+
+### error
+
+Event emitted by ContainerLink
+
+
+
+### connection
+
+Emitted when a web container connects and registers
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Container UUID |
+| `arg1` | `any` | Connection metadata |
+
+
+
+### evalResult
+
+Emitted when an eval result is received
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Request ID |
+| `arg1` | `any` | Result or error |
+
+
+
+### event
+
+Emitted when a web container sends a structured event
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Container UUID |
+| `arg1` | `string` | Event name |
+| `arg2` | `any` | Event data |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `connectionCount` | `number` | Number of currently connected web containers |
+| `port` | `number` | Port the WebSocket server is listening on |
+| `listening` | `boolean` | Whether the WebSocket server is listening |
+
+## Examples
+
+**features.containerLink**
+
+```ts
+const link = container.feature('containerLink', {
+ enable: true,
+ hostUrl: 'ws://localhost:8089',
+})
+await link.connect()
+
+// Send events to the host
+link.emitToHost('click', { x: 100, y: 200 })
+
+// Listen for eval requests before they execute
+link.on('evalRequest', (code, requestId) => {
+ console.log('Host is evaluating:', code)
+})
+```
+

package/docs/apis/features/node/content-db.md

@@ -0,0 +1,450 @@
+# ContentDb (features.contentDb)
+
+Provides access to a Contentbase Collection for a folder of structured markdown files. Models are defined in the collection's models.ts file and auto-discovered on load. This feature is a thin wrapper that manages the collection lifecycle and provides convenience accessors for models and documents.
+
+## Usage
+
+```ts
+container.feature('contentDb', {
+  // Root directory path containing the structured markdown collection
+  rootPath,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `rootPath` | `string` | Root directory path containing the structured markdown collection |
+
+## Methods
+
+### renderTree
+
+Render a tree view of the collection directory structure. Built with container.fs so it works without the `tree` binary.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{ depth?: number; dirsOnly?: boolean }` |  | Parameter options |
+
+**Returns:** `string`
+
+
+
+### grep
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `string | GrepOptions` | ✓ | Parameter options |
+
+**Returns:** `void`
+
+
+
+### query
+
+Query documents belonging to a specific model definition.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `model` | `T` | ✓ | The model definition to query against |
+
+**Returns:** `void`
+
+```ts
+const contentDb = container.feature('contentDb', { rootPath: './docs' })
+await contentDb.load()
+const articles = await contentDb.query(contentDb.models.Article).fetchAll()
+```
+
+
+
+### parseMarkdownAtPath
+
+Parse a markdown file at the given path without loading the full collection.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` | ✓ | Absolute or relative path to the markdown file |
+
+**Returns:** `void`
+
+```ts
+const doc = contentDb.parseMarkdownAtPath('./docs/getting-started.md')
+console.log(doc.frontmatter, doc.content)
+```
+
+
+
+### load
+
+Load the collection, discovering models from models.ts and parsing all documents.
+
+**Returns:** `Promise<ContentDb>`
+
+```ts
+const contentDb = container.feature('contentDb', { rootPath: './docs' })
+await contentDb.load()
+console.log(contentDb.isLoaded) // true
+```
+
+
+
+### reload
+
+Force-reload the collection from disk, picking up new/changed/deleted documents.
+
+**Returns:** `Promise<ContentDb>`
+
+
+
+### read
+
+Read a single document by its path ID, optionally filtering to specific sections. The document title (H1) is always included in the output. When using `include`, the leading content (paragraphs between the H1 and first H2) is also included by default, controlled by the `leadingContent` option. When `include` is provided, only those sections are returned (via extractSections in flat mode). When `exclude` is provided, those sections are removed from the full document. If both are set, `include` takes precedence.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `idStringOrObject` | `string | { id: string }` | ✓ | Document path ID string, or an object with an `id` property |
+| `options` | `{ exclude?: string[], include?: string[], meta?: boolean, leadingContent?: boolean }` |  | Optional filtering and formatting options |
+
+`{ exclude?: string[], include?: string[], meta?: boolean, leadingContent?: boolean }` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `include` | `any` | Only return sections matching these heading names |
+| `exclude` | `any` | Remove sections matching these heading names |
+| `meta` | `any` | Whether to include YAML frontmatter in the output (default: false) |
+| `leadingContent` | `any` | Include content between the H1 and first H2 when using include filter (default: true) |
+
+**Returns:** `Promise<string>`
+
+```ts
+await contentDb.read('guides/intro')
+await contentDb.read('guides/intro', { include: ['Installation', 'Usage'] })
+await contentDb.read('guides/intro', { exclude: ['Changelog'], meta: true })
+await contentDb.read('guides/intro', { include: ['API'], leadingContent: false })
+```
+
+
+
+### readMultiple
+
+Read multiple documents by their path IDs, concatenated into a single string. By default each document is wrapped in `<!-- BEGIN: id -->` / `<!-- END: id -->` dividers for easy identification. Supports the same filtering options as {@link read}.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `ids` | `string[] | { id: string }[]` | ✓ | Array of document path ID strings or objects with `id` properties |
+| `options` | `{ exclude?: string[], include?: string[], meta?: boolean, leadingContent?: boolean, dividers?: boolean }` |  | Optional filtering and formatting options (applied to each document) |
+
+`{ exclude?: string[], include?: string[], meta?: boolean, leadingContent?: boolean, dividers?: boolean }` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dividers` | `any` | Wrap each document in BEGIN/END comment dividers showing the ID (default: true) |
+
+**Returns:** `Promise<string>`
+
+```ts
+await contentDb.readMultiple(['guides/intro', 'guides/setup'])
+await contentDb.readMultiple([{ id: 'guides/intro' }], { include: ['Overview'], dividers: false })
+```
+
+
+
+### generateTableOfContents
+
+**Returns:** `void`
+
+
+
+### generateModelSummary
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `any` | ✓ | Parameter options |
+
+**Returns:** `void`
+
+
+
+### search
+
+BM25 keyword search across indexed documents. If no search index exists, throws with an actionable message.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | Parameter query |
+| `options` | `{ limit?: number; model?: string; where?: Record<string, any> }` |  | Parameter options |
+
+**Returns:** `void`
+
+
+
+### vectorSearch
+
+Vector similarity search using embeddings. Finds conceptually related documents even without keyword matches.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | Parameter query |
+| `options` | `{ limit?: number; model?: string; where?: Record<string, any> }` |  | Parameter options |
+
+**Returns:** `void`
+
+
+
+### hybridSearch
+
+Combined keyword + semantic search with Reciprocal Rank Fusion. Best for general questions about the collection.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | Parameter query |
+| `options` | `{ limit?: number; model?: string; where?: Record<string, any>; ftsWeight?: number; vecWeight?: number }` |  | Parameter options |
+
+**Returns:** `void`
+
+
+
+### buildSearchIndex
+
+Build the search index from all documents in the collection. Chunks documents and generates embeddings.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{ force?: boolean; embeddingProvider?: string; embeddingModel?: string; onProgress?: (indexed: number, total: number) => void }` |  | Parameter options |
+
+**Returns:** `void`
+
+
+
+### rebuildSearchIndex
+
+Rebuild the entire search index from scratch.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{ embeddingProvider?: string; embeddingModel?: string; onProgress?: (indexed: number, total: number) => void }` |  | Parameter options |
+
+**Returns:** `void`
+
+
+
+### getCollectionOverview
+
+Returns a high-level overview of the collection.
+
+**Returns:** `void`
+
+
+
+### listDocuments
+
+List document IDs, optionally filtered by model or glob.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ model?: string; glob?: string }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### readDocument
+
+Read a single document with optional section filtering.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ id: string; include?: string[]; exclude?: string[]; meta?: boolean }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### readMultipleDocuments
+
+Read multiple documents with optional section filtering.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ ids: string[]; include?: string[]; exclude?: string[]; meta?: boolean }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### queryDocuments
+
+Query documents by model with filters, sort, limit.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ model: string; where?: string; sort?: string; limit?: number; offset?: number; select?: string[] }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### searchContent
+
+Grep/text search across the collection.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ pattern: string; caseSensitive?: boolean }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### semanticSearch
+
+Hybrid semantic search with graceful fallback to grep.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ query: string; limit?: number }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isLoaded` | `boolean` | Whether the content database has been loaded. |
+| `collection` | `Collection` | Returns the lazily-initialized Collection instance for the configured rootPath. |
+| `collectionPath` | `string` | Returns the absolute resolved path to the collection root directory. |
+| `models` | `Record<string, ModelDefinition>` | Returns an object mapping model names to their model definitions, sourced from the collection. |
+| `modelNames` | `string[]` | Returns an array of all registered model names from the collection. |
+| `available` | `string[]` | Returns the available document ids in the collection |
+| `modelDefinitionTable` | `Record<string, { description: string; glob: string; routePatterns: string[] }>` |  |
+| `fileTree` | `string` |  |
+| `searchIndexStatus` | `{ exists: boolean; documentCount: number; chunkCount: number; embeddingCount: number; lastIndexedAt: any; provider: any; model: any; dimensions: number; dbSizeBytes: number }` | Get the current search index status. |
+| `queries` | `Record<string, ReturnType<typeof this.query>>` | Returns an object with query builders keyed by model name (singular and plural, lowercased). Provides a convenient shorthand for querying without looking up model definitions manually. |
+
+## Events (Zod v4 schema)
+
+### reloaded
+
+When the content collection is reloaded from disk
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `loaded` | `boolean` | Whether the content collection has been loaded and parsed |
+| `tableOfContents` | `string` | Generated table of contents string for the collection |
+| `modelSummary` | `string` | Summary of all discovered content models and their document counts |
+
+## Examples
+
+**features.contentDb**
+
+```ts
+const contentDb = container.feature('contentDb', { rootPath: './docs' })
+await contentDb.load()
+console.log(contentDb.modelNames) // ['Article', 'Page', ...]
+```
+
+
+
+**query**
+
+```ts
+const contentDb = container.feature('contentDb', { rootPath: './docs' })
+await contentDb.load()
+const articles = await contentDb.query(contentDb.models.Article).fetchAll()
+```
+
+
+
+**parseMarkdownAtPath**
+
+```ts
+const doc = contentDb.parseMarkdownAtPath('./docs/getting-started.md')
+console.log(doc.frontmatter, doc.content)
+```
+
+
+
+**load**
+
+```ts
+const contentDb = container.feature('contentDb', { rootPath: './docs' })
+await contentDb.load()
+console.log(contentDb.isLoaded) // true
+```
+
+
+
+**read**
+
+```ts
+await contentDb.read('guides/intro')
+await contentDb.read('guides/intro', { include: ['Installation', 'Usage'] })
+await contentDb.read('guides/intro', { exclude: ['Changelog'], meta: true })
+await contentDb.read('guides/intro', { include: ['API'], leadingContent: false })
+```
+
+
+
+**readMultiple**
+
+```ts
+await contentDb.readMultiple(['guides/intro', 'guides/setup'])
+await contentDb.readMultiple([{ id: 'guides/intro' }], { include: ['Overview'], dividers: false })
+```
+
+
+
+**queries**
+
+```ts
+const contentDb = container.feature('contentDb', { rootPath: './docs' })
+await contentDb.load()
+const allArticles = await contentDb.queries.articles.fetchAll()
+const firstTask = await contentDb.queries.task.first()
+```
+