@ecopages/core 0.2.0-alpha.54 → 0.2.0-alpha.55

package/src/adapters/shared/hmr-entrypoint-registrar.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared runtime state used while registering HMR-owned entrypoints.
+ */
+export interface HmrEntrypointRegistrarOptions {
+    /** Absolute source directory used to derive the emitted HMR path. */
+    srcDir: string;
+    /** Absolute distribution directory where HMR outputs are written. */
+    distDir: string;
+    /** In-flight registrations keyed by normalized absolute entrypoint path. */
+    entrypointRegistrations: Map<string, Promise<string>>;
+    /** Stable entrypoint-to-output mapping retained once an entrypoint is registered. */
+    watchedFiles: Map<string, string>;
+    /** Runtime-specific cleanup invoked when an entrypoint registration fails. */
+    clearFailedRegistration?: (entrypointPath: string) => void;
+    /** Development-only guardrail for integrations that never finish producing output. */
+    registrationTimeoutMs: number;
+}
+/**
+ * Runtime-specific hooks required to materialize a single HMR entrypoint.
+ */
+export interface HmrEntrypointRegistrationOptions {
+    /**
+     * Emits the browser-consumable HMR artifact for an entrypoint.
+     */
+    emit(entrypointPath: string, outputPath: string): Promise<void>;
+    /**
+     * Creates the runtime-specific error raised when the emit hook completes without producing output.
+     */
+    getMissingOutputError(entrypointPath: string, outputPath: string): Error;
+}
+/**
+ * Coordinates the shared HMR entrypoint registration lifecycle for both Node and Bun managers.
+ *
+ * The registrar owns the cross-runtime policy: normalize entrypoint identities, dedupe concurrent
+ * registrations, derive the emitted `_hmr` output path, clear stale output before rebuilding, and
+ * apply the development timeout that prevents unresolved registrations from hanging navigation.
+ * Runtime-specific managers remain responsible for the actual emit step and any cleanup outside
+ * this shared registration flow.
+ */
+export declare class HmrEntrypointRegistrar {
+    private readonly options;
+    constructor(options: HmrEntrypointRegistrarOptions);
+    /**
+     * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
+     *
+     * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
+     * integration only builds once per registration cycle.
+     */
+    registerEntrypoint(entrypointPath: string, registrationOptions: HmrEntrypointRegistrationOptions): Promise<string>;
+    private registerEntrypointInternal;
+    private awaitEntrypointRegistration;
+    private getEntrypointOutput;
+    private removeStaleEntrypointOutput;
+    private encodeDynamicSegments;
+}

package/src/adapters/shared/hmr-entrypoint-registrar.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { appLogger } from "../../global/app-logger.js";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+class HmrEntrypointRegistrar {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
+   *
+   * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
+   * integration only builds once per registration cycle.
+   */
+  async registerEntrypoint(entrypointPath, registrationOptions) {
+    const normalizedEntrypoint = path.resolve(entrypointPath);
+    const existingRegistration = this.options.entrypointRegistrations.get(normalizedEntrypoint);
+    if (existingRegistration) {
+      return await this.awaitEntrypointRegistration(existingRegistration, normalizedEntrypoint);
+    }
+    const registration = this.registerEntrypointInternal(normalizedEntrypoint, registrationOptions);
+    this.options.entrypointRegistrations.set(normalizedEntrypoint, registration);
+    try {
+      return await this.awaitEntrypointRegistration(registration, normalizedEntrypoint);
+    } catch (error) {
+      this.options.clearFailedRegistration?.(normalizedEntrypoint);
+      throw error;
+    } finally {
+      this.options.entrypointRegistrations.delete(normalizedEntrypoint);
+    }
+  }
+  async registerEntrypointInternal(entrypointPath, registrationOptions) {
+    if (this.options.watchedFiles.has(entrypointPath)) {
+      return this.options.watchedFiles.get(entrypointPath);
+    }
+    const { outputPath, outputUrl } = this.getEntrypointOutput(entrypointPath);
+    this.options.watchedFiles.set(entrypointPath, outputUrl);
+    this.removeStaleEntrypointOutput(outputPath);
+    await registrationOptions.emit(entrypointPath, outputPath);
+    if (!fileSystem.exists(outputPath)) {
+      throw registrationOptions.getMissingOutputError(entrypointPath, outputPath);
+    }
+    return outputUrl;
+  }
+  async awaitEntrypointRegistration(registration, entrypointPath) {
+    if (process.env.NODE_ENV !== "development") {
+      return await registration;
+    }
+    return await Promise.race([
+      registration,
+      new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`[HMR] Timed out registering entrypoint: ${entrypointPath}`));
+        }, this.options.registrationTimeoutMs);
+      })
+    ]);
+  }
+  getEntrypointOutput(entrypointPath) {
+    const relativePath = path.relative(this.options.srcDir, entrypointPath);
+    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
+    const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
+    const urlPath = encodedPathJs.split(path.sep).join("/");
+    return {
+      outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath)}`,
+      outputPath: path.join(this.options.distDir, urlPath)
+    };
+  }
+  removeStaleEntrypointOutput(outputPath) {
+    if (!fileSystem.exists(outputPath)) {
+      return;
+    }
+    try {
+      fileSystem.remove(outputPath);
+    } catch (error) {
+      appLogger.warn(
+        `[HMR] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  encodeDynamicSegments(filepath) {
+    return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
+  }
+}
+export {
+  HmrEntrypointRegistrar
+};

