@adep/cli 0.4.4 → 0.4.5

package/templates/app-mobile-xtool/Sources/AdepShell/ShellViewController.swift

@@ -0,0 +1,223 @@
+import AdepBridge
+import Capacitor
+import Foundation
+
+/// 包内站点位置。
+///
+/// `xtool.yml` 声明 `resources: [app/site]`，Packer 的 `packFileToRoot` 走
+/// `FileManager.copyItem(at:to:)`（对目录递归复制），落点 `<.app>/<末段目录名>`
+/// ⇒ 包内路径恒为 `Bundle.main.bundleURL/site/`，与仓库里的 `app/site/` 一一对应。
+///
+/// ⚠️ **不要**改成 `public/`（Capacitor 的默认 `appLocation`）来"省掉"这次重定向：
+/// `public/` 是 `cap sync` 的产物目录名，与 CLI 注入契约（`app/site/`）不是同一个概念；
+/// 两处都用 `public/` 会在同一包里出现两种来源的同一个目录名。
+enum ShellSite {
+    static let directoryName = "site"
+    static let entryName = "index.html"
+
+    static var packagedDirectory: URL {
+        Bundle.main.bundleURL.appendingPathComponent(directoryName, isDirectory: true)
+    }
+
+    static var packagedEntry: URL {
+        packagedDirectory.appendingPathComponent(entryName, isDirectory: false)
+    }
+
+    /// 站点是否随包注入（判 `index.html` 是**文件**，不是只看目录存在——
+    /// 空目录 `site/` 会让 Capacitor 的 `appStartFileURL` 检查走到 `fatalLoadError()` 直接崩）。
+    static func isInstalled(in fileManager: FileManager = .default) -> Bool {
+        var isDirectory: ObjCBool = false
+        let exists = fileManager.fileExists(atPath: packagedEntry.path, isDirectory: &isDirectory)
+        return exists && !isDirectory.boolValue
+    }
+}
+
+/// 站点缺失时的**看得见的**错误页。
+///
+/// 为什么必须有：Capacitor 的 `loadWebView()` 在 `appStartFileURL` 不存在时调
+/// `fatalLoadError()` → `fatalError`（**进程崩溃**，源码 `CAPBridgeViewController.swift`）。
+/// 而"白屏"与"崩溃"都是最难定位的两类症状；这里换成一个写明原因的错误页，
+/// 让「CLI 没注入站点」这件事在设备上一眼可见（fail loud 且不 crash）。
+enum ShellFallbackPage {
+    private static let directoryName = "adep-shell-missing-site"
+
+    /// 生成错误页目录并返回；失败返回 nil（调用方回退到 Capacitor 原生报错路径）。
+    static func materialize(message: String, in fileManager: FileManager = .default) -> URL? {
+        let directory = fileManager.temporaryDirectory
+            .appendingPathComponent(directoryName, isDirectory: true)
+        do {
+            try fileManager.createDirectory(at: directory, withIntermediateDirectories: true)
+            let entry = directory.appendingPathComponent(ShellSite.entryName, isDirectory: false)
+            try html(message: message).write(to: entry, atomically: true, encoding: .utf8)
+            return directory
+        } catch {
+            NSLog("[adep-shell] 错误页写入失败：\(error)")
+            return nil
+        }
+    }
+
+    private static func html(message: String) -> String {
+        let escaped = message
+            .replacingOccurrences(of: "&", with: "&amp;")
+            .replacingOccurrences(of: "<", with: "&lt;")
+            .replacingOccurrences(of: ">", with: "&gt;")
+        return """
+        <!doctype html>
+        <html lang="zh-CN">
+          <head>
+            <meta charset="utf-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1" />
+            <title>AdepShell</title>
+            <style>
+              body { margin: 0; padding: 24px; font: 15px/1.6 -apple-system, system-ui, sans-serif; }
+              h1 { font-size: 17px; margin: 0 0 12px; }
+              code { font-size: 13px; word-break: break-all; }
+            </style>
+          </head>
+          <body>
+            <h1>站点资源未就绪</h1>
+            <p>页面内容应随包注入到 <code>site/</code>，但当前包内缺失：</p>
+            <p><code>\(escaped)</code></p>
+            <p>这是构建期问题（CLI 未注入前端产物），不是网络问题。</p>
+          </body>
+        </html>
+        """
+    }
+}
+
+/// 页面侧诊断注入（真机排障通用面，APP-022 白屏取证落地）。
+///
+/// 页面里的 console / 未捕获异常 / 未处理 rejection 在 WKWebView 里默认**不可见**
+/// （Safari 远程检查要接 Mac）。把三类事件全部经 `WKScriptMessageHandler` 转发到
+/// 系统日志（前缀 `[adep-web]`），真机日志里直接可见页面发生了什么，不用接 Mac。
+/// 诊断脚本经覆写 `webViewConfiguration(for:)` 注入——`prepareWebView` 消费的就是它，
+/// 注入时点早于任何页面脚本（`loadWebView()` 在 `viewDidLoad()` 里，晚于 `loadView()`）。
+enum PageDiagnostics {
+    static let source = """
+;(function(){
+  var send = function(level, msg) {
+    try { window.webkit.messageHandlers.adepDiag.postMessage(level + ': ' + msg); } catch (e) {}
+  };
+  ['log','warn','error','info'].forEach(function(level){
+    var orig = console[level] ? console[level].bind(console) : function(){};
+    console[level] = function(){ send(level, Array.prototype.map.call(arguments, String).join(' ')); orig.apply(null, arguments); };
+  });
+  window.addEventListener('error', function(e){ send('pageerror', e.message + ' @' + e.filename + ':' + e.lineno); });
+  window.addEventListener('unhandledrejection', function(e){ send('rejection', String(e.reason)); });
+})();
+"""
+}
+
+/// 加载回执探针：页面加载完成后延迟读取页面真实状态打系统日志。
+///
+/// 为什么要有：`didFinishNavigation` 只证明「导航完成」，不证明「页面活着」——
+/// JS 全灭的页面同样会走完 didFinish。1.5s / 4s 两条回执读 `document.body.innerText`
+/// 与 `window.__ADEP_APP__`（页面桥装配结果），把「页面真实状态」变成日志可判读的读数。
+///
+/// ⚠️ 装配失败时**必须把原因也打出来**（APP-030）：页面桥失败后会落一个 `mode: 'online'`
+/// 的态对象，光看 `adepApp=online/-` 与正常在线装配**一模一样**——读数存在却区分不了
+/// 「装备好了」和「配置没进包」。三个错误字段（configError / offlineError / timeoutError）
+/// 因此一并进回执。
+enum LoadReceipt {
+    static let source = """
+;(function(){
+  var report = function(tag){
+    var app = window.__ADEP_APP__;
+    var err = !app ? '' : (app.configError ? ' CONFIG_ERR=' + app.configError.slice(0, 160) : '')
+      + (app.offlineError ? ' OFFLINE_ERR=' + app.offlineError.slice(0, 160) : '')
+      + (app.timeoutError ? ' TIMEOUT_ERR=' + app.timeoutError.slice(0, 160) : '');
+    return tag + ' bodyText=' + (document.body ? document.body.innerText.slice(0, 80) : 'null')
+      + ' adepApp=' + (app ? app.mode + '/' + (app.version || '-') + err : 'MISSING');
+  };
+  setTimeout(function(){ try { window.webkit.messageHandlers.adepDiag.postMessage('RECEIPT-1.5s ' + report('t1.5')); } catch(e){} }, 1500);
+  setTimeout(function(){ try { window.webkit.messageHandlers.adepDiag.postMessage('RECEIPT-4s ' + report('t4') + ' url=' + location.href); } catch(e){} }, 4000);
+})();
+"""
+}
+
+/// 诊断消息的宿主（`adepDiag` handler 的接收端；只做转发打日志）。
+///
+/// ⚠️ **必须用 `NSLog`，不能用 `CAPLog.print`**：`CAPLog.print` 内部是 `Swift.print`
+/// → 写 **stdout**；SpringBoard 拉起的 app 没人接 stdout，输出直接蒸发。
+/// 而 `NSLog` 走 os_log，`idevicesyslog` 才收得到（2026-10-22 真机实测：
+/// syslog 里只有 WebKit 自己的 os_log 行，全部 `[adep-shell]`/`[adep-web]` 行缺失）。
+final class DiagMessageHandler: NSObject, WKScriptMessageHandler {
+    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
+        NSLog("[adep-web] \(message.body)")
+    }
+}
+
+/// 壳的根视图控制器：Capacitor 的 WebView 宿主。
+///
+/// 站点注入点只有一个——覆写 `instanceDescriptor()` 把 `appLocation` 指到包内 `site/`。
+/// 之后 Capacitor 自己会：
+///   1. `assetHandler.setAssetPath(appLocation.path)`（`loadView()` 里）；
+///   2. `loadWebView()` 检查 `appStartFileURL` = `appLocation/index.html` 存在；
+///   3. 从 `appStartServerURL` 加载——即 `capacitor://localhost/`，由 Capacitor 的
+///      `WKURLSchemeHandler` 从 `appLocation` 供文件。
+///
+/// ⚠️ **刻意不用 `loadFileURL(_:allowingReadAccessTo:)`**（任务单原设想的形态）：
+/// file:// 页面的 origin 是 **null**，`fetch()` 打平台地址（`platformUrl`，https）会带
+/// `Origin: null`，服务端要额外放行 null origin；而走 Capacitor 的本地 scheme 拿到的是
+/// 正常源 `capacitor://localhost`，且 MIME / 相对路径解析由框架既有实现负责。
+/// 这条设计改动已回填计划 §12.20（N-2 的验收形态随之变化：不再依赖 file 读取权限语义）。
+final class ShellViewController: CAPBridgeViewController {
+    /// 把 `AdepBridge` 交给 Capacitor 的插件表（APP-018）。
+    ///
+    /// **时机依据（Capacitor 7.6.9 源码）**：`loadView()` 末尾调 `capacitorDidLoad()`，而
+    /// `loadWebView()` 在 `viewDidLoad()` 里 ⇒ 注册早于页面加载与 JS 导出；`registerPluginInstance`
+    /// 内部还会 `pluginInstance.load(on:)` + `JSExport.exportJS(...)`，所以插件脚本一定先于页面就绪。
+    ///
+    /// ⚠️ **不要改成 `registerPluginType(_:)`**：它首行是 `if autoRegisterPlugins { return }`，
+    /// 而 `CAPBridgeViewController` 构造 bridge 时没传该开关（默认 true）⇒ 类型注册是**空操作**，
+    /// 写了等于没写、且不报错（`CapacitorBridge.swift`）。实例注册不受该开关影响，并且写进
+    /// 的正是 `plugin(withName:)` 读的那张 `plugins` 表。
+    override func capacitorDidLoad() {
+        super.capacitorDidLoad()
+        guard let bridge = bridge else {
+            NSLog("[adep-shell] capacitorDidLoad 时 bridge 为 nil —— AdepBridge 未注册")
+            return
+        }
+        bridge.registerPluginInstance(AdepBridge())
+        // 正向证据（不是「应该注册了」）：注册失败时 Capacitor 只打一行日志就 return
+        // （`as? CapacitorPlugin` 不满足 / 实例为 nil），而页面上的症状与「没注册」完全一样
+        // ——都是 NATIVE_UNAVAILABLE。所以这里必须留一行可读的判活读数。
+        let registered = bridge.plugin(withName: "AdepBridge") != nil
+        // NSLog 而非 CAPLog.print——stdout 在 SpringBoard 拉起的 app 里无人接收（见 DiagMessageHandler）。
+        NSLog("[adep-shell] AdepBridge registered: \(registered)")
+    }
+
+    /// 注入页面诊断脚本（console / error / rejection → 系统日志）+ 加载回执探针。
+    /// 依据见 `PageDiagnostics` 注释；handler 加在 super 的 controller 上（保留 Capacitor 自身注入）。
+    override func webViewConfiguration(for instanceConfiguration: InstanceConfiguration) -> WKWebViewConfiguration {
+        let config = super.webViewConfiguration(for: instanceConfiguration)
+        let controller = config.userContentController
+        controller.add(DiagMessageHandler(), name: "adepDiag")
+        controller.addUserScript(WKUserScript(source: PageDiagnostics.source, injectionTime: .atDocumentStart, forMainFrameOnly: true))
+        controller.addUserScript(WKUserScript(source: LoadReceipt.source, injectionTime: .atDocumentEnd, forMainFrameOnly: true))
+        return config
+    }
+
+    override func instanceDescriptor() -> InstanceDescriptor {
+        let descriptor = super.instanceDescriptor()
+        descriptor.appLocation = resolveAppLocation()
+        // 装载读数（白屏排障，APP-022）：appLocation 解析结果是壳层唯一的自由变量，
+        // 打出来才能区分「包内 site 缺失走了错误页」与「正常指向 site/」两种形态。
+        // NSLog 而非 CAPLog.print——stdout 在 SpringBoard 拉起的 app 里无人接收。
+        NSLog("[adep-shell] appLocation: \(descriptor.appLocation.path)")
+        return descriptor
+    }
+
+    private func resolveAppLocation() -> URL {
+        if ShellSite.isInstalled() {
+            return ShellSite.packagedDirectory
+        }
+        let expected = ShellSite.packagedEntry.path
+        if let fallback = ShellFallbackPage.materialize(message: expected) {
+            NSLog("[adep-shell] app/site 未注入，改用错误页；期望路径：\(expected)")
+            return fallback
+        }
+        // 兜底：交回原路径，让 Capacitor 的 fatalLoadError 把真实期望路径打出来（fail loud）。
+        return ShellSite.packagedDirectory
+    }
+}

