ccqa 0.13.1 → 1.1.0

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

@@ -9,13 +9,15 @@ import { z } from "zod";
  * 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".
+ * A run's outcome. "running" is non-terminal/mutable — an opened run
+ * (`POST /runs/open`) sits in this state while it's patched incrementally.
+ * "passed"/"failed" are terminal/immutable: a pushed run (`POST /runs`)
+ * starts there directly, and an opened run ends there once done.
  */
 declare const RunStatusSchema: z.ZodEnum<{
   passed: "passed";
   failed: "failed";
+  running: "running";
 }>;
 type RunStatus = z.infer<typeof RunStatusSchema>;
 /**
@@ -30,6 +32,7 @@ declare const RunSchema: z.ZodObject<{
   status: z.ZodEnum<{
     passed: "passed";
     failed: "failed";
+    running: "running";
   }>;
   kind: z.ZodDefault<z.ZodEnum<{
     run: "run";
@@ -133,7 +136,9 @@ type PutActualCauseRequest = z.infer<typeof PutActualCauseRequestSchema>;
  *
  * 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`).
+ *    and `.agent.md` (auto-rewritten by `ccqa run --update-agent-prompt`) —
+ *    plus `triage.user`, the human-maintained guidance injected into the
+ *    failure-analysis (triage) prompt.
  *  - "custom-prompt": `analysis-custom-prompt` — Claude-written calibration guidance
  *    learned from graded triage cases, injected into the failure-analysis
  *    prompt at run time.
@@ -142,10 +147,304 @@ type PutActualCauseRequest = z.infer<typeof PutActualCauseRequestSchema>;
  * 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"];
+declare const PROMPT_NAMES: readonly ["record.user", "record.agent", "live.user", "live.agent", "playwright.user", "playwright.agent", "runn.user", "runn.agent", "triage.user", "analysis-custom-prompt"];
 type PromptName = (typeof PROMPT_NAMES)[number];
 //#endregion
 //#region src/report/schema.d.ts
+declare const ReportSpecResultSchema: z.ZodObject<{
+  feature: z.ZodString;
+  spec: z.ZodString;
+  title: z.ZodNullable<z.ZodString>;
+  target: z.ZodOptional<z.ZodString>;
+  status: z.ZodEnum<{
+    passed: "passed";
+    failed: "failed";
+    skipped: "skipped";
+  }>;
+  skipReason: z.ZodOptional<z.ZodString>;
+  testCounts: z.ZodNullable<z.ZodObject<{
+    total: z.ZodNumber;
+    passed: z.ZodNumber;
+    failed: z.ZodNumber;
+  }, z.core.$strip>>;
+  durationMs: z.ZodNullable<z.ZodNumber>;
+  assertions: z.ZodNullable<z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    status: z.ZodEnum<{
+      passed: "passed";
+      failed: "failed";
+      skipped: "skipped";
+    }>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>>;
+  analysis: z.ZodNullable<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.ZodEnum<{
+      TIMING_ISSUE: "TIMING_ISSUE";
+      OVER_ASSERTION: "OVER_ASSERTION";
+      SELECTOR_DRIFT: "SELECTOR_DRIFT";
+      DATA_MISSING: "DATA_MISSING";
+      NONE: "NONE";
+    }>>;
+    headline: z.ZodDefault<z.ZodString>;
+    recommendation: z.ZodDefault<z.ZodString>;
+    evidence: z.ZodArray<z.ZodObject<{
+      file: z.ZodOptional<z.ZodString>;
+      detail: z.ZodString;
+    }, z.core.$strip>>;
+    reasoning: z.ZodString;
+  }, z.core.$strip>>;
+  analysisSkipped: z.ZodNullable<z.ZodString>;
+  driftIssues: z.ZodNullable<z.ZodArray<z.ZodObject<{
+    severity: z.ZodEnum<{
+      OK: "OK";
+      WARN: "WARN";
+      ERROR: "ERROR";
+    }>;
+    category: z.ZodEnum<{
+      assertable: "assertable";
+      blocks: "blocks";
+      granularity: "granularity";
+      unimplemented: "unimplemented";
+    }>;
+    stepId: z.ZodNullable<z.ZodString>;
+    message: z.ZodString;
+    detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  }, z.core.$strip>>>;
+  failureLogExcerpt: z.ZodNullable<z.ZodString>;
+  diffExcerpt: z.ZodNullable<z.ZodString>;
+  specYaml: z.ZodNullable<z.ZodString>;
+  evidence: z.ZodNullable<z.ZodArray<z.ZodObject<{
+    stepId: z.ZodString;
+    source: z.ZodString;
+    pngPath: z.ZodString;
+    url: z.ZodNullable<z.ZodString>;
+    title: z.ZodNullable<z.ZodString>;
+    capturedAt: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    status: z.ZodDefault<z.ZodEnum<{
+      passed: "passed";
+      failed: "failed";
+    }>>;
+    failureSummary: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+  }, z.core.$strip>>>;
+  artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    kind: z.ZodEnum<{
+      image: "image";
+      text: "text";
+      json: "json";
+      binary: "binary";
+    }>;
+    sizeBytes: z.ZodNumber;
+  }, z.core.$strip>>>;
+  liveRun: z.ZodNullable<z.ZodObject<{
+    runId: z.ZodString;
+    sessionName: z.ZodString;
+    startedAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    steps: z.ZodArray<z.ZodObject<{
+      stepId: z.ZodString;
+      source: z.ZodString;
+      instruction: z.ZodString;
+      expected: z.ZodString;
+      status: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        skipped: "skipped";
+      }>;
+      reasoning: z.ZodString;
+      beforePng: z.ZodNullable<z.ZodString>;
+      afterPng: z.ZodNullable<z.ZodString>;
+      durationMs: z.ZodNumber;
+      cost: z.ZodObject<{
+        totalCostUsd: z.ZodNullable<z.ZodNumber>;
+        durationApiMs: z.ZodNullable<z.ZodNumber>;
+        numTurns: z.ZodNullable<z.ZodNumber>;
+        inputTokens: z.ZodNullable<z.ZodNumber>;
+        cacheCreationInputTokens: z.ZodNullable<z.ZodNumber>;
+        cacheReadInputTokens: z.ZodNullable<z.ZodNumber>;
+        outputTokens: z.ZodNullable<z.ZodNumber>;
+        models: z.ZodArray<z.ZodString>;
+      }, z.core.$strip>;
+      commands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    cost: z.ZodObject<{
+      totalCostUsd: z.ZodNullable<z.ZodNumber>;
+      durationApiMs: z.ZodNullable<z.ZodNumber>;
+      numTurns: z.ZodNullable<z.ZodNumber>;
+      inputTokens: z.ZodNullable<z.ZodNumber>;
+      cacheCreationInputTokens: z.ZodNullable<z.ZodNumber>;
+      cacheReadInputTokens: z.ZodNullable<z.ZodNumber>;
+      outputTokens: z.ZodNullable<z.ZodNumber>;
+      models: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type ReportSpecResult = z.infer<typeof ReportSpecResultSchema>;
+declare const RunReportDataSchema: z.ZodObject<{
+  schemaVersion: z.ZodLiteral<1>;
+  kind: z.ZodDefault<z.ZodEnum<{
+    run: "run";
+    drift: "drift";
+  }>>;
+  createdAt: z.ZodString;
+  runId: z.ZodNullable<z.ZodString>;
+  git: z.ZodObject<{
+    head: z.ZodNullable<z.ZodString>;
+    base: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>;
+  model: z.ZodNullable<z.ZodString>;
+  language: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+  promptVersion: z.ZodString;
+  customPromptVersion: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+  triageUserPromptHash: z.ZodOptional<z.ZodString>;
+  results: z.ZodArray<z.ZodObject<{
+    feature: z.ZodString;
+    spec: z.ZodString;
+    title: z.ZodNullable<z.ZodString>;
+    target: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+      passed: "passed";
+      failed: "failed";
+      skipped: "skipped";
+    }>;
+    skipReason: z.ZodOptional<z.ZodString>;
+    testCounts: z.ZodNullable<z.ZodObject<{
+      total: z.ZodNumber;
+      passed: z.ZodNumber;
+      failed: z.ZodNumber;
+    }, z.core.$strip>>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+    assertions: z.ZodNullable<z.ZodArray<z.ZodObject<{
+      name: z.ZodString;
+      status: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        skipped: "skipped";
+      }>;
+      durationMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    analysis: z.ZodNullable<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.ZodEnum<{
+        TIMING_ISSUE: "TIMING_ISSUE";
+        OVER_ASSERTION: "OVER_ASSERTION";
+        SELECTOR_DRIFT: "SELECTOR_DRIFT";
+        DATA_MISSING: "DATA_MISSING";
+        NONE: "NONE";
+      }>>;
+      headline: z.ZodDefault<z.ZodString>;
+      recommendation: z.ZodDefault<z.ZodString>;
+      evidence: z.ZodArray<z.ZodObject<{
+        file: z.ZodOptional<z.ZodString>;
+        detail: z.ZodString;
+      }, z.core.$strip>>;
+      reasoning: z.ZodString;
+    }, z.core.$strip>>;
+    analysisSkipped: z.ZodNullable<z.ZodString>;
+    driftIssues: z.ZodNullable<z.ZodArray<z.ZodObject<{
+      severity: z.ZodEnum<{
+        OK: "OK";
+        WARN: "WARN";
+        ERROR: "ERROR";
+      }>;
+      category: z.ZodEnum<{
+        assertable: "assertable";
+        blocks: "blocks";
+        granularity: "granularity";
+        unimplemented: "unimplemented";
+      }>;
+      stepId: z.ZodNullable<z.ZodString>;
+      message: z.ZodString;
+      detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    failureLogExcerpt: z.ZodNullable<z.ZodString>;
+    diffExcerpt: z.ZodNullable<z.ZodString>;
+    specYaml: z.ZodNullable<z.ZodString>;
+    evidence: z.ZodNullable<z.ZodArray<z.ZodObject<{
+      stepId: z.ZodString;
+      source: z.ZodString;
+      pngPath: z.ZodString;
+      url: z.ZodNullable<z.ZodString>;
+      title: z.ZodNullable<z.ZodString>;
+      capturedAt: z.ZodNullable<z.ZodString>;
+      description: z.ZodNullable<z.ZodString>;
+      status: z.ZodDefault<z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+      }>>;
+      failureSummary: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      name: z.ZodString;
+      path: z.ZodString;
+      kind: z.ZodEnum<{
+        image: "image";
+        text: "text";
+        json: "json";
+        binary: "binary";
+      }>;
+      sizeBytes: z.ZodNumber;
+    }, z.core.$strip>>>;
+    liveRun: z.ZodNullable<z.ZodObject<{
+      runId: z.ZodString;
+      sessionName: z.ZodString;
+      startedAt: z.ZodString;
+      durationMs: z.ZodNumber;
+      steps: z.ZodArray<z.ZodObject<{
+        stepId: z.ZodString;
+        source: z.ZodString;
+        instruction: z.ZodString;
+        expected: z.ZodString;
+        status: z.ZodEnum<{
+          passed: "passed";
+          failed: "failed";
+          skipped: "skipped";
+        }>;
+        reasoning: z.ZodString;
+        beforePng: z.ZodNullable<z.ZodString>;
+        afterPng: z.ZodNullable<z.ZodString>;
+        durationMs: z.ZodNumber;
+        cost: z.ZodObject<{
+          totalCostUsd: z.ZodNullable<z.ZodNumber>;
+          durationApiMs: z.ZodNullable<z.ZodNumber>;
+          numTurns: z.ZodNullable<z.ZodNumber>;
+          inputTokens: z.ZodNullable<z.ZodNumber>;
+          cacheCreationInputTokens: z.ZodNullable<z.ZodNumber>;
+          cacheReadInputTokens: z.ZodNullable<z.ZodNumber>;
+          outputTokens: z.ZodNullable<z.ZodNumber>;
+          models: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        commands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      }, z.core.$strip>>;
+      cost: z.ZodObject<{
+        totalCostUsd: z.ZodNullable<z.ZodNumber>;
+        durationApiMs: z.ZodNullable<z.ZodNumber>;
+        numTurns: z.ZodNullable<z.ZodNumber>;
+        inputTokens: z.ZodNullable<z.ZodNumber>;
+        cacheCreationInputTokens: z.ZodNullable<z.ZodNumber>;
+        cacheReadInputTokens: z.ZodNullable<z.ZodNumber>;
+        outputTokens: z.ZodNullable<z.ZodNumber>;
+        models: z.ZodArray<z.ZodString>;
+      }, z.core.$strip>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type RunReportData = z.infer<typeof RunReportDataSchema>;
 declare const LabelsExportSchema: z.ZodObject<{
   schemaVersion: z.ZodLiteral<1>;
   runId: z.ZodNullable<z.ZodString>;
@@ -170,7 +469,30 @@ declare const LabelsExportSchema: z.ZodObject<{
 }, z.core.$strip>;
 type LabelsExport = z.infer<typeof LabelsExportSchema>;
 //#endregion
+//#region src/run/incremental-report.d.ts
+/**
+ * The report envelope fields that don't change spec-to-spec — everything in
+ * `RunReportData` except `results`. Captured once when the writer is created
+ * so each incremental flush produces the same envelope the final batch write
+ * used to.
+ */
+type ReportEnvelope = Omit<RunReportData, "results">;
+//#endregion
 //#region src/hub-client/index.d.ts
