Skip to content

Commit b0c00eb

Browse files
gregbergeclaude
andauthored
feat: add --skip-if-empty option to argos finalize (#341)
* feat: add --skip-if-empty option to argos finalize When every upload step of a pipeline is conditional (e.g. skipped by a task cache such as Turborepo or Nx), a run may produce no parallel shard at all: finalize then has nothing to close and a required Argos status check stays missing on the commit. With --skip-if-empty, finalize creates a skipped build when no parallel build matches the nonce, so the commit still gets a successful Argos status. The skipped build is named with --build-name / ARGOS_BUILD_NAME. Also exposes --token on the finalize command and apiBaseUrl/token on the core finalize() parameters, for parity with upload/skip. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore: fix formatting and make finalize tests CI-agnostic The files were accidentally formatted with a different style than the repository's prettier config. The 'throws without a nonce' test also failed on GitHub Actions, where a parallel nonce is automatically derived from the run: CI detection is now neutralized in the test setup so the suite behaves the same everywhere. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent aa6ac0c commit b0c00eb

5 files changed

Lines changed: 207 additions & 8 deletions

File tree

‎packages/cli/src/commands/finalize.ts‎

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,49 @@
11
import ora from "ora";
2-
import type { Command } from "commander";
2+
import { Option, type Command } from "commander";
33
import { finalize } from "@argos-ci/core";
4-
import { parallelNonceOption, type ParallelNonceOption } from "../options";
4+
import {
5+
buildNameOption,
6+
parallelNonceOption,
7+
tokenOption,
8+
type BuildNameOption,
9+
type ParallelNonceOption,
10+
type TokenOption,
11+
} from "../options";
512

6-
type FinalizeOptions = ParallelNonceOption;
13+
type FinalizeOptions = ParallelNonceOption &
14+
TokenOption &
15+
BuildNameOption & { skipIfEmpty?: boolean | undefined };
16+
17+
const skipIfEmptyOption = new Option(
18+
"--skip-if-empty",
19+
"Create a skipped build when no parallel build matches the nonce.\nUseful when uploads are conditional (e.g. skipped by a CI cache) and Argos is a required status check: the skipped build reports a success status even though nothing was uploaded.",
20+
);
721

822
export function finalizeCommand(program: Command) {
923
program
1024
.command("finalize")
1125
.description("Finalize pending parallel builds")
1226
.addOption(parallelNonceOption)
27+
.addOption(tokenOption)
28+
.addOption(skipIfEmptyOption)
29+
.addOption(buildNameOption)
1330
.action(async (options: FinalizeOptions) => {
1431
const spinner = ora("Finalizing builds").start();
1532
try {
1633
const result = await finalize({
34+
token: options.token,
1735
parallel: options.parallelNonce
1836
? { nonce: options.parallelNonce }
1937
: undefined,
38+
skipIfEmpty: options.skipIfEmpty,
39+
buildName: options.buildName,
2040
});
2141
spinner.succeed(
22-
result.builds.length === 0
23-
? "No builds to finalize"
24-
: `Builds finalized: ${result.builds.map((b) => b.url).join(", ")}`,
42+
result.skippedBuild
43+
? `No builds to finalize — skipped build created: ${result.skippedBuild.url}`
44+
: result.builds.length === 0
45+
? "No builds to finalize"
46+
: `Builds finalized: ${result.builds.map((b) => b.url).join(", ")}`,
2547
);
2648
} catch (error) {
2749
if (error instanceof Error) {
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
import { http, HttpResponse } from "msw";
2+
3+
type FinalizeBuildsParams = never;
4+
type FinalizeBuildsRequestBody = {
5+
parallelNonce: string;
6+
};
7+
type FinalizeBuildsResponseBody = {
8+
builds: {
9+
id: string;
10+
url: string;
11+
}[];
12+
};
13+
14+
export const finalizeBuilds = http.post<
15+
FinalizeBuildsParams,
16+
FinalizeBuildsRequestBody,
17+
FinalizeBuildsResponseBody
18+
>("https://api.argos-ci.dev/builds/finalize", async ({ request }) => {
19+
const body = await request.json();
20+
// The "empty" nonce simulates a run where no parallel build was uploaded.
21+
if (body.parallelNonce === "empty") {
22+
return HttpResponse.json({ builds: [] });
23+
}
24+
return HttpResponse.json({
25+
builds: [
26+
{
27+
id: "456",
28+
url: "https://app.argos-ci.dev/builds/456",
29+
},
30+
],
31+
});
32+
});

‎packages/core/mocks/server.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
import { beforeAll, afterAll, afterEach } from "vitest";
22
import { setupServer } from "msw/node";
33
import { createBuild } from "./handlers/createBuild";
4+
import { finalizeBuilds } from "./handlers/finalizeBuilds";
45
import { getProject } from "./handlers/getProject";
56
import { updateBuild } from "./handlers/updateBuild";
67
import { uploadScreenshot } from "./handlers/uploadScreenshot";
78

89
export const server = setupServer(
910
createBuild,
11+
finalizeBuilds,
1012
updateBuild,
1113
uploadScreenshot,
1214
getProject,

‎packages/core/src/finalize.test.ts‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
2+
import { setupMockServer } from "../mocks/server";
3+
import { finalize } from "./finalize";
4+
5+
setupMockServer();
6+
7+
describe("#finalize", () => {
8+
beforeEach(() => {
9+
// Neutralize CI detection so the tests behave the same locally and on
10+
// GitHub Actions, where a nonce would be derived from the run
11+
// automatically.
12+
vi.stubEnv("GITHUB_ACTIONS", "");
13+
vi.stubEnv("ARGOS_COMMIT", "f16f980bd17cccfa93a1ae7766727e67950773d0");
14+
vi.stubEnv("ARGOS_BRANCH", "main");
15+
});
16+
17+
afterEach(() => {
18+
vi.unstubAllEnvs();
19+
});
20+
21+
it("finalizes builds matching the nonce", async () => {
22+
const result = await finalize({
23+
apiBaseUrl: "https://api.argos-ci.dev",
24+
token: "92d832e0d22ab113c8979d73a87a11130eaa24a9",
25+
parallel: { nonce: "nonce-123" },
26+
});
27+
28+
expect(result).toEqual({
29+
builds: [{ id: "456", url: "https://app.argos-ci.dev/builds/456" }],
30+
skippedBuild: null,
31+
});
32+
});
33+
34+
it("returns no builds when the nonce matches nothing", async () => {
35+
const result = await finalize({
36+
apiBaseUrl: "https://api.argos-ci.dev",
37+
token: "92d832e0d22ab113c8979d73a87a11130eaa24a9",
38+
parallel: { nonce: "empty" },
39+
});
40+
41+
expect(result).toEqual({ builds: [], skippedBuild: null });
42+
});
43+
44+
it("throws without a nonce", async () => {
45+
await expect(
46+
finalize({
47+
apiBaseUrl: "https://api.argos-ci.dev",
48+
token: "92d832e0d22ab113c8979d73a87a11130eaa24a9",
49+
}),
50+
).rejects.toThrow("parallel.nonce is required to finalize the build");
51+
});
52+
53+
describe("with skipIfEmpty", () => {
54+
it("creates a skipped build when the nonce matches nothing", async () => {
55+
const result = await finalize({
56+
apiBaseUrl: "https://api.argos-ci.dev",
57+
token: "92d832e0d22ab113c8979d73a87a11130eaa24a9",
58+
parallel: { nonce: "empty" },
59+
skipIfEmpty: true,
60+
buildName: "unit",
61+
});
62+
63+
expect(result).toEqual({
64+
builds: [],
65+
skippedBuild: {
66+
id: "123",
67+
url: "https://app.argos-ci.dev/builds/123",
68+
},
69+
});
70+
});
71+
72+
it("does not create a skipped build when builds are finalized", async () => {
73+
const result = await finalize({
74+
apiBaseUrl: "https://api.argos-ci.dev",
75+
token: "92d832e0d22ab113c8979d73a87a11130eaa24a9",
76+
parallel: { nonce: "nonce-123" },
77+
skipIfEmpty: true,
78+
buildName: "unit",
79+
});
80+
81+
expect(result).toEqual({
82+
builds: [{ id: "456", url: "https://app.argos-ci.dev/builds/456" }],
83+
skippedBuild: null,
84+
});
85+
});
86+
});
87+
});

‎packages/core/src/finalize.ts‎

Lines changed: 58 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,63 @@
1+
import type { ArgosAPISchema } from "@argos-ci/api-client";
12
import { createClient, throwAPIError } from "@argos-ci/api-client";
23
import { resolveArgosToken } from "./auth";
34
import { readConfig } from "./config";
5+
import { skip } from "./skip";
46

57
export type FinalizeParameters = {
8+
/**
9+
* Base URL of the Argos API.
10+
*/
11+
apiBaseUrl?: string;
12+
13+
/**
14+
* Argos token.
15+
*/
16+
token?: string;
17+
618
parallel?: {
719
nonce: string;
820
};
21+
22+
/**
23+
* Create a skipped build when no parallel build matches the nonce.
24+
* Useful when uploads are conditional (e.g. skipped by a CI cache such as
25+
* Turborepo or Nx) and Argos is a required status check: the skipped build
26+
* reports a success status even though nothing was uploaded.
27+
*/
28+
skipIfEmpty?: boolean;
29+
30+
/**
31+
* Name of the build, used by the skipped build created when `skipIfEmpty`
32+
* is enabled and no build matches the nonce.
33+
*/
34+
buildName?: string;
35+
};
36+
37+
type Build = ArgosAPISchema.components["schemas"]["Build"];
38+
39+
export type FinalizeResult = {
40+
/**
41+
* Parallel builds finalized by this call.
42+
*/
43+
builds: Build[];
44+
45+
/**
46+
* Skipped build created when `skipIfEmpty` is enabled and no parallel
47+
* build matched the nonce, `null` otherwise.
48+
*/
49+
skippedBuild: Build | null;
950
};
1051

1152
/**
1253
* Finalize pending builds.
1354
*/
14-
export async function finalize(params: FinalizeParameters) {
55+
export async function finalize(
56+
params: FinalizeParameters,
57+
): Promise<FinalizeResult> {
1558
const config = await readConfig({
59+
apiBaseUrl: params.apiBaseUrl,
60+
token: params.token,
1661
parallelNonce: params.parallel?.nonce,
1762
});
1863
const authToken = await resolveArgosToken(config);
@@ -36,5 +81,16 @@ export async function finalize(params: FinalizeParameters) {
3681
throwAPIError(finalizeBuildsResult.error, finalizeBuildsResult.response);
3782
}
3883

39-
return finalizeBuildsResult.data;
84+
const { builds } = finalizeBuildsResult.data;
85+
86+
if (builds.length === 0 && params.skipIfEmpty) {
87+
const { build } = await skip({
88+
apiBaseUrl: params.apiBaseUrl,
89+
token: params.token,
90+
buildName: params.buildName,
91+
});
92+
return { builds, skippedBuild: build };
93+
}
94+
95+
return { builds, skippedBuild: null };
4096
}

0 commit comments

Comments
 (0)