@runcontext/cli 0.3.0 → 0.3.1

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command12 } from "commander";
+import { Command as Command15 } from "commander";
 
 // src/commands/lint.ts
 import { Command } from "commander";
@@ -508,25 +508,352 @@ var explainCommand = new Command4("explain").description("Look up models, terms,
 });
 
 // src/commands/fix.ts
+import { Command as Command7 } from "commander";
+import chalk8 from "chalk";
+import path7 from "path";
+import fs2 from "fs";
+import {
+  compile as compile6,
+  loadConfig as loadConfig6,
+  LintEngine as LintEngine3,
+  ALL_RULES as ALL_RULES3,
+  applyFixes as applyFixes2,
+  createAdapter as createAdapter3
+} from "@runcontext/core";
+
+// src/commands/introspect.ts
 import { Command as Command5 } from "commander";
 import chalk6 from "chalk";
 import path5 from "path";
-import fs2 from "fs";
+import { mkdirSync, writeFileSync as writeFileSync2, existsSync } from "fs";
 import {
-  compile as compile5,
   loadConfig as loadConfig4,
+  createAdapter,
+  scaffoldFromSchema
+} from "@runcontext/core";
+function parseDbUrl(db) {
+  if (db.startsWith("duckdb://")) {
+    return { adapter: "duckdb", path: db.slice("duckdb://".length) };
+  }
+  if (db.startsWith("postgres://") || db.startsWith("postgresql://")) {
+    return { adapter: "postgres", connection: db };
+  }
+  if (db.endsWith(".duckdb") || db.endsWith(".db")) {
+    return { adapter: "duckdb", path: db };
+  }
+  throw new Error(
+    `Cannot determine adapter from "${db}". Use duckdb:// or postgres:// prefix.`
+  );
+}
+var introspectCommand = new Command5("introspect").description("Introspect a database and scaffold Bronze-level OSI metadata").option(
+  "--db <url>",
+  "Database URL (e.g., duckdb://path.duckdb or postgres://...)"
+).option(
+  "--source <name>",
+  "Use a named data_source from contextkit.config.yaml"
+).option("--tables <glob>", 'Filter tables by glob pattern (e.g., "vw_*")').option(
+  "--model-name <name>",
+  "Name for the generated model (default: derived from source)"
+).action(async (opts) => {
+  try {
+    const config = loadConfig4(process.cwd());
+    const contextDir = path5.resolve(config.context_dir);
+    let dsConfig;
+    let dsName;
+    if (opts.db) {
+      dsConfig = parseDbUrl(opts.db);
+      dsName = opts.source ?? "default";
+    } else if (opts.source) {
+      if (!config.data_sources?.[opts.source]) {
+        console.error(
+          chalk6.red(
+            `Data source "${opts.source}" not found in config`
+          )
+        );
+        process.exit(1);
+      }
+      dsConfig = config.data_sources[opts.source];
+      dsName = opts.source;
+    } else {
+      const sources = config.data_sources;
+      if (!sources || Object.keys(sources).length === 0) {
+        console.error(
+          chalk6.red(
+            "No data source specified. Use --db <url> or configure data_sources in config"
+          )
+        );
+        process.exit(1);
+      }
+      const firstName = Object.keys(sources)[0];
+      dsConfig = sources[firstName];
+      dsName = firstName;
+    }
+    const adapter = await createAdapter(dsConfig);
+    await adapter.connect();
+    console.log(
+      chalk6.green(
+        `Connected to ${dsConfig.adapter}: ${dsConfig.path ?? dsConfig.connection}`
+      )
+    );
+    let tables = await adapter.listTables();
+    if (opts.tables) {
+      const pattern = opts.tables.replace(/\*/g, ".*");
+      const regex = new RegExp(`^${pattern}$`, "i");
+      tables = tables.filter((t) => regex.test(t.name));
+    }
+    console.log(`Discovered ${tables.length} tables/views`);
+    const columns = {};
+    for (const table of tables) {
+      columns[table.name] = await adapter.listColumns(table.name);
+    }
+    const totalCols = Object.values(columns).reduce(
+      (sum, cols) => sum + cols.length,
+      0
+    );
+    console.log(`Found ${totalCols} columns total`);
+    await adapter.disconnect();
+    const modelName = opts.modelName ?? dsName.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+    const result = scaffoldFromSchema({
+      modelName,
+      dataSourceName: dsName,
+      tables,
+      columns
+    });
+    for (const dir of ["models", "governance", "owners"]) {
+      const dirPath = path5.join(contextDir, dir);
+      if (!existsSync(dirPath)) mkdirSync(dirPath, { recursive: true });
+    }
+    const osiPath = path5.join(contextDir, "models", result.files.osi);
+    const govPath = path5.join(
+      contextDir,
+      "governance",
+      result.files.governance
+    );
+    const ownerPath = path5.join(contextDir, "owners", result.files.owner);
+    writeFileSync2(osiPath, result.osiYaml, "utf-8");
+    writeFileSync2(govPath, result.governanceYaml, "utf-8");
+    if (!existsSync(ownerPath)) {
+      writeFileSync2(ownerPath, result.ownerYaml, "utf-8");
+    }
+    console.log("");
+    console.log(chalk6.green("Scaffolded:"));
+    console.log(`  ${path5.relative(process.cwd(), osiPath)}`);
+    console.log(`  ${path5.relative(process.cwd(), govPath)}`);
+    console.log(`  ${path5.relative(process.cwd(), ownerPath)}`);
+    console.log("");
+    console.log(chalk6.cyan("Run `context tier` to check your tier score."));
+    console.log(
+      chalk6.cyan("Run `context verify` to validate against data.")
+    );
+  } catch (err) {
+    console.error(
+      chalk6.red(`Introspect failed: ${err.message}`)
+    );
+    process.exit(1);
+  }
+});
+
+// src/commands/verify.ts
+import { Command as Command6 } from "commander";
+import chalk7 from "chalk";
+import path6 from "path";
+import {
+  compile as compile5,
+  loadConfig as loadConfig5,
   LintEngine as LintEngine2,
   ALL_RULES as ALL_RULES2,
-  applyFixes as applyFixes2
+  createAdapter as createAdapter2
 } from "@runcontext/core";
