@atlassian-dc-mcp/bitbucket 0.34.0 → 0.36.0

package/build/repo-gateway.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 declare const MERGE_POLICY: GatewayPolicy;
+/**
+ * Declining has no target-ref restriction: which branch a pull request would have landed on
+ * says nothing about whether abandoning it is safe.
+ */
+export declare const DECLINE_POLICY: GatewayPolicy;
+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;
+}
+/**
+ * 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 declare function resolveGateway(policy: GatewayPolicy, options?: ResolveGatewayOptions): RepoGateway;
+export declare function resolveMergeGateway(options?: ResolveGatewayOptions): RepoGateway;
+export declare function resolveDeclineGateway(options?: ResolveGatewayOptions): RepoGateway;
+/** Throws unless the gateway allows its operation in this repository. No network call. */
+export declare function assertRepoOperationAllowed(gateway: RepoGateway, projectKey: string, repositorySlug: string): void;
+/** Throws unless the gateway allows merging into this target ref. A gateway with no ref restriction allows all. */
+export declare function assertTargetRefMergeAllowed(gateway: RepoGateway, targetRefId: string | undefined): void;
+export {};
+//# sourceMappingURL=repo-gateway.d.ts.map

package/build/repo-gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-gateway.d.ts","sourceRoot":"","sources":["../src/repo-gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,oGAAoG;AACpG,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,YAAY,EAAE,aAM1B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,aAK5B,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,2FAA2F;IAC3F,OAAO,EAAE,OAAO,CAAC;IACjB,+FAA+F;IAC/F,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,0GAA0G;IAC1G,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAC9C,KAAK,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAEtC,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AA+CD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,WAAW,CA2BlG;AAED,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,WAAW,CAEhF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,WAAW,CAElF;AAED,0FAA0F;AAC1F,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAcjH;AAED,mHAAmH;AACnH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAgBvG"}

package/build/repo-gateway.js

