@grafema/core 0.1.0-alpha.1

package/dist/storage/backends/RFDBServerBackend.js

@@ -0,0 +1,565 @@
+/**
+ * RFDBServerBackend - Graph backend using RFDB server via Unix socket
+ *
+ * Replaces ReginaFlowBackend's direct NAPI binding with socket-based
+ * communication to a shared RFDB server. This allows multiple processes
+ * (MCP server, analysis workers) to share the same graph database.
+ *
+ * Socket path defaults to `{dbPath}/../rfdb.sock` (e.g., .grafema/rfdb.sock),
+ * ensuring each project has its own socket and avoiding conflicts when
+ * multiple MCP instances run simultaneously.
+ *
+ * Usage:
+ *   const backend = new RFDBServerBackend({
+ *     dbPath: '/project/.grafema/graph.rfdb'  // socket will be /project/.grafema/rfdb.sock
+ *   });
+ *   await backend.connect();
+ *   await backend.addNodes([...]);
+ *   await backend.flush();
+ */
+import { RFDBClient } from '@grafema/rfdb-client';
+import { existsSync, unlinkSync } from 'fs';
+import { spawn } from 'child_process';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { setTimeout as sleep } from 'timers/promises';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export class RFDBServerBackend {
+    socketPath;
+    dbPath;
+    client;
+    serverProcess;
+    connected; // Public for compatibility
+    edgeTypes;
+    _cachedNodeCounts;
+    _cachedEdgeCounts;
+    constructor(options = {}) {
+        this.dbPath = options.dbPath;
+        // Default socket path: next to the database in .grafema folder
+        // This ensures each project has its own socket, avoiding conflicts
+        if (options.socketPath) {
+            this.socketPath = options.socketPath;
+        }
+        else if (this.dbPath) {
+            this.socketPath = join(dirname(this.dbPath), 'rfdb.sock');
+        }
+        else {
+            this.socketPath = '/tmp/rfdb.sock'; // fallback, not recommended
+        }
+        this.client = null;
+        this.serverProcess = null;
+        this.connected = false;
+        this.edgeTypes = new Set();
+    }
+    /**
+     * Connect to RFDB server, starting it if necessary
+     */
+    async connect() {
+        if (this.connected)
+            return;
+        // Try to connect first
+        this.client = new RFDBClient(this.socketPath);
+        try {
+            await this.client.connect();
+            // Verify server is responsive
+            await this.client.ping();
+            this.connected = true;
+            console.log(`[RFDBServerBackend] Connected to existing RFDB server at ${this.socketPath}`);
+            return;
+        }
+        catch {
+            // Server not running, need to start it
+            console.log(`[RFDBServerBackend] RFDB server not running, starting...`);
+        }
+        // Start the server
+        await this._startServer();
+        // Connect again
+        this.client = new RFDBClient(this.socketPath);
+        await this.client.connect();
+        await this.client.ping();
+        this.connected = true;
+        console.log(`[RFDBServerBackend] Connected to RFDB server at ${this.socketPath}`);
+    }
+    /**
+     * Alias for connect()
+     */
+    async initialize() {
+        return this.connect();
+    }
+    /**
+     * Start RFDB server process
+     */
+    async _startServer() {
+        if (!this.dbPath) {
+            throw new Error('dbPath required to start RFDB server');
+        }
+        // Find server binary
+        const projectRoot = join(__dirname, '../../../../..');
+        const releaseBinary = join(projectRoot, 'rust-engine/target/release/rfdb-server');
+        const debugBinary = join(projectRoot, 'rust-engine/target/debug/rfdb-server');
+        let binaryPath = existsSync(releaseBinary) ? releaseBinary : debugBinary;
+        if (!existsSync(binaryPath)) {
+            console.log(`[RFDBServerBackend] Server binary not found, building...`);
+            const { execSync } = await import('child_process');
+            execSync('cargo build --bin rfdb-server', {
+                cwd: join(projectRoot, 'rust-engine'),
+                stdio: 'inherit',
+            });
+            binaryPath = debugBinary;
+        }
+        // Remove stale socket
+        if (existsSync(this.socketPath)) {
+            unlinkSync(this.socketPath);
+        }
+        console.log(`[RFDBServerBackend] Starting: ${binaryPath} ${this.dbPath} --socket ${this.socketPath}`);
+        this.serverProcess = spawn(binaryPath, [this.dbPath, '--socket', this.socketPath], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: true, // Allow server to outlive this process
+        });
+        // Don't let server process prevent parent from exiting
+        this.serverProcess.unref();
+        this.serverProcess.stderr?.on('data', (data) => {
+            const msg = data.toString().trim();
+            if (!msg.includes('FLUSH') && !msg.includes('WRITER')) {
+                console.log(`[rfdb-server] ${msg}`);
+            }
+        });
+        this.serverProcess.on('error', (err) => {
+            console.error(`[RFDBServerBackend] Server process error:`, err);
+        });
+        // Wait for socket to appear
+        let attempts = 0;
+        while (!existsSync(this.socketPath) && attempts < 50) {
+            await sleep(100);
+            attempts++;
+        }
+        if (!existsSync(this.socketPath)) {
+            throw new Error(`RFDB server failed to start (socket not created after ${attempts * 100}ms)`);
+        }
+        console.log(`[RFDBServerBackend] Server started on ${this.socketPath}`);
+    }
+    /**
+     * Close connection and stop server if we started it
+     */
+    async close() {
+        if (this.client) {
+            await this.client.close();
+            this.client = null;
+        }
+        this.connected = false;
+        // Kill server process if we started it
+        if (this.serverProcess) {
+            this.serverProcess.kill('SIGTERM');
+            this.serverProcess = null;
+        }
+    }
+    /**
+     * Clear the database
+     */
+    async clear() {
+        if (!this.client)
+            throw new Error('Not connected');
+        await this.client.clear();
+    }
+    /**
+     * Flush data to disk
+     */
+    async flush() {
+        if (!this.client)
+            throw new Error('Not connected');
+        await this.client.flush();
+    }
+    // ===========================================================================
+    // Node Operations
+    // ===========================================================================
+    /**
+     * Add a single node
+     */
+    async addNode(node) {
+        return this.addNodes([node]);
+    }
+    /**
+     * Add multiple nodes
+     */
+    async addNodes(nodes) {
+        if (!this.client)
+            throw new Error('Not connected');
+        if (!nodes.length)
+            return;
+        const wireNodes = nodes.map(n => {
+            // Extract metadata from node
+            const { id, type, nodeType, node_type, name, file, exported, ...rest } = n;
+            return {
+                id: String(id),
+                nodeType: (nodeType || node_type || type || 'UNKNOWN'),
+                name: name || '',
+                file: file || '',
+                exported: exported || false,
+                metadata: JSON.stringify({ originalId: String(id), ...rest }),
+            };
+        });
+        await this.client.addNodes(wireNodes);
+    }
+    /**
+     * Add a single edge
+     */
+    async addEdge(edge) {
+        return this.addEdges([edge]);
+    }
+    /**
+     * Add multiple edges
+     */
+    async addEdges(edges, skipValidation = false) {
+        if (!this.client)
+            throw new Error('Not connected');
+        if (!edges.length)
+            return;
+        // Track edge types
+        for (const e of edges) {
+            const edgeType = e.edgeType || e.edge_type || e.etype || e.type;
+            if (typeof edgeType === 'string')
+                this.edgeTypes.add(edgeType);
+        }
+        const wireEdges = edges.map(e => {
+            const { src, dst, type, edgeType, edge_type, etype, ...rest } = e;
+            return {
+                src: String(src),
+                dst: String(dst),
+                edgeType: (edgeType || edge_type || etype || type || 'UNKNOWN'),
+                // Store original string IDs in metadata for retrieval
+                metadata: JSON.stringify({ _origSrc: String(src), _origDst: String(dst), ...rest }),
+            };
+        });
+        await this.client.addEdges(wireEdges, skipValidation);
+    }
+    /**
+     * Get a node by ID
+     */
+    async getNode(id) {
+        if (!this.client)
+            throw new Error('Not connected');
+        const node = await this.client.getNode(String(id));
+        if (!node)
+            return null;
+        return this._parseNode(node);
+    }
+    /**
+     * Check if node exists
+     */
+    async nodeExists(id) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.nodeExists(id);
+    }
+    /**
+     * Delete a node
+     */
+    async deleteNode(id) {
+        if (!this.client)
+            throw new Error('Not connected');
+        await this.client.deleteNode(id);
+    }
+    /**
+     * Find nodes by attributes
+     */
+    async findByAttr(query) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.findByAttr(query);
+    }
+    /**
+     * Parse a node from wire format to JS format
+     */
+    _parseNode(wireNode) {
+        const metadata = wireNode.metadata ? JSON.parse(wireNode.metadata) : {};
+        // Parse nested JSON strings
+        for (const [key, value] of Object.entries(metadata)) {
+            if (typeof value === 'string' && (value.startsWith('[') || value.startsWith('{'))) {
+                try {
+                    metadata[key] = JSON.parse(value);
+                }
+                catch {
+                    // Not JSON, keep as string
+                }
+            }
+        }
+        const humanId = metadata.originalId || wireNode.id;
+        return {
+            id: humanId,
+            nodeType: wireNode.nodeType,
+            type: wireNode.nodeType,
+            name: wireNode.name,
+            file: wireNode.file,
+            exported: wireNode.exported,
+            ...metadata,
+        };
+    }
+    /**
+     * Async generator for querying nodes
+     */
+    async *queryNodes(query) {
+        if (!this.client)
+            throw new Error('Not connected');
+        // Build query for server
+        const serverQuery = {};
+        if (query.nodeType)
+            serverQuery.nodeType = query.nodeType;
+        if (query.type)
+            serverQuery.nodeType = query.type;
+        if (query.name)
+            serverQuery.name = query.name;
+        if (query.file)
+            serverQuery.file = query.file;
+        // Use findByType if only nodeType specified
+        if (serverQuery.nodeType && Object.keys(serverQuery).length === 1) {
+            const ids = await this.client.findByType(serverQuery.nodeType);
+            for (const id of ids) {
+                const node = await this.getNode(id);
+                if (node)
+                    yield node;
+            }
+            return;
+        }
+        // Otherwise use client's queryNodes
+        for await (const wireNode of this.client.queryNodes(serverQuery)) {
+            yield this._parseNode(wireNode);
+        }
+    }
+    /**
+     * Get ALL nodes matching query (collects from queryNodes into array)
+     */
+    async getAllNodes(query = {}) {
+        const nodes = [];
+        for await (const node of this.queryNodes(query)) {
+            nodes.push(node);
+        }
+        return nodes;
+    }
+    // ===========================================================================
+    // Edge Operations
+    // ===========================================================================
+    /**
+     * Delete an edge
+     */
+    async deleteEdge(src, dst, type) {
+        if (!this.client)
+            throw new Error('Not connected');
+        await this.client.deleteEdge(src, dst, type);
+    }
+    /**
+     * Get all edges
+     */
+    async getAllEdges() {
+        return this.getAllEdgesAsync();
+    }
+    /**
+     * Get all edges (async version)
+     */
+    async getAllEdgesAsync() {
+        if (!this.client)
+            throw new Error('Not connected');
+        const edges = await this.client.getAllEdges();
+        return edges.map(e => {
+            const meta = JSON.parse(e.metadata || '{}');
+            // Use original string IDs if stored, otherwise use numeric IDs
+            const { _origSrc, _origDst, ...rest } = meta;
+            return {
+                src: _origSrc || e.src,
+                dst: _origDst || e.dst,
+                type: e.edgeType,
+                edgeType: e.edgeType,
+                ...rest,
+            };
+        });
+    }
+    /**
+     * Get outgoing edges from a node
+     */
+    async getOutgoingEdges(nodeId, edgeTypes = null) {
+        if (!this.client)
+            throw new Error('Not connected');
+        const edges = await this.client.getOutgoingEdges(nodeId, edgeTypes || undefined);
+        return edges.map(e => {
+            const meta = JSON.parse(e.metadata || '{}');
+            const { _origSrc, _origDst, ...rest } = meta;
+            return {
+                src: _origSrc || e.src,
+                dst: _origDst || e.dst,
+                type: e.edgeType,
+                edgeType: e.edgeType,
+                ...rest,
+            };
+        });
+    }
+    /**
+     * Get incoming edges to a node
+     */
+    async getIncomingEdges(nodeId, edgeTypes = null) {
+        if (!this.client)
+            throw new Error('Not connected');
+        const edges = await this.client.getIncomingEdges(nodeId, edgeTypes || undefined);
+        return edges.map(e => {
+            const meta = JSON.parse(e.metadata || '{}');
+            const { _origSrc, _origDst, ...rest } = meta;
+            return {
+                src: _origSrc || e.src,
+                dst: _origDst || e.dst,
+                type: e.edgeType,
+                edgeType: e.edgeType,
+                ...rest,
+            };
+        });
+    }
+    // ===========================================================================
+    // Graph Traversal
+    // ===========================================================================
+    /**
+     * BFS traversal
+     */
+    async bfs(startIds, maxDepth, edgeTypes) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.bfs(startIds, maxDepth, edgeTypes);
+    }
+    /**
+     * DFS traversal
+     */
+    async dfs(startIds, maxDepth, edgeTypes = []) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.dfs(startIds, maxDepth, edgeTypes);
+    }
+    // ===========================================================================
+    // Statistics
+    // ===========================================================================
+    /**
+     * Get node count
+     */
+    async nodeCount() {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.nodeCount();
+    }
+    /**
+     * Get edge count
+     */
+    async edgeCount() {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.edgeCount();
+    }
+    /**
+     * Get statistics
+     */
+    async getStats() {
+        if (!this.client)
+            throw new Error('Not connected');
+        const nodeCount = await this.client.nodeCount();
+        const edgeCount = await this.client.edgeCount();
+        const nodeCounts = await this.client.countNodesByType();
+        const edgeCounts = await this.client.countEdgesByType();
+        return {
+            nodeCount,
+            edgeCount,
+            nodesByType: nodeCounts,
+            edgesByType: edgeCounts,
+        };
+    }
+    /**
+     * Count nodes by type (sync, returns cached value)
+     */
+    async countNodesByType(_types = null) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.countNodesByType();
+    }
+    /**
+     * Count edges by type
+     */
+    async countEdgesByType(_edgeTypes = null) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.countEdgesByType();
+    }
+    /**
+     * Refresh cached counts (call after analysis)
+     */
+    async refreshCounts() {
+        if (!this.client)
+            throw new Error('Not connected');
+        this._cachedNodeCounts = await this.client.countNodesByType();
+        this._cachedEdgeCounts = await this.client.countEdgesByType();
+    }
+    // ===========================================================================
+    // Datalog Queries
+    // ===========================================================================
+    /**
+     * Check a guarantee (Datalog rule) and return violations
+     */
+    async checkGuarantee(ruleSource) {
+        if (!this.client)
+            throw new Error('Not connected');
+        const violations = await this.client.checkGuarantee(ruleSource);
+        // Convert bindings from {X: "value"} to [{name: "X", value: "value"}]
+        return violations.map(v => ({
+            bindings: Object.entries(v.bindings).map(([name, value]) => ({ name, value }))
+        }));
+    }
+    /**
+     * Load Datalog rules
+     */
+    async datalogLoadRules(source) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return await this.client.datalogLoadRules(source);
+    }
+    /**
+     * Clear Datalog rules
+     */
+    async datalogClearRules() {
+        if (!this.client)
+            throw new Error('Not connected');
+        await this.client.datalogClearRules();
+    }
+    /**
+     * Run a Datalog query
+     */
+    async datalogQuery(query) {
+        if (!this.client)
+            throw new Error('Not connected');
+        const results = await this.client.datalogQuery(query);
+        // Convert bindings from {X: "value"} to [{name: "X", value: "value"}]
+        return results.map(r => ({
+            bindings: Object.entries(r.bindings).map(([name, value]) => ({ name, value }))
+        }));
+    }
+    // ===========================================================================
+    // Export/Import
+    // ===========================================================================
+    /**
+     * Export graph (for tests)
+     */
+    async export() {
+        const nodes = await this.getAllNodes();
+        const edges = await this.getAllEdgesAsync();
+        return {
+            nodes: nodes,
+            edges: edges,
+        };
+    }
+    /**
+     * Find nodes by predicate (for compatibility)
+     */
+    async findNodes(predicate) {
+        const allNodes = await this.getAllNodes();
+        return allNodes.filter(predicate);
+    }
+    // ===========================================================================
+    // Graph property (for compatibility)
+    // ===========================================================================
+    get graph() {
+        return this;
+    }
+}
+export default RFDBServerBackend;