package/src/adapters/shared/hmr-html-response.d.ts

@@ -0,0 +1,22 @@
+import type { IHmrManager } from '../../types/public-types.js';
+/**
+ * Returns whether a response is HTML and therefore eligible for development HMR
+ * runtime injection.
+ */
+export declare function isHtmlResponse(response: Response): boolean;
+/**
+ * Returns whether HTML responses should receive the HMR runtime bootstrap.
+ *
+ * This is shared because filesystem page responses and adapter-level HTML
+ * responses flow through different layers, but both need identical injection
+ * behavior in watch mode.
+ */
+export declare function shouldInjectHmrHtmlResponse(watch: boolean, hmrManager?: Pick<IHmrManager, 'isEnabled'>): boolean;
+/**
+ * Injects the development HMR runtime script into an HTML response if it is not
+ * already present.
+ *
+ * The check is intentionally idempotent because an HTML response can pass
+ * through more than one development-layer wrapper before reaching the client.
+ */
+export declare function injectHmrRuntimeIntoHtmlResponse(response: Response): Promise<Response>;

package/src/adapters/shared/hmr-html-response.js

@@ -0,0 +1,33 @@
+const HMR_RUNTIME_IMPORT = "import '/_hmr_runtime.js'";
+const HMR_RUNTIME_SCRIPT = `<script type="module">${HMR_RUNTIME_IMPORT};<\/script>`;
+function isHtmlResponse(response) {
+  const contentType = response.headers.get("Content-Type");
+  return contentType !== null && contentType.startsWith("text/html");
+}
+function shouldInjectHmrHtmlResponse(watch, hmrManager) {
+  return watch && hmrManager?.isEnabled() === true;
+}
+async function injectHmrRuntimeIntoHtmlResponse(response) {
+  const html = await response.text();
+  const headers = new Headers(response.headers);
+  headers.set("Cache-Control", "no-store, must-revalidate");
+  headers.delete("Content-Length");
+  if (html.includes(HMR_RUNTIME_IMPORT)) {
+    return new Response(html, {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
+  }
+  const updatedHtml = html.replace(/<\/html>/i, `${HMR_RUNTIME_SCRIPT}</html>`);
+  return new Response(updatedHtml, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+export {
+  injectHmrRuntimeIntoHtmlResponse,
+  isHtmlResponse,
+  shouldInjectHmrHtmlResponse
+};

package/src/adapters/shared/render-context.d.ts

@@ -0,0 +1,16 @@
+import type { RenderContext } from '../../types/public-types.js';
+import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.js';
+export interface CreateRenderContextOptions {
+    integrations: AnyIntegrationPlugin[];
+    rendererModules?: unknown;
+    importServerModule?: (filePath: string) => Promise<unknown>;
+}
+/**
+ * Creates a render context for route handlers.
+ * Provides render(), renderPartial(), json(), and html() methods that can be used
+ * within route handlers to generate responses.
+ *
+ * @param options - Configuration options including available integrations
+ * @returns A RenderContext object with methods for rendering views and creating responses
+ */
+export declare function createRenderContext(options: CreateRenderContextOptions): RenderContext;

package/src/adapters/shared/render-context.js

@@ -0,0 +1,93 @@
+import { fileURLToPath } from "node:url";
+import { invariant } from "../../utils/invariant.js";
+function resolveServerModulePath(filePath) {
+  return filePath instanceof URL ? fileURLToPath(filePath) : filePath;
+}
+function mergePropsWithLocals(props, locals) {
+  if (!locals || typeof props !== "object" || props === null) {
+    return props;
+  }
+  return { ...props, locals };
+}
+function createRenderContext(options) {
+  const { integrations } = options;
+  const getRendererForView = (view) => {
+    const integrationName = view.config?.integration ?? view.config?.__eco?.integration;
+    invariant(
+      !!integrationName,
+      "Cannot determine integration for view. Set view.config.integration explicitly or ensure the view is defined with eco.page() in a file with a recognized extension."
+    );
+    const integration = integrations.find((i) => i.name === integrationName);
+    invariant(!!integration, `No integration found for: ${integrationName}`);
+    return integration.initializeRenderer({
+      rendererModules: options.rendererModules
+    });
+  };
+  const renderContext = {
+    importServerModule: async (filePath) => {
+      invariant(!!options.importServerModule, "Server module importing is not available in this render context.");
+      return await options.importServerModule(resolveServerModulePath(filePath));
+    },
+    async renderServerModule(filePath, props, renderOptions) {
+      const module = await renderContext.importServerModule(filePath);
+      const view = module.default;
+      const locals = this?.locals;
+      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
+      const renderer = getRendererForView(view);
+      const ctx = {
+        partial: false,
+        status: renderOptions?.status,
+        headers: renderOptions?.headers
+      };
+      return await renderer.renderToResponse(view, mergedProps, ctx);
+    },
+    async render(view, props, renderOptions) {
+      const locals = this?.locals;
+      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
+      const renderer = getRendererForView(view);
+      const ctx = {
+        partial: false,
+        status: renderOptions?.status,
+        headers: renderOptions?.headers
+      };
+      return renderer.renderToResponse(view, mergedProps, ctx);
+    },
+    async renderPartial(view, props, renderOptions) {
+      const locals = this?.locals;
+      const mergedProps = mergePropsWithLocals(props, locals);
+      const renderer = getRendererForView(view);
+      const ctx = {
+        partial: true,
+        status: renderOptions?.status,
+        headers: renderOptions?.headers
+      };
+      return renderer.renderToResponse(view, mergedProps, ctx);
+    },
+    json(data, responseOptions) {
+      const headers = new Headers({ "Content-Type": "application/json; charset=utf-8" });
+      if (responseOptions?.headers) {
+        const incomingHeaders = new Headers(responseOptions.headers);
+        incomingHeaders.forEach((value, key) => headers.set(key, value));
+      }
+      return new Response(JSON.stringify(data), {
+        status: responseOptions?.status ?? 200,
+        headers
+      });
+    },
+    html(content, responseOptions) {
+      const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
+      if (responseOptions?.headers) {
+        const incomingHeaders = new Headers(responseOptions.headers);
+        incomingHeaders.forEach((value, key) => headers.set(key, value));
+      }
+      return new Response(content, {
+        status: responseOptions?.status ?? 200,
+        headers
+      });
+    }
+  };
+  return renderContext;
+}
+export {
+  createRenderContext
+};

package/src/adapters/shared/runtime-app-bootstrap.d.ts

@@ -0,0 +1,26 @@
+import type { ReturnParseCliArgs } from '../../utils/parse-cli-args.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export type RuntimeBinding = {
+    preferredPort: number;
+    preferredHostname: string;
+    runtimeOrigin: string;
+    serveOptions: Record<string, unknown>;
+    watch: boolean;
+};
+export type StaticRuntimeMode = {
+    requiresFetchRuntime: boolean;
+    canBuildWithoutRuntimeServer: boolean;
+};
+export declare function resolveServeRuntimeOrigin(serveOptions: {
+    hostname?: string;
+    port?: number | string;
+}): string;
+export declare function resolveRuntimeBinding(options: {
+    cliArgs: ReturnParseCliArgs;
+    serverOptions?: Record<string, unknown>;
+    env?: NodeJS.ProcessEnv;
+}): RuntimeBinding;
+export declare function resolveStaticRuntimeMode(options: {
+    appConfig: EcoPagesAppConfig;
+    cliArgs: ReturnParseCliArgs;
+}): StaticRuntimeMode;

package/src/adapters/shared/runtime-app-bootstrap.js

@@ -0,0 +1,46 @@
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+function normalizeOriginHostname(hostname) {
+  if (hostname.includes(":") && !hostname.startsWith("[") && !hostname.endsWith("]")) {
+    return `[${hostname}]`;
+  }
+  return hostname;
+}
+function resolveServeRuntimeOrigin(serveOptions) {
+  const hostname = normalizeOriginHostname(String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME));
+  const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+  return `http://${hostname}:${port}`;
+}
+function resolveRuntimeBinding(options) {
+  const env = options.env ?? process.env;
+  const preferredPort = options.cliArgs.port ?? (env.ECOPAGES_PORT ? Number(env.ECOPAGES_PORT) : void 0) ?? DEFAULT_ECOPAGES_PORT;
+  const preferredHostname = options.cliArgs.hostname ?? env.ECOPAGES_HOSTNAME ?? DEFAULT_ECOPAGES_HOSTNAME;
+  return {
+    preferredPort,
+    preferredHostname,
+    runtimeOrigin: resolveServeRuntimeOrigin({
+      hostname: preferredHostname,
+      port: preferredPort
+    }),
+    serveOptions: {
+      port: preferredPort,
+      hostname: preferredHostname,
+      ...options.serverOptions ?? {}
+    },
+    watch: options.cliArgs.dev
+  };
+}
+function resolveStaticRuntimeMode(options) {
+  const requiresFetchRuntime = options.appConfig.integrations.some(
+    (integration) => integration.staticBuildStep === "fetch"
+  );
+  const canBuildWithoutRuntimeServer = (options.cliArgs.build || options.cliArgs.preview) && !requiresFetchRuntime;
+  return {
+    requiresFetchRuntime,
+    canBuildWithoutRuntimeServer
+  };
+}
+export {
+  resolveRuntimeBinding,
+  resolveServeRuntimeOrigin,
+  resolveStaticRuntimeMode
+};

package/src/adapters/shared/runtime-host.d.ts

@@ -0,0 +1,12 @@
+export interface RuntimeHost<TServer, TServeOptions> {
+    start(options: RuntimeHostStartOptions<TServeOptions>): Promise<TServer>;
+    stop(server: TServer, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    getOrigin(server: TServer, fallbackServeOptions: TServeOptions): string;
+}
+export interface RuntimeHostStartOptions<TServeOptions> {
+    serveOptions: TServeOptions;
+    handleRequest(request: Request): Promise<Response>;
+    onError(error: Error): Promise<void> | void;
+}

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

@@ -0,0 +1,108 @@
+import { AbstractServerAdapter } from '../abstract/server-adapter.js';
+import type { ServerAdapterOptions, ServerAdapterResult } from '../abstract/server-adapter.js';
+import { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+import { RouteRegistry } from '../../router/server/route-registry.js';
+import { SchemaValidationService } from '../../services/validation/schema-validation-service.js';
+import { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.js';
+import { ServerStaticBuilder } from './server-static-builder.js';
+import { FileSystemResponseMatcher } from './fs-server-response-matcher.js';
+import { ServerRouteHandler } from './server-route-handler.js';
+import type { ApiHandler, CacheInvalidator, ErrorHandler, RenderContext, StaticRoute } from '../../types/public-types.js';
+type SharedRequestContext = {
+    apiHandlers: ApiHandler[];
+    errorHandler?: ErrorHandler;
+    serverInstance?: any;
+    hmrManager?: any;
+};
+export declare abstract class SharedServerAdapter<TOptions extends ServerAdapterOptions, TResult extends ServerAdapterResult> extends AbstractServerAdapter<TOptions, TResult> {
+    protected router: RouteRegistry;
+    protected fileSystemResponseMatcher: FileSystemResponseMatcher;
+    protected routeRendererFactory: RouteRendererFactory;
+    protected routeHandler: ServerRouteHandler;
+    protected staticSiteGenerator: StaticSiteGenerator;
+    protected staticBuilder: ServerStaticBuilder;
+    protected readonly schemaValidator: SchemaValidationService;
+    protected initializeSharedRouteHandling(options: {
+        staticRoutes: StaticRoute[];
+        hmrManager?: any;
+    }): Promise<void>;
+    protected createSharedWatchRefreshCallback(options: {
+        staticRoutes: StaticRoute[];
+        hmrManager?: any;
+        onRoutesReady?: () => Promise<void> | void;
+        onError?: (error: Error) => Promise<void> | void;
+    }): () => Promise<void>;
+    /**
+     * Scans the filesystem and dynamically constructs the Route Registry.
+     *
+     * This process runs identically across both Bun and Node wrappers. It analyzes the configured pages
+     * directory, building a map of all available UI routes and API endpoints.
+     * The resulting `RouteRegistry` instance becomes the central nervous system for mapping WinterCG incoming
+     * Web Requests (`Request`) to their corresponding internal execution paths.
+     */
+    protected initSharedRouter(): Promise<void>;
+    private createRouteRegistryPageModuleAdapter;
+    /**
+     * Sets up the unified rendering pipeline and response matching chain.
+     *
+     * It bridges several sub-systems together so that when an incoming request is received, the adapter knows:
+     * 1. How to render React/Lit pages via `RouteRendererFactory`
+     * 2. How to match logical routes to physical filesystem artifacts via `FileSystemResponseMatcher`
+     * 3. Whether to serve the response from the embedded `PageCacheService` or generate it fresh on the fly.
+     *
+     * Because `HmrManager` implementations rely heavily on runtime-specific WebSocket APIs (e.g. Bun.serve Websockets vs Node WS),
+     * we leave it untyped (`any`) here at the common denominator core.
+     *
+     * @param staticRoutes - A map of explicitly served static assets.
+     * @param hmrManager - The runtime-specific Hot Module Replacement orchestrator (if watching).
+     */
+    protected configureSharedResponseHandlers(staticRoutes: StaticRoute[], hmrManager?: any): void;
+    private createSharedResponseHandlerDependencies;
+    private createSharedPageCacheService;
+    protected getCacheService(): CacheInvalidator | null;
+    protected getRenderContext(): RenderContext;
+    /**
+     * Executes an Application Programming Interface (API) handler in an environment-agnostic manner.
+     *
+     * API routes in Ecopages are universally written using standard WinterCG `Request` and `Response` objects.
+     * This execution pipeline takes the raw `Request`, extracts its dynamic segments, runs our high-speed JSON schema
+     * validator against the body/query/headers, and triggers the developer's middleware chain sequentially.
+     *
+     * If the execution throws an error, it is gracefully caught, logged, and mutated into a standardized Http error payload,
+     * ensuring the consuming client receives a parsable response even upon internal catastrophic failure.
+     *
+     * @param request - The incoming Web standard `Request`.
+     * @param params - The extracted dynamic URL parameters (e.g., `{ id: '123' }`).
+     * @param routeConfig - The user-defined API handler object containing their business logic (`handler`) and `middleware`.
+     * @param serverInstance - Untyped reference to the underlying native server instance (BunServer/NodeServer) for potential escape hatches.
+     * @param errorHandler - Optional global error trap defined in project configuration.
+     * @returns The resulting Web standard `Response` constructed by the user's handler.
+     */
+    protected executeApiHandler(request: Request, params: Record<string, string | string[]>, routeConfig: ApiHandler, serverInstance: any, errorHandler?: ErrorHandler): Promise<Response>;
+    private createApiHandlerContext;
+    private normalizeApiParams;
+    private applyApiRequestSchema;
+    private runApiMiddlewareChain;
+    private normalizePath;
+    private matchApiPath;
+    private getApiPathScore;
+    protected matchApiHandler(request: Request, apiHandlers: ApiHandler[]): {
+        routeConfig: ApiHandler;
+        params: Record<string, string | string[]>;
+    } | null;
+    private tryHandleSharedHmrRequest;
+    private tryHandleSharedApiRequest;
+    /**
+     * Universally processes an incoming WinterCG Web standard Request.
+     *
+     * 1. Resolves static Hot Module Replacement runtime blobs if development.
+     * 2. Checks if the incoming request matches any parsed API route schemas.
+     *   - Routes through `executeApiHandler` which performs strict validation.
+     * 3. Falls through to standard `ServerRouteHandler` for React/Lit filesystem pages.
+     *
+     * Both Bun and Node bindings fall back to this exact function once they have mapped their
+     * native HTTP objects into Web Standard Requests.
+     */
+    handleSharedRequest(request: Request, context: SharedRequestContext): Promise<Response>;
+}
+export {};