@ait-co/devtools 0.1.135 → 0.1.137

package/dist/test-runner/bin.js

@@ -122,7 +122,7 @@ function createRelayConnectionFactory(opts) {
 			const { prepareAttach, renderAndMaybeWait, mintAttachUrl } = await import("../attach-orchestrator-CE0S09YU.js").then((n) => n.i);
 			const { injectDebugIndicator, injectGlobals } = await import("../cell-BIdSQb9T.js").then((n) => n.t);
 			const { loadRelaySecretReadOnly } = await import("../relay-secret-store-CLEGyHou.js");
-			const { bootRelayFamily, buildRelayVerifyAuth } = await import("../debug-server-CBqMfcUi.js");
+			const { bootRelayFamily, buildRelayVerifyAuth } = await import("../debug-server-D2wpPK3_.js");
 			await loadRelaySecretReadOnly({ projectRoot });
 			let resolveTunnelUp;
 			const tunnelReady = new Promise((resolve) => {
@@ -152,7 +152,7 @@ function createRelayConnectionFactory(opts) {
 				canOpenBrowser: () => !headless
 			};
 			try {
-				const { startQrHttpServer } = await import("../qr-http-server-yQ1EWTwf.js");
+				const { startQrHttpServer } = await import("../qr-http-server-C7q8Gn04.js");
 				const getDashboardState = () => ({
 					tunnel: attachDeps.getTunnelStatus(),
 					pages: null,
@@ -210,6 +210,7 @@ function createRelayConnectionFactory(opts) {
 			}
 			await injectDebugIndicator(booted.connection);
 			if (opts.cell !== void 0) await injectGlobals(booted.connection, { __AIT_CELL__: opts.cell });
+			if (opts.stubBlocking === true) await injectGlobals(booted.connection, { __AIT_STUB_BLOCKING__: true });
 			return booted.connection;
 		},
 		onSessionPhase(next) {
@@ -906,6 +907,16 @@ const SDK_IMPORT_FILTER = new RegExp(`^${SDK_PACKAGE.replace(/[.*+?^${}()|[\]\\]
 *
 * If `window.__sdk` is absent (non-dog-food build), every access throws a
 * descriptive error rather than returning `undefined` silently.
+*
+* Bridge-stub interception (devtools#740, DT-2): the virtual module runs the
+* resolved `window.__sdk` object through `wrapSdkWithStub` before exporting
+* it. `wrapSdkWithStub` is a pass-through (returns the same object,
+* unwrapped) unless `isStubBlockingEnabled()` reads `true` off
+* `globalThis.__AIT_STUB_BLOCKING__` — an opt-in flag injected the same way
+* `__AIT_CELL__` is (`cell.ts#injectGlobals`, wired from the CLI's
+* `--stub-blocking` flag). Default off => zero behavior change: every existing
+* (non-stub) test run resolves the exact same `window.__sdk` reference it did
+* before this plugin learned about stubbing.
 */
 function sdkRedirectPlugin() {
 	return {
@@ -920,16 +931,19 @@ function sdkRedirectPlugin() {
 				namespace: "sdk-redirect"
 			}, () => ({
 				contents: `
-var __proxy = (typeof window !== 'undefined' && window.__sdk)
+import { wrapSdkWithStub, isStubBlockingEnabled } from ${JSON.stringify(getBridgeStubPath())};
+var __rawSdk = (typeof window !== 'undefined' && window.__sdk)
   ? window.__sdk
   : new Proxy({}, {
       get: function(_t, p) {
         throw new Error('window.__sdk is not installed — run in a dog-food build. Missing: ' + String(p));
       }
     });
+var __proxy = wrapSdkWithStub(__rawSdk, isStubBlockingEnabled());
 module.exports = __proxy;
 `,
-				loader: "js"
+				loader: "js",
+				resolveDir: process.cwd()
 			}));
 		}
 	};
@@ -1063,8 +1077,9 @@ function userFactoryPlugin(absPath) {
 	};
 }
 /**
-* Returns the absolute filesystem path to the test-runner runtime module
-* (dist/test-runner/runtime.js — a fully self-contained page-side bundle).
+* Returns the absolute filesystem path to a page-side leaf module shipped
+* alongside `bundle.ts` in dist (e.g. `runtime.js`, `bridge-stub.js`) — a
+* fully self-contained module with no further page-side deps of its own.
 *
 * Rolldown code-splitting duplicates this bundling logic into shared chunks
 * emitted at ARBITRARY dist depths: the `devtools-test` CLI pulls it from
@@ -1074,26 +1089,30 @@ function userFactoryPlugin(absPath) {
 * is therefore wrong from at least one chunk — the live #697 regression.
 *
 * This resolves WITHOUT assuming chunk depth: from `import.meta.url`'s dir it
-* probes the co-located `runtime.js` and the nested `test-runner/runtime.js`,
+* probes the co-located `<name>.js` and the nested `test-runner/<name>.js`,
 * then ascends one directory at a time (bounded) repeating both probes. The
-* nested probe catches dist/test-runner/runtime.js from the dist/ root level no
+* nested probe catches dist/test-runner/<name>.js from the dist/ root level no
 * matter which depth the chunk was hoisted to (root, dist/mcp/, or a future
-* relocation). The build always emits dist/test-runner/runtime.js (tsdown entry
-* `'test-runner/runtime'`; guarded by scripts/check-test-runner-dist.sh).
+* relocation). The build always emits dist/test-runner/<name>.js (tsdown entry
+* `'test-runner/<name>'`; guarded by scripts/check-test-runner-dist.sh for
+* `runtime`).
 *
 * An ABSOLUTE path is returned deliberately: esbuild loads it as a literal file
 * read, bypassing Node module resolution entirely, so this works identically in
 * the npx-daemon context (its own dist tree) and the consumer-CLI context
 * (the mini-app's installed @ait-co/devtools dist) — neither needs the package
 * to be node-resolvable from the caller.
+*
+* @param moduleName - The leaf module's basename without extension, e.g.
+*   `'runtime'` or `'bridge-stub'`.
 */
-function getRuntimePath() {
+function getPageSideModulePath(moduleName) {
 	const startDir = path$1.dirname(fileURLToPath(import.meta.url));
 	const RELATIVE_PROBES = [
-		["runtime.js"],
-		["test-runner", "runtime.js"],
-		["runtime.ts"],
-		["test-runner", "runtime.ts"]
+		[`${moduleName}.js`],
+		["test-runner", `${moduleName}.js`],
+		[`${moduleName}.ts`],
+		["test-runner", `${moduleName}.ts`]
 	];
 	let dir = startDir;
 	for (let i = 0; i < 12; i++) {
@@ -1108,7 +1127,19 @@ function getRuntimePath() {
 		if (parent === dir) break;
 		dir = parent;
 	}
-	return path$1.join(startDir, "runtime.js");
+	return path$1.join(startDir, `${moduleName}.js`);
+}
+/** Absolute path to the test-runner page-side runtime (describe/it/test/expect). */
+function getRuntimePath() {
+	return getPageSideModulePath("runtime");
+}
+/**
+* Absolute path to the bridge-stub interceptor (devtools#740, DT-2) —
+* `wrapSdkWithStub`/`isStubBlockingEnabled`, statically imported by the
+* `sdk-redirect` virtual module.
+*/
+function getBridgeStubPath() {
+	return getPageSideModulePath("bridge-stub");
 }
 /**
 * Bundles `absPath` into a single IIFE string suitable for `Runtime.evaluate`.
@@ -1382,6 +1413,7 @@ async function runTestFilesOverRelay(connection, files, opts) {
 	const manualFiles = opts?.manualFiles;
 	const manualTotal = manualFiles?.size ?? 0;
 	let manualIndex = 0;
+	const stubBlockingFiles = opts?.stubBlockingFiles;
 	let preflightPermissions;
 	if (files.length > 0) preflightPermissions = await runPermissionPreflight(connection);
 	try {
@@ -1390,7 +1422,8 @@ async function runTestFilesOverRelay(connection, files, opts) {
 				await attemptReconnect("next-file");
 				pendingReconnectCheck = false;
 			}
-			const isManual = manualFiles?.has(file) === true;
+			const isStubbed = stubBlockingFiles?.has(file) === true;
+			const isManual = !isStubbed && manualFiles?.has(file) === true;
 			if (isManual) {
 				manualIndex += 1;
 				opts?.onManualFile?.(file, manualIndex, manualTotal);
@@ -1457,7 +1490,8 @@ async function runTestFilesOverRelay(connection, files, opts) {
 				};
 			}
 			if ("error" in fileEntry.result && isRelayDisconnectMessage(fileEntry.result.error)) pendingReconnectCheck = true;
-			if (isManual) fileEntry.mode = "manual";
+			if (isStubbed) fileEntry.mode = "stubbed";
+			else if (isManual) fileEntry.mode = "manual";
 			fileResults.push(fileEntry);
 		}
 	} finally {
@@ -1573,7 +1607,7 @@ function serializeRelayReport(report, meta) {
 		...report.preflight ? { preflight: report.preflight } : {},
 		files: report.files.map((f) => {
 			const file = relativise(meta.projectRoot, f.file);
-			const modeField = f.mode === "manual" ? { mode: "manual" } : {};
+			const modeField = f.mode === "manual" || f.mode === "stubbed" ? { mode: f.mode } : {};
 			if ("error" in f.result) return {
 				file,
 				error: f.result.error,
@@ -1605,11 +1639,21 @@ function serializeRelayReport(report, meta) {
 * `<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.
+* what the unattended-baseline filename means.
+*
+* Stub-blocking provenance (devtools#740, DT-2): `mode: 'stubbed'` files are
+* written to a THIRD, separate `<dir>/<sdkLine>.<platform>.stubbed.json`
+* artifact — never merged into the standard file (it is unattended, like the
+* standard file, so a naive filename split could conflate the two) and never
+* merged into `.manual.json` (it did NOT have a human present). Its body is
+* ALSO stamped `cell.bridgeStub: true` — the mandatory HYBRID-cell provenance
+* from the issue: a stubbed result must never be silently mixed into the
+* real-device baseline report.
+*
+* If ALL files in the run are regular, only the standard artifact is written
+* (today's behavior, unchanged). Any combination of the three modes present
+* in a single run writes ONLY the corresponding artifacts — each is additive,
+* never replacing another.
 *
 * SECRET-HANDLING: the written body contains no relay/secret fields (the schema
 * has none). `dir`/`projectRoot` are local filesystem paths, never logged here.
@@ -1618,14 +1662,16 @@ function serializeRelayReport(report, meta) {
 * @param dir    - Output directory (created recursively if missing).
 * @param meta   - Cell axes + projectRoot.
 * @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.
+*   regular files ran), then manual (if any manual files ran), then stubbed
+*   (if any stubbed 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 regularFiles = serialised.files.filter((f) => f.mode !== "manual");
+	const regularFiles = serialised.files.filter((f) => f.mode === void 0);
 	const manualFiles = serialised.files.filter((f) => f.mode === "manual");
+	const stubbedFiles = serialised.files.filter((f) => f.mode === "stubbed");
 	const written = [];
 	if (regularFiles.length > 0 || serialised.files.length === 0) {
 		const outFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.json`);
@@ -1643,6 +1689,18 @@ async function writeReportArtifact(report, dir, meta) {
 		}, null, 2)}\n`, "utf8");
 		written.push(manualOutFile);
 	}
+	if (stubbedFiles.length > 0) {
+		const stubbedOutFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.stubbed.json`);
+		await writeFile(stubbedOutFile, `${JSON.stringify({
+			...serialised,
+			cell: {
+				...serialised.cell,
+				bridgeStub: true
+			},
+			files: stubbedFiles
+		}, null, 2)}\n`, "utf8");
+		written.push(stubbedOutFile);
+	}
 	return written;
 }
 /**
@@ -1686,6 +1744,76 @@ async function writeCaptureArtifacts(captures, dir, cell) {
 	return written;
 }
 //#endregion
+//#region src/test-runner/teardown.ts
+/**
+* Runs `steps` in strict order, each bounded by `perStepTimeoutMs` so a
+* single hung `close()` cannot block the rest — a later step (e.g. "close
+* the QR HTTP server") still runs even if an earlier one (e.g. "flip the
+* on-phone badge over CDP") times out.
+*
+* Order is load-bearing: `relay-factory.ts`'s existing `close()` already
+* encodes "badge over still-open channel, THEN close that channel" — this
+* function does not reorder or parallelize, it just bounds+reports whatever
+* sequence the caller provides.
+*/
+async function runTeardownSteps(steps, options = {}) {
+	const { perStepTimeoutMs = 5e3, setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout } = options;
+	const results = [];
+	for (const step of steps) results.push(await runOneStep(step, perStepTimeoutMs, setTimeoutFn, clearTimeoutFn));
+	return results;
+}
+async function runOneStep(step, perStepTimeoutMs, setTimeoutFn, clearTimeoutFn) {
+	let timeoutHandle;
+	const timeoutPromise = new Promise((resolve) => {
+		timeoutHandle = setTimeoutFn(() => resolve("timeout"), perStepTimeoutMs);
+	});
+	try {
+		const outcome = await Promise.race([Promise.resolve().then(() => step.close()).then(() => "ok"), timeoutPromise]);
+		if (timeoutHandle !== void 0) clearTimeoutFn(timeoutHandle);
+		return {
+			name: step.name,
+			status: outcome
+		};
+	} catch (e) {
+		if (timeoutHandle !== void 0) clearTimeoutFn(timeoutHandle);
+		return {
+			name: step.name,
+			status: "error",
+			error: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+/**
+* Arms a grace-period timer that force-exits the process if it has not
+* already exited on its own by the time the timer fires. The timer is
+* deliberately NOT `.unref()`'d — its entire purpose is to hold the event
+* loop open long enough to fire if nothing else does, so unref'ing it would
+* defeat the backstop. `disarm()` clears it — the CLI calls `disarm()`
+* immediately once `main()`'s own teardown (Step 6, cli.ts) has finished,
+* so on the happy path the timer never fires (Node drains the loop and
+* exits naturally at whatever `process.exitCode` was already set to).
+*
+* SECRET-HANDLING: this function never touches stdout/stderr content — the
+* caller (cli.ts) is responsible for flushing any final output before the
+* backstop's `exitFn` runs.
+*/
+function armExitBackstop(options) {
+	const { graceMs = 3e3, exitCode, setTimeoutFn = setTimeout, exitFn = (code) => process.exit(code) } = options;
+	let fired = false;
+	const handle = setTimeoutFn(() => {
+		fired = true;
+		exitFn(exitCode);
+	}, graceMs);
+	return {
+		disarm() {
+			clearTimeout(handle);
+		},
+		get fired() {
+			return fired;
+		}
+	};
+}
+//#endregion
 //#region src/test-runner/cli.ts
 /**
 * `devtools-test` CLI.
@@ -1752,6 +1880,24 @@ OPTIONS
                           each manual file's report entry is stamped
                           mode: 'manual' — never diff a manual run against an
                           unattended baseline as if they were equivalent.
+  --stub-blocking         Run manual-tagged test files (*.manual.ait.test.ts)
+                          UNATTENDED (devtools#740, DT-2) by intercepting a
+                          fixed allowlist of blocking-UI SDK calls (ads
+                          show*, openPermissionDialog/requestPermission,
+                          saveBase64Data) in the page and answering them from
+                          fixtures captured by a real --manual-blocking run,
+                          instead of forwarding them to native UI. Implies
+                          --manual-blocking (manual files are included in the
+                          run); no human presence or QR-dashboard prompt is
+                          needed for them. HYBRID cell, not pure env3 — every
+                          other SDK call in the same run still hits the real
+                          native bridge. With --report-dir, files that ran
+                          under the stub are written to a SEPARATE
+                          <sdkLine>.<platform>.stubbed.json artifact (never
+                          merged into the standard or .manual.json report) and
+                          the report body is stamped cell.bridgeStub: true —
+                          never diff a stubbed run against a real device
+                          baseline (manual or unattended) as if equivalent.
   --help, -h              Show this help message
 
 DESCRIPTION
@@ -1778,6 +1924,15 @@ EXAMPLE
 
 `.trimStart();
 /**
+* Grace period (ms) for the exit backstop armed around Step 6 teardown
+* (devtools#755). See `teardown.ts`'s module doc for the root-cause writeup
+* — the two upstream `http.Server#close()` hangs are fixed at the source, so
+* this backstop is a last-mile safety net that should never fire in
+* practice. Exported so tests can assert the backstop is armed with the
+* expected value without hardcoding the literal twice.
+*/
+const EXIT_BACKSTOP_GRACE_MS = 3e3;
+/**
 * Parses --timeout and --attach-timeout raw string values into the two
 * distinct clocks.
 *
@@ -1921,7 +2076,8 @@ async function main(argv = process.argv.slice(2)) {
 				"no-qr-stdout": { type: "boolean" },
 				headless: { type: "boolean" },
 				"project-root": { type: "string" },
-				"manual-blocking": { type: "boolean" }
+				"manual-blocking": { type: "boolean" },
+				"stub-blocking": { type: "boolean" }
 			},
 			allowPositionals: true
 		});
@@ -1958,7 +2114,8 @@ async function main(argv = process.argv.slice(2)) {
 		return;
 	}
 	const suppressQr = shouldSuppressQr(vals["no-qr-stdout"] === true);
-	const manualBlocking = vals["manual-blocking"] === true;
+	const stubBlocking = vals["stub-blocking"] === true;
+	const manualBlocking = vals["manual-blocking"] === true || stubBlocking;
 	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;
@@ -1984,6 +2141,7 @@ async function main(argv = process.argv.slice(2)) {
 	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`);
+	if (stubBlocking) process.stderr.write("devtools-test: --stub-blocking enabled — blocking-UI calls in manual-tagged files will be answered from fixtures (devtools#740), not forwarded to native UI\n");
 	const factory = createRelayConnectionFactory({
 		schemeUrl,
 		projectRoot,
@@ -1991,6 +2149,7 @@ async function main(argv = process.argv.slice(2)) {
 		...dashboardPort !== void 0 ? { dashboardPort } : {},
 		headless,
 		cell: hasCell ? cell : void 0,
+		stubBlocking,
 		onQrContent: (chunks) => {
 			if (suppressQr) {
 				process.stdout.write("QR suppressed (non-interactive)\n");
@@ -2015,6 +2174,7 @@ async function main(argv = process.argv.slice(2)) {
 			printSummary: true,
 			collectCaptures: reportDir !== void 0,
 			manualFiles: manualBlocking && manualFileSet.size > 0 ? manualFileSet : void 0,
+			stubBlockingFiles: stubBlocking && manualFileSet.size > 0 ? manualFileSet : void 0,
 			onManualFile: (file, index, total) => {
 				const name = basename(file);
 				process.stdout.write(`수동 단계: ${name} — 폰에서 네이티브 시트가 뜨면 안내에 따라 조작하세요 (${index}/${total})\n`);
@@ -2041,7 +2201,15 @@ async function main(argv = process.argv.slice(2)) {
 		exitCode = report.totals.failed > 0 ? 1 : 0;
 	} finally {
 		factory.onSessionPhase?.("complete");
-		await factory.close(connection);
+		const backstop = armExitBackstop({
+			graceMs: EXIT_BACKSTOP_GRACE_MS,
+			exitCode
+		});
+		await runTeardownSteps([{
+			name: "factory.close",
+			close: () => factory.close(connection)
+		}]);
+		backstop.disarm();
 		process.exitCode = exitCode;
 	}
 }