cj-tauri 0.8.0 → 1.1.0

package/src/hotkey.cj

@@ -0,0 +1,66 @@
+package cjTauri
+
+import std.collection.*
+
+/**
+ * 全局快捷键的**纯仓颉模型**（RFC-003 第 5 期首个落地项）：只描述意图，不含任何平台概念。
+ *
+ * 分层与菜单同构（RFC-002 §5.1）：模型（本文件）→ `WebViewHost.setGlobalHotkeys()`
+ * → C 桥 `cj_bridge_set_global_hotkeys` → 平台翻译层（Linux = X11 grab；Windows 桩如实报暂不支持）。
+ *
+ * wire 格式（与 `native/core/bridge_core.h` 的 `pending_hotkeys` 注释逐字对应）：
+ * 一行一条 `<accel>:<id>`，如 `Ctrl+Alt+C:show-panel`。accel 的修饰键只有四个约定名
+ * （Ctrl / Alt / Shift / Super），键名是单字符或 F1..F12 / Enter / Esc 等常用键——
+ * 平台侧解析不了的那条整行丢弃并出声，而不是静默吞掉。
+ *
+ * 文本来自**应用作者**（不是页面可控输入），这里不做转义；id 里出现 `:` 或换行是应用自己的错，
+ * toWire 不出口这种行（防御性跳过并留一句 stderr 的成本太高，直接约定 + 文档）。
+ */
+public class Hotkey {
+    public let accel: String
+    public let id: String
+
+    public init(accel: String, id: String) {
+        this.accel = accel
+        this.id = id
+    }
+}
+
+/** 快捷键模型：注册表即整表替换（运行期再调 setGlobalHotkeys = 先注销旧表再注册新表） */
+public class HotkeyModel {
+    public let keys: ArrayList<Hotkey>
+
+    public init(keys: ArrayList<Hotkey>) {
+        this.keys = keys
+    }
+
+    /** 便捷构造：可变参数式逐条 add */
+    public init() {
+        this.keys = ArrayList<Hotkey>()
+    }
+
+    public func add(accel: String, id: String): HotkeyModel {
+        this.keys.add(Hotkey(accel, id))
+        return this
+    }
+
+    /** 线路文本（每行 `<accel>:<id>`；空模型给空串 = 全部注销） */
+    public func toWire(): String {
+        let sb = StringBuilder()
+        var first = true
+        for (k in this.keys) {
+            if (k.accel.contains(":") || k.accel.contains("\n") ||
+                k.id.contains(":") || k.id.contains("\n")) {
+                continue // 非法字段整条出局：wire 的分隔符就是这两个字符
+            }
+            if (!first) {
+                sb.append("\n")
+            }
+            first = false
+            sb.append(k.accel)
+            sb.append(":")
+            sb.append(k.id)
+        }
+        return sb.toString()
+    }
+}

package/src/ipc_hub.cj

