@soederpop/luca 0.0.2

package/docs/apis/features/node/launcher-app-command-listener.md

@@ -0,0 +1,145 @@
+# LauncherAppCommandListener (features.launcherAppCommandListener)
+
+LauncherAppCommandListener — IPC transport for commands from the LucaVoiceLauncher app Listens on a Unix domain socket for the native macOS launcher app to connect. When a command event arrives (voice, hotkey, text input), it wraps it in a `CommandHandle` and emits a `command` event. The consumer is responsible for acknowledging, processing, and finishing the command via the handle. Uses NDJSON (newline-delimited JSON) over the socket per the CLIENT_SPEC protocol.
+
+## Usage
+
+```ts
+container.feature('launcherAppCommandListener', {
+  // Path to the Unix domain socket to listen on
+  socketPath,
+  // Automatically start listening when the feature is enabled
+  autoListen,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `socketPath` | `string` | Path to the Unix domain socket to listen on |
+| `autoListen` | `boolean` | Automatically start listening when the feature is enabled |
+
+## Methods
+
+### enable
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `any` |  | Parameter options |
+
+**Returns:** `Promise<this>`
+
+
+
+### listen
+
+Start listening on the Unix domain socket for the native app to connect. Fire-and-forget — binds the socket and returns immediately. Sits quietly until the native app connects; does nothing visible if it never does.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `socketPath` | `string` |  | Override the configured socket path |
+
+**Returns:** `this`
+
+
+
+### stop
+
+Stop the IPC server and clean up all connections.
+
+**Returns:** `Promise<this>`
+
+
+
+### send
+
+Write an NDJSON message to the connected app client.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `msg` | `Record<string, any>` | ✓ | The message object to send (will be JSON-serialized + newline) |
+
+**Returns:** `boolean`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isListening` | `boolean` | Whether the IPC server is currently listening. |
+| `isClientConnected` | `boolean` | Whether the native app client is currently connected. |
+
+## Events (Zod v4 schema)
+
+### listening
+
+Event emitted by LauncherAppCommandListener
+
+
+
+### clientConnected
+
+Event emitted by LauncherAppCommandListener
+
+
+
+### clientDisconnected
+
+Event emitted by LauncherAppCommandListener
+
+
+
+### command
+
+Event emitted by LauncherAppCommandListener
+
+
+
+### message
+
+Event emitted by LauncherAppCommandListener
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `listening` | `boolean` | Whether the IPC server is listening |
+| `clientConnected` | `boolean` | Whether the native launcher app is connected |
+| `socketPath` | `string` | The socket path in use |
+| `commandsReceived` | `number` | Total number of commands received |
+| `lastCommandText` | `string` | The text of the last received command |
+| `lastError` | `string` | Last error message |
+
+## Examples
+
+**features.launcherAppCommandListener**
+
+```ts
+const listener = container.feature('launcherAppCommandListener', {
+ enable: true,
+ autoListen: true,
+})
+
+listener.on('command', async (cmd) => {
+ cmd.ack('Working on it!')     // or just cmd.ack() for silent
+
+ // ... do your actual work ...
+ cmd.progress(0.5, 'Halfway there')
+
+ cmd.finish()                   // silent finish
+ cmd.finish({ result: { action: 'completed' }, speech: 'All done!' })
+ // or: cmd.fail({ error: 'not found', speech: 'Sorry, that failed.' })
+})
+```
+

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

@@ -0,0 +1,281 @@
+# 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:** `void`
+
+```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:** `void`
+
+```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` | `any` |  |
+| `os` | `any` |  |
+| `nmap` | `any` | Optional nmap wrapper for users that already have nmap installed. |
+
+## Events (Zod v4 schema)
+
+### scan:start
+
+Event emitted by Networking
+
+
+
+### host:discovered
+
+Event emitted by Networking
+
+
+
+### scan:complete
+
+Event emitted by Networking
+
+
+
+### port:open
+
+Event emitted by Networking
+
+
+
+## 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')
+}
+```
+

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

