@snapvisor/cli 7.0.0 → 7.1.0

package/README.md

@@ -33,6 +33,24 @@ Upload a directory of screenshots to Argos. Authenticate with your project token
 ARGOS_TOKEN="<your-argos-token>" npx @snapvisor/cli upload ./screenshots
 ```
 
+### Failing CI when a build needs review
+
+By default `upload` exits right after the build is created, so a build with unreviewed changes does not fail the job (the commit status does). Pass `--wait` to make the command wait for the build to finish and report the result through its exit code:
+
+```sh
+ARGOS_TOKEN="<your-argos-token>" npx @snapvisor/cli upload ./screenshots --wait --wait-timeout 300
+```
+
+| Build state                                                | Exit code |
+| ---------------------------------------------------------- | --------- |
+| `accepted` / `no-changes`                                  | `0`       |
+| `changes-detected` on a reference build (auto-approved)    | `0`       |
+| `changes-detected` awaiting review                         | `1`       |
+| `rejected`, `expired`, `aborted`, `error`                  | `1`       |
+| Still running after `--wait-timeout` seconds (default 600) | `1`       |
+
+The exit code always agrees with the build's commit status: success is exit 0, pending review or failure is exit 1. A `429` from the API is retried until the timeout. The build URL and final state are printed either way. `--wait` polls the Snapvisor API, so it needs a token it can read the build with (`--token` or `ARGOS_TOKEN`): GitHub Actions OIDC and tokenless uploads, and `argos login` sessions, are not supported. It cannot be combined with `--parallel`, because a parallel build only finishes once it is finalized.
+
 The CLI also exposes commands to `deploy` a static build, inspect and `review` builds, post a `comment`, and more. List them all with:
 
 ```sh

package/dist/index.mjs

@@ -1,125 +1,14 @@
 import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
-import { Option, program } from "commander";
-import { deploy, finalize, skip, upload } from "@snapvisor/core";
+import { InvalidArgumentError, Option, program } from "commander";
+import { deploy, finalize, readConfig, skip, upload } from "@snapvisor/core";
 import ora from "ora";
 import { APIError, createClient, throwAPIError } from "@snapvisor/api-client";
 import { homedir } from "node:os";
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import open from "open";
-//#region src/options.ts
-const parallelNonceOption = new Option("--parallel-nonce <string>", "A unique ID for this parallel build");
-const tokenOption = new Option("--token <token>", "Repository token");
-const projectOption = new Option("--project <slug>", "Snapvisor project slug (account/project), used to disambiguate tokenless authentication when multiple projects are linked to the same repository");
-const buildNameOption = new Option("--build-name <string>", "Name of the build, in case you want to run multiple Snapvisor builds in a single CI job");
-const accountOption = new Option("--account <slug>", "Slug of the account (personal or team) that will own the project");
-const jsonOption = new Option("--json", "Output machine-readable JSON instead of human-readable text");
-const projectPathOption = new Option("--project <owner/project>", "Project path in owner/project format. Required for build-number references on review and comment commands");
-const changeProjectPathOption = new Option("--project <owner/project>", "Project the change belongs to, in owner/project format. Also ARGOS_PROJECT");
-const METRICS_PERIOD_BY_CHOICE = {
-	"24h": "LAST_24_HOURS",
-	"3d": "LAST_3_DAYS",
-	"7d": "LAST_7_DAYS",
-	"30d": "LAST_30_DAYS",
-	"90d": "LAST_90_DAYS"
-};
-const metricsPeriodOption = new Option("--metrics-period <period>", "Window over which test flakiness metrics are computed").choices(Object.keys(METRICS_PERIOD_BY_CHOICE)).default("7d");
-/** Map a `--metrics-period` choice to the value the API expects. */
-function toMetricsPeriod(choice) {
-	return METRICS_PERIOD_BY_CHOICE[choice] ?? "LAST_7_DAYS";
-}
-//#endregion
-//#region src/commands/upload.ts
-function uploadCommand(program) {
-	program.command("upload").argument("<directory>", "Directory to upload").description("Upload screenshots to Snapvisor").option("-f, --files <patterns...>", "One or more globs matching image file paths to upload", "**/*.{png,jpg,jpeg}").option("-i, --ignore <patterns...>", "One or more globs matching image file paths to ignore (ex: \"**/*.png **/diff.jpg\")").addOption(tokenOption).addOption(projectOption).addOption(buildNameOption).addOption(new Option("--mode <string>", "Mode of comparison applied. CI for visual regression testing, monitoring for visual monitoring.").default("ci").choices(["ci", "monitoring"])).addOption(new Option("--parallel", "Enable parallel mode. Run multiple Snapvisor builds and combine them at the end.\nCan also be set via the ARGOS_PARALLEL environment variable.")).addOption(new Option("--parallel-total <number>", "The number of parallel nodes being ran")).addOption(parallelNonceOption).addOption(new Option("--parallel-index <number>", "The index of the parallel node being ran (must be at least 1)")).addOption(new Option("--reference-branch <string>", "Branch used as baseline for screenshot comparison")).addOption(new Option("--reference-commit <string>", "Commit used as baseline for screenshot comparison")).addOption(new Option("--threshold <number>", "Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Default to 0.5")).addOption(new Option("--subset", "Whether this build contains only a subset of screenshots.\nThis is useful when a build is created from an incomplete test suite where some tests are skipped.\nCan also be set via the ARGOS_SUBSET environment variable.")).action(async (directory, options) => {
-		const spinner = ora("Uploading screenshots").start();
-		try {
-			const parallel = (() => {
-				if (!options.parallel) return;
-				if (!options.parallelNonce) {
-					spinner.fail("--parallel-nonce is required if --parallel is set");
-					process.exit(1);
-				}
-				if (!options.parallelTotal) {
-					spinner.fail("--parallel-total is required if --parallel is set");
-					process.exit(1);
-				}
-				return {
-					nonce: options.parallelNonce,
-					total: options.parallelTotal,
-					index: options.parallelIndex
-				};
-			})();
-			const result = await upload({
-				token: options.token,
-				project: options.project,
-				root: directory,
-				buildName: options.buildName,
-				files: options.files,
-				ignore: options.ignore,
-				parallel,
-				referenceBranch: options.referenceBranch,
-				referenceCommit: options.referenceCommit,
-				mode: options.mode,
-				threshold: options.threshold,
-				subset: options.subset
-			});
-			spinner.succeed(`Build created: ${result.build.url}`);
-		} catch (error) {
-			if (error instanceof Error) {
-				spinner.fail(`Build failed: ${error.message}`);
-				console.error(error.stack);
-			}
-			process.exit(1);
-		}
-	});
-}
-//#endregion
-//#region src/commands/finalize.ts
-const skipIfEmptyOption = new Option("--skip-if-empty", "Create a skipped build when no parallel build matches the nonce.\nUseful when uploads are conditional (e.g. skipped by a CI cache) and Snapvisor is a required status check: the skipped build reports a success status even though nothing was uploaded.");
-function finalizeCommand(program) {
-	program.command("finalize").description("Finalize pending parallel builds").addOption(parallelNonceOption).addOption(tokenOption).addOption(skipIfEmptyOption).addOption(buildNameOption).action(async (options) => {
-		const spinner = ora("Finalizing builds").start();
-		try {
-			const result = await finalize({
-				token: options.token,
-				parallel: options.parallelNonce ? { nonce: options.parallelNonce } : void 0,
-				skipIfEmpty: options.skipIfEmpty,
-				buildName: options.buildName
-			});
-			spinner.succeed(result.skippedBuild ? `No builds to finalize — skipped build created: ${result.skippedBuild.url}` : result.builds.length === 0 ? "No builds to finalize" : `Builds finalized: ${result.builds.map((b) => b.url).join(", ")}`);
-		} catch (error) {
-			if (error instanceof Error) {
-				spinner.fail(`Failed to finalize: ${error.message}`);
-				console.error(error.stack);
-			}
-			process.exit(1);
-		}
-	});
-}
-//#endregion
-//#region src/commands/skip.ts
-function skipCommand(program) {
-	program.command("skip").description("Mark a build as skipped").addOption(tokenOption).addOption(buildNameOption).action(async (options) => {
-		const spinner = ora("Creating skipped build").start();
-		try {
-			const result = await skip({
-				token: options.token,
-				buildName: options.buildName
-			});
-			spinner.succeed(`Build created: ${result.build.url}`);
-		} catch (error) {
-			if (error instanceof Error) {
-				spinner.fail(`Build failed: ${error.message}`);
-				console.error(error.stack);
-			}
-			process.exit(1);
-		}
-	});
-}
-//#endregion
 //#region src/lib/api.ts
 /** Optional override for the API base URL (used in tests and dev). */
 function getApiBaseUrl() {
@@ -142,314 +31,106 @@ function unwrap(result) {
 	return result.data;
 }
 //#endregion
-//#region src/lib/format.ts
-/** Render a scalar, using `-` for empty values. */
-function formatValue(value) {
-	if (value === null || value === void 0 || value === "") return "-";
-	return String(value);
+//#region src/lib/cli-error.ts
+/**
+* Error whose message is meant to be shown to the user verbatim (prefixed with
+* `Error: `) before the CLI exits with a non-zero code. Throw it — via
+* {@link fail} — instead of calling `process.exit` directly so the failure can
+* be unit-tested and handled in a single place ({@link handleCliError}).
+*/
+var CliError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CliError";
+	}
+};
+/**
+* Abort the current command with a user-facing message.
+*/
+function fail(message) {
+	throw new CliError(message);
 }
