@ait-co/devtools 0.1.131 → 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
@@ -65,12 +114,13 @@ function createRelayConnectionFactory(opts) {
 	let family;
 	let qrServer;
 	let phase = "active";
+	let manualPrompt = null;
 	return {
 		async open() {
 			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-CD4zYBq4.js");
+			const { bootRelayFamily, buildRelayVerifyAuth } = await import("../debug-server-BBUzxZSf.js");
 			await loadRelaySecretReadOnly({ projectRoot });
 			let resolveTunnelUp;
 			const tunnelReady = new Promise((resolve) => {
@@ -100,13 +150,14 @@ function createRelayConnectionFactory(opts) {
 				canOpenBrowser: () => !headless
 			};
 			try {
-				const { startQrHttpServer } = await import("../qr-http-server-DCbjORFa.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",
-					phase
+					phase,
+					manualPrompt
 				});
 				qrServer = await startQrHttpServer(getDashboardState);
 				attachDeps.qrHttpServer = qrServer;
@@ -163,6 +214,10 @@ function createRelayConnectionFactory(opts) {
 			phase = next;
 			qrServer?.notifyStateChange();
 		},
+		onManualPrompt(next) {
+			manualPrompt = next;
+			qrServer?.notifyStateChange();
+		},
 		async close(connection) {
 			if (phase !== "complete") {
 				phase = "complete";
@@ -1316,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.
@@ -1386,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);
@@ -1417,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,
@@ -1453,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 {
@@ -1566,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,
@@ -1576,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`,
@@ -1688,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
@@ -1836,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
 		});
@@ -1867,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;
@@ -1881,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,
@@ -1917,15 +2046,26 @@ async function main(argv = process.argv.slice(2)) {
 		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) {