@sfmc-bds/cli 0.2.0-beta.8 → 0.2.0

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

@@ -0,0 +1,96 @@
+// @ts-check
+/**
+ * modules/catalog.json 读写与同步（权威实现在 @sfmc-bds/cli）
+ */
+import { CATALOG_PATH } from "./paths.mjs";
+import { readJson, writeJson } from "./io.mjs";
+import {
+  folderFromEntryPath,
+  loadPackageCatalogEntry,
+  projectCatalogEntry,
+  scanInstalledPackages,
+} from "./packages.mjs";
+
+const CATALOG_SCHEMA =
+  "https://raw.githubusercontent.com/DogeLakeDev/ScriptsForMinecraftServer/main/modules/sdk/@sfmc-sdk/schemas/module_catalog.schema.json";
+
+/**
+ * @typedef {import("./packages.mjs").CatalogEntry} CatalogEntry
+ * @typedef {import("@sfmc-bds/sdk/contracts").ModuleCatalog} ModuleCatalog
+ */
+
+/** @returns {ModuleCatalog} */
+export function readCatalog() {
+  const raw = readJson(CATALOG_PATH, null);
+  if (!raw || typeof raw !== "object") {
+    return { version: 1, modules: [] };
+  }
+  return {
+    version: typeof raw.version === "number" ? raw.version : 1,
+    modules: Array.isArray(raw.modules) ? raw.modules : [],
+  };
+}
+
+/** @param {ModuleCatalog} catalog */
+export function writeCatalog(catalog) {
+  writeJson(CATALOG_PATH, {
+    $schema: CATALOG_SCHEMA,
+    version: catalog.version || 1,
+    modules: catalog.modules || [],
+  });
+}
+
+/**
+ * 扫描 packages 全量重写 catalog.modules
+ * @returns {{ catalog: ModuleCatalog, count: number }}
+ */
+export function syncCatalogFromPackages() {
+  const prev = readCatalog();
+  /** @type {CatalogEntry[]} */
+  const modules = [];
+  for (const pkg of scanInstalledPackages()) {
+    modules.push(projectCatalogEntry(pkg.folder, pkg.manifest));
+  }
+  const catalog = {
+    version: prev.version || 1,
+    modules,
+  };
+  writeCatalog(catalog);
+  return { catalog, count: modules.length };
+}
+
+/**
+ * install 后 upsert 单条
+ * @param {string} folder
+ * @returns {CatalogEntry}
+ */
+export function upsertCatalogEntry(folder) {
+  const entry = loadPackageCatalogEntry(folder);
+  if (!entry) throw new Error(`packages/${folder}: 无有效 sapi/manifest.json`);
+  const catalog = readCatalog();
+  const idx = catalog.modules.findIndex(
+    (m) => m.id === entry.id || (m.entry && folderFromEntryPath(m.entry.path) === folder)
+  );
+  if (idx >= 0) catalog.modules[idx] = entry;
+  else catalog.modules.push(entry);
+  catalog.modules.sort((a, b) => a.id.localeCompare(b.id));
+  writeCatalog(catalog);
+  return entry;
+}
+
+/**
+ * uninstall 后按 folder / manifest.id 删除
+ * @param {string} folderOrId
+ * @returns {CatalogEntry | null} 被删条目
+ */
+export function removeCatalogEntry(folderOrId) {
+  const catalog = readCatalog();
+  const idx = catalog.modules.findIndex((m) => {
+    if (m.id === folderOrId) return true;
+    return folderFromEntryPath(m.entry?.path) === folderOrId;
+  });
+  if (idx < 0) return null;
+  const [removed] = catalog.modules.splice(idx, 1);
+  writeCatalog(catalog);
+  return removed;
+}

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/lib/io.mjs

@@ -0,0 +1,37 @@
+// @ts-check
+/**
+ * tools/lib/io.mjs — JSON 读写与 die 辅助
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+/** @param {string} file @param {unknown} fallback */
+export function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+/** @param {string} file @param {unknown} data */
+export function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+/** @param {string} tag @param {string} msg @param {number} [code] */
+export function die(tag, msg, code = 1) {
+  console.error(`[${tag}] ${msg}`);
+  process.exit(code);
+}
+
+/** @param {string} p */
+export function exists(p) {
+  try {
+    fs.accessSync(p, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/scripts/module-install/lib/link-from.mjs

@@ -0,0 +1,80 @@
+// @ts-check
+/**
+ * --from 规范化（裸路径 / local: / dir:）
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * 是否为带 scheme 的 --from（非裸文件系统路径）。
+ * @param {string} from
+ */
+export function isSchemeFrom(from) {
+  return (
+    from === "local" ||
+    from.startsWith("local:") ||
+    from.startsWith("dir:") ||
+    from.startsWith("npm:") ||
+    from.startsWith("tgz:") ||
+    from.startsWith("zip:") ||
+    from.startsWith("github:")
+  );
+}
+
+/**
+ * 把裸路径规范成 dir:<abs>（不存在则报错）。
+ * @param {string} raw
+ * @param {string} [cwd]
+ * @returns {{ ok: true, from: string } | { ok: false, error: string }}
+ */
+export function normalizeBarePathFrom(raw, cwd = process.cwd()) {
+  const abs = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(cwd, raw);
+  if (!fs.existsSync(abs)) {
+    return { ok: false, error: `--from 路径不存在: ${abs}` };
+  }
+  const st = fs.lstatSync(abs);
+  if (!st.isDirectory()) {
+    return {
+      ok: false,
+      error: `--from 裸路径须为目录（文件请用 --from local:<tgz|zip>）: ${abs}`,
+    };
+  }
+  return { ok: true, from: `dir:${abs}` };
+}
+
+/**
+ * @param {string} from
+ * @param {string} [cwd]
+ * @returns {{ ok: true, from: string } | { ok: false, error: string }}
+ */
+export function normalizeLinkFrom(from, cwd = process.cwd()) {
+  if (!from || from === "local" || from.startsWith("local:")) {
+    const tail = !from || from === "local" ? "" : from.slice("local:".length);
+    const abs =
+      !tail || tail === "." || tail === "./"
+        ? path.resolve(cwd)
+        : path.isAbsolute(tail)
+          ? path.resolve(tail)
+          : path.resolve(cwd, tail);
+    if (!fs.existsSync(abs)) {
+      return { ok: false, error: `--from local target not found: ${abs}` };
+    }
+    const st = fs.lstatSync(abs);
+    if (st.isDirectory()) return { ok: true, from: `dir:${abs}` };
+    return {
+      ok: false,
+      error: `--link 仅支持目录源；tgz/zip 请去掉 --link 使用 copy 安装`,
+    };
+  }
+  if (from.startsWith("dir:")) return { ok: true, from };
+  /* 约定写法：mod install <id> --from <路径> --link */
+  if (!isSchemeFrom(from)) {
+    const bare = normalizeBarePathFrom(from, cwd);
+    if (!bare.ok) return bare;
+    return bare;
+  }
+  return {
+    ok: false,
+    error: `--link only works with --from <path> / dir:<path> / local[:<dir>] (got ${from})`,
+  };
+}

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

@@ -0,0 +1,78 @@
+// @ts-check
+/**
+ * modules/module-lock.json 读写（权威实现在 @sfmc-bds/cli）
+ *
+ * 服务类条目(service-* 与 tool-*)保留；业务模块按 manifest.id 启停。
+ */
+import { MODULE_LOCK_PATH } from "./paths.mjs";
+import { readJson, writeJson } from "./io.mjs";
+
+/**
+ * @typedef {import("@sfmc-bds/sdk/contracts").ModuleRuntimeState} LockState
+ * @typedef {import("@sfmc-bds/sdk/contracts").ModuleLock} ModuleLock
+ */
+
+const SERVICE_PREFIXES = ["service-", "tool-"];
+
+/** @param {string} id */
+export function isServiceLockId(id) {
+  return SERVICE_PREFIXES.some((p) => id.startsWith(p));
+}
+
+/** @returns {ModuleLock} */
+export function readLock() {
+  const raw = readJson(MODULE_LOCK_PATH, null);
+  if (!raw || typeof raw !== "object") return { version: 1, modules: {} };
+  return {
+    version: typeof raw.version === "number" ? raw.version : 1,
+    modules: raw.modules && typeof raw.modules === "object" ? { ...raw.modules } : {},
+  };
+}
+
+/** @param {ModuleLock} lock */
+export function writeLock(lock) {
+  writeJson(MODULE_LOCK_PATH, {
+    version: lock.version || 1,
+    modules: lock.modules || {},
+  });
+}
+
+/**
+ * @param {string} moduleId manifest.id
+ * @param {boolean} enabled
+ */
+export function setModuleLockEnabled(moduleId, enabled) {
+  const lock = readLock();
+  lock.modules[moduleId] = {
+    enabled: !!enabled,
+    updatedAt: Date.now(),
+  };
+  writeLock(lock);
+}
+
+/** @param {string} moduleId */
+export function removeModuleLock(moduleId) {
+  const lock = readLock();
+  if (!(moduleId in lock.modules)) return false;
+  delete lock.modules[moduleId];
+  writeLock(lock);
+  return true;
+}
+
+/**
+ * 清理 lock 中已不在 catalog 的业务模块条目(保留 service/tool)
+ * @param {Set<string>} catalogIds
+ */
+export function pruneOrphanModuleLocks(catalogIds) {
+  const lock = readLock();
+  let changed = false;
+  for (const id of Object.keys(lock.modules)) {
+    if (isServiceLockId(id)) continue;
+    if (!catalogIds.has(id)) {
+      delete lock.modules[id];
+      changed = true;
+    }
+  }
+  if (changed) writeLock(lock);
+  return changed;
+}

package/scripts/module-install/lib/npm-resolver.mjs

@@ -0,0 +1,55 @@
+// @ts-check
+/**
+ * npm 包名解析（单一权威）
+ *
+ * 规则（DRY，避免重复解析逻辑）：
+ *   - 已含 scope（@scope/name）→ 原样
+ *   - 已含 logical id（feature-land / core-data-backup）→ @sfmc-bds/module-<folder>
+ *   - 短 id（land / my-mod）→ @sfmc-bds/module-<folder>
+ *
+ * @param {string} idOrName  用户传入的模块 id 或包名
+ * @param {string} [scope]   显式 scope，默认 @sfmc-bds
+ * @returns {string} npm 包名
+ */
+export const DEFAULT_NPM_SCOPE = "@sfmc-bds";
+
+export function resolveNpmPackageName(idOrName, scope = DEFAULT_NPM_SCOPE) {
+  const raw = String(idOrName ?? "").trim();
+  if (!raw) throw new Error("empty module id");
+  /* 已含 scope（@scope/name）→ 原样 */
+  if (raw.startsWith("@")) {
+    const m = raw.match(/^@([^/]+)\/(.+)$/);
+    if (!m) throw new Error(`invalid scoped package name: ${raw}`);
+    return raw;
+  }
+  /* feature-* / core-* → folder */
+  const folder = raw.replace(/^(feature|core)-/, "");
+  if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(folder)) {
+    throw new Error(`invalid module id: ${raw}`);
+  }
+  return `${scope}/module-${folder}`;
+}
+
+/**
+ * 反向：从 npm 包名解出 folder（packages/<folder> 用）。
+ * 接受：
+ *   @sfmc-bds/module-land         → land
+ *   @<scope>/sfmc-module-land     → land
+ *   @<scope>/sfmc-module-my-mod   → my-mod
+ */
+export function folderFromNpmPackageName(pkgName) {
+  const raw = String(pkgName ?? "").trim();
+  const m = raw.match(/^@[^/]+\/(?:module-|sfmc-module-)(.+)$/);
+  return m ? m[1] : null;
+}
+
+/**
+ * 规范化 npm 包名（去掉前缀、保证 kebab）—— 给 tarball 内部读到的 name 用。
+ */
+export function normalizeNpmPackageName(pkgName) {
+  const raw = String(pkgName ?? "").trim();
+  if (!raw) throw new Error("empty npm package name");
+  /* @scope/module-foo → foo；@scope/sfmc-module-foo → foo；module-foo → foo */
+  const m = raw.match(/^(?:@[^/]+\/)?(?:sfmc-)?module-(.+)$/);
+  return m ? m[1] : raw;
+}

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

@@ -0,0 +1,136 @@
+// @ts-check
+/**
+ * 扫描 modules/packages/<id>/sapi/manifest.json 并投影为 catalog 条目
+ *
+ * v3 兼容：若 manifest.schemaVersion === 3，则把 semantic 块原样投影进 catalog 条目；
+ *          v2 manifest 不带 semantic，catalog 条目也不带。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { exists, readJson } from "./io.mjs";
+import { catalogEntryRelPath, packageDir, packageEntryPath, packageManifestPath, PACKAGES_DIR } from "./paths.mjs";
+
+/**
+ * @typedef {object} PackageInfo
+ * @property {string} folder  packages 下目录名(registry install id)
+ * @property {*} manifest
+ * @property {string} manifestPath
+ * @property {string} entryAbs
+ * @property {boolean} hasEntry
+ */
+
+/**
+ * v3 semantic 块投影后形状（catalog 与 manifest 同源；后续沙箱可直接读）。
+ * @typedef {{
+ *   configKeys?: string[],
+ *   dependsOn?: string[],
+ *   events?: { emits?: string[], listens?: string[] },
+ *   dbTables?: Array<{ name: string, columns?: string[] }>,
+ *   publicApi?: Array<{ symbol: string, description?: string, params?: Array<{ name: string, type: string, required?: boolean, description?: string }>, returns?: { type: string, description?: string } }>
+ * }} SemanticBlock
+ */
+
+/**
+ * @typedef {import("@sfmc-bds/sdk/contracts").ModuleCatalogEntry} CatalogEntry
+ */
+
+/** @returns {PackageInfo[]} */
+export function scanInstalledPackages() {
+  if (!exists(PACKAGES_DIR)) return [];
+  /** @type {PackageInfo[]} */
+  const out = [];
+  for (const ent of fs.readdirSync(PACKAGES_DIR, { withFileTypes: true })) {
+    if (ent.name.startsWith(".")) continue;
+    const folder = ent.name;
+    const abs = path.join(PACKAGES_DIR, folder);
+    // 跟随 symlink：Dirent.isDirectory() 对链接目录为 false
+    try {
+      if (!fs.statSync(abs).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    const manifestPath = packageManifestPath(folder);
+    if (!exists(manifestPath)) continue;
+    const manifest = readJson(manifestPath, null);
+    if (!manifest || typeof manifest !== "object") continue;
+    const entryAbs = packageEntryPath(folder);
+    out.push({
+      folder,
+      manifest,
+      manifestPath,
+      entryAbs,
+      hasEntry: exists(entryAbs),
+    });
+  }
+  out.sort((a, b) => a.folder.localeCompare(b.folder));
+  return out;
+}
+
+/**
+ * 从 v2 / v3 manifest 及包所在目录名投影生成 catalog 条目。
+ * - v2 manifest：投影基础核心字段，不包含 semantic 块；
+ * - v3 manifest：在核心字段基础上将 semantic 块深拷贝透传至条目中；
+ * - 契约原则：本函数仅做结构投影与深拷贝，不负责校验字段形状合法性；形状校验统一以 SDK 的 `validateManifest` 为准（由 check-modules 离线自检或安装器统一调用）。
+ *
+ * @param {string} folder 安装目录名。
+ * @param {Record<string, unknown>} manifest 原始 manifest 对象。
+ * @returns {CatalogEntry} 投影生成的 catalog 条目。
+ */
+export function projectCatalogEntry(folder, manifest) {
+  const id = String(manifest.id || "").trim();
+  const configKey = String(manifest.configKey || "").trim();
+  if (!id) throw new Error(`packages/${folder}: manifest.id 缺失`);
+  if (!configKey) throw new Error(`packages/${folder}: manifest.configKey 缺失`);
+
+  /* 缺省：默认启用、允许禁用；不可禁用须在 manifest 显式 canDisable:false */
+  const enabledByDefault = typeof manifest.enabledByDefault === "boolean" ? manifest.enabledByDefault : true;
+  const canDisable = typeof manifest.canDisable === "boolean" ? manifest.canDisable : true;
+
+  /** @type {CatalogEntry} */
+  const entry = {
+    id,
+    configKey,
+    name: String(manifest.name || configKey),
+    description: String(manifest.description || ""),
+    enabledByDefault,
+    canDisable,
+    requires: Array.isArray(manifest.requires) ? manifest.requires.map(String) : [],
+    entry: {
+      kind: "sapi",
+      path: catalogEntryRelPath(folder),
+    },
+  };
+  /* v3 semantic 语义块投影：
+   * 采用 structuredClone 执行只读深拷贝透传，不在此处重复校验字段形状。
+   * 契约原则：字段形状与类型的合法性统一以 SDK validateManifest 为唯一权威（由 check-modules 等上层检查脚本统一调用验证）。 */
+  if (manifest.schemaVersion === 3 && manifest.semantic && typeof manifest.semantic === "object") {
+    entry.semantic = /** @type {SemanticBlock} */ (structuredClone(manifest.semantic));
+  }
+  return entry;
+}
+
+
+/** @param {string} folder @returns {CatalogEntry | null} */
+export function loadPackageCatalogEntry(folder) {
+  const manifestPath = packageManifestPath(folder);
+  if (!exists(manifestPath)) return null;
+  const manifest = readJson(manifestPath, null);
+  if (!manifest) return null;
+  return projectCatalogEntry(folder, manifest);
+}
+
+/** @param {string} folder */
+export function packageExists(folder) {
+  return exists(packageDir(folder));
+}
+
+/**
+ * 从 entry.path 解析 packages 目录名
+ * @param {string} entryPath
+ */
+export function folderFromEntryPath(entryPath) {
+  const m = String(entryPath || "")
+    .replace(/\\/g, "/")
+    .match(/modules\/packages\/([^/]+)\//);
+  return m ? m[1] : null;
+}

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

@@ -0,0 +1,48 @@
+// @ts-check
+/**
+ * CLI module-install 路径 — modules/packages、catalog、lock（相对 SFMC_ROOT）
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findMonorepoRoot } from "@sfmc-bds/sdk/node/config";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** @sfmc-bds/cli 包根（packages/cli 或 node_modules/@sfmc-bds/cli） */
+export const CLI_PKG_DIR = path.resolve(__dirname, "..", "..", "..");
+
+/**
+ * 工作根目录。
+ * 优先 SFMC_ROOT；否则 walk-up 找 sfmc-monorepo；再回退到 cwd。
+ */
+export const ROOT = process.env.SFMC_ROOT
+  ? path.resolve(process.env.SFMC_ROOT)
+  : findMonorepoRoot(__dirname) ?? process.cwd();
+
+export const MODULES_DIR = path.join(ROOT, "modules");
+export const PACKAGES_DIR = path.join(MODULES_DIR, "packages");
+export const CATALOG_PATH = path.join(MODULES_DIR, "catalog.json");
+export const MODULE_LOCK_PATH = path.join(MODULES_DIR, "module-lock.json");
+
+/** 本包内 fetch-module 入口（npm 安装时勿拼 ROOT） */
+export const FETCH_MODULE = path.join(CLI_PKG_DIR, "scripts", "module-install", "fetch-module.mjs");
+
+/** @param {string} folder  packages/<folder> */
+export function packageDir(folder) {
+  return path.join(PACKAGES_DIR, folder);
+}
+
+/** @param {string} folder */
+export function packageManifestPath(folder) {
+  return path.join(PACKAGES_DIR, folder, "sapi", "manifest.json");
+}
+
+/** @param {string} folder */
+export function packageEntryPath(folder) {
+  return path.join(PACKAGES_DIR, folder, "sapi", "src", "index.ts");
+}
+
+/** catalog.entry.path 用正斜杠相对仓库根 */
+export function catalogEntryRelPath(folder) {
+  return `modules/packages/${folder}/sapi/src/index.ts`;
+}