@bridge-ds/core 0.9.0 → 0.10.0

package/dist/suggestion-apply.d.ts

@@ -0,0 +1,150 @@
+import type { BridgeConfig } from './config';
+import { type LayerIssue } from './layered';
+import { type ContrastDelta, type LayeredChange } from './layered-review';
+import { type ApprovalRole } from './review-gate';
+import { type RiskResult, type RiskTier } from './risk';
+import { type SuggestionApprovals, type SuggestionCommentLike, type SuggestionGovernance } from './suggestion-review';
+import { type ParsedSuggestion, type SuggestionPayloadV1 } from './suggestions';
+import { type TokenEdit } from './token-edits';
+/** What the planner reads. Paths are repo-relative and already checked by suggestionPathProblems. */
+export interface SuggestionWorkspace {
+    /** The file as it is now (text and git blob sha), or null when it does not exist. */
+    read(path: string): Promise<{
+        text: string;
+        sha: string;
+    } | null>;
+    /** The file at a commit (the payload's base sha), or null when it is missing there or the commit is unknown. */
+    readAt(ref: string, path: string): Promise<string | null>;
+    /** Every file path now, repo-relative (used to find the token files). */
+    list(): Promise<string[]>;
+    /** True when the path, or a folder on the way to it, is a symbolic link. Absent: no symlinks (a browser). */
+    isSymlink?(path: string): Promise<boolean>;
+    /** 3-way merge of a text file. Absent: a file changed on both sides is a conflict. */
+    merge?(input: {
+        path: string;
+        ours: string;
+        base: string;
+        theirs: string;
+    }): Promise<{
+        clean: boolean;
+        text: string;
+        conflicts: number;
+    }>;
+}
+export type SuggestionApplyOpState = 'already-applied' | 'apply' | 'apply-merged' | 'conflict';
+/** One change of the suggestion against the current tree. */
+export interface SuggestionApplyOp {
+    type: 'token' | 'file' | 'docs' | 'component-spec';
+    /** Token path for token edits, repo path otherwise. */
+    path: string;
+    /** Token edits: the edit as suggested. */
+    edit?: TokenEdit | undefined;
+    /** Token file the edit targets, relative to tokens.root, when known. */
+    file?: string | undefined;
+    state: SuggestionApplyOpState;
+    /** One sentence: what happens or why it conflicts. */
+    detail: string;
+    /** Conflicts: the value when suggested, the suggested value, and the value now. */
+    before?: unknown;
+    after?: unknown;
+    now?: unknown;
+    /** 3-way merge conflicts: how many conflict regions git found. */
+    hunks?: number | undefined;
+}
+export type SuggestionApplyOutcome = 
+/** The checks pass and every change can be written. */
+'ready'
+/** Every change is already in the tree: nothing to write. */
+ | 'already-applied'
+/** At least one change conflicts with the current tree: nothing is written. */
+ | 'conflict'
+/** The approvals on the current payload do not cover its tier. */
+ | 'not-approved'
+/** The re-run checks stop it: the tier went up, a contrast pair would fail, or a new validation error. */
+ | 'blocked'
+/** Not applied at all: unsafe path, symlink, edited payload, invalid content. */
+ | 'refused';
+/** Exit codes the CLI uses: 0 ok (ready or already applied), 1 gate or checks, 2 usage, 3 conflict. */
+export declare const SUGGESTION_APPLY_EXIT: Record<SuggestionApplyOutcome, 0 | 1 | 3>;
+export interface SuggestionApplyGate {
+    /** The payload's review state on its current sha. */
+    review: 'needs-review' | 'changes-requested' | 'approved';
+    /** Approvals still missing for the tier. */
+    missing: ApprovalRole[];
+    approvals: SuggestionApprovals;
+    /** Applied without the approvals because the developer asked for it (recorded in the applied comment). */
+    forced: boolean;
+    /** The payload no longer matches what Bridge wrote; applied only because the developer accepted it. */
+    edited: boolean;
+}
+export interface SuggestionApplyChecks {
+    /** Tier when suggested and recomputed on the current tree. */
+    tierWhenSuggested: RiskTier;
+    tier: RiskResult;
+    tierIncreased: boolean;
+    /** Validation errors the result adds to today's tokens. */
+    newErrors: LayerIssue[];
+    /** Contrast pairs that pass today and would fail. */
+    newFailures: ContrastDelta[];
+    /** Every contrast pair that moved. */
+    contrast: ContrastDelta[];
+    /** Token changes the result makes against today's tokens. */
+    tokenChanges: LayeredChange[];
+}
+export interface SuggestionApplyPlan {
+    outcome: SuggestionApplyOutcome;
+    exitCode: 0 | 1 | 3;
+    /** One sentence for people: what happens, or what stops it and how to go on. */
+    message: string;
+    /** sha256 of the payload the plan applies (what approvals bound to). */
+    payloadSha: string;
+    payload: SuggestionPayloadV1;
+    gate: SuggestionApplyGate | null;
+    ops: SuggestionApplyOp[];
+    /** Files to write when the outcome is "ready" (null content: delete). Empty otherwise. */
+    writes: {
+        path: string;
+        content: string | null;
+    }[];
+    checks: SuggestionApplyChecks | null;
+    /** Why it is refused or blocked, as sentences. */
+    problems: string[];
+    /** Notes for the developer (token aliases left broken, a payload file the token edits replace...). */
+    notes: string[];
+    /** Component specs: the brief Claude or a developer implements from the spec file. */
+    brief?: string | undefined;
+}
+export interface PlanSuggestionApplyInput {
+    /** The parsed issue (parseSuggestionIssue). */
+    parsed: Extract<ParsedSuggestion, {
+        ok: true;
+    }>;
+    /** bridge.config.json as read from the code (the default branch or the checkout), never from the payload. */
+    config: BridgeConfig;
+    /** Issue comments, for the approvals. */
+    comments: readonly SuggestionCommentLike[];
+    /** Owners and rights from the same config (plus team members when read). Default: the config's. */
+    governance?: SuggestionGovernance | undefined;
+    /** The issue author: never approves their own suggestion. */
+    author?: string | null | undefined;
+    workspace: SuggestionWorkspace;
+    /** Apply even though the payload was edited by hand since Bridge wrote it. */
+    acceptEdited?: boolean | undefined;
+    /** Apply without every approval, or with a tier that went up (recorded in the applied comment). */
+    forceUnapproved?: boolean | undefined;
+}
+/**
+ * The plan to apply a suggestion to the current tree. Never writes; the adapter writes `writes` when the outcome is
+ * "ready". Stops before reading any file when a path is unsafe.
+ */
+export declare function planSuggestionApply(input: PlanSuggestionApplyInput): Promise<SuggestionApplyPlan>;
+/** The comment recording where a planned suggestion was applied (posting it is the caller's job). */
+export declare function suggestionAppliedComment(plan: Pick<SuggestionApplyPlan, 'payloadSha' | 'gate'>, where: {
+    by?: string | undefined;
+    branch?: string | undefined;
+    commit?: string | undefined;
+    pr?: number | undefined;
+    at: string;
+}): string;
+/** The per-change table of a plan, as Markdown (the CLI dry run, the MCP answer). */
+export declare function suggestionApplyTable(plan: Pick<SuggestionApplyPlan, 'ops'>): string;

