@soederpop/luca 0.0.2

package/docs/examples/grep.md

@@ -0,0 +1,85 @@
+---
+title: "grep"
+tags: [grep, search, core]
+lastTested: null
+lastTestPassed: null
+---
+
+# grep
+
+Search file contents for patterns, find imports, definitions, and TODO comments.
+
+## Overview
+
+The `grep` feature is a core feature, auto-enabled on every container. You can access it directly as a global or via `container.feature('grep')`. It wraps ripgrep with a structured API, providing methods for pattern search, import discovery, definition lookup, and TODO scanning. Results come back as arrays of match objects with file, line, and content info.
+
+## Searching for a Pattern
+
+Use `search()` to find occurrences of a pattern across files. Options let you filter by file type, limit results, and control case sensitivity.
+
+```ts
+const results = await grep.search({ pattern: 'container', include: '*.ts', exclude: 'node_modules', maxResults: 5 })
+console.log('Matches for "container" in .ts files (first 5):')
+results.forEach(r => {
+  console.log(`  ${r.file}:${r.line} ${r.content.trim().slice(0, 60)}`)
+})
+```
+
+Each match object contains `file`, `line`, and `content` fields.
+
+## Counting Matches
+
+Use `count()` to get just the number of matches without fetching all the details.
+
+```ts
+const total = await grep.count('container', { include: '*.ts', exclude: 'node_modules' })
+console.log('Total "container" occurrences in .ts files:', total)
+```
+
+This is much faster when you only need the total.
+
+## Finding Import Statements
+
+Use `imports()` to find all files that import a specific module or path.
+
+```ts
+const results = await grep.imports('path', { include: '*.ts', exclude: 'node_modules', maxResults: 5 })
+console.log('Files importing "path" (first 5):')
+results.forEach(r => {
+  console.log(`  ${r.file}:${r.line} ${r.content.trim().slice(0, 70)}`)
+})
+```
+
+This searches for both `import` and `require` patterns automatically.
+
+## Finding Definitions
+
+Use `definitions()` to locate where functions, classes, types, or variables are defined.
+
+```ts
+const defs = await grep.definitions('Feature', { include: '*.ts', exclude: 'node_modules', maxResults: 5 })
+console.log('Definitions matching "Feature" (first 5):')
+defs.forEach(d => {
+  console.log(`  ${d.file}:${d.line} ${d.content.trim().slice(0, 70)}`)
+})
+```
+
+This searches for `function`, `class`, `type`, `interface`, `const`, and `let` declarations.
+
+## Finding TODOs
+
+Use `todos()` to scan for TODO, FIXME, HACK, and XXX comments across the codebase.
+
+```ts
+const todos = await grep.todos({ include: '*.ts', exclude: 'node_modules', maxResults: 5 })
+console.log('TODOs found in .ts files (first 5):')
+todos.forEach(t => {
+  console.log(`  ${t.file}:${t.line} ${t.content.trim().slice(0, 70)}`)
+})
+```
+
+This is handy for tracking technical debt and outstanding work items.
+
+## Summary
+
+This demo covered pattern searching with structured results, counting matches efficiently, finding import statements, locating definitions by name, and scanning for TODO comments. The `grep` feature is the go-to tool for codebase analysis and discovery.

package/docs/examples/ink-blocks.md

@@ -0,0 +1,75 @@
+# Ink Blocks — Poor Man's MDX
+
+This example demonstrates rendering rich terminal UI inline in a markdown document using ink blocks.
+
+## Blocks
+
+```tsx
+const { Box, Text } = ink.components
+const React = ink.React
+
+function Greeting({ name, role }) {
+  return (
+    <Box borderStyle="round" padding={1}>
+      <Text color="green" bold>Hello {name}!</Text>
+      <Text dimColor> ({role})</Text>
+    </Box>
+  )
+}
+
+function StatusBar({ items }) {
+  return (
+    <Box flexDirection="row" gap={2}>
+      {items.map((item, i) =>
+        <Text key={i} color={item.ok ? 'green' : 'red'}>{item.label}</Text>
+      )}
+    </Box>
+  )
+}
+
+function DelayedMessage({ message, delay, done }) {
+  const [visible, setVisible] = React.useState(false)
+
+  React.useEffect(() => {
+    const timer = setTimeout(() => {
+      setVisible(true)
+      done()
+    }, delay || 500)
+    return () => clearTimeout(timer)
+  }, [])
+
+  return (
+    <Box>
+      <Text dimColor={!visible} color={visible ? 'cyan' : undefined}>
+        {visible ? message : 'Loading...'}
+      </Text>
+    </Box>
+  )
+}
+```
+
+## Report
+
+Let's greet the admin:
+
+```ts
+await render('Greeting', { name: 'Jon', role: 'admin' })
+```
+
+Now let's check the system status:
+
+```ts
+await render('StatusBar', { items: [
+  { label: 'API', ok: true },
+  { label: 'DB', ok: false },
+  { label: 'Cache', ok: true },
+]})
+```
+
+Now an async block that waits for a timer before rendering:
+
+```ts
+await renderAsync('DelayedMessage', { message: 'Data loaded successfully!', delay: 1000 })
+```
+
+All done. Blocks rendered inline with the document flow.

