fix(gitlab): name the cause of a failed glab command

packages/source-control-gitlab/src/server/GitLabCli.test.ts

@@ -3,7 +3,7 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import { ChildProcessSpawner } from "effect/process";
 
-import { VcsProcessExitError } from "@t3tools/contracts";
+import { VcsProcessExitError, VcsProcessTimeoutError } from "@t3tools/contracts";
 
 import type * as SourceControlHost from "@t3tools/source-control-core/server/SourceControlHost";
 import * as TestSourceControlHost from "@t3tools/source-control-testing/TestSourceControlHost";
@@ -182,7 +182,7 @@ layer("GitLabCli.layer", (it) => {
     }),
   );
 
-  it.effect("keeps non-merge-request not-found failures generic", () =>
+  it.effect("names non-merge-request not-found failures without claiming a missing MR", () =>
     Effect.gen(function* () {
       const cause = new VcsProcessExitError({
         operation: "GitLabCli.execute",
@@ -202,8 +202,10 @@ layer("GitLabCli.layer", (it) => {
         });
       }).pipe(Effect.flip);
 
-      assert.strictEqual(error._tag, "GitLabCliCommandError");
       assert.strictEqual(error.cause, cause);
+      assert.strictEqual(error.detail, "GitLab CLI command failed (not-found).");
+      assert(error._tag === "GitLabCliCommandError");
+      assert.strictEqual(error.reason, "not-found");
     }),
   );
 
@@ -228,4 +230,82 @@ layer("GitLabCli.layer", (it) => {
       assert.strictEqual(error.cause, cause);
     }),
   );
+
+  it.effect("names a not-found exit in a failed command's detail", () =>
+    Effect.gen(function* () {
+      const cause = new VcsProcessExitError({
+        operation: "GitLabCli.execute",
+        command: "glab",
+        cwd: "/repo",
+        exitCode: 1,
+        detail: "Merge request not found.",
+        failureKind: "not-found",
+      });
+      mockedRun.mockReturnValueOnce(Effect.fail(cause));
+
+      const glab = yield* GitLabCli.GitLabCli;
+      const error = yield* glab
+        .listMergeRequests({ cwd: "/repo", headSelector: "main", state: "open" })
+        .pipe(Effect.flip);
+
+      assert.strictEqual(error.cause, cause);
+      assert.strictEqual(error.detail, "GitLab CLI command failed (not-found).");
+      assert(error._tag === "GitLabCliCommandError");
+      assert.strictEqual(error.reason, "not-found");
+      assert.notInclude(error.message, "Merge request not found.");
+    }),
+  );
+
+  it.effect("names recognized failure classes and leaves unclassified exits generic", () =>
+    Effect.gen(function* () {
+      const timeoutCause = new VcsProcessTimeoutError({
+        operation: "GitLabCli.execute",
+        command: "glab",
+        cwd: "/repo",
+        timeoutMs: 30_000,
+      });
+      const exitCause = new VcsProcessExitError({
+        operation: "GitLabCli.execute",
+        command: "glab",
+        cwd: "/repo",
+        exitCode: 1,
+        detail: "Process exited with a non-zero status.",
+        failureKind: "command-failed",
+      });
+      // The boundary always sets failureKind; an absent one is a schema-optional
+      // fallback that must still stay generic.
+      const unclassifiedCause = new VcsProcessExitError({
+        operation: "GitLabCli.execute",
+        command: "glab",
+        cwd: "/repo",
+        exitCode: 1,
+        detail: "Process exited with a non-zero status.",
+      });
+      mockedRun
+        .mockReturnValueOnce(Effect.fail(timeoutCause))
+        .mockReturnValueOnce(Effect.fail(exitCause))
+        .mockReturnValueOnce(Effect.fail(unclassifiedCause));
+
+      const glab = yield* GitLabCli.GitLabCli;
+      const timedOut = yield* glab
+        .execute({ cwd: "/repo", args: ["api", "projects"] })
+        .pipe(Effect.flip);
+      const failed = yield* glab
+        .execute({ cwd: "/repo", args: ["api", "projects"] })
+        .pipe(Effect.flip);
+      const unclassified = yield* glab
+        .execute({ cwd: "/repo", args: ["api", "projects"] })
+        .pipe(Effect.flip);
+
+      assert.strictEqual(timedOut.detail, "GitLab CLI command failed (timed-out).");
+      assert(timedOut._tag === "GitLabCliCommandError");
+      assert.strictEqual(timedOut.reason, "timed-out");
+      assert.strictEqual(failed.detail, "GitLab CLI command failed.");
+      assert(failed._tag === "GitLabCliCommandError");
+      assert.strictEqual(failed.reason, undefined);
+      assert.strictEqual(unclassified.detail, "GitLab CLI command failed.");
+      assert(unclassified._tag === "GitLabCliCommandError");
+      assert.strictEqual(unclassified.reason, undefined);
+    }),
+  );
 });

