codex-dev-mcp-suite 1.1.0 → 1.3.0

package/devjournal/rerank.js

@@ -1,14 +1,14 @@
 /**
  * LLM reranker via any OpenAI-compatible /v1/chat/completions model.
- * Used when embeddings are unavailable: keyword prefilter -> LLM picks the
- * most relevant candidates. Degrades gracefully: returns null on any failure
- * so callers fall back to keyword ordering. Never throws.
+ * Tries provider chain slots in order, skipping any currently cooling down
+ * after a recent failure. Degrades gracefully: returns null on any failure so
+ * callers fall back to keyword ordering. Never throws. Never logs keys/bodies.
  */
 import http from "http";
 import https from "https";
 import { URL } from "url";
 import { deterministicEnabled } from "./env.js";
-import { providerChainConfig } from "./provider-chain.js";
+import { providerChainConfig, isCoolingDown, recordOutcome } from "./provider-chain.js";
 
 const TIMEOUT_MS = Number(process.env.RERANK_TIMEOUT_MS || 30000);
 const ENABLED = process.env.RERANK_ENABLED !== "0";
@@ -25,10 +25,19 @@ export function rerankConfig() {
   };
 }
 
+function providerKey(provider) {
+  return `${provider.label}|${provider.base}|${provider.model}`;
+}
+
+/**
+ * Resolves { content, retryable }. retryable=true means try the next provider
+ * (timeout, network error, 429, or 5xx). retryable=false with null content
+ * means a definitive non-retryable response (e.g. 4xx auth).
+ */
 function chatWithProvider(provider, messages) {
   return new Promise((resolve) => {
     let u;
-    try { u = new URL("/v1/chat/completions", provider.base); } catch { return resolve(null); }
+    try { u = new URL("/v1/chat/completions", provider.base); } catch { return resolve({ content: null, retryable: false }); }
     const payload = Buffer.from(JSON.stringify({ model: provider.model, stream: false, temperature: 0, max_tokens: 200, messages }));
     const lib = u.protocol === "https:" ? https : http;
     const req = lib.request(
@@ -44,10 +53,14 @@ function chatWithProvider(provider, messages) {
         let body = "";
         res.on("data", (c) => (body += c));
         res.on("end", () => {
-          if (res.statusCode !== 200) return resolve(null);
+          const status = res.statusCode || 0;
+          if (status !== 200) {
+            const retryable = status === 429 || status >= 500;
+            return resolve({ content: null, retryable });
+          }
           try {
             const j = JSON.parse(body);
-            return resolve(j?.choices?.[0]?.message?.content ?? null);
+            return resolve({ content: j?.choices?.[0]?.message?.content ?? null, retryable: false });
           } catch { /* maybe SSE */ }
           try {
             let acc = "";
@@ -59,13 +72,13 @@ function chatWithProvider(provider, messages) {
               const j = JSON.parse(d);
               acc += j?.choices?.[0]?.delta?.content || j?.choices?.[0]?.message?.content || "";
             }
-            return resolve(acc || null);
-          } catch { return resolve(null); }
+            return resolve({ content: acc || null, retryable: false });
+          } catch { return resolve({ content: null, retryable: true }); }
         });
       }
     );
-    req.on("error", () => resolve(null));
-    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.on("error", () => resolve({ content: null, retryable: true }));
+    req.on("timeout", () => { req.destroy(); resolve({ content: null, retryable: true }); });
     req.write(payload);
     req.end();
   });
@@ -75,8 +88,11 @@ async function chat(messages) {
   if (!ENABLED || deterministicEnabled()) return null;
   const { providers } = providerChainConfig();
   for (const provider of providers) {
-    const out = await chatWithProvider(provider, messages);
-    if (out) return out;
+    const key = providerKey(provider);
+    if (isCoolingDown(key)) continue;
+    const { content, retryable } = await chatWithProvider(provider, messages);
+    if (content) { recordOutcome(key, true); return content; }
+    if (retryable) recordOutcome(key, false);
   }
   return null;
 }

