@infly/libs 2.0.53 → 2.1.0

package/README.md

@@ -204,9 +204,34 @@ infly-libs project build --env stage --target SQ223
 
 `build.environments` 推荐使用 `选择键:实际 mode` 数组，例如 `["prod:production", "stage:staging"]`；CLI 使用冒号前的值进行选择，并把冒号后的值作为 `--mode` 参数。没有冒号时选择键和 mode 同名。对象形式继续兼容，用于自定义 `label`、`mode` 或 `args`。项目如果自行管理构建入口，应设置 `infly.buildConfigs.manageScripts=false`，避免安装阶段重新写入传统 `build:prod/build:stage`。
 
+### 通用终端单选与多选
+
+`@infly/libs/cli/select-option` 提供不包含业务选项的 TTY 交互适配，调用方负责传入稳定的 `value` 和展示 `label`：
+
+```js
+const {
+  EXIT_SELECTION,
+  selectOption,
+  selectOptions,
+} = require("@infly/libs/cli/select-option");
+
+const platform = await selectOption("请选择平台", [
+  { value: "a", label: "平台 A" },
+  { value: "b", label: "平台 B" },
+]);
+if (platform === EXIT_SELECTION) return;
+
+const components = await selectOptions("请选择构建范围", [
+  { value: "frontend", label: "前端" },
+  { value: "backend", label: "后端" },
+]);
+```
+
+`selectOptions` 至少要求选择一项，并返回所选 `value` 数组；取消提示时与 `selectOption` 一样返回 `EXIT_SELECTION`。两者都只允许在 TTY 中交互，CI 等非交互环境必须由调用方提供显式参数，不得猜测默认选项。
+
 ### Docker Compose 版本发布
 
