preflite 1.0.1

package/dist/mcp/server.js

@@ -0,0 +1,260 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { homedir } from "node:os";
+import { z } from "zod";
+import { AgentHttpClient } from "./agentHttpClient.js";
+import { AgentRuntimeManager } from "./agentRuntime.js";
+import { runDoctor } from "./doctor.js";
+import { writeEvidence } from "./evidence.js";
+import { startLiveViewer } from "./liveViewer.js";
+import { RunManager } from "./runManager.js";
+import { summarizeRun } from "./runSummary.js";
+import { readReport } from "./reportReader.js";
+import { loadPreflightUserConfig } from "./userConfig.js";
+import { compileVisualFlow, validateVisualFlow } from "./visual-flow/index.js";
+import { registerExplorationTools } from "./exploration/index.js";
+import { createMidsceneSessionFromResourceId, ensureIosWdaStarted } from "./exploration/tools-session.js";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export function createPreflightMcpServer(options = {}) {
+    const agentBaseUrl = options.agentBaseUrl ?? process.env.AGENT_BASE_URL ?? "http://127.0.0.1:18998";
+    const livePort = options.livePort ?? Number(process.env.MCP_LIVE_PORT ?? "18999");
+    const preflightHome = process.env.PREFLIGHT_HOME?.trim() || `${homedir()}/.preflight`;
+    const projectRoot = options.runtimeRoot ?? process.env.AGENT_RUNTIME_ROOT?.trim() ?? options.projectRoot ?? process.env.PROJECT_ROOT ?? process.cwd();
+    const client = new AgentHttpClient({ baseUrl: agentBaseUrl, token: options.agentToken ?? process.env.AGENT_HTTP_TOKEN });
+    const loadConfigEnv = async () => (await loadPreflightUserConfig()).env;
+    const runtime = new AgentRuntimeManager({ projectRoot, agentBaseUrl, client, env: process.env, runtimeRoot: options.runtimeRoot, loadConfigEnv });
+    const liveBaseUrl = `http://127.0.0.1:${livePort}`;
+    const runManager = new RunManager(client, liveBaseUrl);
+    let liveServerStarted;
+    const server = new McpServer({ name: "Preflight", version: "0.1.0" });
+    server.registerTool("agent_health", {
+        title: "Agent Health",
+        description: "Check whether the local automation-agent HTTP service is reachable.",
+    }, async () => jsonResult(await runtime.status()));
+    server.registerTool("start_agent", {
+        title: "Start Agent",
+        description: "Start or reuse the local automation-agent runtime required by Preflight MCP tools.",
+    }, async () => jsonResult(await runtime.ensureStarted()));
+    server.registerTool("stop_agent", {
+        title: "Stop Agent",
+        description: "Stop the automation-agent process started by this MCP server. Does not kill manually-started agents.",
+    }, async () => jsonResult(await runtime.stop()));
+    server.registerTool("start_ios_wda", {
+        title: "Start iOS WebDriverAgent",
+        description: "Start or ensure WebDriverAgent (WDA) is running on the specified iOS device. " +
+            "Required before exploration_start for iOS devices. Call this when doctor reports iOS WebDriverAgent as not running.",
+        inputSchema: {
+            resourceId: z.string().describe("iOS device resource ID (e.g., ios:xxx-xxx-xxx)"),
+        },
+    }, async ({ resourceId }) => {
+        await runtime.ensureStarted();
+        const configEnv = await loadConfigEnv();
+        const runtimeEnv = { ...configEnv };
+        return jsonResult(await ensureIosWdaStarted(resourceId, runtimeEnv, projectRoot));
+    });
+    server.registerTool("config_status", {
+        title: "Config Status",
+        description: "Show which Preflight user config file is loaded without exposing secret values.",
+    }, async () => {
+        const config = await loadPreflightUserConfig();
+        return jsonResult({
+            path: config.path ?? null,
+            keys: Object.keys(config.env).sort(),
+        });
+    });
+    server.registerTool("get_visual_flow_ir_rules", {
+        title: "Get Visual Flow IR Rules",
+        description: "Return the low-noise Visual Flow IR rules that the model should follow when generating test cases.",
+    }, async () => {
+        const text = await readFile(join(projectRoot, "docs", "visual-flow-ir-llm.md"), "utf8").catch(() => "");
+        return { content: [{ type: "text", text: `${VISUAL_FLOW_LLM_HARD_RULES}\n\n${text}` }] };
+    });
+    server.registerTool("validate_visual_flow", {
+        title: "Validate Visual Flow",
+        description: "Validate a generated visualFlow JSON before compiling or running it.",
+        inputSchema: {
+            visualFlow: z.record(z.unknown()),
+        },
+    }, async ({ visualFlow }) => jsonResult(validateVisualFlow(visualFlow)));
+    server.registerTool("doctor", {
+        title: "Doctor",
+        description: "Auto-start the local automation-agent, then check blocking dependencies (Midscene API key, adb, hdc, Xcode/xcrun, iproxy) and iOS WebDriverAgent health.",
+    }, async () => jsonResult(await runDoctor({
+        env: { ...process.env, ...(await loadConfigEnv()) },
+        agentHealth: async () => (await runtime.ensureStarted()).health ?? client.health(),
+    })));
+    server.registerTool("list_devices", {
+        title: "List Devices",
+        description: "List devices currently visible to the local automation-agent.",
+    }, async () => {
+        await runtime.ensureStarted();
+        return jsonResult(await client.listDevices());
+    });
+    server.registerTool("install_app", {
+        title: "Install App",
+        description: "Install an app package on a selected local device through automation-agent.",
+        inputSchema: {
+            resourceId: z.string().describe("Device resource id, for example android:serial or ios:udid."),
+            appRef: z.string().describe("Local path, file:// URL, or http(s) URL of the app package."),
+        },
+    }, async ({ resourceId, appRef }) => {
+        await runtime.ensureStarted();
+        return jsonResult(await client.installApp(resourceId, appRef));
+    });
+    server.registerTool("run_flow", {
+        title: "Run Visual Flow Test",
+        description: "Validate and compile a visualFlow JSON, then run it through the local automation-agent with live viewer support. " +
+            "IMPORTANT: MCP transport has a 60-second timeout. For multi-step flows (3+ steps), the test WILL NOT finish within this timeout. " +
+            "Strategy for long-running tests: " +
+            "(1) Set waitForCompletion to false — the tool returns immediately with a runId. " +
+            "(2) Then poll with watch_run (without waitForCompletion) until status shows completed/failed. " +
+            "Only set waitForCompletion: true for very short flows (1-2 steps) where total time is under 60s.",
+        inputSchema: {
+            platform: z.enum(["ANDROID", "IOS", "HARMONY"]),
+            visualFlow: z.record(z.unknown()),
+            resourceId: z.string().optional(),
+            appRef: z.string().optional(),
+            testIntent: z.string().optional(),
+            runtimeEnv: z.record(z.string()).optional(),
+            waitForCompletion: z.boolean().optional().describe("Set to false for multi-step flows (3+ steps) — returns immediately with a runId, then poll with watch_run. " +
+                "Set to true only for very short flows (1-2 steps) that finish within the MCP 60s transport timeout."),
+            timeoutMs: z.number().int().positive().optional().describe("Maximum wait time in milliseconds for the test to complete. " +
+                "Calculate as: number of visual flow steps × 60000 (1 minute per step). " +
+                "For example, a 5-step flow should set timeoutMs to 300000. " +
+                "Default is 120000 (2 minutes) which is only suitable for very short flows (1-2 steps). " +
+                "NOTE: Only effective when waitForCompletion is true. " +
+                "MCP transport has a 60s hard timeout — if timeoutMs exceeds 60s, " +
+                "use waitForCompletion: false and poll with watch_run instead."),
+        },
+    }, async (input) => {
+        await runtime.ensureStarted();
+        const parsed = validateVisualFlow(input.visualFlow);
+        if (!parsed.ok)
+            return jsonResult(parsed);
+        liveServerStarted ??= startLiveViewer(livePort, runManager).then((viewer) => {
+            runManager.setLiveBaseUrl(viewer.baseUrl);
+        });
+        await liveServerStarted;
+        const script = await compileVisualFlow(parsed.value);
+        const started = await runManager.startRun({
+            platform: input.platform,
+            script,
+            scriptKind: "midscene",
+            resourceId: input.resourceId,
+            appRef: input.appRef,
+            testIntent: input.testIntent,
+            runtimeEnv: { ...preflightRunDefaults(), ...(await loadConfigEnv()), ...input.runtimeEnv },
+            visualFlow: parsed.value,
+        });
+        if (!input.waitForCompletion)
+            return jsonResult({ ...started, visualFlow: parsed.value });
+        return jsonResult(await runManager.waitForRun(started.runId, input.timeoutMs ?? 120_000, 2_000));
+    });
+    server.registerTool("watch_run", {
+        title: "Watch Test Run",
+        description: "Refresh and summarize a test run. Use while the live viewer is open. " +
+            "For long-running tests that exceed the MCP transport timeout (60s): " +
+            "(1) Call run_flow with waitForCompletion: false to get a runId. " +
+            "(2) Call watch_run with minIntervalMs (e.g. 30000 = check every 30s) to poll. " +
+            "minIntervalMs blocks on the server side and polls the agent every 2s internally, " +
+            "so one call covers one full interval without consuming tokens on intermediate checks. " +
+            "Do NOT call run_flow again — that creates a duplicate run.",
+        inputSchema: {
+            runId: z.string(),
+            waitForCompletion: z.boolean().optional().describe("Set to true to block until the run finishes (respects timeoutMs). " +
+                "Omit or set to false for a lightweight status check — use this for polling."),
+            timeoutMs: z.number().int().positive().optional().describe("Maximum wait time in milliseconds. " +
+                "Based on the total number of steps in the original visual flow: steps × 60000. " +
+                "Default is 120000 (2 minutes). " +
+                "NOTE: Only effective when waitForCompletion is true. " +
+                "Due to MCP 60s transport timeout, prefer polling without waitForCompletion for long runs."),
+            minIntervalMs: z.number().int().positive().optional().describe("Block for at least this many milliseconds before returning. " +
+                "While blocked, the server polls the agent every 2s internally. " +
+                "If the run finishes early, returns immediately. " +
+                "Use 30000 for a ~30s polling cadence without consuming extra tokens " +
+                "on intermediate calls. Capped internally to 55000 to leave headroom " +
+                "for the 60s MCP transport timeout."),
+        },
+    }, async ({ runId, waitForCompletion, timeoutMs, minIntervalMs }) => {
+        await runtime.ensureStarted();
+        return jsonResult(waitForCompletion ? await runManager.waitForRun(runId, timeoutMs ?? 120_000, 2_000) : await runManager.watchRun(runId, minIntervalMs));
+    });
+    server.registerTool("cancel_run", {
+        title: "Cancel Test Run",
+        description: "Cancel a running test. Use this when the test is taking too long or you want to stop it early. " +
+            "After cancellation, poll watch_run to confirm the status becomes CANCELLED.",
+        inputSchema: {
+            runId: z.string(),
+            reason: z.string().optional().describe("Why the run was cancelled (e.g. 'test took too long', 'debug info collected')"),
+        },
+    }, async ({ runId, reason }) => {
+        await runtime.ensureStarted();
+        return jsonResult(await runManager.cancelRun(runId, "model", reason ?? "no reason given"));
+    });
+    server.registerTool("save_report", {
+        title: "Save Test Report",
+        description: "Save the test report for a completed or failed test run.",
+        inputSchema: {
+            runId: z.string(),
+        },
+    }, async ({ runId }) => {
+        await runtime.ensureStarted();
+        await runManager.watchRun(runId);
+        const run = runManager.getRun(runId);
+        if (!run)
+            throw new Error(`Unknown runId: ${runId}`);
+        const summary = summarizeRun(run);
+        return jsonResult(await writeEvidence({
+            outputRoot: preflightHome,
+            run: {
+                ...run,
+                status: summary.status,
+                failureAnalysis: summary.failureAnalysis,
+            },
+        }));
+    });
+    server.registerTool("read_report", {
+        title: "Read Test Report",
+        description: "Read a Midscene test run report directory and extract the operation path (what actually happened during the test). " +
+            "The reportDir is the path to the report directory containing N.execution.json files, " +
+            "typically found under ~/.preflight/midscene_run/report/. " +
+            "Returns the operation path with step-by-step details that the model can summarize.",
+        inputSchema: {
+            reportDir: z.string().describe("Absolute path to the Midscene report directory containing *.execution.json files"),
+        },
+    }, async ({ reportDir }) => {
+        const result = await readReport(reportDir);
+        return jsonResult(result);
+    });
+    registerExplorationTools(server, { client, loadConfigEnv, ensureAgentStarted: async () => { await runtime.ensureStarted(); }, createSessionFromMeta: createMidsceneSessionFromResourceId, projectRoot });
+    return server;
+}
+function jsonResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    };
+}
+function preflightRunDefaults() {
+    return {
+        MIDSCENE_OUTPUT_FORMAT: "html-and-external-assets",
+        MIDSCENE_RECORD_VIDEO_ENABLED: "1",
+        MIDSCENE_RECORD_VIDEO_PLAYBACK_RATE: "2",
+        MIDSCENE_RECORD_VIDEO_SCALE_WIDTH: "540",
+        MIDSCENE_RECORD_VIDEO_CRF: "32",
+        MIDSCENE_RECORD_VIDEO_PRESET: "fast",
+        MIDSCENE_RUN_TIMEOUT_MS: "1200000", // 20分钟，适配多步骤流程
+    };
+}
+const VISUAL_FLOW_LLM_HARD_RULES = `# Preflight Visual Flow IR hard rules
+
+- Use visualFlow JSON as the output format.
+- Variables declared by scriptVars, setVar, assignVar, or transformVar must be referenced only with interpolation syntax: {{varName}}, {{varName[0]}}, {{varName.1}}, or {{varName.length}}.
+- In prompt/value/expression fields, write declared variables with interpolation syntax. Example: "{{timeBefore}}和{{timeAfter}}不同".
+- If a value comes from a previous step, create it with setVar/assignVar/transformVar first, then reference it with {{}} in later steps.
+- Use aiAct for complex multi-step interactions that need visual planning. Describe the user goal and important constraints, then let the visual model plan the concrete taps/swipes/inputs.
+- Use setAIActContext to define cross-step handling for unexpected UI, for example "遇到权限弹窗请同意，营销弹窗请拒绝". This context is carried into later act operations, so the visual model can handle temporary popups as part of the normal action flow.
+- Use fixed sleep steps for page transitions, app launch, refresh, animations, and list updates, for example {"type":"sleep","ms":3000}.
+- Place assert steps only at critical verification points, usually the changed behavior or necessary regression checkpoint. Normal action failures already stop the run.
+- Make every step prompt self-contained. Each step is executed as an independent visual instruction, so include the necessary target, expected state, or comparison data inside that step.
+- Keep prompts concise and explicit. Provide the required information only; the visual model plans detailed interaction from clear short instructions.
+`;

