dsh-switchman 1.3.1 → 1.6.0

package/skills/db-query/scripts/lib/config.js

@@ -1,39 +1,43 @@
 'use strict';
 
 /**
- * 配置解析：env 文件 / 环境变量 / 脱敏 / 安全错误格式化
- * dotenv 只用 parse()，不污染 process.env；POSIX 下检查 env 文件权限
+ * Configuration: env file / environment variables / sanitizing / safe error formatting
+ * Only dotenv.parse() is used so process.env stays untouched; env file
+ * permissions are checked on POSIX
  */
 
 const fs = require('fs');
 const path = require('path');
 const dotenv = require('dotenv');
 
-// ── env 文件加载（不污染 process.env）──
+// ── Env file loading (does not touch process.env) ──
 
 /**
- * 加载指定 env 文件，返回键值对
- * 不读 cwd 的 .env，防止意外泄露；group/other 可读时直接拒绝（凭据安全）
- * @param {string|undefined} envFile - env 文件路径
- * @returns {object} 键值对
+ * Load the given env file and return key/value pairs
+ * Never reads .env from cwd to avoid accidental leaks; rejects outright when
+ * group/other can read it (credential safety)
+ * @param {string|undefined} envFile - env file path
+ * @returns {object} key/value pairs
  */
 function loadEnvFile(envFile) {
   if (!envFile) return {};
   const resolved = path.resolve(envFile);
   if (!fs.existsSync(resolved)) {
-    throw new Error(`env 文件不存在: ${resolved}`);
+    throw new Error(`Env file not found: ${resolved}`);
   }
 
-  // POSIX 下检查 group/other 权限：同机其他用户可读即泄露密码，直接拒绝
+  // Check group/other permissions on POSIX: if other local users can read the
+  // file the password leaks — reject outright
   try {
     const stat = fs.statSync(resolved);
     // eslint-disable-next-line no-bitwise
     if ((stat.mode & 0o077) !== 0) {
-      throw new ConfigError(`env 文件 ${resolved} 权限过宽（group/other 可访问），请 chmod 600`);
+      throw new ConfigError(`Env file ${resolved} permissions too broad (accessible by group/other), run chmod 600`);
     }
   } catch (e) {
-    // 仅跳过 Windows 等非 POSIX 系统的权限检查错误；其余错误（权限过宽）往上抛
-    if (e.message.includes('权限过宽')) throw e;
+    // Only skip the permission-check error on Windows and other non-POSIX
+    // systems; rethrow everything else (permissions too broad)
+    if (e.message.includes('permissions too broad')) throw e;
   }
 
   const content = fs.readFileSync(resolved, 'utf8');
@@ -41,28 +45,30 @@ function loadEnvFile(envFile) {
 }
 
 /**
- * 按 SKILL.md 优先级读取配置值：CLI > env 文件 > 进程环境变量 > undefined
- * @param {object} envPairs - dotenv.parse() 结果（显式 --env-file，权限受控）
- * @param {string} envKey - 环境变量名（如 DB_QUERY_MYSQL_HOST）
- * @param {*} cliValue - CLI 传入的值；undefined 表示 CLI 未指定
- * @returns {*} CLI 优先，其次 env 文件，再次进程环境变量，否则 undefined
+ * Read a config value with SKILL.md precedence: CLI > env file > process env > undefined
+ * @param {object} envPairs - dotenv.parse() result (explicit --env-file, permission-controlled)
+ * @param {string} envKey - environment variable name (e.g. DB_QUERY_MYSQL_HOST)
+ * @param {*} cliValue - value from the CLI; undefined means not given on the CLI
+ * @returns {*} CLI first, then env file, then process env, otherwise undefined
  */
 function resolveEnv(envPairs, envKey, cliValue) {
   if (cliValue !== undefined) return cliValue;
-  // env 文件优先（显式指定、权限受控 0600），其次进程环境变量
-  // （loadEnvFile 刻意不污染 process.env，必须在此显式读取兜底，否则 export DB_QUERY_* 不生效）
+  // Env file first (explicitly given, permission-controlled 0600), then the
+  // process environment (loadEnvFile deliberately leaves process.env
+  // untouched, so fall back to it here or `export DB_QUERY_*` would not work)
   if (envPairs[envKey] !== undefined) return envPairs[envKey];
   if (process.env[envKey] !== undefined) return process.env[envKey];
   return undefined;
 }
 
 /**
- * 从 env/CLI 解析数值并校验 min/max 边界
- * 所有来源（CLI / env 文件 / 环境变量）统一跑边界检查，防止 env 文件绕过硬上限
+ * Parse a number from env/CLI and validate min/max bounds
+ * Every source (CLI / env file / environment) runs the same bounds check so
+ * an env file cannot bypass hard limits
  *
- * @param {object} envPairs - dotenv.parse() 结果
- * @param {string} envKey - 环境变量名
- * @param {*} cliValue - CLI 传入的值（已由 cli.js 做过边界校验）
+ * @param {object} envPairs - dotenv.parse() result
+ * @param {string} envKey - environment variable name
+ * @param {*} cliValue - value from the CLI (bounds already checked by cli.js)
  * @param {object} bounds - { min?: number, max?: number }
  * @returns {number}
  */
@@ -71,29 +77,31 @@ class ConfigError extends Error {
 }
 
 function resolveEnvNumber(envPairs, envKey, cliValue, bounds) {
-  // CLI 来源：cli.js 的 coerceValue 已做过边界检查，直接返回
+  // CLI source: cli.js coerceValue already checked the bounds, return as-is
   if (cliValue !== undefined) return cliValue;
-  // env 文件优先，其次进程环境变量（与 resolveEnv 优先级一致，符合 SKILL.md 承诺）；
-  // env 来源的值需统一解析 + 边界校验，防止 env 绕过硬上限
+  // Env file first, then process env (same precedence as resolveEnv, per the
+  // SKILL.md contract); env-sourced values are parsed and bounds-checked
+  // uniformly so env cannot bypass hard limits
   const raw = envPairs[envKey] !== undefined ? envPairs[envKey] : process.env[envKey];
   if (raw === undefined) return undefined;
   const n = Number(raw);
   if (!Number.isInteger(n)) {
-    throw new ConfigError(`环境变量 ${envKey}=${raw} 不是合法整数`);
+    throw new ConfigError(`Environment variable ${envKey}=${raw} is not a valid integer`);
   }
   if (bounds && bounds.min !== undefined && n < bounds.min) {
-    throw new ConfigError(`环境变量 ${envKey}=${n} 低于最小值 ${bounds.min}`);
+    throw new ConfigError(`Environment variable ${envKey}=${n} is below the minimum ${bounds.min}`);
   }
   if (bounds && bounds.max !== undefined && n > bounds.max) {
-    throw new ConfigError(`环境变量 ${envKey}=${n} 超过最大值 ${bounds.max}`);
+    throw new ConfigError(`Environment variable ${envKey}=${n} exceeds the maximum ${bounds.max}`);
   }
   return n;
 }
 
-// ── 连接目标脱敏 ──
+// ── Connection target sanitizing ──
 
 /**
- * 生成脱敏的连接目标信息，绝不包含密码或含密码 URI
+ * Build sanitized connection target info; never includes the password or a
+ * password-bearing URI
  * @param {object} opts - { host, port, user, database }
  * @returns {string}
  */
@@ -104,14 +112,16 @@ function sanitizeTarget(opts) {
   return parts.join(', ');
 }
 
-// ── 安全错误格式化 ──
+// ── Safe error formatting ──
 
-// 屏蔽 URL/连接串里内联的密码（://user:password@host → ://user:***@host）。
-// 用户名段用 * 以覆盖 redis 无用户名的标准形式（://:password@host），防御性脱敏
+// Mask passwords inlined in URLs/connection strings (://user:password@host → ://user:***@host).
+// The username segment uses * to also cover the standard no-username Redis
+// form (://:password@host); defensive sanitizing
 const URL_CRED_PATTERN = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/\s:@]*:)[^/\s@]+(@)/g;
 
 /**
- * 取错误 message 首行，脱敏截断：屏蔽内联凭据 + 截断到 200 字符防意外泄露
+ * Take the first line of an error message, sanitized and truncated: mask
+ * inline credentials + cut at 200 chars to prevent accidental leaks
  * @param {string} s
  * @returns {string}
  */