@@ -0,0 +1,133 @@
+# NLP (features.nlp)
+
+The NLP feature provides natural language processing utilities for parsing utterances into structured data. Combines two complementary libraries: - **compromise**: Verb normalization (toInfinitive), POS pattern matching - **wink-nlp**: High-accuracy POS tagging (~95%), named entity recognition Three methods at increasing levels of detail: - `parse()` — compromise-powered quick structure + verb normalization - `analyze()` — wink-powered high-accuracy POS + entity extraction - `understand()` — combined parse + analyze merged
+
+## Usage
+
+```ts
+container.feature('nlp')
+```
+
+## Methods
+
+### parse
+
+Parse an utterance into structured command data using compromise. Extracts intent (normalized verb), target noun, prepositional subject, and modifiers.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `text` | `string` | ✓ | The raw utterance to parse |
+
+**Returns:** `ParsedCommand`
+
+```ts
+nlp.parse("open the terminal")
+// { intent: "open", target: "terminal", subject: null, modifiers: [], raw: "open the terminal" }
+
+nlp.parse("draw a diagram of the auth flow")
+// { intent: "draw", target: "diagram", subject: "auth flow", modifiers: [], raw: "..." }
+```
+
+
+
+### analyze
+
+Analyze text with high-accuracy POS tagging and named entity recognition using wink-nlp.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `text` | `string` | ✓ | The text to analyze |
+
+**Returns:** `Analysis`
+
+```ts
+nlp.analyze("meet john at 3pm about the deployment")
+// { tokens: [{value:"meet",pos:"VERB"}, {value:"john",pos:"PROPN"}, ...],
+//   entities: [{value:"john",type:"PERSON"}, {value:"3pm",type:"TIME"}],
+//   raw: "meet john at 3pm about the deployment" }
+```
+
+
+
+### understand
+
+Full understanding: combines compromise parsing with wink-nlp analysis. Returns intent, target, subject, modifiers (from parse) plus tokens and entities (from analyze).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `text` | `string` | ✓ | The text to understand |
+
+**Returns:** `ParsedCommand & Analysis`
+
+```ts
+nlp.understand("draw a diagram of the auth flow")
+// { intent: "draw", target: "diagram", subject: "auth flow", modifiers: [],
+//   tokens: [{value:"draw",pos:"VERB"}, ...], entities: [...], raw: "..." }
+```
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `parseCalls` | `number` | Total parse() invocations |
+| `analyzeCalls` | `number` | Total analyze() invocations |
+
+## Examples
+
+**features.nlp**
+
+```ts
+const nlp = container.feature('nlp', { enable: true })
+
+nlp.parse("draw a diagram of the auth flow")
+// { intent: "draw", target: "diagram", subject: "auth flow", modifiers: [], raw: "..." }
+
+nlp.analyze("meet john at 3pm about the deployment")
+// { tokens: [{value:"meet",pos:"VERB"}, ...], entities: [{value:"john",type:"PERSON"}, ...] }
+
+nlp.understand("draw a diagram of the auth flow")
+// { intent, target, subject, modifiers, tokens, entities, raw }
+```
+
+
+
+**parse**
+
+```ts
+nlp.parse("open the terminal")
+// { intent: "open", target: "terminal", subject: null, modifiers: [], raw: "open the terminal" }
+
+nlp.parse("draw a diagram of the auth flow")
+// { intent: "draw", target: "diagram", subject: "auth flow", modifiers: [], raw: "..." }
+```
+
+
+
+**analyze**
+
+```ts
+nlp.analyze("meet john at 3pm about the deployment")
+// { tokens: [{value:"meet",pos:"VERB"}, {value:"john",pos:"PROPN"}, ...],
+//   entities: [{value:"john",type:"PERSON"}, {value:"3pm",type:"TIME"}],
+//   raw: "meet john at 3pm about the deployment" }
+```
+
+
+
+**understand**
+
+```ts
+nlp.understand("draw a diagram of the auth flow")
+// { intent: "draw", target: "diagram", subject: "auth flow", modifiers: [],
+//   tokens: [{value:"draw",pos:"VERB"}, ...], entities: [...], raw: "..." }
+```
+

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

@@ -0,0 +1,97 @@
+# Opener (features.opener)
+
+The Opener feature opens files, URLs, desktop applications, and code editors. HTTP/HTTPS URLs are opened in Google Chrome. Desktop apps can be launched by name. VS Code and Cursor can be opened to a specific path. All other paths are opened with the platform's default handler (e.g. Preview for images, Finder for folders).
+
+## Usage
+
+```ts
+container.feature('opener')
+```
+
+## Methods
+
+### open
+
+Opens a path or URL with the appropriate application. HTTP and HTTPS URLs are opened in Google Chrome. Everything else is opened with the system default handler via `open` (macOS).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `target` | `string` | ✓ | A URL or file path to open |
+
+**Returns:** `Promise<void>`
+
+
+
+### app
+
+Opens a desktop application by name. On macOS, uses `open -a` to launch the app. On Windows, uses `start`. On Linux, attempts to run the lowercase app name as a command.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The application name (e.g. "Slack", "Finder", "Safari") |
+
+**Returns:** `Promise<void>`
+
+
+
+### code
+
+Opens VS Code at the specified path. Uses the `code` CLI command. Falls back to `open -a "Visual Studio Code"` on macOS.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` |  | The file or folder path to open |
+
+**Returns:** `Promise<void>`
+
+
+
+### cursor
+
+Opens Cursor at the specified path. Uses the `cursor` CLI command. Falls back to `open -a "Cursor"` on macOS.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` |  | The file or folder path to open |
+
+**Returns:** `Promise<void>`
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.opener**
+
+```ts
+const opener = container.feature('opener')
+
+// Open a URL in Chrome
+await opener.open('https://www.google.com')
+
+// Open a file with the default application
+await opener.open('/path/to/image.png')
+
+// Open a desktop application
+await opener.app('Slack')
+
+// Open VS Code at a project path
+await opener.code('/Users/jon/projects/my-app')
+
+// Open Cursor at a project path
+await opener.cursor('/Users/jon/projects/my-app')
+```
+