@deepsql/mcp 0.11.0 → 0.13.0

package/src/commands/mcp.test.js

@@ -0,0 +1,384 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const {
+  mergeJson,
+  mergeToml,
+  renderSnippet,
+  mergeConfig,
+  installSkill,
+  upsertGuardedSection,
+  renderSkill,
+  loadSkillBody,
+  EDITORS,
+} = require("./mcp");
+
+function withTempDir(fn) {
+  return async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "deepsql-mcp-skill-test-"));
+    try {
+      await fn(dir);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  };
+}
+
+// ─── snippet rendering ──────────────────────────────────────────────────────
+
+test("renderSnippet emits valid JSON for the JSON editors", () => {
+  const text = renderSnippet("json", "mcpServers");
+  const parsed = JSON.parse(text);
+  assert.deepEqual(parsed, {
+    mcpServers: { deepsql: { command: "deepsql", args: ["mcp"] } },
+  });
+});
+
+test("renderSnippet emits a parseable [mcp_servers.deepsql] section for codex", () => {
+  const text = renderSnippet("toml", "mcp_servers");
+  assert.match(text, /^\[mcp_servers\.deepsql\]/m);
+  assert.match(text, /command = "deepsql"/);
+  assert.match(text, /args = \["mcp"\]/);
+});
+
+// ─── JSON merge ─────────────────────────────────────────────────────────────
+
+test("mergeJson creates the file when nothing exists", () => {
+  const r = mergeJson(null, "mcpServers", false);
+  const parsed = JSON.parse(r.text);
+  assert.equal(parsed.mcpServers.deepsql.command, "deepsql");
+});
+
+test("mergeJson preserves siblings under mcpServers", () => {
+  const original = JSON.stringify({
+    mcpServers: {
+      "other-tool": { command: "node", args: ["server.js"] },
+    },
+  });
+  const r = mergeJson(original, "mcpServers", false);
+  const parsed = JSON.parse(r.text);
+  assert.equal(parsed.mcpServers["other-tool"].command, "node");
+  assert.equal(parsed.mcpServers.deepsql.command, "deepsql");
+});
+
+test("mergeJson preserves top-level siblings (e.g. permissions, env)", () => {
+  const original = JSON.stringify({ env: { FOO: "bar" }, permissions: ["x"] });
+  const r = mergeJson(original, "mcpServers", false);
+  const parsed = JSON.parse(r.text);
+  assert.deepEqual(parsed.env, { FOO: "bar" });
+  assert.deepEqual(parsed.permissions, ["x"]);
+  assert.ok(parsed.mcpServers.deepsql);
+});
+
+test("mergeJson skips when an existing deepsql entry exists and --force is off", () => {
+  const original = JSON.stringify({
+    mcpServers: { deepsql: { command: "stale", args: [] } },
+  });
+  const r = mergeJson(original, "mcpServers", false);
+  assert.equal(r.skipped, true);
+});
+
+test("mergeJson overwrites with --force", () => {
+  const original = JSON.stringify({
+    mcpServers: { deepsql: { command: "stale", args: [] } },
+  });
+  const r = mergeJson(original, "mcpServers", true);
+  const parsed = JSON.parse(r.text);
+  assert.equal(parsed.mcpServers.deepsql.command, "deepsql");
+});
+
+test("mergeJson refuses to silently overwrite malformed JSON", () => {
+  assert.throws(() => mergeJson("{this is not json", "mcpServers", false), /malformed JSON|config/);
+});
+
+test("mergeJson rejects a top-level array", () => {
+  assert.throws(() => mergeJson("[1,2,3]", "mcpServers", false), /must be a JSON object/);
+});
+
+// ─── TOML merge ─────────────────────────────────────────────────────────────
+
+test("mergeToml appends when no section exists", () => {
+  const r = mergeToml("", "mcp_servers", false);
+  assert.match(r.text, /^\[mcp_servers\.deepsql\]/m);
+});
+
+test("mergeToml preserves unrelated sections above and below", () => {
+  const original = [
+    "[runtime]",
+    "verbose = true",
+    "",
+    "[mcp_servers.other]",
+    'command = "elsewhere"',
+    "",
+  ].join("\n");
+  const r = mergeToml(original, "mcp_servers", false);
+  assert.match(r.text, /\[runtime\]/);
+  assert.match(r.text, /verbose = true/);
+  assert.match(r.text, /\[mcp_servers\.other\]/);
+  assert.match(r.text, /\[mcp_servers\.deepsql\]/);
+});
+
+test("mergeToml skips an existing deepsql section without --force", () => {
+  const original = '[mcp_servers.deepsql]\ncommand = "stale"\nargs = []\n';
+  const r = mergeToml(original, "mcp_servers", false);
+  assert.equal(r.skipped, true);
+});
+
+test("mergeToml replaces an existing deepsql section with --force, leaving neighbors alone", () => {
+  const original = [
+    "[mcp_servers.deepsql]",
+    'command = "stale"',
+    "args = []",
+    "",
+    "[mcp_servers.other]",
+    'command = "elsewhere"',
+    "",
+  ].join("\n");
+  const r = mergeToml(original, "mcp_servers", true);
+  assert.match(r.text, /command = "deepsql"/);
+  assert.equal(/command = "stale"/.test(r.text), false);
+  assert.match(r.text, /\[mcp_servers\.other\]/, "neighbor section must survive");
+  assert.match(r.text, /command = "elsewhere"/);
+});
+
+// ─── filesystem integration ────────────────────────────────────────────────
+
+test("mergeConfig writes the JSON file (no original, no backup)", withTempDir((dir) => {
+  const configPath = path.join(dir, "mcp.json");
+  const result = mergeConfig({
+    format: "json", key: "mcpServers", configPath, force: false,
+  });
+  assert.equal(result.written, true);
+  assert.equal(result.backupPath, null);
+  const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  assert.equal(parsed.mcpServers.deepsql.command, "deepsql");
+}));
+
+test("mergeConfig backs up the existing file when it actually changes", withTempDir((dir) => {
+  const configPath = path.join(dir, "mcp.json");
+  fs.writeFileSync(configPath, JSON.stringify({ mcpServers: { other: { command: "x" } } }));
+  const result = mergeConfig({
+    format: "json", key: "mcpServers", configPath, force: false,
+  });
+  assert.equal(result.written, true);
+  assert.ok(result.backupPath, "backup path must be set when content changed");
+  assert.ok(fs.existsSync(result.backupPath));
+  const restored = JSON.parse(fs.readFileSync(result.backupPath, "utf8"));
+  assert.equal(restored.mcpServers.other.command, "x", "backup must contain pre-merge content");
+}));
+
+test("mergeConfig returns skipped=true when deepsql already there and --force off", withTempDir((dir) => {
+  const configPath = path.join(dir, "mcp.json");
+  fs.writeFileSync(configPath, JSON.stringify({
+    mcpServers: { deepsql: { command: "deepsql", args: ["mcp"] } },
+  }));
+  const result = mergeConfig({
+    format: "json", key: "mcpServers", configPath, force: false,
+  });
+  assert.equal(result.skipped, true);
+}));
+
+test("mergeConfig writes TOML to ~/.codex/config.toml layout", withTempDir((dir) => {
+  const configPath = path.join(dir, "config.toml");
+  fs.writeFileSync(configPath, "[runtime]\nverbose = true\n");
+  const result = mergeConfig({
+    format: "toml", key: "mcp_servers", configPath, force: false,
+  });
+  assert.equal(result.written, true);
+  const text = fs.readFileSync(configPath, "utf8");
+  assert.match(text, /\[runtime\]/);
+  assert.match(text, /\[mcp_servers\.deepsql\]/);
+}));
+
+test("mergeConfig creates parent directories that don't exist yet", withTempDir((dir) => {
+  const configPath = path.join(dir, "deep", "nested", "mcp.json");
+  const result = mergeConfig({
+    format: "json", key: "mcpServers", configPath, force: false,
+  });
+  assert.equal(result.written, true);
+  assert.ok(fs.existsSync(configPath));
+}));
+
+// ─── editor catalog ────────────────────────────────────────────────────────
+
+test("EDITORS catalog exposes the four supported targets with sensible defaults", () => {
+  for (const editor of ["claude-code", "claude-desktop", "cursor", "codex"]) {
+    const e = EDITORS[editor];
+    assert.ok(e, `missing editor: ${editor}`);
+    assert.match(e.format, /^(json|toml)$/);
+    assert.ok(typeof e.path === "function");
+    const p = e.path();
+    assert.ok(p && typeof p === "string" && p.length > 0);
+  }
+  assert.equal(EDITORS.codex.format, "toml");
+  for (const editor of ["claude-code", "claude-desktop", "cursor"]) {
+    assert.equal(EDITORS[editor].format, "json");
+  }
+});
+
+// ─── skill body + per-editor metadata ──────────────────────────────────────
+
+test("loadSkillBody returns the bundled SKILL_BODY.md content", () => {
+  const body = loadSkillBody();
+  assert.ok(body.length > 500, "skill body should not be empty");
+  assert.match(body, /DBA consult/i, "body should mention the DBA consult framing");
+  assert.match(body, /get_brain_context/, "body should reference the brain-context tool call");
+  assert.match(body, /confirmMutation/, "body should reference the mutation confirm flow");
+});
+
+test("each supported editor either has a skill descriptor or explicitly opts out", () => {
+  for (const [name, editor] of Object.entries(EDITORS)) {
+    if (editor.skill === null) {
+      // Explicit opt-out (claude-desktop today).
+      assert.equal(name, "claude-desktop", `unexpected null skill on ${name}`);
+      continue;
+    }
+    assert.ok(editor.skill, `${name} needs a skill descriptor or explicit null`);
+    assert.match(editor.skill.kind, /^(file|agents-append)$/);
+    assert.ok(typeof editor.skill.path === "function");
+    assert.ok(typeof editor.skill.frontmatter === "function");
+  }
+});
+
+test("renderSkill prepends Claude-Code-style YAML frontmatter naming the skill", () => {
+  const text = renderSkill(EDITORS["claude-code"].skill);
+  assert.match(text, /^---\nname: deepsql\n/);
+  assert.match(text, /description:.*DBA consult/i);
+  assert.match(text, /\n---\n\n#/, "frontmatter must be terminated before the body");
+});
+
+test("renderSkill prepends Cursor-style frontmatter with globs and alwaysApply=false", () => {
+  const text = renderSkill(EDITORS["cursor"].skill);
+  assert.match(text, /^---\n/);
+  assert.match(text, /alwaysApply: false/);
+  assert.match(text, /globs:/);
+  assert.match(text, /migrations/);
+  assert.match(text, /\.prisma/);
+});
+
+test("renderSkill for codex emits the bare body (the AGENTS.md wrapper adds guards)", () => {
+  const text = renderSkill(EDITORS["codex"].skill);
+  // No frontmatter for codex — AGENTS.md is plain markdown, the
+  // upsertGuardedSection wrapper adds the BEGIN/END markers.
+  assert.equal(/^---/.test(text), false);
+  assert.match(text, /^# DeepSQL/);
+});
+
+// ─── installSkill (standalone-file flavor: claude-code, cursor) ────────────
+
+test("installSkill writes Claude Code SKILL.md at the configured path", withTempDir(async (dir) => {
+  const skillPath = path.join(dir, "claude", "skills", "deepsql", "SKILL.md");
+  const skill = {
+    kind: "file",
+    path: () => skillPath,
+    frontmatter: EDITORS["claude-code"].skill.frontmatter,
+  };
+  const r = installSkill({ skill, force: false });
+  assert.equal(r.written, true);
+  assert.equal(r.backupPath, null, "no backup when file didn't exist before");
+  const written = fs.readFileSync(skillPath, "utf8");
+  assert.match(written, /^---\nname: deepsql\n/);
+  assert.match(written, /DBA consult/);
+}));
+
+test("installSkill is idempotent — second call without --force is a no-op", withTempDir(async (dir) => {
+  const skillPath = path.join(dir, "SKILL.md");
+  const skill = {
+    kind: "file",
+    path: () => skillPath,
+    frontmatter: EDITORS["claude-code"].skill.frontmatter,
+  };
+  const r1 = installSkill({ skill, force: false });
+  assert.equal(r1.written, true);
+  const r2 = installSkill({ skill, force: false });
+  assert.equal(r2.skipped, true, "should not rewrite identical content");
+}));
+
+test("installSkill backs up a divergent skill file before overwriting with --force", withTempDir(async (dir) => {
+  const skillPath = path.join(dir, "SKILL.md");
+  fs.writeFileSync(skillPath, "stale content the user wrote by hand\n");
+  const skill = {
+    kind: "file",
+    path: () => skillPath,
+    frontmatter: EDITORS["claude-code"].skill.frontmatter,
+  };
+  const r = installSkill({ skill, force: true });
+  assert.equal(r.written, true);
+  assert.ok(r.backupPath, "must back up the file when content differs");
+  const backup = fs.readFileSync(r.backupPath, "utf8");
+  assert.match(backup, /stale content/);
+}));
+
+test("installSkill writes Cursor .mdc with globs", withTempDir(async (dir) => {
+  const rulePath = path.join(dir, "rules", "deepsql.mdc");
+  const skill = {
+    kind: "file",
+    path: () => rulePath,
+    frontmatter: EDITORS["cursor"].skill.frontmatter,
+  };
+  installSkill({ skill, force: false });
+  const written = fs.readFileSync(rulePath, "utf8");
+  assert.match(written, /alwaysApply: false/);
+  assert.match(written, /migrations/);
+}));
+
+// ─── upsertGuardedSection (codex AGENTS.md flavor) ─────────────────────────
+
+test("upsertGuardedSection appends a guarded section to a new AGENTS.md", withTempDir(async (dir) => {
+  const file = path.join(dir, "AGENTS.md");
+  const r = upsertGuardedSection({ filePath: file, content: "hello world", force: false });
+  assert.equal(r.written, true);
+  const text = fs.readFileSync(file, "utf8");
+  assert.match(text, /<!-- BEGIN DEEPSQL DBA CONSULT SKILL -->/);
+  assert.match(text, /<!-- END DEEPSQL DBA CONSULT SKILL -->/);
+  assert.match(text, /hello world/);
+}));
+
+test("upsertGuardedSection preserves the user's existing AGENTS.md content", withTempDir(async (dir) => {
+  const file = path.join(dir, "AGENTS.md");
+  fs.writeFileSync(file, "# My agent instructions\n\nDon't bug me on weekends.\n");
+  upsertGuardedSection({ filePath: file, content: "deepsql skill content", force: false });
+  const text = fs.readFileSync(file, "utf8");
+  assert.match(text, /# My agent instructions/, "user's pre-existing content must be preserved");
+  assert.match(text, /Don't bug me on weekends/);
+  assert.match(text, /deepsql skill content/);
+}));
+
+test("upsertGuardedSection replaces only the guarded section on re-install", withTempDir(async (dir) => {
+  const file = path.join(dir, "AGENTS.md");
+  fs.writeFileSync(file, "# Top of file\n\nUser stuff.\n");
+  upsertGuardedSection({ filePath: file, content: "v1 content", force: false });
+  upsertGuardedSection({ filePath: file, content: "v2 content", force: true });
+  const text = fs.readFileSync(file, "utf8");
+  assert.equal(/v1 content/.test(text), false, "old guarded content must be replaced");
+  assert.match(text, /v2 content/);
+  assert.match(text, /# Top of file/, "user content above the guarded section stays");
+  assert.match(text, /User stuff\./);
+}));
+
+test("upsertGuardedSection re-installs the same content as a no-op (skipped)", withTempDir(async (dir) => {
+  const file = path.join(dir, "AGENTS.md");
+  upsertGuardedSection({ filePath: file, content: "stable content", force: false });
+  const r = upsertGuardedSection({ filePath: file, content: "stable content", force: false });
+  assert.equal(r.skipped, true);
+}));
+
+test("upsertGuardedSection refuses to write if a BEGIN marker exists without a matching END", withTempDir(async (dir) => {
+  const file = path.join(dir, "AGENTS.md");
+  fs.writeFileSync(file, "# Header\n\n<!-- BEGIN DEEPSQL DBA CONSULT SKILL -->\nhalf-edited\n");
+  assert.throws(
+    () => upsertGuardedSection({ filePath: file, content: "anything", force: false }),
+    /half-edited state/,
+  );
+}));
+
+// ─── per-editor skill_off opt-out via skill === null ───────────────────────
+
+test("claude-desktop intentionally has no skill descriptor (no skills surface)", () => {
+  assert.equal(EDITORS["claude-desktop"].skill, null);
+});

package/src/commands/query.js

@@ -1,36 +1,118 @@
 "use strict";
 
+/**
+ * `deepsql query` — execute a SQL statement against a connection.
+ *
+ * In 0.13.0 this stopped being a read-only-only command. It now hits the same
+ * canonical Editor endpoint (`/api/connections/{id}/query`) that the web UI
+ * uses, so policy decisions are uniform across all DeepSQL surfaces:
+ *
+ *   - Developer + SELECT/WITH/SHOW/EXPLAIN → runs immediately
+ *   - Developer + DML/DDL                  → backend returns 403 with a
+ *                                            clear EDITOR_MUTATION_FORBIDDEN
+ *   - Admin + DML/DDL (no --write)         → server returns
+ *                                            requiresConfirmation; we print
+ *                                            the warnings, prompt y/N, and
+ *                                            re-send with confirmMutation=true
+ *   - Admin + DML/DDL + --write            → confirmation flag is set
+ *                                            upfront, no prompt; useful in
+ *                                            scripts / CI
+ *
+ * `EXPLAIN` and `EXPLAIN ANALYZE` are just SQL — no special flag needed.
+ * For the AI-enriched plan analysis, use `deepsql analyze "<sql>"`.
+ *
+ * The old phase-1 read-only parser has been removed; the backend is the
+ * single source of truth on policy now. This also closes the
+ * "client says no but server would have said yes" mismatches we kept
+ * hitting in CI.
+ */
+
 const fs = require("node:fs");
 const { request } = require("../api/client");
-const { validateReadOnlySql } = require("../../deepsql-phase1-lib");
 const { resolveSession } = require("./_session");
 const { resolveConnectionId } = require("./_connections");
+const ui = require("../ui/prompts");
 
-async function run(opts, { stdout = process.stdout } = {}) {
+async function run(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
   const sql = readSqlInput(opts);
-  const validation = validateReadOnlySql(sql, { allowExplain: true });
-  if (!validation.ok) throw new Error(validation.reason);
 
   const session = resolveSession(opts);
   const connectionId = await resolveConnectionId(session, opts.connection);
   const limit = clampInt(opts.limit, 1, 1000, 100);
-  const timeout = opts.timeoutSeconds == null ? null : clampInt(opts.timeoutSeconds, 1, 60, null);
+  const timeoutSeconds = opts.timeoutSeconds == null ? null : clampInt(opts.timeoutSeconds, 1, 60, null);
+
+  const response = await runOnce(session, connectionId, {
+    query: sql,
+    limit,
+    timeoutSeconds,
+    mutationConfirmed: !!opts.write,
+  });
 
-  const response = await request(session.baseUrl, "/mcp/query-readonly", {
-    method: "POST",
-    token: session.token,
-    json: {
-      connectionId,
-      query: validation.normalizedQuery,
+  // Two-step mutation flow: server returns 200 with requiresConfirmation=true
+  // when the statement is a mutation and confirmMutation wasn't set. We show
+  // the warning list, ask the human, then resubmit.
+  if (response && response.success === false && response.requiresConfirmation) {
+    if (opts.write) {
+      // --write was passed but server still wants confirmation. That means
+      // the request lost the flag somewhere — surface it.
+      throw new Error(
+        `Server still asked for confirmation despite --write. Message: ${response.message}`,
+      );
+    }
+    const accepted = await promptForConfirmation(response, { stderr });
+    if (!accepted) {
+      stderr.write("Aborted.\n");
+      return;
+    }
+    const confirmed = await runOnce(session, connectionId, {
+      query: sql,
       limit,
-      timeoutSeconds: timeout,
+      timeoutSeconds,
+      mutationConfirmed: true,
+    });
+    printOutcome(confirmed, opts, { stdout, stderr });
+    return;
+  }
+
+  printOutcome(response, opts, { stdout, stderr });
+}
+
+async function runOnce(session, connectionId, body) {
+  return request(
+    session.baseUrl,
+    `/connections/${encodeURIComponent(connectionId)}/query`,
+    {
+      method: "POST",
+      token: session.token,
+      json: body,
     },
-  });
+  );
+}
+
+async function promptForConfirmation(response, { stderr = process.stderr }) {
+  stderr.write(`\n⚠ ${response.message || "This statement will modify the database."}\n`);
+  if (response.queryType) stderr.write(`  statement: ${response.queryType}\n`);
+  const warnings = Array.isArray(response.warnings) ? response.warnings : [];
+  for (const w of warnings) {
+    stderr.write(`  • ${w}\n`);
+  }
+  stderr.write("\n");
+  return ui.confirm({ message: "Execute the statement?", default: false });
+}
 
+function printOutcome(response, opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
   if (opts.json) {
     stdout.write(`${JSON.stringify(response, null, 2)}\n`);
     return;
   }
+  if (response && response.success === false) {
+    // Block or failure that didn't go via the throw path. Print message
+    // + error code so a script can grep.
+    const code = response.errorCode ? ` [${response.errorCode}]` : "";
+    stderr.write(`${response.message || "Query failed."}${code}\n`);
+    process.exitCode = 1;
+    return;
+  }
   printRows(stdout, response);
 }