ccqa 0.10.2 → 0.11.0

package/dist/hub-client/index.d.mts

@@ -0,0 +1,246 @@
+import { z } from "zod";
+
+//#region src/hub/contract/schema.d.ts
+/**
+ * The hub's public REST contract (docs/hub-api.md). These schemas are
+ * consumed on both sides of the wire: the hub validates request/response
+ * bodies against them, and `ccqa/hub-client` re-exports them so any HTTP
+ * client — the ccqa CLI, an intranet web app, the hub's own bundled UI —
+ * gets the same types.
+ */
+/**
+ * A run's outcome. The hub never executes — a run is created when a client
+ * pushes the report of an already-finished `ccqa run`, so the only two
+ * terminal states that reach the hub are "passed" and "failed".
+ */
+declare const RunStatusSchema: z.ZodEnum<{
+  passed: "passed";
+  failed: "failed";
+}>;
+type RunStatus = z.infer<typeof RunStatusSchema>;
+/**
+ * A pushed run. All fields are derived server-side from the report the client
+ * pushed (`POST /runs`) — the run is immutable once created.
+ */
+declare const RunSchema: z.ZodObject<{
+  id: z.ZodString;
+  project: z.ZodString;
+  profile: z.ZodNullable<z.ZodString>;
+  branch: z.ZodNullable<z.ZodString>;
+  status: z.ZodEnum<{
+    passed: "passed";
+    failed: "failed";
+  }>;
+  specs: z.ZodObject<{
+    total: z.ZodNumber;
+    passed: z.ZodNumber;
+    failed: z.ZodNumber;
+  }, z.core.$strip>;
+  gitHead: z.ZodNullable<z.ZodString>;
+  promptVersion: z.ZodString;
+  ciRunId: z.ZodNullable<z.ZodString>;
+  reportCreatedAt: z.ZodString;
+  createdAt: z.ZodString;
+}, z.core.$strip>;
+type Run = z.infer<typeof RunSchema>;
+/**
+ * One failing spec's triage: the AI's prediction (read-only, sourced from
+ * the run's report) paired with the human-recorded actual cause (write-only
+ * from the client's perspective — the API is how it gets in).
+ */
+declare const TriageCaseSchema: z.ZodObject<{
+  feature: z.ZodString;
+  spec: z.ZodString;
+  predicted: z.ZodObject<{
+    label: z.ZodEnum<{
+      TEST_DRIFT: "TEST_DRIFT";
+      SPEC_CHANGE: "SPEC_CHANGE";
+      PRODUCT_BUG: "PRODUCT_BUG";
+      UNKNOWN: "UNKNOWN";
+    }>;
+    confidence: z.ZodNumber;
+    subDiagnosis: z.ZodOptional<z.ZodString>;
+    headline: z.ZodString;
+  }, z.core.$strip>;
+  actual: z.ZodNullable<z.ZodObject<{
+    cause: z.ZodEnum<{
+      TEST_DRIFT: "TEST_DRIFT";
+      SPEC_CHANGE: "SPEC_CHANGE";
+      PRODUCT_BUG: "PRODUCT_BUG";
+    }>;
+    note: z.ZodOptional<z.ZodString>;
+    recordedAt: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type TriageCase = z.infer<typeof TriageCaseSchema>;
+declare const RunTriageSchema: z.ZodObject<{
+  runId: z.ZodString;
+  promptVersion: z.ZodString;
+  cases: z.ZodArray<z.ZodObject<{
+    feature: z.ZodString;
+    spec: z.ZodString;
+    predicted: z.ZodObject<{
+      label: z.ZodEnum<{
+        TEST_DRIFT: "TEST_DRIFT";
+        SPEC_CHANGE: "SPEC_CHANGE";
+        PRODUCT_BUG: "PRODUCT_BUG";
+        UNKNOWN: "UNKNOWN";
+      }>;
+      confidence: z.ZodNumber;
+      subDiagnosis: z.ZodOptional<z.ZodString>;
+      headline: z.ZodString;
+    }, z.core.$strip>;
+    actual: z.ZodNullable<z.ZodObject<{
+      cause: z.ZodEnum<{
+        TEST_DRIFT: "TEST_DRIFT";
+        SPEC_CHANGE: "SPEC_CHANGE";
+        PRODUCT_BUG: "PRODUCT_BUG";
+      }>;
+      note: z.ZodOptional<z.ZodString>;
+      recordedAt: z.ZodString;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+  recorded: z.ZodNumber;
+  total: z.ZodNumber;
+}, z.core.$strip>;
+type RunTriage = z.infer<typeof RunTriageSchema>;
+declare const PutActualCauseRequestSchema: z.ZodObject<{
+  cause: z.ZodEnum<{
+    TEST_DRIFT: "TEST_DRIFT";
+    SPEC_CHANGE: "SPEC_CHANGE";
+    PRODUCT_BUG: "PRODUCT_BUG";
+  }>;
+  note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type PutActualCauseRequest = z.infer<typeof PutActualCauseRequestSchema>;
+//#endregion
+//#region src/prompts/prompt-names.d.ts
+/**
+ * The fixed set of prompt assets the hub stores per project/profile, and which
+ * each is fetched at run time by the CLI. Kept as a tiny, dependency-free
+ * module so both the hub side (store/handlers) and the client/CLI can share
+ * the names without a circular import.
+ *
+ * Two kinds share one namespace:
+ *  - "guidance": the record/live prompt bundle — `.user.md` (human-maintained)
+ *    and `.agent.md` (auto-rewritten by `ccqa run --update-agent-prompt`).
+ *  - "custom-prompt": `analysis-custom-prompt` — Claude-written calibration guidance
+ *    learned from graded triage cases, injected into the failure-analysis
+ *    prompt at run time.
+ *
+ * Hub names are extensionless (`record.agent`), local files keep their real
+ * extensions; `PROMPT_LOCAL_PATHS` is the single mapping every caller (push,
+ * pull, learn, UI) goes through so the two never drift.
+ */
+declare const PROMPT_NAMES: readonly ["record.user", "record.agent", "live.user", "live.agent", "analysis-custom-prompt"];
+type PromptName = (typeof PROMPT_NAMES)[number];
+//#endregion
+//#region src/report/schema.d.ts
+declare const LabelsExportSchema: z.ZodObject<{
+  schemaVersion: z.ZodLiteral<1>;
+  runId: z.ZodNullable<z.ZodString>;
+  promptVersion: z.ZodString;
+  exportedAt: z.ZodString;
+  labels: z.ZodArray<z.ZodObject<{
+    feature: z.ZodString;
+    spec: z.ZodString;
+    predicted: z.ZodEnum<{
+      TEST_DRIFT: "TEST_DRIFT";
+      SPEC_CHANGE: "SPEC_CHANGE";
+      PRODUCT_BUG: "PRODUCT_BUG";
+      UNKNOWN: "UNKNOWN";
+    }>;
+    label: z.ZodEnum<{
+      TEST_DRIFT: "TEST_DRIFT";
+      SPEC_CHANGE: "SPEC_CHANGE";
+      PRODUCT_BUG: "PRODUCT_BUG";
+    }>;
+    note: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type LabelsExport = z.infer<typeof LabelsExportSchema>;
+//#endregion
+//#region src/hub-client/index.d.ts
+/**
+ * TypeScript client for the ccqa hub's public REST API (docs/hub-api.md).
+ * Uses the global `fetch` only — no `node:*` imports — so this same module
+ * works unmodified as a browser bundle (an intranet dashboard) or in a
+ * Node script (the `ccqa hub push/pull` CLI, which is itself just one more
+ * consumer of this client).
+ */
+interface HubClientOptions {
+  baseUrl: string;
+  token: string;
+  /** Override for testing; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+declare class HubApiError extends Error {
+  readonly status: number;
+  readonly code: string;
+  constructor(status: number, code: string, message: string);
+}
+interface HubVariable {
+  name: string;
+  sensitive: boolean;
+  updatedAt: string;
+  value?: string;
+}
+interface HubPromptMeta {
+  name: string;
+  kind: "guidance" | "custom-prompt";
+  updatedAt: string;
+  meta: Record<string, unknown>;
+}
+interface HubClient {
+  /** Push a report directory (as a tar.gz) for an already-finished `ccqa run`. */
+  pushRun(archive: Uint8Array, meta: {
+    project: string;
+    branch?: string;
+    profile?: string;
+  }): Promise<Run>;
+  listRuns(q?: {
+    project?: string;
+    branch?: string;
+    status?: RunStatus;
+    limit?: number;
+  }): Promise<Run[]>;
+  getRun(id: string): Promise<Run>;
+  getReport(id: string): Promise<unknown>;
+  downloadArtifacts(id: string): Promise<Uint8Array>;
+  getTriage(id: string): Promise<RunTriage>;
+  putActualCause(id: string, c: {
+    feature: string;
+    spec: string;
+  }, v: PutActualCauseRequest): Promise<TriageCase>;
+  deleteActualCause(id: string, c: {
+    feature: string;
+    spec: string;
+  }): Promise<void>;
+  importActualCauses(id: string, labels: LabelsExport): Promise<{
+    imported: number;
+  }>;
+  /** Every project the hub knows (from runs and stored secrets). */
+  listProjects(): Promise<string[]>;
+  putSession(project: string, profile: string, name: string, storageState: unknown): Promise<void>;
+  getSession(project: string, profile: string, name: string): Promise<unknown>;
+  listSessions(project: string, profile: string): Promise<{
+    name: string;
+    updatedAt: string;
+  }[]>;
+  deleteSession(project: string, profile: string, name: string): Promise<void>;
+  putVariable(project: string, profile: string, name: string, v: {
+    value: string;
+    sensitive: boolean;
+  }): Promise<void>;
+  listVariables(project: string, profile: string, opts?: {
+    includeValues?: boolean;
+  }): Promise<HubVariable[]>;
+  deleteVariable(project: string, profile: string, name: string): Promise<void>;
+  putPrompt(project: string, name: PromptName, body: string): Promise<void>;
+  getPrompt(project: string, name: PromptName): Promise<string | null>;
+  listPrompts(project: string): Promise<HubPromptMeta[]>;
+  deletePrompt(project: string, name: PromptName): Promise<void>;
+}
+declare function createHubClient(opts: HubClientOptions): HubClient;
+//#endregion
+export { HubApiError, HubClient, HubClientOptions, HubPromptMeta, HubVariable, createHubClient };

package/dist/hub-client/index.mjs

@@ -0,0 +1,212 @@
+//#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));
+}
+function createHubClient(opts) {
+	const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+	const doFetch = opts.fetchImpl ?? fetch;
+	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);
+	}
+	async function request(path, init = {}) {
+		const method = (init.method ?? "GET").toUpperCase();
+		const maxAttempts = 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: {
+						...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");
+	}
+	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);
+			return json(`/api/v1/runs?${params}`, {
+				method: "POST",
+				headers: { "Content-Type": "application/gzip" },
+				body: toBodyInit(archive)
+			});
+		},
+		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`);
+		},
+		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 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");
+		}
+	};
+}
+/** `/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`;
+}
+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
+export { HubApiError, createHubClient };

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {
@@ -18,6 +18,10 @@
     "./test-helpers": {
       "types": "./dist/runtime/test-helpers.d.mts",
       "import": "./dist/runtime/test-helpers.mjs"
+    },
+    "./hub-client": {
+      "types": "./dist/hub-client/index.d.mts",
+      "import": "./dist/hub-client/index.mjs"
     }
   },
   "files": [

package/dist/runtime/vitest.config.d.mts

@@ -1,6 +1,7 @@
 /// <reference types="node" />
 import * as fs from "node:fs";
 import { URL as URL$1 } from "node:url";
+import { ZlibOptions } from "node:zlib";
 import * as http from "node:http";
 import { Agent, ClientRequest, ClientRequestArgs, OutgoingHttpHeaders } from "node:http";
 import { Http2SecureServer } from "node:http2";
@@ -10,7 +11,6 @@ import * as net from "node:net";
 import { Duplex, DuplexOptions, Stream } from "node:stream";
 import esbuild from "esbuild";
 import { SecureContextOptions } from "node:tls";
-import { ZlibOptions } from "node:zlib";
 import * as Terser from "terser";
 import DartSass from "sass";
 import SassEmbedded from "sass-embedded";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {
@@ -18,6 +18,10 @@
     "./test-helpers": {
       "types": "./dist/runtime/test-helpers.d.mts",
       "import": "./dist/runtime/test-helpers.mjs"
+    },
+    "./hub-client": {
+      "types": "./dist/hub-client/index.d.mts",
+      "import": "./dist/hub-client/index.mjs"
     }
   },
   "files": [