package/docs/configuration.md

@@ -73,6 +73,20 @@ MCP_PROVIDER_CHAIN3_MODEL=openai/gpt-4o-mini
 
 You can add `MCP_PROVIDER_CHAIN4_*`, `MCP_PROVIDER_CHAIN5_*`, and so on. The provider name is only a label; any OpenAI-compatible endpoint works when `BASE_URL`, `API_KEY`, and `MODEL` are set.
 
+On a `429`, `5xx`, timeout, or network error, a provider is put on a short cooldown and the next slot is tried. Tune the window with `MCP_PROVIDER_COOLDOWN_MS` (default `60000`).
+
+## Diagnostics
+
+Each server bin supports inspection flags that never start the server:
+
+```bash
+project-memory-mcp --version
+project-memory-mcp --doctor   # storage + model/provider config, API keys redacted
+project-memory-mcp --help
+```
+
+`--doctor` reports configured providers and storage paths and shows API keys only as `set (<n> chars)` or `not set`, never the raw value.
+
 Example OpenRouter-style config:
 
 ```bash

package/lib/prune.js

@@ -0,0 +1,114 @@
+/**
+ * Dev MCP Suite — prune library.
+ *
+ * Identifies and removes "temp" project slugs (prefix `tmp.`) from all three
+ * stores. Used by `bin/prune.mjs`. No MCP, no stdio — safe to import from tests.
+ *
+ * Storage layout (matches the rest of the suite):
+ *   <root>/vault/<slug>/
+ *   <root>/journal/<slug>/
+ *   <root>/checkpoints/<slug>/
+ */
+
+import fs from "fs";
+import path from "path";
+
+export const STORES = ["vault", "journal", "checkpoints"];
+const TEMP_PREFIX = "tmp.";
+
+/** Returns the list of slug names matching temp pattern across all stores. */
+export function findTempSlugs({ root }) {
+  const set = new Set();
+  for (const store of STORES) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(path.join(root, store), { withFileTypes: true });
+    } catch { continue; }
+    for (const e of entries) {
+      if (e.isDirectory() && e.name.startsWith(TEMP_PREFIX)) set.add(e.name);
+    }
+  }
+  return [...set].sort();
+}
+
+/** Recursively sum bytes under each slug's directories across stores. */
+export function estimateBytes({ root, slugs }) {
+  let total = 0;
+  for (const slug of slugs) {
+    for (const store of STORES) {
+      total += dirSize(path.join(root, store, slug));
+    }
+  }
+  return total;
+}
+
+function dirSize(p) {
+  let total = 0;
+  let stack = [p];
+  while (stack.length) {
+    const cur = stack.pop();
+    let stat;
+    try { stat = fs.lstatSync(cur); } catch { continue; }
+    if (stat.isDirectory()) {
+      let children = [];
+      try { children = fs.readdirSync(cur); } catch { continue; }
+      for (const c of children) stack.push(path.join(cur, c));
+    } else {
+      total += stat.size;
+    }
+  }
+  return total;
+}
+
+/** Validate slugs only contain temp prefix — refuse to delete otherwise. */
+function assertTempSlugs(slugs) {
+  for (const s of slugs) {
+    if (!s.startsWith(TEMP_PREFIX)) {
+      throw new Error(`refusing to remove non-temp slug: "${s}" (must start with "${TEMP_PREFIX}")`);
+    }
+  }
+}
+
+/** Compute a plan: per-slug list of stores where the dir exists + total bytes. */
+export function planPrune({ root }) {
+  const slugs = findTempSlugs({ root });
+  return slugs.map((slug) => {
+    const stores = [];
+    for (const store of STORES) {
+      const p = path.join(root, store, slug);
+      try {
+        if (fs.existsSync(p)) stores.push(store);
+      } catch { /* ignore */ }
+    }
+    const bytes = estimateBytes({ root, slugs: [slug] });
+    return { slug, stores, bytes };
+  });
+}
+
+/**
+ * Remove temp slugs from all stores. Default is dry-run (no deletion).
+ * @param {{ root: string, slugs: string[], dryRun?: boolean }} opts
+ * @returns {{ removed: string[], skipped: string[], errors: Array<{slug:string,store:string,error:string}> }}
+ */
+export function applyPrune({ root, slugs, dryRun = true }) {
+  assertTempSlugs(slugs);
+  const removed = [];
+  const skipped = [];
+  const errors = [];
+  for (const slug of slugs) {
+    let anyRemoved = false;
+    for (const store of STORES) {
+      const p = path.join(root, store, slug);
+      if (!fs.existsSync(p)) continue;
+      if (dryRun) { skipped.push(slug); continue; }
+      try {
+        fs.rmSync(p, { recursive: true, force: true });
+        anyRemoved = true;
+      } catch (e) {
+        errors.push({ slug, store, error: String(e && e.message || e) });
+      }
+    }
+    if (anyRemoved) removed.push(slug);
+  }
+  return { removed, skipped, errors };
+}

package/lib/stats.js

@@ -0,0 +1,269 @@
+/**
+ * Dev MCP Suite — stats aggregation library.
+ *
+ * Pure functions for summarizing local memory storage across the three stores
+ * (vault / journal / checkpoints). No MCP, no stdio — used by bin/stats.mjs
+ * and safe to import from tests.
+ *
+ * Storage layout assumed (see each MCP server's server.js for source of truth):
+ *   <root>/vault/<slug>/notes/*.md            (one .md per memory_save note)
+ *   <root>/journal/<slug>/journal.jsonl       (append-only entries)
+ *   <root>/journal/<slug>/handoff.json        (optional)
+ *   <root>/checkpoints/<slug>/snapshots/<id>/ (one dir per snapshot)
+ *   <root>/checkpoints/<slug>/manifest.json   (checkpoint index)
+ */
+
+import fs from "fs";
+import path from "path";
+
+const VAULT_DIRNAME = "vault";
+const JOURNAL_DIRNAME = "journal";
+const CHECKPOINT_DIRNAME = "checkpoints";
+
+function safeListDirs(parent) {
+  try {
+    return fs
+      .readdirSync(parent, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+function safeListFiles(parent) {
+  try {
+    return fs.readdirSync(parent);
+  } catch {
+    return [];
+  }
+}
+
+function newestMtimeMs(dir) {
+  try {
+    const stat = fs.statSync(dir);
+    return stat.mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function isoFromMs(ms) {
+  if (!ms) return null;
+  return new Date(ms).toISOString();
+}
+
+function isTempSlug(slug) {
+  return /^tmp\./.test(slug);
+}
+
+function summarizeProject(slug, { root }) {
+  const vaultDir = path.join(root, VAULT_DIRNAME, slug);
+  const journalDir = path.join(root, JOURNAL_DIRNAME, slug);
+  const cpDir = path.join(root, CHECKPOINT_DIRNAME, slug);
+
+  const notesDir = path.join(vaultDir, "notes");
+  const notes = safeListFiles(notesDir).filter((f) => f.endsWith(".md")).length;
+
+  let journalEntries = 0;
+  let lastEntryTs = null;
+  const jl = path.join(journalDir, "journal.jsonl");
+  if (fs.existsSync(jl)) {
+    try {
+      const lines = fs.readFileSync(jl, "utf8").split("\n").filter(Boolean);
+      journalEntries = lines.length;
+      // journal entries are append-only and roughly time-ordered; parse first + last
+      for (const line of lines) {
+        try {
+          const obj = JSON.parse(line);
+          if (obj && obj.ts) {
+            if (!lastEntryTs || obj.ts > lastEntryTs) lastEntryTs = obj.ts;
+          }
+        } catch { /* skip malformed */ }
+      }
+    } catch { /* ignore read errors */ }
+  }
+
+  // checkpoints: count snapshot dirs
+  let checkpoints = 0;
+  const snapsDir = path.join(cpDir, "snapshots");
+  if (fs.existsSync(snapsDir)) {
+    checkpoints = safeListDirs(snapsDir).length;
+  }
+
+  // last activity across all artifacts (mtime fallback)
+  let lastActivityMs = 0;
+  for (const d of [vaultDir, journalDir, cpDir]) {
+    const m = newestMtimeMs(d);
+    if (m > lastActivityMs) lastActivityMs = m;
+  }
+  // prefer parsed entry ts if newer than filesystem mtime
+  if (lastEntryTs) {
+    const t = Date.parse(lastEntryTs);
+    if (!Number.isNaN(t) && t > lastActivityMs) lastActivityMs = t;
+  }
+  const lastActivityTs = isoFromMs(lastActivityMs);
+
+  return {
+    slug,
+    notes,
+    journalEntries,
+    checkpoints,
+    lastActivityTs,
+    temp: isTempSlug(slug),
+  };
+}
+
+/**
+ * Compute aggregate stats for a memory root.
+ * @param {object} opts
+ * @param {string} opts.root - absolute path to memories root (containing vault/, journal/, checkpoints/)
+ * @param {number} [opts.topLimit=10] - max entries in topByNotes / recentActivity
+ * @returns {{
+ *   root: string,
+ *   totals: { notes: number, journalProjects: number, checkpoints: number },
+ *   projectCount: number,
+ *   topByNotes: Array<{ slug: string, notes: number }>,
+ *   recentActivity: Array<{ slug: string, ts: string }>,
+ *   tempSlugs: string[],
+ *   perProject: Array<{ slug: string, notes: number, journalEntries: number, checkpoints: number, lastActivityTs: string|null, temp: boolean }>,
+ * }}
+ */
+export function computeStats({ root, topLimit = 10 } = {}) {
+  if (!root) throw new Error("computeStats: `root` is required");
+
+  // union of slugs across all three stores
+  const slugSet = new Set();
+  for (const store of [VAULT_DIRNAME, JOURNAL_DIRNAME, CHECKPOINT_DIRNAME]) {
+    for (const slug of safeListDirs(path.join(root, store))) slugSet.add(slug);
+  }
+
+  const perProject = [...slugSet]
+    .map((slug) => summarizeProject(slug, { root }))
+    .sort((a, b) => {
+      if (a.temp !== b.temp) return a.temp ? 1 : -1; // real first
+      return a.slug.localeCompare(b.slug);
+    });
+
+  const totals = perProject.reduce(
+    (acc, p) => ({
+      notes: acc.notes + p.notes,
+      journalProjects: acc.journalProjects + (p.journalEntries > 0 ? 1 : 0),
+      checkpoints: acc.checkpoints + p.checkpoints,
+    }),
+    { notes: 0, journalProjects: 0, checkpoints: 0 },
+  );
+
+  const topByNotes = [...perProject]
+    .filter((p) => p.notes > 0)
+    .sort((a, b) => b.notes - a.notes || a.slug.localeCompare(b.slug))
+    .slice(0, topLimit)
+    .map((p) => ({ slug: p.slug, notes: p.notes }));
+
+  const recentActivity = [...perProject]
+    .filter((p) => p.lastActivityTs && !p.temp)
+    .sort((a, b) => (a.lastActivityTs < b.lastActivityTs ? 1 : -1))
+    .slice(0, topLimit)
+    .map((p) => ({ slug: p.slug, ts: p.lastActivityTs }));
+
+  const tempSlugs = perProject.filter((p) => p.temp).map((p) => p.slug).sort();
+
+  return {
+    root,
+    totals,
+    projectCount: perProject.length,
+    topByNotes,
+    recentActivity,
+    tempSlugs,
+    perProject,
+  };
+}
+
+/** Right-pad a slug to a fixed display width. */
+function pad(s, w) {
+  s = String(s);
+  if (s.length >= w) return s + " ";
+  return s + " ".repeat(w - s.length);
+}
+function rpadNum(n, w) {
+  const s = String(n);
+  return s.length >= w ? s : " ".repeat(w - s.length) + s;
+}
+
+function formatLocal(ts) {
+  if (!ts) return "—";
+  try {
+    return new Date(ts).toISOString().replace("T", " ").replace(/\.\d+Z$/, "Z");
+  } catch {
+    return ts;
+  }
+}
+
+/**
+ * Human-readable text summary.
+ * @param {ReturnType<typeof computeStats>} stats
+ * @param {object} [opts]
+ * @param {string} [opts.timezone="UTC"] - display-only label, not used to convert
+ */
+export function formatText(stats, opts = {}) {
+  const lines = [];
+  lines.push("Dev MCP Suite — stats");
+  lines.push("======================");
+  lines.push(`Storage root: ${stats.root}`);
+  lines.push("");
+  lines.push("Totals");
+  lines.push("------");
+  lines.push(`  Notes:           ${stats.totals.notes}`);
+  lines.push(`  Journal projects:${rpadNum(stats.totals.journalProjects, 2)}`);
+  lines.push(`  Checkpoints:     ${stats.totals.checkpoints}`);
+  lines.push(`  Distinct projects: ${stats.projectCount}`);
+  lines.push("");
+
+  if (stats.topByNotes.length) {
+    lines.push(`Top projects by notes (top ${stats.topByNotes.length})`);
+    lines.push("------------------------");
+    const slugW = Math.max(8, ...stats.topByNotes.map((p) => p.slug.length));
+    for (const p of stats.topByNotes) {
+      lines.push(`  ${rpadNum(p.notes, 4)}  ${pad(p.slug, slugW)}`);
+    }
+    lines.push("");
+  }
+
+  if (stats.recentActivity.length) {
+    lines.push("Most recent activity");
+    lines.push("--------------------");
+    const slugW = Math.max(8, ...stats.recentActivity.map((p) => p.slug.length));
+    for (const p of stats.recentActivity) {
+      lines.push(`  ${pad(p.slug, slugW)} ${formatLocal(p.ts)}`);
+    }
+    lines.push("");
+  }
+
+  if (stats.tempSlugs.length) {
+    lines.push(`Temp/cleanup candidates (${stats.tempSlugs.length})`);
+    lines.push("------------------------");
+    for (const slug of stats.tempSlugs) lines.push(`  ${slug}`);
+    lines.push("");
+  } else {
+    lines.push("Temp/cleanup candidates: none");
+    lines.push("");
+  }
+
+  lines.push(`Generated at ${new Date().toISOString()}`);
+  return lines.join("\n");
+}
+
+/** Stable JSON serialization (sorted keys for top-level + totals). */
+export function formatJson(stats) {
+  const out = {
+    root: stats.root,
+    totals: stats.totals,
+    projectCount: stats.projectCount,
+    topByNotes: stats.topByNotes,
+    recentActivity: stats.recentActivity,
+    tempSlugs: stats.tempSlugs,
+    perProject: stats.perProject,
+    generatedAt: new Date().toISOString(),
+  };
+  return JSON.stringify(out, null, 2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-dev-mcp-suite",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Four local, file-based MCP servers for solo devs/vibecoders: persistent project memory, session handoff/resume, git-independent file checkpoints, and token-efficient project briefings. Works with any MCP client.",
   "type": "module",
   "license": "MIT",
@@ -32,16 +32,20 @@
     "project-memory-mcp": "bin/project-memory.mjs",
     "devjournal-mcp": "bin/devjournal.mjs",
     "checkpoint-mcp": "bin/checkpoint.mjs",
-    "context-pack-mcp": "bin/context-pack.mjs"
+    "context-pack-mcp": "bin/context-pack.mjs",
+    "stats": "bin/stats.mjs",
+    "prune": "bin/prune.mjs"
   },
   "scripts": {
-    "test": "node run-tests.mjs"
+    "test": "node run-tests.mjs",
+    "test:stats": "node tests/stats.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "files": [
     "bin/*.mjs",
+    "bin/_meta.mjs",
     "project-memory/*.js",
     "project-memory/server.js",
     "project-memory/embedding.js",
@@ -69,6 +73,7 @@
     "CHANGELOG.md",
     "README.md",
     "LICENSE",
-    ".env.example"
+    ".env.example",
+    "lib/*.js"
   ]
 }

package/project-memory/provider-chain.js

@@ -7,6 +7,11 @@ function value(name) {
   return String(process.env[name] || "").trim();
 }
 
+export function redactKey(key) {
+  const k = String(key || "");
+  return k ? `set (${k.length} chars)` : "not set";
+}
+
 function providerEnv(prefix) {
   const label = value(prefix);
   const base = value(`${prefix}_BASE_URL`);
@@ -16,20 +21,34 @@ function providerEnv(prefix) {
   return { label, base, key, model };
 }
 
-function numberedProviders() {
-  const providers = [];
-  const primary = providerEnv("MCP_PROVIDER_PRIMARY");
-  if (primary) providers.push(primary);
+function slotIssues(prefix) {
+  const present = ["", "_BASE_URL", "_API_KEY", "_MODEL"].some((s) => value(`${prefix}${s}`));
+  if (!present) return null;
+  const missing = [];
+  if (!value(prefix)) missing.push(`${prefix}`);
+  if (!value(`${prefix}_BASE_URL`)) missing.push(`${prefix}_BASE_URL`);
+  if (!value(`${prefix}_API_KEY`)) missing.push(`${prefix}_API_KEY`);
+  if (!value(`${prefix}_MODEL`)) missing.push(`${prefix}_MODEL`);
+  return missing.length ? { prefix, missing } : null;
+}
 
-  const slots = Object.keys(process.env)
-    .map((name) => name.match(/^MCP_PROVIDER_CHAIN(\d+)$/)?.[1])
+function numberedPrefixes() {
+  const prefixes = ["MCP_PROVIDER_PRIMARY"];
+  const nums = Object.keys(process.env)
+    .map((name) => name.match(/^MCP_PROVIDER_CHAIN(\d+)/)?.[1])
     .filter(Boolean)
     .map(Number)
-    .filter((n) => n >= 2)
-    .sort((a, b) => a - b);
+    .filter((n) => n >= 2);
+  for (const n of [...new Set(nums)].sort((a, b) => a - b)) {
+    prefixes.push(`MCP_PROVIDER_CHAIN${n}`);
+  }
+  return prefixes;
+}
 
-  for (const n of slots) {
-    const provider = providerEnv(`MCP_PROVIDER_CHAIN${n}`);
+function numberedProviders() {
+  const providers = [];
+  for (const prefix of numberedPrefixes()) {
+    const provider = providerEnv(prefix);
     if (provider) providers.push(provider);
   }
   return providers;
@@ -54,3 +73,37 @@ export function providerChainConfig() {
   }
   return { providers, enabled: providers.length > 0, deterministic };
 }
+
+export function providerChainDiagnostics() {
+  const cfg = providerChainConfig();
+  const issues = [];
+  for (const prefix of numberedPrefixes()) {
+    const issue = slotIssues(prefix);
+    if (issue) issues.push(issue);
+  }
+  return {
+    deterministic: cfg.deterministic,
+    enabled: cfg.enabled,
+    providers: cfg.providers.map((p) => ({ label: p.label, base: p.base, model: p.model, apiKey: redactKey(p.key) })),
+    issues,
+  };
+}
+
+const COOLDOWN_MS = Number(process.env.MCP_PROVIDER_COOLDOWN_MS || 60000);
+const cooldowns = new Map();
+
+export function isCoolingDown(key, now = Date.now()) {
+  const until = cooldowns.get(key);
+  if (!until) return false;
+  if (now >= until) { cooldowns.delete(key); return false; }
+  return true;
+}
+
+export function recordOutcome(key, ok, now = Date.now()) {
+  if (ok) { cooldowns.delete(key); return; }
+  cooldowns.set(key, now + COOLDOWN_MS);
+}
+
+export function _resetCooldowns() {
+  cooldowns.clear();
+}