@m2canvas/connect 0.3.1 → 0.5.0

package/dist/bridge/precheck.js

@@ -0,0 +1,149 @@
+/**
+ * 会话前预检：登录状态 + m2 MCP 状态，并给出页面可展示的下一步（命令或手动步骤）。
+ *
+ * 为什么要预检：m2 没配置、没授权、还没连上时，ACP 里没有任何信号，agent 只会说「没有这个工具」（PoC 报告 §4.1）。
+ *
+ * 边界：
+ * - 只运行不修改配置的状态命令（status、mcp list；注意 `claude mcp list` 会启动用户配置的 stdio MCP 做健康检查）；bridge 不替用户登录、不替用户授权，只返回命令让用户在自己的终端执行。
+ * - 不调用 ACP authenticate 探测登录：Qoder 未登录时 60 秒不响应（PoC 报告 §2.5）。
+ * - `qodercli mcp list` 会以 `mcp-test-client` 身份连 M2，服务端判成 mcp、不进项目房间（总控 §6）：页面不要把这次连接当成 Qoder 会话。
+ * - Cursor 的 m2 授权按目录保存，mcp list 与授权命令都必须在会话 cwd 下执行。
+ * - Codex 的预检与授权都用适配器自带的 codex（调用方保证适配器已就绪）。
+ */
+import { join } from 'node:path';
+import { findM2Names } from './m2-config.js';
+import { CODEX_BIN_LINK, CODEX_SCRIPT } from './adapters.js';
+import { combinedOutput } from './exec.js';
+import { parseClaudeAuthStatus, parseClaudeMcpList, parseCodexLoginStatus, parseCodexMcpListJson, parseCursorMcpList, parseCursorStatus, parseOpencodeMcpList, parseQoderMcpList, parseQoderStatus, tail, } from './precheck-parse.js';
+export const PRECHECK_TIMEOUT_MS = 45_000;
+export function shellQuote(value) {
+    return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function commandHint(command, args, cwd = null) {
+    const line = [command, ...args].map(shellQuote).join(' ');
+    return { command, args, cwd, display: cwd ? `cd ${shellQuote(cwd)} && ${line}` : line };
+}
+const run = (command, args) => ({ kind: 'command', command: commandHint(command, args) });
+/** 执行失败（启动不了 / 超时）时的统一兜底：报 unknown 并带上原因，不猜 */
+function failed(result) {
+    if (result.error && result.code === null)
+        return tail(combinedOutput(result));
+    return null;
+}
+function toLogin(parse, next) {
+    return { state: parse.state, next: parse.state === 'logged_out' || parse.state === 'unknown' ? next : null, raw: parse.raw };
+}
+function toM2(parse, nextFor) {
+    const next = parse.state === 'not_configured' ? { kind: 'configure' } : nextFor(parse.state, parse.entry ?? 'm2');
+    return { state: parse.state, entry: parse.entry, next, raw: parse.raw };
+}
+function plan(agent, deps) {
+    const cmd = agent.command ?? agent.path ?? agent.id;
+    const path = agent.path ?? cmd;
+    switch (agent.id) {
+        case 'claude':
+            return {
+                exec: { command: path, prefix: [] },
+                login: { args: ['auth', 'status', '--json'], parse: (r) => parseClaudeAuthStatus(r.stdout, r.code), next: run(cmd, ['auth', 'login']) },
+                m2: {
+                    args: ['mcp', 'list'],
+                    parse: (r) => parseClaudeMcpList(combinedOutput(r), r.code),
+                    next: (state, entry) => state === 'needs_auth'
+                        ? run(cmd, ['mcp', 'login', entry])
+                        : state === 'needs_enable'
+                            ? { kind: 'manual', text: `Run claude in ${deps.cwd} and approve the project MCP server "${entry}".` }
+                            : null,
+                },
+            };
+        case 'codex': {
+            const dir = deps.adapters.installDir('codex');
+            const display = join(dir, CODEX_BIN_LINK);
+            return {
+                exec: { command: deps.nodePath, prefix: [join(dir, CODEX_SCRIPT)] },
+                login: { args: ['login', 'status'], parse: (r) => parseCodexLoginStatus(combinedOutput(r), r.code), next: run(display, ['login']) },
+                m2: {
+                    args: ['mcp', 'list', '--json'],
+                    parse: (r) => parseCodexMcpListJson(r.stdout, r.code),
+                    next: (state, entry) => state === 'needs_auth' || state === 'unverified'
+                        ? run(display, ['mcp', 'login', entry])
+                        : state === 'needs_enable'
+                            ? { kind: 'manual', text: `Set enabled = true under [mcp_servers.${entry}] in your Codex config.toml.` }
+                            : null,
+                },
+            };
+        }
+        case 'cursor':
+            return {
+                exec: { command: path, prefix: [] },
+                login: { args: ['status'], parse: (r) => parseCursorStatus(combinedOutput(r)), next: run(cmd, ['login']) },
+                m2: {
+                    args: ['mcp', 'list'],
+                    parse: (r) => {
+                        const found = findM2Names([join(deps.cwd, '.cursor', 'mcp.json'), join(deps.home, '.cursor', 'mcp.json')]);
+                        // 配置文件坏了又找不到 m2：不能报 not_configured（会引导用户去重复添加），报 unknown 并说明是哪个文件
+                        if (found.names.length === 0 && found.unreadable.length > 0) {
+                            return { state: 'unknown', entry: null, raw: tail(`Could not read Cursor MCP config: ${found.unreadable.join('; ')}`) };
+                        }
+                        return parseCursorMcpList(combinedOutput(r), found.names, r.code);
+                    },
+                    next: (state, entry) => state === 'needs_auth'
+                        ? { kind: 'command', command: commandHint(cmd, ['mcp', 'login', entry], deps.cwd) }
+                        : state === 'needs_enable'
+                            ? { kind: 'command', command: commandHint(cmd, ['mcp', 'enable', entry], deps.cwd) }
+                            : null,
+                },
+            };
+        case 'opencode':
+            return {
+                exec: { command: path, prefix: [] },
+                // 不登录也能用自带的免费模型（PoC 报告 §2.4），不检查
+                login: { args: null, parse: () => ({ state: 'not_required', raw: null }), next: null },
+                m2: {
+                    args: ['mcp', 'list'],
+                    parse: (r) => parseOpencodeMcpList(combinedOutput(r), r.code),
+                    next: (state, entry) => state === 'needs_auth'
+                        ? run(cmd, ['mcp', 'auth', entry])
+                        : state === 'needs_enable'
+                            ? { kind: 'manual', text: `Set "enabled": true for "${entry}" in your OpenCode config.` }
+                            : null,
+                },
+            };
+        case 'qoder':
+            return {
+                exec: { command: path, prefix: [] },
+                login: { args: ['status'], parse: (r) => parseQoderStatus(combinedOutput(r)), next: run(cmd, ['login']) },
+                m2: {
+                    args: ['mcp', 'list'],
+                    parse: (r) => parseQoderMcpList(combinedOutput(r), r.code),
+                    // qodercli 没有 mcp login 子命令，只能在交互界面里授权
+                    next: (state, entry) => (state === 'needs_auth' ? { kind: 'manual', text: `Run qodercli, type /mcp, choose "${entry}" and authorize it.` } : null),
+                },
+            };
+    }
+}
+async function runStep(deps, p, args) {
+    return deps.exec(p.exec.command, [...p.exec.prefix, ...args], { env: deps.env, cwd: deps.cwd, timeoutMs: PRECHECK_TIMEOUT_MS });
+}
+export async function precheckM2(agent, deps) {
+    const p = plan(agent, deps);
+    const result = await runStep(deps, p, p.m2.args);
+    const failure = failed(result);
+    return toM2(failure ? { state: 'unknown', entry: null, raw: failure } : p.m2.parse(result), p.m2.next);
+}
+/** 调用方保证 agent 已安装；适配器类 agent 的适配器已就绪 */
+export async function precheckAgent(agent, deps, now = () => new Date()) {
+    const p = plan(agent, deps);
+    const loginArgs = p.login.args;
+    const [loginResult, m2] = await Promise.all([
+        loginArgs ? runStep(deps, p, loginArgs) : Promise.resolve(null),
+        precheckM2(agent, deps),
+    ]);
+    let login;
+    if (!loginResult)
+        login = p.login.parse({ code: 0, signal: null, stdout: '', stderr: '', timedOut: false, error: null });
+    else {
+        const failure = failed(loginResult);
+        login = failure ? { state: 'unknown', raw: failure } : p.login.parse(loginResult);
+    }
+    return { agent: agent.id, login: toLogin(login, p.login.next), m2, checkedAt: now().toISOString() };
+}

package/dist/bridge/processes.js

@@ -0,0 +1,212 @@
+/**
+ * agent 子进程：拉起、stdio ↔ 行 的转发、按进程组清理。
+ *
+ * 边界：
+ * - 不解析 ACP。stdout 按 \n 切行（去掉行尾 \r、跳过空行），每行原样交给 onLine；写入时补一个 \n。
+ * - 每个 agent 是独立进程组（POSIX detached）：适配器会再拉起 agent 本体（claude-agent-acp → claude、codex-acp → codex），
+ *   只杀直接子进程会留下孙进程。停止 = 对整组 SIGTERM，宽限期后仍在就 SIGKILL。
+ * - 进程属于拉起它的连接（ownerId）：连接关闭时调用方对该 owner 调 stopOwner。bridge 退出时 killAllNow 同步清理，
+ *   这条也挂在 process 'exit' 钩子上（覆盖 process.exit 与未捕获异常）；SIGINT / SIGTERM / SIGHUP 不触发 'exit'，由 main.ts 显式处理。
+ * - Windows 的进程树清理用 taskkill /T /F，未实测（一期只在 macOS 实测）。
+ */
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+export const MAX_PROCESSES_PER_OWNER = 5;
+export const MAX_PROCESSES_TOTAL = 10;
+export const KILL_GRACE_MS = 3_000;
+/** 单行累计超过这个长度仍无换行：认为 agent 输出异常，停止进程（防止内存无限增长） */
+export const MAX_LINE_CHARS = 64 * 1024 * 1024;
+const STDERR_KEEP = 8 * 1024;
+const STDERR_REPORT = 4 * 1024;
+export class ProcessError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function signalGroup(child, signal) {
+    if (child.pid === undefined)
+        return;
+    try {
+        if (process.platform === 'win32') {
+            spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+        }
+        else {
+            process.kill(-child.pid, signal);
+        }
+    }
+    catch (error) {
+        // ESRCH = 进程组已经不在了，预期内。其他错误（如 EPERM）不应出现：不抛（这里在退出回调里，抛出会让 bridge 崩溃），但要看得见
+        if (error.code !== 'ESRCH') {
+            console.warn(`Could not signal agent process group ${child.pid}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+export class ProcessManager {
+    options;
+    processes = new Map();
+    /** 已调用 spawn、还没等到 'spawn' 事件的进程（按 owner 计）：也要计入上限，否则同一批并发的 start 能突破上限 */
+    starting = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    countFor(ownerId) {
+        let count = this.starting.get(ownerId) ?? 0;
+        for (const managed of this.processes.values())
+            if (managed.ownerId === ownerId)
+                count++;
+        return count;
+    }
+    totalCount() {
+        let starting = 0;
+        for (const count of this.starting.values())
+            starting += count;
+        return this.processes.size + starting;
+    }
+    adjustStarting(ownerId, delta) {
+        const next = (this.starting.get(ownerId) ?? 0) + delta;
+        if (next > 0)
+            this.starting.set(ownerId, next);
+        else
+            this.starting.delete(ownerId);
+    }
+    /** 等到子进程真正启动（'spawn' 事件）才返回，启动失败（如 ENOENT）以 ProcessError 拒绝 */
+    start(ownerId, agent, launch) {
+        if (this.countFor(ownerId) >= (this.options.maxPerOwner ?? MAX_PROCESSES_PER_OWNER)) {
+            return Promise.reject(new ProcessError('too_many_processes', 'too many agent processes for this page'));
+        }
+        if (this.totalCount() >= (this.options.maxTotal ?? MAX_PROCESSES_TOTAL)) {
+            return Promise.reject(new ProcessError('too_many_processes', 'too many agent processes on this bridge'));
+        }
+        const id = randomUUID();
+        this.adjustStarting(ownerId, 1);
+        let child;
+        try {
+            child = spawn(launch.command, launch.args, {
+                cwd: this.options.cwd,
+                env: this.options.env,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                detached: process.platform !== 'win32',
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            // 参数非法等同步异常（例如 cwd 不存在在部分平台上）：同样按启动失败处理，并把计数还回去
+            this.adjustStarting(ownerId, -1);
+            return Promise.reject(new ProcessError('spawn_failed', `${launch.command}: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        const managed = { id, ownerId, agent, child, stopping: false, tooLarge: false, stderr: '', killTimer: null };
+        return new Promise((resolve, reject) => {
+            let started = false;
+            child.once('spawn', () => {
+                started = true;
+                this.adjustStarting(ownerId, -1);
+                this.processes.set(id, managed);
+                this.wire(managed);
+                resolve(id);
+            });
+            // 用 on 而不是 once：启动后的 error 事件（极少见）没有监听器会让整个 bridge 崩溃；启动后的错误由 'close' 上报
+            child.on('error', (error) => {
+                if (started)
+                    return;
+                this.adjustStarting(ownerId, -1);
+                reject(new ProcessError('spawn_failed', `${launch.command}: ${error.message}`));
+            });
+        });
+    }
+    wire(managed) {
+        const { child } = managed;
+        let buffer = '';
+        child.stdin?.on('error', () => undefined); // agent 先退出时写入会 EPIPE，退出事件另行上报
+        child.stdout?.setEncoding('utf8');
+        const maxLine = this.options.maxLineChars ?? MAX_LINE_CHARS;
+        child.stdout?.on('data', (chunk) => {
+            // 已判定输出异常、正在停止：剩下的数据一律丢弃，不再切行、不再累积（否则超长行的尾巴会被当成一行发出去）
+            if (managed.tooLarge)
+                return;
+            buffer += chunk;
+            let index;
+            while ((index = buffer.indexOf('\n')) >= 0) {
+                this.emitLine(managed, buffer.slice(0, index));
+                buffer = buffer.slice(index + 1);
+            }
+            if (buffer.length > maxLine) {
+                managed.tooLarge = true;
+                buffer = '';
+                this.stopManaged(managed);
+            }
+        });
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', (chunk) => {
+            managed.stderr = (managed.stderr + chunk).slice(-STDERR_KEEP);
+            this.options.onStderr?.(managed.id, managed.agent, chunk);
+        });
+        // 'close' 在 stdio 全部关闭后触发，保证最后几行先于退出事件送出
+        child.on('close', (code, signal) => {
+            if (buffer.length > 0 && !managed.tooLarge)
+                this.emitLine(managed, buffer);
+            buffer = '';
+            if (managed.killTimer)
+                clearTimeout(managed.killTimer);
+            this.processes.delete(managed.id);
+            // 进程组里可能还有孙进程（直接子进程退出不代表整组退出）。POSIX 下组里还有成员时 pgid 不会被复用，组空了是 ESRCH；
+            // Windows 没有进程组，taskkill 只能按 PID 找树，而进程已退出后 PID 可能很快被复用 —— 那里不做这一步，以免误杀无关进程
+            if (process.platform !== 'win32')
+                signalGroup(child, 'SIGKILL');
+            this.options.onExit(managed.ownerId, {
+                processId: managed.id,
+                agent: managed.agent,
+                code,
+                signal,
+                reason: managed.tooLarge ? 'output_too_large' : managed.stopping ? 'stopped' : 'exited',
+                stderrTail: managed.stderr.slice(-STDERR_REPORT),
+            });
+        });
+    }
+    emitLine(managed, raw) {
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        if (line.trim().length > 0)
+            this.options.onLine(managed.ownerId, managed.id, line);
+    }
+    /** 写入一行（调用方已保证不含换行）。进程不存在或不属于该 owner 时返回 false */
+    write(ownerId, processId, line) {
+        const managed = this.processes.get(processId);
+        if (!managed || managed.ownerId !== ownerId || managed.stopping)
+            return false;
+        managed.child.stdin?.write(`${line}\n`);
+        return true;
+    }
+    stopManaged(managed) {
+        if (managed.stopping)
+            return;
+        managed.stopping = true;
+        managed.child.stdin?.end();
+        signalGroup(managed.child, 'SIGTERM');
+        managed.killTimer = setTimeout(() => signalGroup(managed.child, 'SIGKILL'), this.options.killGraceMs ?? KILL_GRACE_MS);
+    }
+    stop(ownerId, processId) {
+        const managed = this.processes.get(processId);
+        if (!managed || managed.ownerId !== ownerId)
+            return false;
+        this.stopManaged(managed);
+        return true;
+    }
+    stopOwner(ownerId) {
+        for (const managed of this.processes.values())
+            if (managed.ownerId === ownerId)
+                this.stopManaged(managed);
+    }
+    stopAll() {
+        for (const managed of this.processes.values())
+            this.stopManaged(managed);
+    }
+    /** 同步、不等待：bridge 退出时用（包括 process 'exit' 钩子里） */
+    killAllNow() {
+        for (const managed of this.processes.values())
+            signalGroup(managed.child, 'SIGKILL');
+    }
+    get size() {
+        return this.processes.size;
+    }
+}

package/dist/bridge/protocol.js

@@ -0,0 +1,62 @@
+/**
+ * 本机 ACP bridge ↔ M2 页面的 WebSocket 协议（change acp-local-bridge，给 change 3 acp-panel-local-agent 用）。
+ *
+ * 规范正文在 openspec 里该 change 的 design「页面协议」一节；本文件是它的类型落地，两者不一致时以 design 为准并修正这里。
+ *
+ * 维护约束：
+ * - 本文件同时被 bridge（Node，ES2022 / NodeNext）和前端（浏览器，ES2020 / bundler / noUncheckedIndexedAccess）编译，
+ *   所以只能有类型和常量：不 import 任何模块、不用 enum、不用 Node 或 DOM 专有类型。
+ * - 同一协议版本内只做加法（新方法、新事件、新可选字段、新枚举值）。删除字段或改变语义要升 BRIDGE_PROTOCOL_VERSION，
+ *   bridge 至少同时支持前一个版本。页面必须忽略不认识的字段 / 事件，把不认识的 state 当成 unknown。
+ * - bridge 不翻译 ACP：agent → 页面的 `acp` 行原样转发（不保证是 JSON）；页面 → agent 的行只做方法白名单与会话范围检查（acp-guard.ts），
+ *   翻译全部在页面做。
+ * - 配对 = 授权该页面以用户的身份驱动本机 agent（包括让它执行命令）；页面代码与 token 的保管要按这个级别对待。
+ */
+/** 本 bridge 支持的协议版本（页面在 hello 里给出自己支持的列表，bridge 选双方共有的最大值） */
+export const BRIDGE_PROTOCOL_VERSION = 1;
+export const BRIDGE_SUPPORTED_PROTOCOLS = [1];
+/** 默认端口与路径。页面必须连 127.0.0.1（不是 localhost：localhost 可能先解析到 ::1，bridge 不监听 IPv6）。 */
+export const BRIDGE_DEFAULT_PORT = 47821;
+export const BRIDGE_WS_PATH = '/bridge';
+/** 与前端 src/lib/agent-types 的 AgentType 取值一致（是它的子集），顺序即 agents/list 的返回顺序 */
+export const BRIDGE_AGENT_IDS = ['claude', 'codex', 'cursor', 'opencode', 'qoder'];
+/**
+ * 页面可以发给 agent 的 ACP 方法（bridge 的 acp-guard.ts 按它放行，名单外回 `acp_rejected`、不转发）。
+ * 页面对 agent 请求的响应（没有 method 键，例如审批结果）不受它限制。页面要用新方法：先在这里加上并发新版 bridge，
+ * 页面按 welcome 的 `bridge.version` 判断对方是否支持。
+ */
+export const BRIDGE_PAGE_ACP_METHODS = [
+    'initialize',
+    'session/new',
+    'session/load',
+    'session/resume',
+    'session/list',
+    'session/prompt',
+    'session/cancel',
+    'session/set_mode',
+    'session/set_config_option',
+    'session/close',
+    '$/cancel_request',
+];
+export const BRIDGE_METHODS = [
+    'pair',
+    'agents/list',
+    'agent/prepare',
+    'agent/precheck',
+    'm2/configure',
+    'process/start',
+    'process/stop',
+];
+export const BRIDGE_CLOSE_CODES = {
+    normal: 1000,
+    goingAway: 1001,
+    unsupportedData: 1003,
+    /** 单帧超过 64MB（ws 库自动发出） */
+    messageTooBig: 1009,
+    /** 握手阶段 bridge 内部出错 */
+    internalError: 1011,
+    badHandshake: 4400,
+    timeout: 4408,
+    protocolUnsupported: 4426,
+    tooManyUnpaired: 4429,
+};

package/dist/bridge/security.js

@@ -0,0 +1,52 @@
+/**
+ * 本机 ACP bridge 的连接准入判定（纯函数）。在 HTTP upgrade 阶段、完成 WebSocket 握手之前调用。
+ *
+ * 这里管的是「谁能连上来」：Origin 白名单与只接受本机连接（第三道「配对 token」在 pairing.ts）。
+ * 浏览器这层不可依赖：开了本机代理的用户，Chrome 不会弹本地网络访问框（ACP PoC 报告 §3），
+ * 所以任何网站都能尝试连 127.0.0.1，只能靠 bridge 自己挡。
+ * 连上并配对之后页面能做什么，见 server.ts / acp-guard.ts 的文件头：配对 = 授权该页面驱动本机 agent。
+ *
+ * 维护约束：
+ * - Origin 必须精确匹配（scheme + host + port 全等）。不要改成后缀匹配、正则或「包含 m2ui.ai」——
+ *   `https://m2ui.ai.evil.com`、`https://evil.m2ui.ai` 都必须被拒。
+ * - 默认只放行正式域名。开发域名只在 `bridge --dev` 时放行：`localhost:5173` 是所有本机 Vite 项目共用的 Origin、
+ *   共用 localStorage，给开发版 M2 配对过后，任何跑在 5173 的项目（包括它的依赖）都能读走 token 免码连上
+ *   （review r3 B2，用户 2026-10-02 拍板改为 --dev，推翻了最初的「开发域名常开」）。名单写死在包里，不提供任意扩展参数。
+ * - Host 校验防 DNS rebinding：攻击者域名解析到 127.0.0.1 时，Host 头是攻击者域名。
+ */
+import { BRIDGE_WS_PATH } from './protocol.js';
+/** www.m2ui.ai 由 m2-router 301 到根域，页面 Origin 不会是它，所以不列 */
+export const PROD_ORIGINS = ['https://m2ui.ai'];
+/** 本地开发 M2 用（Vite 默认端口）；只有 `bridge --dev` 才放行 */
+export const DEV_ORIGINS = ['http://localhost:5173', 'http://127.0.0.1:5173'];
+export function allowedOrigins(dev) {
+    return dev ? [...PROD_ORIGINS, ...DEV_ORIGINS] : PROD_ORIGINS;
+}
+export function isAllowedOrigin(origin, origins) {
+    return typeof origin === 'string' && origins.includes(origin);
+}
+/** 只接受 `127.0.0.1:<port>` 与 `localhost:<port>`；port 是实际监听端口（测试里可能是随机端口） */
+export function isAllowedHost(host, port) {
+    return host === `127.0.0.1:${port}` || host === `localhost:${port}`;
+}
+/** 服务只监听 127.0.0.1，这里是第二道确认（例如以后有人把监听地址改宽了） */
+export function isLoopbackAddress(address) {
+    return address === '127.0.0.1' || address === '::ffff:127.0.0.1' || address === '::1';
+}
+/**
+ * 拒绝时返回 HTTP 状态，由调用方直接写回并销毁 socket，不完成握手。
+ * 403 而不是「握手后再关」：不对非白名单页面完成任何握手。注意这挡不住「探测 bridge 是否在运行」——
+ * 任何网站用 no-cors 请求 http://127.0.0.1:<port>/ 都能分辨「有响应」与「连接被拒」，只暴露这一点信息。
+ */
+export function checkUpgrade(info, port, origins) {
+    const pathname = (info.path ?? '').split('?')[0];
+    if (pathname !== BRIDGE_WS_PATH)
+        return { ok: false, status: 404, reason: `unknown path ${pathname}` };
+    if (!isLoopbackAddress(info.remoteAddress))
+        return { ok: false, status: 403, reason: `remote ${info.remoteAddress ?? 'unknown'}` };
+    if (!isAllowedHost(info.host, port))
+        return { ok: false, status: 403, reason: `host ${info.host ?? 'missing'}` };
+    if (!isAllowedOrigin(info.origin, origins))
+        return { ok: false, status: 403, reason: `origin ${info.origin ?? 'missing'}` };
+    return { ok: true };
+}