@soederpop/luca 0.0.2

package/docs/examples/python.md

@@ -0,0 +1,91 @@
+---
+title: "Python"
+tags: [python, scripting, virtualenv, integration]
+lastTested: null
+lastTestPassed: null
+---
+
+# python
+
+Python virtual machine feature for executing Python code, managing environments, and installing dependencies. Automatically detects uv, conda, venv, or system Python.
+
+## Overview
+
+The `python` feature provides a bridge between Luca and the Python ecosystem. It auto-detects the best available Python environment (uv, conda, venv, system), can install project dependencies, and execute Python code with variable injection and local variable capture. Requires Python to be installed on the host.
+
+## Enabling the Feature
+
+```ts
+const python = container.feature('python', { enable: true })
+console.log('Python feature enabled:', python.state.get('enabled'))
+console.log('Python ready:', python.state.get('isReady'))
+```
+
+## Exploring the API
+
+```ts
+const docs = container.features.describe('python')
+console.log(docs)
+```
+
+## Environment Detection
+
+```ts
+const python = container.feature('python')
+await python.detectEnvironment()
+console.log('Environment type:', python.state.get('environmentType'))
+console.log('Python path:', python.state.get('pythonPath'))
+```
+
+## Running Inline Code
+
+Execute Python code directly and capture the output.
+
+```ts skip
+const result = await python.execute('print("Hello from Python!")')
+console.log('stdout:', result.stdout)
+console.log('exit code:', result.exitCode)
+```
+
+You can also pass variables into the Python context and capture locals after execution.
+
+```ts skip
+const result = await python.execute(
+  'greeting = f"Hello {name}, you are {age}!";\nprint(greeting)',
+  { name: 'Alice', age: 30 },
+  { captureLocals: true }
+)
+console.log('stdout:', result.stdout)
+console.log('locals:', result.locals)
+```
+
+The `captureLocals` option serializes all local variables from the script back to JavaScript as JSON.
+
+## Running a Script File
+
+Execute an existing `.py` file and capture its output.
+
+```ts skip
+const result = await python.executeFile('/path/to/analysis.py')
+console.log('stdout:', result.stdout)
+console.log('stderr:', result.stderr)
+```
+
+## Creating a Virtual Environment
+
+Install project dependencies using the auto-detected package manager.
+
+```ts skip
+const python = container.feature('python', {
+  dir: '/path/to/python-project',
+  installCommand: 'pip install -r requirements.txt'
+})
+const result = await python.installDependencies()
+console.log('Install exit code:', result.exitCode)
+```
+
+When no `installCommand` is provided, the feature infers the correct command from the detected environment type (e.g., `uv sync` for uv, `pip install -e .` for venv).
+
+## Summary
+
+The `python` feature bridges Luca and Python by auto-detecting environments, managing dependencies, and providing inline code execution with variable injection. It supports uv, conda, venv, and system Python installations.

package/docs/examples/repl.md

