@adep/cli 0.4.1 → 0.4.5

package/README.md

@@ -279,6 +279,7 @@ adep serve --db sqlite --db-file var/local.sqlite   # 指定库文件
 adep publish                          # 缺省全栈：函数 deploy + 前端平台侧构建托管
 adep publish --only functions         # 只发布云函数
 adep publish --only frontend          # 只发布前端（vite 工程平台侧构建；纯静态站直通托管通道）
+adep publish --only frontend --env dev   # 前端发到**开发站点**（site-dev/ + dev- 子域 + 独立版本序列）
 adep publish -p my-app                # 显式指定目标 slug
 ```
 
@@ -305,6 +306,11 @@ hello  v1  https://my-app.platform.example.com/api/hello
 
 - `--json` 输出统一信封 `{ ok, command, data: { scope, functions?, frontend? } }`。
 
+- **`--env dev` 只影响前端**：产物写 `site-dev/`、版本走独立序列（dev v1.. / prod v1..）、地址是
+  `dev-<子域>`，与线上站点完全隔离。**函数部署不受影响**——网关恒读生产库，不存在「部署一个读开发库的
+  函数」，输出里会显式说明。纯静态站（无 `scripts.build`、无待编译源码）传 `--env dev` 直接 fail loud
+  （`STATIC_DEV_UNSUPPORTED`）：该通道直传 `site/`，会覆盖线上站点。
+
 > 兼容别名：`adep deploy` / `adep functions deploy` / `adep hosting deploy` 保留原行为，
 > 仅在 stderr 打印 deprecation 提示指向本命令（见下文）。
 
@@ -318,8 +324,13 @@ hello  v1  https://my-app.platform.example.com/api/hello
 ```bash
 adep deploy                      # 项目 slug 取 adep.config.ts 的 name
 adep deploy -p my-app            # 显式指定目标 slug
+adep deploy --worker -p <id|slug>   # 按 **wrangler 项目**部署（CF-063，见下）
 ```
 
+- **`--worker` 是另一条链**：当前目录当作 wrangler 项目根，读 `wrangler.jsonc` 直传构建产物——它不是
+  「部署 adep 函数」，输入 / 产物 / 成败判据都不同（因此 `-p` 必填，缺省即 `WORKER_PROJECT_REQUIRED`）。
+  失败始终非零退出（`WORKER_DEPLOY_FAILED`）：CI 里「部署失败但退出码 0」是最坏的一种静默。
+
 - 本地 `functions/<name>.ts` 对应平台函数 `<name>`（入口文件固定为 `index.ts`）。
   目录形态 `functions/<name>/index.ts` **等价**：目录内其余文件是该函数的私有文件，随草稿整组上传
   （默认模板生成扁平形态；两种形态不可同名并存 —— 并存时命令非零退出并列出冲突路径）。
@@ -421,6 +432,10 @@ adep db start                          # 启动项目数据库（已存在则重
 adep db status                         # 查询状态与用量（体积 / 表数 / 行数）
 adep db stop                           # 停止数据库（连接关闭并标记；文件保留）
 
+# 列当前环境的表与行数；--table 看单表结构（字段 / 索引 / 建表 DDL）
+adep db tables
+adep db tables --table users
+
 # 执行单条 SQL；写 / 破坏性语句需 --confirm-table 二次确认目标表名
 adep db exec --sql "SELECT * FROM users"
 adep db exec --sql "DELETE FROM users WHERE id = 1" --confirm-table users
@@ -436,6 +451,12 @@ adep db rollback --to 2026-01-01T00:00:00.000Z
 
 `db exec` 人读模式下返回对齐文本表（结果行截断时会提示），`--json` 输出结构化结果。
 
+- **环境（`--env`）**：`exec` / `migrate` / `tables` 按全局 `--env dev|prod` 选库，优先级
+  `--env` > `ADEP_ENV` > `adep.config.ts` 的 `db_environment` > `prod`；每条命令都打印生效环境**及来源**。
+  服务端一直支持 `?environment=`，CLI 之前不传 ⇒ `exec` 恒打生产库，开发者在 dev 建的表用 CLI 一查
+  就「不存在」——同一类事故的 CLI 版。
+- `start` / `status` / `stop` 与快照类**不分环境**：它们管理的是「项目数据库」这一资源本身。
+
 ### `adep storage`
 
 云存储 / 文件存储子命令组：上传 / 下载 / 列表 / 删除。
@@ -453,6 +474,7 @@ adep storage rm avatars/a.png
 - **下载**：先列表解析出服务端生成的 URL（public 直连 / private 15 分钟签名），再取回内容——private 文件无需 CLI 自行签发签名。
 
 - 所有命令都支持 `-p <slug>` 指定项目。
+- 四个子命令都跟随全局 `--env`：dev 走 `.env-dev/` 键空间（dev 传的文件在 prod `ls` 里看不到，反之亦然），输出会标明当前环境。上传走 multipart 的 `environment` 字段，其余走 `?environment=`。
 
 ### `adep hosting`（deprecated）
 
@@ -498,6 +520,7 @@ adep export --out ./dist-export      # 指定输出目录（缺省 ./exports）
 ```bash
 adep app init -p my-app -n "我的应用"        # 生成 Electron 壳工程（缺省 ./my-app-app）
 cd my-app-app && npm install                 # 壳工程依赖（electron + electron-builder）
+adep app open                                # 启动开发预览（等价壳工程内 npm start，构建前先跑一眼）
 
 adep app build                               # 拉取已发布页面产物 → 注入 app/site/ → 出安装包
 adep app build --platform win32              # 交叉指定目标平台（缺省当前平台）
@@ -508,6 +531,16 @@ adep app build --prepare-only                # 只拉产物 + 注入 + 出构建
 - `app build` 只把项目**已发布**的前端产物（`adep publish --only frontend` 的产物）打进壳：
   经平台导出链路拉包 → 校验 manifest 与逐项 sha256 → 只取 `site/**` 注入 `app/site/`
   （注入前清空旧产物，上一次构建留下的陈旧文件不会躺在安装包里）；
+- **缺省产物形态**（APP-037 契约门锁住，漂移当场红）：
+
+  | 平台                 | 缺省格式                                                | 签名状态 | 说明                                                                                                                                                               |
+  | -------------------- | ------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+  | macOS（`darwin`）    | `.dmg`                                                  | unsigned | 签名 / 公证由开发者本地完成                                                                                                                                        |
+  | Windows（`win32`）   | nsis 安装器（`*-Setup.exe`）+ zip 便携包（`*-win.zip`） | unsigned | 安装器**不是单文件绿色 exe**；zip 便携包（APP-043）解压后直接运行里面的 `<productName>.exe`，两者同次产出                                                          |
+  | Linux（`linux`）     | `.AppImage` + `.deb`                                    | unsigned | deb 需要宿主机有 `dpkg-deb`——缺失时 electron-builder 会静默跳过，构建报告与终端会显式列出 `APP_BUILD_TARGET_SKIPPED` 及原因（rpm 不进缺省模板，见计划 R2 拍板 P3） |
+  | Android（`android`） | unsigned `.apk`                                         | unsigned | `gradlew assembleRelease`，签名由开发者自担                                                                                                                        |
+  | iOS（`ios`）         | unsigned `.xcarchive` / `.ipa`                          | unsigned | xcodebuild 或 xtool（`--toolchain xtool` 产 `.ipa`）                                                                                                               |
+
 - **函数源码不入包**：在线运行时下函数在服务端执行，构建报告里的函数清单只标
   `runtime: "online"`（安装包内不含任何 `functions/` 文件）；
 - 产物版本回写 `adep.app.json` 的 `build` 段（`bundleVersion` = manifest 项目版本 + `site/` 内容指纹，
@@ -517,6 +550,12 @@ adep app build --prepare-only                # 只拉产物 + 注入 + 出构建
 - fail loud（都以退出码 1 结束且不产出安装包）：项目从未发布前端（提示先跑
   `publish --only frontend`）、壳工程依赖未安装（提示先 `npm install`）、导出包损坏或内容物校验和不匹配。
   其中「依赖未安装」的判定**有意排在导出之前**——导出是分钟级长任务，依赖没装不必白跑。
+- `app open`（APP-035）只服务桌面壳：直接调壳工程内安装的 `node_modules/.bin/electron .`
+  （与模板缺省 start script `electron .` 等价，不经 npm 以规避 Windows 下 npm.cmd 的 shell 差异；
+  若你改过 start script，open 不感知，直接跑 `npm start` 即可）。**移动壳没有开发预览路径**
+  （capacitor 壳下一步是 `npx cap add ios / android` + Xcode / Android Studio，xtool 壳是 `xtool dev`），
+  对它们执行 open 当场报 `APP_OPEN_UNSUPPORTED` 并点名下一步。与 `app doctor` 同口径的开发期
+  便利命令：不需要登录、不需要网络、不设门（判定门在 `app build`）。
 
 #### 移动壳（Capacitor，APP-009）
 
