@carllee1983/dbcli 1.5.2 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [1.7.0] - 2026-05-04
+
+### Added
+
+- `dbcli q @<name>` 執行已保存的參數化 SELECT 片段
+- `dbcli queries list/show/new/edit/check` 管理片段
+- 兩層片段儲存：`.dbcli-shared/queries/`（共享）+ `.dbcli/queries/`（個人覆蓋）
+- 完整安全 invariants：拒絕非 SELECT/WITH、多語句、`${...}` / `{{...}}` 模板語法
+- 子查詢式 size guard 包裹 (`SELECT * FROM (...) AS _dbcli_guard LIMIT 1000`)
+- 內建 YAML 子集 frontmatter parser（無新增 npm 依賴）
+- `queries list/show --format json` 為未來 MCP server 預留契約
+
+## [1.6.0] - 2026-04-23
+
+### Added
+
+- **Full MongoDB Support**: Extended all core operations to support MongoDB.
+  - Data operations: `query`, `insert`, `update`, `delete`.
+  - Safeguards: Integrated `blacklist` protection and `query-size-guard` for MongoDB commands.
+  - Discovery: Implemented schema inspection for MongoDB collections.
+  - Diagnostics: Added comprehensive MongoDB environment and connection diagnostics to `dbcli doctor`.
+- **Improved AI Skill Installation**: `dbcli skill --install` now deploys both `SKILL.md` (high-level workflow) and `reference.md` (full command syntax and examples) to target platforms (Claude Code, Gemini CLI, Copilot, Cursor).
+- **Security model enhancement**: `dbcli init` now defaults to a more secure storage model, placing sensitive connection details in `~/.config/dbcli/` rather than the local project workspace.
+
+### Changed
+
+- **Documentation Refactor**: Updated and synchronized documentation (README, README.zh-TW, SKILL.md) to reflect full MongoDB capabilities and first-step walkthroughs.
+
 ## [1.5.2] - 2026-04-22
 
 ### Fixed

package/README.dev.md

@@ -1,5 +1,7 @@
 # Development Guide
 
+Scoped package: **`@carllee1983/dbcli`**. All `npm` / `npx` examples below use this name.
+
 ## npm Publishing Process
 
 ### Pre-Publication Checklist
@@ -9,115 +11,110 @@ Before running `npm publish`:
 1. **Verify build is clean:**
    ```bash
    bun run build
-   ls -lh dist/cli.mjs  # Should be 1.0-1.5MB
+   ls -lh dist/cli.mjs   # expect a few MB (bundled CLI + dependencies)
    ```
 
-2. **Verify test suite passes:**
+2. **Verify tests pass (pick one):**
    ```bash
-   bun test --run unit/
+   # Fast path: unit + core only (matches CI-style smoke)
+   bun run test:unit
+
+   # Full suite (Bun test runner)
+   bun test
    ```
 
-   For live database integration tests, use an explicit config path if needed:
+   For live database integration tests, set an explicit config if needed:
    ```bash
    LIVE_DB_CONFIG_PATH=/path/to/.dbcli bun test tests/integration/live-db.test.ts
    ```
 
    If no live config is available, `tests/integration/live-db.test.ts` skips
-   instead of falling back to the default PostgreSQL configuration.
+   instead of falling back to the default PostgreSQL configuration. Use
+   `SKIP_INTEGRATION_TESTS=true` to skip integration tests when running a broad `bun test`.
 
 3. **Update version in package.json:**
    ```bash
-   npm version minor  # Updates package.json version + creates git tag
-   # OR manually update "version" field in package.json
+   npm version minor   # bumps version + creates git tag (in this repo)
+   # OR edit the "version" field in package.json by hand
    ```
 
 4. **Verify package contents (dry run):**
    ```bash
    npm pack --dry-run
-   # Should list only: dist/*, README.md, CHANGELOG.md, package.json
    ```
