@soederpop/luca 0.0.2

package/docs/examples/nlp.md

@@ -0,0 +1,91 @@
+---
+title: "Natural Language Processing"
+tags: [nlp, parsing, text-analysis]
+lastTested: null
+lastTestPassed: null
+---
+
+# nlp
+
+Natural language processing utilities for parsing utterances into structured data, POS tagging, and entity extraction.
+
+## Overview
+
+The `nlp` feature is an on-demand feature that combines two complementary NLP libraries: **compromise** for verb normalization and quick structural parsing, and **wink-nlp** for high-accuracy part-of-speech tagging and named entity recognition. Use it when you need to extract intent from voice commands, classify sentence structure, or identify entities in text.
+
+## Enabling the Feature
+
+The nlp feature is on-demand, so we enable it explicitly.
+
+```ts
+const nlp = container.feature('nlp', { enable: true })
+console.log('NLP feature enabled:', nlp.state.enabled)
+```
+
+## Parsing Voice Commands
+
+The `parse()` method uses compromise to extract structured command data: an intent (normalized verb), a target noun, an optional prepositional subject, and any modifiers.
+
+```ts
+const cmd1 = nlp.parse("open the terminal")
+console.log('Command:', JSON.stringify(cmd1, null, 2))
+```
+
+Prepositional phrases with "of" are extracted as the subject.
+
+```ts
+const cmd2 = nlp.parse("draw a diagram of the auth flow")
+console.log('Command with subject:', JSON.stringify(cmd2, null, 2))
+```
+
+Notice how `intent` is the normalized verb form ("draw"), `target` is the direct object ("diagram"), and `subject` captures the prepositional phrase ("auth flow").
+
+## POS Tagging and Entity Recognition
+
+The `analyze()` method uses wink-nlp for high-accuracy part-of-speech tagging and named entity recognition.
+
+```ts
+const analysis = nlp.analyze("meet john at 3pm about the deployment")
+console.log('Tokens:')
+for (const tok of analysis.tokens) {
+  console.log(`  ${tok.value.padEnd(15)} ${tok.pos}`)
+}
+console.log('Entities:', JSON.stringify(analysis.entities))
+```
+
+Each token is tagged with its part of speech (VERB, NOUN, ADP, DET, etc.) and named entities like times and proper nouns are extracted separately.
+
+## Full Understanding
+
+The `understand()` method combines both `parse()` and `analyze()` into a single result, giving you structured command data alongside detailed POS tags and entities.
+
+```ts
+const full = nlp.understand("send an email to sarah about the quarterly report")
+console.log('Intent:', full.intent)
+console.log('Target:', full.target)
+console.log('Modifiers:', full.modifiers)
+console.log('Token count:', full.tokens.length)
+console.log('Entities:', JSON.stringify(full.entities))
+```
+
+This is the most complete method when you need both the high-level command structure and the detailed linguistic analysis in one call.
+
+## Comparing Multiple Commands
+
+Parse is fast and lightweight, making it suitable for batch processing of voice commands.
+
+```ts
+const commands = [
+  "deploy the app to production",
+  "restart the database server",
+  "show logs for the api gateway",
+]
+for (const raw of commands) {
+  const parsed = nlp.parse(raw)
+  console.log(`"${raw}" => intent: ${parsed.intent}, target: ${parsed.target}`)
+}
+```
+
+## Summary
+
+This demo covered the three main methods of the `nlp` feature: `parse()` for quick structural extraction from voice commands, `analyze()` for detailed POS tagging and entity recognition, and `understand()` for a combined view of both. The feature is well suited for building voice command interpreters, chatbot intent classifiers, and text analysis pipelines.

package/docs/examples/opener.md