@@ -533,18 +572,100 @@ adep app build --platform ios                            # xcodebuild archive（
 - 骨架含 `plugins/adep-bridge` **原生桥**（iOS Swift / Android Kotlin）与 host-side 门控镜像
   `bridge/gate.mjs`：权限门控做在**原生侧**，未在 `adep.permissions.json` 声明的权限一律
   `PERMISSION_DENIED` + 设备侧审计日志；`ownerKey` 只存 Keychain / Keystore。
+- 构建往 `app/site/` 落四件：`adep.permissions.json`（权限清单）、`adep-bridge.js`（页面桥）、
+  `adep.app.json`（壳配置）、以及往 `index.html` 幂等注入的一行 `<script src="/adep-bridge.js">`。
+  **缺 `index.html` 即构建失败**（`APP_SITE_MISSING`）：它是 WebView 恒加载的入口页，缺了装机就是
+  白屏——所以不产出「报告成功、装机白屏」的包。页面加载后由桥装配 `window.__ADEP_APP__`，
+  失败时按原因分三种字段（`configError` / `offlineError` / `timeoutError`），都带可读原因，
+  不会只剩一个 `MISSING`。
+- iOS 侧原生桥是**双形态并存**（APP-015）：`Package.swift`（SPM）与 `ios/AdepBridge.podspec`
+  （CocoaPods）各管一条消费路径。自 Capacitor 8 起 `cap add ios` 默认建 SPM 工程，缺 SPM 清单的
+  插件会被**静默跳过**（运行时才报 "plugin is not implemented"），所以两者都别删；包名 / product 名
+  （`AdepBridge`）、目录布局（清单在 npm 包根、源码平铺 `ios/Sources`）与 iOS 下限（14.0）两形态必须一致。
 - 移动平台**必须显式指定** `--platform ios|android`；产物是 **unsigned** 的 `.xcarchive` / APK。
+- ⚠️ **`.xcarchive` ≠ 安装包**（APP-040）：它是 Xcode 的归档格式，不能直接装真机；导出 `.ipa`
+  还需要在 Xcode 里完成 Distribute App（或 `xcodebuild -exportArchive`），而导出要**用户自备**
+  `ExportOptions.plist` 与描述文件——平台不出具签名（PRD §2.11.7），这一步不做自动化
+  （见 `docs/mobile-shell-signing.md` §3）。构建期会对 `.xcarchive` 做产物级结构核对：
+  缺 `Products/Applications/*.app` 报 `APP_ARCHIVE_INCOMPLETE`；归档内出现
+  `_CodeSignature` / `embedded.mobileprovision` 报 `APP_ARCHIVE_SIGNED`（与「平台不出具签名」
+  口径冲突，属实现回归）。
 - 签名 / 公证 / 上架由开发者自担，逐步指引见仓库 `docs/mobile-shell-signing.md`。
 
