@soederpop/luca 0.0.6 → 0.0.8

package/src/cli/cli.ts

@@ -5,30 +5,74 @@ import { homedir } from 'os'
 import { join } from 'path'
 
 async function main() {
+	const profile = process.env.LUCA_PROFILE === '1'
+	const t = (label?: string) => {
+		if (!profile) return () => {}
+		const start = performance.now()
+		return (suffix?: string) => {
+			const ms = (performance.now() - start).toFixed(1)
+			console.error(`[profile] ${label}${suffix ? ` ${suffix}` : ''}: ${ms}ms`)
+		}
+	}
+
+	const tTotal = t('total boot')
+
+	// LUCA_COMMAND_DISCOVERY: "disable" skips all, "no-local" skips project, "no-home" skips user
+	const discovery = process.env.LUCA_COMMAND_DISCOVERY || ''
+
+	// Snapshot built-in commands BEFORE loadCliModule — luca.cli.ts may call
+	// helpers.discoverAll() which registers project commands early
+	const builtinCommands = new Set(container.commands.available as string[])
+
 	// Load project-level CLI module (luca.cli.ts) for container customization
+	let done = t('loadCliModule')
 	await loadCliModule()
+	done()
+
 	// Discover project-local commands (commands/ or src/commands/)
-	await discoverProjectCommands()
+	done = t('discoverProjectCommands')
+	if (discovery !== 'disable' && discovery !== 'no-local') {
+		await discoverProjectCommands()
+	}
+	done()
+	const afterProject = new Set(container.commands.available as string[])
+	const projectCommands = new Set([...afterProject].filter((n) => !builtinCommands.has(n)))
+
 	// Discover user-level commands (~/.luca/commands/)
-	await discoverUserCommands()
+	done = t('discoverUserCommands')
+	if (discovery !== 'disable' && discovery !== 'no-home') {
+		await discoverUserCommands()
+	}
+	done()
+	const afterUser = new Set(container.commands.available as string[])
+	const userCommands = new Set([...afterUser].filter((n) => !builtinCommands.has(n) && !projectCommands.has(n)))
+
+	// Store command sources for help display
+	;(container as any)._commandSources = { builtinCommands, projectCommands, userCommands }
+
 	// Load generated introspection data if present
+	done = t('loadProjectIntrospection')
 	await loadProjectIntrospection()
+	done()
 
 	const commandName = container.argv._[0] as string
 
+	done = t('dispatch')
 	if (commandName && container.commands.has(commandName)) {
 		const cmd = container.command(commandName as any)
-		await cmd.run()
+		await cmd.dispatch()
 	} else if (commandName) {
 		// not a known command — treat as implicit `run`
 		container.argv._.splice(0, 0, 'run')
 		const cmd = container.command('run' as any)
-		await cmd.run()
+		await cmd.dispatch()
 	} else {
 		container.argv._.splice(0, 0, 'help')
 		const cmd = container.command('help' as any)
-		await cmd.run()
+		await cmd.dispatch()
 	}
+	done()
+	tTotal()
 }
 
 
