esa-cli 1.0.10 → 1.0.11

package/README.md

@@ -1,6 +1,13 @@
-# Install/Update ESA CLI
+# Alibaba Cloud ESA CLI
 
-ESA CLI is a command-line tool for building with Alibaba Cloud ESA Functions and Pages.
+[![npm version](https://img.shields.io/npm/v/esa-cli?style=flat-square)](https://www.npmjs.com/package/esa-cli)
+[![CI](https://img.shields.io/github/actions/workflow/status/aliyun/alibabacloud-esa-cli/main.yml?style=flat-square&label=CI)](https://github.com/aliyun/alibabacloud-esa-cli/actions/workflows/main.yml)
+![Node.js](https://img.shields.io/badge/Node.js-18%20%7C%2020%20%7C%2022-3c873a?style=flat-square)
+[![TypeScript](https://img.shields.io/badge/TypeScript-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+
+ESA CLI is a command-line tool for building, developing, and deploying [Alibaba Cloud ESA](https://www.alibabacloud.com/help/en/edge-security-acceleration/esa/user-guide/what-is-er/) Functions & Pages projects.
+
+It helps you create projects from templates, run Functions & Pages locally, package static assets and edge functions, publish code versions, deploy to staging or production, and manage domains, routes, and deployments from your terminal.
 
 <p>
   <a href="https://discord.gg/BxcRVEeh">
@@ -9,54 +16,231 @@ ESA CLI is a command-line tool for building with Alibaba Cloud ESA Functions and
   <a href="https://discord.gg/SHYe5926" style="margin-left:8px;">
     <img alt="Discord EN" src="https://img.shields.io/badge/Discord-English-5865F2?logo=discord&logoColor=white" />
   </a>
- </p>
+</p>
+
+[Get started](#getting-started) • [Configuration](#configuration) • [Commands](#commands) • [Development](#development) • [Resources](#resources)
 
-## Install ESA CLI
+## Features
 
-### Prerequisites
+- **Project scaffolding**: initialize React, Vue, Next.js static export, Astro, and React Router projects with ESA-ready configuration.
+- **Local development**: run a local ESA-compatible server with automatic rebuilds, local upstream proxying, mock KV, and cache support.
+- **Static + dynamic deployments**: deploy static Pages, edge functions, or hybrid Functions & Pages projects.
+- **Versioned releases**: create code versions with `commit`, deploy existing versions, or split traffic between two versions by percentage.
+- **Account operations**: login with AK/SK or STS credentials, list projects and sites, and manage custom domains and routes.
+- **Bilingual CLI**: switch the CLI language between English and Simplified Chinese.
 
-- Node.js: 20.x or higher (supports 20.x, 22.x)
-- OS: macOS (x86, Apple Silicon), Linux
-- Recommended to use a Node version manager like Volta or nvm to avoid permission issues and easily switch Node.js versions.
+## Prerequisites
+
+- Node.js 20 or newer is recommended. CI currently covers Node.js 18.x, 20.x, and 22.x.
+- npm, pnpm, yarn, or Bun for installing the package.
+- An Alibaba Cloud account with ESA Functions & Pages access.
+
+> [!TIP]
+> For team projects, install `esa-cli` as a dev dependency so everyone runs the same CLI version.
 
 ## Installation
 
-To ensure consistent collaboration across your team, we recommend installing `esa-cli` as a dev dependency in your project. This helps everyone use the same version.
+Install locally in your project:
 
 ```bash
 npm i -D esa-cli@latest
 ```
 
-Alternatively, install globally to use the `esa-cli` command system-wide:
+Or install globally:
 
 ```bash
 npm i -g esa-cli@latest
 ```
 
-> [!TIP]
-> When `esa-cli` is not previously installed, `npx` will fetch and run the latest version from the registry.
-
-## Check your ESA CLI version
+The package exposes both `esa-cli` and the shorter `esa` command after installation.
 
-**To check your ESA CLI version, run:**
+Check the installed version:
 
 ```bash
 npx esa-cli --version
-# or
 npx esa-cli -v
 ```
 
-## Update ESA CLI
+## Getting Started
+
+### 1. Authenticate
 
-**To update ESA CLI to the latest version, run:**
+Run the interactive login flow:
 
 ```bash
-npm i -D esa-cli@latest
+npx esa-cli login
+```
+
+You can also pass credentials directly:
+
+```bash
+npx esa-cli login --access-key-id <ACCESS_KEY_ID> --access-key-secret <ACCESS_KEY_SECRET>
+```
+
+For temporary credentials, pass an STS token:
+
+```bash
+npx esa-cli login --sts-token "AccessKeyId,AccessKeySecret,SecurityToken"
+```
+
+Environment variables are supported:
+
+```bash
+export ALIBABA_CLOUD_ACCESS_KEY_ID=<ACCESS_KEY_ID>
+export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<ACCESS_KEY_SECRET>
+export ALIBABA_CLOUD_SECURITY_TOKEN=<SECURITY_TOKEN>
+npx esa-cli login
+```
+
+The legacy `ESA_ACCESS_KEY_ID`, `ESA_ACCESS_KEY_SECRET`, and `ESA_SECURITY_TOKEN` variables remain supported as fallbacks. When both forms are set, the standard `ALIBABA_CLOUD_*` variables take precedence.
+
+### 2. Create a Project
+
+Create a new ESA-ready application from a template:
+
+```bash
+npx esa-cli init my-esa-app
+cd my-esa-app
+```
+
+You can also make the template choice explicit:
+
+```bash
+npx esa-cli init my-esa-app --framework react --language typescript
 ```
 
-## Related Documentation
+### 3. Develop Locally
+
+Start the local development server:
+
+```bash
+npx esa-cli dev
+```
+
+Use a custom port or local upstream when needed:
+
+```bash
+npx esa-cli dev --port 18080 --local-upstream https://example.com
+```
+
+### 4. Commit and Deploy
+
+Create a code version without deploying it:
+
+```bash
+npx esa-cli commit --description "Prepare release"
+```
+
+Deploy the current project:
+
+```bash
+npx esa-cli deploy --description "Initial release"
+```
+
+Deploy an existing version:
+
+```bash
+npx esa-cli deploy --version <VERSION_ID> --environment production
+```
+
+Split traffic between two versions:
+
+```bash
+npx esa-cli deploy --versions v1:80,v2:20 --environment production
+```
+
+## Configuration
+
+ESA CLI looks for `esa.jsonc` or `esa.toml` from the current directory upward. `esa.jsonc` is recommended for new projects.
+
+```jsonc
+{
+  "name": "my-esa-app",
+  "description": "My ESA Functions & Pages project",
+  "entry": "./src/index.ts",
+  "assets": {
+    "directory": "./dist",
+    "notFoundStrategy": "singlePageApplication"
+  },
+  "dev": {
+    "port": 18080,
+    "localUpstream": "https://example.com"
+  }
+}
+```
+
+You can configure only `entry` for an edge function, only `assets.directory` for static Pages, or both for a hybrid project.
+
+> [!NOTE]
+> If both a function entry and `assets.notFoundStrategy` are configured, navigation requests are handled by the static fallback strategy instead of the function entry.
+
+See the [ESA Configuration Guide](https://github.com/aliyun/alibabacloud-esa-cli/blob/master/docs/Config_en.md) for all fields and examples.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `esa-cli init [name]` | Create a new project from framework templates. |
+| `esa-cli login` | Authenticate with AK/SK, STS token, or supported environment variables. |
+| `esa-cli dev [entry]` | Start a local server for Functions & Pages development. |
+| `esa-cli commit [entry]` | Package code and assets, then save them as a new version. |
+| `esa-cli deploy [entry]` | Generate or select a version and deploy it to staging, production, or both. |
+| `esa-cli deployments list` | List code versions for the current Functions & Pages project. |
+| `esa-cli deployments delete` | Delete one or more code versions. |
+| `esa-cli project list` | List Functions & Pages projects in the current account. |
+| `esa-cli project delete` | Delete a Functions & Pages project. |
+| `esa-cli site list` | List activated ESA sites. |
+| `esa-cli domain add/list/delete` | Manage custom domain bindings. |
+| `esa-cli route add/list/delete` | Manage route bindings for activated sites. |
+| `esa-cli config --local/--global` | Edit local project or global CLI configuration. |
+| `esa-cli lang` | Switch CLI language. |
+
+For the full option reference, see [ESA CLI Commands](https://github.com/aliyun/alibabacloud-esa-cli/blob/master/docs/Commands_en.md).
+
+## Development
+
+Clone the repository and install dependencies:
+
+```bash
+git clone git@github.com:aliyun/alibabacloud-esa-cli.git
+cd alibabacloud-esa-cli
+npm install
+```
+
+Build the CLI:
+
+```bash
+npm run build
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Useful scripts:
+
+| Script | Description |
+| --- | --- |
+| `npm run dev` | Run TypeScript in watch mode. |
+| `npm run build` | Generate locale files, compile TypeScript, and copy runtime assets into `dist`. |
+| `npm test` | Run Vitest with coverage. |
+| `npm run lint` | Run ESLint on `src`. |
+| `npm run lint:fix` | Run ESLint with automatic fixes. |
+
+## Troubleshooting
+
+- Run commands with `--debug` to print more detailed logs where supported.
+- Use `--skip-update-check` or `ESA_NO_UPDATE_CHECK=1` to skip the CLI update check.
+- Set `ALIBABA_CLOUD_ESA_CLI_COMPAT_MODE` to override the CLI name shown in help, usage, and error messages when invoking ESA CLI through a compatibility wrapper.
+- If packaging fails, confirm that `entry` points to an existing file and `assets.directory` points to an existing directory.
+- If route or domain binding fails, confirm the target site is already activated under the current account.
+
+## Resources
 
-- [esa-cli command](./docs/Commands_en.md)
-- [ESA Configuration Guide](./docs/Config_en.md)
+- [ESA CLI Commands](https://github.com/aliyun/alibabacloud-esa-cli/blob/master/docs/Commands_en.md)
+- [ESA Configuration Guide](https://github.com/aliyun/alibabacloud-esa-cli/blob/master/docs/Config_en.md)
 - [Alibaba Cloud ESA Documentation](https://www.alibabacloud.com/help/en/edge-security-acceleration/esa/user-guide/what-is-er/)
 - [Functions and Pages API Reference](https://www.alibabacloud.com/help/en/edge-security-acceleration/esa/user-guide/api-documentation/)
+- [中文文档](./zh_CN.md)

package/bin/enter.cjs

@@ -3,6 +3,38 @@ const fs = require('fs');
 const spawn = require('cross-spawn');
 const path = require('path');
 
+const getRuntimeNodePath = () => {
+  const nodePaths = new Set();
+  const launcherDirs = [
+    __dirname,
+    process.argv[1] ? path.dirname(process.argv[1]) : undefined
+  ].filter(Boolean);
+
+  for (const launcherDir of launcherDirs) {
+    const pnpmNodeModules = path.resolve(
+      launcherDir,
+      '..',
+      '..',
+      '.pnpm',
+      'node_modules'
+    );
+
+    if (fs.existsSync(pnpmNodeModules)) {
+      nodePaths.add(pnpmNodeModules);
+    }
+  }
+
+  if (process.env.NODE_PATH) {
+    for (const nodePath of process.env.NODE_PATH.split(path.delimiter)) {
+      if (nodePath) {
+        nodePaths.add(nodePath);
+      }
+    }
+  }
+
+  return nodePaths.size > 0 ? Array.from(nodePaths).join(path.delimiter) : '';
+};
+
 const main = () => {
   let entryPath;
   if (fs.existsSync(path.join(__dirname, '../dist/index.js'))) {
@@ -13,29 +45,30 @@ const main = () => {
     throw new Error('Neither dist/index.js nor index.js could be found.');
   }
 
+  const nodePath = getRuntimeNodePath();
+
   return spawn(
     process.execPath,
     ['--no-warnings', ...process.execArgv, entryPath, ...process.argv.slice(2)],
     {
-      stdio: [0, 1, 2, 'ipc'],
+      stdio: 'inherit',
       env: {
-        ...process.env
+        ...process.env,
+        ...(nodePath ? { NODE_PATH: nodePath } : {})
       }
     }
   )
     .on('error', (err) => {
       console.log('Get Error', err);
     })
-    .on('message', (msg) => {
-      // console.log('Get Message', msg);
-      process.send && process.send(msg);
-    })
-    .on('disconnect', () => {
-      // console.log('Get disconnect');
-      process.disconnect && process.disconnect();
-    })
-    .on('exit', (code) => {
-      process.exit && process.exit(code);
+    .on('exit', (code, signal) => {
+      if (code !== null) {
+        process.exit(code);
+      } else if (signal) {
+        process.kill(process.pid, signal);
+      } else {
+        process.exit(1);
+      }
     });
 };
 

package/dist/bin/enter.cjs

@@ -3,6 +3,38 @@ const fs = require('fs');
 const spawn = require('cross-spawn');
 const path = require('path');
 
+const getRuntimeNodePath = () => {
+  const nodePaths = new Set();
+  const launcherDirs = [
+    __dirname,
+    process.argv[1] ? path.dirname(process.argv[1]) : undefined
+  ].filter(Boolean);
+
+  for (const launcherDir of launcherDirs) {
+    const pnpmNodeModules = path.resolve(
+      launcherDir,
+      '..',
+      '..',
+      '.pnpm',
+      'node_modules'
+    );
+
+    if (fs.existsSync(pnpmNodeModules)) {
+      nodePaths.add(pnpmNodeModules);
+    }
+  }
+
+  if (process.env.NODE_PATH) {
+    for (const nodePath of process.env.NODE_PATH.split(path.delimiter)) {
+      if (nodePath) {
+        nodePaths.add(nodePath);
+      }
+    }
+  }
+
+  return nodePaths.size > 0 ? Array.from(nodePaths).join(path.delimiter) : '';
+};
+
 const main = () => {
   let entryPath;
   if (fs.existsSync(path.join(__dirname, '../dist/index.js'))) {
@@ -13,29 +45,30 @@ const main = () => {
     throw new Error('Neither dist/index.js nor index.js could be found.');
   }
 
+  const nodePath = getRuntimeNodePath();
+
   return spawn(
     process.execPath,
     ['--no-warnings', ...process.execArgv, entryPath, ...process.argv.slice(2)],
     {
-      stdio: [0, 1, 2, 'ipc'],
+      stdio: 'inherit',
       env: {
-        ...process.env
+        ...process.env,
+        ...(nodePath ? { NODE_PATH: nodePath } : {})
       }
     }
   )
     .on('error', (err) => {
       console.log('Get Error', err);
     })
-    .on('message', (msg) => {
-      // console.log('Get Message', msg);
-      process.send && process.send(msg);
-    })
-    .on('disconnect', () => {
-      // console.log('Get disconnect');
-      process.disconnect && process.disconnect();
-    })
-    .on('exit', (code) => {
-      process.exit && process.exit(code);
+    .on('exit', (code, signal) => {
+      if (code !== null) {
+        process.exit(code);
+      } else if (signal) {
+        process.kill(process.pid, signal);
+      } else {
+        process.exit(1);
+      }
     });
 };
 

package/dist/commands/commit/index.js

@@ -47,8 +47,8 @@ const commit = {
         });
     },
     handler: (argv) => __awaiter(void 0, void 0, void 0, function* () {
-        yield handleCommit(argv);
-        exit();
+        const success = yield handleCommit(argv);
+        exit(success ? 0 : 1);
     })
 };
 export default commit;
@@ -58,7 +58,7 @@ export function handleCommit(argv) {
         intro(`Commit an application with ESA`);
         const projectInfo = yield validateAndInitializeProject(argv === null || argv === void 0 ? void 0 : argv.name);
         if (!projectInfo)
-            return;
+            return false;
         const { projectName } = projectInfo;
         let description;
         if (argv.description) {
@@ -77,7 +77,7 @@ export function handleCommit(argv) {
         const { isSuccess } = res || {};
         if (!isSuccess) {
             logger.endSubStep('Generate version failed');
-            exit(1);
+            return false;
         }
         const codeVersion = (_b = (_a = res === null || res === void 0 ? void 0 : res.res) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.CodeVersion;
         if (!codeVersion) {
@@ -86,5 +86,6 @@ export function handleCommit(argv) {
         }
         logger.endSubStep(`Version generated: ${codeVersion}`);
         outro(`Code version ${chalk.bold(codeVersion)} generated successfully`);
+        return true;
     });
 }

package/dist/commands/deployments/delete.js

@@ -31,7 +31,7 @@ const deploymentsDelete = {
         });
     },
     handler: (argv) => __awaiter(void 0, void 0, void 0, function* () {
-        handleDeleteDeployments(argv);
+        yield handleDeleteDeployments(argv);
     })
 };
 export default deploymentsDelete;

package/dist/commands/deployments/list.js

@@ -19,7 +19,7 @@ const deploymentsList = {
     command: 'list',
     describe: `🔍 ${t('deployments_list_describe').d('List all deployments')}`,
     handler: () => __awaiter(void 0, void 0, void 0, function* () {
-        handleListDeployments();
+        yield handleListDeployments();
     })
 };
 export default deploymentsList;

package/dist/commands/dev/build.js

@@ -7,7 +7,10 @@ import esbuild from 'esbuild';
 import { lessLoader } from 'esbuild-plugin-less';
 import { getRoot } from '../../utils/fileUtils/base.js';
 import { NODE_EXTERNALS } from '../common/constant.js';
-const replacements = { cache: 'mockCache', EdgeKV: 'mockKV' };
+const replacements = {
+    cache: 'mockCache',
+    EdgeKV: 'mockKV'
+};
 const traverse = _traverse.default;
 const generator = _generator.default;
 const renameMock = {

package/dist/commands/dev/doProcess.js

@@ -8,26 +8,102 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import chalk from 'chalk';
-import { Box, Text, useApp, useInput, render } from 'ink';
-import React, { useEffect } from 'react';
 import t from '../../i18n/index.js';
 import logger from '../../libs/logger.js';
 import { checkOS, Platforms } from '../../utils/checkOS.js';
 import { getDevOpenBrowserUrl } from '../../utils/fileUtils/index.js';
 import openInBrowser from '../../utils/openInBrowser.js';
-const InteractionBox = ({ worker }) => {
-    const { exit } = useApp();
+const getShortcutSegments = (useEw2) => [
+    ['[b]', ' open a browser, '],
+    ...(!useEw2
+        ? [['[d]', ' open Devtools, ']]
+        : []),
+    ['[c]', ' clear console, '],
+    ['[x]', ' to exit']
+];
+export const formatShortcutPanel = (useEw2, columns = process.stdout.columns) => {
+    const segments = getShortcutSegments(useEw2);
+    const fullPlain = segments
+        .map(([key, description]) => key + description)
+        .join('');
+    const shouldStack = Boolean(columns && fullPlain.length + 4 > columns);
+    const rows = shouldStack
+        ? segments.map(([key, description]) => ({
+            plain: key + description,
+            styled: chalk.bold(key) + description
+        }))
+        : [
+            {
+                plain: fullPlain,
+                styled: segments
+                    .map(([key, description]) => chalk.bold(key) + description)
+                    .join('')
+            }
+        ];
+    const innerWidth = Math.max(...rows.map(({ plain }) => plain.length));
+    const border = `+${'-'.repeat(innerWidth + 2)}+`;
+    return [
+        border,
+        ...rows.map(({ plain, styled }) => `| ${styled}${' '.repeat(innerWidth - plain.length)} |`),
+        border
+    ];
+};
+const printShortcutPanel = (useEw2) => {
+    formatShortcutPanel(useEw2).forEach((line) => logger.log(line));
+};
+/**
+ * Keyboard shortcut panel for `dev` mode, implemented with raw stdin
+ * (previously an ink component). Returns the same shape as before:
+ * `{ devElement: { waitUntilExit }, exit }`.
+ */
+const doProcess = (worker) => {
     const inspectLink = chalk.underline.blue('chrome://inspect/#devices');
     const remoteTarget = chalk.blue('Remote Target');
     const inspect = chalk.blue('inspect');
     const OS = checkOS();
-    const useEw2 = OS === Platforms.AppleArm || Platforms.AppleIntel || Platforms.LinuxX86;
-    /* eslint-disable no-unused-vars */
-    useInput((input) => __awaiter(void 0, void 0, void 0, function* () {
+    const useEw2 = [
+        Platforms.AppleArm,
+        Platforms.AppleIntel,
+        Platforms.LinuxX86
+    ].includes(OS);
+    printShortcutPanel(useEw2);
+    let resolveExit;
+    const exitPromise = new Promise((resolve) => {
+        resolveExit = resolve;
+    });
+    let exited = false;
+    const cleanup = () => {
+        process.stdin.off('data', onData);
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(false);
+        }
+        process.stdin.pause();
+        if (worker) {
+            worker.stop();
+        }
+    };
+    const exit = () => {
+        if (exited)
+            return;
+        exited = true;
+        cleanup();
+        resolveExit();
+        setTimeout(() => {
+            process.exit(0);
+        }, 500);
+    };
+    const onData = (data) => __awaiter(void 0, void 0, void 0, function* () {
+        const input = data.toString();
+        // Ctrl+C
+        if (input === '\u0003') {
+            exit();
+            return;
+        }
         switch (input.toLowerCase()) {
             case 'c':
                 console.clear();
                 logger.block();
+                printShortcutPanel(useEw2);
                 break;
             case 'b': {
                 yield openInBrowser(getDevOpenBrowserUrl());
@@ -46,36 +122,18 @@ const InteractionBox = ({ worker }) => {
             default:
                 break;
         }
-    }));
-    useEffect(() => {
-        return () => {
-            if (worker) {
-                worker.stop();
-            }
-        };
-    }, []);
-    return (React.createElement(React.Fragment, null,
-        React.createElement(Box, { borderStyle: "classic", paddingLeft: 1, paddingRight: 1 },
-            React.createElement(Text, { bold: true }, "[b]"),
-            React.createElement(Text, null, " open a browser, "),
-            !useEw2 ? (React.createElement(React.Fragment, null,
-                React.createElement(Text, { bold: true }, "[d]"),
-                React.createElement(Text, null, " open Devtools, "))) : null,
-            React.createElement(Text, { bold: true }, "[c]"),
-            React.createElement(Text, null, " clear console, "),
-            React.createElement(Text, { bold: true }, "[x]"),
-            React.createElement(Text, null, " to exit"))));
-};
-const doProcess = (worker) => {
-    const devElement = render(React.createElement(InteractionBox, { worker: worker }));
+    });
+    if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true);
+    }
+    process.stdin.setEncoding('utf8');
+    process.stdin.resume();
+    process.stdin.on('data', onData);
     return {
-        devElement,
-        exit: () => {
-            devElement.unmount();
-            setTimeout(() => {
-                process.exit(0);
-            }, 500);
-        }
+        devElement: {
+            waitUntilExit: () => exitPromise
+        },
+        exit
     };
 };
 export default doProcess;

package/dist/commands/domain/add.js

@@ -41,7 +41,7 @@ const addDomain = {
         });
     },
     handler: (argv) => __awaiter(void 0, void 0, void 0, function* () {
-        handleAddDomain(argv);
+        yield handleAddDomain(argv);
     })
 };
 export default addDomain;

package/dist/commands/domain/delete.js

@@ -17,15 +17,14 @@ const deleteDomain = {
     command: 'delete <domain>',
     describe: `🗑  ${t('domain_delete_describe').d('Delete a related domain')}`,
     builder: (yargs) => {
-        return yargs.positional('domains', {
+        return yargs.positional('domain', {
             describe: t('domain_delete_positional_describe').d('The names of the related domains to delete'),
             type: 'string',
-            array: true,
             demandOption: true
         });
     },
     handler: (argv) => __awaiter(void 0, void 0, void 0, function* () {
-        handleDeleteDomain(argv);
+        yield handleDeleteDomain(argv);
     })
 };
 export default deleteDomain;