luca 2.0.0 → 3.0.2

package/src/node/features/yaml-tree.ts

@@ -0,0 +1,148 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { Feature } from "../feature.js";
+import { NodeContainer } from "../container.js";
+import { camelCase, omit, set } from 'lodash-es'
+
+/**
+ * Zod schema for the YamlTree feature state.
+ * Extends FeatureStateSchema and allows any additional string-keyed properties for tree data.
+ */
+export const YamlTreeStateSchema = FeatureStateSchema.extend({}).catchall(z.any()).describe('State schema for the YamlTree feature, stores loaded YAML tree data as arbitrary key-value pairs')
+export type YamlTreeState = z.infer<typeof YamlTreeStateSchema>
+
+/**
+ * YamlTree Feature - A powerful YAML file tree loader and processor
+ * 
+ * This feature provides functionality to recursively load YAML files from a directory structure
+ * and build a hierarchical tree representation. It automatically processes file paths to create
+ * a nested object structure where file paths become object property paths.
+ * 
+ * **Key Features:**
+ * - Recursive YAML file discovery in directory trees
+ * - Automatic path-to-property mapping using camelCase conversion
+ * - Integration with FileManager for efficient file operations
+ * - State-based tree storage and retrieval
+ * - Support for both .yml and .yaml file extensions
+ * 
+ * @example
+ * ```typescript
+ * const yamlTree = container.feature('yamlTree', { enable: true });
+ * await yamlTree.loadTree('config', 'appConfig');
+ * const configData = yamlTree.tree.appConfig;
+ * ```
+ * 
+ * @template T - The state type, defaults to YamlTreeState
+ * @extends {Feature<T>}
+ */
+export class YamlTree<T extends YamlTreeState = YamlTreeState> extends Feature<T> {
+  static { Feature.register(this, 'yamlTree') }
+  /** The shortcut path for accessing this feature */
+  static override shortcut = "features.yamlTree" as const
+  static override stateSchema = YamlTreeStateSchema
+  static override optionsSchema = FeatureOptionsSchema
+
+  /**
+   * Attaches the YamlTree feature to a NodeContainer instance.
+   * Registers the feature and creates an auto-enabled instance.
+   * 
+   * @param container - The NodeContainer to attach to
+   * @returns The container for method chaining
+   */
+  static attach(container: NodeContainer & { yamlTree?: YamlTree }) {
+    container.yamlTree = container.feature("yamlTree", { enable: true });
+  }
+
+  /**
+   * Loads a tree of YAML files from the specified base path and stores them in state.
+   * 
+   * This method recursively scans the provided directory for YAML files (.yml and .yaml),
+   * processes their content, and builds a hierarchical object structure. File paths are
+   * converted to camelCase property names, and the resulting tree is stored in the feature's state.
+   * 
+   * **Path Processing:**
+   * - Removes the base path prefix from file paths
+   * - Converts directory/file names to camelCase
+   * - Creates nested objects based on directory structure
+   * - Removes file extensions (.yml/.yaml)
+   * 
+   * **Example:**
+   * ```
+   * config/
+   *   database/
+   *     production.yml  -> tree.config.database.production
+   *     staging.yml     -> tree.config.database.staging
+   *   api/
+   *     endpoints.yaml  -> tree.config.api.endpoints
+   * ```
+   * 
+   * @param basePath - The root directory path to scan for YAML files
+   * @param key - The key to store the tree under in state (defaults to first segment of basePath)
+   * @returns Promise resolving to the complete tree object
+   * 
+   * @throws {Error} When FileManager fails to start or files cannot be read
+   * 
+   * @example
+   * ```typescript
+   * // Load all YAML files from 'config' directory into state.config
+   * await yamlTree.loadTree('config');
+   * 
+   * // Load with custom key
+   * await yamlTree.loadTree('app/settings', 'appSettings');
+   * 
+   * // Access the loaded data
+   * const dbConfig = yamlTree.tree.config.database.production;
+   * ```
+   */
+  async loadTree(basePath: string, key: string = basePath.split('/')[0]!  ) {
+    const { container } = this;
+    const yamlFeature = container.feature("yaml");
+    const fileManager = container.feature("fileManager")
+    const fileSystem = container.feature("fs");
+
+    await fileManager.start()
+
+    // Use the FileManager to find all YAML files in the tree.
+    const yamlFiles = fileManager.matchFiles([
+      `${basePath}/**/*.yml`, 
+      `${basePath}/**/*.yaml`
+    ]);
+
+    const tree : any = {}
+
+    for (const file of yamlFiles.filter(Boolean)) {
+      if(file?.relativePath) {
+        const fileContent = fileSystem.readFile(file.relativePath);
+        const fileData = yamlFeature.parse(String(fileContent));
+        const path = file.relativePath.replace(/\.ya?ml$/, "").replace(basePath + "/", "").split("/").filter(v => v?.length).map(p => camelCase(p));
+        set(tree, path, fileData)
+      }
+    }
+
+    // @ts-ignore-next-line
+    this.setState({ ...this.tree, [key]: tree })
+    
+    return this.tree 
+  }
+
+  /**
+   * Gets the current tree data, excluding the 'enabled' state property.
+   * 
+   * Returns a clean copy of the tree data without internal state management properties.
+   * This provides access to only the YAML tree data that has been loaded.
+   * 
+   * @returns The tree object containing all loaded YAML data, organized by keys
+   * 
+   * @example
+   * ```typescript
+   * await yamlTree.loadTree('config');
+   * const allTrees = yamlTree.tree;
+   * // Returns: { config: { database: { ... }, api: { ... } } }
+   * ```
+   */
+  get tree() {
+    return omit(this.state.current, 'enabled')
+  }
+}
+
+export default YamlTree

