@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.51

package/src/build/runtime-build-executor.js

@@ -0,0 +1,22 @@
+import {
+  getAppBuildAdapter,
+  getAppBuildExecutor,
+  getAppBuildOwnership,
+  getAppServerBuildPlugins,
+  setAppBuildExecutor
+} from "./build-adapter.js";
+import { createOrReuseAppBuildExecutor, withBuildExecutorPlugins } from "./dev-build-coordinator.js";
+function installAppRuntimeBuildExecutor(appConfig, options) {
+  const buildOwnership = getAppBuildOwnership(appConfig);
+  const buildExecutor = buildOwnership === "bun-native" ? createOrReuseAppBuildExecutor({
+    development: options.development,
+    adapter: getAppBuildAdapter(appConfig),
+    currentExecutor: getAppBuildExecutor(appConfig),
+    getPlugins: () => getAppServerBuildPlugins(appConfig)
+  }) : withBuildExecutorPlugins(getAppBuildAdapter(appConfig), () => getAppServerBuildPlugins(appConfig));
+  setAppBuildExecutor(appConfig, buildExecutor);
+  return buildExecutor;
+}
+export {
+  installAppRuntimeBuildExecutor
+};

package/src/build/runtime-specifier-alias-plugin.d.ts

@@ -0,0 +1,15 @@
+import type { EcoBuildPlugin } from './build-types.js';
+type RuntimeSpecifierMap = ReadonlyMap<string, string> | Record<string, string>;
+/**
+ * Creates a build plugin that aliases runtime bare specifiers to concrete URLs.
+ *
+ * @remarks
+ * This helper is used when browser-target builds must preserve integration-owned
+ * runtime specifier semantics while letting the bundler treat the mapped URLs as
+ * external runtime assets.
+ */
+export declare function createRuntimeSpecifierAliasPlugin(specifierMapInput: RuntimeSpecifierMap, options?: {
+    name?: string;
+    external?: boolean;
+}): EcoBuildPlugin | null;
+export {};

package/src/build/runtime-specifier-alias-plugin.js

@@ -0,0 +1,31 @@
+function toRuntimeSpecifierMap(specifierMap) {
+  return specifierMap instanceof Map ? specifierMap : new Map(Object.entries(specifierMap));
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function createRuntimeSpecifierAliasPlugin(specifierMapInput, options) {
+  const specifierMap = toRuntimeSpecifierMap(specifierMapInput);
+  if (specifierMap.size === 0) {
+    return null;
+  }
+  const filter = new RegExp(`^(${Array.from(specifierMap.keys()).map(escapeRegExp).join("|")})$`);
+  return {
+    name: options?.name ?? "runtime-specifier-alias",
+    setup(build) {
+      build.onResolve({ filter }, (args) => {
+        const mappedPath = specifierMap.get(args.path);
+        if (!mappedPath) {
+          return void 0;
+        }
+        return {
+          path: mappedPath,
+          external: options?.external ?? true
+        };
+      });
+    }
+  };
+}
+export {
+  createRuntimeSpecifierAliasPlugin
+};

package/src/config/README.md

@@ -0,0 +1,36 @@
+# Config Layer
+
+This directory contains the app-configuration finalization path for Ecopages.
+
+## Purpose
+
+The config layer answers one question:
+
+How does one `eco.config.ts` become one stable, app-owned runtime/build configuration?
+
+It is responsible for:
+
+- validating integration, processor, and loader registration
+- resolving semantic paths such as `html` and `404` templates
+- selecting explicit build ownership and creating app-owned runtime state such as the build adapter, build executor, build manifest, dev graph service, and remaining compatibility-only runtime state
+- enforcing runtime capability requirements before startup
+- carrying host-injected runtime dependencies only through abstract slots such as host module loaders, never through bundler-specific core defaults
+
+## Main Files
+
+- `config-builder.ts`: the primary builder and config finalization boundary
+- `config-builder.test.ts`: coverage for validation, path resolution, and runtime capability checks
+
+## Ownership Rules
+
+- Integrations and processors declare contributions.
+- `ConfigBuilder.build()` decides ordering, validates compatibility, and seals build ownership for the finalized app config.
+- Runtime startup reuses finalized config/build state; it should not recompute manifest ownership.
+
+Bun-native is the default ownership path. Vite-host ownership is explicit and should be selected during config construction when a host-driven compatibility flow must avoid silently falling back to Bun build execution.
+
+## Output
+
+The result of this layer is a built `EcoPagesAppConfig` with resolved absolute paths and app-owned runtime services attached under `appConfig.runtime`.
+
+That built config is then consumed by server adapters, static generation, route rendering, and HMR.

package/src/config/config-builder.d.ts

@@ -2,11 +2,13 @@
  * This module contains the ConfigBuilder class, which is used to build the EcoPagesAppConfig object.
  * @module
  */
+import { type BuildOwnership } from '../build/build-adapter.js';
 import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { EcoPagesAppConfig, IncludesTemplates, RobotsPreference } from '../internal-types.js';
-import type { IntegrationPlugin } from '../plugins/integration-plugin.js';
+import type { EcoPagesAppConfig, RobotsPreference } from '../types/internal-types.js';
+import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
 import type { Processor } from '../plugins/processor.js';
-import type { PageMetadataProps } from '../public-types.js';
+import type { EcoSourceTransform } from '../plugins/source-transform.js';
+import type { PageMetadataProps } from '../types/public-types.js';
 import type { CacheConfig } from '../services/cache/cache.types.js';
 export declare const CONFIG_BUILDER_ERRORS: {
     readonly DUPLICATE_INTEGRATION_NAMES: "Integrations names must be unique";
@@ -14,21 +16,17 @@ export declare const CONFIG_BUILDER_ERRORS: {
     readonly MIXED_JSX_ENGINES: "Both kitajs and react integrations are enabled. Use per-file JSX import source/pragma consistently (e.g. `/** @jsxImportSource react */` for React files and `/** @jsxImportSource @kitajs/html */` for Kita files).";
     readonly duplicateProcessorName: (name: string) => string;
     readonly duplicateLoaderName: (name: string) => string;
+    readonly duplicateSemanticTemplate: (kind: "html" | "404", matches: string[]) => string;
+    readonly incompatibleRuntimeCapability: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, reason: string) => string;
+    readonly unsupportedRuntimeVersion: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, current: string, min: string) => string;
+    readonly invalidRuntimeVersion: (kind: "integration" | "processor", name: string, version: string) => string;
 };
