@soederpop/luca 0.1.2 → 0.2.1

package/dist/node/features/vault.d.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+import { type ContainerContext } from '../../container.js';
+export declare const VaultStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    secret: z.ZodOptional<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>;
+}, z.core.$loose>;
+export type VaultState = z.infer<typeof VaultStateSchema>;
+export declare const VaultOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    secret: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>, z.ZodString]>>;
+}, z.core.$strip>;
+export type VaultOptions = z.infer<typeof VaultOptionsSchema>;
+/**
+ * The Vault feature provides encryption and decryption capabilities using AES-256-GCM.
+ *
+ * This feature allows you to securely encrypt and decrypt sensitive data using
+ * industry-standard encryption. It manages secret keys and provides a simple
+ * interface for cryptographic operations.
+ *
+ * @example
+ * ```typescript
+ * const vault = container.feature('vault')
+ *
+ * // Encrypt sensitive data
+ * const encrypted = vault.encrypt('sensitive information')
+ * console.log(encrypted) // Base64 encoded encrypted data
+ *
+ * // Decrypt the data
+ * const decrypted = vault.decrypt(encrypted)
+ * console.log(decrypted) // 'sensitive information'
+ * ```
+ *
+ * @extends Feature
+ */
+export declare class Vault extends Feature<VaultState, VaultOptions> {
+    static shortcut: "features.vault";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        secret: z.ZodOptional<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        secret: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>, z.ZodString]>>;
+    }, z.core.$strip>;
+    constructor(options: VaultOptions, context: ContainerContext);
+    /**
+     * Gets the secret key as a base64-encoded string.
+     *
+     * @returns {string | undefined} The secret key encoded as base64, or undefined if no secret is set
+     */
+    get secretText(): string;
+    /**
+     * Gets or generates a secret key for encryption operations.
+     *
+     * @param {object} [options={}] - Options for secret key handling
+     * @param {boolean} [options.refresh=false] - Whether to generate a new secret key
+     * @param {boolean} [options.set=true] - Whether to store the generated key in state
+     * @returns {Buffer} The secret key as a Buffer
+     */
+    secret({ refresh, set }?: {
+        refresh?: boolean | undefined;
+        set?: boolean | undefined;
+    }): Buffer;
+    /**
+     * Decrypts an encrypted payload that was created by the encrypt method.
+     *
+     * @param {string} payload - The encrypted payload to decrypt (base64 encoded with delimiters)
+     * @returns {string} The decrypted plaintext
+     * @throws {Error} Throws an error if decryption fails or the payload is malformed
+     */
+    decrypt(payload: string): string;
+    /**
+     * Encrypts a plaintext string using AES-256-GCM encryption.
+     *
+     * @param {string} payload - The plaintext string to encrypt
+     * @returns {string} The encrypted payload as a base64 encoded string with delimiters
+     */
+    encrypt(payload: string): string;
+    private _encrypt;
+    private _decrypt;
+}
+export default Vault;
+//# sourceMappingURL=vault.d.ts.map

package/dist/node/features/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../../src/node/features/vault.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAE1D,eAAO,MAAM,gBAAgB;;;iBAG3B,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEzD,eAAO,MAAM,kBAAkB;;;;;;iBAG7B,CAAA;AACF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAE7D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,KAAM,SAAQ,OAAO,CAAC,UAAU,EAAE,YAAY,CAAC;IAC1D,OAAgB,QAAQ,EAAG,gBAAgB,CAAS;IACpD,OAAgB,WAAW;;;sBAAmB;IAC9C,OAAgB,aAAa;;;;;;sBAAqB;gBAGtC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,gBAAgB;IAY5D;;;;OAIG;IACH,IAAI,UAAU,WAEb;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAe,EAAE,GAAU,EAAE;;;KAAK,GAAI,MAAM;IAcrD;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM;IAKvB;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM;IAUvB,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,QAAQ;CAGjB;AAED,eAAe,KAAK,CAAA"}