package/dist/mcp/setup.js

@@ -0,0 +1,185 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { installLocalRuntime } from "./runtimeInstall.js";
+export async function setupLocalMcp(options) {
+    const agentBaseUrl = options.agentBaseUrl ?? "http://127.0.0.1:18998";
+    const livePort = options.livePort ?? 18999;
+    const shouldInstallRuntime = options.installRuntime ?? true;
+    const installedRuntime = shouldInstallRuntime
+        ? await installLocalRuntime({ projectRoot: options.projectRoot, runtimeRoot: options.runtimeRoot })
+        : undefined;
+    const runtimeRoot = installedRuntime?.runtimeRoot ?? options.runtimeRoot ?? process.env.AGENT_RUNTIME_ROOT?.trim();
+    const isRuntime = !!runtimeRoot;
+    const cursorConfigPath = join(options.projectRoot, ".cursor", "mcp.json");
+    const cursorRulePath = join(options.projectRoot, ".cursor", "rules", "preflight.mdc");
+    const skillPath = join(options.projectRoot, ".preflight", "skills", "preflight.md");
+    const codexSkillPath = join(homedir(), ".codex", "skills", "preflight", "SKILL.md");
+    const agentsSkillPath = join(homedir(), ".agents", "skills", "preflight", "SKILL.md");
+    const userConfigExamplePath = join(homedir(), ".preflight", "config.example.json");
+    const codexConfigPath = join(homedir(), ".codex", "config.toml");
+    await writeCursorMcpConfig(cursorConfigPath, options.projectRoot, agentBaseUrl, livePort, isRuntime, runtimeRoot);
+    await writeTextFile(cursorRulePath, cursorRuleText());
+    await writeTextFile(skillPath, skillText());
+    await writeTextFile(codexSkillPath, skillText());
+    await writeTextFile(agentsSkillPath, skillText());
+    await writeTextFile(userConfigExamplePath, userConfigExampleText());
+    await upsertCodexMcpConfig(codexConfigPath, options.projectRoot, agentBaseUrl, livePort, isRuntime, runtimeRoot);
+    return { cursorConfigPath, cursorRulePath, codexConfigPath, skillPath, codexSkillPath, agentsSkillPath, runtimeRoot, userConfigExamplePath };
+}
+async function writeCursorMcpConfig(path, projectRoot, agentBaseUrl, livePort, isRuntime, runtimeRoot) {
+    let existing = {};
+    try {
+        existing = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        existing = {};
+    }
+    const mcpServers = typeof existing.mcpServers === "object" && existing.mcpServers
+        ? { ...existing.mcpServers }
+        : {};
+    delete mcpServers["Preflight"];
+    if (isRuntime && runtimeRoot) {
+        const nodeBin = join(runtimeRoot, "node", "bin", "node");
+        const mcpEntry = join(runtimeRoot, "dist", "mcp", "cli.js");
+        existing.mcpServers = {
+            ...mcpServers,
+            "Preflight": {
+                command: nodeBin,
+                args: [mcpEntry, "serve"],
+                env: {
+                    AGENT_RUNTIME_ROOT: runtimeRoot,
+                    AGENT_BASE_URL: agentBaseUrl,
+                    MCP_LIVE_PORT: String(livePort),
+                    PREFLIGHT_HOME: join(homedir(), ".preflight"),
+                },
+            },
+        };
+    }
+    else {
+        existing.mcpServers = {
+            ...mcpServers,
+            "Preflight": {
+                command: "npm",
+                args: ["--silent", "--prefix", projectRoot, "run", "mcp", "--", "serve"],
+                env: {
+                    PROJECT_ROOT: projectRoot,
+                    AGENT_BASE_URL: agentBaseUrl,
+                    MCP_LIVE_PORT: String(livePort),
+                    PREFLIGHT_HOME: join(homedir(), ".preflight"),
+                },
+            },
+        };
+    }
+    await writeTextFile(path, `${JSON.stringify(existing, null, 2)}\n`);
+}
+async function upsertCodexMcpConfig(path, projectRoot, agentBaseUrl, livePort, isRuntime, runtimeRoot) {
+    let existing = "";
+    try {
+        existing = await readFile(path, "utf8");
+    }
+    catch {
+        existing = "";
+    }
+    await writeTextFile(path, mergeCodexMcpConfig(existing, projectRoot, agentBaseUrl, livePort, isRuntime, runtimeRoot));
+}
+export function mergeCodexMcpConfig(existing, projectRoot, agentBaseUrl, livePort, isRuntime = false, runtimeRoot) {
+    const block = isRuntime && runtimeRoot
+        ? `[mcp_servers.Preflight]
+command = ${tomlString(join(runtimeRoot, "node", "bin", "node"))}
+args = [${tomlString(join(runtimeRoot, "dist", "mcp", "cli.js"))}, "serve"]
+env = { AGENT_RUNTIME_ROOT = ${tomlString(runtimeRoot)}, AGENT_BASE_URL = ${tomlString(agentBaseUrl)}, MCP_LIVE_PORT = ${tomlString(String(livePort))}, PREFLIGHT_HOME = ${tomlString(join(homedir(), ".preflight"))} }
+`
+        : `[mcp_servers.Preflight]
+command = "npm"
+args = ["--silent", "--prefix", ${tomlString(projectRoot)}, "run", "mcp", "--", "serve"]
+env = { PROJECT_ROOT = ${tomlString(projectRoot)}, AGENT_BASE_URL = ${tomlString(agentBaseUrl)}, MCP_LIVE_PORT = ${tomlString(String(livePort))}, PREFLIGHT_HOME = ${tomlString(join(homedir(), ".preflight"))} }
+`;
+    const withoutOld = existing
+        .replace(/(?:^|\n)\[mcp_servers\.Preflight\]\n(?:(?!\[).*(?:\n|$))*/g, "\n")
+        .trimEnd();
+    return `${withoutOld}${withoutOld ? "\n\n" : ""}${block}`;
+}
+async function writeTextFile(path, text) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, text, "utf8");
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function cursorRuleText() {
+    return `---
+description: 使用本机 Preflight MCP 做移动端测试
+alwaysApply: false
+---
+
+当用户要求"测试""跑一下这次的改动"时：
+
+0. 必须先确认 Preflight MCP 工具已经注入当前会话。若看不到 \`doctor\`、\`list_devices\` 等工具，立即停止并提示用户重启 Codex/Cursor 或检查 MCP 配置；不要改用 shell、curl、npm script、读取本仓库源码等方式模拟 MCP。
+1. 只在用户当前项目中读取 git diff，总结本次改动影响的页面、流程、平台和风险点。
+2. 调用 \`start_agent\` 或 \`doctor\`；MCP 会自动拉起本地 automation-agent，不需要用户手动执行 \`npm run dev\`，也不需要 test-service/platform。
+3. 如果 Midscene API key 这类阻塞项失败，先把阻塞项说清楚，不要继续跑；如果 ffmpeg 或 scrcpy 缺失，说明本次不会生成 Android 操作录屏；\`AGENT_HTTP_TOKEN\` 不是本地 MCP 必填项。
+4. 如需确认配置来源，调用 \`config_status\`；模型 API key 应放在 \`~/.preflight/config.json\` 或 \`~/.preflight/config.yaml\`，不要写进 MCP 配置环境变量。
+5. 调用 \`list_devices\`，优先选择与改动相关的平台设备。
+6. 调用 \`get_visual_flow_ir_rules\`，按 IR 规范生成 visualFlow JSON。默认不要直接写 Midscene TS 脚本。
+7. 调用 \`validate_visual_flow\`。如果校验失败，按 message 修正 visualFlow 后再次校验。
+8. 生成最小测试用例：先覆盖改动点，再补必要回归。
+9. 如用户给了 app 包，先调用 \`install_app\`。
+10. 调用 \`run_flow\`，把返回的 liveUrl 明确给用户，让用户可以打开浏览器看实时执行。
+11. 执行中调用 \`watch_run\` 观察状态。失败时先判断是环境/设备、IR 用例步骤、agent runtime 还是真实业务问题。
+12. 如果失败原因是 IR 步骤不合理，只能调整 visualFlow 后重跑；不要读取或手写 Midscene TS 脚本。若是 Preflight 编译器/runtime 内部错误，停止并报告为工具缺陷。
+13. 最终调用 \`save_report\`，并在回复中给出测试报告、report/liveUrl 和 PASS/FAIL 结论。
+`;
+}
+function skillText() {
+    return `---
+name: preflight
+description: Use when the user wants to test mobile app changes, run visualFlow IR cases, inspect device/runtime blockers, or debug failures with live viewer output.
+---
+
+# Preflight
+
+Use the local Preflight MCP server to run mobile tests via visualFlow IR. The default path is visualFlow IR, not raw Midscene TypeScript.
+
+Hard gate:
+
+- This skill requires injected MCP tools named \`start_agent\`, \`doctor\`, \`config_status\`, \`list_devices\`, \`get_visual_flow_ir_rules\`, \`validate_visual_flow\`, \`run_flow\`, \`watch_run\`, and \`save_report\`.
+- If those tools are unavailable in the current conversation, stop immediately and tell the user to restart Codex/Cursor or check the MCP config. Do not use shell commands, curl, npm scripts, or direct reads of this repository to imitate the MCP tools.
+- When running from another project, inspect only that project's diff and files. Treat this repository as an implementation detail behind the MCP server.
+- Do not ask the user to start test-service/platform for local testing. The MCP server auto-starts automation-agent in local MCP mode; the only universal required secret is a Midscene-compatible model API key.
+- Preflight runs write report assets under \`~/.preflight/midscene_run/report/<reportName>/\`, including \`index.html\`, execution JSON, screenshots, and compressed recordings when ffmpeg and the platform recorder are available. Android recording uses scrcpy.
+- Read Midscene model configuration from \`~/.preflight/config.json\`, \`~/.preflight/config.yaml\`, or \`~/.preflight/config.yml\`. Do not ask the user to put API keys in Codex/Cursor MCP environment variables.
+- Do not write, inspect, or repair raw Midscene TypeScript scripts. If a run fails because the generated script cannot compile, go back to \`get_visual_flow_ir_rules\` + \`validate_visual_flow\` and adjust the visualFlow JSON. If the visualFlow validates but Preflight still compiles bad TypeScript, report a Preflight bug instead of reading this repository.
+
+Workflow:
+
+1. Inspect git diff and identify affected flows.
+2. Start or reuse the local runtime with \`start_agent\`; \`doctor\` also auto-starts it.
+3. Run \`doctor\`; stop on blocking failures such as missing model API key.
+4. If config is unclear, call \`config_status\`; it reports loaded config path and key names without exposing values.
+5. List devices with \`list_devices\`.
+6. Read \`get_visual_flow_ir_rules\` and generate visualFlow JSON, not raw Midscene TypeScript.
+7. Validate with \`validate_visual_flow\`; fix the JSON until validation passes.
+8. Install the app when an app package path is provided.
+9. Start the run with \`run_flow\` and show the returned liveUrl.
+10. Poll with \`watch_run\`.
+11. Analyze failures before retrying. Distinguish device/env failures, brittle IR steps, agent runtime failures, and real app bugs. For IR problems, revise visualFlow only; never switch to raw Midscene script repair.
+12. Save report with \`save_report\`.
+
+Reports are written under \`~/.preflight/midscene_run/report/<reportName>/\`.
+
+If Preflight MCP tools are missing, tell the user to restart Codex after checking \`~/.codex/config.toml\` contains \`[mcp_servers.Preflight]\`. Do not continue with a fallback path.
+`;
+}
+function userConfigExampleText() {
+    return `{
+  "env": {
+    "MIDSCENE_MODEL_BASE_URL": "https://ark.cn-beijing.volces.com/api/v3",
+    "MIDSCENE_MODEL_API_KEY": "replace-me",
+    "MIDSCENE_MODEL_NAME": "doubao-seed-2-0-lite-260215",
+    "MIDSCENE_MODEL_FAMILY": "doubao-seed",
+    "MIDSCENE_MODEL_REASONING_ENABLED": "false"
+  }
+}
+`;
+}

package/dist/mcp/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/userConfig.js

@@ -0,0 +1,45 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+const CONFIG_PATHS = [
+    join(homedir(), ".preflight", "config.json"),
+    join(homedir(), ".preflight", "config.yaml"),
+    join(homedir(), ".preflight", "config.yml"),
+];
+export async function loadPreflightUserConfig() {
+    for (const path of CONFIG_PATHS) {
+        const raw = await readFile(path, "utf8").catch(() => undefined);
+        if (raw === undefined)
+            continue;
+        const parsed = path.endsWith(".json") ? JSON.parse(raw) : parseYaml(raw);
+        return { path, env: flattenConfig(parsed) };
+    }
+    return { env: {} };
+}
+function flattenConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const root = value;
+    const envCandidate = root.env && typeof root.env === "object" && !Array.isArray(root.env) ? root.env : root;
+    const out = {};
+    for (const [rawKey, rawValue] of Object.entries(envCandidate)) {
+        const key = rawKey.trim();
+        if (!/^[A-Z][A-Z0-9_]*$/.test(key))
+            continue;
+        const text = scalarToString(rawValue);
+        if (text === undefined || !text.trim())
+            continue;
+        out[key] = text;
+    }
+    return out;
+}
+function scalarToString(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    return undefined;
+}