@bridge-ds/mcp 0.8.4 → 0.9.0

package/README.md

@@ -12,7 +12,7 @@ with your own token.
 From npm, nothing to build:
 
 ```sh
-npx -y @bridge-ds/mcp --repo owner/name                  # GitHub repo, read-only
+npx -y @bridge-ds/mcp --repo owner/name                  # GitHub repo: your gh sign-in, else read-only
 GITHUB_TOKEN=... npx -y @bridge-ds/mcp --repo owner/name # GitHub repo, can open PRs
 npx -y @bridge-ds/mcp --root .                           # local folder (default: current directory)
 npx -y @bridge-ds/mcp --help
@@ -43,59 +43,102 @@ Working on the server itself: `npm run mcp:build` in a clone of this repo builds
 
 ## Tools
 
-| Tool | What it does |
-| --- | --- |
-| `bridge_get_config` | Source, write access, tiers, modes, the effective `bridge.config.json` |
-| `bridge_list_tokens` | Tokens with resolved values, filtered by tier, `$type`, path prefix, mode |
-| `bridge_get_token` | One token: value per mode with alias chain, defining files, tokens aliasing it, components using it |
-| `bridge_search_tokens` | By words, CSS variable or value (exact and near colors) |
-| `bridge_check_contrast` | The contrast gate in every brand x theme; with `edits`, before/after and new failures |
-| `bridge_validate_tokens` | DTCG shapes, names, broken/circular aliases, type mismatches, light/dark parity |
-| `bridge_list_components` | Components with family and summary |
-| `bridge_get_component` | Props parsed from TypeScript, docs.json usage guidance, CSS variables used |
-| `bridge_draft_docs` | docs.json pre-fill from the code (props, tokens, anatomy, contrast, changelog line, missing keys) and a prompt to write the prose; writes nothing |
-| `bridge_get_design_language` | Sections of the design language doc |
-| `bridge_get_guidelines` | AGENTS.md rules, risk tiers, what Bridge enforces |
-| `bridge_propose_token_change` | Edits, validation, contrast, tier, changeset, PR body; branch (local) or PR (remote) |
-| `bridge_list_brands` | Brands: slug, name, default, primary action color, theme override files |
-| `bridge_plan_brand` | Dry run of a new brand: generated ramps, contrast for every theme, files, tier 3, PR body |
-| `bridge_propose_brand` | The new brand as a local `bridge/brand-<slug>` branch or a draft PR; blocked when a pair fails |
-| `bridge_list_reviews` | Open PRs (Bridge ones flagged) and local `bridge/*` branches |
-| `bridge_get_review` | Diff table, contrast before/after, impact, tier check, CI status, approvals |
-| `bridge_review_pr` | Comment, approve or request changes (token required; `bridge_review_branch` is the designer version) |
-| `bridge_scaffold_component` | New component folder per the repo checklist |
-| `bridge_visual_impact` | Before/after screenshots of the impacted stories and admin screens, pixel diff, manifest (local, needs Chrome; `plan` for the selection only) |
-| `bridge_get_history` | Token history: versions, merged PRs and commits, who, when, why, tier |
-| `bridge_get_token_history` | Every change of one token, before and after per mode |
-| `bridge_plan_revert` | Dry run of a revert (or a one-token restore) against the current base, conflicts shown |
-| `bridge_propose_revert` | The revert as a local bridge/* branch or a draft PR labelled revert |
-| `bridge_audit` | Adoption in a product folder or file (local): CSS, SCSS, Less, TS/JS, TSX/JSX, Astro, Vue and Svelte. Token and component adoption, hardcoded values with the closest token, foreign and native components with the DS one to use, top files and fixes; `allowlist` and `bridge-audit-ignore-next-line: reason` comments leave known exceptions out, listed under `ignored` |
-| `bridge_list_requests` | Component change requests (issues labeled `component-change`) with status and linked pull requests |
-| `bridge_get_request` | One request with the component's files and a brief to implement it in a pull request that says "Closes #n" |
-| `bridge_create_request` | File a request as an issue labeled `component-change` (token required; `dryRun` previews; `exploration` targets an exploration branch) |
-| `bridge_start_exploration` | Start an exploration: `explore/<name>` branch and a draft pull request labeled `exploration`, previews and a snapshot package, never merged as is |
-| `bridge_list_explorations` | Explorations with status, previews, the snapshot install command and linked requests |
-| `bridge_promote_exploration`, `bridge_close_exploration` | Promote an exploration to review, or close it |
-| `bridge_list_products` | Products (`products` in bridge.config.json) and the one the current folder belongs to |
-| `bridge_what_needs_me` | The review queue, the branches where you act now first |
-| `bridge_branch_status` | One branch: status, approvals, tests, main, whether you may merge, next step |
-| `bridge_list_comments`, `bridge_comment` | Read the conversation and line threads; comment or reply |
-| `bridge_send_for_review`, `bridge_back_to_draft` | Ready for review, or back to draft (the author) |
-| `bridge_review_branch` | Approve, request changes or comment on the version seen |
-| `bridge_ask_someone_else` | Ask the other people who can give the missing approvals to review |
-| `bridge_merge_branch` | Merge through Studio's gate; owner override with a reason posted first (token required) |
-| `bridge_close_branch`, `bridge_reopen_branch` | Close without merging; reopen with Studio's rule |
-| `bridge_update_from_main` | Update from main; token conflicts to pick, code conflicts left to a developer |
-| `bridge_try_branch` | Product previews Vercel reported, the install command and a message for a product team |
-| `bridge_combine_branches` | Try 2 to 4 token branches together (writes nothing) |
-| `bridge_save_docs` | Save usage guidance on a new branch for review, or on an open branch |
-| `bridge_get_settings` | Roles, who ships, owner override, protection, products |
-| `bridge_figma_coverage` | Which components are in Figma, code images for the fidelity check |
+<!-- tools:start (generated from the server: npm run readme:tools -w @bridge-ds/mcp) -->
+
+73 tools. "writes" tools change files, branches, pull requests or issues; they need a token in remote mode and only run when the person asked.
+
+| Tool | Access | What it does |
+| --- | --- | --- |
+| `bridge_apply_suggestion` | writes | Apply a Bridge suggestion to today's code ("Apply Bridge suggestion #42"). |
+| `bridge_ask_someone_else` | writes | Ask the other people who can give the missing approvals to review a branch, as "Ask someone else to review" in the Studio review queue, and take the person off its requested reviewers. |
+| `bridge_audit` | reads | Measure how a product codebase uses this design system (local only). |
+| `bridge_back_to_draft` | writes | Take a branch out of review back to draft, as in Studio's More menu. |
+| `bridge_branch_status` | reads | One branch in review as Studio shows it: its product, status (draft, in review, needs design or tech approval, blocked by tests, conflict, ready to merge, merged, closed), approvals (Tier 1: one owner approval; a branch that applies an approved suggestion carries its approvals), tests, how it stands against main, whether the person may merge it (the same verdict as the Merge button and status chips in Studio), and the next step. |
+| `bridge_check_contrast` | reads | Run the repo's WCAG contrast gate (every pair in every brand x theme). |
+| `bridge_close_branch` | writes | Close a branch without merging it, as in Studio's More menu. |
+| `bridge_close_exploration` | writes | Close an exploration without merging it, as in Studio. |
+| `bridge_combine_branches` | reads | Combined preview of 2 to 4 token branches, as "Try together" in Studio: each branch's own token edits on the latest main, the tokens two branches set differently (pick one per key with picks), and the links that open the combination (the admin demo with the Bridge toolbar, the library views). |
+| `bridge_comment` | writes | Post a comment on a branch, or reply in the thread of a line comment (replyTo: its id from bridge_list_comments). |
+| `bridge_create_request` | writes | File a component change request as a GitHub issue labeled component-change (source: mcp), in the same format as Figma and Bridge Studio requests. |
+| `bridge_create_suggestion` | writes | File any change as a suggestion from its payload (schema bridge.suggestion/1: kind, title, summary, and tokens edits, docs, componentSpec or files). |
+| `bridge_draft_docs` | reads | Start or refresh a component's docs.json. |
+| `bridge_figma_changes` | reads | The library branches the DS Bridge Figma plugin opened for components changed in Figma (label from-figma), with where each stands: an exact token change (no AI, contrast gated), or a branch carrying the spec, waiting for Claude AI to draft the code, then drafted by Claude AI and reviewed by a person. |
+| `bridge_figma_coverage` | reads | Which components are in Figma, in Studio's words (Yes, Drafted, Auto layout, Not yet with the reason), and whether code images exist for the fidelity check the DS Bridge Figma plugin runs (its scores live in Figma). |
+| `bridge_figma_gaps` | reads | The components whose Figma build differs from their story (Differs) or cannot be checked (Can't check, with the reason), from the latest Check fidelity run of the DS Bridge plugin (the story shots are the referee), else from the measure's own check; a status fix in figma-fixes.json shows with its reason. |
+| `bridge_get_build_request` | reads | One build request, ready to build: what the designer sent (the request, before and after images, props needed, the spec when the issue keeps it), the status timeline, the linked pull request, the Jira key, the component files and `brief`, the prompt to build it in this repo. |
+| `bridge_get_component` | reads | One component: props parsed from TypeScript (type, default, description, allowed values), usage docs (summary, whenToUse, whenNotToUse, dos/donts with examples, accessibility, contentGuidelines, anatomy), CSS variables it uses, and story names. |
+| `bridge_get_config` | reads | Where the design system lives and what Bridge may do: source (local path or GitHub repo), write access, token tiers, modes (brand/theme/density...) and the full bridge.config.json. |
+| `bridge_get_design_language` | reads | The design language doc (principles, color, type, space, density, radius, elevation, motion, icons, voice, accessibility). |
+| `bridge_get_figma_change` | reads | One library branch sent from Figma: its spec (variant matrix, properties, bound variables per variant, layers, what code gave Figma before, the exact token swaps) and the brief to draft the code on that branch. |
+| `bridge_get_gap_case` | reads | One component's gap case: per differing variant, its story, args, state, shot and every difference with the part id, property, expected (code) and actual (Figma) and the delta in px, plus the figma-fixes.json schema. |
+| `bridge_get_guidelines` | reads | Rules for agents in this repo (AGENTS.md): always / ask before / never lists, token conventions, risk tiers, and what Bridge enforces. |
+| `bridge_get_history` | reads | History of the design tokens: merged token-changing PRs and commits (local git: first parent of HEAD; GitHub: PR merge commits), newest first, each with author, date, why (changeset summary, PR or commit body), version it shipped in, risk tier, semver bump, breaking flag and change counts, plus the timeline of design system versions. |
+| `bridge_get_request` | reads | One request, ready to implement: the parsed request (component, kind, summary, changes asked, Figma link, images), its status and linked pull requests, the component files found under the components directory, the agent rules file, and `brief`: the prompt to implement it in this repo. |
+| `bridge_get_review` | reads | Review a token change: designer-readable diff table, contrast before -> after, new validation errors, downstream impact, computed risk tier (and a warning if labelled lower), and for PRs the CI status, approvals and roles: who may approve design, approve tech and ship, with GitHub teams named and their size, and any team that cannot be read with the fix. |
+| `bridge_get_settings` | reads | What Studio Settings shows that is safe to read: who approves design and tech (GitHub teams named with their size), who may merge, the owner override (who, what reason), whether main is protected, the products, the preview apps and the visual impact mode. |
+| `bridge_get_suggestion` | reads | One suggestion: the change (tokens before and after, docs, component spec, files), the checks when suggested, links, its version (payloadSha: what approvals bind to), who approved it, which approvals are missing for its tier, reviews that no longer count (an older version, or not an owner), whether the machine-readable block was edited by hand, linked pull requests, and for a component spec the brief to implement it. |
+| `bridge_get_token` | reads | Everything about one token: CSS variable, type, tier, description, the files that define it, resolved value in every mode (brand x theme x density, collapsed where equal) with its alias chain, tokens that alias it, and components whose CSS uses it (directly or through a component token). |
+| `bridge_get_token_history` | reads | Every recorded change of one token, newest first, renames followed: value before and after per mode (raw and resolved CSS), who, when, the PR and why. |
+| `bridge_link_suggestion` | writes | Record the pull request (or branch, or commit) that applies a suggestion: a comment on the issue and the "suggestion: applying" label. |
+| `bridge_list_brands` | reads | Brands of the repo: slug, name, default, primary action color and theme override files. |
+| `bridge_list_build_requests` | reads | Build requests: structure changes pushed from Figma (a new variant, option, layout or component) that developers build, as GitHub issues labeled component-change and bridge-build, plus library branches from Figma waiting for a developer. |
+| `bridge_list_comments` | reads | The conversation on a branch and its line comment threads, with the ids to reply to (bridge_comment with replyTo). |
+| `bridge_list_components` | reads | List design system components with family and one-line summary (what it is for). |
+| `bridge_list_explorations` | reads | Explorations of the repo (draft pull requests labeled exploration on explore/* branches): name, purpose, status (active: running; promoted: ready for review; closed), author, last update, for running ones the preview links Vercel reports (url null while it has not reported one yet) and the install command a product staging branch uses, read from the preview comment on the pull request (state building until the snapshot of the latest commit is published, never a guessed command), and the component requests implemented on each. |
+| `bridge_list_products` | reads | The products of this design system (bridge.config.json "products": name, repo or folder, preview link pattern, framework) and the one the current folder or repo belongs to, which tools that start work use when no product is given. |
+| `bridge_list_requests` | reads | Component change requests: GitHub issues labeled component-change (from Figma, Bridge Studio, the CLI or Claude). |
+| `bridge_list_reviews` | reads | Open pull requests on the repo (flagging the ones Bridge opened) and, locally, the bridge/* proposal branches. |
+| `bridge_list_suggestions` | reads | Suggestions in the repo: GitHub issues labeled bridge-suggestion, each an exact change (tokens, docs, a component spec, a brand, a revert, settings) that the owners approve and a developer applies. |
+| `bridge_list_tokens` | reads | List tokens with their resolved CSS value in one mode. |
+| `bridge_mark_figma_change_drafted` | writes | After you pushed the code for a component change from Figma to its branch: mark its pull request ready for review, label it drafted-by-claude (no longer waiting-for-claude) and say so in its description, in one step, for a person to review. |
+| `bridge_merge_branch` | writes | Merge a branch into main through the same gate as Studio's Merge button: tests pass, the approvals its tier needs (Tier 1: one owner approval; Tier 2 and 3: design and tech; a branch that applies an approved suggestion with Closes #n carries its approvals while the suggestion stays approved and the tier is not higher), no changes requested, no conflict, not a draft or an exploration, and the person holds the right to ship (governance.rights). |
+| `bridge_missing_pieces` | writes | Check a product branch (an exploration started for a product) against the library: the adoption audit on each product file it changes, at its start and at its head, keeps what the branch added. |
+| `bridge_open_library_branch` | writes | Turn one recorded missing piece into a library branch linked to the product branch, as Bridge Studio does: a token piece opens a token change (same gate and body as bridge_propose_token_change, a draft for design and tech review) and the product branch takes its preview; a variant opens a library exploration with the brief to build it (build it there, then bridge_use_library_preview); a new component opens a component request. |
+| `bridge_pending_drafts` | reads | Change texts a designer asked their own Claude to write from the DS Bridge Figma plugin ("Draft with my Claude"), waiting on the bridge-requests branch. |
+| `bridge_plan_brand` | reads | Dry run of a new brand: the brand token file (generated primary and neutral ramps, radius and font roles), copied theme overrides, the bridge.config.json change, every contrast pair for the new brand in light and dark (ok, or the failing pairs), validation issues, the risk tier (always Tier 3, minor) and the PR body. |
+| `bridge_plan_revert` | reads | What undoing a merged token change takes, computed against the CURRENT base branch (not a blind git revert): the inverse edits, conflicts where a token changed again later (with the later PR), changes already undone, contrast before and after, new validation errors, risk tier, files and the PR body ("Revert: <title>", links the original PR). |
+| `bridge_product_branch` | reads | A product branch as Studio shows it: the summary sentence, each linked library branch with its status and reviewers, what its preview means for the product branch and the next action, and the pieces with no library branch yet. |
+| `bridge_promote_exploration` | writes | Promote an exploration (explore/<name>) to review, as in Studio: the draft becomes ready for review with its tier labels, the exploration label and note go, and the component requests it implements are linked so they close when it merges. |
+| `bridge_propose_brand` | writes | Propose a new brand as a reviewable change. |
+| `bridge_propose_figma_fixes` | writes | Opens the accepted fixes for review like other Bridge changes: figma-fixes.json with them on a new bridge/* branch and a draft pull request labelled drafted-by-claude, figma-fixes and its tier (locally: a new local branch, never pushed). |
+| `bridge_propose_revert` | writes | Plans the revert (or restore) like bridge_plan_revert, then: local repo, commits to a new local bridge/* branch without touching your working tree (never pushes); GitHub with token, new bridge/* branch and a PR labelled revert and its tier (draft for Tier 2 and 3). |
+| `bridge_propose_token_change` | writes | Propose token edits as a reviewable change. |
+| `bridge_push_figma_component` | writes | What the DS Bridge plugin Push tab does, from a structured diff of a Figma component (the v 1 spec shape: component, figmaName, coded, kind, title, summary, changes, rebinds, needsCode, unknown, variantAxes, properties, bindings, anatomy). |
+| `bridge_reopen_branch` | writes | Reopen a closed branch, with Studio's rule: its author or an owner with write access, and only while its work is still on GitHub. |
+| `bridge_review_branch` | writes | Approve, request changes or comment on a branch, as the review box in Studio, on the version the person saw, under their GitHub account. |
+| `bridge_review_pr` | writes | Post a review on a PR as the token owner: comment, approve or request changes, with a body. |
+| `bridge_review_suggestion` | writes | Approve, request changes on, comment on or decline a suggestion, as the person whose GitHub token the server has. |
+| `bridge_save_docs` | writes | Save a component's usage guidance (docs.json sections: summary, whenToUse, whenNotToUse, dos, donts, accessibility, contentGuidelines, anatomy, preview) the way the Library edit mode does: merged into the docs on the branch, cleaned and checked (a summary, no empty items, no em dash). |
+| `bridge_scaffold_component` | writes | Generate a new component folder per the repo checklist: Name.tsx (forwardRef, typed props), Name.module.css (existing tokens only), stories with AllStates, docs.json with the reference component's keys, a keyboard + axe test when interactive, index.ts. |
+| `bridge_search_tokens` | reads | Find tokens by words in the path or description ("danger text", "focus ring"), by CSS variable, or by value ("#c2410c", "16px": exact and near colors). |
+| `bridge_send_for_review` | writes | Ask for review: a draft branch becomes ready for review, as "Mark as ready" in Studio. |
+| `bridge_start_exploration` | writes | Start an exploration: a branch explore/<slug> from the default branch with a note file, and a DRAFT pull request labeled exploration that gets per-branch previews and a snapshot package a product staging branch installs (npm i @bridge-ds/react@<snapshot>). |
+| `bridge_switch_to_published` | writes | Once its library branches shipped, bring main into the product branch (GitHub update branch): it stops carrying the library change and uses the shipped one. |
+| `bridge_try_branch` | reads | Try a branch before it merges: the preview link of each product Vercel reported for it (the admin demo opens with the Bridge toolbar on, as "Try it in the product" in Studio), the other previews, and "Share with a product team": the install command a product team runs in a staging branch, or why there is none yet, with a ready-to-paste message. |
+| `bridge_try_figma_fix` | reads | Checks proposed fixes offline, nothing is written: validates them (the strict figma-fixes.json validator), lays them on the measure, rebuilds the set the way the plugin pulls it, and compares each differing variant with what the code renders. |
+| `bridge_update_from_main` | writes | Bring the latest main into a branch, as "Update from main" in Studio. |
+| `bridge_use_library_preview` | writes | The product branch takes the latest commits of the library branch of a piece (Bridge merges it in), so the product preview shows the real library change before it ships. |
+| `bridge_validate_tokens` | reads | Validate tokens: DTCG 2025.10 shape per $type, names, broken and circular aliases in every mode, alias type mismatches, missing layer files, and mode parity (a semantic token must exist in both light and dark). |
+| `bridge_visual_impact` | writes | Screenshots what a design system change touches, before and after, and pixel-diffs them. |
+| `bridge_what_needs_me` | reads | The review queue, as Studio counts it (open branches, without running explorations and the release automation), each with its status in designer words, and first the ones where the person acts now: an approval they can give, their own branch blocked, ready for them to merge. |
+| `bridge_write_drafts` | writes | Write the titles, summaries and change lines (or, for docs items, the docs sections or the rewritten passage) you drafted for a session from bridge_pending_drafts. |
+
+<!-- tools:end -->
 
 Resources: `bridge://tokens/resolved`, `bridge://design-language`, `bridge://guidelines`,
 `bridge://components/{name}`. Prompts: `review-token-pr`, `add-component`, `audit-ui-for-tokens`,
 `migrate-file-to-ds`.
 
+### The merge gate is Studio's
+
+`bridge_branch_status`, `bridge_merge_branch` and `bridge_what_needs_me` (and `bridge branch status|merge|list` in the
+CLI) read the same verdict as Studio's branch page and status chips: `branchVerdict` in `@bridge-ds/core`. Tier 1
+needs one owner approval; Tier 2 and 3 a design owner and a tech owner. A branch whose body says `Closes #<n>` for an
+approved suggestion carries that suggestion's approvals while it stays approved and the branch's tier is not higher.
+The owner override (`overrideReason`) is for owners named in `governance.override.allowed` only, skips missing
+approvals only, and always needs a reason of at least `minReasonLength` characters (20 by default). See
+[GOVERNANCE.md](../../docs/GOVERNANCE.md#one-verdict-everywhere).
+
 ## Configuration
 
 `bridge.config.json` at the repo root says where tokens live, how they layer per mode, and what Bridge may

package/dist/branches.d.ts

@@ -1,4 +1,4 @@
-import { type BridgeConfig, type GitHubClient, type MergeChoices, type ProductConfig, type ReviewStatusKind } from '@bridge-ds/core';
+import { tokenFileChanges, type FigmaPush, type PullRequestFile, type BridgeConfig, type GitHubClient, type MergeChoices, type ProductConfig, type ReviewStatusKind } from '@bridge-ds/core';
 import type { BridgeContext } from './context.js';
 /** What a write needs from the token, per action, in the words GitHub's token settings use. */
 export declare const RIGHTS: {
@@ -19,6 +19,29 @@ export declare function writer(ctx: BridgeContext, what: string, need: string):
 export declare function branchNumber(input: number | string): number;
 /** The viewer of the token, or null without one (or when GitHub does not say). */
 export declare function viewerOf(ctx: BridgeContext, gh: GitHubClient): Promise<string | null>;
+type PullForTokens = {
+    labels: string[];
+    body: string;
+    baseRef: string;
+    headSha: string;
+};
+/**
+ * The token changes of a pull request, from its token files at the base and the head (never from its body). A renamed
+ * token file, or a read that fails, leaves them unknown (null): the tech approval is then still needed.
+ */
+export declare function tokenChangesOf(gh: GitHubClient, config: BridgeConfig, pr: PullForTokens, files: PullRequestFile[], base: string | null | undefined): Promise<ReturnType<typeof tokenFileChanges> | null>;
+/**
+ * The Figma push facts of a pull request (docs/BUILD-REQUESTS.md), read the way Studio reads them: only for a push
+ * from the Figma plugin (labels or the "From Figma" block) or the pull request of a build request sent from Figma
+ * (its body closes one labeled source: figma). The token changes come from tokenChangesOf (`read`, when the caller
+ * already reads them).
+ */
+export declare function figmaPushFacts(gh: GitHubClient, config: BridgeConfig, pr: PullForTokens, files: PullRequestFile[], base: string | null | undefined, read?: () => Promise<ReturnType<typeof tokenFileChanges> | null>): Promise<FigmaPush | null>;
+/**
+ * Whether a pull request only changes token values (core isTokenValueChange, decision TV-1), whoever opened it: the
+ * design approval is then all it needs, as in Studio. Reads the token files only when its files could be one.
+ */
+export declare function tokenValuesFact(config: BridgeConfig, pr: Pick<PullForTokens, 'labels'>, files: PullRequestFile[], read: () => Promise<ReturnType<typeof tokenFileChanges> | null>): Promise<boolean>;
 /** Everything Studio reads about one branch to paint its header and decide its actions. */
 export declare function branchFacts(ctx: BridgeContext, gh: GitHubClient, n: number, viewer: string | null): Promise<{
     config: BridgeConfig;
@@ -26,13 +49,16 @@ export declare function branchFacts(ctx: BridgeContext, gh: GitHubClient, n: num
         body: string;
         mergeable: boolean | null;
         requestedReviewers: string[];
+        autoMerge: boolean;
     };
-    files: import("@bridge-ds/core").PullRequestFile[];
+    files: PullRequestFile[];
     ci: import("@bridge-ds/core").CiSummary;
     approvals: import("@bridge-ds/core").ApprovalSummary;
     tier: import("@bridge-ds/core").RiskTier | null;
     gate: import("@bridge-ds/core").MergeGate;
     status: ReviewStatusKind;
+    override: import("@bridge-ds/core").OverridePolicy;
+    suggestion: import("@bridge-ds/core").ApprovedSuggestion | null;
     fresh: import("@bridge-ds/core").Freshness;
     compare: {
         behindBy: number;
@@ -48,6 +74,7 @@ export declare function branchFacts(ctx: BridgeContext, gh: GitHubClient, n: num
     } | null;
     exploration: boolean;
     product: ProductConfig;
+    lookAgain: string[];
     lifecycle: import("@bridge-ds/core").PullState;
     write: boolean | null;
     repo: {
@@ -61,11 +88,22 @@ export declare function branchFacts(ctx: BridgeContext, gh: GitHubClient, n: num
         };
     } | null;
     solo: string | null;
+    lists: import("@bridge-ds/core").Owners;
+    figmaPush: FigmaPush | null;
+    tokenValues: boolean;
+    autoShip: boolean;
+    statusLabel: string;
 }>;
 /** One branch, the way Studio shows it: status, what blocks the merge and who acts, how it stands against main. */
 export declare function branchStatus(ctx: BridgeContext, a: {
     pr: number | string;
 }): Promise<{
+    next: string;
+    fromFigma?: {
+        scope: import("@bridge-ds/core").FigmaPushScope;
+        shipsByItself: boolean;
+        said: string;
+    } | undefined;
     pr: number;
     title: string;
     url: string;
@@ -79,13 +117,16 @@ export declare function branchStatus(ctx: BridgeContext, a: {
         kind: ReviewStatusKind;
         label: string;
     };
-    approvalNeeded: string;
+    approvalNeeded: string | null;
     approvals: {
         soloOwner?: string | undefined;
-        approvedBy: string[];
-        changesRequestedBy: string[];
+        carriedFrom?: string | undefined;
         design: boolean;
         tech: boolean;
+        owner: boolean;
+        lookAgain?: string[] | undefined;
+        approvedBy: string[];
+        changesRequestedBy: string[];
     };
     tests: {
         state: import("@bridge-ds/core").CiState;
@@ -109,7 +150,6 @@ export declare function branchStatus(ctx: BridgeContext, a: {
         allowed: boolean;
         blockedBy: string[];
     };
-    next: string;
 }>;
 /**
  * What needs me: the review queue (open branches minus running explorations and release automation), each with its
@@ -120,7 +160,7 @@ export declare function whatNeedsMe(ctx: BridgeContext, a?: {
 }): Promise<{
     viewer: string | null;
     summary: string;
-    branches: ({
+    branches: NonNullable<{
         pr: number;
         title: string;
         url: string;
@@ -140,7 +180,7 @@ export declare function whatNeedsMe(ctx: BridgeContext, a?: {
         statusLabel: string;
         yours: boolean;
         needsYou: string | null;
-    })[];
+    } | null>[];
 }>;
 /** The configured products, and the one the current folder or repo belongs to (the default for new work). */
 export declare function listProducts(ctx: BridgeContext): Promise<{
@@ -183,6 +223,10 @@ export declare function tryBranch(ctx: BridgeContext, a: {
         url: string | null;
         how: string;
     }[];
+    local: {
+        branch: string;
+        command: string;
+    } | null;
     previews: {
         app: keyof import("@bridge-ds/core").PreviewApps;
         label: string;
@@ -325,8 +369,9 @@ export declare function listComments(ctx: BridgeContext, a: {
 }>;
 /**
  * Merge, through the same gate as Studio's Merge button (tests, approvals for the tier, who may ship, conflicts,
- * drafts and explorations). With `overrideReason`, the owner override: only missing approvals are skipped, the reason is
- * posted on the branch first, and only people in governance.override.allowed may use it.
+ * drafts and explorations; core branchVerdict). With `overrideReason`, the owner override: only missing approvals are
+ * skipped, the reason (always required, at least `minReasonLength` characters, 20 by default) is posted on the branch
+ * first, and only the owners governance.override.allowed names may use it.
  */
 export declare function mergeBranch(ctx: BridgeContext, a: {
     pr: number | string;
@@ -336,6 +381,22 @@ export declare function mergeBranch(ctx: BridgeContext, a: {
     pr: number;
     status: "would-merge";
     said: string;
+    note: string;
+    blockedBy?: undefined;
+    skips?: undefined;
+} | {
+    pr: number;
+    status: "blocked";
+    blockedBy: string[];
+    said: string;
+    note: string;
+    skips?: undefined;
+} | {
+    pr: number;
+    status: "would-merge";
+    said: string;
+    note?: undefined;
+    blockedBy?: undefined;
     skips?: undefined;
 } | {
     warnings?: string[] | undefined;
@@ -343,12 +404,23 @@ export declare function mergeBranch(ctx: BridgeContext, a: {
     status: "merged";
     sha: string;
     said: string;
+    note?: undefined;
+    blockedBy?: undefined;
+    skips?: undefined;
+} | {
+    pr: number;
+    status: "blocked";
+    blockedBy: string[];
+    said: string;
+    note?: undefined;
     skips?: undefined;
 } | {
     pr: number;
     status: "would-override";
     skips: import("@bridge-ds/core").MissingApproval[];
     said: string;
+    note?: undefined;
+    blockedBy?: undefined;
 } | {
     warnings?: string[] | undefined;
     pr: number;
@@ -357,6 +429,8 @@ export declare function mergeBranch(ctx: BridgeContext, a: {
     sha: string;
     reasonUrl: string;
     said: string;
+    note?: undefined;
+    blockedBy?: undefined;
     skips?: undefined;
 }>;
 /** Close without merging (Studio More menu). The work stays on GitHub and the branch can be reopened. */
@@ -439,6 +513,7 @@ export declare function addableBranch(ctx: BridgeContext, n: number): Promise<{
         body: string;
         mergeable: boolean | null;
         requestedReviewers: string[];
+        autoMerge: boolean;
     };
     viewer: string;
     comment: (paths: string[]) => string;

package/dist/build-requests.d.ts

@@ -0,0 +1,96 @@
+import { type BuildFilter } from '@bridge-ds/core';
+import type { BridgeContext } from './context.js';
+export declare const BUILD_FILTERS: BuildFilter[];
+export declare function listBuildRequests(ctx: BridgeContext, a?: {
+    filter?: BuildFilter | undefined;
+    component?: string | undefined;
+    limit?: number | undefined;
+}): Promise<{
+    repo: string;
+    filter: BuildFilter;
+    summary: string;
+    total: number;
+    buildRequests: {
+        figma?: string | undefined;
+        jira?: string | undefined;
+        pull?: {
+            number: number;
+            url?: string | undefined;
+            state: string;
+        } | undefined;
+        url: string;
+        shippedAt?: string | undefined;
+        number: number;
+        kind: "issue" | "library branch";
+        component: string;
+        title: string;
+        status: import("@bridge-ds/core").BuildStatus;
+        statusLabel: string;
+        said: string;
+        builders: string[];
+        ageDays: number;
+        stale: boolean;
+    }[];
+}>;
+/**
+ * One build request, ready to build: what was sent (the request, before and after images, props needed, the spec when
+ * the issue keeps it), the status timeline, the linked pull request, the Jira key and `brief`, the prompt for Claude.
+ * A library branch from Figma waiting for a developer (direct mode) gives the spec and brief of that branch.
+ */
+export declare function getBuildRequest(ctx: BridgeContext, a: {
+    number: number;
+}): Promise<{
+    brief: string | null;
+    next: string;
+    spec?: (import("@bridge-ds/core").ComponentPushDiff & {
+        tokenEdits?: import("@bridge-ds/core").TokenEdit[];
+        reasons?: string[];
+    }) | undefined;
+    figma?: string | undefined;
+    jira?: string | undefined;
+    pull?: {
+        number: number;
+        url?: string | undefined;
+        state: string;
+    } | undefined;
+    url: string;
+    status: import("@bridge-ds/core").BuildStatus;
+    label: string;
+    said: string;
+    builders: string[];
+    ageDays: number;
+    stale: boolean;
+    timeline: import("@bridge-ds/core").BuildStatusEvent[];
+    number: number;
+    kind: "library branch";
+    component: string;
+    title: string;
+} | {
+    componentFiles: string[];
+    agentsFile: string;
+    brief: string;
+    next: string;
+    spec?: {} | null | undefined;
+    request: import("@bridge-ds/core").ComponentChangeRequest & {
+        build: import("@bridge-ds/core").BuildRequestExtra;
+    };
+    figma?: string | undefined;
+    jira?: string | undefined;
+    pull?: {
+        number: number;
+        url?: string | undefined;
+        state: string;
+    } | undefined;
+    url: string;
+    status: import("@bridge-ds/core").BuildStatus;
+    label: string;
+    said: string;
+    builders: string[];
+    ageDays: number;
+    stale: boolean;
+    timeline: import("@bridge-ds/core").BuildStatusEvent[];
+    number: number;
+    kind: "issue";
+    component: string;
+    title: string;
+}>;