@carllee1983/dbcli 1.23.1 → 1.28.0

package/dist/cli.mjs

@@ -25565,7 +25565,7 @@ class AuditLockManager {
 var LOCK_RETRY_BUDGET_MS = 200, LOCK_BACKOFF_START_MS = 5, LOCK_BACKOFF_MAX_MS = 50, STALE_LOCK_MULTIPLIER = 10;
 var init_lock = () => {};
 
-// src/core/audit/rotation.ts
+// src/utils/jsonl-rotation.ts
 import { rename } from "fs/promises";
 function shouldRotate(stats, thresholds, nextLineByteLength) {
   const bytesAfter = stats.currentSizeBytes + nextLineByteLength;
@@ -25577,7 +25577,12 @@ async function rotate(currentPath, previousPath) {
     await rename(currentPath, previousPath);
   } catch {}
 }
-var init_rotation = () => {};
+var init_jsonl_rotation = () => {};
+
+// src/core/audit/rotation.ts
+var init_rotation = __esm(() => {
+  init_jsonl_rotation();
+});
 
 // src/core/audit/logger.ts
 import { appendFile, mkdir as mkdir3, readFile, stat } from "fs/promises";
@@ -81217,7 +81222,7 @@ var {
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.23.1",
+  version: "1.28.0",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {
@@ -81226,6 +81231,13 @@ var package_default = {
   bin: {
     dbcli: "./dist/cli.mjs"
   },
+  exports: {
+    ".": "./dist/cli.mjs",
+    "./core": {
+      types: "./dist/core.d.ts",
+      import: "./dist/core.mjs"
+    }
+  },
   license: "MIT",
   author: "Carl Lee",
   repository: {
@@ -81296,9 +81308,11 @@ var package_default = {
     "@inquirer/prompts": "^8.4.3",
     "@testing-library/react": "^16.3.2",
     "@types/bun": "latest",
+    "@types/pg": "^8.20.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     autoprefixer: "^10.5.0",
+    "dts-bundle-generator": "^9.5.1",
     eslint: "^10.4.0",
     "happy-dom": "^20.9.0",
     postcss: "^8.5.14",
@@ -87648,6 +87662,7 @@ function resolveSkillSource(lang) {
 var SUPPORTED_PLATFORMS = [
   "claude",
   "gemini",
+  "antigravity",
   "copilot",
   "cursor",
   "codex",
@@ -87715,6 +87730,8 @@ function getInstallPath(platform) {
       return path4.join(home, ".claude", "skills", "dbcli", "SKILL.md");
     case "gemini":
       return path4.join(home, ".gemini", "skills", "dbcli", "SKILL.md");
+    case "antigravity":
+      return path4.join(home, ".gemini", "antigravity-cli", "skills", "dbcli", "SKILL.md");
     case "codex":
       return path4.join(home, ".codex", "skills", "dbcli", "SKILL.md");
     case "copilot":
@@ -87755,7 +87772,7 @@ async function ensureDir(dirPath) {
   }
 }
 function registerSkillCommand(program2) {
-  const skill = program2.command("skill").description(t("skill.description")).option("--install <platform>", "Install to platform directory (claude, gemini, copilot, cursor, codex, windsurf)").option("--output <path>", "Write skill to file instead of stdout").addOption(new Option("--lang <lang>", "Source language for SKILL content").choices(["en", "zh-TW"]).default("en")).action(async (options) => {
+  const skill = program2.command("skill").description(t("skill.description")).option("--install <platform>", "Install to platform directory (claude, gemini, antigravity, copilot, cursor, codex, windsurf)").option("--output <path>", "Write skill to file instead of stdout").addOption(new Option("--lang <lang>", "Source language for SKILL content").choices(["en", "zh-TW"]).default("en")).action(async (options) => {
     try {
       await skillCommand(program2, options);
     } catch (error) {
@@ -90355,11 +90372,454 @@ function makeSavedQueryLoader2() {
   };
 }
 
+// src/commands/snapshot.ts
+init_adapters();
+init_config();
+import { join as join26 } from "path";
+init_validation();
+init_blacklist_validator();
+init_engine_hints();
+
+// src/core/result-snapshot/fingerprint.ts
+import { createHash as createHash2 } from "crypto";
+function sha256(input) {
+  return createHash2("sha256").update(input).digest("hex");
+}
+function isNumeric(values) {
+  return values.length > 0 && values.every((v) => typeof v === "number");
+}
+function buildColumn(name2, type, values) {
+  const nonNull = values.filter((v) => v !== null && v !== undefined);
+  const nullCount = values.length - nonNull.length;
+  const asStrings = nonNull.map((v) => String(v));
+  const distinctCount = new Set(asStrings).size;
+  const checksum = sha256(JSON.stringify([...asStrings].sort()));
+  const col = { name: name2, type, nullCount, distinctCount, checksum };
+  if (isNumeric(nonNull)) {
+    col.min = Math.min(...nonNull);
+    col.max = Math.max(...nonNull);
+    col.sum = nonNull.reduce((a, b) => a + b, 0);
+  } else if (nonNull.length > 0) {
+    const sorted = [...asStrings].sort();
+    col.min = sorted[0];
+    col.max = sorted[sorted.length - 1];
+  }
+  return col;
+}
+function buildFingerprint(result, opts) {
+  const columns = result.columnNames.map((name2, i) => buildColumn(name2, result.columnTypes?.[i] ?? "unknown", result.rows.map((r) => r[name2])));
+  for (const name2 of opts.redactedColumns ?? []) {
+    if (!columns.some((c2) => c2.name === name2)) {
+      columns.push({
+        name: name2,
+        type: "redacted",
+        nullCount: 0,
+        distinctCount: 0,
+        checksum: "",
+        redacted: true
+      });
+    }
+  }
+  const rowStrings = result.rows.map((r) => JSON.stringify(result.columnNames.map((n) => r[n]))).sort();
+  const snap = {
+    schemaVersion: 1,
+    query: opts.query ?? "",
+    engine: opts.engine ?? "postgresql",
+    createdAt: opts.createdAt ?? new Date().toISOString(),
+    rowCount: result.rowCount,
+    resultChecksum: sha256(JSON.stringify(rowStrings)),
+    columns
+  };
+  if (opts.includeRows)
+    snap.rows = result.rows;
+  return snap;
+}
+function compareAgainst(current, baseline, tolerance) {
+  const checks = [];
+  if (tolerance === 0) {
+    checks.push({
+      name: "resultChecksum",
+      expected: baseline.resultChecksum,
+      actual: current.resultChecksum,
+      pass: current.resultChecksum === baseline.resultChecksum
+    });
+    return checks;
+  }
+  const within = (a, b) => b === 0 ? a === 0 : Math.abs(a - b) / Math.abs(b) <= tolerance;
+  checks.push({
+    name: "rowCount",
+    expected: `${baseline.rowCount} \xB1${tolerance * 100}%`,
+    actual: String(current.rowCount),
+    pass: within(current.rowCount, baseline.rowCount)
+  });
+  for (const base of baseline.columns) {
+    if (base.sum === undefined)
+      continue;
+    const cur = current.columns.find((c2) => c2.name === base.name);
+    const curSum = cur?.sum;
+    checks.push({
+      name: `sum(${base.name})`,
+      expected: `${base.sum} \xB1${tolerance * 100}%`,
+      actual: String(curSum),
+      pass: curSum !== undefined && within(curSum, base.sum)
+    });
+  }
+  return checks;
+}
+
+// src/core/result-snapshot/types.ts
+class SnapshotVersionError extends Error {
+  code = "SNAPSHOT_VERSION_MISMATCH";
+  constructor(message) {
+    super(message);
+    this.name = "SnapshotVersionError";
+  }
+}
+
+// src/core/result-snapshot/serializer.ts
+async function writeSnapshot(path6, snap) {
+  await Bun.write(path6, JSON.stringify(snap, null, 2));
+}
+async function readSnapshot(path6) {
+  const file = Bun.file(path6);
+  if (!await file.exists()) {
+    const err = new Error(`Snapshot file not found: ${path6}`);
+    err.code = "SNAPSHOT_NOT_FOUND";
+    throw err;
+  }
+  const parsed = JSON.parse(await file.text());
+  if (parsed.schemaVersion !== 1) {
+    throw new SnapshotVersionError(`Unsupported snapshot schemaVersion ${parsed.schemaVersion} (expected 1)`);
+  }
+  return parsed;
+}
+
+// src/commands/snapshot.ts
+init_saved_queries();
+init_integration_helper();
+var ALLOWED_FORMATS12 = ["json", "table"];
+var SQL_SYSTEMS5 = ["postgresql", "mysql", "mariadb"];
+function requireSqlConnection9(connection) {
+  if (!SQL_SYSTEMS5.includes(connection.system)) {
+    throw new Error(`snapshot currently supports SQL engines only, got: ${connection.system}`);
+  }
+  return connection;
+}
+function pad(n) {
+  return String(n).padStart(2, "0");
+}
+function defaultSnapshotPath() {
+  const d = new Date;
+  const stamp = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+  return join26(".dbcli", "snapshots", `snap-${stamp}.json`);
+}
+var snapshotCommand = new Command().name("snapshot").description("Capture a result fingerprint (rowCount + per-column aggregates) for later comparison").argument("<query>", "SQL string or @saved-query reference").option("--out <path>", "Write snapshot to this path (default: .dbcli/snapshots/snap-<timestamp>.json)").option("--rows", "Also include full (blacklist-masked) rows in the snapshot", false).option("--stdout", "Print snapshot JSON to stdout instead of writing a file", false).option("--format <format>", "Output format for --stdout: json (default) or table", "json").option("--no-limit", "Disable the automatic query-only LIMIT").action(async (query, options, command) => {
+  try {
+    validateFormat(options.format, ALLOWED_FORMATS12, "snapshot");
+    const configPath = resolveConfigPath(command, options);
+    const config = await configModule.read(configPath);
+    if (!config.connection) {
+      console.error("Database not configured. Run: dbcli init");
+      process.exit(1);
+    }
+    let sql = query;
+    if (query.startsWith("@")) {
+      const engine = mapSystemToEngine(config.connection.system);
+      const dirs = resolveSnippetDirs(process.cwd());
+      const snippets = await loadSnippets(dirs);
+      sql = resolveByName(snippets, query.slice(1), engine).query.sqlBody;
+    }
+    const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection9(config.connection));
+    await adapter.connect();
+    try {
+      const blacklistManager = new BlacklistManager(config);
+      const blacklistValidator = new BlacklistValidator(blacklistManager);
+      const executor3 = new QueryExecutor(adapter, config.permission, blacklistValidator, config, options);
+      const result = await executor3.execute(sql, { autoLimit: options.limit !== false });
+      const table = extractTableName(sql);
+      const redactedColumns = table ? blacklistManager.getBlacklistedColumns(table) : [];
+      const snap = buildFingerprint(result, {
+        includeRows: options.rows === true,
+        redactedColumns,
+        query: sql,
+        engine: config.connection.system
+      });
+      if (options.stdout === true) {
+        console.log(JSON.stringify(snap, null, 2));
+      } else {
+        const outPath = options.out ?? defaultSnapshotPath();
+        await writeSnapshot(outPath, snap);
+        console.error(`Snapshot saved to ${outPath} (${snap.rowCount} rows, ${snap.columns.length} columns)`);
+      }
+      await writeAuditEntry(config, "snapshot", options, {
+        success: true,
+        sql
+      });
+    } finally {
+      await adapter.disconnect();
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+      if (error instanceof ConnectionError)
+        error.hints.forEach((h) => console.error(`   Hint: ${h}`));
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/assert.ts
+init_adapters();
+init_config();
+init_validation();
+init_blacklist_validator();
+init_saved_queries();
+
+// src/core/assert/grammar.ts
+class AssertExpressionError extends Error {
+  code = "ASSERT_BAD_EXPRESSION";
+  constructor(input) {
+    super(`Cannot parse --expect "${input}". Examples: "rows > 0", "value == 5000", ` + `"col:email not null", "col:id unique", "col:amount between 0 and 100", "col:age >= 18".`);
+    this.name = "AssertExpressionError";
+  }
+}
+var OP = /(>=|<=|==|!=|>|<)/;
+function parseScalar2(raw) {
+  const s = raw.trim();
+  if (/^".*"$/.test(s) || /^'.*'$/.test(s))
+    return s.slice(1, -1);
+  const n = Number(s);
+  return Number.isNaN(n) ? s : n;
+}
+function parseExpect(input) {
+  const s = input.trim();
+  const rows = s.match(new RegExp(`^rows\\s*${OP.source}\\s*(\\d+)$`));
+  if (rows)
+    return { kind: "rows", op: rows[1], value: parseInt(rows[2], 10) };
+  const value = s.match(new RegExp(`^value\\s*${OP.source}\\s*(.+)$`));
+  if (value)
+    return { kind: "value", op: value[1], value: parseScalar2(value[2]) };
+  const col = s.match(/^col:(\w+)\s+(.+)$/);
+  if (col) {
+    const column = col[1];
+    const rest = col[2].trim();
+    if (/^not\s+null$/i.test(rest))
+      return { kind: "col", column, pred: { type: "notNull" } };
+    if (/^unique$/i.test(rest))
+      return { kind: "col", column, pred: { type: "unique" } };
+    const between = rest.match(/^between\s+(-?\d+(?:\.\d+)?)\s+and\s+(-?\d+(?:\.\d+)?)$/i);
+    if (between) {
+      return {
+        kind: "col",
+        column,
+        pred: { type: "between", low: Number(between[1]), high: Number(between[2]) }
+      };
+    }
+    const cmp = rest.match(new RegExp(`^${OP.source}\\s*(.+)$`));
+    if (cmp)
+      return {
+        kind: "col",
+        column,
+        pred: { type: "cmp", op: cmp[1], value: parseScalar2(cmp[2]) }
+      };
+  }
+  throw new AssertExpressionError(input);
+}
+
+// src/core/assert/evaluator.ts
+class AssertShapeError extends Error {
+  code = "ASSERT_SHAPE_MISMATCH";
+  constructor(message) {
+    super(message);
+    this.name = "AssertShapeError";
+  }
+}
+function compare(a, op, b) {
+  switch (op) {
+    case ">":
+      return a > b;
+    case ">=":
+      return a >= b;
+    case "<":
+      return a < b;
+    case "<=":
+      return a <= b;
+    case "==":
+      return a === b;
+    case "!=":
+      return a !== b;
+  }
+}
+function firstScalar(result) {
+  if (result.columnNames.length !== 1) {
+    throw new AssertShapeError(`value assertion needs a single-column result, got ${result.columnNames.length} columns. Project to one column.`);
+  }
+  if (result.rows.length === 0)
+    return null;
+  const v = result.rows[0][result.columnNames[0]];
+  return v === null || v === undefined ? null : v;
+}
+function evaluateExpect(node, result) {
+  if (node.kind === "rows") {
+    const actual = result.rowCount;
+    return {
+      name: "rows",
+      expected: `rows ${node.op} ${node.value}`,
+      actual: String(actual),
+      pass: compare(actual, node.op, node.value)
+    };
+  }
+  if (node.kind === "value") {
+    const actual = firstScalar(result);
+    return {
+      name: "value",
+      expected: `value ${node.op} ${node.value}`,
+      actual: String(actual),
+      pass: actual !== null && compare(actual, node.op, node.value)
+    };
+  }
+  const { column, pred } = node;
+  const values = result.rows.map((r) => r[column]);
+  const nonNull = values.filter((v) => v !== null && v !== undefined);
+  if (pred.type === "notNull") {
+    const nullCount = values.length - nonNull.length;
+    return {
+      name: `col:${column} not null`,
+      expected: "0 nulls",
+      actual: `${nullCount} nulls`,
+      pass: nullCount === 0
+    };
+  }
+  if (pred.type === "unique") {
+    const distinct = new Set(nonNull.map((v) => String(v))).size;
+    return {
+      name: `col:${column} unique`,
+      expected: `${nonNull.length} distinct`,
+      actual: `${distinct} distinct`,
+      pass: distinct === nonNull.length
+    };
+  }
+  if (pred.type === "between") {
+    const bad2 = nonNull.filter((v) => typeof v !== "number" || v < pred.low || v > pred.high);
+    return {
+      name: `col:${column} between ${pred.low} and ${pred.high}`,
+      expected: "0 out of range",
+      actual: `${bad2.length} out of range`,
+      pass: bad2.length === 0
+    };
+  }
+  const bad = nonNull.filter((v) => !compare(v, pred.op, pred.value));
+  return {
+    name: `col:${column} ${pred.op} ${pred.value}`,
+    expected: "0 violations",
+    actual: `${bad.length} violations`,
+    pass: bad.length === 0
+  };
+}
+function compareVs(a, b, mode) {
+  if (mode === "rows") {
+    return {
+      name: "vs:rows",
+      expected: String(b.rowCount),
+      actual: String(a.rowCount),
+      pass: a.rowCount === b.rowCount
+    };
+  }
+  const av = firstScalar(a);
+  const bv = firstScalar(b);
+  return {
+    name: "vs:value",
+    expected: String(bv),
+    actual: String(av),
+    pass: av !== null && bv !== null && av === bv
+  };
+}
+
+// src/commands/assert.ts
+init_integration_helper();
+var ALLOWED_FORMATS13 = ["json", "table"];
+var SQL_SYSTEMS6 = ["postgresql", "mysql", "mariadb"];
+function requireSqlConnection10(connection) {
+  if (!SQL_SYSTEMS6.includes(connection.system)) {
+    throw new Error(`assert currently supports SQL engines only, got: ${connection.system}`);
+  }
+  return connection;
+}
+var assertCommand = new Command().name("assert").description("Assert an invariant on a query result (exit 1 on failure unless --no-fail)").argument("<query>", "SQL string or @saved-query reference").option("--expect <condition>", 'e.g. "rows > 0", "value == 5000", "col:email not null"').option("--vs <query>", "Second SQL/@saved query for reconciliation").option("--compare <mode>", "For --vs: rows | value (default value)", "value").option("--against <path>", "Compare current result fingerprint against a saved snapshot").option("--tolerance <pct>", "For --against: allowed relative drift, e.g. 0.01 (default 0)", (v) => parseFloat(v), 0).option("--no-fail", "Always exit 0; report pass/fail in output only").option("--format <format>", "Output format: json (default) or table", "json").action(async (query, options, command) => {
+  try {
+    validateFormat(options.format, ALLOWED_FORMATS13, "assert");
+    if (!options.expect && !options.vs && !options.against) {
+      console.error("Specify one of --expect, --vs, or --against");
+      process.exit(1);
+    }
+    const configPath = resolveConfigPath(command, options);
+    const config = await configModule.read(configPath);
+    if (!config.connection) {
+      console.error("Database not configured. Run: dbcli init");
+      process.exit(1);
+    }
+    const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection10(config.connection));
+    await adapter.connect();
+    let verdict;
+    try {
+      const blacklistManager = new BlacklistManager(config);
+      const blacklistValidator = new BlacklistValidator(blacklistManager);
+      const executor3 = new QueryExecutor(adapter, config.permission, blacklistValidator, config, options);
+      const engine = mapSystemToEngine(config.connection.system);
+      const dirs = resolveSnippetDirs(process.cwd());
+      const snippets = await loadSnippets(dirs);
+      const resolveSql = (q) => q.startsWith("@") ? resolveByName(snippets, q.slice(1), engine).query.sqlBody : q;
+      const result = await executor3.execute(resolveSql(query), { autoLimit: true });
+      const checks = [];
+      if (options.expect)
+        checks.push(evaluateExpect(parseExpect(options.expect), result));
+      if (options.vs) {
+        const other = await executor3.execute(resolveSql(options.vs), {
+          autoLimit: true
+        });
+        checks.push(compareVs(result, other, options.compare ?? "value"));
+      }
+      if (options.against) {
+        const baseline = await readSnapshot(options.against);
+        const current = buildFingerprint(result, {
+          query: resolveSql(query),
+          engine: config.connection.system
+        });
+        checks.push(...compareAgainst(current, baseline, options.tolerance));
+      }
+      verdict = { pass: checks.every((c2) => c2.pass), checks };
+      await writeAuditEntry(config, "assert", options, {
+        success: verdict.pass,
+        sql: query
+      });
+    } finally {
+      await adapter.disconnect();
+    }
+    if (options.format === "json") {
+      console.log(JSON.stringify(verdict, null, 2));
+    } else {
+      for (const c2 of verdict.checks) {
+        console.log(`${c2.pass ? "PASS" : "FAIL"}  ${c2.name}  expected=${c2.expected} actual=${c2.actual}`);
+      }
+      console.log(`
+Verdict: ${verdict.pass ? "PASS" : "FAIL"}`);
+    }
+    process.exit(verdict.pass || options.fail === false ? 0 : 1);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+      if (error instanceof ConnectionError)
+        error.hints.forEach((h) => console.error(`   Hint: ${h}`));
+    }
+    process.exit(1);
+  }
+});
+
 // src/commands/recovery.ts
 init_message_loader();
 init_validation();
 init_recovery();
-var ALLOWED_FORMATS12 = ["json", "markdown"];
+var ALLOWED_FORMATS14 = ["json", "markdown"];
 function parseCode(value) {
   const normalized = value.trim();
   if (!RECOVERY_CODES.includes(normalized)) {
@@ -90395,7 +90855,7 @@ var recoveryCommand = new Command().name("recovery").description(t("recovery.des
     const forAgent = options.forAgent === true;
     const format = forAgent ? "json" : options.format;
     const brief = forAgent || options.brief === true;
-    validateFormat(format, ALLOWED_FORMATS12, "recovery");
+    validateFormat(format, ALLOWED_FORMATS14, "recovery");
     if (options.list === true) {
       if (format === "markdown") {
         console.log(renderCodeList());
@@ -90572,7 +91032,7 @@ function looksLikeSavedEnvelope(x) {
 init_next_step();
 init_next_step_schema();
 init_validation();
-var ALLOWED_FORMATS13 = ["json", "markdown"];
+var ALLOWED_FORMATS15 = ["json", "markdown"];
 var ALLOWED_TIERS = ["readonly-cmd", "write-cmd"];
 
 class RecoverCliError extends Error {
@@ -90724,7 +91184,7 @@ var recoverCommand = new Command().name("recover").description("Inspect or apply
     }
     const explicitFormat = options.format;
     const format = explicitFormat ?? (options.apply === true || options.next === true ? "json" : "markdown");
-    validateFormat(format, ALLOWED_FORMATS13, "recover");
+    validateFormat(format, ALLOWED_FORMATS15, "recover");
     let allowWrite = "none";
     if (options.next !== true) {
       const allowWriteRaw = options.allowWrite;
@@ -90791,14 +91251,14 @@ var recoverCommand = new Command().name("recover").description("Inspect or apply
 
 // src/commands/audit.ts
 import { rm as rm3, stat as stat7 } from "fs/promises";
-import { join as join26 } from "path";
+import { join as join27 } from "path";
 init_message_loader();
 init_validation();
 init_config();
 init_config_binding();
 init_reader();
 init_integration_helper();
-var ALLOWED_FORMATS14 = ["table", "json"];
+var ALLOWED_FORMATS16 = ["table", "json"];
 var DEFAULT_TAIL_N = 10;
 var MAX_TAIL_N = 1e4;
 var SHORT_ID_LEN = 8;
@@ -90807,8 +91267,8 @@ var PREFIX_MIN = 4;
 async function resolveAuditPaths(configPath, config) {
   const storagePath = await resolveConfigStoragePath(configPath);
   const connName = config.effectiveConnectionName || getGlobalConnectionName() || "default";
-  const auditDir = join26(storagePath, ".dbcli", "audit");
-  const auditFile = join26(auditDir, `${connName}.jsonl`);
+  const auditDir = join27(storagePath, ".dbcli", "audit");
+  const auditFile = join27(auditDir, `${connName}.jsonl`);
   return { auditDir, connectionName: connName, auditFile };
 }
 function isAuditDisabled(config) {
@@ -90992,13 +91452,13 @@ async function statAuditFile(file) {
   }
 }
 var auditCommand = new Command("audit").description(t("audit.description"));
-auditCommand.command("tail").description(t("audit.tail.description")).option("--n <number>", `Number of recent entries to show (1..${MAX_TAIL_N})`, String(DEFAULT_TAIL_N)).option("--all", "Merge entries across all connections", false).option("--format <format>", `Output format: ${ALLOWED_FORMATS14.join(" | ")} (default: table)`, "table").option("--brief", "Trim each entry to ts/command/target/success", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (options, command) => {
+auditCommand.command("tail").description(t("audit.tail.description")).option("--n <number>", `Number of recent entries to show (1..${MAX_TAIL_N})`, String(DEFAULT_TAIL_N)).option("--all", "Merge entries across all connections", false).option("--format <format>", `Output format: ${ALLOWED_FORMATS16.join(" | ")} (default: table)`, "table").option("--brief", "Trim each entry to ts/command/target/success", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (options, command) => {
   const forAgent = options.forAgent === true;
   const format = forAgent ? "json" : options.format;
   const briefSource = command.getOptionValueSource("brief");
   const briefExplicit = briefSource !== undefined && briefSource !== "default";
   const brief = briefExplicit ? options.brief === true : forAgent;
-  validateFormat(format, ALLOWED_FORMATS14, "audit tail");
+  validateFormat(format, ALLOWED_FORMATS16, "audit tail");
   const n = parseTailN(options.n);
   const configPath = resolveConfigPath(command, options);
   const config = await configModule.read(configPath);
@@ -91041,7 +91501,7 @@ auditCommand.command("tail").description(t("audit.tail.description")).option("--
     console.log(renderTailTable(tail));
   }
 });
-auditCommand.command("show [id]").description(t("audit.show.description")).option("--all", "Search across all connections", false).option("--recovery-ref <ref>", "Look up by entry.recovery_ref (exact match)").option("--format <format>", `Output format: ${ALLOWED_FORMATS14.join(" | ")} (default: table)`, "table").option("--brief", "Trim metadata + redacted_query", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (id, options, command) => {
+auditCommand.command("show [id]").description(t("audit.show.description")).option("--all", "Search across all connections", false).option("--recovery-ref <ref>", "Look up by entry.recovery_ref (exact match)").option("--format <format>", `Output format: ${ALLOWED_FORMATS16.join(" | ")} (default: table)`, "table").option("--brief", "Trim metadata + redacted_query", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (id, options, command) => {
   if (id && options.recoveryRef) {
     console.error(t("audit.show_mutex_violation"));
     process.exit(1);
@@ -91055,7 +91515,7 @@ auditCommand.command("show [id]").description(t("audit.show.description")).optio
   const briefSource = command.getOptionValueSource("brief");
   const briefExplicit = briefSource !== undefined && briefSource !== "default";
   const brief = briefExplicit ? options.brief === true : forAgent;
-  validateFormat(format, ALLOWED_FORMATS14, "audit show");
+  validateFormat(format, ALLOWED_FORMATS16, "audit show");
   const configPath = resolveConfigPath(command, options);
   const config = await configModule.read(configPath);
   if (isAuditDisabled(config))
@@ -91197,13 +91657,13 @@ auditCommand.command("clear").description(t("audit.clear.description")).option("
 `);
   process.exit(0);
 });
-auditCommand.command("health").description(t("audit.health.description")).option("--format <format>", `Output format: ${ALLOWED_FORMATS14.join(" | ")} (default: table)`, "table").option("--brief", "Trim to enabled / lastWrite / rotationUsage", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (options, command) => {
+auditCommand.command("health").description(t("audit.health.description")).option("--format <format>", `Output format: ${ALLOWED_FORMATS16.join(" | ")} (default: table)`, "table").option("--brief", "Trim to enabled / lastWrite / rotationUsage", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (options, command) => {
   const forAgent = options.forAgent === true;
   const format = forAgent ? "json" : options.format;
   const briefSource = command.getOptionValueSource("brief");
   const briefExplicit = briefSource !== undefined && briefSource !== "default";
   const brief = briefExplicit ? options.brief === true : forAgent;
-  validateFormat(format, ALLOWED_FORMATS14, "audit health");
+  validateFormat(format, ALLOWED_FORMATS16, "audit health");
   const configPath = resolveConfigPath(command, options);
   const config = await configModule.read(configPath);
   const logger = await getAuditLogger(config, configPath);
@@ -91235,15 +91695,15 @@ init_config_binding();
 init_schema_path();
 init_config();
 init_integration_helper();
-import { join as join27 } from "path";
+import { join as join28 } from "path";
 import { resolveSrv as resolveSrv2 } from "dns/promises";
-function requireSqlConnection9(connection) {
+function requireSqlConnection11(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
   }
   return connection;
 }
-var ALLOWED_FORMATS15 = ["text", "json"];
+var ALLOWED_FORMATS17 = ["text", "json"];
 var SENSITIVE_PATTERNS = [
   "password",
   "passwd",
@@ -91315,7 +91775,7 @@ var runDoctorChecks = {
     }
   },
   async checkConfigExists(configPath, existsFn) {
-    const exists = existsFn ? await existsFn(configPath) : await Bun.file(configPath).exists() || await Bun.file(join27(configPath, "config.json")).exists();
+    const exists = existsFn ? await existsFn(configPath) : await Bun.file(configPath).exists() || await Bun.file(join28(configPath, "config.json")).exists();
     return {
       group: "Configuration",
       label: "Config exists",
@@ -91472,7 +91932,7 @@ var runDoctorChecks = {
   async checkV2Config(configPath) {
     const results = [];
     const storagePath = await resolveConfigStoragePath(configPath);
-    const configFile = Bun.file(join27(storagePath, "config.json"));
+    const configFile = Bun.file(join28(storagePath, "config.json"));
     if (!await configFile.exists())
       return results;
     let raw;
@@ -91512,7 +91972,7 @@ var runDoctorChecks = {
     }
     for (const [name2, conn] of Object.entries(config.connections)) {
       if (conn.envFile) {
-        const envPath = join27(storagePath, conn.envFile);
+        const envPath = join28(storagePath, conn.envFile);
         const exists = await Bun.file(envPath).exists();
         results.push({
           group: "Configuration",
@@ -91657,7 +92117,7 @@ async function collectElasticsearchDoctorResults(config) {
   return results;
 }
 var doctorCommand = new Command("doctor").description("Run diagnostic checks on dbcli configuration, environment, and connection").option("--format <type>", "Output format: text, json", "text").action(async (options) => {
-  validateFormat(options.format, ALLOWED_FORMATS15, "doctor");
+  validateFormat(options.format, ALLOWED_FORMATS17, "doctor");
   const logger = getLogger();
   const results = [];
   const configPath = resolveConfigPath(doctorCommand);
@@ -91703,7 +92163,7 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
             blacklistedColumns
           }));
         } else {
-          const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection9(config.connection));
+          const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection11(config.connection));
           await adapter.connect();
           results.push({
             group: "Connection & Data",
@@ -91731,7 +92191,7 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
           }
           try {
             const schemaConnName = await getSchemaIsolationConnectionName(configPath);
-            const indexPath = join27(resolveSchemaPath(storagePath, schemaConnName), "index.json");
+            const indexPath = join28(resolveSchemaPath(storagePath, schemaConnName), "index.json");
             const indexFile = Bun.file(indexPath);
             let indexParsed = null;
             if (await indexFile.exists()) {
@@ -91785,7 +92245,7 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
 
 // src/commands/completion.ts
 init_colors();
-import { join as join28 } from "path";
+import { join as join29 } from "path";
 import { homedir as homedir3 } from "os";
 function extractCommands(program2) {
   return program2.commands.map((cmd) => ({
@@ -91887,11 +92347,11 @@ function getInstallPath2(shell) {
   const home = homedir3();
   switch (shell) {
     case "bash":
-      return join28(home, ".bashrc");
+      return join29(home, ".bashrc");
     case "zsh":
-      return join28(home, ".zshrc");
+      return join29(home, ".zshrc");
     case "fish":
-      return join28(home, ".config", "fish", "completions", "dbcli.fish");
+      return join29(home, ".config", "fish", "completions", "dbcli.fish");
     default:
       throw new Error(`Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
   }
@@ -91911,7 +92371,7 @@ var MARKER_END = "# <<< dbcli completion <<<";
 async function installCompletion(shell, script) {
   const targetPath = getInstallPath2(shell);
   if (shell === "fish") {
-    const dir = join28(homedir3(), ".config", "fish", "completions");
+    const dir = join29(homedir3(), ".config", "fish", "completions");
     await Bun.$`mkdir -p ${dir}`.quiet();
     await Bun.file(targetPath).write(script);
     console.log(colors.success(`\u2713 Fish completion installed to ${targetPath}`));
@@ -92144,7 +92604,7 @@ ${t("upgrade.failed")}`));
 init_config();
 init_adapters();
 import { createInterface as createInterface3 } from "readline";
-import { join as join29 } from "path";
+import { join as join30 } from "path";
 import { homedir as homedir4 } from "os";
 
 // src/core/repl/types.ts
@@ -93066,13 +93526,13 @@ async function runEsShell(configPath) {
 }
 
 // src/commands/shell.ts
-function requireSqlConnection10(connection) {
+function requireSqlConnection12(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
   }
   return connection;
 }
-var HISTORY_PATH = join29(homedir4(), ".dbcli_history");
+var HISTORY_PATH = join30(homedir4(), ".dbcli_history");
 var MONGO_COMPLETION_EAGER_THRESHOLD = 20;
 async function populateMongoColumns(mongoAdapter, collectionNames, threshold = MONGO_COMPLETION_EAGER_THRESHOLD) {
   const columnsByTable = {};
@@ -93109,7 +93569,7 @@ async function runShell(options, configPath) {
   const connectionOpts = config.connection;
   const mongoInner = isMongoDB ? AdapterFactory.createMongoDBAdapter(connectionOpts) : null;
   const redisInner = isRedis ? AdapterFactory.createRedisAdapter(connectionOpts, config.blacklist?.tables ?? [], config.redis?.mask ?? []) : null;
-  const adapter = isMongoDB ? new MongoShellAdapter(mongoInner) : isRedis ? new RedisShellAdapter(redisInner) : AdapterFactory.createSqlAdapter(requireSqlConnection10(connectionOpts));
+  const adapter = isMongoDB ? new MongoShellAdapter(mongoInner) : isRedis ? new RedisShellAdapter(redisInner) : AdapterFactory.createSqlAdapter(requireSqlConnection12(connectionOpts));
   try {
     await adapter.connect();
   } catch (error) {
@@ -93836,7 +94296,7 @@ class DDLExecutor {
   }
 }
 // src/commands/migrate.ts
-function requireSqlConnection11(connection) {
+function requireSqlConnection13(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
   }
@@ -93860,7 +94320,7 @@ async function runDDL(operation, opts) {
     console.error("\u6B64\u547D\u4EE4\u76EE\u524D\u4E0D\u652F\u63F4 Elasticsearch\uFF1B\u5982\u9700\u5EFA\u7ACB\u7D22\u5F15\u6216\u8ABF\u6574 mapping\uFF0C\u8ACB\u6539\u7528\u5916\u90E8\u5DE5\u5177");
     process.exit(1);
   }
-  const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection11(config.connection));
+  const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection13(config.connection));
   const isDryRun = !opts.execute;
   if (!isDryRun) {
     await adapter.connect();
@@ -94071,7 +94531,7 @@ init_config();
 init_errors();
 init_message_loader();
 init_config_binding();
-import { join as join30 } from "path";
+import { join as join31 } from "path";
 async function switchDefault(configPath, name2, config) {
   if (!config.connections[name2]) {
     const available = Object.keys(config.connections).join(", ");
@@ -94094,7 +94554,7 @@ function listConnectionsForDisplay(config) {
 }
 async function ensureV2Config(configPath) {
   const storagePath = await resolveConfigStoragePath(configPath);
-  const configFile = Bun.file(join30(storagePath, "config.json"));
+  const configFile = Bun.file(join31(storagePath, "config.json"));
   const legacyFile = Bun.file(configPath);
   if (!await configFile.exists() && !await legacyFile.exists()) {
     throw new ConfigError(t("init.config_not_found"));
@@ -94156,14 +94616,1214 @@ var useCommand = new Command("use").description("Switch or display the default d
   }
 });
 
+// src/commands/proxy.ts
+init_config();
+init_validation();
+import { join as join32 } from "path";
+
+// src/proxy/relay.ts
+class TcpRelay {
+  clientBytes = 0;
+  serverBytes = 0;
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  fromClient(bytes) {
+    this.opts.writeToUpstream(bytes);
+    this.clientBytes += bytes.length;
+    this.feed("client_to_server", bytes);
+  }
+  fromUpstream(bytes) {
+    this.opts.writeToClient(bytes);
+    this.serverBytes += bytes.length;
+    this.feed("server_to_client", bytes);
+  }
+  feed(direction, bytes) {
+    try {
+      this.opts.analyzer.onData(direction, bytes);
+    } catch (err) {
+      this.opts.onSignal({
+        kind: "parse_error",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+}
+
+// src/proxy/events.ts
+init_jsonl_rotation();
+import { appendFile as appendFile2, mkdir as mkdir10, readFile as readFile6, stat as stat8 } from "fs/promises";
+import { dirname as dirname11 } from "path";
+
+// src/proxy/sql-metadata.ts
+var KNOWN_KEYWORDS = [
+  "SELECT",
+  "INSERT",
+  "UPDATE",
+  "DELETE",
+  "CREATE",
+  "ALTER",
+  "DROP",
+  "TRUNCATE",
+  "BEGIN",
+  "COMMIT",
+  "ROLLBACK",
+  "SET",
+  "SHOW",
+  "USE"
+];
+var KNOWN = new Set(KNOWN_KEYWORDS);
+function detectStatement(sql) {
+  const m = sql.trim().match(/^([a-zA-Z]+)/);
+  if (!m || !m[1])
+    return "OTHER";
+  const kw = m[1].toUpperCase();
+  return KNOWN.has(kw) ? kw : "OTHER";
+}
+var TABLE_RE = /\b(?:FROM|JOIN|INTO|UPDATE)\s+["'`]?([A-Za-z_]\w*)["'`]?(?:\.["'`]?([A-Za-z_]\w*)["'`]?)?/gi;
+function extractTables(sql) {
+  const seen = new Set;
+  for (const m of sql.matchAll(TABLE_RE)) {
+    const name2 = m[2] ?? m[1];
+    if (name2)
+      seen.add(name2);
+  }
+  return [...seen];
+}
+function redactLiterals(sql) {
+  const noStrings = sql.replace(/'(?:[^']|'')*'/g, "?");
+  return noStrings.replace(/\b\d+(?:\.\d+)?\b/g, "?");
+}
+
+// src/proxy/events.ts
+var PROXY_EVENT_VERSION = 1;
+function hasSql(e) {
+  return e.type === "query_observed" || e.type === "query_completed" || e.type === "query_errored";
+}
+function applyRedaction(event, mode) {
+  if (mode === "none" || !hasSql(event))
+    return event;
+  return { ...event, sql: redactLiterals(event.sql) };
+}
+var DEFAULT_ROTATION = {
+  maxBytes: 50 * 1024 * 1024,
+  maxEntries: 200000
+};
+
+class EventWriter {
+  path;
+  previousPath;
+  redact;
+  maxBytes;
+  maxEntries;
+  dirEnsured = false;
+  initialized = false;
+  currentSizeBytes = 0;
+  currentEntryCount = 0;
+  writeChain = Promise.resolve();
+  constructor(opts) {
+    this.path = opts.path;
+    this.previousPath = `${opts.path}.1`;
+    this.redact = opts.redact;
+    this.maxBytes = opts.rotation?.maxBytes ?? DEFAULT_ROTATION.maxBytes;
+    this.maxEntries = opts.rotation?.maxEntries ?? DEFAULT_ROTATION.maxEntries;
+  }
+  write(event) {
+    const op = this.writeChain.then(() => this.writeInternal(event));
+    this.writeChain = op.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return op;
+  }
+  async writeInternal(event) {
+    if (!this.dirEnsured) {
+      await mkdir10(dirname11(this.path), { recursive: true });
+      this.dirEnsured = true;
+    }
+    if (!this.initialized) {
+      await this.syncCountersFromDisk();
+      this.initialized = true;
+    }
+    const redacted = applyRedaction(event, this.redact);
+    const line = JSON.stringify(redacted) + `
+`;
+    const lineBytes = Buffer.byteLength(line, "utf8");
+    if (shouldRotate({ currentSizeBytes: this.currentSizeBytes, currentEntryCount: this.currentEntryCount }, { maxBytes: this.maxBytes, maxEntries: this.maxEntries }, lineBytes)) {
+      await rotate(this.path, this.previousPath);
+      this.currentSizeBytes = 0;
+      this.currentEntryCount = 0;
+    }
+    await appendFile2(this.path, line, { encoding: "utf8" });
+    this.currentSizeBytes += lineBytes;
+    this.currentEntryCount += 1;
+  }
+  async syncCountersFromDisk() {
+    try {
+      const s = await stat8(this.path);
+      this.currentSizeBytes = s.size;
+      const raw = await readFile6(this.path, "utf8");
+      this.currentEntryCount = raw.split(`
+`).filter(Boolean).length;
+    } catch {
+      this.currentSizeBytes = 0;
+      this.currentEntryCount = 0;
+    }
+  }
+}
+
+// src/proxy/session.ts
+class ProxySession {
+  o;
+  active = null;
+  queryCounter = 0;
+  startedAt = 0;
+  clientBytesAtBoundary = 0;
+  pending = Promise.resolve();
+  constructor(opts) {
+    this.o = opts;
+  }
+  enqueue(event) {
+    this.pending = this.pending.then(() => this.o.writeEvent(event)).catch((err) => {
+      this.o.warn(`event write failed: ${err instanceof Error ? err.message : String(err)}`);
+    });
+  }
+  async start() {
+    this.startedAt = this.o.now();
+    this.enqueue({
+      version: PROXY_EVENT_VERSION,
+      type: "session_started",
+      timestamp: new Date().toISOString(),
+      engine: this.o.engine,
+      sessionId: this.o.sessionId,
+      client: this.o.client,
+      target: this.o.target
+    });
+    await this.flush();
+  }
+  onSignal(signal) {
+    switch (signal.kind) {
+      case "query":
+        this.beginQuery(signal.sql, signal.tags ?? []);
+        break;
+      case "query_end":
+        this.completeQuery(signal.rowCount ?? null);
+        break;
+      case "error":
+        this.errorQuery(signal.code, signal.message);
+        break;
+      case "tag":
+        if (this.active && !this.active.tags.includes(signal.tag)) {
+          this.active.tags.push(signal.tag);
+        }
+        break;
+      case "parse_error":
+        this.enqueue({
+          version: PROXY_EVENT_VERSION,
+          type: "parse_error",
+          timestamp: new Date().toISOString(),
+          engine: this.o.engine,
+          sessionId: this.o.sessionId,
+          client: this.o.client,
+          target: this.o.target,
+          message: signal.message,
+          tags: []
+        });
+        break;
+    }
+  }
+  beginQuery(sql, tags) {
+    const bytes = this.o.getBytes();
+    this.queryCounter += 1;
+    this.active = {
+      queryId: `qry_${this.o.sessionId}_${this.queryCounter}`,
+      sql,
+      startedAt: this.o.now(),
+      clientBytesAtStart: this.clientBytesAtBoundary,
+      serverBytesAtStart: bytes.serverBytes,
+      tags: [...tags]
+    };
+    this.enqueue({
+      version: PROXY_EVENT_VERSION,
+      type: "query_observed",
+      timestamp: new Date().toISOString(),
+      engine: this.o.engine,
+      sessionId: this.o.sessionId,
+      queryId: this.active.queryId,
+      client: this.o.client,
+      target: this.o.target,
+      sql,
+      statement: detectStatement(sql),
+      tables: extractTables(sql),
+      tags: [...this.active.tags]
+    });
+  }
+  completeQuery(rowCount) {
+    const q3 = this.active;
+    if (!q3)
+      return;
+    const bytes = this.o.getBytes();
+    const durationMs = this.o.now() - q3.startedAt;
+    const requestBytes = bytes.clientBytes - q3.clientBytesAtStart;
+    const responseBytes = bytes.serverBytes - q3.serverBytesAtStart;
+    const slow = durationMs >= this.o.slowMs;
+    this.enqueue({
+      version: PROXY_EVENT_VERSION,
+      type: "query_completed",
+      timestamp: new Date().toISOString(),
+      engine: this.o.engine,
+      sessionId: this.o.sessionId,
+      queryId: q3.queryId,
+      client: this.o.client,
+      target: this.o.target,
+      sql: q3.sql,
+      statement: detectStatement(q3.sql),
+      tables: extractTables(q3.sql),
+      durationMs,
+      requestBytes,
+      responseBytes,
+      rowCount,
+      slow,
+      error: null,
+      tags: [...q3.tags]
+    });
+    if (slow) {
+      this.o.warn(`slow query (${durationMs}ms): ${q3.sql.slice(0, 80)}`);
+    }
+    this.clientBytesAtBoundary = bytes.clientBytes;
+    this.active = null;
+  }
+  errorQuery(code, message) {
+    const q3 = this.active;
+    const bytes = this.o.getBytes();
+    const startedAt = q3?.startedAt ?? this.o.now();
+    this.enqueue({
+      version: PROXY_EVENT_VERSION,
+      type: "query_errored",
+      timestamp: new Date().toISOString(),
+      engine: this.o.engine,
+      sessionId: this.o.sessionId,
+      queryId: q3?.queryId ?? `qry_${this.o.sessionId}_err_${++this.queryCounter}`,
+      client: this.o.client,
+      target: this.o.target,
+      sql: q3?.sql ?? "",
+      statement: detectStatement(q3?.sql ?? ""),
+      tables: extractTables(q3?.sql ?? ""),
+      durationMs: this.o.now() - startedAt,
+      requestBytes: q3 ? bytes.clientBytes - q3.clientBytesAtStart : 0,
+      responseBytes: q3 ? bytes.serverBytes - q3.serverBytesAtStart : 0,
+      rowCount: null,
+      error: { code, message },
+      tags: q3 ? [...q3.tags] : []
+    });
+    this.clientBytesAtBoundary = bytes.clientBytes;
+    this.active = null;
+  }
+  async end(reason) {
+    const bytes = this.o.getBytes();
+    this.enqueue({
+      version: PROXY_EVENT_VERSION,
+      type: "session_ended",
+      timestamp: new Date().toISOString(),
+      engine: this.o.engine,
+      sessionId: this.o.sessionId,
+      client: this.o.client,
+      target: this.o.target,
+      durationMs: this.o.now() - this.startedAt,
+      requestBytes: bytes.clientBytes,
+      responseBytes: bytes.serverBytes,
+      reason
+    });
+    await this.flush();
+  }
+  async flush() {
+    await this.pending;
+  }
+}
+
+// src/proxy/analyzers/types.ts
+var UTF8 = new TextDecoder;
+
+class FrameBuffer {
+  buf = new Uint8Array(0);
+  get length() {
+    return this.buf.length;
+  }
+  push(chunk) {
+    if (this.buf.length === 0) {
+      this.buf = chunk.slice();
+      return;
+    }
+    const next = new Uint8Array(this.buf.length + chunk.length);
+    next.set(this.buf, 0);
+    next.set(chunk, this.buf.length);
+    this.buf = next;
+  }
+  peek(n) {
+    return this.buf.subarray(0, Math.min(n, this.buf.length));
+  }
+  byteAt(offset) {
+    return this.buf[offset];
+  }
+  consume(n) {
+    this.buf = this.buf.subarray(Math.min(n, this.buf.length));
+  }
+  readUInt24LE(offset) {
+    const b0 = this.buf[offset] ?? 0;
+    const b1 = this.buf[offset + 1] ?? 0;
+    const b2 = this.buf[offset + 2] ?? 0;
+    return b0 | b1 << 8 | b2 << 16;
+  }
+  readUInt16LE(offset) {
+    const b0 = this.buf[offset] ?? 0;
+    const b1 = this.buf[offset + 1] ?? 0;
+    return b0 | b1 << 8;
+  }
+  readUInt32BE(offset) {
+    const b0 = this.buf[offset] ?? 0;
+    const b1 = this.buf[offset + 1] ?? 0;
+    const b2 = this.buf[offset + 2] ?? 0;
+    const b3 = this.buf[offset + 3] ?? 0;
+    return (b0 << 24 >>> 0) + (b1 << 16) + (b2 << 8) + b3;
+  }
+  text(start, end) {
+    return UTF8.decode(this.buf.subarray(start, end));
+  }
+}
+
+// src/proxy/analyzers/mysql.ts
+var COM_QUERY = 3;
+var COM_STMT_PREPARE = 22;
+var COM_STMT_EXECUTE = 23;
+var HEADER = 4;
+function createMysqlAnalyzer(deps) {
+  const clientBuf = new FrameBuffer;
+  const serverBuf = new FrameBuffer;
+  let awaitingResponse = false;
+  function handleClientPacket(payloadStart, payloadLen) {
+    const seqId = clientBuf.byteAt(payloadStart - 1);
+    if (seqId !== 0)
+      return;
+    const cmd = clientBuf.byteAt(payloadStart);
+    if (cmd === undefined)
+      return;
+    if (cmd === COM_QUERY) {
+      const sql = clientBuf.text(payloadStart + 1, payloadStart + payloadLen);
+      deps.emit({ kind: "query", sql });
+      awaitingResponse = true;
+    } else if (cmd === COM_STMT_PREPARE) {
+      const sql = clientBuf.text(payloadStart + 1, payloadStart + payloadLen);
+      deps.emit({ kind: "query", sql, tags: ["prepared_statement"] });
+      awaitingResponse = true;
+    } else if (cmd === COM_STMT_EXECUTE) {
+      deps.emit({ kind: "tag", tag: "prepared_statement" });
+      awaitingResponse = true;
+    }
+  }
+  function handleServerPacket(payloadStart, payloadLen) {
+    if (!awaitingResponse)
+      return;
+    const first = serverBuf.byteAt(payloadStart);
+    if (first === undefined)
+      return;
+    if (first === 255) {
+      const code = serverBuf.readUInt16LE(payloadStart + 1);
+      let msgStart = payloadStart + 3;
+      if (serverBuf.byteAt(msgStart) === 35) {
+        msgStart += 6;
+      }
+      const message = serverBuf.text(msgStart, payloadStart + payloadLen);
+      deps.emit({ kind: "error", code: String(code), message });
+      awaitingResponse = false;
+    } else if (first === 0) {
+      deps.emit({ kind: "query_end", rowCount: null });
+      awaitingResponse = false;
+    } else {
+      deps.emit({ kind: "tag", tag: "parse_partial" });
+      deps.emit({ kind: "query_end", rowCount: null });
+      awaitingResponse = false;
+    }
+  }
+  function drain(buf, onPacket) {
+    while (buf.length >= HEADER) {
+      const payloadLen = buf.readUInt24LE(0);
+      if (buf.length < HEADER + payloadLen)
+        break;
+      onPacket(HEADER, payloadLen);
+      buf.consume(HEADER + payloadLen);
+    }
+  }
+  return {
+    onData(direction, chunk) {
+      try {
+        if (direction === "client_to_server") {
+          clientBuf.push(chunk);
+          drain(clientBuf, handleClientPacket);
+        } else {
+          serverBuf.push(chunk);
+          drain(serverBuf, handleServerPacket);
+        }
+      } catch (err) {
+        deps.emit({
+          kind: "parse_error",
+          message: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+  };
+}
+
+// src/proxy/analyzers/postgresql.ts
+function rowCountFromTag(tag) {
+  const parts = tag.trim().split(/\s+/);
+  const last = parts[parts.length - 1];
+  if (last === undefined)
+    return null;
+  const n = Number(last);
+  return Number.isInteger(n) ? n : null;
+}
+var MAX_STARTUP_LEN = 1e4;
+function createPostgresAnalyzer(deps) {
+  const clientBuf = new FrameBuffer;
+  const serverBuf = new FrameBuffer;
+  let startupSeen = false;
+  let awaitingResponse = false;
+  function cStringEnd(buf, start, end) {
+    let i = start;
+    while (i < end && buf.byteAt(i) !== 0)
+      i++;
+    return i;
+  }
+  function readCString(buf, start, end) {
+    return buf.text(start, cStringEnd(buf, start, end));
+  }
+  function handleClientMessage(type, bodyStart, bodyEnd) {
+    const t2 = String.fromCharCode(type);
+    if (t2 === "Q") {
+      const sql = readCString(clientBuf, bodyStart, bodyEnd);
+      deps.emit({ kind: "query", sql });
+      awaitingResponse = true;
+    } else if (t2 === "P" || t2 === "B" || t2 === "E" || t2 === "S" || t2 === "D") {
+      deps.emit({ kind: "tag", tag: "extended_protocol" });
+      if (t2 === "P") {
+        const nameEnd = cStringEnd(clientBuf, bodyStart, bodyEnd) + 1;
+        const sql = readCString(clientBuf, nameEnd, bodyEnd);
+        if (sql)
+          deps.emit({ kind: "query", sql, tags: ["extended_protocol"] });
+        awaitingResponse = true;
+      }
+    }
+  }
+  function handleServerMessage(type, bodyStart, bodyEnd) {
+    if (!awaitingResponse)
+      return;
+    const t2 = String.fromCharCode(type);
+    if (t2 === "E") {
+      let code = null;
+      let message = "";
+      let i = bodyStart;
+      while (i < bodyEnd) {
+        const fieldType = serverBuf.byteAt(i);
+        if (fieldType === undefined || fieldType === 0)
+          break;
+        i += 1;
+        const valEnd = cStringEnd(serverBuf, i, bodyEnd);
+        const value = serverBuf.text(i, valEnd);
+        i = valEnd + 1;
+        if (fieldType === 67)
+          code = value;
+        else if (fieldType === 77)
+          message = value;
+      }
+      deps.emit({ kind: "error", code, message });
+      awaitingResponse = false;
+    } else if (t2 === "C") {
+      const tag = readCString(serverBuf, bodyStart, bodyEnd);
+      deps.emit({ kind: "query_end", rowCount: rowCountFromTag(tag) });
+      awaitingResponse = false;
+    }
+  }
+  function drain(buf, isClient, onMessage) {
+    if (isClient && !startupSeen) {
+      if (buf.length < 4)
+        return;
+      const len = buf.readUInt32BE(0);
+      if (len >= 4 && len <= buf.length && len <= MAX_STARTUP_LEN) {
+        startupSeen = true;
+        buf.consume(len);
+      } else {
+        startupSeen = true;
+      }
+    }
+    while (buf.length >= 5) {
+      const type = buf.byteAt(0);
+      const len = buf.readUInt32BE(1);
+      const total = 1 + len;
+      if (buf.length < total)
+        break;
+      onMessage(type, 5, total);
+      buf.consume(total);
+    }
+  }
+  return {
+    onData(direction, chunk) {
+      try {
+        if (direction === "client_to_server") {
+          clientBuf.push(chunk);
+          drain(clientBuf, true, handleClientMessage);
+        } else {
+          serverBuf.push(chunk);
+          drain(serverBuf, false, handleServerMessage);
+        }
+      } catch (err) {
+        deps.emit({
+          kind: "parse_error",
+          message: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+  };
+}
+
+// src/proxy/server.ts
+function makeAnalyzer(engine, deps) {
+  return engine === "postgresql" ? createPostgresAnalyzer(deps) : createMysqlAnalyzer(deps);
+}
+
+class ProxyServer {
+  o;
+  writer;
+  listener = null;
+  sessionCounter = 0;
+  writeFailed = false;
+  constructor(opts) {
+    this.o = opts;
+    this.writer = new EventWriter({ path: opts.eventsPath, redact: opts.redact });
+  }
+  get port() {
+    return this.listener?.port ?? null;
+  }
+  async start() {
+    await this.writer.write({
+      version: PROXY_EVENT_VERSION,
+      type: "proxy_started",
+      timestamp: new Date().toISOString(),
+      engine: this.o.engine,
+      sessionId: "pxy_root",
+      listen: `${this.o.listen.host}:${this.o.listen.port}`,
+      target: `${this.o.target.host}:${this.o.target.port}`
+    });
+    this.listener = Bun.listen({
+      hostname: this.o.listen.host,
+      port: this.o.listen.port,
+      socket: {
+        open: (client) => {
+          this.handleConnection(client);
+        },
+        data(client, chunk) {
+          const ctx = client.data;
+          ctx?.onData?.(chunk);
+        },
+        close(client) {
+          const ctx = client.data;
+          ctx?.onClose?.();
+        },
+        error(client) {
+          const ctx = client.data;
+          ctx?.onClose?.();
+        }
+      }
+    });
+  }
+  stop() {
+    this.listener?.stop();
+    this.listener = null;
+  }
+  async handleConnection(client) {
+    if (this.writeFailed) {
+      client.end();
+      return;
+    }
+    this.sessionCounter += 1;
+    const sessionId = `pxy_${this.sessionCounter}`;
+    const clientAddr = client.remoteAddress ?? "unknown";
+    const target = `${this.o.target.host}:${this.o.target.port}`;
+    const earlyBuffer = [];
+    let relay = null;
+    client.data = {
+      onData: (chunk) => {
+        if (relay) {
+          relay.fromClient(chunk);
+        } else {
+          earlyBuffer.push(chunk);
+        }
+      },
+      onClose: () => {
+        client.end();
+      }
+    };
+    const session = new ProxySession({
+      sessionId,
+      engine: this.o.engine,
+      client: clientAddr,
+      target,
+      slowMs: this.o.slowMs,
+      now: () => performance.now(),
+      getBytes: () => ({
+        clientBytes: relay?.clientBytes ?? 0,
+        serverBytes: relay?.serverBytes ?? 0
+      }),
+      writeEvent: (e) => this.writer.write(e).catch((err) => {
+        this.writeFailed = true;
+        this.o.warn(`event write failed: ${err instanceof Error ? err.message : String(err)}`);
+      }),
+      warn: this.o.warn
+    });
+    let upstream;
+    try {
+      const analyzer = makeAnalyzer(this.o.engine, { emit: (s) => session.onSignal(s) });
+      upstream = await Bun.connect({
+        hostname: this.o.target.host,
+        port: this.o.target.port,
+        socket: {
+          data(_s, chunk) {
+            relay?.fromUpstream(chunk);
+          },
+          close() {
+            session.end("upstream_closed").then(() => client.end());
+          },
+          error() {
+            session.end("error").then(() => client.end());
+          }
+        }
+      });
+      relay = new TcpRelay({
+        writeToClient: (b) => {
+          client.write(b);
+        },
+        writeToUpstream: (b) => {
+          upstream.write(b);
+        },
+        analyzer,
+        onSignal: (s) => session.onSignal(s)
+      });
+      const liveUpstream = upstream;
+      client.data = {
+        onData: (chunk) => relay?.fromClient(chunk),
+        onClose: () => void session.end("client_closed").then(() => liveUpstream.end())
+      };
+      for (const chunk of earlyBuffer) {
+        relay.fromClient(chunk);
+      }
+      earlyBuffer.length = 0;
+    } catch (err) {
+      this.o.warn(`upstream connect failed: ${err instanceof Error ? err.message : String(err)}`);
+      await session.start();
+      await session.end("error");
+      client.end();
+      return;
+    }
+    try {
+      await session.start();
+    } catch (err) {
+      this.o.warn(`session start failed: ${err instanceof Error ? err.message : String(err)}`);
+      client.end();
+      upstream.end();
+      return;
+    }
+  }
+}
+
+// src/proxy/event-reader.ts
+import { readFile as readFile7 } from "fs/promises";
+async function readEvents(path6, opts) {
+  const candidates = opts.includeRotated ? [path6, `${path6}.1`] : [path6];
+  const files = [];
+  const events = [];
+  let malformedLines = 0;
+  for (const file of candidates) {
+    let raw;
+    try {
+      raw = await readFile7(file, "utf8");
+    } catch (err) {
+      if (err.code !== "ENOENT")
+        throw err;
+      continue;
+    }
+    files.push(file);
+    for (const rawLine of raw.split(`
+`)) {
+      const trimmed = rawLine.trim();
+      if (!trimmed)
+        continue;
+      try {
+        events.push(JSON.parse(trimmed));
+      } catch {
+        malformedLines += 1;
+      }
+    }
+  }
+  events.sort((a, b) => a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0);
+  return { events, malformedLines, files };
+}
+
+// src/proxy/analyze.ts
+var isCompleted = (e) => e.type === "query_completed";
+var isErrored = (e) => e.type === "query_errored";
+function percentile(values, p) {
+  if (values.length === 0)
+    return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const rank = Math.ceil(p / 100 * sorted.length);
+  const idx = Math.min(Math.max(rank, 1), sorted.length) - 1;
+  return sorted[idx];
+}
+function fingerprintSql(sql) {
+  return redactLiterals(sql).replace(/\s+/g, " ").trim();
+}
+function shellEscapeDq(s) {
+  return s.replace(/\\/g, "\\\\").replace(/\$/g, "\\$").replace(/`/g, "\\`").replace(/"/g, "\\\"");
+}
+function buildByFingerprint(events, slowMs, top) {
+  const errorByFp = new Map;
+  for (const e of events.filter(isErrored)) {
+    const fp = fingerprintSql(e.sql);
+    errorByFp.set(fp, (errorByFp.get(fp) ?? 0) + 1);
+  }
+  const groups = new Map;
+  for (const e of events.filter(isCompleted)) {
+    const fp = fingerprintSql(e.sql);
+    let g = groups.get(fp);
+    if (!g) {
+      g = {
+        fingerprint: fp,
+        statement: e.statement,
+        tables: e.tables,
+        durations: [],
+        reqBytes: 0,
+        respBytes: 0,
+        rows: [],
+        slowCount: 0,
+        exampleSql: e.sql,
+        exampleQueryId: e.queryId,
+        exampleDuration: e.durationMs
+      };
+      groups.set(fp, g);
+    }
+    g.durations.push(e.durationMs);
+    g.reqBytes += e.requestBytes;
+    g.respBytes += e.responseBytes;
+    if (e.rowCount !== null)
+      g.rows.push(e.rowCount);
+    if (e.durationMs >= slowMs)
+      g.slowCount += 1;
+    if (e.durationMs > g.exampleDuration) {
+      g.exampleDuration = e.durationMs;
+      g.exampleSql = e.sql;
+      g.exampleQueryId = e.queryId;
+    }
+  }
+  const stats = [...groups.values()].map((g) => {
+    const count = g.durations.length;
+    const total = g.durations.reduce((sum, d) => sum + d, 0);
+    return {
+      fingerprint: g.fingerprint,
+      statement: g.statement,
+      tables: g.tables,
+      count,
+      durationMs: {
+        total,
+        avg: count ? Math.round(total / count) : 0,
+        p95: percentile(g.durations, 95),
+        max: count ? Math.max(...g.durations) : 0
+      },
+      rowsAvg: g.rows.length ? Math.round(g.rows.reduce((sum, r) => sum + r, 0) / g.rows.length) : 0,
+      bytesAvg: {
+        request: count ? Math.round(g.reqBytes / count) : 0,
+        response: count ? Math.round(g.respBytes / count) : 0
+      },
+      errorCount: errorByFp.get(g.fingerprint) ?? 0,
+      slowCount: g.slowCount,
+      redacted: redactLiterals(g.exampleSql) === g.exampleSql,
+      exampleSql: g.exampleSql,
+      exampleQueryId: g.exampleQueryId
+    };
+  });
+  stats.sort((a, b) => b.durationMs.total - a.durationMs.total);
+  return stats.map((s, i) => {
+    if (i < top && s.statement === "SELECT") {
+      const sql = shellEscapeDq(s.exampleSql);
+      return {
+        ...s,
+        suggestedCommands: [`dbcli explain "${sql}"`, `dbcli guide missing-index-for "${sql}"`]
+      };
+    }
+    return s;
+  });
+}
+function buildSlowest(events, top) {
+  return events.filter(isCompleted).sort((a, b) => b.durationMs - a.durationMs).slice(0, top).map((e) => ({
+    queryId: e.queryId,
+    durationMs: e.durationMs,
+    sql: e.sql,
+    statement: e.statement,
+    tables: e.tables,
+    timestamp: e.timestamp,
+    sessionId: e.sessionId
+  }));
+}
+function buildErrors(events) {
+  const groups = new Map;
+  for (const e of events.filter(isErrored)) {
+    const key = `${e.error.code ?? ""} ${e.error.message}`;
+    let g = groups.get(key);
+    if (!g) {
+      g = {
+        code: e.error.code,
+        message: e.error.message,
+        count: 0,
+        fingerprint: fingerprintSql(e.sql),
+        exampleSql: e.sql
+      };
+      groups.set(key, g);
+    }
+    g.count += 1;
+  }
+  return [...groups.values()].sort((a, b) => b.count - a.count);
+}
+function buildHotTables(events) {
+  const map = new Map;
+  for (const e of events.filter(isCompleted)) {
+    for (const t2 of e.tables) {
+      let g = map.get(t2);
+      if (!g) {
+        g = { queryCount: 0, totalDurationMs: 0 };
+        map.set(t2, g);
+      }
+      g.queryCount += 1;
+      g.totalDurationMs += e.durationMs;
+    }
+  }
+  return [...map.entries()].map(([table, g]) => ({ table, queryCount: g.queryCount, totalDurationMs: g.totalDurationMs })).sort((a, b) => b.queryCount - a.queryCount);
+}
+function buildRepetition(events, threshold) {
+  const groups = new Map;
+  for (const e of events.filter(isCompleted)) {
+    const fp = fingerprintSql(e.sql);
+    const key = `${e.sessionId} ${fp}`;
+    const ts = Date.parse(e.timestamp);
+    let g = groups.get(key);
+    if (!g) {
+      g = {
+        fingerprint: fp,
+        sessionId: e.sessionId,
+        tables: e.tables,
+        count: 0,
+        totalDurationMs: 0,
+        minTs: ts,
+        maxTs: ts
+      };
+      groups.set(key, g);
+    }
+    g.count += 1;
+    g.totalDurationMs += e.durationMs;
+    if (ts < g.minTs)
+      g.minTs = ts;
+    if (ts > g.maxTs)
+      g.maxTs = ts;
+  }
+  return [...groups.values()].filter((g) => g.count >= threshold).map((g) => ({
+    fingerprint: g.fingerprint,
+    sessionId: g.sessionId,
+    count: g.count,
+    spanMs: g.maxTs - g.minTs,
+    totalDurationMs: g.totalDurationMs,
+    tables: g.tables
+  })).sort((a, b) => b.count - a.count);
+}
+function analyzeEvents(events, opts) {
+  const timestamps = events.map((e) => e.timestamp).filter(Boolean).sort();
+  const from = timestamps[0] ?? null;
+  const to = timestamps[timestamps.length - 1] ?? null;
+  return {
+    version: 1,
+    tool: "proxy-analyze",
+    engine: events[0]?.engine ?? null,
+    source: {
+      files: opts.sourceFiles,
+      eventsRead: events.length,
+      malformedLines: opts.malformedLines,
+      timeSpan: {
+        from,
+        to,
+        durationMs: from && to ? Date.parse(to) - Date.parse(from) : 0
+      }
+    },
+    summary: buildSummary(events, opts.slowMs),
+    byFingerprint: buildByFingerprint(events, opts.slowMs, opts.top),
+    slowest: buildSlowest(events, opts.top),
+    errors: buildErrors(events),
+    hotTables: buildHotTables(events),
+    repetition: buildRepetition(events, opts.nPlusOne)
+  };
+}
+function buildSummary(events, slowMs) {
+  const completed = events.filter(isCompleted);
+  const errored = events.filter(isErrored);
+  const durations = completed.map((e) => e.durationMs);
+  const queries = completed.length;
+  const errors3 = errored.length;
+  const denom = queries + errors3;
+  return {
+    sessions: new Set(events.filter((e) => e.type === "session_started").map((e) => e.sessionId)).size,
+    queries,
+    errors: errors3,
+    errorRate: denom === 0 ? 0 : errors3 / denom,
+    parseErrors: events.filter((e) => e.type === "parse_error").length,
+    slowCount: completed.filter((e) => e.durationMs >= slowMs).length,
+    latencyMs: {
+      p50: percentile(durations, 50),
+      p95: percentile(durations, 95),
+      p99: percentile(durations, 99),
+      max: durations.length ? Math.max(...durations) : 0
+    },
+    bytes: {
+      request: completed.reduce((sum, e) => sum + e.requestBytes, 0),
+      response: completed.reduce((sum, e) => sum + e.responseBytes, 0)
+    }
+  };
+}
+
+// src/proxy/analyze-render.ts
+function renderAnalysisText(report, top) {
+  if (report.summary.queries === 0 && report.summary.errors === 0) {
+    return "no events to analyze";
+  }
+  const s = report.summary;
+  const L2 = [];
+  L2.push("SUMMARY");
+  L2.push(`  engine: ${report.engine ?? "unknown"}  sessions: ${s.sessions}  ` + `queries: ${s.queries}  errors: ${s.errors} (${(s.errorRate * 100).toFixed(2)}%)`);
+  L2.push(`  latency ms: p50=${s.latencyMs.p50} p95=${s.latencyMs.p95} ` + `p99=${s.latencyMs.p99} max=${s.latencyMs.max}  slow=${s.slowCount}`);
+  L2.push(`  bytes: req=${s.bytes.request} resp=${s.bytes.response}`);
+  L2.push("", "TOP QUERIES BY TOTAL TIME");
+  for (const f of report.byFingerprint.slice(0, top)) {
+    L2.push(`  [${f.count}x total=${f.durationMs.total}ms avg=${f.durationMs.avg} ` + `p95=${f.durationMs.p95}] ${f.fingerprint}`);
+  }
+  L2.push("", "SLOWEST SINGLE QUERIES");
+  for (const q3 of report.slowest.slice(0, top)) {
+    L2.push(`  ${q3.durationMs}ms  ${q3.sql}`);
+  }
+  L2.push("", "HOT TABLES");
+  for (const t2 of report.hotTables.slice(0, top)) {
+    L2.push(`  ${t2.queryCount}x  ${t2.totalDurationMs}ms  ${t2.table}`);
+  }
+  L2.push("", "ERRORS");
+  if (report.errors.length === 0)
+    L2.push("  (none)");
+  for (const e of report.errors.slice(0, top)) {
+    L2.push(`  ${e.count}x  [${e.code ?? "?"}] ${e.message}`);
+  }
+  L2.push("", "N+1 SUSPECTS");
+  if (report.repetition.length === 0)
+    L2.push("  (none)");
+  for (const r of report.repetition.slice(0, top)) {
+    L2.push(`  ${r.count}x in session ${r.sessionId} (${r.spanMs}ms)  ${r.fingerprint}`);
+  }
+  const cmds = [...new Set(report.byFingerprint.flatMap((f) => f.suggestedCommands ?? []))];
+  if (cmds.length) {
+    L2.push("", "SUGGESTED COMMANDS");
+    for (const c2 of cmds)
+      L2.push(`  ${c2}`);
+  }
+  return L2.join(`
+`);
+}
+
+// src/commands/proxy.ts
+var SUPPORTED = ["mysql", "mariadb", "postgresql"];
+var ALLOWED_FORMATS18 = ["text", "json"];
+var ALLOWED_REDACT = ["none", "literals"];
+function parseHostPort(value) {
+  const idx = value.lastIndexOf(":");
+  if (idx <= 0 || idx === value.length - 1) {
+    throw new Error(`Invalid address "${value}". Expected host:port`);
+  }
+  const host = value.slice(0, idx);
+  const port = Number(value.slice(idx + 1));
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error(`Invalid port in "${value}". Expected host:port with a numeric port`);
+  }
+  return { host, port };
+}
+function resolveProxyConfig(input) {
+  if (!input.listen) {
+    throw new Error("--listen <host:port> is required");
+  }
+  const listen = parseHostPort(input.listen);
+  let engine;
+  if (input.subcommandEngine) {
+    engine = input.subcommandEngine;
+  } else {
+    const sys = input.connection?.system;
+    if (!sys || !SUPPORTED.includes(sys)) {
+      throw new Error(`proxy supports mysql, mariadb, postgresql (got: ${sys ?? "none"})`);
+    }
+    engine = sys;
+  }
+  let target;
+  if (input.target) {
+    target = parseHostPort(input.target);
+  } else if (input.connection) {
+    target = { host: input.connection.host, port: input.connection.port };
+  } else {
+    throw new Error("--target <host:port> is required when config does not provide host/port");
+  }
+  return { engine, listen, target };
+}
+async function runProxy(subcommandEngine, options, command) {
+  try {
+    validateFormat(options.format ?? "text", ALLOWED_FORMATS18, "proxy");
+    const redact = options.redact ?? "none";
+    if (!ALLOWED_REDACT.includes(redact)) {
+      throw new Error(`Invalid --redact "${redact}". Allowed: none, literals`);
+    }
+    const configPath = resolveConfigPath(command, options);
+    let connection = null;
+    try {
+      const config = await configModule.read(configPath);
+      if (config.connection) {
+        connection = {
+          system: config.connection.system,
+          host: config.connection.host,
+          port: config.connection.port
+        };
+      }
+    } catch {}
+    const resolved = resolveProxyConfig({
+      subcommandEngine,
+      listen: options.listen,
+      target: options.target,
+      connection
+    });
+    const eventsPath = options.events ?? join32(".dbcli", "proxy", "events.jsonl");
+    const slowMs = Number(options.slowMs ?? 1000);
+    if (!Number.isFinite(slowMs) || slowMs < 0) {
+      throw new Error(`Invalid --slow-ms "${options.slowMs}". Expected a non-negative number`);
+    }
+    const server = new ProxyServer({
+      engine: resolved.engine,
+      listen: resolved.listen,
+      target: resolved.target,
+      eventsPath,
+      slowMs,
+      redact,
+      warn: (m) => process.stderr.write(`[proxy] ${m}
+`)
+    });
+    await server.start();
+    if (options.format === "json") {
+      process.stdout.write(JSON.stringify({
+        status: "listening",
+        engine: resolved.engine,
+        listen: `${resolved.listen.host}:${resolved.listen.port}`,
+        target: `${resolved.target.host}:${resolved.target.port}`,
+        events: eventsPath,
+        redact
+      }) + `
+`);
+    } else {
+      process.stdout.write(`dbcli proxy (${resolved.engine}) listening on ${resolved.listen.host}:${resolved.listen.port}` + ` -> ${resolved.target.host}:${resolved.target.port}
+` + `events: ${eventsPath} | slow-ms: ${slowMs} | redact: ${redact}
+` + `Press Ctrl+C to stop.
+`);
+    }
+    await new Promise((resolve5) => {
+      const shutdown = () => {
+        process.removeListener("SIGINT", shutdown);
+        process.removeListener("SIGTERM", shutdown);
+        server.stop();
+        resolve5();
+      };
+      process.on("SIGINT", shutdown);
+      process.on("SIGTERM", shutdown);
+    });
+  } catch (error) {
+    if (error instanceof Error)
+      console.error(error.message);
+    process.exit(1);
+  }
+}
+function addCommonOptions(cmd) {
+  return cmd.option("--listen <host:port>", "Local proxy listen address (required)").option("--target <host:port>", "Upstream DB target (optional when config provides host/port)").option("--events <path>", "Event JSONL path", join32(".dbcli", "proxy", "events.jsonl")).option("--slow-ms <number>", "Threshold (ms); queries at/above it get slow:true in the event + a terminal warning", "1000").option("--redact <mode>", "SQL redaction: none | literals", "none").option("--format <format>", "Runtime status output: text | json", "text");
+}
+var proxyCommand = new Command().name("proxy").description("Local development observability proxy for MySQL/MariaDB/PostgreSQL (observe-only)");
+proxyCommand.enablePositionalOptions();
+for (const engine of SUPPORTED) {
+  addCommonOptions(proxyCommand.command(engine).description(`Proxy a ${engine} connection`)).action(async (options, command) => {
+    await runProxy(engine, options, command);
+  });
+}
+var ANALYZE_FORMATS = ["json", "text"];
+function parseNonNegInt(value, flag, fallback) {
+  if (value === undefined)
+    return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new Error(`Invalid --${flag} "${value}". Expected a non-negative integer`);
+  }
+  return n;
+}
+async function runAnalyze(options) {
+  try {
+    const format = options.format ?? "json";
+    validateFormat(format, ANALYZE_FORMATS, "proxy analyze");
+    const top = parseNonNegInt(options.top, "top", 20);
+    const slowMs = parseNonNegInt(options.slowMs, "slow-ms", 1000);
+    const nPlusOne = parseNonNegInt(options.nPlusOne, "n-plus-one", 10);
+    const eventsPath = options.events ?? join32(".dbcli", "proxy", "events.jsonl");
+    const { events, malformedLines, files } = await readEvents(eventsPath, {
+      includeRotated: options.includeRotated !== false
+    });
+    if (files.length === 0) {
+      throw new Error(`no events found at ${eventsPath}; run 'dbcli proxy <engine>' first`);
+    }
+    const report = analyzeEvents(events, {
+      slowMs,
+      top,
+      nPlusOne,
+      sourceFiles: files,
+      malformedLines
+    });
+    if (format === "text") {
+      process.stdout.write(renderAnalysisText(report, top) + `
+`);
+    } else {
+      process.stdout.write(JSON.stringify(report, null, 2) + `
+`);
+    }
+  } catch (error) {
+    if (error instanceof Error)
+      console.error(error.message);
+    process.exit(1);
+  }
+}
+proxyCommand.command("analyze").description("Analyze a proxy event log offline (no DB connection)").option("--events <path>", "Event JSONL path", join32(".dbcli", "proxy", "events.jsonl")).option("--format <format>", "Output format: json | text", "json").option("--top <number>", "Rows shown in text + suggestedCommands depth", "20").option("--slow-ms <number>", "Slow-query threshold (ms) for slowCount", "1000").option("--n-plus-one <number>", "Min repeats per (session,fingerprint) to flag N+1", "10").option("--no-include-rotated", "Do not merge the rotated <events>.1 segment").action(async (options) => {
+  await runAnalyze(options);
+});
+addCommonOptions(proxyCommand).action(async (options, command) => {
+  await runProxy(null, options, command);
+});
+
 // src/cli.ts
 init_config();
-import { join as join31 } from "path";
+import { join as join33 } from "path";
 var _bgVersionCheckResult;
 function shouldSkipBackgroundChecks() {
   return process.env.DBCLI_NO_UPDATE_CHECK === "1" || process.env.DBCLI_NO_UPDATE_CHECK === "true" || false;
 }
-var program2 = new Command().name("dbcli").description("Database CLI for AI agents").version(package_default.version).option("--no-color", "Disable colored output").option("-v, --verbose", "Increase verbosity (-v verbose, -vv debug)", (_, prev) => prev + 1, 0).option("-q, --quiet", "Suppress non-essential output").option("--config <path>", "Path to .dbcli config file", ".dbcli").option("--use <connection>", "Use a specific named connection (v2 config)");
+var program2 = new Command().name("dbcli").description("Database CLI for AI agents").version(package_default.version).option("--no-color", "Disable colored output").option("-v, --verbose", "Increase verbosity (-v verbose, -vv debug)", (_, prev) => prev + 1, 0).option("-q, --quiet", "Suppress non-essential output").option("--config <path>", "Path to .dbcli config file", ".dbcli").option("--use <connection>", "Use a specific named connection (v2 config)").enablePositionalOptions();
 program2.hook("preAction", (thisCommand, actionCommand) => {
   const opts = thisCommand.opts();
   const useConnection = opts.use;
@@ -94187,7 +95847,7 @@ program2.hook("preAction", (thisCommand, actionCommand) => {
       try {
         let cache = null;
         try {
-          const cacheFile = Bun.file(join31(configPath, "version-check.json"));
+          const cacheFile = Bun.file(join33(configPath, "version-check.json"));
           if (await cacheFile.exists()) {
             cache = await cacheFile.json();
           }
@@ -94307,6 +95967,9 @@ program2.addCommand(migrateCommand);
 program2.addCommand(useCommand);
 program2.addCommand(queriesCommand);
 program2.addCommand(explainCommand);
+program2.addCommand(snapshotCommand);
+program2.addCommand(assertCommand);
+program2.addCommand(proxyCommand);
 if (!process.argv.slice(2).length) {
   program2.outputHelp();
 }