docs: document egg bundler tooling

tools/egg-bin/README.md

@@ -36,6 +36,7 @@ Add `egg-bin` to `package.json` scripts:
     "test-local": "egg-bin test",
     "test": "npm run lint -- --fix && npm run test-local",
     "cov": "egg-bin cov",
+    "bundle": "egg-bin bundle",
     "lint": "eslint .",
     "ci": "npm run lint && npm run cov"
   }
@@ -183,6 +184,38 @@ You can set `COV_EXCLUDES` env to add glob patterns to exclude from coverage (co
 COV_EXCLUDES="app/plugins/c*,app/autocreate/**" egg-bin cov
 ```
 
+### bundle
+
+Bundle an Egg application into a deployable artifact with `@eggjs/egg-bundler`.
+
+```bash
+egg-bin bundle
+egg-bin bundle --output ./dist-bundle
+egg-bin bundle --mode development
+egg-bin bundle --framework egg --output ./out
+```
+
+The command writes the bundle to `./dist-bundle` by default. The generated
+artifact can be started with Node from the output directory:
+
+```bash
+cd dist-bundle
+node worker.js
+```
+
+#### bundle options
+
+- `--output` / `-o` output directory, default to `./dist-bundle`
+- `--manifest` path to `manifest.json`, default to `<baseDir>/.egg/manifest.json`
+- `--framework` / `-f` framework name or absolute path
+- `--mode` build mode, `production` or `development`, default to `production`
+- `--no-tegg` disable tegg decorated file collection
+- `--force-external` package name to always keep external, supports multiple
+- `--inline-external` package name to force inline, supports multiple
+
+See [`@eggjs/egg-bundler`](../egg-bundler/README.md) for the programmatic API
+and output structure.
+
 ## Breaking Changes (v8)
 
 ### Migrated from Mocha to Vitest

tools/egg-bundler/README.md

@@ -0,0 +1,60 @@
+# @eggjs/egg-bundler
+
+Bundle an Egg application into a deployable CommonJS artifact.
+
+The bundler is used by `egg-bin bundle` and is also available as a programmatic
+API for tooling that needs to build bundles directly.
+
+## Usage
+
+```ts
+import { bundle } from '@eggjs/egg-bundler';
+
+await bundle({
+  baseDir: '/path/to/app',
+  outputDir: './dist-bundle',
+  framework: 'egg',
+  mode: 'production',
+});
+```
+
+`outputDir` is resolved from `baseDir` when it is relative. The default manifest
+path is `<baseDir>/.egg/manifest.json`.
+
+## Options
+
+| Option | Description |
+| --- | --- |
+| `baseDir` | Application root directory. Required. |
+| `outputDir` | Output directory for the bundled artifact. Required. |
+| `manifestPath` | Path to `manifest.json`. Defaults to `<baseDir>/.egg/manifest.json`. |
+| `framework` | Framework name or absolute path. Defaults to `egg`. |
+| `mode` | Build mode, `production` or `development`. Defaults to `production`. |
+| `tegg` | Enable tegg decorated file collection. Defaults to `true`. |
+| `externals.force` | Package names to always keep external. |
+| `externals.inline` | Package names to force inline even if auto-detected as external. |
+| `pack.buildFunc` | Test hook for replacing the real `@utoo/pack` build entry. |
+| `pack.rootPath` | Override the monorepo workspace root used by `@utoo/pack`. |
+
+## Result
+
+`bundle()` resolves with:
+
+| Field | Description |
+| --- | --- |
+| `outputDir` | Absolute output directory. |
+| `files` | Sorted absolute paths for files written into the artifact. |
+| `manifestPath` | Absolute path to `bundle-manifest.json`. |
+
+## Running The Bundle
+
+```bash
+cd dist-bundle
+node worker.js
+```
+
+The generated worker entry runs the app in Egg's single-process mode and serves
+framework file discovery/module resolution from the inlined bundle map.
+
+See [output-structure.md](./docs/output-structure.md) for artifact layout,
+externals behavior, and current limitations.

wiki/index.md

@@ -18,6 +18,7 @@ Read this file before exploring raw sources.
 
 ## Packages
 
+- [Egg Bundler](./packages/egg-bundler.md) - Tooling package that bundles Egg applications and backs `egg-bin bundle`.
 - [Typings Package](./packages/typings.md) - Shared TypeScript type surface for cross-package Egg typings.
 
 ## Sources

wiki/log.md

@@ -1,5 +1,11 @@
 # Wiki Log
 
+## [2026-05-02] package | document egg bundler tooling
+
+- sources touched: `tools/egg-bundler/src/index.ts`, `tools/egg-bundler/src/lib/Bundler.ts`, `tools/egg-bin/src/commands/bundle.ts`, `tools/egg-bundler/docs/output-structure.md`
+- pages updated: `wiki/index.md`, `wiki/log.md`, `wiki/packages/egg-bundler.md`
+- note: Recorded the new `@eggjs/egg-bundler` package and its `egg-bin bundle` CLI surface after the bundler stack reached `next`.
+
 ## [2026-04-21] bootstrap | seed wiki schema and starter pages
 
 - sources touched: `CLAUDE.md`

wiki/packages/egg-bundler.md

@@ -0,0 +1,47 @@
+---
+title: Egg Bundler
+type: package
+summary: Bundles Egg applications into deployable CommonJS artifacts and powers the egg-bin bundle command.
+source_files:
+  - tools/egg-bundler/src/index.ts
+  - tools/egg-bundler/src/lib/Bundler.ts
+  - tools/egg-bin/src/commands/bundle.ts
+  - tools/egg-bundler/docs/output-structure.md
+updated_at: 2026-05-02
+status: active
+---
+
+# Egg Bundler
+
+`@eggjs/egg-bundler` is a developer tooling package under `tools/egg-bundler/`.
+It exposes `bundle(config)` and the `Bundler` class for producing a deployable
+CommonJS artifact from an Egg application.
+
+## Public Surfaces
+
+- `tools/egg-bundler/src/index.ts` exports `bundle`, `Bundler`, the helper
+  classes, and the public config/result types.
+- `tools/egg-bin/src/commands/bundle.ts` wires the package into
+  `egg-bin bundle`.
+
+## Bundle Flow
+
+1. `ManifestLoader` loads the app startup manifest, defaulting to
+   `<baseDir>/.egg/manifest.json`.
+2. `ExternalsResolver` classifies packages that should stay external.
+3. `EntryGenerator` writes a synthetic worker entry that installs the bundle
+   manifest/module loader before starting Egg.
+4. `PackRunner` invokes `@utoo/pack`.
+5. `Bundler` writes `bundle-manifest.json` and returns absolute output paths.
+
+## Current Behavior
+
+- Relative `outputDir` values are resolved from `baseDir`.
+- Default mode is `production`; `development` is also accepted.
+- The generated app runs in Egg single-process mode.
+- Native addons, ESM-only packages, peer dependencies, `@eggjs/*`, and
+  explicit `externals.force` entries are external.
+
+Inference: because `egg-bin bundle` is now a public CLI surface, user-facing
+tooling docs should mention the command and its key flags whenever this package
+changes materially.