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

package/src/adapters/bun/hmr-manager.js

@@ -0,0 +1,334 @@
+import fs from "node:fs";
+import path from "node:path";
+import { RESOLVED_ASSETS_DIR } from "../../constants";
+import { getAppBuildExecutor } from "../../build/build-adapter.js";
+import { fileSystem } from "@ecopages/file-system";
+import { HmrStrategyType } from "../../hmr/hmr-strategy";
+import { DefaultHmrStrategy } from "../../hmr/strategies/default-hmr-strategy";
+import { JsHmrStrategy } from "../../hmr/strategies/js-hmr-strategy";
+import { appLogger } from "../../global/app-logger";
+import { HmrEntrypointRegistrar } from "../shared/hmr-entrypoint-registrar.js";
+import { BrowserBundleService } from "../../services/assets/browser-bundle.service.js";
+import { getAppServerModuleTranspiler } from "../../services/module-loading/app-server-module-transpiler.service";
+import {
+  getAppEntrypointDependencyGraph,
+  NoopEntrypointDependencyGraph,
+  setAppEntrypointDependencyGraph
+} from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
+import { getAppRuntimeSpecifierRegistry } from "../../services/runtime-state/runtime-specifier-registry.service.js";
+import { resolveInternalExecutionDir, resolveInternalWorkDir } from "../../utils/resolve-work-dir.js";
+class HmrManager {
+  static entrypointRegistrationTimeoutMs = 4e3;
+  appConfig;
+  bridge;
+  /** Keep track of watchers */
+  watchers = /* @__PURE__ */ new Map();
+  /** entrypoint -> output path */
+  watchedFiles = /* @__PURE__ */ new Map();
+  entrypointRegistrations = /* @__PURE__ */ new Map();
+  distDir;
+  plugins = [];
+  enabled = true;
+  strategies = [];
+  entrypointRegistrar;
+  browserBundleService;
+  entrypointDependencyGraph;
+  runtimeSpecifierRegistry;
+  serverModuleTranspiler;
+  wsHandler;
+  constructor({ appConfig, bridge }) {
+    this.appConfig = appConfig;
+    this.bridge = bridge;
+    this.distDir = path.join(resolveInternalWorkDir(this.appConfig), RESOLVED_ASSETS_DIR, "_hmr");
+    this.entrypointRegistrar = new HmrEntrypointRegistrar({
+      srcDir: this.appConfig.absolutePaths.srcDir,
+      distDir: this.distDir,
+      entrypointRegistrations: this.entrypointRegistrations,
+      watchedFiles: this.watchedFiles,
+      clearFailedRegistration: (entrypointPath) => this.clearFailedEntrypointRegistration(entrypointPath),
+      registrationTimeoutMs: HmrManager.entrypointRegistrationTimeoutMs
+    });
+    this.browserBundleService = new BrowserBundleService(appConfig);
+    const existingEntrypointDependencyGraph = getAppEntrypointDependencyGraph(appConfig);
+    this.entrypointDependencyGraph = existingEntrypointDependencyGraph instanceof NoopEntrypointDependencyGraph ? existingEntrypointDependencyGraph : new NoopEntrypointDependencyGraph();
+    setAppEntrypointDependencyGraph(this.appConfig, this.entrypointDependencyGraph);
+    this.runtimeSpecifierRegistry = getAppRuntimeSpecifierRegistry(this.appConfig);
+    this.serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
+    this.cleanDistDir();
+    this.initializeStrategies();
+  }
+  /**
+   * Ensures the HMR output directory exists.
+   *
+   * This must not remove the directory because multiple app processes
+   * can share the same dist path during e2e runs.
+   */
+  cleanDistDir() {
+    fileSystem.ensureDir(this.distDir);
+  }
+  /**
+   * Returns whether the generic JS strategy may rebuild an entrypoint.
+   *
+   * @remarks
+   * Integration-owned page entrypoints are excluded so a shared dependency
+   * invalidation cannot replace framework-owned browser output with a generic JS
+   * rebuild.
+   */
+  shouldJsStrategyProcessEntrypoint(entrypointPath) {
+    return !this.strategies.some((strategy) => {
+      if (strategy.type !== HmrStrategyType.INTEGRATION || strategy.priority <= HmrStrategyType.SCRIPT) {
+        return false;
+      }
+      try {
+        return strategy.matches(entrypointPath);
+      } catch (error) {
+        appLogger.error(error);
+        return false;
+      }
+    });
+  }
+  /**
+   * Initializes core HMR strategies.
+   * Strategies are evaluated in priority order (highest first).
+   */
+  initializeStrategies() {
+    const jsContext = {
+      getWatchedFiles: () => this.watchedFiles,
+      getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
+      getDistDir: () => this.distDir,
+      getPlugins: () => this.plugins,
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getTemplateExtensions: () => this.appConfig.templatesExt,
+      getBrowserBundleService: () => this.browserBundleService,
+      getEntrypointDependencyGraph: () => this.entrypointDependencyGraph,
+      shouldProcessEntrypoint: (entrypointPath) => this.shouldJsStrategyProcessEntrypoint(entrypointPath)
+    };
+    this.strategies = [new JsHmrStrategy(jsContext), new DefaultHmrStrategy()];
+  }
+  /**
+   * Registers a custom HMR strategy.
+   * Used by integrations to provide framework-specific HMR handling.
+   * @param strategy - The HMR strategy to register
+   */
+  registerStrategy(strategy) {
+    this.strategies.push(strategy);
+  }
+  setPlugins(plugins) {
+    this.plugins = [...plugins];
+  }
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * Registers runtime bare-specifier mappings exposed by integrations.
+   *
+   * @remarks
+   * These mappings are consumed by framework-owned HMR strategies that preserve
+   * shared runtime imports in browser bundles. The registry stays generic so
+   * these mappings can later support broader import-map-style runtime features
+   * without moving integration semantics into core.
+   */
+  registerSpecifierMap(map) {
+    this.runtimeSpecifierRegistry.register(map);
+  }
+  getWebSocketHandler() {
+    const open = (ws) => {
+      this.bridge.subscribe(ws);
+      appLogger.debug(`[HmrManager] Connection opened. Subscribers: ${this.bridge.subscriberCount}`);
+    };
+    const close = (ws) => {
+      this.bridge.unsubscribe(ws);
+      appLogger.debug(`[HmrManager] Connection closed. Subscribers: ${this.bridge.subscriberCount}`);
+    };
+    this.wsHandler = { open, close };
+    return {
+      open: this.wsHandler.open,
+      close: this.wsHandler.close,
+      message: (_ws, message) => {
+        appLogger.debug("[HMR] Received message from client:", message);
+      }
+    };
+  }
+  /**
+   * Builds the client-side HMR runtime script.
+   */
+  async buildRuntime() {
+    const runtimeSource = path.resolve(import.meta.dirname, "../../hmr/client/hmr-runtime.js");
+    const result = await this.browserBundleService.bundle({
+      profile: "hmr-runtime",
+      entrypoints: [runtimeSource],
+      outdir: this.distDir,
+      naming: "_hmr_runtime.js",
+      minify: false,
+      plugins: this.plugins
+    });
+    if (!result.success) {
+      appLogger.error("[HMR] Failed to build runtime script:", result.logs);
+    }
+  }
+  getRuntimePath() {
+    return path.join(this.distDir, "_hmr_runtime.js");
+  }
+  broadcast(event) {
+    appLogger.debug(
+      `[HMR] Broadcasting ${event.type} event, path=${event.path || "all"}, subscribers=${this.bridge.subscriberCount}`
+    );
+    this.bridge.broadcast(event);
+  }
+  async handleFileChange(filePath, options = {}) {
+    const sorted = [...this.strategies].sort((a, b) => b.priority - a.priority);
+    const strategy = sorted.find((s) => {
+      try {
+        return s.matches(filePath);
+      } catch (err) {
+        appLogger.error(err);
+        return false;
+      }
+    });
+    if (!strategy) {
+      appLogger.warn(`[HMR] No strategy found for ${filePath}`);
+      return;
+    }
+    appLogger.debug(`[HmrManager] Selected strategy: ${strategy.constructor.name}`);
+    const action = await strategy.process(filePath);
+    const shouldBroadcast = options.broadcast ?? true;
+    if (shouldBroadcast && action.type === "broadcast") {
+      if (action.events) {
+        for (const event of action.events) {
+          this.broadcast(event);
+        }
+      }
+    }
+  }
+  getOutputUrl(entrypointPath) {
+    return this.watchedFiles.get(entrypointPath);
+  }
+  getWatchedFiles() {
+    return this.watchedFiles;
+  }
+  getSpecifierMap() {
+    return this.runtimeSpecifierRegistry.getAll();
+  }
+  getDistDir() {
+    return this.distDir;
+  }
+  getPlugins() {
+    return this.plugins;
+  }
+  getDefaultContext() {
+    return {
+      getWatchedFiles: () => this.watchedFiles,
+      getSpecifierMap: () => this.runtimeSpecifierRegistry.getAll(),
+      getDistDir: () => this.distDir,
+      getPlugins: () => this.plugins,
+      getSrcDir: () => this.appConfig.absolutePaths.srcDir,
+      getLayoutsDir: () => this.appConfig.absolutePaths.layoutsDir,
+      getPagesDir: () => this.appConfig.absolutePaths.pagesDir,
+      getBuildExecutor: () => getAppBuildExecutor(this.appConfig),
+      getBrowserBundleService: () => this.browserBundleService,
+      importServerModule: async (filePath) => await this.serverModuleTranspiler.importModule({
+        filePath,
+        outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
+        externalPackages: true
+      })
+    };
+  }
+  clearFailedEntrypointRegistration(entrypointPath) {
+    this.watchedFiles.delete(entrypointPath);
+  }
+  /**
+   * Registers one integration-owned page entrypoint.
+   *
+   * @remarks
+   * Concurrent callers share one in-flight registration. The registration is
+   * cleared from the dedupe map when it settles so later callers cannot inherit a
+   * stale promise.
+   */
+  async registerEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint, outputPath) => await this.emitStrictEntrypoint(normalizedEntrypoint, outputPath),
+      getMissingOutputError: (normalizedEntrypoint, outputPath) => new Error(
+        `[HMR] Integration failed to emit entrypoint ${normalizedEntrypoint} to ${outputPath}. Page entrypoints must be produced by their owning integration.`
+      )
+    });
+  }
+  /**
+   * Registers one generic script entrypoint.
+   *
+   * @remarks
+   * This explicit path keeps the page-entrypoint contract strict while still
+   * allowing generic script assets to use the fallback build path.
+   */
+  async registerScriptEntrypoint(entrypointPath) {
+    return await this.entrypointRegistrar.registerEntrypoint(entrypointPath, {
+      emit: async (normalizedEntrypoint, outputPath) => await this.emitScriptEntrypoint(normalizedEntrypoint, outputPath),
+      getMissingOutputError: (normalizedEntrypoint) => new Error(`[HMR] Failed to register script entrypoint: ${normalizedEntrypoint}`)
+    });
+  }
+  /**
+   * Performs strict integration-owned registration for one normalized path.
+   *
+   * @remarks
+   * The manager reserves the output URL, removes any stale emitted file, runs
+   * strategy processing without broadcasting, and then verifies that the owning
+   * integration emitted the expected file.
+   */
+  async emitStrictEntrypoint(entrypointPath, _outputPath) {
+    await this.handleFileChange(entrypointPath, { broadcast: false });
+  }
+  /**
+   * Performs registration for a generic script asset.
+   *
+   * @remarks
+   * Strategies get the first chance to emit output. If no output exists after
+   * that pass, Bun falls back to the generic browser build for this explicit
+   * script-only path.
+   */
+  async emitScriptEntrypoint(entrypointPath, outputPath) {
+    const naming = path.relative(this.distDir, outputPath).split(path.sep).join("/");
+    await this.handleFileChange(entrypointPath, { broadcast: false });
+    if (!fileSystem.exists(outputPath)) {
+      const buildResult = await this.browserBundleService.bundle({
+        profile: "hmr-entrypoint",
+        entrypoints: [entrypointPath],
+        outdir: this.distDir,
+        naming,
+        minify: false,
+        plugins: this.plugins
+      });
+      if (!buildResult.success) {
+        appLogger.error(
+          `[HMR] Generic script entrypoint build failed for ${entrypointPath}:`,
+          buildResult.logs
+        );
+      }
+    }
+  }
+  /**
+   * Stops active watchers and releases retained registration state.
+   *
+   * @remarks
+   * Emitted `_hmr` files remain on disk because parallel app processes may share
+   * the same dist directory. The in-memory indexes are cleared so stale
+   * entrypoints and specifier maps cannot leak through a reused manager object.
+   */
+  stop() {
+    this.entrypointRegistrations.clear();
+    for (const watcher of this.watchers.values()) {
+      watcher.close();
+    }
+    this.watchers.clear();
+    this.watchedFiles.clear();
+    this.runtimeSpecifierRegistry.clear();
+    this.entrypointDependencyGraph.reset();
+    this.plugins = [];
+  }
+}
+export {
+  HmrManager
+};

