@weapp-vite/miniprogram-automator 1.2.23 → 1.3.0

package/dist/index.mjs

@@ -1,31 +1,48 @@
+import { OPERATION_TIMEOUT_CODE, OperationLifecycle, classifyOperationError, isRecoverableOperationError, readWechatLoginState } from "./operation.mjs";
 import { randomUUID } from "node:crypto";
 import net from "node:net";
 import process from "node:process";
-import { spawn } from "node:child_process";
 import path from "node:path";
 import { EventEmitter } from "node:events";
 import { createDebug } from "obug";
 import WebSocket from "ws";
 import fs from "node:fs/promises";
 import os from "node:os";
+import { spawn } from "node:child_process";
 import { decodeQrCodeFromBase64, renderTerminalQrCode } from "@weapp-vite/qr";
 import { Buffer } from "node:buffer";
 //#region src/internal/compat/async.ts
 /**
 * @file 异步控制工具。
 */
-/** sleep 的方法封装。 */
-function sleep$1(timeout) {
-	return new Promise((resolve) => setTimeout(resolve, timeout));
+/** 可取消的延迟，取消时释放自身计时器。 */
+function sleep$1(timeout, signal) {
+	signal?.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		let timer;
+		function abort() {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", abort);
+			reject(signal?.reason);
+		}
+		timer = setTimeout(() => {
+			signal?.removeEventListener("abort", abort);
+			resolve();
+		}, timeout);
+		signal?.addEventListener("abort", abort, { once: true });
+	});
 }
-/** waitUntil 的方法封装。 */
-async function waitUntil(condition, timeout = 0, interval = 250) {
-	const startTime = Date.now();
+/** 条件轮询受同一个单调时钟 deadline 与取消信号约束。 */
+async function waitUntil(condition, timeout = 0, interval = 250, signal) {
+	const deadlineAt = timeout ? performance.now() + timeout : Number.POSITIVE_INFINITY;
 	while (true) {
+		signal?.throwIfAborted();
 		const value = await condition();
+		signal?.throwIfAborted();
 		if (value) return value;
-		if (timeout && Date.now() - startTime >= timeout) throw new Error(`Wait timed out after ${timeout} ms`);
-		await sleep$1(interval);
+		const remaining = deadlineAt - performance.now();
+		if (remaining <= 0) throw new Error(`Wait timed out after ${timeout} ms`);
+		await sleep$1(Math.min(interval, remaining), signal);
 	}
 }
 //#endregion
@@ -825,7 +842,7 @@ var Transport = class extends EventEmitter {
 		this.ws.send(message);
 	}
 	close() {
-		this.ws.close();
+		this.ws.terminate();
 	}
 };
 //#endregion
@@ -840,10 +857,17 @@ const CONNECT_TIMEOUT = 3e4;
 /** Page frame 定向消息失效、需要切换到 App-service Page 协议的 DevTools 版本。 */
 const APP_SERVICE_PAGE_PROTOCOL_VERSIONS = /* @__PURE__ */ new Set(["2.01.2510290"]);
 /** 仅页面方法调用失效的版本，元素查询仍保留原生组件作用域。 */
-const APP_SERVICE_PAGE_METHOD_VERSIONS = /* @__PURE__ */ new Set(["2.02.2608070", "2.02.2609231"]);
+const APP_SERVICE_PAGE_METHOD_VERSIONS = /* @__PURE__ */ new Set([
+	"2.02.2608070",
+	"2.02.2608080",
+	"2.02.2609231",
+	"2.02.2610082",
+	"2.02.2610092"
+]);
 /** Connection 的实现。 */
 var Connection = class Connection extends EventEmitter {
 	transport;
+	disposed = false;
 	callbacks = /* @__PURE__ */ new Map();
 	useAppServicePageProtocol = false;
 	useAppServicePageMethod = false;
@@ -854,6 +878,7 @@ var Connection = class Connection extends EventEmitter {
 		transport.on("close", this.onClose);
 	}
 	send(method, params = {}, options = {}) {
+		if (this.disposed) return Promise.reject(/* @__PURE__ */ new Error(closeErrTip));
 		const id = uuid();
 		const payload = stringify({
 			id,
@@ -877,14 +902,19 @@ var Connection = class Connection extends EventEmitter {
 			});
 			try {
 				this.transport.send(payload);
-			} catch {
+			} catch (cause) {
 				clearTimeout(timeout);
 				this.callbacks.delete(id);
-				reject(/* @__PURE__ */ new Error(closeErrTip));
+				reject(new Error(closeErrTip, { cause }));
 			}
 		});
 	}
 	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.onClose();
