@ecopages/core 0.2.0-alpha.1

package/src/integrations/ghtml/ghtml.plugin.d.ts

@@ -0,0 +1,20 @@
+import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin';
+import { GhtmlRenderer } from './ghtml-renderer';
+/**
+ * The name of the ghtml plugin
+ */
+export declare const GHTML_PLUGIN_NAME = "ghtml";
+/**
+ * The Ghtml plugin class
+ * This plugin provides support for ghtml components in Ecopages
+ */
+export declare class GhtmlPlugin extends IntegrationPlugin {
+    renderer: typeof GhtmlRenderer;
+    constructor(options?: Omit<IntegrationPluginConfig, 'name'>);
+}
+/**
+ * Factory function to create a Ghtml plugin instance
+ * @param options Configuration options for the Ghtml plugin
+ * @returns A new GhtmlPlugin instance
+ */
+export declare function ghtmlPlugin(options?: Omit<IntegrationPluginConfig, 'name'>): GhtmlPlugin;

package/src/integrations/ghtml/ghtml.plugin.js

@@ -0,0 +1,21 @@
+import { IntegrationPlugin } from "../../plugins/integration-plugin";
+import { GhtmlRenderer } from "./ghtml-renderer";
+const GHTML_PLUGIN_NAME = "ghtml";
+class GhtmlPlugin extends IntegrationPlugin {
+  renderer = GhtmlRenderer;
+  constructor(options) {
+    super({
+      name: GHTML_PLUGIN_NAME,
+      extensions: [".ghtml.ts", ".ghtml.tsx", ".ghtml"],
+      ...options
+    });
+  }
+}
+function ghtmlPlugin(options) {
+  return new GhtmlPlugin(options);
+}
+export {
+  GHTML_PLUGIN_NAME,
+  GhtmlPlugin,
+  ghtmlPlugin
+};

package/src/integrations/ghtml/ghtml.plugin.ts

@@ -0,0 +1,32 @@
+import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin';
+import { GhtmlRenderer } from './ghtml-renderer';
+
+/**
+ * The name of the ghtml plugin
+ */
+export const GHTML_PLUGIN_NAME = 'ghtml';
+
+/**
+ * The Ghtml plugin class
+ * This plugin provides support for ghtml components in Ecopages
+ */
+export class GhtmlPlugin extends IntegrationPlugin {
+	renderer = GhtmlRenderer;
+
+	constructor(options?: Omit<IntegrationPluginConfig, 'name'>) {
+		super({
+			name: GHTML_PLUGIN_NAME,
+			extensions: ['.ghtml.ts', '.ghtml.tsx', '.ghtml'],
+			...options,
+		});
+	}
+}
+
+/**
+ * Factory function to create a Ghtml plugin instance
+ * @param options Configuration options for the Ghtml plugin
+ * @returns A new GhtmlPlugin instance
+ */
+export function ghtmlPlugin(options?: Omit<IntegrationPluginConfig, 'name'>): GhtmlPlugin {
+	return new GhtmlPlugin(options);
+}

package/src/internal-types.d.ts