+/**
+ * Body of a `PATCH /runs/:id` incremental push: the newly-finished spec rows,
+ * their evidence PNGs (posix relPath → base64), the report envelope metadata
+ * (filled once the real git diff is known), and — on the last patch — `done`
+ * with the terminal status.
+ */
+interface PatchRunRequest {
+  rows: ReportSpecResult[];
+  /** reportDir-relative posix path → base64 PNG bytes. */
+  evidence?: Record<string, string>;
+  done?: boolean;
+  finalStatus?: "passed" | "failed";
+  reportMeta?: Partial<ReportEnvelope>;
+}
 /**
  * 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
@@ -215,6 +537,19 @@ interface HubClient {
     profile?: string;
     kind?: "run" | "drift";
   }): Promise<Run>;
+  /**
+   * Open a `running` run to push results into incrementally. Returns the new
+   * run's id. Non-retryable (a dropped response after the server committed
+   * would leave a second open run); callers degrade to local-only on failure.
+   */
+  openRun(meta: {
+    project: string;
+    branch?: string;
+    profile?: string;
+    kind?: "run" | "drift";
+  }): Promise<Run>;
+  /** Add finished spec rows (+ evidence) to a running run; `done` closes it. */
+  patchRun(id: string, body: PatchRunRequest): Promise<Run>;
   listRuns(q?: {
     project?: string;
     branch?: string;
@@ -257,7 +592,17 @@ interface HubClient {
   getPrompt(project: string, name: PromptName): Promise<string | null>;
   listPrompts(project: string): Promise<HubPromptMeta[]>;
   deletePrompt(project: string, name: PromptName): Promise<void>;
+  /** The project's perspectives document (coverage inventory), stored hub-only. */
+  putPerspectives(project: string, doc: unknown): Promise<void>;
+  getPerspectives(project: string): Promise<unknown | null>;
+  /** Set (or clear, with an empty string) the human note on one spec's entry. */
+  patchPerspectivesNote(project: string, c: {
+    feature: string;
+    spec: string;
+    note: string;
+  }): Promise<void>;
+  deletePerspectives(project: string): Promise<void>;
 }
 declare function createHubClient(opts: HubClientOptions): HubClient;
 //#endregion
-export { HubApiError, HubClient, HubClientOptions, HubPromptMeta, HubVariable, createHubClient };
+export { HubApiError, HubClient, HubClientOptions, HubPromptMeta, HubVariable, PatchRunRequest, createHubClient };

package/dist/hub-client/index.mjs

@@ -104,6 +104,20 @@ function createHubClient(opts) {
 				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);
+			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;
@@ -186,6 +200,27 @@ function createHubClient(opts) {
 		},
 		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");
 		}
 	};
 }
