@maximalabs/dev-mcp-suite 0.0.0-stage → 3.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/.env.example +69 -0
  2. package/CHANGELOG.md +281 -0
  3. package/CODEX_DEV_MCP_GUIDE.md +297 -0
  4. package/LICENSE +21 -0
  5. package/README.md +193 -2
  6. package/armada/package.json +14 -0
  7. package/armada/server.js +329 -0
  8. package/backfill-sessions-v2.mjs +288 -0
  9. package/bin/_meta.mjs +73 -0
  10. package/bin/armada-mcp.mjs +12 -0
  11. package/bin/checkpoint.mjs +9 -0
  12. package/bin/context-pack.mjs +9 -0
  13. package/bin/devjournal.mjs +9 -0
  14. package/bin/init.mjs +25 -0
  15. package/bin/project-memory.mjs +10 -0
  16. package/bin/provider-smoke.mjs +278 -0
  17. package/bin/prune.mjs +158 -0
  18. package/bin/stats.mjs +101 -0
  19. package/bin/ui.mjs +5 -0
  20. package/checkpoint/package.json +14 -0
  21. package/checkpoint/server.js +318 -0
  22. package/context-pack/package.json +14 -0
  23. package/context-pack/server.js +747 -0
  24. package/devjournal/compress.js +75 -0
  25. package/devjournal/env.js +3 -0
  26. package/devjournal/package.json +14 -0
  27. package/devjournal/provider-chain.js +109 -0
  28. package/devjournal/rerank.js +120 -0
  29. package/devjournal/server.js +415 -0
  30. package/docs/ROADMAP.md +77 -0
  31. package/docs/clients/antigravity.md +52 -0
  32. package/docs/clients/claude-code.md +46 -0
  33. package/docs/clients/codex.md +39 -0
  34. package/docs/clients/generic-mcp.md +45 -0
  35. package/docs/clients/hermes.md +48 -0
  36. package/docs/configuration.md +123 -0
  37. package/docs/privacy.md +39 -0
  38. package/docs/providers.md +13 -0
  39. package/docs/superpowers/plans/2026-06-15-hardening-v1-2-implementation.md +60 -0
  40. package/docs/superpowers/plans/2026-06-15-provider-chain-v1-1-implementation.md +65 -0
  41. package/docs/superpowers/plans/2026-06-15-provider-client-agnostic-config.md +41 -0
  42. package/docs/superpowers/plans/2026-06-15-trust-release-implementation.md +62 -0
  43. package/docs/superpowers/plans/2026-06-18-v1-5-0-knowledge-graph.md +792 -0
  44. package/docs/superpowers/specs/2026-06-15-provider-chain-v1-1-design.md +89 -0
  45. package/docs/superpowers/specs/2026-06-15-trust-release-design.md +164 -0
  46. package/docs/superpowers/specs/2026-06-18-dev-mcp-suite-v1-5-0-knowledge-graph-design.md +386 -0
  47. package/docs/superpowers/specs/2026-07-22-v2-0-0-peak-intelligence.md +50 -0
  48. package/docs/superpowers/specs/2026-07-22-v3-0-0-god-tier.md +32 -0
  49. package/lib/init-wizard.js +120 -0
  50. package/lib/provider-smoke.js +234 -0
  51. package/lib/prune.js +114 -0
  52. package/lib/stats.js +269 -0
  53. package/lib/ui-server.js +151 -0
  54. package/lib/update-check.js +125 -0
  55. package/package.json +71 -4
  56. package/project-memory/auto-indexer.js +152 -0
  57. package/project-memory/dedup.js +49 -0
  58. package/project-memory/embedding.js +174 -0
  59. package/project-memory/env.js +3 -0
  60. package/project-memory/global-index.js +46 -0
  61. package/project-memory/graph.js +93 -0
  62. package/project-memory/local-embed.js +92 -0
  63. package/project-memory/package.json +14 -0
  64. package/project-memory/provider-chain.js +109 -0
  65. package/project-memory/rerank.js +120 -0
  66. package/project-memory/server.js +931 -0
  67. package/project-memory/swarm.js +56 -0
  68. package/run-tests.mjs +54 -0
