@ecopages/core 0.2.0-beta.8 → 0.2.0-rc.0

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

@@ -1,41 +0,0 @@
-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) {
-  return {
-    canBuildWithoutRuntimeServer: options.cliArgs.build || options.cliArgs.preview
-  };
-}
-export {
-  resolveRuntimeBinding,
-  resolveServeRuntimeOrigin,
-  resolveStaticRuntimeMode
-};

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

@@ -1,436 +0,0 @@
-import path from "node:path";
-import { AbstractServerAdapter } from "../abstract/server-adapter.js";
-import { RouteRendererFactory } from "../../route-renderer/route-renderer.js";
-import { RouteRegistry } from "../../router/server/route-registry.js";
-import { MemoryCacheStore } from "../../services/cache/memory-cache-store.js";
-import { PageCacheService } from "../../services/cache/page-cache-service.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 { ExplicitStaticRouteMatcher } from "./explicit-static-route-matcher.js";
-import { FileSystemServerResponseFactory } from "./fs-server-response-factory.js";
-import { FileSystemResponseMatcher } from "./fs-server-response-matcher.js";
-import { ServerRouteHandler } from "./server-route-handler.js";
-import { createRenderContext } from "./render-context.js";
-import { createRequire } from "../../utils/locals-utils.js";
-import { HttpError } from "../../errors/http-error.js";
-import { ApiResponseBuilder } from "./api-response.js";
-import { appLogger } from "../../global/app-logger.js";
-import { fileSystem } from "@ecopages/file-system";
-import { getAppServerModuleTranspiler } from "../../services/module-loading/app-server-module-transpiler.service.js";
-import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
-class SharedServerAdapter extends AbstractServerAdapter {
-  router;
-  fileSystemResponseMatcher;
-  routeRendererFactory;
-  routeHandler;
-  staticSiteGenerator;
-  staticBuilder;
-  schemaValidator = new SchemaValidationService();
-  async initializeSharedRouteHandling(options) {
-    await this.initSharedRouter();
-    this.configureSharedResponseHandlers(options.staticRoutes, options.hmrManager);
-  }
-  createSharedWatchRefreshCallback(options) {
-    return async () => {
-      try {
-        await this.initializeSharedRouteHandling({
-          staticRoutes: options.staticRoutes,
-          hmrManager: options.hmrManager
-        });
-        if (options.onRoutesReady) {
-          await options.onRoutesReady();
-        }
-      } catch (error) {
-        if (options.onError) {
-          await options.onError(error instanceof Error ? error : new Error(String(error)));
-          return;
-        }
-        throw error;
-      }
-    };
-  }
-  /**
-   * 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.
-   */
-  async initSharedRouter() {
-    this.router = new RouteRegistry({
-      pagesDir: path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.pagesDir),
-      appConfig: this.appConfig,
-      origin: this.runtimeOrigin,
-      templatesExt: this.appConfig.templatesExt,
-      buildMode: !this.options?.watch,
-      pageModuleAdapter: this.createRouteRegistryPageModuleAdapter()
-    });
-    await this.router.init();
-  }
-  createRouteRegistryPageModuleAdapter() {
-    const serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
-    return {
-      loadPageModule: async (filePath) => {
-        const module = await serverModuleTranspiler.importModule({
-          filePath,
-          outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-route-modules"),
-          externalPackages: true,
-          transpileErrorMessage: (details) => `Error transpiling route module: ${details}`,
-          noOutputMessage: (targetFilePath) => `No transpiled output generated for route module: ${targetFilePath}`
-        });
-        const page = module.default;
-        return {
-          staticPaths: page?.staticPaths ?? module.getStaticPaths,
-          staticProps: page?.staticProps ?? module.getStaticProps
-        };
-      }
-    };
-  }
-  /**
-   * 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).
-   */
-  configureSharedResponseHandlers(staticRoutes, hmrManager) {
-    this.routeRendererFactory = new RouteRendererFactory({
-      appConfig: this.appConfig,
-      rendererModules: this.appConfig.runtime?.rendererModuleContext,
-      runtimeOrigin: this.runtimeOrigin
-    });
-    const { fileSystemResponseMatcher, explicitStaticRouteMatcher } = this.createSharedResponseHandlerDependencies(staticRoutes);
-    this.fileSystemResponseMatcher = fileSystemResponseMatcher;
-    this.routeHandler = new ServerRouteHandler({
-      router: this.router,
-      fileSystemResponseMatcher: this.fileSystemResponseMatcher,
-      explicitStaticRouteMatcher,
-      watch: !!this.options?.watch,
-      hmrManager
-    });
-  }
-  createSharedResponseHandlerDependencies(staticRoutes) {
-    const fileSystemResponseFactory = new FileSystemServerResponseFactory({
-      options: {
-        watchMode: !!this.options?.watch
-      }
-    });
-    const cacheService = this.createSharedPageCacheService();
-    const fileSystemResponseMatcher = new FileSystemResponseMatcher({
-      appConfig: this.appConfig,
-      assetPrefix: path.join(this.appConfig.rootDir, this.appConfig.distDir),
-      router: this.router,
-      routeRendererFactory: this.routeRendererFactory,
-      fileSystemResponseFactory,
-      cacheService,
-      defaultCacheStrategy: this.appConfig.cache?.defaultStrategy ?? "static"
-    });
-    return {
-      cacheService,
-      fileSystemResponseMatcher,
-      explicitStaticRouteMatcher: staticRoutes.length > 0 ? new ExplicitStaticRouteMatcher({
-        appConfig: this.appConfig,
-        routeRendererFactory: this.routeRendererFactory,
-        staticRoutes
-      }) : void 0
-    };
-  }
-  createSharedPageCacheService() {
-    const cacheConfig = this.appConfig.cache;
-    const isCacheEnabled = cacheConfig?.enabled ?? !this.options?.watch;
-    if (!isCacheEnabled) {
-      return null;
-    }
-    const store = cacheConfig?.store === "memory" || !cacheConfig?.store ? new MemoryCacheStore({ maxEntries: cacheConfig?.maxEntries }) : cacheConfig.store;
-    return new PageCacheService({ store, enabled: true });
-  }
-  getCacheService() {
-    return this.fileSystemResponseMatcher?.getCacheService() ?? null;
-  }
-  getRenderContext() {
-    const serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
-    return createRenderContext({
-      integrations: this.appConfig.integrations,
-      rendererModules: this.appConfig.runtime?.rendererModuleContext,
-      importServerModule: async (filePath) => await serverModuleTranspiler.importModule({
-        filePath,
-        outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
-        externalPackages: true,
-        bypassCache: this.options?.watch === true
-      })
-    });
-  }
-  /**
-   * 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.
-   */
-  async executeApiHandler(request, params, routeConfig, serverInstance, errorHandler) {
-    let context;
-    try {
-      context = this.createApiHandlerContext(request, params, serverInstance);
-      const schemaResponse = await this.applyApiRequestSchema(context, routeConfig.schema);
-      if (schemaResponse) {
-        return schemaResponse;
-      }
-      return await this.runApiMiddlewareChain(context, routeConfig);
-    } catch (error) {
-      if (error instanceof Response) return error;
-      if (errorHandler) {
-        try {
-          if (!context) {
-            context = this.createApiHandlerContext(request, params, serverInstance);
-          }
-          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 API request: ${error}`);
-      return new Response("Internal Server Error", { status: 500 });
-    }
-  }
-  createApiHandlerContext(request, params, serverInstance) {
-    const locals = {};
-    const normalizedParams = this.normalizeApiParams(params);
-    return {
-      request,
-      params: normalizedParams,
-      response: new ApiResponseBuilder(),
-      server: serverInstance,
-      locals,
-      require: createRequire(() => locals),
-      services: {
-        cache: this.getCacheService()
-      },
-      ...this.getRenderContext()
-    };
-  }
-  normalizeApiParams(params) {
-    return Object.fromEntries(
-      Object.entries(params).map(([key, value]) => [key, Array.isArray(value) ? value.join("/") : value])
-    );
-  }
-  async applyApiRequestSchema(context, schema) {
-    if (!schema) {
-      return void 0;
-    }
-    const url = new URL(context.request.url);
-    const queryParams = Object.fromEntries(url.searchParams);
-    const headers = Object.fromEntries(context.request.headers);
-    let body;
-    if (schema.body) {
-      try {
-        const contentType = context.request.headers.get("Content-Type") || "";
-        if (contentType.includes("application/json")) body = await context.request.clone().json();
-        else if (contentType.includes("text/plain")) body = await context.request.clone().text();
-      } catch {
-        return context.response.status(400).json({ error: "Invalid request body" });
-      }
-    }
-    const validationResult = await this.schemaValidator.validateRequest(
-      { body, query: queryParams, headers, params: context.params },
-      schema
-    );
-    if (!validationResult.success) {
-      return context.response.status(400).json({
-        error: "Validation failed",
-        issues: validationResult.errors
-      });
-    }
-    const validated = validationResult.data;
-    if (validated.body !== void 0) context.body = validated.body;
-    if (validated.query !== void 0) context.query = validated.query;
-    if (validated.headers !== void 0) context.headers = validated.headers;
-    if (validated.params !== void 0) context.params = validated.params;
-    return void 0;
-  }
-  async runApiMiddlewareChain(context, routeConfig) {
-    const middleware = routeConfig.middleware || [];
-    if (middleware.length === 0) {
-      return await routeConfig.handler(context);
-    }
-    let index = 0;
-    const executeNext = async () => {
-      if (index < middleware.length) {
-        const currentMiddleware = middleware[index++];
-        return await currentMiddleware(context, executeNext);
-      }
-      return await routeConfig.handler(context);
-    };
-    return await executeNext();
-  }
-  normalizePath(pathname) {
-    if (pathname.length > 1 && pathname.endsWith("/")) {
-      return pathname.slice(0, -1);
-    }
-    return pathname;
-  }
-  matchApiPath(pattern, pathname) {
-    const normalizedPattern = this.normalizePath(pattern);
-    const normalizedPathname = this.normalizePath(pathname);
-    const patternSegments = normalizedPattern.split("/").filter(Boolean);
-    const pathSegments = normalizedPathname.split("/").filter(Boolean);
-    const params = {};
-    let patternIndex = 0;
-    let pathIndex = 0;
-    while (patternIndex < patternSegments.length && pathIndex < pathSegments.length) {
-      const patternSegment = patternSegments[patternIndex];
-      const pathSegment = pathSegments[pathIndex];
-      if (patternSegment === "*") {
-        return params;
-      }
-      if (patternSegment.startsWith("[...") && patternSegment.endsWith("]")) {
-        const paramName = patternSegment.slice(4, -1);
-        params[paramName] = pathSegments.slice(pathIndex);
-        return params;
-      }
-      if (patternSegment.startsWith(":")) {
-        params[patternSegment.slice(1)] = pathSegment;
-        patternIndex++;
-        pathIndex++;
-        continue;
-      }
-      if (patternSegment.startsWith("[") && patternSegment.endsWith("]")) {
-        params[patternSegment.slice(1, -1)] = pathSegment;
-        patternIndex++;
-        pathIndex++;
-        continue;
-      }
-      if (patternSegment !== pathSegment) {
-        return null;
-      }
-      patternIndex++;
-      pathIndex++;
-    }
-    if (patternIndex < patternSegments.length) {
-      const remaining = patternSegments.slice(patternIndex);
-      const catchAll = remaining[0];
-      if (remaining.length === 1 && (catchAll === "*" || catchAll.startsWith("[...") && catchAll.endsWith("]"))) {
-        if (catchAll.startsWith("[...")) {
-          const paramName = catchAll.slice(4, -1);
-          params[paramName] = [];
-        }
-        return params;
-      }
-      return null;
-    }
-    if (pathIndex < pathSegments.length) {
-      return null;
-    }
-    return params;
-  }
-  getApiPathScore(pattern) {
-    const segments = this.normalizePath(pattern).split("/").filter(Boolean);
-    let score = 0;
-    for (const segment of segments) {
-      if (segment === "*" || segment.startsWith("[...") && segment.endsWith("]")) {
-        score += 10;
-      } else if (segment.startsWith(":") || segment.startsWith("[") && segment.endsWith("]")) {
-        score += 50;
-      } else {
-        score += 100;
-      }
-    }
-    return score;
-  }
-  matchApiHandler(request, apiHandlers) {
-    const pathname = new URL(request.url).pathname;
-    const method = request.method.toUpperCase();
-    const sortedHandlers = [...apiHandlers].sort((a, b) => {
-      return this.getApiPathScore(b.path) - this.getApiPathScore(a.path);
-    });
-    for (const routeConfig of sortedHandlers) {
-      const routeMethod = (routeConfig.method || "GET").toUpperCase();
-      if (routeMethod !== method) {
-        continue;
-      }
-      const params = this.matchApiPath(routeConfig.path, pathname);
-      if (params) {
-        return { routeConfig, params };
-      }
-    }
-    return null;
-  }
-  tryHandleSharedHmrRequest(request, context) {
-    const url = new URL(request.url);
-    if (url.pathname === "/_hmr_runtime.js" && context.hmrManager) {
-      const runtimePath = context.hmrManager.getRuntimePath();
-      if (fileSystem.exists(runtimePath)) {
-        return new Response(fileSystem.readFileAsBuffer(runtimePath), {
-          headers: { "Content-Type": "application/javascript" }
-        });
-      }
-    }
-    if (url.pathname.startsWith("/assets/_hmr/") && context.hmrManager) {
-      const relativePath = url.pathname.slice("/assets/_hmr/".length);
-      const assetPath = path.join(context.hmrManager.getDistDir(), relativePath);
-      if (fileSystem.exists(assetPath)) {
-        return new Response(fileSystem.readFileAsBuffer(assetPath), {
-          headers: { "Content-Type": "application/javascript" }
-        });
-      }
-    }
-    return null;
-  }
-  async tryHandleSharedApiRequest(request, context) {
-    const apiMatch = this.matchApiHandler(request, context.apiHandlers);
-    if (!apiMatch) {
-      return null;
-    }
-    return await this.executeApiHandler(
-      request,
-      apiMatch.params,
-      apiMatch.routeConfig,
-      context.serverInstance,
-      context.errorHandler
-    );
-  }
-  /**
-   * 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.
-   */
-  async handleSharedRequest(request, context) {
-    const hmrResponse = this.tryHandleSharedHmrRequest(request, context);
-    if (hmrResponse) {
-      return hmrResponse;
-    }
-    const apiResponse = await this.tryHandleSharedApiRequest(request, context);
-    if (apiResponse) {
-      return apiResponse;
-    }
-    return this.routeHandler.handleResponse(request);
-  }
-}
-export {
-  SharedServerAdapter
-};

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

@@ -1,111 +0,0 @@
-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;
-  explicitStaticRouteMatcher;
-  watch;
-  hmrManager;
-  /**
-   * Creates a new ServerRouteHandler instance.
-   *
-   * @param params - Configuration parameters
-   */
-  constructor({
-    router,
-    fileSystemResponseMatcher,
-    explicitStaticRouteMatcher,
-    watch = false,
-    hmrManager
-  }) {
-    this.router = router;
-    this.fileSystemResponseMatcher = fileSystemResponseMatcher;
-    this.explicitStaticRouteMatcher = explicitStaticRouteMatcher;
-    this.watch = watch;
-    this.hmrManager = hmrManager;
-  }
-  /**
-   * Determines if HMR script should be injected.
-   *
-   * @returns true if in watch mode and HMR manager is enabled
-   */
-  shouldInjectHmrScript() {
-    return shouldInjectHmrHtmlResponse(this.watch, this.hmrManager);
-  }
-  /**
-   * Checks if a response contains HTML content.
-   *
-   * @param response - The HTTP response to check
-   * @returns true if Content-Type header starts with 'text/html'
-   */
-  isHtmlResponse(response) {
-    return isHtmlResponse(response);
-  }
-  /**
-   * Handles HTTP requests from the router adapter.
-   *
-   * Priority-based routing flow:
-   * 1. Check explicit static routes first (e.g., /sitemap.xml, /image.webp from plugins)
-   * 2. Match file-based routes without extensions (application routes)
-   * 3. Fall back to static file serving from disk
-   *
-   * @param request - The incoming HTTP request
-   * @returns HTTP response, potentially with injected HMR script in dev mode
-   */
-  async handleResponse(request) {
-    const pathname = new URL(request.url).pathname;
-    const explicitMatch = this.explicitStaticRouteMatcher?.match(request.url);
-    if (explicitMatch) {
-      const response2 = await this.explicitStaticRouteMatcher.handleMatch(explicitMatch);
-      return this.maybeInjectHmrScript(response2);
-    }
-    const fsMatch = !pathname.includes(".") && this.router.matchRequest(request.url);
-    const response = await (fsMatch ? this.fileSystemResponseMatcher.handleMatch(fsMatch, request) : this.handleNoMatch(request));
-    return this.maybeInjectHmrScript(response);
-  }
-  /**
-   * Injects HMR script into HTML responses in development mode.
-   *
-   * The script is inserted before the closing </html> tag to enable
-   * hot module reloading without full page refreshes.
-   *
-   * @param response - The HTTP response to potentially modify
-   * @returns Original response or modified response with HMR script
-   */
-  async maybeInjectHmrScript(response) {
-    if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
-      return injectHmrRuntimeIntoHtmlResponse(response);
-    }
-    return response;
-  }
-  /**
-   * Handles requests that do not match any routes.
-   *
-   * This is the final fallback that attempts to serve static files from disk.
-   * If the requested path corresponds to an HTML file or no file is found,
-   * a custom 404 response is returned.
-   *
-   * @param request - The HTTP request to handle
-   * @returns Response from file system or error response
-   * @throws HttpError for standard HTTP errors
-   */
-  async handleNoMatch(request) {
-    try {
-      const pathname = new URL(request.url).pathname;
-      return await this.fileSystemResponseMatcher.handleNoMatch(pathname);
-    } catch (error) {
-      if (error instanceof HttpError) {
-        return error.toResponse();
-      }
-      if (error instanceof Error) {
-        this.hmrManager?.broadcast({ type: "error", message: error.message });
-        appLogger.error("Error handling no match:", error);
-      }
-      return new Response("Internal Server Error", { status: 500 });
-    }
-  }
-}
-export {
-  ServerRouteHandler
-};