luca 2.0.0 → 3.0.0

package/docs/apis/features/node/secure-shell.md

@@ -0,0 +1,176 @@
+# SecureShell (features.secureShell)
+
+SecureShell Feature -- SSH command execution and SCP file transfers. Uses the system `ssh` and `scp` binaries to run commands on remote hosts and transfer files. Supports key-based and password-based authentication through the container's `proc` feature.
+
+## Usage
+
+```ts
+container.feature('secureShell', {
+  // Remote host address
+  host,
+  // SSH port number (default: 22)
+  port,
+  // Username for SSH authentication
+  username,
+  // Password for SSH authentication
+  password,
+  // Path to SSH private key file
+  key,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `host` | `string` | Remote host address |
+| `port` | `number` | SSH port number (default: 22) |
+| `username` | `string` | Username for SSH authentication |
+| `password` | `string` | Password for SSH authentication |
+| `key` | `string` | Path to SSH private key file |
+
+## Methods
+
+### testConnection
+
+Test the SSH connection by running a simple echo command on the remote host. Updates `state.connected` based on the result.
+
+**Returns:** `Promise<boolean>`
+
+```ts
+const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+const ok = await ssh.testConnection()
+if (!ok) console.error('SSH connection failed')
+```
+
+
+
+### exec
+
+Executes a command on the remote host.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `command` | `string` | ✓ | The command to execute on the remote shell |
+
+**Returns:** `Promise<string>`
+
+```ts
+const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+const listing = await ssh.exec('ls -la /var/log')
+console.log(listing)
+```
+
+
+
+### download
+
+Downloads a file from the remote host via SCP.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `source` | `string` | ✓ | The source file path on the remote host |
+| `target` | `string` | ✓ | The target file path on the local machine |
+
+**Returns:** `Promise<string>`
+
+```ts
+const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+await ssh.download('/var/log/app.log', './logs/app.log')
+```
+
+
+
+### upload
+
+Uploads a file to the remote host via SCP.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `source` | `string` | ✓ | The source file path on the local machine |
+| `target` | `string` | ✓ | The target file path on the remote host |
+
+**Returns:** `Promise<string>`
+
+```ts
+const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+await ssh.upload('./build/app.tar.gz', '/opt/releases/app.tar.gz')
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `sshPath` | `string` | Resolved path to the ssh binary |
+| `scpPath` | `string` | Resolved path to the scp binary |
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `connected` | `boolean` | Whether an SSH connection is currently active |
+
+## Examples
+
+**features.secureShell**
+
+```ts
+const ssh = container.feature('secureShell', {
+ host: '192.168.1.100',
+ username: 'deploy',
+ key: '~/.ssh/id_ed25519',
+})
+
+if (await ssh.testConnection()) {
+ const uptime = await ssh.exec('uptime')
+ console.log(uptime)
+}
+```
+
+
+
+**testConnection**
+
+```ts
+const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+const ok = await ssh.testConnection()
+if (!ok) console.error('SSH connection failed')
+```
+
+
+
+**exec**
+
+```ts
+const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+const listing = await ssh.exec('ls -la /var/log')
+console.log(listing)
+```
+
+
+
+**download**
+
+```ts
+const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+await ssh.download('/var/log/app.log', './logs/app.log')
+```
+
+
+
+**upload**
+
+```ts
+const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+await ssh.upload('./build/app.tar.gz', '/opt/releases/app.tar.gz')
+```
+

package/docs/apis/features/node/semantic-search.md

