@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.41

package/src/build/build-adapter.d.ts

@@ -9,289 +9,17 @@
  *   {@link ViteHostBuildAdapter} (a host-owned boundary marker that throws
  *   on direct use, for host runtimes that own their own build pipeline).
  * - `BuildExecutor` — the runtime-facing facade stored on
- *   `appConfig.runtime.buildExecutor`. It is intentionally narrower than
- *   `BuildAdapter` so callers that only need to issue builds do not depend
- *   on `resolve` / `getTranspileOptions`.
- * - App-owned helpers (`getAppBuildAdapter`, `getAppBuildExecutor`, and
- *   the `set*` counterparts) — the supported way for runtime code to read
- *   and mutate the active adapter per `EcoPagesAppConfig`.
- */
-import type { EcoBuildPlugin } from './build-types.js';
-import { type AppBuildManifest } from './build-manifest.js';
+ *   `appConfig.runtime.buildRuntime` via profile-based accessors.
+ * - App-owned helpers (`getAppBuildAdapter` and the `set*` counterparts) —
+ *   the supported way for runtime code to read and mutate the active adapter
+ *   per `EcoPagesAppConfig`. Profile executors live on
+ *   `appConfig.runtime.buildRuntime`.
+ */
+import type { EcoBuildPlugin } from './contracts/build-types.js';
+import { type BuildAdapter, type BuildExecutor, type BuildOptions, type BuildOwnership, type BuildResult, type BuildTranspileOptions, type BuildTranspileProfile } from './contracts/build-contracts.js';
+export type { BuildAdapter, BuildDependencyGraph, BuildExecutor, BuildLog, BuildOptions, BuildOutput, BuildOwnership, BuildResult, BuildTranspileOptions, BuildTranspileProfile, } from './contracts/build-contracts.js';
+import { type AppBuildManifest } from './contracts/build-manifest.js';
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
-import type { IHmrManager } from '../types/public-types.js';
-/**
- * Which backend owns the app's build pipeline.
- *
- * - `'rolldown'`: the default. Ecopages runs the build directly through
- *   its bundler-backed adapter.
- * - `'rolldown-dev'`: uses Rolldown's DevEngine for cached incremental
- *   rebuilds. Ideal for HMR and watch mode where the same entrypoints
- *   are rebuilt repeatedly.
- * - `'vite-host'`: a host runtime owns the build. {@link ViteHostBuildAdapter}
- *   is exposed as a boundary marker; any direct call into it throws.
- */
-export type BuildOwnership = 'vite-host' | 'rolldown' | 'rolldown-dev';
-/**
- * A single message emitted by the build backend.
- *
- * @remarks
- * Today this only carries `message`. Severity and structured fields
- * belong in a future schema bump; the current shape mirrors the
- * bundler's log output 1:1.
- */
-export interface BuildLog {
-    message: string;
-}
-/**
- * A single artifact emitted by the build backend.
- *
- * @remarks
- * `path` is the absolute on-disk path of the emitted file. For
- * filename templates that include a content-hash token, the bundler
- * returns the concrete resolved path (not the template), so callers
- * can read the file directly.
- */
-export interface BuildOutput {
-    path: string;
-}
-/**
- * Per-entrypoint dependency metadata surfaced alongside a build.
- *
- * @remarks
- * Populated from the bundler's per-chunk module list and exposed as a
- * normalized absolute-path map. Consumers (HMR invalidation, the build
- * manifest) read this without needing to know which adapter produced
- * it. The shape is preserved across adapters so historical callers
- * continue to compile.
- */
-export interface BuildDependencyGraph {
-    /**
-     * Normalized absolute entrypoint path mapped to every normalized
-     * absolute source input that contributed to that entrypoint's
-     * output, including the entrypoint itself.
-     */
-    entrypoints: Record<string, string[]>;
-}
-/**
- * The full result of one `BuildAdapter.build` call.
- *
- * @remarks
- * `success === false` means the build failed and `outputs` will be
- * empty. Inspect `logs` for the error message; the original `Error` is
- * already normalized into `BuildLog` shape.
- */
-export interface BuildResult {
-    success: boolean;
-    logs: BuildLog[];
-    outputs: BuildOutput[];
-    /**
-     * Per-entrypoint dependency metadata, when the backend produced it.
-     * Some backends (notably the Vite-host boundary marker) leave this
-     * undefined; callers must treat that as a valid state and fall
-     * back deterministically.
-     */
-    dependencyGraph?: BuildDependencyGraph;
-}
-/**
- * Options accepted by every `BuildAdapter.build` call.
- *
- * @remarks
- * Fields that the adapter can forward are honored; fields that cannot
- * (currently `splitting`, `bundle`, and `outbase`) are accepted so
- * call-sites compile, but the adapter ignores them. See each field's
- * docstring for the current behavior.
- */
-export interface BuildOptions {
-    /**
-     * Absolute or context-root-relative source files that begin the build graph.
-     *
-     * Use a record (key → source path) when the caller needs to control chunk
-     * names. Keys become the `[name]` token in `naming`, which lets the caller
-     * embed path information that the bundler would otherwise strip.
-     */
-    entrypoints: string[] | Record<string, string>;
-    /** Output directory. Defaults to `dist/assets` when omitted. */
-    outdir?: string;
-    /**
-     * Base directory for `[dir]` placeholders in `naming`. Currently
-     * the bundled adapter derives the base from `root` directly and
-     * ignores this field.
-     */
-    outbase?: string;
-    /**
-     * Filename pattern for entrypoints. The bundled adapter honors
-     * `[name]`, `[hash]`, and `[ext]`. The `[dir]` token is stripped
-     * before forwarding to the bundler (rolldown does not implement it);
-     * callers that need directory structure preserved should use the
-     * record form of `entrypoints` so each key becomes its own chunk.
-     * When omitted, the bundler's default applies.
-     */
-    naming?: string;
-    /**
-     * Package export conditions to honor during resolution
-     * (e.g. `['import', 'browser', 'default']`).
-     */
-    conditions?: string[];
-    /**
-     * Global identifier replacements. Honored by the bundled adapter.
-     */
-    define?: Record<string, string>;
-    /** Run the bundler's minifier. Off by default. */
-    minify?: boolean;
-    /** Enable the bundler's tree-shaker. Defaults to `true`. */
-    treeshaking?: boolean;
-    /**
-     * Output target family. Accepted values: `'browser'`, `'node'`,
-     * anything else falls through to a platform-neutral setup.
-     */
-    target?: string;
-    /** Output module format. Accepted: `'esm'`, `'cjs'`, `'iife'`. */
-    format?: string;
-    /**
-     * Source map mode. Accepted: `'none'`, `'inline'`, `'external'`,
-     * `'linked'`. Anything else maps to the bundler's default (linked).
-     */
-    sourcemap?: string;
-    /**
-     * Historical code-splitting flag. Currently a no-op on the bundled
-     * adapter: the bundler splits by default and this flag is not
-     * forwarded. See the per-chunk naming convention in the adapter for
-     * the available control.
-     */
-    splitting?: boolean;
-    /** Project root used to resolve relative paths and the tsconfig lookup. */
-    root?: string;
-    /**
-     * Historical bundle flag. Currently a no-op on the bundled adapter:
-     * the bundler always bundles. Accepted so call-sites compile.
-     */
-    bundle?: boolean;
-    /**
-     * Treat `node_modules` packages as external. Honored by the bundled
-     * adapter.
-     */
-    externalPackages?: boolean;
-    /** Explicit list of module specifiers to leave as external imports. */
-    external?: string[];
-    /**
-     * JSX runtime configuration. Mirrors the bundler's `jsx` option shape.
-     */
-    jsx?: {
-        development?: boolean;
-        factory?: string;
-        fragment?: string;
-        importSource?: string;
-        runtime?: 'classic' | 'automatic';
-        sideEffects?: boolean;
-    };
-    /**
-     * Runtime-agnostic `EcoBuildPlugin[]` to attach to this build. The
-     * bundled adapter translates the array via the rolldown plugin
-     * bridge.
-     */
-    plugins?: EcoBuildPlugin[];
-    /**
-     * Escape hatch for backends that need to forward unknown options
-     * to their underlying driver. Consumers should prefer the typed
-     * fields above.
-     */
-    [key: string]: unknown;
-}
-/** Stable profile identifiers for `BuildAdapter.getTranspileOptions`. */
-export type BuildTranspileProfile = 'browser-script' | 'hmr-runtime' | 'hmr-entrypoint';
-/**
- * Resolved transpile settings for a given profile.
- *
- * @remarks
- * The three fields map 1:1 to the trio the HMR and browser-script
- * code paths look at: target platform, output format, and source-map
- * mode. Today the bundled adapter returns identical defaults for all
- * three profiles; the type is kept open so per-profile tuning can
- * land without breaking callers.
- */
-export interface BuildTranspileOptions {
-    target: string;
-    format: string;
-    sourcemap: string;
-}
-/**
- * Low-level build backend contract.
- *
- * @remarks
- * One instance is owned by each `EcoPagesAppConfig` (see
- * {@link getAppBuildAdapter}). Two implementations exist: the bundled
- * adapter does the work; {@link ViteHostBuildAdapter} is a host-owned
- * boundary marker that throws on direct use.
- */
-export interface BuildAdapter {
-    /** Which backend owns this adapter. Used for routing decisions in app helpers. */
-    readonly ownership?: BuildOwnership;
-    /**
-     * Run one build.
-     *
-     * @remarks
-     * Implementations are expected to be safe to call from any caller.
-     * Concurrent calls are not guaranteed to be serialized by the
-     * adapter itself; the dev-watch pipeline wraps the adapter in
-     * {@link SerializedBuildExecutor} when it needs FIFO ordering.
-     *
-     * Returns a `BuildResult` with `success: false` on failure; the
-     * thrown-error variant (`buildOrThrow`) is reserved for callers
-     * that need the original `Error` object.
-     */
-    build(options: BuildOptions): Promise<BuildResult>;
-    /**
-     * Resolve a module specifier against the project's `rootDir`.
-     *
-     * @remarks
-     * Used by the source-loading services when they need to know the
-     * absolute path of a specifier without performing a full build.
-     */
-    resolve(importPath: string, rootDir: string): string;
-    /**
-     * Resolve transpile settings for a known profile.
-     *
-     * @remarks
-     * Today the bundled adapter returns identical defaults for all
-     * profiles. The profile argument is kept so per-profile tuning
-     * can land without breaking callers.
-     */
-    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
-}
-/**
- * Runtime-facing facade for issuing builds.
- *
- * @remarks
- * Strictly narrower than {@link BuildAdapter}: it only exposes `build`.
- * This is the shape stored on `appConfig.runtime.buildExecutor` and
- * passed across the dev-watch and server-module-loading seams, so
- * callers cannot accidentally depend on `resolve` or
- * `getTranspileOptions`.
- *
- * In production and non-watch flows the executor is the adapter
- * itself. In development watch flows the executor is a
- * {@link SerializedBuildExecutor} wrapping the adapter so dev-watch
- * pipelines are FIFO-serialized.
- */
-export interface BuildExecutor {
-    build(options: BuildOptions): Promise<BuildResult>;
-}
-/**
- * Wraps a {@link BuildExecutor} so each call to `build` receives the
- * union of the caller's `options.plugins` and the plugins sourced
- * from `getPlugins()`.
- *
- * @remarks
- * The single point of plugin injection in the runtime path: the
- * `ConfigBuilder` stores a raw adapter on
- * `appConfig.runtime.buildAdapter` and the
- * `installAppRuntimeBuildExecutor` step wraps that adapter with this
- * helper. Callers that issue builds against
- * `appConfig.runtime.buildExecutor` get the merged plugin set without
- * further ceremony.
- */
-export declare function withBuildExecutorPlugins(executor: BuildExecutor, getPlugins: () => EcoBuildPlugin[]): BuildExecutor;
 /**
  * Boundary-marker adapter for Vite-host ownership.
  *
@@ -397,7 +125,14 @@ export declare function setAppBuildAdapter(appConfig: EcoPagesAppConfig, buildAd
  * services.
  */
 export declare function getAppBuildManifest(appConfig: EcoPagesAppConfig): AppBuildManifest;
