@ecopages/core 0.2.0-alpha.27 → 0.2.0-alpha.29

package/src/adapters/shared/server-static-builder.d.ts

@@ -0,0 +1,71 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { ApiHandler, StaticRoute } from '../../types/public-types.js';
+import type { RouteRegistry } from '../../router/server/route-registry.js';
+import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.js';
+import type { StaticGenerationRendererResolver } from '../../route-renderer/route-renderer.js';
+export interface StaticBuildOptions {
+    preview?: boolean;
+    baseUrl?: string;
+}
+export interface ServeOptions {
+    hostname?: string;
+    port?: number | string;
+}
+export interface ServerStaticBuilderParams {
+    appConfig: EcoPagesAppConfig;
+    staticSiteGenerator: StaticSiteGenerator;
+    serveOptions: ServeOptions;
+    apiHandlers?: ApiHandler[];
+    logger?: ServerStaticBuilderLogger;
+    previewServerFactory?: ServerStaticPreviewServerFactory;
+}
+/**
+ * Minimal logger dependency used by the static builder.
+ */
+export interface ServerStaticBuilderLogger {
+    warn(message: string, detail?: string): unknown;
+    info(message: string): unknown;
+    error(message: string): unknown;
+}
+/**
+ * Preview server factory dependency used when static preview mode is enabled.
+ */
+export interface ServerStaticPreviewServerFactory {
+    createServer(args: {
+        appConfig: EcoPagesAppConfig;
+        options: {
+            port: number;
+        };
+    }): {
+        server?: {
+            port?: number;
+        } | null;
+    };
+}
+/**
+ * Handles static site generation and previews.
+ */
+export declare class ServerStaticBuilder {
+    private readonly appConfig;
+    private readonly staticSiteGenerator;
+    private readonly serveOptions;
+    private readonly apiHandlers;
+    private readonly logger;
+    private readonly previewServerFactory;
+    constructor({ appConfig, staticSiteGenerator, serveOptions, apiHandlers, logger, previewServerFactory, }: ServerStaticBuilderParams);
+    private warnApiHandlersUnavailableInStaticMode;
+    private prepareExportDirectory;
+    private refreshRuntimeAssets;
+    /**
+     * Generates a static build of the site for deployment.
+     * @param options.preview - If true, starts a preview server after build
+     * @param dependencies.router - The initialized router
+     * @param dependencies.routeRendererFactory - The route renderer factory
+     * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
+     */
+    build(options: StaticBuildOptions | undefined, dependencies: {
+        router: RouteRegistry;
+        routeRendererFactory: StaticGenerationRendererResolver;
+        staticRoutes?: StaticRoute[];
+    }): Promise<void>;
+}

package/src/adapters/shared/server-static-builder.js

