@deepsql/mcp 0.16.0 → 0.18.0

package/src/commands/slow-queries.js

@@ -11,6 +11,15 @@
  *   deepsql slow-queries optimize --connection <name> --query-id <id>
  *       (streams SSE; use --query-text to skip history lookup)
  *   deepsql slow-queries delete --history-id <id> [--yes]
+ *   deepsql slow-queries trends --connection <name> [--json]
+ *   deepsql slow-queries regressions --connection <name> [--min-factor <n>] [--json]
+ *   deepsql slow-queries timeline <fingerprint> --connection <name> [--json]
+ *   deepsql slow-queries customers --connection <name> [--json]
+ *   deepsql slow-queries samples <fingerprint> --connection <name> [--limit <n>] [--json]
+ *   deepsql slow-queries insights --connection <name>
+ *       [--kind hotspots|remediation|tail-risk|plan-drift|skew]
+ *       [--window LAST_7_DAYS|LAST_24_HOURS|LAST_30_DAYS] [--limit <n>] [--json]
+ *   deepsql slow-queries trigger --connection <name> [--json]
  *
  * The optimize subcommand follows the SSE protocol from
  * /slow-queries/optimize/stream — `step` events go to stderr, the final
@@ -29,12 +38,22 @@ const SUBCOMMANDS = {
   analyze: cmdAnalyze,
   optimize: cmdOptimize,
   delete: cmdDelete,
+  trends: cmdTrends,
+  regressions: cmdRegressions,
+  timeline: cmdTimeline,
+  customers: cmdCustomers,
+  samples: cmdSamples,
+  insights: cmdInsights,
+  trigger: cmdTrigger,
 };
 
 async function run(opts, io = {}) {
   const sub = opts.positional[0];
   if (!sub) {
-    throw new Error("Usage: deepsql slow-queries <latest|history|analyze|optimize|delete> ...");
+    throw new Error(
+      "Usage: deepsql slow-queries "
+      + "<latest|history|analyze|optimize|delete|trends|regressions|timeline"
+      + "|customers|samples|insights|trigger> ...");
   }
   const handler = SUBCOMMANDS[sub];
   if (!handler) throw new Error(`Unknown slow-queries subcommand: ${sub}.`);
@@ -275,6 +294,246 @@ function safeParse(text) {
   }
 }
 
+// ─── trends ──────────────────────────────────────────────────────────────
+// 30-day analytics: tracked queries, regressions, and per-query timelines.
+
+async function cmdTrends(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const queries = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}/queries`,
+    { token: session.token },
+  );
+  const items = Array.isArray(queries) ? queries : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write("No tracked queries yet. The daily analysis runs at 01:30, "
+      + "or trigger one now from the UI / API.\n");
+    return;
+  }
+  printTrendRows(stdout, items);
+}
+
+async function cmdRegressions(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const minFactor = parseNum(opts["min-factor"]) || 1.5;
+  const rows = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}/regressions?minFactor=${minFactor}`,
+    { token: session.token },
+  );
+  const items = Array.isArray(rows) ? rows : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write(`No queries regressed by ${minFactor}x or more on the latest run.\n`);
+    return;
+  }
+  printTable(stdout, [
+    { key: "fingerprint", label: "QUERY ID" },
+    { key: "factor", label: "SLOWDOWN" },
+    { key: "meanMs", label: "MEAN MS" },
+    { key: "calls", label: "CALLS" },
+    { key: "sql", label: "QUERY" },
+  ], items.map((r) => ({
+    fingerprint: trim(r.fingerprint || "", 14),
+    factor: r.regressionFactor != null ? `${r.regressionFactor.toFixed(2)}x` : "?",
+    meanMs: r.meanExecMs != null ? Math.round(r.meanExecMs).toString() : "?",
+    calls: String(r.callsDelta ?? "?"),
+    sql: trim(r.normalizedSql || "", 56),
+  })));
+}
+
+async function cmdTimeline(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const fingerprint = opts.positional[0];
+  if (!fingerprint) {
+    throw new Error("Usage: deepsql slow-queries timeline <fingerprint> --connection <name>");
+  }
+  const points = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}`
+      + `/timeline/${encodeURIComponent(fingerprint)}`,
+    { token: session.token },
+  );
+  const items = Array.isArray(points) ? points : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write("No timeline data for that query fingerprint.\n");
+    return;
+  }
+  printTable(stdout, [
+    { key: "day", label: "DAY" },
+    { key: "calls", label: "CALLS" },
+    { key: "meanMs", label: "MEAN MS" },
+    { key: "maxMs", label: "MAX MS" },
+    { key: "factor", label: "VS PREV" },
+  ], items.map((p) => ({
+    day: String(p.day || ""),
+    calls: String(p.callsDelta ?? "?"),
+    meanMs: p.meanExecMs != null ? Math.round(p.meanExecMs).toString() : "?",
+    maxMs: p.maxExecMs != null ? Math.round(p.maxExecMs).toString() : "?",
+    factor: p.regressionFactor != null ? `${p.regressionFactor.toFixed(2)}x` : "—",
+  })));
+}
+
+// ─── customers ─────────────────────────────────────────────────────────────
+
+async function cmdCustomers(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const rows = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}/customers`,
+    { token: session.token },
+  );
+  const items = Array.isArray(rows) ? rows : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write("No customer attribution data yet. Configure a tenant column in analytics settings.\n");
+    return;
+  }
+  printTable(stdout, [
+    { key: "rank",       label: "#" },
+    { key: "customer",   label: "CUSTOMER" },
+    { key: "name",       label: "NAME" },
+    { key: "queries",    label: "QUERIES" },
+    { key: "totalSec",   label: "TOTAL (s)" },
+  ], items.map((c, i) => ({
+    rank:     String(i + 1),
+    customer: trim(c.customerId || "", 22),
+    name:     trim(c.customerName || "—", 28),
+    queries:  String(c.queryCount ?? "?"),
+    totalSec: c.totalExecMs != null ? (c.totalExecMs / 1000).toFixed(1) : "?",
+  })));
+}
+
+// ─── samples ───────────────────────────────────────────────────────────────
+
+async function cmdSamples(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const fingerprint = opts.positional[0];
+  if (!fingerprint) {
+    throw new Error("Usage: deepsql slow-queries samples <fingerprint> --connection <name>");
+  }
+  const limit = parseNum(opts.limit) || 10;
+  const rows = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}`
+      + `/query/${encodeURIComponent(fingerprint)}/samples`,
+    { token: session.token },
+  );
+  const items = Array.isArray(rows) ? rows.slice(0, limit) : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write("No samples found for that fingerprint.\n");
+    return;
+  }
+  printTable(stdout, [
+    { key: "execMs",   label: "EXEC MS" },
+    { key: "examined", label: "ROWS EXAM" },
+    { key: "sent",     label: "ROWS SENT" },
+    { key: "source",   label: "SOURCE" },
+    { key: "captured", label: "CAPTURED AT" },
+    { key: "sql",      label: "SQL" },
+  ], items.map((s) => ({
+    execMs:   s.execMs != null ? String(Math.round(s.execMs)) : "?",
+    examined: String(s.rowsExamined ?? "?"),
+    sent:     String(s.rowsSent ?? "?"),
+    source:   trim(s.source || "?", 14),
+    captured: formatTime(s.capturedAt),
+    sql:      trim(s.rawSql || "", 60),
+  })));
+}
+
+// ─── insights ──────────────────────────────────────────────────────────────
+
+async function cmdInsights(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const kind = (opts.kind || "").toLowerCase();
+  const window = (opts.window || "LAST_7_DAYS").toUpperCase();
+  const limit = parseNum(opts.limit) || 10;
+  const subPath = kind && kind !== "all" ? `/${encodeURIComponent(kind)}` : "";
+  const rows = await request(
+    session.baseUrl,
+    `/slow-queries/insights/${encodeURIComponent(connectionId)}${subPath}`
+      + `?window=${encodeURIComponent(window)}&limit=${limit}`,
+    { token: session.token },
+  );
+  const items = Array.isArray(rows) ? rows : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write(`No insights for window=${window}${kind ? ` kind=${kind}` : ""}.\n`);
+    return;
+  }
+  for (let i = 0; i < items.length; i++) {
+    const ins = items[i];
+    const sev = ins.severity ? `[${ins.severity}] ` : "";
+    const title = ins.title || ins.insightType || "insight";
+    const desc = String(ins.description || ins.message || "").replace(/\s+/g, " ").trim();
+    stdout.write(`${i + 1}. ${sev}${title}\n`);
+    if (desc) stdout.write(`   ${desc}\n`);
+  }
+}
+
+// ─── trigger ───────────────────────────────────────────────────────────────
+
+async function cmdTrigger(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  stderr.write(`Triggering slow-query analysis for ${opts.connection}…\n`);
+  const result = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}/analyze-now`,
+    { method: "POST", token: session.token, timeoutMs: 300000 },
+  );
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  const runId = result?.analysisRunId || result?.runId || "?";
+  const health = result?.overallHealth || result?.health || "";
+  stdout.write(`Analysis started. Run ID: ${runId}${health ? `  Health: ${health}` : ""}\n`);
+}
+
+function printTrendRows(stdout, items) {
+  printTable(stdout, [
+    { key: "fingerprint", label: "QUERY ID" },
+    { key: "meanMs", label: "MEAN MS" },
+    { key: "calls", label: "CALLS" },
+    { key: "factor", label: "VS PREV" },
+    { key: "sql", label: "QUERY" },
+  ], items.map((q) => ({
+    fingerprint: trim(q.fingerprint || "", 14),
+    meanMs: q.meanExecMs != null ? Math.round(q.meanExecMs).toString() : "?",
+    calls: String(q.callsDelta ?? "?"),
+    factor: q.regressionFactor != null ? `${q.regressionFactor.toFixed(2)}x` : "—",
+    sql: trim(q.normalizedSql || "", 54),
+  })));
+}
+
 function printHistory(stdout, items) {
   const rows = items.map((h) => ({
     id: String(h.id ?? h.historyId ?? ""),

package/src/user-home.js

@@ -0,0 +1,29 @@
+"use strict";
+
+/**
+ * Resolves the real user's home directory, even when the CLI is run via sudo.
+ *
+ * Priority: HOME env var → SUDO_USER /etc/passwd lookup → os.homedir().
+ * The "/root" guard on HOME handles `sudo -H` (which sets HOME=/root) while
+ * still respecting `sudo -E` (which preserves the original HOME).
+ */
+
+const fs = require("node:fs");
+const os = require("node:os");
+
+function userHome() {
+  if (process.env.HOME && process.env.HOME !== "/root") return process.env.HOME;
+  if (process.env.SUDO_USER) {
+    try {
+      const passwd = fs.readFileSync("/etc/passwd", "utf8");
+      const line = passwd.split("\n").find(l => l.startsWith(process.env.SUDO_USER + ":"));
+      if (line) {
+        const home = line.split(":")[5];
+        if (home) return home;
+      }
+    } catch (_) { /* fall through */ }
+  }
+  return os.homedir();
+}
+
+module.exports = { userHome };