@adep/cli 0.4.6 → 0.4.10

package/README.md

@@ -83,7 +83,7 @@ bun run packages/cli/src/index.ts --help
 ## 快速开始
 
 ```bash
-# 1. 登录平台（打开浏览器用网页授权；凭据保存在 ~/.adep/credentials，权限 0600）
+# 1. 登录平台（打开浏览器用网页授权；凭据按 server 分槽保存于 ~/.adep/credentials.d/，权限 0600）
 adep login
 # 无浏览器环境（SSH / 无桌面）：只打印验证码与链接，手工在浏览器里完成授权
 adep login --no-browser
@@ -139,6 +139,11 @@ adep logout                      # 通知平台注销并清除本地凭据
   平台没有设备授权端点（老版本）→ `LOGIN_UNSUPPORTED`（提示改用 `-e/-p`）。失败**不写凭据**。
 - 凭据形态：浏览器登录落 `authType: "bearer"`（发 `Authorization: Bearer`），
   密码直登落 `authType: "cookie"`；旧凭据缺该字段按 cookie 兼容。
+- 凭据按 server **分槽**保存（`~/.adep/credentials.d/<host>.json` + `current` 指针，
+  权限 0600）：SaaS 与本地自建位等多环境先后登录**互不覆盖**——登录哪个环境，
+  后续命令就连哪个环境的凭据，谁也不会被静默替换；旧版单文件 `~/.adep/credentials`
+  在首次读写时自动迁入对应槽并删除。同 server 重复登录只覆盖自己的槽（输出会注明
+  替换了哪个邮箱的凭据）。
 
 ### `adep init`
 
@@ -488,13 +493,18 @@ adep storage rm avatars/a.png
 
 ```bash
 adep hosting info                        # 查看托管配置、站点地址与文件树
-adep hosting deploy ./dist               # 递归上传目录到 site/ 并打开托管（deprecated）
+adep hosting deploy ./dist               # 增量上传目录到 site/ 并打开托管（deprecated）
 adep hosting deploy ./dist --spa         # 同时启用 SPA 回退（deprecated）
