@atlassian-dc-mcp/bitbucket 0.34.0 → 0.36.0

package/src/__tests__/{merge-gateway.test.ts → repo-gateway.test.ts}

@@ -1,11 +1,22 @@
 import {
-  assertRepoMergeAllowed,
+  DECLINE_POLICY,
+  MERGE_POLICY,
+  assertRepoOperationAllowed,
   assertTargetRefMergeAllowed,
+  resolveDeclineGateway,
   resolveMergeGateway,
-} from '../merge-gateway.js';
+  type RepoGateway,
+} from '../repo-gateway.js';
 
 const silentWarn = () => undefined;
 
+const disabled = (policy = MERGE_POLICY): RepoGateway => ({
+  enabled: false,
+  repos: [],
+  targetRefs: [],
+  policy,
+});
+
 describe('resolveMergeGateway', () => {
   it('is disabled by default', () => {
     const gateway = resolveMergeGateway({ env: {}, warn: silentWarn });
@@ -63,40 +74,101 @@ describe('resolveMergeGateway', () => {
   });
 });
 
-describe('assertRepoMergeAllowed', () => {
+describe('resolveDeclineGateway', () => {
+  it('is disabled by default', () => {
+    const gateway = resolveDeclineGateway({ env: {}, warn: silentWarn });
+    expect(gateway.enabled).toBe(false);
+  });
+
+  it('reads its own environment variables rather than the merge ones', () => {
+    const gateway = resolveDeclineGateway({
+      env: {
+        BITBUCKET_DECLINE_ENABLED: 'true',
+        BITBUCKET_DECLINE_ALLOWED_REPOS: 'proj/Demo, OTHER/*',
+      },
+      warn: silentWarn,
+    });
+    expect(gateway.enabled).toBe(true);
+    expect(gateway.repos).toEqual(['PROJ/demo', 'OTHER/*']);
+  });
+
+  it('stays disabled when only merging was enabled', () => {
+    const gateway = resolveDeclineGateway({
+      env: { BITBUCKET_MERGE_ENABLED: 'true', BITBUCKET_MERGE_ALLOWED_REPOS: 'PROJ/demo' },
+      warn: silentWarn,
+    });
+    expect(gateway.enabled).toBe(false);
+  });
+
+  it('never restricts target refs, even when the merge target refs are configured', () => {
+    const gateway = resolveDeclineGateway({
+      env: {
+        BITBUCKET_DECLINE_ENABLED: 'true',
+        BITBUCKET_DECLINE_ALLOWED_REPOS: 'PROJ/demo',
+        BITBUCKET_MERGE_ALLOWED_TARGET_REFS: 'develop',
+      },
+      warn: silentWarn,
+    });
+    expect(gateway.targetRefs).toEqual([]);
+  });
+
+  it('names the decline environment variables when enabled with no valid repository', () => {
+    const warnings: string[] = [];
+    resolveDeclineGateway({ env: { BITBUCKET_DECLINE_ENABLED: 'true' }, warn: message => warnings.push(message) });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('BITBUCKET_DECLINE_ALLOWED_REPOS');
+  });
+});
+
+describe('assertRepoOperationAllowed', () => {
   const gateway = resolveMergeGateway({
     env: { BITBUCKET_MERGE_ENABLED: 'true', BITBUCKET_MERGE_ALLOWED_REPOS: 'PROJ/demo, OTHER/*' },
     warn: silentWarn,
   });
 
-  it('refuses everything when merging is disabled', () => {
-    expect(() => assertRepoMergeAllowed({ enabled: false, repos: [], targetRefs: [] }, 'PROJ', 'demo'))
+  it('refuses everything when the operation is disabled', () => {
+    expect(() => assertRepoOperationAllowed(disabled(), 'PROJ', 'demo'))
       .toThrow(/disabled on this server/);
   });
 
+  it('names the environment variables of its own operation when disabled', () => {
+    expect(() => assertRepoOperationAllowed(disabled(DECLINE_POLICY), 'PROJ', 'demo'))
+      .toThrow(/Declining pull requests is disabled on this server\. Enable it with BITBUCKET_DECLINE_ENABLED and list the allowed repositories in BITBUCKET_DECLINE_ALLOWED_REPOS\./);
+  });
+
   it('allows an exact repository regardless of the casing used by the caller', () => {
-    expect(() => assertRepoMergeAllowed(gateway, 'proj', 'DEMO')).not.toThrow();
+    expect(() => assertRepoOperationAllowed(gateway, 'proj', 'DEMO')).not.toThrow();
   });
 
   it('allows any repository in a wildcard project', () => {
-    expect(() => assertRepoMergeAllowed(gateway, 'OTHER', 'anything')).not.toThrow();
+    expect(() => assertRepoOperationAllowed(gateway, 'OTHER', 'anything')).not.toThrow();
   });
 
   it('refuses a repository outside the allowed list', () => {
-    expect(() => assertRepoMergeAllowed(gateway, 'PROJ', 'other-repo')).toThrow(/not allowed in PROJ\/other-repo/);
+    expect(() => assertRepoOperationAllowed(gateway, 'PROJ', 'other-repo')).toThrow(/Merging is not allowed in PROJ\/other-repo/);
+  });
+
+  it('names the refused operation in the message', () => {
+    const declineGateway = resolveDeclineGateway({
+      env: { BITBUCKET_DECLINE_ENABLED: 'true', BITBUCKET_DECLINE_ALLOWED_REPOS: 'PROJ/demo' },
+      warn: silentWarn,
+    });
+    expect(() => assertRepoOperationAllowed(declineGateway, 'PROJ', 'other-repo'))
+      .toThrow(/Declining is not allowed in PROJ\/other-repo/);
   });
 
   it('does not treat a wildcard project as a prefix of another project', () => {
-    expect(() => assertRepoMergeAllowed(gateway, 'OTHERS', 'demo')).toThrow(/not allowed/);
+    expect(() => assertRepoOperationAllowed(gateway, 'OTHERS', 'demo')).toThrow(/not allowed/);
   });
 });
 
 describe('assertTargetRefMergeAllowed', () => {
-  const unrestricted = { enabled: true, repos: ['PROJ/demo'], targetRefs: [] };
-  const restricted = {
+  const unrestricted: RepoGateway = { enabled: true, repos: ['PROJ/demo'], targetRefs: [], policy: MERGE_POLICY };
+  const restricted: RepoGateway = {
     enabled: true,
     repos: ['PROJ/demo'],
     targetRefs: ['refs/heads/develop', 'refs/heads/release/*'],
+    policy: MERGE_POLICY,
   };
 
   it('allows any ref when no target-ref restriction is configured', () => {

package/src/bitbucket-service.ts

@@ -5,7 +5,14 @@ import { handleApiOperation, resolveOpenApiBase } from '@atlassian-dc-mcp/common
 import { simplifyInboxPullRequests } from './inbox-pr-mapper.js';
 import { CompareDiffResponse, formatCompareDiffAsUnified } from './compare-diff-mapper.js';
 import { BITBUCKET_PRODUCT, getDefaultPageSize, getMissingConfig } from './config.js';
+import { fetchPullRequestBuilds } from './pr-builds.js';
 import { fetchMergeability, mergePullRequest, type MergePullRequestParams } from './pr-merge.js';
+import {
+  declinePullRequest,
+  reopenPullRequest,
+  type DeclinePullRequestParams,
+  type ReopenPullRequestParams,
+} from './pr-state.js';
 import {
   BitbucketMutationOutputMode,
   BitbucketOutputMode,
@@ -581,6 +588,17 @@ export class BitbucketService {
     return fetchMergeability(projectKey.toUpperCase(), repositorySlug.toLowerCase(), pullRequestId);
   }
 
+  /**
+   * Get the CI build statuses reported on a pull request's latest source commit. Read-only.
+   * @param projectKey The project key
+   * @param repositorySlug The repository slug
+   * @param pullRequestId The pull request ID
+   * @returns Promise with the commit id, per-state counts and the build statuses
+   */
+  async getPullRequestBuilds(projectKey: string, repositorySlug: string, pullRequestId: string) {
+    return fetchPullRequestBuilds(projectKey.toUpperCase(), repositorySlug.toLowerCase(), pullRequestId);
+  }
+
   /**
    * Merge a pull request. Only permitted for repositories (and target branches) the operator
    * allowed through the merge gateway; see merge-gateway.ts. A conflicted or vetoed pull
@@ -599,6 +617,35 @@ export class BitbucketService {
     });
   }
 
+  /**
+   * Decline a pull request. Only permitted for repositories the operator allowed through the
+   * decline gateway; see repo-gateway.ts.
+   * @param params.version The current pull request version, required for optimistic locking
+   * @param params.comment Optional reason, posted as a pull request comment by the same request
+   * @param params.gateway The resolved operator decline policy
+   * @returns Promise with the declined pull request
+   */
+  async declinePullRequest(params: DeclinePullRequestParams) {
+    return declinePullRequest({
+      ...params,
+      projectKey: params.projectKey.toUpperCase(),
+      repositorySlug: params.repositorySlug.toLowerCase(),
+    });
+  }
+
+  /**
+   * Reopen a declined pull request. Not gated: it restores the state a decline removed.
+   * @param params.version The current pull request version, required for optimistic locking
+   * @returns Promise with the reopened pull request
+   */
+  async reopenPullRequest(params: ReopenPullRequestParams) {
+    return reopenPullRequest({
+      ...params,
+      projectKey: params.projectKey.toUpperCase(),
+      repositorySlug: params.repositorySlug.toLowerCase(),
+    });
+  }
+
   /**
    * Get a user by slug, or search for users by name/email filter
    * @param userSlug Optional exact slug to look up a specific user
@@ -1259,6 +1306,11 @@ export const bitbucketToolSchemas = {
     repositorySlug: z.string().describe("The repository slug"),
     pullRequestId: z.string().describe("The pull request ID")
   },
+  getPullRequestBuilds: {
+    projectKey: z.string().describe("The project key"),
+    repositorySlug: z.string().describe("The repository slug"),
+    pullRequestId: z.string().describe("The pull request ID")
+  },
   mergePullRequest: {
     projectKey: z.string().describe("The project key"),
     repositorySlug: z.string().describe("The repository slug"),
@@ -1268,6 +1320,21 @@ export const bitbucketToolSchemas = {
     message: z.string().optional().describe("Commit message for the merge commit. Omit to let Bitbucket generate it."),
     output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
   },
+  declinePullRequest: {
+    projectKey: z.string().describe("The project key"),
+    repositorySlug: z.string().describe("The repository slug"),
+    pullRequestId: z.string().describe("The pull request ID"),
+    version: z.number().describe("The current version of the pull request (required for optimistic locking). Fetch it with bitbucket_getPullRequest immediately before declining; a stale version is rejected with a 409, in which case refetch the version and retry once."),
+    comment: z.string().optional().describe("Reason for declining, posted as a pull request comment by the same request. Prefer this over posting a separate comment first: sending both together means a rejected decline leaves no orphaned 'why this was abandoned' comment on a pull request that stayed open."),
+    output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
+  },
+  reopenPullRequest: {
+    projectKey: z.string().describe("The project key"),
+    repositorySlug: z.string().describe("The repository slug"),
+    pullRequestId: z.string().describe("The pull request ID"),
+    version: z.number().describe("The current version of the pull request (required for optimistic locking). Fetch it with bitbucket_getPullRequest immediately before reopening; a stale version is rejected with a 409, in which case refetch the version and retry once."),
+    output: z.enum(['ack', 'full']).optional().describe("Return a compact acknowledgement or the full API response. Defaults to ack.")
+  },
   getRequiredReviewers: {
     projectKey: z.string().describe("The project key"),
     repositorySlug: z.string().describe("The repository slug"),

package/src/index.ts

@@ -1,7 +1,7 @@
 import { connectServer, createMcpServer, formatToolResponse, initializeRuntimeConfig } from '@atlassian-dc-mcp/common';
 import { BitbucketService, bitbucketToolSchemas } from './bitbucket-service.js';
 import { getBitbucketRuntimeConfig, getDefaultPageSize } from './config.js';
-import { resolveMergeGateway } from './merge-gateway.js';
+import { resolveDeclineGateway, resolveMergeGateway } from './repo-gateway.js';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
@@ -229,6 +229,16 @@ server.tool(
   }
 );
 
+server.tool(
+  "bitbucket_getPullRequestBuilds",
+  "Get the CI/CD build statuses of a pull request — the builds, jobs or pipelines that any CI server integrated with Bitbucket (Jenkins, Bamboo, TeamCity or any other tool posting build statuses) reported on the latest commit of its source branch, as shown in the pull request's Builds panel. Use it to check whether a pull request's checks passed, failed or are still running, e.g. after a push. Read-only. Returns the commit id, counts per state, and for each build its state (SUCCESSFUL, FAILED, INPROGRESS, CANCELLED, UNKNOWN), name, url of the run in the CI server and description.",
+  bitbucketToolSchemas.getPullRequestBuilds,
+  async ({ projectKey, repositorySlug, pullRequestId }) => {
+    const result = await bitbucketService.getPullRequestBuilds(projectKey, repositorySlug, pullRequestId);
+    return formatToolResponse(result);
+  }
+);
+
 const mergeGateway = resolveMergeGateway();
 
 // Merging lands code on a shared branch and cannot be undone through the API, so the tool is
@@ -257,6 +267,47 @@ if (mergeGateway.enabled) {
   );
 }
 
+const declineGateway = resolveDeclineGateway();
+
+// Declining is reviewer-visible the moment it lands and notifies everyone on the pull request, so
+// it is registered only for the repositories the operator named. Reopening is the undo path and is
+// always available.
+if (declineGateway.enabled) {
+  server.tool(
+    "bitbucket_declinePullRequest",
+    `Decline (close without merging) a pull request. IMPORTANT: you MUST first call bitbucket_getPullRequest to get the current 'version' — it is required for optimistic locking and a stale version is rejected. Pass the reason as 'comment' so it is posted with the decline in a single request. Reviewers are notified; undo with bitbucket_reopenPullRequest. Allowed on this server: ${declineGateway.repos.join(', ')}.`,
+    bitbucketToolSchemas.declinePullRequest,
+    async ({ projectKey, repositorySlug, pullRequestId, version, comment, output }) => {
+      const result = await bitbucketService.declinePullRequest({
+        projectKey,
+        repositorySlug,
+        pullRequestId,
+        version,
+        comment,
+        output,
+        gateway: declineGateway,
+      });
+      return formatToolResponse(result);
+    }
+  );
+}
+
+server.tool(
+  "bitbucket_reopenPullRequest",
+  "Reopen a declined pull request, restoring it to OPEN. IMPORTANT: you MUST first call bitbucket_getPullRequest to get the current 'version' — it is required for optimistic locking and a stale version is rejected. The pull request must be in the DECLINED state; anything else is refused.",
+  bitbucketToolSchemas.reopenPullRequest,
+  async ({ projectKey, repositorySlug, pullRequestId, version, output }) => {
+    const result = await bitbucketService.reopenPullRequest({
+      projectKey,
+      repositorySlug,
+      pullRequestId,
+      version,
+      output,
+    });
+    return formatToolResponse(result);
+  }
+);
+
 server.tool(
   "bitbucket_getRequiredReviewers",
   "Get required reviewers for pull request creation. Returns a set of users who are required reviewers for pull requests created from the given source repository and ref to the given target ref in this repository.",

package/src/pr-builds.ts

@@ -0,0 +1,74 @@
+import { handleApiOperation } from '@atlassian-dc-mcp/common';
+import { DeprecatedService, PullRequestsService } from './bitbucket-client/index.js';
+
+/** The commit build-status resource keeps only the 100 most recent statuses per commit. */
+const MAX_BUILD_STATUSES = 100;
+
+type BuildState = 'SUCCESSFUL' | 'FAILED' | 'INPROGRESS' | 'CANCELLED' | 'UNKNOWN';
+
+export interface BuildStatus {
+  key?: string;
+  name?: string;
+  state?: BuildState;
+  url?: string;
+  description?: string;
+  dateAdded?: number;
+  duration?: number;
+  buildNumber?: string;
+  testResults?: { successful?: number; failed?: number; skipped?: number };
+}
+
+export interface BuildCounts {
+  successful: number;
+  failed: number;
+  inProgress: number;
+  cancelled: number;
+  unknown: number;
+}
+
+export interface PullRequestBuilds {
+  commitId: string;
+  counts: BuildCounts;
+  builds: BuildStatus[];
+}
+
+const COUNT_FIELD: Record<BuildState, keyof BuildCounts> = {
+  SUCCESSFUL: 'successful',
+  FAILED: 'failed',
+  INPROGRESS: 'inProgress',
+  CANCELLED: 'cancelled',
+  UNKNOWN: 'unknown',
+};
+
+function countBuilds(builds: BuildStatus[]): BuildCounts {
+  const counts: BuildCounts = { successful: 0, failed: 0, inProgress: 0, cancelled: 0, unknown: 0 };
+  for (const build of builds) {
+    counts[COUNT_FIELD[build.state ?? 'UNKNOWN'] ?? 'unknown'] += 1;
+  }
+  return counts;
+}
+
+async function fetchLatestSourceCommit(projectKey: string, repositorySlug: string, pullRequestId: string): Promise<string> {
+  const pullRequest = await PullRequestsService.get3(projectKey, pullRequestId, repositorySlug) as {
+    fromRef?: { latestCommit?: string };
+  };
+  const latestCommit = pullRequest?.fromRef?.latestCommit;
+  if (!latestCommit) {
+    throw new Error(`Pull request ${pullRequestId} has no source commit`);
+  }
+  return latestCommit;
+}
+
+/**
+ * Build statuses on the pull request's latest source commit — what the pull request's Builds
+ * panel shows. Uses the commit-level build-status resource because the repository-scoped one
+ * only returns a single status by key and cannot list them.
+ */
+export async function fetchPullRequestBuilds(projectKey: string, repositorySlug: string, pullRequestId: string) {
+  return handleApiOperation<PullRequestBuilds>(async () => {
+    const commitId = await fetchLatestSourceCommit(projectKey, repositorySlug, pullRequestId);
+    const page = await DeprecatedService.getBuildStatus(commitId, 'NEWEST', 0, MAX_BUILD_STATUSES);
+    const builds = (page?.values ?? []) as BuildStatus[];
+    return { commitId, counts: countBuilds(builds), builds };
+  }, 'Error fetching pull request builds');
+}

package/src/pr-merge.ts

@@ -5,7 +5,7 @@ import {
   shapeMergeability,
   shapePullRequestAck,
 } from './bitbucket-response-mapper.js';
-import { assertRepoMergeAllowed, assertTargetRefMergeAllowed, type MergeGateway } from './merge-gateway.js';
+import { assertRepoOperationAllowed, assertTargetRefMergeAllowed, type RepoGateway } from './repo-gateway.js';
 
 export interface MergePullRequestParams {
   projectKey: string;
@@ -13,7 +13,7 @@ export interface MergePullRequestParams {
   pullRequestId: string;
   /** Current PR version, required for optimistic locking. */
   version: number;
-  gateway: MergeGateway;
+  gateway: RepoGateway;
   strategyId?: string;
   message?: string;
   output?: BitbucketMutationOutputMode;
@@ -75,7 +75,7 @@ export async function mergePullRequest(params: MergePullRequestParams) {
   const { projectKey, repositorySlug, pullRequestId, version, gateway } = params;
 
   const result = await handleApiOperation(async () => {
-    assertRepoMergeAllowed(gateway, projectKey, repositorySlug);
+    assertRepoOperationAllowed(gateway, projectKey, repositorySlug);
     await assertTargetRefAllowed(params);
     await assertMergeable(projectKey, repositorySlug, pullRequestId);
 

package/src/pr-state.ts

@@ -0,0 +1,68 @@
+import { handleApiOperation } from '@atlassian-dc-mcp/common';
+import { PullRequestsService } from './bitbucket-client/index.js';
+import { BitbucketMutationOutputMode, shapePullRequestAck } from './bitbucket-response-mapper.js';
+import { assertRepoOperationAllowed, type RepoGateway } from './repo-gateway.js';
+
+interface PullRequestStateParams {
+  projectKey: string;
+  repositorySlug: string;
+  pullRequestId: string;
+  /** Current PR version, required for optimistic locking. */
+  version: number;
+  output?: BitbucketMutationOutputMode;
+}
+
+export interface DeclinePullRequestParams extends PullRequestStateParams {
+  gateway: RepoGateway;
+  /**
+   * Reason for declining, posted as a pull request comment by the same request. Sending it with
+   * the decline keeps the two atomic: a rejected decline leaves no orphaned "why this was
+   * abandoned" comment on a pull request that stayed open.
+   */
+  comment?: string;
+}
+
+export type ReopenPullRequestParams = PullRequestStateParams;
+
+/** The ack carries the new version, which is what a later reopen needs as its optimistic lock. */
+function shapeResult<T extends { success: boolean; data?: unknown }>(result: T, output?: BitbucketMutationOutputMode) {
+  if (result.success && result.data && output !== 'full') {
+    return { ...result, data: shapePullRequestAck(result.data) };
+  }
+  return result;
+}
+
+/**
+ * Decline a pull request under the operator's decline policy. The repository is checked before
+ * any request is issued. Bitbucket rejects a stale version and a pull request that is not OPEN
+ * with a 409, so no pre-flight read is needed.
+ */
+export async function declinePullRequest(params: DeclinePullRequestParams) {
+  const { projectKey, repositorySlug, pullRequestId, version, gateway, comment } = params;
+
+  const result = await handleApiOperation(async () => {
+    assertRepoOperationAllowed(gateway, projectKey, repositorySlug);
+
+    return PullRequestsService.decline(projectKey, pullRequestId, repositorySlug, String(version), {
+      version,
+      ...(comment ? { comment } : {}),
+    });
+  }, 'Error declining pull request');
+
+  return shapeResult(result, params.output);
+}
+
+/**
+ * Reopen a declined pull request. Ungated: it restores the state a decline removed, so it is the
+ * undo path rather than a destructive one. A pull request that is not declined is rejected with a 409.
+ */
+export async function reopenPullRequest(params: ReopenPullRequestParams) {
+  const { projectKey, repositorySlug, pullRequestId, version } = params;
+
+  const result = await handleApiOperation(
+    () => PullRequestsService.reopen(projectKey, pullRequestId, repositorySlug, String(version), { version }),
+    'Error reopening pull request',
+  );
+
+  return shapeResult(result, params.output);
+}

package/src/repo-gateway.ts

@@ -0,0 +1,183 @@
+/**
+ * Operator-controlled gate for pull request operations that change state on a shared branch
+ * or in front of other people.
+ *
+ * A merge cannot be undone through the API, and a decline is visible to every reviewer the
+ * moment it lands, so both are disabled by default: the tool is not even registered unless
+ * the operator enables it and names the repositories it may act on. Each operation reads its
+ * own environment variables, so allowing declines never implies allowing merges. The scope is
+ * read once at startup, so the model can never select or widen it. Read-only checks are not
+ * gated.
+ */
+
+/** Names an operation in refusal messages and points the operator at the variables that open it. */
+export interface GatewayPolicy {
+  /** Short operation name, used to tag warnings. */
+  name: string;
+  /** Gerund that starts a refusal message, e.g. "Merging". */
+  gerund: string;
+  flagVar: string;
+  reposVar: string;
+  /** Omitted for operations that have no meaningful target-branch restriction. */
+  targetRefsVar?: string;
+}
+
+export const MERGE_POLICY: GatewayPolicy = {
+  name: 'merge',
+  gerund: 'Merging',
+  flagVar: 'BITBUCKET_MERGE_ENABLED',
+  reposVar: 'BITBUCKET_MERGE_ALLOWED_REPOS',
+  targetRefsVar: 'BITBUCKET_MERGE_ALLOWED_TARGET_REFS',
+};
+
+/**
+ * Declining has no target-ref restriction: which branch a pull request would have landed on
+ * says nothing about whether abandoning it is safe.
+ */
+export const DECLINE_POLICY: GatewayPolicy = {
+  name: 'decline',
+  gerund: 'Declining',
+  flagVar: 'BITBUCKET_DECLINE_ENABLED',
+  reposVar: 'BITBUCKET_DECLINE_ALLOWED_REPOS',
+};
+
+export interface RepoGateway {
+  /** Whether the operation is enabled and at least one valid repository pattern resolved. */
+  enabled: boolean;
+  /** Allowed `PROJECT/repository-slug` targets; a `PROJECT/*` entry allows the whole project. */
+  repos: string[];
+  /** Allowed target refs; a trailing `*` matches a prefix. Empty means any ref in an allowed repository. */
+  targetRefs: string[];
+  policy: GatewayPolicy;
+}
+
+type Env = Record<string, string | undefined>;
+type Warn = (message: string) => void;
+
+export interface ResolveGatewayOptions {
+  env?: Env;
+  warn?: Warn;
+}
+
+const REPO_ENTRY_RE = /^[^\s/]+\/[^\s/]+$/;
+
+function readBool(env: Env, name: string): boolean {
+  const value = env[name]?.trim().toLowerCase();
+  return value === 'true' || value === '1' || value === 'yes';
+}
+
+function parseList(raw: string | undefined): string[] {
+  return (raw ?? '').split(/[,;\s]+/).map(entry => entry.trim()).filter(Boolean);
+}
+
+function dedupe(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+/**
+ * Accepts `PROJECT/repository-slug` or `PROJECT/*`. The project key is upper-cased and
+ * the slug lower-cased to match the casing the REST API uses, so comparisons are exact.
+ */
+function normalizeRepoEntry(entry: string, warn: Warn): string | undefined {
+  if (!REPO_ENTRY_RE.test(entry)) {
+    warn(`Ignoring repository entry that is not "PROJECT/repository-slug" or "PROJECT/*": "${entry}"`);
+    return undefined;
+  }
+  const [projectKey, slug] = entry.split('/');
+  if (projectKey === '*') {
+    warn(`Ignoring repository entry that would allow every project: "${entry}"`);
+    return undefined;
+  }
+  return `${projectKey.toUpperCase()}/${slug.toLowerCase()}`;
+}
+
+/** Bare branch names are expanded so operators can write `develop` instead of `refs/heads/develop`. */
+function normalizeRefEntry(entry: string): string {
+  return entry.startsWith('refs/') ? entry : `refs/heads/${entry}`;
+}
+
+function matchesPattern(value: string, pattern: string): boolean {
+  return pattern.endsWith('*') ? value.startsWith(pattern.slice(0, -1)) : value === pattern;
+}
+
+function disabledGateway(policy: GatewayPolicy): RepoGateway {
+  return { enabled: false, repos: [], targetRefs: [], policy };
+}
+
+/**
+ * Reads one operation's gateway configuration from the environment. The operation only
+ * activates when its flag is set and at least one repository entry is valid; otherwise a
+ * warning is logged and the gateway stays disabled.
+ */
+export function resolveGateway(policy: GatewayPolicy, options?: ResolveGatewayOptions): RepoGateway {
+  const env = options?.env ?? process.env;
+  const warn = options?.warn ?? ((message: string) => console.error(`[${policy.name}-gateway] ${message}`));
+
+  if (!readBool(env, policy.flagVar)) {
+    return disabledGateway(policy);
+  }
+
+  const repos = dedupe(
+    parseList(env[policy.reposVar])
+      .map(entry => normalizeRepoEntry(entry, warn))
+      .filter((entry): entry is string => Boolean(entry)),
+  );
+
+  if (repos.length === 0) {
+    warn(
+      `${policy.gerund} was enabled but no valid repository is configured (set ${policy.reposVar} ` +
+        'to a list of "PROJECT/repository-slug" or "PROJECT/*" entries); the tool will stay disabled.',
+    );
+    return disabledGateway(policy);
+  }
+
+  const targetRefs = policy.targetRefsVar
+    ? dedupe(parseList(env[policy.targetRefsVar]).map(normalizeRefEntry))
+    : [];
+
+  return { enabled: true, repos, targetRefs, policy };
+}
+
+export function resolveMergeGateway(options?: ResolveGatewayOptions): RepoGateway {
+  return resolveGateway(MERGE_POLICY, options);
+}
+
+export function resolveDeclineGateway(options?: ResolveGatewayOptions): RepoGateway {
+  return resolveGateway(DECLINE_POLICY, options);
+}
+
+/** Throws unless the gateway allows its operation in this repository. No network call. */
+export function assertRepoOperationAllowed(gateway: RepoGateway, projectKey: string, repositorySlug: string): void {
+  const { policy } = gateway;
+  if (!gateway.enabled) {
+    throw new Error(
+      `${policy.gerund} pull requests is disabled on this server. Enable it with ${policy.flagVar} ` +
+        `and list the allowed repositories in ${policy.reposVar}.`,
+    );
+  }
+  const target = `${projectKey.toUpperCase()}/${repositorySlug.toLowerCase()}`;
+  if (!gateway.repos.some(pattern => matchesPattern(target, pattern))) {
+    throw new Error(
+      `${policy.gerund} is not allowed in ${target} on this server. Allowed: ${gateway.repos.join(', ')}.`,
+    );
+  }
+}
+
+/** Throws unless the gateway allows merging into this target ref. A gateway with no ref restriction allows all. */
+export function assertTargetRefMergeAllowed(gateway: RepoGateway, targetRefId: string | undefined): void {
+  if (gateway.targetRefs.length === 0) {
+    return;
+  }
+  if (!targetRefId) {
+    throw new Error(
+      'Could not determine the target branch of the pull request, and this server restricts which ' +
+        `branches may be merged into (${gateway.policy.targetRefsVar}); refusing to merge.`,
+    );
+  }
+  if (!gateway.targetRefs.some(pattern => matchesPattern(targetRefId, pattern))) {
+    throw new Error(
+      `Merging into ${targetRefId} is not allowed on this server. ` +
+        `Allowed target refs: ${gateway.targetRefs.join(', ')}.`,
+    );
+  }
+}