@bridge-ds/core 0.8.0 → 0.10.0

package/dist/docs-proposal.d.ts

@@ -1,6 +1,9 @@
+import type { ChangesMode } from './config';
 import { type ComponentDocsJson } from './docs-draft';
 import type { GitHubClient, PullRequestSummary } from './github-client';
+import type { RequestSource } from './requests';
 import { type RiskResult } from './risk';
+import { type SuggestionPayloadV1 } from './suggestions';
 /** One component's docs.json, before (null: a new file) and after, at its repo path. */
 export interface DocsFileEdit {
     path: string;
@@ -114,13 +117,7 @@ export declare function docsProposal(edits: DocsFileEdit[], opts: {
     origin?: DocsOrigin | undefined;
     authorLine?: string | undefined;
 }): DocsProposal;
-/**
- * Opens one pull request with the docs edits from the default branch, the Jira key first in the title and the branch
- * name (Jira's GitHub integration links them). Returns its number, link and branch. Labels are best effort.
- * One open proposal per component: when the component already has one, the edit goes there as a new commit
- * (`continued`; `unchanged` when it already says this) instead of a second pull request.
- */
-export declare function proposeDocsOnGitHub(gh: GitHubClient, edits: DocsFileEdit[], opts: {
+export interface ProposeDocsOptions {
     base: string;
     title?: string | undefined;
     notes?: string | undefined;
@@ -131,16 +128,67 @@ export declare function proposeDocsOnGitHub(gh: GitHubClient, edits: DocsFileEdi
     commitNote?: string | undefined;
     /** Who wrote the text (docsAuthorLine). Without it, the origin's footer, never "no AI" over a Claude draft. */
     authorLine?: string | undefined;
-    /** Default true: continue the component's open proposal. False always opens a new one. */
+    /** Default true: continue the component's open proposal. False always opens a new one. Direct mode only. */
     continueOpen?: boolean | undefined;
-}): Promise<{
+    /**
+     * "direct" (default here, so existing callers keep their behaviour): a branch and a pull request. "suggest": a
+     * suggestion issue with the cleaned docs, no branch. Callers pass changesMode(config).
+     */
+    mode?: ChangesMode | undefined;
+    /** Suggest mode: where it was sent from (default from the origin: Studio, or MCP) and who sent it. */
+    source?: RequestSource | undefined;
+    suggestedBy?: string | undefined;
+    /** Suggest mode: commit sha of `base`, when the caller already read it. */
+    baseSha?: string | undefined;
+}
+export interface ProposedDocs {
+    status: 'opened' | 'continued';
     number: number;
     url: string;
     branch: string;
     title: string;
     continued: boolean;
     unchanged: boolean;
-}>;
+}
+export interface SuggestedDocs {
+    status: 'suggested';
+    /** The suggestion issue. */
+    number: number;
+    url: string;
+    title: string;
+    /** sha256 of the payload: what approvals bind to. */
+    sha: string;
+    warnings: string[];
+}
+/**
+ * The suggestion payload (bridge.suggestion/1, kind docs) of a set of docs edits: the cleaned docs object of each
+ * component (re-written at apply time as a minimal diff of the current file) and the patch changeset. Pure.
+ */
+export declare function docsSuggestionPayload(edits: DocsFileEdit[], opts: {
+    base: {
+        ref: string;
+        sha: string;
+    };
+    title?: string | undefined;
+    notes?: string | undefined;
+    date?: Date | undefined;
+    origin?: DocsOrigin | undefined;
+    source?: RequestSource | undefined;
+    suggestedBy?: string | undefined;
+    packageName?: string | undefined;
+    changesetDir?: string | undefined;
+}): SuggestionPayloadV1;
+/**
+ * Opens one pull request with the docs edits from the default branch, the Jira key first in the title and the branch
+ * name (Jira's GitHub integration links them). Returns its number, link and branch. Labels are best effort.
+ * One open proposal per component: when the component already has one, the edit goes there as a new commit
+ * (`continued`; `unchanged` when it already says this) instead of a second pull request.
+ * In suggest mode (`mode: 'suggest'`) it files a suggestion instead: no branch, no pull request (`status: 'suggested'`).
+ */
+export declare function proposeDocsOnGitHub(gh: GitHubClient, edits: DocsFileEdit[], opts: ProposeDocsOptions & {
+    mode?: 'direct' | undefined;
+}): Promise<ProposedDocs>;
+export declare function proposeDocsOnGitHub(gh: GitHubClient, edits: DocsFileEdit[], opts: ProposeDocsOptions): Promise<ProposedDocs | SuggestedDocs>;
 /**
  * Rewrites one file on an open branch in one commit (`next` gets the current text). Returns the commit sha, or ''
  * when nothing changed. The Library editor saves an edited docs.json and accepts a Claude draft this way.

package/dist/figma-push-github.d.ts

@@ -0,0 +1,143 @@
+import type { ChangesMode } from './config';
+import { type GitHubClient } from './github-client';
+import { type SuggestionPayloadV1 } from './suggestions';
+import type { TokenEdit } from './token-edits';
+import { type ComponentPushDiff, type ComponentPushPlan, type FigmaOrigin, type FigmaPushStatus, type PushTokenContext } from './figma-push';
+/**
+ * Opens the token change of an exact push: the caller plans it on the library's token files (planTokenProposal). In
+ * suggest mode (`mode`), it files a suggestion instead (suggestTokenProposalOnGitHub with `links: { figma }`) and
+ * returns its result: a result with `status: 'suggested'` is reported as a suggestion.
+ */
+export type FigmaTokenWriter = (input: {
+    edits: TokenEdit[];
+    title: string;
+    summary: string;
+    bodyExtra: string[];
+    mode: ChangesMode;
+    /** The Figma component, for the suggestion's links. */
+    figma: {
+        fileKey?: string | undefined;
+        nodeId?: string | undefined;
+        url?: string | undefined;
+    };
+}) => Promise<{
+    number: number;
+    url: string;
+    branch: string;
+    status?: undefined;
+} | {
+    status: 'suggested';
+    number: number;
+    url: string;
+}>;
+export interface OpenComponentPushInput {
+    diff: ComponentPushDiff;
+    /** Token facts to route it (planComponentPush), or the route already planned with every component of the file. */
+    tokens?: PushTokenContext | undefined;
+    plan?: ComponentPushPlan | undefined;
+    /** Branch library work starts from (the default branch). */
+    base: string;
+    /** governance.branchPrefix ("bridge/"). */
+    branchPrefix: string;
+    /** Labels the repo adds to every Bridge branch (governance.labels), before the Figma ones. */
+    labels?: string[] | undefined;
+    /** The token change of an exact push (planTokenProposal + writeTokenProposalOnGitHub where the token files are read). */
+    writeTokens?: FigmaTokenWriter | undefined;
+    /** "the DS Bridge Figma plugin", "Bridge MCP". */
+    tool?: string | undefined;
+    dryRun?: boolean | undefined;
+    /**
+     * "direct" (default here, so existing callers keep their behaviour): a branch and a pull request. "suggest": a
+     * suggestion issue (a token change, or a component spec for Claude), no branch. Callers pass changesMode(config).
+     */
+    mode?: ChangesMode | undefined;
+    /** Who sends it (a GitHub login), recorded on a suggestion. Defaults to the diff's requestedBy. */
+    suggestedBy?: string | undefined;
+    /** Commit sha of `base`, when the caller already read it (a component spec suggestion records it). */
+    baseSha?: string | undefined;
+}
+export interface OpenedComponentPush {
+    status: 'opened' | 'suggested' | 'dry-run' | 'not-sent';
+    plan: ComponentPushPlan;
+    /** The library branch: a token change or a Claude draft branch (a draft pull request). Null when suggested. */
+    link: {
+        route: 'token-change' | 'claude-draft';
+        number: number;
+        url: string;
+        branch: string;
+    } | null;
+    /** The suggestion issue (status 'suggested'): a token change, or a component spec Claude drafts the code from. */
+    suggestion?: {
+        route: 'token-change' | 'claude-draft';
+        number: number;
+        url: string;
+    } | undefined;
+}
+/** The suggestion payload (bridge.suggestion/1, kind component-spec) of a push that needs code. Pure. */
+export declare function componentSpecSuggestionPayload(d: ComponentPushDiff, plan: Pick<ComponentPushPlan, 'edits' | 'reasons' | 'issues'>, ctx: {
+    base: {
+        ref: string;
+        sha: string;
+    };
+    suggestedBy?: string | undefined;
+    createdAt?: string | undefined;
+    componentsDir?: string | undefined;
+}): SuggestionPayloadV1;
+/**
+ * Opens the library branch of a component change from Figma, linked to its origin (the Figma component): an exact token
+ * swap opens a token change (the shared proposal write: contrast gate, tier, changeset); anything that needs code opens
+ * a draft pull request carrying the spec (`.bridge/figma/<slug>.json`), labelled waiting for Claude. A manual change
+ * opens nothing: its issues say what to do in Figma.
+ * In suggest mode: the token swap is a token suggestion (through `writeTokens`), the code change a component spec
+ * suggestion (the spec inside the payload, labelled from Figma and waiting for Claude). Issues write only.
+ */
+export declare function openComponentPushOnGitHub(gh: GitHubClient, input: OpenComponentPushInput): Promise<OpenedComponentPush>;
+export interface FigmaChangeRow {
+    number: number;
+    title: string;
+    url: string;
+    branch: string;
+    origin: FigmaOrigin;
+    status: FigmaPushStatus;
+}
+/** Library branches opened from Figma components (label from-figma), newest first, with where each stands. */
+export declare function listFigmaChangesOnGitHub(gh: GitHubClient, opts?: {
+    state?: 'open' | 'closed' | 'all';
+}): Promise<FigmaChangeRow[]>;
+/** One library branch from Figma, its spec and Claude's brief to draft the code. */
+export declare function figmaChangeOnGitHub(gh: GitHubClient, n: number, opts?: {
+    componentsDir?: string | undefined;
+}): Promise<{
+    pull: import("./github-client").PullRequest & import("./github-client").PullRequestSummary & {
+        body: string;
+        mergeable: boolean | null;
+        requestedReviewers: string[];
+    };
+    origin: FigmaOrigin;
+    status: FigmaPushStatus;
+    spec: undefined;
+    brief: undefined;
+} | {
+    pull: import("./github-client").PullRequest & import("./github-client").PullRequestSummary & {
+        body: string;
+        mergeable: boolean | null;
+        requestedReviewers: string[];
+    };
+    origin: FigmaOrigin;
+    status: FigmaPushStatus;
+    spec: ComponentPushDiff & {
+        tokenEdits?: TokenEdit[];
+        reasons?: string[];
+    };
+    brief: string;
+}>;
+/**
+ * Claude wrote the code: the branch is labelled drafted by Claude AI (no longer waiting) and its description says so.
+ * Refused while the branch only carries the spec, so the label never claims code that is not there.
+ */
+export declare function markFigmaChangeDraftedOnGitHub(gh: GitHubClient, n: number): Promise<{
+    status: FigmaPushStatus;
+    files: string[];
+}>;
+/** Where each pushed Figma component's library branch stands (by pull request number), for the plugin's Pull. */
+export declare function figmaPushStatusesOnGitHub(gh: GitHubClient, numbers: number[]): Promise<Map<number, FigmaPushStatus>>;

package/dist/figma-push.d.ts

@@ -0,0 +1,204 @@
+import { type ComponentSpecsFile } from './component-spec';
+import { type RequestChange, type RequestKind, type RequestSource } from './requests';
+import type { TokenEdit } from './token-edits';
+import type { ContrastPair } from './wcag';
+/** Where a component change goes: a token change (exact), a library branch Claude drafts, or nowhere yet (manual). */
+export type PushRoute = 'token-change' | 'claude-draft' | 'manual';
+/** A token swap seen in Figma: in these variants, one property moved from one variable to another (token paths). */
+export interface Rebind {
+    /** Property family, as the scan names it: fill, stroke, radius, padding, gap, size, typography... */
+    kind: string;
+    /** Variant names ("Size=md, Tone=primary") where it moved. */
+    variants: string[];
+    /** Every variant of the component moved the same way. */
+    allVariants: boolean;
+    before: string[];
+    after: string[];
+}
+/** An edit the scan cannot read with confidence, and what the designer does about it. */
+export interface PushIssue {
+    what: string;
+    todo: string;
+}
+/**
+ * A component change from Figma, structured: what the designer sees in the Push tab, and what the library branch
+ * carries as its spec (the JSON Claude reads to write the code).
+ */
+export interface ComponentPushDiff {
+    v: 1;
+    /** Coded name ("Button"), or the proposed name of a new component ("DatePicker"). */
+    component: string;
+    /** Name of the set in Figma ("Forms / Date picker"). */
+    figmaName: string;
+    /** The component has a folder in code. */
+    coded: boolean;
+    kind: RequestKind;
+    /** One line, sentence case: "Add a lg size". */
+    title: string;
+    summary: string;
+    /** What changes, in one sentence. */
+    line?: string | undefined;
+    /** The rows of the change, as the Push tab lists them. */
+    changes: RequestChange[];
+    /** Token swaps, for the exact route. */
+    rebinds: Rebind[];
+    /** Something only code can carry: a variant, a property, layers, a swapped instance, a new component. */
+    needsCode: boolean;
+    /** Edits the scan cannot read with confidence: listed with what to do, never sent. */
+    unknown: PushIssue[];
+    figma?: {
+        fileKey?: string | undefined;
+        nodeId?: string | undefined;
+        nodeName?: string | undefined;
+        url?: string | undefined;
+    } | undefined;
+    /** The component as Figma has it now: variant axes, properties, bound variables (token paths) per variant. */
+    variantAxes: Record<string, string[]>;
+    properties: {
+        name: string;
+        type: string;
+        default: string;
+    }[];
+    bindings: Record<string, Record<string, string[]>>;
+    /** Layers of each variant, in order, as words ("instance Icon/Pencil, \"Icon\""). */
+    anatomy: Record<string, string[]>;
+    /** What code gave Figma at the last pull, when known. */
+    before?: {
+        variantAxes: Record<string, string[]>;
+        properties: {
+            name: string;
+            type: string;
+            default: string;
+        }[];
+    } | undefined;
+    /** Screenshot URLs (Figma exports on the requests branch). */
+    images?: string[] | undefined;
+    source: RequestSource;
+    requestedBy?: string | undefined;
+}
+/** What the plan needs to know about tokens, from wherever the caller reads them (the plugin, the MCP server). */
+export interface PushTokenContext {
+    /** Tier of a token path ("component", "semantic"...), undefined when the library has no such token. */
+    tierOf(path: string): string | undefined;
+    /**
+     * Where else this token paints: variants of the same component outside the swap ("Size=sm, Variant=primary"), and
+     * other components ("IconButton"). Empty lists: nowhere else.
+     */
+    usedElsewhere(path: string, rebind: Rebind): {
+        variants: string[];
+        components: string[];
+    };
+}
+export interface ComponentPushPlan {
+    route: PushRoute;
+    /** One sentence in designer words: what happens when it is sent. */
+    said: string;
+    /** Exact token edits: the whole change (token-change), or the part Claude makes too (claude-draft). */
+    edits: TokenEdit[];
+    /** Why a token swap needs Claude rather than a token change, one sentence each. */
+    reasons: string[];
+    /** Listed with what to do, never sent. */
+    issues: PushIssue[];
+    /** Other components an exact token change also repaints (they share the component token): said, for review. */
+    alsoChanges: string[];
+}
+/**
+ * How a component change from Figma goes back to the library. A token swap is exact when the property was painted by a
+ * component token (one variable before, one after), that token paints nothing else, and the new variable is a token
+ * the library has: the token then points to the new variable. Anything else that needs code is drafted by Claude AI;
+ * what cannot be read with confidence is listed with what to do.
+ */
+export declare function planComponentPush(d: ComponentPushDiff, ctx: PushTokenContext): ComponentPushPlan;
+/**
+ * Where else a token paints, from component-specs.json (what code gives each component): the variants of `component`
+ * outside the swap, and the other components. For tools that read the code, not a Figma file (the MCP server, the CLI).
+ */
+export declare function specsUsage(specs: Pick<ComponentSpecsFile, 'components'>, component: string): PushTokenContext['usedElsewhere'];
+/**
+ * The contrast gate for component token swaps. contrast.checks.json lists semantic pairs (action text on action bg);
+ * a component token that aliases one side of a pair is checked in its place, against the component token that aliases
+ * the other side (button.primary.text on button.primary.bg), else against that other side itself. So pointing
+ * button.primary.bg to a pale variable fails the same way the semantic pair would.
+ */
+export declare function componentContrastPairs(edits: readonly Pick<TokenEdit, 'path'>[], pairs: readonly ContrastPair[], tokens: {
+    aliasOf(path: string): string | undefined;
+    paths: readonly string[];
+}): ContrastPair[];
+/** Every library branch opened from a Figma component carries this label. */
+export declare const FROM_FIGMA_LABEL = "from-figma";
+/** A Claude draft branch that carries the spec only: no code yet. */
+export declare const WAITING_FOR_CLAUDE_LABEL = "waiting-for-claude";
+/** A Claude draft branch once Claude wrote the code: a person reviews it. */
+export declare const DRAFTED_BY_CLAUDE_LABEL = "drafted-by-claude";
+/** Where a Claude draft branch keeps the spec it was opened with. */
+export declare const FIGMA_SPEC_DIR = ".bridge/figma";
+export type FigmaOriginStatus = 'spec' | 'drafted';
+/** What the library branch remembers about where it came from: the Figma component and how it was routed. */
+export interface FigmaOrigin {
+    component: string;
+    figmaName: string;
+    route: Exclude<PushRoute, 'manual'>;
+    kind: RequestKind;
+    nodeId?: string | undefined;
+    fileKey?: string | undefined;
+    url?: string | undefined;
+    /** Claude draft branches: the spec file, and whether Claude wrote the code yet. */
+    spec?: string | undefined;
+    status?: FigmaOriginStatus | undefined;
+    requestedBy?: string | undefined;
+}
+export declare function parseFigmaOrigin(body: string | null | undefined): FigmaOrigin | undefined;
+/** The "From Figma" lines people read on GitHub, then the hidden block tools read. */
+export declare function figmaOriginSection(o: FigmaOrigin): string;
+/** The body with the "From Figma" section first (replacing an earlier one). */
+export declare function withFigmaOrigin(body: string | null | undefined, o: FigmaOrigin): string;
+export declare const figmaSpecSlug: (d: Pick<ComponentPushDiff, "component" | "title">) => string;
+/** The spec file of a Claude draft branch. */
+export declare const figmaSpecPath: (d: Pick<ComponentPushDiff, "component" | "title">) => string;
+/** The structured diff as the spec file stores it (stable key order, two-space JSON). */
+export declare function formatFigmaSpec(d: ComponentPushDiff, plan: Pick<ComponentPushPlan, 'edits' | 'reasons' | 'issues'>): string;
+/** Reads a spec file back; undefined when it is not one. */
+export declare function parseFigmaSpec(text: string | null | undefined): (ComponentPushDiff & {
+    tokenEdits?: TokenEdit[];
+    reasons?: string[];
+}) | undefined;
+/**
+ * What Claude gets to draft the code on the branch (MCP `bridge_get_figma_change`, CLI `bridge figma show`): the change,
+ * the spec, the exact token swaps to make too, the rules, and how to say it is drafted.
+ */
+export declare function figmaDraftBrief(d: ComponentPushDiff & {
+    tokenEdits?: TokenEdit[] | undefined;
+    reasons?: string[] | undefined;
+}, ctx: {
+    pr: number;
+    branch: string;
+    specPath: string;
+    componentsDir?: string | undefined;
+    agentsFile?: string | undefined;
+} | {
+    suggestion: true;
+    specPath: string;
+    componentsDir?: string | undefined;
+    agentsFile?: string | undefined;
+}): string;
+/** The pull request body of a Claude draft branch: the origin, the change, the rows and the spec. */
+export declare function figmaDraftBody(d: ComponentPushDiff, plan: Pick<ComponentPushPlan, 'edits' | 'reasons' | 'issues'>, o: FigmaOrigin): string;
+/** The title of a library branch opened from Figma: "Button: add a lg size". */
+export declare const figmaBranchTitle: (d: Pick<ComponentPushDiff, "component" | "title">) => string;
+export type FigmaPushStatusKey = 'waiting-for-claude' | 'drafted' | 'in-review' | 'shipped' | 'closed';
+export interface FigmaPushStatus {
+    key: FigmaPushStatusKey;
+    /** "Waiting for Claude AI", "Shipped". */
+    label: string;
+    /** One sentence for the designer. */
+    sentence: string;
+    /** The Figma component should be rebuilt from code (the branch shipped or was closed). */
+    rebuild: boolean;
+}
+/** Where a library branch opened from Figma stands, from its state and labels. */
+export declare function figmaPushStatus(x: {
+    state: string;
+    draft?: boolean | undefined;
+    labels?: readonly string[] | undefined;
+    route?: PushRoute | undefined;
+}): FigmaPushStatus;

package/dist/github-client.d.ts

@@ -302,12 +302,17 @@ export declare class GitHubClient {
     /** Best effort: labels need the repo to allow it; failure is not fatal. */
     addLabels(issueNumber: number, labels: string[]): Promise<boolean>;
     addComment(issueNumber: number, body: string): Promise<void>;
-    /** Comments on an issue or pull request, oldest first (first 100: the sticky preview comment is posted early). */
+    /**
+     * Comments on an issue or pull request, oldest first (first 100: the sticky preview comment is posted early).
+     * `authorAssociation` is GitHub's OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR, NONE... (suggestion approvals read it).
+     */
     listIssueComments(issueNumber: number): Promise<{
         id: number;
         body: string;
         author: string;
         updatedAt: string;
+        createdAt: string;
+        authorAssociation: string;
     }[]>;
     createIssue(input: {
         title: string;
@@ -508,6 +513,15 @@ export declare class GitHubClient {
     }>;
     /** GitHub's "Update branch": merges the base into the pull request, only when its head is still `expectedHeadSha`. */
     updatePullRequestBranch(n: number, expectedHeadSha: string): Promise<void>;
+    /**
+     * Merges the branch `head` into the branch `base` (GitHub's merges API): a merge commit on `base`, or nothing when
+     * `base` already has every commit of `head`. A conflict throws a GitHubError with status 409. Refuses protected
+     * branches and, with a branch prefix, a `base` without it.
+     */
+    mergeIntoBranch(base: string, head: string, message: string): Promise<{
+        status: 'merged' | 'up-to-date';
+        sha: string | null;
+    }>;
     /** Posts a comment on an issue or pull request and returns its id and link. */
     createIssueComment(n: number, body: string): Promise<{
         id: number;

package/dist/index.d.ts

@@ -54,3 +54,12 @@ export * from './share-branch';
 export * from './try-in-product';
 export * from './combine-branches';
 export * from './products';
+export * from './prod-branch';
+export * from './prod-branch-github';
+export * from './token-proposal';
+export * from './figma-push';
+export * from './figma-push-github';
+export * from './suggestions';
+export * from './suggestion-review';
+export * from './suggestions-github';
+export * from './suggestion-apply';