@deepsql/mcp 0.13.4 → 0.16.0

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();
 }

package/src/commands/indexes.test.js

@@ -281,6 +281,237 @@ test("indexes list --json emits raw JSON and no human prose", async () => {
   assert.equal(parsed[0].id, "r1");
 });
 
+// ═════════════════════════════════════════════════════════════════════════════
+// Advisor-surface tests (top / show / refresh / apply / dismiss)
+// — absorbed from the deprecated `index-recommendations` namespace in 0.15.0.
+// ═════════════════════════════════════════════════════════════════════════════
+
+// Richer stub that captures the full request signature (path, method, query)
+// so the advisor tests can assert on POST vs GET, query strings, etc. Same
+// shape as `loadWithStubs` above but with explicit request-object capture.
+function loadWithRichStubs({ requests = [], responder = () => [] }) {
+  for (const k of [
+    require.resolve("../api/client"),
+    require.resolve("./_session"),
+    require.resolve("./_connections"),
+    require.resolve("./indexes"),
+  ]) {
+    delete require.cache[k];
+  }
+
+  const apiKey = require.resolve("../api/client");
+  require.cache[apiKey] = {
+    id: apiKey,
+    filename: apiKey,
+    loaded: true,
+    exports: {
+      ApiError: class ApiError extends Error { constructor(m, s) { super(m); this.status = s; } },
+      async request(baseUrl, path, opts = {}) {
+        const captured = { path, method: opts.method || "GET", query: opts.query || null };
+        requests.push(captured);
+        return responder(captured);
+      },
+    },
+  };
+
+  const sessKey = require.resolve("./_session");
+  require.cache[sessKey] = {
+    id: sessKey, filename: sessKey, loaded: true,
+    exports: { resolveSession: () => ({ baseUrl: "http://test", token: "t", defaultConnection: null }) },
+  };
+
+  const connKey = require.resolve("./_connections");
+  require.cache[connKey] = {
+    id: connKey, filename: connKey, loaded: true,
+    exports: {
+      resolveConnectionId: async () => "conn-abc",
+      listConnections: async () => [],
+    },
+  };
+
+  return require("./indexes");
+}
+
+function captureStreams() {
+  let out = "";
+  let err = "";
+  return {
+    stdout: { write: (s) => { out += s; } },
+    stderr: { write: (s) => { err += s; } },
+    out: () => out,
+    err: () => err,
+  };
+}
+
+// ─── top ───────────────────────────────────────────────────────────────────
+
+test("indexes top renders workload-weighted summary with net-benefit + evidence", async () => {
+  const indexes = loadWithRichStubs({
+    responder: ({ path }) => {
+      assert.match(path, /\/index-recommendations\/conn-abc\/top$/);
+      return [{
+        id: "rec-1",
+        tableName: "orders",
+        columnNames: "customer_id,status",
+        kind: "CREATE_INDEX",
+        priority: "HIGH",
+        occurrenceCount: 4,
+        netBenefitMs: 4823000,
+        evidenceCount: 3,
+        reason: "Workload-weighted composite.",
+        hypopgBeforeCost: 1000,
+        hypopgAfterCost: 250,
+        hypopgReductionPct: 75,
+        topEvidence: [
+          { calls: 4500, meanExecTimeMs: 850, totalExecTimeMs: 3825000, role: "WHERE_EQ" },
+        ],
+      }];
+    },
+  });
+  const s = captureStreams();
+  await indexes.run(opts(["top", "--connection", "mylocalpg"]), s);
+  assert.match(s.out(), /\[CREATE\] orders\(customer_id,status\)/);
+  assert.match(s.out(), /seen 4×/);
+  assert.match(s.out(), /net=1\.3h saved/);
+  assert.match(s.out(), /HypoPG cost: 1000 → 250 \(−75\.0%\)/);
+  assert.match(s.out(), /id: rec-1/);
+  assert.match(s.out(), /top evidence: 4500 calls/);
+});
+
+test("indexes top renders an empty-state message", async () => {
+  const indexes = loadWithRichStubs({ responder: () => [] });
+  const s = captureStreams();
+  await indexes.run(opts(["top", "--connection", "c1"]), s);
+  assert.match(s.out(), /No pending index recommendations/);
+  assert.match(s.out(), /indexes refresh/); // points at the consolidated namespace, not the deprecated one
+});
+
+test("indexes top --limit clamps to [1, 50]", async () => {
+  const requests = [];
+  const indexes = loadWithRichStubs({ requests, responder: () => [] });
+  const s = captureStreams();
+  await indexes.run(opts(["top", "--connection", "c1", "--limit", "999"]), s);
+  await indexes.run(opts(["top", "--connection", "c1", "--limit", "0"]), s);
+  await indexes.run(opts(["top", "--connection", "c1", "--limit", "10"]), s);
+  assert.equal(requests[0].query.limit, 50);
+  assert.equal(requests[1].query.limit, 1);
+  assert.equal(requests[2].query.limit, 10);
+});
+
+test("indexes top --json passes the raw payload through", async () => {
+  const indexes = loadWithRichStubs({
+    responder: () => [{ id: "rec-1", tableName: "orders" }],
+  });
+  const s = captureStreams();
+  await indexes.run(opts(["top", "--connection", "c1", "--json"]), s);
+  const parsed = JSON.parse(s.out());
+  assert.equal(parsed[0].id, "rec-1");
+});
+
+// ─── apply (the one mutation) ──────────────────────────────────────────────
+
+test("indexes apply --mode apply without --confirm refuses up-front (no API call)", async () => {
+  const requests = [];
+  const indexes = loadWithRichStubs({ requests, responder: () => ({}) });
+  const s = captureStreams();
+  await assert.rejects(
+    () => indexes.run(opts(["apply", "rec-1", "--mode", "apply"]), s),
+    /Re-run with --confirm/,
+  );
+  assert.equal(requests.length, 0, "API should not be hit without --confirm");
+});
+
+test("indexes apply --mode dry-run defaults concurrent=true and surfaces planner-cost delta", async () => {
+  const requests = [];
+  const indexes = loadWithRichStubs({
+    requests,
+    responder: ({ path, method, query }) => {
+      assert.equal(path, "/index-recommendations/rec-1/apply");
+      assert.equal(method, "POST");
+      assert.deepEqual(query, { mode: "DRY_RUN", confirm: false, concurrent: true });
+      return {
+        recommendationId: "rec-1",
+        executedDdl: "CREATE INDEX idx_o_status ON orders (status);",
+        mode: "DRY_RUN",
+        status: "OK",
+        beforeCost: 1000,
+        afterCost: 250,
+        costReductionPct: 75,
+        samples: [{ fingerprint: "abc123def456", beforeCost: 1000, afterCost: 250 }],
+        message: "DRY_RUN complete — planner cost −75.0% (1000 → 250)",
+      };
+    },
+  });
+  const s = captureStreams();
+  await indexes.run(opts(["apply", "rec-1", "--mode", "dry-run"]), s);
+  assert.match(s.out(), /\[DRY_RUN\] OK/);
+  assert.match(s.out(), /planner cost: 1000 → 250 \(−75\.0%\)/);
+  assert.match(s.out(), /fp=abc123def456 cost 1000 → 250/);
+});
+
+test("indexes apply --no-concurrent passes concurrent=false to the backend", async () => {
+  const requests = [];
+  const indexes = loadWithRichStubs({
+    requests,
+    responder: () => ({ mode: "APPLY", status: "OK", executedDdl: "CREATE INDEX …" }),
+  });
+  const s = captureStreams();
+  await indexes.run(
+    opts(["apply", "rec-1", "--mode", "apply", "--confirm", "--no-concurrent"]),
+    s,
+  );
+  assert.deepEqual(requests[0].query, {
+    mode: "APPLY",
+    confirm: true,
+    concurrent: false,
+  });
+});
+
+test("indexes apply rejects unknown modes early (no API call)", async () => {
+  const requests = [];
+  const indexes = loadWithRichStubs({ requests, responder: () => ({}) });
+  const s = captureStreams();
+  await assert.rejects(
+    () => indexes.run(opts(["apply", "rec-1", "--mode", "bogus"]), s),
+    /Unknown mode/,
+  );
+  assert.equal(requests.length, 0);
+});
+
+// ─── refresh / dismiss / show ──────────────────────────────────────────────
+
+test("indexes refresh POSTs to /generate and surfaces the count", async () => {
+  const indexes = loadWithRichStubs({
+    responder: ({ path, method }) => {
+      assert.equal(path, "/index-recommendations/generate/conn-abc");
+      assert.equal(method, "POST");
+      return { success: true, count: 12, message: "Generated 12 index recommendations" };
+    },
+  });
+  const s = captureStreams();
+  await indexes.run(opts(["refresh", "--connection", "mylocalpg"]), s);
+  assert.match(s.out(), /Refresh complete: 12 candidate/);
+});
+
+test("indexes dismiss issues PUT /{id}/dismiss", async () => {
+  const requests = [];
+  const indexes = loadWithRichStubs({ requests, responder: () => ({}) });
+  const s = captureStreams();
+  await indexes.run(opts(["dismiss", "rec-9"]), s);
+  assert.equal(requests[0].path, "/index-recommendations/rec-9/dismiss");
+  assert.equal(requests[0].method, "PUT");
+  assert.match(s.out(), /Dismissed recommendation rec-9/);
+});
+
+test("indexes show <id> requires --connection", async () => {
+  const indexes = loadWithRichStubs({});
+  const s = captureStreams();
+  await assert.rejects(
+    () => indexes.run(opts(["show", "rec-1"]), s),
+    /needs --connection/,
+  );
+});
+
 // Keep the suite hermetic — flush the stubs back so later test files that
 // require these modules don't pick up our fakes.
 test.after(() => {