@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.30

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

@@ -1,10 +1,11 @@
-import type { EcoPagesAppConfig } from '../../internal-types';
-import type { StaticRoute } from '../../public-types';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer';
-import type { FSRouter } from '../../router/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 { RouteRegistry } from '../../router/server/route-registry.js';
+import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.js';
+import type { StaticGenerationRendererResolver } from '../../route-renderer/route-renderer.js';
 export interface StaticBuildOptions {
     preview?: boolean;
+    baseUrl?: string;
 }
 export interface ServeOptions {
     hostname?: string;
@@ -14,6 +15,32 @@ export interface ServerStaticBuilderParams {
     appConfig: EcoPagesAppConfig;
     staticSiteGenerator: StaticSiteGenerator;
     serveOptions: ServeOptions;
+    apiHandlers?: ApiHandler[];
+    logger?: ServerStaticBuilderLogger;
+    previewServerFactory?: ServerStaticPreviewServerFactory;
+}
+/**
+ * Minimal logger dependency used by the static builder.
+ */
+export interface ServerStaticBuilderLogger {
+    warn(message: string, detail?: string): unknown;
+    info(message: string): unknown;
+    error(message: string): unknown;
+}
+/**
+ * Preview server factory dependency used when static preview mode is enabled.
+ */
+export interface ServerStaticPreviewServerFactory {
+    createServer(args: {
+        appConfig: EcoPagesAppConfig;
+        options: {
+            port: number;
+        };
+    }): {
+        server?: {
+            port?: number;
+        } | null;
+    };
 }
 /**
  * Handles static site generation and previews.
@@ -22,7 +49,13 @@ export declare class ServerStaticBuilder {
     private readonly appConfig;
     private readonly staticSiteGenerator;
     private readonly serveOptions;
-    constructor({ appConfig, staticSiteGenerator, serveOptions }: ServerStaticBuilderParams);
+    private readonly apiHandlers;
+    private readonly logger;
+    private readonly previewServerFactory;
+    constructor({ appConfig, staticSiteGenerator, serveOptions, apiHandlers, logger, previewServerFactory, }: ServerStaticBuilderParams);
+    private warnApiHandlersUnavailableInStaticMode;
+    private prepareExportDirectory;
+    private refreshRuntimeAssets;
     /**
      * Generates a static build of the site for deployment.
      * @param options.preview - If true, starts a preview server after build
@@ -31,8 +64,8 @@ export declare class ServerStaticBuilder {
      * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
      */
     build(options: StaticBuildOptions | undefined, dependencies: {
-        router: FSRouter;
-        routeRendererFactory: RouteRendererFactory;
+        router: RouteRegistry;
+        routeRendererFactory: StaticGenerationRendererResolver;
         staticRoutes?: StaticRoute[];
     }): Promise<void>;
 }

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

@@ -1,13 +1,64 @@
-import { StaticContentServer } from "../../dev/sc-server";
-import { appLogger } from "../../global/app-logger";
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+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;
   serveOptions;
-  constructor({ appConfig, staticSiteGenerator, serveOptions }) {
+  apiHandlers;
+  logger;
+  previewServerFactory;
+  constructor({
+    appConfig,
+    staticSiteGenerator,
+    serveOptions,
+    apiHandlers,
+    logger,
+    previewServerFactory
+  }) {
     this.appConfig = appConfig;
     this.staticSiteGenerator = staticSiteGenerator;
     this.serveOptions = serveOptions;
+    this.apiHandlers = apiHandlers ?? [];
+    this.logger = logger ?? appLogger;
+    this.previewServerFactory = previewServerFactory ?? StaticContentServer;
+  }
+  warnApiHandlersUnavailableInStaticMode() {
+    if (this.apiHandlers.length === 0) {
+      return;
+    }
+    const uniqueHandlers = Array.from(
+      new Set(this.apiHandlers.map((handler) => `${handler.method} ${handler.path}`))
+    );
+    const visibleHandlers = uniqueHandlers.slice(0, 5).join(", ");
+    const remainingCount = uniqueHandlers.length - Math.min(uniqueHandlers.length, 5);
+    const summary = remainingCount > 0 ? `${visibleHandlers}, +${remainingCount} more` : visibleHandlers;
+    this.logger.warn(
+      "Registered API endpoints are not available in static build or preview modes because no server runtime is started. They are excluded from the generated output.\n",
+      `\u27A4 ${summary}`
+    );
+  }
+  prepareExportDirectory() {
+    const exportDir = this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
+    fileSystem.ensureDir(exportDir, true);
+    const srcPublicDir = path.join(
+      this.appConfig.rootDir,
+      this.appConfig.srcDir ?? "src",
+      this.appConfig.publicDir ?? "public"
+    );
+    if (fileSystem.exists(srcPublicDir)) {
+      fileSystem.copyDir(srcPublicDir, exportDir);
+    }
+  }
+  async refreshRuntimeAssets() {
+    for (const processor of this.appConfig.processors.values()) {
+      await processor.setup();
+    }
+    for (const integration of this.appConfig.integrations) {
+      await integration.setup();
+    }
   }
   /**
    * Generates a static build of the site for deployment.
@@ -17,8 +68,11 @@ class ServerStaticBuilder {
    * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
    */
   async build(options, dependencies) {
-    const { preview = false } = options ?? {};
-    const baseUrl = `http://${this.serveOptions.hostname || "localhost"}:${this.serveOptions.port || 3e3}`;
+    const { preview = false, baseUrl: explicitBaseUrl } = options ?? {};
+    const baseUrl = explicitBaseUrl ?? `http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
+    this.warnApiHandlersUnavailableInStaticMode();
+    this.prepareExportDirectory();
+    await this.refreshRuntimeAssets();
     await this.staticSiteGenerator.run({
       router: dependencies.router,
       baseUrl,
@@ -26,18 +80,18 @@ class ServerStaticBuilder {
       staticRoutes: dependencies.staticRoutes
     });
     if (!preview) {
-      appLogger.info("Build completed");
+      this.logger.info("Build completed");
       return;
     }
-    const previewPort = this.serveOptions.port || 3e3;
-    const { server } = StaticContentServer.createServer({
+    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
+    const { server } = this.previewServerFactory.createServer({
       appConfig: this.appConfig,
       options: { port: Number(previewPort) }
     });
-    if (server) {
-      appLogger.info(`Preview running at http://localhost:${server.port}`);
+    if (server?.port) {
+      this.logger.info(`Preview running at http://localhost:${server.port}`);
     } else {
-      appLogger.error("Failed to start preview server");
+      this.logger.error("Failed to start preview server");
     }
   }
 }

package/src/build/README.md

