@deepsql/mcp 0.2.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "./bin/deepsql.js",

package/src/api/client.js

@@ -32,7 +32,7 @@ function resolveUrl(baseUrl, path) {
   return new URL(withApi, normalizeBaseUrl(baseUrl)).toString();
 }
 
-async function request(baseUrl, pathOrUrl, { method = "GET", json, headers, token, timeoutMs = 120000, query } = {}) {
+async function request(baseUrl, pathOrUrl, { method = "GET", json, headers, token, timeoutMs = 120000, query, returnHeaders = false } = {}) {
   let url;
   if (typeof pathOrUrl === "string" && /^https?:\/\//i.test(pathOrUrl)) {
     url = pathOrUrl;
@@ -87,7 +87,31 @@ async function request(baseUrl, pathOrUrl, { method = "GET", json, headers, toke
     const message = (body && typeof body === "object" && (body.message || body.error)) || `HTTP ${response.status}`;
     throw new ApiError(message, { status: response.status, body });
   }
+  if (returnHeaders) {
+    // Node's fetch exposes Set-Cookie via getSetCookie() (Node 20+); the
+    // password-login flow needs the auth_token cookie value to mint a long-
+    // lived MCP token afterwards.
+    const setCookies = typeof response.headers.getSetCookie === "function"
+      ? response.headers.getSetCookie()
+      : [];
+    return { body, status: response.status, setCookies };
+  }
   return body;
 }
 
-module.exports = { ApiError, request, resolveUrl, normalizeBaseUrl };
+/**
+ * Extract a single cookie value from an array of Set-Cookie header values.
+ *
+ *   parseCookieValue(["auth_token=abc.def; Path=/; HttpOnly", "refresh_token=…"], "auth_token")
+ *     => "abc.def"
+ */
+function parseCookieValue(setCookies, name) {
+  if (!Array.isArray(setCookies)) return null;
+  for (const raw of setCookies) {
+    const match = raw && raw.match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`));
+    if (match) return decodeURIComponent(match[1]);
+  }
+  return null;
+}
+
+module.exports = { ApiError, request, resolveUrl, normalizeBaseUrl, parseCookieValue };

package/src/auth/password-flow.js

@@ -0,0 +1,149 @@
+"use strict";
+
+/**
+ * Direct username/password login — for headless boxes where neither a browser
+ * nor copy-paste of a device code is convenient (e.g. provisioning a fresh
+ * self-host VM via Ansible/cloud-init, or a CI runner that needs to mint a
+ * service-account token from a stored secret).
+ *
+ * Flow:
+ *   1. Prompt for email + password (or accept --email and --password-stdin).
+ *   2. POST /auth/login. The backend either:
+ *        a) succeeds and sets the auth_token cookie containing a session JWT, or
+ *        b) returns { challengeId, message } indicating an email-OTP step.
+ *   3. If a challenge is required, kick off /auth/email/start, prompt for the
+ *      OTP, then POST /auth/email/verify. Same auth_token cookie is set on
+ *      success.
+ *   4. With the JWT in hand, POST /auth/mcp-tokens to mint a long-lived MCP
+ *      token. The session cookie is short-lived (minutes); the MCP token lives
+ *      until revoked, which is what we want to persist to ~/.config/deepsql.
+ *
+ * Security notes:
+ *   - We never persist the raw password. It's read from a TTY (echo off) or
+ *     from stdin and then dropped after the login POST.
+ *   - The session JWT is held only in memory between login and the
+ *     mcp-tokens POST.
+ *   - For CI-style use, callers should pipe the password via stdin
+ *     (`--password-stdin`) rather than passing it as an argv flag, since argv
+ *     shows up in `ps`.
+ */
+
+const os = require("node:os");
+
+const { ApiError, parseCookieValue, request } = require("../api/client");
+const { prompt, promptPassword, readSingleLineFromStdin } = require("./prompt");
+
+async function runPasswordFlow({ baseUrl, email, passwordStdin, hostname, clientLabel, log = () => {} }) {
+  const resolvedEmail = email && email.trim() ? email.trim() : await prompt("Email: ");
+  if (!resolvedEmail) throw new Error("Email is required.");
+
+  const password = passwordStdin
+    ? await readSingleLineFromStdin()
+    : await promptPassword("Password: ");
+  if (!password) throw new Error("Password is required.");
+
+  log(`Authenticating ${resolvedEmail} against ${baseUrl}…`);
+  let jwt = await postLoginAndExtractJwt(baseUrl, resolvedEmail, password);
+
+  if (!jwt) {
+    // Server returned a challenge — currently the only kind we handle is
+    // email OTP. Other challenges (e.g. authenticator-app MFA) should fall
+    // back to the browser flow with a clear error.
+    log("Server requires email verification. Sending OTP…");
+    jwt = await runEmailOtpChallenge(baseUrl, resolvedEmail);
+  }
+
+  log("Minting long-lived CLI token…");
+  const tokenName = buildTokenName(clientLabel, hostname);
+  const created = await request(baseUrl, "/auth/mcp-tokens", {
+    method: "POST",
+    token: jwt,
+    json: { name: tokenName },
+  });
+
+  return {
+    token: created.token,
+    token_id: created.id,
+    username: extractUsername(created, resolvedEmail),
+    expires_at: created.expiresAt || null,
+  };
+}
+
+async function postLoginAndExtractJwt(baseUrl, email, password) {
+  let result;
+  try {
+    result = await request(baseUrl, "/auth/login", {
+      method: "POST",
+      json: { email, password },
+      returnHeaders: true,
+    });
+  } catch (err) {
+    if (err instanceof ApiError && err.status >= 400 && err.status < 500) {
+      const detail = err.body && typeof err.body === "object" ? err.body.message : null;
+      throw new Error(detail || "Invalid email or password.");
+    }
+    throw err;
+  }
+
+  const jwt = parseCookieValue(result.setCookies, "auth_token");
+  if (jwt) return jwt;
+
+  // No cookie on the response — must be a challenge handoff. Body shape is
+  // { challengeId, message }.
+  if (result.body && result.body.challengeId) return null;
+
+  throw new Error(
+    "Login succeeded but no session token was issued — your DeepSQL instance may use SSO that the CLI can't drive. Use `deepsql login` (browser flow) instead.",
+  );
+}
+
+async function runEmailOtpChallenge(baseUrl, email) {
+  // Fresh challenge so /email/start has something to act on. The login call
+  // above already created a challenge but didn't expose its id; calling
+  // /email/start without a prior challenge id is supported and starts a new
+  // one for the same user.
+  let started;
+  try {
+    started = await request(baseUrl, "/auth/email/start", {
+      method: "POST",
+      json: { email },
+    });
+  } catch (err) {
+    throw new Error(
+      `Could not start email verification: ${err.message}. Use \`deepsql login\` (browser flow) if your account requires SSO or authenticator MFA.`,
+    );
+  }
+
+  const otp = await prompt(`Email OTP (sent to ${email}): `);
+  if (!otp) throw new Error("OTP is required.");
+
+  const result = await request(baseUrl, "/auth/email/verify", {
+    method: "POST",
+    json: { challengeId: started.challengeId, otp },
+    returnHeaders: true,
+  });
+  const jwt = parseCookieValue(result.setCookies, "auth_token");
+  if (!jwt) {
+    throw new Error("Email verification did not return a session token. Aborting.");
+  }
+  return jwt;
+}
+
+function extractUsername(createdTokenResponse, fallbackEmail) {
+  if (createdTokenResponse && typeof createdTokenResponse === "object") {
+    if (createdTokenResponse.username) return createdTokenResponse.username;
+    if (createdTokenResponse.userId) return String(createdTokenResponse.userId);
+  }
+  return fallbackEmail;
+}
+
+function buildTokenName(clientLabel, hostname) {
+  const parts = ["CLI"];
+  parts.push(clientLabel && clientLabel.trim() ? clientLabel.trim() : "deepsql");
+  if (hostname && hostname.trim()) parts.push(`@ ${hostname.trim()}`);
+  parts.push("(password)");
+  const name = parts.join(" ");
+  return name.length > 120 ? name.slice(0, 120) : name;
+}
+
+module.exports = { runPasswordFlow };

package/src/auth/prompt.js

@@ -0,0 +1,96 @@
+"use strict";
+
+/**
+ * Tiny interactive prompt helpers — no dependency on a TTY library.
+ *
+ * For passwords we mute the terminal echo so the value does not show on screen
+ * or get captured by ttyrec / screen-recording. If stdin is not a TTY (piped
+ * input), we read a single line as-is.
+ */
+
+const readline = require("node:readline");
+
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function promptPassword(question) {
+  if (!process.stdin.isTTY) {
+    return readSingleLineFromStdin();
+  }
+  return new Promise((resolve, reject) => {
+    process.stderr.write(question);
+    const stdin = process.stdin;
+    const previousRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+
+    const ETX = "\u0003"; // Ctrl-C
+    const EOT = "\u0004"; // Ctrl-D
+    const BS  = "\u0008"; // ASCII backspace
+    const DEL = "\u007f"; // most modern terminals send this on backspace
+
+    let buffer = "";
+    const onData = (char) => {
+      switch (char) {
+        case "\r":
+        case "\n":
+        case EOT:
+          finish();
+          return;
+        case ETX:
+          cleanup();
+          process.stderr.write("\n");
+          reject(new Error("Cancelled"));
+          return;
+        case BS:
+        case DEL:
+          buffer = buffer.slice(0, -1);
+          return;
+        default:
+          // Accept printable chars only; ignore other ANSI control sequences.
+          if (char.charCodeAt(0) >= 32) buffer += char;
+      }
+    };
+
+    const cleanup = () => {
+      stdin.removeListener("data", onData);
+      try {
+        stdin.setRawMode(previousRaw);
+      } catch {}
+      stdin.pause();
+    };
+
+    const finish = () => {
+      cleanup();
+      process.stderr.write("\n");
+      resolve(buffer);
+    };
+
+    stdin.on("data", onData);
+  });
+}
+
+function readSingleLineFromStdin() {
+  return new Promise((resolve, reject) => {
+    let buffer = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      buffer += chunk;
+    });
+    process.stdin.on("end", () => {
+      // Strip a single trailing newline if the caller did echo \$PWD | …
+      resolve(buffer.replace(/\r?\n$/, ""));
+    });
+    process.stdin.on("error", reject);
+  });
+}
+
+module.exports = { prompt, promptPassword, readSingleLineFromStdin };

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,7 @@ const COMMANDS = {
   query: () => require("./commands/query"),
   explain: () => require("./commands/explain"),
   schema: () => require("./commands/schema"),
+  digest: () => require("./commands/digest"),
 };
 
 const HELP = `deepsql — DeepSQL CLI
@@ -31,8 +32,14 @@ Usage:
   deepsql <command> [options]
 
 Commands:
-  login [--url <url>] [--device|--browser] [--no-browser] [--label <name>]
+  login [--url <url>] [--device|--browser|--password] [--no-browser] [--label <name>]
+        [--email <email>] [--password-stdin]
                                   Authorize this CLI with a DeepSQL instance.
+                                  Default: browser callback (PKCE), or device-code
+                                  on headless boxes. Use --password for direct
+                                  email+password login on a fresh self-host VM
+                                  with no browser; pipe the password via stdin
+                                  with --password-stdin for non-interactive use.
   logout [--url <url>]            Revoke and forget the saved token.
   whoami                          Show the user behind the saved token.
   config show                     List saved profiles.
@@ -40,14 +47,21 @@ 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.
 
 Global options:
   --url <url>     Override the DeepSQL base URL.
@@ -107,12 +121,16 @@ function buildOpts(parsed) {
     device: !!f.device,
     browser: !!f.browser,
     noBrowser: !!f.noBrowser,
+    password: !!f.password,
+    passwordStdin: !!f.passwordStdin,
+    email: f.email || null,
     label: f.label || null,
     connection: f.connection || f.c || null,
     chat: f.chat || null,
     user: f.user || null,
     project: f.project || null,
     limit: f.limit,
+    count: f.count || f.n || null,
     timeoutSeconds: f.timeoutSeconds,
     file: f.file || null,
   };

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/ask.js

@@ -3,13 +3,15 @@
 const os = require("node:os");
 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 ask \"why is this query slow?\" --connection <id>`.");
