preflite 1.0.1

package/dist/mcp/reportReader.js

@@ -0,0 +1,157 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+// ── Parser ──────────────────────────────────────────────────────────
+/**
+ * Read a Midscene report directory (containing N.execution.json files)
+ * and extract the full operation path.
+ */
+export async function readReport(reportDir) {
+    if (!existsSync(reportDir)) {
+        return { success: false, reportDir, stepCount: 0, steps: [], error: `Report directory not found: ${reportDir}` };
+    }
+    const allFiles = await readdir(reportDir);
+    const execFiles = allFiles
+        .filter((f) => /^\d+\.execution\.json$/.test(f))
+        .sort((a, b) => {
+        const na = parseInt(a.match(/^(\d+)/)[1], 10);
+        const nb = parseInt(b.match(/^(\d+)/)[1], 10);
+        return na - nb;
+    });
+    if (execFiles.length === 0) {
+        return { success: false, reportDir, stepCount: 0, steps: [], error: `No *.execution.json files found in: ${reportDir}` };
+    }
+    const steps = [];
+    for (const file of execFiles) {
+        const content = await readFile(join(reportDir, file), "utf8");
+        const step = parseExecutionFile(content, file);
+        if (step)
+            steps.push(step);
+    }
+    return { success: true, reportDir, stepCount: steps.length, steps };
+}
+function parseExecutionFile(content, filename) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+    const exec = parsed.executions?.[0];
+    if (!exec)
+        return null;
+    // Extract name like "Terminate", "Launch", "Act - xxx", "Query - xxx", "Number - xxx", etc.
+    const rawName = exec.name ?? filename.replace(/\.execution\.json$/, "");
+    const tasks = exec.tasks ?? [];
+    const description = exec.description;
+    // Determine overall status
+    const hasFailedTask = tasks.some((t) => t.status === "failed");
+    const status = hasFailedTask ? "failed" : "finished";
+    // Extract AI thought from the Planning task
+    const planTask = tasks.find((t) => t.subType === "Plan");
+    const aiThought = planTask?.output?.thought ?? planTask?.thought;
+    // Extract all actions
+    const actions = [];
+    for (const task of tasks) {
+        if (task.type === "Action Space" && task.subType) {
+            const actionType = task.subType; // "Tap", "LongPress", "Terminate", "Launch"
+            const locate = task.param?.locate;
+            const action = { type: actionType };
+            if (locate?.description)
+                action.target = locate.description;
+            if (locate?.center)
+                action.coordinate = [locate.center[0], locate.center[1]];
+            if (locate?.rect) {
+                action.bbox = [locate.rect.left, locate.rect.top, locate.rect.width, locate.rect.height];
+            }
+            action.result = task.status === "finished" ? "success" : "failed";
+            actions.push(action);
+        }
+        // Also read actions from the Planning output
+        if (task.output?.actions) {
+            for (const act of task.output.actions) {
+                const existing = actions.find((a) => a.type === act.type && a.target === act.param?.locate?.description);
+                if (!existing && act.type) {
+                    actions.push({
+                        type: act.type,
+                        target: act.param?.locate?.description,
+                        coordinate: act.param?.locate?.center,
+                        bbox: act.param?.locate?.rect
+                            ? [act.param.locate.rect.left, act.param.locate.rect.top, act.param.locate.rect.width, act.param.locate.rect.height]
+                            : undefined,
+                        result: "planned",
+                    });
+                }
+            }
+        }
+        // Also extract locate elements for LongPress
+        if (task.subType === "Locate" && task.output?.element) {
+            // Already captured by the Plan output actions
+        }
+    }
+    // Extract data from Insight tasks (Query / Number / Boolean / Assert)
+    let extractedData = undefined;
+    let error = undefined;
+    for (const task of tasks) {
+        if (task.type === "Insight") {
+            if (task.subType === "Query" || task.subType === "Number" || task.subType === "Boolean") {
+                extractedData = task.output;
+            }
+            if (task.subType === "Assert") {
+                if (task.status === "failed") {
+                    error = task.errorMessage ?? "Assertion failed";
+                }
+                extractedData = task.output;
+            }
+        }
+        if (task.status === "failed" && task.errorMessage) {
+            error = task.errorMessage;
+        }
+    }
+    // Build summary from the log/output
+    let summary;
+    if (description) {
+        summary = description;
+    }
+    else if (rawName.startsWith("Terminate")) {
+        summary = `关闭应用 ${tasks.find((t) => t.subType === "Terminate")?.param ?? ""}`;
+    }
+    else if (rawName.startsWith("Launch")) {
+        summary = `启动应用 ${tasks.find((t) => t.subType === "Launch")?.param ?? ""}`;
+    }
+    else if (rawName.startsWith("Act -")) {
+        summary = rawName.slice(5).trim();
+        const actionLog = planTask?.output?.log;
+        if (actionLog)
+            summary = actionLog;
+        if (status === "failed")
+            summary += " (失败)";
+    }
+    else if (rawName.startsWith("Query -")) {
+        summary = `读取数据: ${JSON.stringify(extractedData ?? "")}`;
+    }
+    else if (rawName.startsWith("Number -")) {
+        summary = `计数结果: ${JSON.stringify(extractedData ?? "")}`;
+    }
+    else if (rawName.startsWith("Boolean -")) {
+        summary = `条件判断: ${JSON.stringify(extractedData ?? "")}`;
+    }
+    else if (rawName.startsWith("Assert -")) {
+        const assertResult = status === "finished" ? "通过" : "失败";
+        summary = `断言 ${assertResult}: ${rawName.slice(7).trim()}`;
+    }
+    else if (rawName.startsWith("Log -")) {
+        summary = `记录日志: ${description ?? ""}`;
+    }
+    else {
+        summary = rawName;
+    }
+    // If there's an error, append it to summary
+    if (error) {
+        summary += ` | 错误: ${error.slice(0, 200)}`;
+    }
+    // Derive step index from filename
+    const stepIndex = parseInt(filename.match(/^(\d+)/)?.[1] ?? "0", 10);
+    return { stepIndex, name: rawName, status, summary, aiThought, actions, extractedData, error };
+}

package/dist/mcp/runManager.js

@@ -0,0 +1,161 @@
+import { mkdir, appendFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { buildFlowStepView, extractFlowStepEventsFromRun } from "./flowStepEvents.js";
+import { summarizeRun } from "./runSummary.js";
+/**
+ * MCP transport has a 60s hard timeout.  watchRun blocking must leave
+ * enough headroom so the response can be delivered before the transport
+ * closes and kills the MCP server process.  55s is the safe ceiling.
+ */
+const MAX_BLOCK_MS = 45_000;
+const TERMINAL = new Set(["SUCCESS", "FAILED", "CANCELLED"]);
+const PREFLIGHT_HOME = process.env.PREFLIGHT_HOME?.trim() || `${homedir()}/.preflight`;
+function runLogPath(runId) {
+    return join(PREFLIGHT_HOME, "runs", runId, "run.log");
+}
+async function logRun(runId, event, detail) {
+    try {
+        const dir = join(PREFLIGHT_HOME, "runs", runId);
+        await mkdir(dir, { recursive: true });
+        const ts = new Date().toISOString();
+        await appendFile(join(dir, "run.log"), `${ts} [${event}] ${detail}\n`, "utf8");
+    }
+    catch {
+        // 日志写失败不影响主流程
+    }
+}
+/** 将 RunState 完整快照写入 state.json，重启后仍可查看 */
+async function snapshotRun(run) {
+    try {
+        const dir = join(PREFLIGHT_HOME, "runs", run.runId);
+        await writeFile(join(dir, "state.json"), JSON.stringify(run, null, 2), "utf8");
+    }
+    catch {
+        // 快照写失败不影响主流程
+    }
+}
+export class RunManager {
+    client;
+    liveBaseUrl;
+    runs = new Map();
+    constructor(client, liveBaseUrl) {
+        this.client = client;
+        this.liveBaseUrl = liveBaseUrl;
+    }
+    setLiveBaseUrl(liveBaseUrl) {
+        this.liveBaseUrl = liveBaseUrl;
+    }
+    async startRun(input) {
+        const runId = timestampId();
+        const taskId = `mcp-${runId}`;
+        const now = new Date().toISOString();
+        const liveUrl = `${this.liveBaseUrl.replace(/\/$/, "")}/runs/${encodeURIComponent(runId)}/live`;
+        const run = {
+            runId,
+            taskId,
+            platform: input.platform,
+            resourceId: input.resourceId,
+            appRef: input.appRef,
+            testIntent: input.testIntent,
+            script: input.script,
+            visualFlow: input.visualFlow,
+            createdAt: now,
+            updatedAt: now,
+            liveUrl,
+            events: [],
+            artifacts: [],
+        };
+        this.runs.set(runId, run);
+        logRun(runId, "START", `platform=${input.platform}, testIntent=${input.testIntent ?? ""}, ${input.resourceId ? `resourceId=${input.resourceId}` : ""}`);
+        await this.client.createTask({
+            taskId,
+            requiredPlatform: input.platform,
+            script: input.script,
+            scriptKind: input.scriptKind,
+            resourceId: input.resourceId,
+            runtimeEnv: input.runtimeEnv,
+        });
+        await this.refreshRun(runId);
+        snapshotRun(this.mustGet(runId));
+        return summarizeRun(this.mustGet(runId));
+    }
+    async cancelRun(runId, source, detail) {
+        const run = this.mustGet(runId);
+        const now = new Date().toISOString();
+        run.termination = { source, detail, timestamp: now };
+        run.updatedAt = now;
+        logRun(runId, "CANCEL", `source=${source}, detail=${detail}`);
+        snapshotRun(run);
+        return summarizeRun(run);
+    }
+    async watchRun(runId, minIntervalMs) {
+        await this.refreshRun(runId);
+        const summary = summarizeRun(this.mustGet(runId));
+        if (TERMINAL.has(summary.status)) {
+            logRun(runId, "END", `status=${summary.status}, failure=${summary.failureAnalysis.category}`);
+            return summary;
+        }
+        if (!minIntervalMs || minIntervalMs <= 0) {
+            return summary;
+        }
+        // 安全上限：MCP transport 有 60s 硬超时，阻塞必须留余量
+        const safeInterval = Math.min(minIntervalMs, MAX_BLOCK_MS);
+        const deadline = Date.now() + safeInterval;
+        while (Date.now() < deadline) {
+            await sleep(Math.min(2000, deadline - Date.now()));
+            await this.refreshRun(runId);
+            const latest = summarizeRun(this.mustGet(runId));
+            if (TERMINAL.has(latest.status)) {
+                logRun(runId, "END", `status=${latest.status}, failure=${latest.failureAnalysis.category}`);
+                return latest;
+            }
+        }
+        await this.refreshRun(runId);
+        return summarizeRun(this.mustGet(runId));
+    }
+    getRun(runId) {
+        return this.runs.get(runId);
+    }
+    listRuns() {
+        return [...this.runs.values()].sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    }
+    async waitForRun(runId, timeoutMs, pollIntervalMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const summary = await this.watchRun(runId);
+            if (TERMINAL.has(summary.status))
+                return summary;
+            await sleep(pollIntervalMs);
+        }
+        return this.watchRun(runId);
+    }
+    async refreshRun(runId) {
+        const run = this.mustGet(runId);
+        const [task, events, artifacts] = await Promise.all([
+            this.client.getTask(run.taskId),
+            this.client.listEvents(run.taskId).catch(() => run.events),
+            this.client.listArtifacts(run.taskId).catch(() => run.artifacts),
+        ]);
+        run.task = task ?? run.task;
+        run.events = events;
+        run.artifacts = artifacts;
+        run.flowStepView = buildFlowStepView(run.visualFlow, extractFlowStepEventsFromRun(run));
+        run.updatedAt = new Date().toISOString();
+        snapshotRun(run);
+    }
+    mustGet(runId) {
+        const run = this.runs.get(runId);
+        if (!run)
+            throw new Error(`Unknown runId: ${runId}`);
+        return run;
+    }
+}
+function timestampId() {
+    const stamp = new Date().toISOString().replaceAll(/[-:]/g, "").replace(/\..+$/, "");
+    return `${stamp}-${randomUUID().slice(0, 8)}`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/mcp/runSummary.js

@@ -0,0 +1,72 @@
+const TERMINAL_STATUSES = new Set(["SUCCESS", "FAILED", "CANCELLED"]);
+export function summarizeRun(run) {
+    const eventStatus = [...run.events]
+        .reverse()
+        .map((event) => event.payload.status)
+        .find((status) => typeof status === "string");
+    const status = run.task?.status ?? eventStatus ?? "UNKNOWN";
+    const failureText = status === "FAILED" ? run.task?.message ?? latestEventMessage(run) ?? "" : "";
+    return {
+        runId: run.runId,
+        taskId: run.taskId,
+        status,
+        liveUrl: run.liveUrl,
+        updatedAt: run.updatedAt,
+        artifacts: run.artifacts,
+        failureAnalysis: TERMINAL_STATUSES.has(status) ? analyzeRunFailure(failureText, status) : runningAnalysis(status),
+    };
+}
+export function analyzeRunFailure(message, status = "FAILED") {
+    if (status === "SUCCESS") {
+        return { category: "none", summary: "No failure.", recommendation: "No retry needed." };
+    }
+    if (status === "CANCELLED") {
+        return {
+            category: "agent-or-runtime",
+            summary: "The run was cancelled before completion.",
+            recommendation: "Start a new run after confirming the device is free.",
+        };
+    }
+    const lower = message.toLowerCase();
+    // timeout must be checked before adb — the Agent's error message often
+    // includes ADB debug log lines (e.g. "dbug ADB Running 'adb -H ...'")
+    // concatenated with a timeout suffix.  If "adb" is checked first these
+    // timeouts are misclassified as device-or-environment.
+    if (lower.includes("timeout") || lower.includes("api key") || lower.includes("midscene") || lower.includes("spawn")) {
+        return {
+            category: "agent-or-runtime",
+            summary: message || "The run failed in the agent or Midscene runtime.",
+            recommendation: "Run doctor, fix blocking runtime checks, then rerun.",
+        };
+    }
+    if (lower.includes("adb") ||
+        lower.includes("hdc") ||
+        lower.includes("wda") ||
+        lower.includes("iproxy") ||
+        lower.includes("device offline") ||
+        lower.includes("no device")) {
+        return {
+            category: "device-or-environment",
+            summary: message || "The run failed in device or environment setup.",
+            recommendation: "Check the device connection, adb/hdc/WDA availability, then rerun the same test.",
+        };
+    }
+    return {
+        category: "test-or-app-behavior",
+        summary: message || "The run failed while executing the generated test steps.",
+        recommendation: "Inspect the live viewer/report, adjust the test steps if they were too brittle, or file a product bug if the app behavior is wrong.",
+    };
+}
+function runningAnalysis(status) {
+    return {
+        category: "none",
+        summary: `Run is still ${status}.`,
+        recommendation: "Continue watching the run before changing the test case.",
+    };
+}
+function latestEventMessage(run) {
+    return [...run.events]
+        .reverse()
+        .map((event) => event.payload.message)
+        .find((message) => typeof message === "string");
+}

package/dist/mcp/runtimeInstall.js

@@ -0,0 +1,44 @@
+import { spawn } from "node:child_process";
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export async function installLocalRuntime(options) {
+    const runtimeRoot = options.runtimeRoot ?? join(homedir(), ".preflight", "runtime");
+    await runNpm(["run", "build"], options.projectRoot);
+    await rm(runtimeRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 500 });
+    await mkdir(runtimeRoot, { recursive: true });
+    await mkdir(join(runtimeRoot, "node", "bin"), { recursive: true });
+    await cp(process.execPath, join(runtimeRoot, "node", "bin", "node"));
+    await cp(join(options.projectRoot, "dist"), join(runtimeRoot, "dist"), { recursive: true });
+    await cp(join(options.projectRoot, "package.json"), join(runtimeRoot, "package.json"));
+    await cp(join(options.projectRoot, "package-lock.json"), join(runtimeRoot, "package-lock.json"));
+    await cp(join(options.projectRoot, "scripts"), join(runtimeRoot, "scripts"), { recursive: true }).catch(() => { });
+    await mkdir(join(runtimeRoot, "docs"), { recursive: true });
+    await cp(join(options.projectRoot, "docs", "visual-flow-ir-llm.md"), join(runtimeRoot, "docs", "visual-flow-ir-llm.md"));
+    await runNpm(["ci", "--omit=dev"], runtimeRoot);
+    await writeFile(join(runtimeRoot, "preflight-runtime.json"), `${JSON.stringify({ installedAt: new Date().toISOString(), source: options.projectRoot }, null, 2)}\n`, "utf8");
+    return {
+        runtimeRoot,
+        nodeBin: join(runtimeRoot, "node", "bin", "node"),
+        mcpEntry: join(runtimeRoot, "dist", "mcp", "cli.js"),
+    };
+}
+function run(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, stdio: "inherit" });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${command} ${args.join(" ")} failed with exit code ${code ?? "unknown"}`));
+        });
+    });
+}
+function runNpm(args, cwd) {
+    const npmExecPath = process.env.npm_execpath;
+    if (npmExecPath) {
+        return run(process.execPath, [npmExecPath, ...args], cwd);
+    }
+    return run("npm", args, cwd);
+}