@deepsql/mcp 0.5.0 → 0.8.0

package/src/commands/access.js

@@ -0,0 +1,225 @@
+"use strict";
+
+/**
+ * `deepsql access` — per-connection access grants and chat-policy editing.
+ *
+ *   deepsql access list --user <ref>            → connections this user can see
+ *   deepsql access list --connection <name>     → users who can see this connection
+ *   deepsql access grant --user <ref> --connection <name> --level read|write|admin
+ *   deepsql access revoke --user <ref> --connection <name>
+ *   deepsql access policy <user> <connection>   → opens $EDITOR with the
+ *     plain-English chat policy; on save, validates via the preview endpoint
+ *     and PUTs the result.
+ */
+
+const { ApiError, request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveUser } = require("./_users");
+const { resolveConnectionId, listConnections } = require("./_connections");
+const { editText } = require("../ui/editor");
+
+const SUBCOMMANDS = {
+  list: cmdList,
+  grant: cmdGrant,
+  revoke: cmdRevoke,
+  policy: cmdPolicy,
+};
+
+async function run(opts, io = {}) {
+  const sub = opts.positional[0];
+  if (!sub) throw new Error("Usage: deepsql access <list|grant|revoke|policy> ...");
+  const handler = SUBCOMMANDS[sub];
+  if (!handler) throw new Error(`Unknown access subcommand: ${sub}.`);
+  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 — managing access requires ADMIN role.");
+      }
+      throw err;
+    }
+  };
+}
+
+// ─── list ──────────────────────────────────────────────────────────────────
+
+async function cmdList(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  if (opts.user) {
+    const user = await resolveUser(session, opts.user);
+    const grants = await request(session.baseUrl, `/admin/users/${user.id}/connection-access`, {
+      token: session.token,
+    });
+    if (opts.json) {
+      stdout.write(`${JSON.stringify(grants, null, 2)}\n`);
+      return;
+    }
+    if (!Array.isArray(grants) || grants.length === 0) {
+      stdout.write(`${user.email || user.username} has no connection grants.\n`);
+      return;
+    }
+    printGrants(stdout, grants, "user");
+    return;
+  }
+  if (opts.connection) {
+    const connectionId = await resolveConnectionId(session, opts.connection);
+    const grants = await request(
+      session.baseUrl,
+      `/admin/connections/${encodeURIComponent(connectionId)}/connection-access`,
+      { token: session.token },
+    );
+    if (opts.json) {
+      stdout.write(`${JSON.stringify(grants, null, 2)}\n`);
+      return;
+    }
+    if (!Array.isArray(grants) || grants.length === 0) {
+      stdout.write(`No grants on ${opts.connection}.\n`);
+      return;
+    }
+    printGrants(stdout, grants, "connection");
+    return;
+  }
+  throw new Error("Pass --user <ref> or --connection <name>.");
+}
+
+// ─── grant ─────────────────────────────────────────────────────────────────
+
+async function cmdGrant(opts, { stdout = process.stdout } = {}) {
+  if (!opts.user) throw new Error("--user <ref> is required.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
+  const level = (opts.level || "READ").toUpperCase();
+  if (!["READ", "WRITE", "ADMIN"].includes(level)) {
+    throw new Error(`Invalid --level "${level}". Pick read, write, or admin.`);
+  }
+
+  const session = resolveSession(opts);
+  const user = await resolveUser(session, opts.user);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  await request(
+    session.baseUrl,
+    `/admin/users/${user.id}/connection-access/${encodeURIComponent(connectionId)}`,
+    {
+      method: "PUT",
+      token: session.token,
+      json: { accessLevel: level },
+    },
+  );
+  stdout.write(
+    `Granted ${level} on ${opts.connection} to ${user.email || user.username}.\n`,
+  );
+}
+
+// ─── revoke ────────────────────────────────────────────────────────────────
+
+async function cmdRevoke(opts, { stdout = process.stdout } = {}) {
+  if (!opts.user) throw new Error("--user <ref> is required.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
+
+  const session = resolveSession(opts);
+  const user = await resolveUser(session, opts.user);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  await request(
+    session.baseUrl,
+    `/admin/users/${user.id}/connection-access/${encodeURIComponent(connectionId)}`,
+    { method: "DELETE", token: session.token },
+  );
+  stdout.write(`Revoked ${opts.connection} for ${user.email || user.username}.\n`);
+}
+
+// ─── policy ────────────────────────────────────────────────────────────────
+
+const POLICY_HEADER =
+  "# Plain-English chat access policy. Lines starting with # are kept as-is —\n" +
+  "# DeepSQL doesn't strip them. Save and quit to commit; quit without changes\n" +
+  "# (e.g. :cq in vi) to abort.";
+
+async function cmdPolicy(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const userRef = opts.positional[0];
+  const connRef = opts.positional[1];
+  if (!userRef || !connRef) {
+    throw new Error("Usage: deepsql access policy <user> <connection>");
+  }
+
+  const session = resolveSession(opts);
+  const user = await resolveUser(session, userRef);
+  const connectionId = await resolveConnectionId(session, connRef);
+
+  const existing = await request(
+    session.baseUrl,
+    `/admin/users/${user.id}/connection-access/${encodeURIComponent(connectionId)}/chat-policy`,
+    { token: session.token },
+  );
+
+  const initial = (existing && existing.plainEnglishPolicy) || "";
+
+  stderr.write(
+    `Editing policy for ${user.email || user.username} on ${connRef}…\n`,
+  );
+  const { content, changed } = await editText(initial, {
+    suffix: ".policy.md",
+    header: POLICY_HEADER,
+  });
+
+  if (!changed) {
+    stderr.write("No changes.\n");
+    return;
+  }
+
+  // Validate via preview before committing.
+  const preview = await request(session.baseUrl, "/admin/connection-chat-policies/preview", {
+    method: "POST",
+    token: session.token,
+    json: { connectionId, plainEnglishPolicy: content },
+  });
+  if (preview && preview.error) {
+    throw new Error(`Policy preview rejected: ${preview.error}`);
+  }
+
+  const saved = await request(
+    session.baseUrl,
+    `/admin/users/${user.id}/connection-access/${encodeURIComponent(connectionId)}/chat-policy`,
+    {
+      method: "PUT",
+      token: session.token,
+      json: { plainEnglishPolicy: content, active: true },
+    },
+  );
+  stdout.write(`Saved policy for ${user.email || user.username} on ${connRef}.\n`);
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(saved, null, 2)}\n`);
+  }
+}
+
+// ─── helpers ───────────────────────────────────────────────────────────────
+
+function printGrants(stdout, grants, mode) {
+  const rows = grants.map((g) => ({
+    a: mode === "user" ? (g.connectionName || g.connectionId || "") : (g.email || g.username || ""),
+    level: (g.accessLevel || g.level || "").toUpperCase(),
+    grantedBy: g.grantedBy || "",
+  }));
+  const headerA = mode === "user" ? "CONNECTION" : "USER";
+  const widthA = Math.max(headerA.length, ...rows.map((r) => r.a.length));
+  const widthLevel = Math.max("LEVEL".length, ...rows.map((r) => r.level.length));
+  const widthGrantedBy = Math.max("GRANTED BY".length, ...rows.map((r) => r.grantedBy.length));
+  stdout.write(
+    `${headerA.padEnd(widthA)}  ${"LEVEL".padEnd(widthLevel)}  ${"GRANTED BY".padEnd(widthGrantedBy)}\n` +
+      `${"-".repeat(widthA)}  ${"-".repeat(widthLevel)}  ${"-".repeat(widthGrantedBy)}\n`,
+  );
+  for (const r of rows) {
+    stdout.write(`${r.a.padEnd(widthA)}  ${r.level.padEnd(widthLevel)}  ${r.grantedBy.padEnd(widthGrantedBy)}\n`);
+  }
+}
+
+// listConnections used in __mocks elsewhere; expose for tests if needed
+module.exports = { run, _internal: { listConnections } };

package/src/commands/admin.test.js

@@ -0,0 +1,135 @@
+"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));
+}
+
+// users -----------------------------------------------------------------------
+
+test("users add positional email + role/name flags", () => {
+  const o = opts(["add", "x@y.com", "--role", "DEVELOPER", "--name", "X"]);
+  assert.deepEqual(o.positional, ["add", "x@y.com"]);
+  assert.equal(o.role, "DEVELOPER");
+  assert.equal(o.name, "X");
+});
+
+test("users delete --yes flag", () => {
+  const o = opts(["delete", "alice@x.com", "--yes"]);
+  assert.equal(o.yes, true);
+  assert.deepEqual(o.positional, ["delete", "alice@x.com"]);
+});
+
+test("users reset-password --password-stdin flag", () => {
+  const o = opts(["reset-password", "alice@x.com", "--password-stdin"]);
+  assert.equal(o.passwordStdin, true);
+  assert.equal(o.password, null); // stays null since it's a separate flag
+});
+
+// access ----------------------------------------------------------------------
+
+test("access grant requires user/connection/level", () => {
+  const o = opts([
+    "grant",
+    "--user",
+    "alice@x.com",
+    "--connection",
+    "mylocalpg",
+    "--level",
+    "read",
+  ]);
+  assert.equal(o.user, "alice@x.com");
+  assert.equal(o.connection, "mylocalpg");
+  assert.equal(o.level, "read");
+});
+
+test("access policy passes positional user + connection", () => {
+  const o = opts(["policy", "alice@x.com", "mylocalpg"]);
+  assert.deepEqual(o.positional, ["policy", "alice@x.com", "mylocalpg"]);
+});
+
+// permissions -----------------------------------------------------------------
+
+test("permissions override --grant + --reason", () => {
+  const o = opts([
+    "override",
+    "--role",
+    "DEVELOPER",
+    "--permission",
+    "USE_CHAT",
+    "--grant",
+    "--reason",
+    "Beta access",
+  ]);
+  assert.equal(o.role, "DEVELOPER");
+  assert.equal(o.permission, "USE_CHAT");
+  assert.equal(o.grant, true);
+  assert.equal(o.revoke, false);
+  assert.equal(o.reason, "Beta access");
+});
+
+test("permissions override --revoke flips to revoke", () => {
+  const o = opts(["override", "--role", "DEVELOPER", "--permission", "USE_CHAT", "--revoke"]);
+  assert.equal(o.grant, false);
+  assert.equal(o.revoke, true);
+});
+
+// slow-queries ----------------------------------------------------------------
+
+test("slow-queries history N positional", () => {
+  const o = opts(["history", "--connection", "mylocalpg", "5"]);
+  assert.deepEqual(o.positional, ["history", "5"]);
+  assert.equal(o.connection, "mylocalpg");
+});
+
+test("slow-queries analyze flags", () => {
+  const o = opts([
+    "analyze",
+    "--connection",
+    "mylocalpg",
+    "--time-range",
+    "LAST_HOUR",
+    "--threshold-ms",
+    "200",
+    "--limit",
+    "20",
+  ]);
+  assert.equal(o.timeRange, "LAST_HOUR");
+  assert.equal(o.thresholdMs, "200");
+  assert.equal(o.limit, "20");
+});
+
+test("slow-queries optimize uses --query-id", () => {
+  const o = opts(["optimize", "--connection", "mylocalpg", "--query-id", "q-123"]);
+  assert.equal(o.queryId, "q-123");
+});
+
+test("slow-queries delete --history-id with --yes", () => {
+  const o = opts(["delete", "--history-id", "42", "--yes"]);
+  assert.equal(o.historyId, "42");
+  assert.equal(o.yes, true);
+});
+
+// setup -----------------------------------------------------------------------
+
+test("setup --force --skip-email", () => {
+  const o = opts(["--force", "--skip-email"]);
+  assert.equal(o.force, true);
+  assert.equal(o.skipEmail, true);
+});
+
+// password flag stays a flag for login + value for users -----------------------
+
+test("--password alone (login flow) leaves password truthy", () => {
+  const o = opts(["--password"]);
+  assert.equal(!!o.password, true);
+});
+
+test("--password=secret keeps the string value (still truthy)", () => {
+  const o = opts(["--password=secret"]);
+  assert.equal(o.password, "secret");
+});

package/src/commands/anti-patterns.js

@@ -0,0 +1,77 @@
+"use strict";
+
+/**
+ * `deepsql anti-patterns --connection <name> [--kind table|query] [--limit N] [--json]`
+ *
+ * Returns DeepSQL-detected anti-patterns. Two flavors:
+ *   - kind=table (default) → GET /brain/table-anti-patterns/{cid}
+ *   - kind=query           → GET /brain/query-anti-patterns/{cid}?limit=
+ */
+
+const { request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+async function run(opts, { stdout = process.stdout } = {}) {
+  if (!opts.connection) throw new Error("--connection <name> is required.");
+
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const kind = opts.kind === "query" ? "query" : "table";
+  const path =
+    kind === "query"
+      ? `/brain/query-anti-patterns/${encodeURIComponent(connectionId)}`
+      : `/brain/table-anti-patterns/${encodeURIComponent(connectionId)}`;
+
+  const query = {};
+  if (kind === "query" && opts.limit != null) query.limit = opts.limit;
+
+  const response = await request(session.baseUrl, path, {
+    token: session.token,
+    query,
+  });
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  if (kind === "table") {
+    const tableMap =
+      response && typeof response === "object" && !Array.isArray(response) ? response : {};
+    const tables = Object.keys(tableMap);
+    if (tables.length === 0) {
+      stdout.write("No table-level anti-patterns detected.\n");
+      return;
+    }
+    const noun = tables.length === 1 ? "table" : "tables";
+    stdout.write(`${tables.length} ${noun} with anti-patterns:\n`);
+    for (const t of tables) {
+      const entry = tableMap[t] || {};
+      const patterns = entry.patterns || entry.antiPatterns || entry || [];
+      const n = Array.isArray(patterns) ? patterns.length : 0;
+      stdout.write(`  • ${t}: ${n} ${n === 1 ? "pattern" : "patterns"}\n`);
+    }
+    return;
+  }
+
+  const list = Array.isArray(response) ? response : response?.patterns || [];
+  if (list.length === 0) {
+    stdout.write("No query anti-patterns detected.\n");
+    return;
+  }
+  const sev = list.reduce((acc, p) => {
+    const s = p.severity || "UNKNOWN";
+    acc[s] = (acc[s] || 0) + 1;
+    return acc;
+  }, {});
+  const sevStr = Object.entries(sev).map(([k, v]) => `${k}=${v}`).join(", ");
+  const noun = list.length === 1 ? "anti-pattern" : "anti-patterns";
+  stdout.write(`${list.length} query ${noun}${sevStr ? ` (${sevStr})` : ""}:\n`);
+  for (const p of list.slice(0, 20)) {
+    stdout.write(`  • [${p.severity || "?"}] ${p.patternType || p.name || "pattern"}: ${p.description || ""}\n`);
+  }
+}
+
+module.exports = { run };

package/src/commands/brain-context.js

@@ -0,0 +1,68 @@
+"use strict";
+
+/**
+ * `deepsql brain-context "<question>" --connection <name> [--top-k N] [--json]`
+ *
+ * Returns DeepSQL's retrieval context for a question — relevant tables,
+ * columns, FK relationships, training docs, business rules, and embedding-
+ * ranked snippets — without invoking the chat agent. Coding agents (Claude
+ * Code, Cursor, Codex) feed this into their own LLM to generate SQL or prose.
+ *
+ *   - Without --top-k → POST /training/context/{cid}  (rich payload)
+ *   - With --top-k    → GET  /training/retrieve/{cid}?q=&topK= (ranked snippets)
+ */
+
+const { request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+async function run(opts, { stdout = process.stdout } = {}) {
+  const question = opts.positional.join(" ").trim();
+  if (!question) {
+    throw new Error(
+      'Pass a question: `deepsql brain-context "which tables hold customer orders?" --connection <name>`.',
+    );
+  }
+  if (!opts.connection) throw new Error("--connection <name> is required.");
+
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const topK = opts.topK == null ? null : Number.parseInt(opts.topK, 10);
+  let response;
+  if (topK != null && Number.isFinite(topK)) {
+    response = await request(
+      session.baseUrl,
+      `/training/retrieve/${encodeURIComponent(connectionId)}`,
+      { token: session.token, query: { q: question, topK } },
+    );
+  } else {
+    response = await request(
+      session.baseUrl,
+      `/training/context/${encodeURIComponent(connectionId)}`,
+      { method: "POST", token: session.token, json: { question } },
+    );
+  }
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  // Default: print the most useful field directly so it can be piped into
+  // a coding agent. /context returns trainingContext (text); /retrieve
+  // returns ranked results — fall back to JSON for the latter.
+  if (response && typeof response === "object" && response.trainingContext) {
+    if (response.skipped) {
+      stdout.write(`# (skipped: ${response.skipReason || "n/a"})\n`);
+    }
+    stdout.write(`${response.trainingContext}\n`);
+    if (response.companyKnowledgeContext) {
+      stdout.write(`\n# Company knowledge\n${response.companyKnowledgeContext}\n`);
+    }
+    return;
+  }
+  stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+}
+
+module.exports = { run };

package/src/commands/business-rules.js

@@ -0,0 +1,59 @@
+"use strict";
+
+/**
+ * `deepsql business-rules --connection <name> [--question "..."] [--json]`
+ *
+ * Lists active business rules and SQL guardrails for a connection. Wraps
+ * GET /business-rules/connection/{connectionId}?question=...
+ */
+
+const { request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+async function run(opts, { stdout = process.stdout } = {}) {
+  if (!opts.connection) throw new Error("--connection <name> is required.");
+
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const query = {};
+  if (opts.question) query.question = opts.question;
+  const response = await request(
+    session.baseUrl,
+    `/business-rules/connection/${encodeURIComponent(connectionId)}`,
+    { token: session.token, query },
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  const active = response?.activeRules || [];
+  const guards = response?.applicableGuardrails || [];
+
+  if (active.length === 0 && guards.length === 0) {
+    stdout.write("No business rules or guardrails configured for this connection.\n");
+    return;
+  }
+
+  stdout.write(
+    `${plural(active.length, "active business rule", "active business rules")}, ` +
+      `${plural(guards.length, "applicable guardrail", "applicable guardrails")}.\n`,
+  );
+  for (const r of active) {
+    const name = r.name || r.ruleName || `rule#${r.id}`;
+    const desc = r.description || r.ruleText || "";
+    stdout.write(`  • ${name}${desc ? `: ${desc}` : ""}\n`);
+  }
+  if (guards.length) {
+    stdout.write(`\nGuardrail context:\n${response?.guardrailContext || "(none)"}\n`);
+  }
+}
+
+function plural(n, singular, many) {
+  return `${n} ${n === 1 ? singular : many}`;
+}
+
+module.exports = { run };