esa-cli 0.0.2-beta.9 → 1.0.0

package/dist/docs/Commands_zh_CN.md

@@ -1,224 +1,272 @@
-# Commands
+## 命令一览
 
-### init
+### esa-cli init [name]
 
-选择模版初始化项目。
+初始化一个函数和Pages项目（支持框架或模板）。
 
 ```bash
-$ esa init [OPTIONS]
+esa-cli init [name]
 ```
 
-- -c, --config `boolean` `optional`
-- 在您的项目中生成一个esa.toml配置文件。
+- 位置参数：
+  - name：项目名
 
-### routine [script]
+- 选项：
+  - -f, --framework string：选择前端框架（react/vue/nextjs...）
+  - -l, --language string：选择语言（typescript/javascript）。可选：typescript | javascript
+  - -t, --template string：指定模板名称
+  - -y, --yes boolean：对所有交互询问选择“是”（默认 false），模版采用helloworld
+  - --git boolean：在项目中初始化 git
+  - --deploy boolean：初始化完成后自动部署
 
-管理边缘函数。
+---
 
-#### delete <routineName>
+### esa-cli dev [entry]
 
-删除一个边缘函数。
+启动本地开发服务器。
 
 ```bash
-$ esa routine delete <routineName>
+esa-cli dev [entry]
 ```
 
-- routineName `string` `required`
-- 要删除的边缘函数名称。
+- 位置参数：
+  - entry：函数和Pages入口文件
 
-#### list
+- 选项：
+  - -p, --port number：监听端口
+  - -m, --minify boolean：开发模式下压缩代码（默认 false）
+  - --refresh-command string：保存自动刷新前执行的命令
+  - --local-upstream string：在本地开发中作为源站的主机
+  - --debug boolean：输出调试日志（默认 false）
 
-查看所有边缘函数。
+---
+
+### esa-cli commit [entry]
+
+提交代码并保存为新版本。
 
 ```bash
-$ esa routine list
+esa-cli commit [entry]
 ```
 
-### route [script]
+- 选项：
+  - -m, --minify boolean：提交前压缩代码（默认 false）
+  - -a, --assets string：静态资源目录
+  - -d, --description string：版本/例程描述（跳过交互输入）
+  - -n, --name string：函数和Pages名称
 
-管理绑定到边缘函数的路由。
+---
 
-#### add [route] [site]
+### esa-cli deploy [entry]
 
-将路由绑定到边缘函数。
+生成一个代码版本，并同时部署项目到仿真和线上环境
 
 ```bash
-$ esa route add [route] [site]
+esa-cli deploy [entry]
 ```
 
-#### delete <route>
+- 选项：
+  - entry 可选参数，默认以 `esa.jsonc`中entry配置为准
+  - -v, --version string：指定要部署的版本（跳过交互选择）
+  - -e, --environment string：部署环境。可选：staging | production
+  - -n, --name string：函数和Pages名称
+  - -a, --assets string：静态资源目录（例如：./dist）
+  - -d, --description string：版本描述
+  - -m, --minify boolean：是否压缩代码
+
+---
 
-删除一个绑定路由。
+### esa-cli deployments list
+
+列出当前函数和Pages下所有代码版本。
 
 ```bash
-$ esa route delete <route>
+esa-cli deployments list
 ```
 
-- route `string` `required`
-- 要删除的路由名称。
+无额外选项。
+
+---
 
-#### list
+### esa-cli deployments delete [deploymentId...]
 
-查看所有绑定路由。
+删除当前函数和Pages的一个或多个代码版本。
 
 ```bash
-$ esa route list
+esa-cli deployments delete [deploymentId...]
 ```
 
-### login
-
-登录。
+- 位置参数：
+  - deploymentId...：要删除的部署版本ID（可一次传多个）
 
-```bash
-$ esa login
-```
+---
 
-### dev [entry]
+### esa-cli project list
 
-启动本地调试。
+列出账号下所有的函数和Pages。
 
 ```bash
-$ esa dev [entry] [OPTIONS]
+esa-cli project list
 ```
 
-- entry `string` `optional`
-- 入口文件路径。
+无额外选项。
 
-- -port, --p `number` `optional`
-- 监听端口。
+---
 
-- --inspect-port `number` `optional`
-- 用于 Chrome inspect 调试工具的端口。
+### esa-cli project delete <projectName>
 
-- -minify, --m `boolean` `optional`
-- 开发打包时压缩代码。
+删除指定函数和Pages。
+
+```bash
+esa-cli project delete <projectName>
+```
 
-- --local-upstream `string` `optional`
-- 在开发时作为源站的域名。
+- 位置参数：
+  - projectName：要删除的函数或Pages名称
 
-- --refresh-command `string` `optional`
-- 提供一个在保存自动刷新前执行的命令。
+---
 
-### deploy [entry]
+### esa-cli site list
 
-部署您的项目。
+列出账号下所有已激活站点。
 
 ```bash
-$ esa deploy [entry]
+esa-cli site list
 ```
 
-- entry `string` `optional`
-- 入口文件路径。
+无额外选项。
 
-### domain [script]
+---
 
-管理绑定到边缘函数的域名。
+### esa-cli domain add <domain>
 
-#### add <domain>
-
-绑定域名到边缘函数。
+绑定域名到当前函数和Pages。
 
 ```bash
-$ esa domain add <domain>
+esa-cli domain add <domain>
 ```
 
-- domain `string` `required`
-- 需要添加的域名。
+- 位置参数：
+  - domain：要绑定的域名
+
+---
 
-#### delete <domain>
+### esa-cli domain list
 
-删除一个绑定域名。
+查看当前函数和Pages所有已绑定域名。
 
 ```bash
-$ esa domain delete <domain>
+esa-cli domain list
 ```
 
-- domains `string` `required`
-- 要删除的绑定域名。
+无额外选项。
+
+---
 
-#### list
+### esa-cli domain delete <domain>
 
-查看所有绑定域名。
+删除当前函数和Pages下已绑定域名。
 
 ```bash
-$ esa domain list
+esa-cli domain delete <domain>
 ```
 
-### deployments [script]
+- 位置参数：
+  - domain：要删除绑定的域名
 
-管理您的部署。
+---
 
-#### delete <deploymentId>
+#### esa-cli route add
 
-删除一个部署版本。
+为当前函数和Pages绑定一个路由。
 
 ```bash
-$ esa deployments delete <deploymentId>
+esa-cli route add [route] [site] [--alias <routeName>] [--route <route>] [--site <site>]
 ```
 
-- deploymentId `string` `required`
-- 要删除的部署版本ID。
+- 位置参数（可选）：
+  - route：路由值，例如：example.com/_ 或 _.example.com/\*
+  - site：站点名称，例如：example.com
 
-#### list
+- 选项：
+  - -r, --route string：路由值，例如：example.com/\*
+    - 主机名支持以 `*` 开头表示后缀匹配（如：`*.example.com`）
+    - 路径支持以 `*` 结尾表示前缀匹配（如：`/api/*`）
+  - -s, --site string：站点名称（需为已激活站点）
+  - -a, --alias string：路由名称（别名） 例如：apple、orange等
 
-查看所有部署。
+---
+
+### esa-cli route list
+
+查看函数和Pages所有已绑定路由。
 
 ```bash
-$ esa deployments list
+esa-cli route list
 ```
 
-### commit [entry]
+无额外选项。
+
+---
 
-提交代码，保存为一个版本。
+### esa-cli route delete <routeName>
+
+删除函数和Pages下已绑定路由。
 
 ```bash
-$ esa commit [entry] [OPTIONS]
+esa-cli route delete <routeName>
 ```
 
-- entry `string` `optional`
-- 入口文件路径。
+- 位置参数：
+  - routeName：要删除的路由名称
 
-- -m, --minify `boolean` `optional`
-- 上传前压缩代码。
+---
 
-### logout
+### esa-cli login
 
-注销登录。
+登录。
 
 ```bash
-$ esa logout
+esa-cli login
 ```
 
-### config
+- 选项：
+  - --access-key-id, --ak string：AccessKey ID (AK)
+  - --access-key-secret, --sk string：AccessKey Secret (SK)
+- 从环境变量中读取process.env
+  - ESA_ACCESS_KEY_ID
+  - ESA_ACCESS_KEY_SECRET
+
+---
 
