@ecopages/core 0.2.0-alpha.9 → 0.2.1

package/src/adapters/shared/server-route-handler.js

@@ -1,6 +1,6 @@
-import { appLogger } from "../../global/app-logger";
-import { HttpError } from "../../errors/http-error";
-import { injectHmrRuntimeIntoHtmlResponse, isHtmlResponse, shouldInjectHmrHtmlResponse } from "./hmr-html-response";
+import { appLogger } from "../../global/app-logger.js";
+import { HttpError } from "../../errors/http-error.js";
+import { injectHmrRuntimeIntoHtmlResponse, isHtmlResponse, shouldInjectHmrHtmlResponse } from "./hmr-html-response.js";
 class ServerRouteHandler {
   router;
   fileSystemResponseMatcher;

package/src/adapters/shared/server-static-builder.d.ts

@@ -1,8 +1,8 @@
-import type { EcoPagesAppConfig } from '../../internal-types';
-import type { ApiHandler, StaticRoute } from '../../public-types';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer';
-import type { FSRouter } from '../../router/server/fs-router';
-import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ApiHandler, StaticRoute } from '../../types/public-types.js';
+import type { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+import type { FSRouter } from '../../router/server/fs-router.js';
+import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.js';
 export interface StaticBuildOptions {
     preview?: boolean;
 }

package/src/adapters/shared/server-static-builder.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
-import { StaticContentServer } from "../../dev/sc-server";
-import { appLogger } from "../../global/app-logger";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+import { StaticContentServer } from "../../dev/sc-server.js";
+import { appLogger } from "../../global/app-logger.js";
 class ServerStaticBuilder {
   appConfig;
   staticSiteGenerator;
@@ -68,7 +69,7 @@ class ServerStaticBuilder {
    */
   async build(options, dependencies) {
     const { preview = false } = options ?? {};
-    const baseUrl = `http://${this.serveOptions.hostname || "localhost"}:${this.serveOptions.port || 3e3}`;
+    const baseUrl = `http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
     this.warnApiHandlersUnavailableInStaticMode();
     this.prepareExportDirectory();
     await this.refreshRuntimeAssets();
@@ -82,7 +83,7 @@ class ServerStaticBuilder {
       this.logger.info("Build completed");
       return;
     }
-    const previewPort = this.serveOptions.port || 3e3;
+    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
     const { server } = this.previewServerFactory.createServer({
       appConfig: this.appConfig,
       options: { port: Number(previewPort) }

package/src/build/README.md

@@ -1,13 +1,13 @@
 # Build Layer
 
-This directory contains the runtime-neutral build contract used across Ecopages and the esbuild-backed implementation that currently powers the default fallback adapter.
+This directory contains the runtime-neutral build contract used across Ecopages, the Bun-native adapter that currently uses esbuild under the hood, and the explicit host-owned Vite compatibility boundary.
 
 ## Files
 
-- `build-adapter.ts`: shared build interfaces, result types, app-owned adapter/executor helpers, the exported `defaultBuildAdapter` fallback, and the top-level `build()` / `getTranspileOptions()` pipeline functions.
+- `build-adapter.ts`: shared build interfaces, explicit Bun-native versus Vite-host ownership helpers, app-owned adapter/executor helpers, and compatibility fallback helpers for older Bun-native call paths.
 - `build-types.ts`: plugin bridge types used by integrations and processors.
-- `esbuild-build-adapter.ts`: the concrete esbuild backend.
-- `dev-build-coordinator.ts`: development-only orchestration around the shared esbuild backend.
+- `esbuild-build-adapter.ts`: the concrete Bun-native adapter implementation. It is compatibility infrastructure, not strategic architecture.
+- `dev-build-coordinator.ts`: development-only orchestration around the temporary Bun-native esbuild backend.
 - `*.test.ts`: focused regression coverage for plain builds and development serialization and recovery.
 
 ## Responsibilities
@@ -18,10 +18,10 @@ The build layer is intentionally split into two parts.
 
 - It is the narrow facade stored on `appConfig.runtime.buildExecutor`.
 - It answers only how a given app instance should execute builds right now.
-- `EsbuildBuildAdapter` satisfies this contract directly in plain flows.
-- `DevBuildCoordinator` also satisfies this contract by wrapping the shared esbuild adapter with development-only serialization and recovery policy.
+- the Bun-native adapter satisfies this contract directly in plain flows.
+- `DevBuildCoordinator` also satisfies this contract by wrapping the temporary Bun-native esbuild adapter with development-only serialization and recovery policy.
 
-`EsbuildBuildAdapter` is the backend. It knows how to:
+`EsbuildBuildAdapter` is the current Bun-native backend. It knows how to:
 
 - load the esbuild module
 - translate Ecopages `BuildOptions` into esbuild options
@@ -29,6 +29,8 @@ The build layer is intentionally split into two parts.
 - normalize build output, logs, and dependency graph metadata
 - detect the subset of runtime faults that mean the esbuild worker protocol is corrupted
 
+`ViteHostBuildAdapter` is a boundary marker, not a real backend. It exists so app/runtime state can represent that Vite owns host-side build execution instead of silently falling back to a framework-owned esbuild path.
+
 `DevBuildCoordinator` is the development policy layer. It exists because one app/runtime can have many build callers during dev mode, including:
 
 - page module imports
@@ -36,7 +38,7 @@ The build layer is intentionally split into two parts.
 - script and asset processors
 - React integration build paths
 
-Those callers must not race each other against one long-lived esbuild worker. The coordinator therefore owns:
+Those callers must not race each other against one long-lived esbuild worker. The coordinator therefore owns temporary compatibility policy for the Bun-native path:
 
 - serialized access to the shared adapter in development
 - recycling warm Node-target esbuild sessions between builds
@@ -44,9 +46,13 @@ Those callers must not race each other against one long-lived esbuild worker. Th
 
 ## Default Flow
 
-Each `EcoPagesAppConfig` owns a build adapter, build manifest, and `buildExecutor` in `appConfig.runtime`. `ConfigBuilder.build()` now creates that app-owned build state up front so later runtime startup can reuse it rather than mutating a shared adapter.
+Each `EcoPagesAppConfig` owns explicit build ownership, a build adapter, a build manifest, and a `buildExecutor` in `appConfig.runtime`. `ConfigBuilder.build()` now creates that app-owned build state up front so later runtime startup can reuse it rather than mutating a shared adapter.
+
+When a Bun server adapter starts in watch mode, it replaces that executor with a per-app `DevBuildCoordinator`. Vite-hosted flows should not use that coordinator; the host owns watch, graph, and HMR policy there. Build consumers then either call the executor directly or pass it explicitly to the top-level `build()` helper.
+
+The exported `defaultBuildAdapter` and top-level `getTranspileOptions()` helper are compatibility fallbacks only. New runtime code should prefer app-owned access through `getAppBuildAdapter()`, `getAppBuildExecutor()`, and `getAppTranspileOptions()`.
 
-When a Node or Bun server adapter starts in watch mode, it replaces that executor with a per-app `DevBuildCoordinator`. Build consumers then either call the executor directly or pass it explicitly to the top-level `build()` helper.
+The same rule applies to source-module loading: host-owned import behavior must be injected through abstract runtime state rather than imported directly into core services.
 
 Plugins are part of app-owned manifest or per-build input now. The source build contract no longer exposes adapter-level plugin registration, which keeps build composition scoped to an app/runtime instance instead of leaking across instances.
 
@@ -82,14 +88,14 @@ After that reset, the coordinator retries the failed build once.
 
 ## Why Explicit App Ownership
 
-There are many build callsites across core and integrations. The coordinator still needs to stay centralized, but process-global installation hid the real dependency and tied behavior to startup order.
+There are many build callsites across core and integrations. The coordinator still needs to stay centralized for the remaining Bun-native compatibility path, but process-global installation hid the real dependency and tied behavior to startup order.
 
 The explicit app-owned executor model keeps the design honest:
 
 - each app/runtime owns its own build executor
-- development policy stays in one place (`DevBuildCoordinator`)
+- development policy stays in one place (`DevBuildCoordinator`) for the remaining Bun-native path only
 - callers with app context use that executor explicitly instead of consulting global state
-- tests can still instantiate `EsbuildBuildAdapter` or `DevBuildCoordinator` directly when they want the raw backend only
+- tests can still instantiate `EsbuildBuildAdapter`, `ViteHostBuildAdapter`, or `DevBuildCoordinator` directly when they want the raw ownership boundary or compatibility backend only
 
 ## Testing Strategy
 

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

@@ -1,8 +1,9 @@
 import type { EcoBuildPlugin } from './build-types.js';
 import { type AppBuildManifest } from './build-manifest.js';
-import type { EcoPagesAppConfig } from '../internal-types.js';
-import type { IHmrManager } from '../public-types.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { IHmrManager } from '../types/public-types.js';
 export { EsbuildBuildAdapter } from './esbuild-build-adapter.js';
+export type BuildOwnership = 'bun-native' | 'vite-host';
 export interface BuildLog {
     message: string;
 }
@@ -63,12 +64,14 @@ export interface BuildTranspileOptions {
     sourcemap: string;
 }
 export interface BuildAdapter {
+    readonly ownership?: BuildOwnership;
     /**
      * Executes one concrete backend build.
      *
      * @remarks
-     * `BuildAdapter` is the low-level backend contract. The default adapter is
-     * `EsbuildBuildAdapter`, but alternate adapters may satisfy the same shape.
+     * `BuildAdapter` is the low-level backend contract. Bun-native execution owns
+     * one adapter directly; Vite-hosted execution is represented as an explicit
+     * host-owned compatibility path rather than an implicit esbuild default.
      */
     build(options: BuildOptions): Promise<BuildResult>;
     resolve(importPath: string, rootDir: string): string;
@@ -81,31 +84,69 @@ export interface BuildAdapter {
  * This is intentionally narrower than `BuildAdapter`. A build executor answers
  * only the question "how should this app execute a build right now?".
  *
- * In production and non-watch flows the executor is usually the adapter itself,
- * which today means `EsbuildBuildAdapter`. In development watch flows the
- * executor is typically `DevBuildCoordinator`, which wraps the shared esbuild
- * adapter to serialize callers and recover from known worker faults.
+ * In Bun-native production and non-watch flows the executor is usually the
+ * adapter itself. In development watch flows the executor may be a
+ * compatibility coordinator around the Bun-native adapter while the Vite host
+ * path continues migrating toward host-owned execution.
  */
 export interface BuildExecutor {
     build(options: BuildOptions): Promise<BuildResult>;
 }
-export declare function createBuildAdapter(): BuildAdapter;
-/**
- * @deprecated Use EsbuildBuildAdapter instead. Bun native build is missing some dependency graph features.
- */
 export declare class BunBuildAdapter implements BuildAdapter {
+    readonly ownership: "bun-native";
+    private readonly fallbackAdapter;
+    private getPluginsForBuild;
+    private escapeRegExp;
+    private resolvePluginPath;
+    private inferLoaderFromPath;
+    private normalizeBunLoader;
+    private convertLoadResultToModuleSource;
+    private convertPluginOnLoadResult;
+    private createEcoPluginBridge;
+    private toBuildLogs;
+    private mapBunTarget;
+    private mapBunFormat;
+    private getOutputExtension;
+    private resolveConcreteOutputPath;
+    private resolveTemplatedOutputPath;
+    private relocateOutputFile;
+    private normalizeBunOutputs;
+    private rewriteAliasedRuntimeSpecifiers;
     build(options: BuildOptions): Promise<BuildResult>;
     resolve(importPath: string, rootDir: string): string;
     getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
 }
+export declare class ViteHostBuildAdapter implements BuildAdapter {
+    readonly ownership: "vite-host";
+    build(_options: BuildOptions): Promise<BuildResult>;
+    resolve(_importPath: string, _rootDir: string): string;
+    getTranspileOptions(_profile: BuildTranspileProfile): BuildTranspileOptions;
+}
+export declare function createBunBuildAdapter(): BuildAdapter;
+export declare function createViteHostBuildAdapter(): BuildAdapter;
+export declare function createBuildAdapter(options?: {
+    ownership?: BuildOwnership;
+}): BuildAdapter;
+export declare const defaultBunBuildAdapter: BuildAdapter;
+export declare const defaultViteHostBuildAdapter: BuildAdapter;
+/**
+ * Bun-native fallback export for callsites that still resolve build state
+ * globally.
+ *
+ * New app-aware code should prefer `getAppBuildAdapter()`.
+ */
 export declare const defaultBuildAdapter: BuildAdapter;
+export declare function getDefaultBuildAdapter(ownership?: BuildOwnership): BuildAdapter;
+export declare function getBuildAdapterOwnership(buildAdapter: BuildAdapter | undefined): BuildOwnership;
+export declare function getAppBuildOwnership(appConfig: EcoPagesAppConfig): BuildOwnership;
+export declare function setAppBuildOwnership(appConfig: EcoPagesAppConfig, buildOwnership: BuildOwnership): void;
 /**
  * Returns the adapter owned by an app/runtime instance.
  *
  * @remarks
- * The config builder installs a dedicated adapter per app. The shared default
- * adapter remains only as a compatibility fallback for older tests and helpers
- * that do not yet thread app runtime state explicitly.
+ * The config builder installs an explicit adapter per app. The Bun-native
+ * fallback remains only as compatibility scaffolding for helpers that do not
+ * yet thread app runtime state explicitly.
  */
 export declare function getAppBuildAdapter(appConfig: EcoPagesAppConfig): BuildAdapter;
 /**
@@ -165,9 +206,9 @@ export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig):
  * Returns the executor owned by an app/runtime instance.
  *
  * @remarks
- * The config builder seeds this with the shared default adapter. Runtime
- * adapters may replace it with a coordinator that still delegates to the same
- * backend while adding development policy.
+ * The config builder seeds this with the app-owned adapter. Runtime adapters
+ * may replace it with a compatibility coordinator while keeping ownership tied
+ * to the same Bun-native backend.
  */
 export declare function getAppBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
 /**
@@ -179,8 +220,14 @@ export declare function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildE
  *
  * @remarks
  * Callers can pass an explicit executor when builds should be routed through an
- * app-owned development coordinator. Without one, the shared default adapter is
- * used directly.
+ * app-owned development coordinator. Without one, the Bun-native default
+ * adapter is used directly.
  */
 export declare function build(options: BuildOptions, executor?: BuildExecutor): Promise<BuildResult>;
+/**
+ * Bun-native fallback helper for callsites without app runtime context.
+ *
+ * New app-aware code should prefer `getAppTranspileOptions()`.
+ */
 export declare function getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+export declare function getAppTranspileOptions(appConfig: EcoPagesAppConfig, profile: BuildTranspileProfile): BuildTranspileOptions;