@deepsql/mcp 0.20.0 → 0.21.0

package/README.md

@@ -53,9 +53,14 @@ DBA persona, read-only-by-default tool scoping, and DeepSQL skins.
 - **No LLM key needed** — the DeepSQL backend proxies the model
   (`/api/llm/v1`), authenticated by your `deepsql login` token. The agent
   never sees a provider key.
-- **First run** installs the agent runtime (Python via the Hermes
-  installer + Node for the TUI) and provisions a local `deepsql` profile.
-  Subsequent launches are instant.
+- **Runtime install** — by default `npm install -g @deepsql/mcp` pre-installs
+  the agent runtime (a Hermes build pinned to a known-good commit) so the first
+  `deepsql` is instant. It's best-effort and never fails the npm install, and
+  skips automatically in CI and non-global installs. Opt out with
+  `DEEPSQL_SKIP_AGENT_SETUP=1` — pure-MCP users (Claude Code / Cursor) then
+  don't pull the runtime, and it installs lazily on first `deepsql agent`
+  instead. The per-user `deepsql` profile is provisioned on first launch after
+  login (it needs your token).
 - **Read-only by default** — only the DeepSQL tools, memory, and skills are
   enabled; host-affecting toolsets (terminal/file/code-exec/browser) are
   disabled. `apply_index_recommendation` stays server-side confirm-gated.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "DeepSQL CLI, DBA Agent TUI, and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",
@@ -14,6 +14,7 @@
     "bin",
     "skills",
     "src",
+    "scripts",
     "agent-profile",
     "deepsql-phase1-server.js",
     "deepsql-phase1-lib.js",
