@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.41

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,35 @@
+import { attachRuntimeSpecifierAliasMap } from "./runtime-specifier-aliases.js";
+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 attachRuntimeSpecifierAliasMap(
+    {
+      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
+          };
+        });
+      }
+    },
+    specifierMap
+  );
+}
+export {
+  createRuntimeSpecifierAliasPlugin
+};

package/src/build/runtime-specifier-aliases.d.ts

@@ -0,0 +1,5 @@
+import type { EcoBuildPlugin } from './build-types.js';
+export declare function attachRuntimeSpecifierAliasMap(plugin: EcoBuildPlugin, specifierMap: ReadonlyMap<string, string>): EcoBuildPlugin;
+export declare function getRuntimeSpecifierAliasMap(plugin: EcoBuildPlugin): ReadonlyMap<string, string> | undefined;
+export declare function collectRuntimeSpecifierAliasMap(plugins: EcoBuildPlugin[] | undefined): ReadonlyMap<string, string>;
+export declare function rewriteRuntimeSpecifierAliases(code: string, specifierMap: ReadonlyMap<string, string>): string;

package/src/build/runtime-specifier-aliases.js

@@ -0,0 +1,95 @@
+import { parseSync } from "oxc-parser";
+const RUNTIME_SPECIFIER_ALIAS_MAP = /* @__PURE__ */ Symbol("ecopages.runtimeSpecifierAliasMap");
+function attachRuntimeSpecifierAliasMap(plugin, specifierMap) {
+  plugin[RUNTIME_SPECIFIER_ALIAS_MAP] = specifierMap;
+  return plugin;
+}
+function getRuntimeSpecifierAliasMap(plugin) {
+  return plugin[RUNTIME_SPECIFIER_ALIAS_MAP];
+}
+function collectRuntimeSpecifierAliasMap(plugins) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const plugin of plugins ?? []) {
+    const specifierMap = getRuntimeSpecifierAliasMap(plugin);
+    if (!specifierMap) {
+      continue;
+    }
+    for (const [specifier, mappedPath] of specifierMap.entries()) {
+      if (!merged.has(specifier)) {
+        merged.set(specifier, mappedPath);
+      }
+    }
+  }
+  return merged;
+}
+function rewriteRuntimeSpecifierAliases(code, specifierMap) {
+  if (specifierMap.size === 0) {
+    return code;
+  }
+  const edits = [];
+  try {
+    const result = parseSync("runtime-alias-output.js", code, {
+      sourceType: "module",
+      lang: "js"
+    });
+    const queueReplacement = (source) => {
+      if (typeof source.value !== "string") {
+        return;
+      }
+      const mappedPath = specifierMap.get(source.value);
+      if (!mappedPath) {
+        return;
+      }
+      const quote = code[source.start] === "'" ? "'" : '"';
+      edits.push({
+        start: source.start,
+        end: source.end,
+        replacement: `${quote}${mappedPath}${quote}`
+      });
+    };
+    const walk = (node) => {
+      if (!node || typeof node !== "object") {
+        return;
+      }
+      if (Array.isArray(node)) {
+        for (const child of node) {
+          walk(child);
+        }
+        return;
+      }
+      const candidate = node;
+      if (candidate.type === "ImportDeclaration" || candidate.type === "ExportNamedDeclaration" || candidate.type === "ExportAllDeclaration") {
+        if (candidate.source) {
+          queueReplacement(candidate.source);
+        }
+      }
+      if (candidate.type === "ImportExpression") {
+        const importNode = candidate;
+        if (importNode.source?.type === "StringLiteral" || importNode.source?.type === "Literal") {
+          queueReplacement(importNode.source);
+        }
+      }
+      for (const value of Object.values(candidate)) {
+        walk(value);
+      }
+    };
+    walk(result.program);
+  } catch {
+    return code;
+  }
+  if (edits.length === 0) {
+    return code;
+  }
+  edits.sort((left, right) => right.start - left.start);
+  let rewritten = code;
+  for (const edit of edits) {
+    rewritten = rewritten.slice(0, edit.start) + edit.replacement + rewritten.slice(edit.end);
+  }
+  return rewritten;
+}
+export {
+  attachRuntimeSpecifierAliasMap,
+  collectRuntimeSpecifierAliasMap,
+  getRuntimeSpecifierAliasMap,
+  rewriteRuntimeSpecifierAliases
+};

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 {};