@ait-co/devtools 0.1.131 → 0.1.133

package/dist/mcp/cli.js

@@ -2024,7 +2024,7 @@ async function readMcpSdkVersion() {
 * some test environments that skip the build step).
 */
 function readDevtoolsVersion() {
-	return "0.1.131";
+	return "0.1.133";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -2932,6 +2932,110 @@ function buildIndicatorExpression(opts) {
 * Node-only. react-free. CdpConnection only.
 */
 /**
+* `__AIT_PERMS__` key → SDK function name whose `.getPermission()` is probed
+* (devtools#739). This is the exact contract sdk-example#265 consumes — do
+* not rename keys without a coordinated sdk-example update.
+*
+* Each SDK function is reached via `window.__sdk` — the SAME page-global
+* bridge `src/in-app/auto.ts` installs for `call_sdk`/`__sdkCall` (see
+* `src/test-runner/bundle.ts`'s `sdkRedirectPlugin`, which redirects bundled
+* `@apps-in-toss/web-framework` imports to this same object at runtime). The
+* test-runner bundle owns no independent SDK import — `window.__sdk` is a
+* page global regardless of whether a bundle has been injected yet, so this
+* preflight runs standalone via `injectGlobals`'s `Runtime.evaluate`
+* mechanism BEFORE the first bundle, rather than being prepended into
+* `rpc.ts#buildRunTestsExpression`. (Design choice documented in PR #739 —
+* bundle-prepend was the fallback plan if the SDK were only reachable from
+* inside bundle scope, which reality ruled out.)
+*/
+const PERMISSION_PROBE_MAP = {
+	clipboardRead: "getClipboardText",
+	clipboardWrite: "setClipboardText",
+	album: "fetchAlbumPhotos",
+	camera: "openCamera",
+	contacts: "fetchContacts",
+	location: "getCurrentLocation"
+};
+/** Non-fatal bound for the permission preflight `Runtime.evaluate` round-trip. */
+const PERMISSION_PREFLIGHT_TIMEOUT_MS = 1e4;
+/**
+* Builds the `Runtime.evaluate` expression for the permission-state preflight
+* (devtools#739). Evaluated ONCE per relay session, before the first test
+* bundle is injected (see `relay-worker.ts#runTestFilesOverRelay`).
+*
+* For each entry in {@link PERMISSION_PROBE_MAP}, probes
+* `window.__sdk.<fn>.getPermission()` — a NON-blocking query (never
+* `openPermissionDialog`/`requestPermission`, which open native UI) — and
+* assigns the resolved `'allowed'|'denied'|'notDetermined'` status to
+* `globalThis.__AIT_PERMS__[<key>]`. A probe that is absent, throws, or
+* rejects resolves to `'unavailable'` — this expression never throws to its
+* caller, and a single slow/broken permission must not fail the others (each
+* probe is awaited independently, not short-circuited).
+*
+* Tests (sdk-example#265) read `globalThis.__AIT_PERMS__` to branch
+* deterministically per permission state instead of blanket outcome-branching.
+*
+* Returns a JSON-serialised string (the same double-serialisation pattern
+* `rpc.ts#buildRunTestsExpression` uses) rather than relying on CDP
+* `returnByValue` structural fidelity for a plain object across the Chii
+* relay — the Node side re-parses via `JSON.parse`.
+*
+* Pure function — no I/O, no CDP call. Callers pass the returned string to
+* `Runtime.evaluate`.
+*/
+function buildPermissionPreflightExpression() {
+	return `(async () => {  const probe = async (fnName) => {    try {      const fn = globalThis.__sdk && globalThis.__sdk[fnName];      if (!fn || typeof fn.getPermission !== 'function') return 'unavailable';      const status = await fn.getPermission();      if (status === 'allowed' || status === 'denied' || status === 'notDetermined') return status;      return 'unavailable';    } catch (e) {      return 'unavailable';    }  };  const result = {};${Object.entries(PERMISSION_PROBE_MAP).map(([key, fnName]) => `    result[${JSON.stringify(key)}] = await probe(${JSON.stringify(fnName)});`).join("\n")}\n  globalThis.__AIT_PERMS__ = result;  return JSON.stringify(result);})()`;
+}
+/**
+* Runs the permission-state preflight (devtools#739) via `Runtime.evaluate`
+* and returns the collected `__AIT_PERMS__` map, or `undefined` when the
+* preflight itself failed or timed out.
+*
+* NON-FATAL by design: any failure (CDP exception, timeout, page-side throw)
+* is caught here, logged as ONE stderr line, and swallowed — the whole test
+* run must proceed even when the preflight cannot complete (e.g. `window.__sdk`
+* not yet installed, or a page navigation mid-attach). Callers that want the
+* result for report provenance (`RelayRunReport.preflight`) get `undefined`
+* in that case, which downstream code treats the same as "not run".
+*
+* SECRET-HANDLING: no relay/wss/secret values are read or logged; only
+* permission-state strings cross this boundary.
+*
+* @param conn      - The live CDP connection (relay-attached page).
+* @param timeoutMs - Round-trip bound. Defaults to {@link PERMISSION_PREFLIGHT_TIMEOUT_MS}.
+*/
+async function runPermissionPreflight(conn, timeoutMs = PERMISSION_PREFLIGHT_TIMEOUT_MS) {
+	const TIMEOUT_SENTINEL = Symbol("permission-preflight-timeout");
+	const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs));
+	try {
+		const evalPromise = conn.send("Runtime.evaluate", {
+			expression: buildPermissionPreflightExpression(),
+			returnByValue: true,
+			awaitPromise: true
+		});
+		const raceResult = await Promise.race([evalPromise.then((v) => ({
+			tag: "eval",
+			v
+		})), timeoutPromise.then(() => ({ tag: "timeout" }))]);
+		if (raceResult.tag === "timeout") {
+			process.stderr.write(`test-runner: permission preflight timed out after ${timeoutMs}ms — proceeding with __AIT_PERMS__ unset\n`);
+			return;
+		}
+		if (raceResult.v.exceptionDetails) {
+			process.stderr.write("test-runner: permission preflight threw — proceeding with __AIT_PERMS__ unset\n");
+			return;
+		}
+		const rawValue = raceResult.v.result.value;
+		if (typeof rawValue !== "string") return void 0;
+		const parsed = JSON.parse(rawValue);
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		return parsed;
+	} catch (e) {
+		process.stderr.write(`test-runner: permission preflight failed (${e instanceof Error ? e.message : String(e)}) — proceeding with __AIT_PERMS__ unset\n`);
+		return;
+	}
+}
+/**
 * Injects each key of `globals` into `globalThis` in the page via a single
 * `Runtime.evaluate` call. Must be called BEFORE the first `bundleTestFile`
 * inject — the cell is session-global and applies to all subsequent files.
@@ -3007,6 +3111,23 @@ async function injectDebugIndicator(conn, opts) {
 * 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`.
 *
@@ -3015,14 +3136,26 @@ async function injectDebugIndicator(conn, opts) {
 * 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));
 }
 //#endregion
 //#region src/shared/relay-auth-close.ts
@@ -4069,6 +4202,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.
@@ -4139,12 +4279,23 @@ 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;
+	let preflightPermissions;
+	if (files.length > 0) preflightPermissions = await runPermissionPreflight(connection);
 	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);
@@ -4170,7 +4321,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,
@@ -4206,6 +4357,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 {
@@ -4234,7 +4386,8 @@ async function runTestFilesOverRelay(connection, files, opts) {
 		duration: Date.now() - wallStart,
 		files: fileResults,
 		totals,
-		captures
+		captures,
+		...preflightPermissions ? { preflight: { permissions: preflightPermissions } } : {}
 	};
 }
 /**
@@ -4293,6 +4446,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
@@ -6638,7 +6809,8 @@ async function startQrHttpServer(getDashboardState, options) {
 			pages: state.pages,
 			attachUrl: state.attachUrl,
 			inspectorUrl: state.inspectorUrl ?? null,
-			phase: state.phase ?? "active"
+			phase: state.phase ?? "active",
+			manualPrompt: state.manualPrompt ?? null
 		});
 		res.write(`data: ${payload}\n\n`);
 	}
@@ -6947,7 +7119,7 @@ function createDebugServer(deps) {
 	};
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.131"
+		version: "0.1.133"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -8931,7 +9103,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.131"
+		version: "0.1.133"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {