preflite 1.0.1

package/dist/infrastructure/config/agentConfigFile.js

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+/** 显式路径；未设置时使用 `process.cwd()/config.yaml`。 */
+export function resolveAgentConfigPath() {
+    const fromEnv = process.env.AGENT_CONFIG_PATH?.trim();
+    if (fromEnv)
+        return path.resolve(fromEnv);
+    return path.resolve(process.cwd(), "config.yaml");
+}
+function scalarToEnvString(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    if (typeof value === "string")
+        return value;
+    return undefined;
+}
+/** 仅接受顶层的标量键；嵌套对象会被跳过并打日志。 */
+export function flattenYamlConfigToEnv(doc) {
+    if (!doc || typeof doc !== "object" || Array.isArray(doc))
+        return {};
+    const out = {};
+    for (const [k, raw] of Object.entries(doc)) {
+        const key = k.trim();
+        if (!key)
+            continue;
+        if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+            console.warn(`[config] 跳过非标量配置项（请改为顶层 UPPER_SNAKE_CASE）: ${key}`);
+            continue;
+        }
+        if (Array.isArray(raw)) {
+            console.warn(`[config] 跳过数组配置项: ${key}`);
+            continue;
+        }
+        const s = scalarToEnvString(raw);
+        if (s === undefined)
+            continue;
+        out[key] = s;
+    }
+    return out;
+}
+/**
+ * 读取单一 `config.yaml`，将其中出现的键写入 `process.env`（覆盖已有值）。
+ * 文件不存在时静默跳过；解析失败时打错误并 `process.exit(1)`。
+ */
+export function applyAgentConfigFileToProcessEnv() {
+    const configPath = resolveAgentConfigPath();
+    if (!fs.existsSync(configPath)) {
+        return;
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, "utf8");
+    }
+    catch (e) {
+        console.error(`[config] 无法读取配置文件: ${configPath}`, e);
+        process.exit(1);
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (e) {
+        console.error(`[config] YAML 解析失败: ${configPath}`, e);
+        process.exit(1);
+    }
+    const flat = flattenYamlConfigToEnv(parsed);
+    const n = Object.keys(flat).length;
+    for (const [k, v] of Object.entries(flat)) {
+        process.env[k] = v;
+    }
+    if (n > 0) {
+        console.info(`[config] 已从 ${configPath} 加载 ${n} 项环境变量`);
+    }
+}
+/**
+ * 若 `AGENT_HTTP_TOKEN` / `PLATFORM_WS_TOKEN` / `PLATFORM_AGENT_CALLBACK_TOKEN` 中仅部分填写
+ *（与平台共用同一 Bearer 时常见），将已填项回填到未填项，便于只配一处。
+ *
+ * 回填顺序：HTTP 缺省 ← WS → 回调；WS 缺省 ← HTTP → 回调；回调缺省 ← HTTP → WS。
+ */
+export function applyMutualAgentAuthTokenFallbackToProcessEnv() {
+    const h = process.env.AGENT_HTTP_TOKEN?.trim() ?? "";
+    const w = process.env.PLATFORM_WS_TOKEN?.trim() ?? "";
+    const c = process.env.PLATFORM_AGENT_CALLBACK_TOKEN?.trim() ?? "";
+    if (!h && (w || c))
+        process.env.AGENT_HTTP_TOKEN = w || c;
+    if (!w && (h || c))
+        process.env.PLATFORM_WS_TOKEN = h || c;
+    if (!c && (h || w))
+        process.env.PLATFORM_AGENT_CALLBACK_TOKEN = h || w;
+}

package/dist/infrastructure/device/DeviceAppPackageOps.js

