@rmartz/pr-lifecycle 5.0.0

package/dist/chunk-RQEBRPZU.js

@@ -0,0 +1,1296 @@
+// src/bot-eligibility.ts
+var DEPENDABOT_LOGIN = "dependabot[bot]";
+var RELEASE_PLEASE_BRANCH_PREFIX = "release-please--";
+var RELEASE_PLEASE_PENDING_LABEL = "autorelease: pending";
+var DEPENDABOT_UPDATE_TYPES = [
+  "version-update:semver-patch",
+  "version-update:semver-minor",
+  "version-update:semver-major"
+];
+var ELIGIBLE_UPDATE_TYPES = /* @__PURE__ */ new Set([
+  "version-update:semver-patch",
+  "version-update:semver-minor"
+]);
+function isUpdateType(value) {
+  return DEPENDABOT_UPDATE_TYPES.some((type) => type === value);
+}
+function parseDependabotUpdateType(message) {
+  const lines = message.split("\n");
+  const start = lines.findIndex((line) => line.trim() === "updated-dependencies:");
+  if (start === -1) {
+    return void 0;
+  }
+  let highest = -1;
+  for (const line of lines.slice(start + 1)) {
+    const trimmed = line.trim();
+    if (trimmed === "...") {
+      break;
+    }
+    if (!trimmed.startsWith("update-type:")) {
+      continue;
+    }
+    const value = trimmed.slice("update-type:".length).trim();
+    if (!isUpdateType(value)) {
+      return void 0;
+    }
+    highest = Math.max(highest, DEPENDABOT_UPDATE_TYPES.indexOf(value));
+  }
+  return DEPENDABOT_UPDATE_TYPES[highest];
+}
+function result(eligible, reason, prType, updateType) {
+  return { eligible, reason, prType, updateType };
+}
+function classifyDependabot(commits) {
+  if (commits.length === 0) {
+    return result(false, "Dependabot PR with no commits \u2014 not eligible", "dependabot");
+  }
+  if (commits.some((commit) => commit.authorLogin !== DEPENDABOT_LOGIN)) {
+    return result(
+      false,
+      "Dependabot PR has non-Dependabot commits \u2014 held for review",
+      "dependabot"
+    );
+  }
+  let highest = -1;
+  for (const commit of commits) {
+    const type = parseDependabotUpdateType(commit.message);
+    if (type === void 0) {
+      return result(false, "Dependabot update type unavailable \u2014 not eligible", "dependabot");
+    }
+    highest = Math.max(highest, DEPENDABOT_UPDATE_TYPES.indexOf(type));
+  }
+  const updateType = DEPENDABOT_UPDATE_TYPES[highest];
+  if (updateType !== void 0 && ELIGIBLE_UPDATE_TYPES.has(updateType)) {
+    return result(true, `Dependabot ${updateType} \u2014 eligible`, "dependabot", updateType);
+  }
+  return result(false, `Dependabot ${updateType} \u2014 held for review`, "dependabot", updateType);
+}
+function classifyBotPr(facts) {
+  if (facts.isCrossRepository) {
+    return result(false, "head branch is in a fork \u2014 never a trusted bot PR");
+  }
+  if (facts.authorLogin === DEPENDABOT_LOGIN) {
+    return classifyDependabot(facts.commits);
+  }
+  if (facts.headRef.startsWith(RELEASE_PLEASE_BRANCH_PREFIX) || facts.labels.includes(RELEASE_PLEASE_PENDING_LABEL)) {
+    return result(true, "release-please release PR \u2014 eligible", "release-please");
+  }
+  return result(false, "not a recognized bot PR");
+}
+
+// src/cli/args.ts
+var REPO_PATTERN = /^([A-Za-z0-9-]+)\/([A-Za-z0-9._-]+)$/;
+var PR_PATTERN = /^[1-9][0-9]*$/;
+function usageError(message) {
+  return { command: "error", message };
+}
+function parseList(value) {
+  return value.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+}
+function parseReconcile(args) {
+  const values = {};
+  let armAutoMerge = false;
+  let skipCopilotReview = false;
+  let dryRun = false;
+  let json = false;
+  let tokenAdvisory = true;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? "";
+    switch (arg) {
+      case "--arm-auto-merge":
+        armAutoMerge = true;
+        break;
+      case "--skip-copilot-review":
+        skipCopilotReview = true;
+        break;
+      case "--dry-run":
+        dryRun = true;
+        break;
+      case "--json":
+        json = true;
+        break;
+      case "--no-token-advisory":
+        tokenAdvisory = false;
+        break;
+      case "--repo":
+      case "--pr":
+      case "--trusted-authors":
+      case "--hold-checks":
+      case "--ignore-checks": {
+        const value = args[index + 1];
+        if (value === void 0 || value.startsWith("--")) {
+          return usageError(`${arg} requires a value`);
+        }
+        index += 1;
+        values[arg] = value;
+        break;
+      }
+      default:
+        return usageError(`Unknown option: ${arg}`);
+    }
+  }
+  const repoArg = values["--repo"];
+  const prArg = values["--pr"];
+  const repoMatch = repoArg === void 0 ? null : REPO_PATTERN.exec(repoArg);
+  if (repoMatch?.[1] === void 0 || repoMatch[2] === void 0) {
+    return usageError("--repo <owner/repo> is required");
+  }
+  if (prArg === void 0 || !PR_PATTERN.test(prArg)) {
+    return usageError("--pr <number> is required and must be a positive integer");
+  }
+  const trustedAuthors = listOption(values["--trusted-authors"]);
+  if (trustedAuthors?.length === 0) {
+    return usageError("--trusted-authors needs at least one login");
+  }
+  const holdChecks = listOption(values["--hold-checks"]);
+  const ignoredChecks = listOption(values["--ignore-checks"]);
+  return {
+    command: "reconcile",
+    owner: repoMatch[1],
+    repo: repoMatch[2],
+    pr: Number(prArg),
+    policy: {
+      armAutoMerge,
+      skipCopilotReview,
+      ...trustedAuthors === void 0 ? {} : { trustedAuthors },
+      ...holdChecks === void 0 ? {} : { holdChecks },
+      ...ignoredChecks === void 0 ? {} : { ignoredChecks }
+    },
+    dryRun,
+    json,
+    tokenAdvisory
+  };
+}
+function listOption(value) {
+  return value === void 0 ? void 0 : parseList(value);
+}
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (command === void 0 || command === "help" || command === "--help" || command === "-h") {
+    return { command: "help" };
+  }
+  if (rest.includes("--help") || rest.includes("-h")) {
+    return { command: "help" };
+  }
+  if (command === "reconcile") {
+    return parseReconcile(rest);
+  }
+  return usageError(`Unknown command: ${command}`);
+}
+
+// src/cli/output.ts
+var SCHEMA_VERSION = 1;
+function toReconcileJson(target, result2) {
+  const { plan, botEligibility, lineage, skippedAutoMerge } = result2;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    repo: `${target.owner}/${target.repo}`,
+    pr: target.pr,
+    dryRun: target.dryRun,
+    state: plan.state,
+    addLabels: plan.addLabels,
+    removeLabels: plan.removeLabels,
+    autoMerge: plan.autoMerge,
+    botEligibility: {
+      eligible: botEligibility.eligible,
+      reason: botEligibility.reason,
+      prType: botEligibility.prType ?? null,
+      updateType: botEligibility.updateType ?? null
+    },
+    carryOver: lineage === void 0 ? null : { cleanAncestors: lineage.cleanAncestors, stoppedBecause: lineage.stoppedBecause },
+    // The CLI makes release actions unavailable only for a missing token.
+    autoMergeSkipped: skippedAutoMerge === void 0 ? null : { action: skippedAutoMerge, reason: "token-missing" }
+  };
+}
+function formatSummary(target, result2) {
+  const { plan, botEligibility } = result2;
+  const changes = [
+    ...plan.addLabels.map((label) => `+${label}`),
+    ...plan.removeLabels.map((label) => `-${label}`),
+    ...plan.autoMerge === "none" ? [] : [`auto-merge ${plan.autoMerge}`],
+    ...result2.skippedAutoMerge === void 0 ? [] : [`auto-merge ${result2.skippedAutoMerge} skipped (no release token)`]
+  ];
+  const prefix = target.dryRun ? "[dry-run] " : "";
+  const body = changes.length === 0 ? "no changes" : changes.join(", ");
+  return `${prefix}${target.owner}/${target.repo}#${target.pr} \u2192 ${plan.state}: ${body} (bot: ${botEligibility.reason})`;
+}
+
+// src/github/client.ts
+var GitHubApiError = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "GitHubApiError";
+    this.status = status;
+  }
+};
+function isApiStatus(error, status) {
+  return error instanceof GitHubApiError && error.status === status;
+}
+
+// src/facts.ts
+var REPO_PERMISSIONS = ["admin", "maintain", "none", "read", "triage", "write"];
+var ACTOR_TYPES = ["Bot", "User"];
+var REVIEW_STATES = [
+  "APPROVED",
+  "CHANGES_REQUESTED",
+  "COMMENTED",
+  "DISMISSED",
+  "PENDING"
+];
+var PR_STATUSES = ["closed", "merged", "open"];
+
+// src/github/rest-payloads.ts
+function toReviewState(state) {
+  return REVIEW_STATES.find((known) => known === state) ?? "DISMISSED";
+}
+function toActorType(type) {
+  return type === "User" ? "User" : "Bot";
+}
+function toReviewData(review) {
+  return {
+    id: review.id,
+    login: review.user?.login,
+    type: review.user === null ? "User" : toActorType(review.user.type),
+    commitSha: review.commit_id,
+    state: toReviewState(review.state),
+    body: review.body ?? "",
+    submittedAt: review.submitted_at ?? void 0
+  };
+}
+
+// src/github/http-client.ts
+var PAGE_SIZE = 100;
+var ENABLE_AUTO_MERGE = `mutation($id: ID!, $head: GitObjectID!) {
+  enablePullRequestAutoMerge(input: { pullRequestId: $id, mergeMethod: SQUASH, expectedHeadOid: $head }) { clientMutationId }
+}`;
+var MERGE_PULL_REQUEST = `mutation($id: ID!, $head: GitObjectID!) {
+  mergePullRequest(input: { pullRequestId: $id, mergeMethod: SQUASH, expectedHeadOid: $head }) { clientMutationId }
+}`;
+var DISABLE_AUTO_MERGE = `mutation($id: ID!) {
+  disablePullRequestAutoMerge(input: { pullRequestId: $id }) { clientMutationId }
+}`;
+function createHttpClient(options) {
+  let apiUrl = options.apiUrl ?? "https://api.github.com";
+  while (apiUrl.endsWith("/")) {
+    apiUrl = apiUrl.slice(0, -1);
+  }
+  const doFetch = options.fetch ?? fetch;
+  const repoPath = `/repos/${encodeURIComponent(options.owner)}/${encodeURIComponent(options.repo)}`;
+  async function request(method, path, body) {
+    const response = await doFetch(`${apiUrl}${path}`, {
+      method,
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${options.token}`,
+        "Content-Type": "application/json",
+        "User-Agent": "rmartz-pr-lifecycle",
+        "X-GitHub-Api-Version": "2022-11-28"
+      },
+      ...body === void 0 ? {} : { body: JSON.stringify(body) }
+    });
+    if (!response.ok) {
+      const detail = await response.text();
+      throw new GitHubApiError(
+        response.status,
+        `${method} ${path} \u2192 ${response.status}: ${detail}`
+      );
+    }
+    return response.status === 204 ? void 0 : response.json();
+  }
+  async function paginate(path) {
+    const items = [];
+    for (let page = 1; ; page += 1) {
+      const batch = await request("GET", `${path}?per_page=${PAGE_SIZE}&page=${page}`);
+      items.push(...batch);
+      if (batch.length < PAGE_SIZE) {
+        return items;
+      }
+    }
+  }
+  async function graphql(query, variables) {
+    const result2 = await request("POST", "/graphql", { query, variables });
+    if (result2.errors !== void 0 && result2.errors.length > 0) {
+      const messages = result2.errors.map((error) => error.message).join("; ");
+      throw new GitHubApiError(200, `GraphQL error: ${messages}`);
+    }
+  }
+  return {
+    async getPullRequest(pr) {
+      const pull = await request("GET", `${repoPath}/pulls/${pr}`);
+      return {
+        nodeId: pull.node_id,
+        state: pull.state,
+        merged: pull.merged,
+        draft: pull.draft === true,
+        title: pull.title,
+        headSha: pull.head.sha,
+        labels: pull.labels.map((label) => label.name),
+        autoMergeEnabled: pull.auto_merge !== null && pull.auto_merge !== void 0,
+        authorLogin: pull.user?.login,
+        headRef: pull.head.ref,
+        baseRef: pull.base.ref,
+        cloneUrl: pull.base.repo.clone_url,
+        // Compare repo ids, not names (names change on rename); a deleted head
+        // repo is treated as a fork, so it can never look like a trusted branch.
+        isCrossRepository: pull.head.repo?.id !== pull.base.repo.id,
+        mergeable: pull.mergeable ?? void 0,
+        mergeState: pull.mergeable_state
+      };
+    },
+    async getRequiredStatusChecks(branch) {
+      const rules = await paginate(
+        `${repoPath}/rules/branches/${encodeURIComponent(branch)}`
+      );
+      const contexts = rules.filter((rule) => rule.type === "required_status_checks").flatMap((rule) => rule.parameters?.required_status_checks ?? []).map((check) => check.context);
+      return [...new Set(contexts)];
+    },
+    async getBranchHeadSha(branch) {
+      const result2 = await request(
+        "GET",
+        `${repoPath}/branches/${encodeURIComponent(branch)}`
+      );
+      return result2.commit.sha;
+    },
+    async listCheckRuns(sha) {
+      const runs = [];
+      for (let page = 1; ; page += 1) {
+        const batch = await request(
+          "GET",
+          `${repoPath}/commits/${sha}/check-runs?per_page=${PAGE_SIZE}&page=${page}`
+        );
+        runs.push(...batch.check_runs);
+        if (batch.check_runs.length < PAGE_SIZE) {
+          break;
+        }
+      }
+      return runs.map((run) => ({
+        name: run.name,
+        status: run.status,
+        conclusion: run.conclusion,
+        completedAt: run.completed_at
+      }));
+    },
+    async getCommit(sha) {
+      const commit = await request("GET", `${repoPath}/git/commits/${sha}`);
+      return { treeSha: commit.tree.sha, parents: commit.parents.map((parent) => parent.sha) };
+    },
+    async compareCommits(base, head) {
+      const result2 = await request("GET", `${repoPath}/compare/${base}...${head}?per_page=1`);
+      return { status: result2.status, mergeBaseSha: result2.merge_base_commit.sha };
+    },
+    async listCommitStatuses(sha) {
+      const combined = await request("GET", `${repoPath}/commits/${sha}/status`);
+      return combined.statuses.map((status) => ({ context: status.context, state: status.state }));
+    },
+    async listCommits(pr) {
+      const commits = await paginate(`${repoPath}/pulls/${pr}/commits`);
+      return commits.map((commit) => ({
+        authorLogin: commit.author?.login,
+        message: commit.commit.message
+      }));
+    },
+    async listReviews(pr) {
+      const reviews = await paginate(`${repoPath}/pulls/${pr}/reviews`);
+      return reviews.map(toReviewData);
+    },
+    async getCollaboratorPermission(login) {
+      const result2 = await request(
+        "GET",
+        `${repoPath}/collaborators/${encodeURIComponent(login)}/permission`
+      );
+      return { permission: result2.permission, roleName: result2.role_name };
+    },
+    async listRepoLabels() {
+      const labels = await paginate(`${repoPath}/labels`);
+      return labels.map((label) => label.name);
+    },
+    async createLabel(label) {
+      await request("POST", `${repoPath}/labels`, label);
+    },
+    async addLabels(pr, names) {
+      await request("POST", `${repoPath}/issues/${pr}/labels`, { labels: names });
+    },
+    async removeLabel(pr, name) {
+      await request("DELETE", `${repoPath}/issues/${pr}/labels/${encodeURIComponent(name)}`);
+    },
+    async listIssueComments(pr) {
+      const comments = await paginate(`${repoPath}/issues/${pr}/comments`);
+      return comments.map((comment) => comment.body ?? "");
+    },
+    async createIssueComment(pr, body) {
+      await request("POST", `${repoPath}/issues/${pr}/comments`, { body });
+    },
+    async enableAutoMerge(pullRequestNodeId, expectedHeadOid) {
+      await graphql(ENABLE_AUTO_MERGE, { id: pullRequestNodeId, head: expectedHeadOid });
+    },
+    async mergePullRequest(pullRequestNodeId, expectedHeadOid) {
+      await graphql(MERGE_PULL_REQUEST, { id: pullRequestNodeId, head: expectedHeadOid });
+    },
+    async disableAutoMerge(pullRequestNodeId) {
+      await graphql(DISABLE_AUTO_MERGE, { id: pullRequestNodeId });
+    }
+  };
+}
+
+// src/verdict.ts
+var VERDICTS = ["approved", "changes-requested", "escalation-needed"];
+var TRUSTED_PERMISSIONS = /* @__PURE__ */ new Set([
+  "admin",
+  "maintain",
+  "write"
+]);
+var SKILL_META_OPENING = /<!--\s*skill-meta:/;
+var COMMENT_CLOSE = "-->";
+function isVerdict(value) {
+  return VERDICTS.some((verdict) => verdict === value);
+}
+function readSkillMeta(body) {
+  const opening = SKILL_META_OPENING.exec(body);
+  if (opening === null) {
+    return void 0;
+  }
+  const payloadStart = opening.index + opening[0].length;
+  const payloadEnd = body.indexOf(COMMENT_CLOSE, payloadStart);
+  if (payloadEnd === -1) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(body.slice(payloadStart, payloadEnd).trim());
+    return typeof parsed === "object" && parsed !== null ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function parseVerdict(review) {
+  if (review.state === "DISMISSED" || review.state === "PENDING") {
+    return void 0;
+  }
+  const meta = readSkillMeta(review.body);
+  if (meta?.skill === "review") {
+    if (!isVerdict(meta.outcome)) {
+      return void 0;
+    }
+    return {
+      verdict: meta.outcome,
+      markerHead: typeof meta.pr_head === "string" ? meta.pr_head : void 0
+    };
+  }
+  switch (review.state) {
+    case "APPROVED":
+      return { verdict: "approved", markerHead: void 0 };
+    case "CHANGES_REQUESTED":
+      return { verdict: "changes-requested", markerHead: void 0 };
+    case "COMMENTED":
+      return void 0;
+  }
+}
+function isTrustedAuthor(author, policy) {
+  if (author.type !== "User" || !TRUSTED_PERMISSIONS.has(author.permission)) {
+    return false;
+  }
+  if (policy.trustedAuthors === void 0) {
+    return true;
+  }
+  const login = author.login.toLowerCase();
+  return policy.trustedAuthors.some((trusted) => trusted.toLowerCase() === login);
+}
+function compareSubmission(a, b) {
+  return Date.parse(a.submittedAt) - Date.parse(b.submittedAt) || a.id - b.id;
+}
+function countingCommits(facts) {
+  return /* @__PURE__ */ new Set([facts.headSha, ...facts.cleanAncestors]);
+}
+function currentVerdict(facts, policy) {
+  const countingShas = countingCommits(facts);
+  let latest;
+  for (const review of facts.reviews) {
+    const parsed = parseVerdict(review);
+    const counts = parsed !== void 0 && isTrustedAuthor(review.author, policy) && countingShas.has(review.commitSha) && // The marker, when present, must name the same commit the review is bound to.
+    (parsed.markerHead === void 0 || parsed.markerHead === review.commitSha);
+    if (counts && (latest === void 0 || compareSubmission(review, latest.review) > 0)) {
+      latest = { review, verdict: parsed.verdict };
+    }
+  }
+  return latest?.verdict;
+}
+
+// src/state.ts
+var LIFECYCLE_STATES = [
+  "approved",
+  "awaiting-ci",
+  "awaiting-copilot",
+  "blocked-base-red",
+  "changes-requested",
+  "ci-failing",
+  "closed",
+  "draft",
+  "escalation-needed",
+  "fix-required",
+  "review-requested"
+];
+var COPILOT_REVIEWER_LOGIN = "copilot-pull-request-reviewer[bot]";
+var WIP_PATTERN = /\[wip\]/i;
+function computeState(facts, policy) {
+  if (facts.status !== "open") {
+    return "closed";
+  }
+  if (facts.isDraft || WIP_PATTERN.test(facts.title)) {
+    return "draft";
+  }
+  if (facts.mergeable === false) {
+    return "fix-required";
+  }
+  if (facts.ciStatus === "failing") {
+    return facts.baseCiFailing ? "blocked-base-red" : "ci-failing";
+  }
+  const verdict = currentVerdict(facts, policy);
+  if (verdict !== void 0) {
+    return verdict;
+  }
+  if (facts.botEligible) {
+    return "approved";
+  }
+  if (facts.ciStatus === "pending") {
+    return "awaiting-ci";
+  }
+  if (policy.skipCopilotReview === true) {
+    return "review-requested";
+  }
+  const reviewedCommits = countingCommits(facts);
+  const copilotReviewedHead = facts.reviews.some(
+    (review) => review.author.login === COPILOT_REVIEWER_LOGIN && reviewedCommits.has(review.commitSha)
+  );
+  return copilotReviewedHead ? "review-requested" : "awaiting-copilot";
+}
+
+// src/plan.ts
+var LIFECYCLE_LABELS = [
+  "approved",
+  "changes requested",
+  "escalation needed",
+  "fix required",
+  "ci failing",
+  "review requested"
+];
+var AUTO_MERGE_LABEL = "auto-merge enabled";
+function lifecycleLabels(state) {
+  switch (state) {
+    case "approved":
+      return ["approved"];
+    case "changes-requested":
+      return ["changes requested"];
+    case "escalation-needed":
+      return ["escalation needed"];
+    case "fix-required":
+      return ["fix required"];
+    case "ci-failing":
+      return ["fix required", "ci failing"];
+    case "review-requested":
+      return ["review requested"];
+    case "awaiting-ci":
+    case "awaiting-copilot":
+    case "blocked-base-red":
+    case "closed":
+    case "draft":
+      return [];
+  }
+}
+function planReconcile(facts, policy) {
+  const state = computeState(facts, policy);
+  if (state === "closed") {
+    return { state, addLabels: [], removeLabels: [], autoMerge: "none" };
+  }
+  const arming = policy.armAutoMerge === true;
+  const shouldArm = arming && state === "approved";
+  let autoMerge = "none";
+  if (arming && shouldArm !== facts.autoMergeEnabled) {
+    if (!shouldArm) {
+      autoMerge = "disarm";
+    } else {
+      autoMerge = facts.immediatelyMergeable ? "merge" : "arm";
+    }
+  }
+  const owned = [...LIFECYCLE_LABELS];
+  const desired = new Set(lifecycleLabels(state));
+  if (arming) {
+    owned.push(AUTO_MERGE_LABEL);
+    if (shouldArm && autoMerge !== "merge") {
+      desired.add(AUTO_MERGE_LABEL);
+    }
+  }
+  const present = new Set(facts.labels);
+  return {
+    state,
+    addLabels: [...desired].filter((name) => !present.has(name)),
+    removeLabels: owned.filter((name) => present.has(name) && !desired.has(name)),
+    autoMerge
+  };
+}
+function withoutArming(plan) {
+  if (plan.autoMerge !== "arm" && plan.autoMerge !== "merge") {
+    return plan;
+  }
+  return {
+    ...plan,
+    addLabels: plan.addLabels.filter((name) => name !== AUTO_MERGE_LABEL),
+    autoMerge: "none"
+  };
+}
+
+// src/github/label-roster.ts
+var OWNED_LABEL_DEFINITIONS = {
+  approved: {
+    name: "approved",
+    color: "2DA44E",
+    description: "Code review passed \u2014 safe to merge pending UAT."
+  },
+  "auto-merge enabled": {
+    name: AUTO_MERGE_LABEL,
+    color: "1F883D",
+    description: "Native auto-merge is armed on this PR; it merges once required checks pass."
+  },
+  "changes requested": {
+    name: "changes requested",
+    color: "DA3633",
+    description: "Fix-review pass needed \u2014 reviewer flagged addressable issues."
+  },
+  "escalation needed": {
+    name: "escalation needed",
+    color: "DB2777",
+    description: "Needs author input or judgment \u2014 not addressable by automated fix-review."
+  },
+  // Placeholder colors until the fleet roster assigns them (rmartz/dotfiles#1573).
+  "ci failing": {
+    name: "ci failing",
+    color: "B60205",
+    description: "The PR's required CI (excluding gate checks) is failing on its head."
+  },
+  "fix required": {
+    name: "fix required",
+    color: "D93F0B",
+    description: "A statically detected problem (merge conflict or failing CI) needs a fix."
+  },
+  "review requested": {
+    name: "review requested",
+    color: "E3B341",
+    description: "Review pass needed on the current head."
+  }
+};
+function labelDefinition(name) {
+  const known = Object.values(OWNED_LABEL_DEFINITIONS).find((label) => label.name === name);
+  return known ?? { name, color: "EDEDED", description: "" };
+}
+
+// src/github/execute.ts
+function isCleanStatusError(error) {
+  return error instanceof GitHubApiError && /clean status/i.test(error.message);
+}
+async function armOrMerge(release, target) {
+  try {
+    await release.enableAutoMerge(target.nodeId, target.headSha);
+  } catch (error) {
+    if (!isCleanStatusError(error)) {
+      throw error;
+    }
+    await release.mergePullRequest(target.nodeId, target.headSha);
+  }
+}
+async function ensureLabelsExist(client, names) {
+  const existing = new Set(await client.listRepoLabels());
+  for (const name of names) {
+    if (existing.has(name)) {
+      continue;
+    }
+    try {
+      await client.createLabel(labelDefinition(name));
+    } catch (error) {
+      if (!isApiStatus(error, 422)) {
+        throw error;
+      }
+    }
+  }
+}
+async function executePlan(client, target, plan, release = client) {
+  if (plan.autoMerge === "disarm") {
+    await client.disableAutoMerge(target.nodeId);
+  }
+  for (const name of plan.removeLabels) {
+    try {
+      await client.removeLabel(target.pr, name);
+    } catch (error) {
+      if (!isApiStatus(error, 404)) {
+        throw error;
+      }
+    }
+  }
+  if (plan.addLabels.length > 0) {
+    await ensureLabelsExist(client, plan.addLabels);
+    await client.addLabels(target.pr, plan.addLabels);
+  }
+  if (plan.autoMerge === "arm") {
+    await armOrMerge(release, target);
+  }
+  if (plan.autoMerge === "merge") {
+    await release.mergePullRequest(target.nodeId, target.headSha);
+  }
+}
+
+// src/lineage/git.ts
+import { execFile } from "child_process";
+var TIMEOUT_MS = 12e4;
+var MAX_BUFFER = 16 * 1024 * 1024;
+function createGitRunner() {
+  return {
+    run(args, env = {}) {
+      return new Promise((resolve, reject) => {
+        execFile(
+          "git",
+          [...args],
+          {
+            timeout: TIMEOUT_MS,
+            maxBuffer: MAX_BUFFER,
+            // Never prompt for credentials; fail instead.
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0", ...env }
+          },
+          (error, stdout, stderr) => {
+            if (error === null) {
+              resolve({ code: 0, stdout, stderr });
+              return;
+            }
+            if (typeof error.code === "number" && !error.killed) {
+              resolve({ code: error.code, stdout, stderr });
+              return;
+            }
+            reject(new Error(`git ${args[0] ?? ""} failed: ${error.message}`, { cause: error }));
+          }
+        );
+      });
+    }
+  };
+}
+function parseGitVersion(output) {
+  const match = /git version (\d+)\.(\d+)/.exec(output);
+  if (match?.[1] === void 0 || match[2] === void 0) {
+    return void 0;
+  }
+  return [Number(match[1]), Number(match[2])];
+}
+
+// src/lineage/verify.ts
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+var MIN_GIT = [2, 40];
+var OBJECT_ID = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+function isStepSafe(step) {
+  return [step.mergeBase, step.first, step.second, step.tree].every((id) => OBJECT_ID.test(id));
+}
+function authEnv(source) {
+  if (source.token === void 0) {
+    return {};
+  }
+  const basic = Buffer.from(`x-access-token:${source.token}`).toString("base64");
+  return {
+    GIT_CONFIG_COUNT: "1",
+    GIT_CONFIG_KEY_0: "http.extraHeader",
+    GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${basic}`
+  };
+}
+async function createMergeVerifier(git, source) {
+  const version = parseGitVersion((await git.run(["version"])).stdout);
+  if (version === void 0 || version[0] < MIN_GIT[0] || version[0] === MIN_GIT[0] && version[1] < MIN_GIT[1]) {
+    return void 0;
+  }
+  if (!/^(https|file):\/\//.test(source.url)) {
+    return void 0;
+  }
+  const gitDir = await mkdtemp(join(tmpdir(), "pr-lifecycle-lineage-"));
+  const init = await git.run(["init", "--bare", "--quiet", gitDir]);
+  if (init.code !== 0) {
+    await rm(gitDir, { recursive: true, force: true });
+    return void 0;
+  }
+  const env = authEnv(source);
+  return {
+    async verify(step) {
+      if (!isStepSafe(step)) {
+        return false;
+      }
+      const fetched = await git.run(
+        [
+          "--git-dir",
+          gitDir,
+          "fetch",
+          "--quiet",
+          "--no-tags",
+          "--depth=1",
+          "--end-of-options",
+          source.url,
+          step.mergeBase,
+          step.first,
+          step.second
+        ],
+        env
+      );
+      if (fetched.code !== 0) {
+        return false;
+      }
+      const merged = await git.run([
+        "--git-dir",
+        gitDir,
+        "merge-tree",
+        "--write-tree",
+        `--merge-base=${step.mergeBase}`,
+        step.first,
+        step.second
+      ]);
+      return merged.code === 0 && merged.stdout.split("\n")[0]?.trim() === step.tree;
+    },
+    async dispose() {
+      await rm(gitDir, { recursive: true, force: true });
+    }
+  };
+}
+
+// src/github/lineage-facts.ts
+var MAX_CHAIN_STEPS = 20;
+function reviewedAncestors(input) {
+  return new Set(
+    input.reviews.filter((review) => review.commitSha !== input.headSha).filter(
+      (review) => review.login === COPILOT_REVIEWER_LOGIN || review.state === "APPROVED" || review.state === "CHANGES_REQUESTED" || review.body.includes("skill-meta")
+    ).map((review) => review.commitSha)
+  );
+}
+async function onBaseBranch(client, commit, baseHeadSha) {
+  const { status } = await client.compareCommits(commit, baseHeadSha);
+  return status === "identical" || status === "ahead";
+}
+async function walk(client, git, input, wanted) {
+  const verifier = await createMergeVerifier(git, input.source);
+  if (verifier === void 0) {
+    return { cleanAncestors: [], stoppedBecause: "git unavailable or older than 2.40" };
+  }
+  const cleanAncestors = [];
+  try {
+    let current = input.headSha;
+    for (let step = 0; step < MAX_CHAIN_STEPS; step += 1) {
+      const commit = await client.getCommit(current);
+      const [first, second, ...extra] = commit.parents;
+      if (first === void 0 || second === void 0 || extra.length > 0) {
+        return { cleanAncestors, stoppedBecause: `${current} is not a two-parent merge` };
+      }
+      if (!await onBaseBranch(client, second, input.baseHeadSha)) {
+        return { cleanAncestors, stoppedBecause: `${current} merges a commit not on the base` };
+      }
+      const { mergeBaseSha } = await client.compareCommits(first, second);
+      const clean = await verifier.verify({
+        mergeBase: mergeBaseSha,
+        first,
+        second,
+        tree: commit.treeSha
+      });
+      if (!clean) {
+        return { cleanAncestors, stoppedBecause: `${current} is not the clean automatic merge` };
+      }
+      cleanAncestors.push(first);
+      current = first;
+      if ([...wanted].every((sha) => cleanAncestors.includes(sha))) {
+        return { cleanAncestors, stoppedBecause: "every reviewed ancestor reached" };
+      }
+    }
+    return { cleanAncestors, stoppedBecause: `chain longer than ${MAX_CHAIN_STEPS} steps` };
+  } finally {
+    await verifier.dispose();
+  }
+}
+async function gatherLineage(client, git, input) {
+  const wanted = reviewedAncestors(input);
+  if (wanted.size === 0) {
+    return { cleanAncestors: [], stoppedBecause: "no reviews on earlier commits" };
+  }
+  try {
+    return await walk(client, git, input, wanted);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { cleanAncestors: [], stoppedBecause: `verification failed: ${message}` };
+  }
+}
+
+// src/ci.ts
+var DEFAULT_HOLD_CHECKS = ["pr-policy"];
+var DEFAULT_IGNORED_CHECKS = ["merge-safety"];
+var PASSING_CONCLUSIONS = /* @__PURE__ */ new Set(["neutral", "skipped", "success"]);
+var FAILING_CONCLUSIONS = /* @__PURE__ */ new Set([
+  "action_required",
+  "cancelled",
+  "failure",
+  "startup_failure",
+  "timed_out"
+]);
+function checkRunOutcome(run) {
+  const concluded = run.status === "completed" || run.completedAt !== null;
+  if (!concluded || run.conclusion === null) {
+    return "running";
+  }
+  if (PASSING_CONCLUSIONS.has(run.conclusion)) {
+    return "passed";
+  }
+  return FAILING_CONCLUSIONS.has(run.conclusion) ? "failed" : "running";
+}
+function commitStatusOutcome(state) {
+  if (state === "success") {
+    return "passed";
+  }
+  return state === "failure" || state === "error" ? "failed" : "running";
+}
+function computeCiStatus(results, requiredChecks2, policy = {}) {
+  const holds = new Set(policy.holdChecks ?? DEFAULT_HOLD_CHECKS);
+  const ignored = new Set(policy.ignoredChecks ?? DEFAULT_IGNORED_CHECKS);
+  let pending = false;
+  for (const name of new Set(requiredChecks2)) {
+    if (ignored.has(name)) {
+      continue;
+    }
+    const outcomes = results.filter((result2) => result2.name === name).map((r) => r.outcome);
+    if (outcomes.includes("failed")) {
+      return "failing";
+    }
+    const reported = outcomes.length > 0;
+    const running = outcomes.includes("running");
+    if (!holds.has(name) && (!reported || running)) {
+      pending = true;
+    }
+  }
+  return pending ? "pending" : "passing";
+}
+
+// src/github/ci-facts.ts
+var NO_CI = { ciStatus: "passing", baseCiFailing: false };
+var PLAN_LIMITATION = /upgrade to github pro|make this repository public/i;
+async function requiredChecks(client, branch) {
+  try {
+    return await client.getRequiredStatusChecks(branch);
+  } catch (error) {
+    if (error instanceof GitHubApiError && error.status === 403 && PLAN_LIMITATION.test(error.message)) {
+      return [];
+    }
+    throw error;
+  }
+}
+async function statusAt(client, sha, required, policy) {
+  const [runs, statuses] = await Promise.all([
+    client.listCheckRuns(sha),
+    client.listCommitStatuses(sha)
+  ]);
+  const results = [
+    ...runs.map((run) => ({ name: run.name, outcome: checkRunOutcome(run) })),
+    ...statuses.map((status) => ({
+      name: status.context,
+      outcome: commitStatusOutcome(status.state)
+    }))
+  ];
+  return computeCiStatus(results, required, policy);
+}
+async function gatherCiFacts(client, pull, policy) {
+  if (pull.state !== "open") {
+    return NO_CI;
+  }
+  const required = await requiredChecks(client, pull.baseRef);
+  if (required.length === 0) {
+    return NO_CI;
+  }
+  const ciStatus = await statusAt(client, pull.headSha, required, policy);
+  if (ciStatus !== "failing") {
+    return { ciStatus, baseCiFailing: false };
+  }
+  const baseSha = await client.getBranchHeadSha(pull.baseRef);
+  const baseStatus = await statusAt(client, baseSha, required, policy);
+  return { ciStatus, baseCiFailing: baseStatus === "failing" };
+}
+
+// src/github/gather.ts
+async function gatherBotEligibility(client, pr, pull) {
+  const needsCommits = pull.authorLogin === DEPENDABOT_LOGIN && !pull.isCrossRepository;
+  return classifyBotPr({
+    authorLogin: pull.authorLogin ?? "ghost",
+    headRef: pull.headRef,
+    isCrossRepository: pull.isCrossRepository,
+    labels: pull.labels,
+    commits: needsCommits ? await client.listCommits(pr) : []
+  });
+}
+function isRepoPermission(value) {
+  return REPO_PERMISSIONS.some((permission) => permission === value);
+}
+async function lookupPermission(client, login) {
+  try {
+    const { permission, roleName } = await client.getCollaboratorPermission(login);
+    if (isRepoPermission(roleName)) {
+      return roleName;
+    }
+    return isRepoPermission(permission) ? permission : "none";
+  } catch (error) {
+    if (isApiStatus(error, 404)) {
+      return "none";
+    }
+    throw error;
+  }
+}
+async function lookupPermissions(client, reviews) {
+  const logins = /* @__PURE__ */ new Set();
+  for (const review of reviews) {
+    if (review.login !== void 0 && review.type === "User") {
+      logins.add(review.login);
+    }
+  }
+  const entries = await Promise.all(
+    [...logins].map(async (login) => [login, await lookupPermission(client, login)])
+  );
+  return new Map(entries);
+}
+function toReviewFact(review, permissions) {
+  const permission = review.login === void 0 ? void 0 : permissions.get(review.login);
+  return {
+    id: review.id,
+    author: {
+      login: review.login ?? "ghost",
+      type: review.type,
+      permission: permission ?? "none"
+    },
+    commitSha: review.commitSha,
+    state: review.state,
+    body: review.body,
+    submittedAt: review.submittedAt ?? ""
+  };
+}
+async function gatherLineageFor(client, pull, reviews, options) {
+  if (options.lineage === void 0 || pull.state !== "open") {
+    return void 0;
+  }
+  try {
+    const baseHeadSha = await client.getBranchHeadSha(pull.baseRef);
+    return await gatherLineage(client, options.lineage.git, {
+      headSha: pull.headSha,
+      baseHeadSha,
+      source: {
+        url: pull.cloneUrl,
+        ...options.lineage.token === void 0 ? {} : { token: options.lineage.token }
+      },
+      reviews
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { cleanAncestors: [], stoppedBecause: `verification failed: ${message}` };
+  }
+}
+var IMMEDIATE_MERGE_STATES = /* @__PURE__ */ new Set(["clean", "has_hooks", "unstable"]);
+async function gatherFacts(client, pr, policy = {}, options = {}) {
+  const [pull, reviews] = await Promise.all([client.getPullRequest(pr), client.listReviews(pr)]);
+  const [permissions, botEligibility, ci, lineage] = await Promise.all([
+    lookupPermissions(client, reviews),
+    gatherBotEligibility(client, pr, pull),
+    gatherCiFacts(client, pull, policy),
+    gatherLineageFor(client, pull, reviews, options)
+  ]);
+  return {
+    nodeId: pull.nodeId,
+    botEligibility,
+    lineage,
+    facts: {
+      status: pull.merged ? "merged" : pull.state,
+      isDraft: pull.draft,
+      title: pull.title,
+      headSha: pull.headSha,
+      labels: pull.labels,
+      autoMergeEnabled: pull.autoMergeEnabled,
+      botEligible: botEligibility.eligible,
+      mergeable: pull.mergeable,
+      immediatelyMergeable: IMMEDIATE_MERGE_STATES.has(pull.mergeState ?? ""),
+      ciStatus: ci.ciStatus,
+      baseCiFailing: ci.baseCiFailing,
+      cleanAncestors: lineage?.cleanAncestors ?? [],
+      reviews: reviews.map((review) => toReviewFact(review, permissions))
+    }
+  };
+}
+
+// src/github/reconcile.ts
+var REFUSE_RELEASE = {
+  enableAutoMerge: () => Promise.reject(new Error("arming needs a release token")),
+  mergePullRequest: () => Promise.reject(new Error("merging needs a release token"))
+};
+async function reconcilePullRequest(client, pr, policy, options = {}) {
+  const { facts, nodeId, botEligibility, lineage } = await gatherFacts(client, pr, policy, options);
+  const planned = planReconcile(facts, policy);
+  const unavailable = options.release === "unavailable";
+  const plan = unavailable ? withoutArming(planned) : planned;
+  if (options.dryRun !== true) {
+    const release = options.release === "unavailable" ? REFUSE_RELEASE : options.release ?? client;
+    await executePlan(client, { pr, nodeId, headSha: facts.headSha }, plan, release);
+  }
+  const wanted = planned.autoMerge;
+  const skippedAutoMerge = unavailable && (wanted === "arm" || wanted === "merge") ? wanted : void 0;
+  return { plan, botEligibility, lineage, skippedAutoMerge };
+}
+
+// src/github/token-advisory.ts
+var TOKEN_ADVISORY_MARKER = "<!-- pr-lifecycle:token-missing -->";
+var RELEASE_TOKEN_DOCS_URL = "https://github.com/rmartz/pr-lifecycle/blob/main/docs/cli.md#release-token";
+function buildTokenAdvisoryBody(skipped) {
+  const action = skipped === "merge" ? "merged" : "armed for auto-merge";
+  return [
+    TOKEN_ADVISORY_MARKER,
+    "## PR lifecycle: auto-merge skipped",
+    `This PR is approved and would have been **${action}**, but no release token is configured (the action's \`token\` input, or \`PR_LIFECYCLE_TOKEN\` for the CLI).`,
+    "A merge made with `GITHUB_TOKEN` doesn't trigger `on: push` workflows such as releases, so the lifecycle doesn't fall back to it. Labels are still kept up to date; merge this PR by hand, or add the token and re-run.",
+    `To fix it, store a fine-grained PAT with **Contents** and **Pull requests** read/write on this repository as the \`PR_LIFECYCLE_TOKEN\` Actions secret, **and** as a Dependabot secret of the same name if bot PRs are auto-merged (Dependabot-triggered runs only see Dependabot secrets). See ${RELEASE_TOKEN_DOCS_URL}.`,
+    "<sub>pr-lifecycle</sub>"
+  ].join("\n\n");
+}
+async function postTokenAdvisory(client, pr, skipped) {
+  const comments = await client.listIssueComments(pr);
+  if (comments.some((body) => body.includes(TOKEN_ADVISORY_MARKER))) {
+    return false;
+  }
+  await client.createIssueComment(pr, buildTokenAdvisoryBody(skipped));
+  return true;
+}
+
+// src/cli.ts
+var USAGE = `Usage: ai-pr-lifecycle <command> [options]
+
+Commands:
+  reconcile   Recompute a PR's lifecycle state and converge its labels
+  help        Show this message
+
+reconcile options:
+  --repo <owner/repo>       Repository (required)
+  --pr <number>             Pull request number (required)
+  --arm-auto-merge          Arm/disarm native auto-merge from the state
+  --trusted-authors <a,b>   Only these logins (with write access) may cast verdicts
+  --skip-copilot-review     Don't wait for a Copilot review
+  --hold-checks <a,b>       Required checks whose pending is a hold (default: pr-policy)
+  --ignore-checks <a,b>     Required checks CI never counts (default: merge-safety)
+  --dry-run                 Compute the plan without writing anything
+  --json                    Print one JSON object (schemaVersion 1) on stdout
+  --no-token-advisory       Don't comment on the PR when arming lacks a release token
+
+Environment:
+  GITHUB_TOKEN              Token for reads and writes (required)
+  PR_LIFECYCLE_TOKEN
+                            Real-actor token for arming and merging; without it,
+                            --arm-auto-merge keeps labels but skips arm/merge
+  GITHUB_API_URL            API base URL (GitHub Enterprise Server)`;
+async function runCli(argv, io, deps) {
+  const args = parseArgs(argv);
+  switch (args.command) {
+    case "help":
+      io.stdout(USAGE);
+      return 0;
+    case "error":
+      io.stderr(args.message);
+      io.stderr(USAGE);
+      return 2;
+    case "reconcile":
+      break;
+  }
+  const token = deps.env["GITHUB_TOKEN"];
+  if (token === void 0 || token === "") {
+    io.stderr("GITHUB_TOKEN is not set");
+    return 2;
+  }
+  const createClient = deps.createClient ?? createHttpClient;
+  const apiUrl = deps.env["GITHUB_API_URL"];
+  const clientFor = (clientToken) => createClient({
+    token: clientToken,
+    owner: args.owner,
+    repo: args.repo,
+    ...apiUrl === void 0 || apiUrl === "" ? {} : { apiUrl }
+  });
+  const client = clientFor(token);
+  const releaseToken = deps.env["PR_LIFECYCLE_TOKEN"];
+  const hasReleaseToken = releaseToken !== void 0 && releaseToken !== "";
+  const target = { owner: args.owner, repo: args.repo, pr: args.pr, dryRun: args.dryRun };
+  try {
+    const result2 = await reconcilePullRequest(client, args.pr, args.policy, {
+      dryRun: args.dryRun,
+      lineage: { git: deps.git ?? createGitRunner(), token },
+      // Only arming and merging use the release token (never reads). Without one
+      // they are skipped, not done with GITHUB_TOKEN; see docs/cli.md.
+      release: hasReleaseToken ? clientFor(releaseToken) : "unavailable"
+    });
+    if (result2.skippedAutoMerge !== void 0) {
+      io.stderr(
+        `warning: ${args.owner}/${args.repo}#${args.pr} is approved, but auto-merge ${result2.skippedAutoMerge} was skipped: PR_LIFECYCLE_TOKEN is not set`
+      );
+      if (args.tokenAdvisory && !args.dryRun) {
+        await adviseMissingToken(client, args.pr, result2.skippedAutoMerge, io);
+      }
+    }
+    if (args.json) {
+      io.stdout(JSON.stringify(toReconcileJson(target, result2)));
+    } else {
+      io.stdout(formatSummary(target, result2));
+    }
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    io.stderr(`reconcile failed for ${args.owner}/${args.repo}#${args.pr}: ${message}`);
+    return 1;
+  }
+}
+async function adviseMissingToken(client, pr, skipped, io) {
+  try {
+    await postTokenAdvisory(client, pr, skipped);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    io.stderr(`warning: could not post the missing-token advisory: ${message}`);
+  }
+}
+
+export {
+  DEPENDABOT_LOGIN,
+  RELEASE_PLEASE_BRANCH_PREFIX,
+  RELEASE_PLEASE_PENDING_LABEL,
+  DEPENDABOT_UPDATE_TYPES,
+  parseDependabotUpdateType,
+  classifyBotPr,
+  parseArgs,
+  SCHEMA_VERSION,
+  toReconcileJson,
+  formatSummary,
+  GitHubApiError,
+  isApiStatus,
+  REPO_PERMISSIONS,
+  ACTOR_TYPES,
+  REVIEW_STATES,
+  PR_STATUSES,
+  createHttpClient,
+  VERDICTS,
+  parseVerdict,
+  isTrustedAuthor,
+  currentVerdict,
+  LIFECYCLE_STATES,
+  COPILOT_REVIEWER_LOGIN,
+  computeState,
+  LIFECYCLE_LABELS,
+  AUTO_MERGE_LABEL,
+  planReconcile,
+  withoutArming,
+  OWNED_LABEL_DEFINITIONS,
+  executePlan,
+  createGitRunner,
+  parseGitVersion,
+  createMergeVerifier,
+  MAX_CHAIN_STEPS,
+  gatherLineage,
+  gatherFacts,
+  reconcilePullRequest,
+  TOKEN_ADVISORY_MARKER,
+  RELEASE_TOKEN_DOCS_URL,
+  buildTokenAdvisoryBody,
+  postTokenAdvisory,
+  USAGE,
+  runCli
+};