-  if (!opts.connection) throw new Error("--connection <id> is required.");
+  if (!question) throw new Error("Pass a question: `deepsql ask \"why is this query slow?\" --connection <name>`.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
 
   const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
   const userId = opts.user || `cli-${os.userInfo().username}`;
   const projectId = opts.project || "deepsql-cli";
 
@@ -18,7 +20,7 @@ async function run(opts, { stdout = process.stdout } = {}) {
     token: session.token,
     timeoutMs: 240000,
     json: {
-      connectionId: opts.connection,
+      connectionId,
       message: question,
       chatId: opts.chat || null,
       userId,

package/src/commands/connections.js

@@ -18,11 +18,23 @@ async function run(opts, { stdout = process.stdout } = {}) {
     stdout.write("No connections.\n");
     return;
   }
-  for (const conn of data) {
-    const id = conn.id || conn.connectionId;
-    const name = conn.connectionName || conn.name || "(unnamed)";
-    const dbType = conn.databaseType || conn.dbType || "?";
-    stdout.write(`${id}  ${dbType.padEnd(10)}  ${name}\n`);
+  // Name first — it's what users will pass to --connection. ID kept on the
+  // right for back-compat / scripting.
+  const rows = data.map((conn) => ({
+    name: conn.connectionName || conn.name || "(unnamed)",
+    type: conn.databaseType || conn.dbType || "?",
+    id: conn.id || conn.connectionId || "",
+  }));
+  const widths = {
+    name: Math.max(4, ...rows.map((r) => r.name.length)),
+    type: Math.max(4, ...rows.map((r) => r.type.length)),
+  };
+  stdout.write(
+    `${"NAME".padEnd(widths.name)}  ${"TYPE".padEnd(widths.type)}  ID\n` +
+      `${"-".repeat(widths.name)}  ${"-".repeat(widths.type)}  ${"-".repeat(36)}\n`,
+  );
+  for (const row of rows) {
+    stdout.write(`${row.name.padEnd(widths.name)}  ${row.type.padEnd(widths.type)}  ${row.id}\n`);
   }
 }
 

package/src/commands/digest.js

@@ -0,0 +1,197 @@
+"use strict";
+
+/**
+ * `deepsql digest` — surface the daily DeepSQL digest from the terminal.
+ *
+ *   deepsql digest                   → show the single most recent digest, full body
+ *   deepsql digest <N>               → list the last N digests (compact, one per row)
+ *   deepsql digest list [--count N]  → same as above; explicit form
+ *   deepsql digest show <id>         → show a specific digest by id
+ *   --connection <id>                → filter to one connection
+ *   --json                           → raw JSON output
+ *
+ * Backend: GET /admin/slack/digests?connectionId=&page=0&size=N
+ *   Returns a Spring Data Page<SlackDigestLog>: { content: [...], totalElements, ... }
+ *   Requires ADMIN role on the calling user's MCP token.
+ */
+
+const { ApiError, request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+const DEFAULT_LIST_COUNT = 10;
+const MAX_COUNT = 100;
+
+async function run(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (!opts.connection) {
+    throw new Error(
+      "--connection <name> is required. Digests are per-connection — pick one from `deepsql connections list`.",
+    );
+  }
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const sub = opts.positional[0];
+
+  // `deepsql digest <N>` shorthand — first positional is a number.
+  if (sub && /^\d+$/.test(sub)) {
+    return runList(session, connectionId, parseCount(sub), opts, { stdout, stderr });
+  }
+  if (!sub || sub === "latest") {
+    return runLatest(session, connectionId, opts, { stdout, stderr });
+  }
+  if (sub === "list") {
+    const count = parseCount(opts.count) || parseCount(opts.positional[1]) || DEFAULT_LIST_COUNT;
+    return runList(session, connectionId, count, opts, { stdout, stderr });
+  }
+  if (sub === "show") {
+    const id = opts.positional[1];
+    if (!id) throw new Error("Pass the digest id: `deepsql digest show <id> --connection <name>`.");
+    return runShow(session, connectionId, id, opts, { stdout, stderr });
+  }
+  throw new Error(`Unknown digest subcommand: ${sub}. Try \`latest\`, \`list\`, \`show <id>\`, or pass a number.`);
+}
+
+async function runLatest(session, connectionId, opts, { stdout }) {
+  const page = await fetchPage(session, connectionId, 0, 1);
+  const digest = page.content?.[0];
+  if (!digest) {
+    stdout.write(`No digests yet for connection "${opts.connection}".\n`);
+    return;
+  }
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(digest, null, 2)}\n`);
+    return;
+  }
+  printFull(stdout, digest);
+}
+
+async function runList(session, connectionId, requestedCount, opts, { stdout }) {
+  const count = Math.min(requestedCount, MAX_COUNT);
+  const page = await fetchPage(session, connectionId, 0, count);
+  const items = page.content || [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write(`No digests yet for connection "${opts.connection}".\n`);
+    return;
+  }
+  printTable(stdout, items);
+  if (page.totalElements && page.totalElements > items.length) {
+    stdout.write(`\n${items.length} of ${page.totalElements} shown — pass a larger N to see more.\n`);
+  }
+}
+
+async function runShow(session, connectionId, id, opts, { stdout }) {
+  // No single-digest backend endpoint exists yet, so locate by paging.
+  // Cheap enough for typical digest counts; we cap at a few pages.
+  const target = String(id);
+  for (let page = 0; page < 10; page++) {
+    const result = await fetchPage(session, connectionId, page, 50);
+    const hit = (result.content || []).find((d) => String(d.id) === target);
+    if (hit) {
+      if (opts.json) {
+        stdout.write(`${JSON.stringify(hit, null, 2)}\n`);
+        return;
+      }
+      printFull(stdout, hit);
+      return;
+    }
+    if (result.last || (result.content || []).length === 0) break;
+  }
+  throw new Error(`Digest ${id} not found in the most recent 500 entries for "${opts.connection}".`);
+}
+
+async function fetchPage(session, connectionId, page, size) {
+  try {
+    return await request(session.baseUrl, "/admin/slack/digests", {
+      token: session.token,
+      query: {
+        connectionId,
+        page,
+        size,
+      },
+    });
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 403) {
+      throw new Error(
+        "Access denied — fetching digests requires ADMIN role. Ask an administrator to mint a token, or run `deepsql login` as an admin.",
+      );
+    }
+    throw err;
+  }
+}
+
+function printTable(stdout, items) {
+  const rows = items.map((d) => ({
+    id: String(d.id ?? ""),
+    sentAt: formatTimestamp(d.sentAt),
+    status: d.status || "?",
+    connection: trim(d.connectionName || d.connectionId || "—", 24),
+    headline: trim(d.headline || firstLine(d.content) || "(no headline)", 60),
+  }));
+  const cols = [
+    { key: "id", label: "ID" },
+    { key: "sentAt", label: "Sent" },
+    { key: "status", label: "Status" },
+    { key: "connection", label: "Connection" },
+    { key: "headline", label: "Headline" },
+  ];
+  const widths = cols.map((c) => Math.max(c.label.length, ...rows.map((r) => r[c.key].length)));
+  const header = cols.map((c, i) => c.label.padEnd(widths[i])).join("  ");
+  const sep = widths.map((w) => "-".repeat(w)).join("  ");
+  stdout.write(`${header}\n${sep}\n`);
+  for (const row of rows) {
+    stdout.write(`${cols.map((c, i) => row[c.key].padEnd(widths[i])).join("  ")}\n`);
+  }
+}
+
+function printFull(stdout, d) {
+  const sent = formatTimestamp(d.sentAt);
+  stdout.write(`Digest #${d.id}  ·  ${sent}  ·  ${d.status || "?"}\n`);
+  if (d.connectionName || d.connectionId) {
+    stdout.write(`Connection: ${d.connectionName || d.connectionId}\n`);
+  }
+  if (d.headline) {
+    stdout.write(`Headline:   ${d.headline}\n`);
+  }
+  stdout.write("\n");
+  if (d.status === "FAILED" && d.errorMessage) {
+    stdout.write(`Error: ${d.errorMessage}\n`);
+    return;
+  }
+  stdout.write(`${d.content || "(empty)"}\n`);
+}
+
+function parseCount(value) {
+  if (value == null) return null;
+  const n = Number.parseInt(value, 10);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return n;
+}
+
+function formatTimestamp(value) {
+  if (!value) return "—";
+  try {
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime())) return String(value);
+    return d.toISOString().replace("T", " ").slice(0, 16) + "Z";
+  } catch {
+    return String(value);
+  }
+}
+
+function trim(text, maxLen) {
+  if (!text) return "";
+  const s = String(text).replace(/\s+/g, " ").trim();
+  return s.length > maxLen ? s.slice(0, maxLen - 1) + "…" : s;
+}
+
+function firstLine(text) {
+  if (!text) return "";
+  const idx = text.indexOf("\n");
+  return idx === -1 ? text : text.slice(0, idx);
+}
+
+module.exports = { run };

package/src/commands/explain.js

@@ -4,19 +4,21 @@ const fs = require("node:fs");
 const { request } = require("../api/client");
 const { validateReadOnlySql } = require("../../deepsql-phase1-lib");
 const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
 
 async function run(opts, { stdout = process.stdout } = {}) {
-  if (!opts.connection) throw new Error("--connection <id> is required.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
   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 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: opts.connection, query: validation.normalizedQuery },
+    json: { connectionId, query: validation.normalizedQuery },
   });
 
   if (opts.json) {

package/src/commands/login.js

@@ -3,6 +3,7 @@
 const os = require("node:os");
 const { runBrowserFlow } = require("../auth/browser-flow");
 const { runDeviceFlow } = require("../auth/device-flow");
+const { runPasswordFlow } = require("../auth/password-flow");
 const store = require("../auth/store");
 const { ApiError } = require("../api/client");
 
@@ -10,13 +11,15 @@ function defaultClientLabel() {
   return `deepsql-cli@${process.versions.node}`;
 }
 
-function shouldUseDevice(opts) {
-  if (opts.device) return true;
-  if (opts.browser) return false;
-  // Heuristic: assume browser unless we detect a headless env.
-  if (process.env.SSH_CONNECTION || process.env.SSH_CLIENT) return true;
-  if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return true;
-  return false;
+function pickFlow(opts) {
+  // Explicit user choice wins.
+  if (opts.password) return "password";
+  if (opts.device) return "device";
+  if (opts.browser) return "browser";
+  // Heuristic: prefer browser; fall back to device-code in headless envs.
+  if (process.env.SSH_CONNECTION || process.env.SSH_CLIENT) return "device";
+  if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return "device";
+  return "browser";
 }
 
 async function run(opts, { stderr = process.stderr, stdout = process.stdout } = {}) {
@@ -28,14 +31,24 @@ async function run(opts, { stderr = process.stderr, stdout = process.stdout } =
   }
   const hostname = os.hostname();
   const label = opts.label || defaultClientLabel();
-  const useDevice = shouldUseDevice(opts);
+  const flow = pickFlow(opts);
   const log = (msg) => stderr.write(`[deepsql] ${msg}\n`);
 
   let issued;
   try {
-    if (useDevice) {
+    if (flow === "device") {
       log(`Starting device-code login against ${baseUrl}…`);
       issued = await runDeviceFlow({ baseUrl, hostname, clientLabel: label, log });
+    } else if (flow === "password") {
+      log(`Starting password login against ${baseUrl}…`);
+      issued = await runPasswordFlow({
+        baseUrl,
+        email: opts.email,
+        passwordStdin: !!opts.passwordStdin,
+        hostname,
+        clientLabel: label,
+        log,
+      });
     } else {
       log(`Starting browser login against ${baseUrl}…`);
       issued = await runBrowserFlow({

package/src/commands/query.js

@@ -4,14 +4,16 @@ const fs = require("node:fs");
 const { request } = require("../api/client");
 const { validateReadOnlySql } = require("../../deepsql-phase1-lib");
 const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
 
 async function run(opts, { stdout = process.stdout } = {}) {
-  if (!opts.connection) throw new Error("--connection <id> is required.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
   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);
 
@@ -19,7 +21,7 @@ async function run(opts, { stdout = process.stdout } = {}) {
     method: "POST",
     token: session.token,
     json: {
-      connectionId: opts.connection,
+      connectionId,
       query: validation.normalizedQuery,
       limit,
       timeoutSeconds: timeout,
@@ -48,19 +50,49 @@ function clampInt(value, min, max, fallback) {
 }
 
 function printRows(stdout, response) {
-  const rows = response?.rows || response?.data || [];
-  const columns = response?.columns || (rows[0] ? Object.keys(rows[0]) : []);
-  if (columns.length === 0) {
+  // Backend returns: { result: { columns: [...], rows: [[v1,v2,...], ...],
+  //                            rowCount, totalRowCount, isLimited, ... },
+  //                   success, queryType }
+  // Tolerate older shapes too — `rows` directly on the response, with rows as
+  // either arrays or row-objects.
+  const result = response?.result ?? response ?? {};
+  const rawRows = result.rows ?? result.data ?? [];
+  let columns = result.columns;
+  if (!Array.isArray(columns) || columns.length === 0) {
+    columns = rawRows[0] && !Array.isArray(rawRows[0]) ? Object.keys(rawRows[0]) : [];
+  }
+  if (columns.length === 0 || rawRows.length === 0) {
     stdout.write("(no rows)\n");
     return;
   }
-  const widths = columns.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? "").length)));
+  const cellAt = (row, idx, col) =>
+    Array.isArray(row) ? row[idx] : row?.[col];
+  const widths = columns.map((c, i) =>
+    Math.max(
+      String(c).length,
+      ...rawRows.map((r) => String(cellAt(r, i, c) ?? "").length),
+    ),
+  );
   const sep = widths.map((w) => "-".repeat(w)).join("  ");
-  stdout.write(`${columns.map((c, i) => c.padEnd(widths[i])).join("  ")}\n${sep}\n`);
-  for (const row of rows) {
-    stdout.write(`${columns.map((c, i) => String(row[c] ?? "").padEnd(widths[i])).join("  ")}\n`);
+  stdout.write(
+    `${columns.map((c, i) => String(c).padEnd(widths[i])).join("  ")}\n${sep}\n`,
+  );
+  for (const row of rawRows) {
+    stdout.write(
+      `${columns
+        .map((c, i) => String(cellAt(row, i, c) ?? "").padEnd(widths[i]))
+        .join("  ")}\n`,
+    );
+  }
+  if (result.isLimited || result.truncated) {
+    const shown = rawRows.length;
+    const total = result.totalRowCount;
+    stdout.write(
+      total != null && total > shown
+        ? `(showing ${shown} of ${total} rows)\n`
+        : `(result limited to ${shown} rows)\n`,
+    );
   }
-  if (response?.truncated) stdout.write(`(truncated to ${rows.length} rows)\n`);
 }
 
 module.exports = { run };

package/src/commands/schema.js

@@ -2,15 +2,17 @@
 
 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 <id> is required.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
   const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
   const sub = opts.positional[0] || "tables";
   const path =
     sub === "objects"
-      ? `/connections/${encodeURIComponent(opts.connection)}/objects`
-      : `/connections/${encodeURIComponent(opts.connection)}/schema`;
+      ? `/connections/${encodeURIComponent(connectionId)}/objects`
+      : `/connections/${encodeURIComponent(connectionId)}/schema`;
   const response = await request(session.baseUrl, path, { token: session.token });
   stdout.write(`${JSON.stringify(response, null, 2)}\n`);
 }