@compr/opscontext-mcp 2.0.0

package/dist/ingest.d.ts

@@ -0,0 +1,32 @@
+import { KnowledgeSource } from "./config.js";
+/**
+ * A chunk of text extracted from a knowledge source,
+ * suitable for embedding or keyword search.
+ */
+export interface Chunk {
+    /** Which source file this came from */
+    source: string;
+    /** Section heading path (e.g. "## Architecture > ### Docker") */
+    section: string;
+    /** The actual text content */
+    content: string;
+    /** Starting line number in the original file (1-based) */
+    lineStart: number;
+    /** Ending line number in the original file (1-based) */
+    lineEnd: number;
+    /** SHA-256 hash of content for deduplication */
+    contentHash?: string;
+    /** Timestamp when chunk was indexed (ISO string) */
+    indexedAt?: string;
+    /** True if chunk contains a lock marker (LOCKED / ALREADY IMPLEMENTED) — signals agents should not re-audit */
+    locked?: boolean;
+}
+/** Check if a chunk's content contains a lock marker */
+export declare function hasLockMarker(text: string): boolean;
+/**
+ * Ingest all configured knowledge sources into chunks.
+ * Skips files that don't exist (with a warning to stderr).
+ * Deduplicates chunks by content hash.
+ */
+export declare function ingestSources(sources: KnowledgeSource[]): Chunk[];
+//# sourceMappingURL=ingest.d.ts.map

package/dist/ingest.js

@@ -0,0 +1,162 @@
+import { readFileSync, existsSync, statSync } from "fs";
+import { basename } from "path";
+import { createHash } from "crypto";
+/**
+ * Number of overlap lines to carry over from the end of the previous chunk
+ * to the beginning of the next chunk. Provides context continuity at
+ * section boundaries (inspired by OpenClaw's 80-token overlap strategy).
+ */
+const OVERLAP_LINES = 4;
+/**
+ * Lock marker patterns that signal verified/audited content.
+ * Agents should NOT re-audit chunks containing these markers.
+ * Supports code comments (// LOCKED, /* LOCKED, # LOCKED),
+ * HTML comments (<!-- LOCKED -->), and markdown headings (## ALREADY IMPLEMENTED).
+ */
+const LOCK_PATTERNS = [
+    /\/\/\s*LOCKED/i,
+    /\/\*\s*LOCKED/i,
+    /#\s*LOCKED/i,
+    /<!--\s*LOCKED/i,
+    /LOCKED\s*[—–-]\s*verified/i,
+    /DO\s*NOT\s*RE-?AUDIT/i,
+    /ALREADY\s+IMPLEMENTED/i,
+    /VERIFIED\s*[—–-]\s*DO\s*NOT/i,
+];
+/** Check if a chunk's content contains a lock marker */
+export function hasLockMarker(text) {
+    return LOCK_PATTERNS.some(p => p.test(text));
+}
+/**
+ * Compute SHA-256 hash of a string for content deduplication.
+ */
+function hashContent(content) {
+    return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+/**
+ * Parse a markdown file into chunks, splitting on headings.
+ * Each chunk captures the heading hierarchy for context.
+ *
+ * v1.10: Adds overlap lines from the end of each chunk to the start
+ * of the next chunk, providing context continuity at heading boundaries.
+ * Also computes SHA-256 content hashes for deduplication.
+ */
+function parseMarkdown(filePath, sourceName) {
+    let mtime;
+    try {
+        mtime = statSync(filePath).mtime.toISOString();
+    }
+    catch {
+        mtime = new Date().toISOString();
+    }
+    const text = readFileSync(filePath, "utf-8");
+    const lines = text.split("\n");
+    const rawChunks = [];
+    // Track heading hierarchy
+    const headingStack = [];
+    let currentContent = [];
+    let chunkStartLine = 1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const headingMatch = line.match(/^(#{1,6})\s+(.+)/);
+        if (headingMatch) {
+            // Flush previous chunk
+            if (currentContent.length > 0) {
+                const content = currentContent.join("\n").trim();
+                if (content.length > 0) {
+                    rawChunks.push({
+                        section: headingStack.join(" > ") || basename(filePath),
+                        contentLines: [...currentContent],
+                        startLine: chunkStartLine,
+                        endLine: i,
+                    });
+                }
+            }
+            const level = headingMatch[1].length;
+            const title = headingMatch[2].trim();
+            // Pop headings at same or deeper level
+            while (headingStack.length >= level) {
+                headingStack.pop();
+            }
+            headingStack.push(`${"#".repeat(level)} ${title}`);
+            currentContent = [];
+            chunkStartLine = i + 1; // 1-based
+        }
+        else {
+            currentContent.push(line);
+        }
+    }
+    // Flush last chunk
+    if (currentContent.length > 0) {
+        const content = currentContent.join("\n").trim();
+        if (content.length > 0) {
+            rawChunks.push({
+                section: headingStack.join(" > ") || basename(filePath),
+                contentLines: [...currentContent],
+                startLine: chunkStartLine,
+                endLine: lines.length,
+            });
+        }
+    }
+    // Build final chunks with overlap
+    const chunks = [];
+    for (let i = 0; i < rawChunks.length; i++) {
+        const raw = rawChunks[i];
+        let finalLines = raw.contentLines;
+        // Add overlap from previous chunk's tail (if not the first chunk)
+        if (i > 0 && OVERLAP_LINES > 0) {
+            const prevLines = rawChunks[i - 1].contentLines;
+            const overlapCount = Math.min(OVERLAP_LINES, prevLines.length);
+            const overlap = prevLines.slice(-overlapCount);
+            finalLines = [...overlap, "---", ...raw.contentLines];
+        }
+        const content = finalLines.join("\n").trim();
+        if (content.length > 0) {
+            const locked = hasLockMarker(content) || hasLockMarker(raw.section);
+            chunks.push({
+                source: sourceName,
+                section: raw.section,
+                content,
+                lineStart: raw.startLine,
+                lineEnd: raw.endLine,
+                contentHash: hashContent(content),
+                indexedAt: mtime,
+                ...(locked && { locked: true }),
+            });
+        }
+    }
+    return chunks;
+}
+/**
+ * Ingest all configured knowledge sources into chunks.
+ * Skips files that don't exist (with a warning to stderr).
+ * Deduplicates chunks by content hash.
+ */
+export function ingestSources(sources) {
+    const allChunks = [];
+    const seenHashes = new Set();
+    let dupCount = 0;
+    for (const source of sources) {
+        if (!existsSync(source.path)) {
+            console.error(`[ContextEngine] ⚠ Skipping missing: ${source.path}`);
+            continue;
+        }
+        const chunks = parseMarkdown(source.path, source.name);
+        for (const chunk of chunks) {
+            if (chunk.contentHash && seenHashes.has(chunk.contentHash)) {
+                dupCount++;
+                continue;
+            }
+            if (chunk.contentHash)
+                seenHashes.add(chunk.contentHash);
+            allChunks.push(chunk);
+        }
+        console.error(`[ContextEngine] ✅ Indexed: ${source.name} (${chunks.length} chunks)`);
+    }
+    if (dupCount > 0) {
+        console.error(`[ContextEngine] 🔁 Deduplicated: ${dupCount} duplicate chunks removed`);
+    }
+    console.error(`[ContextEngine] 📦 Total: ${allChunks.length} chunks from ${sources.length} sources`);
+    return allChunks;
+}
+//# sourceMappingURL=ingest.js.map

package/dist/learnings.d.ts

@@ -0,0 +1,108 @@
+import { Chunk } from "./ingest.js";
+export interface Learning {
+    id: string;
+    category: string;
+    rule: string;
+    context: string;
+    project?: string;
+    tags: string[];
+    created: string;
+    updated: string;
+}
+export interface LearningsStore {
+    version: number;
+    count: number;
+    learnings: Learning[];
+}
+/** Valid categories for learnings */
+export declare const LEARNING_CATEGORIES: readonly ["deployment", "api", "database", "frontend", "backend", "devops", "security", "performance", "testing", "debugging", "tooling", "git", "dependencies", "architecture", "data", "infrastructure", "mobile", "other"];
+export type LearningCategory = (typeof LEARNING_CATEGORIES)[number];
+/**
+ * Save a new learning. Returns the created learning with ID.
+ * Rejects rules shorter than MIN_RULE_LENGTH and auto-corrects "other" category.
+ */
+export declare function saveLearning(category: string, rule: string, context: string, project?: string): Learning;
+/**
+ * Search learnings by keyword. Returns matches sorted by relevance.
+ */
+export declare function searchLearnings(query: string): Learning[];
+/**
+ * Get learnings, optionally filtered by category and/or project.
+ *
+ * When `projects` is provided, only returns learnings that:
+ * - match one of the given project names (case-insensitive), OR
+ * - have no project set (universal learnings)
+ *
+ * This prevents cross-project IP leakage — e.g. CROWLR learnings
+ * won't appear when working on VOILA.
+ */
+export declare function listLearnings(category?: string, projects?: string[]): Learning[];
+/**
+ * Delete a learning by ID.
+ */
+export declare function deleteLearning(id: string): boolean;
+/**
+ * Import learnings from a Markdown file.
+ * Parses headings and bullet points to extract rules.
+ *
+ * Supported formats:
+ * 1. **Structured Markdown** — H2 = category, H3 = rule, bullet = context
+ *    ```md
+ *    ## deployment
+ *    ### Never docker build | tee
+ *    - Pipeline signals kill builds. Use nohup > /tmp/log 2>&1 &
+ *    ```
+ *
+ * 2. **Bullet-list Markdown** — Each bullet with "→" or "—" separator
+ *    ```md
+ *    - [deployment] Never docker build | tee → Pipeline signals kill builds
+ *    ```
+ *
+ * 3. **JSON array** — Direct Learning[] import
+ */
+export interface ImportResult {
+    imported: number;
+    updated: number;
+    skipped: number;
+    errors: string[];
+}
+export declare function importLearningsFromFile(filePath: string, defaultCategory?: string, defaultProject?: string): ImportResult;
+/**
+ * Convert learnings to Chunks so they can be included in search_context.
+ * This is the key integration — learnings auto-surface in hybrid search.
+ *
+ * When `projects` is provided, only includes learnings for those projects
+ * (+ universal learnings with no project). This prevents cross-project
+ * IP leakage — CROWLR secrets won't appear when searching in VOILA.
+ */
+export declare function learningsToChunks(projects?: string[]): Chunk[];
+/**
+ * Auto-import learnings from discovered knowledge source files.
+ *
+ * Called during reindex — scans all source markdown files and extracts
+ * rules into the permanent learning store. Deduplication is built-in,
+ * so calling repeatedly on the same files is safe (no duplicates).
+ *
+ * This ensures documentation rules become searchable learnings without
+ * requiring the user or agent to manually trigger `import_learnings`.
+ */
+export declare function autoImportFromSources(sources: Array<{
+    path: string;
+    name: string;
+}>): {
+    total: number;
+    imported: number;
+    updated: number;
+};
+/**
+ * Get the store stats.
+ */
+export declare function learningsStats(): {
+    total: number;
+    categories: Record<string, number>;
+};
+/**
+ * Format learnings for display.
+ */
+export declare function formatLearnings(learnings: Learning[]): string;
+//# sourceMappingURL=learnings.d.ts.map