-function formatUser(user) {
-	if (!user) return "-";
-	return user.name ? `${user.name} (@${user.slug})` : `@${user.slug}`;
+//#endregion
+//#region src/lib/oauth.ts
+/**
+* OAuth 2.1 client configuration and helpers for the `argos login` flow
+* (Authorization Code + PKCE with a loopback redirect, RFC 8252).
+*
+* The authorization server is the Snapvisor app origin; endpoints and token
+* validation are implemented in the main Snapvisor repo (`apps/backend/src/oauth`).
+*/
+/** First-party public client id, seeded in the Snapvisor database. */
+const OAUTH_CLIENT_ID = "argos-cli";
+/**
+* Scopes requested by `argos login`, covering the CLI's user actions (identity,
+* projects, reviews, comments). Build upload keeps using a project token.
+*/
+const OAUTH_SCOPES = [
+	"profile",
+	"projects:read",
+	"projects:write",
+	"reviews:write",
+	"comments:read",
+	"comments:write"
+];
+/** Refresh a bit early so a token never expires mid-request. */
+const EXPIRY_SKEW_MS = 60 * 1e3;
+function getAppBaseUrl() {
+	return process.env["ARGOS_APP_BASE_URL"] ?? "https://app.snapvisor.io/";
 }
-function formatMe(me) {
-	const lines = [
-		`Logged in to Snapvisor as ${formatValue(me.user.name)}.`,
-		`Name: ${formatValue(me.user.name)}`,
-		`Email: ${formatValue(me.user.email)}`
-	];
-	if (me.accounts.length > 0) lines.push(`Accounts: ${me.accounts.map((a) => `@${a.slug}`).join(", ")}`);
-	return lines.join("\n");
+/**
+* A token endpoint request that reached the server and was rejected by it
+* (non-2xx / OAuth error), as opposed to a transient network failure. Lets
+* callers tell "your session is gone, log in again" from "the network is down".
+*/
+var OAuthTokenError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "OAuthTokenError";
+	}
+};
+function toTokenSet(data) {
+	return {
+		accessToken: data.access_token,
+		refreshToken: data.refresh_token,
+		expiresAt: Date.now() + data.expires_in * 1e3 - EXPIRY_SKEW_MS,
+		scope: data.scope ?? ""
+	};
 }
-function formatProject(project) {
-	return [
-		`Created project ${project.account.slug}/${project.name}.`,
-		`ID: ${project.id}`,
-		`Name: ${project.name}`,
-		`Account: ${project.account.slug}`,
-		`Default base branch: ${formatValue(project.defaultBaseBranch)}`
-	].join("\n");
+/** Generate a PKCE `code_verifier` and its S256 `code_challenge`. */
+function generatePkce() {
+	const codeVerifier = randomBytes(32).toString("base64url");
+	return {
+		codeVerifier,
+		codeChallenge: createHash("sha256").update(codeVerifier).digest("base64url")
+	};
 }
-function formatStats(stats) {
-	if (!stats) return "-";
-	return [
-		`total ${stats.total}`,
-		`changed ${stats.changed}`,
-		`added ${stats.added}`,
-		`removed ${stats.removed}`,
-		`unchanged ${stats.unchanged}`
-	].join(", ");
+/** Build the `/oauth/authorize` URL to open in the browser. */
+function buildAuthorizeUrl(params) {
+	const url = new URL("/oauth/authorize", getAppBaseUrl());
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("client_id", OAUTH_CLIENT_ID);
+	url.searchParams.set("redirect_uri", params.redirectUri);
+	url.searchParams.set("scope", OAUTH_SCOPES.join(" "));
+	url.searchParams.set("state", params.state);
+	url.searchParams.set("code_challenge", params.codeChallenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	return url.href;
 }
-const SNAPSHOT_STATUS_ORDER = [
-	"changed",
-	"added",
-	"removed",
-	"unchanged",
-	"ignored",
-	"pending",
-	"failure",
-	"retryFailure"
-];
-function formatSnapshotSummary(diffs) {
-	const counts = /* @__PURE__ */ new Map();
-	for (const diff of diffs) counts.set(diff.status, (counts.get(diff.status) ?? 0) + 1);
-	return SNAPSHOT_STATUS_ORDER.map((status) => {
-		const count = counts.get(status);
-		return count ? `${status} ${count}` : null;
-	}).filter((part) => Boolean(part)).join(", ");
-}
-function formatBuild(build) {
-	return [
-		`Build #${build.number}`,
-		`Status: ${build.status}`,
-		`Snapshots: ${formatStats(build.stats)}`,
-		`Conclusion: ${formatValue(build.conclusion)}`,
-		`Branch: ${formatValue(build.head?.branch)}`,
-		`Commit: ${formatValue(build.head?.sha)}`,
-		`Base branch: ${formatValue(build.base?.branch)}`,
-		`Base commit: ${formatValue(build.base?.sha)}`,
-		`URL: ${build.url}`
-	].join("\n");
-}
-/** Render a 0–1 metric to two decimals, or `-` when absent. */
-function formatRatio(value) {
-	return value === null || value === void 0 ? "-" : value.toFixed(2);
-}
-/** Compact one-line summary of a test's flakiness metrics. */
-function formatFlakiness(metrics) {
-	return `${formatRatio(metrics.flakiness)} (stability ${formatRatio(metrics.stability)}, consistency ${formatRatio(metrics.consistency)})`;
-}
-/** Human-readable lines for a single snapshot diff. */
-function formatSnapshotDiff(diff, build) {
-	const lines = [
-		`${diff.name} [${diff.status}]`,
-		`  Review: ${build.url}/${diff.id}`,
-		`  Mask: ${formatValue(diff.url)}`,
-		`  Base file: ${formatValue(diff.base?.url)}`,
-		`  Head file: ${formatValue(diff.head?.url)}`,
-		`  Score: ${formatValue(diff.score)}`,
-		`  Group: ${formatValue(diff.group)}`
-	];
-	if (diff.test) lines.push(`  Flakiness: ${formatFlakiness(diff.test.metrics)}`);
-	if (diff.change) {
-		const ignored = diff.change.ignored ? " [ignored]" : "";
-		lines.push(`  Change: ${diff.change.id}${ignored} · ${diff.change.occurrences} occurrences`);
-	}
-	return lines;
-}
-function formatSnapshots(diffs, build) {
-	if (diffs.length === 0) return "No snapshots found.";
-	return [
-		`Snapshots for build #${build.number}`,
-		`Count: ${diffs.length}`,
-		`Summary: ${formatSnapshotSummary(diffs)}`,
-		"",
-		...diffs.flatMap((diff) => [...formatSnapshotDiff(diff, build), ""])
-	].slice(0, -1).join("\n");
-}
-function formatChange(change) {
-	return [
-		`Change ${change.id}`,
-		`Ignored: ${change.ignored ? "yes" : "no"}`,
-		`Occurrences: ${change.occurrences}`
-	].join("\n");
-}
-function formatReview(review) {
-	const lines = [
-		`Review #${review.id}`,
-		`State: ${review.state}`,
-		`Author: ${formatUser(review.user)}`,
-		`Date: ${review.date}`
-	];
-	if (review.dismissedAt) lines.push(`Dismissed: ${review.dismissedAt} by ${formatUser(review.dismissedBy)}`);
-	return lines.join("\n");
-}
-function formatReviews(reviews) {
-	if (reviews.length === 0) return "No reviews found.";
-	return [
-		`Reviews (${reviews.length})`,
-		"",
-		...reviews.flatMap((review) => [
-			`#${review.id} [${review.state}${review.dismissedAt ? ", dismissed" : ""}]`,
-			`  Author: ${formatUser(review.user)}`,
-			`  Date: ${review.date}`,
-			""
-		])
-	].slice(0, -1).join("\n");
-}
-function formatAnalytics(analytics, context) {
-	const { screenshots, builds } = analytics;
-	const lines = [
-		`Analytics for ${context.account}`,
-		`Period: ${context.from} → ${context.to ?? "now"} (grouped by ${context.groupBy})`,
-		"",
-		`Builds: ${builds.all.total}`,
-		`  Changes detected: ${builds.all.changesDetected}`,
-		`  No changes: ${builds.all.noChanges}`,
-		`  Accepted: ${builds.all.accepted}`,
-		`  Rejected: ${builds.all.rejected}`,
-		`Screenshots: ${screenshots.all.total}`
-	];
-	const names = /* @__PURE__ */ new Map();
-	for (const project of [...builds.projects, ...screenshots.projects]) names.set(project.id, project.name);
-	const ids = /* @__PURE__ */ new Set([...Object.keys(builds.all.projects), ...Object.keys(screenshots.all.projects)]);
-	if (ids.size > 0) {
-		const rows = [...ids].map((id) => ({
-			name: names.get(id) ?? id,
-			builds: builds.all.projects[id] ?? 0,
-			screenshots: screenshots.all.projects[id] ?? 0
-		})).sort((a, b) => b.builds - a.builds || b.screenshots - a.screenshots);
-		lines.push("", `Projects (${rows.length}):`);
-		for (const row of rows) lines.push(`  ${row.name}: ${row.builds} builds, ${row.screenshots} screenshots`);
-	}
-	return lines.join("\n");
-}
-function indent(text) {
-	return text.split("\n").map((line) => `  ${line}`).join("\n");
-}
-function formatAnchor(anchor) {
-	if (!anchor) return null;
-	return anchor.type === "point" ? `point ${anchor.x},${anchor.y}` : `lines ${anchor.from}-${anchor.to}`;
-}
-function formatReactions(reactions) {
-	if (reactions.length === 0) return null;
-	return reactions.map((r) => `${r.emoji} ${r.count}`).join(" ");
-}
-function formatComment(comment) {
-	const lines = [`Comment #${comment.id}`, `Author: ${formatUser(comment.author)}`];
-	if (comment.threadId) lines.push(`Reply to: ${comment.threadId}`);
-	if (comment.screenshotDiffId) {
-		const anchor = formatAnchor(comment.anchor);
-		lines.push(`Diff: ${comment.screenshotDiffId}${anchor ? ` (${anchor})` : ""}`);
-	}
-	if (comment.pending) lines.push("Pending: draft (only visible to you)");
-	if (comment.resolvedAt) lines.push(`Resolved: ${comment.resolvedAt}`);
-	const reactions = formatReactions(comment.reactions);
-	if (reactions) lines.push(`Reactions: ${reactions}`);
-	lines.push(`Date: ${comment.createdAt}${comment.editedAt ? " (edited)" : ""}`);
-	lines.push("", indent(comment.text));
-	return lines.join("\n");
-}
-function formatComments(comments) {
-	if (comments.length === 0) return "No comments found.";
-	return [
-		`Comments (${comments.length})`,
-		"",
-		...comments.flatMap((comment) => {
-			const tags = [
-				comment.threadId ? "reply" : "thread",
-				comment.pending ? "draft" : null,
-				comment.resolvedAt ? "resolved" : null
-			].filter(Boolean);
-			return [
-				`#${comment.id} [${tags.join(", ")}] ${formatUser(comment.author)}`,
-				indent(comment.text),
-				""
-			];
-		})
-	].slice(0, -1).join("\n");
-}
-//#endregion
-//#region src/lib/cli-error.ts
-/**
-* Error whose message is meant to be shown to the user verbatim (prefixed with
-* `Error: `) before the CLI exits with a non-zero code. Throw it — via
-* {@link fail} — instead of calling `process.exit` directly so the failure can
-* be unit-tested and handled in a single place ({@link handleCliError}).
-*/
-var CliError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "CliError";
-	}
-};
-/**
-* Abort the current command with a user-facing message.
-*/
-function fail(message) {
-	throw new CliError(message);
-}
-//#endregion
-//#region src/lib/oauth.ts
-/**
-* OAuth 2.1 client configuration and helpers for the `argos login` flow
-* (Authorization Code + PKCE with a loopback redirect, RFC 8252).
-*
-* The authorization server is the Snapvisor app origin; endpoints and token
-* validation are implemented in the main Snapvisor repo (`apps/backend/src/oauth`).
-*/
-/** First-party public client id, seeded in the Snapvisor database. */
-const OAUTH_CLIENT_ID = "argos-cli";
-/**
-* Scopes requested by `argos login`, covering the CLI's user actions (identity,
-* projects, reviews, comments). Build upload keeps using a project token.
-*/
-const OAUTH_SCOPES = [
-	"profile",
-	"projects:read",
-	"projects:write",
-	"reviews:write",
-	"comments:read",
-	"comments:write"
-];
-/** Refresh a bit early so a token never expires mid-request. */
-const EXPIRY_SKEW_MS = 60 * 1e3;
-function getAppBaseUrl() {
-	return process.env["ARGOS_APP_BASE_URL"] ?? "https://app.snapvisor.io/";
-}
-/**
-* A token endpoint request that reached the server and was rejected by it
-* (non-2xx / OAuth error), as opposed to a transient network failure. Lets
-* callers tell "your session is gone, log in again" from "the network is down".
-*/
-var OAuthTokenError = class extends Error {
-	code;
-	constructor(message, code) {
-		super(message);
-		this.code = code;
-		this.name = "OAuthTokenError";
-	}
-};
-function toTokenSet(data) {
-	return {
-		accessToken: data.access_token,
-		refreshToken: data.refresh_token,
-		expiresAt: Date.now() + data.expires_in * 1e3 - EXPIRY_SKEW_MS,
-		scope: data.scope ?? ""
-	};
-}
-/** Generate a PKCE `code_verifier` and its S256 `code_challenge`. */
-function generatePkce() {
-	const codeVerifier = randomBytes(32).toString("base64url");
-	return {
-		codeVerifier,
-		codeChallenge: createHash("sha256").update(codeVerifier).digest("base64url")
-	};
-}
-/** Build the `/oauth/authorize` URL to open in the browser. */
-function buildAuthorizeUrl(params) {
-	const url = new URL("/oauth/authorize", getAppBaseUrl());
-	url.searchParams.set("response_type", "code");
-	url.searchParams.set("client_id", OAUTH_CLIENT_ID);
-	url.searchParams.set("redirect_uri", params.redirectUri);
-	url.searchParams.set("scope", OAUTH_SCOPES.join(" "));
-	url.searchParams.set("state", params.state);
-	url.searchParams.set("code_challenge", params.codeChallenge);
-	url.searchParams.set("code_challenge_method", "S256");
-	return url.href;
-}
-async function postToken(body) {
-	const url = new URL("/oauth/token", getAppBaseUrl());
-	const response = await fetch(url, {
-		method: "POST",
-		headers: { "Content-Type": "application/x-www-form-urlencoded" },
-		body: new URLSearchParams(body).toString()
-	});
-	const data = await response.json().catch(() => null);
-	if (!response.ok || !data?.access_token) throw new OAuthTokenError(data?.error_description ?? data?.error ?? `HTTP ${response.status}`, data?.error);
-	if (typeof data.refresh_token !== "string" || data.refresh_token === "") throw new Error("Token endpoint response is missing a refresh token.");
-	if (typeof data.expires_in !== "number" || !Number.isFinite(data.expires_in)) throw new Error("Token endpoint response is missing a valid expiry.");
-	return data;
+async function postToken(body) {
+	const url = new URL("/oauth/token", getAppBaseUrl());
+	const response = await fetch(url, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams(body).toString()
+	});
+	const data = await response.json().catch(() => null);
+	if (!response.ok || !data?.access_token) throw new OAuthTokenError(data?.error_description ?? data?.error ?? `HTTP ${response.status}`, data?.error);
+	if (typeof data.refresh_token !== "string" || data.refresh_token === "") throw new Error("Token endpoint response is missing a refresh token.");
+	if (typeof data.expires_in !== "number" || !Number.isFinite(data.expires_in)) throw new Error("Token endpoint response is missing a valid expiry.");
+	return data;
 }
 /** Exchange an authorization code for a token set (`grant_type=authorization_code`). */
 async function exchangeAuthorizationCode(params) {
@@ -522,7 +203,7 @@ async function clearConfig() {
 		await unlink(configPath);
 	} catch {}
 }
-async function readConfig() {
+async function readConfig$1() {
 	const { configPath } = getConfigPaths();
 	try {
 		const config = parseConfig(await readFile(configPath, "utf8"));
@@ -554,7 +235,7 @@ async function saveOAuthTokens(tokens) {
 * falls back to a legacy personal access token when present.
 */
 async function getAccessToken() {
-	const config = await readConfig();
+	const config = await readConfig$1();
 	if (!config) return;
 	if (config.oauth) {
 		if (Date.now() < config.oauth.expiresAt) return config.oauth.accessToken;
@@ -573,7 +254,7 @@ async function getAccessToken() {
 }
 /** Read the stored credentials without refreshing (used by `logout`). */
 async function getStoredCredentials() {
-	const config = await readConfig();
+	const config = await readConfig$1();
 	return {
 		legacyToken: config?.token,
 		oauth: config?.oauth
@@ -585,7 +266,7 @@ async function clearStoredCredentials() {
 }
 //#endregion
 //#region src/lib/build-reference.ts
-const BUILD_URL_REGEXP = /^https:\/\/app\.argos-ci\.(?:com|dev(?::\d+)?)\/(?<owner>[^/?#]+)\/(?<project>[^/?#]+)\/builds\/(?<buildNumber>\d+)(?:[/?#]|$)/;
+const BUILD_URL_REGEXP = /^https:\/\/app\.(?:argos-ci\.(?:com|dev(?::\d+)?)|snapvisor\.io)\/(?<owner>[^/?#]+)\/(?<project>[^/?#]+)\/builds\/(?<buildNumber>\d+)(?:[/?#]|$)/;
 /**
 * Parse a build reference, accepting either a bare build number (`"1234"`) or a
 * full Snapvisor build URL. Returns `null` when the input is neither.
@@ -733,6 +414,526 @@ async function runBuildAction(opts) {
 	}
 }
 //#endregion
+//#region src/lib/wait-for-build.ts
+/** Commander argument parser for `--wait-timeout <seconds>`. */
+function parseWaitTimeout(value) {
+	const seconds = Number(value);
+	if (!Number.isInteger(seconds) || seconds <= 0) throw new InvalidArgumentError("Must be a positive whole number of seconds.");
+	return seconds;
+}
+/**
+* Reject option combinations `--wait` cannot honour, before anything is uploaded.
+* Returns the token used to poll the build, or `null` when not waiting.
+*/
+async function prepareWait(options) {
+	if (!options.wait) {
+		if (options.waitTimeout !== void 0) fail("--wait-timeout requires --wait.");
+		return null;
+	}
+	if (options.parallel || (await readConfig()).parallel) fail("--wait cannot be combined with --parallel (or ARGOS_PARALLEL): a parallel build only finishes once every shard is uploaded and the build is finalized, so waiting on one shard would time out.");
+	const token = options.token || process.env["ARGOS_TOKEN"];
+	if (!token) fail("--wait needs a project token to read the build back: pass --token or set ARGOS_TOKEN (GitHub Actions OIDC / tokenless uploads and `argos login` are not supported with --wait).");
+	return token;
+}
+const POLL_INTERVAL_MS = 5e3;
+/** Statuses a build can still leave: it is waiting for, or being processed by, the diff engine. */
+const IN_FLIGHT_STATUSES = ["pending", "progress"];
+function isFinalStatus(status) {
+	return !IN_FLIGHT_STATUSES.includes(status);
+}
+/**
+* Map a build that reached a final status to a pass/fail outcome.
+*
+* Passes: `accepted`, `no-changes`, and a `changes-detected` build whose commit
+* status is already `success` (a reference-branch build is auto-approved but
+* keeps the `changes-detected` API status). Everything else fails: a
+* `changes-detected` build with a pending status is waiting for a human review,
+* which is exactly what `--wait` exists to surface to CI, so the exit code
+* always agrees with the commit status.
+*/
+function evaluateFinalBuild(build) {
+	if (!isFinalStatus(build.status)) throw new Error(`Invariant: build #${build.number} is still "${build.status}", not final`);
+	const status = build.status;
+	const label = `Build #${build.number}`;
+	switch (status) {
+		case "accepted": return {
+			ok: true,
+			summary: `${label} accepted`
+		};
+		case "no-changes": return {
+			ok: true,
+			summary: `${label} has no changes`
+		};
+		case "changes-detected":
+			if (build.notification?.github.state === "success") return {
+				ok: true,
+				summary: `${label} has changes but its commit status is success (auto-approved)`
+			};
+			return {
+				ok: false,
+				summary: `${label} needs review (changes-detected)`
+			};
+		case "rejected": return {
+			ok: false,
+			summary: `${label} was rejected`
+		};
+		case "expired": return {
+			ok: false,
+			summary: `${label} expired`
+		};
+		case "error": return {
+			ok: false,
+			summary: `${label} failed with an error`
+		};
+		case "aborted": return {
+			ok: false,
+			summary: `${label} was aborted`
+		};
+		default: throw new Error(`Unhandled build status: ${String(status)}`);
+	}
+}
+/**
+* Extract `owner`, `project` and the build number from the build URL returned
+* by the API (`<app origin>/<owner>/<project>/builds/<number>`). Only the last
+* four path segments are read, so self-hosted origins work too.
+*/
+function parseBuildUrl(url) {
+	const [owner, project, builds, buildNumber] = new URL(url).pathname.split("/").filter(Boolean).slice(-4).map((segment) => {
+		try {
+			return decodeURIComponent(segment);
+		} catch (error) {
+			fail(`Cannot wait for build: malformed build URL "${url}" (${error instanceof Error ? error.message : String(error)}).`);
+		}
+	});
+	if (!owner || !project || builds !== "builds" || !buildNumber) fail(`Cannot wait for build: unexpected build URL "${url}" (expected .../<owner>/<project>/builds/<number>).`);
+	return {
+		owner,
+		project,
+		buildNumber
+	};
+}
+const realClock = {
+	now: () => Date.now(),
+	sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+};
+const MAX_RATE_LIMIT_BACKOFF_MS = 6e4;
+/**
+* How long to wait before retrying a 429: the `Retry-After` header (seconds or
+* HTTP date) when present and valid, else exponential backoff from the poll interval.
+*/
+function rateLimitDelayMs(response, attempt, pollIntervalMs, nowMs) {
+	const header = response.headers.get("retry-after");
+	if (header) {
+		const seconds = Number(header);
+		if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+		const date = Date.parse(header);
+		if (!Number.isNaN(date)) return Math.max(0, date - nowMs);
+	}
+	return Math.min(MAX_RATE_LIMIT_BACKOFF_MS, pollIntervalMs * 2 ** attempt);
+}
+/**
+* Poll a build until it reaches a final status and return its pass/fail
+* outcome. Throws a {@link CliError} when `timeoutSeconds` elapses first, and
+* lets API failures (401, 404, network errors, ...) propagate — a build we
+* cannot read must not look green. A 429 is retried (honouring `Retry-After`)
+* for as long as the deadline allows. Each request is aborted at the deadline,
+* so the wait never overshoots `timeoutSeconds` by a whole request.
+*/
+async function waitForBuild(opts) {
+	const { client, buildUrl, timeoutSeconds, pollIntervalMs = POLL_INTERVAL_MS, clock = realClock, onPoll } = opts;
+	const { owner, project, buildNumber } = parseBuildUrl(buildUrl);
+	const deadline = clock.now() + timeoutSeconds * 1e3;
+	let lastStatus = "not yet read";
+	let rateLimitAttempt = 0;
+	const getBuild = (signal) => client.GET("/projects/{owner}/{project}/builds/{buildNumber}", {
+		params: { path: {
+			owner,
+			project,
+			buildNumber
+		} },
+		signal
+	});
+	const timeout = () => fail(`Timed out after ${timeoutSeconds}s waiting for build #${buildNumber} to finish (last status: ${lastStatus}). ${buildUrl}`);
+	for (;;) {
+		const remainingMs = deadline - clock.now();
+		if (remainingMs <= 0) timeout();
+		const signal = AbortSignal.timeout(remainingMs);
+		let result;
+		try {
+			result = await getBuild(signal);
+		} catch (error) {
+			if (signal.aborted) timeout();
+			throw error;
+		}
+		if (result.response.status === 429) {
+			const delayMs = rateLimitDelayMs(result.response, rateLimitAttempt++, pollIntervalMs, clock.now());
+			lastStatus = "rate limited by the API (HTTP 429)";
+			if (delayMs >= deadline - clock.now()) timeout();
+			await clock.sleep(delayMs);
+			continue;
+		}
+		rateLimitAttempt = 0;
+		const build = unwrap(result);
+		lastStatus = build.status;
+		if (isFinalStatus(build.status)) return evaluateFinalBuild(build);
+		onPoll?.(build);
+		const untilDeadlineMs = deadline - clock.now();
+		if (untilDeadlineMs <= 0) timeout();
+		await clock.sleep(Math.min(pollIntervalMs, untilDeadlineMs));
+	}
+}
+//#endregion
+//#region src/options.ts
+const parallelNonceOption = new Option("--parallel-nonce <string>", "A unique ID for this parallel build");
+const tokenOption = new Option("--token <token>", "Repository token");
+const projectOption = new Option("--project <slug>", "Snapvisor project slug (account/project), used to disambiguate tokenless authentication when multiple projects are linked to the same repository");
+const buildNameOption = new Option("--build-name <string>", "Name of the build, in case you want to run multiple Snapvisor builds in a single CI job");
+const accountOption = new Option("--account <slug>", "Slug of the account (personal or team) that will own the project");
+const jsonOption = new Option("--json", "Output machine-readable JSON instead of human-readable text");
+const projectPathOption = new Option("--project <owner/project>", "Project path in owner/project format. Required for build-number references on review and comment commands");
+const changeProjectPathOption = new Option("--project <owner/project>", "Project the change belongs to, in owner/project format. Also ARGOS_PROJECT");
+const METRICS_PERIOD_BY_CHOICE = {
+	"24h": "LAST_24_HOURS",
+	"3d": "LAST_3_DAYS",
+	"7d": "LAST_7_DAYS",
+	"30d": "LAST_30_DAYS",
+	"90d": "LAST_90_DAYS"
+};
+const metricsPeriodOption = new Option("--metrics-period <period>", "Window over which test flakiness metrics are computed").choices(Object.keys(METRICS_PERIOD_BY_CHOICE)).default("7d");
+/** Map a `--metrics-period` choice to the value the API expects. */
+function toMetricsPeriod(choice) {
+	return METRICS_PERIOD_BY_CHOICE[choice] ?? "LAST_7_DAYS";
+}
+//#endregion
+//#region src/commands/upload.ts
+function uploadCommand(program) {
+	program.command("upload").argument("<directory>", "Directory to upload").description("Upload screenshots to Snapvisor").option("-f, --files <patterns...>", "One or more globs matching image file paths to upload", "**/*.{png,jpg,jpeg}").option("-i, --ignore <patterns...>", "One or more globs matching image file paths to ignore (ex: \"**/*.png **/diff.jpg\")").addOption(tokenOption).addOption(projectOption).addOption(buildNameOption).addOption(new Option("--mode <string>", "Mode of comparison applied. CI for visual regression testing, monitoring for visual monitoring.").default("ci").choices(["ci", "monitoring"])).addOption(new Option("--parallel", "Enable parallel mode. Run multiple Snapvisor builds and combine them at the end.\nCan also be set via the ARGOS_PARALLEL environment variable.")).addOption(new Option("--parallel-total <number>", "The number of parallel nodes being ran")).addOption(parallelNonceOption).addOption(new Option("--parallel-index <number>", "The index of the parallel node being ran (must be at least 1)")).addOption(new Option("--reference-branch <string>", "Branch used as baseline for screenshot comparison")).addOption(new Option("--reference-commit <string>", "Commit used as baseline for screenshot comparison")).addOption(new Option("--threshold <number>", "Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff will be. Default to 0.5")).addOption(new Option("--subset", "Whether this build contains only a subset of screenshots.\nThis is useful when a build is created from an incomplete test suite where some tests are skipped.\nCan also be set via the ARGOS_SUBSET environment variable.")).addOption(new Option("--wait", "Wait for the build to finish, then exit 0 if it is accepted or has no changes, and exit 1 if it needs review, is rejected, expired, aborted or errored, or if the wait times out.\nRequires a token (--token, ARGOS_TOKEN) and cannot be combined with --parallel.")).addOption(new Option("--wait-timeout <seconds>", `Maximum time to wait for the build when --wait is set. Defaults to 600.`).argParser(parseWaitTimeout)).action(async (directory, options) => {
+		let waitToken;
+		try {
+			waitToken = await prepareWait({
+				wait: options.wait,
+				waitTimeout: options.waitTimeout,
+				parallel: options.parallel,
+				token: options.token
+			});
+		} catch (error) {
+			handleCliError(error);
+		}
+		const spinner = ora("Uploading screenshots").start();
+		let buildUrl;
+		try {
+			const parallel = (() => {
+				if (!options.parallel) return;
+				if (!options.parallelNonce) {
+					spinner.fail("--parallel-nonce is required if --parallel is set");
+					process.exit(1);
+				}
+				if (!options.parallelTotal) {
+					spinner.fail("--parallel-total is required if --parallel is set");
+					process.exit(1);
+				}
+				return {
+					nonce: options.parallelNonce,
+					total: options.parallelTotal,
+					index: options.parallelIndex
+				};
+			})();
+			buildUrl = (await upload({
+				token: options.token,
+				project: options.project,
+				root: directory,
+				buildName: options.buildName,
+				files: options.files,
+				ignore: options.ignore,
+				parallel,
+				referenceBranch: options.referenceBranch,
+				referenceCommit: options.referenceCommit,
+				mode: options.mode,
+				threshold: options.threshold,
+				subset: options.subset
+			})).build.url;
+			spinner.succeed(`Build created: ${buildUrl}`);
+		} catch (error) {
+			if (error instanceof Error) {
+				spinner.fail(`Build failed: ${error.message}`);
+				console.error(error.stack);
+			}
+			process.exit(1);
+		}
+		if (waitToken === null) return;
+		const waitSpinner = ora("Waiting for the build to finish").start();
+		try {
+			const outcome = await waitForBuild({
+				client: createApiClient(waitToken),
+				buildUrl,
+				timeoutSeconds: options.waitTimeout ?? 600,
+				onPoll: (build) => {
+					waitSpinner.text = `Waiting for the build to finish (status: ${build.status})`;
+				}
+			});
+			if (outcome.ok) waitSpinner.succeed(`${outcome.summary}: ${buildUrl}`);
+			else {
+				waitSpinner.fail(`${outcome.summary}: ${buildUrl}`);
+				process.exit(1);
+			}
+		} catch (error) {
+			waitSpinner.fail("Waiting for the build failed");
+			handleCliError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/finalize.ts
+const skipIfEmptyOption = new Option("--skip-if-empty", "Create a skipped build when no parallel build matches the nonce.\nUseful when uploads are conditional (e.g. skipped by a CI cache) and Snapvisor is a required status check: the skipped build reports a success status even though nothing was uploaded.");
+function finalizeCommand(program) {
+	program.command("finalize").description("Finalize pending parallel builds").addOption(parallelNonceOption).addOption(tokenOption).addOption(skipIfEmptyOption).addOption(buildNameOption).action(async (options) => {
+		const spinner = ora("Finalizing builds").start();
+		try {
+			const result = await finalize({
+				token: options.token,
+				parallel: options.parallelNonce ? { nonce: options.parallelNonce } : void 0,
+				skipIfEmpty: options.skipIfEmpty,
+				buildName: options.buildName
+			});
+			spinner.succeed(result.skippedBuild ? `No builds to finalize — skipped build created: ${result.skippedBuild.url}` : result.builds.length === 0 ? "No builds to finalize" : `Builds finalized: ${result.builds.map((b) => b.url).join(", ")}`);
+		} catch (error) {
+			if (error instanceof Error) {
+				spinner.fail(`Failed to finalize: ${error.message}`);
+				console.error(error.stack);
+			}
+			process.exit(1);
+		}
+	});
+}
+//#endregion
+//#region src/commands/skip.ts
+function skipCommand(program) {
+	program.command("skip").description("Mark a build as skipped").addOption(tokenOption).addOption(buildNameOption).action(async (options) => {
+		const spinner = ora("Creating skipped build").start();
+		try {
+			const result = await skip({
+				token: options.token,
+				buildName: options.buildName
+			});
+			spinner.succeed(`Build created: ${result.build.url}`);
+		} catch (error) {
+			if (error instanceof Error) {
+				spinner.fail(`Build failed: ${error.message}`);
+				console.error(error.stack);
+			}
+			process.exit(1);
+		}
+	});
+}
+//#endregion
+//#region src/lib/format.ts
+/** Render a scalar, using `-` for empty values. */
+function formatValue(value) {
+	if (value === null || value === void 0 || value === "") return "-";
+	return String(value);
+}
+function formatUser(user) {
+	if (!user) return "-";
+	return user.name ? `${user.name} (@${user.slug})` : `@${user.slug}`;
+}
+function formatMe(me) {
+	const lines = [
+		`Logged in to Snapvisor as ${formatValue(me.user.name)}.`,
+		`Name: ${formatValue(me.user.name)}`,
+		`Email: ${formatValue(me.user.email)}`
+	];
+	if (me.accounts.length > 0) lines.push(`Accounts: ${me.accounts.map((a) => `@${a.slug}`).join(", ")}`);
+	return lines.join("\n");
+}
+function formatProject(project) {
+	return [
+		`Created project ${project.account.slug}/${project.name}.`,
+		`ID: ${project.id}`,
+		`Name: ${project.name}`,
+		`Account: ${project.account.slug}`,
+		`Default base branch: ${formatValue(project.defaultBaseBranch)}`
+	].join("\n");
+}
+function formatStats(stats) {
+	if (!stats) return "-";
+	return [
+		`total ${stats.total}`,
+		`changed ${stats.changed}`,
+		`added ${stats.added}`,
+		`removed ${stats.removed}`,
+		`unchanged ${stats.unchanged}`
+	].join(", ");
+}
+const SNAPSHOT_STATUS_ORDER = [
+	"changed",
+	"added",
+	"removed",
+	"unchanged",
+	"ignored",
+	"pending",
+	"failure",
+	"retryFailure"
+];
+function formatSnapshotSummary(diffs) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const diff of diffs) counts.set(diff.status, (counts.get(diff.status) ?? 0) + 1);
+	return SNAPSHOT_STATUS_ORDER.map((status) => {
+		const count = counts.get(status);
+		return count ? `${status} ${count}` : null;
+	}).filter((part) => Boolean(part)).join(", ");
+}
+function formatBuild(build) {
+	return [
+		`Build #${build.number}`,
+		`Status: ${build.status}`,
+		`Snapshots: ${formatStats(build.stats)}`,
+		`Conclusion: ${formatValue(build.conclusion)}`,
+		`Branch: ${formatValue(build.head?.branch)}`,
+		`Commit: ${formatValue(build.head?.sha)}`,
+		`Base branch: ${formatValue(build.base?.branch)}`,
+		`Base commit: ${formatValue(build.base?.sha)}`,
+		`URL: ${build.url}`
+	].join("\n");
+}
+/** Render a 0–1 metric to two decimals, or `-` when absent. */
+function formatRatio(value) {
+	return value === null || value === void 0 ? "-" : value.toFixed(2);
+}
+/** Compact one-line summary of a test's flakiness metrics. */
+function formatFlakiness(metrics) {
+	return `${formatRatio(metrics.flakiness)} (stability ${formatRatio(metrics.stability)}, consistency ${formatRatio(metrics.consistency)})`;
+}
+/** Human-readable lines for a single snapshot diff. */
+function formatSnapshotDiff(diff, build) {
+	const lines = [
+		`${diff.name} [${diff.status}]`,
+		`  Review: ${build.url}/${diff.id}`,
+		`  Mask: ${formatValue(diff.url)}`,
+		`  Base file: ${formatValue(diff.base?.url)}`,
+		`  Head file: ${formatValue(diff.head?.url)}`,
+		`  Score: ${formatValue(diff.score)}`,
+		`  Group: ${formatValue(diff.group)}`
+	];
+	if (diff.test) lines.push(`  Flakiness: ${formatFlakiness(diff.test.metrics)}`);
+	if (diff.change) {
+		const ignored = diff.change.ignored ? " [ignored]" : "";
+		lines.push(`  Change: ${diff.change.id}${ignored} · ${diff.change.occurrences} occurrences`);
+	}
+	return lines;
+}
+function formatSnapshots(diffs, build) {
+	if (diffs.length === 0) return "No snapshots found.";
+	return [
+		`Snapshots for build #${build.number}`,
+		`Count: ${diffs.length}`,
+		`Summary: ${formatSnapshotSummary(diffs)}`,
+		"",
+		...diffs.flatMap((diff) => [...formatSnapshotDiff(diff, build), ""])
+	].slice(0, -1).join("\n");
+}
+function formatChange(change) {
+	return [
+		`Change ${change.id}`,
+		`Ignored: ${change.ignored ? "yes" : "no"}`,
+		`Occurrences: ${change.occurrences}`
+	].join("\n");
+}
+function formatReview(review) {
+	const lines = [
+		`Review #${review.id}`,
+		`State: ${review.state}`,
+		`Author: ${formatUser(review.user)}`,
+		`Date: ${review.date}`
+	];
+	if (review.dismissedAt) lines.push(`Dismissed: ${review.dismissedAt} by ${formatUser(review.dismissedBy)}`);
+	return lines.join("\n");
+}
+function formatReviews(reviews) {
+	if (reviews.length === 0) return "No reviews found.";
+	return [
+		`Reviews (${reviews.length})`,
+		"",
+		...reviews.flatMap((review) => [
+			`#${review.id} [${review.state}${review.dismissedAt ? ", dismissed" : ""}]`,
+			`  Author: ${formatUser(review.user)}`,
+			`  Date: ${review.date}`,
+			""
+		])
+	].slice(0, -1).join("\n");
+}
+function formatAnalytics(analytics, context) {
+	const { screenshots, builds } = analytics;
+	const lines = [
+		`Analytics for ${context.account}`,
+		`Period: ${context.from} → ${context.to ?? "now"} (grouped by ${context.groupBy})`,
+		"",
+		`Builds: ${builds.all.total}`,
+		`  Changes detected: ${builds.all.changesDetected}`,
+		`  No changes: ${builds.all.noChanges}`,
+		`  Accepted: ${builds.all.accepted}`,
+		`  Rejected: ${builds.all.rejected}`,
+		`Screenshots: ${screenshots.all.total}`
+	];
+	const names = /* @__PURE__ */ new Map();
+	for (const project of [...builds.projects, ...screenshots.projects]) names.set(project.id, project.name);
+	const ids = /* @__PURE__ */ new Set([...Object.keys(builds.all.projects), ...Object.keys(screenshots.all.projects)]);
+	if (ids.size > 0) {
+		const rows = [...ids].map((id) => ({
+			name: names.get(id) ?? id,
+			builds: builds.all.projects[id] ?? 0,
+			screenshots: screenshots.all.projects[id] ?? 0
+		})).sort((a, b) => b.builds - a.builds || b.screenshots - a.screenshots);
+		lines.push("", `Projects (${rows.length}):`);
+		for (const row of rows) lines.push(`  ${row.name}: ${row.builds} builds, ${row.screenshots} screenshots`);
+	}
+	return lines.join("\n");
+}
+function indent(text) {
+	return text.split("\n").map((line) => `  ${line}`).join("\n");
+}
+function formatAnchor(anchor) {
+	if (!anchor) return null;
+	return anchor.type === "point" ? `point ${anchor.x},${anchor.y}` : `lines ${anchor.from}-${anchor.to}`;
+}
+function formatReactions(reactions) {
+	if (reactions.length === 0) return null;
+	return reactions.map((r) => `${r.emoji} ${r.count}`).join(" ");
+}
+function formatComment(comment) {
+	const lines = [`Comment #${comment.id}`, `Author: ${formatUser(comment.author)}`];
+	if (comment.threadId) lines.push(`Reply to: ${comment.threadId}`);
+	if (comment.screenshotDiffId) {
+		const anchor = formatAnchor(comment.anchor);
+		lines.push(`Diff: ${comment.screenshotDiffId}${anchor ? ` (${anchor})` : ""}`);
+	}
+	if (comment.pending) lines.push("Pending: draft (only visible to you)");
+	if (comment.resolvedAt) lines.push(`Resolved: ${comment.resolvedAt}`);
+	const reactions = formatReactions(comment.reactions);
+	if (reactions) lines.push(`Reactions: ${reactions}`);
+	lines.push(`Date: ${comment.createdAt}${comment.editedAt ? " (edited)" : ""}`);
+	lines.push("", indent(comment.text));
+	return lines.join("\n");
+}
+function formatComments(comments) {
+	if (comments.length === 0) return "No comments found.";
+	return [
+		`Comments (${comments.length})`,
+		"",
+		...comments.flatMap((comment) => {
+			const tags = [
+				comment.threadId ? "reply" : "thread",
+				comment.pending ? "draft" : null,
+				comment.resolvedAt ? "resolved" : null
+			].filter(Boolean);
+			return [
+				`#${comment.id} [${tags.join(", ")}] ${formatUser(comment.author)}`,
+				indent(comment.text),
+				""
+			];
+		})
+	].slice(0, -1).join("\n");
+}
+//#endregion
 //#region src/commands/build/get.ts
 function registerBuildGet(build) {
 	build.command("get").description("Fetch build metadata").argument("<buildReference>", "Build number or Argos build URL").addOption(tokenOption).addOption(jsonOption).action((reference, options) => runBuildAction({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@snapvisor/cli",
   "description": "Command-line (CLI) for visual testing with Snapvisor.",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "bin": {
     "snapvisor": "./bin/argos-cli.js",
     "argos": "./bin/argos-cli.js"
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@snapvisor/api-client": "0.27.0",
-    "@snapvisor/core": "7.0.0",
+    "@snapvisor/core": "7.0.1",
     "commander": "^15.0.0",
     "open": "^11.0.0",
     "ora": "^9.4.0",
@@ -55,5 +55,5 @@
     "check-format": "prettier --check --ignore-unknown --ignore-path=../../.gitignore --ignore-path=../../.prettierignore .",
     "lint": "eslint ."
   },
-  "gitHead": "b27308a53667724cc3c4f3e5eb7811bce3321f15"
+  "gitHead": "60252cc8da90a38220fd44333e3ac88470bb63ab"
 }