@@ -72,6 +72,26 @@ public class IpcContext {
     public func hostCapabilities(): Int32 {
         return this.hub.hostCapabilities(this.window)
     }
+
+    /**
+     * 解析并校验一个路径参数（RFC-003 第 4 期）。
+     *
+     * 带路径参数的插件**一律**用它取代自己拼路径：清单里为插件写了 scope 就按
+     * allow/deny 判定，越界抛业务错误；没写就维持旧行为（全量放行，启动时有提示）。
+     * 返回值是规范化后的路径（绝对、已解析软链接），直接交给 std.fs 用即可。
+     */
+    public func resolveScopedPath(plugin: String, rawPath: String): String {
+        return this.hub.resolveScopedPath(plugin, rawPath)
+    }
+
+    /**
+     * 取某插件的 scope 规则**本体**（不给判定）：给「匹配语义不是文件路径」的插件用——
+     * 如 http 插件把 allow/deny 模式当**主机名**匹配（不能先走 normalizeScopePath 的
+     * 文件路径折叠）。判定本身仍走共享层 `scopeAllows`，插件不自己写第二份 glob。
+     */
+    public func scopeRuleFor(plugin: String): Option<ScopeRule> {
+        return this.hub.scopeRuleFor(plugin)
+    }
 }
 
 /**
@@ -123,6 +143,35 @@ public class IpcHub {
         return this.commands.contains(cmd)
     }
 
+    /**
+     * 路径 scope 校验（RFC-003 第 4 期）：IpcContext.resolveScopedPath 的实现体。
+     *
+     * 校验只在**真的有插件来问**时发生——没有为它声明 scope 的插件完全不受影响（旧清单行为不变）。
+     * 拒绝时 stderr 留一行凭证（前缀统一好 grep），前端拿到的是可读的业务错误而不是宿主崩溃。
+     */
+    public func resolveScopedPath(plugin: String, rawPath: String): String {
+        let resolved = normalizeScopePath(rawPath)
+        match (this.capabilities.scopeForPlugin(plugin)) {
+            case Some(rule) =>
+                if (!scopeAllows(rule, resolved)) {
+                    eprintln("[cj-tauri] scope denied (${plugin}): ${rawPath} -> ${resolved}")
+                    throw CommandException("${plugin}: path is outside the authorized scope")
+                }
+            case None => ()
+        }
+        return resolved
+    }
+
+    /**
+     * 取某插件的 scope 规则**本体**（不给判定）：给「匹配语义不是文件路径」的插件用——
+     * 如 http 插件把 allow/deny 模式当**主机名**匹配（不能先走 normalizeScopePath 的
+     * 文件路径折叠，那会把 `api.example.com` 当成相对路径去拼接）。判定本身仍走共享层
+     * `scopeAllows`，插件不自己写第二份 glob。
+     */
+    public func scopeRuleFor(plugin: String): Option<ScopeRule> {
+        return this.capabilities.scopeForPlugin(plugin)
+    }
+
     /**
      * 注册后端事件监听器（对标 Tauri Rust 侧的 `app.listen(...)`）
      *

package/src/ipc_message.cj

@@ -8,7 +8,7 @@ import stdx.encoding.json.*
  * 与桥 JS 的 `windowLabel` 缺省、`emitToWindow(..., "main")` 是同一个约定：老前端与现有示例
  * 都写死 `"main"`，默认值一错，事件就静默收不到、回执就静默投不回原窗口（见架构文档 §6.4）。
  */
-let DEFAULT_WINDOW_LABEL = "main"
+public let DEFAULT_WINDOW_LABEL = "main"
 
 /**
  * IPC 消息模型（对标 Tauri IPC 协议）
@@ -245,6 +245,7 @@ public class IpcMessage {
     private static func eventJson(event: String, payload: JsonValue, window: String, coalesce: Bool): JsonObject {
         var obj = JsonObject()
         obj.put("type", JsonString("event"))
+        obj.put("protocol", JsonString(CJ_IPC_PROTOCOL))
         obj.put("event", JsonString(event))
         obj.put("payload", payload)
         if (coalesce) {

package/src/jsutil.cj

@@ -0,0 +1,33 @@
+package cjTauri
+
+import std.collection.*
+
+/**
+ * 把文本包成 JS 双引号字符串字面量（核心共享层）
+ *
+ * ## 为什么单独放在这里，而不是留在 `arkweb_script.cj` 里
+ *
+ * 调用方 `arkWebLabelScript` 带 `@When[env == "ohos"]` 门禁，桌面 `cjpm test` 根本编不到它；
+ * 而这段转义**失效是静默的**：生成的脚本当场语法错误，页面里 `__CJ_TAURI_LABEL__` 永远停在
+ * 默认值 `main`，事件过滤失灵却没有一行报错（AGENTS §4 的同族坑：错得不响，查起来最贵）。
+ * 放到不带门禁的共享层，桌面单测就能守住它；`public` 是为了跨包单测可直接构造。
+ *
+ * ## 转义口径
+ *
+ * 只转义两样：反斜杠与双引号。入参是窗口 label（应用给定的短标识，默认 `main`），
+ * 不承载换行等控制字符——**这里不是通用 JSON 编码器**，真要处理控制字符再加分支，
+ * 别顺手改成「全量转义」把调用方的语义带偏。
+ */
+public func jsStringLiteral(text: String): String {
+    let bytes = text.toArray()
+    let out = ArrayList<UInt8>(bytes.size + 2)
+    out.add(0x22u8)
+    for (b in bytes) {
+        if (b == 0x5Cu8 || b == 0x22u8) {
+            out.add(0x5Cu8)
+        }
+        out.add(b)
+    }
+    out.add(0x22u8)
+    return String.fromUtf8(out.toArray())
+}

