@sfmc-bds/cli 0.2.0-beta.13 → 0.2.0-beta.15

package/scripts/module-install/fetch-module.mjs

@@ -25,22 +25,24 @@
  *         （win32=junction，POSIX=symlink），仍同步 catalog/lock。
  */
 
+import { extractZipFileToDir } from "@sfmc-bds/bds-tools/zipx";
+import { createHash } from "node:crypto";
 import fs, { createReadStream } from "node:fs";
 import fsp from "node:fs/promises";
-import { createHash } from "node:crypto";
-import { pipeline } from "node:stream/promises";
 import path from "node:path";
 import process from "node:process";
+import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
-import { extractZipFileToDir } from "@sfmc-bds/bds-tools/zipx";
 import { runCheckModules } from "./check-modules.mjs";
-import { upsertCatalogEntry, removeCatalogEntry } from "./lib/catalog.mjs";
-import { setModuleLockEnabled, removeModuleLock } from "./lib/lock.mjs";
-import { PACKAGES_DIR, ROOT } from "./lib/paths.mjs";
+import { removeCatalogEntry, upsertCatalogEntry } from "./lib/catalog.mjs";
+import { seedModuleConfig } from "./lib/config-seeding.mjs";
 import { exists } from "./lib/io.mjs";
-import { parseRegistryIndex } from "./lib/registry-index.mjs";
 import { isSchemeFrom, normalizeBarePathFrom, normalizeLinkFrom } from "./lib/link-from.mjs";
+import { removeModuleLock, setModuleLockEnabled } from "./lib/lock.mjs";
 import { folderFromNpmPackageName } from "./lib/npm-resolver.mjs";
+import { loadPackageCatalogEntry } from "./lib/packages.mjs";
+import { PACKAGES_DIR, ROOT } from "./lib/paths.mjs";
+import { parseRegistryIndex } from "./lib/registry-index.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TARGET = PACKAGES_DIR;
@@ -105,9 +107,7 @@ async function resolveRegistryIndex() {
       );
       return { index: cache.index, stale: true };
     }
-    throw new Error(
-      `registry unreachable and no cache: ${message}. Pass --from explicitly to skip the registry.`
-    );
+    throw new Error(`registry unreachable and no cache: ${message}. Pass --from explicitly to skip the registry.`);
   }
 }
 
@@ -126,9 +126,7 @@ async function defaultSourceFor(id) {
       return `npm:${entry.npm}`;
     }
     if (entry?.repo && entry?.tag) {
-      console.log(
-        `[fetch-module] ${id} found in registry (deprecated github) → github:${entry.repo}@${entry.tag}`
-      );
+      console.log(`[fetch-module] ${id} found in registry (deprecated github) → github:${entry.repo}@${entry.tag}`);
       return `github:${entry.repo}@${entry.tag}`;
     }
   } catch {
@@ -284,11 +282,28 @@ function afterInstall(folder, opts = {}) {
     try {
       normalizeInstalledPackage(path.join(TARGET, folder));
     } catch (err) {
-      console.warn(
-        `[fetch-module] normalize warn: ${err instanceof Error ? err.message : String(err)}`
-      );
+      console.warn(`[fetch-module] normalize warn: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
+  const moduleRoot = path.join(TARGET, folder);
+  const preview = loadPackageCatalogEntry(folder);
+  if (!preview) throw new Error(`packages/${folder}: 无法读取 sapi/manifest.json`);
+  const seeded = seedModuleConfig({
+    moduleRoot,
+    projectRoot: ROOT,
+    configKey: preview.configKey,
+  });
+  const targetRel = path.relative(ROOT, seeded.target).replaceAll("\\", "/");
+  if (seeded.status === "created") {
+    console.log(`[fetch-module]   config created: ${targetRel}`);
+  } else if (seeded.status === "updated") {
+    console.log(`[fetch-module]   config updated: added ${seeded.addedPaths.join(", ")}`);
+  } else if (seeded.status === "unchanged") {
+    console.log(`[fetch-module]   config unchanged: ${targetRel}`);
+  } else {
+    console.warn(`[fetch-module]   config defaults missing: ${preview.configKey}`);
+  }
+
   const entry = upsertCatalogEntry(folder);
   setModuleLockEnabled(entry.id, entry.enabledByDefault !== false);
   console.log(`[fetch-module]   catalog+lock: ${entry.id} (enabled=${entry.enabledByDefault !== false})`);
@@ -303,6 +318,9 @@ function afterInstall(folder, opts = {}) {
   if (!check.ok) {
     throw new Error(`check-modules 未通过: ${check.error}`);
   }
+  for (const warning of check.warnings ?? []) {
+    console.warn(`[fetch-module]   check warning: ${warning}`);
+  }
   console.log(`[fetch-module]   ${check.summary}`);
   return entry;
 }
@@ -422,7 +440,7 @@ async function fromLocal(id, source, flags) {
 
 /**
  * `sfmc mod install <id>` 走 npm registry 的主路径。
- * 
+ *
  * 入口：`npm install --prefix packages/<id> --omit=dev --no-save --no-package-lock <pkgName>`
  *   - 落地到 packages/<id>，不进主仓根 node_modules（隔离安装）
  *   - 成功后 upsert catalog/lock
@@ -435,32 +453,34 @@ async function fromNpm(id, pkgName, flags) {
   const dir = await ensureTarget(id);
   const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
   const { spawn: spawnChild } = await import("node:child_process");
-  await /** @type {Promise<void>} */(new Promise((resolve, reject) => {
-    const proc = spawnChild(
-      npmCmd,
-      [
-        "install",
-        "--prefix",
-        dir,
-        "--omit=dev",
-        "--no-save",
-        "--no-package-lock",
-        "--no-audit",
-        "--no-fund",
-        pkgName,
-      ],
-      { stdio: ["ignore", "pipe", "pipe"] }
-    );
-    let stderr = "";
-    proc.stderr?.on("data", (d) => {
-      stderr += d.toString();
-    });
-    proc.on("exit", (code) => {
-      if (code === 0) return resolve();
-      reject(new Error(translateNpmInstallError(pkgName, stderr)));
-    });
-    proc.on("error", (e) => reject(new Error(`spawn npm failed: ${e.message}`)));
-  }));
+  await /** @type {Promise<void>} */ (
+    new Promise((resolve, reject) => {
+      const proc = spawnChild(
+        npmCmd,
+        [
+          "install",
+          "--prefix",
+          dir,
+          "--omit=dev",
+          "--no-save",
+          "--no-package-lock",
+          "--no-audit",
+          "--no-fund",
+          pkgName,
+        ],
+        { stdio: ["ignore", "pipe", "pipe"] }
+      );
+      let stderr = "";
+      proc.stderr?.on("data", (d) => {
+        stderr += d.toString();
+      });
+      proc.on("exit", (code) => {
+        if (code === 0) return resolve();
+        reject(new Error(translateNpmInstallError(pkgName, stderr)));
+      });
+      proc.on("error", (e) => reject(new Error(`spawn npm failed: ${e.message}`)));
+    })
+  );
   console.log(`[fetch-module] installed ${id} from npm (${pkgName})`);
   console.log(`[fetch-module]   target: ${dir}`);
   afterInstall(id);
@@ -775,7 +795,9 @@ async function extractTgz(tgzPath, dstDir) {
       stderr += d.toString();
     });
     // @ts-ignore
-    proc.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`npm install tarball exit ${code}: ${stderr}`))));
+    proc.on("exit", (code) =>
+      code === 0 ? resolve() : reject(new Error(`npm install tarball exit ${code}: ${stderr}`))
+    );
     // @ts-ignore
     proc.on("error", reject);
   });
@@ -963,7 +985,9 @@ async function main() {
     const from = flags.from;
     // @ts-ignore
     if (!from || (!from.startsWith("local") && !from.startsWith("dir:"))) {
-      die("usage: install <id> [id2 ...] [--from <source>] [--link]\n或: install --from local|dir:<path> [--link]（从包目录推导 id）");
+      die(
+        "usage: install <id> [id2 ...] [--from <source>] [--link]\n或: install --from local|dir:<path> [--link]（从包目录推导 id）"
+      );
     }
     let absDir;
     // @ts-ignore
@@ -990,7 +1014,7 @@ async function main() {
     // @ts-ignore
     if (!flags.from.startsWith("dir:") && (flags.from === "local" || flags.from.startsWith("local:"))) {
       /* 保持 local；link 时会规范成 dir: */
-    // @ts-ignore
+      // @ts-ignore
     } else if (flags.from.startsWith("dir:")) {
       /* ok */
     } else {

package/scripts/module-install/lib/config-seeding.mjs

@@ -0,0 +1,128 @@
+// @ts-check
+/** 模块默认配置播种：仅补缺，不覆盖用户已有值。 */
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const CONFIG_KEY_RE = /^[A-Za-z0-9_-]+$/;
+
+/** @param {unknown} value */
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/** @param {string} root @param {string} candidate */
+function assertWithin(root, candidate) {
+  const absRoot = path.resolve(root);
+  const absCandidate = path.resolve(candidate);
+  const rel = path.relative(absRoot, absCandidate);
+  if (rel === "" || (!rel.startsWith(".." + path.sep) && rel !== ".." && !path.isAbsolute(rel))) {
+    return absCandidate;
+  }
+  throw new Error("配置路径越界: " + absCandidate);
+}
+
+/** @param {string} file @param {string} label */
+function readObject(file, label) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(label + " JSON 解析失败: " + message);
+  }
+  if (!isPlainObject(parsed)) throw new Error(label + " 顶层必须是 JSON 对象");
+  return parsed;
+}
+
+/**
+ * @param {Record<string, unknown>} current
+ * @param {Record<string, unknown>} defaults
+ * @param {string} [prefix]
+ * @returns {{ value: Record<string, unknown>; addedPaths: string[] }}
+ */
+export function mergeMissing(current, defaults, prefix = "") {
+  const value = structuredClone(current);
+  /** @type {string[]} */
+  const addedPaths = [];
+  for (const key of Object.keys(defaults).sort()) {
+    const fieldPath = prefix ? prefix + "." + key : key;
+    if (!Object.hasOwn(value, key)) {
+      value[key] = structuredClone(defaults[key]);
+      addedPaths.push(fieldPath);
+      continue;
+    }
+    if (isPlainObject(value[key]) && isPlainObject(defaults[key])) {
+      const nested = mergeMissing(
+        /** @type {Record<string, unknown>} */ (value[key]),
+        /** @type {Record<string, unknown>} */ (defaults[key]),
+        fieldPath
+      );
+      value[key] = nested.value;
+      addedPaths.push(...nested.addedPaths);
+    }
+  }
+  return { value, addedPaths: addedPaths.sort() };
+}
+
+/**
+ * @typedef {{
+ *   status: "created" | "updated" | "unchanged" | "missing-defaults";
+ *   target: string;
+ *   addedPaths: string[];
+ * }} SeedResult
+ */
+
+/**
+ * @param {{ moduleRoot: string; projectRoot: string; configKey: string }} options
+ * @returns {SeedResult}
+ */
+export function seedModuleConfig(options) {
+  const { moduleRoot, projectRoot, configKey } = options;
+  if (!CONFIG_KEY_RE.test(configKey)) throw new Error('invalid configKey "' + configKey + '"');
+
+  const safeModuleRoot = path.resolve(moduleRoot);
+  const safeProjectRoot = path.resolve(projectRoot);
+  const source = assertWithin(safeModuleRoot, path.join(safeModuleRoot, "configs-default", configKey + ".json"));
+  const configsDir = assertWithin(safeProjectRoot, path.join(safeProjectRoot, "configs"));
+  const target = assertWithin(configsDir, path.join(configsDir, configKey + ".json"));
+  if (!fs.existsSync(source)) {
+    const defaultsDir = path.dirname(source);
+    const jsonFiles = fs.existsSync(defaultsDir)
+      ? fs.readdirSync(defaultsDir).filter((name) => name.toLowerCase().endsWith(".json"))
+      : [];
+    if (jsonFiles.length > 0) {
+      throw new Error("默认配置文件名必须为 configs-default/" + configKey + ".json，实际为 " + jsonFiles.join(", "));
+    }
+    return { status: "missing-defaults", target, addedPaths: [] };
+  }
+
+  const defaults = readObject(source, "默认配置 " + source);
+  let status = /** @type {SeedResult["status"]} */ ("created");
+  let value = defaults;
+  let addedPaths = Object.keys(defaults).sort();
+  if (fs.existsSync(target)) {
+    const current = readObject(target, "用户配置 " + target);
+    const merged = mergeMissing(current, defaults);
+    value = merged.value;
+    addedPaths = merged.addedPaths;
+    status = addedPaths.length > 0 ? "updated" : "unchanged";
+  }
+  if (status === "unchanged") return { status, target, addedPaths };
+
+  fs.mkdirSync(configsDir, { recursive: true });
+  const temp = assertWithin(configsDir, path.join(configsDir, "." + configKey + "." + randomUUID() + ".tmp"));
+  try {
+    fs.writeFileSync(temp, JSON.stringify(value, null, 2) + "\n", { encoding: "utf8", flag: "wx" });
+    fs.renameSync(temp, target);
+  } finally {
+    try {
+      fs.rmSync(temp, { force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+  return { status, target, addedPaths };
+}

package/scripts/module-install/test/check-modules-config.test.ts

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { validateDefaultConfig } from "../check-modules.mjs";
+
+function moduleFixture(files: Record<string, string> = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "sfmc-check-config-"));
+  const dir = path.join(root, "configs-default");
+  if (Object.keys(files).length > 0) fs.mkdirSync(dir, { recursive: true });
+  for (const [name, body] of Object.entries(files)) fs.writeFileSync(path.join(dir, name), body);
+  return root;
+}
+
+test("validateDefaultConfig 接受标准对象配置", () => {
+  const root = moduleFixture({ "demo.json": '{"enabled":true}' });
+  assert.deepEqual(validateDefaultConfig(root, "demo"), { ok: true });
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("validateDefaultConfig 对缺失默认配置给出警告", () => {
+  const root = moduleFixture();
+  const result = validateDefaultConfig(root, "demo");
+  assert.equal(result.ok, true);
+  if (result.ok) assert.match(result.warning ?? "", /未提供默认配置/);
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("validateDefaultConfig 拒绝错名、损坏及非对象配置", () => {
+  const wrong = moduleFixture({ "other.json": "{}" });
+  assert.deepEqual(validateDefaultConfig(wrong, "demo").ok, false);
+  fs.rmSync(wrong, { recursive: true, force: true });
+
+  const broken = moduleFixture({ "demo.json": "{" });
+  const brokenResult = validateDefaultConfig(broken, "demo");
+  assert.equal(brokenResult.ok, false);
+  if (!brokenResult.ok) assert.match(brokenResult.error, /解析失败/);
+  fs.rmSync(broken, { recursive: true, force: true });
+
+  const array = moduleFixture({ "demo.json": "[]" });
+  const arrayResult = validateDefaultConfig(array, "demo");
+  assert.equal(arrayResult.ok, false);
+  if (!arrayResult.ok) assert.match(arrayResult.error, /顶层必须是 JSON 对象/);
+  fs.rmSync(array, { recursive: true, force: true });
+});

package/scripts/module-install/test/config-seeding.test.ts

@@ -0,0 +1,99 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { mergeMissing, seedModuleConfig } from "../lib/config-seeding.mjs";
+
+function fixture(defaults?: unknown, current?: unknown) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "sfmc-config-seeding-"));
+  const moduleRoot = path.join(root, "module");
+  const projectRoot = path.join(root, "project");
+  fs.mkdirSync(path.join(moduleRoot, "configs-default"), { recursive: true });
+  if (defaults !== undefined) {
+    const body = typeof defaults === "string" ? defaults : JSON.stringify(defaults);
+    fs.writeFileSync(path.join(moduleRoot, "configs-default", "demo.json"), body);
+  }
+  if (current !== undefined) {
+    fs.mkdirSync(path.join(projectRoot, "configs"), { recursive: true });
+    const body = typeof current === "string" ? current : JSON.stringify(current);
+    fs.writeFileSync(path.join(projectRoot, "configs", "demo.json"), body);
+  }
+  return { root, moduleRoot, projectRoot, target: path.join(projectRoot, "configs", "demo.json") };
+}
+
+test("mergeMissing 递归补缺且不覆盖或修改输入", () => {
+  const current = { enabled: false, nested: { keep: 1 }, list: ["user"], extra: true };
+  const defaults = { enabled: true, nested: { keep: 0, added: 2 }, list: ["default"], fresh: "x" };
+  const before = structuredClone(current);
+  const result = mergeMissing(current, defaults);
+  assert.deepEqual(current, before);
+  assert.deepEqual(result.value, {
+    enabled: false,
+    nested: { keep: 1, added: 2 },
+    list: ["user"],
+    extra: true,
+    fresh: "x",
+  });
+  assert.deepEqual(result.addedPaths, ["fresh", "nested.added"]);
+});
+
+test("seedModuleConfig 创建、补缺与无变化", () => {
+  const f = fixture({ enabled: true, nested: { first: 1 } });
+  const created = seedModuleConfig({ ...f, configKey: "demo" });
+  assert.equal(created.status, "created");
+  assert.deepEqual(JSON.parse(fs.readFileSync(f.target, "utf8")), {
+    enabled: true,
+    nested: { first: 1 },
+  });
+
+  fs.writeFileSync(f.target, JSON.stringify({ enabled: false, nested: { first: 9 } }));
+  fs.writeFileSync(
+    path.join(f.moduleRoot, "configs-default", "demo.json"),
+    JSON.stringify({ enabled: true, nested: { first: 1, second: 2 }, list: ["default"] })
+  );
+  const updated = seedModuleConfig({ ...f, configKey: "demo" });
+  assert.equal(updated.status, "updated");
+  assert.deepEqual(updated.addedPaths, ["list", "nested.second"]);
+  assert.deepEqual(JSON.parse(fs.readFileSync(f.target, "utf8")), {
+    enabled: false,
+    nested: { first: 9, second: 2 },
+    list: ["default"],
+  });
+  assert.equal(seedModuleConfig({ ...f, configKey: "demo" }).status, "unchanged");
+  fs.rmSync(f.root, { recursive: true, force: true });
+});
+
+test("seedModuleConfig 缺失默认文件时保持兼容", () => {
+  const f = fixture();
+  assert.equal(seedModuleConfig({ ...f, configKey: "demo" }).status, "missing-defaults");
+  assert.equal(fs.existsSync(f.target), false);
+  fs.rmSync(f.root, { recursive: true, force: true });
+});
+
+test("seedModuleConfig 拒绝与 configKey 不一致的默认文件名", () => {
+  const f = fixture();
+  fs.writeFileSync(path.join(f.moduleRoot, "configs-default", "other.json"), "{}");
+  assert.throws(() => seedModuleConfig({ ...f, configKey: "demo" }), /文件名必须为/);
+  fs.rmSync(f.root, { recursive: true, force: true });
+});
+
+test("seedModuleConfig 拒绝损坏 JSON、非对象与非法 configKey", () => {
+  const brokenDefault = fixture("{");
+  assert.throws(() => seedModuleConfig({ ...brokenDefault, configKey: "demo" }), /默认配置.*解析失败/);
+  fs.rmSync(brokenDefault.root, { recursive: true, force: true });
+
+  const scalar = fixture([]);
+  assert.throws(() => seedModuleConfig({ ...scalar, configKey: "demo" }), /顶层必须是 JSON 对象/);
+  fs.rmSync(scalar.root, { recursive: true, force: true });
+
+  const brokenUser = fixture({ ok: true }, "{broken");
+  const before = fs.readFileSync(brokenUser.target);
+  assert.throws(() => seedModuleConfig({ ...brokenUser, configKey: "demo" }), /用户配置.*解析失败/);
+  assert.deepEqual(fs.readFileSync(brokenUser.target), before);
+  fs.rmSync(brokenUser.root, { recursive: true, force: true });
+
+  const invalid = fixture({});
+  assert.throws(() => seedModuleConfig({ ...invalid, configKey: "../escape" }), /invalid configKey/);
+  fs.rmSync(invalid.root, { recursive: true, force: true });
+});