package/src/node/features/yaml.ts

@@ -0,0 +1,133 @@
+import * as yaml from 'js-yaml'
+import { Feature } from '../feature.js'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { NodeContainer } from '../container.js'
+
+/**
+ * The YAML feature provides utilities for parsing and stringifying YAML data.
+ * 
+ * This feature wraps the js-yaml library to provide convenient methods for
+ * converting between YAML strings and JavaScript objects. It's automatically
+ * attached to Node containers for easy access.
+ * 
+ * @example
+ * ```typescript
+ * const yamlFeature = container.feature('yaml')
+ * 
+ * // Parse YAML string to object
+ * const config = yamlFeature.parse(`
+ *   name: MyApp
+ *   version: 1.0.0
+ *   settings:
+ *     debug: true
+ * `)
+ * 
+ * // Convert object to YAML string
+ * const yamlString = yamlFeature.stringify(config)
+ * console.log(yamlString)
+ * ```
+ * 
+ * @extends Feature
+ */
+export class YAML extends Feature {
+  static override shortcut = 'features.yaml' as const
+  static override stateSchema = FeatureStateSchema
+  static override optionsSchema = FeatureOptionsSchema
+  static { Feature.register(this, 'yaml') }
+
+  /**
+   * Automatically attaches the YAML feature to Node containers.
+   * 
+   * This static method ensures the YAML feature is automatically available
+   * on Node containers without needing manual registration.
+   * 
+   * @param {NodeContainer} c - The Node container to attach to
+   */
+  static attach(c: NodeContainer) {
+    c.feature('yaml', { enable: true })  
+  }
+  
+  /**
+   * Converts a JavaScript object to a YAML string.
+   * 
+   * This method serializes JavaScript data structures into YAML format,
+   * which is human-readable and commonly used for configuration files.
+   * 
+   * @param {any} data - The data to convert to YAML format
+   * @returns {string} The YAML string representation of the data
+   * 
+   * @example
+   * ```typescript
+   * const config = {
+   *   name: 'MyApp',
+   *   version: '1.0.0',
+   *   settings: {
+   *     debug: true,
+   *     ports: [3000, 3001]
+   *   }
+   * }
+   * 
+   * const yamlString = yaml.stringify(config)
+   * console.log(yamlString)
+   * // Output:
+   * // name: MyApp
+   * // version: 1.0.0
+   * // settings:
+   * //   debug: true
+   * //   ports:
+   * //     - 3000
+   * //     - 3001
+   * ```
+   */
+  stringify(data: any) : string {
+    return yaml.dump(data)
+  }
+
+  /**
+   * Parses a YAML string into a JavaScript object.
+   * 
+   * This method deserializes YAML content into JavaScript data structures.
+   * It supports all standard YAML features including nested objects, arrays,
+   * and various data types.
+   * 
+   * @template T - The expected type of the parsed object
+   * @param {string} yamlStr - The YAML string to parse
+   * @returns {T} The parsed JavaScript object
+   * @throws {Error} Throws an error if the YAML string is malformed
+   * 
+   * @example
+   * ```typescript
+   * const yamlContent = `
+   *   name: MyApp
+   *   version: 1.0.0
+   *   settings:
+   *     debug: true
+   *     ports:
+   *       - 3000
+   *       - 3001
+   * `
+   * 
+   * // Parse with type inference
+   * const config = yaml.parse(yamlContent)
+   * console.log(config.name) // 'MyApp'
+   * 
+   * // Parse with explicit typing
+   * interface AppConfig {
+   *   name: string
+   *   version: string
+   *   settings: {
+   *     debug: boolean
+   *     ports: number[]
+   *   }
+   * }
+   * 
+   * const typedConfig = yaml.parse<AppConfig>(yamlContent)
+   * console.log(typedConfig.settings.ports) // [3000, 3001]
+   * ```
+   */
+  parse<T extends object = any>(yamlStr: string) : T {
+    return yaml.load(yamlStr) as T
+  }
+}
+
+export default YAML

