ccqa 1.10.1 → 1.12.0

package/dist/bin/ccqa.mjs

@@ -1327,6 +1327,61 @@ function missingNativeBinaryMessage(pkg) {
 	return `${pkg} is not installed. The Claude Agent SDK needs it to start Claude on this platform, so every Claude-backed command (run in live mode, drift, diagnose) will fail. It ships as an optional dependency of the SDK, which a lockfile can drop silently: reinstall without omitting optional dependencies, or add it to your project as a direct dependency pinned to the same version as @anthropic-ai/claude-agent-sdk.`;
 }
 //#endregion
+//#region src/claude/cost-tally.ts
+/**
+* Sum every Claude invocation made inside a scope.
+*
+* A command like `record` calls Claude several times — the browser trace, the
+* codegen cleanup, one diagnosis per auto-fix retry — and the caller wants one
+* number for the whole command. Threading a cost out of each of those return
+* types would touch every layer in between, so the tally is scoped instead:
+* `invokeClaudeStreaming` adds to whichever scope is active, and nothing
+* between the two has to know.
+*
+* Scoped rather than module-global because commands run specs concurrently
+* (`drift` uses a pool). Two scopes must not fold into each other.
+*/
+const tallyStore = new AsyncLocalStorage();
+/** Record one invocation against the active scope. No-op outside one. */
+function tallyInvocation(cost) {
+	tallyStore.getStore()?.push(cost);
+}
+/** Run `fn` with a fresh tally. Read the total from inside with `readCostTally`. */
+async function withCostTally(fn) {
+	return tallyStore.run([], fn);
+}
+/**
+* The active scope's total so far, or null outside one.
+*
+* Read rather than pushed at the caller because commands end in
+* `process.exit`, which never reaches a `finally`. Each one reports the
+* total itself, at the point it knows it is done.
+*
+* Fields stay `null` when no invocation reported them, so a caller can tell
+* "nothing was billed" from "the SDK didn't say" (mock runs, SDK errors).
+*/
+function readCostTally() {
+	const collected = tallyStore.getStore();
+	return collected === void 0 ? null : sum(collected);
+}
+function sum(costs) {
+	const add = (pick) => {
+		const present = costs.map(pick).filter((v) => v !== null);
+		return present.length === 0 ? null : present.reduce((a, b) => a + b, 0);
+	};
+	return {
+		totalCostUsd: add((c) => c.totalCostUsd),
+		durationMs: add((c) => c.durationMs),
+		durationApiMs: add((c) => c.durationApiMs),
+		numTurns: add((c) => c.numTurns),
+		inputTokens: add((c) => c.inputTokens),
+		cacheCreationInputTokens: add((c) => c.cacheCreationInputTokens),
+		cacheReadInputTokens: add((c) => c.cacheReadInputTokens),
+		outputTokens: add((c) => c.outputTokens),
+		models: [...new Set(costs.flatMap((c) => c.models))]
+	};
+}
+//#endregion
 //#region src/claude/invoke.ts
 function resolveModel(explicit) {
 	if (explicit) return explicit;
@@ -1498,6 +1553,7 @@ async function invokeClaudeStreaming(options, onEvent) {
 		errorDetail = err instanceof Error ? err.message : String(err);
 		if (!result) result = errorDetail;
 	}
+	tallyInvocation(cost);
 	return {
 		result,
 		isError,
@@ -13127,8 +13183,8 @@ For each step:
 3. Execute the action using an ALLOWED selector (see Selector Rules), prefixing the command with \`CCQA_STEP=<step-id>\` like every agent-browser command in the step.
 4. Emit \`AB_ACTION|...\` for every browser action (see AB_ACTION Protocol).
 5. Run \`snapshot\` again to verify the outcome.
-6. Confirm at least **two independent signals** (URL change, element appearance, text change, ...).
-7. Record each verified signal as an assertion by putting a \`CCQA_ASSERT=<marker>\` prefix on the verification command itself (see Assertion Protocol). Only the assert types markers cannot express fall back to \`AB_ACTION|assert|...\` text lines.
+6. Confirm at least **two independent signals** (URL change, element appearance, text change, ...). This is how *you* decide the step worked and it is safe to continue. It is not what gets recorded.
+7. Record as assertions only the signals the step's own \`expected\` asks about, by putting a \`CCQA_ASSERT=<marker>\` prefix on the verification command itself (see Assertion Protocol). Only the assert types markers cannot express fall back to \`AB_ACTION|assert|...\` text lines.
 8. Emit \`STEP_DONE\`, \`ASSERTION_FAILED\`, or \`STEP_SKIPPED\`.
 
 **Protocol lines are recorded ONLY from your plain assistant text.** Every
@@ -13259,7 +13315,9 @@ CCQA_STEP=<step-id> CCQA_ASSERT=url_contains:/dashboard agent-browser --session
 - A marked command that exits non-zero records nothing — fix the check and re-run it.
 - A marker that doesn't match its command (e.g. \`CCQA_ASSERT=1\` on a \`click\`) is ignored with a warning — never do that.
 - \`get count\` and \`get url\` exit 0 regardless of what they print. **Read the output**: if the printed count / URL contradicts the marker, the signal did NOT verify — treat it as a failed verification (emit \`ASSERTION_FAILED\` if the step cannot be confirmed another way).
-- **\`url_contains\` is opt-in, not a habit.** Emit it ONLY when a step's own \`expected\` explicitly asks about the URL or path. Do NOT add a \`url_contains\` to "prove" a login succeeded, a page loaded, or a navigation happened — confirm those with \`text_visible\` / \`element_visible\` on something the destination page renders. An unrequested URL assertion adds no coverage the visible-content assert doesn't already give, and is the single most common way an environment gets baked into a test.
+- **Assert what the step asks about, nothing else.** The \`expected\` is the contract; anything else you happened to see on the way is not. A nav item, a heading or a greeting that the step never mentions adds no coverage, differs between recordings of the same spec, and is the first thing to break on replay — so the next recording quietly drops it and the test gets weaker without anyone deciding that.
+
+- **\`url_contains\` is opt-in, not a habit.** The same rule, in the form that gets broken most. Emit it ONLY when a step's own \`expected\` explicitly asks about the URL or path. Do NOT add a \`url_contains\` to "prove" a login succeeded, a page loaded, or a navigation happened — confirm those with \`text_visible\` / \`element_visible\` on something the destination page renders. An unrequested URL assertion adds no coverage the visible-content assert doesn't already give, and is the single most common way an environment gets baked into a test.
 - **When you do assert a URL, the substring may come from ONE place only:** a \`\${VAR}\` URL that *this step's own instruction* opened, written as that \`\${VAR}\` followed by the literal tail after it. If the step opens \`\${APP_URL}/policies\`, assert \`\${APP_URL}/policies\` (or the tail \`/policies\`); the recorder resolves \`\${APP_URL}\` per environment. Never assert on a URL you merely *observed* — login redirects, identity-provider pages, and OAuth callbacks all live on a **different, environment-named origin** than the app, so any substring of them (host, origin, OR path) names the environment.
 - **A leading slash does NOT make a substring safe.** \`/auth-staging\`, \`/env-qa\`, \`/tenant-acme\` look like paths but are environment labels — the first segment of an identity-provider or tenant URL, not an application route. If a substring contains an environment name, a stage token (\`dev\`, \`stg\`, \`prod\`), a tenant/org name, or any fragment of a hostname, it is forbidden even with a leading slash. The only safe path substrings are stable *application* routes off the app's own origin (\`/dashboard\`, \`/policies/new\`), taken from a \`\${VAR}\` you opened — not from a redirect you watched.
 
@@ -15059,12 +15117,36 @@ const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Com
 	});
 }));
 //#endregion
+//#region src/cli/cost-line.ts
+/**
+* Write what this command spent on Claude to stderr.
+*
+* stderr rather than stdout because `drift --format json` and `select-specs`
+* put machine-readable output on stdout, and a cost line mixed into it breaks
+* the consumer. Cost is diagnostics about the command, not its output.
+*/
+function reportCost() {
+	const cost = readCostTally();
+	if (cost === null) return;
+	const summary = formatLiveCost(cost, { compact: false });
+	if (summary) process.stderr.write(`[cost] ${summary}\n`);
+}
+//#endregion
 //#region src/cli/record.ts
 const VALIDATION_MODES = ["lenient", "strict"];
 const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Record a test from a spec: run agent-browser to collect actions (trace), then compile them into runnable code via the spec's target (generate) — a vitest test.spec.ts for agent-browser, a @playwright/test spec for the playwright target. Recording-backed targets only; spec-input targets like runn have no trace step (use `ccqa generate`), and agent-browser live specs need no recording.").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--validation-mode <mode>", "Post-trace validation behaviour: 'lenient' (default) tags failing actions; 'strict' drops them.", (raw) => {
 	if (VALIDATION_MODES.includes(raw)) return raw;
 	throw new Error(`--validation-mode must be one of ${VALIDATION_MODES.join(" | ")}`);
 }, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--max-retries <n>", "Maximum number of auto-fix retries", "3").option("--force", "Overwrite an existing test.spec.ts without warning").option("--no-snapshot", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").option("--skip-trace", "Skip the trace step and run codegen against an existing ir.json").option("--skip-codegen", "Run only the trace step (do not generate test.spec.ts)").option("--update-agent-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
+	await withCostTally(async () => {
+		try {
+			await runRecord(specPath, opts);
+		} finally {
+			reportCost();
+		}
+	});
+}));
+async function runRecord(specPath, opts) {
 	const { featureName, specName } = parseSpecPath(specPath);
 	const language = opts.language ?? "auto";
 	if (opts.skipTrace && opts.skipCodegen) {
@@ -15151,7 +15233,7 @@ const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Comma
 		...language ? { language } : {},
 		...opts.model ? { model: opts.model } : {}
 	});
-}));
+}
 /**
 * Compact summary of the trace pass for the record agent-prompt refresh.
 * Steps are reconstructed from the trace's status-line protocol (STEP_START
@@ -15467,6 +15549,9 @@ function driftResultsToReport(results, meta) {
 //#region src/cli/drift.ts
 const DEFAULT_CONCURRENCY = 3;
 const driftCommand = addLanguageOption(new Command("drift").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Standalone spec ↔ codebase static audit. Use for PR checks where the browser isn't run. For run-time audit with a structured report, see `ccqa run --report`.").option("--format <fmt>", "Output format: text | json | github", "text").option("--severity <level>", "Exit non-zero on this severity or higher: warn | error", "error").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--changed", "Restrict drift checks to the specs a change reaches, decided by `ccqa select-specs` against --base (or, in CI, $GITHUB_BASE_REF). Costs one model call; specs it cannot decide are checked rather than skipped.").option("--base <ref>", "Base ref to diff against when --changed is set. Defaults to $GITHUB_BASE_REF (CI pull_request runs); required otherwise.").option("--push", "Push the drift result to a ccqa hub as a run (kind: drift).").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption)).action(withUsageErrors(async (specPath, opts) => {
+	await withCostTally(() => runDrift(specPath, opts));
+}));
+async function runDrift(specPath, opts) {
 	const format = parseFormat$1(opts.format);
 	const threshold = parseSeverity(opts.severity);
 	const concurrency = parseConcurrency(opts.concurrency);
@@ -15518,8 +15603,9 @@ const driftCommand = addLanguageOption(new Command("drift").argument("[feature/s
 		format,
 		baseRef
 	});
+	reportCost();
 	process.exit(determineExitCode(results, threshold));
-}));
+}
 /**
 * Push a finished drift audit to a ccqa hub as a `kind: "drift"` run, so it
 * shows up alongside `ccqa run` runs in the hub UI. Best-effort: a missing
@@ -15574,6 +15660,7 @@ async function pushDriftResults(args, resolveHub = resolveHubClient) {
 	}
 }
 function exitWithNoSpecs(format, message) {
+	reportCost();
 	if (format === "json") process.stdout.write(`${JSON.stringify({ specs: [] }, null, 2)}\n`);
 	else if (format === "text") info(message);
 	process.exit(0);
@@ -15639,6 +15726,9 @@ const initCommand = new Command("init").description("Create the .ccqa/ spec skel
 //#region src/cli/select-specs.ts
 const DEFAULT_HEAD = "HEAD";
 const selectSpecsCommand = new Command("select-specs").description("Decide which specs a range of commits reaches. Reads the diff and the spec inventory and returns one verdict per spec: needed | notNeeded | unknown.").requiredOption("--base <ref>", "Commit the range starts at — typically what is currently deployed, or the previous commit on the branch.").option("--head <ref>", `Commit the range ends at (default: ${DEFAULT_HEAD})`).option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Changes outside it are reported but never attributed to a spec. Defaults to process.cwd().").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--format <fmt>", "Output format: text | json", "text").action(async (opts) => {
+	await withCostTally(() => runSelectSpecs(opts));
+});
+async function runSelectSpecs(opts) {
 	const format = parseFormat(opts.format);
 	const cwd = resolveCwd(opts.cwd);
 	const head = opts.head ?? DEFAULT_HEAD;
@@ -15684,8 +15774,9 @@ const selectSpecsCommand = new Command("select-specs").description("Decide which
 		...opts.model ? { model: opts.model } : {}
 	});
 	process.stdout.write(format === "json" ? `${JSON.stringify(report, null, 2)}\n` : renderText(report));
+	reportCost();
 	process.exit(0);
-});
+}
 const VERDICT_ORDER = [
 	"needed",
 	"unknown",

package/dist/package.json

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

package/package.json

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