ccqa 1.51.0 → 1.52.0

package/dist/evidence-constants-BufWx8Bt.cjs

@@ -0,0 +1,59 @@
+//#region src/runtime/evidence-constants.ts
+/**
+* Shared constants + helpers for step-boundary evidence: the env var that
+* enables capture, the file-name sanitizer, and the reserved failure ids.
+*
+* Three producers write the `<id>.png` + `<id>.json` pairs — `abStepEvidence()`
+* / `captureFailureEvidence()` in `test-helpers.ts` (agent-browser replays) and
+* `ccqaStepBefore`/`ccqaStepAfter` in `step-evidence.ts` (external targets) —
+* and one consumer reads them back (`loadEvidenceForSpec` in
+* `report/evidence.ts`). All four agree only on the contract here, so it is
+* kept under `runtime/` (free of CLI-side imports) so the generated-test
+* modules — imported via `ccqa/test-helpers` and `ccqa/step-evidence` — can
+* share it without dragging the CLI in.
+*/
+/**
+* Env var naming the directory a spec's step evidence is written to. `ccqa
+* run` sets it per spec; unset means "capture nothing", which is what keeps a
+* hand-run generated test (or the generation-time verify loop) from
+* scattering screenshots.
+*/
+const EVIDENCE_DIR_ENV = "CCQA_EVIDENCE_DIR";
+/**
+* Make a step id safe to use as an evidence file-name stem. Both evidence
+* producers (agent-browser `abStepEvidence`, external `ccqa/step-evidence`)
+* name their PNG/JSON pair `<stem>.png` / `<stem>.json`, so they must agree on
+* this exact mapping.
+*/
+function sanitizeStepId(stepId) {
+	return stepId.replace(/[^A-Za-z0-9_.-]/g, "_");
+}
+/** stepId reserved for the screenshot captured by fail() at the moment of an assertion failure. */
+const FAILURE_STEP_ID = "failure";
+/** source value paired with FAILURE_STEP_ID so the report can tell failure captures apart from step captures. */
+const FAILURE_SOURCE = "failed";
+//#endregion
+Object.defineProperty(exports, "EVIDENCE_DIR_ENV", {
+	enumerable: true,
+	get: function() {
+		return EVIDENCE_DIR_ENV;
+	}
+});
+Object.defineProperty(exports, "FAILURE_SOURCE", {
+	enumerable: true,
+	get: function() {
+		return FAILURE_SOURCE;
+	}
+});
+Object.defineProperty(exports, "FAILURE_STEP_ID", {
+	enumerable: true,
+	get: function() {
+		return FAILURE_STEP_ID;
+	}
+});
+Object.defineProperty(exports, "sanitizeStepId", {
+	enumerable: true,
+	get: function() {
+		return sanitizeStepId;
+	}
+});

package/dist/hub-client/index.cjs

@@ -0,0 +1,434 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/hub-client/index.ts
+var HubApiError = class extends Error {
+	status;
+	code;
+	constructor(status, code, message) {
+		super(message);
+		this.status = status;
+		this.code = code;
+	}
+};
+/** Per-attempt fetch timeout. Bounds how long a stalled socket can block a poll loop. */
+const REQUEST_TIMEOUT_MS = 3e4;
+/**
+* HTTP methods safe to retry: GET is a pure read, and DELETE is idempotent
+* (deleting an already-deleted resource is a no-op, not a new side effect).
+* POST/PUT are never retried — a POST that "failed" after the server
+* already committed it (e.g. a dropped response to pushRun) would create a
+* duplicate run on retry, and PUT-driven imports would double-apply.
+*/
+const RETRYABLE_METHODS = new Set(["GET", "DELETE"]);
+/** Fixed backoff between retry attempts, in ms. */
+const RETRY_BACKOFF_MS = [
+	100,
+	300,
+	900
+];
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function throwHubApiError(res) {
+	let code = "unknown_error";
+	let message = res.statusText;
+	try {
+		const body = await res.json();
+		if (body.error?.code) code = body.error.code;
+		if (body.error?.message) message = body.error.message;
+	} catch {}
+	throw new HubApiError(res.status, code, message);
+}
+/**
+* One round trip against a hub, with the client's shared policy: bearer auth,
+* per-attempt timeout, retries for idempotent methods, `HubApiError` on the
+* final non-ok answer. Exported for the one caller outside the client
+* (`CoverageInbox`), whose POSTs are appends a duplicate cannot corrupt —
+* unlike the client's own POSTs — so it may opt into `retry: "post-once"`,
+* one extra attempt after a 5xx or network error.
+*/
+async function hubRequest(opts, path, init = {}, retry) {
+	const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+	const doFetch = opts.fetchImpl ?? fetch;
+	const method = (init.method ?? "GET").toUpperCase();
+	const maxAttempts = retry === "post-once" ? 2 : RETRYABLE_METHODS.has(method) ? RETRY_BACKOFF_MS.length + 1 : 1;
+	for (let attempt = 0; attempt < maxAttempts; attempt++) {
+		const signal = init.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+		let res;
+		try {
+			res = await doFetch(`${baseUrl}${path}`, {
+				...init,
+				signal,
+				headers: {
+					...opts.headers,
+					...init.headers,
+					Authorization: `Bearer ${opts.token}`
+				}
+			});
+		} catch (err) {
+			if (attempt < maxAttempts - 1) {
+				await sleep(RETRY_BACKOFF_MS[attempt]);
+				continue;
+			}
+			throw err;
+		}
+		if (res.ok) return res;
+		if (res.status >= 500 && attempt < maxAttempts - 1) {
+			await sleep(RETRY_BACKOFF_MS[attempt]);
+			continue;
+		}
+		return throwHubApiError(res);
+	}
+	throw new Error("unreachable");
+}
+function createHubClient(opts) {
+	function request(path, init = {}) {
+		return hubRequest(opts, path, init);
+	}
+	async function json(path, init) {
+		return (await request(path, init)).json();
+	}
+	async function bytes(path, init) {
+		const buf = await (await request(path, init)).arrayBuffer();
+		return new Uint8Array(buf);
+	}
+	async function text(path, init) {
+		return (await request(path, init)).text();
+	}
+	function noBody(path, method) {
+		return request(path, { method }).then(() => void 0);
+	}
+	function putJson(path, body) {
+		return request(path, {
+			method: "PUT",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body)
+		}).then(() => void 0);
+	}
+	return {
+		pushRun(archive, meta) {
+			const params = new URLSearchParams({ project: meta.project });
+			if (meta.branch) params.set("branch", meta.branch);
+			if (meta.profile) params.set("profile", meta.profile);
+			if (meta.kind) params.set("kind", meta.kind);
+			if (meta.deployedSha) params.set("deployedSha", meta.deployedSha);
+			return json(`/api/v1/runs?${params}`, {
+				method: "POST",
+				headers: { "Content-Type": "application/gzip" },
+				body: toBodyInit(archive)
+			});
+		},
+		openRun(meta) {
+			const params = new URLSearchParams({ project: meta.project });
+			if (meta.branch) params.set("branch", meta.branch);
+			if (meta.profile) params.set("profile", meta.profile);
+			if (meta.kind) params.set("kind", meta.kind);
+			if (meta.gitHead) params.set("gitHead", meta.gitHead);
+			if (meta.deployedSha) params.set("deployedSha", meta.deployedSha);
+			if (meta.ciRunId) params.set("ciRunId", meta.ciRunId);
+			if (meta.runUrl) params.set("runUrl", meta.runUrl);
+			return json(`/api/v1/runs/open?${params}`, { method: "POST" });
+		},
+		patchRun(id, body) {
+			return json(`/api/v1/runs/${encodeURIComponent(id)}`, {
+				method: "PATCH",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body)
+			});
+		},
+		async listRuns(q = {}) {
+			const { runs } = await json(`/api/v1/runs?${queryString(q)}`);
+			return runs;
+		},
+		getRun(id) {
+			return json(`/api/v1/runs/${encodeURIComponent(id)}`);
+		},
+		getReport(id) {
+			return json(`/api/v1/runs/${encodeURIComponent(id)}/report`);
+		},
+		downloadArtifacts(id) {
+			return bytes(`/api/v1/runs/${encodeURIComponent(id)}/artifacts`);
+		},
+		getCoverage(project, q = {}) {
+			return json(`/api/v1/coverage?${queryString({
+				project,
+				runId: q.runId
+			})}`);
+		},
+		putCoverageEdges(project, upsert) {
+			return request(`/api/v1/projects/${encodeURIComponent(project)}/coverage-edges`, {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(upsert)
+			}).then(() => void 0);
+		},
+		async getCoverageEdges(project) {
+			try {
+				return await json(`/api/v1/projects/${encodeURIComponent(project)}/coverage-edges`);
+			} catch (err) {
+				if (err instanceof HubApiError && err.status === 404) return null;
+				throw err;
+			}
+		},
+		putSourceMap(project, commit, assetPath, map) {
+			return request(`${sourceMapPath(project, commit)}/${encodeAssetPath(assetPath)}`, {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: toBodyInit(map)
+			}).then(() => void 0);
+		},
+		async getSourceMap(project, commit, assetPath) {
+			try {
+				return await text(`${sourceMapPath(project, commit)}/${encodeAssetPath(assetPath)}`);
+			} catch (err) {
+				if (err instanceof HubApiError && err.status === 404) return null;
+				throw err;
+			}
+		},
+		sweepSourceMaps(project) {
+			return noBody(`/api/v1/projects/${encodeURIComponent(project)}/sourcemaps/sweep`, "POST");
+		},
+		async listSourceMaps(project, commit) {
+			const { paths } = await json(sourceMapPath(project, commit));
+			return paths;
+		},
+		getTriage(id) {
+			return json(`/api/v1/runs/${encodeURIComponent(id)}/triage`);
+		},
+		putActualCause(id, c, v) {
+			return json(`/api/v1/runs/${encodeURIComponent(id)}/triage/${encodeURIComponent(c.feature)}/${encodeURIComponent(c.spec)}/actual-cause`, {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(v)
+			});
+		},
+		deleteActualCause(id, c) {
+			return noBody(`/api/v1/runs/${encodeURIComponent(id)}/triage/${encodeURIComponent(c.feature)}/${encodeURIComponent(c.spec)}/actual-cause`, "DELETE");
+		},
+		importActualCauses(id, labels) {
+			return json(`/api/v1/runs/${encodeURIComponent(id)}/triage/actual-causes`, {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(labels)
+			});
+		},
+		async getLastGreen(project, q) {
+			const params = queryString({
+				branch: q.branch,
+				...q.profile ? { profile: q.profile } : {},
+				...q.fallbackBranch ? { fallbackBranch: q.fallbackBranch } : {}
+			});
+			const { entries } = await json(`/api/v1/projects/${encodeURIComponent(project)}/last-green?${params}`);
+			return entries;
+		},
+		getRerun(project, q) {
+			return json(`/api/v1/projects/${encodeURIComponent(project)}/rerun?${queryString({ profile: q.profile })}`);
+		},
+		acquireLocks(project, q, body) {
+			return json(`${locksPath(project)}?${queryString({ profile: q.profile })}`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body)
+			});
+		},
+		async releaseLocks(project, q, holder) {
+			await request(`${locksPath(project)}?${queryString({ profile: q.profile })}`, {
+				method: "DELETE",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ holder })
+			});
+		},
+		getAttestations(project, q) {
+			return json(`${attestationsPath(project)}?${queryString({ profile: q.profile })}`);
+		},
+		putAttestation(project, q, body) {
+			return json(`${attestationsPath(project)}?${queryString({ profile: q.profile })}`, {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body)
+			});
+		},
+		async deleteAttestation(project, q, spec) {
+			await request(`${attestationsPath(project)}?${queryString({ profile: q.profile })}`, {
+				method: "DELETE",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ spec })
+			});
+		},
+		getAuditDismissals(project) {
+			return json(auditDismissalsPath(project));
+		},
+		putAuditDismissal(project, body) {
+			return json(auditDismissalsPath(project), {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body)
+			});
+		},
+		async deleteAuditDismissal(project, spec) {
+			await request(auditDismissalsPath(project), {
+				method: "DELETE",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ spec })
+			});
+		},
+		getAuditNeed(project, q) {
+			return json(`/api/v1/projects/${encodeURIComponent(project)}/audit-needed?${queryString({ profile: q.profile })}`);
+		},
+		getDriftLedger(project) {
+			return json(`/api/v1/projects/${encodeURIComponent(project)}/drift`);
+		},
+		recordDeploy(project, profile, body) {
+			return json(`${deploysPath(project)}?${queryString({ profile })}`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body)
+			});
+		},
+		getDeployLog(project, q) {
+			return json(`${deploysPath(project)}?${queryString({
+				profile: q.profile,
+				limit: q.limit
+			})}`);
+		},
+		recordSpend(project, body) {
+			return json(spendPath(project), {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body)
+			});
+		},
+		getSpend(project, q = {}) {
+			return json(`${spendPath(project)}?${queryString({
+				since: q.since,
+				until: q.until
+			})}`);
+		},
+		async listProjects() {
+			const { projects } = await json("/api/v1/projects");
+			return projects;
+		},
+		putSession(project, profile, name, storageState) {
+			return putJson(`${scopePath(project, "sessions", profile)}/${encodeURIComponent(name)}`, storageState);
+		},
+		getSession(project, profile, name) {
+			return json(`${scopePath(project, "sessions", profile)}/${encodeURIComponent(name)}`);
+		},
+		async listSessions(project, profile) {
+			const { sessions } = await json(scopePath(project, "sessions", profile));
+			return sessions;
+		},
+		deleteSession(project, profile, name) {
+			return noBody(`${scopePath(project, "sessions", profile)}/${encodeURIComponent(name)}`, "DELETE");
+		},
+		putVariable(project, profile, name, v) {
+			return putJson(`${scopePath(project, "variables", profile)}/${encodeURIComponent(name)}`, v);
+		},
+		async listVariables(project, profile, opts = {}) {
+			const query = opts.includeValues ? "?include=values" : "";
+			const { variables } = await json(`${scopePath(project, "variables", profile)}${query}`);
+			return variables;
+		},
+		deleteVariable(project, profile, name) {
+			return noBody(`${scopePath(project, "variables", profile)}/${encodeURIComponent(name)}`, "DELETE");
+		},
+		putPrompt(project, name, body) {
+			return request(`${promptsPath(project)}/${encodeURIComponent(name)}`, {
+				method: "PUT",
+				headers: { "Content-Type": "text/markdown; charset=utf-8" },
+				body
+			}).then(() => void 0);
+		},
+		async getPrompt(project, name) {
+			try {
+				return await text(`${promptsPath(project)}/${encodeURIComponent(name)}`);
+			} catch (err) {
+				if (err instanceof HubApiError && err.status === 404) return null;
+				throw err;
+			}
+		},
+		async listPrompts(project) {
+			const { prompts } = await json(promptsPath(project));
+			return prompts;
+		},
+		deletePrompt(project, name) {
+			return noBody(`${promptsPath(project)}/${encodeURIComponent(name)}`, "DELETE");
+		},
+		putPerspectives(project, doc) {
+			return putJson(perspectivesPath(project), doc);
+		},
+		patchPerspectivesNote(project, c) {
+			return request(perspectivesPath(project), {
+				method: "PATCH",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(c)
+			}).then(() => void 0);
+		},
+		async getPerspectives(project) {
+			try {
+				return await json(perspectivesPath(project));
+			} catch (err) {
+				if (err instanceof HubApiError && err.status === 404) return null;
+				throw err;
+			}
+		},
+		deletePerspectives(project) {
+			return noBody(perspectivesPath(project), "DELETE");
+		}
+	};
+}
+/** `/api/v1/projects/<project>/<kind>/<profile>` — the scope prefix secret endpoints share. */
+function scopePath(project, kind, profile) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/${kind}/${encodeURIComponent(profile)}`;
+}
+/** Prompts are project-scoped (not per-profile): `/api/v1/projects/<project>/prompts`. */
+function promptsPath(project) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/prompts`;
+}
+/** The deploy log is per project, selected by a `?profile=` query param: `/api/v1/projects/<project>/deploys`. */
+function deploysPath(project) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/deploys`;
+}
+function spendPath(project) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/spend`;
+}
+function locksPath(project) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/locks`;
+}
+function attestationsPath(project) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/attestations`;
+}
+function auditDismissalsPath(project) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/audit-dismissals`;
+}
+/** Perspectives are one document per project: `/api/v1/projects/<project>/perspectives`. */
+function perspectivesPath(project) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/perspectives`;
+}
+/** `/api/v1/projects/<project>/sourcemaps/<commit>` — the scope a push and a read share. */
+function sourceMapPath(project, commit) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/sourcemaps/${encodeURIComponent(commit)}`;
+}
+/**
+* Asset paths keep their separators — the route matches the rest of the URL as
+* one wildcard segment — so only the parts between them are escaped.
+*/
+function encodeAssetPath(assetPath) {
+	return assetPath.split("/").map(encodeURIComponent).join("/");
+}
+function queryString(params) {
+	const out = new URLSearchParams();
+	for (const [key, value] of Object.entries(params)) if (value !== void 0) out.set(key, String(value));
+	return out;
+}
+/**
+* `Uint8Array` isn't a valid `BodyInit` in every fetch implementation's
+* types (browser lib.dom vs Node's undici disagree) — go through a plain
+* `ArrayBuffer` slice, which every implementation accepts.
+*/
+function toBodyInit(bytes) {
+	return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+//#endregion
+exports.HubApiError = HubApiError;
+exports.createHubClient = createHubClient;
+exports.hubRequest = hubRequest;