@@ -21,7 +22,8 @@
     "codex_config.customer.example.toml"
   ],
   "scripts": {
-    "test": "node --test deepsql-phase1-lib.test.js src/*.test.js src/**/*.test.js"
+    "test": "node --test deepsql-phase1-lib.test.js src/*.test.js src/**/*.test.js",
+    "postinstall": "node scripts/postinstall.js"
   },
   "engines": {
     "node": ">=20"

package/scripts/postinstall.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+"use strict";
+
+// Postinstall: pre-install the DeepSQL Agent (Hermes) runtime at `npm install -g`
+// time so the first `deepsql` launch is instant instead of triggering a heavy
+// one-time download. Best-effort and NON-FATAL — it never fails the npm install.
+//
+// Opt out (e.g. pure-MCP users who only want the editor tools, not the agent):
+//   DEEPSQL_SKIP_AGENT_SETUP=1 npm install -g @deepsql/mcp
+//
+// It auto-skips when there's nothing/no-one to set up for:
+//   - CI environments (process.env.CI)
+//   - non-global installs (local dev `npm install`, dependency installs)
+// The profile itself is provisioned later, on first `deepsql` after login,
+// because it needs the user's token.
+
+function log(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+
+function skip(reason) {
+  // Silent for the common "not global / CI" cases; only note an explicit opt-out.
+  if (reason) log(`DeepSQL Agent: ${reason}`);
+  process.exit(0);
+}
+
+try {
+  if (process.env.DEEPSQL_SKIP_AGENT_SETUP) {
+    skip("agent runtime setup skipped (DEEPSQL_SKIP_AGENT_SETUP set).");
+  }
+  if (process.env.CI) skip();
+  // Only pre-install on an explicit global install (or a forced run). Local /
+  // dependency installs shouldn't pull a Python+Node runtime.
+  const isGlobal = String(process.env.npm_config_global || "") === "true";
+  if (!isGlobal && !process.env.DEEPSQL_FORCE_AGENT_SETUP) skip();
+
+  const { ensureHermes, hermesInstalled } = require("../src/agent/bootstrap");
+
+  if (hermesInstalled()) {
+    log("✓ DeepSQL Agent runtime already present.");
+    process.exit(0);
+  }
+
+  log("DeepSQL Agent: pre-installing the agent runtime so `deepsql` starts instantly.");
+  log("  (Opt out next time with DEEPSQL_SKIP_AGENT_SETUP=1.)");
+  const ok = ensureHermes({ stderr: process.stdout });
+  if (ok) {
+    log("✓ DeepSQL Agent runtime ready. Run `deepsql login`, then `deepsql`.");
+  } else {
+    // Non-fatal: the lazy installer will retry on first `deepsql agent`.
+    log("DeepSQL Agent: runtime not pre-installed; it'll be set up on first `deepsql` run.");
+  }
+} catch (e) {
+  // Never break the npm install over agent pre-setup.
+  log(`DeepSQL Agent: skipped runtime pre-install (${e && e.message ? e.message : e}).`);
+}
+process.exit(0);

package/src/agent/bootstrap.js

@@ -7,6 +7,7 @@
 // config rewrite keeps the token/connection fresh.
 
 const fs = require("node:fs");
+const os = require("node:os");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
 const { userHome } = require("../user-home");
@@ -17,15 +18,65 @@ const AGENT_DIR = path.join(HERMES_HOME, "hermes-agent");
 const PROFILE = "deepsql";
 const PROFILE_HOME = path.join(HERMES_HOME, "profiles", PROFILE);
 
+const INSTALL_URL = "https://hermes-agent.nousresearch.com/install.sh";
+// Pin the Hermes runtime to the exact commit our bundled TUI (agent-profile/
+// tui/entry.js, HERMES_VERSION 0.17.0) was built against. This makes installs
+// reproducible AND guarantees the branded-TUI overlay's version guard matches,
+// so end users get the DeepSQL wordmark/welcome — not a "latest main" build
+// that drifts in behavior and skips our overlay. Bump alongside the bundle.
+const HERMES_COMMIT = "92d40c2553961243991376bf889d833e8326caf7";
+
+// Extra dirs the Hermes runtime + its installer rely on but a bare GUI/login
+// shell PATH (as seen by a spawned Node process) often lacks: the venv, the
+// installer's `hermes` symlink targets, and Homebrew (uv/node/git).
+function extraPathDirs() {
+  return [
+    path.join(AGENT_DIR, ".venv", "bin"),
+    path.join(HOME, ".local", "bin"),
+    "/usr/local/bin",
+    "/opt/homebrew/bin",
+    "/usr/local/lib/hermes-agent/.venv/bin",
+  ];
+}
+
+// Env for any spawn that runs (or installs) Hermes: augmented PATH so node/uv/
+// git resolve, UV_NO_CONFIG so uv ignores stray project configs, and a pinned
+// HERMES_HOME so the install/profile lands where we expect.
+function hermesEnv(extra = {}) {
+  const sep = path.delimiter;
+  const have = (process.env.PATH || "").split(sep);
+  const merged = [...extraPathDirs().filter((d) => !have.includes(d)), ...have].join(sep);
+  return { ...process.env, PATH: merged, UV_NO_CONFIG: "1", HERMES_HOME, ...extra };
+}
+
+// All the places the official installer may drop a runnable `hermes` for a
+// non-root install (venv) or an FHS/root install (/usr/local), plus the PATH.
+function findHermes() {
+  const candidates = [];
+  if (process.env.HERMES_INSTALL_DIR) {
+    candidates.push(path.join(process.env.HERMES_INSTALL_DIR, ".venv", "bin", "hermes"));
+  }
+  candidates.push(
+    path.join(AGENT_DIR, ".venv", "bin", "hermes"),
+    "/usr/local/lib/hermes-agent/.venv/bin/hermes",
+    path.join(HOME, ".local", "bin", "hermes"),
+    "/usr/local/bin/hermes"
+  );
+  for (const bin of candidates) {
+    if (!fs.existsSync(bin)) continue;
+    if (spawnSync(bin, ["--version"], { stdio: "ignore", env: hermesEnv() }).status === 0) return bin;
+  }
+  // Last resort: a `hermes` already on the (augmented) PATH.
+  if (spawnSync("hermes", ["--version"], { stdio: "ignore", env: hermesEnv() }).status === 0) return "hermes";
+  return null;
+}
+
 function hermesBin() {
-  const venv = path.join(AGENT_DIR, ".venv", "bin", "hermes");
-  return fs.existsSync(venv) ? venv : "hermes";
+  return findHermes() || path.join(AGENT_DIR, ".venv", "bin", "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;
+  return findHermes() !== null;
 }
 
 function mcpServerPath() {
@@ -42,16 +93,37 @@ function distSource() {
   return null;
 }
 
-function ensureHermes(io) {
+// Install the Hermes runtime, pinned + non-interactive, with the output teed to
+// a log so a failure surfaces a real cause instead of a vague "can't set up".
+// `quiet` (postinstall) hides the live stream; interactive first-run shows it.
+function ensureHermes(io, { quiet = false } = {}) {
   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" }
+
+  err.write("DeepSQL Agent: installing the agent runtime (first run; ~1–2 min)…\n");
+  const logFile = path.join(os.tmpdir(), `deepsql-agent-install-${process.pid}.log`);
+  // --commit pins the checkout; --skip-setup/--non-interactive avoid the
+  // wizard + any TTY prompt. tee keeps a persisted log for diagnostics.
+  const script =
+    `curl -fsSL ${INSTALL_URL} | bash -s -- ` +
+    `--skip-setup --non-interactive --commit ${HERMES_COMMIT} 2>&1 | tee ${JSON.stringify(logFile)}`;
+  const r = spawnSync("bash", ["-lc", script], {
+    stdio: quiet ? ["ignore", "ignore", "ignore"] : "inherit",
+    env: hermesEnv(),
+  });
+
+  if (hermesInstalled()) {
+    err.write("✓ DeepSQL Agent runtime installed. (Ignore any \"run hermes setup\" note above — DeepSQL configures it for you.)\n");
+    return true;
+  }
+  err.write(
+    "DeepSQL Agent: the runtime install did not complete.\n" +
+      `  Install log: ${logFile}\n` +
+      `  Exit code:   ${r.status == null ? "n/a" : r.status}\n` +
+      "  You can retry, or install Hermes manually: " +
+      `curl -fsSL ${INSTALL_URL} | bash -s -- --commit ${HERMES_COMMIT}\n`
   );
-  return r.status === 0 && hermesInstalled();
+  return false;
 }
 
 function q(s) {
@@ -92,16 +164,39 @@ display:
 `;
   fs.writeFileSync(path.join(PROFILE_HOME, "config.yaml"), config);
 
+  // OPENAI_BASE_URL/OPENAI_API_KEY are belt-and-suspenders: Hermes' first-run
+  // guard (_has_any_provider_configured) treats either as "a provider is
+  // configured", so the "run hermes setup" gate can never fire on a fresh
+  // machine even if config-load timing differs. They point at the SAME backend
+  // proxy as the model block, authed by the user's DeepSQL token.
   const env =
 `DEEPSQL_API_BASE_URL=${apiBase}
 DEEPSQL_AUTH_TOKEN=${token}
 DEEPSQL_MCP_SERVER=${mcp}
 DEEPSQL_DEFAULT_CONNECTION_ID=${conn}
+OPENAI_BASE_URL=${proxy}
+OPENAI_API_KEY=${token}
 HERMES_REVISION=deepsql-cli
 `;
   fs.writeFileSync(path.join(PROFILE_HOME, ".env"), env, { mode: 0o600 });
 }
 
+// Env for spawning the TUI: augmented PATH (so the TUI's node + the MCP
+// server's node resolve), the provider vars that defeat Hermes' first-run
+// guard regardless of config state, and HERMES_TUI_DIR pointing at our prebuilt
+// branded TUI (when the Hermes version matches) so Hermes runs it directly with
+// no esbuild — branded on the first launch.
+function launchEnv(session) {
+  const base = session.baseUrl.replace(/\/?$/, "/");
+  const extra = {
+    OPENAI_BASE_URL: base + "api/llm/v1",
+    OPENAI_API_KEY: session.token,
+  };
+  const tui = brandedTuiDir();
+  if (tui) extra.HERMES_TUI_DIR = tui;
+  return hermesEnv(extra);
+}
+
 function installProfileAssets(io) {
   const err = (io && io.stderr) || process.stderr;
   const src = distSource();
@@ -110,8 +205,19 @@ function installProfileAssets(io) {
     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 });
+  const baseEnv = hermesEnv();
+  const inst = spawnSync(
+    bin,
+    ["profile", "install", src, "--name", PROFILE, "--force", "--yes"],
+    { encoding: "utf8", env: baseEnv }
+  );
+  if (inst.status !== 0) {
+    err.write(
+      "DeepSQL Agent: provisioning the profile failed.\n" +
+        `  ${(inst.stderr || inst.stdout || "(no output)").trim().split("\n").slice(-6).join("\n  ")}\n`
+    );
+    return false;
+  }
   // Skin loads from <profile>/skins/.
   const skin = path.join(src, "skins", "deepsql.yaml");
   if (fs.existsSync(skin)) {
@@ -119,12 +225,13 @@ function installProfileAssets(io) {
     fs.mkdirSync(dst, { recursive: true });
     fs.copyFileSync(skin, path.join(dst, "deepsql.yaml"));
   }
-  // Read-only sandbox: only deepsql + skills/memory remain.
+  // Read-only sandbox: only deepsql + skills/memory remain. Non-fatal — the
+  // shipped distribution already scopes tools; this is defense in depth.
   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 } }
+    { stdio: "ignore", env: hermesEnv({ HERMES_HOME: PROFILE_HOME }) }
   );
   return fs.existsSync(PROFILE_HOME);
 }
@@ -138,8 +245,7 @@ function ensureProfile(session, io) {
 }
 
 // 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.
+// runtime layout isn't what we expect (e.g. PATH-only install).
 function installedHermesVersion() {
   try {
     const init = path.join(AGENT_DIR, "hermes_cli", "__init__.py");
@@ -150,56 +256,38 @@ function installedHermesVersion() {
   }
 }
 
-// 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.
+// The DeepSQL-branded prebuilt TUI bundle shipped in the package, as a directory
+// laid out the way Hermes' `HERMES_TUI_DIR` mechanism expects: `<dir>/dist/entry.js`.
+// When that env var points here, Hermes runs our entry.js DIRECTLY — no npm
+// install, no esbuild — so the custom DEEPSQL wordmark / welcome panel / DBA
+// placeholders show on the very FIRST launch. (The earlier copy-into-the-clone
+// approach lost every launch because Hermes "always esbuild"s the normal path.)
 //
-// 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;
+// Guarded by the Hermes version our bundle was built against: a prebuilt entry.js
+// speaks one release's TUI↔CLI protocol, so we only point at it on an exact
+// version match (the runtime is pinned to HERMES_COMMIT, so it matches on our
+// installs). On any mismatch / missing bundle we return null and let Hermes use
+// its own (stock) TUI, which still renders our skin (DeepSQL name + maroon).
+function brandedTuiDir() {
   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; }
-    })();
+    if (!fs.existsSync(path.join(tuiDir, "dist", "entry.js"))) return null;
+    const builtFor = fs.readFileSync(path.join(tuiDir, "HERMES_VERSION"), "utf8").trim();
     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;
+    if (!builtFor || !installed || builtFor !== installed) return null;
+    return tuiDir;
+  } catch {
+    return null;
   }
 }
 
 module.exports = {
   ensureHermes,
   ensureProfile,
-  ensureBrandedTui,
+  brandedTuiDir,
   hermesBin,
   hermesInstalled,
+  launchEnv,
   PROFILE,
   PROFILE_HOME,
 };

package/src/commands/agent.js

@@ -7,7 +7,7 @@
 
 const { spawn } = require("node:child_process");
 const { resolveSession } = require("./_session");
-const { ensureHermes, ensureProfile, ensureBrandedTui, hermesBin, PROFILE } = require("../agent/bootstrap");
+const { ensureHermes, ensureProfile, hermesBin, launchEnv, PROFILE } = require("../agent/bootstrap");
 
 async function run(opts, io = {}) {
   const stderr = io.stderr || process.stderr;
@@ -28,10 +28,13 @@ async function run(opts, 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
+  // Branding is delivered via HERMES_TUI_DIR in launchEnv (Hermes runs our
+  // prebuilt branded TUI directly — no esbuild), set just below.
 
   // Hand the terminal to the branded TUI (profile config sets interface=tui).
-  const child = spawn(hermesBin(), ["-p", PROFILE, "--tui"], { stdio: "inherit", env: process.env });
+  // launchEnv augments PATH (node/uv for the TUI + MCP server) and injects the
+  // provider vars that keep Hermes' first-run guard from ever firing.
+  const child = spawn(hermesBin(), ["-p", PROFILE, "--tui"], { stdio: "inherit", env: launchEnv(session) });
   return await new Promise((resolve) => {
     child.on("exit", (code) => resolve(code ?? 0));
     child.on("error", (err) => {