@soederpop/luca 0.0.2

package/docs/apis/features/node/ink.md

@@ -0,0 +1,334 @@
+# Ink (features.ink)
+
+Ink Feature — React-powered Terminal UI via Ink Exposes the Ink library (React for CLIs) through the container so any feature, script, or application can build rich terminal user interfaces using React components rendered directly in the terminal. This feature is intentionally a thin pass-through. It re-exports all of Ink's components, hooks, and the render function, plus a few convenience methods for mounting / unmounting apps. The actual UI composition is left entirely to the consumer — the feature just makes Ink available. **What you get:** - `ink.render(element)` — mount a React element to the terminal - `ink.components` — { Box, Text, Static, Transform, Newline, Spacer } - `ink.hooks` — { useInput, useApp, useStdin, useStdout, useStderr, useFocus, useFocusManager } - `ink.React` — the React module itself (createElement, useState, etc.) - `ink.unmount()` — tear down the currently mounted app - `ink.waitUntilExit()` — await the mounted app's exit **Quick start:** ```tsx const ink = container.feature('ink', { enable: true }) 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() ``` Or if you're in a .tsx file: ```tsx import React from 'react' const ink = container.feature('ink', { enable: true }) const { Box, Text } = ink.components ink.render( <Box flexDirection="column"> <Text color="green">hello from ink</Text> <Text dimColor>powered by luca</Text> </Box> ) ```
+
+## Usage
+
+```ts
+container.feature('ink', {
+  // Maximum frames per second for render updates
+  maxFps,
+  // Patch console methods to avoid mixing with Ink output
+  patchConsole,
+  // Enable incremental rendering mode
+  incrementalRendering,
+  // Enable React concurrent rendering mode
+  concurrent,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `maxFps` | `number` | Maximum frames per second for render updates |
+| `patchConsole` | `boolean` | Patch console methods to avoid mixing with Ink output |
+| `incrementalRendering` | `boolean` | Enable incremental rendering mode |
+| `concurrent` | `boolean` | Enable React concurrent rendering mode |
+
+## Methods
+
+### loadModules
+
+Pre-load ink + react modules so the sync getters work. Called automatically by render(), but you can call it early.
+
+**Returns:** `void`
+
+```ts
+const ink = container.feature('ink', { enable: true })
+await ink.loadModules()
+// Now sync getters like ink.React, ink.components, ink.hooks work
+const { Box, Text } = ink.components
+```
+
+
+
+### render
+
+Mount a React element to the terminal. Wraps `ink.render()` — automatically loads modules if needed, tracks the instance for unmount / waitUntilExit, and updates state.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `node` | `any` | ✓ | A React element (JSX or React.createElement) |
+| `options` | `Record<string, any>` |  | Ink render options (stdout, stdin, debug, etc.) |
+
+**Returns:** `void`
+
+
+
+### rerender
+
+Re-render the currently mounted app with a new root element.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `node` | `any` | ✓ | Parameter node |
+
+**Returns:** `void`
+
+```ts
+const ink = container.feature('ink', { enable: true })
+const { React } = await ink.loadModules()
+const { Text } = ink.components
+
+await ink.render(React.createElement(Text, null, 'Hello'))
+ink.rerender(React.createElement(Text, null, 'Updated!'))
+```
+
+
+
+### unmount
+
+Unmount the currently mounted Ink app. Tears down the React tree rendered in the terminal and resets state. Safe to call when no app is mounted (no-op).
+
+**Returns:** `void`
+
+```ts
+const ink = container.feature('ink', { enable: true })
+await ink.render(myElement)
+// ... later
+ink.unmount()
+console.log(ink.isMounted) // false
+```
+
+
+
+### waitUntilExit
+
+Returns a promise that resolves when the mounted app exits. Useful for keeping a script alive while the terminal UI is active.
+
+**Returns:** `Promise<void>`
+
+```ts
+const ink = container.feature('ink', { enable: true })
+await ink.render(myElement)
+await ink.waitUntilExit()
+console.log('App exited')
+```
+
+
+
+### clear
+
+Clear the terminal output of the mounted app. Erases all Ink-rendered content from the terminal. Safe to call when no app is mounted (no-op).
+
+**Returns:** `void`
+
+```ts
+const ink = container.feature('ink', { enable: true })
+await ink.render(myElement)
+// ... later, wipe the screen
+ink.clear()
+```
+
+
+
+### registerBlock
+
+Register a named React function component as a renderable block.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | Unique block name |
+| `component` | `Function` | ✓ | A React function component |
+
+**Returns:** `void`
+
+```ts
+ink.registerBlock('Greeting', ({ name }) =>
+ React.createElement(Text, { color: 'green' }, `Hello ${name}!`)
+)
+```
+
+
+
+### renderBlock
+
+Render a registered block by name with optional props. Looks up the component, creates a React element, renders it via ink, then immediately unmounts so the static output stays on screen while freeing the React tree.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The registered block name |
+| `data` | `Record<string, any>` |  | Props to pass to the component |
+
+**Returns:** `void`
+
+```ts
+await ink.renderBlock('Greeting', { name: 'Jon' })
+```
+
+
+
+### renderBlockAsync
+
+Render a registered block that needs to stay mounted for async work. The component receives a `done` prop — a callback it must invoke when it has finished rendering its final output. The React tree stays alive until `done()` is called or the timeout expires.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The registered block name |
+| `data` | `Record<string, any>` |  | Props to pass to the component (a `done` prop is added automatically) |
+| `options` | `{ timeout?: number }` |  | `timeout` in ms before force-unmounting (default 30 000) |
+
+**Returns:** `void`
+
+```tsx
+// In a ## Blocks section:
+function AsyncChart({ url, done }) {
+ const [rows, setRows] = React.useState(null)
+ React.useEffect(() => {
+   fetch(url).then(r => r.json()).then(data => {
+     setRows(data)
+     done()
+   })
+ }, [])
+ if (!rows) return <Text dimColor>Loading...</Text>
+ return <Box><Text>{JSON.stringify(rows)}</Text></Box>
+}
+
+// In a code block:
+await renderAsync('AsyncChart', { url: 'https://api.example.com/data' })
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `React` | `any` | The React module (createElement, useState, useEffect, etc.) Exposed so consumers don't need a separate react import. Lazy-loaded — first access triggers the import. |
+| `components` | `any` | All Ink components as a single object for destructuring. ```ts const { Box, Text, Static, Spacer } = ink.components ``` |
+| `hooks` | `any` | All Ink hooks as a single object for destructuring. ```ts const { useInput, useApp, useFocus } = ink.hooks ``` |
+| `measureElement` | `any` | The Ink measureElement utility. |
+| `isMounted` | `boolean` | Whether an ink app is currently mounted. |
+| `instance` | `any` | The raw ink render instance if you need low-level access. |
+| `blocks` | `string[]` | List all registered block names. |
+
+## Events (Zod v4 schema)
+
+### mounted
+
+Event emitted by Ink
+
+
+
+### unmounted
+
+Event emitted by Ink
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `mounted` | `boolean` | Whether an ink app is currently rendered / mounted |
+
+## Examples
+
+**loadModules**
+
+```ts
+const ink = container.feature('ink', { enable: true })
+await ink.loadModules()
+// Now sync getters like ink.React, ink.components, ink.hooks work
+const { Box, Text } = ink.components
+```
+
+
+
+**rerender**
+
+```ts
+const ink = container.feature('ink', { enable: true })
+const { React } = await ink.loadModules()
+const { Text } = ink.components
+
+await ink.render(React.createElement(Text, null, 'Hello'))
+ink.rerender(React.createElement(Text, null, 'Updated!'))
+```
+
+
+
+**unmount**
+
+```ts
+const ink = container.feature('ink', { enable: true })
+await ink.render(myElement)
+// ... later
+ink.unmount()
+console.log(ink.isMounted) // false
+```
+
+
+
+**waitUntilExit**
+
+```ts
+const ink = container.feature('ink', { enable: true })
+await ink.render(myElement)
+await ink.waitUntilExit()
+console.log('App exited')
+```
+
+
+
+**clear**
+
+```ts
+const ink = container.feature('ink', { enable: true })
+await ink.render(myElement)
+// ... later, wipe the screen
+ink.clear()
+```
+
+
+
+**registerBlock**
+
+```ts
+ink.registerBlock('Greeting', ({ name }) =>
+ React.createElement(Text, { color: 'green' }, `Hello ${name}!`)
+)
+```
+
+
+
+**renderBlock**
+
+```ts
+await ink.renderBlock('Greeting', { name: 'Jon' })
+```
+
+
+
+**renderBlockAsync**
+
+```tsx
+// In a ## Blocks section:
+function AsyncChart({ url, done }) {
+ const [rows, setRows] = React.useState(null)
+ React.useEffect(() => {
+   fetch(url).then(r => r.json()).then(data => {
+     setRows(data)
+     done()
+   })
+ }, [])
+ if (!rows) return <Text dimColor>Loading...</Text>
+ return <Box><Text>{JSON.stringify(rows)}</Text></Box>
+}
+
+// In a code block:
+await renderAsync('AsyncChart', { url: 'https://api.example.com/data' })
+```
+

