luca 3.0.0 → 3.0.2

package/docs/examples/telegram.md

@@ -1,77 +0,0 @@
----
-title: "Telegram Bot"
-tags: [telegram, bot, messaging, grammy]
-lastTested: null
-lastTestPassed: null
----
-
-# telegram
-
-Telegram bot feature powered by grammY. Supports long-polling and webhook modes, with the full grammY Bot instance exposed for direct API access. Events bridge to Luca's event bus.
-
-## Overview
-
-Use the `telegram` feature when you need to build a Telegram bot. It wraps the grammY library and handles bot lifecycle (start, stop, polling, webhooks) while bridging Telegram events into Luca's event system.
-
-Requires a `TELEGRAM_BOT_TOKEN` environment variable or a `token` option from [@BotFather](https://t.me/BotFather).
-
-## Enabling the Feature
-
-```ts
-const tg = container.feature('telegram', {
-  mode: 'polling',
-  dropPendingUpdates: true
-})
-console.log('Telegram feature created, mode:', tg.mode)
-```
-
-The feature reads `TELEGRAM_BOT_TOKEN` from the environment automatically. You can also pass `token` explicitly as an option.
-
-## API Documentation
-
-```ts
-const info = await container.features.describe('telegram')
-console.log(info)
-```
-
-## Registering Commands
-
-Bot commands are registered with `.command()` and also emit events on Luca's event bus.
-
-```ts skip
-tg.command('start', (ctx) => ctx.reply('Welcome! I am your Luca bot.'))
-tg.command('help', (ctx) => ctx.reply('Available: /start, /help, /ping'))
-tg.command('ping', (ctx) => ctx.reply('Pong!'))
-console.log('Registered commands:', tg.state.commandsRegistered)
-```
-
-If the bot were running with a valid token, sending `/start` in Telegram would reply with "Welcome! I am your Luca bot." and the `command` event would fire on the Luca event bus.
-
-## Handling Messages
-
-Use `.handle()` to register grammY update handlers for any filter query.
-
-```ts skip
-tg.handle('message:text', (ctx) => {
-  ctx.reply(`Echo: ${ctx.message.text}`)
-})
-tg.handle('callback_query:data', (ctx) => {
-  ctx.answerCallbackQuery('Button clicked!')
-})
-```
-
-The `.handle()` method maps directly to grammY's `bot.on()` and supports all grammY filter queries like `message:photo`, `edited_message`, and `callback_query:data`.
-
-## Starting the Bot
-
-```ts skip
-await tg.start()
-console.log('Bot is running:', tg.isRunning)
-console.log('Mode:', tg.mode)
-```
-
-Once started in polling mode, the bot continuously fetches updates from Telegram. Call `await tg.stop()` to shut down gracefully. The `started` and `stopped` events fire on the Luca event bus.
-
-## Summary
-
-The `telegram` feature provides a complete Telegram bot lifecycle manager. Register commands and handlers, then start polling or set up a webhook. All Telegram events are bridged to Luca's event bus for integration with other features. Key methods: `command()`, `handle()`, `start()`, `stop()`, `setupWebhook()`.

package/docs/examples/tts.md

@@ -1,86 +0,0 @@
----
-title: "Text-to-Speech"
-tags: [tts, speech, audio, runpod, chatterbox]
-lastTested: null
-lastTestPassed: null
----
-
-# tts
-
-Text-to-speech feature that synthesizes audio files via RunPod's Chatterbox Turbo endpoint. Supports 20 preset voices and voice cloning from a reference audio URL.
-
-## Overview
-
-Use the `tts` feature when you need to generate speech audio from text. It calls the Chatterbox Turbo public endpoint on RunPod, downloads the resulting audio, and saves it locally. Choose from 20 preset voices or clone any voice by providing a reference audio URL.
-
-Requires a `RUNPOD_API_KEY` environment variable or an `apiKey` option.
-
-## Enabling the Feature
-
-```ts
-const tts = container.feature('tts', {
-  voice: 'lucy',
-  format: 'wav',
-  outputDir: '/tmp/tts-output'
-})
-console.log('TTS feature created')
-console.log('Default voice:', tts.options.voice)
-console.log('Output format:', tts.options.format)
-```
-
-## API Documentation
-
-```ts
-const info = await container.features.describe('tts')
-console.log(info)
-```
-
-## Available Voices
-
-List all 20 preset voice names.
-
-```ts
-console.log('Available voices:', tts.voices.join(', '))
-```
-
-## Generating Speech
-
-Synthesize text with a preset voice.
-
-```ts skip
-const path = await tts.synthesize('Good morning! Here is your daily briefing.', {
-  voice: 'ethan'
-})
-console.log('Audio saved to:', path)
-console.log('Last generated file:', tts.state.lastFile)
-```
-
-The synthesize method sends the text to RunPod, waits for generation, downloads the audio, and saves it to the output directory. The `synthesized` event fires with the file path on completion.
-
-## Voice Cloning
-
-Clone any voice by providing a reference audio URL.
-
-```ts skip
-const path = await tts.synthesize('Hello world, this is a cloned voice.', {
-  voiceUrl: 'https://example.com/reference-voice.wav'
-})
-console.log('Cloned voice audio saved to:', path)
-```
-
-The reference audio should be a clear recording of the voice you want to clone. The Chatterbox Turbo model uses it to match the voice characteristics.
-
-## Output Formats
-
-```ts skip
-const wav = await tts.synthesize('WAV format', { format: 'wav' })
-const flac = await tts.synthesize('FLAC format', { format: 'flac' })
-const ogg = await tts.synthesize('OGG format', { format: 'ogg' })
-console.log('Generated files:', wav, flac, ogg)
-```
-
-Three output formats are supported: WAV (default, uncompressed), FLAC (lossless compressed), and OGG (lossy compressed).
-
-## Summary
-
-The `tts` feature generates speech audio via RunPod's Chatterbox Turbo. Choose from 20 preset voices or clone a custom voice with a reference URL. Supports WAV, FLAC, and OGG output formats. Key methods: `synthesize()`. Key getters: `voices`, `outputDir`.

package/docs/examples/ui.md

@@ -1,80 +0,0 @@
----
-title: "ui"
-tags: [ui, terminal, colors, ascii-art, core]
-lastTested: null
-lastTestPassed: null
----
-
-# ui
-
-Terminal UI utilities including colors, ASCII art, gradients, and markdown rendering.
-
-## Overview
-
-The `ui` feature is a core feature, auto-enabled on every container. You can access it directly as a global or via `container.feature('ui')`. It provides chalk-based color styling, figlet-powered ASCII art, color gradient effects, and terminal markdown rendering. Use it to make CLI output readable and visually organized.
-
-## Text Colors
-
-The `colors` getter provides the full chalk API for coloring and styling terminal text.
-
-```ts
-const { colors } = ui
-console.log(colors.green('Success: all tests passed'))
-console.log(colors.red('Error: file not found'))
-console.log(colors.yellow('Warning: deprecated API'))
-console.log(colors.bold.cyan('Info: build complete'))
-```
-
-Colors can be chained with styles like `bold`, `italic`, `underline`, and `dim`.
-
-## ASCII Art
-
-Use `asciiArt()` to render text in large figlet fonts. Pass the text and a font name.
-
-```ts
-const art = ui.asciiArt('LUCA', 'Standard')
-console.log(art)
-```
-
-The `fonts` getter lists all available figlet fonts if you want to explore options.
-
-## Banner with Gradient
-
-Use `banner()` to combine ASCII art with a color gradient for eye-catching headers.
-
-```ts
-const result = ui.banner('Hello', { font: 'Small', colors: ['cyan', 'blue', 'magenta'] })
-console.log(result)
-```
-
-The gradient is applied automatically across the lines of the ASCII art.
-
-## Color Gradients
-
-Use `applyGradient()` to apply color transitions to any text. Choose between horizontal (per-character) and vertical (per-line) directions.
-
-```ts
-const horizontal = ui.applyGradient('Horizontal gradient across this text', ['red', 'yellow', 'green'], 'horizontal')
-console.log(horizontal)
-
-const lines = 'Line one\nLine two\nLine three\nLine four'
-const vertical = ui.applyGradient(lines, ['cyan', 'blue', 'magenta'], 'vertical')
-console.log(vertical)
-```
-
-Horizontal gradients color each character individually. Vertical gradients color each line uniformly.
-
-## Markdown Rendering
-
-Use `markdown()` to render a markdown string for terminal display with formatting preserved.
-
-```ts
-const md = ui.markdown('## Features\n\n- **Bold** text\n- `inline code`\n- Regular paragraph text\n')
-console.log(md)
-```
-
-This uses marked-terminal under the hood to produce styled terminal output from markdown source.
-
-## Summary
-
-This demo covered text coloring with chalk, ASCII art generation with figlet, gradient banners, horizontal and vertical color gradients, and markdown rendering. The `ui` feature handles all the visual polish for terminal applications.

package/docs/examples/vault.md

@@ -1,70 +0,0 @@
----
-title: "Vault"
-tags: [vault, encryption, security, crypto]
-lastTested: null
-lastTestPassed: null
----
-
-# vault
-
-AES-256-GCM encryption and decryption for sensitive data. Encrypt strings and get them back with a simple two-method API.
-
-## Overview
-
-The `vault` feature is on-demand. It generates or accepts a secret key and provides `encrypt()` and `decrypt()` methods using AES-256-GCM, an authenticated encryption scheme. Use it to protect sensitive configuration values, tokens, or any data that should not be stored in plaintext.
-
-## Enabling the Vault
-
-Create a vault instance. It will generate a secret key automatically.
-
-```ts
-const vault = container.feature('vault')
-console.log('Vault enabled:', vault.state.get('enabled'))
-```
-
-The vault is ready to use immediately after creation.
-
-## Encrypting a String
-
-Pass any plaintext string to `encrypt()` and receive an opaque encrypted payload.
-
-```ts
-const secret = 'my-database-password-12345'
-const encrypted = vault.encrypt(secret)
-console.log('Original:', secret)
-console.log('Encrypted:', encrypted)
-console.log('Encrypted length:', encrypted.length)
-```
-
-The encrypted output is a base64-encoded string containing the IV, auth tag, and ciphertext. It is safe to store in config files or databases.
-
-## Decrypting Back to Plaintext
-
-Use `decrypt()` with the same vault instance to recover the original value.
-
-```ts
-const decrypted = vault.decrypt(encrypted)
-console.log('Decrypted:', decrypted)
-console.log('Round-trip matches:', decrypted === secret)
-```
-
-The decrypted value is identical to the original input.
-
-## Encrypting Multiple Values
-
-Each call to `encrypt()` produces a unique ciphertext, even for the same input, because a fresh IV is generated every time.
-
-```ts
-const a = vault.encrypt('same-input')
-const b = vault.encrypt('same-input')
-console.log('Encryption A:', a)
-console.log('Encryption B:', b)
-console.log('Same ciphertext?', a === b)
-console.log('Both decrypt correctly?', vault.decrypt(a) === vault.decrypt(b))
-```
-
-This property (semantic security) means an attacker cannot tell if two ciphertexts contain the same plaintext.
-
-## Summary
-
-This demo covered enabling the vault, encrypting strings, decrypting them back, and verifying that repeated encryption produces unique ciphertexts. The `vault` feature provides straightforward authenticated encryption for any sensitive data your application handles.

package/docs/examples/vm.md

@@ -1,86 +0,0 @@
----
-title: "vm"
-tags: [vm, sandbox, evaluation, core]
-lastTested: null
-lastTestPassed: null
----
-
-# vm
-
-JavaScript VM for evaluating code in isolated contexts with shared or independent state.
-
-## Overview
-
-The `vm` feature is a core feature, auto-enabled on every container. You can access it directly as a global or via `container.feature('vm')`. It provides methods for running JavaScript in sandboxed contexts, passing variables in, and optionally preserving state across multiple runs. Use it for plugin systems, dynamic code evaluation, or testing snippets in isolation.
-
-## Simple Expression Evaluation
-
-Use `runSync()` to evaluate a JavaScript expression and get the result back immediately.
-
-```ts
-const sum = vm.runSync('2 + 3 * 4')
-console.log('2 + 3 * 4 =', sum)
-
-const greeting = vm.runSync('`Hello ${name}!`', { name: 'Luca' })
-console.log(greeting)
-```
-
-The second argument is an optional context object whose keys become variables in the evaluated code.
-
-## Running with Context Variables
-
-Use `run()` for async evaluation with injected variables. This is the async equivalent of `runSync()`.
-
-```ts
-const result = await vm.run('numbers.reduce((a, b) => a + b, 0)', {
-  numbers: [10, 20, 30, 40]
-})
-console.log('Sum of [10, 20, 30, 40]:', result)
-```
-
-Any JavaScript value can be passed through the context -- arrays, objects, functions, and primitives.
-
-## Getting the Context Back
-
-Use `performSync()` to run code and get both the result and the modified context. This lets you inspect variables that were set during execution.
-
-```ts
-const { result, context } = vm.performSync('x = x * 2; x + 1', { x: 21 })
-console.log('Result:', result)
-console.log('x after execution:', context.x)
-```
-
-The context is mutated in place, so you can see side effects of the evaluated code.
-
-## Shared State Across Runs
-
-Use `createContext()` to build a persistent context that carries state across multiple evaluations.
-
-```ts
-const ctx = vm.createContext({ counter: 0 })
-vm.runSync('counter += 1', ctx)
-vm.runSync('counter += 1', ctx)
-vm.runSync('counter += 10', ctx)
-console.log('Counter after 3 runs:', vm.runSync('counter', ctx))
-```
-
-The same context object is reused, so variables accumulate across calls.
-
-## Error Handling
-
-When evaluated code might throw, wrap the call in a try/catch to handle it gracefully.
-
-```ts
-try {
-  vm.runSync('undefinedFunction()')
-} catch (err) {
-  console.log('Error caught:', err.constructor.name)
-  console.log('Message:', err.message)
-}
-```
-
-This keeps a bad snippet from crashing the rest of your program.
-
-## Summary
-
-This demo covered synchronous and async expression evaluation, passing context variables into the sandbox, inspecting mutated context after execution, maintaining shared state across runs, and safe error handling. The `vm` feature is the foundation for dynamic code execution in any Luca application.

package/docs/examples/websocket-ask-and-reply-example.md

@@ -1,128 +0,0 @@
----
-title: "websocket-ask-and-reply"
-tags: [websocket, client, server, ask, reply, rpc]
-lastTested: null
-lastTestPassed: null
----
-
-# websocket-ask-and-reply
-
-Request/response conversations over WebSocket using `ask()` and `reply()`.
-
-## Overview
-
-The WebSocket client and server both support a request/response protocol on top of the normal fire-and-forget message stream. The client can `ask()` the server a question and await the answer. The server can `ask()` a connected client the same way. Under the hood it works with correlation IDs — `requestId` on the request, `replyTo` on the response — but you never have to touch those directly.
-
-## Setup
-
-Declare the shared references that all blocks will use, and wire up the server's message handler. This block is synchronous so the variables persist across subsequent blocks.
-
-```ts
-var port = 0
-var server = container.server('websocket', { json: true })
-var client = null
-
-server.on('message', (data, ws) => {
-  if (data.type === 'add') {
-    data.reply({ sum: data.data.a + data.data.b })
-  } else if (data.type === 'divide') {
-    if (data.data.b === 0) {
-      data.replyError('division by zero')
-    } else {
-      data.reply({ result: data.data.a / data.data.b })
-    }
-  }
-})
-console.log('Server and handlers configured')
-```
-
-## Start Server and Connect Client
-
-```ts
-port = await networking.findOpenPort(19900)
-await server.start({ port })
-console.log('Server listening on port', port)
-
-client = container.client('websocket', { baseURL: `ws://localhost:${port}` })
-await client.connect()
-console.log('Client connected')
-```
-
-## Client Asks the Server
-
-`ask(type, data, timeout?)` sends a message and returns a promise that resolves with the response payload.
-
-```ts
-var sum = await client.ask('add', { a: 3, b: 4 })
-console.log('3 + 4 =', sum.sum)
-
-var quotient = await client.ask('divide', { a: 10, b: 3 })
-console.log('10 / 3 =', quotient.result.toFixed(2))
-```
-
-## Handling Errors
-
-When the server calls `replyError(message)`, the client's `ask()` promise rejects with that message.
-
-```ts
-try {
-  await client.ask('divide', { a: 1, b: 0 })
-} catch (err) {
-  console.log('Caught error:', err.message)
-}
-```
-
-## Server Asks the Client
-
-The server can also ask a connected client. The client handles incoming requests by listening for messages with a `requestId` and sending back a `replyTo` response.
-
-```ts
-client.on('message', (data) => {
-  if (data.requestId && data.type === 'whoAreYou') {
-    client.send({ replyTo: data.requestId, data: { name: 'luca-client', version: '1.0' } })
-  }
-})
-
-var firstClient = [...server.connections][0]
-var identity = await server.ask(firstClient, 'whoAreYou')
-console.log('Client identified as:', identity.name, identity.version)
-```
-
-## Timeouts
-
-If nobody replies, `ask()` rejects after the timeout (default 10s, configurable as the third argument).
-
-```ts
-try {
-  await client.ask('noop', {}, 500)
-} catch (err) {
-  console.log('Timed out as expected:', err.message)
-}
-```
-
-## Regular Messages Still Work
-
-Messages without `requestId` flow through the normal `message` event as always. The ask/reply protocol is purely additive.
-
-```ts
-var received = null
-server.on('message', (data) => {
-  if (data.type === 'ping') received = data
-})
-
-await client.send({ type: 'ping', ts: Date.now() })
-await new Promise(r => setTimeout(r, 50))
-console.log('Regular message received:', received.type, '— no requestId:', received.requestId === undefined)
-```
-
-## Cleanup
-
-```ts
-await client.disconnect()
-await server.stop()
-console.log('Done')
-```
-
-## Summary
-
-The ask/reply protocol gives you awaitable request/response over WebSocket without leaving the Luca helper API. The client calls `ask(type, data)` and gets back a promise. The server's message handler gets `reply()` and `replyError()` injected on any message that carries a `requestId`. The server can also `ask()` a specific client. Timeouts, error propagation, and cleanup of pending requests on disconnect are all handled automatically.

package/docs/examples/yaml-tree.md

@@ -1,93 +0,0 @@
----
-title: "YAML Tree"
-tags: [yamlTree, yaml, files, data-loading]
-lastTested: null
-lastTestPassed: null
----
-
-# yamlTree
-
-Load YAML files from directory structures into a nested object tree.
-
-## Overview
-
-The `yamlTree` feature is an on-demand feature that recursively scans a directory for `.yml` and `.yaml` files and builds a hierarchical JavaScript object from them. It works identically to `jsonTree` but for YAML content. File paths are converted to camelCased property paths, so `config/database/production.yml` becomes `tree.config.database.production`. This is useful for projects that store configuration, infrastructure definitions, or data in YAML format.
-
-## Feature Documentation
-
-Let us inspect the feature's built-in documentation.
-
-```ts
-const desc = container.features.describe('yamlTree')
-console.log(desc)
-```
-
-Like jsonTree, the key method is `loadTree(basePath, key?)` and the data is accessed through the `tree` getter.
-
-## Enabling the Feature
-
-Enable yamlTree and check its initial state.
-
-```ts
-const yamlTree = container.feature('yamlTree', { enable: true })
-console.log('yamlTree enabled:', yamlTree.state.enabled)
-console.log('Initial tree:', JSON.stringify(yamlTree.tree))
-```
-
-The tree starts empty until you load directories into it.
-
-## Loading YAML Files
-
-We can attempt to load YAML files from the project. If the project has any `.yml` or `.yaml` files, they will appear in the tree.
-
-```ts
-await yamlTree.loadTree('.', 'root')
-const keys = Object.keys(yamlTree.tree.root || {})
-console.log('Keys loaded under root:', keys.length ? keys.join(', ') : '(no YAML files found)')
-```
-
-If no YAML files are found, the tree for that key will be empty. This is expected for projects that do not use YAML.
-
-## How It Compares to jsonTree
-
-The yamlTree and jsonTree features share the same design pattern:
-
-- Both recursively scan directories
-- Both convert file paths to camelCased property paths
-- Both store results in a `tree` getter
-- Both accept a custom key for namespacing
-
-The only difference is the file extensions they look for and the parser they use.
-
-```ts
-const comparison = {
-  jsonTree: { extensions: ['.json'], parser: 'JSON.parse' },
-  yamlTree: { extensions: ['.yml', '.yaml'], parser: 'YAML parser' },
-}
-for (const [name, info] of Object.entries(comparison)) {
-  console.log(`${name}: scans ${info.extensions.join(', ')} files, uses ${info.parser}`)
-}
-```
-
-## Path Transformation Rules
-
-The same path transformation rules apply as in jsonTree:
-
-- Directory names become nested object properties
-- File names (without extension) become leaf properties
-- All names are converted to camelCase
-
-```ts
-const mappings = {
-  'infra/k8s/deployment.yml': 'tree.infra.k8s.deployment',
-  'config/app-settings.yaml': 'tree.config.appSettings',
-  'data/seed/users.yml': 'tree.data.seed.users',
-}
-for (const [file, path] of Object.entries(mappings)) {
-  console.log(`${file} => ${path}`)
-}
-```
-
-## Summary
-
-This demo covered the `yamlTree` feature, which scans directories for YAML files (.yml and .yaml) and builds a nested object tree. It follows the same pattern as `jsonTree` and is ideal for projects that rely on YAML for configuration, infrastructure definitions, or structured data.