@soederpop/luca 0.0.5 → 0.0.7

package/src/web/features/voice-recognition.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { Feature } from "../../feature.js";
 import { type ContainerContext } from '../container.js'
 
@@ -17,6 +17,20 @@ export const VoiceRecognitionStateSchema = FeatureStateSchema.extend({
 export type VoiceRecognitionOptions = z.infer<typeof VoiceRecognitionOptionsSchema>
 export type VoiceRecognitionState = z.infer<typeof VoiceRecognitionStateSchema>
 
+export const VoiceRecognitionEventsSchema = FeatureEventsSchema.extend({
+  result: z.tuple([
+    z.object({
+      finalTranscript: z.string().describe('Accumulated final transcript text'),
+      interimTranscript: z.string().describe('Current interim transcript text'),
+    }).describe('Recognition result payload'),
+  ]).describe('Fires when speech recognition produces a result'),
+  error: z.tuple([z.string().describe('Error message from the recognizer')]).describe('Fires when speech recognition encounters an error'),
+  end: z.tuple([]).describe('Fires when speech recognition ends'),
+  start: z.tuple([]).describe('Fires when speech recognition starts listening'),
+  stop: z.tuple([]).describe('Fires when speech recognition is manually stopped'),
+  abort: z.tuple([]).describe('Fires when speech recognition is aborted'),
+}).describe('VoiceRecognition events')
+
 /**
  * Speech-to-text recognition using the Web Speech API (SpeechRecognition).
  *
@@ -44,6 +58,7 @@ export class VoiceRecognition<T extends VoiceRecognitionState = VoiceRecognition
 
   static override stateSchema = VoiceRecognitionStateSchema
   static override optionsSchema = VoiceRecognitionOptionsSchema
+  static override eventsSchema = VoiceRecognitionEventsSchema
   static override shortcut = "features.voice" as const
 
   static { Feature.register(this as any, 'voice') }

package/test/clients-servers.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, spyOn } from 'bun:test'
 import { NodeContainer } from '../src/node/container'
-import { WebSocketClient, GraphClient } from '../src/client'
+import { WebSocketClient } from '../src/clients/websocket'
+import { GraphClient } from '../src/clients/graph'
 
 describe('Clients', () => {
   it('container has clients registry after construction', () => {

package/test/command.test.ts

@@ -0,0 +1,267 @@
+import { describe, it, expect } from 'bun:test'
+import { Command, commands } from '../src/command'
+import { graftModule, isNativeHelperClass } from '../src/graft'
+import { NodeContainer } from '../src/node/container'
+import { z } from 'zod'
+import { CommandOptionsSchema } from '../src/schemas/base'
+// Side-effect import to register built-in commands
+import '../src/commands/index'
+
+describe('graftModule', () => {
+	it('creates a Command subclass from a run export', () => {
+		const argsSchema = CommandOptionsSchema.extend({
+			file: z.string(),
+		})
+
+		const Grafted = graftModule(Command as any, {
+			description: 'Run a file',
+			argsSchema,
+			positionals: ['file'],
+			run: async (args: any) => {},
+		}, 'graft-run-test', 'commands')
+
+		expect((Grafted as any).shortcut).toBe('commands.graft-run-test')
+		expect((Grafted as any).description).toBe('Run a file')
+		expect((Grafted as any).commandDescription).toBe('Run a file')
+		expect((Grafted as any).positionals).toEqual(['file'])
+		expect((Grafted as any).argsSchema).toBe(argsSchema)
+		expect(Grafted.name).toBe('GraftRunTestCommand')
+	})
+
+	it('creates a Command subclass from a handler export (legacy)', () => {
+		const Grafted = graftModule(Command as any, {
+			description: 'Legacy handler',
+			handler: async (opts: any, ctx: any) => {},
+		}, 'graft-handler-test', 'commands')
+
+		expect((Grafted as any).shortcut).toBe('commands.graft-handler-test')
+		expect((Grafted as any).description).toBe('Legacy handler')
+		expect(typeof (Grafted as any).prototype.run).toBe('function')
+	})
+
+	it('grafts extra exported functions as prototype methods', () => {
+		const Grafted = graftModule(Command as any, {
+			run: async () => {},
+			formatOutput: function (data: any) { return JSON.stringify(data) },
+		}, 'graft-methods-test', 'commands')
+
+		expect(typeof (Grafted as any).prototype.formatOutput).toBe('function')
+	})
+
+	it('grafts getters onto the prototype', () => {
+		const Grafted = graftModule(Command as any, {
+			run: async () => {},
+			getters: {
+				isReady() { return true },
+			},
+		}, 'graft-getters-test', 'commands')
+
+		const desc = Object.getOwnPropertyDescriptor((Grafted as any).prototype, 'isReady')
+		expect(desc).toBeDefined()
+		expect(typeof desc!.get).toBe('function')
+	})
+})
+
+describe('isNativeHelperClass', () => {
+	it('returns true for a direct subclass', () => {
+		class MyCmd extends Command {}
+		expect(isNativeHelperClass(MyCmd, Command)).toBe(true)
+	})
+
+	it('returns false for a plain function', () => {
+		function notACommand() {}
+		expect(isNativeHelperClass(notACommand, Command)).toBe(false)
+	})
+
+	it('returns false for null/undefined', () => {
+		expect(isNativeHelperClass(null, Command)).toBe(false)
+		expect(isNativeHelperClass(undefined, Command)).toBe(false)
+	})
+
+	it('returns true for the base class itself', () => {
+		expect(isNativeHelperClass(Command, Command)).toBe(true)
+	})
+})
+
+describe('Command.register', () => {
+	it('registers a class-based command and sets shortcut', () => {
+		class TestDeployCommand extends Command {
+			static override description = 'Deploy to production'
+		}
+		Command.register(TestDeployCommand, 'test-deploy')
+
+		expect(commands.has('test-deploy')).toBe(true)
+		expect((TestDeployCommand as any).shortcut).toBe('commands.test-deploy')
+		expect((TestDeployCommand as any).commandDescription).toBe('Deploy to production')
+	})
+})
+
+describe('Command.dispatch', () => {
+	it('calls run() with parsed args for CLI dispatch', async () => {
+		let received: any = null
+
+		const argsSchema = CommandOptionsSchema.extend({
+			target: z.string().default('prod'),
+		})
+
+		const Grafted = graftModule(Command as any, {
+			argsSchema,
+			run: async (args: any, ctx: any) => { received = args },
+		}, 'dispatch-cli-test', 'commands')
+
+		commands.register('dispatch-cli-test', Grafted as any)
+		const container = new NodeContainer()
+		const cmd = container.command('dispatch-cli-test' as any)
+
+		await cmd.dispatch({ _: ['dispatch-cli-test'], target: 'staging' }, 'cli')
+
+		expect(received).toBeDefined()
+		expect(received.target).toBe('staging')
+	})
+
+	it('maps positionals to named args for CLI dispatch', async () => {
+		let received: any = null
+
+		const argsSchema = CommandOptionsSchema.extend({
+			file: z.string(),
+		})
+
+		const Grafted = graftModule(Command as any, {
+			argsSchema,
+			positionals: ['file'],
+			run: async (args: any, ctx: any) => { received = args },
+		}, 'dispatch-positional-test', 'commands')
+
+		commands.register('dispatch-positional-test', Grafted as any)
+		const container = new NodeContainer()
+		const cmd = container.command('dispatch-positional-test' as any)
+
+		// Simulate: luca dispatch-positional-test myfile.ts
+		// minimist produces: { _: ['dispatch-positional-test', 'myfile.ts'] }
+		await cmd.dispatch({ _: ['dispatch-positional-test', 'myfile.ts'] }, 'cli')
+
+		expect(received).toBeDefined()
+		expect(received.file).toBe('myfile.ts')
+	})
+
+	it('collects remaining positionals into an array when schema expects one', async () => {
+		let received: any = null
+
+		const argsSchema = CommandOptionsSchema.extend({
+			action: z.string(),
+			files: z.array(z.string()),
+		})
+
+		const Grafted = graftModule(Command as any, {
+			argsSchema,
+			positionals: ['action', 'files'],
+			run: async (args: any, ctx: any) => { received = args },
+		}, 'dispatch-glob-test', 'commands')
+
+		commands.register('dispatch-glob-test', Grafted as any)
+		const container = new NodeContainer()
+		const cmd = container.command('dispatch-glob-test' as any)
+
+		// Simulate: luca dispatch-glob-test process foo.md bar.md baz.md
+		// Shell expands *.md before luca sees it
+		await cmd.dispatch({ _: ['dispatch-glob-test', 'process', 'foo.md', 'bar.md', 'baz.md'] }, 'cli')
+
+		expect(received).toBeDefined()
+		expect(received.action).toBe('process')
+		expect(received.files).toEqual(['foo.md', 'bar.md', 'baz.md'])
+	})
+
+	it('passes named args through for headless dispatch', async () => {
+		let received: any = null
+
+		const argsSchema = CommandOptionsSchema.extend({
+			file: z.string(),
+		})
+
+		const Grafted = graftModule(Command as any, {
+			argsSchema,
+			positionals: ['file'],
+			run: async (args: any, ctx: any) => { received = args },
+		}, 'dispatch-headless-test', 'commands')
+
+		commands.register('dispatch-headless-test', Grafted as any)
+		const container = new NodeContainer()
+		const cmd = container.command('dispatch-headless-test' as any)
+
+		// Headless: named args directly, no positional mapping
+		await cmd.dispatch({ file: 'script.ts' }, 'headless')
+
+		expect(received).toBeDefined()
+		expect(received.file).toBe('script.ts')
+	})
+
+	it('captures stdout/stderr for headless dispatch', async () => {
+		const argsSchema = CommandOptionsSchema.extend({})
+
+		const Grafted = graftModule(Command as any, {
+			argsSchema,
+			run: async (args: any, ctx: any) => {
+				console.log('hello from command')
+				console.error('warning: something')
+			},
+		}, 'dispatch-capture-test', 'commands')
+
+		commands.register('dispatch-capture-test', Grafted as any)
+		const container = new NodeContainer()
+		const cmd = container.command('dispatch-capture-test' as any)
+
+		const result = await cmd.dispatch({}, 'headless')
+
+		expect(result).toBeDefined()
+		expect(result!.exitCode).toBe(0)
+		expect(result!.stdout).toContain('hello from command')
+		expect(result!.stderr).toContain('warning: something')
+	})
+
+	it('captures errors for headless dispatch', async () => {
+		const argsSchema = CommandOptionsSchema.extend({})
+
+		const Grafted = graftModule(Command as any, {
+			argsSchema,
+			run: async () => { throw new Error('boom') },
+		}, 'dispatch-error-test', 'commands')
+
+		commands.register('dispatch-error-test', Grafted as any)
+		const container = new NodeContainer()
+		const cmd = container.command('dispatch-error-test' as any)
+
+		const result = await cmd.dispatch({}, 'headless')
+
+		expect(result).toBeDefined()
+		expect(result!.exitCode).toBe(1)
+		expect(result!.stderr).toContain('boom')
+	})
+})
+
+describe('Command registry', () => {
+	it('has built-in commands registered', () => {
+		const container = new NodeContainer()
+		expect(container.commands.has('run')).toBe(true)
+		expect(container.commands.has('help')).toBe(true)
+		expect(container.commands.has('eval')).toBe(true)
+		expect(container.commands.has('chat')).toBe(true)
+	})
+
+	it('built-in commands still work through registerHandler', () => {
+		const container = new NodeContainer()
+		const RunClass = container.commands.lookup('run')
+		expect(typeof RunClass).toBe('function')
+		expect(typeof RunClass.prototype.run).toBe('function')
+	})
+})
+
+describe('SimpleCommand type', () => {
+	it('grafted commands have positionals as a static property', () => {
+		const Grafted = graftModule(Command as any, {
+			positionals: ['env', 'region'],
+			run: async () => {},
+		}, 'simple-cmd-type-test', 'commands')
+
+		expect((Grafted as any).positionals).toEqual(['env', 'region'])
+	})
+})

package/test-integration/assistants-manager.test.ts

@@ -51,20 +51,16 @@ describe('Assistants Manager Integration', () => {
   })
 
   it('discovers assistants from directory', () => {
-    const manager = container.feature('assistantsManager', {
-      folder: 'assistants',
-    })
-    manager.discover()
+    const manager = container.feature('assistantsManager')
+    await manager.discover()
 
     const list = manager.list()
     expect(list.length).toBe(3)
   })
 
   it('returns correct entry metadata', () => {
-    const manager = container.feature('assistantsManager', {
-      folder: 'assistants',
-    })
-    manager.discover()
+    const manager = container.feature('assistantsManager')
+    await manager.discover()
 
     const entryA = manager.get('assistant-a')
     expect(entryA).toBeDefined()
@@ -84,10 +80,8 @@ describe('Assistants Manager Integration', () => {
   })
 
   it('creates an assistant instance', () => {
-    const manager = container.feature('assistantsManager', {
-      folder: 'assistants',
-    })
-    manager.discover()
+    const manager = container.feature('assistantsManager')
+    await manager.discover()
 
     const assistant = manager.create('assistant-a', {
       model: 'gpt-4o-mini',
@@ -99,10 +93,8 @@ describe('Assistants Manager Integration', () => {
   })
 
   it('generates a summary listing', () => {
-    const manager = container.feature('assistantsManager', {
-      folder: 'assistants',
-    })
-    manager.discover()
+    const manager = container.feature('assistantsManager')
+    await manager.discover()
 
     const summary = manager.toSummary()
     expect(typeof summary).toBe('string')
@@ -112,10 +104,8 @@ describe('Assistants Manager Integration', () => {
   })
 
   it('get returns undefined for non-existent assistant', () => {
-    const manager = container.feature('assistantsManager', {
-      folder: 'assistants',
-    })
-    manager.discover()
+    const manager = container.feature('assistantsManager')
+    await manager.discover()
 
     const entry = manager.get('non-existent')
     expect(entry).toBeUndefined()

package/tmp/.cache/luca-disk-cache/content-v2/sha512/1b/b5/c75b28794f00f94c4d609a98978e9420e9b7146d204a7fbf5b0b30477292581705d207c0100dabaac27eef540aaaece3374af75104a93219d4ec8bfb44e7

@@ -0,0 +1 @@
+["d587b833-0933-4782-8c20-ad1c28d12c7a"]

package/tmp/.cache/luca-disk-cache/content-v2/sha512/da/df/1d90ce4e042abeb035a197832c6d6893420a747a056be773eb00e4f745a037d505c8db13dde7d36b36b6b893addbb7df0f5fe9f0c13e665f20056447318b

@@ -0,0 +1 @@
+{"id":"d587b833-0933-4782-8c20-ad1c28d12c7a","title":"Untitled","model":"gpt-5.2","tags":[],"thread":"assistant:zapldb:2026-03-15","createdAt":"2026-03-15T03:08:58.783Z","updatedAt":"2026-03-15T03:08:58.783Z","messageCount":5,"metadata":{}}

package/tmp/.cache/luca-disk-cache/content-v2/sha512/ed/04/e1d0c2a58c2db29b3921ca2affb3ea4febe831c53b38ebc21019fb799823aba6ed5b4611873d2cd25d422d49955b852a9c326da0d678899bc1c2c2960901

@@ -0,0 +1 @@
+{"id":"d587b833-0933-4782-8c20-ad1c28d12c7a","title":"Untitled","model":"gpt-5.2","messages":[{"role":"system","content":"# Luca Assistant Example\n\nYou are currently an example / template \"Assistant\" provided by the Luca framework.  ( You'll probably have no idea what that is, don't worry, it doesn't matter ).\n\nYou are what gets scaffolded when a user writes the `luca scaffold assistant` command.\n\nIn luca, an Assistant is backed by a folder which has a few components:\n\n- CORE.md -- this is a markdown file that will get injected into the system prompt of a chat completion call\n- tools.ts -- this file is expected to export functions, and a schemas object whose keys are the names of the functions that get exported, and whose values are zod v4 schemas that describe the parameters\n- hooks.ts -- this file is expexted to export functions, whose names match the events emitted by the luca assistant helper\n\nCurrently, the user is chatting with you from the `luca chat` CLI.  \n\nYou should tell them what each of these files is and how to edit them.\n\nIt is also important for them to know that the luca `container` is globally available for them in the context of the `tools.ts` and `hooks.ts` files."},{"role":"user","content":"What should we do?"},{"role":"assistant","content":null,"tool_calls":[{"id":"call_bwGYIZLkPRtuqUMVRAg8ykPy","type":"function","function":{"name":"README","arguments":"{}"}}]},{"role":"tool","tool_call_id":"call_bwGYIZLkPRtuqUMVRAg8ykPy","content":"YO YO"},{"role":"assistant","content":"You’ll typically do three things: customize the assistant’s behavior (CORE.md), add capabilities (tools.ts), and wire up lifecycle events (hooks.ts).\n\n## 1) Edit `CORE.md` (behavior + policy)\n**What it is:** A markdown file whose contents get injected into the **system prompt** at runtime. This is where you define the assistant’s identity, boundaries, style, domain knowledge, do/don’t rules, and any project-specific instructions.\n\n**What to put in it:**\n- Role + purpose (“You are an assistant that helps with X…”)\n- Tone/format preferences (concise, code-first, etc.)\n- Hard constraints (what it must never do, how it handles secrets, etc.)\n- Domain context (your product, APIs, repos, conventions)\n\n**When to edit:** Any time you want the assistant to “think/behave differently” without changing code.\n\n---\n\n## 2) Edit `tools.ts` (add callable functions)\n**What it is:** A TypeScript module that exports:\n- **functions** the model can call as tools (e.g., `searchDocs`, `runQuery`, `readFile`, `createTicket`)\n- a **`schemas` object** mapping tool/function names → **zod v4 schemas** describing parameters\n\n**Why it matters:** Tools are how your assistant safely does real work (fetch data, manipulate files, call APIs) instead of guessing.\n\n**Key points:**\n- Keep tools small and composable.\n- Validate all inputs with zod schemas.\n- Return structured data the model can use.\n\n**Important:** The luca **`container`** is globally available inside `tools.ts`. Use it to access shared services/config (whatever your luca setup provides) without manually importing/constructing everything.\n\n---\n\n## 3) Edit `hooks.ts` (react to events)\n**What it is:** A TypeScript module exporting functions whose names match luca assistant helper **events** (lifecycle hooks). These run automatically when those events fire (e.g., session start, before/after tool call, etc.—depending on what luca emits in your setup).\n\n**Use cases:**\n- Logging / tracing\n- Metrics\n- Tool-call auditing\n- Injecting/refreshing context\n- Guardrails (block certain actions, redact secrets)\n\n**Important:** The luca **`container`** is also globally available in `hooks.ts`.\n\n---\n\n## What to do next (practical plan)\n1) **Open `CORE.md`** and write 10–30 lines that clearly define the assistant’s job and constraints.\n2) **Add 1–2 tools** in `tools.ts` that reflect what you actually want the assistant to be able to do (start minimal).\n3) **Add a basic hook** in `hooks.ts` for logging (so you can see what’s happening and iterate safely).\n4) Run `luca chat` again and test; tighten instructions/schemas based on failures.\n\nIf you tell me what your assistant is supposed to help with (e.g., “triage support tickets”, “write PRs”, “query an internal API”), I can suggest exactly what to put into `CORE.md` and the first tools/hooks to implement."}],"tags":[],"thread":"assistant:zapldb:2026-03-15","createdAt":"2026-03-15T03:08:58.783Z","updatedAt":"2026-03-15T03:08:58.783Z","messageCount":5,"metadata":{}}

package/tmp/.cache/luca-disk-cache/index-v5/00/13/572aa4c9a94f99eda999695d050cdd0ca7fe2d23a50af03234d4c8ce0791

@@ -0,0 +1,2 @@
+
+0633d48140563c44b78c1c0b9ff1c1fc5d79b689	{"key":"conversation-history:__index__","integrity":"sha512-G7XHWyh5TwD5TE1gmpiXjpQg6bcUbSBKf79bCzBHcpJYFwXSB8AQDauqwn7vVAqq7OM3SvdRBKkyGdTsi/tE5w==","time":1773544138800,"size":40}

package/tmp/.cache/luca-disk-cache/index-v5/75/a9/cb61dc0f0589e8ec10a9aca27b834bc73884c479941042d22a2b22324cd3

@@ -0,0 +1,2 @@
+
+db975a1cc1e358a00d66dab7a468db4ee63eb62d	{"key":"conversation-history:meta:d587b833-0933-4782-8c20-ad1c28d12c7a","integrity":"sha512-2t8dkM5OBCq+sDWhl4MsbWiTQgp0egVr53PrAOT3RaA31QXI2xPd59NrNra4k63bt98PX+nwwT5mXyAFZEcxiw==","time":1773544138799,"size":240}

package/tmp/.cache/luca-disk-cache/index-v5/9f/0f/8b1f915ee64cfff7667dd96acd7a5ac0a96aa91a346e19cefd45909a9c9c

@@ -0,0 +1,2 @@
+
+74e795aeefad56844bf7be3dc434e7e99a145283	{"key":"conversation-history:d587b833-0933-4782-8c20-ad1c28d12c7a","integrity":"sha512-7QTh0MKljC2ymzkhyir/s+pP6+gxxTs468IQGft5mCOrpu1bRhGHPSzSXUItSZVbhSqcMm2g1niJm8HCwpYJAQ==","time":1773544138797,"size":4603}

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

@@ -1,145 +0,0 @@
-# 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/examples/launcher-app-command-listener.md

@@ -1,120 +0,0 @@
----
-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`.