cj-tauri 0.8.0 → 1.1.0

package/src/menu.cj

@@ -1,196 +1,197 @@
-package cjTauri
-
-import std.collection.*
-
-/**
- * 窗口菜单栏的**纯仓颉模型**（RFC-002 §5.1）：只描述意图，不含任何平台概念。
- *
- * 分层：模型（本文件）→ `WebViewHost.setMenu()`（src/host.cj）→ C 桥 `cj_bridge_set_menu` →
- * 平台翻译层（native/bridge_win.c 的 CreateMenu 族 / bridge_linux.c 的 GtkMenuBar）。
- * 菜单文本来自**应用作者**（不是页面可控的不可信输入），所以这里不做转义——
- * 非法字段让那一项出局并出声，而不是写一套转义/反转义。
- */
-public enum MenuItemKind {
-    | Normal // 普通项：点击回调自己的 id
-    | Checkbox // 可勾选项：回调里带 checked
-    | Separator // 分隔线：无 id、不可点
-    | Submenu // 子菜单：自身不可点，只承载 children
-}
-
-public class MenuItem {
-    public let id: String
-    public let label: String
-    public let kind: MenuItemKind
-    /** 快捷键**提示**文本（如 "Ctrl+S"）。v1 只显示，不抢页面按键 */
-    public let accelerator: String
-    public var enabled: Bool
-    public var checked: Bool
-    /** 仅 Submenu 用；其它 kind 恒为空表 */
-    public let children: ArrayList<MenuItem>
-
-    public init(id: String, label: String, kind: MenuItemKind, accelerator: String,
-                enabled: Bool, checked: Bool, children: ArrayList<MenuItem>) {
-        this.id = id
-        this.label = label
-        this.kind = kind
-        this.accelerator = accelerator
-        this.enabled = enabled
-        this.checked = checked
-        this.children = children
-    }
-
-    /** 普通菜单项（最常用） */
-    public static func normal(id: String, label: String): MenuItem {
-        return MenuItem(id, label, MenuItemKind.Normal, "", true, false, ArrayList<MenuItem>())
-    }
-
-    /** 带快捷键提示的普通项 */
-    public static func normalWithAccel(id: String, label: String, accelerator: String): MenuItem {
-        return MenuItem(id, label, MenuItemKind.Normal, accelerator, true, false, ArrayList<MenuItem>())
-    }
-
-    /** 勾选项（初始 checked） */
-    public static func checkbox(id: String, label: String, checked: Bool): MenuItem {
-        return MenuItem(id, label, MenuItemKind.Checkbox, "", true, checked, ArrayList<MenuItem>())
-    }
-
-    /** 子菜单：id 留空（自身不回调），动作交给 children */
-    public static func submenu(label: String, children: ArrayList<MenuItem>): MenuItem {
-        return MenuItem("", label, MenuItemKind.Submenu, "", true, false, children)
-    }
-
-    /** 分隔线 */
-    public static func separator(): MenuItem {
-        return MenuItem("", "", MenuItemKind.Separator, "", true, false, ArrayList<MenuItem>())
-    }
-}
-
-/**
- * 菜单模型：`items` 是菜单栏的顶层，子菜单靠 `MenuItem.children` 递归。
- *
- * **不可变**（items 只读）：运行期改状态走 `WebViewHost.setMenuItemState(id, …)`，不在这里改——
- * 状态的真身在平台对象上（Windows 的 HMENU、GTK 的 GtkCheckMenuItem），只改模型平台不会自己变。
- */
-public class MenuModel {
-    public let items: ArrayList<MenuItem>
-
-    public init(items: ArrayList<MenuItem>) {
-        this.items = items
-    }
-
-    /**
-     * 按 id 找菜单项（本层优先，再下钻子菜单）；找不到返回 None
-     *
-     * 为什么要它：运行期改状态按 id 定位（`setMenuItemState`），而**应用层的模型状态**必须
-     * 能反查出「这个 id 现在是什么状态」——平台侧一次写两位（enabled + checked，见
-     * `WebViewHost.setMenuItemState`），拿不到另一维就会把用户刚点出来的勾选抹掉。
-     */
-    public func findById(id: String): Option<MenuItem> {
-        return MenuModel.lookup(this.items, id)
-    }
-
-    private static func lookup(items: ArrayList<MenuItem>, id: String): Option<MenuItem> {
-        for (item in items) {
-            if (item.id == id) {
-                return Some(item)
-            }
-            match (MenuModel.lookup(item.children, id)) {
-                case Some(found) => return Some(found)
-                case None => ()
-            }
-        }
-        return None
-    }
-
-    /**
-     * 线路格式（RFC-002 §5.4）：一行一项，字段用制表符分隔，**行首制表符数 = 层级**。
-     *
-     *     <tabs><kind>\t<id>\t<label>\t<flags>\t<accel>\n
-     *
-     * kind：`n` 普通 / `c` 勾选 / `s` 分隔线 / `m` 子菜单；
-     * flags：十进制，bit0 = 可用、bit1 = 勾选（`3` = 又可用又勾选）；
-     * 分隔线与子菜单也走满 5 个字段（id / label / accel 为空），C 侧因此不必为它们开特例。
-     *
-     * 为什么 kind 放最前：C 侧先分派再取值，日志里一眼能看出这行是什么。
-     * 为什么不是 JSON：C 侧（bridge_core.c）是纯 C、不引第三方，行式文本解析几十行就够，
-     * 且坏了能直接 `fprintf` 到 stderr（诊断走 stderr 是项目铁律）。JSON 留在仓颉侧给 CLI / 清单用。
-     * 为什么不做转义：字段里出现制表符 / 换行会破坏「一行一项」的结构——v1 的口径是
-     * **丢弃该项 + stderr 逐项提示**（见 emit），而不是引入转义/反转义这一对必须同时正确的函数。
-     */
-    public func toWire(): String {
-        return MenuModel.emit(this.items, 0)
-    }
-
-    private static func emit(items: ArrayList<MenuItem>, depth: Int64): String {
-        var out = ""
-        for (item in items) {
-            if (!MenuModel.wireSafe(item.id) || !MenuModel.wireSafe(item.label) ||
-                !MenuModel.wireSafe(item.accelerator)) {
-                eprintln("[cj-tauri] menu: item dropped from wire (id/label/accelerator contains tab or newline)")
-                continue
-            }
-            out += MenuModel.tabs(depth) + MenuModel.kindCode(item.kind) + "\t" + item.id + "\t" +
-                item.label + "\t" + MenuModel.flags(item).toString() + "\t" + item.accelerator + "\n"
-            if (MenuModel.isSubmenu(item.kind)) {
-                out += MenuModel.emit(item.children, depth + 1)
-            }
-        }
-        return out
-    }
-
-    /**
-     * 枚举值**不能用 `==` 比较**（实测：Cangjie 1.2.0 编译期报
-     * `invalid binary operator '==' on type 'Enum-MenuItemKind' and 'Enum-MenuItemKind'`），只有 match 能判。
-     */
-    private static func isSubmenu(kind: MenuItemKind): Bool {
-        match (kind) {
-            case MenuItemKind.Submenu => true
-            case _ => false
-        }
-    }
-
-    /**
-     * 字段里不许有制表符 / 换行 / 回车：它们是线路格式的结构字符。
-     * 注意本 SDK 里 `for (cp in someString)` 迭代出的是 **UInt8 字节**（不是 UInt32 码点，AGENTS §4 那条已更正）：
-     * 三个结构字符都在 ASCII 范围内，按字节比对既够用、也不受多字节字符影响。
-     */
-    private static func wireSafe(s: String): Bool {
-        for (cp in s) {
-            if (cp == 9u8 || cp == 10u8 || cp == 13u8) {
-                return false
-            }
-        }
-        return true
-    }
-
-    private static func tabs(n: Int64): String {
-        var out = ""
-        var i = 0
-        while (i < n) {
-            out += "\t"
-            i++
-        }
-        return out
-    }
-
-    private static func kindCode(kind: MenuItemKind): String {
-        match (kind) {
-            case MenuItemKind.Normal => "n"
-            case MenuItemKind.Checkbox => "c"
-            case MenuItemKind.Separator => "s"
-            case MenuItemKind.Submenu => "m"
-        }
-    }
-
-    /** flags：bit0 = 可用、bit1 = 勾选（十进制传输，C 侧只要 atoi） */
-    private static func flags(item: MenuItem): Int64 {
-        var f = 0
-        if (item.enabled) {
-            f += 1
-        }
-        if (item.checked) {
-            f += 2
-        }
-        return f
-    }
-}
+package cjTauri
+
+import std.collection.*
+
+/**
+ * 窗口菜单栏的**纯仓颉模型**（RFC-002 §5.1）：只描述意图，不含任何平台概念。
+ *
+ * 分层：模型（本文件）→ `WebViewHost.setMenu()`（src/host.cj）→ C 桥 `cj_bridge_set_menu` →
+ * 平台翻译层（native/bridge_win.c 的 CreateMenu 族 / bridge_linux.c 的 GtkMenuBar）。
+ * 菜单文本来自**应用作者**（不是页面可控的不可信输入），所以这里不做转义——
+ * 非法字段让那一项出局并出声，而不是写一套转义/反转义。
+ */
+public enum MenuItemKind {
+    | Normal // 普通项：点击回调自己的 id
+    | Checkbox // 可勾选项：回调里带 checked
+    | Separator // 分隔线：无 id、不可点
+    | Submenu // 子菜单：自身不可点，只承载 children
+}
+
+public class MenuItem {
+    public let id: String
+    public let label: String
+    public let kind: MenuItemKind
+    /** 快捷键**提示**文本（如 "Ctrl+S"）。v1 只显示，不抢页面按键 */
+    public let accelerator: String
+    public var enabled: Bool
+    public var checked: Bool
+    /** 仅 Submenu 用；其它 kind 恒为空表 */
+    public let children: ArrayList<MenuItem>
+
+    public init(id: String, label: String, kind: MenuItemKind, accelerator: String,
+                enabled: Bool, checked: Bool, children: ArrayList<MenuItem>) {
+        this.id = id
+        this.label = label
+        this.kind = kind
+        this.accelerator = accelerator
+        this.enabled = enabled
+        this.checked = checked
+        this.children = children
+    }
+
+    /** 普通菜单项（最常用） */
+    public static func normal(id: String, label: String): MenuItem {
+        return MenuItem(id, label, MenuItemKind.Normal, "", true, false, ArrayList<MenuItem>())
+    }
+
+    /** 带快捷键提示的普通项 */
+    public static func normalWithAccel(id: String, label: String, accelerator: String): MenuItem {
+        return MenuItem(id, label, MenuItemKind.Normal, accelerator, true, false, ArrayList<MenuItem>())
+    }
+
+    /** 勾选项（初始 checked） */
+    public static func checkbox(id: String, label: String, checked: Bool): MenuItem {
+        return MenuItem(id, label, MenuItemKind.Checkbox, "", true, checked, ArrayList<MenuItem>())
+    }
+
+    /** 子菜单：id 留空（自身不回调），动作交给 children */
+    public static func submenu(label: String, children: ArrayList<MenuItem>): MenuItem {
+        return MenuItem("", label, MenuItemKind.Submenu, "", true, false, children)
+    }
+
+    /** 分隔线 */
+    public static func separator(): MenuItem {
+        return MenuItem("", "", MenuItemKind.Separator, "", true, false, ArrayList<MenuItem>())
+    }
+}
+
+/**
+ * 菜单模型：`items` 是菜单栏的顶层，子菜单靠 `MenuItem.children` 递归。
+ *
+ * **不可变**（items 只读）：运行期改状态走 `WebViewHost.setMenuItemState(id, …)`，不在这里改——
+ * 状态的真身在平台对象上（Windows 的 HMENU、GTK 的 GtkCheckMenuItem），只改模型平台不会自己变。
+ */
+public class MenuModel {
+    public let items: ArrayList<MenuItem>
+
+    public init(items: ArrayList<MenuItem>) {
+        this.items = items
+    }
+
+    /**
+     * 按 id 找菜单项（本层优先，再下钻子菜单）；找不到返回 None
+     *
+     * 为什么要它：运行期改状态按 id 定位（`setMenuItemState`），而**应用层的模型状态**必须
+     * 能反查出「这个 id 现在是什么状态」——平台侧一次写两位（enabled + checked，见
+     * `WebViewHost.setMenuItemState`），拿不到另一维就会把用户刚点出来的勾选抹掉。
+     */
+    public func findById(id: String): Option<MenuItem> {
+        return MenuModel.lookup(this.items, id)
+    }
+
+    private static func lookup(items: ArrayList<MenuItem>, id: String): Option<MenuItem> {
+        for (item in items) {
+            if (item.id == id) {
+                return Some(item)
+            }
+            match (MenuModel.lookup(item.children, id)) {
+                case Some(found) => return Some(found)
+                case None => ()
+            }
+        }
+        return None
+    }
+
+    /**
+     * 线路格式（RFC-002 §5.4）：一行一项，字段用制表符分隔，**行首制表符数 = 层级**。
+     *
+     *     <tabs><kind>\t<id>\t<label>\t<flags>\t<accel>\n
+     *
+     * kind：`n` 普通 / `c` 勾选 / `s` 分隔线 / `m` 子菜单；
+     * flags：十进制，bit0 = 可用、bit1 = 勾选（`3` = 又可用又勾选）；
+     * 分隔线与子菜单也走满 5 个字段（id / label / accel 为空），C 侧因此不必为它们开特例。
+     *
+     * 为什么 kind 放最前：C 侧先分派再取值，日志里一眼能看出这行是什么。
+     * 为什么不是 JSON：C 侧（bridge_core.c）是纯 C、不引第三方，行式文本解析几十行就够，
+     * 且坏了能直接 `fprintf` 到 stderr（诊断走 stderr 是项目铁律）。JSON 留在仓颉侧给 CLI / 清单用。
+     * 为什么不做转义：字段里出现制表符 / 换行会破坏「一行一项」的结构——v1 的口径是
+     * **丢弃该项 + stderr 逐项提示**（见 emit），而不是引入转义/反转义这一对必须同时正确的函数。
+     */
+    public func toWire(): String {
+        return MenuModel.emit(this.items, 0)
+    }
+
+    /** 包内共享（TrayModel 的托盘菜单复用同一遍发射器，别再抄一份格式） */
+    static func emit(items: ArrayList<MenuItem>, depth: Int64): String {
+        var out = ""
+        for (item in items) {
+            if (!MenuModel.wireSafe(item.id) || !MenuModel.wireSafe(item.label) ||
+                !MenuModel.wireSafe(item.accelerator)) {
+                eprintln("[cj-tauri] menu: item dropped from wire (id/label/accelerator contains tab or newline)")
+                continue
+            }
+            out += MenuModel.tabs(depth) + MenuModel.kindCode(item.kind) + "\t" + item.id + "\t" +
+                item.label + "\t" + MenuModel.flags(item).toString() + "\t" + item.accelerator + "\n"
+            if (MenuModel.isSubmenu(item.kind)) {
+                out += MenuModel.emit(item.children, depth + 1)
+            }
+        }
+        return out
+    }
+
+    /**
+     * 枚举值**不能用 `==` 比较**（实测：Cangjie 1.2.0 编译期报
+     * `invalid binary operator '==' on type 'Enum-MenuItemKind' and 'Enum-MenuItemKind'`），只有 match 能判。
+     */
+    private static func isSubmenu(kind: MenuItemKind): Bool {
+        match (kind) {
+            case MenuItemKind.Submenu => true
+            case _ => false
+        }
+    }
+
+    /**
+     * 字段里不许有制表符 / 换行 / 回车：它们是线路格式的结构字符。
+     * 注意本 SDK 里 `for (cp in someString)` 迭代出的是 **UInt8 字节**（不是 UInt32 码点，AGENTS §4 那条已更正）：
+     * 三个结构字符都在 ASCII 范围内，按字节比对既够用、也不受多字节字符影响。
+     */
+    private static func wireSafe(s: String): Bool {
+        for (cp in s) {
+            if (cp == 9u8 || cp == 10u8 || cp == 13u8) {
+                return false
+            }
+        }
+        return true
+    }
+
+    private static func tabs(n: Int64): String {
+        var out = ""
+        var i = 0
+        while (i < n) {
+            out += "\t"
+            i++
+        }
+        return out
+    }
+
+    private static func kindCode(kind: MenuItemKind): String {
+        match (kind) {
+            case MenuItemKind.Normal => "n"
+            case MenuItemKind.Checkbox => "c"
+            case MenuItemKind.Separator => "s"
+            case MenuItemKind.Submenu => "m"
+        }
+    }
+
+    /** flags：bit0 = 可用、bit1 = 勾选（十进制传输，C 侧只要 atoi） */
+    private static func flags(item: MenuItem): Int64 {
+        var f = 0
+        if (item.enabled) {
+            f += 1
+        }
+        if (item.checked) {
+            f += 2
+        }
+        return f
+    }
+}

