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

package/dist/world-packs.d.ts

@@ -1,3 +1,12 @@
+/**
+ * world-packs.ts — 通用 Minecraft 基岩版世界行为包（BP）与资源包（RP）管理工具
+ *
+ * 核心能力：
+ * - 格式与命名规范化：过滤 Minecraft 颜色格式码，自动补充 `[BP]` / `[RP]` 前缀及冲突避让
+ * - 压缩包递归解构：支持 `.zip`、`.mcpack`、`.mcaddon` 嵌套包解压并智能识别 BP 与 RP 根目录
+ * - 版本递增与同步：同步升级 manifest 中的版本元数据并对齐世界启用清单版本
+ * - 幂等安装与回滚：按 UUID 精确匹配升级与安装计划，支持删除备份至回收站机制
+ */
 import { type WorldPackListReadResult } from "./pack-manager.js";
 export type WorldPackKind = "behavior" | "resource";
 export interface PackManifestInfo {
@@ -18,6 +27,34 @@ export interface InstalledWorldPack {
 }
 /** 滤掉 §x（Minecraft 格式码）、残余压缩后缀，加 [BP]/[RP] 前缀 */
 export declare function formatWorldPackFolderName(rawName: string, kind: WorldPackKind): string;
+/** 去掉已有 [BP]/[RP] 前缀，得到文件夹名主干 */
+export declare function stripWorldPackFolderPrefix(rawName: string): string;
+/**
+ * 归档内常见占位目录名（B / R / BP / RP）过短或过泛，不能作为世界目录名，
+ * 否则不同包会撞到同一路径并被误判为「覆盖」。
+ */
+export declare function isGenericPackFolderStem(rawName: string): boolean;
+/**
+ * 选定安装文件夹名：hint 过泛时改用 manifest.name；再与已占用名避让（不同 uuid 不互相覆盖）。
+ * 纯函数：只依赖 taken 集合，便于表驱动单测（DRY：decide / choose 共用）。
+ */
+export declare function allocatePackFolderName(opts: {
+    hint?: string;
+    info: PackManifestInfo;
+    takenFolderNames: Iterable<string>;
+    /** 同 uuid 更新时允许占用的已有目录名（不触发避让） */
+    allowFolderName?: string;
+}): string;
+/**
+ * 选定安装文件夹名（读 destParent 占用）。
+ * 决策权威见 allocatePackFolderName / decidePackInstallPlan。
+ */
+export declare function choosePackInstallFolderName(opts: {
+    hint?: string;
+    info: PackManifestInfo;
+    destParent: string;
+    allowFolderName?: string;
+}): string;
 /** 根据 manifest modules[].type 判定 BP / RP */
 export declare function detectPackKindFromManifest(raw: {
     modules?: Array<{
@@ -30,18 +67,72 @@ export declare function discoverPackRoots(root: string, opts?: {
     maxDepth?: number;
 }): string[];
 export declare function isPackArchive(filePath: string): boolean;
+/**
+ * 列出目录树内的包归档文件。
+ * 已是包根（含 manifest.json）的目录不再下钻，避免误解压包内资源。
+ */
+export declare function listPackArchiveFiles(root: string, opts?: {
+    maxDepth?: number;
+}): string[];
+/**
+ * 在临时树内原地展开嵌套归档：解压到同级目录并删除归档文件，多轮直至没有新归档。
+ * 仅应对我们自己的 staging，禁止用于用户 inbox 原目录。
+ */
+export declare function expandNestedArchivesInPlace(workDir: string, opts?: {
+    maxRounds?: number;
+    maxScanDepth?: number;
+}): Promise<number>;
+export type ResolvePackRootsResult = {
+    roots: string[];
+    /** 清理本轮创建的全部临时目录（可安全多次调用） */
+    dispose: () => void;
+};
+/**
+ * 统一包根解析：目录 / 顶层归档 / 嵌套 .mcpack|.zip|.mcaddon。
+ * 规则：先展开归档为目录树，再只认含 manifest.json 的目录为包根。
+ * 用户目录内的嵌套归档解到独立 temp，不修改原目录。
+ */
+export declare function resolvePackRoots(src: string, opts?: {
+    maxDirDepth?: number;
+    maxArchiveRounds?: number;
+}): Promise<ResolvePackRootsResult>;
 /** 解压 zip/mcpack/mcaddon 到临时目录，返回该目录（经 zipx 防 zip-slip） */
 export declare function extractArchiveToTemp(filePath: string): Promise<string>;
 /** 扫描世界内已安装 BP/RP 目录 */
 export declare function listInstalledWorldPacks(bdsRoot: string, levelName: string): InstalledWorldPack[];
-/** RP/BP 第三位版本 +1，写回 manifest */
+/**
+ * 将目标包 manifest.json 中的 Patch 版本号递增（+1）并持久化写回。
+ *
+ * @param packDir 包根目录路径。
+ * @returns 递增后的版本三元组 `[major, minor, patch]`。
+ */
 export declare function bumpPackPatchVersion(packDir: string): [number, number, number];
-/** 写入 header.version（并同步 modules[].version 的 patch） */
+/**
+ * 向目标包的 manifest.json 写入新的版本号，并同步更新内部 modules 的 patch 版本。
+ *
+ * @param packDir 包根目录路径。
+ * @param next 待写入的版本三元组。
+ * @returns 写入确认的版本三元组。
+ */
 export declare function writePackHeaderVersion(packDir: string, next: [number, number, number]): [number, number, number];
 /** 读取 BP manifest 中依赖的资源包 uuid（非 @minecraft 模块） */
 export declare function readPackDependencyUuids(packDir: string): string[];
-/** 确保版本严格大于 floor（patch/minor 抬一级） */
-export declare function ensureVersionGreaterThan(packDir: string, floor: [number, number, number], component?: "patch" | "minor"): [number, number, number];
+/** 比较 SemVer 三元组；a>b 正，a<b 负，相等 0 */
+export declare function compareSemVer3(a: [number, number, number], b: [number, number, number]): number;
+/** 取较大的 SemVer 三元组 */
+export declare function maxSemVer3(a: [number, number, number], b: [number, number, number]): [number, number, number];
+/** 按 component 抬一级 */
+export declare function bumpSemVer3(v: [number, number, number], component: "patch" | "minor"): [number, number, number];
+/**
+ * 进服启用版本：max(远程/新包, 旧启用) 再抬一级。
+ * 单一规则，禁止 while 追赶（作者乱写高版本如 [1,21,100] 时也能一次算完）。
+ */
+export declare function nextEnabledVersion(remote: [number, number, number], previous: [number, number, number], component?: "patch" | "minor"): [number, number, number];
+/**
+ * 将包目录 manifest 抬到 nextEnabledVersion(当前, previous)。
+ * previous 一般为更新前已安装 RP / 世界 enable 列表中的版本。
+ */
+export declare function ensureVersionGreaterThan(packDir: string, previous: [number, number, number], component?: "patch" | "minor"): [number, number, number];
 export interface InstallPackResult {
     ok: boolean;
     skipped?: boolean;
@@ -56,9 +147,71 @@ export interface InstallPackResult {
         incoming: PackManifestInfo;
     };
 }
+/** 目标父目录内已占用项（供纯决策，不含 FS 副作用） */
+export type DestOccupancy = {
+    folderName: string;
+    dir: string;
+    uuid: string | null;
+    version: [number, number, number] | null;
+    /** 可读时的展示名；决策不依赖，仅供 conflict UI */
+    name?: string;
+    /** 可读时的包类型；决策展示优先用真实 kind，避免伪造 incoming.kind（LSP） */
+    kind?: WorldPackKind;
+};
+export type PackInstallPlan = {
+    kind: "fresh";
+    folderName: string;
+    incoming: PackManifestInfo;
+} | {
+    kind: "overwriteInPlace";
+    folderName: string;
+    dir: string;
+    incoming: PackManifestInfo;
+    existing: PackManifestInfo & {
+        dir: string;
+    };
+} | {
+    kind: "needConfirm";
+    folderName: string;
+    dir: string;
+    incoming: PackManifestInfo;
+    existing: PackManifestInfo & {
+        dir: string;
+    };
+};
+/**
+ * 读单目录占用事实（info 优先，否则 header）。
+ * 解析失败返回 null；不抛 BOM（readJsonFile 已剥离）。
+ */
+export declare function readPackDirOccupancy(dir: string): {
+    uuid: string;
+    version: [number, number, number];
+    name?: string;
+    kind?: WorldPackKind;
+} | null;
+/** 扫描 destParent 下含 manifest 的目录占用（单一事实源：readPackDirOccupancy） */
+export declare function scanDestOccupancy(destParent: string): DestOccupancy[];
+/**
+ * 纯决策：装到哪、是否需确认、是否原地覆盖。
+ * 同 uuid：incoming 版本严格更大 → 静默覆盖；≤ 已有且 !force → needConfirm；force → 原地覆盖。
+ */
+export declare function decidePackInstallPlan(opts: {
+    incoming: PackManifestInfo;
+    hint?: string;
+    occupancy: readonly DestOccupancy[];
+    force?: boolean;
+}): PackInstallPlan;
+/** 落盘后校验：防止旁路安装 / 拷贝失败仍报成功 */
+export declare function verifyInstalledPack(destDir: string, incoming: PackManifestInfo): {
+    ok: true;
+    info: PackManifestInfo;
+} | {
+    ok: false;
+    reason: string;
+};
 /**
  * 将包目录安装到 destParent（behavior_packs 或 resource_packs）。
- * force=true 时覆盖冲突；否则返回 conflict 供上层询问。
+ * 编排：scan → decide → apply → verify。同 uuid 版本更高时静默原地覆盖。
  */
 export declare function installPackDirectory(opts: {
     srcDir: string;

package/dist/world-packs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world-packs.d.ts","sourceRoot":"","sources":["../src/world-packs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"world-packs.d.ts","sourceRoot":"","sources":["../src/world-packs.ts"],"names":[],"mappings":"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"}

package/dist/world-packs.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { copyDirAsync } from "./fsx.js";
+import { copyDirAsync, readJsonFile } from "./fsx.js";
 import {
   bdsWorldLevelDir,
   bdsWorldsDir,
@@ -23,6 +23,41 @@ function formatWorldPackFolderName(rawName, kind) {
   if (s.startsWith("[RP]") || s.startsWith("[BP]")) return s;
   return `${prefix} ${s}`;
 }
+function stripWorldPackFolderPrefix(rawName) {
+  return String(rawName ?? "").replace(/^\[BP\]\s*/i, "").replace(/^\[RP\]\s*/i, "").replace(/\.(zip|mcpack|mcaddon)$/i, "").replace(/\s+/g, " ").trim();
+}
+function isGenericPackFolderStem(rawName) {
+  const s = stripWorldPackFolderPrefix(rawName);
+  if (!s) return true;
+  if (s.length <= 2) return true;
+  return /^(bp|rp|b|r|pack|packs|behavior|behaviours?|resource|resources)$/i.test(s);
+}
+function allocatePackFolderName(opts) {
+  const hint = opts.hint && opts.hint.trim() || "";
+  const preferred = isGenericPackFolderStem(hint) ? opts.info.name || hint || "pack" : hint;
+  let folderName = formatWorldPackFolderName(preferred, opts.info.kind);
+  const allow = opts.allowFolderName ? path.basename(opts.allowFolderName) : null;
+  if (allow && folderName === allow) return folderName;
+  const taken = new Set([...opts.takenFolderNames].filter((n) => n !== allow));
+  if (!taken.has(folderName)) return folderName;
+  const withUuid = formatWorldPackFolderName(
+    `${stripWorldPackFolderPrefix(preferred)} ${opts.info.uuid.slice(0, 8)}`,
+    opts.info.kind
+  );
+  if (!taken.has(withUuid)) return withUuid;
+  let i = 2;
+  while (taken.has(`${withUuid}_${i}`)) i++;
+  return `${withUuid}_${i}`;
+}
+function choosePackInstallFolderName(opts) {
+  const taken = listPackDirsIn(opts.destParent).map((d) => path.basename(d));
+  return allocatePackFolderName({
+    info: opts.info,
+    takenFolderNames: taken,
+    ...opts.hint !== void 0 ? { hint: opts.hint } : {},
+    ...opts.allowFolderName !== void 0 ? { allowFolderName: opts.allowFolderName } : {}
+  });
+}
 function detectPackKindFromManifest(raw) {
   const types = (raw.modules ?? []).map((m) => String(m.type ?? "").toLowerCase());
   if (types.includes("resources")) return "resource";
@@ -33,7 +68,7 @@ function readPackManifestInfo(packDir) {
   const file = path.join(packDir, "manifest.json");
   if (!fs.existsSync(file)) return null;
   try {
-    const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    const raw = readJsonFile(file);
     const kind = detectPackKindFromManifest(raw);
     const uuid = raw.header?.uuid;
     const ver = raw.header?.version;
@@ -85,6 +120,118 @@ function isPackArchive(filePath) {
   const lower = filePath.toLowerCase();
   return ARCHIVE_EXTS.some((ext) => lower.endsWith(ext));
 }
+function archiveStem(filePath) {
+  const base = path.basename(filePath);
+  const lower = base.toLowerCase();
+  for (const ext of ARCHIVE_EXTS) {
+    if (lower.endsWith(ext)) return base.slice(0, -ext.length);
+  }
+  return path.parse(base).name;
+}
+function uniqueSiblingExtractDir(archivePath) {
+  const parent = path.dirname(archivePath);
+  let dest = path.join(parent, archiveStem(archivePath) || "pack");
+  if (!fs.existsSync(dest)) return dest;
+  let i = 2;
+  while (fs.existsSync(`${dest}_${i}`)) i++;
+  return `${dest}_${i}`;
+}
+function listPackArchiveFiles(root, opts) {
+  const maxDepth = opts?.maxDepth ?? 4;
+  const out = [];
+  const abs = path.resolve(root);
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return out;
+  function walk(dir, depth) {
+    if (fs.existsSync(path.join(dir, "manifest.json"))) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith(".") || e.name === "node_modules") continue;
+      const full = path.join(dir, e.name);
+      if (e.isFile() && isPackArchive(full)) {
+        out.push(full);
+        continue;
+      }
+      if (e.isDirectory() && depth < maxDepth) walk(full, depth + 1);
+    }
+  }
+  walk(abs, 0);
+  return out;
+}
+async function expandNestedArchivesInPlace(workDir, opts) {
+  const maxRounds = opts?.maxRounds ?? 3;
+  const maxScanDepth = opts?.maxScanDepth ?? 4;
+  let expanded = 0;
+  for (let round = 0; round < maxRounds; round++) {
+    const archives = listPackArchiveFiles(workDir, { maxDepth: maxScanDepth });
+    if (archives.length === 0) break;
+    for (const arch of archives) {
+      const dest = uniqueSiblingExtractDir(arch);
+      await fs.promises.mkdir(dest, { recursive: true });
+      await extractZipFileToDir(arch, dest);
+      await fs.promises.unlink(arch);
+      expanded++;
+    }
+  }
+  return expanded;
+}
+async function resolvePackRoots(src, opts) {
+  const maxDirDepth = opts?.maxDirDepth ?? 4;
+  const maxArchiveRounds = opts?.maxArchiveRounds ?? 3;
+  const temps = [];
+  const dispose = () => {
+    for (const d of temps.splice(0, temps.length)) {
+      try {
+        fs.rmSync(d, { recursive: true, force: true });
+      } catch {
+      }
+    }
+  };
+  const abs = path.resolve(src);
+  if (!fs.existsSync(abs)) return { roots: [], dispose };
+  try {
+    const st = fs.statSync(abs);
+    if (st.isFile()) {
+      if (!isPackArchive(abs)) return { roots: [], dispose };
+      const tmp = await extractArchiveToTemp(abs);
+      temps.push(tmp);
+      await expandNestedArchivesInPlace(tmp, {
+        maxRounds: maxArchiveRounds,
+        maxScanDepth: maxDirDepth
+      });
+      return { roots: discoverPackRoots(tmp, { maxDepth: maxDirDepth }), dispose };
+    }
+    if (!st.isDirectory()) return { roots: [], dispose };
+    const nestedArchives = listPackArchiveFiles(abs, { maxDepth: maxDirDepth });
+    if (nestedArchives.length === 0) {
+      return { roots: discoverPackRoots(abs, { maxDepth: maxDirDepth }), dispose };
+    }
+    const roots = discoverPackRoots(abs, { maxDepth: maxDirDepth });
+    const seen = new Set(roots.map((r) => path.resolve(r)));
+    for (const arch of nestedArchives) {
+      const tmp = await extractArchiveToTemp(arch);
+      temps.push(tmp);
+      await expandNestedArchivesInPlace(tmp, {
+        maxRounds: maxArchiveRounds,
+        maxScanDepth: maxDirDepth
+      });
+      for (const r of discoverPackRoots(tmp, { maxDepth: maxDirDepth })) {
+        const key = path.resolve(r);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        roots.push(r);
+      }
+    }
+    return { roots, dispose };
+  } catch (e) {
+    dispose();
+    throw e;
+  }
+}
 async function extractArchiveToTemp(filePath) {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "sfmc-pack-"));
   await extractZipFileToDir(filePath, tmp);
@@ -143,7 +290,7 @@ function listInstalledWorldPacks(bdsRoot, levelName) {
 function bumpPackPatchVersion(packDir) {
   const file = path.join(packDir, "manifest.json");
   if (!fs.existsSync(file)) throw new Error(`manifest.json missing: ${packDir}`);
-  const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+  const raw = readJsonFile(file);
   const ver = raw.header?.version;
   if (!Array.isArray(ver) || ver.length < 3) throw new Error(`invalid header.version in ${file}`);
   const next = [Number(ver[0]), Number(ver[1]), Number(ver[2]) + 1];
@@ -152,7 +299,7 @@ function bumpPackPatchVersion(packDir) {
 function writePackHeaderVersion(packDir, next) {
   const file = path.join(packDir, "manifest.json");
   if (!fs.existsSync(file)) throw new Error(`manifest.json missing: ${packDir}`);
-  const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+  const raw = readJsonFile(file);
   if (!raw.header) raw.header = {};
   raw.header.version = next;
   if (Array.isArray(raw.modules)) {
@@ -170,80 +317,164 @@ function readPackDependencyUuids(packDir) {
   const file = path.join(packDir, "manifest.json");
   if (!fs.existsSync(file)) return [];
   try {
-    const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    const raw = readJsonFile(file);
     return (raw.dependencies ?? []).map((d) => d.uuid).filter((u) => typeof u === "string" && u.length > 0);
   } catch {
     return [];
   }
 }
-function ensureVersionGreaterThan(packDir, floor, component = "patch") {
+function compareSemVer3(a, b) {
+  for (let i = 0; i < 3; i++) {
+    const d = a[i] - b[i];
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+function maxSemVer3(a, b) {
+  return compareSemVer3(a, b) >= 0 ? a : b;
+}
+function bumpSemVer3(v, component) {
+  return component === "minor" ? [v[0], v[1] + 1, 0] : [v[0], v[1], v[2] + 1];
+}
+function nextEnabledVersion(remote, previous, component = "patch") {
+  return bumpSemVer3(maxSemVer3(remote, previous), component);
+}
+function ensureVersionGreaterThan(packDir, previous, component = "patch") {
   const info = readPackManifestInfo(packDir);
   if (!info) throw new Error(`cannot read pack version: ${packDir}`);
-  let next = component === "minor" ? [info.version[0], info.version[1] + 1, 0] : [info.version[0], info.version[1], info.version[2] + 1];
-  const cmp = (a, b) => {
-    for (let i = 0; i < 3; i++) {
-      const d = a[i] - b[i];
-      if (d !== 0) return d;
+  const next = nextEnabledVersion(info.version, previous, component);
+  return writePackHeaderVersion(packDir, next);
+}
+function readPackDirOccupancy(dir) {
+  const info = readPackManifestInfo(dir);
+  if (info) {
+    return {
+      uuid: info.uuid,
+      version: info.version,
+      name: info.name,
+      kind: info.kind
+    };
+  }
+  const header = readPackManifestHeader(dir);
+  if (header) {
+    return { uuid: header.uuid, version: header.version };
+  }
+  return null;
+}
+function scanDestOccupancy(destParent) {
+  const out = [];
+  for (const dir of listPackDirsIn(destParent)) {
+    let facts = null;
+    try {
+      facts = readPackDirOccupancy(dir);
+    } catch {
     }
-    return 0;
-  };
-  while (cmp(next, floor) <= 0) {
-    if (component === "minor") next = [next[0], next[1] + 1, 0];
-    else next = [next[0], next[1], next[2] + 1];
+    out.push({
+      folderName: path.basename(dir),
+      dir,
+      uuid: facts?.uuid ?? null,
+      version: facts?.version ?? null,
+      ...facts?.name ? { name: facts.name } : {},
+      ...facts?.kind ? { kind: facts.kind } : {}
+    });
   }
-  return writePackHeaderVersion(packDir, next);
+  return out;
+}
+function decidePackInstallPlan(opts) {
+  const force = Boolean(opts.force);
+  const incomingUuid = opts.incoming.uuid.toLowerCase();
+  const same = opts.occupancy.find((o) => o.uuid != null && o.uuid.toLowerCase() === incomingUuid);
+  if (same) {
+    const existingVersion = same.version ?? [0, 0, 0];
+    const existing = {
+      name: same.name ?? same.folderName,
+      uuid: same.uuid,
+      version: existingVersion,
+      kind: same.kind ?? opts.incoming.kind,
+      dir: same.dir
+    };
+    const newer = compareSemVer3(opts.incoming.version, existing.version) > 0;
+    if (force || newer) {
+      return {
+        kind: "overwriteInPlace",
+        folderName: same.folderName,
+        dir: same.dir,
+        incoming: opts.incoming,
+        existing
+      };
+    }
+    return {
+      kind: "needConfirm",
+      folderName: same.folderName,
+      dir: same.dir,
+      incoming: opts.incoming,
+      existing
+    };
+  }
+  const folderName = allocatePackFolderName({
+    info: opts.incoming,
+    takenFolderNames: opts.occupancy.map((o) => o.folderName),
+    ...opts.hint !== void 0 ? { hint: opts.hint } : {}
+  });
+  return { kind: "fresh", folderName, incoming: opts.incoming };
+}
+function verifyInstalledPack(destDir, incoming) {
+  const info = readPackManifestInfo(destDir);
+  if (!info) return { ok: false, reason: "verify: dest has no readable manifest" };
+  if (info.uuid.toLowerCase() !== incoming.uuid.toLowerCase()) {
+    return { ok: false, reason: `verify: uuid mismatch got=${info.uuid} want=${incoming.uuid}` };
+  }
+  if (info.kind !== incoming.kind) {
+    return { ok: false, reason: `verify: kind mismatch got=${info.kind} want=${incoming.kind}` };
+  }
+  if (compareSemVer3(info.version, incoming.version) !== 0) {
+    return {
+      ok: false,
+      reason: `verify: version mismatch got=${info.version.join(".")} want=${incoming.version.join(".")}`
+    };
+  }
+  return { ok: true, info };
 }
 async function installPackDirectory(opts) {
   const info = readPackManifestInfo(opts.srcDir);
   if (!info) {
     return { ok: false, reason: "invalid or unrecognized manifest.json" };
   }
-  const folderName = formatWorldPackFolderName(
-    opts.folderName ?? path.basename(opts.srcDir),
-    info.kind
-  );
   await fs.promises.mkdir(opts.destParent, { recursive: true });
-  let conflictDir = null;
-  let conflictExisting = null;
-  for (const dir of listPackDirsIn(opts.destParent)) {
-    const existing = readPackManifestInfo(dir);
-    const sameFolder = path.basename(dir) === folderName;
-    const sameUuid = !!existing && existing.uuid === info.uuid;
-    if (!sameFolder && !sameUuid) continue;
-    conflictDir = dir;
-    if (existing) {
-      conflictExisting = existing;
-    } else {
-      const header = readPackManifestHeader(dir);
-      conflictExisting = {
-        name: path.basename(dir),
-        uuid: header?.uuid ?? "(unknown)",
-        version: header?.version ?? [0, 0, 0],
-        kind: info.kind
-      };
-    }
-    break;
-  }
-  if (conflictDir && !opts.force) {
+  const occupancy = scanDestOccupancy(opts.destParent);
+  const plan = decidePackInstallPlan({
+    incoming: info,
+    hint: opts.folderName ?? path.basename(opts.srcDir),
+    occupancy,
+    ...opts.force !== void 0 ? { force: opts.force } : {}
+  });
+  if (plan.kind === "needConfirm") {
     return {
       ok: false,
       skipped: true,
       reason: "conflict",
       conflict: {
-        existing: { ...conflictExisting ?? info, dir: conflictDir },
+        existing: plan.existing,
         incoming: info
       }
     };
   }
-  const destDir = path.join(opts.destParent, folderName);
-  if (conflictDir && path.resolve(conflictDir) !== path.resolve(destDir)) {
-    await fs.promises.rm(conflictDir, { recursive: true, force: true });
+  const destDir = path.join(opts.destParent, plan.folderName);
+  if (plan.kind === "overwriteInPlace" && path.resolve(plan.dir) !== path.resolve(destDir)) {
+    return {
+      ok: false,
+      reason: `invariant: overwrite path drift plan.dir=${plan.dir} destDir=${destDir}`
+    };
   }
   if (fs.existsSync(destDir)) {
     await fs.promises.rm(destDir, { recursive: true, force: true });
   }
   await copyDirAsync(opts.srcDir, destDir);
-  return { ok: true, destDir, folderName, info };
+  const verified = verifyInstalledPack(destDir, info);
+  if (!verified.ok) {
+    return { ok: false, reason: verified.reason, folderName: plan.folderName, info };
+  }
+  return { ok: true, destDir, folderName: plan.folderName, info: verified.info };
 }
 async function enableInstalledPack(opts) {
   await enablePackInWorld({
@@ -312,23 +543,38 @@ function findInstalledPackById(packs, id) {
   ) ?? null;
 }
 export {
+  allocatePackFolderName,
   bumpPackPatchVersion,
+  bumpSemVer3,
+  choosePackInstallFolderName,
+  compareSemVer3,
+  decidePackInstallPlan,
   detectPackKindFromManifest,
   disableInstalledPack,
   discoverPackRoots,
   enableInstalledPack,
   ensureVersionGreaterThan,
+  expandNestedArchivesInPlace,
   extractArchiveToTemp,
   findInstalledPackById,
   formatWorldPackFolderName,
   installPackDirectory,
+  isGenericPackFolderStem,
   isPackArchive,
   listInstalledWorldPacks,
+  listPackArchiveFiles,
   listWorldEnableEntries,
   listWorldEnableListResult,
+  maxSemVer3,
+  nextEnabledVersion,
   readPackDependencyUuids,
+  readPackDirOccupancy,
   readPackManifestInfo,
+  resolvePackRoots,
+  scanDestOccupancy,
+  stripWorldPackFolderPrefix,
   uninstallInstalledPack,
+  verifyInstalledPack,
   worldPackParentDir,
   writePackHeaderVersion
 };