@adep/cli 0.4.4 → 0.4.6

package/templates/app-desktop/identity.mjs

@@ -0,0 +1,517 @@
+/**
+ * 桌面壳设备身份自举（APP-033；PRD §2.11.5「设备身份与恢复」/ ADR-0008 第 2 条）。
+ *
+ * ## 这一层解决什么问题
+ *
+ * `ownerKey` 必须由**服务端**签发（本地自造 / 构建期预置都判违规）。移动壳在 APP-027
+ * 已经有完整自举（原生侧首启签发 → Keychain / Keystore），而桌面壳**一次都没调过签发端点**：
+ * `main.mjs` 不读不存、`preload.cjs` 也不注入。后果是 APP-032 的同步 transport 只能在开发机
+ * 上靠 `adep app sync --owner-key` 手传——装机到用户机器上「功能齐了，钥匙没有」。
+ *
+ * ## 三条刻意的边界（与移动壳同一条口径）
+ *
+ * 1. **不做在页面侧**：`preload.cjs` 不暴露 ownerKey，页面拿不到这枚 bearer 凭据。
+ *    同步跑在主进程（transport 在 `offline-runtime.mjs` 里装配），页面不需要它；
+ *    反之，把凭据交给渲染进程等于「页面里任何一个 XSS 都能劫持该设备的数据分区」。
+ *    身份**状态**（backend / 是否已签发）由 `adep app doctor` 读 `data/identity/status.json`
+ *    呈现——那是既有的体检读数面，不新开一条 IPC 通道。
+ * 2. **失败不改变可用性**：断网 / 5xx / 响应形态不符 ⇒ 不写空值、不覆盖既有值，只留带
+ *    **原因码**的日志与状态文件，下次启动重试。首启失败不得阻止 app 启动。
+ * 3. **幂等**：本地已有合法 ownerKey ⇒ 不发请求（一枚安装只签发一次）。
+ *
+ * ## 为什么这个文件不 import electron
+ *
+ * 判定（配置 / URL / 形态 / 响应解析 / 平台映射）与副作用（存储、传输、日志）全部拆开，
+ * 判定层是纯函数 ⇒ `app-desktop-identity.test.ts` 能把**被测源码原样** import 进来真跑，
+ * 不做镜像实现（APP-027 用 swiftc/kotlinc 编原文件，这里是同一思路的 Node 版）。
+ * `main.mjs` 才是唯一碰 electron 的地方。
+ */
+
+/**
+ * 自举配置（`adep.app.json` 的投影；完整校验归 CLI 侧，这里只取两个字段）。
+ *
+ * @typedef {Object} adepIdentityConfig
+ * @property {string} platformUrl 平台地址（http(s) 绝对地址）
+ * @property {string} projectSlug 项目 slug（会拼进签发端点路径）
+ */
+
+/**
+ * 签发响应的投影（三个字段都通过形态校验后才存在这个类型里）。
+ *
+ * @typedef {Object} adepIssueResult
+ * @property {string} ownerKey 设备凭据（`adep_ok_` + 64 位小写 hex）
+ * @property {string} installationId 安装行主键
+ * @property {string} recoveryCode 一次性恢复码（明文只在签发响应里出现一次）
+ */
+
+/**
+ * 自举依赖（全部注入：存储 / 配置 / 传输 / 日志 / 状态落盘）。
+ *
+ * @typedef {Object} adepBootstrapDependencies
+ * @property {() => unknown} readConfig 读壳根 adep.app.json（返回 JSON.parse 结果）
+ * @property {adepProtectedStore} store 受保护存储
+ * @property {(url: string, body: string, timeoutMs: number) => Promise<{status: number, body: string | null, error: string | null}>} transport 签发传输
+ * @property {string} platform 服务端平台枚举值（APP_PLATFORMS 之一，没有 desktop）
+ * @property {number} [timeoutMs] 签发请求超时（缺省 10s）
+ * @property {(line: string) => void} [log] 日志（每条带原因码）
+ * @property {(status: Record<string, unknown>) => void | Promise<void>} [recordStatus] 状态落盘（非机密读数面）
+ */
+
+/**
+ * 受保护存储面（identity-store.mjs 的返回形态；测试用假实现同样满足）。
+ *
+ * @typedef {Object} adepProtectedStore
+ * @property {string} backend 实际生效的后端（退化后是 file）
+ * @property {() => Promise<string|null>} readOwnerKey
+ * @property {(value: string) => Promise<void>} writeOwnerKey
+ * @property {() => Promise<string|null>} readRecoveryCode
+ * @property {(value: string) => Promise<void>} writeRecoveryCode
+ */
+
+/** 自举结果码。日志与状态文件里必须出现码本身（排障时先看码，再看文案）。 */
+export const ADEP_IDENTITY_CODES = {
+  /** 壳根没有 `adep.app.json`（未 init 或文件被删）。 */
+  configMissing: 'IDENTITY_CONFIG_MISSING',
+  /** 配置在但字段非法（platformUrl 不是 http(s) / projectSlug 形态不符）。 */
+  configInvalid: 'IDENTITY_CONFIG_INVALID',
+  /** 传输层失败或非 2xx（断网 / 超时 / 5xx / 429）。 */
+  requestFailed: 'IDENTITY_REQUEST_FAILED',
+  /** 2xx 但响应形态不符（不是 JSON / 缺 installation / ownerKey 形态不对）。 */
+  responseInvalid: 'IDENTITY_RESPONSE_INVALID',
+  /** 拿到合法凭据但落受保护存储失败（含写后读回不一致）。 */
+  storeFailed: 'IDENTITY_STORE_FAILED',
+  /** 已签发（跳过，未发请求）。 */
+  alreadyIssued: 'IDENTITY_ALREADY_ISSUED',
+  /** 同一实例重复 start（跳过，未发请求）。 */
+  alreadyStarted: 'IDENTITY_ALREADY_STARTED',
+}
+
+/** ownerKey 明文前缀（与 `server/domains/appbuild/identity/contract.ts` 的 `OWNER_KEY_PREFIX` 逐字对应）。 */
+export const OWNER_KEY_PREFIX = 'adep_ok_'
+/** ownerKey 随机段 hex 长度（服务端 `OWNER_KEY_BYTES = 32` ⇒ 64 位 hex，256 位熵）。 */
+export const OWNER_KEY_HEX_LENGTH = 64
+/**
+ * 签发端点路径（服务端 `sync-routes.ts` 的 `/v1/projects/:projectId/app-installations`，
+ * 平台侧挂在 `/api` 前缀下；`:projectId` 接受 **id 或 slug**）。
+ */
+export const ISSUE_PATH_PREFIX = '/api/v1/projects/'
+export const ISSUE_PATH_SUFFIX = '/app-installations'
+
+/**
+ * 宿主 OS → 服务端 `APP_PLATFORMS`（`server/domains/appbuild/manifest/schema.ts`）。
+ *
+ * ⚠️ 这里**没有** `desktop` 这个取值——APP-032 的 e2e 就栽在照抄 CLI 的
+ * `--platform desktop|mobile` 上（那是「哪种壳」，不是「哪个系统」），签发端直接
+ * `400 APP_INSTALL_INPUT_INVALID`。两套枚举同名不同域，别互相代入。
+ */
+const HOST_PLATFORM = { darwin: 'macos', win32: 'windows' }
+
+/**
+ * 宿主 OS → 服务端平台枚举。
+ *
+ * @param {string} hostPlatform `process.platform` 的取值
+ * @returns {'macos'|'windows'|'linux'}
+ */
+export function platformForHost(hostPlatform) {
+  return HOST_PLATFORM[hostPlatform] ?? 'linux'
+}
+
+/**
+ * ownerKey 形态：前缀 + 64 位**小写** hex（与服务端正则完全同形）。
+ *
+ * 刻意严格（不宽松地接受大写）：宽松会让「服务端换了编码」这类契约漂移在客户端静默通过，
+ * 然后在同步侧 401——错误在最远的地方爆。
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isOwnerKey(value) {
+  if (typeof value !== 'string' || !value.startsWith(OWNER_KEY_PREFIX)) return false
+  const hex = value.slice(OWNER_KEY_PREFIX.length)
+  if (hex.length !== OWNER_KEY_HEX_LENGTH) return false
+  return /^[0-9a-f]+$/.test(hex)
+}
+
+/**
+ * projectSlug 形态（与 `adep.app.json` schema 的 `^[a-z][a-z0-9-]{0,62}$` 同形）。
+ *
+ * 在客户端再判一次的理由：拼 URL 时 slug 会成为**路径段**，形态失守就是拼出一个别的端点。
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isProjectSlug(value) {
+  return typeof value === 'string' && /^[a-z][a-z0-9-]{0,62}$/.test(value)
+}
+
+/** 身份层错误（带原因码；`message` 会被写进日志与状态文件，必须能直接排障）。 */
+export class IdentityError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   */
+  constructor(code, message) {
+    super(message)
+    this.name = 'IdentityError'
+    this.code = code
+  }
+}
+
+/**
+ * 解析壳根 `adep.app.json` 字节里的自举配置。
+ *
+ * 只取自举需要的两个字段，其余不校验：壳配置的完整校验在 CLI 侧 `app-config.ts`，
+ * 客户端再抄一份 schema 只会漂移。
+ *
+ * @param {unknown} raw 已经 JSON.parse 过的对象
+ * @returns {adepIdentityConfig} 自举所需的最小字段集
+ */
+export function parseIdentityConfig(raw) {
+  if (raw === null || typeof raw !== 'object') {
+    throw new IdentityError(ADEP_IDENTITY_CODES.configInvalid, 'adep.app.json 不是 JSON 对象')
+  }
+  const platformUrl = /** @type {Record<string, unknown>} */ (raw).platformUrl
+  if (typeof platformUrl !== 'string') {
+    throw new IdentityError(ADEP_IDENTITY_CODES.configInvalid, 'adep.app.json 缺 platformUrl')
+  }
+  /** @type {URL} */
+  let url
+  try {
+    url = new URL(platformUrl)
+  } catch {
+    throw new IdentityError(
+      ADEP_IDENTITY_CODES.configInvalid,
+      `platformUrl 不是合法 URL：${platformUrl}`
+    )
+  }
+  if ((url.protocol !== 'http:' && url.protocol !== 'https:') || url.hostname === '') {
+    throw new IdentityError(
+      ADEP_IDENTITY_CODES.configInvalid,
+      `platformUrl 必须是 http(s) 绝对地址：${platformUrl}`
+    )
+  }
+  const projectSlug = /** @type {Record<string, unknown>} */ (raw).projectSlug
+  if (!isProjectSlug(projectSlug)) {
+    throw new IdentityError(
+      ADEP_IDENTITY_CODES.configInvalid,
+      `projectSlug 形态不符（需小写字母开头，仅小写字母/数字/连字符）：${String(projectSlug)}`
+    )
+  }
+  return { platformUrl, projectSlug }
+}
+
+/**
+ * 组装签发端点 URL。`platformUrl` 常带尾斜杠（`https://adep.top/`）⇒ 先归一，
+ * 否则拼出 `//api/v1/...`（服务端 404，症状像「端点没部署」）。
+ *
+ * @param {adepIdentityConfig} config
+ * @returns {string}
+ */
+export function issueUrl(config) {
+  const url = new URL(config.platformUrl)
+  let base = url.pathname
+  while (base.endsWith('/')) base = base.slice(0, -1)
+  url.pathname = `${base}${ISSUE_PATH_PREFIX}${config.projectSlug}${ISSUE_PATH_SUFFIX}`
+  // 平台地址上的 query / fragment 对端点无意义，带上只会污染请求。
+  url.search = ''
+  url.hash = ''
+  return url.toString()
+}
+
+/**
+ * 解析签发响应：`{ installation: { installationId, ownerKey, recoveryCode, partition, platform } }`。
+ *
+ * **形态不符一律抛**（不写「尽量取到的那部分」）：ownerKey 是 bearer 凭据，把一个空串 /
+ * 半截值写进受保护存储，等于把「设备身份」变成「永远 401」的垃圾状态，而且**看起来像已签发**
+ * （下次启动不再重试）——比直接失败难查得多。
+ *
+ * @param {unknown} raw 已经 JSON.parse 过的响应体
+ * @returns {adepIssueResult} 三个字段都已通过形态校验
+ */
+export function parseIssueResponse(raw) {
+  const invalid = (/** @type {string} */ message) =>
+    new IdentityError(ADEP_IDENTITY_CODES.responseInvalid, message)
+  if (raw === null || typeof raw !== 'object') throw invalid('签发响应不是 JSON 对象')
+  const installation = /** @type {Record<string, unknown>} */ (raw).installation
+  if (installation === null || typeof installation !== 'object') {
+    throw invalid('签发响应缺 installation 对象')
+  }
+  const fields = /** @type {Record<string, unknown>} */ (installation)
+  if (!isOwnerKey(fields.ownerKey)) {
+    throw invalid(
+      `installation.ownerKey 形态不符（期望 ${OWNER_KEY_PREFIX} + ${OWNER_KEY_HEX_LENGTH} 位小写 hex）`
+    )
+  }
+  const installationId = fields.installationId
+  if (typeof installationId !== 'string' || installationId === '') {
+    throw invalid('installation.installationId 缺失或为空')
+  }
+  const recoveryCode = fields.recoveryCode
+  if (typeof recoveryCode !== 'string' || recoveryCode === '') {
+    throw invalid('installation.recoveryCode 缺失或为空')
+  }
+  return { ownerKey: fields.ownerKey, installationId, recoveryCode }
+}
+
+/**
+ * 恢复码脱敏（日志用）。恢复码形态 `<installationId>.<secret>`：**installationId 不是机密**
+ * （它就是安装行主键），secret 段才是凭据 ⇒ 保留 installationId + secret 前 4 位 + 总长度
+ * （长度能看出「码被截断」这类畸形）。
+ *
+ * @param {string} value
+ * @param {string} installationId
+ * @returns {string}
+ */
+export function maskRecoveryCode(value, installationId) {
+  const head = installationId === '' ? '' : `${installationId}.`
+  const secret = value.startsWith(head) ? value.slice(head.length) : value
+  return `${head}${secret.slice(0, 4)}…(len ${value.length})`
+}
+
+/**
+ * 生产传输：`fetch` + `AbortSignal.timeout`。
+ *
+ * 返回形态与注入面一致（`status === 0` 表示**没拿到 HTTP 响应**），这样失败分支在测试里
+ * 能被同一组断言覆盖，不必分辨「真网络」与「假传输」。
+ *
+ * @param {number} timeoutMs
+ * @returns {(url: string, body: string, timeoutMs: number) => Promise<{ status: number, body: string | null, error: string | null }>}
+ */
+export function createFetchTransport(timeoutMs) {
+  return async (url, body) => {
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+        body,
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+      return { status: response.status, body: await response.text(), error: null }
+    } catch (error) {
+      return {
+        status: 0,
+        body: null,
+        error: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+}
+
+/**
+ * 首启自举：查本地 →（缺则）签发 → 落受保护存储 → 通知调用方。
+ *
+ * 依赖全部注入（存储 / 配置 / 传输 / 日志 / 状态落盘）——「要不要请求」「写不写」「写什么」
+ * 三条判定都能真跑，而不是靠读源码猜。
+ *
+ * 顺序即不变量：**本地有 ownerKey ⇒ 本地必有与它同源的恢复码**。所以先写恢复码并读回校验，
+ * 再写 ownerKey。反过来会出现「app 已带着这枚身份跑，用户却永远拿不到恢复码」——明文只在
+ * 这一次响应里存在（服务端只存摘要，任何端点都不重发），丢了就是该分区永久不可认领。
+ */
+export class IdentityBootstrap {
+  /**
+   * @param {adepBootstrapDependencies} dependencies 全部注入（判定与副作用分离的关键）
+   */
+  constructor(dependencies) {
+    this.dependencies = dependencies
+    this.started = false
+  }
+
+  /**
+   * 启动一次自举。**幂等**：同一实例重复调用只发一次请求。
+   *
+   * 永不 throw——失败一律折成 `{ status: 'failed', code, detail }`，调用方（主进程）
+   * 不得因为身份没签到而阻止窗口创建。
+   *
+   * @returns {Promise<{ status: 'issued'|'skipped'|'failed', code: string, ownerKey?: string, recoveryCode?: string, backend: string, installationId?: string, detail?: string }>}
+   */
+  async start() {
+    const { log = () => {}, store } = this.dependencies
+    if (this.started) {
+      log(`[adep-identity] ${ADEP_IDENTITY_CODES.alreadyStarted}: 已启动过，忽略重复调用`)
+      return this.#skip(ADEP_IDENTITY_CODES.alreadyStarted)
+    }
+    this.started = true
+
+    // ① 已有合法 ownerKey ⇒ 一枚安装只签发一次（分母断言：这条路径下请求数必须为 0）。
+    const existing = await store.readOwnerKey()
+    if (typeof existing === 'string' && existing !== '') {
+      if (isOwnerKey(existing)) {
+        const masked = `${existing.slice(0, OWNER_KEY_PREFIX.length + 6)}…`
+        log(`[adep-identity] ${ADEP_IDENTITY_CODES.alreadyIssued}: 本地已有 ownerKey（${masked}），不重复签发`)
+        return this.#skip(ADEP_IDENTITY_CODES.alreadyIssued, existing)
+      }
+      // 形态不符（历史垃圾值 / 手写调试值）不是可用身份 ⇒ 重新签发覆盖它。
+      // 不静默当成「已签发」——那会让 app 永远带着一枚服务端不认的凭据。
+      log(`[adep-identity] 本地 ownerKey 形态不符（长度 ${existing.length}），将重新签发`)
+    }
+
+    // ② 配置（壳根 adep.app.json）。缺失与非法分开报：前者是打包问题，后者是配置写错。
+    /** @type {adepIdentityConfig} */
+    let config
+    try {
+      config = parseIdentityConfig(this.dependencies.readConfig())
+    } catch (error) {
+      return this.#fail(error)
+    }
+    let url = ''
+    try {
+      url = issueUrl(config)
+    } catch (error) {
+      return this.#fail(error)
+    }
+
+    // ③ 请求。非 2xx 与传输层失败都落 requestFailed，但 detail 区分（status 0 = 没拿到响应）。
+    const body = JSON.stringify({ platform: this.dependencies.platform })
+    const result = await this.dependencies.transport(url, body, this.dependencies.timeoutMs ?? 10_000)
+    if (result.status < 200 || result.status >= 300) {
+      const detail =
+        result.error === null
+          ? `HTTP ${result.status}（url: ${url}；响应：${(result.body ?? '').slice(0, 200)}）`
+          : `传输层失败：${result.error}（url: ${url}）`
+      return this.#fail(new IdentityError(ADEP_IDENTITY_CODES.requestFailed, detail))
+    }
+    if (result.body === null || result.body === '') {
+      return this.#fail(
+        new IdentityError(ADEP_IDENTITY_CODES.responseInvalid, `HTTP ${result.status} 但响应体为空`)
+      )
+    }
+
+    // ④ 解析 + 落库。
+    /** @type {adepIssueResult} */
+    let issue
+    try {
+      /** @type {unknown} */
+      let parsed
+      try {
+        parsed = JSON.parse(result.body)
+      } catch {
+        throw new IdentityError(ADEP_IDENTITY_CODES.responseInvalid, '签发响应不是合法 JSON')
+      }
+      issue = parseIssueResponse(parsed)
+    } catch (error) {
+      return this.#fail(error)
+    }
+
+    // ⑤ 恢复码先落库并读回校验（APP-028 的顺序）。
+    try {
+      await store.writeRecoveryCode(issue.recoveryCode)
+    } catch (error) {
+      return this.#fail(
+        new IdentityError(
+          ADEP_IDENTITY_CODES.storeFailed,
+          `恢复码写入受保护存储失败（installationId: ${issue.installationId}）：${describe(error)}——本次不落 ownerKey，下次启动重新签发`
+        )
+      )
+    }
+    // 读回校验：写接口报成功但读不出是真实故障形态（条目被策略清掉 / backend 回退写到了
+    // 另一处）。只看写返回成功会把「码已丢」当成功——正是 APP-028 要消灭的静默。
+    if ((await store.readRecoveryCode()) !== issue.recoveryCode) {
+      return this.#fail(
+        new IdentityError(
+          ADEP_IDENTITY_CODES.storeFailed,
+          `恢复码写入后读回不一致（installationId: ${issue.installationId}）——本次不落 ownerKey`
+        )
+      )
+    }
+
+    // ⑥ ownerKey 落库（写不进去也算失败：下次启动还会再签发一次，多一枚孤儿安装行）。
+    try {
+      await store.writeOwnerKey(issue.ownerKey)
+    } catch (error) {
+      return this.#fail(
+        new IdentityError(
+          ADEP_IDENTITY_CODES.storeFailed,
+          `ownerKey 写入受保护存储失败（installationId: ${issue.installationId}）：${describe(error)}`
+        )
+      )
+    }
+
+    log(
+      `[adep-identity] 签发成功（installationId: ${issue.installationId}, platform: ${this.dependencies.platform}, ` +
+        `storage: ${store.backend}, recoveryCode: ${maskRecoveryCode(issue.recoveryCode, issue.installationId)}）`
+    )
+    await this.#record({
+      state: 'issued',
+      code: 'IDENTITY_ISSUED',
+      backend: store.backend,
+      installationId: issue.installationId,
+      platform: this.dependencies.platform,
+    })
+    return {
+      status: 'issued',
+      code: 'IDENTITY_ISSUED',
+      ownerKey: issue.ownerKey,
+      recoveryCode: issue.recoveryCode,
+      backend: store.backend,
+      installationId: issue.installationId,
+    }
+  }
+
+  /**
+   * 跳过收口（未发请求）。状态文件照写：doctor 要能区分「已签发（正常）」与「还没跑过」。
+   *
+   * @param {string} code
+   * @param {string} [ownerKey]
+   */
+  async #skip(code, ownerKey) {
+    const { store } = this.dependencies
+    await this.#record({
+      state: 'issued',
+      code,
+      backend: store.backend,
+      platform: this.dependencies.platform,
+    })
+    return {
+      status: 'skipped',
+      code,
+      ...(typeof ownerKey === 'string' ? { ownerKey } : {}),
+      backend: store.backend,
+    }
+  }
+
+  /**
+   * 失败收口：日志带**原因码**（排障顺序：先看码，再看详情），状态文件同步落一份。
+   * 失败时**不写任何凭据**——只写状态（state=failed + code），下次启动据此重试。
+   *
+   * @param {unknown} error
+   */
+  async #fail(error) {
+    const { log = () => {} } = this.dependencies
+    const code = error instanceof IdentityError ? error.code : ADEP_IDENTITY_CODES.requestFailed
+    const detail = describe(error)
+    log(`[adep-identity] ${code}: ${detail}`)
+    await this.#record({ state: 'failed', code, backend: this.dependencies.store.backend, detail })
+    return {
+      status: 'failed',
+      code,
+      detail,
+      backend: this.dependencies.store.backend,
+    }
+  }
+
+  /**
+   * 状态落盘（非机密：只有 backend / 码 / installationId）。写失败不算自举失败——
+   * 状态文件是**读数面**，不是身份本身；丢一份读数不该让已经落库的凭据变成无效。
+   *
+   * @param {Record<string, unknown>} status
+   */
+  async #record(status) {
+    const record = this.dependencies.recordStatus
+    if (record === undefined) return
+    try {
+      await record({ ...status, at: new Date().toISOString() })
+    } catch (error) {
+      this.dependencies.log?.(`[adep-identity] 状态文件写入失败（不影响身份）：${describe(error)}`)
+    }
+  }
+}
+
+/**
+ * 可读错误文本（`Error` 取 message，其余 String 化）。
+ *
+ * @param {unknown} error
+ * @returns {string}
+ */
+export function describe(error) {
+  return error instanceof Error ? error.message : String(error)
+}

package/templates/app-desktop/main.cjs

@@ -0,0 +1,17 @@
+/**
+ * ESM 主进程入口的 CJS 包装（APP-036）。
+ *
+ * ## 为什么入口是 .cjs 而不是直接用 main.mjs
+ *
+ * 2026-10-23 视觉验收实测（macOS 27.0.1 / Electron 44.9.3）：ESM 主进程（`main: main.mjs`）
+ * 的 top-level `await app.whenReady()` **永不 resolve**——主线程停在 libuv 的 io poll 上、
+ * 无任何错误输出、窗口不出现（TRACE 打点钉死卡点；对照实验：同一二进制跑 CJS 入口，
+ * whenReady 47ms 即 resolve）。CJS 入口一切正常，故模板入口换成本包装，`main.mjs`
+ * 保持 ESM 语义不动（import 链 / top-level await 都不变，只是由本文件动态 import）。
+ *
+ * 失败响亮：动态 import 失败（模板缺文件 / 语法错）不能静默——打日志并置非零退出码。
+ */
+import('./main.mjs').catch((error) => {
+  console.error('[adep-app] 主进程加载失败：', error)
+  process.exitCode = 1
+})