@ecopages/core 0.2.0-alpha.2 → 0.2.0-alpha.20

package/src/services/runtime-state/entrypoint-dependency-graph.service.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+class NoopEntrypointDependencyGraph {
+  supportsSelectiveInvalidation() {
+    return false;
+  }
+  getDependencyEntrypoints(_filePath) {
+    return /* @__PURE__ */ new Set();
+  }
+  setEntrypointDependencies(_entrypointPath, _dependencies) {
+  }
+  clearEntrypointDependencies(_entrypointPath) {
+  }
+  reset() {
+  }
+}
+class InMemoryEntrypointDependencyGraph {
+  dependencyEntrypoints = /* @__PURE__ */ new Map();
+  entrypointDependencies = /* @__PURE__ */ new Map();
+  supportsSelectiveInvalidation() {
+    return true;
+  }
+  getDependencyEntrypoints(filePath) {
+    return new Set(this.dependencyEntrypoints.get(path.resolve(filePath)) ?? []);
+  }
+  setEntrypointDependencies(entrypointPath, dependencies) {
+    const normalizedEntrypoint = path.resolve(entrypointPath);
+    this.clearEntrypointDependencies(normalizedEntrypoint);
+    const normalizedDependencies = /* @__PURE__ */ new Set([
+      normalizedEntrypoint,
+      ...dependencies.map((dependencyPath) => path.resolve(dependencyPath))
+    ]);
+    this.entrypointDependencies.set(normalizedEntrypoint, normalizedDependencies);
+    for (const dependencyPath of normalizedDependencies) {
+      const entrypoints = this.dependencyEntrypoints.get(dependencyPath) ?? /* @__PURE__ */ new Set();
+      entrypoints.add(normalizedEntrypoint);
+      this.dependencyEntrypoints.set(dependencyPath, entrypoints);
+    }
+  }
+  clearEntrypointDependencies(entrypointPath) {
+    const normalizedEntrypoint = path.resolve(entrypointPath);
+    const previousDependencies = this.entrypointDependencies.get(normalizedEntrypoint);
+    if (!previousDependencies) {
+      return;
+    }
+    for (const dependencyPath of previousDependencies) {
+      const entrypoints = this.dependencyEntrypoints.get(dependencyPath);
+      if (!entrypoints) {
+        continue;
+      }
+      entrypoints.delete(normalizedEntrypoint);
+      if (entrypoints.size === 0) {
+        this.dependencyEntrypoints.delete(dependencyPath);
+      }
+    }
+    this.entrypointDependencies.delete(normalizedEntrypoint);
+  }
+  reset() {
+    this.dependencyEntrypoints.clear();
+    this.entrypointDependencies.clear();
+  }
+}
+function isLegacyEntrypointDependencyGraph(value) {
+  return Boolean(value) && typeof value === "object" && typeof value.supportsSelectiveInvalidation === "function" && typeof value.getDependencyEntrypoints === "function" && typeof value.setEntrypointDependencies === "function" && typeof value.clearEntrypointDependencies === "function" && typeof value.reset === "function";
+}
+function getAppEntrypointDependencyGraph(appConfig) {
+  if (appConfig.runtime?.entrypointDependencyGraph) {
+    return appConfig.runtime.entrypointDependencyGraph;
+  }
+  if (isLegacyEntrypointDependencyGraph(appConfig.runtime?.devGraphService)) {
+    return appConfig.runtime.devGraphService;
+  }
+  return new NoopEntrypointDependencyGraph();
+}
+function setAppEntrypointDependencyGraph(appConfig, entrypointDependencyGraph) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    entrypointDependencyGraph
+  };
+}
+export {
+  InMemoryEntrypointDependencyGraph,
+  NoopEntrypointDependencyGraph,
+  getAppEntrypointDependencyGraph,
+  setAppEntrypointDependencyGraph
+};

package/src/services/runtime-state/runtime-specifier-registry.service.d.ts

@@ -0,0 +1,69 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Stores runtime-visible bare-specifier mappings for one app instance.
+ *
+ * @remarks
+ * Integrations populate this registry during runtime setup when they expose
+ * browser runtime modules through stable bare imports. Build and HMR code later
+ * consume the collected map to create aliasing and bootstrap behavior without
+ * forcing integrations to own global registry state.
+ */
+export interface RuntimeSpecifierRegistry {
+    /**
+     * Merges a new batch of specifier mappings into the registry.
+     *
+     * @remarks
+     * Later registrations replace earlier URLs for the same specifier. This keeps
+     * runtime setup deterministic while still allowing an integration to refresh
+     * its own declarations during one app session.
+     */
+    register(map: Record<string, string>): void;
+    /**
+     * Returns the current registry contents.
+     *
+     * @remarks
+     * The returned map is the live backing map for the registry implementation, so
+     * callers should treat it as read-only unless they intentionally own registry
+     * mutation semantics.
+     */
+    getAll(): Map<string, string>;
+    /**
+     * Removes all registered specifiers for the current app/runtime instance.
+     */
+    clear(): void;
+}
+/**
+ * Default in-memory runtime specifier registry used by core.
+ *
+ * @remarks
+ * Runtime specifier maps are app-local bootstrap metadata, not durable build
+ * artifacts, so the default implementation stays intentionally small.
+ */
+export declare class InMemoryRuntimeSpecifierRegistry implements RuntimeSpecifierRegistry {
+    private readonly specifierMap;
+    /**
+     * Merges one integration-provided mapping set into the app registry.
+     */
+    register(map: Record<string, string>): void;
+    /**
+     * Returns the live app-owned mapping table.
+     */
+    getAll(): Map<string, string>;
+    /**
+     * Clears all mappings for the current runtime session.
+     */
+    clear(): void;
+}
+/**
+ * Returns the runtime specifier registry owned by one app instance.
+ *
+ * @remarks
+ * Older tests and helpers may not seed runtime state explicitly yet, so this
+ * helper still provides an in-memory fallback when the app runtime has not been
+ * initialized.
+ */
+export declare function getAppRuntimeSpecifierRegistry(appConfig: EcoPagesAppConfig): RuntimeSpecifierRegistry;
+/**
+ * Installs the runtime specifier registry that should back one app instance.
+ */
+export declare function setAppRuntimeSpecifierRegistry(appConfig: EcoPagesAppConfig, runtimeSpecifierRegistry: RuntimeSpecifierRegistry): void;

package/src/services/runtime-state/runtime-specifier-registry.service.js

@@ -0,0 +1,37 @@
+class InMemoryRuntimeSpecifierRegistry {
+  specifierMap = /* @__PURE__ */ new Map();
+  /**
+   * Merges one integration-provided mapping set into the app registry.
+   */
+  register(map) {
+    for (const [specifier, url] of Object.entries(map)) {
+      this.specifierMap.set(specifier, url);
+    }
+  }
+  /**
+   * Returns the live app-owned mapping table.
+   */
+  getAll() {
+    return this.specifierMap;
+  }
+  /**
+   * Clears all mappings for the current runtime session.
+   */
+  clear() {
+    this.specifierMap.clear();
+  }
+}
+function getAppRuntimeSpecifierRegistry(appConfig) {
+  return appConfig.runtime?.runtimeSpecifierRegistry ?? new InMemoryRuntimeSpecifierRegistry();
+}
+function setAppRuntimeSpecifierRegistry(appConfig, runtimeSpecifierRegistry) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    runtimeSpecifierRegistry
+  };
+}
+export {
+  InMemoryRuntimeSpecifierRegistry,
+  getAppRuntimeSpecifierRegistry,
+  setAppRuntimeSpecifierRegistry
+};

package/src/services/runtime-state/server-invalidation-state.service.d.ts

@@ -0,0 +1,26 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * App-owned coarse invalidation state for server-executed modules.
+ */
+export interface ServerInvalidationState {
+    getServerInvalidationVersion(): number;
+    invalidateServerModules(changedFiles?: string[]): void;
+    reset(): void;
+}
+/**
+ * Minimal app-local invalidation state backed by a single generation counter.
+ */
+export declare class CounterServerInvalidationState implements ServerInvalidationState {
+    private serverInvalidationVersion;
+    getServerInvalidationVersion(): number;
+    invalidateServerModules(_changedFiles?: string[]): void;
+    reset(): void;
+}
+/**
+ * Returns the app-owned server invalidation state.
+ */
+export declare function getAppServerInvalidationState(appConfig: EcoPagesAppConfig): ServerInvalidationState;
+/**
+ * Installs the invalidation state used by one app instance.
+ */
+export declare function setAppServerInvalidationState(appConfig: EcoPagesAppConfig, serverInvalidationState: ServerInvalidationState): void;

package/src/services/runtime-state/server-invalidation-state.service.js

@@ -0,0 +1,35 @@
+class CounterServerInvalidationState {
+  serverInvalidationVersion = 0;
+  getServerInvalidationVersion() {
+    return this.serverInvalidationVersion;
+  }
+  invalidateServerModules(_changedFiles) {
+    this.serverInvalidationVersion += 1;
+  }
+  reset() {
+    this.serverInvalidationVersion += 1;
+  }
+}
+function isLegacyServerInvalidationState(value) {
+  return Boolean(value) && typeof value === "object" && typeof value.getServerInvalidationVersion === "function" && typeof value.invalidateServerModules === "function" && typeof value.reset === "function";
+}
+function getAppServerInvalidationState(appConfig) {
+  if (appConfig.runtime?.serverInvalidationState) {
+    return appConfig.runtime.serverInvalidationState;
+  }
+  if (isLegacyServerInvalidationState(appConfig.runtime?.devGraphService)) {
+    return appConfig.runtime.devGraphService;
+  }
+  return new CounterServerInvalidationState();
+}
+function setAppServerInvalidationState(appConfig, serverInvalidationState) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    serverInvalidationState
+  };
+}
+export {
+  CounterServerInvalidationState,
+  getAppServerInvalidationState,
+  setAppServerInvalidationState
+};

package/src/services/{schema-validation-service.d.ts → validation/schema-validation-service.d.ts}