@@ -0,0 +1,200 @@
+import type { EcoBuildPlugin } from './build/build-types.js';
+import type { IntegrationPlugin } from './plugins/integration-plugin.js';
+import type { Processor } from './plugins/processor.js';
+import type { PageMetadataProps } from './public-types.js';
+import type { FSRouter } from './router/fs-router.js';
+import type { CacheConfig } from './services/cache/cache.types.js';
+/**
+ * The templates used to build the pages and loaded via the includes directory.
+ */
+export type IncludesTemplates = {
+    head: string;
+    html: string;
+    seo: string;
+};
+export interface RobotsPreference {
+    /**
+     * The user agent
+     * If an empty array is provided, it will enable all paths for the user agent
+     * If a path is provided, it will disallow the path for the user agent
+     */
+    [key: string]: string[];
+}
+/**
+ * Represents the complete configuration object for EcoPages.
+ */
+export type EcoPagesAppConfig = {
+    /**
+     * The base URL of the website, localhost or the domain
+     */
+    baseUrl: string;
+    /**
+     * The root directory of the project
+     * @default "."
+     */
+    rootDir: string;
+    /**
+     * The root directory of the project
+     * @default "src"
+     */
+    srcDir: string;
+    /**
+     * The directory where the public files are located
+     * @default "public"
+     */
+    publicDir: string;
+    /**
+     * The directory where the pages are located
+     * @default "pages"
+     */
+    pagesDir: string;
+    /**
+     * The directory where the includes templates are located
+     * @default "includes"
+     */
+    includesDir: string;
+    /**
+     * The directory where the layouts are located
+     * @default "layouts"
+     */
+    layoutsDir: string;
+    /**
+     * The templates used for the pages
+     * @default "{head: 'head.kita.tsx', html: 'html.kita.tsx', seo: 'seo.kita.tsx'}"
+     */
+    includesTemplates: IncludesTemplates;
+    /** Error 404 page
+     * @default "404.kita.tsx"
+     */
+    error404Template: string;
+    /**
+     * The directory where the output will be located
+     * @default "dist"
+     */
+    distDir: string;
+    /**
+     * The templates extensions based on the integrations
+     */
+    templatesExt: string[];
+    /**
+     * The directory where the components are located
+     * @default "components"
+     */
+    componentsDir: string;
+    /**
+     * The robots.txt configuration
+     */
+    robotsTxt: {
+        /**
+         * The robots preferences. The key is the user agent and the value is the disallowed paths.
+         * @default { "*": [] }
+         */
+        preferences: RobotsPreference;
+    };
+    /** Additional paths to watch. Use this to monitor extra files. It is relative to the rootDir */
+    additionalWatchPaths: string[];
+    /**
+     * @default { title: 'Ecopages', description: 'Ecopages' }
+     */
+    defaultMetadata: PageMetadataProps;
+    /** Integrations plugins */
+    integrations: IntegrationPlugin[];
+    /** Integrations dependencies */
+    integrationsDependencies: IntegrationDependencyConfig[];
+    /** Derived Paths */
+    absolutePaths: {
+        config: string;
+        componentsDir: string;
+        distDir: string;
+        includesDir: string;
+        layoutsDir: string;
+        pagesDir: string;
+        projectDir: string;
+        publicDir: string;
+        srcDir: string;
+        htmlTemplatePath: string;
+        error404TemplatePath: string;
+    };
+    /**
+     * The processors to be used in the app
+     */
+    processors: Map<string, Processor>;
+    /**
+     * Loaders to be used in the app, these are used to process the files when importing them
+     */
+    loaders: Map<string, EcoBuildPlugin>;
+    /**
+     * Cache configuration for ISR and page caching.
+     * @default { store: 'memory', defaultStrategy: 'static', enabled: true }
+     */
+    cache?: CacheConfig;
+    /**
+     * Experimental features.
+     */
+    experimental?: {
+        /** Escape hatch for short-lived private toggles. No validation or IntelliSense. */
+        unsafe?: Record<string, unknown>;
+    };
+};
+export type IntegrationDependencyConfig = {
+    integration: string;
+    kind: 'script' | 'stylesheet';
+    position?: 'head' | 'body';
+    srcUrl: string;
+    filePath: string;
+    /** @todo inline dependencies not implemented yet */
+    inline?: boolean;
+};
+/**
+ * The possible kinds of a route.
+ */
+export type RouteKind = 'exact' | 'catch-all' | 'dynamic';
+/**
+ * Represents the result of a route match.
+ */
+export type MatchResult = {
+    filePath: string;
+    kind: RouteKind;
+    pathname: string;
+    query?: Record<string, string>;
+    params?: Record<string, string | string[]>;
+};
+/**
+ * Represents a route in EcoPages.
+ */
+export type Route = {
+    kind: RouteKind;
+    filePath: string;
+    pathname: string;
+};
+/**
+ * Represents the routes in EcoPages.
+ */
+export type Routes = Record<string, Route>;
+/**
+ * Represents the options for the file system server.
+ */
+export type FileSystemServerOptions = {
+    watchMode: boolean;
+    port?: number | string;
+};
+/**
+ * Represents the file system server adapter.
+ */
+export interface EcoPagesFileSystemServerAdapter<ServerInstanceOptions = unknown> {
+    startServer(serverOptions: ServerInstanceOptions): {
+        router: FSRouter;
+        server: unknown;
+    } | Promise<{
+        router: FSRouter;
+        server: unknown;
+    }>;
+}
+export interface ProcessorPlugin {
+    name: string;
+    description?: string;
+    setup(): Promise<void>;
+    process<T = unknown>(input: T): Promise<T>;
+    teardown?(): Promise<void>;
+}
+export type { ClientBridgeEvent, DefaultHmrContext, IHmrManager, IClientBridge } from './public-types.js';

