@infly/libs 2.0.53 → 2.1.0

package/build/docker/deployment/release.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+bundle_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)
+source "$bundle_dir/config.sh"
+[[ $# -gt 0 ]] || { echo '需要组件=正式镜像参数' >&2; exit 2; }
+cd "$project_dir"
+for file in "$compose_file" "$secret_env_file" "$release_env_file" "$bundle_dir/docker-compose.release.yml"; do
+  [[ -f "$file" ]] || { echo "部署缺少文件: $file" >&2; exit 1; }
+done
+# 先持有目录锁再读基线，避免前后端两个任务同时发布时使用过期基线。
+mkdir "$lock_dir" 2>/dev/null || { echo "已有发布任务持有锁: $project_dir/$lock_dir" >&2; exit 1; }
+next_env=""
+cleanup() { [[ -z "$next_env" ]] || rm -f -- "$next_env"; rmdir "$lock_dir" 2>/dev/null || true; }
+trap cleanup EXIT
+current_images=()
+next_images=()
+selected_indexes=()
+selected_services=()
+for i in "${!component_names[@]}"; do
+  key=${image_keys[$i]}
+  [[ "$(grep -c "^${key}=" "$release_env_file" || true)" == 1 ]] || { echo "基线必须包含唯一 $key" >&2; exit 1; }
+  image=$(grep "^${key}=" "$release_env_file"); image=${image#*=}
+  suffix=${image#"${repositories[$i]}"}
+  [[ "$image" != "$suffix" && ( "$suffix" =~ ^:[0-9a-f]{12}$ || "$suffix" =~ ^@sha256:[0-9a-f]{64}$ ) ]] || {
+    echo "当前基线不是配置仓库的不可变镜像: $key" >&2; exit 1;
+  }
+  current_images+=("$image"); next_images+=("$image")
+done
+for pair in "$@"; do
+  [[ "$pair" == *=* ]] || { echo '参数必须是组件=镜像' >&2; exit 2; }
+  name=${pair%%=*}; image=${pair#*=}; found=false
+  for i in "${!component_names[@]}"; do
+    [[ "$name" == "${component_names[$i]}" ]] || continue
+    found=true
+    for selected in "${selected_indexes[@]}"; do [[ "$selected" != "$i" ]] || { echo '组件重复' >&2; exit 2; }; done
+    suffix=${image#"${repositories[$i]}:"}
+    [[ "$suffix" != "$image" && "$suffix" =~ ^[0-9a-f]{12}$ ]] || { echo "只接受本组件正式 commit 镜像: $name" >&2; exit 1; }
+    next_images[$i]=$image
+    selected_indexes+=("$i")
+    read -r -a group <<< "${service_groups[$i]}"
+    selected_services+=("${group[@]}")
+  done
+  [[ "$found" == true ]] || { echo "未配置的组件: $name" >&2; exit 2; }
+done
+umask 077
+mkdir -p .release-history
+previous_env=$(mktemp ".release-history/deploy-${target}-$(date -u +%Y%m%dT%H%M%SZ)-XXXXXX.env")
+cp -- "$release_env_file" "$previous_env"
+chmod 600 "$previous_env"
+next_env=$(mktemp "${release_env_file}.next.XXXXXX")
+# 发布环境文件仅保存配置声明的镜像，敏感值仍由独立环境文件提供。
+for i in "${!image_keys[@]}"; do printf '%s=%s\n' "${image_keys[$i]}" "${next_images[$i]}"; done > "$next_env"
+compose=(docker compose --env-file "$secret_env_file" --env-file "$next_env" -f "$compose_file" -f "$bundle_dir/docker-compose.release.yml")
+"${compose[@]}" config --quiet
+"${compose[@]}" pull "${selected_services[@]}"
+for i in "${selected_indexes[@]}"; do
+  image=${next_images[$i]}; short=${image##*:}
+  full=$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$image")
+  [[ "$full" =~ ^[0-9a-f]{40}$ && "${full:0:12}" == "$short" ]] || { echo "镜像 revision 校验失败: $image" >&2; exit 1; }
+done
+mv -f -- "$next_env" "$release_env_file"
+next_env=""
+compose=(docker compose --env-file "$secret_env_file" --env-file "$release_env_file" -f "$compose_file" -f "$bundle_dir/docker-compose.release.yml")
+rollback() {
+  echo "发布失败，恢复基线: $previous_env" >&2
+  cp -- "$previous_env" "$release_env_file"
+  chmod 600 "$release_env_file"
+  if ! "${compose[@]}" up -d --no-deps "${selected_services[@]}" || ! bash "$bundle_dir/health-check.sh"; then
+    echo "自动回滚未通过验证，需人工恢复: $project_dir/$previous_env" >&2
+  fi
+}
+if ! "${compose[@]}" up -d --no-deps "${selected_services[@]}"; then rollback; exit 1; fi
+if ! bash "$bundle_dir/health-check.sh"; then rollback; exit 1; fi
+echo "发布成功: $target; 上一版本记录: $project_dir/$previous_env"

package/build/docker/deployment-bundle.js

@@ -0,0 +1,87 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const quote = (value) => "'" + String(value).replaceAll("'", "'\\''") + "'";
+const array = (name, values) => `${name}=(${values.map(quote).join(" ")})`;
+function required(value, name, pattern) {
+  if (typeof value !== "string" || !value || (pattern && !pattern.test(value))) throw new Error(`部署配置无效: ${name}`);
+  return value;
+}
+
+function renderDeploymentConfig(config, target) {
+  const profile = config?.targets?.[target];
+  const deploy = profile?.deployment;
+  if (!deploy || deploy.ready !== true) throw new Error(`平台 ${target} 尚未完成人工服务器核验，禁止生产发布`);
+  const components = Object.entries(profile.components || {});
+  if (!components.length) throw new Error("部署必须配置 components");
+  const repositories = [], keys = [], serviceGroups = [];
+  for (const [name, component] of components) {
+    required(name, "component", /^[a-z][a-z0-9_-]*$/);
+    const repository = required(component.repository, `${name}.repository`, /^[a-z0-9][a-z0-9.:/_-]+$/);
+    if (repository.split("/").at(-1).includes(":")) throw new Error("镜像仓库不得带标签");
+    repositories.push(repository);
+    keys.push(required(component.imageEnv, `${name}.imageEnv`, /^[A-Z][A-Z0-9_]*$/));
+    if (!Array.isArray(component.services) || !component.services.length) throw new Error(`${name} 缺少 services`);
+    serviceGroups.push(component.services.map((service) => required(service, "service", /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/)).join(" "));
+  }
+  if (new Set(keys).size !== keys.length) throw new Error("imageEnv 不得重复");
+  const allServices = serviceGroups.flatMap((group) => group.split(" "));
+  if (new Set(allServices).size !== allServices.length) throw new Error("组件不能重复拥有同一个服务");
+  const lines = ["# 由 @infly/libs 根据项目配置生成；只含非敏感参数。",
+    `target=${quote(required(target, "target", /^[a-zA-Z0-9_-]+$/))}`,
+    `registry=${quote(required(config.registry, "registry", /^[a-zA-Z0-9.:-]+$/))}`,
+    `server=${quote(required(deploy.server, "server", /^[a-zA-Z0-9][a-zA-Z0-9.-]*$/))}`,
+    `ssh_user=${quote(required(deploy.sshUser, "sshUser", /^[a-z_][a-z0-9_-]*$/))}`,
+    `project_dir=${quote(required(deploy.directory, "directory", /^\/(?!$)[a-zA-Z0-9_./-]+$/))}`,
+    ...[["compose_file", "composeFile"], ["secret_env_file", "secretEnvFile"], ["release_env_file", "releaseEnvFile"]].map(([shell, json]) => {
+      const value = required(deploy[json], json, /^[a-zA-Z0-9_./-]+$/);
+      if (value.startsWith("/") || value.split("/").includes("..")) throw new Error(`${json} 必须位于部署目录内`);
+      return `${shell}=${quote(value)}`;
+    }),
+    `lock_dir=${quote(required(deploy.lockName || ".infly-release.lock", "lockName", /^\.[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*$/))}`,
+    array("component_names", components.map(([name]) => name)), array("repositories", repositories),
+    array("image_keys", keys), array("service_groups", serviceGroups), array("health_services", allServices),
+  ];
+  const health = deploy.health || {};
+  if (!Array.isArray(health.urls) || !health.urls.length) throw new Error("必须配置 health.urls");
+  for (const url of health.urls) if (!/^https?:\/\//.test(url)) throw new Error("健康检查 URL 必须是 HTTP(S)");
+  lines.push(array("health_urls", health.urls));
+  for (const [shell, value] of [["health_attempts", health.attempts ?? 12], ["health_interval", health.intervalSeconds ?? 5], ["health_timeout", health.timeoutSeconds ?? 20]]) {
+    if (!Number.isInteger(value) || value < 1 || value > 300) throw new Error(`${shell} 必须为 1 至 300 的整数`);
+    lines.push(`${shell}=${value}`);
+  }
+  lines.push("check_application() {");
+  for (const check of health.exec || []) {
+    if (!allServices.includes(check.service) || !Array.isArray(check.command) || !check.command.length
+      || !check.command.every((arg) => typeof arg === "string" && !arg.includes("\0"))) throw new Error("health.exec 必须绑定已配置服务和命令数组");
+    lines.push(`  "\${compose[@]}" exec -T ${quote(check.service)} ${check.command.map(quote).join(" ")} || return $?`);
+  }
+  lines.push("  return 0", "}");
+  return lines.join("\n") + "\n";
+}
+
+function createDeploymentBundle(options = {}) {
+  const projectDir = path.resolve(options.projectDir || process.cwd());
+  const config = options.configObject || (options.config
+    ? JSON.parse(fs.readFileSync(path.resolve(projectDir, options.config), "utf8"))
+    : JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8")).infly?.docker);
+  const rendered = renderDeploymentConfig(config, options.target);
+  if (options.dryRun) return { target: options.target, config: rendered };
+  const output = path.resolve(projectDir, options.output || ".infly-deploy");
+  const relative = path.relative(projectDir, output);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error("输出必须是项目内独立子目录");
+  // 每次生成独立发布包，拒绝覆盖用户文件或上次中断的部署包。
+  if (fs.existsSync(output)) throw new Error(`输出目录已存在，请先人工处理: ${output}`);
+  const overlay = path.resolve(projectDir, config.targets[options.target].deployment.releaseComposeFile || "");
+  const overlayRelative = path.relative(projectDir, overlay);
+  if (overlayRelative.startsWith("..") || path.isAbsolute(overlayRelative) || !fs.statSync(overlay).isFile()) throw new Error("releaseComposeFile 必须是项目内文件");
+  fs.mkdirSync(output, { recursive: true });
+  for (const name of ["release.sh", "health-check.sh", "deploy.sh", "promote-image.sh"]) {
+    fs.writeFileSync(path.join(output, name), fs.readFileSync(path.join(__dirname, "deployment", name), "utf8").replaceAll("\r\n", "\n"));
+  }
+  fs.writeFileSync(path.join(output, "config.sh"), rendered, { mode: 0o600 });
+  fs.copyFileSync(overlay, path.join(output, "docker-compose.release.yml"));
+  return { target: options.target, output };
+}
+
+module.exports = { renderDeploymentConfig, createDeploymentBundle };

package/build/docker/target-release.js

@@ -0,0 +1,180 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { execFileSync } = require("node:child_process");
+const { EXIT_SELECTION, selectOption, selectOptions } = require("../../cli/select-option");
+
+function parseReleaseArgs(argv) {
+  const options = { push: false };
+  const keys = { "--target": "target", "--platform": "target", "--components": "components",
+    "--project-dir": "projectDir", "--backend-dir": "backendDir", "--config": "config", "--output": "output" };
+  for (let i = 0; i < argv.length; i++) {
+    const [flag, ...suffix] = argv[i].split("=");
+    if (flag === "--") continue;
+    if (["--push", "--no-push", "--dry-run"].includes(flag) && suffix.length === 0) {
+      if (flag === "--dry-run") options.dryRun = true;
+      else options.push = flag === "--push";
+      continue;
+    }
+    if (!keys[flag]) throw new Error(`不支持的参数: ${argv[i]}`);
+    const value = suffix.length ? suffix.join("=") : argv[++i];
+    if (!value || value.startsWith("--")) throw new Error(`${flag} 缺少参数值`);
+    options[keys[flag]] = flag === "--components" ? value.split(",") : value;
+  }
+  return options;
+}
+
+function inside(root, relative) {
+  if (typeof relative !== "string" || !relative || path.isAbsolute(relative)) throw new Error(`必须配置相对路径: ${relative}`);
+  const result = path.resolve(root, relative);
+  const offset = path.relative(root, result);
+  if (offset === ".." || offset.startsWith(`..${path.sep}`)) throw new Error(`路径越界: ${relative}`);
+  return result;
+}
+
+function validateComponent(component, name) {
+  if (!component || !/^[a-z0-9][a-z0-9._:/-]*$/.test(component.repository || "") || component.repository.includes("@")) {
+    throw new Error(`${name} 必须配置有效的镜像 repository（不含标签）`);
+  }
+  if (component.repository.split("/").at(-1).includes(":")) throw new Error(`${name} repository 不得包含标签`);
+  if (!component.expectedRef && !component.source?.branch) throw new Error(`${name} 必须配置 expectedRef 或 source.branch`);
+  if (component.source && (!component.source.directory || !component.source.branch || component.source.branch.startsWith("-"))) {
+    throw new Error(`${name} source 必须配置 directory 和 branch`);
+  }
+  inside("/config", component.dockerfile || "Dockerfile");
+  inside("/config", component.context || ".");
+  if (component.requiredFiles) {
+    if (!Array.isArray(component.requiredFiles)) throw new Error(`${name} requiredFiles 必须是数组`);
+    for (const file of component.requiredFiles) inside("/config", file);
+  }
+  if (component.files) {
+    if (!Array.isArray(component.files) || component.files.length === 0) throw new Error(`${name} files 必须是非空数组`);
+    for (const file of component.files) { inside("/config", file.from); inside("/config", file.to); }
+  }
+  if (component.check) {
+    const { entrypoint, args, addHosts = [] } = component.check;
+    if (typeof entrypoint !== "string" || !entrypoint || !Array.isArray(args)
+      || !args.every((arg) => typeof arg === "string") || !Array.isArray(addHosts)
+      || !addHosts.every((host) => typeof host === "string" && host.includes(":"))) {
+      throw new Error(`${name} check 必须配置 entrypoint、args 数组及可选 addHosts 数组`);
+    }
+  }
+}
+
+function execute(command, args, options = {}) {
+  return execFileSync(command, args, { stdio: "inherit", ...options });
+}
+
+async function runTargetRelease(options = {}, dependencies = {}) {
+  const projectDir = path.resolve(options.projectDir || process.cwd());
+  const config = options.configObject || (options.config
+    ? JSON.parse(fs.readFileSync(path.resolve(projectDir, options.config), "utf8"))
+    : JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8")).infly?.docker);
+  const targets = config?.targets;
+  if (!targets || !Object.keys(targets).length) throw new Error("请配置 infly.docker.targets");
+  const log = dependencies.log || console.log;
+  const target = options.target || await (dependencies.selectOption || selectOption)("请选择构建平台",
+    Object.entries(targets).filter(([, value]) => value.components).map(([value, item]) => ({ value, label: item.label || value })));
+  if (target === EXIT_SELECTION) return { cancelled: true };
+  const profile = targets[target];
+  if (!profile?.components) throw new Error(`平台 ${target} 未配置 components`);
+  const components = options.components || await (dependencies.selectOptions || selectOptions)("请选择构建范围",
+    Object.entries(profile.components).map(([value, item]) => ({ value, label: item.label || value })));
+  if (components === EXIT_SELECTION) return { cancelled: true };
+  if (!Array.isArray(components) || !components.length || new Set(components).size !== components.length) {
+    throw new Error("请至少选择一个构建范围，且不能重复");
+  }
+  const plan = components.map((name) => {
+    if (!Object.hasOwn(profile.components, name)) throw new Error(`不支持的构建范围: ${name}`);
+    const component = profile.components[name];
+    validateComponent(component, name);
+    return { name, ...component, source: component.source && { ...component.source,
+      directory: path.resolve(projectDir, name === "backend" && options.backendDir ? options.backendDir : component.source.directory) } };
+  });
+  // dry-run 只解析配置，不联网、不调用 Git/Docker、不创建临时目录。
+  if (options.dryRun) { log(JSON.stringify({ target, push: Boolean(options.push), plan }, null, 2)); return { target, plan }; }
+  const io = dependencies.fs || fs;
+  const run = dependencies.run || execute;
+  const capture = (command, args) => String(run(command, args, { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) || "").trim();
+  // 全部组件先预检，缺少独立源码仓时不先推送部分镜像。
+  const missing = plan.filter((item) => item.source && !io.existsSync(path.join(item.source.directory, ".git")));
+  if (missing.length) {
+    for (const item of missing) {
+      const source = item.source;
+      log(`未找到 ${item.name} 源码仓: ${source.directory}`);
+      log(`请在 ${projectDir} 准备源码仓后重新运行：`);
+      if (source.url) log(`git clone "${source.url}" "${source.directory}"`);
+      log(`git -C "${source.directory}" fetch origin "${source.branch}"`);
+      const overrides = `${options.backendDir ? ` --backend-dir "${options.backendDir}"` : ""}${options.config ? ` --config "${options.config}"` : ""}`;
+      log(`infly-libs docker:release --project-dir "${projectDir}" --target ${target} --components ${components.join(",")}${overrides} ${options.push ? "--push" : "--no-push"}`);
+    }
+    return { target, missingSources: missing.map((item) => item.name) };
+  }
+  run("docker", ["info"], { cwd: projectDir });
+  run("docker", ["buildx", "version"], { cwd: projectDir });
+  const results = [];
+  for (const item of plan) {
+    let tempRoot;
+    let worktree;
+    let sourceDir = projectDir;
+    try {
+      if (item.source) {
+        run("git", ["-C", item.source.directory, "fetch", "origin"], { cwd: projectDir });
+        tempRoot = io.mkdtempSync(path.join(os.tmpdir(), "infly-image-"));
+        const candidate = path.join(tempRoot, "source");
+        run("git", ["-C", item.source.directory, "worktree", "add", "--detach", candidate, `origin/${item.source.branch}`], { cwd: projectDir });
+        worktree = candidate;
+        sourceDir = worktree;
+      }
+      const git = (...args) => capture("git", ["-C", sourceDir, ...args]);
+      if (git("status", "--porcelain", "--untracked-files=all")) throw new Error(`${item.name} 仓库存在未提交改动`);
+      const commit = git("rev-parse", "HEAD").toLowerCase();
+      const expectedRef = item.source ? `origin/${item.source.branch}` : item.expectedRef;
+      if (!/^[a-f0-9]{40}$/.test(commit) || commit !== git("rev-parse", `${expectedRef}^{commit}`).toLowerCase()) {
+        throw new Error(`${item.name} HEAD 与 ${expectedRef} 不一致，请先核对并 fetch 对应仓库`);
+      }
+      let context = inside(sourceDir, item.context || ".");
+      let dockerfile = inside(sourceDir, item.dockerfile || "Dockerfile");
+      for (const file of item.requiredFiles || []) {
+        if (!io.existsSync(inside(sourceDir, file))) throw new Error(`缺少必需构建产物: ${file}`);
+      }
+      if (item.files) {
+        tempRoot ||= io.mkdtempSync(path.join(os.tmpdir(), "infly-image-"));
+        context = path.join(tempRoot, "context");
+        io.mkdirSync(context, { recursive: true });
+        for (const file of item.files) {
+          const from = inside(sourceDir, file.from);
+          const to = inside(context, file.to);
+          // 仅复制配置声明的产物，避免把整个 monorepo 发送给 Docker。
+          io.mkdirSync(path.dirname(to), { recursive: true });
+          io.cpSync(from, to, { recursive: true, dereference: false });
+        }
+        dockerfile = inside(context, item.dockerfile || "Dockerfile");
+      }
+      if (!io.existsSync(dockerfile)) throw new Error(`缺少 Dockerfile: ${dockerfile}`);
+      const short = commit.slice(0, 12);
+      const image = `${item.repository}:qc-${short}`;
+      run("docker", ["buildx", "build", "--load", "--file", dockerfile,
+        "--label", `org.opencontainers.image.revision=${commit}`, "--label", `org.opencontainers.image.version=${short}`,
+        "--label", `com.infly.platform=${target}`, "--tag", image, context], { cwd: projectDir });
+      if (capture("docker", ["image", "inspect", "--format", '{{ index .Config.Labels "org.opencontainers.image.revision" }}', image]) !== commit) {
+        throw new Error(`${item.name} 镜像 revision 校验失败`);
+      }
+      if (item.check) {
+        const hosts = (item.check.addHosts || []).flatMap((host) => ["--add-host", host]);
+        run("docker", ["run", "--rm", ...hosts, "--entrypoint", item.check.entrypoint, image, ...item.check.args], { cwd: projectDir });
+      }
+      if (options.push) run("docker", ["push", image], { cwd: projectDir });
+      log(`${item.name}_commit=${commit}`);
+      log(`${item.name}=${image}`);
+      results.push({ component: item.name, commit, image, pushed: Boolean(options.push) });
+    } finally {
+      // 只移除本次创建的隔离 worktree；清理失败保留目录供人工恢复，绝不清空开发工作区。
+      if (worktree) run("git", ["-C", item.source.directory, "worktree", "remove", "--force", worktree], { cwd: projectDir });
+      if (tempRoot) io.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  }
+  return { target, results };
+}
+
+module.exports = { parseReleaseArgs, runTargetRelease };

package/build/project-files.js

@@ -3,53 +3,53 @@ const path = require("path");
 
 // 兼容旧 tools/file-process.js 的 __dirname 路径语义。
 const legacyToolsDir = path.resolve(__dirname, "../tools");
-
-/**
- * 覆盖写入构建脚本
- * @param {String} filePath - 覆盖文件路径
- * @param {Array | Object} scriptsList - 写入脚本配置
- * @param {String} 更新字段值
- */
-function scriptWrite(filePath, scriptsList, updateKey = "scripts") {
-  const pkg = JSON.parse(fs.readFileSync(filePath));
-  pkg[updateKey] = pkg[updateKey] || {};
-  if (Array.isArray(scriptsList)) {
-    scriptsList.forEach(item => {
-      if (pkg[updateKey][item.key]) {
-        pkg[updateKey][`origin:${item.key}`] = pkg[updateKey][item.key];
-      }
-      pkg[updateKey][item.key] = item.value;
-    });
-  } else if (typeof scriptsList === "object") {
-    pkg[updateKey] = scriptsList;
-  }
-
-  fs.writeFileSync(filePath, JSON.stringify(pkg, null, 2));
-}
-
-/**
- * 获取文件绝对路径
- * @param {String} filePath - 文件路径
- * @returns
- */
-function targetProjectFileResolve(filePath) {
-  // 初始脚本自动执行路径会自动读取node_modules
-  const projectRoot = process.cwd();
-  const absoluteProjectRoot = projectRoot.replace(/\\node_modules.*$/g, "");
-  return path.resolve(absoluteProjectRoot, filePath);
-}
-
-/**
- * 获取文件绝对路径
- * @param {String} filePath - 文件路径
- * @returns
- */
+
+/**
+ * 覆盖写入构建脚本
+ * @param {String} filePath - 覆盖文件路径
+ * @param {Array | Object} scriptsList - 写入脚本配置
+ * @param {String} 更新字段值
+ */
+function scriptWrite(filePath, scriptsList, updateKey = "scripts") {
+  const pkg = JSON.parse(fs.readFileSync(filePath));
+  pkg[updateKey] = pkg[updateKey] || {};
+  if (Array.isArray(scriptsList)) {
+    scriptsList.forEach(item => {
+      if (pkg[updateKey][item.key]) {
+        pkg[updateKey][`origin:${item.key}`] = pkg[updateKey][item.key];
+      }
+      pkg[updateKey][item.key] = item.value;
+    });
+  } else if (typeof scriptsList === "object") {
+    pkg[updateKey] = scriptsList;
+  }
+
+  fs.writeFileSync(filePath, JSON.stringify(pkg, null, 2));
+}
+
+/**
+ * 获取文件绝对路径
+ * @param {String} filePath - 文件路径
+ * @returns
+ */
+function targetProjectFileResolve(filePath) {
+  // 初始脚本自动执行路径会自动读取node_modules
+  const projectRoot = process.cwd();
+  const absoluteProjectRoot = projectRoot.replace(/\\node_modules.*$/g, "");
+  return path.resolve(absoluteProjectRoot, filePath);
+}
+
+/**
+ * 获取文件绝对路径
+ * @param {String} filePath - 文件路径
+ * @returns
+ */
 function currentProjectFileResolve(filePath) {
   return path.join(legacyToolsDir, filePath);
 }
-
-module.exports = {
-  scriptWrite,
-  targetProjectFileResolve,
-  currentProjectFileResolve
-};
+
+module.exports = {
+  scriptWrite,
+  targetProjectFileResolve,
+  currentProjectFileResolve
+};

package/cli/progress.js

@@ -14,6 +14,7 @@ function createProgressReporter(options = {}) {
     status: "检查状态",
     deinit: "停用模块",
     init: "模块加载",
+    remote: "更新远端",
   };
   const labels = { ...defaultLabels, ...options.labels };
   return (event) => {
@@ -44,6 +45,7 @@ function formatSwitchSummary(name, totalMs, dependencyResult, timings) {
     status: "状态",
     deinit: "停用",
     init: "加载",
+    remote: "远端",
     install: "依赖",
   };
   const phases = Object.entries(labels)

package/cli/project-command.js

@@ -1,5 +1,5 @@
 // 配置驱动的公共项目命令编排。
-const { execFileSync } = require("node:child_process");
+const { spawn, spawnSync } = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
 
@@ -77,17 +77,101 @@ function commandParts(command) {
   return { command: parts[0], args: parts.slice(1) };
 }
 
-function defaultRunCommand(command, args, options) {
-  // Windows: node_modules/.bin 的 npm-script 命令是 .CMD 批处理垫片，
-  // execFileSync 无 shell 时 CreateProcess 只解析 .exe → ENOENT；与 build-utils/command.js 约定一致。
-  const useShell = process.platform === "win32";
+function attachChildLifecycle(child, command, resolve, reject) {
+  // 把子进程的生命周期（信号转发/退出语义）挂接到一个已启动的 child 上。
+  const forwardSignal = (signal) => {
+    try {
+      child.kill(signal);
+    } catch {
+      // 子进程已退出时忽略转发失败
+    }
+    // Windows 下 cmd 批处理在 Ctrl+C 时会弹"终止批处理操作吗(Y/N)?"等待输入，主进程等
+    // 子进程 exit 会永久阻塞；补杀整棵进程树（taskkill /T）并立即退出主进程，保证终端干净。
+    if (process.platform === "win32" && child.pid) {
+      try {
+        spawnSync("taskkill", ["/T", "/F", "/PID", String(child.pid)], {
+          stdio: "ignore",
+          windowsHide: true,
+        });
+      } catch {
+        // taskkill 失败不影响退出：子进程可能已结束
+      }
+    }
+    process.exit(0);
+  };
+  process.once("SIGINT", forwardSignal);
+  process.once("SIGTERM", forwardSignal);
+
+  const cleanup = () => {
+    process.removeListener("SIGINT", forwardSignal);
+    process.removeListener("SIGTERM", forwardSignal);
+  };
+
+  child.on("error", (error) => {
+    cleanup();
+    reject(error);
+  });
+  child.on("exit", (code, signal) => {
+    cleanup();
+    // 被信号终止（如用户 Ctrl+C）视为正常结束：dev server 由中断信号退出，
+    // 主进程随后返回，CLI 自然退出，不将 Ctrl+C 视为命令失败。
+    if (code === 0 || signal) {
+      resolve({ signal: signal || null });
+      return;
+    }
+    const error = new Error(`Command failed with exit code ${code ?? "unknown"}: ${command}`);
+    error.code = code;
+    reject(error);
+  });
+}
+
+function spawnCommand(command, args, options, useShell) {
   // shell=true 时按 build-utils/command.js 约定传单字符串，规避 DEP0190
   const [cmd, cmdArgs] = useShell ? [[command, ...args].join(" "), []] : [command, args];
-  execFileSync(cmd, cmdArgs, {
-    cwd: options.cwd,
-    env: options.env,
-    stdio: "inherit",
-    shell: useShell,
+  // 用 spawn（异步、非阻塞）替代 execFileSync：dev 场景（长驻进程）下，
+  // execFileSync 同步阻塞 + 多层 cmd/pnpm 嵌套在 Windows 上 Ctrl+C 后易留孤儿进程占用终端与端口。
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, cmdArgs, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: "inherit",
+      shell: useShell,
+    });
+    attachChildLifecycle(child, command, resolve, reject);
+  });
+}
+
+function defaultRunCommand(command, args, options) {
+  // 非 Windows 统一走无 shell 形态。
+  if (process.platform !== "win32") {
+    return spawnCommand(command, args, options, false);
+  }
+  // Windows: 先尝试无 shell 直跑（.exe，如 node）——避免 cmd 批处理层在 Ctrl+C 时弹
+  // "终止批处理操作吗(Y/N)?" 等待输入；.CMD 垫片（如 pnpm/npm）无 shell 会 ENOENT，回退 cmd shell。
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: "inherit",
+      shell: false,
+    });
+    let settled = false;
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      if (error.code === "ENOENT") {
+        // .cmd/.bat 垫片：回退 cmd shell（保留原有行为）
+        spawnCommand(command, args, options, true).then(resolve, reject);
+        return;
+      }
+      reject(error);
+    });
+    child.once("spawn", () => {
+      if (settled) return;
+      settled = true;
+      // 无 shell 直跑成功：挂接生命周期到当前 child（不再二次启动）
+      attachChildLifecycle(child, command, resolve, reject);
+    });
   });
 }
 
@@ -146,7 +230,7 @@ async function runProjectCommand(options = {}, dependencies = {}) {
     const parts = commandParts(devConfig.command);
     const env = { ...process.env, VUE_APP_PLATFORM: targetName };
     if (options.dryRun) printDryRun(parts.command, parts.args, env);
-    else runCommand(parts.command, parts.args, { cwd: configDir, env });
+    else await runCommand(parts.command, parts.args, { cwd: configDir, env });
     return { action, target: targetName };
   }
 
@@ -191,7 +275,7 @@ async function runProjectCommand(options = {}, dependencies = {}) {
       const parts = commandParts(step.command);
       const args = [...parts.args, ...step.extraArgs];
       if (options.dryRun) printDryRun(parts.command, args, env);
-      else runCommand(parts.command, args, { cwd: configDir, env });
+      else await runCommand(parts.command, args, { cwd: configDir, env });
     }
   }