@deepsql/mcp 0.14.0 → 0.16.0

package/CLAUDE.md

@@ -211,9 +211,10 @@ for them to say yes, then re-call with `confirmMutation: true`.
 
 **"What indexes should we add?"** → `get_index_recommendations`. Returns
 the workload-weighted top-N (default 5) with net benefit, contributing
-queries, and HypoPG cost-delta when available. Use `deepsql indexes
-missing` / `deepsql indexes health` in the terminal for catalog-level
-counterparts (usage stats, duplicates).
+queries, and HypoPG cost-delta when available. The terminal equivalent
+is `deepsql indexes top` (same data, same ranking); `deepsql indexes
+missing` / `health` / `unused` / `duplicates` cover the catalog-level
+diagnostics that complement the workload-weighted advisor.
 
 **"How much faster will this index actually make things?"** →
 `apply_index_recommendation` with `mode: "DRY_RUN"` (default). On
@@ -225,7 +226,10 @@ the index (CONCURRENTLY) and run `EXPLAIN ANALYZE` before/after.
 
 **"What changed recently / what should I worry about?"** → Tell the user to
 run `deepsql digest` (today) or `deepsql digest 7` (last seven). The digest
-isn't MCP-exposed.
+isn't MCP-exposed. The digest now includes a workload-weighted **Index Wins**
+section that surfaces the same top-N recommendations `get_index_recommendations`
+returns, with the `deepsql indexes apply <id> --mode dry-run` CTA — so a user
+who skims the digest in Slack can flow directly into the apply path.
 
 **"Are there foreign keys between X and Y?"** → `get_relationships`. Many
 real-world DBs lack declared FKs but DeepSQL's brain infers them; check the
@@ -318,11 +322,16 @@ them at the terminal command rather than trying to fake it through
 
 | Capability | CLI command |
 |---|---|
-| Catalog-level index stats (counterpart to `get_index_recommendations`) | `deepsql indexes list`, `deepsql indexes missing` |
-| Unused / duplicate index detection | `deepsql indexes unused`, `deepsql indexes duplicates` |
-| Per-table index usage stats | `deepsql indexes usage <table>` |
-| Index health report | `deepsql indexes health` |
-| Workload-weighted advisor + apply (DBA-grade) | `deepsql index-recommendations top` / `apply <id>` — same surface as the MCP `get_index_recommendations` + `apply_index_recommendation` tools, useful from a terminal |
+| Workload-weighted advisor (terminal mirror of `get_index_recommendations`) | `deepsql indexes top [--limit N]` |
+| Apply / dry-run an advisor recommendation (terminal mirror of `apply_index_recommendation`) | `deepsql indexes apply <id> [--mode dry-run\|apply\|apply-and-measure] [--confirm]` |
+| Force a fresh accumulation cycle | `deepsql indexes refresh` |
+| Full recommendation detail incl. contributing queries | `deepsql indexes show <id>` |
+| Dismiss a recommendation | `deepsql indexes dismiss <id>` |
+| Browse all recommendations (any status) | `deepsql indexes list [--all\|--status …]` |
+| Catalog: missing-index suggestions | `deepsql indexes missing` |
+| Catalog: unused / duplicate index detection | `deepsql indexes unused`, `deepsql indexes duplicates` |
+| Catalog: per-table index usage stats | `deepsql indexes usage <table>` |
+| Catalog: index health report | `deepsql indexes health` |
 | Daily digest (anomalies + AI commentary) | `deepsql digest`, `deepsql digest 7` |
 | Streaming AI optimization for a slow query | `deepsql slow-queries optimize --query-id <id>` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",

package/src/cli.js

@@ -36,7 +36,6 @@ const COMMANDS = {
   access: () => require("./commands/access"),
   permissions: () => require("./commands/permissions"),
   "slow-queries": () => require("./commands/slow-queries"),
-  "index-recommendations": () => require("./commands/index-recommendations"),
   setup: () => require("./commands/setup"),
 };
 