package/dist/suggestion-review.d.ts

@@ -0,0 +1,70 @@
+import type { Owners } from './config';
+import { type ApprovalRole, type ApprovalSummary } from './review-gate';
+import { type Rights } from './rights';
+import type { RiskTier } from './risk';
+import type { TeamStates } from './teams';
+export declare const SUGGESTION_REVIEW_MARK = "bridge-suggestion-review";
+export declare const SUGGESTION_APPLIED_MARK = "bridge-suggestion-applied";
+export type SuggestionReviewEvent = 'approve' | 'request-changes' | 'comment';
+export interface SuggestionReviewRecord {
+    event: SuggestionReviewEvent;
+    /** The role the reviewer approved for. Informative: what counts is the author against the owner lists. */
+    role?: ApprovalRole | undefined;
+    /** sha256 of the payload the reviewer saw (suggestionPayloadSha). */
+    payloadSha: string;
+    /** ISO date. */
+    at: string;
+}
+/** The comment a review posts: a sentence, the reviewer's message quoted, and the hidden record. */
+export declare function composeSuggestionReviewComment(r: SuggestionReviewRecord & {
+    by?: string | null | undefined;
+    message?: string | undefined;
+}): string;
+/** The review record in a comment, or null when the comment is not a Bridge review. */
+export declare function parseSuggestionReviewComment(body: string | null | undefined): SuggestionReviewRecord | null;
+/** A developer applied the suggestion: where, and on which payload. */
+export interface SuggestionAppliedRecord {
+    by?: string | undefined;
+    branch?: string | undefined;
+    commit?: string | undefined;
+    pr?: number | undefined;
+    payloadSha: string;
+    at: string;
+    /** Applied without the approvals (`--force-unapproved`). */
+    forced?: boolean | undefined;
+}
+/** The comment recording that a suggestion is being applied (a branch or a pull request exists). */
+export declare function composeSuggestionAppliedComment(r: SuggestionAppliedRecord): string;
+export declare function parseSuggestionAppliedComment(body: string | null | undefined): SuggestionAppliedRecord | null;
+/** A comment as read from GitHub (listIssueComments), oldest first. */
+export interface SuggestionCommentLike {
+    author: string;
+    body: string;
+    createdAt?: string | undefined;
+    /** GitHub's author_association: OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR, NONE... */
+    authorAssociation?: string | undefined;
+}
+export interface SuggestionGovernance {
+    owners: Owners;
+    rights?: Rights | null | undefined;
+    /** Team members once read (teams.ts). Undefined: owner entries are used as listed. */
+    teams?: TeamStates | null | undefined;
+}
+export interface SuggestionApprovals extends ApprovalSummary {
+    /** People whose latest review is on an older payload: it no longer counts. */
+    stale: string[];
+    /** People whose review does not count because they are not owners (or not collaborators when no owner is set). */
+    ignored: string[];
+}
+/**
+ * Approvals on a suggestion, as summarizeApprovals counts them on a pull request, from the review comments: only
+ * comments by people in the approver lists (governance owners and rights) count; with no owner configured at all, only
+ * repository owners, members and collaborators (GitHub's author association). Only reviews of the current payload
+ * sha count; the suggestion's author never approves their own suggestion.
+ */
+export declare function summarizeSuggestionApprovals(comments: readonly SuggestionCommentLike[], gov: SuggestionGovernance, opts: {
+    payloadSha: string;
+    author?: string | null | undefined;
+}): SuggestionApprovals;
+/** The review state for the status machine: changes requested beats approved; approved when no approval is missing. */
+export declare function suggestionReviewState(tier: RiskTier, approvals: ApprovalSummary): 'needs-review' | 'changes-requested' | 'approved';