-#### 离线运行时（`--offline`，APP-008）
+#### 离线运行时（`--offline`，APP-008 / APP-022）
+
+```bash
+adep app build --offline                     # 桌面壳：注入 app/offline/
+adep app build --offline --toolchain xtool   # iOS xtool 壳：注入 app/site/offline/
+```
+
+把设备端运行时（`@adep/app-runtime`）装入壳工程的离线根——桌面 `app/offline/`，xtool
+`app/site/offline/`（页面经 `capacitor://` 只能读 `appLocation` 之内的文件）：白名单云函数与
+数据库基线表全部**随包本地执行**，不需要平台在线。白名单函数含**不可移植**写法时构建失败、
+退出码非 0，错误含违规类型与文件名行号。
+
+`--offline` 在**桌面壳**下不接受 `--platform`（离线包与平台无关）；iOS 走
+`--offline --toolchain xtool`（恒 `--platform ios`）。
+
+⚠️ **xtool 离线构建要求先跑在线构建**：离线路径只追加 `site/offline/` 子树与壳注入面
+（页面桥 / `adep.app.json` / 权限清单），**不产生页面本体**——页面只能来自平台导出。
+缺 `app/site/index.html` 时当场报 `APP_SITE_MISSING`，不会产出「报告成功、装机白屏」的包。
+
+```bash
+adep app build --platform ios --toolchain xtool   # 1) 拉页面产物 + 注入页面桥 / 壳配置
+adep app build --offline --toolchain xtool        # 2) 追加离线树
+```
+
+#### 壳工程体检（`adep app doctor`，APP-031）
+
+```bash
+adep app doctor                      # 体检当前目录（壳工程根）
+adep app doctor --dir ./my-app-app   # 指定壳工程
+adep app doctor --json               # 机器可读（脚本 / CI 归档）
+```
+
+**只读、不需要登录、不需要网络**：体检的是「盘上已经有的东西」。它与 `app build` 的分工是场景不同——
+build 要先登录、先发布、跑一整轮导出才知道注入面齐不齐；doctor 一条离线命令就回答同一个问题，
+适合排查「上次构建留下的壳工程为什么装机白屏」。十项结论各带固定 `id` 与原因码（与构建侧同码）：
+
+| id             | 查什么                                                                                           | 不通过时                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `config`       | `adep.app.json` 在且过 schema                                                                    | `APP_CONFIG_NOT_FOUND` / `APP_CONFIG_INVALID`（读不到就当场收口，不再往下猜）            |
+| `form`         | 由 `template` 推导构建形态（desktop→electron；mobile→capacitor + 盘上原生工程；xtool→xtool/ios） | 还没 `npx cap add` / 未知模板 ⇒ 提示                                                     |
+| `deps`         | 打包器前置（复用构建侧判定，不写盘）                                                             | `APP_SHELL_DEPS_MISSING` / `APP_XTOOL_MISSING` / `APP_XCODE_SDK_MISSING`                 |
+| `siteEntry`    | `app/site/index.html`                                                                            | `APP_SITE_MISSING` / `APP_SITE_UNREADABLE`                                               |
+| `bridgeTag`    | 入口页引用了 `/adep-bridge.js`（桌面壳改查 `preload.cjs`）                                       | 桥压根不执行 ⇒ `__ADEP_APP__` 永不出现                                                   |
+| `siteAssets`   | `app/site/` 三件套齐（桌面壳不走注入，跳过）                                                     | 点名缺哪一个                                                                             |
+| `configDrift`  | 站点内壳配置与壳根一致（比页面消费的 6 个字段；`build` 段不比）                                  | 构建后改了配置没重建 ⇒ 页面还在打旧平台地址                                              |
+| `buildBinding` | 壳根有 `build` 段                                                                                | 未构建过 ⇒ 提示（新 init 的正常中间态）                                                  |
+| `offline`      | 离线树必需文件 + 函数清单里每个函数的源码                                                        | 点名缺件 / 缺哪个函数源码（设备上会 FN_NOT_FOUND）                                       |
+| `identity`     | 桌面壳首启是否签发了 `ownerKey`、落在哪种存储（读 `data/identity/status.json`，**非机密**）      | 未自举 ⇒ 提示；落在 0600 文件 ⇒ 明说「非系统凭据」；签发失败 ⇒ 原因码原样透出（APP-033） |
+
+**它不是门**：有 `fail` 项也以退出码 0 结束（与 `adep doctor` 同口径）；判定门在 `adep app build`。
+
+#### 离线库同步（`adep app sync`，APP-032）
 
 ```bash
-adep app build --offline                     # 消费服务端 .adepack：离线白名单函数 + 基线表 + 预置资源
+adep app sync --owner-key adep_ok_…        # 一次往返：先上行 outbox，再拉下行增量
+adep app sync --owner-key adep_ok_… --push # 只上行（排障时不必来回跑整轮）
+adep app sync --owner-key adep_ok_… --pull # 只下行
+ADEP_OWNER_KEY=adep_ok_… adep app sync     # 也可以走环境变量
 ```
 
