[codex] Structure Bitbucket API errors

[juliusmarminge]

Summary

• replace the free-form BitbucketApiError.detail bucket with distinct Schema error classes for transport, HTTP response, body-read, decode, repository resolution, locator, body-file, and checkout failures
• expose the union and its Schema.is predicate so checkout preserves already-structured Bitbucket failures by tag
• retain the existing user-facing messages while attaching operation-specific context, HTTP status/body diagnostics, and immediate causes
• update the existing Bitbucket API and provider tests with focused coverage for response diagnostics, body-read cause chains, and checkout tag preservation

Validation

• vp test run apps/server/src/sourceControl/BitbucketApi.test.ts apps/server/src/sourceControl/BitbucketSourceControlProvider.test.ts
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

---

Note

Medium Risk
Changes error shapes and HTTP failure messaging (no embedded API bodies); callers matching on detail or the old single class need updates, but user-facing messages stay stable and leakage risk is reduced.

Overview
Replaces the monolithic BitbucketApiError (with free-form detail) with tagged Schema error classes and a BitbucketApiError union plus isBitbucketApiError for narrowing.

Failures are split by kind: transport (BitbucketRequestError), HTTP status (BitbucketResponseError with responseBodyLength only—no response body text in messages or fields), body read (BitbucketResponseBodyReadError), JSON decode, repository resolution/locator, PR body file read, and checkout (BitbucketCheckoutError with cwd/reference). checkoutPullRequest re-throws existing union members via isBitbucketApiError instead of re-wrapping.

Tests assert specific error classes, redaction of secrets from diagnostics, body-read cause chains, and provider-layer cause preservation without leaking upstream messages.

^{Reviewed by Cursor Bugbot for commit d0ebe0d. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace generic Bitbucket API errors with typed error classes

• Introduces specific tagged error classes (BitbucketRequestError, BitbucketResponseError, BitbucketResponseBodyReadError, BitbucketResponseDecodeError, BitbucketCheckoutError, BitbucketRepositoryLocatorError, etc.) replacing the previous single BitbucketApiError class in BitbucketApi.ts.
• Each error class captures structured context (e.g. operation, status, responseBodyLength, cwd, reference) rather than freeform detail strings.
• Non-2xx response bodies are no longer included in error objects; only the body length is recorded, preventing sensitive content from leaking into diagnostics.
• BitbucketApiError is now a Schema.Union of all specific error types with an exported isBitbucketApiError predicate.
• Behavioral Change: callers that previously matched on BitbucketApiError with detail/operation fields must migrate to the new specific error types and their respective fields.

^{Macroscope summarized d0ebe0d.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: e489e8ca-112d-4ca5-86c3-7adb9d4c51f7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structural-bitbucket-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Effect service review: one convention issue, recurring across six new error classes in apps/server/src/sourceControl/BitbucketApi.ts.

The split from the generic BitbucketApiError into tagged classes is the right direction. The problem is that six of the new classes encode the same distinction twice — a specific error tag plus a single-value operation literal — which the conventions disallow. The fix is to drop the redundant operation field from those classes (inlining the constant operation name in each message getter) while keeping operation only on the shared multi-operation errors (BitbucketRequestError, BitbucketResponseError, BitbucketResponseBodyReadError, BitbucketResponseDecodeError).

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Approved

Refactor that replaces a generic BitbucketApiError with multiple specific error classes for better error handling granularity. Changes are internal to error structure with comprehensive test coverage and include a security improvement by excluding response bodies from error messages.

^{You can customize Macroscope's approvability policy. Learn more.}

Dismissing prior approval to re-evaluate ecba319

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Raw response body in message
  • Added a 512-character truncation limit to the HTTP response body in the responseError() function before storing it in BitbucketResponseError, preventing sensitive data exposure and excessively large error payloads.

Or push these changes by commenting:

@cursor push 482367cda8

Preview (482367cda8)

diff --git a/apps/server/src/sourceControl/BitbucketApi.ts b/apps/server/src/sourceControl/BitbucketApi.ts
--- a/apps/server/src/sourceControl/BitbucketApi.ts
+++ b/apps/server/src/sourceControl/BitbucketApi.ts
@@ -27,6 +27,8 @@
 
 const DEFAULT_API_BASE_URL = "https://api.bitbucket.org/2.0";
 
+const MAX_RESPONSE_BODY_LENGTH = 512;
+
 const BitbucketApiEnvConfig = Config.all({
   baseUrl: Config.string("T3CODE_BITBUCKET_API_BASE_URL").pipe(
     Config.withDefault(DEFAULT_API_BASE_URL),
@@ -488,15 +490,20 @@
           cause,
         }),
     ),
-    Effect.flatMap((body) =>
-      Effect.fail(
+    Effect.flatMap((body) => {
+      const trimmed = body.trim();
+      const bounded =
+        trimmed.length > MAX_RESPONSE_BODY_LENGTH
+          ? `${trimmed.slice(0, MAX_RESPONSE_BODY_LENGTH)}…`
+          : trimmed;
+      return Effect.fail(
         new BitbucketResponseError({
           operation,
           status: response.status,
-          responseBody: body,
+          responseBody: bounded,
         }),
-      ),
-    ),
+      );
+    }),
   );
 }

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit bbb7b63. Configure here.}

Dismissing prior approval to re-evaluate d0ebe0d