authorgravatar for julius0216@outlook.comJulius Marminge <julius0216@outlook.com> 2026-06-20 18:58:19-07:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2026-06-20 18:58:19-07:00
logd389cfd4e39ec1b76a6898a04d1b90190155b618
tree4397b89d13ba6ec9adc090e707a116d8c92b3622
parent6fc79737c3854344d05c1ac3d0dd10e143a19fa9
signature Signed by PGP key B5690EEEBB952194

[codex] Structure Azure DevOps CLI failures (#3460)

Co-authored-by: codex <codex@users.noreply.github.com>

3 files changed, 222 insertions(+), 86 deletions(-)

apps/server/src/sourceControl/AzureDevOpsCli.test.ts+54-1
......@@ -4,8 +4,9 @@ import * as Effect from "effect/Effect";
44import * as FileSystem from "effect/FileSystem";
55import * as Layer from "effect/Layer";
66import * as Option from "effect/Option";
7import * as PlatformError from "effect/PlatformError";
78import { ChildProcessSpawner } from "effect/unstable/process";
8import { VcsProcessExitError } from "@t3tools/contracts";
9import { VcsProcessExitError, VcsProcessSpawnError } from "@t3tools/contracts";
910
1011import * as VcsProcess from "../vcs/VcsProcess.ts";
1112import * as AzureDevOpsCli from "./AzureDevOpsCli.ts";
......@@ -345,11 +346,63 @@ describe("AzureDevOpsCli.layer", () => {
345346 const az = yield* AzureDevOpsCli.AzureDevOpsCli;
346347 const error = yield* az.execute({ cwd: "/repo", args: ["repos", "list"] }).pipe(Effect.flip);
347348
349 assert.instanceOf(error, AzureDevOpsCli.AzureDevOpsCommandFailedError);
350 assert.strictEqual(error.operation, "execute");
348351 assert.strictEqual(error.command, "az");
349352 assert.strictEqual(error.cwd, "/repo");
353 assert.strictEqual(error.argumentCount, 2);
350354 assert.strictEqual(error.detail, "Azure DevOps CLI command failed.");
351355 assert.strictEqual(error.cause, cause);
352356 assert.equal(error.message.includes("sensitive-upstream-detail"), false);
353357 }).pipe(Effect.provide(layer)),
354358 );
359
360 it.effect("does not report a missing working directory as a missing Azure CLI", () =>
361 Effect.gen(function* () {
362 const cwd = "/missing/repo";
363 const platformCause = PlatformError.systemError({
364 _tag: "NotFound",
365 module: "ChildProcess",
366 method: "spawn",
367 syscall: "chdir",
368 pathOrDescriptor: cwd,
369 });
370 const cause = new VcsProcessSpawnError({
371 operation: "AzureDevOpsCli.execute",
372 command: "az",
373 cwd,
374 argumentCount: 2,
375 cause: platformCause,
376 });
377 mockRun.mockReturnValueOnce(Effect.fail(cause));
378
379 const az = yield* AzureDevOpsCli.AzureDevOpsCli;
380 const error = yield* az.execute({ cwd, args: ["repos", "list"] }).pipe(Effect.flip);
381
382 assert.instanceOf(error, AzureDevOpsCli.AzureDevOpsCommandFailedError);
383 assert.strictEqual(error.cwd, cwd);
384 assert.strictEqual(error.cause, cause);
385 }).pipe(Effect.provide(layer)),
386 );
387
388 it.effect("keeps invalid pull request output diagnostics structured", () =>
389 Effect.gen(function* () {
390 mockRun.mockReturnValueOnce(Effect.succeed(processOutput("not-json")));
391
392 const az = yield* AzureDevOpsCli.AzureDevOpsCli;
393 const error = yield* az.getPullRequest({ cwd: "/repo", reference: "42" }).pipe(Effect.flip);
394
395 assert.instanceOf(error, AzureDevOpsCli.AzureDevOpsPullRequestDecodeError);
396 assert.strictEqual(error.operation, "getPullRequest");
397 assert.strictEqual(error.command, "az");
398 assert.strictEqual(error.cwd, "/repo");
399 assert.strictEqual(error.outputLength, 8);
400 assert.strictEqual(error.detail, "Azure DevOps CLI returned invalid pull request JSON.");
401 assert.exists(error.cause);
402 assert.strictEqual(
403 error.message,
404 "Azure DevOps CLI failed in getPullRequest: Azure DevOps CLI returned invalid pull request JSON.",
405 );
406 }).pipe(Effect.provide(layer)),
407 );
355408});
apps/server/src/sourceControl/AzureDevOpsCli.ts+166-83
......@@ -1,9 +1,11 @@
11import * as Context from "effect/Context";
22import * as Effect from "effect/Effect";
33import * as Layer from "effect/Layer";
4import * as PlatformError from "effect/PlatformError";
45import * as Result from "effect/Result";
56import * as Schema from "effect/Schema";
67import {
8 NonNegativeInt,
79 TrimmedNonEmptyString,
810 type SourceControlRepositoryVisibility,
911 type VcsError,
......@@ -19,16 +21,61 @@ import * as SourceControlProvider from "./SourceControlProvider.ts";
1921
2022const DEFAULT_TIMEOUT_MS = 30_000;
2123
22export class AzureDevOpsCliError extends Schema.TaggedErrorClass<AzureDevOpsCliError>()(
23 "AzureDevOpsCliError",
24 {
25 operation: Schema.String,
26 command: Schema.String,
27 cwd: Schema.String,
28 detail: Schema.String,
29 cause: Schema.optional(Schema.Defect()),
30 },
24const azureDevOpsCommandErrorFields = {
25 operation: Schema.Literal("execute"),
26 command: Schema.Literal("az"),
27 cwd: Schema.String,
28 argumentCount: NonNegativeInt,
29 cause: Schema.Defect(),
30};
31
32export class AzureDevOpsCliUnavailableError extends Schema.TaggedErrorClass<AzureDevOpsCliUnavailableError>()(
33 "AzureDevOpsCliUnavailableError",
34 azureDevOpsCommandErrorFields,
35) {
36 get detail(): string {
37 return "Azure CLI (`az`) with the Azure DevOps extension is required but not available on PATH.";
38 }
39
40 override get message(): string {
41 return `Azure DevOps CLI failed in ${this.operation}: ${this.detail}`;
42 }
43}
44
45export class AzureDevOpsCliAuthenticationError extends Schema.TaggedErrorClass<AzureDevOpsCliAuthenticationError>()(
46 "AzureDevOpsCliAuthenticationError",
47 azureDevOpsCommandErrorFields,
48) {
49 get detail(): string {
50 return "Azure DevOps CLI is not authenticated. Run `az devops login` and retry.";
51 }
52
53 override get message(): string {
54 return `Azure DevOps CLI failed in ${this.operation}: ${this.detail}`;
55 }
56}
57
58export class AzureDevOpsPullRequestNotFoundError extends Schema.TaggedErrorClass<AzureDevOpsPullRequestNotFoundError>()(
59 "AzureDevOpsPullRequestNotFoundError",
60 azureDevOpsCommandErrorFields,
61) {
62 get detail(): string {
63 return "Pull request not found. Check the PR number or URL and try again.";
64 }
65
66 override get message(): string {
67 return `Azure DevOps CLI failed in ${this.operation}: ${this.detail}`;
68 }
69}
70
71export class AzureDevOpsCommandFailedError extends Schema.TaggedErrorClass<AzureDevOpsCommandFailedError>()(
72 "AzureDevOpsCommandFailedError",
73 azureDevOpsCommandErrorFields,
3174) {
75 get detail(): string {
76 return "Azure DevOps CLI command failed.";
77 }
78
3279 override get message(): string {
3380 return `Azure DevOps CLI failed in ${this.operation}: ${this.detail}`;
3481 }
......@@ -38,53 +85,109 @@ export class AzureDevOpsCliError extends Schema.TaggedErrorClass<AzureDevOpsCliE
3885 readonly operation: "execute";
3986 readonly command: "az";
4087 readonly cwd: string;
88 readonly argumentCount: number;
4189 },
42 error: VcsError | unknown,
90 cause: VcsError,
4391 ): AzureDevOpsCliError {
44 const lower = errorText(error).toLowerCase();
45
46 if (lower.includes("command not found: az") || lower.includes("enoent")) {
47 return new AzureDevOpsCliError({
48 ...context,
49 detail:
50 "Azure CLI (`az`) with the Azure DevOps extension is required but not available on PATH.",
51 cause: error,
52 });
53 }
92 const fields = { ...context, cause };
5493
5594 if (
56 lower.includes("az devops login") ||
57 lower.includes("please run az login") ||
58 lower.includes("not logged in") ||
59 lower.includes("authentication failed") ||
60 lower.includes("unauthorized")
95 cause._tag === "VcsProcessSpawnError" &&
96 cause.cause instanceof PlatformError.PlatformError &&
97 cause.cause.reason._tag === "NotFound" &&
98 cause.cause.reason.pathOrDescriptor !== context.cwd &&
99 cause.cause.reason.syscall !== "chdir"
61100 ) {
62 return new AzureDevOpsCliError({
63 ...context,
64 detail: "Azure DevOps CLI is not authenticated. Run `az devops login` and retry.",
65 cause: error,
66 });
101 return new AzureDevOpsCliUnavailableError(fields);
67102 }
68103
69 if (
70 lower.includes("pull request") &&
71 (lower.includes("not found") || lower.includes("does not exist"))
72 ) {
73 return new AzureDevOpsCliError({
74 ...context,
75 detail: "Pull request not found. Check the PR number or URL and try again.",
76 cause: error,
77 });
104 if (cause._tag === "VcsProcessExitError") {
105 if (cause.failureKind === "authentication") {
106 return new AzureDevOpsCliAuthenticationError(fields);
107 }
108 if (cause.failureKind === "not-found") {
109 return new AzureDevOpsPullRequestNotFoundError(fields);
110 }
78111 }
79112
80 return new AzureDevOpsCliError({
81 ...context,
82 detail: "Azure DevOps CLI command failed.",
83 cause: error,
84 });
113 return new AzureDevOpsCommandFailedError(fields);
114 }
115}
116
117const azureDevOpsDecodeErrorFields = {
118 command: Schema.Literal("az"),
119 cwd: Schema.String,
120 outputLength: NonNegativeInt,
121 cause: Schema.Defect(),
122};
123
124export class AzureDevOpsPullRequestListDecodeError extends Schema.TaggedErrorClass<AzureDevOpsPullRequestListDecodeError>()(
125 "AzureDevOpsPullRequestListDecodeError",
126 {
127 operation: Schema.Literal("listPullRequests"),
128 ...azureDevOpsDecodeErrorFields,
129 },
130) {
131 get detail(): string {
132 return "Azure DevOps CLI returned invalid PR list JSON.";
133 }
134
135 override get message(): string {
136 return `Azure DevOps CLI failed in ${this.operation}: ${this.detail}`;
137 }
138}
139
140export class AzureDevOpsPullRequestDecodeError extends Schema.TaggedErrorClass<AzureDevOpsPullRequestDecodeError>()(
141 "AzureDevOpsPullRequestDecodeError",
142 {
143 operation: Schema.Literal("getPullRequest"),
144 ...azureDevOpsDecodeErrorFields,
145 },
146) {
147 get detail(): string {
148 return "Azure DevOps CLI returned invalid pull request JSON.";
149 }
150
151 override get message(): string {
152 return `Azure DevOps CLI failed in ${this.operation}: ${this.detail}`;
153 }
154}
155
156const AzureDevOpsRepositoryDecodeOperation = Schema.Literals([
157 "getRepositoryCloneUrls",
158 "getDefaultBranch",
159 "createRepository",
160]);
161
162export class AzureDevOpsRepositoryDecodeError extends Schema.TaggedErrorClass<AzureDevOpsRepositoryDecodeError>()(
163 "AzureDevOpsRepositoryDecodeError",
164 {
165 operation: AzureDevOpsRepositoryDecodeOperation,
166 ...azureDevOpsDecodeErrorFields,
167 },
168) {
169 get detail(): string {
170 return "Azure DevOps CLI returned invalid repository JSON.";
171 }
172
173 override get message(): string {
174 return `Azure DevOps CLI failed in ${this.operation}: ${this.detail}`;
85175 }
86176}
87177
178export const AzureDevOpsCliError = Schema.Union([
179 AzureDevOpsCliUnavailableError,
180 AzureDevOpsCliAuthenticationError,
181 AzureDevOpsPullRequestNotFoundError,
182 AzureDevOpsCommandFailedError,
183 AzureDevOpsPullRequestListDecodeError,
184 AzureDevOpsPullRequestDecodeError,
185 AzureDevOpsRepositoryDecodeError,
186]);
187export type AzureDevOpsCliError = typeof AzureDevOpsCliError.Type;
188
189export const isAzureDevOpsCliError = Schema.is(AzureDevOpsCliError);
190
88191export interface AzureDevOpsRepositoryCloneUrls {
89192 readonly nameWithOwner: string;
90193 readonly url: string;
......@@ -146,17 +249,6 @@ export class AzureDevOpsCli extends Context.Service<
146249 }
147250>()("t3/sourceControl/AzureDevOpsCli") {}
148251
149function errorText(error: VcsError | unknown): string {
150 if (typeof error === "object" && error !== null) {
151 const tag = "_tag" in error && typeof error._tag === "string" ? error._tag : "";
152 const detail = "detail" in error && typeof error.detail === "string" ? error.detail : "";
153 const message = "message" in error && typeof error.message === "string" ? error.message : "";
154 return [tag, detail, message].filter(Boolean).join("\n");
155 }
156
157 return String(error);
158}
159
160252function normalizeChangeRequestId(reference: string): string {
161253 const trimmed = reference.trim().replace(/^#/, "");
162254 const urlMatch = /(?:pullrequest|pull-request|pull|_pulls?)\/(\d+)(?:\D.*)?$/i.exec(trimmed);
......@@ -225,19 +317,18 @@ function parseRepositorySpecifier(repository: string): {
225317function decodeAzureDevOpsJson<S extends Schema.Top>(
226318 raw: string,
227319 schema: S,
228 operation: "getRepositoryCloneUrls" | "getDefaultBranch" | "createRepository",
229 invalidDetail: string,
320 operation: typeof AzureDevOpsRepositoryDecodeOperation.Type,
230321 cwd: string,
231): Effect.Effect<S["Type"], AzureDevOpsCliError, S["DecodingServices"]> {
322): Effect.Effect<S["Type"], AzureDevOpsRepositoryDecodeError, S["DecodingServices"]> {
232323 return Schema.decodeEffect(Schema.fromJsonString(schema))(raw).pipe(
233324 Effect.mapError(
234 (error) =>
235 new AzureDevOpsCliError({
325 (cause) =>
326 new AzureDevOpsRepositoryDecodeError({
236327 operation,
237328 command: "az",
238329 cwd,
239 detail: invalidDetail,
240 cause: error,
330 outputLength: raw.length,
331 cause,
241332 }),
242333 ),
243334 );
......@@ -257,8 +348,13 @@ export const make = Effect.gen(function* () {
257348 })
258349 .pipe(
259350 Effect.mapError((error) =>
260 AzureDevOpsCliError.fromVcsError(
261 { operation: "execute", command: "az", cwd: input.cwd },
351 AzureDevOpsCommandFailedError.fromVcsError(
352 {
353 operation: "execute",
354 command: "az",
355 cwd: input.cwd,
356 argumentCount: input.args.length,
357 },
262358 error,
263359 ),
264360 ),
......@@ -297,11 +393,11 @@ export const make = Effect.gen(function* () {
297393 Effect.flatMap((decoded) => {
298394 if (!Result.isSuccess(decoded)) {
299395 return Effect.fail(
300 new AzureDevOpsCliError({
396 new AzureDevOpsPullRequestListDecodeError({
301397 operation: "listPullRequests",
302398 command: "az",
303399 cwd: input.cwd,
304 detail: "Azure DevOps CLI returned invalid PR list JSON.",
400 outputLength: raw.length,
305401 cause: decoded.failure,
306402 }),
307403 );
......@@ -331,11 +427,11 @@ export const make = Effect.gen(function* () {
331427 Effect.flatMap((decoded) => {
332428 if (!Result.isSuccess(decoded)) {
333429 return Effect.fail(
334 new AzureDevOpsCliError({
430 new AzureDevOpsPullRequestDecodeError({
335431 operation: "getPullRequest",
336432 command: "az",
337433 cwd: input.cwd,
338 detail: "Azure DevOps CLI returned invalid pull request JSON.",
434 outputLength: raw.length,
339435 cause: decoded.failure,
340436 }),
341437 );
......@@ -357,7 +453,6 @@ export const make = Effect.gen(function* () {
357453 raw,
358454 RawAzureDevOpsRepositorySchema,
359455 "getRepositoryCloneUrls",
360 "Azure DevOps CLI returned invalid repository JSON.",
361456 input.cwd,
362457 ),
363458 ),
......@@ -383,13 +478,7 @@ export const make = Effect.gen(function* () {
383478 }).pipe(
384479 Effect.map((result) => result.stdout.trim()),
385480 Effect.flatMap((raw) =>
386 decodeAzureDevOpsJson(
387 raw,
388 RawAzureDevOpsRepositorySchema,
389 "createRepository",
390 "Azure DevOps CLI returned invalid repository JSON.",
391 input.cwd,
392 ),
481 decodeAzureDevOpsJson(raw, RawAzureDevOpsRepositorySchema, "createRepository", input.cwd),
393482 ),
394483 Effect.map(normalizeRepositoryCloneUrls),
395484 );
......@@ -421,13 +510,7 @@ export const make = Effect.gen(function* () {
421510 }).pipe(
422511 Effect.map((result) => result.stdout.trim()),
423512 Effect.flatMap((raw) =>
424 decodeAzureDevOpsJson(
425 raw,
426 RawAzureDevOpsRepositorySchema,
427 "getDefaultBranch",
428 "Azure DevOps CLI returned invalid repository JSON.",
429 input.cwd,
430 ),
513 decodeAzureDevOpsJson(raw, RawAzureDevOpsRepositorySchema, "getDefaultBranch", input.cwd),
431514 ),
432515 Effect.map((repo) => normalizeDefaultBranch(repo.defaultBranch)),
433516 ),
apps/server/src/sourceControl/AzureDevOpsSourceControlProvider.test.ts+2-2
......@@ -48,11 +48,11 @@ it.effect("maps Azure DevOps PR summaries into provider-neutral change requests"
4848
4949it.effect("adds change-request context while retaining Azure CLI causes", () =>
5050 Effect.gen(function* () {
51 const cause = new AzureDevOpsCli.AzureDevOpsCliError({
51 const cause = new AzureDevOpsCli.AzureDevOpsCommandFailedError({
5252 operation: "execute",
5353 command: "az",
5454 cwd: "/repo",
55 detail: "Azure DevOps CLI command failed.",
55 argumentCount: 2,
5656 cause: new Error("raw upstream detail that should remain in the cause"),
5757 });
5858 const provider = yield* makeProvider({