@sfmc-bds/cli 0.2.5 → 0.3.0

package/scripts/module-install/lib/pins.mjs

@@ -0,0 +1,436 @@
+// @ts-check
+/**
+ * modules/module-pins.json
+ * 记录每个已装模块的来源、已装版本和是否允许自动更新。
+ * catalog 仍只投影 manifest，module-lock 仍只记启停。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { readJson, writeJson } from "./io.mjs";
+import { ROOT } from "./paths.mjs";
+import { readCachedRegistryIndex } from "./registry-cache.mjs";
+
+/**
+ * @typedef {"npm" | "github" | "link" | "local"} PinSource
+ * @typedef {"index" | "dist-tag" | "none"} PinChannel
+ * @typedef {"default" | "user"} PinAutoSetBy
+ * @typedef {{
+ *   source: PinSource,
+ *   channel: PinChannel,
+ *   spec: string,
+ *   installedVersion: string | null,
+ *   manifestId: string | null,
+ *   auto: boolean,
+ *   autoLocked: boolean,
+ *   autoSetBy: PinAutoSetBy,
+ *   lastCheckedAt: number | null,
+ *   lastAppliedAt: number | null,
+ *   lastError: string | null,
+ * }} ModulePin
+ * @typedef {{ version: number, modules: Record<string, ModulePin> }} ModulePinsFile
+ */
+
+/**
+ * 去掉 feature- / core- 前缀，让目录名和 manifest.id 能对上。
+ * @param {string | null | undefined} id
+ */
+export function normalizeModuleId(id) {
+  return String(id ?? "").replace(/^(feature|core)-/, "");
+}
+
+/**
+ * @param {string} [root]
+ */
+export function pinsFile(root = ROOT) {
+  return path.join(root, "modules", "module-pins.json");
+}
+
+/**
+ * @param {string} root
+ * @param {string} folder
+ */
+export function packageDirOf(root, folder) {
+  return path.join(root, "modules", "packages", folder);
+}
+
+/**
+ * @param {string} [root]
+ * @returns {ModulePinsFile}
+ */
+export function readPins(root = ROOT) {
+  const raw = readJson(pinsFile(root), null);
+  if (!raw || typeof raw !== "object") return { version: 1, modules: {} };
+  const modules = /** @type {Record<string, unknown>} */ (raw).modules;
+  return {
+    version: 1,
+    modules: modules && typeof modules === "object" ? /** @type {Record<string, ModulePin>} */ (modules) : {},
+  };
+}
+
+/**
+ * @param {string} root
+ * @param {ModulePinsFile} file
+ */
+export function writePins(root, file) {
+  writeJson(pinsFile(root), {
+    version: 1,
+    modules: file.modules || {},
+  });
+}
+
+/**
+ * 目录是 junction / symlink 时视为本地开发链接。
+ * @param {string} dir
+ */
+export function isLinkedPackageDir(dir) {
+  try {
+    return fs.lstatSync(dir).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} dir
+ * @returns {string | null}
+ */
+export function readPackageVersion(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    return typeof pkg.version === "string" && pkg.version.trim() ? pkg.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} dir
+ * @returns {string | null}
+ */
+export function readPackageName(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    return typeof pkg.name === "string" && pkg.name.trim() ? pkg.name.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} dir
+ * @returns {string | null}
+ */
+export function readManifestId(dir) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(dir, "sapi", "manifest.json"), "utf8"));
+    return typeof manifest.id === "string" && manifest.id.trim() ? manifest.id.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * npm spec 是否带了精确版本（@scope/name@1.2.3）。
+ * @param {string} specBody
+ */
+function npmSpecHasVersion(specBody) {
+  const slash = specBody.indexOf("/");
+  const at = specBody.indexOf("@", slash >= 0 ? slash + 1 : 0);
+  return at > 0 && specBody.slice(at + 1).length > 0;
+}
+
+/**
+ * 从本次安装的 --from 推导 pin 草稿。
+ * 带版本的 npm 先按索引钉版处理；链接和本地目录强制关闭自动更新。
+ * @param {string} from
+ * @param {boolean} link
+ * @returns {Pick<ModulePin, "source" | "channel" | "spec" | "auto" | "autoLocked">}
+ */
+export function inferPinDraft(from, link) {
+  const spec = String(from ?? "");
+  if (link) {
+    return { source: "link", channel: "none", spec, auto: false, autoLocked: true };
+  }
+  if (spec.startsWith("npm:")) {
+    const body = spec.slice("npm:".length);
+    const pinned = npmSpecHasVersion(body);
+    return {
+      source: "npm",
+      channel: pinned ? "index" : "dist-tag",
+      spec,
+      auto: false,
+      autoLocked: false,
+    };
+  }
+  if (spec.startsWith("github:")) {
+    return { source: "github", channel: "none", spec, auto: false, autoLocked: false };
+  }
+  return { source: "local", channel: "none", spec, auto: false, autoLocked: true };
+}
+
+/**
+ * 按索引重算“默认”自动更新开关。服主改过的 auto 保持不动。
+ * @param {ModulePin} pin
+ * @param {{ npm?: string, version?: string } | null | undefined} indexEntry
+ * @returns {ModulePin}
+ */
+export function reconcileDefaultAuto(pin, indexEntry) {
+  if (pin.autoLocked || pin.source === "link" || pin.source === "local") {
+    return { ...pin, auto: false, autoLocked: true };
+  }
+  if (pin.autoSetBy === "user") return pin;
+  if (pin.source === "npm" && indexEntry?.npm && indexEntry.version) {
+    return { ...pin, auto: true, channel: "index" };
+  }
+  if (pin.source === "github") return { ...pin, auto: false };
+  if (pin.channel === "dist-tag") return { ...pin, auto: false };
+  return { ...pin, auto: false };
+}
+
+/**
+ * 升级时若已有启停记录，则不要按 enabledByDefault 重写。
+ * @param {boolean} preserveLock
+ * @param {boolean} lockHasModule
+ */
+export function shouldPreserveLock(preserveLock, lockHasModule) {
+  return !!(preserveLock && lockHasModule);
+}
+
+/**
+ * @param {ModulePinsFile} file
+ * @param {string} id
+ */
+export function findPinKey(file, id) {
+  if (file.modules[id]) return id;
+  const want = normalizeModuleId(id);
+  for (const [key, pin] of Object.entries(file.modules)) {
+    if (normalizeModuleId(key) === want) return key;
+    if (pin?.manifestId && normalizeModuleId(pin.manifestId) === want) return key;
+  }
+  return null;
+}
+
+/**
+ * @param {string} root
+ * @returns {string[]}
+ */
+function listPackageFolders(root) {
+  const dir = path.join(root, "modules", "packages");
+  if (!fs.existsSync(dir)) return [];
+  /** @type {string[]} */
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (name.startsWith(".")) continue;
+    const abs = path.join(dir, name);
+    try {
+      if (fs.statSync(abs).isDirectory()) out.push(name);
+    } catch {
+      /* 跳过读不到的目录 */
+    }
+  }
+  out.sort((a, b) => a.localeCompare(b));
+  return out;
+}
+
+/**
+ * 给还没有 pin 的已装目录补一条记录。不升级。
+ * @param {string} root
+ * @param {Record<string, { npm?: string, version?: string }> | null} [index]
+ * @returns {string[]} 新补上的目录名
+ */
+export function backfillModulePins(root, index = null) {
+  const file = readPins(root);
+  /** @type {string[]} */
+  const added = [];
+  for (const folder of listPackageFolders(root)) {
+    if (file.modules[folder]) continue;
+    const dir = packageDirOf(root, folder);
+    const linked = isLinkedPackageDir(dir);
+    const name = readPackageName(dir);
+    const version = readPackageVersion(dir);
+    const manifestId = readManifestId(dir);
+    /** @type {ModulePin} */
+    let pin;
+    if (linked) {
+      pin = {
+        source: "link",
+        channel: "none",
+        spec: "",
+        installedVersion: version,
+        manifestId,
+        auto: false,
+        autoLocked: true,
+        autoSetBy: "default",
+        lastCheckedAt: null,
+        lastAppliedAt: null,
+        lastError: null,
+      };
+    } else if (name) {
+      pin = {
+        source: "npm",
+        channel: "none",
+        spec: version ? `npm:${name}@${version}` : `npm:${name}`,
+        installedVersion: version,
+        manifestId,
+        auto: false,
+        autoLocked: false,
+        autoSetBy: "default",
+        lastCheckedAt: null,
+        lastAppliedAt: null,
+        lastError: null,
+      };
+    } else {
+      pin = {
+        source: "local",
+        channel: "none",
+        spec: "",
+        installedVersion: version,
+        manifestId,
+        auto: false,
+        autoLocked: true,
+        autoSetBy: "default",
+        lastCheckedAt: null,
+        lastAppliedAt: null,
+        lastError: null,
+      };
+    }
+    const entry = index ? index[folder] || index[normalizeModuleId(manifestId || folder)] : null;
+    file.modules[folder] = reconcileDefaultAuto(pin, entry);
+    added.push(folder);
+  }
+  if (added.length > 0) writePins(root, file);
+  return added;
+}
+
+/**
+ * 用磁盘上的 package.json 刷新已装版本，并按索引重算默认 auto。
+ * @param {string} root
+ * @param {Record<string, { npm?: string, version?: string }> | null} index
+ */
+export function refreshPinsFromDisk(root, index) {
+  backfillModulePins(root, index);
+  const file = readPins(root);
+  let changed = false;
+  for (const [folder, pin] of Object.entries(file.modules)) {
+    const dir = packageDirOf(root, folder);
+    if (!fs.existsSync(dir)) continue;
+    const version = readPackageVersion(dir);
+    const manifestId = readManifestId(dir);
+    const entry = index ? index[folder] || index[normalizeModuleId(manifestId || folder)] || index[normalizeModuleId(pin.manifestId || "")] : null;
+    let next = { ...pin };
+    if (version !== pin.installedVersion) next = { ...next, installedVersion: version };
+    if (manifestId && manifestId !== pin.manifestId) next = { ...next, manifestId };
+    next = reconcileDefaultAuto(next, entry);
+    if (JSON.stringify(next) !== JSON.stringify(pin)) {
+      file.modules[folder] = next;
+      changed = true;
+    }
+  }
+  if (changed) writePins(root, file);
+  return readPins(root);
+}
+
+/**
+ * 安装或升级成功后写入 pin。已有记录时保留服主设置的 auto。
+ * 写入失败只影响后续自动更新，不让本次安装失败。
+ * @param {string} root
+ * @param {string} folder
+ * @param {{ from?: string, link?: boolean }} opts
+ */
+export function recordInstallPin(root, folder, opts = {}) {
+  const dir = packageDirOf(root, folder);
+  const from = String(opts.from ?? "");
+  const link = !!opts.link || isLinkedPackageDir(dir);
+  const file = readPins(root);
+  const prev = file.modules[folder];
+  const draft = inferPinDraft(from, link);
+  const version = readPackageVersion(dir);
+  const manifestId = readManifestId(dir);
+  /** @type {ModulePin} */
+  const pin = {
+    source: from || link ? draft.source : prev?.source || draft.source,
+    channel: prev?.channel === "dist-tag" && draft.source === "npm" && !draft.autoLocked ? "dist-tag" : draft.channel,
+    spec: from || prev?.spec || draft.spec,
+    installedVersion: version,
+    manifestId,
+    auto: draft.auto,
+    autoLocked: draft.autoLocked,
+    autoSetBy: "default",
+    lastCheckedAt: prev?.lastCheckedAt ?? null,
+    lastAppliedAt: Date.now(),
+    lastError: null,
+  };
+  if (!from && !link && prev) {
+    pin.source = prev.source;
+    pin.channel = prev.channel;
+    pin.spec = prev.spec;
+    pin.auto = prev.auto;
+    pin.autoLocked = prev.autoLocked;
+    pin.autoSetBy = prev.autoSetBy;
+  } else if (prev && prev.autoSetBy === "user" && !draft.autoLocked) {
+    pin.auto = prev.auto;
+    pin.autoSetBy = "user";
+  }
+  if (pin.autoLocked) {
+    pin.auto = false;
+  } else if (pin.autoSetBy !== "user") {
+    const index = readCachedRegistryIndex();
+    const entry = index ? index[folder] || index[normalizeModuleId(manifestId || folder)] : null;
+    const reconciled = reconcileDefaultAuto(pin, entry);
+    pin.auto = reconciled.auto;
+    pin.channel = reconciled.channel;
+  }
+  file.modules[folder] = pin;
+  writePins(root, file);
+  return pin;
+}
+
+/**
+ * @param {string} root
+ * @param {string} folderOrId
+ */
+export function removePin(root, folderOrId) {
+  const file = readPins(root);
+  const key = findPinKey(file, folderOrId);
+  if (!key) return false;
+  delete file.modules[key];
+  writePins(root, file);
+  return true;
+}
+
+/**
+ * @param {string} root
+ * @param {string} id
+ * @param {string | null} message
+ */
+export function markPinError(root, id, message) {
+  const file = readPins(root);
+  const key = findPinKey(file, id);
+  if (!key) return;
+  const pin = file.modules[key];
+  if (!pin) return;
+  pin.lastCheckedAt = Date.now();
+  pin.lastError = message;
+  writePins(root, file);
+}
+
+/**
+ * 打开或关闭某个模块的自动更新。链接和本地目录不能打开。
+ * @param {string} root
+ * @param {string} id
+ * @param {boolean} auto
+ * @returns {{ ok: true, code: "ok", id: string, auto: boolean } | { ok: false, code: "missing" | "locked", id?: string }}
+ */
+export function setModulePinAuto(root, id, auto) {
+  backfillModulePins(root, null);
+  const file = readPins(root);
+  const key = findPinKey(file, id);
+  if (!key || !file.modules[key]) return { ok: false, code: "missing" };
+  const pin = file.modules[key];
+  if (pin.autoLocked && auto) return { ok: false, code: "locked", id: key };
+  pin.auto = !!auto;
+  pin.autoSetBy = "user";
+  pin.lastError = null;
+  writePins(root, file);
+  return { ok: true, code: "ok", id: key, auto: !!auto };
+}