@@ -0,0 +1,146 @@
+import { PlatformType } from "../../shared-kernel/enums/index.js";
+import { buildAndroidAdbCliPrefix, buildHarmonyHdcShellPrefix, shSingleQuote } from "../adapters/deviceDetailsProbe.js";
+/**
+ * 卸载 CLI 非零退出且输出表明「包未安装 / 不存在」时视为幂等成功（与手动多卸一次一致）。
+ * 用于单测与各端卸载容错；连接类错误仍应失败。
+ */
+export function isUninstallTargetAbsentOk(platform, stdout, stderr) {
+    const t = `${stdout}\n${stderr}`.toLowerCase();
+    switch (platform) {
+        case PlatformType.ANDROID:
+            return (t.includes("failure [not installed") ||
+                t.includes("unknown package") ||
+                t.includes("package unknown") ||
+                t.includes("delete_failed_unknown_package") ||
+                t.includes("package not installed"));
+        case PlatformType.IOS: {
+            if (t.includes("could not connect to lockdownd") ||
+                t.includes("could not start com.apple.mobile.installation_proxy") ||
+                t.includes("could not connect to device")) {
+                return false;
+            }
+            return (t.includes("not installed on the device") ||
+                t.includes("application not installed") ||
+                t.includes("app not installed") ||
+                (t.includes("uninstall") && t.includes("not installed")) ||
+                (t.includes("uninstall") && t.includes("not found")) ||
+                (t.includes("bundle identifier") && t.includes("not found")) ||
+                t.includes("application not found") ||
+                t.includes("no suitable application") ||
+                t.includes("appnotfound"));
+        }
+        case PlatformType.HARMONY:
+            return (t.includes("17700001") ||
+                t.includes("bundle name does not exist") ||
+                t.includes("specified bundle name is not found") ||
+                t.includes("the specified bundle name is not found") ||
+                t.includes("包不存在") ||
+                t.includes("应用未安装") ||
+                (t.includes("bundle") && t.includes("not found")) ||
+                (t.includes("bundle") && t.includes("does not exist")));
+        default:
+            return false;
+    }
+}
+export class DeviceAppPackageOps {
+    runner;
+    config;
+    constructor(runner, config = {}) {
+        this.runner = runner;
+        this.config = config;
+    }
+    ideviceinstaller() {
+        const exe = this.config.ideviceinstallerExe?.trim() || "ideviceinstaller";
+        return /[^\w@%+=:,./-]/.test(exe) || exe.includes(" ") ? `"${exe.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : exe;
+    }
+    async installAndroid(serial, apkPath, timeoutMs) {
+        const adb = buildAndroidAdbCliPrefix(this.config.adbHost, this.config.adbPort);
+        const cmd = `${adb} -s ${shSingleQuote(serial)} install -r ${shSingleQuote(apkPath)}`;
+        const res = await this.runner.run(cmd, timeoutMs);
+        if (!res.ok) {
+            throw new Error(`adb install failed (exit ${res.exitCode}): ${res.stderr || res.stdout}`);
+        }
+    }
+    async uninstallAndroid(serial, packageName, timeoutMs) {
+        const adb = buildAndroidAdbCliPrefix(this.config.adbHost, this.config.adbPort);
+        const cmd = `${adb} -s ${shSingleQuote(serial)} uninstall ${shSingleQuote(packageName)}`;
+        const res = await this.runner.run(cmd, timeoutMs);
+        if (!res.ok && !isUninstallTargetAbsentOk(PlatformType.ANDROID, res.stdout, res.stderr)) {
+            throw new Error(`adb uninstall failed (exit ${res.exitCode}): ${res.stderr || res.stdout}`);
+        }
+    }
+    async installIos(udid, ipaPath, timeoutMs) {
+        const exe = this.ideviceinstaller();
+        const cmd = `${exe} -u ${shSingleQuote(udid)} install ${shSingleQuote(ipaPath)}`;
+        const res = await this.runner.run(cmd, timeoutMs);
+        if (!res.ok) {
+            throw new Error(`ideviceinstaller install failed (exit ${res.exitCode}): ${res.stderr || res.stdout}`);
+        }
+    }
+    async uninstallIos(udid, bundleId, timeoutMs) {
+        const exe = this.ideviceinstaller();
+        const cmd = `${exe} -u ${shSingleQuote(udid)} uninstall ${shSingleQuote(bundleId)}`;
+        const res = await this.runner.run(cmd, timeoutMs);
+        if (!res.ok && !isUninstallTargetAbsentOk(PlatformType.IOS, res.stdout, res.stderr)) {
+            throw new Error(`ideviceinstaller uninstall failed (exit ${res.exitCode}): ${res.stderr || res.stdout}`);
+        }
+    }
+    async installHarmony(deviceId, hapPath, timeoutMs) {
+        const hdc = buildHarmonyHdcShellPrefix(this.config.harmonyHdcPath, this.config.harmonyHdcHost, this.config.harmonyHdcPort);
+        const cmd = `${hdc} -t ${shSingleQuote(deviceId)} install -r ${shSingleQuote(hapPath)}`;
+        const res = await this.runner.run(cmd, timeoutMs);
+        if (!res.ok) {
+            throw new Error(`hdc install failed (exit ${res.exitCode}): ${res.stderr || res.stdout}`);
+        }
+    }
+    async uninstallHarmony(deviceId, bundleId, timeoutMs) {
+        const hdc = buildHarmonyHdcShellPrefix(this.config.harmonyHdcPath, this.config.harmonyHdcHost, this.config.harmonyHdcPort);
+        const cmd = `${hdc} -t ${shSingleQuote(deviceId)} uninstall ${shSingleQuote(bundleId)}`;
+        const res = await this.runner.run(cmd, timeoutMs);
+        if (!res.ok && !isUninstallTargetAbsentOk(PlatformType.HARMONY, res.stdout, res.stderr)) {
+            throw new Error(`hdc uninstall failed (exit ${res.exitCode}): ${res.stderr || res.stdout}`);
+        }
+    }
+    async install(platform, paths, packagePath, timeoutMs) {
+        switch (platform) {
+            case PlatformType.ANDROID:
+                if (!paths.serial)
+                    throw new Error("missing android serial");
+                await this.installAndroid(paths.serial, packagePath, timeoutMs);
+                return;
+            case PlatformType.IOS:
+                if (!paths.udid)
+                    throw new Error("missing ios udid");
+                await this.installIos(paths.udid, packagePath, timeoutMs);
+                return;
+            case PlatformType.HARMONY:
+                if (!paths.deviceId)
+                    throw new Error("missing harmony device id");
+                await this.installHarmony(paths.deviceId, packagePath, timeoutMs);
+                return;
+            default:
+                throw new Error(`unsupported platform for install: ${platform}`);
+        }
+    }
+    async uninstall(platform, paths, bundleId, timeoutMs) {
+        switch (platform) {
+            case PlatformType.ANDROID:
+                if (!paths.serial)
+                    throw new Error("missing android serial");
+                await this.uninstallAndroid(paths.serial, bundleId, timeoutMs);
+                return;
+            case PlatformType.IOS:
+                if (!paths.udid)
+                    throw new Error("missing ios udid");
+                await this.uninstallIos(paths.udid, bundleId, timeoutMs);
+                return;
+            case PlatformType.HARMONY:
+                if (!paths.deviceId)
+                    throw new Error("missing harmony device id");
+                await this.uninstallHarmony(paths.deviceId, bundleId, timeoutMs);
+                return;
+            default:
+                throw new Error(`unsupported platform for uninstall: ${platform}`);
+        }
+    }
+}

package/dist/infrastructure/ios/IOSWdaWatchdog.js

@@ -0,0 +1,207 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import net from "node:net";
+import path from "node:path";
+import { parseBootedSimulators, parseIOSDevices } from "../adapters/ios/IOSResourceAdapter.js";
+function extractDeviceId(resourceLike) {
+    const idx = resourceLike.indexOf(":");
+    return idx >= 0 ? resourceLike.slice(idx + 1) : resourceLike;
+}
+function normalizePortRange(startRaw, endRaw) {
+    const fallbackStart = 8200;
+    const fallbackEnd = 8399;
+    const start = Number.isFinite(startRaw) && startRaw > 0 ? Math.floor(startRaw) : fallbackStart;
+    const end = Number.isFinite(endRaw) && endRaw > 0 ? Math.floor(endRaw) : fallbackEnd;
+    return start <= end ? { start, end } : { start: end, end: start };
+}
+function renderTemplate(template, udid, wdaPort) {
+    return template
+        .replaceAll("{resourceId}", `ios:${udid}`)
+        .replaceAll("{deviceId}", extractDeviceId(udid))
+        .replaceAll("{wdaPort}", String(wdaPort));
+}
+export class IOSWdaWatchdog {
+    commandRunner;
+    options;
+    timer = null;
+    pollInFlight = null;
+    running = false;
+    stopped = false;
+    pollCount = 0;
+    portsByUdid = new Map();
+    constructor(commandRunner, options) {
+        this.commandRunner = commandRunner;
+        this.options = options;
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.stopped = false;
+        console.info(`[IOSWdaWatchdog] start intervalMs=${this.options.intervalMs} portRange=${this.options.portRangeStart}-${this.options.portRangeEnd} stateFile=${this.options.stateFilePath}`);
+        await this.loadPortMapState();
+        await this.pollOnce();
+        this.timer = setInterval(() => {
+            void this.pollOnce();
+        }, this.options.intervalMs);
+        this.timer.unref();
+    }
+    async stop() {
+        if (!this.running || this.stopped)
+            return;
+        console.info("[IOSWdaWatchdog] stopping");
+        this.stopped = true;
+        this.running = false;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        try {
+            if (this.pollInFlight) {
+                await this.pollInFlight;
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[IOSWdaWatchdog] pending poll failed while stopping: ${message}`);
+        }
+        const stopResult = await this.commandRunner.run(this.options.stopCommand, Math.max(5_000, this.options.startupTimeoutMs));
+        if (!stopResult.ok) {
+            const stderr = stopResult.stderr.trim();
+            console.warn(`[IOSWdaWatchdog] stop command failed: ${stderr || "unknown error"}`);
+            return;
+        }
+        console.info("[IOSWdaWatchdog] stop command finished");
+    }
+    async pollOnce() {
+        if (!this.running || this.stopped)
+            return;
+        if (this.pollInFlight)
+            return this.pollInFlight;
+        this.pollInFlight = this.doPoll();
+        try {
+            await this.pollInFlight;
+        }
+        finally {
+            this.pollInFlight = null;
+        }
+    }
+    async doPoll() {
+        const pollId = ++this.pollCount;
+        const startedAt = Date.now();
+        console.info(`[IOSWdaWatchdog] poll#${pollId} start`);
+        const onlineUdids = [];
+        // 1) Real iOS devices via xctrace
+        const discovered = await this.commandRunner.run(this.options.discoveryCommand, 15_000);
+        if (!discovered.ok) {
+            const stderr = discovered.stderr.trim();
+            console.warn(`[IOSWdaWatchdog] poll#${pollId} discovery command failed: ${stderr || "unknown error"}`);
+        }
+        else {
+            const onlineDevices = parseIOSDevices(discovered.stdout);
+            onlineUdids.push(...onlineDevices.map((item) => item.udid));
+        }
+        // 2) Booted simulators via simctl
+        const simctlResult = await this.commandRunner.run("xcrun simctl list devices booted", 10_000);
+        if (simctlResult.ok) {
+            const simDevices = parseBootedSimulators(simctlResult.stdout);
+            onlineUdids.push(...simDevices.map((item) => item.udid));
+        }
+        const uniqueUdids = [...new Set(onlineUdids)];
+        console.info(`[IOSWdaWatchdog] poll#${pollId} onlineDevices=${uniqueUdids.length}`);
+        const nextPortsByUdid = new Map();
+        const usedPorts = new Set();
+        const devicePlans = [];
+        if (uniqueUdids.length === 0) {
+            console.info(`[IOSWdaWatchdog] poll#${pollId} no online iOS devices`);
+        }
+        for (const udid of uniqueUdids) {
+            try {
+                const wdaPort = await this.resolvePortForDevice(udid, usedPorts);
+                // Reserve port immediately to avoid assigning the same port in this poll.
+                usedPorts.add(wdaPort);
+                devicePlans.push({ udid, wdaPort });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`[IOSWdaWatchdog] poll#${pollId} skip udid=${udid} reason=${message}`);
+            }
+        }
+        await Promise.all(devicePlans.map(async ({ udid, wdaPort }) => {
+            console.info(`[IOSWdaWatchdog] poll#${pollId} keepalive udid=${udid} port=${wdaPort}`);
+            const startCommand = renderTemplate(this.options.startCommandTemplate, udid, wdaPort);
+            const startResult = await this.commandRunner.run(startCommand, this.options.startupTimeoutMs);
+            if (!startResult.ok) {
+                const stderr = startResult.stderr.trim();
+                const stdout = startResult.stdout.trim();
+                const looksLikeInteractivePrompt = /password\s*:/i.test(`${stdout}\n${stderr}`);
+                if (looksLikeInteractivePrompt) {
+                    console.warn(`[IOSWdaWatchdog] poll#${pollId} start blocked by interactive prompt udid=${udid} port=${wdaPort} (Password prompt detected)`);
+                }
+                console.warn(`[IOSWdaWatchdog] poll#${pollId} start failed udid=${udid} port=${wdaPort} exitCode=${startResult.exitCode} err=${stderr.slice(0, 300)}`);
+                return;
+            }
+            nextPortsByUdid.set(udid, wdaPort);
+            console.info(`[IOSWdaWatchdog] poll#${pollId} keepalive ok udid=${udid} port=${wdaPort}`);
+        }));
+        this.portsByUdid.clear();
+        for (const [udid, port] of nextPortsByUdid.entries()) {
+            this.portsByUdid.set(udid, port);
+        }
+        await this.persistPortMapState();
+        const durationMs = Date.now() - startedAt;
+        console.info(`[IOSWdaWatchdog] poll#${pollId} done kept=${nextPortsByUdid.size} durationMs=${durationMs}`);
+    }
+    async resolvePortForDevice(udid, usedPorts) {
+        const { start, end } = normalizePortRange(this.options.portRangeStart, this.options.portRangeEnd);
+        const existing = this.portsByUdid.get(udid);
+        if (existing != null && existing >= start && existing <= end && !usedPorts.has(existing)) {
+            return existing;
+        }
+        for (let port = start; port <= end; port += 1) {
+            if (usedPorts.has(port))
+                continue;
+            if (!(await this.canBindPort(port)))
+                continue;
+            return port;
+        }
+        throw new Error(`[IOSWdaWatchdog] no available WDA port in range ${start}-${end}`);
+    }
+    async canBindPort(port) {
+        return new Promise((resolve) => {
+            const server = net.createServer();
+            server.unref();
+            server.once("error", () => resolve(false));
+            server.listen(port, "127.0.0.1", () => {
+                server.close(() => resolve(true));
+            });
+        });
+    }
+    async loadPortMapState() {
+        try {
+            const raw = await readFile(this.options.stateFilePath, "utf8");
+            const parsed = JSON.parse(raw);
+            const portsByUdid = parsed.portsByUdid;
+            if (!portsByUdid || typeof portsByUdid !== "object")
+                return;
+            this.portsByUdid.clear();
+            for (const [udid, value] of Object.entries(portsByUdid)) {
+                const port = Number(value);
+                if (!Number.isFinite(port) || port <= 0)
+                    continue;
+                this.portsByUdid.set(udid, Math.floor(port));
+            }
+        }
+        catch {
+            // Ignore missing or malformed state file, will rebuild on next poll.
+        }
+    }
+    async persistPortMapState() {
+        const payload = {
+            version: 1,
+            updatedAt: new Date().toISOString(),
+            portsByUdid: Object.fromEntries(Array.from(this.portsByUdid.entries()).sort(([a], [b]) => a.localeCompare(b))),
+        };
+        await mkdir(path.dirname(this.options.stateFilePath), { recursive: true });
+        await writeFile(this.options.stateFilePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    }
+}