-使用 -l 或 -g 修改本地或全局配置。
+### esa-cli logout
+
+退出登录。
 
 ```bash
-$ esa config [OPTIONS]
+esa-cli logout
 ```
 
-- -g, --global `boolean` `optional`
-- 编辑全局配置文件。
-
-- -l, --local `boolean` `optional`
-- 编辑本地配置文件。
+---
 
-### lang
+### esa-cli config [-l | -g]
 
-选择语言。
+修改本地或全局配置。
 
 ```bash
-$ esa lang
+esa-cli config [--local] [--global]
 ```
 
-### site [script]
+- 选项：
+  - -l, --local boolean：编辑本地配置文件（默认 false）
+  - -g, --global boolean：编辑全局配置文件（默认 false）
 
-管理站点。
+---
 
-#### list
+### esa-cli lang
 
-列出站点。
+设置 CLI 语言。
 
 ```bash
-$ esa site list
+esa-cli lang
 ```

package/dist/docs/Config_en.md

@@ -0,0 +1,70 @@
+## ESA Configuration Guide
+
+This document describes the structure, parameters, and example of the ESA (Edge Security Acceleration) project configuration file `esa.jsonc`, helping developers configure and manage ESA projects efficiently.
+
+## Project configuration file (esa.jsonc)
+
+`esa.jsonc` is the core configuration file of an ESA project. It defines the project name, description, dynamic function entry, static asset hosting strategy, and local development settings. Below are the details of each field.
+
+### Parameter description
+
+| **Parameter**   | **Description**                                                                                                                              |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **name**        | Target project name. If it exists, deployment goes into it; otherwise, a new project is created.                                             |
+| **description** | Project description. Optional, used to briefly document the purpose or functionality.                                                        |
+| **entry**       | Dynamic function entry file path, e.g.,`./src/index.ts`. Optional, set only when using a function.                                           |
+| **assets**      | Static asset hosting configuration (each Pages project supports only one set of static assets). Includes `directory` and `notFoundStrategy`. |
+| **dev**         | Local development configuration. Optional; used to set dev server port and proxy.                                                            |
+
+#### Field structure
+
+- **name**: `string`
+  - Project name. Required.
+- **description**: `string`
+  - Project description. Optional.
+- **entry**: `string`
+  - Dynamic function entry file path, e.g., `./src/index.ts`. Optional.
+- **assets**: `object`
+  - Static asset hosting settings. Optional. Includes:
+    - **directory**: `string`
+      - Build output directory, e.g., `./public`, `./dist`, or `./build`. The directory to be hosted statically.
+    - **notFoundStrategy?**: `string`
+      - Strategy when a request does not match any static asset. Accepted values:
+        - `singlePageApplication`: Return `index.html` from the static directory with `200 OK` (suitable for SPAs).
+        - `404Page`: Return `404.html` from the static directory with `404 Not Found`.
+- **dev**: `object`
+  - Local development settings. Optional. Includes:
+    - **port**: `number`
+      - Dev server port. Default: `18080`.
+    - **localUpstream**: `string`
+      - Local upstream proxy URL for development.
+
+> Note: If both a function script and `assets.notFoundStrategy` are configured, navigation requests will not trigger the function script. A navigation request is sent when a user directly visits a page (e.g., entering a URL or clicking a link) and includes the header `Sec-Fetch-Mode: navigate`.
+
+### JSONC example
+
+Below is a typical `esa.jsonc` example for a Vite + React single-page application:
+
+```jsonc
+{
+  "name": "vite-react-template",
+  "assets": {
+    "directory": "./dist",
+    "notFoundStrategy": "singlePageApplication"
+  },
+  "dev": {
+    "port": 18080
+  }
+}
+```
+
+#### Example notes
+
+- **name**: Sets the project name to `vite-react-template`.
+- **assets.directory**: Static asset directory is `./dist` (typical Vite build output).
+- **assets.notFoundStrategy**: `singlePageApplication` returns `index.html` when not matched (SPA-friendly).
+- **dev.port**: Dev server runs on port `18080`.
+
+### Reference
+
+- [Pages build and routing guide](https://help.aliyun.com/zh/edge-security-acceleration/esa/build-pages)

package/dist/docs/Config_zh_CN.md

@@ -0,0 +1,68 @@
+# ESA 配置文件说明
+
+本文档介绍 ESA（Edge Security Acceleration）项目的配置文件 `esa.jsonc` 的结构、参数说明及示例，旨在帮助开发者快速配置和管理 ESA 项目。
+
+## 项目配置文件（esa.jsonc）
+
+`esa.jsonc` 是 ESA 项目的核心配置文件，用于定义项目的名称、描述、入口文件、静态资源托管方式以及本地开发工具的配置。以下是配置文件中各字段的详细说明。
+
+### 参数说明
+
+| **参数**        | **说明**                                                                                             |
+| --------------- | ---------------------------------------------------------------------------------------------------- |
+| **name**        | 目标项目名称。若项目已存在，则部署到该项目；若不存在，则以此名称创建新项目。                         |
+| **description** | 项目描述，可选字段，用于简要说明项目功能或用途。                                                     |
+| **entry**       | 动态函数入口文件路径，例如 `./src/index.ts`。可选字段，用于指定动态函数的入口。                      |
+| **assets**      | 静态资源托管配置（每个 Pages 项目仅支持一组静态资源）。包含 `directory` 和 `notFoundStrategy` 字段。 |
+| **dev**         | 本地开发工具配置，可选字段，用于设置开发服务器端口和代理地址。                                       |
+
+#### 字段结构
+
+- **name**: `string`
+  - 项目名称，必填字段，用于标识项目。
+- **description**: `string`
+  - 项目描述，可选字段，用于记录项目的功能或用途。
+- **entry**: `string`
+  - 动态函数入口文件路径，例如 `./src/index.ts`。可选字段，仅在需要动态函数时配置。
+- **assets?**: `object`
+  - 静态资源托管配置，可选字段，包含以下子字段：
+    - **directory**: `string`
+      - 构建输出目录，例如 `./public`、 `./dist` 或 `./build`。指定静态资源托管的目录。
+    - **notFoundStrategy**: `string`
+      - 当请求路径未匹配到静态资源时的处理策略，可选值：
+        - `singlePageApplication`: 返回静态目录中的 `index.html`，状态码为 `200 OK`（适用于单页应用）。
+        - `404Page`: 返回静态目录中的 `404.html`，状态码为 `404 Not Found`。
+- **dev**: `object`
+  - 本地开发工具配置，可选字段，包含以下子字段：
+    - **port?**: `number`
+      - 开发服务器端口，默认值为 `18080`。
+    - **localUpstream?**: `string`
+      - 本地上游代理地址，用于本地开发时的代理设置。
+
+### JSONC 示例
+
+以下是一个典型的 `esa.jsonc` 配置文件示例，展示了如何配置一个基于 Vite 和 React 的单页应用项目：
+
+```jsonc
+{
+  "name": "vite-react-template",
+  "assets": {
+    "directory": "./dist",
+    "notFoundStrategy": "singlePageApplication"
+  },
+  "dev": {
+    "port": 18080
+  }
+}
+```
+
+#### 示例说明
+
+- **name**: 指定项目名称为 `vite-react-template`。
+- **assets.directory**: 静态资源托管目录为 `./dist`，通常是 Vite 构建后的输出目录。
+- **assets.notFoundStrategy**: 配置为 `singlePageApplication`，表示未找到资源时返回 `index.html`，适用于单页应用。
+- **dev.port**: 本地开发服务器运行在端口 `18080`。
+
+### 相关文档
+
+- [Pages 构建和路由指南](https://help.aliyun.com/zh/edge-security-acceleration/esa/build-pages)

package/dist/i18n/index.js

@@ -1,8 +1,8 @@
 import { resolve } from 'path';
-import { getCliConfig } from '../utils/fileUtils/index.js';
 import logger from '../libs/logger.js';
-import { readJson } from '../utils/readJson.js';
 import { getDirName } from '../utils/fileUtils/base.js';
+import { getCliConfig } from '../utils/fileUtils/index.js';
+import { readJson } from '../utils/readJson.js';
 const localesJson = readJson(resolve(getDirName(import.meta.url), './locales.json'));
 const t = (key, variables) => {
     var _a;