@@ -0,0 +1,107 @@
+# Build Layer
+
+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, 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 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
+
+The build layer is intentionally split into two parts.
+
+`BuildExecutor` is the runtime-facing contract.
+
+- It is the narrow facade stored on `appConfig.runtime.buildExecutor`.
+- It answers only how a given app instance should execute builds right now.
+- 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 current Bun-native backend. It knows how to:
+
+- load the esbuild module
+- translate Ecopages `BuildOptions` into esbuild options
+- bridge Ecopages build plugins into esbuild hooks
+- 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
+- HMR entrypoint builds
+- 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 temporary compatibility policy for the Bun-native path:
+
+- serialized access to the shared adapter in development
+- recycling warm Node-target esbuild sessions between builds
+- recovery from known esbuild worker protocol faults
+
+## Default Flow
+
+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()`.
+
+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.
+
+HMR callers follow the same ownership model. Integration-specific runtime aliasing stays with the integration that owns those specifiers, rather than in generic core HMR bundling.
+
+## Orchestration Diagram
+
+```mermaid
+flowchart TD
+    Config["ConfigBuilder.build()"] --> DefaultExec["appConfig.runtime.buildExecutor = createAppBuildExecutor(app adapter, manifest)"]
+    Adapter["Server adapter initialize() in watch mode"] --> DevExec["appConfig.runtime.buildExecutor = DevBuildCoordinator"]
+    Caller["Any build caller with app/runtime context"] --> Build["executor.build(options) or build(options, executor)"]
+    Build --> Executor["BuildExecutor"]
+    Executor --> Coordinator["DevBuildCoordinator.build()"]
+    Coordinator --> Backend["EsbuildBuildAdapter.buildOrThrow()"]
+    Executor -->|plain flow| Direct["EsbuildBuildAdapter.build()"]
+    Backend --> Result["BuildResult"]
+    Direct --> Result["BuildResult"]
+    Result --> Browser["Browser consumes emitted bundle directly"]
+```
+
+## Recovery Model
+
+The recovery path is narrow on purpose. The coordinator only treats an error as recoverable when `EsbuildBuildAdapter.isEsbuildProtocolError()` matches one of the known worker-protocol failure signatures.
+
+When that happens, recovery does three things in order:
+
+1. Reset the serialized queue so future builds are not stuck behind a wedged promise.
+2. Stop the current esbuild service instance.
+3. Increment the esbuild module generation so the next import gets a fresh worker instance.
+
+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 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`) 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`, `ViteHostBuildAdapter`, or `DevBuildCoordinator` directly when they want the raw ownership boundary or compatibility backend only
+
+## Testing Strategy
+
+The build tests are split by concern.
+
+- `build-adapter.test.ts` verifies plain backend behavior and plugin bridging.
+- `build-adapter-serialization.test.ts` verifies development orchestration behavior such as serialization, warm-session recycling, and protocol-fault recovery.
+
+If you change the build orchestration rules, update the coordinator tests first. If you change esbuild option mapping or plugin behavior, update the backend tests first.

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

@@ -1,5 +1,9 @@
 import type { EcoBuildPlugin } from './build-types.js';
+import { type AppBuildManifest } from './build-manifest.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;
 }
@@ -36,7 +40,10 @@ export interface BuildResult {
 export interface BuildOptions {
     entrypoints: string[];
     outdir?: string;
+    outbase?: string;
     naming?: string;
+    conditions?: string[];
+    define?: Record<string, string>;
     minify?: boolean;
     treeshaking?: boolean;
     target?: string;
@@ -57,18 +64,176 @@ export interface BuildTranspileOptions {
     sourcemap: string;
 }
 export interface BuildAdapter {
+    readonly ownership?: BuildOwnership;
+    /**
+     * Executes one concrete backend build.
+     *
+     * @remarks
+     * `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;
-    registerPlugin(plugin: EcoBuildPlugin): void;
     getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
 }
 /**
- * @deprecated Use EsbuildBuildAdapter instead. Bun native build is missing some dependency graph features.
+ * Runtime-owned facade for issuing builds.
+ *
+ * @remarks
+ * This is intentionally narrower than `BuildAdapter`. A build executor answers
+ * only the question "how should this app execute a build right now?".
+ *
+ * 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 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 normalizePathForMatch;
+    private normalizeOutputPathForMatch;
+    private extractTemplateHashTokens;
+    private applyTemplateHashTokens;
+    private resolveTemplatedOutputPath;
+    private relocateOutputFile;
+    private hasJavaScriptExtension;
+    private findOutputMatchForEntrypoint;
+    private normalizeBunOutputs;
+    private rewriteAliasedRuntimeSpecifiers;
     build(options: BuildOptions): Promise<BuildResult>;
     resolve(importPath: string, rootDir: string): string;
-    registerPlugin(plugin: EcoBuildPlugin): void;
     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 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;
+/**
+ * Installs the adapter that should serve future builds for one app instance.
+ */
+export declare function setAppBuildAdapter(appConfig: EcoPagesAppConfig, buildAdapter: BuildAdapter): void;
+/**
+ * Returns the build manifest owned by an app/runtime instance.
+ */
+export declare function getAppBuildManifest(appConfig: EcoPagesAppConfig): AppBuildManifest;
+/**
+ * Installs the build manifest that should be visible to one app instance.
+ */
+export declare function setAppBuildManifest(appConfig: EcoPagesAppConfig, buildManifest: AppBuildManifest): void;
+/**
+ * Rebuilds an app-owned manifest from config-owned loaders plus explicit
+ * runtime/browser contribution input.
+ *
+ * @remarks
+ * This keeps loader ownership with config finalization while still letting a
+ * caller supply the non-loader plugin buckets that were discovered elsewhere.
+ */
+export declare function createConfiguredAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): AppBuildManifest;
+/**
+ * Replaces the app-owned manifest using config-owned loaders and explicit
+ * 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
+ * This runs `prepareBuildContributions()` only. Runtime-only side effects such
+ * as HMR registration, cache prewarming, and runtime-origin wiring belong to
+ * the startup path and must not be triggered here.
+ */
+export declare function collectConfiguredAppBuildManifestContributions(appConfig: EcoPagesAppConfig): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins'>>;
+/**
+ * Runs runtime-only processor and integration setup against an already sealed
+ * app manifest.
+ *
+ * @remarks
+ * Startup paths call this after config build has finalized manifest
+ * contributions. The manifest is reused as-is; this helper only performs the
+ * runtime side effects that still need live startup context.
+ */
+export declare function setupAppRuntimePlugins(options: {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    hmrManager?: IHmrManager;
+    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
+}): Promise<void>;
+export declare function getAppServerBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+/**
+ * Returns the executor owned by an app/runtime instance.
+ *
+ * @remarks
+ * 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;
+/**
+ * Installs the executor that should serve future builds for one app instance.
+ */
+export declare function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void;
+/**
+ * Runs a build through the active pipeline.
+ *
+ * @remarks
+ * Callers can pass an explicit executor when builds should be routed through an
+ * 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;