@starklab/stark-mcp 0.2.0 → 0.3.0

package/src/cli.js

@@ -9,18 +9,22 @@ import {
   getComponentProps,
   buildManifest,
   ejectComponent,
+  whispererContext,
 } from './data.js';
 import { resolveReferences } from './adopt/referenceResolver.js';
 import { resolveWrappers } from './adopt/wrapperResolver.js';
 import { resolveTokenAliases } from './adopt/tokenAliasResolver.js';
 import { resolveTailwindTokens } from './adopt/tailwindResolver.js';
 import { resolvePropApi } from './adopt/propApiResolver.js';
+import { buildScanRollup } from './adopt/scanRollup.js';
+import { attachFindingSnippets } from './adopt/findingSnippet.js';
 import { resolveUsageRules } from './adopt/usageRulesResolver.js';
 import { resolveOpportunities } from './adopt/opportunityResolver.js';
 import { resolveRnTokenAliases } from './adopt/rnTokenAliasResolver.js';
 import { resolveRnTailwindTokens } from './adopt/rnTailwindResolver.js';
 import { discoverTargets, workspacePackageMap } from './adopt/targetDiscovery.js';
 import { verifyVecnaLayout } from './adopt/vecnaVerifier.js';
+import { gateAdoptResult, GATE_SEVERITIES } from './adopt/adoptGate.js';
 import { resolveForeignDiscovery } from './adopt/foreignDiscoveryResolver.js';
 import { resolvePropSchema } from './adopt/foreignPropSchemaResolver.js';
 import { scoreForeignAdoption } from './adopt/foreignScoringResolver.js';
@@ -29,6 +33,8 @@ import { detectForeignSystems } from './adopt/installedSystemAutoDetector.js';
 import { scanInstalledSystem } from './adopt/installedSystemScan.js';
 import { reportForeignScan } from './adopt/foreignScanReport.js';
 import { reportAdoptScan } from './adopt/adoptScanReport.js';
