@ait-co/devtools 0.1.129 → 0.1.132

package/dist/test-runner/bin.js

@@ -22,6 +22,23 @@ import { fileURLToPath } from "node:url";
 * safe to import from the MCP daemon graph.
 */
 /**
+* Filename suffix that opts a test file into manual-variant scheduling
+* (devtools#741). A file named `<name>.manual.ait.test.ts` is EXCLUDED from
+* `discoverTestFiles`'s default output (so existing unattended runs are
+* unaffected — the zero-diff-when-off constraint) and is only surfaced when
+* the caller explicitly asks for manual files via {@link partitionManualTests}
+* (wired from the CLI's `--manual-blocking` flag).
+*
+* This is the entire tagging contract for v1 — no separate manifest/config,
+* just a filename convention. Documented here + in the CLI `--help` text
+* (cli.ts USAGE) and the test-runner README.
+*/
+const MANUAL_TEST_SUFFIX = ".manual.ait.test.ts";
+/** True when `file`'s basename ends with {@link MANUAL_TEST_SUFFIX}. */
+function isManualTestFile(file) {
+	return basename(file).endsWith(MANUAL_TEST_SUFFIX);
+}
+/**
 * Expands `patterns` (globs or plain paths) into a sorted, de-duplicated list of
 * ABSOLUTE test file paths, resolved relative to `cwd`.
 *
@@ -30,14 +47,46 @@ import { fileURLToPath } from "node:url";
 * resolved against `cwd`. `bundleTestFile` requires an absolute path, so the
 * absolute output feeds it directly.
 *
+* By default, files matching {@link MANUAL_TEST_SUFFIX} are EXCLUDED from the
+* result (devtools#741) — blocking-UI tests opt in via that filename
+* convention and must never appear in an unattended run unless the caller
+* explicitly asks for them via `includeManual: true`. This keeps the
+* default (flag-off) discovery path byte-for-byte identical to before this
+* option existed.
+*
 * @param patterns Glob patterns or file paths (e.g. `['src/**\/*.ait.test.ts']`).
 * @param cwd      Base directory for relative patterns/results.
+* @param opts     `{ includeManual }` — when true, manual-tagged files are kept
+*                 in the (still-sorted) output instead of being filtered out.
+*                 Use {@link partitionManualTests} to separate + reorder them.
 * @returns Sorted, de-duplicated absolute file paths. Empty when nothing matches.
 */