@@ -0,0 +1,122 @@
+/**
+ * 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.
+ */
+export const MERGE_POLICY = {
+    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 = {
+    name: 'decline',
+    gerund: 'Declining',
+    flagVar: 'BITBUCKET_DECLINE_ENABLED',
+    reposVar: 'BITBUCKET_DECLINE_ALLOWED_REPOS',
+};
+const REPO_ENTRY_RE = /^[^\s/]+\/[^\s/]+$/;
+function readBool(env, name) {
+    const value = env[name]?.trim().toLowerCase();
+    return value === 'true' || value === '1' || value === 'yes';
+}
+function parseList(raw) {
+    return (raw ?? '').split(/[,;\s]+/).map(entry => entry.trim()).filter(Boolean);
+}
+function dedupe(values) {
+    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, warn) {
+    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) {
+    return entry.startsWith('refs/') ? entry : `refs/heads/${entry}`;
+}
+function matchesPattern(value, pattern) {
+    return pattern.endsWith('*') ? value.startsWith(pattern.slice(0, -1)) : value === pattern;
+}
+function disabledGateway(policy) {
+    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, options) {
+    const env = options?.env ?? process.env;
+    const warn = options?.warn ?? ((message) => 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) => 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) {
+    return resolveGateway(MERGE_POLICY, options);
+}
+export function resolveDeclineGateway(options) {
+    return resolveGateway(DECLINE_POLICY, options);
+}
+/** Throws unless the gateway allows its operation in this repository. No network call. */
+export function assertRepoOperationAllowed(gateway, projectKey, repositorySlug) {
+    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, targetRefId) {
+    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(', ')}.`);
+    }
+}
+//# sourceMappingURL=repo-gateway.js.map

package/build/repo-gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-gateway.js","sourceRoot":"","sources":["../src/repo-gateway.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlassian-dc-mcp/bitbucket",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "main": "build/index.js",
   "type": "module",
   "bin": "./bin/run.js",
@@ -31,7 +31,7 @@
     "test": "jest"
   },
   "dependencies": {
-    "@atlassian-dc-mcp/common": "^0.34.0",
+    "@atlassian-dc-mcp/common": "^0.36.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "dotenv": "^16.4.7",
     "zod": "^3.24.2"
@@ -48,5 +48,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "ab2b534bafefa4666feca463e79824dadb797ff3"
+  "gitHead": "f2ef2f49cce893cbf1ff2cad072cdecaae7ad28d"
 }

package/src/__tests__/bitbucket-service.test.ts

@@ -3,7 +3,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { initializeRuntimeConfig } from '@atlassian-dc-mcp/common';
 import { BitbucketService } from '../bitbucket-service.js';
-import { PullRequestsService, RepositoryService } from '../bitbucket-client/index.js';
+import { DeprecatedService, PullRequestsService, RepositoryService } from '../bitbucket-client/index.js';
+import { DECLINE_POLICY, type RepoGateway } from '../repo-gateway.js';
 import { request as mockRequest } from '../bitbucket-client/core/request.js';
 
 // Mock the request function
@@ -23,12 +24,17 @@ jest.mock('../bitbucket-client/index.js', () => ({
     updateStatus: jest.fn(),
     getPage: jest.fn(),
     getReviewers: jest.fn(),
-    get3: jest.fn()
+    get3: jest.fn(),
+    decline: jest.fn(),
+    reopen: jest.fn()
   },
   RepositoryService: {
     streamRaw: jest.fn(),
     createBranch: jest.fn()
   },
+  DeprecatedService: {
+    getBuildStatus: jest.fn()
+  },
   OpenAPI: {
     BASE: '',
     TOKEN: '',
@@ -2971,6 +2977,48 @@ describe('BitbucketService', () => {
         'refs/heads/feature', 'refs/heads/main'
       );
     });
+
+    it('should uppercase projectKey and lowercase repositorySlug for declinePullRequest', async () => {
+      const gateway: RepoGateway = {
+        enabled: true,
+        repos: ['TEST/test-repo'],
+        targetRefs: [],
+        policy: DECLINE_POLICY,
+      };
+      (PullRequestsService.decline as jest.Mock).mockResolvedValue({ id: 1, state: 'DECLINED' });
+
+      await bitbucketService.declinePullRequest({
+        projectKey: 'test',
+        repositorySlug: 'Test-Repo',
+        pullRequestId: '1',
+        version: 2,
+        gateway,
+      });
+
+      expect(PullRequestsService.decline).toHaveBeenCalledWith('TEST', '1', 'test-repo', '2', { version: 2 });
+    });
+
+    it('should uppercase projectKey and lowercase repositorySlug for reopenPullRequest', async () => {
+      (PullRequestsService.reopen as jest.Mock).mockResolvedValue({ id: 1, state: 'OPEN' });
+
+      await bitbucketService.reopenPullRequest({
+        projectKey: 'test',
+        repositorySlug: 'Test-Repo',
+        pullRequestId: '1',
+        version: 2,
+      });
+
+      expect(PullRequestsService.reopen).toHaveBeenCalledWith('TEST', '1', 'test-repo', '2', { version: 2 });
+    });
+
+    it('should uppercase projectKey and lowercase repositorySlug for getPullRequestBuilds', async () => {
+      (PullRequestsService.get3 as jest.Mock).mockResolvedValue({ id: 1, fromRef: { latestCommit: 'abc123' } });
+      (DeprecatedService.getBuildStatus as jest.Mock).mockResolvedValue({ values: [] });
+
+      await bitbucketService.getPullRequestBuilds('test', 'Test-Repo', '1');
+
+      expect(PullRequestsService.get3).toHaveBeenCalledWith('TEST', '1', 'test-repo');
+    });
   });
 
   describe('searchCode', () => {

package/src/__tests__/config.test.ts

@@ -16,8 +16,9 @@ describe('Bitbucket config', () => {
   });
 
   afterEach(() => {
-    fs.rmSync(tempDir, { recursive: true, force: true });
+    // Windows refuses to remove a directory that is still the process cwd.
     process.chdir(originalCwd);
+    fs.rmSync(tempDir, { recursive: true, force: true });
   });
 
   afterAll(() => {

package/src/__tests__/pr-builds.test.ts

@@ -0,0 +1,93 @@
+import { DeprecatedService, PullRequestsService } from '../bitbucket-client/index.js';
+import { fetchPullRequestBuilds } from '../pr-builds.js';
+
+jest.mock('../bitbucket-client/index.js', () => ({
+  PullRequestsService: {
+    get3: jest.fn(),
+  },
+  DeprecatedService: {
+    getBuildStatus: jest.fn(),
+  },
+  OpenAPI: { BASE: '', TOKEN: '', VERSION: '' },
+}));
+
+const getPullRequest = PullRequestsService.get3 as jest.Mock;
+const getBuildStatus = DeprecatedService.getBuildStatus as jest.Mock;
+
+const HEAD = '0780e1428c06abf1c96ab9cb995d129255511c93';
+const OPEN_PR = { id: 42, fromRef: { id: 'refs/heads/feature', latestCommit: HEAD } };
+
+const BUILD = {
+  key: 'a1',
+  name: 'Builds » demo » PR-42 #1',
+  state: 'SUCCESSFUL',
+  url: 'https://ci.example.com/job/demo/job/PR-42/1/',
+  description: 'This commit looks good.',
+  dateAdded: 1791464936354,
+};
+const E2E = { ...BUILD, key: 'b2', name: 'E2E » demo » PR-42 #1', state: 'FAILED' };
+const REVIEW = { ...BUILD, key: 'c3', name: 'AI Code Review » demo » PR-42 #1', state: 'INPROGRESS' };
+
+describe('fetchPullRequestBuilds', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('lists the build statuses of the latest source commit with per-state counts', async () => {
+    getPullRequest.mockResolvedValue(OPEN_PR);
+    getBuildStatus.mockResolvedValue({ size: 3, isLastPage: true, values: [BUILD, E2E, REVIEW] });
+
+    const result = await fetchPullRequestBuilds('PROJ', 'demo', '42');
+
+    expect(getPullRequest).toHaveBeenCalledWith('PROJ', '42', 'demo');
+    expect(getBuildStatus).toHaveBeenCalledWith(HEAD, 'NEWEST', 0, 100);
+    expect(result).toEqual({
+      success: true,
+      data: {
+        commitId: HEAD,
+        counts: { successful: 1, failed: 1, inProgress: 1, cancelled: 0, unknown: 0 },
+        builds: [BUILD, E2E, REVIEW],
+      },
+    });
+  });
+
+  it('counts a build without a recognised state as unknown', async () => {
+    getPullRequest.mockResolvedValue(OPEN_PR);
+    getBuildStatus.mockResolvedValue({ values: [{ key: 'x' }, { key: 'y', state: 'QUEUED' }] });
+
+    const result = await fetchPullRequestBuilds('PROJ', 'demo', '42');
+
+    expect(result.data?.counts).toEqual({ successful: 0, failed: 0, inProgress: 0, cancelled: 0, unknown: 2 });
+  });
+
+  it('returns empty builds when no CI has reported on the commit', async () => {
+    getPullRequest.mockResolvedValue(OPEN_PR);
+    getBuildStatus.mockResolvedValue({ size: 0, isLastPage: true, values: [] });
+
+    const result = await fetchPullRequestBuilds('PROJ', 'demo', '42');
+
+    expect(result.data).toEqual({
+      commitId: HEAD,
+      counts: { successful: 0, failed: 0, inProgress: 0, cancelled: 0, unknown: 0 },
+      builds: [],
+    });
+  });
+
+  it('fails without querying builds when the pull request has no source commit', async () => {
+    getPullRequest.mockResolvedValue({ id: 42, fromRef: { id: 'refs/heads/feature' } });
+
+    const result = await fetchPullRequestBuilds('PROJ', 'demo', '42');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Pull request 42 has no source commit');
+    expect(getBuildStatus).not.toHaveBeenCalled();
+  });
+
+  it('reports an API error with the status line', async () => {
+    getPullRequest.mockRejectedValue({ status: 404, statusText: 'Not Found', body: { errors: [] } });
+
+    const result = await fetchPullRequestBuilds('PROJ', 'demo', '42');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Error fetching pull request builds: 404 Not Found');
+    expect(getBuildStatus).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/pr-merge.test.ts

@@ -1,6 +1,6 @@
 import { PullRequestsService } from '../bitbucket-client/index.js';
 import { fetchMergeability, mergePullRequest } from '../pr-merge.js';
-import type { MergeGateway } from '../merge-gateway.js';
+import { MERGE_POLICY, type RepoGateway } from '../repo-gateway.js';
 
 jest.mock('../bitbucket-client/index.js', () => ({
   PullRequestsService: {
@@ -15,7 +15,7 @@ const canMerge = PullRequestsService.canMerge as jest.Mock;
 const merge = PullRequestsService.merge as jest.Mock;
 const getPullRequest = PullRequestsService.get3 as jest.Mock;
 
-const OPEN_GATEWAY: MergeGateway = { enabled: true, repos: ['PROJ/demo'], targetRefs: [] };
+const OPEN_GATEWAY: RepoGateway = { enabled: true, repos: ['PROJ/demo'], targetRefs: [], policy: MERGE_POLICY };
 const CLEAN = { canMerge: true, conflicted: false, outcome: 'CLEAN', vetoes: [] };
 const MERGED_PR = {
   id: 42,
@@ -111,7 +111,7 @@ describe('mergePullRequest', () => {
   it('refuses without any request when merging is disabled', async () => {
     const result = await mergePullRequest({
       ...baseParams,
-      gateway: { enabled: false, repos: [], targetRefs: [] },
+      gateway: { enabled: false, repos: [], targetRefs: [], policy: MERGE_POLICY },
     });
 
     expect(result.success).toBe(false);
@@ -137,7 +137,7 @@ describe('mergePullRequest', () => {
 
     const result = await mergePullRequest({
       ...baseParams,
-      gateway: { enabled: true, repos: ['PROJ/demo'], targetRefs: ['refs/heads/develop'] },
+      gateway: { enabled: true, repos: ['PROJ/demo'], targetRefs: ['refs/heads/develop'], policy: MERGE_POLICY },
     });
 
     expect(result.success).toBe(false);
@@ -153,7 +153,7 @@ describe('mergePullRequest', () => {
 
     const result = await mergePullRequest({
       ...baseParams,
-      gateway: { enabled: true, repos: ['PROJ/demo'], targetRefs: ['refs/heads/release/*'] },
+      gateway: { enabled: true, repos: ['PROJ/demo'], targetRefs: ['refs/heads/release/*'], policy: MERGE_POLICY },
     });
 
     expect(result.success).toBe(true);

package/src/__tests__/pr-state.test.ts

@@ -0,0 +1,150 @@
+import { PullRequestsService } from '../bitbucket-client/index.js';
+import { declinePullRequest, reopenPullRequest } from '../pr-state.js';
+import { DECLINE_POLICY, type RepoGateway } from '../repo-gateway.js';
+
+jest.mock('../bitbucket-client/index.js', () => ({
+  PullRequestsService: {
+    decline: jest.fn(),
+    reopen: jest.fn(),
+  },
+  OpenAPI: { BASE: '', TOKEN: '', VERSION: '' },
+}));
+
+const decline = PullRequestsService.decline as jest.Mock;
+const reopen = PullRequestsService.reopen as jest.Mock;
+
+const OPEN_GATEWAY: RepoGateway = {
+  enabled: true,
+  repos: ['PROJ/demo'],
+  targetRefs: [],
+  policy: DECLINE_POLICY,
+};
+
+const DECLINED_PR = {
+  id: 42,
+  version: 3,
+  title: 'Add decline tool',
+  state: 'DECLINED',
+  fromRef: { id: 'refs/heads/feature' },
+  toRef: { id: 'refs/heads/develop' },
+  reviewers: [],
+};
+
+const REOPENED_PR = { ...DECLINED_PR, version: 4, state: 'OPEN' };
+
+const baseParams = {
+  projectKey: 'PROJ',
+  repositorySlug: 'demo',
+  pullRequestId: '42',
+  version: 2,
+};
+
+describe('declinePullRequest', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('declines with the version as an optimistic lock and returns a compact ack', async () => {
+    decline.mockResolvedValue(DECLINED_PR);
+
+    const result = await declinePullRequest({ ...baseParams, gateway: OPEN_GATEWAY });
+
+    expect(decline).toHaveBeenCalledWith('PROJ', '42', 'demo', '2', { version: 2 });
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual({
+      id: 42,
+      version: 3,
+      title: 'Add decline tool',
+      state: 'DECLINED',
+      fromRefId: 'refs/heads/feature',
+      toRefId: 'refs/heads/develop',
+      reviewerCount: 0,
+    });
+  });
+
+  it('posts the reason atomically with the decline when a comment is given', async () => {
+    decline.mockResolvedValue(DECLINED_PR);
+
+    await declinePullRequest({
+      ...baseParams,
+      gateway: OPEN_GATEWAY,
+      comment: 'Superseded by PR 99.',
+    });
+
+    expect(decline).toHaveBeenCalledWith('PROJ', '42', 'demo', '2', {
+      version: 2,
+      comment: 'Superseded by PR 99.',
+    });
+  });
+
+  it('can return the full payload', async () => {
+    decline.mockResolvedValue(DECLINED_PR);
+
+    const result = await declinePullRequest({ ...baseParams, gateway: OPEN_GATEWAY, output: 'full' });
+
+    expect(result.data).toBe(DECLINED_PR);
+  });
+
+  it('refuses without any request when declining is disabled', async () => {
+    const result = await declinePullRequest({
+      ...baseParams,
+      gateway: { enabled: false, repos: [], targetRefs: [], policy: DECLINE_POLICY },
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/Declining pull requests is disabled on this server/);
+    expect(decline).not.toHaveBeenCalled();
+  });
+
+  it('refuses a repository outside the allowed list without any request', async () => {
+    const result = await declinePullRequest({
+      ...baseParams,
+      repositorySlug: 'other-repo',
+      gateway: OPEN_GATEWAY,
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/Declining is not allowed in PROJ\/other-repo/);
+    expect(decline).not.toHaveBeenCalled();
+  });
+
+  it('surfaces a server-side failure such as a stale version', async () => {
+    decline.mockRejectedValue({ status: 409, statusText: 'Conflict', body: { errors: [{ message: 'stale' }] } });
+
+    const result = await declinePullRequest({ ...baseParams, gateway: OPEN_GATEWAY });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Error declining pull request: 409 Conflict');
+    expect(result.details).toEqual({ errors: [{ message: 'stale' }] });
+  });
+});
+
+describe('reopenPullRequest', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('reopens with the version as an optimistic lock and returns a compact ack', async () => {
+    reopen.mockResolvedValue(REOPENED_PR);
+
+    const result = await reopenPullRequest(baseParams);
+
+    expect(reopen).toHaveBeenCalledWith('PROJ', '42', 'demo', '2', { version: 2 });
+    expect(result.success).toBe(true);
+    expect(result.data).toMatchObject({ id: 42, version: 4, state: 'OPEN' });
+  });
+
+  it('can return the full payload', async () => {
+    reopen.mockResolvedValue(REOPENED_PR);
+
+    const result = await reopenPullRequest({ ...baseParams, output: 'full' });
+
+    expect(result.data).toBe(REOPENED_PR);
+  });
+
+  it('surfaces a server-side failure such as a pull request that is not declined', async () => {
+    reopen.mockRejectedValue({ status: 409, statusText: 'Conflict', body: { errors: [{ message: 'not declined' }] } });
+
+    const result = await reopenPullRequest(baseParams);
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Error reopening pull request: 409 Conflict');
+    expect(result.details).toEqual({ errors: [{ message: 'not declined' }] });
+  });
+});