+   Expect **`dist/`** (at least `cli.mjs`), **`assets/`** (e.g. `SKILL.md`, `reference.md` for `dbcli skill`), **`README.md`**, **`CHANGELOG.md`**, **`LICENSE`**, and **`package.json`**. There must be **no** `src/`, `tests/`, or `node_modules/`. The listing may also include other root `README*.md` files (npm can still pack them even when `files` is set); dev-only readmes are listed in **`.npmignore`** — re-check with dry-run if you add or remove docs.
 
 5. **Check package size:**
    ```bash
    npm pack
-   ls -lh dbcli-*.tgz  # Must be < 5MB
-   rm dbcli-*.tgz      # Cleanup
+   ls -lh carllee1983-dbcli-*.tgz   # compressed tarball (typically well under 5MB)
+   rm carllee1983-dbcli-*.tgz       # cleanup
    ```
 
 ### Publication
 
-The publication process is automated by npm hooks:
+Publication uses the `prepublishOnly` script in `package.json`:
 
 ```bash
 npm publish
 ```
 
-This invokes (in order):
-1. `prepublishOnly` hook: Runs `bun run build` → ensures fresh dist/cli.mjs
-2. npm creates tarball with `files` whitelist → only intended files included
-3. npm applies `.npmignore` rules → additional safety layer
-4. npm publishes to registry
+What runs (conceptually):
 
-**Note:** The build CANNOT be skipped. If you try to publish with a stale dist/cli.mjs, prepublishOnly will rebuild it.
+1. **`prepublishOnly`:** `bun run build` — rebuilds `dist/cli.mjs` from `src/cli.ts` via `scripts/build.ts`.
+2. **Tarball** — paths from the **`files`** field in `package.json`, further filtered by **`.npmignore`**. (Some npm versions also merge in extra root `README*` files; use dry-run to see exactly what will ship.)
+3. **Registry** — with `"publishConfig": { "access": "public" }`, the scoped package is published as **public**.
+
+A failed `bun run build` will fail the publish, so you should not ship a stale `dist/` from a previous local build.
 
 ### Verification (Post-Publication)
 
 After publishing:
 
-1. **Test installation globally:**
+1. **Global install:**
    ```bash
-   npm install -g dbcli
-   which dbcli  # Should show: /usr/local/bin/dbcli or similar
+   npm install -g @carllee1983/dbcli
+   which dbcli
    dbcli --version
    ```
 
-2. **Test zero-install (npx):**
+2. **Zero-install (npx / bunx):**
    ```bash
-   cd /tmp
-   mkdir test-dbcli && cd test-dbcli
-   npx dbcli --help
-   npx dbcli --version
+   cd /tmp && mkdir -p test-dbcli && cd test-dbcli
+   npx @carllee1983/dbcli --help
+   npx @carllee1983/dbcli --version
+   # or: bunx @carllee1983/dbcli --help
    ```
 
-3. **Test Windows installation (if available):**
-   - On Windows machine: `npm install -g dbcli`
-   - Verify: `dbcli --help` and `dbcli --version` work
-   - npm creates .cmd wrapper automatically; no manual .cmd needed
+3. **Windows (if available):** `npm install -g @carllee1983/dbcli`, then `dbcli --help`. npm creates the `.cmd` stub for the `bin` entry; no hand-written `.cmd` in the repo.
 
 ### Rollback (if needed)
 
-If critical bug discovered after publishing:
+If a bad release must be mitigated:
 
 ```bash
-npm unpublish dbcli@VERSION  # Remove specific version
-# OR
-npm deprecate dbcli@VERSION "Critical bug; use VERSION-1"  # Mark as deprecated
+npm unpublish @carllee1983/dbcli@<VERSION>
+# and/or
+npm deprecate @carllee1983/dbcli@<VERSION> "Reason; use <SAFE_VERSION> instead"
 ```
 
-Then publish a patch fix.
+Then ship a patch version with the fix. Prefer **deprecate** over **unpublish** when consumers may already depend on the version.
 
 ### Configuration Details
 
