fix(egg-bundler): copy app runtime assets (#5931)

## Summary
- Copy non-source runtime assets under app into the bundle output with
the same baseDir-relative paths.
- Preserve source-module exclusion while copying static asset
directories such as app/public verbatim.
- Cover app/port/*.html assets and document bundle/non-bundle readFile
behavior.

## Tests
- pnpm --filter @eggjs/egg-bundler test -- integration.test.ts
- pnpm --filter @eggjs/egg-bundler typecheck
- pnpm --filter @eggjs/egg-bundler lint
- pnpm exec oxfmt --check tools/egg-bundler/src/lib/Bundler.ts
tools/egg-bundler/test/integration.test.ts
tools/egg-bundler/docs/output-structure.md
- git diff --check

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Runtime assets are copied into the bundle output and listed in the
final manifest; a new runtimeAssets config (with roots and
forceCopyDirs) controls which app files are preserved.

* **Documentation**
* README and docs updated with a "Runtime assets" section, examples, and
option descriptions for runtimeAssets.roots and
runtimeAssets.forceCopyDirs.

* **Tests**
* Added integration and validation tests for asset copying, manifest
inclusion, content preservation, and invalid runtimeAssets config
errors.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: killagu

tools/egg-bundler/README.md

@@ -33,6 +33,17 @@ Applications can also provide stable bundle configuration in
 
 ```yaml
 bundle:
+  runtimeAssets:
+    # Optional. When omitted, defaults to app.
+    # When present, this list replaces the default runtime asset scan roots.
+    roots:
+      - app
+    # Optional. When omitted, defaults to app/public, app/assets, and app/static.
+    # When present, this list replaces the default force-copy directories.
+    forceCopyDirs:
+      - app/public
+      - app/assets
+      - app/static
   pack:
     resolve:
       alias:
@@ -42,7 +53,11 @@ bundle:
 Dot-relative alias targets are resolved from `baseDir`; package-style and
 absolute targets are passed through. Aliases supplied directly through the
 programmatic `pack.resolve.alias` option override aliases with the same key from
-`module.yml`.
+`module.yml`. `runtimeAssets.forceCopyDirs` entries are bundle-output relative
+paths that are copied even when their files use source-like extensions such as
+`.js` or `.ts`. `runtimeAssets.roots` entries are baseDir-relative directories
+that are scanned for runtime assets and preserve that same relative path in the
+bundle output.
 
 If the startup manifest is missing, the bundler generates it by starting the app
 with `metadataOnly: true`. In that mode Egg skips the agent and normal boot
@@ -52,19 +67,21 @@ not run.
 
 ## 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 package specifier. Defaults to `egg`; absolute paths are unsupported. |
-| `mode`               | Build mode, `production` or `development`. Defaults to `production`.            |
-| `tegg`               | Accepted by `BundlerConfig`, but not applied by the current implementation yet. |
-| `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`.                      |
-| `pack.resolve.alias` | Application-supplied `@utoo/pack` resolve aliases; overrides `module.yml`.      |
+| 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 package specifier. Defaults to `egg`; absolute paths are unsupported. |
+| `mode`                        | Build mode, `production` or `development`. Defaults to `production`.            |
+| `tegg`                        | Accepted by `BundlerConfig`, but not applied by the current implementation yet. |
+| `externals.force`             | Package names to always keep external.                                          |
+| `externals.inline`            | Package names to force inline even if auto-detected as external.                |
+| `runtimeAssets.roots`         | BaseDir-relative runtime asset scan roots; overrides `module.yml`.              |
+| `runtimeAssets.forceCopyDirs` | Relative dirs copied even for source-like files; overrides `module.yml`.        |
+| `pack.buildFunc`              | Test hook for replacing the real `@utoo/pack` build entry.                      |
+| `pack.rootPath`               | Override the monorepo workspace root used by `@utoo/pack`.                      |
+| `pack.resolve.alias`          | Application-supplied `@utoo/pack` resolve aliases; overrides `module.yml`.      |
 
 ## Result
 

tools/egg-bundler/docs/output-structure.md

@@ -14,6 +14,8 @@ the chunks.
 ├── _root-of-the-server___<hash>.js.map
 ├── _turbopack__runtime.js             # @utoo/pack runtime shim
 ├── _turbopack__runtime.js.map
+├── app/port/binary.html               # app runtime asset copied from <baseDir>/app/port/binary.html
+├── app/port/login.html                # app runtime asset copied from <baseDir>/app/port/login.html
 ├── tsconfig.json                      # written by PackRunner; SWC reads decorator options from here
 ├── package.json                       # written by PackRunner; `{ "type": "commonjs" }` so node parses *.js as CJS
 └── bundle-manifest.json               # written by Bundler; reference / debug metadata
@@ -40,6 +42,36 @@ is keyed by relKey, output-dir absolute paths, precomputed original app absolute
 paths, and manifest `resolveCache` request aliases. Application code and plugins
 may still use `fs` for resources such as config, views, or assets.
 
+## Runtime assets
+
+The bundler copies application runtime assets from `<baseDir>/app` by default
+into the same relative path under `outputDir`, excluding manifest-known module
+files and source-like files such as `.js`, `.ts`, `.mjs`, and `.cjs` outside
+static asset directories. For example, `<baseDir>/app/port/binary.html` is
+emitted as `<outputDir>/app/port/binary.html`. Since bundled workers start Egg with
+`baseDir: outputDir`, existing reads such as
+`fs.readFile(path.join(app.config.baseDir, 'app/port/binary.html'))` resolve to
+the copied file in bundle mode and continue to resolve to the original file in
+non-bundle mode. Static asset directories such as `app/public`, `app/assets`,
+and `app/static` are copied verbatim so frontend `.js` and `.css` files remain
+servable from the bundled app. Applications may replace those force-copy
+directories with `bundle.runtimeAssets.forceCopyDirs` in `module.yml`, for
+example:
+
+```yaml
+bundle:
+  runtimeAssets:
+    roots:
+      - app
+    forceCopyDirs:
+      - app/port
+      - app/public
+```
+
+Applications may also replace the scanned roots with
+`bundle.runtimeAssets.roots`. Root entries are baseDir-relative directories, and
+the output keeps the same baseDir-relative path.
+
 ## `bundle-manifest.json`
 
 A reference file produced by `Bundler` (not consumed at runtime). Shape:

tools/egg-bundler/src/index.ts

@@ -30,6 +30,13 @@ export interface BundlerPackConfig {
   readonly resolve?: PackRunnerResolveConfig;
 }
 
+export interface BundlerRuntimeAssetsConfig {
+  /** BaseDir-relative directories scanned for runtime assets. Defaults to `['app']`. */
+  readonly roots?: readonly string[];
+  /** Relative directories whose files should be copied even when they use source-like extensions. */
+  readonly forceCopyDirs?: readonly string[];
+}
+
 export interface BundlerConfig {
   /** Application root directory. Required. */
   readonly baseDir: string;
@@ -45,6 +52,8 @@ export interface BundlerConfig {
   readonly externals?: BundlerExternalsConfig;
   /** @utoo/pack tuning. */
   readonly pack?: BundlerPackConfig;
+  /** Runtime asset copy tuning. */
+  readonly runtimeAssets?: BundlerRuntimeAssetsConfig;
   /** Enable tegg decoratedFile collection. Defaults to `true`. */
   readonly tegg?: boolean;
 }