cj-tauri 2.0.0 → 2.1.1

package/src/plugin.cj

@@ -1,333 +1,333 @@
-package cjTauri
-
-import std.collection.*
-import std.sort.*
-import stdx.encoding.json.*
-
-/**
- * 插件（对标 Tauri v2 的 plugin，设计见 docs/RFC-插件体系.md）
- *
- * 一个插件 = 一组命令（全名 `<插件名>:<短名>`）+ 可选事件 + 可选前端 JS 片段。
- * 权限仍由应用的 capabilities 目录里的 json 决定：插件只声明「我提供什么」，**不自动放行**，
- * 默认最小权限不被破坏（RFC §5.3 的取舍 B）。
- *
- * 装配（必须在 run() / runUrl() 之前——页面加载前命令表要定稿）：
- *   TauriApp().plugin(FsPlugin())
- *
- * 命令全名与内置的 system:* 同形，所以 IpcHub 分发与 Capability 校验零改动。
- * 接口带默认实现，插件作者通常只写 name() 与 commands()。
- */
-public interface Plugin {
-    /** 插件名：作为命令/事件的命名空间（如 "fs"），不得为空、不得含 ':' */
-    func name(): String
-
-    /** 命令短名 → 处理器；框架注册为 "<插件名>:<短名>" */
-    func commands(): HashMap<String, CommandHandler>
-
-    /** 可能推送的事件短名；框架登记为 "<插件名>:<短名>"，用于缺权限提示。默认无事件 */
-    func events(): ArrayList<String> {
-        return ArrayList<String>()
-    }
-
-    /** 前端 JS 片段：定义 window.__CJ_TAURI__.<插件名>；没有就返回空串 */
-    func jsShim(): String {
-        return ""
-    }
-
-    /** 初始化：记录 app 引用、做一次性准备。默认空实现 */
-    func setup(app: TauriApp): Unit { let _ = app }
-
-    /**
-     * 命名权限集（v1.1）：短集名 → 成员（写短名会自动补 "<插件名>:"，写全名则原样保留）。
-     * 应用在 capabilities 的 permissions 里按 "<插件名>:<短集名>" 引用，一次放行一组。
-     * 默认无。**集声明不等于放行**——清单不引用它，一条也不会生效。
-     */
-    func permissions(): HashMap<String, ArrayList<String>> {
-        return HashMap<String, ArrayList<String>>()
-    }
-
-    /**
-     * 本插件是否吃「路径 scope」这层校验（RFC-003 第 4 期，默认 false）。
-     *
-     * 声明 true 意味着：命令里带路径的参数一律经 `IpcContext.resolveScopedPath(插件名, 路径)` 取值
-     * （越界即拒），且清单没为它写 scopes 时框架会在启动时提示「按旧行为全量放行」。
-     * 为什么不由框架猜「哪个参数是路径」：只有插件自己知道参数语义，猜出来的白名单等于没有白名单。
-     */
-    func scopeAware(): Bool {
-        return false
-    }
-
-    /**
-     * 自描述（批次 3，RFC §4.6.7）：供 sync/check 三方比对的静态数据。
-     * 默认实现 = 全宿主、无能力依赖（多数插件无需覆盖）；
-     * 有平台约束的插件必须覆盖（如 SqlitePlugin 只支持 webkitgtk）。
-     *
-     * v1 曾结论「不加接口方法」（数据可从 commands()/events()/permissions() 推出）；
-     * 批次 3 改自描述双通道——supportedHosts / requiredCapabilities 是命令表推不出来的
-     * 语义信息，只能由插件自报。
-     */
-    func describe(): PluginManifest {
-        return PluginManifest(ArrayList<String>(), ArrayList<String>())
-    }
-}
-
-/**
- * 插件自描述（批次 3，RFC §4.6.7）：供 sync/check 三方比对的静态数据。
- *
- * - supportedHosts：插件实际支持的 hostKind 列表；空 = 全宿主。
- *   不在列表的宿主上，插件必须以桩如实失败「端不支持」（P-2），不得静默缺失；
- * - requiredCapabilities：插件依赖的能力清单 identifier；空 = 无依赖。
- *   check 拿它与 capabilities 目录的 identifier 交叉比对（缺声明 = 失败）。
- */
-public class PluginManifest {
-    public let supportedHosts: ArrayList<String>
-    public let requiredCapabilities: ArrayList<String>
-
-    public init(supportedHosts: ArrayList<String>, requiredCapabilities: ArrayList<String>) {
-        this.supportedHosts = supportedHosts
-        this.requiredCapabilities = requiredCapabilities
-    }
-}
-
-/**
- * 插件名是否合法：非空且不含全/半角冒号。
- * 冒号是命名空间分隔符，混进来会让 "<插件名>:<短名>" 无法解析、权限也写不清。
- */
-public func isValidPluginName(name: String): Bool {
-    if (name.size == 0) {
-        return false
-    }
-    return !name.contains(":") && !name.contains("：")
-}
-
-/** 某插件的命令全名列表（`<插件名>:<短名>`） */
-public func pluginCommandNames(p: Plugin): ArrayList<String> {
-    let names = ArrayList<String>()
-    for ((short, _) in p.commands()) {
-        names.add("${p.name()}:${short}")
-    }
-    return names
-}
-
-/** 某插件的事件全名列表（`<插件名>:<短名>`） */
-public func pluginEventNames(p: Plugin): ArrayList<String> {
-    let names = ArrayList<String>()
-    for (short in p.events()) {
-        names.add("${p.name()}:${short}")
-    }
-    return names
-}
-
-/** 把插件的命令按 "<插件名>:<短名>" 注册进 hub（TauriApp.prepare 与测试共用） */
-public func registerPluginCommands(hub: IpcHub, p: Plugin): Unit {
-    for ((short, handler) in p.commands()) {
-        hub.register("${p.name()}:${short}", handler)
-    }
-}
-
-/** 某插件的命名权限集：`<插件名>:<短集名>` → 展开后的成员全名列表 */
-public func pluginPermissionSets(p: Plugin): HashMap<String, ArrayList<String>> {
-    let out = HashMap<String, ArrayList<String>>()
-    for ((shortSet, members) in p.permissions()) {
-        let expanded = ArrayList<String>()
-        for (m in members) {
-            if (m.contains(":")) {
-                expanded.add(m)
-            } else {
-                expanded.add("${p.name()}:${m}")
-            }
-        }
-        out.add("${p.name()}:${shortSet}", expanded)
-    }
-    return out
-}
-
-/** 把插件的命名权限集注册进能力注册中心（TauriApp.prepare 与测试共用） */
-public func registerPluginPermissionSets(reg: CapabilityRegistry, p: Plugin): Unit {
-    for ((setName, members) in pluginPermissionSets(p)) {
-        reg.addPermissionSet(setName, members)
-    }
-}
-
-/** 人类可读的命名权限集清单（启动日志用）；一个集都没有时返回空串 */
-public func describePermissionSets(plugins: ArrayList<Plugin>): String {
-    var text = ""
-    for (p in plugins) {
-        for ((setName, members) in pluginPermissionSets(p)) {
-            var list = ""
-            for (m in members) {
-                if (list.size > 0) {
-                    list += ", "
-                }
-                list += m
-            }
-            text += "  ${setName}  ${list}\n"
-        }
-    }
-    return text
-}
-
-/**
- * 收集各插件的 jsShim，作为「预执行脚本」逐条返回（一个插件一段，顺序 = 装配顺序）
- *
- * v2 方案（RFC §5.4）：不再把 shim 拼成 script 标签塞进 HTML——那段字符串操作对畸形 HTML 不健壮，
- * 而且 runUrl 的页面 HTML 根本不在本进程、拼不进去。改为交给宿主的 addInitScript，两平台都以
- * document-start 注入，HTML / URL 两种来源一视同仁。
- * 一个插件一段（而不是拼成一整段）：某个插件的 shim 写坏了不会带崩其它插件的命名空间。
- */
-public func pluginInitScripts(plugins: ArrayList<Plugin>): ArrayList<String> {
-    let out = ArrayList<String>()
-    for (p in plugins) {
-        let shim = p.jsShim()
-        if (shim.size > 0) {
-            out.add(shim)
-        }
-    }
-    return out
-}
-
-/** 人类可读的插件清单（启动日志用，对齐 RFC §5.5 的打印形态） */
-public func describePlugins(plugins: ArrayList<Plugin>): String {
-    var text = ""
-    for (p in plugins) {
-        var cmds = ""
-        for (n in pluginCommandNames(p)) {
-            if (cmds.size > 0) {
-                cmds += ", "
-            }
-            cmds += n
-        }
-        text += "  ${p.name()}  ${cmds}"
-        let evts = pluginEventNames(p)
-        if (evts.size > 0) {
-            text += "  events: "
-            var first = true
-            for (n in evts) {
-                if (!first) {
-                    text += ", "
-                }
-                text += n
-                first = false
-            }
-        }
-        text += "\n"
-    }
-    return text
-}
-
-/**
- * 机器可读的插件清单（RFC §8 第 7 条的答案 C：给工具/CI 用，**不动 Plugin 接口**）
- *
- * 形态 `[{name, commands, events, permissions, hasShim}, ...]`：
- *   - `commands` / `events`：全名数组（`<插件名>:<短名>`，与 IPC 注册名、能力清单里写的名字一致）
- *   - `permissions`：集全名 → 成员全名数组（**框架展开后**的样子，也就是清单里能引用的名字）
- *   - `hasShim`：是否带前端 JS 片段（工具据此判断要不要等 `__CJ_TAURI__.<插件名>`）
- * 数组与权限键都按字典序排：HashMap 迭代顺序不定，工具的输出 / diff 需要稳定。
- *
- * 数据来自 describe()（批次 3 自描述双通道）：命令/事件/权限集之外，携带 supportedHosts /
- * requiredCapabilities 两个命令表推不出来的语义项（RFC §4.6.7）。
- */
-public func describePluginsJson(plugins: ArrayList<Plugin>): JsonValue {
-    let arr = ArrayList<JsonValue>()
-    for (p in plugins) {
-        var obj = JsonObject()
-        let d = p.describe()
-        obj.put("name", JsonString(p.name()))
-        obj.put("commands", jsonStringArray(pluginCommandNames(p)))
-        obj.put("events", jsonStringArray(pluginEventNames(p)))
-        obj.put("permissions", jsonPermissionSets(p))
-        obj.put("hasShim", JsonBool(p.jsShim().size > 0))
-        obj.put("supportedHosts", jsonStringArray(d.supportedHosts))
-        obj.put("requiredCapabilities", jsonStringArray(d.requiredCapabilities))
-        arr.add(obj)
-    }
-    return JsonArray(arr)
-}
-
-/** 字符串数组 → JSON 数组，元素按字典序（HashMap 来的一律先排序，保证输出稳定） */
-func jsonStringArray(items: ArrayList<String>): JsonValue {
-    let sorted = sortedStrings(items)
-    let arr = ArrayList<JsonValue>()
-    for (s in sorted) {
-        arr.add(JsonString(s))
-    }
-    return JsonArray(arr)
-}
-
-/** 命名权限集 → JSON 对象（键 = 集全名，值 = 成员全名数组）；键也按字典序 */
-func jsonPermissionSets(p: Plugin): JsonValue {
-    let sets = pluginPermissionSets(p)
-    let keys = ArrayList<String>()
-    for ((setName, _) in sets) {
-        keys.add(setName)
-    }
-    var obj = JsonObject()
-    for (setName in sortedStrings(keys)) {
-        match (sets.get(setName)) {
-            case Some(members) => obj.put(setName, jsonStringArray(members))
-            case None => ()
-        }
-    }
-    return obj
-}
-
-/** 复制一份并按字典序排序（不改动入参；元素量级只有每插件的几条命令，开销可忽略） */
-func sortedStrings(items: ArrayList<String>): ArrayList<String> {
-    let out = ArrayList<String>()
-    for (s in items) {
-        out.add(s)
-    }
-    sort(out)
-    return out
-}
-
-/**
- * 未授权提示：插件声明了、但应用的能力清单没放行时，说清缺哪条、加到哪去。
- * 只提示、不改权限——放行与否仍由 capabilities 决定（RFC §5.3 的取舍 B）。
- * 调用时机：能力清单加载完成之后、页面加载之前（TauriApp.prepare）。
- */
-public func warnUnauthorizedPlugins(plugins: ArrayList<Plugin>, caps: CapabilityRegistry): Unit {
-    for (p in plugins) {
-        for (name in pluginCommandNames(p)) {
-            if (!caps.canInvoke(name)) {
-                eprintln("[cj-tauri] 插件 ${p.name()} 的命令 ${name} 尚未授权，前端调用会被拒绝")
-                eprintln("[cj-tauri]   请在 capabilities 目录的 json 里把 \"${name}\" 加进 commands")
-            }
-        }
-        for (name in pluginEventNames(p)) {
-            if (!caps.canEmit(name)) {
-                eprintln("[cj-tauri] 插件 ${p.name()} 的事件 ${name} 尚未授权，推送会被丢弃")
-                eprintln("[cj-tauri]   请在 capabilities 目录的 json 里把 \"${name}\" 加进 events")
-            }
-        }
-    }
-}
-
-/**
- * 提示「吃 scope 的插件没有被声明 scope」——旧清单缺省行为：全量放行（RFC-003 第 4 期）。
- *
- * 只在「该插件至少有一条命令被授权」时提示：没用到它的应用不必被这行日志打扰。
- * 声明了 scope 的插件（caps.hasScopeForPlugin 为真）不提示。
- */
-public func warnUnscopedPlugins(plugins: ArrayList<Plugin>, caps: CapabilityRegistry): Unit {
-    for (p in plugins) {
-        if (!p.scopeAware()) {
-            continue
-        }
-        var authorized = false
-        for (name in pluginCommandNames(p)) {
-            if (caps.canInvoke(name)) {
-                authorized = true
-                break
-            }
-        }
-        if (!authorized) {
-            continue
-        }
-        if (caps.hasScopeForPlugin(p.name())) {
-            continue
-        }
-        eprintln("[cj-tauri] 插件 ${p.name()} 的路径参数未声明 scope：按旧行为全量放行")
-        eprintln("[cj-tauri]   建议在 capabilities 的 json 里加 \"scopes\": { \"${p.name()}\": { \"allow\": [\"<放行路径>\"] } }")
-    }
-}
+package cjTauri
+
+import std.collection.*
+import std.sort.*
+import stdx.encoding.json.*
+
+/**
+ * 插件（对标 Tauri v2 的 plugin，设计见 docs/RFC-插件体系.md）
+ *
+ * 一个插件 = 一组命令（全名 `<插件名>:<短名>`）+ 可选事件 + 可选前端 JS 片段。
+ * 权限仍由应用的 capabilities 目录里的 json 决定：插件只声明「我提供什么」，**不自动放行**，
+ * 默认最小权限不被破坏（RFC §5.3 的取舍 B）。
+ *
+ * 装配（必须在 run() / runUrl() 之前——页面加载前命令表要定稿）：
+ *   TauriApp().plugin(FsPlugin())
+ *
+ * 命令全名与内置的 system:* 同形，所以 IpcHub 分发与 Capability 校验零改动。
+ * 接口带默认实现，插件作者通常只写 name() 与 commands()。
+ */
+public interface Plugin {
+    /** 插件名：作为命令/事件的命名空间（如 "fs"），不得为空、不得含 ':' */
+    func name(): String
+
+    /** 命令短名 → 处理器；框架注册为 "<插件名>:<短名>" */
+    func commands(): HashMap<String, CommandHandler>
+
+    /** 可能推送的事件短名；框架登记为 "<插件名>:<短名>"，用于缺权限提示。默认无事件 */
+    func events(): ArrayList<String> {
+        return ArrayList<String>()
+    }
+
+    /** 前端 JS 片段：定义 window.__CJ_TAURI__.<插件名>；没有就返回空串 */
+    func jsShim(): String {
+        return ""
+    }
+
+    /** 初始化：记录 app 引用、做一次性准备。默认空实现 */
+    func setup(app: TauriApp): Unit { let _ = app }
+
+    /**
+     * 命名权限集（v1.1）：短集名 → 成员（写短名会自动补 "<插件名>:"，写全名则原样保留）。
+     * 应用在 capabilities 的 permissions 里按 "<插件名>:<短集名>" 引用，一次放行一组。
+     * 默认无。**集声明不等于放行**——清单不引用它，一条也不会生效。
+     */
+    func permissions(): HashMap<String, ArrayList<String>> {
+        return HashMap<String, ArrayList<String>>()
+    }
+
+    /**
+     * 本插件是否吃「路径 scope」这层校验（RFC-003 第 4 期，默认 false）。
+     *
+     * 声明 true 意味着：命令里带路径的参数一律经 `IpcContext.resolveScopedPath(插件名, 路径)` 取值
+     * （越界即拒），且清单没为它写 scopes 时框架会在启动时提示「按旧行为全量放行」。
+     * 为什么不由框架猜「哪个参数是路径」：只有插件自己知道参数语义，猜出来的白名单等于没有白名单。
+     */
+    func scopeAware(): Bool {
+        return false
+    }
+
+    /**
+     * 自描述（批次 3，RFC §4.6.7）：供 sync/check 三方比对的静态数据。
+     * 默认实现 = 全宿主、无能力依赖（多数插件无需覆盖）；
+     * 有平台约束的插件必须覆盖（如 SqlitePlugin 只支持 webkitgtk）。
+     *
+     * v1 曾结论「不加接口方法」（数据可从 commands()/events()/permissions() 推出）；
+     * 批次 3 改自描述双通道——supportedHosts / requiredCapabilities 是命令表推不出来的
+     * 语义信息，只能由插件自报。
+     */
+    func describe(): PluginManifest {
+        return PluginManifest(ArrayList<String>(), ArrayList<String>())
+    }
+}
+
+/**
+ * 插件自描述（批次 3，RFC §4.6.7）：供 sync/check 三方比对的静态数据。
+ *
+ * - supportedHosts：插件实际支持的 hostKind 列表；空 = 全宿主。
+ *   不在列表的宿主上，插件必须以桩如实失败「端不支持」（P-2），不得静默缺失；
+ * - requiredCapabilities：插件依赖的能力清单 identifier；空 = 无依赖。
+ *   check 拿它与 capabilities 目录的 identifier 交叉比对（缺声明 = 失败）。
+ */
+public class PluginManifest {
+    public let supportedHosts: ArrayList<String>
+    public let requiredCapabilities: ArrayList<String>
+
+    public init(supportedHosts: ArrayList<String>, requiredCapabilities: ArrayList<String>) {
+        this.supportedHosts = supportedHosts
+        this.requiredCapabilities = requiredCapabilities
+    }
+}
+
+/**
+ * 插件名是否合法：非空且不含全/半角冒号。
+ * 冒号是命名空间分隔符，混进来会让 "<插件名>:<短名>" 无法解析、权限也写不清。
+ */
+public func isValidPluginName(name: String): Bool {
+    if (name.size == 0) {
+        return false
+    }
+    return !name.contains(":") && !name.contains("：")
+}
+
+/** 某插件的命令全名列表（`<插件名>:<短名>`） */
+public func pluginCommandNames(p: Plugin): ArrayList<String> {
+    let names = ArrayList<String>()
+    for ((short, _) in p.commands()) {
+        names.add("${p.name()}:${short}")
+    }
+    return names
+}
+
+/** 某插件的事件全名列表（`<插件名>:<短名>`） */
+public func pluginEventNames(p: Plugin): ArrayList<String> {
+    let names = ArrayList<String>()
+    for (short in p.events()) {
+        names.add("${p.name()}:${short}")
+    }
+    return names
+}
+
+/** 把插件的命令按 "<插件名>:<短名>" 注册进 hub（TauriApp.prepare 与测试共用） */
+public func registerPluginCommands(hub: IpcHub, p: Plugin): Unit {
+    for ((short, handler) in p.commands()) {
+        hub.register("${p.name()}:${short}", handler)
+    }
+}
+
+/** 某插件的命名权限集：`<插件名>:<短集名>` → 展开后的成员全名列表 */
+public func pluginPermissionSets(p: Plugin): HashMap<String, ArrayList<String>> {
+    let out = HashMap<String, ArrayList<String>>()
+    for ((shortSet, members) in p.permissions()) {
+        let expanded = ArrayList<String>()
+        for (m in members) {
+            if (m.contains(":")) {
+                expanded.add(m)
+            } else {
+                expanded.add("${p.name()}:${m}")
+            }
+        }
+        out.add("${p.name()}:${shortSet}", expanded)
+    }
+    return out
+}
+
+/** 把插件的命名权限集注册进能力注册中心（TauriApp.prepare 与测试共用） */
+public func registerPluginPermissionSets(reg: CapabilityRegistry, p: Plugin): Unit {
+    for ((setName, members) in pluginPermissionSets(p)) {
+        reg.addPermissionSet(setName, members)
+    }
+}
+
+/** 人类可读的命名权限集清单（启动日志用）；一个集都没有时返回空串 */
+public func describePermissionSets(plugins: ArrayList<Plugin>): String {
+    var text = ""
+    for (p in plugins) {
+        for ((setName, members) in pluginPermissionSets(p)) {
+            var list = ""
+            for (m in members) {
+                if (list.size > 0) {
+                    list += ", "
+                }
+                list += m
+            }
+            text += "  ${setName}  ${list}\n"
+        }
+    }
+    return text
+}
+
+/**
+ * 收集各插件的 jsShim，作为「预执行脚本」逐条返回（一个插件一段，顺序 = 装配顺序）
+ *
+ * v2 方案（RFC §5.4）：不再把 shim 拼成 script 标签塞进 HTML——那段字符串操作对畸形 HTML 不健壮，
+ * 而且 runUrl 的页面 HTML 根本不在本进程、拼不进去。改为交给宿主的 addInitScript，两平台都以
+ * document-start 注入，HTML / URL 两种来源一视同仁。
+ * 一个插件一段（而不是拼成一整段）：某个插件的 shim 写坏了不会带崩其它插件的命名空间。
+ */
+public func pluginInitScripts(plugins: ArrayList<Plugin>): ArrayList<String> {
+    let out = ArrayList<String>()
+    for (p in plugins) {
+        let shim = p.jsShim()
+        if (shim.size > 0) {
+            out.add(shim)
+        }
+    }
+    return out
+}
+
+/** 人类可读的插件清单（启动日志用，对齐 RFC §5.5 的打印形态） */
+public func describePlugins(plugins: ArrayList<Plugin>): String {
+    var text = ""
+    for (p in plugins) {
+        var cmds = ""
+        for (n in pluginCommandNames(p)) {
+            if (cmds.size > 0) {
+                cmds += ", "
+            }
+            cmds += n
+        }
+        text += "  ${p.name()}  ${cmds}"
+        let evts = pluginEventNames(p)
+        if (evts.size > 0) {
+            text += "  events: "
+            var first = true
+            for (n in evts) {
+                if (!first) {
+                    text += ", "
+                }
+                text += n
+                first = false
+            }
+        }
+        text += "\n"
+    }
+    return text
+}
+
+/**
+ * 机器可读的插件清单（RFC §8 第 7 条的答案 C：给工具/CI 用，**不动 Plugin 接口**）
+ *
+ * 形态 `[{name, commands, events, permissions, hasShim}, ...]`：
+ *   - `commands` / `events`：全名数组（`<插件名>:<短名>`，与 IPC 注册名、能力清单里写的名字一致）
+ *   - `permissions`：集全名 → 成员全名数组（**框架展开后**的样子，也就是清单里能引用的名字）
+ *   - `hasShim`：是否带前端 JS 片段（工具据此判断要不要等 `__CJ_TAURI__.<插件名>`）
+ * 数组与权限键都按字典序排：HashMap 迭代顺序不定，工具的输出 / diff 需要稳定。
+ *
+ * 数据来自 describe()（批次 3 自描述双通道）：命令/事件/权限集之外，携带 supportedHosts /
+ * requiredCapabilities 两个命令表推不出来的语义项（RFC §4.6.7）。
+ */
+public func describePluginsJson(plugins: ArrayList<Plugin>): JsonValue {
+    let arr = ArrayList<JsonValue>()
+    for (p in plugins) {
+        var obj = JsonObject()
+        let d = p.describe()
+        obj.put("name", JsonString(p.name()))
+        obj.put("commands", jsonStringArray(pluginCommandNames(p)))
+        obj.put("events", jsonStringArray(pluginEventNames(p)))
+        obj.put("permissions", jsonPermissionSets(p))
+        obj.put("hasShim", JsonBool(p.jsShim().size > 0))
+        obj.put("supportedHosts", jsonStringArray(d.supportedHosts))
+        obj.put("requiredCapabilities", jsonStringArray(d.requiredCapabilities))
+        arr.add(obj)
+    }
+    return JsonArray(arr)
+}
+
+/** 字符串数组 → JSON 数组，元素按字典序（HashMap 来的一律先排序，保证输出稳定） */
+func jsonStringArray(items: ArrayList<String>): JsonValue {
+    let sorted = sortedStrings(items)
+    let arr = ArrayList<JsonValue>()
+    for (s in sorted) {
+        arr.add(JsonString(s))
+    }
+    return JsonArray(arr)
+}
+
+/** 命名权限集 → JSON 对象（键 = 集全名，值 = 成员全名数组）；键也按字典序 */
+func jsonPermissionSets(p: Plugin): JsonValue {
+    let sets = pluginPermissionSets(p)
+    let keys = ArrayList<String>()
+    for ((setName, _) in sets) {
+        keys.add(setName)
+    }
+    var obj = JsonObject()
+    for (setName in sortedStrings(keys)) {
+        match (sets.get(setName)) {
+            case Some(members) => obj.put(setName, jsonStringArray(members))
+            case None => ()
+        }
+    }
+    return obj
+}
+
+/** 复制一份并按字典序排序（不改动入参；元素量级只有每插件的几条命令，开销可忽略） */
+func sortedStrings(items: ArrayList<String>): ArrayList<String> {
+    let out = ArrayList<String>()
+    for (s in items) {
+        out.add(s)
+    }
+    sort(out)
+    return out
+}
+
+/**
+ * 未授权提示：插件声明了、但应用的能力清单没放行时，说清缺哪条、加到哪去。
+ * 只提示、不改权限——放行与否仍由 capabilities 决定（RFC §5.3 的取舍 B）。
+ * 调用时机：能力清单加载完成之后、页面加载之前（TauriApp.prepare）。
+ */
+public func warnUnauthorizedPlugins(plugins: ArrayList<Plugin>, caps: CapabilityRegistry): Unit {
+    for (p in plugins) {
+        for (name in pluginCommandNames(p)) {
+            if (!caps.canInvoke(name)) {
+                eprintln("[cj-tauri] 插件 ${p.name()} 的命令 ${name} 尚未授权，前端调用会被拒绝")
+                eprintln("[cj-tauri]   请在 capabilities 目录的 json 里把 \"${name}\" 加进 commands")
+            }
+        }
+        for (name in pluginEventNames(p)) {
+            if (!caps.canEmit(name)) {
+                eprintln("[cj-tauri] 插件 ${p.name()} 的事件 ${name} 尚未授权，推送会被丢弃")
+                eprintln("[cj-tauri]   请在 capabilities 目录的 json 里把 \"${name}\" 加进 events")
+            }
+        }
+    }
+}
+
+/**
+ * 提示「吃 scope 的插件没有被声明 scope」——旧清单缺省行为：全量放行（RFC-003 第 4 期）。
+ *
+ * 只在「该插件至少有一条命令被授权」时提示：没用到它的应用不必被这行日志打扰。
+ * 声明了 scope 的插件（caps.hasScopeForPlugin 为真）不提示。
+ */
+public func warnUnscopedPlugins(plugins: ArrayList<Plugin>, caps: CapabilityRegistry): Unit {
+    for (p in plugins) {
+        if (!p.scopeAware()) {
+            continue
+        }
+        var authorized = false
+        for (name in pluginCommandNames(p)) {
+            if (caps.canInvoke(name)) {
+                authorized = true
+                break
+            }
+        }
+        if (!authorized) {
+            continue
+        }
+        if (caps.hasScopeForPlugin(p.name())) {
+            continue
+        }
+        eprintln("[cj-tauri] 插件 ${p.name()} 的路径参数未声明 scope：按旧行为全量放行")
+        eprintln("[cj-tauri]   建议在 capabilities 的 json 里加 \"scopes\": { \"${p.name()}\": { \"allow\": [\"<放行路径>\"] } }")
+    }
+}