cj-tauri 1.1.2 → 2.0.0

package/src/platform_host_provider.cj

@@ -0,0 +1,87 @@
+package cjTauri
+
+import std.collection.ArrayList
+import cjTauri.platform.*
+
+/**
+ * 宿主提供者注册表（RFC-002 §5.1）——多宿主入口，取代早期的单槽注入
+ *
+ * 为什么是"优先级"而不是布尔匹配：同一 os 下会有多个宿主——鸿蒙 ArkWeb 与
+ * ARM64 Linux 桌面的 os 都报 Linux，Android 与 Linux 同理；整数优先级让
+ * 「专用实现压过通用实现」成为数据而不是 if 顺序。
+ *
+ * 早期的单槽注入（`setHostFactory` / `requireInjectedHost`）已删除：装配层只经本注册表
+ * 取宿主，`resolveHost` 优先注册表、没有匹配者才回落内置宿主（见 host.cj 的 createHost）。
+ */
+public interface HostProvider {
+    /** 0 = 不匹配；>0 越大越优先 */
+    func priority(target: TargetInfo): Int64
+    /** 一个 label 一个宿主实例（多窗口事件按 label 路由，见 host.cj HostRoute） */
+    func create(label: String, target: TargetInfo): WebViewHost
+}
+
+private var HOST_PROVIDERS: ArrayList<HostProvider> = ArrayList<HostProvider>()
+
+/** 注册宿主提供者：**必须在构造 TauriApp() 之前**（宿主在字段初始化时就创建，
+ *  与内置宿主同一约束）；幂等性由调用方保证，重复注册按优先级取胜者。
+ *  返回注册下标（测试反注册用） */
+public func registerHost(provider: HostProvider): Int64 {
+    let idx = HOST_PROVIDERS.size
+    HOST_PROVIDERS.add(provider)
+    return idx
+}
+
+/** 已注册数量（自检 / 测试用） */
+public func hostProviderCount(): Int64 {
+    return HOST_PROVIDERS.size
+}
+
+/**
+ * 反注册（测试用）：全局注册表是进程级的，用例注册的探针宿主不清走会污染后续用例
+ * （优先级平局 / 抢占都取决于注册先后）。业务侧没有场景该调它。
+ * 接口引用没有可用的相等比较（`!=` 与 `equal` 都不提供），所以按注册下标定位。
+ */
+public func unregisterHost(index: Int64): Unit {
+    if (index >= 0 && index < HOST_PROVIDERS.size) {
+        // remove 收区间（start 含、end 不含）：单元素 = index..index+1
+        HOST_PROVIDERS.remove(index..index + 1)
+    }
+}
+
+/**
+ * 按 TargetInfo 选出优先级最高的宿主并创建
+ *
+ * 框架内部装配用（批次 1 的 createHost 会走这里）；没有匹配者返回 None，
+ * 由调用方给出可照做的错误——与宿主装配「不静默回落」同一约定。
+ */
+public func pickHost(label: String, target: TargetInfo): Option<WebViewHost> {
+    var best: Option<HostProvider> = None
+    var bestPriority: Int64 = 0
+    for (p in HOST_PROVIDERS) {
+        let pr = p.priority(target)
+        if (pr > bestPriority) {
+            bestPriority = pr
+            best = Some(p)
+        }
+    }
+    match (best) {
+        case Some(p) => return Some(p.create(label, target))
+        case None => return None
+    }
+}
+
+/**
+ * 装配层的宿主解析（批次 1 接线，RFC §5.4）：注册表优先，内置实现兜底
+ *
+ * app.cj 的 TauriApp 构造与 addWindow 都走这里；原有 @When 门禁的 createHost
+ * 三分支原样保留为兜底（桌面 WebKit/WebView2、鸿蒙 ArkWeb），既有行为不变。
+ * 注册表的优先级 > 0 才参与，因此「应用显式注册」永远压过内置默认。
+ * （public：装配层与测试子包 cjTauri.tests 都要引用；业务侧正常不会直接调用。）
+ */
+public func resolveHost(label: String): WebViewHost {
+    let target = Platform.guessTarget()
+    match (pickHost(label, target)) {
+        case Some(h) => return h
+        case None => return createHost(label)
+    }
+}

