@sfmc-bds/cli 0.2.0-beta.0 → 0.2.0-beta.10

package/scripts/module-install/install-resolver.test.mjs

@@ -0,0 +1,48 @@
+// @ts-check
+/**
+ * install-resolver.test.mjs — npm 包名解析表驱动
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  resolveNpmPackageName,
+  folderFromNpmPackageName,
+  normalizeNpmPackageName,
+} from "./lib/npm-resolver.mjs";
+
+test("短 id → @sfmc-bds/module-<id>", () => {
+  assert.equal(resolveNpmPackageName("land"), "@sfmc-bds/module-land");
+  assert.equal(resolveNpmPackageName("my-mod"), "@sfmc-bds/module-my-mod");
+});
+
+test("logical id (feature-* / core-*) → @sfmc-bds/module-<folder>", () => {
+  assert.equal(resolveNpmPackageName("feature-land"), "@sfmc-bds/module-land");
+  assert.equal(resolveNpmPackageName("core-data-backup"), "@sfmc-bds/module-data-backup");
+});
+
+test("已带 scope 原样透传", () => {
+  assert.equal(resolveNpmPackageName("@alice/sfmc-module-foo"), "@alice/sfmc-module-foo");
+  assert.equal(resolveNpmPackageName("@sfmc-bds/module-land"), "@sfmc-bds/module-land");
+});
+
+test("非 kebab 报错", () => {
+  assert.throws(() => resolveNpmPackageName("NotKebab"), /invalid module id/);
+  assert.throws(() => resolveNpmPackageName("feature-"), /invalid module id/);
+});
+
+test("@ 但无 / → invalid scoped package name", () => {
+  assert.throws(() => resolveNpmPackageName("@orphan"), /invalid scoped package name/);
+});
+
+test("folderFromNpmPackageName 反向解析", () => {
+  assert.equal(folderFromNpmPackageName("@sfmc-bds/module-land"), "land");
+  assert.equal(folderFromNpmPackageName("@alice/sfmc-module-foo"), "foo");
+  assert.equal(folderFromNpmPackageName("@alice/sfmc-module-my-mod"), "my-mod");
+  assert.equal(folderFromNpmPackageName("@alice/random"), null);
+});
+
+test("normalizeNpmPackageName 兼容两种前缀", () => {
+  assert.equal(normalizeNpmPackageName("@sfmc-bds/module-land"), "land");
+  assert.equal(normalizeNpmPackageName("@alice/sfmc-module-foo"), "foo");
+  assert.equal(normalizeNpmPackageName("@alice/module-bar"), "bar");
+});

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://cdn.jsdelivr.net/gh/DogeLakeDev/ScriptsForMinecraftServer@%40sfmc-bds/sdk@0.2.0-beta.6/modules/sdk/%40sfmc-sdk/schemas/module_catalog.schema.json";
+
+/**
+ * @typedef {import("./packages.mjs").CatalogEntry} CatalogEntry
+ * @typedef {{ $schema?: string, version: number, modules: CatalogEntry[] }} 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/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 {{ enabled: boolean, updatedAt?: number }} LockState
+ * @typedef {{ version: number, modules: Record<string, LockState> }} 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,142 @@
+// @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 {object} CatalogEntry
+ * @property {string} id
+ * @property {string} configKey
+ * @property {string} name
+ * @property {string} type
+ * @property {string} description
+ * @property {boolean} enabledByDefault
+ * @property {boolean} canDisable
+ * @property {string[]} requires
+ * @property {{ kind: string, path: string }} entry
+ * @property {SemanticBlock} [semantic]  v3 字段；v2 模块不写
+ */
+
+/** @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 → 与历史完全相同；v3 → 把 semantic 块原样带进 catalog（沙箱读模块语义镜像）。
+ * @param {string} folder
+ * @param {Record<string, unknown>} manifest
+ * @returns {CatalogEntry}
+ */
+export function projectCatalogEntry(folder, manifest) {
+  const type = String(manifest.type || "feature");
+  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 缺失`);
+
+  const enabledByDefault = typeof manifest.enabledByDefault === "boolean" ? manifest.enabledByDefault : type === "core";
+  const canDisable = typeof manifest.canDisable === "boolean" ? manifest.canDisable : type !== "core";
+
+  /** @type {CatalogEntry} */
+  const entry = {
+    id,
+    configKey,
+    name: String(manifest.name || configKey),
+    type,
+    description: String(manifest.description || ""),
+    enabledByDefault,
+    canDisable,
+    requires: Array.isArray(manifest.requires) ? manifest.requires.map(String) : [],
+    entry: {
+      kind: "sapi",
+      path: catalogEntryRelPath(folder),
+    },
+  };
+  /* v3 semantic 投影：原样复制即可（catalog 与 manifest 同源）。
+   * 此处不再做形状校验——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`;
+}

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

@@ -0,0 +1,50 @@
+// @ts-check
+/**
+ * 解析 Tanya7z/sfmc-modules index.json
+ *
+ * 契约（与 sfmc/src/registry.ts#parseRegistryIndex 保持一致）:
+ *   { modules: { <id>: { npm?, version?, sdk?, repo?, tag? } } }
+ * 条目至少具备 npm 或 repo+tag。`_` 前缀键视为元数据并忽略。
+ */
+
+/**
+ * @typedef {{ npm?: string, version?: string, sdk?: string, repo?: string, tag?: string }} RegistryEntry
+ * @typedef {Record<string, RegistryEntry>} RegistryIndex
+ */
+
+/**
+ * @param {unknown} json
+ * @returns {RegistryIndex}
+ */
+export function parseRegistryIndex(json) {
+  if (typeof json !== "object" || json === null || Array.isArray(json)) {
+    throw new Error("registry index must be a JSON object with a 'modules' field");
+  }
+  const modules = /** @type {Record<string, unknown>} */ (json).modules;
+  if (typeof modules !== "object" || modules === null || Array.isArray(modules)) {
+    throw new Error("registry index must have a 'modules' object mapping id → entry");
+  }
+  /** @type {RegistryIndex} */
+  const filtered = {};
+  for (const [k, v] of Object.entries(modules)) {
+    if (k.startsWith("_")) continue;
+    if (typeof v !== "object" || v === null || Array.isArray(v)) continue;
+    const entry = /** @type {Record<string, unknown>} */ (v);
+    const hasNpm = typeof entry.npm === "string" && entry.npm.length > 0;
+    const hasGh = typeof entry.repo === "string" && typeof entry.tag === "string";
+    if (!hasNpm && !hasGh) continue;
+    /** @type {RegistryEntry} */
+    const out = {};
+    if (hasNpm) {
+      out.npm = /** @type {string} */ (entry.npm);
+      if (typeof entry.version === "string") out.version = entry.version;
+      if (typeof entry.sdk === "string") out.sdk = entry.sdk;
+    }
+    if (hasGh) {
+      out.repo = /** @type {string} */ (entry.repo);
+      out.tag = /** @type {string} */ (entry.tag);
+    }
+    filtered[k] = out;
+  }
+  return filtered;
+}

package/scripts/module-install/link-local.test.mjs

@@ -0,0 +1,51 @@
+// @ts-check
+/**
+ * link-local.test.mjs — normalizeLinkFrom 表驱动
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { normalizeLinkFrom } from "./lib/link-from.mjs";
+
+const CWD = process.cwd();
+
+test("local 无路径 → dir:cwd", () => {
+  const r = normalizeLinkFrom("local", CWD);
+  assert.equal(r.ok, true);
+  if (r.ok) assert.equal(r.from, `dir:${path.resolve(CWD)}`);
+});
+
+test("local:相对目录 → dir:绝对路径", () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "sfmc-link-rel-"));
+  const rel = path.relative(CWD, tmp) || ".";
+  const r = normalizeLinkFrom(`local:${rel}`, CWD);
+  assert.equal(r.ok, true);
+  if (r.ok) assert.equal(r.from, `dir:${path.resolve(CWD, rel)}`);
+  fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+test("local:file.tgz + link → 拒绝", () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "sfmc-link-"));
+  const tgz = path.join(tmp, "x.tgz");
+  fs.writeFileSync(tgz, "");
+  const r = normalizeLinkFrom(`local:${tgz}`, CWD);
+  assert.equal(r.ok, false);
+  if (!r.ok) assert.match(r.error, /tgz|zip|--link/i);
+  fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+test("dir: 原样通过", () => {
+  const r = normalizeLinkFrom("dir:D:/mods/foo", CWD);
+  assert.equal(r.ok, true);
+  if (r.ok) assert.equal(r.from, "dir:D:/mods/foo");
+});
+
+test("裸路径目录 → dir:绝对路径", () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "sfmc-link-bare-"));
+  const r = normalizeLinkFrom(tmp, CWD);
+  assert.equal(r.ok, true);
+  if (r.ok) assert.equal(r.from, `dir:${path.resolve(tmp)}`);
+  fs.rmSync(tmp, { recursive: true, force: true });
+});