@soederpop/luca 0.0.6 → 0.0.8

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/vm-context.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'bun:test'
+import { NodeContainer } from '../src/node/container'
+
+/**
+ * These tests verify the VM context preservation behavior that `luca run`
+ * depends on for markdown execution. When running sequential code blocks
+ * in a shared context, variables defined in earlier blocks must be accessible
+ * in later blocks — as long as the blocks don't use top-level await (which
+ * wraps code in an async IIFE and isolates the scope).
+ */
+describe('VM context preservation across sequential runs', () => {
+	it('preserves const declarations across runs without await', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('const x = 42', shared)
+		const result = await vm.run('x', shared)
+
+		expect(result).toBe(42)
+	})
+
+	it('preserves let declarations across runs without await', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('let count = 0', shared)
+		await vm.run('count += 10', shared)
+		const result = await vm.run('count', shared)
+
+		expect(result).toBe(10)
+	})
+
+	it('preserves function declarations across runs', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('function double(n) { return n * 2 }', shared)
+		const result = await vm.run('double(21)', shared)
+
+		expect(result).toBe(42)
+	})
+
+	it('preserves arrow functions assigned to const', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('const greet = (name) => `hello ${name}`', shared)
+		const result = await vm.run('greet("world")', shared)
+
+		expect(result).toBe('hello world')
+	})
+
+	it('preserves objects and allows mutation across runs', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('const data = { items: [] }', shared)
+		await vm.run('data.items.push("a", "b")', shared)
+		await vm.run('data.items.push("c")', shared)
+		const result = await vm.run('data.items', shared)
+
+		expect(result).toEqual(['a', 'b', 'c'])
+	})
+
+	it('preserves class declarations across runs', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('class Counter { constructor() { this.n = 0 } inc() { this.n++ } }', shared)
+		await vm.run('const counter = new Counter(); counter.inc(); counter.inc()', shared)
+		const result = await vm.run('counter.n', shared)
+
+		expect(result).toBe(2)
+	})
+
+	it('later blocks can compose values from earlier blocks', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('const firstName = "Jane"', shared)
+		await vm.run('const lastName = "Doe"', shared)
+		await vm.run('const fullName = `${firstName} ${lastName}`', shared)
+		const result = await vm.run('fullName', shared)
+
+		expect(result).toBe('Jane Doe')
+	})
+
+	it('top-level await blocks lose const/let scope (known limitation)', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		// This block has await, so it gets wrapped in (async () => { ... })()
+		// The const is scoped to that IIFE and doesn't leak to the shared context
+		await vm.run('const val = await Promise.resolve(99)', shared)
+		const result = await vm.run('typeof val', shared)
+
+		expect(result).toBe('undefined')
+	})
+
+	it('top-level await blocks can share state via pre-existing context properties', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({ result: null })
+
+		// Assigning to an existing context property works even inside the IIFE
+		await vm.run('result = await Promise.resolve("async value")', shared)
+		const value = await vm.run('result', shared)
+
+		expect(value).toBe('async value')
+	})
+})
+
+describe('VM wrapTopLevelAwait', () => {
+	it('does not wrap code without await', () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+
+		const code = 'const x = 42'
+		expect(vm.wrapTopLevelAwait(code)).toBe(code)
+	})
+
+	it('wraps code containing await in an async IIFE', () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+
+		const wrapped = vm.wrapTopLevelAwait('const x = await fetch("http://example.com")')
+		expect(wrapped).toContain('async')
+		expect(wrapped).toContain('await fetch')
+	})
+
+	it('does not wrap code already in an async function', () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+
+		const code = 'async function go() { await fetch("http://example.com") }'
+		expect(vm.wrapTopLevelAwait(code)).toBe(code)
+	})
+})

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/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.' })
-})
-```
-