+		this.transport.off("message", this.onMessage);
+		this.transport.off("close", this.onClose);
 		this.transport.close();
 	}
 	/** 根据 DevTools 版本选择稳定的 Page 协议实现。 */
@@ -924,35 +954,53 @@ var Connection = class Connection extends EventEmitter {
 		}
 		this.callbacks.clear();
 	};
-	static create(url, timeout = CONNECT_TIMEOUT) {
+	static create(url, timeout = CONNECT_TIMEOUT, signal) {
+		signal?.throwIfAborted();
 		return new Promise((resolve, reject) => {
 			const ws = new WebSocket(url);
 			let settled = false;
-			const timer = setTimeout(() => {
+			let timer;
+			let onAbort;
+			let onOpen;
+			let onClose;
+			function cleanup() {
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+				ws.off("open", onOpen);
+				ws.off("close", onClose);
+			}
+			function fail(error) {
 				if (settled) return;
 				settled = true;
-				ws.close();
-				reject(/* @__PURE__ */ new Error(`Timed out connecting to DevTools websocket ${url} after ${timeout}ms`));
-			}, timeout);
-			ws.on("open", () => {
+				cleanup();
+				ws.terminate();
+				reject(error);
+			}
+			onAbort = () => {
+				fail(signal?.reason);
+			};
+			onClose = () => {
+				fail(/* @__PURE__ */ new Error("DevTools websocket closed before handshake completed"));
+			};
+			onOpen = () => {
 				if (settled) return;
 				settled = true;
-				clearTimeout(timer);
+				cleanup();
 				resolve(new Connection(new Transport(ws)));
-			});
-			ws.on("error", (error) => {
-				if (settled) return;
-				settled = true;
-				clearTimeout(timer);
-				reject(error);
-			});
+			};
+			timer = setTimeout(() => fail(/* @__PURE__ */ new Error(`Timed out connecting to DevTools websocket ${url} after ${timeout}ms`)), timeout);
+			ws.on("open", onOpen);
+			ws.on("error", fail);
+			ws.on("close", onClose);
+			signal?.addEventListener("abort", onAbort, { once: true });
+			if (signal?.aborted) onAbort();
 		});
 	}
 };
 //#endregion
 //#region src/headless.ts
 async function launchHeadlessAutomator(options) {
-	return await (await import("./launch-CSjvON-f.mjs")).launch({ projectPath: options.projectPath });
+	return await (await import("./launch-anJvfi-6.mjs")).launch({ projectPath: options.projectPath });
 }
 //#endregion
 //#region src/launcher/portLease.ts