package/docs/examples/ink-renderer.md

@@ -0,0 +1,41 @@
+# Feature Registry
+
+## Blocks
+
+```tsx
+const { Box, Text } = ink.components
+const React = ink.React
+
+function Table({ rows, columns }) {
+  const colWidth = Math.floor(70 / columns)
+
+  const chunked = []
+  for (let i = 0; i < rows.length; i += columns) {
+    chunked.push(rows.slice(i, i + columns))
+  }
+
+  return (
+    <Box flexDirection="column">
+      <Box borderStyle="single" paddingX={1}>
+        <Text bold color="cyan">Available Features</Text>
+      </Box>
+      {chunked.map((row, ri) => (
+        <Box key={ri} flexDirection="row">
+          {row.map((item, ci) => (
+            <Box key={ci} width={colWidth} paddingX={1}>
+              <Text color="green">{item}</Text>
+            </Box>
+          ))}
+        </Box>
+      ))}
+    </Box>
+  )
+}
+```
+
+## Features
+
+```ts
+const features = container.features.available
+await render('Table', { rows: features, columns: 3 })
+```

package/docs/examples/ink.md

@@ -0,0 +1,103 @@
+---
+title: "Ink"
+tags: [ink, react, terminal, ui, components]
+lastTested: null
+lastTestPassed: null
+---
+
+# ink
+
+React-powered terminal UI via the Ink library. Build rich, interactive command-line interfaces using React components that render directly in the terminal.
+
+## Overview
+
+The `ink` feature exposes the Ink library (React for CLIs) through the container. It provides access to React itself, all Ink components (Box, Text, Spacer, etc.), all Ink hooks (useInput, useApp, useFocus, etc.), and a render/unmount lifecycle. Because Ink renders an interactive React tree in the terminal, it cannot be fully demonstrated in a non-interactive markdown runner. Runnable blocks cover setup and introspection; actual rendering is shown in skip blocks.
+
+## Enabling the Feature
+
+```ts
+const ink = container.feature('ink', { enable: true })
+console.log('Ink enabled:', ink.state.get('enabled'))
+console.log('Currently mounted:', ink.isMounted)
+```
+
+## Exploring the API
+
+```ts
+const docs = container.features.describe('ink')
+console.log(docs)
+```
+
+## Loading Modules
+
+The `loadModules` method pre-loads React and Ink so that the sync getters work immediately.
+
+```ts
+const ink = container.feature('ink', { enable: true })
+await ink.loadModules()
+const componentNames = Object.keys(ink.components)
+const hookNames = Object.keys(ink.hooks)
+console.log('Components:', componentNames.join(', '))
+console.log('Hooks:', hookNames.join(', '))
+console.log('React available:', typeof ink.React.createElement)
+```
+
+## Rendering a Component
+
+Mount a React element to the terminal using `React.createElement`.
+
+```ts skip
+const { Box, Text } = ink.components
+const { React } = ink
+
+ink.render(
+  React.createElement(Box, { flexDirection: 'column' },
+    React.createElement(Text, { color: 'green' }, 'Hello from Ink'),
+    React.createElement(Text, { dimColor: true }, 'Powered by Luca')
+  )
+)
+await ink.waitUntilExit()
+```
+
+The `render` method mounts the React tree and starts the Ink render loop. `waitUntilExit` returns a promise that resolves when the app exits (via `useApp().exit()` or `unmount()`).
+
+## Using Hooks
+
+Ink hooks like `useInput` and `useFocus` work inside functional components passed to `render`.
+
+```ts skip
+const { Text } = ink.components
+const { React } = ink
+const { useInput, useApp } = ink.hooks
+
+function App() {
+  const { exit } = useApp()
+  useInput((input, key) => {
+    if (input === 'q') exit()
+  })
+  return React.createElement(Text, null, 'Press q to quit')
+}
+
+ink.render(React.createElement(App))
+await ink.waitUntilExit()
+console.log('App exited')
+```
+
+## Unmounting and Cleanup
+
+Tear down the rendered app and clear terminal output.
+
+```ts skip
+ink.render(
+  React.createElement(ink.components.Text, null, 'Temporary UI')
+)
+ink.clear()
+ink.unmount()
+console.log('Mounted after unmount:', ink.isMounted)
+```
+
+The `clear` method erases all Ink-rendered content from the terminal. The `unmount` method tears down the React tree. Both are safe to call when no app is mounted.
+
+## Summary
+
+The `ink` feature brings React-based terminal UIs to Luca scripts. It provides the full Ink component and hook library, a render lifecycle with mount/unmount/rerender, and access to the React module itself. Best suited for interactive CLI tools and dashboards.

