@cloudbase/manager-node 5.9.3 → 5.10.0

package/types/utils/ignore.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 上传类操作的默认排除清单。
+ *
+ * ⚠️ 这里必须保持「无 import」：`src/utils/fs.ts`、`src/storage/index.ts`、
+ * `src/deploy/StaticDeployer.ts` 三方都要引用它，带依赖会立刻形成循环引用
+ * （StaticDeployer → environment → storage → utils/fs → StaticDeployer）。
+ */
+/**
+ * 上传产物 / 源码包时默认排除的敏感文件。
+ *
+ * 两类场景都可能把密钥发布出去：
+ *   1. `outputDir: '.'` 时产物目录就是项目根，`.env` 会进**公开可访问**的托管桶
+ *   2. `skipBuild` 场景的源码包虽不参与构建，但仍会落到 COS
+ *
+ * `node_modules` 由 `uploadCode` 的 `excludeNodeModules`（默认 true）与
+ * `DEFAULT_ARTIFACT_IGNORE` 分别处理，不在此列。
+ *
+ * 两条硬约束（各自都出过真实缺陷，改动本清单前先看）：
+ *
+ * 1. **每一项都必须能命中绝对路径**：文件级上传（`uploadFilesCustom`）拿到的
+ *    `files[].localPath` 是 `path.resolve()` 后的绝对路径，根锚定写法（`.env`）
+ *    匹配不到它，只有 `**\/` 前缀形式能命中。
+ * 2. **点目录必须显式成条目**：micromatch 默认 `dot: false`，`**` / `*` 不会
+ *    穿越以点开头的目录 —— `**\/id_rsa*` 打不到 `.ssh/id_rsa`，`**\/*.pem` 同样
+ *    打不到。`isIgnoredPath` / `walkLocalDir` 已统一改用 `{ dot: true }` 兜住
+ *    通配符盲区（stbug-KlBy1JWhvD），但**新文件名仍需显式列出**：`dot: true`
+ *    只让 `**` 能进点目录，不能让通配符猜出 `.npmrc` 这类只靠文件名识别的凭证。
+ *
+ * 为什么仍是黑名单而不是「默认拒绝 + 白名单放行」：本清单同时决定静态产物能否
+ * 上传，白名单化会静默漏掉未知产物（站点缺文件、线上 404）。因此采用
+ * 「黑名单 + dot:true + 显式点目录条目」的组合，覆盖已知凭证载体。
+ */
+export declare const SENSITIVE_FILE_IGNORE: string[];
+/**
+ * 产物上传（目录级 `uploadDirectoryCustom` / 文件级 `uploadFilesCustom`）的默认排除清单，
+ * app / hosting 共用。
+ *
+ * 用户配置的 `ignore` 只能**追加**在其后，不能替换：hosting 曾用
+ * `config.ignore || ['.DS_Store']`，纯静态回退 root 时 `.env` / `.git` / 私钥会被公开发布。
+ *
+ * ⚠️ 作用域：只在**静态托管 / 静态部署**链路生效（`StaticDeployer.uploadArtifact`、
+ * `HostingService.uploadFiles`）。通用云存储上传（`storage.uploadFiles` /
+ * `uploadDirectory`）是私有桶语义，用户可能确实要备份 `.env` / 配置文件，
+ * 本次**不**强制套用本清单 —— 强制并入会让这类上传静默丢文件且无任何提示。
+ *
+ * `node_modules`：静态托管不构建、不运行 Node，上传它没有任何作用，
+ * 还会拖慢上传并公开依赖清单。必须同时写两条：`node_modules/**` 只匹配根目录那一层，
+ * `web/node_modules` 这类嵌套目录要靠 `**\/node_modules/**`。
+ * 例外：页面里直接引用 `./node_modules/xxx` 的写法会 404，应改为拷贝到 `vendor/` 或走 CDN。
+ */
+export declare const DEFAULT_ARTIFACT_IGNORE: string[];
+/**
+ * 把调用方传入的 `ignore` 追加到 `DEFAULT_ARTIFACT_IGNORE` 之后并去重。
+ *
+ * **唯一**的清单构造入口，三条路径共用同一份结果：
+ *   1. 静态托管直传（`HostingService.uploadFiles` → `uploadDirectoryCustom` / `uploadFilesCustom`）
+ *   2. 静态部署直传（`StaticDeployer.uploadArtifact`）
+ *   3. 版本快照打包（`StaticDeployer.deployAppStatic` → `cloudAppService.uploadCode`）
+ *
+ * 1 与 2/3 曾经各写一份：托管桶排 node_modules / .DS_Store，快照 ZIP 只排敏感文件，
+ * 于是产物目录含 node_modules 时「版本快照 = 实际发布内容」的契约不成立
+ * （回滚拿到快照里多了线上没有的文件）。现在统一，不再提供 scope 参数 ——
+ * 两侧范围本来就该一致，留一个可选 scope 只会让下一次分叉更容易发生
+ * （stbug-OSPixWD3KS）。
+ *
+ * 用户 ignore 只能追加：`undefined` / `[]` / 单字符串都表示「不加额外规则」，
+ * 绝不表示「不排除敏感文件」。去重是必要的：调用链上会被合并两次
+ * （StaticDeployer → hosting.uploadFiles），必须保证重复合并 = 幂等。
+ *
+ * ⚠️ 空串必须在这里丢掉（与 `StaticDeployer.normalizeIgnore` 同一口径）：
+ * 空串不是合法 glob，留着会一路透传到 `utils/fs.ts:matchesIgnorePattern` 的
+ * `micromatch.isMatch`，picomatch 直接抛 `TypeError: Expected pattern to be a
+ * non-empty string` —— 上传在第一次匹配时崩溃，且抛的是底层库错误、无任何指向性。
+ * 非字符串项同样丢弃：本文件必须保持「无 import」，不能引入 INVALID_PARAM 抛错。
+ */
+export declare function mergeArtifactIgnore(ignore?: string | string[] | null): string[];

package/types/utils/index.d.ts

@@ -95,4 +95,8 @@ export declare const getCompleteTimeRange: (timeRange: {
     startTime: string;
     endTime: string;
 };
+/** 用户可见的进度日志（准备上传 / 批次 / 完成），写 stderr，不污染 stdout */
+export declare function progressLog(msg: string): void;
+/** 诊断日志，默认静默，仅 verbose 时输出 */
+export declare function debugLog(msg: string): void;
 export declare function successLog(msg: string): void;