-`docker:compose` 面向已有 Compose 文件的镜像版本递增、配置校验和构建，与上面的 Dockerfile/commit-tag `build:docker` 流程互不替代：
+`docker:compose` 面向已有 Compose 文件的镜像版本固定或递增、配置校验和构建，与上面的 Dockerfile/commit-tag `build:docker` 流程互不替代：
 
 ```bash
 infly-libs docker:compose --target yhqy --bump patch
@@ -219,8 +244,95 @@ infly-libs docker:compose --target yhqy --bump patch
 - `--target`：选择 `infly.docker.targets` 或外部配置中的目标；非交互环境必须显式传入。
 - `--config`：可选的外部 JS 配置文件，使用 `targets.<name>.file` 结构。
 - `--project-dir` + `--file`：不使用 target 配置时的兼容直传方式，Compose 文件不能越出 `project-dir`。
-- `--bump patch`：目前只支持 patch 递增，且 Compose 中必须恰好有一个 `x.y.z` 镜像 tag。
+- `--bump none|patch`：`none` 保持 Compose 中的镜像版本不变，`patch` 将补丁版本递增；两种模式都要求 Compose 中恰好有一个 `x.y.z` 镜像 tag。
 - `--push`：显式推送；未传时只执行 `docker compose config` 和 `build`。
 - `--dry-run`：只打印版本变化和计划命令，不写文件、不调用 Docker。
 
-构建、校验或推送失败时，命令会恢复原 Compose 内容。公共包不内置 yhqy、qdxy 等业务目标映射；目标配置和单一发布 script 应归 Compose 所在项目所有。
+递增模式下构建、校验或推送失败时，命令会恢复原 Compose 内容；固定模式不会重写 Compose。公共包不内置 yhqy、qdxy 等业务目标映射；目标配置和发布 scripts 应归 Compose 所在项目所有。
+
+## 配置驱动的 Docker 构建与部署
+
+维护归属：公共构建工具；以 `bin/cli.js`、`build/docker/target-release.js` 和 `deployment-bundle.js` 为实现契约。新增配置字段时同步此节及测试。
+
+`infly-libs docker:release` 先单选 target，再多选该 target 的 components。构建在执行命令的机器进行。默认不推送；`--push` 构建、验证后推送 `qc-<12位commit>`；`--dry-run` 只解析配置，不联网、不运行 Git/Docker、不创建目录。
+
+```json
+{
+  "scripts": {
+    "docker:build": "infly-libs docker:release --no-push",
+    "docker:release": "infly-libs docker:release --push"
+  },
+  "infly": {
+    "docker": {
+      "registry": "registry.example.com",
+      "targets": {
+        "demo": {
+          "label": "示例平台",
+          "components": {
+            "frontend": {
+              "label": "前端",
+              "repository": "registry.example.com/demo/web",
+              "expectedRef": "origin/master",
+              "dockerfile": "Dockerfile",
+              "files": [
+                { "from": "deploy/Dockerfile", "to": "Dockerfile" },
+                { "from": "dist", "to": "html" }
+              ],
+              "check": { "entrypoint": "nginx", "args": ["-t"] },
+              "imageEnv": "WEB_IMAGE",
+              "services": ["web"]
+            },
+            "backend": {
+              "label": "后端",
+              "repository": "registry.example.com/demo/api",
+              "source": {
+                "directory": "../api",
+                "url": "https://example.com/api.git",
+                "branch": "release/demo"
+              },
+              "dockerfile": "Dockerfile",
+              "context": ".",
+              "imageEnv": "API_IMAGE",
+              "services": ["api", "worker"]
+            }
+          },
+          "deployment": {
+            "ready": true,
+            "server": "example.com",
+            "sshUser": "ubuntu",
+            "directory": "/opt/demo",
+            "composeFile": "compose.yml",
+            "secretEnvFile": ".env",
+            "releaseEnvFile": "deploy.env",
+            "releaseComposeFile": "deploy/compose.release.yml",
+            "health": { "urls": ["https://example.com/"] }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+- `files`：从组件源码仓复制到独立临时上下文，仅发送指定产物；配置后 `dockerfile` 相对临时上下文。未配置时 `context`、`dockerfile` 相对组件源码仓。
+- `requiredFiles`：构建前必须存在的源码仓相对路径，例如前端产物的 `index.html`；缺失时停止构建。
+- `source`：可选独立源码仓；从项目目录解析 `directory`，fetch 后使用指定分支的临时 detached worktree，不切换当前开发分支。缺少源码仓时打印准备步骤，全部构建停止，CLI 返回 2。
+- 无 `source` 时构建当前项目，要求干净工作树且 HEAD 等于 `expectedRef`。有 `source` 时校验临时工作树对应的 origin 分支。
+- `check`：可选镜像内校验，使用 `entrypoint`、`args` 数组及 `addHosts` 数组；失败不推送。配置命令具有代码执行权限，应与源码一样评审，不能来自不可信输入。
+- `deployment`：仅用于部署包生成；`ready=false` 会阻止生成。可设置 `lockName`，默认 `.infly-release.lock`。服务归属和 imageEnv 必须唯一。
+- `health`：容器运行检查、可选 `exec: [{service, command: [...]}]`，以及 HTTP URL 重试；默认 attempts=12、intervalSeconds=5、timeoutSeconds=20。不要配置迁移、业务写入或数据库命令。
+- 路径、分支、镜像、服务、健康检查由项目配置决定；公共包不内置项目映射。Dockerfile、Compose、Nginx 由项目保留。
+
+```bash
+infly-libs docker:release --target demo --components frontend,backend --push
+infly-libs docker:release --platform demo --components backend --backend-dir ../api --no-push
+infly-libs docker:release --project-dir ./deployment --config docker.json --target demo --components frontend --dry-run
+infly-libs docker:bundle --target demo --output .infly-deploy-123
+infly-libs docker:bundle --target demo --dry-run
+```
+
+`--platform` 是 `--target` 的兼容别名；`--config` 读取 JSON 文件，其顶层直接为 docker 配置。CLI 参数优先于项目配置；`--backend-dir` 仅覆盖名为 backend 的组件源码目录。
+
+`docker:bundle` 只生成本地脚本包，不自动部署；输出须是项目内尚不存在的独立子目录。包内包含 config.sh、Compose 覆盖文件和公共 shell 脚本。Jenkins 固定公共包版本后生成，使用既有凭据及人工确认，调用 `deploy.sh component=repository:commit` 传输并执行；`promote-image.sh` 接受组件名、qc 镜像、正式镜像和完整 commit。运行部署脚本会操作服务器，必须由开发者手动触发既定任务。
+
+远端发布持锁后读取全部组件镜像基线，保存 .release-history，仅更新传入组件的服务（up -d --no-deps）。失败恢复镜像环境文件及选中服务；回滚验证失败明确报错。不创建/修改数据库，不更新未配置的基础设施。服务器不需要 npm/Node，仍需 Bash、Docker Compose 和 curl。

package/adapters/webpack/auto-export.js

@@ -1,56 +1,56 @@
 /**
  * Webpack require.context 适配器。
- * 自动导出目录下所有文件
- * @param {Function} requireContext - require.context 返回的函数
- * @returns {Object} 导出对象，key 为文件名（不含扩展名），value 为模块内容
- *
- * @example
- * // 在 components/Dialog/index.js 中使用
+ * 自动导出目录下所有文件
+ * @param {Function} requireContext - require.context 返回的函数
+ * @returns {Object} 导出对象，key 为文件名（不含扩展名），value 为模块内容
+ *
+ * @example
+ * // 在 components/Dialog/index.js 中使用
  * import { autoExportFiles } from '@infly/libs/adapters/webpack/auto-export';
- * const components = autoExportFiles(require.context('./', false, /\.vue$/));
- * Object.keys(components).forEach(name => {
- *   module.exports[name] = components[name];
- * });
- *
- * // 或者直接一行
- * Object.assign(module.exports, autoExportFiles(require.context('./', false, /\.vue$/)));
- */
-function autoExportFiles(requireContext) {
-  if (!requireContext || typeof requireContext !== 'function') {
-    console.error('autoExportFiles: requireContext 必须是 require.context 返回的函数');
-    return {};
-  }
-
-  const exports = {};
-
-  requireContext.keys().forEach(fileName => {
-    // 跳过 index 文件自身
-    if (fileName.includes('index')) return;
-
-    const componentConfig = requireContext(fileName);
-    const componentName = fileName
-      .replace(/^\.\//, '')        // 移除 './'
-      .replace(/\.\w+$/, '');      // 移除扩展名
-
-    exports[componentName] = componentConfig.default || componentConfig;
-  });
-
-  return exports;
-}
-
-/**
- * 简化版：直接挂载到 module.exports
- * @param {Function} requireContext - require.context 返回的函数
- * @param {Object} targetExports - 目标导出对象（通常是 module.exports）
- *
- * @example
- * // 在 components/Dialog/index.js 中使用
+ * const components = autoExportFiles(require.context('./', false, /\.vue$/));
+ * Object.keys(components).forEach(name => {
+ *   module.exports[name] = components[name];
+ * });
+ *
+ * // 或者直接一行
+ * Object.assign(module.exports, autoExportFiles(require.context('./', false, /\.vue$/)));
+ */
+function autoExportFiles(requireContext) {
+  if (!requireContext || typeof requireContext !== 'function') {
+    console.error('autoExportFiles: requireContext 必须是 require.context 返回的函数');
+    return {};
+  }
+
+  const exports = {};
+
+  requireContext.keys().forEach(fileName => {
+    // 跳过 index 文件自身
+    if (fileName.includes('index')) return;
+
+    const componentConfig = requireContext(fileName);
+    const componentName = fileName
+      .replace(/^\.\//, '')        // 移除 './'
+      .replace(/\.\w+$/, '');      // 移除扩展名
+
+    exports[componentName] = componentConfig.default || componentConfig;
+  });
+
+  return exports;
+}
+
+/**
+ * 简化版：直接挂载到 module.exports
+ * @param {Function} requireContext - require.context 返回的函数
+ * @param {Object} targetExports - 目标导出对象（通常是 module.exports）
+ *
+ * @example
+ * // 在 components/Dialog/index.js 中使用
  * import { autoExportToModule } from '@infly/libs/adapters/webpack/auto-export';
- * autoExportToModule(require.context('./', false, /\.vue$/), module.exports);
- */
-function autoExportToModule(requireContext, targetExports) {
-  const files = autoExportFiles(requireContext);
-  Object.assign(targetExports, files);
-}
-
-export { autoExportFiles, autoExportToModule };
+ * autoExportToModule(require.context('./', false, /\.vue$/), module.exports);
+ */
+function autoExportToModule(requireContext, targetExports) {
+  const files = autoExportFiles(requireContext);
+  Object.assign(targetExports, files);
+}
+
+export { autoExportFiles, autoExportToModule };

package/bin/cli.js

@@ -99,6 +99,18 @@ function parseProjectArgs(argv) {
 async function main(argv = process.argv.slice(2)) {
   const command = argv[0];
   const commandMap = {
+    "docker:bundle": () => {
+      const { parseReleaseArgs } = require("../build/docker/target-release");
+      const result = require("../build/docker/deployment-bundle").createDeploymentBundle(parseReleaseArgs(argv.slice(1)));
+      console.log(JSON.stringify(result, null, 2));
+      return result;
+    },
+    "docker:release": async () => {
+      const { parseReleaseArgs, runTargetRelease } = require("../build/docker/target-release");
+      const result = await runTargetRelease(parseReleaseArgs(argv.slice(1)));
+      if (result.missingSources?.length) process.exitCode = 2;
+      return result;
+    },
     afterBuild: () => loadBuildDist().init(),
     initZip: () => loadBuildDist().init(),
     preview: () => loadPreview().init(),

package/build/build-utils/command.js

@@ -1,57 +1,57 @@
-const { spawn } = require("child_process");
-
-function run(command, args, options = {}) {
-  return new Promise((resolve, reject) => {
-    const useShell = options.shell !== undefined ? options.shell : process.platform === "win32";
-    // Avoid DEP0190: when shell=true, pass command+args as single string
-    const [cmd, cmdArgs] = useShell
-      ? [[command, ...args].join(" "), []]
-      : [command, args];
-    const child = spawn(cmd, cmdArgs, {
-      cwd: options.cwd || process.cwd(),
-      env: {
-        ...process.env,
-        ...(options.env || {})
-      },
-      stdio: options.stdio || "inherit",
-      shell: useShell
-    });
-
-    child.on("close", (code) => {
-      if (code === 0) {
-        resolve();
-      } else {
-        reject(new Error(`${command} ${args.join(" ")} failed with exit code ${code}`));
-      }
-    });
-
-    child.on("error", reject);
-  });
-}
-
-function spawnBackground(command, args, options = {}) {
-  const useShell = options.shell !== undefined ? options.shell : process.platform === "win32";
-  const [cmd, cmdArgs] = useShell
-    ? [[command, ...args].join(" "), []]
-    : [command, args];
-  const child = spawn(cmd, cmdArgs, {
-    cwd: options.cwd || process.cwd(),
-    env: {
-      ...process.env,
-      ...(options.env || {})
-    },
-    stdio: options.stdio || "inherit",
-    shell: useShell
-  });
-
-  child.on("error", (error) => {
-    console.error(error.message);
-  });
-
-  return child;
-}
-
-module.exports = {
-  run,
-  spawnBackground
-};
+const { spawn } = require("child_process");
+
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const useShell = options.shell !== undefined ? options.shell : process.platform === "win32";
+    // Avoid DEP0190: when shell=true, pass command+args as single string
+    const [cmd, cmdArgs] = useShell
+      ? [[command, ...args].join(" "), []]
+      : [command, args];
+    const child = spawn(cmd, cmdArgs, {
+      cwd: options.cwd || process.cwd(),
+      env: {
+        ...process.env,
+        ...(options.env || {})
+      },
+      stdio: options.stdio || "inherit",
+      shell: useShell
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`${command} ${args.join(" ")} failed with exit code ${code}`));
+      }
+    });
+
+    child.on("error", reject);
+  });
+}
+
+function spawnBackground(command, args, options = {}) {
+  const useShell = options.shell !== undefined ? options.shell : process.platform === "win32";
+  const [cmd, cmdArgs] = useShell
+    ? [[command, ...args].join(" "), []]
+    : [command, args];
+  const child = spawn(cmd, cmdArgs, {
+    cwd: options.cwd || process.cwd(),
+    env: {
+      ...process.env,
+      ...(options.env || {})
+    },
+    stdio: options.stdio || "inherit",
+    shell: useShell
+  });
+
+  child.on("error", (error) => {
+    console.error(error.message);
+  });
+
+  return child;
+}
+
+module.exports = {
+  run,
+  spawnBackground
+};