@@ -60,8 +59,7 @@ const COMMAND_LIST = [
   ["business-rules", false, "List active business rules and SQL guardrails"],
   ["relationships",  false, "List inferred and validated FK relationships"],
   ["anti-patterns",  false, "List schema- or query-level anti-patterns"],
-  ["indexes",        true,  "Index suggestions, usage, and health (read-only)"],
-  ["index-recommendations", true, "Workload-weighted index advisor + HypoPG-validated apply tool"],
+  ["indexes",        true,  "Workload-weighted index advisor + catalog diagnostics (top, apply, list, missing, health, unused, duplicates, usage)"],
   ["users",          true,  "Manage workspace users (admin)"],
   ["access",         true,  "Manage per-connection access grants (admin)"],
   ["permissions",    true,  "Manage role-based permission overrides (admin)"],
@@ -267,23 +265,41 @@ const COMMAND_HELP = {
   },
 
   indexes: {
-    description: "Index suggestions, usage, and health — read-only in V1.",
+    description:
+      "Unified index advisor — workload-weighted recommendations + catalog diagnostics. " +
+      "`apply` is the one mutation; dry-run is the default and uses HypoPG on Postgres " +
+      "to estimate cost-delta without writes. Write modes (apply / apply-and-measure) " +
+      "require --confirm.",
     usage: "deepsql indexes <subcommand> [options]",
     subcommands: [
-      ["list [--all] [--status <s>]", "Index recommendations (defaults to PENDING)"],
-      ["missing",                     "Missing-index suggestions from the advisor"],
-      ["health",                      "Comprehensive index health report"],
-      ["unused",                      "Indexes the engine has not used"],
-      ["duplicates",                  "Duplicate or redundant indexes"],
-      ["usage <table>",               "Per-table index usage statistics"],
+      // Advisor (workload-weighted)
+      ["top    [--limit N]",                                  "Pre-computed top-N pending recommendations (default 5, max 50) — ranked by net benefit, with HypoPG cost-delta + contributing-query evidence"],
+      ["list   [--all] [--status PENDING|APPLIED|DISMISSED]", "All recommendations (defaults to PENDING) — simpler view than `top`"],
+      ["show   <id> --connection <name>",                     "Full detail: workload, write-cost, HypoPG cost, contributing queries"],
+      ["refresh",                                              "Force a fresh accumulation cycle (POST /generate)"],
+      ["apply  <id> [--mode <m>] [--confirm] [--no-concurrent]", "Run or dry-run a recommendation with before/after measurement"],
+      ["dismiss <id>",                                         "Mark a recommendation as DISMISSED"],
+      // Catalog diagnostics
+      ["missing",                                              "Missing-index suggestions from the catalog advisor"],
+      ["health",                                               "Comprehensive index health report"],
+      ["unused",                                               "Indexes the engine has not used (live pg_stat_user_indexes / sys.* probe)"],
+      ["duplicates",                                           "Duplicate or redundant indexes"],
+      ["usage  <table>",                                       "Per-table index usage statistics"],
     ],
     options: [
-      ["--connection <name>",            "Connection to inspect"],
-      ["--all",                          "Include APPLIED and DISMISSED in `list`"],
-      ["--status PENDING|APPLIED|DISMISSED", "Filter `list` by status"],
-      ["--json",                         "Raw JSON output"],
+      ["--connection <name>",                       "Connection to inspect"],
+      ["--limit <n>",                               "top: number of recommendations (default 5, max 50)"],
+      ["--all",                                     "list: include APPLIED and DISMISSED rows"],
+      ["--status PENDING|APPLIED|DISMISSED",        "list: filter by status"],
+      ["--mode dry-run|apply|apply-and-measure",    "apply: defaults to dry-run (HypoPG; no writes)"],
+      ["--confirm",                                 "apply: required for apply / apply-and-measure (write modes)"],
+      ["--no-concurrent",                           "apply: skip CREATE/DROP INDEX CONCURRENTLY (small dev tables)"],
+      ["--json",                                    "Raw backend JSON instead of the terminal-friendly table"],
     ],
-    notes: "V1 is read-only. Apply, dismiss, delete, and generate are not exposed by the CLI yet.",
+    notes:
+      "Mirrors the MCP `get_index_recommendations` + `apply_index_recommendation` tools — " +
+      "use this when you're at a terminal, the MCP tools when you're inside an AI client. " +
+      "Same backend, same data, same safety contract.",
   },
 
   users: {
@@ -363,33 +379,6 @@ const COMMAND_HELP = {
     notes: "Org and LLM config are set at install time and are NOT touched by this wizard.",
   },
 
-  "index-recommendations": {
-    description:
-      "DBA-grade workload-weighted index advisor. Default `top` shows pending " +
-      "recommendations ranked by net benefit (workload − write-cost). `apply` " +
-      "is the only mutation — dry-run uses HypoPG (Postgres-only) so no writes " +
-      "leak; the two write modes require --confirm.",
-    usage:
-      "deepsql index-recommendations <top|list|show|refresh|apply|dismiss> [options]",
-    subcommands: [
-      ["top    --connection <name> [--limit N]",     "Pre-computed top-N (default 5, max 50), evidence-bearing"],
-      ["list   --connection <name>",                  "All pending recommendations for the connection"],
-      ["show   <id> --connection <name>",             "Full detail: workload, HypoPG cost, contributing queries"],
-      ["refresh --connection <name>",                 "Force a fresh accumulation cycle (POST /generate)"],
-      ["apply  <id> [--mode <m>] [--confirm]",        "Run / dry-run with before/after measurement"],
-      ["dismiss <id>",                                 "Mark a recommendation as DISMISSED"],
-    ],
-    options: [
-      ["--limit <n>",        "top: number of recommendations (default 5, max 50)"],
-      ["--mode <m>",         "apply: dry-run (default) | apply | apply-and-measure"],
-      ["--confirm",          "apply: required for apply / apply-and-measure (write modes)"],
-      ["--no-concurrent",    "apply: skip CREATE/DROP INDEX CONCURRENTLY (dev / small tables)"],
-      ["--json",             "Emit raw backend JSON instead of the terminal-friendly table"],
-    ],
-    notes:
-      "Complements `deepsql indexes` (catalog-level usage / health). " +
-      "This namespace surfaces the workload-weighted advisor + the apply tool.",
-  },
 };
 
 // ─── Color helpers ──────────────────────────────────────────────────────────

package/src/commands/indexes.js

@@ -1,31 +1,47 @@
 "use strict";
 
 /**
- * `deepsql indexes` — index suggestions, usage, and health (read-only V1).
+ * `deepsql indexes` — unified index advisor namespace.
  *
- * Subcommands:
- *   list [--all | --status PENDING|APPLIED|DISMISSED]
- *                           GET /index-recommendations/{cid} (or /pending/{cid})
- *   missing                 GET /advisor/indexes/{cid}            (missing-index advisor)
- *   health                  GET /index-advisor/{cid}/health-report
- *   unused                  GET /index-advisor/{cid}/unused
- *   duplicates              GET /index-advisor/{cid}/duplicates
- *   usage <table>           GET /index-advisor/{cid}/usage/{tableName}
+ * Two categories of subcommand live here, sharing the same `--connection` /
+ * `--json` flag plumbing:
  *
- * Everything is read-only by design — V1 surfaces suggestions only. Apply,
- * dismiss, delete, generate, and the estimate-create/estimate-drop endpoints
- * are intentionally not wired up here; they'll land in a later pass once we
- * have UX for confirming mutations.
+ *   Advisor (workload-weighted, evidence-bearing — mirrors the MCP tools):
+ *     top      [--limit N]                            GET    /index-recommendations/{cid}/top
+ *     list     [--all | --status PENDING|APPLIED|…]   GET    /index-recommendations/{cid}[?status=]
+ *     show     <id>                                   GET    /index-recommendations/{cid}/top (client-side filter)
+ *     refresh                                         POST   /index-recommendations/generate/{cid}
+ *     apply    <id> [--mode … --confirm --no-concurrent]  POST  /index-recommendations/{id}/apply
+ *     dismiss  <id>                                   PUT    /index-recommendations/{id}/dismiss
+ *
+ *   Catalog diagnostics (read-only — live pg_stat_* / sys.* probes):
+ *     missing                                         GET    /advisor/indexes/{cid}
+ *     health                                          GET    /index-advisor/{cid}/health-report
+ *     unused                                          GET    /index-advisor/{cid}/unused
+ *     duplicates                                      GET    /index-advisor/{cid}/duplicates
+ *     usage    <table>                                GET    /index-advisor/{cid}/usage/{tableName}
+ *
+ * The `apply` subcommand is the one mutation here. Default mode is dry-run
+ * (HypoPG-based, no writes on Postgres). `apply` / `apply-and-measure`
+ * require `--confirm`; `--no-concurrent` opts out of CREATE/DROP INDEX
+ * CONCURRENTLY.
  */
 
-const { request } = require("../api/client");
+const { ApiError, request } = require("../api/client");
 const { resolveSession } = require("./_session");
 const { resolveConnectionId } = require("./_connections");
 
 const VALID_STATUSES = new Set(["PENDING", "APPLIED", "DISMISSED"]);
 
 const SUBCOMMANDS = {
+  // Advisor surface (workload-weighted)
+  top: cmdTop,
   list: cmdList,
+  show: cmdShow,
+  refresh: cmdRefresh,
+  apply: cmdApply,
+  dismiss: cmdDismiss,
+  // Catalog diagnostics
   missing: cmdMissing,
   health: cmdHealth,
   unused: cmdUnused,
@@ -38,10 +54,101 @@ async function run(opts, io = {}) {
   const handler = SUBCOMMANDS[sub];
   if (!handler) {
     throw new Error(
-      `Unknown indexes subcommand: ${sub}. Try \`list\`, \`missing\`, \`health\`, \`unused\`, \`duplicates\`, or \`usage <table>\`.`,
+      `Unknown indexes subcommand: ${sub}. ` +
+        `Try one of: top, list, show, refresh, apply, dismiss, ` +
+        `missing, health, unused, duplicates, usage <table>.`,
     );
   }
-  return handler({ ...opts, positional: opts.positional.slice(1) }, io);
+  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 operations require permissions on this connection.",
+        );
+      }
+      if (err instanceof ApiError && err.status === 404) {
+        throw new Error(err.message || "Recommendation not found.");
+      }
+      throw err;
+    }
+  };
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// ADVISOR SURFACE — workload-weighted, evidence-bearing
+// (mirrors the `get_index_recommendations` + `apply_index_recommendation` MCP tools)
+// ═════════════════════════════════════════════════════════════════════════════
+
+// ─── 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 indexes 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 ──────────────────────────────────────────────────────────────────
@@ -58,9 +165,6 @@ async function cmdList(opts, { stdout = process.stdout } = {}) {
     );
   }
 
-  // `pending/{cid}` is a server-side filter for the common path; otherwise pull
-  // the full list and filter client-side so a user can scope to APPLIED /
-  // DISMISSED without a second backend route.
   const path = wantAll
     ? `/index-recommendations/${encodeURIComponent(connectionId)}`
     : `/index-recommendations/pending/${encodeURIComponent(connectionId)}`;
@@ -104,6 +208,125 @@ async function cmdList(opts, { stdout = process.stdout } = {}) {
   }
 }
 
+// ─── show <id> ─────────────────────────────────────────────────────────────
+
+async function cmdShow(opts, { stdout = process.stdout } = {}) {
+  const id = opts.positional[0];
+  if (!id) throw new Error("Usage: deepsql indexes show <id> --connection <name>");
+  const session = resolveSession(opts);
+  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 indexes top\` to see the top-N.\n`,
+    );
+  } else {
+    stdout.write(`Refresh response: ${JSON.stringify(result)}\n`);
+  }
+}
+
+// ─── apply <id> (the one mutation) ─────────────────────────────────────────
+
+async function cmdApply(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const id = opts.positional[0];
+  if (!id) {
+    throw new Error(
+      "Usage: deepsql indexes 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.`,
+    );
+  }
+  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 <id> ──────────────────────────────────────────────────────────
+
+async function cmdDismiss(opts, { stdout = process.stdout } = {}) {
+  const id = opts.positional[0];
+  if (!id) throw new Error("Usage: deepsql indexes 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`);
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// CATALOG DIAGNOSTICS — live pg_stat_* / sys.* probes
+// ═════════════════════════════════════════════════════════════════════════════
+
 // ─── missing ───────────────────────────────────────────────────────────────
 
 async function cmdMissing(opts, { stdout = process.stdout } = {}) {
@@ -278,7 +501,92 @@ async function cmdUsage(opts, { stdout = process.stdout } = {}) {
   }
 }
 
-// ─── helpers ───────────────────────────────────────────────────────────────
+// ═════════════════════════════════════════════════════════════════════════════
+// 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 priorityWeight(p) {
   switch (String(p || "").toUpperCase()) {
@@ -290,6 +598,57 @@ function priorityWeight(p) {
   }
 }
 
+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)}…`;
+}
+
 function oneLine(s) {
   return String(s).replace(/\s+/g, " ").trim();
 }