@carllee1983/dbcli 1.50.0 → 1.51.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "description": "Database CLI skill and command reference for AI agents.",
   "author": {
     "name": "Carl Lee",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/.cursor/rules/dbcli.mdc

@@ -375,6 +375,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `upgrade` | n/a | Self-update from npm; 24h-cached version hints on every command. |
 | `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). **(v1.22)** Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for an LLM prompt-context payload (for injecting into another LLM, not needed for normal operation). |
+| `semantic` | n/a | Validate, search, inspect drift, migrate to v2, or print the optional project-root `dbcli.semantic.json`. Give its reviewed context to an external agent, but keep provider credentials, prompts, and agent context outside dbcli. `semantic draft validate --input <file|-> [--format text\|json]` validates only the explicit untrusted `QueryDraft` offline against local semantic/schema/saved-query metadata; it returns safe hashes/references/violation codes, never executes or echoes candidate SQL. Review the original draft, then invoke `explain` or `query` separately if intended. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,

package/.cursor/skills/dbcli/reference.md

@@ -2190,6 +2190,124 @@ dbcli migrate drop-enum status --execute --force
 
 **AI agent note:** Always use dry-run first (no `--execute`) to preview generated SQL. Only add `--execute` after confirming the SQL is correct. For DROP operations, both `--execute` and `--force` are required.
 
+### semantic
+
+Validate or print the optional, version-controlled `dbcli.semantic.json` in the
+project root. It supplies business names and descriptions to an agent, but is
+not a query language: these commands are offline, read-only, and never execute
+SQL or contact an LLM.
+
+```bash
+dbcli semantic validate
+dbcli semantic validate --format json
+dbcli semantic context
+dbcli semantic context --format markdown
+dbcli semantic context --file ./analytics.semantic.json
+dbcli semantic drift --format json
+dbcli semantic migrate --to 2 --format json
+dbcli semantic search purchases --kind model --format json
+dbcli semantic draft validate --input ./draft.json --format json
+external-agent | dbcli semantic draft validate --input - --format json
+```
+
+The default file has this compact contract:
+
+```json
+{
+  "version": 2,
+  "models": [
+    {
+      "name": "orders",
+      "table": "orders",
+      "description": "Completed purchases.",
+      "aliases": ["purchases"],
+      "fields": [
+        { "column": "created_at", "aliases": ["order date"] },
+        { "column": "customer_id" }
+      ]
+    },
+    {
+      "name": "customers",
+      "table": "customers",
+      "fields": [{ "column": "id" }]
+    }
+  ],
+  "relationships": [
+    {
+      "name": "order-customer",
+      "from": { "model": "orders", "field": "customer_id" },
+      "to": { "model": "customers", "field": "id" },
+      "cardinality": "many-to-one",
+      "description": "Each order belongs to one customer."
+    }
+  ],
+  "metrics": [
+    { "name": "daily-revenue", "query": "@analytics/revenue" }
+  ]
+}
+```
+
+Version 1 remains supported and is normalized with `relationships: []`.
+Version 2 relationships must reference a declared model and a declared field on
+that model; the field must also be visible in cached schema. Their `cardinality`
+is one of `one-to-one`, `one-to-many`, `many-to-one`, or `many-to-many`.
+`models[].table` and `models[].fields[].column` must name a visible cached
+schema object. Blacklisted tables and columns are not visible and are rejected.
+Each metric `query` must name an available saved query. Validation parses its
+local file through the normal saved-query safety checks, but never executes or
+emits SQL. The semantic file cannot contain SQL, connection data, or
+credentials. `semantic validate` reports a
+deterministic success summary (`--format text|json`); `semantic context` prints
+the validated context (`--format json|markdown`). `semantic drift` returns a
+stable `valid`, `stale`, `invalid`, or `unavailable` report and exits non-zero
+for every status except `valid`; it never connects to a database. `semantic
+migrate --to 2` prints a deterministic v2 JSON document to stdout and never
+writes the input file. An absent default file is allowed for `skill context`
+and simply omits the semantic section; a stale or invalid present file fails
+closed rather than being silently ignored.
+
+`semantic search <terms...>` performs deterministic, case-insensitive matching
+over canonical names, aliases, descriptions, and governed model paths. Results
+are ranked by exact canonical name, exact alias, prefix, then description token;
+kind/name breaks ties. Use `--kind model|field|relationship|metric` and
+`--limit <1-100>` (default `20`). It returns only canonical references, matched
+terms, aliases, descriptions, and necessary model paths—never SQL bodies,
+connection data, or blacklist names. No result is an empty array / text notice
+with exit 0.
+
+`semantic draft validate --input <file|-> [--format text|json]` accepts only an
+explicit untrusted `QueryDraft` JSON document from a file or stdin. First give
+the external agent reviewed `dbcli semantic context --format json` output; its
+provider credentials, prompt, and other agent context remain outside dbcli. The
+agent returns a draft using only the declared models and fields, for example:
+
+```json
+{
+  "version": 1,
+  "questionHash": "<sha256-of-the-original-question>",
+  "candidate": { "kind": "sql", "sql": "<reviewed-read-only-sql>" },
+  "semanticReferences": ["model:<model>", "field:<model>.<field>"]
+}
+```
+
+The command validates the contract, read-only single-statement SQL, canonical
+semantic references, saved-query names, and local filtered schema/blacklist
+compatibility without connecting to a database, reading query results, storing
+the draft, or calling a provider. JSON reports contain only status, hashes,
+canonical references, and safe violation codes; they never echo candidate SQL
+or protected names. Exit `0` means valid, `1` means rejected, and `2` means
+required local semantic evidence is unavailable. A valid report is not execution
+authorization: review the original draft, then separately and explicitly invoke
+`dbcli explain "<reviewed-read-only-sql>"` or `dbcli query
+"<reviewed-read-only-sql>"` when appropriate.
+
+When valid, `dbcli skill context` includes the same bounded data in its JSON,
+XML, and Markdown output. To run a metric, an agent must still invoke the named
+saved query through `dbcli q`; all ordinary permissions, blacklist masking,
+limits, audit, and recovery safeguards remain in force.
+
+**Permission:** n/a (local files only; no database connection).
+
 ### skill
 
 Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or an

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "dbcli-agent",
   "displayName": "dbcli Agent",
   "description": "Database CLI skill and command reference for AI agents.",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "author": {
     "name": "Carl Lee",
     "url": "https://github.com/CarlLee1983"

package/.github/skills/dbcli/SKILL.md

@@ -375,6 +375,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `upgrade` | n/a | Self-update from npm; 24h-cached version hints on every command. |
 | `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). **(v1.22)** Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for an LLM prompt-context payload (for injecting into another LLM, not needed for normal operation). |
