luca 1.1.2 → 3.0.0

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')
+```
+

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

@@ -0,0 +1,146 @@
+# OS (features.os)
+
+The OS feature provides access to operating system utilities and information. This feature wraps Node.js's built-in `os` module and provides convenient getters for system information like architecture, platform, directories, network interfaces, and hardware details.
+
+## Usage
+
+```ts
+container.feature('os')
+```
+
+## Methods
+
+### getDisplayInfo
+
+Gets information about all connected displays. Platform-specific: currently implemented for macOS (darwin). Linux and Windows will throw with a clear "not yet implemented" message.
+
+**Returns:** `DisplayInfo[]`
+
+```ts
+const displays = os.getDisplayInfo()
+displays.forEach(d => {
+ console.log(`${d.name}: ${d.resolution.width}x${d.resolution.height}${d.retina ? ' (Retina)' : ''}`)
+})
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `arch` | `string` | Gets the operating system CPU architecture. |
+| `tmpdir` | `string` | Gets the operating system's default directory for temporary files. |
+| `homedir` | `string` | Gets the current user's home directory path. |
+| `cpuCount` | `number` | Gets the number of logical CPU cores available on the system. |
+| `hostname` | `string` | Gets the hostname of the operating system. |
+| `platform` | `string` | Gets the operating system platform. |
+| `networkInterfaces` | `NodeJS.Dict<os.NetworkInterfaceInfo[]>` | Gets information about the system's network interfaces. |
+| `macAddresses` | `string[]` | Gets an array of MAC addresses for non-internal IPv4 network interfaces. This filters the network interfaces to only include external IPv4 interfaces and returns their MAC addresses, which can be useful for system identification. |
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.os**
+
+```ts
+const osInfo = container.feature('os')
+
+console.log(`Platform: ${osInfo.platform}`)
+console.log(`Architecture: ${osInfo.arch}`)
+console.log(`CPU cores: ${osInfo.cpuCount}`)
+console.log(`Home directory: ${osInfo.homedir}`)
+```
+
+
+
+**getDisplayInfo**
+
+```ts
+const displays = os.getDisplayInfo()
+displays.forEach(d => {
+ console.log(`${d.name}: ${d.resolution.width}x${d.resolution.height}${d.retina ? ' (Retina)' : ''}`)
+})
+```
+
+
+
+**arch**
+
+```ts
+const arch = os.arch
+console.log(`Running on ${arch} architecture`)
+```
+
+
+
+**tmpdir**
+
+```ts
+const tempDir = os.tmpdir
+console.log(`Temp directory: ${tempDir}`)
+```
+
+
+
+**homedir**
+
+```ts
+const home = os.homedir
+console.log(`User home: ${home}`)
+```
+
+
+
+**cpuCount**
+
+```ts
+const cores = os.cpuCount
+console.log(`System has ${cores} CPU cores`)
+```
+
+
+
+**hostname**
+
+```ts
+const hostname = os.hostname
+console.log(`Hostname: ${hostname}`)
+```
+
+
+
+**platform**
+
+```ts
+const platform = os.platform
+if (platform === 'darwin') {
+ console.log('Running on macOS')
+}
+```
+
+
+
+**networkInterfaces**
+
+```ts
+const interfaces = os.networkInterfaces
+Object.keys(interfaces).forEach(name => {
+ console.log(`Interface ${name}:`, interfaces[name])
+})
+```
+
+
+
+**macAddresses**
+
+```ts
+const macAddresses = os.macAddresses
+console.log(`External MAC addresses: ${macAddresses.join(', ')}`)
+```
+