-var fixCommand = new Command5("fix").description("Auto-fix lint issues").option("--context-dir <path>", "Path to context directory").option("--format <type>", "Output format: pretty or json", "pretty").option("--dry-run", "Show what would be fixed without writing files").action(async (opts) => {
+function findTable(dsName, graph, existingTables) {
+  if (existingTables.has(dsName)) return dsName;
+  for (const [, model] of graph.models) {
+    const ds = model.datasets.find((d) => d.name === dsName);
+    if (ds?.source) {
+      const tableName = ds.source.split(".").pop();
+      if (existingTables.has(tableName)) return tableName;
+    }
+  }
+  return void 0;
+}
+async function collectDataValidation(adapter, graph) {
+  const validation = {
+    existingTables: /* @__PURE__ */ new Map(),
+    existingColumns: /* @__PURE__ */ new Map(),
+    actualSampleValues: /* @__PURE__ */ new Map(),
+    goldenQueryResults: /* @__PURE__ */ new Map(),
+    guardrailResults: /* @__PURE__ */ new Map()
+  };
+  const tables = await adapter.listTables();
+  for (const t of tables) {
+    validation.existingTables.set(t.name, t.row_count);
+  }
+  for (const t of tables) {
+    const cols = await adapter.listColumns(t.name);
+    const colMap = new Map(cols.map((c) => [c.name, c.data_type]));
+    validation.existingColumns.set(t.name, colMap);
+  }
+  for (const [, gov] of graph.governance) {
+    if (!gov.fields) continue;
+    for (const [fieldKey, fieldGov] of Object.entries(gov.fields)) {
+      if (!fieldGov.sample_values || fieldGov.sample_values.length === 0)
+        continue;
+      const dotIdx = fieldKey.indexOf(".");
+      if (dotIdx < 0) continue;
+      const dsName = fieldKey.substring(0, dotIdx);
+      const fieldName = fieldKey.substring(dotIdx + 1);
+      const tableName = findTable(dsName, graph, validation.existingTables);
+      if (!tableName) continue;
+      try {
+        const result = await adapter.query(
+          `SELECT DISTINCT CAST("${fieldName}" AS VARCHAR) AS val FROM "${tableName}" WHERE "${fieldName}" IS NOT NULL LIMIT 50`
+        );
+        validation.actualSampleValues.set(
+          fieldKey,
+          result.rows.map((r) => String(r.val))
+        );
+      } catch {
+      }
+    }
+  }
+  for (const [, rules] of graph.rules) {
+    if (!rules.golden_queries) continue;
+    for (let i = 0; i < rules.golden_queries.length; i++) {
+      const gq = rules.golden_queries[i];
+      try {
+        const result = await adapter.query(gq.sql);
+        validation.goldenQueryResults.set(i, {
+          success: true,
+          rowCount: result.row_count
+        });
+      } catch (err) {
+        validation.goldenQueryResults.set(i, {
+          success: false,
+          error: err.message
+        });
+      }
+    }
+  }
+  for (const [, rules] of graph.rules) {
+    if (!rules.guardrail_filters) continue;
+    for (let i = 0; i < rules.guardrail_filters.length; i++) {
+      const gf = rules.guardrail_filters[i];
+      const testTable = gf.tables?.[0] ?? "unknown";
+      const tableName = findTable(testTable, graph, validation.existingTables);
+      if (!tableName) {
+        validation.guardrailResults.set(i, {
+          valid: false,
+          error: `Table "${testTable}" not found`
+        });
+        continue;
+      }
+      try {
+        await adapter.query(
+          `SELECT 1 FROM "${tableName}" WHERE ${gf.filter} LIMIT 1`
+        );
+        validation.guardrailResults.set(i, { valid: true });
+      } catch (err) {
+        validation.guardrailResults.set(i, {
+          valid: false,
+          error: err.message
+        });
+      }
+    }
+  }
+  return validation;
+}
+var verifyCommand = new Command6("verify").description("Validate metadata accuracy against a live database").option("--source <name>", "Use a specific data_source from config").option("--db <url>", "Database URL override (postgres:// or path.duckdb)").option("--context-dir <path>", "Path to context directory").option("--format <type>", "Output format: pretty or json", "pretty").action(async (opts) => {
   try {
-    const config = loadConfig4(process.cwd());
-    const contextDir = opts.contextDir ? path5.resolve(opts.contextDir) : path5.resolve(config.context_dir);
-    const { graph } = await compile5({ contextDir, config, rootDir: process.cwd() });
-    const overrides = config.lint?.severity_overrides;
-    const engine = new LintEngine2(overrides);
+    const config = loadConfig5(process.cwd());
+    const contextDir = opts.contextDir ? path6.resolve(opts.contextDir) : path6.resolve(config.context_dir);
+    const { graph, diagnostics: compileDiags } = await compile5({
+      contextDir,
+      config
+    });
+    let dsConfig;
+    if (opts.db) {
+      dsConfig = parseDbUrl(opts.db);
+    } else {
+      const sources = config.data_sources;
+      if (!sources || Object.keys(sources).length === 0) {
+        console.error(
+          chalk7.red(
+            "No data source configured. Add data_sources to contextkit.config.yaml or use --db."
+          )
+        );
+        process.exit(1);
+      }
+      const name = opts.source ?? Object.keys(sources)[0];
+      const resolved = sources[name];
+      if (!resolved) {
+        console.error(
+          chalk7.red(
+            `Data source "${name}" not found. Available: ${Object.keys(sources).join(", ")}`
+          )
+        );
+        process.exit(1);
+        return;
+      }
+      dsConfig = resolved;
+    }
+    const adapter = await createAdapter2(dsConfig);
+    await adapter.connect();
+    console.log(chalk7.green(`Connected to ${dsConfig.adapter}`));
+    console.log("Collecting validation data...\n");
+    graph.dataValidation = await collectDataValidation(adapter, graph);
+    await adapter.disconnect();
+    const engine = new LintEngine2();
     for (const rule of ALL_RULES2) {
+      if (rule.id.startsWith("data/")) {
+        engine.register(rule);
+      }
+    }
+    const dataDiags = engine.run(graph);
+    const allDiags = [...dataDiags];
+    if (allDiags.length === 0) {
+      const tableCount = graph.dataValidation.existingTables.size;
+      const totalRows = [
+        ...graph.dataValidation.existingTables.values()
+      ].reduce((a, b) => a + b, 0);
+      console.log(chalk7.green("All data validation checks passed.\n"));
+      console.log(
+        `Verified against ${tableCount} table(s) (${totalRows.toLocaleString()} total rows)`
+      );
+    } else {
+      console.log(formatDiagnostics(allDiags));
+    }
+    const hasErrors = allDiags.some((d) => d.severity === "error");
+    if (hasErrors) process.exit(1);
+  } catch (err) {
+    console.error(chalk7.red(`Verify failed: ${err.message}`));
+    process.exit(1);
+  }
+});
+
+// src/commands/fix.ts
+var fixCommand = new Command7("fix").description("Auto-fix lint issues").option("--context-dir <path>", "Path to context directory").option("--format <type>", "Output format: pretty or json", "pretty").option("--dry-run", "Show what would be fixed without writing files").option("--db <url>", "Database URL for data-aware fixes (postgres:// or path.duckdb)").option("--source <name>", "Use a specific data_source from config").action(async (opts) => {
+  try {
+    const config = loadConfig6(process.cwd());
+    const contextDir = opts.contextDir ? path7.resolve(opts.contextDir) : path7.resolve(config.context_dir);
+    const { graph } = await compile6({ contextDir, config, rootDir: process.cwd() });
+    let dsConfig;
+    if (opts.db) {
+      dsConfig = parseDbUrl(opts.db);
+    } else {
+      const sources = config.data_sources;
+      if (sources && Object.keys(sources).length > 0) {
+        const name = opts.source ?? Object.keys(sources)[0];
+        dsConfig = sources[name];
+      }
+    }
+    if (dsConfig) {
+      const adapter = await createAdapter3(dsConfig);
+      await adapter.connect();
+      graph.dataValidation = await collectDataValidation(adapter, graph);
+      await adapter.disconnect();
+    }
+    const overrides = config.lint?.severity_overrides;
+    const engine = new LintEngine3(overrides);
+    for (const rule of ALL_RULES3) {
       engine.register(rule);
     }
     const diagnostics = engine.run(graph);
@@ -535,7 +862,7 @@ var fixCommand = new Command5("fix").description("Auto-fix lint issues").option(
       if (opts.format === "json") {
         console.log(formatJson({ fixedFiles: [], fixCount: 0 }));
       } else {
-        console.log(chalk6.green("No fixable issues found."));
+        console.log(chalk8.green("No fixable issues found."));
       }
       return;
     }
@@ -552,10 +879,10 @@ var fixCommand = new Command5("fix").description("Auto-fix lint issues").option(
         );
       } else {
         console.log(
-          chalk6.yellow(`Dry run: ${fixable.length} issue(s) would be fixed in ${fixedFiles.size} file(s):`)
+          chalk8.yellow(`Dry run: ${fixable.length} issue(s) would be fixed in ${fixedFiles.size} file(s):`)
         );
         for (const file of fixedFiles.keys()) {
-          console.log(chalk6.gray(`  ${file}`));
+          console.log(chalk8.gray(`  ${file}`));
         }
       }
       return;
@@ -584,15 +911,15 @@ var fixCommand = new Command5("fix").description("Auto-fix lint issues").option(
 });
 
 // src/commands/dev.ts
-import { Command as Command6 } from "commander";
-import chalk7 from "chalk";
-import path6 from "path";
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { Command as Command8 } from "commander";
+import chalk9 from "chalk";
+import path8 from "path";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
 import {
-  compile as compile6,
-  loadConfig as loadConfig5,
-  LintEngine as LintEngine3,
-  ALL_RULES as ALL_RULES3,
+  compile as compile7,
+  loadConfig as loadConfig7,
+  LintEngine as LintEngine4,
+  ALL_RULES as ALL_RULES4,
   filterByDirectives as filterByDirectives2,
   applyFixes as applyFixes3
 } from "@runcontext/core";
@@ -601,15 +928,15 @@ function diagKey(d) {
 }
 var previousDiags = /* @__PURE__ */ new Map();
 async function runLint(contextDir, fix) {
-  const config = loadConfig5(process.cwd());
-  const { graph, diagnostics: compileDiags, directives } = await compile6({
+  const config = loadConfig7(process.cwd());
+  const { graph, diagnostics: compileDiags, directives } = await compile7({
     contextDir,
     config,
     rootDir: process.cwd()
   });
   const overrides = config.lint?.severity_overrides;
-  const engine = new LintEngine3(overrides);
-  for (const rule of ALL_RULES3) {
+  const engine = new LintEngine4(overrides);
+  for (const rule of ALL_RULES4) {
     engine.register(rule);
   }
   const lintDiags = engine.run(graph);
@@ -619,20 +946,20 @@ async function runLint(contextDir, fix) {
     if (fixable.length > 0) {
       const fixes = applyFixes3(fixable, (filePath) => readFileSync2(filePath, "utf-8"));
       for (const [file, content] of fixes) {
-        writeFileSync2(file, content, "utf-8");
+        writeFileSync3(file, content, "utf-8");
       }
-      const { graph: reGraph, diagnostics: reCompileDiags, directives: reDirs } = await compile6({
+      const { graph: reGraph, diagnostics: reCompileDiags, directives: reDirs } = await compile7({
         contextDir,
         config,
         rootDir: process.cwd()
       });
-      const reEngine = new LintEngine3(overrides);
-      for (const rule of ALL_RULES3) {
+      const reEngine = new LintEngine4(overrides);
+      for (const rule of ALL_RULES4) {
         reEngine.register(rule);
       }
       allDiags = filterByDirectives2([...reCompileDiags, ...reEngine.run(reGraph)], reDirs);
       if (fixable.length > 0) {
-        console.log(chalk7.green(`  Auto-fixed ${fixable.length} issue(s).`));
+        console.log(chalk9.green(`  Auto-fixed ${fixable.length} issue(s).`));
       }
     }
   }
@@ -649,16 +976,16 @@ async function runLint(contextDir, fix) {
     if (!currentDiags.has(key)) resolved.push(d);
   }
   console.clear();
-  console.log(chalk7.gray(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] Linting...`));
+  console.log(chalk9.gray(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] Linting...`));
   if (previousDiags.size > 0) {
     if (resolved.length > 0) {
-      console.log(chalk7.green(`  ${resolved.length} issue(s) resolved`));
+      console.log(chalk9.green(`  ${resolved.length} issue(s) resolved`));
     }
     if (newIssues.length > 0) {
-      console.log(chalk7.red(`  ${newIssues.length} new issue(s)`));
+      console.log(chalk9.red(`  ${newIssues.length} new issue(s)`));
     }
     if (resolved.length === 0 && newIssues.length === 0) {
-      console.log(chalk7.gray("  No changes"));
+      console.log(chalk9.gray("  No changes"));
     }
     console.log("");
   }
@@ -666,14 +993,14 @@ async function runLint(contextDir, fix) {
   console.log("");
   previousDiags = currentDiags;
 }
-var devCommand = new Command6("dev").description("Watch mode \u2014 re-run lint on file changes").option("--context-dir <path>", "Path to context directory").option("--fix", "Auto-fix problems on each re-lint").action(async (opts) => {
+var devCommand = new Command8("dev").description("Watch mode \u2014 re-run lint on file changes").option("--context-dir <path>", "Path to context directory").option("--fix", "Auto-fix problems on each re-lint").action(async (opts) => {
   try {
-    const config = loadConfig5(process.cwd());
-    const contextDir = opts.contextDir ? path6.resolve(opts.contextDir) : path6.resolve(config.context_dir);
+    const config = loadConfig7(process.cwd());
+    const contextDir = opts.contextDir ? path8.resolve(opts.contextDir) : path8.resolve(config.context_dir);
     const fix = opts.fix === true;
-    console.log(chalk7.blue(`Watching ${contextDir} for changes...`));
-    if (fix) console.log(chalk7.blue("Auto-fix enabled."));
-    console.log(chalk7.gray("Press Ctrl+C to stop.\n"));
+    console.log(chalk9.blue(`Watching ${contextDir} for changes...`));
+    if (fix) console.log(chalk9.blue("Auto-fix enabled."));
+    console.log(chalk9.gray("Press Ctrl+C to stop.\n"));
     await runLint(contextDir, fix);
     const { watch } = await import("chokidar");
     let debounceTimer = null;
@@ -690,21 +1017,21 @@ var devCommand = new Command6("dev").description("Watch mode \u2014 re-run lint
           await runLint(contextDir, fix);
         } catch (err) {
           console.error(
-            chalk7.red(`Lint error: ${err.message}`)
+            chalk9.red(`Lint error: ${err.message}`)
           );
         }
       }, 300);
     });
   } catch (err) {
-    console.error(chalk7.red(`Dev mode failed: ${err.message}`));
+    console.error(chalk9.red(`Dev mode failed: ${err.message}`));
     process.exit(1);
   }
 });
 
 // src/commands/init.ts
-import { Command as Command7 } from "commander";
-import chalk8 from "chalk";
-import path7 from "path";
+import { Command as Command9 } from "commander";
+import chalk10 from "chalk";
+import path9 from "path";
 import fs3 from "fs";
 var EXAMPLE_OSI = `version: "1.0"
 
@@ -769,26 +1096,26 @@ var EXAMPLE_CONFIG = `context_dir: context
 output_dir: dist
 minimum_tier: bronze
 `;
-var initCommand = new Command7("init").description("Scaffold a v0.2 ContextKit project structure").option("--dir <path>", "Root directory for the project", ".").action(async (opts) => {
+var initCommand = new Command9("init").description("Scaffold a v0.2 ContextKit project structure").option("--dir <path>", "Root directory for the project", ".").action(async (opts) => {
   try {
-    const rootDir = path7.resolve(opts.dir);
-    const contextDir = path7.join(rootDir, "context");
+    const rootDir = path9.resolve(opts.dir);
+    const contextDir = path9.join(rootDir, "context");
     const dirs = [
-      path7.join(contextDir, "models"),
-      path7.join(contextDir, "governance"),
-      path7.join(contextDir, "glossary"),
-      path7.join(contextDir, "owners")
+      path9.join(contextDir, "models"),
+      path9.join(contextDir, "governance"),
+      path9.join(contextDir, "glossary"),
+      path9.join(contextDir, "owners")
     ];
     for (const dir of dirs) {
       fs3.mkdirSync(dir, { recursive: true });
     }
     const files = [
       {
-        path: path7.join(contextDir, "models", "example-model.osi.yaml"),
+        path: path9.join(contextDir, "models", "example-model.osi.yaml"),
         content: EXAMPLE_OSI
       },
       {
-        path: path7.join(
+        path: path9.join(
           contextDir,
           "governance",
           "example-model.governance.yaml"
@@ -796,15 +1123,15 @@ var initCommand = new Command7("init").description("Scaffold a v0.2 ContextKit p
         content: EXAMPLE_GOVERNANCE
       },
       {
-        path: path7.join(contextDir, "glossary", "glossary.term.yaml"),
+        path: path9.join(contextDir, "glossary", "glossary.term.yaml"),
         content: EXAMPLE_TERM
       },
       {
-        path: path7.join(contextDir, "owners", "data-team.owner.yaml"),
+        path: path9.join(contextDir, "owners", "data-team.owner.yaml"),
         content: EXAMPLE_OWNER
       },
       {
-        path: path7.join(rootDir, "contextkit.config.yaml"),
+        path: path9.join(rootDir, "contextkit.config.yaml"),
         content: EXAMPLE_CONFIG
       }
     ];
@@ -812,11 +1139,11 @@ var initCommand = new Command7("init").description("Scaffold a v0.2 ContextKit p
     let skipped = 0;
     for (const file of files) {
       if (fs3.existsSync(file.path)) {
-        console.log(chalk8.gray(`  skip ${path7.relative(rootDir, file.path)} (exists)`));
+        console.log(chalk10.gray(`  skip ${path9.relative(rootDir, file.path)} (exists)`));
         skipped++;
       } else {
         fs3.writeFileSync(file.path, file.content, "utf-8");
-        console.log(chalk8.green(`  create ${path7.relative(rootDir, file.path)}`));
+        console.log(chalk10.green(`  create ${path9.relative(rootDir, file.path)}`));
         created++;
       }
     }
@@ -827,10 +1154,10 @@ var initCommand = new Command7("init").description("Scaffold a v0.2 ContextKit p
       )
     );
     console.log("");
-    console.log(chalk8.gray("Next steps:"));
-    console.log(chalk8.gray("  1. Edit the example files in context/"));
-    console.log(chalk8.gray("  2. Run: context lint"));
-    console.log(chalk8.gray("  3. Run: context build"));
+    console.log(chalk10.gray("Next steps:"));
+    console.log(chalk10.gray("  1. Edit the example files in context/"));
+    console.log(chalk10.gray("  2. Run: context lint"));
+    console.log(chalk10.gray("  3. Run: context build"));
   } catch (err) {
     console.error(formatError(err.message));
     process.exit(1);
@@ -838,15 +1165,15 @@ var initCommand = new Command7("init").description("Scaffold a v0.2 ContextKit p
 });
 
 // src/commands/site.ts
-import { Command as Command8 } from "commander";
-import chalk9 from "chalk";
-import path8 from "path";
-import { compile as compile7, loadConfig as loadConfig6, emitManifest as emitManifest2 } from "@runcontext/core";
-var siteCommand = new Command8("site").description("Build a static documentation site from compiled context").option("--context-dir <path>", "Path to context directory").option("--output-dir <path>", "Path to site output directory").action(async (opts) => {
+import { Command as Command10 } from "commander";
+import chalk11 from "chalk";
+import path10 from "path";
+import { compile as compile8, loadConfig as loadConfig8, emitManifest as emitManifest2 } from "@runcontext/core";
+var siteCommand = new Command10("site").description("Build a static documentation site from compiled context").option("--context-dir <path>", "Path to context directory").option("--output-dir <path>", "Path to site output directory").action(async (opts) => {
   try {
-    const config = loadConfig6(process.cwd());
-    const contextDir = opts.contextDir ? path8.resolve(opts.contextDir) : path8.resolve(config.context_dir);
-    const { graph } = await compile7({ contextDir, config, rootDir: process.cwd() });
+    const config = loadConfig8(process.cwd());
+    const contextDir = opts.contextDir ? path10.resolve(opts.contextDir) : path10.resolve(config.context_dir);
+    const { graph } = await compile8({ contextDir, config, rootDir: process.cwd() });
     const manifest = emitManifest2(graph, config);
     let buildSite;
     try {
@@ -856,15 +1183,15 @@ var siteCommand = new Command8("site").description("Build a static documentation
     }
     if (!buildSite) {
       console.log(
-        chalk9.yellow(
+        chalk11.yellow(
           "Site generator is not yet available. Install @runcontext/site to enable this command."
         )
       );
       process.exit(0);
     }
-    const outputDir = opts.outputDir ? path8.resolve(opts.outputDir) : path8.resolve(config.site?.base_path ?? "site");
+    const outputDir = opts.outputDir ? path10.resolve(opts.outputDir) : path10.resolve(config.site?.base_path ?? "site");
     await buildSite(manifest, config, outputDir);
-    console.log(chalk9.green(`Site built to ${outputDir}`));
+    console.log(chalk11.green(`Site built to ${outputDir}`));
   } catch (err) {
     console.error(formatError(err.message));
     process.exit(1);
@@ -872,9 +1199,9 @@ var siteCommand = new Command8("site").description("Build a static documentation
 });
 
 // src/commands/serve.ts
-import { Command as Command9 } from "commander";
-import chalk10 from "chalk";
-var serveCommand = new Command9("serve").description("Start the MCP server (stdio transport)").option("--context-dir <path>", "Path to context directory").action(async (opts) => {
+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) => {
   try {
     let startServer;
     try {
@@ -884,13 +1211,13 @@ var serveCommand = new Command9("serve").description("Start the MCP server (stdi
     }
     if (!startServer) {
       console.log(
-        chalk10.yellow(
+        chalk12.yellow(
           "MCP server is not available. Install @runcontext/mcp to enable this command."
         )
       );
       process.exit(1);
     }
-    console.log(chalk10.blue("Starting MCP server (stdio transport)..."));
+    console.log(chalk12.blue("Starting MCP server (stdio transport)..."));
     await startServer({
       contextDir: opts.contextDir,
       rootDir: process.cwd()
@@ -902,13 +1229,13 @@ var serveCommand = new Command9("serve").description("Start the MCP server (stdi
 });
 
 // src/commands/validate-osi.ts
-import { Command as Command10 } from "commander";
-import chalk11 from "chalk";
-import path9 from "path";
+import { Command as Command12 } from "commander";
+import chalk13 from "chalk";
+import path11 from "path";
 import { parseFile, osiDocumentSchema } from "@runcontext/core";
-var validateOsiCommand = new Command10("validate-osi").description("Validate a single OSI file against the schema").argument("<file>", "Path to the OSI YAML file").option("--format <type>", "Output format: pretty or json", "pretty").action(async (file, opts) => {
+var validateOsiCommand = new Command12("validate-osi").description("Validate a single OSI file against the schema").argument("<file>", "Path to the OSI YAML file").option("--format <type>", "Output format: pretty or json", "pretty").action(async (file, opts) => {
   try {
-    const filePath = path9.resolve(file);
+    const filePath = path11.resolve(file);
     const parsed = await parseFile(filePath, "model");
     const result = osiDocumentSchema.safeParse(parsed.data);
     if (result.success) {
@@ -937,9 +1264,9 @@ var validateOsiCommand = new Command10("validate-osi").description("Validate a s
           })
         );
       } else {
-        console.error(chalk11.red(`Validation failed for ${filePath}:`));
+        console.error(chalk13.red(`Validation failed for ${filePath}:`));
         for (const issue of issues) {
-          console.error(chalk11.red(`  ${issue.path}: ${issue.message}`));
+          console.error(chalk13.red(`  ${issue.path}: ${issue.message}`));
         }
       }
       process.exit(1);
@@ -950,46 +1277,268 @@ var validateOsiCommand = new Command10("validate-osi").description("Validate a s
   }
 });
 
+// src/commands/enrich.ts
+import { Command as Command13 } from "commander";
+import chalk14 from "chalk";
+import path12 from "path";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync4, mkdirSync as mkdirSync2, existsSync as existsSync2, readdirSync } from "fs";
+import * as yaml from "yaml";
+import {
+  compile as compile9,
+  loadConfig as loadConfig9,
+  computeTier as computeTier2,
+  createAdapter as createAdapter4,
+  suggestEnrichments,
+  inferSemanticRole,
+  inferAggregation
+} from "@runcontext/core";
+function findFileRecursive(dir, suffix) {
+  if (!existsSync2(dir)) return void 0;
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path12.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const found = findFileRecursive(fullPath, suffix);
+      if (found) return found;
+    } else if (entry.name.endsWith(suffix)) {
+      return fullPath;
+    }
+  }
+  return void 0;
+}
+var enrichCommand = new Command13("enrich").description("Suggest or apply metadata enrichments to reach a target tier").option("--target <tier>", "Target tier: silver or gold", "silver").option("--apply", "Write suggestions to YAML files").option("--source <name>", "Data source for sample values").option("--db <url>", "Database URL for sample values").option("--context-dir <path>", "Path to context directory").action(async (opts) => {
+  try {
+    const config = loadConfig9(process.cwd());
+    const contextDir = opts.contextDir ? path12.resolve(opts.contextDir) : path12.resolve(config.context_dir);
+    const target = opts.target;
+    if (!["silver", "gold"].includes(target)) {
+      console.error(chalk14.red('--target must be "silver" or "gold"'));
+      process.exit(1);
+    }
+    const { graph } = await compile9({ contextDir, config });
+    for (const [modelName] of graph.models) {
+      const tierScore = computeTier2(modelName, graph);
+      console.log(chalk14.bold(`${modelName}: ${tierScore.tier.toUpperCase()}`));
+      if (tierScore.tier === target || target === "silver" && tierScore.tier === "gold") {
+        console.log(chalk14.green(`  Already at ${target} or above.
+`));
+        continue;
+      }
+      const model = graph.models.get(modelName);
+      const datasetNames = model.datasets.map((d) => d.name);
+      const suggestions = suggestEnrichments(target, tierScore, datasetNames);
+      if (!suggestions.governance && !suggestions.lineage && !suggestions.glossaryTerms && !suggestions.needsRulesFile && !suggestions.needsSampleValues && !suggestions.needsSemanticRoles) {
+        console.log(chalk14.green("  No suggestions needed.\n"));
+        continue;
+      }
+      if (suggestions.governance?.trust) {
+        console.log(chalk14.yellow(`  + Add trust: ${suggestions.governance.trust}`));
+      }
+      if (suggestions.governance?.tags) {
+        console.log(chalk14.yellow(`  + Add tags: [${suggestions.governance.tags.join(", ")}]`));
+      }
+      if (suggestions.governance?.refreshAll) {
+        console.log(chalk14.yellow(`  + Add refresh: ${suggestions.governance.refreshAll}`));
+      }
+      if (suggestions.lineage) {
+        console.log(chalk14.yellow(`  + Add lineage with ${suggestions.lineage.upstream?.length ?? 0} upstream sources`));
+      }
+      if (suggestions.glossaryTerms) {
+        console.log(chalk14.yellow(`  + Generate ${suggestions.glossaryTerms.length} glossary term(s)`));
+      }
+      if (suggestions.needsSampleValues) {
+        console.log(chalk14.yellow("  + Populate sample_values from database"));
+      }
+      if (suggestions.needsSemanticRoles) {
+        console.log(chalk14.yellow("  + Infer semantic_role for all fields"));
+      }
+      if (suggestions.needsRulesFile) {
+        console.log(chalk14.yellow("  + Generate rules file"));
+      }
+      if (!opts.apply) {
+        console.log(chalk14.cyan("\n  Run with --apply to write these changes.\n"));
+        continue;
+      }
+      const govFilePath = findFileRecursive(contextDir, `${modelName}.governance.yaml`);
+      if (govFilePath) {
+        const govContent = readFileSync3(govFilePath, "utf-8");
+        const govDoc = yaml.parse(govContent) ?? {};
+        if (suggestions.governance?.trust) {
+          govDoc.trust = suggestions.governance.trust;
+        }
+        if (suggestions.governance?.tags) {
+          govDoc.tags = suggestions.governance.tags;
+        }
+        if (suggestions.governance?.refreshAll) {
+          for (const dsName of Object.keys(govDoc.datasets ?? {})) {
+            govDoc.datasets[dsName].refresh = suggestions.governance.refreshAll;
+          }
+        }
+        if (suggestions.needsSemanticRoles) {
+          govDoc.fields = govDoc.fields ?? {};
+          let adapter = null;
+          const dsConfig = opts.db ? parseDbUrl(opts.db) : config.data_sources?.[opts.source ?? Object.keys(config.data_sources ?? {})[0]];
+          if (dsConfig) {
+            adapter = await createAdapter4(dsConfig);
+            await adapter.connect();
+          }
+          for (const ds of model.datasets) {
+            let columns = [];
+            if (adapter) {
+              const tableName = ds.source?.split(".").pop() ?? ds.name;
+              try {
+                columns = await adapter.listColumns(tableName);
+              } catch {
+              }
+            }
+            for (const field of ds.fields ?? []) {
+              const fieldKey = `${ds.name}.${field.name}`;
+              if (govDoc.fields[fieldKey]?.semantic_role) continue;
+              const col = columns.find((c) => c.name === field.name);
+              const isPK = col?.is_primary_key ?? field.name.endsWith("_id");
+              const dataType = col?.data_type ?? "VARCHAR";
+              govDoc.fields[fieldKey] = govDoc.fields[fieldKey] ?? {};
+              const role = inferSemanticRole(field.name, dataType, isPK);
+              govDoc.fields[fieldKey].semantic_role = role;
+              if (role === "metric") {
+                govDoc.fields[fieldKey].default_aggregation = inferAggregation(field.name);
+                govDoc.fields[fieldKey].additive = govDoc.fields[fieldKey].default_aggregation === "SUM";
+              }
+            }
+          }
+          if (adapter) await adapter.disconnect();
+        }
+        if (suggestions.needsSampleValues) {
+          govDoc.fields = govDoc.fields ?? {};
+          const dsConfig2 = opts.db ? parseDbUrl(opts.db) : config.data_sources?.[opts.source ?? Object.keys(config.data_sources ?? {})[0]];
+          if (dsConfig2) {
+            const adapter2 = await createAdapter4(dsConfig2);
+            await adapter2.connect();
+            let count = 0;
+            for (const ds of model.datasets) {
+              if (count >= 2) break;
+              const tableName = ds.source?.split(".").pop() ?? ds.name;
+              for (const field of ds.fields ?? []) {
+                if (count >= 2) break;
+                const fieldKey = `${ds.name}.${field.name}`;
+                if (govDoc.fields[fieldKey]?.sample_values?.length > 0) continue;
+                try {
+                  const result = await adapter2.query(
+                    `SELECT DISTINCT CAST("${field.name}" AS VARCHAR) AS val FROM "${tableName}" WHERE "${field.name}" IS NOT NULL LIMIT 5`
+                  );
+                  if (result.rows.length > 0) {
+                    govDoc.fields[fieldKey] = govDoc.fields[fieldKey] ?? {};
+                    govDoc.fields[fieldKey].sample_values = result.rows.map((r) => String(r.val));
+                    count++;
+                  }
+                } catch {
+                }
+              }
+            }
+            await adapter2.disconnect();
+          }
+        }
+        writeFileSync4(govFilePath, yaml.stringify(govDoc, { lineWidth: 120 }), "utf-8");
+        console.log(chalk14.green(`  Updated: ${path12.relative(process.cwd(), govFilePath)}`));
+      }
+      if (suggestions.lineage) {
+        const lineageDir = path12.join(contextDir, "lineage");
+        if (!existsSync2(lineageDir)) mkdirSync2(lineageDir, { recursive: true });
+        const lineagePath = path12.join(lineageDir, `${modelName}.lineage.yaml`);
+        if (!existsSync2(lineagePath)) {
+          const lineageDoc = {
+            model: modelName,
+            upstream: suggestions.lineage.upstream
+          };
+          writeFileSync4(lineagePath, yaml.stringify(lineageDoc, { lineWidth: 120 }), "utf-8");
+          console.log(chalk14.green(`  Created: ${path12.relative(process.cwd(), lineagePath)}`));
+        }
+      }
+      if (suggestions.glossaryTerms) {
+        const glossaryDir = path12.join(contextDir, "glossary");
+        if (!existsSync2(glossaryDir)) mkdirSync2(glossaryDir, { recursive: true });
+        for (const term of suggestions.glossaryTerms) {
+          const termPath = path12.join(glossaryDir, `${term.id}.term.yaml`);
+          if (!existsSync2(termPath)) {
+            writeFileSync4(termPath, yaml.stringify(term, { lineWidth: 120 }), "utf-8");
+            console.log(chalk14.green(`  Created: ${path12.relative(process.cwd(), termPath)}`));
+          }
+        }
+      }
+      if (suggestions.needsRulesFile) {
+        const rulesDir = path12.join(contextDir, "rules");
+        if (!existsSync2(rulesDir)) mkdirSync2(rulesDir, { recursive: true });
+        const rulesPath = path12.join(rulesDir, `${modelName}.rules.yaml`);
+        if (!existsSync2(rulesPath)) {
+          const rulesDoc = {
+            model: modelName,
+            golden_queries: [
+              { question: "TODO: What is the total count?", sql: "SELECT COUNT(*) FROM table_name" },
+              { question: "TODO: What are the top records?", sql: "SELECT * FROM table_name LIMIT 10" },
+              { question: "TODO: What is the distribution?", sql: "SELECT column, COUNT(*) FROM table_name GROUP BY column" }
+            ],
+            business_rules: [
+              { name: "TODO: rule-name", definition: "TODO: describe the business rule" }
+            ],
+            guardrail_filters: [
+              { name: "TODO: filter-name", filter: "column IS NOT NULL", reason: "TODO: explain why" }
+            ],
+            hierarchies: [
+              { name: "TODO: hierarchy-name", levels: ["level1", "level2"], dataset: datasetNames[0] ?? "dataset" }
+            ]
+          };
+          writeFileSync4(rulesPath, yaml.stringify(rulesDoc, { lineWidth: 120 }), "utf-8");
+          console.log(chalk14.green(`  Created: ${path12.relative(process.cwd(), rulesPath)} (with TODOs)`));
+        }
+      }
+      console.log("");
+    }
+  } catch (err) {
+    console.error(chalk14.red(`Enrich failed: ${err.message}`));
+    process.exit(1);
+  }
+});
+
 // src/commands/rules.ts
-import { Command as Command11 } from "commander";
-import chalk12 from "chalk";
-import { ALL_RULES as ALL_RULES4 } from "@runcontext/core";
+import { Command as Command14 } from "commander";
+import chalk15 from "chalk";
+import { ALL_RULES as ALL_RULES5 } from "@runcontext/core";
 function formatRuleTable(rules) {
   if (rules.length === 0) {
-    return chalk12.gray("No rules match the filters.");
+    return chalk15.gray("No rules match the filters.");
   }
   const lines = [];
   const header = `${"ID".padEnd(40)} ${"Tier".padEnd(8)} ${"Severity".padEnd(10)} ${"Fix".padEnd(5)} Description`;
-  lines.push(chalk12.bold(header));
-  lines.push(chalk12.gray("\u2500".repeat(100)));
+  lines.push(chalk15.bold(header));
+  lines.push(chalk15.gray("\u2500".repeat(100)));
   for (const rule of rules) {
     const tier = rule.tier ?? "\u2014";
     const tierCol = colorTier(tier);
-    const fixCol = rule.fixable ? chalk12.green("yes") : chalk12.gray("no");
-    const sevCol = rule.defaultSeverity === "error" ? chalk12.red(rule.defaultSeverity) : chalk12.yellow(rule.defaultSeverity);
-    const deprecated = rule.deprecated ? chalk12.gray(" (deprecated)") : "";
+    const fixCol = rule.fixable ? chalk15.green("yes") : chalk15.gray("no");
+    const sevCol = rule.defaultSeverity === "error" ? chalk15.red(rule.defaultSeverity) : chalk15.yellow(rule.defaultSeverity);
+    const deprecated = rule.deprecated ? chalk15.gray(" (deprecated)") : "";
     lines.push(
       `${rule.id.padEnd(40)} ${tierCol.padEnd(8 + (tierCol.length - tier.length))} ${sevCol.padEnd(10 + (sevCol.length - rule.defaultSeverity.length))} ${fixCol.padEnd(5 + (fixCol.length - (rule.fixable ? 3 : 2)))} ${rule.description}${deprecated}`
     );
   }
   lines.push("");
-  lines.push(chalk12.gray(`${rules.length} rule(s) total`));
+  lines.push(chalk15.gray(`${rules.length} rule(s) total`));
   return lines.join("\n");
 }
 function colorTier(tier) {
   switch (tier) {
     case "gold":
-      return chalk12.yellow(tier);
+      return chalk15.yellow(tier);
     case "silver":
-      return chalk12.white(tier);
+      return chalk15.white(tier);
     case "bronze":
-      return chalk12.hex("#CD7F32")(tier);
+      return chalk15.hex("#CD7F32")(tier);
     default:
-      return chalk12.gray(tier);
+      return chalk15.gray(tier);
   }
 }
-var rulesCommand = new Command11("rules").description("List all lint rules with metadata").option("--tier <tier>", "Filter by tier: bronze, silver, gold").option("--fixable", "Show only fixable rules").option("--format <type>", "Output format: pretty or json", "pretty").action((opts) => {
-  let rules = [...ALL_RULES4];
+var rulesCommand = new Command14("rules").description("List all lint rules with metadata").option("--tier <tier>", "Filter by tier: bronze, silver, gold").option("--fixable", "Show only fixable rules").option("--format <type>", "Output format: pretty or json", "pretty").action((opts) => {
+  let rules = [...ALL_RULES5];
   if (opts.tier) {
     const tier = opts.tier;
     rules = rules.filter((r) => r.tier === tier);
@@ -1014,8 +1563,8 @@ var rulesCommand = new Command11("rules").description("List all lint rules with
 });
 
 // src/index.ts
-var program = new Command12();
-program.name("context").description("ContextKit \u2014 AI-ready metadata governance over OSI").version("0.2.1");
+var program = new Command15();
+program.name("context").description("ContextKit \u2014 AI-ready metadata governance over OSI").version("0.3.1");
 program.addCommand(lintCommand);
 program.addCommand(buildCommand);
 program.addCommand(tierCommand);
@@ -1026,6 +1575,9 @@ program.addCommand(initCommand);
 program.addCommand(siteCommand);
 program.addCommand(serveCommand);
 program.addCommand(validateOsiCommand);
+program.addCommand(introspectCommand);
+program.addCommand(verifyCommand);
+program.addCommand(enrichCommand);
 program.addCommand(rulesCommand);
 program.parse();
 //# sourceMappingURL=index.js.map