package/src/log_bridge.cj

@@ -0,0 +1,107 @@
+package cjTauri
+
+
+/**
+ * 日志落盘桥（RFC-003 第 5 期）：C 桥 `cj_bridge_log_*` 的声明与薄包装。
+ *
+ * 桌面两平台导出同名同签名（AGENTS §2 的硬约束），实现只有一份
+ * （`native/core/bridge_core.c`）——落盘是把 fd 2 指到日志文件，与宿主 UI 栈无关，
+ * 所以不吃宿主句柄、也不进 `WebViewHost` 接口：它是**进程级**的，不是窗口级的。
+ *
+ * 为什么非得在 fd 层接管：要让「没有控制台的 GUI 产物」也有凭证，就必须把 C 桥与仓颉侧
+ * **两侧**的诊断收进同一份文件，只有 fd 层的接管做得到（见 core 里那段注释的取舍）。
+ *
+ * 鸿蒙（`env == "ohos"`）侧没有 C 桥产物（`native/platforms/harmonyos/` 目前只有契约），
+ * 这三个 FFI 符号无处解析——若照桌面那份写下去，**模块加载期就 SIGSEGV**（实测 2026-10-18：
+ * 应用进程 signal:11，AbilityStage.onCreate 一行都执行不到）。所以这里按平台分叉，
+ * 鸿蒙侧如实降级：不落盘、`writeLogLine` 返回 false，绝不假装成功。
+ *
+ * 判据用 `env` 而不是 `arch`（2026-10-19 校正）：`arch == "aarch64"` 连桌面 aarch64 Linux
+ * 一起门禁掉了，那个平台**是有 C 桥的**，会白白失去日志落盘能力。
+ */
+
+/** 门禁口径与 `host.cj` 的 FFI 一致：桌面走 C 桥，鸿蒙走降级实现。 */
+@When[env != "ohos"]
+@C
+foreign func cj_bridge_set_log_file(path: CString, maxKB: Int32, keep: Int32): Int32
+
+/**
+ * 回读生效中的日志路径；未开启时为空串。
+ * 返回的是 C 侧内部静态缓冲，**不要**释放（也不要在别的线程上长期持有）。
+ */
+@When[env != "ohos"]
+@C
+foreign func cj_bridge_log_file(): CString
+
+/**
+ * 追加一行到日志出口（同样走轮转）：0 = 已写入，-1 = 参数非法。
+ * 给 `log` 插件用——页面报错也并进同一份文件（单文件产物里它原本同样看不见）。
+ */
+@When[env != "ohos"]
+@C
+foreign func cj_bridge_log_write(line: CString): Int32
+
+/** 开日志落盘，返回是否真的开了（被拒时 C 侧已出声，这里绝不假装成功） */
+@When[env != "ohos"]
+func enableLogFile(path: String, maxKB: Int64, keep: Int64): Bool {
+    var kb = maxKB
+    var kp = keep
+    if (kb > 1048576) {
+        kb = 1048576 // 1 GiB 上限：Int64 → Int32 的转换不该被一个手滑的环境变量带崩
+    }
+    if (kp > 1000) {
+        kp = 1000
+    }
+    var rc: Int32 = 0
+    unsafe {
+        rc = cj_bridge_set_log_file(LibC.mallocCString(path), Int32(kb), Int32(kp))
+    }
+    return rc == 1
+}
+
+/**
+ * 鸿蒙侧：没有 C 桥，落盘能力位如实为 0。
+ *
+ * 返回 false 而不抛异常——调用方（`setLogToDefaultFile`）本就是「尽力而为」语义，
+ * 抛异常会把应用启动带走。留一行 stderr 说明「哪条路没走通」。
+ */
+@When[env == "ohos"]
+func enableLogFile(path: String, maxKB: Int64, keep: Int64): Bool {
+    let _ = maxKB
+    let _ = keep
+    eprintln("[cj-tauri] log file sink unavailable on this platform (no C bridge): ${path}")
+    return false
+}
+
+/** 生效中的日志路径（未开启 = 空串）。公开是给插件子包用（子包看不到父包非 public 符号） */
+@When[env != "ohos"]
+public func currentLogFilePath(): String {
+    let cs = unsafe { cj_bridge_log_file() }
+    if (cs.isNull()) {
+        return ""
+    }
+    return cs.toString()
+}
+
+/** 鸿蒙侧没有落盘出口：恒为空串（与「未开启」同口径，调用方无需分支） */
+@When[env == "ohos"]
+public func currentLogFilePath(): String {
+    return ""
+}
+
+/** 往日志出口追加一行（log 插件用）。公开理由同上 */
+@When[env != "ohos"]
+public func writeLogLine(line: String): Bool {
+    var rc: Int32 = -1
+    unsafe {
+        rc = cj_bridge_log_write(LibC.mallocCString(line))
+    }
+    return rc == 0
+}
+
+/** 鸿蒙侧：没有出口可写，返回 false（调用方据返回值如实回报，不冒充已写入） */
+@When[env == "ohos"]
+public func writeLogLine(line: String): Bool {
+    let _ = line
+    return false
+}