@@ -197,6 +232,10 @@ function scopePath(project, kind, profile) {
 function promptsPath(project) {
 	return `/api/v1/projects/${encodeURIComponent(project)}/prompts`;
 }
+/** Perspectives are one document per project: `/api/v1/projects/<project>/perspectives`. */
+function perspectivesPath(project) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/perspectives`;
+}
 function queryString(params) {
 	const out = new URLSearchParams();
 	for (const [key, value] of Object.entries(params)) if (value !== void 0) out.set(key, String(value));

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "0.13.1",
+  "version": "1.1.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {

package/dist/runtime/test-helpers.mjs

@@ -1,4 +1,4 @@
-import { i as FAILURE_STEP_ID, n as spawnAB, r as FAILURE_SOURCE, t as sleepSync } from "../spawn-ab-Ja8NRRab.mjs";
+import { i as FAILURE_STEP_ID, n as spawnAB, r as FAILURE_SOURCE, t as sleepSync } from "../spawn-ab-Cr967J2N.mjs";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 //#region src/runtime/test-helpers.ts

package/dist/{spawn-ab-Ja8NRRab.mjs → spawn-ab-Cr967J2N.mjs}

@@ -14,7 +14,8 @@ const FAILURE_STEP_ID = "failure";
 const FAILURE_SOURCE = "failed";
 //#endregion
 //#region src/runtime/spawn-ab.ts
-const AB = createRequire(import.meta.url).resolve("agent-browser/bin/agent-browser.js");
+const require = createRequire(import.meta.url);
+const AB = process.env["CCQA_AB_BIN"] ?? require.resolve("agent-browser/bin/agent-browser.js");
 const EAGAIN_PATTERN = /Resource temporarily unavailable|os error 35/i;
 const EAGAIN_TOTAL_BUDGET_MS = 3e4;
 const EAGAIN_BACKOFF_MS = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "0.13.1",
+  "version": "1.1.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {