@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.9

package/src/adapters/bun/server-adapter.js

@@ -0,0 +1,373 @@
+import { appLogger } from "../../global/app-logger.js";
+import { HttpError } from "../../errors/http-error.js";
+import { createRequire } from "../../utils/locals-utils.js";
+import { fileSystem } from "@ecopages/file-system";
+import { SharedServerAdapter } from "../shared/server-adapter.js";
+import { ApiResponseBuilder } from "../shared/api-response.js";
+import { installSharedRuntimeBuildExecutor } from "../shared/runtime-bootstrap.js";
+import { ServerRouteHandler } from "../shared/server-route-handler.js";
+import { ServerStaticBuilder } from "../shared/server-static-builder";
+import {
+  injectHmrRuntimeIntoHtmlResponse,
+  isHtmlResponse,
+  shouldInjectHmrHtmlResponse
+} from "../shared/hmr-html-response";
+import { ClientBridge } from "./client-bridge";
+import { HmrManager } from "./hmr-manager";
+import { ServerLifecycle } from "./server-lifecycle.js";
+class BunServerAdapter extends SharedServerAdapter {
+  apiHandlers;
+  staticRoutes;
+  errorHandler;
+  bridge;
+  lifecycle;
+  hmrManager;
+  initializationPromise = null;
+  fullyInitialized = false;
+  lifecycleFactory;
+  staticBuilderFactory;
+  routeHandlerFactory;
+  hmrManagerFactory;
+  bridgeFactory;
+  constructor({
+    appConfig,
+    runtimeOrigin,
+    serveOptions,
+    apiHandlers,
+    staticRoutes,
+    errorHandler,
+    options,
+    lifecycle,
+    staticBuilderFactory,
+    routeHandlerFactory,
+    hmrManager,
+    bridge
+  }) {
+    super({ appConfig, runtimeOrigin, serveOptions, options });
+    this.apiHandlers = apiHandlers || [];
+    this.staticRoutes = staticRoutes || [];
+    this.errorHandler = errorHandler;
+    this.lifecycleFactory = lifecycle;
+    this.staticBuilderFactory = staticBuilderFactory;
+    this.routeHandlerFactory = routeHandlerFactory;
+    this.hmrManagerFactory = hmrManager;
+    this.bridgeFactory = bridge;
+  }
+  /**
+   * Determines if HMR script should be injected.
+   * Only injects in watch mode when HMR manager is enabled.
+   */
+  shouldInjectHmrScript() {
+    return shouldInjectHmrHtmlResponse(this.options?.watch === true, this.hmrManager);
+  }
+  /**
+   * Checks if a response contains HTML content.
+   */
+  isHtmlResponse(response) {
+    return isHtmlResponse(response);
+  }
+  /**
+   * Injects HMR script into HTML responses in development mode.
+   * Ensures explicit API handlers that return HTML get auto-reload capability.
+   */
+  async maybeInjectHmrScript(response) {
+    if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
+      return injectHmrRuntimeIntoHtmlResponse(response);
+    }
+    return response;
+  }
+  /**
+   * Initializes the server adapter's core components.
+   * Delegates to ServerLifecycle for setup.
+   */
+  async initialize() {
+    installSharedRuntimeBuildExecutor(this.appConfig, {
+      development: this.options?.watch === true
+    });
+    this.bridge = this.bridgeFactory ?? new ClientBridge();
+    this.hmrManager = this.hmrManagerFactory ?? new HmrManager({ appConfig: this.appConfig, bridge: this.bridge });
+    this.lifecycle = this.lifecycleFactory ?? new ServerLifecycle({
+      appConfig: this.appConfig,
+      runtimeOrigin: this.runtimeOrigin,
+      hmrManager: this.hmrManager,
+      bridge: this.bridge
+    });
+    this.staticSiteGenerator = await this.lifecycle.initialize();
+    const staticBuilderOptions = {
+      appConfig: this.appConfig,
+      staticSiteGenerator: this.staticSiteGenerator,
+      serveOptions: this.serveOptions,
+      apiHandlers: this.apiHandlers
+    };
+    this.staticBuilder = this.staticBuilderFactory ? this.staticBuilderFactory(staticBuilderOptions) : new ServerStaticBuilder(staticBuilderOptions);
+    await this.lifecycle.initializePlugins({ watch: this.options?.watch });
+  }
+  /**
+   * Refreshes the router routes during watch mode.
+   */
+  async refreshRouterRoutes() {
+    if (!this.serverInstance || typeof this.serverInstance.reload !== "function") {
+      appLogger.error("Server instance is not available for reloading");
+      return;
+    }
+    await this.createSharedWatchRefreshCallback({
+      staticRoutes: this.staticRoutes,
+      hmrManager: this.hmrManager,
+      onRoutesReady: () => {
+        const options = this.getServerOptions({ enableHmr: true });
+        this.serverInstance.reload(options);
+        appLogger.debug("Server routes updated with dynamic routes");
+      },
+      onError: (error) => {
+        this.hmrManager.broadcast({ type: "error", message: error.message });
+        appLogger.error("Failed to refresh router routes:", error);
+      }
+    })();
+  }
+  async watch() {
+    await this.lifecycle.startWatching({
+      refreshRouterRoutesCallback: this.refreshRouterRoutes.bind(this)
+    });
+  }
+  /**
+   * Retrieves the current server options, optionally enabling HMR.
+   * If HMR is enabled, modifies fetch to handle WebSocket upgrades and serve HMR runtime.
+   * Ensures original fetch logic is preserved and called for non-HMR requests.
+   * @param options.enableHmr Whether to enable Hot Module Replacement
+   */
+  getServerOptions({ enableHmr = false } = {}) {
+    appLogger.debug(`[BunServerAdapter] getServerOptions called with enableHmr: ${enableHmr}`);
+    const serverOptions = this.buildServerSettings();
+    if (enableHmr) {
+      const originalFetch = serverOptions.fetch;
+      const hmrHandler = this.hmrManager.getWebSocketHandler();
+      const hmrManager = this.hmrManager;
+      serverOptions.development = true;
+      serverOptions.websocket = hmrHandler;
+      serverOptions.fetch = async function(request, _server) {
+        const url = new URL(request.url);
+        appLogger.debug(`[HMR] Request: ${url.pathname}`);
+        if (url.pathname === "/_hmr") {
+          const success = this.upgrade(request, {
+            data: void 0
+          });
+          if (success) return;
+          return new Response("WebSocket upgrade failed", { status: 400 });
+        }
+        if (url.pathname === "/_hmr_runtime.js") {
+          appLogger.debug(`[HMR] Serving runtime from ${hmrManager.getRuntimePath()}`);
+          return new Response(fileSystem.readFileAsBuffer(hmrManager.getRuntimePath()), {
+            headers: { "Content-Type": "application/javascript" }
+          });
+        }
+        let response;
+        if (originalFetch) {
+          const res = await originalFetch.call(this, request, this);
+          response = res instanceof Response ? res : new Response("Not Found", { status: 404 });
+        } else {
+          response = new Response("Not Found", { status: 404 });
+        }
+        return response;
+      };
+    }
+    return serverOptions;
+  }
+  /**
+   * Helper method to retrieve and parse the request body.
+   * Handles JSON and plain text content types.
+   * For FormData (multipart/form-data, x-www-form-urlencoded), use ctx.request.formData() directly.
+   * Returns undefined for unsupported content types.
+   */
+  async retrieveBodyFromRequest(request) {
+    const contentType = request.headers.get("Content-Type") || "";
+    if (contentType.includes("application/json")) {
+      return await request.json();
+    }
+    if (contentType.includes("text/plain")) {
+      return await request.text();
+    }
+    return void 0;
+  }
+  /**
+   * Creates complete server configuration with request handling.
+   * @returns Server options ready for Bun.serve()
+   */
+  buildServerSettings() {
+    const serverOptions = { ...this.serveOptions };
+    const handleNoMatch = this.handleNoMatch.bind(this);
+    const waitForInit = this.waitForInitialization.bind(this);
+    const handleReq = this.handleRequest.bind(this);
+    const errorHandler = this.errorHandler;
+    const getCacheService = () => this.getCacheService();
+    const getRenderContext = () => this.getRenderContext();
+    appLogger.debug(`[BunServerAdapter] Building server settings`);
+    const finalOptions = {
+      ...serverOptions,
+      async fetch(request, _server) {
+        try {
+          await waitForInit();
+          return await handleReq(request);
+        } catch (error) {
+          if (error instanceof Response) return error;
+          if (errorHandler) {
+            try {
+              const locals = {};
+              const context = {
+                request,
+                params: {},
+                response: new ApiResponseBuilder(),
+                server: _server,
+                locals,
+                require: createRequire(() => locals),
+                services: {
+                  cache: getCacheService()
+                },
+                ...getRenderContext()
+              };
+              return await errorHandler(error, context);
+            } catch (handlerError) {
+              appLogger.error(`[ecopages] Error in custom error handler: ${handlerError}`);
+            }
+          }
+          if (error instanceof HttpError) return error.toResponse();
+          appLogger.error(`[ecopages] Error handling request: ${error}`);
+          return new Response("Internal Server Error", { status: 500 });
+        }
+      },
+      error(error) {
+        appLogger.error(`[ecopages] Error handling request: ${error}`);
+        return handleNoMatch(new Request("http://localhost"));
+      }
+    };
+    return finalOptions;
+  }
+  /**
+   * Generates a static build of the site for deployment.
+   * @param options.preview - If true, starts a preview server after build
+   */
+  async buildStatic(options) {
+    if (!this.fullyInitialized) {
+      await this.initializeSharedRouteHandling({
+        staticRoutes: this.staticRoutes,
+        hmrManager: this.hmrManager
+      });
+    }
+    await this.staticBuilder.build(options, {
+      router: this.router,
+      routeRendererFactory: this.routeRendererFactory,
+      staticRoutes: this.staticRoutes
+    });
+  }
+  /**
+   * Initializes the server with dynamic routes after server creation.
+   * Must be called before handling any requests.
+   * @param server - The Bun server instance
+   */
+  async completeInitialization(server) {
+    if (this.fullyInitialized) {
+      if (server && !this.serverInstance) {
+        this.serverInstance = server;
+      }
+      return;
+    }
+    if (!this.initializationPromise) {
+      this.initializationPromise = this._performInitialization(server ?? null);
+    }
+    return this.initializationPromise;
+  }
+  /**
+   * Performs complete server setup including routing, watchers, and HMR.
+   */
+  async _performInitialization(server) {
+    this.serverInstance = server;
+    appLogger.debug("Completing server initialization with dynamic routes");
+    await this.initializeSharedRouteHandling({
+      staticRoutes: this.staticRoutes,
+      hmrManager: this.hmrManager
+    });
+    this.fullyInitialized = true;
+    if (this.options?.watch) await this.watch();
+    if (server && typeof server.reload === "function") {
+      const updatedOptions = this.getServerOptions(this.options?.watch ? { enableHmr: true } : void 0);
+      server.reload(updatedOptions);
+      appLogger.debug("Server routes updated with dynamic routes");
+    }
+  }
+  /**
+   * Creates and initializes the Bun server adapter.
+   * @returns Configured adapter with server methods
+   */
+  async createAdapter() {
+    await this.initialize();
+    return {
+      getServerOptions: this.getServerOptions.bind(this),
+      buildStatic: this.buildStatic.bind(this),
+      completeInitialization: this.completeInitialization.bind(this),
+      handleRequest: this.handleRequest.bind(this)
+    };
+  }
+  /**
+   * Handles HTTP requests by passing them securely to the shared core router adapter.
+   */
+  async handleRequest(request) {
+    const response = await this.handleSharedRequest(request, {
+      apiHandlers: this.apiHandlers,
+      errorHandler: this.errorHandler,
+      serverInstance: this.serverInstance,
+      hmrManager: this.hmrManager
+    });
+    return await this.maybeInjectHmrScript(response);
+  }
+  /**
+   * Ensures server initialization completes before request handling.
+   * Prevents race conditions during startup.
+   */
+  async waitForInitialization() {
+    if (this.fullyInitialized) {
+      return;
+    }
+    if (this.initializationPromise) {
+      return this.initializationPromise;
+    }
+    throw new Error("Server not initialized. Call completeInitialization() first.");
+  }
+  /**
+   * Handles HTTP requests from the router adapter.
+   */
+  async handleResponse(request) {
+    await this.waitForInitialization();
+    return this.routeHandler.handleResponse(request);
+  }
+  /**
+   * Handles requests that do not match any routes.
+   */
+  async handleNoMatch(request) {
+    await this.waitForInitialization();
+    return this.routeHandler.handleNoMatch(request);
+  }
+}
+async function createBunServerAdapter(params) {
+  const runtimeOrigin = params.runtimeOrigin ?? `http://${params.serveOptions.hostname || "localhost"}:${params.serveOptions.port || 3e3}`;
+  const bridge = params.bridge ?? new ClientBridge();
+  const hmrManager = params.hmrManager ?? new HmrManager({ appConfig: params.appConfig, bridge });
+  const lifecycle = params.lifecycle ?? new ServerLifecycle({
+    appConfig: params.appConfig,
+    runtimeOrigin,
+    hmrManager,
+    bridge
+  });
+  const adapter = new BunServerAdapter({
+    ...params,
+    runtimeOrigin,
+    bridge,
+    hmrManager,
+    lifecycle,
+    staticBuilderFactory: params.staticBuilderFactory ?? ((opts) => new ServerStaticBuilder(opts)),
+    routeHandlerFactory: params.routeHandlerFactory ?? ((p) => new ServerRouteHandler(p))
+  });
+  return adapter.createAdapter();
+}
+export {
+  BunServerAdapter,
+  createBunServerAdapter
+};

