luca 2.0.0 → 3.0.0

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

@@ -0,0 +1,249 @@
+# 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:** - Hub-and-spoke: one server, many named clients with identity tracking - Targeted messaging: sendTo(clientId), broadcast(msg, excludeId) - Request/reply: ask() + reply() with timeout-based correlation - Auto-reconnect: clients reconnect with exponential backoff - Stale socket detection: probeSocket() before listen() - Clean shutdown: stopServer() removes socket file **Server (Hub):** ```typescript const ipc = container.feature('ipcSocket'); await ipc.listen('/tmp/hub.sock', true); ipc.on('connection', (clientId, socket) => { console.log('Client joined:', clientId); }); ipc.on('message', (data, clientId) => { console.log(`From ${clientId}:`, data); // Reply to sender, or ask and wait ipc.sendTo(clientId, { ack: true }); }); ``` **Client (Spoke):** ```typescript const ipc = container.feature('ipcSocket'); await ipc.connect('/tmp/hub.sock', { reconnect: true, name: 'worker-1' }); // Fire and forget await ipc.send({ type: 'status', ready: true }); // Request/reply ipc.on('message', (data) => { if (data.requestId) ipc.reply(data.requestId, { result: 42 }); }); ```
+
+## 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).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `message` | `any` | ✓ | The message object to broadcast |
+| `exclude` | `string` |  | Optional client ID to exclude from broadcast |
+
+**Returns:** `this`
+
+
+
+### sendTo
+
+Sends a message to a specific client by ID (server mode only).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `clientId` | `string` | ✓ | The target client ID |
+| `message` | `any` | ✓ | The message to send |
+
+**Returns:** `boolean`
+
+
+
+### send
+
+Fire-and-forget: sends a message to the server (client mode only). For server→client, use sendTo() or broadcast().
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `message` | `any` | ✓ | The message to send |
+
+**Returns:** `Promise<void>`
+
+
+
+### ask
+
+Sends a message and waits for a correlated reply. Works in both client and server mode. The recipient should call `reply(requestId, response)` to respond.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `message` | `any` | ✓ | The message to send |
+| `options` | `{ clientId?: string; timeoutMs?: number }` |  | Optional: clientId (server mode target), timeoutMs |
+
+**Returns:** `Promise<any>`
+
+
+
+### reply
+
+Sends a reply to a previous ask() call, correlated by requestId.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `requestId` | `string` | ✓ | The requestId from the incoming message |
+| `data` | `any` | ✓ | The reply payload |
+| `clientId` | `string` |  | Target client (server mode; for client mode, omit) |
+
+**Returns:** `void`
+
+
+
+### connect
+
+Connects to an IPC server at the specified socket path (client mode).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `socketPath` | `string` | ✓ | Path to the server's Unix domain socket |
+| `options` | `{ reconnect?: boolean; name?: string }` |  | Optional: reconnect (enable auto-reconnect), name (identify this client) |
+
+**Returns:** `Promise<Socket>`
+
+
+
+### disconnect
+
+Disconnects the client and stops any reconnection attempts.
+
+**Returns:** `void`
+
+
+
+### probeSocket
+
+Probe an existing socket to see if a live listener is behind it. Attempts a quick connect — if it succeeds, someone is listening.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `socketPath` | `string` | ✓ | Parameter socketPath |
+
+**Returns:** `Promise<boolean>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isClient` | `boolean` | Checks if the IPC socket is operating in client mode. |
+| `isServer` | `boolean` | Checks if the IPC socket is operating in server mode. |
+| `clientCount` | `number` | Returns the number of currently connected clients (server mode). |
+| `connectedClients` | `Array<{ id: string; name?: string; connectedAt: number }>` | Returns info about all connected clients (server mode). |
+| `connection` | `Socket | undefined` | Gets the current client connection socket. |
+
+## Events (Zod v4 schema)
+
+### disconnection
+
+Event emitted by IpcSocket
+
+
+
+### 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 |
+
+## 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);
+}
+```
+

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;
+```
+

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

@@ -0,0 +1,316 @@
+# Networking (features.networking)
+
+The Networking feature provides utilities for network-related operations. This feature includes utilities for port detection and availability checking, which are commonly needed when setting up servers or network services.
+
+## Usage
+
+```ts
+container.feature('networking', {
+  // Default timeout in milliseconds for probing
+  timeout,
+  // Default concurrency for scanning operations
+  concurrency,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `timeout` | `number` | Default timeout in milliseconds for probing |
+| `concurrency` | `number` | Default concurrency for scanning operations |
+
+## Methods
+
+### findOpenPort
+
+Finds the next available port starting from the specified port number. This method will search for the first available port starting from the given port number. If the specified port is available, it returns that port. Otherwise, it returns the next available port.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `startAt` | `any` |  | The port number to start searching from (0 means system will choose) |
+
+**Returns:** `Promise<number>`
+
+```ts
+// Find any available port
+const anyPort = await networking.findOpenPort()
+
+// Find an available port starting from 3000
+const port = await networking.findOpenPort(3000)
+console.log(`Server can use port: ${port}`)
+```
+
+
+
+### isPortOpen
+
+Checks if a specific port is available for use. This method attempts to detect if the specified port is available. It returns true if the port is available, false if it's already in use.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `checkPort` | `any` |  | The port number to check for availability |
+
+**Returns:** `Promise<boolean>`
+
+```ts
+// Check if port 8080 is available
+const isAvailable = await networking.isPortOpen(8080)
+if (isAvailable) {
+ console.log('Port 8080 is free to use')
+} else {
+ console.log('Port 8080 is already in use')
+}
+```
+
+
+
+### getLocalNetworks
+
+Returns local external IPv4 interfaces and their CIDR ranges.
+
+**Returns:** `LocalNetwork[]`
+
+
+
+### expandCidr
+
+Expands a CIDR block to host IP addresses. For /31 and /32, all addresses are returned. For all others, network/broadcast are excluded.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `cidr` | `string` | ✓ | Parameter cidr |
+
+**Returns:** `string[]`
+
+
+
+### getArpTable
+
+Reads and parses the system ARP cache.
+
+**Returns:** `Promise<ArpEntry[]>`
+
+
+
+### isHostReachable
+
+Performs a lightweight TCP reachability probe.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `host` | `string` | ✓ | Parameter host |
+| `options` | `ReachableHostOptions` |  | Parameter options |
+
+`ReachableHostOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `timeout` | `number` |  |
+| `ports` | `number[]` |  |
+
+**Returns:** `Promise<boolean>`
+
+
+
+### discoverHosts
+
+Discovers hosts in a CIDR range by combining ARP cache and TCP probes.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `cidr` | `string` | ✓ | Parameter cidr |
+| `options` | `DiscoverHostsOptions` |  | Parameter options |
+
+`DiscoverHostsOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `timeout` | `number` |  |
+| `concurrency` | `number` |  |
+| `ports` | `number[]` |  |
+
+**Returns:** `Promise<DiscoverHost[]>`
+
+
+
+### scanPorts
+
+TCP connect scan for a host. By default only returns open ports.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `host` | `string` | ✓ | Parameter host |
+| `options` | `ScanPortsOptions` |  | Parameter options |
+
+`ScanPortsOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ports` | `string | number[]` |  |
+| `timeout` | `number` |  |
+| `concurrency` | `number` |  |
+| `banner` | `boolean` |  |
+| `includeClosed` | `boolean` |  |
+
+**Returns:** `Promise<PortScanResult[]>`
+
+
+
+### scanLocalNetworks
+
+Convenience method: discover and port-scan hosts across all local networks.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `ScanLocalNetworksOptions` |  | Parameter options |
+
+`ScanLocalNetworksOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ports` | `string | number[]` |  |
+| `timeout` | `number` |  |
+| `concurrency` | `number` |  |
+| `hostConcurrency` | `number` |  |
+| `banner` | `boolean` |  |
+
+**Returns:** `Promise<LocalNetworkScanHost[]>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `proc` | `ReturnType<typeof this.container.feature<'proc'>>` |  |
+| `os` | `ReturnType<typeof this.container.feature<'os'>>` |  |
+| `nmap` | `{ isAvailable: () => Promise<boolean>; scan: (target: string, args?: string[]) => Promise<{ hosts: NmapHost[]; raw: string }>; quickScan: (cidr: string) => Promise<{ hosts: NmapHost[]; raw: string }>; fullScan: (target: string) => Promise<{ hosts: NmapHost[]; raw: string }> }` | Optional nmap wrapper for users that already have nmap installed. |
+
+## Events (Zod v4 schema)
+
+### scan:start
+
+When a network scan begins
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `target` | `string` | Scan target identifier |
+| `type` | `string` | Scan type identifier |
+
+
+
+### host:discovered
+
+When a host is found during network scanning
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ip` | `string` | Host IP address |
+| `mac` | `string` | MAC address when available |
+| `reachable` | `boolean` | Whether host appears reachable |
+| `method` | `'arp' | 'tcp'` | Discovery method used for this host |
+
+
+
+### scan:complete
+
+When a network scan finishes
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `target` | `string` | Scan target identifier |
+| `type` | `string` | Scan type identifier |
+| `duration` | `number` | Scan duration in milliseconds |
+| `hostsFound` | `number` | Number of hosts discovered |
+| `portsFound` | `number` | Number of open ports discovered |
+
+
+
+### port:open
+
+When an open port is detected on a host
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `host` | `string` | Host IP address |
+| `port` | `number` | Open port number |
+| `service` | `string` | Best-effort service name |
+| `banner` | `string` | Banner text when captured |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `lastScan` | `object` | The most recent network scan result |
+
+## Examples
+
+**features.networking**
+
+```ts
+const networking = container.feature('networking')
+
+// Find an available port starting from 3000
+const port = await networking.findOpenPort(3000)
+console.log(`Available port: ${port}`)
+
+// Check if a specific port is available
+const isAvailable = await networking.isPortOpen(8080)
+if (isAvailable) {
+ console.log('Port 8080 is available')
+}
+```
+
+
+
+**findOpenPort**
+
+```ts
+// Find any available port
+const anyPort = await networking.findOpenPort()
+
+// Find an available port starting from 3000
+const port = await networking.findOpenPort(3000)
+console.log(`Server can use port: ${port}`)
+```
+
+
+
+**isPortOpen**
+
+```ts
+// Check if port 8080 is available
+const isAvailable = await networking.isPortOpen(8080)
+if (isAvailable) {
+ console.log('Port 8080 is free to use')
+} else {
+ console.log('Port 8080 is already in use')
+}
+```
+