+import { reportPrCheck } from './adopt/prCheckReport.js';
+import { runA11yPass } from './adopt/a11yPass.js';
 
 function print(value) {
   console.log(JSON.stringify(value, null, 2));
@@ -86,10 +92,77 @@ function flagValue(args, name, fallback) {
   return arg ? arg.slice(prefix.length) : fallback;
 }
 
+/** Every occurrence of a repeatable flag, each also split on commas, so
+ *  "--a11y-url=a --a11y-url=b" and "--a11y-url=a,b" mean the same thing. A
+ *  list of pages is the one input here a consumer plausibly writes both ways,
+ *  and silently keeping only the first would score a subset of what they
+ *  asked for while labelling it as the whole. */
+function flagValues(args, name) {
+  const prefix = `--${name}=`;
+  return args
+    .filter(a => a.startsWith(prefix))
+    .flatMap(a => a.slice(prefix.length).split(','))
+    .map(s => s.trim())
+    .filter(Boolean);
+}
+
+/** Gate flags, shared by "adopt --gate" and the standalone "gate" command so
+ *  a verdict means the same thing however it was produced. Throws on an
+ *  unusable value rather than silently falling back to the default — a CI
+ *  that asked for --fail-on=warn and got critical would be told it passed
+ *  under a threshold it never set. */
+function gateOptions(args) {
+  const failOn = flagValue(args, 'fail-on', 'critical');
+  if (!GATE_SEVERITIES.includes(failOn)) {
+    throw new Error(`--fail-on must be one of: ${GATE_SEVERITIES.join(', ')} (got "${failOn}").`);
+  }
+  const raw = flagValue(args, 'min-components', undefined);
+  let minComponentsUsed = null;
+  if (raw !== undefined) {
+    minComponentsUsed = Number(raw);
+    if (!Number.isInteger(minComponentsUsed) || minComponentsUsed < 0) {
+      throw new Error(`--min-components must be a non-negative integer (got "${raw}").`);
+    }
+  }
+  return { failOn, minComponentsUsed };
+}
+
+/** A gate that cannot run must never report PASS — that is the one failure
+ *  mode a gate cannot have. So a crash (or a bad flag on "adopt --gate",
+ *  where the scan itself still has output worth printing) becomes a FAIL
+ *  verdict carrying the error, instead of propagating out and taking the
+ *  scan's stdout with it. This is the opposite of the reporting block below,
+ *  which is allowed to fail silently precisely because it is not a judgment. */
+function runGate(adoptResult, args) {
+  try {
+    return gateAdoptResult(adoptResult, gateOptions(args));
+  } catch (err) {
+    return { verdict: 'FAIL', error: `The gate could not run: ${err.message}`, summary: null, checks: [] };
+  }
+}
+
+/** stdout stays a single JSON document; the human-readable verdict and the
+ *  exit code go to stderr and process.exitCode, same split as --report's. */
+function announceGate(gate) {
+  if (gate.verdict === 'FAIL') {
+    const failed = (gate.checks ?? []).filter(c => c.status === 'fail');
+    const detail = gate.error
+      ? gate.error
+      : failed.map(c => `${c.id} (${c.evidenceTotal} finding${c.evidenceTotal === 1 ? '' : 's'})`).join(', ');
+    console.error(`Gate: FAIL — ${detail}`);
+    process.exitCode = 1;
+    return;
+  }
+  const s = gate.summary;
+  console.error(
+    `Gate: PASS — ${s.passed}/${s.checks} checks passed, ${s.notApplicable} not applicable, ${s.noEvidence} with no evidence to judge.`
+  );
+}
+
 // Shared by the single-target `adopt` path and the `--all-targets` loop —
 // `workspacePackages` is only non-empty in the latter, where it enables
 // wrapperResolver.js's cross-workspace resolution (ADOPTION_APP_PLAN.md §3e).
-function runAdopt(root, platform, ignore, workspacePackages) {
+function runAdopt(root, platform, ignore, workspacePackages, { snippets = true } = {}) {
   const references = resolveReferences(root, { platform, ignore });
   const wrappers = resolveWrappers(root, { platform, ignore, workspacePackages });
   // CSS custom properties and Tailwind utility classes have no RN
@@ -118,7 +191,7 @@ function runAdopt(root, platform, ignore, workspacePackages) {
   const rnTokenAliases = platform === 'native' ? resolveRnTokenAliases(root, { platform, ignore }) : null;
   // NativeWind is the RN analog of web Tailwind — same platform split.
   const rnTailwind = platform === 'native' ? resolveRnTailwindTokens(root, { platform, ignore }) : null;
-  return {
+  const result = {
     ...references,
     wrappers: wrappers.wrappers,
     byComponent: wrappers.byComponent,
@@ -134,6 +207,18 @@ function runAdopt(root, platform, ignore, workspacePackages) {
     rnTokenAliases,
     rnTailwind,
   };
+  // Folded here, not in adoptScanReport.js, because its inputs are exactly the
+  // per-site enumerations `stripAdoptDetail`'s DROPPED_KEYS removes on the way
+  // out — computing it any later would mean computing it from data that is
+  // already gone (scanRollup.js). It is derived, so it also belongs in the
+  // printed document: `stark-cli gate <adopt.json>` and a human reading stdout
+  // both see the same rollup Dominion stores.
+  const reported = { ...result, rollup: buildScanRollup(result) };
+  // Last, and after the rollup: this is the only step that reads the
+  // consumer's source *text* rather than its structure, so it is the only one
+  // that can be turned off (--no-snippets) without changing any other number
+  // in the document. See findingSnippet.js for the bounds it works under.
+  return snippets ? attachFindingSnippets(reported, { root }) : reported;
 }
 
 const HELP = `stark-cli — query the Stark design system catalog from the terminal
@@ -144,13 +229,18 @@ Usage:
   stark-cli props <Component> [--platform=web|native] [--tokens]
   stark-cli manifest
   stark-cli eject <Component> [--platform=web|native] [--out=<dir>] [--force]
-  stark-cli adopt [path] [--platform=web|native] [--ignore=<glob>,<glob>,...] [--all-targets]
+  stark-cli adopt [path] [--platform=web|native] [--ignore=<glob>,<glob>,...] [--all-targets] [--no-snippets]
+                                                         [--a11y-url=<url>[,<url>...] [--a11y-browser-path=<bin>]]
                                                          [--report=<url> --target-dir=<dir> [--commit=<sha>]]
+                                                         [--pr-check=<url> --target-dir=<dir> [--commit=<sha>]]
+                                                         [--gate [--fail-on=critical|warning|info] [--min-components=<n>]]
   stark-cli targets [path]
+  stark-cli gate <path-to-adopt.json> [--fail-on=critical|warning|info] [--min-components=<n>]
   stark-cli verify-vecna <path-to-layout.json> [--out=<dir>]
   stark-cli scan-foreign <system-id-or-npm-package|auto> [path] [--platform=web|native] [--allow-network] [--ignore=<glob>,<glob>,...]
                                                          [--report=<url> --target-dir=<dir> [--commit=<sha>]]
   stark-cli scan-foreign                                 List the tested systems (pass one's id, or any raw npm package name)
+  stark-cli whisper "<question>" [--context=<prior turn>]... [--json]
 
 Options:
   --platform=<web|native>   Target platform for "props", "eject", and "adopt" (default: web)
@@ -160,6 +250,17 @@ Options:
   --ignore=<globs>          Extra comma-separated glob patterns to exclude from "adopt"'s scan
   --all-targets             Discover every workspace target under [path] and run "adopt" on
                              each in-scope one, instead of treating [path] as a single target
+  --gate                    Judge an "adopt" scan and print a PASS/FAIL verdict with evidence
+  --fail-on=<severity>      Lowest severity that fails the gate (default: critical)
+  --min-components=<n>      Opt-in CI floor: fail the gate below n referenced catalog components
+  --a11y-url=<url>          A page of your running app to render and check with axe. Repeatable,
+                             and comma-separated lists are accepted. Opt-in; without it an "adopt"
+                             score measures components and tokens only
+  --a11y-browser-path=<bin> Chromium executable for the a11y pass (or STARK_A11Y_BROWSER_PATH),
+                             needed only where "playwright-core" is installed without a browser
+  --context=<text>          A prior turn of the conversation, for "whisper"; repeatable, newest first
+  --json                    Print "whisper"'s output as JSON ({ systemPrompt, grounding, components,
+                             named, tokens }) instead of the ready-to-use system prompt text
 
 "eject --platform=native" copies from @starklab/stk-react-native
 instead of @starklab/stk-components.
@@ -357,11 +458,60 @@ adoption score gets into the dashboard. It takes the same
 reduced projection: every per-site enumeration ("sites", "usages",
 "properties", "checks") is dropped, since the tracker reads counts and the
 three-number reports, never the enumeration behind them. Findings are kept.
+
+Each finding that carries a file and a line also carries a "snippet": a few
+lines of the real source around it ("before"), and, only where the token
+build proves a single replacement, the same lines with the fix applied
+("after"). This is the one part of a scan that ships the customer's own
+code, so it is bounded (2 lines of context, 200 characters per line, 200
+snippets per scan) and "--no-snippets" turns it off entirely, leaving every
+other number in the document unchanged.
 "--report" is not supported together with "--all-targets" — a reported scan
 belongs to exactly one tracker target, so run one "adopt <dir>
 --report --target-dir=<dir>" per target instead of reporting a whole
 discovery sweep under a single dir.
 
+"adopt --pr-check=<url>" is the pull-request half of the same wire, and
+posts to a different endpoint (/api/pr-check) for a different purpose.
+"--report" accumulates history: every scan is stored, and a falling score is
+information rather than a failure. "--pr-check" judges one commit: the
+tracker diffs this scan's findings against the ones already open on the
+target, and posts a real GitHub Check Run on "--commit" — red when the pull
+request introduces a critical finding, neutral when it introduces a
+non-critical one, green when it introduces none. Both flags take the same
+"--target-dir=<dir>" (required), "--commit=<sha>", STARK_DOMINION_TOKEN /
+"--token=<secret>" and never-fail-the-build behaviour, both may be passed in
+the same run, and neither is supported with "--all-targets" for the same
+reason.
+
+What is sent is only what the check can act on: a "{rule, location,
+severity}" triple per finding, where "location" is the target-relative
+"file:line". A finding the tracker cannot place in a file does not travel,
+and the count of those is printed to stderr rather than swallowed — a
+resolver that reports a property but no file, or a page URL instead of a
+path (every accessibility finding is one), has nothing to annotate. Nothing
+else about the scan is sent: no snippets, no counts, no source.
+
+"adopt --a11y-url=<url>" adds the one measurement a source scan can never
+make. Accessibility rules are statements about a rendered page — a contrast
+ratio is a fact about two resolved colors, a missing accessible name a fact
+about the element the browser built — so they need a running product, not a
+particular kind of connection. Where your CI already boots your app (with
+whatever session your own end-to-end tests set up), point this at the pages
+you care about and the scan renders each one in headless Chromium, runs
+axe-core against it, and folds the result in: the score becomes 40%
+components / 40% tokens / 20% accessibility instead of 50/50, and every
+critical or serious violation arrives as a finding. Without the flag,
+nothing is rendered and the score stays 50/50 — a scan that did not look is
+never reported as a scan that found nothing.
+
+playwright and axe-core are optional peer dependencies, installed only where
+you use this: "npm i -D playwright axe-core && npx playwright install
+chromium". If either is missing, or a page fails to load, the pass is
+skipped with a message on stderr and the scan reports its other numbers as
+usual — this must never be the thing that breaks your build. Only the URLs
+you name are visited; nothing is crawled, and at most 25 pages are rendered.
+
 "verify-vecna <path-to-layout.json>" is the reverse direction of "adopt":
 instead of scanning a consumer's real code for catalog usage, it checks one
 of Vecna's own generated LayoutConfig JSON files against the same catalog.
@@ -487,6 +637,30 @@ absolute path is rewritten to "<root>"/"<home>" before the payload leaves
 the machine. Paths are scrubbed only on the reported copy — stdout keeps
 the real ones, which is what is actually useful when debugging a local
 scan.
+
+"adopt --gate" judges the scan it just ran and prints a PASS/FAIL verdict
+under "gate", exiting non-zero on FAIL — the piece that makes a customer CI
+run a gate rather than a report. "stark-cli gate <adopt.json>" re-judges an
+already-saved scan with the same code, so a verdict can be reproduced (or
+re-run at a different threshold) without re-scanning.
+
+The verdict is assembled from findings the resolvers already produced — the
+gate never re-implements a check — and each of its eight checks carries the
+evidence for its own status: the components and call sites the reference
+check found, the offending file/line/rule for anything that failed. A check
+whose resolver did not run on this platform is "not-applicable"; one whose
+resolver ran with nothing in its domain (no CSS files, no catalog JSX, no
+Tailwind config) is "no-evidence". Neither can fail the gate, and neither is
+folded into "pass" — a PASS over an empty denominator is a weaker claim than
+one over a full denominator, and the two have to stay distinguishable.
+
+Low adoption is never a failure: a repo using three catalog components
+correctly passes. That is a score, which the tracker computes from the same
+scan, not a conformance verdict. "--min-components=<n>" is the opt-in
+exception, for a CI that wants an explicit floor; its finding is marked
+"policy": true to keep it separable from what the resolvers found.
+"--fail-on=<severity>" lowers the bar to warning (or info, which will fail
+on findings whose own text says no action is needed).
 `;
 
 const [, , command, ...rest] = process.argv;
@@ -557,16 +731,36 @@ switch (command) {
     const ignore = ignoreArg ? ignoreArg.split(',').map(s => s.trim()).filter(Boolean) : [];
 
     const reportUrl = flagValue(rest, 'report', undefined);
+    const prCheckUrl = flagValue(rest, 'pr-check', undefined);
+    // Opt-out, not opt-in: a finding without its code is a coordinate someone
+    // has to go and look up by hand, which is the state this flag exists to
+    // let a customer choose deliberately rather than get by default.
+    const snippets = !hasFlag(rest, 'no-snippets');
+
+    // The pages this run may render. Empty is the normal case and means the
+    // scan measures components and tokens only — accessibility is opt-in
+    // because it needs a running product, which a source scan never has and a
+    // CI pipeline sometimes does.
+    const a11yUrls = flagValues(rest, 'a11y-url');
 
     if (hasFlag(rest, 'all-targets')) {
-      if (reportUrl) {
+      if (a11yUrls.length > 0) {
+        // Refused for the same reason --report is: a rendered page belongs to
+        // one target's score, and a sweep produces one result per discovered
+        // directory. Folding one a11y number into all of them would put a
+        // measurement on targets that were never rendered.
+        fail('--a11y-url cannot be combined with --all-targets. Run "stark-cli adopt <dir> --a11y-url=<url>" once per target.');
+        break;
+      }
+      if (reportUrl || prCheckUrl) {
         // Refused rather than silently ignored. A reported scan is keyed to
         // one tracker target (targets.dir + the per-target bearer secret), and
         // an --all-targets sweep produces one result per discovered directory
         // — there is no single dir the aggregate honestly belongs to. Filing
         // it under whatever --target-dir happened to be passed would attribute
         // every target's numbers to one of them.
-        fail('--report cannot be combined with --all-targets. Run "stark-cli adopt <dir> --report=<url> --target-dir=<dir>" once per target.');
+        const which = reportUrl ? '--report' : '--pr-check';
+        fail(`${which} cannot be combined with --all-targets. Run "stark-cli adopt <dir> ${which}=<url> --target-dir=<dir>" once per target.`);
         break;
       }
       try {
@@ -575,7 +769,7 @@ switch (command) {
         const targets = {};
         for (const t of discovery.inScope) {
           const targetRoot = path.join(discovery.root, t.dir);
-          targets[t.dir] = runAdopt(targetRoot, platform, ignore, workspacePackages);
+          targets[t.dir] = runAdopt(targetRoot, platform, ignore, workspacePackages, { snippets });
         }
         print({
           root: discovery.root,
@@ -593,13 +787,58 @@ switch (command) {
 
     let adoptResult = null;
     try {
-      adoptResult = runAdopt(root, platform, ignore);
-      print(adoptResult);
+      adoptResult = runAdopt(root, platform, ignore, undefined, { snippets });
     } catch (err) {
       adoptResult = null;
       fail(err.message);
     }
 
+    // Between the scan and the print, and outside the scan's try/catch on
+    // purpose: runA11yPass never throws (adopt/a11yPass.js), and its result
+    // has to be *inside* the printed document rather than beside it, because
+    // `a11y` is what decides whether the score this scan produces may say it
+    // measured accessibility at all. A pass that could not run is recorded as
+    // such — `{ran: false, reason}` — rather than omitted, so a consumer
+    // reading the artifact can tell "no browser here" from "never asked for".
+    if (adoptResult && a11yUrls.length > 0) {
+      const a11y = await runA11yPass(a11yUrls, {
+        executablePath: flagValue(rest, 'a11y-browser-path', undefined),
+      });
+      adoptResult = { ...adoptResult, a11y };
+      // stderr, like every other outcome line here: stdout stays a clean JSON
+      // document.
+      if (a11y.ran) {
+        // "N of M" whenever some pages were dropped, and then the reason for
+        // each one. A partial pass used to print only the count it managed to
+        // measure, which reads as a complete run to anyone who does not
+        // remember how many URLs they passed — and the pass has a way to drop
+        // a page that looks entirely healthy from the outside: a page that
+        // loads perfectly and renders nothing is reported as not measured
+        // rather than scored 100 (adopt/a11yPass.js). Silence there is the
+        // worst of both, so the reasons are already computed and simply were
+        // never printed.
+        const skipped = Array.isArray(a11y.skipped) ? a11y.skipped : [];
+        const over = skipped.length > 0 ? `${a11y.scanned} of ${a11y.requested}` : `${a11y.scanned}`;
+        console.error(`Accessibility: ${a11y.score}/100 over ${over} page(s) (${a11y.counts.critical} critical, ${a11y.counts.serious} serious).`);
+        for (const s of skipped) {
+          console.error(`  Not measured: ${s.url} — ${s.reason}`);
+        }
+      } else {
+        console.error(a11y.reason);
+      }
+    }
+
+    if (adoptResult) {
+      try {
+        const gate = hasFlag(rest, 'gate') ? runGate(adoptResult, rest) : null;
+        print(gate ? { ...adoptResult, gate } : adoptResult);
+        if (gate) announceGate(gate);
+      } catch (err) {
+        adoptResult = null;
+        fail(err.message);
+      }
+    }
+
     // Same placement and the same reasoning as scan-foreign's reporting block
     // below: outside the scan's try/catch, so a fault in the reporting path
     // can never reach fail() and turn a successful scan into a non-zero exit.
@@ -622,6 +861,48 @@ switch (command) {
         console.error(`Scan complete; reporting was skipped: ${outcome.reason}`);
       }
     }
+
+    // Same placement and the same reasoning as the block above: outside the
+    // scan's try/catch, stderr only, and a fault here can never turn a
+    // successful scan into a non-zero exit. The pull request going red is the
+    // route's decision, made from what we send; it is never this command's.
+    if (adoptResult && prCheckUrl) {
+      const token = flagValue(rest, 'token', process.env.STARK_DOMINION_TOKEN);
+      const outcome = await reportPrCheck(adoptResult, {
+        url: prCheckUrl,
+        token,
+        // Same `root` --report passes, and required for the same reason it is
+        // there: it is what turns an absolute `file` into the spelling the
+        // stored scan holds, so the check can tell a new finding from one it
+        // has already seen (adopt/prCheckReport.js).
+        root,
+        targetDir: flagValue(rest, 'target-dir', undefined),
+        commitSha: flagValue(rest, 'commit', resolveCommitSha(root)),
+      }).catch((err) => ({ reported: false, reason: err.message }));
+
+      if (outcome.reported) {
+        const check = outcome.response?.checkRun;
+        const where = check?.posted
+          ? `Check Run posted (${check.conclusion})`
+          : outcome.response?.skipped
+            ? 'the target has PR checks turned off'
+            : 'diff computed, no Check Run posted';
+        console.error(`PR check sent to ${prCheckUrl}: ${outcome.sent} finding(s), ${where}.`);
+      } else {
+        console.error(`Scan complete; the PR check was skipped: ${outcome.reason}`);
+      }
+
+      // Printed whether or not the send succeeded, and never as a failure: a
+      // dropped finding is a gap in what the check can say, and a gap nobody
+      // is told about is how this whole wire stayed missing.
+      const s = outcome.skipped;
+      if (s && (s.noRule || s.noFile || s.notInFile)) {
+        console.error(
+          `  Not sent (nothing to annotate): ${s.noFile} without a file, ` +
+          `${s.notInFile} not in a source file, ${s.noRule} without a rule name.`,
+        );
+      }
+    }
     break;
   }
 
@@ -637,6 +918,35 @@ switch (command) {
     break;
   }
 
+  case 'gate': {
+    const [maybePath] = rest;
+    if (!maybePath || maybePath.startsWith('--')) {
+      fail('Usage: stark-cli gate <path-to-adopt.json> [--fail-on=<severity>] [--min-components=<n>]');
+      break;
+    }
+    const scanPath = path.resolve(process.cwd(), maybePath);
+    let adoptResult;
+    try {
+      adoptResult = JSON.parse(readFileSync(scanPath, 'utf-8'));
+    } catch (err) {
+      fail(err.message);
+      break;
+    }
+    // Unlike "adopt --gate", a bad threshold here is the whole command rather
+    // than one flag on a scan that still has output worth printing — so it
+    // fails outright instead of degrading to a FAIL verdict.
+    try {
+      gateOptions(rest);
+    } catch (err) {
+      fail(err.message);
+      break;
+    }
+    const gate = runGate(adoptResult, rest);
+    print(gate);
+    announceGate(gate);
+    break;
+  }
+
   case 'verify-vecna': {
     const [maybePath] = rest;
     if (!maybePath || maybePath.startsWith('--')) {
@@ -767,6 +1077,31 @@ switch (command) {
     break;
   }
 
+  // The grounding a model answers a design-system question from — the same
+  // brain behind Whisperer in Stark Dominion, for an editor agent or a shell
+  // pipeline. Prints the system prompt as text, ready to paste; --json gives
+  // the parts apart, for a caller that puts them in its own slots.
+  case 'whisper': {
+    const question = rest.find(a => !a.startsWith('--'));
+    if (!question) {
+      fail('Usage: stark-cli whisper "<question>" [--context=<prior turn>]... [--json]');
+      break;
+    }
+    const context = flagValues(rest, 'context');
+    try {
+      const result = whispererContext(question, context);
+      if (hasFlag(rest, 'json')) {
+        const { text, ...parts } = result;
+        print(parts);
+      } else {
+        console.log(result.text);
+      }
+    } catch (err) {
+      fail(err.message);
+    }
+    break;
+  }
+
   case undefined:
   case '--help':
   case '-h':

package/src/data.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { loadUsage } from '@starklab/stk/usage/loader.js';
 import { buildCatalogFromDir } from '@starklab/stk/conformance/catalog.js';
 import { runConformance, hasBlocking } from '@starklab/stk/conformance/index.js';
+import { createWhisperer, WHISPERER_SYSTEM_PROMPT } from './whisperer.js';
 
 const require = createRequire(import.meta.url);
 
@@ -53,17 +54,54 @@ function mappingFiles(dir) {
   return readdirSync(dir).filter(f => f.endsWith('.mapping.json'));
 }
 
+// catalog.json is the existence authority: one entry per barrel export, per
+// platform, with the kind of thing it is. The mapping files are a Figma-parity
+// contract, and a component can ship without one (MoveMenu, StatusPage — and,
+// by design, every React Native component), so a list built from the mapping
+// directory alone told external agents those components did not exist.
+const CATALOG_PLATFORMS = { web: 'web', rn: 'native' };
+
+// Kinds a caller can reach for as a component. Hooks, providers and constants
+// are exports, not components, and stay out of the list.
+const LISTED_KINDS = new Set(['component', 'primitive', 'subpart']);
+
+function catalogComponents(root = stkRoot()) {
+  const catalog = readJson(path.join(root, 'catalog.json'));
+  const byName = new Map();
+  for (const [catalogPlatform, platform] of Object.entries(CATALOG_PLATFORMS)) {
+    const exports = catalog.platforms?.[catalogPlatform]?.exports ?? {};
+    for (const [name, entry] of Object.entries(exports)) {
+      if (!LISTED_KINDS.has(entry?.kind)) continue;
+      if (!byName.has(name)) byName.set(name, new Set());
+      byName.get(name).add(platform);
+    }
+  }
+  return byName;
+}
+
+// The union of the catalog and the mapping files, and the union of the
+// platforms each names: a mapping file may say `web` for a component the RN
+// barrel also exports (DropdownMenu), and the catalog cannot know a platform
+// the mapping declares for a component it does not classify.
 export function listComponents() {
   const dir = mappingDir();
-  return mappingFiles(dir)
-    .map(file => {
-      const mapping = readJson(path.join(dir, file));
-      const slug = toSlug(mapping.component);
-      const usage = loadUsage(slug);
+  const platformsByName = catalogComponents();
+  for (const file of mappingFiles(dir)) {
+    const mapping = readJson(path.join(dir, file));
+    if (!platformsByName.has(mapping.component)) platformsByName.set(mapping.component, new Set());
+    for (const platform of mapping.platforms ?? ['web']) platformsByName.get(mapping.component).add(platform);
+  }
+  return [...platformsByName.entries()]
+    .map(([name, platformSet]) => {
+      const slug = toSlug(name);
+      const platforms = ['web', 'native'].filter(p => platformSet.has(p));
+      // The web file is the canonical prose; a component that only exists on
+      // React Native describes itself from its RN file instead.
+      const usage = loadUsage(slug) ?? loadUsage(slug, { platform: 'native' });
       return {
-        name: mapping.component,
+        name,
         slug,
-        platforms: mapping.platforms ?? ['web'],
+        platforms,
         status: usage?.status ?? 'unknown',
         description: usage?.description ?? null,
         figmaUrl: usage?.figmaUrl ?? null,
@@ -132,10 +170,17 @@ export function getComponentProps(component, platform = 'web', includeTokens = f
   return result;
 }
 
-// Aggregates the full catalog — usage, props (per supported platform), and
-// tokens — into one artifact, so an external caller doesn't need N round
-// trips (list_components, then get_component_usage/get_component_props per
-// component) just to see the whole system's shape.
+// Aggregates the full catalog — usage (per platform), props (per supported
+// platform), and tokens — into one artifact, so an external caller doesn't
+// need N round trips (list_components, then get_component_usage/
+// get_component_props per component) just to see the whole system's shape.
+//
+// `usage` is the web file and `nativeUsage` the React Native one
+// (usage/components/rn/): the RN files are their own set, with a prop table
+// (name, type, default, description), a code example and their own dos/donts,
+// because the RN port's props differ from web's for most components. Kept as
+// two fields rather than nesting `usage` per platform so that a reader of an
+// earlier manifest finds `usage` where it always was.
 export function buildManifest() {
   const components = listComponents().map(({ name, slug, status, description, figmaUrl, platforms }) => {
     let usage = null;
@@ -144,6 +189,7 @@ export function buildManifest() {
     } catch {
       // no usage/*.usage.json for this component
     }
+    const nativeUsage = platforms.includes('native') ? loadUsage(slug, { platform: 'native' }) : null;
 
     const props = {};
     for (const platform of ['web', 'native']) {
@@ -163,6 +209,7 @@ export function buildManifest() {
       figmaUrl,
       platforms,
       usage,
+      nativeUsage,
       props,
       tokens: getComponentTokens(name),
     };
@@ -265,3 +312,50 @@ export function ejectComponent(component, { outDir, cwd = process.cwd(), force =
 
   return { component: name, platform, from: sourceDir, to: target, files };
 }
+
+// ---------------------------------------------------------------------------
+// Whisperer — the grounding an answer about the design system is built on.
+// The logic lives in whisperer.js, which takes the generated files as data so
+// that Dominion's chat panel and this server share one brain; this is the
+// side that loads those files from the installed @starklab/stk.
+// ---------------------------------------------------------------------------
+
+
+let whispererInstance = null;
+
+// Built once per process: the token list and the catalog index are cached
+// inside the instance, and the five files are ~1 MB of JSON to re-read.
+export function loadWhisperer() {
+  if (!whispererInstance) {
+    whispererInstance = createWhisperer({
+      manifest: require('@starklab/stk/manifest.json'),
+      catalog: require('@starklab/stk/catalog.json'),
+      componentProps: require('@starklab/stk/component-props.json'),
+      tokenMeta: require('@starklab/stk/json-meta'),
+      tokenDark: require('@starklab/stk/json-dark'),
+    });
+  }
+  return whispererInstance;
+}
+
+// Everything a model needs to answer one question about the design system:
+// the rules it answers under and the facts it may answer from. `context` is
+// the prior turns of the conversation, newest first, so a follow-up that
+// names no component keeps the detail of the one it is about. The caller
+// puts `systemPrompt` in its system slot and `grounding` under a
+// "# The design system" heading — or takes `text`, which is both already
+// joined that way.
+export function whispererContext(question, context = []) {
+  if (typeof question !== 'string' || !question.trim()) {
+    throw new Error('whisperer_context needs a question: the text of what is being asked about the design system.');
+  }
+  const { text, components, named, tokens } = loadWhisperer().buildGrounding(question, context);
+  return {
+    systemPrompt: WHISPERER_SYSTEM_PROMPT,
+    grounding: text,
+    text: `${WHISPERER_SYSTEM_PROMPT}\n\n# The design system\n\n${text}`,
+    components,
+    named,
+    tokens,
+  };
+}