@carllee1983/dbcli 1.54.0 → 1.55.0

package/dist/cli-runtime.mjs

@@ -51,7 +51,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@carllee1983/dbcli",
-    version: "1.54.0",
+    version: "1.55.0",
     description: "Database CLI for AI agents",
     type: "module",
     publishConfig: {
@@ -93,11 +93,11 @@ var init_package = __esm(() => {
       "blacklist"
     ],
     engines: {
-      node: ">=18.0.0",
       bun: ">=1.3.3"
     },
     files: [
       "dist/",
+      "scripts/postinstall-check-bun.mjs",
       "!dist/.build-stamp",
       "assets/",
       "plugins/",
@@ -114,6 +114,7 @@ var init_package = __esm(() => {
       "LICENSE"
     ],
     scripts: {
+      postinstall: "bun scripts/postinstall-check-bun.mjs || node scripts/postinstall-check-bun.mjs || exit 0",
       dev: "bun run src/cli.ts",
       build: "bun run scripts/build.ts",
       "build:determinism": "bun run scripts/check-build-determinism.ts",
@@ -9674,10 +9675,12 @@ var init_types2 = __esm(() => {
   ConnectionError = class ConnectionError extends Error {
     code;
     hints;
-    constructor(code, message, hints) {
+    limitMs;
+    constructor(code, message, hints, limitMs) {
       super(message);
       this.code = code;
       this.hints = hints;
+      this.limitMs = limitMs;
       this.name = "ConnectionError";
       Object.setPrototypeOf(this, ConnectionError.prototype);
     }
@@ -9836,18 +9839,28 @@ var init_capabilities = __esm(() => {
 });
 
 // src/adapters/error-mapper.ts
-function categorize(errCode, errno, errMsg) {
+function isTransportDriverCode(code) {
+  return TLS_CODE_PREFIX.test(code) || TRANSPORT_CODES[code] !== undefined;
+}
+function categorize(errCode, errno, errMsg, system) {
   if (errCode) {
+    if (TLS_CODE_PREFIX.test(errCode))
+      return "TLS_ERROR";
     const known = TRANSPORT_CODES[errCode] ?? MYSQL_CODES[errCode] ?? SQLSTATES[errCode] ?? REDIS_PREFIXES[errCode];
+    if (known === "STATEMENT_TIMEOUT" && errCode === "57014" && !PG_CANCEL_BY_TIMEOUT.test(errMsg)) {
+      return null;
+    }
     if (known)
       return known;
   }
-  if (typeof errno === "number" && MYSQL_ERRNOS[errno])
+  const isMysqlFamily = system === "mysql" || system === "mariadb";
+  if (isMysqlFamily && typeof errno === "number" && MYSQL_ERRNOS[errno]) {
     return MYSQL_ERRNOS[errno];
+  }
   const redisPrefix = errMsg.match(/^([A-Z]+)\s/)?.[1];
   if (redisPrefix && REDIS_PREFIXES[redisPrefix])
     return REDIS_PREFIXES[redisPrefix];
-  if (errCode || typeof errno === "number")
+  if (errCode || isMysqlFamily && typeof errno === "number")
     return null;
   for (const [pattern, category] of FALLBACK_PATTERNS) {
     if (pattern.test(errMsg))
@@ -9870,7 +9883,7 @@ function mapError(error, system, options) {
   const errMsg = String(err?.message || String(error));
   const errCode = String(err?.code || "");
   const errno = err?.errno;
-  switch (categorize(errCode, errno, errMsg)) {
+  switch (categorize(errCode, errno, errMsg, system)) {
     case "ECONNREFUSED":
       return new ConnectionError("ECONNREFUSED", `Cannot connect to ${options.host}:${options.port} \u2014 server is not running or not listening on this port`, serviceHints(system, options));
     case "ETIMEDOUT":
@@ -9879,6 +9892,42 @@ function mapError(error, system, options) {
         `Increase timeout: edit .dbcli and add "timeout": 15000`,
         `Verify network connectivity: ping ${options.host} -c 3`
       ]);
+    case "CONNECTION_LOST":
+      return new ConnectionError("CONNECTION_LOST", `Connection to ${options.host}:${options.port} was lost mid-session \u2014 the server closed it or the network dropped`, [
+        "Re-run the command: a dropped connection is often transient",
+        `Check whether the server restarted or is cycling: ${SYSTEM_FACTS[system].logFile}`,
+        "If it happens on long-running work, look at the server idle/wait timeout"
+      ]);
+    case "SERVER_NOT_READY":
+      return new ConnectionError("SERVER_NOT_READY", `${options.host}:${options.port} is not accepting connections yet \u2014 the server is starting up or recovering`, [
+        "Retry shortly: this clears on its own once startup or recovery finishes",
+        `Watch progress in the server log: ${SYSTEM_FACTS[system].logFile}`,
+        "On a replica, this also appears while it catches up with the primary"
+      ]);
+    case "CONNECTION_REJECTED":
+      return new ConnectionError("CONNECTION_REJECTED", `${options.host}:${options.port} answered but rejected the connection attempt`, [
+        "Check the server access rules (pg_hba.conf) for this user, database, and client address",
+        "If a pooler (pgbouncer / ProxySQL) sits in front, check its own rules and limits",
+        "Check whether the connection limit for this user or database is exhausted"
+      ]);
+    case "TOO_MANY_CONNECTIONS":
+      return new ConnectionError("TOO_MANY_CONNECTIONS", `${options.host}:${options.port} refused the connection \u2014 the server has no connection slots left`, [
+        "Wait and retry: the limit is on concurrent connections, not on you",
+        system === "postgresql" ? "Inspect usage: SELECT count(*) FROM pg_stat_activity \u2014 compare against max_connections" : 'Inspect usage: SHOW STATUS LIKE "Threads_connected" \u2014 compare against max_connections',
+        "Close idle sessions, or raise max_connections if the load is legitimate"
+      ]);
+    case "EHOSTUNREACH":
+      return new ConnectionError("EHOSTUNREACH", `No route to ${options.host} \u2014 the name resolved, but the host or network is unreachable`, [
+        "Check that you are on the right network or VPN",
+        `Check routing and firewall between here and ${options.host}`,
+        `Confirm the address is the one you meant: ${options.host}:${options.port}`
+      ]);
+    case "TLS_ERROR":
+      return new ConnectionError("TLS_ERROR", `TLS handshake failed: ${errMsg}`, [
+        'Point the connection at the right CA bundle: set "caPath" in .dbcli',
+        'For a self-signed certificate in a trusted network, set "rejectUnauthorized": false',
+        `Confirm the certificate covers the host you connected to: ${options.host}`
+      ]);
     case "ENOTFOUND":
       return new ConnectionError("ENOTFOUND", `Host not found: ${options.host}`, [
         `Check the hostname spelling: ${options.host}`,
@@ -9909,6 +9958,14 @@ function mapError(error, system, options) {
         "Column names are case-sensitive on some databases (PostgreSQL with quoted identifiers)"
       ]);
     }
+    case "STATEMENT_TIMEOUT": {
+      const limitMs = options.statementTimeout ?? options.timeout;
+      return new ConnectionError("STATEMENT_TIMEOUT", `Statement timed out${limitMs ? ` (${limitMs}ms)` : ""} \u2014 the server canceled this query before it finished`, [
+        'Inspect the query plan: dbcli explain "<sql>"',
+        "Raise the ceiling for this run: dbcli --statement-timeout <ms> \u2026 (0 removes it)",
+        "Narrow the query: add WHERE filters, reduce the LIMIT, or index the scanned columns"
+      ], limitMs);
+    }
     case "SQL_SYNTAX_ERROR":
       return new ConnectionError("SQL_SYNTAX_ERROR", `SQL syntax error: ${errMsg}`, [
         "Check your SQL syntax near the position reported above",
@@ -9929,7 +9986,7 @@ function mapError(error, system, options) {
     `Try connecting directly with the ${SYSTEM_FACTS[system].client} command-line tool`
   ]);
 }
-var TRANSPORT_CODES, MYSQL_CODES, MYSQL_ERRNOS, SQLSTATES, REDIS_PREFIXES, FALLBACK_PATTERNS, SYSTEM_FACTS;
+var TRANSPORT_CODES, TLS_CODE_PREFIX, MYSQL_CODES, MYSQL_ERRNOS, SQLSTATES, REDIS_PREFIXES, FALLBACK_PATTERNS, PG_CANCEL_BY_TIMEOUT, SYSTEM_FACTS;
 var init_error_mapper = __esm(() => {
   init_types2();
   TRANSPORT_CODES = {
@@ -9938,9 +9995,16 @@ var init_error_mapper = __esm(() => {
     ESOCKETTIMEDOUT: "ETIMEDOUT",
     ENOTFOUND: "ENOTFOUND",
     EAI_AGAIN: "ENOTFOUND",
-    PROTOCOL_CONNECTION_LOST: "ECONNREFUSED",
-    PROTOCOL_SEQUENCE_TIMEOUT: "ETIMEDOUT"
-  };
+    PROTOCOL_CONNECTION_LOST: "CONNECTION_LOST",
+    PROTOCOL_SEQUENCE_TIMEOUT: "ETIMEDOUT",
+    ECONNRESET: "CONNECTION_LOST",
+    EPIPE: "CONNECTION_LOST",
+    ECONNABORTED: "CONNECTION_LOST",
+    EHOSTUNREACH: "EHOSTUNREACH",
+    ENETUNREACH: "EHOSTUNREACH",
+    ENETDOWN: "EHOSTUNREACH"
+  };
+  TLS_CODE_PREFIX = /^(CERT_|SELF_SIGNED_|DEPTH_ZERO_|UNABLE_TO_(?:GET|VERIFY)_|ERR_TLS_|ERR_SSL_)/;
   MYSQL_CODES = {
     ER_NO_SUCH_TABLE: "TABLE_NOT_FOUND",
     ER_BAD_FIELD_ERROR: "COLUMN_NOT_FOUND",
@@ -9948,7 +10012,11 @@ var init_error_mapper = __esm(() => {
     ER_ACCESS_DENIED_ERROR: "AUTH_FAILED",
     ER_DBACCESS_DENIED_ERROR: "AUTH_FAILED",
     ER_NOT_SUPPORTED_AUTH_MODE: "AUTH_FAILED",
-    ER_MUST_CHANGE_PASSWORD_LOGIN: "AUTH_FAILED"
+    ER_MUST_CHANGE_PASSWORD_LOGIN: "AUTH_FAILED",
+    ER_QUERY_TIMEOUT: "STATEMENT_TIMEOUT",
+    ER_STATEMENT_TIMEOUT: "STATEMENT_TIMEOUT",
+    ER_CON_COUNT_ERROR: "TOO_MANY_CONNECTIONS",
+    ER_SERVER_SHUTDOWN: "CONNECTION_LOST"
   };
   MYSQL_ERRNOS = {
     1045: "AUTH_FAILED",
@@ -9957,14 +10025,30 @@ var init_error_mapper = __esm(() => {
     1064: "SQL_SYNTAX_ERROR",
     1146: "TABLE_NOT_FOUND",
     1251: "AUTH_FAILED",
-    1698: "AUTH_FAILED"
+    1698: "AUTH_FAILED",
+    1040: "TOO_MANY_CONNECTIONS",
+    1053: "CONNECTION_LOST",
+    2006: "CONNECTION_LOST",
+    2013: "CONNECTION_LOST",
+    1969: "STATEMENT_TIMEOUT",
+    3024: "STATEMENT_TIMEOUT"
   };
   SQLSTATES = {
     "28000": "AUTH_FAILED",
     "28P01": "AUTH_FAILED",
     "42601": "SQL_SYNTAX_ERROR",
     "42P01": "TABLE_NOT_FOUND",
-    "42703": "COLUMN_NOT_FOUND"
+    "42703": "COLUMN_NOT_FOUND",
+    "57014": "STATEMENT_TIMEOUT",
+    "08000": "CONNECTION_LOST",
+    "08003": "CONNECTION_LOST",
+    "08006": "CONNECTION_LOST",
+    "08001": "ECONNREFUSED",
+    "08004": "CONNECTION_REJECTED",
+    "53300": "TOO_MANY_CONNECTIONS",
+    "57P01": "CONNECTION_LOST",
+    "57P02": "CONNECTION_LOST",
+    "57P03": "SERVER_NOT_READY"
   };
   REDIS_PREFIXES = {
     NOAUTH: "AUTH_FAILED",
@@ -9976,6 +10060,10 @@ var init_error_mapper = __esm(() => {
     [/connect(?:ion)? time(?:d )?out/i, "ETIMEDOUT"],
     [/timeout exceeded/i, "ETIMEDOUT"],
     [/timed out/i, "ETIMEDOUT"],
+    [/connection terminated/i, "CONNECTION_LOST"],
+    [/server closed the connection/i, "CONNECTION_LOST"],
+    [/server has gone away/i, "CONNECTION_LOST"],
+    [/lost connection to \S+ server/i, "CONNECTION_LOST"],
     [/getaddrinfo/i, "ENOTFOUND"],
     [/authentication failed/i, "AUTH_FAILED"],
     [/access denied for user/i, "AUTH_FAILED"],
@@ -9983,6 +10071,7 @@ var init_error_mapper = __esm(() => {
     [/role\s+".*?"\s+does not exist/i, "AUTH_FAILED"],
     [/password supplied/i, "AUTH_FAILED"]
   ];
+  PG_CANCEL_BY_TIMEOUT = /statement timeout/i;
   SYSTEM_FACTS = {
     postgresql: {
       serviceCheck: "systemctl status postgresql",
@@ -17956,7 +18045,7 @@ async function mapWithConcurrency(items, limit, worker) {
 }
 
 // src/core/recovery/types.ts
-var RECOVERY_SCHEMA_VERSION = 1, RECOVERY_CODES, MAX_BRANCH_STEPS = 6, MAX_BRANCH_COUNT = 8, SchemaCacheMissingError, RECOVERY_CODE_METADATA;
+var RECOVERY_SCHEMA_VERSION = 1, RECOVERY_CODES, MAX_BRANCH_STEPS = 6, MAX_BRANCH_COUNT = 8, STATEMENT_TIMEOUT_CODE = "STATEMENT_TIMEOUT", SchemaCacheMissingError, RECOVERY_CODE_METADATA;
 var init_types4 = __esm(() => {
   RECOVERY_CODES = [
     "CONFIG_MISSING",
@@ -18081,6 +18170,64 @@ function dryRunStepForWrite(ctx, quotedTable, placeholders) {
   };
   return draft;
 }
+function statementTimeoutSteps() {
+  return [
+    {
+      command: 'dbcli lint "<sql>"',
+      rationale: "Static anti-pattern read of the statement; needs no connection, so it cannot time out in turn.",
+      risk: "readonly",
+      expects: "Findings with rewrite drafts, or an empty list when nothing is flagged.",
+      placeholders: ["<sql>"]
+    },
+    {
+      command: 'dbcli explain "<sql>"',
+      rationale: "Read the query plan to find the scan or join that exceeded the statement limit.",
+      risk: "readonly",
+      expects: "Annotated query plan; look for sequential scans and unindexed joins.",
+      placeholders: ["<sql>"]
+    },
+    {
+      command: 'dbcli --statement-timeout <ms> query "<sql>"',
+      rationale: "Re-run with an explicit ceiling once the cost is understood; 0 removes the limit entirely.",
+      risk: "readonly",
+      expects: "Query result, or the same timeout if <ms> is still below what the plan costs.",
+      placeholders: ["<ms>", "<sql>"]
+    }
+  ];
+}
+function tlsErrorSteps() {
+  return [
+    {
+      command: "dbcli status --format json",
+      rationale: "Read back the active connection without a live probe to confirm which host and TLS settings are in force.",
+      risk: "readonly",
+      expects: "JSON status with system / permission; no credentials."
+    },
+    {
+      command: "dbcli doctor --format json",
+      rationale: "Doctor reports the handshake failure verbatim, which names the certificate problem (expired, self-signed, altname mismatch).",
+      risk: "readonly",
+      expects: "JSON report whose connection check fails with the TLS error text."
+    }
+  ];
+}
+function connectionsExhaustedSteps(ctx) {
+  const inspectSql = ctx.system === "postgresql" ? "SELECT count(*) FROM pg_stat_activity" : 'SHOW STATUS LIKE "Threads_connected"';
+  return [
+    {
+      command: `dbcli query ${shellQuote(inspectSql)} --format json`,
+      rationale: "Count the connections currently held so the limit can be compared against real usage; needs one free slot, so it may have to wait.",
+      risk: "readonly",
+      expects: "A single row with the current connection count."
+    },
+    {
+      command: "dbcli doctor --format json",
+      rationale: "Once a slot frees up, confirm the connection itself is healthy \u2014 the config was never the problem.",
+      risk: "readonly",
+      expects: "JSON report with the connection check passing."
+    }
+  ];
+}
 function stepsForCode(code, ctx) {
   const drafts = draftsForCode(code, ctx);
   return drafts.slice(0, MAX_RECOVERY_STEPS).map((d, i) => ({ ...d, order: i + 1 }));
@@ -18106,6 +18253,13 @@ function draftsForCode(code, ctx) {
     case "CONN_REFUSED":
     case "CONN_TIMEOUT":
     case "CONN_UNKNOWN": {
+      if (code === "CONN_TIMEOUT" && ctx.connectionCode === STATEMENT_TIMEOUT_CODE) {
+        return statementTimeoutSteps();
+      }
+      if (ctx.connectionCode === "TLS_ERROR")
+        return tlsErrorSteps();
+      if (ctx.connectionCode === "TOO_MANY_CONNECTIONS")
+        return connectionsExhaustedSteps(ctx);
       const out = [
         {
           command: "dbcli doctor --format json",
@@ -18329,7 +18483,9 @@ function draftsForCode(code, ctx) {
   }
 }
 var MAX_RECOVERY_STEPS = 6;
-var init_recovery_steps = () => {};
+var init_recovery_steps = __esm(() => {
+  init_types4();
+});
 
 // src/utils/sql-lexical.ts
 function dollarQuoteDelimiterAt(sql, index) {
@@ -19055,7 +19211,9 @@ var init_types5 = __esm(() => {
 });
 
 // src/core/recovery/verify-steps.ts
-function verifyForCode(code, _ctx) {
+function verifyForCode(code, ctx) {
+  if (ctx.connectionCode === STATEMENT_TIMEOUT_CODE)
+    return null;
   const command = VERIFY_COMMAND_BY_CODE[code];
   if (!command)
     return null;
@@ -19069,6 +19227,7 @@ function verifyForCode(code, _ctx) {
 }
 var VERIFY_COMMAND_BY_CODE, VERIFY_RATIONALE_BY_CODE, VERIFY_EXPECTS_BY_CODE;
 var init_verify_steps = __esm(() => {
+  init_types4();
   VERIFY_COMMAND_BY_CODE = {
     CONFIG_MISSING: "dbcli inspect --no-connect --format json",
     CONN_REFUSED: "dbcli doctor --format json",
@@ -19326,7 +19485,7 @@ function classifyError(error, ctx) {
   const ctxWithDetails = applyDetailsToContext(ctx, recoveryError);
   const recovery = stepsForCode(recoveryError.code, ctxWithDetails);
   const verify = verifyForCode(recoveryError.code, ctxWithDetails);
-  const branchExtras = recoveryError.category === "connection" ? buildConnectionBranches(ctxWithDetails) : null;
+  const branchExtras = recoveryError.category === "connection" && ctxWithDetails.connectionCode !== STATEMENT_TIMEOUT_CODE ? buildConnectionBranches(ctxWithDetails) : null;
   return {
     schemaVersion: RECOVERY_SCHEMA_VERSION,
     generatedAt: new Date().toISOString(),
@@ -19365,8 +19524,19 @@ function errorToRecoveryError(error, ctx) {
   return baseError("UNKNOWN");
 }
 function classifyConnection(err) {
-  const code = err.code === "ECONNREFUSED" ? "CONN_REFUSED" : err.code === "ETIMEDOUT" ? "CONN_TIMEOUT" : err.code === "AUTH_FAILED" ? "CONN_AUTH_FAILED" : err.code === "ENOTFOUND" ? "CONN_HOST_NOT_FOUND" : "CONN_UNKNOWN";
-  return baseError(code, { connectionCode: err.code });
+  const code = RECOVERY_CODE_BY_CONNECTION_CODE[err.code];
+  const base = baseError(code, { connectionCode: err.code });
+  const override = MESSAGE_BY_CONNECTION_CODE[err.code];
+  if (override)
+    return { ...base, message: override };
+  if (err.code === STATEMENT_TIMEOUT_CODE) {
+    const ceiling = err.limitMs !== undefined ? ` The ceiling in force was ${err.limitMs}ms.` : "";
+    return {
+      ...base,
+      message: `The server canceled the statement for exceeding the statement timeout.${ceiling}`
+    };
+  }
+  return base;
 }
 function classifyBlacklist(err) {
   if (/touches blacklisted columns:/i.test(err.message)) {
@@ -19417,9 +19587,11 @@ function applyDetailsToContext(ctx, err) {
     ...ctx,
     table: err.details?.table ?? ctx.table,
     snippet: err.details?.snippet ?? ctx.snippet,
-    hint: err.details?.paramName ?? ctx.hint
+    hint: err.details?.paramName ?? ctx.hint,
+    connectionCode: err.details?.connectionCode ?? ctx.connectionCode
   };
 }
+var RECOVERY_CODE_BY_CONNECTION_CODE, MESSAGE_BY_CONNECTION_CODE;
 var init_classify = __esm(() => {
   init_types2();
   init_permission_guard();
@@ -19429,6 +19601,31 @@ var init_classify = __esm(() => {
   init_verify_steps();
   init_connection_branches();
   init_types4();
+  RECOVERY_CODE_BY_CONNECTION_CODE = {
+    ECONNREFUSED: "CONN_REFUSED",
+    CONNECTION_LOST: "CONN_REFUSED",
+    TOO_MANY_CONNECTIONS: "CONN_REFUSED",
+    SERVER_NOT_READY: "CONN_REFUSED",
+    CONNECTION_REJECTED: "CONN_REFUSED",
+    ETIMEDOUT: "CONN_TIMEOUT",
+    STATEMENT_TIMEOUT: "CONN_TIMEOUT",
+    AUTH_FAILED: "CONN_AUTH_FAILED",
+    TLS_ERROR: "CONN_UNKNOWN",
+    ENOTFOUND: "CONN_HOST_NOT_FOUND",
+    EHOSTUNREACH: "CONN_HOST_NOT_FOUND",
+    SQL_SYNTAX_ERROR: "CONN_UNKNOWN",
+    TABLE_NOT_FOUND: "CONN_UNKNOWN",
+    COLUMN_NOT_FOUND: "CONN_UNKNOWN",
+    UNKNOWN: "CONN_UNKNOWN"
+  };
+  MESSAGE_BY_CONNECTION_CODE = {
+    EHOSTUNREACH: "The host name resolved, but the host or network is unreachable (routing or VPN).",
+    TOO_MANY_CONNECTIONS: "The server has no connection slots left; the limit is on concurrent connections, not on this caller.",
+    CONNECTION_LOST: "The connection was established and then dropped mid-session.",
+    TLS_ERROR: "The TLS handshake failed (certificate or trust chain).",
+    SERVER_NOT_READY: "The server is starting up or recovering and is not accepting connections yet.",
+    CONNECTION_REJECTED: "The server answered and rejected the connection attempt (access rules, pooler, or a per-user limit)."
+  };
 });
 
 // src/core/recovery/render-json.ts
@@ -20579,6 +20776,7 @@ __export(exports_recovery, {
   __resetExecutorForTests: () => __resetExecutorForTests,
   SchemaCacheMissingError: () => SchemaCacheMissingError,
   STEP_RESULT_SUMMARY_FIELD_CAP: () => STEP_RESULT_SUMMARY_FIELD_CAP,
+  STATEMENT_TIMEOUT_CODE: () => STATEMENT_TIMEOUT_CODE,
   RECOVERY_SCHEMA_VERSION: () => RECOVERY_SCHEMA_VERSION,
   RECOVERY_CODE_METADATA: () => RECOVERY_CODE_METADATA,
   RECOVERY_CODES: () => RECOVERY_CODES,
@@ -24498,6 +24696,45 @@ var init_saved_queries = __esm(() => {
   init_snippet_paths();
 });
 
+// src/utils/connection-error-message.ts
+function isTransportFailure(error) {
+  if (error instanceof ConnectionError)
+    return IS_TRANSPORT_FAILURE[error.code];
+  const raw = error?.code;
+  return typeof raw === "string" && isTransportDriverCode(raw);
+}
+function presentConnectionError(error) {
+  const key = IS_TRANSPORT_FAILURE[error.code] ? "errors.connection_failed" : "errors.message";
+  return {
+    message: t_vars(key, { message: error.message }),
+    code: error.code,
+    hints: error.hints
+  };
+}
+var IS_TRANSPORT_FAILURE;
+var init_connection_error_message = __esm(() => {
+  init_types2();
+  init_error_mapper();
+  init_message_loader();
+  IS_TRANSPORT_FAILURE = {
+    ECONNREFUSED: true,
+    ETIMEDOUT: true,
+    AUTH_FAILED: true,
+    ENOTFOUND: true,
+    EHOSTUNREACH: true,
+    CONNECTION_LOST: true,
+    TOO_MANY_CONNECTIONS: true,
+    TLS_ERROR: true,
+    SERVER_NOT_READY: true,
+    CONNECTION_REJECTED: true,
+    STATEMENT_TIMEOUT: false,
+    SQL_SYNTAX_ERROR: false,
+    TABLE_NOT_FOUND: false,
+    COLUMN_NOT_FOUND: false,
+    UNKNOWN: false
+  };
+});
+
 // src/commands/q-mongo.ts
 var exports_q_mongo = {};
 __export(exports_q_mongo, {
@@ -24834,7 +25071,7 @@ async function handleQError(error, snippetName, options, config) {
     process.exit(1);
   }
   if (error instanceof ConnectionError) {
-    printLocalizedCliError(t_vars("errors.connection_failed", { message: error.message }), error);
+    printLocalizedCliError(formatCliError(presentConnectionError(error)), error);
     process.exit(1);
   }
   printLocalizedCliError(t_vars("errors.message", { message: error.message }), error);
@@ -24952,6 +25189,7 @@ var init_q = __esm(() => {
   init_colors();
   init_applied_limit();
   init_cli_error();
+  init_connection_error_message();
   init_strategies();
   init_slow_query_advisory();
 });
@@ -26197,7 +26435,7 @@ async function insertCommand(table, options, command) {
       process.exit(1);
     }
     if (error instanceof ConnectionError) {
-      printLocalizedCliError(t_vars("errors.connection_failed", { message: error.message }), error);
+      printLocalizedCliError(formatCliError(presentConnectionError(error)), error);
       process.exit(1);
     }
     const output = {
@@ -26213,6 +26451,7 @@ async function insertCommand(table, options, command) {
 var init_insert = __esm(() => {
   init_message_loader();
   init_cli_error();
+  init_connection_error_message();
   init_adapters();
   init_data_executor();
   init_config();
@@ -26504,7 +26743,7 @@ async function updateCommand(table, options, command) {
       process.exit(1);
     }
     if (error instanceof ConnectionError) {
-      printLocalizedCliError(t_vars("errors.connection_failed", { message: error.message }), error);
+      printLocalizedCliError(formatCliError(presentConnectionError(error)), error);
       process.exit(1);
     }
     const output = {
@@ -26520,6 +26759,7 @@ async function updateCommand(table, options, command) {
 var init_update = __esm(() => {
   init_message_loader();
   init_cli_error();
+  init_connection_error_message();
   init_adapters();
   init_data_executor();
   init_config();
@@ -26795,7 +27035,7 @@ async function deleteCommand(table, options, command) {
       process.exit(1);
     }
     if (error instanceof ConnectionError) {
-      printLocalizedCliError(t_vars("errors.connection_failed", { message: error.message }), error);
+      printLocalizedCliError(formatCliError(presentConnectionError(error)), error);
       process.exit(1);
     }
     const output = {
@@ -26811,6 +27051,7 @@ async function deleteCommand(table, options, command) {
 var init_delete = __esm(() => {
   init_message_loader();
   init_cli_error();
+  init_connection_error_message();
   init_adapters();
   init_data_executor();
   init_config();
@@ -43842,13 +44083,12 @@ class ReplEngine {
     return null;
   }
   isConnectionError(error) {
-    const e = error;
-    const msg = (e.message ?? "").toLowerCase();
-    return e.code === "ECONNREFUSED" || e.code === "ECONNRESET" || e.code === "ETIMEDOUT" || msg.includes("connection") || msg.includes("terminated") || msg.includes("socket");
+    return isTransportFailure(error);
   }
 }
 var import_picocolors3;
 var init_repl_engine = __esm(() => {
+  init_connection_error_message();
   init_input_classifier();
   init_meta_commands();
   init_history_manager();

package/dist/cli.mjs

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.54.0",
+  version: "1.55.0",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {
@@ -45,11 +45,11 @@ var package_default = {
     "blacklist"
   ],
   engines: {
-    node: ">=18.0.0",
     bun: ">=1.3.3"
   },
   files: [
     "dist/",
+    "scripts/postinstall-check-bun.mjs",
     "!dist/.build-stamp",
     "assets/",
     "plugins/",
@@ -66,6 +66,7 @@ var package_default = {
     "LICENSE"
   ],
   scripts: {
+    postinstall: "bun scripts/postinstall-check-bun.mjs || node scripts/postinstall-check-bun.mjs || exit 0",
     dev: "bun run src/cli.ts",
     build: "bun run scripts/build.ts",
     "build:determinism": "bun run scripts/check-build-determinism.ts",

package/dist/core.d.ts

@@ -129,21 +129,31 @@ export interface TableSchema {
 	/** Type of table (table or view) */
 	tableType?: "table" | "view";
 }
-/**
- * Connection error with categorized error code and troubleshooting hints
- */
+type ConnectionErrorCode = "ECONNREFUSED" | "ETIMEDOUT" | "AUTH_FAILED" | "ENOTFOUND" | "EHOSTUNREACH" | "CONNECTION_LOST" | "TOO_MANY_CONNECTIONS" | "TLS_ERROR" | "SERVER_NOT_READY" | "CONNECTION_REJECTED" | "SQL_SYNTAX_ERROR" | "STATEMENT_TIMEOUT" | "TABLE_NOT_FOUND" | "COLUMN_NOT_FOUND" | "UNKNOWN";
 export declare class ConnectionError extends Error {
 	/** Error category code */
-	code: "ECONNREFUSED" | "ETIMEDOUT" | "AUTH_FAILED" | "ENOTFOUND" | "SQL_SYNTAX_ERROR" | "TABLE_NOT_FOUND" | "COLUMN_NOT_FOUND" | "UNKNOWN";
+	code: ConnectionErrorCode;
 	/** Array of actionable troubleshooting hints */
 	hints: string[];
+	/**
+	 * The ceiling that was in force, in milliseconds. Set on STATEMENT_TIMEOUT so
+	 * consumers can state it without parsing `message`; the recovery envelope needs
+	 * it to tell an agent what `--statement-timeout <ms>` it was already up against.
+	 */
+	limitMs?: number | undefined;
 	constructor(
 	/** Error category code */
-	code: "ECONNREFUSED" | "ETIMEDOUT" | "AUTH_FAILED" | "ENOTFOUND" | "SQL_SYNTAX_ERROR" | "TABLE_NOT_FOUND" | "COLUMN_NOT_FOUND" | "UNKNOWN", 
+	code: ConnectionErrorCode, 
 	/** User-friendly error message */
 	message: string, 
 	/** Array of actionable troubleshooting hints */
-	hints: string[]);
+	hints: string[], 
+	/**
+	 * The ceiling that was in force, in milliseconds. Set on STATEMENT_TIMEOUT so
+	 * consumers can state it without parsing `message`; the recovery envelope needs
+	 * it to tell an agent what `--statement-timeout <ms>` it was already up against.
+	 */
+	limitMs?: number | undefined);
 }
 /**
  * Result of a database query or command execution