@soulcraft/brainy 3.9.0 → 3.10.0

package/dist/vfs/KnowledgeAugmentation.js

@@ -0,0 +1,146 @@
+/**
+ * Knowledge Augmentation
+ *
+ * Main orchestrator for the Knowledge Layer that coordinates all knowledge systems
+ * and enhances the VFS with intelligent capabilities
+ */
+import crypto from 'crypto';
+import { EventRecorder } from './EventRecorder.js';
+import { SemanticVersioning } from './SemanticVersioning.js';
+import { PersistentEntitySystem } from './PersistentEntitySystem.js';
+import { ConceptSystem } from './ConceptSystem.js';
+import { GitBridge } from './GitBridge.js';
+export class KnowledgeAugmentation {
+    constructor(config) {
+        this.enabled = false;
+        this.config = config;
+    }
+    /**
+     * Initialize the Knowledge Augmentation with Brainy instance
+     */
+    async init(brain, vfs) {
+        this.brain = brain;
+        this.vfs = vfs;
+        if (!this.config.enabled) {
+            return;
+        }
+        // Initialize sub-systems
+        if (this.config.eventRecording?.enabled) {
+            this.eventRecorder = new EventRecorder(this.brain);
+        }
+        if (this.config.semanticVersioning?.enabled !== false) {
+            this.semanticVersioning = new SemanticVersioning(this.brain);
+        }
+        if (this.config.entitySystem?.enabled !== false) {
+            this.entitySystem = new PersistentEntitySystem(this.brain);
+        }
+        if (this.config.conceptSystem?.enabled !== false) {
+            this.conceptSystem = new ConceptSystem(this.brain);
+        }
+        if (this.config.gitBridge?.enabled !== false) {
+            this.gitBridge = new GitBridge(this.brain, this.vfs);
+        }
+        this.enabled = true;
+    }
+    /**
+     * Enable the Knowledge Augmentation
+     */
+    async enable() {
+        if (!this.brain || !this.vfs) {
+            throw new Error('Knowledge augmentation not initialized. Call init() first.');
+        }
+        this.enabled = true;
+        // Enhance VFS with knowledge methods
+        this.enhanceVFS();
+    }
+    /**
+     * Disable the Knowledge Augmentation
+     */
+    async disable() {
+        this.enabled = false;
+        // Remove VFS enhancements if any were added
+        // For now, just mark as disabled
+    }
+    /**
+     * Check if the knowledge augmentation is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Get the EventRecorder instance
+     */
+    getEventRecorder() {
+        return this.eventRecorder;
+    }
+    /**
+     * Get the SemanticVersioning instance
+     */
+    getSemanticVersioning() {
+        return this.semanticVersioning;
+    }
+    /**
+     * Get the PersistentEntitySystem instance
+     */
+    getEntitySystem() {
+        return this.entitySystem;
+    }
+    /**
+     * Get the ConceptSystem instance
+     */
+    getConceptSystem() {
+        return this.conceptSystem;
+    }
+    /**
+     * Get the GitBridge instance
+     */
+    getGitBridge() {
+        return this.gitBridge;
+    }
+    /**
+     * Record a file event (called by VFS)
+     */
+    async recordEvent(type, path, metadata) {
+        if (!this.enabled || !this.eventRecorder)
+            return;
+        await this.eventRecorder.recordEvent({
+            id: crypto.randomUUID(),
+            timestamp: Date.now(),
+            type,
+            path,
+            metadata
+        });
+    }
+    /**
+     * Create a semantic version (called by VFS)
+     */
+    async createVersion(path, content) {
+        if (!this.enabled || !this.semanticVersioning)
+            return;
+        await this.semanticVersioning.createVersion(path, content);
+    }
+    /**
+     * Extract entities from content (called by VFS)
+     */
+    async extractEntities(path, content) {
+        if (!this.enabled || !this.entitySystem)
+            return;
+        await this.entitySystem.extractEntities(content, { sourcePath: path });
+    }
+    /**
+     * Extract concepts from content (called by VFS)
+     */
+    async extractConcepts(path, content) {
+        if (!this.enabled || !this.conceptSystem)
+            return;
+        await this.conceptSystem.extractConcepts(content, { sourcePath: path });
+    }
+    /**
+     * Enhance the VFS with knowledge methods
+     */
+    enhanceVFS() {
+        // For now, the VFS calls the knowledge methods directly
+        // In the future, we could add methods to the VFS prototype
+    }
+}
+//# sourceMappingURL=KnowledgeAugmentation.js.map

package/dist/vfs/KnowledgeLayer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Knowledge Layer for VFS
+ *
+ * This is the REAL integration that makes VFS intelligent.
+ * It wraps VFS operations and adds Knowledge Layer processing.
+ */
+import { VirtualFileSystem } from './VirtualFileSystem.js';
+import { Brainy } from '../brainy.js';
+export declare class KnowledgeLayer {
+    private vfs;
+    private brain;
+    private eventRecorder;
+    private semanticVersioning;
+    private entitySystem;
+    private conceptSystem;
+    private gitBridge;
+    private enabled;
+    constructor(vfs: VirtualFileSystem, brain: Brainy);
+    /**
+     * Enable Knowledge Layer by wrapping VFS methods
+     */
+    enable(): Promise<void>;
+    /**
+     * Add Knowledge Layer query methods to VFS
+     */
+    private addKnowledgeMethods;
+    /**
+     * Disable Knowledge Layer
+     */
+    disable(): Promise<void>;
+}
+/**
+ * Enable Knowledge Layer on a VFS instance
+ */
+export declare function enableKnowledgeLayer(vfs: VirtualFileSystem, brain: Brainy): Promise<KnowledgeLayer>;

package/dist/vfs/KnowledgeLayer.js

@@ -0,0 +1,443 @@
+/**
+ * Knowledge Layer for VFS
+ *
+ * This is the REAL integration that makes VFS intelligent.
+ * It wraps VFS operations and adds Knowledge Layer processing.
+ */
+import { EventRecorder } from './EventRecorder.js';
+import { SemanticVersioning } from './SemanticVersioning.js';
+import { PersistentEntitySystem } from './PersistentEntitySystem.js';
+import { ConceptSystem } from './ConceptSystem.js';
+import { GitBridge } from './GitBridge.js';
+export class KnowledgeLayer {
+    constructor(vfs, brain) {
+        this.vfs = vfs;
+        this.brain = brain;
+        this.enabled = false;
+        // Initialize all Knowledge Layer components
+        this.eventRecorder = new EventRecorder(brain);
+        this.semanticVersioning = new SemanticVersioning(brain);
+        this.entitySystem = new PersistentEntitySystem(brain);
+        this.conceptSystem = new ConceptSystem(brain);
+        this.gitBridge = new GitBridge(vfs, brain);
+    }
+    /**
+     * Enable Knowledge Layer by wrapping VFS methods
+     */
+    async enable() {
+        if (this.enabled)
+            return;
+        this.enabled = true;
+        // Save original methods
+        const originalWriteFile = this.vfs.writeFile.bind(this.vfs);
+        const originalUnlink = this.vfs.unlink.bind(this.vfs);
+        const originalRename = this.vfs.rename.bind(this.vfs);
+        const originalMkdir = this.vfs.mkdir.bind(this.vfs);
+        const originalRmdir = this.vfs.rmdir.bind(this.vfs);
+        // Wrap writeFile to add intelligence
+        this.vfs.writeFile = async (path, data, options) => {
+            // Call original VFS method first
+            const result = await originalWriteFile(path, data, options);
+            // Process in background (non-blocking)
+            setImmediate(async () => {
+                try {
+                    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
+                    // 1. Record the event
+                    await this.eventRecorder.recordEvent({
+                        type: 'write',
+                        path,
+                        content: buffer,
+                        size: buffer.length,
+                        author: options?.author || 'system'
+                    });
+                    // 2. Check for semantic versioning
+                    try {
+                        const existingContent = await this.vfs.readFile(path).catch(() => null);
+                        if (existingContent) {
+                            const shouldVersion = await this.semanticVersioning.shouldVersion(existingContent, buffer);
+                            if (shouldVersion) {
+                                await this.semanticVersioning.createVersion(path, buffer, {
+                                    message: options?.message || 'Automatic semantic version'
+                                });
+                            }
+                        }
+                    }
+                    catch (err) {
+                        console.debug('Versioning check failed:', err);
+                    }
+                    // 3. Extract entities
+                    if (options?.extractEntities !== false) {
+                        await this.entitySystem.extractEntities(path, buffer);
+                    }
+                    // 4. Extract concepts
+                    if (options?.extractConcepts !== false) {
+                        await this.conceptSystem.extractAndLinkConcepts(path, buffer);
+                    }
+                }
+                catch (error) {
+                    console.debug('Knowledge Layer processing error:', error);
+                }
+            });
+            return result;
+        };
+        // Wrap unlink to record deletion
+        this.vfs.unlink = async (path) => {
+            const result = await originalUnlink(path);
+            setImmediate(async () => {
+                await this.eventRecorder.recordEvent({
+                    type: 'delete',
+                    path,
+                    author: 'system'
+                });
+            });
+            return result;
+        };
+        // Wrap rename to track moves
+        this.vfs.rename = async (oldPath, newPath) => {
+            const result = await originalRename(oldPath, newPath);
+            setImmediate(async () => {
+                await this.eventRecorder.recordEvent({
+                    type: 'rename',
+                    path: oldPath,
+                    metadata: { newPath },
+                    author: 'system'
+                });
+            });
+            return result;
+        };
+        // Wrap mkdir to track directory creation
+        this.vfs.mkdir = async (path, options) => {
+            const result = await originalMkdir(path, options);
+            setImmediate(async () => {
+                await this.eventRecorder.recordEvent({
+                    type: 'mkdir',
+                    path,
+                    author: 'system'
+                });
+            });
+            return result;
+        };
+        // Wrap rmdir to track directory deletion
+        this.vfs.rmdir = async (path, options) => {
+            const result = await originalRmdir(path, options);
+            setImmediate(async () => {
+                await this.eventRecorder.recordEvent({
+                    type: 'rmdir',
+                    path,
+                    author: 'system'
+                });
+            });
+            return result;
+        };
+        // Add Knowledge Layer methods to VFS
+        this.addKnowledgeMethods();
+        console.log('✨ Knowledge Layer enabled on VFS');
+    }
+    /**
+     * Add Knowledge Layer query methods to VFS
+     */
+    addKnowledgeMethods() {
+        // Event history
+        this.vfs.getHistory = async (path, options) => {
+            return await this.eventRecorder.getHistory(path, options);
+        };
+        this.vfs.reconstructAtTime = async (path, timestamp) => {
+            return await this.eventRecorder.reconstructFileAtTime(path, timestamp);
+        };
+        // Semantic versioning
+        this.vfs.getVersions = async (path) => {
+            return await this.semanticVersioning.getVersions(path);
+        };
+        this.vfs.getVersion = async (path, versionId) => {
+            return await this.semanticVersioning.getVersion(path, versionId);
+        };
+        this.vfs.restoreVersion = async (path, versionId) => {
+            const content = await this.semanticVersioning.getVersion(path, versionId);
+            if (content) {
+                await this.vfs.writeFile(path, content);
+            }
+        };
+        // Entity system
+        this.vfs.createEntity = async (config) => {
+            return await this.entitySystem.createEntity(config);
+        };
+        this.vfs.findEntity = async (query) => {
+            return await this.entitySystem.findEntity(query);
+        };
+        this.vfs.getEntityEvolution = async (entityId) => {
+            return await this.entitySystem.getEvolution(entityId);
+        };
+        // Concept system
+        this.vfs.createConcept = async (config) => {
+            return await this.conceptSystem.createConcept(config);
+        };
+        this.vfs.findConcepts = async (query) => {
+            return await this.conceptSystem.findConcepts(query);
+        };
+        this.vfs.getConceptGraph = async (options) => {
+            return await this.conceptSystem.getConceptGraph(options);
+        };
+        // Git bridge
+        this.vfs.exportToGit = async (vfsPath, gitPath) => {
+            return await this.gitBridge.exportToGit(vfsPath, gitPath);
+        };
+        this.vfs.importFromGit = async (gitPath, vfsPath) => {
+            return await this.gitBridge.importFromGit(gitPath, vfsPath);
+        };
+        // Temporal coupling
+        this.vfs.findTemporalCoupling = async (path, windowMs) => {
+            return await this.eventRecorder.findTemporalCoupling(path, windowMs);
+        };
+        // Entity convenience methods that wrap Brainy's core API
+        this.vfs.linkEntities = async (fromEntity, toEntity, relationship) => {
+            // Handle both entity IDs and entity objects
+            const fromId = typeof fromEntity === 'string' ? fromEntity : fromEntity.id;
+            const toId = typeof toEntity === 'string' ? toEntity : toEntity.id;
+            // Use brain.relate to create the relationship
+            return await this.brain.relate({
+                from: fromId,
+                to: toId,
+                type: relationship // VerbType or string
+            });
+        };
+        // Find where an entity appears across files
+        this.vfs.findEntityOccurrences = async (entityId) => {
+            const occurrences = [];
+            // Search for files that contain references to this entity
+            // First, get all relationships where this entity is involved
+            const relations = await this.brain.getRelations({ from: entityId });
+            const toRelations = await this.brain.getRelations({ to: entityId });
+            // Find file entities that relate to this entity
+            for (const rel of [...relations, ...toRelations]) {
+                try {
+                    // Check if the related entity is a file
+                    const relatedId = rel.from === entityId ? rel.to : rel.from;
+                    const entity = await this.brain.get(relatedId);
+                    if (entity?.metadata?.vfsType === 'file' && entity?.metadata?.path) {
+                        occurrences.push({
+                            path: entity.metadata.path,
+                            context: entity.data ? entity.data.toString().substring(0, 200) : undefined
+                        });
+                    }
+                }
+                catch (error) {
+                    // Entity might not exist, continue
+                }
+            }
+            // Also search for files that mention the entity name in their content
+            const entityData = await this.brain.get(entityId);
+            if (entityData?.metadata?.name) {
+                const searchResults = await this.brain.find({
+                    query: entityData.metadata.name,
+                    where: { vfsType: 'file' },
+                    limit: 20
+                });
+                for (const result of searchResults) {
+                    if (result.entity?.metadata?.path && !occurrences.some(o => o.path === result.entity.metadata.path)) {
+                        occurrences.push({
+                            path: result.entity.metadata.path,
+                            context: result.entity.data ? result.entity.data.toString().substring(0, 200) : undefined
+                        });
+                    }
+                }
+            }
+            return occurrences;
+        };
+        // Update an entity (convenience wrapper)
+        this.vfs.updateEntity = async (entityId, updates) => {
+            // Get current entity from brain
+            const currentEntity = await this.brain.get(entityId);
+            if (!currentEntity) {
+                throw new Error(`Entity ${entityId} not found`);
+            }
+            // Merge updates
+            const updatedMetadata = {
+                ...currentEntity.metadata,
+                ...updates,
+                lastUpdated: Date.now(),
+                version: (currentEntity.metadata?.version || 0) + 1
+            };
+            // Update via brain
+            await this.brain.update({
+                id: entityId,
+                data: JSON.stringify(updatedMetadata),
+                metadata: updatedMetadata
+            });
+            return entityId;
+        };
+        // Get entity graph (convenience wrapper)
+        this.vfs.getEntityGraph = async (entityId, options) => {
+            const depth = options?.depth || 2;
+            const graph = { nodes: new Map(), edges: [] };
+            const visited = new Set();
+            const traverse = async (id, currentDepth) => {
+                if (visited.has(id) || currentDepth > depth)
+                    return;
+                visited.add(id);
+                // Add node
+                const entity = await this.brain.get(id);
+                if (entity) {
+                    graph.nodes.set(id, entity);
+                }
+                // Get relationships
+                const relations = await this.brain.getRelations({ from: id });
+                const toRelations = await this.brain.getRelations({ to: id });
+                for (const rel of [...relations, ...toRelations]) {
+                    graph.edges.push(rel);
+                    // Traverse connected nodes
+                    if (currentDepth < depth) {
+                        const nextId = rel.from === id ? rel.to : rel.from;
+                        await traverse(nextId, currentDepth + 1);
+                    }
+                }
+            };
+            await traverse(entityId, 0);
+            return {
+                nodes: Array.from(graph.nodes.values()),
+                edges: graph.edges
+            };
+        };
+        // List all entities of a specific type
+        this.vfs.listEntities = async (query) => {
+            return await this.entitySystem.findEntity(query || {});
+        };
+        // Find files by concept
+        this.vfs.findByConcept = async (conceptName) => {
+            const paths = [];
+            // First find the concept
+            const concepts = await this.conceptSystem.findConcepts({ name: conceptName });
+            if (concepts.length === 0) {
+                return paths;
+            }
+            const concept = concepts[0];
+            // Search for files that contain concept keywords
+            const searchTerms = [conceptName, ...(concept.keywords || [])].join(' ');
+            const searchResults = await this.brain.find({
+                query: searchTerms,
+                where: { vfsType: 'file' },
+                limit: 50
+            });
+            // Get unique paths
+            const pathSet = new Set();
+            for (const result of searchResults) {
+                if (result.entity?.metadata?.path) {
+                    pathSet.add(result.entity.metadata.path);
+                }
+            }
+            // Also check concept manifestations if stored
+            if (concept.manifestations) {
+                for (const manifestation of concept.manifestations) {
+                    if (manifestation.filePath) {
+                        pathSet.add(manifestation.filePath);
+                    }
+                }
+            }
+            return Array.from(pathSet);
+        };
+        // Get timeline of events
+        this.vfs.getTimeline = async (options) => {
+            const fromTime = options?.from ? new Date(options.from).getTime() : Date.now() - 30 * 24 * 60 * 60 * 1000; // 30 days ago
+            const toTime = options?.to ? new Date(options.to).getTime() : Date.now();
+            const limit = options?.limit || 100;
+            // Get events from event recorder
+            const events = await this.eventRecorder.getEvents({
+                since: fromTime,
+                until: toTime,
+                types: options?.types,
+                limit
+            });
+            // Transform to timeline format
+            return events.map(event => ({
+                timestamp: new Date(event.timestamp),
+                type: event.type,
+                path: event.path,
+                user: event.author,
+                description: `${event.type} ${event.path}${event.oldPath ? ` (from ${event.oldPath})` : ''}`
+            }));
+        };
+        // Get collaboration history for a file
+        this.vfs.getCollaborationHistory = async (path) => {
+            // Get all events for this path
+            const history = await this.eventRecorder.getHistory(path, { limit: 100 });
+            return history.map(event => ({
+                user: event.author || 'system',
+                timestamp: new Date(event.timestamp),
+                action: event.type,
+                size: event.size
+            }));
+        };
+        // Export to markdown format
+        this.vfs.exportToMarkdown = async (path) => {
+            const markdown = [];
+            const traverse = async (currentPath, depth = 0) => {
+                const indent = '  '.repeat(depth);
+                try {
+                    const stats = await this.vfs.stat(currentPath);
+                    if (stats.isDirectory()) {
+                        // Add directory header
+                        const name = currentPath.split('/').pop() || currentPath;
+                        markdown.push(`${indent}## ${name}/`);
+                        markdown.push('');
+                        // List and traverse children
+                        const children = await this.vfs.readdir(currentPath);
+                        for (const child of children.sort()) {
+                            const childPath = currentPath === '/' ? `/${child}` : `${currentPath}/${child}`;
+                            await traverse(childPath, depth + 1);
+                        }
+                    }
+                    else {
+                        // Add file content
+                        const name = currentPath.split('/').pop() || currentPath;
+                        const extension = name.split('.').pop() || 'txt';
+                        try {
+                            const content = await this.vfs.readFile(currentPath);
+                            const textContent = content.toString('utf8');
+                            markdown.push(`${indent}### ${name}`);
+                            markdown.push('');
+                            // Add code block for code files
+                            if (['js', 'ts', 'jsx', 'tsx', 'py', 'java', 'cpp', 'go', 'rs', 'json'].includes(extension)) {
+                                markdown.push(`${indent}\`\`\`${extension}`);
+                                markdown.push(textContent.split('\n').map(line => `${indent}${line}`).join('\n'));
+                                markdown.push(`${indent}\`\`\``);
+                            }
+                            else if (extension === 'md') {
+                                // Include markdown directly
+                                markdown.push(textContent);
+                            }
+                            else {
+                                // Plain text in quotes
+                                markdown.push(`${indent}> ${textContent.split('\n').join(`\n${indent}> `)}`);
+                            }
+                            markdown.push('');
+                        }
+                        catch (error) {
+                            markdown.push(`${indent}*Binary or unreadable file*`);
+                            markdown.push('');
+                        }
+                    }
+                }
+                catch (error) {
+                    // Skip inaccessible paths
+                }
+            };
+            await traverse(path);
+            return markdown.join('\n');
+        };
+    }
+    /**
+     * Disable Knowledge Layer
+     */
+    async disable() {
+        // Would restore original methods here
+        this.enabled = false;
+    }
+}
+/**
+ * Enable Knowledge Layer on a VFS instance
+ */
+export async function enableKnowledgeLayer(vfs, brain) {
+    const knowledgeLayer = new KnowledgeLayer(vfs, brain);
+    await knowledgeLayer.enable();
+    return knowledgeLayer;
+}
+//# sourceMappingURL=KnowledgeLayer.js.map