@deepsql/mcp 0.14.0 → 0.17.0

package/src/commands/mcp.js

@@ -23,11 +23,11 @@
  */
 
 const fs = require("node:fs");
-const os = require("node:os");
 const path = require("node:path");
 const { spawn, spawnSync } = require("node:child_process");
 
 const { resolveSession } = require("./_session");
+const { userHome } = require("../user-home");
 
 const SKILL_HEADER_MARKER = "<!-- BEGIN DEEPSQL DBA CONSULT SKILL -->";
 const SKILL_FOOTER_MARKER = "<!-- END DEEPSQL DBA CONSULT SKILL -->";
@@ -44,7 +44,7 @@ const EDITORS = {
     // (the official CLI handles future storage changes for us). If
     // `claude` isn't on PATH (e.g. CI, SSH boxes), we fall back to
     // writing ~/.claude.json directly via the standard JSON merge.
-    path: () => path.join(os.homedir(), ".claude.json"),
+    path: () => path.join(userHome(), ".claude.json"),
     key: "mcpServers",
     cli: {
       binary: "claude",
@@ -59,7 +59,7 @@ const EDITORS = {
     },
     skill: {
       kind: "file",
-      path: () => path.join(os.homedir(), ".claude", "skills", "deepsql", "SKILL.md"),
+      path: () => path.join(userHome(), ".claude", "skills", "deepsql", "SKILL.md"),
       frontmatter: () => [
         "---",
         "name: deepsql",
@@ -77,11 +77,11 @@ const EDITORS = {
   },
   "cursor": {
     format: "json",
-    path: () => path.join(os.homedir(), ".cursor", "mcp.json"),
+    path: () => path.join(userHome(), ".cursor", "mcp.json"),
     key: "mcpServers",
     skill: {
       kind: "file",
-      path: () => path.join(os.homedir(), ".cursor", "rules", "deepsql.mdc"),
+      path: () => path.join(userHome(), ".cursor", "rules", "deepsql.mdc"),
       frontmatter: () => [
         "---",
         "description: DeepSQL DBA consult — call DeepSQL's MCP tools BEFORE generating any DDL, migration, or non-trivial SQL. Get brain context, schema, business rules, and anti-patterns first; then narrate findings to the user before proposing schema.",
@@ -100,11 +100,11 @@ const EDITORS = {
   },
   "codex": {
     format: "toml",
-    path: () => path.join(os.homedir(), ".codex", "config.toml"),
+    path: () => path.join(userHome(), ".codex", "config.toml"),
     key: "mcp_servers",
     skill: {
       kind: "agents-append", // Codex reads AGENTS.md; we append a guarded section
-      path: () => path.join(os.homedir(), ".codex", "AGENTS.md"),
+      path: () => path.join(userHome(), ".codex", "AGENTS.md"),
       frontmatter: () => "",
     },
   },
@@ -589,12 +589,12 @@ function claudeDesktopPath() {
   //        Desktop isn't officially shipped on Linux yet but the pattern
   //        matches the XDG default).
   if (process.platform === "darwin") {
-    return path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    return path.join(userHome(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
   }
   if (process.platform === "win32" && process.env.APPDATA) {
     return path.join(process.env.APPDATA, "Claude", "claude_desktop_config.json");
   }
-  return path.join(os.homedir(), ".config", "Claude", "claude_desktop_config.json");
+  return path.join(userHome(), ".config", "Claude", "claude_desktop_config.json");
 }
 
 module.exports = {

package/src/commands/slow-queries.js

@@ -29,12 +29,17 @@ const SUBCOMMANDS = {
   analyze: cmdAnalyze,
   optimize: cmdOptimize,
   delete: cmdDelete,
+  trends: cmdTrends,
+  regressions: cmdRegressions,
+  timeline: cmdTimeline,
 };
 
 async function run(opts, io = {}) {
   const sub = opts.positional[0];
   if (!sub) {
-    throw new Error("Usage: deepsql slow-queries <latest|history|analyze|optimize|delete> ...");
+    throw new Error(
+      "Usage: deepsql slow-queries "
+      + "<latest|history|analyze|optimize|delete|trends|regressions|timeline> ...");
   }
   const handler = SUBCOMMANDS[sub];
   if (!handler) throw new Error(`Unknown slow-queries subcommand: ${sub}.`);
@@ -275,6 +280,116 @@ function safeParse(text) {
   }
 }
 
+// ─── trends ──────────────────────────────────────────────────────────────
+// 30-day analytics: tracked queries, regressions, and per-query timelines.
+
+async function cmdTrends(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const queries = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}/queries`,
+    { token: session.token },
+  );
+  const items = Array.isArray(queries) ? queries : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write("No tracked queries yet. The daily analysis runs at 01:30, "
+      + "or trigger one now from the UI / API.\n");
+    return;
+  }
+  printTrendRows(stdout, items);
+}
+
+async function cmdRegressions(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const minFactor = parseNum(opts["min-factor"]) || 1.5;
+  const rows = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}/regressions?minFactor=${minFactor}`,
+    { token: session.token },
+  );
+  const items = Array.isArray(rows) ? rows : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write(`No queries regressed by ${minFactor}x or more on the latest run.\n`);
+    return;
+  }
+  printTable(stdout, [
+    { key: "fingerprint", label: "QUERY ID" },
+    { key: "factor", label: "SLOWDOWN" },
+    { key: "meanMs", label: "MEAN MS" },
+    { key: "calls", label: "CALLS" },
+    { key: "sql", label: "QUERY" },
+  ], items.map((r) => ({
+    fingerprint: trim(r.fingerprint || "", 14),
+    factor: r.regressionFactor != null ? `${r.regressionFactor.toFixed(2)}x` : "?",
+    meanMs: r.meanExecMs != null ? Math.round(r.meanExecMs).toString() : "?",
+    calls: String(r.callsDelta ?? "?"),
+    sql: trim(r.normalizedSql || "", 56),
+  })));
+}
+
+async function cmdTimeline(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const fingerprint = opts.positional[0];
+  if (!fingerprint) {
+    throw new Error("Usage: deepsql slow-queries timeline <fingerprint> --connection <name>");
+  }
+  const points = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}`
+      + `/timeline/${encodeURIComponent(fingerprint)}`,
+    { token: session.token },
+  );
+  const items = Array.isArray(points) ? points : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write("No timeline data for that query fingerprint.\n");
+    return;
+  }
+  printTable(stdout, [
+    { key: "day", label: "DAY" },
+    { key: "calls", label: "CALLS" },
+    { key: "meanMs", label: "MEAN MS" },
+    { key: "maxMs", label: "MAX MS" },
+    { key: "factor", label: "VS PREV" },
+  ], items.map((p) => ({
+    day: String(p.day || ""),
+    calls: String(p.callsDelta ?? "?"),
+    meanMs: p.meanExecMs != null ? Math.round(p.meanExecMs).toString() : "?",
+    maxMs: p.maxExecMs != null ? Math.round(p.maxExecMs).toString() : "?",
+    factor: p.regressionFactor != null ? `${p.regressionFactor.toFixed(2)}x` : "—",
+  })));
+}
+
+function printTrendRows(stdout, items) {
+  printTable(stdout, [
+    { key: "fingerprint", label: "QUERY ID" },
+    { key: "meanMs", label: "MEAN MS" },
+    { key: "calls", label: "CALLS" },
+    { key: "factor", label: "VS PREV" },
+    { key: "sql", label: "QUERY" },
+  ], items.map((q) => ({
+    fingerprint: trim(q.fingerprint || "", 14),
+    meanMs: q.meanExecMs != null ? Math.round(q.meanExecMs).toString() : "?",
+    calls: String(q.callsDelta ?? "?"),
+    factor: q.regressionFactor != null ? `${q.regressionFactor.toFixed(2)}x` : "—",
+    sql: trim(q.normalizedSql || "", 54),
+  })));
+}
+
 function printHistory(stdout, items) {
   const rows = items.map((h) => ({
     id: String(h.id ?? h.historyId ?? ""),

package/src/user-home.js

@@ -0,0 +1,29 @@
+"use strict";
+
+/**
+ * Resolves the real user's home directory, even when the CLI is run via sudo.
+ *
+ * Priority: HOME env var → SUDO_USER /etc/passwd lookup → os.homedir().
+ * The "/root" guard on HOME handles `sudo -H` (which sets HOME=/root) while
+ * still respecting `sudo -E` (which preserves the original HOME).
+ */
+
+const fs = require("node:fs");
+const os = require("node:os");
+
+function userHome() {
+  if (process.env.HOME && process.env.HOME !== "/root") return process.env.HOME;
+  if (process.env.SUDO_USER) {
+    try {
+      const passwd = fs.readFileSync("/etc/passwd", "utf8");
+      const line = passwd.split("\n").find(l => l.startsWith(process.env.SUDO_USER + ":"));
+      if (line) {
+        const home = line.split(":")[5];
+        if (home) return home;
+      }
+    } catch (_) { /* fall through */ }
+  }
+  return os.homedir();
+}
+
+module.exports = { userHome };

package/src/commands/index-recommendations.js

@@ -1,426 +0,0 @@
-"use strict";
-
-/**
- * `deepsql index-recommendations` — surface DeepSQL's DBA-grade index
- * advisor from the terminal. Mirrors the MCP tools (`get_index_recommendations`
- * + `apply_index_recommendation`) so an on-call DBA gets the same workflow
- * an AI coding agent does, without needing the IDE plumbing.
- *
- * Subcommands:
- *   deepsql index-recommendations top    --connection <name> [--limit N] [--json]
- *   deepsql index-recommendations list   --connection <name> [--json]
- *   deepsql index-recommendations show   <id> [--json]
- *   deepsql index-recommendations refresh --connection <name> [--json]
- *   deepsql index-recommendations apply  <id> [--mode dry-run|apply|apply-and-measure]
- *                                              [--confirm] [--concurrent|--no-concurrent]
- *                                              [--json]
- *   deepsql index-recommendations dismiss <id> [--json]
- *
- * Default output is a compact terminal-friendly table. `--json` passes the
- * raw backend payload through, which is what callers from scripts / CI
- * pipelines want.
- *
- * Apply is the one mutation. The contract matches the MCP tool: default
- * mode is `dry-run` (HypoPG-based, no writes); the two write modes
- * (`apply`, `apply-and-measure`) require `--confirm`. `--no-concurrent`
- * opts out of CREATE INDEX CONCURRENTLY when the brief ACCESS EXCLUSIVE
- * lock is acceptable (small dev tables, or after the DBA has drained the
- * connection pool).
- */
-
-const { ApiError, request } = require("../api/client");
-const { resolveSession } = require("./_session");
-const { resolveConnectionId } = require("./_connections");
-
-const SUBCOMMANDS = {
-  top: cmdTop,
-  list: cmdList,
-  show: cmdShow,
-  refresh: cmdRefresh,
-  apply: cmdApply,
-  dismiss: cmdDismiss,
-};
-
-async function run(opts, io = {}) {
-  const sub = opts.positional[0];
-  if (!sub) {
-    throw new Error(
-      "Usage: deepsql index-recommendations <top|list|show|refresh|apply|dismiss> …"
-    );
-  }
-  const handler = SUBCOMMANDS[sub];
-  if (!handler) {
-    throw new Error(`Unknown index-recommendations subcommand: ${sub}.`);
-  }
-  return wrap(handler)(
-    { ...opts, positional: opts.positional.slice(1) },
-    io
-  );
-}
-
-function wrap(handler) {
-  return async (opts, io) => {
-    try {
-      return await handler(opts, io);
-    } catch (err) {
-      if (err instanceof ApiError && err.status === 403) {
-        throw new Error(
-          "Access denied — index-recommendation operations require permissions on this connection."
-        );
-      }
-      if (err instanceof ApiError && err.status === 404) {
-        throw new Error(err.message || "Recommendation not found.");
-      }
-      throw err;
-    }
-  };
-}
-
-// ─── top ───────────────────────────────────────────────────────────────────
-
-async function cmdTop(opts, { stdout = process.stdout } = {}) {
-  const session = resolveSession(opts);
-  const connectionId = await resolveConnectionId(session, opts.connection);
-  const limit = clampLimit(opts.limit, 5);
-  const result = await request(
-    session.baseUrl,
-    `/index-recommendations/${encodeURIComponent(connectionId)}/top`,
-    { token: session.token, query: { limit } }
-  );
-
-  if (opts.json) {
-    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    return;
-  }
-
-  const list = Array.isArray(result) ? result : [];
-  if (list.length === 0) {
-    stdout.write(
-      "No pending index recommendations. The 6-hour refresh scheduler may not have run yet, " +
-        "or the workload has none worth flagging. Try `deepsql index-recommendations refresh` " +
-        "to force a fresh accumulation cycle.\n"
-    );
-    return;
-  }
-
-  stdout.write(`Top ${list.length} pending index recommendation(s):\n\n`);
-  list.forEach((r, idx) => {
-    const action = r.kind === "DROP_INDEX" ? "DROP" : "CREATE";
-    const target =
-      r.kind === "DROP_INDEX"
-        ? `${r.tableName}.${r.indexName} (unused)`
-        : `${r.tableName}(${r.columnNames})`;
-
-    const meta = [
-      r.priority,
-      r.occurrenceCount != null ? `seen ${r.occurrenceCount}×` : null,
-      formatNet(r),
-      r.evidenceCount > 0 ? `${r.evidenceCount} ev` : null,
-    ]
-      .filter(Boolean)
-      .join(", ");
-
-    stdout.write(`${idx + 1}. [${action}] ${target} — ${meta}\n`);
-    stdout.write(`   id: ${r.id}\n`);
-    if (r.hypopgReductionPct != null) {
-      stdout.write(
-        `   HypoPG cost: ${formatCost(r.hypopgBeforeCost)} → ${formatCost(r.hypopgAfterCost)} ` +
-          `(${signedPct(r.hypopgReductionPct)})\n`
-      );
-    }
-    if (r.reason) {
-      stdout.write(`   ${truncate(r.reason, 200)}\n`);
-    }
-    if (Array.isArray(r.topEvidence) && r.topEvidence.length) {
-      const ev = r.topEvidence[0];
-      stdout.write(
-        `   top evidence: ${ev.calls} calls × ${formatMs(ev.meanExecTimeMs)}` +
-          ` mean = ${formatMs(ev.totalExecTimeMs)} total (${ev.role})\n`
-      );
-    }
-    stdout.write("\n");
-  });
-}
-
-// ─── list / show ───────────────────────────────────────────────────────────
-
-async function cmdList(opts, { stdout = process.stdout } = {}) {
-  const session = resolveSession(opts);
-  const connectionId = await resolveConnectionId(session, opts.connection);
-  const result = await request(
-    session.baseUrl,
-    `/index-recommendations/pending/${encodeURIComponent(connectionId)}`,
-    { token: session.token }
-  );
-  if (opts.json) {
-    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    return;
-  }
-  const list = Array.isArray(result) ? result : [];
-  if (list.length === 0) {
-    stdout.write("No pending index recommendations.\n");
-    return;
-  }
-  stdout.write(`${list.length} pending recommendation(s):\n\n`);
-  list.forEach((r, idx) => {
-    const action = r.kind === "DROP_INDEX" ? "DROP" : "CREATE";
-    stdout.write(
-      `${idx + 1}. [${action}] ${r.tableName}(${r.columnNames || r.indexName}) — ${r.priority}, occ=${r.occurrenceCount}, id=${r.id}\n`
-    );
-  });
-}
-
-async function cmdShow(opts, { stdout = process.stdout } = {}) {
-  const id = opts.positional[0];
-  if (!id) throw new Error("Usage: deepsql index-recommendations show <id>");
-  const session = resolveSession(opts);
-  // No direct GET by id endpoint — use the connection's top with a wide
-  // limit and filter client-side. Cheap enough for inspection use.
-  const connectionId = opts.connection
-    ? await resolveConnectionId(session, opts.connection)
-    : null;
-  if (!connectionId) {
-    throw new Error(
-      "`show` needs --connection <name> to look up the recommendation (or pin one with `deepsql connections use`)."
-    );
-  }
-  const list = await request(
-    session.baseUrl,
-    `/index-recommendations/${encodeURIComponent(connectionId)}/top`,
-    { token: session.token, query: { limit: 50 } }
-  );
-  const found = (list || []).find((r) => r.id === id);
-  if (!found) {
-    throw new Error(`Recommendation ${id} not in the top-50 for this connection.`);
-  }
-  if (opts.json) {
-    stdout.write(`${JSON.stringify(found, null, 2)}\n`);
-    return;
-  }
-  renderRecommendationDetail(stdout, found);
-}
-
-// ─── refresh ───────────────────────────────────────────────────────────────
-
-async function cmdRefresh(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
-  const session = resolveSession(opts);
-  const connectionId = await resolveConnectionId(session, opts.connection);
-  stderr.write(`Refreshing index recommendations on ${opts.connection || connectionId}…\n`);
-  const result = await request(
-    session.baseUrl,
-    `/index-recommendations/generate/${encodeURIComponent(connectionId)}`,
-    { method: "POST", token: session.token, timeoutMs: 600000 }
-  );
-  if (opts.json) {
-    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    return;
-  }
-  if (result && result.success) {
-    stdout.write(
-      `Refresh complete: ${result.count} candidate(s) merged. ` +
-        `Use \`deepsql index-recommendations top\` to see the top-N.\n`
-    );
-  } else {
-    stdout.write(`Refresh response: ${JSON.stringify(result)}\n`);
-  }
-}
-
-// ─── apply ─────────────────────────────────────────────────────────────────
-
-async function cmdApply(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
-  const id = opts.positional[0];
-  if (!id) {
-    throw new Error(
-      "Usage: deepsql index-recommendations apply <id> [--mode dry-run|apply|apply-and-measure] [--confirm] [--no-concurrent]"
-    );
-  }
-
-  const mode = normalizeMode(opts.mode);
-  const isWriteMode = mode === "APPLY" || mode === "APPLY_AND_MEASURE";
-  if (isWriteMode && !opts.confirm) {
-    throw new Error(
-      `Mode ${mode} mutates the target database. Re-run with --confirm to proceed.`
-    );
-  }
-  // --concurrent defaults to true; --no-concurrent flips it off (parser
-  // surfaces noConcurrent boolean).
-  const concurrent = !opts.noConcurrent;
-
-  const session = resolveSession(opts);
-  if (isWriteMode) {
-    stderr.write(`Running ${mode} on recommendation ${id}…\n`);
-  }
-
-  const result = await request(
-    session.baseUrl,
-    `/index-recommendations/${encodeURIComponent(id)}/apply`,
-    {
-      method: "POST",
-      token: session.token,
-      timeoutMs: 600000,
-      query: { mode, confirm: opts.confirm === true, concurrent },
-    }
-  );
-
-  if (opts.json) {
-    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    return;
-  }
-  renderApplyResult(stdout, result);
-}
-
-// ─── dismiss ───────────────────────────────────────────────────────────────
-
-async function cmdDismiss(opts, { stdout = process.stdout } = {}) {
-  const id = opts.positional[0];
-  if (!id) throw new Error("Usage: deepsql index-recommendations dismiss <id>");
-  const session = resolveSession(opts);
-  const result = await request(
-    session.baseUrl,
-    `/index-recommendations/${encodeURIComponent(id)}/dismiss`,
-    { method: "PUT", token: session.token }
-  );
-  if (opts.json) {
-    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    return;
-  }
-  stdout.write(`Dismissed recommendation ${id}.\n`);
-}
-
-// ─── formatting helpers ────────────────────────────────────────────────────
-
-function renderRecommendationDetail(stdout, r) {
-  const action = r.kind === "DROP_INDEX" ? "DROP" : "CREATE";
-  stdout.write(`[${action}] ${r.tableName}(${r.columnNames || r.indexName})\n`);
-  stdout.write(`  id            : ${r.id}\n`);
-  stdout.write(`  priority      : ${r.priority}\n`);
-  stdout.write(`  status        : ${r.status || "PENDING"}\n`);
-  stdout.write(`  occurrenceCnt : ${r.occurrenceCount}\n`);
-  stdout.write(`  workloadScore : ${formatMs(r.workloadScoreMs)}\n`);
-  stdout.write(`  writeCost     : ${formatMs(r.writeCostScore)}\n`);
-  stdout.write(`  netBenefit    : ${formatMs(r.netBenefitMs)}\n`);
-  if (r.hypopgReductionPct != null) {
-    stdout.write(
-      `  HypoPG        : ${formatCost(r.hypopgBeforeCost)} → ${formatCost(r.hypopgAfterCost)} ` +
-        `(${signedPct(r.hypopgReductionPct)})\n`
-    );
-  }
-  stdout.write(`  DDL           : ${r.createStatement}\n`);
-  if (r.reason) stdout.write(`  reason        : ${r.reason}\n`);
-  if (Array.isArray(r.topEvidence) && r.topEvidence.length) {
-    stdout.write(`  contributing queries (${r.topEvidence.length}):\n`);
-    for (const ev of r.topEvidence) {
-      stdout.write(
-        `    - fp=${(ev.fingerprint || "?").slice(0, 12)} calls=${ev.calls} mean=${formatMs(ev.meanExecTimeMs)} total=${formatMs(ev.totalExecTimeMs)} role=${ev.role}\n`
-      );
-      if (ev.exampleSql) {
-        stdout.write(`      ${truncate(ev.exampleSql, 200)}\n`);
-      }
-    }
-  }
-}
-
-function renderApplyResult(stdout, r) {
-  if (!r || typeof r !== "object") {
-    stdout.write("Apply returned no body.\n");
-    return;
-  }
-  const status = r.status || "?";
-  if (status === "BLOCKED_NEEDS_CONFIRMATION") {
-    stdout.write(`[${r.mode}] blocked — pass --confirm to mutate the database.\n`);
-    return;
-  }
-  if (status === "NOT_FOUND") {
-    stdout.write(`[${r.mode}] recommendation not found: ${r.recommendationId}\n`);
-    return;
-  }
-  if (status === "NO_USABLE_SAMPLES") {
-    stdout.write(
-      `[${r.mode}] no literal-bearing contributing queries available; cannot measure.\n`
-    );
-    return;
-  }
-  if (status === "FAILED") {
-    stdout.write(`[${r.mode}] failed: ${r.message || "(no message)"}\n`);
-    return;
-  }
-
-  stdout.write(`[${r.mode}] ${status}\n`);
-  stdout.write(`  DDL: ${r.executedDdl}\n`);
-  if (r.beforeCost != null && r.afterCost != null) {
-    stdout.write(
-      `  planner cost: ${formatCost(r.beforeCost)} → ${formatCost(r.afterCost)} ` +
-        `(${signedPct(r.costReductionPct)})\n`
-    );
-  }
-  if (r.beforeWallTimeMs != null && r.afterWallTimeMs != null) {
-    stdout.write(
-      `  wall time: ${formatMs(r.beforeWallTimeMs)} → ${formatMs(r.afterWallTimeMs)} ` +
-        `(${signedPct(r.wallTimeImprovementPct)})\n`
-    );
-  }
-  if (Array.isArray(r.samples) && r.samples.length) {
-    stdout.write(`  ${r.samples.length} contributing query sample(s):\n`);
-    for (const s of r.samples.slice(0, 5)) {
-      stdout.write(
-        `    fp=${(s.fingerprint || "?").slice(0, 12)} cost ${formatCost(s.beforeCost)} → ${formatCost(s.afterCost)}` +
-          (s.error ? ` (error: ${s.error})` : "") +
-          "\n"
-      );
-    }
-  }
-  if (r.message) stdout.write(`  ${r.message}\n`);
-}
-
-function clampLimit(raw, fallback) {
-  const n = Number.parseInt(raw, 10);
-  if (!Number.isFinite(n)) return fallback;
-  return Math.min(50, Math.max(1, n));
-}
-
-function normalizeMode(raw) {
-  if (!raw) return "DRY_RUN";
-  // Accept dash-form (CLI convention) and underscore-form (API enum).
-  const m = String(raw).toUpperCase().replace(/-/g, "_");
-  if (!["DRY_RUN", "APPLY", "APPLY_AND_MEASURE"].includes(m)) {
-    throw new Error(`Unknown mode: ${raw}. Expected dry-run, apply, or apply-and-measure.`);
-  }
-  return m;
-}
-
-function formatMs(ms) {
-  if (ms == null || !Number.isFinite(Number(ms))) return "—";
-  const n = Number(ms);
-  if (n <= 0) return "0ms";
-  if (n >= 86_400_000) return `${(n / 86_400_000).toFixed(1)}d`;
-  if (n >= 3_600_000) return `${(n / 3_600_000).toFixed(1)}h`;
-  if (n >= 60_000) return `${(n / 60_000).toFixed(1)}m`;
-  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}s`;
-  return `${n.toFixed(n >= 10 ? 0 : 1)}ms`;
-}
-
-function formatCost(c) {
-  if (c == null || !Number.isFinite(Number(c))) return "—";
-  return Number(c).toFixed(0);
-}
-
-function signedPct(pct) {
-  if (pct == null || !Number.isFinite(Number(pct))) return "—";
-  const sign = pct >= 0 ? "−" : "+";
-  return `${sign}${Math.abs(pct).toFixed(1)}%`;
-}
-
-function formatNet(r) {
-  if (r.netBenefitMs != null && r.netBenefitMs > 0) {
-    return `net=${formatMs(r.netBenefitMs)} saved`;
-  }
-  if (r.estimatedImpact != null) return `impact ${r.estimatedImpact}`;
-  return null;
-}
-
-function truncate(s, max) {
-  if (!s) return s;
-  return s.length <= max ? s : `${s.slice(0, max)}…`;
-}
-
-module.exports = { run };