package/src/adapters/bun/server-lifecycle.d.ts

@@ -0,0 +1,63 @@
+import type { EcoPagesAppConfig } from '../../internal-types';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import { StaticSiteGenerator } from '../../static-site-generator/static-site-generator';
+import type { ClientBridge } from './client-bridge';
+import type { HmrManager } from './hmr-manager';
+export interface WatcherCallbacks {
+    refreshRouterRoutesCallback: () => Promise<void>;
+}
+export interface ServerLifecycleParams {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    hmrManager: HmrManager;
+    bridge: ClientBridge;
+}
+/**
+ * Coordinates Bun-runtime server startup side effects for one app instance.
+ *
+ * @remarks
+ * This class keeps runtime-only concerns together: build-runtime bootstrapping,
+ * Bun loader registration, public asset preparation, plugin setup, and file
+ * watching. Core config/build state is expected to already be finalized before
+ * this lifecycle runs.
+ */
+export declare class ServerLifecycle {
+    private readonly appConfig;
+    private readonly hmrManager;
+    private readonly bridge;
+    private readonly runtimeOrigin;
+    private staticSiteGenerator;
+    constructor({ appConfig, runtimeOrigin, hmrManager, bridge }: ServerLifecycleParams);
+    /**
+     * Initializes the runtime services that Bun startup depends on.
+     *
+     * @returns The static-site generator instance reused by the adapter.
+     */
+    initialize(): Promise<StaticSiteGenerator>;
+    /**
+     * Registers config-owned build loaders with Bun's runtime plugin API.
+     *
+     * @remarks
+     * Bun remains responsible only for transport-level plugin registration here.
+     * Loader ownership and composition were already finalized during config build.
+     */
+    setupLoaders(): void;
+    /**
+     * Runs runtime-only processor and integration setup for this Bun app session.
+     *
+     * @param options.watch Whether watch mode is enabled.
+     * @returns The browser build plugins visible to HMR after runtime setup.
+     */
+    initializePlugins(options?: {
+        watch?: boolean;
+    }): Promise<EcoBuildPlugin[]>;
+    /**
+     * Starts file watching and wires change events back into the adapter refresh
+     * callback.
+     */
+    startWatching(callbacks: WatcherCallbacks): Promise<void>;
+    /**
+     * Returns the static-site generator created during initialization.
+     */
+    getStaticSiteGenerator(): StaticSiteGenerator;
+}