+| `semantic` | n/a | Validate, search, inspect drift, migrate to v2, or print the optional project-root `dbcli.semantic.json`. Give its reviewed context to an external agent, but keep provider credentials, prompts, and agent context outside dbcli. `semantic draft validate --input <file|-> [--format text\|json]` validates only the explicit untrusted `QueryDraft` offline against local semantic/schema/saved-query metadata; it returns safe hashes/references/violation codes, never executes or echoes candidate SQL. Review the original draft, then invoke `explain` or `query` separately if intended. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,

package/.github/skills/dbcli/reference.md

@@ -2190,6 +2190,124 @@ dbcli migrate drop-enum status --execute --force
 
 **AI agent note:** Always use dry-run first (no `--execute`) to preview generated SQL. Only add `--execute` after confirming the SQL is correct. For DROP operations, both `--execute` and `--force` are required.
 
+### semantic
+
+Validate or print the optional, version-controlled `dbcli.semantic.json` in the
+project root. It supplies business names and descriptions to an agent, but is
+not a query language: these commands are offline, read-only, and never execute
+SQL or contact an LLM.
+
+```bash
+dbcli semantic validate
+dbcli semantic validate --format json
+dbcli semantic context
+dbcli semantic context --format markdown
+dbcli semantic context --file ./analytics.semantic.json
+dbcli semantic drift --format json
+dbcli semantic migrate --to 2 --format json
+dbcli semantic search purchases --kind model --format json
+dbcli semantic draft validate --input ./draft.json --format json
+external-agent | dbcli semantic draft validate --input - --format json
+```
+
+The default file has this compact contract:
+
+```json
+{
+  "version": 2,
+  "models": [
+    {
+      "name": "orders",
+      "table": "orders",
+      "description": "Completed purchases.",
+      "aliases": ["purchases"],
+      "fields": [
+        { "column": "created_at", "aliases": ["order date"] },
+        { "column": "customer_id" }
+      ]
+    },
+    {
+      "name": "customers",
+      "table": "customers",
+      "fields": [{ "column": "id" }]
+    }
+  ],
+  "relationships": [
+    {
+      "name": "order-customer",
+      "from": { "model": "orders", "field": "customer_id" },
+      "to": { "model": "customers", "field": "id" },
+      "cardinality": "many-to-one",
+      "description": "Each order belongs to one customer."
+    }
+  ],
+  "metrics": [
+    { "name": "daily-revenue", "query": "@analytics/revenue" }
+  ]
+}
+```
+
+Version 1 remains supported and is normalized with `relationships: []`.
+Version 2 relationships must reference a declared model and a declared field on
+that model; the field must also be visible in cached schema. Their `cardinality`
+is one of `one-to-one`, `one-to-many`, `many-to-one`, or `many-to-many`.
+`models[].table` and `models[].fields[].column` must name a visible cached
+schema object. Blacklisted tables and columns are not visible and are rejected.
+Each metric `query` must name an available saved query. Validation parses its
+local file through the normal saved-query safety checks, but never executes or
+emits SQL. The semantic file cannot contain SQL, connection data, or
+credentials. `semantic validate` reports a
+deterministic success summary (`--format text|json`); `semantic context` prints
+the validated context (`--format json|markdown`). `semantic drift` returns a
+stable `valid`, `stale`, `invalid`, or `unavailable` report and exits non-zero
+for every status except `valid`; it never connects to a database. `semantic
+migrate --to 2` prints a deterministic v2 JSON document to stdout and never
+writes the input file. An absent default file is allowed for `skill context`
+and simply omits the semantic section; a stale or invalid present file fails
+closed rather than being silently ignored.
+
+`semantic search <terms...>` performs deterministic, case-insensitive matching
+over canonical names, aliases, descriptions, and governed model paths. Results
+are ranked by exact canonical name, exact alias, prefix, then description token;
+kind/name breaks ties. Use `--kind model|field|relationship|metric` and
+`--limit <1-100>` (default `20`). It returns only canonical references, matched
+terms, aliases, descriptions, and necessary model paths—never SQL bodies,
+connection data, or blacklist names. No result is an empty array / text notice
+with exit 0.
+
+`semantic draft validate --input <file|-> [--format text|json]` accepts only an
+explicit untrusted `QueryDraft` JSON document from a file or stdin. First give
+the external agent reviewed `dbcli semantic context --format json` output; its
+provider credentials, prompt, and other agent context remain outside dbcli. The
+agent returns a draft using only the declared models and fields, for example:
+
+```json
+{
+  "version": 1,
+  "questionHash": "<sha256-of-the-original-question>",
+  "candidate": { "kind": "sql", "sql": "<reviewed-read-only-sql>" },
+  "semanticReferences": ["model:<model>", "field:<model>.<field>"]
+}
+```
+
+The command validates the contract, read-only single-statement SQL, canonical
+semantic references, saved-query names, and local filtered schema/blacklist
+compatibility without connecting to a database, reading query results, storing
+the draft, or calling a provider. JSON reports contain only status, hashes,
+canonical references, and safe violation codes; they never echo candidate SQL
+or protected names. Exit `0` means valid, `1` means rejected, and `2` means
+required local semantic evidence is unavailable. A valid report is not execution
+authorization: review the original draft, then separately and explicitly invoke
+`dbcli explain "<reviewed-read-only-sql>"` or `dbcli query
+"<reviewed-read-only-sql>"` when appropriate.
+
+When valid, `dbcli skill context` includes the same bounded data in its JSON,
+XML, and Markdown output. To run a metric, an agent must still invoke the named
+saved query through `dbcli q`; all ordinary permissions, blacklist masking,
+limits, audit, and recovery safeguards remain in force.
+
+**Permission:** n/a (local files only; no database connection).
+
 ### skill
 
 Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or an

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.51.0] - 2026-08-07 - Local semantic context and offline query-draft validation
+
+### Added
+
+- **Business semantic context commands.** Add the offline, read-only `dbcli semantic validate`, `context`, `search`, `drift`, and `migrate` commands for a reviewable `dbcli.semantic.json`. Semantic models, metrics, aliases, and v2 relationships are checked against the cached visible schema and saved-query names; v1 files remain supported and `migrate --to 2` writes only to stdout.
+- **Deterministic governed semantic search and relationship drift checks.** `semantic search` returns only reviewed metadata, removes blacklist names from free-text results, and supports bounded result counts. `semantic drift` identifies stale, invalid, or unavailable local semantic evidence, including relationship references that no longer match declared visible fields.
+- **Offline validation boundary for agent query drafts.** `dbcli semantic draft validate --input <file|->` accepts an explicit untrusted JSON draft and validates its references and read-only SQL without executing it, persisting it, or calling a provider. Reports contain hashes, canonical references, and safe violation codes rather than candidate SQL; a successful validation is explicitly not permission to execute.
+- **Semantic context in agent-facing skill context.** `dbcli skill context` includes the validated semantic context when present, after blacklist filtering, so agents receive only governed schema and semantic metadata.
+
 ## [1.50.0] - 2026-08-06 - QueryLens proxy query analysis
 
 ### Added

