[codex] Structure GitHub CLI failures

[juliusmarminge]

Summary

• replace the free-form GitHub CLI error with distinct Schema error classes for unavailable, authentication, missing pull request, command, and response-decode failures
• classify process failures from structured VCS tags and failure kinds instead of parsing error messages
• preserve exact caller-facing guidance and the immediate cause chain through provider mapping

Validation

• vp test apps/server/src/sourceControl/GitHubCli.test.ts apps/server/src/sourceControl/GitHubSourceControlProvider.test.ts apps/server/src/git/GitManager.test.ts (75 tests)
• vp test apps/server/src/sourceControl/GitHubCli.test.ts apps/server/src/sourceControl/GitHubSourceControlProvider.test.ts (16 tests)
• vp check (20 pre-existing warnings)
• vp run typecheck

---

Note

Medium Risk
Touches GitHub CLI error handling used by git workflows and source-control provider mapping; behavior should stay the same for callers reading detail, but misclassification of spawn vs auth vs not-found could change surfaced messages.

Overview
Replaces the single free-form GitHubCliError with distinct Schema tagged errors (unavailable, authentication, PR not found, command failure, and JSON decode failures for PR lists, change requests, single PRs, and repositories). User-facing guidance now lives on each class’s detail getter; failures carry command, cwd, and cause instead of operation + detail strings.

Classification no longer inspects error message text. fromVcsError maps VcsProcessSpawnError (ChildProcess spawn NotFound only) to unavailable, and VcsProcessExitError with failureKind authentication / not-found to the matching types; everything else becomes GitHubCliCommandError. A new unit test asserts a missing cwd (FileSystem NotFound) is not treated as a missing gh binary.

Call sites and tests use GitHubCliError as a union type, isGitHubCliError, and the specific error classes. GitHubSourceControlProvider maps any failure to SourceControlProviderError via Effect.mapError using error.detail, and emits GitHubChangeRequestListDecodeError for bad non-open list JSON. GitManager fakes and integration tests were updated to the new shapes (e.g. GitHubCliUnavailableError / GitHubCliAuthenticationError).

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

Note

Replace string-matched GitHub CLI errors with structured error classes in GitHubCli

• Introduces dedicated tagged error classes in GitHubCli.ts: GitHubCliUnavailableError, GitHubCliAuthenticationError, GitHubPullRequestNotFoundError, GitHubCliCommandError, and decode-specific errors for PR lists, single PRs, repositories, and change requests.
• Replaces string-inspection-based error classification with a structured fromVcsError mapper that uses VcsError data (spawn NotFound, exit failureKind) to select the appropriate error class.
• Exports a GitHubCliError union type and isGitHubCliError type guard so callers can identify GitHub CLI errors without inspecting raw error shapes.
• Updates GitHubSourceControlProvider to map any error into SourceControlProviderError via a single Effect.mapError, removing the previous Effect.catchTags on the old GitHubCliError.

^{Macroscope summarized 81dd825.}

[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: 8a25047d-228a-4fba-b1f3-12baaefb8065

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/structure-github-cli-errors

---

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

[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: Spawn failures misreported unavailable
  • Added an isEnoentCause check so only ENOENT spawn failures map to GitHubCliUnavailableError; other spawn failures (EACCES, etc.) now correctly fall through to GitHubCliCommandError.

Or push these changes by commenting:

@cursor push 05040000e0

Preview (05040000e0)

diff --git a/apps/server/src/sourceControl/GitHubCli.ts b/apps/server/src/sourceControl/GitHubCli.ts
--- a/apps/server/src/sourceControl/GitHubCli.ts
+++ b/apps/server/src/sourceControl/GitHubCli.ts
@@ -161,6 +161,14 @@
 
 export const isGitHubCliError = Schema.is(GitHubCliError);
 
+function isEnoentCause(cause: unknown): boolean {
+  if (typeof cause === "object" && cause !== null && "code" in cause) {
+    return (cause as { code: unknown }).code === "ENOENT";
+  }
+  const text = String(cause).toLowerCase();
+  return text.includes("enoent") || text.includes("command not found");
+}
+
 export function fromVcsError(
   context: {
     readonly operation: "execute";
@@ -170,7 +178,10 @@
   error: VcsError,
 ): GitHubCliError {
   if (error._tag === "VcsProcessSpawnError") {
-    return new GitHubCliUnavailableError({ ...context, cause: error });
+    if (isEnoentCause(error.cause)) {
+      return new GitHubCliUnavailableError({ ...context, cause: error });
+    }
+    return new GitHubCliCommandError({ ...context, cause: error });
   }
 
   if (error._tag === "VcsProcessExitError") {

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

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

[macroscopeapp]

Effect Service Conventions — one finding on the new GitHubCli error model. The split into distinct tagged errors, the required cause, the Schema.Union + Schema.is predicate, and message-from-attributes are all good; the only issue is a redundant single-value operation discriminator carried alongside each distinct tag.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors GitHub CLI error handling by replacing a generic error class with specialized typed error classes. The changes are mechanical restructuring of error classification with comprehensive test updates, maintaining the same user-facing error messages.

No code changes detected at 81dd825. Prior analysis still applies.

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