@bridge-ds/mcp 0.8.4 → 0.9.0

package/dist/figma-fixes.d.ts

@@ -0,0 +1,206 @@
+import { type FigmaFixesFile } from '@bridge-ds/core';
+import type { BridgeContext } from './context.js';
+/** Where `bridge specs --measure` writes, from the repo root. */
+export declare const MEASURED_SPECS_FILE = "measured-specs.json";
+/** The label every figma-fixes.json change carries, next to drafted-by-claude. */
+export declare const FIGMA_FIXES_LABEL = "figma-fixes";
+export interface FixFilesArgs {
+    /** measured-specs.json path in the repo. */
+    measured?: string | undefined;
+    /** The fidelity run: a path in the repo, or the report itself (pasted from the plugin's "Copy the report"). */
+    fidelity?: string | Record<string, unknown> | undefined;
+    /** figma-fixes.json path in the repo. */
+    fixesFile?: string | undefined;
+}
+/** bridge_figma_gaps / `bridge gaps`: the components whose Figma build differs from their story, or cannot be checked. */
+export declare function figmaGapsOp(ctx: BridgeContext, a?: FixFilesArgs): Promise<{
+    measured: string;
+    gaps: import("@bridge-ds/core").FigmaGapRow[];
+    next: string;
+    report: string;
+    checkedAt: string | undefined;
+    referee: string;
+} | {
+    measured: string;
+    gaps: import("@bridge-ds/core").FigmaGapRow[];
+    next: string;
+    note: string;
+    referee: string;
+}>;
+/** bridge_get_gap_case / `bridge fix <component> --case`: one component's gap case and the fix schema. */
+export declare function getGapCaseOp(ctx: BridgeContext, a: FixFilesArgs & {
+    component: string;
+}): Promise<{
+    schema: string;
+    docs: string;
+    rounds: {
+        used: number;
+        max: number;
+    };
+    /** Ids already in figma-fixes.json: a new fix takes another id, or the same id to replace that fix. */
+    fixIds: string[];
+    next: string;
+    report: string;
+    gap: import("@bridge-ds/core").GapCase;
+} | {
+    schema: string;
+    docs: string;
+    rounds: {
+        used: number;
+        max: number;
+    };
+    /** Ids already in figma-fixes.json: a new fix takes another id, or the same id to replace that fix. */
+    fixIds: string[];
+    next: string;
+    note: string;
+    gap: import("@bridge-ds/core").GapCase;
+}>;
+/** bridge_try_figma_fix / `bridge fix <component> --try fixes.json`: the values referee on proposed fixes. */
+export declare function tryFigmaFixOp(ctx: BridgeContext, a: FixFilesArgs & {
+    component: string;
+    fixes: unknown[];
+}): Promise<{
+    next: string;
+    fixesFile?: FigmaFixesFile | undefined;
+    report: string;
+    round: number;
+    roundsLeft: number;
+    pixelCheck: string;
+    status: "invalid" | "checked";
+    component: string;
+    problems: string[];
+    applied: import("@bridge-ds/core").AppliedFix[];
+    verdict: import("@bridge-ds/core").FixVerdict;
+    referee: "values";
+    variants: import("@bridge-ds/core").TriedVariant[];
+    summary: string;
+    detail: string;
+} | {
+    next: string;
+    fixesFile?: FigmaFixesFile | undefined;
+    note: string;
+    round: number;
+    roundsLeft: number;
+    pixelCheck: string;
+    status: "invalid" | "checked";
+    component: string;
+    problems: string[];
+    applied: import("@bridge-ds/core").AppliedFix[];
+    verdict: import("@bridge-ds/core").FixVerdict;
+    referee: "values";
+    variants: import("@bridge-ds/core").TriedVariant[];
+    summary: string;
+    detail: string;
+}>;
+/**
+ * bridge_propose_figma_fixes / `bridge fix <component> --propose fixes.json`: the accepted fixes in figma-fixes.json on
+ * a new branch, opened for review like other Bridge changes (a draft pull request labelled drafted-by-claude and its
+ * tier; locally, a bridge/* branch never pushed). The values referee runs again first: a fix that moves the component
+ * further from the code is refused, and part or story fixes that move nothing are refused (propose a status fix),
+ * unless they size, place or lay out a part: the values referee can't judge layout, Check fidelity decides.
+ */
+export declare function proposeFigmaFixesOp(ctx: BridgeContext, a: FixFilesArgs & {
+    component: string;
+    fixes: unknown[];
+    summary: string;
+    dryRun?: boolean | undefined;
+    source?: 'mcp' | 'cli' | undefined;
+}): Promise<{
+    status: string;
+    verdict: "same" | "worse";
+    why: string;
+    detail: string;
+    hint: string;
+} | {
+    labels: string[];
+    prBody: string;
+    fileContents: {
+        path: string;
+        content: string;
+    }[];
+    component: string;
+    verdict: "closer" | "same";
+    summary: string;
+    variants: import("@bridge-ds/core").TriedVariant[];
+    fixes: string[];
+    tier: import("@bridge-ds/core").RiskTier;
+    prTitle: string;
+    status: string;
+    why?: undefined;
+    detail?: undefined;
+    hint?: undefined;
+} | {
+    prBody: string;
+    fileContents: {
+        path: string;
+        content: string;
+    }[];
+    component: string;
+    verdict: "closer" | "same";
+    summary: string;
+    variants: import("@bridge-ds/core").TriedVariant[];
+    fixes: string[];
+    tier: import("@bridge-ds/core").RiskTier;
+    prTitle: string;
+    status: string;
+    message: string;
+    why?: undefined;
+    detail?: undefined;
+    hint?: undefined;
+} | {
+    branch: string;
+    base: string;
+    commit: string;
+    prBody: string;
+    labels: string[];
+    next: string;
+    component: string;
+    verdict: "closer" | "same";
+    summary: string;
+    variants: import("@bridge-ds/core").TriedVariant[];
+    fixes: string[];
+    tier: import("@bridge-ds/core").RiskTier;
+    prTitle: string;
+    status: string;
+    why?: undefined;
+    detail?: undefined;
+    hint?: undefined;
+} | {
+    prBody: string;
+    labels: string[];
+    fileContents: {
+        path: string;
+        content: string;
+    }[];
+    component: string;
+    verdict: "closer" | "same";
+    summary: string;
+    variants: import("@bridge-ds/core").TriedVariant[];
+    fixes: string[];
+    tier: import("@bridge-ds/core").RiskTier;
+    prTitle: string;
+    status: string;
+    message: string;
+    why?: undefined;
+    detail?: undefined;
+    hint?: undefined;
+} | {
+    branch: string;
+    commit: string;
+    pr: number;
+    url: string;
+    labels: string[];
+    draft: boolean;
+    next: string;
+    component: string;
+    verdict: "closer" | "same";
+    summary: string;
+    variants: import("@bridge-ds/core").TriedVariant[];
+    fixes: string[];
+    tier: import("@bridge-ds/core").RiskTier;
+    prTitle: string;
+    status: string;
+    why?: undefined;
+    detail?: undefined;
+    hint?: undefined;
+}>;

package/dist/figma.d.ts

@@ -45,13 +45,14 @@ export declare function getFigmaChangeOp(ctx: BridgeContext, a: {
     status: string;
     said: string;
 }>;
-/** bridge_mark_figma_change_drafted / `bridge figma drafted <n>`: the code is on the branch, labelled drafted by Claude AI. */
+/** bridge_mark_figma_change_drafted / `bridge figma drafted <n>`: the code is on the branch, ready for review and labelled drafted by Claude AI. */
 export declare function markFigmaDraftedOp(ctx: BridgeContext, a: {
     pr: number | string;
 }): Promise<{
     pr: number;
     status: string;
     said: string;
+    readyForReview: boolean;
     files: string[];
     next: string;
 }>;

package/dist/history.d.ts

@@ -115,7 +115,9 @@ export declare function getTokenHistory(ctx: BridgeContext, a: {
     }[];
 }>;
 /** Finds an entry by id ("pr-12"), PR number ("#12", "12"), or sha (7 characters or more). */
-export declare function findEntry(entries: HistoryEntry[], target: string): HistoryEntry;
+export declare function findEntry(entries: HistoryEntry[], target: string, ctx?: {
+    surface: 'mcp' | 'cli';
+}): HistoryEntry;
 export interface RestoreArg {
     path: string;
     /** History entry whose value to restore (its value AFTER that change), or use `value`. */
@@ -134,16 +136,44 @@ export interface PlanArgs {
     /** Shortcut: every conflict uses the value from before the change. */
     restoreConflicts?: boolean;
 }
+/** Items per list in a bridge_plan_revert answer, and the longest PR body it returns, so a bulk revert stays readable. */
+export declare const PLAN_PAGE = 50;
+export declare const PLAN_BODY_MAX = 20000;
+/**
+ * One page of each list of a plan report (edits, conflicts, skipped, changes), with the totals and how to read the
+ * rest. The whole plan is still what bridge_propose_revert opens.
+ */
+export declare function pagePlanReport<R extends {
+    edits: unknown[];
+    conflicts: unknown[];
+    skipped: unknown[];
+    changes: unknown[];
+}>(report: R, limit?: number, offset?: number): R & {
+    truncated?: string | undefined;
+    edits: unknown[];
+    conflicts: unknown[];
+    skipped: unknown[];
+    changes: unknown[];
+    counts: {
+        edits: number;
+        conflicts: number;
+        skipped: number;
+        changes: number;
+    };
+};
 /** Dry run: what undoing a change (or restoring a token) takes, conflicts included. Writes nothing. */
 export declare function planRevertOp(ctx: BridgeContext, a: PlanArgs & {
     includeBody?: boolean;
+    limit?: number;
+    offset?: number;
 }): Promise<{
     next: string;
-    prBody?: string | undefined;
+    prBody: string;
+    prBodyNote: string;
     tier: 1 | 2 | 3;
     bump: import("@bridge-ds/core").SemverBump;
     reasons: string[];
-    edits: string[];
+    edits: string[] & unknown[];
     conflicts: {
         before?: string | undefined;
         now?: unknown;
@@ -154,15 +184,15 @@ export declare function planRevertOp(ctx: BridgeContext, a: PlanArgs & {
         message: string;
         later: string[];
         resolution: RevertResolution;
-    }[];
-    skipped: string[];
+    }[] & unknown[];
+    skipped: string[] & unknown[];
     changes: {
         kind: "added" | "changed" | "renamed" | "removed";
         path: string;
         file: string;
         before: string | undefined;
         after: string | undefined;
-    }[];
+    }[] & unknown[];
     contrast: {
         moved: number;
         newFailures: import("@bridge-ds/core").ContrastDelta[];
@@ -183,6 +213,119 @@ export declare function planRevertOp(ctx: BridgeContext, a: PlanArgs & {
     title: string;
     why?: string | undefined;
     status: "ready" | "blocked" | "nothing-to-do";
+    truncated?: string | undefined;
+    counts: {
+        edits: number;
+        conflicts: number;
+        skipped: number;
+        changes: number;
+    };
+} | {
+    next: string;
+    prBody: string;
+    prBodyNote?: undefined;
+    tier: 1 | 2 | 3;
+    bump: import("@bridge-ds/core").SemverBump;
+    reasons: string[];
+    edits: string[] & unknown[];
+    conflicts: {
+        before?: string | undefined;
+        now?: unknown;
+        key: string;
+        path: string;
+        file: string;
+        reason: import("@bridge-ds/core").ConflictReason;
+        message: string;
+        later: string[];
+        resolution: RevertResolution;
+    }[] & unknown[];
+    skipped: string[] & unknown[];
+    changes: {
+        kind: "added" | "changed" | "renamed" | "removed";
+        path: string;
+        file: string;
+        before: string | undefined;
+        after: string | undefined;
+    }[] & unknown[];
+    contrast: {
+        moved: number;
+        newFailures: import("@bridge-ds/core").ContrastDelta[];
+        sample: import("@bridge-ds/core").ContrastDelta[];
+    };
+    newErrors: import("@bridge-ds/core").LayerIssue[];
+    branch: string;
+    files: string[];
+    notes: string[];
+    reverts?: {
+        pr?: number | undefined;
+        id: string;
+        title: string;
+        date: string;
+        author: string;
+    } | undefined;
+    kind: "revert" | "restore";
+    title: string;
+    why?: string | undefined;
+    status: "ready" | "blocked" | "nothing-to-do";
+    truncated?: string | undefined;
+    counts: {
+        edits: number;
+        conflicts: number;
+        skipped: number;
+        changes: number;
+    };
+} | {
+    next: string;
+    tier: 1 | 2 | 3;
+    bump: import("@bridge-ds/core").SemverBump;
+    reasons: string[];
+    edits: string[] & unknown[];
+    conflicts: {
+        before?: string | undefined;
+        now?: unknown;
+        key: string;
+        path: string;
+        file: string;
+        reason: import("@bridge-ds/core").ConflictReason;
+        message: string;
+        later: string[];
+        resolution: RevertResolution;
+    }[] & unknown[];
+    skipped: string[] & unknown[];
+    changes: {
+        kind: "added" | "changed" | "renamed" | "removed";
+        path: string;
+        file: string;
+        before: string | undefined;
+        after: string | undefined;
+    }[] & unknown[];
+    contrast: {
+        moved: number;
+        newFailures: import("@bridge-ds/core").ContrastDelta[];
+        sample: import("@bridge-ds/core").ContrastDelta[];
+    };
+    newErrors: import("@bridge-ds/core").LayerIssue[];
+    branch: string;
+    files: string[];
+    notes: string[];
+    reverts?: {
+        pr?: number | undefined;
+        id: string;
+        title: string;
+        date: string;
+        author: string;
+    } | undefined;
+    kind: "revert" | "restore";
+    title: string;
+    why?: string | undefined;
+    status: "ready" | "blocked" | "nothing-to-do";
+    truncated?: string | undefined;
+    counts: {
+        edits: number;
+        conflicts: number;
+        skipped: number;
+        changes: number;
+    };
 }>;
 /** Plans, then commits to a new local bridge/* branch or opens a PR on a new bridge/* branch. Never main. */
 export declare function proposeRevert(ctx: BridgeContext, a: PlanArgs & {

package/dist/index.js

@@ -3,8 +3,8 @@ import {
   VERSION,
   optionsFromArgv,
   serveStdio
-} from "./chunk-HZWFI7A2.js";
-import "./chunk-PMZGEZGX.js";
+} from "./chunk-TP33MW7E.js";
+import "./chunk-ZVORAO5H.js";
 
 // src/index.ts
 var argv = process.argv.slice(2);
@@ -16,8 +16,12 @@ Usage:
   bridge-mcp --repo <owner/name> [--ref r]  GitHub repo over the API
 
 Env:
-  GITHUB_TOKEN   optional. Without it Bridge is read-only. With it Bridge can open PRs on new
-                 bridge/* branches (never main). Use a fine-grained token scoped to one repo.
+  GITHUB_TOKEN   optional (or BRIDGE_GITHUB_TOKEN). When neither is set, Bridge uses your gh sign-in
+                 (gh auth token) and says so once at start. Without any token Bridge is read-only on GitHub
+                 (60 requests an hour) and says that at start too; a local git repo still gets local bridge/*
+                 branches, never pushed. With one Bridge files suggestions and requests (issues), reviews,
+                 comments, branches and pull requests, never the default branch. Use a fine-grained token
+                 scoped to one repo. bridge_get_config says what this server may write. The token is never logged.
 `);
   process.exit(0);
 }

package/dist/lib.d.ts

@@ -1,5 +1,6 @@
 import { type ContextOptions } from './context.js';
 export { BridgeContext, type ContextOptions } from './context.js';
+export { BlockedError, isBlocked, say } from './say.js';
 export { createServer, VERSION } from './server.js';
 export { CONFIG_FILE, detectConfig, parseConfig, toConfigJson, type BridgeConfig } from './config.js';
 export { core } from './core-adapter.js';
@@ -9,17 +10,29 @@ export * as ops from './ops.js';
 export * as history from './history.js';
 export * as brand from './brand.js';
 export * as requests from './requests.js';
+export * as buildRequests from './build-requests.js';
 export * as explorations from './explorations.js';
 export * as drafts from './drafts.js';
 export * as branches from './branches.js';
 export * as studio from './studio.js';
 export * as pieces from './pieces.js';
 export * as figma from './figma.js';
+export * as figmaFixes from './figma-fixes.js';
 export * as suggestions from './suggestions.js';
 export { DOCS_DRAFT_MODEL, anthropicReplyText, anthropicRequest, formatDocsJson, mergeDocsDraft, missingProse, parseDocsReply } from '@bridge-ds/core';
+/** Where the server's GitHub token came from: the environment, the gh sign-in, or nowhere. Never the token itself. */
+export type TokenSource = 'env' | 'gh' | 'none';
 export interface ServeOptions extends ContextOptions {
+    tokenSource?: TokenSource;
 }
+/** The gh sign-in (`gh auth token`), or undefined when gh is missing or signed out. Never logged. */
+export declare function ghAuthToken(): string | undefined;
+/** Said once at start, on stderr: where the token came from, or what the server does without one. Never the token. */
+export declare function tokenNote(source: TokenSource | undefined): string | undefined;
 /** Starts the stdio MCP server. Logs go to stderr: stdout belongs to the protocol. */
 export declare function serveStdio(opts?: ServeOptions): Promise<void>;
-/** Parses `--root <dir> --repo <owner/name> --ref <ref>`; token from GITHUB_TOKEN or BRIDGE_GITHUB_TOKEN. */
-export declare function optionsFromArgv(argv: string[], env?: NodeJS.ProcessEnv): ServeOptions;
+/**
+ * Parses `--root <dir> --repo <owner/name> --ref <ref>`. Token: BRIDGE_GITHUB_TOKEN or GITHUB_TOKEN, else the gh
+ * sign-in (`gh auth token`), in the same order as the bridge CLI. `tokenSource` says which, for the start line.
+ */
+export declare function optionsFromArgv(argv: string[], env?: NodeJS.ProcessEnv, gh?: () => string | undefined): ServeOptions;

package/dist/lib.js

@@ -1,4 +1,5 @@
 import {
+  BlockedError,
   BridgeContext,
   DOCS_DRAFT_MODEL,
   GitHubSource,
@@ -10,14 +11,18 @@ import {
   auditSnippet,
   branches_exports,
   brand_exports,
+  build_requests_exports,
   core,
   createServer,
   detectConfig,
   drafts_exports,
   explorations_exports,
   figma_exports,
+  figma_fixes_exports,
   formatDocsJson,
+  ghAuthToken,
   history_exports,
+  isBlocked,
   mergeDocsDraft,
   missingProse,
   ops_exports,
@@ -25,16 +30,19 @@ import {
   parseDocsReply,
   pieces_exports,
   requests_exports,
+  say,
   serveStdio,
   studio_exports,
-  suggestions_exports
-} from "./chunk-HZWFI7A2.js";
+  suggestions_exports,
+  tokenNote
+} from "./chunk-TP33MW7E.js";
 import {
   CONFIG_FILE,
   loadConfig,
   toConfigJson
-} from "./chunk-PMZGEZGX.js";
+} from "./chunk-ZVORAO5H.js";
 export {
+  BlockedError,
   BridgeContext,
   CONFIG_FILE,
   DOCS_DRAFT_MODEL,
@@ -47,14 +55,18 @@ export {
   auditSnippet,
   branches_exports as branches,
   brand_exports as brand,
+  build_requests_exports as buildRequests,
   core,
   createServer,
   detectConfig,
   drafts_exports as drafts,
   explorations_exports as explorations,
   figma_exports as figma,
+  figma_fixes_exports as figmaFixes,
   formatDocsJson,
+  ghAuthToken,
   history_exports as history,
+  isBlocked,
   mergeDocsDraft,
   missingProse,
   ops_exports as ops,
@@ -63,8 +75,10 @@ export {
   parseDocsReply,
   pieces_exports as pieces,
   requests_exports as requests,
+  say,
   serveStdio,
   studio_exports as studio,
   suggestions_exports as suggestions,
-  toConfigJson
+  toConfigJson,
+  tokenNote
 };

package/dist/ops.d.ts

@@ -71,6 +71,7 @@ export declare function searchTokens(ctx: BridgeContext, a: {
     type?: string;
     limit?: number;
 }): Promise<{
+    truncated?: string | undefined;
     query: string;
     mode: Combo;
     total: number;
@@ -197,6 +198,46 @@ export declare function getComponentOp(ctx: BridgeContext, a: {
  * CSS module classes, contrast notes, changelog line, existing prose kept) and a prompt for the user's own Claude
  * to write the prose that code cannot tell. Nothing is written.
  */
+/**
+ * The tokens a component reaches: the ones its stylesheets read plus every token they alias, in any mode
+ * (card.bg -> color.surface.raised), so a contrast pair written on semantic tokens matches a component token.
+ */
+export declare function reachedTokens(set: TokenSet, paths: Iterable<string>): Set<string>;
+/**
+ * Contrast pairs that concern a component: both sides among the tokens it reaches (its text on its own surface).
+ * A component that sets no surface of its own (text on whatever it sits on) gets the pairs of the foregrounds it
+ * uses instead. Never a pair that only shares a background with it.
+ */
+export declare function relevantPairs<P extends {
+    foreground: string;
+    background: string;
+}>(pairs: P[], reached: Set<string>): P[];
+/** Characters of the docs prompt per page of bridge_draft_docs: a whole prompt can pass 25,000 characters. */
+export declare const DOCS_PROMPT_PAGE = 12000;
+/** Splits text into pages of at most `size` characters, on line breaks when it can. */
+export declare function textPages(text: string, size: number): string[];
+/**
+ * bridge_draft_docs result for a tool call: the prompt one page at a time (page 1 by default), with a summary of
+ * what the draft holds and how to read the next page. The CLI prints the whole draft and does not page.
+ */
+export declare function pagedDraftDocs<D extends {
+    component: string;
+    prompt: string;
+    prefill: {
+        tokens: string[];
+        contrastNotes: string[];
+        missing: string[];
+    };
+}>(d: D, page?: number, size?: number): {
+    summary: string;
+} & D & {
+    prompt: string;
+    promptPage: {
+        next?: string | undefined;
+        page: number;
+        pages: number;
+    };
+};
 export declare function draftDocsOp(ctx: BridgeContext, a: {
     name: string;
     branch?: string | undefined;

package/dist/say.d.ts

@@ -0,0 +1,22 @@
+type Surface = {
+    surface: 'mcp' | 'cli';
+};
+/** The MCP wording or the CLI wording, for this context's reader. */
+export declare function say(ctx: Surface, mcp: string, cli: string): string;
+/** Where a change comes from, as the labels say ("source: cli"): what the caller passed, else this context's reader. */
+export declare const sourceOf: (ctx: Surface, source?: "mcp" | "cli" | undefined) => "mcp" | "cli";
+/** The tool in pull request bodies and commit messages: "Bridge MCP" or "the bridge CLI". */
+export declare const toolName: (source: "mcp" | "cli") => "Bridge MCP" | "the bridge CLI";
+/** The same with its source label: "Bridge MCP (source: mcp)". */
+export declare const toolTag: (source: "mcp" | "cli") => string;
+/** How to give Bridge a token where it runs. */
+export declare function addToken(ctx: Surface): string;
+/** "Read-only: ... to open this as a pull request." for previews without a token. */
+export declare function readOnlyPreview(ctx: Surface, what?: string): string;
+/** Thrown when a rule blocks the action (the merge gate, the owner override): not a usage error. */
+export declare class BlockedError extends Error {
+    readonly blocked = true;
+    constructor(message: string);
+}
+export declare const isBlocked: (e: unknown) => e is BlockedError;
+export {};