package/docs/apis/features/node/ipc-socket.md

@@ -0,0 +1,260 @@
+# IpcSocket (features.ipcSocket)
+
+IpcSocket Feature - Inter-Process Communication via Unix Domain Sockets This feature provides robust IPC (Inter-Process Communication) capabilities using Unix domain sockets. It supports both server and client modes, allowing processes to communicate efficiently through file system-based socket connections. **Key Features:** - Dual-mode operation: server and client functionality - JSON message serialization/deserialization - Multiple client connection support (server mode) - Event-driven message handling - Automatic socket cleanup and management - Broadcast messaging to all connected clients - Lock file management for socket paths **Communication Pattern:** - Messages are automatically JSON-encoded with unique IDs - Both server and client emit 'message' events for incoming data - Server can broadcast to all connected clients - Client maintains single connection to server **Socket Management:** - Automatic cleanup of stale socket files - Connection tracking and management - Graceful shutdown procedures - Lock file protection against conflicts **Usage Examples:** **Server Mode:** ```typescript const ipc = container.feature('ipcSocket'); await ipc.listen('/tmp/myapp.sock', true); // removeLock=true ipc.on('connection', (socket) => { console.log('Client connected'); }); ipc.on('message', (data) => { console.log('Received:', data); ipc.broadcast({ reply: 'ACK', original: data }); }); ``` **Client Mode:** ```typescript const ipc = container.feature('ipcSocket'); await ipc.connect('/tmp/myapp.sock'); ipc.on('message', (data) => { console.log('Server says:', data); }); await ipc.send({ type: 'request', payload: 'hello' }); ```
+
+## Usage
+
+```ts
+container.feature('ipcSocket')
+```
+
+## Methods
+
+### listen
+
+Starts the IPC server listening on the specified socket path. This method sets up a Unix domain socket server that can accept multiple client connections. Each connected client is tracked, and the server automatically handles connection lifecycle events. Messages received from clients are JSON-parsed and emitted as 'message' events. **Server Behavior:** - Tracks all connected clients in the sockets Set - Automatically removes clients when they disconnect - JSON-parses incoming messages and emits 'message' events - Emits 'connection' events when clients connect - Prevents starting multiple servers on the same instance **Socket File Management:** - Resolves the socket path relative to the container's working directory - Optionally removes existing socket files to prevent "address in use" errors - Throws error if socket file exists and removeLock is false
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `socketPath` | `string` | ✓ | The file system path for the Unix domain socket |
+| `removeLock` | `any` |  | Whether to remove existing socket file (default: false) |
+
+**Returns:** `Promise<Server>`
+
+```ts
+// Basic server setup
+const server = await ipc.listen('/tmp/myapp.sock');
+
+// With automatic lock removal
+const server = await ipc.listen('/tmp/myapp.sock', true);
+
+// Handle connections and messages
+ipc.on('connection', (socket) => {
+ console.log('New client connected');
+});
+
+ipc.on('message', (data) => {
+ console.log('Received message:', data);
+ // Echo back to all clients
+ ipc.broadcast({ echo: data });
+});
+```
+
+
+
+### stopServer
+
+Stops the IPC server and cleans up all connections. This method gracefully shuts down the server by: 1. Closing the server listener 2. Destroying all active client connections 3. Clearing the sockets tracking set 4. Resetting the server instance
+
+**Returns:** `Promise<void>`
+
+```ts
+// Graceful shutdown
+try {
+ await ipc.stopServer();
+ console.log('IPC server stopped successfully');
+} catch (error) {
+ console.error('Failed to stop server:', error.message);
+}
+```
+
+
+
+### broadcast
+
+Broadcasts a message to all connected clients (server mode only). This method sends a JSON-encoded message with a unique ID to every client currently connected to the server. Each message is automatically wrapped with metadata including a UUID for tracking. **Message Format:** Messages are automatically wrapped in the format: ```json { "data": <your_message>, "id": "<uuid>" } ```
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `message` | `any` | ✓ | The message object to broadcast to all clients |
+
+**Returns:** `void`
+
+```ts
+// Broadcast to all connected clients
+ipc.broadcast({ 
+ type: 'notification',
+ message: 'Server is shutting down in 30 seconds',
+ timestamp: Date.now()
+});
+
+// Chain multiple operations
+ipc.broadcast({ status: 'ready' })
+  .broadcast({ time: new Date().toISOString() });
+```
+
+
+
+### send
+
+Sends a message to the server (client mode only). This method sends a JSON-encoded message with a unique ID to the connected server. The message is automatically wrapped with metadata for tracking purposes. **Message Format:** Messages are automatically wrapped in the format: ```json { "data": <your_message>, "id": "<uuid>" } ```
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `message` | `any` | ✓ | The message object to send to the server |
+
+**Returns:** `void`
+
+```ts
+// Send a simple message
+await ipc.send({ type: 'ping' });
+
+// Send complex data
+await ipc.send({
+ type: 'data_update',
+ payload: { users: [...], timestamp: Date.now() }
+});
+```
+
+
+
+### connect
+
+Connects to an IPC server at the specified socket path (client mode). This method establishes a client connection to an existing IPC server. Once connected, the client can send messages to the server and receive responses. The connection is maintained until explicitly closed or the server terminates. **Connection Behavior:** - Sets the socket mode to 'client' - Returns existing connection if already connected - Automatically handles connection events and cleanup - JSON-parses incoming messages and emits 'message' events - Cleans up connection reference when socket closes **Error Handling:** - Throws error if already in server mode - Rejects promise on connection failures - Automatically cleans up on connection close
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `socketPath` | `string` | ✓ | The file system path to the server's Unix domain socket |
+
+**Returns:** `Promise<Socket>`
+
+```ts
+// Connect to server
+const socket = await ipc.connect('/tmp/myapp.sock');
+console.log('Connected to IPC server');
+
+// Handle incoming messages
+ipc.on('message', (data) => {
+ console.log('Server message:', data);
+});
+
+// Send messages
+await ipc.send({ type: 'hello', client_id: 'client_001' });
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isClient` | `any` | Checks if the IPC socket is operating in client mode. |
+| `isServer` | `any` | Checks if the IPC socket is operating in server mode. |
+| `connection` | `any` | Gets the current client connection socket. |
+
+## Events (Zod v4 schema)
+
+### connection
+
+Event emitted by IpcSocket
+
+
+
+### message
+
+Event emitted by IpcSocket
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `mode` | `string` | The current mode of the IPC socket - either server or client |
+
+## Examples
+
+**listen**
+
+```ts
+// Basic server setup
+const server = await ipc.listen('/tmp/myapp.sock');
+
+// With automatic lock removal
+const server = await ipc.listen('/tmp/myapp.sock', true);
+
+// Handle connections and messages
+ipc.on('connection', (socket) => {
+ console.log('New client connected');
+});
+
+ipc.on('message', (data) => {
+ console.log('Received message:', data);
+ // Echo back to all clients
+ ipc.broadcast({ echo: data });
+});
+```
+
+
+
+**stopServer**
+
+```ts
+// Graceful shutdown
+try {
+ await ipc.stopServer();
+ console.log('IPC server stopped successfully');
+} catch (error) {
+ console.error('Failed to stop server:', error.message);
+}
+```
+
+
+
+**broadcast**
+
+```ts
+// Broadcast to all connected clients
+ipc.broadcast({ 
+ type: 'notification',
+ message: 'Server is shutting down in 30 seconds',
+ timestamp: Date.now()
+});
+
+// Chain multiple operations
+ipc.broadcast({ status: 'ready' })
+  .broadcast({ time: new Date().toISOString() });
+```
+
+
+
+**send**
+
+```ts
+// Send a simple message
+await ipc.send({ type: 'ping' });
+
+// Send complex data
+await ipc.send({
+ type: 'data_update',
+ payload: { users: [...], timestamp: Date.now() }
+});
+```
+
+
+
+**connect**
+
+```ts
+// Connect to server
+const socket = await ipc.connect('/tmp/myapp.sock');
+console.log('Connected to IPC server');
+
+// Handle incoming messages
+ipc.on('message', (data) => {
+ console.log('Server message:', data);
+});
+
+// Send messages
+await ipc.send({ type: 'hello', client_id: 'client_001' });
+```
+

