weapp-ide-cli 6.1.8 → 6.2.0

package/README.md

@@ -253,6 +253,24 @@ if (isWeappIdeTopLevelCommand('preview')) {
 console.log(WEAPP_IDE_TOP_LEVEL_COMMAND_NAMES)
 ```
 
+截图发生协议、导航或截图请求超时时，默认最多重试一次，失败连接由原会话生命周期释放，不在重试层按项目键再次关闭共享连接；不调用无项目定位的 `close` 或退出共享宿主。重试仍失败时保留原始错误，手动打开的窗口和其他项目保持不变。
+
+登录诊断可使用 `queryWechatIdeLogin(cliPath, { timeout: 3000 })`，显式指定本轮选择的 CLI。只有原生 JSON 中的 `login` 布尔值才返回 `{ status: 'success', login }`；超时、命令失败、空输出或矛盾响应均返回 `{ status: 'unknown', reason }`。`unknown` 不等于未登录。机器租约冲突返回 `reason: 'runtime-busy'`，应等待持有者结束后再查询。该方法不提示、不重试、不回退安装路径；原生 `islogin` 可能启动 IDE，不属于静态探针。旧的 `isWechatIdeLoggedIn()` 保留 CLI 透传行为，其 Promise 完成不能作为登录事实。
+
+### 安装选择与共享登录
+
+日常开发和本仓库 E2E 推荐使用固定位置的一份官方 Stable。多个项目复用同一个已登录宿主，无需为测试另外准备微信账号；登录正常过期时仍需通过 IDE 完成登录。不要复制 ticket、Cookie 或账号配置来同步两个安装。
+
+未提供固定 `target` 时，程序化调用的显式 `cliPath` 优先；未指定时依次使用进程环境变量 `WEAPP_IDE_CLI_PATH`、全局 `cliPath` 配置和平台默认路径。提供 `target` 后，额外的 `cliPath` 必须指向同一个真实 CLI 文件，符号链接别名可用；不同安装会抛出 `WECHAT_DEVTOOLS_INSTALLATION_SELECTION_CONFLICT`，不会覆盖既定选择。环境变量只作用于当前进程及其子进程，不写回配置文件。`weapp config doctor` 显示持久配置与实际生效路径、产品版本和安装身份。
+
+HTTP 服务端口和 automator 会话都绑定选定安装。另一安装的配置较新、端口可连或版本号相同，均不代表可以复用。未知旧会话不会直接连接；宿主或监听端口归属不一致时停止操作，保留原有 IDE 和账号状态。`port` 仍表示对应接口原有的端口类型，不将 automator WebSocket 端口当作 HTTP 服务端口。
+
+显式 HTTP 或 automator 端口必须是 `1` 到 `65535` 的整数；CLI、MCP 和 REST 同样拒绝无效端口，不会将 `0`、小数、混合文本或超范围值当作默认端口。打开项目的 HTTP 请求与官方 CLI 回退共用一次安装选择和机器租约，安装冲突不会触发回退。
+
+`openWechatIdeProjectByHttp()` 使用 `/v2/open` 的 `project` 参数并保留原始响应正文；空正文或空 JSON 对象会抛出 `WECHAT_DEVTOOLS_HTTP_OPEN_UNCONFIRMED`，不能把 HTTP 200 当作项目已打开的证据。目标项目及 runtime 是否就绪仍需通过会话或 IDE 界面确认。
+
+本仓库真实 IDE E2E 显式设置 `WEAPP_VITE_E2E_DEVTOOLS_CLI_PATH`，预检把它传入本轮公共 CLI，核对执行时官方 Stable 与实际宿主；不会自动安装或切换版本。不同 worktree 的 E2E 使用同机同用户的排他租约，冲突报告 `Runtime busy`，应等待持有者结束。普通 CLI 的宿主变更同样参与协调，已建立的多项目连接不长期占用此租约。自动恢复不清共享缓存、不退出账号；只释放本任务登记的资源。
+
 ### 6. 程序化 opened-session helper
 
 除了官方 CLI 透传和 automator 子命令，`weapp-ide-cli` 也提供了一组面向「已打开 DevTools 会话」的 helper。它们会优先复用当前项目对应的会话，在官方 HTTP / Tool 域能力可用时直接下发指令，减少再次拉起 IDE 或误打开项目选择页的概率。

package/dist/automator-BkZZsGtn.js

@@ -0,0 +1 @@
+export { n as launchAutomator } from "./automator-CRpB6_pA.js";

package/dist/automator-CRpB6_pA.js

@@ -0,0 +1,576 @@
+import { _ as readCustomConfig, a as assertWechatDevtoolsPort, i as assertWechatDevtoolsHost, n as readPersistedAutomatorSession, r as resolveWechatDevtoolsTarget, t as persistAutomatorSession } from "./sessionStore-zdzy2UFM.js";
+import path from "node:path";
+import { withMachineE2ELease } from "@weapp-vite/devtools-runtime";
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import process from "node:process";
+import os from "node:os";
+import { OperationLifecycle } from "@weapp-vite/miniprogram-automator/operation";
+//#region src/cli/automator/port.ts
+/** 显式端口不能被截断或作为默认值忽略，避免连接其他项目。 */
+function assertAutomatorPort(port) {
+	if (port !== void 0 && (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535)) throw Object.assign(/* @__PURE__ */ new RangeError("Automator port must be an integer between 1 and 65535."), { code: "DEVTOOLS_INVALID_PORT" });
+}
+/** CLI 只接受完整十进制数字，缺失值、尾随字符和指数写法均报错。 */
+function parseAutomatorPort(raw) {
+	const port = raw !== void 0 && /^\d+$/.test(raw) ? Number(raw) : NaN;
+	assertAutomatorPort(port);
+	return port;
+}
+//#endregion
+//#region src/cli/automator/context.ts
+/** 在连接与共享缓存入口固定安装选择；headless 不读取或修改 IDE 状态。 */
+async function resolveAutomatorSessionOptions(options) {
+	assertAutomatorPort(options.port);
+	options.signal?.throwIfAborted();
+	const runtimeProvider = options.runtimeProvider ?? process.env.WEAPP_VITE_AUTOMATOR_RUNTIME_PROVIDER ?? process.env.WEAPP_VITE_E2E_RUNTIME_PROVIDER;
+	if (runtimeProvider === "headless") return {
+		...options,
+		runtimeProvider,
+		installationId: "headless"
+	};
+	const target = await resolveWechatDevtoolsTarget(options);
+	options.signal?.throwIfAborted();
+	if (options.installationId && options.installationId !== target.installationId) throw Object.assign(/* @__PURE__ */ new Error("DEVTOOLS_INSTALLATION_MISMATCH: resolved installation does not match the selected session."), { code: "DEVTOOLS_INSTALLATION_MISMATCH" });
+	return {
+		...options,
+		target,
+		cliPath: target.cliPath,
+		installationId: target.installationId
+	};
+}
+//#endregion
+//#region src/cli/automator/errors.ts
+const ERROR_STACK_PREFIX_RE = /^at /;
+const ERROR_PREFIX_RE = /^\[error\]\s*/i;
+const ERROR_LABEL_PREFIX_RE = /^error\s*:\s*/i;
+const ERROR_LINE_SPLIT_RE = /\r?\n/;
+const LOGIN_REQUIRED_CN_RE = /需要重新登录/;
+const LOGIN_REQUIRED_EN_RE = /need\s+re-?login|re-?login/i;
+const LOGIN_REQUIRED_CODE_RE = /code\s*[:=]\s*(\d+)/i;
+const DEVTOOLS_HTTP_PORT_ERROR = "Failed to launch wechat web devTools, please make sure http port is open";
+const DEVTOOLS_EXTENSION_CONTEXT_INVALIDATED_RE = /Extension context invalidated/i;
+const AUTOMATOR_LAUNCH_TIMEOUT_RE = /Wait timed out after \d+ ms/i;
+const AUTOMATOR_WS_CONNECT_RE = /Failed connecting to ws:\/\/127\.0\.0\.1:\d+/i;
+const AUTOMATOR_PORT_IN_USE_RE = /Port \d+ is in use, please specify another port/i;
+const DEVTOOLS_PROTOCOL_TIMEOUT_RE = /DevTools did not respond to protocol method (\S+) within \d+ms/i;
+const DEVTOOLS_INFRA_ERROR_PATTERNS = [
+	/#initialize-error:\s*wait IDE port timeout/i,
+	/wait IDE port timeout/i,
+	/listen EPERM/i,
+	/operation not permitted 0\.0\.0\.0/i,
+	/EACCES/i,
+	/ECONNREFUSED/i,
+	/connect ECONNREFUSED/i
+];
+const DEVTOOLS_LOGIN_REQUIRED_PATTERNS = [
+	/code\s*[:=]\s*10/i,
+	/需要重新登录/,
+	/need\s+re-?login/i,
+	/re-?login/i
+];
+/**
+* @description 从错误对象中提取可读文本。
+*/
+function extractErrorText(error) {
+	if (!error || typeof error !== "object") return "";
+	const candidate = error;
+	return [
+		candidate.message,
+		candidate.shortMessage,
+		candidate.stderr,
+		candidate.stdout
+	].filter((value) => typeof value === "string" && value.trim().length > 0).join("\n");
+}
+/**
+* @description 提取登录失效时最适合展示给用户的一行信息。
+*/
+function extractLoginRequiredMessage(text) {
+	if (!text) return "";
+	if (LOGIN_REQUIRED_CN_RE.test(text)) return "需要重新登录";
+	const englishMatch = text.match(LOGIN_REQUIRED_EN_RE);
+	if (englishMatch?.[0]) return englishMatch[0].toLowerCase();
+	const firstLine = text.split(ERROR_LINE_SPLIT_RE).map((line) => line.trim()).find((line) => Boolean(line) && !ERROR_STACK_PREFIX_RE.test(line));
+	if (!firstLine) return "";
+	return firstLine.replace(ERROR_PREFIX_RE, "").replace(ERROR_LABEL_PREFIX_RE, "").slice(0, 120);
+}
+/**
+* @description 判断错误是否属于开发者工具服务端口不可用。
+*/
+function isDevtoolsHttpPortError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return message.includes(DEVTOOLS_HTTP_PORT_ERROR) || DEVTOOLS_INFRA_ERROR_PATTERNS.some((pattern) => pattern.test(message));
+}
+/**
+* @description 判断错误是否属于开发者工具 automator 扩展上下文尚未就绪。
+*/
+function isDevtoolsExtensionContextInvalidatedError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return DEVTOOLS_EXTENSION_CONTEXT_INVALIDATED_RE.test(message);
+}
+/**
+* @description 判断错误是否属于可重试的 automator 启动抖动。
+*/
+function isRetryableAutomatorLaunchError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return DEVTOOLS_EXTENSION_CONTEXT_INVALIDATED_RE.test(message) || AUTOMATOR_LAUNCH_TIMEOUT_RE.test(message) || AUTOMATOR_WS_CONNECT_RE.test(message);
+}
+/**
+* @description 判断错误是否属于开发者工具 websocket 连接失败。
+*/
+function isAutomatorWsConnectError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return AUTOMATOR_WS_CONNECT_RE.test(message);
+}
+/**
+* @description 判断错误是否属于目标项目 automator 端口仍被旧会话占用。
+*/
+function isAutomatorPortInUseError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return AUTOMATOR_PORT_IN_USE_RE.test(message);
+}
+/**
+* @description 判断错误是否属于开发者工具协议调用超时。
+*/
+function isAutomatorProtocolTimeoutError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return DEVTOOLS_PROTOCOL_TIMEOUT_RE.test(message);
+}
+/**
+* @description 提取协议超时的方法名。
+*/
+function getAutomatorProtocolTimeoutMethod(error) {
+	return (error instanceof Error ? error.message : String(error)).match(DEVTOOLS_PROTOCOL_TIMEOUT_RE)?.[1];
+}
+/**
+* @description 判断错误是否属于开发者工具登录失效。
+*/
+function isAutomatorLoginError(error) {
+	const text = extractErrorText(error);
+	if (!text) return false;
+	return DEVTOOLS_LOGIN_REQUIRED_PATTERNS.some((pattern) => pattern.test(text));
+}
+/**
+* @description 格式化开发者工具登录失效错误，便于终端展示。
+*/
+function formatAutomatorLoginError(error) {
+	const text = extractErrorText(error);
+	const code = text.match(LOGIN_REQUIRED_CODE_RE)?.[1];
+	const message = extractLoginRequiredMessage(text);
+	const lines = ["微信开发者工具返回登录错误："];
+	if (code) lines.push(`- code: ${code}`);
+	if (message) lines.push(`- message: ${message}`);
+	if (!code && !message) lines.push("- message: 需要重新登录");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/cli/automatorProject.ts
+const WRAPPER_ROOT = path.join(os.tmpdir(), "weapp-ide-cli-automator-projects");
+function normalizeProjectRelativeRoot(rawRoot) {
+	if (typeof rawRoot !== "string") return;
+	const normalized = rawRoot.trim().replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/+$/, "");
+	if (!normalized || normalized === ".") return;
+	if (normalized.split("/").includes("..")) return;
+	return normalized;
+}
+async function pathExists(filePath) {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function readJsonObject$1(filePath) {
+	try {
+		const raw = await fs.readFile(filePath, "utf8");
+		const value = JSON.parse(raw);
+		return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+	} catch {
+		return;
+	}
+}
+async function writeJsonObject$1(filePath, value) {
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+async function copyProjectRoot(sourceProjectPath, wrapperProjectPath, relativeRoot) {
+	const sourcePath = path.join(sourceProjectPath, relativeRoot);
+	if (!await pathExists(sourcePath)) return;
+	await fs.cp(sourcePath, path.join(wrapperProjectPath, relativeRoot), {
+		dereference: true,
+		force: true,
+		recursive: true
+	});
+}
+function createWrapperProjectConfig(source, patch) {
+	const { miniprogramRoot: _miniprogramRoot, qcloudRoot: _qcloudRoot, srcMiniprogramRoot: _srcMiniprogramRoot, ...rest } = source;
+	const sourceSetting = source.setting && typeof source.setting === "object" ? source.setting : {};
+	const patchSetting = patch.setting && typeof patch.setting === "object" ? patch.setting : {};
+	return {
+		...rest,
+		...patch,
+		setting: {
+			...sourceSetting,
+			...patchSetting,
+			packNpmManually: false,
+			packNpmRelationList: []
+		}
+	};
+}
+async function ensureWrapperAppConfig(wrapperProjectPath) {
+	const appConfigPath = path.join(wrapperProjectPath, "app.json");
+	const appConfig = await readJsonObject$1(appConfigPath);
+	if (!appConfig) return;
+	await writeJsonObject$1(appConfigPath, {
+		...appConfig,
+		subPackages: Array.isArray(appConfig.subPackages) ? appConfig.subPackages : []
+	});
+}
+/**
+* @description 为 DevTools automator 准备稳定的小程序根目录，避免打开瞬间跨 miniprogramRoot 读取 app.json 抖动。
+*/
+async function resolveAutomatorProjectPath(projectPath) {
+	const sourceProjectPath = path.resolve(projectPath);
+	const projectConfig = await readJsonObject$1(path.join(sourceProjectPath, "project.config.json"));
+	const miniprogramRoot = normalizeProjectRelativeRoot(projectConfig?.miniprogramRoot);
+	if (!miniprogramRoot) return {
+		projectPath: sourceProjectPath,
+		sourceProjectPath
+	};
+	const sourceProjectConfig = projectConfig ?? {};
+	const distRoot = path.join(sourceProjectPath, miniprogramRoot);
+	if (!await pathExists(path.join(distRoot, "app.json"))) return {
+		projectPath: sourceProjectPath,
+		sourceProjectPath
+	};
+	const wrapperHash = createHash("sha1").update(sourceProjectPath).update("\0").update(path.resolve(distRoot)).digest("hex").slice(0, 16);
+	const wrapperProjectPath = path.join(WRAPPER_ROOT, wrapperHash);
+	await fs.rm(wrapperProjectPath, {
+		recursive: true,
+		force: true
+	});
+	await fs.mkdir(wrapperProjectPath, { recursive: true });
+	await fs.cp(distRoot, wrapperProjectPath, {
+		dereference: true,
+		force: true,
+		recursive: true
+	});
+	const pluginRoot = normalizeProjectRelativeRoot(sourceProjectConfig.pluginRoot);
+	if (pluginRoot) await copyProjectRoot(sourceProjectPath, wrapperProjectPath, pluginRoot);
+	const rootPatch = {
+		compileType: sourceProjectConfig.compileType === "plugin" ? "plugin" : "miniprogram",
+		miniprogramRoot: "./",
+		srcMiniprogramRoot: "./"
+	};
+	const projectPrivateConfig = await readJsonObject$1(path.join(sourceProjectPath, "project.private.config.json")) ?? {};
+	await writeJsonObject$1(path.join(wrapperProjectPath, "project.config.json"), createWrapperProjectConfig(sourceProjectConfig, {
+		...projectPrivateConfig,
+		...rootPatch
+	}));
+	await fs.rm(path.join(wrapperProjectPath, "project.private.config.json"), { force: true });
+	await ensureWrapperAppConfig(wrapperProjectPath);
+	return {
+		cleanup: async () => {
+			await fs.rm(wrapperProjectPath, {
+				recursive: true,
+				force: true
+			});
+		},
+		projectPath: wrapperProjectPath,
+		sourceProjectPath
+	};
+}
+//#endregion
+//#region src/cli/wechatDevtoolsSettings.ts
+function createStorageHash(key) {
+	return createHash("md5").update(key).digest("hex");
+}
+const SETTINGS_STORAGE_HASH = createStorageHash("reduxPersist:settings");
+const SETTINGS_STORAGE_FILE_NAMES = [`localstorage_${SETTINGS_STORAGE_HASH}.json`, `ls_${SETTINGS_STORAGE_HASH}.json`];
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizePort(value) {
+	if (typeof value !== "number" || !Number.isInteger(value)) return;
+	if (value <= 0 || value > 65535) return;
+	return value;
+}
+function normalizeWechatDevtoolsSecuritySettings(value) {
+	if (!isRecord(value)) return;
+	const normalized = {};
+	if (typeof value.enableServicePort === "boolean") normalized.enableServicePort = value.enableServicePort;
+	const port = normalizePort(value.port);
+	if (port !== void 0) normalized.port = port;
+	if (typeof value.allowGetTicket === "boolean") normalized.allowGetTicket = value.allowGetTicket;
+	if (typeof value.trustWhenAuto === "boolean") normalized.trustWhenAuto = value.trustWhenAuto;
+	return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+async function resolveSelectedProfile(options) {
+	const platform = options.platform ?? process.platform;
+	if (!options.target && platform !== "darwin" && platform !== "win32") return;
+	return (await resolveWechatDevtoolsTarget(options)).profileDir;
+}
+async function readJsonObject(filePath) {
+	try {
+		const raw = await fs.readFile(filePath, "utf8");
+		const parsed = JSON.parse(raw);
+		if (!isRecord(parsed)) return {};
+		return parsed;
+	} catch (error) {
+		if (error.code === "ENOENT") return {};
+		if (error instanceof SyntaxError) return {};
+		throw error;
+	}
+}
+async function writeJsonObject(filePath, value) {
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+async function detectWechatDevtoolsSecuritySettings(localDataDir) {
+	for (const fileName of SETTINGS_STORAGE_FILE_NAMES) {
+		const security = normalizeWechatDevtoolsSecuritySettings((await readJsonObject(path.join(localDataDir, fileName))).security);
+		if (security) return security;
+	}
+}
+async function trustWechatDevtoolsProject(localDataDir, projectPath) {
+	const normalizedProjectPath = path.resolve(projectPath);
+	const projectHash = createStorageHash(`project2_${normalizedProjectPath}`);
+	const fileNames = [`localstorage_${projectHash}.json`, `ls_${projectHash}.json`];
+	let trusted = false;
+	for (const fileName of fileNames) {
+		const projectFilePath = path.join(localDataDir, fileName);
+		const current = await readJsonObject(projectFilePath);
+		if (current.projectid !== normalizedProjectPath || current.projectpath !== normalizedProjectPath || typeof current.appid !== "string" || !current.appid || !isRecord(current.attr) || !isRecord(current.attr.setting)) continue;
+		await writeJsonObject(projectFilePath, {
+			...current,
+			isTrusted: true
+		});
+		trusted = true;
+	}
+	return trusted;
+}
+async function scanWechatDevtoolsServicePort(profileDir) {
+	const localDataDir = profileDir && path.join(profileDir, "WeappLocalData");
+	const exists = localDataDir && await fs.stat(localDataDir).then((stat) => stat.isDirectory(), (error) => {
+		if (error.code !== "ENOENT") throw error;
+		return false;
+	});
+	const security = exists && localDataDir ? await detectWechatDevtoolsSecuritySettings(localDataDir) : void 0;
+	return {
+		touchedInstanceCount: exists ? 1 : 0,
+		detectedSecurityCount: security ? 1 : 0,
+		servicePort: security?.port,
+		servicePortEnabled: security?.enableServicePort
+	};
+}
+/**
+* @description 检测微信开发者工具当前服务端口配置，严格沿用用户已有设置。
+*/
+async function detectWechatDevtoolsServicePort(options = {}) {
+	return await scanWechatDevtoolsServicePort(await resolveSelectedProfile(options));
+}
+/**
+* @description 在启动微信开发者工具前，检测服务端口配置，并按需写入项目信任信息。
+*/
+async function bootstrapWechatDevtoolsSettings(options = {}) {
+	const profileDir = await resolveSelectedProfile(options);
+	const result = await scanWechatDevtoolsServicePort(profileDir);
+	const trusted = profileDir && result.touchedInstanceCount && options.projectPath && options.trustProject === true ? await trustWechatDevtoolsProject(path.join(profileDir, "WeappLocalData"), options.projectPath) : false;
+	return {
+		...result,
+		updatedSecurityCount: 0,
+		trustedProjectCount: trusted ? 1 : 0
+	};
+}
+//#endregion
+//#region src/cli/automator.ts
+const PROJECT_AUTOMATOR_PORT_BASE = 9620;
+const PROJECT_AUTOMATOR_PORT_RANGE = 2e3;
+/**
+* @description 为项目路径派生稳定的 DevTools automator 端口，避免多个 dev:open 项目抢占默认端口。
+*/
+function resolveProjectAutomatorPort(projectPath) {
+	const offset = createHash("sha1").update(path.resolve(projectPath)).digest().readUInt32BE(0) % PROJECT_AUTOMATOR_PORT_RANGE;
+	return PROJECT_AUTOMATOR_PORT_BASE + offset;
+}
+async function launchSelectedAutomator(options) {
+	const { port, projectPath, sessionId, timeout = 3e4 } = options;
+	const lifecycle = new OperationLifecycle(timeout, "IDE launch", options.signal);
+	let managedLaunch;
+	try {
+		return await lifecycle.run(async (scope) => {
+			const { Launcher } = await scope.step(() => import("@weapp-vite/miniprogram-automator"), { stage: "load-automator" });
+			const { target, cliPath: resolvedCliPath, installationId, runtimeProvider } = await scope.step(() => resolveAutomatorSessionOptions(options), { stage: "resolve-cli" });
+			if (runtimeProvider === "headless") return await scope.step(() => new Launcher().launch({
+				projectPath,
+				runtimeProvider,
+				timeout: scope.remainingMs(),
+				signal: scope.signal
+			}), {
+				stage: "launch",
+				disposeLate: (program) => program.disconnect()
+			});
+			await scope.step(() => assertWechatDevtoolsHost(target, {
+				signal: scope.signal,
+				timeout: scope.remainingMs()
+			}), { stage: "host-identity" });
+			const config = await scope.step(() => readCustomConfig(), { stage: "configuration" });
+			const resolvedTrustProject = options.trustProject ?? config.autoTrustProject ?? false;
+			const launcher = new Launcher();
+			let lastError = null;
+			let bootstrapResult;
+			const resolvedProject = options.preserveProjectRoot ? {
+				projectPath: path.resolve(projectPath),
+				sourceProjectPath: path.resolve(projectPath)
+			} : await scope.step(() => resolveAutomatorProjectPath(projectPath), { stage: "project" });
+			if (process.env.WEAPP_IDE_MANAGED_PROJECT_JOURNAL) {
+				const { launchManagedAutomator } = await import("./managed-Sq8y8FzP.js");
+				managedLaunch = launchManagedAutomator({
+					launcher,
+					scope,
+					target,
+					projectPath: resolvedProject.projectPath,
+					sourceProjectPath: projectPath,
+					port: port ?? resolveProjectAutomatorPort(resolvedProject.projectPath),
+					sessionId,
+					trustProject: resolvedTrustProject,
+					persistAsDefaultSession: options.persistAsDefaultSession
+				});
+				return await managedLaunch;
+			}
+			if (config.autoBootstrapDevtools !== false) bootstrapResult = await scope.step(() => bootstrapWechatDevtoolsSettings({
+				target,
+				projectPath: resolvedProject.projectPath,
+				trustProject: resolvedTrustProject
+			}), { stage: "settings" });
+			if (bootstrapResult?.servicePortEnabled === false) throw new Error("Detected WeChat DevTools service port is disabled in current settings. Please enable it manually; existing user settings were not modified.");
+			for (let attempt = 0; attempt < 2; attempt += 1) {
+				scope.attempt();
+				try {
+					const miniProgram = await scope.step(() => launcher.launch({
+						cliPath: resolvedCliPath,
+						...port ? { port } : {},
+						projectPath: resolvedProject.projectPath,
+						timeout: scope.remainingMs(),
+						signal: scope.signal,
+						trustProject: resolvedTrustProject
+					}), {
+						stage: "launch",
+						disposeLate: (program) => program.disconnect()
+					});
+					scope.own(() => miniProgram.disconnect(), "automator-session");
+					const sessionMetadata = Reflect.get(miniProgram, "__WEAPP_VITE_SESSION_METADATA");
+					if (typeof sessionMetadata?.wsEndpoint === "string" && sessionMetadata.wsEndpoint) {
+						const wsEndpoint = sessionMetadata.wsEndpoint;
+						await scope.step(() => assertWechatDevtoolsPort(target, Number(new URL(wsEndpoint).port), {
+							signal: scope.signal,
+							timeout: scope.remainingMs()
+						}), { stage: "port-identity" });
+						await scope.step(() => persistAutomatorSession({
+							installationId,
+							signal: scope.signal,
+							...port ? { port: sessionMetadata.port ?? port } : {},
+							projectPath,
+							sessionId,
+							wsEndpoint
+						}), { stage: "session-persist" });
+						if (options.persistAsDefaultSession && (port || sessionId)) await scope.step(() => persistAutomatorSession({
+							installationId,
+							signal: scope.signal,
+							projectPath,
+							wsEndpoint
+						}), { stage: "session-persist" });
+					}
+					return miniProgram;
+				} catch (error) {
+					lastError = error;
+					scope.recordFailure(error);
+					scope.throwIfAborted();
+					if (!isRetryableAutomatorLaunchError(error) || attempt === 1) throw error;
+				}
+			}
+			throw lastError instanceof Error ? lastError : new Error(String(lastError));
+		});
+	} catch (error) {
+		if (managedLaunch) await (await managedLaunch).close();
+		throw error;
+	}
+}
+/**
+* @description 基于当前配置解析 CLI 路径，并通过现代化 automator 入口启动会话。
+*/
+async function launchAutomator(options) {
+	options.signal?.throwIfAborted();
+	return (options.runtimeProvider ?? process.env.WEAPP_VITE_AUTOMATOR_RUNTIME_PROVIDER ?? process.env.WEAPP_VITE_E2E_RUNTIME_PROVIDER) === "headless" ? await launchSelectedAutomator(options) : await withMachineE2ELease(() => launchSelectedAutomator(options));
+}
+/**
+* @description 登记由外部 automator bridge 创建的会话，供 CLI 子进程安全复用。
+*/
+async function persistOpenedAutomatorSession(options) {
+	const resolved = await resolveAutomatorSessionOptions(options);
+	if (resolved.runtimeProvider === "headless" || !resolved.target) throw new Error("DEVTOOLS_SESSION_PROVIDER_INVALID: external automator sessions require the WeChat DevTools provider.");
+	const endpoint = new URL(options.wsEndpoint);
+	if (endpoint.protocol !== "ws:" || endpoint.hostname !== "127.0.0.1" || !endpoint.port) throw new Error("DEVTOOLS_SESSION_ENDPOINT_INVALID: automator session endpoint must be a loopback websocket.");
+	const endpointPort = Number(endpoint.port);
+	const port = options.port ?? endpointPort;
+	if (port !== endpointPort) throw new Error(`DEVTOOLS_SESSION_PORT_MISMATCH: endpoint=${endpointPort} option=${port}`);
+	await assertWechatDevtoolsPort(resolved.target, endpointPort, {
+		signal: options.signal,
+		timeout: options.timeout ?? 3e4
+	});
+	await persistAutomatorSession({
+		installationId: resolved.installationId,
+		projectPath: options.projectPath,
+		port,
+		...options.sessionId ? { sessionId: options.sessionId } : {},
+		signal: options.signal,
+		wsEndpoint: options.wsEndpoint
+	});
+	if (!options.port && !options.sessionId) await persistAutomatorSession({
+		installationId: resolved.installationId,
+		projectPath: options.projectPath,
+		signal: options.signal,
+		wsEndpoint: options.wsEndpoint
+	});
+}
+/**
+* @description 只读连接当前项目已打开的自动化会话；失败不证明缓存过期，也不删除其他操作持有的会话记录。
+*/
+async function connectOpenedAutomator(options) {
+	const { port, projectPath, sessionId } = options;
+	return await new OperationLifecycle(options.timeout ?? 3e4, "IDE connect", options.signal).run(async (scope) => {
+		const { Launcher } = await scope.step(() => import("@weapp-vite/miniprogram-automator"), { stage: "load-automator" });
+		scope.attempt();
+		const launcher = new Launcher();
+		const resolved = await scope.step(() => resolveAutomatorSessionOptions(options), { stage: "resolve-cli" });
+		const persistedSession = await scope.step(() => readPersistedAutomatorSession({
+			projectPath,
+			sessionId,
+			port,
+			installationId: resolved.installationId
+		}), { stage: "session-lookup" });
+		if (!persistedSession) throw Object.assign(/* @__PURE__ */ new Error("DEVTOOLS_SESSION_IDENTITY_UNVERIFIED: no matching installation-bound session; launch the selected installation before connecting."), { code: "DEVTOOLS_SESSION_IDENTITY_UNVERIFIED" });
+		const wsEndpoint = persistedSession.wsEndpoint;
+		await scope.step(() => assertWechatDevtoolsPort(resolved.target, Number(new URL(wsEndpoint).port), {
+			signal: scope.signal,
+			timeout: scope.remainingMs()
+		}), { stage: "port-identity" });
+		const miniProgram = await scope.step(async () => await launcher.connect({
+			timeout: scope.remainingMs(),
+			signal: scope.signal,
+			wsEndpoint
+		}), {
+			stage: "connect",
+			disposeLate: (program) => {
+				if (program && typeof program === "object" && "disconnect" in program && typeof program.disconnect === "function") program.disconnect();
+			}
+		});
+		if (process.env.WEAPP_IDE_MANAGED_PROJECT_JOURNAL) miniProgram.close = async () => {
+			miniProgram.disconnect();
+		};
+		return miniProgram;
+	});
+}
+//#endregion
+export { parseAutomatorPort as _, bootstrapWechatDevtoolsSettings as a, getAutomatorProtocolTimeoutMethod as c, isAutomatorProtocolTimeoutError as d, isAutomatorWsConnectError as f, resolveAutomatorSessionOptions as g, isRetryableAutomatorLaunchError as h, resolveProjectAutomatorPort as i, isAutomatorLoginError as l, isDevtoolsHttpPortError as m, launchAutomator as n, detectWechatDevtoolsServicePort as o, isDevtoolsExtensionContextInvalidatedError as p, persistOpenedAutomatorSession as r, formatAutomatorLoginError as s, connectOpenedAutomator as t, isAutomatorPortInUseError as u };