@@ -1064,7 +1112,10 @@ async function enableAutomatorViaHttp(options) {
 	if (options.account) endpoint.searchParams.set("account", options.account);
 	if (options.ticket) endpoint.searchParams.set("ticket", options.ticket);
 	if (options.trustProject) endpoint.searchParams.set("trustProject", "true");
-	const response = await fetch(endpoint, { redirect: "follow" });
+	const response = await fetch(endpoint, {
+		redirect: "follow",
+		signal: options.signal
+	});
 	const body = await response.text();
 	if (!response.ok) throw new Error(`WeChat DevTools HTTP automator fallback failed with status ${response.status}`);
 	let result;
@@ -1073,6 +1124,7 @@ async function enableAutomatorViaHttp(options) {
 	} catch {
 		throw new Error("WeChat DevTools HTTP automator fallback returned invalid JSON");
 	}
+	if (result && typeof result === "object" && "code" in result && Number(result.code) === 10) throw Object.assign(/* @__PURE__ */ new Error("DEVTOOLS_LOGIN_REQUIRED: need re-login"), { code: 10 });
 	if (result && typeof result === "object" && "autoPort" in result) {
 		const autoPort = Number(result.autoPort);
 		if (!Number.isInteger(autoPort) || autoPort <= 0 || autoPort > 65535) throw new Error("WeChat DevTools HTTP automator fallback returned invalid autoPort");
@@ -1106,8 +1158,122 @@ function resolveWechatDevtoolsBootstrapArgs(args) {
 	return bootstrapArgs;
 }
 //#endregion
+//#region src/launcher/process.ts
+const WINDOWS_BATCH_CLI_RE = /\.(?:bat|cmd)$/i;
+function shouldUseWindowsCommandShell(cliPath) {
+	return isWindows && WINDOWS_BATCH_CLI_RE.test(cliPath);
+}
+function escapeWindowsCmdArg(arg) {
+	const escaped = arg.replace(/"/g, "\"\"").replace(/%/g, "%%");
+	return /[\s"&<>^|()]/.test(arg) ? `"${escaped}"` : escaped;
+}
+function resolveWindowsBatchSpawn(cliPath, args) {
+	return {
+		file: process.env.ComSpec || "cmd.exe",
+		args: [
+			"/d",
+			"/s",
+			"/c",
+			`"${[cliPath, ...args].map(escapeWindowsCmdArg).join(" ")}"`
+		]
+	};
+}
+/** 只持有本次 CLI 子进程句柄；退出后不通过旧 PID 查找或终止宿主。 */
+function spawnWechatCli(cliPath, args, cwd, scope) {
+	scope.throwIfAborted();
+	const state = {
+		error: null,
+		success: false,
+		exited: false,
+		output: ""
+	};
+	const bootstrapArgs = resolveWechatDevtoolsBootstrapArgs(args);
+	const target = shouldUseWindowsCommandShell(cliPath) ? resolveWindowsBatchSpawn(cliPath, bootstrapArgs) : {
+		file: cliPath,
+		args: bootstrapArgs
+	};
+	const child = spawn(target.file, target.args, {
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		cwd: cwd || void 0,
+		...shouldUseWindowsCommandShell(cliPath) ? {
+			windowsHide: true,
+			windowsVerbatimArguments: true
+		} : {}
+	});
+	let released;
+	const release = () => {
+		if (!released) released = new Promise((resolve) => {
+			if (state.exited || !child.pid || child.exitCode !== null || child.signalCode !== null) {
+				resolve();
+				return;
+			}
+			child.once("close", () => resolve());
+			child.kill("SIGKILL");
+		});
+		return released;
+	};
+	const disown = scope.own(release, "cli-process");
+	child.on("error", (error) => {
+		state.error = error;
+	});
+	const output = (chunk) => {
+		state.output = (state.output + String(chunk)).slice(-32768);
+	};
+	child.stdout?.on("data", output);
+	child.stderr?.on("data", output);
+	child.on("exit", (code, signal) => {
+		disown();
+		state.exited = true;
+		if (code !== 0 || signal) state.error = /* @__PURE__ */ new Error(`DevTools cli exited unexpectedly with code ${code ?? "null"}${signal ? ` and signal ${signal}` : ""}`);
+		else state.success = true;
+	});
+	child.unref();
+	return Object.assign(state, { release });
+}
+//#endregion
 //#region package.json
-var version = "1.2.23";
+var version = "1.3.0";
+//#endregion
+//#region src/appServiceHeap.ts
+function isRecord$1(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function unsupported$1(reason) {
+	return {
+		status: "unsupported",
+		source: "appservice-cdp-runtime",
+		reason
+	};
+}
+/** 只读取 AppService 当前 V8 堆，不调用 GC，也不把协议故障或空响应当成零内存。 */
+async function readAppServiceHeapUsage(send, options = {}) {
+	const timeout = options.timeout ?? 2500;
+	if (!Number.isFinite(timeout) || timeout <= 0) throw new TypeError("AppService heap timeout must be finite and positive");
+	let response;
+	try {
+		response = await send("App.CDPCommand", {
+			domain: "Runtime",
+			method: "getHeapUsage",
+			params: {}
+		}, { timeout });
+	} catch (error) {
+		if (error instanceof Error && (error.message === "appservice App.CDPCommand unimplemented" || error.message === "Method not implemented.")) return unsupported$1("protocol-unimplemented");
+		if (error instanceof Error && error.message === "'Runtime.getHeapUsage' wasn't found") return unsupported$1("method-not-found");
+		throw error;
+	}
+	if (isRecord$1(response) && isRecord$1(response.error) && response.error.code === -32601) return unsupported$1("method-not-found");
+	if (!isRecord$1(response) || response.error || response.exceptionDetails || typeof response.usedSize !== "number" || !Number.isFinite(response.usedSize) || response.usedSize < 0 || typeof response.totalSize !== "number" || !Number.isFinite(response.totalSize) || response.totalSize < response.usedSize) throw new Error("Invalid AppService Runtime.getHeapUsage response: expected finite non-negative usedSize <= totalSize");
+	return {
+		status: "available",
+		source: "appservice-cdp-runtime",
+		usedSize: response.usedSize,
+		totalSize: response.totalSize
+	};
+}
 //#endregion
 //#region src/Native.ts
 /** Native 的实现。 */
@@ -1158,6 +1324,25 @@ var Native = class extends EventEmitter {
 	}
 };
 //#endregion
+//#region src/navigation/query.ts
+/** 仅核对请求显式携带的参数，保留宿主附加参数及其原始编码形式。 */
+function matchesRouteQuery(actual, expected) {
+	const expectedKeys = Object.keys(expected);
+	if (!expectedKeys.length) return true;
+	if (!actual || typeof actual !== "object" || Array.isArray(actual)) return false;
+	const query = actual;
+	return expectedKeys.every((key) => {
+		if (!Object.prototype.hasOwnProperty.call(query, key) || query[key] == null) return false;
+		const value = String(query[key]);
+		if (value === expected[key]) return true;
+		try {
+			return decodeURIComponent(value) === expected[key];
+		} catch {
+			return false;
+		}
+	});
+}
+//#endregion
 //#region src/pageRouteFallback.ts
 function normalizeFallbackIdPart(value) {
 	return encodeURIComponent(value).replace(/%/g, "_");
@@ -2422,7 +2607,7 @@ function isPluginNavigationUrl(value) {
 }
 function matchesRouteChange(options) {
 	const normalizedCurrentPath = normalizeRoutePath(options.currentPath);
-	if (!options.expectedRoute || normalizedCurrentPath === options.expectedRoute) return true;
+	if (!options.expectedRoute || normalizedCurrentPath === options.expectedRoute) return matchesRouteQuery(options.currentQuery, options.expectedQuery);
 	if (!isPluginNavigationUrl(options.requestedUrl) || !isPluginPath(options.currentPath)) return false;
 	return normalizedCurrentPath !== normalizeRoutePath(options.previousPath);
 }
@@ -2600,6 +2785,10 @@ var MiniProgram = class extends EventEmitter {
 		}, sendOptions);
 		return result;
 	}
+	/** 探测并读取 AppService JS 堆；明确不支持时返回原因，连接故障与无效响应继续抛出。 */
+	async getAppServiceHeapUsage(options = {}) {
+		return await readAppServiceHeapUsage((method, params, sendOptions) => this.send(method, params, sendOptions), options);
+	}
 	async pageScrollTo(scrollTop) {
 		await this.callWxMethod("pageScrollTo", {
 			scrollTop,
@@ -2695,7 +2884,7 @@ var MiniProgram = class extends EventEmitter {
 		if (sdkVersion !== "dev" && cmpVersion(sdkVersion, "2.7.3") < 0) throw new Error(`SDKVersion is currently ${sdkVersion}, while automator(${version}) requires at least version 2.7.3`);
 	}
 	/**
-	* @description 等待小程序 App 域协议可用，避免返回半就绪自动化会话。
+	* @description 等待原生协议返回真实页面标识和路径，避免返回半就绪自动化会话。
 	*/
 	async waitForAppReady(timeout = APP_READY_TIMEOUT) {
 		const startedAt = Date.now();
@@ -2703,13 +2892,15 @@ var MiniProgram = class extends EventEmitter {
 		while (Date.now() - startedAt < timeout) {
 			const remainingTimeout = timeout - (Date.now() - startedAt);
 			try {
-				await this.send("App.captureScreenshot", {}, { timeout: Math.min(APP_READY_PROBE_TIMEOUT, remainingTimeout) });
-				return;
+				const page = await this.send("App.getCurrentPage", {}, { timeout: Math.min(APP_READY_PROBE_TIMEOUT, remainingTimeout) });
+				if (page && typeof page === "object" && "pageId" in page && typeof page.pageId === "number" && Number.isSafeInteger(page.pageId) && page.pageId >= 0 && "path" in page && typeof page.path === "string" && page.path.trim()) return;
+				lastError = /* @__PURE__ */ new Error("App.getCurrentPage returned no ready page with a valid pageId and path");
 			} catch (error) {
+				if (!isCurrentPageProtocolTimeout(error) && !isPageMetaMissingError(error) && !isCurrentFrameTimedOutError(error)) throw error;
 				lastError = error;
-				const remainingAfterProbe = timeout - (Date.now() - startedAt);
-				if (remainingAfterProbe > 0) await sleep(Math.min(APP_READY_POLL_DELAY, remainingAfterProbe));
 			}
+			const remainingAfterProbe = timeout - (Date.now() - startedAt);
+			if (remainingAfterProbe > 0) await sleep(Math.min(APP_READY_POLL_DELAY, remainingAfterProbe));
 		}
 		throw lastError instanceof Error ? lastError : /* @__PURE__ */ new Error(`Timed out waiting App domain readiness after ${timeout}ms`);
 	}
@@ -2800,9 +2991,11 @@ var MiniProgram = class extends EventEmitter {
 				logChangeRouteDebug(`poll method=${method} url=${url ?? "<none>"} current=${page?.path ?? "<none>"}`);
 				if (matchesRouteChange({
 					currentPath: page?.path,
+					currentQuery: page?.query,
 					previousPath: currentPage?.path,
 					requestedUrl: url,
-					expectedRoute
+					expectedRoute,
+					expectedQuery: expectedRouteQuery
 				})) {
 					logChangeRouteDebug(`ready method=${method} url=${url ?? "<none>"} current=${page?.path ?? "<none>"}`);
 					return page;
@@ -2819,9 +3012,11 @@ var MiniProgram = class extends EventEmitter {
 					logChangeRouteDebug(`stack method=${method} url=${url ?? "<none>"} current=${stackTop.path}`);
 					if (matchesRouteChange({
 						currentPath: stackTop.path,
+						currentQuery: stackTop.query,
 						previousPath: currentPage?.path,
 						requestedUrl: url,
-						expectedRoute
+						expectedRoute,
+						expectedQuery: expectedRouteQuery
 					})) {
 						logChangeRouteDebug(`stack-ready method=${method} url=${url ?? "<none>"} current=${stackTop.path}`);
 						return stackTop;
@@ -3364,16 +3559,7 @@ const VERSION_CHECK_TIMEOUT = 3e4;
 const AUTOMATOR_LAUNCH_RETRIES = 3;
 const DEFAULT_RUNTIME_PROVIDER_ENV = "WEAPP_VITE_AUTOMATOR_RUNTIME_PROVIDER";
 const LEGACY_RUNTIME_PROVIDER_ENV = "WEAPP_VITE_E2E_RUNTIME_PROVIDER";
-const EXTENSION_CONTEXT_INVALIDATED_RE = /Extension context invalidated/i;
-const RETRYABLE_LAUNCH_PORT_RE = /Wait timed out after \d+ ms|Failed connecting to ws:\/\/127\.0\.0\.1:\d+|Failed connecting to devtools websocket endpoint|Failed to launch wechat web devTools, please make sure cliPath is correctly specified/i;
-const WINDOWS_BATCH_CLI_RE = /\.(?:bat|cmd)$/i;
 let localhostListenPatched = false;
-function isExtensionContextInvalidatedError(error) {
-	return error instanceof Error && EXTENSION_CONTEXT_INVALIDATED_RE.test(error.message);
-}
-function isRetryableAutomatorPortLaunchError(error) {
-	return error instanceof Error && RETRYABLE_LAUNCH_PORT_RE.test(error.message);
-}
 function retainPortLeaseUntilSessionClose(miniProgram, portLease) {
 	let released = false;
 	const release = async () => {
@@ -3418,25 +3604,6 @@ function patchNetListenToLoopback() {
 		return rawListen.apply(this, args);
 	};
 }
-/** IConnectOptions 的类型定义。 */
-function shouldUseWindowsCommandShell(cliPath) {
-	return isWindows && WINDOWS_BATCH_CLI_RE.test(cliPath);
-}
-function escapeWindowsCmdArg(arg) {
-	const escaped = arg.replace(/"/g, "\"\"").replace(/%/g, "%%");
-	return /[\s"&<>^|()]/.test(arg) ? `"${escaped}"` : escaped;
-}
-function resolveWindowsBatchSpawn(cliPath, args) {
-	return {
-		file: process.env.ComSpec || "cmd.exe",
-		args: [
-			"/d",
-			"/s",
-			"/c",
-			`"${[cliPath, ...args].map(escapeWindowsCmdArg).join(" ")}"`
-		]
-	};
-}
 function resolveRuntimeProvider(options) {
 	return options.runtimeProvider || process.env[DEFAULT_RUNTIME_PROVIDER_ENV] || process.env[LEGACY_RUNTIME_PROVIDER_ENV] || "devtools";
 }
@@ -3449,88 +3616,62 @@ var Launcher = class {
 			return await launchHeadlessAutomator({ projectPath: options.projectPath });
 		}
 		patchNetListenToLoopback();
-		if (options.port) return await this.launchWechatDevtools(options);
-		let lastError = null;
-		for (let attempt = 1; attempt <= AUTOMATOR_LAUNCH_RETRIES; attempt += 1) try {
-			return await this.launchWechatDevtools(options);
-		} catch (error) {
-			lastError = error;
-			if (!isRetryableAutomatorPortLaunchError(error) || attempt === AUTOMATOR_LAUNCH_RETRIES) throw error;
-		}
-		throw lastError instanceof Error ? lastError : new Error(String(lastError));
+		return await new OperationLifecycle(options.timeout ?? DEFAULT_TIMEOUT, "automator launch", options.signal).run(async (scope) => {
+			const attempts = options.port ? 1 : AUTOMATOR_LAUNCH_RETRIES;
+			for (let attempt = 1;; attempt += 1) {
+				scope.attempt();
+				try {
+					return await scope.step(() => this.launchWechatDevtools(options, scope));
+				} catch (error) {
+					scope.recordFailure(error);
+					scope.throwIfAborted();
+					if (!isRecoverableOperationError(error) || attempt >= attempts) throw error;
+				}
+			}
+		});
 	}
-	async launchWechatDevtools(options) {
-		const { cliPath = await this.resolveCliPath(), timeout = DEFAULT_TIMEOUT, projectConfig = {}, ticket = "", cwd = "", account = "", trustProject = false } = options;
-		let { args = [], projectPath } = options;
-		const portLease = await acquireAutomatorPortLease(options.port);
+	async launchWechatDevtools(options, scope) {
+		const { cliPath = await scope.step(() => this.resolveCliPath(), { stage: "resolve-cli" }), projectConfig = {}, ticket = "", cwd = "", account = "", trustProject = false } = options;
+		const { args = [], projectPath } = options;
+		const portLease = await scope.step(() => acquireAutomatorPortLease(options.port), {
+			stage: "port-lease",
+			disposeLate: (lease) => lease.release()
+		});
+		const rawReleaseLease = portLease.release.bind(portLease);
+		let releasedLease;
+		portLease.release = () => releasedLease ??= rawReleaseLease();
+		const disownLease = scope.own(() => portLease.release(), "port-lease");
 		let releasePortLeaseOnExit = true;
+		let releaseChild = async () => {};
 		try {
 			const port = portLease.port;
 			if (!cliPath) throw new Error("Wechat web devTools not found, please specify cliPath option");
 			if (isWindows && endWith(cliPath, ".exe")) throw new Error("cliPath is not correct, it's usually named as 'cli' or 'cli.bat'");
 			if (!projectPath) throw new Error("projectPath is not provided");
 			const resolvedProjectPath = isRelative(projectPath) ? path.resolve(projectPath) : projectPath;
-			if (isRelative(projectPath)) projectPath = resolvedProjectPath;
-			if (!await import("node:fs/promises").then((fs) => fs.access(resolvedProjectPath).then(() => true).catch(() => false))) throw new Error(`Project path ${resolvedProjectPath} doesn't exist`);
-			if (!isEmpty(projectConfig)) await this.extendProjectConfig(projectConfig, resolvedProjectPath);
-			let processError = null;
-			let processExitCode = null;
-			let processSignal = null;
-			let successfulCliExitSettled = false;
+			if (!await scope.step(() => import("node:fs/promises").then((fs) => fs.access(resolvedProjectPath).then(() => true).catch(() => false)), { stage: "project" })) throw new Error(`Project path ${resolvedProjectPath} doesn't exist`);
+			if (!isEmpty(projectConfig)) await scope.step(() => this.extendProjectConfig(projectConfig, resolvedProjectPath), { stage: "project-config" });
+			scope.throwIfAborted();
 			let httpFallbackAttempted = false;
 			let httpFallbackError = null;
 			let targetPort = port;
-			const cliOutput = [];
-			args = resolveWechatDevtoolsBootstrapArgs(args);
-			try {
-				const spawnTarget = shouldUseWindowsCommandShell(cliPath) ? resolveWindowsBatchSpawn(cliPath, args) : {
-					file: cliPath,
-					args
-				};
-				const child = spawn(spawnTarget.file, spawnTarget.args, {
-					stdio: [
-						"ignore",
-						"pipe",
-						"pipe"
-					],
-					cwd: cwd || void 0,
-					...shouldUseWindowsCommandShell(cliPath) ? {
-						windowsHide: true,
-						windowsVerbatimArguments: true
-					} : {}
-				});
-				child.on("error", (error) => {
-					processError = error;
-				});
-				child.stdout?.on("data", (chunk) => {
-					cliOutput.push(String(chunk));
-				});
-				child.stderr?.on("data", (chunk) => {
-					cliOutput.push(String(chunk));
-				});
-				child.on("exit", (code, signal) => {
-					processExitCode = code;
-					processSignal = signal;
-					if (code !== 0 || signal) processError = /* @__PURE__ */ new Error(`DevTools cli exited unexpectedly with code ${code ?? "null"}${signal ? ` and signal ${signal}` : ""}`);
-					else successfulCliExitSettled = true;
-				});
-				child.unref();
-			} catch (error) {
-				processError = error;
-			}
+			const cli = spawnWechatCli(cliPath, args, cwd, scope);
+			releaseChild = cli.release;
 			let miniProgram = null;
 			let lastConnectError = null;
-			const readinessStartedAt = Date.now();
-			const resolveRemainingTimeout = () => Math.max(0, timeout - (Date.now() - readinessStartedAt));
-			await waitUntil(async () => {
+			const resolveRemainingTimeout = () => scope.remainingMs();
+			await scope.step(() => waitUntil(async () => {
+				scope.throwIfAborted();
 				try {
-					if (processError) return true;
-					if (successfulCliExitSettled && !httpFallbackAttempted) {
-						const servicePort = extractWechatDevtoolsServicePort(cliOutput.join("\n"));
+					if (cli.error) return true;
+					if (cli.success && readWechatLoginState(cli.output) === false) throw Object.assign(/* @__PURE__ */ new Error("DEVTOOLS_LOGIN_REQUIRED: need re-login"), { code: 10 });
+					if (cli.success && !httpFallbackAttempted) {
+						const servicePort = extractWechatDevtoolsServicePort(cli.output);
 						if (servicePort) {
 							httpFallbackAttempted = true;
 							try {
 								targetPort = await enableAutomatorViaHttp({
+									signal: scope.signal,
 									account,
 									autoPort: port,
 									projectPath: resolvedProjectPath,
@@ -3546,43 +3687,59 @@ var Launcher = class {
 					}
 					const connectTimeout = resolveRemainingTimeout();
 					if (connectTimeout <= 0) return false;
-					const candidate = await this.connectTool({
+					const candidate = await scope.step(() => this.connectTool({
+						signal: scope.signal,
 						timeout: Math.min(3e3, connectTimeout),
 						wsEndpoint: `ws://127.0.0.1:${targetPort}`
+					}), {
+						stage: "websocket",
+						disposeLate: (program) => program.disconnect()
 					});
+					let releasedCandidate = false;
+					const releaseCandidate = () => {
+						if (!releasedCandidate) {
+							releasedCandidate = true;
+							candidate.disconnect();
+						}
+					};
+					const disownCandidate = scope.own(releaseCandidate, "websocket");
 					try {
 						const checkVersionTimeout = resolveRemainingTimeout();
 						if (checkVersionTimeout <= 0) {
-							candidate.disconnect();
+							releaseCandidate();
 							return false;
 						}
-						await candidate.checkVersion(Math.min(VERSION_CHECK_TIMEOUT, checkVersionTimeout));
+						await scope.step(() => candidate.checkVersion(Math.min(VERSION_CHECK_TIMEOUT, checkVersionTimeout)), { stage: "version" });
 						if (typeof candidate.waitForAppReady === "function") {
 							const appReadyTimeout = resolveRemainingTimeout();
 							if (appReadyTimeout <= 0) {
-								candidate.disconnect();
+								releaseCandidate();
 								return false;
 							}
-							await candidate.waitForAppReady(appReadyTimeout);
+							await scope.step(() => candidate.waitForAppReady(appReadyTimeout), { stage: "app-ready" });
 						}
 					} catch (error) {
-						candidate.disconnect();
+						disownCandidate();
+						releaseCandidate();
 						lastConnectError = error;
-						if (isExtensionContextInvalidatedError(error)) return false;
+						if (isRecoverableOperationError(error)) return false;
 						throw error;
 					}
 					miniProgram = candidate;
 					return true;
 				} catch (error) {
 					lastConnectError = error;
+					scope.recordFailure(error);
+					scope.throwIfAborted();
+					if (!isRecoverableOperationError(error)) throw error;
 					return false;
 				}
-			}, timeout, 1e3);
+			}, scope.remainingMs(), 1e3, scope.signal), { stage: "readiness" });
 			if (!miniProgram) {
 				if (httpFallbackError) throw httpFallbackError;
-				if (processError) throw new Error("Failed to launch wechat web devTools, please make sure cliPath is correctly specified");
+				if (cli.error) throw new Error("Failed to launch wechat web devTools, please make sure cliPath is correctly specified", { cause: cli.error });
 				if (lastConnectError) throw lastConnectError;
-				if (processExitCode !== null || processSignal) throw new Error("Failed to launch wechat web devTools, please make sure http port is open");
+				if (cli.exited) throw new Error("Failed to launch wechat web devTools, please make sure http port is open");
 				throw new Error("Failed connecting to devtools websocket endpoint");
 			}
 			const resolvedMiniProgram = miniProgram;
@@ -3592,33 +3749,32 @@ var Launcher = class {
 				wsEndpoint: `ws://127.0.0.1:${targetPort}`
 			});
 			releasePortLeaseOnExit = !retainPortLeaseUntilSessionClose(resolvedMiniProgram, portLease);
-			await sleep$1(5e3);
+			disownLease();
 			return resolvedMiniProgram;
 		} finally {
-			if (releasePortLeaseOnExit) await portLease.release();
+			await releaseChild();
+			if (releasePortLeaseOnExit) {
+				disownLease();
+				await portLease.release();
+			}
 		}
 	}
 	async connect(options) {
 		if (normalizePlatform(options.platform) === "swan") return await new SwanLauncher().connect(options);
-		const timeout = options.timeout ?? DEFAULT_TIMEOUT;
-		const deadlineAt = performance.now() + timeout;
-		const miniProgram = await this.connectTool({
-			...options,
-			timeout
-		});
-		try {
-			const remaining = Math.ceil(deadlineAt - performance.now());
-			if (remaining <= 0) throw new Error(`Timed out connecting to automator after ${timeout}ms`);
-			await miniProgram.checkVersion(remaining);
+		return await new OperationLifecycle(options.timeout ?? DEFAULT_TIMEOUT, "automator connect", options.signal).run(async (scope) => {
+			scope.attempt();
+			const miniProgram = await scope.step(() => this.connectTool({
+				...options,
+				signal: scope.signal,
+				timeout: scope.remainingMs()
+			}), {
+				stage: "websocket",
+				disposeLate: (program) => program.disconnect()
+			});
+			scope.own(() => miniProgram.disconnect(), "websocket");
+			await scope.step(() => miniProgram.checkVersion(scope.remainingMs()), { stage: "version" });
 			return miniProgram;
-		} catch (error) {
-			try {
-				miniProgram.disconnect();
-			} catch (cleanupError) {
-				throw new AggregateError([error, cleanupError], "Automator connection and cleanup both failed", { cause: error });
-			}
-			throw error;
-		}
+		});
 	}
 	async extendProjectConfig(projectConfig, projectPath) {
 		const projectConfigPath = path.resolve(projectPath, "project.config.json");
@@ -3630,9 +3786,9 @@ var Launcher = class {
 	}
 	async connectTool(options) {
 		try {
-			return new MiniProgram(await Connection.create(options.wsEndpoint, options.timeout));
-		} catch {
-			throw new Error(`Failed connecting to ${options.wsEndpoint}, check if target project window is opened with automation enabled`);
+			return new MiniProgram(await Connection.create(options.wsEndpoint, options.timeout, options.signal));
+		} catch (cause) {
+			throw new Error(`Failed connecting to ${options.wsEndpoint}, check if target project window is opened with automation enabled`, { cause });
 		}
 	}
 	async resolveCliPath() {
@@ -3674,4 +3830,4 @@ var Automator = class {
 */
 const SmartappAutomator = smartappAutomatorRuntime;
 //#endregion
-export { Automator, Connection, ContextElement, CustomElement, Element, InputElement, Launcher, MiniProgram, MovableViewElement, Native, Page, ScrollViewElement, SliderElement, SmartappAutomator, SwiperElement, SwitchElement, TextareaElement, Transport, decodeQrCode, extractPluginId, isPluginPath, normalizePlatform, printQrCode };
+export { Automator, Connection, ContextElement, CustomElement, Element, InputElement, Launcher, MiniProgram, MovableViewElement, Native, OPERATION_TIMEOUT_CODE, OperationLifecycle, Page, ScrollViewElement, SliderElement, SmartappAutomator, SwiperElement, SwitchElement, TextareaElement, Transport, acquireAutomatorPortLease, classifyOperationError, decodeQrCode, extractPluginId, isPluginPath, isRecoverableOperationError, normalizePlatform, printQrCode, readWechatLoginState };