@starklab/stark-mcp 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starklab/stark-mcp",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -10,22 +10,28 @@
   },
   "main": "./src/server.js",
   "files": [
-    "src/"
+    "src/",
+    "!src/**/*.test.js",
+    "!src/adopt/__fixtures__"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "start": "node src/index.js",
-    "generate-manifest": "node scripts/generate-manifest.js"
+    "generate-manifest": "node scripts/generate-manifest.js",
+    "generate-foreign-systems": "node scripts/generate-foreign-systems.js",
+    "validate:pack": "node ../../scripts/validate-pack.mjs",
+    "prepublishOnly": "npm run validate:pack"
   },
   "dependencies": {
-    "@starklab/stk": "^1.1.0",
+    "@starklab/stk": "^1.2.0",
     "@babel/parser": "^7.29.7",
     "@babel/traverse": "^7.29.7",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "fast-glob": "^3.3.3",
     "postcss": "^8.5.25",
+    "typescript": "^6.0.0",
     "zod": "^4.0.0"
   }
 }

package/src/adopt/adoptScanReport.js

@@ -0,0 +1,124 @@
+import { scrubForeignScanPaths } from './foreignScanReport.js';
+
+/**
+ * The reporting half of `stark-cli adopt --report`: turns a `runAdopt` result
+ * into the payload Dominion's POST /api/adoption-scan accepts, and sends it.
+ *
+ * This is the sibling of foreignScanReport.js and inherits both of its
+ * governing constraints verbatim — read that file's header for the full
+ * reasoning:
+ *
+ *  1. **It must never break the consumer's CI.** Every failure path returns
+ *     `{ reported: false, reason }`; nothing throws, and the caller never
+ *     touches `process.exitCode`.
+ *  2. **It must not leak the customer's filesystem layout.** `runAdopt`'s
+ *     output embeds the absolute scan root at the top level and again inside
+ *     every resolver's sub-result, so the same scrub applies. It is imported
+ *     rather than reimplemented: `scrubForeignScanPaths` is already generic
+ *     over any value, and a second copy would be a second thing to keep
+ *     correct.
+ */
+
+/**
+ * Per-site enumerations dropped before sending, at any depth.
+ *
+ * Same reduction rationale as foreignScanReport.js's `stripPropSchema`: the
+ * ingest reads counts and the three-number `report` summaries, never the
+ * enumeration behind them, and the enumeration is re-derivable by re-scanning.
+ * Each of these is one entry per source location, so on a real repo they are
+ * most of the document:
+ *
+ *   sites       — referenceResolver: one per component reference
+ *   usages      — tokenAlias/tailwind (web + RN): one per token usage site
+ *   properties  — tokenAlias/tailwind (web + RN): one per consumer-declared
+ *                 custom property / theme entry
+ *   checks      — propApiResolver: one per validated JSX attribute
+ *
+ * `findings` is deliberately NOT in this list. A finding is a defect the
+ * tracker exists to surface, and the counts alone can't reconstruct one.
+ *
+ * stdout is untouched either way — `--report` changes what is sent, never what
+ * the command prints.
+ */
+const DROPPED_KEYS = new Set(['sites', 'usages', 'properties', 'checks']);
+
+export function stripAdoptDetail(value) {
+  if (Array.isArray(value)) return value.map(stripAdoptDetail);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (DROPPED_KEYS.has(key)) continue;
+      out[key] = stripAdoptDetail(child);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** Builds the request body POST /api/adoption-scan expects. */
+export function buildAdoptScanReport(result, { root, targetDir, commitSha, scannerVersion }) {
+  return {
+    targetDir,
+    commitSha,
+    scannerVersion,
+    result: scrubForeignScanPaths(stripAdoptDetail(result), root),
+  };
+}
+
+/**
+ * POSTs the adoption scan and resolves to an outcome record. Never throws,
+ * never rejects — see property (1) in this file's header.
+ *
+ * `fetchImpl` exists for tests; production always uses global fetch.
+ */
+export async function reportAdoptScan(result, {
+  url,
+  token,
+  root,
+  targetDir,
+  commitSha,
+  scannerVersion,
+  timeoutMs = 15000,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const missing = Object.entries({ url, token, targetDir, commitSha, scannerVersion })
+    .filter(([, v]) => !v)
+    .map(([k]) => k);
+  if (missing.length > 0) {
+    return { reported: false, reason: `Missing required reporting field(s): ${missing.join(', ')}.` };
+  }
+
+  const body = buildAdoptScanReport(result, { root, targetDir, commitSha, scannerVersion });
+
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (err) {
+    // Network down, DNS failure, TLS error, timeout. The scan itself already
+    // succeeded and has already been printed.
+    return { reported: false, reason: `Could not reach ${url}: ${err.message}` };
+  }
+
+  const text = await response.text().catch(() => '');
+  let parsed = null;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch {
+    // A proxy or error page rather than the API. Surfaced as-is below.
+  }
+
+  if (!response.ok) {
+    const detail = parsed?.error ?? (text ? text.slice(0, 200) : '(empty response)');
+    return { reported: false, status: response.status, reason: `${url} returned ${response.status}: ${detail}` };
+  }
+
+  return { reported: true, status: response.status, response: parsed };
+}

package/src/adopt/catalog.js

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { stkRoot } from '../data.js';
@@ -30,7 +30,11 @@ function readBarrel(file) {
     const m = bare.match(/^export\s*\{([^}]+)\}\s*from\s*['"][^'"]+['"];?$/);
     if (!m) continue;
     for (const part of m[1].split(',')) {
-      const name = part.trim().split(/\s+as\s+/).pop().trim();
+      const name = part
+        .trim()
+        .split(/\s+as\s+/)
+        .pop()
+        .trim();
       if (name) names.push(name);
     }
   }
@@ -54,7 +58,9 @@ const toSlug = (s) =>
 export function loadCatalog(platform = 'web') {
   const catalogKey = CATALOG_KEY[platform];
   if (!catalogKey) {
-    throw new Error(`Unsupported platform "${platform}". Available: ${Object.keys(CATALOG_KEY).join(', ')}.`);
+    throw new Error(
+      `Unsupported platform "${platform}". Available: ${Object.keys(CATALOG_KEY).join(', ')}.`
+    );
   }
 
   const root = stkRoot();
@@ -64,10 +70,22 @@ export function loadCatalog(platform = 'web') {
     throw new Error(`catalog.json has no "${catalogKey}" platform entry.`);
   }
 
-  const barrelPath = path.resolve(root, cfg.barrel);
-  const exported = readBarrel(barrelPath);
   const classified = cfg.exports ?? {};
 
+  // In the monorepo the barrel is read directly, so drift between it and
+  // catalog.json surfaces here as well as in reconcile-catalog.js. In a
+  // published install it is absent: cfg.barrel points at a sibling package
+  // (@starklab/stk-components / -react-native) that stark-mcp deliberately
+  // does not depend on — those ship React, floating-ui and the whole UI
+  // graph, which an MCP server has no business pulling in to read a list of
+  // names. Fall back to catalog.json's own classified export list, which
+  // reconcile-catalog.js already gates against the barrel in CI. Same set
+  // either way (verified in catalog.test.js); this is a resolution
+  // fallback, not a second source of truth. Order differs between the two
+  // paths and does not matter — referenceResolver sorts by name.
+  const barrelPath = path.resolve(root, cfg.barrel);
+  const exported = existsSync(barrelPath) ? readBarrel(barrelPath) : Object.keys(classified);
+
   const components = exported
     .filter((name) => classified[name]?.kind === 'component')
     .map((name) => ({ name, slug: toSlug(name) }));
@@ -82,7 +100,9 @@ export function loadCatalog(platform = 'web') {
 export function packageNameForPlatform(platform) {
   const name = PACKAGE_NAME[platform];
   if (!name) {
-    throw new Error(`Unsupported platform "${platform}". Available: ${Object.keys(PACKAGE_NAME).join(', ')}.`);
+    throw new Error(
+      `Unsupported platform "${platform}". Available: ${Object.keys(PACKAGE_NAME).join(', ')}.`
+    );
   }
   return name;
 }

package/src/adopt/foreignDiscoveryResolver.js

@@ -0,0 +1,276 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import fg from 'fast-glob';
+import postcss from 'postcss';
+
+import { getForeignSystem } from './foreignSystemConfig.js';
+import { parseSource } from './parseSource.js';
+
+const DEFAULT_IGNORE = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.next/**',
+  '**/coverage/**',
+  '**/storybook-static/**',
+  '**/.storybook*/**',
+];
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function depNames(pkg) {
+  return new Set([
+    ...Object.keys(pkg?.dependencies || {}),
+    ...Object.keys(pkg?.devDependencies || {}),
+    ...Object.keys(pkg?.peerDependencies || {}),
+  ]);
+}
+
+/**
+ * Package detection — mirrors targetDiscovery.js's hasDirectStkDep() shape,
+ * but a foreign system needs two signals rather than one dependency
+ * prefix: a copy-paste system like shadcn is never itself an npm
+ * dependency, so its primary signal is a config file written by its own
+ * init CLI (components.json), with the wrapped dependencies it generates
+ * (depFallback, e.g. @radix-ui/*) only as corroborating evidence.
+ */
+export function detectPackage(root, ignore, system) {
+  const configFiles = fg.sync(
+    system.packageDetect.configFiles.map((f) => `**/${f}`),
+    { cwd: root, ignore: [...DEFAULT_IGNORE, ...ignore], absolute: true }
+  );
+
+  const depEvidence = [];
+  if (system.packageDetect.depFallback?.length) {
+    const pkgFiles = fg.sync(['**/package.json'], {
+      cwd: root,
+      ignore: [...DEFAULT_IGNORE, ...ignore],
+      absolute: true,
+    });
+    for (const pf of pkgFiles) {
+      const pkg = readJson(pf);
+      if (!pkg) continue;
+      for (const dep of depNames(pkg)) {
+        if (system.packageDetect.depFallback.some((re) => re.test(dep))) {
+          depEvidence.push({ file: path.relative(root, pf), dep });
+        }
+      }
+    }
+  }
+
+  return {
+    detected: configFiles.length > 0 || depEvidence.length > 0,
+    configFiles: configFiles.map((f) => path.relative(root, f)),
+    depEvidence,
+  };
+}
+
+/**
+ * True when a node's value is a real component implementation — a
+ * function/arrow expression, or a forwardRef(...)/memo(...) call wrapping
+ * one — never a bare filename match.
+ */
+function isComponentValue(node) {
+  if (!node) return false;
+  if (node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') return true;
+  if (node.type === 'CallExpression') {
+    const { callee } = node;
+    const calleeName =
+      callee.type === 'Identifier'
+        ? callee.name
+        : callee.type === 'MemberExpression' && callee.property.type === 'Identifier'
+          ? callee.property.name
+          : null;
+    if (calleeName === 'forwardRef' || calleeName === 'memo') {
+      return node.arguments.some((arg) => isComponentValue(arg));
+    }
+  }
+  return false;
+}
+
+/**
+ * True when the file's AST has a real component export — a named or
+ * default export that's a function declaration, or an isComponentValue()
+ * expression. The spike's own regex approach counted type-only
+ * declarations as components on other systems; this is where that
+ * discipline actually matters, since shadcn's directory-listing
+ * enumeration mode would otherwise trust the filename alone.
+ *
+ * shadcn's own generator never inlines the export — every real component
+ * file declares locally (`const Button = React.forwardRef(...)`) and
+ * exports by specifier at the bottom (`export { Button, buttonVariants }`).
+ * A live run against shadcn-ui/taxonomy caught this: the inline-only checks
+ * above matched 1 of 37 real components/ui files (only Toaster, which
+ * happens to use `export function Toaster()` directly). So this also
+ * indexes top-level function/variable declarations by name and resolves
+ * bare `export { Name }` specifiers against that index.
+ */
+function hasComponentExport(ast) {
+  const localDeclarations = new Map();
+  for (const node of ast.program.body) {
+    if (node.type === 'FunctionDeclaration' && node.id) {
+      localDeclarations.set(node.id.name, node);
+    }
+    if (node.type === 'VariableDeclaration') {
+      for (const decl of node.declarations) {
+        if (decl.id.type === 'Identifier') localDeclarations.set(decl.id.name, decl.init);
+      }
+    }
+  }
+
+  for (const node of ast.program.body) {
+    if (node.type === 'ExportDefaultDeclaration') {
+      if (node.declaration.type === 'FunctionDeclaration') return true;
+      if (isComponentValue(node.declaration)) return true;
+    }
+    if (node.type === 'ExportNamedDeclaration') {
+      if (node.declaration?.type === 'FunctionDeclaration') return true;
+      if (node.declaration?.type === 'VariableDeclaration') {
+        for (const decl of node.declaration.declarations) {
+          if (isComponentValue(decl.init)) return true;
+        }
+      }
+      if (!node.declaration) {
+        for (const specifier of node.specifiers) {
+          if (specifier.type !== 'ExportSpecifier') continue;
+          const localName = specifier.local.name;
+          const local = localDeclarations.get(localName);
+          if (!local) continue;
+          if (local.type === 'FunctionDeclaration') return true;
+          if (isComponentValue(local)) return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Component enumeration — walks for componentDir matches (e.g.
+ * components/ui), then parses each .tsx/.jsx directly inside and keeps
+ * only files with a real component export. This is literally reading a
+ * conventional folder shadcn always writes to, not import-usage detection
+ * — a consumer who renamed or restructured that folder produces zero
+ * components here, not a false "clean" signal (surfaced via
+ * unresolvedFiles for files that fail to parse at all).
+ */
+function enumerateComponents(root, ignore, system) {
+  const { parentName, dirName } = system.componentDir;
+  const dirs = fg.sync([`**/${parentName}/${dirName}`], {
+    cwd: root,
+    ignore: [...DEFAULT_IGNORE, ...ignore],
+    absolute: true,
+    onlyDirectories: true,
+  });
+
+  const components = [];
+  const unresolvedFiles = [];
+
+  for (const dir of dirs) {
+    const files = fg.sync(['*.tsx', '*.jsx'], { cwd: dir, absolute: true });
+    for (const file of files) {
+      let code;
+      try {
+        code = readFileSync(file, 'utf-8');
+      } catch {
+        continue;
+      }
+      let ast;
+      try {
+        ast = parseSource(code, file);
+      } catch {
+        unresolvedFiles.push(path.relative(root, file));
+        continue;
+      }
+      if (!hasComponentExport(ast)) continue;
+      components.push({
+        name: path.basename(file, path.extname(file)),
+        file: path.relative(root, file),
+      });
+    }
+  }
+
+  return { componentDirs: dirs.map((d) => path.relative(root, d)), components, unresolvedFiles };
+}
+
+/**
+ * Token source detection — postcss.parse() over every .css file, walking
+ * Declaration nodes for a custom property matching the system's
+ * markerVars. Reuses the exact postcss dependency and parse call
+ * tokenAliasResolver.js already makes, rather than a second hand-rolled
+ * CSS scanner. Token NAMES here are a shadcn convention (--background/
+ * --primary/--radius inside a :root block in globals.css), not enforced
+ * by any package.
+ */
+function detectTokenSource(root, ignore, system) {
+  const cssFiles = fg.sync(['**/*.css'], {
+    cwd: root,
+    ignore: [...DEFAULT_IGNORE, ...ignore],
+    absolute: true,
+  });
+  const markerSet = new Set(system.tokenSource.markerVars);
+  const matches = [];
+
+  for (const file of cssFiles) {
+    let src;
+    try {
+      src = readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = postcss.parse(src, { from: file });
+    } catch {
+      continue;
+    }
+    let hit = false;
+    parsed.walkDecls((decl) => {
+      if (decl.prop.startsWith('--') && markerSet.has(decl.prop)) hit = true;
+    });
+    if (hit) matches.push(path.relative(root, file));
+  }
+
+  return { detected: matches.length > 0, files: matches };
+}
+
+/**
+ * Layer 1 of "Version B" (ADOPTION_APP_PLAN.md §10 decision #25) — static,
+ * source-only discovery of a foreign design system's shape, the same
+ * no-install/no-registry constraint every adopt/ resolver already operates
+ * under for Stark itself. Not merged into runAdopt's per-target Stark-
+ * adoption shape: this answers a different question ("what does this
+ * repo's OWN design system look like") and gets its own CLI command
+ * (stark-cli scan-foreign) rather than a new key inside "adopt".
+ */
+export function resolveForeignDiscovery(root, systemId, { ignore = [] } = {}) {
+  const system = getForeignSystem(systemId);
+  if (system.distribution !== 'copy-paste') {
+    throw new Error(
+      `resolveForeignDiscovery only supports 'copy-paste' distribution systems (got "${systemId}" — distribution: "${system.distribution}"). ` +
+      `Use resolveInstalledPackageDiscovery for installed-package systems instead.`
+    );
+  }
+  const packageDetection = detectPackage(root, ignore, system);
+  const { componentDirs, components, unresolvedFiles } = enumerateComponents(root, ignore, system);
+  const tokenSource = detectTokenSource(root, ignore, system);
+
+  return {
+    system: system.id,
+    root,
+    packageDetected: packageDetection.detected,
+    evidence: { configFiles: packageDetection.configFiles, depEvidence: packageDetection.depEvidence },
+    componentDirs,
+    components,
+    unresolvedFiles,
+    tokenFile: tokenSource.files[0] ?? null,
+    tokenSource,
+  };
+}

package/src/adopt/foreignPropSchemaResolver.js

@@ -0,0 +1,134 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { parseSource } from './parseSource.js';
+
+function typeAnnotationToString(node) {
+  if (!node) return 'unknown';
+  switch (node.type) {
+    case 'TSStringKeyword':
+      return 'string';
+    case 'TSNumberKeyword':
+      return 'number';
+    case 'TSBooleanKeyword':
+      return 'boolean';
+    case 'TSAnyKeyword':
+      return 'any';
+    case 'TSVoidKeyword':
+      return 'void';
+    case 'TSFunctionType':
+      return 'function';
+    case 'TSArrayType':
+      return `${typeAnnotationToString(node.elementType)}[]`;
+    case 'TSTypeReference':
+      return node.typeName.type === 'Identifier' ? node.typeName.name : 'unknown';
+    case 'TSUnionType':
+      return node.types.map(typeAnnotationToString).join(' | ');
+    case 'TSLiteralType':
+      return node.literal.type === 'StringLiteral' ? `"${node.literal.value}"` : String(node.literal.value ?? 'literal');
+    default:
+      return node.type.replace(/^TS/, '').replace(/Keyword$/, '').toLowerCase() || 'unknown';
+  }
+}
+
+/**
+ * Extracts { name, type, optional } members from a TSInterfaceDeclaration
+ * body or a TSTypeAliasDeclaration whose right-hand side is a literal
+ * object shape. Returns null when the declaration isn't a literal shape at
+ * all (e.g. `type CardProps = ComponentProps<'div'>`) — that's a real
+ * "unreachable" case, not zero props.
+ */
+function membersFromDeclaration(node) {
+  const members =
+    node.type === 'TSInterfaceDeclaration'
+      ? node.body.body
+      : node.typeAnnotation?.type === 'TSTypeLiteral'
+        ? node.typeAnnotation.members
+        : null;
+  if (!members) return null;
+
+  return members
+    .filter((m) => m.type === 'TSPropertySignature')
+    .map((m) => ({
+      name: m.key.type === 'Identifier' ? m.key.name : m.key.type === 'StringLiteral' ? m.key.value : null,
+      type: typeAnnotationToString(m.typeAnnotation?.typeAnnotation),
+      optional: Boolean(m.optional),
+    }))
+    .filter((m) => m.name !== null);
+}
+
+/**
+ * Finds the file's own `${Component}Props` interface/type — case-
+ * insensitive against the component name, since shadcn filenames are
+ * lowercase (button.tsx) while the exported type is capitalized
+ * (ButtonProps). Falls back to the only Props-suffixed declaration in the
+ * file when exactly one exists, since some components alias the shape
+ * under a name that doesn't literally prefix-match the filename — but
+ * never guesses among multiple candidates.
+ */
+function findPropsDeclaration(ast, componentName) {
+  const candidates = [];
+  for (const node of ast.program.body) {
+    const decl = node.type === 'ExportNamedDeclaration' ? node.declaration : node;
+    if (!decl) continue;
+    if (decl.type === 'TSInterfaceDeclaration' && /Props$/.test(decl.id.name)) candidates.push(decl);
+    if (decl.type === 'TSTypeAliasDeclaration' && /Props$/.test(decl.id.name)) candidates.push(decl);
+  }
+  if (candidates.length === 0) return null;
+
+  const prefixMatch = candidates.find((c) => c.id.name.toLowerCase() === `${componentName.toLowerCase()}props`);
+  if (prefixMatch) return prefixMatch;
+  return candidates.length === 1 ? candidates[0] : null;
+}
+
+/**
+ * Layer 2 of "Version B" (ADOPTION_APP_PLAN.md §10 decision #25) —
+ * shadcn-only for Phase 1, since it's the one system where the B1 spike
+ * found real prop types reachable from repo source alone (copy-paste
+ * distribution, no node_modules boundary). Does the spike's own
+ * hasExplicitPropsType regex check for real, via AST, instead of a
+ * boolean. Deliberately has no installed-package branch (Phase 2,
+ * MUI-shaped) — that stays entirely absent rather than a stub that always
+ * returns reachable:false with no caller.
+ */
+export function resolvePropSchema(root, systemId, components) {
+  const sampled = components.map(({ name, file }) => {
+    const absFile = path.isAbsolute(file) ? file : path.join(root, file);
+    let code;
+    try {
+      code = readFileSync(absFile, 'utf-8');
+    } catch {
+      return { component: name, file, reachable: false, reason: 'file not readable' };
+    }
+    let ast;
+    try {
+      ast = parseSource(code, absFile);
+    } catch {
+      return { component: name, file, reachable: false, reason: 'parse error' };
+    }
+
+    const declaration = findPropsDeclaration(ast, name);
+    if (!declaration) {
+      return { component: name, file, reachable: false, reason: 'no Props interface/type found' };
+    }
+
+    const props = membersFromDeclaration(declaration);
+    if (props === null) {
+      return {
+        component: name,
+        file,
+        reachable: false,
+        reason: `${declaration.id.name} isn't a literal object shape (e.g. aliases ComponentProps<...>)`,
+      };
+    }
+
+    return { component: name, file, reachable: true, typeName: declaration.id.name, props };
+  });
+
+  return {
+    system: systemId,
+    root,
+    reachableFromRepoAlone: true,
+    sampled,
+  };
+}