package/dist/storage/backends/typeValidation.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Type Validation Utilities
+ *
+ * Levenshtein distance and typo detection for node/edge types.
+ * Extracted from ReginaFlowBackend for use in multiple contexts.
+ */
+export interface TypoCheckResult {
+    isTooSimilar: boolean;
+    similarTo: string | null;
+}
+/**
+ * Levenshtein distance for typo detection
+ */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Check if a type is too similar to any existing known type (possible typo)
+ */
+export declare function checkTypoAgainstKnownTypes(newType: string): TypoCheckResult;
+/**
+ * Reset KNOWN_NODE_TYPES to initial state (for testing)
+ */
+export declare function resetKnownNodeTypes(): void;
+/**
+ * Get current known node types (for testing/debugging)
+ */
+export declare function getKnownNodeTypes(): Set<string>;
+/**
+ * Check if an edge type is too similar to any existing known edge type (possible typo)
+ */
+export declare function checkTypoAgainstKnownEdgeTypes(newType: string): TypoCheckResult;
+/**
+ * Reset KNOWN_EDGE_TYPES to initial state (for testing)
+ */
+export declare function resetKnownEdgeTypes(): void;
+/**
+ * Get current known edge types (for testing/debugging)
+ */
+export declare function getKnownEdgeTypes(): Set<string>;
+/**
+ * Add a new node type to the known types set
+ */
+export declare function addKnownNodeType(nodeType: string): void;
+/**
+ * Add a new edge type to the known types set
+ */
+export declare function addKnownEdgeType(edgeType: string): void;
+//# sourceMappingURL=typeValidation.d.ts.map

package/dist/storage/backends/typeValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeValidation.d.ts","sourceRoot":"","sources":["../../../src/storage/backends/typeValidation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA+CH,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAcxD;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAS3E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,GAAG,CAAC,MAAM,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAS/E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,GAAG,CAAC,MAAM,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEvD"}