@@ -0,0 +1,78 @@
+---
+title: "Opener"
+tags: [opener, files, urls, apps, editor]
+lastTested: null
+lastTestPassed: null
+---
+
+# opener
+
+Opens files, URLs, desktop applications, and code editors from scripts. HTTP/HTTPS URLs open in Chrome, files open with the system default handler, and VS Code / Cursor can be targeted directly.
+
+## Overview
+
+The `opener` feature provides a simple interface for opening things on the host system. It delegates to platform-appropriate commands (`open` on macOS, `start` on Windows, direct invocation on Linux). Because every method triggers a side effect (launching an application or browser), all operational examples use skip blocks.
+
+## Enabling the Feature
+
+```ts
+const opener = container.feature('opener', { enable: true })
+console.log('Opener enabled:', opener.state.get('enabled'))
+```
+
+## Exploring the API
+
+```ts
+const docs = container.features.describe('opener')
+console.log(docs)
+```
+
+## Opening a URL
+
+Open a URL in Google Chrome (the default browser for HTTP/HTTPS targets).
+
+```ts skip
+await opener.open('https://github.com/soederpop/luca')
+console.log('URL opened in Chrome')
+```
+
+Non-HTTP paths are opened with the platform default handler. For example, opening a `.png` file would launch Preview on macOS.
+
+```ts skip
+await opener.open('/Users/jon/screenshots/diagram.png')
+```
+
+## Opening a Desktop App
+
+Launch any desktop application by name.
+
+```ts skip
+await opener.app('Slack')
+console.log('Slack launched')
+```
+
+```ts skip
+await opener.app('Finder')
+```
+
+On macOS this uses `open -a`. The application name should match what appears in `/Applications`.
+
+## Opening in VS Code or Cursor
+
+Open a file or folder directly in VS Code or Cursor.
+
+```ts skip
+await opener.code('/Users/jon/projects/my-app')
+console.log('VS Code opened')
+```
+
+```ts skip
+await opener.cursor('/Users/jon/projects/my-app/src/index.ts')
+console.log('Cursor opened')
+```
+
+Both methods fall back to `open -a` on macOS if the CLI command is not found in PATH.
+
+## Summary
+
+The `opener` feature provides `open`, `app`, `code`, and `cursor` methods for launching URLs, files, desktop applications, and code editors from Luca scripts. All operations produce side effects on the host system.

package/docs/examples/os.md

@@ -0,0 +1,72 @@
+---
+title: "os"
+tags: [os, system, platform, core]
+lastTested: null
+lastTestPassed: null
+---
+
+# os
+
+Operating system information including platform, architecture, CPU, and network details.
+
+## Overview
+
+The `os` feature is a core feature, auto-enabled on every container. You can access it directly as a global or via `container.feature('os')`. It exposes system metadata through simple getters -- no method calls needed. Use it to detect the runtime environment, adapt behavior per platform, or gather machine info for diagnostics.
+
+## Platform and Architecture
+
+The `platform` and `arch` getters tell you what operating system and CPU architecture the code is running on.
+
+```ts
+console.log('Platform:', os.platform)
+console.log('Architecture:', os.arch)
+```
+
+Platform returns values like `darwin`, `linux`, or `win32`. Architecture returns values like `arm64` or `x64`.
+
+## CPU Information
+
+The `cpuCount` getter reports the number of logical CPU cores available.
+
+```ts
+console.log('CPU cores:', os.cpuCount)
+```
+
+Use this to size worker pools or decide how many parallel tasks to run.
+
+## System Paths
+
+The `tmpdir` and `homedir` getters return commonly needed system directories.
+
+```ts
+console.log('Temp directory:', os.tmpdir)
+console.log('Home directory:', os.homedir)
+```
+
+These are the OS defaults -- `tmpdir` for throwaway files and `homedir` for the current user's home.
+
+## Hostname
+
+The `hostname` getter returns the machine's network hostname.
+
+```ts
+console.log('Hostname:', os.hostname)
+```
+
+This can be useful for logging, multi-machine coordination, or display purposes.
+
+## Network Interfaces
+
+The `macAddresses` getter returns MAC addresses for non-internal IPv4 network interfaces.
+
+```ts
+const macs = os.macAddresses
+console.log('MAC addresses:', macs.length, 'found')
+macs.slice(0, 3).forEach(mac => console.log(' ', mac))
+```
+
+MAC addresses are useful for machine fingerprinting or license management.
+
+## Summary
+
+This demo covered querying the platform and architecture, checking CPU core count, retrieving system directory paths, reading the hostname, and listing network MAC addresses. The `os` feature gives scripts everything they need to adapt to and report on the runtime environment.

package/docs/examples/package-finder.md

