@ecopages/core 0.2.0-beta.6 → 0.2.0-beta.8

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

@@ -0,0 +1,78 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import {
+  createBuildInputsFingerprint,
+  hashAppConfigFile,
+  haveBuildInputsChanged
+} from "../build/build-input-fingerprint.js";
+import {
+  ROUTE_MODULE_BUILD_CACHE_FILENAME
+} from "../services/module-loading/route-module-build-manifest.js";
+import {
+  getSharedRouteModuleBuildCache,
+  getServerModuleBuildCacheOutdir
+} from "../services/module-loading/route-module-build-cache-registry.js";
+import { resolveInternalExecutionDir } from "../utils/resolve-work-dir.js";
+import {
+  collectBuildInputContributors,
+  createBuildInputsFingerprint as createBuildInputsFingerprint2,
+  didBuildInputContributorChange,
+  hashAppConfigFile as hashAppConfigFile2,
+  haveBuildInputsChanged as haveBuildInputsChanged2
+} from "../build/build-input-fingerprint.js";
+function createRouteModuleStaticRenderCacheContext(appConfig) {
+  return {
+    configHash: hashAppConfigFile(appConfig),
+    buildInputsFingerprint: createBuildInputsFingerprint(appConfig)
+  };
+}
+function shouldResetStaticExportDirectory(appConfig, force = false) {
+  if (force) {
+    return true;
+  }
+  if (haveBuildInputsChanged(appConfig)) {
+    return true;
+  }
+  const routeModuleCache = getSharedRouteModuleBuildCache(getServerModuleBuildCacheOutdir(appConfig), appConfig);
+  return !routeModuleCache.isIncrementalStaticGenerationAvailable(
+    createRouteModuleStaticRenderCacheContext(appConfig)
+  );
+}
+const PRODUCTION_BUILD_CACHE_OUTDIRS = [".server-modules", ".server-route-modules"];
+function clearProductionBuildCaches(appConfig) {
+  if (process.env.NODE_ENV !== "production") {
+    return;
+  }
+  const executionDir = resolveInternalExecutionDir(appConfig);
+  for (const subdir of PRODUCTION_BUILD_CACHE_OUTDIRS) {
+    const manifestPath = path.join(executionDir, subdir, ROUTE_MODULE_BUILD_CACHE_FILENAME);
+    if (fileSystem.exists(manifestPath)) {
+      fileSystem.remove(manifestPath);
+    }
+  }
+  const serverEntryCachePath = path.join(executionDir, ".server-entry", ROUTE_MODULE_BUILD_CACHE_FILENAME);
+  if (fileSystem.exists(serverEntryCachePath)) {
+    fileSystem.remove(serverEntryCachePath);
+  }
+  const pagesGraphCachePath = path.join(executionDir, ".server-pages-graph", ROUTE_MODULE_BUILD_CACHE_FILENAME);
+  if (fileSystem.exists(pagesGraphCachePath)) {
+    fileSystem.remove(pagesGraphCachePath);
+  }
+  for (const cache of appConfig.runtime?.routeModuleBuildCaches?.values() ?? []) {
+    cache.resetMemory();
+  }
+  appConfig.runtime?.routeModuleBuildCaches?.clear();
+  if (appConfig.runtime) {
+    appConfig.runtime.serverEntryBuildExecutor = void 0;
+  }
+}
+export {
+  clearProductionBuildCaches,
+  collectBuildInputContributors,
+  createBuildInputsFingerprint2 as createBuildInputsFingerprint,
+  createRouteModuleStaticRenderCacheContext,
+  didBuildInputContributorChange,
+  hashAppConfigFile2 as hashAppConfigFile,
+  haveBuildInputsChanged2 as haveBuildInputsChanged,
+  shouldResetStaticExportDirectory
+};

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

