feat: add BitBucket integration for pull request management

[NoahCardoza]

Summary

• Add BitBucket VCS provider with PR creation, listing, reviewer resolution, and repository auto-detection from git remotes
• Add Jira issue tracker provider with sprint/board support, issue transitions, and JQL-based queries
• Address code review feedback: fix error swallowing, BBQL injection, sensitive field redaction, dead code removal, and test coverage gaps

Test plan

• pnpm build compiles successfully
• pnpm test — all 3937 tests pass
• New tests for checkForExistingPR error propagation (401/403 re-thrown, network errors return null)
• New tests for redactSensitiveFields (null/undefined, primitives, sensitive keys, nested objects, arrays)
• New tests for BitBucket URL patterns in parseGitRemotes (HTTPS/SSH, with/without .git)

🤖 Generated with Claude Code

[NoahCardoza]

Rebasing now

[acreeger]

Hey @NoahCardoza — thanks so much for this PR! Really solid work on the BitBucket integration. The security hygiene (token redaction), error handling patterns, and test coverage are all well done. The fromSettings() factory method refactoring is a clean pattern too.

We ran a code review and found 3 bugs that we're fixing up now:

1. JSON mode hang with bitbucket-pr (High) — The JSON mode validation in finish.ts only guards against missing --cleanup/--no-cleanup for github-pr/github-draft-pr, but not bitbucket-pr. This would cause il finish --json to block waiting for interactive input in CI.

2. BitBucket PR listing ignores pagination (Medium) — listPullRequests in BitBucketApiClient.ts only returns the first page of results. Repos with many open PRs would silently get incomplete results. Adding pagination to match the pattern already used in getAllWorkspaceMembers.

3. --mine flag not applied for BitBucket PRs (Medium) — The GitHub path in issues.ts respects --mine, but the BitBucket path fetches all open PRs regardless. Adding current-user filtering.

Also applying prTitlePrefix to GitHub PRs for consistency (it was BitBucket-only before).

Will push these fixes shortly!

[acreeger]

VCS Provider Gap Analysis