@@ -0,0 +1,100 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../config/constants.js";
+import { StaticContentServer } from "../../dev/sc-server.js";
+import { appLogger } from "../../global/app-logger.js";
+class ServerStaticBuilder {
+  appConfig;
+  staticSiteGenerator;
+  serveOptions;
+  apiHandlers;
+  logger;
+  previewServerFactory;
+  constructor({
+    appConfig,
+    staticSiteGenerator,
+    serveOptions,
+    apiHandlers,
+    logger,
+    previewServerFactory
+  }) {
+    this.appConfig = appConfig;
+    this.staticSiteGenerator = staticSiteGenerator;
+    this.serveOptions = serveOptions;
+    this.apiHandlers = apiHandlers ?? [];
+    this.logger = logger ?? appLogger;
+    this.previewServerFactory = previewServerFactory ?? StaticContentServer;
+  }
+  warnApiHandlersUnavailableInStaticMode() {
+    if (this.apiHandlers.length === 0) {
+      return;
+    }
+    const uniqueHandlers = Array.from(
+      new Set(this.apiHandlers.map((handler) => `${handler.method} ${handler.path}`))
+    );
+    const visibleHandlers = uniqueHandlers.slice(0, 5).join(", ");
+    const remainingCount = uniqueHandlers.length - Math.min(uniqueHandlers.length, 5);
+    const summary = remainingCount > 0 ? `${visibleHandlers}, +${remainingCount} more` : visibleHandlers;
+    this.logger.warn(
+      "Registered API endpoints are not available in static build or preview modes because no server runtime is started. They are excluded from the generated output.\n",
+      `\u27A4 ${summary}`
+    );
+  }
+  prepareExportDirectory() {
+    const exportDir = this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
+    fileSystem.ensureDir(exportDir, true);
+    const srcPublicDir = path.join(
+      this.appConfig.rootDir,
+      this.appConfig.srcDir ?? "src",
+      this.appConfig.publicDir ?? "public"
+    );
+    if (fileSystem.exists(srcPublicDir)) {
+      fileSystem.copyDir(srcPublicDir, exportDir);
+    }
+  }
+  async refreshRuntimeAssets() {
+    for (const processor of this.appConfig.processors.values()) {
+      await processor.setup();
+    }
+    for (const integration of this.appConfig.integrations) {
+      await integration.setup();
+    }
+  }
+  /**
+   * Generates a static build of the site for deployment.
+   * @param options.preview - If true, starts a preview server after build
+   * @param dependencies.router - The initialized router
+   * @param dependencies.routeRendererFactory - The route renderer factory
+   * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
+   */
+  async build(options, dependencies) {
+    const { preview = false, baseUrl: explicitBaseUrl } = options ?? {};
+    const baseUrl = explicitBaseUrl ?? `http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
+    this.warnApiHandlersUnavailableInStaticMode();
+    this.prepareExportDirectory();
+    await this.refreshRuntimeAssets();
+    await this.staticSiteGenerator.run({
+      router: dependencies.router,
+      baseUrl,
+      routeRendererFactory: dependencies.routeRendererFactory,
+      staticRoutes: dependencies.staticRoutes
+    });
+    if (!preview) {
+      this.logger.info("Build completed");
+      return;
+    }
+    const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
+    const { server } = this.previewServerFactory.createServer({
+      appConfig: this.appConfig,
+      options: { port: Number(previewPort) }
+    });
+    if (server?.port) {
+      this.logger.info(`Preview running at http://localhost:${server.port}`);
+    } else {
+      this.logger.error("Failed to start preview server");
+    }
+  }
+}
+export {
+  ServerStaticBuilder
+};

package/src/build/build-adapter.d.ts

