@deepsql/mcp 0.18.2 → 0.20.0

package/src/agent/bootstrap.js

@@ -0,0 +1,205 @@
+"use strict";
+
+// Lazy bootstrap for the DeepSQL Agent (Hermes-based TUI): detect/install the
+// Hermes runtime and provision the `deepsql` profile (model → the backend LLM
+// proxy with the user's token; DeepSQL MCP tools; DBA persona/skills; subtle
+// DeepSQL skin; read-only sandbox). Provisioning is idempotent; the per-launch
+// config rewrite keeps the token/connection fresh.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { userHome } = require("../user-home");
+
+const HOME = userHome();
+const HERMES_HOME = path.join(HOME, ".hermes");
+const AGENT_DIR = path.join(HERMES_HOME, "hermes-agent");
+const PROFILE = "deepsql";
+const PROFILE_HOME = path.join(HERMES_HOME, "profiles", PROFILE);
+
+function hermesBin() {
+  const venv = path.join(AGENT_DIR, ".venv", "bin", "hermes");
+  return fs.existsSync(venv) ? venv : "hermes";
+}
+
+function hermesInstalled() {
+  if (fs.existsSync(path.join(AGENT_DIR, ".venv", "bin", "hermes"))) return true;
+  const r = spawnSync("hermes", ["--version"], { stdio: "ignore" });
+  return r.status === 0;
+}
+
+function mcpServerPath() {
+  return path.resolve(__dirname, "..", "..", "deepsql-phase1-server.js");
+}
+
+// Profile distribution (SOUL.md + skills/ + skins/): the bundled copy shipped in
+// the package, else the repo `hermes/` dir during local development.
+function distSource() {
+  const bundled = path.resolve(__dirname, "..", "..", "agent-profile");
+  if (fs.existsSync(path.join(bundled, "distribution.yaml"))) return bundled;
+  const repoHermes = path.resolve(__dirname, "..", "..", "..", "hermes");
+  if (fs.existsSync(path.join(repoHermes, "distribution.yaml"))) return repoHermes;
+  return null;
+}
+
+function ensureHermes(io) {
+  const err = (io && io.stderr) || process.stderr;
+  if (hermesInstalled()) return true;
+  err.write("DeepSQL Agent needs its runtime (first run) — installing, this may take a minute…\n");
+  const r = spawnSync(
+    "bash",
+    ["-lc", "curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-setup"],
+    { stdio: "inherit" }
+  );
+  return r.status === 0 && hermesInstalled();
+}
+
+function q(s) {
+  return `"${String(s).replace(/"/g, '\\"')}"`;
+}
+
+function writeRuntimeConfig(session) {
+  fs.mkdirSync(PROFILE_HOME, { recursive: true });
+  const base = session.baseUrl.replace(/\/?$/, "/"); // ensure single trailing /
+  const proxy = base + "api/llm/v1";
+  const apiBase = base + "api/";
+  const token = session.token;
+  const mcp = mcpServerPath();
+  const conn = session.defaultConnection || "";
+
+  const config =
+`model:
+  default: gpt-5.4
+  provider: custom
+  base_url: ${q(proxy)}
+  api_key: ${q(token)}
+  api_mode: chat_completions
+  context_length: 272000
+mcp_servers:
+  deepsql:
+    command: node
+    args:
+      - ${q(mcp)}
+    env:
+      DEEPSQL_API_BASE_URL: ${q(apiBase)}
+      DEEPSQL_MCP_USER_ID: deepsql-cli
+      DEEPSQL_AUTH_TOKEN: ${q(token)}
+approvals:
+  mode: smart
+display:
+  skin: deepsql
+  interface: tui
+`;
+  fs.writeFileSync(path.join(PROFILE_HOME, "config.yaml"), config);
+
+  const env =
+`DEEPSQL_API_BASE_URL=${apiBase}
+DEEPSQL_AUTH_TOKEN=${token}
+DEEPSQL_MCP_SERVER=${mcp}
+DEEPSQL_DEFAULT_CONNECTION_ID=${conn}
+HERMES_REVISION=deepsql-cli
+`;
+  fs.writeFileSync(path.join(PROFILE_HOME, ".env"), env, { mode: 0o600 });
+}
+
+function installProfileAssets(io) {
+  const err = (io && io.stderr) || process.stderr;
+  const src = distSource();
+  if (!src) {
+    err.write("DeepSQL agent profile assets not found in this install.\n");
+    return false;
+  }
+  const bin = hermesBin();
+  const baseEnv = { ...process.env, UV_NO_CONFIG: "1" };
+  spawnSync(bin, ["profile", "install", src, "--name", PROFILE, "--force", "--yes"], { stdio: "ignore", env: baseEnv });
+  // Skin loads from <profile>/skins/.
+  const skin = path.join(src, "skins", "deepsql.yaml");
+  if (fs.existsSync(skin)) {
+    const dst = path.join(PROFILE_HOME, "skins");
+    fs.mkdirSync(dst, { recursive: true });
+    fs.copyFileSync(skin, path.join(dst, "deepsql.yaml"));
+  }
+  // Read-only sandbox: only deepsql + skills/memory remain.
+  spawnSync(
+    bin,
+    ["tools", "disable", "terminal", "file", "code_execution", "browser", "computer_use",
+     "image_gen", "tts", "vision", "web", "delegation", "cronjob"],
+    { stdio: "ignore", env: { ...baseEnv, HERMES_HOME: PROFILE_HOME } }
+  );
+  return fs.existsSync(PROFILE_HOME);
+}
+
+function ensureProfile(session, io) {
+  if (!fs.existsSync(path.join(PROFILE_HOME, "config.yaml"))) {
+    if (!installProfileAssets(io)) return false;
+  }
+  writeRuntimeConfig(session); // always refresh the token/connection for this launch
+  return true;
+}
+
+// Installed Hermes version (parsed from the runtime's __init__.py). Null if the
+// runtime layout isn't what we expect (e.g. PATH-only install) — overlay is then
+// skipped and the user gets the stock TUI with our skin.
+function installedHermesVersion() {
+  try {
+    const init = path.join(AGENT_DIR, "hermes_cli", "__init__.py");
+    const m = fs.readFileSync(init, "utf8").match(/__version__\s*=\s*["']([^"']+)["']/);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+// Overlay the prebuilt, DeepSQL-branded TUI bundle (custom DEEPSQL wordmark,
+// "What I can do" welcome panel, DBA placeholders) onto the installed Hermes
+// runtime's `ui-tui/dist/entry.js`. This delivers the full branded experience
+// with NO build step on the user's machine.
+//
+// Guarded by the Hermes version our bundle was built against: a prebuilt
+// entry.js speaks the TUI↔CLI protocol of one Hermes release, so we overlay
+// only on an exact version match. On any mismatch (or a missing bundle) we
+// leave the stock TUI in place — it still renders our skin (DeepSQL name +
+// maroon palette via skins/deepsql.yaml), just without the custom wordmark.
+//
+// We refresh the overlay on every launch and bump its mtime past the TUI build
+// inputs so Hermes' freshness check (`_tui_need_rebuild`, an mtime compare of
+// dist/entry.js vs src/) never rebuilds over it after a `hermes update`.
+function ensureBrandedTui(io) {
+  const err = (io && io.stderr) || process.stderr;
+  try {
+    const tuiDir = path.resolve(__dirname, "..", "..", "agent-profile", "tui");
+    const bundledEntry = path.join(tuiDir, "entry.js");
+    if (!fs.existsSync(bundledEntry)) return false; // skin-only branding
+    const builtFor = (() => {
+      try { return fs.readFileSync(path.join(tuiDir, "HERMES_VERSION"), "utf8").trim(); }
+      catch { return null; }
+    })();
+    const installed = installedHermesVersion();
+    if (!builtFor || !installed || builtFor !== installed) return false; // degrade to stock TUI + skin
+
+    const distDir = path.join(AGENT_DIR, "ui-tui", "dist");
+    const target = path.join(distDir, "entry.js");
+    fs.mkdirSync(distDir, { recursive: true });
+    const same =
+      fs.existsSync(target) && fs.statSync(target).size === fs.statSync(bundledEntry).size;
+    if (!same) fs.copyFileSync(bundledEntry, target);
+    // Bump mtime past every TUI build input so the freshness check never
+    // rebuilds the stock TUI over our branded bundle.
+    const future = new Date(Date.now() + 60_000);
+    fs.utimesSync(target, future, future);
+    return true;
+  } catch (e) {
+    err.write(`DeepSQL Agent: branded TUI overlay skipped (${e.message}); using stock TUI.\n`);
+    return false;
+  }
+}
+
+module.exports = {
+  ensureHermes,
+  ensureProfile,
+  ensureBrandedTui,
+  hermesBin,
+  hermesInstalled,
+  PROFILE,
+  PROFILE_HOME,
+};

package/src/cli.js

@@ -14,6 +14,7 @@
  */
 
 const COMMANDS = {
+  agent: () => require("./commands/agent"),
   login: () => require("./commands/login"),
   logout: () => require("./commands/logout"),
   whoami: () => require("./commands/whoami"),
@@ -46,6 +47,7 @@ const COMMANDS = {
 // suffix in the listing and reveal their full usage via `<command> --help`.
 
 const COMMAND_LIST = [
+  ["agent",          false, "Launch the DeepSQL Agent — interactive chat TUI (also: bare `deepsql`)"],
   ["login",          false, "Authorize this CLI with a DeepSQL instance"],
   ["logout",         false, "Revoke and forget the saved token"],
   ["whoami",         false, "Show the user behind the saved token"],
@@ -87,6 +89,16 @@ const GLOBAL_OPTIONS = [
 // constant; the dispatcher renders them on `<command> --help`.
 
 const COMMAND_HELP = {
+  agent: {
+    description: "Launch the DeepSQL Agent — an interactive chat TUI for DBA work, BI questions, and database guardrails. Running `deepsql` with no command in a terminal launches it too.",
+    usage: "deepsql agent [options]   (or just: deepsql)",
+    options: [
+      ["--url <url>",          "DeepSQL instance to use (default: saved login)"],
+      ["--connection <name>",  "Default connection for the session"],
+    ],
+    notes: "First run installs the agent runtime. Uses your saved `deepsql login` — no LLM key needed (the backend proxies the model).",
+  },
+
   login: {
     description: "Authorize this CLI with a DeepSQL instance.",
     usage: "deepsql login [options]",
@@ -650,7 +662,7 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
   const stdout = io.stdout || process.stdout;
   const useColor = colorEnabled(stdout, rawArgv);
 
-  if (rawArgv.length === 0 || isHelpFlag(rawArgv[0])) {
+  if (isHelpFlag(rawArgv[0])) {
     stdout.write(`${renderRootHelp(useColor)}\n`);
     return 0;
   }
@@ -659,8 +671,14 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
     stdout.write(`${pkg.version}\n`);
     return 0;
   }
+  // No subcommand: launch the DeepSQL Agent TUI in an interactive terminal;
+  // fall back to the root help when stdout is piped/redirected (scripts, CI).
+  if (rawArgv.length === 0 && !stdout.isTTY) {
+    stdout.write(`${renderRootHelp(useColor)}\n`);
+    return 0;
+  }
 
-  const command = rawArgv[0];
+  const command = rawArgv.length === 0 ? "agent" : rawArgv[0];
   const loader = COMMANDS[command];
   if (!loader) {
     stderr.write(`Unknown command: ${command}\n\n${renderRootHelp(colorEnabled(stderr, rawArgv))}\n`);
@@ -668,7 +686,7 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
   }
 
   // Per-command help: `deepsql <command> --help` / `-h` (anywhere in args).
-  const restArgs = rawArgv.slice(1);
+  const restArgs = rawArgv.length === 0 ? [] : rawArgv.slice(1);
   if (restArgs.some(isHelpFlag)) {
     stdout.write(`${renderCommandHelp(command, useColor)}\n`);
     return 0;
@@ -690,9 +708,17 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
     version: pkg.version,
   });
 
+  const previousExitCode = process.exitCode;
+  process.exitCode = undefined;
   try {
     const mod = loader();
-    await mod.run(opts, { stdout, stderr });
+    const commandCode = await mod.run(opts, { stdout, stderr });
+    if (typeof commandCode === "number") {
+      return commandCode;
+    }
+    if (typeof process.exitCode === "number" && process.exitCode !== 0) {
+      return process.exitCode;
+    }
     return 0;
   } catch (err) {
     stderr.write(`Error: ${err.message}\n`);
@@ -700,6 +726,12 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
       stderr.write(`${err.stack}\n`);
     }
     return 1;
+  } finally {
+    if (previousExitCode == null) {
+      process.exitCode = undefined;
+    } else {
+      process.exitCode = previousExitCode;
+    }
   }
 }
 

package/src/cli.test.js

@@ -73,6 +73,7 @@ test("every command in the catalog has a COMMAND_HELP entry", () => {
   const { main: _main } = require("./cli");
   void _main;
   const expected = [
+    "agent",
     "login","logout","whoami","config","mcp","connections","query","analyze","schema",
     "digest","brain-context","business-rules","relationships","anti-patterns","indexes",
     "users","access","permissions","slow-queries","setup",
@@ -108,6 +109,13 @@ test("main rejects unknown commands and shows the root help", async () => {
   assert.match(io.err(), /Usage: deepsql/);
 });
 
+test("main preserves a non-zero command return code", async () => {
+  const io = captureStreams();
+  const code = await main(["connections", "current", "--url", "http://x", "--token", "t"], io);
+  assert.equal(code, 1);
+  assert.match(io.err(), /No active connection set/);
+});
+
 test("--no-color suppresses ANSI escapes in help output", async () => {
   const io = captureStreams();
   // Force a TTY so the only thing turning color off is --no-color itself.
@@ -116,3 +124,45 @@ test("--no-color suppresses ANSI escapes in help output", async () => {
   // No ESC bytes anywhere.
   assert.equal(/\x1b\[/.test(io.out()), false, "help output should be plain when --no-color is set");
 });
+
+// ─── help/dispatch drift guard ─────────────────────────────────────────────
+//
+// Every command-module SUBCOMMANDS map must be reflected in COMMAND_HELP so
+// `deepsql <command> -h` actually documents what `deepsql <command> <sub>`
+// will dispatch. A previous regression shipped four new slow-query
+// subcommands that worked but weren't listed in -h — users assumed the
+// install was stale. This test catches that class of bug at PR time.
+//
+// To extend: add a `{ command, modulePath }` entry. The module must export
+// a `SUBCOMMANDS` object whose keys are the dispatchable subcommand names.
+const HELP_DRIFT_TARGETS = [
+  { command: "slow-queries", modulePath: "./commands/slow-queries" },
+];
+
+for (const { command, modulePath } of HELP_DRIFT_TARGETS) {
+  test(`COMMAND_HELP["${command}"] documents every dispatchable subcommand`, () => {
+    const mod = require(modulePath);
+    assert.ok(mod.SUBCOMMANDS, `${modulePath} must export SUBCOMMANDS for the drift guard`);
+    const help = COMMAND_HELP[command];
+    assert.ok(help, `COMMAND_HELP["${command}"] is missing`);
+    assert.ok(Array.isArray(help.subcommands), `COMMAND_HELP["${command}"].subcommands must be an array`);
+
+    const dispatchable = Object.keys(mod.SUBCOMMANDS).sort();
+    // Each help row is [usage-string, description]; the first whitespace-
+    // separated token of usage-string is the subcommand name.
+    const documented = help.subcommands
+      .map((row) => String(row[0]).trim().split(/\s+/)[0])
+      .sort();
+    const missing = dispatchable.filter((s) => !documented.includes(s));
+    const stale = documented.filter((s) => !dispatchable.includes(s));
+
+    assert.deepEqual(
+      { missing, stale },
+      { missing: [], stale: [] },
+      `\`deepsql ${command} -h\` is out of sync with src/commands/${command}.js:\n`
+        + `  missing from help (callable but undocumented): ${missing.join(", ") || "none"}\n`
+        + `  stale in help   (documented but not callable): ${stale.join(", ") || "none"}\n`
+        + `Fix: update COMMAND_HELP["${command}"].subcommands in src/cli.js.`,
+    );
+  });
+}

package/src/commands/agent.js

@@ -0,0 +1,44 @@
+"use strict";
+
+// `deepsql agent` (and bare `deepsql` in a terminal): launch the DeepSQL Agent —
+// a branded Hermes TUI for DBA / BI / database-guard chat. Resolves the saved
+// login, lazily installs the runtime, provisions the `deepsql` profile pointed
+// at the backend LLM proxy (no LLM key needed), then hands the terminal to the TUI.
+
+const { spawn } = require("node:child_process");
+const { resolveSession } = require("./_session");
+const { ensureHermes, ensureProfile, ensureBrandedTui, hermesBin, PROFILE } = require("../agent/bootstrap");
+
+async function run(opts, io = {}) {
+  const stderr = io.stderr || process.stderr;
+
+  let session;
+  try {
+    session = resolveSession(opts);
+  } catch (e) {
+    stderr.write(`${e.message}\n`);
+    return 1;
+  }
+
+  if (!ensureHermes(io)) {
+    stderr.write("Could not set up the DeepSQL Agent runtime. See https://github.com/NousResearch/hermes-agent for manual install.\n");
+    return 1;
+  }
+  if (!ensureProfile(session, io)) {
+    stderr.write("Could not provision the DeepSQL Agent profile.\n");
+    return 1;
+  }
+  ensureBrandedTui(io); // best-effort: full branded TUI when versions match, else stock TUI + skin
+
+  // Hand the terminal to the branded TUI (profile config sets interface=tui).
+  const child = spawn(hermesBin(), ["-p", PROFILE, "--tui"], { stdio: "inherit", env: process.env });
+  return await new Promise((resolve) => {
+    child.on("exit", (code) => resolve(code ?? 0));
+    child.on("error", (err) => {
+      stderr.write(`Failed to launch the DeepSQL Agent: ${err.message}\n`);
+      resolve(1);
+    });
+  });
+}
+
+module.exports = { run };

package/src/commands/connections.js

@@ -333,10 +333,11 @@ async function runTest(opts, { stdout = process.stdout, stderr = process.stderr
       throw new Error("Usage: deepsql connections test <name> | --from-file <path>");
     }
     const connectionId = await resolveConnectionId(session, target);
-    cfg = await findConnectionRecord(session, connectionId);
-    if (!cfg) throw new Error(`Connection ${target} not found.`);
-    // Backend's POST /connections/test uses saved secrets when `id` is set.
-    cfg.id = connectionId;
+    // Send only the id for saved connections. The list/show APIs intentionally
+    // omit secrets, so posting that masked summary back to /connections/test
+    // breaks SSH/SSL/password-backed connections. The backend hydrates the
+    // saved decrypted config when an id is present.
+    cfg = { id: connectionId };
   }
 
   const result = await request(session.baseUrl, "/connections/test", {
@@ -352,7 +353,9 @@ async function runTest(opts, { stdout = process.stdout, stderr = process.stderr
   printPrivilegeReport(stdout, result);
   if (!result?.connectionSuccessful) {
     process.exitCode = 1;
+    return 1;
   }
+  return 0;
 }
 
 // ─── show ──────────────────────────────────────────────────────────────────

package/src/commands/connections.test.js

@@ -0,0 +1,93 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const { parseArgs, buildOpts } = require("../cli");
+
+function opts(argv) {
+  return buildOpts(parseArgs(argv));
+}
+
+function captureStdout() {
+  let out = "";
+  let err = "";
+  return {
+    stream: { write: (s) => { out += s; } },
+    errStream: { write: (s) => { err += s; } },
+    out: () => out,
+    err: () => err,
+  };
+}
+
+function loadWithStubs({ onRequest }) {
+  for (const k of [
+    require.resolve("../api/client"),
+    require.resolve("./_session"),
+    require.resolve("./_connections"),
+    require.resolve("./connections"),
+  ]) {
+    delete require.cache[k];
+  }
+
+  const apiKey = require.resolve("../api/client");
+  require.cache[apiKey] = {
+    id: apiKey, filename: apiKey, loaded: true,
+    exports: {
+      ApiError: class ApiError extends Error {},
+      async request(baseUrl, path, body) {
+        return onRequest(baseUrl, path, body);
+      },
+      setClientContext() {},
+      getClientContext() { return null; },
+    },
+  };
+
+  const sessKey = require.resolve("./_session");
+  require.cache[sessKey] = {
+    id: sessKey, filename: sessKey, loaded: true,
+    exports: {
+      resolveSession: () => ({
+        baseUrl: "http://test",
+        token: "t",
+        defaultConnection: null,
+      }),
+    },
+  };
+
+  return require("./connections");
+}
+
+test("connections test <saved-name> posts only the connection id", async () => {
+  const seen = [];
+  const connections = loadWithStubs({
+    onRequest: (_baseUrl, path, body) => {
+      seen.push({ path, body });
+      if (path === "/connections") {
+        return [{ id: "cid-1", connectionName: "prod", sshPrivateKey: "(masked)" }];
+      }
+      if (path === "/connections/test") {
+        return {
+          success: false,
+          connectionSuccessful: false,
+          message: "Connection failed",
+          privileges: [],
+        };
+      }
+      throw new Error(`unexpected path ${path}`);
+    },
+  });
+  const stdout = captureStdout();
+  const previousExitCode = process.exitCode;
+  process.exitCode = undefined;
+  try {
+    const code = await connections.run(opts(["test", "prod"]), { stdout: stdout.stream });
+
+    assert.equal(code, 1);
+    assert.equal(process.exitCode, 1);
+    assert.deepEqual(seen.at(-1).body.json, { id: "cid-1" });
+    assert.match(stdout.out(), /Connection failed/);
+  } finally {
+    process.exitCode = previousExitCode;
+  }
+});

package/src/commands/slow-queries.js

@@ -343,7 +343,7 @@ async function cmdRegressions(opts, { stdout = process.stdout } = {}) {
     { key: "calls", label: "CALLS" },
     { key: "sql", label: "QUERY" },
   ], items.map((r) => ({
-    fingerprint: trim(r.fingerprint || "", 14),
+    fingerprint: trim(r.fingerprint || "", 16),
     factor: r.regressionFactor != null ? `${r.regressionFactor.toFixed(2)}x` : "?",
     meanMs: r.meanExecMs != null ? Math.round(r.meanExecMs).toString() : "?",
     calls: String(r.callsDelta ?? "?"),
@@ -526,7 +526,7 @@ function printTrendRows(stdout, items) {
     { key: "factor", label: "VS PREV" },
     { key: "sql", label: "QUERY" },
   ], items.map((q) => ({
-    fingerprint: trim(q.fingerprint || "", 14),
+    fingerprint: trim(q.fingerprint || "", 16),
     meanMs: q.meanExecMs != null ? Math.round(q.meanExecMs).toString() : "?",
     calls: String(q.callsDelta ?? "?"),
     factor: q.regressionFactor != null ? `${q.regressionFactor.toFixed(2)}x` : "—",