ccqa 1.51.1 → 1.53.0

package/dist/runtime/test-helpers.d.cts

@@ -0,0 +1,39 @@
+//#region src/runtime/test-helpers.d.ts
+declare function __setCurrentStep(stepId: string, source: string): void;
+declare function ab(...args: string[]): void;
+/** Wait for element/text with an explicit timeout so long-running async ops don't hang. */
+declare function abWait(selector: string, timeoutMs?: number): void;
+/**
+ * Upload one or more files to a file input via `agent-browser upload`.
+ * Relative paths resolve against the test's cwd. We pre-check existence
+ * locally so a typo in a fixture path surfaces as a clear error before
+ * agent-browser exits with an opaque non-zero status.
+ */
+declare function abUpload(selector: string, ...files: string[]): void;
+/** Assert stable text is visible on page (via wait --text). */
+declare function abAssertTextVisible(text: string, timeoutMs?: number): void;
+/** Assert element is visible (polls `get count`; never uses the blocking `wait <selector>`). */
+declare function abAssertVisible(selector: string, timeoutMs?: number): void;
+/** Assert element is NOT visible (polls `get count` for absence; --fn for text). */
+declare function abAssertNotVisible(selector: string, timeoutMs?: number): void;
+/** Assert URL contains a pattern (via get url). */
+declare function abAssertUrl(pattern: string): void;
+/** Assert element is enabled (via is enabled). */
+declare function abAssertEnabled(selector: string): void;
+/** Assert element is disabled (via is enabled). */
+declare function abAssertDisabled(selector: string): void;
+/** Assert checkbox is checked (via is checked). */
+declare function abAssertChecked(selector: string): void;
+/** Assert checkbox is unchecked (via is checked). */
+declare function abAssertUnchecked(selector: string): void;
+/**
+ * Capture a step-boundary evidence pair (PNG + JSON metadata) so a reviewer
+ * can confirm at a glance that a passing spec actually drove the app to the
+ * state its `expected` describes. Opt-in at runtime via `CCQA_EVIDENCE_DIR` so
+ * generated scripts hand-run outside `ccqa run` don't write stray files. All
+ * errors are swallowed with a stderr warning — evidence capture must never
+ * flip a passing spec to red.
+ */
+declare function abStepEvidence(stepId: string, source: string): void;
+//#endregion
+export { __setCurrentStep, ab, abAssertChecked, abAssertDisabled, abAssertEnabled, abAssertNotVisible, abAssertTextVisible, abAssertUnchecked, abAssertUrl, abAssertVisible, abStepEvidence, abUpload, abWait };

package/dist/runtime/test-helpers.mjs

@@ -1,7 +1,138 @@
-import { i as sanitizeStepId, n as FAILURE_SOURCE, r as FAILURE_STEP_ID, t as EVIDENCE_DIR_ENV } from "../evidence-constants-Cm_S_5od.mjs";
-import { n as spawnAB, t as sleepSync } from "../spawn-ab-CR_Sr7wh.mjs";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { i as sanitizeStepId, n as FAILURE_SOURCE, r as FAILURE_STEP_ID, t as EVIDENCE_DIR_ENV } from "../evidence-constants-BLXD0LRY.mjs";
+import { createRequire } from "node:module";
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+//#region src/runtime/agent-browser-bin.ts
+const require = createRequire(import.meta.url);
+function hasAgentBrowserShim(dir) {
+	try {
+		statSync(join(dir, "agent-browser"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Walks up from `start` looking for a `node_modules/.bin/agent-browser` shim.
+* Returns the .bin directory containing the shim, or null if none is found.
+*/
+function findNodeModulesBin(start) {
+	let cur = start;
+	while (true) {
+		const candidate = join(cur, "node_modules", ".bin");
+		if (hasAgentBrowserShim(candidate)) return candidate;
+		const parent = dirname(cur);
+		if (parent === cur) return null;
+		cur = parent;
+	}
+}
+/** The shim-directory walk shared by every resolution below (no env override). */
+function resolveShimDir() {
+	const fromCwd = findNodeModulesBin(process.cwd());
+	if (fromCwd) return fromCwd;
+	const fromSelf = findNodeModulesBin(dirname(require.resolve("agent-browser/package.json")));
+	if (fromSelf) return fromSelf;
+	try {
+		const candidate = join(dirname(require.resolve("agent-browser/package.json")), "node_modules", ".bin");
+		if (hasAgentBrowserShim(candidate)) return candidate;
+	} catch {}
+	return null;
+}
+/**
+* INVARIANT: every agent-browser invocation in one ccqa process — the host
+* side (`spawnAB`: state load, replay probes, …) and the Claude subprocess
+* (via the PATH prepended by `pathWithAgentBrowserShim`) — must resolve to
+* the SAME binary. agent-browser runs one daemon per binary, and a state
+* loaded into one daemon's session is invisible to a same-named session on
+* another daemon, so a split resolution silently loses session restores.
+* Both entry points below therefore share one resolution order:
+* `CCQA_AB_BIN` (explicit override, e.g. the e2e harness or a dev build
+* driving a consumer project's agent-browser) → the peer-installed shim
+* (consumer project first, then ccqa's own tree).
+*/
+/**
+* Resolves the executable `spawnAB` should invoke. Falls back to the package
+* JS entry (resolvable whenever the peer dependency is installed) when no
+* shim directory exists; throws only if agent-browser is missing entirely.
+*/
+function resolveAgentBrowserBin() {
+	const override = process.env["CCQA_AB_BIN"];
+	if (override) return override;
+	const shimDir = resolveShimDir();
+	if (shimDir) return join(shimDir, "agent-browser");
+	return require.resolve("agent-browser/bin/agent-browser.js");
+}
+//#endregion
+//#region src/runtime/spawn-ab.ts
+const AB = resolveAgentBrowserBin();
+const EAGAIN_PATTERN = /Resource temporarily unavailable|os error 35/i;
+const EAGAIN_TOTAL_BUDGET_MS = 3e4;
+const EAGAIN_BACKOFF_MS = [
+	100,
+	200,
+	300,
+	500,
+	700,
+	1e3,
+	1500,
+	2e3,
+	2500,
+	3e3,
+	3e3,
+	3e3,
+	3e3,
+	3e3,
+	3e3
+];
+const PROCESS_HARD_TIMEOUT_MS = 35e3;
+function sleepSync(ms) {
+	const buf = new SharedArrayBuffer(4);
+	Atomics.wait(new Int32Array(buf), 0, 0, ms);
+}
+function spawnABOnce(args, timeoutMs) {
+	const result = spawnSync(AB, args, {
+		stdio: "pipe",
+		timeout: timeoutMs
+	});
+	const wedged = result.error?.code === "ETIMEDOUT";
+	return {
+		status: result.status,
+		stdout: result.stdout?.toString() ?? "",
+		stderr: (result.stderr?.toString() ?? "") + (wedged ? `\n[ccqa] agent-browser ${subcommand(args)} did not answer in ${timeoutMs}ms — killed after hard timeout` : ""),
+		wedged
+	};
+}
+/** The verb a reader recognises, past the one prefix every caller writes. */
+function subcommand(args) {
+	return (args[0] === "--session" ? args[2] : args[0]) ?? "(no command)";
+}
+/**
+* Invoke `agent-browser` once and return its exit status/stdout/stderr,
+* retrying internally up to ~30s while the daemon's state file is in the
+* "Resource temporarily unavailable" race window. Used by both the test
+* runtime (`test-helpers.ts`) and the post-trace replay validation
+* (`replay-validate.ts`). Kept out of `test-helpers.ts` because that
+* module is also the public surface for generated test scripts — exposing
+* the raw spawner there would widen the contract for end users.
+*/
+function spawnAB(args, opts) {
+	const timeoutMs = opts?.timeoutMs ?? PROCESS_HARD_TIMEOUT_MS;
+	let result = spawnABOnce(args, timeoutMs);
+	let elapsed = 0;
+	let attempt = 0;
+	while (result.status !== 0 && elapsed < EAGAIN_TOTAL_BUDGET_MS) {
+		const combined = `${result.stdout}\n${result.stderr}`;
+		if (!EAGAIN_PATTERN.test(combined)) return result;
+		const wait = EAGAIN_BACKOFF_MS[attempt] ?? 3e3;
+		sleepSync(wait);
+		elapsed += wait;
+		attempt++;
+		result = spawnABOnce(args, timeoutMs);
+	}
+	return result;
+}
+//#endregion
 //#region src/runtime/test-helpers.ts
 const POST_OPEN_SETTLE_MS = 600;
 function logStep(action, args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.51.1",
+  "version": "1.53.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {
@@ -16,20 +16,60 @@
   },
   "exports": {
     "./test-helpers": {
-      "types": "./dist/runtime/test-helpers.d.mts",
-      "import": "./dist/runtime/test-helpers.mjs"
+      "import": {
+        "types": "./dist/runtime/test-helpers.d.mts",
+        "default": "./dist/runtime/test-helpers.mjs"
+      },
+      "require": {
+        "types": "./dist/runtime/test-helpers.d.cts",
+        "default": "./dist/runtime/test-helpers.cjs"
+      }
     },
     "./step-evidence": {
-      "types": "./dist/runtime/step-evidence.d.mts",
-      "import": "./dist/runtime/step-evidence.mjs"
+      "import": {
+        "types": "./dist/runtime/step-evidence.d.mts",
+        "default": "./dist/runtime/step-evidence.mjs"
+      },
+      "require": {
+        "types": "./dist/runtime/step-evidence.d.cts",
+        "default": "./dist/runtime/step-evidence.cjs"
+      }
     },
     "./hub-client": {
-      "types": "./dist/hub-client/index.d.mts",
-      "import": "./dist/hub-client/index.mjs"
+      "import": {
+        "types": "./dist/hub-client/index.d.mts",
+        "default": "./dist/hub-client/index.mjs"
+      },
+      "require": {
+        "types": "./dist/hub-client/index.d.cts",
+        "default": "./dist/hub-client/index.cjs"
+      }
     },
     "./judge": {
-      "types": "./dist/runtime/judge.d.mts",
-      "import": "./dist/runtime/judge.mjs"
+      "import": {
+        "types": "./dist/runtime/judge.d.mts",
+        "default": "./dist/runtime/judge.mjs"
+      },
+      "require": {
+        "types": "./dist/runtime/judge.d.cts",
+        "default": "./dist/runtime/judge.cjs"
+      }
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "test-helpers": [
+        "dist/runtime/test-helpers.d.mts"
+      ],
+      "step-evidence": [
+        "dist/runtime/step-evidence.d.mts"
+      ],
+      "hub-client": [
+        "dist/hub-client/index.d.mts"
+      ],
+      "judge": [
+        "dist/runtime/judge.d.mts"
+      ]
     }
   },
   "files": [