@bridge-ds/mcp 0.8.0 → 0.8.2

package/dist/{chunk-BHODFN52.js → chunk-DPK46GA2.js}

@@ -596,7 +596,7 @@ var DEFAULT_GOVERNANCE = {
   owners: { design: [], tech: [] }
 };
 var FLAT_TOKEN_KEYS = ["primitives", "brands", "semantic", "base", "density", "components", "contrastChecks"];
-var CANONICAL_TOKEN_KEYS = ["root", "include", "exclude", "tiers", "layers"];
+var CANONICAL_TOKEN_KEYS = ["root", "include", "exclude", "tiers", "layers", "usage"];
 var FLAT_MODE_KEYS = ["brands", "themes", "densities", "defaults"];
 var AXIS_OF = { brands: "brand", themes: "theme", densities: "density" };
 var ConfigError = class extends Error {
@@ -684,7 +684,7 @@ function defineConfig(input) {
   const contrastFile = contrastPath ?? [root === "." ? "" : root, paths.contrastChecks].filter(Boolean).join("/");
   return {
     repo: parseRepoInput(input.repo, input.branch),
-    tokens: { ...paths, include: input.tokens?.include ?? ["**/*.tokens.json"], exclude: input.tokens?.exclude ?? [], tiers, layers },
+    tokens: { ...paths, include: input.tokens?.include ?? ["**/*.tokens.json"], exclude: input.tokens?.exclude ?? [], tiers, layers, ...t.usage ? { usage: trimSlashes(t.usage) } : {} },
     axes,
     modes,
     contrast: { path: contrastFile, modes: input.contrast?.modes },
@@ -719,6 +719,7 @@ function defineConfig(input) {
     products: input.products?.length ? input.products.map((p) => ({ ...p })) : DEFAULT_PRODUCTS.map((p) => ({ ...p })),
     changes: input.changes === "direct" ? "direct" : DEFAULT_CHANGES_MODE,
     ...input.storybook?.url ? { storybook: { url: input.storybook.url.trim().replace(/\/+$/, "") } } : {},
+    ...input.library?.public === true ? { library: { public: true } } : {},
     ...input.audit ? { audit: { ...input.audit } } : {},
     ...input.visualImpact ? { visualImpact: { mode: input.visualImpact.mode === "on-demand" ? "on-demand" : "auto" } } : {},
     ...input.integrations ? { integrations: { ...input.integrations } } : {},
@@ -763,7 +764,7 @@ function loadConfig(source) {
     if (!isObj(tokens)) problems.push('"tokens" must be an object');
     else
       for (const [k, v] of Object.entries(tokens)) {
-        if (FLAT_TOKEN_KEYS.includes(k) || k === "root") {
+        if (FLAT_TOKEN_KEYS.includes(k) || k === "root" || k === "usage") {
           if (!isStr(v)) problems.push(`"tokens.${k}" must be a non-empty string`);
         } else if (k === "include" || k === "exclude") {
           if (!isStrList(v)) problems.push(`"tokens.${k}" must be a list of globs`);
@@ -849,6 +850,14 @@ function loadConfig(source) {
     else if (!/^https:\/\/[^\s/]+/.test(sb.url.trim())) problems.push('"storybook.url" must start with https://, for example https://storybook.example.com');
     else for (const k of Object.keys(sb)) if (k !== "url") problems.push(`"storybook.${k}" is not a known key`);
   }
+  const lib = d.library;
+  if (lib !== void 0) {
+    if (!isObj(lib)) problems.push('"library" must be an object, for example { "public": true }');
+    else {
+      if (lib.public !== void 0 && typeof lib.public !== "boolean") problems.push('"library.public" must be true or false');
+      for (const k of Object.keys(lib)) if (k !== "public") problems.push(`"library.${k}" is not a known key`);
+    }
+  }
   problems.push(...productProblems(d.products));
   const audit = d.audit;
   if (audit !== void 0) {
@@ -887,7 +896,7 @@ function toConfigJson(config, schema = "./packages/core/bridge.config.schema.jso
     $schema: schema,
     version: 1,
     ...config.repo ? { repo: config.repo } : {},
-    tokens: { root: config.tokens.root, include: config.tokens.include, ...config.tokens.exclude.length ? { exclude: config.tokens.exclude } : {}, tiers: config.tokens.tiers, layers: config.tokens.layers.map((l) => l.optional ? l : { files: l.files }) },
+    tokens: { root: config.tokens.root, include: config.tokens.include, ...config.tokens.exclude.length ? { exclude: config.tokens.exclude } : {}, tiers: config.tokens.tiers, layers: config.tokens.layers.map((l) => l.optional ? l : { files: l.files }), ...config.tokens.usage ? { usage: config.tokens.usage } : {} },
     modes: Object.fromEntries(Object.entries(config.axes).map(([k, a]) => [k, a.parity ? a : { values: a.values, default: a.default }])),
     ...config.contrast ? { contrast: config.contrast.modes ? config.contrast : { path: config.contrast.path } } : {},
     ...config.components ? { components: Object.fromEntries(Object.entries(config.components).filter(([, v]) => v !== void 0)) } : {},
@@ -900,6 +909,7 @@ function toConfigJson(config, schema = "./packages/core/bridge.config.schema.jso
     ...config.visualImpact ? { visualImpact: config.visualImpact } : {},
     changes: changesMode(config),
     ...config.storybook ? { storybook: config.storybook } : {},
+    ...config.library ? { library: config.library } : {},
     ...config.products && !sameProducts(config.products, DEFAULT_PRODUCTS) ? { products: config.products } : {}
   };
 }

package/dist/{chunk-VV5HHLLG.js → chunk-QCPYJXK4.js}

@@ -79,7 +79,7 @@ import {
   validateLayered,
   variantKeyOf,
   whoCanShipSentence
-} from "./chunk-BHODFN52.js";
+} from "./chunk-DPK46GA2.js";
 
 // src/lib.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -1263,6 +1263,44 @@ function classifyAuth(status, detail, opts = {}) {
   }
   return {};
 }
+function memoryEtagStore(max = 500) {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    get(key) {
+      const e = map.get(key);
+      if (e) {
+        map.delete(key);
+        map.set(key, e);
+      }
+      return e;
+    },
+    set(key, entry) {
+      map.delete(key);
+      map.set(key, entry);
+      while (map.size > max) map.delete(map.keys().next().value);
+    },
+    clear: () => map.clear()
+  };
+}
+var sharedEtags = memoryEtagStore();
+function tokenFingerprint(token) {
+  if (!token) return "anon";
+  let a = 2166136261;
+  let b = 16777619 ^ token.length;
+  for (let i = 0; i < token.length; i++) {
+    const c = token.charCodeAt(i);
+    a = Math.imul(a ^ c, 16777619) >>> 0;
+    b = Math.imul(b ^ c ^ i & 255, 1540483477) >>> 0;
+  }
+  return a.toString(16).padStart(8, "0") + b.toString(16).padStart(8, "0");
+}
+function installationFor(list, owner) {
+  const inst = list.find((i) => i.account?.login?.toLowerCase() === owner.toLowerCase());
+  if (!inst) return { reach: "no" };
+  const selection = inst.repositorySelection ?? inst.repository_selection;
+  return selection === "all" ? { reach: "yes", id: inst.id } : { reach: "check", id: inst.id };
+}
+var MAX_PAGES = 10;
 function rateLimitMessage(x) {
   const when = x.resetsAt ? ` It resets at ${x.resetsAt.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}.` : "";
   if (x.withToken) return `GitHub's hourly request limit for this token is used up.${when} Try again after that.`;
@@ -1270,8 +1308,11 @@ function rateLimitMessage(x) {
   return `GitHub's hourly limit for requests without a token (60 an hour) is used up.${when} To keep going now, ${hint}: a token gets 5,000 requests an hour.`;
 }
 var DEFAULT_RETRY = { attempts: 3, baseDelayMs: 600, sleep: (ms) => new Promise((r) => setTimeout(r, ms)) };
+var hourlyLimitErrors = /* @__PURE__ */ new WeakSet();
 var isTransient = (status, detail) => status === 0 || status >= 500 || status === 429 || status === 403 && /secondary rate limit/i.test(detail);
 var API = "https://api.github.com";
+var ACCEPT_JSON = "application/vnd.github+json";
+var ACCEPT_RAW = "application/vnd.github.raw";
 var RAW = "https://raw.githubusercontent.com";
 function parseRepo(repo) {
   const m = /^\s*(?:https?:\/\/github\.com\/|git@github\.com:)?([A-Za-z0-9-]+)\/([A-Za-z0-9._-]+?)(?:\.git)?\/?\s*$/.exec(repo);
@@ -1290,6 +1331,7 @@ function base64ToUtf8(b64) {
   for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
   return new TextDecoder("utf-8").decode(bytes);
 }
+var copy = (value) => value === null || typeof value !== "object" ? value : typeof structuredClone === "function" ? structuredClone(value) : JSON.parse(JSON.stringify(value));
 var encodeRef = (ref) => ref.split("/").map(encodeURIComponent).join("/");
 var GitHubClient = class _GitHubClient {
   constructor(repo, token, fetchImpl = (url, init) => fetch(url, init), retry = DEFAULT_RETRY, options = {}) {
@@ -1302,6 +1344,8 @@ var GitHubClient = class _GitHubClient {
     this.name = r.name;
     this.api = (options.apiUrl ?? API).replace(/\/$/, "");
     this.protectedBranches = options.protectedBranches ?? DEFAULT_PROTECTED_BRANCHES;
+    this.etags = options.etags === false ? void 0 : options.etags ?? sharedEtags;
+    this.etagScope = options.etagScope ?? tokenFingerprint(token);
   }
   token;
   fetchImpl;
@@ -1312,6 +1356,15 @@ var GitHubClient = class _GitHubClient {
   blobCache = /* @__PURE__ */ new Map();
   api;
   protectedBranches;
+  etags;
+  etagScope;
+  rate;
+  /** What the conditional request cache did for this client. */
+  etagStats = { conditional: 0, notModified: 0, stale: 0 };
+  /** GitHub's rate-limit headers from the last API response, or undefined before any response carried them. */
+  get rateLimit() {
+    return this.rate;
+  }
   /** "owner/name". */
   get fullName() {
     return `${this.owner}/${this.name}`;
@@ -1335,45 +1388,77 @@ var GitHubClient = class _GitHubClient {
   get repoPath() {
     return `/repos/${this.owner}/${this.name}`;
   }
-  async request(method, path, body, retryable = method === "GET") {
+  async request(method, path, body, retryable = method === "GET", opts = {}) {
     const attempts = retryable ? Math.max(1, this.retry.attempts) : 1;
     for (let attempt = 1; ; attempt++) {
       try {
-        return await this.once(method, path, body);
+        return await this.once(method, path, body, opts);
       } catch (err) {
         const e = err;
-        if (attempt >= attempts || !(e instanceof GitHubError) || !isTransient(e.status, e.detail ?? "")) throw err;
+        if (attempt >= attempts || !(e instanceof GitHubError) || hourlyLimitErrors.has(e) || !isTransient(e.status, e.detail ?? "")) throw err;
         await this.retry.sleep(this.retry.baseDelayMs * 2 ** (attempt - 1));
       }
     }
   }
-  async once(method, path, body) {
+  noteRateLimit(headers) {
+    const remaining = headers?.get("x-ratelimit-remaining");
+    if (remaining == null) return;
+    const limit = headers?.get("x-ratelimit-limit");
+    const reset = headers?.get("x-ratelimit-reset");
+    this.rate = {
+      limit: limit != null ? Number(limit) : void 0,
+      remaining: Number(remaining),
+      resetsAt: reset ? new Date(Number(reset) * 1e3) : void 0,
+      resource: headers?.get("x-ratelimit-resource") ?? void 0
+    };
+  }
+  async once(method, path, body, opts = {}) {
+    const accept = opts.accept ?? ACCEPT_JSON;
     const headers = {
-      Accept: "application/vnd.github+json",
+      Accept: accept,
       "X-GitHub-Api-Version": "2022-11-28"
     };
     if (this.token) headers.Authorization = `Bearer ${this.token}`;
     if (body !== void 0) headers["Content-Type"] = "application/json";
+    const key = method === "GET" && this.etags && opts.etag !== false ? `${this.etagScope} ${accept} ${this.api}${path}` : void 0;
+    const cached = key ? this.etags.get(key) : void 0;
+    if (cached && this.token) {
+      headers["If-None-Match"] = cached.etag;
+      this.etagStats.conditional++;
+    }
     let res;
     try {
       res = await this.fetchImpl(`${this.api}${path}`, { method, headers, ...body !== void 0 ? { body: JSON.stringify(body) } : {} });
     } catch (err) {
+      if (err instanceof GitHubError) throw err;
       throw new GitHubError(0, "Could not reach GitHub. Check your connection, then try again.", err.message);
     }
+    this.noteRateLimit(res.headers);
+    if (res.status === 304 && cached && key && this.token) {
+      this.etagStats.notModified++;
+      this.etags.set(key, { ...cached, at: Date.now() });
+      return copy(cached.body);
+    }
     if (res.status === 204) return void 0;
     if (!res.ok) {
       let detail = "";
       try {
-        const data = await res.json();
-        detail = [data.message, ...(data.errors ?? []).map((e) => typeof e === "string" ? e : e.message)].filter(Boolean).join(" ");
+        const data2 = await res.json();
+        detail = [data2.message, ...(data2.errors ?? []).map((e) => typeof e === "string" ? e : e.message)].filter(Boolean).join(" ");
       } catch {
         detail = "";
       }
       const remaining = res.headers?.get("x-ratelimit-remaining");
       const reset = res.headers?.get("x-ratelimit-reset");
       if ((res.status === 403 || res.status === 429) && remaining === "0") {
+        if (cached && this.options.serveStaleOnRateLimit) {
+          this.etagStats.stale++;
+          return copy(cached.body);
+        }
         const resetsAt = reset ? new Date(Number(reset) * 1e3) : void 0;
-        throw new GitHubError(429, rateLimitMessage({ withToken: Boolean(this.token), resetsAt, tokenHint: this.options.tokenHint }), detail);
+        const limited = new GitHubError(429, rateLimitMessage({ withToken: Boolean(this.token), resetsAt, tokenHint: this.options.tokenHint }), detail);
+        hourlyLimitErrors.add(limited);
+        throw limited;
       }
       const info = classifyAuth(res.status, detail, {
         path,
@@ -1382,7 +1467,24 @@ var GitHubClient = class _GitHubClient {
       });
       throw new GitHubError(res.status, friendlyMessage(res.status, detail, info), detail, info);
     }
-    return await res.json();
+    const data = opts.text ? await res.text() : await res.json();
+    const etag = key ? res.headers?.get("etag") : null;
+    if (key && etag) this.etags.set(key, { etag, body: copy(data), at: Date.now() });
+    return data;
+  }
+  /**
+   * Every item of a paged listing (`per_page=100`), at most 10 pages. `pick` takes the items out of one page (the
+   * installation endpoints wrap them in an object with `total_count`).
+   */
+  async paged(path, pick) {
+    const out = [];
+    const sep2 = path.includes("?") ? "&" : "?";
+    for (let page = 1; page <= MAX_PAGES; page++) {
+      const { items, total } = pick(await this.request("GET", `${path}${sep2}per_page=100&page=${page}`));
+      out.push(...items);
+      if (items.length < 100 || total !== void 0 && out.length >= total) break;
+    }
+    return out;
   }
   async getRepo() {
     const r = await this.request(
@@ -1765,6 +1867,14 @@ var GitHubClient = class _GitHubClient {
    */
   async readFile(path, ref) {
     if (this.token) return this.getFileText(path, ref);
+    return this.readRawFile(path, ref);
+  }
+  /**
+   * Text of a file from the raw host (raw.githubusercontent.com), sent without any header so the browser makes a
+   * simple CORS request (no preflight) and nothing counts against the API limit. Works for public repositories only:
+   * a private file answers 404 there, like a missing one. Undefined on 404.
+   */
+  async readRawFile(path, ref) {
     const url = `${(this.options.rawUrl ?? RAW).replace(/\/$/, "")}/${this.owner}/${this.name}/${encodeRef(ref)}/${encodeRef(path)}`;
     let res;
     try {
@@ -1776,6 +1886,76 @@ var GitHubClient = class _GitHubClient {
     if (!res.ok) throw new GitHubError(res.status, friendlyMessage(res.status, ""), `raw ${path}@${ref}`);
     return res.text();
   }
+  /**
+   * Text of a file at a ref through the contents API with the raw media type: the way to read a private file (the raw
+   * host cannot take the token without a preflight). Counts against the API limit; conditional when cached.
+   * Undefined when the file does not exist.
+   */
+  async getRawText(path, ref) {
+    try {
+      return await this.request("GET", `${this.repoPath}/contents/${encodeRef(path)}?ref=${encodeURIComponent(ref)}`, void 0, true, { accept: ACCEPT_RAW, text: true });
+    } catch (err) {
+      if (err instanceof GitHubError && err.status === 404) return void 0;
+      throw err;
+    }
+  }
+  /**
+   * Text of a blob by its sha through the git blobs API with the raw media type: how a signed-in reader loads a file
+   * listed by a tree (the raw host refuses any request that carries a token). A blob sha names its content, so the
+   * answer is cached for the client's life and never revalidated. Undefined on 404.
+   */
+  async getBlobRaw(sha) {
+    const cached = this.blobCache.get(sha);
+    if (cached !== void 0) return cached;
+    try {
+      const text = await this.request("GET", `${this.repoPath}/git/blobs/${encodeURIComponent(sha)}`, void 0, true, { accept: ACCEPT_RAW, text: true, etag: false });
+      this.blobCache.set(sha, text);
+      return text;
+    } catch (err) {
+      if (err instanceof GitHubError && err.status === 404) return void 0;
+      throw err;
+    }
+  }
+  // --- GitHub App installations (user-to-server tokens) ---------------------------------------
+  /**
+   * Installations of the signing-in GitHub App that the signed-in user can reach (GET /user/installations, every
+   * page). Needs a user-to-server token of that same App: a personal or OAuth token is refused (403), and each App
+   * sees only its own installations. GitHub lists only installations on accounts and repositories the user has
+   * explicit permission on: a public repository where the user is not a collaborator is never listed, installed or
+   * not. (GET /repos/{o}/{r}/installation would say, but it needs the App's private key, which Bridge never holds.)
+   */
+  async listUserInstallations() {
+    this.assertToken("Reading where Bridge is installed");
+    const list = await this.paged("/user/installations", (p) => ({ items: p.installations ?? [], total: p.total_count }));
+    return list.map((i) => ({
+      id: i.id,
+      account: i.account?.login ? { login: i.account.login, type: i.account.type ?? "User" } : null,
+      repositorySelection: i.repository_selection ?? "selected",
+      appSlug: i.app_slug
+    }));
+  }
+  /** Repositories of one installation the signed-in user can reach (GET /user/installations/{id}/repositories, every page). */
+  async listInstallationRepos(installationId) {
+    this.assertToken("Reading where Bridge is installed");
+    const list = await this.paged(`/user/installations/${encodeURIComponent(String(installationId))}/repositories`, (p) => ({
+      items: p.repositories ?? [],
+      total: p.total_count
+    }));
+    return list.map((r) => ({ owner: r.owner?.login ?? r.full_name.split("/")[0], name: r.name, fullName: r.full_name, private: Boolean(r.private) }));
+  }
+  /**
+   * The App installation that gives the signed-in user this repository (this client's by default): its id, or null
+   * when the App is not installed there or the user cannot reach it. One call when the installation covers all of
+   * the owner's repositories, two (paged) when it covers selected ones.
+   */
+  async findInstallation(owner = this.owner, repo = this.name) {
+    const found = installationFor(await this.listUserInstallations(), owner);
+    if (found.reach === "no") return null;
+    if (found.reach === "yes") return { id: found.id, selection: "all" };
+    const repos = await this.listInstallationRepos(found.id);
+    const hit = repos.some((r) => r.owner.toLowerCase() === owner.toLowerCase() && r.name.toLowerCase() === repo.toLowerCase());
+    return hit ? { id: found.id, selection: "selected" } : null;
+  }
   /** The repository's default branch. */
   async getDefaultBranch() {
     return (await this.getRepo()).defaultBranch;
@@ -6255,6 +6435,7 @@ function shareMessage(x) {
 // ../core/src/try-in-product.ts
 function tryInProductUrl(preview, pr, screen) {
   const url = new URL(preview);
+  if (url.protocol !== "https:" && url.protocol !== "http:") return "";
   url.pathname = "/";
   url.search = "";
   url.searchParams.set("bridge", String(pr));
@@ -11754,7 +11935,7 @@ async function visualImpact(ctx, a, run2) {
   if (ctx.mode !== "local" || !ctx.root) throw new Error("Visual impact needs a local checkout (start Bridge with --root): it builds Storybook and the app at both refs.");
   if (!ctx.isGit) throw new Error(`${ctx.root} is not a git repository.`);
   const out = a.out ? resolve3(ctx.root, a.out) : join5(ctx.root, "visual-impact");
-  const runImpact = run2 ?? (await import("./src-P3GHW467.js")).runImpact;
+  const runImpact = run2 ?? (await import("./src-UNWS2OVM.js")).runImpact;
   const r = await runImpact({
     root: ctx.root,
     base: a.base ?? "main",
@@ -12822,7 +13003,7 @@ async function pushFigmaComponentOp(ctx, a) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.8.0" : "dev";
+var VERSION = true ? "0.8.2" : "dev";
 var ok = (data) => ({ content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }] });
 var fail2 = (e) => ({ content: [{ type: "text", text: `Error: ${e.message ?? String(e)}` }], isError: true });
 var run = (fn) => async (a) => {

package/dist/index.js

@@ -3,8 +3,8 @@ import {
   VERSION,
   optionsFromArgv,
   serveStdio
-} from "./chunk-VV5HHLLG.js";
-import "./chunk-BHODFN52.js";
+} from "./chunk-QCPYJXK4.js";
+import "./chunk-DPK46GA2.js";
 
 // src/index.ts
 var argv = process.argv.slice(2);

package/dist/lib.js

@@ -28,12 +28,12 @@ import {
   serveStdio,
   studio_exports,
   suggestions_exports
-} from "./chunk-VV5HHLLG.js";
+} from "./chunk-QCPYJXK4.js";
 import {
   CONFIG_FILE,
   loadConfig,
   toConfigJson
-} from "./chunk-BHODFN52.js";
+} from "./chunk-DPK46GA2.js";
 export {
   BridgeContext,
   CONFIG_FILE,

package/dist/{src-P3GHW467.js → src-UNWS2OVM.js}

@@ -11,7 +11,7 @@ import {
   referenceImagePath,
   selectTokenFiles,
   showFile
-} from "./chunk-BHODFN52.js";
+} from "./chunk-DPK46GA2.js";
 
 // ../visual/src/run.ts
 import { existsSync as existsSync3 } from "node:fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge-ds/mcp",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "type": "module",
   "description": "Bridge MCP server: lets Claude (Claude Code, Claude Desktop or any MCP client) read, check and propose changes to a DTCG design system repo through pull requests.",
   "license": "MIT",
@@ -54,8 +54,8 @@
     "build:package": "node ../../scripts/build-packages.mjs mcp"
   },
   "dependencies": {
-    "@bridge-ds/core": "^0.13.0",
-    "@bridge-ds/visual": "^0.3.7",
+    "@bridge-ds/core": "^0.15.0",
+    "@bridge-ds/visual": "^0.3.9",
     "@modelcontextprotocol/sdk": "1.31.0",
     "typescript": "5.9.3",
     "zod": "3.25.76"