@adep/cli 0.0.8 → 0.1.0

package/README.md

@@ -28,11 +28,13 @@
 
    - [`adep serve`](#adep-serve)
 
-   - [`adep deploy`](#adep-deploy)
+   - [`adep publish`](#adep-publish)
+
+   - [`adep deploy`](#adep-deploy-deprecated)
 
    - [`adep projects`](#adep-projects)
 
-   - [`adep functions`](#adep-functions)
+   - [`adep functions`](#adep-functions-deprecated)
 
    - [`adep mcp`](#adep-mcp)
 
@@ -42,7 +44,7 @@
 
    - [`adep storage`](#adep-storage)
 
-   - [`adep hosting`](#adep-hosting)
+   - [`adep hosting`](#adep-hosting-deprecated)
 
    - [`adep export`](#adep-export)
 
@@ -91,11 +93,12 @@ cd my-app
 adep dev
 # → http://127.0.0.1:8787/hello
 
-# 4. 部署上线
-adep deploy
+# 4. 部署上线（全栈：函数 + 前端）
+adep publish
 ```
 
-三步即可把本地 `functions/hello.ts` 发到线上并得到公网访问地址。
+三步即可把本地 `functions/hello.ts` 与 `web/` 前端发到线上并得到公网访问地址。
+只发布函数：`adep publish --only functions`；只发布前端：`adep publish --only frontend`。
 
 ---
 
@@ -129,29 +132,51 @@ adep init --list                      # 从平台 GET /api/v1/templates 列出
 adep init --list -s https://platform.example.com
 ```
 
-产物结构（`fullstack` 模板）：
+产物结构（`fullstack` 模板，CLI-014：vite 工程根在项目根目录）：
 
 ```
 my-app/
-├── adep.config.ts      # 项目标识（dev / deploy 按此识别）
-├── tsconfig.json       # 云函数 TypeScript 编辑器配置（strict + noEmit）
-├── adep.d.ts           # 云函数上下文环境类型声明（ctx: AdepContext 补全）
+├── package.json         # 应用定义：@adep/cli + 前端依赖同根声明 + scripts（dev/build/site:deploy/serve/deploy/doctor）+ engines
+├── vite.config.ts       # vite 配置：vue 插件 + adep() 云函数插件；build.outDir = site/
+├── index.html           # vite 入口（引用 /web/src/main.ts）
+├── adep.config.ts       # 项目配置：name / template / functionsDir / functions_prefix（默认 /api）
+├── tsconfig.json        # 云函数 TypeScript 编辑器配置（strict + noEmit）
+├── adep.d.ts            # 云函数上下文环境类型声明（ctx: AdepContext 补全）
 ├── functions/
-│   ├── hello.ts        # 示例函数（deploy 后经 /hello 触发）
+│   ├── hello.ts         # 示例函数（deploy 后经 /api/hello 触发）
 │   └── README.md
-├── web/                # 前端工程（标准 Vite + Vue 3，与 Web IDE 项目同构）
-│   ├── index.html
-│   ├── package.json
-│   ├── vite.config.ts
-│   └── src/{main.ts, App.vue}
+├── web/src/             # 前端源码（Vue 3；与 Web IDE 的 web/ 工程共用同一份 src/）
+│   ├── main.ts
+│   └── App.vue
+├── site/                # vite build 构建产物（站点托管目录，adep hosting deploy site 上传；已 gitignore）
 ├── database/
-│   └── schema.sql      # 数据库结构（占位；表由平台控制台 / adep db 管理）
+│   └── schema.sql       # 数据库结构（占位；表由平台控制台 / adep db 管理）
 ├── README.md
-└── .gitignore          # 已忽略 node_modules/ data/ .adep/
+└── .gitignore           # 已忽略 node_modules/ data/ .adep/ site/
 ```
 
-**web/ 前端工程**：与 Web IDE 内创建的项目完全同构（同一份模板真相源），可无缝在两端切换开发；
-本地跑前端：`cd web && npm install && npm run dev`，部署由 `adep deploy` 统一构建发布。
+**根 package.json**：与导出的离线部署包（`adep export` / 平台自托管导出）的应用定义同构——
+声明 `@adep/cli` 版本依赖（值来自 CLI 自身发布版本，不硬编码）与常用 scripts：
+`pnpm dev`（= `vite`，全栈开发：前端 HMR + 云函数代理）/ `pnpm build`（= `vite build` → `site/`）/
+`pnpm site:deploy`（= `adep hosting deploy site --spa`）/ `pnpm serve` / `pnpm deploy` / `pnpm doctor`。
+
+**全栈开发（vite + 云函数代理）**：`pnpm dev` 启动 vite 后，`@adep/cli/vite` 插件在 vite 进程内
+启动 `adep dev`（模拟运行时，函数热重载 / .env.local / cloud.* 全可用），并把
+`/{functions_prefix}/*` 请求代理到云函数——默认前缀 `/api`（与线上函数路由对齐），
+前端 `fetch('/api/hello')` 即调用 `functions/hello.ts`。
+
+**functions_prefix（云函数路由前缀）**：`adep.config.ts` 的 `functions_prefix`（**默认 `/api`**）：
+
+- `adep dev` 访问路径 `/{prefix}/{fnName}`（如 `/api/hello`）；vite 插件按同一前缀代理。
+- `adep serve` 为 `/api/{prefix}/{fnName}`（前缀拼接在 `/api/` 之后）。
+- 留空（旧项目）：`adep dev` 为 `/{fnName}`，`adep serve` 为 `/api/{fnName}`；
+  vite 插件在配置为空时强制 `/api` 并同步覆盖 dev 路由，保证代理与路由一致。
+- **边界**：只影响本地 HTTP 入口路由；函数互调 `ctx.cloud.invoke('name')` 与线上部署路径
+  按函数名，不随前缀变化（与线上同构）。
+
+**前端源码（web/src/）**：与 Web IDE 内 `web/` 工程的 `src/` 完全同构（同一份模板真相源）；
+vite 工程根在项目根目录（`vite.config.ts` / `index.html` / 根 `package.json`），构建产物输出到
+`site/`（站点托管目录），`pnpm site:deploy` 上传部署。
 
 **类型提示**：`adep init` 产出的项目自带 `tsconfig.json` 与 `adep.d.ts`，用 VSCode 打开即可在
 `functions/` 下获得 `AdepContext` / `ctx.cloud.*` 补全，无需本机安装 `@adep/types`。
@@ -202,7 +227,40 @@ adep serve --static web          # 指定静态托管目录（缺省 public/）
 
 - 绑定非回环地址时给出对外暴露警告（它不带生产级加固）。
 
-### `adep deploy`
+### `adep publish`
+
+全栈发布顶层命令（CLI-010）：函数部署 + 前端构建托管一把梭。
+
+```bash
+adep publish                          # 缺省全栈：函数 deploy + 前端平台侧构建托管
+adep publish --only functions         # 只发布云函数
+adep publish --only frontend          # 只触发平台侧前端构建（FN-024）并切换站点版本
+adep publish -p my-app                # 显式指定目标 slug
+```
+
+- **函数部分**：扫描本地 `functions/` 计算内容哈希 → 调平台 `/api/v1/deploy/diff` 拿差异清单 →
+  仅上传变更函数 → 发布 → 输出访问域名（与 `adep deploy` 同一管线）。
+
+- **前端部分**：调平台 `POST /api/v1/projects/:id/frontend/publish`（服务端真实构建 `web/` 草稿），
+  再读 `/frontend/versions` 取当前版本与 `siteUrl`。未登录由 `createClient` 统一抛 `NOT_LOGGED_IN`。
+
+- 成功输出每个函数的名字 / 版本 / 访问地址，末尾汇总函数部署数 + 前端构建状态 + 站点 URL：
+
+```bash
+hello  v1  https://my-app.platform.example.com/api/hello
+✓ 1 functions deployed in 3.2s
+✓ frontend built v2 · https://my-app.platform.example.com
+```
+
+- `--json` 输出统一信封 `{ ok, command, data: { scope, functions?, frontend? } }`。
+
+> 兼容别名：`adep deploy` / `adep functions deploy` / `adep hosting deploy` 保留原行为，
+> 仅在 stderr 打印 deprecation 提示指向本命令（见下文）。
+
+### `adep deploy`（deprecated）
+
+> **已废弃**：推荐使用 `adep publish`（全栈）或 `adep publish --only functions`（仅函数）。
+> 本命令保留向后兼容，运行时在 stderr 打印迁移提示。
 
 增量部署：扫描本地 `functions/` 计算内容哈希 → 调平台 `/api/v1/deploy/diff` 拿差异清单 → 仅上传变更函数 → 发布 → 输出访问域名。
 
@@ -242,13 +300,16 @@ adep projects info game-arcade              # id \t slug \t name \t url
 
 - 未登录 / 会话失效 → 打印错误后附带 `提示：先执行 adep login`。
 
-### `adep functions`
+### `adep functions`（deprecated）
+
+> **`functions deploy` 已废弃**：推荐使用 `adep publish --only functions`（或 `adep publish --only functions -- <dir>` 等价语义）。
+> `functions list` / `functions logs` 保留不变。
 
 云函数子命令组：部署（可指定目录）/ 列出 / 查日志。
 
 ```bash
-adep functions deploy ./handlers            # 覆盖 adep.config.ts 的 functionsDir
-adep functions deploy                       # 等价于 adep deploy
+adep functions deploy ./handlers            # 覆盖 adep.config.ts 的 functionsDir（deprecated）
+adep functions deploy                       # 等价于 adep deploy（deprecated）
 adep functions list -p my-app               # name \t 访问地址
 adep functions logs hello -p my-app --tail 50
 ```
@@ -334,14 +395,18 @@ adep storage rm avatars/a.png
 
 - 所有命令都支持 `-p <slug>` 指定项目。
 
-### `adep hosting`
+### `adep hosting`（deprecated）
+
+> **`hosting deploy` 已废弃**：推荐使用 `adep publish --only frontend`（平台侧构建 `web/` 草稿）。
+> 如确需上传预构建目录（如本地 `vite build` 产物），`hosting deploy <dir>` 仍可用，仅 stderr 提示迁移。
+> `hosting info` / `pull` / `config` 保留（运维类操作不并入 publish）。
 
 静态托管子命令组：查看 / 部署 / 拉取 / 配置。站点文件即项目桶 `site/` 前缀下的 public 文件。
 
 ```bash
 adep hosting info                        # 查看托管配置、站点地址与文件树
-adep hosting deploy ./dist               # 递归上传目录到 site/ 并打开托管
-adep hosting deploy ./dist --spa         # 同时启用 SPA 回退（无匹配静态文件回 index.html）
+adep hosting deploy ./dist               # 递归上传目录到 site/ 并打开托管（deprecated）
+adep hosting deploy ./dist --spa         # 同时启用 SPA 回退（deprecated）
 adep hosting pull [-o ./site]            # 拉取站点公开文件到本地（跳过 private 托管配置）
 adep hosting config --enabled true --spa true    # 更新托管开关 / SPA 回退（幂等）
 ```
@@ -384,16 +449,23 @@ export ADEP_HOME=~/.adep
 
 ### `adep.config.ts`
 
-`adep init` 生成的项目标识文件，CLI 的 `dev` / `deploy` 按此识别项目（CLI 直接 import 后读 `default` 的字段，无需任何辅助包）：
+`adep init` 生成的项目配置文件，CLI 的 `dev` / `serve` / `deploy` 按此识别项目（CLI 直接 import 后读 `default` 的字段，无需任何辅助包）：
 
 ```ts
-// adep 项目配置：CLI（dev / deploy）按 default export 读取（name / functionsDir）。
+// adep 项目配置：CLI（dev / serve / deploy）与云函数 vite 插件按 default export 读取。
 export default {
   name: 'my-app', // 项目名（deploy 的默认 slug）
   template: 'fullstack', // 模板：empty | function | fullstack
+  functionsDir: 'functions', // 云函数目录
+  functions_prefix: '/api', // 云函数路由前缀（默认 /api，与线上 /api/{fn} 对齐）
 }
 ```
 
+- `functionsDir`：云函数目录（`dev` / `serve` / `deploy` 读取，缺省 `functions/`）。
+- `functions_prefix`：**影响本地路由与 vite 插件代理前缀**（见上方 `adep init` 产物结构说明）——
+  默认 `/api`：`adep dev` 访问 `/{prefix}/{fnName}`、`adep serve` 访问 `/api/{prefix}/{fnName}`、
+  vite 插件按 `/{prefix}/*` 代理；函数互调与线上部署路径不随前缀变化。
+
 ---
 
 ## 常用示例
@@ -419,11 +491,11 @@ 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 deploy ./dist        # deprecated：推荐 adep publish --only frontend
 adep hosting pull -o ./site
 
 # 以 JSON 输出（Agent / CI 可用）
-adep --json deploy -p my-app
+adep --json publish -p my-app
 ```
 
 ---