@imayuur/contexthub-core 1.0.0

package/dist/memory-storage.js

@@ -0,0 +1,419 @@
+"use strict";
+/**
+ * MemoryStorage — Secure, encrypted file-based storage for ContextHub
+ *
+ * Security features:
+ * - AES-256-GCM encryption at rest for all JSON data files
+ * - Atomic writes (write to .tmp, then rename) to prevent corruption
+ * - In-process mutex to prevent race conditions on concurrent access
+ * - File size limits to prevent OOM/DoS
+ * - Entry count caps with automatic archival
+ * - Secure file permissions (0600 for files, 0700 for directories)
+ * - Automatic migration from plaintext to encrypted format
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStorage = void 0;
+const crypto = __importStar(require("crypto"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const security_1 = require("./security");
+// Simple in-process async mutex for file locking
+class Mutex {
+    constructor() {
+        this.queue = [];
+        this.locked = false;
+    }
+    async acquire() {
+        return new Promise((resolve) => {
+            const tryAcquire = () => {
+                if (!this.locked) {
+                    this.locked = true;
+                    resolve(() => this.release());
+                }
+                else {
+                    this.queue.push(tryAcquire);
+                }
+            };
+            tryAcquire();
+        });
+    }
+    release() {
+        this.locked = false;
+        const next = this.queue.shift();
+        if (next)
+            next();
+    }
+}
+class MemoryStorage {
+    constructor(repoPath) {
+        this.repoPath = repoPath;
+        this.contexthubPath = path.join(repoPath, '.contexthub');
+        this.sessionsPath = path.join(this.contexthubPath, 'sessions.json');
+        this.memoriesPath = path.join(this.contexthubPath, 'memories.json');
+        this.projectMetadataPath = path.join(this.contexthubPath, 'project-metadata.json');
+        this.security = new security_1.SecurityManager(repoPath);
+        this.mutex = new Mutex();
+        // Create .contexthub directory if it doesn't exist (with secure permissions)
+        if (!fs.existsSync(this.contexthubPath)) {
+            fs.mkdirSync(this.contexthubPath, { recursive: true });
+            this.security.setSecurePermissions(this.contexthubPath, true);
+        }
+        // Initialize files if they don't exist
+        this.initFile(this.sessionsPath, []);
+        this.initFile(this.memoriesPath, []);
+        this.initFile(this.projectMetadataPath, null);
+    }
+    // ── File I/O (Encrypted + Atomic) ──────────────────────────────────────
+    initFile(filePath, defaultContent) {
+        if (!fs.existsSync(filePath)) {
+            this.writeJSONFileSync(filePath, defaultContent);
+        }
+    }
+    /**
+     * Read and decrypt a JSON file from disk.
+     * Handles both encrypted and plaintext formats (for migration).
+     */
+    readJSONFile(filePath) {
+        // Check file size before reading
+        this.security.checkFileSize(filePath);
+        const raw = fs.readFileSync(filePath, 'utf8').trim();
+        // Empty file — return default
+        if (raw.length === 0) {
+            return [];
+        }
+        // Try parsing as plaintext JSON first (for migration / backwards compat)
+        if (raw.startsWith('[') || raw.startsWith('{') || raw === 'null') {
+            try {
+                const parsed = JSON.parse(raw);
+                // Auto-migrate: re-write as encrypted
+                this.writeJSONFileSync(filePath, parsed);
+                return parsed;
+            }
+            catch {
+                // Not valid JSON — try decrypting
+            }
+        }
+        // Decrypt
+        try {
+            const decrypted = this.security.decrypt(raw);
+            return JSON.parse(decrypted);
+        }
+        catch (e) {
+            throw new Error(`Failed to read data file (may be corrupted): ${path.basename(filePath)}`);
+        }
+    }
+    /**
+     * Encrypt and write JSON data to disk using atomic write.
+     * Writes to a .tmp file first, then renames — prevents corruption on crash.
+     */
+    writeJSONFileSync(filePath, data) {
+        const jsonStr = JSON.stringify(data, null, 2);
+        const encrypted = this.security.encrypt(jsonStr);
+        const tmpPath = filePath + `.tmp.${crypto.randomBytes(4).toString('hex')}`;
+        try {
+            fs.writeFileSync(tmpPath, encrypted, { mode: 0o600 });
+            fs.renameSync(tmpPath, filePath);
+        }
+        catch (e) {
+            // Clean up temp file on error
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch { /* ignore */ }
+            throw e;
+        }
+    }
+    // ── Session Management ─────────────────────────────────────────────────
+    async createSession(agent, metadata = {}) {
+        const release = await this.mutex.acquire();
+        try {
+            const id = crypto.randomUUID();
+            const startTime = Date.now();
+            // Sanitize inputs
+            const sanitizedAgent = this.security.sanitizeInput(agent, 100);
+            const session = {
+                id,
+                repoPath: this.repoPath,
+                startTime,
+                agent: sanitizedAgent,
+                metadata
+            };
+            const sessions = this.readJSONFile(this.sessionsPath);
+            sessions.push(session);
+            // Cap sessions at max entries
+            const capped = sessions.length > this.security.maxMemoryEntries
+                ? sessions.slice(-this.security.maxMemoryEntries)
+                : sessions;
+            this.writeJSONFileSync(this.sessionsPath, capped);
+            return id;
+        }
+        finally {
+            release();
+        }
+    }
+    async endSession(sessionId) {
+        const release = await this.mutex.acquire();
+        try {
+            const sessions = this.readJSONFile(this.sessionsPath);
+            const sessionIndex = sessions.findIndex(s => s.id === sessionId);
+            if (sessionIndex !== -1) {
+                sessions[sessionIndex].endTime = Date.now();
+                this.writeJSONFileSync(this.sessionsPath, sessions);
+            }
+        }
+        finally {
+            release();
+        }
+    }
+    async getSession(sessionId) {
+        const sessions = this.readJSONFile(this.sessionsPath);
+        return sessions.find(s => s.id === sessionId) || null;
+    }
+    async getSessions(limit) {
+        let sessions = this.readJSONFile(this.sessionsPath);
+        sessions.sort((a, b) => b.startTime - a.startTime); // descending by startTime
+        if (limit !== undefined) {
+            const safeLimit = this.security.validateLimit(limit);
+            sessions = sessions.slice(0, safeLimit);
+        }
+        return sessions;
+    }
+    // ── Memory Management ──────────────────────────────────────────────────
+    calculateJaccard(str1, str2) {
+        const words1 = str1.toLowerCase().split(/\W+/).filter(w => w.length > 2);
+        const words2 = str2.toLowerCase().split(/\W+/).filter(w => w.length > 2);
+        if (words1.length === 0 && words2.length === 0)
+            return 1;
+        if (words1.length === 0 || words2.length === 0)
+            return 0;
+        const set1 = new Set(words1);
+        const set2 = new Set(words2);
+        const intersection = new Set([...set1].filter(x => set2.has(x)));
+        const union = new Set([...set1, ...set2]);
+        return intersection.size / union.size;
+    }
+    async saveMemory(memory) {
+        const release = await this.mutex.acquire();
+        try {
+            const id = crypto.randomUUID();
+            // Sanitize content — redact sensitive data
+            let content = this.security.sanitizeInput(memory.content);
+            if (this.security.isSensitive(content)) {
+                content = this.security.redactSensitive(content);
+            }
+            // Validate type
+            const validType = this.security.validateMemoryType(memory.type || 'manual');
+            // Sanitize tags
+            const sanitizedTags = (memory.tags || [])
+                .map(tag => this.security.sanitizeInput(tag, 100))
+                .filter(tag => tag.length > 0)
+                .slice(0, 20); // Max 20 tags
+            const memoryWithId = {
+                ...memory,
+                id,
+                content,
+                type: validType,
+                tags: sanitizedTags,
+                relatedPaths: memory.relatedPaths ? this.security.validateRelatedPaths(memory.relatedPaths) : undefined,
+                relatedSymbols: memory.relatedSymbols ? this.security.validateRelatedSymbols(memory.relatedSymbols) : undefined,
+                commitHash: memory.commitHash ? this.security.validateCommitHash(memory.commitHash) : undefined,
+                branch: memory.branch ? this.security.sanitizeInput(String(memory.branch), 100) : undefined,
+            };
+            let memories = this.readJSONFile(this.memoriesPath);
+            // Duplicate detection
+            if (memory.sessionId) {
+                const sessionMemories = memories.filter(m => m.sessionId === memory.sessionId).slice(-20);
+                for (const sm of sessionMemories) {
+                    const jaccard = this.calculateJaccard(sm.content, content);
+                    if (jaccard > 0.9) {
+                        return sm.id; // Return existing ID if it's a near duplicate
+                    }
+                }
+            }
+            memories.push(memoryWithId);
+            // Cap at max entries — archive old ones
+            const capped = memories.length > this.security.maxMemoryEntries
+                ? memories.slice(-this.security.maxMemoryEntries)
+                : memories;
+            this.writeJSONFileSync(this.memoriesPath, capped);
+            return id;
+        }
+        finally {
+            release();
+        }
+    }
+    async getMemory(id) {
+        const memories = this.readJSONFile(this.memoriesPath);
+        return memories.find(mem => mem.id === id) || null;
+    }
+    async searchMemories(options) {
+        let memories = this.readJSONFile(this.memoriesPath);
+        if (options.sessionId) {
+            memories = memories.filter(mem => mem.sessionId === options.sessionId);
+        }
+        if (options.type) {
+            memories = memories.filter(mem => mem.type === options.type);
+        }
+        if (options.tags && options.tags.length > 0) {
+            const tags = options.tags;
+            memories = memories.filter(mem => tags.some(tag => mem.tags.includes(tag)));
+        }
+        memories.sort((a, b) => b.timestamp - a.timestamp); // descending by timestamp
+        if (options.offset !== undefined) {
+            const safeOffset = Math.max(0, Math.floor(options.offset));
+            memories = memories.slice(safeOffset);
+        }
+        if (options.limit !== undefined) {
+            const safeLimit = this.security.validateLimit(options.limit);
+            memories = memories.slice(0, safeLimit);
+        }
+        return memories;
+    }
+    // ── Project Metadata ───────────────────────────────────────────────────
+    async saveProjectMetadata(metadata) {
+        const release = await this.mutex.acquire();
+        try {
+            this.writeJSONFileSync(this.projectMetadataPath, metadata);
+        }
+        finally {
+            release();
+        }
+    }
+    async getProjectMetadata() {
+        try {
+            return this.readJSONFile(this.projectMetadataPath);
+        }
+        catch (e) {
+            return null;
+        }
+    }
+    // ── Maintenance & Compaction ───────────────────────────────────────────
+    async archiveOldMemories(maxAgeDays) {
+        const release = await this.mutex.acquire();
+        try {
+            const memories = this.readJSONFile(this.memoriesPath);
+            const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+            const toKeep = [];
+            const toArchive = [];
+            for (const m of memories) {
+                if (m.timestamp < cutoff && !m.tags.includes('pinned')) {
+                    toArchive.push(m);
+                }
+                else {
+                    toKeep.push(m);
+                }
+            }
+            if (toArchive.length > 0) {
+                this.writeJSONFileSync(this.memoriesPath, toKeep);
+                // Write to archive file
+                const archiveDir = path.join(this.contexthubPath, 'archive');
+                if (!fs.existsSync(archiveDir)) {
+                    fs.mkdirSync(archiveDir, { recursive: true });
+                    this.security.setSecurePermissions(archiveDir, true);
+                }
+                const archivePath = path.join(archiveDir, `memories-${Date.now()}.json`);
+                this.writeJSONFileSync(archivePath, toArchive);
+            }
+            return toArchive.length;
+        }
+        finally {
+            release();
+        }
+    }
+    async compactMemories() {
+        const release = await this.mutex.acquire();
+        try {
+            let memories = this.readJSONFile(this.memoriesPath);
+            let mergedCount = 0;
+            // We will group by sessionId and then look for adjacent prompt -> response
+            const sessionMap = new Map();
+            for (const m of memories) {
+                if (!sessionMap.has(m.sessionId))
+                    sessionMap.set(m.sessionId, []);
+                sessionMap.get(m.sessionId).push(m);
+            }
+            const newMemories = [];
+            for (const [sessionId, sessionMems] of sessionMap.entries()) {
+                // Sort chronologically to find adjacent pairs easily
+                sessionMems.sort((a, b) => a.timestamp - b.timestamp);
+                let i = 0;
+                while (i < sessionMems.length) {
+                    const m1 = sessionMems[i];
+                    const m2 = i + 1 < sessionMems.length ? sessionMems[i + 1] : null;
+                    if (m2 &&
+                        m1.type === 'prompt' &&
+                        m2.type === 'response' &&
+                        !m1.tags.includes('pinned') &&
+                        !m2.tags.includes('pinned')) {
+                        // Merge them
+                        const mergedContent = `Prompt: ${m1.content}\n\nResponse: ${m2.content}`;
+                        const mergedTags = Array.from(new Set([...m1.tags, ...m2.tags]));
+                        const mergedPaths = Array.from(new Set([...(m1.relatedPaths || []), ...(m2.relatedPaths || [])])).slice(0, 20);
+                        newMemories.push({
+                            id: crypto.randomUUID(),
+                            sessionId: sessionId,
+                            type: 'summary',
+                            content: mergedContent,
+                            timestamp: m2.timestamp,
+                            tags: mergedTags,
+                            relatedPaths: mergedPaths.length > 0 ? mergedPaths : undefined,
+                            commitHash: m2.commitHash || m1.commitHash,
+                            branch: m2.branch || m1.branch
+                        });
+                        mergedCount++;
+                        i += 2; // skip both
+                    }
+                    else {
+                        newMemories.push(m1);
+                        i++;
+                    }
+                }
+            }
+            if (mergedCount > 0) {
+                this.writeJSONFileSync(this.memoriesPath, newMemories);
+            }
+            return mergedCount;
+        }
+        finally {
+            release();
+        }
+    }
+    // ── Cleanup ────────────────────────────────────────────────────────────
+    async close() {
+        // Nothing to clean up
+    }
+}
+exports.MemoryStorage = MemoryStorage;

