@bridge-ds/cli 0.2.0 → 0.3.1

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { existsSync as existsSync5 } from "node:fs";
 import { readFile as readFile5, writeFile as writeFile4 } from "node:fs/promises";
-import { join as join5, relative as relative4, resolve as resolve3 } from "node:path";
+import { isAbsolute, join as join5, relative as relative4, resolve as resolve3 } from "node:path";
 
 // ../core/src/audit/types.ts
 var AUDIT_SCHEMA_VERSION = 1;
@@ -1115,9 +1115,9 @@ var DesignSystemIndex = class {
         return generic ? this.make(generic, 1, 0.3) : void 0;
       }
       case "shadow": {
-        const norm3 = (s) => s.replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").trim().toLowerCase();
+        const norm4 = (s) => s.replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").trim().toLowerCase();
         const cands = this.entries(["shadow"]);
-        const exact = cands.find((e) => norm3(e.css) === norm3(value));
+        const exact = cands.find((e) => norm4(e.css) === norm4(value));
         if (exact) return this.make(exact, 0, 1);
         const t = shadowNums(value);
         const scored = cands.map((e) => {
@@ -1766,6 +1766,226 @@ async function originRepo(root) {
 // ../core/src/previews.ts
 var PREVIEW_APP_LABELS = { docs: "Docs", storybook: "Storybook", admin: "Admin demo" };
 
+// ../core/src/teams.ts
+var LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;
+var SLUG = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+function parseOwnerEntry(raw) {
+  if (typeof raw !== "string") return null;
+  const s = raw.trim().replace(/^@/, "");
+  const slash = s.indexOf("/");
+  if (slash < 0) return LOGIN.test(s) ? { kind: "person", login: s } : null;
+  const org = s.slice(0, slash);
+  const slug = s.slice(slash + 1);
+  return LOGIN.test(org) && SLUG.test(slug) ? { kind: "team", org, slug } : null;
+}
+var teamKey = (org, slug) => `@${org.toLowerCase()}/${slug.toLowerCase()}`;
+function ownerEntryProblems(raw) {
+  if (raw === void 0) return [];
+  const isObj2 = (x) => Boolean(x) && typeof x === "object" && !Array.isArray(x);
+  if (!isObj2(raw)) return ['"governance.owners" must be { "design": [people or teams], "tech": [people or teams] }'];
+  const out = [];
+  for (const [k, v] of Object.entries(raw)) {
+    if (k !== "design" && k !== "tech") {
+      out.push(`"governance.owners.${k}" is not an owner group (design, tech)`);
+      continue;
+    }
+    if (!Array.isArray(v)) {
+      out.push(`"governance.owners.${k}" must be a list of people or teams`);
+      continue;
+    }
+    v.forEach((x, i) => {
+      if (typeof x !== "string" || !parseOwnerEntry(x))
+        out.push(`"governance.owners.${k}[${i}]" (${JSON.stringify(x)}) is not a GitHub login or team. Write a person as "peterbono" or "@peterbono", a team as "@org/team-slug".`);
+    });
+  }
+  return out;
+}
+function teamUnreadableMessage(team, reason) {
+  const name = `@${team.org}/${team.slug}`;
+  switch (reason) {
+    case "personal-account":
+      return `${name} cannot be used: ${team.org} is a personal GitHub account, and teams only exist in organizations. List people instead, or move the repository to an organization.`;
+    case "missing-permission":
+      return `The members of ${name} cannot be read: the GitHub token needs read:org (classic token) or Members: Read on the ${team.org} organization (fine-grained token).`;
+    case "no-token":
+      return `The members of ${name} cannot be read without a working GitHub token. Connect GitHub with a token that has read:org.`;
+    case "not-found":
+      return `${name} was not found. Check the team slug on GitHub, or give the token read:org so it can see the team.`;
+    case "unreachable":
+      return `The members of ${name} cannot be read right now: GitHub did not answer. Try again in a moment.`;
+  }
+}
+function teamsIn(owners) {
+  const all = Array.isArray(owners) ? owners : [...owners.design ?? [], ...owners.tech ?? []];
+  const out = /* @__PURE__ */ new Map();
+  for (const raw of all) {
+    const e = parseOwnerEntry(raw);
+    if (e?.kind === "team") out.set(teamKey(e.org, e.slug), { key: teamKey(e.org, e.slug), org: e.org, slug: e.slug });
+  }
+  return [...out.values()];
+}
+var norm = (x) => x.trim().toLowerCase().replace(/^@/, "");
+var people = (n) => `${n} ${n === 1 ? "person" : "people"}`;
+function entryLabel(raw, teams) {
+  const e = parseOwnerEntry(raw);
+  if (!e) return raw;
+  if (e.kind === "person") return `@${e.login}`;
+  const state = teams?.[teamKey(e.org, e.slug)];
+  const name = `@${e.org}/${e.slug}`;
+  return state?.status === "ok" ? `${name} (${people(state.members.length)})` : name;
+}
+var TeamDirectory = class {
+  constructor(reader, opts = {}) {
+    this.reader = reader;
+    this.ttl = opts.ttlMs ?? 5 * 6e4;
+    this.now = opts.now ?? Date.now;
+  }
+  reader;
+  teams = /* @__PURE__ */ new Map();
+  accounts = /* @__PURE__ */ new Map();
+  memberships = /* @__PURE__ */ new Map();
+  ttl;
+  now;
+  accountType(org) {
+    const k = org.toLowerCase();
+    let p = this.accounts.get(k);
+    if (!p) {
+      p = this.reader.getAccountType(org).catch(() => null);
+      this.accounts.set(k, p);
+    }
+    return p;
+  }
+  /** The reason a read of `org` failed, as a state. A 404 on a personal account says so; a 403 is a missing permission. */
+  async failure(ref, err) {
+    const e = err ?? {};
+    let reason;
+    if (!this.reader.hasToken) reason = await this.accountType(ref.org) === "User" ? "personal-account" : "no-token";
+    else if (e.status === 401) reason = "no-token";
+    else if (e.status === 403 || e.auth === "missing-permission") reason = "missing-permission";
+    else if (e.status === 404) reason = await this.accountType(ref.org) === "User" ? "personal-account" : "not-found";
+    else reason = "unreachable";
+    return { ...ref, status: "unreadable", reason, message: teamUnreadableMessage(ref, reason) };
+  }
+  /** Members of one team, or why they cannot be read. Cached. */
+  team(org, slug) {
+    const ref = { key: teamKey(org, slug), org, slug };
+    const hit = this.teams.get(ref.key);
+    if (hit && this.now() - hit.at < this.ttl) return hit.value;
+    const value = (async () => {
+      if (!this.reader.hasToken) return this.failure(ref, void 0);
+      try {
+        const members = await this.reader.listTeamMembers(org, slug);
+        return { ...ref, status: "ok", members };
+      } catch (err) {
+        return this.failure(ref, err);
+      }
+    })();
+    this.teams.set(ref.key, { at: this.now(), value });
+    void value.then((s) => {
+      if (s.status === "unreadable" && s.reason === "unreachable") this.teams.delete(ref.key);
+    });
+    return value;
+  }
+  /** Every team named in the owner lists, read in parallel. Empty object when no team is named (no request). */
+  async resolve(owners) {
+    const refs = teamsIn(owners);
+    const states = await Promise.all(refs.map((r) => this.team(r.org, r.slug)));
+    return Object.fromEntries(states.map((s) => [s.key, s]));
+  }
+  /**
+   * Whether `login` is an active member of one team: from the cached member list when there is one, else one
+   * membership read (GET /orgs/{org}/teams/{slug}/memberships/{user}). An unreadable team returns its state.
+   */
+  async isMember(org, slug, login) {
+    const ref = { key: teamKey(org, slug), org, slug };
+    const cached = this.teams.get(ref.key);
+    if (cached && this.now() - cached.at < this.ttl) {
+      const s = await cached.value;
+      if (s.status === "ok") return s.members.some((m) => norm(m) === norm(login));
+    }
+    const k = `${ref.key}#${norm(login)}`;
+    const hit = this.memberships.get(k);
+    if (hit && this.now() - hit.at < this.ttl) return hit.value;
+    const value = (async () => {
+      if (!this.reader.hasToken) return this.failure(ref, void 0);
+      try {
+        return await this.reader.getTeamMembership(org, slug, login) === "active";
+      } catch (err) {
+        return this.failure(ref, err);
+      }
+    })();
+    this.memberships.set(k, { at: this.now(), value });
+    return value;
+  }
+  /**
+   * Whether `login` holds a right given to `entries` (people and teams): a person entry matches directly, a team
+   * through its membership. Teams are only read when no person entry matches.
+   */
+  async memberOfAny(entries, login) {
+    const unreadable = [];
+    const parsed = entries.map(parseOwnerEntry).filter((e) => Boolean(e));
+    if (parsed.some((e) => e.kind === "person" && norm(e.login) === norm(login))) return { member: true, unreadable };
+    for (const e of parsed) {
+      if (e.kind !== "team") continue;
+      const r = await this.isMember(e.org, e.slug, login);
+      if (r === true) return { member: true, unreadable };
+      if (typeof r === "object" && r.status === "unreadable") unreadable.push(r);
+    }
+    return { member: false, unreadable };
+  }
+  /** The organization's teams for a picker, or why they cannot be listed (a personal account has none). */
+  async orgTeams(org) {
+    if (await this.accountType(org) === "User") return { status: "unreadable", reason: "personal-account" };
+    if (!this.reader.hasToken) return { status: "unreadable", reason: "no-token" };
+    try {
+      return { status: "ok", teams: await this.reader.listOrgTeams(org) };
+    } catch (err) {
+      const s = await this.failure({ key: teamKey(org, "*"), org, slug: "*" }, err);
+      return { status: "unreadable", reason: s.status === "unreadable" ? s.reason : "unreachable" };
+    }
+  }
+  /** Drops every cached read (after the token changes). */
+  clear() {
+    this.teams.clear();
+    this.accounts.clear();
+    this.memberships.clear();
+  }
+};
+
+// ../core/src/rights.ts
+var OWNER_GROUPS = ["design", "tech"];
+var RIGHTS = ["approveDesign", "approveTech", "ship"];
+var DEFAULT_RIGHTS = { approveDesign: ["design"], approveTech: ["tech"], ship: ["tech"] };
+function normalizeRights(input) {
+  const pick = (r) => {
+    const v = input?.[r];
+    if (!Array.isArray(v)) return [...DEFAULT_RIGHTS[r]];
+    return OWNER_GROUPS.filter((g) => v.includes(g));
+  };
+  return { approveDesign: pick("approveDesign"), approveTech: pick("approveTech"), ship: pick("ship") };
+}
+function rightsProblems(raw) {
+  if (raw === void 0) return [];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return ['"governance.rights" must be { "approveDesign": [groups], "approveTech": [groups], "ship": [groups] }'];
+  const out = [];
+  for (const [k, v] of Object.entries(raw)) {
+    if (!RIGHTS.includes(k)) out.push(`"governance.rights.${k}" is not a right (${RIGHTS.join(", ")})`);
+    else if (!Array.isArray(v) || v.length === 0 || !v.every((g) => OWNER_GROUPS.includes(g)))
+      out.push(`"governance.rights.${k}" must list one or more of "design", "tech"`);
+  }
+  return out;
+}
+function visualImpactProblems(raw) {
+  if (raw === void 0) return [];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return ['"visualImpact" must be { "mode": "auto" | "on-demand" }'];
+  const out = [];
+  for (const [k, v] of Object.entries(raw)) {
+    if (k !== "mode") out.push(`"visualImpact.${k}" is not a setting (mode)`);
+    else if (v !== "auto" && v !== "on-demand") out.push('"visualImpact.mode" must be "auto" or "on-demand"');
+  }
+  return out;
+}
+
 // ../core/src/config.ts
 var CONFIG_FILE = "bridge.config.json";
 var DEFAULT_OVERRIDE = { allowed: [], requireReason: true, minReasonLength: 20 };
@@ -1903,9 +2123,11 @@ function defineConfig(input) {
           requireReason: g.override.requireReason ?? DEFAULT_OVERRIDE.requireReason,
           minReasonLength: g.override.minReasonLength ?? DEFAULT_OVERRIDE.minReasonLength
         }
-      } : {}
+      } : {},
+      ...g.rights ? { rights: normalizeRights(g.rights) } : {}
     },
     ...input.audit ? { audit: { ...input.audit } } : {},
+    ...input.visualImpact ? { visualImpact: { mode: input.visualImpact.mode === "on-demand" ? "on-demand" : "auto" } } : {},
     ...input.integrations ? { integrations: { ...input.integrations } } : {},
     ...input.previews ? {
       previews: {
@@ -2012,9 +2234,7 @@ function loadConfig(source) {
     else {
       for (const k of ["protectedBranches", "labels", "guardrails"]) if (gov[k] !== void 0 && !(Array.isArray(gov[k]) && gov[k].every((x) => typeof x === "string"))) problems.push(`"governance.${k}" must be a list of strings`);
       if (gov.branchPrefix !== void 0 && !isStr(gov.branchPrefix)) problems.push('"governance.branchPrefix" must be a non-empty string');
-      const o = gov.owners;
-      if (o !== void 0 && (!isObj(o) || ["design", "tech"].some((k) => o[k] !== void 0 && !(Array.isArray(o[k]) && o[k].every((x) => typeof x === "string")))))
-        problems.push('"governance.owners" must be { "design": [logins], "tech": [logins] }');
+      problems.push(...ownerEntryProblems(gov.owners));
       const ov = gov.override;
       if (ov !== void 0) {
         if (!isObj(ov)) problems.push('"governance.override" must be an object');
@@ -2024,8 +2244,10 @@ function loadConfig(source) {
           if (ov.minReasonLength !== void 0 && !(Number.isInteger(ov.minReasonLength) && ov.minReasonLength >= 0)) problems.push('"governance.override.minReasonLength" must be a whole number, 0 or more');
         }
       }
+      problems.push(...rightsProblems(gov.rights));
     }
   }
+  problems.push(...visualImpactProblems(d.visualImpact));
   const audit2 = d.audit;
   if (audit2 !== void 0) {
     if (!isObj(audit2)) problems.push('"audit" must be an object');
@@ -2237,125 +2459,147 @@ import { mkdir as mkdir3, readFile as readFile3, rm as rm2, unlink, writeFile as
 import { tmpdir } from "node:os";
 import { join as join4, relative as relative3, resolve as resolve2 } from "node:path";
 
-// ../core/src/usage.ts
-var VAR_RE = /var\(\s*(--[A-Za-z0-9_-]+)/g;
-var IMPORT_RE = /(?:import|export)\s[^'"]*?from\s*['"]([^'"]+)['"]|import\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
-function cssVarsIn(text) {
-  const out = /* @__PURE__ */ new Set();
-  for (const m of text.matchAll(VAR_RE)) out.add(m[1]);
-  return [...out];
-}
-function importsIn(text) {
-  const out = /* @__PURE__ */ new Set();
-  for (const m of text.matchAll(IMPORT_RE)) out.add(m[1] ?? m[2]);
-  return [...out];
-}
-var norm = (p) => p.replace(/\\/g, "/").replace(/\/+$/, "");
-var isStory = (p) => /\.stories\.[cm]?[jt]sx?$/.test(p);
-var isTest = (p) => /\.(test|spec)\.[cm]?[jt]sx?$/.test(p);
-var isCss = (p) => /\.(css|scss|less)$/.test(p);
-var isScript = (p) => /\.[cm]?[jt]sx?$/.test(p);
-function componentOf(from, spec, componentsDir) {
-  if (!spec.startsWith(".")) return null;
-  const parts = from.split("/").slice(0, -1);
-  for (const seg of spec.split("/")) {
-    if (seg === "." || seg === "") continue;
-    if (seg === "..") parts.pop();
-    else parts.push(seg);
-  }
-  const abs = parts.join("/");
-  if (!abs.startsWith(`${componentsDir}/`)) return null;
-  return abs.slice(componentsDir.length + 1).split("/")[0] || null;
-}
-function componentForPath(path, componentsDir) {
-  const dir = norm(componentsDir);
-  const p = norm(path);
-  if (!p.startsWith(`${dir}/`)) return null;
-  const rest = p.slice(dir.length + 1).split("/");
-  return rest.length >= 2 ? rest[0] : null;
-}
-function buildUsageIndex(files, componentsDir) {
-  const dir = norm(componentsDir);
-  const modules = {};
-  const vars = /* @__PURE__ */ new Map();
-  const imports = /* @__PURE__ */ new Map();
-  const storyImports = /* @__PURE__ */ new Map();
-  const globalVars = {};
-  const get = (m, k) => m.get(k) ?? m.set(k, /* @__PURE__ */ new Set()).get(k);
-  for (const f of files) {
-    const path = norm(f.path);
-    const id = componentForPath(path, dir);
-    if (!id) {
-      if (isCss(path)) {
-        const v = cssVarsIn(f.text);
-        if (v.length) globalVars[path] = v.sort();
-      }
-      continue;
-    }
-    const mod = modules[id] ??= { id, dir: `${dir}/${id}`, files: [], vars: [], imports: [], storyImports: [] };
-    mod.files.push(path);
-    if (isTest(path)) continue;
-    for (const v of cssVarsIn(f.text)) get(vars, id).add(v);
-    if (!isScript(path)) continue;
-    for (const spec of importsIn(f.text)) {
-      const dep = componentOf(path, spec, dir);
-      if (!dep || dep === id) continue;
-      get(isStory(path) ? storyImports : imports, id).add(dep);
-    }
-  }
-  const byVar = {};
-  for (const mod of Object.values(modules)) {
-    mod.files.sort();
-    mod.vars = [...vars.get(mod.id) ?? []].sort();
-    mod.imports = [...imports.get(mod.id) ?? []].sort();
-    mod.storyImports = [...storyImports.get(mod.id) ?? []].filter((d) => !mod.imports.includes(d)).sort();
-    for (const v of mod.vars) (byVar[v] ??= []).push(mod.id);
-  }
-  for (const k of Object.keys(byVar)) byVar[k].sort();
-  return { componentsDir: dir, modules, byVar, globalVars };
-}
-function impactedModules(index, input) {
-  const reasons = /* @__PURE__ */ new Map();
-  const add = (id, reason, indirect) => {
-    const r = reasons.get(id);
-    if (r) {
-      if (!r.reasons.includes(reason)) r.reasons.push(reason);
-      r.indirect &&= indirect;
-    } else reasons.set(id, { reasons: [reason], indirect });
-  };
-  const changedVars = new Set(input.vars ?? []);
-  for (const v of changedVars) for (const id of index.byVar[v] ?? []) add(id, `uses ${v}`, false);
-  for (const f of input.files ?? []) {
-    const id = componentForPath(f, index.componentsDir);
-    if (id && index.modules[id]) add(id, `file changed: ${norm(f)}`, false);
-  }
-  const renderedBy = /* @__PURE__ */ new Map();
-  for (const m of Object.values(index.modules)) for (const d of m.imports) (renderedBy.get(d) ?? renderedBy.set(d, []).get(d)).push(m.id);
-  const queue = [...reasons.keys()];
-  while (queue.length) {
-    const id = queue.shift();
-    for (const parent of renderedBy.get(id) ?? []) {
-      const known = reasons.has(parent);
-      add(parent, `renders ${id}`, true);
-      if (!known) queue.push(parent);
+// ../core/src/protection.ts
+var PROTECTION_PARTS = ["review", "checks", "history", "deletion"];
+var protectionRulesetName = (defaultBranch) => `Protect the library (${defaultBranch})`;
+function refPattern(pattern) {
+  const src = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(/\u0000/g, ".*");
+  return new RegExp(`^${src}$`);
+}
+function rulesetTargetsDefault(ruleset, defaultBranch) {
+  if (ruleset.target && ruleset.target !== "branch") return false;
+  const ref = `refs/heads/${defaultBranch}`;
+  const hit = (p) => p === "~ALL" || p === "~DEFAULT_BRANCH" || p === ref || p === defaultBranch || refPattern(p.startsWith("refs/") ? p : `refs/heads/${p}`).test(ref);
+  const cond = ruleset.conditions?.ref_name;
+  if (!cond) return false;
+  if ((cond.exclude ?? []).some(hit)) return false;
+  return (cond.include ?? []).some(hit);
+}
+var count = (v) => typeof v === "number" ? v : 0;
+function rulesetParts(ruleset) {
+  const parts = /* @__PURE__ */ new Set();
+  if (ruleset.enforcement !== "active") return parts;
+  for (const rule of ruleset.rules ?? []) {
+    if (rule.type === "deletion") parts.add("deletion");
+    if (rule.type === "non_fast_forward") parts.add("history");
+    if (rule.type === "pull_request" && count(rule.parameters?.required_approving_review_count) >= 1) parts.add("review");
+    if (rule.type === "required_status_checks" && Array.isArray(rule.parameters?.required_status_checks) && rule.parameters.required_status_checks.length > 0) parts.add("checks");
+  }
+  return parts;
+}
+function classicParts(p) {
+  const parts = /* @__PURE__ */ new Set();
+  if (count(p.required_pull_request_reviews?.required_approving_review_count) >= 1) parts.add("review");
+  if (((p.required_status_checks?.contexts?.length ?? 0) || (p.required_status_checks?.checks?.length ?? 0)) > 0) parts.add("checks");
+  if (!p.allow_force_pushes?.enabled) parts.add("history");
+  if (!p.allow_deletions?.enabled) parts.add("deletion");
+  return parts;
+}
+var rulesetUrl = (r) => r.html_url ?? r._links?.html?.href;
+function protectionState(rulesets, branchProtection, defaultBranch) {
+  const bridge = rulesets?.find((r) => r.name === protectionRulesetName(defaultBranch));
+  const extra = bridge?.id !== void 0 ? { bridgeRulesetId: bridge.id } : {};
+  const covered = /* @__PURE__ */ new Set();
+  let url;
+  for (const r of rulesets ?? []) {
+    if (!rulesetTargetsDefault(r, defaultBranch)) continue;
+    const parts = rulesetParts(r);
+    if (parts.size && !url) url = rulesetUrl(r);
+    parts.forEach((p) => covered.add(p));
+  }
+  if (branchProtection) classicParts(branchProtection).forEach((p) => covered.add(p));
+  const missing = PROTECTION_PARTS.filter((p) => !covered.has(p));
+  const withUrl = url ? { url } : {};
+  if (!missing.length) return { kind: "protected", missing, ...extra, ...withUrl };
+  const unreadable = rulesets == null || branchProtection === void 0;
+  if (covered.size === 0) return { kind: unreadable ? "unknown" : "unprotected", missing, ...extra };
+  return { kind: "partial", missing, ...extra, ...withUrl };
+}
+var PROTECTION_PART_PHRASE = {
+  review: "changes can skip review",
+  checks: "checks do not have to pass",
+  history: "past changes can be rewritten",
+  deletion: "the library can be deleted"
+};
+var joinAnd = (xs) => xs.length <= 1 ? xs[0] ?? "" : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`;
+function protectionSentence(state) {
+  switch (state.kind) {
+    case "protected":
+      return "Protected: every change goes through review.";
+    case "unprotected":
+      return "Your library can be changed without review.";
+    case "partial": {
+      const s = joinAnd(state.missing.map((p) => PROTECTION_PART_PHRASE[p]));
+      return `Partly protected: ${s}.`;
     }
+    default:
+      return "Protection status unknown: GitHub did not let this token read it.";
   }
-  const globalHits = Object.entries(index.globalVars).map(([file, vs]) => ({ file, vars: vs.filter((v) => changedVars.has(v)) })).filter((g) => g.vars.length > 0);
-  const modules = [...reasons.entries()].map(([id, r]) => ({ id, reasons: r.reasons, indirect: r.indirect })).sort((a, b) => Number(a.indirect) - Number(b.indirect) || a.id.localeCompare(b.id));
-  return { modules, globalHits };
 }
 
 // ../core/src/github-client.ts
 var GitHubError = class extends Error {
-  constructor(status, message, detail) {
+  constructor(status, message, detail, info = {}) {
     super(message);
     this.status = status;
     this.detail = detail;
     this.name = "GitHubError";
+    this.auth = info.auth;
+    this.permission = info.permission;
   }
   status;
   detail;
+  /** Set when the failure is about the token: rejected (401) or missing a permission (403). */
+  auth;
+  /** With auth "missing-permission": the permission the call needed, when known. */
+  permission;
+};
+var PERMISSION_LABELS = {
+  issues: "Issues",
+  pull_requests: "Pull requests",
+  contents: "Contents",
+  checks: "Checks",
+  statuses: "Commit statuses",
+  metadata: "Metadata",
+  actions: "Actions",
+  deployments: "Deployments",
+  workflows: "Workflows",
+  administration: "Administration"
 };
+function permissionLabel(permission) {
+  return PERMISSION_LABELS[permission] ?? permission.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+}
+var TOKEN_REJECTED_MESSAGE = "Your GitHub token stopped working. It was revoked, regenerated or has expired: replace it with a new one.";
+function missingPermissionMessage(permission, action) {
+  const what = action ? `This token cannot ${action}.` : "This token is missing a permission for this.";
+  if (!permission) return `${what} Check its repository permissions on GitHub (Contents and Pull requests need Read and write).`;
+  return `${what} Add ${permissionLabel(permission)}: Read and write on GitHub.`;
+}
+function requiredPermission(path, acceptedHeader) {
+  if (acceptedHeader) {
+    const first = acceptedHeader.split(";")[0].split(",").map((p2) => p2.trim().split("=")[0].trim()).filter((p2) => p2 && p2 !== "metadata");
+    if (first.length) return first[0];
+  }
+  const p = path.replace(/[?#].*$/, "");
+  if (/\/repos\/[^/]+\/[^/]+\/(issues|labels|milestones)(\/|$)/.test(p)) return "issues";
+  if (/\/repos\/[^/]+\/[^/]+\/pulls(\/|$)/.test(p)) return "pull_requests";
+  if (/\/repos\/[^/]+\/[^/]+\/(rulesets(\/|$)|branches\/.+\/protection$)/.test(p)) return "administration";
+  if (/\/repos\/[^/]+\/[^/]+\/(contents|git|commits|branches|merges)(\/|$)/.test(p)) return "contents";
+  if (/\/repos\/[^/]+\/[^/]+\/(check-runs|check-suites)(\/|$)/.test(p)) return "checks";
+  if (/\/repos\/[^/]+\/[^/]+\/statuses(\/|$)/.test(p)) return "statuses";
+  if (/\/repos\/[^/]+\/[^/]+\/deployments(\/|$)/.test(p)) return "deployments";
+  if (/\/repos\/[^/]+\/[^/]+\/actions(\/|$)/.test(p)) return "actions";
+  return void 0;
+}
+var PERMISSION_DENIED = /not accessible by (personal access token|integration)|must have (admin|push|write) (rights|access)|write access to repository not granted|permission to .* denied/i;
+function classifyAuth(status, detail, opts = {}) {
+  if (status === 401 && opts.withToken !== false) return { auth: "rejected" };
+  if (status !== 403 || /rate limit|archived/i.test(detail)) return {};
+  if (opts.acceptedPermissions || PERMISSION_DENIED.test(detail)) {
+    return { auth: "missing-permission", permission: requiredPermission(opts.path ?? "", opts.acceptedPermissions) };
+  }
+  return {};
+}
 var DEFAULT_RETRY = { attempts: 3, baseDelayMs: 600, sleep: (ms) => new Promise((r) => setTimeout(r, ms)) };
 var isTransient = (status, detail) => status === 0 || status >= 500 || status === 429 || status === 403 && /secondary rate limit/i.test(detail);
 var API = "https://api.github.com";
@@ -2417,7 +2661,7 @@ var GitHubClient = class _GitHubClient {
     }
   }
   assertToken(what) {
-    if (!this.token) throw new GitHubError(401, `${what} needs a GitHub token (contents and pull requests, read and write, on this repository only). Without one Bridge is read-only.`);
+    if (!this.token) throw new GitHubError(401, `${what} needs a GitHub token (contents and pull requests, read and write, on this repository only). Without one Bridge is read-only.`, "no-token");
   }
   get repoPath() {
     return `/repos/${this.owner}/${this.name}`;
@@ -2466,7 +2710,12 @@ var GitHubClient = class _GitHubClient {
           detail
         );
       }
-      throw new GitHubError(res.status, friendlyMessage(res.status, detail), detail);
+      const info = classifyAuth(res.status, detail, {
+        path,
+        acceptedPermissions: res.headers?.get("x-accepted-github-permissions"),
+        withToken: Boolean(this.token)
+      });
+      throw new GitHubError(res.status, friendlyMessage(res.status, detail, info), detail, info);
     }
     return await res.json();
   }
@@ -2616,6 +2865,25 @@ var GitHubClient = class _GitHubClient {
       throw new GitHubError(422, `GitHub refused to mark #${n} ready for review${detail ? `: ${detail}` : "."} Use "Ready for review" on GitHub instead.`, detail);
     }
   }
+  /**
+   * Turns an open pull request back into a draft: the GraphQL mutation convertPullRequestToDraft (REST cannot set
+   * `draft` either), same token. No-op when it is already a draft.
+   */
+  async convertToDraft(n) {
+    this.assertToken("Turning a pull request back into a draft");
+    const pr = await this.request("GET", `${this.repoPath}/pulls/${n}`);
+    if (pr.draft === true) return;
+    if (pr.state && pr.state !== "open") throw new GitHubError(422, `Pull request #${n} is ${pr.state}: only an open one can go back to draft.`);
+    if (!pr.node_id) throw new GitHubError(422, `Pull request #${n} has no node id: convert it to draft on GitHub.`);
+    const r = await this.request("POST", "/graphql", {
+      query: "mutation($id: ID!) { convertPullRequestToDraft(input: { pullRequestId: $id }) { pullRequest { number isDraft } } }",
+      variables: { id: pr.node_id }
+    });
+    if (r?.errors?.length) {
+      const detail = r.errors.map((e) => e.message).filter(Boolean).join(" ");
+      throw new GitHubError(422, `GitHub refused to turn #${n} back into a draft${detail ? `: ${detail}` : "."} Use "Convert to draft" on GitHub instead.`, detail);
+    }
+  }
   async createPullRequest(input) {
     this.assertWritableBranch(input.head, input.base);
     const r = await this.request(
@@ -2645,6 +2913,11 @@ var GitHubClient = class _GitHubClient {
   async addComment(issueNumber2, body) {
     await this.request("POST", `${this.repoPath}/issues/${issueNumber2}/comments`, { body });
   }
+  /** Comments on an issue or pull request, oldest first (first 100: the sticky preview comment is posted early). */
+  async listIssueComments(issueNumber2) {
+    const r = await this.request("GET", `${this.repoPath}/issues/${issueNumber2}/comments?per_page=100`);
+    return r.map((c) => ({ id: c.id, body: c.body ?? "", author: c.user?.login ?? "unknown", updatedAt: c.updated_at }));
+  }
   // --- Issues (component change requests) ---------------------------------------------------
   async createIssue(input) {
     const r = await this.request("POST", `${this.repoPath}/issues`, {
@@ -2665,6 +2938,67 @@ var GitHubClient = class _GitHubClient {
   async getIssue(n) {
     return toIssue(await this.request("GET", `${this.repoPath}/issues/${n}`));
   }
+  /** Edits an issue: its body, or closes it with a reason ("not_planned" for a declined request). */
+  async updateIssue(n, patch) {
+    this.assertToken("Editing an issue");
+    return toIssue(await this.request("PATCH", `${this.repoPath}/issues/${n}`, patch));
+  }
+  /** Adds people to an issue's assignees (GitHub ignores logins that cannot be assigned: the result says who is). */
+  async addAssignees(n, logins) {
+    this.assertToken("Assigning an issue");
+    const r = await this.request("POST", `${this.repoPath}/issues/${n}/assignees`, { assignees: logins });
+    return (r.assignees ?? []).map((a) => a.login);
+  }
+  /** People with at least `permission` on the repository (reading the list needs push access). First 100. */
+  async listCollaborators(permission = "push") {
+    const r = await this.request("GET", `${this.repoPath}/collaborators?permission=${permission}&per_page=100`);
+    return r.map((c) => ({ login: c.login, avatarUrl: c.avatar_url ?? "" }));
+  }
+  /** Whether a token is sent with each request (TeamReader). */
+  get hasToken() {
+    return Boolean(this.token);
+  }
+  /** Every page of a list endpoint (per_page 100), up to `maxPages`. */
+  async paginate(path, maxPages = 20) {
+    const out = [];
+    const sep3 = path.includes("?") ? "&" : "?";
+    for (let page = 1; page <= maxPages; page++) {
+      const r = await this.request("GET", `${path}${sep3}per_page=100&page=${page}`);
+      out.push(...r);
+      if (r.length < 100) break;
+    }
+    return out;
+  }
+  /** Every member login of an organization team (needs read:org, or Members: Read on a fine-grained token). */
+  async listTeamMembers(org, slug) {
+    const r = await this.paginate(`/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(slug)}/members`);
+    return r.map((m) => m.login);
+  }
+  /** A user's membership of a team: "active", "pending", or null when GitHub says they are not a member (404). */
+  async getTeamMembership(org, slug, login) {
+    try {
+      const r = await this.request("GET", `/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(slug)}/memberships/${encodeURIComponent(login)}`);
+      return r.state === "active" ? "active" : "pending";
+    } catch (err) {
+      if (err instanceof GitHubError && err.status === 404) return null;
+      throw err;
+    }
+  }
+  /** "User" or "Organization" for a login, null when GitHub does not know it. */
+  async getAccountType(login) {
+    try {
+      const r = await this.request("GET", `/users/${encodeURIComponent(login)}`);
+      return r.type === "Organization" ? "Organization" : r.type === "User" ? "User" : null;
+    } catch (err) {
+      if (err instanceof GitHubError && err.status === 404) return null;
+      throw err;
+    }
+  }
+  /** The organization's teams this token can see. */
+  async listOrgTeams(org) {
+    const r = await this.paginate(`/orgs/${encodeURIComponent(org)}/teams`);
+    return r.map((t) => ({ slug: t.slug, name: t.name }));
+  }
   /** Create or update a binary file (base64 content) on a branch, e.g. a Figma export attached to a request. */
   async putBase64File(input) {
     this.assertWritableBranch(input.branch);
@@ -2800,6 +3134,27 @@ var GitHubClient = class _GitHubClient {
     const pending = checks.some((c) => c.status !== "completed");
     return { state: !checks.length ? "none" : failing ? "failure" : pending ? "pending" : "success", checks };
   }
+  /** Commit statuses of a commit, newest first (Vercel reports each project as "Vercel – <project>"). */
+  async listCommitStatuses(sha) {
+    const r = await this.request("GET", `${this.repoPath}/commits/${encodeRef(sha)}/statuses?per_page=100`);
+    return r.map((s) => ({ context: s.context, state: s.state, target_url: s.target_url ?? null, description: s.description ?? null }));
+  }
+  /**
+   * GitHub deployments of a commit with their latest status (environment "Preview – <project>", environment_url the
+   * preview). Latest per environment only, so it costs one read plus one per environment.
+   */
+  async listDeployments(sha) {
+    const list2 = await this.request("GET", `${this.repoPath}/deployments?sha=${encodeURIComponent(sha)}&per_page=30`);
+    const latest = /* @__PURE__ */ new Map();
+    for (const d of list2) if (!latest.has(d.environment)) latest.set(d.environment, d);
+    return Promise.all(
+      [...latest.values()].map(async (d) => {
+        const st = await this.request("GET", `${this.repoPath}/deployments/${d.id}/statuses?per_page=1`).catch(() => []);
+        const s = st[0];
+        return { id: d.id, environment: d.environment, state: s?.state ?? null, environmentUrl: s?.environment_url || null };
+      })
+    );
+  }
   async getPullRequest(n) {
     const r = await this.request("GET", `${this.repoPath}/pulls/${n}`);
     return { ...toSummary(r), body: r.body ?? "", mergeable: r.mergeable ?? null };
@@ -2826,7 +3181,44 @@ var GitHubClient = class _GitHubClient {
       "GET",
       `${this.repoPath}/commits/${encodeRef(ref)}/check-runs`
     );
-    return r.check_runs.map((c) => ({ id: c.id, name: c.name, status: c.status, conclusion: c.conclusion, url: c.html_url }));
+    return r.check_runs.map((c) => ({ id: c.id, name: c.name, status: c.status, conclusion: c.conclusion, url: c.html_url, ...c.app?.slug ? { app: c.app.slug } : {} }));
+  }
+  /** Rulesets that apply to the repository, without their rules (GET /rulesets; read access is enough). */
+  async listRulesets() {
+    const r = await this.request("GET", `${this.repoPath}/rulesets?includes_parents=true&per_page=100`);
+    return r.map(withRulesetUrl);
+  }
+  /** One ruleset with its rules. */
+  async getRuleset(id) {
+    return withRulesetUrl(await this.request("GET", `${this.repoPath}/rulesets/${id}`));
+  }
+  /** Creates a repository ruleset. Needs admin on the repo (fine-grained token: Administration read and write). */
+  async createRuleset(payload) {
+    this.assertToken("Protecting the library");
+    return withRulesetUrl(await this.request("POST", `${this.repoPath}/rulesets`, payload));
+  }
+  /** Replaces a repository ruleset (same permissions as createRuleset). */
+  async updateRuleset(id, payload) {
+    this.assertToken("Protecting the library");
+    return withRulesetUrl(await this.request("PUT", `${this.repoPath}/rulesets/${id}`, payload));
+  }
+  /**
+   * Classic branch protection of `branch`: the settings, null when the branch has none (404), undefined when this
+   * token cannot read them (403: the endpoint needs admin). On a 403 the public branch summary still tells
+   * whether the branch is protected at all: `protected: false` means there is nothing to read, so null.
+   */
+  async getBranchProtection(branch) {
+    try {
+      return await this.request("GET", `${this.repoPath}/branches/${encodeRef(branch)}/protection`);
+    } catch (err) {
+      if (!(err instanceof GitHubError)) throw err;
+      if (err.status === 404) return null;
+      if (err.status === 403 || err.status === 401) {
+        const b = await this.request("GET", `${this.repoPath}/branches/${encodeRef(branch)}`).catch(() => void 0);
+        return b?.protected === false ? null : void 0;
+      }
+      throw err;
+    }
   }
   /** Create a check run (needs a GitHub App token; personal tokens are refused by GitHub). */
   async createCheckRun(input) {
@@ -2868,7 +3260,9 @@ function toSummary(r) {
     ...typeof r.body === "string" ? { body: r.body } : {}
   };
 }
-function friendlyMessage(status, detail) {
+function friendlyMessage(status, detail, info = {}) {
+  if (info.auth === "rejected") return TOKEN_REJECTED_MESSAGE;
+  if (info.auth === "missing-permission") return missingPermissionMessage(info.permission);
   switch (status) {
     case 401:
       return "GitHub rejected the token. It may be expired or mistyped: create a new one and save it in Settings.";
@@ -2888,6 +3282,10 @@ function friendlyMessage(status, detail) {
       return `GitHub error ${status}${detail ? `: ${detail}` : ""}`;
   }
 }
+function withRulesetUrl(r) {
+  const href = r._links?.html?.href;
+  return href && !r.html_url ? { ...r, html_url: href } : r;
+}
 function toIssue(r) {
   return {
     number: r.number,
@@ -2903,6 +3301,122 @@ function toIssue(r) {
   };
 }
 
+// ../core/src/protection-github.ts
+async function loadProtection(client, defaultBranch) {
+  const rulesets = await client.listRulesets().then((list2) => Promise.all(list2.map((r) => r.enforcement === "disabled" || r.id === void 0 ? r : client.getRuleset(r.id)))).catch(() => null);
+  const classic = await client.getBranchProtection(defaultBranch).catch(() => void 0);
+  return protectionState(rulesets, classic, defaultBranch);
+}
+var rulesSettingsUrl = (owner, repo) => `https://github.com/${owner}/${repo}/settings/rules`;
+
+// ../core/src/usage.ts
+var VAR_RE = /var\(\s*(--[A-Za-z0-9_-]+)/g;
+var IMPORT_RE = /(?:import|export)\s[^'"]*?from\s*['"]([^'"]+)['"]|import\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+function cssVarsIn(text) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of text.matchAll(VAR_RE)) out.add(m[1]);
+  return [...out];
+}
+function importsIn(text) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of text.matchAll(IMPORT_RE)) out.add(m[1] ?? m[2]);
+  return [...out];
+}
+var norm2 = (p) => p.replace(/\\/g, "/").replace(/\/+$/, "");
+var isStory = (p) => /\.stories\.[cm]?[jt]sx?$/.test(p);
+var isTest = (p) => /\.(test|spec)\.[cm]?[jt]sx?$/.test(p);
+var isCss = (p) => /\.(css|scss|less)$/.test(p);
+var isScript = (p) => /\.[cm]?[jt]sx?$/.test(p);
+function componentOf(from, spec, componentsDir) {
+  if (!spec.startsWith(".")) return null;
+  const parts = from.split("/").slice(0, -1);
+  for (const seg of spec.split("/")) {
+    if (seg === "." || seg === "") continue;
+    if (seg === "..") parts.pop();
+    else parts.push(seg);
+  }
+  const abs = parts.join("/");
+  if (!abs.startsWith(`${componentsDir}/`)) return null;
+  return abs.slice(componentsDir.length + 1).split("/")[0] || null;
+}
+function componentForPath(path, componentsDir) {
+  const dir = norm2(componentsDir);
+  const p = norm2(path);
+  if (!p.startsWith(`${dir}/`)) return null;
+  const rest = p.slice(dir.length + 1).split("/");
+  return rest.length >= 2 ? rest[0] : null;
+}
+function buildUsageIndex(files, componentsDir) {
+  const dir = norm2(componentsDir);
+  const modules = {};
+  const vars = /* @__PURE__ */ new Map();
+  const imports = /* @__PURE__ */ new Map();
+  const storyImports = /* @__PURE__ */ new Map();
+  const globalVars = {};
+  const get = (m, k) => m.get(k) ?? m.set(k, /* @__PURE__ */ new Set()).get(k);
+  for (const f of files) {
+    const path = norm2(f.path);
+    const id = componentForPath(path, dir);
+    if (!id) {
+      if (isCss(path)) {
+        const v = cssVarsIn(f.text);
+        if (v.length) globalVars[path] = v.sort();
+      }
+      continue;
+    }
+    const mod = modules[id] ??= { id, dir: `${dir}/${id}`, files: [], vars: [], imports: [], storyImports: [] };
+    mod.files.push(path);
+    if (isTest(path)) continue;
+    for (const v of cssVarsIn(f.text)) get(vars, id).add(v);
+    if (!isScript(path)) continue;
+    for (const spec of importsIn(f.text)) {
+      const dep = componentOf(path, spec, dir);
+      if (!dep || dep === id) continue;
+      get(isStory(path) ? storyImports : imports, id).add(dep);
+    }
+  }
+  const byVar = {};
+  for (const mod of Object.values(modules)) {
+    mod.files.sort();
+    mod.vars = [...vars.get(mod.id) ?? []].sort();
+    mod.imports = [...imports.get(mod.id) ?? []].sort();
+    mod.storyImports = [...storyImports.get(mod.id) ?? []].filter((d) => !mod.imports.includes(d)).sort();
+    for (const v of mod.vars) (byVar[v] ??= []).push(mod.id);
+  }
+  for (const k of Object.keys(byVar)) byVar[k].sort();
+  return { componentsDir: dir, modules, byVar, globalVars };
+}
+function impactedModules(index, input) {
+  const reasons = /* @__PURE__ */ new Map();
+  const add = (id, reason, indirect) => {
+    const r = reasons.get(id);
+    if (r) {
+      if (!r.reasons.includes(reason)) r.reasons.push(reason);
+      r.indirect &&= indirect;
+    } else reasons.set(id, { reasons: [reason], indirect });
+  };
+  const changedVars = new Set(input.vars ?? []);
+  for (const v of changedVars) for (const id of index.byVar[v] ?? []) add(id, `uses ${v}`, false);
+  for (const f of input.files ?? []) {
+    const id = componentForPath(f, index.componentsDir);
+    if (id && index.modules[id]) add(id, `file changed: ${norm2(f)}`, false);
+  }
+  const renderedBy = /* @__PURE__ */ new Map();
+  for (const m of Object.values(index.modules)) for (const d of m.imports) (renderedBy.get(d) ?? renderedBy.set(d, []).get(d)).push(m.id);
+  const queue = [...reasons.keys()];
+  while (queue.length) {
+    const id = queue.shift();
+    for (const parent of renderedBy.get(id) ?? []) {
+      const known = reasons.has(parent);
+      add(parent, `renders ${id}`, true);
+      if (!known) queue.push(parent);
+    }
+  }
+  const globalHits = Object.entries(index.globalVars).map(([file, vs]) => ({ file, vars: vs.filter((v) => changedVars.has(v)) })).filter((g) => g.vars.length > 0);
+  const modules = [...reasons.entries()].map(([id, r]) => ({ id, reasons: r.reasons, indirect: r.indirect })).sort((a, b) => Number(a.indirect) - Number(b.indirect) || a.id.localeCompare(b.id));
+  return { modules, globalHits };
+}
+
 // ../core/src/explorations.ts
 var EXPLORATION_USE_CASES = [
   { value: "user-test", label: "Prototype for a user test", hint: "A coded prototype on a product staging branch, with the real components and tokens." },
@@ -2917,7 +3431,8 @@ var EXPLORATION_STATUS_LABEL = { active: "Running", promoted: "Promoted to revie
 var REQUEST_KINDS = [
   { value: "new-component", label: "New component", hint: "A component the design system does not have yet." },
   { value: "new-variant", label: "New variant", hint: "A size, tone or state the component does not have yet." },
-  { value: "prop-change", label: "Prop change", hint: "Add, rename or change a prop or its default." },
+  { value: "prop-change", label: "Option change (prop)", hint: "Add, rename or change an option (a prop in code) or its default." },
+  { value: "structure", label: "Structure change", hint: "A part was added, removed or moved." },
   { value: "visual", label: "Visual change", hint: "Spacing, radius, layout or icon placement." },
   { value: "token-binding", label: "Token change", hint: "The component should paint with another token." },
   { value: "bug", label: "Bug", hint: "It looks or behaves differently from the guidance." },
@@ -2949,6 +3464,7 @@ function jiraIssueFields(r, jira, issueUrl) {
       version: 1,
       content: [
         para(text(r.summary.trim() || r.title)),
+        ...r.line?.trim() ? [para(text(r.line.trim()))] : [],
         ...r.changes.map((c) => para(text(`${c.field}: ${c.before ?? "(none)"} -> ${c.after ?? "(removed)"}`))),
         para({ type: "text", text: "GitHub request", marks: [{ type: "link", attrs: { href: issueUrl } }] })
       ]
@@ -3213,14 +3729,14 @@ function union(a, b) {
 // ../visual/src/manifest.ts
 var COMMENT_MARKER = "<!-- bridge-visual-impact -->";
 function summarize(shots) {
-  const count = (s) => shots.filter((x) => x.status === s).length;
+  const count2 = (s) => shots.filter((x) => x.status === s).length;
   return {
     shots: shots.length,
-    changed: count("changed"),
-    unchanged: count("unchanged"),
-    added: count("added"),
-    removed: count("removed"),
-    errors: count("error"),
+    changed: count2("changed"),
+    unchanged: count2("unchanged"),
+    added: count2("added"),
+    removed: count2("removed"),
+    errors: count2("error"),
     maxPercent: shots.reduce((m, s) => Math.max(m, s.percent), 0)
   };
 }
@@ -3356,17 +3872,17 @@ var shotKey = (...parts) => parts.map((p) => p.toLowerCase().replace(/[^a-z0-9-]
 
 // ../visual/src/select.ts
 var NO_VISUAL = /(\.test\.[cm]?[jt]sx?|\.spec\.[cm]?[jt]sx?|\.docs\.json|\.mdx?|README[^/]*)$/i;
-var norm2 = (p) => p.replace(/^\.\//, "").replace(/\\/g, "/");
+var norm3 = (p) => p.replace(/^\.\//, "").replace(/\\/g, "/");
 var isAllStates = (s) => /--all-states$/.test(s.id) || /^all ?states$/i.test(s.name);
 function storyComponent(s, componentsDir) {
-  return componentForPath(norm2(s.importPath), componentsDir);
+  return componentForPath(norm3(s.importPath), componentsDir);
 }
 function selectImpact(input) {
   const { usage, stories } = input;
   const dir = usage.componentsDir;
   const lib = input.librarySrc.replace(/\/$/, "");
   const cap = input.maxStoriesPerComponent ?? 4;
-  const visualFiles = input.files.map(norm2).filter((f) => !NO_VISUAL.test(f));
+  const visualFiles = input.files.map(norm3).filter((f) => !NO_VISUAL.test(f));
   const vars = [...new Set(input.tokens.map((t) => input.cssVar(t.path)))].sort();
   const impact2 = impactedModules(usage, { vars, files: visualFiles });
   let fallback = null;
@@ -3406,7 +3922,7 @@ function selectImpact(input) {
   return {
     tokens: input.tokens,
     vars,
-    files: input.files.map(norm2),
+    files: input.files.map(norm3),
     components: components.map((c) => ({ id: c.id, reasons: c.reasons, indirect: c.indirect })),
     stories: [...new Set(picked)],
     fallback,
@@ -3425,7 +3941,7 @@ function storiesFromSource(files) {
     if (!title) continue;
     for (const m of f.text.matchAll(/export\s+const\s+([A-Z]\w*)\s*[:=]/g)) {
       const name = m[1];
-      out.push({ id: storyId(title, name), title, name: name.replace(/([a-z0-9])([A-Z])/g, "$1 $2"), importPath: `./${norm2(f.path)}` });
+      out.push({ id: storyId(title, name), title, name: name.replace(/([a-z0-9])([A-Z])/g, "$1 $2"), importPath: `./${norm3(f.path)}` });
     }
   }
   return out;
@@ -4232,8 +4748,9 @@ Usage:
                      GitHub token: the branch and the draft pull request on GitHub. Without one, in a git repo:
                      a local branch only, nothing pushed
   bridge explore list [--all] [--json]
-                     running and promoted explorations, with previews, the snapshot install command and the
-                     requests implemented on each (--all: closed ones too)
+                     running and promoted explorations, with the preview links Vercel reports, the install
+                     command from the pull request (once the snapshot is built) and the requests implemented
+                     on each (--all: closed ones too)
   bridge explore promote <name|#pr> [--dry-run] [--json]
                      ready for review, tier labels, exploration label and note removed (never merges)
   bridge explore close <name|#pr> [--json]
@@ -4249,6 +4766,7 @@ async function context2(root, io) {
   const token = io.env.BRIDGE_GITHUB_TOKEN || io.env.GITHUB_TOKEN || io.ghToken();
   return BridgeContext3.create({ root, ...token ? { token } : {}, ...io.fetch ? { fetch: io.fetch } : {} });
 }
+var exploreSource = (env) => ({ source: "cli", ...env.CLAUDECODE ? { agent: "claude" } : {} });
 var date = (iso) => iso ? iso.slice(0, 10) : "";
 async function runExplore(a, root, io = defaultIO()) {
   const sub = a._[1];
@@ -4264,7 +4782,7 @@ async function runExplore(a, root, io = defaultIO()) {
       if (!name || !purpose) throw new RequestUsageError('Usage: bridge explore start <name> --purpose "What you want to learn"');
       const useCase = flag2(a, "use-case");
       const ctx = await context2(root, io);
-      const r = await explorations.startExploration(ctx, { name, purpose, ...useCase ? { useCase } : {}, ...a.flags.experimental ? { experimental: a.flags.experimental } : {}, dryRun: has2(a, "dry-run") });
+      const r = await explorations.startExploration(ctx, { name, purpose, ...exploreSource(io.env), ...useCase ? { useCase } : {}, ...a.flags.experimental ? { experimental: a.flags.experimental } : {}, dryRun: has2(a, "dry-run") });
       if (json) return io.print(JSON.stringify(r, null, 2)), 0;
       if (r.status === "dry-run") {
         io.print(`Dry run, nothing written.
@@ -4279,8 +4797,7 @@ ${r.prBody}`);
       if (r.status === "started") {
         io.print(`Started ${r.branch}: draft pull request #${r.pr} ${r.url}`);
         io.print(`
-Install it in a product staging branch:
-  ${r.install.command}`);
+${r.install.note}`);
         for (const p of r.previews ?? []) io.print(`${p.label}: ${p.url}`);
       } else io.print(`Created the local branch ${r.branch} (${String(r.commit).slice(0, 7)}).`);
       io.print(`
@@ -4297,8 +4814,8 @@ Next: ${r.next}`);
 #${x.number} ${x.name}  ${EXPLORATION_STATUS_LABEL[x.status]}  ${x.branch}  @${x.author}  ${date(x.updatedAt)}`);
         if (x.purpose) io.print(`  ${x.purpose}`);
         io.print(`  ${x.url}`);
-        for (const p of x.previews) io.print(`  ${p.label}: ${p.url}`);
-        if (x.install.packages.length) io.print(`  Install: ${x.install.command}`);
+        for (const p of x.previews) io.print(`  ${p.label}: ${p.url ? `${p.url}${p.state === "building" ? " (building)" : p.state === "failed" ? " (build failed)" : ""}` : "link not reported by Vercel yet, see the pull request"}`);
+        if (x.install) io.print(x.install.command ? `  Install: ${x.install.command}` : `  Install: ${x.install.note}`);
         if (x.requests.length) io.print(`  Requests: ${x.requests.map((q) => `#${q.number}`).join(", ")}`);
       }
       for (const b of r.localBranches ?? []) io.print(`
@@ -4335,13 +4852,50 @@ ${EXPLORE_HELP}`);
   }
 }
 
+// src/protection.ts
+var UNKNOWN = { kind: "unknown", missing: ["review", "checks", "history", "deletion"] };
+async function protectionReport(opts) {
+  let state = UNKNOWN;
+  try {
+    const client = new GitHubClient(opts.repo, opts.token ?? "", opts.fetch, { attempts: 1, baseDelayMs: 0, sleep: async () => {
+    } });
+    state = await loadProtection(client, opts.defaultBranch);
+  } catch {
+    state = UNKNOWN;
+  }
+  const [owner, name] = opts.repo.split("/");
+  const lines = [`protection: ${protectionSentence(state)}`];
+  if (state.kind === "protected" && state.url) lines.push(`  ${state.url}`);
+  if (state.kind === "unprotected" || state.kind === "partial") lines.push(`  Protect it in Studio > Settings, or GitHub settings > Rules: ${rulesSettingsUrl(owner, name)}`);
+  return { state, lines };
+}
+
+// src/roles.ts
+async function rolesReport(opts) {
+  if (!teamsIn(opts.owners).length) return { teams: [], lines: [] };
+  const client = new GitHubClient(opts.repo, opts.token ?? "", opts.fetch, { attempts: 1, baseDelayMs: 0, sleep: async () => {
+  } });
+  const states = await new TeamDirectory(client).resolve(opts.owners);
+  const teams = Object.values(states);
+  const group = (entries) => entries.length ? entries.map((e) => entryLabel(e, states)).join(", ") : "nobody listed";
+  const lines = [`roles: design owners ${group(opts.owners.design)}; tech owners ${group(opts.owners.tech)}`];
+  for (const t of teams) if (t.status === "unreadable") lines.push(`  warn   team-unreadable  ${t.message}`);
+  return { teams, lines };
+}
+
 // src/index.ts
 import { brand, BridgeContext as BridgeContext4, CONFIG_FILE as CONFIG_FILE2, core, detectConfig, GitRefSource, history as hist, LocalSource, ops, optionsFromArgv, serveStdio, toConfigJson, VERSION } from "@bridge-ds/mcp";
+var MCP_PACKAGE = "@bridge-ds/mcp";
 var HELP = `bridge ${VERSION}: design system as code, for you and your Claude
 
 Usage:
   bridge init [--force]               write bridge.config.json (detected) and .mcp.json for Claude Code
-  bridge check [--json] [--strict]    validate tokens + contrast gate. Exit 0 ok, 1 failures, 2 setup error
+  bridge check [--json] [--strict] [--offline]
+                                      validate tokens + contrast gate, and say whether the library is
+                                      protected (reviewed pull requests only) and who is in the GitHub
+                                      teams named as owners, reporting teams it cannot read (neither
+                                      changes the exit code; --offline skips both). Exit 0 ok, 1 failures,
+                                      2 setup error
   bridge tokens <query> [--json]      search tokens by name, description or value
   bridge diff <base> [--json|--md]    designer-readable token diff: working tree vs <base> (git ref)
   bridge propose --title "..." --set path=value [--set ...] [--file f | --mode theme=dark]
@@ -4408,7 +4962,7 @@ function parse(argv) {
       const [k, inline] = a.slice(2).split(/=(.*)/s, 2);
       const next = argv[i + 1];
       const fileArg = k === "json" && /\.json$/i.test(next ?? "") || k === "md" && /\.(md|markdown)$/i.test(next ?? "");
-      const takesValue = inline === void 0 && next !== void 0 && !next.startsWith("--") && (fileArg || !["force", "json", "md", "strict", "dry-run", "help", "fix", "write", "no-regress", "plan", "keep-unchanged", "restore-conflicts", "breaking", "claude", "all"].includes(k));
+      const takesValue = inline === void 0 && next !== void 0 && !next.startsWith("--") && (fileArg || !["force", "json", "md", "strict", "dry-run", "help", "fix", "write", "no-regress", "plan", "keep-unchanged", "restore-conflicts", "breaking", "claude", "all", "offline"].includes(k));
       (out.flags[k] ??= []).push(inline ?? (takesValue ? argv[++i] : "true"));
     } else out._.push(a);
   }
@@ -4437,18 +4991,19 @@ async function init(a, root) {
   }
   const serverJs = fileURLToPath(new URL("./index.js", import.meta.resolve("@bridge-ds/mcp")));
   const relServer = relative4(root, serverJs);
-  const inRepo = !relServer.startsWith("..");
+  const inRepo = !relServer.startsWith("..") && !isAbsolute(relServer);
+  const server = (dir) => inRepo ? { command: "node", args: [relServer, "--root", dir] } : { command: "npx", args: ["-y", MCP_PACKAGE, "--root", dir] };
   const mcpPath = join5(root, ".mcp.json");
   const existing = existsSync5(mcpPath) ? JSON.parse(await readFile5(mcpPath, "utf8")) : {};
-  existing.mcpServers = { ...existing.mcpServers ?? {}, bridge: { command: "node", args: [inRepo ? relServer : serverJs, "--root", "."] } };
+  existing.mcpServers = { ...existing.mcpServers ?? {}, bridge: server(".") };
   await writeFile4(mcpPath, `${JSON.stringify(existing, null, 2)}
 `);
   print(`Wrote .mcp.json: Claude Code picks up the "bridge" server next time it starts in ${root}.`);
+  const desktop = inRepo ? { command: "node", args: [serverJs, "--root", root] } : server(root);
   print("\nClaude Desktop: add this to claude_desktop_config.json (Settings > Developer > Edit config):");
-  print(JSON.stringify({ mcpServers: { bridge: { command: "node", args: [serverJs, "--root", root] } } }, null, 2));
+  print(JSON.stringify({ mcpServers: { bridge: desktop } }, null, 2));
   print("\nOr with the Claude Code CLI:");
-  print(`  claude mcp add bridge -- node ${serverJs} --root ${root}`);
-  print("(Once @bridge-ds/mcp is published: claude mcp add bridge -- npx -y @bridge-ds/mcp)");
+  print(`  claude mcp add bridge -- ${desktop.command} ${desktop.args.join(" ")}`);
 }
 async function check(a, root) {
   const ctx = await BridgeContext4.create({ root });
@@ -4456,8 +5011,10 @@ async function check(a, root) {
   const c = await ops.checkContrast(ctx, {});
   const warnings = "warnings" in v ? v.warnings ?? [] : [];
   const failed = !v.valid || "failing" in c && (c.failing ?? 0) > 0 || has3(a, "strict") && warnings.length > 0;
+  const protection = await protectionOf(a, root, ctx);
+  const roles = await rolesOf(a, root, ctx);
   if (has3(a, "json")) {
-    print(JSON.stringify({ ok: !failed, validation: v, contrast: c }, null, 2));
+    print(JSON.stringify({ ok: !failed, validation: v, contrast: c, ...protection ? { protection: protection.state } : {}, ...roles?.teams.length ? { teams: roles.teams } : {} }, null, 2));
     return failed ? 1 : 0;
   }
   print(`tokens: ${v.tokens} in ${v.files} files, ${v.modeCombinations} mode combinations`);
@@ -4469,9 +5026,27 @@ async function check(a, root) {
     const tight = c.tightest?.[0];
     if (tight) print(`  tightest: ${tight.pair} [${tight.modes}] ${tight.ratio}:1 (min ${tight.min})`);
   } else print(`contrast: ${c.message}`);
+  for (const line of protection?.lines ?? []) print(line);
+  for (const line of roles?.lines ?? []) print(line);
   print(failed ? "FAIL" : "OK");
   return failed ? 1 : 0;
 }
+async function protectionOf(a, root, ctx) {
+  if (has3(a, "offline") || process.env.BRIDGE_OFFLINE === "1") return void 0;
+  const { config } = await ctx.config();
+  const repo = config.repo ? `${config.repo.owner}/${config.repo.name}` : await originRepo(root);
+  if (!repo) return void 0;
+  const token = process.env.BRIDGE_GITHUB_TOKEN || process.env.GITHUB_TOKEN || void 0;
+  return protectionReport({ repo, defaultBranch: config.repo?.defaultBranch ?? "main", token });
+}
+async function rolesOf(a, root, ctx) {
+  if (has3(a, "offline") || process.env.BRIDGE_OFFLINE === "1") return void 0;
+  const { config } = await ctx.config();
+  const repo = config.repo ? `${config.repo.owner}/${config.repo.name}` : await originRepo(root);
+  if (!repo) return void 0;
+  const token = process.env.BRIDGE_GITHUB_TOKEN || process.env.GITHUB_TOKEN || void 0;
+  return rolesReport({ repo, owners: config.governance.owners, token });
+}
 async function tokens(a, root) {
   const q = a._.slice(1).join(" ");
   if (!q) throw new UsageError("bridge tokens <query>");
@@ -4834,7 +5409,7 @@ async function main() {
   if (cmd === "explore") return runExplore(a, root);
   if (!cmd || has3(a, "help") || cmd === "help") {
     print(HELP);
-    return cmd ? 0 : 2;
+    return cmd || has3(a, "help") ? 0 : 2;
   }
   if (cmd === "--version" || cmd === "version") return print(VERSION), 0;
   switch (cmd) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge-ds/cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "bridge CLI: set up Bridge in a design system repo, check tokens in CI, search and diff tokens, propose changes, start the MCP server.",
   "license": "MIT",
@@ -43,8 +43,8 @@
     "build:package": "node ../../scripts/build-packages.mjs cli"
   },
   "dependencies": {
-    "@bridge-ds/mcp": "^0.2.0",
-    "@bridge-ds/visual": "^0.2.0",
+    "@bridge-ds/mcp": "^0.3.1",
+    "@bridge-ds/visual": "^0.2.2",
     "typescript": "5.9.3"
   },
   "devDependencies": {