@starklab/stark-mcp 0.1.0

package/src/cli.js

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+import path from 'node:path';
+
+import {
+  listComponents,
+  getComponentUsage,
+  getComponentProps,
+  buildManifest,
+  ejectComponent,
+} 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 { resolveRnTokenAliases } from './adopt/rnTokenAliasResolver.js';
+import { resolveRnTailwindTokens } from './adopt/rnTailwindResolver.js';
+import { discoverTargets, workspacePackageMap } from './adopt/targetDiscovery.js';
+
+function print(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function fail(message) {
+  console.error(message);
+  process.exitCode = 1;
+}
+
+function hasFlag(args, name) {
+  return args.includes(`--${name}`);
+}
+
+function flagValue(args, name, fallback) {
+  const prefix = `--${name}=`;
+  const arg = args.find(a => a.startsWith(prefix));
+  return arg ? arg.slice(prefix.length) : fallback;
+}
+
+// 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) {
+  const references = resolveReferences(root, { platform, ignore });
+  const wrappers = resolveWrappers(root, { platform, ignore, workspacePackages });
+  // CSS custom properties and Tailwind utility classes have no RN
+  // equivalent — both resolvers only run for the web platform.
+  const tokenAliases = platform === 'web' ? resolveTokenAliases(root, { platform, ignore }) : null;
+  const tailwind = platform === 'web' ? resolveTailwindTokens(root, { platform, ignore }) : null;
+  // prop-mapping/ is flat, with no rn/ subdirectory — there is no artifact
+  // to validate an RN prop against, so metric 6 only runs on web.
+  const propApi = platform === 'web' ? resolvePropApi(root, { platform, ignore }) : null;
+  // The RN JS-object token indirection resolver is the inverse: it only
+  // makes sense for the native platform (see rnTokenAliasResolver.js).
+  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 {
+    ...references,
+    wrappers: wrappers.wrappers,
+    byComponent: wrappers.byComponent,
+    contradictions: wrappers.contradictions,
+    unresolvedDeclarations: wrappers.unresolvedDeclarations,
+    provenanceTriple: wrappers.provenanceTriple,
+    dominionConfigFound: wrappers.dominionConfigFound,
+    tokenAliases,
+    tailwind,
+    propApi,
+    rnTokenAliases,
+    rnTailwind,
+  };
+}
+
+const HELP = `stark-cli — query the Stark design system catalog from the terminal
+
+Usage:
+  stark-cli list
+  stark-cli usage <Component>
+  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 targets [path]
+
+Options:
+  --platform=<web|native>   Target platform for "props", "eject", and "adopt" (default: web)
+  --tokens                  Include component token JSON in "props" output
+  --out=<dir>               Where to copy the component source (default: ./stark-eject/<Component>)
+  --force                   Overwrite the output directory if it already exists and isn't empty
+  --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
+
+"eject --platform=native" copies from @starklab/stk-react-native
+instead of @starklab/stk-components.
+
+"adopt [path]" scans a consumer repo (default: current directory) for
+references to catalog components and reports usage counts per component,
+classified by how certain each reference is (jsx/createElement/hoc are
+counted usages; indirect needs review; reexport isn't a usage). Every
+catalog component is reported, including ones with zero references —
+never derive the component list from the scan alone.
+
+It also resolves the consumer's own wrapper components (e.g. a local
+MyButton that renders <Button/>) down to the catalog component each one
+ultimately wraps, classifies how faithfully each wrapper passes props
+through (transparent/constraining/augmenting/divergent), and counts how
+often each wrapper is itself used — reported under "wrappers" and rolled
+up per-component under "byComponent". A dominion.config.json at the repo
+root ({"wrappers": {"<path>": "<ComponentName>"}}) fills in wrappers
+auto-detection couldn't resolve; it never overrides a contradicting
+auto-detected terminal (see "contradictions" in the output).
+
+On the web platform, "adopt" also resolves the consumer's own CSS custom-
+property alias graph (e.g. --app-primary: var(--stk-surface-brand-1-default))
+transitively, so an aliased token counts as adopted rather than absent —
+reported under "tokenAliases". Each consumer property is classified
+conformant / drift (aliases a raw value) / broken (undefined or cyclic),
+or partial-conformance when the same property resolves differently under
+different selectors (e.g. :root vs a theme override) — never collapsed to
+one dominant scope. Findings also flag alias chains through a primitive
+token (layer-violation), chains deeper than 3 hops, and raw-value var()
+fallbacks (info-level: works today, silently hardcodes if the aliased
+property is ever renamed). "tokenAliases.report" gives the three headline
+numbers — direct / aliased / unresolved — never a single collapsed score.
+Not run for --platform=native (CSS custom properties have no RN
+equivalent).
+
+Also on the web platform, "adopt" resolves Tailwind's own indirection layer:
+a v4 CSS "@theme{}" block or a v3 "tailwind.config.{js,cjs,mjs,ts}"
+theme.extend.colors map. A utility class like "bg-primary" has no var() at
+its call site, so tokenAliasResolver alone can't see it — tailwind resolves
+the theme key back through the same alias graph and scans JSX/TSX
+"className"/"class" attributes for statically-known utility usages,
+reported under "tailwind". Variant prefixes (hover:, dark:, arbitrary
+[&:hover]:) are stripped before matching; an arbitrary-value var() utility
+like "bg-[var(--stk-surface-brand-1-strong)]" is classified "direct", same
+as a literal var() call site. Utility classes that don't correspond to a
+theme key the consumer declared (Tailwind's own default palette, e.g.
+"bg-red-500") are out of scope, not counted as violations. Dynamic
+className expressions (clsx(), ternaries, interpolated templates) aren't
+statically resolvable and are skipped.
+
+Detection is always cheap, resolution isn't: if no Tailwind config or
+@theme block is found at all, "tailwind.detected" is false and "report" is
+null rather than a fabricated 0% score. If Tailwind is detected but no
+theme entries could be statically extracted (e.g. a dynamic/function-based
+v3 config), "tailwind.themeParseIncomplete" is true and "report" is again
+null — never scored low just because resolution, not detection, hit a
+wall. Not run for --platform=native (Tailwind utility classes have no RN
+equivalent).
+
+Also on the web platform, "adopt" validates every JSX call site of a
+catalog component against that component's own
+prop-mapping/components/<slug>.mapping.json — the legal prop surface
+already used to keep Storybook and Figma in sync — reported under
+"propApi". Four checks: an enum prop set to a value outside its declared
+"values" (invalid-enum-value, critical), a prop marked "deprecated" in the
+mapping still passed at a call site (deprecated-prop-passed, warning), a
+prop marked "required" missing from a call site (required-prop-missing,
+critical, unless the element also spreads props ({...rest}), which could
+forward it dynamically and is left unresolved rather than flagged), and
+"className"/"style" passed to a component whose contract is token-driven
+styling (style-escape-hatch, warning — a visible, intentional escape hatch,
+so lower severity than an invalid value). A dynamic prop value
+(variant={someVar}) is never scored valid or invalid, only unresolved, same
+rule as every other resolver. "propApi.report" gives the three headline
+numbers — valid / invalid / unresolved — computed only from the two checks
+with a real valid population (enum values, required props); the
+deprecated/style-escape-hatch checks only ever produce findings, never a
+"valid" row, so they sit outside that ledger the same way tokenAliases'
+raw-fallback/layer-violation findings do. "required"/"deprecated" are
+optional propMapEntry fields (packages/stk/prop-mapping/schema.json) that
+no shipped mapping file sets yet, so those two checks currently report zero
+findings against real data — an honest "not yet authored" state, not a
+missing feature; population is a separate, later pass. Not run for
+--platform=native (prop-mapping/ has no RN equivalent) — metric 6 is a
+visible "n/a" there, never an implicit zero.
+
+On the native platform, "adopt" instead resolves the consumer's own JS-
+object token indirection — RN has no CSS custom properties, so the
+indirection is a local const or object property instead of var(), e.g.
+"const theme = { primary: stkSurfaceBrand1Strong }" or
+"const primary = stkSurfaceBrand1Strong". Reported under "rnTokenAliases"
+with the same shape as "tokenAliases": conformant / drift (aliases a raw
+literal) / broken (undefined or foreign import, or a cycle), findings for
+layer-violation and alias chains deeper than 3 hops, and a three-number
+"report" (direct / aliased / unresolved). A usage site whose containing
+object has no static origin (e.g. a "const t = useTokens()" hook return)
+is still classified "direct" with "heuristic: true" when the accessed
+property name is an unambiguous Stark RN token name — a name match, never
+a value match. If no file imports from a @starklab/stk RN token
+package (rn, rn-spacing, rn-typography, rn-easing, rn-shadows, rn-dark) at
+all, "rnTokenAliases.detected" is false and "report" is null, same
+detection-first rule as "tailwind". Unlike the web resolvers, this one is
+static-only — there is no getComputedStyle()-equivalent runtime oracle on
+React Native to reconcile against — so "rnTokenAliases.confidence" is
+always "uncertain" on a detected result. Not run for --platform=web (CSS
+var()/Tailwind classes are the web analog).
+
+Also on the native platform, "adopt" resolves NativeWind — the one real
+Tailwind-syntax library on React Native ("className" props via a Babel
+transform, built on Tailwind's own config/theming). RN has no CSS custom
+properties, so a NativeWind consumer can only alias a Stark token by
+importing the RN token constant directly into tailwind.config.{js,cjs,mjs,ts}
+and referencing it as a JS expression (an identifier or a single-hop member
+access) — never var(), since there's no DOM/CSS runtime on RN to resolve
+that against. Reported under "rnTailwind" with the same shape as "tailwind":
+"properties" (theme.colors entries classified conformant/drift/broken),
+"usages" (className utility occurrences resolved back through the theme
+map), findings for layer-violation and alias chains deeper than 3 hops, and
+a three-number "report" (direct / aliased / unresolved) — "direct" is
+always 0 here, since there's no var()-arbitrary-value escape hatch on RN.
+Colors-only (theme.colors / theme.extend.colors), matching the web v3
+config parser's actual coverage; no v4 CSS "@theme" support (a CSS file
+can't import a JS token constant). Detection requires a genuine NativeWind
+signal — a "nativewind" package.json dependency, a "nativewind/babel" Babel
+preset, or a "withNativeWind" Metro config wrapper — a bare
+tailwind.config.js alone doesn't count, since it could belong to an
+unrelated web app elsewhere in the same monorepo; "rnTailwind.detected" is
+false and "report" is null when none of those are found, and
+"rnTailwind.themeParseIncomplete" is true (report still null) when
+NativeWind is detected but no theme.colors entries could be statically
+resolved. Not run for --platform=web (Tailwind's own web resolver is the
+analog).
+
+"stark-cli targets [path]" and "adopt --all-targets" address
+ADOPTION_APP_PLAN.md §3e: a product is rarely one repo passed as a single
+[path] — it's a monorepo of workspace packages, only some of which
+actually depend on the design system. "targets" discovers every workspace
+target under [path] (from package.json#workspaces, falling back to
+pnpm-workspace.yaml, falling back to a scan for any nested package.json if
+neither manifest exists) and classifies each one in or out of scope: a
+target with no dependency on @starklab/stk*, direct or via a
+workspace sibling, is out of scope, not scored 0%. Excluded targets that
+still depend on a UI framework (React, React Native, etc.) are surfaced
+separately under "opportunities" — the most valuable excluded rows,
+which must never be read as zeros. A dominion.config.json
+{"targets": {"forceInclude": ["<dir>"], "forceExclude": {"<dir>": "<reason>"}}}
+overrides the automatic classification asymmetrically: force-include is
+unrestricted, force-exclude always carries a recorded reason shown beside
+the excluded count.
+
+"adopt --all-targets [path]" runs the full "adopt" scan (references,
+wrappers, tokenAliases, tailwind, propApi, etc.) once per in-scope target
+discovered under [path], reported under "targets" keyed by each target's
+directory, alongside the same "excluded" and "opportunities" lists
+"targets" reports on its own. Every per-target wrapper resolution is given
+the full set of discovered workspace package names, so a wrapper that
+imports a *sibling* workspace package (e.g. an app importing its own repo's
+internal @acme/ui) resolves into that sibling's real source instead of
+terminating at the workspace boundary as an ordinary third-party import —
+without this, a shared internal UI package would score near-0% in every
+consuming target and 100% in the one that defines it, the same inverted-
+result problem catalog left-joining exists to prevent, recurring one level
+up at package granularity.
+`;
+
+const [, , command, ...rest] = process.argv;
+
+switch (command) {
+  case 'list':
+    print(listComponents());
+    break;
+
+  case 'usage': {
+    const [component] = rest;
+    if (!component) {
+      fail('Usage: stark-cli usage <Component>');
+      break;
+    }
+    try {
+      print(getComponentUsage(component));
+    } catch (err) {
+      fail(err.message);
+    }
+    break;
+  }
+
+  case 'props': {
+    const [component] = rest;
+    if (!component) {
+      fail('Usage: stark-cli props <Component> [--platform=web|native] [--tokens]');
+      break;
+    }
+    const platform = flagValue(rest, 'platform', 'web');
+    const includeTokens = hasFlag(rest, 'tokens');
+    try {
+      print(getComponentProps(component, platform, includeTokens));
+    } catch (err) {
+      fail(err.message);
+    }
+    break;
+  }
+
+  case 'manifest':
+    print(buildManifest());
+    break;
+
+  case 'eject': {
+    const [component] = rest;
+    if (!component) {
+      fail('Usage: stark-cli eject <Component> [--platform=web|native] [--out=<dir>] [--force]');
+      break;
+    }
+    const platform = flagValue(rest, 'platform', 'web');
+    const outDir = flagValue(rest, 'out', undefined);
+    const force = hasFlag(rest, 'force');
+    try {
+      print(ejectComponent(component, { platform, outDir, force }));
+    } catch (err) {
+      fail(err.message);
+    }
+    break;
+  }
+
+  case 'adopt': {
+    const [maybePath] = rest;
+    const target = maybePath && !maybePath.startsWith('--') ? maybePath : '.';
+    const root = path.resolve(process.cwd(), target);
+    const platform = flagValue(rest, 'platform', 'web');
+    const ignoreArg = flagValue(rest, 'ignore', '');
+    const ignore = ignoreArg ? ignoreArg.split(',').map(s => s.trim()).filter(Boolean) : [];
+
+    if (hasFlag(rest, 'all-targets')) {
+      try {
+        const discovery = discoverTargets(root);
+        const workspacePackages = workspacePackageMap(discovery);
+        const targets = {};
+        for (const t of discovery.inScope) {
+          const targetRoot = path.join(discovery.root, t.dir);
+          targets[t.dir] = runAdopt(targetRoot, platform, ignore, workspacePackages);
+        }
+        print({
+          root: discovery.root,
+          manifestSource: discovery.manifestSource,
+          monorepoTooling: discovery.monorepoTooling,
+          targets,
+          excluded: discovery.excluded,
+          opportunities: discovery.opportunities,
+        });
+      } catch (err) {
+        fail(err.message);
+      }
+      break;
+    }
+
+    try {
+      print(runAdopt(root, platform, ignore));
+    } catch (err) {
+      fail(err.message);
+    }
+    break;
+  }
+
+  case 'targets': {
+    const [maybePath] = rest;
+    const target = maybePath && !maybePath.startsWith('--') ? maybePath : '.';
+    const root = path.resolve(process.cwd(), target);
+    try {
+      print(discoverTargets(root));
+    } catch (err) {
+      fail(err.message);
+    }
+    break;
+  }
+
+  case undefined:
+  case '--help':
+  case '-h':
+  case 'help':
+    console.log(HELP);
+    break;
+
+  default:
+    fail(`Unknown command "${command}".\n\n${HELP}`);
+}

package/src/data.js

@@ -0,0 +1,267 @@
+import { createRequire } from 'node:module';
+import { readFileSync, readdirSync, existsSync, mkdirSync, copyFileSync } from 'node:fs';
+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';
+
+const require = createRequire(import.meta.url);
+
+export function stkRoot() {
+  return path.dirname(require.resolve('@starklab/stk/package.json'));
+}
+
+export function mappingDir(root = stkRoot()) {
+  return path.join(root, 'prop-mapping', 'components');
+}
+
+// Resolves @starklab/stk-components relative to the caller's own
+// project (cwd), not stark-mcp's own dependency tree — eject only makes sense
+// against the component library the consumer actually has installed.
+export function stkComponentsRoot(cwd = process.cwd()) {
+  return path.dirname(require.resolve('@starklab/stk-components/package.json', { paths: [cwd] }));
+}
+
+// Same idea as stkComponentsRoot, for the React Native port. RN component
+// dirs have a different shape (single .jsx, no .css, no .figma.tsx) but
+// ejectComponent's "copy every file in the source dir" logic already handles
+// that without a separate code path.
+export function stkReactNativeRoot(cwd = process.cwd()) {
+  return path.dirname(require.resolve('@starklab/stk-react-native/package.json', { paths: [cwd] }));
+}
+
+export function tokensDir(root = stkRoot()) {
+  return path.join(root, 'tokens', 'components');
+}
+
+// Mirrors the file-naming convention across prop-mapping/ and usage/:
+// PascalCase component names on disk as kebab-case ("TextInput" -> "text-input").
+export function toSlug(name) {
+  return String(name)
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+}
+
+function readJson(absPath) {
+  return JSON.parse(readFileSync(absPath, 'utf-8'));
+}
+
+function mappingFiles(dir) {
+  return readdirSync(dir).filter(f => f.endsWith('.mapping.json'));
+}
+
+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);
+      return {
+        name: mapping.component,
+        slug,
+        platforms: mapping.platforms ?? ['web'],
+        status: usage?.status ?? 'unknown',
+        description: usage?.description ?? null,
+        figmaUrl: usage?.figmaUrl ?? null,
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function getComponentUsage(component) {
+  const slug = toSlug(component);
+  const usage = loadUsage(slug);
+  if (!usage) {
+    throw new Error(
+      `No usage rules found for "${component}" (looked for slug "${slug}"). Call list_components to see valid names.`
+    );
+  }
+  return usage;
+}
+
+function findMappingFile(dir, slug) {
+  return mappingFiles(dir).find(f => toSlug(f.replace(/\.mapping\.json$/, '')) === slug);
+}
+
+// Component token JSON (tokens/components/{slug}.json) doesn't exist for pure
+// layout primitives (Container, Grid, Stack...) that carry no component-layer
+// tokens of their own — absence is expected, not an error.
+export function getComponentTokens(component) {
+  const slug = toSlug(component);
+  const file = path.join(tokensDir(), `${slug}.json`);
+  try {
+    return readJson(file);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+export function getComponentProps(component, platform = 'web', includeTokens = false) {
+  const dir = mappingDir();
+  const slug = toSlug(component);
+  const file = findMappingFile(dir, slug);
+  if (!file) {
+    throw new Error(
+      `No prop mapping found for "${component}" (looked for slug "${slug}"). Call list_components to see valid names.`
+    );
+  }
+  const mapping = readJson(path.join(dir, file));
+  const platforms = mapping.platforms ?? ['web'];
+  if (!platforms.includes(platform)) {
+    throw new Error(
+      `Component "${mapping.component}" does not support platform "${platform}". Available: ${platforms.join(', ')}.`
+    );
+  }
+  // Mirrors buildCatalogFromDir's platform-namespaced-vs-legacy-flat fallback.
+  const block = mapping[platform] ?? mapping;
+  const result = {
+    component: mapping.component,
+    figmaComponentSetName: mapping.figmaComponentSetName,
+    platform,
+    propMap: block.propMap ?? [],
+    ignore: block.ignore ?? [],
+  };
+  if (includeTokens) {
+    result.tokens = getComponentTokens(mapping.component);
+  }
+  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.
+export function buildManifest() {
+  const components = listComponents().map(({ name, slug, status, description, figmaUrl, platforms }) => {
+    let usage = null;
+    try {
+      usage = getComponentUsage(name);
+    } catch {
+      // no usage/*.usage.json for this component
+    }
+
+    const props = {};
+    for (const platform of ['web', 'native']) {
+      try {
+        const { propMap, ignore } = getComponentProps(name, platform);
+        props[platform] = { propMap, ignore };
+      } catch {
+        // component doesn't support this platform
+      }
+    }
+
+    return {
+      name,
+      slug,
+      status,
+      description,
+      figmaUrl,
+      platforms,
+      usage,
+      props,
+      tokens: getComponentTokens(name),
+    };
+  });
+
+  return {
+    generatedAt: new Date().toISOString(),
+    package: '@starklab/stk',
+    componentCount: components.length,
+    components,
+  };
+}
+
+export function getLayoutCatalog(platform = 'web') {
+  return buildCatalogFromDir(mappingDir(), { platform });
+}
+
+export function getLayoutSchema(component, platform = 'web') {
+  const slug = toSlug(component);
+  const catalog = getLayoutCatalog(platform);
+  const entry = catalog.find(c => toSlug(c.name) === slug);
+  if (!entry) {
+    throw new Error(
+      `No layoutSchema for "${component}" on platform "${platform}" — it may be an overlay/sub-component with no ` +
+        `standalone layout node, or the platform doesn't apply. Call get_layout_catalog to see what's available.`
+    );
+  }
+  return entry;
+}
+
+// `canvasCases` (the renderer's supported node types) is optional and defaults
+// to []. Omitting it silently skips the catalog<->renderer parity check inside
+// runConformance — real for external callers whose renderer isn't Stark's own
+// LayoutCanvas.jsx. Pass your own renderer's supported type list if you have one.
+export function validateLayout({ layout, intent = {}, platform = 'web', canvasCases = [] } = {}) {
+  const catalog = getLayoutCatalog(platform);
+  const findings = runConformance({ layout, intent, catalog, canvasCases });
+  return { findings, hasBlocking: hasBlocking(findings) };
+}
+
+export function getGenerationProtocol() {
+  return readJson(path.join(stkRoot(), 'generation-protocol.json'));
+}
+
+const EJECT_PACKAGES = {
+  web: { name: '@starklab/stk-components', resolve: stkComponentsRoot },
+  native: { name: '@starklab/stk-react-native', resolve: stkReactNativeRoot },
+};
+
+// Copies one component's source out of the installed component package
+// (@starklab/stk-components for web, @starklab/stk-react-native
+// for native) into the caller's own project, so they can customize it locally
+// without forking the whole library — at the cost of losing future upstream
+// fixes for that component. Mirrors Docusaurus's "swizzle"/eject: an escape
+// hatch for the rare case where the token/prop API genuinely can't express
+// what's needed.
+export function ejectComponent(component, { outDir, cwd = process.cwd(), force = false, platform = 'web' } = {}) {
+  const pkg = EJECT_PACKAGES[platform];
+  if (!pkg) {
+    throw new Error(`Unsupported platform "${platform}". Available: ${Object.keys(EJECT_PACKAGES).join(', ')}.`);
+  }
+
+  const match = listComponents().find(c => c.slug === toSlug(component));
+  if (!match) {
+    throw new Error(`Unknown component "${component}". Call list_components to see valid names.`);
+  }
+  const name = match.name;
+  if (!match.platforms.includes(platform)) {
+    throw new Error(`Component "${name}" does not support platform "${platform}". Available: ${match.platforms.join(', ')}.`);
+  }
+
+  let root;
+  try {
+    root = pkg.resolve(cwd);
+  } catch {
+    throw new Error(`Could not resolve "${pkg.name}" from ${cwd}. Install it first: npm install ${pkg.name}`);
+  }
+
+  const sourceDir = path.join(root, 'src', name);
+  if (!existsSync(sourceDir)) {
+    throw new Error(
+      `"${name}" has no source directory in the installed ${pkg.name} (looked in ${sourceDir}). ` +
+        `The installed version may be out of date.`
+    );
+  }
+
+  const target = path.resolve(cwd, outDir || path.join('stark-eject', name));
+  if (existsSync(target) && readdirSync(target).length > 0 && !force) {
+    throw new Error(`"${target}" already exists and is not empty. Pass force to overwrite.`);
+  }
+
+  // .figma.tsx is Code Connect metadata, not runtime source — an ejected
+  // component doesn't need it, and it may reference internal Figma node IDs.
+  const files = readdirSync(sourceDir).filter(f => !f.endsWith('.figma.tsx'));
+
+  mkdirSync(target, { recursive: true });
+  for (const file of files) {
+    copyFileSync(path.join(sourceDir, file), path.join(target, file));
+  }
+
+  return { component: name, platform, from: sourceDir, to: target, files };
+}