package/dist/node/features/vm.d.ts

@@ -0,0 +1,285 @@
+import { z } from 'zod';
+import vm from 'vm';
+import { Feature } from "../feature.js";
+export declare const VMStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$loose>;
+export type VMState = z.infer<typeof VMStateSchema>;
+export declare const VMOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    context: z.ZodAny;
+}, z.core.$strip>;
+export type VMOptions = z.infer<typeof VMOptionsSchema>;
+/**
+ * The VM feature provides Node.js virtual machine capabilities for executing JavaScript code.
+ *
+ * This feature wraps Node.js's built-in `vm` module to provide secure code execution
+ * in isolated contexts. It's useful for running untrusted code, creating sandboxed
+ * environments, or dynamically executing code with controlled access to variables and modules.
+ *
+ * @example
+ * ```typescript
+ * const vm = container.feature('vm')
+ *
+ * // Execute simple code
+ * const result = vm.run('1 + 2 + 3')
+ * console.log(result) // 6
+ *
+ * // Execute code with custom context
+ * const result2 = vm.run('greeting + " " + name', {
+ *   greeting: 'Hello',
+ *   name: 'World'
+ * })
+ * console.log(result2) // 'Hello World'
+ * ```
+ *
+ * @extends Feature
+ */
+export declare class VM<T extends VMState = VMState, K extends VMOptions = VMOptions> extends Feature<T, K> {
+    static shortcut: "features.vm";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        context: z.ZodAny;
+    }, z.core.$strip>;
+    /** Map of virtual module IDs to their exports, consulted before Node's native require */
+    modules: Map<string, any>;
+    /**
+     * Register a virtual module that will be available to `require()` inside VM-executed code.
+     * Modules registered here take precedence over Node's native resolution.
+     *
+     * @param id - The module specifier (e.g. `'@soederpop/luca'`, `'zod'`)
+     * @param exports - The module's exports object
+     *
+     * @example
+     * ```typescript
+     * const vm = container.feature('vm')
+     * vm.defineModule('@soederpop/luca', { Container, Feature, fs, proc })
+     * vm.defineModule('zod', { z })
+     *
+     * // Now loadModule can resolve these in user code:
+     * // import { Container } from '@soederpop/luca'  → works
+     * ```
+     */
+    defineModule(id: string, exports: any): void;
+    /**
+     * Build a require function that resolves from the virtual modules map first,
+     * falling back to Node's native `createRequire` for everything else.
+     *
+     * @param filePath - The file path to scope native require resolution to
+     * @returns A require function with `.resolve` preserved from the native require
+     */
+    createRequireFor(filePath: string): ((id: string) => any) & {
+        resolve: RequireResolve;
+    };
+    /**
+     * Creates a new VM script from the provided code.
+     *
+     * This method compiles JavaScript code into a VM script that can be executed
+     * multiple times in different contexts. The script is pre-compiled for better
+     * performance when executing the same code repeatedly.
+     *
+     * @param {string} code - The JavaScript code to compile into a script
+     * @param {vm.ScriptOptions} [options] - Options for script compilation
+     * @returns {vm.Script} A compiled VM script ready for execution
+     *
+     * @example
+     * ```typescript
+     * const script = vm.createScript('Math.max(a, b)')
+     *
+     * // Execute the script multiple times with different contexts
+     * const result1 = script.runInContext(vm.createContext({ a: 5, b: 3 }))
+     * const result2 = script.runInContext(vm.createContext({ a: 10, b: 20 }))
+     * ```
+     */
+    createScript(code: string, options?: vm.ScriptOptions): vm.Script;
+    /**
+     * Check whether an object has already been contextified by `vm.createContext()`.
+     *
+     * Useful to avoid double-contextifying when you're not sure if the caller
+     * passed a plain object or an existing context.
+     *
+     * @param ctx - The object to check
+     * @returns True if the object is a VM context
+     *
+     * @example
+     * ```typescript
+     * const ctx = vm.createContext({ x: 1 })
+     * vm.isContext(ctx)   // true
+     * vm.isContext({ x: 1 }) // false
+     * ```
+     */
+    isContext(ctx: unknown): ctx is vm.Context;
+    /**
+     * Create an isolated JavaScript execution context.
+     *
+     * Combines the container's context with any additional variables provided.
+     * If the input is already a VM context, it is returned as-is.
+     *
+     * @param ctx - Additional context variables to include
+     * @returns A VM context ready for script execution
+     *
+     * @example
+     * ```typescript
+     * const context = vm.createContext({ user: { name: 'John' } })
+     * const result = vm.runSync('user.name', context)
+     * ```
+     */
+    createContext(ctx?: any): vm.Context;
+    /**
+     * Executes JavaScript code in a controlled environment.
+     *
+     * This method creates a script from the provided code, sets up an execution context
+     * with the specified variables, and runs the code safely. It handles errors gracefully
+     * and returns either the result or the error object.
+     *
+     * @param {string} code - The JavaScript code to execute
+     * @param {any} [ctx={}] - Context variables to make available to the executing code
+     * @returns {any} The result of the code execution, or an Error object if execution failed
+     *
+     * @example
+     * ```typescript
+     * // Simple calculation
+     * const result = vm.run('2 + 3 * 4')
+     * console.log(result) // 14
+     *
+     * // Using context variables
+     * const greeting = vm.run('`Hello ${name}!`', { name: 'Alice' })
+     * console.log(greeting) // 'Hello Alice!'
+     *
+     * // Array operations
+     * const sum = vm.run('numbers.reduce((a, b) => a + b, 0)', {
+     *   numbers: [1, 2, 3, 4, 5]
+     * })
+     * console.log(sum) // 15
+     *
+     * // Error handling
+     * const error = vm.run('invalidFunction()')
+     * if (error instanceof Error) {
+     *   console.log('Execution failed:', error.message)
+     * }
+     * ```
+     */
+    /**
+     * Wrap code containing top-level `await` in an async IIFE, injecting
+     * `return` before the last expression so the value is not lost.
+     *
+     * If the code does not contain `await`, or is already wrapped in an
+     * async function/arrow, it is returned unchanged.
+     */
+    wrapTopLevelAwait(code: string): string;
+    run<T extends any>(code: string, ctx?: any): Promise<T>;
+    /**
+     * Execute code and capture all console output as structured JSON.
+     *
+     * Returns both the execution result and an array of every `console.*` call
+     * made during execution, each entry recording the method name and arguments.
+     *
+     * @param code - The JavaScript code to execute
+     * @param ctx - Context variables to make available to the executing code
+     * @returns The result, an array of captured console calls, and the context
+     *
+     * @example
+     * ```typescript
+     * const { result, console: calls } = await vm.runCaptured('console.log("hi"); console.warn("oh"); 42')
+     * // result === 42
+     * // calls === [{ method: 'log', args: ['hi'] }, { method: 'warn', args: ['oh'] }]
+     * ```
+     */
+    runCaptured<T extends any>(code: string, ctx?: any): Promise<{
+        result: T;
+        console: Array<{
+            method: string;
+            args: any[];
+        }>;
+        context: vm.Context;
+    }>;
+    /**
+     * Execute JavaScript code synchronously in a controlled environment.
+     *
+     * @param code - The JavaScript code to execute
+     * @param ctx - Context variables to make available to the executing code
+     * @returns The result of the code execution
+     *
+     * @example
+     * ```typescript
+     * const sum = vm.runSync('a + b', { a: 2, b: 3 })
+     * console.log(sum) // 5
+     * ```
+     */
+    runSync<T extends any = any>(code: string, ctx?: any): T;
+    /**
+     * Execute code asynchronously and return both the result and the execution context.
+     *
+     * Unlike `run`, this method also returns the context object, allowing you to inspect
+     * variables set during execution.
+     *
+     * @param code - The JavaScript code to execute
+     * @param ctx - Context variables to make available to the executing code
+     * @returns The execution result and the context object
+     *
+     * @example
+     * ```typescript
+     * const { result, context } = await vm.perform('x = 42; x * 2', { x: 0 })
+     * console.log(result)     // 84
+     * console.log(context.x)  // 42
+     * ```
+     */
+    perform<T extends any>(code: string, ctx?: any): Promise<{
+        result: T;
+        context: vm.Context;
+    }>;
+    /**
+     * Executes JavaScript code synchronously and returns both the result and the execution context.
+     *
+     * Unlike `runSync`, this method also returns the context object, allowing you to inspect
+     * variables set during execution (e.g. `module.exports`). This is the synchronous equivalent
+     * of `perform()`.
+     *
+     * @param {string} code - The JavaScript code to execute
+     * @param {any} [ctx={}] - Context variables to make available to the executing code
+     * @returns {{ result: T, context: vm.Context }} The execution result and the context object
+     *
+     * @example
+     * ```typescript
+     * const { result, context } = vm.performSync(code, {
+     *   exports: {},
+     *   module: { exports: {} },
+     * })
+     * const moduleExports = context.module?.exports || context.exports
+     * ```
+     */
+    performSync<T extends any = any>(code: string, ctx?: any): {
+        result: T;
+        context: vm.Context;
+    };
+    /**
+     * Synchronously loads a JavaScript/TypeScript module from a file path, executing it
+     * in an isolated VM context and returning its exports. The module gets `require`,
+     * `exports`, and `module` globals automatically, plus any additional context you provide.
+     *
+     * @param {string} filePath - Absolute path to the module file to load
+     * @param {any} [ctx={}] - Additional context variables to inject into the module's execution environment
+     * @returns {Record<string, any>} The module's exports (from `module.exports` or `exports`)
+     *
+     * @example
+     * ```typescript
+     * const vm = container.feature('vm')
+     *
+     * // Load a tools module, injecting the container
+     * const tools = vm.loadModule('/path/to/tools.ts', { container, me: assistant })
+     * // tools.myFunction, tools.schemas, etc.
+     * ```
+     */
+    loadModule(filePath: string, ctx?: any): Record<string, any>;
+}
+export default VM;
+//# sourceMappingURL=vm.d.ts.map