@@ -121,27 +131,28 @@ function sanitizeErrorLine(s) {
   return masked.length > 200 ? masked.slice(0, 200) + '…' : masked;
 }
 
-// 连接/认证/握手阶段错误码 —— 归为「连接失败」，明确区分于查询执行错误
+// Connection/auth/handshake error codes — classified as "connection failure",
+// clearly distinct from query execution errors
 const CONNECTION_CODES = new Set([
-  // Node 网络与系统错误
+  // Node network and system errors
   'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND',
   'EHOSTUNREACH', 'ENETUNREACH', 'EPIPE', 'ECONNABORTED', 'EDESTADDRREQ',
-  // DNS 解析错误
+  // DNS resolution errors
   'EAI_AGAIN', 'EAI_NONAME', 'EAI_SERVICE', 'EAI_FAIL', 'EAI_BADFLAGS',
-  // TLS 错误
+  // TLS errors
   'ERR_TLS_CERT_ALTNAME_INVALID', 'CERT_HAS_EXPIRED',
   'DEPTH_ZERO_SELF_SIGNED_CERT', 'ERR_TLS_INVALID_PROTOCOL_METHOD',
   'ERR_TLS_PROTOCOL_VERSION_CONFLICT',
-  // mysql2 连接/握手/选库阶段
+  // mysql2 connection/handshake/db-selection stage
   'HANDSHAKE_ERROR', 'PROTOCOL_CONNECTION_LOST',
   'PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR', 'PROTOCOL_SEQUENCE_TIMEOUT',
   'ER_ACCESS_DENIED_ERROR', 'ER_DBACCESS_DENIED_ERROR',
   'ER_BAD_DB_ERROR', 'ER_BAD_HOST_ERROR',
-  // Redis 认证阶段
+  // Redis auth stage
   'WRONGPASS', 'NOAUTH',
 ]);
 
