@soederpop/luca 0.0.5 → 0.0.7

package/docs/tasks/web-container-helper-discovery.md

@@ -1,71 +0,0 @@
----
-repeatable: false
----
-
-# Implement Helper Discovery for WebContainer
-
-The NodeContainer has a `helpers` feature (`src/node/features/helpers.ts`) that provides unified discovery across all registries. The WebContainer has no equivalent. Implement helper discovery for the web container.
-
-## Context
-
-The node `Helpers` feature provides:
-- `container.helpers.discover('features')` — scan conventional folders and register what it finds
-- `container.helpers.discoverAll()` — discover across all registry types
-- `container.helpers.available` — unified view of all registries
-- `container.helpers.lookup(type, name)` and `container.helpers.describe(type, name)`
-
-The web container has `features` and `clients` registries (Client is attached via `extension.ts`, which calls `container.use(Client)` and triggers `registerHelperType('clients', 'client')`). It has `RestClient` and `SocketClient` available. No servers, commands, or endpoints registries.
-
-## What to Build
-
-### 1. Create `src/web/features/helpers.ts`
-
-Port the node `Helpers` feature to work in the browser environment. Key differences from the node version:
-
-- **No filesystem scanning** — the browser can't scan directories. Instead, discovery should work via explicit registration or a manifest/config object that lists available helpers and their import paths.
-- **Registry scope** — cover `features` and `clients` (both already attached). The `registryMap` should reflect what the web container actually has.
-- **No dynamic `import()` from disk** — helper modules need to be bundled or loaded via URL. Consider accepting a map of `{ name: () => import('./my-feature.js') }` lazy loaders.
-- **Keep the same public API surface** — `discover()`, `discoverAll()`, `available`, `lookup()`, `describe()` should all work identically from the consumer's perspective.
-
-### 2. Register it in `src/web/extension.ts`
-
-Add the helpers feature to the web extension so it's available as `container.feature('helpers')` / `container.helpers`.
-
-### 3. Approach for Browser Discovery
-
-Since there's no filesystem to scan, discovery needs a different mechanism. Recommended approach:
-
-```typescript
-// Option A: Manifest-based discovery
-const helpers = container.feature('helpers', {
-  enable: true,
-  manifest: {
-    features: {
-      myFeature: () => import('./features/my-feature.js'),
-    }
-  }
-})
-await helpers.discoverAll()
-```
-
-This keeps the same `discover()` / `discoverAll()` API but replaces folder scanning with a lazy-import manifest. The manifest can be generated at build time by a bundler plugin or written by hand.
-
-### 4. Shared Base
-
-Look at whether a base `Helpers` class can be extracted to `src/features/helpers.ts` (universal, not node or web specific) with the shared API surface (`available`, `lookup`, `describe`, state/events schemas). Then `src/node/features/helpers.ts` and `src/web/features/helpers.ts` extend it with their environment-specific discovery strategies (filesystem vs manifest).
-
-## Files to Touch
-
-- `src/features/helpers.ts` — new, shared base class with common API
-- `src/web/features/helpers.ts` — new, web-specific discovery via manifest
-- `src/node/features/helpers.ts` — refactor to extend shared base
-- `src/web/extension.ts` — register the web helpers feature
-- `src/schemas/base.ts` — only if new shared schemas are needed
-
-## Acceptance Criteria
-
-- `container.helpers.available` works in both node and web containers
-- `container.helpers.discover('features')` works in web via manifest config
-- `container.helpers.lookup()` and `container.helpers.describe()` work in web
-- Node behavior is unchanged (existing tests still pass)
-- The shared base class eliminates duplicated logic between node and web

package/docs/todos.md

@@ -1 +0,0 @@
-- make container.start() meaningful. i like the idea of container.use() accepting in addition to the current shape, an async function and container.start() basically running all of those functions.  

package/scripts/test-command-listener.ts

