@runcontext/cli 0.3.1 → 0.3.2

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command15 } from "commander";
+import { Command as Command16 } from "commander";
 
 // src/commands/lint.ts
 import { Command } from "commander";
@@ -1562,8 +1562,1028 @@ var rulesCommand = new Command14("rules").description("List all lint rules with
   }
 });
 
+// src/commands/setup.ts
+import { Command as Command15 } from "commander";
+import * as p9 from "@clack/prompts";
+import chalk16 from "chalk";
+
+// src/setup/steps/connect.ts
+import * as p from "@clack/prompts";
+import path13 from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "fs";
+import * as yaml2 from "yaml";
+import { loadConfig as loadConfig10, createAdapter as createAdapter5 } from "@runcontext/core";
+function autoDetectDb(cwd) {
+  try {
+    const config = loadConfig10(cwd);
+    if (config.data_sources && Object.keys(config.data_sources).length > 0) {
+      const name = Object.keys(config.data_sources)[0];
+      const ds = config.data_sources[name];
+      const loc = ds.path ?? ds.connection ?? name;
+      return { dsConfig: ds, label: `${ds.adapter} \u2014 ${loc} (from contextkit.config.yaml)` };
+    }
+  } catch {
+  }
+  if (process.env.DATABASE_URL) {
+    try {
+      const ds = parseDbUrl(process.env.DATABASE_URL);
+      return { dsConfig: ds, label: `${ds.adapter} \u2014 $DATABASE_URL` };
+    } catch {
+    }
+  }
+  if (process.env.DUCKDB_PATH && existsSync3(process.env.DUCKDB_PATH)) {
+    return {
+      dsConfig: { adapter: "duckdb", path: process.env.DUCKDB_PATH },
+      label: `duckdb \u2014 $DUCKDB_PATH`
+    };
+  }
+  const mcpPath = path13.join(cwd, ".claude", "mcp.json");
+  if (existsSync3(mcpPath)) {
+    try {
+      const mcpConfig = JSON.parse(readFileSync4(mcpPath, "utf-8"));
+      const duckdbServer = mcpConfig.mcpServers?.duckdb;
+      if (duckdbServer?.args) {
+        const args = duckdbServer.args;
+        const idx = args.indexOf("--db-path");
+        if (idx >= 0 && args[idx + 1]) {
+          const dbPath = args[idx + 1];
+          if (existsSync3(dbPath)) {
+            return {
+              dsConfig: { adapter: "duckdb", path: dbPath },
+              label: `duckdb \u2014 ${path13.basename(dbPath)} (from .claude/mcp.json)`
+            };
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return void 0;
+}
+async function promptForConnection() {
+  const connector = await p.select({
+    message: "Select your database",
+    options: [
+      { value: "duckdb", label: "DuckDB", hint: "Local .duckdb file" },
+      { value: "postgres", label: "PostgreSQL", hint: "Connection string" }
+    ]
+  });
+  if (p.isCancel(connector)) return void 0;
+  if (connector === "duckdb") {
+    const method = await p.select({
+      message: "How do you connect?",
+      options: [
+        { value: "env", label: "Environment variable", hint: "e.g. DUCKDB_PATH" },
+        { value: "path", label: "File path", hint: "e.g. ./warehouse.duckdb" }
+      ]
+    });
+    if (p.isCancel(method)) return void 0;
+    if (method === "env") {
+      const envName = await p.text({
+        message: "Environment variable name",
+        initialValue: "DUCKDB_PATH",
+        validate(value) {
+          if (!value) return "Required";
+          const resolved = process.env[value];
+          if (!resolved) return `$${value} is not set`;
+          if (!existsSync3(resolved)) return `$${value} points to "${resolved}" which does not exist`;
+        }
+      });
+      if (p.isCancel(envName)) return void 0;
+      return { adapter: "duckdb", path: process.env[envName] };
+    } else {
+      const filePath = await p.text({
+        message: "Path to .duckdb file",
+        placeholder: "./warehouse.duckdb",
+        validate(value) {
+          if (!value) return "Required";
+          if (!existsSync3(value)) return `File not found: ${value}`;
+        }
+      });
+      if (p.isCancel(filePath)) return void 0;
+      return { adapter: "duckdb", path: path13.resolve(filePath) };
+    }
+  } else {
+    const method = await p.select({
+      message: "How do you connect?",
+      options: [
+        { value: "env", label: "Environment variable", hint: "e.g. DATABASE_URL" },
+        { value: "url", label: "Connection string", hint: "postgres://..." }
+      ]
+    });
+    if (p.isCancel(method)) return void 0;
+    if (method === "env") {
+      const envName = await p.text({
+        message: "Environment variable name",
+        initialValue: "DATABASE_URL",
+        validate(value) {
+          if (!value) return "Required";
+          const resolved = process.env[value];
+          if (!resolved) return `$${value} is not set`;
+        }
+      });
+      if (p.isCancel(envName)) return void 0;
+      return { adapter: "postgres", connection: process.env[envName] };
+    } else {
+      const url = await p.text({
+        message: "Connection string",
+        placeholder: "postgres://user:pass@host:5432/dbname",
+        validate(value) {
+          if (!value) return "Required";
+          if (!value.startsWith("postgres://") && !value.startsWith("postgresql://")) {
+            return "Must start with postgres:// or postgresql://";
+          }
+        }
+      });
+      if (p.isCancel(url)) return void 0;
+      return { adapter: "postgres", connection: url };
+    }
+  }
+}
+async function runConnectStep() {
+  const cwd = process.cwd();
+  let dsConfig;
+  const detected = autoDetectDb(cwd);
+  if (detected) {
+    p.log.info(`Detected: ${detected.label}`);
+    const useDetected = await p.confirm({ message: "Use this database?" });
+    if (p.isCancel(useDetected)) {
+      p.cancel("Setup cancelled.");
+      return void 0;
+    }
+    if (useDetected) {
+      dsConfig = detected.dsConfig;
+    } else {
+      const manual = await promptForConnection();
+      if (!manual) {
+        p.cancel("Setup cancelled.");
+        return void 0;
+      }
+      dsConfig = manual;
+    }
+  } else {
+    const manual = await promptForConnection();
+    if (!manual) {
+      p.cancel("Setup cancelled.");
+      return void 0;
+    }
+    dsConfig = manual;
+  }
+  const spin = p.spinner();
+  spin.start("Connecting to database...");
+  let adapter;
+  try {
+    adapter = await createAdapter5(dsConfig);
+    await adapter.connect();
+  } catch (err) {
+    spin.stop("Connection failed");
+    p.log.error(err.message);
+    p.cancel("Could not connect to database.");
+    return void 0;
+  }
+  const tables = await adapter.listTables();
+  const columns = {};
+  for (const table of tables) {
+    columns[table.name] = await adapter.listColumns(table.name);
+  }
+  const totalCols = Object.values(columns).reduce((sum, c) => sum + c.length, 0);
+  spin.stop(`Found ${tables.length} tables, ${totalCols} columns`);
+  const tableLines = tables.map((t) => `  ${t.name.padEnd(30)} ${t.row_count.toLocaleString()} rows`).join("\n");
+  p.note(tableLines, "Discovered Tables");
+  const defaultModel = path13.basename(cwd).replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+  const modelInput = await p.text({
+    message: "Model name",
+    initialValue: defaultModel,
+    validate(value) {
+      if (!value) return "Required";
+      if (!/^[a-z0-9-]+$/.test(value)) return "Use lowercase letters, numbers, and hyphens only";
+    }
+  });
+  if (p.isCancel(modelInput)) {
+    p.cancel("Setup cancelled.");
+    await adapter.disconnect();
+    return void 0;
+  }
+  const tierInput = await p.select({
+    message: "Target metadata tier",
+    options: [
+      { value: "bronze", label: "Bronze", hint: "Schema + ownership + grain" },
+      { value: "silver", label: "Silver", hint: "+ trust, lineage, glossary, refresh, sample values" },
+      { value: "gold", label: "Gold", hint: "+ semantic roles, rules, golden queries (needs curation)" }
+    ]
+  });
+  if (p.isCancel(tierInput)) {
+    p.cancel("Setup cancelled.");
+    await adapter.disconnect();
+    return void 0;
+  }
+  const configPath = path13.join(cwd, "contextkit.config.yaml");
+  let config;
+  try {
+    config = loadConfig10(cwd);
+  } catch {
+    config = { context_dir: "./context" };
+  }
+  if (!config.data_sources || Object.keys(config.data_sources).length === 0) {
+    const newConfig = {
+      context_dir: config.context_dir ?? "./context",
+      data_sources: { default: dsConfig }
+    };
+    writeFileSync5(configPath, yaml2.stringify(newConfig, { lineWidth: 120 }), "utf-8");
+    config = loadConfig10(cwd);
+  }
+  const contextDir = path13.resolve(cwd, config.context_dir ?? "./context");
+  return {
+    cwd,
+    contextDir,
+    dsConfig,
+    adapter,
+    tables,
+    columns,
+    modelName: modelInput,
+    targetTier: tierInput
+  };
+}
+
+// src/setup/steps/scaffold.ts
+import * as p3 from "@clack/prompts";
+import path14 from "path";
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync6, existsSync as existsSync4 } from "fs";
+import { scaffoldFromSchema as scaffoldFromSchema2, compile as compile10, computeTier as computeTier3, loadConfig as loadConfig11 } from "@runcontext/core";
+
+// src/setup/display.ts
+import * as p2 from "@clack/prompts";
+function displayTierScore(score) {
+  p2.note(formatTierScore(score), "Tier Scorecard");
+}
+
+// src/setup/steps/scaffold.ts
+async function runScaffoldStep(ctx) {
+  const shouldRun = await p3.confirm({
+    message: "Scaffold Bronze metadata from database schema?"
+  });
+  if (p3.isCancel(shouldRun) || !shouldRun) {
+    return { skipped: true, summary: "Skipped" };
+  }
+  const spin = p3.spinner();
+  spin.start("Scaffolding Bronze metadata...");
+  const result = scaffoldFromSchema2({
+    modelName: ctx.modelName,
+    dataSourceName: "default",
+    tables: ctx.tables,
+    columns: ctx.columns
+  });
+  for (const dir of ["models", "governance", "owners"]) {
+    const dirPath = path14.join(ctx.contextDir, dir);
+    if (!existsSync4(dirPath)) mkdirSync3(dirPath, { recursive: true });
+  }
+  const created = [];
+  const files = [
+    { rel: path14.join("models", result.files.osi), content: result.osiYaml },
+    { rel: path14.join("governance", result.files.governance), content: result.governanceYaml },
+    { rel: path14.join("owners", result.files.owner), content: result.ownerYaml }
+  ];
+  for (const f of files) {
+    const fullPath = path14.join(ctx.contextDir, f.rel);
+    writeFileSync6(fullPath, f.content, "utf-8");
+    created.push(f.rel);
+  }
+  const config = loadConfig11(ctx.cwd);
+  const { graph } = await compile10({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = graph;
+  ctx.tierScore = computeTier3(ctx.modelName, graph);
+  spin.stop(`Created ${created.length} files`);
+  const fileList = created.map((f) => `  ${f}`).join("\n");
+  p3.note(fileList, "Files Created");
+  displayTierScore(ctx.tierScore);
+  return { skipped: false, summary: `${created.length} files \u2192 ${ctx.tierScore.tier.toUpperCase()}` };
+}
+
+// src/setup/steps/enrich-silver.ts
+import * as p4 from "@clack/prompts";
+import path15 from "path";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync7, mkdirSync as mkdirSync4, existsSync as existsSync5, readdirSync as readdirSync2 } from "fs";
+import * as yaml3 from "yaml";
+import {
+  compile as compile11,
+  computeTier as computeTier4,
+  suggestEnrichments as suggestEnrichments2,
+  loadConfig as loadConfig12
+} from "@runcontext/core";
+function findFileRecursive2(dir, suffix) {
+  if (!existsSync5(dir)) return void 0;
+  const entries = readdirSync2(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path15.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const found = findFileRecursive2(fullPath, suffix);
+      if (found) return found;
+    } else if (entry.name.endsWith(suffix)) {
+      return fullPath;
+    }
+  }
+  return void 0;
+}
+async function runEnrichSilverStep(ctx) {
+  const config = loadConfig12(ctx.cwd);
+  const { graph } = await compile11({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = graph;
+  const tierScore = computeTier4(ctx.modelName, graph);
+  if (tierScore.silver.passed) {
+    p4.log.success("Already at Silver or above \u2014 skipping.");
+    ctx.tierScore = tierScore;
+    return { skipped: true, summary: "Already Silver" };
+  }
+  const model = graph.models.get(ctx.modelName);
+  if (!model) {
+    p4.log.error(`Model "${ctx.modelName}" not found in graph.`);
+    return { skipped: true, summary: "Model not found" };
+  }
+  const datasetNames = model.datasets.map((d) => d.name);
+  const suggestions = suggestEnrichments2("silver", tierScore, datasetNames);
+  const preview = [];
+  if (suggestions.governance?.trust) preview.push(`+ trust: ${suggestions.governance.trust}`);
+  if (suggestions.governance?.tags) preview.push(`+ tags: [${suggestions.governance.tags.join(", ")}]`);
+  if (suggestions.governance?.refreshAll) preview.push(`+ refresh: ${suggestions.governance.refreshAll} (all datasets)`);
+  if (suggestions.lineage) preview.push(`+ ${suggestions.lineage.upstream?.length ?? 0} lineage upstream source(s)`);
+  if (suggestions.glossaryTerms) preview.push(`+ ${suggestions.glossaryTerms.length} glossary term(s)`);
+  if (suggestions.needsSampleValues) preview.push("+ sample_values from live data");
+  if (preview.length > 0) {
+    p4.note(preview.join("\n"), "Silver Enrichments");
+  }
+  const shouldRun = await p4.confirm({
+    message: "Apply Silver enrichments?"
+  });
+  if (p4.isCancel(shouldRun) || !shouldRun) {
+    return { skipped: true, summary: "Skipped" };
+  }
+  const spin = p4.spinner();
+  spin.start("Enriching to Silver...");
+  const govFilePath = findFileRecursive2(ctx.contextDir, `${ctx.modelName}.governance.yaml`);
+  if (govFilePath) {
+    const govContent = readFileSync5(govFilePath, "utf-8");
+    const govDoc = yaml3.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.needsSampleValues) {
+      govDoc.fields = govDoc.fields ?? {};
+      try {
+        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 ctx.adapter.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 {
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    writeFileSync7(govFilePath, yaml3.stringify(govDoc, { lineWidth: 120 }), "utf-8");
+  }
+  if (suggestions.lineage) {
+    const lineageDir = path15.join(ctx.contextDir, "lineage");
+    if (!existsSync5(lineageDir)) mkdirSync4(lineageDir, { recursive: true });
+    const lineagePath = path15.join(lineageDir, `${ctx.modelName}.lineage.yaml`);
+    if (!existsSync5(lineagePath)) {
+      const lineageDoc = { model: ctx.modelName, upstream: suggestions.lineage.upstream };
+      writeFileSync7(lineagePath, yaml3.stringify(lineageDoc, { lineWidth: 120 }), "utf-8");
+    }
+  }
+  if (suggestions.glossaryTerms) {
+    const glossaryDir = path15.join(ctx.contextDir, "glossary");
+    if (!existsSync5(glossaryDir)) mkdirSync4(glossaryDir, { recursive: true });
+    for (const term of suggestions.glossaryTerms) {
+      const termPath = path15.join(glossaryDir, `${term.id}.term.yaml`);
+      if (!existsSync5(termPath)) {
+        writeFileSync7(termPath, yaml3.stringify(term, { lineWidth: 120 }), "utf-8");
+      }
+    }
+  }
+  const { graph: newGraph } = await compile11({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = newGraph;
+  ctx.tierScore = computeTier4(ctx.modelName, newGraph);
+  spin.stop("Applied Silver enrichments");
+  displayTierScore(ctx.tierScore);
+  return { skipped: false, summary: ctx.tierScore.tier.toUpperCase() };
+}
+
+// src/setup/steps/enrich-gold.ts
+import * as p5 from "@clack/prompts";
+import path16 from "path";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync8, mkdirSync as mkdirSync5, existsSync as existsSync6, readdirSync as readdirSync3 } from "fs";
+import * as yaml4 from "yaml";
+import {
+  compile as compile12,
+  computeTier as computeTier5,
+  suggestEnrichments as suggestEnrichments3,
+  inferSemanticRole as inferSemanticRole2,
+  inferAggregation as inferAggregation2,
+  loadConfig as loadConfig13
+} from "@runcontext/core";
+function findFileRecursive3(dir, suffix) {
+  if (!existsSync6(dir)) return void 0;
+  const entries = readdirSync3(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path16.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const found = findFileRecursive3(fullPath, suffix);
+      if (found) return found;
+    } else if (entry.name.endsWith(suffix)) {
+      return fullPath;
+    }
+  }
+  return void 0;
+}
+async function runEnrichGoldStep(ctx) {
+  const config = loadConfig13(ctx.cwd);
+  const { graph } = await compile12({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = graph;
+  const tierScore = computeTier5(ctx.modelName, graph);
+  if (tierScore.gold.passed) {
+    p5.log.success("Already at Gold \u2014 skipping.");
+    ctx.tierScore = tierScore;
+    return { skipped: true, summary: "Already Gold" };
+  }
+  const model = graph.models.get(ctx.modelName);
+  if (!model) {
+    p5.log.error(`Model "${ctx.modelName}" not found.`);
+    return { skipped: true, summary: "Model not found" };
+  }
+  const datasetNames = model.datasets.map((d) => d.name);
+  const suggestions = suggestEnrichments3("gold", tierScore, datasetNames);
+  const preview = [];
+  if (suggestions.needsSemanticRoles) preview.push("+ Infer semantic_role for all fields");
+  if (suggestions.needsRulesFile) preview.push("+ Generate rules file (golden queries, guardrails, hierarchies)");
+  if (suggestions.governance?.trust) preview.push(`+ trust: ${suggestions.governance.trust}`);
+  preview.push("+ Add version, business_context stubs to governance");
+  preview.push("+ Add ai_context placeholder to model");
+  preview.push("+ Infer relationships from column name patterns");
+  if (preview.length > 0) {
+    p5.note(preview.join("\n"), "Gold Enrichments");
+  }
+  p5.log.warning("Gold enrichments create TODO placeholders that need manual curation.");
+  const shouldRun = await p5.confirm({
+    message: "Apply Gold enrichments?"
+  });
+  if (p5.isCancel(shouldRun) || !shouldRun) {
+    return { skipped: true, summary: "Skipped" };
+  }
+  const spin = p5.spinner();
+  spin.start("Enriching to Gold...");
+  const govFilePath = findFileRecursive3(ctx.contextDir, `${ctx.modelName}.governance.yaml`);
+  if (govFilePath) {
+    const govContent = readFileSync6(govFilePath, "utf-8");
+    const govDoc = yaml4.parse(govContent) ?? {};
+    if (suggestions.governance?.trust) govDoc.trust = suggestions.governance.trust;
+    if (suggestions.needsSemanticRoles) {
+      govDoc.fields = govDoc.fields ?? {};
+      for (const ds of model.datasets) {
+        const tableName = ds.source?.split(".").pop() ?? ds.name;
+        let dbColumns = [];
+        try {
+          dbColumns = await ctx.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 = dbColumns.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 = inferSemanticRole2(field.name, dataType, isPK);
+          govDoc.fields[fieldKey].semantic_role = role;
+          if (role === "metric") {
+            govDoc.fields[fieldKey].default_aggregation = inferAggregation2(field.name);
+            govDoc.fields[fieldKey].additive = govDoc.fields[fieldKey].default_aggregation === "SUM";
+          }
+        }
+      }
+    }
+    if (!govDoc.version) {
+      govDoc.version = "0.1.0";
+    }
+    if (!govDoc.business_context || govDoc.business_context.length === 0) {
+      govDoc.business_context = [
+        { name: "TODO: Use Case Name", description: "TODO: Describe the analytical use case and business value." }
+      ];
+    }
+    writeFileSync8(govFilePath, yaml4.stringify(govDoc, { lineWidth: 120 }), "utf-8");
+  }
+  const modelFilePath = findFileRecursive3(ctx.contextDir, `${ctx.modelName}.osi.yaml`);
+  if (modelFilePath) {
+    const modelContent = readFileSync6(modelFilePath, "utf-8");
+    const modelDoc = yaml4.parse(modelContent) ?? {};
+    const semModels = modelDoc.semantic_model ?? [];
+    let changed = false;
+    for (const sm of semModels) {
+      if (sm.name !== ctx.modelName) continue;
+      if (!sm.ai_context) {
+        sm.ai_context = "TODO: Describe how an AI agent should use this model, common pitfalls, and important filters.";
+        changed = true;
+      }
+      if (!sm.relationships || sm.relationships.length === 0) {
+        const datasets = sm.datasets ?? [];
+        const dsNames = new Set(datasets.map((d) => d.name));
+        const inferred = [];
+        for (const ds of datasets) {
+          for (const field of ds.fields ?? []) {
+            const fname = field.name;
+            const idMatch = fname.match(/^(.+)_id$/);
+            if (idMatch && idMatch[1]) {
+              const targetBase = idMatch[1];
+              for (const targetDs of datasets) {
+                if (targetDs.name === ds.name) continue;
+                const targetName = targetDs.name;
+                if (targetName.includes(targetBase) || targetBase.includes(targetName)) {
+                  const targetHasField = (targetDs.fields ?? []).some((f) => f.name === fname);
+                  if (targetHasField) {
+                    const relName = `${ds.name}-to-${targetName}`;
+                    if (!inferred.some((r) => r.name === relName)) {
+                      inferred.push({
+                        name: relName,
+                        from: ds.name,
+                        to: targetName,
+                        from_columns: [fname],
+                        to_columns: [fname]
+                      });
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        if (inferred.length > 0) {
+          sm.relationships = inferred;
+          changed = true;
+        }
+      }
+    }
+    if (changed) {
+      writeFileSync8(modelFilePath, yaml4.stringify(modelDoc, { lineWidth: 120 }), "utf-8");
+    }
+  }
+  if (suggestions.needsRulesFile) {
+    const rulesDir = path16.join(ctx.contextDir, "rules");
+    if (!existsSync6(rulesDir)) mkdirSync5(rulesDir, { recursive: true });
+    const rulesPath = path16.join(rulesDir, `${ctx.modelName}.rules.yaml`);
+    if (!existsSync6(rulesPath)) {
+      const rulesDoc = {
+        model: ctx.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" }
+        ]
+      };
+      writeFileSync8(rulesPath, yaml4.stringify(rulesDoc, { lineWidth: 120 }), "utf-8");
+    }
+  }
+  const { graph: newGraph } = await compile12({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = newGraph;
+  ctx.tierScore = computeTier5(ctx.modelName, newGraph);
+  spin.stop("Applied Gold enrichments");
+  const todos = suggestions.needsRulesFile ? "\nThe rules file contains TODO placeholders \u2014 edit context/rules/ to complete Gold." : "";
+  if (todos) p5.log.warning(todos);
+  displayTierScore(ctx.tierScore);
+  return { skipped: false, summary: `${ctx.tierScore.tier.toUpperCase()} (may need curation)` };
+}
+
+// src/setup/steps/verify.ts
+import * as p6 from "@clack/prompts";
+import {
+  compile as compile13,
+  LintEngine as LintEngine5,
+  ALL_RULES as ALL_RULES6,
+  computeTier as computeTier6,
+  loadConfig as loadConfig14
+} from "@runcontext/core";
+async function runVerifyStep(ctx) {
+  const shouldRun = await p6.confirm({
+    message: "Verify metadata against live data?"
+  });
+  if (p6.isCancel(shouldRun) || !shouldRun) {
+    return { skipped: true, summary: "Skipped" };
+  }
+  const spin = p6.spinner();
+  spin.start("Verifying against database...");
+  const config = loadConfig14(ctx.cwd);
+  const { graph } = await compile13({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  graph.dataValidation = await collectDataValidation(ctx.adapter, graph);
+  const engine = new LintEngine5();
+  for (const rule of ALL_RULES6) {
+    if (rule.id.startsWith("data/")) engine.register(rule);
+  }
+  const dataDiags = engine.run(graph);
+  ctx.graph = graph;
+  ctx.tierScore = computeTier6(ctx.modelName, graph);
+  const errors = dataDiags.filter((d) => d.severity === "error").length;
+  const warnings = dataDiags.filter((d) => d.severity === "warning").length;
+  if (dataDiags.length === 0) {
+    spin.stop("All data validation checks passed");
+  } else {
+    spin.stop(`${errors} error(s), ${warnings} warning(s)`);
+    const details = dataDiags.map((d) => `  ${d.severity === "error" ? "x" : "!"} ${d.message}`).join("\n");
+    p6.note(details, "Data Validation Issues");
+  }
+  return {
+    skipped: false,
+    summary: dataDiags.length === 0 ? "Clean" : `${errors} errors, ${warnings} warnings`
+  };
+}
+
+// src/setup/steps/autofix.ts
+import * as p7 from "@clack/prompts";
+import fs4 from "fs";
+import {
+  compile as compile14,
+  LintEngine as LintEngine6,
+  ALL_RULES as ALL_RULES7,
+  applyFixes as applyFixes4,
+  computeTier as computeTier7,
+  loadConfig as loadConfig15
+} from "@runcontext/core";
+async function runAutofixStep(ctx) {
+  const config = loadConfig15(ctx.cwd);
+  const { graph } = await compile14({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  graph.dataValidation = await collectDataValidation(ctx.adapter, graph);
+  const engine = new LintEngine6();
+  for (const rule of ALL_RULES7) engine.register(rule);
+  const diagnostics = engine.run(graph);
+  const fixable = diagnostics.filter((d) => d.fixable);
+  if (fixable.length === 0) {
+    p7.log.success("No fixable issues found.");
+    ctx.graph = graph;
+    ctx.tierScore = computeTier7(ctx.modelName, graph);
+    return { skipped: true, summary: "Nothing to fix" };
+  }
+  const shouldRun = await p7.confirm({
+    message: `Auto-fix ${fixable.length} issue(s)?`
+  });
+  if (p7.isCancel(shouldRun) || !shouldRun) {
+    return { skipped: true, summary: "Skipped" };
+  }
+  const spin = p7.spinner();
+  spin.start("Fixing...");
+  const readFile = (filePath) => fs4.readFileSync(filePath, "utf-8");
+  const fixedFiles = applyFixes4(fixable, readFile);
+  for (const [file, content] of fixedFiles) {
+    fs4.writeFileSync(file, content, "utf-8");
+  }
+  const { graph: newGraph } = await compile14({ contextDir: ctx.contextDir, config, rootDir: ctx.cwd });
+  ctx.graph = newGraph;
+  ctx.tierScore = computeTier7(ctx.modelName, newGraph);
+  spin.stop(`Fixed ${fixable.length} issue(s) in ${fixedFiles.size} file(s)`);
+  displayTierScore(ctx.tierScore);
+  return { skipped: false, summary: `${fixable.length} issues fixed` };
+}
+
+// src/setup/steps/claude-md.ts
+import * as p8 from "@clack/prompts";
+import path17 from "path";
+import { existsSync as existsSync7, writeFileSync as writeFileSync9 } from "fs";
+function buildClaudeMd(ctx) {
+  const modelName = ctx.modelName;
+  const tier = ctx.tierScore?.tier?.toUpperCase() ?? "UNKNOWN";
+  const model = ctx.graph?.models.get(modelName);
+  const datasets = model?.datasets ?? [];
+  const datasetList = datasets.map((ds) => `- \`${ds.name}\` \u2014 ${ds.fields?.length ?? 0} fields`).join("\n");
+  const failingChecks = [];
+  if (ctx.tierScore) {
+    for (const check of ctx.tierScore.bronze.checks) {
+      if (!check.passed) failingChecks.push(`- ${check.id}: ${check.detail ?? check.label}`);
+    }
+    for (const check of ctx.tierScore.silver.checks) {
+      if (!check.passed) failingChecks.push(`- ${check.id}: ${check.detail ?? check.label}`);
+    }
+    for (const check of ctx.tierScore.gold.checks) {
+      if (!check.passed) failingChecks.push(`- ${check.id}: ${check.detail ?? check.label}`);
+    }
+  }
+  const failingSection = failingChecks.length > 0 ? `### Failing Checks
+
+${failingChecks.join("\n")}` : "All checks passing.";
+  return `# ContextKit Agent Instructions
+
+You have two MCP servers: **duckdb** (query data) and **contextkit** (query metadata).
+
+Model: **${modelName}** | Current Tier: **${tier}**
+
+## The Cardinal Rule: Never Fabricate Metadata
+
+**Every piece of metadata you write must be grounded in evidence from the actual data.**
+
+- NEVER invent owner names, emails, team names, or contact info
+- NEVER write a field description that is just the column name repeated
+- NEVER assign a semantic_role without first querying the column's actual values
+- NEVER mark a field as additive without understanding what summing it means
+- NEVER write lineage entries without knowing the actual data sources
+- NEVER write a business_context narrative you can't justify from the data
+- NEVER create a glossary definition that is just "Definition for X"
+
+If you don't know something, say so. Leave it as a TODO with a note about what you'd need to determine the answer. A honest TODO is infinitely better than fabricated metadata that looks plausible but is wrong.
+
+## On Session Start
+
+1. Run \`context_tier\` to check the current metadata tier (Bronze/Silver/Gold)
+2. Report the current tier and list failing checks
+3. Ask the user what they'd like to work on \u2014 don't start changing files unprompted
+
+## When Asked to Reach Gold
+
+Work through ALL failing Gold checks iteratively until \`context tier\` reports Gold:
+
+1. Run \`context_tier\` and collect every failing check
+2. For each failing check, query the database to gather evidence, then fix the metadata
+3. Run \`context_tier\` again
+4. If checks still fail, go back to step 2
+5. **Do NOT stop until every Gold check passes** or you hit something that genuinely requires human input (like real owner contact info)
+6. For checks you cannot fix (e.g., owner email), leave a clear TODO explaining what a human needs to provide
+
+You must iterate \u2014 a single pass is never enough. Each \`context tier\` run may reveal new failures after earlier ones are fixed.
+
+## How to Curate Metadata (the right way)
+
+### Before writing ANY metadata, query the database first
+
+For every field you're about to describe or classify:
+
+\`\`\`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;
+
+-- 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
+\`\`\`
+
+### Semantic Role Decision Tree
+
+Query the column first, then apply this logic:
+
+1. **Is it a primary key or foreign key?** \u2192 \`identifier\`
+2. **Is it a date or timestamp?** \u2192 \`date\`
+3. **Is it numeric AND does aggregation make business sense?**
+   - Does SUM make sense? (counts, amounts, quantities) \u2192 \`metric\`, \`additive: true\`
+   - Does only AVG/MIN/MAX make sense? (rates, percentages, scores, ratings) \u2192 \`metric\`, \`additive: false\`
+4. **Everything else** \u2192 \`dimension\`
+
+Common mistakes to avoid:
+- \`stars\` (ratings) \u2192 metric with AVG, NOT additive (summing star ratings is meaningless)
+- \`_per_10k_people\` (rates) \u2192 metric with AVG, NOT additive
+- \`_score\` (composite scores) \u2192 metric with AVG, NOT additive
+- \`useful/funny/cool\` (vote counts) \u2192 metric with SUM, additive
+- \`_count\` fields \u2192 metric with SUM, additive (usually)
+
+### Field Descriptions
+
+Write descriptions that help someone who has never seen this database understand what the column contains. Include:
+- What the value represents
+- Units or scale (if applicable)
+- Where the data comes from (if known)
+- Any known quirks or caveats
+
+Bad: \`description: total_population\`
+Good: \`description: Total resident population of the census tract from American Community Survey 5-year estimates\`
+
+Bad: \`description: stars\`
+Good: \`description: Average Yelp star rating (1.0-5.0 scale) based on all reviews for this business\`
+
+### Lineage
+
+Upstream sources are the EXTERNAL systems that feed data into this warehouse. They are NOT the tables in the warehouse itself.
+
+Ask yourself: "Where did this data originally come from before it was loaded here?"
+
+Bad lineage:
+\`\`\`yaml
+upstream:
+  - source: yelp_business    # This is a table IN the warehouse, not an upstream source
+    type: pipeline
+\`\`\`
+
+Good lineage:
+\`\`\`yaml
+upstream:
+  - source: yelp-academic-dataset
+    type: file
+    notes: Yelp Open Dataset (academic use), loaded via CSV import
+\`\`\`
+
+### Owner Files
+
+Do NOT create fake owner identities. If the real owner is unknown:
+- Keep the existing owner file as-is
+- Note in the file that contact info needs to be filled in by a real person
+- NEVER invent email addresses like \`analytics@example.com\`
+
+### Business Context
+
+Write business_context entries that describe real analytical use cases you can verify from the data. Query the data to understand what questions it can answer before writing narratives.
+
+### Golden Queries
+
+Every golden query MUST be tested against the actual database before you write it. Run the SQL, verify it returns sensible results, then document it.
+
+### Data Quality
+
+When you discover data quality issues (null values, broken joins, missing data), FLAG THEM \u2014 don't hide them. Add notes in governance or report them to the user.
+
+## This Project
+
+### Datasets
+
+${datasetList || "(none detected)"}
+
+${failingSection}
+
+## MCP Tools
+
+| Tool | Parameters | What it does |
+|------|-----------|-------------|
+| \`context_search\` | \`query\` | Find models, datasets, fields, terms by keyword |
+| \`context_explain\` | \`model\` | Full model details \u2014 governance, rules, lineage, tier |
+| \`context_validate\` | \u2014 | Run linter, get errors and warnings |
+| \`context_tier\` | \`model\` | Tier scorecard with all check results |
+| \`context_golden_query\` | \`question\` | Find pre-validated SQL for a question |
+| \`context_guardrails\` | \`tables[]\` | Get required WHERE clauses for tables |
+
+## Tier Checks Quick Reference
+
+**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
+
+## YAML Formats
+
+**Governance** (\`context/governance/*.governance.yaml\`):
+\`\`\`yaml
+model: my-model
+owner: team-name
+version: "1.0.0"
+trust: endorsed
+security: internal
+tags: [domain-tag-1, domain-tag-2]
+business_context:
+  - name: Use Case Name
+    description: What analytical question this data answers and for whom.
+datasets:
+  my_table:
+    grain: "One row per [entity] identified by [key]"
+    table_type: fact    # fact | dimension | event | view
+    refresh: daily
+fields:
+  dataset.field:
+    semantic_role: metric        # metric | dimension | identifier | date
+    default_aggregation: SUM     # SUM | AVG | COUNT | COUNT_DISTINCT | MIN | MAX
+    additive: true               # can this metric be summed across dimensions?
+    default_filter: "is_open = 1"
+    sample_values: ["val1", "val2"]
+\`\`\`
+
+**Rules** (\`context/rules/*.rules.yaml\`):
+\`\`\`yaml
+model: my-model
+golden_queries:
+  - question: What are the top items by count?
+    sql: SELECT name, count FROM my_table ORDER BY count DESC LIMIT 10
+    intent: Identify top performers by volume
+    caveats: Filters to active records only
+business_rules:
+  - name: valid-ratings
+    definition: All ratings must be between 1 and 5
+guardrail_filters:
+  - name: active-only
+    filter: "status = 'active'"
+    reason: Exclude inactive records from analytics
+    tables: [my_table]
+hierarchies:
+  - name: geography
+    levels: [state, city, postal_code]
+    dataset: my_table
+\`\`\`
+
+## CLI Commands
+
+\`\`\`bash
+context tier                  # Check scorecard
+context verify --db <path>    # Validate against live data
+context fix --db <path>       # Auto-fix data warnings
+context setup                 # Interactive setup wizard
+context dev                   # Watch mode for live editing
+\`\`\`
+`;
+}
+async function runClaudeMdStep(ctx) {
+  const instructionsPath = path17.join(ctx.contextDir, "AGENT_INSTRUCTIONS.md");
+  if (existsSync7(instructionsPath)) {
+    const shouldOverwrite = await p8.confirm({
+      message: "context/AGENT_INSTRUCTIONS.md already exists. Overwrite with updated instructions?"
+    });
+    if (p8.isCancel(shouldOverwrite) || !shouldOverwrite) {
+      return { skipped: true, summary: "context/AGENT_INSTRUCTIONS.md already exists, kept existing" };
+    }
+  }
+  const content = buildClaudeMd(ctx);
+  writeFileSync9(instructionsPath, content, "utf-8");
+  p8.log.success("Generated context/AGENT_INSTRUCTIONS.md with agent curation instructions");
+  return { skipped: false, summary: "Generated context/AGENT_INSTRUCTIONS.md" };
+}
+
+// src/commands/setup.ts
+var setupCommand = new Command15("setup").description("Interactive wizard to scaffold and enrich metadata from a database").action(async () => {
+  p9.intro(chalk16.bgCyan(chalk16.black(" ContextKit Setup ")));
+  const ctx = await runConnectStep();
+  if (!ctx) return;
+  try {
+    const steps = [
+      { name: "Scaffold Bronze", fn: runScaffoldStep }
+    ];
+    if (ctx.targetTier === "silver" || ctx.targetTier === "gold") {
+      steps.push({ name: "Enrich to Silver", fn: runEnrichSilverStep });
+    }
+    if (ctx.targetTier === "gold") {
+      steps.push({ name: "Enrich to Gold", fn: runEnrichGoldStep });
+    }
+    steps.push(
+      { name: "Verify data", fn: runVerifyStep },
+      { name: "Auto-fix", fn: runAutofixStep },
+      { name: "Generate agent instructions", fn: runClaudeMdStep }
+    );
+    const results = [];
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      p9.log.step(`${chalk16.dim(`[${i + 1}/${steps.length}]`)} ${step.name}`);
+      const result = await step.fn(ctx);
+      results.push({ name: step.name, summary: result.summary });
+    }
+    const summaryLines = results.map((r) => `  ${chalk16.green("+")} ${r.name}: ${r.summary}`).join("\n");
+    p9.note(summaryLines, "Summary");
+    if (ctx.tierScore) {
+      displayTierScore(ctx.tierScore);
+    }
+    const currentTier = ctx.tierScore?.tier ?? "none";
+    const reachedTarget = ctx.targetTier === "bronze" && ["bronze", "silver", "gold"].includes(currentTier) || ctx.targetTier === "silver" && ["silver", "gold"].includes(currentTier) || ctx.targetTier === "gold" && currentTier === "gold";
+    if (reachedTarget) {
+      p9.outro(`Done! You're at ${chalk16.bold(currentTier.toUpperCase())}. Run ${chalk16.cyan("context tier")} anytime to check.`);
+    } else if (ctx.targetTier === "gold" && currentTier !== "gold") {
+      const nextSteps = [
+        `Your metadata is at ${chalk16.bold(currentTier.toUpperCase())} \u2014 Gold needs curation.`,
+        "",
+        `${chalk16.bold("To reach Gold, tell your AI assistant:")}`,
+        "",
+        `  "Read ${chalk16.cyan("context/AGENT_INSTRUCTIONS.md")} for curation guidelines.`,
+        `   Run ${chalk16.cyan("context tier")} and fix every failing Gold check.`,
+        `   Query the database before writing any metadata.`,
+        `   Keep iterating until ${chalk16.cyan("context tier")} reports Gold."`
+      ];
+      p9.note(nextSteps.join("\n"), "Next Steps");
+      p9.outro(`Run ${chalk16.cyan("context dev")} to watch for changes as you edit.`);
+    } else {
+      p9.outro(`Run ${chalk16.cyan("context tier")} to check your scorecard.`);
+    }
+  } finally {
+    try {
+      await ctx.adapter.disconnect();
+    } catch {
+    }
+  }
+});
+
 // src/index.ts
-var program = new Command15();
+var program = new Command16();
 program.name("context").description("ContextKit \u2014 AI-ready metadata governance over OSI").version("0.3.1");
 program.addCommand(lintCommand);
 program.addCommand(buildCommand);
@@ -1579,5 +2599,6 @@ program.addCommand(introspectCommand);
 program.addCommand(verifyCommand);
 program.addCommand(enrichCommand);
 program.addCommand(rulesCommand);
+program.addCommand(setupCommand);
 program.parse();
 //# sourceMappingURL=index.js.map