package/docs/examples/ipc-socket.md

@@ -0,0 +1,103 @@
+---
+title: "IPC Socket"
+tags: [ipcSocket, ipc, unix-socket, messaging]
+lastTested: null
+lastTestPassed: null
+---
+
+# ipcSocket
+
+Inter-process communication via Unix domain sockets. Supports both server and client modes with JSON message serialization, broadcast messaging, and event-driven message handling.
+
+## Overview
+
+The `ipcSocket` feature enables processes to communicate through file-system-based Unix domain sockets. A server listens on a socket path and accepts multiple client connections. Messages are automatically JSON-encoded with unique IDs. Both server and client emit `message` events for incoming data. Because IPC requires coordinating two processes (server and client), all socket operation examples use skip blocks.
+
+## Enabling the Feature
+
+```ts
+const ipc = container.feature('ipcSocket', { enable: true })
+console.log('IPC Socket enabled:', ipc.state.get('enabled'))
+console.log('Current mode:', ipc.state.get('mode'))
+```
+
+## Exploring the API
+
+```ts
+const docs = container.features.describe('ipcSocket')
+console.log(docs)
+```
+
+## Checking Mode
+
+```ts
+const ipc = container.feature('ipcSocket')
+console.log('Is server:', ipc.isServer)
+console.log('Is client:', ipc.isClient)
+```
+
+## Starting a Server
+
+Listen on a Unix domain socket and handle incoming connections.
+
+```ts skip
+const server = await ipc.listen('/tmp/myapp.sock', true)
+console.log('Server listening')
+
+ipc.on('connection', (socket) => {
+  console.log('Client connected')
+})
+
+ipc.on('message', (data) => {
+  console.log('Received:', data)
+  ipc.broadcast({ reply: 'ACK', original: data })
+})
+```
+
+The second argument `true` removes any stale socket file before binding. Without it, the call throws if the socket file already exists.
+
+## Connecting a Client
+
+Connect to an existing server and exchange messages.
+
+```ts skip
+const socket = await ipc.connect('/tmp/myapp.sock')
+console.log('Connected to server')
+
+ipc.on('message', (data) => {
+  console.log('Server says:', data)
+})
+
+ipc.send({ type: 'hello', clientId: 'worker-1' })
+```
+
+Messages sent via `ipc.send()` are automatically wrapped with a unique ID for tracking. The server receives the original data in the `message` event.
+
+## Broadcasting Messages
+
+Send a message to all connected clients from the server.
+
+```ts skip
+ipc.broadcast({
+  type: 'notification',
+  message: 'Deployment starting',
+  timestamp: Date.now()
+})
+```
+
+Each connected client receives the broadcast as a `message` event. Messages are JSON-encoded with a UUID for correlation.
+
+## Stopping the Server
+
+Gracefully shut down the server and disconnect all clients.
+
+```ts skip
+await ipc.stopServer()
+console.log('Server stopped')
+```
+
+The `stopServer` method closes the listener, destroys all active client connections, and resets internal state.
+
+## Summary
+
+The `ipcSocket` feature provides Unix domain socket IPC with JSON message serialization, multi-client support, broadcast messaging, and automatic socket cleanup. It works in either server or client mode within a single feature instance.

package/docs/examples/json-tree.md

