@ecopages/core 0.2.0-alpha.25 → 0.2.0-alpha.26

package/src/static-site-generator/static-site-generator.js

@@ -0,0 +1,349 @@
+import path from "node:path";
+import { appLogger } from "../global/app-logger.js";
+import { fileSystem } from "@ecopages/file-system";
+import { PathUtils } from "../utils/path-utils.module.js";
+const STATIC_SITE_GENERATOR_ERRORS = {
+  ROUTE_RENDERER_FACTORY_REQUIRED: "RouteRendererFactory is required for render strategy",
+  unsupportedBodyType: (bodyType) => `Unsupported body type for static generation: ${bodyType}`,
+  missingIntegration: (routePath) => `View at ${routePath} is missing __eco.integration. Ensure it's defined with eco.page().`,
+  noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`,
+  dynamicRouteRequiresStaticPaths: (routePath) => `Dynamic route ${routePath} requires staticPaths to be defined on the view.`
+};
+class StaticSiteGenerator {
+  appConfig;
+  /**
+   * Creates the static-site generator for one app config.
+   */
+  constructor({ appConfig }) {
+    this.appConfig = appConfig;
+  }
+  getExportDir() {
+    return this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
+  }
+  /**
+   * Logs the standardized warning emitted when a dynamic-cache page is skipped.
+   */
+  warnDynamicPageSkipped(filePath) {
+    appLogger.warn(
+      "Pages with cache: 'dynamic' are not supported in static generation or preview, so they will be skipped\n",
+      `\u27A4 ${filePath}`
+    );
+  }
+  /**
+   * Determines whether one filesystem-discovered page should be excluded from
+   * static generation.
+   */
+  async shouldSkipStaticPageFile(filePath, routeRendererFactory) {
+    const module = await routeRendererFactory.createRenderer(filePath).loadPageModule(filePath, {
+      cacheScope: "static-page-probe"
+    });
+    if (module.default?.cache !== "dynamic") {
+      return false;
+    }
+    this.warnDynamicPageSkipped(filePath);
+    return true;
+  }
+  /**
+   * Determines whether one explicit static route view should be excluded from
+   * static generation.
+   */
+  shouldSkipStaticView(routePath, view) {
+    if (view.cache !== "dynamic") {
+      return false;
+    }
+    this.warnDynamicPageSkipped(routePath);
+    return true;
+  }
+  /**
+   * Writes the robots.txt file declared by the app config.
+   */
+  generateRobotsTxt() {
+    let data = "";
+    const preferences = this.appConfig.robotsTxt.preferences;
+    for (const userAgent in preferences) {
+      data += `user-agent: ${userAgent}
+`;
+      for (const path2 of preferences[userAgent]) {
+        data += `disallow: ${path2}
+`;
+      }
+      data += "\n";
+    }
+    fileSystem.ensureDir(this.getExportDir());
+    fileSystem.write(path.join(this.getExportDir(), "robots.txt"), data);
+  }
+  /**
+   * Returns whether the input path points at the root directory.
+   */
+  isRootDir(path2) {
+    const slashes = path2.match(/\//g);
+    return slashes && slashes.length === 1;
+  }
+  /**
+   * Collects parent directories that must exist for the generated route set.
+   */
+  getDirectories(routes) {
+    const directories = /* @__PURE__ */ new Set();
+    for (const route of routes) {
+      const path2 = route.startsWith("http") ? new URL(route).pathname : route;
+      const segments = path2.split("/");
+      if (segments.length > 2) {
+        directories.add(segments.slice(0, segments.length - 1).join("/"));
+      }
+    }
+    return Array.from(directories);
+  }
+  /**
+   * Extracts dynamic parameters from the actual path based on the template path.
+   *
+   * @param templatePath - The template path (e.g., "/blog/[slug]")
+   * @param actualPath - The actual path (e.g., "/blog/my-post")
+   * @returns A record of extracted parameters (e.g., { slug: "my-post" })
+   */
+  extractParams(templatePath, actualPath) {
+    const templateSegments = templateSegmentsFromPath(templatePath);
+    const actualSegments = templateSegmentsFromPath(actualPath);
+    const params = {};
+    for (let i = 0; i < templateSegments.length; i++) {
+      const segment = templateSegments[i];
+      if (segment.startsWith("[") && segment.endsWith("]")) {
+        const paramName = segment.slice(1, -1).replace("...", "");
+        params[paramName] = actualSegments[i];
+      }
+    }
+    return params;
+  }
+  /**
+   * Generates static output for all filesystem-discovered routes.
+   *
+   * @remarks
+   * Routes whose integrations opt into fetch-based static builds are rendered by
+   * issuing a request against the running server origin. Render-strategy routes
+   * go through the normal route renderer directly.
+   */
+  async generateStaticPages(router, baseUrl, routeRendererFactory) {
+    const routes = Object.keys(router.routes).filter((route) => !route.includes("["));
+    appLogger.debug("Static Pages", routes);
+    const directories = this.getDirectories(routes);
+    for (const directory of directories) {
+      fileSystem.ensureDir(path.join(this.getExportDir(), directory));
+    }
+    for (const route of routes) {
+      try {
+        const { filePath, pathname: routePathname } = router.routes[route];
+        const ext = PathUtils.getEcoTemplateExtension(filePath);
+        const integration = this.appConfig.integrations.find((plugin) => plugin.extensions.includes(ext));
+        const strategy = integration?.staticBuildStep || "render";
+        let contents;
+        if (strategy === "fetch") {
+          const fetchUrl = this.resolveStaticFetchUrl(route, baseUrl);
+          const response = await fetch(fetchUrl);
+          if (!response.ok) {
+            appLogger.error(`Failed to fetch ${fetchUrl}. Status: ${response.status}`);
+            continue;
+          }
+          contents = await response.text();
+        } else {
+          if (!routeRendererFactory) {
+            throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
+          }
+          if (await this.shouldSkipStaticPageFile(filePath, routeRendererFactory)) {
+            continue;
+          }
+          let pathname2 = routePathname;
+          const pathnameSegments2 = pathname2.split("/").filter(Boolean);
+          if (pathname2 === "/") {
+            pathname2 = "/index.html";
+          } else if (pathnameSegments2.join("/").includes("[")) {
+            pathname2 = `${route.replace(router.origin, "")}.html`;
+          } else if (pathnameSegments2.length >= 1 && directories.includes(`/${pathnameSegments2.join("/")}`)) {
+            pathname2 = `${pathname2.endsWith("/") ? pathname2 : `${pathname2}/`}index.html`;
+          } else {
+            pathname2 += ".html";
+          }
+          const renderer = routeRendererFactory.createRenderer(filePath);
+          const params = this.extractParams(routePathname, pathname2.replace(".html", ""));
+          const result = await renderer.createRoute({
+            file: filePath,
+            params
+          });
+          const body = result.body;
+          if (typeof body === "string" || Buffer.isBuffer(body)) {
+            contents = body;
+          } else if (body instanceof ReadableStream) {
+            contents = await new Response(body).text();
+          } else {
+            throw new Error(STATIC_SITE_GENERATOR_ERRORS.unsupportedBodyType(typeof body));
+          }
+        }
+        let pathname = routePathname;
+        const pathnameSegments = pathname.split("/").filter(Boolean);
+        if (pathname === "/") {
+          pathname = "/index.html";
+        } else if (pathnameSegments.join("/").includes("[")) {
+          pathname = `${route.replace(router.origin, "")}.html`;
+        } else if (pathnameSegments.length >= 1 && directories.includes(`/${pathnameSegments.join("/")}`)) {
+          pathname = `${pathname.endsWith("/") ? pathname : `${pathname}/`}index.html`;
+        } else {
+          pathname += ".html";
+        }
+        const outputPath = path.join(this.getExportDir(), pathname);
+        fileSystem.write(outputPath, contents);
+      } catch (error) {
+        appLogger.error(
+          `Error generating static page for ${route}:`,
+          error instanceof Error ? error : String(error)
+        );
+      }
+    }
+  }
+  resolveStaticFetchUrl(route, baseUrl) {
+    if (!route.startsWith("http://") && !route.startsWith("https://")) {
+      return `${baseUrl}${route}`;
+    }
+    const targetUrl = new URL(route);
+    const buildUrl = new URL(baseUrl);
+    buildUrl.pathname = targetUrl.pathname;
+    buildUrl.search = targetUrl.search;
+    buildUrl.hash = targetUrl.hash;
+    return buildUrl.href;
+  }
+  /**
+   * Executes the full static-generation workflow for one app run.
+   */
+  async run({
+    router,
+    baseUrl,
+    routeRendererFactory,
+    staticRoutes
+  }) {
+    this.generateRobotsTxt();
+    await this.generateStaticPages(router, baseUrl, routeRendererFactory);
+    if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
+      await this.generateExplicitStaticPages(staticRoutes, routeRendererFactory);
+    }
+  }
+  /**
+   * Generates static pages from explicit static routes registered via app.static().
+   * These routes use eco.page views via loader functions for HMR support.
+   */
+  async generateExplicitStaticPages(staticRoutes, routeRendererFactory) {
+    appLogger.debug(
+      "Generating explicit static routes",
+      staticRoutes.map((r) => r.path)
+    );
+    for (const route of staticRoutes) {
+      try {
+        const mod = await route.loader();
+        const view = mod.default;
+        if (this.shouldSkipStaticView(route.path, view)) {
+          continue;
+        }
+        const isDynamic = route.path.includes(":") || route.path.includes("[");
+        if (isDynamic) {
+          await this.generateDynamicStaticRoute(route.path, view, routeRendererFactory);
+        } else {
+          await this.generateSingleStaticRoute(route.path, view, routeRendererFactory);
+        }
+      } catch (error) {
+        appLogger.error(
+          `Error generating explicit static page for ${route.path}:`,
+          error instanceof Error ? error : String(error)
+        );
+      }
+    }
+  }
+  /**
+   * Generate a single static page for a non-dynamic route.
+   */
+  async generateSingleStaticRoute(routePath, view, routeRendererFactory) {
+    const integrationName = view.config?.__eco?.integration;
+    if (!integrationName) {
+      throw new Error(STATIC_SITE_GENERATOR_ERRORS.missingIntegration(routePath));
+    }
+    const renderer = routeRendererFactory.getRendererByIntegration(integrationName);
+    if (!renderer) {
+      throw new Error(STATIC_SITE_GENERATOR_ERRORS.noRendererForIntegration(integrationName));
+    }
+    const props = view.staticProps ? (await view.staticProps({
+      pathname: { params: {} },
+      appConfig: this.appConfig,
+      runtimeOrigin: this.appConfig.baseUrl
+    })).props : {};
+    const response = await renderer.renderToResponse(view, props, {});
+    const contents = await response.text();
+    const outputPath = this.getOutputPath(routePath);
+    fileSystem.ensureDir(path.dirname(outputPath));
+    fileSystem.write(outputPath, contents);
+    appLogger.debug(`Generated static page: ${routePath} -> ${outputPath}`);
+  }
+  /**
+   * Generate static pages for a dynamic route using staticPaths.
+   */
+  async generateDynamicStaticRoute(routePath, view, routeRendererFactory) {
+    if (!view.staticPaths) {
+      throw new Error(STATIC_SITE_GENERATOR_ERRORS.dynamicRouteRequiresStaticPaths(routePath));
+    }
+    const integrationName = view.config?.__eco?.integration;
+    if (!integrationName) {
+      throw new Error(STATIC_SITE_GENERATOR_ERRORS.missingIntegration(routePath));
+    }
+    const renderer = routeRendererFactory.getRendererByIntegration(integrationName);
+    if (!renderer) {
+      throw new Error(STATIC_SITE_GENERATOR_ERRORS.noRendererForIntegration(integrationName));
+    }
+    const { paths } = await view.staticPaths({
+      appConfig: this.appConfig,
+      runtimeOrigin: this.appConfig.baseUrl
+    });
+    for (const { params } of paths) {
+      const resolvedPath = this.resolveRoutePath(routePath, params);
+      const props = view.staticProps ? (await view.staticProps({
+        pathname: { params },
+        appConfig: this.appConfig,
+        runtimeOrigin: this.appConfig.baseUrl
+      })).props : {};
+      const response = await renderer.renderToResponse(view, props, {});
+      const contents = await response.text();
+      const outputPath = this.getOutputPath(resolvedPath);
+      fileSystem.ensureDir(path.dirname(outputPath));
+      fileSystem.write(outputPath, contents);
+      appLogger.debug(`Generated static page: ${resolvedPath} -> ${outputPath}`);
+    }
+  }
+  /**
+   * Resolve a route path template with actual params.
+   * Supports both :param and [param] syntax.
+   */
+  resolveRoutePath(routePath, params) {
+    let resolved = routePath;
+    for (const [key, value] of Object.entries(params)) {
+      const paramValue = Array.isArray(value) ? value.join("/") : value;
+      resolved = resolved.replace(`:${key}`, paramValue);
+      resolved = resolved.replace(`[${key}]`, paramValue);
+      resolved = resolved.replace(`[...${key}]`, paramValue);
+    }
+    return resolved;
+  }
+  /**
+   * Get the output file path for a given route.
+   */
+  getOutputPath(routePath) {
+    let outputName;
+    if (routePath === "/") {
+      outputName = "index.html";
+    } else if (routePath.endsWith("/")) {
+      outputName = `${routePath}index.html`;
+    } else {
+      outputName = `${routePath}.html`;
+    }
+    return path.join(this.getExportDir(), outputName);
+  }
+}
+function templateSegmentsFromPath(path2) {
+  return path2.split("/").filter(Boolean);
+}
+export {
+  STATIC_SITE_GENERATOR_ERRORS,
+  StaticSiteGenerator
+};

package/src/types/internal-types.d.ts

@@ -0,0 +1,231 @@
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { AppBuildManifest } from '../build/build-manifest.js';
+import type { BuildAdapter, BuildExecutor, BuildOwnership } from '../build/build-adapter.js';
+import type { IntegrationPlugin } from '../plugins/integration-plugin.js';
+import type { Processor } from '../plugins/processor.js';
+import type { EcoSourceTransform } from '../plugins/source-transform.js';
+import type { PageMetadataProps } from './public-types.js';
+import type { FSRouter } from '../router/server/fs-router.js';
+import type { CacheConfig } from '../services/cache/cache.types.js';
+import type { DevGraphService } from '../services/runtime-state/dev-graph.service.js';
+import type { AppModuleLoader } from '../services/module-loading/app-module-loader.service.js';
+import type { SourceModuleLoader } from '../services/module-loading/module-loading-types.js';
+import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { RuntimeSpecifierRegistry } from '../services/runtime-state/runtime-specifier-registry.service.js';
+import type { ServerInvalidationState } from '../services/runtime-state/server-invalidation-state.service.js';
+import type { ServerModuleTranspiler } from '../services/module-loading/server-module-transpiler.service.js';
+export interface RobotsPreference {
+    /**
+     * The user agent
+     * If an empty array is provided, it will enable all paths for the user agent
+     * If a path is provided, it will disallow the path for the user agent
+     */
+    [key: string]: string[];
+}
+/**
+ * Represents the complete configuration object for EcoPages.
+ */
+export type EcoPagesAppConfig = {
+    /**
+     * The base URL of the website, localhost or the domain
+     */
+    baseUrl: string;
+    /**
+     * The root directory of the project
+     * @default "."
+     */
+    rootDir: string;
+    /**
+     * The root directory of the project
+     * @default "src"
+     */
+    srcDir: string;
+    /**
+     * The directory where the public files are located
+     * @default "public"
+     */
+    publicDir: string;
+    /**
+     * The directory where the pages are located
+     * @default "pages"
+     */
+    pagesDir: string;
+    /**
+     * The directory where the includes templates are located
+     * @default "includes"
+     */
+    includesDir: string;
+    /**
+     * The directory where the layouts are located
+     * @default "layouts"
+     */
+    layoutsDir: string;
+    /**
+     * The directory where the output will be located
+     * @default "dist"
+     */
+    distDir: string;
+    /**
+     * The directory where internal runtime and build artifacts are stored.
+     *
+     * @remarks
+     * This directory is not intended for deployment. It owns transpiled server
+     * modules, runtime manifests, and processor caches so `distDir` can remain a
+     * clean export tree.
+     *
+     * @default ".eco"
+     */
+    workDir: string;
+    /**
+     * The templates extensions based on the integrations
+     */
+    templatesExt: string[];
+    /**
+     * The directory where the components are located
+     * @default "components"
+     */
+    componentsDir: string;
+    /**
+     * The robots.txt configuration
+     */
+    robotsTxt: {
+        /**
+         * The robots preferences. The key is the user agent and the value is the disallowed paths.
+         * @default { "*": [] }
+         */
+        preferences: RobotsPreference;
+    };
+    /** Additional paths to watch. Use this to monitor extra files. It is relative to the rootDir */
+    additionalWatchPaths: string[];
+    /**
+     * @default { title: 'Ecopages', description: 'Ecopages' }
+     */
+    defaultMetadata: PageMetadataProps;
+    /** Integrations plugins */
+    integrations: IntegrationPlugin[];
+    /** Integrations dependencies */
+    integrationsDependencies: IntegrationDependencyConfig[];
+    /** Derived Paths */
+    absolutePaths: {
+        config: string;
+        componentsDir: string;
+        distDir: string;
+        workDir: string;
+        includesDir: string;
+        layoutsDir: string;
+        pagesDir: string;
+        projectDir: string;
+        publicDir: string;
+        srcDir: string;
+        htmlTemplatePath: string;
+        error404TemplatePath: string;
+    };
+    /**
+     * The processors to be used in the app
+     */
+    processors: Map<string, Processor>;
+    /**
+     * Loaders to be used in the app, these are used to process the files when importing them
+     */
+    loaders: Map<string, EcoBuildPlugin>;
+    /**
+     * App-owned source transforms that can be adapted into Vite or other
+     * transform-first bundlers without going through the legacy loader bridge.
+     */
+    sourceTransforms: Map<string, EcoSourceTransform>;
+    /**
+     * Cache configuration for ISR and page caching.
+     * @default { store: 'memory', defaultStrategy: 'static', enabled: true }
+     */
+    cache?: CacheConfig;
+    /**
+     * Runtime-owned services attached after config construction.
+     *
+     * These values are internal implementation details used to thread per-app
+     * executors and similar runtime state through the system without relying on
+     * process-global registries.
+     */
+    runtime?: {
+        appModuleLoader?: AppModuleLoader;
+        buildOwnership?: BuildOwnership;
+        buildAdapter?: BuildAdapter;
+        buildManifest?: AppBuildManifest;
+        buildExecutor?: BuildExecutor;
+        devGraphService?: DevGraphService;
+        entrypointDependencyGraph?: EntrypointDependencyGraph;
+        hostModuleLoader?: SourceModuleLoader;
+        rendererModuleContext?: unknown;
+        runtimeSpecifierRegistry?: RuntimeSpecifierRegistry;
+        serverInvalidationState?: ServerInvalidationState;
+        serverModuleTranspiler?: ServerModuleTranspiler;
+    };
+    /**
+     * Experimental features.
+     */
+    experimental?: {
+        /** Escape hatch for short-lived private toggles. No validation or IntelliSense. */
+        unsafe?: Record<string, unknown>;
+    };
+};
+export type IntegrationDependencyConfig = {
+    integration: string;
+    kind: 'script' | 'stylesheet';
+    position?: 'head' | 'body';
+    srcUrl: string;
+    filePath: string;
+    /** @todo inline dependencies not implemented yet */
+    inline?: boolean;
+};
+/**
+ * The possible kinds of a route.
+ */
+export type RouteKind = 'exact' | 'catch-all' | 'dynamic';
+/**
+ * Represents the result of a route match.
+ */
+export type MatchResult = {
+    filePath: string;
+    kind: RouteKind;
+    pathname: string;
+    query?: Record<string, string>;
+    params?: Record<string, string | string[]>;
+};
+/**
+ * Represents a route in EcoPages.
+ */
+export type Route = {
+    kind: RouteKind;
+    filePath: string;
+    pathname: string;
+};
+/**
+ * Represents the routes in EcoPages.
+ */
+export type Routes = Record<string, Route>;
+/**
+ * Represents the options for the file system server.
+ */
+export type FileSystemServerOptions = {
+    watchMode: boolean;
+    port?: number | string;
+};
+/**
+ * Represents the file system server adapter.
+ */
+export interface EcoPagesFileSystemServerAdapter<ServerInstanceOptions = unknown> {
+    startServer(serverOptions: ServerInstanceOptions): {
+        router: FSRouter;
+        server: unknown;
+    } | Promise<{
+        router: FSRouter;
+        server: unknown;
+    }>;
+}
+export interface ProcessorPlugin {
+    name: string;
+    description?: string;
+    setup(): Promise<void>;
+    process<T = unknown>(input: T): Promise<T>;
+    teardown?(): Promise<void>;
+}
+export type { ClientBridgeEvent, DefaultHmrContext, IHmrManager, IClientBridge } from './public-types.js';