@ecopages/core 0.2.0-alpha.22 → 0.2.0-alpha.24

package/src/plugins/processor.d.ts

@@ -1,95 +0,0 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { EcoPagesAppConfig, IClientBridge } from '../types/internal-types.js';
-import type { AssetDefinition } from '../services/assets/asset-processing-service/assets.types.js';
-import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
-export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
-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[];
-    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 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[];
-    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>);
-    setContext(appConfig: EcoPagesAppConfig): void;
-    /**
-     * 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()`.
-     */
-    prepareBuildContributions(): Promise<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

@@ -1,136 +0,0 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { DEFAULT_ECOPAGES_WORK_DIR } from "../config/constants.js";
-import { GENERATED_BASE_PATHS } from "../config/constants.js";
-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 = [];
-  runtimeCapability;
-  constructor(config) {
-    this.name = config.name;
-    this.options = config.options;
-    this.watchConfig = config.watch;
-    this.capabilities = config.capabilities ?? [];
-    this.runtimeCapability = config.runtimeCapability;
-  }
-  setContext(appConfig) {
-    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() {
-  }
-  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
-};

package/src/plugins/source-transform.d.ts

@@ -1,46 +0,0 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { EcoPagesAppConfig } from '../types/internal-types.js';
-export interface EcoSourceTransformResult {
-    code: string;
-    map?: unknown;
-}
-export interface EcoSourceTransform {
-    name: string;
-    filter: RegExp;
-    enforce?: 'pre' | 'post';
-    transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
-}
-export interface EcoViteCompatiblePlugin {
-    name: string;
-    enforce?: 'pre' | 'post';
-    transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
-}
-/**
- * Normalizes bundler module ids so one transform can serve Ecopages loaders,
- * Vite, and future bundler adapters.
- */
-export declare function normalizeTransformId(id: string): string;
-/**
- * Applies one source transform if the normalized id matches its filter.
- */
-export declare function applySourceTransform(transform: EcoSourceTransform, code: string, id: string): EcoSourceTransformResult | string | undefined;
-/**
- * Adapts a source transform into the existing Ecopages build-plugin contract.
- */
-export declare function createEcoBuildPluginFromSourceTransform(transform: EcoSourceTransform): EcoBuildPlugin;
-/**
- * Adapts a source transform into a Vite-compatible plugin object.
- *
- * @remarks
- * This intentionally returns a plain object shape so core does not need a hard
- * dependency on `vite` just to author transform primitives.
- */
-export declare function createVitePluginFromSourceTransform(transform: EcoSourceTransform): EcoViteCompatiblePlugin;
-/**
- * Returns the app-owned source transforms in stable registration order.
- */
-export declare function getAppSourceTransforms(appConfig: EcoPagesAppConfig): EcoSourceTransform[];
-/**
- * Adapts the app-owned source transforms into Vite-compatible plugin objects.
- */
-export declare function createVitePluginsFromAppSourceTransforms(appConfig: EcoPagesAppConfig): EcoViteCompatiblePlugin[];

package/src/plugins/source-transform.js

@@ -1,71 +0,0 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-function normalizeTransformId(id) {
-  const queryIndex = id.indexOf("?");
-  const hashIndex = id.indexOf("#");
-  const endIndex = [queryIndex, hashIndex].filter((index) => index >= 0).sort((left, right) => left - right)[0];
-  return endIndex === void 0 ? id : id.slice(0, endIndex);
-}
-function applySourceTransform(transform, code, id) {
-  const normalizedId = normalizeTransformId(id);
-  if (!transform.filter.test(normalizedId)) {
-    return void 0;
-  }
-  return transform.transform(code, normalizedId);
-}
-function inferLoaderFromPath(filePath) {
-  const extension = path.extname(filePath).toLowerCase();
-  switch (extension) {
-    case ".ts":
-      return "ts";
-    case ".tsx":
-      return "tsx";
-    case ".jsx":
-      return "jsx";
-    default:
-      return "js";
-  }
-}
-function createEcoBuildPluginFromSourceTransform(transform) {
-  return {
-    name: transform.name,
-    setup(build) {
-      build.onLoad({ filter: transform.filter }, (args) => {
-        const filePath = normalizeTransformId(args.path);
-        const code = fileSystem.readFileSync(filePath);
-        const result = applySourceTransform(transform, code, filePath);
-        if (!result) {
-          return void 0;
-        }
-        return {
-          contents: typeof result === "string" ? result : result.code,
-          loader: inferLoaderFromPath(filePath),
-          resolveDir: path.dirname(filePath)
-        };
-      });
-    }
-  };
-}
-function createVitePluginFromSourceTransform(transform) {
-  return {
-    name: transform.name,
-    enforce: transform.enforce,
-    transform(code, id) {
-      return applySourceTransform(transform, code, id);
-    }
-  };
-}
-function getAppSourceTransforms(appConfig) {
-  return Array.from(appConfig.sourceTransforms.values());
-}
-function createVitePluginsFromAppSourceTransforms(appConfig) {
-  return getAppSourceTransforms(appConfig).map((transform) => createVitePluginFromSourceTransform(transform));
-}
-export {
-  applySourceTransform,
-  createEcoBuildPluginFromSourceTransform,
-  createVitePluginFromSourceTransform,
-  createVitePluginsFromAppSourceTransforms,
-  getAppSourceTransforms,
-  normalizeTransformId
-};

