@runcontext/cli 0.4.2 → 0.4.4

package/dist/index.js

@@ -141,7 +141,7 @@ function formatSarif(diagnostics) {
         tool: {
           driver: {
             name: "ContextKit",
-            version: "0.4.2",
+            version: "0.4.4",
             informationUri: "https://github.com/erickittelson/ContextKit",
             rules: Array.from(ruleMap.values())
           }
@@ -1088,7 +1088,7 @@ var devCommand = new Command8("dev").description("Watch mode \u2014 re-run lint
     await runLint(contextDir, fix);
     let recompileAndBroadcast;
     if (opts.studio) {
-      const { startStudioServer } = await import("./server-DEKWPP3H.js");
+      const { startStudioServer } = await import("./server-MQUOYUAX.js");
       const studioPort = parseInt(opts.port, 10);
       const { server: _studioServer, recompileAndBroadcast: rab } = await startStudioServer({
         contextDir,
@@ -1278,19 +1278,19 @@ 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) => {
+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").option("--astro", "Use Astro-based site builder (default: EJS legacy)").action(async (opts) => {
   try {
     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;
+    let builder;
     try {
       const siteModule = await import("@runcontext/site");
-      buildSite = siteModule.buildSite;
+      builder = opts.astro ? siteModule.buildAstroSite : siteModule.buildSite;
     } catch {
     }
-    if (!buildSite) {
+    if (!builder) {
       console.log(
         chalk11.yellow(
           "Site generator is not yet available. Install @runcontext/site to enable this command."
@@ -1299,8 +1299,8 @@ var siteCommand = new Command10("site").description("Build a static documentatio
       process.exit(0);
     }
     const outputDir = opts.outputDir ? path10.resolve(opts.outputDir) : path10.resolve(config.site?.base_path ?? "site");
-    await buildSite(manifest, config, outputDir);
-    console.log(chalk11.green(`Site built to ${outputDir}`));
+    await builder(manifest, config, outputDir);
+    console.log(chalk11.green(`Site built to ${outputDir}${opts.astro ? " (Astro)" : ""}`));
   } catch (err) {
     console.error(formatError(err.message));
     process.exit(1);
@@ -3324,59 +3324,68 @@ CREATE TABLE / CREATE VIEW / CREATE INDEX
 
 If a query might be expensive and you're not sure, **ask the user first**. "This table looks large \u2014 is it OK if I run a COUNT(*)?" is always the right call.
 
-## Reference Documents
+## Mandatory Task Checklist
 
-Check \`context/reference/\` for any files the user has provided \u2014 data dictionaries, Confluence exports, ERDs, business glossaries, dashboard docs, etc. **Read these first** before querying the database. They contain domain knowledge that will dramatically improve your metadata quality.
+**You MUST complete every task in order. Do NOT skip any task. Do NOT proceed to the next task until the current one is done.**
 
-If the folder is empty, ask the user: "Do you have any existing documentation about this data? Data dictionaries, wiki pages, spreadsheets? Drop them in context/reference/ and I'll use them."
+This is the full workflow for building a semantic layer. Check off each task as you complete it.
 
-## On Session Start
+### Phase 1: Discovery (BEFORE touching any YAML)
 
-1. Check \`context/reference/\` for any reference documents \u2014 read them if present
-2. Run \`context tier\` to check the current metadata tier (Bronze/Silver/Gold)
-3. Report the current tier and summarize failing checks
-4. Ask the user what they'd like to focus on \u2014 don't start changing files unprompted
-5. If the user says "get me to Gold" or "build my semantic layer," follow the iterative workflow below
+- [ ] **Task 1: Ask about the project goal.** Ask the user: "What is this data for? What questions do you want to answer with it? Who will be using it?" Do NOT proceed until the user answers.
 
-## The Iterative Workflow
+- [ ] **Task 2: Ask for reference documents.** Tell the user: "Do you have any existing documentation about this data? Data dictionaries, wiki pages, ERDs, spreadsheets, Confluence exports, dashboard screenshots? Drop them in \`context/reference/\` and I'll use them to write much better metadata." Check \`context/reference/\` for any files already there. Read them if present.
 
-Building a semantic layer is a **conversation**. You and the user go back and forth \u2014 you query the data, propose metadata, ask questions, and iterate. Here's the loop:
+- [ ] **Task 3: Ask about ownership.** Ask: "Who owns this data? What team maintains it? What's the best contact email?" Do NOT invent owner info.
 
-\`\`\`
-                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
-                    \u2502   context tier           \u2502
-                    \u2502   (check failing checks) \u2502
-                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
-                               \u2502
-                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
-                    \u2502  Pick highest-impact     \u2502
-                    \u2502  failing check           \u2502
-                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
-                               \u2502
-                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
-                    \u2502  Query the database      \u2502
-                    \u2502  to gather evidence      \u2502
-                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
-                               \u2502
-                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
-                    \u2502  Need user input?        \u2502\u2500\u2500\u2500\u2500 YES \u2500\u2500\u2192 Ask the user
-                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518              (then continue)
-                               \u2502 NO
-                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
-                    \u2502  Edit YAML metadata      \u2502
-                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
-                               \u2502
-                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
-                    \u2502  context lint            \u2502
-                    \u2502  context tier            \u2502
-                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
-                               \u2502
-                    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25BC\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
-                    \u2502  All Gold checks pass?   \u2502\u2500\u2500\u2500\u2500 NO \u2500\u2500\u2192 Loop back
-                    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
-                               \u2502 YES
-                            \u2713 DONE
-\`\`\`
+- [ ] **Task 4: Ask about data sources.** Ask: "Where does this data come from originally? What upstream systems feed into this database? (e.g., Salesforce, Stripe, internal APIs, CSV imports)"
+
+- [ ] **Task 5: Run \`context tier\`.** Check the current tier score and report it to the user. Summarize which checks are failing.
+
+### Phase 2: Guided Curation (the conversation)
+
+- [ ] **Task 6: Walk through key fields WITH the user.** For each dataset, sample the data (with LIMIT), then ask the user about fields that are ambiguous:
+  - "I see a column called \`stars\` with values 1.0-5.0 \u2014 is this a rating that should be averaged, or something else?"
+  - "Should \`revenue\` be summed or averaged? Is it additive across dimensions?"
+  - "What does \`status\` mean in your business? What are the valid values?"
+  - Do NOT silently assign semantic roles without checking ambiguous cases.
+
+- [ ] **Task 7: Ask about metrics the user cares about.** Ask: "What are the key metrics you track? What KPIs matter most to your team? (e.g., revenue, churn rate, conversion, average order value)" \u2014 then build metrics around their answers, not just what you find in the data.
+
+- [ ] **Task 8: Ask about business rules and filters.** Ask: "Are there any filters that should always be applied? For example: only active records, exclude test data, only completed orders?"
+
+- [ ] **Task 9: Ask about glossary terms.** Ask: "What business terms do people in your org use that a new analyst might not understand? (e.g., 'MRR', 'churn', 'qualified lead')"
+
+- [ ] **Task 10: Curate to Gold.** Now iterate through failing checks:
+  1. Run \`context tier\` to see what's failing
+  2. Fix the highest-impact failing check
+  3. If you need user input to fix a check, ASK \u2014 don't guess
+  4. Run \`context tier\` again
+  5. Repeat until Gold or until you hit something that genuinely requires human input
+
+### Phase 3: Deliver
+
+- [ ] **Task 11: Build the AI Blueprint.** Run \`context blueprint ${modelName}\` to export the Gold-tier data product as a portable YAML file. Show the user where it was saved.
+
+- [ ] **Task 12: Serve the metadata site.** Run \`context dev --studio\` to start the interactive metadata browser. Tell the user: "Your metadata catalog is now live \u2014 open the link above to browse your semantic layer in the browser."
+
+- [ ] **Task 13: Summary.** Give the user a final summary:
+  - Current tier score
+  - Number of datasets, fields, metrics, glossary terms, golden queries
+  - What's complete and what still needs human input
+  - Next steps they can take
+
+## Key Principles
+
+### This is a CONVERSATION, not a batch job
+
+The single most important thing: **ask questions and wait for answers.** The user knows the business. You know the data. Together you build the semantic layer. If you silently curate everything without asking, the metadata will be plausible-looking but wrong.
+
+**Ask one question at a time.** Don't batch 10 questions into one message. Ask, wait, incorporate the answer, then ask the next question.
+
+### Reference Documents
+
+Check \`context/reference/\` for any files the user has provided \u2014 data dictionaries, Confluence exports, ERDs, business glossaries, dashboard docs, etc. **Read these first** before querying the database. They contain domain knowledge that will dramatically improve your metadata quality.
 
 ### What to Ask the User About
 
@@ -3410,17 +3419,26 @@ context serve --stdio           # Start MCP server (for Claude, Cursor, etc.)
 context dev --studio            # Open visual editor in browser
 \`\`\`
 
-### Do NOT Stop Until Gold
+### Do NOT Stop Until Gold (Task 10)
 
 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
-6. For checks you cannot fix, ask the user or leave a clear TODO explaining what's needed
+3. **If you need user input to fix a check \u2014 ASK.** Do not guess.
+4. Run \`context tier\` again
+5. If checks still fail, go back to step 2
+6. **Do NOT stop until every Gold check passes** or you hit something that genuinely requires human input
+7. For checks you cannot fix, ask the user or leave a clear TODO explaining what's needed
 
 You must iterate \u2014 a single pass is never enough. Each \`context tier\` run may reveal new failures after earlier ones are fixed.
 
+### After Gold: Deliver (Tasks 11-13)
+
+**Do NOT skip these.** Once you reach Gold (or as close as possible):
+
+1. Run \`context blueprint ${modelName}\` \u2014 export the AI Blueprint
+2. Run \`context dev --studio\` \u2014 start the metadata browser for the user
+3. Give the user a summary of what was built and what needs human input
+
 ## How to Curate Metadata (the right way)
 
 ### Before writing ANY metadata, query the database first
@@ -4238,7 +4256,7 @@ var newCommand = new Command17("new").description("Scaffold a new data product i
 
 // src/index.ts
 var program = new Command18();
-program.name("context").description("ContextKit \u2014 AI-ready metadata governance over OSI").version("0.4.2");
+program.name("context").description("ContextKit \u2014 AI-ready metadata governance over OSI").version("0.4.4");
 program.addCommand(lintCommand);
 program.addCommand(buildCommand);
 program.addCommand(tierCommand);