@adep/cli 0.4.4 → 0.4.6

package/templates/app-desktop/main.mjs

@@ -5,7 +5,12 @@
  * 1. 注册自定义 scheme `adep-app://`——`file://` 直接加载 ESM bundle 会被 CORS 拦
  *    （`file://` origin 为 null，ES module 跨源请求一律被拒），必须走自定义协议；
  * 2. `adep-app://bundle/<path>` 从工程内 `app/site/` 提供静态产物（带 MIME 与 SPA 回退）；
- * 3. 创建 BrowserWindow，经 additionalArguments 把 adep.app.json 配置传给沙箱 preload。
+ * 3. `adep-app://bundle/api/*` 经主进程代理到平台（`/api/v1/*` 主域 / 其余项目子域）——
+ *    页面相对路径的函数调用落在本协议上，不经代理就是被 SPA 回退吞掉；主进程转发
+ *    也不受渲染进程 CORS 约束（2026-10-27 实测：不代理则在线运行时云端全断）；
+ * 4. 创建 BrowserWindow，经 additionalArguments 把 adep.app.json 配置传给沙箱 preload；
+ * 5. （APP-033）首屏之后在后台做设备身份自举 → 挂同步：签发失败只留日志与状态文件，
+ *    绝不影响本地可用性（详见 `identity.mjs` 的三条边界）。
  *
  * 页面侧经 preload 注入的 `__ADEP_APP__` 拿到 platformUrl 后，用 `@adep/client`
  * 绝对地址 invoke 云函数（在线运行时，函数逻辑迭代不需要重新发版）。
@@ -14,11 +19,18 @@
  * 直写，比 .then() 链少一层回调；启动失败即响亮崩溃（unhandled rejection）。
  */
 import { readFileSync } from 'node:fs'
+import http from 'node:http'
+import https from 'node:https'
 import { dirname, join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import { app, ipcMain, net, protocol } from 'electron'
+import { pipeline, Readable } from 'node:stream'
+import { app, clipboard, dialog, ipcMain, Menu, net, protocol } from 'electron'
 import { createWindow } from './window.mjs'
 import { createOfflineRuntime, hasOfflineBundle } from './offline-runtime.mjs'
+import { IdentityBootstrap, createFetchTransport, platformForHost } from './identity.mjs'
+import { createProtectedStore, writeIdentityStatus } from './identity-store.mjs'
+import { createRecoveryActions } from './recovery-ui.mjs'
+import { createSyncLoop } from './sync-loop.mjs'
 
 const APP_SCHEME = 'adep-app'
 const SITE_DIR = 'app/site'
@@ -59,6 +71,108 @@ protocol.registerSchemesAsPrivileged([
 await app.whenReady()
 const config = loadAppConfig()
 
+// ── 在线云函数 / 平台 API 代理（PRD §2.11 路径 A 的最后一环）──
+//
+// 页面以相对路径 fetch('/api/...') 时，相对解析落在 adep-app://bundle/api/...——协议处理器
+// 必须把这类请求代理到平台，否则会被 SPA 回退吞成 index.html，页面拿不到 JSON 只能进
+// 「云端不可达」的本机模式。而经渲染进程直接打 platformUrl 绝对地址也不行：跨源 + 平台
+// 函数路由面无 CORS 头，浏览器层直接拒收响应（2026-10-27 countdown 导出包实测，两端全断）。
+//
+// 所以在主进程代理（node:http 的 connect 目标与 Host 头是分离的）：
+// - `/api/v1/*` → 平台自有 API，Host 用主域；
+// - 其余 `/api/*` → 项目云函数，Host 用 `<slug>.<platformHost>`（网关按 Host 路由用户函数，
+//   主域不路由）。连接恒打 platformUrl 的地址——Windows 不解析 `*.localhost` 通配
+//   （AGENTS §9 e2e ENOTFOUND 家族），直连子域会 DNS 失败。
+// 主进程发请求不受渲染进程 CORS 约束，平台无需为壳 origin 开任何 CORS 面。
+const PLATFORM_URL = new URL(config.platformUrl)
+const PLATFORM_IS_HTTPS = PLATFORM_URL.protocol === 'https:'
+const PLATFORM_TRANSPORT = PLATFORM_IS_HTTPS ? https : http
+const PLATFORM_PORT = PLATFORM_URL.port || (PLATFORM_IS_HTTPS ? '443' : '80')
+const PLATFORM_HOST_HEADER = PLATFORM_URL.host
+// 子域形态只在「平台主机是域名」时成立（`<slug>.<host>`）；platformUrl 是 IP 字面量时
+// 拼出 `countdown.127.0.0.1` 这类坏 Host，被 better-auth 的 allowedHosts 直接 403
+//（2026-10-27 实测）。本地开发规范域是 `localhost:<port>`（.env 五键铁律的 PLATFORM_DOMAIN
+// 口径），此时回退 `<slug>.localhost:<port>`——只改 Host 头，连接仍打原地址，无需解析。
+const PLATFORM_HOSTNAME_IS_IP =
+  /^[\d.]+$/.test(PLATFORM_URL.hostname) || PLATFORM_URL.hostname.includes(':')
+const FUNCTIONS_HOST_HEADER = PLATFORM_HOSTNAME_IS_IP
+  ? `${config.projectSlug}.localhost${PLATFORM_URL.port ? `:${PLATFORM_URL.port}` : ''}`
+  : `${config.projectSlug}.${PLATFORM_URL.host}`
+
+/**
+ * 把 adep-app://bundle/api/* 请求经主进程转发到平台。
+ *
+ * @param {Request} request 协议处理器收到的原始请求（method / headers / body 原样透传）
+ * @param {string} hostHeader 上游 Host 头（主域 = 平台 API；子域 = 项目云函数）
+ * @returns {Promise<Response>} 上游响应（status / headers / body 流式回传）
+ */
+function proxyToPlatform(request, hostHeader) {
+  const upstreamHeaders = {}
+  request.headers.forEach((value, key) => {
+    // Host 由我们钉（决定网关路由）；连接级逐跳头不透传（node:http 会自己管）。
+    if (key === 'host' || key === 'connection' || key === 'content-length') return
+    upstreamHeaders[key] = value
+  })
+  upstreamHeaders.host = hostHeader
+  const { pathname, search } = new URL(request.url)
+  return new Promise((resolveProxy) => {
+    // 恰好 resolve 一次：上游响应 / 中途错误 / 管道破裂三条路径都可能到达，
+    // 悬而未决的 Promise 会把页面 fetch 挂死（无超时、无报错）。
+    let settled = false
+    const settle = (response) => {
+      if (settled) return
+      settled = true
+      resolveProxy(response)
+    }
+    const upstream = PLATFORM_TRANSPORT.request(
+      {
+        host: PLATFORM_URL.hostname,
+        port: PLATFORM_PORT,
+        path: `${pathname}${search}`,
+        method: request.method,
+        headers: upstreamHeaders,
+      },
+      (res) => {
+        const headers = new Headers()
+        for (const [key, value] of Object.entries(res.headers)) {
+          if (value === undefined) continue
+          for (const item of Array.isArray(value) ? value : [value]) headers.append(key, item)
+        }
+        settle(
+          new Response(Readable.toWeb(res), {
+            status: res.statusCode ?? 502,
+            headers,
+          })
+        )
+      }
+    )
+    upstream.on('error', (error) => {
+      // 代理失败必须与「应用自己的 404」不同形：给 502 + 可读原因，别让页面把网络故障
+      // 当成业务响应，也别落进 SPA 回退（那会把 index.html 当 API 响应返回）。
+      settle(
+        new Response(
+          JSON.stringify({ proxyError: String(error instanceof Error ? error.message : error) }),
+          { status: 502, headers: { 'content-type': 'application/json' } }
+        )
+      )
+    })
+    if (request.body === null) {
+      upstream.end()
+      return
+    }
+    pipeline(Readable.fromWeb(request.body), upstream, (error) => {
+      if (error) {
+        settle(
+          new Response(JSON.stringify({ proxyError: String(error) }), {
+            status: 502,
+            headers: { 'content-type': 'application/json' },
+          })
+        )
+      }
+    })
+  })
+}
+
 // 流式协议处理器：adep-app://bundle/<path> → app/site/<path>。
 // 用 net.fetch(pathToFileURL(...)) 而非手拼 Response：前者自动带 Content-Type
 //（ESM 对 MIME 严格校验，手写 Response 不给 MIME 会被静默拒载）。
@@ -67,6 +181,13 @@ protocol.handle(APP_SCHEME, async (request) => {
   if (host !== 'bundle') {
     return new Response(`未知 host "${host}"`, { status: 404 })
   }
+  // /api/* 不落静态面：页面相对路径的云函数 / 平台 API 调用经主进程代理（见上方注释）。
+  if (pathname === '/api' || pathname.startsWith('/api/')) {
+    return proxyToPlatform(
+      request,
+      pathname.startsWith('/api/v1/') ? PLATFORM_HOST_HEADER : FUNCTIONS_HOST_HEADER
+    )
+  }
   const siteRoot = join(APP_ROOT, SITE_DIR)
   const relative = decodeURIComponent(pathname).replace(/^\/+/, '')
   const rootUrl = pathToFileURL(siteRoot).href
@@ -97,6 +218,101 @@ if (hasOfflineBundle()) {
 const win = await createWindow(config, { offline: offline !== null })
 await win.loadURL(`${APP_SCHEME}://bundle/index.html`)
 
+/** 身份 / 同步日志：GUI 形态下用户看不到 stdout，所以另有一份状态文件给 doctor 读。 */
+function logLine(line) {
+  console.log(line)
+}
+
+/**
+ * 受保护存储 + 恢复码动作（APP-034）。
+ *
+ * store 提到模块级：自举与恢复码读口共用同一实例（一个后端、一份降级状态）。
+ * 恢复码的呈现与导出全在主进程（应用菜单 + 原生对话框）——**不开 IPC、不改 preload**，
+ * 恢复码与 ownerKey 都不进渲染进程（APP-033 的边界不回退）。
+ */
+const identityStore = createProtectedStore({
+  root: APP_ROOT,
+  // 凭据条目的 service 串：一眼能看出属于哪个平台项目，且不含任何机密。
+  service: `adep-app:${config.projectSlug}`,
+  log: logLine,
+})
+const recoveryActions = createRecoveryActions({
+  root: APP_ROOT,
+  readRecoveryCode: () => identityStore.readRecoveryCode(),
+  appName: config.appName,
+  projectSlug: config.projectSlug,
+  deps: { dialog, clipboard, log: logLine },
+})
+
+// 应用菜单挂「凭据」子菜单（用户的设置/关于面——壳没有自己的设置页，页面是用户内容）。
+// macOS 保留系统惯例角色（appMenu / editMenu…），否则复制粘贴快捷键全失效。
+Menu.setApplicationMenu(
+  Menu.buildFromTemplate([
+    ...(process.platform === 'darwin' ? [{ role: 'appMenu' }] : []),
+    { role: 'fileMenu' },
+    { role: 'editMenu' },
+    { role: 'viewMenu' },
+    { role: 'windowMenu' },
+    { label: '凭据', submenu: recoveryActions.menuItems() },
+  ])
+)
+
+/**
+ * 设备身份自举 + 后台同步（APP-033）。
+ *
+ * **刻意排在首屏之后**（`void`，不 await）：首启要发一次真实网络请求，断网时最长要等到
+ * 超时；身份只影响同步与（未来的）库 key，不影响页面加载——为了它让用户盯着白窗口是错的。
+ * 失败必须只留日志、不改变可用性（`IdentityBootstrap.start()` 永不 throw）。
+ *
+ * 身份就绪后再 `attachSync`：本地库早就打开（离线运行时装配时），此处只挂 transport，
+ * 不重开第二个 `DatabaseSync` 句柄（两个句柄写同一个 SQLite 文件＝拿锁打架）。
+ */
+async function bootstrapDeviceIdentity() {
+  const bootstrap = new IdentityBootstrap({
+    readConfig: () => JSON.parse(readFileSync(join(APP_ROOT, 'adep.app.json'), 'utf8')),
+    // 与恢复码动作共用同一份受保护存储（见文件上方 APP-034 注释）。
+    store: identityStore,
+    transport: createFetchTransport(10_000),
+    // 宿主 OS → 服务端 APP_PLATFORMS（没有 `desktop` 这个取值，见 identity.mjs 注释）。
+    platform: platformForHost(process.platform),
+    log: logLine,
+    // 读数面：桌面壳是 GUI，stdout 用户看不到 ⇒ 状态另落一份给 `adep app doctor` 读。
+    recordStatus: (record) => writeIdentityStatus(APP_ROOT, record),
+  })
+
+  const outcome = await bootstrap.start()
+  if (outcome.status === 'failed') {
+    logLine(
+      `[adep-app] 身份未就绪（${outcome.code}）：${outcome.detail ?? ''}——` +
+        '应用照常可用，下次启动重试；排查用 adep app doctor'
+    )
+    return
+  }
+
+  // 恢复码首次呈现（APP-034）：码可读且没呈现过 ⇒ 弹一次。刻意不绑「本次刚签发」——
+  // 老安装升级上来时用户同样一次没见过码；已呈现过 ⇒ 幂等空操作。失败只留日志。
+  void recoveryActions.showOnceIfNeeded().catch((error) => {
+    logLine(`[adep-app] 恢复码呈现失败（不影响其他功能）：${error?.message ?? error}`)
+  })
+
+  if (offline === null) {
+    // 在线形态没有本地库，同步没有载体（不是错误：在线运行时函数本来就在服务端跑）。
+    logLine('[adep-app] 在线形态：不做本地同步')
+    return
+  }
+
+  const sync = offline.attachSync({ ownerKey: outcome.ownerKey })
+  const loop = createSyncLoop({ sync, log: logLine })
+  loop.start()
+  // 退出前停循环：定时器在 quit 之后还会 fire，那时 sqlite 句柄可能已关。
+  app.on('before-quit', () => loop.stop())
+}
+
+void bootstrapDeviceIdentity().catch((error) => {
+  // 兜底：这里的任何异常都只该是「同步没起来」，绝不能让未处理的 rejection 崩主进程。
+  console.error('[adep-app] 身份自举异常（不影响本地可用性）：', error)
+})
+
 app.on('activate', () => {
   // macOS：点 Dock 图标且无窗口时重建（Electron 官方生命周期约定）。
   if (app.getAllWindows().length === 0) void createWindow(config)

package/templates/app-desktop/offline-runtime.mjs

@@ -8,7 +8,7 @@
  *   → 造 DeviceBridge（node:sqlite + 只读文件桥 + 空 env——离线包永不下发 secret）
  *   → executor.createLocalExecutor（白名单路由：offline:true 本地执行，false 返回
  *     FN_OFFLINE_ONLY 且提示在线调用方式）
- *   → 返回 { executor, manifest, sqlite, version } 供主进程 ipc 面使用。
+ *   → 返回 { executor, manifest, sqlite, version }（给 ownerKey 时另带 sync）供主进程 ipc 面使用。
  *
  * 壳工程是**独立 npm 工程**（装不了私有 workspace 包），运行时随包分发是本模板对
  * 「接 @adep/app-runtime」的唯一可行落地；e2e 黄金测试（e2e/cli/app-offline.spec.ts）
@@ -47,8 +47,12 @@ function readFunctionSource(name) {
 /**
  * 装配离线运行时：装载 executor（data URL 动态 import，引擎无关标准 ESM 语义）、
  * 初始化本地库、造桥。任何一步失败即 throw（壳启动即响亮崩溃，不留半离线坏状态）。
+ *
+ * `options.ownerKey`（APP-032）：设备身份。给了就**额外**装配同步 transport
+ * （`push` / `pull`），用的是随包分发的同一份设备端代码（bundle 导出 `createSyncTransport`），
+ * 与 `adep app sync` 逐字同源。不给就不装——同步没有身份就没有分母，**不**做匿名上行。
  */
-export async function createOfflineRuntime() {
+export async function createOfflineRuntime(options = {}) {
   if (!hasOfflineBundle()) {
     throw new Error('[adep-app] 未检测到离线产物 app/offline/manifest.json：请先执行 adep app build --offline')
   }
@@ -125,5 +129,70 @@ export async function createOfflineRuntime() {
   const local = executorModule.createLocalExecutor({ functions, bridge, env })
   const version = readFileSync(join(OFFLINE_DIR, 'runtime', 'version.txt'), 'utf8').trim()
 
-  return { executor: local, manifest, sqlite, version }
+  // 同步（APP-032/APP-033）：设备端 transport 是**随包分发的那一份**，不是这里另写一套。
+  //
+  // 装配入口拆成 `attachSync({ ownerKey })` 而不是只在构造参数里给：桌面壳的身份是**异步**
+  // 自举的（首启要发一次网络请求，APP-033）——窗口先出来、身份后到，此时运行时与本地库
+  // 早就打开了。若只保留「构造时传 ownerKey」，主进程要么阻塞首屏等签名，要么重新打开
+  // 一次库（第二个 DatabaseSync 句柄同时写一个文件＝拿锁打架）。
+  const createSync = (syncOwnerKey, fetchOverride) => {
+    if (typeof executorModule.createSyncTransport !== 'function') {
+      throw new Error(
+        '[adep-app] 包内运行时不含同步 transport（runtime/executor.mjs 是旧版本）：请重跑 adep app build --offline'
+      )
+    }
+    // 同步目标取壳配置（与页面 / 主进程同一份 adep.app.json），不另立一份环境变量。
+    const appConfig = JSON.parse(readFileSync(join(APP_ROOT, 'adep.app.json'), 'utf8'))
+    if (typeof appConfig.platformUrl !== 'string' || typeof appConfig.projectSlug !== 'string') {
+      throw new Error('[adep-app] adep.app.json 缺 platformUrl / projectSlug：同步端点路径拼不出来')
+    }
+    const driver = executorModule.createDeviceSqliteDriver(sqliteBridge)
+    return executorModule.createSyncTransport({
+      driver,
+      ownerKey: syncOwnerKey,
+      baseUrl: appConfig.platformUrl,
+      projectSlug: appConfig.projectSlug,
+      // 渲染进程有 window.fetch，主进程 / Node 22 有全局 fetch：两者都满足同一注入面。
+      fetch: fetchOverride ?? options.fetch ?? ((url, init) => fetch(url, init)),
+    })
+  }
+
+  /**
+   * 身份就绪后再挂同步（APP-033）。`ownerKey` 为空即**不挂**（不做匿名上行）。
+   *
+   * 重复调用返回同一个实例：主进程可能同时被「自举完成」和「窗口重建」两条路径调到。
+   */
+  let attachedSync
+  const attachSync = ({ ownerKey, fetch: overrideFetch } = {}) => {
+    const key = ownerKey === undefined || ownerKey === '' ? options.ownerKey : ownerKey
+    if (key === undefined || key === '') {
+      throw new Error('[adep-app] attachSync 需要设备身份 ownerKey（无身份不做匿名同步）')
+    }
+    if (attachedSync !== undefined) return attachedSync
+    attachedSync = createSync(key, overrideFetch)
+    return attachedSync
+  }
+
+  const sync =
+    options.ownerKey === undefined || options.ownerKey === ''
+      ? undefined
+      : createSync(options.ownerKey)
+
+  const close = () => {
+    // DatabaseSync.close() 释放文件句柄；Windows 上不显式 close 时文件锁靠 GC 终结器
+    // 释放，与 afterAll/退出时的 rm/卸载赛跑（e2e 实测 EBUSY，POSIX 因锁语义宽松恒绿）。
+    if (sqlite !== undefined) {
+      sqlite.close()
+    }
+  }
+
+  return {
+    executor: local,
+    manifest,
+    sqlite,
+    version,
+    attachSync,
+    close,
+    ...(sync === undefined ? {} : { sync }),
+  }
 }

package/templates/app-desktop/package.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "description": "{{appName}} —— AgentDeploy 桌面应用（Electron 壳，在线 + 离线运行时）",
-  "main": "main.mjs",
+  "main": "main.cjs",
   "scripts": {
     "start": "electron .",
     "dist": "electron-builder"
@@ -20,13 +20,15 @@
       "output": "dist"
     },
     "files": [
-      "main.mjs",
-      "window.mjs",
+      "*.mjs",
+      "*.cjs",
       "preload.cjs",
       "adep.app.json",
       "app/site/**/*",
       "app/offline/**/*",
-      "data/**/*"
+      "data/**/*",
+      "!data/identity/**",
+      "!data/*.sqlite*"
     ],
     "mac": {
       "target": [
@@ -36,12 +38,14 @@
     },
     "win": {
       "target": [
-        "nsis"
+        "nsis",
+        "zip"
       ]
     },
     "linux": {
       "target": [
-        "AppImage"
+        "AppImage",
+        "deb"
       ],
       "category": "Utility"
     }