feat(tools/bitbucket): add initial Bitbucket bridge

[KatalKavya96]

Summary

• Adds an initial tools/bitbucket bridge for Bitbucket Cloud and Bitbucket Data Center so Magpie can start supporting Bitbucket-backed forge/change-request workflows.
• Implements read-only repository metadata, open pull request listing, single pull request fetching, and Cloud/Data Center response normalization behind one CLI surface.
• Updates capability/vendor-neutrality docs and workspace membership so the new bridge is included in validation, workspace checks, and CI coverage.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other:

Test plan

• prek run --all-files passes
• For Python packages touched: uv run pytest / ruff check / mypy passes
• For Groovy bridges touched: command-line invocation tested end-to-end
• For skill changes: eval suite passes for the affected skill
  (PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/evals/<skill>/)
• For skill behaviour changes: a new or updated eval fixture is included in this PR
  (a regression test for the bug fixed / the behaviour added — see CONTRIBUTING.md)
• Other: verified targeted Bitbucket tests with PYTHONPATH=src uv run pytest tests/test_bitbucket.py

RFC-AI-0004 compliance

• HITL — any new mutation is gated on explicit user confirmation
• Sandbox — no new unrestricted host access; network reach declared in the adapter
• Vendor neutrality — placeholders (<PROJECT>, <tracker>, <upstream>, <security-list>) used in all skill / tool prose (the check-placeholders prek hook is the mechanical gate)
• Conversational + correctable — agentic-override path documented if behaviour is adopter-tunable
• Write-access discipline — no autonomous outbound messages; drafts only, sent on confirmation
• Privacy LLM — private content does not reach a non-approved LLM; redactor invoked where needed

Linked issues

Refs #606

Notes for reviewers (optional)

This PR intentionally keeps the Bitbucket bridge read-only. It establishes the package structure, CLI, config/auth handling, Cloud/Data Center API split, normalization layer, tests, workspace registration, and docs updates.

Follow-up PRs can extend this bridge with Bitbucket Issues, linked Jira handoff, PR comment/review/approve/decline/merge operations, branch permissions, and Pipelines status reads.

[KatalKavya96]

@potiuk , I have opened an initial PR for the Bitbucket bridge.

This PR keeps the scope intentionally read-only and focuses on the foundation: tools/bitbucket package setup, Cloud/Data Center API split, auth/config handling, repository metadata fetch, open PR listing, single PR fetch, normalised output, tests, and docs/workspace registration.

Could you please specifically check whether:

1. The first PR scope is appropriate for feat(tools/bitbucket): Bitbucket forge + tracker bridge (Atlassian) #606.
2. The declared capabilities contract:tracker + contract:change-request are correct, without adding contract:source-control yet.
3. The Cloud/Data Center abstraction and normalized output shape look aligned with Magpie’s tool patterns.
4. The follow-up boundaries for Jira handoff, issue writes, PR review/merge actions, branch permissions, and Pipelines status make sense.

I kept write operations out of this PR so the bridge stays safe and reviewable as a starting point. Thanks!

[KatalKavya96]

Hi @potiuk I ran the Magpie review skill locally and addressed the main feedback before pushing the latest changes.

I clarified the Bitbucket bridge scope as an initial read-only foundation rather than a complete tracker/change-request backend, added safer HTTP handling, pagination for Bitbucket Cloud and Data Center PR listing, clearer normalized read-only capability metadata, sandbox/egress allowlist updates, and aligned the docs across the adapter registry, capability list, vendor-neutrality page, and spec-loop adapter spec.

• One design point I wanted to confirm before making the next update: the local Magpie/Codex review suggested avoiding a new capability like contract:change-request-read, and instead keeping Bitbucket under contract:change-request with a separate Coverage: partial-read-only profile.

• The idea is that partial adapters can implement named contract verbs, but should not be advertised as complete/selectable backends or counted as “working backends” in vendor-neutrality scoring. For this PR, Bitbucket would support repository metadata, open PR listing, and metadata-only PR fetching, while contract:tracker stays absent until issue operations or Jira handoff coverage exists.

• Does this partial-adapter profile sound acceptable for Magpie, or would you prefer that this initial Bitbucket bridge avoid claiming contract:change-request until the complete contract is implemented?

prek run --all-files is passing now. This PR references #606 as partial progress, while keeping deeper Jira handoff, issue operations, review/merge writes, branch permissions, and Pipelines coverage open for follow-up work.

[potiuk]

Very nice!

[potiuk]

Really nice first cut of a Bitbucket bridge — strong security posture (HTTPS enforced via _require_https; the NoAuthRedirectHandler that stops Authorization leaking across a redirect; every URL path segment quote(..., safe="")-escaped; no subprocess/SQL), deterministic output (json.dumps(sort_keys=True)), Apache headers on every file, and genuinely good test coverage (URL construction, Cloud next + DC nextPageStart pagination, auth-scheme validation, normalization, CLI dispatch for both backends). Registry sync is complete (labels doc, workspace member, adapter/spec docs, egress + sandbox allowlists).

Heads-up: a maintainer (me) rebased this onto current main and force-pushed — it was behind the commits that landed today. As part of the rebase I regenerated uv.lock to a minimal, bitbucket-only add: the branch's lockfile had drifted — it dropped the [options] exclude-newer-span = "P7D" cooldown block and bumped ~9 unrelated deps. The regenerated lock preserves the 7-day cooldown (per AGENTS.md → Local setup) and touches nothing but the magpie-bitbucket member. I also approved the workflow run, so CI is now green (37/37). Please pull the rebased branch before pushing further so the drift doesn't come back.

Two things to sort before this can merge:

1. Capability label vs. what the tool implements. The README declares **Capability:** contract:change-request, but also says it is "not a complete contract:change-request backend yet", and normalize.py labels output partial-change-request. It also reads repository metadata (a contract:source-control surface) without declaring that contract. Could you confirm contract:change-request is the intended "foundation" label for an admittedly-partial backend — the honest partial framing is fine if that's the call — and add contract:source-control if the repo-metadata reads are meant to be a supported surface?

2. Where does the token persistently live? Auth arrives via BITBUCKET_TOKEN / BITBUCKET_CLOUD_USER env vars injected by the caller (good — nothing is committed in-tree), but AGENTS.md → Local setup requires persistent tokens to live under ~/.config/apache-magpie/<tool>. Add a one-line pointer in the README's Configuration section so adopters don't stash it in the project tree.

Happy to re-review once those are addressed.

[KatalKavya96]

Really nice first cut of a Bitbucket bridge — strong security posture (HTTPS enforced via _require_https; the NoAuthRedirectHandler that stops Authorization leaking across a redirect; every URL path segment quote(..., safe="")-escaped; no subprocess/SQL), deterministic output (json.dumps(sort_keys=True)), Apache headers on every file, and genuinely good test coverage (URL construction, Cloud next + DC nextPageStart pagination, auth-scheme validation, normalization, CLI dispatch for both backends). Registry sync is complete (labels doc, workspace member, adapter/spec docs, egress + sandbox allowlists).

Heads-up: a maintainer (me) rebased this onto current main and force-pushed — it was behind the commits that landed today. As part of the rebase I regenerated uv.lock to a minimal, bitbucket-only add: the branch's lockfile had drifted — it dropped the [options] exclude-newer-span = "P7D" cooldown block and bumped ~9 unrelated deps. The regenerated lock preserves the 7-day cooldown (per AGENTS.md → Local setup) and touches nothing but the magpie-bitbucket member. I also approved the workflow run, so CI is now green (37/37). Please pull the rebased branch before pushing further so the drift doesn't come back.

Two things to sort before this can merge:

1. Capability label vs. what the tool implements. The README declares **Capability:** contract:change-request, but also says it is "not a complete contract:change-request backend yet", and normalize.py labels output partial-change-request. It also reads repository metadata (a contract:source-control surface) without declaring that contract. Could you confirm contract:change-request is the intended "foundation" label for an admittedly-partial backend — the honest partial framing is fine if that's the call — and add contract:source-control if the repo-metadata reads are meant to be a supported surface?
2. Where does the token persistently live? Auth arrives via BITBUCKET_TOKEN / BITBUCKET_CLOUD_USER env vars injected by the caller (good — nothing is committed in-tree), but AGENTS.md → Local setup requires persistent tokens to live under ~/.config/apache-magpie/<tool>. Add a one-line pointer in the README's Configuration section so adopters don't stash it in the project tree.

Happy to re-review once those are addressed.

@potiuk Addressed in #748, Please review Thanks!