@deepsql/mcp 0.10.1 → 0.11.0

package/src/cli.test.js

@@ -3,7 +3,18 @@
 const test = require("node:test");
 const assert = require("node:assert/strict");
 
-const { parseArgs, buildOpts } = require("./cli");
+const { parseArgs, buildOpts, main, renderRootHelp, renderCommandHelp, COMMAND_HELP } = require("./cli");
+
+function captureStreams() {
+  let out = "";
+  let err = "";
+  return {
+    stdout: { write: (s) => { out += s; }, isTTY: false },
+    stderr: { write: (s) => { err += s; }, isTTY: false },
+    out: () => out,
+    err: () => err,
+  };
+}
 
 test("parseArgs collects positional args", () => {
   const { positional, flags } = parseArgs(["how", "many", "rows"]);
@@ -36,3 +47,72 @@ test("buildOpts maps known flags", () => {
   assert.equal(opts.limit, "50");
   assert.deepEqual(opts.positional, ["SELECT 1"]);
 });
+
+test("renderRootHelp lists every command and marks subcommand-bearing ones with *", () => {
+  const text = renderRootHelp(false);
+  assert.match(text, /🐬 DeepSQL/);
+  assert.match(text, /Hint: commands suffixed with \* have subcommands/);
+  // Leaf command — no star.
+  assert.match(text, /\n\s+login\s+ /);
+  // Parent commands — must carry a star.
+  for (const name of ["config", "connections", "digest", "users", "access", "permissions", "slow-queries"]) {
+    assert.match(text, new RegExp(`\\n\\s+${name} \\*`), `expected "${name} *" in root help`);
+  }
+});
+
+test("renderCommandHelp emits subcommands and options for parent commands", () => {
+  const text = renderCommandHelp("connections", false);
+  assert.match(text, /Usage: deepsql connections/);
+  assert.match(text, /Subcommands:/);
+  assert.match(text, /Options:/);
+  assert.match(text, /list \[--json\]/);
+});
+
+test("every command in the catalog has a COMMAND_HELP entry", () => {
+  // Sourced from the dispatcher map so the lists stay in lockstep.
+  const { main: _main } = require("./cli");
+  void _main;
+  const expected = [
+    "login","logout","whoami","config","mcp","connections","query","explain","schema",
+    "digest","brain-context","business-rules","relationships","anti-patterns","indexes",
+    "users","access","permissions","slow-queries","setup",
+  ];
+  for (const name of expected) {
+    assert.ok(COMMAND_HELP[name], `missing COMMAND_HELP for ${name}`);
+    assert.ok(COMMAND_HELP[name].usage, `missing usage for ${name}`);
+  }
+});
+
+test("main prints root help on no args and on --help", async () => {
+  for (const argv of [[], ["--help"], ["-h"]]) {
+    const io = captureStreams();
+    const code = await main(argv, io);
+    assert.equal(code, 0);
+    assert.match(io.out(), /Usage: deepsql \[options\] \[command\]/);
+  }
+});
+
+test("main prints per-command help when --help follows the command", async () => {
+  const io = captureStreams();
+  const code = await main(["connections", "--help"], io);
+  assert.equal(code, 0);
+  assert.match(io.out(), /Usage: deepsql connections/);
+  assert.match(io.out(), /Subcommands:/);
+});
+
+test("main rejects unknown commands and shows the root help", async () => {
+  const io = captureStreams();
+  const code = await main(["nope-not-real"], io);
+  assert.equal(code, 2);
+  assert.match(io.err(), /Unknown command: nope-not-real/);
+  assert.match(io.err(), /Usage: deepsql/);
+});
+
+test("--no-color suppresses ANSI escapes in help output", async () => {
+  const io = captureStreams();
+  // Force a TTY so the only thing turning color off is --no-color itself.
+  io.stdout.isTTY = true;
+  await main(["--help", "--no-color"], io);
+  // No ESC bytes anywhere.
+  assert.equal(/\x1b\[/.test(io.out()), false, "help output should be plain when --no-color is set");
+});

package/src/commands/indexes.js

@@ -0,0 +1,306 @@
+"use strict";
+
+/**
+ * `deepsql indexes` — index suggestions, usage, and health (read-only V1).
+ *
+ * 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}
+ *
+ * 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.
+ */
+
+const { request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+const VALID_STATUSES = new Set(["PENDING", "APPLIED", "DISMISSED"]);
+
+const SUBCOMMANDS = {
+  list: cmdList,
+  missing: cmdMissing,
+  health: cmdHealth,
+  unused: cmdUnused,
+  duplicates: cmdDuplicates,
+  usage: cmdUsage,
+};
+
+async function run(opts, io = {}) {
+  const sub = opts.positional[0] || "list";
+  const handler = SUBCOMMANDS[sub];
+  if (!handler) {
+    throw new Error(
+      `Unknown indexes subcommand: ${sub}. Try \`list\`, \`missing\`, \`health\`, \`unused\`, \`duplicates\`, or \`usage <table>\`.`,
+    );
+  }
+  return handler({ ...opts, positional: opts.positional.slice(1) }, io);
+}
+
+// ─── list ──────────────────────────────────────────────────────────────────
+
+async function cmdList(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const wantAll = !!opts.all || (opts.status && opts.status !== "PENDING");
+  const statusFilter = opts.status ? String(opts.status).toUpperCase() : null;
+  if (statusFilter && !VALID_STATUSES.has(statusFilter)) {
+    throw new Error(
+      `Invalid --status "${opts.status}". One of: ${[...VALID_STATUSES].join(", ")}.`,
+    );
+  }
+
+  // `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)}`;
+
+  const response = await request(session.baseUrl, path, { token: session.token });
+  let list = Array.isArray(response) ? response : [];
+  if (statusFilter && statusFilter !== "PENDING") {
+    list = list.filter((r) => String(r.status || "").toUpperCase() === statusFilter);
+  }
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(list, null, 2)}\n`);
+    return;
+  }
+
+  if (list.length === 0) {
+    const scope = statusFilter || (wantAll ? "any" : "pending");
+    stdout.write(`No ${scope.toLowerCase()} index recommendations for this connection.\n`);
+    return;
+  }
+
+  const byPriority = (a, b) => priorityWeight(b.priority) - priorityWeight(a.priority);
+  list.sort(byPriority);
+
+  const scopeLabel = statusFilter || (wantAll ? "all" : "pending");
+  const noun = list.length === 1 ? "recommendation" : "recommendations";
+  stdout.write(`${list.length} ${scopeLabel} ${noun}:\n\n`);
+
+  for (const r of list) {
+    const prio = r.priority ? `[${r.priority}]` : "[?]";
+    const cols = r.columnNames || "?";
+    const status = r.status ? ` (${r.status})` : "";
+    const impact = r.estimatedImpact != null ? `, impact≈${r.estimatedImpact}%` : "";
+    const affected = r.affectedQueries != null ? `, ${r.affectedQueries} queries` : "";
+    stdout.write(`${prio} ${r.tableName || "?"}(${cols})${status}\n`);
+    if (r.indexName) stdout.write(`  name:   ${r.indexName}\n`);
+    if (r.reason) stdout.write(`  reason: ${r.reason}${impact}${affected}\n`);
+    if (r.createStatement) stdout.write(`  ddl:    ${oneLine(r.createStatement)}\n`);
+    if (r.id) stdout.write(`  id:     ${r.id}\n`);
+    stdout.write("\n");
+  }
+}
+
+// ─── missing ───────────────────────────────────────────────────────────────
+
+async function cmdMissing(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const response = await request(
+    session.baseUrl,
+    `/advisor/indexes/${encodeURIComponent(connectionId)}`,
+    { token: session.token },
+  );
+  const list = Array.isArray(response) ? response : [];
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(list, null, 2)}\n`);
+    return;
+  }
+  if (list.length === 0) {
+    stdout.write("No missing-index suggestions for this connection.\n");
+    return;
+  }
+
+  stdout.write(`${list.length} missing-index ${list.length === 1 ? "suggestion" : "suggestions"}:\n\n`);
+  for (const r of list) {
+    const prio = r.priority ? `[${r.priority}]` : "[?]";
+    const cols = formatColumns(r.columnNames || r.columns);
+    stdout.write(`${prio} ${r.tableName || "?"}(${cols})\n`);
+    if (r.reason) stdout.write(`  reason: ${r.reason}\n`);
+    if (r.estimatedImpact != null) stdout.write(`  impact: ${r.estimatedImpact}\n`);
+    if (r.suggestedIndex) stdout.write(`  ddl:    ${oneLine(r.suggestedIndex)}\n`);
+    stdout.write("\n");
+  }
+}
+
+// ─── health ────────────────────────────────────────────────────────────────
+
+async function cmdHealth(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const response = await request(
+    session.baseUrl,
+    `/index-advisor/${encodeURIComponent(connectionId)}/health-report`,
+    { token: session.token },
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+  if (!response || typeof response !== "object") {
+    stdout.write("No health report available.\n");
+    return;
+  }
+
+  stdout.write("Index health report\n");
+  stdout.write("───────────────────\n");
+  for (const [key, value] of Object.entries(response)) {
+    if (value == null) continue;
+    if (Array.isArray(value)) {
+      stdout.write(`${pad(key)} ${value.length} entries\n`);
+    } else if (typeof value === "object") {
+      stdout.write(`${pad(key)} ${JSON.stringify(value)}\n`);
+    } else {
+      stdout.write(`${pad(key)} ${value}\n`);
+    }
+  }
+}
+
+// ─── unused ────────────────────────────────────────────────────────────────
+
+async function cmdUnused(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const response = await request(
+    session.baseUrl,
+    `/index-advisor/${encodeURIComponent(connectionId)}/unused`,
+    { token: session.token },
+  );
+  const list = Array.isArray(response) ? response : [];
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(list, null, 2)}\n`);
+    return;
+  }
+  if (list.length === 0) {
+    stdout.write("No unused indexes detected.\n");
+    return;
+  }
+
+  stdout.write(`${list.length} unused ${list.length === 1 ? "index" : "indexes"}:\n\n`);
+  for (const idx of list) {
+    const size = idx.sizeMb != null ? `, ${idx.sizeMb} MB` : (idx.indexSize ? `, ${idx.indexSize}` : "");
+    const scans = idx.scans != null ? `, scans=${idx.scans}` : (idx.indexScans != null ? `, scans=${idx.indexScans}` : "");
+    stdout.write(
+      `  • ${idx.tableName || idx.table || "?"}.${idx.indexName || idx.name || "?"}${size}${scans}\n`,
+    );
+  }
+}
+
+// ─── duplicates ────────────────────────────────────────────────────────────
+
+async function cmdDuplicates(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const response = await request(
+    session.baseUrl,
+    `/index-advisor/${encodeURIComponent(connectionId)}/duplicates`,
+    { token: session.token },
+  );
+  const list = Array.isArray(response) ? response : [];
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(list, null, 2)}\n`);
+    return;
+  }
+  if (list.length === 0) {
+    stdout.write("No duplicate or redundant indexes detected.\n");
+    return;
+  }
+
+  stdout.write(`${list.length} duplicate ${list.length === 1 ? "group" : "groups"}:\n\n`);
+  for (const dup of list) {
+    const table = dup.tableName || dup.table || "?";
+    const names = Array.isArray(dup.indexes)
+      ? dup.indexes.map((i) => (typeof i === "string" ? i : i.indexName || i.name)).join(", ")
+      : (dup.indexName || dup.name || "?");
+    stdout.write(`  • ${table}: ${names}\n`);
+    if (dup.reason) stdout.write(`      ${dup.reason}\n`);
+  }
+}
+
+// ─── usage <table> ─────────────────────────────────────────────────────────
+
+async function cmdUsage(opts, { stdout = process.stdout } = {}) {
+  const tableName = opts.positional[0];
+  if (!tableName) {
+    throw new Error("Usage: deepsql indexes usage <tableName> --connection <name> [--json]");
+  }
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const response = await request(
+    session.baseUrl,
+    `/index-advisor/${encodeURIComponent(connectionId)}/usage/${encodeURIComponent(tableName)}`,
+    { token: session.token },
+  );
+  const list = Array.isArray(response) ? response : [];
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(list, null, 2)}\n`);
+    return;
+  }
+  if (list.length === 0) {
+    stdout.write(`No index usage stats for ${tableName}.\n`);
+    return;
+  }
+
+  stdout.write(`Index usage for ${tableName} (${list.length} ${list.length === 1 ? "index" : "indexes"}):\n\n`);
+  for (const idx of list) {
+    const scans = idx.scans ?? idx.indexScans ?? "?";
+    const reads = idx.tuplesRead ?? idx.tupReads ?? null;
+    const fetched = idx.tuplesFetched ?? idx.tupFetched ?? null;
+    const extra = [
+      `scans=${scans}`,
+      reads != null ? `reads=${reads}` : null,
+      fetched != null ? `fetched=${fetched}` : null,
+    ].filter(Boolean).join(", ");
+    stdout.write(`  • ${idx.indexName || idx.name || "?"} — ${extra}\n`);
+  }
+}
+
+// ─── helpers ───────────────────────────────────────────────────────────────
+
+function priorityWeight(p) {
+  switch (String(p || "").toUpperCase()) {
+    case "CRITICAL": return 4;
+    case "HIGH":     return 3;
+    case "MEDIUM":   return 2;
+    case "LOW":      return 1;
+    default:         return 0;
+  }
+}
+
+function oneLine(s) {
+  return String(s).replace(/\s+/g, " ").trim();
+}
+
+function formatColumns(cols) {
+  if (Array.isArray(cols)) return cols.join(", ");
+  return cols || "?";
+}
+
+function pad(key) {
+  return `${key}:`.padEnd(28);
+}
+
+module.exports = { run };

package/src/commands/indexes.test.js

@@ -0,0 +1,298 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const Module = require("node:module");
+
+const { parseArgs, buildOpts } = require("../cli");
+
+function opts(argv) {
+  return buildOpts(parseArgs(argv));
+}
+
+// ─── argv plumbing ─────────────────────────────────────────────────────────
+
+test("indexes flags: --all, --status, --json land in opts", () => {
+  const o = opts(["list", "--all", "--status", "APPLIED", "--json"]);
+  assert.equal(o.all, true);
+  assert.equal(o.status, "APPLIED");
+  assert.equal(o.json, true);
+  assert.deepEqual(o.positional, ["list"]);
+});
+
+test("indexes usage <table> keeps the table name as positional[1]", () => {
+  const o = opts(["usage", "users", "--connection", "c1"]);
+  assert.deepEqual(o.positional, ["usage", "users"]);
+  assert.equal(o.connection, "c1");
+});
+
+// ─── dispatch ──────────────────────────────────────────────────────────────
+//
+// Build a fake api/client + _session + _connections so the `run` handlers
+// don't try to hit the network. We stub them via Node's `require.cache` so
+// they intercept the next require() inside indexes.js.
+
+function loadWithStubs({ requests = [], responses = {} }) {
+  // Reset the modules we're about to stub + the indexes module itself.
+  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 {},
+      async request(_base, path) {
+        requests.push(path);
+        if (Object.prototype.hasOwnProperty.call(responses, path)) {
+          return responses[path];
+        }
+        return [];
+      },
+    },
+  };
+
+  const sessKey = require.resolve("./_session");
+  require.cache[sessKey] = {
+    id: sessKey,
+    filename: sessKey,
+    loaded: true,
+    exports: {
+      resolveSession: () => ({ baseUrl: "http://test", token: "t" }),
+    },
+  };
+
+  const connKey = require.resolve("./_connections");
+  require.cache[connKey] = {
+    id: connKey,
+    filename: connKey,
+    loaded: true,
+    exports: {
+      resolveConnectionId: async () => "00000000-0000-0000-0000-000000000001",
+      listConnections: async () => [],
+    },
+  };
+
+  return require("./indexes");
+}
+
+function captureStdout() {
+  let out = "";
+  return {
+    stream: { write: (s) => { out += s; } },
+    out: () => out,
+  };
+}
+
+test("indexes list (default) hits the /pending endpoint", async () => {
+  const requests = [];
+  const indexes = loadWithStubs({
+    requests,
+    responses: {
+      "/index-recommendations/pending/00000000-0000-0000-0000-000000000001": [],
+    },
+  });
+  const stdout = captureStdout();
+  await indexes.run(opts(["list"]), { stdout: stdout.stream });
+  assert.equal(requests.length, 1);
+  assert.match(requests[0], /\/index-recommendations\/pending\//);
+  assert.match(stdout.out(), /No pending index recommendations/);
+});
+
+test("indexes list --all hits the all-recs endpoint", async () => {
+  const requests = [];
+  const indexes = loadWithStubs({
+    requests,
+    responses: {
+      "/index-recommendations/00000000-0000-0000-0000-000000000001": [],
+    },
+  });
+  const stdout = captureStdout();
+  await indexes.run(opts(["list", "--all"]), { stdout: stdout.stream });
+  assert.equal(requests.length, 1);
+  assert.equal(requests[0], "/index-recommendations/00000000-0000-0000-0000-000000000001");
+});
+
+test("indexes list renders priority, name, ddl per recommendation", async () => {
+  const indexes = loadWithStubs({
+    responses: {
+      "/index-recommendations/pending/00000000-0000-0000-0000-000000000001": [
+        {
+          id: "r1",
+          tableName: "orders",
+          columnNames: "customer_id, created_at",
+          indexName: "idx_orders_customer_created",
+          createStatement: "CREATE INDEX idx_orders_customer_created ON orders (customer_id, created_at)",
+          priority: "HIGH",
+          estimatedImpact: 42,
+          affectedQueries: 7,
+          reason: "Hot lookup pattern from chat history",
+          status: "PENDING",
+        },
+      ],
+    },
+  });
+  const stdout = captureStdout();
+  await indexes.run(opts(["list"]), { stdout: stdout.stream });
+  const text = stdout.out();
+  assert.match(text, /\[HIGH\] orders\(customer_id, created_at\)/);
+  assert.match(text, /idx_orders_customer_created/);
+  assert.match(text, /CREATE INDEX idx_orders_customer_created/);
+  assert.match(text, /impact≈42%/);
+  assert.match(text, /7 queries/);
+});
+
+test("indexes list --status filters client-side and switches to the all endpoint", async () => {
+  const requests = [];
+  const indexes = loadWithStubs({
+    requests,
+    responses: {
+      "/index-recommendations/00000000-0000-0000-0000-000000000001": [
+        { id: "a", tableName: "t1", columnNames: "x", priority: "LOW", status: "APPLIED" },
+        { id: "b", tableName: "t2", columnNames: "y", priority: "HIGH", status: "DISMISSED" },
+      ],
+    },
+  });
+  const stdout = captureStdout();
+  await indexes.run(opts(["list", "--status", "DISMISSED"]), { stdout: stdout.stream });
+  assert.match(requests[0], /\/index-recommendations\/00000000/);
+  const text = stdout.out();
+  assert.match(text, /1 DISMISSED recommendation/);
+  assert.match(text, /\[HIGH\] t2/);
+  assert.equal(/t1/.test(text), false, "applied row should be filtered out");
+});
+
+test("indexes list rejects bogus --status values", async () => {
+  const indexes = loadWithStubs({});
+  await assert.rejects(
+    indexes.run(opts(["list", "--status", "REJECTED"]), { stdout: captureStdout().stream }),
+    /Invalid --status/,
+  );
+});
+
+test("indexes usage <table> wires the table into the URL", async () => {
+  const requests = [];
+  const indexes = loadWithStubs({
+    requests,
+    responses: {
+      "/index-advisor/00000000-0000-0000-0000-000000000001/usage/users": [],
+    },
+  });
+  const stdout = captureStdout();
+  await indexes.run(opts(["usage", "users"]), { stdout: stdout.stream });
+  assert.equal(requests[0], "/index-advisor/00000000-0000-0000-0000-000000000001/usage/users");
+});
+
+test("indexes usage without a table name throws a friendly Usage:", async () => {
+  const indexes = loadWithStubs({});
+  await assert.rejects(
+    indexes.run(opts(["usage"]), { stdout: captureStdout().stream }),
+    /Usage: deepsql indexes usage <tableName>/,
+  );
+});
+
+test("indexes unused prints size and scan counts in the text view", async () => {
+  const indexes = loadWithStubs({
+    responses: {
+      "/index-advisor/00000000-0000-0000-0000-000000000001/unused": [
+        { tableName: "orders", indexName: "idx_old", sizeMb: 120, scans: 0 },
+      ],
+    },
+  });
+  const stdout = captureStdout();
+  await indexes.run(opts(["unused"]), { stdout: stdout.stream });
+  assert.match(stdout.out(), /orders\.idx_old, 120 MB, scans=0/);
+});
+
+test("indexes duplicates handles the empty case", async () => {
+  const indexes = loadWithStubs({
+    responses: {
+      "/index-advisor/00000000-0000-0000-0000-000000000001/duplicates": [],
+    },
+  });
+  const stdout = captureStdout();
+  await indexes.run(opts(["duplicates"]), { stdout: stdout.stream });
+  assert.match(stdout.out(), /No duplicate or redundant indexes detected\./);
+});
+
+test("indexes health flattens the report into key: value lines", async () => {
+  const indexes = loadWithStubs({
+    responses: {
+      "/index-advisor/00000000-0000-0000-0000-000000000001/health-report": {
+        totalIndexes: 47,
+        unusedCount: 3,
+        duplicateGroups: 1,
+        items: [{ a: 1 }, { a: 2 }],
+      },
+    },
+  });
+  const stdout = captureStdout();
+  await indexes.run(opts(["health"]), { stdout: stdout.stream });
+  const text = stdout.out();
+  assert.match(text, /Index health report/);
+  assert.match(text, /totalIndexes:.*47/);
+  assert.match(text, /items:.*2 entries/);
+});
+
+test("indexes missing renders advisor-style suggestions", async () => {
+  const indexes = loadWithStubs({
+    responses: {
+      "/advisor/indexes/00000000-0000-0000-0000-000000000001": [
+        { tableName: "users", columns: ["email"], priority: "CRITICAL", reason: "Unindexed equality lookup", suggestedIndex: "CREATE INDEX idx_users_email ON users(email)" },
+      ],
+    },
+  });
+  const stdout = captureStdout();
+  await indexes.run(opts(["missing"]), { stdout: stdout.stream });
+  const text = stdout.out();
+  assert.match(text, /\[CRITICAL\] users\(email\)/);
+  assert.match(text, /idx_users_email/);
+});
+
+test("indexes <unknown-sub> throws a hint that lists the real ones", async () => {
+  const indexes = loadWithStubs({});
+  await assert.rejects(
+    indexes.run(opts(["nope"]), { stdout: captureStdout().stream }),
+    /Unknown indexes subcommand: nope/,
+  );
+});
+
+test("indexes list --json emits raw JSON and no human prose", async () => {
+  const indexes = loadWithStubs({
+    responses: {
+      "/index-recommendations/pending/00000000-0000-0000-0000-000000000001": [
+        { id: "r1", tableName: "t", columnNames: "x" },
+      ],
+    },
+  });
+  const stdout = captureStdout();
+  await indexes.run(opts(["list", "--json"]), { stdout: stdout.stream });
+  const text = stdout.out().trim();
+  const parsed = JSON.parse(text);
+  assert.equal(parsed.length, 1);
+  assert.equal(parsed[0].id, "r1");
+});
+
+// Keep the suite hermetic — flush the stubs back so later test files that
+// require these modules don't pick up our fakes.
+test.after(() => {
+  for (const k of [
+    require.resolve("../api/client"),
+    require.resolve("./_session"),
+    require.resolve("./_connections"),
+    require.resolve("./indexes"),
+  ]) {
+    delete require.cache[k];
+  }
+});
+
+// Quieten the unused-Module warning — we may use it later.
+void Module;