@runcontext/cli 0.3.2 → 0.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Kittelson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @runcontext/cli
+
+CLI for [ContextKit](https://github.com/erickittelson/ContextKit) — AI-ready metadata governance over OSI.
+
+**Your data already has a schema. ContextKit gives it meaning.**
+
+## Installation
+
+```bash
+# Global install
+npm install -g @runcontext/cli
+
+# Or per-project
+npm install -D @runcontext/cli
+```
+
+## Quick Start
+
+```bash
+# Point at any database — interactive wizard does the rest
+context setup
+
+# Or step by step
+context introspect --db duckdb://warehouse.duckdb
+context enrich --target silver --apply
+context tier
+```
+
+## Commands
+
+### Core Workflow
+
+```bash
+context setup                    # Interactive wizard — database to metadata in one flow
+context introspect               # Scan a database → scaffold Bronze-level OSI metadata
+context enrich --target silver   # Auto-enrich metadata toward a target tier
+context lint                     # Run 37 lint rules against context files
+context fix --write              # Auto-fix lint issues where possible
+context build                    # Compile context files → emit manifest JSON
+context tier [model]             # Show Bronze/Silver/Gold scorecard
+```
+
+### Exploration
+
+```bash
+context explain <name>           # Look up any model, term, or owner
+context rules                    # List all lint rules with tier, severity, fixability
+context validate-osi <file>      # Validate a single OSI file against the schema
+context verify                   # Check metadata accuracy against a live database
+```
+
+### Serving
+
+```bash
+context serve --stdio            # Start MCP server over stdio (for Claude, Cursor, etc.)
+context serve --http --port 3000 # Start MCP server over HTTP
+context site                     # Generate a static documentation site
+context dev                      # Watch mode — re-lint on file changes
+context init                     # Scaffold a new project structure
+```
+
+## The Tier System
+
+| Tier | What it means | How to get there |
+|---|---|---|
+| **Bronze** | Discoverable — described, owned, classified | `context introspect` |
+| **Silver** | Trusted — lineage, glossary, sample values, trust status | `context enrich --target silver` |
+| **Gold** | AI-Ready — semantic roles, golden queries, guardrails, business rules | Human curation + `context enrich --target gold` |
+
+## Database Support
+
+| Adapter | Connection |
+|---|---|
+| DuckDB | `--db duckdb://path/to/file.duckdb` |
+| PostgreSQL | `--db postgres://user:pass@host:5432/db` |
+
+## MCP Server
+
+Expose your metadata to AI agents:
+
+```bash
+# For Claude Code / Cursor
+context serve --stdio
+
+# For multi-agent setups
+context serve --http --port 3000
+```
+
+Add to `.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "contextkit": {
+      "command": "npx",
+      "args": ["@runcontext/cli", "serve", "--stdio"]
+    }
+  }
+}
+```
+
+## Full Documentation
+
+See the [ContextKit repository](https://github.com/erickittelson/ContextKit) for complete docs, file structure, tier requirements, and examples.
+
+## License
+
+MIT

package/dist/index.js

@@ -1201,15 +1201,14 @@ var siteCommand = new Command10("site").description("Build a static documentatio
 // src/commands/serve.ts
 import { Command as Command11 } from "commander";
 import chalk12 from "chalk";
-var serveCommand = new Command11("serve").description("Start the MCP server (stdio transport)").option("--context-dir <path>", "Path to context directory").action(async (opts) => {
+var serveCommand = new Command11("serve").description("Start the MCP server (stdio or HTTP transport)").option("--context-dir <path>", "Path to context directory").option("--http", "Serve over HTTP instead of stdio").option("--port <number>", "HTTP port (default: 3000)", "3000").option("--host <address>", "HTTP host (default: 0.0.0.0)", "0.0.0.0").action(async (opts) => {
   try {
-    let startServer;
+    let mcpModule;
     try {
-      const mcpModule = await import("@runcontext/mcp");
-      startServer = mcpModule.startServer;
+      mcpModule = await import("@runcontext/mcp");
     } catch {
     }
-    if (!startServer) {
+    if (!mcpModule) {
       console.log(
         chalk12.yellow(
           "MCP server is not available. Install @runcontext/mcp to enable this command."
@@ -1217,11 +1216,24 @@ var serveCommand = new Command11("serve").description("Start the MCP server (std
       );
       process.exit(1);
     }
-    console.log(chalk12.blue("Starting MCP server (stdio transport)..."));
-    await startServer({
-      contextDir: opts.contextDir,
-      rootDir: process.cwd()
-    });
+    if (opts.http) {
+      const startServerHttp = mcpModule.startServerHttp;
+      const port = parseInt(opts.port, 10);
+      console.log(chalk12.blue(`Starting MCP server (HTTP on port ${port})...`));
+      await startServerHttp({
+        contextDir: opts.contextDir,
+        rootDir: process.cwd(),
+        port,
+        host: opts.host
+      });
+    } else {
+      const startServer = mcpModule.startServer;
+      console.log(chalk12.blue("Starting MCP server (stdio transport)..."));
+      await startServer({
+        contextDir: opts.contextDir,
+        rootDir: process.cwd()
+      });
+    }
   } catch (err) {
     console.error(formatError(err.message));
     process.exit(1);
@@ -2444,7 +2456,93 @@ ${failingSection}
 
 **Bronze (7):** descriptions, owner, security, grain, table_type
 **Silver (+6):** trust, 2+ tags, glossary linked, lineage, refresh, 2+ sample_values
-**Gold (+21):** semantic_role on ALL fields, metric aggregation/additive, 1+ guardrail, 3+ golden queries, 1+ business rule, 1+ hierarchy, 1+ default_filter, trust=endorsed, contactable owner, 1+ relationship, description \u226550 chars, ai_context (no TODO), 1+ business_context, version, field descriptions not lazy, glossary definitions substantive, lineage references real sources, grain statements specific, ai_context filled in
+**Gold (+24):** semantic_role on ALL fields, metric aggregation/additive, 1+ guardrail, 3+ golden queries, 1+ business rule, 1+ hierarchy, 1+ default_filter, trust=endorsed, contactable owner, 1+ relationship, description \u226550 chars, ai_context (no TODO), 1+ business_context, version, field descriptions not lazy, glossary definitions substantive, lineage references real sources, grain statements specific, ai_context filled in, 3+ relationships (models with 3+ datasets), 1+ computed metric, 3+ glossary terms (models with 5+ datasets)
+
+## How to Reach Gold: Curation Recipes
+
+### Metrics (gold/metrics-defined)
+
+Inspect computed views in the database. Any calculated column is a candidate metric.
+
+\`\`\`sql
+-- Find computed columns in views
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_name LIKE 'vw_%' AND data_type IN ('DOUBLE', 'FLOAT', 'INTEGER', 'BIGINT', 'DECIMAL');
+\`\`\`
+
+For each computed column (e.g., \`opportunity_score\`, \`shops_per_10k\`, \`demand_signal_pct\`):
+1. Query it to understand what it measures
+2. Add it to the model's \`metrics[]\` array in the OSI YAML
+3. Include the SQL expression, aggregation type (SUM/AVG), and a human description
+4. Mark whether it's additive (can be summed across dimensions)
+
+Example:
+\`\`\`yaml
+metrics:
+  - name: opportunity_score
+    expression:
+      dialects:
+        - dialect: DuckDB
+          expression: "(population/10000)*2 + (income/50000)*2 + (10-shops_per_10k)*3 + transit*1.5 + demand*0.5"
+    description: Composite score ranking census tracts for coffee shop viability
+    aggregation: AVG
+    additive: false
+\`\`\`
+
+### Glossary Terms (gold/glossary-coverage)
+
+For each key business concept your model measures, create a glossary term file.
+
+Think about the terms a new analyst would need defined:
+- What is "supply saturation"? (> 5.0 shops per 10k people)
+- What is a "demand signal"? (review mentioning wait/line/crowded/busy)
+- What is "opportunity score"? (composite ranking formula)
+
+For each term, create \`context/glossary/<term-name>.term.yaml\`:
+\`\`\`yaml
+term: supply-saturation
+definition: >
+  A measure of coffee shop density per census tract. Calculated as
+  shops per 10,000 residents. Tracts with > 5.0 are considered saturated.
+owner: analytics-team
+tags: [coffee-analytics]
+\`\`\`
+
+Models with 5+ datasets need at least 3 glossary terms linked by shared tags or owner.
+
+### Relationships (gold/relationships-coverage)
+
+For each join in the SQL views, define a relationship in the OSI model.
+
+\`\`\`sql
+-- Find joins by examining view definitions
+-- Look for patterns: ON table_a.col = table_b.col
+-- Or spatial joins: ABS(a.lat - b.lat) < threshold
+\`\`\`
+
+For each join:
+\`\`\`yaml
+relationships:
+  - name: business-to-tract
+    left_dataset: yelp_business
+    right_dataset: census_tract
+    join_type: spatial
+    cardinality: many-to-one
+    description: Businesses assigned to nearest census tract within 0.02 degrees (~1 mile)
+\`\`\`
+
+Models with 3+ datasets need at least 3 relationships.
+
+### Golden Queries
+
+Write 3-5 SQL queries answering common business questions. **Test each query first!**
+
+\`\`\`sql
+-- Run the query, verify it returns sensible results, then document:
+SELECT geoid, tract_name, opportunity_score
+FROM vw_candidate_zones ORDER BY opportunity_score DESC LIMIT 10;
+\`\`\`
 
 ## YAML Formats