luca 1.1.2 → 3.0.0

package/src/python/generated.ts

@@ -0,0 +1,227 @@
+// Auto-generated Python bridge script
+// Generated at: 2026-04-10T05:00:55.842Z
+// Source: src/python/bridge.py
+//
+// Do not edit manually. Run: luca build-python-bridge
+
+export const bridgeScript = `#!/usr/bin/env python3
+"""Luca Python Bridge - persistent interactive Python session.
+
+Communicates via JSON lines over stdin/stdout. Each request is a single
+JSON object per line on stdin; each response is a single JSON object per
+line on stdout. User print() output is captured per-execution via
+io.StringIO so it never corrupts the protocol.
+
+Python 3.8+ compatible (stdlib only).
+"""
+import sys
+import json
+import io
+import traceback
+import os
+
+# Persistent namespace shared across all exec/eval calls
+_namespace = {"__builtins__": __builtins__}
+
+
+def setup_sys_path(project_dir):
+    """Insert project_dir and common sub-paths into sys.path."""
+    paths_to_add = [project_dir]
+
+    # src/ layout (PEP 621 / setuptools)
+    src_dir = os.path.join(project_dir, "src")
+    if os.path.isdir(src_dir):
+        paths_to_add.append(src_dir)
+
+    # lib/ layout (less common but exists)
+    lib_dir = os.path.join(project_dir, "lib")
+    if os.path.isdir(lib_dir):
+        paths_to_add.append(lib_dir)
+
+    for p in reversed(paths_to_add):
+        if p not in sys.path:
+            sys.path.insert(0, p)
+
+
+def _safe_serialize(value):
+    """Attempt JSON serialization; fall back to repr()."""
+    try:
+        json.dumps(value, default=str)
+        return value
+    except (TypeError, ValueError, OverflowError):
+        return repr(value)
+
+
+def handle_exec(req):
+    """Execute code in the persistent namespace."""
+    code = req.get("code", "")
+    variables = req.get("variables", {})
+    _namespace.update(variables)
+
+    old_stdout = sys.stdout
+    captured = io.StringIO()
+    sys.stdout = captured
+    try:
+        exec(code, _namespace)
+        sys.stdout = old_stdout
+        return {"ok": True, "stdout": captured.getvalue(), "result": None}
+    except Exception as e:
+        sys.stdout = old_stdout
+        return {
+            "ok": False,
+            "error": str(e),
+            "traceback": traceback.format_exc(),
+            "stdout": captured.getvalue(),
+        }
+
+
+def handle_eval(req):
+    """Evaluate an expression and return its value."""
+    expression = req.get("expression", "")
+
+    old_stdout = sys.stdout
+    captured = io.StringIO()
+    sys.stdout = captured
+    try:
+        result = eval(expression, _namespace)
+        sys.stdout = old_stdout
+        return {
+            "ok": True,
+            "result": _safe_serialize(result),
+            "stdout": captured.getvalue(),
+        }
+    except Exception as e:
+        sys.stdout = old_stdout
+        return {
+            "ok": False,
+            "error": str(e),
+            "traceback": traceback.format_exc(),
+            "stdout": captured.getvalue(),
+        }
+
+
+def handle_import(req):
+    """Import a module into the namespace."""
+    module_name = req.get("module", "")
+    alias = req.get("alias", module_name.split(".")[-1])
+    try:
+        mod = __import__(
+            module_name,
+            fromlist=[module_name.split(".")[-1]] if "." in module_name else [],
+        )
+        _namespace[alias] = mod
+        return {"ok": True, "result": "Imported {} as {}".format(module_name, alias)}
+    except Exception as e:
+        return {
+            "ok": False,
+            "error": str(e),
+            "traceback": traceback.format_exc(),
+        }
+
+
+def handle_call(req):
+    """Call a function by dotted path in the namespace."""
+    func_path = req.get("function", "")
+    args = req.get("args", [])
+    kwargs = req.get("kwargs", {})
+
+    old_stdout = sys.stdout
+    captured = io.StringIO()
+    sys.stdout = captured
+    try:
+        parts = func_path.split(".")
+        obj = _namespace[parts[0]]
+        for part in parts[1:]:
+            obj = getattr(obj, part)
+        result = obj(*args, **kwargs)
+        sys.stdout = old_stdout
+        return {
+            "ok": True,
+            "result": _safe_serialize(result),
+            "stdout": captured.getvalue(),
+        }
+    except Exception as e:
+        sys.stdout = old_stdout
+        return {
+            "ok": False,
+            "error": str(e),
+            "traceback": traceback.format_exc(),
+            "stdout": captured.getvalue(),
+        }
+
+
+def handle_get_locals(req):
+    """Return all non-dunder keys from the namespace."""
+    safe = {}
+    for k, v in _namespace.items():
+        if k.startswith("__"):
+            continue
+        safe[k] = _safe_serialize(v)
+    return {"ok": True, "result": safe}
+
+
+def handle_reset(req):
+    """Clear the namespace."""
+    _namespace.clear()
+    _namespace["__builtins__"] = __builtins__
+    return {"ok": True, "result": "Session reset"}
+
+
+HANDLERS = {
+    "exec": handle_exec,
+    "eval": handle_eval,
+    "import": handle_import,
+    "call": handle_call,
+    "get_locals": handle_get_locals,
+    "reset": handle_reset,
+}
+
+
+def main():
+    # First line from stdin is the init handshake with project_dir
+    init_line = sys.stdin.readline().strip()
+    if init_line:
+        try:
+            init = json.loads(init_line)
+            if "project_dir" in init:
+                setup_sys_path(init["project_dir"])
+        except json.JSONDecodeError:
+            pass
+
+    # Signal ready
+    sys.stdout.write(json.dumps({"ok": True, "type": "ready"}) + "\\n")
+    sys.stdout.flush()
+
+    # Main loop: read JSON commands, execute, respond
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError as e:
+            resp = {"ok": False, "error": "Invalid JSON: {}".format(e)}
+            sys.stdout.write(json.dumps(resp) + "\\n")
+            sys.stdout.flush()
+            continue
+
+        req_id = req.get("id")
+        req_type = req.get("type", "exec")
+        handler = HANDLERS.get(req_type)
+
+        if not handler:
+            resp = {"ok": False, "error": "Unknown request type: {}".format(req_type)}
+        else:
+            resp = handler(req)
+
+        if req_id:
+            resp["id"] = req_id
+
+        sys.stdout.write(json.dumps(resp, default=str) + "\\n")
+        sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()
+`