-- **files whitelist (package.json):** Restricts tarball to source only
-  - Includes: dist/, README.md, CHANGELOG.md, LICENSE
-  - Excludes: src/, tests/, node_modules/, .git/, docs/
-- **prepublishOnly hook:** Ensures build runs before pack
-  - Prevents stale binaries from being published
-  - Runs automatically; cannot be skipped with --no-scripts
-- **engines field:** Declares minimum Node >=18.0.0, Bun >=1.3.3
-  - npm warns if consumer's environment is too old
-- **Cross-platform support:** Shebang `#!/usr/bin/env bun` works on all platforms
-  - macOS/Linux: Direct shebang execution
-  - Windows: npm creates .cmd wrapper automatically (no manual creation needed)
-- **Live integration tests:** `tests/integration/live-db.test.ts` reads `.dbcli/config.json`
-  by default or `LIVE_DB_CONFIG_PATH` when you need to point at another config
-  directory. Set `SKIP_INTEGRATION_TESTS=true` to skip all integration tests.
+- **`files` (in `package.json`):** Publishes `dist/`, `assets/`, `README.md`, `CHANGELOG.md`, `LICENSE`. The `assets/` tree is required for `dbcli skill` to copy bundled `SKILL.md` / `reference.md` from the installed package.
+- **`prepublishOnly`:** `bun run build` so `dist/cli.mjs` matches current source.
+- **`engines`:** Declares `node >= 18.0.0` and `bun >= 1.3.3` so npm can warn on outdated runtimes.
+- **Shebang:** `scripts/build.ts` prepends `#!/usr/bin/env bun` to `dist/cli.mjs`; the `bin` field in `package.json` points at that file.
+- **Live DB tests:** `tests/integration/live-db.test.ts` uses project `.dbcli` by default or `LIVE_DB_CONFIG_PATH` when you point at another config directory. Set `SKIP_INTEGRATION_TESTS=true` to skip all integration tests.
+
+For contributor workflow and release process, see **[CONTRIBUTING.md](./CONTRIBUTING.md)** and the main **[README.md](./README.md)** Development section.
 
 ### Troubleshooting
 
-| Issue | Solution |
-|-------|----------|
-| prepublishOnly fails (build error) | Fix TypeScript errors in src/, run `bun test --run unit/`, retry `npm publish` |
-| Package size > 5MB | Run `bun build --metafile=meta.json`, analyze output, remove unused dependencies |
-| Windows installation fails | Verify shebang is `#!/usr/bin/env bun` in dist/cli.mjs; npm's .cmd wrapper will be created automatically |
-| npx hangs or times out | Run `npm cache clean --force`, retry `npx dbcli` |
+| Issue | What to do |
+|-------|------------|
+| `prepublishOnly` / build fails | Fix TypeScript or build errors, run `bun run test:unit`, then `bun run build` again. |
+| Tarball unexpectedly large or bloated | Inspect the bundle: e.g. `bun build ./src/cli.ts --outfile=dist/cli.mjs --target=bun --metafile=meta.json` and review the metafile; trim dependencies or dev-only code paths. |
+| Windows: `dbcli` not found after global install | Confirm PATH includes npm’s global `bin`; reinstall `npm i -g @carllee1983/dbcli`. |
+| `npx` download slow or cache weird | `npm cache clean --force` and retry `npx @carllee1983/dbcli --version`. |

package/README.md

@@ -6,6 +6,8 @@ A unified database CLI tool that enables AI agents (Claude Code, Gemini, Copilot
 
 **Core Value:** AI agents can safely and intelligently access project databases through a single, permission-controlled CLI tool with sensitive data protection.
 
+> **Security update:** `dbcli init` now writes only a small project binding stub into `./.dbcli/config.json`. The full connection configuration is stored under `~/.config/dbcli/projects/<project-id>/config.json`, so sensitive settings do not live inside the project workspace by default.
+
 ## Internationalization (i18n)
 
 dbcli supports multiple languages via the `DBCLI_LANG` environment variable:
@@ -76,6 +78,9 @@ When `dbcli` is not on your `PATH`, use `bun run src/cli.ts <subcommand> ...` (s
 # Initialize project with database connection
 dbcli init
 
+# Interactive shell (SQL + dbcli commands, tab completion)
+dbcli shell
+
 # List available tables
 dbcli list
 
@@ -85,6 +90,9 @@ dbcli schema users
 # Query data
 dbcli query "SELECT * FROM users"
 
+# Preview schema DDL (dry-run by default; add --execute to apply)
+dbcli migrate create posts --column "id:serial:pk" --column "title:varchar(200):not-null"
+
 # Generate AI agent skill
 dbcli skill --install claude
 ```
@@ -106,12 +114,16 @@ dbcli query '{"status":"active"}' --collection users --use atlas
 
 For MongoDB, `list` and `query` operate on the database configured for the connection, and `query` requires `--collection <name>`.
 
+For a command-by-command support matrix across PostgreSQL, MySQL, MariaDB, and MongoDB, see [docs/feature-matrix.md](./docs/feature-matrix.md).
+
 ---
 
 ## Multi-connection Support (v2)
 
 dbcli supports multiple named database connections within a single project. This is useful for managing different environments (development, staging, production) or multiple databases.
 
+The project `.dbcli` directory now acts as a binding + cache layer. The actual connection config is stored in `~/.config/dbcli/projects/<project-id>/`, which keeps sensitive settings out of the workspace by default.
+
 ### Initializing Named Connections
 
 To create a named connection, use the `--conn-name` option during `init`. You can also specify a custom `.env` file for that connection.
@@ -170,13 +182,14 @@ dbcli init [OPTIONS]
 ```
 
 **Options (Basic):**
-- `--system <type>` — Database system: `postgresql`, `mysql`, `mariadb`
+- `--system <type>` — Database system: `postgresql`, `mysql`, `mariadb`, `mongodb`
 - `--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`
+- **MongoDB only:** `--uri <uri>` — full connection URI (`mongodb://…` or `mongodb+srv://…`); `--auth-source <db>` — auth database (default `admin` when using user/password)
 - `--use-env-refs` — Store environment variable references instead of actual values in config
 - `--skip-test` — Skip connection test
 - `--no-interactive` — Non-interactive mode (requires all options)
@@ -191,7 +204,7 @@ dbcli init [OPTIONS]
 **Behavior:**
 - Reads `.env` file if present (auto-fills DATABASE_URL, DB_* variables)
 - Prompts for missing values (host, port, user, password, database name, permission level)
-- Creates `.dbcli` JSON config file in project root
+- Creates a project binding stub in `.dbcli/config.json` and stores the full config under `~/.config/dbcli/projects/<project-id>/`
 - Tests database connection before saving
 
 **Examples:**
@@ -241,6 +254,8 @@ dbcli use --list
 
 > **`--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.
 
+> **Storage model:** The project `.dbcli` directory is now a binding + cache layer, not the canonical home for secrets. If you inspect `./.dbcli/config.json`, you should only see the binding metadata; the full config lives in the home storage path shown above.
+
 ---
 
 #### `dbcli list`
@@ -489,8 +504,8 @@ dbcli skill --install cursor          # Install to Cursor IDE
 ```
 
 **Behavior:**
-- Ships a canonical **`assets/SKILL.md`** in the package (single source of truth)
-- Prints that file to **stdout**, writes it with **`--output`**, or copies it to a **platform-specific path** with **`--install`**
+- Ships canonical **`assets/SKILL.md`** + **`assets/reference.md`** (single source of truth: concise skill + long command reference)
+- Prints the skill to **stdout**, writes it with **`--output`**, or copies it to a **platform-specific path** with **`--install`**
 - Actual database access is still enforced by your `.dbcli` permission level and blacklist — the skill text describes the full CLI surface
 
 **Examples:**
@@ -592,12 +607,8 @@ dbcli check users
 dbcli check orders --checks nulls,orphans --format table
 # Scan all tables
 dbcli check --all
-```
 
----
-
-**Examples:**
-```bash
+# Table view + all-tables with selected checks
 dbcli check orders --format table
 dbcli check --all --checks nulls,duplicates --format json
 ```
@@ -690,7 +701,7 @@ dbcli upgrade --check           # Only check, do not upgrade
 
 **Background checks (stderr, skipped when `--quiet` or for `upgrade` / `skill`):**
 - **CLI version:** dbcli checks the npm registry (cached, about once per 24 hours). If a newer package exists, a one-line hint prints after normal command output.
-- **Installed skills:** If you used `dbcli skill --install <platform>`, dbcli compares each installed copy to the bundled `assets/SKILL.md`. When they differ, a short reminder lists which platforms to re-install (`dbcli skill --install <platform>`). Run `dbcli upgrade` to see the same skill status together with version info.
+- **Installed skills:** If you used `dbcli skill --install <platform>`, dbcli compares each installed primary skill file (`SKILL.md` or `dbcli.mdc`) to the bundled `assets/SKILL.md`. When they differ, a short reminder lists which platforms to re-install (`dbcli skill --install <platform>`). Run `dbcli upgrade` to see the same skill status together with version info. Re-installing also refreshes `reference.md` next to the skill.
 
 #### `dbcli shell`
 
@@ -760,6 +771,43 @@ dbcli migrate drop-enum status --execute --force
 
 ---
 
+## Query Risk Planning
+
+Use `plan` to inspect SQL safety before execution. It reads local dbcli config, permissions, blacklist rules, and cached schema metadata only; it does not connect to the database.
+
+```bash
+dbcli plan "UPDATE users SET status='inactive'" --format json
+```
+
+Decisions are:
+
+- `ALLOW` — no obvious risk was detected.
+- `WARN` — inspect warnings before executing.
+- `BLOCK` — unsafe, unsupported, or violates configured safety constraints.
+
+Text output is concise for humans:
+
+```text
+Decision: BLOCK
+Operation: UPDATE
+Target tables: users
+
+Risk factors:
+- UPDATE statement has no WHERE clause.
+
+Recommendations:
+- Add a WHERE clause.
+- Use --dry-run on the actual write command.
+```
+
+JSON output includes `suggestedCommands` for agents:
+
+```bash
+dbcli plan "SELECT id FROM users WHERE id = 1 LIMIT 1" --format json
+```
+
+---
+
 ## Global Options
 
 All commands support these global options:
@@ -948,9 +996,25 @@ A Query-only agent cannot write to any table, and also cannot read blacklisted t
 
 ---
 
+## Saved queries
+
+Save parameterised SELECT snippets and re-run them by name:
+
+```bash
+dbcli queries list
+dbcli queries show @dau
+dbcli q @dau --param days=30 --format json
+```
+
+Snippets live in `.dbcli-shared/queries/` (committed) or `.dbcli/queries/`
+(gitignored, personal override). Each `.sql` file declares its frontmatter
+in a `-- ---` block. Read `assets/reference.md` for the full schema.
+
+---
+
 ## AI Integration Guide
 
-dbcli ships AI-consumable skill documentation (`assets/SKILL.md`) and can copy it into your favorite AI development tool directories.
+dbcli ships AI-consumable skill files (`assets/SKILL.md` and `assets/reference.md`) and can copy them into your favorite AI tool directories.
 
 ### Quick Start
 
@@ -982,7 +1046,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Restart Claude Code extension
 5. In Claude Code chat, ask: "Show me the database schema" or "Query active users"
 
-**Skill location:** `~/.claude/skills/dbcli/SKILL.md`
+**Skill location:** `~/.claude/skills/dbcli/` (SKILL.md + reference.md)
 
 ---
 
@@ -994,7 +1058,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Start Gemini: `gemini start`
 5. In chat, request: "Query the users table" or "Show database tables"
 
-**Skill location:** `~/.gemini/skills/dbcli/SKILL.md`
+**Skill location:** `~/.gemini/skills/dbcli/` (SKILL.md + reference.md)
 
 ---
 
@@ -1006,7 +1070,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Install Copilot CLI: `npm install -g @github-next/github-copilot-cli`
 5. Use copilot preview: `copilot --help` and explore dbcli integration
 
-**Skill location:** `.github/skills/dbcli/SKILL.md` under the **current working directory** when you run `dbcli skill --install copilot` (typically your project root).
+**Skill location:** `.github/skills/dbcli/` (SKILL.md + reference.md) when you run `dbcli skill --install copilot` in your project root.
 
 ---
 
@@ -1018,7 +1082,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 4. Open Cursor editor
 5. Use Cursor's Composer: "Insert a new user" or "Export user data"
 
-**Skill location:** `.cursor/rules/dbcli.mdc` under the **current working directory** when you run `dbcli skill --install cursor` (project-level Cursor rule).
+**Skill location:** `.cursor/rules/dbcli.mdc` (summary + workflows) and `.cursor/skills/dbcli/reference.md` (full command flags and examples) under the **current working directory** when you run `dbcli skill --install cursor`.
 
 ---
 
@@ -1045,7 +1109,7 @@ dbcli skill --install claude
 
 ### Updating the skill after upgrades
 
-The markdown installed by `dbcli skill` is the bundled **`assets/SKILL.md`**. It is **not** regenerated from your live config. When you **upgrade dbcli** or the bundled skill changes, re-copy it to each platform you use:
+`dbcli skill` copies the bundled **`assets/SKILL.md`** (and for `--install`, **`assets/reference.md`** next to it). It is **not** regenerated from your live config. When you **upgrade dbcli** or the bundled skill changes, re-copy it to each platform you use:
 
 ```bash
 dbcli skill --install claude
@@ -1053,7 +1117,7 @@ dbcli skill --install gemini
 # ... etc.
 ```
 
-If an installed copy is older than the bundled file, dbcli prints a **stderr reminder** after most commands (see **`dbcli upgrade`**). Changing **permission level** or **blacklist** in `.dbcli` affects what the CLI allows at runtime — keep project context (e.g. `dbcli status`, `dbcli blacklist list`) in mind for agents even though the skill text lists the full command set.
+If an installed primary skill file is older than the bundled `assets/SKILL.md`, dbcli prints a **stderr reminder** after most commands (see **`dbcli upgrade`**). Changing **permission level** or **blacklist** in `.dbcli` affects what the CLI allows at runtime — keep project context (e.g. `dbcli status`, `dbcli blacklist list`) in mind for agents even though the skill text lists the full command set.
 
 ---
 
@@ -1230,6 +1294,7 @@ chmod +x dist/cli.mjs
 - **PostgreSQL:** 12.0+
 - **MySQL:** 8.0+
 - **MariaDB:** 10.5+
+- **MongoDB:** 4.4+ (query and collection listing via `mongodb://` and `mongodb+srv://`; see **MongoDB Atlas / SRV Connections** earlier in this document)
 
 ### Runtime
 
@@ -1248,12 +1313,15 @@ chmod +x dist/cli.mjs
 
 ```bash
 bun test                  # full test suite (Bun test runner)
+bun run typecheck         # TypeScript compile-time validation
 bun run test:unit         # unit + core tests only
 bun run test:integration  # integration tests
 bun run test:docker       # integration tests with docker-compose.test.yml (MySQL + PostgreSQL)
 bun run build             # bundle CLI to dist/ (used before publish)
 ```
 
+CI treats `bun run typecheck` and `bun test` as the required pass/fail validation gate on every push and pull request. Lint, build, smoke checks, and benchmarks run in addition to that gate.
+
 Live database integration tests use `.dbcli/config.json` by default. If your live
 config lives elsewhere, set `LIVE_DB_CONFIG_PATH=/path/to/.dbcli` before running: