@volcengine/vefaas-cli 0.2.2-win32-x64 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.2.2] - 2026-06-08
+
+0.2.2 提升函数调试、沙箱应用、OpenAPI 调用和认证体验，面向自动化脚本与 AI Agent 场景提供更稳定的结构化能力。
+
+### Added
+
+- `vefaas api` 支持按 Action 自动解析 veFaaS v1、veFaaS v2 和 APIG API 版本，并允许通过 `--service`、`--api-version` 显式覆盖。
+- `vefaas fn invoke` 支持 APIG 形态的请求参数和 debug instance 调用，便于在没有触发器绑定的情况下直接测试函数。
+- `vefaas fn trigger apig` 和 `vefaas sandbox trigger apig` 支持绑定与编辑 APIG 路由。
+- `vefaas sandbox create` 支持在创建沙箱应用时同步配置 APIG 网关路由。
+
+### Improved
+
+- `vefaas login --check` 返回登录方式、凭据来源和环境信息，便于脚本判断当前认证状态。
+- 当 SSO 凭据缺少 APIG 权限时，CLI 会提示使用 AK/SK 登录，并给出 AK/SK 获取入口。
+- 沙箱实例启动失败时会识别冷启动超时等平台错误，并提示检查实例、日志和沙箱配置。
+- veFaaS Skill 文档补充函数调用、APIG 触发器和沙箱网关路由配置说明。
+
+### Fixed
+
+- 减少登录状态检查时对系统 Keychain 的重复访问。
+- 修复部分 APIG 路由 Action 需要特定版本时无法直接通过 `vefaas api` 调用的问题。
+
+## [0.2.1] - 2026-06-08
+
+0.2.1 聚焦安装、部署输出和登录状态检查体验，提升 npm 发布后的使用稳定性。
+
+### Fixed
+
+- 修复一键安装命令在部分环境下无法正常执行的问题。
+- 修复 `vefaas login --check` 在无有效凭据时的错误提示。
+- 修复 `vefaas deploy -o json` 在未完成项目关联时的非交互处理。
+
+### Improved
+
+- `vefaas deploy` 会展示最终生效的构建设置，并在结构化输出中返回 settings 信息。
+- 优化登录状态读取流程，减少重复凭据校验带来的干扰。
+- 优化全局安装和更新流程，对已有 `vefaas` 安装更友好。
+- 更新 veFaaS Skill 的安装入口。
+
+## [0.2.0] - 2026-06-05
+
+0.2.0 是 veFaaS CLI 的正式对外发布版本，重点提升命令覆盖度、结构化输出、认证稳定性和 Agent/脚本场景可用性。
+
+### Added
+
+- 新增 `vefaas fn` 函数管理命令，支持函数列表、详情、创建、删除、调用、日志、实例、发布、回滚、触发器、依赖、环境变量、配置、伸缩和 WebShell 等操作。
+- 新增 `vefaas sandbox` 沙箱管理命令，支持沙箱列表、创建、删除、详情、镜像查询、配置管理、WebShell 以及实例生命周期操作。
+- 新增 `vefaas gateway` 网关管理命令，支持查询网关、路由、服务和 upstream。
+- 新增 `vefaas api` 命令，可在 CLI 中直接调用 veFaaS OpenAPI，便于排障、自动化和临时运维。
+- 新增 `vefaas doctor` 诊断命令，用于检查 CLI 版本、运行时、凭据状态、项目配置和本地环境。
+- 新增 `vefaas completion` 命令，用于生成 shell 自动补全脚本。
+- 新增 `--output json|yaml|table|text` 输出格式，并支持 `--fields`、`--limit` 和 `--jq`，方便脚本、CI 和 AI Agent 消费命令结果。
+- 新增凭据加密存储与旧凭据迁移能力，兼容环境变量、系统凭据层、加密文件和旧版明文凭据。
+
+### Changed
+
+- CLI 帮助、参数校验、全局选项和子命令行为统一调整，错误提示和非交互场景表现更一致。
+- 使用说明重写，补充认证、常用命令、输出格式、环境变量和故障排查说明。
+
+### Improved
+
+- 优化文本、表格、JSON 和 YAML 输出，减少命令间输出差异。
+- 优化错误码和错误文案，提升 CI、脚本和 Agent 调用时的可判断性。
+- 优化登录、凭据读取和本地配置读取流程，降低重复登录和凭据文件兼容问题。
+- 优化函数选择、分页选择、名称校验、运行时检测和本地项目探测体验。
+- 优化 OpenAPI 调用参数提示，降低直接调用 API 的使用成本。

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# veFaaS CLI
+
+veFaaS CLI 是火山引擎 veFaaS 的命令行工具，用于在终端中完成登录、项目初始化、应用部署、函数管理、沙箱管理、网关管理和 OpenAPI 调用。
+
+如果你在 AI Agent 中使用 veFaaS，建议同时安装 veFaaS Skill。CLI 负责真实执行命令，Skill 负责向 Agent 提供 veFaaS 的使用说明、最佳实践、部署工作流和常见排障路径。
+
+## 安装 CLI
+
+一键安装 CLI 和 veFaaS Skill：
+
+```bash
+npx @volcengine/vefaas-cli@latest install
+```
+
+全局安装 CLI：
+
+```bash
+npm i -g @volcengine/vefaas-cli@latest
+```
+
+或使用 pnpm：
+
+```bash
+pnpm add -g @volcengine/vefaas-cli@latest
+```
+
+验证安装：
+
+```bash
+vefaas --version
+vefaas --help
+```
+
+## 安装 Skill
+
+veFaaS Skill 面向 AI Agent 场景，说明比 CLI `--help` 更完整，包含：
+
+- 什么时候使用 veFaaS CLI
+- 如何部署 Web 应用和静态站点
+- 如何管理函数、沙箱、环境变量和网关
+- 常见错误的诊断方式
+- Agent 调用 CLI 时应遵循的工作流和安全约定
+
+安装 veFaaS Skill：
+
+```bash
+npx skills add vefaas-dev/skills -y -g
+```
+
+安装后，你可以在支持 Skill 的 Agent 中直接提出 veFaaS 相关需求，例如：
+
+```text
+帮我把当前项目部署到 veFaaS
+检查这个函数为什么访问失败
+把 .env 导入到已关联的函数环境变量
+```
+
+Skill 文档：<https://www.volcengine.com/docs/6662/2222391>
+
+## 环境要求
+
+- Node.js >= 18
+- npm 或 pnpm
+- 普通安装和使用不需要手动安装 Bun
+
+## 认证
+
+交互式登录：
+
+```bash
+vefaas login
+```
+
+浏览器 SSO 登录：
+
+```bash
+vefaas login --sso
+```
+
+非交互环境可以使用 AK/SK：
+
+```bash
+vefaas login --accessKey <AK> --secretKey <SK>
+```
+
+也可以直接通过环境变量提供凭据：
+
+```bash
+VOLC_ACCESS_KEY_ID=<AK> VOLC_SECRET_ACCESS_KEY=<SK> vefaas fn list
+```
+
+退出登录：
+
+```bash
+vefaas logout
+```
+
+诊断当前环境、项目配置和凭据状态：
+
+```bash
+vefaas doctor
+vefaas doctor -o json
+```
+
+## 常用命令
+
+查看帮助：
+
+```bash
+vefaas --help
+vefaas <command> --help
+```
+
+初始化或关联项目：
+
+```bash
+vefaas init
+vefaas link
+```
+
+部署当前项目：
+
+```bash
+vefaas deploy
+```
+
+函数管理：
+
+```bash
+vefaas fn list
+vefaas fn info --id <functionId>
+vefaas fn invoke --id <functionId>
+vefaas fn logs --id <functionId>
+```
+
+沙箱管理：
+
+```bash
+vefaas sandbox list
+vefaas sandbox create --help
+vefaas sandbox instance list --id <sandboxId>
+```
+
+网关管理：
+
+```bash
+vefaas gateway list
+vefaas gateway routes --gateway-id <gatewayId>
+```
+
+直接调用 veFaaS OpenAPI：
+
+```bash
+vefaas api ListFunctions --PageSize 10 -o table
+```
+
+## 输出格式
+
+默认输出为文本。可以通过 `-o` / `--output` 切换格式：
+
+```bash
+vefaas fn list -o table
+vefaas fn list -o json
+vefaas fn list -o yaml
+```
+
+JSON 输出可以配合 `--jq` 过滤：
+
+```bash
+vefaas fn list -o json --jq '.data.functions[0].Name'
+```
+
+表格输出可以限制字段和行数：
+
+```bash
+vefaas fn list -o table --fields Id,Name,Runtime --limit 10
+```
+
+## 环境变量
+
+| 变量 | 说明 |
+|-|-|
+| `VOLC_TOKEN` | 使用 token 凭据。优先级高于 AK/SK。 |
+| `VOLC_ACCESS_KEY_ID` | 火山引擎 Access Key ID。 |
+| `VOLC_SECRET_ACCESS_KEY` | 火山引擎 Secret Access Key。 |
+| `VOLC_SESSION_TOKEN` | 可选 STS session token，需要和 AK/SK 一起使用。 |
+| `VEFAAS_DISABLE_KEYCHAIN=1` | 禁用系统凭据存储，改用本地加密文件 fallback。 |
+| `VEFAAS_HOME=<dir>` | 覆盖 CLI 用户配置根目录，凭据和用户配置位于 `$VEFAAS_HOME/.vefaas/`。 |
+| `NO_UPDATE_NOTIFIER=1` | 关闭版本更新提示。 |
+| `VEFAAS_NO_UPDATE_NOTIFIER=1` | 同样用于关闭版本更新提示。 |
+| `NO_COLOR=1` | 禁用彩色输出。 |
+
+示例：
+
+```bash
+NO_UPDATE_NOTIFIER=1 vefaas --help
+VEFAAS_DISABLE_KEYCHAIN=1 vefaas login --accessKey <AK> --secretKey <SK>
+VEFAAS_HOME="$(mktemp -d)" vefaas doctor -o json
+```
+
+## 故障排查
+
+查看 CLI、运行时、凭据和项目配置状态：
+
+```bash
+vefaas doctor
+```
+
+## 更新日志
+
+版本更新内容请查看 [CHANGELOG.md](./CHANGELOG.md)。
+
+## 主页与许可
+
+- 主页：<https://console.volcengine.com/vefaas>
+- 文档：<https://www.volcengine.com/docs/6662>
+- 许可协议：MIT，详见 [LICENSE](./LICENSE)

package/bin/install.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const CLI_PACKAGE = '@volcengine/vefaas-cli';
+const LEGACY_CLI_PACKAGE = '@volcengine/vefaas';
+const SKILL_REPO = 'vefaas-dev/skills';
+const isWindows = process.platform === 'win32';
+
+function parseArgs() {
+  const options = {
+    skipCli: false,
+    skipSkill: false,
+    registry: '',
+  };
+
+  const args = process.argv.slice(2);
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--skip-cli') {
+      options.skipCli = true;
+    } else if (arg === '--skip-skill') {
+      options.skipSkill = true;
+    } else if (arg === '--registry') {
+      options.registry = args[++index] || '';
+    } else if (arg.startsWith('--registry=')) {
+      options.registry = arg.slice('--registry='.length);
+    } else if (arg === '--help' || arg === '-h') {
+      showHelp();
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function showHelp() {
+  console.log(`
+Usage: npx ${CLI_PACKAGE}@latest install [options]
+
+Options:
+  --skip-cli     Do not install or update the global CLI.
+  --skip-skill   Do not install the veFaaS AI skill.
+  --registry     npm registry for installing the CLI.
+
+Flow:
+  1. npm install -g ${CLI_PACKAGE}@latest
+  2. npx -y skills add ${SKILL_REPO} -y -g
+`);
+}
+
+function execCmd(command, args, options = {}) {
+  if (isWindows) {
+    return execFileSync('cmd.exe', ['/c', command, ...args], options);
+  }
+  return execFileSync(command, args, options);
+}
+
+function run(command, args) {
+  console.log(`$ ${[command, ...args].join(' ')}`);
+  execCmd(command, args, {
+    stdio: 'inherit',
+    env: process.env,
+  });
+}
+
+function runOptional(command, args) {
+  try {
+    execCmd(command, args, {
+      stdio: 'ignore',
+      env: process.env,
+    });
+  } catch {}
+}
+
+function runCapture(command, args) {
+  return execCmd(command, args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    env: process.env,
+  }).trim();
+}
+
+function installCli(registry) {
+  console.log(`Installing ${CLI_PACKAGE}@latest globally...`);
+  runOptional('npm', ['uninstall', '-g', LEGACY_CLI_PACKAGE]);
+
+  const args = ['install', '-g', '--force', `${CLI_PACKAGE}@latest`];
+  if (registry) args.push('--registry', registry);
+  run('npm', args);
+}
+
+function skillAlreadyInstalled() {
+  try {
+    const output = runCapture('npx', ['-y', 'skills', 'ls', '-g']);
+    return /\bvefaas\b/i.test(output);
+  } catch {
+    return false;
+  }
+}
+
+function installSkill() {
+  if (skillAlreadyInstalled()) {
+    console.log('veFaaS skill is already installed.');
+    return;
+  }
+
+  console.log('Installing veFaaS skill...');
+  run('npx', ['-y', 'skills', 'add', SKILL_REPO, '-y', '-g']);
+}
+
+function printDone() {
+  console.log('');
+  console.log('veFaaS CLI setup completed.');
+  console.log('');
+  console.log('Next steps:');
+  console.log('  vefaas --version');
+  console.log('  vefaas login');
+}
+
+let options;
+
+try {
+  options = parseArgs();
+  if (!options.skipCli) installCli(options.registry);
+  if (!options.skipSkill) installSkill();
+  printDone();
+} catch (error) {
+  console.error('');
+  console.error(`veFaaS CLI setup failed: ${error instanceof Error ? error.message : String(error)}`);
+  console.error('');
+  console.error('You can retry manually:');
+  const registryArg = options?.registry ? ` --registry ${options.registry}` : '';
+  console.error(`  npm uninstall -g ${LEGACY_CLI_PACKAGE}`);
+  console.error(`  npm install -g --force ${CLI_PACKAGE}@latest${registryArg}`);
+  console.error(`  npx -y skills add ${SKILL_REPO} -y -g`);
+  process.exit(1);
+}

package/bin/vefaas.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const args = process.argv.slice(2);
+const installScript = join(dirname(fileURLToPath(import.meta.url)), 'install.js');
+
+const SUPPORTED_TARGETS = {
+  'linux-x64': {
+    packageName: '@volcengine/vefaas-cli-linux-x64',
+    binaryName: 'vefaas',
+  },
+  'linux-arm64': {
+    packageName: '@volcengine/vefaas-cli-linux-arm64',
+    binaryName: 'vefaas',
+  },
+  'darwin-x64': {
+    packageName: '@volcengine/vefaas-cli-darwin-x64',
+    binaryName: 'vefaas',
+  },
+  'darwin-arm64': {
+    packageName: '@volcengine/vefaas-cli-darwin-arm64',
+    binaryName: 'vefaas',
+  },
+  'win32-x64': {
+    packageName: '@volcengine/vefaas-cli-win32-x64',
+    binaryName: 'vefaas.exe',
+  },
+  'win32-arm64': {
+    packageName: '@volcengine/vefaas-cli-win32-arm64',
+    binaryName: 'vefaas.exe',
+  },
+};
+
+function run(command, commandArgs) {
+  const result = spawnSync(command, commandArgs, {
+    stdio: 'inherit',
+    windowsHide: false,
+  });
+
+  if (result.error) {
+    console.error(result.error.message);
+    process.exit(1);
+  }
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+  }
+  process.exit(result.status ?? 1);
+}
+
+function resolveBinary(target) {
+  const packageJsonPath = require.resolve(`${target.packageName}/package.json`);
+  return join(dirname(packageJsonPath), 'bin', target.binaryName);
+}
+
+if (args[0] === 'install') {
+  run(process.execPath, [installScript, ...args.slice(1)]);
+}
+
+const targetKey = `${process.platform}-${process.arch}`;
+const target = SUPPORTED_TARGETS[targetKey];
+
+if (target) {
+  try {
+    run(resolveBinary(target), args);
+  } catch {}
+}
+
+const fallback = fileURLToPath(new URL('../dist/vefaas.js', import.meta.url));
+if (existsSync(fallback)) {
+  run(process.execPath, [fallback, ...args]);
+}
+
+const supported = Object.keys(SUPPORTED_TARGETS).join(', ');
+console.error(`vefaas does not ship a binary for ${targetKey}.`);
+if (target) {
+  console.error(`Expected optional package: ${target.packageName}`);
+  console.error('Try reinstalling with optional dependencies enabled: npm install -g @volcengine/vefaas-cli@latest');
+} else {
+  console.error(`Supported targets: ${supported}`);
+}
+process.exit(1);

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "@volcengine/vefaas-cli",
-  "version": "0.2.2-win32-x64",
+  "version": "0.2.2",
   "license": "MIT",
