@deepsql/mcp 0.3.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "./bin/deepsql.js",
@@ -22,5 +22,8 @@
   "engines": {
     "node": ">=20"
   },
-  "license": "UNLICENSED"
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@inquirer/prompts": "^8.4.2"
+  }
 }

package/src/cli.js

@@ -7,7 +7,7 @@
  * small for the self-hosted distribution and makes it trivial to embed in
  * scripts. Supports:
  *   - boolean flags:  --json, --device, --browser, --no-browser
- *   - value flags:    --url <url>, --token <t>, --connection <id>, --limit 50
+ *   - value flags:    --url <url>, --token <t>, --connection <name>, --limit 50
  *   - subcommands:    deepsql connections list, deepsql config show
  *   - positional:     deepsql ask "what tables exist?"
  */
@@ -23,6 +23,12 @@ const COMMANDS = {
   query: () => require("./commands/query"),
   explain: () => require("./commands/explain"),
   schema: () => require("./commands/schema"),
+  digest: () => require("./commands/digest"),
+  users: () => require("./commands/users"),
+  access: () => require("./commands/access"),
+  permissions: () => require("./commands/permissions"),
+  "slow-queries": () => require("./commands/slow-queries"),
+  setup: () => require("./commands/setup"),
 };
 
 const HELP = `deepsql — DeepSQL CLI
@@ -46,14 +52,50 @@ Commands:
   config path                     Print the auth file path.
   mcp                             Run the stdio MCP server using the saved token.
   connections list [--json]       List database connections.
-  ask "<question>" --connection <id> [--chat <id>] [--json]
+  ask "<question>" --connection <name> [--chat <id>] [--json]
                                   Ask DeepSQL a question.
-  query "<sql>" --connection <id> [--limit <n>] [--timeout-seconds <n>] [--file <path>] [--json]
+  query "<sql>" --connection <name> [--limit <n>] [--timeout-seconds <n>] [--file <path>] [--json]
                                   Run a read-only SQL query.
-  explain "<sql>" --connection <id> [--file <path>] [--json]
+  explain "<sql>" --connection <name> [--file <path>] [--json]
                                   Get an EXPLAIN plan.
-  schema [tables|objects] --connection <id>
+  schema [tables|objects] --connection <name>
                                   Dump schema or database objects as JSON.
+  digest [N] [--connection <name>] [--json]
+                                  Show the latest DeepSQL digest, or pass a
+                                  number to list the last N (e.g. digest 5).
+  digest list [--count N] [--connection <name>] [--json]
+                                  Explicit list form (same as digest <N>).
+  digest show <id> [--connection <name>] [--json]
+                                  Show one digest by id.
+
+Admin commands (require ADMIN role on the calling token):
+  users list | get <ref> | add [<email>] [--role <r>] [--name <n>] [--password-stdin]
+        | set-role <ref> <role> | lock|unlock|disable <ref>
+        | resend-invite <ref> | reset-password <ref> [--password-stdin]
+        | delete <ref> [--yes]
+                                  Manage workspace users.
+  access list --user <ref> | --connection <name>
+        | grant   --user <ref> --connection <name> --level read|write|admin
+        | revoke  --user <ref> --connection <name>
+        | policy  <user> <connection>     (opens $EDITOR)
+                                  Per-connection access grants and chat policies.
+  permissions list [--role <ROLE>] [--json]
+        | override --role <ROLE> --permission <PERM> --grant|--revoke [--reason "..."]
+        | reset    --role <ROLE> --permission <PERM>
+                                  Role-based permission overrides.
+  slow-queries latest --connection <name>
+        | history --connection <name> [N]
+        | analyze --connection <name> [--time-range LAST_24_HOURS|LAST_HOUR]
+                                       [--threshold-ms <n>] [--limit <n>]
+        | optimize --connection <name> --query-id <id>
+                  (streams AI optimization steps to stderr; result to stdout)
+        | delete (--history-id <id> | --connection <name>) [--yes]
+                                  Read, trigger, and clean up slow-query analyses.
+  setup [--skip-email] [--skip-slack] [--skip-complete]
+                                  Post-install wizard: SMTP/email, Slack
+                                  (digests + bot), then mark setup complete.
+                                  Org and LLM config are set at install time
+                                  and are NOT touched by this wizard.
 
 Global options:
   --url <url>     Override the DeepSQL base URL.
@@ -110,20 +152,50 @@ function buildOpts(parsed) {
     url: f.url || null,
     token: f.token || null,
     json: !!f.json,
+    // Login-flow selectors
     device: !!f.device,
     browser: !!f.browser,
     noBrowser: !!f.noBrowser,
-    password: !!f.password,
+    // password may be `true` (login flow flag) OR a string value (`users add
+    // --password secret`, `users add --password=secret`). Each command
+    // interprets whichever shape it expects.
+    password: f.password ?? null,
     passwordStdin: !!f.passwordStdin,
     email: f.email || null,
     label: f.label || null,