@@ -0,0 +1,93 @@
+---
+title: "REPL"
+tags: [repl, interactive, debugging, console]
+lastTested: null
+lastTestPassed: null
+---
+
+# repl
+
+Interactive read-eval-print loop with tab completion, history, and full container access.
+
+## Overview
+
+The `repl` feature is an on-demand feature that launches an interactive REPL session inside a VM context populated with the container and all its helpers. It supports tab completion for dot-notation property access, command history persistence, and top-level await. Since it is interactive, it cannot run inside a markdown code block -- instead, the typical workflow is to run `luca run somefile.md --console` which executes all code blocks first and then drops into a REPL with the accumulated context.
+
+## Feature Documentation
+
+Let us inspect the feature's built-in documentation.
+
+```ts
+const desc = container.features.describe('repl')
+console.log(desc)
+```
+
+The main method is `start(options?)` which begins the interactive session. It accepts an optional context object and history path.
+
+## Enabling the Feature
+
+We can enable the feature and inspect its state without starting the interactive session.
+
+```ts
+const repl = container.feature('repl', { enable: true })
+console.log('REPL enabled:', repl.state.enabled)
+console.log('REPL started:', repl.state.started)
+```
+
+The feature is enabled but not started. Starting it would block execution waiting for interactive input, which is not suitable for a markdown runner context.
+
+## Configuration Options
+
+The REPL feature accepts several options for customization.
+
+```ts
+const options = {
+  prompt: 'Custom prompt string displayed before each input line',
+  historyPath: 'Path to a file where command history is persisted between sessions',
+  context: 'Additional variables injected into the VM evaluation context',
+}
+for (const [key, desc] of Object.entries(options)) {
+  console.log(`  ${key}: ${desc}`)
+}
+```
+
+When you provide a `context` object to `start()`, those variables become globally available in the REPL session alongside the container and its helpers.
+
+## How to Use the REPL
+
+The recommended way to use the REPL is through the `--console` flag on `luca run`.
+
+```ts
+console.log('Usage patterns:')
+console.log('')
+console.log('  luca run script.md --console')
+console.log('    Run all code blocks, then drop into REPL with accumulated context')
+console.log('')
+console.log('  luca run setup.md --console')
+console.log('    Execute setup code, then explore interactively')
+console.log('')
+console.log('Inside the REPL:')
+console.log('  - Tab completion works on all container properties')
+console.log('  - Top-level await is supported')
+console.log('  - Type .exit or exit to quit')
+```
+
+This is especially powerful when combined with runnable markdown files: you define your setup and data loading in code blocks, then explore the results interactively in the REPL.
+
+## REPL Context
+
+When launched via `--console`, the REPL inherits everything from the markdown execution context. This means all variables, enabled features, and loaded data carry over.
+
+```ts
+console.log('The REPL context automatically includes:')
+const globals = ['container', 'fs', 'git', 'proc', 'grep', 'os', 'networking', 'ui', 'vm', 'esbuild', 'console']
+for (const name of globals) {
+  console.log(`  ${name}`)
+}
+console.log('')
+console.log('Plus any variables defined in preceding code blocks.')
+```
+
+## Summary
+
+This demo covered the `repl` feature, which provides an interactive REPL with tab completion, history, and async support. Since it is interactive by nature, it is best used via `luca run somefile.md --console` to combine scripted setup with interactive exploration. The REPL inherits the full container context plus any variables accumulated during markdown execution.

package/docs/examples/runpod.md

@@ -0,0 +1,119 @@
+---
+title: "RunPod GPU Cloud"
+tags: [runpod, gpu, cloud, pods, ssh, infrastructure]
+lastTested: null
+lastTestPassed: null
+---
+
+# runpod
+
+GPU cloud pod management via the RunPod REST API and CLI. Provision GPU instances, manage network volumes, SSH into pods, and transfer files.
+
+## Overview
+
+Use the `runpod` feature when you need to manage GPU cloud infrastructure. It provides a complete interface for creating and managing RunPod GPU pods, including template selection, volume management, SSH access, file transfers, and lifecycle operations (start, stop, remove). Integrates with the `secureShell` feature for remote command execution.
+
+Requires a `RUNPOD_API_KEY` environment variable or an `apiKey` option.
+
+## Enabling the Feature
+
+```ts
+const runpod = container.feature('runpod', {
+  dataCenterId: 'US-TX-3'
+})
+console.log('RunPod feature created')
+console.log('Data center:', runpod.dataCenterId)
+console.log('API key configured:', !!runpod.apiKey)
+```
+
+## API Documentation
+
+```ts
+const info = await container.features.describe('runpod')
+console.log(info)
+```
+
+## Listing Pods and GPUs
+
+Query your existing pods and available GPU types.
+
+```ts skip
+const pods = await runpod.getpods()
+pods.forEach(p => console.log(`${p.name}: ${p.desiredStatus} - $${p.costPerHr}/hr`))
+
+const gpus = await runpod.listSecureGPUs()
+gpus.forEach(g => console.log(`${g.gpuType}: $${g.ondemandPrice}/hr`))
+```
+
+Use `getpods()` for detailed REST API data including port mappings and public IP, or `listPods()` for a quick summary via the CLI.
+
+## Creating and Managing Pods
+
+Provision a new GPU pod and manage its lifecycle.
+
+```ts skip
+const pod = await runpod.createPod({
+  name: 'my-training-pod',
+  gpuTypeId: 'NVIDIA RTX 4090',
+  templateId: 'abc123',
+  volumeInGb: 50,
+  containerDiskInGb: 50,
+  ports: ['8888/http', '22/tcp']
+})
+console.log(`Pod ${pod.id} created`)
+
+const ready = await runpod.waitForPod(pod.id, 'RUNNING', { timeout: 120000 })
+console.log('Pod is running:', ready.desiredStatus)
+```
+
+After creation, use `waitForPod()` to poll until the pod reaches the desired status.
+
+## Pod Lifecycle
+
+```ts skip
+await runpod.stopPod('pod-abc123')
+console.log('Pod stopped')
+
+await runpod.startPod('pod-abc123')
+console.log('Pod restarted')
+
+await runpod.removePod('pod-abc123')
+console.log('Pod permanently deleted')
+```
+
+Stopping a pod preserves its disk; removing it is permanent.
+
+## SSH and Remote Execution
+
+Connect to a running pod and execute commands remotely.
+
+```ts skip
+const shell = await runpod.getShell('pod-abc123')
+const output = await shell.exec('nvidia-smi')
+console.log(output)
+
+const ls = await shell.exec('ls /workspace')
+console.log('Workspace files:', ls)
+```
+
+The `getShell()` method uses REST API data for reliable SSH connections. Use it over `createRemoteShell()` which depends on the CLI.
+
+## Network Volumes
+
+Manage persistent storage that survives pod restarts.
+
+```ts skip
+const vol = await runpod.createVolume({ name: 'my-models', size: 100 })
+console.log(`Created volume ${vol.id}`)
+
+const volumes = await runpod.listVolumes()
+volumes.forEach(v => console.log(`${v.name}: ${v.size}GB`))
+
+await runpod.removeVolume('vol-abc123')
+```
+
+Attach network volumes to pods via the `networkVolumeId` option in `createPod()`.
+
+## Summary
+
+The `runpod` feature provides complete GPU cloud management. Create pods from templates, manage lifecycle (start/stop/remove), SSH into running pods, and manage network storage volumes. Supports polling for readiness and file transfer operations. Key methods: `createPod()`, `getpods()`, `waitForPod()`, `getShell()`, `listVolumes()`, `createVolume()`.

package/docs/examples/secure-shell.md

@@ -0,0 +1,92 @@
+---
+title: "Secure Shell"
+tags: [secureShell, ssh, scp, remote, deployment]
+lastTested: null
+lastTestPassed: null
+---
+
+# secureShell
+
+SSH command execution and SCP file transfers. Uses the system `ssh` and `scp` binaries to run commands on remote hosts and transfer files securely.
+
+## Overview
+
+The `secureShell` feature provides an SSH client for executing commands on remote machines and transferring files via SCP. It supports both key-based and password-based authentication. All operations require a reachable SSH target host, so the actual connection and command examples use skip blocks.
+
+## Enabling the Feature
+
+```ts
+const ssh = container.feature('secureShell', {
+  host: 'example.com',
+  username: 'deploy',
+  key: '~/.ssh/id_ed25519',
+  enable: true
+})
+console.log('SSH enabled:', ssh.state.get('enabled'))
+```
+
+## Exploring the API
+
+```ts
+const docs = container.features.describe('secureShell')
+console.log(docs)
+```
+
+## Feature Options
+
+```ts
+const ssh = container.feature('secureShell', {
+  host: '192.168.1.100',
+  port: 22,
+  username: 'admin',
+  key: '~/.ssh/id_rsa'
+})
+console.log('Host configured:', ssh.options.host)
+console.log('Port:', ssh.options.port || 22)
+```
+
+## Testing the Connection
+
+Verify that the SSH target is reachable before running commands.
+
+```ts skip
+const ok = await ssh.testConnection()
+console.log('Connection OK:', ok)
+console.log('State connected:', ssh.state.get('connected'))
+```
+
+The `testConnection` method runs a simple echo command on the remote host. If it succeeds, `state.connected` is set to `true`.
+
+## Executing a Remote Command
+
+Run a shell command on the remote host and capture its output.
+
+```ts skip
+const uptime = await ssh.exec('uptime')
+console.log('Remote uptime:', uptime)
+
+const listing = await ssh.exec('ls -la /var/log')
+console.log(listing)
+```
+
+The `exec` method returns the command's stdout as a string. It uses the configured host, username, and authentication credentials.
+
+## Uploading and Downloading Files
+
+Transfer files between the local machine and the remote host using SCP.
+
+```ts skip
+await ssh.upload('./build/app.tar.gz', '/opt/releases/app.tar.gz')
+console.log('Upload complete')
+```
+
+```ts skip
+await ssh.download('/var/log/app.log', './logs/app.log')
+console.log('Download complete')
+```
+
+Both methods use the same authentication credentials configured on the feature instance. Paths on the remote side are absolute or relative to the user's home directory.
+
+## Summary
+
+The `secureShell` feature wraps the system `ssh` and `scp` commands to provide remote command execution and file transfers. It supports key-based and password-based authentication, connection testing, and maintains connection state on the feature instance.

package/docs/examples/sqlite.md

@@ -0,0 +1,86 @@
+---
+title: "SQLite"
+tags: [sqlite, database, sql, storage]
+lastTested: null
+lastTestPassed: null
+---
+
+# sqlite
+
+In-process SQLite database via Bun's native binding. Create tables, insert rows, and query data with parameterized SQL or tagged templates.
+
+## Overview
+
+The `sqlite` feature is on-demand. Pass `{ path: ':memory:' }` for an in-memory database or a file path for persistence. It supports parameterized queries to prevent SQL injection and a convenient tagged-template syntax for inline SQL.
+
+## Creating an In-Memory Database
+
+Enable the feature with an in-memory path. No files are created on disk.
+
+```ts
+const db = container.feature('sqlite', { path: ':memory:' })
+console.log('SQLite enabled:', db.state.get('enabled'))
+```
+
+The database is ready for queries immediately.
+
+## Creating a Table
+
+Use `execute()` for DDL and write statements.
+
+```ts
+await db.execute(`
+  CREATE TABLE users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    email TEXT NOT NULL UNIQUE,
+    active INTEGER DEFAULT 1
+  )
+`)
+console.log('Table created')
+```
+
+The `execute()` method returns metadata including the number of changes and the last inserted row ID.
+
+## Inserting Rows
+
+Insert data using parameterized queries to keep values safe.
+
+```ts
+await db.execute('INSERT INTO users (name, email) VALUES (?, ?)', ['Alice', 'alice@example.com'])
+await db.execute('INSERT INTO users (name, email) VALUES (?, ?)', ['Bob', 'bob@example.com'])
+const result = await db.execute('INSERT INTO users (name, email, active) VALUES (?, ?, ?)', ['Charlie', 'charlie@example.com', 0])
+console.log('Last insert ID:', result.lastInsertRowid)
+console.log('Changes:', result.changes)
+```
+
+Each `?` placeholder is bound to the corresponding value in the array, preventing SQL injection.
+
+## Querying Rows
+
+Use `query()` for SELECT statements that return result rows.
+
+```ts
+const users = await db.query('SELECT * FROM users WHERE active = ?', [1])
+console.log('Active users:')
+users.forEach(u => console.log(`  ${u.id}: ${u.name} <${u.email}>`))
+```
+
+Results come back as an array of plain objects with column names as keys.
+
+## Tagged Template Queries
+
+The `sql` tagged template lets you write queries with inline interpolation that is still safely parameterized.
+
+```ts
+const emailDomain = '%example.com'
+const rows = await db.sql`SELECT name, email FROM users WHERE email LIKE ${emailDomain}`
+console.log('Users matching domain:')
+rows.forEach(r => console.log(`  ${r.name}: ${r.email}`))
+```
+
+Interpolated values become bound parameters automatically. This combines readability with safety.
+
+## Summary
+
+This demo covered creating an in-memory SQLite database, defining tables, inserting rows with parameterized queries, reading data back, and using the tagged-template SQL syntax. The `sqlite` feature gives you a full relational database with zero setup.

package/docs/examples/telegram.md

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

@@ -0,0 +1,86 @@
+---
+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`.