-把设备端运行时（`@adep/app-runtime`）装入 `app/offline/`：页面、白名单云函数与数据库基线表全部**随包本地执行**，
-不需要平台在线。白名单函数含**不可移植**写法时构建失败、退出码非 0，错误含违规类型与文件名行号。
-`--offline` 与 `--platform` 互斥——离线包与平台无关，iOS 不做运行时下发离线包。
+把桌面壳的**设备本地库**（`data/offline.sqlite`，由离线运行时首次启动时创建）与云端项目库按
+单主语义对齐：上行读本地变更流 → `outbox` → `POST /app-sync/upstream`（整批原子，服务端确认后才推进
+`acked_seq`）；下行 `GET /app-sync/changes?since=<游标>` → 应用进本地库（**直写驱动，不追加变更流**，
+否则刚拉下来的行会被下一次上行当成新写推回去）。
+
+- **身份不是可选项**：`--owner-key` / `ADEP_OWNER_KEY` 必填。ownerKey 由服务端签发
+  （`POST /api/v1/projects/<slug>/app-installations`，移动壳由原生侧首启自举写入 Keychain / Keystore，
+  桌面壳由主进程首启自举写入系统凭据库或 0600 文件，见 APP-033），
+  CLI **不复用平台会话**冒充设备身份；缺失即 `IDENTITY_MISSING` 且不发任何 `/app-sync` 请求。
+  桌面 app 自己启动后会自动同步；本命令用于**开发期 / 排障**（比如看某次上行到底卡在哪一批）。
+- 同步目标取壳配置的 `platformUrl` / `projectSlug`（不是 `ADEP_SERVER`）：同步的一定是**这个壳**连的项目。
+- 只支持**桌面壳**：移动壳的库在设备沙箱里，本机 CLI 摸不到（`APP_SYNC_UNSUPPORTED_SHELL`）。
+- 本地库不存在 ⇒ `APP_SYNC_DB_MISSING`（先跑一次离线运行时，库才会被建出来）。
+- 服务端拒绝时命令退出码非 0，**码与 `failedSeq` 原样透出**，本地位点不动（可原样重试）。
 
 ---
 
@@ -552,18 +673,22 @@ adep app build --offline                     # 消费服务端 .adepack：离线
 
 ### 环境变量
 
-| 变量              | 说明                              | 缺省                          |
-| ----------------- | --------------------------------- | ----------------------------- |
-| `ADEP_SERVER`     | 平台地址（CLI 请求的默认 server） | `https://adep.top`   |
-| `ADEP_HOME`       | 凭据目录（测试隔离用）            | `~/.adep`                     |
-| `ADEP_NO_BROWSER` | `1` = `adep login` 不打开浏览器   | 未设置（TTY 下自动打开）      |
+| 变量              | 说明                                                | 缺省                                                        |
+| ----------------- | --------------------------------------------------- | ----------------------------------------------------------- |
+| `ADEP_SERVER`     | 平台地址（CLI 请求的默认 server）                   | `https://adep.top`                                          |
+| `ADEP_HOME`       | 凭据目录（测试隔离用）                              | `~/.adep`                                                   |
+| `ADEP_NO_BROWSER` | `1` = `adep login` 不打开浏览器                     | 未设置（TTY 下自动打开）                                    |
+| `ADEP_ENV`        | 数据面默认环境（`dev` / `prod`）                    | 未设置（再读 `db_environment`，最后 `prod`）                |
+| `ADEP_OWNER_KEY`  | `adep app sync` 的设备身份（服务端签发的 ownerKey） | 未设置（`--owner-key` 优先；两者都空即 `IDENTITY_MISSING`） |
 
 ```bash
 export ADEP_SERVER=https://platform.example.com
 export ADEP_HOME=~/.adep
+export ADEP_ENV=dev          # 等价于每条命令都带 --env dev（db exec / migrate / tables、storage、publish 前端）
 ```
 
-> 也可通过 `-s` / `-e` / `-p` 等子命令参数覆盖。
+> 也可通过 `-s` / `-e` / `-p` 等子命令参数覆盖。全局旗标 `--env <dev|prod>` 优先级最高：
+> `--env` > `ADEP_ENV` > `adep.config.ts` 的 `db_environment` > `prod`。
 
 ### `adep.config.ts`
 
@@ -576,6 +701,7 @@ export default {
   template: 'fullstack', // 模板：empty | function | fullstack
   functionsDir: 'functions', // 云函数目录
   functions_prefix: '/api', // 云函数路由前缀（默认 /api，与线上 /api/{fn} 对齐）
+  db_environment: 'dev', // 数据面默认环境（dev | prod，2026-10-18）
 }
 ```
 
@@ -583,6 +709,9 @@ export default {
 - `functions_prefix`：**影响本地路由与 vite 插件代理前缀**（见上方 `adep init` 产物结构说明）——
   默认 `/api`：`adep dev` 访问 `/{prefix}/{fnName}`、`adep serve` 访问 `/api/{prefix}/{fnName}`、
   vite 插件按 `/{prefix}/*` 代理；函数互调与线上部署路径不随前缀变化。
+- `db_environment`：不带 `--env` 也不设 `ADEP_ENV` 时数据面命令的默认环境。⚠️ **不能复用**
+  `environment`——那个键是「注入函数运行时的变量表」（`Record<string, string>`），同名会让解析拿到
+  对象、判成非法值。
 
 ---