ccqa 1.5.0 → 1.7.0

package/dist/evidence-constants-C425F7ZG.mjs

@@ -0,0 +1,36 @@
+//#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
+export { sanitizeStepId as i, FAILURE_SOURCE as n, FAILURE_STEP_ID as r, EVIDENCE_DIR_ENV as t };

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

@@ -64,6 +64,7 @@ type Run = z.infer<typeof RunSchema>;
 declare const TriageCaseSchema: z.ZodObject<{
   feature: z.ZodString;
   spec: z.ZodString;
+  target: z.ZodOptional<z.ZodString>;
   predicted: z.ZodObject<{
     label: z.ZodEnum<{
       TEST_DRIFT: "TEST_DRIFT";
@@ -92,6 +93,7 @@ declare const RunTriageSchema: z.ZodObject<{
   cases: z.ZodArray<z.ZodObject<{
     feature: z.ZodString;
     spec: z.ZodString;
+    target: z.ZodOptional<z.ZodString>;
     predicted: z.ZodObject<{
       label: z.ZodEnum<{
         TEST_DRIFT: "TEST_DRIFT";
@@ -242,6 +244,7 @@ declare const ReportSpecResultSchema: z.ZodObject<{
     stepId: z.ZodString;
     source: z.ZodString;
     pngPath: z.ZodString;
+    beforePngPath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     url: z.ZodNullable<z.ZodString>;
     title: z.ZodNullable<z.ZodString>;
     capturedAt: z.ZodNullable<z.ZodString>;
@@ -252,6 +255,7 @@ declare const ReportSpecResultSchema: z.ZodObject<{
     }>>;
     failureSummary: z.ZodDefault<z.ZodNullable<z.ZodString>>;
   }, z.core.$strip>>>;
+  evidenceUnavailable: z.ZodOptional<z.ZodString>;
   artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
     name: z.ZodString;
     path: z.ZodString;
@@ -407,6 +411,7 @@ declare const RunReportDataSchema: z.ZodObject<{
       stepId: z.ZodString;
       source: z.ZodString;
       pngPath: z.ZodString;
+      beforePngPath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
       url: z.ZodNullable<z.ZodString>;
       title: z.ZodNullable<z.ZodString>;
       capturedAt: z.ZodNullable<z.ZodString>;
@@ -417,6 +422,7 @@ declare const RunReportDataSchema: z.ZodObject<{
       }>>;
       failureSummary: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>>;
+    evidenceUnavailable: z.ZodOptional<z.ZodString>;
     artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
       name: z.ZodString;
       path: z.ZodString;

package/dist/package.json

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

package/dist/runtime/step-evidence.d.mts

@@ -0,0 +1,53 @@
+//#region src/runtime/step-evidence.d.ts
+/**
+ * Step-boundary screenshot capture for tests ccqa generates for external
+ * targets (Playwright today). Generated tests import this through the
+ * `ccqa/step-evidence` subpath and call it at each spec-step boundary; the
+ * `<id>.png` + `<id>.json` pairs it writes are exactly what `ccqa run`'s
+ * report loader consumes, so an external target's rows carry the same
+ * per-step evidence the built-in agent-browser path produces.
+ *
+ * Two constraints shape the whole module:
+ *
+ *   - **No test-framework dependency.** The page handle is typed
+ *     structurally, so ccqa never imports `@playwright/test` and a consumer
+ *     installs nothing beyond ccqa itself. Any object exposing these three
+ *     members works — including a Playwright `Page`.
+ *   - **Never fail the user's test.** Capture is best-effort: every error is
+ *     swallowed with a stderr note. A missing screenshot costs a frame in the
+ *     report; it must never flip a passing spec to red.
+ *
+ * Capture is opt-in at runtime via `CCQA_EVIDENCE_DIR`, which only `ccqa run`
+ * sets. Running the generated test directly (or through the generation-time
+ * verify/fix loop) writes nothing.
+ */
+/**
+ * The subset of a browser page this module needs. Structural by design — see
+ * the module comment.
+ */
+interface CcqaEvidencePage {
+  screenshot(options: {
+    path: string;
+  }): Promise<unknown>;
+  url(): string;
+  title(): Promise<string>;
+}
+/**
+ * Capture the screen as the step is entered. Pair with `ccqaStepAfter` at the
+ * end of the same step.
+ */
+declare function ccqaStepBefore(page: CcqaEvidencePage, stepId: string, source: string): Promise<void>;
+/**
+ * Capture the screen as the step closes and finalise the step's metadata:
+ * the closing shot becomes the step's primary screenshot, the entry shot (if
+ * one was taken) rides along as `beforePngFile`, and the "did not complete"
+ * caption written by `ccqaStepBefore` is cleared.
+ *
+ * If the closing shot itself fails, the step still COMPLETED — it just lost its
+ * final frame. Rewrite the meta without the failure caption (keeping the entry
+ * shot as the frame) so a passing step doesn't render red; the capture failure
+ * is surfaced via the stderr warn in `capture()`.
+ */
+declare function ccqaStepAfter(page: CcqaEvidencePage, stepId: string, source: string): Promise<void>;
+//#endregion
+export { CcqaEvidencePage, ccqaStepAfter, ccqaStepBefore };

package/dist/runtime/step-evidence.mjs

@@ -0,0 +1,104 @@
+import { i as sanitizeStepId, t as EVIDENCE_DIR_ENV } from "../evidence-constants-C425F7ZG.mjs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/runtime/step-evidence.ts
+/**
+* Caption recorded on the entry shot's metadata and cleared by
+* `ccqaStepAfter`. If the test dies inside the step, this is what survives —
+* so the report shows the failing step with the screen it started from,
+* marked failed, instead of dropping the step entirely.
+*/
+const INCOMPLETE_STEP_SUMMARY = "the test stopped inside this step (no closing screenshot)";
+/**
+* Capture the screen as the step is entered. Pair with `ccqaStepAfter` at the
+* end of the same step.
+*/
+async function ccqaStepBefore(page, stepId, source) {
+	const dir = process.env[EVIDENCE_DIR_ENV];
+	if (!dir) return;
+	const id = sanitizeStepId(stepId);
+	const beforeFile = `${id}.before.png`;
+	if (!await capture(page, dir, beforeFile)) return;
+	await writeMeta(page, dir, id, {
+		stepId,
+		source,
+		pngFile: beforeFile,
+		failureSummary: INCOMPLETE_STEP_SUMMARY
+	});
+}
+/**
+* Capture the screen as the step closes and finalise the step's metadata:
+* the closing shot becomes the step's primary screenshot, the entry shot (if
+* one was taken) rides along as `beforePngFile`, and the "did not complete"
+* caption written by `ccqaStepBefore` is cleared.
+*
+* If the closing shot itself fails, the step still COMPLETED — it just lost its
+* final frame. Rewrite the meta without the failure caption (keeping the entry
+* shot as the frame) so a passing step doesn't render red; the capture failure
+* is surfaced via the stderr warn in `capture()`.
+*/
+async function ccqaStepAfter(page, stepId, source) {
+	const dir = process.env[EVIDENCE_DIR_ENV];
+	if (!dir) return;
+	const id = sanitizeStepId(stepId);
+	const afterFile = `${id}.png`;
+	const beforeFile = `${id}.before.png`;
+	const hasBefore = existsSync(join(dir, beforeFile));
+	if (!await capture(page, dir, afterFile)) {
+		if (hasBefore) await writeMeta(page, dir, id, {
+			stepId,
+			source,
+			pngFile: beforeFile
+		});
+		return;
+	}
+	await writeMeta(page, dir, id, {
+		stepId,
+		source,
+		pngFile: afterFile,
+		...hasBefore ? { beforePngFile: beforeFile } : {}
+	});
+}
+/** Screenshot into `<dir>/<file>`; false when the shot could not be taken. */
+async function capture(page, dir, file) {
+	try {
+		mkdirSync(dir, { recursive: true });
+		await page.screenshot({ path: join(dir, file) });
+		return true;
+	} catch (e) {
+		warn(`screenshot failed for ${file} (${message(e)})`);
+		return false;
+	}
+}
+/**
+* Write the step's meta sidecar. `url`/`title` are read here rather than by
+* the caller so a page that cannot answer them still yields a usable record
+* (the screenshot alone is worth keeping).
+*/
+async function writeMeta(page, dir, id, fields) {
+	let url = null;
+	let title = null;
+	try {
+		url = page.url();
+		title = await page.title();
+	} catch {}
+	const meta = {
+		...fields,
+		url,
+		title,
+		capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	try {
+		writeFileSync(join(dir, `${id}.json`), `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+	} catch (e) {
+		warn(`meta write failed for ${id} (${message(e)})`);
+	}
+}
+function message(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+function warn(text) {
+	process.stderr.write(`[ccqa] step-evidence: ${text}\n`);
+}
+//#endregion
+export { ccqaStepAfter, ccqaStepBefore };

package/dist/runtime/test-helpers.mjs

@@ -1,4 +1,5 @@
-import { c as FAILURE_SOURCE, l as FAILURE_STEP_ID, n as spawnAB, t as sleepSync } from "../spawn-ab-B9Il2TMd.mjs";
+import { i as sanitizeStepId, n as FAILURE_SOURCE, r as FAILURE_STEP_ID, t as EVIDENCE_DIR_ENV } from "../evidence-constants-C425F7ZG.mjs";
+import { n as spawnAB, t as sleepSync } from "../spawn-ab-CRIVfWpw.mjs";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 //#region src/runtime/test-helpers.ts
@@ -30,7 +31,7 @@ function __setCurrentStep(stepId, source) {
 }
 function captureFailureEvidence(summary) {
 	if (currentStep) {
-		const safe = currentStep.stepId.replace(/[^A-Za-z0-9_.-]/g, "_");
+		const safe = sanitizeStepId(currentStep.stepId);
 		captureEvidence({
 			stepId: currentStep.stepId,
 			source: currentStep.source,
@@ -244,7 +245,7 @@ function abStepEvidence(stepId, source) {
 	captureEvidence({
 		stepId,
 		source,
-		pngFile: `${stepId.replace(/[^A-Za-z0-9_.-]/g, "_")}.png`
+		pngFile: `${sanitizeStepId(stepId)}.png`
 	});
 	if (currentStep && currentStep.stepId === stepId) currentStep = null;
 }
@@ -255,7 +256,7 @@ function abStepEvidence(stepId, source) {
 * expression must itself stringify the payload — hence the double JSON.parse.
 */
 function captureEvidence(opts) {
-	const dir = process.env["CCQA_EVIDENCE_DIR"];
+	const dir = process.env[EVIDENCE_DIR_ENV];
 	if (!dir) return;
 	const { stepId, source, pngFile, failureSummary, silent } = opts;
 	const pngPath = join(dir, pngFile);

package/dist/{spawn-ab-B9Il2TMd.mjs → spawn-ab-CRIVfWpw.mjs}

@@ -2,19 +2,6 @@ import { createRequire } from "node:module";
 import { statSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
 import { spawnSync } from "node:child_process";
-//#region src/runtime/evidence-constants.ts
-/**
-* Shared constants for step-boundary evidence captured by abStepEvidence() /
-* captureFailureEvidence() and consumed by the run report. Kept under
-* `runtime/` so the test-helpers module — which generated test scripts import
-* via `ccqa/test-helpers` — can stay free of CLI-side imports while still
-* sharing the literal with run.ts.
-*/
-/** 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
 //#region src/runtime/agent-browser-bin.ts
 const require = createRequire(import.meta.url);
 function hasAgentBrowserShim(dir) {
@@ -207,4 +194,4 @@ function spawnAB(args) {
 	return result;
 }
 //#endregion
-export { formatAgentBrowserUnavailableMessage as a, FAILURE_SOURCE as c, assertAgentBrowserAvailable as i, FAILURE_STEP_ID as l, spawnAB as n, pathWithAgentBrowserShim as o, AgentBrowserUnavailableError as r, resolveAgentBrowserBin as s, sleepSync as t };
+export { formatAgentBrowserUnavailableMessage as a, assertAgentBrowserAvailable as i, spawnAB as n, pathWithAgentBrowserShim as o, AgentBrowserUnavailableError as r, resolveAgentBrowserBin as s, sleepSync as t };

package/package.json

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