@ecopages/core 0.2.0-alpha.1

package/src/plugins/integration-plugin.d.ts

@@ -0,0 +1,102 @@
+import type { EcoBuildPlugin } from '../build/build-types';
+import type { EcoPagesAppConfig, IHmrManager } from '../internal-types';
+import type { HmrStrategy } from '../hmr/hmr-strategy';
+import type { EcoComponent, EcoPagesElement } from '../public-types';
+import type { IntegrationRenderer } from '../route-renderer/integration-renderer';
+import { AssetProcessingService } from '../services/asset-processing-service/asset-processing.service';
+import type { AssetDefinition, ProcessedAsset } from '../services/asset-processing-service/assets.types';
+export declare const INTEGRATION_PLUGIN_ERRORS: {
+    readonly NOT_INITIALIZED_WITH_APP_CONFIG: "Plugin not initialized with app config";
+    readonly NOT_INITIALIZED_WITH_ASSET_SERVICE: "Plugin not initialized with asset dependency service";
+};
+export interface IntegrationPluginConfig {
+    /**
+     * The name of the integration plugin.
+     */
+    name: string;
+    /**
+     * The extensions that this plugin supports (e.g., ['.kita.js', '.kita.tsx']).
+     */
+    extensions: string[];
+    /**
+     * The dependencies that this plugin requires on a global level.
+     * These dependencies will be resolved during the setup process and injected into the global scope of the application.
+     * They are not specific to any particular page or component.
+     */
+    integrationDependencies?: AssetDefinition[];
+    /**
+     * The strategy to use for static building.
+     * - 'render': Execute component function directly (faster, efficient).
+     * - 'fetch': Start server and fetch URL (slower, needed for some SSR like Lit).
+     * @default 'render'
+     */
+    staticBuildStep?: 'render' | 'fetch';
+}
+/**
+ * Metadata used by integration-owned boundary policy.
+ *
+ * This payload describes the currently active integration pass together with the
+ * target component boundary being entered.
+ */
+export type ComponentBoundaryPolicyInput = {
+    currentIntegration: string;
+    targetIntegration?: string;
+    component: EcoComponent;
+};
+type RendererClass<C> = new (options: {
+    appConfig: EcoPagesAppConfig;
+    assetProcessingService: AssetProcessingService;
+    resolvedIntegrationDependencies: ProcessedAsset[];
+    runtimeOrigin: string;
+}) => IntegrationRenderer<C>;
+export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
+    readonly name: string;
+    readonly extensions: string[];
+    abstract renderer: RendererClass<C>;
+    readonly staticBuildStep: 'render' | 'fetch';
+    protected integrationDependencies: AssetDefinition[];
+    protected resolvedIntegrationDependencies: ProcessedAsset[];
+    protected options?: Record<string, unknown>;
+    protected appConfig?: EcoPagesAppConfig;
+    protected assetProcessingService?: AssetProcessingService;
+    protected hmrManager?: IHmrManager;
+    runtimeOrigin: string;
+    get plugins(): EcoBuildPlugin[];
+    constructor(config: IntegrationPluginConfig);
+    setConfig(appConfig: EcoPagesAppConfig): void;
+    setRuntimeOrigin(runtimeOrigin: string): void;
+    /**
+     * Returns an HMR strategy for this integration, if applicable.
+     * The strategy will be registered with the HmrManager during initialization.
+     *
+     * @returns HmrStrategy instance or undefined if no custom HMR handling needed
+     *
+     * @example
+     * ```typescript
+     * getHmrStrategy(): HmrStrategy {
+     *   const context = this.hmrManager!.getDefaultContext();
+     *   return new ReactHmrStrategy(context);
+     * }
+     * ```
+     */
+    getHmrStrategy?(): HmrStrategy | undefined;
+    setHmrManager(hmrManager: IHmrManager): void;
+    initializeAssetDefinitionService(): void;
+    getResolvedIntegrationDependencies(): ProcessedAsset[];
+    initializeRenderer(): IntegrationRenderer<C>;
+    /**
+     * Declares whether a component boundary targeting this integration should be
+     * deferred through the marker pipeline.
+     *
+     * The default implementation never defers. Integrations that require deferred
+     * subtree rendering should override this method and return `true` when their
+     * boundary must be resolved during the marker graph stage.
+     *
+     * @param input Boundary metadata for the current render pass.
+     * @returns `true` when the boundary should be deferred; otherwise `false`.
+     */
+    shouldDeferComponentBoundary(_input: ComponentBoundaryPolicyInput): boolean;
+    setup(): Promise<void>;
+    teardown(): Promise<void>;
+}
+export {};

package/src/plugins/integration-plugin.js

@@ -0,0 +1,100 @@
+import { AssetProcessingService } from "../services/asset-processing-service/asset-processing.service";
+const INTEGRATION_PLUGIN_ERRORS = {
+  NOT_INITIALIZED_WITH_APP_CONFIG: "Plugin not initialized with app config",
+  NOT_INITIALIZED_WITH_ASSET_SERVICE: "Plugin not initialized with asset dependency service"
+};
+class IntegrationPlugin {
+  name;
+  extensions;
+  staticBuildStep;
+  integrationDependencies;
+  resolvedIntegrationDependencies = [];
+  options;
+  appConfig;
+  assetProcessingService;
+  hmrManager;
+  get plugins() {
+    return [];
+  }
+  constructor(config) {
+    this.name = config.name;
+    this.extensions = config.extensions;
+    this.integrationDependencies = config.integrationDependencies || [];
+    this.staticBuildStep = config.staticBuildStep || "render";
+  }
+  setConfig(appConfig) {
+    this.appConfig = appConfig;
+    this.initializeAssetDefinitionService();
+  }
+  setRuntimeOrigin(runtimeOrigin) {
+    this.runtimeOrigin = runtimeOrigin;
+  }
+  setHmrManager(hmrManager) {
+    this.hmrManager = hmrManager;
+    const strategy = this.getHmrStrategy?.();
+    if (strategy) {
+      hmrManager.registerStrategy(strategy);
+    }
+    if (this.assetProcessingService) {
+      this.assetProcessingService.setHmrManager(hmrManager);
+    }
+  }
+  initializeAssetDefinitionService() {
+    if (!this.appConfig) throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
+    this.assetProcessingService = AssetProcessingService.createWithDefaultProcessors(this.appConfig);
+    if (this.hmrManager) {
+      this.assetProcessingService.setHmrManager(this.hmrManager);
+    }
+  }
+  getResolvedIntegrationDependencies() {
+    return this.resolvedIntegrationDependencies;
+  }
+  initializeRenderer() {
+    if (!this.appConfig) {
+      throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
+    }
+    const assetProcessingService = AssetProcessingService.createWithDefaultProcessors(this.appConfig);
+    if (this.hmrManager) {
+      assetProcessingService.setHmrManager(this.hmrManager);
+    }
+    const renderer = new this.renderer({
+      appConfig: this.appConfig,
+      assetProcessingService,
+      resolvedIntegrationDependencies: this.resolvedIntegrationDependencies,
+      runtimeOrigin: this.runtimeOrigin
+    });
+    if (this.hmrManager) {
+      renderer.setHmrManager(this.hmrManager);
+    }
+    return renderer;
+  }
+  /**
+   * Declares whether a component boundary targeting this integration should be
+   * deferred through the marker pipeline.
+   *
+   * The default implementation never defers. Integrations that require deferred
+   * subtree rendering should override this method and return `true` when their
+   * boundary must be resolved during the marker graph stage.
+   *
+   * @param input Boundary metadata for the current render pass.
+   * @returns `true` when the boundary should be deferred; otherwise `false`.
+   */
+  shouldDeferComponentBoundary(_input) {
+    return false;
+  }
+  async setup() {
+    if (this.integrationDependencies.length === 0) return;
+    if (!this.assetProcessingService) throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_ASSET_SERVICE);
+    this.resolvedIntegrationDependencies = await this.assetProcessingService.processDependencies(
+      this.integrationDependencies,
+      this.name
+    );
+    this.initializeRenderer();
+  }
+  async teardown() {
+  }
+}
+export {
+  INTEGRATION_PLUGIN_ERRORS,
+  IntegrationPlugin
+};

package/src/plugins/integration-plugin.ts

@@ -0,0 +1,184 @@
+import type { EcoBuildPlugin } from '../build/build-types';
+import type { EcoPagesAppConfig, IHmrManager } from '../internal-types';
+import type { HmrStrategy } from '../hmr/hmr-strategy';
+import type { EcoComponent, EcoPagesElement } from '../public-types';
+import type { IntegrationRenderer } from '../route-renderer/integration-renderer';
+import { AssetProcessingService } from '../services/asset-processing-service/asset-processing.service';
+import type { AssetDefinition, ProcessedAsset } from '../services/asset-processing-service/assets.types';
+
+export const INTEGRATION_PLUGIN_ERRORS = {
+	NOT_INITIALIZED_WITH_APP_CONFIG: 'Plugin not initialized with app config',
+	NOT_INITIALIZED_WITH_ASSET_SERVICE: 'Plugin not initialized with asset dependency service',
+} as const;
+
+export interface IntegrationPluginConfig {
+	/**
+	 * The name of the integration plugin.
+	 */
+	name: string;
+	/**
+	 * The extensions that this plugin supports (e.g., ['.kita.js', '.kita.tsx']).
+	 */
+	extensions: string[];
+	/**
+	 * The dependencies that this plugin requires on a global level.
+	 * These dependencies will be resolved during the setup process and injected into the global scope of the application.
+	 * They are not specific to any particular page or component.
+	 */
+	integrationDependencies?: AssetDefinition[];
+	/**
+	 * The strategy to use for static building.
+	 * - 'render': Execute component function directly (faster, efficient).
+	 * - 'fetch': Start server and fetch URL (slower, needed for some SSR like Lit).
+	 * @default 'render'
+	 */
+	staticBuildStep?: 'render' | 'fetch';
+}
+
+/**
+ * Metadata used by integration-owned boundary policy.
+ *
+ * This payload describes the currently active integration pass together with the
+ * target component boundary being entered.
+ */
+export type ComponentBoundaryPolicyInput = {
+	currentIntegration: string;
+	targetIntegration?: string;
+	component: EcoComponent;
+};
+
+type RendererClass<C> = new (options: {
+	appConfig: EcoPagesAppConfig;
+	assetProcessingService: AssetProcessingService;
+	resolvedIntegrationDependencies: ProcessedAsset[];
+	runtimeOrigin: string;
+}) => IntegrationRenderer<C>;
+
+export abstract class IntegrationPlugin<C = EcoPagesElement> {
+	readonly name: string;
+	readonly extensions: string[];
+	abstract renderer: RendererClass<C>;
+	readonly staticBuildStep: 'render' | 'fetch';
+
+	protected integrationDependencies: AssetDefinition[];
+	protected resolvedIntegrationDependencies: ProcessedAsset[] = [];
+	protected options?: Record<string, unknown>;
+	protected appConfig?: EcoPagesAppConfig;
+	protected assetProcessingService?: AssetProcessingService;
+	protected hmrManager?: IHmrManager;
+	declare runtimeOrigin: string;
+
+	get plugins(): EcoBuildPlugin[] {
+		return [];
+	}
+
+	constructor(config: IntegrationPluginConfig) {
+		this.name = config.name;
+		this.extensions = config.extensions;
+		this.integrationDependencies = config.integrationDependencies || [];
+		this.staticBuildStep = config.staticBuildStep || 'render';
+	}
+
+	setConfig(appConfig: EcoPagesAppConfig): void {
+		this.appConfig = appConfig;
+		this.initializeAssetDefinitionService();
+	}
+
+	setRuntimeOrigin(runtimeOrigin: string) {
+		this.runtimeOrigin = runtimeOrigin;
+	}
+
+	/**
+	 * Returns an HMR strategy for this integration, if applicable.
+	 * The strategy will be registered with the HmrManager during initialization.
+	 *
+	 * @returns HmrStrategy instance or undefined if no custom HMR handling needed
+	 *
+	 * @example
+	 * ```typescript
+	 * getHmrStrategy(): HmrStrategy {
+	 *   const context = this.hmrManager!.getDefaultContext();
+	 *   return new ReactHmrStrategy(context);
+	 * }
+	 * ```
+	 */
+	getHmrStrategy?(): HmrStrategy | undefined;
+
+	setHmrManager(hmrManager: IHmrManager) {
+		this.hmrManager = hmrManager;
+
+		const strategy = this.getHmrStrategy?.();
+		if (strategy) {
+			hmrManager.registerStrategy(strategy);
+		}
+
+		if (this.assetProcessingService) {
+			this.assetProcessingService.setHmrManager(hmrManager);
+		}
+	}
+
+	initializeAssetDefinitionService(): void {
+		if (!this.appConfig) throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
+
+		this.assetProcessingService = AssetProcessingService.createWithDefaultProcessors(this.appConfig);
+		if (this.hmrManager) {
+			this.assetProcessingService.setHmrManager(this.hmrManager);
+		}
+	}
+
+	getResolvedIntegrationDependencies(): ProcessedAsset[] {
+		return this.resolvedIntegrationDependencies;
+	}
+
+	initializeRenderer(): IntegrationRenderer<C> {
+		if (!this.appConfig) {
+			throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
+		}
+
+		const assetProcessingService = AssetProcessingService.createWithDefaultProcessors(this.appConfig);
+		if (this.hmrManager) {
+			assetProcessingService.setHmrManager(this.hmrManager);
+		}
+
+		const renderer = new this.renderer({
+			appConfig: this.appConfig,
+			assetProcessingService,
+			resolvedIntegrationDependencies: this.resolvedIntegrationDependencies,
+			runtimeOrigin: this.runtimeOrigin,
+		});
+
+		if (this.hmrManager) {
+			renderer.setHmrManager(this.hmrManager);
+		}
+
+		return renderer;
+	}
+
+	/**
+	 * Declares whether a component boundary targeting this integration should be
+	 * deferred through the marker pipeline.
+	 *
+	 * The default implementation never defers. Integrations that require deferred
+	 * subtree rendering should override this method and return `true` when their
+	 * boundary must be resolved during the marker graph stage.
+	 *
+	 * @param input Boundary metadata for the current render pass.
+	 * @returns `true` when the boundary should be deferred; otherwise `false`.
+	 */
+	shouldDeferComponentBoundary(_input: ComponentBoundaryPolicyInput): boolean {
+		return false;
+	}
+
+	async setup(): Promise<void> {
+		if (this.integrationDependencies.length === 0) return;
+		if (!this.assetProcessingService) throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_ASSET_SERVICE);
+
+		this.resolvedIntegrationDependencies = await this.assetProcessingService.processDependencies(
+			this.integrationDependencies,
+			this.name,
+		);
+
+		this.initializeRenderer();
+	}
+	async teardown(): Promise<void> {}
+}

package/src/plugins/processor.d.ts

@@ -0,0 +1,82 @@
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoPagesAppConfig, IClientBridge } from '../internal-types';
+import type { AssetDefinition } from '../services/asset-processing-service';
+export declare const PROCESSOR_ERRORS: {
+    readonly CACHE_DIRECTORY_NOT_SET: "Cache directory not set in context";
+};
+export interface ProcessorWatchContext {
+    path: string;
+    bridge: IClientBridge;
+}
+export interface ProcessorWatchConfig {
+    paths: string[];
+    extensions?: string[];
+    onCreate?: (ctx: ProcessorWatchContext) => Promise<void>;
+    onChange?: (ctx: ProcessorWatchContext) => Promise<void>;
+    onDelete?: (ctx: ProcessorWatchContext) => Promise<void>;
+    onError?: (error: Error) => void;
+}
+export type ProcessorAssetKind = 'script' | 'stylesheet' | 'image';
+export type ProcessorExtensionPattern = string;
+export interface ProcessorAssetCapability {
+    kind: ProcessorAssetKind;
+    /**
+     * Supported patterns:
+     * - `*` (all extensions)
+     * - `.css` or `css`
+     * - `*.css`
+     * - `*.{css,scss,sass}`
+     *
+     * Pattern matching is case-insensitive and trims surrounding spaces,
+     * including grouped values (e.g. `*.{ CSS, ScSs }`).
+     */
+    extensions?: ProcessorExtensionPattern[];
+}
+export interface ProcessorConfig<TOptions = Record<string, unknown>> {
+    name: string;
+    description?: string;
+    options?: TOptions;
+    watch?: ProcessorWatchConfig;
+    capabilities?: ProcessorAssetCapability[];
+}
+export interface ProcessorContext {
+    config: EcoPagesAppConfig;
+    rootDir: string;
+    srcDir: string;
+    distDir: string;
+    cache?: string;
+}
+/**
+ * Interface for processor build plugins
+ * This is used to pass plugins to the build process directly from the processor
+ * For instance it can become very handy when dealing with virtual modules that needs to be recognized by the bundler
+ * i.e. @ecopages/image-processor
+ */
+export declare abstract class Processor<TOptions = Record<string, unknown>> {
+    readonly name: string;
+    protected dependencies: AssetDefinition[];
+    protected context?: ProcessorContext;
+    protected options?: TOptions;
+    protected watchConfig?: ProcessorWatchConfig;
+    protected capabilities: ProcessorAssetCapability[];
+    /** Plugins that are only used during the build process */
+    abstract buildPlugins?: EcoBuildPlugin[];
+    /** Plugins that are used during runtime for file processing */
+    abstract plugins?: EcoBuildPlugin[];
+    constructor(config: ProcessorConfig<TOptions>);
+    setContext(appConfig: EcoPagesAppConfig): void;
+    abstract setup(): Promise<void>;
+    abstract teardown(): Promise<void>;
+    abstract process(input: unknown, filePath?: string): Promise<unknown>;
+    protected getCachePath(key: string): string;
+    protected readCache<T>(key: string): Promise<T | null>;
+    protected writeCache<T>(key: string, data: T): Promise<void>;
+    getWatchConfig(): ProcessorWatchConfig | undefined;
+    getDependencies(): AssetDefinition[];
+    getName(): string;
+    getAssetCapabilities(): ProcessorAssetCapability[];
+    matchesFileFilter(_filepath: string): boolean;
+    canProcessAsset(kind: ProcessorAssetKind, filepath?: string): boolean;
+    private matchesCapabilityExtensions;
+    private normalizeExtensionPattern;
+}

package/src/plugins/processor.js

@@ -0,0 +1,122 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { GENERATED_BASE_PATHS } from "../constants";
+const PROCESSOR_ERRORS = {
+  CACHE_DIRECTORY_NOT_SET: "Cache directory not set in context"
+};
+function resolveGeneratedPath(type, options) {
+  const { root, module, subPath } = options;
+  const parts = [root, GENERATED_BASE_PATHS[type], module, subPath].filter(Boolean);
+  return path.join(...parts);
+}
+class Processor {
+  name;
+  dependencies = [];
+  context;
+  options;
+  watchConfig;
+  capabilities = [];
+  constructor(config) {
+    this.name = config.name;
+    this.options = config.options;
+    this.watchConfig = config.watch;
+    this.capabilities = config.capabilities ?? [];
+  }
+  setContext(appConfig) {
+    const cachePath = resolveGeneratedPath("cache", {
+      root: appConfig.absolutePaths.distDir,
+      module: this.name
+    });
+    fileSystem.ensureDir(cachePath);
+    this.context = {
+      config: appConfig,
+      rootDir: appConfig.rootDir,
+      srcDir: appConfig.absolutePaths.srcDir,
+      distDir: appConfig.absolutePaths.distDir,
+      cache: cachePath
+    };
+  }
+  getCachePath(key) {
+    return `${this.context?.cache}/${key}`;
+  }
+  async readCache(key) {
+    const cachePath = this.getCachePath(key);
+    try {
+      const data = await fileSystem.readFile(cachePath);
+      return JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+  async writeCache(key, data) {
+    if (!this.context?.cache) {
+      throw new Error(PROCESSOR_ERRORS.CACHE_DIRECTORY_NOT_SET);
+    }
+    const cachePath = this.getCachePath(key);
+    fileSystem.write(cachePath, JSON.stringify(data, null, 2));
+  }
+  getWatchConfig() {
+    return this.watchConfig;
+  }
+  getDependencies() {
+    return this.dependencies;
+  }
+  getName() {
+    return this.name;
+  }
+  getAssetCapabilities() {
+    return this.capabilities;
+  }
+  matchesFileFilter(_filepath) {
+    return true;
+  }
+  canProcessAsset(kind, filepath) {
+    const capabilities = this.getAssetCapabilities();
+    if (capabilities.length === 0) {
+      return false;
+    }
+    const matchingKind = capabilities.filter((capability) => capability.kind === kind);
+    if (matchingKind.length === 0) {
+      return false;
+    }
+    if (!filepath) {
+      return true;
+    }
+    return matchingKind.some((capability) => this.matchesCapabilityExtensions(filepath, capability.extensions));
+  }
+  matchesCapabilityExtensions(filepath, extensions) {
+    if (!extensions || extensions.length === 0) {
+      return true;
+    }
+    const normalizedExt = path.extname(filepath).toLowerCase();
+    return extensions.some((rawPattern) => {
+      const pattern = this.normalizeExtensionPattern(rawPattern);
+      if (!pattern) {
+        return false;
+      }
+      if (pattern === "*") {
+        return true;
+      }
+      const groupedMatch = pattern.match(/^\*\.\{(.+)\}$/);
+      if (groupedMatch) {
+        const groupItems = groupedMatch[1].split(",").map((item) => this.normalizeExtensionPattern(item)).filter(Boolean);
+        return groupItems.some((item) => normalizedExt === item || normalizedExt === `.${item}`);
+      }
+      if (pattern.startsWith("*")) {
+        const suffix = pattern.slice(1);
+        return normalizedExt.endsWith(suffix);
+      }
+      if (pattern.startsWith(".")) {
+        return normalizedExt === pattern;
+      }
+      return normalizedExt === `.${pattern}`;
+    });
+  }
+  normalizeExtensionPattern(rawPattern) {
+    return rawPattern.trim().toLowerCase();
+  }
+}
+export {
+  PROCESSOR_ERRORS,
+  Processor
+};