@@ -0,0 +1,91 @@
+---
+title: "JSON Tree"
+tags: [jsonTree, json, files, data-loading]
+lastTested: null
+lastTestPassed: null
+---
+
+# jsonTree
+
+Load JSON files from directory structures into a nested object tree.
+
+## Overview
+
+The `jsonTree` feature is an on-demand feature that recursively scans a directory for `.json` files and builds a hierarchical JavaScript object from them. File paths are converted to camelCased property paths, so `config/database/production.json` becomes `tree.config.database.production`. This is useful when your project stores structured data across many JSON files and you want to access it all through a single unified object.
+
+## Feature Documentation
+
+Let us inspect the feature's built-in documentation.
+
+```ts
+const desc = container.features.describe('jsonTree')
+console.log(desc)
+```
+
+The key method is `loadTree(basePath, key?)` which scans a directory and populates the `tree` getter.
+
+## Enabling the Feature
+
+Enable jsonTree and check its initial state.
+
+```ts
+const jsonTree = container.feature('jsonTree', { enable: true })
+console.log('jsonTree enabled:', jsonTree.state.enabled)
+console.log('Initial tree:', JSON.stringify(jsonTree.tree))
+```
+
+The tree starts empty until you load directories into it.
+
+## How loadTree Works
+
+The `loadTree(basePath, key?)` method recursively scans a directory for `.json` files, parses each one, and builds a nested object from the file paths. The optional `key` parameter controls where in the tree the data is stored.
+
+```ts
+console.log('loadTree processing steps:')
+console.log('  1. Scans basePath recursively for *.json files')
+console.log('  2. Reads and parses each file with JSON.parse()')
+console.log('  3. Converts file paths to camelCased property paths')
+console.log('  4. Stores the result under the given key in feature state')
+console.log('')
+console.log('Example call: await jsonTree.loadTree("config", "appConfig")')
+console.log('  config/db/prod.json => jsonTree.tree.appConfig.db.prod')
+```
+
+After calling `loadTree`, the data is accessible through the `tree` getter, which returns all loaded trees minus internal state properties.
+
+## Inspecting the Tree Getter
+
+The `tree` getter provides clean access to loaded data. Before any data is loaded, it returns an empty object.
+
+```ts
+console.log('Tree before loading:', JSON.stringify(jsonTree.tree))
+console.log('Tree type:', typeof jsonTree.tree)
+console.log('Tree is clean (no "enabled" key):', !('enabled' in jsonTree.tree))
+```
+
+The getter filters out the internal `enabled` state property so you only see your loaded JSON data.
+
+## Path Transformation Rules
+
+The feature applies consistent transformations when building the tree:
+
+- Directory names become nested object properties
+- File names (without `.json`) become leaf properties
+- All names are converted to camelCase
+- Hyphens and dots in names are handled by the camelCase conversion
+
+```ts
+// Conceptual example of path mapping:
+const mappings = {
+  'config/database/production.json': 'tree.config.database.production',
+  'data/user-profiles.json': 'tree.data.userProfiles',
+  'settings/app-config.json': 'tree.settings.appConfig',
+}
+for (const [file, path] of Object.entries(mappings)) {
+  console.log(`${file} => ${path}`)
+}
+```
+
+## Summary
+
+This demo covered the `jsonTree` feature, which scans directories for JSON files and builds a nested object tree from them. File paths are transformed into camelCased property paths, making it easy to access deeply nested configuration or data files through a single unified interface.

package/docs/examples/launcher-app-command-listener.md