package/templates/app-mobile-xtool/adep.permissions.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "permissions": []
+}

package/templates/app-mobile-xtool/template.json

@@ -0,0 +1,15 @@
+{
+  "code": "app-mobile-xtool",
+  "name": "移动应用壳（xtool / iOS 原生）",
+  "description": "xtool 壳工程：SwiftPM app target（AdepShell）+ WKWebView 消费 app/site/ 产物，经 xtool 编译为**真 iOS app**（不依赖 Xcode 工程文件）；在线运行时（云函数经 platformUrl 服务端执行）；原生桥仍复用 plugins/adep-bridge（源码单一来源，渲染期注入）",
+  "version": "0.1.0",
+  "variables": [
+    {
+      "name": "projectSlug",
+      "description": "平台项目 slug（写入包名 / adep.app.json / bundle id 推导）"
+    },
+    { "name": "appName", "description": "应用显示名（写 Info.plist 的 CFBundleDisplayName；产品名固定 AdepShell，见 README）" },
+    { "name": "platformUrl", "description": "平台地址（页面侧 @adep/client 以此为 baseUrl invoke 云函数）" },
+    { "name": "iosBundleId", "description": "iOS bundle identifier（top.adep.<slug>，连字符合法）" }
+  ]
+}

package/templates/app-mobile-xtool/xtool.yml

