@danielblomma/cortex-mcp 0.4.5 → 1.0.0

package/scaffold/scripts/install-git-hooks.sh

@@ -10,12 +10,14 @@ if [[ ! -d "$HOOKS_DIR" ]]; then
 fi
 
 chmod +x \
+  "$HOOKS_DIR/post-commit" \
   "$HOOKS_DIR/post-merge" \
   "$HOOKS_DIR/post-checkout" \
+  "$HOOKS_DIR/post-rewrite" \
   "$HOOKS_DIR/_cortex-update-runner.sh"
 
 git -C "$REPO_ROOT" config core.hooksPath .githooks
 
 echo "[hooks] installed core.hooksPath=.githooks"
-echo "[hooks] post-merge + post-checkout now trigger background cortex update"
+echo "[hooks] post-checkout + post-merge + post-commit + post-rewrite now trigger background cortex update"
 echo "[hooks] logs: .context/hooks/update.log"

package/scaffold/scripts/memory-compile.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseFrontmatter, parseStringList } from "../mcp/dist/frontmatter.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function normalizeForWsl(rawPath) {
+  const m = rawPath.match(/^([A-Za-z]):[/\\](.*)/);
+  if (!m) return rawPath;
+  try { if (!/microsoft|wsl/i.test(fs.readFileSync("/proc/version", "utf8"))) return rawPath; }
+  catch { return rawPath; }
+  return `/mnt/${m[1].toLowerCase()}/${m[2].replace(/\\/g, "/").replace(/\/+$/, "")}`;
+}
+
+const REPO_ROOT = process.env.CORTEX_PROJECT_ROOT
+  ? path.resolve(normalizeForWsl(process.env.CORTEX_PROJECT_ROOT))
+  : path.resolve(__dirname, "..");
+const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
+const MEMORY_DIR = path.join(CONTEXT_DIR, "memory");
+const RAW_DIR = path.join(MEMORY_DIR, "raw");
+const COMPILED_DIR = path.join(MEMORY_DIR, "compiled");
+
+const ALLOWED_TYPES = new Set([
+  "decision",
+  "gotcha",
+  "fix",
+  "benchmark",
+  "migration-note",
+  "note"
+]);
+
+const REQUIRED_FIELDS = ["title", "type", "summary"];
+
+// ── ID generation ──────────────────────────────────────────
+
+function normalizeId(filename) {
+  const base = path.basename(filename, path.extname(filename)).toLowerCase();
+  return `memory:${base.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "")}`;
+}
+
+// ── Validation ─────────────────────────────────────────────
+
+function validate(rawPath, fields, body) {
+  const errors = [];
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!fields.get(field)) {
+      errors.push(`missing required field: ${field}`);
+    }
+  }
+
+  const memoryType = fields.get("type") || "";
+  if (memoryType && !ALLOWED_TYPES.has(memoryType)) {
+    errors.push(`unknown type "${memoryType}" (allowed: ${[...ALLOWED_TYPES].join(", ")})`);
+  }
+
+  if (!body) {
+    errors.push("empty body — compiled articles need explanatory text");
+  }
+
+  return errors;
+}
+
+// ── Supersession detection ─────────────────────────────────
+
+function detectSuperseded(compiledArticles) {
+  const byTarget = new Map();
+  for (const article of compiledArticles) {
+    for (const target of article.appliesTo) {
+      const list = byTarget.get(target) ?? [];
+      list.push(article);
+      byTarget.set(target, list);
+    }
+  }
+
+  const warnings = [];
+  for (const [target, articles] of byTarget) {
+    if (articles.length > 1) {
+      const ids = articles.map((a) => a.id).join(", ");
+      warnings.push(`multiple memories for ${target}: ${ids} — consider adding supersedes field`);
+    }
+  }
+  return warnings;
+}
+
+// ── Compiled article serialization ─────────────────────────
+
+function serializeCompiled(article) {
+  const lines = ["---"];
+  lines.push(`id: ${article.id}`);
+  lines.push(`title: ${article.title}`);
+  lines.push(`type: ${article.type}`);
+  lines.push(`summary: ${article.summary}`);
+
+  if (article.evidence) lines.push(`evidence: ${article.evidence}`);
+  if (article.appliesTo.length > 0) lines.push(`applies_to: ${article.appliesTo.join(", ")}`);
+  if (article.decisionOrGotcha) lines.push(`decision_or_gotcha: ${article.decisionOrGotcha}`);
+  if (article.sources.length > 0) lines.push(`sources: ${article.sources.join(", ")}`);
+  if (article.supersedes) lines.push(`supersedes: ${article.supersedes}`);
+  lines.push(`freshness: ${article.freshness}`);
+  lines.push(`updated_at: ${article.updatedAt}`);
+  lines.push(`status: ${article.status}`);
+  lines.push(`trust_level: ${article.trustLevel}`);
+  if (article.sourceOfTruth) lines.push(`source_of_truth: true`);
+
+  lines.push("---");
+  lines.push("");
+  lines.push(article.body);
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+// ── Main compile pipeline ──────────────────────────────────
+
+function compileRawNote(rawPath) {
+  const markdown = fs.readFileSync(rawPath, "utf8");
+  const stats = fs.statSync(rawPath);
+  const { fields, body } = parseFrontmatter(markdown);
+  const filename = path.basename(rawPath);
+
+  const errors = validate(rawPath, fields, body);
+  if (errors.length > 0) {
+    return { ok: false, rawPath, errors };
+  }
+
+  const article = {
+    id: fields.get("id") || normalizeId(filename),
+    title: fields.get("title"),
+    type: fields.get("type"),
+    summary: fields.get("summary"),
+    evidence: fields.get("evidence") || "",
+    appliesTo: parseStringList(fields.get("applies_to")),
+    decisionOrGotcha: fields.get("decision_or_gotcha") || fields.get("decision") || "",
+    sources: parseStringList(fields.get("sources")),
+    supersedes: fields.get("supersedes") || "",
+    freshness: fields.get("freshness") || "current",
+    updatedAt: fields.get("updated_at") || stats.mtime.toISOString(),
+    status: fields.get("status") || "active",
+    trustLevel: Number(fields.get("trust_level")) || 70,
+    sourceOfTruth: fields.get("source_of_truth")?.toLowerCase() === "true",
+    body
+  };
+
+  return { ok: true, rawPath, article };
+}
+
+function run() {
+  const verbose = process.argv.includes("--verbose");
+  const dryRun = process.argv.includes("--dry-run");
+
+  if (!fs.existsSync(RAW_DIR)) {
+    console.log(`[memory-compile] no raw directory at ${RAW_DIR} — nothing to compile`);
+    console.log(`[memory-compile] create ${RAW_DIR} and add .md notes to get started`);
+    process.exit(0);
+  }
+
+  const rawFiles = fs.readdirSync(RAW_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".md"))
+    .map((entry) => entry.name)
+    .sort();
+
+  if (rawFiles.length === 0) {
+    console.log("[memory-compile] no raw .md files found — nothing to compile");
+    process.exit(0);
+  }
+
+  console.log(`[memory-compile] found ${rawFiles.length} raw note(s)`);
+
+  fs.mkdirSync(COMPILED_DIR, { recursive: true });
+
+  const results = rawFiles.map((filename) =>
+    compileRawNote(path.join(RAW_DIR, filename))
+  );
+
+  const successes = results.filter((r) => r.ok);
+  const failures = results.filter((r) => !r.ok);
+
+  // Report validation failures
+  for (const failure of failures) {
+    console.log(`[memory-compile] SKIP ${path.basename(failure.rawPath)}:`);
+    for (const error of failure.errors) {
+      console.log(`  - ${error}`);
+    }
+  }
+
+  // Detect supersession warnings
+  const articles = successes.map((r) => r.article);
+  const supersessionWarnings = detectSuperseded(articles);
+  for (const warning of supersessionWarnings) {
+    console.log(`[memory-compile] WARN ${warning}`);
+  }
+
+  // Write compiled articles
+  let written = 0;
+  let skipped = 0;
+
+  for (const { article, rawPath } of successes) {
+    const outputFilename = path.basename(rawPath);
+    const outputPath = path.join(COMPILED_DIR, outputFilename);
+    const compiled = serializeCompiled(article);
+
+    // Skip if compiled output is identical to existing
+    if (fs.existsSync(outputPath)) {
+      const existing = fs.readFileSync(outputPath, "utf8");
+      if (existing === compiled) {
+        if (verbose) console.log(`[memory-compile] unchanged: ${outputFilename}`);
+        skipped++;
+        continue;
+      }
+    }
+
+    if (dryRun) {
+      console.log(`[memory-compile] would write: ${outputFilename} (${article.id})`);
+      if (verbose) console.log(compiled);
+    } else {
+      fs.writeFileSync(outputPath, compiled, "utf8");
+      console.log(`[memory-compile] compiled: ${outputFilename} → ${article.id}`);
+    }
+    written++;
+  }
+
+  console.log("");
+  console.log(`[memory-compile] ${dryRun ? "dry-run " : ""}summary:`);
+  console.log(`  compiled: ${written}`);
+  console.log(`  skipped (unchanged): ${skipped}`);
+  console.log(`  failed: ${failures.length}`);
+  if (supersessionWarnings.length > 0) {
+    console.log(`  supersession warnings: ${supersessionWarnings.length}`);
+  }
+  console.log(`  total raw: ${rawFiles.length}`);
+
+  if (failures.length > 0) {
+    process.exit(1);
+  }
+}
+
+run();

