@m2canvas/connect 0.3.1 → 0.4.0

package/dist/bridge/pairing.js

@@ -0,0 +1,242 @@
+/**
+ * 配对：安全三条里的第三条。Origin 白名单挡住了其他网站，但挡不住两类来源 —— `--dev` 时本机其他跑在开发端口上的页面
+ * 和本机其他进程（可以伪造 Origin）。它们都拿不到只出现在终端里的配对码。
+ * 配对 = 授权该页面以用户的身份驱动本机 agent（包括执行命令），所以码和 token 都按这个级别保管。
+ *
+ * 流程：终端打印一次性配对码 → 用户在页面输入 → 换取长期 token（页面存 localStorage）→ 之后每次 hello 带上。
+ *
+ * 维护约束：
+ * - 本地只存 token 的 sha256，不存明文；文件 0600、目录 0700。
+ * - token 绑定配对时的 Origin：开发域名配出的 token 不能拿到正式域名用。
+ * - 配对码约 40 bit，每个码最多错 MAX_CODE_FAILURES 次、CODE_TTL_MS 后过期，二者都会轮换并在终端重新打印；
+ *   自上次成功配对以来累计错 MAX_TOTAL_FAILURES 次就锁定（不论中间换过几个码、码是不是过期换的），只有重启 bridge 才解除
+ *   （锁只在内存里）。锁定不影响已配对的页面。
+ *   不要为了「方便」放宽次数、延长有效期或加一个页面能触发的解锁：码是唯一挡住本机恶意页面的东西。
+ *   也不要改成「在终端按回车解锁」：那需要读终端，而 bridge 放到后台（`… bridge &`）时读终端会被系统挂起（review r2 实测）。
+ * - 比较用常量时间（timingSafeEqual），不要改回 ===。
+ */
+import { createHash, randomBytes, randomInt, randomUUID, timingSafeEqual } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const CODE_TTL_MS = 10 * 60 * 1000;
+export const MAX_CODE_FAILURES = 5;
+export const TOKEN_IDLE_MS = 30 * 24 * 60 * 60 * 1000;
+export const TOKEN_IDLE_DAYS = 30;
+export const MAX_PAIRINGS = 20;
+/**
+ * 自上次成功配对以来累计错这么多次就锁定，重启 bridge 才解除。按累计而不是「因错码轮换的次数」计：
+ * 码过期换新时不清零 —— 否则每个码错 4 次再等它过期就能无限猜下去（review r3 S4）。
+ */
+export const MAX_TOTAL_FAILURES = 15;
+/** 同一 Origin、同一个码在终端的重复提示间隔 */
+const PROMPT_DEDUPE_MS = 60_000;
+/** Crockford base32：去掉易混的 I、L、O、U */
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const CODE_LENGTH = 8;
+/** 用户输入归一：大小写、空格、连字符；按 Crockford 规则把 O 视同 0、I / L 视同 1 */
+export function normalizePairingCode(input) {
+    return input
+        .toUpperCase()
+        .replace(/[\s-]/g, '')
+        .replace(/O/g, '0')
+        .replace(/[IL]/g, '1');
+}
+function formatCode(code) {
+    return `${code.slice(0, 4)}-${code.slice(4)}`;
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest();
+}
+function sameSecret(a, b) {
+    const left = sha256(a);
+    const right = sha256(b);
+    return timingSafeEqual(left, right);
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export class PairingManager {
+    active = null;
+    /** 自上次成功配对以来累计的错码次数（跨码、跨过期）；配对成功时清零 */
+    failuresSinceSuccess = 0;
+    locked = false;
+    /** Origin → 上次在终端提示它的时间与当时的码，用于去重 */
+    lastPrompt = new Map();
+    store;
+    now;
+    onCodeIssued;
+    onLocked;
+    onProblem;
+    constructor(options) {
+        this.store = options.store;
+        this.now = options.now ?? Date.now;
+        this.onCodeIssued = options.onCodeIssued;
+        this.onLocked = options.onLocked ?? (() => undefined);
+        this.onProblem = options.onProblem ?? (() => undefined);
+    }
+    /** 生成新码（旧码立即失效）并通知调用方打印，返回显示形式 */
+    issueCode(reason, origin = null) {
+        let code = '';
+        for (let i = 0; i < CODE_LENGTH; i++)
+            code += ALPHABET[randomInt(ALPHABET.length)];
+        this.active = { code, issuedAt: this.now(), failures: 0 };
+        const display = formatCode(code);
+        if (origin)
+            this.lastPrompt.set(origin, { at: this.now(), code });
+        this.onCodeIssued({ display, reason, origin, expiresAt: this.active.issuedAt + CODE_TTL_MS });
+        return display;
+    }
+    hasValidCode() {
+        return this.active !== null && this.now() - this.active.issuedAt <= CODE_TTL_MS;
+    }
+    isLocked() {
+        return this.locked;
+    }
+    /**
+     * 未配对页面连上时调用。没有有效码就出新码；有有效码也把它连同发起方 Origin 再提示一次 ——
+     * 最常见的首次流程是「启动 bridge 后马上打开页面」，终端里只有一个不带 Origin 的启动码，
+     * 不再提示的话用户看不到是哪个页面在请求配对。同一 Origin、同一个码一分钟内只提示一次（页面重连不刷屏）。
+     * 锁定期间什么都不做。
+     */
+    ensureCode(origin) {
+        if (this.locked)
+            return;
+        if (!this.hasValidCode() || !this.active) {
+            this.issueCode('requested', origin);
+            return;
+        }
+        const last = this.lastPrompt.get(origin);
+        if (last && last.code === this.active.code && this.now() - last.at < PROMPT_DEDUPE_MS)
+            return;
+        this.lastPrompt.set(origin, { at: this.now(), code: this.active.code });
+        this.onCodeIssued({ display: formatCode(this.active.code), reason: 'requested', origin, expiresAt: this.active.issuedAt + CODE_TTL_MS });
+    }
+    /**
+     * 配对。保存 token 失败时抛出（调用方回给页面 internal），此时码不被消耗、可以重试。
+     *
+     * 暴力尝试的上限：每个码最多错 MAX_CODE_FAILURES 次（然后换码），自上次成功以来累计错 MAX_TOTAL_FAILURES 次锁定，
+     * 锁定期间不再出码、不再比对，只有重启 bridge 才解除。没有累计上限，换码本身就是无限次尝试
+     * （review r1 实测 1.6 秒 20000 次），还会让陌生页面把用户的配对码一直刷掉。
+     */
+    pair(input, origin) {
+        if (this.locked)
+            return { ok: false, code: 'pairing_locked' };
+        if (!this.active) {
+            // 码已被消费：请用户看终端里的新码
+            this.issueCode('requested', origin);
+            return { ok: false, code: 'pairing_code_rotated' };
+        }
+        if (!this.hasValidCode()) {
+            this.issueCode('expired', origin);
+            return { ok: false, code: 'pairing_code_rotated' };
+        }
+        const active = this.active;
+        if (sameSecret(normalizePairingCode(input), active.code)) {
+            const token = this.createToken(origin);
+            this.active = null;
+            this.failuresSinceSuccess = 0;
+            return { ok: true, token };
+        }
+        active.failures += 1;
+        this.failuresSinceSuccess += 1;
+        if (this.failuresSinceSuccess >= MAX_TOTAL_FAILURES) {
+            this.locked = true;
+            this.active = null;
+            this.onLocked(origin);
+            return { ok: false, code: 'pairing_locked' };
+        }
+        if (active.failures < MAX_CODE_FAILURES) {
+            const attemptsLeft = Math.min(MAX_CODE_FAILURES - active.failures, MAX_TOTAL_FAILURES - this.failuresSinceSuccess);
+            return { ok: false, code: 'pairing_invalid', attemptsLeft };
+        }
+        this.issueCode('too_many_failures', origin);
+        return { ok: false, code: 'pairing_code_rotated' };
+    }
+    createToken(origin) {
+        const token = randomBytes(32).toString('base64url');
+        const nowIso = new Date(this.now()).toISOString();
+        const records = this.liveRecords();
+        records.push({ id: randomUUID(), tokenHash: sha256(token).toString('hex'), origin, createdAt: nowIso, lastUsedAt: nowIso });
+        // 超出上限时淘汰最久未用的
+        records.sort((a, b) => Date.parse(b.lastUsedAt) - Date.parse(a.lastUsedAt));
+        // 这里的写失败必须抛出：token 没存下来，页面拿到也用不了
+        this.store.save(records.slice(0, MAX_PAIRINGS));
+        return token;
+    }
+    /** 读出未过期的记录；顺带把过期的从存储里删掉（删不掉只告警：不影响本次判定） */
+    liveRecords() {
+        const all = this.store.load();
+        const live = all.filter((record) => this.now() - Date.parse(record.lastUsedAt) <= TOKEN_IDLE_MS);
+        if (live.length !== all.length)
+            this.trySave(live);
+        return live;
+    }
+    trySave(records) {
+        try {
+            this.store.save(records);
+        }
+        catch (error) {
+            this.onProblem(`Could not update the pairing file (${errorText(error)}). Pairings still work for now but may not survive a restart.`);
+        }
+    }
+    /**
+     * token 有效且与当前 Origin 匹配时返回 true，并刷新 lastUsedAt（闲置期从此刻重新计算）。
+     * 刷新写盘失败只告警、仍判有效：判定本身只依赖读到的记录，不能因为磁盘满让已配对的页面全部掉线（更不能让 bridge 崩溃）。
+     */
+    verifyToken(token, origin) {
+        if (typeof token !== 'string' || token.length === 0)
+            return false;
+        const hash = sha256(token);
+        const records = this.liveRecords();
+        const match = records.find((record) => {
+            const stored = Buffer.from(record.tokenHash, 'hex');
+            return stored.length === hash.length && timingSafeEqual(stored, hash) && record.origin === origin;
+        });
+        if (!match)
+            return false;
+        match.lastUsedAt = new Date(this.now()).toISOString();
+        this.trySave(records);
+        return true;
+    }
+    unpairAll() {
+        this.store.clear();
+    }
+}
+function isRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return ['id', 'tokenHash', 'origin', 'createdAt', 'lastUsedAt'].every((key) => typeof record[key] === 'string');
+}
+/**
+ * `~/.m2canvas/bridge-pairings.json`。文件损坏按空处理（用户需要重新配对）并经 onProblem 报告，
+ * 不抛错：bridge 仍应能启动，只是之前的配对作废。
+ */
+export function createFilePairingStore(path, onProblem = () => undefined) {
+    return {
+        load() {
+            if (!existsSync(path))
+                return [];
+            try {
+                const parsed = JSON.parse(readFileSync(path, 'utf8'));
+                const list = typeof parsed === 'object' && parsed !== null ? parsed.pairings : undefined;
+                if (!Array.isArray(list))
+                    throw new Error('missing "pairings" array');
+                return list.filter(isRecord);
+            }
+            catch (error) {
+                onProblem(`Ignoring unreadable pairing file ${path} (${error instanceof Error ? error.message : String(error)}). Pages will need to pair again.`);
+                return [];
+            }
+        },
+        save(records) {
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            chmodSync(dirname(path), 0o700);
+            writeFileSync(path, `${JSON.stringify({ version: 1, pairings: records }, null, 2)}\n`, { mode: 0o600 });
+            chmodSync(path, 0o600);
+        },
+        clear() {
+            rmSync(path, { force: true });
+        },
+    };
+}

