luca 3.0.0 → 3.1.0

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

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

@@ -1,408 +0,0 @@
-# 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')
-```
-