package/src/adapters/bun/index.d.ts

@@ -0,0 +1,2 @@
+export { EcopagesApp, createApp } from './create-app.js';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from '../shared/define-api-handler.js';

package/src/adapters/bun/index.js

@@ -0,0 +1,8 @@
+import { EcopagesApp, createApp } from "./create-app.js";
+import { defineApiHandler, defineGroupHandler } from "../shared/define-api-handler.js";
+export {
+  EcopagesApp,
+  createApp,
+  defineApiHandler,
+  defineGroupHandler
+};

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

@@ -0,0 +1,155 @@
+import type { Server, WebSocketHandler } from 'bun';
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { ApiHandler, ErrorHandler, StaticRoute } from '../../public-types.js';
+import { SharedServerAdapter } from '../shared/server-adapter.js';
+import type { ServerAdapterResult } from '../abstract/server-adapter.js';
+import { ServerRouteHandler, type ServerRouteHandlerParams } from '../shared/server-route-handler.js';
+import { ServerStaticBuilder, type ServerStaticBuilderParams } from '../shared/server-static-builder';
+import { ClientBridge } from './client-bridge';
+import { HmrManager } from './hmr-manager';
+import { ServerLifecycle } from './server-lifecycle.js';
+type BunServerInstance = Server<unknown>;
+type BunNativeServeOptions = Bun.Serve.Options<unknown>;
+export type BunServerRoutes = Bun.Serve.Routes<unknown, string>;
+export type BunServeAdapterServerOptions = Partial<Omit<BunNativeServeOptions, 'fetch'> & {
+    fetch(this: BunServerInstance, request: Request): Promise<void | Response>;
+}>;
+export type BunServeOptions = Omit<BunNativeServeOptions, 'fetch'> & {
+    fetch?: (this: BunServerInstance, request: Request, server: BunServerInstance) => Promise<void | Response>;
+    websocket?: WebSocketHandler<unknown>;
+};
+export interface BunServerAdapterParams {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    serveOptions: BunServeAdapterServerOptions;
+    apiHandlers?: ApiHandler<string, Request, BunServerInstance>[];
+    staticRoutes?: StaticRoute[];
+    errorHandler?: ErrorHandler;
+    options?: {
+        watch?: boolean;
+    };
+    lifecycle?: ServerLifecycle;
+    staticBuilderFactory?: (params: ServerStaticBuilderParams) => ServerStaticBuilder;
+    routeHandlerFactory?: (params: ServerRouteHandlerParams) => ServerRouteHandler;
+    hmrManager?: HmrManager;
+    bridge?: ClientBridge;
+}
+export interface BunServerAdapterResult extends ServerAdapterResult {
+    getServerOptions: (options?: {
+        enableHmr?: boolean;
+    }) => BunServeOptions;
+    buildStatic: (options?: {
+        preview?: boolean;
+    }) => Promise<void>;
+    completeInitialization: (server?: BunServerInstance | null) => Promise<void>;
+    handleRequest: (request: Request) => Promise<Response>;
+}
+export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapterParams, BunServerAdapterResult> {
+    appConfig: EcoPagesAppConfig;
+    options: BunServerAdapterParams['options'];
+    serveOptions: BunServeAdapterServerOptions;
+    protected apiHandlers: ApiHandler<string, Request, BunServerInstance>[];
+    protected staticRoutes: StaticRoute[];
+    protected errorHandler?: ErrorHandler;
+    private bridge;
+    private lifecycle;
+    hmrManager: HmrManager;
+    private initializationPromise;
+    private fullyInitialized;
+    serverInstance: BunServerInstance | null;
+    private readonly lifecycleFactory?;
+    private readonly staticBuilderFactory?;
+    private readonly routeHandlerFactory?;
+    private readonly hmrManagerFactory?;
+    private readonly bridgeFactory?;
+    constructor({ appConfig, runtimeOrigin, serveOptions, apiHandlers, staticRoutes, errorHandler, options, lifecycle, staticBuilderFactory, routeHandlerFactory, hmrManager, bridge, }: BunServerAdapterParams);
+    /**
+     * Determines if HMR script should be injected.
+     * Only injects in watch mode when HMR manager is enabled.
+     */
+    private shouldInjectHmrScript;
+    /**
+     * Checks if a response contains HTML content.
+     */
+    private isHtmlResponse;
+    /**
+     * Injects HMR script into HTML responses in development mode.
+     * Ensures explicit API handlers that return HTML get auto-reload capability.
+     */
+    private maybeInjectHmrScript;
+    /**
+     * Initializes the server adapter's core components.
+     * Delegates to ServerLifecycle for setup.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Refreshes the router routes during watch mode.
+     */
+    private refreshRouterRoutes;
+    private watch;
+    /**
+     * 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 }?: {
+        enableHmr?: boolean | undefined;
+    }): BunServeOptions;
+    /**
+     * 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.
+     */
+    private retrieveBodyFromRequest;
+    /**
+     * Creates complete server configuration with request handling.
+     * @returns Server options ready for Bun.serve()
+     */
+    private buildServerSettings;
+    /**
+     * Generates a static build of the site for deployment.
+     * @param options.preview - If true, starts a preview server after build
+     */
+    buildStatic(options?: {
+        preview?: boolean;
+    }): Promise<void>;
+    /**
+     * Initializes the server with dynamic routes after server creation.
+     * Must be called before handling any requests.
+     * @param server - The Bun server instance
+     */
+    completeInitialization(server?: BunServerInstance | null): Promise<void>;
+    /**
+     * Performs complete server setup including routing, watchers, and HMR.
+     */
+    private _performInitialization;
+    /**
+     * Creates and initializes the Bun server adapter.
+     * @returns Configured adapter with server methods
+     */
+    createAdapter(): Promise<BunServerAdapterResult>;
+    /**
+     * Handles HTTP requests by passing them securely to the shared core router adapter.
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * Ensures server initialization completes before request handling.
+     * Prevents race conditions during startup.
+     */
+    private waitForInitialization;
+    /**
+     * Handles HTTP requests from the router adapter.
+     */
+    handleResponse(request: Request): Promise<Response>;
+    /**
+     * Handles requests that do not match any routes.
+     */
+    private handleNoMatch;
+}
+/**
+ * Factory function to create a Bun server adapter
+ */
+export declare function createBunServerAdapter(params: BunServerAdapterParams): Promise<BunServerAdapterResult>;
+export {};