package/src/internal-types.ts

@@ -0,0 +1,212 @@
+import type { EcoBuildPlugin } from './build/build-types.ts';
+import type { IntegrationPlugin } from './plugins/integration-plugin.ts';
+import type { Processor } from './plugins/processor.ts';
+import type { PageMetadataProps } from './public-types.ts';
+import type { FSRouter } from './router/fs-router.ts';
+import type { CacheConfig } from './services/cache/cache.types.ts';
+
+/**
+ * The templates used to build the pages and loaded via the includes directory.
+ */
+export type IncludesTemplates = {
+	head: string;
+	html: string;
+	seo: string;
+};
+
+export interface RobotsPreference {
+	/**
+	 * The user agent
+	 * If an empty array is provided, it will enable all paths for the user agent
+	 * If a path is provided, it will disallow the path for the user agent
+	 */
+	[key: string]: string[];
+}
+
+/**
+ * Represents the complete configuration object for EcoPages.
+ */
+export type EcoPagesAppConfig = {
+	/**
+	 * The base URL of the website, localhost or the domain
+	 */
+	baseUrl: string;
+	/**
+	 * The root directory of the project
+	 * @default "."
+	 */
+	rootDir: string;
+	/**
+	 * The root directory of the project
+	 * @default "src"
+	 */
+	srcDir: string;
+	/**
+	 * The directory where the public files are located
+	 * @default "public"
+	 */
+	publicDir: string;
+	/**
+	 * The directory where the pages are located
+	 * @default "pages"
+	 */
+	pagesDir: string;
+	/**
+	 * The directory where the includes templates are located
+	 * @default "includes"
+	 */
+	includesDir: string;
+	/**
+	 * The directory where the layouts are located
+	 * @default "layouts"
+	 */
+	layoutsDir: string;
+	/**
+	 * The templates used for the pages
+	 * @default "{head: 'head.kita.tsx', html: 'html.kita.tsx', seo: 'seo.kita.tsx'}"
+	 */
+	includesTemplates: IncludesTemplates;
+	/** Error 404 page
+	 * @default "404.kita.tsx"
+	 */
+	error404Template: string;
+	/**
+	 * The directory where the output will be located
+	 * @default "dist"
+	 */
+	distDir: string;
+	/**
+	 * The templates extensions based on the integrations
+	 */
+	templatesExt: string[];
+	/**
+	 * The directory where the components are located
+	 * @default "components"
+	 */
+	componentsDir: string;
+	/**
+	 * The robots.txt configuration
+	 */
+	robotsTxt: {
+		/**
+		 * The robots preferences. The key is the user agent and the value is the disallowed paths.
+		 * @default { "*": [] }
+		 */
+		preferences: RobotsPreference;
+	};
+	/** Additional paths to watch. Use this to monitor extra files. It is relative to the rootDir */
+	additionalWatchPaths: string[];
+	/**
+	 * @default { title: 'Ecopages', description: 'Ecopages' }
+	 */
+	defaultMetadata: PageMetadataProps;
+	/** Integrations plugins */
+	integrations: IntegrationPlugin[];
+	/** Integrations dependencies */
+	integrationsDependencies: IntegrationDependencyConfig[];
+	/** Derived Paths */
+	absolutePaths: {
+		config: string;
+		componentsDir: string;
+		distDir: string;
+		includesDir: string;
+		layoutsDir: string;
+		pagesDir: string;
+		projectDir: string;
+		publicDir: string;
+		srcDir: string;
+		htmlTemplatePath: string;
+		error404TemplatePath: string;
+	};
+	/**
+	 * The processors to be used in the app
+	 */
+	processors: Map<string, Processor>;
+	/**
+	 * Loaders to be used in the app, these are used to process the files when importing them
+	 */
+	loaders: Map<string, EcoBuildPlugin>;
+	/**
+	 * Cache configuration for ISR and page caching.
+	 * @default { store: 'memory', defaultStrategy: 'static', enabled: true }
+	 */
+	cache?: CacheConfig;
+	/**
+	 * Experimental features.
+	 */
+	experimental?: {
+		/** Escape hatch for short-lived private toggles. No validation or IntelliSense. */
+		unsafe?: Record<string, unknown>;
+	};
+};
+
+export type IntegrationDependencyConfig = {
+	integration: string;
+	kind: 'script' | 'stylesheet';
+	position?: 'head' | 'body';
+	srcUrl: string;
+	filePath: string;
+	/** @todo inline dependencies not implemented yet */
+	inline?: boolean;
+};
+
+/**
+ * The possible kinds of a route.
+ */
+export type RouteKind = 'exact' | 'catch-all' | 'dynamic';
+
+/**
+ * Represents the result of a route match.
+ */
+export type MatchResult = {
+	filePath: string;
+	kind: RouteKind;
+	pathname: string;
+	query?: Record<string, string>;
+	params?: Record<string, string | string[]>;
+};
+
+/**
+ * Represents a route in EcoPages.
+ */
+export type Route = {
+	kind: RouteKind;
+	filePath: string;
+	pathname: string;
+};
+
+/**
+ * Represents the routes in EcoPages.
+ */
+export type Routes = Record<string, Route>;
+
+/**
+ * Represents the options for the file system server.
+ */
+export type FileSystemServerOptions = {
+	watchMode: boolean;
+	port?: number | string;
+};
+
+/**
+ * Represents the file system server adapter.
+ */
+export interface EcoPagesFileSystemServerAdapter<ServerInstanceOptions = unknown> {
+	startServer(serverOptions: ServerInstanceOptions):
+		| {
+				router: FSRouter;
+				server: unknown;
+		  }
+		| Promise<{ router: FSRouter; server: unknown }>;
+}
+
+export interface ProcessorPlugin {
+	name: string;
+	description?: string;
+	setup(): Promise<void>;
+	process<T = unknown>(input: T): Promise<T>;
+	teardown?(): Promise<void>;
+}
+
+// Re-export HMR types from public-types for internal use
+export type { ClientBridgeEvent, DefaultHmrContext, IHmrManager, IClientBridge } from './public-types.ts';

