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

package/README.md

@@ -25,7 +25,9 @@ BePack is a build tool for Minecraft Bedrock add-ons. It keeps behavior-pack and
 - Create a BePack configuration from scratch or import it from existing manifests.
 - Keep `manifest.json` in sync without overwriting fields that BePack does not own.
 - Build a Behavior Pack's TypeScript Script API entry into its `scripts/` directory.
+- Type-check that source with `tsc --noEmit` before bundling — **on by default**.
 - Inject build-time feature flags with `compile.define` (identifier-level, typecheck-safe) or `replace` tokens.
+- Customize the Rolldown build with inline options, a function, or your own `rolldown.config.ts`.
 - Resolve supported `@minecraft/*` dependencies and write their concrete versions to your project.
 - Keep `manifest.json` in sync with a `preserve` (incremental) or `clean` (config-generated) merge strategy.
 - Copy packs into a Minecraft development folder and create release archives.
@@ -76,7 +78,9 @@ bepack init --from-bp bp/manifest.json
 bepack init --from-bp bp/manifest.json --from-rp rp/manifest.json
 ```
 
-This creates `bepack.config.ts` from the pack roots, names, UUIDs, versions, manifest format, and supported Script API dependencies it finds. A BP script module is also converted into a TypeScript build configuration when possible.
+This creates `bepack.config.ts` from the pack roots, names, UUIDs, versions, manifest format, and supported Script API dependencies it finds. A BP script module becomes a TypeScript build configuration only when a matching source file (`src/<entry>.ts`, `.mts`, `.js` or `.mjs`) actually exists — a pack whose scripts already live inside it keeps compilation disabled instead of generating an entry that would fail the first build. Missing `tsconfig.json` (when a TypeScript source exists) is reported and disables type checking in the generated config.
+
+`--dry-run` prints what would be created without writing anything.
 
 Useful variations:
 
@@ -158,13 +162,15 @@ bepack build
 # Watch files and rebuild during development
 bepack dev
 
-# Create a distributable archive
+# Create a distributable archive (builds first)
 bepack pack
 
 # Build and package in one command
 bepack build --pack
 ```
 
+`bepack pack` builds first, so a bare `pack` can never ship stale `scripts/*.js` output; use `bepack pack --no-build` to zip the pack folders exactly as they are on disk.
+
 Use `bepack install` on its own when you only want to update managed dependencies and manifests. Set `target` in the config, or temporarily override it while installing and building:
 
 ```bash
@@ -172,8 +178,44 @@ bepack install --target 1.21.120
 bepack build --install --target 1.21.120
 ```
 
+> **Type checking runs by default.** Every `bepack build` and `bepack dev` executes `tsc --noEmit` before Rolldown bundles your source. A failing check stops the build with `TYPECHECK_FAILED` instead of emitting a broken pack. Skip it with `--skip-typecheck`, or set `packs.bp.compile.typecheck: false`. This is independent of any custom Rolldown options — adding them does **not** turn the type check off.
+
 `stable`, `beta`, `preview`, and exact versions can be used for the supported `@minecraft/*` dependency entries. BePack resolves selectors such as `stable` to concrete package versions before updating `package.json` and the BP manifest.
 