@@ -0,0 +1,22 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { StaticRoute } from '../types/public-types.js';
+import type { StaticGenerationRendererResolver } from '../route-renderer/route-renderer.js';
+import type { StaticGenerationRoute } from '../router/server/route-registry.js';
+type StaticGenerationRouteSource = {
+    listStaticGenerationRoutes(input: {
+        runtimeOrigin: string;
+    }): Promise<readonly StaticGenerationRoute[]>;
+};
+/**
+ * Context passed to integration plugins during static export lifecycle hooks.
+ */
+export interface StaticExportContext {
+    appConfig: EcoPagesAppConfig;
+    router: StaticGenerationRouteSource;
+    baseUrl: string;
+    routeRendererFactory?: StaticGenerationRendererResolver;
+    staticRoutes?: StaticRoute[];
+    force: boolean;
+    preserveExportDirectory: boolean;
+}
+export {};

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

@@ -2,6 +2,7 @@ import type { EcoPagesAppConfig } from '../types/internal-types.js';
 import type { StaticRoute } from '../types/public-types.js';
 import type { PageRendererResolver, StaticGenerationRendererResolver } from '../route-renderer/route-renderer.js';
 import type { StaticGenerationRoute } from '../router/server/route-registry.js';
+import type { RouteModuleBuildCache } from '../services/module-loading/route-module-build-cache.store.js';
 type StaticGenerationRouteSource = {
     listStaticGenerationRoutes(input: {
         runtimeOrigin: string;
@@ -27,26 +28,19 @@ export declare const STATIC_SITE_GENERATOR_ERRORS: {
  */
 export declare class StaticSiteGenerator {
     appConfig: EcoPagesAppConfig;
+    private readonly routeModuleBuildCacheOverride?;
+    private staticRenderCacheContext;
+    private forceFullStaticGeneration;
     /**
      * Creates the static-site generator for one app config.
      */
-    constructor({ appConfig }: {
+    constructor({ appConfig, routeModuleBuildCache, }: {
         appConfig: EcoPagesAppConfig;
+        routeModuleBuildCache?: RouteModuleBuildCache;
     });
+    private getRouteModuleBuildCache;
     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.
@@ -61,32 +55,35 @@ export declare class StaticSiteGenerator {
      */
     getDirectories(routes: string[]): string[];
     private writeStaticOutput;
-    private getStaticBuildStrategy;
+    private writeStaticPageArtifact;
+    private pruneStaleStaticOutputs;
     private createFilesystemStaticContents;
     /**
      * 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.
+     * Routes are rendered through the normal route renderer directly.
      */
-    generateStaticPages(router: StaticGenerationRouteSource, baseUrl: string, routeRendererFactory?: StaticPageRouteRendererFactory): Promise<void>;
-    private resolveStaticFetchUrl;
+    generateStaticPages(router: StaticGenerationRouteSource, baseUrl: string, routeRendererFactory?: StaticPageRouteRendererFactory, skipped?: string[], activeStaticPathnames?: Set<string>, preloadedRoutes?: readonly StaticGenerationRoute[]): Promise<void>;
+    private createStaticExportContext;
+    private invokeStaticExportHook;
     /**
      * Executes the full static-generation workflow for one app run.
      */
-    run({ router, baseUrl, routeRendererFactory, staticRoutes, }: {
+    run({ router, baseUrl, routeRendererFactory, staticRoutes, force, preserveExportDirectory, }: {
         router: StaticGenerationRouteSource;
         baseUrl: string;
         routeRendererFactory?: StaticGenerationRendererFactory;
         staticRoutes?: StaticRoute[];
+        force?: boolean;
+        preserveExportDirectory?: boolean;
     }): Promise<void>;
     /**
      * Generates static pages from explicit static routes registered via app.static().
      * These routes use eco.page views via loader functions for HMR support.
      */
     private generateExplicitStaticPages;
+    private resolveExplicitViewSourceFile;
     private generateExplicitStaticRoute;
     private planExplicitStaticRoute;
     private createExplicitStaticContents;

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

@@ -1,8 +1,14 @@
 import path from "node:path";
+import { availableParallelism } from "node:os";
 import { appLogger } from "../global/app-logger.js";
 import { fileSystem } from "@ecopages/file-system";
-import { PathUtils } from "../utils/path-utils.module.js";
 import { prepareExplicitStaticRender } from "../adapters/shared/explicit-static-render-preparation.js";
+import { createRouteModuleStaticRenderCacheContext } from "./static-build-invalidation.js";
+import {
+  getServerModuleBuildCacheOutdir,
+  getSharedRouteModuleBuildCache
+} from "../services/module-loading/route-module-build-cache-registry.js";
+import { ensurePagesUnifiedGraphBuilt, shouldBuildPagesUnifiedGraph } from "../build/pages-unified-graph-build.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}`,
@@ -10,50 +16,51 @@ const STATIC_SITE_GENERATOR_ERRORS = {
   noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`,
   dynamicRouteRequiresStaticPaths: (routePath) => `Dynamic route ${routePath} requires staticPaths to be defined on the view.`
 };
+function resolveStaticPageConcurrency() {
+  return Math.max(1, availableParallelism() - 1);
+}
+async function runWithConcurrency(items, concurrency, worker) {
+  if (items.length === 0) {
+    return;
+  }
+  const limit = Math.max(1, concurrency);
+  let nextIndex = 0;
+  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (nextIndex < items.length) {
+      const currentIndex = nextIndex++;
+      await worker(items[currentIndex]);
+    }
+  });
+  await Promise.all(runners);
+}
 class StaticSiteGenerator {
   appConfig;
+  routeModuleBuildCacheOverride;
+  staticRenderCacheContext;
+  forceFullStaticGeneration = false;
   /**
    * Creates the static-site generator for one app config.
    */
-  constructor({ appConfig }) {
+  constructor({
+    appConfig,
+    routeModuleBuildCache
+  }) {
     this.appConfig = appConfig;
+    this.routeModuleBuildCacheOverride = routeModuleBuildCache;
+    this.staticRenderCacheContext = createRouteModuleStaticRenderCacheContext(appConfig);
+  }
+  getRouteModuleBuildCache() {
+    return this.routeModuleBuildCacheOverride ?? getSharedRouteModuleBuildCache(getServerModuleBuildCacheOutdir(this.appConfig), this.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.getPageRenderer(filePath).loadPageModule(filePath, {
-      cacheScope: "static-page-probe"
-    });
-    if (module.default?.cache !== "dynamic") {
-      return false;
-    }
-    this.warnDynamicPageSkipped(filePath);
-    return true;
+    const module = await routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath);
+    return module.default?.cache === "dynamic";
   }
-  /**
-   * 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;
+  shouldSkipStaticView(_routePath, view) {
+    return view.cache === "dynamic";
   }
   /**
    * Writes the robots.txt file declared by the app config.
@@ -100,29 +107,56 @@ class StaticSiteGenerator {
     fileSystem.write(outputPath, contents);
     return outputPath;
   }
-  getStaticBuildStrategy(filePath) {
-    const ext = PathUtils.getEcoTemplateExtension(filePath);
-    const integration = this.appConfig.integrations.find((plugin) => plugin.extensions.includes(ext));
-    return integration?.staticBuildStep || "render";
+  async writeStaticPageArtifact(options) {
+    options.activeStaticPathnames?.add(options.pathname);
+    const directories = options.directories ?? this.getDirectories([options.pathname]);
+    const renderedOutputPath = this.getOutputPath(options.pathname, directories);
+    const routeModuleBuildCache = this.getRouteModuleBuildCache();
+    if (options.reuseRenderedOutput !== false && options.sourceFile && routeModuleBuildCache.canReuseStaticRender({
+      sourceFile: options.sourceFile,
+      pathname: options.pathname,
+      renderedOutputPath,
+      context: this.staticRenderCacheContext,
+      force: this.forceFullStaticGeneration
+    })) {
+      appLogger.debug(`Skipped unchanged static page: ${options.debugLabel ?? options.pathname}`);
+      return;
+    }
+    const contents = await options.createContents();
+    if (contents === null) {
+      return;
+    }
+    const outputPath = this.writeStaticOutput(options.pathname, contents, directories);
+    if (options.sourceFile) {
+      routeModuleBuildCache.recordStaticRender({
+        filePath: options.sourceFile,
+        pathname: options.pathname,
+        sourceHash: fileSystem.hash(options.sourceFile),
+        renderedOutputPath: outputPath,
+        context: this.staticRenderCacheContext
+      });
+    }
   }
-  async createFilesystemStaticContents(route, baseUrl, routeRendererFactory) {
+  pruneStaleStaticOutputs(activeStaticPathnames) {
+    const removedOutputPaths = this.getRouteModuleBuildCache().pruneStaleRenderedOutputs(activeStaticPathnames);
+    for (const outputPath of removedOutputPaths) {
+      const resolvedOutputPath = path.isAbsolute(outputPath) ? outputPath : path.resolve(outputPath);
+      if (fileSystem.exists(resolvedOutputPath)) {
+        fileSystem.remove(resolvedOutputPath);
+        appLogger.debug(`Removed stale static output: ${resolvedOutputPath}`);
+      }
+    }
+  }
+  async createFilesystemStaticContents(route, _baseUrl, routeRendererFactory, skipped) {
     const {
       templateRoute: { filePath },
       params
     } = route;
-    if (this.getStaticBuildStrategy(filePath) === "fetch") {
-      const fetchUrl = this.resolveStaticFetchUrl(route.requestUrl, baseUrl);
-      const response = await fetch(fetchUrl);
-      if (!response.ok) {
-        appLogger.error(`Failed to fetch ${fetchUrl}. Status: ${response.status}`);
-        return null;
-      }
-      return response.text();
-    }
     if (!routeRendererFactory) {
       throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
     }
     if (await this.shouldSkipStaticPageFile(filePath, routeRendererFactory)) {
+      skipped?.push(filePath);
       return null;
     }
     const renderer = routeRendererFactory.getPageRenderer(filePath);
@@ -143,42 +177,51 @@ class StaticSiteGenerator {
    * 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.
+   * Routes are rendered through the normal route renderer directly.
    */
-  async generateStaticPages(router, baseUrl, routeRendererFactory) {
-    const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
+  async generateStaticPages(router, baseUrl, routeRendererFactory, skipped, activeStaticPathnames, preloadedRoutes) {
+    const routes = preloadedRoutes ?? await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
     appLogger.debug(
       "Static Pages",
       routes.map((route) => route.requestUrl)
     );
     const directories = this.getDirectories(routes.map((route) => route.requestUrl));
-    for (const route of routes) {
+    await runWithConcurrency(routes, resolveStaticPageConcurrency(), async (route) => {
       try {
-        const contents = await this.createFilesystemStaticContents(route, baseUrl, routeRendererFactory);
-        if (contents === null) {
-          continue;
-        }
-        this.writeStaticOutput(route.pathname, contents, directories);
+        await this.writeStaticPageArtifact({
+          pathname: route.pathname,
+          sourceFile: route.templateRoute.filePath,
+          directories,
+          debugLabel: route.requestUrl,
+          activeStaticPathnames,
+          createContents: () => this.createFilesystemStaticContents(route, baseUrl, routeRendererFactory, skipped)
+        });
       } catch (error) {
         appLogger.error(
           `Error generating static page for ${route.requestUrl}:`,
           error instanceof Error ? error : String(error)
         );
       }
-    }
+    });
   }
-  resolveStaticFetchUrl(route, baseUrl) {
-    if (!route.startsWith("http://") && !route.startsWith("https://")) {
-      return `${baseUrl}${route}`;
+  createStaticExportContext(input) {
+    return {
+      appConfig: this.appConfig,
+      router: input.router,
+      baseUrl: input.baseUrl,
+      routeRendererFactory: input.routeRendererFactory,
+      staticRoutes: input.staticRoutes,
+      force: input.force,
+      preserveExportDirectory: input.preserveExportDirectory
+    };
+  }
+  async invokeStaticExportHook(hook, context) {
+    for (const integration of this.appConfig.integrations) {
+      const handler = integration[hook];
+      if (typeof handler === "function") {
+        await handler.call(integration, context);
+      }
     }
-    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.
@@ -187,19 +230,71 @@ class StaticSiteGenerator {
     router,
     baseUrl,
     routeRendererFactory,
-    staticRoutes
+    staticRoutes,
+    force = false,
+    preserveExportDirectory = false
   }) {
-    this.generateRobotsTxt();
-    await this.generateStaticPages(router, baseUrl, routeRendererFactory);
-    if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
-      await this.generateExplicitStaticPages(staticRoutes, routeRendererFactory);
+    const skippedDynamicPages = [];
+    const activeStaticPathnames = /* @__PURE__ */ new Set();
+    this.forceFullStaticGeneration = force;
+    this.staticRenderCacheContext = createRouteModuleStaticRenderCacheContext(this.appConfig);
+    if (!force) {
+      this.getRouteModuleBuildCache().ensureIncrementalStaticGenerationContext(this.staticRenderCacheContext);
+    }
+    const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
+    if (shouldBuildPagesUnifiedGraph()) {
+      await ensurePagesUnifiedGraphBuilt({
+        appConfig: this.appConfig,
+        entryPaths: routes.map((route) => route.templateRoute.filePath),
+        outdir: getServerModuleBuildCacheOutdir(this.appConfig),
+        force
+      });
+    }
+    const staticExportContext = this.createStaticExportContext({
+      router,
+      baseUrl,
+      routeRendererFactory,
+      staticRoutes,
+      force,
+      preserveExportDirectory
+    });
+    await this.invokeStaticExportHook("beforeStaticExport", staticExportContext);
+    try {
+      this.generateRobotsTxt();
+      await this.generateStaticPages(
+        router,
+        baseUrl,
+        routeRendererFactory,
+        skippedDynamicPages,
+        activeStaticPathnames,
+        routes
+      );
+      if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
+        await this.generateExplicitStaticPages(
+          staticRoutes,
+          routeRendererFactory,
+          skippedDynamicPages,
+          activeStaticPathnames
+        );
+      }
+      if (preserveExportDirectory) {
+        this.pruneStaleStaticOutputs(activeStaticPathnames);
+      }
+    } finally {
+      await this.invokeStaticExportHook("afterStaticExport", staticExportContext);
+    }
+    if (skippedDynamicPages.length > 0) {
+      appLogger.debug(
+        `Skipped ${skippedDynamicPages.length} page(s) with cache: 'dynamic' (not supported in static generation)`,
+        skippedDynamicPages
+      );
     }
   }
   /**
    * 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) {
+  async generateExplicitStaticPages(staticRoutes, routeRendererFactory, skipped, activeStaticPathnames) {
     appLogger.debug(
       "Generating explicit static routes",
       staticRoutes.map((r) => r.path)
@@ -209,9 +304,10 @@ class StaticSiteGenerator {
         const mod = await route.loader();
         const view = mod.default;
         if (this.shouldSkipStaticView(route.path, view)) {
+          skipped?.push(route.path);
           continue;
         }
-        await this.generateExplicitStaticRoute(route.path, view, routeRendererFactory);
+        await this.generateExplicitStaticRoute(route.path, view, routeRendererFactory, activeStaticPathnames);
       } catch (error) {
         appLogger.error(
           `Error generating explicit static page for ${route.path}:`,
@@ -220,18 +316,25 @@ class StaticSiteGenerator {
       }
     }
   }
-  async generateExplicitStaticRoute(routePath, view, routeRendererFactory) {
+  resolveExplicitViewSourceFile(view) {
+    const sourceFile = view.config?.__eco?.file;
+    if (!sourceFile) {
+      return void 0;
+    }
+    return path.isAbsolute(sourceFile) ? sourceFile : path.join(this.appConfig.rootDir, sourceFile);
+  }
+  async generateExplicitStaticRoute(routePath, view, routeRendererFactory, activeStaticPathnames) {
     const { renderer, routeEntries } = await this.planExplicitStaticRoute(routePath, view, routeRendererFactory);
+    const sourceFile = this.resolveExplicitViewSourceFile(view);
     for (const { pathname, params } of routeEntries) {
-      const contents = await this.createExplicitStaticContents(
-        routePath,
-        view,
-        params,
-        routeRendererFactory,
-        renderer
-      );
-      const outputPath = this.writeStaticOutput(pathname, contents);
-      appLogger.debug(`Generated static page: ${pathname} -> ${outputPath}`);
+      await this.writeStaticPageArtifact({
+        pathname,
+        sourceFile,
+        debugLabel: pathname,
+        activeStaticPathnames,
+        createContents: () => this.createExplicitStaticContents(routePath, view, params, routeRendererFactory, renderer)
+      });
+      appLogger.debug(`Generated static page: ${pathname}`);
     }
   }
   async planExplicitStaticRoute(routePath, view, routeRendererFactory) {

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

@@ -13,6 +13,7 @@ import type { SourceModuleLoader } from '../services/module-loading/module-loadi
 import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.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';
+import type { RouteModuleBuildCache } from '../services/module-loading/route-module-build-cache.store.js';
 export interface RobotsPreference {
     /**
      * The user agent
@@ -150,12 +151,19 @@ export type EcoPagesAppConfig = {
         buildAdapter?: BuildAdapter;
         buildManifest?: AppBuildManifest;
         buildExecutor?: BuildExecutor;
+        hmrBuildExecutor?: BuildExecutor;
+        routeModuleBuildExecutor?: BuildExecutor;
         devGraphService?: DevGraphService;
         entrypointDependencyGraph?: EntrypointDependencyGraph;
         hostModuleLoader?: SourceModuleLoader;
         rendererModuleContext?: unknown;
         serverInvalidationState?: ServerInvalidationState;
         serverModuleTranspiler?: ServerModuleTranspiler;
+        routeModuleBuildCaches?: Map<string, RouteModuleBuildCache>;
+        /** Serialized server-entry bundler installed by {@link getInstalledServerEntryBuildExecutor}. */
+        serverEntryBuildExecutor?: BuildExecutor;
+        /** Set after {@link setupAppRuntimePlugins} runs processor/integration setup once per process. */
+        runtimeAssetsPrepared?: boolean;
     };
     /**
      * Experimental features.

package/src/utils/parse-cli-args.d.ts

@@ -13,6 +13,7 @@ export type ReturnParseCliArgs = {
     build: boolean;
     start: boolean;
     dev: boolean;
+    force: boolean;
     port?: number;
     hostname?: string;
     reactFastRefresh?: boolean;

package/src/utils/parse-cli-args.js

@@ -7,6 +7,7 @@ function getEmbeddedRuntimeCommandOptions() {
     build: false,
     start: !isDevelopment,
     dev: isDevelopment,
+    force: false,
     port: void 0,
     hostname: void 0,
     reactFastRefresh: void 0
@@ -25,6 +26,7 @@ function parseCliArgs(options = {}) {
       dev: { type: "boolean" },
       preview: { type: "boolean" },
       build: { type: "boolean" },
+      force: { type: "boolean" },
       port: { type: "string" },
       hostname: { type: "string" },
       "react-fast-refresh": { type: "boolean" }
@@ -48,6 +50,7 @@ function parseCliArgs(options = {}) {
     build: isBuildCommand,
     start: isStartCommand,
     dev: isDevCommand,
+    force: !!values.force,
     port: values.port ? Number(values.port) : void 0,
     hostname: values.hostname,
     reactFastRefresh: values["react-fast-refresh"]

package/src/watchers/project-watcher.d.ts

@@ -133,4 +133,12 @@ export declare class ProjectWatcher {
      * rapid file changes efficiently.
      */
     createWatcherSubscription(): Promise<FSWatcher>;
+    /**
+     * Closes the active filesystem watcher subscription.
+     *
+     * @remarks
+     * Safe to call multiple times. Used when tearing down dev servers in tests
+     * and other short-lived Ecopages runtimes.
+     */
+    close(): Promise<void>;
 }