@starklab/stark-mcp 0.2.0 → 0.3.0

package/README.md

@@ -31,14 +31,15 @@ Add to your MCP client config (e.g. `.mcp.json`):
 
 | Tool | Wraps | Returns |
 |---|---|---|
-| `list_components` | `prop-mapping/components/*.mapping.json` + `usage/components/*.usage.json` | name, slug, status, description, platforms |
+| `list_components` | `catalog.json` exports ∪ `prop-mapping/components/*.mapping.json` + `usage/components/{,rn/}*.usage.json` | name, slug, status, description, platforms |
 | `get_component_usage` | `usage/loader.js` (`loadUsage`) | dos/donts, props, figmaUrl, status |
 | `get_component_props` | `prop-mapping/components/{c}.mapping.json` (+ `tokens/components/{c}.json` when `includeTokens` is set) | React↔Figma `propMap` for a platform, optionally the component's token JSON |
-| `get_manifest` | all of the above, aggregated | usage + props (per platform) + tokens for every component in one call |
+| `get_manifest` | all of the above, aggregated | usage (web) + nativeUsage (React Native) + props (per platform) + tokens for every component in one call |
 | `get_layout_catalog` | `conformance/catalog.js` (`buildCatalogFromDir`) | every layout-capable component's props/slots |
 | `get_layout_schema` | same, filtered to one component | one component's layoutSchema |
 | `validate_layout` | `conformance/index.js` (`runConformance`) | deterministic findings (`Critical`/`Warning`/`Info`), no LLM involved |
 | `get_generation_protocol` | `generation-protocol.json` | the enforced step checklist Vecna runs |
+| `whisperer_context` | `manifest.json` + `catalog.json` + `component-props.json` + `json-meta` + `json-dark`, through `src/whisperer.js` | a system prompt (prose, not JSON): the rules to answer under and every component and token to answer from, with the ones the question names expanded in full |
 
 ## CLI
 