After completing the generic merge mode refactoring (epic #842, merged via NoahCardoza#19), I did a thorough audit of how the new VCS provider abstraction integrates across the codebase. There are several gaps where BitBucket as a VCS provider isn't fully wired in. These are all pre-existing architectural issues — not regressions from #842.

---

Critical Gaps

1. createPR() discards the PR number

Files: src/lib/VersionControlProvider.ts, src/lib/providers/bitbucket/BitBucketVCSProvider.ts

The interface defines createPR() as returning Promise<string> (URL only). The BitBucket implementation has the PR ID internally (pr.id at line 162) but only returns pr.links.html.href.

This means finish.ts can't pass a PR number to SessionSummaryService. The interface should return { url: string; number: number }.

Impact: This is the key blocker — SessionSummaryService already has VCS provider routing code (line 411-417) that would work, but prNumber is always undefined for BitBucket PRs, so summaries fall back to posting on the issue instead of the PR.

2. MCP inline review operations hardcoded to GitHub

Files: src/mcp/issue-management-server.ts

• get_review_comments is hardcoded to GitHubIssueManagementProvider — no BitBucket routing
• update_comment(type:pr) doesn't route to BitBucket either

BitBucket Cloud REST API does support inline comments via { inline: { from, path } } in the POST body, but BitBucketApiClient has no inline comment methods — only addPRComment() for general comments.

Note: get_pr and create_comment(type:pr) already route through BitBucket when configured. The MCP server loads settings from filesystem via SettingsManager.loadSettings() at startup, so no additional env vars are needed.

3. MCP type system excludes BitBucket for PR operations

File: src/mcp/types.ts (line 8)

export type IssueProvider = 'github' | 'linear' | 'jira'

Correct for issue tracking, but the MCP server uses this same type for PR operations. PR operations need to route through VCSProviderFactory instead of IssueManagementProviderFactory.

---

Medium Gaps

4. MCP config generation doesn't surface VCS provider

File: src/utils/mcp.ts

generateIssueManagementMcpConfig() only generates environment variables for issue providers. No awareness of the VCS provider at all. Even though the MCP server loads settings from the filesystem directly (so env vars aren't strictly needed for credentials), there's no signaling of which VCS provider is active.

5. No validation of provider combinations

There are no guard rails preventing confusing combos like Jira issues + BitBucket VCS. These combinations are technically valid (and should work once the gaps above are fixed), but edge cases should be documented.

---

Decided: Out of Scope

• Draft PR operations hardcoded to PRManager (GitHub) — BitBucket doesn't support Draft PRs. Acceptable for now.
• Init wizard doesn't configure VCS provider — Keep the wizard brief. Users can manually add versionControl.provider: "bitbucket" config. Document in docs instead.

---

Decisions

• GitHub Issues + BitBucket VCS combo: This should be supported. The separation between issue tracking and VCS is the right architecture. Most of the routing already works — the createPR() return type is the key blocker.
• Inline code review for BitBucket: Feasible since BitBucket API supports it. Needs new BitBucketApiClient methods + MCP routing.
• Documentation over wizard: Add VCS provider configuration docs to docs/iloom-commands.md rather than adding an init wizard step.

Implementation Plan

#	Gap	Effort	Impact
1	Fix createPR() return type → { url: string; number: number }	Small	Unblocks session summaries on BB PRs
2	Add inline comment methods to BitBucketApiClient	Medium	Enables review comments on BB PRs
3	Route get_review_comments through VCS provider	Medium	Agents can read BB review threads
4	Route update_comment(type:pr) through VCS provider	Small	Agents can reply to BB reviews
5	Add VCS provider configuration to docs	Small	Users know how to set up BB
6	Document supported provider combinations	Small	Clear expectations for mixed setups

[acreeger]

Architecture Investigation: VCS Provider Routing

• Q1: GitHub Issues + BitBucket VCS combination
• Q2: Inline code review MCP tools
• Q3: MCP server VCS routing
• Compile findings and post analysis

Executive Summary

The VCS provider gap analysis from the previous comment identified 8 gaps. After tracing all code paths, I found that several gaps have already been addressed in the current branch -- the MCP server already routes get_pr, create_comment(type:pr), and update_comment(type:pr) through BitBucket when configured. The remaining real gaps are: (1) createPR() returns URL-only which prevents the PR number from reaching SessionSummaryService, (2) get_review_comments and update_comment cannot work with BitBucket PRs, and (3) github-draft-pr mode is hardcoded to PRManager.

Questions and Key Decisions

Question	Answer
Can SessionSummaryService post to BitBucket PRs?	Partially. The service already routes through VCSProviderFactory when prNumber is provided (line 411-417). But finish.ts never passes prNumber for BitBucket because createPR() returns only a URL string. Fix createPR() return type and the summary will flow correctly.
Does the MCP server need env vars for BitBucket?	No. The MCP server loads settings via SettingsManager.loadSettings() at startup (line 1113-1114) and initializes bitBucketVCSProvider from settings (line 1119-1128). No BitBucket-specific env vars are needed.
Can agents update progress comments on BitBucket PRs?	No. update_comment explicitly throws for BitBucket PRs (line 540-544). BitBucket Cloud does support PUT for comments, but it is not implemented. This blocks the standard agent create+update comment workflow.
Does BitBucket support inline review comments via API?	Yes. POST to /pullrequests/{id}/comments with { inline: { from: lineNum, path: filePath } }. Not implemented in BitBucketApiClient.

HIGH/CRITICAL Risks

• Agent comment workflow broken for BitBucket PRs: The standard iloom agent pattern (create comment, then update it with progress) will fail on the update_comment call because the MCP server throws an explicit error. Agents working on BitBucket-hosted repos will lose the ability to track progress on the PR itself. The MCP server error message says "BitBucket does not support editing PR comments" but this is incorrect -- the BitBucket Cloud REST API does support PUT on comment endpoints.
• Session summaries silently post to issue instead of PR: When bitbucket-pr mode creates a PR, prNumber is undefined because createPR() returns only a URL. SessionSummaryService silently falls back to posting on the issue tracker's issue. No error is raised, so this will be confusing to users.

Impact Summary

• 1 interface change needed: VersionControlProvider.createPR() return type (affects 1 interface + 1 implementation)
• 1 file with incorrect error message: issue-management-server.ts line 540-544
• 1 API client needing new methods: BitBucketApiClient.ts (update comment, inline comments)
• Key decision: Whether to prioritize agent comment update support (high impact on agent workflow) or inline review comments (lower priority, not used in core workflows)

---

Complete Technical Reference (click to expand for implementation details)

Q1: GitHub Issues + BitBucket VCS Combination

How finish.ts handles PR creation

Three merge modes handle PRs differently:

1. github-pr mode (line 780-783): Calls executeVCSPRWorkflow(parsed, options, worktree, settings, null, result) with vcsProvider=null, which means PRManager (GitHub gh CLI) handles everything.

2. github-draft-pr mode (line 786-900): Entirely hardcoded to PRManager. Uses prManager.markPRReady() (line 866-868) and prManager.createDraftPR() (LoomManager.ts line 318). VCSProviderFactory is never consulted. The VersionControlProvider interface has optional createDraftPR() and markPRReadyForReview() methods, but they are never called from any code path.

3. bitbucket-pr mode (line 903-922): Creates VCS provider via VCSProviderFactory.create(settings) (line 911), validates it's BitBucket, then delegates to executeVCSPRWorkflow().

executeVCSPRWorkflow code path (line 1105-1255)

When vcsProvider is non-null (BitBucket):

• Line 1181: Calls vcsProvider.checkForExistingPR() for existing PR detection
• Line 1192-1198: Calls vcsProvider.createPR() which returns Promise<string> (URL only)
• Line 1199: Sets prNumber = undefined with comment "VCS providers return URL only; no number extracted"
• Line 1239-1244: Passes prNumber (undefined) to generateSessionSummaryIfConfigured()

The PRCreationResult interface is defined at VersionControlProvider.ts:9-13 with { url, number, wasExisting } but is not used by createPR(). The method signature at line 40-46 returns Promise<string>.

How SessionSummaryService posts comments

postSummaryToIssue() at SessionSummaryService.ts:399-437:

• When prNumber is provided (line 411-427): Calls VCSProviderFactory.create(settings). If it returns non-null (BitBucket configured), calls vcsProvider.createPRComment(prNumber, finalSummary, worktreePath). If null (GitHub), falls back to IssueManagementProviderFactory.create('github') with type: 'pr'.
• When prNumber is undefined (line 429-436): Uses issueManagement.provider setting to post on the issue.

Gap: Because finish.ts passes prNumber=undefined for BitBucket PRs, the summary always takes the "no prNumber" path and posts to the issue instead of the PR. The VCS provider routing code at line 411-417 is correct but never triggered.

How issues.ts lists PRs

IssuesCommand.execute() at issues.ts:188-255:

• Reads vcsProvider from settings.versionControl?.provider ?? 'github' (line 189)
• If bitbucket (line 191-225): Dynamically imports BitBucketVCSProvider, calls listPullRequests(), applies --mine filter via currentUser comparison
• If not bitbucket (line 226-255): Uses fetchGitHubPRList() from github.ts
• This correctly respects the VCS provider setting. No gap here.

Places assuming issue tracker === VCS provider

1. finish.ts github-draft-pr mode (line 786-900): Always uses PRManager (GitHub gh CLI). If someone configured github-draft-pr mode but BitBucket VCS (contradictory config), it would try to use gh pr ready on a BitBucket repo.
2. LoomManager.ts createDraftPR (line 234-329): Always uses PRManager. Same assumption as above.
3. mcp/types.ts comment at line 33: "PRs only exist on GitHub" in the GetPRInput interface doc.

Q2: Inline Code Review MCP Tools

get_review_comments tool

Defined at issue-management-server.ts:317-383:

• Description explicitly states: "PRs only exist on GitHub, so this tool always uses GitHub" (line 325)
• Handler at line 361: Always creates new GitHubIssueManagementProvider() directly -- no routing through VCS provider or BitBucket check
• Uses provider.getReviewComments() which calls gh api --paginate for GitHub REST API

BitBucket inline review comment capability

BitBucket Cloud REST API does support inline comments:

• Create: POST /repositories/{ws}/{repo}/pullrequests/{id}/comments with body:

  { "content": { "raw": "text" }, "inline": { "from": 6, "path": "style.css" } }

• List: GET on the same endpoint returns comments with inline property containing from, to, path fields
• Update: PUT /repositories/{ws}/{repo}/pullrequests/{id}/comments/{comment_id} (exists but not confirmed via official docs)

BitBucketApiClient.ts current capabilities

The API client has:

• addPRComment() (line 297-311): Creates general comments. Does not accept inline parameters.
• getPullRequest() (line 207-215): Gets PR details. Does not fetch comments.

Missing methods needed for review comment support:

• addInlineComment(workspace, repoSlug, prId, content, filePath, lineNumber) -- new method
• listPRComments(workspace, repoSlug, prId) -- new method to fetch comments including inline metadata
• updatePRComment(workspace, repoSlug, prId, commentId, content) -- new method

What would be needed to support BitBucket review comments in MCP

1. Add three methods to BitBucketApiClient: addInlineComment, listPRComments, updatePRComment
2. Add getReviewComments(prNumber), createReviewComment(prNumber, path, line, body), updatePRComment(prNumber, commentId, body) to BitBucketVCSProvider
3. Update get_review_comments tool in issue-management-server.ts to check bitBucketVCSProvider before falling through to GitHub
4. Add updatePRComment to VersionControlProvider interface

Q3: MCP Server VCS Routing

Current provider selection mechanism

The MCP server uses a dual-provider approach established in the current branch:

1. Issue provider (process.env.ISSUE_PROVIDER): Controls get_issue, get_comment, create_comment(type:issue), update_comment(type:issue), create_issue, etc. Set via env var from generateIssueManagementMcpConfig().

2. VCS provider (bitBucketVCSProvider module variable): Controls get_pr, create_comment(type:pr). Initialized from settings file (not env vars) at startup (issue-management-server.ts:1119-1128).

Env var configuration (src/utils/mcp.ts)

generateIssueManagementMcpConfig() (line 19-150) generates env vars:

• Always: ISSUE_PROVIDER
• GitHub: REPO_OWNER, REPO_NAME, GITHUB_API_URL, GITHUB_EVENT_NAME
• Linear: LINEAR_API_TOKEN, LINEAR_TEAM_KEY
• Jira: JIRA_HOST, JIRA_USERNAME, JIRA_API_TOKEN, JIRA_PROJECT_KEY

No BitBucket-specific env vars are generated. But this is not actually a gap -- the MCP server reads BitBucket config from SettingsManager.loadSettings() at line 1113-1114, which reads the settings JSON files from the filesystem. The MCP server process inherits the working directory and can find the settings files.

Tool routing table

Tool	Issue type routing	PR type routing
get_issue	ISSUE_PROVIDER env var	N/A
get_pr	N/A	bitBucketVCSProvider if set, else GitHubIssueManagementProvider
get_review_comments	N/A	Always GitHubIssueManagementProvider (hardcoded)
get_comment	ISSUE_PROVIDER env var	N/A
create_comment	ISSUE_PROVIDER for issue type	bitBucketVCSProvider for PR type if set, else 'github' hardcoded
update_comment	ISSUE_PROVIDER for issue type	Throws error if bitBucketVCSProvider set for PR type, else 'github' hardcoded

What would need to change for full VCS routing

The MCP server already has the basic routing structure in place. Remaining items:

1. Fix update_comment to support BitBucket PR comment updates (add PUT method to BitBucketApiClient)
2. Add get_review_comments routing through bitBucketVCSProvider (requires new listPRComments method with inline support)
3. The settings-based initialization approach works well -- no additional env vars needed

Affected Files

• /src/lib/VersionControlProvider.ts:40-46 -- createPR() method returns Promise<string>, should return Promise<PRCreationResult> (the interface is already defined at line 9-13 but unused)
• /src/lib/providers/bitbucket/BitBucketVCSProvider.ts:112-165 -- createPR() returns pr.links.html.href (string), has pr.id available at line 155 but discards it
• /src/commands/finish.ts:1192-1199 -- VCS provider path sets prNumber = undefined because createPR() returns string
• /src/mcp/issue-management-server.ts:539-545 -- update_comment throws for BitBucket PRs with incorrect claim that API doesn't support it
• /src/mcp/issue-management-server.ts:356-383 -- get_review_comments hardcoded to GitHub
• /src/lib/providers/bitbucket/BitBucketApiClient.ts -- Missing updatePRComment(), addInlineComment(), listPRComments() methods
• /src/mcp/types.ts:33 -- GetPRInput doc comment says "PRs only exist on GitHub" (stale)
• /src/lib/LoomManager.ts:234-329 -- Draft PR creation hardcoded to PRManager
• /src/commands/finish.ts:866-868 -- markPRReady() hardcoded to PRManager

Integration Points

• finish.ts calls SessionSummaryService.generateAndPostSummary() with prNumber from executeVCSPRWorkflow
• SessionSummaryService.postSummaryToIssue() calls VCSProviderFactory.create(settings) to decide BitBucket vs GitHub routing
• MCP issue-management-server.ts main() calls BitBucketVCSProvider.fromSettings(settings) to initialize the module-level bitBucketVCSProvider
• All MCP PR tool handlers check bitBucketVCSProvider truthiness to decide routing
• BitBucketVCSProvider delegates to BitBucketApiClient for all REST API calls

Medium Severity Risks

• Draft PR mode has no VCS provider abstraction: If a user configures github-draft-pr merge mode with BitBucket VCS, LoomManager will try to use gh pr CLI commands which will fail. There's no validation preventing this combination.
• MCP server settings resolution path: The MCP server calls loadSettings() without arguments (line 1114), which means it resolves settings from process.cwd(). If the MCP server's working directory differs from the loom worktree, it might load wrong settings or fail to find them.

[acreeger]

Code Review: GitHub Flow Verification

Ran 4 parallel review agents focused on verifying the default GitHub flow is preserved after the BitBucket integration + epic #842 merge mode refactoring + issue #861 MCP routing work.

Result: Ready to merge

All 4,634 tests pass across 138 test files. The default GitHub flow is fully preserved across:

• MCP server — All PR tools (get_pr, create_comment, update_comment, get_review_comments) use a consistent if (vcsProvider) guard. When no versionControl is configured, vcsProvider is null and everything falls through to GitHubIssueManagementProvider.
• finish.ts — Both pr and draft-pr modes fall through to the existing PRManager path when VCSProviderFactory.create() returns null. PR number extraction, session summary posting, and JSON mode validation all work correctly.
• SessionSummaryService / issues.ts / LoomManager — All use the same null-check pattern with correct fallbacks.
• Settings — versionControl section is fully optional. Old configs without it work fine. Merge mode transform is additive (bitbucket-pr → pr), existing modes unchanged.

Minor Findings (non-breaking, for future reference)

1. Dead code in finish.ts (lines 791-796) — Manual re-normalization of github-pr → pr and github-draft-pr → draft-pr is redundant since Zod's mergeModeTransform already handles this at loadSettings() time. Same issue at lines 228-230 with needsRepo computation. Harmless but misleading.

2. Missing moveIssueToReadyForReview in VCS provider path — The BitBucket code path in executeVCSPRWorkflow doesn't call issueTracker.moveIssueToReadyForReview() when creating a new PR, but the GitHub legacy path does. Not a GitHub regression, but a BitBucket gap worth addressing later.

3. Duplicate type definitions — PRCreationResult and ExistingPR are defined in both PRManager.ts (file-local) and VersionControlProvider.ts (exported). Structurally identical, no conflict, but could confuse future maintainers. Consider having PRManager import from VersionControlProvider instead.

4. Static import of BitBucket module in VCSProviderFactory — BitBucket code is loaded for all users at startup, even GitHub-only ones. Consistent with how Jira is handled, but worth noting for startup performance if the dependency tree grows.

---

Thanks @NoahCardoza for the excellent foundation on this PR! The BitBucket integration, security hygiene (token redaction), error handling patterns, and test coverage were all well done. The fromSettings() factory method pattern has been a clean abstraction that made the subsequent VCS provider routing work much easier to build on top of.

[NoahCardoza]

BitBucket doesn't support Draft PRs

I'm not sure if this is referring to Bitbucket as a service or our interface with Bitbucket. Bitbucket does support draft PR's, which is a rather new feature (released almost exactly a year ago), relative to GitHub at least.

I may be able to look into adding this functionality.