@deepsql/mcp 0.10.2 → 0.13.0

package/src/commands/analyze.js

@@ -0,0 +1,165 @@
+"use strict";
+
+/**
+ * `deepsql analyze` — AI-enriched query plan analysis.
+ *
+ * Hits the canonical Editor endpoint `/api/explain/analyze`. The response is
+ * an ExplainPlanAnalysis carrying:
+ *   - the parsed plan tree (planTree), raw plan text/JSON
+ *   - performance issues (slow nodes, missing index hints, bad estimates)
+ *   - index recommendations
+ *   - an LLM-written summary that takes the connection's schema, business
+ *     rules, and detected anti-patterns into account
+ *
+ * Two modes:
+ *   - default (`useAnalyze=false`)  Plain EXPLAIN, no execution. Safe for any
+ *                                   actor with read access to the connection.
+ *   - `--analyze` (`useAnalyze=true`) EXPLAIN ANALYZE — actually runs the
+ *                                   query. For mutations this requires the
+ *                                   same admin role + WHERE + confirmation
+ *                                   gate as `deepsql query`.
+ *
+ * Pass `--write` to confirm an EXPLAIN ANALYZE of a mutation upfront (skips
+ * the interactive prompt).
+ */
+
+const fs = require("node:fs");
+const { request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+const ui = require("../ui/prompts");
+
+async function run(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const sql = readSqlInput(opts);
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const body = {
+    connectionId,
+    query: sql,
+    useAnalyze: !!opts.analyze,
+    mutationConfirmed: !!opts.write,
+  };
+
+  let response;
+  try {
+    response = await runOnce(session, body);
+  } catch (err) {
+    // Two-step mutation: the policy gate throws when useAnalyze=true with
+    // a mutation and no confirm. The server packs requiresConfirmation
+    // into the error response body.
+    if (err.body && err.body.requiresConfirmation && !opts.write) {
+      const accepted = await promptForConfirmation(err.body, { stderr });
+      if (!accepted) {
+        stderr.write("Aborted.\n");
+        return;
+      }
+      response = await runOnce(session, { ...body, mutationConfirmed: true });
+    } else {
+      throw err;
+    }
+  }
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+  renderAnalysis(stdout, response);
+}
+
+async function runOnce(session, body) {
+  return request(session.baseUrl, "/explain/analyze", {
+    method: "POST",
+    token: session.token,
+    json: body,
+  });
+}
+
+async function promptForConfirmation(errorBody, { stderr = process.stderr }) {
+  stderr.write(
+    `\n⚠ ${errorBody.message || "EXPLAIN ANALYZE will actually execute this statement."}\n`,
+  );
+  if (errorBody.queryType) stderr.write(`  statement: ${errorBody.queryType}\n`);
+  const warnings = Array.isArray(errorBody.warnings) ? errorBody.warnings : [];
+  for (const w of warnings) {
+    stderr.write(`  • ${w}\n`);
+  }
+  stderr.write("\n");
+  return ui.confirm({ message: "Run EXPLAIN ANALYZE on the statement?", default: false });
+}
+
+function renderAnalysis(stdout, response) {
+  if (!response || typeof response !== "object") {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  // Plain EXPLAIN responses set wasExecuted=false; EXPLAIN ANALYZE sets it
+  // to true. Surface the distinction at the top.
+  const heading = response.wasExecuted
+    ? "Plan (executed via EXPLAIN ANALYZE):"
+    : "Plan (EXPLAIN, not executed):";
+  stdout.write(`${heading}\n`);
+
+  if (response.planText) {
+    stdout.write(`${String(response.planText).trim()}\n\n`);
+  } else if (response.planJson) {
+    stdout.write(`${response.planJson}\n\n`);
+  }
+
+  const numbers = [];
+  if (response.totalTimeMs != null) numbers.push(`total ${response.totalTimeMs}ms`);
+  if (response.executionTimeMs != null) numbers.push(`exec ${response.executionTimeMs}ms`);
+  if (response.planningTimeMs != null) numbers.push(`plan ${response.planningTimeMs}ms`);
+  if (response.estimatedRows != null) numbers.push(`est ${response.estimatedRows} rows`);
+  if (response.actualRows != null) numbers.push(`actual ${response.actualRows} rows`);
+  if (response.nodeCount != null) numbers.push(`${response.nodeCount} nodes`);
+  if (numbers.length) stdout.write(`Timings: ${numbers.join(", ")}\n\n`);
+
+  if (response.aiSummary) {
+    stdout.write(`Summary:\n${response.aiSummary.trim()}\n\n`);
+  }
+
+  const issues = Array.isArray(response.issues) ? response.issues : [];
+  if (issues.length > 0) {
+    stdout.write(`Issues (${issues.length}):\n`);
+    for (const issue of issues) {
+      const label = issue.severity ? `[${issue.severity}] ` : "";
+      stdout.write(`  • ${label}${issue.title || issue.message || JSON.stringify(issue)}\n`);
+      if (issue.message && issue.title) stdout.write(`      ${issue.message}\n`);
+    }
+    stdout.write("\n");
+  }
+
+  const recs = Array.isArray(response.indexRecommendations) ? response.indexRecommendations : [];
+  if (recs.length > 0) {
+    stdout.write(`Suggested indexes (${recs.length}):\n`);
+    for (const r of recs) {
+      const cols = Array.isArray(r.columns) ? r.columns.join(", ") : (r.columnNames || "?");
+      stdout.write(`  • ${r.tableName || "?"}(${cols})`);
+      if (r.estimatedImpact != null) stdout.write(`  impact≈${r.estimatedImpact}`);
+      stdout.write("\n");
+      if (r.suggestedSql) stdout.write(`      ${r.suggestedSql.trim()}\n`);
+    }
+    stdout.write("\n");
+  }
+
+  const tips = Array.isArray(response.optimizationSuggestions) ? response.optimizationSuggestions : [];
+  if (tips.length > 0) {
+    stdout.write(`Suggestions:\n`);
+    for (const t of tips) stdout.write(`  • ${t}\n`);
+  }
+
+  if (response.aiOptimization) {
+    stdout.write(`\nOptimization narrative:\n${response.aiOptimization.trim()}\n`);
+  }
+}
+
+function readSqlInput(opts) {
+  if (opts.file) return fs.readFileSync(opts.file, "utf8");
+  if (opts.positional.length > 0) return opts.positional.join(" ");
+  if (!process.stdin.isTTY) return fs.readFileSync(0, "utf8");
+  throw new Error("Pass SQL as an argument, via --file <path>, or pipe it to stdin.");
+}
+
+module.exports = { run };

package/src/commands/analyze.test.js

@@ -0,0 +1,180 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const { parseArgs, buildOpts } = require("../cli");
+
+function opts(argv) {
+  return buildOpts(parseArgs(argv));
+}
+
+function loadWithStubs({ responses = [], onRequest = () => {}, errors = [], confirmAnswer = false }) {
+  for (const k of [
+    require.resolve("../api/client"),
+    require.resolve("./_session"),
+    require.resolve("./_connections"),
+    require.resolve("../ui/prompts"),
+    require.resolve("./analyze"),
+  ]) {
+    delete require.cache[k];
+  }
+
+  const apiKey = require.resolve("../api/client");
+  let i = 0;
+  class FakeApiError extends Error {
+    constructor(message, { status, body } = {}) { super(message); this.status = status; this.body = body; }
+  }
+  require.cache[apiKey] = {
+    id: apiKey, filename: apiKey, loaded: true,
+    exports: {
+      ApiError: FakeApiError,
+      async request(_base, path, body) {
+        onRequest(path, body);
+        if (errors[i]) {
+          const e = errors[i];
+          i++;
+          throw new FakeApiError(e.message || "fail", { status: e.status, body: e.body });
+        }
+        const r = responses[i] ?? {};
+        i++;
+        return r;
+      },
+      setClientContext() {},
+      getClientContext() { return null; },
+    },
+  };
+
+  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" },
+  };
+
+  const promptsKey = require.resolve("../ui/prompts");
+  require.cache[promptsKey] = {
+    id: promptsKey, filename: promptsKey, loaded: true,
+    exports: { confirm: async () => confirmAnswer, input: async () => "", password: async () => "", select: async () => "" },
+  };
+
+  return require("./analyze");
+}
+
+function captureStdout() {
+  let out = ""; let err = "";
+  return {
+    stream: { write: (s) => { out += s; } },
+    errStream: { write: (s) => { err += s; } },
+    out: () => out, err: () => err,
+  };
+}
+
+test("analyze hits /explain/analyze with useAnalyze=false by default", async () => {
+  const seen = [];
+  const analyze = loadWithStubs({
+    onRequest: (path, body) => seen.push({ path, body: body && body.json }),
+    responses: [{ planText: "Seq Scan on orders" }],
+  });
+  const io = captureStdout();
+  await analyze.run(opts(["SELECT * FROM orders"]), { stdout: io.stream, stderr: io.errStream });
+  assert.equal(seen.length, 1);
+  assert.match(seen[0].path, /\/explain\/analyze$/);
+  assert.equal(seen[0].body.useAnalyze, false);
+  assert.match(io.out(), /Plan \(EXPLAIN, not executed\)/);
+  assert.match(io.out(), /Seq Scan on orders/);
+});
+
+test("analyze --analyze flips useAnalyze=true on the request", async () => {
+  const seen = [];
+  const analyze = loadWithStubs({
+    onRequest: (path, body) => seen.push(body && body.json),
+    responses: [{ wasExecuted: true, planText: "executed" }],
+  });
+  const io = captureStdout();
+  await analyze.run(opts(["SELECT * FROM orders", "--analyze"]), { stdout: io.stream });
+  assert.equal(seen[0].useAnalyze, true);
+  assert.match(io.out(), /Plan \(executed via EXPLAIN ANALYZE\)/);
+});
+
+test("analyze on a mutation triggers two-step confirmation flow on 4xx requiresConfirmation", async () => {
+  const seen = [];
+  const analyze = loadWithStubs({
+    onRequest: (_path, body) => seen.push(body && body.json),
+    errors: [{
+      status: 200,
+      body: { requiresConfirmation: true, message: "ANALYZE will execute this mutation.", queryType: "DELETE", warnings: ["no WHERE"] },
+      message: "confirmation required",
+    }, null],
+    responses: [null, { wasExecuted: true, planText: "deleted 1" }],
+    confirmAnswer: true,
+  });
+  const io = captureStdout();
+  await analyze.run(opts(["DELETE FROM users WHERE id=1", "--analyze"]), { stdout: io.stream, stderr: io.errStream });
+  assert.equal(seen.length, 2);
+  assert.equal(seen[0].mutationConfirmed, false);
+  assert.equal(seen[1].mutationConfirmed, true);
+  assert.match(io.err(), /ANALYZE will execute/);
+});
+
+test("analyze --write skips the prompt and bakes confirmMutation into the first call", async () => {
+  const seen = [];
+  const analyze = loadWithStubs({
+    onRequest: (_path, body) => seen.push(body && body.json),
+    responses: [{ wasExecuted: true, planText: "ok" }],
+  });
+  const io = captureStdout();
+  await analyze.run(opts(["DELETE FROM users WHERE id=1", "--analyze", "--write"]), { stdout: io.stream });
+  assert.equal(seen.length, 1);
+  assert.equal(seen[0].mutationConfirmed, true);
+});
+
+test("analyze --json emits the raw analysis payload", async () => {
+  const analyze = loadWithStubs({
+    responses: [{ aiSummary: "fast", nodeCount: 3, issues: [], indexRecommendations: [] }],
+  });
+  const io = captureStdout();
+  // SQL first so `--json` doesn't eat it as a value.
+  await analyze.run(opts(["SELECT 1", "--json"]), { stdout: io.stream });
+  const parsed = JSON.parse(io.out());
+  assert.equal(parsed.nodeCount, 3);
+  assert.equal(parsed.aiSummary, "fast");
+});
+
+test("analyze renders AI summary, issues, and index recommendations from the response", async () => {
+  const analyze = loadWithStubs({
+    responses: [{
+      planText: "Seq Scan",
+      aiSummary: "Sequential scan on a large table; consider an index on customer_id.",
+      issues: [{ severity: "HIGH", title: "Sequential scan", message: "10M rows scanned" }],
+      indexRecommendations: [{ tableName: "orders", columns: ["customer_id"], estimatedImpact: 80 }],
+      optimizationSuggestions: ["Add WHERE customer_id = ?"],
+    }],
+  });
+  const io = captureStdout();
+  await analyze.run(opts(["SELECT * FROM orders"]), { stdout: io.stream });
+  const out = io.out();
+  assert.match(out, /Summary:/);
+  assert.match(out, /Sequential scan on a large table/);
+  assert.match(out, /\[HIGH\] Sequential scan/);
+  assert.match(out, /orders\(customer_id\)/);
+  assert.match(out, /impact≈80/);
+  assert.match(out, /Add WHERE customer_id/);
+});
+
+test.after(() => {
+  for (const k of [
+    require.resolve("../api/client"),
+    require.resolve("./_session"),
+    require.resolve("./_connections"),
+    require.resolve("../ui/prompts"),
+    require.resolve("./analyze"),
+  ]) {
+    delete require.cache[k];
+  }
+});

package/src/commands/explain.js

@@ -1,41 +1,25 @@
 "use strict";
 
-const fs = require("node:fs");
-const { request } = require("../api/client");
-const { validateReadOnlySql } = require("../../deepsql-phase1-lib");
-const { resolveSession } = require("./_session");
-const { resolveConnectionId } = require("./_connections");
+/**
+ * `deepsql explain` — deprecated alias for `deepsql analyze`.
+ *
+ * In 0.13.0 we consolidated SQL execution and plan analysis under two
+ * canonical commands: `deepsql query` (executes anything) and
+ * `deepsql analyze` (AI-enriched plan analysis, with optional ANALYZE).
+ * `explain` was a thin read-only-locked subset of analyze, so it lives on
+ * for one cycle as a forwarder while users migrate; it will be removed in
+ * 0.14.0.
+ */
 
-async function run(opts, { stdout = process.stdout } = {}) {
-  const sql = readSqlInput(opts);
-  // EXPLAIN ANALYZE is mutating; require plain EXPLAIN.
-  const validation = validateReadOnlySql(sql, { allowExplain: false });
-  if (!validation.ok) throw new Error(validation.reason);
+const analyze = require("./analyze");
 
-  const session = resolveSession(opts);
-  const connectionId = await resolveConnectionId(session, opts.connection);
-  const response = await request(session.baseUrl, "/mcp/explain-readonly", {
-    method: "POST",
-    token: session.token,
-    json: { connectionId, query: validation.normalizedQuery },
-  });
-
-  if (opts.json) {
-    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
-    return;
-  }
-  if (response?.plan) {
-    stdout.write(typeof response.plan === "string" ? `${response.plan}\n` : `${JSON.stringify(response.plan, null, 2)}\n`);
-    return;
-  }
-  stdout.write(`${JSON.stringify(response, null, 2)}\n`);
-}
-
-function readSqlInput(opts) {
-  if (opts.file) return fs.readFileSync(opts.file, "utf8");
-  if (opts.positional.length > 0) return opts.positional.join(" ");
-  if (!process.stdin.isTTY) return fs.readFileSync(0, "utf8");
-  throw new Error("Pass SQL as an argument, via --file <path>, or pipe it to stdin.");
+async function run(opts, io = {}) {
+  const stderr = io.stderr || process.stderr;
+  stderr.write(
+    "[deepsql] `deepsql explain` is deprecated and will be removed in 0.14.0. "
+    + "Use `deepsql analyze` (same behavior; add `--analyze` for EXPLAIN ANALYZE).\n",
+  );
+  return analyze.run(opts, io);
 }
 
 module.exports = { run };