@@ -0,0 +1,32 @@
1
+ # Design Spec: v3.0.0 — The Autonomous Agent OS Edition (God-Tier)
2
+
3
+ ## Overview
4
+
5
+ `codex-dev-mcp-suite` v3.0.0 represents the ultimate evolution in local-first AI development tools. It transforms the suite into an **Autonomous Agent Operating System** with live dev server telemetry observation, background git auto-indexing, predictive schema/contract diff analysis, and a zero-dependency interactive Web GUI Dashboard.
6
+
7
+ ---
8
+
9
+ ## ⚡ 4 God-Tier Pillars
10
+
11
+ ### 1. Live Dev-Server & Log Telemetry (`pack_telemetry`)
12
+ - **Module**: `context-pack` / `lib/telemetry.js`
13
+ - **Goal**: Read live dev server logs (`/tmp/*.log`, Docker logs, systemd, PM2, app console logs) to surface runtime errors and HTTP 500 stack traces directly into agent context without manual copy-pasting.
14
+ - **Tool**: `pack_telemetry({ logFile, limit, level })`
15
+
16
+ ### 2. Autonomous Background Git & Mtime Observer (`memory_auto_index`)
17
+ - **Module**: `project-memory` / `project-memory/auto-indexer.js`
18
+ - **Goal**: Inspect recent git commits, branch switches, and file modifications (`mtime`) to automatically derive and update Obsidian vault notes and knowledge graph links without explicit agent prompt calls.
19
+ - **Tool**: `memory_auto_index({ dir, dryRun })`
20
+
21
+ ### 3. Predictive Contract & Schema Impact Simulation (`pack_predictive_diff`)
22
+ - **Module**: `context-pack`
23
+ - **Goal**: Simulate proposed file edits or schema changes (e.g. Prisma schemas, REST endpoints, TypeScript interfaces) against frontend & backend callers to predict breaking contract changes before saving to disk.
24
+ - **Tool**: `pack_predictive_diff({ targetFile, proposedDiff })`
25
+
26
+ ### 4. Interactive Knowledge Graph & Memory Web GUI Dashboard (`mcp-ui` / `lib/ui-server.js`)
27
+ - **Module**: Built-in HTTP server (`bin/ui.mjs` / `npx codex-dev-mcp-suite ui`)
28
+ - **Goal**: Serve a zero-dependency, ultra-sleek, glassmorphic Web GUI Dashboard on `http://localhost:3333` featuring:
29
+ - 3D/2D Interactive Knowledge Graph View (Visual Nodes & Edges).
30
+ - Real-Time Multi-Agent Swarm Stream Timeline.
31
+ - Session Handoff & Journal History Explorer.
32
+ - Git-Independent Checkpoints Snapshot Diff Inspector.
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Auto-Config Installer Wizard for @maximalabs/dev-mcp-suite.
3
+ * Detects installed AI tools (Codex, Claude Code, Cursor, Windsurf, Hermes, AGY)
4
+ * and configures the 4 MCP servers automatically.
5
+ */
6
+
7
+ import fs from "fs/promises";
8
+ import path from "path";
9
+ import os from "os";
10
+
11
+ const HOME = os.homedir();
12
+
13
+ export const CLIENT_CONFIGS = [
14
+ {
15
+ name: "Codex CLI",
16
+ type: "toml",
17
+ path: path.join(HOME, ".codex", "config.toml"),
18
+ sampleSnippet: `
19
+ [mcp_servers.project-memory]
20
+ command = "npx"
21
+ args = ["-y", "-p", "@maximalabs/dev-mcp-suite", "project-memory-mcp"]
22
+
23
+ [mcp_servers.devjournal]
24
+ command = "npx"
25
+ args = ["-y", "-p", "@maximalabs/dev-mcp-suite", "devjournal-mcp"]
26
+
27
+ [mcp_servers.checkpoint]
28
+ command = "npx"
29
+ args = ["-y", "-p", "@maximalabs/dev-mcp-suite", "checkpoint-mcp"]
30
+
31
+ [mcp_servers.context-pack]
32
+ command = "npx"
33
+ args = ["-y", "-p", "@maximalabs/dev-mcp-suite", "context-pack-mcp"]
34
+ `
35
+ },
36
+ {
37
+ name: "Claude Code",
38
+ type: "json",
39
+ path: path.join(HOME, ".claude.json"),
40
+ },
41
+ {
42
+ name: "Cursor",
43
+ type: "json",
44
+ path: path.join(HOME, ".cursor", "mcp.json"),
45
+ },
46
+ {
47
+ name: "Windsurf",
48
+ type: "json",
49
+ path: path.join(HOME, ".codeium", "windsurf", "mcp_config.json"),
50
+ },
51
+ {
52
+ name: "Hermes Agent",
53
+ type: "json",
54
+ path: path.join(HOME, ".hermes", "config.json"),
55
+ },
56
+ {
57
+ name: "Antigravity CLI",
58
+ type: "json",
59
+ path: path.join(HOME, ".gemini", "antigravity-cli", "mcp_servers.json"),
60
+ }
61
+ ];
62
+
63
+ export async function detectClients() {
64
+ const detected = [];
65
+ for (const client of CLIENT_CONFIGS) {
66
+ try {
67
+ await fs.access(path.dirname(client.path));
68
+ detected.push(client);
69
+ } catch {}
70
+ }
71
+ return detected;
72
+ }
73
+
74
+ export async function configureJsonClient(configPath) {
75
+ let json = {};
76
+ try {
77
+ const raw = await fs.readFile(configPath, "utf8");
78
+ json = JSON.parse(raw);
79
+ } catch {}
80
+
81
+ json.mcpServers = json.mcpServers || {};
82
+ const servers = ["project-memory", "devjournal", "checkpoint", "context-pack"];
83
+ for (const s of servers) {
84
+ json.mcpServers[s] = {
85
+ command: "npx",
86
+ args: ["-y", "-p", "@maximalabs/dev-mcp-suite", `${s}-mcp`]
87
+ };
88
+ }
89
+
90
+ await fs.mkdir(path.dirname(configPath), { recursive: true });
91
+ await fs.writeFile(configPath, JSON.stringify(json, null, 2) + "\n");
92
+ return configPath;
93
+ }
94
+
95
+ export async function runInitWizard({ dryRun = false } = {}) {
96
+ const clients = await detectClients();
97
+ const results = [];
98
+
99
+ for (const c of clients) {
100
+ if (c.type === "json") {
101
+ if (!dryRun) {
102
+ await configureJsonClient(c.path);
103
+ }
104
+ results.push({ name: c.name, path: c.path, status: dryRun ? "PREVIEW" : "CONFIGURED 🟢" });
105
+ } else if (c.type === "toml") {
106
+ let content = "";
107
+ try {
108
+ content = await fs.readFile(c.path, "utf8");
109
+ } catch {}
110
+
111
+ if (!content.includes("[mcp_servers.project-memory]") && !dryRun) {
112
+ await fs.mkdir(path.dirname(c.path), { recursive: true });
113
+ await fs.appendFile(c.path, "\n" + c.sampleSnippet.trim() + "\n");
114
+ }
115
+ results.push({ name: c.name, path: c.path, status: dryRun ? "PREVIEW" : "CONFIGURED 🟢" });
116
+ }
117
+ }
118
+
119
+ return { detectedCount: clients.length, results };
120
+ }
@@ -0,0 +1,234 @@
1
+ /**
2
+ * Dev MCP Suite — provider smoke library.
3
+ *
4
+ * Builds a "matrix" of providers from environment variables (matching the
5
+ * convention used by project-memory / devjournal servers: `MCP_*` neutral,
6
+ * `NINEROUTER_*` / `LLM_*` / `EMBED_*` legacy aliases), then exposes
7
+ * helpers to shape probe results and format them as text/JSON/markdown.
8
+ *
9
+ * The actual HTTP probes are NOT done here — the CLI wires real `fetch`.
10
+ * Keeping the lib free of network I/O makes it trivially testable offline.
11
+ */
12
+
13
+ import os from "os";
14
+
15
+ /**
16
+ * Static metadata for well-known providers. `supportsEmbed: false` means
17
+ * the provider does not expose an OpenAI-compatible /v1/embeddings endpoint
18
+ * (e.g. Groq, Cerebras — they focus on inference speed).
19
+ */
20
+ export function isCloudflareURL(urlStr) {
21
+ return typeof urlStr === "string" && urlStr.includes("api.cloudflare.com/client/v4/accounts");
22
+ }
23
+
24
+ export const KNOWN_PROVIDERS = {
25
+ // Inference-only (no embeddings endpoint)
26
+ groq: { supportsChat: true, supportsEmbed: false, defaultBase: "https://api.groq.com/openai/v1", defaultModel: "llama-3.3-70b-versatile", notes: "OpenAI-compatible; inference-only" },
27
+ cerebras: { supportsChat: true, supportsEmbed: false, defaultBase: "https://api.cerebras.ai/v1", defaultModel: "gpt-oss-120b", notes: "OpenAI-compatible; inference-only" },
28
+ anthropic: { supportsChat: true, supportsEmbed: false, defaultBase: "https://api.anthropic.com/v1", defaultModel: null, notes: "No embeddings API" },
29
+
30
+ // Embeddings + chat
31
+ openai: { supportsChat: true, supportsEmbed: true, defaultBase: "https://api.openai.com/v1", defaultModel: "text-embedding-3-small", notes: "Reference impl; paid (~$0.02/1M tok)" },
32
+ mistral: { supportsChat: true, supportsEmbed: true, defaultBase: "https://api.mistral.ai/v1", defaultModel: "mistral-embed", notes: "OpenAI-compatible; paid w/ free tier" },
33
+ openrouter: { supportsChat: true, supportsEmbed: true, defaultBase: "https://openrouter.ai/api/v1", defaultModel: "openai/text-embedding-3-small", notes: "Aggregator; many free models available" },
34
+ gemini: { supportsChat: true, supportsEmbed: true, defaultBase: "https://generativelanguage.googleapis.com/v1beta/openai", defaultModel: "text-embedding-004", notes: "Google; OpenAI-compatible; generous free tier" },
35
+ cohere: { supportsChat: true, supportsEmbed: true, defaultBase: "https://api.cohere.ai/v1", defaultModel: "embed-multilingual-v3.0", notes: "Top multilingual; trial + paid" },
36
+ voyage: { supportsChat: false, supportsEmbed: true, defaultBase: "https://api.voyageai.com/v1", defaultModel: "voyage-3", notes: "Embeddings-only; 200M free on signup" },
37
+
38
+ // Local (free, unlimited, uses laptop resources)
39
+ ollama: { supportsChat: true, supportsEmbed: true, defaultBase: "http://localhost:11434/v1", defaultModel: "nomic-embed-text", notes: "Local; runs on laptop CPU/GPU/RAM" },
40
+
41
+ // Non-OpenAI-compatible (requires custom code path in embedding.js)
42
+ 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" },
43
+
44
+ // Local proxy / aggregator (not OpenAI by default; configured via env)
45
+ "9router": { supportsChat: true, supportsEmbed: true, defaultBase: null, defaultModel: null, notes: "Self-hosted OpenAI-compatible aggregator" },
46
+ };
47
+
48
+ function pickEnv(env, names) {
49
+ for (const n of names) if (env[n]) return env[n];
50
+ return undefined;
51
+ }
52
+
53
+ /** Read a provider slot (PRIMARY, CHAIN2..N) into a normalized record. */
54
+ function readProviderSlot(env, slot /* PRIMARY | CHAIN2 | CHAIN3 | ... */) {
55
+ const upper = slot.toUpperCase();
56
+ const name = pickEnv(env, [
57
+ `MCP_PROVIDER_${upper}`,
58
+ `MCP_PROVIDER_${upper}_NAME`,
59
+ ]);
60
+ if (!name) return null;
61
+ const lower = name.toLowerCase();
62
+ const baseUrl = pickEnv(env, [`MCP_PROVIDER_${upper}_BASE_URL`]);
63
+ const apiKey = pickEnv(env, [`MCP_PROVIDER_${upper}_API_KEY`]);
64
+ const chatModel = pickEnv(env, [`MCP_PROVIDER_${upper}_MODEL`, `MCP_PROVIDER_${upper}_CHAT_MODEL`]);
65
+ const embedModel = pickEnv(env, [`MCP_PROVIDER_${upper}_EMBED_MODEL`]);
66
+ const meta = KNOWN_PROVIDERS[lower] || {};
67
+ return {
68
+ id: lower,
69
+ name,
70
+ baseUrl: baseUrl || meta.defaultBase || null,
71
+ apiKey: apiKey || null,
72
+ chatModel: chatModel || meta.defaultModel || null,
73
+ embedModel: embedModel || null,
74
+ supportsChat: meta.supportsChat !== false,
75
+ supportsEmbed: meta.supportsEmbed === true && Boolean(embedModel || meta.defaultModel),
76
+ source: `MCP_PROVIDER_${upper}`,
77
+ };
78
+ }
79
+
80
+ /** Read a "named" provider from explicit env (e.g. MISTRAL_*, OPENAI_*, GROQ_*). */
81
+ function readNamedProvider(env, id) {
82
+ const upper = id.toUpperCase();
83
+ const apiKey = pickEnv(env, [`${upper}_API_KEY`, `${upper}_KEY`, `MCP_${upper}_API_KEY`]);
84
+ const baseUrl = pickEnv(env, [`${upper}_BASE_URL`, `${upper}_URL`, `MCP_${upper}_BASE_URL`]);
85
+ const chatModel = pickEnv(env, [`${upper}_MODEL`, `${upper}_CHAT_MODEL`, `MCP_${upper}_MODEL`]);
86
+ const embedModel = pickEnv(env, [`${upper}_EMBED_MODEL`, `MCP_EMBED_MODEL`, `${upper}_MODEL`]);
87
+ if (!apiKey && !baseUrl) return null;
88
+ const meta = KNOWN_PROVIDERS[id] || {};
89
+ // For single-model providers (e.g. Cloudflare), the configured model is used for both chat and embed.
90
+ const effectiveChatModel = chatModel || meta.defaultModel || embedModel || null;
91
+ const effectiveEmbedModel = embedModel || meta.defaultModel || chatModel || null;
92
+ const effectiveBaseUrl = baseUrl || meta.defaultBase || null;
93
+ return {
94
+ id,
95
+ name: id,
96
+ baseUrl: effectiveBaseUrl,
97
+ apiKey: apiKey || null,
98
+ chatModel: effectiveChatModel,
99
+ embedModel: effectiveEmbedModel,
100
+ supportsChat: meta.supportsChat !== false,
101
+ supportsEmbed: meta.supportsEmbed === true && Boolean(effectiveEmbedModel),
102
+ endpoint: meta.endpoint || (effectiveBaseUrl && isCloudflareURL(effectiveBaseUrl) ? "cloudflare" : "openai-compatible"),
103
+ source: `${upper}_*`,
104
+ };
105
+ }
106
+
107
+ /** Read the existing 9router/agentrouter config used by project-memory / devjournal. */
108
+ function read9routerLike(env) {
109
+ const baseUrl = pickEnv(env, [
110
+ "MCP_LLM_BASE_URL", "MCP_RERANK_BASE_URL", "MCP_EMBED_BASE_URL",
111
+ "LLM_BASE_URL", "EMBED_URL", "NINEROUTER_URL", "RERANK_URL",
112
+ ]);
113
+ const apiKey = pickEnv(env, [
114
+ "MCP_LLM_API_KEY", "MCP_RERANK_API_KEY", "MCP_EMBED_API_KEY",
115
+ "LLM_API_KEY", "EMBED_KEY", "NINEROUTER_KEY", "RERANK_KEY",
116
+ ]);
117
+ if (!baseUrl && !apiKey) return null;
118
+ // Heuristic: label the catch-all based on host for clarity in output.
119
+ const host = baseUrl ? new URL(baseUrl).hostname : "";
120
+ let id = "openai-compatible";
121
+ if (/9router|agentrouter/i.test(host)) id = "9router";
122
+ return {
123
+ id,
124
+ name: id,
125
+ baseUrl: baseUrl || null,
126
+ apiKey: apiKey || null,
127
+ chatModel: pickEnv(env, [
128
+ "MCP_RERANK_MODEL", "MCP_LLM_MODEL", "RERANK_MODEL", "LLM_MODEL",
129
+ "NINEROUTER_CHAT_MODEL", "NINEROUTER_RERANK_MODEL", "NINEROUTER_MODEL",
130
+ ]) || null,
131
+ embedModel: pickEnv(env, [
132
+ "MCP_EMBED_MODEL", "EMBED_MODEL", "NINEROUTER_EMBED_MODEL",
133
+ ]) || null,
134
+ supportsChat: true,
135
+ supportsEmbed: true,
136
+ source: "MCP_LLM_BASE_URL",
137
+ };
138
+ }
139
+
140
+ /**
141
+ * Build the provider matrix from environment variables.
142
+ * Returns a deduplicated list of provider records.
143
+ * @param {Record<string,string|undefined>} env
144
+ * @returns {Array<{id, name, baseUrl, apiKey, chatModel, embedModel, supportsChat, supportsEmbed, source}>}
145
+ */
146
+ export function buildProviderMatrix(env) {
147
+ const out = [];
148
+ const seen = new Set();
149
+
150
+ const push = (p) => {
151
+ if (!p || !p.baseUrl && !p.apiKey) return;
152
+ if (seen.has(p.id)) return;
153
+ seen.add(p.id);
154
+ out.push(p);
155
+ };
156
+
157
+ // 1. Primary + numbered slots
158
+ push(readProviderSlot(env, "PRIMARY"));
159
+ for (let i = 2; i <= 10; i++) {
160
+ push(readProviderSlot(env, `CHAIN${i}`));
161
+ }
162
+
163
+ // 2. Named providers (Groq, Cerebras, Mistral, OpenRouter, OpenAI, Ollama)
164
+ for (const id of ["groq", "cerebras", "mistral", "openrouter", "openai", "ollama", "anthropic", "gemini", "cohere", "voyage", "cloudflare"]) {
165
+ push(readNamedProvider(env, id));
166
+ }
167
+
168
+ // 3. Catch-all: existing 9router-like config from MCP_LLM_BASE_URL etc.
169
+ push(read9routerLike(env));
170
+
171
+ return out;
172
+ }
173
+
174
+ /**
175
+ * Shape a probe result into the canonical record used by formatting helpers.
176
+ */
177
+ export function shapeProbe({ name, kind, ok, latencyMs = null, status = null, sample = null, error = null, dim = null }) {
178
+ return { name, kind, ok, latencyMs, status, sample, error, dim };
179
+ }
180
+
181
+ // ---- formatting ----
182
+
183
+ function fmtLatency(ms) {
184
+ if (ms == null) return "—";
185
+ if (ms < 1000) return `${ms}ms`;
186
+ return `${(ms / 1000).toFixed(2)}s`;
187
+ }
188
+
189
+ export function formatText(results) {
190
+ const lines = [];
191
+ lines.push("Dev MCP Suite — provider smoke");
192
+ lines.push("==============================");
193
+ // group by provider
194
+ const byName = new Map();
195
+ for (const r of results) {
196
+ if (!byName.has(r.name)) byName.set(r.name, []);
197
+ byName.get(r.name).push(r);
198
+ }
199
+ for (const [name, rs] of byName) {
200
+ lines.push(`\n[${name}]`);
201
+ for (const r of rs) {
202
+ const mark = r.ok ? "✓" : "✗";
203
+ const lat = r.ok ? fmtLatency(r.latencyMs) : "";
204
+ const detail = r.ok
205
+ ? `${r.status || ""} ${lat}${r.sample ? ` "${String(r.sample).slice(0, 40)}"` : ""}${r.dim ? ` dim=${r.dim}` : ""}`.trim()
206
+ : `${r.status || "—"} ${r.error || "unknown error"}`;
207
+ lines.push(` ${mark} ${r.kind.padEnd(10)} ${detail}`);
208
+ }
209
+ }
210
+ lines.push("");
211
+ return lines.join("\n");
212
+ }
213
+
214
+ export function formatJson(results) {
215
+ return JSON.stringify(results, null, 2);
216
+ }
217
+
218
+ export function formatMarkdown(results) {
219
+ const lines = [];
220
+ lines.push("# Provider smoke matrix");
221
+ lines.push("");
222
+ lines.push(`_Generated ${new Date().toISOString()}_`);
223
+ lines.push("");
224
+ lines.push("| Provider | Kind | Status | Latency | HTTP | Sample / dim | Error |");
225
+ lines.push("|---|---|---|---|---|---|---|");
226
+ for (const r of results) {
227
+ const okMark = r.ok ? "✓" : "✗";
228
+ const sample = r.ok ? (r.sample ? `\`${String(r.sample).slice(0, 30)}\`` : (r.dim ? `dim=${r.dim}` : "—")) : "—";
229
+ const err = r.ok ? "" : (r.error || "").replace(/\|/g, "\\|");
230
+ lines.push(`| ${r.name} | ${r.kind} | ${okMark} | ${fmtLatency(r.latencyMs)} | ${r.status || "—"} | ${sample} | ${err} |`);
231
+ }
232
+ lines.push("");
233
+ return lines.join("\n");
234
+ }
package/lib/prune.js ADDED
@@ -0,0 +1,114 @@
1
+ /**
2
+ * Dev MCP Suite — prune library.
3
+ *
4
+ * Identifies and removes "temp" project slugs (prefix `tmp.`) from all three
5
+ * stores. Used by `bin/prune.mjs`. No MCP, no stdio — safe to import from tests.
6
+ *
7
+ * Storage layout (matches the rest of the suite):
8
+ * <root>/vault/<slug>/
9
+ * <root>/journal/<slug>/
10
+ * <root>/checkpoints/<slug>/
11
+ */
12
+
13
+ import fs from "fs";
14
+ import path from "path";
15
+
16
+ export const STORES = ["vault", "journal", "checkpoints"];
17
+ const TEMP_PREFIX = "tmp.";
18
+
19
+ /** Returns the list of slug names matching temp pattern across all stores. */
20
+ export function findTempSlugs({ root }) {
21
+ const set = new Set();
22
+ for (const store of STORES) {
23
+ let entries = [];
24
+ try {
25
+ entries = fs.readdirSync(path.join(root, store), { withFileTypes: true });
26
+ } catch { continue; }
27
+ for (const e of entries) {
28
+ if (e.isDirectory() && e.name.startsWith(TEMP_PREFIX)) set.add(e.name);
29
+ }
30
+ }
31
+ return [...set].sort();
32
+ }
33
+
34
+ /** Recursively sum bytes under each slug's directories across stores. */
35
+ export function estimateBytes({ root, slugs }) {
36
+ let total = 0;
37
+ for (const slug of slugs) {
38
+ for (const store of STORES) {
39
+ total += dirSize(path.join(root, store, slug));
40
+ }
41
+ }
42
+ return total;
43
+ }
44
+
45
+ function dirSize(p) {
46
+ let total = 0;
47
+ let stack = [p];
48
+ while (stack.length) {
49
+ const cur = stack.pop();
50
+ let stat;
51
+ try { stat = fs.lstatSync(cur); } catch { continue; }
52
+ if (stat.isDirectory()) {
53
+ let children = [];
54
+ try { children = fs.readdirSync(cur); } catch { continue; }
55
+ for (const c of children) stack.push(path.join(cur, c));
56
+ } else {
57
+ total += stat.size;
58
+ }
59
+ }
60
+ return total;
61
+ }
62
+
63
+ /** Validate slugs only contain temp prefix — refuse to delete otherwise. */
64
+ function assertTempSlugs(slugs) {
65
+ for (const s of slugs) {
66
+ if (!s.startsWith(TEMP_PREFIX)) {
67
+ throw new Error(`refusing to remove non-temp slug: "${s}" (must start with "${TEMP_PREFIX}")`);
68
+ }
69
+ }
70
+ }
71
+
72
+ /** Compute a plan: per-slug list of stores where the dir exists + total bytes. */
73
+ export function planPrune({ root }) {
74
+ const slugs = findTempSlugs({ root });
75
+ return slugs.map((slug) => {
76
+ const stores = [];
77
+ for (const store of STORES) {
78
+ const p = path.join(root, store, slug);
79
+ try {
80
+ if (fs.existsSync(p)) stores.push(store);
81
+ } catch { /* ignore */ }
82
+ }
83
+ const bytes = estimateBytes({ root, slugs: [slug] });
84
+ return { slug, stores, bytes };
85
+ });
86
+ }
87
+
88
+ /**
89
+ * Remove temp slugs from all stores. Default is dry-run (no deletion).
90
+ * @param {{ root: string, slugs: string[], dryRun?: boolean }} opts
91
+ * @returns {{ removed: string[], skipped: string[], errors: Array<{slug:string,store:string,error:string}> }}
92
+ */
93
+ export function applyPrune({ root, slugs, dryRun = true }) {
94
+ assertTempSlugs(slugs);
95
+ const removed = [];
96
+ const skipped = [];
97
+ const errors = [];
98
+ for (const slug of slugs) {
99
+ let anyRemoved = false;
100
+ for (const store of STORES) {
101
+ const p = path.join(root, store, slug);
102
+ if (!fs.existsSync(p)) continue;
103
+ if (dryRun) { skipped.push(slug); continue; }
104
+ try {
105
+ fs.rmSync(p, { recursive: true, force: true });
106
+ anyRemoved = true;
107
+ } catch (e) {
108
+ errors.push({ slug, store, error: String(e && e.message || e) });
109
+ }
110
+ }
111
+ if (anyRemoved) removed.push(slug);
112
+ }
113
+ return { removed, skipped, errors };
114
+ }