@carllee1983/dbcli 1.45.1 → 1.47.0

package/dist/core.mjs

@@ -15022,12 +15022,40 @@ class MongoDBAdapter {
   buildUri() {
     if (this.options.uri)
       return this.options.uri;
-    const { user, password, host, port, database, authSource } = this.options;
-    if (user && password) {
-      const auth = authSource ?? "admin";
-      return `mongodb://${user}:${encodeURIComponent(password)}@${host}:${port}/${database}?authSource=${auth}`;
+    const { user, password, host, port, database, authSource, replicaSet, tls, srv } = this.options;
+    if (!host) {
+      throw new ConnectionError("UNKNOWN", "MongoDB host \u672A\u8A2D\u5B9A", [
+        "\u8ACB\u586B\u5BEB host\uFF0C\u6216\u6539\u7528 uri \u6B04\u4F4D\u6307\u5B9A\u5B8C\u6574\u9023\u7DDA\u5B57\u4E32"
+      ]);
+    }
+    const isBracketedIpv6 = /^\[[0-9a-f:]+\]$/i.test(host);
+    if (!isBracketedIpv6 && /[/@?#:\s\\]/.test(host)) {
+      throw new ConnectionError("UNKNOWN", `MongoDB host \u542B\u6709\u975E\u6CD5\u5B57\u5143: ${host}`, [
+        "host \u53EA\u61C9\u5305\u542B\u4E3B\u6A5F\u540D\u7A31\u6216 IP\uFF0C\u4E0D\u8981\u542B /\u3001@\u3001?\u3001#\u3001: \u6216\u7A7A\u767D",
+        "\u57E0\u865F\u8ACB\u586B\u5728 port \u6B04\u4F4D\uFF0C\u4E0D\u8981\u4F75\u9032 host",
+        "IPv6 \u4F4D\u5740\u8ACB\u52A0\u65B9\u62EC\u865F\uFF0C\u4F8B\u5982 [::1]",
+        "\u82E5\u8981\u6307\u5B9A\u5B8C\u6574\u9023\u7DDA\u5B57\u4E32\uFF0C\u8ACB\u6539\u7528 uri \u6B04\u4F4D"
+      ]);
     }
-    return `mongodb://${host}:${port}/${database}`;
+    if (user && !password) {
+      throw new ConnectionError("UNKNOWN", "\u5DF2\u6307\u5B9A user \u4F46\u672A\u63D0\u4F9B password", [
+        '\u8ACB\u88DC\u4E0A password\uFF0C\u6216\u6539\u7528\u74B0\u5883\u8B8A\u6578\u53C3\u7167 {"$env": "..."}',
+        "\u82E5\u78BA\u5B9A\u8981\u4EE5\u7121\u8A8D\u8B49\u65B9\u5F0F\u9023\u7DDA\uFF0C\u8ACB\u4E00\u4F75\u6E05\u7A7A user"
+      ]);
+    }
+    const userInfo = user ? `${encodeURIComponent(user)}:${encodeURIComponent(password)}@` : "";
+    const scheme = srv ? "mongodb+srv://" : "mongodb://";
+    const authority = srv ? host : `${host}:${port}`;
+    const path = database ? `/${encodeURIComponent(database)}` : "/";
+    const query = new URLSearchParams;
+    if (user)
+      query.set("authSource", authSource || "admin");
+    if (replicaSet)
+      query.set("replicaSet", replicaSet);
+    if (tls !== undefined)
+      query.set("tls", String(tls));
+    const search = query.toString();
+    return `${scheme}${userInfo}${authority}${path}${search ? `?${search}` : ""}`;
   }
   parseTxtRecords(records) {
     const combined = records.flat().map((record) => record.replace(/^"|"$/g, "")).join("&");
@@ -15089,13 +15117,11 @@ class MongoDBAdapter {
     return this.parseTxtRecords(payload.Answer.map((answer) => [answer.data]));
   }
   async buildResolvedUri() {
-    if (!this.options.uri) {
-      return this.buildUri();
+    const canonical = this.buildUri();
+    if (!canonical.startsWith("mongodb+srv://")) {
+      return canonical;
     }
-    if (!this.options.uri.startsWith("mongodb+srv://")) {
-      return this.options.uri;
-    }
-    const url = new URL(this.options.uri);
+    const url = new URL(canonical);
     const hosts = await this.resolveSrvHosts(url.hostname);
     const txtOptions = await this.resolveTxtOptions(url.hostname);
     const query = new URLSearchParams(url.searchParams);
@@ -15115,6 +15141,37 @@ class MongoDBAdapter {
     const search = query.toString();
     return `mongodb://${userInfo}${hosts.join(",")}${path}${search ? `?${search}` : ""}`;
   }
+  connectionHints(error, message) {
+    const AUTH_HINTS = [
+      "\u8A8D\u8B49\u5931\u6557\uFF1A\u8ACB\u78BA\u8A8D user / password \u6B63\u78BA",
+      "\u8ACB\u78BA\u8A8D authSource \u6307\u5411\u5B58\u653E\u8A72\u5E33\u865F\u7684\u8CC7\u6599\u5EAB\uFF08Atlas \u8207\u591A\u6578\u81EA\u67B6\u74B0\u5883\u70BA admin\uFF09"
+    ];
+    const DNS_HINTS = [
+      "DNS/SRV \u89E3\u6790\u5931\u6557\uFF1A\u8ACB\u78BA\u8A8D host \u70BA SRV \u7DB2\u57DF\uFF0C\u4E14 srv \u8A2D\u5B9A\u8207\u5B83\u4E00\u81F4",
+      "\u82E5\u8A72\u4E3B\u6A5F\u4E0D\u662F SRV \u7DB2\u57DF\uFF0C\u8ACB\u95DC\u9589 srv \u4E26\u6539\u586B host \u8207 port",
+      "\u8ACB\u78BA\u8A8D\u672C\u6A5F DNS \u6216\u7DB2\u8DEF\uFF08VPN\u3001\u516C\u53F8\u7DB2\u8DEF\uFF09\u5141\u8A31 SRV \u67E5\u8A62"
+    ];
+    const TLS_HINTS = [
+      "TLS \u63E1\u624B\u5931\u6557\uFF1A\u8ACB\u78BA\u8A8D tls \u6B04\u4F4D\u8A2D\u5B9A\u8207\u4F3A\u670D\u5668\u4E00\u81F4",
+      "\u81EA\u7C3D\u6191\u8B49\u74B0\u5883\u9700\u8981\u5728\u4F3A\u670D\u5668\u7AEF\u6216\u7CFB\u7D71\u4FE1\u4EFB\u93C8\u4E2D\u5B89\u88DD CA \u6191\u8B49"
+    ];
+    const err = error;
+    const causeCode = String(err?.cause?.code ?? err?.code ?? "");
+    if (err?.code === 18 || err?.codeName === "AuthenticationFailed")
+      return AUTH_HINTS;
+    if (["ENOTFOUND", "EAI_AGAIN"].includes(causeCode))
+      return DNS_HINTS;
+    if (causeCode.startsWith("ERR_TLS") || causeCode.startsWith("SELF_SIGNED"))
+      return TLS_HINTS;
+    if (/authentication failed|not authorized|bad auth/i.test(message))
+      return AUTH_HINTS;
+    if (/querySrv|getaddrinfo (ENOTFOUND|EAI_AGAIN)/i.test(message))
+      return DNS_HINTS;
+    if (/unable to verify the first certificate|self.signed certificate|certificate has expired|ERR_TLS/i.test(message)) {
+      return TLS_HINTS;
+    }
+    return ["\u8ACB\u78BA\u8A8D MongoDB \u670D\u52D9\u6B63\u5728\u57F7\u884C", "\u8ACB\u78BA\u8A8D\u9023\u7DDA\u8A2D\u5B9A\uFF08URI \u6216 host/port\uFF09\u6B63\u78BA"];
+  }
   getDatabase() {
     if (!this.client) {
       throw new ConnectionError("UNKNOWN", "\u5C1A\u672A\u9023\u7DDA\uFF0C\u8ACB\u5148\u547C\u53EB connect()", []);
@@ -15130,10 +15187,7 @@ class MongoDBAdapter {
     } catch (err) {
       const message = err.message ?? "Unknown error";
       const code = message.includes("ECONNREFUSED") ? "ECONNREFUSED" : message.includes("ETIMEDOUT") ? "ETIMEDOUT" : "UNKNOWN";
-      throw new ConnectionError(code, `MongoDB \u9023\u7DDA\u5931\u6557: ${message}`, [
-        "\u8ACB\u78BA\u8A8D MongoDB \u670D\u52D9\u6B63\u5728\u57F7\u884C",
-        "\u8ACB\u78BA\u8A8D\u9023\u7DDA\u8A2D\u5B9A\uFF08URI \u6216 host/port\uFF09\u6B63\u78BA"
-      ]);
+      throw new ConnectionError(code, `MongoDB \u9023\u7DDA\u5931\u6557: ${message}`, this.connectionHints(err, message));
     }
   }
   async disconnect() {
@@ -16671,9 +16725,22 @@ class ElasticsearchAdapter {
   }
 }
 
+// src/utils/connection-timeout.ts
+var _globalConnectionTimeout;
+function resolveConnectionTimeout(configured) {
+  return _globalConnectionTimeout ?? configured;
+}
+function withResolvedTimeout(options) {
+  const timeout = resolveConnectionTimeout(options.timeout);
+  if (timeout === options.timeout)
+    return options;
+  return { ...options, timeout };
+}
+
 // src/adapters/factory.ts
 class AdapterFactory {
-  static createSqlAdapter(options) {
+  static createSqlAdapter(rawOptions) {
+    const options = withResolvedTimeout(rawOptions);
     switch (options.system) {
       case "postgresql":
         return new PostgreSQLAdapter(options);
@@ -16684,7 +16751,8 @@ class AdapterFactory {
         throw new Error(`createSqlAdapter requires a SQL system, got: ${options.system}`);
     }
   }
-  static createQueryableAdapter(options) {
+  static createQueryableAdapter(rawOptions) {
+    const options = withResolvedTimeout(rawOptions);
     switch (options.system) {
       case "mongodb":
         return new MongoDBAdapter(options);
@@ -16716,10 +16784,11 @@ class AdapterFactory {
     }
     return AdapterFactory.createQueryableAdapter(options);
   }
-  static createRedisAdapter(options, blacklistRules = [], maskRules = []) {
-    if (options.system !== "redis") {
+  static createRedisAdapter(rawOptions, blacklistRules = [], maskRules = []) {
+    if (rawOptions.system !== "redis") {
       throw new Error("createRedisAdapter requires system: redis");
     }
+    const options = withResolvedTimeout(rawOptions);
     const adapter = new RedisAdapter(options);
     adapter.setBlacklistRules(blacklistRules);
     adapter.setMaskRules(maskRules);
@@ -21797,6 +21866,11 @@ var StringOrEnvRef = exports_external.union([exports_external.string().min(1), E
 var NumberOrEnvRef = exports_external.union([exports_external.number().int().min(1).max(65535), EnvRefSchema]);
 var OptStringOrEnvRef = exports_external.union([exports_external.string(), EnvRefSchema]).optional().default("");
 var OptNumberOrEnvRef = exports_external.union([exports_external.number().int(), EnvRefSchema]).optional().default(27017);
+var MIN_CONNECTION_TIMEOUT_MS = 100;
+var MAX_CONNECTION_TIMEOUT_MS = 600000;
+var TimeoutField = {
+  timeout: exports_external.number().int().min(MIN_CONNECTION_TIMEOUT_MS).max(MAX_CONNECTION_TIMEOUT_MS).optional()
+};
 var MongoDBConnectionConfigSchema = exports_external.object({
   system: exports_external.literal("mongodb"),
   uri: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
@@ -21804,7 +21878,12 @@ var MongoDBConnectionConfigSchema = exports_external.object({
   port: OptNumberOrEnvRef,
   user: OptStringOrEnvRef,
   password: OptStringOrEnvRef,
-  database: OptStringOrEnvRef
+  database: OptStringOrEnvRef,
+  authSource: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
+  replicaSet: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
+  tls: exports_external.boolean().optional(),
+  srv: exports_external.boolean().optional().default(false),
+  ...TimeoutField
 });
 var SqlConnectionConfigSchema = exports_external.object({
   system: exports_external.enum(["postgresql", "mysql", "mariadb"]),
@@ -21812,7 +21891,8 @@ var SqlConnectionConfigSchema = exports_external.object({
   port: NumberOrEnvRef,
   user: StringOrEnvRef,
   password: exports_external.union([exports_external.string(), EnvRefSchema]).default(""),
-  database: StringOrEnvRef
+  database: StringOrEnvRef,
+  ...TimeoutField
 });
 var RedisConnectionConfigSchema = exports_external.object({
   system: exports_external.literal("redis"),
@@ -21820,7 +21900,8 @@ var RedisConnectionConfigSchema = exports_external.object({
   port: NumberOrEnvRef,
   user: OptStringOrEnvRef,
   password: exports_external.union([exports_external.string(), EnvRefSchema]).optional().default(""),
-  database: OptStringOrEnvRef
+  database: OptStringOrEnvRef,
+  ...TimeoutField
 });
 var ElasticsearchConnectionConfigSchema = exports_external.object({
   system: exports_external.literal("elasticsearch"),
@@ -21834,7 +21915,8 @@ var ElasticsearchConnectionConfigSchema = exports_external.object({
   cloudId: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
   apiKey: exports_external.union([exports_external.string(), EnvRefSchema]).optional(),
   caPath: exports_external.string().optional(),
-  rejectUnauthorized: exports_external.boolean().optional().default(true)
+  rejectUnauthorized: exports_external.boolean().optional().default(true),
+  ...TimeoutField
 });
 var ConnectionConfigSchema = exports_external.union([
   SqlConnectionConfigSchema,
@@ -21924,6 +22006,89 @@ var DbcliConfigV2Schema = exports_external.object({
   path: ["default"]
 });
 
+// src/utils/config-error-format.ts
+var SUPPORTED_SYSTEMS = [
+  "postgresql",
+  "mysql",
+  "mariadb",
+  "mongodb",
+  "redis",
+  "elasticsearch"
+];
+function isConnectionNode(raw, path) {
+  const last = path[path.length - 1];
+  const parent = path[path.length - 2];
+  if (last !== "connection" && parent !== "connections")
+    return false;
+  const node = valueAtPath(raw, path);
+  return typeof node === "object" && node !== null && !Array.isArray(node);
+}
+function valueAtPath(raw, path) {
+  let current = raw;
+  for (const key of path) {
+    if (current == null || typeof current !== "object")
+      return;
+    current = current[key];
+  }
+  return current;
+}
+function declaredSystem(raw, path) {
+  const node = valueAtPath(raw, path);
+  if (node == null || typeof node !== "object")
+    return;
+  const system = node.system;
+  return typeof system === "string" ? system : undefined;
+}
+function branchMatchesSystem(issues) {
+  return !issues.some((issue) => issue.path[issue.path.length - 1] === "system" && (issue.code === "invalid_literal" || issue.code === "invalid_enum_value" || issue.code === "invalid_type"));
+}
+function formatPath(path) {
+  return path.length > 0 ? path.join(".") : "(root)";
+}
+function flattenIssues(issues, raw, basePath = []) {
+  const flat = [];
+  for (const issue of issues) {
+    const fullPath = [...basePath, ...issue.path];
+    if (issue.code === "invalid_union") {
+      const system = declaredSystem(raw, fullPath);
+      const branches = issue.unionErrors.map((error) => error.issues);
+      const candidates = system ? branches.filter((branchIssues) => branchMatchesSystem(branchIssues)) : [];
+      if (isConnectionNode(raw, fullPath) && candidates.length === 0) {
+        flat.push({
+          path: formatPath([...fullPath, "system"]),
+          message: `must be one of ${SUPPORTED_SYSTEMS.join(" | ")}` + (system === undefined ? " (missing)" : ` (received '${system}')`)
+        });
+        continue;
+      }
+      const chosen = candidates[0] ?? branches.reduce((best, current) => current.length < best.length ? current : best, branches[0] ?? []);
+      flat.push(...flattenIssues(chosen, raw, basePath));
+      continue;
+    }
+    flat.push({ path: formatPath(fullPath), message: issue.message });
+  }
+  return flat;
+}
+function dedupe(issues) {
+  const seen = new Set;
+  return issues.filter((issue) => {
+    const key = `${issue.path}\x00${issue.message}`;
+    if (seen.has(key))
+      return false;
+    seen.add(key);
+    return true;
+  });
+}
+function formatConfigValidationError(error, raw) {
+  const issues = dedupe(flattenIssues(error.issues, raw));
+  if (issues.length === 0)
+    return error.message;
+  return issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join(`
+`);
+}
+function isZodError(error) {
+  return error instanceof Error && error.name === "ZodError" && Array.isArray(error.issues);
+}
+
 // src/agent-core/env-loader.ts
 import { readFile as readFile3 } from "fs/promises";
 function parseEnvContent(content) {
@@ -22130,6 +22295,7 @@ function parseEnvPassword(content) {
 var configModule = {
   async read(path, connectionName, options = {}) {
     const effectiveConnectionName = connectionName ?? _globalConnectionName;
+    let rawForDiagnostics;
     try {
       const binding = await readProjectBinding(path);
       const storagePath = await resolveConfigStoragePath(path);
@@ -22155,6 +22321,7 @@ var configModule = {
           const content = await configFile.text();
           await assertConfigIntegrity(storagePath, content, { requireRecord: true });
           const config = JSON.parse(content);
+          rawForDiagnostics = config;
           if (detectConfigVersion(config) === 2) {
             const v2Config = DbcliConfigV2Schema.parse(config);
             const resolved = resolveConnection(v2Config, effectiveConnectionName);
@@ -22235,6 +22402,7 @@ var configModule = {
         assertNoConnectionSelectorOnV1(effectiveConnectionName);
         const content = await file.text();
         const raw = JSON.parse(content);
+        rawForDiagnostics = raw;
         const resolved = resolveEnvReferences(raw, process.env);
         return DbcliConfigSchema.parse(resolved);
       }
@@ -22245,6 +22413,10 @@ var configModule = {
     } catch (error) {
       if (error instanceof ConfigError)
         throw error;
+      if (isZodError(error)) {
+        throw new ConfigError(`Failed to read .dbcli config: \u8A2D\u5B9A\u5167\u5BB9\u4E0D\u7B26\u5408\u7D50\u69CB
+${formatConfigValidationError(error, rawForDiagnostics)}`);
+      }
       if (error instanceof Error && error.message.includes("JSON")) {
         throw new ConfigError(`Failed to parse .dbcli file: ${error.message}`);
       }
@@ -22255,6 +22427,10 @@ var configModule = {
     try {
       return DbcliConfigSchema.parse(raw);
     } catch (error) {
+      if (isZodError(error)) {
+        throw new ConfigError(`Invalid .dbcli config structure:
+${formatConfigValidationError(error, raw)}`);
+      }
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new ConfigError(`Invalid .dbcli config structure: ${errorMessage}`);
     }
@@ -22355,6 +22531,7 @@ var KEEP_VALUE_FLAGS = new Set([
   "--min-severity",
   "--output",
   "--limit",
+  "--timeout",
   "--collection",
   "--index",
   "--fields",

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.45.1",
+  "version": "1.47.0",
   "description": "Database CLI skill and command reference for AI agents.",
   "contextFileName": "AGENTS.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.45.1",
+  "version": "1.47.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {

package/plugins/dbcli-agent/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.45.1",
+  "version": "1.47.0",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/plugins/dbcli-agent/skills/dbcli/SKILL.md

@@ -77,7 +77,10 @@ When reporting a check's outcome use the vocabulary `verified` (evidence matched
 `not_verified` (check ran and contradicted) / `indeterminate` (ran but ambiguous) /
 `blocked` (could not run due to config, permission, schema, placeholder, or safety gate).
 
-Prefer `--format json` for agent-friendly output.
+Prefer `--format json` for agent-friendly output. Diagnostics (auto-limit notices,
+warnings) go to stderr so stdout stays parseable — when piping JSON into a parser,
+use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
+into stdout and the parse fails.
 
 ## Agent Task Packs
 
@@ -229,11 +232,13 @@ dbcli init --system postgresql --host localhost --port 5432 \
 # Reuse an existing .env (DATABASE_URL=postgresql://user:pw@host:5432/db)
 dbcli init                                                # parses .env in cwd
 
-# MongoDB — full URI (Atlas / replica sets / authSource)
+# MongoDB — field-by-field (no auth = omit --user/--password)
+dbcli init --system mongodb --host localhost --port 27017 --name mydb
+dbcli init --system mongodb --host localhost --port 27017 \
+  --user admin --password '<secret>' --auth-source admin --name mydb
+# MongoDB — full URI (advanced escape hatch: multi-host, non-standard driver options)
 dbcli init --system mongodb \
   --uri "mongodb+srv://user:pw@cluster.example.mongodb.net/mydb?authSource=admin"
-# MongoDB — discrete params (no auth = omit --user/--password)
-dbcli init --system mongodb --host localhost --port 27017 --name mydb
 
 # Redis — `--name` is the LOGICAL DB INDEX ("0".."15"), not a database name
 dbcli init --system redis --host localhost --port 6379 --password '<secret>' --name 0
@@ -301,10 +306,25 @@ as a `$env` ref. In a **non-interactive / CI** run you **must** pass all five `-
 flags; otherwise `init` exits with an error — it never silently falls back to plaintext.
 `--env-file <path>` is the path to the env file, independent of the `$env` key names.
 
+**MongoDB is the exception**: only `--env-host` is required non-interactively.
+`--env-port` / `--env-user` / `--env-password` / `--env-database` are optional — an
+omitted one is written as a literal value (empty string for `user` / `password`, the
+resolved value for `port` / `database`) instead of an `$env` ref, so a field the
+connection never needed doesn't later fail closed on an undefined variable. `init`
+also skips the connection test in this mode regardless of `--skip-test` — the `$env`
+refs have no value to connect with yet.
+
 ### Common gotchas
 
 - **MongoDB `mongodb+srv://`** — `dbcli doctor` reports whether SRV resolves
   natively or via the DoH fallback; useful when the runtime restricts DNS.
+- **MongoDB `authSource` / `replicaSet` / `tls` / `srv`** — `init` asks for
+  these interactively (`authSource` only when a user is set; `replicaSet` /
+  `tls` behind an "advanced options?" prompt); `--auth-source <db>` is the
+  only one with a dedicated non-interactive flag, so set `replicaSet` / `tls`
+  interactively or edit `.dbcli` afterward. If a config has both `uri` and
+  per-field values, `uri` wins silently — `dbcli doctor` flags this and also
+  warns when `srv: true` is combined with a non-default `port`.
 - **MySQL/Postgres password with `@` `:` `/`** — when using `DATABASE_URL`,
   percent-encode (`@` → `%40`); discrete `--password` flags do not need encoding.
 - **Redis `--name`** — accepts only the logical DB index string; non-numeric
@@ -536,4 +556,4 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - Blacklisted tables and columns are redacted from query output.
 - `schema` reports `estimatedRowCount` and `sizeCategory` (small / medium / large / huge). For large/huge tables add `WHERE` or `LIMIT` — bands in reference.md.
 - `doctor` on `mongodb+srv://` reports whether SRV resolves natively or through the DoH fallback — useful when the runtime restricts DNS.
-- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.
+- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `--timeout <ms>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.

package/plugins/dbcli-agent/skills/dbcli/reference.md

@@ -19,6 +19,28 @@ command-level option is only valid after the command that declares it.
 | `--config <path>` | Select the `.dbcli` configuration path. |
 | `--global` | Select the user-global registry at `~/.config/dbcli/config.json` instead of the current project's `.dbcli` config. Place it before the command path. |
 | `--use <connection>` | Select a named connection for this invocation; place it before the command path unless that command explicitly lists a command-level `--use`. |
+| `--timeout <ms>` | Connection timeout in milliseconds (integer, 100–600000), overriding the connection config's `timeout` field for this invocation. Applies to every engine adapter. Without either the flag or the config field, adapters fall back to their built-in 5000ms default. |
+
+`--timeout` is applied only when the adapter is constructed for this invocation — it is
+never written back to `config.json`. Set the connection's `timeout` field instead for a
+value that persists across runs. On PostgreSQL, the same value is also used as the
+session's `statement_timeout` (not just the connection timeout), so a low value can cut
+off a long-running query with an error that looks like a connection timeout; the 100ms
+floor exists specifically to keep that failure mode from being too easy to trigger.
+Elasticsearch applies its timeout per request rather than once for the whole connection.
+The `timeout` field itself always takes a literal number — unlike other connection
+fields, it does not accept an `{"$env": "..."}` reference.
+
+### Redirecting output
+
+Results go to stdout; diagnostics (auto-limit notices, warnings, update hints) go to
+stderr. That split is what keeps `--format json` machine-parseable, so do not collapse
+it with `2>&1` — the diagnostic lines land in front of the JSON document and the parse
+fails. Pipe stdout alone, or add `2>/dev/null` when the diagnostics are not wanted:
+
+```bash
+dbcli query '{}' --collection events --format json 2>/dev/null | jq '.rows | length'
+```
 
 ## Commands
 
@@ -32,10 +54,11 @@ dbcli init --system mysql --host localhost --port 3306 --user root --name mydb
 dbcli init --use-env-refs                               # Store env var references
 dbcli init --no-interactive --force                     # Non-interactive mode
 
-# MongoDB
-dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
-dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --name mydb
+# MongoDB — field-by-field (primary path, same shape as SQL)
+dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
 dbcli init --system mongodb --host localhost --port 27017 --name mydb  # No auth
+# MongoDB — full URI (advanced fallback: multi-host, non-standard driver options)
+dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
 
 # Redis (database = logical DB index)
 dbcli init --system redis --host localhost --port 6379
@@ -62,7 +85,7 @@ dbcli --global use --list
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
-**MongoDB-specific options:** `--uri <uri>` (full connection URI), `--auth-source <db>` (auth database, default: `admin` when user/password set)
+**MongoDB-specific options:** `--uri <uri>` (full connection URI — advanced fallback), `--auth-source <db>` (auth database, default: `admin` when user/password set). Interactive `init` also asks for `replicaSet` and `tls` under an "advanced options?" prompt; there is no dedicated non-interactive flag for either yet — set them interactively or edit `.dbcli` afterward. `srv` (boolean, builds `mongodb+srv://` and resolves hosts via DNS SRV, ignoring `port`) is asked right after `host`, before `port`, since it decides whether `port` is even relevant.
 
 **Elasticsearch-specific options:** `--cloud-id <id>` (Elastic Cloud), `--api-key <key>` (ApiKey auth). Other ES fields (`nodes[]`, `protocol`, `caPath`, `rejectUnauthorized`) can be edited directly in `.dbcli`.
 
@@ -117,6 +140,10 @@ agent mode disabled. A host that needs protection from a same-user hostile
 process can set `DBCLI_CONFIG_INTEGRITY_ANCHOR_DIR` to a protected or read-only
 directory; trusted writes publish detached digests there.
 
+When a connection's config fails schema validation, dbcli reports the specific field
+path(s) that are wrong for that connection's declared `system` — not the raw Zod union
+error tree — so a broken `.dbcli` can be fixed without guessing which branch applies.
+
 ### list
 
 List all tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch).
@@ -2025,7 +2052,9 @@ dbcli doctor --format json      # JSON output for AI agents
 - Configuration: config file exists/valid, permission level, blacklist completeness (detects unprotected sensitive columns)
 - Connection & Data: database connectivity, schema cache freshness (warns if > 7 days), large table warnings (> 1M rows)
 
-> **MongoDB SRV diagnostics:** When the active connection uses `mongodb+srv://`, `doctor` reports whether the current runtime can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by dbcli. This helps spot execution-environment DNS restrictions even when Compass can connect.
+> **MongoDB SRV diagnostics:** When the active connection uses `mongodb+srv://` (via a full `uri` or the per-field `srv: true`), `doctor` reports whether the current runtime can resolve SRV records directly or only through the DNS-over-HTTPS fallback used by dbcli. This helps spot execution-environment DNS restrictions even when Compass can connect.
+
+> **MongoDB connection-field warnings:** `doctor` also warns when a config has both `uri` and per-field values (`host` / `user`) present — `uri` silently wins and the per-field values are ignored — and when `srv: true` is combined with a non-default `port`, since SRV records carry their own ports.
 
 **Exit code:** 0 if all pass or warnings only, 1 if any error
 **Options:** `--format <text|json>`, `--remediation`
@@ -2600,7 +2629,9 @@ Parser behaviour (`src/core/saved-queries/parser.ts::normaliseVisual`):
 
 MongoDB connections use a JSON-based query model instead of SQL. Treat MongoDB support as a narrower document-database path, not as a full SQL feature equivalent.
 
-Atlas-style `mongodb+srv://` URIs are supported. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
+`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow and the unchanged non-interactive path via `--uri`. Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
+
+The 5000ms default server-selection timeout is often too tight for a connection over a VPN or to Atlas. Set a `timeout` field (ms) in the connection config, or override it per invocation with root-level `--timeout`, e.g. `dbcli --timeout 20000 --use <conn> list`.
 
 **Supported commands:** `init`, `use`, `list`, `schema`, `query`, `q`, `insert`, `update`, `delete`, `export`, `status`, `shell`, `doctor`, `upgrade`, `completion`
 
@@ -2623,7 +2654,10 @@ Atlas-style `mongodb+srv://` URIs are supported. `list` and `query` run against
 ### MongoDB-specific workflow
 
 ```bash
-# 1. Initialize (URI or individual params)
+# 1. Initialize — field-by-field (primary path)
+dbcli init --system mongodb --host localhost --port 27017 \
+  --user admin --password '<secret>' --auth-source admin --name mydb
+# ...or a full URI (advanced fallback, e.g. Atlas SRV clusters)
 dbcli init --system mongodb --uri "mongodb+srv://user:pass@cluster.example.mongodb.net/mydb"
 
 # 2. List collections
@@ -2663,7 +2697,7 @@ Redis connections speak Redis commands rather than SQL. The adapter uses Bun's n
 
 - Required fields: `system: redis`, `host`, `port`. `password` and `database` are optional.
 - `database` is the **logical DB index** (`"0"` … `"15"`), kept as a string to play nicely with env-ref bindings. `list` and the connection metadata both label it as the active DB.
-- `connection.timeout` (ms, default 5000) maps to the client's `connectionTimeout`.
+- `connection.timeout` (ms, default 5000) maps to the client's `connectionTimeout`; root-level `--timeout <ms>` overrides it for a single invocation.
 
 ### Permission classification
 
@@ -2793,7 +2827,7 @@ Elasticsearch connections speak the REST API. The adapter is fetch-based (no SDK
 - Either `host` + `port` (default `https://localhost:9200`) or `nodes: [...]` (first node is used) or `cloudId`.
 - Auth precedence: `apiKey` → `user`/`password` (HTTP Basic). Leave both unset for an open cluster.
 - `protocol` defaults to `https`. For TLS quirks: `caPath` (path to a PEM bundle) and `rejectUnauthorized: false` (last resort).
-- `connection.timeout` (ms, default 5000) is wired to `AbortController` on every request.
+- `connection.timeout` (ms, default 5000) is wired to `AbortController` on every request; root-level `--timeout <ms>` overrides it for a single invocation.
 
 ### Permission classification
 

package/skills/dbcli/SKILL.md

@@ -77,7 +77,10 @@ When reporting a check's outcome use the vocabulary `verified` (evidence matched
 `not_verified` (check ran and contradicted) / `indeterminate` (ran but ambiguous) /
 `blocked` (could not run due to config, permission, schema, placeholder, or safety gate).
 
-Prefer `--format json` for agent-friendly output.
+Prefer `--format json` for agent-friendly output. Diagnostics (auto-limit notices,
+warnings) go to stderr so stdout stays parseable — when piping JSON into a parser,
+use `2>/dev/null` or leave stderr alone. **Never `2>&1`**: it merges those lines back
+into stdout and the parse fails.
 
 ## Agent Task Packs
 
@@ -229,11 +232,13 @@ dbcli init --system postgresql --host localhost --port 5432 \
 # Reuse an existing .env (DATABASE_URL=postgresql://user:pw@host:5432/db)
 dbcli init                                                # parses .env in cwd
 
-# MongoDB — full URI (Atlas / replica sets / authSource)
+# MongoDB — field-by-field (no auth = omit --user/--password)
+dbcli init --system mongodb --host localhost --port 27017 --name mydb
+dbcli init --system mongodb --host localhost --port 27017 \
+  --user admin --password '<secret>' --auth-source admin --name mydb
+# MongoDB — full URI (advanced escape hatch: multi-host, non-standard driver options)
 dbcli init --system mongodb \
   --uri "mongodb+srv://user:pw@cluster.example.mongodb.net/mydb?authSource=admin"
-# MongoDB — discrete params (no auth = omit --user/--password)
-dbcli init --system mongodb --host localhost --port 27017 --name mydb
 
 # Redis — `--name` is the LOGICAL DB INDEX ("0".."15"), not a database name
 dbcli init --system redis --host localhost --port 6379 --password '<secret>' --name 0
@@ -301,10 +306,25 @@ as a `$env` ref. In a **non-interactive / CI** run you **must** pass all five `-
 flags; otherwise `init` exits with an error — it never silently falls back to plaintext.
 `--env-file <path>` is the path to the env file, independent of the `$env` key names.
 
+**MongoDB is the exception**: only `--env-host` is required non-interactively.
+`--env-port` / `--env-user` / `--env-password` / `--env-database` are optional — an
+omitted one is written as a literal value (empty string for `user` / `password`, the
+resolved value for `port` / `database`) instead of an `$env` ref, so a field the
+connection never needed doesn't later fail closed on an undefined variable. `init`
+also skips the connection test in this mode regardless of `--skip-test` — the `$env`
+refs have no value to connect with yet.
+
 ### Common gotchas
 
 - **MongoDB `mongodb+srv://`** — `dbcli doctor` reports whether SRV resolves
   natively or via the DoH fallback; useful when the runtime restricts DNS.
+- **MongoDB `authSource` / `replicaSet` / `tls` / `srv`** — `init` asks for
+  these interactively (`authSource` only when a user is set; `replicaSet` /
+  `tls` behind an "advanced options?" prompt); `--auth-source <db>` is the
+  only one with a dedicated non-interactive flag, so set `replicaSet` / `tls`
+  interactively or edit `.dbcli` afterward. If a config has both `uri` and
+  per-field values, `uri` wins silently — `dbcli doctor` flags this and also
+  warns when `srv: true` is combined with a non-default `port`.
 - **MySQL/Postgres password with `@` `:` `/`** — when using `DATABASE_URL`,
   percent-encode (`@` → `%40`); discrete `--password` flags do not need encoding.
 - **Redis `--name`** — accepts only the logical DB index string; non-numeric
@@ -536,4 +556,4 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - Blacklisted tables and columns are redacted from query output.
 - `schema` reports `estimatedRowCount` and `sizeCategory` (small / medium / large / huge). For large/huge tables add `WHERE` or `LIMIT` — bands in reference.md.
 - `doctor` on `mongodb+srv://` reports whether SRV resolves natively or through the DoH fallback — useful when the runtime restricts DNS.
-- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.
+- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `--timeout <ms>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.