@cloudbase/manager-node 5.8.9-beta.0 → 5.9.0

package/lib/deploy/GatewayDeployer.js

@@ -144,25 +144,25 @@ class GatewayDeployer {
         // 保留前缀检测（对齐控制台 useRouteConfig 与 tcb routes add）：/__auth、/.well-known 是系统保留前缀
         const reservedPrefix = /^\/(__auth|\.well-known)/;
         if (reservedPrefix.test(path)) {
-            throw new error_1.CloudBaseError(`网关路由 path 不能使用系统保留前缀：${path}。/__auth、/.well-known 是系统保留前缀，请更换其他路径`);
+            (0, error_1.throwInvalidParam)(`网关路由 path 不能使用系统保留前缀：${path}。/__auth、/.well-known 是系统保留前缀，请更换其他路径`);
         }
         // path 格式校验（与控制台 useRouteConfig、tcb routes add 一致）
         const pathPattern = /^(\/(?!\/)[a-zA-Z0-9_\.\-]{0,50})+\/?$/;
         if (!pathPattern.test(path)) {
-            throw new error_1.CloudBaseError(`网关路由 path 格式错误：${path}。必须以 "/" 开头，每段只含字母/数字/./_/-，每段≤50字符，不支持通配符 *（示例：/api、/pay-common、/）`);
+            (0, error_1.throwInvalidParam)(`网关路由 path 格式错误：${path}。必须以 "/" 开头，每段只含字母/数字/./_/-，每段≤50字符，不支持通配符 *（示例：/api、/pay-common、/）`);
         }
         const match = /^(function|hosting):(.+)$/.exec(target);
         if (!match) {
-            throw new error_1.CloudBaseError(`网关路由 target 格式错误：${target}，仅支持 function:<name> / hosting:<name>`);
+            (0, error_1.throwInvalidParam)(`网关路由 target 格式错误：${target}，仅支持 function:<name> / hosting:<name>`);
         }
         const [, type, name] = match;
         if (!name) {
-            throw new error_1.CloudBaseError(`网关路由 target 缺少资源名：${target}`);
+            (0, error_1.throwInvalidParam)(`网关路由 target 缺少资源名：${target}`);
         }
         // 静态托管：上游名固定为 staticstore，且只支持一级路径（与 tcb routes add 一致）
         if (type === 'hosting') {
             if (!/^\/[a-zA-Z0-9_\.\-]{0,50}\/?$/.test(path)) {
-                throw new error_1.CloudBaseError(`静态托管路由只支持一级路径（如 / 或 /web），当前值：${path}`);
+                (0, error_1.throwInvalidParam)(`静态托管路由只支持一级路径（如 / 或 /web），当前值：${path}`);
             }
             return Object.assign({ Path: path, UpstreamResourceType: 'STATIC_STORE', UpstreamResourceName: 'staticstore', EnableSafeDomain: true, EnableAuth: enableAuth !== null && enableAuth !== void 0 ? enableAuth : false, EnablePathTransmission: enablePathTransmission !== null && enablePathTransmission !== void 0 ? enablePathTransmission : false, Enable: true }, (qpsPolicy ? { QPSPolicy: qpsPolicy } : {}));
         }

package/lib/deploy/StaticDeployer.js

@@ -39,7 +39,7 @@ class StaticDeployer {
         const { config, cwd = process.cwd() } = options;
         const serviceName = config.serviceName;
         if (!serviceName) {
-            throw new error_1.CloudBaseError('app 部署需要配置 serviceName');
+            (0, error_1.throwInvalidParam)('app 部署需要配置 serviceName');
         }
         const projectPath = path_1.default.resolve(cwd, config.root || '.');
         const resolvedDeployPath = config.deployPath || `/${serviceName}`;
@@ -208,7 +208,7 @@ class StaticDeployer {
         }
         catch (e) {
             const detail = ((e === null || e === void 0 ? void 0 : e.stderr) || (e === null || e === void 0 ? void 0 : e.stdout) || (e === null || e === void 0 ? void 0 : e.message) || String(e)).toString().trim();
-            throw new error_1.CloudBaseError(`本地构建失败：在 ${projectPath} 执行「${buildCommand}」失败。\n` +
+            (0, error_1.throwApiError)(`本地构建失败：在 ${projectPath} 执行「${buildCommand}」失败。\n` +
                 `请先在项目目录手动执行该命令排查原因（常见原因：构建脚本报错、依赖未安装、lockfile 不一致）。\n` +
                 (detail ? `原始错误：${detail.slice(0, 500)}` : ''));
         }

package/lib/deploy/framework.js

@@ -42,6 +42,7 @@ exports.buildHostingItem = buildHostingItem;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
+const error_1 = require("../error");
 /**
  * 框架 → 默认构建命令映射（hosting 本地构建 / app 云端构建复用）
  */
@@ -258,7 +259,7 @@ function buildHostingItem(config, root, envVariables) {
     }
     catch (e) {
         const detail = ((e === null || e === void 0 ? void 0 : e.stderr) || (e === null || e === void 0 ? void 0 : e.stdout) || (e === null || e === void 0 ? void 0 : e.message) || String(e)).toString().trim();
-        throw new Error(`本地构建失败：在 ${root} 执行「${buildCommand}」失败。\n${detail.slice(0, 500)}`);
+        throw new error_1.CloudBaseError(`本地构建失败：在 ${root} 执行「${buildCommand}」失败。\n${detail.slice(0, 500)}`, { code: 'BUILD_FAILED', source: 'manager-node' });
     }
     return resolveHostingOutputDir(config, root);
 }

package/lib/deploy/function/config-guard.js

@@ -501,7 +501,9 @@ function checkImageReference(imageConfig, checks) {
         return;
     }
     if (parsed.tag === 'latest' && !parsed.digest) {
-        checks.push(fail(types_1.FUNCTION_DEPLOY_ERROR.IMAGE_TAG_LATEST_FORBIDDEN, '镜像地址禁止使用 latest', '请使用内容可追溯的不可变 tag 或 digest'));
+        // D7：平台**允许** latest —— 它是「次优/有风险」而非「必然失败」，按 §4.4 判据应**提示**而非拦截。
+        // 走 fail 会违反 AIP-163「fail 必须蕴含真实失败」，属把建议误当校验（归类纠错）。
+        checks.push(warn(types_1.FUNCTION_DEPLOY_ERROR.IMAGE_TAG_LATEST_FORBIDDEN, '镜像地址使用了 latest（内容不可追溯）', '建议使用不可变 tag 或 digest，以便部署可重试、可回滚'));
     }
 }
 /**
@@ -561,8 +563,9 @@ function checkBuildTag(raw, build) {
         return [fail(types_1.FUNCTION_DEPLOY_ERROR.BUILD_TAG_INVALID, '镜像 tag 不合法')];
     }
     if (build.tag === 'latest') {
+        // D7：同前 —— 平台允许 latest，故为「提示」而非「拦截」（AIP-163）
         return [
-            fail(types_1.FUNCTION_DEPLOY_ERROR.IMAGE_TAG_LATEST_FORBIDDEN, '镜像 tag 禁止使用 latest', '请使用不可变 tag，或不指定 tag 由构建器生成时间戳 tag')
+            warn(types_1.FUNCTION_DEPLOY_ERROR.IMAGE_TAG_LATEST_FORBIDDEN, '镜像 tag 使用了 latest（内容不可追溯）', '建议改用不可变 tag，或不指定 tag 由构建器生成时间戳 tag')
         ];
     }
     return [];
@@ -804,6 +807,15 @@ function assertDeployConfig(config) {
     const report = checkDeployConfig(config);
     if (!report.ready) {
         const failures = report.checks.filter(item => item.status === 'fail');
+        // ⚠️ 同 FunctionDeployer.assertPreflightReady：报告不自洽（ready=false 但无 fail 项）时
+        // `failures` 为空数组，取 `failures[0].id` 会先抛 TypeError（代码评审：边界条件）。
+        if (failures.length === 0) {
+            failures.push({
+                id: 'CHECK_REPORT_INCONSISTENT',
+                status: 'fail',
+                summary: '部署配置校验未通过，但未给出具体失败项，请重试或用 --debug 查看完整报告'
+            });
+        }
         const message = failures
             .map(item => {
             const remediation = item.remediation ? `，${item.remediation}` : '';
@@ -811,7 +823,15 @@ function assertDeployConfig(config) {
         })
             .join('\n');
         throw new error_1.CloudBaseError(`部署配置校验未通过：\n${message}`, {
-            code: failures[0].id
+            code: failures[0].id,
+            // code 只能承载第一个失败项，meta.failures 保留全量（埋点才能统计真实分布）
+            meta: {
+                failures: failures.map(item => ({
+                    code: item.id,
+                    summary: item.summary,
+                    remediation: item.remediation
+                }))
+            }
         });
     }
     return normalizeDeployConfig(config);

package/lib/deploy/function/enterprise-tcr.js

@@ -6,6 +6,7 @@ exports.createTcrApiService = createTcrApiService;
 const error_1 = require("../../error");
 const types_1 = require("../types");
 const config_guard_1 = require("./config-guard");
+const cam_preflight_1 = require("./cam-preflight");
 const TCR_API_VERSION = '2019-09-24';
 const NAMESPACE_PATTERN = /^[a-z0-9](?:[a-z0-9]|[._-](?![._-])){0,28}[a-z0-9]$/;
 function responseOf(result) {
@@ -64,9 +65,18 @@ async function resolveRegistry(service, region, explicitRegistryId) {
         });
     }
     catch (error) {
+        // AIP-193：权限错误必须**保持权限语义**，不得包装成「实例发现失败」这类业务错误 ——
+        // 否则用户与埋点都看不到「无权限」这个真实原因。直接透传上游错误
+        // （其 code 为 AuthFailure.*，source 为 cloud-api，requestId 完整）。
+        if ((0, cam_preflight_1.isCamPermissionError)(error)) {
+            throw error;
+        }
         throw new error_1.CloudBaseError('查询企业版 TCR 实例失败，请确认当前身份具备 DescribeInstances 权限。', {
             code: types_1.FUNCTION_DEPLOY_ERROR.TCR_INSTANCE_DISCOVERY_FAILED,
-            requestId: errorRequestId(error) || ''
+            source: 'manager-node',
+            requestId: errorRequestId(error) || '',
+            // 保留上游错误：不挂 cause 链会让排查丢失最关键的原始 code / requestId
+            original: error instanceof Error ? error : undefined
         });
     }
     const response = responseOf(result);
@@ -179,9 +189,15 @@ async function createEnterpriseTcrCredential(service, registryId) {
         });
     }
     catch (error) {
+        // AIP-193：权限错误保持权限语义（同上）—— 透传上游错误，不包装成「凭证创建失败」
+        if ((0, cam_preflight_1.isCamPermissionError)(error)) {
+            throw error;
+        }
         throw new error_1.CloudBaseError('获取企业版 TCR 临时登录凭证失败，请确认当前身份具备 CreateInstanceToken 权限。', {
             code: types_1.FUNCTION_DEPLOY_ERROR.TCR_TOKEN_CREATE_FAILED,
-            requestId: errorRequestId(error) || ''
+            source: 'manager-node',
+            requestId: errorRequestId(error) || '',
+            original: error instanceof Error ? error : undefined
         });
     }
     const response = responseOf(result);

package/lib/docs/index.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DocsService = void 0;
 const http_request_1 = require("../utils/http-request");
+const error_1 = require("../error");
 const DOCS_BASE_URL = 'https://docs.cloudbase.net';
 const CATEGORY_URL = `${DOCS_BASE_URL}/category.json`;
 const ALGOLIA_SEARCH_URL = 'https://70wjvl90pg-dsn.algolia.net/1/indexes/*/queries' +
@@ -45,7 +46,7 @@ class DocsService {
         if (found) {
             return found;
         }
-        throw new Error(`Module "${moduleName}" not found`);
+        (0, error_1.throwNotFound)(`Module "${moduleName}" not found`);
     }
     /**
      * Case: tcb docs read <任意输入>
@@ -72,7 +73,7 @@ class DocsService {
             if (result) {
                 return result;
             }
-            throw new Error(`未找到模块或文档 "${input}"`);
+            (0, error_1.throwNotFound)(`未找到模块或文档 "${input}"`);
         }
         // 模式3: 模块名查找（顶级或嵌套）复用上面已获取的 category
         const topLevelModule = category[input];
@@ -93,7 +94,7 @@ class DocsService {
         if (prefixResult) {
             return prefixResult;
         }
-        throw new Error(`未找到模块或文档 "${input}"`);
+        (0, error_1.throwNotFound)(`未找到模块或文档 "${input}"`);
     }
     async readDoc(docPath) {
         const normalizedPath = docPath.endsWith('.md') ? docPath : `${docPath}/index.md`;

package/lib/env/index.js

@@ -301,7 +301,7 @@ class EnvService {
         const validStatus = ['ENABLE', 'DISABLE'];
         let finalAppSecret = appSecret;
         if (!validStatus.includes(status)) {
-            throw new error_1.CloudBaseError(`Invalid status value: ${status}. Only support 'ENABLE', 'DISABLE'`);
+            (0, error_1.throwInvalidParam)(`Invalid status value: ${status}. Only support 'ENABLE', 'DISABLE'`);
         }
         const params = {
             EnvId: this.envId,
@@ -457,7 +457,7 @@ class EnvService {
     async getAdminAccessToken(credentials) {
         const { secretId, secretKey, token } = credentials || this.environment.cloudBaseContext;
         if (!secretId || !secretKey) {
-            throw new error_1.CloudBaseError('missing secretId or secretKey of tencent cloud');
+            (0, error_1.throwInvalidParam)('missing secretId or secretKey of tencent cloud');
         }
         const envId = this.envId;
         const cacheKey = `access_token_secret_${envId}_${secretId}`;
@@ -567,7 +567,7 @@ class EnvService {
         });
         const packageInfo = (_a = packageRes.PackageList) === null || _a === void 0 ? void 0 : _a[0];
         if (!packageInfo) {
-            throw new error_1.CloudBaseError(`Invalid package id: ${packageId}`);
+            (0, error_1.throwInvalidParam)(`Invalid package id: ${packageId}`);
         }
         const { BillTags: billTags } = packageInfo;
         const newBillTag = this.parseBillTags(billTags);
@@ -595,7 +595,7 @@ class EnvService {
         });
         const priceInfo = (_c = priceRes.PriceInfos) === null || _c === void 0 ? void 0 : _c[0];
         if (!priceInfo) {
-            throw new error_1.CloudBaseError(`Invalid package id: ${packageId}`);
+            (0, error_1.throwInvalidParam)(`Invalid package id: ${packageId}`);
         }
         return priceInfo;
     }
@@ -620,11 +620,11 @@ class EnvService {
         const envBaseInfo = (_a = envInfoRes === null || envInfoRes === void 0 ? void 0 : envInfoRes.EnvInfo) === null || _a === void 0 ? void 0 : _a.EnvBaseInfo;
         const billingInfo = (_b = billingRes.EnvBillingInfoList) === null || _b === void 0 ? void 0 : _b[0];
         if (!(envBaseInfo === null || envBaseInfo === void 0 ? void 0 : envBaseInfo.EnvId) || !billingInfo) {
-            throw new error_1.CloudBaseError(`Invalid env id: ${envId}`);
+            (0, error_1.throwInvalidParam)(`Invalid env id: ${envId}`);
         }
         const packageInfo = (_c = packageRes.PackageList) === null || _c === void 0 ? void 0 : _c.find(item => item.PackageName === envBaseInfo.PackageId);
         if (!packageInfo) {
-            throw new error_1.CloudBaseError(`Invalid env id: ${envId}`);
+            (0, error_1.throwInvalidParam)(`Invalid env id: ${envId}`);
         }
         const region = envBaseInfo.Region;
         const extPackageData = ((_d = billingInfo.ExtPackageCode) === null || _d === void 0 ? void 0 : _d.reduce((acc, { Code, Num }) => {
@@ -649,7 +649,7 @@ class EnvService {
         });
         const priceInfo = (_f = priceRes.PriceInfos) === null || _f === void 0 ? void 0 : _f[0];
         if (!priceInfo) {
-            throw new error_1.CloudBaseError(`Invalid env id: ${envId}`);
+            (0, error_1.throwInvalidParam)(`Invalid env id: ${envId}`);
         }
         return priceInfo;
     }
@@ -674,15 +674,15 @@ class EnvService {
         const envBaseInfo = (_a = envInfoRes === null || envInfoRes === void 0 ? void 0 : envInfoRes.EnvInfo) === null || _a === void 0 ? void 0 : _a.EnvBaseInfo;
         const billingInfo = (_b = billingRes.EnvBillingInfoList) === null || _b === void 0 ? void 0 : _b[0];
         if (!(envBaseInfo === null || envBaseInfo === void 0 ? void 0 : envBaseInfo.EnvId) || !billingInfo || !billingInfo.PackageId) {
-            throw new error_1.CloudBaseError(`Invalid env id: ${envId}`);
+            (0, error_1.throwInvalidParam)(`Invalid env id: ${envId}`);
         }
         const oldPackageInfo = (_c = packageRes.PackageList) === null || _c === void 0 ? void 0 : _c.find(item => item.PackageName === billingInfo.PackageId);
         if (!oldPackageInfo) {
-            throw new error_1.CloudBaseError(`Modification for this package is not available`);
+            (0, error_1.throwApiError)(`Modification for this package is not available`);
         }
         const newPackageInfo = (_d = packageRes.PackageList) === null || _d === void 0 ? void 0 : _d.find(item => item.PackageName === newPackageId);
         if (!newPackageInfo) {
-            throw new error_1.CloudBaseError(`Invalid package id: ${newPackageId}`);
+            (0, error_1.throwInvalidParam)(`Invalid package id: ${newPackageId}`);
         }
         const region = envBaseInfo.Region;
         const newBillTags = this.parseBillTags(newPackageInfo.BillTags);
@@ -737,7 +737,7 @@ class EnvService {
         });
         const priceInfo = (_g = priceRes.PriceInfos) === null || _g === void 0 ? void 0 : _g[0];
         if (!priceInfo) {
-            throw new error_1.CloudBaseError(`Invalid package id: ${newPackageId}`);
+            (0, error_1.throwInvalidParam)(`Invalid package id: ${newPackageId}`);
         }
         return priceInfo;
     }
@@ -780,11 +780,11 @@ class EnvService {
      */
     async describeCertificates(params = {}) {
         if (params.Offset !== undefined && (!Number.isInteger(params.Offset) || params.Offset < 0)) {
-            throw new error_1.CloudBaseError('Offset 必须是大于等于 0 的整数');
+            (0, error_1.throwInvalidParam)('Offset 必须是大于等于 0 的整数');
         }
         if (params.Limit !== undefined &&
             (!Number.isInteger(params.Limit) || params.Limit < 1 || params.Limit > 1000)) {
-            throw new error_1.CloudBaseError('Limit 必须是 1 至 1000 的整数');
+            (0, error_1.throwInvalidParam)('Limit 必须是 1 至 1000 的整数');
         }
         return this.certificateCloudService.request('DescribeCertificates', params);
     }
@@ -894,13 +894,13 @@ class EnvService {
         const domains = queryRes.Domains || [];
         const targetDomain = domains.find(d => d.Domain === Domain);
         if (!targetDomain) {
-            throw new error_1.CloudBaseError(`Domain ${Domain} does not exist`);
+            (0, error_1.throwNotFound)(`Domain ${Domain} does not exist`);
         }
         // 检查是否有路由绑定
         const routes = targetDomain.Routes || [];
         if (routes.length > 0) {
             const routePaths = routes.map(r => r.Path).join(', ');
-            throw new error_1.CloudBaseError(`Domain ${Domain} has ${routes.length} route binding(s) (${routePaths}). Please delete the routes before deleting the domain.`);
+            (0, error_1.throwApiError)(`Domain ${Domain} has ${routes.length} route binding(s) (${routePaths}). Please delete the routes before deleting the domain.`);
         }
         // 无路由绑定，可以删除域名
         return this.cloudService.request('DeleteHTTPServiceRoute', {
@@ -986,7 +986,7 @@ class EnvService {
             return JSON.parse(billTags);
         }
         catch (e) {
-            throw new error_1.CloudBaseError(`Failed to parse BillTags: ${billTags}`);
+            (0, error_1.throwApiError)(`Failed to parse BillTags: ${billTags}`);
         }
     }
 }

package/lib/environment.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Environment = void 0;
 const database_1 = require("./database");
+const error_1 = require("./error");
 const function_1 = require("./function");
 const FunctionDeployer_1 = require("./deploy/FunctionDeployer");
 const cloudrun_1 = require("./cloudrun");
@@ -10,7 +11,6 @@ const storage_1 = require("./storage");
 const env_1 = require("./env");
 const common_1 = require("./common");
 const log_1 = require("./log");
-const error_1 = require("./error");
 const constant_1 = require("./constant");
 const utils_1 = require("./utils");
 const hosting_1 = require("./hosting");
@@ -61,7 +61,7 @@ class Environment {
             return envConfig.getEnvInfo().then(envInfo => {
                 this.lazyEnvironmentConfig = envInfo.EnvInfo;
                 if (!this.lazyEnvironmentConfig.EnvId) {
-                    throw new error_1.CloudBaseError(`Environment ${this.envId} not found`);
+                    (0, error_1.throwNotFound)(`Environment ${this.envId} not found`);
                 }
                 this.inited = true;
                 return this.lazyEnvironmentConfig;
@@ -169,10 +169,10 @@ class Environment {
             const envToken = (0, utils_1.getEnvVar)(constant_1.ENV_NAME.ENV_SESSIONTOKEN);
             if (!envSecretId || !envSecretKey) {
                 if ((0, utils_1.getRuntime)() === constant_1.RUN_ENV.SCF) {
-                    throw new Error('missing authoration key, redeploy the function');
+                    (0, error_1.throwCredentialError)('missing authorization key, redeploy the function');
                 }
                 else {
-                    throw new Error('missing secretId or secretKey of tencent cloud');
+                    (0, error_1.throwCredentialError)('missing secretId or secretKey of tencent cloud');
                 }
             }
             else {

package/lib/environmentManager.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnvironmentManager = void 0;
 const environment_1 = require("./environment");
 const constant_1 = require("./constant");
+const error_1 = require("./error");
 class EnvironmentManager {
     constructor(context) {
         this.envs = {};
@@ -11,7 +12,10 @@ class EnvironmentManager {
     }
     getCurrentEnv() {
         if (!this.currentEnv) {
-            throw new Error(constant_1.ERROR.CURRENT_ENVIRONMENT_IS_NULL);
+            throw new error_1.CloudBaseError(constant_1.ERROR.CURRENT_ENVIRONMENT_IS_NULL, {
+                code: 'CONFIG_ERROR',
+                source: 'manager-node'
+            });
         }
         return this.currentEnv;
     }