@@ -0,0 +1,89 @@
+---
+title: "Package Finder"
+tags: [packageFinder, packages, dependencies, npm]
+lastTested: null
+lastTestPassed: null
+---
+
+# packageFinder
+
+Scans your workspace's node_modules and builds a queryable index of every installed package. Find duplicates, inspect versions, and map dependency relationships.
+
+## Overview
+
+The `packageFinder` feature is on-demand. After enabling and starting it, it recursively walks all node_modules directories, reads every package.json, and indexes the results. Use it for dependency auditing, duplicate detection, or understanding what is actually installed in your project.
+
+## Starting the Finder
+
+Enable the feature and run the initial scan.
+
+```ts
+const finder = container.feature('packageFinder')
+await finder.start()
+console.log('Scan complete:', finder.isStarted)
+console.log('Unique packages:', finder.packageNames.length)
+console.log('Total manifests:', finder.manifests.length)
+```
+
+The difference between unique package names and total manifests reveals how many packages exist in multiple copies (different versions in different locations).
+
+## Listing Packages
+
+Browse the discovered package names.
+
+```ts
+const names = finder.packageNames
+console.log('First 10 packages:')
+names.slice(0, 10).forEach(n => console.log(' ', n))
+```
+
+Package names include both scoped and unscoped packages from every node_modules tree in the workspace.
+
+## Finding a Package by Name
+
+Look up a specific package to see its version and location.
+
+```ts
+const zod = finder.findByName('zod')
+if (zod) {
+  console.log('Found:', zod.name)
+  console.log('Version:', zod.version)
+  console.log('Description:', zod.description)
+}
+```
+
+If multiple versions exist, `findByName` returns the first match. Use `filter()` to find all instances.
+
+## Scoped Packages
+
+The finder tracks which npm scopes are present in your dependencies.
+
+```ts
+const scopes = finder.scopes
+console.log('Scopes found:', scopes.length)
+scopes.slice(0, 8).forEach(s => {
+  const count = finder.packageNames.filter(n => n.startsWith(s)).length
+  console.log(`  ${s}: ${count} packages`)
+})
+```
+
+This is useful for auditing which organizations and ecosystems your project depends on.
+
+## Detecting Duplicates
+
+Packages that appear in multiple locations (often at different versions) show up in the duplicates list.
+
+```ts
+const dupes = finder.duplicates
+console.log('Duplicate packages:', dupes.length)
+dupes.slice(0, 5).forEach(name => {
+  const count = finder.counts[name]
+  console.log(`  ${name}: ${count} copies`)
+})
+```
+
+Duplicates increase install size and can cause subtle bugs when multiple versions of the same library coexist.
+
+## Summary
+
+This demo covered scanning the workspace for packages, listing and looking up packages, inspecting scopes, and detecting duplicates. The `packageFinder` feature gives you a complete inventory of your installed dependencies for auditing and analysis.

package/docs/examples/port-exposer.md

@@ -0,0 +1,89 @@
+---
+title: "Port Exposer"
+tags: [portExposer, ngrok, networking, tunnel]
+lastTested: null
+lastTestPassed: null
+---
+
+# portExposer
+
+Exposes local HTTP services via ngrok with SSL-enabled public URLs. Useful for development, testing webhooks, and sharing local services with external consumers.
+
+## Overview
+
+The `portExposer` feature creates an ngrok tunnel from a local port to a public HTTPS URL. It supports custom subdomains, regional endpoints, basic auth, and OAuth (features that require a paid ngrok plan). Requires ngrok to be installed or available as a dependency, and optionally an auth token for premium features.
+
+## Enabling the Feature
+
+```ts
+const exposer = container.feature('portExposer', {
+  port: 3000,
+  enable: true
+})
+console.log('Port Exposer enabled:', exposer.state.get('enabled'))
+```
+
+## Exploring the API
+
+```ts
+const docs = container.features.describe('portExposer')
+console.log(docs)
+```
+
+## Checking Connection State
+
+```ts
+const exposer = container.feature('portExposer', { port: 3000 })
+console.log('Connected:', exposer.isConnected())
+```
+
+## Exposing a Port
+
+Create a tunnel and get the public URL.
+
+```ts skip
+const url = await exposer.expose()
+console.log('Public URL:', url)
+console.log('Connected:', exposer.isConnected())
+```
+
+The returned URL is an HTTPS endpoint that forwards traffic to `localhost:3000`. The tunnel remains active until `close()` is called or the process exits.
+
+## Getting Connection Info
+
+Retrieve a snapshot of the current tunnel state.
+
+```ts skip
+await exposer.expose()
+const info = exposer.getConnectionInfo()
+console.log('Public URL:', info.publicUrl)
+console.log('Local port:', info.localPort)
+console.log('Connected at:', info.connectedAt)
+```
+
+## Reconnecting with New Options
+
+Close the existing tunnel and re-expose with different settings.
+
+```ts skip
+const url1 = await exposer.expose()
+console.log('First URL:', url1)
+
+const url2 = await exposer.reconnect({ port: 8080 })
+console.log('New URL (port 8080):', url2)
+```
+
+The `reconnect` method calls `close()` internally, merges the new options, then calls `expose()` again.
+
+## Closing the Tunnel
+
+```ts skip
+await exposer.close()
+console.log('Tunnel closed:', !exposer.isConnected())
+```
+
+Calling `close()` when no tunnel is active is a safe no-op. The `disable()` method also closes the tunnel before disabling the feature.
+
+## Summary
+
+The `portExposer` feature wraps ngrok to expose local ports as public HTTPS endpoints. It supports connection lifecycle management, reconnection with new options, and event-driven notifications for tunnel state changes. Requires ngrok to be installed.