package/src/adapters/bun/server-lifecycle.js

@@ -0,0 +1,92 @@
+import { getBunRuntime } from "../../utils/runtime.js";
+import { appLogger } from "../../global/app-logger";
+import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator";
+import {
+  bindSharedRuntimeHmrManager,
+  initializeSharedRuntimePlugins,
+  prepareSharedRuntimePublicDir,
+  startSharedProjectWatching
+} from "../shared/runtime-bootstrap.js";
+class ServerLifecycle {
+  appConfig;
+  hmrManager;
+  bridge;
+  runtimeOrigin;
+  staticSiteGenerator;
+  constructor({ appConfig, runtimeOrigin, hmrManager, bridge }) {
+    this.appConfig = appConfig;
+    this.runtimeOrigin = runtimeOrigin;
+    this.hmrManager = hmrManager;
+    this.bridge = bridge;
+  }
+  /**
+   * Initializes the runtime services that Bun startup depends on.
+   *
+   * @returns The static-site generator instance reused by the adapter.
+   */
+  async initialize() {
+    this.staticSiteGenerator = new StaticSiteGenerator({ appConfig: this.appConfig });
+    await this.hmrManager.buildRuntime();
+    this.setupLoaders();
+    prepareSharedRuntimePublicDir(this.appConfig);
+    return this.staticSiteGenerator;
+  }
+  /**
+   * Registers config-owned build loaders with Bun's runtime plugin API.
+   *
+   * @remarks
+   * Bun remains responsible only for transport-level plugin registration here.
+   * Loader ownership and composition were already finalized during config build.
+   */
+  setupLoaders() {
+    const loaders = this.appConfig.loaders;
+    for (const loader of loaders.values()) {
+      getBunRuntime()?.plugin(loader);
+    }
+  }
+  /**
+   * Runs runtime-only processor and integration setup for this Bun app session.
+   *
+   * @param options.watch Whether watch mode is enabled.
+   * @returns The browser build plugins visible to HMR after runtime setup.
+   */
+  async initializePlugins(options) {
+    try {
+      const hmrEnabled = !!options?.watch;
+      this.hmrManager.setEnabled(hmrEnabled);
+      await initializeSharedRuntimePlugins({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin,
+        hmrManager: this.hmrManager,
+        onRuntimePlugin: (plugin) => {
+          getBunRuntime()?.plugin(plugin);
+        }
+      });
+      return bindSharedRuntimeHmrManager(this.appConfig, this.hmrManager);
+    } catch (error) {
+      appLogger.error(`Failed to initialize plugins: ${error instanceof Error ? error.message : String(error)}`);
+      throw error;
+    }
+  }
+  /**
+   * Starts file watching and wires change events back into the adapter refresh
+   * callback.
+   */
+  async startWatching(callbacks) {
+    await startSharedProjectWatching({
+      appConfig: this.appConfig,
+      refreshRouterRoutesCallback: callbacks.refreshRouterRoutesCallback,
+      hmrManager: this.hmrManager,
+      bridge: this.bridge
+    });
+  }
+  /**
+   * Returns the static-site generator created during initialization.
+   */
+  getStaticSiteGenerator() {
+    return this.staticSiteGenerator;
+  }
+}
+export {
+  ServerLifecycle
+};