package/src/route-renderer/orchestration/boundary-planning.service.d.ts

@@ -1,25 +0,0 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { BoundaryPlan, EcoComponent } from '../../types/public-types.js';
-type BoundaryPlanBuildInput = {
-    routeFile: string;
-    currentIntegrationName: string;
-    HtmlTemplate: EcoComponent;
-    Layout?: EcoComponent;
-    Page: EcoComponent;
-};
-/**
- * Builds a declared ownership plan from the component dependency graph.
- *
- * The plan is intentionally conservative: it reflects declared component
- * dependencies available during render preparation and records diagnostics for
- * foreign ownership edges that cannot be validated against registered
- * integrations or stable component metadata.
- */
-export declare class BoundaryPlanningService {
-    private readonly appConfig;
-    private nextSyntheticId;
-    constructor(appConfig: EcoPagesAppConfig);
-    buildPlan(input: BoundaryPlanBuildInput): BoundaryPlan;
-    private isRegisteredIntegration;
-}
-export {};

package/src/route-renderer/orchestration/boundary-planning.service.js

@@ -1,97 +0,0 @@
-class BoundaryPlanningService {
-  appConfig;
-  nextSyntheticId = 0;
-  constructor(appConfig) {
-    this.appConfig = appConfig;
-  }
-  buildPlan(input) {
-    this.nextSyntheticId = 0;
-    const validationErrors = [];
-    const rendererNames = /* @__PURE__ */ new Set([input.currentIntegrationName]);
-    let foreignEdgeCount = 0;
-    const buildNode = (component, source, parentIntegrationName, lineage) => {
-      const integrationName = component.config?.integration ?? component.config?.__eco?.integration ?? parentIntegrationName;
-      const componentMeta = component.config?.__eco;
-      const isForeignToParent = integrationName !== parentIntegrationName;
-      const componentId = componentMeta?.id ?? componentMeta?.file ?? `${source}:${this.nextSyntheticId += 1}`;
-      rendererNames.add(integrationName);
-      if (isForeignToParent) {
-        foreignEdgeCount += 1;
-        if (!componentMeta) {
-          validationErrors.push({
-            code: "MISSING_COMPONENT_METADATA",
-            message: `[ecopages] Foreign boundary "${componentId}" must provide stable __eco metadata so ownership diagnostics stay actionable. Declared dependencies must include all possible foreign children.`,
-            componentId,
-            integrationName
-          });
-        }
-        if (!this.isRegisteredIntegration(integrationName, input.currentIntegrationName)) {
-          validationErrors.push({
-            code: "UNKNOWN_INTEGRATION_OWNER",
-            message: `[ecopages] Foreign boundary "${componentId}" references unknown integration owner "${integrationName}". Declared dependencies must include all possible foreign children and those integrations must be registered.`,
-            componentId,
-            componentFile: componentMeta?.file,
-            integrationName
-          });
-        }
-      }
-      const nextLineage = new Set(lineage);
-      nextLineage.add(component);
-      const children = (component.config?.dependencies?.components ?? []).flatMap((child) => {
-        if (!child || nextLineage.has(child)) {
-          return [];
-        }
-        return [buildNode(child, "dependency", integrationName, nextLineage)];
-      });
-      return {
-        id: componentId,
-        source,
-        ownership: {
-          integrationName,
-          componentId,
-          componentFile: componentMeta?.file,
-          isPageEntry: source === "page",
-          isForeignToParent
-        },
-        children,
-        declaredDependenciesValid: true
-      };
-    };
-    const roots = [
-      { component: input.HtmlTemplate, source: "html-template" },
-      ...input.Layout ? [{ component: input.Layout, source: "layout" }] : [],
-      { component: input.Page, source: "page" }
-    ];
-    const root = {
-      id: `route:${input.routeFile}`,
-      source: "route",
-      ownership: {
-        integrationName: input.currentIntegrationName,
-        componentId: `route:${input.routeFile}`,
-        componentFile: input.routeFile,
-        isPageEntry: false,
-        isForeignToParent: false
-      },
-      children: roots.map(
-        ({ component, source }) => buildNode(component, source, input.currentIntegrationName, /* @__PURE__ */ new Set())
-      ),
-      declaredDependenciesValid: validationErrors.length === 0
-    };
-    return {
-      root,
-      rendererNames: Array.from(rendererNames),
-      foreignEdgeCount,
-      hasValidationErrors: validationErrors.length > 0,
-      validationErrors
-    };
-  }
-  isRegisteredIntegration(integrationName, currentIntegrationName) {
-    if (integrationName === currentIntegrationName) {
-      return true;
-    }
-    return this.appConfig.integrations.some((integration) => integration.name === integrationName);
-  }
-}
-export {
-  BoundaryPlanningService
-};