package/src/react/index.ts

@@ -0,0 +1,175 @@
+import { createContext, useContext, useRef, useState, useEffect, useCallback, useMemo, createElement } from 'react'
+import type { ReactNode } from 'react'
+import type { Container, AvailableFeatures } from '../container'
+import type { Helper } from '../helper'
+import type { StateChangeType } from '../state'
+
+// ── Context & Provider ──────────────────────────────────────────────
+
+const ContainerContext = createContext<Container | null>(null)
+
+function ContainerProvider({ container, children }: { container: Container; children: ReactNode }) {
+  return createElement(ContainerContext.Provider, { value: container }, children)
+}
+
+function useContainer<T extends Container = Container>(): T {
+  const container = useContext(ContainerContext)
+  if (!container) {
+    throw new Error('useContainer must be used within a <ContainerProvider>')
+  }
+  return container as T
+}
+
+// ── State Hooks ─────────────────────────────────────────────────────
+
+type HasState = { state: { current: any; version: number; observe: (cb: (changeType: StateChangeType, key: any, value?: any) => void) => () => void } }
+
+function useContainerState<T extends object = any>(target?: HasState): T {
+  const container = useContext(ContainerContext)
+  const resolved = target ?? container
+  if (!resolved) {
+    throw new Error('useContainerState requires a target or a ContainerProvider')
+  }
+  const [snapshot, setSnapshot] = useState<T>(() => ({ ...resolved.state.current }))
+
+  useEffect(() => {
+    setSnapshot({ ...resolved.state.current })
+    const unsub = resolved.state.observe(() => {
+      setSnapshot({ ...resolved.state.current })
+    })
+    return unsub
+  }, [resolved])
+
+  return snapshot
+}
+
+function useStateValue<V = any>(target: HasState, key: string): V | undefined {
+  const [value, setValue] = useState<V | undefined>(() => target.state.current[key])
+
+  useEffect(() => {
+    setValue(target.state.current[key])
+    const unsub = target.state.observe((_changeType: StateChangeType, changedKey: any, newValue?: any) => {
+      if (changedKey === key) {
+        setValue(newValue as V)
+      }
+    })
+    return unsub
+  }, [target, key])
+
+  return value
+}
+
+function useStateVersion(target?: HasState): number {
+  const container = useContext(ContainerContext)
+  const resolved = target ?? container
+  if (!resolved) {
+    throw new Error('useStateVersion requires a target or a ContainerProvider')
+  }
+  const [version, setVersion] = useState(() => resolved.state.version)
+
+  useEffect(() => {
+    setVersion(resolved.state.version)
+    const unsub = resolved.state.observe(() => {
+      setVersion(resolved.state.version)
+    })
+    return unsub
+  }, [resolved])
+
+  return version
+}
+
+// ── Event Hooks ─────────────────────────────────────────────────────
+
+type HasEvents = { on: (event: string, listener: (...args: any[]) => void) => any; off: (event: string, listener?: (...args: any[]) => void) => any }
+
+function useEvent(target: HasEvents, event: string, handler: (...args: any[]) => void): void {
+  const handlerRef = useRef(handler)
+  handlerRef.current = handler
+
+  useEffect(() => {
+    const listener = (...args: any[]) => handlerRef.current(...args)
+    target.on(event, listener)
+    return () => { target.off(event, listener) }
+  }, [target, event])
+}
+
+function useWaitFor<T = any>(target: HasEvents & { waitFor: (event: string) => Promise<any> }, event: string): { data: T | undefined; pending: boolean; error: Error | undefined } {
+  const [data, setData] = useState<T | undefined>(undefined)
+  const [pending, setPending] = useState(true)
+  const [error, setError] = useState<Error | undefined>(undefined)
+
+  useEffect(() => {
+    let cancelled = false
+    setPending(true)
+    setData(undefined)
+    setError(undefined)
+
+    target.waitFor(event).then(
+      (result) => {
+        if (!cancelled) {
+          setData(result as T)
+          setPending(false)
+        }
+      },
+      (err) => {
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error(String(err)))
+          setPending(false)
+        }
+      }
+    )
+
+    return () => { cancelled = true }
+  }, [target, event])
+
+  return { data, pending, error }
+}
+
+// ── Feature Hook ────────────────────────────────────────────────────
+
+function useFeature<K extends keyof AvailableFeatures>(
+  name: K,
+  options?: ConstructorParameters<AvailableFeatures[K]>[0]
+): InstanceType<AvailableFeatures[K]> {
+  const container = useContainer()
+  return useMemo(
+    () => container.feature(name, options),
+    [container, name]
+  )
+}
+
+// ── Helper State Hook ───────────────────────────────────────────────
+
+function useHelperState<T extends object = any>(helper: Helper): [T, (value: any) => void] {
+  const [snapshot, setSnapshot] = useState<T>(() => ({ ...helper.state.current } as T))
+
+  useEffect(() => {
+    setSnapshot({ ...helper.state.current } as T)
+    const unsub = helper.state.observe(() => {
+      setSnapshot({ ...helper.state.current } as T)
+    })
+    return unsub
+  }, [helper])
+
+  const setState = useCallback(
+    (value: any) => helper.setState(value),
+    [helper]
+  )
+
+  return [snapshot, setState]
+}
+
+// ── Exports ─────────────────────────────────────────────────────────
+
+export {
+  ContainerContext,
+  ContainerProvider,
+  useContainer,
+  useContainerState,
+  useStateValue,
+  useStateVersion,
+  useEvent,
+  useWaitFor,
+  useFeature,
+  useHelperState,
+}

package/src/registry.ts

@@ -0,0 +1,210 @@
+import type { Helper } from './helper.js';
+import type { ContainerContext } from './container.js';
+import { Bus } from './bus.js';
+import { inspect } from 'util';
+
+import { introspect, interceptRegistration } from './introspection/index.js';
+import type { HelperIntrospection } from './introspection/index.js';
+
+export type { HelperIntrospection }
+
+abstract class Registry<T extends Helper> {
+  scope: string = "unspecified"
+
+  baseClass?: new (options: any, context: ContainerContext) => T
+
+  private readonly members! : Map<string, new (options: any, context: ContainerContext) => T>
+
+  private readonly _events! : Bus
+
+  constructor() {
+    Object.defineProperty(this, 'members', { enumerable: false, value: new Map<string, new (options: any, context: ContainerContext) => T>() })
+    Object.defineProperty(this, '_events', { enumerable: false, value: new Bus() })
+    Object.defineProperty(this, 'scope', { enumerable: false })
+    Object.defineProperty(this, 'baseClass', { enumerable: false })
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')]() {
+    const helpers = this.available
+    const methods: string[] = []
+    const getters: string[] = []
+
+    let proto = Object.getPrototypeOf(this)
+    while (proto && proto !== Object.prototype) {
+      for (const k of Object.getOwnPropertyNames(proto)) {
+        if (k === 'constructor' || k.startsWith('_')) continue
+        const desc = Object.getOwnPropertyDescriptor(proto, k)
+        if (!desc) continue
+        if (desc.get && !getters.includes(k)) getters.push(k)
+        else if (typeof desc.value === 'function' && !methods.includes(k)) methods.push(k)
+      }
+      proto = Object.getPrototypeOf(proto)
+    }
+
+    const parts = [`${this.constructor.name} [${this.scope}]`]
+    if (getters.length) parts.push(`  getters: ${getters.sort().join(', ')}`)
+    if (methods.length) parts.push(`  methods: ${methods.sort().map(m => m + '()').join(', ')}`)
+    parts.push(`  registered: ${helpers.join(', ')}`)
+    return parts.join('\n')
+  }
+
+  /**
+   * Lists the keys of all available helpers in this registry.
+  */
+  get available() : string[] {
+    return Array.from(this.members.keys()).map(r => r.replace(`${this.scope}.`, '')).sort()
+  }
+
+  /** 
+   * Register a new helper in this registry.
+   * 
+   * @param id - The id of the helper to register.
+   * @param constructor - The constructor for the helper.
+   * @returns The constructor for the helper.
+  */
+  register(id: string, constructor: new (options: any, context: ContainerContext) => T) {
+    this.members.set(id.replace(`${this.scope}.`, ''), constructor);
+    interceptRegistration(this, constructor)
+    this.emit('helperRegistered', id, constructor)
+    return constructor
+  }
+
+  /**
+   * Remove a helper from this registry.
+   *
+   * @param id - The id of the helper to unregister.
+   * @returns True if the helper was removed, false if it wasn't registered.
+  */
+  unregister(id: string) : boolean {
+    const key = id.replace(`${this.scope}.`, '')
+    return this.members.delete(key)
+  }
+
+  /**
+   * Check if a helper is registered in this registry.
+   * 
+   * @param id - The id of the helper to check.
+   * @returns True if the helper is registered, false otherwise.
+  */
+  has(id: string) : boolean {
+    return this.members.has(id) || this.members.has([this.scope, id].join('.'))
+  }
+
+  /** 
+   * Lookup a helper by id.
+   * 
+   * @param id - The id of the helper to lookup.
+   * @returns The constructor for the helper.
+  */
+  lookup(id: string) : new (options: any, context: ContainerContext) => T {
+    if (!this.members.has(id) && this.members.has([this.scope, id].join('.'))) {
+      id = [this.scope, id].join(".")
+    }
+
+    const Constructor = this.members.get(id);
+
+    if (!Constructor) {
+      const available = this.available
+      const suggestion = available.length > 0
+        ? `\n\nAvailable ${this.scope}: ${available.join(', ')}`
+        : `\n\nNo ${this.scope} are registered. Make sure the module is imported or .use()'d on the container.`
+
+      throw new Error(
+        `${this.scope} "${id}" is not registered.${suggestion}\n\n` +
+        `To fix this, ensure the module that defines "${id}" is imported (e.g. import './${this.scope}/${id}') ` +
+        `or registered on the container (e.g. container.use(${id ? id[0]!.toUpperCase() + id.slice(1) : 'MyHelper'})).`
+      )
+    }
+
+    return Constructor;
+  }
+
+  /** 
+   * View data about the interface for a particular Helper.  Will tell you about the options
+   * to create one, the state it maintains, the methods and properties it has, and the events it emits.
+  */
+  introspect(id: string) : HelperIntrospection | undefined {
+    return introspect(id)
+  }
+ 
+  /** 
+   * Learn about the interface for a particular Helper.  Will tell you about the options
+   * to create one, the state it maintains, the methods and properties it has, and the events it emits.
+   * 
+   * Will return information as a markdown string.
+  */
+  describe(id: string) : string {
+    const Constructor = this.lookup(id) as any
+    return Constructor.introspectAsText()
+  }
+ 
+
+  /**
+   * Returns a condensed overview of all available helpers in this registry.
+   * Shows each helper's name and description, without the full introspection details.
+   *
+   * Use `describe(id)` to get the full details for a specific helper.
+  */
+  describeAll() : string {
+    const sections: string[] = [`# Available ${this.scope}\n`]
+
+    for (const id of this.available) {
+      const Constructor = this.lookup(id) as any
+      const introspection = Constructor.introspect?.()
+      const description = introspection?.description || Constructor.description || 'No description provided'
+      sections.push(`## ${id}\n\n${description}\n`)
+    }
+
+    return sections.join('\n')
+  }
+
+  /** 
+   * Emit an event on the registry's event bus.
+   * 
+   * @param event - The event to emit.
+   * @param args - The arguments to pass to the event listener.
+   * @returns The registry instance.
+  */
+  emit(event: string, ...args: any[]) {
+    this._events.emit(event, ...args)
+    return this
+  }
+
+  /** 
+   * Subscribe to an event on the registry's event bus.
+   * 
+   * @param event - The event to subscribe to.
+   * @param listener - The listener to call when the event is emitted.
+   * @returns The registry instance.
+  */
+  on(event: string, listener: (...args: any[]) => void) {
+    this._events.on(event, listener)
+    return this
+  }
+
+  /** 
+   * Unsubscribe a listener from an event on the registry's event bus.
+   * 
+   * @param event - The event to unsubscribe from.
+   * @param listener - The listener to unsubscribe.
+   * @returns The registry instance.
+  */
+  off(event: string, listener: (...args: any[]) => void) {
+    this._events.off(event, listener)
+    return this
+  }
+
+  /** 
+   * Subscribe to an event on the registry's event bus, but only fire once.
+   * 
+   * @param event - The event to subscribe to.
+   * @param listener - The listener to call when the event is emitted.
+   * @returns The registry instance.
+  */
+  once(event: string, listener: (...args: any[]) => void) {
+      this._events.once(event, listener)
+      return this
+  }
+}
+
+export { Registry }