package/src/adapters/index.d.ts

@@ -0,0 +1,6 @@
+export { EcopagesApp, createApp } from './bun/create-app.js';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from './shared/define-api-handler.js';
+export { NodeServerAdapter, createNodeServerAdapter } from './node/server-adapter.js';
+export { EcopagesApp as NodeAdapterEcopagesApp, createNodeApp } from './node/create-app.js';
+export type { NodeServerAdapterParams, NodeServerAdapterResult } from './node/server-adapter.js';
+export type { EcopagesAppOptions as NodeEcopagesAppOptions } from './node/create-app.js';

package/src/adapters/index.js

@@ -0,0 +1,14 @@
+import { EcopagesApp, createApp } from "./bun/create-app.js";
+import { defineApiHandler, defineGroupHandler } from "./shared/define-api-handler.js";
+import { NodeServerAdapter, createNodeServerAdapter } from "./node/server-adapter.js";
+import { EcopagesApp as EcopagesApp2, createNodeApp } from "./node/create-app.js";
+export {
+  EcopagesApp,
+  EcopagesApp2 as NodeAdapterEcopagesApp,
+  NodeServerAdapter,
+  createApp,
+  createNodeApp,
+  createNodeServerAdapter,
+  defineApiHandler,
+  defineGroupHandler
+};