package/dist/node/features/vm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vm.d.ts","sourceRoot":"","sources":["../../../src/node/features/vm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,MAAM,IAAI,CAAA;AACnB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,eAAO,MAAM,aAAa;;iBAAgC,CAAA;AAC1D,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEnD,eAAO,MAAM,eAAe;;;;;;iBAG1B,CAAA;AACF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,EAAE,CACb,CAAC,SAAS,OAAO,GAAG,OAAO,EAC3B,CAAC,SAAS,SAAS,GAAG,SAAS,CAC/B,SAAQ,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACrB,OAAgB,QAAQ,EAAG,aAAa,CAAS;IACjD,OAAgB,WAAW;;sBAAgB;IAC3C,OAAgB,aAAa;;;;;;sBAAkB;IAG/C,yFAAyF;IACzF,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAY;IAErC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI;IAI5C;;;;;;OAMG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,GAAG,CAAC,GAAG;QAAE,OAAO,EAAE,cAAc,CAAA;KAAE;IAavF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,aAAa,GAAG,EAAE,CAAC,MAAM;IAMjE;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,EAAE,CAAC,OAAO;IAI1C;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,GAAG,GAAE,GAAQ,GAAG,EAAE,CAAC,OAAO;IAiBxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH;;;;;;OAMG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IA6BjC,GAAG,CAAC,CAAC,SAAS,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,GAAQ,GAAG,OAAO,CAAC,CAAC,CAAC;IAQjE;;;;;;;;;;;;;;;;OAgBG;IACG,WAAW,CAAC,CAAC,SAAS,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,GAAQ,GAAG,OAAO,CAAC;QACrE,MAAM,EAAE,CAAC,CAAA;QACT,OAAO,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,GAAG,EAAE,CAAA;SAAE,CAAC,CAAA;QAC/C,OAAO,EAAE,EAAE,CAAC,OAAO,CAAA;KACpB,CAAC;IA2BF;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,GAAQ,GAAG,CAAC;IAO5D;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CAAC,CAAC,SAAS,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,GAAQ,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,CAAC,CAAC;QAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAA;KAAE,CAAC;IAOtG;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,GAAQ,GAAG;QAAE,MAAM,EAAE,CAAC,CAAC;QAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAA;KAAE;IAOjG;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,GAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CA2BjE;AAED,eAAe,EAAE,CAAA"}