package/src/node.ts

@@ -0,0 +1,76 @@
+import { NodeContainer, Feature } from './node/container'
+import './introspection/generated.node'
+
+export * from './node/container'
+
+const container = new NodeContainer()
+
+const { servers, features, clients } = container
+
+export default container as NodeContainer
+
+/**
+ * Returns the singleton container instance.
+ * LLMs love to hallucinate this function — so we provide it, but warn.
+ * If you need a separate container, use `container.subcontainer()`.
+ */
+export function createContainer() {
+  console.warn(
+    '[luca] createContainer() is unnecessary — import the default export instead.\n' +
+    '       `import container from "luca"`\n' +
+    '       For a separate instance, use container.subcontainer().'
+  )
+  return container
+}
+
+// Convenient pre-enabled feature instances
+export const ui = container.feature('ui')
+export const fs = container.feature('fs')
+export const vm = container.feature('vm')
+export const proc = container.feature('proc')
+
+// Registries
+export { servers, features, clients }
+
+// Core classes
+export { Feature }
+export { Container } from './container'
+export { Helper } from './helper'
+export { Bus } from './bus'
+export { State } from './state'
+export { Registry } from './registry'
+
+// Helper subclasses & registries
+export { Client, ClientsRegistry } from './client'
+export { RestClient } from './clients/rest'
+export { GraphClient } from './clients/graph'
+export { WebSocketClient } from './clients/websocket'
+export { Command, CommandsRegistry, commands, graftModule } from './command'
+export { Endpoint, EndpointsRegistry, endpoints } from './endpoint'
+export { Selector, SelectorsRegistry, selectors } from './selector'
+export { Server, ServersRegistry } from './server'
+export { FeaturesRegistry } from './feature'
+
+// Concrete server implementations
+export { ExpressServer } from './servers/express'
+export { WebsocketServer } from './servers/socket'
+
+// Types
+export type { ContainerContext, ContainerArgv, Plugin, Extension } from './container'
+export type { AvailableClients } from './client'
+export type { AvailableCommands, CommandHandler } from './command'
+export type { AvailableEndpoints, EndpointContext } from './endpoint'
+export type { AvailableSelectors, SelectorsInterface, SelectorRunResult, SimpleSelector } from './selector'
+export type { AvailableFeatures, FeatureOptions, FeatureState } from './feature'
+export type { NodeContainer, NodeFeatures } from './node/container'
+export type { AvailableServers, StartOptions, ServersInterface } from './server'
+export type { HelperState, HelperOptions } from './helper'
+export type { Entity } from './entity'
+export type { EventMap } from './bus'
+export type { SetStateValue, StateChangeType } from './state'
+
+// Zod — so consumer code can `import { z } from 'luca'`
+export { z } from 'zod'
+
+// Schemas
+export * from './schemas/base'

package/src/python/bridge.py

@@ -0,0 +1,220 @@
+#!/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()