@adep/cli 0.1.16 → 0.2.0

package/README.md

@@ -48,6 +48,8 @@
 
    - [`adep export`](#adep-export)
 
+   - [`adep app`](#adep-app)
+
 4. [配置](#配置)
 
    - [环境变量](#环境变量)
@@ -81,9 +83,12 @@ bun run packages/cli/src/index.ts --help
 ## 快速开始
 
 ```bash
-# 1. 登录平台（凭据保存在 ~/.adep/credentials，权限 0600）
+# 1. 登录平台（打开浏览器用网页授权；凭据保存在 ~/.adep/credentials，权限 0600）
 adep login
-# 或指定平台与邮箱：adep login -s https://platform.example.com -e you@example.com
+# 无浏览器环境（SSH / 无桌面）：只打印验证码与链接，手工在浏览器里完成授权
+adep login --no-browser
+# 或不走浏览器，直接用邮箱密码登录（脚本 / 老平台）
+adep login -s https://platform.example.com -e you@example.com -p '***'
 
 # 2. 初始化一个函数项目
 adep init my-app --template function
@@ -113,6 +118,28 @@ adep --json whoami
 
 失败时返回退出码 1 + `{"ok":false,"command":"...","error":{"code":"...","message":"..."}}`。
 
+### `adep login` / `whoami` / `logout`
+
+`adep login` 缺省走**浏览器网页授权**（RFC 8628 设备授权流）：CLI 向平台要一个设备码并把
+`<平台>/device?user_code=XXXX` 打开，你在网页上确认「批准」后 CLI 自动换回会话并落盘凭据。
+
+```bash
+adep login                       # 打开浏览器；终端会同时打印验证码与链接
+adep login --no-browser          # 不开浏览器：手工访问打印出来的链接（SSH / 无桌面）
+adep login -s <url>              # 指定平台（缺省 ADEP_SERVER，再缺省 https://adep.jajabjbj.top）
+adep login -e <邮箱> -p <密码>   # 邮箱密码直登，不发起浏览器流程（CI / 老平台）
+adep whoami                      # 查看当前身份（读凭据并向平台确认会话仍有效）
+adep logout                      # 通知平台注销并清除本地凭据
+```
+
+- 判定「打不开浏览器」的三种情况：`--no-browser`、`ADEP_NO_BROWSER=1`、stdout 不是 TTY（CI）。
+  三种都**不会**尝试打开浏览器，但都会打印验证码与链接——命令仍可完成登录。
+- `--json` 模式下交互提示（验证码 / 链接）写 **stderr**，stdout 恒为恰好一个 JSON 对象。
+- 失败语义：用户拒绝 → `LOGIN_DENIED`；验证码过期 → `DEVICE_CODE_EXPIRED`；
+  平台没有设备授权端点（老版本）→ `LOGIN_UNSUPPORTED`（提示改用 `-e/-p`）。失败**不写凭据**。
+- 凭据形态：浏览器登录落 `authType: "bearer"`（发 `Authorization: Bearer`），
+  密码直登落 `authType: "cookie"`；旧凭据缺该字段按 cookie 兼容。
+
 ### `adep init`
 
 初始化项目（脚手架）。**默认 `fullstack` 模板**：生成与 Web IDE 项目**同一结构**的全栈骨架
@@ -133,7 +160,7 @@ adep init --list -s https://platform.example.com
 adep templates publish -t fullstack  # 上传平台托管模板包（需登录；模板目录须含 template.json）
 ```
 
-模板来源（CLI-020）：`adep init` 优先下载**平台托管模板包**（`GET /api/v1/templates/:code/package`，
+模板来源（CLI-023）：`adep init` 优先下载**平台托管模板包**（`GET /api/v1/templates/:code/package`，
 缓存到 `~/.adep/templates/<code>-<version>.json`）；平台无包 / 下载失败 / 离线时自动回退本地内置模板。
 模板包为 JSON 文件映射，与本地内置模板共用同一套 `{{var}}` 渲染管线。
 
@@ -196,10 +223,15 @@ vite 工程根在项目根目录（`vite.config.ts` / `index.html` / 根 `packag
 ```bash
 adep dev                      # 默认端口 8787
 adep dev -p 3000              # 指定端口
+adep dev --db sim             # 回到纯模拟数据面（.adep/sim/db.json）
+adep dev --db sqlite --db-file var/dev.sqlite    # 自定义库文件
+adep dev --schema database/schema.sql            # 启动时灌 schema（与 serve 同一套语义）
 ```
 
 - **模拟运行时**：默认使用进程内模拟运行时（`@adep/runtime` + 本地模拟器），**不连云端、不装 Docker、断网也能开发**——只替换传输与持久化，不改写函数语义。
 
+- **数据库面与 `adep serve` 同源**：缺省 `--db sqlite`（真实 SQLite 库文件 `.adep/data/project.sqlite`，schema.sql 全量生效、视图 / 唯一索引可用；运行时不支持或打开失败时自动降级 `sim` 并告警），`--db sim` 回到内置模拟引擎。三个旗标（`--db` / `--db-file` / `--schema`）与 `adep serve` **共用同一份实现**，两条命令在同一目录、同一环境下必然给出同一个数据面。
+
 - **能力注入**：自动装配 `cloud.db` / `cloud.storage` / `cloud.realtime`，语义与线上一致。
 
 - **环境变量**：读取 `.env.local` / `.env` 的键值，注入执行沙箱（`process.env[KEY]`）。
@@ -246,7 +278,7 @@ adep serve --db sqlite --db-file var/local.sqlite   # 指定库文件
 ```bash
 adep publish                          # 缺省全栈：函数 deploy + 前端平台侧构建托管
 adep publish --only functions         # 只发布云函数
-adep publish --only frontend          # 只触发平台侧前端构建（FN-024）并切换站点版本
+adep publish --only frontend          # 只触发平台侧前端构建（FN-025）并切换站点版本
 adep publish -p my-app                # 显式指定目标 slug
 ```
 
@@ -302,11 +334,11 @@ hello  v1  https://my-app.platform.example.com/hello
 项目子命令组：创建 / 列出 / 查看 / 删除。子域地址由平台回显（`projectBaseUrl`），CLI 不自行拼域名。
 
 ```bash
-adep projects create game-arcade            # → ✓ Project created · https://game-arcade.adep.top
-adep projects create game-arcade -n 游戏厅  # 展示名与 slug 分开
+adep projects create notes-app              # → ✓ Project created · https://notes-app.adep.top
+adep projects create notes-app -n 笔记应用  # 展示名与 slug 分开
 adep projects list                          # slug \t name \t url
-adep projects info game-arcade              # id \t slug \t name \t url
-adep projects delete game-arcade --yes      # → ✓ Project deleted · game-arcade
+adep projects info notes-app                # id \t slug \t name \t url
+adep projects delete notes-app --yes        # → ✓ Project deleted · notes-app
 ```
 
 - `--name` 缺省取 slug：一行命令即可建项目。
@@ -449,16 +481,73 @@ adep export --out ./dist-export      # 指定输出目录（缺省 ./exports）
 
 - `--json` 输出单个结果信封；导出失败（长任务未产出 / 自检不过）以退出码 1 + `EXPORT_FAILED` 结束，不静默给半截产物。
 
+### `adep app`
+
+应用壳工程（PRD §2.11 路径 A：在线运行时——**页面随包本地加载、云函数服务端执行**，改函数逻辑不需要重新发版）。
+两种壳：`--platform desktop`（缺省，Electron）与 `--platform mobile`（Capacitor 移动壳，见下）。
+
+```bash
+adep app init -p my-app -n "我的应用"        # 生成 Electron 壳工程（缺省 ./my-app-app）
+cd my-app-app && npm install                 # 壳工程依赖（electron + electron-builder）
+
+adep app build                               # 拉取已发布页面产物 → 注入 app/site/ → 出安装包
+adep app build --platform win32              # 交叉指定目标平台（缺省当前平台）
+adep app build --target dir                  # 只出未压缩目录（macOS 即 .app），本地快速验证
+adep app build --prepare-only                # 只拉产物 + 注入 + 出构建报告，不调 electron-builder
+```
+
+- `app build` 只把项目**已发布**的前端产物（`adep publish --only frontend` 的产物）打进壳：
+  经平台导出链路拉包 → 校验 manifest 与逐项 sha256 → 只取 `site/**` 注入 `app/site/`
+  （注入前清空旧产物，上一次构建留下的陈旧文件不会躺在安装包里）；
+- **函数源码不入包**：在线运行时下函数在服务端执行，构建报告里的函数清单只标
+  `runtime: "online"`（安装包内不含任何 `functions/` 文件）；
+- 产物版本回写 `adep.app.json` 的 `build` 段（`bundleVersion` = manifest 项目版本 + `site/` 内容指纹，
+  内容不变则版本不变），同一份版本也写进 `dist/build-report.json`（`appName` / `bundleVersion` /
+  `functions` / `topAssets` 四字段 + 平台、产物路径等）；
+- 平台**不出具任何签名**：签名与公证由开发者本地完成；
+- fail loud（都以退出码 1 结束且不产出安装包）：项目从未发布前端（提示先跑
+  `publish --only frontend`）、壳工程依赖未安装（提示先 `npm install`）、导出包损坏或内容物校验和不匹配。
+  其中「依赖未安装」的判定**有意排在导出之前**——导出是分钟级长任务，依赖没装不必白跑。
+
+#### 移动壳（Capacitor，APP-009）
+
+```bash
+adep app init -p my-app -n "我的应用" --platform mobile   # Capacitor 骨架 + plugins/adep-bridge 原生桥
+cd my-app-app && npm install
+npx cap add ios && npx cap add android                   # 原生工程由 Capacitor 生成
+
+adep app build --platform android --prepare-only         # 只注入 + 出报告，先验证注入面
+adep app build --platform android                        # gradlew assembleRelease → unsigned APK
+adep app build --platform ios                            # xcodebuild archive（CODE_SIGNING_ALLOWED=NO）
+```
+
+- 骨架含 `plugins/adep-bridge` **原生桥**（iOS Swift / Android Kotlin）与 host-side 门控镜像
+  `bridge/gate.mjs`：权限门控做在**原生侧**，未在 `adep.permissions.json` 声明的权限一律
+  `PERMISSION_DENIED` + 设备侧审计日志；`ownerKey` 只存 Keychain / Keystore。
+- 移动平台**必须显式指定** `--platform ios|android`；产物是 **unsigned** 的 `.xcarchive` / APK。
+- 签名 / 公证 / 上架由开发者自担，逐步指引见仓库 `docs/mobile-shell-signing.md`。
+
+#### 离线运行时（`--offline`，APP-008）
+
+```bash
+adep app build --offline                     # 消费服务端 .adepack：离线白名单函数 + 基线表 + 预置资源
+```
+
+把设备端运行时（`@adep/app-runtime`）装入 `app/offline/`：页面、白名单云函数与数据库基线表全部**随包本地执行**，
+不需要平台在线。白名单函数含**不可移植**写法时构建失败、退出码非 0，错误含违规类型与文件名行号。
+`--offline` 与 `--platform` 互斥——离线包与平台无关，iOS 不做运行时下发离线包。
+
 ---
 
 ## 配置
 
 ### 环境变量
 
-| 变量          | 说明                              | 缺省                    |
-| ------------- | --------------------------------- | ----------------------- |
-| `ADEP_SERVER` | 平台地址（CLI 请求的默认 server） | `http://localhost:3000` |
-| `ADEP_HOME`   | 凭据目录（测试隔离用）            | `~/.adep`               |
+| 变量              | 说明                              | 缺省                          |
+| ----------------- | --------------------------------- | ----------------------------- |
+| `ADEP_SERVER`     | 平台地址（CLI 请求的默认 server） | `https://adep.jajabjbj.top`   |
+| `ADEP_HOME`       | 凭据目录（测试隔离用）            | `~/.adep`                     |
+| `ADEP_NO_BROWSER` | `1` = `adep login` 不打开浏览器   | 未设置（TTY 下自动打开）      |
 
 ```bash
 export ADEP_SERVER=https://platform.example.com