-async function discoverTestFiles(patterns, cwd) {
+async function discoverTestFiles(patterns, cwd, opts) {
 	const out = /* @__PURE__ */ new Set();
 	for await (const match of glob(patterns, { cwd })) out.add(isAbsolute(match) ? match : resolve(cwd, match));
-	return [...out].sort();
+	const sorted = [...out].sort();
+	if (opts?.includeManual) return sorted;
+	return sorted.filter((f) => !isManualTestFile(f));
+}
+/**
+* Splits an already-discovered file list into `{ regular, manual }`, each
+* still sorted. Used by the CLI's `--manual-blocking` path to schedule manual
+* files strictly AFTER every regular file (devtools#741) — regular files run
+* first (and produce the unattended-shaped part of the report) and manual
+* files run last, each preceded by a dashboard prompt.
+*
+* Pure partition — does not itself decide inclusion; call
+* `discoverTestFiles(patterns, cwd, { includeManual: true })` first so manual
+* files are present in `files` to partition.
+*/
+function partitionManualTests(files) {
+	const regular = [];
+	const manual = [];
+	for (const f of files) (isManualTestFile(f) ? manual : regular).push(f);
+	return {
+		regular,
+		manual
+	};
 }
 //#endregion
 //#region src/test-runner/relay-factory.ts
@@ -45,11 +94,14 @@ async function discoverTestFiles(patterns, cwd) {
 * Builds a {@link RelayConnectionFactory} that opens a standalone env3 relay
 * connection.
 *
-* `open()` performs the full attach lifecycle and BLOCKS for tens of seconds (up
-* to `timeoutMs`) while a human scans the rendered QR with their phone — there
-* is no way around the manual scan for env3. It resolves with the live
-* `CdpConnection` once a matching page attaches; `close()` tears the relay
-* family down.
+* `open()` performs the full attach lifecycle and BLOCKS while a human scans
+* the rendered QR with their phone — there is no way around the manual scan
+* for env3. By default the wait is UNBOUNDED (`opts.timeoutMs` omitted): the
+* runner stays up until the user stops it (Ctrl-C/SIGTERM), since QR-scan is
+* a human-paced action with no sound default bound (devtools#735). Passing an
+* explicit `timeoutMs` opts into the old bounded behavior (CI/headless
+* callers). It resolves with the live `CdpConnection` once a matching page
+* attaches; `close()` tears the relay family down.
 *
 * The factory holds the booted relay family in a closure so `close()` can stop
 * it. A second `open()` on the same factory boots a fresh family (the previous
@@ -57,16 +109,18 @@ async function discoverTestFiles(patterns, cwd) {
 */
 function createRelayConnectionFactory(opts) {
 	const projectRoot = opts.projectRoot ?? process.cwd();
-	const timeoutMs = opts.timeoutMs ?? 6e5;
+	const timeoutMs = opts.timeoutMs ?? Number.POSITIVE_INFINITY;
 	const headless = opts.headless === true;
 	let family;
 	let qrServer;
+	let phase = "active";
+	let manualPrompt = null;
 	return {
 		async open() {
-			const { prepareAttach, renderAndMaybeWait, mintAttachUrl } = await import("../attach-orchestrator-Bdt5Zdo9.js");
-			const { injectDebugIndicator, injectGlobals } = await import("../cell-DLRv4iG6.js");
+			const { prepareAttach, renderAndMaybeWait, mintAttachUrl } = await import("../attach-orchestrator-ca34r46y.js");
+			const { injectDebugIndicator, injectGlobals } = await import("../cell-rr6gL9AT.js");
 			const { loadRelaySecretReadOnly } = await import("../relay-secret-store-CFc9n0OA.js");
-			const { bootRelayFamily, buildRelayVerifyAuth } = await import("../debug-server-e1qPe0ZB.js");
+			const { bootRelayFamily, buildRelayVerifyAuth } = await import("../debug-server-BBUzxZSf.js");
 			await loadRelaySecretReadOnly({ projectRoot });
 			let resolveTunnelUp;
 			const tunnelReady = new Promise((resolve) => {
@@ -77,6 +131,9 @@ function createRelayConnectionFactory(opts) {
 				onWssUrl: () => {
 					resolveTunnelUp();
 					qrServer?.notifyStateChange();
+				},
+				onTunnelDown: () => {
+					qrServer?.notifyStateChange();
 				}
 			});
 			family = booted;
@@ -93,12 +150,14 @@ function createRelayConnectionFactory(opts) {
 				canOpenBrowser: () => !headless
 			};
 			try {
-				const { startQrHttpServer } = await import("../qr-http-server-s1iW_5VQ.js");
+				const { startQrHttpServer } = await import("../qr-http-server-KB147M-S.js");
 				const getDashboardState = () => ({
 					tunnel: attachDeps.getTunnelStatus(),
 					pages: null,
 					attachUrl: lastAttachParts ? mintAttachUrl(attachDeps, lastAttachParts) : null,
-					mode: "relay-dev"
+					mode: "relay-dev",
+					phase,
+					manualPrompt
 				});
 				qrServer = await startQrHttpServer(getDashboardState);
 				attachDeps.qrHttpServer = qrServer;
@@ -151,7 +210,23 @@ function createRelayConnectionFactory(opts) {
 			if (opts.cell !== void 0) await injectGlobals(booted.connection, { __AIT_CELL__: opts.cell });
 			return booted.connection;
 		},
-		async close(_connection) {
+		onSessionPhase(next) {
+			phase = next;
+			qrServer?.notifyStateChange();
+		},
+		onManualPrompt(next) {
+			manualPrompt = next;
+			qrServer?.notifyStateChange();
+		},
+		async close(connection) {
+			if (phase !== "complete") {
+				phase = "complete";
+				qrServer?.notifyStateChange();
+			}
+			try {
+				const { injectDebugIndicator } = await import("../cell-rr6gL9AT.js");
+				await injectDebugIndicator(connection, { state: "disconnected" });
+			} catch {}
 			family?.stop();
 			family = void 0;
 			await qrServer?.close();
@@ -484,7 +559,11 @@ var ChiiCdpConnection = class {
 	* EventEmitter is missed (defensive belt-and-suspenders).
 	*
 	* @param filterFn  - Predicate that the returned targets must satisfy.
-	* @param timeoutMs - Reject after this many ms (default 90 000).
+	* @param timeoutMs - Reject after this many ms (default 90 000). Pass a
+	*   non-finite value (`Infinity`) to disable the rejection timer entirely —
+	*   used by the test-runner's unbounded QR-attach wait (devtools#735). Node
+	*   clamps `setTimeout(fn, Infinity)` to ~1ms, so a non-finite value MUST
+	*   skip arming the timer rather than pass it through.
 	* @param pollIntervalMs - Fallback poll interval (default 500ms).
 	*/
 	waitForFirstTarget(filterFn, timeoutMs = 9e4, pollIntervalMs = 500) {
@@ -496,7 +575,7 @@ var ChiiCdpConnection = class {
 			const settle = (targets) => {
 				if (settled) return;
 				settled = true;
-				clearTimeout(timeoutHandle);
+				if (timeoutHandle !== null) clearTimeout(timeoutHandle);
 				if (pollHandle !== null) {
 					clearInterval(pollHandle);
 					pollHandle = null;
@@ -507,7 +586,7 @@ var ChiiCdpConnection = class {
 			const onAttach = (targets) => {
 				if (filterFn(targets)) settle(targets);
 			};
-			const timeoutHandle = setTimeout(() => {
+			const timeoutHandle = Number.isFinite(timeoutMs) ? setTimeout(() => {
 				if (settled) return;
 				settled = true;
 				if (pollHandle !== null) {
@@ -516,7 +595,7 @@ var ChiiCdpConnection = class {
 				}
 				this.emitter.off("target:attached", onAttach);
 				reject(/* @__PURE__ */ new Error(`waitForFirstTarget: 타임아웃 (${timeoutMs}ms) — 폰이 relay에 attach되지 않았습니다.`));
-			}, timeoutMs);
+			}, timeoutMs) : null;
 			this.emitter.on("target:attached", onAttach);
 			pollHandle = setInterval(() => {
 				this.refreshTargets().then((targets) => {
@@ -1292,6 +1371,13 @@ async function injectAndRunBundle(connection, bundleCode, timeoutMs = DEFAULT_TI
 //#endregion
 //#region src/test-runner/relay-worker.ts
 /**
+* Per-file evaluate timeout (ms) for manual-variant files (devtools#741) — a
+* human is expected to be tapping through a native sheet, so the timeout must
+* be far longer than the unattended default (60s, rpc.ts DEFAULT_TIMEOUT_MS).
+* Fixed constant (not configurable in v1) — documented here + CLI `--help`.
+*/
+const MANUAL_FILE_TIMEOUT_MS = 5 * 6e4;
+/**
 * Sentinel string embedded in the error message by `injectAndRunBundle` when
 * the per-file evaluate race hits the timeout. Used by the retry guard so only
 * genuine timeouts get a second attempt — not bundle errors or parse failures.
@@ -1362,12 +1448,21 @@ async function runTestFilesOverRelay(connection, files, opts) {
 			process.stderr.write(`relay-worker: reconnect failed (${e instanceof Error ? e.message : String(e)}) — continuing, remaining files may fail\n`);
 		}
 	};
+	const manualFiles = opts?.manualFiles;
+	const manualTotal = manualFiles?.size ?? 0;
+	let manualIndex = 0;
 	try {
 		for (const file of files) {
 			if (pendingReconnectCheck) {
 				await attemptReconnect("next-file");
 				pendingReconnectCheck = false;
 			}
+			const isManual = manualFiles?.has(file) === true;
+			if (isManual) {
+				manualIndex += 1;
+				opts?.onManualFile?.(file, manualIndex, manualTotal);
+			}
+			const fileTimeoutMs = isManual ? MANUAL_FILE_TIMEOUT_MS : opts?.timeoutMs;
 			let fileEntry;
 			try {
 				const { code } = await bundleTestFile(file, opts?.bundleOptions);
@@ -1393,7 +1488,7 @@ async function runTestFilesOverRelay(connection, files, opts) {
 				const attempt = async () => {
 					let rpcResult;
 					try {
-						rpcResult = await injectAndRunBundle(connection, code, opts?.timeoutMs);
+						rpcResult = await injectAndRunBundle(connection, code, fileTimeoutMs);
 					} catch (e) {
 						return {
 							file,
@@ -1429,6 +1524,7 @@ async function runTestFilesOverRelay(connection, files, opts) {
 				};
 			}
 			if ("error" in fileEntry.result && isRelayDisconnectMessage(fileEntry.result.error)) pendingReconnectCheck = true;
+			if (isManual) fileEntry.mode = "manual";
 			fileResults.push(fileEntry);
 		}
 	} finally {
@@ -1542,9 +1638,11 @@ function serializeRelayReport(report, meta) {
 		totals: report.totals,
 		files: report.files.map((f) => {
 			const file = relativise(meta.projectRoot, f.file);
+			const modeField = f.mode === "manual" ? { mode: "manual" } : {};
 			if ("error" in f.result) return {
 				file,
-				error: f.result.error
+				error: f.result.error,
+				...modeField
 			};
 			return {
 				file,
@@ -1552,33 +1650,65 @@ function serializeRelayReport(report, meta) {
 				passed: f.result.passed,
 				failed: f.result.failed,
 				skipped: f.result.skipped,
-				tests: f.result.tests
+				tests: f.result.tests,
+				...modeField
 			};
 		})
 	};
 }
 /**
 * Writes the serialised report to `<dir>/<sdkLine>.<platform>.json`, creating
-* `dir` if needed. Returns the absolute path written.
+* `dir` if needed. Returns the absolute path(s) written.
 *
 * The cell-suffixed filename keeps 2.x and 3.0 (and per-platform) runs as
 * distinct artifacts in the same directory; the same cell metadata is also baked
 * into the body so a renamed/moved file still carries its provenance.
 *
+* Manual-run provenance (devtools#741): when `report.files` contains ANY
+* `mode: 'manual'` entry (i.e. this run included `--manual-blocking` files),
+* the manual-tagged files are written to a SEPARATE
+* `<dir>/<sdkLine>.<platform>.manual.json` artifact instead of the standard
+* one — the standard `<sdkLine>.<platform>.json` filename is reserved for the
+* regular (unattended) files only, so a manual run's presence never mutates
+* what the unattended-baseline filename means. If ALL files in the run are
+* regular, only the standard artifact is written (today's behavior,
+* unchanged). If a run mixes both (regular files + `--manual-blocking`
+* scheduled last), BOTH artifacts are written — the manual one ALONGSIDE, not
+* replacing, the standard one.
+*
 * SECRET-HANDLING: the written body contains no relay/secret fields (the schema
 * has none). `dir`/`projectRoot` are local filesystem paths, never logged here.
 *
 * @param report - The core relay run report.
 * @param dir    - Output directory (created recursively if missing).
 * @param meta   - Cell axes + projectRoot.
-* @returns The absolute path of the written file.
+* @returns The absolute path(s) written, in order: standard first (if any
+*   regular files ran), then manual (if any manual files ran). At least one
+*   path is always returned when `report.files` is non-empty.
 */
 async function writeReportArtifact(report, dir, meta) {
 	const serialised = serializeRelayReport(report, meta);
 	await mkdir(dir, { recursive: true });
-	const outFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.json`);
-	await writeFile(outFile, `${JSON.stringify(serialised, null, 2)}\n`, "utf8");
-	return outFile;
+	const regularFiles = serialised.files.filter((f) => f.mode !== "manual");
+	const manualFiles = serialised.files.filter((f) => f.mode === "manual");
+	const written = [];
+	if (regularFiles.length > 0 || serialised.files.length === 0) {
+		const outFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.json`);
+		await writeFile(outFile, `${JSON.stringify({
+			...serialised,
+			files: regularFiles
+		}, null, 2)}\n`, "utf8");
+		written.push(outFile);
+	}
+	if (manualFiles.length > 0) {
+		const manualOutFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.manual.json`);
+		await writeFile(manualOutFile, `${JSON.stringify({
+			...serialised,
+			files: manualFiles
+		}, null, 2)}\n`, "utf8");
+		written.push(manualOutFile);
+	}
+	return written;
 }
 /**
 * Writes harvested `__AIT_CAPTURE__` lines to per-category files under `dir`,
@@ -1649,9 +1779,9 @@ OPTIONS
                           the CLI waits for a human to scan the QR code — use
                           --attach-timeout for that.
   --attach-timeout <ms>   How long to wait for a human to scan the QR code with
-                          their phone (default: 600000 — 10 minutes). Omit to
-                          use the relay factory's generous default. Decrease for
-                          CI environments where a scan should arrive quickly.
+                          their phone. Omit (default) to wait indefinitely — the
+                          runner stays up until you stop it (Ctrl-C/SIGTERM).
+                          Pass a value to bound the wait for CI/headless runs.
   --cell-sdk-line <line>  SDK line to inject as __AIT_CELL__.sdkLine (2.x|3.x)
   --cell-platform <plat>  Platform to inject as __AIT_CELL__.platform
                           (mock|ios|android, default: AIT_CELL_PLATFORM env)
@@ -1664,6 +1794,24 @@ OPTIONS
   --headless              Disable browser auto-open (text QR only)
   --project-root <dir>    Project root for .ait_relay secret lookup
                           (default: current working directory)
+  --manual-blocking       Run manual-tagged test files (*.manual.ait.test.ts)
+                          LAST, after all regular files, with a human present.
+                          Before each manual file, the QR dashboard is pushed
+                          a step-by-step Korean prompt naming the file + its
+                          progress (k/n), and the same line is printed to
+                          stdout. Manual files get a 5-minute per-file evaluate
+                          timeout (vs. --timeout for everything else) since a
+                          human is expected to tap through a native sheet
+                          (photo picker, permission dialog, fullscreen ad).
+                          Without this flag (default off), *.manual.ait.test.ts
+                          files are EXCLUDED from the glob expansion entirely —
+                          existing unattended runs are byte-for-byte unaffected.
+                          With --report-dir, a run that included manual files
+                          ALSO writes <sdkLine>.<platform>.manual.json
+                          alongside (never replacing) the standard report, and
+                          each manual file's report entry is stamped
+                          mode: 'manual' — never diff a manual run against an
+                          unattended baseline as if they were equivalent.
   --help, -h              Show this help message
 
 DESCRIPTION
@@ -1812,7 +1960,8 @@ async function main(argv = process.argv.slice(2)) {
 				"report-dir": { type: "string" },
 				"no-qr-stdout": { type: "boolean" },
 				headless: { type: "boolean" },
-				"project-root": { type: "string" }
+				"project-root": { type: "string" },
+				"manual-blocking": { type: "boolean" }
 			},
 			allowPositionals: true
 		});
@@ -1843,6 +1992,7 @@ async function main(argv = process.argv.slice(2)) {
 	const projectRoot = typeof vals["project-root"] === "string" ? vals["project-root"] : process.cwd();
 	const reportDir = typeof vals["report-dir"] === "string" ? vals["report-dir"] : void 0;
 	const suppressQr = shouldSuppressQr(vals["no-qr-stdout"] === true);
+	const manualBlocking = vals["manual-blocking"] === true;
 	const cellSdkLine = typeof vals["cell-sdk-line"] === "string" ? vals["cell-sdk-line"] : void 0;
 	const cellPlatform = typeof vals["cell-platform"] === "string" ? vals["cell-platform"] : process.env.AIT_CELL_PLATFORM;
 	const hasCell = cellSdkLine !== void 0 || cellPlatform !== void 0;
@@ -1857,13 +2007,16 @@ async function main(argv = process.argv.slice(2)) {
 		process.exitCode = 1;
 		return;
 	}
-	const files = await discoverTestFiles(globs, process.cwd());
-	if (files.length === 0) {
+	const discovered = await discoverTestFiles(globs, process.cwd(), { includeManual: manualBlocking });
+	if (discovered.length === 0) {
 		process.stderr.write(`devtools-test: no test files matched ${globs.join(", ")}\n`);
 		process.exitCode = 1;
 		return;
 	}
-	process.stderr.write(`devtools-test: found ${files.length} test file(s)\n`);
+	const { regular, manual } = partitionManualTests(discovered);
+	const files = manualBlocking ? [...regular, ...manual] : regular;
+	const manualFileSet = new Set(manual);
+	process.stderr.write(manualBlocking && manual.length > 0 ? `devtools-test: found ${regular.length} regular + ${manual.length} manual (${MANUAL_TEST_SUFFIX}) test file(s)\n` : `devtools-test: found ${files.length} test file(s)\n`);
 	if (hasCell) process.stderr.write(`devtools-test: injecting __AIT_CELL__ = ${JSON.stringify(cell)}\n`);
 	const factory = createRelayConnectionFactory({
 		schemeUrl,
@@ -1889,18 +2042,30 @@ async function main(argv = process.argv.slice(2)) {
 	}
 	let exitCode = 0;
 	try {
+		factory.onSessionPhase?.("running");
 		const report = await runWithConnection(connection, files, {
 			timeoutMs: evaluateTimeoutMs,
 			printSummary: true,
-			collectCaptures: reportDir !== void 0
+			collectCaptures: reportDir !== void 0,
+			manualFiles: manualBlocking && manualFileSet.size > 0 ? manualFileSet : void 0,
+			onManualFile: (file, index, total) => {
+				const name = basename(file);
+				process.stdout.write(`수동 단계: ${name} — 폰에서 네이티브 시트가 뜨면 안내에 따라 조작하세요 (${index}/${total})\n`);
+				factory.onManualPrompt?.({
+					file: name,
+					index,
+					total
+				});
+			}
 		});
+		if (manualBlocking && manualFileSet.size > 0) factory.onManualPrompt?.(null);
 		if (reportDir !== void 0) try {
-			const reportPath = await writeReportArtifact(report, reportDir, {
+			const reportPaths = await writeReportArtifact(report, reportDir, {
 				sdkLine: cell.sdkLine,
 				platform: cell.platform,
 				projectRoot
 			});
-			process.stderr.write(`devtools-test: wrote report ${reportPath}\n`);
+			for (const reportPath of reportPaths) process.stderr.write(`devtools-test: wrote report ${reportPath}\n`);
 			const capturePaths = await writeCaptureArtifacts(report.captures, `${reportDir}/.ait-capture`, cell);
 			if (capturePaths.length > 0) process.stderr.write(`devtools-test: wrote ${capturePaths.length} capture file(s)\n`);
 		} catch (e) {
@@ -1908,6 +2073,7 @@ async function main(argv = process.argv.slice(2)) {
 		}
 		exitCode = report.totals.failed > 0 ? 1 : 0;
 	} finally {
+		factory.onSessionPhase?.("complete");
 		await factory.close(connection);
 		process.exitCode = exitCode;
 	}