package/dist/query-pipeline.d.ts

@@ -0,0 +1,20 @@
+import type { ContextHubCore } from './index';
+import type { MemoryEntry } from '@imayuur/contexthub-shared-types';
+export interface UnifiedQueryResult {
+    answerSummary: string;
+    memories: MemoryEntry[];
+    codeHits: Array<{
+        path: string;
+        symbol?: string;
+        reason: string;
+    }>;
+    gitHits?: any[];
+    trace?: {
+        hops: Array<{
+            type: string;
+            id: string;
+            label: string;
+        }>;
+    };
+}
+export declare function runUnifiedQuery(query: string, limit: number, core: ContextHubCore, vectorEngine: any, graphManager: any, gitIntegration: any): Promise<UnifiedQueryResult>;

package/dist/query-pipeline.js

@@ -0,0 +1,182 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runUnifiedQuery = runUnifiedQuery;
+const path = __importStar(require("path"));
+async function runUnifiedQuery(query, limit, core, vectorEngine, graphManager, gitIntegration) {
+    const security = core['storage']['security']; // Access security manager safely
+    const sanitizedQuery = security.sanitizeQuery(query);
+    const safeLimit = security.validateLimit(limit, 1, 100);
+    const queryLower = sanitizedQuery.toLowerCase();
+    function rrfMerge(lists, k = 60) {
+        const scores = new Map();
+        for (const list of lists) {
+            list.forEach((item, i) => {
+                scores.set(item.id, (scores.get(item.id) || 0) + 1 / (k + i + 1));
+            });
+        }
+        return scores;
+    }
+    // 1. Code Graph Traversal
+    const codeHits = [];
+    let trace = undefined;
+    try {
+        if (graphManager) {
+            const graph = await graphManager.loadGraph();
+            const referencedNodes = [];
+            for (const node of graph.nodes) {
+                if (node.kind === 'file') {
+                    const basename = path.basename(node.path).toLowerCase();
+                    if (queryLower.includes(basename)) {
+                        referencedNodes.push(node);
+                    }
+                }
+                else if (node.kind === 'symbol' && node.name) {
+                    const symLower = node.name.toLowerCase();
+                    const regex = new RegExp('\\b' + symLower + '\\b');
+                    if (regex.test(queryLower)) {
+                        referencedNodes.push(node);
+                    }
+                }
+            }
+            for (const node of referencedNodes) {
+                codeHits.push({
+                    path: node.path,
+                    symbol: node.kind === 'symbol' ? node.name : undefined,
+                    reason: `Directly mentioned in query`
+                });
+                const related = await graphManager.getRelatedSymbols(node.id, 5);
+                for (const rel of related) {
+                    if (!codeHits.some(h => h.path === rel.path && h.symbol === rel.name)) {
+                        codeHits.push({
+                            path: rel.path,
+                            symbol: rel.name,
+                            reason: `Related symbol to '${node.name || path.basename(node.path)}' in graph`
+                        });
+                    }
+                }
+            }
+            if (referencedNodes.length >= 2) {
+                const fromNode = referencedNodes[0];
+                const toNode = referencedNodes[1];
+                const pathHops = await graphManager.tracePath(fromNode.id, toNode.id, 5);
+                if (pathHops) {
+                    trace = { hops: pathHops };
+                }
+            }
+        }
+    }
+    catch (e) {
+        // Ignore
+    }
+    // 2. Git Recent Changes
+    let gitHits = undefined;
+    const historyKeywords = ['recent', 'change', 'git', 'commit', 'log', 'history', 'branch', 'timeline'];
+    const wantsHistory = historyKeywords.some(kw => queryLower.includes(kw));
+    if (wantsHistory && gitIntegration) {
+        try {
+            const summary = await gitIntegration.getGitSummary();
+            gitHits = summary.recentCommits.slice(0, 5).map((c) => ({
+                hash: c.hash.substring(0, 7),
+                message: c.message,
+                author: c.author,
+                date: c.date
+            }));
+        }
+        catch (e) {
+            // Ignore
+        }
+    }
+    // 3. Load Memories
+    let allMemories = [];
+    try {
+        allMemories = await core.searchMemories({ limit: 1000 });
+    }
+    catch (e) { }
+    // 4. Semantic Search
+    let semanticResults = [];
+    try {
+        if (vectorEngine && allMemories.length > 0) {
+            semanticResults = await vectorEngine.searchSimilarText(sanitizedQuery, allMemories, 50);
+        }
+    }
+    catch (e) { }
+    // 5. Keyword Search
+    const keywordResults = allMemories.filter(mem => mem.content.toLowerCase().includes(queryLower) ||
+        mem.tags.some(tag => tag.toLowerCase().includes(queryLower))).slice(0, 50);
+    // 6. Graph Pseudo-hits
+    const graphMemories = allMemories.filter(mem => {
+        const matchPath = mem.relatedPaths?.some(p => codeHits.some(c => c.path === p));
+        const matchSym = mem.relatedSymbols?.some(s => codeHits.some(c => c.symbol === s));
+        return matchPath || matchSym;
+    }).slice(0, 50);
+    // 7. Git Pseudo-hits
+    const gitMemories = allMemories.filter(mem => {
+        if (!mem.commitHash || !gitHits)
+            return false;
+        return gitHits.some(g => mem.commitHash.startsWith(g.hash));
+    }).slice(0, 50);
+    // 8. RRF Merge
+    const rrfScores = rrfMerge([
+        semanticResults,
+        keywordResults,
+        graphMemories,
+        gitMemories
+    ]);
+    const sortedMemories = Array.from(rrfScores.entries())
+        .sort((a, b) => b[1] - a[1])
+        .map(([id]) => allMemories.find(m => m.id === id))
+        .filter(Boolean)
+        .slice(0, safeLimit);
+    // 9. Deterministic Stitched Answer Summary
+    let answerSummary = `### ContextHub Query Results for "${sanitizedQuery}"\n\n`;
+    answerSummary += `* Found ${sortedMemories.length} relevant memory entries.\n`;
+    if (codeHits.length > 0) {
+        answerSummary += `* Identified ${codeHits.length} related symbols/files in the local knowledge graph.\n`;
+    }
+    if (gitHits && gitHits.length > 0) {
+        answerSummary += `* Retrieved ${gitHits.length} recent commits from git repository history.\n`;
+    }
+    if (trace) {
+        answerSummary += `* Traced dependency connection path: ${trace.hops.map(h => `\`${h.label}\` (${h.type})`).join(' → ')}\n`;
+    }
+    return {
+        answerSummary,
+        memories: sortedMemories,
+        codeHits: codeHits.slice(0, safeLimit),
+        gitHits,
+        trace
+    };
+}