@ecopages/core 0.2.0-alpha.8 → 0.2.1

package/src/plugins/integration-plugin.ts

@@ -1,226 +0,0 @@
-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/orchestration/integration-renderer';
-import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service';
-import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types';
-import type { RuntimeCapabilityDeclaration } from './runtime-capability.ts';
-
-export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.ts';
-
-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';
-	/**
-	 * Declares runtime-specific requirements that must be satisfied before the
-	 * app can start with this integration enabled.
-	 */
-	runtimeCapability?: RuntimeCapabilityDeclaration;
-}
-
-/**
- * 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';
-	readonly runtimeCapability?: RuntimeCapabilityDeclaration;
-
-	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';
-		this.runtimeCapability = config.runtimeCapability;
-	}
-
-	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;
-
-	/**
-	 * Returns bare-specifier mappings that should be registered in the active
-	 * runtime specifier registry.
-	 *
-	 * @remarks
-	 * Override this when the integration owns browser runtime bundles that must
-	 * be addressable from client-side imports through stable bare specifiers.
-	 *
-	 * Today these mappings are consumed by the development runtime and browser
-	 * bundle aliasing path. They are intentionally generic enough to grow into a
-	 * broader import-map-style facility later without moving framework-specific
-	 * map contents into core.
-	 */
-	getRuntimeSpecifierMap(): Record<string, string> {
-		return {};
-	}
-
-	setHmrManager(hmrManager: IHmrManager) {
-		this.hmrManager = hmrManager;
-		hmrManager.registerSpecifierMap(this.getRuntimeSpecifierMap());
-
-		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;
-	}
-
-	/**
-	 * Prepares build-facing contributions before the app build manifest is sealed.
-	 *
-	 * @remarks
-	 * Override this when an integration needs to materialize runtime/build plugin
-	 * declarations ahead of runtime startup. Keep runtime-only side effects out of
-	 * this hook; they belong in `setup()`.
-	 */
-	async prepareBuildContributions(): Promise<void> {}
-
-	/**
-	 * Performs runtime-only integration setup after config build has already
-	 * sealed manifest contributions.
-	 */
-	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.ts

@@ -1,240 +0,0 @@
-import path from 'node:path';
-import { fileSystem } from '@ecopages/file-system';
-import type { EcoBuildPlugin } from '../build/build-types.ts';
-import type { EcoPagesAppConfig, IClientBridge } from '../internal-types';
-import type { AssetDefinition } from '../services/assets/asset-processing-service';
-import { DEFAULT_ECOPAGES_WORK_DIR } from '../constants.ts';
-import { GENERATED_BASE_PATHS } from '../constants';
-import type { RuntimeCapabilityDeclaration } from './runtime-capability.ts';
-
-export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.ts';
-
-export const PROCESSOR_ERRORS = {
-	CACHE_DIRECTORY_NOT_SET: 'Cache directory not set in context',
-} as const;
-
-function resolveGeneratedPath(
-	type: keyof typeof GENERATED_BASE_PATHS,
-	options: { root: string; module: string; subPath?: string },
-): string {
-	const { root, module, subPath } = options;
-	const parts = [root, GENERATED_BASE_PATHS[type], module, subPath].filter(Boolean);
-	return path.join(...(parts as string[]));
-}
-
-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[];
-	runtimeCapability?: RuntimeCapabilityDeclaration;
-}
-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 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[] = [];
-	readonly runtimeCapability?: RuntimeCapabilityDeclaration;
-
-	/** 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>) {
-		this.name = config.name;
-		this.options = config.options;
-		this.watchConfig = config.watch;
-		this.capabilities = config.capabilities ?? [];
-		this.runtimeCapability = config.runtimeCapability;
-	}
-
-	setContext(appConfig: EcoPagesAppConfig): void {
-		const workDir =
-			appConfig.absolutePaths.workDir ??
-			path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
-		const cachePath = resolveGeneratedPath('cache', {
-			root: workDir,
-			module: this.name,
-		});
-
-		fileSystem.ensureDir(cachePath);
-
-		this.context = {
-			config: appConfig,
-			rootDir: appConfig.rootDir,
-			srcDir: appConfig.absolutePaths.srcDir,
-			distDir: appConfig.absolutePaths.distDir,
-			cache: cachePath,
-		};
-	}
-
-	/**
-	 * Prepares build-facing processor contributions before config finalization.
-	 *
-	 * @remarks
-	 * Override this when a processor must compute runtime/build plugins or other
-	 * manifest-owned state before startup. Runtime-only work such as cache
-	 * warming or watcher registration should stay in `setup()`.
-	 */
-	async prepareBuildContributions(): Promise<void> {}
-
-	abstract setup(): Promise<void>;
-	abstract teardown(): Promise<void>;
-	abstract process(input: unknown, filePath?: string): Promise<unknown>;
-
-	protected getCachePath(key: string): string {
-		return `${this.context?.cache}/${key}`;
-	}
-
-	protected async readCache<T>(key: string): Promise<T | null> {
-		const cachePath = this.getCachePath(key);
-		try {
-			const data = await fileSystem.readFile(cachePath);
-			return JSON.parse(data) as T;
-		} catch {
-			return null;
-		}
-	}
-
-	protected async writeCache<T>(key: string, data: T): Promise<void> {
-		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(): ProcessorWatchConfig | undefined {
-		return this.watchConfig;
-	}
-
-	getDependencies(): AssetDefinition[] {
-		return this.dependencies;
-	}
-
-	getName(): string {
-		return this.name;
-	}
-
-	getAssetCapabilities(): ProcessorAssetCapability[] {
-		return this.capabilities;
-	}
-
-	matchesFileFilter(_filepath: string): boolean {
-		return true;
-	}
-
-	canProcessAsset(kind: ProcessorAssetKind, filepath?: string): boolean {
-		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));
-	}
-
-	private matchesCapabilityExtensions(filepath: string, extensions?: ProcessorExtensionPattern[]): boolean {
-		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}`;
-		});
-	}
-
-	private normalizeExtensionPattern(rawPattern: string): string {
-		return rawPattern.trim().toLowerCase();
-	}
-}

package/src/plugins/runtime-capability.ts

@@ -1,14 +0,0 @@
-export type RuntimeCapabilityTag =
-	| 'bun-only'
-	| 'node-compatible'
-	| 'requires-native-bun-api'
-	| 'requires-node-builtins';
-
-/**
- * Declares the runtime assumptions a plugin makes so config finalization can
- * reject incompatible startup environments before bootstrapping the app.
- */
-export interface RuntimeCapabilityDeclaration {
-	tags: RuntimeCapabilityTag[];
-	minRuntimeVersion?: string;
-}