package/src/plugins/alias-resolver-plugin.d.ts

@@ -0,0 +1,2 @@
+import type { EcoBuildPlugin } from '../build/build-types.js';
+export declare function createAliasResolverPlugin(srcDir: string): EcoBuildPlugin;

package/src/plugins/alias-resolver-plugin.js

@@ -0,0 +1,39 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx", ".css", ".scss", ".sass", ".less"];
+function findResolvablePath(candidate) {
+  if (path.extname(candidate)) {
+    return existsSync(candidate) ? candidate : void 0;
+  }
+  for (const extension of RESOLVABLE_EXTENSIONS) {
+    const fileCandidate = `${candidate}${extension}`;
+    if (existsSync(fileCandidate)) {
+      return fileCandidate;
+    }
+  }
+  for (const extension of RESOLVABLE_EXTENSIONS) {
+    const indexCandidate = path.join(candidate, `index${extension}`);
+    if (existsSync(indexCandidate)) {
+      return indexCandidate;
+    }
+  }
+  return void 0;
+}
+function createAliasResolverPlugin(srcDir) {
+  return {
+    name: "ecopages-alias-resolver",
+    setup(build) {
+      build.onResolve({ filter: /^@\// }, (args) => {
+        const candidate = path.join(srcDir, args.path.slice(2));
+        const resolved = findResolvablePath(candidate);
+        if (resolved) {
+          return { path: resolved };
+        }
+        return {};
+      });
+    }
+  };
+}
+export {
+  createAliasResolverPlugin
+};

package/src/plugins/alias-resolver-plugin.ts

@@ -0,0 +1,45 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import type { EcoBuildPlugin } from '../build/build-types.ts';
+
+const RESOLVABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mdx', '.css', '.scss', '.sass', '.less'];
+
+function findResolvablePath(candidate: string): string | undefined {
+	if (path.extname(candidate)) {
+		return existsSync(candidate) ? candidate : undefined;
+	}
+
+	for (const extension of RESOLVABLE_EXTENSIONS) {
+		const fileCandidate = `${candidate}${extension}`;
+		if (existsSync(fileCandidate)) {
+			return fileCandidate;
+		}
+	}
+
+	for (const extension of RESOLVABLE_EXTENSIONS) {
+		const indexCandidate = path.join(candidate, `index${extension}`);
+		if (existsSync(indexCandidate)) {
+			return indexCandidate;
+		}
+	}
+
+	return undefined;
+}
+
+export function createAliasResolverPlugin(srcDir: string): EcoBuildPlugin {
+	return {
+		name: 'ecopages-alias-resolver',
+		setup(build) {
+			build.onResolve({ filter: /^@\// }, (args) => {
+				const candidate = path.join(srcDir, args.path.slice(2));
+				const resolved = findResolvablePath(candidate);
+
+				if (resolved) {
+					return { path: resolved };
+				}
+
+				return {};
+			});
+		},
+	};
+}