@@ -36,28 +80,26 @@ async function loadCliModule() {
 	const modulePath = container.paths.resolve('luca.cli.ts')
 	if (!container.fs.exists(modulePath)) return
 
-	const mod = await import(modulePath)
-	const exports = mod.default || mod
+	// Use the helpers feature to load the module — it handles the native import
+	// vs VM decision using the same useNativeImport check as discovery
+	const helpers = container.feature('helpers') as any
+	const exports = await helpers.loadModuleExports(modulePath)
 
-	if (typeof exports.main === 'function') {
+	if (typeof exports?.main === 'function') {
 		await exports.main(container)
 	}
 
-	if (typeof exports.onStart === 'function') {
+	if (typeof exports?.onStart === 'function') {
 		container.once('started', () => exports.onStart(container))
 	}
 }
 
 async function discoverProjectCommands() {
-	const { fs, paths } = container
-
-	for (const candidate of ['commands', 'src/commands']) {
-		const dir = paths.resolve(candidate)
-		if (fs.exists(dir)) {
-			await container.commands.discover({ directory: dir })
-			return
-		}
-	}
+	// Always route through the helpers feature — it handles native import vs VM
+	// internally, and deduplicates concurrent/repeated discovery via promise caching.
+	// If luca.cli.ts already called helpers.discoverAll(), this resolves instantly.
+	const helpers = container.feature('helpers') as any
+	await helpers.discover('commands')
 }
 
 async function loadProjectIntrospection() {
@@ -81,11 +123,12 @@ async function loadProjectIntrospection() {
 }
 
 async function discoverUserCommands() {
-	const { fs } = container
 	const dir = join(homedir(), '.luca', 'commands')
 
-	if (fs.exists(dir)) {
-		await container.commands.discover({ directory: dir })
+	if (container.fs.exists(dir)) {
+		// Route through helpers for consistent dedup and VM/native handling
+		const helpers = container.feature('helpers') as any
+		await helpers.discover('commands', { directory: dir })
 	}
 }
 

package/src/client.ts

@@ -1,25 +1,24 @@
 import { Helper } from "./helper.js";
 import type { Container, ContainerContext } from "./container.js";
-import axios, { type AxiosError, type AxiosInstance, type AxiosRequestConfig } from "axios";
 import { Registry } from "./registry.js";
 import { z } from 'zod'
 import {
   ClientStateSchema, ClientOptionsSchema, ClientEventsSchema,
-  WebSocketClientStateSchema, WebSocketClientOptionsSchema, WebSocketClientEventsSchema,
-  GraphClientOptionsSchema, GraphClientEventsSchema,
 } from './schemas/base.js'
 
 export type ClientOptions = z.infer<typeof ClientOptionsSchema>
 export type ClientState = z.infer<typeof ClientStateSchema>
-export type WebSocketClientState = z.infer<typeof WebSocketClientStateSchema>
-export type WebSocketClientOptions = z.infer<typeof WebSocketClientOptionsSchema>
-export type GraphClientOptions = z.infer<typeof GraphClientOptionsSchema>
 
-export interface AvailableClients {
-  rest: typeof RestClient;
-  graph: typeof GraphClient;
-  websocket: typeof WebSocketClient;
-}
+// Subclass types re-exported for backward compatibility.
+// Import the concrete classes from their individual files:
+//   import { RestClient } from './clients/rest'
+//   import { GraphClient } from './clients/graph'
+//   import { WebSocketClient } from './clients/websocket'
+export type { WebSocketClientState, WebSocketClientOptions } from './clients/websocket.js'
+export type { GraphClientOptions } from './clients/graph.js'
+
+// AvailableClients is an open interface — subclasses augment it via `declare module`
+export interface AvailableClients {}
 
 export interface ClientsInterface {
   clients: ClientsRegistry;
@@ -29,6 +28,14 @@ export interface ClientsInterface {
   ): InstanceType<AvailableClients[T]>;
 }
 
+/**
+ * Base client class for all Luca network clients. Provides connection state
+ * tracking, configuration, and the registry/factory infrastructure for
+ * creating typed client instances via `container.client('rest')`.
+ *
+ * Subclasses should override `connect()` and add protocol-specific methods.
+ * Register subclasses using `Client.register(this, 'myClient')` in a static block.
+ */
 export class Client<
   T extends ClientState = ClientState,
   K extends ClientOptions = ClientOptions
@@ -81,6 +88,7 @@ export class Client<
     this.state.set("connected", false);
   }
 
+  /** The base URL for this client's connections/requests. */
   get baseURL() {
     return this.options.baseURL || ''
   }
@@ -89,14 +97,17 @@ export class Client<
     return this._options as K;
   }
 
+  /** Configure this client instance with additional options. */
   configure(options?: any): this {
     return this;
   }
 
+  /** Whether the client is currently connected. */
   get isConnected() {
     return !!this.state.get("connected");
   }
 
+  /** Establish a connection. Subclasses should override with protocol-specific logic. */
   async connect(): Promise<this> {
     this.state.set("connected", true);
     return this;
@@ -104,7 +115,7 @@ export class Client<
 }
 
 // --- Registry and Client.register must be defined BEFORE subclasses ---
-// because static blocks in RestClient/GraphClient/WebSocketClient run at class declaration time.
+// because static blocks in subclass files run at class declaration time.
 
 export class ClientsRegistry extends Registry<Client<any>> {
   override scope = "clients"
@@ -156,349 +167,4 @@ Client.register = function registerClient(
   return SubClass
 }
 
-// --- Built-in client subclasses ---
-
-export class RestClient<
-  T extends ClientState = ClientState,
-  K extends ClientOptions = ClientOptions
-> extends Client<T, K> {
-  axios!: AxiosInstance;
-
-  static override shortcut: string = "clients.rest"
-  static { Client.register(this, 'rest') }
-
-  constructor(options: K, context: ContainerContext) {
-    super(options, context);
-
-    this.axios = axios.create({
-      baseURL: this.baseURL,
-    });
-
-    if (this.useJSON) {
-      this.axios.defaults.headers.common = {
-        ...this.axios.defaults.headers.common,
-        "Content-Type": "application/json",
-        Accept: "application/json",
-      }
-    }
-  }
-
-  async beforeRequest() {
-  }
-
-  get useJSON() {
-    return !!this.options.json
-  }
-
-  override get baseURL() {
-    return this.options.baseURL || '/'
-  }
-
-  async patch(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
-    await this.beforeRequest();
-    return this.axios({
-      ...options,
-      method: "PATCH",
-      url,
-      data,
-    })
-      .then((r) => r.data)
-      .catch((e: any) => {
-        if (e.isAxiosError) {
-          return this.handleError(e);
-        } else {
-          throw e;
-        }
-      });
-  }
-
-  async put(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
-    await this.beforeRequest();
-    return this.axios({
-      ...options,
-      method: "PUT",
-      url,
-      data,
-    })
-      .then((r) => r.data)
-      .catch((e: any) => {
-        if (e.isAxiosError) {
-          return this.handleError(e);
-        } else {
-          throw e;
-        }
-      });
-  }
-
-  async post(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
-    await this.beforeRequest();
-    return this.axios({
-      ...options,
-      method: "POST",
-      url,
-      data,
-    })
-      .then((r) => r.data)
-      .catch((e: any) => {
-        if (e.isAxiosError) {
-          return this.handleError(e);
-        } else {
-          throw e;
-        }
-      });
-  }
-
-  async delete(url: string, params: any = {}, options: AxiosRequestConfig = {}) {
-    await this.beforeRequest();
-    return this.axios({
-      ...options,
-      method: "DELETE",
-      url,
-      params,
-    })
-      .then((r) => r.data)
-      .catch((e: any) => {
-        if (e.isAxiosError) {
-          return this.handleError(e);
-        } else {
-          throw e;
-        }
-      });
-  }
-
-
-  async get(url: string, params: any = {}, options: AxiosRequestConfig = {}) {
-    await this.beforeRequest()
-    return this.axios({
-      ...options,
-      method: "GET",
-      url,
-      params,
-    })
-      .then((r) => r.data)
-      .catch((e: any) => {
-        if (e.isAxiosError) {
-          return this.handleError(e);
-        } else {
-          throw e;
-        }
-      });
-  }
-
-  async handleError(error: AxiosError) {
-    this.emit('failure', error)
-    return error.toJSON();
-  }
-}
-
-/**
- * GraphQL client that wraps RestClient with convenience methods for executing
- * queries and mutations. Automatically handles the GraphQL request envelope
- * (query/variables/operationName) and unwraps responses, extracting the `data`
- * field and emitting events for GraphQL-level errors.
- */
-export class GraphClient<
-  T extends ClientState = ClientState,
-  K extends GraphClientOptions = GraphClientOptions
-> extends RestClient<T, K> {
-  static override shortcut = "clients.graph" as const
-  static override optionsSchema = GraphClientOptionsSchema
-  static override eventsSchema = GraphClientEventsSchema
-  static { Client.register(this, 'graph') }
-
-  /** The GraphQL endpoint path. Defaults to '/graphql'. */
-  get endpoint() {
-    return (this.options as GraphClientOptions).endpoint || '/graphql'
-  }
-
-  /**
-   * Execute a GraphQL query and return the unwrapped data.
-   * @param query - The GraphQL query string
-   * @param variables - Optional variables for the query
-   * @param operationName - Optional operation name when the query contains multiple operations
-   */
-  async query<R = any>(query: string, variables?: Record<string, any>, operationName?: string): Promise<R> {
-    return this.execute<R>(query, variables, operationName)
-  }
-
-  /**
-   * Execute a GraphQL mutation and return the unwrapped data.
-   * Semantically identical to query() but named for clarity when performing mutations.
-   * @param mutation - The GraphQL mutation string
-   * @param variables - Optional variables for the mutation
-   * @param operationName - Optional operation name when the mutation contains multiple operations
-   */
-  async mutate<R = any>(mutation: string, variables?: Record<string, any>, operationName?: string): Promise<R> {
-    return this.execute<R>(mutation, variables, operationName)
-  }
-
-  /**
-   * Execute a GraphQL operation, unwrap the response, and handle errors.
-   * Posts to the configured endpoint with the standard GraphQL envelope.
-   * If the response contains GraphQL-level errors, emits both 'graphqlError'
-   * and 'failure' events before returning the data.
-   */
-  private async execute<R = any>(query: string, variables?: Record<string, any>, operationName?: string): Promise<R> {
-    const body: Record<string, any> = { query }
-    if (variables) body.variables = variables
-    if (operationName) body.operationName = operationName
-
-    const response = await this.post(this.endpoint, body)
-
-    if (response?.errors?.length) {
-      this.emit('graphqlError', response.errors)
-      this.emit('failure', response.errors)
-    }
-
-    return response?.data as R
-  }
-}
-
-/**
- * WebSocket client that bridges raw WebSocket events to Luca's Helper event bus,
- * providing a clean interface for sending/receiving messages, tracking connection
- * state, and optional auto-reconnection with exponential backoff.
- *
- * Events emitted:
- * - `open` — connection established
- * - `message` — message received (JSON-parsed when possible)
- * - `close` — connection closed (with code and reason)
- * - `error` — connection error
- * - `reconnecting` — attempting reconnection (with attempt number)
- */
-export class WebSocketClient<
-  T extends WebSocketClientState = WebSocketClientState,
-  K extends WebSocketClientOptions = WebSocketClientOptions
-> extends Client<T, K> {
-  ws!: WebSocket
-  _intentionalClose: boolean
-
-  static override shortcut = "clients.websocket" as const
-  static override stateSchema = WebSocketClientStateSchema
-  static override optionsSchema = WebSocketClientOptionsSchema
-  static override eventsSchema = WebSocketClientEventsSchema
-  static { Client.register(this, 'websocket') }
-
-  constructor(options?: K, context?: ContainerContext) {
-    super(options, context)
-    this._intentionalClose = false
-  }
-
-  override get initialState(): T {
-    return {
-      connected: false,
-      reconnectAttempts: 0,
-    } as T
-  }
-
-  /**
-   * Establish a WebSocket connection to the configured baseURL.
-   * Wires all raw WebSocket events (open, message, close, error) to the
-   * Helper event bus and updates connection state accordingly.
-   * Resolves once the connection is open; rejects on error.
-   */
-  override async connect(): Promise<this> {
-    if (this.isConnected) {
-      return this
-    }
-
-    const ws = this.ws = new WebSocket(this.baseURL)
-    const state = this.state as any
-
-    await new Promise<void>((resolve, reject) => {
-      ws.onopen = () => {
-        state.set('connected', true)
-        state.set('connectionError', undefined)
-        state.set('reconnectAttempts', 0)
-        this.emit('open')
-        resolve()
-      }
-
-      ws.onerror = (event: any) => {
-        state.set('connectionError', event)
-        this.emit('error', event)
-        reject(event)
-      }
-
-      ws.onmessage = (event: any) => {
-        let data = event?.data ?? event
-        try {
-          data = JSON.parse(data)
-        } catch {}
-        this.emit('message', data)
-      }
-
-      ws.onclose = (event: any) => {
-        state.set('connected', false)
-        this.emit('close', event?.code, event?.reason)
-        if (!this._intentionalClose) {
-          this.maybeReconnect()
-        }
-        this._intentionalClose = false
-      }
-    })
-
-    return this
-  }
-
-  /**
-   * Send data over the WebSocket connection. Automatically JSON-serializes
-   * the payload. If not currently connected, attempts to connect first.
-   * @param data - The data to send (will be JSON.stringify'd)
-   */
-  async send(data: any): Promise<void> {
-    if (!this.isConnected) {
-      await this.connect()
-    }
-
-    if (!this.ws) {
-      throw new Error('WebSocket instance not available')
-    }
-
-    this.ws.send(JSON.stringify(data))
-  }
-
-  /**
-   * Gracefully close the WebSocket connection. Suppresses auto-reconnect
-   * and updates connection state to disconnected.
-   */
-  async disconnect(): Promise<this> {
-    this._intentionalClose = true
-    if (this.ws) {
-      this.ws.close()
-    }
-    ;(this.state as any).set('connected', false)
-    return this
-  }
-
-  /** Whether the client is in an error state. */
-  get hasError() {
-    return !!(this.state as any).get('connectionError')
-  }
-
-  /**
-   * Attempt to reconnect if the reconnect option is enabled and we haven't
-   * exceeded maxReconnectAttempts. Uses exponential backoff capped at 30s.
-   */
-  private maybeReconnect() {
-    const opts = this.options as WebSocketClientOptions
-    if (!opts.reconnect) return
-
-    const state = this.state as any
-    const maxAttempts = opts.maxReconnectAttempts ?? Infinity
-    const baseInterval = opts.reconnectInterval ?? 1000
-    const attempts = ((state.get('reconnectAttempts') as number) ?? 0) + 1
-
-    if (attempts > maxAttempts) return
-
-    state.set('reconnectAttempts', attempts)
-    this.emit('reconnecting', attempts)
-
-    const delay = Math.min(baseInterval * Math.pow(2, attempts - 1), 30000)
-    setTimeout(() => {
-      this.connect().catch(() => {})
-    }, delay)
-  }
-}
-
 export default Client;

package/src/clients/civitai/index.ts

@@ -1,8 +1,8 @@
 import {
   Client,
   type ClientOptions,
-  RestClient,
 } from "@soederpop/luca/client";
+import { RestClient } from "../rest";
 import { type ContainerContext } from "@soederpop/luca/container";
 import { isEmpty, maxBy, omitBy } from "lodash-es";
 import { NodeContainer } from "@soederpop/luca/node/container";

package/src/clients/client-template.ts

@@ -2,8 +2,8 @@ import {
   type ClientOptions,
   type ClientsInterface,
   clients,
-  RestClient,
 } from "@soederpop/luca/client";
+import { RestClient } from "./rest";
 import { type ContainerContext } from "@soederpop/luca/container";
 import { z } from 'zod'
 import { ClientStateSchema } from '@soederpop/luca/schemas/base.js'

package/src/clients/comfyui/index.ts

@@ -1,10 +1,10 @@
 import {
   Client,
-  RestClient,
 } from "@soederpop/luca/client";
+import { RestClient } from "../rest";
 import type { ContainerContext } from "@soederpop/luca/container";
 import { z } from 'zod'
-import { ClientStateSchema, ClientOptionsSchema } from '@soederpop/luca/schemas/base.js'
+import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca/schemas/base.js'
 
 declare module "@soederpop/luca/client" {
   interface AvailableClients {
@@ -25,6 +25,16 @@ export const ComfyUIClientOptionsSchema = ClientOptionsSchema.extend({
 export type ComfyUIClientState = z.infer<typeof ComfyUIClientStateSchema>
 export type ComfyUIClientOptions = z.infer<typeof ComfyUIClientOptionsSchema>
 
+export const ComfyUIClientEventsSchema = ClientEventsSchema.extend({
+  execution_start: z.tuple([z.object({ promptId: z.string().describe('The prompt ID that started executing') })]).describe('Emitted when prompt execution begins'),
+  executing: z.tuple([z.object({ node: z.string().describe('The node ID currently executing'), promptId: z.string().describe('The prompt ID') })]).describe('Emitted when a specific node begins executing'),
+  progress: z.tuple([z.object({ node: z.string().describe('The node ID'), value: z.number().describe('Current progress value'), max: z.number().describe('Maximum progress value'), promptId: z.string().describe('The prompt ID') })]).describe('Emitted during node execution with progress updates'),
+  executed: z.tuple([z.object({ node: z.string().describe('The node ID that finished'), output: z.any().describe('The node output data'), promptId: z.string().describe('The prompt ID') })]).describe('Emitted when a node finishes execution'),
+  execution_cached: z.tuple([z.object({ nodes: z.array(z.string()).describe('Array of cached node IDs'), promptId: z.string().describe('The prompt ID') })]).describe('Emitted when nodes are served from cache'),
+  execution_error: z.tuple([z.object({ promptId: z.string().describe('The prompt ID'), exception_message: z.string().optional().describe('Error message') }).passthrough()]).describe('Emitted when prompt execution fails'),
+  execution_complete: z.tuple([z.object({ promptId: z.string().describe('The prompt ID that completed') })]).describe('Emitted when prompt execution finishes successfully'),
+}).describe('ComfyUI client events')
+
 /** Maps a semantic input name to a specific node ID and field */
 export type InputMapping = Record<string, { nodeId: string; field: string }>;
 
@@ -66,6 +76,7 @@ export class ComfyUIClient extends RestClient<ComfyUIClientState, ComfyUIClientO
   static override description = "ComfyUI workflow execution client";
   static override stateSchema = ComfyUIClientStateSchema;
   static override optionsSchema = ComfyUIClientOptionsSchema;
+  static override eventsSchema = ComfyUIClientEventsSchema;
 
   static { Client.register(this, 'comfyui') }
 

package/src/clients/elevenlabs/index.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca/schemas/base.js'
-import { Client, RestClient } from "@soederpop/luca/client";
+import { Client } from "@soederpop/luca/client";
+import { RestClient } from "../rest";
 import type { ContainerContext } from "@soederpop/luca/container";
 import type { AxiosRequestConfig } from 'axios'