package/dist/bridge/precheck-parse.js

@@ -0,0 +1,246 @@
+/**
+ * 各家 CLI 的登录状态与 `mcp list` 输出解析（纯函数）。
+ *
+ * 这些输出都是给人看的文本，没有格式承诺，各家升级就可能变。所以规则是：只认实测过的关键词（样本见单测，
+ * 原文记录在 acp-local-bridge 的 evidence/cli-probes.md），其余一律 unknown 并附原文。
+ * **不要加「认不出就当 ready / logged_in」的分支** —— ACP 对 m2 不可用完全不报（PoC 报告 §4.1），
+ * 误报 ready 会让用户在一个没有画布工具的会话里白等。
+ *
+ * m2 配置项按 URL 的 host 识别（与 connect 的 isM2Url 同一判据），名字可以是任意的。
+ */
+import { isM2Url } from '../config-files.js';
+/** raw 字段最多保留的尾部字符数 */
+export const RAW_LIMIT = 2048;
+// eslint-disable-next-line no-control-regex
+const ANSI_RE = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+export function stripAnsi(text) {
+    return text.replace(ANSI_RE, '');
+}
+export function tail(text) {
+    return text.length > RAW_LIMIT ? text.slice(-RAW_LIMIT) : text;
+}
+function login(state, output) {
+    return { state, raw: state === 'unknown' ? tail(stripAnsi(output)) : null };
+}
+function m2(state, entry, output) {
+    return { state, entry, raw: state === 'error' || state === 'unknown' ? tail(stripAnsi(output)) : null };
+}
+/** 多个指向 m2 的配置项时取最好的那个 */
+const RANK = {
+    ready: 0,
+    unverified: 1,
+    needs_enable: 2,
+    needs_auth: 3,
+    error: 4,
+    unknown: 5,
+    not_configured: 6,
+};
+function best(candidates, output) {
+    const sorted = [...candidates].sort((a, b) => RANK[a.state] - RANK[b.state]);
+    const top = sorted[0];
+    return top ? m2(top.state, top.entry, output) : m2('unknown', null, output);
+}
+// ───────────────────────────── 登录 ─────────────────────────────
+/** `claude auth status --json`：未登录时退出码 1，stdout 仍是完整 JSON */
+export function parseClaudeAuthStatus(stdout, _exitCode) {
+    try {
+        const parsed = JSON.parse(stdout);
+        const loggedIn = typeof parsed === 'object' && parsed !== null ? parsed.loggedIn : undefined;
+        if (loggedIn === true)
+            return login('logged_in', stdout);
+        if (loggedIn === false)
+            return login('logged_out', stdout);
+    }
+    catch {
+        // 落到 unknown
+    }
+    return login('unknown', stdout);
+}
+/** `codex login status`：输出在 stderr；已登录退出码 0，未登录退出码 1 */
+export function parseCodexLoginStatus(output, exitCode) {
+    if (/Not logged in/i.test(output))
+        return login('logged_out', output);
+    if (exitCode === 0 && /Logged in/i.test(output))
+        return login('logged_in', output);
+    return login('unknown', output);
+}
+/** `agent status`（Cursor）：两种情况退出码都是 0 */
+export function parseCursorStatus(output) {
+    if (/Not logged in/i.test(output))
+        return login('logged_out', output);
+    if (/Logged in/i.test(output))
+        return login('logged_in', output);
+    return login('unknown', output);
+}
+/** `qodercli status`：未登录是 `Account: Not logged in`，已登录列出 Username / Email */
+export function parseQoderStatus(output) {
+    if (/Not logged in/i.test(output))
+        return login('logged_out', output);
+    if (/^(Email|Username):/m.test(output))
+        return login('logged_in', output);
+    return login('unknown', output);
+}
+// ───────────────────────────── m2 ─────────────────────────────
+/** `<名字>: <url> …`；Qoder 行首还有一个状态图标（✓ / 🔑），图标由非字母数字字符组成，名字可含空格 */
+const URL_LINE_RE = /^(?:[^\p{L}\p{N}\s]+\s+)?(.+?): (https?:\/\/\S+)(.*)$/u;
+/**
+ * 任何服务器行（含 stdio 服务器：`<名字>: <命令> - <状态>`，没有 URL）。用来区分「列出了服务器但没有 m2」
+ * （→ not_configured，页面给出 configure）和「输出认不出」（→ unknown）。
+ *
+ * 有意的取舍：这个模式比较宽。如果哪天某个 CLI 不再给 HTTP 服务器打印 URL，已配置的 m2 会被判成 not_configured
+ * （页面引导「添加」，connect 回「已存在」，再预检仍是 not_configured）——是一次可见的引导错误，但不会误报 ready。
+ * 反过来收窄成「只认带 URL 的行」，只配了 stdio 服务器的用户就永远拿不到 configure（review r1 S6）。
+ */
+const SERVER_LINE_RE = /^(?:[^\p{L}\p{N}\s]+\s+)?.+?: \S.* - \S/u;
+function hasServerLines(output) {
+    return stripAnsi(output)
+        .split(/\r?\n/)
+        .some((line) => SERVER_LINE_RE.test(line.trim()));
+}
+function urlLines(output) {
+    const lines = [];
+    for (const raw of stripAnsi(output).split(/\r?\n/)) {
+        const match = URL_LINE_RE.exec(raw.trim());
+        if (match?.[1] && match[2])
+            lines.push({ name: match[1], url: match[2], rest: match[3] ?? '' });
+    }
+    return lines;
+}
+function claudeStatus(rest) {
+    if (/Failed to connect/i.test(rest))
+        return 'error';
+    if (/Needs authentication/i.test(rest))
+        return 'needs_auth';
+    if (/Pending approval/i.test(rest))
+        return 'needs_enable';
+    if (/\bConnected\b/.test(rest))
+        return 'ready';
+    return 'unknown';
+}
+/** `claude mcp list`：每行 `<名字>: <url> (HTTP) - <图标> <状态>`；stdio 服务器的行没有 URL，与 m2 无关 */
+export function parseClaudeMcpList(output, exitCode) {
+    if (exitCode !== 0)
+        return m2('unknown', null, output);
+    const lines = urlLines(output);
+    const candidates = lines.filter((line) => isM2Url(line.url)).map((line) => ({ state: claudeStatus(line.rest), entry: line.name }));
+    if (candidates.length > 0)
+        return best(candidates, output);
+    if (lines.length > 0 || hasServerLines(output) || /No MCP servers configured/i.test(output))
+        return m2('not_configured', null, output);
+    return m2('unknown', null, output);
+}
+/** `qodercli mcp list`：`<图标> <名字>: <url> (http) - <状态>`；它也读项目级 .mcp.json */
+export function parseQoderMcpList(output, exitCode) {
+    if (exitCode !== 0)
+        return m2('unknown', null, output);
+    const lines = urlLines(output);
+    const candidates = lines
+        .filter((line) => isM2Url(line.url))
+        .map((line) => ({
+        state: /Needs authentication/i.test(line.rest) ? 'needs_auth' : /\bConnected\b/.test(line.rest) ? 'ready' : 'unknown',
+        entry: line.name,
+    }));
+    if (candidates.length > 0)
+        return best(candidates, output);
+    if (lines.length > 0 || hasServerLines(output) || /No MCP servers configured/i.test(output))
+        return m2('not_configured', null, output);
+    return m2('unknown', null, output);
+}
+/**
+ * 适配器自带 codex 的 `mcp list --json`。`auth_status: "o_auth"` 只说明存过 OAuth 凭证，不说明还有效
+ * （旧版本 codex 存的凭证新版本刷新不了，PoC 报告 §2.2），所以只能报 unverified。
+ */
+export function parseCodexMcpListJson(stdout, exitCode) {
+    if (exitCode !== 0)
+        return m2('unknown', null, stdout);
+    let servers;
+    try {
+        servers = JSON.parse(stdout);
+    }
+    catch {
+        return m2('unknown', null, stdout);
+    }
+    if (!Array.isArray(servers))
+        return m2('unknown', null, stdout);
+    const candidates = [];
+    for (const server of servers) {
+        if (typeof server !== 'object' || server === null || !isM2Url(server.transport?.url))
+            continue;
+        const entry = typeof server.name === 'string' ? server.name : '';
+        if (server.enabled === false)
+            candidates.push({ state: 'needs_enable', entry });
+        else if (server.auth_status === 'not_logged_in')
+            candidates.push({ state: 'needs_auth', entry });
+        else if (server.auth_status === 'o_auth')
+            candidates.push({ state: 'unverified', entry });
+        else
+            candidates.push({ state: 'unknown', entry });
+    }
+    return candidates.length > 0 ? best(candidates, stdout) : m2('not_configured', null, stdout);
+}
+/**
+ * `agent mcp list`（Cursor）：输出只有 `<名字>: <状态>`，没有 URL，所以由调用方先从
+ * `<cwd>/.cursor/mcp.json` 与 `~/.cursor/mcp.json` 找出指向 m2 的名字（entryNames）再对行。
+ * 授权按目录保存，调用方必须在会话 cwd 下执行命令。
+ */
+export function parseCursorMcpList(output, entryNames, exitCode) {
+    if (entryNames.length === 0)
+        return m2('not_configured', null, output);
+    if (exitCode !== 0)
+        return m2('unknown', null, output);
+    const status = new Map();
+    for (const raw of stripAnsi(output).split(/\r?\n/)) {
+        const index = raw.lastIndexOf(': ');
+        if (index > 0)
+            status.set(raw.slice(0, index).trim(), raw.slice(index + 2).trim());
+    }
+    const candidates = [];
+    for (const name of entryNames) {
+        const value = status.get(name);
+        if (value === undefined)
+            continue;
+        const state = value === 'ready' ? 'ready' : value === 'requires_authentication' ? 'needs_auth' : /needs approval/i.test(value) ? 'needs_enable' : 'unknown';
+        candidates.push({ state, entry: name });
+    }
+    return best(candidates, output);
+}
+/** OpenCode 状态行的结尾词（实测过的三种） */
+const OPENCODE_STATUS = [
+    ['needs authentication', 'needs_auth'],
+    ['connected', 'ready'],
+    ['disabled', 'needs_enable'],
+];
+/**
+ * `opencode mcp list`：带框线与 ANSI（NO_COLOR 无效）。每个服务器两行：
+ * `●  <图标> <名字> <状态>`，下一行 `│  <url>`。
+ */
+export function parseOpencodeMcpList(output, exitCode) {
+    if (exitCode !== 0)
+        return m2('unknown', null, output);
+    const text = stripAnsi(output);
+    if (/No MCP servers configured/i.test(text))
+        return m2('not_configured', null, output);
+    const candidates = [];
+    let pending = null;
+    let sawServer = false;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        const head = /^●\s+\S+\s+(.+)$/u.exec(line);
+        if (head?.[1]) {
+            sawServer = true;
+            const body = head[1].trim();
+            const known = OPENCODE_STATUS.find(([word]) => body.endsWith(` ${word}`));
+            pending = known ? { entry: body.slice(0, -known[0].length - 1).trim(), state: known[1] } : { entry: body, state: 'unknown' };
+            continue;
+        }
+        const url = /^│\s+(https?:\/\/\S+)/u.exec(line);
+        if (url?.[1] && pending) {
+            if (isM2Url(url[1]))
+                candidates.push(pending);
+            pending = null;
+        }
+    }
+    if (candidates.length > 0)
+        return best(candidates, output);
+    return sawServer ? m2('not_configured', null, output) : m2('unknown', null, output);
+}

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() };
+}