@@ -0,0 +1,35 @@
+# xtool 壳工程配置（APP-016）。
+#
+# ⚠️ **键名必须逐字来自 xtool 的 PackSchemaBase**（源码 `Sources/PackLib/PackSchema.swift`）：
+#   version / orgID / bundleID / product / infoPath / entitlementsPath / iconPath /
+#   resources / extensions / skipLSP
+# Yams 解码**静默忽略未知键** ⇒ 拼错（如小写 `bundleId`）不报错、只是不生效，
+# 而症状是「bundle id 还是默认值」这种极难定位的偏差。`app-shell-xtool.test.ts` 的键白名单
+# 就是钉这一条。
+#
+# 各键在此处的取值理由：
+#   - `bundleID`：渲染期由 CLI 填 `top.adep.<slug>`（免费签名时 `com.example.*` 会被 Apple 拒，
+#     计划 §12.16 踩过）。留成模板变量，不写死。
+#     ⚠️ 值**必须加引号**：YAML 1.2 把不带引号的双花括号占位符解析成 **flow mapping**
+#     （花括号套花括号）而不是字符串。渲染器在文本层替换，所以产物碰巧仍是合法 YAML，
+#     但模板文件本身对任何 YAML 工具都是坏结构——实测就是这个坑（首版未加引号，
+#     测试里的 `parse()` 读出来是 `{ "{ iosBundleId }": null }`）。
+#     ⚠️ 注释里也**不得**出现「双花括号 + 英文标识符」的字面量：渲染器会把它当变量、
+#     白名单校验直接 fail loud（实测：注释里写了单个字母的示范串 ⇒ adep app init 当场抛
+#     SHELL_TEMPLATE_INVALID）。所以坑只能这样用文字描述，不能写出样子来
+#     （与「JSDoc 里不能写 cron 通配」同族：被解析的文本里不能放会被解析的样例）。
+#   - `product`：必须与 Package.swift 的 library product 名逐字一致（`AdepShell`）——
+#     xtool 按名字在包内选主 product，对不上报「找不到 main product」。
+#   - `infoPath`：只放**要覆盖**的键。xtool 已经默认注入 CFBundleIdentifier / CFBundleVersion /
+#     MinimumOSVersion（取 Package.swift 的 iOS 版本）/ UILaunchScreen / 屏幕方向等，
+#     这里的 plist 是 `merge(uniquingKeysWith: { $1 })` ⇒ 同名键以本文件为准。
+#   - `resources`：**目录是被支持的**（不是只吃单文件）。Packer 的 `packFileToRoot` 走
+#     `FileManager.copyItem(at:to:)`——对目录递归复制，落点是 `<.app>/<lastPathComponent>`
+#     ⇒ 写 `app/site` 得到 `Payload/AdepShell.app/site/`，嵌套相对路径原样保留。
+#     ⚠️ 各条资源的**末段目录名**不能撞车（copyItem 目标已存在即抛错）。
+version: 1
+bundleID: "{{iosBundleId}}"
+product: AdepShell
+infoPath: AdepShell-Info.plist
+resources:
+  - app/site

package/templates/app-mobile/plugins/adep-bridge/capacitor.plugin.json

@@ -1,10 +0,0 @@
-{
-  "ios": {
-    "src": "ios",
-    "dest": "ios"
-  },
-  "android": {
-    "src": "android",
-    "dest": "android"
-  }
-}