@soederpop/luca 0.0.2

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

@@ -0,0 +1,313 @@
+# 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
+
+### 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
+```
+
+
+
+### 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`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isLoaded` | `any` | Whether the content database has been loaded. |
+| `collection` | `any` | Returns the lazily-initialized Collection instance for the configured rootPath. |
+| `collectionPath` | `any` | 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. |
+| `searchIndexStatus` | `any` | 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. |
+
+## 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()
+```
+

package/docs/apis/features/node/disk-cache.md

@@ -0,0 +1,379 @@
+# DiskCache (features.diskCache)
+
+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.
+
+## Usage
+
+```ts
+container.feature('diskCache')
+```
+
+## Methods
+
+### saveFile
+
+Retrieve a file from the disk cache and save it to the local disk
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The cache key to retrieve |
+| `outputPath` | `string` | ✓ | The local path where the file should be saved |
+| `isBase64` | `any` |  | Whether the cached content is base64 encoded |
+
+**Returns:** `void`
+
+```ts
+await diskCache.saveFile('myFile', './output/file.txt')
+await diskCache.saveFile('encodedImage', './images/photo.jpg', true)
+```
+
+
+
+### ensure
+
+Ensure a key exists in the cache, setting it with the provided content if it doesn't exist
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The cache key to check/set |
+| `content` | `string` | ✓ | The content to set if the key doesn't exist |
+
+**Returns:** `void`
+
+```ts
+await diskCache.ensure('config', JSON.stringify(defaultConfig))
+```
+
+
+
+### copy
+
+Copy a cached item from one key to another
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `source` | `string` | ✓ | The source cache key |
+| `destination` | `string` | ✓ | The destination cache key |
+| `overwrite` | `boolean` |  | Whether to overwrite if destination exists (default: false) |
+
+**Returns:** `void`
+
+```ts
+await diskCache.copy('original', 'backup')
+await diskCache.copy('file1', 'file2', true) // force overwrite
+```
+
+
+
+### move
+
+Move a cached item from one key to another (copy then delete source)
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `source` | `string` | ✓ | The source cache key |
+| `destination` | `string` | ✓ | The destination cache key |
+| `overwrite` | `boolean` |  | Whether to overwrite if destination exists (default: false) |
+
+**Returns:** `void`
+
+```ts
+await diskCache.move('temp', 'permanent')
+await diskCache.move('old_key', 'new_key', true) // force overwrite
+```
+
+
+
+### has
+
+Check if a key exists in the cache
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The cache key to check |
+
+**Returns:** `void`
+
+```ts
+if (await diskCache.has('myKey')) {
+ console.log('Key exists!')
+}
+```
+
+
+
+### get
+
+Retrieve a value from the cache
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The cache key to retrieve |
+| `json` | `any` |  | Whether to parse the value as JSON (default: false) |
+
+**Returns:** `void`
+
+```ts
+const text = await diskCache.get('myText')
+const data = await diskCache.get('myData', true) // parse as JSON
+```
+
+
+
+### set
+
+Store a value in the cache
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The cache key to store under |
+| `value` | `any` | ✓ | The value to store (string, object, or any serializable data) |
+| `meta` | `any` |  | Optional metadata to associate with the cached item |
+
+**Returns:** `void`
+
+```ts
+await diskCache.set('myKey', 'Hello World')
+await diskCache.set('userData', { name: 'John', age: 30 })
+await diskCache.set('file', content, { size: 1024, type: 'image' })
+```
+
+
+
+### rm
+
+Remove a cached item
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The cache key to remove |
+
+**Returns:** `void`
+
+```ts
+await diskCache.rm('obsoleteKey')
+```
+
+
+
+### clearAll
+
+Clear all cached items
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `confirm` | `any` |  | Must be set to true to confirm the operation |
+
+**Returns:** `void`
+
+```ts
+await diskCache.clearAll(true) // Must explicitly confirm
+```
+
+
+
+### keys
+
+Get all cache keys
+
+**Returns:** `Promise<string[]>`
+
+```ts
+const allKeys = await diskCache.keys()
+console.log(`Cache contains ${allKeys.length} items`)
+```
+
+
+
+### listKeys
+
+List all cache keys (alias for keys())
+
+**Returns:** `Promise<string[]>`
+
+```ts
+const keyList = await diskCache.listKeys()
+```
+
+
+
+### create
+
+Create a cacache instance with the specified path
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` |  | Optional cache directory path (defaults to options.path or node_modules/.cache/luca-disk-cache) |
+
+**Returns:** `void`
+
+```ts
+const customCache = diskCache.create('/custom/cache/path')
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `cache` | `any` | Returns the underlying cacache instance configured with the cache directory path. |
+| `securely` | `any` | Get encrypted cache operations interface Requires encryption to be enabled and a secret to be provided |
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.diskCache**
+
+```ts
+const diskCache = container.feature('diskCache', { path: '/tmp/cache' })
+await diskCache.set('greeting', 'Hello World')
+const value = await diskCache.get('greeting')
+```
+
+
+
+**saveFile**
+
+```ts
+await diskCache.saveFile('myFile', './output/file.txt')
+await diskCache.saveFile('encodedImage', './images/photo.jpg', true)
+```
+
+
+
+**ensure**
+
+```ts
+await diskCache.ensure('config', JSON.stringify(defaultConfig))
+```
+
+
+
+**copy**
+
+```ts
+await diskCache.copy('original', 'backup')
+await diskCache.copy('file1', 'file2', true) // force overwrite
+```
+
+
+
+**move**
+
+```ts
+await diskCache.move('temp', 'permanent')
+await diskCache.move('old_key', 'new_key', true) // force overwrite
+```
+
+
+
+**has**
+
+```ts
+if (await diskCache.has('myKey')) {
+ console.log('Key exists!')
+}
+```
+
+
+
+**get**
+
+```ts
+const text = await diskCache.get('myText')
+const data = await diskCache.get('myData', true) // parse as JSON
+```
+
+
+
+**set**
+
+```ts
+await diskCache.set('myKey', 'Hello World')
+await diskCache.set('userData', { name: 'John', age: 30 })
+await diskCache.set('file', content, { size: 1024, type: 'image' })
+```
+
+
+
+**rm**
+
+```ts
+await diskCache.rm('obsoleteKey')
+```
+
+
+
+**clearAll**
+
+```ts
+await diskCache.clearAll(true) // Must explicitly confirm
+```
+
+
+
+**keys**
+
+```ts
+const allKeys = await diskCache.keys()
+console.log(`Cache contains ${allKeys.length} items`)
+```
+
+
+
+**listKeys**
+
+```ts
+const keyList = await diskCache.listKeys()
+```
+
+
+
+**create**
+
+```ts
+const customCache = diskCache.create('/custom/cache/path')
+```
+
+
+
+**securely**
+
+```ts
+// Initialize with encryption
+const cache = container.feature('diskCache', { 
+ encrypt: true, 
+ secret: Buffer.from('my-secret-key') 
+})
+
+// Use encrypted operations
+await cache.securely.set('sensitive', 'secret data')
+const decrypted = await cache.securely.get('sensitive')
+```
+