@soulcraft/brainy 3.12.0 → 3.14.0

package/dist/types/augmentations.d.ts

@@ -37,7 +37,29 @@ import type { BrainyAugmentation as BA, BaseAugmentation as BaseA, AugmentationC
 export type BrainyAugmentation = BA;
 export type BaseAugmentation = BaseA;
 export type AugmentationContext = AC;
+/**
+ * @deprecated Use BrainyAugmentation from '../augmentations/brainyAugmentation.js' instead
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { IAugmentation } from '@soulcraft/brainy/types/augmentations'
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ */
 export type IAugmentation = BrainyAugmentation;
+/**
+ * @deprecated Augmentation types are now unified under BrainyAugmentation interface
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { AugmentationType } from '@soulcraft/brainy/types/augmentations'
+ * if (augmentation.type === AugmentationType.SENSE) { ... }
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ * // Use the unified BrainyAugmentation interface directly
+ */
 export declare enum AugmentationType {
     SENSE = "sense",
     CONDUIT = "conduit",
@@ -49,23 +71,139 @@ export declare enum AugmentationType {
     WEBSOCKET = "webSocket",
     SYNAPSE = "synapse"
 }
+/**
+ * @deprecated Use BrainyAugmentation interface directly instead of namespace types
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { BrainyAugmentations } from '@soulcraft/brainy/types/augmentations'
+ * class MyAugmentation implements BrainyAugmentations.ISenseAugmentation { ... }
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ * class MyAugmentation implements BrainyAugmentation { ... }
+ */
 export declare namespace BrainyAugmentations {
+    /** @deprecated Use BrainyAugmentation instead */
     type ISenseAugmentation = BrainyAugmentation;
+    /** @deprecated Use BrainyAugmentation instead */
     type IConduitAugmentation = BrainyAugmentation;
+    /** @deprecated Use BrainyAugmentation instead */
     type ICognitionAugmentation = BrainyAugmentation;
+    /** @deprecated Use BrainyAugmentation instead */
     type IMemoryAugmentation = BrainyAugmentation;
+    /** @deprecated Use BrainyAugmentation instead */
     type IPerceptionAugmentation = BrainyAugmentation;
+    /** @deprecated Use BrainyAugmentation instead */
     type IDialogAugmentation = BrainyAugmentation;
+    /** @deprecated Use BrainyAugmentation instead */
     type IActivationAugmentation = BrainyAugmentation;
+    /** @deprecated Use BrainyAugmentation instead */
     type ISynapseAugmentation = BrainyAugmentation;
 }
+/**
+ * @deprecated Use BrainyAugmentation from '../augmentations/brainyAugmentation.js' instead
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { ISenseAugmentation } from '@soulcraft/brainy/types/augmentations'
+ * class MySense implements ISenseAugmentation { ... }
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ * class MySense implements BrainyAugmentation { ... }
+ */
 export type ISenseAugmentation = BrainyAugmentation;
+/**
+ * @deprecated Use BrainyAugmentation from '../augmentations/brainyAugmentation.js' instead
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { IConduitAugmentation } from '@soulcraft/brainy/types/augmentations'
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ */
 export type IConduitAugmentation = BrainyAugmentation;
+/**
+ * @deprecated Use BrainyAugmentation from '../augmentations/brainyAugmentation.js' instead
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { ICognitionAugmentation } from '@soulcraft/brainy/types/augmentations'
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ */
 export type ICognitionAugmentation = BrainyAugmentation;
+/**
+ * @deprecated Use BrainyAugmentation from '../augmentations/brainyAugmentation.js' instead
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { IMemoryAugmentation } from '@soulcraft/brainy/types/augmentations'
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ */
 export type IMemoryAugmentation = BrainyAugmentation;
+/**
+ * @deprecated Use BrainyAugmentation from '../augmentations/brainyAugmentation.js' instead
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { IPerceptionAugmentation } from '@soulcraft/brainy/types/augmentations'
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ */
 export type IPerceptionAugmentation = BrainyAugmentation;
+/**
+ * @deprecated Use BrainyAugmentation from '../augmentations/brainyAugmentation.js' instead
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { IDialogAugmentation } from '@soulcraft/brainy/types/augmentations'
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ */
 export type IDialogAugmentation = BrainyAugmentation;
+/**
+ * @deprecated Use BrainyAugmentation from '../augmentations/brainyAugmentation.js' instead
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { IActivationAugmentation } from '@soulcraft/brainy/types/augmentations'
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ */
 export type IActivationAugmentation = BrainyAugmentation;
+/**
+ * @deprecated Use BrainyAugmentation from '../augmentations/brainyAugmentation.js' instead
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { ISynapseAugmentation } from '@soulcraft/brainy/types/augmentations'
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ */
 export type ISynapseAugmentation = BrainyAugmentation;
+/**
+ * @deprecated WebSocket support is now built into BrainyAugmentation interface
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { IWebSocketSupport } from '@soulcraft/brainy/types/augmentations'
+ * class MyAugmentation implements IWebSocketSupport { ... }
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ * class MyAugmentation implements BrainyAugmentation {
+ *   // WebSocket functionality is now part of the unified interface
+ * }
+ */
 export interface IWebSocketSupport {
 }

package/dist/types/augmentations.js

@@ -4,6 +4,18 @@
  * This file contains only the minimal types needed for augmentations.
  * The main augmentation interfaces are now in augmentations/brainyAugmentation.ts
  */
+/**
+ * @deprecated Augmentation types are now unified under BrainyAugmentation interface
+ *
+ * @example
+ * // ❌ Old way (v2.x):
+ * import { AugmentationType } from '@soulcraft/brainy/types/augmentations'
+ * if (augmentation.type === AugmentationType.SENSE) { ... }
+ *
+ * // ✅ New way (v3.x):
+ * import { BrainyAugmentation } from '@soulcraft/brainy'
+ * // Use the unified BrainyAugmentation interface directly
+ */
 export var AugmentationType;
 (function (AugmentationType) {
     AugmentationType["SENSE"] = "sense";

package/dist/vfs/TreeUtils.d.ts

@@ -0,0 +1,67 @@
+/**
+ * VFS Tree Utilities
+ * Provides safe tree operations that prevent common recursion issues
+ */
+import { VFSEntity } from './types.js';
+export interface TreeNode {
+    name: string;
+    path: string;
+    type: 'file' | 'directory';
+    entityId?: string;
+    children?: TreeNode[];
+    metadata?: any;
+}
+export interface TreeOptions {
+    maxDepth?: number;
+    includeHidden?: boolean;
+    filter?: (node: VFSEntity) => boolean;
+    sort?: 'name' | 'modified' | 'size';
+    expandAll?: boolean;
+}
+/**
+ * Tree utility functions for VFS
+ * These functions ensure proper tree structure without recursion issues
+ */
+export declare class VFSTreeUtils {
+    /**
+     * Build a safe tree structure from VFS entities
+     * Guarantees no directory appears as its own child
+     */
+    static buildTree(entities: VFSEntity[], rootPath?: string, options?: TreeOptions): TreeNode;
+    /**
+     * Get direct children only - guaranteed no self-inclusion
+     */
+    static getDirectChildren(entities: VFSEntity[], parentPath: string): VFSEntity[];
+    /**
+     * Get all descendants (recursive children)
+     */
+    static getDescendants(entities: VFSEntity[], ancestorPath: string, includeAncestor?: boolean): VFSEntity[];
+    /**
+     * Flatten a tree structure back to a list
+     */
+    static flattenTree(node: TreeNode): TreeNode[];
+    /**
+     * Find a node in the tree by path
+     */
+    static findNode(root: TreeNode, targetPath: string): TreeNode | null;
+    /**
+     * Calculate tree statistics
+     */
+    static getTreeStats(node: TreeNode): {
+        totalNodes: number;
+        files: number;
+        directories: number;
+        maxDepth: number;
+        totalSize?: number;
+    };
+    private static getParentPath;
+    private static sortTreeNodes;
+    private static limitDepth;
+    /**
+     * Validate tree structure - ensures no recursion
+     */
+    static validateTree(node: TreeNode, visited?: Set<string>): {
+        valid: boolean;
+        errors: string[];
+    };
+}

package/dist/vfs/TreeUtils.js

@@ -0,0 +1,268 @@
+/**
+ * VFS Tree Utilities
+ * Provides safe tree operations that prevent common recursion issues
+ */
+/**
+ * Tree utility functions for VFS
+ * These functions ensure proper tree structure without recursion issues
+ */
+export class VFSTreeUtils {
+    /**
+     * Build a safe tree structure from VFS entities
+     * Guarantees no directory appears as its own child
+     */
+    static buildTree(entities, rootPath = '/', options = {}) {
+        const pathToEntity = new Map();
+        const pathToNode = new Map();
+        // First pass: index all entities by path
+        for (const entity of entities) {
+            const path = entity.metadata.path;
+            // Critical: Skip if entity IS the root we're building from
+            if (path === rootPath) {
+                continue;
+            }
+            pathToEntity.set(path, entity);
+        }
+        // Create root node
+        const rootNode = {
+            name: rootPath === '/' ? 'root' : rootPath.split('/').pop(),
+            path: rootPath,
+            type: 'directory',
+            children: []
+        };
+        pathToNode.set(rootPath, rootNode);
+        // Second pass: build tree structure
+        const sortedPaths = Array.from(pathToEntity.keys()).sort();
+        for (const path of sortedPaths) {
+            const entity = pathToEntity.get(path);
+            // Apply filter if provided
+            if (options.filter && !options.filter(entity)) {
+                continue;
+            }
+            // Skip hidden files if requested
+            if (!options.includeHidden && entity.metadata.name.startsWith('.')) {
+                continue;
+            }
+            // Create node for this entity
+            const node = {
+                name: entity.metadata.name,
+                path: entity.metadata.path,
+                type: entity.metadata.vfsType === 'directory' ? 'directory' : 'file',
+                entityId: entity.id,
+                metadata: entity.metadata
+            };
+            if (entity.metadata.vfsType === 'directory') {
+                node.children = [];
+            }
+            pathToNode.set(path, node);
+            // Find parent and attach
+            const parentPath = this.getParentPath(path);
+            const parentNode = pathToNode.get(parentPath);
+            if (parentNode && parentNode.children) {
+                parentNode.children.push(node);
+            }
+        }
+        // Sort children if requested
+        if (options.sort) {
+            this.sortTreeNodes(rootNode, options.sort);
+        }
+        // Apply depth limit if specified
+        if (options.maxDepth !== undefined) {
+            this.limitDepth(rootNode, options.maxDepth);
+        }
+        return rootNode;
+    }
+    /**
+     * Get direct children only - guaranteed no self-inclusion
+     */
+    static getDirectChildren(entities, parentPath) {
+        const children = [];
+        const parentDepth = parentPath === '/' ? 0 : parentPath.split('/').length - 1;
+        for (const entity of entities) {
+            const path = entity.metadata.path;
+            // Critical check 1: Skip if this IS the parent
+            if (path === parentPath) {
+                continue;
+            }
+            // Check if entity is a direct child
+            if (path.startsWith(parentPath)) {
+                const relativePath = parentPath === '/'
+                    ? path.substring(1)
+                    : path.substring(parentPath.length + 1);
+                // Direct child has no additional slashes
+                if (!relativePath.includes('/')) {
+                    children.push(entity);
+                }
+            }
+        }
+        return children;
+    }
+    /**
+     * Get all descendants (recursive children)
+     */
+    static getDescendants(entities, ancestorPath, includeAncestor = false) {
+        const descendants = [];
+        for (const entity of entities) {
+            const path = entity.metadata.path;
+            // Include ancestor only if explicitly requested
+            if (path === ancestorPath) {
+                if (includeAncestor) {
+                    descendants.push(entity);
+                }
+                continue;
+            }
+            // Check if entity is under ancestor path
+            const prefix = ancestorPath === '/' ? '/' : ancestorPath + '/';
+            if (path.startsWith(prefix)) {
+                descendants.push(entity);
+            }
+        }
+        return descendants;
+    }
+    /**
+     * Flatten a tree structure back to a list
+     */
+    static flattenTree(node) {
+        const result = [node];
+        if (node.children) {
+            for (const child of node.children) {
+                result.push(...this.flattenTree(child));
+            }
+        }
+        return result;
+    }
+    /**
+     * Find a node in the tree by path
+     */
+    static findNode(root, targetPath) {
+        if (root.path === targetPath) {
+            return root;
+        }
+        if (root.children) {
+            for (const child of root.children) {
+                const found = this.findNode(child, targetPath);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
+    }
+    /**
+     * Calculate tree statistics
+     */
+    static getTreeStats(node) {
+        let stats = {
+            totalNodes: 0,
+            files: 0,
+            directories: 0,
+            maxDepth: 0,
+            totalSize: 0
+        };
+        function traverse(n, depth) {
+            stats.totalNodes++;
+            stats.maxDepth = Math.max(stats.maxDepth, depth);
+            if (n.type === 'file') {
+                stats.files++;
+                if (n.metadata?.size) {
+                    stats.totalSize += n.metadata.size;
+                }
+            }
+            else {
+                stats.directories++;
+            }
+            if (n.children) {
+                for (const child of n.children) {
+                    traverse(child, depth + 1);
+                }
+            }
+        }
+        traverse(node, 0);
+        return stats;
+    }
+    // Helper methods
+    static getParentPath(path) {
+        if (path === '/')
+            return '/';
+        const parts = path.split('/');
+        parts.pop();
+        return parts.length === 1 ? '/' : parts.join('/');
+    }
+    static sortTreeNodes(node, sortBy) {
+        if (!node.children)
+            return;
+        node.children.sort((a, b) => {
+            // Directories first, then files
+            if (a.type !== b.type) {
+                return a.type === 'directory' ? -1 : 1;
+            }
+            switch (sortBy) {
+                case 'name':
+                    return a.name.localeCompare(b.name);
+                case 'modified':
+                    const aTime = a.metadata?.modified || 0;
+                    const bTime = b.metadata?.modified || 0;
+                    return bTime - aTime;
+                case 'size':
+                    const aSize = a.metadata?.size || 0;
+                    const bSize = b.metadata?.size || 0;
+                    return bSize - aSize;
+                default:
+                    return 0;
+            }
+        });
+        // Recursively sort children
+        for (const child of node.children) {
+            this.sortTreeNodes(child, sortBy);
+        }
+    }
+    static limitDepth(node, maxDepth, currentDepth = 0) {
+        if (currentDepth >= maxDepth) {
+            delete node.children;
+            return;
+        }
+        if (node.children) {
+            for (const child of node.children) {
+                this.limitDepth(child, maxDepth, currentDepth + 1);
+            }
+        }
+    }
+    /**
+     * Validate tree structure - ensures no recursion
+     */
+    static validateTree(node, visited = new Set()) {
+        const errors = [];
+        // Check for cycles
+        if (visited.has(node.path)) {
+            errors.push(`Cycle detected at path: ${node.path}`);
+            return { valid: false, errors };
+        }
+        visited.add(node.path);
+        // Check children
+        if (node.children) {
+            const childPaths = new Set();
+            for (const child of node.children) {
+                // Check for duplicate children
+                if (childPaths.has(child.path)) {
+                    errors.push(`Duplicate child path: ${child.path}`);
+                }
+                childPaths.add(child.path);
+                // Check child is not parent
+                if (child.path === node.path) {
+                    errors.push(`Directory contains itself: ${node.path}`);
+                }
+                // Check child is actually under parent
+                if (node.path !== '/' && !child.path.startsWith(node.path + '/')) {
+                    errors.push(`Child ${child.path} not under parent ${node.path}`);
+                }
+                // Recursively validate children
+                const childValidation = this.validateTree(child, new Set(visited));
+                errors.push(...childValidation.errors);
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors
+        };
+    }
+}
+//# sourceMappingURL=TreeUtils.js.map

package/dist/vfs/VirtualFileSystem.d.ts

@@ -52,6 +52,37 @@ export declare class VirtualFileSystem implements IVirtualFileSystem {
      * Delete a file
      */
     unlink(path: string): Promise<void>;
+    /**
+     * Get only direct children of a directory - guaranteed no self-inclusion
+     * This is the SAFE way to get children for building tree UIs
+     */
+    getDirectChildren(path: string): Promise<VFSEntity[]>;
+    /**
+     * Get a properly structured tree for the given path
+     * This prevents recursion issues common when building file explorers
+     */
+    getTreeStructure(path: string, options?: {
+        maxDepth?: number;
+        includeHidden?: boolean;
+        sort?: 'name' | 'modified' | 'size';
+    }): Promise<any>;
+    /**
+     * Get all descendants of a directory (flat list)
+     */
+    getDescendants(path: string, options?: {
+        includeAncestor?: boolean;
+        type?: 'file' | 'directory';
+    }): Promise<VFSEntity[]>;
+    /**
+     * Inspect a path and return structured information
+     * This is the recommended method for file explorers to use
+     */
+    inspect(path: string): Promise<{
+        node: VFSEntity;
+        children: VFSEntity[];
+        parent: VFSEntity | null;
+        stats: VFSStats;
+    }>;
     /**
      * Create a directory
      */

package/dist/vfs/VirtualFileSystem.js

@@ -322,6 +322,116 @@ export class VirtualFileSystem {
         this.triggerWatchers(path, 'rename');
         // Knowledge Layer hooks will be added by augmentation if enabled
     }
+    // ============= Tree Operations (NEW) =============
+    /**
+     * Get only direct children of a directory - guaranteed no self-inclusion
+     * This is the SAFE way to get children for building tree UIs
+     */
+    async getDirectChildren(path) {
+        await this.ensureInitialized();
+        const entityId = await this.pathResolver.resolve(path);
+        const entity = await this.getEntityById(entityId);
+        // Verify it's a directory
+        if (entity.metadata.vfsType !== 'directory') {
+            throw new VFSError(VFSErrorCode.ENOTDIR, `Not a directory: ${path}`, path, 'getDirectChildren');
+        }
+        // Use the safe getChildren from PathResolver
+        const children = await this.pathResolver.getChildren(entityId);
+        // Double-check no self-inclusion (paranoid safety)
+        return children.filter(child => child.metadata.path !== path);
+    }
+    /**
+     * Get a properly structured tree for the given path
+     * This prevents recursion issues common when building file explorers
+     */
+    async getTreeStructure(path, options) {
+        await this.ensureInitialized();
+        const { VFSTreeUtils } = await import('./TreeUtils.js');
+        const entityId = await this.pathResolver.resolve(path);
+        const entity = await this.getEntityById(entityId);
+        if (entity.metadata.vfsType !== 'directory') {
+            throw new VFSError(VFSErrorCode.ENOTDIR, `Not a directory: ${path}`, path, 'getTreeStructure');
+        }
+        // Recursively gather all descendants
+        const allEntities = [];
+        const visited = new Set();
+        const gatherDescendants = async (dirId) => {
+            if (visited.has(dirId))
+                return; // Prevent cycles
+            visited.add(dirId);
+            const children = await this.pathResolver.getChildren(dirId);
+            for (const child of children) {
+                allEntities.push(child);
+                if (child.metadata.vfsType === 'directory') {
+                    await gatherDescendants(child.id);
+                }
+            }
+        };
+        await gatherDescendants(entityId);
+        // Build safe tree structure
+        return VFSTreeUtils.buildTree(allEntities, path, options || {});
+    }
+    /**
+     * Get all descendants of a directory (flat list)
+     */
+    async getDescendants(path, options) {
+        await this.ensureInitialized();
+        const entityId = await this.pathResolver.resolve(path);
+        const entity = await this.getEntityById(entityId);
+        if (entity.metadata.vfsType !== 'directory') {
+            throw new VFSError(VFSErrorCode.ENOTDIR, `Not a directory: ${path}`, path, 'getDescendants');
+        }
+        const descendants = [];
+        if (options?.includeAncestor) {
+            descendants.push(entity);
+        }
+        const visited = new Set();
+        const queue = [entityId];
+        while (queue.length > 0) {
+            const currentId = queue.shift();
+            if (visited.has(currentId))
+                continue;
+            visited.add(currentId);
+            const children = await this.pathResolver.getChildren(currentId);
+            for (const child of children) {
+                // Filter by type if specified
+                if (!options?.type || child.metadata.vfsType === options.type) {
+                    descendants.push(child);
+                }
+                // Add directories to queue for traversal
+                if (child.metadata.vfsType === 'directory') {
+                    queue.push(child.id);
+                }
+            }
+        }
+        return descendants;
+    }
+    /**
+     * Inspect a path and return structured information
+     * This is the recommended method for file explorers to use
+     */
+    async inspect(path) {
+        await this.ensureInitialized();
+        const entityId = await this.pathResolver.resolve(path);
+        const entity = await this.getEntityById(entityId);
+        const stats = await this.stat(path);
+        let children = [];
+        if (entity.metadata.vfsType === 'directory') {
+            children = await this.getDirectChildren(path);
+        }
+        let parent = null;
+        if (path !== '/') {
+            const parentPath = path.substring(0, path.lastIndexOf('/')) || '/';
+            const parentId = await this.pathResolver.resolve(parentPath);
+            parent = await this.getEntityById(parentId);
+        }
+        return {
+            node: entity,
+            children,
+            parent,
+            stats
+        };
+    }
     // ============= Directory Operations =============
     /**
      * Create a directory