package/scaffold/scripts/memory-compile.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Keep in sync with scripts/memory-compile.sh
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CONTEXT_DIR="$REPO_ROOT/.context"
+
+printf "[memory-compile] repo: %s\n" "$REPO_ROOT"
+
+if [[ ! -d "$CONTEXT_DIR" ]]; then
+  echo "[memory-compile] missing .context/ directory — run cortex init first"
+  exit 1
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "[memory-compile] Node.js is required but not found on PATH"
+  exit 1
+fi
+
+node "$REPO_ROOT/scripts/memory-compile.mjs" "$@"

package/scaffold/scripts/memory-lint.mjs

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseFrontmatter, parseStringList } from "../mcp/dist/frontmatter.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function normalizeForWsl(rawPath) {
+  const m = rawPath.match(/^([A-Za-z]):[/\\](.*)/);
+  if (!m) return rawPath;
+  try { if (!/microsoft|wsl/i.test(fs.readFileSync("/proc/version", "utf8"))) return rawPath; }
+  catch { return rawPath; }
+  return `/mnt/${m[1].toLowerCase()}/${m[2].replace(/\\/g, "/").replace(/\/+$/, "")}`;
+}
+
+const REPO_ROOT = process.env.CORTEX_PROJECT_ROOT
+  ? path.resolve(normalizeForWsl(process.env.CORTEX_PROJECT_ROOT))
+  : path.resolve(__dirname, "..");
+const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
+const MEMORY_DIR = path.join(CONTEXT_DIR, "memory");
+const COMPILED_DIR = path.join(MEMORY_DIR, "compiled");
+const CACHE_DIR = path.join(CONTEXT_DIR, "cache");
+
+const ALLOWED_TYPES = new Set([
+  "decision",
+  "gotcha",
+  "fix",
+  "benchmark",
+  "migration-note",
+  "note"
+]);
+
+const REQUIRED_FIELDS = ["title", "type", "summary"];
+
+const STALE_DAYS = 90;
+
+// ── Index loading ─────────────────────────────────────────
+
+function readJsonl(filePath) {
+  if (!fs.existsSync(filePath)) return [];
+  return fs
+    .readFileSync(filePath, "utf8")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try { return JSON.parse(line); }
+      catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+function loadKnownEntityIds() {
+  const ids = new Set();
+
+  for (const row of readJsonl(path.join(CACHE_DIR, "documents.jsonl"))) {
+    if (row.id) ids.add(row.id);
+  }
+  for (const row of readJsonl(path.join(CACHE_DIR, "entities.adr.jsonl"))) {
+    if (row.id) ids.add(row.id);
+  }
+  for (const row of readJsonl(path.join(CACHE_DIR, "entities.rule.jsonl"))) {
+    if (row.id) ids.add(row.id);
+  }
+  for (const row of readJsonl(path.join(CACHE_DIR, "entities.chunk.jsonl"))) {
+    if (row.id) ids.add(row.id);
+  }
+
+  return ids;
+}
+
+function loadKnownFilePaths() {
+  const paths = new Set();
+  for (const row of readJsonl(path.join(CACHE_DIR, "documents.jsonl"))) {
+    if (row.path) paths.add(row.path);
+  }
+  return paths;
+}
+
+// ── Compiled article loading ──────────────────────────────
+
+function loadCompiledArticles() {
+  if (!fs.existsSync(COMPILED_DIR)) return [];
+
+  return fs
+    .readdirSync(COMPILED_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".md"))
+    .map((entry) => entry.name)
+    .sort()
+    .map((filename) => {
+      const absolutePath = path.join(COMPILED_DIR, filename);
+      const markdown = fs.readFileSync(absolutePath, "utf8");
+      const stats = fs.statSync(absolutePath);
+      const { fields, body } = parseFrontmatter(markdown);
+
+      return {
+        filename,
+        id: fields.get("id") || "",
+        title: fields.get("title") || "",
+        type: fields.get("type") || "",
+        summary: fields.get("summary") || "",
+        evidence: fields.get("evidence") || "",
+        appliesTo: parseStringList(fields.get("applies_to")),
+        decisionOrGotcha: fields.get("decision_or_gotcha") || fields.get("decision") || "",
+        sources: parseStringList(fields.get("sources")),
+        supersedes: fields.get("supersedes") || "",
+        freshness: fields.get("freshness") || "",
+        updatedAt: fields.get("updated_at") || stats.mtime.toISOString(),
+        status: fields.get("status") || "active",
+        trustLevel: Number(fields.get("trust_level")) || 70,
+        sourceOfTruth: fields.get("source_of_truth")?.toLowerCase() === "true",
+        body
+      };
+    });
+}
+
+// ── Lint checks ───────────────────────────────────────────
+
+function checkMissingProvenance(article) {
+  const issues = [];
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!article[field]) {
+      issues.push({ severity: "error", file: article.filename, message: `missing required field: ${field}` });
+    }
+  }
+
+  if (!article.id) {
+    issues.push({ severity: "error", file: article.filename, message: "missing id field" });
+  }
+
+  const memoryType = article.type;
+  if (memoryType && !ALLOWED_TYPES.has(memoryType)) {
+    issues.push({
+      severity: "error",
+      file: article.filename,
+      message: `unknown type "${memoryType}" (allowed: ${[...ALLOWED_TYPES].join(", ")})`
+    });
+  }
+
+  if (!article.body) {
+    issues.push({ severity: "error", file: article.filename, message: "empty body" });
+  }
+
+  if (article.appliesTo.length === 0 && article.sources.length === 0) {
+    issues.push({
+      severity: "warn",
+      file: article.filename,
+      message: "no applies_to or sources — memory has no link to codebase"
+    });
+  }
+
+  return issues;
+}
+
+function checkOrphaned(article, knownEntityIds, knownFilePaths) {
+  const issues = [];
+
+  for (const target of article.appliesTo) {
+    if (!knownEntityIds.has(target)) {
+      issues.push({
+        severity: "warn",
+        file: article.filename,
+        message: `applies_to target not found in index: ${target}`
+      });
+    }
+  }
+
+  for (const source of article.sources) {
+    const asFileId = `file:${source}`;
+    if (!knownEntityIds.has(asFileId) && !knownFilePaths.has(source)) {
+      issues.push({
+        severity: "warn",
+        file: article.filename,
+        message: `source file not found in index: ${source}`
+      });
+    }
+  }
+
+  return issues;
+}
+
+function checkStale(article) {
+  const issues = [];
+
+  if (article.freshness.toLowerCase() === "stale") {
+    issues.push({
+      severity: "warn",
+      file: article.filename,
+      message: "freshness is marked stale"
+    });
+    return issues;
+  }
+
+  if (!article.updatedAt) return issues;
+
+  const updatedDate = new Date(article.updatedAt);
+  if (isNaN(updatedDate.getTime())) return issues;
+
+  const ageMs = Date.now() - updatedDate.getTime();
+  const ageDays = ageMs / (1000 * 60 * 60 * 24);
+
+  if (ageDays > STALE_DAYS) {
+    issues.push({
+      severity: "warn",
+      file: article.filename,
+      message: `updated_at is ${Math.floor(ageDays)} days old (threshold: ${STALE_DAYS} days)`
+    });
+  }
+
+  return issues;
+}
+
+function checkDuplicates(articles) {
+  const issues = [];
+  const byId = new Map();
+
+  for (const article of articles) {
+    if (!article.id) continue;
+    const list = byId.get(article.id) ?? [];
+    list.push(article);
+    byId.set(article.id, list);
+  }
+
+  for (const [id, group] of byId) {
+    if (group.length > 1) {
+      const files = group.map((a) => a.filename).join(", ");
+      issues.push({
+        severity: "error",
+        file: group[0].filename,
+        message: `duplicate memory id "${id}" in files: ${files}`
+      });
+    }
+  }
+
+  return issues;
+}
+
+function checkContradictions(articles) {
+  const issues = [];
+  const activeArticles = articles.filter((a) => a.status === "active");
+
+  // Group active articles by applies_to target
+  const byTarget = new Map();
+  for (const article of activeArticles) {
+    for (const target of article.appliesTo) {
+      const list = byTarget.get(target) ?? [];
+      list.push(article);
+      byTarget.set(target, list);
+    }
+  }
+
+  // Conflicting types on the same target signal potential contradiction
+  const conflictingPairs = new Set(["decision|decision", "gotcha|fix", "fix|fix", "decision|gotcha"]);
+
+  for (const [target, group] of byTarget) {
+    if (group.length < 2) continue;
+
+    for (let i = 0; i < group.length; i++) {
+      for (let j = i + 1; j < group.length; j++) {
+        const a = group[i];
+        const b = group[j];
+
+        // Skip if one supersedes the other
+        if (a.supersedes === b.id || b.supersedes === a.id) continue;
+
+        const pair = [a.type, b.type].sort().join("|");
+        if (conflictingPairs.has(pair)) {
+          issues.push({
+            severity: "warn",
+            file: a.filename,
+            message: `potential contradiction on ${target}: "${a.id}" (${a.type}) vs "${b.id}" (${b.type})`
+          });
+        }
+      }
+    }
+  }
+
+  // Check for broken supersedes references
+  const allIds = new Set(articles.map((a) => a.id));
+  for (const article of articles) {
+    if (!article.supersedes) continue;
+    if (!allIds.has(article.supersedes)) {
+      issues.push({
+        severity: "warn",
+        file: article.filename,
+        message: `supersedes target "${article.supersedes}" not found among compiled articles`
+      });
+    }
+  }
+
+  return issues;
+}
+
+// ── Main ──────────────────────────────────────────────────
+
+function run() {
+  const verbose = process.argv.includes("--verbose");
+  const json = process.argv.includes("--json");
+
+  if (!fs.existsSync(COMPILED_DIR)) {
+    if (json) {
+      console.log(JSON.stringify({ issues: [], summary: { errors: 0, warnings: 0, articles: 0 } }));
+    } else {
+      console.log("[memory-lint] no compiled directory — nothing to lint");
+    }
+    process.exit(0);
+  }
+
+  const articles = loadCompiledArticles();
+
+  if (articles.length === 0) {
+    if (json) {
+      console.log(JSON.stringify({ issues: [], summary: { errors: 0, warnings: 0, articles: 0 } }));
+    } else {
+      console.log("[memory-lint] no compiled articles found");
+    }
+    process.exit(0);
+  }
+
+  const knownEntityIds = loadKnownEntityIds();
+  const knownFilePaths = loadKnownFilePaths();
+
+  const allIssues = [];
+
+  // Per-article checks
+  for (const article of articles) {
+    allIssues.push(...checkMissingProvenance(article));
+    allIssues.push(...checkOrphaned(article, knownEntityIds, knownFilePaths));
+    allIssues.push(...checkStale(article));
+  }
+
+  // Cross-article checks
+  allIssues.push(...checkDuplicates(articles));
+  allIssues.push(...checkContradictions(articles));
+
+  const errors = allIssues.filter((i) => i.severity === "error");
+  const warnings = allIssues.filter((i) => i.severity === "warn");
+
+  if (json) {
+    console.log(JSON.stringify({
+      issues: allIssues,
+      summary: { errors: errors.length, warnings: warnings.length, articles: articles.length }
+    }, null, 2));
+    process.exit(errors.length > 0 ? 1 : 0);
+  }
+
+  console.log(`[memory-lint] linting ${articles.length} compiled article(s)`);
+  console.log("");
+
+  if (allIssues.length === 0) {
+    console.log("[memory-lint] no issues found");
+    process.exit(0);
+  }
+
+  // Group issues by file for readable output
+  const byFile = new Map();
+  for (const issue of allIssues) {
+    const list = byFile.get(issue.file) ?? [];
+    list.push(issue);
+    byFile.set(issue.file, list);
+  }
+
+  for (const [file, issues] of byFile) {
+    console.log(`  ${file}:`);
+    for (const issue of issues) {
+      const prefix = issue.severity === "error" ? "ERROR" : "WARN";
+      console.log(`    ${prefix}: ${issue.message}`);
+    }
+    if (verbose) console.log("");
+  }
+
+  console.log("");
+  console.log(`[memory-lint] summary:`);
+  console.log(`  articles: ${articles.length}`);
+  console.log(`  errors: ${errors.length}`);
+  console.log(`  warnings: ${warnings.length}`);
+
+  process.exit(errors.length > 0 ? 1 : 0);
+}
+
+run();

package/scaffold/scripts/memory-lint.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Keep in sync with scripts/memory-lint.sh
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CONTEXT_DIR="$REPO_ROOT/.context"
+
+printf "[memory-lint] repo: %s\n" "$REPO_ROOT"
+
+if [[ ! -d "$CONTEXT_DIR" ]]; then
+  echo "[memory-lint] missing .context/ directory — run cortex init first"
+  exit 1
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "[memory-lint] Node.js is required but not found on PATH"
+  exit 1
+fi
+
+node "$REPO_ROOT/scripts/memory-lint.mjs" "$@"