package/src/adapters/node/bootstrap-dependency-resolver.d.ts

@@ -0,0 +1,44 @@
+import type { EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { NodeRuntimeManifest } from '../../services/runtime-manifest/node-runtime-manifest.service.js';
+/**
+ * Returns the runtime-local node_modules directory used by the Node thin-host
+ * bootstrap output.
+ */
+export declare function getNodeRuntimeNodeModulesDir(manifest: NodeRuntimeManifest): string;
+/**
+ * Returns the app-local node_modules directory used by framework-owned Node
+ * bootstrap loads outside the thin-host manifest path.
+ */
+export declare function getAppRuntimeNodeModulesDir(appConfig: Pick<EcoPagesAppConfig, 'rootDir' | 'workDir' | 'absolutePaths'>): string;
+export interface NodeBootstrapResolutionOptions {
+    projectDir: string;
+    runtimeNodeModulesDir: string;
+    preserveImportMetaPaths?: string[];
+}
+/**
+ * Builds the user-facing error for Bun-native imports that cannot run on the
+ * Node thin-host bootstrap path.
+ */
+export declare function getNodeUnsupportedBuiltinError(specifier: string, importer?: string): string;
+/**
+ * Resolves one bare specifier encountered while bundling Node thin-host
+ * bootstrap modules.
+ *
+ * Workspace-owned `@ecopages/*` packages stay in the bundle graph so Node does
+ * not execute their source files directly. Third-party packages stay external,
+ * but are linked into the runtime-local `node_modules` tree so the generated
+ * bootstrap output resolves them from a deterministic location.
+ */
+export declare function resolveNodeBootstrapDependency(args: Pick<EcoBuildOnResolveArgs, 'path' | 'importer'>, options: NodeBootstrapResolutionOptions): EcoBuildOnResolveResult | undefined;
+/**
+ * Creates the bootstrap-time resolver plugin used by the Node thin-host
+ * adapter for config and entry module loading.
+ */
+export declare function createNodeBootstrapPlugin(options: NodeBootstrapResolutionOptions): EcoBuildPlugin;
+/**
+ * Creates the standard Node bootstrap plugin for one finalized app config.
+ */
+export declare function createAppNodeBootstrapPlugin(appConfig: Pick<EcoPagesAppConfig, 'rootDir' | 'workDir' | 'absolutePaths'>, options?: {
+    preserveImportMetaPaths?: string[];
+}): EcoBuildPlugin;