@carllee1983/dbcli 0.4.0-beta → 0.5.0-beta

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.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/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
 ```
 
@@ -438,6 +442,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 使用三層粗粒度權限模型，並搭配黑名單系統提供敏感表和欄位的細粒度保護（見[資料存取控制](#資料存取控制)）：
@@ -358,6 +364,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

@@ -176,6 +176,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 +233,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