@@ -1,123 +0,0 @@
-import { NodeContainer } from '../src/node/container'
-
-const container = new NodeContainer({ cwd: process.cwd() })
-const listener = container.feature('launcherAppCommandListener', {
-  autoListen: true,
-})
-
-const windowManager = container.feature('windowManager')
-
-console.log('Listening on:', listener.state.get('socketPath'))
-console.log('Waiting for native app to connect...\n')
-
-listener.enable()
-
-listener.on('clientConnected', () => {
-  console.log('[connected] Native app connected')
-})
-
-listener.on('clientDisconnected', () => {
-  console.log('[disconnected] Native app disconnected')
-})
-
-listener.on('command', async (cmd) => {
-  console.log(`[command] "${cmd.text}" (source: ${cmd.source}, id: ${cmd.id})`)
-
-  const normalizedText = String(cmd.text).toLowerCase()
-
-  if (normalizedText.includes('terminal')) {
-    await container.sleep(1000)
-    cmd.ack('Sheeeeeeeit.  I got you fam!')
-    await container.sleep(1000)
-    console.log('Spawning terminal')
-    const result = await windowManager.spawnTTY({ 
-      command: '/Users/jon/.bun/bin/bun',
-      args: ['run', '/Users/jon/@luca/src/cli/cli.ts', 'console'],
-      cwd: '/Users/jon/@soederpop',
-      title: 'The Console',
-      cols: 120,
-      rows: 40,
-      width: 1000,
-      height: 700,
-    })
-
-    await container.sleep(4000)
-
-    cmd.finish({ result: { action: 'completed', text: cmd.text }, speech: 'Check that shit out playboy. Fuckin terminal output.' })
-
-    return
-  } else if (normalizedText.includes('code')) {
-    await container.sleep(1000)
-    cmd.ack('Real talk, I feel for the homies we told to learn to code.  Now that claude is on this shit?? I mean.')
-    await container.sleep(1000)
-    console.log('Spawning terminal')
-    const result = await windowManager.spawnTTY({ 
-      command: '/Users/jon/.bun/bin/claude',
-      cwd: '/Users/jon/@soederpop',
-      title: 'Claude',
-      cols: 120,
-      rows: 80,
-      width: 1000,
-      height: 700,
-    })
-
-    await container.sleep(4000)
-
-    cmd.finish({ result: { action: 'completed', text: cmd.text }, speech: 'Good luck with claude bro.' })
-
-    return   
-  } else if (normalizedText.includes('web') || normalizedText.includes('browser')) {
-    cmd.ack('Yo.... Fuckin check this out, twin.')
-    await container.sleep(1000)
-    const result = await windowManager.spawn({
-      url: 'https://google.com',
-      width: 1000,
-      height: 700,
-    })
-
-    console.log('Web browser spawned', result)
-
-    await container.sleep(3000)
-    cmd.finish({ result: { action: 'completed', text: cmd.text }, speech: 'Motherfucker I can even launch web browsers' })
-    return
-  } else if (normalizedText.includes('write')) {
-    await container.sleep(1000)
-    cmd.ack('Aight. Sheeeit. We got a real fuckin earnest hemmingway up in here.')
-    const result = await windowManager.spawn({
-      url: 'http://localhost:3080',
-      width: 1200,
-      height: 900,
-    })
-    
-    await container.sleep(4000)
-    cmd.finish({ result: { action: 'completed', text: cmd.text }, speech: 'Let the boy COOK' })
-    return
-  } else if (normalizedText.includes('track')) {
-    await container.sleep(1000)
-    cmd.ack('Better believe it.  Aint nobody hiding from your boy.')
-
-    container.proc.spawnAndCapture('luca', ['serve', '--force', '--port', '3969', '--no-open'], {
-      cwd: '/Users/jon/@soederpop/playground/enemy-tracker'
-    })
-
-    await container.sleep(4000)
-
-    const result = await windowManager.spawn({
-      url: 'http://localhost:3969',
-      width: 1400,
-      height: 1000,
-    })
-
-    cmd.finish({ result: { action: 'completed', text: cmd.text }, speech: 'Get em dawg.  Me and the homies are ready.' })
-    
-    return
-  }
-
-  await container.sleep(4000)
-  cmd.ack('Look unc. I dont know the fuck you talmbout.')
-  cmd.finish({ result: { action: 'unknown' }})
-})
-
-listener.on('message', (msg) => {
-  console.log('[message]', JSON.stringify(msg))
-})

