@carllee1983/dbcli 0.4.0-beta → 0.5.2-beta

package/CHANGELOG.md

@@ -5,6 +5,59 @@ All notable changes to dbcli are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.2-beta] - 2026-03-27
+
+### Fixed
+
+- **`init --use-env-refs` permission bug**: Interactive env-ref mode now correctly offers all 4 permission levels (was missing `data-admin`)
+- **`init` i18n completeness**: All 10 hardcoded English messages replaced with i18n keys (supports en/zh-TW)
+- **`init` duplicate code**: Extracted shared `.dbcli exists` overwrite check into `checkOverwrite()` helper
+- **`--use-env-refs` help text**: Improved option description to clarify CI/CD and multi-env use case
+- **Documentation**: Added `--use-env-refs` to README (en/zh-TW), CHANGELOG, and SKILL.md with AI agent guidance
+
+---
+
+## [0.5.1-beta] - 2026-03-27
+
+### Added
+
+- **Database version check**: Warns on stderr when connected database version is below minimum supported (PostgreSQL 12+, MySQL 8.0+, MariaDB 10.5+). Non-blocking — connection proceeds normally.
+- **`dbcli doctor` DB version check**: New "Database version" item in Connection & Data group.
+- **`dbcli init --use-env-refs`**: Store environment variable references (`{"$env": "DB_HOST"}`) in config instead of actual values. Supports interactive and non-interactive modes with `--env-host`, `--env-port`, `--env-user`, `--env-password`, `--env-database` options. Suitable for CI/CD and multi-environment deployments.
+
+### Fixed
+
+- **`init` permission bug**: Interactive env-ref mode now correctly offers all 4 permission levels (was missing `data-admin`)
+- **`init` i18n**: All hardcoded English messages in init command replaced with i18n keys (10 messages)
+- **`init` duplicate code**: Extracted shared `.dbcli exists` overwrite check into `checkOverwrite()` helper
+
+---
+
+## [0.5.0-beta] - 2026-03-27
+
+### UX & Developer Experience — Colors, Logging, Diagnostics, and Tooling
+
+### Added
+
+- **Color system** (`picocolors`): Semantic color helpers (`success`/`error`/`warn`/`info`/`dim`/`bold`) with automatic `NO_COLOR` support
+- **SQL syntax highlighting**: Keywords (blue bold), strings (green), numbers (yellow) — applied in verbose mode and dry-run preview
+- **Leveled logger**: Four levels — quiet (`-q`), normal (default), verbose (`-v`), debug (`-vv`) — all output to stderr to keep stdout clean for structured data
+- **`--no-color` global flag**: Disable colored output; also respects `NO_COLOR` environment variable (<https://no-color.org/>)
+- **`-v, --verbose` global flag**: Increase verbosity (`-v` = verbose, `-vv` = debug)
+- **`-q, --quiet` global flag**: Suppress non-essential output
+- **`dbcli doctor` command**: Full self-diagnostic — checks Bun version, dbcli version (npm registry), config validity, permission level, blacklist completeness (detects unprotected sensitive columns like `password`/`token`/`secret`), database connectivity, schema cache freshness, and large table warnings (> 1M rows). Supports `--format json` for AI agents. Exits with code 1 on errors.
+- **`dbcli completion` command**: Shell auto-completion script generation for bash, zsh, and fish. `--install` flag auto-writes to the shell rc file using idempotent marker blocks.
+- **`dbcli upgrade` command**: Self-update from npm registry. `--check` flag for check-only mode.
+- **Background version check**: Every command silently checks the npm registry (at most once per 24 hours, cached in `.dbcli/version-check.json`). Shows a one-line hint to stderr after the command completes if a newer version is available. Suppressed by `--quiet`.
+- **Table formatter colorization**: Table headers now display in bold
+- **62 new tests**: colors (7), sql-highlight (6), logger (10), doctor (12), completion (8), upgrade/version-check (19)
+
+### Dependencies
+
+- Added `picocolors` (~0.4 KB) as production dependency
+
+---
+
 ## [0.2.0-beta] - 2026-03-26
 
 ### Data Access Control — Blacklist System

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carl Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -49,6 +49,10 @@ npx @carllee1983/dbcli query "SELECT * FROM users"
 #### Update
 
 ```bash
+# Self-update (recommended)
+dbcli upgrade
+
+# Or via npm
 npm update -g @carllee1983/dbcli
 ```
 
@@ -92,9 +96,27 @@ Initialize a new dbcli project with database connection configuration.
 
 **Usage:**
 ```bash
-dbcli init
+dbcli init [OPTIONS]
 ```
 
+**Options:**
+- `--system <type>` — Database system: `postgresql`, `mysql`, `mariadb`
+- `--host <host>` — Database host
+- `--port <port>` — Database port
+- `--user <user>` — Database user
+- `--password <pass>` — Database password
+- `--name <db>` — Database name
+- `--permission <level>` — Permission level: `query-only`, `read-write`, `data-admin`, `admin`
+- `--use-env-refs` — Store environment variable references instead of actual values in config
+- `--env-host <var>` — Env var name for host (with `--use-env-refs`)
+- `--env-port <var>` — Env var name for port (with `--use-env-refs`)
+- `--env-user <var>` — Env var name for user (with `--use-env-refs`)
+- `--env-password <var>` — Env var name for password (with `--use-env-refs`)
+- `--env-database <var>` — Env var name for database (with `--use-env-refs`)
+- `--skip-test` — Skip connection test
+- `--no-interactive` — Non-interactive mode (requires all options)
+- `--force` — Overwrite existing config without confirmation
+
 **Behavior:**
 - Reads `.env` file if present (auto-fills DATABASE_URL, DB_* variables)
 - Prompts for missing values (host, port, user, password, database name, permission level)
@@ -112,8 +134,20 @@ dbcli init
 
 # Specify permission level
 echo "PERMISSION_LEVEL=admin" >> .env && dbcli init
+
+# Store env var references instead of values (interactive)
+dbcli init --use-env-refs
+
+# Store env var references (non-interactive)
+dbcli init --use-env-refs --system mysql \
+  --env-host DB_HOST --env-port DB_PORT \
+  --env-user DB_USER --env-password DB_PASSWORD \
+  --env-database DB_DATABASE \
+  --no-interactive
 ```
 
+> **`--use-env-refs`:** When enabled, the config stores environment variable names (e.g., `{"$env": "DB_HOST"}`) instead of actual values. This avoids writing sensitive credentials into the config file, making it suitable for multi-environment deployments and CI/CD pipelines. At connection time, dbcli automatically reads the actual values from the referenced environment variables.
+
 ---
 
 #### `dbcli list`
@@ -438,6 +472,68 @@ DBCLI_OVERRIDE_BLACKLIST=true dbcli query "SELECT * FROM secrets_vault"
 
 ---
 
+#### `dbcli doctor`
+
+Run diagnostic checks on environment, configuration, connection, and data.
+
+```bash
+dbcli doctor                    # Colored text output
+dbcli doctor --format json      # JSON output for AI agents
+```
+
+**Checks:**
+- **Environment:** Bun version compatibility, dbcli version (compares with npm registry)
+- **Configuration:** Config file exists/valid, permission level, blacklist completeness
+- **Connection & Data:** Database connectivity, schema cache freshness (> 7 days warning), large table warnings (> 1M rows)
+
+**Options:** `--format <text|json>`
+**Exit code:** 0 = all pass or warnings only, 1 = errors found
+
+---
+
+#### `dbcli completion [shell]`
+
+Generate shell completion scripts for tab auto-complete.
+
+```bash
+dbcli completion bash            # Output bash completion to stdout
+dbcli completion zsh             # Output zsh completion to stdout
+dbcli completion fish            # Output fish completion to stdout
+dbcli completion --install       # Auto-detect shell and install to rc file
+dbcli completion --install zsh   # Install for specific shell
+```
+
+**Supported shells:** bash, zsh, fish
+
+---
+
+#### `dbcli upgrade`
+
+Check for updates and self-upgrade dbcli.
+
+```bash
+dbcli upgrade                   # Check and upgrade if newer version available
+dbcli upgrade --check           # Only check, do not upgrade
+```
+
+**Options:** `--check` — check only, don't install
+**Background check:** dbcli silently checks npm registry once per 24 hours. If a newer version is found, a hint is shown after command output.
+
+---
+
+## Global Options
+
+All commands support these global options:
+
+| Flag | Description |
+|------|-------------|
+| `--config <path>` | Path to .dbcli config file (default: `.dbcli`) |
+| `-v, --verbose` | Increase verbosity (`-v` verbose, `-vv` debug) |
+| `-q, --quiet` | Suppress non-essential output |
+| `--no-color` | Disable colored output (respects `NO_COLOR` env var) |
+
+---
+
 ## Permission Model
 
 dbcli implements a coarse-grained permission system with three levels. Permission level is set during `dbcli init` and stored in `.dbcli` config file. The blacklist system works alongside permissions to provide fine-grained protection for sensitive tables and columns (see [Data Access Control](#data-access-control)).

package/README.zh-TW.md

@@ -29,11 +29,11 @@ npm install --save-dev @carllee1983/dbcli
 ### 更新
 
 ```bash
-# Bun
-bun update @carllee1983/dbcli
+# 自動更新（推薦）
+dbcli upgrade
 
-# npm
-npm update --save-dev @carllee1983/dbcli
+# 或手動更新
+bun update @carllee1983/dbcli
 ```
 
 ### 初始化
@@ -142,6 +142,12 @@ dbcli init
 - 支援跨平台 AI 代理使用（Claude Code、Gemini、Copilot CLI、Cursor、IDE）
 - 技能動態反映 dbcli 功能
 
+### 診斷與維護
+
+- `dbcli doctor` — 執行環境、設定、連線與資料的全面診斷
+- `dbcli upgrade` — 檢查更新並自動升級 dbcli
+- `dbcli completion [shell]` — 產生 shell 自動補全腳本（bash、zsh、fish）
+
 ## 權限模型
 
 dbcli 使用三層粗粒度權限模型，並搭配黑名單系統提供敏感表和欄位的細粒度保護（見[資料存取控制](#資料存取控制)）：
@@ -232,8 +238,19 @@ dbcli init
 
 dbcli init --host db.example.com --port 5432 --user admin --password secret --name prod_db --system postgresql
 # 非交互式初始化
+
+dbcli init --use-env-refs
+# 交互式：提示輸入環境變數名稱，config 中儲存 {"$env": "DB_HOST"} 而非實際值
+
+dbcli init --use-env-refs --system mysql \
+  --env-host DB_HOST --env-port DB_PORT \
+  --env-user DB_USER --env-password DB_PASSWORD \
+  --env-database DB_DATABASE --no-interactive
+# 非交互式環境變數參照模式，適合 CI/CD
 ```
 
+> **`--use-env-refs` 說明：** 使用此選項時，config 中儲存的是環境變數名稱（如 `{"$env": "DB_HOST"}`）而非實際值。這樣可以避免將敏感資訊寫入 config 檔案，適合多環境部署或 CI/CD 場景。連線時 dbcli 會自動從環境變數讀取實際值。
+
 ### 列出表
 
 ```bash
@@ -358,6 +375,62 @@ dbcli blacklist column remove users.ssn
 DBCLI_OVERRIDE_BLACKLIST=true dbcli query "SELECT * FROM secrets_vault"
 ```
 
+#### `dbcli doctor`
+
+執行環境、設定、連線與資料的全面診斷。
+
+```bash
+dbcli doctor                    # 彩色文字輸出
+dbcli doctor --format json      # JSON 輸出供 AI agent 使用
+```
+
+**檢查項目：**
+- **環境：** Bun 版本相容性、dbcli 版本（與 npm registry 比對）
+- **設定：** 設定檔存在/合法、權限等級、blacklist 完整性
+- **連線與資料：** 資料庫連線測試、schema cache 新鮮度（> 7 天警告）、大表警告（> 1M 列）
+
+**選項：** `--format <text|json>`
+
+---
+
+#### `dbcli completion [shell]`
+
+產生 shell 自動補全腳本。
+
+```bash
+dbcli completion bash            # 輸出 bash 補全腳本
+dbcli completion zsh             # 輸出 zsh 補全腳本
+dbcli completion fish            # 輸出 fish 補全腳本
+dbcli completion --install       # 自動偵測 shell 並安裝
+dbcli completion --install zsh   # 指定 shell 安裝
+```
+
+**支援 shell：** bash、zsh、fish
+
+---
+
+#### `dbcli upgrade`
+
+檢查更新並自動升級 dbcli。
+
+```bash
+dbcli upgrade                   # 檢查並升級
+dbcli upgrade --check           # 僅檢查，不升級
+```
+
+**背景檢查：** 每個指令靜默檢查 npm registry（每 24 小時一次），有新版時在指令完成後顯示提示。
+
+## 全域選項
+
+以下選項適用於所有指令：
+
+| 選項 | 說明 |
+|------|------|
+| `--config <path>` | 指定 .dbcli 設定檔路徑（預設：`.dbcli`） |
+| `-v, --verbose` | 增加輸出詳細度（`-v` 詳細、`-vv` 除錯） |
+| `-q, --quiet` | 靜音模式，抑制非必要輸出 |
+| `--no-color` | 關閉彩色輸出（支援 `NO_COLOR` 環境變數） |
+
 ## 環境配置
 
 ### .dbcli 配置檔案

package/assets/SKILL.md

@@ -30,6 +30,8 @@ dbcli init --no-interactive --force # Non-interactive, skip overwrite confirmati
 
 **Key options:** `--system <postgresql|mysql|mariadb>`, `--permission <query-only|read-write|data-admin|admin>`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`
 
+> **AI agent note on `--use-env-refs`:** If an existing `.dbcli` config contains `{"$env": "DB_HOST"}` style references, the connection values are read from environment variables at runtime. Do NOT re-run `init` to replace these references with actual values — the env-ref format is intentional for CI/CD and multi-environment setups.
+
 ### list
 
 List all tables.
@@ -176,6 +178,50 @@ dbcli status --format text      # Human-readable text output
 **Output:** `permission`, `system`, `blacklist` summary, `version`
 **Permission:** query-only+
 
+### doctor
+
+Run diagnostic checks on environment, configuration, connection, and data.
+
+```bash
+dbcli doctor                    # Colored text output
+dbcli doctor --format json      # JSON output for AI agents
+```
+
+**Checks:**
+- Environment: Bun version, dbcli version (compares with npm registry)
+- 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)
+
+**Exit code:** 0 if all pass or warnings only, 1 if any error
+**Options:** `--format <text|json>`
+
+### completion
+
+Generate shell completion scripts for tab auto-complete.
+
+```bash
+dbcli completion bash            # Output bash completion script
+dbcli completion zsh             # Output zsh completion script
+dbcli completion fish            # Output fish completion script
+dbcli completion --install       # Auto-detect shell and install
+dbcli completion --install zsh   # Install for specific shell
+```
+
+**Supported shells:** bash, zsh, fish
+
+### upgrade
+
+Check for updates and self-upgrade dbcli to the latest version from npm.
+
+```bash
+dbcli upgrade                   # Check and upgrade if newer version available
+dbcli upgrade --check           # Only check, do not upgrade
+```
+
+**Options:** `--check`
+
+**Background check:** Every command silently checks the npm registry for a newer version (at most once per 24 hours, cached in `.dbcli/version-check.json`). If a newer version is found, a one-line hint is printed to stderr after the command completes. Pass `-q` / `--quiet` to suppress the hint.
+
 ## Permission Levels
 
 | Level | Allowed Operations |
@@ -189,7 +235,12 @@ Set via `dbcli init --permission <level>` or in `.dbcli` config.
 
 ## Global Options
 
-All commands support `--config <path>` to specify a custom config file (default: `.dbcli`).
+| Flag | Description |
+|------|-------------|
+| `--config <path>` | Path to .dbcli config file (default: `.dbcli`) |
+| `-v, --verbose` | Increase verbosity (`-v` verbose, `-vv` debug) |
+| `-q, --quiet` | Suppress non-essential output |
+| `--no-color` | Disable colored output (also respects `NO_COLOR` env var) |
 
 ## AI Agent Workflow