fix(#264) : Enhance error handling and testing for branch creation failures

[haddybhaiya]

closes #264
This pull request improves the reliability and clarity of branch creation in the CLI by better handling ambiguous failures, especially around gateway errors, and by enhancing error reporting. The logic for "adopting" a branch after an ambiguous failure is now more robust, and error messages now carry more detail for debugging.

Branch creation reliability improvements:

• The adoption logic after a failed branch creation now includes not only transport (network) failures but also ambiguous gateway failures (HTTP 502, 503, 504). This reduces the chance of reporting a failure when the branch was actually created. (src/commands/branch/create.ts, [1] [2] [3] [4]
• Added a test to ensure that the CLI correctly adopts a branch if it was created despite receiving a 502 error response. (src/commands/branch/create.test.ts, src/commands/branch/create.test.tsR434-R467)

Error reporting enhancements:

• The CLIError thrown on failed API responses now includes the HTTP status code as a property, and the error message is more descriptive, including both error and message fields if present. (src/lib/api/platform.ts, [1] [2]

Summary by CodeRabbit

• Bug Fixes
  • Improved branch creation recovery after temporary gateway or transport failures by adopting matching in-progress branches instead of reporting failure.
  • Enhanced API error messages with clearer server-provided details and HTTP status information.
• Documentation
  • Clarified which failures support branch recovery and documented safeguards for timestamps, modes, and failure states.
• Tests
  • Added coverage for recovering from a gateway error during branch creation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a282e1f3-024c-481f-959a-47a2e317502f

📥 Commits

Reviewing files that changed from the base of the PR and between 58ae921 and 4a7e614.

📒 Files selected for processing (3)

• src/commands/branch/create.test.ts
• src/commands/branch/create.ts
• src/lib/api/platform.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/commands/branch/create.test.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

The change adds API message text to post-refresh HTTP errors, classifies gateway failures as ambiguous branch-creation outcomes, and adopts matching branches after HTTP 502, 503, or 504 responses. A test covers adoption after a 502 response.

Changes

Branch creation recovery

Layer / File(s)	Summary
Preserve HTTP failure details src/lib/api/platform.ts	platformFetch combines API error and message text while retaining HTTP status and exit-code behavior.
Classify and adopt ambiguous failures src/commands/branch/create.ts, src/commands/branch/create.test.ts	Branch creation allows adoption for tagged transport failures and HTTP 502–504 responses. The test verifies adoption after a 502 response.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 4a7e6

The PR improves branch-creation failure handling and error reporting with localized code and test changes; no actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: jwfing, fermionic-lyu

Poem

A rabbit saw a gateway fall,
Then found the branch beyond the wall.
Status clues now mark the way,
Matching branches hop to stay.
Clearer errors greet us all.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the branch creation error-handling and testing changes.
Linked Issues check	✅ Passed	The changes address ambiguous 502 recovery, status-aware CLIError reporting, adoption testing, and preservation of duplicate-name safeguards for issue #264.
Out of Scope Changes check	✅ Passed	The test, documentation, and API error-reporting changes are directly related to the linked issue objectives.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[greptile-apps]

Greptile Summary

The PR improves recovery when branch creation returns an ambiguous gateway error and enriches shared Platform API errors with HTTP status and server-provided details.

• Treats HTTP 502, 503, and 504 responses as eligible for guarded branch adoption.
• Preserves status codes and combines error and message fields in Platform API failures.
• Adds coverage for successful adoption after a 502 response.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the eligible follow-up-review scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/commands/branch/create.ts	Expands guarded branch adoption to ambiguous gateway statuses while preserving name, mode, and timestamp matching.
src/lib/api/platform.ts	Enriches both normal and post-refresh HTTP failures with status codes and combined server error details.
src/commands/branch/create.test.ts	Adds regression coverage showing that a matching branch is adopted after an HTTP 502 response.

Sequence Diagram

sequenceDiagram
    participant CLI
    participant Platform as Platform API
    CLI->>Platform: Create branch
    Platform-->>CLI: Transport error or 502/503/504
    CLI->>Platform: List branches
    Platform-->>CLI: Existing branches
    alt Same name, mode, and recent timestamp
        CLI->>CLI: Adopt matching branch
        CLI->>Platform: Poll until ready
    else No matching branch
        CLI->>CLI: Rethrow original error
    end

Loading

_{Reviews (2): Last reviewed commit: "Merge branch 'main' into main" | Re-trigger Greptile}

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}

[jwfing]

@haddybhaiya could you please resolve the conflicts first?

[haddybhaiya]

@haddybhaiya could you please resolve the conflicts first?

Done @jwfing , thanks for mentioning !