-/** Installs the build manifest that should be visible to one app instance. */
+/** Installs the build manifest that should be visible to one app instance.
+ *
+ * @remarks
+ * Production apps are sealed via {@link updateAppBuildManifest} during
+ * {@link ConfigBuilder.build}. Call `setAppBuildManifest` directly only in tests or
+ * when replacing the entire manifest object; partial updates should use
+ * {@link updateAppBuildManifest}.
+ */
 export declare function setAppBuildManifest(appConfig: EcoPagesAppConfig, buildManifest: AppBuildManifest): void;
 /**
  * Builds a fresh app manifest from the config's loaders plus optional
@@ -413,45 +148,14 @@ export declare function createConfiguredAppBuildManifest(appConfig: EcoPagesAppC
 /**
  * Replaces the app-owned manifest using config-owned loaders and the
  * caller-supplied contribution input.
- */
-export declare function updateAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): void;
-/**
- * Collects the build-facing processor and integration contributions
- * that should be sealed into the app manifest during config
- * finalization.
  *
  * @remarks
- * Runs `prepareBuildContributions()` on every processor and
- * integration. Runtime-only side effects (HMR registration, cache
- * prewarming, runtime-origin wiring) belong to the startup path and
- * must not be triggered here; use {@link setupAppRuntimePlugins} for
- * those.
- *
- * @returns The new manifest's runtime / browser / browser-runtime-manifest
- * contribution buckets. Caller seals them into a manifest via
- * {@link updateAppBuildManifest}.
+ * Primary production entry: `ConfigBuilder.build()` passes the return value of
+ * {@link collectConfiguredAppBuildManifestContributions} here to seal
+ * `appConfig.runtime.buildManifest` before startup.
  */
-export declare function collectConfiguredAppBuildManifestContributions(appConfig: EcoPagesAppConfig): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins' | 'browserRuntimeManifest'>>;
-/**
- * Runs runtime-only processor and integration setup against an already
- * sealed app manifest.
- *
- * @remarks
- * Startup paths call this after `ConfigBuilder.build` has finalized
- * the manifest. The manifest is reused as-is; this helper only performs
- * the runtime side effects that need live startup context (cache
- * prewarming, runtime-origin wiring, HMR manager attachment).
- *
- * Loaders, processors, and integrations are visited in that order;
- * each one's plugins are forwarded to the optional `onRuntimePlugin`
- * callback so callers can attach to every plugin discovered.
- */
-export declare function setupAppRuntimePlugins(options: {
-    appConfig: EcoPagesAppConfig;
-    runtimeOrigin: string;
-    hmrManager?: IHmrManager;
-    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
-}): Promise<void>;
+export declare function updateAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): void;
+export { collectConfiguredAppBuildManifestContributions, ensureIntegrationRuntimeReady, setupAppRuntimePlugins, } from './app-build-manifest-runtime.js';
 /**
  * Returns the server-bundle plugin list for one app/runtime instance.
  *
@@ -468,28 +172,19 @@ export declare function getAppServerBuildPlugins(appConfig: EcoPagesAppConfig):
  * Reads from the app's sealed build manifest. The browser-bundle
  * manifest is the source of truth for which plugins participate in the
  * browser bundle.
- */
-export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
-/**
- * Returns the executor owned by an app/runtime instance.
  *
- * @remarks
- * Falls back to {@link getAppBuildAdapter} when no executor is set
- * on the runtime yet. The dev-watch pipeline replaces this value with
- * a {@link SerializedBuildExecutor} via
- * {@link installAppRuntimeBuildExecutor}.
+ * Plugins whose `name` matches a registered {@link EcoSourceTransform} are
+ * excluded here because browser builds run those transforms via the Rolldown
+ * bridge post-load pass instead of as competing `onLoad` handlers.
  */
-export declare function getAppBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
-/** Installs the executor that should serve future builds for one app instance. */
-export declare function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void;
+export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
 /**
  * Runs a build through the active pipeline.
  *
  * @remarks
  * `executor` defaults to the default-bundler adapter for non-app-aware
- * callsites. App-aware code should pass
- * `getAppBuildExecutor(appConfig)` (or read it directly) to honor the
- * per-app pipeline.
+ * callsites. App-aware code should pass a profile executor from
+ * {@link requireBuildRuntime} to honor the per-app pipeline.
  */
 export declare function build(options: BuildOptions, executor?: BuildExecutor): Promise<BuildResult>;
 /**