package/dist/suggestions-github.d.ts

@@ -0,0 +1,131 @@
+import { GitHubClient, type IssueSummary, type PullRequestSummary } from './github-client';
+import { type SuggestionAppliedRecord, type SuggestionApprovals, type SuggestionCommentLike, type SuggestionGovernance, type SuggestionReviewEvent } from './suggestion-review';
+import { type ComposeSuggestionOptions, type ParsedSuggestion, type SuggestionKind, type SuggestionPayloadV1, type SuggestionStatus } from './suggestions';
+import type { ApprovalRole } from './review-gate';
+export interface CreatedSuggestion {
+    number: number;
+    url: string;
+    /** sha256 of the payload: what approvals bind to. */
+    sha: string;
+    /** Continuation comments posted. */
+    parts: number;
+    /** Sentences about parts that did not go through (labels refused). The suggestion itself holds. */
+    warnings: string[];
+}
+/**
+ * Files a suggestion: the issue (title, body, labels), then its continuation comments in order when the payload is
+ * too large for the body. A part that fails leaves the suggestion incomplete (parsers refuse it) and throws with the
+ * issue number, so the caller can say so.
+ */
+export declare function createSuggestionOnGitHub(gh: GitHubClient, payload: SuggestionPayloadV1, opts?: ComposeSuggestionOptions): Promise<CreatedSuggestion>;
+/** Linked pull requests of an issue, from the bodies that close it ("Closes #n"). */
+export declare function linkedPullsOf(n: number, pulls: readonly Pick<PullRequestSummary, 'number' | 'state' | 'body' | 'url'>[]): {
+    number: number;
+    url: string;
+    state: 'open' | 'closed';
+    merged: boolean;
+}[];
+export interface SuggestionListItem {
+    number: number;
+    title: string;
+    url: string;
+    author: string;
+    createdAt: string;
+    state: 'open' | 'closed';
+    stateReason: string | null;
+    labels: string[];
+    kind: SuggestionKind | undefined;
+    /** Tier from the `tier: N` label. */
+    tier: 1 | 2 | 3 | undefined;
+    linkedPrs: {
+        number: number;
+        url: string;
+        state: 'open' | 'closed';
+        merged: boolean;
+    }[];
+    /**
+     * Status from the issue state, linked pull requests and the state label (a cache: getSuggestionOnGitHub reads the
+     * review comments for the real one).
+     */
+    status: SuggestionStatus;
+}
+/**
+ * Suggestions in the repository, newest first. Status comes from labels and linked pull requests (one call per list,
+ * no comment reads); open getSuggestionOnGitHub for the counted approvals.
+ */
+export declare function listSuggestionsOnGitHub(gh: GitHubClient, opts?: {
+    state?: 'open' | 'closed' | 'all' | undefined;
+    perPage?: number | undefined;
+    pulls?: PullRequestSummary[] | undefined;
+}): Promise<SuggestionListItem[]>;
+export interface SuggestionDetail {
+    issue: IssueSummary;
+    parsed: ParsedSuggestion;
+    comments: (SuggestionCommentLike & {
+        id: number;
+    })[];
+    /** Counted on the current payload sha. Undefined when the payload does not parse. */
+    approvals: SuggestionApprovals | undefined;
+    linkedPrs: {
+        number: number;
+        url: string;
+        state: 'open' | 'closed';
+        merged: boolean;
+    }[];
+    applied: SuggestionAppliedRecord[];
+    status: SuggestionStatus;
+}
+/**
+ * One suggestion with everything its status needs: the payload (parts reassembled from the author's comments), the
+ * review comments counted against the owners of the config read from the default branch, linked pull requests and
+ * applied markers. `outdated` comes from the caller's dry run (it needs the current files).
+ */
+export declare function getSuggestionOnGitHub(gh: GitHubClient, n: number, gov: SuggestionGovernance, opts?: {
+    pulls?: PullRequestSummary[] | undefined;
+    outdated?: boolean | undefined;
+}): Promise<SuggestionDetail>;
+/**
+ * Keeps exactly one state label on the issue, the one the status calls for (none once closed or outdated). Best
+ * effort: returns a warning sentence when the labels could not be changed.
+ */
+export declare function syncSuggestionStateLabel(gh: GitHubClient, n: number, labels: readonly string[], status: SuggestionStatus): Promise<string | null>;
+export interface SuggestionReviewResult {
+    commentUrl: string;
+    payloadSha: string;
+    status: SuggestionStatus;
+    /** Whether this review counts (the reviewer is an owner, or a collaborator when no owner is set). */
+    counts: boolean;
+    warnings: string[];
+}
+/**
+ * Approves, requests changes on or comments on a suggestion as the token's user. `payloadSha` is the version the
+ * reviewer saw: when the payload changed since, nothing is posted and the error says to reload. Then the state label
+ * is re-synced from the recomputed status.
+ */
+export declare function reviewSuggestionOnGitHub(gh: GitHubClient, n: number, input: {
+    event: SuggestionReviewEvent;
+    role?: ApprovalRole | undefined;
+    message?: string | undefined;
+    payloadSha?: string | undefined;
+    by?: string | undefined;
+    at?: Date | undefined;
+}, gov: SuggestionGovernance): Promise<SuggestionReviewResult>;
+/**
+ * Records that a suggestion is being applied (the applied marker comment) and sets the `suggestion: applying` label.
+ * Called after a developer pushed the branch or opened the pull request that says "Closes #n".
+ */
+export declare function linkSuggestionPrOnGitHub(gh: GitHubClient, n: number, link: {
+    pr?: number | undefined;
+    branch?: string | undefined;
+    commit?: string | undefined;
+    by?: string | undefined;
+    payloadSha: string;
+    forced?: boolean | undefined;
+    at?: Date | undefined;
+}): Promise<{
+    warnings: string[];
+}>;
+/** Declines a suggestion like a request (reason comment, closed as not planned), then clears its state label. */
+export declare function declineSuggestionOnGitHub(gh: GitHubClient, n: number, reason: string, by?: string | null): Promise<{
+    warnings: string[];
+}>;

package/dist/suggestions.d.ts

@@ -0,0 +1,236 @@
+import { type BridgeConfig } from './config';
+import type { LayeredChange } from './layered-review';
+import { type NeededBy } from './prod-branch';
+import type { RequestSource } from './requests';
+import type { TokenEdit } from './token-edits';
+export declare const SUGGESTION_SCHEMA = "bridge.suggestion/1";
+/** Every suggestion issue carries this label; tools list suggestions by it. */
+export declare const SUGGESTION_LABEL = "bridge-suggestion";
+export type SuggestionKind = 'token-change' | 'docs' | 'component-spec' | 'brand' | 'revert' | 'config';
+export declare const SUGGESTION_KINDS: readonly SuggestionKind[];
+/** The states a suggestion label records, exactly one at a time while the issue is open. */
+export type SuggestionState = 'needs-review' | 'changes-requested' | 'approved' | 'applying';
+/** Where a suggestion stands (suggestionStatus). */
+export type SuggestionStatus = SuggestionState | 'applied' | 'declined' | 'outdated';
+export declare const SUGGESTION_STATE_LABELS: Record<SuggestionState, string>;
+export declare const SUGGESTION_STATUS_LABEL: Record<SuggestionStatus, string>;
+/** A whole-file result: the git blob sha at `base` (null: a new file), after (null: deleted), and the new content. */
+export interface SuggestionFile {
+    path: string;
+    beforeSha: string | null;
+    afterSha: string | null;
+    /** The new text; null for a deleted file. Absent from the body when it moved to a continuation comment (`part`). */
+    content?: string | null | undefined;
+    /** Continuation comment (1-based) where the content starts. Transport only: not part of the payload sha. */
+    part?: number | undefined;
+}
+export interface SuggestionContrastCheck {
+    pair: string;
+    mode?: string | undefined;
+    before: number;
+    after: number;
+    min: number;
+    pass: boolean;
+}
+export type SuggestionTokenChange = Pick<LayeredChange, 'kind' | 'path' | 'from' | 'file' | 'before' | 'after' | 'beforeCss' | 'afterCss'>;
+export interface SuggestionPayloadV1 {
+    schema: typeof SUGGESTION_SCHEMA;
+    kind: SuggestionKind;
+    title: string;
+    summary: string;
+    source: RequestSource;
+    /** GitHub login. */
+    suggestedBy?: string | undefined;
+    /** ISO date. */
+    createdAt: string;
+    /** Default branch and the commit the plan was computed on. */
+    base: {
+        ref: string;
+        sha: string;
+    };
+    tier: {
+        tier: 1 | 2 | 3;
+        bump: 'patch' | 'minor' | 'major';
+    };
+    /** Semantic token ops, applied with applyTokenEdits on the current token set, never as a text patch. */
+    tokens?: {
+        edits: TokenEdit[];
+        changes: SuggestionTokenChange[];
+    } | undefined;
+    /** docs.json edits: the component and the cleaned docs object. */
+    docs?: {
+        component: string;
+        path: string;
+        after: unknown;
+    }[] | undefined;
+    /** Figma component push spec, for Claude or a developer to implement. */
+    componentSpec?: {
+        component: string;
+        specPath: string;
+        spec: unknown;
+        brief: string;
+    } | undefined;
+    /** Whole-file results for everything else (changeset, brand files, revert, config). */
+    files?: SuggestionFile[] | undefined;
+    checks: {
+        newErrors: number;
+        contrast: SuggestionContrastCheck[];
+        /** The planner's `blocked` sentence at creation; a suggestion is never created when it is set. */
+        blocked: string | null;
+        impact: number;
+    };
+    links?: {
+        neededBy?: NeededBy | undefined;
+        figma?: {
+            fileKey?: string | undefined;
+            nodeId?: string | undefined;
+            url?: string | undefined;
+        } | undefined;
+        /** explore/<slug> */
+        exploration?: string | undefined;
+        /** A previous suggestion this one replaces. */
+        supersedes?: number | undefined;
+    } | undefined;
+    previews?: {
+        label: string;
+        url: string;
+    }[] | undefined;
+}
+/** GitHub caps an issue body and a comment at 65,536 characters. The budgets below keep every write under it. */
+export declare const SUGGESTION_LIMITS: {
+    readonly body: 65536;
+    /** The readable part of the body (tables are cut with "and N more"). */
+    readonly human: 12000;
+    /** The JSON block in the body. */
+    readonly inline: 48000;
+    /** The JSON block of one continuation comment. */
+    readonly part: 60000;
+    /** Continuation comments at most (about 480 KB of file contents). */
+    readonly maxParts: 8;
+};
+export type SuggestionErrorCode = 'too-large' | 'invalid';
+export declare class SuggestionError extends Error {
+    readonly code: SuggestionErrorCode;
+    constructor(code: SuggestionErrorCode, message: string);
+}
+export declare const SUGGESTION_TOO_LARGE = "Too large for a suggestion: split it, or ask a developer to open it directly.";
+/** sha256 of a string's UTF-8 bytes, as 64 hex characters. */
+export declare function sha256Hex(text: string): string;
+/** The git blob sha of a text file (what `git hash-object` and the GitHub contents API return). */
+export declare function gitBlobSha(text: string): string;
+/** JSON with object keys sorted and no spaces; `undefined` members dropped, as JSON.stringify does. */
+export declare function canonicalJson(value: unknown): string;
+/** sha256 of the payload's canonical JSON: what approvals bind to and what the marker records. */
+export declare function suggestionPayloadSha(p: SuggestionPayloadV1): string;
+/** Subject of the title: the component for docs and component specs, else the kind ("Tokens", "Brand"). */
+export declare function suggestionSubject(p: Pick<SuggestionPayloadV1, 'kind' | 'docs' | 'componentSpec'>): string;
+/** Issue title, like requests: "Tokens: raise color.action.primary.bg contrast", "Button: docs for the danger tone". */
+export declare function suggestionIssueTitle(p: Pick<SuggestionPayloadV1, 'kind' | 'title' | 'docs' | 'componentSpec'>): string;
+/**
+ * The labels of a suggestion issue: the list key, kind, source, tier, one state label, then the marks it carries
+ * (needed by a product, from Figma, exploration) and the caller's (governance or integrations labels). Labels are a
+ * cache for filtering: status is always recomputed from comments and pull requests.
+ */
+export declare function suggestionLabels(p: SuggestionPayloadV1, opts?: {
+    state?: SuggestionState | undefined;
+    labels?: string[] | undefined;
+}): string[];
+/** The kind a label set names, when the issue has a `suggestion: <kind>` label. */
+export declare function suggestionKindFromLabels(labels: readonly string[]): SuggestionKind | undefined;
+/** The state a label set records (the cache), when it has one. */
+export declare function suggestionStateFromLabels(labels: readonly string[]): SuggestionState | undefined;
+export interface SuggestionStatusInput {
+    state: 'open' | 'closed';
+    stateReason?: string | null | undefined;
+    /** Pull requests whose body closes the issue ("Closes #n"). */
+    linkedPrs?: {
+        state: 'open' | 'closed';
+        merged?: boolean | undefined;
+    }[] | undefined;
+    /** From the review comments on the current payload sha (suggestionReviewState in suggestion-review.ts). */
+    review?: 'needs-review' | 'changes-requested' | 'approved' | undefined;
+    /** An "applied" marker comment exists (a developer applied it on a branch, see linkSuggestionPrOnGitHub). */
+    applied?: boolean | undefined;
+    /** The dry-run apply found a conflict with the current default branch. */
+    outdated?: boolean | undefined;
+}
+/**
+ * Where a suggestion stands. Closed: applied when a linked pull request merged or the issue was closed as completed,
+ * declined otherwise. Open: applying when a linked pull request is open or an applied marker exists; outdated when the
+ * dry run found a conflict; then the review state (changes requested, approved, needs review).
+ */
+export declare function suggestionStatus(i: SuggestionStatusInput): SuggestionStatus;
+/** The state label a status keeps on the issue, or null when none should stay (closed, outdated). */
+export declare function suggestionStateLabel(status: SuggestionStatus): string | null;
+export interface SuggestionIssue {
+    title: string;
+    body: string;
+    labels: string[];
+    assignees: string[];
+    /** Continuation comments to post right after the issue, in order. Empty when everything fits in the body. */
+    parts: string[];
+    /** sha256 of the payload (canonical JSON, contents included). */
+    sha: string;
+}
+export interface ComposeSuggestionOptions {
+    labels?: string[] | undefined;
+    assignees?: string[] | undefined;
+    state?: SuggestionState | undefined;
+    /**
+     * Extra Markdown for the readable part, placed after the changes table (for example the risk tier reasons, contrast
+     * and impact sections of composeProposalBody). Cut to fit the readable budget.
+     */
+    details?: string | undefined;
+    /** "owner/name", for the Claude Code install line in "How to apply". Absent: a placeholder. */
+    repo?: string | undefined;
+}
+/** The one-time command that gives Claude Code the Bridge MCP server for a repository. */
+export declare const bridgeMcpInstallCommand: (repo?: string | null) => string;
+/** The suggestion as a GitHub issue: readable Markdown, labels, the payload block, and continuation comments when large. */
+export declare function composeSuggestionIssue(payload: SuggestionPayloadV1, opts?: ComposeSuggestionOptions): SuggestionIssue;
+export type SuggestionParseFailure = 'no-block' | 'invalid' | 'unsupported-version' | 'missing-part';
+export type ParsedSuggestion = {
+    ok: true;
+    payload: SuggestionPayloadV1;
+    /** sha256 of the payload as read now (what approvals bind to). */
+    sha: string;
+    /** The sha the marker recorded when Bridge wrote it. */
+    markedSha: string;
+    /** The payload or a part no longer matches what Bridge wrote: someone edited it by hand. */
+    edited: boolean;
+    /** Continuation comments read. */
+    parts: number;
+} | {
+    ok: false;
+    reason: SuggestionParseFailure;
+    message: string;
+};
+export interface SuggestionCommentInput {
+    body: string;
+    author?: string | undefined;
+}
+/** Whether a body carries a suggestion block (any version). */
+export declare function hasSuggestionBlock(body: string | null | undefined): boolean;
+/**
+ * The suggestion in an issue body (plus its continuation comments when it has parts). Checks the schema, reassembles
+ * the parts (only comments by the issue author count when `author` is given), recomputes the sha and compares it with
+ * the marker: a mismatch sets `edited` (shown, applied only when the developer accepts it).
+ */
+export declare function parseSuggestionIssue(body: string | null | undefined, opts?: {
+    comments?: SuggestionCommentInput[] | undefined;
+    author?: string | undefined;
+}): ParsedSuggestion;
+/** Problems with a payload's shape, as sentences. Empty when it is a valid v1 payload. */
+export declare function suggestionShapeProblems(raw: unknown): string[];
+/** Problems with one repo-relative path, as sentences. Empty when it is a plain path inside the repo. */
+export declare function unsafePathProblem(path: string): string | null;
+/** Whether a path is a governance guardrail (a trailing "/" in the list matches a directory). */
+export declare function isGuardrailPath(path: string, guardrails: readonly string[]): boolean;
+/** Where each kind may write, repo-relative. Undefined: anywhere (revert), still subject to guardrails. */
+export declare function suggestionAllowedRoots(kind: SuggestionKind, config: Pick<BridgeConfig, 'tokens' | 'changesets' | 'components'>): string[] | undefined;
+/**
+ * Every unsafe path in a payload, as sentences that say what is wrong: not a plain repo-relative path, outside the
+ * folders its kind may touch, or a governance guardrail (bridge.config.json is allowed for config and brand only).
+ * Token edit files are checked under the tokens root. Symlinks are checked where files are read (apply).
+ */
+export declare function suggestionPathProblems(p: SuggestionPayloadV1, config: Pick<BridgeConfig, 'tokens' | 'changesets' | 'components' | 'governance'>): string[];

package/dist/token-proposal.d.ts

@@ -1,5 +1,8 @@
 import type { BridgeConfig } from './config';
 import type { GitHubClient } from './github-client';
+import type { NeededBy } from './prod-branch';
+import type { RequestSource } from './requests';
+import { type SuggestionPayloadV1 } from './suggestions';
 import { LayeredTokenSet, type LayerIssue } from './layered';
 import { type ChangeTier, type ContrastDelta, type ImpactEntry, type LayeredChange } from './layered-review';
 import { type TokenEdit } from './token-edits';
@@ -7,6 +10,8 @@ import type { ContrastPair } from './wcag';
 export interface TokenProposalPlan {
     title: string;
     summary: string;
+    /** The token edits the plan applied: what a suggestion stores and re-applies on the current tokens. */
+    edits: TokenEdit[];
     before: LayeredTokenSet;
     after: LayeredTokenSet;
     changes: LayeredChange[];
@@ -70,3 +75,49 @@ export declare function writeTokenProposalOnGitHub(gh: GitHubClient, plan: Token
     /** Who proposes it, in the commit message: "Bridge MCP (source: mcp)". */
     tool?: string | undefined;
 }): Promise<OpenedTokenProposal>;
+export interface SuggestedTokenProposal {
+    status: 'suggested';
+    /** The suggestion issue. */
+    number: number;
+    url: string;
+    /** sha256 of the payload: what approvals bind to. */
+    sha: string;
+    labels: string[];
+    /** Sentences about parts that did not go through (labels refused). The suggestion itself holds. */
+    warnings: string[];
+}
+/** The suggestion payload (bridge.suggestion/1) of a planned token change, computed on `base`. Pure. */
+export declare function tokenSuggestionPayload(plan: TokenProposalPlan, ctx: {
+    base: {
+        ref: string;
+        sha: string;
+    };
+    source: RequestSource;
+    suggestedBy?: string | undefined;
+    createdAt?: string | undefined;
+    links?: SuggestionPayloadV1['links'];
+    previews?: SuggestionPayloadV1['previews'];
+}): SuggestionPayloadV1;
+/**
+ * Files a planned token change as a suggestion (suggest mode): one issue with the readable change, the checks and the
+ * exact edits, labelled like the pull request would be (tier, tokens, breaking), plus the suggestion labels. Needs
+ * Issues write only: no branch, no commit, no pull request. Refuses a blocked plan, like writeTokenProposalOnGitHub.
+ */
+export declare function suggestTokenProposalOnGitHub(gh: GitHubClient, plan: TokenProposalPlan, opts: {
+    /** Default branch the plan was computed on. Its head commit is recorded as the suggestion's base. */
+    base: string;
+    source: RequestSource;
+    /** GitHub login of who suggests it. */
+    suggestedBy?: string | undefined;
+    /** Labels before the tier ones (governance.labels), and after them (the product label). */
+    labels?: string[] | undefined;
+    labelsAfter?: string[] | undefined;
+    /** The product branch that needs it (a missing piece). */
+    neededBy?: NeededBy | undefined;
+    /** The Figma origin, a suggestion it replaces. */
+    links?: SuggestionPayloadV1['links'];
+    previews?: SuggestionPayloadV1['previews'];
+    assignees?: string[] | undefined;
+    /** Commit sha of `base`, when the caller already read it (saves a call). */
+    baseSha?: string | undefined;
+}): Promise<SuggestedTokenProposal>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge-ds/core",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Bridge core: bridge.config.json, DTCG token loading (tiers and layered modes), alias resolution, WCAG contrast, diffs, minimal-diff edits, PR body, the shared risk tier classifier, changesets and a fetch-based GitHub client. No Figma API, no DOM; Node-only helpers (git, reading a product folder) under @bridge-ds/core/node; the adoption audit under @bridge-ds/core/audit.",
   "license": "MIT",