feat(cli): add builds command

Author: jsfez

.github/workflows/ci.yml

@@ -89,6 +89,7 @@ jobs:
         run: pnpm exec -- turbo run e2e --filter=@argos-ci/core --filter=@argos-ci/cli
         env:
           ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
+          ARGOS_BUILD_ID: ${{ vars.ARGOS_BUILD_ID }}
           NODE_VERSION: ${{ matrix.node-version }}
           OS: ${{ matrix.os }}
 

.gitignore

@@ -9,4 +9,6 @@ dist/
 # Turborepo
 .turbo
 # NPM
-.npmrc
+.npmrc
+# macOS
+.DS_Store

packages/api-client/src/schema.ts

@@ -236,6 +236,13 @@ export interface components {
                 };
             };
         };
+        /** @description Build git reference */
+        BuildGitReference: {
+            /** @description The commit SHA */
+            sha: components["schemas"]["Sha1Hash"];
+            /** @description The branch name */
+            branch: string;
+        };
         /** @description Build */
         Build: {
             id: components["schemas"]["BuildId"];

packages/cli/e2e/builds.js

@@ -0,0 +1,183 @@
+/**
+ * E2E tests for `argos builds` commands.
+ * Requires ARGOS_TOKEN and ARGOS_BUILD_ID env vars.
+ * Optional: ARGOS_API_BASE_URL env var.
+ *
+ * Usage:
+ *   ARGOS_TOKEN=xxx ARGOS_BUILD_ID=<failingBuildId> node e2e/builds.js
+ *   ARGOS_TOKEN=xxx ARGOS_BUILD_ID=<failingBuildId> ARGOS_API_BASE_URL=https://api.argos-ci.com/v2 node e2e/builds.js
+ */
+
+import { execFileSync } from "node:child_process";
+
+const token = process.env.ARGOS_TOKEN;
+const apiBaseURL = process.env.ARGOS_API_BASE_URL;
+const buildId = process.env.ARGOS_BUILD_ID;
+const cliPath = "bin/argos-cli.js";
+
+if (!token || !buildId) {
+  console.error(
+    "Usage: ARGOS_TOKEN=xxx ARGOS_BUILD_ID=<id> [ARGOS_API_BASE_URL=<url>] node e2e/builds.js",
+  );
+  process.exit(1);
+}
+
+function envWith(overrides = {}) {
+  return { ...process.env, ...overrides };
+}
+
+const baseEnv = apiBaseURL
+  ? envWith({ ARGOS_API_BASE_URL: apiBaseURL })
+  : process.env;
+
+function run(args, env = process.env) {
+  return execFileSync("node", [cliPath, ...args], {
+    encoding: "utf8",
+    env,
+  });
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    console.error(`FAIL: ${message}`);
+    process.exit(1);
+  }
+  console.log(`PASS: ${message}`);
+}
+
+// --- Authentication tests ---
+
+// No token → error + exit 1
+try {
+  run(["builds", "get", buildId], { ...baseEnv, ARGOS_TOKEN: "" });
+  assert(false, "Missing token should exit with code 1");
+} catch (err) {
+  assert(err.status === 1, "Exit code 1 when no token");
+  assert(
+    err.stderr.includes("No Argos token found"),
+    "Error message includes 'No Argos token found'",
+  );
+}
+
+// ARGOS_TOKEN env var
+const getOutputEnv = run(["builds", "get", buildId], {
+  ...baseEnv,
+  ARGOS_TOKEN: token,
+});
+assert(getOutputEnv.includes("Build #"), "ARGOS_TOKEN env var authenticates");
+
+// --token flag (takes precedence)
+const getOutputFlag = run(["builds", "get", buildId, "--token", token], {
+  ...baseEnv,
+  ARGOS_TOKEN: "invalid",
+});
+assert(
+  getOutputFlag.includes("Build #"),
+  "--token flag takes precedence over env var",
+);
+
+// --- builds get tests ---
+
+// Formatted output
+assert(getOutputEnv.includes("Status:"), "builds get: formatted Status line");
+assert(getOutputEnv.includes("Branch:"), "builds get: formatted Branch line");
+assert(getOutputEnv.includes("Commit:"), "builds get: formatted Commit line");
+assert(getOutputEnv.includes("URL:"), "builds get: formatted URL line");
+assert(
+  getOutputEnv.includes("Snapshots:"),
+  "builds get: formatted Snapshots line",
+);
+
+// --json flag
+const getJsonOutput = run(["builds", "get", buildId, "--json"], {
+  ...baseEnv,
+  ARGOS_TOKEN: token,
+});
+const buildJson = JSON.parse(getJsonOutput);
+assert(buildJson.id !== undefined, "--json: has 'id' field");
+assert(buildJson.status !== undefined, "--json: has 'status' field");
+assert(
+  buildJson.branch !== undefined || buildJson.branch === null,
+  "--json: has 'branch' field",
+);
+assert(
+  buildJson.commit !== undefined || buildJson.commit === null,
+  "--json: has 'commit' field",
+);
+assert(buildJson.url !== undefined, "--json: has 'url' field");
+
+// status reflects actual result
+assert(
+  ["failure", "success", "pending"].includes(buildJson.status),
+  `--json: status is one of failure|success|pending (got: ${buildJson.status})`,
+);
+
+// Unknown build ID
+try {
+  run(["builds", "get", "unknown-build-id-9999"], {
+    ...baseEnv,
+    ARGOS_TOKEN: token,
+  });
+  assert(false, "Unknown build ID should exit with code 1");
+} catch (err) {
+  assert(err.status === 1, "Unknown build ID: exit code 1");
+  assert(
+    err.stderr.includes("Error:") || err.stderr.includes("not found"),
+    "Unknown build ID: human-readable error message",
+  );
+}
+
+// --- builds snapshots tests ---
+
+// List all (no filter)
+const snapshotsAll = run(["builds", "snapshots", buildId], {
+  ...baseEnv,
+  ARGOS_TOKEN: token,
+});
+assert(typeof snapshotsAll === "string", "builds snapshots: returns output");
+
+// --status failure filter
+const snapshotsFailure = run(
+  ["builds", "snapshots", buildId, "--status", "failure"],
+  { ...baseEnv, ARGOS_TOKEN: token },
+);
+const failureLines = snapshotsFailure.trim().split("\n").filter(Boolean);
+assert(
+  failureLines.every((line) => line.includes("[failure]")),
+  "--status failure: all lines have [failure] status",
+);
+
+// --json output
+const snapshotsJson = run(["builds", "snapshots", buildId, "--json"], {
+  ...baseEnv,
+  ARGOS_TOKEN: token,
+});
+const snapshotItems = JSON.parse(snapshotsJson);
+assert(Array.isArray(snapshotItems), "--json: returns an array");
+if (snapshotItems.length > 0) {
+  const first = snapshotItems[0];
+  assert(first.name !== undefined, "--json: each item has 'name' field");
+  assert(first.status !== undefined, "--json: each item has 'status' field");
+  assert(first.url !== undefined, "--json: each item has 'url' field");
+}
+
+// Integration test: --status failure --json → every item has "status": "failure"
+const snapshotsFailureJson = run(
+  ["builds", "snapshots", buildId, "--status", "failure", "--json"],
+  { ...baseEnv, ARGOS_TOKEN: token },
+);
+const failureItems = JSON.parse(snapshotsFailureJson);
+assert(
+  Array.isArray(failureItems),
+  "integration: --status failure --json returns array",
+);
+assert(
+  failureItems.every((item) => item.status === "failure"),
+  'integration: every item in --status failure --json has "status": "failure"',
+);
+
+// Empty result for build with no failures using --status failure should exit 0
+// (this test passes trivially if the build has failures and returns items,
+// but the logic is tested by checking exit code 0 above)
+
+console.log("\nAll e2e tests passed!");

packages/cli/package.json

@@ -34,14 +34,15 @@
     "access": "public"
   },
   "dependencies": {
+    "@argos-ci/api-client": "workspace:*",
     "@argos-ci/core": "workspace:*",
     "commander": "^14.0.3",
     "ora": "^9.3.0",
     "update-notifier": "^7.3.1"
   },
   "scripts": {
     "build": "tsdown",
-    "e2e": "node e2e/upload.js && node e2e/skip.js",
+    "e2e": "node e2e/upload.js && node e2e/skip.js && node e2e/builds.js",
     "check-types": "tsc",
     "check-format": "prettier --check --ignore-unknown --ignore-path=../../.gitignore --ignore-path=../../.prettierignore .",
     "lint": "eslint ."