@primer/brand-mcp 0.0.0-20260626120119

package/README.md

@@ -0,0 +1,43 @@
+# @primer/brand-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that helps AI agents use **Primer Brand** (`@primer/react-brand`) correctly when building GitHub marketing and landing pages.
+
+It is a version-aware, `stdio` (local) server which reads the docs and metadata of your installed `@primer/react-brand` dependency.
+
+## Tools
+
+| Tool                     | What it does                                                                                                                      |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `primer_brand_setup`     | Framework-aware setup (Auto-installs `ThemeProvider`, Mona Sans fonts, styles, `'use client'` for RSC) - the parts agents forget. |
+| `primer_brand_component` | List components, or get one component's API: props, allowed values, sub-components, and examples.                                 |
+| `primer_brand_examples`  | Ranked, copy-and-adapt examples for a goal, taken from the library's own tested stories. Falls back to a default set.             |
+| `primer_brand_tokens`    | Resolve design tokens by intent (color, space, typography) to CSS variables and values.                                           |
+| `primer_brand_asset`     | Find Octicons (`@primer/octicons-react`) and Octovisuals (`@primer/octovisuals-react`) as code imports.                           |
+| `primer_brand_docs`      | Search and read Primer Brand guidance (principles, accessibility, getting started).                                               |
+| `primer_brand_review`    | Check generated JSX/CSS against the design system: unknown components, invalid props, hardcoded values, off-brand tells.          |
+
+## Getting started
+
+Requires Node.js >= 24.
+
+### VS Code
+
+```jsonc
+{
+  "servers": {
+    "Primer Brand": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@primer/brand-mcp@latest"]
+    }
+  }
+}
+```
+
+### Copilot CLI / other stdio clients
+
+Run the server with `npx @primer/brand-mcp@latest`.
+
+## License
+
+MIT

package/dist/brand/detect-framework.d.ts

@@ -0,0 +1,13 @@
+export type FrameworkId = 'next-app' | 'next-pages' | 'vite' | 'astro' | 'remix' | 'unknown';
+export interface FrameworkInfo {
+    id: FrameworkId;
+    label: string;
+    /** Uses React Server Components, so providers need a `'use client'` boundary. */
+    rsc: boolean;
+    projectDir: string | null;
+}
+/**
+ * Best-effort detection of the consumer's framework so setup guidance can be tailored
+ * (where providers go, whether a `'use client'` boundary is required, which style import to use).
+ */
+export declare function detectFramework(fromDir?: string): FrameworkInfo;

package/dist/brand/detect-framework.js

@@ -0,0 +1,48 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+/** Nearest `package.json` above `fromDir` that isn't inside `node_modules`. */
+function findProjectDir(fromDir) {
+    let dir = fromDir;
+    for (;;) {
+        if (!dir.split(sep).includes('node_modules') && existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function readDependencies(projectDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'));
+        return { ...parsed.dependencies, ...parsed.devDependencies };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Best-effort detection of the consumer's framework so setup guidance can be tailored
+ * (where providers go, whether a `'use client'` boundary is required, which style import to use).
+ */
+export function detectFramework(fromDir = process.cwd()) {
+    const projectDir = findProjectDir(fromDir);
+    if (!projectDir)
+        return { id: 'unknown', label: 'a React project', rsc: false, projectDir: null };
+    const deps = readDependencies(projectDir);
+    if (deps.next) {
+        const appRouter = existsSync(join(projectDir, 'app')) || existsSync(join(projectDir, 'src', 'app'));
+        return appRouter
+            ? { id: 'next-app', label: 'Next.js (App Router)', rsc: true, projectDir }
+            : { id: 'next-pages', label: 'Next.js (Pages Router)', rsc: false, projectDir };
+    }
+    if (deps['@remix-run/react'] || deps['@remix-run/node']) {
+        return { id: 'remix', label: 'Remix', rsc: false, projectDir };
+    }
+    if (deps.astro)
+        return { id: 'astro', label: 'Astro', rsc: false, projectDir };
+    if (deps.vite)
+        return { id: 'vite', label: 'Vite + React', rsc: false, projectDir };
+    return { id: 'unknown', label: 'a React project', rsc: false, projectDir };
+}
+//# sourceMappingURL=detect-framework.js.map

package/dist/brand/detect-framework.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-framework.js","sourceRoot":"","sources":["../../src/brand/detect-framework.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,SAAS,CAAA;AAChD,OAAO,EAAC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAC,MAAM,WAAW,CAAA;AAY5C,+EAA+E;AAC/E,SAAS,cAAc,CAAC,OAAe;IACrC,IAAI,GAAG,GAAG,OAAO,CAAA;IACjB,SAAS,CAAC;QACR,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;YAAE,OAAO,GAAG,CAAA;QACjG,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;QAC3B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAA;QAC/B,GAAG,GAAG,MAAM,CAAA;IACd,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,UAAkB;IAC1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAG/E,CAAA;QACD,OAAO,EAAC,GAAG,MAAM,CAAC,YAAY,EAAE,GAAG,MAAM,CAAC,eAAe,EAAC,CAAA;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB,OAAO,CAAC,GAAG,EAAE;IAC7D,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IAC1C,IAAI,CAAC,UAAU;QAAE,OAAO,EAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAC,CAAA;IAE/F,MAAM,IAAI,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAA;IACzC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;QACnG,OAAO,SAAS;YACd,CAAC,CAAC,EAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,sBAAsB,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,EAAC;YACxE,CAAC,CAAC,EAAC,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,wBAAwB,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAC,CAAA;IACjF,CAAC;IACD,IAAI,IAAI,CAAC,kBAAkB,CAAC,IAAI,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACxD,OAAO,EAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAC,CAAA;IAC9D,CAAC;IACD,IAAI,IAAI,CAAC,KAAK;QAAE,OAAO,EAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAC,CAAA;IAC5E,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,EAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAC,CAAA;IACjF,OAAO,EAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAC,CAAA;AAC1E,CAAC"}

package/dist/brand/docs-source.d.ts

@@ -0,0 +1,40 @@
+import type { Logger } from '../logger.js';
+import type { BrandInstall } from './resolve-install.js';
+/**
+ * One entry in the documentation table of contents (parsed from `llms.txt`).
+ */
+export interface DocEntry {
+    label: string;
+    /** Path relative to the docs root, e.g. `docs/components/Hero/index.md`. */
+    path: string;
+    description?: string;
+}
+export type DocOrigin = 'installed' | 'live' | 'none';
+export interface DocResult {
+    text: string;
+    origin: DocOrigin;
+    version: string | null;
+}
+/**
+ * Tiered documentation source.
+ *
+ * Resolution order, by design:
+ *   1. The bundled, version-pinned docs of the installed `@primer/react-brand` (authoritative,
+ *      offline, matches the consumer's version).
+ *   2. The live site's `llms.txt` / pages — best-effort enrichment for guidance that is not
+ *      bundled, bounded by a short timeout and cached.
+ *
+ * Version-sensitive facts never depend on the network; this only covers prose guidance.
+ */
+export interface DocsSource {
+    origin: DocOrigin;
+    version: string | null;
+    index(): Promise<DocEntry[]>;
+    read(path: string): Promise<DocResult | null>;
+}
+export declare function createDocsSource(brand: BrandInstall, logger: Logger): DocsSource;
+/**
+ * Parse the `llms.txt` markdown table of contents into structured entries.
+ * Lines look like: `- [Hero](docs/components/Hero/index.md): A prominent banner...`
+ */
+export declare function parseToc(markdown: string): DocEntry[];

package/dist/brand/docs-source.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, normalize, resolve, sep } from 'node:path';
+const SITE = 'https://primer.style/brand';
+const FETCH_TIMEOUT_MS = 2500;
+export function createDocsSource(brand, logger) {
+    const cache = new Map();
+    const hasLocalDocs = Boolean(brand.llmsPath && brand.docsDir);
+    const docsRoot = brand.docsDir ? dirname(brand.docsDir) : null;
+    async function fetchText(url) {
+        const cached = cache.get(url);
+        if (cached !== undefined)
+            return cached;
+        try {
+            const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+            if (!response.ok)
+                return null;
+            const text = await response.text();
+            cache.set(url, text);
+            return text;
+        }
+        catch (error) {
+            logger.debug(`live fetch failed for ${url}: ${error.message}`);
+            return null;
+        }
+    }
+    async function index() {
+        if (hasLocalDocs && brand.llmsPath) {
+            return parseToc(readFileSync(brand.llmsPath, 'utf8'));
+        }
+        const live = await fetchText(`${SITE}/llms.txt`);
+        return live ? parseToc(live) : [];
+    }
+    async function read(path) {
+        if (hasLocalDocs && docsRoot) {
+            const safe = safeJoin(docsRoot, path);
+            if (safe && existsSync(safe)) {
+                return { text: readFileSync(safe, 'utf8'), origin: 'installed', version: brand.version };
+            }
+        }
+        const live = await fetchText(`${SITE}/${path.replace(/^docs\//, '').replace(/\.md$/, '')}`);
+        if (live)
+            return { text: live, origin: 'live', version: null };
+        return null;
+    }
+    return {
+        origin: hasLocalDocs ? 'installed' : 'live',
+        version: brand.version,
+        index,
+        read,
+    };
+}
+/**
+ * Parse the `llms.txt` markdown table of contents into structured entries.
+ * Lines look like: `- [Hero](docs/components/Hero/index.md): A prominent banner...`
+ */
+export function parseToc(markdown) {
+    const entries = [];
+    const linkLine = /^- \[(.+?)\]\((.+?)\)(?::\s*(.*))?$/;
+    for (const raw of markdown.split('\n')) {
+        const match = linkLine.exec(raw.trim());
+        if (!match)
+            continue;
+        const [, label, path, description] = match;
+        if (!label || !path)
+            continue;
+        entries.push({ label, path, description: description?.trim() || undefined });
+    }
+    return entries;
+}
+/**
+ * Join a user-supplied doc path onto the docs root, refusing anything that escapes it.
+ * Prevents path traversal (e.g. `../../etc/passwd`) reaching the filesystem.
+ */
+function safeJoin(root, path) {
+    const target = resolve(join(root, normalize(path)));
+    const realRoot = realpathSync(root);
+    const prefix = realRoot.endsWith(sep) ? realRoot : `${realRoot}${sep}`;
+    if (target !== realRoot && !target.startsWith(prefix))
+        return null;
+    return target;
+}
+//# sourceMappingURL=docs-source.js.map

package/dist/brand/docs-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-source.js","sourceRoot":"","sources":["../../src/brand/docs-source.ts"],"names":[],"mappings":"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"}

package/dist/brand/resolve-assets.d.ts

@@ -0,0 +1,14 @@
+import type { CatalogAsset } from '../catalog/types.js';
+export interface InstalledAssets {
+    assets: CatalogAsset[];
+    sources: Array<{
+        module: string;
+        version: string | null;
+    }>;
+}
+/**
+ * Resolve the icon/illustration packages installed in the consumer's project and extract their
+ * exported names. This makes `primer_brand_asset` version-accurate: it reflects the Octicons/Octovisuals
+ * the project actually has, rather than the snapshot baked into the catalog at build time.
+ */
+export declare function resolveInstalledAssets(fromDir?: string): InstalledAssets;

package/dist/brand/resolve-assets.js

@@ -0,0 +1,101 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const ASSET_PACKAGES = [
+    { module: '@primer/octicons-react', kind: 'icon' },
+    { module: '@primer/octovisuals-react', kind: 'illustration' },
+];
+/** Walk up from `fromDir` to find an installed package directory. */
+function findPackageDir(packageName, fromDir) {
+    let dir = fromDir;
+    for (;;) {
+        const candidate = join(dir, 'node_modules', ...packageName.split('/'));
+        if (existsSync(join(candidate, 'package.json')))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function readVersion(packageDir) {
+    try {
+        return JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8')).version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Collect exported PascalCase const names from a package's `.d.ts` type declarations. Octicons
+ * declare their icons as `declare const AlertIcon: Icon` in a sibling file, so all `.d.ts` files
+ * in the package's output directory are scanned, not just `index.d.ts`.
+ */
+function exportedNames(packageDir) {
+    const names = new Set();
+    for (const sub of ['dist', 'lib', '.']) {
+        let entries;
+        try {
+            entries = readdirSync(join(packageDir, sub));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith('.d.ts'))
+                continue;
+            let source;
+            try {
+                source = readFileSync(join(packageDir, sub, entry), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            for (const match of source.matchAll(/(?:export\s+)?declare\s+const\s+([A-Z]\w+)/g)) {
+                if (match[1])
+                    names.add(match[1]);
+            }
+            for (const match of source.matchAll(/export\s+const\s+([A-Z]\w+)/g)) {
+                if (match[1])
+                    names.add(match[1]);
+            }
+            for (const match of source.matchAll(/export\s*\{([^}]*)\}/g)) {
+                for (const part of (match[1] ?? '').split(',')) {
+                    const ident = part
+                        .trim()
+                        .split(/\s+as\s+/)
+                        .pop()
+                        ?.trim();
+                    if (ident && /^[A-Z]\w+$/.test(ident))
+                        names.add(ident);
+                }
+            }
+        }
+    }
+    return [...names];
+}
+function keepName(name, kind) {
+    // Octovisuals components are also named `...Icon`, so they are kept by package, not suffix.
+    return kind === 'icon' ? name.endsWith('Icon') : /^[A-Z]/.test(name) && !/(Props|Type|Metadata)$/.test(name);
+}
+/**
+ * Resolve the icon/illustration packages installed in the consumer's project and extract their
+ * exported names. This makes `primer_brand_asset` version-accurate: it reflects the Octicons/Octovisuals
+ * the project actually has, rather than the snapshot baked into the catalog at build time.
+ */
+export function resolveInstalledAssets(fromDir = process.cwd()) {
+    const assets = [];
+    const sources = [];
+    for (const { module, kind } of ASSET_PACKAGES) {
+        const packageDir = findPackageDir(module, fromDir);
+        if (!packageDir)
+            continue;
+        const names = exportedNames(packageDir).filter(name => keepName(name, kind));
+        if (names.length === 0)
+            continue;
+        sources.push({ module, version: readVersion(packageDir) });
+        for (const name of names)
+            assets.push({ name, module, kind });
+    }
+    return { assets, sources };
+}
+//# sourceMappingURL=resolve-assets.js.map

package/dist/brand/resolve-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-assets.js","sourceRoot":"","sources":["../../src/brand/resolve-assets.ts"],"names":[],"mappings":"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"}

package/dist/brand/resolve-install.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Information about the `@primer/react-brand` install discovered in the consumer's project.
+ * This is what makes the server version-aware: tools prefer the docs and version of the
+ * package the project actually depends on.
+ */
+export interface BrandInstall {
+    found: boolean;
+    version: string | null;
+    packageDir: string | null;
+    /** Bundled version-pinned docs directory, when the installed version ships one. */
+    docsDir: string | null;
+    /** Bundled `llms.txt` table of contents, when present. */
+    llmsPath: string | null;
+}
+/**
+ * Walk up from `fromDir` looking for `node_modules/@primer/react-brand`. We resolve from the
+ * working directory (not from this server's own location) so that, when launched inside a
+ * consumer project, we read their installed version.
+ */
+export declare function resolveBrandInstall(fromDir?: string): BrandInstall;
+/**
+ * To properly disambiguate competing MCP libraries within Primer, we check if the project depends on `@primer/react` (the product UI library) but not Primer Brand.
+ * Used to gently steer agents that may have invoked the wrong design system's tools.
+ */
+export declare function looksLikeProductProject(fromDir?: string): boolean;

package/dist/brand/resolve-install.js

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const notFound = {
+    found: false,
+    version: null,
+    packageDir: null,
+    docsDir: null,
+    llmsPath: null,
+};
+/**
+ * Walk up from `fromDir` looking for `node_modules/@primer/react-brand`. We resolve from the
+ * working directory (not from this server's own location) so that, when launched inside a
+ * consumer project, we read their installed version.
+ */
+export function resolveBrandInstall(fromDir = process.cwd()) {
+    let dir = fromDir;
+    for (;;) {
+        const packageDir = join(dir, 'node_modules', '@primer', 'react-brand');
+        if (existsSync(join(packageDir, 'package.json'))) {
+            const docsDir = join(packageDir, 'docs');
+            const llmsPath = join(packageDir, 'llms.txt');
+            return {
+                found: true,
+                version: readVersion(join(packageDir, 'package.json')),
+                packageDir,
+                docsDir: existsSync(docsDir) ? docsDir : null,
+                llmsPath: existsSync(llmsPath) ? llmsPath : null,
+            };
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return notFound;
+        dir = parent;
+    }
+}
+/**
+ * To properly disambiguate competing MCP libraries within Primer, we check if the project depends on `@primer/react` (the product UI library) but not Primer Brand.
+ * Used to gently steer agents that may have invoked the wrong design system's tools.
+ */
+export function looksLikeProductProject(fromDir = process.cwd()) {
+    if (resolveBrandInstall(fromDir).found)
+        return false;
+    let dir = fromDir;
+    for (;;) {
+        if (existsSync(join(dir, 'node_modules', '@primer', 'react', 'package.json')))
+            return true;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}
+function readVersion(packageJsonPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+        return parsed.version ?? null;
+    }
+    catch {
+        // Unreadable manifest -> treat the version as unknown rather than failing discovery.
+        return null;
+    }
+}
+//# sourceMappingURL=resolve-install.js.map

package/dist/brand/resolve-install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-install.js","sourceRoot":"","sources":["../../src/brand/resolve-install.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,SAAS,CAAA;AAChD,OAAO,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,WAAW,CAAA;AAiBvC,MAAM,QAAQ,GAAiB;IAC7B,KAAK,EAAE,KAAK;IACZ,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,IAAI;IAChB,OAAO,EAAE,IAAI;IACb,QAAQ,EAAE,IAAI;CACf,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAkB,OAAO,CAAC,GAAG,EAAE;IACjE,IAAI,GAAG,GAAG,OAAO,CAAA;IACjB,SAAS,CAAC;QACR,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,CAAC,CAAA;QACtE,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;YACjD,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;YACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;YAC7C,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;gBACtD,UAAU;gBACV,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;gBAC7C,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI;aACjD,CAAA;QACH,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;QAC3B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,QAAQ,CAAA;QACnC,GAAG,GAAG,MAAM,CAAA;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAkB,OAAO,CAAC,GAAG,EAAE;IACrE,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC,KAAK;QAAE,OAAO,KAAK,CAAA;IACpD,IAAI,GAAG,GAAG,OAAO,CAAA;IACjB,SAAS,CAAC;QACR,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;YAAE,OAAO,IAAI,CAAA;QAC1F,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;QAC3B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,KAAK,CAAA;QAChC,GAAG,GAAG,MAAM,CAAA;IACd,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,eAAuB;IAC1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAuB,CAAA;QACtF,OAAO,MAAM,CAAC,OAAO,IAAI,IAAI,CAAA;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,qFAAqF;QACrF,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/catalog/load.d.ts

@@ -0,0 +1,3 @@
+import type { Logger } from '../logger.js';
+import { type Catalog } from './types.js';
+export declare function loadCatalog(logger: Logger): Catalog;

package/dist/catalog/load.js

@@ -0,0 +1,18 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { emptyCatalog } from './types.js';
+export function loadCatalog(logger) {
+    // Output next to the compiled output (`dist/catalog.json`) by the build-time generator.
+    const path = fileURLToPath(new URL('../catalog.json', import.meta.url));
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        logger.debug(`loaded catalog (${parsed.components.length} components, generated from @primer/react-brand@${parsed.generatedFromVersion})`);
+        return parsed;
+    }
+    catch (error) {
+        logger.warn(`could not load catalog at ${path}: ${error.message}`);
+        // If missing, it falls back to an empty catalog.
+        return emptyCatalog();
+    }
+}
+//# sourceMappingURL=load.js.map

package/dist/catalog/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/catalog/load.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAC,MAAM,SAAS,CAAA;AACpC,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAA;AAGtC,OAAO,EAAe,YAAY,EAAC,MAAM,YAAY,CAAA;AAErD,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,wFAAwF;IACxF,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;IACvE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAY,CAAA;QAChE,MAAM,CAAC,KAAK,CACV,mBAAmB,MAAM,CAAC,UAAU,CAAC,MAAM,mDAAmD,MAAM,CAAC,oBAAoB,GAAG,CAC7H,CAAA;QACD,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,6BAA6B,IAAI,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAA;QAC7E,iDAAiD;QACjD,OAAO,YAAY,EAAE,CAAA;IACvB,CAAC;AACH,CAAC"}

package/dist/catalog/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * All types associated with the build-generated catalog that ships inside the package.
+ * It is the structured, offline source of truth the tools reason over so they never depend on the network for version-sensitive facts.
+ */
+export interface CatalogProp {
+    name: string;
+    type?: string;
+    /** Allowed string-literal values, when the prop is an enum. */
+    enum?: string[];
+    required?: boolean;
+    default?: string;
+    /** One-line prop description from its JSDoc, when documented in source. */
+    description?: string;
+}
+export interface CatalogExample {
+    title: string;
+    /** Source snippet (JSX), when one could be extracted. */
+    code?: string;
+    /** Where the snippet came from: an authored JSDoc `@example`, a tested Storybook story, or a docs page. */
+    source: 'jsdoc' | 'story' | 'docs';
+    /** Storybook story id, when the example comes from a story. */
+    storyId?: string;
+}
+export interface CatalogComponent {
+    /** Public name, e.g. `Hero`. */
+    name: string;
+    /** Package the component is imported from. */
+    module: string;
+    /** Compound sub-components, e.g. `['Hero.Heading', 'Hero.Description']`. */
+    subcomponents: string[];
+    props: CatalogProp[];
+    examples: CatalogExample[];
+    /** One-line summary for listings, when available. */
+    description?: string;
+    /** Search keywords from the component's docs page, used to improve relevance ranking. */
+    keywords?: string[];
+    /** A usage caveat from the component's JSDoc `@remarks` (e.g. a non-obvious prop interaction). */
+    note?: string;
+}
+export interface CatalogAsset {
+    name: string;
+    module: string;
+    kind: 'icon' | 'illustration';
+}
+export interface CatalogToken {
+    name: string;
+    value: string;
+    group: string;
+}
+export interface Catalog {
+    /** Package whose API this catalog describes. */
+    brandPackage: string;
+    /** Version of `@primer/react-brand` the catalog was generated from. */
+    generatedFromVersion: string;
+    generatedAt: string;
+    components: CatalogComponent[];
+    assets: CatalogAsset[];
+    tokens: CatalogToken[];
+}
+export declare function emptyCatalog(): Catalog;

package/dist/catalog/types.js

@@ -0,0 +1,15 @@
+/**
+ * All types associated with the build-generated catalog that ships inside the package.
+ * It is the structured, offline source of truth the tools reason over so they never depend on the network for version-sensitive facts.
+ */
+export function emptyCatalog() {
+    return {
+        brandPackage: '@primer/react-brand',
+        generatedFromVersion: 'unknown',
+        generatedAt: new Date(0).toISOString(),
+        components: [],
+        assets: [],
+        tokens: [],
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/catalog/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/catalog/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+DH,MAAM,UAAU,YAAY;IAC1B,OAAO;QACL,YAAY,EAAE,qBAAqB;QACnC,oBAAoB,EAAE,SAAS;QAC/B,WAAW,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE;QACtC,UAAU,EAAE,EAAE;QACd,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,EAAE;KACX,CAAA;AACH,CAAC"}