@runcontext/cli 0.4.1 → 0.4.2

package/dist/index.js

@@ -141,7 +141,7 @@ function formatSarif(diagnostics) {
         tool: {
           driver: {
             name: "ContextKit",
-            version: "0.4.1",
+            version: "0.4.2",
             informationUri: "https://github.com/erickittelson/ContextKit",
             rules: Array.from(ruleMap.values())
           }
@@ -3259,6 +3259,71 @@ ${intentSection}## The Cardinal Rule: Never Fabricate Metadata
 
 If you don't know something, **ask the user**. A honest "I'm not sure \u2014 can you tell me what this field means?" is infinitely better than fabricated metadata that looks plausible but is wrong.
 
+## Database Safety \u2014 MANDATORY
+
+**Your job is to READ the database to build metadata. You must NEVER modify the database.**
+
+### Hard Rules (no exceptions)
+
+- **READ-ONLY.** Never execute INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, MERGE, REPLACE, or any DDL/DML statement
+- **LIMIT everything.** Every SELECT must include \`LIMIT\`. Use \`LIMIT 20\` for sample values, \`LIMIT 100\` max for golden query validation. Never run unlimited queries
+- **No full table scans.** Never \`SELECT * FROM large_table\` without a WHERE clause and LIMIT. For row counts, use \`COUNT(*)\` \u2014 never pull all rows to count them
+- **No expensive aggregations.** Avoid \`GROUP BY\` on high-cardinality columns across full tables. When checking distinct values, use \`SELECT DISTINCT col FROM table LIMIT 20\`, not \`SELECT DISTINCT col FROM table\`
+- **No cross joins or cartesian products.** Never join tables without a proper join condition
+- **No recursive or deeply nested queries.** Keep queries simple \u2014 you're sampling data, not building reports
+- **No EXPLAIN ANALYZE on cloud warehouses.** On Snowflake, BigQuery, Databricks, etc., even EXPLAIN can trigger computation. Use metadata queries (information_schema) instead when possible
+
+### Cost Awareness
+
+Cloud data warehouses (Snowflake, BigQuery, Databricks, Redshift) charge per query based on data scanned. **Every query costs money.**
+
+- Prefer \`information_schema\` queries over scanning actual tables
+- Use \`LIMIT\` on every query \u2014 no exceptions
+- Sample a few rows to understand a column, don't scan the full table
+- For BigQuery: always qualify table names with dataset to avoid scanning wrong tables
+- For Snowflake: use \`SAMPLE\` clause when available instead of full table scans
+- If you need row counts, use table metadata or \`COUNT(*)\` \u2014 never \`SELECT *\`
+- Batch your questions: gather what you need to know, then write ONE efficient query instead of many small ones
+
+### What You ARE Allowed To Do
+
+\`\`\`sql
+-- YES: Sample values (always with LIMIT)
+SELECT DISTINCT column_name FROM table_name LIMIT 20;
+
+-- YES: Basic stats for a column (single column, not full row)
+SELECT MIN(col), MAX(col), COUNT(DISTINCT col) FROM table_name;
+
+-- YES: Row count
+SELECT COUNT(*) FROM table_name;
+
+-- YES: Schema metadata (free or near-free on all platforms)
+SELECT column_name, data_type FROM information_schema.columns
+WHERE table_name = 'my_table';
+
+-- YES: Validate a golden query (with LIMIT)
+SELECT geoid, score FROM vw_rankings ORDER BY score DESC LIMIT 10;
+\`\`\`
+
+### What You Must NEVER Do
+
+\`\`\`sql
+-- NEVER: Modify data
+INSERT INTO / UPDATE / DELETE FROM / DROP TABLE / ALTER TABLE
+
+-- NEVER: Unlimited scans
+SELECT * FROM large_table;
+SELECT DISTINCT high_cardinality_col FROM big_table;
+
+-- NEVER: Expensive cross-table operations without LIMIT
+SELECT * FROM a JOIN b ON a.id = b.id JOIN c ON b.id = c.id;
+
+-- NEVER: Write to the database in any way
+CREATE TABLE / CREATE VIEW / CREATE INDEX
+\`\`\`
+
+If a query might be expensive and you're not sure, **ask the user first**. "This table looks large \u2014 is it OK if I run a COUNT(*)?" is always the right call.
+
 ## Reference Documents
 
 Check \`context/reference/\` for any files the user has provided \u2014 data dictionaries, Confluence exports, ERDs, business glossaries, dashboard docs, etc. **Read these first** before querying the database. They contain domain knowledge that will dramatically improve your metadata quality.
@@ -3360,18 +3425,20 @@ You must iterate \u2014 a single pass is never enough. Each \`context tier\` run
 
 ### Before writing ANY metadata, query the database first
 
-For every field you're about to describe or classify:
+For every field you're about to describe or classify (**always with LIMIT, always read-only**):
 
 \`\`\`sql
 -- What type of values does this column contain?
 SELECT DISTINCT column_name FROM table LIMIT 20;
 
 -- For numeric columns: is this a metric or dimension?
-SELECT MIN(col), MAX(col), AVG(col), COUNT(DISTINCT col) FROM table;
+SELECT MIN(col), MAX(col), AVG(col), COUNT(DISTINCT col) FROM table LIMIT 1;
 
 -- For potential metrics: does SUM make sense?
 -- If SUM produces a meaningful business number \u2192 additive: true
 -- If SUM is meaningless (e.g., summing percentages, scores, ratings) \u2192 additive: false
+
+-- REMEMBER: Never run queries without LIMIT. Never modify data.
 \`\`\`
 
 ### Semantic Role Decision Tree
@@ -3454,6 +3521,42 @@ ${datasetList || "(none detected)"}
 
 ${failingSection}
 
+## Serving to Other Agents via MCP
+
+Once the semantic layer reaches Silver or Gold, serve it so other AI agents can use the curated metadata:
+
+\`\`\`bash
+# Start MCP server (agents connect via stdio)
+context serve --stdio
+
+# Or via HTTP for remote/multi-agent setups
+context serve --http --port 3000
+\`\`\`
+
+To add ContextKit as an MCP server in another agent's config:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "contextkit": {
+      "command": "npx",
+      "args": ["@runcontext/cli", "serve", "--stdio"]
+    }
+  }
+}
+\`\`\`
+
+### Exporting AI Blueprints
+
+Export the Gold-tier outcome as a portable YAML file:
+
+\`\`\`bash
+context blueprint ${modelName}
+# \u2192 blueprints/${modelName}.data-product.osi.yaml
+\`\`\`
+
+This AI Blueprint contains the complete semantic specification \u2014 share it, serve it via MCP, or import it into any OSI-compliant tool.
+
 ## MCP Tools (if using ContextKit as an MCP server)
 
 | Tool | Parameters | What it does |
@@ -3478,10 +3581,11 @@ ${failingSection}
 Inspect computed views in the database. Any calculated column is a candidate metric.
 
 \`\`\`sql
--- Find computed columns in views
+-- Find computed columns in views (information_schema queries are free/cheap)
 SELECT column_name, data_type
 FROM information_schema.columns
-WHERE table_name LIKE 'vw_%' AND data_type IN ('DOUBLE', 'FLOAT', 'INTEGER', 'BIGINT', 'DECIMAL');
+WHERE table_name LIKE 'vw_%' AND data_type IN ('DOUBLE', 'FLOAT', 'INTEGER', 'BIGINT', 'DECIMAL')
+LIMIT 100;
 \`\`\`
 
 For each computed column (e.g., \`opportunity_score\`, \`shops_per_10k\`, \`demand_signal_pct\`):
@@ -3529,9 +3633,10 @@ Models with 5+ datasets need at least 3 glossary terms linked by shared tags or
 For each join in the SQL views, define a relationship in the OSI model.
 
 \`\`\`sql
--- Find joins by examining view definitions
+-- Find joins by examining view definitions (metadata query, low cost)
 -- Look for patterns: ON table_a.col = table_b.col
 -- Or spatial joins: ABS(a.lat - b.lat) < threshold
+-- NEVER run the actual joins yourself to "test" them \u2014 just document the relationship
 \`\`\`
 
 For each join:
@@ -3549,12 +3654,14 @@ Models with 3+ datasets need at least 3 relationships.
 
 ### Golden Queries
 
-Write 3-5 SQL queries answering common business questions. **Test each query first!**
+Write 3-5 SQL queries answering common business questions. **Test each query with LIMIT first!**
 
 \`\`\`sql
--- Run the query, verify it returns sensible results, then document:
+-- Validate with LIMIT (never run unbounded queries to "test"):
 SELECT geoid, tract_name, opportunity_score
 FROM vw_candidate_zones ORDER BY opportunity_score DESC LIMIT 10;
+
+-- The golden query YAML can document the full query, but when you TEST it, always use LIMIT
 \`\`\`
 
 ## YAML Formats
@@ -4131,7 +4238,7 @@ var newCommand = new Command17("new").description("Scaffold a new data product i
 
 // src/index.ts
 var program = new Command18();
-program.name("context").description("ContextKit \u2014 AI-ready metadata governance over OSI").version("0.4.1");
+program.name("context").description("ContextKit \u2014 AI-ready metadata governance over OSI").version("0.4.2");
 program.addCommand(lintCommand);
 program.addCommand(buildCommand);
 program.addCommand(tierCommand);