@atlassian-dc-mcp/bitbucket 0.34.0 → 0.35.0

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' }] });
+  });
+});

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

@@ -6,6 +6,12 @@ import { simplifyInboxPullRequests } from './inbox-pr-mapper.js';
 import { CompareDiffResponse, formatCompareDiffAsUnified } from './compare-diff-mapper.js';
 import { BITBUCKET_PRODUCT, getDefaultPageSize, getMissingConfig } from './config.js';
 import { fetchMergeability, mergePullRequest, type MergePullRequestParams } from './pr-merge.js';
+import {
+  declinePullRequest,
+  reopenPullRequest,
+  type DeclinePullRequestParams,
+  type ReopenPullRequestParams,
+} from './pr-state.js';
 import {
   BitbucketMutationOutputMode,
   BitbucketOutputMode,
@@ -599,6 +605,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
@@ -1268,6 +1303,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);
@@ -257,6 +257,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-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);
+}