@@ -1,4 +1,4 @@
-import type { StandardSchema } from './validation/standard-schema.types.js';
+import type { StandardSchema } from './standard-schema.types.js';
 export interface ValidationResult<T = unknown> {
     success: boolean;
     data?: T;

package/src/static-site-generator/README.md

@@ -0,0 +1,26 @@
+# Static Site Generation
+
+This directory contains the static-build execution path used when Ecopages renders pages ahead of time.
+
+## Purpose
+
+The static-site generator reuses the same app-owned config, route matching, and rendering services that development and preview flows use, but drives them in a build-oriented loop.
+
+It is responsible for:
+
+- enumerating renderable routes
+- rendering static outputs through the normal rendering pipeline
+- respecting route-level constraints such as cache policy and unsupported dynamic server-only paths
+
+## Design Rule
+
+Static generation should follow the same ownership model as runtime rendering.
+
+That means it should reuse:
+
+- built app config
+- route matching
+- render orchestration
+- asset processing
+
+It should not invent a parallel rendering stack just for build mode.

package/src/static-site-generator/static-site-generator.d.ts

@@ -1,7 +1,7 @@
-import type { EcoPagesAppConfig } from '../internal-types.js';
-import type { StaticRoute } from '../public-types.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { StaticRoute } from '../types/public-types.js';
 import type { RouteRendererFactory } from '../route-renderer/route-renderer.js';
-import type { FSRouter } from '../router/fs-router.js';
+import type { FSRouter } from '../router/server/fs-router.js';
 export declare const STATIC_SITE_GENERATOR_ERRORS: {
     readonly ROUTE_RENDERER_FACTORY_REQUIRED: "RouteRendererFactory is required for render strategy";
     readonly unsupportedBodyType: (bodyType: string) => string;
@@ -9,13 +9,49 @@ export declare const STATIC_SITE_GENERATOR_ERRORS: {
     readonly noRendererForIntegration: (integrationName: string) => string;
     readonly dynamicRouteRequiresStaticPaths: (routePath: string) => string;
 };
+/**
+ * Generates static output files from the finalized app config and route graph.
+ *
+ * @remarks
+ * This class intentionally reuses the same routing, renderer, and server-module
+ * loading seams used by runtime rendering. Static generation should be a build
+ * loop over the normal app model, not a parallel rendering stack with different
+ * semantics.
+ */
 export declare class StaticSiteGenerator {
     appConfig: EcoPagesAppConfig;
+    /**
+     * Creates the static-site generator for one app config.
+     */
     constructor({ appConfig }: {
         appConfig: EcoPagesAppConfig;
     });
+    private getExportDir;
+    /**
+     * Logs the standardized warning emitted when a dynamic-cache page is skipped.
+     */
+    private warnDynamicPageSkipped;
+    /**
+     * Determines whether one filesystem-discovered page should be excluded from
+     * static generation.
+     */
+    private shouldSkipStaticPageFile;
+    /**
+     * Determines whether one explicit static route view should be excluded from
+     * static generation.
+     */
+    private shouldSkipStaticView;
+    /**
+     * Writes the robots.txt file declared by the app config.
+     */
     generateRobotsTxt(): void;
+    /**
+     * Returns whether the input path points at the root directory.
+     */
     isRootDir(path: string): boolean | null;
+    /**
+     * Collects parent directories that must exist for the generated route set.
+     */
     getDirectories(routes: string[]): string[];
     /**
      * Extracts dynamic parameters from the actual path based on the template path.
@@ -25,7 +61,18 @@ export declare class StaticSiteGenerator {
      * @returns A record of extracted parameters (e.g., { slug: "my-post" })
      */
     private extractParams;
+    /**
+     * 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.
+     */
     generateStaticPages(router: FSRouter, baseUrl: string, routeRendererFactory?: RouteRendererFactory): Promise<void>;
+    /**
+     * Executes the full static-generation workflow for one app run.
+     */
     run({ router, baseUrl, routeRendererFactory, staticRoutes, }: {
         router: FSRouter;
         baseUrl: string;

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

@@ -11,9 +11,52 @@ const STATIC_SITE_GENERATOR_ERRORS = {
 };
 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;
@@ -26,13 +69,19 @@ class StaticSiteGenerator {
       }
       data += "\n";
     }
-    fileSystem.ensureDir(this.appConfig.distDir);
-    fileSystem.write(`${this.appConfig.distDir}/robots.txt`, data);
+    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) {
@@ -64,12 +113,20 @@ class StaticSiteGenerator {
     }
     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.appConfig.rootDir, this.appConfig.distDir, directory));
+      fileSystem.ensureDir(path.join(this.getExportDir(), directory));
     }
     for (const route of routes) {
       try {
@@ -90,6 +147,9 @@ class StaticSiteGenerator {
           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 === "/") {
@@ -127,7 +187,7 @@ class StaticSiteGenerator {
         } else {
           pathname += ".html";
         }
-        const outputPath = path.join(this.appConfig.rootDir, this.appConfig.distDir, pathname);
+        const outputPath = path.join(this.getExportDir(), pathname);
         fileSystem.write(outputPath, contents);
       } catch (error) {
         appLogger.error(
@@ -137,6 +197,9 @@ class StaticSiteGenerator {
       }
     }
   }
+  /**
+   * Executes the full static-generation workflow for one app run.
+   */
   async run({
     router,
     baseUrl,
@@ -162,6 +225,9 @@ class StaticSiteGenerator {
       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);
@@ -260,7 +326,7 @@ class StaticSiteGenerator {
     } else {
       outputName = `${routePath}.html`;
     }
-    return path.join(this.appConfig.rootDir, this.appConfig.distDir, outputName);
+    return path.join(this.getExportDir(), outputName);
   }
 }
 function templateSegmentsFromPath(path2) {

package/src/{internal-types.d.ts → types/internal-types.d.ts}

@@ -1,17 +1,19 @@
-import type { EcoBuildPlugin } from './build/build-types.js';
-import type { IntegrationPlugin } from './plugins/integration-plugin.js';
-import type { Processor } from './plugins/processor.js';
+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/fs-router.js';
-import type { CacheConfig } from './services/cache/cache.types.js';
-/**
- * The templates used to build the pages and loaded via the includes directory.
- */
-export type IncludesTemplates = {
-    head: string;
-    html: string;
-    seo: string;
-};
+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
@@ -58,20 +60,22 @@ export type EcoPagesAppConfig = {
      * @default "layouts"
      */
     layoutsDir: string;
-    /**
-     * The templates used for the pages
-     * @default "{head: 'head.kita.tsx', html: 'html.kita.tsx', seo: 'seo.kita.tsx'}"
-     */
-    includesTemplates: IncludesTemplates;
-    /** Error 404 page
-     * @default "404.kita.tsx"
-     */
-    error404Template: 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
      */
@@ -106,6 +110,7 @@ export type EcoPagesAppConfig = {
         config: string;
         componentsDir: string;
         distDir: string;
+        workDir: string;
         includesDir: string;
         layoutsDir: string;
         pagesDir: string;
@@ -123,11 +128,37 @@ export type EcoPagesAppConfig = {
      * 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.
      */