@carllee1983/dbcli 1.50.0 → 1.51.0

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.49.0",
+  "version": "1.51.0",
   "description": "Database CLI skill and command reference for AI agents.",
   "contextFileName": "AGENTS.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {

package/plugins/dbcli-agent/.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/plugins/dbcli-agent/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/plugins/dbcli-agent/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/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/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