pi-cursor-sdk 0.1.28 → 0.1.29

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.28",
+	"version": "0.1.29",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",
@@ -36,6 +36,21 @@
 		"scripts/debug-sdk-events.d.mts",
 		"scripts/debug-provider-events.mjs",
 		"scripts/debug-provider-events.d.mts",
+		"platform-smoke.config.mjs",
+		"scripts/platform-smoke.mjs",
+		"scripts/platform-smoke/assertions.mjs",
+		"scripts/platform-smoke/artifacts.mjs",
+		"scripts/platform-smoke/card-detect.mjs",
+		"scripts/platform-smoke/crabbox-runner.mjs",
+		"scripts/platform-smoke/doctor.mjs",
+		"scripts/platform-smoke/live-suite-runner.mjs",
+		"scripts/platform-smoke/jsonl-text.mjs",
+		"scripts/platform-smoke/platform-build-windows.ps1",
+		"scripts/platform-smoke/pty-capture.mjs",
+		"scripts/platform-smoke/render-ansi.mjs",
+		"scripts/platform-smoke/scenarios.mjs",
+		"scripts/platform-smoke/targets.mjs",
+		"scripts/platform-smoke/visual-evidence.mjs",
 		"scripts/lib/cursor-cli-args.mjs",
 		"scripts/lib/cursor-cli-args.d.mts",
 		"scripts/lib/cursor-child-process.mjs",
@@ -54,9 +69,11 @@
 		"docs/cursor-tool-surfaces.md",
 		"docs/cursor-live-smoke-checklist.md",
 		"docs/cursor-testing-lessons.md",
+		"docs/crabbox-platform-testing-lessons.md",
 		"docs/cursor-dogfood-checklist.md",
 		"docs/cursor-native-tool-replay.md",
 		"docs/cursor-native-tool-visual-audit.md",
+		"docs/platform-smoke.md",
 		"LICENSE",
 		"CHANGELOG.md"
 	],
@@ -69,6 +86,7 @@
 		"typecheck:src": "tsc --noEmit",
 		"typecheck:tests": "tsc -p tsconfig.test.json --noEmit",
 		"typecheck:replay-compile": "tsc --noEmit -p test/tsconfig.json",
+		"verify": "npm run check:platform-smoke && npm run typecheck && npm test",
 		"test": "vitest run",
 		"test:watch": "vitest",
 		"refresh:cursor-snapshots": "node scripts/refresh-cursor-model-snapshots.mjs",
@@ -79,10 +97,17 @@
 		"smoke:jsonl": "node scripts/validate-smoke-jsonl.mjs",
 		"debug:sdk-events": "node scripts/debug-sdk-events.mjs",
 		"debug:provider-events": "node scripts/debug-provider-events.mjs",
-		"debug:mcp-coldstart": "node scripts/probe-mcp-coldstart.mjs"
+		"debug:mcp-coldstart": "node scripts/probe-mcp-coldstart.mjs",
+		"check:platform-smoke": "node --check scripts/platform-smoke.mjs && node --check scripts/platform-smoke/assertions.mjs && node --check scripts/platform-smoke/artifacts.mjs && node --check scripts/platform-smoke/card-detect.mjs && node --check scripts/platform-smoke/crabbox-runner.mjs && node --check scripts/platform-smoke/doctor.mjs && node --check scripts/platform-smoke/jsonl-text.mjs && node --check scripts/platform-smoke/live-suite-runner.mjs && node --check scripts/platform-smoke/pty-capture.mjs && node --check scripts/platform-smoke/render-ansi.mjs && node --check scripts/platform-smoke/scenarios.mjs && node --check scripts/platform-smoke/targets.mjs && node --check scripts/platform-smoke/visual-evidence.mjs && vitest run test/smoke-tooling.test.ts",
+		"smoke:platform": "node scripts/platform-smoke.mjs",
+		"smoke:platform:doctor": "node scripts/platform-smoke.mjs doctor",
+		"smoke:platform:macos": "node scripts/platform-smoke.mjs run --target macos",
+		"smoke:platform:ubuntu": "node scripts/platform-smoke.mjs run --target ubuntu",
+		"smoke:platform:windows-native": "node scripts/platform-smoke.mjs run --target windows-native",
+		"smoke:platform:all": "npm run smoke:platform:doctor && node scripts/platform-smoke.mjs run --target macos,ubuntu,windows-native"
 	},
 	"dependencies": {
-		"@cursor/sdk": "1.0.16",
+		"@cursor/sdk": "1.0.17",
 		"@modelcontextprotocol/sdk": "^1.29.0"
 	},
 	"peerDependencies": {
@@ -96,6 +121,7 @@
 		"@earendil-works/pi-coding-agent": "0.78.0",
 		"@earendil-works/pi-tui": "0.78.0",
 		"@xterm/xterm": "^6.0.0",
+		"node-pty": "^1.1.0",
 		"playwright": "^1.60.0",
 		"typebox": "^1.1.38",
 		"typescript": "^6.0.3",
@@ -109,5 +135,8 @@
 	"overrides": {
 		"undici": "7.25.0",
 		"sqlite3": "6.0.1"
+	},
+	"allowScripts": {
+		"node-pty@1.1.0": true
 	}
 }

package/platform-smoke.config.mjs

@@ -0,0 +1,21 @@
+// Platform smoke configuration for pi-cursor-sdk.
+// Reusable across pi extensions: change package name, model IDs, scenarios, and card matrix only.
+
+export default {
+	packageName: "pi-cursor-sdk",
+	cursorModel: "cursor/composer-2-5",
+	artifactRoot: ".artifacts/platform-smoke",
+	requiredTargets: ["macos", "ubuntu", "windows-native"],
+	requiredSuites: [
+		"platform-build",
+		"cursor-native-visual-matrix",
+		"cursor-bridge-visual-matrix",
+		"cursor-abort-cleanup",
+	],
+	requiredCrabbox: {
+		install: "brew install crabbox",
+		version: "0.24.0",
+	},
+	ubuntuContainerImage: "cimg/node:24.16",
+	nodeValidationMajor: 24,
+};

package/scripts/debug-provider-events.mjs

@@ -5,7 +5,7 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
 	apiKeySecretsFromProcess,
@@ -20,10 +20,17 @@ import { scrubSensitiveText } from "../shared/cursor-sensitive-text.mjs";
 import { createScriptFail } from "./lib/cursor-script-fail.mjs";
 import { serializeCursorSettingSources } from "../shared/cursor-setting-sources.mjs";
 
+function isMainModule() {
+	if (!process.argv[1]) return false;
+	const current = fileURLToPath(import.meta.url);
+	const invoked = resolve(process.argv[1]);
+	return process.platform === "win32" ? current.toLowerCase() === invoked.toLowerCase() : current === invoked;
+}
+
 const require = createRequire(import.meta.url);
 const root = fileURLToPath(new URL("..", import.meta.url));
 const packageJson = require("../package.json");
-const DEFAULT_MODEL = "cursor/composer-2.5";
+const DEFAULT_MODEL = "cursor/composer-2-5";
 const DEFAULT_OUT_BASE = ".debug/cursor-sdk-events";
 const SDK_EVENT_DEBUG_LOG_PREFIX = "[pi-cursor-sdk:sdk-events]";
 const PI_SESSION_SNAPSHOT_ARTIFACT = "pi-session-snapshot.jsonl";
@@ -291,7 +298,7 @@ async function main(argv = process.argv.slice(2), env = process.env) {
 	console.log(JSON.stringify(await runDebugProviderEvents(args, env)));
 }
 
-if (import.meta.url === new URL(process.argv[1], "file:").href) {
+if (isMainModule()) {
 	main().catch((error) => {
 		fail(error instanceof Error ? error.message : String(error), apiKeySecretsFromProcess());
 	});

package/scripts/debug-sdk-events.mjs

@@ -5,7 +5,8 @@
  */
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
 import {
 	apiKeySecretsFromProcess,
 	commonProbeFlags,
@@ -18,6 +19,13 @@ import {
 import { createScriptFail } from "./lib/cursor-script-fail.mjs";
 import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./lib/cursor-sdk-output-filter.mjs";
 
+function isMainModule() {
+	if (!process.argv[1]) return false;
+	const current = fileURLToPath(import.meta.url);
+	const invoked = resolve(process.argv[1]);
+	return process.platform === "win32" ? current.toLowerCase() === invoked.toLowerCase() : current === invoked;
+}
+
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 
@@ -343,7 +351,7 @@ async function main(argv = process.argv.slice(2), env = process.env) {
 	await captureEvents(args);
 }
 
-if (import.meta.url === new URL(process.argv[1], "file:").href) {
+if (isMainModule()) {
 	main().catch((error) => {
 		const message = error instanceof Error ? error.message : String(error);
 		fail(message, apiKeySecretsFromProcess());

package/scripts/isolated-cursor-smoke.sh

@@ -361,13 +361,13 @@ log "check: list-models"
 LIST_OUT="$ISOLATED/list-models.txt"
 run_in_dir_capture_combined "list-models" 30 "$PROJECT_DIR" "$LIST_OUT" "${PI_CURSOR_ENV[@]}" \
 	"$PI_BIN" --cursor-no-fast --list-models cursor
-"$RG_BIN" -q "composer-2\\.5|composer-2-5" "$LIST_OUT" || fail "composer-2.5 not listed (see $LIST_OUT)"
+"$RG_BIN" -q "composer-2\\.5|composer-2-5" "$LIST_OUT" || fail "composer-2-5 not listed (see $LIST_OUT)"
 
 log "check: basic provider prompt"
 BASIC_DIR="$SESSION_ROOT/basic"
 mkdir -p "$BASIC_DIR"
 run_in_dir_capture_split "basic prompt" "$PI_LIVE_TIMEOUT" "$PROJECT_DIR" "$ISOLATED/basic.stdout.txt" "$ISOLATED/basic.stderr.txt" "${PI_CURSOR_ENV[@]}" \
-	"$PI_BIN" --cursor-no-fast --model cursor/composer-2.5 --session-dir "$BASIC_DIR" --no-tools -p 'Reply exactly: PI_CURSOR_ISOLATED_OK'
+	"$PI_BIN" --cursor-no-fast --model cursor/composer-2-5 --session-dir "$BASIC_DIR" --no-tools -p 'Reply exactly: PI_CURSOR_ISOLATED_OK'
 "$RG_BIN" -q "PI_CURSOR_ISOLATED_OK" "$ISOLATED/basic.stdout.txt" || fail "basic prompt missing PI_CURSOR_ISOLATED_OK"
 validate_replay_jsonl "$BASIC_DIR"
 
@@ -375,14 +375,14 @@ log "check: native replay"
 REPLAY_DIR="$SESSION_ROOT/native-replay"
 mkdir -p "$REPLAY_DIR"
 run_in_dir_capture_split "native replay" "$PI_LIVE_TIMEOUT" "$PROJECT_DIR" "$ISOLATED/replay.stdout.txt" "$ISOLATED/replay.stderr.txt" "${PI_CURSOR_ENV[@]}" PI_CURSOR_NATIVE_TOOL_DISPLAY=1 \
-	"$PI_BIN" --cursor-no-fast --model cursor/composer-2.5 --session-dir "$REPLAY_DIR" -p 'Read ./README.md briefly, then answer README_SEEN=yes if it mentions pi-cursor-sdk.'
+	"$PI_BIN" --cursor-no-fast --model cursor/composer-2-5 --session-dir "$REPLAY_DIR" -p 'Read ./README.md briefly, then answer README_SEEN=yes if it mentions pi-cursor-sdk.'
 validate_replay_jsonl "$REPLAY_DIR"
 
 log "check: plan-strip shim (plan-mode execute reset)"
 PLAN_DIR="$SESSION_ROOT/plan-strip"
 mkdir -p "$PLAN_DIR"
 run_in_dir_capture_split "plan-strip replay" "$PI_LIVE_TIMEOUT" "$PROJECT_DIR" "$ISOLATED/plan.stdout.txt" "$ISOLATED/plan.stderr.txt" "${PI_CURSOR_ENV[@]}" PI_CURSOR_NATIVE_TOOL_DISPLAY=1 \
-	"$PI_BIN" -e "$SHIM_DIR" --cursor-no-fast --model cursor/composer-2.5 --session-dir "$PLAN_DIR" -p 'After reset, read README.md and answer PLAN_STRIP_OK=yes.'
+	"$PI_BIN" -e "$SHIM_DIR" --cursor-no-fast --model cursor/composer-2-5 --session-dir "$PLAN_DIR" -p 'After reset, read README.md and answer PLAN_STRIP_OK=yes.'
 validate_replay_jsonl "$PLAN_DIR"
 
 log "PASS isolated install smoke: $ISOLATED"

package/scripts/lib/cursor-visual-render.mjs

@@ -91,6 +91,7 @@ try {
 	});
 	term.open(terminalElement);
 	term.resize(${options.width}, ${options.height});
+	window.__piVisualSmokeTerminal = term;
 	term.write(ansi, () => {
 		document.body.setAttribute("data-render-ready", "true");
 	});

package/scripts/platform-smoke/artifacts.mjs

@@ -0,0 +1,124 @@
+/**
+ * Artifact management — directory layout, manifest, redaction scanning, packaging.
+ */
+
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { resolve, relative, basename } from "node:path";
+
+/** Create a suite artifact directory. */
+export function createSuiteDir(artifactRoot, runId, targetName, suiteName) {
+	const dir = resolve(process.cwd(), artifactRoot, runId, targetName, suiteName);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+/** Write artifact-manifest.json. */
+export function writeManifest(dir, expectedFiles) {
+	const actual = [];
+	function walk(d) {
+		for (const entry of readdirSync(d, { withFileTypes: true })) {
+			const fp = resolve(d, entry.name);
+			if (entry.isDirectory()) walk(fp);
+			else if (entry.isFile()) actual.push(relative(dir, fp));
+		}
+	}
+	if (existsSync(dir)) walk(dir);
+
+	const manifest = {
+		expected: expectedFiles ?? [],
+		present: actual,
+		missing: (expectedFiles ?? []).filter(f => !actual.includes(f)),
+		writtenAt: new Date().toISOString(),
+	};
+	writeFileSync(resolve(dir, "artifact-manifest.json"), JSON.stringify(manifest, null, 2));
+	return manifest;
+}
+
+const SECRET_PATTERNS = [
+	[/Authorization:\s*Bearer\s+[A-Za-z0-9\-._~+/]{20,}=*/gi, "Authorization header", "Authorization: Bearer [REDACTED_BEARER_TOKEN]"],
+	[/(bearer\s+)[A-Za-z0-9\-._~+/]{20,}=*/gi, "bearer token", "$1[REDACTED_BEARER_TOKEN]"],
+	[/connect\.sid=[A-Za-z0-9%]+/gi, "session cookie", "connect.sid=[REDACTED_SESSION_COOKIE]"],
+	[/https?:\/\/[^/\s]*\/cursor-pi-tool-bridge\/[A-Za-z0-9_.:-]+\/mcp/gi, "bridge endpoint URL", "[REDACTED_BRIDGE_ENDPOINT_URL]"],
+	[/"(apiKey|accessToken|refreshToken|session|cookie)"\s*:\s*"[^"\s]{12,}"/gi, "auth/token JSON field", '"$1":"[REDACTED_SECRET]"'],
+];
+
+/** Redact known secret material before writing logs/artifacts. */
+export function redactSecrets(text) {
+	let redacted = String(text ?? "");
+	const cursorKey = process.env.CURSOR_API_KEY;
+	if (cursorKey && cursorKey.length > 10) {
+		redacted = redacted.split(cursorKey).join("[REDACTED_CURSOR_API_KEY]");
+	}
+	for (const [pattern, , replacement] of SECRET_PATTERNS) {
+		redacted = redacted.replace(pattern, replacement);
+	}
+	return redacted;
+}
+
+/** Scan text content for secrets. Returns array of violation descriptions. */
+export function scanForSecrets(text) {
+	const violations = [];
+	const cursorKey = process.env.CURSOR_API_KEY;
+	if (cursorKey && cursorKey.length > 10 && String(text ?? "").includes(cursorKey)) {
+		violations.push("CURSOR_API_KEY literal found");
+	}
+	for (const [pattern, label] of SECRET_PATTERNS) {
+		pattern.lastIndex = 0;
+		if (pattern.test(String(text ?? ""))) violations.push(`potential ${label}`);
+	}
+	return violations;
+}
+
+/** Scan all text files in a directory for secrets. */
+export function scanArtifacts(dir) {
+	const findings = [];
+	function walk(d) {
+		for (const entry of readdirSync(d, { withFileTypes: true })) {
+			const fp = resolve(d, entry.name);
+			if (entry.isDirectory()) { walk(fp); continue; }
+			if (!entry.isFile()) continue;
+			const ext = entry.name.split(".").pop()?.toLowerCase() ?? "";
+			if (!["txt", "json", "jsonl", "md", "log", "ansi", "html", "yml", "yaml", "js", "mjs", "ts"].includes(ext)) continue;
+			try {
+				const content = readFileSync(fp, "utf-8");
+				const violations = scanForSecrets(content);
+				for (const v of violations) {
+					findings.push({ file: relative(dir, fp), violation: v });
+				}
+			} catch { /* binary or unreadable */ }
+		}
+	}
+	walk(dir);
+	return findings;
+}
+
+/** Write summary.json for a suite. */
+export function writeSummary(dir, data) {
+	writeFileSync(resolve(dir, "summary.json"), JSON.stringify({
+		...data,
+		writtenAt: new Date().toISOString(),
+	}, null, 2));
+}
+
+/** Write command.txt recording the command that was executed. */
+export function writeCommand(dir, cmd) {
+	writeFileSync(resolve(dir, "command.txt"), Array.isArray(cmd) ? cmd.join(" ") + "\n" : cmd + "\n");
+}
+
+/** Write exit-code.txt. */
+export function writeExitCode(dir, code, signal) {
+	writeFileSync(resolve(dir, "exit-code.txt"), `code=${code}\nsignal=${signal ?? "none"}\n`);
+}
+
+/** Package a directory as tar.gz (posix) or zip (powershell). */
+export async function packageArtifacts(dir, archivePath) {
+	const { execSync } = await import("node:child_process");
+	const dirName = basename(dir);
+	const parentDir = resolve(dir, "..");
+	if (archivePath.endsWith(".tar.gz")) {
+		execSync(`tar -czf "${archivePath}" -C "${parentDir}" "${dirName}"`, { stdio: "pipe" });
+	} else if (archivePath.endsWith(".zip")) {
+		execSync(`cd "${parentDir}" && zip -r "${archivePath}" "${dirName}"`, { stdio: "pipe" });
+	}
+	return archivePath;
+}

package/scripts/platform-smoke/assertions.mjs

@@ -0,0 +1,101 @@
+/**
+ * Assertion engine — assertions.json, failures.md, JSONL parsing.
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { resolve, basename } from "node:path";
+
+/** Run a set of checks and write assertions.json. */
+export function runAssertions(dir, checks) {
+	const results = [];
+	let allOk = true;
+	for (const check of checks) {
+		try {
+			const ok = check.fn();
+			results.push({ id: check.id, ok, ...(ok ? {} : { error: check.error }) });
+			if (!ok) allOk = false;
+		} catch (e) {
+			results.push({ id: check.id, ok: false, error: e.message });
+			allOk = false;
+		}
+	}
+
+	const assertions = {
+		ok: allOk,
+		checks: results,
+		writtenAt: new Date().toISOString(),
+	};
+
+	writeFileSync(resolve(dir, "assertions.json"), JSON.stringify(assertions, null, 2));
+
+	if (!allOk) {
+		const failures = results.filter(r => !r.ok);
+		const md = [
+			"# Assertion Failures",
+			"",
+			...failures.map(f => `- **${f.id}**: ${f.error ?? "failed"}`),
+			"",
+			`Total: ${failures.length} failure(s)`,
+		];
+		writeFileSync(resolve(dir, "failures.md"), md.join("\n") + "\n");
+	}
+
+	return assertions;
+}
+
+/** Parse a JSONL file into an array of objects. */
+export function parseJSONL(path) {
+	if (!existsSync(path)) return [];
+	try {
+		const text = readFileSync(path, "utf-8");
+		return text.split("\n").filter(Boolean).map(line => {
+			try { return JSON.parse(line); } catch { return null; }
+		}).filter(Boolean);
+	} catch {
+		return [];
+	}
+}
+
+/** Find a session JSONL file in a session directory. */
+export function findSessionJSONL(sessionDir) {
+	if (!existsSync(sessionDir)) return null;
+	for (const entry of readdirSync(sessionDir, { withFileTypes: true })) {
+		if (entry.isDirectory()) {
+			const found = findSessionJSONL(resolve(sessionDir, entry.name));
+			if (found) return found;
+		}
+		if (entry.name.endsWith(".jsonl") && !entry.name.includes("events")) {
+			return resolve(sessionDir, entry.name);
+		}
+	}
+	return null;
+}
+
+/** Simple check: does text contain a required substring? */
+export function assertContains(text, substring, id) {
+	return { id, fn: () => text.includes(substring) };
+}
+
+/** Simple check: does a file exist? */
+export function assertFileExists(path, id) {
+	return { id, fn: () => existsSync(path) };
+}
+
+/** Check JSONL for required tool calls. */
+export function assertJSONLToolCalls(jsonlPath, expectedTools) {
+	return {
+		id: "jsonl-tool-calls",
+		fn: () => {
+			const events = parseJSONL(jsonlPath);
+			const toolCalls = events.filter(e => e.type === "tool_use" || e.toolCall);
+			for (const expected of expectedTools) {
+				const found = toolCalls.some(tc => {
+					const name = tc.toolCall?.name ?? tc.name ?? tc.tool_name ?? "";
+					return name === expected.name;
+				});
+				if (!found) return false;
+			}
+			return true;
+		},
+	};
+}

package/scripts/platform-smoke/card-detect.mjs

@@ -0,0 +1,96 @@
+/**
+ * Card detector — records stable visible evidence regions from rendered terminal output.
+ *
+ * This is intentionally stricter than a raw text-marker search: prompt lines such as
+ * "call pi__read" must not satisfy card assertions. Per-card screenshots come from
+ * visual-evidence.mjs; this module writes the legacy cards.json/index.html inventory.
+ */
+
+import { writeFileSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+const CARD_PATTERNS = [
+	{ id: "read", pattern: /^\s*read (?:\.\/)?package\.json\s*$/i },
+	{ id: "grep", pattern: /^\s*grep \/pi-cursor-sdk\/ in README\.md\s*$/i },
+	{ id: "find", pattern: /^\s*find README\.md in\s+\S+/i },
+	{ id: "list", pattern: /^\s*(?:find \* in src|find src\/\* in \.|Get-ChildItem -Name \.\/src)\s*/i },
+	{ id: "shell-success", pattern: /^\s*cursor visual smoke\s*$/i },
+	{ id: "write", pattern: /^\s*\+.*beta\s*$/i },
+	{ id: "edit-diff", pattern: /^\s*\+.*gamma\s*$/i },
+	{ id: "shell-failure", pattern: /^\s*(?:native shell failure|Command exited with code 7)\s*$/i },
+	{ id: "bridge-read-success", pattern: /^\s*read \.\/package\.json\s*$/i },
+	{ id: "bridge-read-failure", pattern: /^\s*(?:read \.\/definitely-missing-platform-smoke-file\.txt|ENOENT: no such file)\s*/i },
+	{ id: "bridge-shell-success", pattern: /^\s*bridge visual smoke\s*$/i },
+	{ id: "footer-status", pattern: /\bcomposer-2-5\b|\bcomposer-2\.5\b/i },
+];
+
+function cleanLine(line) {
+	return line
+		.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "")
+		.replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "")
+		.replace(/\r/g, "");
+}
+
+/**
+ * Detect stable rendered evidence regions in terminal text.
+ *
+ * Returns an array of { id, label, startLine, endLine }.
+ */
+export function detectCards(txtContent) {
+	const lines = txtContent.split("\n").map(cleanLine);
+	const cards = [];
+	const seen = new Set();
+
+	for (let i = 0; i < lines.length; i++) {
+		for (const card of CARD_PATTERNS) {
+			if (seen.has(card.id)) continue;
+			card.pattern.lastIndex = 0;
+			if (!card.pattern.test(lines[i])) continue;
+			seen.add(card.id);
+			cards.push({
+				id: card.id,
+				label: card.id,
+				startLine: i,
+				endLine: i,
+			});
+		}
+	}
+
+	return cards;
+}
+
+/** Write cards.json and cards/index.html gallery. */
+export function writeCardArtifacts(dir, cards) {
+	mkdirSync(resolve(dir, "cards"), { recursive: true });
+
+	const cardsData = cards.map(c => ({
+		id: c.id,
+		label: c.label,
+		startLine: c.startLine,
+		endLine: c.endLine,
+		lineCount: c.endLine - c.startLine + 1,
+	}));
+
+	writeFileSync(resolve(dir, "cards", "cards.json"), JSON.stringify(cardsData, null, 2));
+
+	const html = `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Cards Gallery</title>
+<style>
+body { font-family: monospace; background: #1e1e1e; color: #d4d4d4; padding: 20px; }
+.card { border: 1px solid #444; margin: 8px 0; padding: 8px; }
+.card h3 { margin: 0 0 4px 0; color: #569cd6; }
+.card .meta { color: #888; font-size: 12px; }
+</style></head><body>
+<h1>Cards Gallery</h1>
+${cardsData.map(c => `<div class="card"><h3>${c.label}</h3><div class="meta">line ${c.startLine}</div></div>`).join("\n")}
+</body></html>`;
+
+	writeFileSync(resolve(dir, "cards", "index.html"), html);
+}
+
+/** Assert that required cards are present as distinct exact evidence ids. */
+export function assertRequiredCards(_dir, detectedCards, requiredCards) {
+	const detectedIds = new Set(detectedCards.map(c => c.id));
+	return requiredCards.map((req) => ({ id: `card-${req}`, ok: detectedIds.has(req) }));
+}