package/docs/examples/postgres.md

@@ -0,0 +1,91 @@
+---
+title: "PostgreSQL"
+tags: [postgres, database, sql, storage]
+lastTested: null
+lastTestPassed: null
+---
+
+# postgres
+
+PostgreSQL feature for safe SQL execution through Bun's native SQL client. Supports parameterized queries, tagged-template literals, and write operations.
+
+## Overview
+
+Use the `postgres` feature when you need to interact with a PostgreSQL database. It provides three query interfaces: parameterized `query()` for reads, `execute()` for writes, and the `sql` tagged template for injection-safe inline SQL.
+
+Requires a running PostgreSQL instance and a connection URL.
+
+## Enabling the Feature
+
+```ts
+const pg = container.feature('postgres', {
+  url: 'postgres://user:pass@localhost:5432/mydb'
+})
+console.log('Postgres feature created')
+console.log('Connection URL configured:', !!pg.state.url)
+```
+
+Pass your connection URL via the `url` option. In production, read from an environment variable.
+
+## API Documentation
+
+```ts
+const info = await container.features.describe('postgres')
+console.log(info)
+```
+
+## Parameterized Queries
+
+Use `query()` for SELECT statements with `$N` placeholders to prevent SQL injection.
+
+```ts skip
+const users = await pg.query(
+  'SELECT id, email FROM users WHERE active = $1 LIMIT $2',
+  [true, 10]
+)
+console.log(`Found ${users.length} active users`)
+users.forEach(u => console.log(`  ${u.id}: ${u.email}`))
+```
+
+With a running database, this would return an array of row objects matching the query. The `query` event fires on each execution.
+
+## Tagged Template SQL
+
+The `sql` tagged template automatically converts interpolated values into bound parameters.
+
+```ts skip
+const email = 'hello@example.com'
+const rows = await pg.sql`
+  SELECT id, name FROM users WHERE email = ${email}
+`
+console.log('Found:', rows)
+```
+
+This is the most ergonomic way to write queries. Each interpolated value becomes a `$N` parameter automatically, preventing SQL injection without manual placeholder numbering.
+
+## Write Operations
+
+Use `execute()` for INSERT, UPDATE, and DELETE statements that return affected row counts.
+
+```ts skip
+const { rowCount } = await pg.execute(
+  'UPDATE users SET active = $1 WHERE last_login < $2',
+  [false, '2024-01-01']
+)
+console.log(`Deactivated ${rowCount} users`)
+```
+
+The `execute` event fires with the row count after each write operation.
+
+## Closing the Connection
+
+```ts skip
+await pg.close()
+console.log('Connection closed:', !pg.state.connected)
+```
+
+Always close the connection when done. The `closed` event fires after teardown.
+
+## Summary
+
+The `postgres` feature wraps Bun's native SQL client with three query methods: `query()` for parameterized reads, `execute()` for writes, and the `sql` tagged template for ergonomic injection-safe queries. Events fire for each operation. Key methods: `query()`, `execute()`, `sql`, `close()`.

package/docs/examples/proc.md

