@adep/cli 0.4.1 → 0.4.5

package/templates/app-desktop/recovery-ui.mjs

@@ -0,0 +1,300 @@
+/**
+ * 恢复码呈现与导出（APP-034，app-desktop 模板）。
+ *
+ * 背景：APP-033 让桌面壳首启自举把恢复码**落库**（明文只在签发响应里出现一次，
+ * 服务端只存摘要、任何端点都不重发），但用户从没见过它——直到真丢了 ownerKey
+ * 才发现手里没有认领凭据。本模块补上「读数 → 呈现 → 导出」的最后一跳。
+ *
+ * 形态决策（为什么全在主进程、不进渲染进程）：
+ * - 页面是**用户内容**（app/site/ 产物），壳不能往里注 DOM，也没有设置页可挂；
+ * - Electron 的应用菜单 + 原生对话框就是壳自己的「设置 / 关于」面，不改 preload、
+ *   不开 IPC——恢复码与 ownerKey 都**不进渲染进程**（APP-033 已立的边界不回退）。
+ *
+ * 「呈现一次」的判定：`data/identity/recovery-code-shown` 标记文件。
+ * 刻意**不**绑死「本次刚签发」：老安装升级到带本模块的版本时，用户同样一次都没见过码，
+ * 标记缺失 + 码可读 ⇒ 也呈现一次。呈现过就写标记，此后只从菜单进（不再主动弹）。
+ *
+ * JSDoc 用 `@typedef` + `@property` 形态（**别写对象字面量类型**——模板渲染门
+ * 会咬「白名单外的双花括号残留」，APP-033 实证；连注释里提这个写法都不行）。
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 「已呈现过」标记文件名（落 data/identity/，非机密读数）。 */
+export const RECOVERY_SHOWN_FILE = 'recovery-code-shown'
+
+/** @returns {string} 标记文件绝对路径（root 为壳工程根）。 */
+export function recoveryShownPath(root) {
+  return join(root, 'data', 'identity', RECOVERY_SHOWN_FILE)
+}
+
+/** @returns {boolean} 标记是否存在（不存在 / 读不到都当「没呈现过」）。 */
+export function readShownMarker(root) {
+  return existsSync(recoveryShownPath(root))
+}
+
+/**
+ * 写「已呈现过」标记（内容是时间戳，给人看的；判据只看存在性）。
+ * 目录自建：老安装升级上来时 data/identity/ 可能还没有（自举没跑过），不能 ENOENT。
+ *
+ * @param {string} root 壳工程根
+ */
+export function writeShownMarker(root) {
+  const file = recoveryShownPath(root)
+  mkdirSync(join(file, '..'), { recursive: true })
+  writeFileSync(file, `${new Date().toISOString()}\n`)
+}
+
+/**
+ * 呈现一次的判定（纯函数——判据的核心在这里，Electron 只是执行器）。
+ *
+ * @param {adepShowDecisionInput} input
+ * @returns {boolean} true = 应该弹一次
+ */
+export function shouldShowFirstTime(input) {
+  return input.codeReadable && !input.alreadyShown
+}
+
+/**
+ * 首次呈现对话框的形态（文案与按钮顺序在这里定，测试钉这里）。
+ *
+ * 按钮：0 = 复制到剪贴板，1 = 导出到文件，2 = 我已保存（关闭）。
+ * cancelId 必须是「我已保存」：Esc / 关窗不算「没保存」，只是不主动了。
+ *
+ * @param {adepDialogTextInput} input
+ * @returns {electronDialogOptions}
+ */
+export function firstShowDialogOptions(input) {
+  return {
+    type: 'info',
+    title: '设备恢复码（请妥善保存）',
+    message: '这是你的设备恢复码，服务端无法重发',
+    detail:
+      `${input.code}\n\n` +
+      '它用于在换机 / 重装后重新认领本设备的同步分区。服务端只存摘要，' +
+      '丢了码等于放弃认领——请导出或复制到安全的地方保存。',
+    buttons: ['复制到剪贴板', '导出到文件…', '我已保存'],
+    defaultId: 2,
+    cancelId: 2,
+    noLink: true,
+  }
+}
+
+/**
+ * 再次查看 / 导出用的通用对话框形态（菜单入口；同样只呈现不设置默认复制）。
+ *
+ * @param {adepDialogTextInput} input
+ * @returns {electronDialogOptions}
+ */
+export function reviewDialogOptions(input) {
+  return {
+    type: 'info',
+    title: '设备恢复码',
+    message: '这是你的设备恢复码，服务端无法重发',
+    detail:
+      `${input.code}\n\n` +
+      '换机 / 重装后在登录流程提交它即可重新认领本设备的同步分区。',
+    buttons: ['复制到剪贴板', '导出到文件…', '关闭'],
+    defaultId: 2,
+    cancelId: 2,
+    noLink: true,
+  }
+}
+
+/**
+ * 导出文件的内容（导出即用户自担保存责任，头两行把后果写明）。
+ *
+ * @param {adepExportTextInput} input
+ * @returns {string}
+ */
+export function exportRecoveryText(input) {
+  const when = typeof input.at === 'string' ? input.at : new Date().toISOString()
+  return [
+    'adep 设备恢复码',
+    `应用：${input.appName}（项目 ${input.projectSlug}）`,
+    `导出时间：${when}`,
+    '',
+    '⚠️ 服务端只存本码的摘要、无法重发；丢了码等于放弃本设备同步分区的认领。',
+    '请把本文件存到密码管理器或其他安全的地方，不要留在下载目录里。',
+    '',
+    `恢复码：${input.code}`,
+    '',
+  ].join('\n')
+}
+
+/** 导出文件缺省名（带项目 slug，多项目时一眼可分）。 */
+export function exportDefaultFileName(projectSlug) {
+  return `adep-recovery-code-${projectSlug}.txt`
+}
+
+/**
+ * 造恢复码动作集。**全部依赖注入**（dialog / clipboard 来自 Electron，
+ * 但不在本模块 import——单测用假件真跑行为，判据不撞渲染器）。
+ *
+ * @param {adepRecoveryActionsInput} input
+ * @returns {adepRecoveryActions}
+ */
+export function createRecoveryActions(input) {
+  const { root, readRecoveryCode, appName, projectSlug } = input
+  const deps = {
+    dialog: input.deps.dialog,
+    clipboard: input.deps.clipboard,
+    log: input.deps.log ?? (() => {}),
+  }
+
+  /** 读码并归一「可读」判定（空串 / 非串都算不可读）。 */
+  async function readCode() {
+    const code = await readRecoveryCode()
+    return typeof code === 'string' && code !== '' ? code : null
+  }
+
+  async function copyToClipboard(code) {
+    deps.clipboard.writeText(code)
+    deps.log('[adep-app] 恢复码已复制到剪贴板')
+  }
+
+  async function exportToFile() {
+    const code = await readCode()
+    if (code === null) return { exported: false, reason: 'CODE_UNREADABLE' }
+    const result = await deps.dialog.showSaveDialog({
+      title: '导出设备恢复码',
+      defaultPath: exportDefaultFileName(projectSlug),
+      properties: ['createDirectory', 'showOverwriteConfirmation'],
+    })
+    if (result.canceled || typeof result.filePath !== 'string' || result.filePath === '') {
+      return { exported: false, reason: 'CANCELED' }
+    }
+    writeFileSync(result.filePath, exportRecoveryText({ code, appName, projectSlug }))
+    deps.log(`[adep-app] 恢复码已导出到 ${result.filePath}`)
+    return { exported: true, filePath: result.filePath }
+  }
+
+  /** 用户在对话框里点完按钮后的分流（showOnceIfNeeded / showAgain 共用）。 */
+  async function handleDialogChoice(code, choice) {
+    if (choice.response === 0) await copyToClipboard(code)
+    if (choice.response === 1) await exportToFile()
+  }
+
+  return {
+    /**
+     * 首次呈现：码可读且未呈现过 ⇒ 弹一次并写标记。幂等——调用多少次只弹一次。
+     * 码不可读（未签发 / 存储失败）不弹也不写标记（下次启动还有机会）。
+     */
+    async showOnceIfNeeded() {
+      const code = await readCode()
+      const decision = shouldShowFirstTime({
+        codeReadable: code !== null,
+        alreadyShown: readShownMarker(root),
+      })
+      if (!decision) return { shown: false }
+      const choice = await deps.dialog.showMessageBox(firstShowDialogOptions({ code, appName }))
+      await handleDialogChoice(code, choice)
+      writeShownMarker(root)
+      deps.log('[adep-app] 恢复码已首次呈现（此后从应用菜单「凭据」进入）')
+      return { shown: true }
+    },
+
+    /** 菜单入口：再次查看。码不可读时给出可解释的失败（不是静默空窗）。 */
+    async showAgain() {
+      const code = await readCode()
+      if (code === null) {
+        await deps.dialog.showMessageBox({
+          type: 'warning',
+          title: '恢复码不可读',
+          message: '没有找到可读的设备恢复码',
+          detail:
+            '可能原因：本应用尚未完成设备签发（离线首启需要网络），或受保护存储读取失败。' +
+            '排查用 adep app doctor（identity 项）。',
+          buttons: ['好'],
+          noLink: true,
+        })
+        return { shown: false, reason: 'CODE_UNREADABLE' }
+      }
+      const choice = await deps.dialog.showMessageBox(reviewDialogOptions({ code, appName }))
+      await handleDialogChoice(code, choice)
+      return { shown: true }
+    },
+
+    exportToFile,
+
+    /**
+     * 应用菜单「凭据」子菜单项（Menu.buildFromTemplate 直接吃）。
+     * click 里 void 掉 promise：菜单回调不吃 await，失败走 log（不崩主进程）。
+     */
+    menuItems() {
+      return [
+        { label: '查看恢复码…', click: () => void this.showAgain().catch((e) => deps.log(`[adep-app] 恢复码查看失败：${e?.message ?? e}`)) },
+        { label: '导出恢复码…', click: () => void this.exportToFile().catch((e) => deps.log(`[adep-app] 恢复码导出失败：${e?.message ?? e}`)) },
+      ]
+    },
+  }
+}
+
+/**
+ * @typedef {Object} adepShowDecisionInput
+ * @property {boolean} codeReadable 受保护存储里读得到非空恢复码
+ * @property {boolean} alreadyShown 标记文件是否存在
+ */
+
+/**
+ * @typedef {Object} adepDialogTextInput
+ * @property {string} code 恢复码明文
+ * @property {string} appName 应用名（对话框标题用）
+ */
+
+/**
+ * @typedef {Object} adepExportTextInput
+ * @property {string} code 恢复码明文
+ * @property {string} appName 应用名
+ * @property {string} projectSlug 项目 slug
+ * @property {string} [at] 导出时间（缺省 now；测试注入固定值）
+ */
+
+/**
+ * @typedef {Object} adepRecoveryActionsInput
+ * @property {string} root 壳工程根
+ * @property {() => Promise<string|null>} readRecoveryCode 受保护存储读口（identity-store）
+ * @property {string} appName 应用名
+ * @property {string} projectSlug 项目 slug
+ * @property {adepRecoveryDeps} deps Electron 面板 / 剪贴板 / 日志（全注入）
+ */
+
+/**
+ * @typedef {Object} adepRecoveryDeps
+ * @property {electronDialog} dialog
+ * @property {electronClipboard} clipboard
+ * @property {(line: string) => void} [log]
+ */
+
+/**
+ * @typedef {Object} electronDialog
+ * @property {(options: electronDialogOptions) => Promise<{response: number, checked: boolean}>} showMessageBox
+ * @property {(options: electronSaveDialogOptions) => Promise<{canceled: boolean, filePath?: string}>} showSaveDialog
+ */
+
+/**
+ * Electron 剪贴板面（main.mjs 传 `clipboard`；测试传假件）。
+ *
+ * @typedef {Object} electronClipboard
+ * @property {(text: string) => void} writeText
+ */
+
+/**
+ * @typedef {Object} electronDialogOptions
+ * @property {string} type
+ * @property {string} title
+ * @property {string} message
+ * @property {string} detail
+ * @property {string[]} buttons
+ * @property {number} defaultId
+ * @property {number} cancelId
+ * @property {boolean} noLink
+ */
+
+/**
+ * @typedef {Object} electronSaveDialogOptions
+ * @property {string} title
+ * @property {string} defaultPath
+ * @property {string[]} properties
+ */