@@ -58,13 +59,50 @@ The package name and the `stark-mcp` bin match, so plain `npx
 is what selects the second (`stark-cli`) bin instead. Once installed locally
 or globally, just run `stark-cli <command>`. Run `stark-cli --help` for the
 full command list. Output is always JSON on stdout; errors go to stderr with
-a non-zero exit code.
+a non-zero exit code — except `whisper`, whose output is prose.
+
+## Whisperer
+
+`whisperer_context` is the brain behind Whisperer, the customization
+concierge in Stark Dominion, published so that an editor agent — Cursor,
+Claude Code, anything holding this server — answers a design-system question
+from the same facts Dominion's chat panel does, through the same code path
+(`src/whisperer.js`; Dominion imports it rather than keeping a copy). Give it
+the question and, for a follow-up, the prior turns newest first; put what
+comes back in the system prompt and answer from it alone. It carries every
+component with its props per platform, every semantic token and scale with
+its light and dark values, the token it aliases and its React Native export
+name, and the full detail — usage, props, examples, component tokens — of the
+components the question names. The colour-shade primitives are deliberately
+withheld from the list, because a component token must alias a semantic
+token, never a shade; a question that names one outright still gets it
+resolved.
+
+From a terminal:
+
+```bash
+npx --package=@starklab/stark-mcp stark-cli whisper "Does Card exist on React Native?"
+npx --package=@starklab/stark-mcp stark-cli whisper "and the sizes?" --context="What variants does Button have?"
+npx --package=@starklab/stark-mcp stark-cli whisper "What is --stk-radius-md?" --json
+```
+
+`--json` gives the parts apart — `systemPrompt`, `grounding`, and the
+`components`, `named` and `tokens` the grounding expanded — for a caller
+that fills its own slots. The rules the prompt carries are the design
+system's; a surface adds its own (Dominion adds how its panel renders and
+that it cannot see the questioner's code).
 
 ## Public manifest
 
 `npm run generate-manifest` writes the full catalog (usage + props + tokens
 for every component) to `manifest.json` inside the installed
-`@starklab/stk` package. Run it before publishing a new version of
+`@starklab/stk` package. The list of components is `catalog.json`'s exports
+(every `component`, `primitive` and `subpart`, on either platform) unioned
+with the mapping files, so a component that ships without a mapping file
+(`MoveMenu`, `StatusPage`, every React Native component) is still in it. Per
+component, `usage` is the web usage file and `nativeUsage` the React Native
+one from `usage/components/rn/` — its own rules, prop table and code example —
+or `null` where the platform does not apply. Run it before publishing a new version of
 `stk` so the manifest ships with it and stays fetchable as a static file —
 e.g. via a CDN mirror of the npm package — without needing an MCP session at
 all. It's not checked into git (same as `stk`'s `build/` output); regenerate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starklab/stark-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server exposing the Stark design system catalog, usage rules, prop mappings, and layout conformance checks to any MCP-compatible coding agent — without needing the stark-workspace monorepo checked out.",
   "license": "MIT",
   "type": "module",
@@ -21,9 +21,20 @@
     "start": "node src/index.js",
     "generate-manifest": "node scripts/generate-manifest.js",
     "generate-foreign-systems": "node scripts/generate-foreign-systems.js",
+    "canary:foreign": "node scripts/foreign-canary.js",
     "validate:pack": "node ../../scripts/validate-pack.mjs",
     "prepublishOnly": "npm run validate:pack"
   },
+  "peerDependencies": {
+    "axe-core": ">=4",
+    "playwright": ">=1.40",
+    "playwright-core": ">=1.40"
+  },
+  "peerDependenciesMeta": {
+    "axe-core": { "optional": true },
+    "playwright": { "optional": true },
+    "playwright-core": { "optional": true }
+  },
   "dependencies": {
     "@starklab/stk": "^1.2.0",
     "@babel/parser": "^7.29.7",

package/src/adopt/a11yPass.js

@@ -0,0 +1,397 @@
+/**
+ * The accessibility half of `stark-cli adopt`, and the only part of the
+ * command that needs a browser.
+ *
+ * Why it exists at all: accessibility rules are statements about a *rendered*
+ * page — a contrast ratio is a fact about two resolved colors, a missing
+ * accessible name is a fact about the element the browser actually built. A
+ * static scan of source has neither, which is why lib/adoptionScan.ts's
+ * `scoreFrom` drops the a11y term rather than inventing it. The missing
+ * ingredient is a running product, not a connector: it happens that Dominion's
+ * own crawler is the only place one existed, and that is a fact about where
+ * the browser was, not about repos.
+ *
+ * So this runs the browser where a running product already exists and no
+ * credential problem does — inside the consumer's own CI, against the app
+ * their pipeline just booted, with whatever logged-in session their own tests
+ * already set up. Dominion never sees the URLs; it sees the numbers.
+ *
+ * Three properties are inherited wholesale from adoptScanReport.js, because
+ * this runs in the same place under the same rules:
+ *
+ *  1. **It must never break the consumer's CI.** Every failure path returns
+ *     `{ ran: false, reason }`. Nothing throws, nothing sets process.exitCode,
+ *     and a missing browser is an ordinary outcome rather than an error — the
+ *     adoption scan itself already succeeded and has numbers to report.
+ *  2. **It must not leak anything the consumer did not name.** The only URLs
+ *     visited are the ones passed on the command line. There is no crawl here
+ *     and deliberately so: following links inside a CI network is how a
+ *     scanner ends up on an internal host nobody meant to hand it.
+ *  3. **The penalty scale is shared, not chosen.** AXE_SCORE_MAP below is the
+ *     same map packages/stk/scripts/a11y/axe-runner.js and dominion's
+ *     lib/url-crawl.ts use. An a11y number measured here has to be comparable
+ *     with one measured by the crawler or the label "includes accessibility"
+ *     would mean two different things.
+ *
+ * One rule is this module's own, because only this module runs against a page
+ * the consumer's CI just booted rather than a public site: **a page axe could
+ * read but the browser never filled is not a measurement.** See SETTLE_CAP_MS
+ * and isBlankRender below — between them they are the difference between
+ * scoring the product and scoring the empty div it mounts into.
+ */
+
+/**
+ * ds-governance.md's scoring matrix, byte-identical to the two other places it
+ * appears. Only `critical` and `serious` are scored: `moderate` and `minor`
+ * are advisory in axe's own vocabulary, and letting them move a number would
+ * make the score depend on axe's taxonomy drift rather than on the product.
+ */
+const AXE_SCORE_MAP = { critical: -20, serious: -10 };
+
+/** Same ceiling as lib/url-crawl.ts's SITE_PAGE_CAP, for the same reason. */
+const MAX_PAGES = 25;
+
+/** Per page. A CI job is not a place to hang on a slow route. */
+const DEFAULT_PAGE_TIMEOUT_MS = 20000;
+
+/** A snippet is a hover-sized excerpt — dominion bounds these again on ingest. */
+const MAX_HTML_LENGTH = 400;
+
+/**
+ * How long a page may keep changing after `load` before axe reads it, and how
+ * much stillness counts as finished.
+ *
+ * `load` fires once the document and its subresources are in. On a
+ * server-rendered page that is the moment the markup is final; on a
+ * client-rendered one it is roughly the moment the first script starts
+ * running. This pass is pointed at a page of the consumer's own product,
+ * booted by their own pipeline, so the second case is the common one and axe
+ * was reading the shell before the product existed — no violations found,
+ * score 100, and the "includes accessibility" label on a measurement of
+ * nothing.
+ *
+ * Waiting on the network is the usual reflex and the wrong one here.
+ * `networkidle` wants 500ms with no connections at all, and the app under
+ * test in CI is very often a dev server holding an open hot-reload socket, so
+ * that wait would expire on every page and spend its whole budget doing it.
+ * What axe needs is a DOM that has stopped moving *and has something in it*,
+ * so that is what this waits for directly. Both halves are load-bearing, and
+ * the first one alone is wrong in a way that looks right: at `load` a
+ * client-rendered page is perfectly still — it has not started yet — so a
+ * plain quiet-period check passes immediately and measures the shell it was
+ * written to avoid. Measured against a page that renders after 800ms, the
+ * quiet-only version returned "nothing rendered" and the pass reported no
+ * measurement at all.
+ *
+ * The cost lands where it should: a page already finished at `load` leaves
+ * after SETTLE_QUIET_MS, a page still building leaves SETTLE_QUIET_MS after
+ * its last change, and only a page that never renders anything pays the full
+ * cap — which is exactly the page whose measurement is about to be thrown
+ * away anyway.
+ */
+const SETTLE_QUIET_MS = 500;
+const SETTLE_CAP_MS = 5000;
+
+/**
+ * Loads playwright without making it a dependency of this package.
+ *
+ * `playwright` is tried before `playwright-core` because only the former
+ * brings a browser with it; a consumer who installed the core package alone is
+ * expected to point at their own binary. Neither is declared as anything but
+ * an optional peer: most people running `stark-cli adopt` never pass an a11y
+ * URL, and a browser download is not a reasonable cost to put on them.
+ */
+async function loadChromium() {
+  for (const specifier of ['playwright', 'playwright-core']) {
+    try {
+      const mod = await import(specifier);
+      if (mod?.chromium) return { chromium: mod.chromium, specifier };
+    } catch {
+      // Not installed, or installed broken. Try the next one; the caller gets
+      // one actionable message below rather than a stack per attempt.
+    }
+  }
+  return null;
+}
+
+async function loadAxe() {
+  try {
+    const mod = await import('axe-core');
+    // axe-core ships CJS; the default interop is where `source` lands.
+    const axe = mod?.default ?? mod;
+    return axe?.source ? axe : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The element's own markup, bounded. Unlike a source finding there is no file
+ * and no line to point at, so the markup and the selector are the whole of the
+ * evidence — the same trade dominion's URL findings make, and the reason those
+ * show "what to write" rather than a diff to apply.
+ */
+function snippetFor(url, node, violation) {
+  const html = String(node?.html ?? '').slice(0, MAX_HTML_LENGTH);
+  if (!html) return null;
+  return {
+    file: url,
+    before: [html],
+    after: null,
+    highlightIndex: 0,
+    beforeAnnotation: String(violation?.help ?? violation?.id ?? '').slice(0, 200) || null,
+    afterAnnotation: null,
+  };
+}
+
+function selectorOf(node) {
+  const target = Array.isArray(node?.target) ? node.target : [];
+  // axe nests a frame path as an array; flattened here so one string is one
+  // element wherever it lives.
+  return target.flat().filter((t) => typeof t === 'string').join(' >>> ');
+}
+
+/**
+ * Wait for the page to stop building itself, and to have built something.
+ *
+ * Best-effort by contract: a page that loaded gets measured whether or not
+ * this settles, so every failure here is swallowed rather than costing the
+ * consumer a measurement. The cap is what makes it safe to point at a page
+ * that never comes to rest — a ticking clock, a carousel, a poller, or one
+ * that renders nothing at all — and the quiet period is what keeps it cheap
+ * against a page that was finished before it arrived.
+ *
+ * The readiness test is isBlankRender's, inverted, and it has to be: this
+ * decides when to stop waiting for content, that decides whether content ever
+ * came, and two different answers to "is there anything here" would let a
+ * page fail one and pass the other.
+ */
+async function settleDom(page, { quietMs = SETTLE_QUIET_MS, capMs = SETTLE_CAP_MS } = {}) {
+  try {
+    await page.evaluate(
+      ({ quiet, cap }) =>
+        new Promise((resolve) => {
+          let idle;
+          const observer = new MutationObserver(restart);
+
+          const rendered = () => {
+            const body = document.body;
+            if (!body) return false;
+            if (body.innerText.trim().length > 0) return true;
+            return body.querySelectorAll('img, svg, canvas, video, iframe').length > 0;
+          };
+
+          function stop() {
+            clearTimeout(idle);
+            clearTimeout(ceiling);
+            observer.disconnect();
+            resolve();
+          }
+          // Quiet is only the end of the wait once there is something to have
+          // gone quiet about. Until then this re-arms rather than finishing,
+          // which also keeps a page that renders with no DOM change of its
+          // own — an <img> that simply took its time — from being read early.
+          function settled() {
+            if (rendered()) stop();
+            else restart();
+          }
+          function restart() {
+            clearTimeout(idle);
+            idle = setTimeout(settled, quiet);
+          }
+
+          observer.observe(document.documentElement, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            characterData: true,
+          });
+          // Declared here rather than above so it can be const: nothing can
+          // call stop() before this line runs, since this is the first timer
+          // armed and the observer only ever re-arms `idle`.
+          const ceiling = setTimeout(stop, cap);
+          restart();
+        }),
+      { quiet: quietMs, cap: capMs },
+    );
+  } catch {
+    // The page went away, or navigated under us. Either way the next step
+    // reads whatever is actually there, and says so if it is nothing.
+  }
+}
+
+/** What the browser ended up showing, reduced to the two facts below. */
+async function inspectRender(page) {
+  return page.evaluate(() => ({
+    text: (document.body ? document.body.innerText : '').trim().slice(0, 200),
+    visuals: document.body
+      ? document.body.querySelectorAll('img, svg, canvas, video, iframe').length
+      : 0,
+  }));
+}
+
+/**
+ * Whether the browser rendered nothing a person could have read or seen.
+ *
+ * axe is honest about an empty page: it reports no violations, because there
+ * is nothing there to violate anything. Scored, that reads as a flawless
+ * page — the same "reward a broken route" mistake the load-failure path
+ * refuses to make, arriving through a different door, and the one failure
+ * this pass could otherwise report as a success. A client-rendered app whose
+ * bundle 404s in the consumer's CI lands here every time.
+ *
+ * Deliberately blunt: any text at all, or any image, icon, canvas, video or
+ * frame, counts as rendered. A real page clears that bar without trying, and
+ * the alternative — deciding how much content is enough — would start
+ * throwing away real measurements of pages that are merely sparse.
+ */
+export function isBlankRender({ text = '', visuals = 0 } = {}) {
+  return String(text).trim().length === 0 && visuals === 0;
+}
+
+const BLANK_RENDER_REASON =
+  'The page loaded but rendered nothing — no text and no images. An empty page has no violations, which would score as a perfect one, so it is reported as not measured instead.';
+
+/**
+ * Runs axe against each URL and folds the results into one a11y score.
+ *
+ * Never throws. `ran: false` means the pass could not run at all and the caller
+ * must report a scan *without* accessibility rather than one with a zero in it
+ * — a page that failed to load and a page with no violations are not the same
+ * measurement, and only one of them may carry the "includes accessibility"
+ * label.
+ */
+export async function runA11yPass(urls, {
+  timeoutMs = DEFAULT_PAGE_TIMEOUT_MS,
+  maxPages = MAX_PAGES,
+  executablePath = process.env.STARK_A11Y_BROWSER_PATH || undefined,
+} = {}) {
+  const wanted = [...new Set((urls ?? []).filter(Boolean))];
+  if (wanted.length === 0) return { ran: false, reason: 'No --a11y-url was given.' };
+
+  const loaded = await loadChromium();
+  if (!loaded) {
+    return {
+      ran: false,
+      reason:
+        'Accessibility pass skipped: playwright is not installed. Add it where this scan runs — "npm i -D playwright && npx playwright install chromium" — or drop --a11y-url to score without accessibility.',
+    };
+  }
+  const axe = await loadAxe();
+  if (!axe) {
+    return {
+      ran: false,
+      reason: 'Accessibility pass skipped: axe-core is not installed. Add it where this scan runs: "npm i -D axe-core".',
+    };
+  }
+
+  const requested = wanted.length;
+  const pageUrls = wanted.slice(0, maxPages);
+
+  let browser;
+  try {
+    browser = await loaded.chromium.launch({ headless: true, ...(executablePath ? { executablePath } : {}) });
+  } catch (err) {
+    return {
+      ran: false,
+      reason: `Accessibility pass skipped: could not launch a browser (${err.message}). If you installed playwright-core only, set STARK_A11Y_BROWSER_PATH or pass --a11y-browser-path.`,
+    };
+  }
+
+  const pages = [];
+  const findings = [];
+  const failed = [];
+  try {
+    const context = await browser.newContext();
+    for (const url of pageUrls) {
+      const page = await context.newPage();
+      try {
+        await page.goto(url, { waitUntil: 'load', timeout: timeoutMs });
+        await settleDom(page);
+        if (isBlankRender(await inspectRender(page))) {
+          failed.push({ url, reason: BLANK_RENDER_REASON });
+          continue;
+        }
+        await page.addScriptTag({ content: axe.source });
+        const results = await page.evaluate(() => window.axe.run(document.documentElement));
+
+        // One entry per failing node, not per rule: the score is a count of
+        // occurrences, and so is the queue a person works through.
+        const nodes = (results?.violations ?? [])
+          .filter((v) => v.impact === 'critical' || v.impact === 'serious')
+          .flatMap((v) => (v.nodes ?? []).map((node) => ({ violation: v, node })));
+
+        let critical = 0;
+        let serious = 0;
+        const seen = new Set();
+        for (const { violation, node } of nodes) {
+          const selector = selectorOf(node);
+          // Two axe checks can report the same element under the same rule
+          // through different frame paths; the pair is the occurrence.
+          const key = `${violation.id}:${selector}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+
+          if (violation.impact === 'critical') critical += 1;
+          else serious += 1;
+
+          findings.push({
+            rule: violation.id,
+            // The page's own URL stands in for a file path — the same
+            // substitution lib/url-crawl.ts makes, and what the finding's
+            // header shows.
+            file: url,
+            selector,
+            severity: violation.impact === 'critical' ? 'critical' : 'warning',
+            snippet: snippetFor(url, node, violation),
+          });
+        }
+
+        const penalty = critical * AXE_SCORE_MAP.critical + serious * AXE_SCORE_MAP.serious;
+        pages.push({ url, score: Math.max(0, 100 + penalty), critical, serious });
+      } catch (err) {
+        // A page that did not load was not measured. It is recorded as such
+        // rather than scored 100 (which would reward a broken route) or 0
+        // (which would punish the product for a CI networking problem).
+        failed.push({ url, reason: err.message });
+      } finally {
+        await page.close().catch(() => {});
+      }
+    }
+  } catch (err) {
+    return { ran: false, reason: `Accessibility pass failed: ${err.message}` };
+  } finally {
+    await browser.close().catch(() => {});
+  }
+
+  if (pages.length === 0) {
+    return {
+      ran: false,
+      // "measured", not "loaded": a page can now fail here by loading
+      // perfectly and showing nothing, and the reason below says which.
+      reason: `Accessibility pass skipped: none of the ${requested} page(s) could be measured.${failed[0] ? ` First reason: ${failed[0].reason}` : ''}`,
+    };
+  }
+
+  // Averaged across pages, not summed: a11y is a rate, and lib/url-crawl.ts's
+  // aggregateSite averages it for the same reason component and token counts
+  // are summed and it is not — twenty clean pages do not pay for one broken
+  // one, and a site is not more accessible for having more pages.
+  const score = Math.round(pages.reduce((s, p) => s + p.score, 0) / pages.length);
+
+  return {
+    ran: true,
+    score,
+    pages,
+    requested,
+    scanned: pages.length,
+    skipped: failed,
+    counts: {
+      critical: pages.reduce((s, p) => s + p.critical, 0),
+      serious: pages.reduce((s, p) => s + p.serious, 0),
+    },
+    findings,
+  };
+}
+
+export { AXE_SCORE_MAP };