@carllee1983/dbcli 0.3.2-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

@@ -0,0 +1,376 @@
+---
+name: dbcli
+description: Database CLI for AI agents with permission-based access control. Use to query, inspect schemas, insert/update/delete data, export results, and manage sensitive data blacklists. Supports MySQL, PostgreSQL, MariaDB. Trigger when working with databases, running SQL, exploring table structures, or protecting sensitive columns/tables from AI access.
+---
+
+# dbcli
+
+Database CLI for AI agents with permission-based access control.
+
+## Quick Start
+
+```bash
+dbcli init                          # Initialize .dbcli config (parses .env automatically)
+dbcli schema                        # Scan all tables and save to .dbcli
+dbcli query "SELECT * FROM users"   # Execute SQL
+```
+
+## Commands
+
+### init
+
+Initialize `.dbcli` configuration file. Typically run manually by the developer — avoid running on behalf of the user unless explicitly requested.
+
+```bash
+dbcli init
+dbcli init --system mysql --host localhost --port 3306 --user root --name mydb
+dbcli init --use-env-refs           # Store env var references instead of values
+dbcli init --no-interactive --force # Non-interactive, skip overwrite confirmation
+```
+
+**Key options:** `--system <postgresql|mysql|mariadb>`, `--permission <query-only|read-write|data-admin|admin>`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`
+
+### list
+
+List all tables.
+
+```bash
+dbcli list
+dbcli list --format json
+```
+
+**Permission:** query-only+
+
+### schema
+
+Display table schema or scan entire database.
+
+```bash
+dbcli schema                        # Scan all tables, save to .dbcli
+dbcli schema users                  # Show single table schema
+dbcli schema users --format json
+dbcli schema --refresh              # Detect and apply schema changes
+dbcli schema --reset                # Clear all schema data and re-fetch
+dbcli schema --reset --force        # Skip confirmation
+```
+
+**Options:** `--format <table|json>`, `--refresh`, `--reset`, `--force`
+**Permission:** query-only+
+
+### query
+
+Execute SQL query.
+
+```bash
+dbcli query "SELECT * FROM users LIMIT 10"
+dbcli query "SELECT id, email FROM users" --format json
+dbcli query "SELECT * FROM logs" --no-limit
+```
+
+**Options:** `--format <table|json|csv>`, `--limit <number>`, `--no-limit`
+**Permission:** query-only+
+
+### insert
+
+Insert data into a table.
+
+```bash
+dbcli insert users --data '{"name":"Alice","email":"alice@example.com"}'
+dbcli insert users --data '{"name":"Alice"}' --dry-run
+dbcli insert users --data '{"name":"Alice"}' --force
+```
+
+**Options:** `--data <json>`, `--dry-run`, `--force`
+**Permission:** read-write+
+
+### update
+
+Update existing data.
+
+```bash
+dbcli update users --where "id=1" --set '{"name":"Bob"}'
+dbcli update users --where "id=1" --set '{"name":"Bob"}' --dry-run
+```
+
+**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`
+**Permission:** read-write+
+
+### delete
+
+Delete data from a table.
+
+```bash
+dbcli delete users --where "id=1"
+dbcli delete users --where "id=1" --dry-run
+dbcli delete users --where "id=1" --force
+```
+
+**Options:** `--where <condition>` (required), `--dry-run`, `--force`
+**Permission:** data-admin+
+
+### export
+
+Export query results to file or stdout.
+
+```bash
+dbcli export "SELECT * FROM users" --format csv --output users.csv
+dbcli export "SELECT * FROM users" --format json | jq '.[]'
+```
+
+**Options:** `--format <json|csv>` (required), `--output <path>`
+**Permission:** query-only+
+
+### blacklist
+
+Manage sensitive data blacklist to prevent AI access to restricted tables/columns.
+
+```bash
+dbcli blacklist list                        # Show current blacklist
+dbcli blacklist table add payments          # Block entire table
+dbcli blacklist table remove payments       # Unblock table
+dbcli blacklist column add users.password   # Block specific column
+dbcli blacklist column remove users.password
+```
+
+**Subcommands:** `list`, `table add <name>`, `table remove <name>`, `column add <table.column>`, `column remove <table.column>`
+
+### check
+
+Run data health checks on tables.
+
+```bash
+dbcli check users                           # Check single table
+dbcli check users --format json             # JSON output (default)
+dbcli check --all                           # Check all tables (huge tables auto-skipped)
+dbcli check --all --include-large           # Include huge tables
+dbcli check orders --checks nulls,orphans   # Specific checks only
+dbcli check orders --sample 10000           # Sample size for large tables
+```
+
+**Checks:** `nulls`, `duplicates`, `orphans`, `emptyStrings`, `rowCount`, `size`
+**Options:** `--all`, `--include-large`, `--checks <types>`, `--sample <number>`, `--format <json|table>`
+**Permission:** query-only+
+
+### diff
+
+Compare schema snapshots to detect changes.
+
+```bash
+dbcli diff --snapshot before.json           # Save current schema snapshot
+dbcli diff --against before.json            # Compare current vs snapshot
+dbcli diff --against before.json --format json
+```
+
+**Options:** `--snapshot <path>`, `--against <path>`, `--format <json|table>`
+**Permission:** query-only+
+
+### status
+
+Show current configuration status (safe for AI agents, no credentials exposed).
+
+```bash
+dbcli status                    # JSON output (default)
+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 |
+|-------|-------------------|
+| query-only | SELECT, list, schema, export |
+| read-write | query-only + INSERT, UPDATE |
+| data-admin | read-write + DELETE (full DML, no DDL) |
+| admin | data-admin + DROP, ALTER, CREATE, TRUNCATE |
+
+Set via `dbcli init --permission <level>` or in `.dbcli` config.
+
+## 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 (also respects `NO_COLOR` env var) |
+
+## AI Agent Workflow
+
+**Before any database operation, follow this sequence:**
+
+1. `dbcli status` — Check current permission level and system info (safe — no credentials exposed)
+2. `dbcli blacklist list` — Confirm sensitive data is protected
+3. `dbcli schema <table> --format json` — Verify actual column names
+4. Then execute `query` / `insert` / `update` / `export` / `delete` according to your permission level
+
+**Never guess column names.** Naming conventions vary across projects (e.g. `frozen_balance` vs `freeze`, `amount` vs `balance_variable`). Always confirm with `schema` first.
+
+## Debugging Workflow
+
+When investigating a bug related to database state:
+
+1. `dbcli schema <table> --format json` — Confirm actual columns and types
+2. `dbcli check <table> --format json` — Quick health scan (nulls, orphans, duplicates)
+3. `dbcli query "SELECT * FROM <table> WHERE <condition>" --format json` — Inspect the specific record
+4. Follow foreign keys from schema to trace related tables
+5. Repeat step 3 for each related table to verify referential integrity
+
+**Key principle:** Let the data tell the story. Don't hypothesize before seeing actual state.
+
+## Write Verification Workflow
+
+After any INSERT or UPDATE:
+
+1. `dbcli insert <table> --data '...' --dry-run` — Preview SQL first
+2. Execute the actual insert/update (remove --dry-run)
+3. `dbcli query "SELECT * FROM <table> WHERE <condition>" --format json` — Read back the written record
+4. Compare the returned data against the intended values
+5. If mismatch, check for triggers, default values, or blacklisted columns that may alter the result
+
+## Migration Safety Workflow
+
+Before and after running database migrations:
+
+1. `dbcli diff --snapshot before.json` — Capture current schema
+2. Run the migration
+3. `dbcli diff --against before.json --format json` — Compare changes
+4. Verify: added/removed/modified columns match the migration intent
+5. `dbcli check <affected-tables> --format json` — Ensure no orphaned data from column drops or FK changes
+
+## Health Check Workflow
+
+Periodic or on-demand database health scan:
+
+1. `dbcli check --all --format json` — Scan all tables (huge tables auto-skipped)
+2. Review the summary: focus on orphans (broken FKs) and unexpected nulls
+3. For any flagged issues, drill down with `dbcli query` to inspect specific records
+4. Use `estimatedRowCount` and `sizeCategory` from schema to gauge table growth
+
+## Code Generation from Schema
+
+When setting up a new project or migrating frameworks (e.g., Laravel to Bun + Drizzle):
+
+1. `dbcli schema --format json` — Export full database schema with FK, indexes, defaults, enums
+2. Use the JSON output to generate ORM schema definitions (Drizzle, Prisma, TypeORM, etc.)
+3. For each table, map:
+   - `primaryKey` + `autoIncrement` to ORM primary key decorator
+   - `foreignKey` to relation/reference definitions
+   - `indexes` to index declarations
+   - `enumValues` to TypeScript enums or union types
+   - `nullable` + `defaultValue` to column options
+   - `comment` to JSDoc or schema comments
+4. `dbcli check --all --format json` — Verify data health before trusting existing data
+5. After ORM setup, run a test query through the new ORM and compare results with `dbcli query` to validate correctness
+
+## Logic Verification Workflow
+
+Validate that application logic produces correct database state:
+
+1. `dbcli query "SELECT * FROM <table> WHERE <condition>" --format json` — Capture state BEFORE
+2. Execute the application logic (API call, script, etc.)
+3. `dbcli query "SELECT * FROM <table> WHERE <condition>" --format json` — Capture state AFTER
+4. Compare before/after:
+   - Were the expected rows created/updated/deleted?
+   - Are computed values correct (totals, balances, counters)?
+   - Did related tables update consistently?
+5. For complex transactions, check ALL affected tables
+6. `dbcli check <affected-tables> --format json` — Ensure no orphaned data post-operation
+
+**When to use:** Unit tests mock the DB and may miss real constraint violations, triggers, and default values. dbcli verifies actual DB state — catches what mocks hide. Best practice: unit tests for logic, dbcli for integration truth.
+
+## Natural Language Operations Workflow
+
+When the user describes a database operation in plain language:
+
+1. **Parse intent** — Identify the operation type:
+   - "查今天的訂單" → query (SELECT)
+   - "幫我新增一筆記事" → insert (INSERT)
+   - "把這筆訂單改成已出貨" → update (UPDATE)
+
+2. **Resolve context** — Use schema to map natural language to actual columns:
+   - `dbcli schema <table> --format json` — Get real column names
+   - "今天的訂單" → `WHERE created_at >= CURDATE()` (verify column name from schema)
+   - "已出貨" → check status column's enum values or existing data patterns
+
+3. **Infer missing fields** — Use schema defaults and context:
+   - `defaultValue` from schema → skip fields with sensible defaults
+   - `autoIncrement` → don't include primary key in INSERT
+   - `nullable: false` without default → MUST ask user for this value
+
+4. **Safety gate**:
+   - `dbcli blacklist list` — Ensure no blacklisted columns in the operation
+   - Check `sizeCategory` — if querying a huge table without filter, warn and suggest conditions
+   - For writes: ALWAYS use `--dry-run` first, show the SQL, then confirm
+
+5. **Execute and verify**:
+   - Run the operation
+   - For INSERT/UPDATE: read back with `dbcli query` to confirm
+   - Report result in natural language back to user
+
+**Key principle:** Never guess column names or values. Always schema-first, dry-run-first.
+
+## Notes
+
+- **Use `--format json`**: More reliable for AI parsing than table format
+- **Use `--dry-run` before writes**: Preview generated SQL before executing
+- **auto-limit**: Query-only mode appends `LIMIT 1000` automatically. Use `--no-limit` for `information_schema` queries or statements incompatible with LIMIT
+- **Blacklist scope**: Blacklisted tables/columns are automatically filtered from query results
+
+## Data Volume Protection
+
+Schema output includes `estimatedRowCount` and `sizeCategory` for each table:
+
+| Category | Rows | Behavior |
+|----------|------|----------|
+| small | < 10K | No restrictions |
+| medium | 10K - 100K | Suggest adding LIMIT/WHERE |
+| large | 100K - 1M | Warning displayed |
+| huge | > 1M | Full-table SELECT blocked without WHERE/LIMIT — use `--no-limit` to override |
+
+**Always check `sizeCategory` before querying.** For `large`/`huge` tables, add WHERE conditions or reasonable LIMIT.