-// node-redis 命令执行阶段错误码（与连接阶段区分）
+// node-redis command execution error codes (distinct from the connection stage)
 const REDIS_EXEC_CODES = new Set([
   'ERR', 'WRONGTYPE', 'WRONGINT', 'WRONGBIT', 'WRONGKEY',
   'EXECABORT', 'NOREPLICAS', 'MISCONF', 'BUSYGROUP', 'NOGROUP',
@@ -150,14 +161,18 @@ const REDIS_EXEC_CODES = new Set([
 ]);
 
 /**
- * 安全地格式化数据库错误，让排障 agent 能立刻看清真正的失败原因。
+ * Format a database error safely so a triaging agent can see the real failure
+ * at a glance.
  *
- * 关键安全前提：mysql2 的 ER_* / node-redis 的命令错误，其 message 来自
- * 数据库服务端，不含客户端凭据（服务端不感知客户端密码）；Node 网络错误
- * message 形如 "connect ECONNREFUSED 127.0.0.1:3306" 也不含密码。因此按
- * code 分类后暴露 code + message 首行（已脱敏截断）是安全的，且能让 agent
- * 一次区分「连不上」还是「SQL 写错」，避免无效的二分排查。
- * 仅对「既无 code 也无 message」的极端异常给中性兜底，且不再误报成「连接失败」。
+ * Key security premise: messages of mysql2 ER_* / node-redis command errors
+ * come from the database server and contain no client credentials (the server
+ * never sees the client password); Node network errors such as
+ * "connect ECONNREFUSED 127.0.0.1:3306" contain no password either. So
+ * exposing the code plus the sanitized first message line, classified by
+ * code, is safe and lets the agent tell "cannot connect" from "bad SQL" in
+ * one step, avoiding pointless bisection. Only pathological errors with
+ * neither code nor message get a neutral fallback, no longer misreported as
+ * "connection failure".
  * @param {Error} err
  * @returns {string}
  */
@@ -168,29 +183,31 @@ function safeMessage(err) {
   if (code) {
     const codeStr = String(code);
     if (CONNECTION_CODES.has(codeStr)) {
-      return `连接失败 [${codeStr}]: ${line}`;
+      return `Connection failed [${codeStr}]: ${line}`;
     }
-    // mysql2 服务端执行错误：ER_BAD_FIELD_ERROR(1054)/ER_PARSE_ERROR/ER_NO_SUCH_TABLE 等
+    // mysql2 server-side execution errors: ER_BAD_FIELD_ERROR(1054)/ER_PARSE_ERROR/ER_NO_SUCH_TABLE etc.
     if (/^ER_/.test(codeStr)) {
-      return `查询执行错误 [${codeStr}]: ${line}`;
+      return `Query execution error [${codeStr}]: ${line}`;
     }
-    // node-redis 命令执行错误
+    // node-redis command execution errors
     if (REDIS_EXEC_CODES.has(codeStr)) {
-      return `查询执行错误 [${codeStr}]: ${line}`;
+      return `Query execution error [${codeStr}]: ${line}`;
     }
-    // 未知 code：仍暴露 code + 首行（已脱敏截断），比「详情已隐藏」更利于排障
+    // Unknown code: still expose code + first line (sanitized and
+    // truncated); more useful for triage than "details hidden"
     return `[${codeStr}] ${line}`;
   }
 
-  // 无 code：无法分类，给中性措辞，不再误导成「连接失败」
+  // No code: cannot classify, use neutral wording instead of a misleading
+  // "connection failure"
   const name = err.name || 'Error';
-  return `${name}: ${line || '（无错误信息，请检查 SQL/命令与连接参数）'}`;
+  return `${name}: ${line || '(no error message; check the SQL/command and connection parameters)'}`;
 }
 
-// ── TLS 选项构建 ──
+// ── TLS options ──
 
 /**
- * 从 ca-file 路径构建 TLS 选项
+ * Build TLS options from a ca-file path
  * @param {string|undefined} caFile
  * @returns {object|undefined}
  */
@@ -198,7 +215,7 @@ function buildTlsOptions(caFile) {
   if (!caFile) return undefined;
   const resolved = path.resolve(caFile);
   if (!fs.existsSync(resolved)) {
-    throw new Error(`CA 证书文件不存在: ${resolved}`);
+    throw new Error(`CA certificate file not found: ${resolved}`);
   }
   const ca = fs.readFileSync(resolved);
   return { ca, rejectUnauthorized: true };