@@ -0,0 +1,408 @@
+# SemanticSearch (features.semanticSearch)
+
+Semantic search feature providing BM25 keyword search, vector similarity search, and hybrid search with Reciprocal Rank Fusion over a SQLite-backed index. Uses bun:sqlite for FTS5 keyword search and BLOB-stored embeddings with JavaScript cosine similarity for vector search.
+
+## Usage
+
+```ts
+container.feature('semanticSearch', {
+  // Path to the SQLite database file
+  dbPath,
+  // Embedding model name
+  embeddingModel,
+  // Where to generate embeddings
+  embeddingProvider,
+  // How to split documents
+  chunkStrategy,
+  // Token limit per chunk for fixed strategy
+  chunkSize,
+  // Overlap ratio for fixed strategy
+  chunkOverlap,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dbPath` | `string` | Path to the SQLite database file |
+| `embeddingModel` | `string` | Embedding model name |
+| `embeddingProvider` | `string` | Where to generate embeddings |
+| `chunkStrategy` | `string` | How to split documents |
+| `chunkSize` | `number` | Token limit per chunk for fixed strategy |
+| `chunkOverlap` | `number` | Overlap ratio for fixed strategy |
+
+## Methods
+
+### initDb
+
+**Returns:** `Promise<void>`
+
+
+
+### insertDocument
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `doc` | `DocumentInput` | ✓ | Parameter doc |
+
+`DocumentInput` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pathId` | `string` |  |
+| `model` | `string` |  |
+| `title` | `string` |  |
+| `slug` | `string` |  |
+| `meta` | `Record<string, any>` |  |
+| `content` | `string` |  |
+| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
+
+**Returns:** `void`
+
+
+
+### insertChunk
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `chunk` | `Chunk` | ✓ | Parameter chunk |
+
+`Chunk` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pathId` | `string` |  |
+| `section` | `string` |  |
+| `headingPath` | `string` |  |
+| `seq` | `number` |  |
+| `content` | `string` |  |
+| `contentHash` | `string` |  |
+| `embedding` | `Float32Array` | ✓ | Parameter embedding |
+
+**Returns:** `void`
+
+
+
+### removeDocument
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `pathId` | `string` | ✓ | Parameter pathId |
+
+**Returns:** `void`
+
+
+
+### getStats
+
+**Returns:** `IndexStatus`
+
+
+
+### embed
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `texts` | `string[]` | ✓ | Parameter texts |
+
+**Returns:** `Promise<number[][]>`
+
+
+
+### ensureModel
+
+**Returns:** `Promise<void>`
+
+
+
+### disposeModel
+
+**Returns:** `Promise<void>`
+
+
+
+### getDimensions
+
+**Returns:** `number`
+
+
+
+### chunkDocument
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `doc` | `DocumentInput` | ✓ | Parameter doc |
+
+`DocumentInput` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pathId` | `string` |  |
+| `model` | `string` |  |
+| `title` | `string` |  |
+| `slug` | `string` |  |
+| `meta` | `Record<string, any>` |  |
+| `content` | `string` |  |
+| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
+| `strategy` | `'section' | 'fixed' | 'document'` |  | Parameter strategy |
+
+**Returns:** `Chunk[]`
+
+
+
+### search
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | Parameter query |
+| `options` | `SearchOptions` |  | Parameter options |
+
+`SearchOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `limit` | `number` |  |
+| `model` | `string` |  |
+| `where` | `Record<string, any>` |  |
+
+**Returns:** `Promise<SearchResult[]>`
+
+
+
+### vectorSearch
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | Parameter query |
+| `options` | `SearchOptions` |  | Parameter options |
+
+`SearchOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `limit` | `number` |  |
+| `model` | `string` |  |
+| `where` | `Record<string, any>` |  |
+
+**Returns:** `Promise<SearchResult[]>`
+
+
+
+### hybridSearch
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | Parameter query |
+| `options` | `HybridSearchOptions` |  | Parameter options |
+
+`HybridSearchOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ftsWeight` | `number` |  |
+| `vecWeight` | `number` |  |
+
+**Returns:** `Promise<SearchResult[]>`
+
+
+
+### deepSearch
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `_query` | `string` | ✓ | Parameter _query |
+| `_options` | `SearchOptions` |  | Parameter _options |
+
+`SearchOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `limit` | `number` |  |
+| `model` | `string` |  |
+| `where` | `Record<string, any>` |  |
+
+**Returns:** `Promise<SearchResult[]>`
+
+
+
+### indexDocuments
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `DocumentInput[]` | ✓ | Parameter docs |
+
+`DocumentInput[]` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pathId` | `string` |  |
+| `model` | `string` |  |
+| `title` | `string` |  |
+| `slug` | `string` |  |
+| `meta` | `Record<string, any>` |  |
+| `content` | `string` |  |
+| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
+
+**Returns:** `Promise<void>`
+
+
+
+### reindex
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `pathIds` | `string[]` |  | Parameter pathIds |
+
+**Returns:** `Promise<void>`
+
+
+
+### removeStale
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `currentPathIds` | `string[]` | ✓ | Parameter currentPathIds |
+
+**Returns:** `void`
+
+
+
+### needsReindex
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `doc` | `DocumentInput` | ✓ | Parameter doc |
+
+`DocumentInput` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pathId` | `string` |  |
+| `model` | `string` |  |
+| `title` | `string` |  |
+| `slug` | `string` |  |
+| `meta` | `Record<string, any>` |  |
+| `content` | `string` |  |
+| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
+
+**Returns:** `boolean`
+
+
+
+### status
+
+**Returns:** `IndexStatus`
+
+
+
+### installLocalEmbeddings
+
+Install node-llama-cpp into the user's project for local embedding support. Detects package manager from lockfile presence and verifies the native addon loads.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `cwd` | `string` | ✓ | Parameter cwd |
+
+**Returns:** `Promise<void>`
+
+
+
+### close
+
+**Returns:** `Promise<void>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `db` | `Database` |  |
+| `dimensions` | `number` |  |
+
+## Events (Zod v4 schema)
+
+### dbReady
+
+When the SQLite database is initialized and ready
+
+
+
+### modelLoaded
+
+When the local embedding model is loaded into memory
+
+
+
+### modelDisposed
+
+When the local embedding model is disposed from memory
+
+
+
+### indexed
+
+When documents are indexed with embeddings
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `documents` | `number` | Number of documents indexed |
+| `chunks` | `number` | Number of chunks created |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `indexed` | `number` | Count of indexed documents |
+| `embedded` | `number` | Count of documents with embeddings |
+| `lastIndexedAt` | `any` | ISO timestamp of last indexing |
+| `dbReady` | `boolean` | Whether SQLite is initialized |
+
+## Examples
+
+**features.semanticSearch**
+
+```ts
+const search = container.feature('semanticSearch', {
+ dbPath: '.contentbase/search.sqlite',
+ embeddingProvider: 'local',
+})
+await search.initDb()
+await search.indexDocuments(docs)
+const results = await search.hybridSearch('how does authentication work')
+```
+