dsh-switchman 1.3.0

package/skills/db-query/references/mysql.md

@@ -0,0 +1,137 @@
+<!-- [2026-09-05]-[translated to English (skill is now English-only)]-[content unchanged] -->
+# MySQL Syntax Matrix & Query Recipes
+
+## Allowed / Rejected Statement Matrix
+
+### ✅ Allowed
+
+| Statement type | Example | Notes |
+|----------|------|------|
+| `SELECT` | `SELECT id, name FROM users WHERE id = 42` | Most common |
+| `WITH...SELECT` | `WITH c AS (SELECT 1) SELECT * FROM c` | CTE supported |
+| `SHOW` | `SHOW TABLES`, `SHOW CREATE TABLE t` | Metadata queries |
+| `DESCRIBE` / `DESC` | `DESC users`, `DESCRIBE users name` | Table structure |
+| `EXPLAIN SELECT` | `EXPLAIN SELECT * FROM users` | EXPLAIN SELECT only, no ANALYZE |
+
+### ❌ Rejected
+
+| Statement type | Rejection reason |
+|----------|----------|
+| `INSERT / UPDATE / DELETE / REPLACE` | Write operations |
+| `DROP / ALTER / CREATE / TRUNCATE / RENAME` | DDL |
+| `GRANT / REVOKE` | Privilege management |
+| `SET` | Session variable changes |
+| `LOCK / UNLOCK TABLES` | Explicit locks |
+| `CALL / EXECUTE` | Stored procedures |
+| `LOAD DATA / INTO OUTFILE` | File operations |
+| `START TRANSACTION / COMMIT / ROLLBACK` | Transaction control is managed by the script |
+| `HANDLER` | Low-level table access interface |
+| All comments (`#`, `-- `, `/* */`, `/*! */`, `/*+ */`) | Can nest malicious SQL |
+| Backslash escapes (`\`) | Can craft dangerous syntax |
+| Multiple statements (`;` separated) | Prevents concatenation injection |
+| `FOR UPDATE` / `LOCK IN SHARE MODE` | Explicit locking |
+| `SLEEP()` / `BENCHMARK()` / `GET_LOCK()` | Potential DoS |
+| `INTO OUTFILE` | Server-side file writes |
+| `EXPLAIN ANALYZE` | Actually executes the query; blocked as a security trade-off |
+
+### Common "legal" forms that get rejected, and alternatives
+
+| Intent | Rejected form | Alternative |
+|--------|-------------|----------|
+| Query SQL with comments | `SELECT 1 /* comment */` | Remove the comment |
+| Backticks + trailing comment | `` SELECT `id` FROM `t` -- comment `` | Remove the comment |
+| Dynamic LIMIT (variables) | `PREPARE` + `EXECUTE` | Write a literal number |
+| Execution analysis | `EXPLAIN ANALYZE SELECT ...` | Use `EXPLAIN SELECT ...` (no execution) |
+| Multiple statements at once | `SELECT 1; SELECT 2` | Split into separate calls |
+| Write inside a subquery | `SELECT (UPDATE ...)` | Not allowed; all writes are refused |
+
+## Common read-only recipes
+
+### Single record by primary key
+
+```bash
+./scripts/mysql-query.js --user=reader --database=mydb \
+  'SELECT id, username, email, status FROM users WHERE id = 42'
+```
+
+### Recent changes by time range
+
+```bash
+./scripts/mysql-query.js --user=reader --database=mydb --max-rows=50 \
+  "SELECT id, status, updated_at FROM orders WHERE updated_at >= '2024-06-01 00:00:00' ORDER BY updated_at DESC"
+```
+
+### Aggregate counts (grouped by status)
+
+```bash
+./scripts/mysql-query.js --user=reader --database=mydb \
+  'SELECT status, COUNT(*) AS cnt FROM users GROUP BY status ORDER BY cnt DESC'
+```
+
+### JOIN to verify related data
+
+```bash
+# Verify order ↔ user consistency
+./scripts/mysql-query.js --user=reader --database=mydb --max-rows=30 \
+  'SELECT o.id AS order_id, o.user_id, u.username, o.amount FROM orders o JOIN users u ON o.user_id = u.id WHERE o.status = "pending" ORDER BY o.created_at DESC'
+```
+
+### Execution plan
+
+```bash
+./scripts/mysql-query.js --user=reader --database=mydb \
+  'EXPLAIN SELECT * FROM orders WHERE user_id = 100 AND created_at >= "2024-01-01"'
+```
+
+### Table structure
+
+```bash
+./scripts/mysql-query.js --user=reader --database=mydb 'DESCRIBE orders'
+
+# or use SHOW
+./scripts/mysql-query.js --user=reader --database=mydb 'SHOW CREATE TABLE orders'
+```
+
+### Connectivity test
+
+```bash
+./scripts/mysql-query.js --user=reader --database=mydb 'SELECT 1'
+```
+
+## LIMIT & truncation behavior
+
+| Scenario | Behavior |
+|------|------|
+| SQL has no `LIMIT` clause | Script auto-injects `LIMIT <max-rows>` (default 200) |
+| SQL has `LIMIT n` with `n <= max-rows` | Executed as-is |
+| SQL has `LIMIT n` with `n > max-rows` | Validation rejects it: LIMIT exceeds the cap |
+| Actual rows reach `max-rows` | Trailing notice "result truncated"; refine the query and re-run |
+
+> ⚠️ The auto-injected LIMIT applies to the outermost query. Subqueries and UNION internals are unaffected (the outer LIMIT still protects).
+
+## Field type output conventions
+
+| MySQL type | Output form | Notes |
+|------------|----------|------|
+| INT / TINYINT / SMALLINT / MEDIUMINT | Number | Normal range |
+| BIGINT | String | Avoids exceeding JS Number.MAX_SAFE_INTEGER |
+| DECIMAL / NUMERIC | String | Avoids floating-point precision loss |
+| FLOAT / DOUBLE | Number | Precision loss possible |
+| DATE / DATETIME / TIMESTAMP | String | `dateStrings` mode, no timezone conversion |
+| CHAR / VARCHAR / TEXT | String | As-is |
+| JSON | Formatted string | Pretty-printed after JSON.parse |
+| BLOB / BINARY | Base64 string | Binary-safe representation |
+| NULL | `null` | null in JSON, NULL in table output |
+
+## Offline validation
+
+Use `--validate-only` to check SQL safety without connecting:
+
+```bash
+# Validate first, then execute
+./scripts/mysql-query.js --validate-only 'SELECT id FROM users WHERE id = 42'
+# Once it passes, drop --validate-only and execute
+./scripts/mysql-query.js --user=reader --database=mydb 'SELECT id FROM users WHERE id = 42'
+```
+
+Validation covers: statement type allowlist, comments/backslash/multi-statement/dangerous functions, and LIMIT compliance.

package/skills/db-query/references/redis.md

@@ -0,0 +1,213 @@
+<!-- [2026-09-05]-[translated to English (skill is now English-only)]-[content unchanged] -->
+# Redis Command Whitelist & Query Patterns
+
+## Full command-args-return reference
+
+### General / key operations
+
+| Command | Args | Return form | Notes |
+|------|------|----------|------|
+| `PING` | none | `PONG` (string) | Connectivity test |
+| `GET key` | key | String value or `(nil)` | Read a String value |
+| `MGET key [key ...]` | 1+ keys | Array of values (in order) | Batch read Strings |
+| `EXISTS key [key ...]` | 1+ keys | Count of existing keys | Check key existence |
+| `TYPE key` | key | Type string | Key's data type |
+| `TTL key` | key | Remaining seconds (integer) | Time until expiry |
+| `PTTL key` | key | Remaining milliseconds (integer) | Expiry in ms precision |
+| `STRLEN key` | key | String length | Byte length of String value |
+| `SCAN cursor [MATCH pattern] [COUNT count]` | cursor, optional args | Cursor + key list | Incremental key iteration |
+| `KEYS pattern`† | pattern | Key list | Full key match (blocking risk) |
+| `DBSIZE` | none | Total key count | Key count in current db |
+| `TIME` | none | Unix timestamp (sec.µs) | Server current time |
+
+### Hash operations
+
+| Command | Args | Return form | Notes |
+|------|------|----------|------|
+| `HGET key field` | key, field | Field value or `(nil)` | Read a single field |
+| `HMGET key field [field ...]` | key, 1+ fields | Array of values | Batch read fields |
+| `HEXISTS key field` | key, field | 1 (exists) / 0 (missing) | Check field existence |
+| `HLEN key` | key | Field count | Number of hash fields |
+| `HGETALL key`† | key | Alternating field-value array | Full dump (blocking risk) |
+| `HKEYS key`† | key | Field name array | All field names (blocking risk) |
+| `HVALS key`† | key | Value array | All values (blocking risk) |
+| `HSCAN key cursor [MATCH pattern] [COUNT count]` | key, cursor, optional | Cursor + field-value pairs | Incremental hash iteration |
+
+### List operations
+
+| Command | Args | Return form | Notes |
+|------|------|----------|------|
+| `LINDEX key index` | key, index | Element or `(nil)` | Element by index |
+| `LLEN key` | key | List length | Element count |
+| `LRANGE key start stop` | key, start/stop indexes | Element array | Elements in range |
+
+### Set operations
+
+| Command | Args | Return form | Notes |
+|------|------|----------|------|
+| `SISMEMBER key member` | key, member | 1 (member) / 0 (not) | Membership check |
+| `SCARD key` | key | Member count | Set size |
+| `SMEMBERS key`† | key | Member array | Full dump (blocking risk) |
+| `SSCAN key cursor [MATCH pattern] [COUNT count]` | key, cursor, optional | Cursor + member list | Incremental set iteration |
+
+### ZSet operations
+
+| Command | Args | Return form | Notes |
+|------|------|----------|------|
+| `ZCARD key` | key | Member count | ZSet size |
+| `ZCOUNT key min max` | key, score range | Count | Count by score range |
+| `ZSCORE key member` | key, member | Score or `(nil)` | Member's score |
+| `ZRANK key member` | key, member | Rank or `(nil)` | Ascending rank (0-based) |
+| `ZREVRANK key member` | key, member | Rank or `(nil)` | Descending rank (0-based) |
+| `ZRANGE key start stop [WITHSCORES]` | key, start/stop, optional | Member (+score) array | Query by rank range |
+| `ZRANGEBYSCORE key min max [WITHSCORES]` | key, score range, optional | Member (+score) array | Query by score range |
+| `ZSCAN key cursor [MATCH pattern] [COUNT count]` | key, cursor, optional | Cursor + member-score pairs | Incremental zset iteration |
+
+### Server info
+
+| Command | Args | Return form | Notes |
+|------|------|----------|------|
+| `INFO [section]` | optional section | Info text block | Server info & stats |
+| `CLIENT LIST` | none | Client connection list | Current connections |
+| `CONFIG GET parameter`† | Parameter name | Parameter value | Read config (safe items only) |
+
+> † Requires the `--allow-unbounded` flag.
+
+## SCAN-family cursor usage
+
+SCAN-family commands iterate incrementally with a cursor and never block Redis.
+
+### Basic pattern
+
+```bash
+# SCAN instead of KEYS to iterate keys
+./scripts/redis-query.js -- SCAN 0 MATCH user:* COUNT 100
+# Returns: next cursor + key list
+# Cursor 0 means iteration is complete
+
+# Multi-round iteration (manual loop)
+./scripts/redis-query.js -- SCAN 0 MATCH user:* COUNT 100
+# Returns cursor=42, keys=[user:1, user:2, ...]
+./scripts/redis-query.js -- SCAN 42 MATCH user:* COUNT 100
+# Returns cursor=0 (done)
+```
+
+### Per-type SCAN
+
+```bash
+# Incremental hash iteration
+./scripts/redis-query.js -- HSCAN session:abc 0 COUNT 50
+./scripts/redis-query.js -- HSCAN session:abc 128 COUNT 50  # next round
+
+# Incremental set iteration
+./scripts/redis-query.js -- SSCAN online:users 0 COUNT 100
+
+# Incremental zset iteration
+./scripts/redis-query.js -- ZSCAN leaderboard 0 COUNT 100
+```
+
+### SCAN caveats
+
+- `COUNT` is a hint; actual batch sizes may differ (Redis internals).
+- Cursor `0` means done, but keys added/removed during iteration may be missed or repeated.
+- `MATCH` filters server-side: it reduces network transfer, not traversal work.
+
+## TTL / PTTL return values
+
+| Return | Meaning | Notes |
+|--------|------|------|
+| `>= 0` | Remaining lifetime | TTL in seconds, PTTL in milliseconds |
+| `-1` | No expiry | Key exists without a TTL set |
+| `-2` | Key missing | Expired and removed, or never created |
+
+```bash
+./scripts/redis-query.js -- TTL cache:homepage
+# 300 → expires in 5 minutes
+# -1 → no expiry
+# -2 → key missing
+```
+
+## Safe query steps per data type
+
+Recommended pattern: **run `TYPE` first, then pick the matching command**.
+
+### String
+
+```bash
+./scripts/redis-query.js -- TYPE user:42          # confirm it's a string
+./scripts/redis-query.js -- GET user:42           # read value
+./scripts/redis-query.js -- TTL user:42           # check expiry
+./scripts/redis-query.js -- STRLEN user:42        # check length
+```
+
+### Hash
+
+```bash
+./scripts/redis-query.js -- TYPE user:42          # confirm it's a hash
+./scripts/redis-query.js -- HLEN user:42          # field count (size hint)
+./scripts/redis-query.js -- HGET user:42 name     # single field
+./scripts/redis-query.js -- HMGET user:42 name email status  # batch fields
+./scripts/redis-query.js -- HSCAN user:42 0 COUNT 100  # batched iteration (recommended)
+# For small keys, HGETALL works (needs --allow-unbounded)
+./scripts/redis-query.js --allow-unbounded -- HGETALL user:42
+```
+
+### List
+
+```bash
+./scripts/redis-query.js -- TYPE task:queue       # confirm it's a list
+./scripts/redis-query.js -- LLEN task:queue       # length
+./scripts/redis-query.js -- LRANGE task:queue 0 9 # first 10 (non-negative indexes, range ≤ max-items)
+# For the tail: LLEN first, then compute a non-negative index; negative-index LRANGE ranges are unpredictable and need --allow-unbounded
+./scripts/redis-query.js -- LLEN task:queue
+./scripts/redis-query.js --allow-unbounded -- LRANGE task:queue -10 -1  # explicitly allowed negative range
+./scripts/redis-query.js -- LINDEX task:queue -1  # last element (single value; negative index unrestricted)
+```
+
+### Set
+
+```bash
+./scripts/redis-query.js -- TYPE online:users     # confirm it's a set
+./scripts/redis-query.js -- SCARD online:users    # member count
+./scripts/redis-query.js -- SISMEMBER online:users user:42  # membership check
+./scripts/redis-query.js -- SSCAN online:users 0 COUNT 100  # batched iteration
+```
+
+### ZSet
+
+```bash
+./scripts/redis-query.js -- TYPE leaderboard      # confirm it's a zset
+./scripts/redis-query.js -- ZCARD leaderboard     # member count
+./scripts/redis-query.js -- ZSCORE leaderboard user:42   # score lookup
+./scripts/redis-query.js -- ZRANK leaderboard user:42    # ascending rank
+./scripts/redis-query.js -- ZRANGEBYSCORE leaderboard 100 999 WITHSCORES  # score range
+./scripts/redis-query.js -- ZSCAN leaderboard 0 COUNT 100  # batched iteration
+```
+
+## Unbounded command risks & SCAN alternatives
+
+These commands can block Redis for a long time on big keys (single-threaded model) and **require `--allow-unbounded` by default**:
+
+| Dangerous command | Reason | SCAN alternative |
+|----------|------|-----------|
+| `KEYS pattern` | O(N) over all keys | `SCAN 0 MATCH pattern COUNT 100` |
+| `HGETALL key` | O(N) returns all fields | `HSCAN key 0 COUNT 100` |
+| `HKEYS key` | O(N) returns all field names | `HSCAN key 0 COUNT 100` (ignore values) |
+| `HVALS key` | O(N) returns all values | `HSCAN key 0 COUNT 100` (ignore field names) |
+| `SMEMBERS key` | O(N) returns all members | `SSCAN key 0 COUNT 100` |
+
+**Production principle**: prefer SCAN; use `--allow-unbounded` only when the key is known to be small.
+
+## CONFIG GET safe-parameter whitelist
+
+`CONFIG GET` only allows these parameters (no credential leaks, no service behavior impact):
+
+| Parameter | Notes |
+|------|------|
+| `maxmemory` | Max memory limit |
+| `maxmemory-policy` | Eviction policy |
+| `timeout` | Client idle timeout |
+| `tcp-keepalive` | TCP keepalive interval |
+| `databases` | Number of databases |
+
+Querying other parameters (e.g. `requirepass`, `masterauth`, `save`) is rejected to prevent leaking sensitive config.

package/skills/db-query/references/security.md

@@ -0,0 +1,176 @@
+<!-- [2026-09-05]-[translated to English (skill is now English-only)]-[content unchanged] -->
+# Read-Only Security Model
+
+Security core of this skill: **three layers of defense guarantee read-only; any write operation is intercepted before it reaches the database**.
+Application-layer interception cannot replace database privileges, though — production must use a dedicated read-only account.
+
+## Threat model & attack surface
+
+### Who can trigger this skill
+
+- A user asking (via conversation) to query the database → the agent invokes the script
+- A user unintentionally or deliberately passing SQL/commands containing writes
+
+### Attack surface
+
+1. **SQL injection**: achieving writes via SQL syntax (nested comments, newlines inside strings, etc.)
+2. **Dangerous functions**: calling `SLEEP()`, `BENCHMARK()`, `GET_LOCK()` etc. through a legal SELECT (DoS)
+3. **Multi-statement injection**: concatenating write statements with semicolons
+4. **Redis command injection**: executing write commands via arguments or variants
+
+## MySQL three-layer defense
+
+### Layer 1: SQL lexical scanner
+
+Before connecting, the script lexically scans the raw SQL text.
+
+**Allowed statement types:**
+- `SELECT ...`
+- `WITH ... SELECT ...` (CTE)
+- `SHOW ...`
+- `DESCRIBE` / `DESC ...`
+- `EXPLAIN SELECT ...`
+
+**Rejected writes:** INSERT / UPDATE / DELETE / REPLACE / DROP / ALTER / CREATE / TRUNCATE / RENAME / GRANT / REVOKE / SET / LOCK / UNLOCK / CALL / LOAD DATA etc.
+
+**Rejected comment forms (all banned, including legal SQL inside comments):**
+- `#` single-line comment
+- `-- ` (double dash + space) single-line comment
+- `/* */` multi-line comment
+- `/*! */` MySQL version comment
+- `/*+ */` optimizer hint
+
+> **Why ban comments?** Comments can nest malicious SQL (e.g. `SELECT 1; /* */ DROP TABLE x;`) and hide version-specific syntax. A lexical scanner cannot safely parse comment contents, so they are rejected outright.
+
+**Additional restrictions:**
+- No backslash escapes (`\`) — prevents crafting legal-but-dangerous syntax via escapes
+- No multi-statements (`;` separated) — prevents concatenated writes
+- No `INTO OUTFILE` (exports to the server filesystem)
+- No `FOR UPDATE` / `LOCK IN SHARE MODE` (explicit locking)
+- No potential DoS functions like `SLEEP()` / `BENCHMARK()` / `GET_LOCK()`
+- Auto-inject a top-level `LIMIT` when none is present (prevents long-blocking full scans)
+
+> **Why a lexical scanner instead of regex?** Regex cannot reliably handle SQL string literals, identifier quoting (backticks), and operator ambiguity. A token-by-token scanner is more reliable than regex, yet it is still not a full SQL parser — complex but legal SQL may be rejected. That is a security trade-off.
+
+### Layer 2: connection-level protection
+
+Once connected:
+- `multipleStatements: false`: the mysql2 driver explicitly disables multi-statement execution; even if the scanner misses a semicolon, subsequent statements never run
+- `START TRANSACTION READ ONLY`: an explicit read-only transaction; the MySQL server itself rejects writes
+- Always `ROLLBACK` after the query; never `COMMIT`
+
+> **Why START TRANSACTION READ ONLY + ROLLBACK?** Defense in depth: even if the lexical scanner were bypassed (theoretically possible), the read-only transaction intercepts writes server-side, and ROLLBACK guarantees no side effects.
+
+### Layer 3: account-level privileges
+
+**Strongly recommended**: a dedicated read-only MySQL account granted only SELECT and SHOW VIEW.
+This is the final boundary — even if both layers above fail, account privileges still block writes.
+
+> ⚠️ **The admin commands below are for DBAs only; this skill's scripts never execute them:**
+
+```sql
+-- Read-only account setup example (for reference only)
+CREATE USER 'db_query_reader'@'%' IDENTIFIED BY 'strong-password';
+GRANT SELECT, SHOW VIEW ON `mydb`.* TO 'db_query_reader'@'%';
+FLUSH PRIVILEGES;
+```
+
+## Redis security model
+
+### Whitelist design
+
+Redis uses a **command whitelist**, not a blacklist.
+
+**Why a whitelist?**
+- A blacklist must enumerate every dangerous command, but Redis keeps adding new ones and Redis Modules can register custom commands. A whitelist rejects unknown commands by default (fail-closed) — safer.
+- Blacklists are easily bypassed by new/module commands.
+
+### Allowed commands (full list)
+
+| Category | Commands | Notes |
+|------|------|------|
+| **General** | PING, GET, MGET, EXISTS, TYPE, TTL, PTTL, STRLEN, SCAN, KEYS†, DBSIZE, TIME | |
+| **Hash** | HGET, HMGET, HEXISTS, HLEN, HGETALL†, HKEYS†, HVALS†, HSCAN | |
+| **List** | LINDEX, LLEN, LRANGE | |
+| **Set** | SISMEMBER, SCARD, SMEMBERS†, SSCAN | |
+| **ZSet** | ZCARD, ZCOUNT, ZSCORE, ZRANK, ZREVRANK, ZRANGE, ZRANGEBYSCORE, ZSCAN | |
+| **Server info** | INFO, CLIENT LIST, CONFIG GET† | CONFIG GET limited to safe items |
+
+> † Requires `--allow-unbounded`. These can block Redis on big keys; prefer SCAN in production.
+
+### Rejected commands
+
+Everything not on the whitelist is rejected (fail-closed), including but not limited to:
+- **Write commands**: SET, DEL, EXPIRE, INCR, DECR, HSET, LPUSH, SADD, ZADD, PFADD etc.
+- **Dangerous commands**: FLUSHALL, FLUSHDB, SHUTDOWN, DEBUG, EVAL, EVALSHA, SCRIPT
+- **Admin commands**: CONFIG SET, RENAME, MOVE, RESTORE, MIGRATE, SORT (may write to external storage)
+- **Unrecognized commands**: including those registered by Redis Modules
+
+### db is chosen via connection config
+
+The Redis `db` number can only be set through the `--db` connection option; the **`SELECT` command is not exposed**.
+This prevents switching databases mid-query and avoids touching the wrong db.
+
+### Gate mechanism for KEYS and other big commands
+
+`KEYS`, `HGETALL`, `HKEYS`, `HVALS`, `SMEMBERS` can block Redis for a long time on big keys (single-threaded model).
+They are rejected by default and require an explicit `--allow-unbounded`, forcing awareness of the risk.
+
+**Production alternative — SCAN-family commands:**
+- `KEYS pattern` → `SCAN 0 MATCH pattern COUNT 100`
+- `HGETALL key` → `HSCAN key 0 COUNT 100`
+- `SMEMBERS key` → `SSCAN key 0 COUNT 100`
+
+### CONFIG GET safe-parameter whitelist
+
+`CONFIG GET` only allows these safe parameters (read-only config that doesn't affect service behavior):
+- `maxmemory`
+- `maxmemory-policy`
+- `timeout`
+- `tcp-keepalive`
+- `databases`
+
+Other config items (e.g. `requirepass`, `masterauth`) may leak credentials and are always rejected.
+
+### Redis ACL as the final server-side boundary
+
+**Strongly recommended**: a dedicated Redis ACL user for queries:
+```
+# Redis ACL example (for DBAs/ops only)
+ACL SETUSER db_query_reader on >password ~* +@read +ping +info +client|list +config|get
+```
+
+> ⚠️ A client-side timeout (`--timeout-ms`) only closes the client socket; it **does not cancel the command running server-side**. If a command takes too long on the server (e.g. `KEYS *` over a million keys), Redis keeps executing it after the client disconnects, blocking other requests meanwhile. This is inherent to Redis's single-threaded model, which is why the script gates dangerous commands client-side.
+
+## Credentials & TLS conventions
+
+### Password safety
+
+- **No CLI `--password`**: command-line arguments land in shell history (`~/.bash_history` / `~/.zsh_history`) and may be readable by others.
+- **Recommended**:
+  1. Environment variables (`DB_QUERY_MYSQL_PASSWORD` / `DB_QUERY_REDIS_PASSWORD`)
+  2. Env file (`--env-file=<path>`) with `0600` permissions
+- Scripts never echo passwords in output.
+
+### TLS
+
+- Both MySQL and Redis support `--tls` for encrypted connections.
+- `--ca-file` specifies a CA certificate for server identity verification.
+- **Enable TLS** for cross-network connections in production.
+
+## Failure mode: fail-closed
+
+All safety checks follow the **fail-closed** principle:
+- Unknown token in the SQL lexical scan → reject
+- Unknown Redis command → reject
+- Timeout → disconnect, never continue
+- No "lenient mode" or fallback — a rejection is a rejection
+
+## Known limitations
+
+| Limitation | Impact | Mitigation |
+|------|------|------|
+| Lexer is not a full SQL parser | Complex but legal SQL (comments, backslash escapes, dynamic LIMIT, EXPLAIN ANALYZE) is rejected | Security trade-off; no lenient fallback added |
+| MySQL `MAX_EXECUTION_TIME` only on 5.7.8+/8.0 | Query timeout not guaranteed on MariaDB | Dedicated read-only account + connection-level timeout as backstop |
+| Redis client timeout doesn't cancel server-side commands | Big-key commands can keep blocking Redis | Gate dangerous commands client-side; restrict via ACL server-side |
+| Application-layer checks can't replace DB privileges | A script bug could bypass client-side checks | Dedicated read-only account + ACL mandatory in production/shared environments |

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

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * 严格 CLI 参数解析器
+ * 支持 --key=value、--key value、布尔 flag、-- 分隔 SQL/Redis 命令
+ * 未知选项、重复冲突、越界数字 → 立即失败（fail-closed）
+ */
+
+class CliError extends Error {
+  constructor(msg) { super(msg); this.name = 'CliError'; }
+}
+
+/**
+ * 解析 CLI 参数，返回 { options: {}, rest: string[] }
+ * @param {string[]} argv - process.argv.slice(2)
+ * @param {object} spec - 参数规格 { name: { type, default, min, max, alias } }
+ */
+function parseCli(argv, spec) {
+  const options = {};
+  const rest = [];
+  const seen = new Set();
+
+  // 填充默认值
+  for (const [key, def] of Object.entries(spec)) {
+    if (def.default !== undefined) options[key] = def.default;
+  }
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    // -- 分隔符：后续全部作为位置参数
+    if (arg === '--') {
+      rest.push(...argv.slice(i + 1));
+      break;
+    }
+
+    // --option=value 或 --option value 形式
+    if (arg.startsWith('--')) {
+      let key, value;
+      const eqIdx = arg.indexOf('=');
+      if (eqIdx !== -1) {
+        key = arg.slice(2, eqIdx);
+        value = arg.slice(eqIdx + 1);
+      } else {
+        key = arg.slice(2);
+        // 查找规格中该选项的类型
+        const s = findSpec(spec, key);
+        if (!s) throw new CliError(`未知选项: --${key}`);
+        if (s.type === 'boolean') {
+          value = true;
+        } else {
+          i++;
+          if (i >= argv.length) throw new CliError(`--${key} 需要值`);
+          value = argv[i];
+        }
+      }
+
+      const resolved = resolveAlias(spec, key);
+      if (!resolved) throw new CliError(`未知选项: --${key}`);
+
+      // 重复选项检查
+      if (seen.has(resolved)) throw new CliError(`重复选项: --${resolved}`);
+      seen.add(resolved);
+
+      const s = spec[resolved];
+      options[resolved] = coerceValue(resolved, value, s);
+    } else {
+      // 非选项参数 → 位置参数
+      rest.push(arg);
+    }
+    i++;
+  }
+
+  return { options, rest };
+}
+
+/** 在 spec 或 alias 中查找选项名 */
+function findSpec(spec, key) {
+  if (spec[key]) return spec[key];
+  for (const s of Object.values(spec)) {
+    if (s.alias === key) return s;
+  }
+  return null;
+}
+
+/** 解析别名到规范名 */
+function resolveAlias(spec, key) {
+  if (spec[key]) return key;
+  for (const [name, s] of Object.entries(spec)) {
+    if (s.alias === key) return name;
+  }
+  return null;
+}
+
+/** 类型转换 + 边界检查 */
+function coerceValue(key, raw, spec) {
+  if (spec.type === 'boolean') {
+    if (raw === 'true' || raw === true) return true;
+    if (raw === 'false' || raw === false) return false;
+    throw new CliError(`--${key} 期望布尔值，收到: ${raw}`);
+  }
+  if (spec.type === 'integer') {
+    const n = Number(raw);
+    if (!Number.isInteger(n)) throw new CliError(`--${key} 期望整数，收到: ${raw}`);
+    if (spec.min !== undefined && n < spec.min) throw new CliError(`--${key} 最小值 ${spec.min}，收到: ${n}`);
+    if (spec.max !== undefined && n > spec.max) throw new CliError(`--${key} 最大值 ${spec.max}，收到: ${n}`);
+    return n;
+  }
+  if (spec.type === 'string' && spec.choices) {
+    const lower = String(raw).toLowerCase();
+    if (!spec.choices.includes(lower)) throw new CliError(`--${key} 必须为 ${spec.choices.join('|')} 之一，收到: ${raw}`);
+    return lower;
+  }
+  return String(raw);
+}
+
+module.exports = { parseCli, CliError };