package/src/plugins/eco-component-meta-plugin.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Bun plugin that auto-injects `__eco` metadata into EcoComponent config objects.
+ *
+ * This plugin uses AST parsing (via oxc-parser) to reliably inject the `__eco` property
+ * into EcoComponent config objects at import time. The injected metadata contains:
+ * - `dir`: The directory path of the component file (used for dependency resolution)
+ * - `integration`: The integration type (e.g., 'react', 'kitajs', 'ghtml', 'lit')
+ *
+ * The plugin intercepts file loading for all configured integration extensions and
+ * transforms component configs before they are executed.
+ *
+ * @example
+ * ```typescript
+ * // Before transformation:
+ * export default eco.page({
+ *   render: () => '<div>Hello</div>',
+ * });
+ *
+ * // After transformation:
+ * export default eco.page({
+ *   __eco: { id: "<hash>", file: "/path/to/pages/index.tsx", integration: "react" },
+ *   render: () => '<div>Hello</div>',
+ * });
+ * ```
+ *
+ * @module eco-component-meta-plugin
+ */
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoPagesAppConfig } from '../internal-types.js';
+/**
+ * Options for creating the eco-component-meta-plugin.
+ */
+export interface EcoComponentDirPluginOptions {
+    /** The EcoPages application configuration containing integration settings */
+    config: EcoPagesAppConfig;
+}
+/**
+ * Creates a build plugin that auto-injects `__eco` metadata into EcoComponent config objects.
+ *
+ * This plugin intercepts file loading for all integration-compatible files and:
+ * 1. Strips any query string from the file path (for dev mode cache-busting)
+ * 2. Reads the file contents
+ * 3. Parses the AST using oxc-parser to find injection points
+ * 4. Injects `__eco: { id: "...", file: "...", integration: "..." }` into config objects
+ * 5. Returns the transformed content with the appropriate loader
+ *
+ * Supported patterns:
+ * - `eco.page({ ... })` - Page component declarations
+ * - `eco.component({ ... })` - Reusable component declarations
+ * - `Component.config = { ... }` - Config assignment pattern
+ * - `config: { ... }` - Config property in object literals
+ * - `export const config = { ... }` - Exported config declarations
+ *
+ * @param options - Plugin options containing the EcoPages config
+ * @returns A build plugin instance ready for registration
+ *
+ * @example
+ * ```typescript
+ * import { createEcoComponentMetaPlugin } from '@ecopages/core';
+ *
+ * const plugin = createEcoComponentMetaPlugin({ config: appConfig });
+ * appConfig.loaders.set(plugin.name, plugin);
+ * ```
+ */
+export declare function createEcoComponentMetaPlugin(options: EcoComponentDirPluginOptions): EcoBuildPlugin;
+/**
+ * Injects `__eco` metadata into EcoComponent config objects in file content.
+ *
+ * Uses oxc-parser for robust AST-based code analysis, which handles edge cases
+ * that regex-based approaches would miss (e.g., complex generics, nested objects,
+ * comments, string literals containing similar patterns).
+ *
+ * The injection is performed by:
+ * 1. Parsing the source code into an AST
+ * 2. Walking the AST to find all config object patterns
+ * 3. Collecting insertion points (sorted in reverse order to preserve positions)
+ * 4. Inserting the `__eco` property at each point
+ *
+ * @param contents - The source code content to transform
+ * @param filePath - Absolute path to the file (used to derive the directory)
+ * @param integration - The integration identifier for this file type
+ * @returns Transformed source code with `__eco` injected, or original if no patterns found
+ *
+ * @example
+ * ```typescript
+ * const result = injectEcoMeta(
+ *   'export default eco.page({ render: () => "<div>Hi</div>" });',
+ *   '/app/src/pages/index.tsx',
+ *   'react'
+ * );
+ * // Result: 'export default eco.page({ __eco: { id: "<hash>", file: "/app/src/pages/index.tsx", integration: "react" }, render: () => "<div>Hi</div>" });'
+ * ```
+ */
+export declare function injectEcoMeta(contents: string, filePath: string, integration: string): string;
+export default createEcoComponentMetaPlugin;