+    // Connection / users / chat
     connection: f.connection || f.c || null,
     chat: f.chat || null,
     user: f.user || null,
     project: f.project || null,
+    name: f.name || null,
+    username: f.username || null,
+    role: f.role || null,
+    // List / pagination
     limit: f.limit,
+    count: f.count || f.n || null,
     timeoutSeconds: f.timeoutSeconds,
     file: f.file || null,
+    // RBAC / access
+    level: f.level || null,
+    permission: f.permission || null,
+    grant: !!f.grant,
+    revoke: !!f.revoke,
+    reason: f.reason || null,
+    // Slow queries
+    timeRange: f.timeRange || null,
+    thresholdMs: f.thresholdMs || null,
+    queryId: f.queryId || null,
+    queryText: f.queryText || null,
+    sampleQuery: f.sampleQuery || null,
+    historyId: f.historyId || null,
+    // Setup wizard
+    force: !!f.force,
+    skipEmail: !!f.skipEmail,
+    skipSlack: !!f.skipSlack,
+    skipComplete: !!f.skipComplete,
+    // Confirmations
+    yes: !!f.yes || !!f.y,
   };
 }
 

package/src/commands/_connections.js

@@ -0,0 +1,66 @@
+"use strict";
+
+/**
+ * Resolve a user-supplied connection identifier (name or UUID) to the
+ * canonical connection ID the backend expects.
+ *
+ * Backend `/connections` returns rows shaped roughly like:
+ *   { id: "<uuid>", connectionName: "mylocalpg", databaseType: "postgresql", ... }
+ *
+ * Resolution rules:
+ *   - If input matches a UUID pattern, treat it as an ID (one fetch saved).
+ *     We still verify it exists so we can fail fast with a useful message,
+ *     but only if a list fetch is cheap — for now, trust UUIDs.
+ *   - Otherwise, fetch the list and match `connectionName` case-insensitively.
+ *   - On ambiguous matches (rare — names are not unique by schema constraint),
+ *     prefer an exact-case match; otherwise raise.
+ */
+
+const { request } = require("../api/client");
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+let cachedList = null;
+
+async function listConnections(session) {
+  if (cachedList) return cachedList;
+  cachedList = await request(session.baseUrl, "/connections", { token: session.token });
+  if (!Array.isArray(cachedList)) cachedList = [];
+  return cachedList;
+}
+
+async function resolveConnectionId(session, input) {
+  if (!input || typeof input !== "string") {
+    throw new Error("Pass a connection name or id with --connection.");
+  }
+  const trimmed = input.trim();
+  if (UUID_RE.test(trimmed)) return trimmed;
+
+  const connections = await listConnections(session);
+  const exact = connections.filter((c) => (c.connectionName || c.name) === trimmed);
+  if (exact.length === 1) return exact[0].id || exact[0].connectionId;
+
+  const ciMatches = connections.filter(
+    (c) => String(c.connectionName || c.name || "").toLowerCase() === trimmed.toLowerCase(),
+  );
+  if (ciMatches.length === 1) return ciMatches[0].id || ciMatches[0].connectionId;
+
+  if (ciMatches.length > 1) {
+    const names = ciMatches.map((c) => `${c.connectionName} (${c.id})`).join(", ");
+    throw new Error(
+      `Multiple connections match "${trimmed}" by case-insensitive name: ${names}. Pass the exact name or the id.`,
+    );
+  }
+
+  // No match — show what's available so the user can pick.
+  const available = connections
+    .map((c) => c.connectionName || c.name)
+    .filter(Boolean)
+    .slice(0, 20);
+  const hint = available.length
+    ? ` Available: ${available.join(", ")}.`
+    : " (no connections visible to this token).";
+  throw new Error(`Connection "${trimmed}" not found.${hint}`);
+}
+
+module.exports = { resolveConnectionId, listConnections };

package/src/commands/_connections.test.js