package/src/logging.cj

@@ -0,0 +1,127 @@
+package cjTauri
+
+import std.env.*
+import std.convert.*
+
+/**
+ * 日志落盘的策略层（RFC-003 第 5 期）：文件放哪、预算多少、环境变量怎么兜底。
+ *
+ * 落盘本身在 `src/log_bridge.cj`（进程级、无平台分支）；这里只管策略，纯函数 + `@When` 目录推导。
+ *
+ * 为什么要环境变量兜底：单文件产物是 Windows 的 GUI 子系统、双击时没有控制台，而**已经分发的
+ * exe 改不了代码**——让报障的人带上 `CJ_TAURI_LOG` 再启动一次，就能拿到凭证；
+ * 不设这些变量时行为与之前**完全一致**（不落盘、stderr 照旧）。
+ */
+
+/** 默认预算：256 KB 一份、留 2 份档案（最坏约 1 MB，常驻托盘类应用也吃得消） */
+public let CJ_LOG_DEFAULT_MAX_KB: Int64 = 256
+public let CJ_LOG_DEFAULT_KEEP: Int64 = 2
+
+/** 应用名缺省值（应用没给名字时用它当文件名） */
+public let CJ_LOG_DEFAULT_APP: String = "app"
+
+/**
+ * 单行上限（字节）：页面可控的字符串，超了只记一条说明
+ *
+ * 8 KiB 够放一段异常栈；不设上限的话，一行天文数字能同时把内存与日志文件撑爆，
+ * 而这一行本身还未必有诊断价值。
+ */
+public let CJ_LOG_MAX_LINE: Int64 = 8192
+
+/** 读环境变量（空串按未设置算）。公开只为子包用例可见（子包看不到父包非 public 符号） */
+public func logEnvOr(name: String, dflt: String): String {
+    if (let Some(v) <- getVariable(name)) {
+        if (v.size > 0) {
+            return v
+        }
+    }
+    return dflt
+}
+
+/**
+ * 解析预算类环境变量（CJ_TAURI_LOG_MAX_KB / CJ_TAURI_LOG_KEEP）
+ *
+ * 非法值按未设置算，并留一行 stderr——「设了但没生效」比「没设」难查得多。
+ * 公开只为子包用例可见（子包看不到父包非 public 符号）
+ */
+public func logBudgetFromEnv(name: String, dflt: Int64): Int64 {
+    if (let Some(v) <- getVariable(name)) {
+        if (v.size > 0) {
+            try {
+                let n = Int64.parse(v)
+                if (n > 0) {
+                    return n
+                }
+                eprintln("[cj-tauri] ${name}=\"${v}\" 不是正整数，按默认值 ${dflt} 处理")
+            } catch (e: Exception) {
+                eprintln("[cj-tauri] ${name}=\"${v}\" 解析失败，按默认值 ${dflt} 处理")
+            }
+        }
+    }
+    return dflt
+}
+
+/**
+ * 平台惯例的日志目录（不含文件名）
+ *
+ * Linux 认 `XDG_STATE_HOME`（缺省 `~/.local/state`）：日志属 state，不属 config——
+ * 放 `~/.config` 会把「可丢弃的运行痕迹」混进配置备份里。
+ */
+@When[os == "Linux"]
+public func defaultLogDir(): String {
+    let base = logEnvOr("XDG_STATE_HOME", "")
+    if (base.size > 0) {
+        return "${base}/cj-tauri"
+    }
+    return "${logEnvOr("HOME", "/tmp")}/.local/state/cj-tauri"
+}
+
+/**
+ * 平台惯例的日志目录（不含文件名）
+ *
+ * Windows 认 `%LOCALAPPDATA%`（`C:\Users\<用户>\AppData\Local`）：单机可丢的数据就该落这里，
+ * 漫游配置里不放日志。变量缺失时退到 USERPROFILE，别拼出个以 `\cj-tauri` 开头的绝对路径。
+ */
+@When[os == "Windows"]
+public func defaultLogDir(): String {
+    let base = logEnvOr("LOCALAPPDATA", "")
+    if (base.size > 0) {
+        return "${base}\\cj-tauri\\logs"
+    }
+    return "${logEnvOr("USERPROFILE", "C:")}\\AppData\\Local\\cj-tauri\\logs"
+}
+
+/** 目录 + 文件名：分隔符按平台给（C 侧整条路径直接用，不做拼接） */
+@When[os == "Linux"]
+func logPathJoin(dir: String, name: String): String {
+    return "${dir}/${name}"
+}
+
+/** 目录 + 文件名：分隔符按平台给（C 侧整条路径直接用，不做拼接） */
+@When[os == "Windows"]
+func logPathJoin(dir: String, name: String): String {
+    return "${dir}\\${name}"
+}
+
+/** 应用名 → 平台惯例目录下的日志全路径（`CJ_TAURI_LOG` 的覆写由调用方先判） */
+public func defaultLogPath(appName: String): String {
+    let name = if (appName.size > 0) {
+        appName
+    } else {
+        CJ_LOG_DEFAULT_APP
+    }
+    return logPathJoin(defaultLogDir(), "${name}.log")
+}
+
+/**
+ * 「环境变量给了就用它，没给才落平台惯例目录」——`setLogToDefaultFile` 的选择器
+ *
+ * 抽成纯函数只为**可测**：单测里改环境变量会污染同进程的其它用例，所以把「读到什么」
+ * 当参数传进来，判据钉在这个函数上（`envPath` 空串＝未设置，与 `logEnvOr` 同口径）。
+ */
+public func logPathOrDefault(envPath: String, appName: String): String {
+    if (envPath.size > 0) {
+        return envPath
+    }
+    return defaultLogPath(appName)
+}