@compr/opscontext-mcp 2.8.0 → 2.8.2

package/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to OpsContext for AI Agents (previously ContextEngine — MC
 
 > Entries for 2.2.0 through 2.4.0 were not backfilled here; see `docs/sessions/SESSION_19` through `SESSION_21` for those releases.
 
+## [2.8.2] 2026-09-08: every source says what it is
+
+### Added
+
+- **One-line summary per source in `list_sources` and `contextengine list-sources`**
+  (`src/source-summary.ts`): frontmatter `description` when the file has one, else H1 title
+  plus first prose line, else the module docstring or header comment for code. Read from the
+  first 4 KB of each file only. Why: with 800+ sources an agent opened two or three whole
+  documents to find the right one; the summary lets it pick once.
+
+## [2.8.1] 2026-09-07: a push is not done until its CI is read
+
+### Added
+
+- **`end-session` check 3c, CI on HEAD** (`[PUSHED-MEANS-CI-READ]`, `src/ci-status.ts`): every
+  workflow run for the exact HEAD sha through `gh run list`; a failed run is a FAIL item (exit 1).
+  No gh, no remote, or no runs yet is "not checked", never a pass. Why: main's CI had been red
+  on every commit since 2026-09-04 and the Telegram alert fired each time; thirty commits and
+  five releases went by with nobody reading it.
+
+### Changed
+
+- CI installs the activation server's own packages too: the first time the Test step actually
+  ran, `server/src/community-rules-server.test.ts` could not load (`ERR_MODULE_NOT_FOUND`).
+- The Doc Freshness gate fails only when 20 or more source lines change without a doc change; a
+  one-line lint fix is not a documented change (its first run paged Telegram for a dash).
+- CI runs on Node 20 and 22 with `fail-fast: false`; Node 18 is EOL and eslint 10 needs 20.19+,
+  and the 18 job's failure was cancelling the others before tests ran. `engines.node` is now
+  `>=20.19.0`, which is what is tested.
+
+### Fixed
+
+- CI was red on every pull request for one `prefer-const` lint error in `src/firewall.ts`.
+- The Doc Freshness workflow failed any push or PR made more than 8 hours after the last
+  SKILLS.md commit, whatever the change (two Dependabot bumps on 2026-09-07). It now measures
+  the change itself: source touched without a doc touched fails, anything else passes
+  (`[DOC-GATE-MEASURES-THE-DIFF]`).
+
 ## [2.8.0] 2026-09-06: health is measured, never estimated
 
 ### Added

package/dist/ci-status.d.ts

@@ -0,0 +1,16 @@
+export interface CiRun {
+    name: string;
+    status: string;
+    conclusion: string | null;
+    url: string;
+}
+export interface CiStatus {
+    sha: string;
+    state: "ok" | "failed" | "pending" | "no-runs" | "unavailable";
+    runs: CiRun[];
+    note?: string;
+}
+export type Runner = (cmd: string, args: string[], cwd: string) => string;
+export declare function ciStatusForHead(cwd: string, run?: Runner): CiStatus;
+export declare function formatCiStatus(s: CiStatus): string[];
+//# sourceMappingURL=ci-status.d.ts.map

package/dist/ci-status.js

@@ -0,0 +1,55 @@
+// [LOCKED] [PUSHED-MEANS-CI-READ] 2026-09-07
+// [NEVER] let end-session pass while a workflow run for HEAD has failed, and [NEVER] count
+//         "no runs found" as green.
+// WHY: main's CI had been red on every commit since 2026-09-04 (one lint error, then a Node 18
+//      job that eslint 10 cannot run on) and the Telegram alert fired each time. Thirty commits,
+//      five releases, nobody read it: the post-commit hook pushes, end-session ran after every
+//      push, and nothing in that loop looked at the result. A push is not done until its CI is.
+// FIX: end-session check 3c lists every workflow run for the exact HEAD sha through `gh run
+//      list` (hardcoded argv, no shell) and counts a failure as a FAIL item. gh missing, no
+//      GitHub remote, or no runs yet is reported as "not checked", never as pass.
+import { execFileSync } from "child_process";
+const defaultRunner = (cmd, args, cwd) => execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 15_000 }).trim();
+export function ciStatusForHead(cwd, run = defaultRunner) {
+    let sha = "";
+    try {
+        sha = run("git", ["rev-parse", "HEAD"], cwd);
+    }
+    catch {
+        return { sha, state: "unavailable", runs: [], note: "not a git repository" };
+    }
+    let raw = "";
+    try {
+        raw = run("gh", ["run", "list", "--limit", "40", "--json", "name,status,conclusion,url,headSha"], cwd);
+    }
+    catch {
+        return { sha, state: "unavailable", runs: [], note: "gh not available, not logged in, or no GitHub remote" };
+    }
+    let all = [];
+    try {
+        all = JSON.parse(raw);
+    }
+    catch {
+        return { sha, state: "unavailable", runs: [], note: "gh returned no JSON" };
+    }
+    const runs = all.filter((r) => r.headSha === sha).map(({ name, status, conclusion, url }) => ({ name, status, conclusion, url }));
+    if (runs.length === 0)
+        return { sha, state: "no-runs", runs, note: "no workflow run for HEAD yet: pushed seconds ago, or CI not wired" };
+    const failed = runs.some((r) => r.conclusion === "failure" || r.conclusion === "timed_out" || r.conclusion === "startup_failure");
+    const pending = runs.some((r) => r.status !== "completed");
+    return { sha, state: failed ? "failed" : pending ? "pending" : "ok", runs };
+}
+export function formatCiStatus(s) {
+    const lines = [];
+    if (s.state === "unavailable" || s.state === "no-runs") {
+        lines.push(`- ⚠️ CI on HEAD${s.sha ? ` ${s.sha.slice(0, 7)}` : ""} not checked: ${s.note}`);
+        return lines;
+    }
+    for (const r of s.runs) {
+        const bad = r.conclusion === "failure" || r.conclusion === "timed_out" || r.conclusion === "startup_failure";
+        const icon = bad ? "❌ FAIL" : r.status !== "completed" ? "⏳" : r.conclusion === "success" ? "✅" : "▫️";
+        lines.push(`- ${icon} ${r.name}: ${r.conclusion ?? r.status}${bad ? `  ${r.url}` : ""}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=ci-status.js.map

package/dist/cli.js

@@ -641,6 +641,7 @@ async function runInit() {
 // ---------------------------------------------------------------------------
 import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir, findProjectRoot, looksLikePath } from "./config.js";
 import { ingestSources } from "./ingest.js";
+import { summarizeSource } from "./source-summary.js";
 import { searchChunks } from "./search.js";
 import { SERVER_COMMANDS, suggestCommands } from "./cli-commands.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
@@ -657,6 +658,7 @@ import { getStagedFiles, runSecretScan, runDocCoverage, runCommitMessageRequired
 import { safeAppend } from "./audit.js";
 import { listServers, formatServers } from "./server-registry.js";
 import { computeFleetHealth, formatFleetHealth } from "./fleet-health.js";
+import { ciStatusForHead, formatCiStatus } from "./ci-status.js";
 import { installSkill, locateBundledSkill, buildManagedBlock, syncClaudeMd, } from "./claude-integration.js";
 import { fileURLToPath } from "url";
 // ---------------------------------------------------------------------------
@@ -742,6 +744,9 @@ async function cliListSources() {
         const count = chunks.filter((c) => c.source === s.name).length;
         const status = exists ? `✅ ${count} chunks` : "⚠ file not found";
         console.log(`  ${s.name}: ${status}`);
+        const summary = exists ? summarizeSource(s) : "";
+        if (summary)
+            console.log(`    ${summary}`);
         console.log(`    ${s.path}`);
     }
     console.log("");
@@ -2238,6 +2243,17 @@ async function cliEndSession() {
     if (fleet.warnings.length > 0)
         failCount += fleet.warnings.length;
     checks.push("");
+    // --- Check 3c: CI on HEAD ([LOCK] [PUSHED-MEANS-CI-READ]) ---
+    checks.push("## 3c. CI on HEAD\n");
+    const ci = ciStatusForHead(process.cwd());
+    checks.push(...formatCiStatus(ci));
+    if (ci.state === "failed") {
+        failCount++;
+        checks.push("- ❌ FAIL: a workflow run for HEAD failed; a push is not done until its CI is");
+    }
+    else if (ci.state === "ok")
+        passCount++;
+    checks.push("");
     checks.push("## 4. Sessions\n");
     const sessions = listSessions();
     if (sessions.length > 0) {

package/dist/firewall.js

@@ -185,7 +185,7 @@ export class ProtocolFirewall {
         if (sessionUrgent && level === "footer")
             level = "header";
         // Prepend learning injection to response (always, if available)
-        let text = injection ? injection + "\n\n" + responseText : responseText;
+        const text = injection ? injection + "\n\n" + responseText : responseText;
         // Build session urgency block (always prepended when overdue)
         const urgentBlock = sessionUrgent ? this.buildSessionUrgentBlock() : null;
         if (level === "silent" && !urgentBlock)

package/dist/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir } from "./config.js";
 import { ingestSources } from "./ingest.js";
+import { summarizeSource } from "./source-summary.js";
 import { searchChunks } from "./search.js";
 import { initEmbeddings, embedChunks, embedKeyOf, vectorSearch, isEmbeddingsReady, } from "./embeddings.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
@@ -575,7 +576,7 @@ server.tool("search_context", "Search across all indexed project knowledge (copi
 // ---------------------------------------------------------------------------
 // Tool: list_sources
 // ---------------------------------------------------------------------------
-server.tool("list_sources", "List all knowledge sources indexed by ContextEngine, with their status (found/missing) and chunk counts.", {}, async () => {
+server.tool("list_sources", "List all knowledge sources indexed by ContextEngine, each with a one-line summary (from the file's own head: frontmatter description, title plus first sentence, or module docstring), status (found/missing) and chunk counts. Read the summary to pick the right source before calling read_source.", {}, async () => {
     const lines = sources.map((s) => {
         const exists = existsSync(s.path);
         const count = chunks.filter((c) => c.source === s.name).length;
@@ -583,7 +584,8 @@ server.tool("list_sources", "List all knowledge sources indexed by ContextEngine
         const status = exists
             ? `✅ ${count} chunks${embeddedCount > 0 ? ` (${embeddedCount} embedded)` : ""}`
             : "⚠ file not found";
-        return `${s.name}: ${status}\n  ${s.path}`;
+        const summary = exists ? summarizeSource(s) : "";
+        return `${s.name}: ${status}${summary ? `\n  ${summary}` : ""}\n  ${s.path}`;
     });
     const embStatus = isEmbeddingsReady()
         ? `✅ ${embeddedChunks.length} vectors`

package/dist/source-summary.d.ts

@@ -0,0 +1,9 @@
+import type { KnowledgeSource } from "./config.js";
+export declare const HEAD_BYTES = 4096;
+export declare const SUMMARY_MAX = 110;
+/** Read at most `bytes` from the start of a file. Empty string on any error. */
+export declare function readHead(path: string, bytes?: number): string;
+/** Summary for a configured source; "" when the file is unreadable or says nothing. */
+export declare function summarizeSource(source: KnowledgeSource): string;
+export declare function summarizeText(text: string, type: "markdown" | "code"): string;
+//# sourceMappingURL=source-summary.d.ts.map

package/dist/source-summary.js

@@ -0,0 +1,150 @@
+/**
+ * One-line summary per knowledge source, for list_sources (MCP) and
+ * `contextengine list-sources` (CLI).
+ *
+ * Why: with 800+ sources, an agent reading a bare name plus a path opens two
+ * or three files to find the right one. Each open puts a whole document into
+ * its context (see CLAUDE.md, multi-agent cost). A summary line derived from
+ * the first few KB of the file lets it pick once.
+ *
+ * Reads only the head of the file (HEAD_BYTES), never the whole document, so
+ * the cost is bounded no matter how many sources are configured.
+ */
+import { openSync, readSync, closeSync } from "fs";
+export const HEAD_BYTES = 4096;
+export const SUMMARY_MAX = 110;
+/** Read at most `bytes` from the start of a file. Empty string on any error. */
+export function readHead(path, bytes = HEAD_BYTES) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+        const buf = Buffer.alloc(bytes);
+        const n = readSync(fd, buf, 0, bytes, 0);
+        return buf.subarray(0, n).toString("utf-8");
+    }
+    catch {
+        return "";
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** Summary for a configured source; "" when the file is unreadable or says nothing. */
+export function summarizeSource(source) {
+    return summarizeText(readHead(source.path), source.type);
+}
+export function summarizeText(text, type) {
+    if (!text)
+        return "";
+    return clip(type === "code" ? summarizeCode(text) : summarizeMarkdown(text));
+}
+function clip(s) {
+    const one = s.replace(/\s+/g, " ").trim();
+    if (one.length <= SUMMARY_MAX)
+        return one;
+    return one.slice(0, SUMMARY_MAX - 3).trimEnd() + "...";
+}
+/** Strip markdown decoration so the line reads as plain text. */
+function plain(line) {
+    return line
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, "") // images
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") // links -> text
+        .replace(/`([^`]*)`/g, "$1") // inline code
+        .replace(/\*\*|__/g, "") // bold
+        .replace(/^\s*(?:[-*+]|\d+[.)])\s+/, "") // list bullet
+        .replace(/^\s*>\s?/, "") // blockquote
+        .trim();
+}
+/** Header metadata lines that say nothing about the content. */
+const META_LINE = /^(updated|last updated|created|date|status|author|owner|version|scope|audience)\b\s*[:\-]/i;
+function summarizeMarkdown(text) {
+    let body = text;
+    // YAML frontmatter: prefer its description, it IS a one-line summary.
+    if (body.startsWith("---\n") || body.startsWith("---\r\n")) {
+        const end = body.indexOf("\n---", 4);
+        if (end !== -1) {
+            const fm = body.slice(4, end);
+            const desc = fm.match(/^description:\s*(.+)$/m);
+            if (desc)
+                return desc[1].trim().replace(/^["']|["']$/g, "");
+            body = body.slice(end + 4);
+        }
+    }
+    let title = "";
+    let prose = "";
+    let inFence = false;
+    for (const raw of body.split("\n")) {
+        const line = raw.trim();
+        if (line.startsWith("```") || line.startsWith("~~~")) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence || !line)
+            continue;
+        if (line.startsWith("<!--") || line.startsWith("|") || line.startsWith("![") || line.startsWith("[!"))
+            continue;
+        if (/^[-=*_]{3,}$/.test(line))
+            continue;
+        if (line.startsWith("#")) {
+            if (!title)
+                title = plain(line.replace(/^#+\s*/, ""));
+            continue;
+        }
+        const p = plain(line);
+        if (p.length < 12)
+            continue; // lone dates, "v2.1", etc.
+        if (META_LINE.test(p))
+            continue; // "Updated: 2026-03-13", "Status: draft"
+        prose = p;
+        break;
+    }
+    if (title && prose)
+        return `${title}: ${prose}`;
+    return title || prose;
+}
+const CODE_SKIP = /^(#!|\/\/\s*eslint|\/\*\s*eslint|@ts-|#\s*-\*-|#\s*coding[:=]|SPDX|Copyright|\[LOCK|\[LOCKED\]|\[NEVER\]|WHY:|FIX:|import |from |export |const |let |var |use strict|"use strict")/i;
+function summarizeCode(text) {
+    const lines = text.split("\n");
+    let inBlock = false;
+    for (const raw of lines) {
+        let line = raw.trim();
+        if (!line)
+            continue;
+        if (!inBlock) {
+            const opensBlock = line.startsWith("/*") || line.startsWith('"""') || line.startsWith("'''");
+            const closesOnSameLine = (line.startsWith("/*") && /\*\/$/.test(line)) ||
+                (/^("""|''')/.test(line) && line.length > 3 && /("""|''')$/.test(line));
+            if (CODE_SKIP.test(line)) {
+                // Pragma, shebang or marker on the raw line: skip it. A one-line
+                // block comment ("/* eslint-disable */") must not leave us in a block.
+                if (opensBlock && !closesOnSameLine)
+                    inBlock = true;
+                continue;
+            }
+            if (opensBlock) {
+                inBlock = !closesOnSameLine;
+                line = line.replace(/^(\/\*+|"""|''')\s*/, "").replace(/(\*\/|"""|''')\s*$/, "").trim();
+            }
+            else if (line.startsWith("//") || line.startsWith("#")) {
+                line = line.replace(/^(\/\/|#)+\s*/, "").trim();
+            }
+            else {
+                // Code before any comment: nothing worth saying about this file.
+                return "";
+            }
+        }
+        else {
+            if (/(\*\/|"""|''')$/.test(line))
+                inBlock = false;
+            line = line.replace(/^\*+\s*/, "").replace(/(\*\/|"""|''')\s*$/, "").trim();
+        }
+        if (!line || /^[-=*_#]{3,}$/.test(line) || CODE_SKIP.test(line))
+            continue;
+        if (line.length < 12)
+            continue;
+        return line;
+    }
+    return "";
+}
+//# sourceMappingURL=source-summary.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "OpsContext for AI Agents — read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident audit log + policy-as-code hooks. The ops + compliance layer Claude Code can't grow natively.",
   "type": "module",
   "main": "dist/index.js",
@@ -59,7 +59,7 @@
     "email": "yannick@compr.ch"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.19.0"
   },
   "files": [
     "dist/",