package/docs/apis/features/node/json-tree.md

@@ -0,0 +1,86 @@
+# JsonTree (features.jsonTree)
+
+JsonTree Feature - A powerful JSON file tree loader and processor This feature provides functionality to recursively load JSON files from a directory structure and build a hierarchical tree representation. It automatically processes file paths to create a nested object structure where file paths become object property paths. **Key Features:** - Recursive JSON file discovery in directory trees - Automatic path-to-property mapping using camelCase conversion - Integration with FileManager for efficient file operations - State-based tree storage and retrieval - Native JSON parsing for optimal performance **Path Processing:** Files are processed to create a nested object structure: - Directory names become object properties (camelCased) - File names become the final property names (without .json extension) - Nested directories create nested objects **Usage Example:** ```typescript const jsonTree = container.feature('jsonTree', { enable: true }); await jsonTree.loadTree('data', 'appData'); const userData = jsonTree.tree.appData.users.profiles; ``` **Directory Structure Example:** ``` data/ users/ profiles.json    -> tree.data.users.profiles settings.json    -> tree.data.users.settings config/ app-config.json  -> tree.data.config.appConfig ```
+
+## Usage
+
+```ts
+container.feature('jsonTree')
+```
+
+## Methods
+
+### loadTree
+
+Loads a tree of JSON files from the specified base path and stores them in state. This method recursively scans the provided directory for JSON files, processes their content, and builds a hierarchical object structure. File paths are converted to camelCase property names, and the resulting tree is stored in the feature's state. **Processing Steps:** 1. Uses FileManager to discover all .json files recursively 2. Reads each file's content using the file system feature 3. Parses JSON content using native JSON.parse() 4. Converts file paths to nested object properties 5. Stores the complete tree in feature state **Path Transformation:** - Removes the base path prefix from file paths - Converts directory/file names to camelCase - Creates nested objects based on directory structure - Removes .json file extension **Example Transformation:** ``` config/ database/ production.json  -> tree.config.database.production staging.json     -> tree.config.database.staging api/ endpoints.json   -> tree.config.api.endpoints ```
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `basePath` | `string` | ✓ | The root directory path to scan for JSON files |
+| `key` | `string` |  | The key to store the tree under in state (defaults to first segment of basePath) |
+
+**Returns:** `void`
+
+```ts
+// Load all JSON files from 'data' directory into state.data
+await jsonTree.loadTree('data');
+
+// Load with custom key
+await jsonTree.loadTree('app/config', 'configuration');
+
+// Access the loaded data
+const dbConfig = jsonTree.tree.data.database.production;
+const apiEndpoints = jsonTree.tree.data.api.endpoints;
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `tree` | `any` | Gets the current tree data, excluding the 'enabled' state property. Returns a clean copy of the tree data without internal state management properties. This provides access to only the JSON tree data that has been loaded through loadTree(). |
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**loadTree**
+
+```ts
+// Load all JSON files from 'data' directory into state.data
+await jsonTree.loadTree('data');
+
+// Load with custom key
+await jsonTree.loadTree('app/config', 'configuration');
+
+// Access the loaded data
+const dbConfig = jsonTree.tree.data.database.production;
+const apiEndpoints = jsonTree.tree.data.api.endpoints;
+```
+
+
+
+**tree**
+
+```ts
+await jsonTree.loadTree('data');
+await jsonTree.loadTree('config', 'appConfig');
+
+const allTrees = jsonTree.tree;
+// Returns: { 
+//   data: { users: { ... }, products: { ... } },
+//   appConfig: { database: { ... }, api: { ... } }
+// }
+
+// Access specific trees
+const userData = jsonTree.tree.data.users;
+const dbConfig = jsonTree.tree.appConfig.database;
+```
+