+type RuntimeKind = 'node' | 'bun';
 /**
  * A builder class for creating and configuring EcoPages application configuration.
  * Provides a fluent interface for setting various configuration options and managing
  * application settings.
  *
- * @example
- * ```typescript
- * const config = new ConfigBuilder()
- *   .setBaseUrl('https://example.com')
- *   .setRootDir('./myproject')
- *   .setSrcDir('source')
- *   .build();
- * ```
- *
  * @remarks
  * The ConfigBuilder follows the builder pattern and allows for:
  * - Setting directory paths for various components (pages, includes, layouts, etc.)
@@ -46,6 +44,7 @@ export declare const CONFIG_BUILDER_ERRORS: {
  * @throws {Error} When adding duplicate processors or loaders
  */
 export declare class ConfigBuilder {
+    private buildOwnership;
     config: EcoPagesAppConfig;
     /**
      * Sets the base URL for the application.
@@ -63,6 +62,15 @@ export declare class ConfigBuilder {
      * @returns The ConfigBuilder instance for method chaining
      */
     setRootDir(rootDir: string): this;
+    /**
+     * Sets which runtime path owns build execution for the finalized app config.
+     *
+     * @remarks
+     * Bun-native remains the default. Vite-host ownership should be selected only
+     * for host-driven compatibility flows where core must not silently fall back to
+     * Bun build execution.
+     */
+    setBuildOwnership(buildOwnership: BuildOwnership): this;
     /**
      * Sets the source directory relative to the root directory.
      * This directory contains all the source files for the application.
@@ -111,21 +119,6 @@ export declare class ConfigBuilder {
      * @returns The ConfigBuilder instance for method chaining
      */
     setPublicDir(publicDir: string): this;
-    /**
-     * Sets the templates used for includes.
-     * These templates are used to build the HTML structure of pages.
-     *
-     * @param includesTemplates - An object containing the template file names
-     * @returns The ConfigBuilder instance for method chaining
-     */
-    setIncludesTemplates(includesTemplates: IncludesTemplates): this;
-    /**
-     * Sets the template file for the 404 error page.
-     *
-     * @param error404Template - The file name of the 404 error template (default: '404.ghtml.ts')
-     * @returns The ConfigBuilder instance for method chaining
-     */
-    setError404Template(error404Template: string): this;
     /**
      * Sets the robots.txt configuration.
      * This determines which paths are allowed/disallowed for search engines.
@@ -143,14 +136,26 @@ export declare class ConfigBuilder {
      * @param integrations - An array of integration plugins
      * @returns The ConfigBuilder instance for method chaining
      */
-    setIntegrations(integrations: IntegrationPlugin<unknown>[]): this;
+    setIntegrations(integrations: AnyIntegrationPlugin[]): this;
     /**
      * Sets the output directory for the built application.
      *
-     * @param distDir - The distribution directory name (default: '.eco')
+     * @param distDir - The distribution directory name (default: 'dist')
      * @returns The ConfigBuilder instance for method chaining
      */
     setDistDir(distDir: string): this;
+    /**
+     * Sets the internal work directory for runtime-only artifacts.
+     *
+     * @remarks
+     * Use this when deployable output should stay clean while Ecopages still
+     * needs a separate workspace for server transpilation caches, runtime
+     * manifests, and other internal build products.
+     *
+     * @param workDir - The internal work directory name
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setWorkDir(workDir: string): this;
     /**
      * Sets the default metadata for pages.
      * This is used when a page doesn't specify its own metadata.
@@ -190,6 +195,11 @@ export declare class ConfigBuilder {
      * @returns The ConfigBuilder instance for method chaining
      */
     setLoaders(loaders: EcoBuildPlugin[]): this;
+    /**
+     * Sets the source transforms to use for transform-first bundlers such as Vite.
+     * This replaces any existing source transforms.
+     */
+    setSourceTransforms(sourceTransforms: EcoSourceTransform[]): this;
     /**
      * Adds a loader to the application.
      *
@@ -199,6 +209,12 @@ export declare class ConfigBuilder {
      * @throws Error if a loader with the same name already exists
      */
     addLoader(name: string, loader: EcoBuildPlugin): this;
+    /**
+     * Adds a source transform to the application.
+     *
+     * @throws Error if a source transform with the same name already exists.
+     */
+    addSourceTransform(name: string, sourceTransform: EcoSourceTransform): this;
     /**
      * Sets the cache configuration for ISR and page caching.
      *
@@ -208,8 +224,16 @@ export declare class ConfigBuilder {
     setCacheConfig(cacheConfig: CacheConfig): this;
     setExperimental(experimental: NonNullable<EcoPagesAppConfig['experimental']>): this;
     private createAbsolutePaths;
+    private resolveSemanticTemplatePath;
     private createIntegrationTemplatesExt;
     private initializeProcessors;
+    private validateRuntimeCapabilities;
+    private validateRuntimeCapability;
+    private detectRuntimeEnvironment;
+    private getBunVersion;
+    private describeUnsupportedRuntimeTag;
+    private parseVersion;
+    private compareVersions;
     /**
      * Initializes default loaders that are required for EcoPages to function.
      * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
@@ -225,3 +249,4 @@ export declare class ConfigBuilder {
      */
     build(): Promise<EcoPagesAppConfig>;
 }
+export {};