@@ -0,0 +1,239 @@
+import type { EcoBuildPlugin } from './build-types.js';
+import { type AppBuildManifest } from './build-manifest.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { IHmrManager } from '../types/public-types.js';
+export { EsbuildBuildAdapter } from './esbuild-build-adapter.js';
+export type BuildOwnership = 'bun-native' | 'vite-host';
+export interface BuildLog {
+    message: string;
+}
+export interface BuildOutput {
+    path: string;
+}
+/**
+ * Dependency graph metadata produced by a build backend.
+ *
+ * @remarks
+ * This structure is runtime-neutral at the type level, but current population
+ * is Node/esbuild-only. Bun-backed builds may omit this metadata.
+ */
+export interface BuildDependencyGraph {
+    /**
+     * Normalized absolute entrypoint path mapped to all normalized absolute
+     * source inputs that contributed to that entrypoint output.
+     */
+    entrypoints: Record<string, string[]>;
+}
+export interface BuildResult {
+    success: boolean;
+    logs: BuildLog[];
+    outputs: BuildOutput[];
+    /**
+     * Optional build dependency metadata for selective invalidation.
+     *
+     * @remarks
+     * This is currently filled by the Node/esbuild adapter. Other runtimes should
+     * treat missing graph data as a valid state and fall back deterministically.
+     */
+    dependencyGraph?: BuildDependencyGraph;
+}
+export interface BuildOptions {
+    entrypoints: string[];
+    outdir?: string;
+    outbase?: string;
+    naming?: string;
+    conditions?: string[];
+    define?: Record<string, string>;
+    minify?: boolean;
+    treeshaking?: boolean;
+    target?: string;
+    format?: string;
+    sourcemap?: string;
+    splitting?: boolean;
+    root?: string;
+    bundle?: boolean;
+    externalPackages?: boolean;
+    external?: string[];
+    plugins?: EcoBuildPlugin[];
+    [key: string]: unknown;
+}
+export type BuildTranspileProfile = 'browser-script' | 'hmr-runtime' | 'hmr-entrypoint';
+export interface BuildTranspileOptions {
+    target: string;
+    format: string;
+    sourcemap: string;
+}
+export interface BuildAdapter {
+    readonly ownership?: BuildOwnership;
+    /**
+     * Executes one concrete backend build.
+     *
+     * @remarks
+     * `BuildAdapter` is the low-level backend contract. Bun-native execution owns
+     * one adapter directly; Vite-hosted execution is represented as an explicit
+     * host-owned compatibility path rather than an implicit esbuild default.
+     */
+    build(options: BuildOptions): Promise<BuildResult>;
+    resolve(importPath: string, rootDir: string): string;
+    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+}
+/**
+ * Runtime-owned facade for issuing builds.
+ *
+ * @remarks
+ * This is intentionally narrower than `BuildAdapter`. A build executor answers
+ * only the question "how should this app execute a build right now?".
+ *
+ * In Bun-native production and non-watch flows the executor is usually the
+ * adapter itself. In development watch flows the executor may be a
+ * compatibility coordinator around the Bun-native adapter while the Vite host
+ * path continues migrating toward host-owned execution.
+ */
+export interface BuildExecutor {
+    build(options: BuildOptions): Promise<BuildResult>;
+}
+export declare class BunBuildAdapter implements BuildAdapter {
+    readonly ownership: "bun-native";
+    private readonly fallbackAdapter;
+    private getPluginsForBuild;
+    private escapeRegExp;
+    private resolvePluginPath;
+    private inferLoaderFromPath;
+    private normalizeBunLoader;
+    private convertLoadResultToModuleSource;
+    private convertPluginOnLoadResult;
+    private createEcoPluginBridge;
+    private toBuildLogs;
+    private mapBunTarget;
+    private mapBunFormat;
+    private getOutputExtension;
+    private resolveConcreteOutputPath;
+    private normalizePathForMatch;
+    private normalizeOutputPathForMatch;
+    private extractTemplateHashTokens;
+    private applyTemplateHashTokens;
+    private resolveTemplatedOutputPath;
+    private relocateOutputFile;
+    private hasJavaScriptExtension;
+    private findOutputMatchForEntrypoint;
+    private normalizeBunOutputs;
+    private rewriteAliasedRuntimeSpecifiers;
+    build(options: BuildOptions): Promise<BuildResult>;
+    resolve(importPath: string, rootDir: string): string;
+    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+}
+export declare class ViteHostBuildAdapter implements BuildAdapter {
+    readonly ownership: "vite-host";
+    build(_options: BuildOptions): Promise<BuildResult>;
+    resolve(_importPath: string, _rootDir: string): string;
+    getTranspileOptions(_profile: BuildTranspileProfile): BuildTranspileOptions;
+}
+export declare function createBunBuildAdapter(): BuildAdapter;
+export declare function createViteHostBuildAdapter(): BuildAdapter;
+export declare function createBuildAdapter(options?: {
+    ownership?: BuildOwnership;
+}): BuildAdapter;
+export declare const defaultBunBuildAdapter: BuildAdapter;
+export declare const defaultViteHostBuildAdapter: BuildAdapter;
+/**
+ * Bun-native fallback export for callsites that still resolve build state
+ * globally.
+ *
+ * New app-aware code should prefer `getAppBuildAdapter()`.
+ */
+export declare const defaultBuildAdapter: BuildAdapter;
+export declare function getDefaultBuildAdapter(ownership?: BuildOwnership): BuildAdapter;
+export declare function getBuildAdapterOwnership(buildAdapter: BuildAdapter | undefined): BuildOwnership;
+export declare function getAppBuildOwnership(appConfig: EcoPagesAppConfig): BuildOwnership;
+export declare function setAppBuildOwnership(appConfig: EcoPagesAppConfig, buildOwnership: BuildOwnership): void;
+/**
+ * Returns the adapter owned by an app/runtime instance.
+ *
+ * @remarks
+ * The config builder installs an explicit adapter per app. The Bun-native
+ * fallback remains only as compatibility scaffolding for helpers that do not
+ * yet thread app runtime state explicitly.
+ */
+export declare function getAppBuildAdapter(appConfig: EcoPagesAppConfig): BuildAdapter;
+/**
+ * Installs the adapter that should serve future builds for one app instance.
+ */
+export declare function setAppBuildAdapter(appConfig: EcoPagesAppConfig, buildAdapter: BuildAdapter): void;
+/**
+ * Returns the build manifest owned by an app/runtime instance.
+ */
+export declare function getAppBuildManifest(appConfig: EcoPagesAppConfig): AppBuildManifest;
+/**
+ * Installs the build manifest that should be visible to one app instance.
+ */
+export declare function setAppBuildManifest(appConfig: EcoPagesAppConfig, buildManifest: AppBuildManifest): void;
+/**
+ * Rebuilds an app-owned manifest from config-owned loaders plus explicit
+ * runtime/browser contribution input.
+ *
+ * @remarks
+ * This keeps loader ownership with config finalization while still letting a
+ * caller supply the non-loader plugin buckets that were discovered elsewhere.
+ */
+export declare function createConfiguredAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): AppBuildManifest;
+/**
+ * Replaces the app-owned manifest using config-owned loaders and explicit
+ * contribution input.
+ */
+export declare function updateAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): void;
+/**
+ * Collects the build-facing processor and integration contributions that should
+ * be sealed into the app manifest during config finalization.
+ *
+ * @remarks
+ * This runs `prepareBuildContributions()` only. Runtime-only side effects such
+ * as HMR registration, cache prewarming, and runtime-origin wiring belong to
+ * the startup path and must not be triggered here.
+ */
+export declare function collectConfiguredAppBuildManifestContributions(appConfig: EcoPagesAppConfig): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins'>>;
+/**
+ * Runs runtime-only processor and integration setup against an already sealed
+ * app manifest.
+ *
+ * @remarks
+ * Startup paths call this after config build has finalized manifest
+ * contributions. The manifest is reused as-is; this helper only performs the
+ * runtime side effects that still need live startup context.
+ */
+export declare function setupAppRuntimePlugins(options: {
+    appConfig: EcoPagesAppConfig;
+    runtimeOrigin: string;
+    hmrManager?: IHmrManager;
+    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
+}): Promise<void>;
+export declare function getAppServerBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+/**
+ * Returns the executor owned by an app/runtime instance.
+ *
+ * @remarks
+ * The config builder seeds this with the app-owned adapter. Runtime adapters
+ * may replace it with a compatibility coordinator while keeping ownership tied
+ * to the same Bun-native backend.
+ */
+export declare function getAppBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
+/**
+ * Installs the executor that should serve future builds for one app instance.
+ */
+export declare function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void;
+/**
+ * Runs a build through the active pipeline.
+ *
+ * @remarks
+ * Callers can pass an explicit executor when builds should be routed through an
+ * app-owned development coordinator. Without one, the Bun-native default
+ * adapter is used directly.
+ */
+export declare function build(options: BuildOptions, executor?: BuildExecutor): Promise<BuildResult>;
+/**
+ * Bun-native fallback helper for callsites without app runtime context.
+ *
+ * New app-aware code should prefer `getAppTranspileOptions()`.
+ */
+export declare function getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+export declare function getAppTranspileOptions(appConfig: EcoPagesAppConfig, profile: BuildTranspileProfile): BuildTranspileOptions;