-  "description": "The command-line interface for veFaaS (Windows x64 binary)",
+  "description": "The command-line interface for veFaaS",
+  "type": "module",
   "homepage": "https://console.volcengine.com/vefaas",
-  "os": [
-    "win32"
-  ],
-  "cpu": [
-    "x64"
-  ],
+  "bin": {
+    "vefaas": "bin/vefaas.js"
+  },
+  "preferGlobal": true,
   "files": [
-    "bin"
-  ]
+    "bin",
+    "CHANGELOG.md"
+  ],
+  "optionalDependencies": {
+    "@volcengine/vefaas-cli-linux-x64": "npm:@volcengine/vefaas-cli@0.2.2-linux-x64",
+    "@volcengine/vefaas-cli-linux-arm64": "npm:@volcengine/vefaas-cli@0.2.2-linux-arm64",
+    "@volcengine/vefaas-cli-darwin-x64": "npm:@volcengine/vefaas-cli@0.2.2-darwin-x64",
+    "@volcengine/vefaas-cli-darwin-arm64": "npm:@volcengine/vefaas-cli@0.2.2-darwin-arm64",
+    "@volcengine/vefaas-cli-win32-x64": "npm:@volcengine/vefaas-cli@0.2.2-win32-x64",
+    "@volcengine/vefaas-cli-win32-arm64": "npm:@volcengine/vefaas-cli@0.2.2-win32-arm64"
+  },
+  "engines": {
+    "node": ">=18"
+  }
 }