package/templates/app-desktop/sync-loop.mjs

@@ -0,0 +1,137 @@
+/**
+ * 壳内后台同步驱动（APP-033 第 4 项；transport 本身是 APP-032 的 `sync-transport.ts`）。
+ *
+ * ## 为什么单独一个模块
+ *
+ * 主进程要的是「启动后跑一轮、之后按间隔重跑、失败不打扰用户」，而 `SyncTransport`
+ * 只提供一次往返。把这层留在 `main.mjs` 里就等于**不可测**（main 一 import 就要 electron），
+ * 于是「并发两轮会不会打架」「失败一轮之后还跑不跑」这类判定只能靠读代码猜——
+ * 本仓最反对的就是这个（APP-030/APP-031 的读数教训）。
+ *
+ * ## 四条约定
+ *
+ * 1. **首轮有延迟**（`initialDelayMs`，缺省 5s，且不超过间隔）：窗口要先把页面画出来，
+ *    同步不该和首屏抢网络；延迟是**可注入**的，测试不必真等。
+ * 2. **不重叠**：上一轮没结束就跳过本轮（`skipped: true`），不排队——排队会在断网时堆成
+ *    一串永远不会成功的请求。
+ * 3. **失败不致命**：任一轮抛错只落一条带原因码的日志（`SYNC_BLOCKED`），下一轮照常；
+ *    本地读写完全不经过这里，所以「同步挂了」≠「app 挂了」。
+ * 4. **每轮必打一行日志**：0 行日志与「循环根本没在跑」不可区分（定时器类老坑）。
+ */
+
+/** 同步循环的缺省参数（改了会影响所有壳；测试全部显式注入）。 */
+export const SYNC_LOOP_DEFAULTS = {
+  /** 首轮延迟：让首屏先出来（与「补首轮 delay=min(60s, interval)」同思路）。 */
+  initialDelayMs: 5_000,
+  /** 轮间隔：5 分钟。单主同步是「最终一致」，不该更密。 */
+  intervalMs: 300_000,
+}
+
+/** 失败原因码（日志首词，排障先看码）。 */
+export const SYNC_BLOCKED_CODE = 'SYNC_BLOCKED'
+
+/**
+ * @typedef {Object} adepSyncLoopOptions
+ * @property {adepSyncTransport} sync 设备端 transport（APP-032 的 createSyncTransport 返回值）
+ * @property {(line: string) => void} [log] 每轮必打一行（0 行日志与没跑不可区分）
+ * @property {number} [intervalMs] 轮间隔（缺省 5 分钟）
+ * @property {number} [initialDelayMs] 首轮延迟（缺省 5s，且不超过间隔）
+ * @property {(fn: () => void, ms: number) => unknown} [setTimeout] 定时器注入（测试用假时钟）
+ * @property {(handle: unknown) => void} [clearTimeout]
+ */
+
+/**
+ * @typedef {Object} adepSyncTransport
+ * @property {(limit?: number) => Promise<{push: {pushed: number, remaining: number}, pull: {applied: number, hasMore: boolean}}>} sync 一次往返（push + pull）
+ */
+
+/**
+ * 造一个后台同步循环。**不会自动启动**（`start()` 才排第一轮）。
+ *
+ * @param {adepSyncLoopOptions} options
+ */
+export function createSyncLoop(options) {
+  const {
+    sync,
+    log = () => {},
+    intervalMs = SYNC_LOOP_DEFAULTS.intervalMs,
+    initialDelayMs = SYNC_LOOP_DEFAULTS.initialDelayMs,
+    setTimeout: schedule = globalThis.setTimeout,
+    clearTimeout: cancel = globalThis.clearTimeout,
+  } = options
+
+  /** @type {unknown} */
+  let timer = null
+  let running = false
+  let stopped = false
+  let cycles = 0
+
+  /**
+   * 跑一轮（并发保护在这里，`start()` 与手动调用共用）。
+   *
+   * 返回结构性结果而不是 throw：调用方（主进程）没有任何理由为了同步失败去炸窗口。
+   */
+  const runOnce = async () => {
+    if (running) {
+      log(`[adep-sync] 上一轮未结束，跳过本轮（第 ${cycles + 1} 轮）`)
+      return { skipped: true, cycles }
+    }
+    running = true
+    cycles += 1
+    const ordinal = cycles
+    try {
+      const result = await sync.sync()
+      log(
+        `[adep-sync] 第 ${ordinal} 轮完成：上行 ${result.push.pushed} 条（余 ${result.push.remaining}）` +
+          `· 下行 ${result.pull.applied} 条${result.pull.hasMore ? '（还有更多）' : ''}`
+      )
+      return { skipped: false, cycles: ordinal, result }
+    } catch (error) {
+      log(
+        `[adep-sync] ${SYNC_BLOCKED_CODE}: 第 ${ordinal} 轮失败——${
+          error instanceof Error ? error.message : String(error)
+        }（本地读写不受影响，下一轮重试）`
+      )
+      return { skipped: false, cycles: ordinal, error }
+    } finally {
+      running = false
+    }
+  }
+
+  /** 定时器回调：先清掉句柄再跑，跑完（无论成败）才排下一轮 ⇒ 天然不重叠。 */
+  const tick = () => {
+    timer = null
+    void runOnce().finally(() => {
+      if (!stopped) timer = schedule(tick, intervalMs)
+    })
+  }
+
+  return {
+    /** 排首轮（延迟 = min(initialDelayMs, intervalMs)）。重复调用无副作用。 */
+    start() {
+      if (stopped || timer !== null) return
+      const delay = Math.min(initialDelayMs, intervalMs)
+      log(`[adep-sync] 后台同步已排程：首轮 ${delay}ms 后，之后每 ${intervalMs}ms 一轮`)
+      timer = schedule(tick, delay)
+    },
+    /** 停循环（窗口关闭 / 退出前调用）。已在跑的那一轮不打断——它自己会结束。 */
+    stop() {
+      stopped = true
+      if (timer !== null) {
+        cancel(timer)
+        timer = null
+      }
+      log(`[adep-sync] 后台同步已停止（共 ${cycles} 轮）`)
+    },
+    /** 手动跑一轮（e2e / 诊断用；与定时轮共享并发保护）。 */
+    runOnce,
+    /** 已跑的轮次（含失败轮）。 */
+    get cycles() {
+      return cycles
+    },
+    /** 是否有定时器在等（`false` 且 `cycles === 0` ⇒ 根本没启动）。 */
+    get scheduled() {
+      return timer !== null
+    },
+  }
+}

