@bridge-ds/mcp 0.6.0 → 0.7.1

package/dist/suggestions.d.ts

@@ -0,0 +1,397 @@
+import { type ApprovalRole, type BridgeConfig, type ChangesMode, type GitHubClient, type RequestSource, type SuggestionGovernance, type SuggestionKind, type SuggestionPayloadV1, type SuggestionStatus, type SuggestionWorkspace } from '@bridge-ds/core';
+import { type LocalApplyMode } from '@bridge-ds/core/node';
+import type { BridgeContext } from './context.js';
+/** Rights a suggestion needs: an issue, never code. */
+export declare const SUGGEST_RIGHTS = "Issues: read and write (Contents: read is enough)";
+/**
+ * How a write reaches the code for this call: the explicit choice (a tool's `changes`, the CLI's --suggest or
+ * --direct), else `changes` in bridge.config.json, else "suggest".
+ */
+export declare function changesFor(ctx: BridgeContext, explicit?: ChangesMode | undefined): Promise<ChangesMode>;
+/** What to do next once a suggestion is filed. The wording matches the issue's "How to apply". */
+export declare const appliedNext: (n: number) => string;
+/** Why nothing was filed: no GitHub repo, or no token that can write issues. */
+export declare function noSuggestionAccess(ctx: BridgeContext, gh: GitHubClient | null): string;
+/**
+ * The commit a suggestion is planned on: the local HEAD when the server reads a checkout (that is what the plan read),
+ * else the head of the ref the server reads on GitHub.
+ */
+export declare function suggestionBase(ctx: BridgeContext, gh: GitHubClient, config: BridgeConfig): Promise<{
+    ref: string;
+    sha: string;
+}>;
+/**
+ * The payload of a whole-file change (brand, revert, config): each file with the git blob sha it has where the plan
+ * read it (null: new) and its new content (null: deleted).
+ */
+export declare function filesSuggestionPayload(ctx: BridgeContext, input: {
+    kind: Extract<SuggestionKind, 'brand' | 'revert' | 'config'>;
+    title: string;
+    summary: string;
+    files: {
+        path: string;
+        content: string | null;
+    }[];
+    tier: SuggestionPayloadV1['tier'];
+    base: {
+        ref: string;
+        sha: string;
+    };
+    source: RequestSource;
+    suggestedBy?: string | null | undefined;
+    checks?: Partial<SuggestionPayloadV1['checks']> | undefined;
+}): Promise<SuggestionPayloadV1>;
+/**
+ * Files a planned whole-file change as a suggestion (bridge_propose_brand, bridge_propose_revert in suggest mode).
+ * The caller already checked the plan is not blocked.
+ */
+export declare function fileSuggestion(ctx: BridgeContext, build: (base: {
+    ref: string;
+    sha: string;
+}, suggestedBy: string | null) => Promise<SuggestionPayloadV1>, opts?: {
+    labels?: string[] | undefined;
+    details?: string | undefined;
+    dryRun?: boolean | undefined;
+}): Promise<{
+    status: 'dry-run';
+    suggestion: {
+        title: string;
+        labels: string[];
+        body: string;
+        parts: number;
+    };
+} | {
+    status: 'preview';
+    message: string;
+} | {
+    status: 'suggested';
+    number: number;
+    url: string;
+    sha: string;
+    labels: string[];
+    warnings: string[];
+    next: string;
+}>;
+/** 42, "#42" or an issue link: the suggestion number. Throws how to fix it otherwise. */
+export declare function suggestionNumber(input: number | string): number;
+/**
+ * The owners who approve suggestions, from bridge.config.json on the default branch (never from the payload, never
+ * from a branch someone could edit), with GitHub team members read when owners name teams.
+ */
+export declare function suggestionGovernance(ctx: BridgeContext, gh: GitHubClient): Promise<{
+    config: BridgeConfig;
+    gov: SuggestionGovernance;
+}>;
+export type SuggestionStatusFilter = SuggestionStatus | 'all';
+/** bridge_list_suggestions / `bridge suggestions list`. */
+export declare function listSuggestionsOp(ctx: BridgeContext, a?: {
+    status?: SuggestionStatusFilter | undefined;
+    state?: 'open' | 'closed' | 'all' | undefined;
+    kind?: SuggestionKind | undefined;
+    limit?: number | undefined;
+}): Promise<{
+    repo: string;
+    label: string;
+    state: "closed" | "open" | "all";
+    status: SuggestionStatusFilter;
+    total: number;
+    suggestions: {
+        number: number;
+        title: string;
+        kind: SuggestionKind | null;
+        tier: 1 | 2 | 3 | null;
+        status: SuggestionStatus;
+        said: string;
+        author: string;
+        url: string;
+        linkedPrs: {
+            number: number;
+            url: string;
+            state: "open" | "closed";
+            merged: boolean;
+        }[];
+    }[];
+    next: string;
+}>;
+/** bridge_get_suggestion / `bridge suggestions show <n>`: one suggestion, with its approvals on the current version. */
+export declare function getSuggestionOp(ctx: BridgeContext, a: {
+    number: number | string;
+}): Promise<{
+    problem: string;
+    next: string;
+    number: number;
+    url: string;
+    title: string;
+    state: "closed" | "open";
+    status: SuggestionStatus;
+    said: string;
+    author: string;
+    labels: string[];
+    linkedPrs: {
+        number: number;
+        url: string;
+        state: "open" | "closed";
+        merged: boolean;
+    }[];
+} | {
+    next: string;
+    brief?: string | undefined;
+    approvals: {
+        notCounted?: string[] | undefined;
+        staleReviews?: string[] | undefined;
+        approvedBy: string[];
+        missing: string[];
+        changesRequestedBy: string[];
+    };
+    applied: import("@bridge-ds/core").SuggestionAppliedRecord[];
+    previews?: {
+        label: string;
+        url: string;
+    }[] | undefined;
+    links?: {
+        neededBy?: import("@bridge-ds/core").NeededBy | undefined;
+        figma?: {
+            fileKey?: string | undefined;
+            nodeId?: string | undefined;
+            url?: string | undefined;
+            nodes?: import("@bridge-ds/core").SuggestionFigmaNode[] | undefined;
+        } | undefined;
+        exploration?: string | undefined;
+        supersedes?: number | undefined;
+    } | undefined;
+    change: {
+        files?: {
+            path: string;
+            change: string;
+        }[] | undefined;
+        componentSpec?: {
+            component: string;
+            specPath: string;
+        } | undefined;
+        docs?: {
+            component: string;
+            path: string;
+        }[] | undefined;
+        tokens?: import("@bridge-ds/core").TokenEdit[] | {
+            file: string;
+            before: unknown;
+            after: unknown;
+            from?: string | undefined;
+            kind: "added" | "changed" | "renamed" | "removed";
+            path: string;
+        }[] | undefined;
+    };
+    checks: {
+        newErrors: number;
+        contrast: import("@bridge-ds/core").SuggestionContrastCheck[];
+        blocked: string | null;
+        impact: number;
+    };
+    edited?: string | undefined;
+    createdAt: string;
+    base: {
+        ref: string;
+        sha: string;
+    };
+    tier: 1 | 2 | 3;
+    bump: "patch" | "minor" | "major";
+    version: string;
+    payloadSha: string;
+    suggestedBy?: string | undefined;
+    kind: SuggestionKind;
+    summary: string;
+    source: RequestSource;
+    number: number;
+    url: string;
+    title: string;
+    state: "closed" | "open";
+    status: SuggestionStatus;
+    said: string;
+    author: string;
+    labels: string[];
+    linkedPrs: {
+        number: number;
+        url: string;
+        state: "open" | "closed";
+        merged: boolean;
+    }[];
+}>;
+export type SuggestionReviewEventArg = 'approve' | 'request-changes' | 'comment' | 'decline';
+/**
+ * bridge_review_suggestion / `bridge review <n>`: approve, request changes, comment on or decline a suggestion, as the
+ * token's user. Approvals count only from the owners in bridge.config.json and only on the version reviewed
+ * (`payloadSha`, the version bridge_get_suggestion showed): a newer version is never approved by mistake.
+ */
+export declare function reviewSuggestionOp(ctx: BridgeContext, a: {
+    number: number | string;
+    event: SuggestionReviewEventArg;
+    message?: string | undefined;
+    role?: ApprovalRole | undefined;
+    payloadSha?: string | undefined;
+}): Promise<{
+    next: string;
+    warnings?: string[] | undefined;
+    number: number;
+    status: SuggestionStatus;
+    said: string;
+} | {
+    next: string;
+    warnings?: string[] | undefined;
+    number: number;
+    event: "comment" | "approve" | "request-changes";
+    counts: boolean;
+    version: string;
+    status: SuggestionStatus;
+    said: string;
+    comment: string;
+}>;
+/** The planner's workspace over the GitHub API at a ref (remote mode: nothing is written, the files come back). */
+export declare function githubWorkspace(gh: GitHubClient, ref: string): SuggestionWorkspace;
+export type ApplyModeArg = 'dry-run' | LocalApplyMode;
+/**
+ * bridge_apply_suggestion / `bridge apply <n>`: plans the suggestion on today's code and hands it over.
+ *   - local checkout: "branch" (default, one commit on a new local branch, working tree untouched, nothing pushed),
+ *     "write" (into the working tree), "patch" (a git format-patch text), or "dry-run" (the plan and the diff);
+ *   - remote repo: always a plan, with the files to write yourself on a branch.
+ * Refused, blocked, conflicting or already applied: nothing written. Once a branch or files exist, the applied record
+ * is posted on the issue (best effort, needs Issues write) and the issue is labelled "being applied".
+ */
+export declare function applySuggestionOp(ctx: BridgeContext, a: {
+    number: number | string;
+    mode?: ApplyModeArg | undefined;
+    dryRun?: boolean | undefined;
+    acceptEdited?: boolean | undefined;
+    forceUnapproved?: boolean | undefined;
+    base?: string | undefined;
+    branch?: string | undefined;
+}): Promise<{
+    number: number;
+    status: string;
+    outcome: string;
+    exitCode: number;
+    message: string;
+} | {
+    next: string;
+    files?: {
+        path: string;
+        content: string | null;
+    }[] | undefined;
+    brief?: string | undefined;
+    checks?: {
+        tier: import("@bridge-ds/core").RiskTier;
+        tierWhenSuggested: import("@bridge-ds/core").RiskTier;
+        tierIncreased: boolean;
+        newErrors: number;
+        newContrastFailures: string[];
+    } | undefined;
+    approvals?: {
+        review: "changes-requested" | "needs-review" | "approved";
+        missing: string[];
+        forced: boolean;
+        edited: boolean;
+    } | undefined;
+    notes?: string[] | undefined;
+    problems?: string[] | undefined;
+    outcome: import("@bridge-ds/core").SuggestionApplyOutcome;
+    exitCode: 0 | 1 | 3;
+    version: string;
+    table: string;
+    number: number;
+    status: string;
+    message: string;
+} | {
+    next: string;
+    warnings?: string[] | undefined;
+    recorded: boolean;
+    diff?: string | undefined;
+    patch?: string | undefined;
+    written?: string[] | undefined;
+    commit?: string | undefined;
+    branch?: string | undefined;
+    exitCode: 0 | 1 | 3;
+    brief?: string | undefined;
+    checks?: {
+        tier: import("@bridge-ds/core").RiskTier;
+        tierWhenSuggested: import("@bridge-ds/core").RiskTier;
+        tierIncreased: boolean;
+        newErrors: number;
+        newContrastFailures: string[];
+    } | undefined;
+    approvals?: {
+        review: "changes-requested" | "needs-review" | "approved";
+        missing: string[];
+        forced: boolean;
+        edited: boolean;
+    } | undefined;
+    notes?: string[] | undefined;
+    problems?: string[] | undefined;
+    outcome: import("@bridge-ds/core").SuggestionApplyOutcome;
+    version: string;
+    table: string;
+    number: number;
+    status: import("@bridge-ds/core/node").LocalApplyStatus;
+    mode: string;
+    message: string;
+}>;
+/**
+ * bridge_link_suggestion / `bridge suggestions link <n> --pr <m>`: records the pull request (or branch) that applies a
+ * suggestion, with the applied comment, and labels it "being applied". A pull request that does not say "Closes #n"
+ * is linked with a warning: the suggestion only closes when it says so.
+ */
+export declare function linkSuggestionOp(ctx: BridgeContext, a: {
+    number: number | string;
+    pr?: number | undefined;
+    branch?: string | undefined;
+    commit?: string | undefined;
+    forced?: boolean | undefined;
+}): Promise<{
+    next: string;
+    warnings?: string[] | undefined;
+    branch?: string | undefined;
+    pr?: number | undefined;
+    number: number;
+    status: SuggestionStatus;
+    said: string;
+}>;
+/**
+ * bridge_create_suggestion: files any change as a suggestion from its payload (bridge.suggestion/1), for example the
+ * payload a dry run returned. Missing schema, source, date, base and checks are filled; the shape and the paths are
+ * checked against the kind's folders and the guardrails before anything is sent.
+ */
+export declare function createSuggestionOp(ctx: BridgeContext, a: {
+    payload: Record<string, unknown>;
+    labels?: string[] | undefined;
+    dryRun?: boolean | undefined;
+    source?: RequestSource | undefined;
+}): Promise<{
+    status: string;
+    title: string;
+    labels: string[];
+    body: string;
+    parts: number;
+    version: string;
+    message?: undefined;
+    payload?: undefined;
+} | {
+    status: string;
+    message: string;
+    payload: SuggestionPayloadV1;
+    title?: undefined;
+    labels?: undefined;
+    body?: undefined;
+    parts?: undefined;
+    version?: undefined;
+} | {
+    next: string;
+    warnings?: string[] | undefined;
+    status: string;
+    number: number;
+    url: string;
+    version: string;
+    title?: undefined;
+    labels?: undefined;
+    body?: undefined;
+    parts?: undefined;
+    message?: undefined;
+    payload?: undefined;
+}>;

package/package.json

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