package/scripts/module-install/lib/registry-cache.mjs

@@ -0,0 +1,83 @@
+// @ts-check
+/**
+ * 官方模块索引缓存。
+ * fetch-module 与模块更新共用同一份缓存文件，避免两套 TTL。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseRegistryIndex } from "./registry-index.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** 与历史 fetch-module 常量一致，供 search 文案引用。 */
+export const DEFAULT_REGISTRY_REPO = "Tanya7z/sfmc-modules";
+export const DEFAULT_REGISTRY_TAG = "main";
+export const DEFAULT_REGISTRY_INDEX_URL = `https://raw.githubusercontent.com/${DEFAULT_REGISTRY_REPO}/${DEFAULT_REGISTRY_TAG}/index.json`;
+
+/** 缓存落在 module-install 目录，和原先 fetch-module 旁边的文件是同一个。 */
+const REGISTRY_CACHE_PATH = path.join(__dirname, "..", ".sfmc-registry-cache.json");
+const REGISTRY_CACHE_TTL_MS = 60 * 60 * 1000;
+
+function readCache() {
+  try {
+    return JSON.parse(fs.readFileSync(REGISTRY_CACHE_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** 只读缓存，安装落盘时用来判断模块是否属于官方索引，不再打一次网络。 */
+export function readCachedRegistryIndex() {
+  const cache = readCache();
+  return cache?.index ?? null;
+}
+
+/**
+ * @param {{ fetchedAt: number, index: Record<string, import("./registry-index.mjs").RegistryEntry> }} cache
+ */
+function writeCache(cache) {
+  try {
+    fs.writeFileSync(REGISTRY_CACHE_PATH, JSON.stringify(cache, null, 2));
+  } catch {
+    /* best-effort */
+  }
+}
+
+async function fetchRegistryIndexFresh() {
+  const res = await fetch(DEFAULT_REGISTRY_INDEX_URL, { headers: { "User-Agent": "sfmc-fetch-module" } });
+  if (!res.ok) throw new Error(`HTTP ${res.status} for ${DEFAULT_REGISTRY_INDEX_URL}`);
+  return parseRegistryIndex(await res.json());
+}
+
+/**
+ * 解析官方索引。
+ * 缓存未过期时仍尝试拉新；失败则用缓存。完全没有缓存且网络失败时抛出。
+ * @returns {Promise<{ index: Record<string, import("./registry-index.mjs").RegistryEntry>, stale: boolean }>}
+ */
+export async function resolveRegistryIndex() {
+  const cache = readCache();
+  if (cache && Date.now() - cache.fetchedAt < REGISTRY_CACHE_TTL_MS) {
+    try {
+      const fresh = await fetchRegistryIndexFresh();
+      writeCache({ fetchedAt: Date.now(), index: fresh });
+      return { index: fresh, stale: false };
+    } catch {
+      return { index: cache.index, stale: false };
+    }
+  }
+  try {
+    const fresh = await fetchRegistryIndexFresh();
+    writeCache({ fetchedAt: Date.now(), index: fresh });
+    return { index: fresh, stale: false };
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    if (cache) {
+      console.warn(
+        `[fetch-module] registry offline (${message}); using cached index from ${new Date(cache.fetchedAt).toISOString()}`
+      );
+      return { index: cache.index, stale: true };
+    }
+    throw new Error(`registry unreachable and no cache: ${message}. Pass --from explicitly to skip the registry.`);
+  }
+}

package/scripts/module-install/lib/semver.mjs

@@ -0,0 +1,124 @@
+// @ts-check
+/**
+ * 模块版本比较。
+ * 只覆盖 x.y.z 与可选预发布号，供自动更新决定能否升级。
+ */
+
+/**
+ * @typedef {{ major: number, minor: number, patch: number, pre: string[] | null }} ParsedSemver
+ */
+
+/**
+ * @param {string | null | undefined} input
+ * @returns {ParsedSemver | null}
+ */
+export function parseSemver(input) {
+  const match = String(input ?? "")
+    .trim()
+    .match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    pre: match[4] ? match[4].split(".") : null,
+  };
+}
+
+/**
+ * 预发布标识按 semver 规则比较：数字按数值，其余按字典序。
+ * @param {string} a
+ * @param {string} b
+ */
+function comparePreId(a, b) {
+  const aNum = /^\d+$/.test(a);
+  const bNum = /^\d+$/.test(b);
+  if (aNum && bNum) return Number(a) - Number(b);
+  if (aNum) return -1;
+  if (bNum) return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * @param {string[] | null} a
+ * @param {string[] | null} b
+ */
+function comparePre(a, b) {
+  if (!a && !b) return 0;
+  if (!a) return 1;
+  if (!b) return -1;
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const left = a[i];
+    const right = b[i];
+    if (left === undefined) return -1;
+    if (right === undefined) return 1;
+    const diff = comparePreId(left, right);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * 比较两个版本。无法解析时返回 null。
+ * @param {string | null | undefined} left
+ * @param {string | null | undefined} right
+ * @returns {-1 | 0 | 1 | null}
+ */
+export function compareSemver(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return null;
+  if (a.major !== b.major) return a.major > b.major ? 1 : -1;
+  if (a.minor !== b.minor) return a.minor > b.minor ? 1 : -1;
+  if (a.patch !== b.patch) return a.patch > b.patch ? 1 : -1;
+  const pre = comparePre(a.pre, b.pre);
+  return pre > 0 ? 1 : pre < 0 ? -1 : 0;
+}
+
+/**
+ * 目标版本的主版本号是否高于已装版本。
+ * @param {string | null | undefined} installed
+ * @param {string | null | undefined} target
+ */
+export function isMajorBump(installed, target) {
+  const from = parseSemver(installed);
+  const to = parseSemver(target);
+  if (!from || !to) return false;
+  return to.major > from.major;
+}
+
+/**
+ * 判断本机 SDK 版本是否满足索引里的范围。
+ * 支持 *、精确版本、以及 >= > <= < ^ ~ 前缀。
+ * @param {string | null | undefined} version
+ * @param {string | null | undefined} range
+ */
+export function satisfiesSdk(version, range) {
+  const raw = String(range ?? "").trim();
+  if (!raw || raw === "*") return true;
+  const match = raw.match(/^(>=|>|<=|<|\^|~|=)?\s*v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/);
+  if (!match) return false;
+  const op = match[1] || "=";
+  const wanted = match[2];
+  const cmp = compareSemver(version, wanted);
+  if (cmp === null || !wanted) return false;
+  if (op === "=") return cmp === 0;
+  if (op === ">=") return cmp >= 0;
+  if (op === ">") return cmp > 0;
+  if (op === "<=") return cmp <= 0;
+  if (op === "<") return cmp < 0;
+  const current = parseSemver(version);
+  const base = parseSemver(wanted);
+  if (!current || !base) return false;
+  if (op === "^") {
+    if (cmp < 0) return false;
+    if (base.major > 0) return current.major === base.major;
+    if (base.minor > 0) return current.major === 0 && current.minor === base.minor;
+    return current.major === 0 && current.minor === 0 && current.patch === base.patch;
+  }
+  if (op === "~") {
+    return cmp >= 0 && current.major === base.major && current.minor === base.minor;
+  }
+  return false;
+}