@adep/cli 0.0.1

package/README.md

@@ -0,0 +1,371 @@
+# adep — AgentDeploy CLI
+
+> 面向终端开发者的 AgentDeploy 命令行工具：**登录 / 初始化 / 本地调试 / 部署 / 数据库维护 / 云存储 / 静态托管 / 微前端组件（widget）** 一站式闭环。
+
+`adep` 让你在一个项目目录里完成从**脚手架 → 本地调试 → 部署上线 → 数据与资源运维**的完整流程。它复用平台运行时内核（`@adep/runtime`），本地与线上的执行语义一致，离线、不装 Docker 也能开发。
+
+<br />
+
+<div align="center">
+
+**[安装](#安装)** · **[快速开始](#快速开始)** · **[子命令](#子命令)** · **[配置](#配置)** · **[FAQ](#faq)**
+
+</div>
+
+---
+
+## 目录
+
+1. [安装](#安装)
+
+2. [快速开始](#快速开始)
+
+3. [子命令](#子命令)
+
+   - [`adep init`](#adep-init)
+
+   - [`adep dev`](#adep-dev)
+
+   - [`adep deploy`](#adep-deploy)
+
+   - [`adep db`](#adep-db)
+
+   - [`adep storage`](#adep-storage)
+
+   - [`adep hosting`](#adep-hosting)
+
+   - [`adep widget`](#adep-widget)
+
+4. [配置](#配置)
+
+   - [环境变量](#环境变量)
+
+   - [`adep.config.ts`](#adepconfigts)
+
+5. [常用示例](#常用示例)
+
+6. [FAQ](#faq)
+
+7. [相关](#相关)
+
+---
+
+## 安装
+
+```bash
+# 通过 npm 全局安装
+npm install -g @adep/cli
+# 或使用 bun
+bun add -g @adep/cli
+# 发布前本地调试：从仓库根目录
+bun run packages/cli/src/index.ts --help
+```
+
+> **要求**：Node ≥ 22.19，或 Bun ≥ 1.3（Bun 可免编译直接运行 TS，推荐用于本地开发）。
+> 安装后运行 `adep --help` 查看全部可用命令。
+
+---
+
+## 快速开始
+
+```bash
+# 1. 登录平台（凭据保存在 ~/.adep/credentials，权限 0600）
+adep login
+# 或指定平台与邮箱：adep login -s https://platform.example.com -e you@example.com
+
+# 2. 初始化一个函数项目
+adep init my-app --template function
+
+# 3. 进入项目，本地调试（监听 functions/，支持热重载）
+cd my-app
+adep dev
+# → http://127.0.0.1:8787/hello
+
+# 4. 部署上线
+adep deploy
+```
+
+三步即可把本地 `functions/hello.ts` 发到线上并得到公网访问地址。
+
+---
+
+## 子命令
+
+所有子命令都支持全局 `--json` 标志，以机器可读的 JSON 信封输出（适合 Agent / 脚本调用）：
+
+```bash
+adep --json whoami
+# → {"ok":true,"command":"whoami","data":{"email":"...","server":"..."}}
+```
+
+失败时返回退出码 1 + `{"ok":false,"command":"...","error":{"code":"...","message":"..."}}`。
+
+### `adep init`
+
+初始化项目（脚手架），模板二选一：
+
+| 模板       | 说明                                          |
+| ---------- | --------------------------------------------- |
+| `empty`    | 仅 `adep.config.ts` + 空入口，不生成示例函数  |
+| `function` | 生成一个示例函数 `functions/hello.ts`（默认） |
+
+```bash
+adep init my-app                 # 默认 function 模板
+adep init my-app -t empty        # 空模板
+adep init --list                 # 从平台 GET /api/v1/templates 列出可用模板
+adep init --list -s https://platform.example.com
+```
+
+产物结构（`function` 模板）：
+
+```
+my-app/
+├── adep.config.ts      # 项目标识（dev / deploy 按此识别）
+├── functions/
+│   ├── hello.ts        # 示例函数（deploy 后经 /hello 触发）
+│   └── README.md
+├── README.md
+└── .gitignore          # 已忽略 node_modules/ data/ .adep/
+```
+
+> 目录已存在时会拒绝覆盖（fail loud），不会静默改写你的代码。
+
+### `adep dev`
+
+本地调试：监听 `functions/`（以及 `.env.local` / `adep.config.ts`）变化并热重载，默认监听 `http://127.0.0.1:8787/<fnName>`，冷启动 ≤ 1.5s，文件变更到可被调用 ≤ 300ms。
+
+```bash
+adep dev                      # 默认端口 8787
+adep dev -p 3000              # 指定端口
+```
+
+- **模拟运行时**：默认使用进程内模拟运行时（`@adep/runtime` + 本地模拟器），**不连云端、不装 Docker、断网也能开发**——只替换传输与持久化，不改写函数语义。
+
+- **能力注入**：自动装配 `cloud.db` / `cloud.storage` / `cloud.realtime`，语义与线上一致。
+
+- **环境变量**：读取 `.env.local` / `.env` 的键值，注入执行沙箱（`process.env[KEY]`）。
+
+- **能力边界**：启动时打印一行边界清单（如下），提示本地与线上的差异：
+
+  - 定时/事件触发器只登记，本地以手工 HTTP 调用替代；
+
+  - realtime 为单进程内存广播，线上多实例语义不同；
+
+  - 本地不执行计量 / 配额门禁，不计费。
+
+```bash
+[adep] dev server listening on http://127.0.0.1:8787（Ctrl-C 退出）
+[adep] curl 示例：curl http://127.0.0.1:8787/hello
+...
+```
+
+### `adep deploy`
+
+增量部署：扫描本地 `functions/` 计算内容哈希 → 调平台 `/api/v1/deploy/diff` 拿差异清单 → 仅上传变更函数 → 发布 → 输出访问域名。
+
+```bash
+adep deploy                      # 项目 slug 取 adep.config.ts 的 name
+adep deploy -p my-app            # 显式指定目标 slug
+```
+
+- 本地 `functions/<name>.ts` 对应平台函数 `<name>`（入口文件固定为 `index.ts`）。
+
+- **幂等**：内容与已发布版本一致时输出 `no changes`，不产生新版本。
+
+- 成功输出每个函数的名字 / 版本 / 访问地址：
+
+```bash
+hello  v1  https://my-app.platform.example.com/hello
+```
+
+### `adep db`
+
+项目数据库维护子命令组：启动 / 状态 / 停止 / SQL 执行 / 快照 / 时间点回滚。项目参数缺省取 `adep.config.ts` 的 `name`（也可用 `-p` 显式指定）。
+
+```bash
+adep db start                          # 启动项目数据库（已存在则重新激活，不重建数据）
+adep db status                         # 查询状态与用量（体积 / 表数 / 行数）
+adep db stop                           # 停止数据库（连接关闭并标记；文件保留）
+
+# 执行单条 SQL；写 / 破坏性语句需 --confirm-table 二次确认目标表名
+adep db exec --sql "SELECT * FROM users"
+adep db exec --sql "DELETE FROM users WHERE id = 1" --confirm-table users
+
+# 快照（付费档位）：列出 / 创建 / 还原
+adep db snapshot list
+adep db snapshot create
+adep db snapshot restore <snapshotId>
+
+# 时间点回滚（团队版，基于变更流重放）
+adep db rollback --to 2026-01-01T00:00:00.000Z
+```
+
+`db exec` 人读模式下返回对齐文本表（结果行截断时会提示），`--json` 输出结构化结果。
+
+### `adep storage`
+
+云存储 / 文件存储子命令组：上传 / 下载 / 列表 / 删除。
+
+```bash
+adep storage upload ./avatar.png --path avatars/a.png            # 缺省 private（签名访问）
+adep storage upload ./banner.png --path site/banner.png --visibility public   # public 直连
+adep storage download avatars/a.png [-o 本地输出路径]              # 自动解析签名 / 直连 URL 落盘
+adep storage ls [--prefix site/]                                  # 按前缀列出（附访问 URL）
+adep storage rm avatars/a.png
+```
+
+- **上传**：multipart，单文件 ≤ 50MB；`path` 为桶内相对路径，`visibility` 决定 public 直连或 private 签名。
+
+- **下载**：先列表解析出服务端生成的 URL（public 直连 / private 15 分钟签名），再取回内容——private 文件无需 CLI 自行签发签名。
+
+- 所有命令都支持 `-p <slug>` 指定项目。
+
+### `adep hosting`
+
+静态托管子命令组：查看 / 部署 / 拉取 / 配置。站点文件即项目桶 `site/` 前缀下的 public 文件。
+
+```bash
+adep hosting info                        # 查看托管配置、站点地址与文件树
+adep hosting deploy ./dist               # 递归上传目录到 site/ 并打开托管
+adep hosting deploy ./dist --spa         # 同时启用 SPA 回退（无匹配静态文件回 index.html）
+adep hosting pull [-o ./site]            # 拉取站点公开文件到本地（跳过 private 托管配置）
+adep hosting config --enabled true --spa true    # 更新托管开关 / SPA 回退（幂等）
+```
+
+- **deploy**：把本地目录递归上传为 `site/<rel>`（public）→ 打开托管开关 → 输出站点地址。
+
+- **pull**：只拉公开站点文件，private 侧载的托管配置（`site/.hosting.json`）不会进站点目录。
+
+### `adep widget`
+
+微前端组件（widget）的子命令组：脚手架 / 本地沙箱 / 发布。
+
+#### `adep widget init`
+
+```bash
+adep widget init my-widget                 # 默认 vue3-ts 模板
+adep widget init my-widget -t react-ts     # 或 react-ts
+```
+
+widget 名称需以小写字母开头，仅含小写字母 / 数字 / 连字符。
+
+#### `adep widget dev`
+
+本地宿主沙箱：主题变量 + mock props + token 注入 + 热更新，默认 `http://127.0.0.1:8788`。
+
+```bash
+adep widget dev                  # 默认端口 8788
+adep widget dev -p 9000
+# 在浏览器打开 ?token=<...> 可注入鉴权 token
+```
+
+#### `adep widget publish`
+
+按框架构建 → 上传平台静态资源 → 版本化输出 URL：
+
+```bash
+adep widget publish -p my-app
+# → my-widget  v0.1.0  https://my-app.platform.example.com/widgets/my-widget/0.1.0/index.js
+```
+
+版本取自 widget `package.json` 的 `version`（缺省 `0.1.0`）；产物是单个 ESM 文件。
+
+---
+
+## 配置
+
+### 环境变量
+
+| 变量          | 说明                              | 缺省                    |
+| ------------- | --------------------------------- | ----------------------- |
+| `ADEP_SERVER` | 平台地址（CLI 请求的默认 server） | `http://localhost:3000` |
+| `ADEP_HOME`   | 凭据目录（测试隔离用）            | `~/.adep`               |
+
+```bash
+export ADEP_SERVER=https://platform.example.com
+export ADEP_HOME=~/.adep
+```
+
+> 也可通过 `-s` / `-e` / `-p` 等子命令参数覆盖。
+
+### `adep.config.ts`
+
+`adep init` 生成的项目标识文件，CLI 的 `dev` / `deploy` 按此识别项目：
+
+```ts
+import { defineConfig } from 'adep/config'
+
+export default defineConfig({
+  name: 'my-app', // 项目名（deploy 的默认 slug）
+  template: 'function', // 模板：empty | function
+})
+```
+
+---
+
+## 常用示例
+
+```bash
+# 登录后查看当前身份
+adep whoami
+
+# 登出并清除本地凭据
+adep logout
+
+# 列出平台可用的脚手架模板
+adep init --list
+
+# 数据库运维：启动 → 看状态 → 跑 SQL → 打快照
+adep db start
+adep db status
+adep db exec --sql "SELECT count(*) FROM users"
+adep db snapshot create
+
+# 云存储：上传 / 下载 / 删除
+adep storage upload ./logo.png --path assets/logo.png --visibility public
+adep storage download assets/logo.png -o ./logo.png
+
+# 静态托管：本地构建产物一键上线，随时拉回
+adep hosting deploy ./dist
+adep hosting pull -o ./site
+
+# 以 JSON 输出（Agent / CI 可用）
+adep --json deploy -p my-app
+```
+
+---
+
+## FAQ
+
+**Q：`adep login`** **失败提示** **`NOT_LOGGED_IN`** **/** **`SERVER_UNREACHABLE`？**
+先确认 `ADEP_SERVER`（或 `-s`）指向可访问的平台地址，再重新 `adep login`。凭据保存在 `~/.adep/credentials`（权限 `0600`）。
+
+**Q：`adep dev`** **需要 Docker / 云连接吗？**
+不需要。默认使用进程内模拟运行时（`@adep/runtime`），断网也能开发——只替换传输与持久化，不改变函数语义。
+
+**Q：本地开发与线上行为会不一致吗？**
+模拟器刻意保持执行语义一致：`cloud.db` / `cloud.storage` / `cloud.realtime` 能力装配复用线上逻辑。差异点仅限传输层与持久化层，且 `adep dev` 启动时会打印边界清单（触发器不自动执行、无跨实例广播、不在本地计量计费）。
+
+**Q：`adep deploy`** **显示** **`no changes`？**
+这是幂等设计：本地函数内容与已发布版本一致时复用当前版本，不产生新版本。想强制更新需修改函数内容。
+
+**Q：项目名 / widget 名的命名规则？**
+`init` 项目名：小写字母开头，仅含小写字母 / 数字 / 连字符（≤ 63 字符）。`widget init` 名称同规则。
+
+**Q：`adep db exec`** **的** **`--confirm-table`** **是做什么的？**
+写 / 破坏性语句（DELETE / DROP / ALTER…）服务端要求二次确认目标表名，`--confirm-table users` 即输入目标表名以放行；只读查询无需该参数。
+
+**Q：`adep storage`** **/** **`adep hosting`** **需要在平台项目目录里跑吗？**
+不需要。它们通过 `-p <slug>` 指定目标项目，缺省才读取 `adep.config.ts` 的 `name`——在任何目录下都能对指定项目做资源运维。
+
+**Q：private 文件如何下载？**
+`adep storage download` 会自动调用平台列表接口拿到服务端生成的 15 分钟签名 URL 再取回内容，无需 CLI 自行签发签名；公网访问同样走该 URL。
+
+**Q：`--json`** **输出长什么样？**
+每个命令输出一个 JSON 对象：成功 `{"ok":true,"command":"...","data":{...}}`，预期内失败 `{"ok":false,"command":"...","error":{"code":"...","message":"..."}}` 且退出码为 1。
+
+---
+
+## 相关
+
+- `@adep/runtime` —— 平台运行时内核（执行器 + 本地模拟运行时 + 能力装配），`adep dev` 复用其保证本地/线上语义一致。