package/assets/SKILL.md

@@ -375,6 +375,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `upgrade` | n/a | Self-update from npm; 24h-cached version hints on every command. |
 | `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). **(v1.22)** Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for an LLM prompt-context payload (for injecting into another LLM, not needed for normal operation). |
+| `semantic` | n/a | Validate, search, inspect drift, migrate to v2, or print the optional project-root `dbcli.semantic.json`. Give its reviewed context to an external agent, but keep provider credentials, prompts, and agent context outside dbcli. `semantic draft validate --input <file|-> [--format text\|json]` validates only the explicit untrusted `QueryDraft` offline against local semantic/schema/saved-query metadata; it returns safe hashes/references/violation codes, never executes or echoes candidate SQL. Review the original draft, then invoke `explain` or `query` separately if intended. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,

package/assets/SKILL.zh-TW.md

@@ -288,6 +288,7 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 | `upgrade` | n/a | 從 npm 自我更新；每個指令都帶 24h 快取的版本提示。 |
 | `shell` | (與 query 同) | 互動式 REPL。SQL 引擎、MongoDB 與 Redis（單行；`.no-limit on/off`）。**(v1.22)** Elasticsearch 開啟 Kibana Dev Tools 風格的 REPL（`<METHOD> /<path>` + 可選 JSON body，空白行送出）。 |
 | `skill` | n/a | 產出 / 安裝 AI skill 文件（`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`）；`skill tasks list/show/plan` 提供 Agent Task Packs；`skill context` 提供 LLM 提示詞脈絡載荷（用於注入其他 LLM，正常操作不需要）。 |
+| `semantic` | n/a | 驗證、搜尋、檢查漂移、遷移至 v2 或輸出可選的專案根目錄 `dbcli.semantic.json`。把已檢閱的 context 交給外部 agent，但 provider 憑證、prompt 與 agent context 都留在 dbcli 外。`semantic draft validate --input <file|-> [--format text\|json]` 只會以本機 semantic/schema/saved-query metadata 離線驗證明確提交、不受信任的 `QueryDraft`；只回傳安全的 hash/reference/violation code，絕不執行或回顯 candidate SQL。先檢閱原始 draft，若要執行再另行呼叫 `explain` 或 `query`。 |
 | `migrate` | admin | 僅 SQL。**DDL；預設 dry-run** — 需 `--execute`。 |
 
 任何指令都可使用 root 層級的 `dbcli --use <name> <command>`；`query`、`schema`、`list`、`export`、`check` 也接受指令層級的 `--use`。兩種寫法都只把本次目標切到 v2 連線，不改變預設值。`--recovery` 被 `query`、`q`、`insert`、`update`、`delete`、`export`、`schema`、`inspect`、`lint` 與 `diff --against-orm` 支援（見上方**失敗時**）。

package/assets/reference.md

@@ -2190,6 +2190,124 @@ dbcli migrate drop-enum status --execute --force
 
 **AI agent note:** Always use dry-run first (no `--execute`) to preview generated SQL. Only add `--execute` after confirming the SQL is correct. For DROP operations, both `--execute` and `--force` are required.
 
+### semantic
+
+Validate or print the optional, version-controlled `dbcli.semantic.json` in the
+project root. It supplies business names and descriptions to an agent, but is
+not a query language: these commands are offline, read-only, and never execute
+SQL or contact an LLM.
+
+```bash
+dbcli semantic validate
+dbcli semantic validate --format json
+dbcli semantic context
+dbcli semantic context --format markdown
+dbcli semantic context --file ./analytics.semantic.json
+dbcli semantic drift --format json
+dbcli semantic migrate --to 2 --format json
+dbcli semantic search purchases --kind model --format json
+dbcli semantic draft validate --input ./draft.json --format json
+external-agent | dbcli semantic draft validate --input - --format json
+```
+
+The default file has this compact contract:
+
+```json
+{
+  "version": 2,
+  "models": [
+    {
+      "name": "orders",
+      "table": "orders",
+      "description": "Completed purchases.",
+      "aliases": ["purchases"],
+      "fields": [
+        { "column": "created_at", "aliases": ["order date"] },
+        { "column": "customer_id" }
+      ]
+    },
+    {
+      "name": "customers",
+      "table": "customers",
+      "fields": [{ "column": "id" }]
+    }
+  ],
+  "relationships": [
+    {
+      "name": "order-customer",
+      "from": { "model": "orders", "field": "customer_id" },
+      "to": { "model": "customers", "field": "id" },
+      "cardinality": "many-to-one",
+      "description": "Each order belongs to one customer."
+    }
+  ],
+  "metrics": [
+    { "name": "daily-revenue", "query": "@analytics/revenue" }
+  ]
+}
+```
+
+Version 1 remains supported and is normalized with `relationships: []`.
+Version 2 relationships must reference a declared model and a declared field on
+that model; the field must also be visible in cached schema. Their `cardinality`
+is one of `one-to-one`, `one-to-many`, `many-to-one`, or `many-to-many`.
+`models[].table` and `models[].fields[].column` must name a visible cached
+schema object. Blacklisted tables and columns are not visible and are rejected.
+Each metric `query` must name an available saved query. Validation parses its
+local file through the normal saved-query safety checks, but never executes or
+emits SQL. The semantic file cannot contain SQL, connection data, or
+credentials. `semantic validate` reports a
+deterministic success summary (`--format text|json`); `semantic context` prints
+the validated context (`--format json|markdown`). `semantic drift` returns a
+stable `valid`, `stale`, `invalid`, or `unavailable` report and exits non-zero
+for every status except `valid`; it never connects to a database. `semantic
+migrate --to 2` prints a deterministic v2 JSON document to stdout and never
+writes the input file. An absent default file is allowed for `skill context`
+and simply omits the semantic section; a stale or invalid present file fails
+closed rather than being silently ignored.
+
+`semantic search <terms...>` performs deterministic, case-insensitive matching
+over canonical names, aliases, descriptions, and governed model paths. Results
+are ranked by exact canonical name, exact alias, prefix, then description token;
+kind/name breaks ties. Use `--kind model|field|relationship|metric` and
+`--limit <1-100>` (default `20`). It returns only canonical references, matched
+terms, aliases, descriptions, and necessary model paths—never SQL bodies,
+connection data, or blacklist names. No result is an empty array / text notice
+with exit 0.
+
+`semantic draft validate --input <file|-> [--format text|json]` accepts only an
+explicit untrusted `QueryDraft` JSON document from a file or stdin. First give
+the external agent reviewed `dbcli semantic context --format json` output; its
+provider credentials, prompt, and other agent context remain outside dbcli. The
+agent returns a draft using only the declared models and fields, for example:
+
+```json
+{
+  "version": 1,
+  "questionHash": "<sha256-of-the-original-question>",
+  "candidate": { "kind": "sql", "sql": "<reviewed-read-only-sql>" },
+  "semanticReferences": ["model:<model>", "field:<model>.<field>"]
+}
+```
+
+The command validates the contract, read-only single-statement SQL, canonical
+semantic references, saved-query names, and local filtered schema/blacklist
+compatibility without connecting to a database, reading query results, storing
+the draft, or calling a provider. JSON reports contain only status, hashes,
+canonical references, and safe violation codes; they never echo candidate SQL
+or protected names. Exit `0` means valid, `1` means rejected, and `2` means
+required local semantic evidence is unavailable. A valid report is not execution
+authorization: review the original draft, then separately and explicitly invoke
+`dbcli explain "<reviewed-read-only-sql>"` or `dbcli query
+"<reviewed-read-only-sql>"` when appropriate.
+
+When valid, `dbcli skill context` includes the same bounded data in its JSON,
+XML, and Markdown output. To run a metric, an agent must still invoke the named
+saved query through `dbcli q`; all ordinary permissions, blacklist masking,
+limits, audit, and recovery safeguards remain in force.
+
+**Permission:** n/a (local files only; no database connection).
+
 ### skill
 
 Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or an