@deepsql/mcp 0.11.0 → 0.13.4

package/src/api/client.js

@@ -19,6 +19,27 @@ class ApiError extends Error {
   }
 }
 
+/**
+ * Module-level "who is talking to the backend" record. The CLI's entry
+ * point calls setClientContext() once at startup, then every request()
+ * call below stamps X-DeepSQL-Client-{Type,Agent,Version} headers without
+ * each command needing to thread that information through.
+ *
+ *   type    "cli" by default for everything that goes through this module
+ *   agent   "terminal", or the value of --caller-agent / DEEPSQL_CALLER_AGENT
+ *           (set by agents like claude-code when they shell out to `deepsql`)
+ *   version the npm package version, so backend audit shows which CLI build
+ */
+let currentClient = null;
+
+function setClientContext(client) {
+  currentClient = client ? { ...client } : null;
+}
+
+function getClientContext() {
+  return currentClient;
+}
+
 function normalizeBaseUrl(url) {
   if (!url) throw new ApiError("No DeepSQL URL configured. Run `deepsql login --url <url>` first.");
   return url.endsWith("/") ? url : `${url}/`;
@@ -54,6 +75,11 @@ async function request(baseUrl, pathOrUrl, { method = "GET", json, headers, toke
   };
   if (token) requestHeaders.Authorization = `Bearer ${token}`;
   if (json != null) requestHeaders["Content-Type"] = "application/json";
+  if (currentClient) {
+    if (currentClient.type) requestHeaders["X-DeepSQL-Client-Type"] = currentClient.type;
+    if (currentClient.agent) requestHeaders["X-DeepSQL-Client-Agent"] = currentClient.agent;
+    if (currentClient.version) requestHeaders["X-DeepSQL-Client-Version"] = currentClient.version;
+  }
 
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -114,4 +140,12 @@ function parseCookieValue(setCookies, name) {
   return null;
 }
 
-module.exports = { ApiError, request, resolveUrl, normalizeBaseUrl, parseCookieValue };
+module.exports = {
+  ApiError,
+  request,
+  resolveUrl,
+  normalizeBaseUrl,
+  parseCookieValue,
+  setClientContext,
+  getClientContext,
+};

package/src/cli.js

@@ -21,7 +21,8 @@ const COMMANDS = {
   mcp: () => require("./commands/mcp"),
   connections: () => require("./commands/connections"),
   query: () => require("./commands/query"),
-  explain: () => require("./commands/explain"),
+  analyze: () => require("./commands/analyze"),
+  explain: () => require("./commands/explain"), // deprecated alias for `analyze`, removed in 0.14.0
   schema: () => require("./commands/schema"),
   // Brain tools — give a coding agent the same retrieval context the chat
   // pipeline uses, then let the agent generate SQL/answers itself.
@@ -48,10 +49,10 @@ const COMMAND_LIST = [
   ["logout",         false, "Revoke and forget the saved token"],
   ["whoami",         false, "Show the user behind the saved token"],
   ["config",         true,  "Manage saved CLI profiles"],
-  ["mcp",            false, "Run the stdio MCP server using the saved token"],
+  ["mcp",            true,  "Run the MCP server or install it into an editor config"],
   ["connections",    true,  "Manage database connections"],
-  ["query",          false, "Run a read-only SQL statement"],
-  ["explain",        false, "Get an EXPLAIN plan (no ANALYZE)"],
+  ["query",          false, "Execute a SQL statement (admin: DDL/DML with --write)"],
+  ["analyze",        false, "AI-enriched query plan analysis (use --analyze for EXPLAIN ANALYZE)"],
   ["schema",         false, "Dump connection schema or DB objects as JSON"],
   ["digest",         true,  "Show DeepSQL daily digests"],
   ["brain-context",  false, "Retrieve embedding-ranked context for a question"],
@@ -67,12 +68,13 @@ const COMMAND_LIST = [
 ];
 
 const GLOBAL_OPTIONS = [
-  ["--url <url>",         "Override the DeepSQL base URL"],
-  ["--token <tok>",       "Override the auth token (also: DEEPSQL_AUTH_TOKEN)"],
-  ["--connection <name>", "Override the active connection (also: DEEPSQL_CONNECTION)"],
-  ["--no-color",          "Disable ANSI colors"],
-  ["-h, --help",          "Display help for command"],
-  ["-v, --version",       "Show version"],
+  ["--url <url>",          "Override the DeepSQL base URL"],
+  ["--token <tok>",        "Override the auth token (also: DEEPSQL_AUTH_TOKEN)"],
+  ["--connection <name>",  "Override the active connection (also: DEEPSQL_CONNECTION)"],
+  ["--caller-agent <id>",  "Identify the calling agent in audit logs (also: DEEPSQL_CALLER_AGENT)"],
+  ["--no-color",           "Disable ANSI colors"],
+  ["-h, --help",           "Display help for command"],
+  ["-v, --version",        "Show version"],
 ];
 
 // ─── Per-command help blocks ────────────────────────────────────────────────
@@ -112,9 +114,23 @@ const COMMAND_HELP = {
   },
 
   mcp: {
-    description: "Run the stdio MCP server using the saved token.",
-    usage: "deepsql mcp [--url <url>]",
-    notes: "Used by editor MCP configs (Cursor, Claude Desktop) so the config never has to embed a raw token.",
+    description: "Run the stdio MCP server, or install DeepSQL into an editor's MCP config (+ the DBA-consult skill).",
+    usage: "deepsql mcp [--url <url>]\n       deepsql mcp config (--install | --print) --for <editor> [--force] [--no-skill] [--path <p>]",
+    subcommands: [
+      ["(no args)",                                    "Run the stdio MCP server with the saved token"],
+      ["config --install --for <editor>",              "Write a DeepSQL entry into the editor's MCP config AND install the DBA-consult skill (backs up on overwrite)"],
+      ["config --print --for <editor>",                "Print the snippets (config + skill) without touching disk"],
+    ],
+    options: [
+      ["--for <editor>",   "claude-code, claude-desktop, cursor, or codex"],
+      ["--install",        "Write the entry to the editor's default config path AND install the skill"],
+      ["--print",          "Emit the snippets only (no filesystem writes)"],
+      ["--force",          "Overwrite an existing DeepSQL entry/skill"],
+      ["--no-skill",       "Skip the DBA-consult skill install (MCP server config only)"],
+      ["--path <p>",       "Override the default MCP config path (advanced; doesn't affect the skill path)"],
+      ["--url <url>",      "Profile to bind the spawned MCP server to"],
+    ],
+    notes: "The installed entry runs `deepsql mcp`, which uses the saved profile — no token is embedded in the editor config. The skill teaches the agent to consult DeepSQL BEFORE generating DDL or non-trivial SQL.",
   },
 
   config: {
@@ -158,25 +174,30 @@ const COMMAND_HELP = {
   },
 
   query: {
-    description: "Run a read-only SQL statement (parser-enforced, ACL-checked).",
+    description: "Execute a SQL statement against a connection. Same policy gate as the web SQL Editor: developers can run SELECT/WITH/SHOW/EXPLAIN; admins can additionally run DML/DDL with a two-step confirm.",
     usage: 'deepsql query "<sql>" --connection <name> [options]',
     options: [
       ["--connection <name>",    "Connection to run against"],
       ["--limit <n>",            "Row limit (1–1000, default 100)"],
       ["--timeout-seconds <n>",  "Statement timeout in seconds (1–60)"],
       ["--file <path>",          "Read SQL from a file instead of argv"],
+      ["--write",                "Confirm a mutation upfront (skips interactive prompt; scripts/CI)"],
       ["--json",                 "Raw JSON output"],
     ],
+    notes: "EXPLAIN and EXPLAIN ANALYZE are valid SQL — type them directly. For the AI-enriched plan analysis, use `deepsql analyze`.",
   },
 
-  explain: {
-    description: "Get an EXPLAIN plan (no ANALYZE — read-only enforced).",
-    usage: 'deepsql explain "<sql>" --connection <name> [options]',
+  analyze: {
+    description: "AI-enriched query plan analysis. Returns the parsed plan tree, performance issues, index recommendations, and a written summary that takes the connection's schema and business rules into account.",
+    usage: 'deepsql analyze "<sql>" --connection <name> [options]',
     options: [
-      ["--connection <name>", "Connection to run against"],
-      ["--file <path>",       "Read SQL from a file instead of argv"],
-      ["--json",              "Raw JSON output"],
+      ["--connection <name>",    "Connection to run against"],
+      ["--analyze",              "Use EXPLAIN ANALYZE (actually executes the query)"],
+      ["--write",                "Confirm an ANALYZE-of-mutation upfront (skips interactive prompt)"],
+      ["--file <path>",          "Read SQL from a file instead of argv"],
+      ["--json",                 "Raw JSON output"],
     ],
+    notes: "Pass the underlying SQL, not `EXPLAIN <sql>` — the server wraps it. With --analyze on a mutation, the same admin role + WHERE + confirmation gates as `query` apply.",
   },
 
   schema: {
@@ -525,6 +546,17 @@ function buildOpts(parsed) {
     // Indexes
     all: !!f.all,
     status: f.status || null,
+    // mcp config installer
+    install: !!f.install,
+    print: !!f.print,
+    for: f.for || null,
+    path: f.path || null,
+    noSkill: !!f.noSkill,
+    // SQL execution
+    write: !!f.write,
+    analyze: !!f.analyze,
+    // Origin tagging for audit
+    callerAgent: f.callerAgent || null,
     // Setup wizard
     force: !!f.force,
     skipEmail: !!f.skipEmail,
@@ -582,6 +614,19 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
   const parsed = parseArgs(restArgs);
   const opts = buildOpts(parsed);
 
+  // Stamp origin headers on every backend request the command will make.
+  // `clientType` is fixed for CLI traffic; `clientAgent` defaults to
+  // "terminal" but agents that shell out can override via --caller-agent or
+  // the DEEPSQL_CALLER_AGENT env var, so audit rows distinguish "human in a
+  // terminal" from "Claude Code invoked deepsql query."
+  const { setClientContext } = require("./api/client");
+  const pkg = require("../package.json");
+  setClientContext({
+    type: "cli",
+    agent: opts.callerAgent || process.env.DEEPSQL_CALLER_AGENT || "terminal",
+    version: pkg.version,
+  });
+
   try {
     const mod = loader();
     await mod.run(opts, { stdout, stderr });

package/src/cli.test.js

@@ -73,7 +73,7 @@ test("every command in the catalog has a COMMAND_HELP entry", () => {
   const { main: _main } = require("./cli");
   void _main;
   const expected = [
-    "login","logout","whoami","config","mcp","connections","query","explain","schema",
+    "login","logout","whoami","config","mcp","connections","query","analyze","schema",
     "digest","brain-context","business-rules","relationships","anti-patterns","indexes",
     "users","access","permissions","slow-queries","setup",
   ];

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