+adep hosting deploy ./dist --build "npm run build"   # 部署前先跑构建命令（非零退出即中止）
 adep hosting pull [-o ./site]            # 拉取站点公开文件到本地（跳过 private 托管配置）
 adep hosting config --enabled true --spa true    # 更新托管开关 / SPA 回退（幂等）
 ```
 
-- **deploy**：把本地目录递归上传为 `site/<rel>`（public）→ 打开托管开关 → 输出站点地址。
+- **deploy**：先与线上 `site/` 文件表做**增量比对**（逐文件 sha256，CLI-038）——只上传变更文件，
+  输出「N 变更 / M 复用」与「部署内容构建于 <本地最新文件 mtime>」；**与线上完全一致（空 diff）时
+  输出醒目警示**——大概率是改了源码忘了先构建（旧实现全量盲传，曾把旧包原样重传上线且零提示）。
+  `--build <cmd>` 在项目根目录先执行构建命令，构建失败即中止部署。把本地目录上传为
+  `site/<rel>`（public）→ 打开托管开关 → 输出站点地址。
 
 - **pull**：只拉公开站点文件，private 侧载的托管配置（`site/.hosting.json`）不会进站点目录。
 
@@ -690,6 +700,34 @@ export ADEP_ENV=dev          # 等价于每条命令都带 --env dev（db exec /
 > 也可通过 `-s` / `-e` / `-p` 等子命令参数覆盖。全局旗标 `--env <dev|prod>` 优先级最高：
 > `--env` > `ADEP_ENV` > `adep.config.ts` 的 `db_environment` > `prod`。
 
+### 开发期环境变量（`.env` / `.env.local`）
+
+项目根的 `.env` / `.env.local` 与进程环境变量是**两条不同的通道**，混着预期是本地开发
+最常见的排查黑洞（esign 实测：`ADEP_AUTH_ISSUER` 写进 `.env` 后用 `bun run` 起 serve——
+函数数据面一切正常、应用却显示未登录，白耗一轮排查）：
+
+| 通道                                 | 谁在读                                                                                | 变量                                                                                                  | 生效条件                                                |
+| ------------------------------------ | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| **函数 env**（注入函数运行时）       | `adep dev` / `adep serve` 自己读 `.env` + `.env.local` 文件                           | 业务变量、`ADEP_SECRET_*`、`FUNCTIONS_FETCH_*`                                                        | 写进文件即可，**不依赖 shell 进程**                     |
+| **进程级**（CLI 命令自身的行为开关） | 只认 `process.env`，**不读 `.env` 文件**                                              | `PORT` / `HOST` / `ADEP_SERVE_STATIC_DIR` / `ADEP_SERVE_DB` / `ADEP_SERVE_DB_FILE` / `ADEP_SERVER` 等 | `export` / `env VAR=... adep serve` / Docker `env_file` |
+| **混合**（登录即服务）               | `process.env` 优先；缺失时回退 `adep dev` / `adep serve` 读到的 `.env` + `.env.local` | `ADEP_AUTH_ISSUER`                                                                                    | `export`（优先级最高）或直接写 `.env`                   |
+
+函数 env 的合并优先级（`adep dev` / `adep serve` 同一份实现）：`adep.config.ts` 的
+`environment` 为基座 → `.env` 覆盖 → `.env.local` 最优先。
+
+⚠️ **`bun run <script>`（以及 `npm run`）直跑自定义脚本时，`.env` 不会自动生效**——
+`bun run` 的子进程不自动加载 `.env`（node 更不会）。但 `adep dev` / `adep serve` 自己会读文件，
+所以「进程级变量全部失效」只对纯 shell 开关成立：
+
+- 函数 env 不受影响（CLI 自己读文件，数据面已自愈）；
+- `ADEP_AUTH_ISSUER` 有文件回退（CLI-044）：写进 `.env` 后 `bun run serve` / `adep serve` 也能
+  启用「登录即服务」，不再出现「平台授权成功、应用显示未登录」；`process.env` 仍优先；
+- 其余进程级开关（`PORT` / `HOST` / `ADEP_SERVE_*`）仍只认 `process.env`，要显式 `export`
+  或 `env VAR=... adep serve`。
+
+拿不准一个变量属于哪条通道，看它在哪个环节被消费：函数代码里读的走文件通道，
+`adep serve` / `adep dev` 命令行为开关走进程通道（`ADEP_AUTH_ISSUER` 是唯一的文件回退例外）。
+
 ### `adep.config.ts`
 
 `adep init` 生成的项目配置文件，CLI 的 `dev` / `serve` / `deploy` 按此识别项目（CLI 直接 import 后读 `default` 的字段，无需任何辅助包）：
@@ -767,6 +805,9 @@ adep --json publish -p my-app
 **Q：`adep db exec`** **的** **`--confirm-table`** **是做什么的？**
 写 / 破坏性语句（DELETE / DROP / ALTER…）服务端要求二次确认目标表名，`--confirm-table users` 即输入目标表名以放行；只读查询无需该参数。
 
+**Q：变量写进 `.env` 了，`adep serve` 却没生效？**
+先分通道：函数 env（业务变量 / `ADEP_SECRET_*`）走 `.env` / `.env.local` 文件，`adep dev` / `adep serve` 自己读、必生效；进程级开关（`PORT` / `HOST` / `ADEP_SERVE_*` 等）只认 `process.env`，要显式 `export` 或 `env VAR=... adep serve`。`ADEP_AUTH_ISSUER` 是混合通道（CLI-044）：`process.env` 优先，缺失时回退 `.env` / `.env.local`，所以写进 `.env` 也能启用登录即服务。`bun run <script>` / `npm run` 直跑时 `.env` 不会自动加载（详见「配置 → 开发期环境变量」）。
+
 **Q：`adep storage`** **/** **`adep hosting`** **需要在平台项目目录里跑吗？**
 不需要。它们通过 `-p <slug>` 指定目标项目，缺省才读取 `adep.config.ts` 的 `name`——在任何目录下都能对指定项目做资源运维。