@bridge-ds/mcp 0.3.3 → 0.4.0

package/README.md

@@ -62,7 +62,7 @@ Working on the server itself: `npm run mcp:build` in a clone of this repo builds
 | `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_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 |
@@ -75,6 +75,22 @@ Working on the server itself: `npm run mcp:build` in a clone of this repo builds
 | `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 |
 
 Resources: `bridge://tokens/resolved`, `bridge://design-language`, `bridge://guidelines`,
 `bridge://components/{name}`. Prompts: `review-token-pr`, `add-component`, `audit-ui-for-tokens`,

package/dist/branches.d.ts

@@ -0,0 +1,443 @@
+import { 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: {
+    readonly review: "Pull requests: read and write";
+    readonly comment: "Pull requests (or Issues): read and write";
+    readonly merge: "Contents and Pull requests: read and write, and the right to ship in bridge.config.json (governance.rights)";
+    readonly update: "Contents and Pull requests: read and write";
+    readonly draft: "Pull requests: read and write (you must be the author, as in Studio)";
+    readonly docs: "Contents and Pull requests: read and write";
+};
+/** 12, "#12" or a pull request link: the branch number. Throws how to fix it otherwise. */
+export declare function branchNumber(input: number | string): number;
+/** 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;
+    pr: import("@bridge-ds/core").PullRequest & import("@bridge-ds/core").PullRequestSummary & {
+        body: string;
+        mergeable: boolean | null;
+        requestedReviewers: string[];
+    };
+    files: import("@bridge-ds/core").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;
+    fresh: import("@bridge-ds/core").Freshness;
+    compare: {
+        behindBy: number;
+        aheadBy: number;
+        mergeBase: string | null;
+        baseSha: string | null;
+        baseTree: string | null;
+        files: {
+            filename: string;
+            status: string;
+            previous_filename?: string | undefined;
+        }[];
+    } | null;
+    exploration: boolean;
+    product: ProductConfig;
+    lifecycle: import("@bridge-ds/core").PullState;
+    write: boolean | null;
+    repo: {
+        allow_squash_merge?: boolean;
+        allow_merge_commit?: boolean;
+        allow_rebase_merge?: boolean;
+        permissions?: {
+            admin?: boolean;
+            maintain?: boolean;
+            push?: boolean;
+        };
+    } | null;
+}>;
+/** 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<{
+    pr: number;
+    title: string;
+    url: string;
+    author: string;
+    product: {
+        key: string;
+        name: string;
+    };
+    lifecycle: import("@bridge-ds/core").PullState;
+    status: {
+        kind: ReviewStatusKind;
+        label: string;
+    };
+    approvalNeeded: string;
+    approvals: {
+        approvedBy: string[];
+        changesRequestedBy: string[];
+        design: boolean;
+        tech: boolean;
+    };
+    tests: {
+        state: import("@bridge-ds/core").CiState;
+        failing: string[];
+        running: string[];
+    };
+    main: {
+        state: import("@bridge-ds/core").LibraryState;
+        behindBy: number | null;
+    };
+    merge: {
+        you: string;
+        youCanShip: boolean;
+        ownerOverride: boolean;
+        allowed: boolean;
+        blockedBy: string[];
+    } | {
+        you: null;
+        note: string;
+        allowed: boolean;
+        blockedBy: string[];
+    };
+    next: string;
+}>;
+/**
+ * What needs me: the review queue (open branches minus running explorations and release automation), each with its
+ * status, and the ones where the viewer acts now first: approvals they can give, their own branches blocked or ready.
+ */
+export declare function whatNeedsMe(ctx: BridgeContext, a?: {
+    limit?: number | undefined;
+}): Promise<{
+    viewer: string | null;
+    summary: string;
+    branches: ({
+        pr: number;
+        title: string;
+        url: string;
+        author: string;
+        status: ReviewStatusKind;
+        statusLabel: string;
+        yours: boolean;
+        needsYou: string | null;
+        product?: undefined;
+    } | {
+        pr: number;
+        title: string;
+        url: string;
+        author: string;
+        product: string;
+        status: ReviewStatusKind;
+        statusLabel: string;
+        yours: boolean;
+        needsYou: string | 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<{
+    products: {
+        default: boolean;
+        framework?: string | undefined;
+        preview?: string | undefined;
+        path?: string | undefined;
+        repo?: string | undefined;
+        key: string;
+        name: string;
+    }[];
+    current: {
+        key: string;
+        name: string;
+        how: "path" | "default" | "repo";
+    };
+    howToPick: string;
+}>;
+/**
+ * The product new work belongs to: the one named (key or name), else the product of the current folder or repo.
+ * Throws with the list when the name is unknown.
+ */
+export declare function resolveProduct(ctx: BridgeContext, name?: string | undefined): Promise<ProductConfig>;
+/** Labels and a body line for a branch that starts work for a product (the default product adds nothing). */
+export declare function productMarks(products: ProductConfig[], p: ProductConfig): {
+    labels: string[];
+    line: string;
+};
+/**
+ * Try it in a product and share it with a product team: the preview of each product Vercel reported for this branch
+ * (opened with the Bridge toolbar on it), and the install command product teams use in a staging branch, with a
+ * ready-to-paste message. Nothing is written.
+ */
+export declare function tryBranch(ctx: BridgeContext, a: {
+    pr: number | string;
+}): Promise<{
+    pr: number;
+    title: string;
+    tryInProduct: {
+        key: string;
+        name: string;
+        url: string | null;
+        how: string;
+    }[];
+    previews: {
+        app: keyof import("@bridge-ds/core").PreviewApps;
+        label: string;
+        url: string | null;
+        state: import("@bridge-ds/core").PreviewState;
+    }[];
+    share: {
+        message?: import("@bridge-ds/core").ShareMessage | undefined;
+        state: "ready" | "building" | "failed" | "closed" | "no-packages" | "shipped";
+        install: string | null;
+        sentence: string;
+    };
+}>;
+/**
+ * Combined preview of 2 to 4 token branches: the conflicts to pick ("use #118's"), how many tokens change, and the
+ * links that open the combination (the product with the Bridge toolbar, the library views). Nothing is written.
+ */
+export declare function combineBranches(ctx: BridgeContext, a: {
+    prs: (number | string)[];
+    picks?: Record<string, number> | undefined;
+}): Promise<{
+    branches: {
+        pr: number;
+        title: string;
+    }[];
+    tokens: number;
+    conflicts: {
+        key: string;
+        token: string;
+        file: string;
+        options: {
+            use: number | undefined;
+            titles: string[];
+        }[];
+        picked: number | null;
+    }[];
+    missingPicks: number;
+    problems: string[];
+    open: {
+        library?: string | undefined;
+        product?: string | undefined;
+    };
+    next: string;
+}>;
+/** Ask for review: a draft branch becomes ready for review (Studio "Mark as ready"). Its author only, as in Studio. */
+export declare function sendForReview(ctx: BridgeContext, a: {
+    pr: number | string;
+}): Promise<{
+    pr: number;
+    status: "already-in-review";
+    said: string;
+    url?: undefined;
+} | {
+    pr: number;
+    status: "in-review";
+    said: string;
+    url: string;
+}>;
+/** Back to draft: the author takes a branch out of review (Studio More menu). */
+export declare function backToDraft(ctx: BridgeContext, a: {
+    pr: number | string;
+}): Promise<{
+    pr: number;
+    status: "draft";
+    said: string;
+}>;
+/** Approve, request changes or comment as a review, on the head the reviewer saw (Studio review box). */
+export declare function reviewBranch(ctx: BridgeContext, a: {
+    pr: number | string;
+    decision: 'approve' | 'request_changes' | 'comment';
+    body?: string | undefined;
+}): Promise<{
+    pr: number;
+    decision: "comment" | "approve" | "request_changes";
+    id: number;
+    said: string;
+    note: string | undefined;
+}>;
+/**
+ * "Ask someone else to review" (the review queue): asks the other people who can give the missing approvals, and
+ * takes the viewer off the requested reviewers. Studio's rule (core reviewersToAsk): never the viewer or the author.
+ */
+export declare function askSomeoneElse(ctx: BridgeContext, a: {
+    pr: number | string;
+    dryRun?: boolean | undefined;
+}): Promise<{
+    pr: number;
+    status: "would-ask";
+    asks: string[];
+    said: string;
+    asked?: undefined;
+} | {
+    pr: number;
+    status: "asked";
+    asked: string[];
+    said: string;
+    asks?: undefined;
+}>;
+/** A comment on the branch, or a reply in the thread of a line comment. */
+export declare function commentOnBranch(ctx: BridgeContext, a: {
+    pr: number | string;
+    body: string;
+    replyTo?: number | undefined;
+}): Promise<{
+    pr: number;
+    replied: number;
+    url: string;
+    said: string;
+} | {
+    pr: number;
+    url: string;
+    said: string;
+    replied?: undefined;
+}>;
+/** The comments of a branch: the conversation and the line threads (ids to reply to). */
+export declare function listComments(ctx: BridgeContext, a: {
+    pr: number | string;
+}): Promise<{
+    pr: number;
+    conversation: {
+        id: number;
+        author: string;
+        body: string;
+        at: string;
+    }[];
+    threads: {
+        id: number;
+        author: string;
+        file: string;
+        line: number | null;
+        body: string;
+        url: string;
+        replies: {
+            id: number;
+            author: string;
+            body: string;
+        }[];
+    }[];
+    howToReply: string;
+}>;
+/**
+ * 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.
+ */
+export declare function mergeBranch(ctx: BridgeContext, a: {
+    pr: number | string;
+    overrideReason?: string | undefined;
+    dryRun?: boolean | undefined;
+}): Promise<{
+    pr: number;
+    status: "would-merge";
+    said: string;
+    sha?: undefined;
+    skips?: undefined;
+    override?: undefined;
+    reasonUrl?: undefined;
+} | {
+    pr: number;
+    status: "merged";
+    sha: string;
+    said: string;
+    skips?: undefined;
+    override?: undefined;
+    reasonUrl?: undefined;
+} | {
+    pr: number;
+    status: "would-override";
+    skips: import("@bridge-ds/core").MissingApproval[];
+    said: string;
+    sha?: undefined;
+    override?: undefined;
+    reasonUrl?: undefined;
+} | {
+    pr: number;
+    status: "merged";
+    override: boolean;
+    sha: string;
+    reasonUrl: string;
+    said: string;
+    skips?: undefined;
+}>;
+/** Close without merging (Studio More menu). The work stays on GitHub and the branch can be reopened. */
+export declare function closeBranch(ctx: BridgeContext, a: {
+    pr: number | string;
+}): Promise<{
+    pr: number;
+    status: string;
+    said: string;
+}>;
+/** Reopen a closed branch: its author or an owner, with write access, while its work is still there (Studio rule). */
+export declare function reopenBranch(ctx: BridgeContext, a: {
+    pr: number | string;
+}): Promise<{
+    pr: number;
+    status: "open";
+    said: string;
+}>;
+/**
+ * Update from main: when nothing conflicts, GitHub's update-branch. When only token files conflict, the conflicts to
+ * pick ("mine": keep the branch's value, "theirs": use main's) and, once every one is picked, a merge commit with those
+ * choices. Code conflicts stay with a developer on GitHub, as in Studio.
+ */
+export declare function updateFromMain(ctx: BridgeContext, a: {
+    pr: number | string;
+    choices?: MergeChoices | undefined;
+    dryRun?: boolean | undefined;
+}): Promise<{
+    pr: number;
+    status: "up-to-date";
+    said: string;
+    behindBy?: undefined;
+    conflicts?: undefined;
+    missing?: undefined;
+    commit?: undefined;
+} | {
+    pr: number;
+    status: "would-update";
+    behindBy: number | null;
+    said: string;
+    conflicts?: undefined;
+    missing?: undefined;
+    commit?: undefined;
+} | {
+    pr: number;
+    status: "updated";
+    said: string;
+    behindBy?: undefined;
+    conflicts?: undefined;
+    missing?: undefined;
+    commit?: undefined;
+} | {
+    pr: number;
+    status: "token-conflicts";
+    conflicts: {
+        key: string;
+        token: string;
+        file: string;
+        mine: import("@bridge-ds/core").FlatToken | null;
+        theirs: import("@bridge-ds/core").FlatToken | null;
+        default: import("@bridge-ds/core").MergeSide | null;
+    }[];
+    missing: string[];
+    said: string;
+    behindBy?: undefined;
+    commit?: undefined;
+} | {
+    pr: number;
+    status: "resolved";
+    commit: string;
+    said: string;
+    behindBy?: undefined;
+    conflicts?: undefined;
+    missing?: undefined;
+}>;
+/** Who may add edits to a branch, and its head, for bridge_propose_token_change with `pr` (Studio "Edit tokens in this branch"). */
+export declare function addableBranch(ctx: BridgeContext, n: number): Promise<{
+    gh: GitHubClient;
+    pr: import("@bridge-ds/core").PullRequest & import("@bridge-ds/core").PullRequestSummary & {
+        body: string;
+        mergeable: boolean | null;
+        requestedReviewers: string[];
+    };
+    viewer: string;
+    comment: (paths: string[]) => string;
+}>;