@rmartz/pr-lifecycle 5.0.0

package/dist/index.d.ts

@@ -0,0 +1,596 @@
+/**
+ * Bot-PR eligibility: is this a bot PR trusted enough to count as `approved`
+ * without a review (state priority 7 in docs/reconciler-design.md)? Ported from
+ * @rmartz/bot-automerge's classifier, with one deliberate tightening: the head
+ * branch must live in the base repository. See docs/bot-eligibility.md.
+ *
+ * FAIL-SAFE: every uncertain or unrecognized case is not eligible.
+ */
+declare const DEPENDABOT_LOGIN = "dependabot[bot]";
+declare const RELEASE_PLEASE_BRANCH_PREFIX = "release-please--";
+declare const RELEASE_PLEASE_PENDING_LABEL = "autorelease: pending";
+/** Dependabot's semver update types, lowest to highest risk. */
+declare const DEPENDABOT_UPDATE_TYPES: readonly ["version-update:semver-patch", "version-update:semver-minor", "version-update:semver-major"];
+type DependabotUpdateType = (typeof DEPENDABOT_UPDATE_TYPES)[number];
+type BotPrType = 'dependabot' | 'release-please';
+interface BotPrCommit {
+    /** The commit author's GitHub login; undefined when not linked to an account. */
+    authorLogin: string | undefined;
+    message: string;
+}
+interface BotPrFacts {
+    authorLogin: string;
+    headRef: string;
+    /** True when the head branch lives in a fork, not the base repository. */
+    isCrossRepository: boolean;
+    labels: readonly string[];
+    /** The PR's commits; only consulted for Dependabot PRs. */
+    commits: readonly BotPrCommit[];
+}
+interface BotEligibility {
+    eligible: boolean;
+    /** One-line justification, positive or negative, for dry-run output and logs. */
+    reason: string;
+    prType: BotPrType | undefined;
+    updateType: DependabotUpdateType | undefined;
+}
+/**
+ * The highest update type in a Dependabot commit's `updated-dependencies`
+ * metadata block, or undefined when the block is missing or any entry's type is
+ * unrecognized (fail-safe). A grouped update lists several dependencies; the
+ * riskiest one decides. Scans line by line — commit messages are untrusted
+ * input, so no backtracking regex runs over the whole message.
+ */
+declare function parseDependabotUpdateType(message: string): DependabotUpdateType | undefined;
+declare function classifyBotPr(facts: BotPrFacts): BotEligibility;
+
+/**
+ * The CI gate: is the PR's required CI passing, failing, or still running?
+ * Pure — the edge layer gathers the raw check results; this decides. See
+ * docs/reconciler-design.md §CI gate.
+ *
+ * "CI" is the base branch's required checks, with two kinds of exception:
+ * - **hold checks** (e.g. `pr-policy`) report *pending* while they wait on a human
+ *   act, which is a hold, not a running build — so their pending is ignored, but
+ *   their failure (a fixable problem) still counts;
+ * - **ignored checks** (e.g. `merge-safety`, whose failures mean "update needed"
+ *   or "base is red", handled by other states) never count at all.
+ */
+declare const CI_STATUSES: readonly ["failing", "passing", "pending"];
+type CiStatus = (typeof CI_STATUSES)[number];
+
+/**
+ * The facts the reconciler core computes a PR's lifecycle state from. The edge
+ * layer gathers these from GitHub; the core never performs I/O. See
+ * docs/reconciler-design.md §Facts.
+ */
+
+declare const REPO_PERMISSIONS: readonly ["admin", "maintain", "none", "read", "triage", "write"];
+type RepoPermission = (typeof REPO_PERMISSIONS)[number];
+declare const ACTOR_TYPES: readonly ["Bot", "User"];
+type ActorType = (typeof ACTOR_TYPES)[number];
+/** GitHub's native review states, as returned by the REST reviews API. */
+declare const REVIEW_STATES: readonly ["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED", "PENDING"];
+type ReviewState = (typeof REVIEW_STATES)[number];
+declare const PR_STATUSES: readonly ["closed", "merged", "open"];
+type PullRequestStatus = (typeof PR_STATUSES)[number];
+interface ReviewAuthor {
+    login: string;
+    type: ActorType;
+    /** The author's permission on the repository, fetched at the edge. */
+    permission: RepoPermission;
+}
+interface ReviewFact {
+    id: number;
+    author: ReviewAuthor;
+    /** The commit GitHub bound the review to (REST `commit_id`). */
+    commitSha: string;
+    state: ReviewState;
+    body: string;
+    /** ISO-8601 submission time. */
+    submittedAt: string;
+}
+interface PullRequestFacts {
+    status: PullRequestStatus;
+    isDraft: boolean;
+    title: string;
+    headSha: string;
+    labels: readonly string[];
+    autoMergeEnabled: boolean;
+    /** Result of the bot-PR eligibility predicate (Dependabot patch/minor, release-please). */
+    botEligible: boolean;
+    /**
+     * Whether the PR merges cleanly into its base: `false` is a merge conflict, and
+     * `undefined` means GitHub hasn't computed it yet (never treated as a conflict).
+     */
+    mergeable: boolean | undefined;
+    /**
+     * Whether GitHub would merge the PR right now, with nothing left to wait on
+     * (merge state `clean`, `has_hooks`, or `unstable`). Auto-merge can't be armed
+     * then, so an approved PR is merged directly instead, as `gh pr merge --auto` does.
+     */
+    immediatelyMergeable: boolean;
+    /** The CI gate over the head's required checks (see src/ci.ts). */
+    ciStatus: CiStatus;
+    /** Whether the same required checks are failing on the base branch head. */
+    baseCiFailing: boolean;
+    /**
+     * Earlier commits whose verdicts carry over to the head: every commit reached
+     * from the head through a chain of verified clean base merges (see
+     * docs/reconciler-design.md §Approval carry-over). Verified at the edge.
+     */
+    cleanAncestors: readonly string[];
+    reviews: readonly ReviewFact[];
+}
+interface ReconcilePolicy {
+    /**
+     * When set, only these logins (case-insensitive) may author a counting verdict,
+     * in addition to the write-permission requirement. It narrows trust and never
+     * widens it.
+     */
+    trustedAuthors?: readonly string[];
+    /** Arm/disarm native auto-merge from the lifecycle state. Off by default. */
+    armAutoMerge?: boolean;
+    /**
+     * Don't wait for a Copilot review before `review-requested`, for repos without
+     * Copilot code review (where the wait would never end). Off by default.
+     */
+    skipCopilotReview?: boolean;
+    /**
+     * Required checks whose *pending* is a hold on a human act, not a running build;
+     * their failures still count. Defaults to `DEFAULT_HOLD_CHECKS` (src/ci.ts).
+     */
+    holdChecks?: readonly string[];
+    /** Required checks the CI gate never counts. Defaults to `DEFAULT_IGNORED_CHECKS`. */
+    ignoredChecks?: readonly string[];
+}
+
+/**
+ * The narrow GitHub surface the edge layer needs, shaped around the domain rather
+ * than raw REST payloads. Decisions (permission mapping, which errors are
+ * tolerable, write order) live in gather.ts / execute.ts and are tested against
+ * a fake of this interface; the real implementation (http-client.ts) only maps
+ * requests and responses.
+ */
+interface PullRequestData {
+    /** GraphQL node id, needed for the auto-merge mutations. */
+    nodeId: string;
+    state: 'closed' | 'open';
+    merged: boolean;
+    draft: boolean;
+    title: string;
+    headSha: string;
+    labels: string[];
+    autoMergeEnabled: boolean;
+    /** The PR author's login; undefined when the account was deleted. */
+    authorLogin: string | undefined;
+    headRef: string;
+    /** The base branch name, whose rulesets define the required checks. */
+    baseRef: string;
+    /** Clone URL of the base repository, used to fetch commits for carry-over checks. */
+    cloneUrl: string;
+    /** True when the head branch lives in a fork (or a deleted repo), not the base. */
+    isCrossRepository: boolean;
+    /** `false` is a merge conflict; `undefined` means GitHub is still computing it. */
+    mergeable: boolean | undefined;
+    /** GitHub's merge state (`clean`, `blocked`, `behind`, …); undefined while computing. */
+    mergeState: string | undefined;
+}
+/** A check-run on a commit (the latest run per name). */
+interface CheckRunData {
+    name: string;
+    status: string;
+    conclusion: string | null;
+    completedAt: string | null;
+}
+/** A commit status (the latest per context) — the channel some CI uses instead of checks. */
+interface CommitStatusData {
+    context: string;
+    state: string;
+}
+/** A git commit's structure: its tree and parents (for carry-over verification). */
+interface CommitObject {
+    treeSha: string;
+    parents: string[];
+}
+/** The compare API's answer: how `head` relates to `base`, and their merge base. */
+interface CommitComparison {
+    /** `ahead` / `identical` mean `head` contains `base`. */
+    status: string;
+    mergeBaseSha: string;
+}
+interface CommitData {
+    /** The commit author's GitHub login; undefined when not linked to an account. */
+    authorLogin: string | undefined;
+    message: string;
+}
+interface ReviewData {
+    id: number;
+    /** Undefined when the author's account was deleted (a "ghost" review). */
+    login: string | undefined;
+    type: ActorType;
+    commitSha: string;
+    state: ReviewState;
+    body: string;
+    /** Undefined for a pending (unsubmitted) review. */
+    submittedAt: string | undefined;
+}
+/** The collaborator-permission API's answer: the legacy level and the role. */
+interface CollaboratorPermission {
+    /** Legacy level: admin, write, read, or none (maintain → write, triage → read). */
+    permission: string;
+    /** Fine-grained role: admin, maintain, write, triage, read, or a custom role. */
+    roleName: string;
+}
+interface LabelDefinition {
+    name: string;
+    color: string;
+    description: string;
+}
+interface GitHubClient {
+    getPullRequest(pr: number): Promise<PullRequestData>;
+    listReviews(pr: number): Promise<ReviewData[]>;
+    listCommits(pr: number): Promise<CommitData[]>;
+    /** The contexts the branch's rulesets require (empty when none are configured). */
+    getRequiredStatusChecks(branch: string): Promise<string[]>;
+    getBranchHeadSha(branch: string): Promise<string>;
+    listCheckRuns(sha: string): Promise<CheckRunData[]>;
+    listCommitStatuses(sha: string): Promise<CommitStatusData[]>;
+    getCommit(sha: string): Promise<CommitObject>;
+    compareCommits(base: string, head: string): Promise<CommitComparison>;
+    /** Throws a GitHubApiError with status 404 when the user is not a collaborator. */
+    getCollaboratorPermission(login: string): Promise<CollaboratorPermission>;
+    listRepoLabels(): Promise<string[]>;
+    /** Throws a GitHubApiError with status 422 when the label already exists. */
+    createLabel(label: LabelDefinition): Promise<void>;
+    addLabels(pr: number, names: readonly string[]): Promise<void>;
+    /** Throws a GitHubApiError with status 404 when the label is not on the PR. */
+    removeLabel(pr: number, name: string): Promise<void>;
+    /** Bodies of the PR's conversation comments, oldest first. */
+    listIssueComments(pr: number): Promise<string[]>;
+    createIssueComment(pr: number, body: string): Promise<void>;
+    /**
+     * Arm squash auto-merge, bound to `expectedHeadOid`: GitHub rejects it if the
+     * head has moved. Throws "…clean status" when the PR is already mergeable.
+     */
+    enableAutoMerge(pullRequestNodeId: string, expectedHeadOid: string): Promise<void>;
+    /** Squash-merge now, bound to `expectedHeadOid` like `enableAutoMerge`. */
+    mergePullRequest(pullRequestNodeId: string, expectedHeadOid: string): Promise<void>;
+    disableAutoMerge(pullRequestNodeId: string): Promise<void>;
+}
+/**
+ * The writes that must come from a real actor, so the merge they cause re-triggers
+ * `on: push` workflows (a `GITHUB_TOKEN` merge triggers nothing). Kept to these two
+ * calls so the release token is never used for anything else, reads included.
+ */
+type ReleaseActions = Pick<GitHubClient, 'enableAutoMerge' | 'mergePullRequest'>;
+declare class GitHubApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+declare function isApiStatus(error: unknown, status: number): boolean;
+
+/**
+ * The real GitHubClient: REST for reads and labels, GraphQL for the auto-merge
+ * mutations (REST has no endpoint for them). Deliberately thin — it maps requests
+ * and responses and throws GitHubApiError on failure; every decision lives in
+ * gather.ts / execute.ts. `fetch` is injectable so tests use a fake transport.
+ */
+interface HttpClientOptions {
+    token: string;
+    owner: string;
+    repo: string;
+    /** Defaults to GitHub.com; pass GITHUB_API_URL for GHES. */
+    apiUrl?: string;
+    fetch?: typeof fetch;
+}
+declare function createHttpClient(options: HttpClientOptions): GitHubClient;
+
+/**
+ * A bounded `git` subprocess runner. A non-zero exit is data (returned, not
+ * thrown), because `git merge-tree` reports conflicts that way; a timeout, a
+ * missing binary, or an oversized output throws. Injected so lineage code can be
+ * tested against real git in fixture repositories.
+ */
+interface GitResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+interface GitRunner {
+    run(args: readonly string[], env?: Readonly<Record<string, string>>): Promise<GitResult>;
+}
+declare function createGitRunner(): GitRunner;
+/** Parse `git version 2.54.0 (…)` into [major, minor]; undefined when unrecognized. */
+declare function parseGitVersion(output: string): [number, number] | undefined;
+
+/**
+ * Command-line entry for `ai-pr-lifecycle`. Kept free of `process` so it is fully
+ * testable: the bin shim (src/bin/pr-lifecycle.ts) supplies argv, the environment,
+ * and the output streams, and turns the returned code into the exit status.
+ *
+ * Exit codes (a contract with rmartz/pr-lifecycle-action; see docs/cli.md):
+ * 0 reconciled (including "nothing to do" and a skipped closed PR), 1 a GitHub or
+ * other runtime failure, 2 a usage or configuration error.
+ */
+interface CliIo {
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+}
+interface CliDeps {
+    env: Readonly<Record<string, string | undefined>>;
+    /** Builds the GitHub client; tests inject a fake. */
+    createClient?: (options: HttpClientOptions) => GitHubClient;
+    /** Runs git for approval carry-over; tests inject one. Defaults to the real binary. */
+    git?: GitRunner;
+}
+declare const USAGE = "Usage: ai-pr-lifecycle <command> [options]\n\nCommands:\n  reconcile   Recompute a PR's lifecycle state and converge its labels\n  help        Show this message\n\nreconcile options:\n  --repo <owner/repo>       Repository (required)\n  --pr <number>             Pull request number (required)\n  --arm-auto-merge          Arm/disarm native auto-merge from the state\n  --trusted-authors <a,b>   Only these logins (with write access) may cast verdicts\n  --skip-copilot-review     Don't wait for a Copilot review\n  --hold-checks <a,b>       Required checks whose pending is a hold (default: pr-policy)\n  --ignore-checks <a,b>     Required checks CI never counts (default: merge-safety)\n  --dry-run                 Compute the plan without writing anything\n  --json                    Print one JSON object (schemaVersion 1) on stdout\n  --no-token-advisory       Don't comment on the PR when arming lacks a release token\n\nEnvironment:\n  GITHUB_TOKEN              Token for reads and writes (required)\n  PR_LIFECYCLE_TOKEN\n                            Real-actor token for arming and merging; without it,\n                            --arm-auto-merge keeps labels but skips arm/merge\n  GITHUB_API_URL            API base URL (GitHub Enterprise Server)";
+declare function runCli(argv: readonly string[], io: CliIo, deps: CliDeps): Promise<number>;
+
+/**
+ * Argument parsing for `ai-pr-lifecycle`. Pure: argv in, a parsed command or a
+ * usage error out, so every flag is tested without a process. The contract is
+ * recorded on #6 and in docs/cli.md.
+ */
+interface ReconcileArgs {
+    command: 'reconcile';
+    owner: string;
+    repo: string;
+    pr: number;
+    policy: ReconcilePolicy;
+    dryRun: boolean;
+    json: boolean;
+    /** Comment on the PR when arming is skipped for want of a release token. */
+    tokenAdvisory: boolean;
+}
+type ParsedArgs = ReconcileArgs | {
+    command: 'help';
+} | {
+    command: 'error';
+    message: string;
+};
+declare function parseArgs(argv: readonly string[]): ParsedArgs;
+
+/**
+ * Lifecycle state, computed from facts in a fixed priority order. See
+ * docs/reconciler-design.md §State.
+ */
+declare const LIFECYCLE_STATES: readonly ["approved", "awaiting-ci", "awaiting-copilot", "blocked-base-red", "changes-requested", "ci-failing", "closed", "draft", "escalation-needed", "fix-required", "review-requested"];
+type LifecycleState = (typeof LIFECYCLE_STATES)[number];
+declare const COPILOT_REVIEWER_LOGIN = "copilot-pull-request-reviewer[bot]";
+declare function computeState(facts: PullRequestFacts, policy: ReconcilePolicy): LifecycleState;
+
+/**
+ * The reconcile plan: the minimal label and auto-merge changes that converge a PR
+ * to its computed lifecycle state. Labels are output only — the core owns the
+ * lifecycle labels (plus `auto-merge enabled` in arming mode) and never touches
+ * any other label. See docs/reconciler-design.md §Plan.
+ */
+declare const LIFECYCLE_LABELS: readonly ["approved", "changes requested", "escalation needed", "fix required", "ci failing", "review requested"];
+type LifecycleLabel = (typeof LIFECYCLE_LABELS)[number];
+declare const AUTO_MERGE_LABEL = "auto-merge enabled";
+/**
+ * `merge` is arming's twin for a PR GitHub would already merge: auto-merge can't
+ * be armed then, so it is merged directly (see `immediatelyMergeable`).
+ */
+type AutoMergeAction = 'arm' | 'disarm' | 'merge' | 'none';
+interface ReconcilePlan {
+    state: LifecycleState;
+    addLabels: string[];
+    removeLabels: string[];
+    autoMerge: AutoMergeAction;
+}
+declare function planReconcile(facts: PullRequestFacts, policy: ReconcilePolicy): ReconcilePlan;
+/**
+ * The plan with arming and merging taken out, for when no real-actor token is
+ * available to perform them (docs/cli.md §Release token). Disarming stays: it is
+ * safety, and any token may do it. Pure, like the planner.
+ */
+declare function withoutArming(plan: ReconcilePlan): ReconcilePlan;
+
+interface MergeStep {
+    /** The merge base of the two parents. */
+    mergeBase: string;
+    first: string;
+    second: string;
+    /** The tree the merge commit actually has. */
+    tree: string;
+}
+interface RepoSource {
+    /** Clone URL of the repository (https, or file:// in tests). */
+    url: string;
+    /** Token for an https URL; sent as a header, never in argv or the URL. */
+    token?: string;
+}
+interface MergeVerifier {
+    /** True only when the step is a verified clean merge; false on any doubt. */
+    verify(step: MergeStep): Promise<boolean>;
+    dispose(): Promise<void>;
+}
+/**
+ * A verifier bound to one repository and one scratch directory. Returns
+ * undefined when git is too old to verify at all (the caller then carries
+ * nothing over).
+ */
+declare function createMergeVerifier(git: GitRunner, source: RepoSource): Promise<MergeVerifier | undefined>;
+
+/**
+ * Finds the head's clean ancestors: commits reached by walking back from the head
+ * through a chain of **verified clean base merges**, so reviews bound to them
+ * still describe the change being merged (docs/reconciler-design.md §Approval
+ * carry-over). Fails closed: any doubt or error ends the chain, and the cost is
+ * an extra review, never a false approval.
+ */
+/** A longer chain of base merges than this is unusual enough to review again. */
+declare const MAX_CHAIN_STEPS = 20;
+type LineageClient = Pick<GitHubClient, 'compareCommits' | 'getCommit'>;
+interface LineageInput {
+    headSha: string;
+    /** The base branch's current head: every merged-in base commit must be on it. */
+    baseHeadSha: string;
+    source: RepoSource;
+    reviews: readonly ReviewData[];
+}
+interface Lineage {
+    cleanAncestors: string[];
+    /** Why the walk stopped, for reporting. */
+    stoppedBecause: string;
+}
+declare function gatherLineage(client: LineageClient, git: GitRunner, input: LineageInput): Promise<Lineage>;
+
+/**
+ * Gathers a PR's facts from GitHub for the pure core. Everything is read before
+ * anything is written (one gather → plan → execute pass per run), so a run never
+ * reacts to its own writes. See docs/github-edge-layer.md.
+ */
+interface GatheredPullRequest {
+    facts: PullRequestFacts;
+    /** GraphQL node id, for the auto-merge mutations. */
+    nodeId: string;
+    /** The bot-eligibility verdict behind `facts.botEligible`, with its reason. */
+    botEligibility: BotEligibility;
+    /** How far approval carry-over verified, for reporting (absent when off). */
+    lineage: Lineage | undefined;
+}
+interface GatherOptions {
+    /**
+     * Enables approval carry-over across clean base updates, which needs git and a
+     * token that can fetch the repository. Omitted, carry-over is off (fail closed:
+     * earlier-commit verdicts simply don't count).
+     */
+    lineage?: {
+        git: GitRunner;
+        token?: string;
+    };
+}
+declare function gatherFacts(client: GitHubClient, pr: number, policy?: ReconcilePolicy, options?: GatherOptions): Promise<GatheredPullRequest>;
+
+interface ReconcileOptions extends GatherOptions {
+    /** Compute and return the plan without writing anything. */
+    dryRun?: boolean;
+    /**
+     * Who arms and merges. Defaults to `client`, right when its token is a real
+     * actor. `'unavailable'` (no real-actor token configured) skips arming and
+     * merging rather than doing them with a token whose merge triggers no workflows.
+     */
+    release?: ReleaseActions | 'unavailable';
+}
+interface ReconcileResult {
+    plan: ReconcilePlan;
+    /** Why the PR was (or wasn't) treated as a trusted bot PR, for reporting. */
+    botEligibility: BotEligibility;
+    /** How far approval carry-over verified (absent when carry-over is off). */
+    lineage: Lineage | undefined;
+    /** The arm or merge the plan wanted but skipped because `release` was unavailable. */
+    skippedAutoMerge: 'arm' | 'merge' | undefined;
+}
+/**
+ * One full reconcile pass for a PR: gather its facts, plan, and (unless dry-run)
+ * execute. Returns the plan, the bot-eligibility verdict, and the carry-over
+ * result so callers can report what changed and why.
+ */
+declare function reconcilePullRequest(client: GitHubClient, pr: number, policy: ReconcilePolicy, options?: ReconcileOptions): Promise<ReconcileResult>;
+
+/**
+ * CLI output. `--json` is a versioned contract consumed by rmartz/pr-lifecycle-action
+ * (as step outputs): exactly one object on stdout, every field always present
+ * (absent values are `null`, never omitted). Renaming, removing, or retyping a field
+ * is a breaking change that bumps SCHEMA_VERSION; adding a field is not. Pinned by
+ * test/cli.test.ts and documented in docs/cli.md.
+ */
+declare const SCHEMA_VERSION = 1;
+interface ReconcileTarget {
+    owner: string;
+    repo: string;
+    pr: number;
+    dryRun: boolean;
+}
+interface ReconcileJson {
+    schemaVersion: typeof SCHEMA_VERSION;
+    repo: string;
+    pr: number;
+    dryRun: boolean;
+    state: string;
+    addLabels: string[];
+    removeLabels: string[];
+    autoMerge: string;
+    botEligibility: {
+        eligible: boolean;
+        reason: string;
+        prType: string | null;
+        updateType: string | null;
+    };
+    /** Approval carry-over across clean base updates; `null` when it didn't run. */
+    carryOver: {
+        cleanAncestors: string[];
+        stoppedBecause: string;
+    } | null;
+    /** An arm or merge the plan wanted but skipped; `null` when nothing was skipped. */
+    autoMergeSkipped: {
+        action: 'arm' | 'merge';
+        reason: 'token-missing';
+    } | null;
+}
+declare function toReconcileJson(target: ReconcileTarget, result: ReconcileResult): ReconcileJson;
+/** One human-readable line, e.g. `rmartz/x#7 → approved: +approved, auto-merge arm`. */
+declare function formatSummary(target: ReconcileTarget, result: ReconcileResult): string;
+
+/**
+ * Executes a reconcile plan against GitHub. Writes happen in a fail-safe order —
+ * disarm, remove labels, add labels, arm — so a run that dies midway never leaves
+ * auto-merge armed on a PR that is not approved. Arming and merging go through
+ * `release` (a real-actor token) and are bound to the planned head. See
+ * docs/github-edge-layer.md.
+ */
+interface PlanTarget {
+    pr: number;
+    nodeId: string;
+    /** The head the plan was computed for; a merge or arm is rejected if it moved. */
+    headSha: string;
+}
+declare function executePlan(client: GitHubClient, target: PlanTarget, plan: ReconcilePlan, release?: ReleaseActions): Promise<void>;
+
+/**
+ * Canonical definitions for the labels the reconciler owns, mirroring the fleet
+ * roster (rmartz/dotfiles claude/scripts/labels.yml). Used only to create a label
+ * a consumer repo is missing; an existing label's color and description are never
+ * changed.
+ */
+declare const OWNED_LABEL_DEFINITIONS: Record<LifecycleLabel | typeof AUTO_MERGE_LABEL, LabelDefinition>;
+
+/**
+ * The advisory comment posted when a PR is ready to arm or merge but no release
+ * token is configured (modelled on storybook-ci's missing-PAT advisory). It is the
+ * one signal a human will actually see — a warning in the job log goes unread —
+ * and it is posted at most once per PR, found again by its marker.
+ */
+declare const TOKEN_ADVISORY_MARKER = "<!-- pr-lifecycle:token-missing -->";
+declare const RELEASE_TOKEN_DOCS_URL = "https://github.com/rmartz/pr-lifecycle/blob/main/docs/cli.md#release-token";
+/** Pure, so it is unit-tested. */
+declare function buildTokenAdvisoryBody(skipped: 'arm' | 'merge'): string;
+/**
+ * Post the advisory unless the PR already has one. Returns whether a comment was
+ * posted, so callers can report it.
+ */
+declare function postTokenAdvisory(client: GitHubClient, pr: number, skipped: 'arm' | 'merge'): Promise<boolean>;
+
+/**
+ * Verdict parsing and trust. A review is a verdict when it carries a /review
+ * `skill-meta` marker with a verdict outcome, or (with no marker) a native
+ * APPROVED / CHANGES_REQUESTED state. It *counts* only from a trusted author and
+ * only when bound to the current head. See docs/reconciler-design.md §Verdicts.
+ */
+declare const VERDICTS: readonly ["approved", "changes-requested", "escalation-needed"];
+type Verdict = (typeof VERDICTS)[number];
+interface ParsedVerdict {
+    verdict: Verdict;
+    /** The head SHA the marker says was reviewed, when the marker names one. */
+    markerHead: string | undefined;
+}
+/** The verdict a review expresses, or undefined when it is not a verdict. */
+declare function parseVerdict(review: ReviewFact): ParsedVerdict | undefined;
+/** Whether an author may cast a counting verdict under the policy. */
+declare function isTrustedAuthor(author: ReviewAuthor, policy: ReconcilePolicy): boolean;
+declare function currentVerdict(facts: PullRequestFacts, policy: ReconcilePolicy): Verdict | undefined;
+
+export { ACTOR_TYPES, AUTO_MERGE_LABEL, type ActorType, type AutoMergeAction, type BotEligibility, type BotPrCommit, type BotPrFacts, type BotPrType, COPILOT_REVIEWER_LOGIN, type CliDeps, type CliIo, type CollaboratorPermission, type CommitData, DEPENDABOT_LOGIN, DEPENDABOT_UPDATE_TYPES, type DependabotUpdateType, type GatherOptions, type GatheredPullRequest, GitHubApiError, type GitHubClient, type GitResult, type GitRunner, type HttpClientOptions, LIFECYCLE_LABELS, LIFECYCLE_STATES, type LabelDefinition, type LifecycleLabel, type LifecycleState, type Lineage, type LineageInput, MAX_CHAIN_STEPS, type MergeStep, type MergeVerifier, OWNED_LABEL_DEFINITIONS, PR_STATUSES, type ParsedArgs, type ParsedVerdict, type PlanTarget, type PullRequestData, type PullRequestFacts, type PullRequestStatus, RELEASE_PLEASE_BRANCH_PREFIX, RELEASE_PLEASE_PENDING_LABEL, RELEASE_TOKEN_DOCS_URL, REPO_PERMISSIONS, REVIEW_STATES, type ReconcileArgs, type ReconcileJson, type ReconcileOptions, type ReconcilePlan, type ReconcilePolicy, type ReconcileResult, type ReconcileTarget, type ReleaseActions, type RepoPermission, type RepoSource, type ReviewAuthor, type ReviewData, type ReviewFact, type ReviewState, SCHEMA_VERSION, TOKEN_ADVISORY_MARKER, USAGE, VERDICTS, type Verdict, buildTokenAdvisoryBody, classifyBotPr, computeState, createGitRunner, createHttpClient, createMergeVerifier, currentVerdict, executePlan, formatSummary, gatherFacts, gatherLineage, isApiStatus, isTrustedAuthor, parseArgs, parseDependabotUpdateType, parseGitVersion, parseVerdict, planReconcile, postTokenAdvisory, reconcilePullRequest, runCli, toReconcileJson, withoutArming };

