@ait-co/devtools 0.1.133 → 0.1.135

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.133";
+	return "0.1.135";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -3513,9 +3513,13 @@ var ChiiCdpConnection = class {
 	/**
 	* Issue a CDP command and resolve with its result (Phase 2). Rejects on a CDP
 	* error frame or when no websocket is open (no page attached yet).
+	*
+	* @param opts.timeoutMs - Per-call override for this connection's command
+	*   watchdog (devtools#747) — see the `CdpConnection.send` docblock for the
+	*   contract callers racing their own longer timeout must follow.
 	*/
-	send(method, params) {
-		return this.sendCommand(method, params ?? {});
+	send(method, params, opts) {
+		return this.sendCommand(method, params ?? {}, opts);
 	}
 	/**
 	* Issue an arbitrary request→response command over the relay and resolve with
@@ -3526,16 +3530,22 @@ var ChiiCdpConnection = class {
 	* auto-reconnect). Caller should re-run `list_pages` or `enableDomains` to
 	* reattach.
 	*
-	* Times out after `commandTimeoutMs` (default 30s, env
-	* `AIT_CDP_COMMAND_TIMEOUT_MS`). On timeout the pending entry is cleaned up
-	* and the promise rejects with a descriptive Korean error.
+	* Times out after `opts.timeoutMs` when given, else `commandTimeoutMs`
+	* (default 30s, env `AIT_CDP_COMMAND_TIMEOUT_MS`) — see devtools#747: the
+	* default 30s watchdog used to undercut the test-runner's own longer
+	* file-evaluate race no matter what `--timeout` the caller asked for. On
+	* timeout the pending entry is cleaned up and the promise rejects with a
+	* descriptive Korean error. `Number.isFinite` guards against a non-finite
+	* override (e.g. `Infinity`, mirroring `waitForFirstTarget`'s convention)
+	* so an intentional "no watchdog" override doesn't get clamped by
+	* `setTimeout`.
 	*/
-	sendCommand(method, params = {}) {
+	sendCommand(method, params = {}, opts) {
 		if (this.connectionState === "disconnected") return Promise.reject(/* @__PURE__ */ new Error(`relay에 연결되어 있지 않습니다 (${method}). list_pages로 attach 상태를 확인하고 enableDomains()로 재연결하세요.`));
 		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return Promise.reject(/* @__PURE__ */ new Error("No mini-app page attached to the Chii relay yet. Call enableDomains() first."));
 		const id = this.nextCommandId++;
 		const ws = this.ws;
-		const timeoutMs = this.commandTimeoutMs;
+		const timeoutMs = opts?.timeoutMs !== void 0 && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.timeoutMs : this.commandTimeoutMs;
 		return new Promise((resolve, reject) => {
 			const handle = setTimeout(() => {
 				this.pending.delete(id);
@@ -4120,6 +4130,14 @@ function parseCaptureLines(raw) {
 /** Maximum milliseconds to wait for a single evaluate round-trip. */
 const DEFAULT_TIMEOUT_MS = 6e4;
 /**
+* Extra headroom (ms) added on top of the rpc-level `timeoutMs` when telling
+* the underlying `CdpConnection` its per-command watchdog budget (devtools#747).
+* The rpc-level race above is the authoritative file timeout — this margin
+* only ensures the connection's own (shorter-by-default) watchdog never fires
+* first and masks the rpc-level timeout error with a connection-level one.
+*/
+const CONNECTION_TIMEOUT_MARGIN_MS = 5e3;
+/**
 * Wraps bundle code in a self-executing IIFE that:
 *   1. Evaluates the bundle (registering describe/it/test).
 *   2. Calls `__testBundle.runTestModule(...)` — the entry the runtime exports.
@@ -4166,12 +4184,15 @@ function parseRunTestsResult(rawValue) {
 * Injects `bundleCode` into the attached page and awaits test execution.
 *
 * Uses `Runtime.evaluate` with `awaitPromise: true` to wait for the
-* async IIFE to settle.  The 30-second CDP command timeout covers even
-* long-running test suites; split into smaller files if you hit it.
+* async IIFE to settle. `timeoutMs` (default 60s) is the authoritative file
+* timeout — this function races it against the evaluate call AND (devtools#747)
+* threads it down to the underlying `CdpConnection`'s own per-command watchdog
+* (plus a small margin) so that watchdog can never undercut this race. Split
+* into smaller files if you hit the timeout.
 *
 * @param connection   - Active CDP connection (relay or local).
 * @param bundleCode   - IIFE bundle string from `bundleTestFile`.
-* @param timeoutMs    - Override the default 30 s timeout.
+* @param timeoutMs    - Override the default 60 s timeout.
 *
 * SECRET-HANDLING: `bundleCode` and the raw CDP result value are never logged.
 */
@@ -4183,7 +4204,7 @@ async function injectAndRunBundle(connection, bundleCode, timeoutMs = DEFAULT_TI
 		expression,
 		returnByValue: true,
 		awaitPromise: true
-	});
+	}, { timeoutMs: timeoutMs + CONNECTION_TIMEOUT_MARGIN_MS });
 	const raceResult = await Promise.race([evalPromise.then((v) => ({
 		tag: "eval",
 		v
@@ -4441,6 +4462,11 @@ OPTIONS
                           (report: <sdkLine>.<platform>.json; captures:
                           <dir>/.ait-capture/<category>.<sdkLine>.<platform>.json).
                           Omitted = nothing saved. Enables console capture.
+  --dashboard-port <port> Base port for the QR dashboard HTTP server. On
+                          EADDRINUSE it increments (+1, up to 20 tries) before
+                          falling back to an ephemeral port. Omit to use
+                          AIT_DEBUG_HTTP_PORT env or the built-in default
+                          (8317) — pass 0 to force a random ephemeral port.
   --no-qr-stdout          Suppress the QR/attach block on stdout (auto-on for
                           non-interactive stdout / CI / AIT_NO_QR_STDOUT)
   --headless              Disable browser auto-open (text QR only)
@@ -5244,8 +5270,13 @@ var LocalCdpConnection = class {
 	/**
 	* Issue a CDP command and resolve with its typed result. Rejects on a CDP
 	* error frame or when no websocket is open.
+	*
+	* `opts.timeoutMs` is accepted for `CdpConnection` interface parity but
+	* ignored — this connection has no per-command watchdog of its own
+	* (devtools#747 only affects `ChiiCdpConnection`, which layers a
+	* relay-command watchdog on top of the caller's own race).
 	*/
-	send(method, params) {
+	send(method, params, _opts) {
 		return this.sendCommand(method, params ?? {});
 	}
 	/**
@@ -6786,13 +6817,70 @@ function buildAttachHtml(qrDataUrl, safeLabel, safeAttachUrl, locale, path = "/a
 	return filled.replace("</body>", `${sseScript}\n</body>`);
 }
 /**
-* 로컬 HTTP 서버를 127.0.0.1 random port(또는 `AIT_DEBUG_HTTP_PORT` env)로 시작한다.
+* base 포트부터 EADDRINUSE 시 +1씩 증가하며 bind를 시도한다. EADDRINUSE가
+* 아닌 에러는 즉시 reject한다(스캔 대상 아님). `range`번 모두 점유 상태면
+* ephemeral(포트 0)로 폴백하고 한국어 안내를 stderr에 1회 출력한다.
+*
+* 매 시도마다 이전에 등록한 `error` 리스너를 제거한다 — 성공 시 listener가
+* 누적돼 다음 실패에서 중복 reject/EventEmitter 경고가 나는 것을 방지한다.
+*
+* `basePort === 0`이면 스캔 없이 즉시 ephemeral bind (명시적 opt-out, 기존
+* 순수 랜덤 포트 동작 유지).
+*/
+async function bindWithIncrement(server, basePort, range = 20) {
+	if (basePort === 0) return new Promise((resolve, reject) => {
+		const onError = (err) => reject(err);
+		server.once("error", onError);
+		server.listen(0, "127.0.0.1", () => {
+			server.removeListener("error", onError);
+			resolve();
+		});
+	});
+	for (let attempt = 0; attempt < range; attempt++) {
+		const candidatePort = basePort + attempt;
+		try {
+			await new Promise((resolve, reject) => {
+				const onError = (err) => {
+					server.removeListener("error", onError);
+					reject(err);
+				};
+				server.once("error", onError);
+				server.listen(candidatePort, "127.0.0.1", () => {
+					server.removeListener("error", onError);
+					resolve();
+				});
+			});
+			return;
+		} catch (err) {
+			if (err.code !== "EADDRINUSE") throw err;
+		}
+	}
+	process.stderr.write(`devtools: 대시보드 포트 ${basePort}~${basePort + range - 1}이 모두 사용 중이라 임의 포트로 대체합니다.\n`);
+	return new Promise((resolve, reject) => {
+		const onError = (err) => reject(err);
+		server.once("error", onError);
+		server.listen(0, "127.0.0.1", () => {
+			server.removeListener("error", onError);
+			resolve();
+		});
+	});
+}
+/**
+* 로컬 HTTP 서버를 127.0.0.1에 고정 base 포트({@link DEFAULT_DASHBOARD_PORT},
+* `AIT_DEBUG_HTTP_PORT` env, 또는 `options.dashboardPort`)에서 시작한다.
+* base 포트가 점유(EADDRINUSE) 상태면 +1씩 증가하며 재시도하고(최대
+* {@link PORT_SCAN_RANGE}회), 전부 점유면 ephemeral 포트로 폴백한다 —
+* rerun 시 대시보드 URL이 안정적으로 유지되어 브라우저 탭/북마크가
+* run마다 무효화되지 않는다 (devtools#752). base 포트를 명시적으로 `0`으로
+* 주면(env 또는 옵션) 기존 순수 ephemeral 동작을 유지한다.
+*
 * MCP debug server 생애주기에 묶어 사용 — `runDebugServer` shutdown 시 `close()`로 정리.
 *
 * @param getDashboardState - dashboard 상태를 반환하는 클로저. 주입 시 `GET /` dashboard와
 *   `GET /events` SSE 스트림이 활성화된다. 미주입 시 두 라우트는 204/서비스 없음으로 응답.
 * @param options - 서버 옵션. `sseRefreshIntervalMs`로 idle 탭 TOTP 만료 방지 주기를 조정.
 *   `getDirectInspectorUrl`로 /inspector 라우트에서 직접 조립 URL을 제공해 redirect 루프를 방지.
+*   `dashboardPort`로 bind base 포트를 override.
 */
 async function startQrHttpServer(getDashboardState, options) {
 	const { default: QRCode } = await import("qrcode");
@@ -6972,11 +7060,7 @@ async function startQrHttpServer(getDashboardState, options) {
 		res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
 		res.end("Not Found");
 	});
-	const listenPort = Number(process.env.AIT_DEBUG_HTTP_PORT ?? 0);
-	await new Promise((resolve, reject) => {
-		server.listen(listenPort, "127.0.0.1", () => resolve());
-		server.once("error", reject);
-	});
+	await bindWithIncrement(server, options?.dashboardPort ?? (process.env.AIT_DEBUG_HTTP_PORT !== void 0 ? Number(process.env.AIT_DEBUG_HTTP_PORT) : 8317), options?.portScanRange);
 	const address = server.address();
 	if (!address || typeof address === "string") throw new Error("qr-http-server: server.address()가 예상하지 못한 형태입니다.");
 	const port = address.port;
@@ -7119,7 +7203,7 @@ function createDebugServer(deps) {
 	};
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.133"
+		version: "0.1.135"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -9103,7 +9187,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.133"
+		version: "0.1.135"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {