codex-dev-mcp-suite 1.2.0 → 1.4.0

package/bin/prune.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * bin/prune.mjs — Dev MCP Suite prune CLI.
+ *
+ * Removes temp project slugs (prefix `tmp.`) from all stores. Default is
+ * DRY-RUN — nothing is deleted unless you pass `--yes`.
+ *
+ * Usage:
+ *   prune [--root <path>] [--yes] [--json]
+ *   prune --help | --version
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { findTempSlugs, planPrune, applyPrune } from "../lib/prune.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function pkgVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version || "unknown";
+  } catch { return "unknown"; }
+}
+
+function resolveRoot() {
+  const fromFlag = process.env.PRUNE_ROOT;
+  if (fromFlag) return path.resolve(fromFlag);
+  for (const k of ["MEMORY_VAULT_DIR", "JOURNAL_DIR", "CHECKPOINT_DIR"]) {
+    const v = process.env[k];
+    if (v) {
+      const sub = k === "MEMORY_VAULT_DIR" ? "vault" : k === "JOURNAL_DIR" ? "journal" : "checkpoints";
+      const parent = path.dirname(v);
+      if (path.basename(parent) === sub) return parent;
+      return parent;
+    }
+  }
+  return path.join(os.homedir(), ".codex", "memories");
+}
+
+function parseArgs(argv) {
+  const opts = { root: null, yes: false, json: false, help: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "-v" || a === "--version") opts.version = true;
+    else if (a === "--yes" || a === "-y") opts.yes = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--dry-run") opts.yes = false;
+    else if (a === "--root") opts.root = path.resolve(argv[++i]);
+    else if (a.startsWith("--root=")) opts.root = path.resolve(a.slice("--root=".length));
+    else if (!a.startsWith("-")) opts.root = path.resolve(a);
+    else {
+      process.stderr.write(`prune: unknown flag: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(2)} MB`;
+}
+
+function printHelp() {
+  const out = [
+    `prune (Dev MCP Suite) v${pkgVersion()}`,
+    "",
+    "Remove temp project slugs (prefix tmp.) from vault, journal, and",
+    "checkpoints. Default is DRY-RUN — nothing is deleted without --yes.",
+    "",
+    "Usage:",
+    "  prune [root] [--root <path>] [--yes] [--json]",
+    "  prune --help | --version",
+    "",
+    "Options:",
+    "  --yes, -y    Actually delete. Without this, only a dry-run report is printed.",
+    "  --dry-run    Force dry-run mode (default).",
+    "  --json       Machine-readable JSON output.",
+    "  --root <p>   Storage root (default: ~/.codex/memories or first env var of",
+    "               MEMORY_VAULT_DIR / JOURNAL_DIR / CHECKPOINT_DIR)",
+    "  -h, --help",
+    "  -v, --version",
+    "",
+    "Safety: refuses to delete any slug that does not start with `tmp.`.",
+    "",
+    "Examples:",
+    "  prune                       # dry-run report",
+    "  prune --yes                 # delete after seeing the plan",
+    "  prune --yes --json          # machine-readable delete report",
+  ];
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.version) { process.stdout.write(`${pkgVersion()}\n`); process.exit(0); }
+if (opts.help) { printHelp(); process.exit(0); }
+
+const root = opts.root || resolveRoot();
+const plan = planPrune({ root });
+
+if (plan.length === 0) {
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ root, plan: [], removed: [], skipped: [], errors: [] }, null, 2) + "\n");
+  } else {
+    process.stdout.write(`No temp slugs found under ${root}.\n`);
+  }
+  process.exit(0);
+}
+
+if (!opts.yes) {
+  // dry-run report
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ root, dryRun: true, plan, removed: [], skipped: [], errors: [] }, null, 2) + "\n");
+  } else {
+    const lines = [];
+    lines.push(`Dev MCP Suite — prune (DRY RUN)`);
+    lines.push("=================================");
+    lines.push(`Storage root: ${root}`);
+    lines.push(`Found ${plan.length} temp slug${plan.length === 1 ? "" : "s"}:`);
+    let totalBytes = 0;
+    for (const e of plan) {
+      lines.push(`  ${e.slug.padEnd(36)} ${fmtBytes(e.bytes).padStart(10)}   stores: ${e.stores.join(",")}`);
+      totalBytes += e.bytes;
+    }
+    lines.push(`  ${"TOTAL".padEnd(36)} ${fmtBytes(totalBytes).padStart(10)}`);
+    lines.push("");
+    lines.push("Re-run with `--yes` to actually delete.");
+    process.stdout.write(lines.join("\n") + "\n");
+  }
+  process.exit(0);
+}
+
+// actually delete
+const slugs = plan.map((p) => p.slug);
+const result = applyPrune({ root, slugs, dryRun: false });
+const totalFreed = plan.reduce((a, p) => a + p.bytes, 0);
+
+if (opts.json) {
+  process.stdout.write(JSON.stringify({ root, dryRun: false, plan, ...result, bytesFreed: totalFreed }, null, 2) + "\n");
+} else {
+  const lines = [];
+  lines.push(`Dev MCP Suite — prune`);
+  lines.push("=====================");
+  lines.push(`Storage root: ${root}`);
+  lines.push(`Removed ${result.removed.length} slug${result.removed.length === 1 ? "" : "s"} (freed ~${fmtBytes(totalFreed)})`);
+  for (const slug of result.removed) lines.push(`  ✓ ${slug}`);
+  if (result.errors.length) {
+    lines.push("");
+    lines.push(`Errors (${result.errors.length}):`);
+    for (const e of result.errors) lines.push(`  ✗ ${e.slug} [${e.store}]: ${e.error}`);
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+}
+
+process.exit(result.errors.length > 0 ? 1 : 0);

package/bin/stats.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * bin/stats.mjs — Dev MCP Suite stats CLI.
+ *
+ * Usage:
+ *   stats [--root <path>] [--json] [--top N] [--help] [--version]
+ *
+ * Default storage root: ~/.codex/memories (override via --root or
+ * MEMORY_VAULT_DIR / JOURNAL_DIR / CHECKPOINT_DIR siblings).
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { computeStats, formatText, formatJson } from "../lib/stats.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function pkgVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version || "unknown";
+  } catch { return "unknown"; }
+}
+
+function resolveRoot() {
+  // Precedence: explicit --root > vault env > journal env > checkpoint env > ~/.codex/memories
+  const fromFlag = process.env.STATS_ROOT;
+  if (fromFlag) return path.resolve(fromFlag);
+  for (const k of ["MEMORY_VAULT_DIR", "JOURNAL_DIR", "CHECKPOINT_DIR"]) {
+    const v = process.env[k];
+    if (v) {
+      // each server stores under <root>/<subdir>, so the root is the parent
+      const sub = k === "MEMORY_VAULT_DIR" ? "vault" : k === "JOURNAL_DIR" ? "journal" : "checkpoints";
+      const parent = path.dirname(v);
+      if (path.basename(parent) === sub) return parent;
+      return parent;
+    }
+  }
+  return path.join(os.homedir(), ".codex", "memories");
+}
+
+function parseArgs(argv) {
+  const opts = { root: null, json: false, top: 10, help: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "-v" || a === "--version") opts.version = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--root") opts.root = path.resolve(argv[++i]);
+    else if (a.startsWith("--root=")) opts.root = path.resolve(a.slice("--root=".length));
+    else if (a === "--top") opts.top = parseInt(argv[++i], 10) || 10;
+    else if (a.startsWith("--top=")) opts.top = parseInt(a.slice("--top=".length), 10) || 10;
+    else if (a === "--") { /* ignore rest */ break; }
+    else if (!a.startsWith("-")) opts.root = path.resolve(a);
+    else {
+      process.stderr.write(`stats: unknown flag: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function printHelp() {
+  const out = [
+    `stats (Dev MCP Suite) v${pkgVersion()}`,
+    "",
+    "Summarize local memory storage (vault / journal / checkpoints).",
+    "",
+    "Usage:",
+    "  stats [root] [--root <path>] [--json] [--top N]",
+    "  stats --help | --version",
+    "",
+    "Options:",
+    "  --root <path>   Storage root (default: ~/.codex/memories or first env var of",
+    "                  MEMORY_VAULT_DIR / JOURNAL_DIR / CHECKPOINT_DIR)",
+    "  --json          Emit machine-readable JSON instead of human text",
+    "  --top N         How many entries in top-project / recent-activity lists",
+    "                  (default: 10)",
+    "  -h, --help      Show this help",
+    "  -v, --version   Print version",
+    "",
+    "Examples:",
+    "  stats                       # summary of default storage",
+    "  stats --json | jq .totals   # totals only",
+    "  stats --root /tmp/mem       # use a different root",
+  ];
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.version) { process.stdout.write(`${pkgVersion()}\n`); process.exit(0); }
+if (opts.help) { printHelp(); process.exit(0); }
+
+const root = opts.root || resolveRoot();
+const stats = computeStats({ root, topLimit: opts.top });
+
+if (opts.json) {
+  process.stdout.write(formatJson(stats) + "\n");
+} else {
+  process.stdout.write(formatText(stats) + "\n");
+}

package/lib/provider-smoke.js

@@ -0,0 +1,234 @@
+/**
+ * Dev MCP Suite — provider smoke library.
+ *
+ * Builds a "matrix" of providers from environment variables (matching the
+ * convention used by project-memory / devjournal servers: `MCP_*` neutral,
+ * `NINEROUTER_*` / `LLM_*` / `EMBED_*` legacy aliases), then exposes
+ * helpers to shape probe results and format them as text/JSON/markdown.
+ *
+ * The actual HTTP probes are NOT done here — the CLI wires real `fetch`.
+ * Keeping the lib free of network I/O makes it trivially testable offline.
+ */
+
+import os from "os";
+
+/**
+ * Static metadata for well-known providers. `supportsEmbed: false` means
+ * the provider does not expose an OpenAI-compatible /v1/embeddings endpoint
+ * (e.g. Groq, Cerebras — they focus on inference speed).
+ */
+export function isCloudflareURL(urlStr) {
+  return typeof urlStr === "string" && urlStr.includes("api.cloudflare.com/client/v4/accounts");
+}
+
+export const KNOWN_PROVIDERS = {
+  // Inference-only (no embeddings endpoint)
+  groq:       { supportsChat: true,  supportsEmbed: false, defaultBase: "https://api.groq.com/openai/v1",              defaultModel: "llama-3.3-70b-versatile", notes: "OpenAI-compatible; inference-only" },
+  cerebras:   { supportsChat: true,  supportsEmbed: false, defaultBase: "https://api.cerebras.ai/v1",                 defaultModel: "gpt-oss-120b",          notes: "OpenAI-compatible; inference-only" },
+  anthropic:  { supportsChat: true,  supportsEmbed: false, defaultBase: "https://api.anthropic.com/v1",                defaultModel: null,                   notes: "No embeddings API" },
+
+  // Embeddings + chat
+  openai:     { supportsChat: true,  supportsEmbed: true,  defaultBase: "https://api.openai.com/v1",                  defaultModel: "text-embedding-3-small", notes: "Reference impl; paid (~$0.02/1M tok)" },
+  mistral:    { supportsChat: true,  supportsEmbed: true,  defaultBase: "https://api.mistral.ai/v1",                  defaultModel: "mistral-embed",          notes: "OpenAI-compatible; paid w/ free tier" },
+  openrouter: { supportsChat: true,  supportsEmbed: true,  defaultBase: "https://openrouter.ai/api/v1",                defaultModel: "openai/text-embedding-3-small", notes: "Aggregator; many free models available" },
+  gemini:     { supportsChat: true,  supportsEmbed: true,  defaultBase: "https://generativelanguage.googleapis.com/v1beta/openai", defaultModel: "text-embedding-004", notes: "Google; OpenAI-compatible; generous free tier" },
+  cohere:     { supportsChat: true,  supportsEmbed: true,  defaultBase: "https://api.cohere.ai/v1",                   defaultModel: "embed-multilingual-v3.0", notes: "Top multilingual; trial + paid" },
+  voyage:     { supportsChat: false, supportsEmbed: true,  defaultBase: "https://api.voyageai.com/v1",                defaultModel: "voyage-3",               notes: "Embeddings-only; 200M free on signup" },
+
+  // Local (free, unlimited, uses laptop resources)
+  ollama:     { supportsChat: true,  supportsEmbed: true,  defaultBase: "http://localhost:11434/v1",                  defaultModel: "nomic-embed-text",       notes: "Local; runs on laptop CPU/GPU/RAM" },
+
+  // Non-OpenAI-compatible (requires custom code path in embedding.js)
+  cloudflare: { supportsChat: true,  supportsEmbed: true,  defaultBase: null,                                          defaultModel: "@cf/baai/bge-base-en-v1.5", endpoint: "cloudflare", notes: "REST-only API; NOT OpenAI-compatible; 10K neurons/day free; model goes in URL path" },
+
+  // Local proxy / aggregator (not OpenAI by default; configured via env)
+  "9router":  { supportsChat: true,  supportsEmbed: true,  defaultBase: null,                                          defaultModel: null,                   notes: "Self-hosted OpenAI-compatible aggregator" },
+};
+
+function pickEnv(env, names) {
+  for (const n of names) if (env[n]) return env[n];
+  return undefined;
+}
+
+/** Read a provider slot (PRIMARY, CHAIN2..N) into a normalized record. */
+function readProviderSlot(env, slot /* PRIMARY | CHAIN2 | CHAIN3 | ... */) {
+  const upper = slot.toUpperCase();
+  const name = pickEnv(env, [
+    `MCP_PROVIDER_${upper}`,
+    `MCP_PROVIDER_${upper}_NAME`,
+  ]);
+  if (!name) return null;
+  const lower = name.toLowerCase();
+  const baseUrl = pickEnv(env, [`MCP_PROVIDER_${upper}_BASE_URL`]);
+  const apiKey  = pickEnv(env, [`MCP_PROVIDER_${upper}_API_KEY`]);
+  const chatModel = pickEnv(env, [`MCP_PROVIDER_${upper}_MODEL`, `MCP_PROVIDER_${upper}_CHAT_MODEL`]);
+  const embedModel = pickEnv(env, [`MCP_PROVIDER_${upper}_EMBED_MODEL`]);
+  const meta = KNOWN_PROVIDERS[lower] || {};
+  return {
+    id: lower,
+    name,
+    baseUrl: baseUrl || meta.defaultBase || null,
+    apiKey: apiKey || null,
+    chatModel: chatModel || meta.defaultModel || null,
+    embedModel: embedModel || null,
+    supportsChat: meta.supportsChat !== false,
+    supportsEmbed: meta.supportsEmbed === true && Boolean(embedModel || meta.defaultModel),
+    source: `MCP_PROVIDER_${upper}`,
+  };
+}
+
+/** Read a "named" provider from explicit env (e.g. MISTRAL_*, OPENAI_*, GROQ_*). */
+function readNamedProvider(env, id) {
+  const upper = id.toUpperCase();
+  const apiKey = pickEnv(env, [`${upper}_API_KEY`, `${upper}_KEY`, `MCP_${upper}_API_KEY`]);
+  const baseUrl = pickEnv(env, [`${upper}_BASE_URL`, `${upper}_URL`, `MCP_${upper}_BASE_URL`]);
+  const chatModel = pickEnv(env, [`${upper}_MODEL`, `${upper}_CHAT_MODEL`, `MCP_${upper}_MODEL`]);
+  const embedModel = pickEnv(env, [`${upper}_EMBED_MODEL`, `MCP_EMBED_MODEL`, `${upper}_MODEL`]);
+  if (!apiKey && !baseUrl) return null;
+  const meta = KNOWN_PROVIDERS[id] || {};
+  // For single-model providers (e.g. Cloudflare), the configured model is used for both chat and embed.
+  const effectiveChatModel = chatModel || meta.defaultModel || embedModel || null;
+  const effectiveEmbedModel = embedModel || meta.defaultModel || chatModel || null;
+  const effectiveBaseUrl = baseUrl || meta.defaultBase || null;
+  return {
+    id,
+    name: id,
+    baseUrl: effectiveBaseUrl,
+    apiKey: apiKey || null,
+    chatModel: effectiveChatModel,
+    embedModel: effectiveEmbedModel,
+    supportsChat: meta.supportsChat !== false,
+    supportsEmbed: meta.supportsEmbed === true && Boolean(effectiveEmbedModel),
+    endpoint: meta.endpoint || (effectiveBaseUrl && isCloudflareURL(effectiveBaseUrl) ? "cloudflare" : "openai-compatible"),
+    source: `${upper}_*`,
+  };
+}
+
+/** Read the existing 9router/agentrouter config used by project-memory / devjournal. */
+function read9routerLike(env) {
+  const baseUrl = pickEnv(env, [
+    "MCP_LLM_BASE_URL", "MCP_RERANK_BASE_URL", "MCP_EMBED_BASE_URL",
+    "LLM_BASE_URL", "EMBED_URL", "NINEROUTER_URL", "RERANK_URL",
+  ]);
+  const apiKey = pickEnv(env, [
+    "MCP_LLM_API_KEY", "MCP_RERANK_API_KEY", "MCP_EMBED_API_KEY",
+    "LLM_API_KEY", "EMBED_KEY", "NINEROUTER_KEY", "RERANK_KEY",
+  ]);
+  if (!baseUrl && !apiKey) return null;
+  // Heuristic: label the catch-all based on host for clarity in output.
+  const host = baseUrl ? new URL(baseUrl).hostname : "";
+  let id = "openai-compatible";
+  if (/9router|agentrouter/i.test(host)) id = "9router";
+  return {
+    id,
+    name: id,
+    baseUrl: baseUrl || null,
+    apiKey: apiKey || null,
+    chatModel: pickEnv(env, [
+      "MCP_RERANK_MODEL", "MCP_LLM_MODEL", "RERANK_MODEL", "LLM_MODEL",
+      "NINEROUTER_CHAT_MODEL", "NINEROUTER_RERANK_MODEL", "NINEROUTER_MODEL",
+    ]) || null,
+    embedModel: pickEnv(env, [
+      "MCP_EMBED_MODEL", "EMBED_MODEL", "NINEROUTER_EMBED_MODEL",
+    ]) || null,
+    supportsChat: true,
+    supportsEmbed: true,
+    source: "MCP_LLM_BASE_URL",
+  };
+}
+
+/**
+ * Build the provider matrix from environment variables.
+ * Returns a deduplicated list of provider records.
+ * @param {Record<string,string|undefined>} env
+ * @returns {Array<{id, name, baseUrl, apiKey, chatModel, embedModel, supportsChat, supportsEmbed, source}>}
+ */
+export function buildProviderMatrix(env) {
+  const out = [];
+  const seen = new Set();
+
+  const push = (p) => {
+    if (!p || !p.baseUrl && !p.apiKey) return;
+    if (seen.has(p.id)) return;
+    seen.add(p.id);
+    out.push(p);
+  };
+
+  // 1. Primary + numbered slots
+  push(readProviderSlot(env, "PRIMARY"));
+  for (let i = 2; i <= 10; i++) {
+    push(readProviderSlot(env, `CHAIN${i}`));
+  }
+
+  // 2. Named providers (Groq, Cerebras, Mistral, OpenRouter, OpenAI, Ollama)
+  for (const id of ["groq", "cerebras", "mistral", "openrouter", "openai", "ollama", "anthropic", "gemini", "cohere", "voyage", "cloudflare"]) {
+    push(readNamedProvider(env, id));
+  }
+
+  // 3. Catch-all: existing 9router-like config from MCP_LLM_BASE_URL etc.
+  push(read9routerLike(env));
+
+  return out;
+}
+
+/**
+ * Shape a probe result into the canonical record used by formatting helpers.
+ */
+export function shapeProbe({ name, kind, ok, latencyMs = null, status = null, sample = null, error = null, dim = null }) {
+  return { name, kind, ok, latencyMs, status, sample, error, dim };
+}
+
+// ---- formatting ----
+
+function fmtLatency(ms) {
+  if (ms == null) return "—";
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+export function formatText(results) {
+  const lines = [];
+  lines.push("Dev MCP Suite — provider smoke");
+  lines.push("==============================");
+  // group by provider
+  const byName = new Map();
+  for (const r of results) {
+    if (!byName.has(r.name)) byName.set(r.name, []);
+    byName.get(r.name).push(r);
+  }
+  for (const [name, rs] of byName) {
+    lines.push(`\n[${name}]`);
+    for (const r of rs) {
+      const mark = r.ok ? "✓" : "✗";
+      const lat = r.ok ? fmtLatency(r.latencyMs) : "";
+      const detail = r.ok
+        ? `${r.status || ""} ${lat}${r.sample ? `  "${String(r.sample).slice(0, 40)}"` : ""}${r.dim ? `  dim=${r.dim}` : ""}`.trim()
+        : `${r.status || "—"}  ${r.error || "unknown error"}`;
+      lines.push(`  ${mark} ${r.kind.padEnd(10)} ${detail}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+export function formatJson(results) {
+  return JSON.stringify(results, null, 2);
+}
+
+export function formatMarkdown(results) {
+  const lines = [];
+  lines.push("# Provider smoke matrix");
+  lines.push("");
+  lines.push(`_Generated ${new Date().toISOString()}_`);
+  lines.push("");
+  lines.push("| Provider | Kind | Status | Latency | HTTP | Sample / dim | Error |");
+  lines.push("|---|---|---|---|---|---|---|");
+  for (const r of results) {
+    const okMark = r.ok ? "✓" : "✗";
+    const sample = r.ok ? (r.sample ? `\`${String(r.sample).slice(0, 30)}\`` : (r.dim ? `dim=${r.dim}` : "—")) : "—";
+    const err = r.ok ? "" : (r.error || "").replace(/\|/g, "\\|");
+    lines.push(`| ${r.name} | ${r.kind} | ${okMark} | ${fmtLatency(r.latencyMs)} | ${r.status || "—"} | ${sample} | ${err} |`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}

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 };
+}