+The version written to `manifest.json` comes from, in order: an exact version in your config (`"@minecraft/server": "2.10.0"` — always wins), the version resolved by `bepack install` / `build --install` (online), then the version already stored in the manifest (offline `build` / `dev` / `manifest` never touch the network). Every write is logged — `manifest @minecraft/server: 2.0.0 -> 2.10.0 (specifier "stable", install)` or `... kept from manifest ... — run \`bepack install\` to refresh` — so a stale channel version is never silent again.
+
+## Customize the Rolldown build
+
+`packs.bp.compile` covers the common cases. When you need the rest of Rolldown (extra plugins, `resolve.alias`, `treeshake`, `sourcemap`, ...), pass your own options inline, through a function, or through a config file:
+
+```ts
+export default defineConfig({
+    // name, version, packs.bp.root, uuid, ... omitted
+    packs: {
+        bp: {
+            compile: {
+                entry: "src/main.ts",
+                // Object form, or a function (options, context) => options
+                rolldown: {
+                    resolve: { alias: { "@lib": "./src/lib" } },
+                    output: { sourcemap: true },
+                },
+                // Or a config file (relative to the project root):
+                // rolldownConfig: "rolldown.bp.config.ts",
+            },
+        },
+    },
+});
+```
+
+```bash
+# Temporarily replace the configured file
+bepack build --rolldown-config rolldown.staging.mjs
+bepack dev --rolldown-config rolldown.staging.mjs
+```
+
+Your options are merged on top of the ones BePack generates: `plugins` are appended, `external` is unioned, and `transform` / `resolve` / `output` / `experimental` are merged one level deep. `input` and the output location fields stay under BePack's control and are rejected with `CONFIG_INVALID` if a customization tries to move them. Custom config files may be `.ts`, `.mts`, `.js`, or `.mjs` and must export a single configuration. See [the reference guide](./reference.md) for the full merge table and the list of protected fields.
+
 ## Run in Minecraft during development
 
 Configure a copy target once, then add `--copy` to `dev` or `build`:
@@ -224,6 +266,7 @@ export default defineConfig({
 ```bash
 bepack pack
 bepack pack --name my-addon-preview
+bepack pack --no-build      # zip the pack folders as-is, without building first
 ```
 
 | Configured packs | Output     |
@@ -232,18 +275,45 @@ bepack pack --name my-addon-preview
 | RP only          | `.mcpack`  |
 | BP and RP        | `.mcaddon` |
 
+When a pack is packed selectively (always for BP, and for RP once `packs.rp.include` is set), BePack lists the top-level entries the include list leaves out and tells you to add them to `packs.bp.include` / `packs.rp.include` — files such as a `README_中文.md` next to `manifest.json` are no longer dropped silently.
+
+### Pack optimization (`__brarchive`)
+
+Bedrock 1.26.40 introduced Mojang's **pack optimizer**, which stores a pack's loose files in `__brarchive/` archives. BePack can produce the same layout:
+
+```ts
+pack: { outDir: "dist", optimize: true }
+```
+
+```bash
+bepack pack --optimize            # --no-optimize turns it back off
+bepack build --pack --optimize
+```
+
+BePack writes `header.pack_optimization_version: "0.1.0"` into the packaged manifest — that field is what makes the engine read the archives (a game version such as `"1.26.40"` is ignored). Registry folders such as `entities/`, `items/`, `blocks/`, `recipes/` and `models/` are archived in full and their loose files dropped; path-addressed folders (`functions/`, `loot_tables/`, `structures/`, `texts/`, `textures/`, `sounds/`, `font/`, `materials/`) keep their real files and get a name-only stub entry in the archive, exactly like Mojang's own packs. Verified in-game with an embedded `@minecraft/server` probe: archived blocks/items/entities/recipes register, and functions/loot tables resolve from the loose files.
+
+Your pack folder on disk is never modified, and `bepack copy` only optimizes when you ask it to.
+
+> **Compatibility:** only clients that understand `__brarchive/` (1.26.40+) see the archived content; older clients only see the folders that were kept loose. `min_engine_version` does not gate any of this, so BePack just warns when it is below 1.26.40 (`allowUnsupportedTarget: true` silences it). See the reference guide for every option.
+
+Copies to a development folder stay loose by default. Turn on `copy.optimize` (or pass `--optimize` to `copy` / `dev` / `build --copy`) to put the **optimized** shape into the dev folder, so you can catch archive-only problems in-game before shipping:
+
+```ts
+copy: { defaultTarget: "minecraft", optimize: true }
+```
+
 ## Commands at a glance
 
-| Command                   | Purpose                                                               |
-| ------------------------- | --------------------------------------------------------------------- |
-| `bepack init`             | Create a config, or import one with `--from-bp` / `--from-rp`.        |
-| `bepack install`          | Resolve managed dependencies and update `package.json` and manifests. |
-| `bepack manifest`         | Update manifests without running dependency installation.             |
-| `bepack build`            | Patch manifests and compile the configured BP source.                 |
-| `bepack dev`              | Build once, then watch and rebuild.                                   |
-| `bepack copy`             | Copy configured packs to a development target.                        |
-| `bepack pack`             | Create a `.mcpack` or `.mcaddon`.                                     |
-| `bepack config --summary` | Inspect the resolved configuration.                                   |
+| Command                   | Purpose                                                                          |
+| ------------------------- | -------------------------------------------------------------------------------- |
+| `bepack init`             | Create a config, or import one with `--from-bp` / `--from-rp`.                    |
+| `bepack install`          | Resolve managed dependencies and update `package.json` and manifests.             |
+| `bepack manifest`         | Update manifests without running dependency installation.                         |
+| `bepack build`            | Patch manifests, type-check with `tsc`, then compile the configured BP source.    |
+| `bepack dev`              | Build once, then watch and rebuild (type checking on by default).                 |
+| `bepack copy`             | Copy configured packs to a development target.                                    |
+| `bepack pack`             | Build, then create a `.mcpack` or `.mcaddon` (`--no-build` to skip).              |
+| `bepack config --summary` | Inspect the resolved configuration.                                               |
 
 All commands accept `--cwd <project-dir>` and `--config <path>` when the current directory or config filename is different. Add `--dry-run` to preview file-writing commands, or `--json` for machine-readable output. Run `bepack <command> --help` for every command option.
 

package/README.zh-CN.md

@@ -25,7 +25,9 @@ BePack 是 Minecraft 基岩版附加包的构建工具。它将行为包和资
 - 从零创建 BePack 配置，或从已有 manifest 导入配置。
 - 同步 `manifest.json`，同时保留不由 BePack 管理的字段。
 - 将行为包的 TypeScript Script API 入口构建到 `scripts/` 目录。
+- 打包前用 `tsc --noEmit` 做类型检查——**默认开启**。
 - 通过 `compile.define`（标识符级、typecheck 安全）或 `replace` 标记注入编译期 feature flag。
+- 自定义 Rolldown 构建：内联选项、函数，或独立的 `rolldown.config.ts`。
 - 解析受支持的 `@minecraft/*` 依赖，并将具体版本写入项目。
 - 以 `preserve`（增量）或 `clean`（从配置生成）策略同步 `manifest.json`。
 - 将包复制到 Minecraft 开发目录，并生成发布压缩包。
@@ -76,7 +78,9 @@ bepack init --from-bp bp/manifest.json
 bepack init --from-bp bp/manifest.json --from-rp rp/manifest.json
 ```
 
-该命令会根据读取到的包根目录、名称、UUID、版本、manifest 格式和受支持的 Script API 依赖创建 `bepack.config.ts`。如果 BP 存在脚本模块，也会在可行时生成对应的 TypeScript 构建配置。
+该命令会根据读取到的包根目录、名称、UUID、版本、manifest 格式和受支持的 Script API 依赖创建 `bepack.config.ts`。只有当确实存在匹配的源文件（`src/<入口>.ts`、`.mts`、`.js` 或 `.mjs`）时，脚本模块才会生成 TypeScript 构建配置——脚本已经在包里的项目会保持编译关闭，而不是生成一个首次构建就会失败的入口。存在 TypeScript 源码但缺少 `tsconfig.json` 时会给出提示，并在生成的配置里关闭类型检查。
+
+`--dry-run` 只打印将要创建的文件，不写盘。
 
 常用变体：
 
@@ -158,13 +162,15 @@ bepack build
 # 开发时监听文件并自动重建
 bepack dev
 
-# 生成发布压缩包
+# 生成发布压缩包（会先构建）
 bepack pack
 
 # 一次完成构建和打包
 bepack build --pack
 ```
 
+`bepack pack` 默认先构建再打包，因此单独执行 `pack` 不会再把旧的 `scripts/*.js` 打进产物；想直接压缩磁盘上的包目录时用 `bepack pack --no-build`。
+
 如果只想更新受管理的依赖和 manifest，可单独执行 `bepack install`。可以在配置中设置 `target`，也可以在安装并构建时临时指定目标 Minecraft 版本：
 
 ```bash
@@ -172,8 +178,44 @@ bepack install --target 1.21.120
 bepack build --install --target 1.21.120
 ```
 
+> **类型检查默认开启。** 每次 `bepack build` / `bepack dev` 都会先用 `tsc --noEmit` 检查源码，再交给 Rolldown 打包。检查失败会以 `TYPECHECK_FAILED` 终止构建，而不是产出一个损坏的包。可用 `--skip-typecheck` 跳过，或设置 `packs.bp.compile.typecheck: false`。这与自定义 Rolldown 选项无关——加了自定义选项**不会**关闭类型检查。
+
 受支持的 `@minecraft/*` 依赖可使用 `stable`、`beta`、`preview` 或精确版本。BePack 会先把如 `stable` 这样的选择器解析为具体包版本，再更新 `package.json` 和 BP manifest。
 
+写入 `manifest.json` 的版本按这个优先级决定：配置里的精确版本（`"@minecraft/server": "2.10.0"`，永远优先）→ `bepack install` / `build --install` 联网解析的结果 → manifest 里已有的版本（`build` / `dev` / `manifest` **不联网**，频道说明符离线时复用旧值）。每次写入都会打印来源：`manifest @minecraft/server: 2.0.0 -> 2.10.0 (specifier "stable", install)` 或 `... kept from manifest ... — run \`bepack install\` to refresh`，不会再出现"版本被悄悄写死"的情况。
+
+## 自定义 Rolldown 构建
+
+`packs.bp.compile` 覆盖了常见场景。需要 Rolldown 的其它能力时（额外插件、`resolve.alias`、`treeshake`、`sourcemap` 等），可以用内联选项、函数或配置文件传入：
+
+```ts
+export default defineConfig({
+    // 此处省略 name、version、packs.bp.root、uuid 等
+    packs: {
+        bp: {
+            compile: {
+                entry: "src/main.ts",
+                // 对象形式，或函数形式 (options, context) => options
+                rolldown: {
+                    resolve: { alias: { "@lib": "./src/lib" } },
+                    output: { sourcemap: true },
+                },
+                // 或使用配置文件（相对项目根）：
+                // rolldownConfig: "rolldown.bp.config.ts",
+            },
+        },
+    },
+});
+```
+
+```bash
+# 临时替换配置里指定的文件
+bepack build --rolldown-config rolldown.staging.mjs
+bepack dev --rolldown-config rolldown.staging.mjs
+```
+
+自定义选项会合并在 BePack 生成的选项之上：`plugins` 追加，`external` 取并集，`transform` / `resolve` / `output` / `experimental` 一层深合并。`input` 和输出位置字段始终由 BePack 管理，尝试修改会报 `CONFIG_INVALID`。自定义配置文件支持 `.ts` / `.mts` / `.js` / `.mjs`，且只能导出单个配置。完整合并规则与受保护字段见[参考文档](./reference.md)。
+
 ## 开发时复制到 Minecraft
 
 配置一次复制目标，然后在 `dev` 或 `build` 中加 `--copy`：
@@ -224,6 +266,7 @@ export default defineConfig({
 ```bash
 bepack pack
 bepack pack --name my-addon-preview
+bepack pack --no-build      # 不构建，直接压缩磁盘上的包目录
 ```
 
 | 已配置的包 | 输出       |
@@ -232,18 +275,45 @@ bepack pack --name my-addon-preview
 | 仅 RP      | `.mcpack`  |
 | BP 和 RP   | `.mcaddon` |
 
+选择性打包时（BP 始终如此，RP 在设置了 `packs.rp.include` 之后如此），BePack 会列出被 include 列表跳过的顶层条目，并提示把它们加到 `packs.bp.include` / `packs.rp.include`——像 `manifest.json` 旁边的 `README_中文.md` 不会再被无声丢弃。
+
+### Pack 优化（`__brarchive`）
+
+1.26.40 起官方提供 **pack optimizer**：把包里的散文件装进 `__brarchive/` 归档。BePack 可以在打包时生成同样的结构：
+
+```ts
+pack: { outDir: "dist", optimize: true }
+```
+
+```bash
+bepack pack --optimize            # --no-optimize 可覆盖配置里的开启状态
+bepack build --pack --optimize
+```
+
+BePack 会往产物 manifest 写入 `header.pack_optimization_version: "0.1.0"` —— **这个字段才是引擎读取归档的开关**（写游戏版本号如 `"1.26.40"` 无效）。`entities/`、`items/`、`blocks/`、`recipes/`、`models/` 这类注册表目录会完整进归档并删除散文件；而按路径引用的目录（`functions/`、`loot_tables/`、`structures/`、`texts/`、`textures/`、`sounds/`、`font/`、`materials/`）保留真实散文件，归档里只登记一条 0 字节存根 —— 与官方包的做法一致。已用内置 `@minecraft/server` 探针脚本实机验证：归档的 blocks/items/entities/recipes 全部正常注册，functions/loot_tables 从散文件正常解析。
+
+磁盘上的包目录不会被修改，`bepack copy` 也只在显式开启时才优化。
+
+> **兼容性**：只有支持 `__brarchive/` 的客户端（1.26.40+）才能看到归档内容；旧客户端只能看到保留散文件的目录。`min_engine_version` 不参与这个判断，所以低于 1.26.40 时 BePack 只打印警告（`allowUnsupportedTarget: true` 可关闭）。完整选项见参考文档。
+
+复制到开发目录默认仍是散文件形态。开启 `copy.optimize`（或给 `copy` / `dev` / `build --copy` 传 `--optimize`）可以把**优化后的形态**放进开发目录，这样打包后才可能出现的问题能在实机里提前发现：
+
+```ts
+copy: { defaultTarget: "minecraft", optimize: true }
+```
+
 ## 命令速查
 
-| 命令                      | 用途                                                  |
-| ------------------------- | ----------------------------------------------------- |
-| `bepack init`             | 创建配置，或用 `--from-bp` / `--from-rp` 导入配置。   |
-| `bepack install`          | 解析受管理的依赖，并更新 `package.json` 和 manifest。 |
-| `bepack manifest`         | 不安装依赖，仅更新 manifest。                         |
-| `bepack build`            | 修补 manifest 并编译已配置的 BP 源码。                |
-| `bepack dev`              | 先构建一次，随后监听并重建。                          |
-| `bepack copy`             | 复制已配置的包到开发目标。                            |
-| `bepack pack`             | 生成 `.mcpack` 或 `.mcaddon`。                        |
-| `bepack config --summary` | 查看解析后的配置摘要。                                |
+| 命令                      | 用途                                                          |
+| ------------------------- | ------------------------------------------------------------- |
+| `bepack init`             | 创建配置，或用 `--from-bp` / `--from-rp` 导入配置。           |
+| `bepack install`          | 解析受管理的依赖，并更新 `package.json` 和 manifest。         |
+| `bepack manifest`         | 不安装依赖，仅更新 manifest。                                 |
+| `bepack build`            | 修补 manifest，用 `tsc` 类型检查，再编译已配置的 BP 源码。    |
+| `bepack dev`              | 先构建一次，随后监听并重建（类型检查默认开启）。              |
+| `bepack copy`             | 复制已配置的包到开发目标。                                    |
+| `bepack pack`             | 先构建，再生成 `.mcpack` 或 `.mcaddon`（`--no-build` 跳过构建）。 |
+| `bepack config --summary` | 查看解析后的配置摘要。                                        |
 
 所有命令都支持 `--cwd <项目目录>` 和 `--config <路径>`，可用于在非项目目录执行或使用不同的配置文件名。对于会写入文件的命令，可添加 `--dry-run` 预览；如需机器可读输出，可添加 `--json`。使用 `bepack <命令> --help` 查看每个命令的全部参数。