@bepack/cli 0.1.0-beta.1 → 0.1.0-beta.2

package/reference.md

@@ -139,6 +139,7 @@ type UserConfig = {
                  */
                 define?: Record<string, string>;
                 tsconfig?: string;
+                /** 打包前是否运行 tsc 类型检查。默认 true（即默认会跑）。 */
                 typecheck?: boolean;
                 preserveModules?: boolean;
                 external?: (string | RegExp)[];
@@ -151,10 +152,16 @@ type UserConfig = {
                 };
                 /** 编译脚本输出目录，相对于 BP root。默认 "scripts"。 */
                 scriptOutputDir?: string;
+                /**
+                 * 额外的 Rolldown 选项（对象），或自定义函数 (options, context) => options。
+                 * 在 BePack 生成的选项之上增量合并；input 与输出位置字段由 BePack 管理。
+                 */
+                rolldown?: RolldownOptions | RolldownCustomizeFunction;
+                /** Rolldown 配置文件路径（相对项目根或绝对路径），支持 .ts/.mts/.js/.mjs。 */
+                rolldownConfig?: string;
             };
             /** 所有 BP 依赖都在此声明——包括清单依赖和纯代码依赖。 */
             dependencies?: Record<string, "stable" | "beta" | "preview" | string>;
-            achievement?: boolean;
             /**
              * manifest 生成策略。
              * - `merge: "preserve"`（默认）：增量合并，保留用户手写字段。
@@ -214,6 +221,11 @@ type UserConfig = {
                 name?: string | { bp?: string; rp?: string };
             }
         >;
+        /**
+         * 复制到开发目录时也生成 __brarchive 归档，方便实机验证"打包后的形态"。
+         * 默认关闭；要求与 pack.optimize 相同的 min_engine_version >= 1.26.40。
+         */
+        optimize?: boolean | PackOptimizeOptions;
     };
 
     dev?: {
@@ -227,6 +239,24 @@ type UserConfig = {
     pack?: {
         name?: string;
         outDir?: string;
+        /**
+         * 把包内散文件打成 __brarchive 归档（Minecraft 官方 pack optimizer 的行为）。
+         * 默认关闭。开启后 BePack 会往产物 manifest 写入
+         * header.pack_optimization_version = "0.1.0"（这是让引擎读归档的开关）。
+         * 只影响 pack 产物；复制到开发目录默认不优化，可用 copy.optimize 开启。
+         */
+        optimize?: boolean | {
+            /** 额外保留"散文件 + 归档存根"的目录（默认按包类型内置列表）。传 false 表示全部只进归档。 */
+            keepLoose?: string[] | false;
+            /** 这些目录完全不归档，只留散文件。默认无。 */
+            exclude?: string[];
+            /** 是否压缩 JSON 条目。默认 true。 */
+            minifyJson?: boolean;
+            /** 产物 manifest 里 header.pack_optimization_version 的取值。默认 "0.1.0"。 */
+            packOptimizationVersion?: string;
+            /** 关闭 min_engine_version < 1.26.40 时的兼容性警告。默认 false（会警告但照常输出）。 */
+            allowUnsupportedTarget?: boolean;
+        };
     };
 };
 ```
@@ -453,7 +483,6 @@ BP 清单受控字段：
 - 脚本模块
 - BePack 管理的 `@minecraft/*` 依赖
 - BP/RP 相互依赖
-- `metadata.product_type`（仅在 `achievement: true` 时）
 
 RP 清单受控字段：
 
@@ -472,12 +501,6 @@ RP 清单受控字段：
 
 当同时配置了 BP 和 RP 时，BePack 会维护它们 header UUID 之间的相互依赖。
 
-成就元数据：
-
-- `packs.bp.achievement: true` 添加 `metadata.product_type = "addon"`。
-- 每个受管理的 Script API 依赖必须使用 `stable` 说明符。
-- 如果在启用成就时使用了 `beta` 或 `preview` 依赖，BePack 会抛出 `ACHIEVEMENT_REQUIRES_STABLE_API`。
-
 ### manifest 生成策略
 
 `packs.bp.manifest` / `packs.rp.manifest` 控制清单如何与已有文件合并：
@@ -520,23 +543,28 @@ client 侧保持默认 `preserve`（尊重手写 manifest），server 侧 `clean
 ```txt
 清单修补
 hooks.beforeBuild
-类型检查
+类型检查（tsc --noEmit，默认开启）
 Rolldown 构建
 hooks.afterBuild
 可选复制
 可选打包
 ```
 
+> **默认会运行 TypeScript 类型检查。** 只要配置了 `packs.bp.compile`，`bepack build` 与 `bepack dev` 都会在 Rolldown 打包**之前**执行 `tsc --noEmit`；检查失败会以 `TYPECHECK_FAILED` 终止本次构建，不会产出残缺脚本。跳过方式：CLI `--skip-typecheck`，或 `packs.bp.compile.typecheck: false`。注意类型检查与打包是两件独立的事——自定义 Rolldown 选项、替换 `rolldown` 配置都不会关闭它，要关只能显式配置。
+
 CLI 选项：
 
 - `--mode <value>`：执行模式，透传给 Hook 上下文（`HookContext.mode`）。不设则为 `undefined`。Hook 内自行判断是否执行特定逻辑。
+- `--rolldown-config <path>`：临时指定 Rolldown 配置文件，覆盖 `packs.bp.compile.rolldownConfig`（`bepack dev` 同样支持）。
+- `--optimize`：与 `--pack` / `--copy` 一起使用时，把产物（或开发目录）优化为 `__brarchive/` 归档（`--no-optimize` 可覆盖配置）。详见《打包》一节的 Pack 优化。
 
 类型检查行为：
 
-- 默认：系统 `tsc --noEmit`。
+- **默认：系统 `tsc --noEmit`（`packs.bp.compile.typecheck` 默认为 `true`）。** 只有显式设置 `typecheck: false` 或传 `--skip-typecheck` 才会跳过。
 - `build.useNpx: true` 或 `--use-npx`：`npx tsc --noEmit`。
 - `packs.bp.compile.cache`：增量编译缓存配置。`cache.dev`（默认 `true`）控制 dev 模式；`cache.build`（默认 `false`）控制 build 模式。`cache.file` 指定 `.tsbuildinfo` 路径。`bepack build --cache` / `--no-cache` 可覆盖 build 模式。`dev` 命令默认启用缓存。
 - 缺少 `tsconfig.json` 会提前失败，返回 `TYPECHECK_FAILED`。
+- 类型检查在 `hooks.beforeBuild` 之后、Rolldown 之前运行；`--dry-run` 会跳过它。
 
 Rolldown 行为：
 
@@ -552,7 +580,7 @@ Rolldown 行为：
 
 > 注意：构建命令（`build` / `dev`）不再要求 BP 必须存在。如果项目只有 RP 或 BP 没有配置 `compile`，则跳过编译流程，只执行 manifest 修补和可选的文件复制/打包。
 
-`packs.bp.compile.externalDependencies` 默认为 `true`，因此内置的 `manifest: true` 受管理包（例如 `@minecraft/server`、`@minecraft/server-ui`、`@minecraft/server-net`）不会被内联打包。`manifest: false` 的包（例如 `@minecraft/vanilla-data`）可以被内联打包。设置 `externalDependencies` 为 `false` 可自定义，或通过 `packs.bp.compile.external` 添加额外条目。
+`manifest: true` 的受管理包（例如 `@minecraft/server`、`@minecraft/server-ui`、`@minecraft/server-net`）**始终**作为 external 写入 rolldown，不会被内联打包；`manifest: false` 的包（例如 `@minecraft/vanilla-data`）可以被打包进产物。需要额外的 external 时，通过 `packs.bp.compile.external` 追加字符串或正则。
 
 `build.timing: true` 或 `--timing` 可在构建时显示各步骤的耗时明细，便于排查性能瓶颈：
 
@@ -564,6 +592,95 @@ timing    rolldown        45 ms
 
 `--timing` 同样支持 `bepack dev` 命令。
 
+## 自定义 Rolldown 配置
+
+`packs.bp.compile` 覆盖了常见场景，Rolldown 的完整能力通过三个入口开放：
+
+- `packs.bp.compile.rolldown`：内联选项对象，或自定义函数；
+- `packs.bp.compile.rolldownConfig`：Rolldown 配置文件路径（相对项目根或绝对路径）；
+- CLI：`bepack build --rolldown-config <path>` / `bepack dev --rolldown-config <path>`，临时替换配置文件。
+
+> 自定义 Rolldown 配置**不会**关闭类型检查：`bepack build` / `bepack dev` 依然会先执行 `tsc --noEmit`（默认开启，详见《构建》一节）。
+
+### 对象形式
+
+```ts
+packs: {
+    bp: {
+        compile: {
+            entry: "src/main.ts",
+            rolldown: {
+                resolve: { alias: { "@lib": "./src/lib" } },
+                treeshake: { moduleSideEffects: false },
+                output: { sourcemap: true },
+            },
+        },
+    },
+}
+```
+
+### 函数形式
+
+函数接收当前已合并的选项与上下文，返回值再按同样的规则合并一次；返回空则不做改动：
+
+```ts
+packs: {
+    bp: {
+        compile: {
+            rolldown(options, context) {
+                if (context.command === "dev") return { output: { sourcemap: true } };
+                return {};
+            },
+        },
+    },
+}
+```
+
+上下文 `RolldownCustomizeContext` 字段：`command`（`"build"` / `"dev"`）、`mode`（CLI `--mode`）、`target`、`entry`、`outDir`、`outFile`、`preserveModules`，路径均为绝对路径。
+
+### 配置文件
+
+配置文件由 Rolldown 自带的加载器读取，因此 `.ts` / `.mts` / `.js` / `.mjs` 都支持，默认导出可以是选项对象、单元素数组或函数（与 `rolldown.config.ts` 用法一致）：
+
+```ts
+// rolldown.bp.config.ts
+import { defineConfig } from "rolldown";
+
+export default defineConfig({
+    resolve: { alias: { "@lib": "./src/lib" } },
+});
+```
+
+- 只支持**单个**配置：导出多元素数组会报 `CONFIG_INVALID`（BePack 每次只构建一个 BP）。
+- `.ts` 配置文件会先被 Rolldown 打包成 `rolldown.config.<hash>.js` 再导入，随后删除；`dev` watcher 已忽略该临时文件。
+- 优先级：`--rolldown-config` > `compile.rolldownConfig` > `compile.rolldown`。
+
+### 合并规则
+
+BePack 先生成基础选项，再把自定义选项合并上去：
+
+| 字段 | 规则 |
+| --- | --- |
+| `plugins` | 追加在 BePack 插件（replace / define）之后 |
+| `external` | 取并集（字符串去重，`RegExp` 原样保留） |
+| `transform`、`resolve`、`experimental`、`checks`、`optimization`、`watch`、`moduleTypes`、`output` | 一层深合并；其中 `transform.define` 按 key 合并，不会清掉 `compile.define` |
+| 其它字段 | 用户值直接覆盖 |
+
+函数返回值按同一规则合并——因此只能追加，不能移除 BePack 的插件或受管理的外部依赖。
+
+### 受保护字段
+
+以下字段由 BePack 管理，配成其它值会报 `CONFIG_INVALID`（manifest 的 script entry、复制、打包、dev 监听都依赖它们）：
+
+| 字段 | 替代方式 |
+| --- | --- |
+| `input` | `packs.bp.compile.entry` |
+| `output.file` / `output.dir` | `packs.bp.compile.scriptOutputDir` |
+| `output.preserveModules` / `output.preserveModulesRoot` | `packs.bp.compile.preserveModules` |
+| `output.entryFileNames` | manifest script entry 假定"每个源模块一个 `.js`" |
+| `output.format` | Script API 只支持 ESM |
+| `output` 数组（多输出） | 不支持，BePack 只写一个输出 |
+
 ## 构建注入与条件编译
 
 BePack 提供两种编译期注入机制，**建议按用途选择**：
@@ -658,6 +775,7 @@ BePack 默认 `preserveModules: true`，Rolldown 仍会做 tree-shaking：
 - 在监视前先执行一次初始构建（manifest + 若有 compile 则编译）。
 - 支持 `--skip-typecheck` 跳过类型检查（与 `build` 命令一致）。
 - 支持 `--mode <value>`，用法与 `build` 命令相同，透传给 Hook 上下文。初始构建和后续增量重建均会传入该值。
+- 支持 `--optimize`：每次自动复制都生成 `__brarchive/` 归档（等价于 `copy.optimize: true`，`--no-optimize` 可覆盖配置）。
 - 默认监视的路径：
     - `packs.bp.compile.entry` 所在目录（仅在 BP 配置了 compile 时，TypeScript 源码变化 → 触发编译）
     - BP 的默认 include 列表 + `packs.bp.include` 中的文件/文件夹（不含 `scripts` 和 `manifest.json`）
@@ -691,6 +809,12 @@ export default defineConfig({
 
 **如果没有配置任何复制目标，`bepack copy` 会报错。** 复制前会验证目标目录是否存在，不存在则报错。
 
+CLI 选项：
+
+- `--target <target>`：指定复制目标。
+- `--all`：复制到所有目标。
+- `--optimize`：复制时生成 `__brarchive/` 归档（`--no-optimize` 覆盖配置），详见下文《复制时也做 Pack 优化》。
+
 ### 内置目标
 
 - `win`
@@ -785,7 +909,7 @@ copy: {
 ```
 scripts  manifest.json  animation_controllers  animations  biomes
 blocks  entities  functions  items  loot_tables  pack_icon.png
-recipes  spawn_rules  structures  texts  trading
+recipes  shapes  spawn_rules  structures  texts  trading
 feature_rules  features  worldgen
 ```
 
@@ -833,6 +957,25 @@ dev: {
 
 `build.copy` 和 `dev.copy` 默认为 `false`（不复制）。`true` 表示使用 `copy.defaultTarget`，字符串表示使用指定目标。
 
+### 复制时也做 Pack 优化
+
+复制到开发目录默认是"散文件"形态，与发布产物（可能带 `__brarchive/`）不同。为了让开发者能在实机里提前验证**打包后的形态**，可以单独开启 `copy.optimize`：
+
+```ts
+copy: {
+    defaultTarget: "minecraft",
+    optimize: true,          // 或与 pack.optimize 相同的选项对象
+},
+```
+
+```bash
+bepack copy --optimize               # 临时开启（--no-optimize 覆盖配置）
+bepack build --copy --optimize       # build 的 --optimize 同时作用于 pack 与 copy
+bepack dev --optimize                # dev 的每次自动复制也生成归档
+```
+
+行为与 `pack.optimize` 完全一致（同一套镜像规则、排除表、JSON 压缩、1.26.40 门槛），区别只是输出到开发目录而不是 `.mcpack`。默认不保留散文件，因此开发目录里的形态与发布产物一致；需要同时保留散文件时用 `optimize: { keepLooseFiles: true }`。
+
 ## 打包
 
 `bepack pack` 创建：
@@ -860,6 +1003,72 @@ pack: {
 
 打包输入配置必须显式指定，且输入路径必须存在。这可以防止意外打包猜测的默认目录。
 
+### Pack 优化（`__brarchive`）
+
+Minecraft 1.26.40 起官方提供 **Pack Optimization**：把包里的散文件装进 `__brarchive/` 归档，并对 JSON 做压缩。BePack 可以在打包时做同样的事：
+
+```ts
+pack: {
+    outDir: "dist",
+    optimize: true,               // 或传入下面的选项对象
+}
+```
+
+```bash
+bepack pack --optimize            # 临时开启（--no-optimize 可覆盖配置里的开启状态）
+bepack build --pack --optimize    # 构建后打包并优化
+```
+
+产物结构（只影响 `.mcpack` / `.mcaddon` 内部，磁盘上的包目录**不会被修改**）：
+
+```txt
+manifest.json                     # 包根散文件保持原样，并写入 pack_optimization_version
+functions/diag_fn.mcfunction      # 按路径引用的目录：散文件保留（归档里只登记文件名）
+texts/en_US.lang
+__brarchive/entities.brarchive    # 注册表型目录：完整内容进归档，散文件删除
+__brarchive/entities/sub.brarchive   # 每个目录一个归档，镜像目录树
+```
+
+规则：
+
+- **开关是产物 `manifest.json` 里的 `header.pack_optimization_version`**，BePack 默认写入 `"0.1.0"`。只有这个字段能让引擎从 `__brarchive/` 读取注册表；写成游戏版本号（如 `"1.26.40"`）无效。它只写进产物，磁盘上的 `manifest.json` 不受影响。
+- `header.min_engine_version` **不参与判断**（原版 `vanilla` 行为包是 `[1,13,0]` 且带归档）。低于 1.26.40 时只是打印一条警告：旧客户端没有归档支持，只能看到保留散文件的那部分。
+- 每个目录（递归）生成 `<包根>/__brarchive/<相对目录>.brarchive`，条目名是**裸文件名**（如 `entities.brarchive` 里是 `zombie.json`），按名称排序；文件名最多 247 字节。
+- 包根散文件（`manifest.json`、`pack_icon.png` 等）不归档；已存在的 `__brarchive/` 内容原样保留。
+- **按路径引用**的目录会把散文件留在原处，归档里只写一条 **0 字节存根**（登记文件名）——这是原版 `structures/**`、`sounds/**`、`texts` 的做法。默认列表：
+    - 行为包：`functions`、`loot_tables`、`structures`、`texts`
+    - 资源包：`font`、`materials`、`sounds`、`texts`、`textures`
+- 其余目录（`entities`、`items`、`blocks`、`recipes`、`shapes`、`spawn_rules`、`trading`、`models`、`ui`、`particles`、`render_controllers` 等）归档**完整内容并删除散文件**。
+- JSON 条目会被压缩（`{ "a": 1 }` → `{"a":1}`），非 JSON（`.lang`、二进制、`MCB`）原样存储；JSON 解析失败时也原样存储，不会损坏文件。
+
+想调整时用这些选项：
+
+| 选项 | 作用 |
+| --- | --- |
+| `keepLoose: ["blocks"]` | 额外把某些目录改成"散文件 + 存根" |
+| `keepLoose: false` | 不保留任何散文件（产物最小，全部只进归档） |
+| `exclude: ["blocks"]` | 这些目录完全不归档，只留散文件 |
+| `keepLooseFiles: true` | 归档 + 完整散文件都写（体积最大，兼容 1.26.40 之前的旧客户端） |
+| `minifyJson: false` | 不压缩 JSON 条目（排查问题用） |
+| `packOptimizationVersion: "0.2.0"` | 改用其它优化版本号 |
+
+**实机验证（1.26.40 客户端，内置 `@minecraft/server` 探针脚本）**：
+
+| 内容 | 存放方式 | 结果 |
+| --- | --- | --- |
+| `blocks/`、`items/`、`entities/`、`recipes/` | 归档完整内容、删除散文件 | ✅ `BlockTypes/ItemTypes/EntityTypes.get()` 与 `spawnEntity()` 全部通过；配方也从归档正常解析 |
+| `functions/`、`loot_tables/` | 散文件 + 归档存根 | ✅ `/function`、`/loot spawn … loot …` 均返回 success=1 |
+| `structures/` | 散文件 + 归档存根 | ⚠️ `/place structure` 在本机返回 success=0（原版对照名称带 `/` 需要加引号，未能取得正向对照），建议自行用结构方块验证 |
+| `texts/` | 散文件 + 归档存根 | ✅ 散文件 `.lang` 正常（中文客户端需自带 `zh_CN.lang`，否则显示 key） |
+
+> **`scripts/` 默认也会归档**（官方 `behavior_packs/editor` 就是这样，且实测脚本模块可从归档加载）；上面的探针为了确保一定输出，用的是 `keepLoose: ["scripts"]`。如果你的脚本在归档后不执行，加 `keepLoose: ["scripts"]` 即可。
+>
+> **注意模块 UUID 不能重复**：手写 `manifest.json` 里的 `data`/`resources` 模块 UUID 必须和 `packs.bp.moduleUuid`（脚本模块）不同，否则引擎会丢掉脚本模块且没有明显报错。
+
+> **兼容性**：能读 `__brarchive/` 的客户端才有完整内容；1.26.40 之前的客户端只能看到"保留散文件"的目录。设 `allowUnsupportedTarget: true` 可关闭 min_engine_version 警告。
+>
+> 同一套选项也适用于复制：见《复制》一节的[复制时也做 Pack 优化](#复制时也做-pack-优化)。
+
 ## 钩子
 
 支持的钩子：
@@ -958,7 +1167,6 @@ UNSUPPORTED_DEPENDENCY
 DEPENDENCY_VERSION_INVALID
 DEPENDENCY_REQUIRES_INSTALL
 SAPI_VERSION_NOT_FOUND
-ACHIEVEMENT_REQUIRES_STABLE_API
 TYPECHECK_FAILED
 BUILD_FAILED
 COPY_TARGET_NOT_FOUND