@ait-co/devtools 0.1.134 → 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.134";
+	return "0.1.135";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -4462,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)
@@ -6812,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");
@@ -6998,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;
@@ -7145,7 +7203,7 @@ function createDebugServer(deps) {
 	};
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.134"
+		version: "0.1.135"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -9129,7 +9187,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.134"
+		version: "0.1.135"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {