@compr/opscontext-mcp 2.0.0

package/dist/config.js

@@ -0,0 +1,239 @@
+import { resolve, join } from "path";
+import { homedir } from "os";
+import { readFileSync, existsSync, readdirSync, statSync } from "fs";
+import { discoverClaudeMemory } from "./claude-integration.js";
+const DEFAULT_PATTERNS = [
+    // GitHub Copilot
+    ".github/copilot-instructions.md",
+    ".github/instructions/copilot-instructions.md",
+    ".github/SKILLS.md",
+    // Claude Code
+    "CLAUDE.md",
+    // Cursor
+    ".cursorrules",
+    ".cursor/rules",
+    // Codex / multi-agent
+    "AGENTS.md",
+    // Context engineering
+    "CONTEXT_MAP.md",
+];
+/**
+ * Look for contextengine.json in standard locations.
+ * Priority: env var > CWD > home dir
+ */
+function findConfigFile() {
+    const candidates = [];
+    const envPath = process.env.CONTEXTENGINE_CONFIG;
+    if (envPath) {
+        candidates.push(resolve(envPath));
+    }
+    candidates.push(resolve(process.cwd(), "contextengine.json"), resolve(homedir(), ".contextengine.json"));
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+/**
+ * Auto-discover knowledge files by scanning directories for known patterns.
+ * Scans one level deep (each subdirectory = a project).
+ */
+function discoverSources(dirs, patterns) {
+    const sources = [];
+    for (const dir of dirs) {
+        const absDir = resolve(dir.replace(/^~/, homedir()));
+        if (!existsSync(absDir))
+            continue;
+        // Check patterns at this level
+        for (const pattern of patterns) {
+            const filePath = join(absDir, pattern);
+            if (existsSync(filePath)) {
+                const dirName = absDir.split("/").pop() || absDir;
+                const fileName = pattern.split("/").pop() || pattern;
+                sources.push({
+                    name: `${dirName} — ${fileName}`,
+                    path: filePath,
+                    type: "markdown",
+                });
+            }
+        }
+        // Scan one level deep (subdirectories = projects)
+        try {
+            for (const entry of readdirSync(absDir)) {
+                if (entry.startsWith(".") || entry === "node_modules")
+                    continue;
+                const subDir = join(absDir, entry);
+                try {
+                    if (!statSync(subDir).isDirectory())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                for (const pattern of patterns) {
+                    const filePath = join(subDir, pattern);
+                    if (existsSync(filePath)) {
+                        const fileName = pattern.split("/").pop() || pattern;
+                        sources.push({
+                            name: `${entry} — ${fileName}`,
+                            path: filePath,
+                            type: "markdown",
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            // Permission denied — skip
+        }
+    }
+    return sources;
+}
+/**
+ * Load knowledge sources.
+ *
+ * Resolution order:
+ * 1. Config file (CONTEXTENGINE_CONFIG env, ./contextengine.json, ~/.contextengine.json)
+ * 2. CONTEXTENGINE_WORKSPACES env var (colon-separated paths)
+ * 3. Auto-discover from ~/Projects
+ *
+ * Claude Code auto-memory (~/.claude/projects/<slug>/memory/*.md) is added
+ * to every resolution path unless OPSCONTEXT_SKIP_CLAUDE_MEMORY=1.
+ */
+export function loadSources() {
+    const configPath = findConfigFile();
+    if (configPath) {
+        console.error(`[ContextEngine] 📄 Config: ${configPath}`);
+        const config = JSON.parse(readFileSync(configPath, "utf-8"));
+        const sources = [];
+        // Explicit sources
+        if (config.sources) {
+            for (const s of config.sources) {
+                const absPath = resolve(configPath, "..", s.path.replace(/^~/, homedir()));
+                if (existsSync(absPath)) {
+                    sources.push({ name: s.name, path: absPath, type: "markdown" });
+                }
+                else {
+                    console.error(`[ContextEngine] ⚠ Not found: ${absPath}`);
+                }
+            }
+        }
+        // Workspace auto-discovery
+        if (config.workspaces) {
+            const patterns = config.patterns || DEFAULT_PATTERNS;
+            const resolved = config.workspaces.map((w) => resolve(configPath, "..", w.replace(/^~/, homedir())));
+            sources.push(...discoverSources(resolved, patterns));
+        }
+        sources.push(...claudeMemorySources());
+        return dedup(sources);
+    }
+    // Env var fallback
+    const envWorkspaces = process.env.CONTEXTENGINE_WORKSPACES;
+    if (envWorkspaces) {
+        console.error(`[ContextEngine] 🔍 Discovering from CONTEXTENGINE_WORKSPACES`);
+        const dirs = envWorkspaces.split(":").filter(Boolean);
+        const found = discoverSources(dirs, DEFAULT_PATTERNS);
+        return dedup([...found, ...claudeMemorySources()]);
+    }
+    // Auto-discover from ~/Projects
+    const projectsDir = resolve(homedir(), "Projects");
+    if (existsSync(projectsDir)) {
+        console.error(`[ContextEngine] 🔍 Auto-discovering from ~/Projects`);
+        const found = discoverSources([projectsDir], DEFAULT_PATTERNS);
+        return dedup([...found, ...claudeMemorySources()]);
+    }
+    console.error(`[ContextEngine] ⚠ No sources found. Create contextengine.json or set CONTEXTENGINE_WORKSPACES.`);
+    // Claude memory may still exist even without project workspaces — surface it.
+    return claudeMemorySources();
+}
+/**
+ * Pull Claude Code auto-memory into the source list (read-only). Skips when
+ * OPSCONTEXT_SKIP_CLAUDE_MEMORY=1 (escape hatch for tests + air-gapped runs
+ * where ~/.claude/ contents may not be indexable).
+ */
+function claudeMemorySources() {
+    if (process.env.OPSCONTEXT_SKIP_CLAUDE_MEMORY === "1")
+        return [];
+    try {
+        return discoverClaudeMemory();
+    }
+    catch {
+        return [];
+    }
+}
+/** Remove duplicate paths */
+function dedup(sources) {
+    const seen = new Set();
+    return sources.filter((s) => {
+        if (seen.has(s.path))
+            return false;
+        seen.add(s.path);
+        return true;
+    });
+}
+/**
+ * Discover project directories from workspaces.
+ * Returns one entry per top-level project found.
+ */
+export function loadProjectDirs() {
+    const configPath = findConfigFile();
+    const dirs = [];
+    let workspaceDirs = [];
+    if (configPath) {
+        const config = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (config.collectOps === false)
+            return []; // opted out
+        if (config.workspaces) {
+            workspaceDirs = config.workspaces.map((w) => resolve(configPath, "..", w.replace(/^~/, homedir())));
+        }
+    }
+    // Env var fallback
+    if (workspaceDirs.length === 0) {
+        const envWorkspaces = process.env.CONTEXTENGINE_WORKSPACES;
+        if (envWorkspaces) {
+            workspaceDirs = envWorkspaces.split(":").filter(Boolean);
+        }
+    }
+    // Auto-discover fallback
+    if (workspaceDirs.length === 0) {
+        const projectsDir = resolve(homedir(), "Projects");
+        if (existsSync(projectsDir)) {
+            workspaceDirs = [projectsDir];
+        }
+    }
+    for (const wsDir of workspaceDirs) {
+        const absDir = resolve(wsDir.replace(/^~/, homedir()));
+        if (!existsSync(absDir))
+            continue;
+        try {
+            for (const entry of readdirSync(absDir)) {
+                if (entry.startsWith(".") || entry === "node_modules")
+                    continue;
+                const subDir = join(absDir, entry);
+                try {
+                    if (!statSync(subDir).isDirectory())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                dirs.push({ name: entry, path: subDir });
+            }
+        }
+        catch {
+            // Permission denied — skip
+        }
+    }
+    return dirs;
+}
+/**
+ * Load the raw config (for checking flags like collectSystemOps).
+ */
+export function loadConfig() {
+    const configPath = findConfigFile();
+    if (configPath) {
+        return JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    return {};
+}
+//# sourceMappingURL=config.js.map

package/dist/embeddings.d.ts

@@ -0,0 +1,36 @@
+import type { Chunk } from "./ingest.js";
+/**
+ * Initialize the embedding pipeline (downloads model on first run, ~22MB).
+ * Subsequent calls use cached model.
+ *
+ * @huggingface/transformers is an optional dependency (~250MB transitive,
+ * native onnxruntime binaries). If it's absent (npm install --no-optional,
+ * air-gapped network at install time, or locked-down corp proxy), we silently
+ * fall back to BM25 keyword search — `search_context` still works.
+ */
+export declare function initEmbeddings(): Promise<boolean>;
+/**
+ * An embedded chunk with its vector.
+ */
+export interface EmbeddedChunk {
+    chunk: Chunk;
+    vector: Float32Array;
+}
+/**
+ * Embed all chunks. Returns the chunks with their vectors.
+ * Shows progress on stderr.
+ */
+export declare function embedChunks(chunks: Chunk[]): Promise<EmbeddedChunk[]>;
+export interface VectorSearchResult {
+    chunk: Chunk;
+    score: number;
+}
+/**
+ * Semantic search: embed the query, then find most similar chunks.
+ */
+export declare function vectorSearch(query: string, embeddedChunks: EmbeddedChunk[], topK?: number): Promise<VectorSearchResult[]>;
+/**
+ * Check if embeddings are available.
+ */
+export declare function isEmbeddingsReady(): boolean;
+//# sourceMappingURL=embeddings.d.ts.map

package/dist/embeddings.js

@@ -0,0 +1,124 @@
+// LOCKED — verified March 3 2026 — Xenova all-MiniLM-L6-v2 local CPU embeddings + disk cache
+// DO NOT RE-AUDIT — stable since v1.0, no API keys, no data leaves machine
+//
+// 🔒 LOCKED [OPTIONAL-HF] — 2026-06-10
+// ⛔ NEVER convert `await import("@huggingface/transformers")` to a static
+//    import. HF is in optionalDependencies — a static import breaks installs
+//    that ran with --omit=optional (locked-down npm proxies, air-gapped CI).
+// ⛔ NEVER remove the try/catch around the dynamic import or the
+//    isMissingDep detection branch — both keep the MCP server alive on
+//    fresh installs where HF didn't download.
+// WHY: The package was failing to install on enterprise environments because
+//    HF transitively pulls 427 MB of onnxruntime native binaries. Making
+//    HF optional dropped cold install from 547 MB to 120 MB and unblocked
+//    a whole class of buyers. A static import would silently re-break this.
+// FIX: If you need to take a dependency on a transformer feature, add it
+//    behind the same dynamic-import + isEmbeddingsReady() check pattern.
+// We dynamically import @huggingface/transformers to keep startup fast
+// and handle the case where it fails gracefully.
+let embedPipeline = null;
+const MODEL_NAME = "Xenova/all-MiniLM-L6-v2";
+/**
+ * Initialize the embedding pipeline (downloads model on first run, ~22MB).
+ * Subsequent calls use cached model.
+ *
+ * @huggingface/transformers is an optional dependency (~250MB transitive,
+ * native onnxruntime binaries). If it's absent (npm install --no-optional,
+ * air-gapped network at install time, or locked-down corp proxy), we silently
+ * fall back to BM25 keyword search — `search_context` still works.
+ */
+export async function initEmbeddings() {
+    try {
+        console.error(`[ContextEngine] 🧠 Loading embedding model: ${MODEL_NAME}...`);
+        const { pipeline } = await import("@huggingface/transformers");
+        embedPipeline = await pipeline("feature-extraction", MODEL_NAME, {
+            dtype: "fp32",
+        });
+        console.error(`[ContextEngine] ✅ Embedding model loaded`);
+        return true;
+    }
+    catch (err) {
+        const msg = err.message;
+        const isMissingDep = msg.includes("Cannot find package") ||
+            msg.includes("ERR_MODULE_NOT_FOUND") ||
+            msg.includes("@huggingface/transformers");
+        if (isMissingDep) {
+            console.error(`[ContextEngine] ⚠ Semantic search disabled — @huggingface/transformers not installed.\n` +
+                `   BM25 keyword search still works. To enable semantic search:\n` +
+                `     npm install @huggingface/transformers\n` +
+                `   (~250MB download; CPU-only embeddings via Xenova/all-MiniLM-L6-v2, no data leaves the machine).`);
+        }
+        else {
+            console.error(`[ContextEngine] ⚠ Embeddings unavailable (keyword search only):`, msg);
+        }
+        return false;
+    }
+}
+/**
+ * Embed a single text string → float32 vector (384 dimensions).
+ */
+async function embedText(text) {
+    const output = await embedPipeline(text, {
+        pooling: "mean",
+        normalize: true,
+    });
+    // output.data is a flat typed array
+    return new Float32Array(output.data);
+}
+/**
+ * Cosine similarity between two vectors.
+ * Both must be normalized (which MiniLM + normalize:true guarantees),
+ * so dot product = cosine similarity.
+ */
+function cosineSimilarity(a, b) {
+    let dot = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+    }
+    return dot;
+}
+/**
+ * Embed all chunks. Returns the chunks with their vectors.
+ * Shows progress on stderr.
+ */
+export async function embedChunks(chunks) {
+    const results = [];
+    const total = chunks.length;
+    const batchSize = 10;
+    for (let i = 0; i < total; i += batchSize) {
+        const batch = chunks.slice(i, i + batchSize);
+        const batchResults = await Promise.all(batch.map(async (chunk) => {
+            // Embed section + content together for context
+            const text = `${chunk.section}\n${chunk.content}`.slice(0, 512);
+            const vector = await embedText(text);
+            return { chunk, vector };
+        }));
+        results.push(...batchResults);
+        const done = Math.min(i + batchSize, total);
+        if (done % 50 === 0 || done === total) {
+            console.error(`[ContextEngine] 📊 Embedded ${done}/${total} chunks`);
+        }
+    }
+    return results;
+}
+/**
+ * Semantic search: embed the query, then find most similar chunks.
+ */
+export async function vectorSearch(query, embeddedChunks, topK = 10) {
+    if (!embedPipeline || embeddedChunks.length === 0)
+        return [];
+    const queryVector = await embedText(query);
+    const scored = embeddedChunks.map((ec) => ({
+        chunk: ec.chunk,
+        score: cosineSimilarity(queryVector, ec.vector),
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, topK);
+}
+/**
+ * Check if embeddings are available.
+ */
+export function isEmbeddingsReady() {
+    return embedPipeline !== null;
+}
+//# sourceMappingURL=embeddings.js.map

package/dist/firewall.d.ts

@@ -0,0 +1,133 @@
+export interface Obligation {
+    id: string;
+    label: string;
+    status: "ok" | "warn" | "fail";
+    detail: string;
+}
+/**
+ * Callback type for searching learnings — avoids circular import.
+ * Returns top matches with rule text + optional project scope.
+ */
+export type LearningSearchFn = (query: string, projects?: string[]) => Array<{
+    rule: string;
+    project?: string;
+    category: string;
+}>;
+export declare class ProtocolFirewall {
+    private toolCalls;
+    private learningsSaved;
+    private sessionSaved;
+    private readonly startTime;
+    private nudgesIssued;
+    private searchRecalls;
+    private truncations;
+    private lastNonExemptCall;
+    private round;
+    private roundAtLastSave;
+    private roundsSinceSessionSave;
+    private lastSessionSaveTime;
+    private statsFlushTimer;
+    private static readonly STATS_FLUSH_MS;
+    private static readonly STATS_FILE;
+    private learningSearchFn;
+    private activeProjects;
+    private injectionCache;
+    private injectionCacheRound;
+    private learningsInjected;
+    private gitCache;
+    private docCache;
+    private projectDirs;
+    constructor(opts?: {
+        skipRestore?: boolean;
+    });
+    /**
+     * Resume enforcement from a prior session if it crashed recently.
+     * Reads session-stats.json and restores round counters so a crashed
+     * window doesn't reset enforcement back to silent.
+     */
+    private loadPriorState;
+    /**
+     * Update project directories (call during reindex).
+     */
+    setProjectDirs(dirs: Array<{
+        path: string;
+        name: string;
+    }>): void;
+    /**
+     * Register the learning search function.
+     * Call once at startup to enable auto-injection without circular imports.
+     */
+    setLearningSearchFn(fn: LearningSearchFn): void;
+    /**
+     * Wrap a tool response with protocol status + learning injection.
+     * This is the ONLY public API. Call on every tool response.
+     *
+     * - Exempt tools (save_learning, etc.) pass through unmodified
+     * - Silent phase (first 10 calls or 0 obligations): no change
+     * - Footer/Header: status block appended/prepended
+     * - Degraded: response TRUNCATED + status block
+     *
+     * @param toolName  MCP tool name
+     * @param responseText  Original tool response text
+     * @param contextHint  Optional query/args string for learning injection
+     */
+    wrap(toolName: string, responseText: string, contextHint?: string): string;
+    /**
+     * Get current state for diagnostics / testing.
+     */
+    getState(): {
+        toolCalls: number;
+        learningsSaved: number;
+        sessionSaved: boolean;
+        uptimeMinutes: number;
+        nudgesIssued: number;
+        searchRecalls: number;
+        truncations: number;
+        timeSavedMinutes: number;
+        round: number;
+        roundsSinceSessionSave: number;
+        learningsInjected: number;
+        sessionOverdue: boolean;
+    };
+    /**
+     * Record that N learnings were surfaced in a search result.
+     * Call from search_context handler after counting learning-sourced results.
+     */
+    recordSearchRecalls(count: number): void;
+    /**
+     * Search and format relevant learnings for injection into tool response.
+     * Returns null if no relevant learnings or no search function registered.
+     * Results are cached per round to avoid repeated searches for same hint.
+     */
+    private buildLearningInjection;
+    /**
+     * Estimate minutes saved by ContextEngine this session.
+     * Only counts genuine value events — not overhead like nudges or auto-injection.
+     * - Each explicit search recall ≈ 2 min (avoids re-discovery / googling)
+     * - Each auto-injected learning ≈ 1 min (proactive context, less than explicit)
+     * - Each learning saved ≈ 1 min (future sessions benefit)
+     * - Session save ≈ 3 min (avoids cold-start next session)
+     * Note: nudges removed (they're enforcement overhead, not time saved).
+     */
+    private estimateTimeSaved;
+    private scheduleStatsFlush;
+    private flushStats;
+    private recordCompliance;
+    /**
+     * Check if session save is overdue (>10 minutes since last save,
+     * or >10 minutes of activity without ever saving).
+     * Only triggers after the warmup period (first 10 minutes of session).
+     */
+    private isSessionOverdue;
+    /**
+     * Build an urgent session reminder block.
+     * This is injected at the TOP of every tool response when overdue.
+     */
+    private buildSessionUrgentBlock;
+    private evaluate;
+    private checkGit;
+    private checkDocs;
+    private computeLevel;
+    private formatBlock;
+}
+//# sourceMappingURL=firewall.d.ts.map