package/dist/infrastructure/live-debug/LiveDebugSessionManager.js

@@ -0,0 +1,74 @@
+const DEFAULT_FRAME_INTERVAL_MS = 1000;
+const MIN_FRAME_INTERVAL_MS = 1;
+export class LiveDebugSessionManager {
+    frameSource;
+    inputInjector;
+    sessions = new Map();
+    constructor(frameSource, inputInjector) {
+        this.frameSource = frameSource;
+        this.inputInjector = inputInjector;
+    }
+    async start(params) {
+        await this.stop(params.sessionId);
+        const frameIntervalMs = this.normalizeFrameInterval(params.frameIntervalMs);
+        const session = {
+            sessionId: params.sessionId,
+            resourceId: params.resourceId,
+            frameIntervalMs,
+            pumping: false,
+            timer: setInterval(() => {
+                void this.tick(params.sessionId);
+            }, frameIntervalMs),
+            onFrame: params.onFrame,
+            onState: params.onState,
+        };
+        this.sessions.set(params.sessionId, session);
+        await session.onState("STARTED");
+        await this.tick(params.sessionId);
+    }
+    async stop(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        clearInterval(session.timer);
+        this.sessions.delete(sessionId);
+        await session.onState("STOPPED");
+    }
+    async sendInput(sessionId, input) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`live debug session not found: ${sessionId}`);
+        }
+        const result = await this.inputInjector.send(session.resourceId, input);
+        return { output: result.output, resourceId: session.resourceId };
+    }
+    normalizeFrameInterval(frameIntervalMs) {
+        if (!Number.isFinite(frameIntervalMs) || (frameIntervalMs ?? 0) <= 0) {
+            return DEFAULT_FRAME_INTERVAL_MS;
+        }
+        return Math.max(MIN_FRAME_INTERVAL_MS, Math.floor(frameIntervalMs));
+    }
+    async tick(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session || session.pumping)
+            return;
+        session.pumping = true;
+        try {
+            const frame = await this.frameSource.capture(session.resourceId);
+            await session.onFrame(frame);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            try {
+                await session.onState("FAILED", message);
+            }
+            catch (reportError) {
+                const reportMessage = reportError instanceof Error ? reportError.message : String(reportError);
+                console.error(`[LiveDebugSessionManager] tick failed and could not emit FAILED state: original=${message}; report=${reportMessage}`);
+            }
+        }
+        finally {
+            session.pumping = false;
+        }
+    }
+}

package/dist/infrastructure/live-debug/RuntimeLiveDebugAdapters.js

@@ -0,0 +1,19 @@
+import { asResourceId } from "../../shared-kernel/ids/index.js";
+export class RuntimeLiveDebugFrameSource {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async capture(resourceId) {
+        return this.runtime.captureLiveFrame(asResourceId(resourceId));
+    }
+}
+export class RuntimeLiveDebugInputInjector {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async send(resourceId, input) {
+        return this.runtime.sendLiveInput(asResourceId(resourceId), input);
+    }
+}