package/dist/index.js

@@ -0,0 +1,90 @@
+import {
+  ACTOR_TYPES,
+  AUTO_MERGE_LABEL,
+  COPILOT_REVIEWER_LOGIN,
+  DEPENDABOT_LOGIN,
+  DEPENDABOT_UPDATE_TYPES,
+  GitHubApiError,
+  LIFECYCLE_LABELS,
+  LIFECYCLE_STATES,
+  MAX_CHAIN_STEPS,
+  OWNED_LABEL_DEFINITIONS,
+  PR_STATUSES,
+  RELEASE_PLEASE_BRANCH_PREFIX,
+  RELEASE_PLEASE_PENDING_LABEL,
+  RELEASE_TOKEN_DOCS_URL,
+  REPO_PERMISSIONS,
+  REVIEW_STATES,
+  SCHEMA_VERSION,
+  TOKEN_ADVISORY_MARKER,
+  USAGE,
+  VERDICTS,
+  buildTokenAdvisoryBody,
+  classifyBotPr,
+  computeState,
+  createGitRunner,
+  createHttpClient,
+  createMergeVerifier,
+  currentVerdict,
+  executePlan,
+  formatSummary,
+  gatherFacts,
+  gatherLineage,
+  isApiStatus,
+  isTrustedAuthor,
+  parseArgs,
+  parseDependabotUpdateType,
+  parseGitVersion,
+  parseVerdict,
+  planReconcile,
+  postTokenAdvisory,
+  reconcilePullRequest,
+  runCli,
+  toReconcileJson,
+  withoutArming
+} from "./chunk-RQEBRPZU.js";
+export {
+  ACTOR_TYPES,
+  AUTO_MERGE_LABEL,
+  COPILOT_REVIEWER_LOGIN,
+  DEPENDABOT_LOGIN,
+  DEPENDABOT_UPDATE_TYPES,
+  GitHubApiError,
+  LIFECYCLE_LABELS,
+  LIFECYCLE_STATES,
+  MAX_CHAIN_STEPS,
+  OWNED_LABEL_DEFINITIONS,
+  PR_STATUSES,
+  RELEASE_PLEASE_BRANCH_PREFIX,
+  RELEASE_PLEASE_PENDING_LABEL,
+  RELEASE_TOKEN_DOCS_URL,
+  REPO_PERMISSIONS,
+  REVIEW_STATES,
+  SCHEMA_VERSION,
+  TOKEN_ADVISORY_MARKER,
+  USAGE,
+  VERDICTS,
+  buildTokenAdvisoryBody,
+  classifyBotPr,
+  computeState,
+  createGitRunner,
+  createHttpClient,
+  createMergeVerifier,
+  currentVerdict,
+  executePlan,
+  formatSummary,
+  gatherFacts,
+  gatherLineage,
+  isApiStatus,
+  isTrustedAuthor,
+  parseArgs,
+  parseDependabotUpdateType,
+  parseGitVersion,
+  parseVerdict,
+  planReconcile,
+  postTokenAdvisory,
+  reconcilePullRequest,
+  runCli,
+  toReconcileJson,
+  withoutArming
+};