package/src/node/features/launcher-app-command-listener.ts

@@ -1,389 +0,0 @@
-import { z } from 'zod'
-import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { Feature } from '../feature.js'
-import { Server as NetServer, Socket } from 'net'
-import { homedir } from 'os'
-import { join, dirname } from 'path'
-import { existsSync, unlinkSync, mkdirSync } from 'fs'
-
-const DEFAULT_SOCKET_PATH = join(
-  homedir(),
-  'Library',
-  'Application Support',
-  'LucaVoiceLauncher',
-  'ipc-command.sock'
-)
-
-// --- CommandHandle ---
-
-/**
- * A handle to a single incoming command from the native app.
- * Provides methods to acknowledge, report progress, and finish the command.
- * All responses are automatically correlated by the command's `id`.
- */
-export class CommandHandle {
-  /** The correlation UUID from the app. */
-  readonly id: string
-  /** The command text (e.g. "open notes"). */
-  readonly text: string
-  /** The input source (e.g. "voice", "hotkey"). */
-  readonly source: string
-  /** The full payload object from the app. */
-  readonly payload: any
-  /** The entire raw message from the app. */
-  readonly raw: any
-
-  private _send: (msg: Record<string, any>) => boolean
-  private _finished = false
-
-  constructor(msg: any, send: (msg: Record<string, any>) => boolean) {
-    this.id = msg.id
-    this.text = msg.payload?.text ?? ''
-    this.source = msg.payload?.source ?? ''
-    this.payload = msg.payload ?? {}
-    this.raw = msg
-    this._send = send
-  }
-
-  /** Whether `finish()` or `fail()` has been called. */
-  get isFinished(): boolean {
-    return this._finished
-  }
-
-  /**
-   * Send a processing acknowledgement to the app.
-   * Optionally include a speech phrase for TTS or an audio file path for playback.
-   *
-   * @param speechOrOpts - Text the app will speak, or an options object with speech and/or audioFile
-   */
-  ack(speechOrOpts?: string | { speech?: string; audioFile?: string }): boolean {
-    const opts = typeof speechOrOpts === 'string' ? { speech: speechOrOpts } : speechOrOpts
-    return this._send({
-      id: this.id,
-      status: 'processing',
-      ...(opts?.speech ? { speech: opts.speech } : {}),
-      ...(opts?.audioFile ? { audioFile: opts.audioFile } : {}),
-      timestamp: new Date().toISOString(),
-    })
-  }
-
-  /**
-   * Send a progress update to the app.
-   *
-   * @param progress - A number between 0 and 1
-   * @param message - Optional human-readable progress message
-   */
-  progress(progress: number, message?: string): boolean {
-    return this._send({
-      id: this.id,
-      status: 'progress',
-      progress,
-      ...(message ? { message } : {}),
-      timestamp: new Date().toISOString(),
-    })
-  }
-
-  /**
-   * Mark the command as successfully finished.
-   * Can only be called once per command. All arguments are optional.
-   *
-   * @param opts - Optional result payload, speech phrase, and/or audio file path
-   */
-  finish(opts?: { result?: Record<string, any>; speech?: string; audioFile?: string }): boolean {
-    if (this._finished) return false
-    this._finished = true
-    return this._send({
-      id: this.id,
-      status: 'finished',
-      success: true,
-      ...(opts?.result ? { result: opts.result } : {}),
-      ...(opts?.speech ? { speech: opts.speech } : {}),
-      ...(opts?.audioFile ? { audioFile: opts.audioFile } : {}),
-      timestamp: new Date().toISOString(),
-    })
-  }
-
-  /**
-   * Mark the command as failed.
-   * Can only be called once per command.
-   *
-   * @param opts - Optional error description, speech phrase, and/or audio file path
-   */
-  fail(opts?: { error?: string; speech?: string; audioFile?: string }): boolean {
-    if (this._finished) return false
-    this._finished = true
-    return this._send({
-      id: this.id,
-      status: 'finished',
-      success: false,
-      ...(opts?.error ? { error: opts.error } : {}),
-      ...(opts?.speech ? { speech: opts.speech } : {}),
-      ...(opts?.audioFile ? { audioFile: opts.audioFile } : {}),
-      timestamp: new Date().toISOString(),
-    })
-  }
-}
-
-// --- Schemas ---
-
-export const LauncherAppCommandListenerOptionsSchema = FeatureOptionsSchema.extend({
-  socketPath: z.string().default(DEFAULT_SOCKET_PATH)
-    .describe('Path to the Unix domain socket to listen on'),
-  autoListen: z.boolean().optional()
-    .describe('Automatically start listening when the feature is enabled'),
-})
-export type LauncherAppCommandListenerOptions = z.infer<typeof LauncherAppCommandListenerOptionsSchema>
-
-export const LauncherAppCommandListenerStateSchema = FeatureStateSchema.extend({
-  listening: z.boolean().default(false)
-    .describe('Whether the IPC server is listening'),
-  clientConnected: z.boolean().default(false)
-    .describe('Whether the native launcher app is connected'),
-  socketPath: z.string().optional()
-    .describe('The socket path in use'),
-  commandsReceived: z.number().default(0)
-    .describe('Total number of commands received'),
-  lastCommandText: z.string().optional()
-    .describe('The text of the last received command'),
-  lastError: z.string().optional()
-    .describe('Last error message'),
-})
-export type LauncherAppCommandListenerState = z.infer<typeof LauncherAppCommandListenerStateSchema>
-
-export const LauncherAppCommandListenerEventsSchema = FeatureEventsSchema.extend({
-  listening: z.tuple([]).describe('Emitted when the IPC server starts listening'),
-  clientConnected: z.tuple([z.any().describe('The client socket')]).describe('Emitted when the native app connects'),
-  clientDisconnected: z.tuple([]).describe('Emitted when the native app disconnects'),
-  command: z.tuple([z.any().describe('A CommandHandle for the incoming command')]).describe('Emitted when a command is received. The listener is responsible for calling ack(), finish(), or fail() on the handle.'),
-  message: z.tuple([z.any().describe('The parsed message')]).describe('Emitted for any non-command message from the app'),
-})
-
-// --- Private types ---
-
-interface ClientConnection {
-  socket: Socket
-  buffer: string
-}
-
-// --- Feature ---
-
-/**
- * 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.
- *
- * @example
- * ```typescript
- * 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.' })
- * })
- * ```
- */
-export class LauncherAppCommandListener extends Feature<LauncherAppCommandListenerState, LauncherAppCommandListenerOptions> {
-  static override shortcut = 'features.launcherAppCommandListener' as const
-  static override stateSchema = LauncherAppCommandListenerStateSchema
-  static override optionsSchema = LauncherAppCommandListenerOptionsSchema
-  static override eventsSchema = LauncherAppCommandListenerEventsSchema
-  static { Feature.register(this, 'launcherAppCommandListener') }
-
-  private _server?: NetServer
-  private _client?: ClientConnection
-
-  override get initialState(): LauncherAppCommandListenerState {
-    return {
-      ...super.initialState,
-      listening: false,
-      clientConnected: false,
-      commandsReceived: 0,
-    }
-  }
-
-  /** Whether the IPC server is currently listening. */
-  get isListening(): boolean {
-    return this.state.get('listening') || false
-  }
-
-  /** Whether the native app client is currently connected. */
-  get isClientConnected(): boolean {
-    return this.state.get('clientConnected') || false
-  }
-
-  override async enable(options: any = {}): Promise<this> {
-    await super.enable(options)
-
-    if (this.options.autoListen) {
-      this.listen()
-    }
-
-    return this
-  }
-
-  /**
-   * 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.
-   *
-   * @param socketPath - Override the configured socket path
-   * @returns This feature instance for chaining
-   */
-  listen(socketPath?: string): this {
-    if (this._server) return this
-
-    socketPath = socketPath || this.options.socketPath || DEFAULT_SOCKET_PATH
-
-    const dir = dirname(socketPath)
-    if (!existsSync(dir)) {
-      try {
-        mkdirSync(dir, { recursive: true })
-      } catch (error: any) {
-        this.setState({ lastError: `Failed to create socket directory ${dir}: ${error?.message || String(error)}` })
-        return this
-      }
-    }
-
-    if (existsSync(socketPath)) {
-      try {
-        unlinkSync(socketPath)
-      } catch (error: any) {
-        this.setState({ lastError: `Failed to remove stale socket at ${socketPath}: ${error?.message || String(error)}` })
-        return this
-      }
-    }
-
-    const server = new NetServer((socket) => {
-      this.handleClientConnect(socket)
-    })
-
-    server.on('error', (err) => {
-      this.setState({ lastError: err.message })
-    })
-
-    const finalPath = socketPath
-    server.listen(finalPath, () => {
-      this._server = server
-      this.setState({ listening: true, socketPath: finalPath })
-      this.emit('listening')
-    })
-
-    return this
-  }
-
-  /**
-   * Stop the IPC server and clean up all connections.
-   *
-   * @returns This feature instance for chaining
-   */
-  async stop(): Promise<this> {
-    if (this._client) {
-      this._client.socket.destroy()
-      this._client = undefined
-    }
-
-    const socketPath = this.state.get('socketPath')
-
-    if (this._server) {
-      await new Promise<void>((resolve) => {
-        this._server!.close(() => resolve())
-      })
-      this._server = undefined
-    }
-
-    if (socketPath && existsSync(socketPath)) {
-      try { unlinkSync(socketPath) } catch { /* ignore */ }
-    }
-
-    this.setState({ listening: false, clientConnected: false, socketPath: undefined })
-    return this
-  }
-
-  /**
-   * Write an NDJSON message to the connected app client.
-   *
-   * @param msg - The message object to send (will be JSON-serialized + newline)
-   * @returns True if the message was written, false if no client is connected
-   */
-  send(msg: Record<string, any>): boolean {
-    if (!this._client) return false
-    this._client.socket.write(JSON.stringify(msg) + '\n')
-    return true
-  }
-
-  // --- Private ---
-
-  /** Handle a new client connection from the native app. */
-  private handleClientConnect(socket: Socket): void {
-    const client: ClientConnection = { socket, buffer: '' }
-
-    if (this._client) {
-      this._client.socket.destroy()
-    }
-    this._client = client
-
-    this.setState({ clientConnected: true })
-    this.emit('clientConnected', socket)
-
-    socket.on('data', (chunk) => {
-      client.buffer += chunk.toString()
-      const lines = client.buffer.split('\n')
-      client.buffer = lines.pop() || ''
-      for (const line of lines) {
-        if (line.trim()) this.processLine(line)
-      }
-    })
-
-    socket.on('close', () => {
-      if (this._client === client) {
-        this._client = undefined
-        this.setState({ clientConnected: false })
-        this.emit('clientDisconnected')
-      }
-    })
-
-    socket.on('error', (err) => {
-      this.setState({ lastError: err.message })
-    })
-  }
-
-  /** Process a single NDJSON line. Wraps commands in a CommandHandle; emits `message` for everything else. */
-  private processLine(line: string): void {
-    let msg: any
-    try {
-      msg = JSON.parse(line)
-    } catch {
-      return
-    }
-
-    if (msg.type === 'command') {
-      const handle = new CommandHandle(msg, (m) => this.send(m))
-
-      this.setState({
-        commandsReceived: (this.state.get('commandsReceived') ?? 0) + 1,
-        lastCommandText: handle.text,
-      })
-
-      this.emit('command', handle)
-      return
-    }
-
-    this.emit('message', msg)
-  }
-}
-
-export default LauncherAppCommandListener