packages/source-control-gitlab/src/server/GitLabCli.ts

@@ -8,6 +8,7 @@ import * as Schema from "effect/Schema";
 import type * as DateTime from "effect/DateTime";
 
 import {
+  ForwardCompatibleOptional,
   TrimmedNonEmptyString,
   type SourceControlRepositoryVisibility,
   type VcsError,
@@ -114,12 +115,31 @@ export class GitLabMergeRequestNotFoundError extends Schema.TaggedError<GitLabMe
   }
 }
 
+// The process boundary classifies glab's stderr into these tags and discards
+// the raw text, so only a tag can reach detail and message. Unclassified exits
+// stay generic rather than claim a cause that was never recognized.
+export const GitLabCliCommandFailureReason = Schema.Literals([
+  "not-found",
+  "timed-out",
+  "stdin-write-failed",
+  "output-read-failed",
+  "output-limit-exceeded",
+  "missing-exit-code",
+  "repository-detection-failed",
+  "unsupported-operation",
+]);
+export type GitLabCliCommandFailureReason = typeof GitLabCliCommandFailureReason.Type;
+
 export class GitLabCliCommandError extends Schema.TaggedError<GitLabCliCommandError>()(
   "GitLabCliCommandError",
-  gitLabCliExecutionErrorContext,
+  {
+    ...gitLabCliExecutionErrorContext,
+    reason: ForwardCompatibleOptional(GitLabCliCommandFailureReason),
+  },
 ) {
   get detail(): string {
-    return "GitLab CLI command failed.";
+    const reason = this.reason === undefined ? "" : ` (${this.reason})`;
+    return `GitLab CLI command failed${reason}.`;
   }
 
   override get message(): string {
@@ -143,18 +163,26 @@ export class GitLabCliCommandError extends Schema.TaggedError<GitLabCliCommandEr
           case "rate-limited":
             return new GitLabCliRateLimitError({ ...context, cause });
           case "not-found":
+            return new GitLabCliCommandError({ ...context, cause, reason: "not-found" });
           case "command-failed":
           case undefined:
             return new GitLabCliCommandError({ ...context, cause });
         }
       },
-      VcsProcessTimeoutError: (cause) => new GitLabCliCommandError({ ...context, cause }),
-      VcsProcessStdinWriteError: (cause) => new GitLabCliCommandError({ ...context, cause }),
-      VcsProcessOutputReadError: (cause) => new GitLabCliCommandError({ ...context, cause }),
-      VcsProcessOutputLimitError: (cause) => new GitLabCliCommandError({ ...context, cause }),
-      VcsProcessMissingExitCodeError: (cause) => new GitLabCliCommandError({ ...context, cause }),
-      VcsRepositoryDetectionError: (cause) => new GitLabCliCommandError({ ...context, cause }),
-      VcsUnsupportedOperationError: (cause) => new GitLabCliCommandError({ ...context, cause }),
+      VcsProcessTimeoutError: (cause) =>
+        new GitLabCliCommandError({ ...context, cause, reason: "timed-out" }),
+      VcsProcessStdinWriteError: (cause) =>
+        new GitLabCliCommandError({ ...context, cause, reason: "stdin-write-failed" }),
+      VcsProcessOutputReadError: (cause) =>
+        new GitLabCliCommandError({ ...context, cause, reason: "output-read-failed" }),
+      VcsProcessOutputLimitError: (cause) =>
+        new GitLabCliCommandError({ ...context, cause, reason: "output-limit-exceeded" }),
+      VcsProcessMissingExitCodeError: (cause) =>
+        new GitLabCliCommandError({ ...context, cause, reason: "missing-exit-code" }),
+      VcsRepositoryDetectionError: (cause) =>
+        new GitLabCliCommandError({ ...context, cause, reason: "repository-detection-failed" }),
+      VcsUnsupportedOperationError: (cause) =>
+        new GitLabCliCommandError({ ...context, cause, reason: "unsupported-operation" }),
     });
   }
 }