package/src/route-renderer/orchestration/component-render-context.d.ts

@@ -1,83 +0,0 @@
-import type { EcoComponent } from '../../types/public-types.js';
-/**
- * Result returned by a renderer-owned boundary runtime.
- *
- * `inline` keeps rendering inside the current integration. `resolved` returns a
- * renderer-owned value immediately, which can be final HTML or a renderer-local
- * transport token for later queue resolution.
- */
-export type ComponentBoundaryInterceptionResult = {
-    kind: 'inline';
-} | {
-    kind: 'resolved';
-    value: unknown;
-};
-/**
- * Boundary metadata passed into the active renderer-owned runtime.
- */
-export type ComponentBoundaryInterceptionInput = {
-    currentIntegration: string;
-    targetIntegration?: string;
-    component: EcoComponent;
-    props: Record<string, unknown>;
-};
-/**
- * Narrow renderer-owned boundary runtime injected into one active render
- * context.
- *
- * Integrations implement this contract when foreign boundaries must be handed
- * off inside the renderer instead of being left for route-level reconciliation.
- */
-export interface ComponentBoundaryRuntime {
-    interceptBoundary?(input: ComponentBoundaryInterceptionInput): ComponentBoundaryInterceptionResult | Promise<ComponentBoundaryInterceptionResult>;
-    interceptBoundarySync?(input: ComponentBoundaryInterceptionInput): ComponentBoundaryInterceptionResult;
-}
-type ComponentBoundaryRenderInput = {
-    component: EcoComponent;
-    props: Record<string, unknown>;
-    targetIntegration?: string;
-};
-/**
- * Per-render mutable state used while applying boundary interception and lazy
- * output wrapping.
- */
-export type ComponentRenderContext = {
-    currentIntegration: string;
-    boundaryRuntime?: ComponentBoundaryRuntime;
-    interceptBoundary(input: ComponentBoundaryRenderInput): Promise<unknown | undefined> | unknown | undefined;
-    finalizeComponentRender<T>(component: EcoComponent, content: T): T;
-};
-/**
- * Returns the current component render context, if one is active.
- *
- * @returns Active render context or `undefined` outside render execution.
- */
-export declare function getComponentRenderContext(): ComponentRenderContext | undefined;
-/**
- * Runs boundary interception for one component boundary.
- *
- * The active runtime may resolve the boundary immediately or keep it inline.
- */
-export declare function interceptComponentBoundary(input: ComponentBoundaryRenderInput): Promise<unknown | undefined> | unknown | undefined;
-/**
- * Applies lazy trigger or injector wrapping to completed component output.
- *
- * This helper works both inside render-context execution and in fallback flows
- * where no active context exists.
- */
-export declare function finalizeComponentRender<T>(component: EcoComponent, content: T): T;
-/**
- * Runs render work under a fresh component render context and returns the
- * resulting value.
- *
- * @param input Execution metadata for current integration and boundary policy.
- * @param render Async render function to execute inside the context.
- * @returns Render result value.
- */
-export declare function runWithComponentRenderContext<T>(input: {
-    currentIntegration: string;
-    boundaryRuntime?: ComponentBoundaryRuntime;
-}, render: () => Promise<T>): Promise<{
-    value: T;
-}>;
-export {};