@capybara-hq/plugin-tools 0.0.0-stage → 0.1.0-rc.0

package/dist/check/plugin-permissions.js

@@ -0,0 +1,392 @@
+import { isParseError, listSourceFiles, parseFile, stringValue, walk, } from "./source.js";
+const MARKER = "capybara:allow-dynamic-permission";
+const WRAPPERS = new Set([
+    "ParenthesizedExpression",
+    "TSAsExpression",
+    "TSSatisfiesExpression",
+    "TSNonNullExpression",
+    "TSTypeAssertion",
+]);
+function unwrap(n) {
+    let cur = n;
+    while (WRAPPERS.has(cur.type))
+        cur = cur.expression;
+    return cur;
+}
+const propName = (p) => {
+    if (p.type !== "Property" || p.computed)
+        return undefined;
+    const k = p.key;
+    if (k.type === "Identifier")
+        return k.name;
+    if (k.type === "Literal" && typeof k.value === "string")
+        return k.value;
+    return undefined;
+};
+function prop(obj, name) {
+    for (const p of obj.properties)
+        if (propName(p) === name)
+            return p;
+    return undefined;
+}
+/** `x.name` / `x["name"]` 的属性名；动态属性返回 undefined。 */
+function memberName(m) {
+    const p = m.property;
+    if (!m.computed)
+        return p.type === "Identifier" ? p.name : undefined;
+    return stringValue(p);
+}
+const isFn = (n) => n.type === "ArrowFunctionExpression" ||
+    n.type === "FunctionExpression" ||
+    n.type === "FunctionDeclaration";
+/** 文件级环境：同文件的 const 与函数，用于把标识符追到定义处。 */
+function buildDecls(f) {
+    const decls = new Map();
+    walk(f.program, (n) => {
+        if (n.type === "VariableDeclarator") {
+            const id = n.id;
+            if (id.type === "Identifier" && n.init)
+                decls.set(id.name, n.init);
+        }
+        else if (n.type === "FunctionDeclaration") {
+            const id = n.id;
+            if (id)
+                decls.set(id.name, n);
+        }
+    });
+    return decls;
+}
+/** 追到字面量节点：直接写，或经本文件的 const 引用。 */
+function resolve(n, decls) {
+    let e = unwrap(n);
+    for (let i = 0; i < 5 && e.type === "Identifier"; i++) {
+        const init = decls.get(e.name);
+        if (!init)
+            break;
+        e = unwrap(init);
+    }
+    return e;
+}
+/** 找行尾或紧邻上一行（独占一行）的豁免注释。 */
+function findMarker(f, at) {
+    const first = f.lineOf(at.start);
+    const last = f.lineOf(at.end);
+    for (const c of f.comments) {
+        if (c.type !== "Line")
+            continue;
+        const m = new RegExp(`^\\s*${MARKER}(?:\\s+(.*\\S))?\\s*$`).exec(c.value);
+        if (!m)
+            continue;
+        const line = f.lineOf(c.start);
+        const ownLine = f.lineText(line).trimStart().startsWith("//");
+        if (line === first || line === last || (line === first - 1 && ownLine)) {
+            return { reason: m[1] ?? "" };
+        }
+    }
+    return undefined;
+}
+const strings = (n, decls) => {
+    if (!n)
+        return [];
+    const e = resolve(n, decls);
+    if (e.type !== "ArrayExpression")
+        return [];
+    return e.elements.flatMap((x) => {
+        const v = x ? stringValue(resolve(x, decls)) : undefined;
+        return v === undefined ? [] : [v];
+    });
+};
+/** Whether hook options are statically `{ mode: "policy" }` (object literal or same-file const). */
+function policyMode(opts, decls) {
+    const o = opts ? resolve(opts, decls) : undefined;
+    if (o?.type !== "ObjectExpression")
+        return false;
+    const mode = prop(o, "mode")?.value;
+    return mode !== undefined && stringValue(resolve(mode, decls)) === "policy";
+}
+function readManifest(obj, decls) {
+    const m = {
+        secrets: false,
+        http: new Set(),
+        tools: new Set(),
+        uiViews: new Set(),
+        hooks: new Set(),
+        policyHooks: new Set(),
+        caps: new Set(),
+        storage: false,
+        models: false,
+        setup: undefined,
+    };
+    for (const key of ["requires", "optional", "provides"]) {
+        for (const s of strings(prop(obj, key)?.value, decls))
+            m.caps.add(s);
+    }
+    const perm = prop(obj, "permissions");
+    const pe = perm ? resolve(perm.value, decls) : undefined;
+    if (pe?.type === "ObjectExpression") {
+        const secrets = prop(pe, "secrets");
+        m.secrets = !!secrets && resolve(secrets.value, decls).value === true;
+        const storage = prop(pe, "storage");
+        m.storage = !!storage && resolve(storage.value, decls).value === true;
+        m.models = !!prop(pe, "models");
+        for (const t of strings(prop(pe, "tools")?.value, decls))
+            m.tools.add(t);
+        for (const h of strings(prop(pe, "hooks")?.value, decls))
+            m.hooks.add(h);
+        for (const h of strings(prop(pe, "policyHooks")?.value, decls)) {
+            m.policyHooks.add(h);
+        }
+        const ui = prop(pe, "ui");
+        const ue = ui ? resolve(ui.value, decls) : undefined;
+        if (ue?.type === "ObjectExpression") {
+            for (const v of strings(prop(ue, "views")?.value, decls)) {
+                m.uiViews.add(v);
+            }
+        }
+        const http = prop(pe, "http");
+        const arr = http ? resolve(http.value, decls) : undefined;
+        if (arr?.type === "ArrayExpression") {
+            for (const el of arr.elements) {
+                const o = el ? resolve(el, decls) : undefined;
+                if (o?.type !== "ObjectExpression")
+                    continue;
+                const method = stringValue(prop(o, "method")?.value);
+                const path = stringValue(prop(o, "path")?.value);
+                if (method !== undefined && path !== undefined)
+                    m.http.add(`${method} ${path}`);
+            }
+        }
+    }
+    const setup = prop(obj, "setup");
+    if (setup) {
+        const v = resolve(setup.value, decls);
+        if (isFn(v))
+            m.setup = v;
+    }
+    return m;
+}
+function scanSetup(f, m, decls) {
+    const out = [];
+    /** 明确的违规：豁免注释不起作用。 */
+    const add = (at, rule, message) => {
+        out.push({ file: f.file, line: f.lineOf(at.start), rule, message });
+    };
+    /** 「无法静态确认」：只有这类可以用豁免注释放行（原因必填）。 */
+    const dynamic = (at, rule, what) => {
+        const marker = findMarker(f, at);
+        if (marker?.reason)
+            return;
+        add(at, rule, marker
+            ? `// ${MARKER} must be followed by a reason (not empty)`
+            : `Cannot statically confirm ${what}. Use a string literal (or a same-file const), or add // ${MARKER} <reason>`);
+    };
+    let first = m.setup?.params?.[0];
+    if (first?.type === "AssignmentPattern")
+        first = first.left;
+    if (!m.setup || !first)
+        return out;
+    const queue = [];
+    const seen = new Set();
+    const enqueue = (fn, param) => {
+        if (param?.type !== "Identifier")
+            return;
+        const key = `${fn.start}|${param.name}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        queue.push({ fn, names: new Set([param.name]) });
+    };
+    enqueue(m.setup, first);
+    if (first.type === "ObjectPattern") {
+        dynamic(first, "perm-reserved", "platform access through a destructured setup parameter");
+    }
+    while (queue.length > 0) {
+        const { fn, names } = queue.shift();
+        const isCtx = (n) => {
+            const e = n ? unwrap(n) : undefined;
+            return e?.type === "Identifier" && names.has(e.name);
+        };
+        // 先收集本地别名：const c = ctx
+        walk(fn.body, (n) => {
+            if (n.type === "VariableDeclarator" && n.init && isCtx(n.init)) {
+                const id = n.id;
+                if (id.type === "Identifier")
+                    names.add(id.name);
+                else {
+                    dynamic(n, "perm-reserved", "platform access through a destructured ctx");
+                }
+            }
+        });
+        walk(fn.body, (n, parent) => {
+            if (n.type === "CallExpression") {
+                const callee = unwrap(n.callee);
+                const args = n.arguments;
+                // 把 ctx 传给同文件函数：继续跟踪
+                if (callee.type === "Identifier") {
+                    const target = decls.get(callee.name);
+                    const t = target ? unwrap(target) : undefined;
+                    if (t && isFn(t)) {
+                        args.forEach((a, i) => {
+                            if (isCtx(a))
+                                enqueue(t, t.params[i]);
+                        });
+                    }
+                }
+                if (callee.type !== "MemberExpression")
+                    return;
+                const method = memberName(callee);
+                const obj = unwrap(callee.object);
+                if (obj.type !== "MemberExpression" || !isCtx(obj.object))
+                    return;
+                const area = memberName(obj);
+                if (area === "http" && method === "route") {
+                    const verb = args[0] ? stringValue(resolve(args[0], decls)) : undefined;
+                    const path = args[1] ? stringValue(resolve(args[1], decls)) : undefined;
+                    if (verb === undefined || path === undefined) {
+                        return dynamic(n, "perm-http", "the route method and path");
+                    }
+                    if (!m.http.has(`${verb} ${path}`)) {
+                        add(n, "perm-http", `Route "${verb} ${path}" is not declared; add it to permissions.http in the extension manifest`);
+                    }
+                }
+                else if (area === "tools" && method === "register") {
+                    const spec = args[0] ? resolve(args[0], decls) : undefined;
+                    const nameProp = spec?.type === "ObjectExpression" ? prop(spec, "name") : undefined;
+                    const name = nameProp ? stringValue(resolve(nameProp.value, decls)) : undefined;
+                    if (name === undefined)
+                        return dynamic(n, "perm-tools", "the tool name");
+                    if (!m.tools.has(name)) {
+                        add(n, "perm-tools", `Tool "${name}" is not declared; add it to permissions.tools in the extension manifest`);
+                    }
+                }
+                else if (area === "ui" && (method === "view" || method === "action")) {
+                    const id = args[0] ? stringValue(resolve(args[0], decls)) : undefined;
+                    if (id === undefined)
+                        return dynamic(n, "perm-ui", `the ctx.ui.${method} id`);
+                    if (!m.uiViews.has(id)) {
+                        add(n, "perm-ui", `UI view "${id}" is not declared; add it to permissions.ui.views (and ui) in the extension manifest`);
+                    }
+                }
+                else if (area === "hooks" && method === "on") {
+                    const mount = args[0] ? stringValue(resolve(args[0], decls)) : undefined;
+                    if (mount === undefined)
+                        return dynamic(n, "perm-hooks", "the hook mount point");
+                    if (!m.hooks.has(mount)) {
+                        add(n, "perm-hooks", `Hook "${mount}" is not declared; add it to permissions.hooks in the extension manifest`);
+                    }
+                    else if (policyMode(args[2], decls) && !m.policyHooks.has(mount)) {
+                        // a non-literal mode is left to the runtime check (ExtensionPermissionError)
+                        add(n, "perm-hooks", `Policy hook "${mount}" is not declared; add it to permissions.policyHooks in the extension manifest`);
+                    }
+                }
+                else if (area === "extensionPoints" && (method === "get" || method === "list")) {
+                    const ref = args[0] ? stringValue(resolve(args[0], decls)) : undefined;
+                    if (ref === undefined)
+                        return dynamic(n, "perm-extension-point", "the extension point ref");
+                    if (!m.caps.has(ref)) {
+                        add(n, "perm-extension-point", `Extension point "${ref}" is not declared; add it to requires or optional in the extension manifest`);
+                    }
+                }
+            }
+            else if (n.type === "MemberExpression" && isCtx(n.object)) {
+                const name = memberName(n);
+                const unconfirmed = (rule, what) => dynamic(n, rule, what);
+                if (name === undefined)
+                    return unconfirmed("perm-reserved", "a computed ctx member");
+                if (name === "secrets" && !m.secrets) {
+                    add(n, "perm-secrets", "ctx.secrets is used but not declared; set permissions.secrets to true in the extension manifest");
+                }
+                else if (name === "storage") {
+                    if (!m.storage) {
+                        add(n, "perm-storage", "ctx.storage is used but not declared; set permissions.storage to true in the extension manifest");
+                    }
+                }
+                else if (name === "models") {
+                    add(n, "perm-reserved", "ctx.models is reserved and not provided in this release; remove the access");
+                }
+                else if (name === "http" ||
+                    name === "tools" ||
+                    name === "extensionPoints" ||
+                    name === "ui" ||
+                    name === "hooks") {
+                    // 只有 ctx.http.route / ctx.tools.register / ctx.extensionPoints.get|list /
+                    // ctx.ui.view|action|invalidate|verifyEmbedToken 能被确认，其余写法无法确认
+                    // (likewise only ctx.hooks.on is confirmable)
+                    const rule = name === "http"
+                        ? "perm-http"
+                        : name === "tools"
+                            ? "perm-tools"
+                            : name === "ui"
+                                ? "perm-ui"
+                                : name === "hooks"
+                                    ? "perm-hooks"
+                                    : "perm-extension-point";
+                    const outer = parent;
+                    const ok = outer?.type === "MemberExpression" &&
+                        outer.object === n &&
+                        ((name === "http" && memberName(outer) === "route") ||
+                            (name === "tools" && memberName(outer) === "register") ||
+                            (name === "hooks" && memberName(outer) === "on") ||
+                            (name === "extensionPoints" && ["get", "list"].includes(memberName(outer) ?? "")) ||
+                            (name === "ui" &&
+                                ["view", "action", "invalidate", "verifyEmbedToken"].includes(memberName(outer) ?? "")));
+                    if (!ok)
+                        unconfirmed(rule, `how ctx.${name} is used`);
+                }
+            }
+        });
+    }
+    return out;
+}
+function scanFile(f) {
+    const decls = buildDecls(f);
+    const out = [];
+    walk(f.program, (n) => {
+        if (n.type !== "CallExpression")
+            return;
+        const callee = unwrap(n.callee);
+        if (callee.type !== "Identifier" || callee.name !== "defineExtension")
+            return;
+        const arg = n.arguments[0];
+        const obj = arg ? resolve(arg, decls) : undefined;
+        if (obj?.type !== "ObjectExpression")
+            return;
+        out.push(...scanSetup(f, readManifest(obj, decls), decls));
+    });
+    return out;
+}
+/**
+ * 插件权限静态检查（AST）：把 setup(ctx) 里对平台能力的访问与 defineExtension 清单比对。规则：
+ * - perm-secrets：用了 ctx.secrets 而 permissions.secrets 不是 true；
+ * - perm-http：ctx.http.route(method, path) 不在 permissions.http 里；
+ * - perm-tools：ctx.tools.register({ name }) 的名字不在 permissions.tools 里；
+ * - perm-extension-point: the ref of ctx.extensionPoints.get|list(ref) is not in requires / optional / provides;
+ * - perm-ui：ctx.ui.view|action(id) 的 id 不在 permissions.ui.views 里；
+ * - perm-storage：用了 ctx.storage 而 permissions.storage 不是 true；
+ * - perm-hooks: the mount point of ctx.hooks.on(mount, …) is not in permissions.hooks (the mount
+ *   point must be a string literal or a same-file const, like the names below), or the options are
+ *   `{ mode: "policy" }` and the mount point is not in permissions.policyHooks;
+ * - perm-reserved：用了尚未提供的 ctx.models。
+ * 路由路径、工具名、能力 ref、界面 id 须是字符串字面量或本文件的 const；动态的写法报「无法静态确认」，
+ * 豁免：`// capybara:allow-dynamic-permission <原因>`（行尾或紧邻上一行，原因必填）。
+ * ctx 会跟踪本地别名，以及按位置传给同文件函数的参数。
+ * 已知缺口（靠评审与运行时 ExtensionPermissionError 兜底）：传给其他文件 / 方法的 ctx、闭包外的重新赋值、
+ * 没有 defineExtension 的辅助文件、permissions 本身是运行时拼出的。
+ * 扫描范围：传入目录下的非测试源码。
+ */
+export function checkPluginPermissions(pluginDirs) {
+    const findings = [];
+    for (const dir of pluginDirs) {
+        for (const { file, isTest } of listSourceFiles(dir)) {
+            if (isTest)
+                continue;
+            const parsed = parseFile(file);
+            if (isParseError(parsed)) {
+                findings.push(parsed);
+                continue;
+            }
+            findings.push(...scanFile(parsed).sort((a, b) => a.line - b.line));
+        }
+    }
+    return findings;
+}

package/dist/check/plugin-state.d.ts

@@ -0,0 +1,19 @@
+import { type Finding } from "./source.js";
+export type { Finding };
+/**
+ * 插件状态检查（AST）。规则：
+ * - plugin-timer：setTimeout / setInterval / setImmediate（含 globalThis.x、别名、timers 模块导入）；
+ * - plugin-module-state：模块顶层 let / var，或 const 初始化为 new Map/Set/WeakMap/WeakSet 或数组字面量。
+ * 豁免：`// capybara:allow-module-state <原因>`（行尾或紧邻上一行，原因必填）。
+ * 定时器识别：标识符引用（含别名赋值）、`x.setTimeout` / `x["setTimeout"]`、解构键
+ * `{ setTimeout: st }`、任何恰好等于定时器名的字符串字面量（含字面量之间的 `+` 拼接，如
+ * `g["set" + "Timeout"]`）、timers 模块导入（import/require/动态 import）。
+ * 扫描范围：插件目录下所有源码，node_modules 任何深度都跳过；dist 与 test/tests/__tests__ 只在插件根跳过
+ * （更深处同名目录照常扫描，否则 `src/test/impl.ts` 就能绕过）；*.test.* / *.spec.* 不扫。
+ *
+ * 已知缺口（M0 不做，靠评审与双副本测试兜底）：顶层对象字面量（`const x = {}`）、`Array.from(...)` /
+ * `Object.create(...)` 等工厂调用、`export default new Map()`、IIFE 闭包里的状态、namespace 内的 let、
+ * 类静态可变字段、块内 `var` 提升、`queueMicrotask` / `process.nextTick` 递归循环、
+ * 含非字面量成分的运行时拼接（变量、函数调用、带插值的模板）与非字面量动态 import。
+ */
+export declare function checkPluginState(pluginDirs: string[]): Finding[];

package/dist/check/plugin-state.js

@@ -0,0 +1,181 @@
+import { collectImports, isParseError, listSourceFiles, parseFile, stringValue, walk, } from "./source.js";
+const TIMERS = new Set(["setTimeout", "setInterval", "setImmediate"]);
+const TIMER_MODULES = new Set(["timers", "node:timers", "timers/promises", "node:timers/promises"]);
+const STATE_CTORS = new Set(["Map", "Set", "WeakMap", "WeakSet"]);
+const MARKER = "capybara:allow-module-state";
+const FIX = "改用 ctx.kv（带 TTL 的共享状态）/ ctx.queue（延迟任务）/ ctx.bus（跨副本通知）";
+const MSG_TIMER = `插件不得使用定时器：定时器只存在于创建它的那个进程，多副本下别的实例停不掉也看不到它。${FIX}`;
+const MSG_STATE = `模块顶层的可变状态只存在于当前进程，多副本下各实例各存一份。${FIX}；确属只读常量请加 // ${MARKER} <原因>`;
+const MSG_REASON = `// ${MARKER} 后必须写明原因（不能为空）`;
+const WRAPPERS = new Set([
+    "ParenthesizedExpression",
+    "TSAsExpression",
+    "TSSatisfiesExpression",
+    "TSNonNullExpression",
+    "TSTypeAssertion",
+]);
+function unwrap(n) {
+    let cur = n;
+    while (WRAPPERS.has(cur.type))
+        cur = cur.expression;
+    return cur;
+}
+/** 初始化表达式是否是 new Map/Set/WeakMap/WeakSet(...)（含 new globalThis.Map）或数组字面量。 */
+function isStateInit(init) {
+    if (!init)
+        return false;
+    const e = unwrap(init);
+    if (e.type === "ArrayExpression")
+        return true;
+    if (e.type !== "NewExpression")
+        return false;
+    const callee = unwrap(e.callee);
+    if (callee.type === "Identifier")
+        return STATE_CTORS.has(callee.name);
+    if (callee.type === "MemberExpression" && !callee.computed) {
+        return STATE_CTORS.has(callee.property.name);
+    }
+    return false;
+}
+/** 找声明上的豁免标记：声明首行/末行的行尾注释，或独占一行、紧邻声明上方的注释。 */
+function findMarker(f, decl) {
+    const first = f.lineOf(decl.start);
+    const last = f.lineOf(decl.end);
+    for (const c of f.comments) {
+        if (c.type !== "Line")
+            continue;
+        const m = new RegExp(`^\\s*${MARKER}(?:\\s+(.*\\S))?\\s*$`).exec(c.value);
+        if (!m)
+            continue;
+        const line = f.lineOf(c.start);
+        const ownLine = f.lineText(line).trimStart().startsWith("//");
+        if (line === first || line === last || (line === first - 1 && ownLine)) {
+            return { reason: m[1] ?? "" };
+        }
+    }
+    return undefined;
+}
+function moduleStateFindings(f) {
+    const out = [];
+    const body = f.program.body ?? [];
+    for (const stmt of body) {
+        const decl = stmt.type === "ExportNamedDeclaration" && stmt.declaration
+            ? stmt.declaration
+            : stmt;
+        if (decl.type !== "VariableDeclaration")
+            continue;
+        const kind = decl.kind;
+        for (const d of decl.declarations) {
+            const flagged = kind === "let" ||
+                kind === "var" ||
+                (kind === "const" && isStateInit(d.init));
+            if (!flagged)
+                continue;
+            const marker = findMarker(f, stmt);
+            const line = f.lineOf(d.start);
+            if (marker?.reason)
+                continue;
+            out.push({
+                file: f.file,
+                line,
+                rule: "plugin-module-state",
+                message: marker ? MSG_REASON : MSG_STATE,
+            });
+        }
+    }
+    return out;
+}
+function timerFindings(f) {
+    const out = [];
+    const add = (n) => out.push({ file: f.file, line: f.lineOf(n.start), rule: "plugin-timer", message: MSG_TIMER });
+    for (const { spec, start } of collectImports(f.program)) {
+        if (TIMER_MODULES.has(spec)) {
+            out.push({ file: f.file, line: f.lineOf(start), rule: "plugin-timer", message: MSG_TIMER });
+        }
+    }
+    walk(f.program, (n, parent, key) => {
+        if (n.type === "Identifier" && TIMERS.has(n.name)) {
+            if (!parent)
+                return;
+            const p = parent;
+            if (p.type === "MemberExpression" && key === "property" && !p.computed)
+                return;
+            if ((p.type === "Property" ||
+                p.type === "PropertyDefinition" ||
+                p.type === "MethodDefinition") &&
+                key === "key" &&
+                !p.computed) {
+                return;
+            }
+            if (p.type.startsWith("TS"))
+                return;
+            if (/^(Import|Export)/.test(p.type))
+                return; // 从 timers 导入的写法由上面的 import 检查报
+            add(n);
+        }
+        else if (n.type === "ObjectPattern") {
+            // const { setTimeout: st } = globalThis：键名指向定时器，改名后就认不出了。
+            for (const prop of n.properties) {
+                const k = prop.type === "Property" ? prop.key : undefined;
+                if (k && !prop.computed && k.type === "Identifier" && TIMERS.has(k.name))
+                    add(k);
+            }
+        }
+        else if (n.type === "Literal" ||
+            n.type === "TemplateLiteral" ||
+            (n.type === "BinaryExpression" && n.operator === "+")) {
+            // 任何恰好等于定时器名的字符串（Reflect.get(globalThis, "setInterval")、globalThis["setTimeout"]），
+            // 含字符串字面量 / 无插值模板的 `+` 拼接（globalThis["set" + "Immediate"]），由 stringValue 求值。
+            // 刻意保守：误报用豁免之外的办法解决——换个写法。
+            const v = stringValue(n);
+            if (v !== undefined && TIMERS.has(v))
+                add(n);
+        }
+        else if (n.type === "MemberExpression" && !n.computed) {
+            const prop = n.property;
+            if (prop.type === "Identifier" && TIMERS.has(prop.name))
+                add(n);
+        }
+    });
+    return out;
+}
+/**
+ * 插件状态检查（AST）。规则：
+ * - plugin-timer：setTimeout / setInterval / setImmediate（含 globalThis.x、别名、timers 模块导入）；
+ * - plugin-module-state：模块顶层 let / var，或 const 初始化为 new Map/Set/WeakMap/WeakSet 或数组字面量。
+ * 豁免：`// capybara:allow-module-state <原因>`（行尾或紧邻上一行，原因必填）。
+ * 定时器识别：标识符引用（含别名赋值）、`x.setTimeout` / `x["setTimeout"]`、解构键
+ * `{ setTimeout: st }`、任何恰好等于定时器名的字符串字面量（含字面量之间的 `+` 拼接，如
+ * `g["set" + "Timeout"]`）、timers 模块导入（import/require/动态 import）。
+ * 扫描范围：插件目录下所有源码，node_modules 任何深度都跳过；dist 与 test/tests/__tests__ 只在插件根跳过
+ * （更深处同名目录照常扫描，否则 `src/test/impl.ts` 就能绕过）；*.test.* / *.spec.* 不扫。
+ *
+ * 已知缺口（M0 不做，靠评审与双副本测试兜底）：顶层对象字面量（`const x = {}`）、`Array.from(...)` /
+ * `Object.create(...)` 等工厂调用、`export default new Map()`、IIFE 闭包里的状态、namespace 内的 let、
+ * 类静态可变字段、块内 `var` 提升、`queueMicrotask` / `process.nextTick` 递归循环、
+ * 含非字面量成分的运行时拼接（变量、函数调用、带插值的模板）与非字面量动态 import。
+ */
+export function checkPluginState(pluginDirs) {
+    const findings = [];
+    for (const dir of pluginDirs) {
+        for (const { file, isTest } of listSourceFiles(dir)) {
+            if (isTest)
+                continue;
+            const parsed = parseFile(file);
+            if (isParseError(parsed)) {
+                findings.push(parsed);
+                continue;
+            }
+            const all = [...moduleStateFindings(parsed), ...timerFindings(parsed)];
+            all.sort((a, b) => a.line - b.line);
+            const seen = new Set();
+            for (const x of all) {
+                const k = `${x.line}|${x.rule}`;
+                if (!seen.has(k))
+                    findings.push(x);
+                seen.add(k);
+            }
+        }
+    }
+    return findings;
+}

package/dist/check/plugin-versions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `changeset version` bumps only a plugin's `package.json`, but the packer (and the SDK's
+ * package validation) requires the same version in `.capybara-plugin/plugin.json` and in the
+ * extension manifest (`src/index.ts`, `version: "x"`). `pnpm version-packages` (what the Version
+ * Packages PR runs) calls this right after `changeset version`, before the bootstrap pins are
+ * rewritten (`check:bootstrap --write`), since the packed bytes include the version.
+ *
+ * `pluginDirs` defaults to the plugins {@link discoverPlugins} finds under `root`. Returns the files
+ * it changed, relative to `root` (POSIX). Throws when an extension's `src/index.ts`
+ * does not have exactly one `  version: "..."` line, so a reformatted manifest fails loudly
+ * instead of being left stale.
+ */
+export declare function syncPluginVersions(root: string, pluginDirs?: string[]): string[];

package/dist/check/plugin-versions.js

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { discoverPlugins } from "../discover.js";
+/** The one top-level `version: "x"` line of an extension's `defineExtension({...})` manifest. */
+const MANIFEST_VERSION_RE = /^( {2}version: ")([^"]+)(",)$/gm;
+/**
+ * `changeset version` bumps only a plugin's `package.json`, but the packer (and the SDK's
+ * package validation) requires the same version in `.capybara-plugin/plugin.json` and in the
+ * extension manifest (`src/index.ts`, `version: "x"`). `pnpm version-packages` (what the Version
+ * Packages PR runs) calls this right after `changeset version`, before the bootstrap pins are
+ * rewritten (`check:bootstrap --write`), since the packed bytes include the version.
+ *
+ * `pluginDirs` defaults to the plugins {@link discoverPlugins} finds under `root`. Returns the files
+ * it changed, relative to `root` (POSIX). Throws when an extension's `src/index.ts`
+ * does not have exactly one `  version: "..."` line, so a reformatted manifest fails loudly
+ * instead of being left stale.
+ */
+export function syncPluginVersions(root, pluginDirs = discoverPlugins(root)) {
+    const changed = [];
+    const rel = (p) => relative(root, p).split("\\").join("/");
+    for (const dir of pluginDirs) {
+        const pkgFile = join(dir, "package.json");
+        if (!existsSync(pkgFile))
+            continue;
+        const version = JSON.parse(readFileSync(pkgFile, "utf8")).version;
+        if (typeof version !== "string")
+            continue;
+        const manifestFile = join(dir, ".capybara-plugin/plugin.json");
+        const manifestRel = rel(manifestFile);
+        if (existsSync(manifestFile)) {
+            const text = readFileSync(manifestFile, "utf8");
+            const json = JSON.parse(text);
+            if (json.version !== version) {
+                json.version = version;
+                writeFileSync(manifestFile, `${JSON.stringify(json, null, 2)}\n`);
+                changed.push(manifestRel);
+            }
+        }
+        const srcFile = join(dir, "src/index.ts");
+        const srcRel = rel(srcFile);
+        if (existsSync(srcFile)) {
+            const text = readFileSync(srcFile, "utf8");
+            const matches = [...text.matchAll(MANIFEST_VERSION_RE)];
+            if (matches.length !== 1) {
+                throw new Error(`${srcRel}: expected exactly one top-level \`  version: "..."\` line in the extension manifest, found ${matches.length}`);
+            }
+            if (matches[0]?.[2] !== version) {
+                writeFileSync(srcFile, text.replace(MANIFEST_VERSION_RE, (_m, pre, _old, post) => {
+                    return `${pre}${version}${post}`;
+                }));
+                changed.push(srcRel);
+            }
+        }
+    }
+    return changed;
+}