package/templates/app-mobile/README.md

@@ -32,9 +32,9 @@ npx cap add ios        # 生成 ios/ Xcode 工程
 npx cap add android    # 生成 android/ Gradle 工程
 ```
 
-> Android：`cap add` 生成的 `android/app/build.gradle` 里 `applicationId` 默认取
-> `capacitor.config.ts` 的 `appId`；按 `{{androidPackageId}}` 修改（applicationId 不允许
-> 连字符，iOS bundle id 不允许下划线——两端无法共用一个 id）。
+> 两端 bundle id 由 CLI 从 slug 推导为**剔除连字符**的形态（`top.adep.demoapp`）：
+> capacitor 的 appId 双端共用且校验禁连字符，而下划线形态会让 iOS 在开发者后台签
+> App ID 时被拒——剔除是唯一双端全绿的映射，`cap add` 直接通过，无需手工修改。
 
 ## 打 unsigned 安装包
 
@@ -74,12 +74,50 @@ const result = await client.invokeFunction('hello', { name: 'world' })
   （如 `ACCESS_FINE_LOCATION`）。本插件**不**主动索取任何系统权限。
 - 设备端函数（离线运行时）请求原生能力：`await window.__ADEP_APP__.invokeNative('geolocation', {})`。
 
-## ownerKey 存储（§2.11.5 设备身份与恢复）
-
-安装首启时由壳原生侧向服务端签发端点换取 ownerKey，**只存 Keychain（iOS）/ Keystore
-（Android）**：`AdepKeychain.swift`（`kSecClassGenericPassword`）/
-`AdepKeystore.kt`（Android Keystore + AES/GCM，密文落 SharedPreferences）。明文不落 JS
-侧 / 明文文件；插件提供 `getOwnerKey` / `setOwnerKey` / `deleteOwnerKey`（恢复码认领时换键）。
+## 原生桥方法（机器可读契约）
+
+<!-- 下方名单必须与 plugins/adep-bridge/dist/plugin.js 的对象键相等
+     （app-bridge-registration-contract.test.ts 钉住，改一边不改另一边会红） -->
+
+JS 面可调用：`invokeNative` / `getOwnerKey` / `getRecoveryCode` / `sqliteRun` / `sqliteAll` / `sqliteGet`
+
+## ownerKey 签发与存储（§2.11.5 设备身份与恢复）
+
+**当前状态（APP-027）：首启原生自举已接线，ownerKey 由服务端签发、只存 Keychain / Keystore。**
+
+- 存储：`AdepKeychain.swift`（`kSecClassGenericPassword`）/ `AdepKeystore.kt`
+  （Android Keystore + AES/GCM，密文落 SharedPreferences）。明文不落 JS 侧、不落明文文件。
+- **签发（首启，仅原生侧）**：`AdepIdentity.swift` / `AdepIdentity.kt` 在 `load()` 后由后台线程
+  调 `POST <platformUrl>/api/v1/projects/<projectSlug>/app-installations`（body `{ platform }`），
+  成功后写 Keychain / Keystore，**再**把设备本地库的 key 换成它（见下）。
+  - **幂等**：本地已有合法 ownerKey ⇒ 不发请求（一枚安装只签发一次）。
+  - **失败不阻断**：断网 / 5xx / 响应形态不符 ⇒ 不写空值、不覆盖既有值、页面照常加载，
+    日志带原因码（`IDENTITY_CONFIG_MISSING` / `IDENTITY_REQUEST_FAILED` /
+    `IDENTITY_RESPONSE_INVALID` / `IDENTITY_STORE_FAILED`），下次启动重试。
+  - **页面拿不到写凭据的通道**：写只发生在原生侧（`AdepIdentityBootstrap` +
+    `saveOwnerKey`），`dist/plugin.js` 的对象键集合不变——XSS 不能替换 ownerKey 劫持分区。
+- 页面侧只读：`getOwnerKey` 返回明文（未签发 / 签发失败时为 `null`）。单主同步
+  （`/app-sync/*` 的 `Bearer <ownerKey>`）依赖它，因此调用方必须处理 null。
+- 设备本地 SQLite（APP-025/026）的库 key **= ownerKey**；ownerKey 缺失时（离线首启）先落
+  **硬编码缺省**（`AdepSqlite.fallbackKey`，只能算「有锁」不算安全 key），ownerKey 一到即
+  `PRAGMA rekey` 原地换成正式 key（数据行保留，旧 key 立刻失效）；重启时若换代发生在退出前，
+  `open()` 会自动探测并升级老库。**不处理就是「换 key 后老库打不开」**。
+- **恢复码（APP-028）**：签发响应里的 `recoveryCode` **同批落库**（iOS 独立 Keychain service
+  `adep.recoveryCode`；Android 独立 prefs 文件 `adep_keystore_recovery`），与 ownerKey 同生命周期、
+  同覆盖语义。服务端只存它的**摘要**、明文只在这次响应里出现一次 ⇒ 丢即该安装的分区永久不可认领，
+  所以写入后还要**读回校验**，任一环节失败则本次不落 ownerKey（下次启动重签）。
+  **呈现与导出（APP-034）**：页面经 `getRecoveryCode` 读明文（与 `getOwnerKey` 同一
+  只读面），由页面产品代码决定一次性弹层 / 设置项 / 导出的节奏——服务端无法重发，
+  丢了码等于放弃认领，呈现文案必须写明这一点。
+- 恢复码认领端点 `/app-installations/recover` 已交付；认领后的换键流程另单。
+
+## iOS / Android 打包前提（APP-027）
+
+- iOS：签发走 `URLSession` + https，无需额外权限；若平台地址是明文 http，需在
+  `Info.plist` 配 ATS 例外（生产不建议）。
+- Android：插件 `AndroidManifest.xml` 显式声明 `INTERNET`（安装期权限、无弹窗）——
+  不声明就等于把「能不能发请求」押在宿主 app 的 manifest 上，缺了症状是每次启动
+  `IDENTITY_REQUEST_FAILED`（看起来像「服务端没部署」）。
 
 ## iOS 约束（§2.11.4 / §2.11.7）
 

package/templates/app-mobile/package.json

@@ -19,6 +19,7 @@
   "devDependencies": {
     "@capacitor/cli": "^7.0.0",
     "@capacitor/ios": "^7.0.0",
-    "@capacitor/android": "^7.0.0"
+    "@capacitor/android": "^7.0.0",
+    "typescript": "5.9.3"
   }
 }

package/templates/app-mobile/plugins/adep-bridge/Package.swift

@@ -0,0 +1,52 @@
+// swift-tools-version: 5.9
+//
+// adep-bridge 的 Swift Package Manager 清单（APP-015）。
+//
+// ⚠️ **这是双形态中的一支，不是替代品**：CocoaPods 形态（`ios/AdepBridge.podspec`）**必须同时保留**——
+// Capacitor 官方口径是「插件同时是 CocoaPods 与 SPM 库」；自 Capacitor 8 起 `cap add ios` 默认建 SPM 工程，
+// 没有本文件的插件会被静默跳过（运行时表现为 "plugin is not implemented"）。两支并存，各管一条消费路径。
+//
+// 命名与布局**不能随意改**（改了 Capacitor CLI 就找不到这个包）：
+//   - 本文件必须在 **npm 包根**：`cap sync ios` 按 npm 包根路径写入 `.package(name:path:)`
+//     （`path: ".../node_modules/@adep/bridge"`），落在 `ios/` 下不会被消费。
+//   - `name` / product 名 = `AdepBridge`：由 npm 名 `@adep/bridge` 按官方规则派生
+//     （剥 `@`、`/`→`_`、分段首字母大写）。用别的名字会在 app 侧报
+//     "product 'X' required by package 'capapp-spm' target 'CapApp-SPM' not found"。
+//     与既有 `s.name = 'AdepBridge'`（podspec）、`@objc(AdepBridge)` 一致。
+//   - `path: "ios/Sources"`：既有 Swift 源码就平铺在这（与 podspec 的 `source_files` glob 同一目录），
+//     避免为 SPM 搬目录而牵动 podspec 与 capacitor.plugin.json。
+//
+// 版本与平台下限**两形态必须一致**（本仓判据见 `packages/cli/src/__tests__/adep-bridge-spm.test.ts`）：
+//   - `platforms: [.iOS(.v14)]` ↔ podspec 的 `s.ios.deployment_target = '14.0'`。
+//     Capacitor 7 官方迁移要求把 iOS 下限从 13 抬到 14；两端不一致 = 同一插件对同一消费方给出不同平台约束。
+//   - `capacitor-swift-pm` 用 `from: "7.0.0"`（区间）：app 侧按自己装的 `@capacitor/ios` 钉 exact 版本，
+//     这里给区间让 SPM 能同时解析两者；写 `branch:` / `exact:` 会与 app 侧冲突。
+//     与 podspec 的 `s.dependency 'Capacitor'`（无版本约束）对应——语义都是「跟随消费方的 Capacitor 版本」。
+//   - `Capacitor` **与** `Cordova` 两个 product 都要声明：只写 `Capacitor` 会报
+//     `fatal error: module 'Cordova' not found`（Capacitor.framework 的头文件里 `@_exported import Cordova`）。
+import PackageDescription
+
+let package = Package(
+    name: "AdepBridge",
+    platforms: [.iOS(.v14)],
+    products: [
+        .library(name: "AdepBridge", targets: ["AdepBridge"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "7.0.0"),
+        // APP-025：SQLCipher 加密（binary xcframework，GitHub Releases 分发 ⇒ 构建期需网络；
+        // checksum 39f02d2f… 由 SQLCipher.swift 的 Package.swift 钉死，SPM 自动校验完整性）。
+        .package(url: "https://github.com/sqlcipher/SQLCipher.swift.git", from: "4.19.0")
+    ],
+    targets: [
+        .target(
+            name: "AdepBridge",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm"),
+                .product(name: "SQLCipher", package: "SQLCipher.swift"),
+            ],
+            path: "ios/Sources"
+        )
+    ]
+)

package/templates/app-mobile/plugins/adep-bridge/android/build.gradle

@@ -1,15 +1,37 @@
+// APP-044：capacitor 7 的 android 核心是纯 Java，生成的原生工程（root build.gradle / app 模块）
+// 没有任何 Kotlin 工具链——本模块的 .kt 源若无下面的 buildscript + kotlin-android，会被 AGP
+// **静默忽略**（不报错、出一个空 aar，装机后表现为「原生桥不可用：AdepBridge 未注册」）。
+// Kotlin 版本与 @capacitor/android 自身的 kotlin-bom 档对齐（1.9.25）。
+buildscript {
+    ext.kotlin_version = '1.9.25'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
 apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
 
 android {
     namespace "com.adep.bridge"
-    compileSdk 34
+    compileSdk 35
     defaultConfig {
-        minSdk 22
+        // APP-026：SQLCipher for Android 官方下限 API 23（上游 README Compatibility），
+        // minSdk 从 22 抬到 23。
+        minSdk 23
     }
     compileOptions {
         sourceCompatibility JavaVersion.VERSION_17
         targetCompatibility JavaVersion.VERSION_17
     }
+    // kotlin-android 缺省按宿主 JDK（21）出字节码，与上面 Java 17 撞「Inconsistent JVM-target」。
+    kotlinOptions {
+        jvmTarget = '17'
+    }
 }
 
 repositories {
@@ -18,5 +40,14 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.getcapacitor:android:7.0.0'
+    // capacitor 不把 android 库发布到 Maven（只在 npm 里、以子工程形态被 include）：
+    // 依赖必须引本地工程 ':capacitor-android'（compileOnly——运行时副本由 app 模块带，
+    // 不重复打包）。写 maven 坐标 com.getcapacitor:android 在任何机器上都解析不到（APP-044）。
+    compileOnly project(':capacitor-android')
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+    // APP-026：设备本地 SQLite 落盘即密文（与 iOS APP-025 的 SQLCipher 同语义）。
+    // sqlcipher-android 4.x 支持 API 23+；minSdk 22 的壳要抬到 23（SQLCipher 官方下限）。
+    implementation 'net.zetetic:sqlcipher-android:4.6.1@aar'
+    // sqlcipher-android 的 SupportSQLiteOpenHelper 接口来自 androidx.sqlite（上游 README 依赖声明）。
+    implementation 'androidx.sqlite:sqlite:2.4.0'
 }

package/templates/app-mobile/plugins/adep-bridge/android/src/main/AndroidManifest.xml

@@ -1,9 +1,16 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!--
-  AdepBridge 插件（library 模块）**不声明任何系统权限**（uses-permission 留空）。
+  AdepBridge 插件（library 模块）**不声明任何运行时权限**（相机 / 定位 / 通知等全部留空）。
+
   门控语义（PRD §2.11.5）：未在应用 manifest 的 permissions 声明的能力即不可用，
-  且不得在运行时申请——插件本体不主动索取任何系统权限；应用声明了哪些权限，
-  由壳工程在 cap add 生成的应用级 AndroidManifest.xml 里配相应 uses-permission
-  （README 有映射指引）。
+  且不得在运行时申请——插件本体不主动索取任何需要用户同意的权限；应用声明了哪些权限，
+  由壳工程在 cap add 生成的应用级 AndroidManifest.xml 里配相应 uses-permission（README 有映射指引）。
+
+  唯一例外是 INTERNET（APP-027）：它是**安装期权限**（无弹窗、无运行时申请），
+  而首启 ownerKey 签发（`AdepIdentityBootstrap` → POST /api/v1/projects/<slug>/app-installations）
+  依赖它。不在此显式声明就等于把「能不能发请求」押在宿主 app 的 manifest 上——
+  缺了它症状是每次启动都 `IDENTITY_REQUEST_FAILED`（看起来像「服务端没部署」）。
 -->
-<manifest xmlns:android="http://schemas.android.com/apk/res/android" />
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+</manifest>