package/src/plugin.cj

@@ -56,6 +56,37 @@ public interface Plugin {
     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
+    }
 }
 
 /**
@@ -193,18 +224,21 @@ public func describePlugins(plugins: ArrayList<Plugin>): String {
  *   - `hasShim`：是否带前端 JS 片段（工具据此判断要不要等 `__CJ_TAURI__.<插件名>`）
  * 数组与权限键都按字典序排：HashMap 迭代顺序不定，工具的输出 / diff 需要稳定。
  *
- * 为什么不放进 `Plugin` 接口（RFC §7 的 v1 结论）：这些数据框架本就能从 `commands()` /
- * `events()` / `permissions()` 推出来，多一个接口方法只是给插件作者加负担；消费方要的是函数。
+ * 数据来自 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)

package/src/plugins/clipboard/plugin_clipboard.cj

@@ -22,6 +22,14 @@ import stdx.encoding.json.*
  * 读写都要宿主已就绪（start 之后）；更早调用得到 false / None。
  */
 public class ClipboardPlugin <: Plugin {
+
+    /** 自描述：原生桥仅桌面两端实现（ohos 侧按 P-1 落桩，批次 3-PR3） */
+    public func describe(): PluginManifest {
+        let hosts = ArrayList<String>()
+        hosts.add("webkitgtk")
+        hosts.add("webview2")
+        return PluginManifest(hosts, ArrayList<String>())
+    }
     private let handler: ClipboardCommands = ClipboardCommands()
 
     public init() {}

package/src/plugins/menu/plugin_menu.cj

@@ -1,150 +1,158 @@
-package cjTauri.plugins.menu
-
-import cjTauri.*
-
-import std.collection.*
-import stdx.encoding.json.*
-
-/**
- * 官方插件 menu：运行期改菜单项状态 + 前端命名空间（RFC-002 §5.6 / §5.9）
- *
- * 命令（短名 → 全名）：
- *   setEnabled → menu:setEnabled   `{ id, enabled }`
- *   setChecked → menu:setChecked   `{ id, checked }`
- * 事件：`click` → `menu:click`——本插件只**声明**它（给缺权限提示用），真正投递在
- *   `TauriApp` 的 shell 分发里，页面侧写 `listen("menu:click", …)` 即可。
- * 权限：**不自动放行**，应用在 capabilities 里二选一（两种写法等价）：
- *   "commands": ["menu:setEnabled", "menu:setChecked"]   // 明文逐条（旧写法）
- *   "permissions": ["menu:state"]                        // 命名权限集（v1.1）
- * 前端：window.__CJ_TAURI__.menu.setChecked({ id: "view.sidebar", checked: true })
- *
- * 为什么命令要经 `TauriApp`、而不是直接用宿主：菜单项按 id 定位到**调用方那个窗口**
- * （`ipc.window`），而「另一维状态」存在应用层留存的菜单模型里——平台侧一次调用会同时写
- * enabled 与 checked（见 `WebViewHost.setMenuItemState`），拿不到另一维就会把用户刚点出来的
- * 勾选抹掉。所以处理器必须握有 app，装配时由 `setup()` 注入。
- */
-public class MenuPlugin <: Plugin {
-    // 两个命令共用一个处理器实例：app 引用只要注入一次（commands() 早于 setup() 跑，见 attach）
-    private let handler: MenuCommands = MenuCommands()
-
-    public init() {}
-
-    public func name(): String {
-        return "menu"
-    }
-
-    public func commands(): HashMap<String, CommandHandler> {
-        let m = HashMap<String, CommandHandler>()
-        m.add("setEnabled", this.handler)
-        m.add("setChecked", this.handler)
-        return m
-    }
-
-    /** 事件只声明（`<插件名>:<短名>` = `menu:click`），投递在框架的 shell 分发里 */
-    public func events(): ArrayList<String> {
-        let e = ArrayList<String>()
-        e.add("click")
-        return e
-    }
-
-    /**
-     * 命名权限集（v1.1）：`menu:state` = 两个改状态的命令
-     *
-     * 与 fs 的 readonly 同理——**集声明不等于放行**，清单不引用它一条也不会生效。
-     */
-    public func permissions(): HashMap<String, ArrayList<String>> {
-        let m = HashMap<String, ArrayList<String>>()
-        let st = ArrayList<String>()
-        st.add("setEnabled")
-        st.add("setChecked")
-        m.add("state", st)
-        return m
-    }
-
-    public func setup(app: TauriApp): Unit {
-        this.handler.attach(app)
-    }
-
-    /**
-     * 前端 shim：往桥对象上挂一个 menu 命名空间。
-     * 只动 __CJ_TAURI__ 的一个命名空间，不碰 invoke / listen / emit，也不注册全局变量。
-     */
-    public func jsShim(): String {
-        return "(function () { var t = window.__CJ_TAURI__ || (window.__CJ_TAURI__ = {});" +
-            " t.menu = {" +
-            " setEnabled: function (args) { return window.__CJ_TAURI__.invoke('menu:setEnabled', args); }," +
-            " setChecked: function (args) { return window.__CJ_TAURI__.invoke('menu:setChecked', args); }" +
-            " }; })();\n"
-    }
-}
-
-/**
- * menu 插件的命令处理器（两个命令共用一份，按全名分派，与内置 SystemCommands / FsCommands 同形）
- */
-public class MenuCommands <: CommandHandler {
-    private var app: Option<TauriApp> = None
-
-    public init() {}
-
-    /**
-     * 由 MenuPlugin.setup 注入
-     *
-     * 不能靠构造函数传：`commands()`（装配时先跑，负责建处理器）拿不到 app，
-     * 而 `setup(app)` 后跑——所以只能事后注入。
-     */
-    func attach(app: TauriApp): Unit {
-        this.app = Some(app)
-    }
-
-    public func handle(cmd: String, args: JsonObject, ipc: IpcContext): JsonValue {
-        match (cmd) {
-            case "menu:setEnabled" => this.setEnabled(args, ipc)
-            case "menu:setChecked" => this.setChecked(args, ipc)
-            case _ => throw CommandException("unknown menu command: ${cmd}")
-        }
-    }
-
-    /** 只改启用状态；勾选态由应用层模型补齐（见 MenuPlugin 的类注释） */
-    private func setEnabled(args: JsonObject, ipc: IpcContext): JsonValue {
-        let id = this.requireString(args, "id")
-        let enabled = this.requireBool(args, "enabled")
-        this.requireApp().setMenuItemEnabledTo(ipc.window, id, enabled)
-        return JsonBool(true)
-    }
-
-    /** 只改勾选状态；启用态由应用层模型补齐 */
-    private func setChecked(args: JsonObject, ipc: IpcContext): JsonValue {
-        let id = this.requireString(args, "id")
-        let checked = this.requireBool(args, "checked")
-        this.requireApp().setMenuItemCheckedTo(ipc.window, id, checked)
-        return JsonBool(true)
-    }
-
-    private func requireApp(): TauriApp {
-        match (this.app) {
-            case Some(a) => return a
-            case None => throw CommandException("menu: 插件未装配到应用（请 TauriApp().plugin(MenuPlugin())）")
-        }
-    }
-
-    /** 取必需的字符串参数；缺失 / 类型不对时抛业务错误，前端拿到可读原文 */
-    private func requireString(args: JsonObject, key: String): String {
-        match (args.get(key)) {
-            case Some(v) => match (v.kind()) {
-                case JsonKind.JsString => return v.asString().getValue()
-                case _ => throw CommandException("menu: argument \"${key}\" must be a string")
-            }
-            case None => throw CommandException("menu: missing argument \"${key}\"")
-        }
-    }
-
-    private func requireBool(args: JsonObject, key: String): Bool {
-        match (args.get(key)) {
-            case Some(v) => match (v.kind()) {
-                case JsonKind.JsBool => return v.asBool().getValue()
-                case _ => throw CommandException("menu: argument \"${key}\" must be a boolean")
-            }
-            case None => throw CommandException("menu: missing argument \"${key}\"")
-        }
-    }
-}
+package cjTauri.plugins.menu
+
+import cjTauri.*
+
+import std.collection.*
+import stdx.encoding.json.*
+
+/**
+ * 官方插件 menu：运行期改菜单项状态 + 前端命名空间（RFC-002 §5.6 / §5.9）
+ *
+ * 命令（短名 → 全名）：
+ *   setEnabled → menu:setEnabled   `{ id, enabled }`
+ *   setChecked → menu:setChecked   `{ id, checked }`
+ * 事件：`click` → `menu:click`——本插件只**声明**它（给缺权限提示用），真正投递在
+ *   `TauriApp` 的 shell 分发里，页面侧写 `listen("menu:click", …)` 即可。
+ * 权限：**不自动放行**，应用在 capabilities 里二选一（两种写法等价）：
+ *   "commands": ["menu:setEnabled", "menu:setChecked"]   // 明文逐条（旧写法）
+ *   "permissions": ["menu:state"]                        // 命名权限集（v1.1）
+ * 前端：window.__CJ_TAURI__.menu.setChecked({ id: "view.sidebar", checked: true })
+ *
+ * 为什么命令要经 `TauriApp`、而不是直接用宿主：菜单项按 id 定位到**调用方那个窗口**
+ * （`ipc.window`），而「另一维状态」存在应用层留存的菜单模型里——平台侧一次调用会同时写
+ * enabled 与 checked（见 `WebViewHost.setMenuItemState`），拿不到另一维就会把用户刚点出来的
+ * 勾选抹掉。所以处理器必须握有 app，装配时由 `setup()` 注入。
+ */
+public class MenuPlugin <: Plugin {
+    // 两个命令共用一个处理器实例：app 引用只要注入一次（commands() 早于 setup() 跑，见 attach）
+    private let handler: MenuCommands = MenuCommands()
+
+    public init() {}
+
+    public func name(): String {
+        return "menu"
+    }
+
+    /** 自描述：菜单状态改动是宿主能力，仅桌面两端实现（ohos 宿主无菜单栏，命令如实报错，P-1/P-2） */
+    public func describe(): PluginManifest {
+        let hosts = ArrayList<String>()
+        hosts.add("webkitgtk")
+        hosts.add("webview2")
+        return PluginManifest(hosts, ArrayList<String>())
+    }
+
+    public func commands(): HashMap<String, CommandHandler> {
+        let m = HashMap<String, CommandHandler>()
+        m.add("setEnabled", this.handler)
+        m.add("setChecked", this.handler)
+        return m
+    }
+
+    /** 事件只声明（`<插件名>:<短名>` = `menu:click`），投递在框架的 shell 分发里 */
+    public func events(): ArrayList<String> {
+        let e = ArrayList<String>()
+        e.add("click")
+        return e
+    }
+
+    /**
+     * 命名权限集（v1.1）：`menu:state` = 两个改状态的命令
+     *
+     * 与 fs 的 readonly 同理——**集声明不等于放行**，清单不引用它一条也不会生效。
+     */
+    public func permissions(): HashMap<String, ArrayList<String>> {
+        let m = HashMap<String, ArrayList<String>>()
+        let st = ArrayList<String>()
+        st.add("setEnabled")
+        st.add("setChecked")
+        m.add("state", st)
+        return m
+    }
+
+    public func setup(app: TauriApp): Unit {
+        this.handler.attach(app)
+    }
+
+    /**
+     * 前端 shim：往桥对象上挂一个 menu 命名空间。
+     * 只动 __CJ_TAURI__ 的一个命名空间，不碰 invoke / listen / emit，也不注册全局变量。
+     */
+    public func jsShim(): String {
+        return "(function () { var t = window.__CJ_TAURI__ || (window.__CJ_TAURI__ = {});" +
+            " t.menu = {" +
+            " setEnabled: function (args) { return window.__CJ_TAURI__.invoke('menu:setEnabled', args); }," +
+            " setChecked: function (args) { return window.__CJ_TAURI__.invoke('menu:setChecked', args); }" +
+            " }; })();\n"
+    }
+}
+
+/**
+ * menu 插件的命令处理器（两个命令共用一份，按全名分派，与内置 SystemCommands / FsCommands 同形）
+ */
+public class MenuCommands <: CommandHandler {
+    private var app: Option<TauriApp> = None
+
+    public init() {}
+
+    /**
+     * 由 MenuPlugin.setup 注入
+     *
+     * 不能靠构造函数传：`commands()`（装配时先跑，负责建处理器）拿不到 app，
+     * 而 `setup(app)` 后跑——所以只能事后注入。
+     */
+    func attach(app: TauriApp): Unit {
+        this.app = Some(app)
+    }
+
+    public func handle(cmd: String, args: JsonObject, ipc: IpcContext): JsonValue {
+        match (cmd) {
+            case "menu:setEnabled" => this.setEnabled(args, ipc)
+            case "menu:setChecked" => this.setChecked(args, ipc)
+            case _ => throw CommandException("unknown menu command: ${cmd}")
+        }
+    }
+
+    /** 只改启用状态；勾选态由应用层模型补齐（见 MenuPlugin 的类注释） */
+    private func setEnabled(args: JsonObject, ipc: IpcContext): JsonValue {
+        let id = this.requireString(args, "id")
+        let enabled = this.requireBool(args, "enabled")
+        this.requireApp().setMenuItemEnabledTo(ipc.window, id, enabled)
+        return JsonBool(true)
+    }
+
+    /** 只改勾选状态；启用态由应用层模型补齐 */
+    private func setChecked(args: JsonObject, ipc: IpcContext): JsonValue {
+        let id = this.requireString(args, "id")
+        let checked = this.requireBool(args, "checked")
+        this.requireApp().setMenuItemCheckedTo(ipc.window, id, checked)
+        return JsonBool(true)
+    }
+
+    private func requireApp(): TauriApp {
+        match (this.app) {
+            case Some(a) => return a
+            case None => throw CommandException("menu: 插件未装配到应用（请 TauriApp().plugin(MenuPlugin())）")
+        }
+    }
+
+    /** 取必需的字符串参数；缺失 / 类型不对时抛业务错误，前端拿到可读原文 */
+    private func requireString(args: JsonObject, key: String): String {
+        match (args.get(key)) {
+            case Some(v) => match (v.kind()) {
+                case JsonKind.JsString => return v.asString().getValue()
+                case _ => throw CommandException("menu: argument \"${key}\" must be a string")
+            }
+            case None => throw CommandException("menu: missing argument \"${key}\"")
+        }
+    }
+
+    private func requireBool(args: JsonObject, key: String): Bool {
+        match (args.get(key)) {
+            case Some(v) => match (v.kind()) {
+                case JsonKind.JsBool => return v.asBool().getValue()
+                case _ => throw CommandException("menu: argument \"${key}\" must be a boolean")
+            }
+            case None => throw CommandException("menu: missing argument \"${key}\"")
+        }
+    }
+}

package/src/plugins/notification/plugin_notification.cj

@@ -21,6 +21,14 @@ import stdx.encoding.json.*
  * 「发后即忘」：提交即返回，通知显示与否不回传（freedesktop 协议本就没有同步回执）。
  */
 public class NotificationPlugin <: Plugin {
+
+    /** 自描述：原生桥仅桌面两端实现（ohos 侧按 P-1 落桩，批次 3-PR3） */
+    public func describe(): PluginManifest {
+        let hosts = ArrayList<String>()
+        hosts.add("webkitgtk")
+        hosts.add("webview2")
+        return PluginManifest(hosts, ArrayList<String>())
+    }
     private let handler: NotificationCommands = NotificationCommands()
 
     public init() {}