package/src/plugin.cj

@@ -45,6 +45,17 @@ public interface Plugin {
     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
+    }
 }
 
 /**
@@ -257,3 +268,32 @@ public func warnUnauthorizedPlugins(plugins: ArrayList<Plugin>, caps: Capability
         }
     }
 }
+
+/**
+ * 提示「吃 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/src/plugins/clipboard/plugin_clipboard.cj

@@ -0,0 +1,144 @@
+package cjTauri.plugins.clipboard
+
+import cjTauri.*
+
+import std.collection.*
+import stdx.encoding.json.*
+
+/**
+ * 官方插件 clipboard：系统剪贴板（对标 Tauri 的 clipboard-manager 插件，RFC-003 第 3 期）
+ *
+ * 命令：clipboard:write / clipboard:read
+ * 权限：**不自动放行**，应用要在 capabilities 里显式声明，两种写法等价：
+ *   "commands": ["clipboard:read"]                 // 明文逐条
+ *   "permissions": ["clipboard:readonly"]          // 命名权限集（只放行 read）
+ *   "permissions": ["clipboard:default"]           // 命名权限集（读写全量）
+ * 前端：window.__CJ_TAURI__.clipboard.writeText("...") / readText()
+ *
+ * 真正的读写落在 C 桥（`cj_bridge_clipboard_*`）：GTK / Win32 的剪贴板调用都必须在
+ * 宿主 UI 线程上，core 那边做「UI 线程分流 + 单槽等待」。插件只做参数校验与命令分发，
+ * 平台差异不进插件（AGENTS §2 的架构契约）。
+ *
+ * 读写都要宿主已就绪（start 之后）；更早调用得到 false / None。
+ */
+public class ClipboardPlugin <: Plugin {
+    private let handler: ClipboardCommands = ClipboardCommands()
+
+    public init() {}
+
+    public func name(): String {
+        return "clipboard"
+    }
+
+    public func commands(): HashMap<String, CommandHandler> {
+        let m = HashMap<String, CommandHandler>()
+        m.add("write", this.handler)
+        m.add("read", this.handler)
+        return m
+    }
+
+    /**
+     * 命名权限集（v1.1）：readonly 只放行读——剪贴板里可能有用户敏感内容，
+     * 「只写不读」是合理的最小授权面。
+     */
+    public func permissions(): HashMap<String, ArrayList<String>> {
+        let m = HashMap<String, ArrayList<String>>()
+        let ro = ArrayList<String>()
+        ro.add("read")
+        m.add("readonly", ro)
+        let all = ArrayList<String>()
+        all.add("read")
+        all.add("write")
+        m.add("default", all)
+        return m
+    }
+
+    /**
+     * 前端 shim：往桥对象上挂一个 clipboard 命名空间（与 dialog 同款）
+     */
+    public func jsShim(): String {
+        return "(function () { var t = window.__CJ_TAURI__ || (window.__CJ_TAURI__ = {});" +
+            " t.clipboard = {" +
+            " writeText: function (text) { return window.__CJ_TAURI__.invoke('clipboard:write', { text: text }); }," +
+            " readText: function () { return window.__CJ_TAURI__.invoke('clipboard:read', {}); }" +
+            " }; })();\n"
+    }
+
+    public func setup(app: TauriApp): Unit {
+        // 多窗口按报文里的 label 解析宿主（与 dialog 插件同一口径）。固定 `app.webviewHost()`
+        // 会让第二扇窗的剪贴板命令全部落到默认窗那一个宿主上（2026-10-20 dialog 实机取证同款）。
+        this.handler.attachHostResolver({ label => app.hostOf(label) })
+    }
+}
+
+/**
+ * 剪贴板命令处理器：write 收 { text }，read 无参。
+ */
+public class ClipboardCommands <: CommandHandler {
+    private var host: Option<WebViewHost> = None
+
+    /* 按 label 解析宿主（多窗口的正路）：单槽 `host` 只记着装配时那一个宿主，
+       多窗口下用它就是「所有窗的剪贴板命令都发给默认窗那一个宿主」。 */
+    private var hostByWindow: Option<(String) -> Option<WebViewHost>> = None
+
+    public init() {}
+
+    /** 由 ClipboardPlugin.setup() 调用（单窗口 / 单测用；这个槽不带窗口身份） */
+    public func attachHost(h: WebViewHost): Unit {
+        this.host = Some(h)
+    }
+
+    /** 装配「label → 宿主」解析器；由 ClipboardPlugin.setup() 传入 `app.hostOf` */
+    public func attachHostResolver(resolve: (String) -> Option<WebViewHost>): Unit {
+        this.hostByWindow = Some(resolve)
+    }
+
+    public func handle(cmd: String, args: JsonObject, ipc: IpcContext): JsonValue {
+        match (cmd) {
+            case "clipboard:write" =>
+                let text = this.requireString(args, "text")
+                if (this.requireHost(ipc).clipboardWriteText(text)) {
+                    return JsonNull()
+                }
+                throw CommandException("clipboard: 写入失败（宿主未就绪 / 平台拒绝）")
+            case "clipboard:read" =>
+                match (this.requireHost(ipc).clipboardReadText()) {
+                    case Some(text) => return JsonString(text)
+                    case None => return JsonNull() // 空 / 非文本：合法结果，不是错误
+                }
+            case _ => throw CommandException("unknown clipboard command: ${cmd}")
+        }
+    }
+
+    /**
+     * 取**发起这条命令的窗口**的宿主
+     *
+     * 多窗口下必须按 `ipc.window` 解析：用装配时那一个宿主，第二扇窗的命令会落到默认窗的宿主上。
+     * 解析器在场而窗口没登记时**如实报错**，不回落到单槽（与 dialog 插件同一口径）。
+     */
+    private func requireHost(ipc: IpcContext): WebViewHost {
+        match (this.hostByWindow) {
+            case Some(resolve) => match (resolve(ipc.window)) {
+                case Some(h) => return h
+                case None => throw CommandException(
+                    "clipboard: 窗口 \"${ipc.window}\" 没有登记宿主（addWindow(); 默认窗在 run() 之前也可用）")
+            }
+            case None => ()
+        }
+        match (this.host) {
+            case Some(h) => h
+            case None => throw CommandException(
+                "clipboard: 宿主未装配（用 .plugin(ClipboardPlugin()) 装配插件后才可用）")
+        }
+    }
+
+    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("clipboard: argument \"${key}\" must be a string")
+            }
+            case None => throw CommandException("clipboard: missing argument \"${key}\"")
+        }
+    }
+}