package/dist/node/features/yaml-tree.d.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { Feature } from "../feature.js";
+import { NodeContainer } from "../container.js";
+/**
+ * Zod schema for the YamlTree feature state.
+ * Extends FeatureStateSchema and allows any additional string-keyed properties for tree data.
+ */
+export declare const YamlTreeStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$catchall<z.ZodAny>>;
+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 declare class YamlTree<T extends YamlTreeState = YamlTreeState> extends Feature<T> {
+    /** The shortcut path for accessing this feature */
+    static shortcut: "features.yamlTree";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$catchall<z.ZodAny>>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    /**
+     * 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;
+    }): void;
+    /**
+     * 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;
+     * ```
+     */
+    loadTree(basePath: string, key?: string): Promise<Pick<T, Exclude<keyof T, "enabled">>>;
+    /**
+     * 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(): Pick<T, Exclude<keyof T, "enabled">>;
+}
+export default YamlTree;
+//# sourceMappingURL=yaml-tree.d.ts.map

package/dist/node/features/yaml-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-tree.d.ts","sourceRoot":"","sources":["../../../src/node/features/yaml-tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;8BAA+J,CAAA;AAC/L,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,QAAQ,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IAE/E,mDAAmD;IACnD,OAAgB,QAAQ,EAAG,mBAAmB,CAAS;IACvD,OAAgB,WAAW;;mCAAsB;IACjD,OAAgB,aAAa;;;;;sBAAuB;IAEpD;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,aAAa,GAAG;QAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;KAAE;IAIhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAgC;IA+BtE;;;;;;;;;;;;;;OAcG;IACH,IAAI,IAAI,yCAEP;CACF;AAED,eAAe,QAAQ,CAAA"}

package/dist/node/features/yaml.d.ts

@@ -0,0 +1,127 @@
+import { Feature } from '../feature.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 declare class YAML extends Feature {
+    static shortcut: "features.yaml";
+    static stateSchema: import("zod").ZodObject<{
+        enabled: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$loose>;
+    static optionsSchema: import("zod").ZodObject<{
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        _cacheKey: import("zod").ZodOptional<import("zod").ZodString>;
+        cached: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        enable: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$strip>;
+    /**
+     * 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): void;
+    /**
+     * 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;
+    /**
+     * 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;
+}
+export default YAML;
+//# sourceMappingURL=yaml.d.ts.map

package/dist/node/features/yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../../../src/node/features/yaml.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAEvC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,IAAK,SAAQ,OAAO;IAC/B,OAAgB,QAAQ,EAAG,eAAe,CAAS;IACnD,OAAgB,WAAW;;qCAAqB;IAChD,OAAgB,aAAa;;;;;qCAAuB;IAGpD;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,aAAa;IAI9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,SAAS,CAAC,IAAI,EAAE,GAAG,GAAI,MAAM;IAI7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM,GAAI,CAAC;CAGnD;AAED,eAAe,IAAI,CAAA"}