@@ -0,0 +1,81 @@
+---
+title: "proc"
+tags: [proc, process, shell, core]
+lastTested: null
+lastTestPassed: null
+---
+
+# proc
+
+Process execution utilities for running shell commands and capturing their output.
+
+## Overview
+
+The `proc` feature is a core feature, auto-enabled on every container. You can access it directly as a global or via `container.feature('proc')`. It provides synchronous and asynchronous methods for executing shell commands. Use `exec()` for quick synchronous calls and `execAndCapture()` when you need structured output with exit codes.
+
+## Simple Command Execution
+
+Use `exec()` to run a command synchronously and get its stdout as a string.
+
+```ts
+const result = proc.exec('echo hello from luca')
+console.log('Output:', result.trim())
+```
+
+The output is returned directly as a string, with no wrapper object.
+
+## Listing Files
+
+Commands that produce multi-line output work naturally. Each line comes through as part of the string.
+
+```ts
+const listing = proc.exec('ls src')
+const entries = listing.trim().split('\n')
+console.log('Entries in src/:', entries.length)
+entries.slice(0, 5).forEach(e => console.log(' ', e))
+```
+
+You can split and process the output like any other string.
+
+## Working Directory Option
+
+Pass a `cwd` option to run a command in a different directory without changing the container's working directory.
+
+```ts
+const rootFiles = proc.exec('ls -1', { cwd: '.' })
+console.log('Files in project root:')
+rootFiles.trim().split('\n').slice(0, 5).forEach(f => console.log(' ', f))
+```
+
+This is useful when you need to operate on files in a subdirectory or sibling project.
+
+## Getting System Info
+
+Shell commands work for gathering system information that might not be available through other features.
+
+```ts
+const date = proc.exec('date')
+console.log('Current date:', date.trim())
+
+const whoami = proc.exec('whoami')
+console.log('Current user:', whoami.trim())
+```
+
+Any command available on the system PATH can be called through `exec()`.
+
+## Async Execution with Capture
+
+Use `execAndCapture()` for async execution with structured output including exit code and stderr.
+
+```ts
+const result = await proc.execAndCapture('ls src')
+console.log('Exit code:', result.exitCode)
+console.log('Stdout lines:', result.stdout.trim().split('\n').length)
+console.log('Stderr:', result.stderr || '(empty)')
+```
+
+The returned object gives you `stdout`, `stderr`, `exitCode`, and `pid` for full control over the result.
+
+## Summary
+
+This demo covered synchronous command execution, processing multi-line output, running commands in different directories, gathering system info, and async execution with structured results. The `proc` feature is the escape hatch for anything the other features do not cover directly.

package/docs/examples/process-manager.md

@@ -0,0 +1,79 @@
+---
+title: "Process Manager"
+tags: [processManager, processes, spawn, lifecycle]
+lastTested: null
+lastTestPassed: null
+---
+
+# processManager
+
+Manage long-running child processes with tracking, events, and automatic cleanup.
+
+## Overview
+
+The `processManager` feature is an on-demand feature for spawning and supervising child processes. Unlike `proc.spawn` which blocks until a process exits, processManager returns a `SpawnHandler` immediately -- a handle object with its own state, events, and lifecycle methods. The feature tracks all spawned processes and can kill them all on parent exit. Use it when you need to orchestrate multiple background services, dev servers, or worker processes.
+
+## Enabling the Feature
+
+Enable the processManager with auto-cleanup so tracked processes are killed when the parent exits.
+
+```ts
+const pm = container.feature('processManager', { enable: true, autoCleanup: true })
+console.log('ProcessManager enabled:', pm.state.enabled)
+console.log('Total spawned so far:', pm.state.totalSpawned)
+```
+
+## Spawning a Process
+
+Spawn a short-lived process and capture its output. The `spawn` method returns a `SpawnHandler` immediately.
+
+```ts
+const handle = pm.spawn('echo', ['hello from process manager'], { tag: 'greeter' })
+console.log('Spawned process tag:', 'greeter')
+console.log('Handle has kill method:', typeof handle.kill === 'function')
+```
+
+The handle provides methods like `kill()` and events like `stdout`, `stderr`, `exited`, and `crashed`.
+
+## Listing Tracked Processes
+
+The processManager keeps track of every process it has spawned, whether running or finished.
+
+```ts
+const all = pm.list()
+console.log('Tracked processes:', all.length)
+console.log('Total spawned:', pm.state.totalSpawned)
+```
+
+You can also look up a specific process by its tag.
+
+```ts
+const found = pm.getByTag('greeter')
+console.log('Found by tag:', found ? 'yes' : 'no')
+```
+
+## Spawning and Killing
+
+You can spawn a longer process and then kill it. Here we spawn `sleep` and immediately terminate it.
+
+```ts
+const sleeper = pm.spawn('sleep', ['10'], { tag: 'sleeper' })
+console.log('Sleeper spawned')
+sleeper.kill()
+console.log('Sleeper killed')
+console.log('Total spawned now:', pm.state.totalSpawned)
+```
+
+## Cleaning Up
+
+The `killAll` method terminates every tracked process, and `stop` does a full teardown including removing exit handlers.
+
+```ts
+pm.killAll()
+const remaining = pm.list().filter(h => h.state?.status === 'running')
+console.log('Running after killAll:', remaining.length)
+```
+
+## Summary
+
+This demo covered the `processManager` feature: spawning processes that return handles immediately, tracking them by ID or tag, listing all tracked processes, and killing them individually or all at once. It is the right tool for orchestrating background services, dev servers, and any scenario where you need non-blocking process management with lifecycle events.