@@ -0,0 +1,120 @@
+---
+title: "Launcher App Command Listener"
+tags: [launcherAppCommandListener, ipc, macos, voice, commands]
+lastTested: null
+lastTestPassed: null
+---
+
+# launcherAppCommandListener
+
+IPC transport for receiving commands from the LucaVoiceLauncher macOS app. Listens on a Unix domain socket using NDJSON and wraps incoming commands in a `CommandHandle` for structured acknowledgement, progress, and completion.
+
+## Overview
+
+Use the `launcherAppCommandListener` feature when you need to receive and process commands from the native macOS launcher app (voice commands, hotkeys, or text input). It provides the server side of the IPC protocol: listen for the app to connect, receive command events, and respond with acknowledgements, progress updates, and results.
+
+Requires the LucaVoiceLauncher native macOS app to be running.
+
+## Enabling the Feature
+
+```ts
+const listener = container.feature('launcherAppCommandListener', {
+  autoListen: false
+})
+console.log('Command Listener feature created')
+console.log('Listening:', listener.isListening)
+console.log('Client connected:', listener.isClientConnected)
+```
+
+## API Documentation
+
+```ts
+const info = await container.features.describe('launcherAppCommandListener')
+console.log(info)
+```
+
+## Listening for Commands
+
+Start the IPC server and handle incoming commands with the `CommandHandle` API.
+
+```ts skip
+const listener = container.feature('launcherAppCommandListener', {
+  autoListen: true
+})
+
+listener.on('command', async (cmd) => {
+  console.log('Received command:', cmd.text)
+
+  cmd.ack('Working on it!')
+  // ... process the command ...
+  cmd.progress(0.5, 'Halfway there')
+  // ... finish processing ...
+  cmd.finish({ result: { action: 'completed' }, speech: 'All done!' })
+})
+```
+
+Each incoming command is wrapped in a `CommandHandle` that provides `ack()`, `progress()`, `finish()`, and `fail()` methods. The native app displays acknowledgements and speaks the `speech` text.
+
+## Command Handle Lifecycle
+
+The `CommandHandle` follows a structured lifecycle: acknowledge, optionally report progress, then finish or fail.
+
+```ts skip
+listener.on('command', async (cmd) => {
+  // Silent acknowledge
+  cmd.ack()
+
+  try {
+    // Report progress (0-1 scale)
+    cmd.progress(0.25, 'Starting...')
+    cmd.progress(0.75, 'Almost done...')
+
+    // Finish with result and optional speech
+    cmd.finish({
+      result: { data: 'some result' },
+      speech: 'Task completed successfully'
+    })
+  } catch (err) {
+    // Report failure with optional speech
+    cmd.fail({
+      error: err.message,
+      speech: 'Sorry, that failed.'
+    })
+  }
+})
+```
+
+The native app uses the `speech` field for text-to-speech feedback to the user.
+
+## Connection Events
+
+Monitor the IPC connection state.
+
+```ts skip
+listener.on('listening', () => {
+  console.log('IPC server listening on:', listener.state.socketPath)
+})
+listener.on('clientConnected', () => {
+  console.log('Launcher app connected')
+})
+listener.on('clientDisconnected', () => {
+  console.log('Launcher app disconnected')
+})
+```
+
+The `clientConnected` and `clientDisconnected` events fire as the native app connects and disconnects from the socket.
+
+## Sending Messages
+
+Send arbitrary NDJSON messages back to the connected app.
+
+```ts skip
+listener.send({ status: 'ready', message: 'Luca is online' })
+listener.send({ notification: 'Task queue empty' })
+```
+
+Use `send()` for custom protocol messages beyond the standard command lifecycle.
+
+## Summary
+
+The `launcherAppCommandListener` feature provides the IPC server for the LucaVoiceLauncher app. It receives voice, hotkey, and text commands, wrapping each in a `CommandHandle` with structured lifecycle methods (ack, progress, finish, fail). Key methods: `listen()`, `stop()`, `send()`. Key events: `command`, `clientConnected`, `clientDisconnected`.

package/docs/examples/networking.md

@@ -0,0 +1,58 @@
+---
+title: "networking"
+tags: [networking, ports, network, core]
+lastTested: null
+lastTestPassed: null
+---
+
+# networking
+
+Port discovery and availability checking for network services.
+
+## Overview
+
+The `networking` feature is a core feature, auto-enabled on every container. You can access it directly as a global or via `container.feature('networking')`. It provides async methods for finding available ports and checking whether a given port is already in use. Use it before starting servers to avoid port conflicts.
+
+## Finding an Open Port
+
+Use `findOpenPort()` to get the next available port starting from a given number. If the requested port is taken, it searches upward.
+
+```ts
+const port = await networking.findOpenPort(3000)
+console.log('Available port starting from 3000:', port)
+```
+
+If port 3000 is free, you get 3000 back. If not, you get the next one that is.
+
+## Checking Port Availability
+
+Use `isPortOpen()` to check whether a specific port is available without claiming it.
+
+```ts
+const is3000Open = await networking.isPortOpen(3000)
+console.log('Port 3000 available:', is3000Open)
+
+const is80Open = await networking.isPortOpen(80)
+console.log('Port 80 available:', is80Open)
+```
+
+Returns `true` if the port is free, `false` if something is already listening on it.
+
+## Finding Multiple Ports
+
+You can call `findOpenPort()` with different starting points to allocate several non-conflicting ports for a multi-service setup.
+
+```ts
+const apiPort = await networking.findOpenPort(8080)
+const wsPort = await networking.findOpenPort(8090)
+const devPort = await networking.findOpenPort(5173)
+console.log('API server port:', apiPort)
+console.log('WebSocket port:', wsPort)
+console.log('Dev server port:', devPort)
+```
+
+Each call independently finds the next available port from its starting point.
+
+## Summary
+
+This demo covered finding available ports from a starting number, checking individual port availability, and allocating multiple ports for multi-service architectures. The `networking` feature eliminates port conflicts before they happen.