@@ -0,0 +1,74 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+// We mock api/client.request before requiring the resolver so its cached
+// module reference points at our stub.
+const apiClientPath = require.resolve("../api/client");
+const realApiClient = require("../api/client");
+
+function withMockedRequest(connections, fn) {
+  delete require.cache[require.resolve("./_connections")];
+  require.cache[apiClientPath] = {
+    ...require.cache[apiClientPath],
+    exports: {
+      ...realApiClient,
+      request: async () => connections,
+    },
+  };
+  try {
+    const mod = require("./_connections");
+    return fn(mod);
+  } finally {
+    require.cache[apiClientPath].exports = realApiClient;
+    delete require.cache[require.resolve("./_connections")];
+  }
+}
+
+const session = { baseUrl: "http://x", token: "t" };
+
+test("resolves UUID input as-is without a backend roundtrip", async () => {
+  await withMockedRequest([], async ({ resolveConnectionId }) => {
+    const id = await resolveConnectionId(session, "a273f43a-a844-44a3-9026-1b0de1167e8f");
+    assert.equal(id, "a273f43a-a844-44a3-9026-1b0de1167e8f");
+  });
+});
+
+test("matches by exact connection name", async () => {
+  const connections = [
+    { id: "id-prod", connectionName: "prod" },
+    { id: "id-staging", connectionName: "staging" },
+  ];
+  await withMockedRequest(connections, async ({ resolveConnectionId }) => {
+    assert.equal(await resolveConnectionId(session, "prod"), "id-prod");
+    assert.equal(await resolveConnectionId(session, "staging"), "id-staging");
+  });
+});
+
+test("matches case-insensitively when no exact match exists", async () => {
+  const connections = [{ id: "id-prod", connectionName: "MyLocalPG" }];
+  await withMockedRequest(connections, async ({ resolveConnectionId }) => {
+    assert.equal(await resolveConnectionId(session, "mylocalpg"), "id-prod");
+  });
+});
+
+test("throws a useful error listing available names when no match", async () => {
+  const connections = [
+    { id: "1", connectionName: "alpha" },
+    { id: "2", connectionName: "beta" },
+  ];
+  await withMockedRequest(connections, async ({ resolveConnectionId }) => {
+    await assert.rejects(
+      () => resolveConnectionId(session, "missing"),
+      (err) => err.message.includes("alpha") && err.message.includes("beta"),
+    );
+  });
+});
+
+test("requires non-empty input", async () => {
+  await withMockedRequest([], async ({ resolveConnectionId }) => {
+    await assert.rejects(() => resolveConnectionId(session, ""), /connection name/);
+    await assert.rejects(() => resolveConnectionId(session, null), /connection name/);
+  });
+});

package/src/commands/_users.js

@@ -0,0 +1,55 @@
+"use strict";
+
+/**
+ * Resolve a user reference (numeric id, email, or username) to a {id, email,
+ * username, role, ...} record.
+ *
+ * Backend `GET /admin/users` returns the full list, so we fetch once per
+ * invocation and match locally. Cheap for typical org sizes.
+ */
+
+const { request } = require("../api/client");
+
+let cachedUsers = null;
+
+async function listUsers(session) {
+  if (cachedUsers) return cachedUsers;
+  cachedUsers = await request(session.baseUrl, "/admin/users", { token: session.token });
+  if (!Array.isArray(cachedUsers)) cachedUsers = [];
+  return cachedUsers;
+}
+
+function clearUserCache() {
+  cachedUsers = null;
+}
+
+async function resolveUser(session, ref) {
+  if (ref == null || String(ref).trim() === "") {
+    throw new Error("Pass a user email, username, or numeric id.");
+  }
+  const trimmed = String(ref).trim();
+
+  // Numeric id — short-circuit if list isn't already cached.
+  if (/^\d+$/.test(trimmed)) {
+    const users = await listUsers(session);
+    const hit = users.find((u) => String(u.id) === trimmed);
+    if (hit) return hit;
+    throw new Error(`User id ${trimmed} not found.`);
+  }
+
+  const users = await listUsers(session);
+  const lower = trimmed.toLowerCase();
+  const exactEmail = users.find((u) => (u.email || "").toLowerCase() === lower);
+  if (exactEmail) return exactEmail;
+  const exactUsername = users.find((u) => (u.username || "").toLowerCase() === lower);
+  if (exactUsername) return exactUsername;
+
+  const available = users
+    .map((u) => u.email || u.username)
+    .filter(Boolean)
+    .slice(0, 20);
+  const hint = available.length ? ` Available: ${available.join(", ")}.` : "";
+  throw new Error(`User "${trimmed}" not found.${hint}`);
+}
+
+module.exports = { listUsers, resolveUser, clearUserCache };

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