@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.9

package/src/utils/runtime.js

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+const RUNTIME_ERRORS = {
+  BUN_RUNTIME_REQUIRED: "Bun runtime is required"
+};
+function getBunRuntime() {
+  return globalThis.Bun;
+}
+function getRequiredBunRuntime() {
+  const bun = getBunRuntime();
+  if (!bun) {
+    throw new Error(RUNTIME_ERRORS.BUN_RUNTIME_REQUIRED);
+  }
+  return bun;
+}
+function getRuntimeArgv() {
+  return process.argv;
+}
+function isDevelopmentRuntime() {
+  return process.env.NODE_ENV === "development";
+}
+function isProductionRuntime() {
+  return process.env.NODE_ENV === "production";
+}
+function runtimeHash(content) {
+  const bun = getBunRuntime();
+  if (bun) {
+    return bun.hash(content);
+  }
+  const hex = createHash("sha256").update(content).digest("hex").slice(0, 16);
+  return BigInt(`0x${hex}`);
+}
+export {
+  RUNTIME_ERRORS,
+  getBunRuntime,
+  getRequiredBunRuntime,
+  getRuntimeArgv,
+  isDevelopmentRuntime,
+  isProductionRuntime,
+  runtimeHash
+};

package/src/utils/server-utils.module.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Get the content type of a file based on its extension.
+ * @param file - The file name.
+ * @returns The content type.
+ */
+export declare const getContentType: (file: string) => string;
+/**
+ * Check if a file path has a known static file extension.
+ * @param file - The file name or path.
+ * @returns true if the extension is recognized.
+ */
+export declare const hasKnownExtension: (file: string) => boolean;
+/**
+ * A module for server utilities.
+ */
+export declare const ServerUtils: {
+    getContentType: (file: string) => string;
+    hasKnownExtension: (file: string) => boolean;
+};

package/src/utils/server-utils.module.js

@@ -0,0 +1,56 @@
+const ContentTypeMap = /* @__PURE__ */ new Map([
+  ["jpg", "image/jpeg"],
+  ["jpeg", "image/jpeg"],
+  ["png", "image/png"],
+  ["gif", "image/gif"],
+  ["bmp", "image/bmp"],
+  ["svg", "image/svg+xml"],
+  ["tiff", "image/tiff"],
+  ["webp", "image/webp"],
+  ["avif", "image/avif"],
+  ["ico", "image/x-icon"],
+  ["mp3", "audio/mpeg"],
+  ["ogg", "audio/ogg"],
+  ["wav", "audio/wav"],
+  ["mp4", "video/mp4"],
+  ["webm", "video/webm"],
+  ["ogv", "video/ogg"],
+  ["mov", "video/quicktime"],
+  ["txt", "text/plain"],
+  ["html", "text/html"],
+  ["css", "text/css"],
+  ["js", "text/javascript"],
+  ["mjs", "text/javascript"],
+  ["json", "application/json"],
+  ["map", "application/json"],
+  ["xml", "application/xml"],
+  ["webmanifest", "application/manifest+json"],
+  ["wasm", "application/wasm"],
+  ["csv", "text/csv"],
+  ["ttf", "font/ttf"],
+  ["woff", "font/woff"],
+  ["woff2", "font/woff2"],
+  ["otf", "font/otf"],
+  ["eot", "application/vnd.ms-fontobject"],
+  ["gz", "application/x-gzip"],
+  ["zip", "application/zip"],
+  ["pdf", "application/pdf"],
+  ["doc", "application/msword"]
+]);
+const getContentType = (file) => {
+  const extension = file.split(".").pop() || "txt";
+  return ContentTypeMap.get(extension) || "text/plain";
+};
+const hasKnownExtension = (file) => {
+  const extension = file.split(".").pop();
+  return extension !== void 0 && ContentTypeMap.has(extension);
+};
+const ServerUtils = {
+  getContentType,
+  hasKnownExtension
+};
+export {
+  ServerUtils,
+  getContentType,
+  hasKnownExtension
+};

package/src/watchers/project-watcher.d.ts

@@ -0,0 +1,136 @@
+import { type FSWatcher } from 'chokidar';
+import type { EcoPagesAppConfig, IHmrManager, IClientBridge } from '../internal-types.js';
+/**
+ * Configuration options for the ProjectWatcher
+ * @interface ProjectWatcherConfig
+ * @property {EcoPagesAppConfig} config - The application configuration
+ * @property {() => void} refreshRouterRoutesCallback - Callback to refresh router routes
+ * @property {IHmrManager} hmrManager - The HMR manager instance
+ * @property {ClientBridge} bridge - The client bridge instance
+ */
+export interface ProjectWatcherConfig {
+    config: EcoPagesAppConfig;
+    refreshRouterRoutesCallback: () => void;
+    hmrManager: IHmrManager;
+    bridge: IClientBridge;
+}
+/**
+ * ProjectWatcher handles file system changes for hot module replacement (HMR).
+ * It uses chokidar to watch for file changes and triggers appropriate actions:
+ * - Uncaches modules when files change
+ * - Refreshes router routes for page files
+ * - Triggers HMR server reload
+ * - Handles processor-specific file changes
+ *
+ * The watcher uses chokidar's built-in debouncing through `awaitWriteFinish`
+ * to handle rapid file changes efficiently:
+ * - stabilityThreshold: 50ms - Time to wait for writes to stabilize
+ * - pollInterval: 50ms - Interval to poll for file changes
+ *
+ * @class ProjectWatcher
+ */
+export declare class ProjectWatcher {
+    /**
+     * Duplicate identical watcher events within this window are ignored.
+     *
+     * Some editors or save pipelines emit two near-identical filesystem change
+     * notifications for the same file. Ecopages should treat those as one logical
+     * update so HMR and route refresh work are not repeated unnecessarily.
+     */
+    private static readonly duplicateChangeWindowMs;
+    private appConfig;
+    private refreshRouterRoutesCallback;
+    private hmrManager;
+    private bridge;
+    private readonly invalidationService;
+    private watcher;
+    private lastHandledChange;
+    private changeQueue;
+    constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }: ProjectWatcherConfig);
+    /**
+     * Uncaches modules in the source directory to ensure fresh imports.
+     * This is necessary for hot module replacement to work correctly.
+     * @private
+     */
+    private uncacheModules;
+    private isRouteSourceFile;
+    private isIncludeSourceFile;
+    /**
+     * Handles public directory file changes by copying only the changed file.
+     * @param filePath - Absolute path of the changed file
+     */
+    private handlePublicDirFileChange;
+    /**
+     * Serializes file change handling so that concurrent chokidar events are
+     * processed one at a time, preventing overlapping builds and race conditions.
+     */
+    private enqueueChange;
+    /**
+     * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
+     * Follows 5-rule priority:
+     * 0. Public directory match? -> copy file and reload
+     * 1. additionalWatchPaths match? -> reload
+     * 2. Include template source? -> reload after processor notifications
+     * 3. Processor-owned asset? -> processor already handled it via notification, skip HMR
+     * 4. Otherwise -> HMR strategies
+     *
+     * Processors that watch a file extension as a dependency (e.g. PostCSS watching
+     * .tsx for Tailwind class scanning) are always notified first, but do not
+     * prevent the file from flowing through the normal HMR strategy pipeline.
+     *
+     * Duplicate identical watcher events for the same file are coalesced within a
+     * short window before any of the priority rules run.
+     * @param rawPath - Path of the changed file
+     * @param event - The type of file system event
+     */
+    private handleFileChange;
+    /**
+     * Notifies all processors whose watch config matches the given file extension.
+     * This is called before checking processor ownership so that dependency-only
+     * processors (e.g. PostCSS watching .tsx for class scanning) receive their
+     * notifications regardless of whether they own the file.
+     */
+    private notifyProcessors;
+    private getProcessorHandler;
+    /**
+     * Checks if a file is in the public directory.
+     */
+    private isPublicDirFile;
+    /**
+     * Checks if file path matches any additionalWatchPaths patterns.
+     */
+    private matchesAdditionalWatchPaths;
+    /**
+     * Checks if a file is handled by a processor.
+     * Processors that declare asset capabilities own those file types.
+     * Processors without capabilities fall back to checking watch extensions.
+     */
+    private isHandledByProcessor;
+    /**
+     * Triggers router refresh for page directory changes.
+     * This ensures the router is updated when pages are added or removed.
+     *
+     * @param {string} path - Path of the changed directory
+     */
+    triggerRouterRefresh(changedPath: string): void;
+    /**
+     * Handles and logs errors that occur during file watching.
+     *
+     * @param {unknown} error - The error to handle
+     */
+    handleError(error: unknown): void;
+    /**
+     * Creates and configures the file system watcher.
+     * This sets up:
+     * 1. Page file watching
+     * 2. Directory watching
+     * 3. Error handling
+     *
+     * Processor notifications are dispatched inside handleFileChange, ensuring
+     * a single unified event pipeline with no parallel chokidar bindings.
+     *
+     * Uses chokidar's built-in debouncing through `awaitWriteFinish` to handle
+     * rapid file changes efficiently.
+     */
+    createWatcherSubscription(): Promise<FSWatcher>;
+}

package/src/watchers/project-watcher.js

@@ -0,0 +1,281 @@
+import path from "node:path";
+import chokidar, {} from "chokidar";
+import { fileSystem } from "@ecopages/file-system";
+import { appLogger } from "../global/app-logger.js";
+import { DevelopmentInvalidationService } from "../services/invalidation/development-invalidation.service.js";
+class ProjectWatcher {
+  /**
+   * Duplicate identical watcher events within this window are ignored.
+   *
+   * Some editors or save pipelines emit two near-identical filesystem change
+   * notifications for the same file. Ecopages should treat those as one logical
+   * update so HMR and route refresh work are not repeated unnecessarily.
+   */
+  static duplicateChangeWindowMs = 150;
+  appConfig;
+  refreshRouterRoutesCallback;
+  hmrManager;
+  bridge;
+  invalidationService;
+  watcher = null;
+  lastHandledChange = /* @__PURE__ */ new Map();
+  changeQueue = Promise.resolve();
+  constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }) {
+    this.appConfig = config;
+    this.refreshRouterRoutesCallback = refreshRouterRoutesCallback;
+    this.hmrManager = hmrManager;
+    this.bridge = bridge;
+    this.invalidationService = new DevelopmentInvalidationService(config);
+    this.triggerRouterRefresh = this.triggerRouterRefresh.bind(this);
+    this.handleError = this.handleError.bind(this);
+    this.handleFileChange = this.handleFileChange.bind(this);
+  }
+  /**
+   * Uncaches modules in the source directory to ensure fresh imports.
+   * This is necessary for hot module replacement to work correctly.
+   * @private
+   */
+  uncacheModules() {
+    if (typeof require === "undefined") return;
+    const { srcDir, rootDir } = this.appConfig;
+    const regex = new RegExp(`${rootDir}/${srcDir}/.*`);
+    for (const key in require.cache) {
+      if (regex.test(key)) {
+        delete require.cache[key];
+      }
+    }
+  }
+  isRouteSourceFile(filePath) {
+    return this.invalidationService.isRouteSourceFile(filePath);
+  }
+  isIncludeSourceFile(filePath) {
+    return this.invalidationService.isIncludeSourceFile(filePath);
+  }
+  /**
+   * Handles public directory file changes by copying only the changed file.
+   * @param filePath - Absolute path of the changed file
+   */
+  async handlePublicDirFileChange(filePath) {
+    try {
+      const relativePath = path.relative(this.appConfig.absolutePaths.publicDir, filePath);
+      const destPath = path.join(this.appConfig.absolutePaths.distDir, relativePath);
+      if (fileSystem.exists(filePath)) {
+        const destDir = path.dirname(destPath);
+        fileSystem.ensureDir(destDir);
+        await fileSystem.copyFileAsync(filePath, destPath);
+      }
+      this.bridge.reload();
+    } catch (error) {
+      appLogger.error(`Failed to copy public file: ${error instanceof Error ? error.message : String(error)}`);
+      this.bridge.reload();
+    }
+  }
+  /**
+   * Serializes file change handling so that concurrent chokidar events are
+   * processed one at a time, preventing overlapping builds and race conditions.
+   */
+  enqueueChange(task) {
+    const queuedTask = this.changeQueue.then(task, task);
+    this.changeQueue = queuedTask.catch(() => void 0);
+  }
+  /**
+   * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
+   * Follows 5-rule priority:
+   * 0. Public directory match? -> copy file and reload
+   * 1. additionalWatchPaths match? -> reload
+   * 2. Include template source? -> reload after processor notifications
+   * 3. Processor-owned asset? -> processor already handled it via notification, skip HMR
+   * 4. Otherwise -> HMR strategies
+   *
+   * Processors that watch a file extension as a dependency (e.g. PostCSS watching
+   * .tsx for Tailwind class scanning) are always notified first, but do not
+   * prevent the file from flowing through the normal HMR strategy pipeline.
+   *
+   * Duplicate identical watcher events for the same file are coalesced within a
+   * short window before any of the priority rules run.
+   * @param rawPath - Path of the changed file
+   * @param event - The type of file system event
+   */
+  async handleFileChange(rawPath, event = "change") {
+    const filePath = path.resolve(rawPath);
+    const now = Date.now();
+    const lastHandledAt = this.lastHandledChange.get(filePath);
+    if (lastHandledAt !== void 0 && now - lastHandledAt < ProjectWatcher.duplicateChangeWindowMs) {
+      return;
+    }
+    this.lastHandledChange.set(filePath, now);
+    try {
+      const plan = this.invalidationService.planFileChange(filePath);
+      if (plan.category === "public-asset") {
+        await this.handlePublicDirFileChange(filePath);
+        return;
+      }
+      this.uncacheModules();
+      if (plan.invalidateServerModules) {
+        this.invalidationService.invalidateServerModules([filePath]);
+      }
+      if (plan.refreshRoutes) {
+        this.refreshRouterRoutesCallback();
+      }
+      if (plan.category === "additional-watch") {
+        this.bridge.reload();
+        return;
+      }
+      await this.notifyProcessors(filePath, event);
+      if (plan.category === "include-source") {
+        this.bridge.reload();
+        return;
+      }
+      if (plan.processorHandledAsset) {
+        return;
+      }
+      if (plan.delegateToHmr) {
+        await this.hmrManager.handleFileChange(filePath);
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        this.bridge.error(error.message);
+        this.handleError(error);
+      }
+    }
+  }
+  /**
+   * Notifies all processors whose watch config matches the given file extension.
+   * This is called before checking processor ownership so that dependency-only
+   * processors (e.g. PostCSS watching .tsx for class scanning) receive their
+   * notifications regardless of whether they own the file.
+   */
+  async notifyProcessors(filePath, event) {
+    const ctx = { path: filePath, bridge: this.bridge };
+    for (const processor of this.appConfig.processors.values()) {
+      const watchConfig = processor.getWatchConfig();
+      if (!watchConfig) continue;
+      const { extensions = [] } = watchConfig;
+      if (extensions.length && !extensions.some((ext) => filePath.endsWith(ext))) {
+        continue;
+      }
+      const handler = this.getProcessorHandler(watchConfig, event);
+      if (handler) {
+        await handler(ctx);
+      }
+    }
+  }
+  getProcessorHandler(watchConfig, event) {
+    switch (event) {
+      case "change":
+        return watchConfig.onChange;
+      case "add":
+        return watchConfig.onCreate;
+      case "unlink":
+        return watchConfig.onDelete;
+    }
+  }
+  /**
+   * Checks if a file is in the public directory.
+   */
+  isPublicDirFile(filePath) {
+    return this.invalidationService.isPublicDirFile(filePath);
+  }
+  /**
+   * Checks if file path matches any additionalWatchPaths patterns.
+   */
+  matchesAdditionalWatchPaths(filePath) {
+    return this.invalidationService.matchesAdditionalWatchPaths(filePath);
+  }
+  /**
+   * Checks if a file is handled by a processor.
+   * Processors that declare asset capabilities own those file types.
+   * Processors without capabilities fall back to checking watch extensions.
+   */
+  isHandledByProcessor(filePath) {
+    return this.invalidationService.isProcessorOwnedAsset(filePath);
+  }
+  /**
+   * Triggers router refresh for page directory changes.
+   * This ensures the router is updated when pages are added or removed.
+   *
+   * @param {string} path - Path of the changed directory
+   */
+  triggerRouterRefresh(changedPath) {
+    const resolvedPath = path.resolve(changedPath);
+    const isPageDir = resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir) && path.extname(resolvedPath) === "";
+    if (isPageDir || this.isRouteSourceFile(resolvedPath)) {
+      this.refreshRouterRoutesCallback();
+    }
+  }
+  /**
+   * Handles and logs errors that occur during file watching.
+   *
+   * @param {unknown} error - The error to handle
+   */
+  handleError(error) {
+    if (error instanceof Error) {
+      this.hmrManager.broadcast({ type: "error", message: error.message });
+    }
+    appLogger.error(`Watcher error: ${error}`);
+  }
+  /**
+   * Creates and configures the file system watcher.
+   * This sets up:
+   * 1. Page file watching
+   * 2. Directory watching
+   * 3. Error handling
+   *
+   * Processor notifications are dispatched inside handleFileChange, ensuring
+   * a single unified event pipeline with no parallel chokidar bindings.
+   *
+   * Uses chokidar's built-in debouncing through `awaitWriteFinish` to handle
+   * rapid file changes efficiently.
+   */
+  async createWatcherSubscription() {
+    if (!this.watcher) {
+      const processorPaths = [];
+      for (const processor of this.appConfig.processors.values()) {
+        const watchConfig = processor.getWatchConfig();
+        if (!watchConfig) continue;
+        processorPaths.push(...watchConfig.paths);
+      }
+      if (fileSystem.exists(this.appConfig.absolutePaths.includesDir)) {
+        processorPaths.push(this.appConfig.absolutePaths.includesDir);
+      }
+      if (fileSystem.exists(this.appConfig.absolutePaths.srcDir)) {
+        processorPaths.push(this.appConfig.absolutePaths.srcDir);
+      }
+      if (fileSystem.exists(this.appConfig.absolutePaths.pagesDir)) {
+        processorPaths.push(this.appConfig.absolutePaths.pagesDir);
+      }
+      if (fileSystem.exists(this.appConfig.absolutePaths.publicDir)) {
+        processorPaths.push(this.appConfig.absolutePaths.publicDir);
+      }
+      if (this.appConfig.additionalWatchPaths.length) {
+        processorPaths.push(...this.appConfig.additionalWatchPaths);
+      }
+      this.watcher = chokidar.watch(processorPaths, {
+        ignoreInitial: true,
+        ignorePermissionErrors: true,
+        awaitWriteFinish: {
+          stabilityThreshold: 50,
+          pollInterval: 50
+        }
+      });
+    }
+    this.watcher.add(this.appConfig.absolutePaths.srcDir);
+    this.watcher.on("change", (p) => this.enqueueChange(() => this.handleFileChange(p, "change"))).on("add", (p) => {
+      this.enqueueChange(() => this.handleFileChange(p, "add"));
+      this.triggerRouterRefresh(p);
+    }).on("addDir", (p) => this.triggerRouterRefresh(p)).on("unlink", (p) => {
+      this.enqueueChange(() => this.handleFileChange(p, "unlink"));
+      this.triggerRouterRefresh(p);
+    }).on("unlinkDir", (p) => this.triggerRouterRefresh(p)).on("error", (error) => this.handleError(error));
+    for (const processor of this.appConfig.processors.values()) {
+      const watchConfig = processor.getWatchConfig();
+      if (watchConfig?.onError) {
+        this.watcher.on("error", watchConfig.onError);
+      }
+    }
+    return this.watcher;
+  }
+}
+export {
+  ProjectWatcher
+};

package/src/watchers/project-watcher.test-helpers.d.ts

@@ -0,0 +1,4 @@
+import type { IHmrManager } from '../internal-types';
+import type { ClientBridge } from '../adapters/bun/client-bridge';
+export declare const createMockHmrManager: () => IHmrManager;
+export declare const createMockBridge: () => ClientBridge;

package/src/watchers/project-watcher.test-helpers.js

@@ -0,0 +1,52 @@
+import { vi } from "vitest";
+const createMockHmrManager = () => ({
+  handleFileChange: vi.fn(async () => {
+  }),
+  broadcast: vi.fn(() => {
+  }),
+  setEnabled: vi.fn(() => {
+  }),
+  setPlugins: vi.fn(() => {
+  }),
+  registerEntrypoint: vi.fn(async () => ""),
+  registerScriptEntrypoint: vi.fn(async () => ""),
+  registerSpecifierMap: vi.fn(() => {
+  }),
+  registerStrategy: vi.fn(() => {
+  }),
+  isEnabled: vi.fn(() => true),
+  getOutputUrl: vi.fn(() => void 0),
+  getWatchedFiles: vi.fn(() => /* @__PURE__ */ new Map()),
+  getSpecifierMap: vi.fn(() => /* @__PURE__ */ new Map()),
+  getDistDir: vi.fn(() => ""),
+  getPlugins: vi.fn(() => []),
+  getDefaultContext: vi.fn(() => ({
+    getWatchedFiles: () => /* @__PURE__ */ new Map(),
+    getSpecifierMap: () => /* @__PURE__ */ new Map(),
+    getDistDir: () => "",
+    getPlugins: () => [],
+    getSrcDir: () => "",
+    getLayoutsDir: () => ""
+  }))
+});
+const createMockBridge = () => ({
+  reload: vi.fn(() => {
+  }),
+  error: vi.fn(() => {
+  }),
+  cssUpdate: vi.fn(() => {
+  }),
+  update: vi.fn(() => {
+  }),
+  subscribe: vi.fn(() => {
+  }),
+  unsubscribe: vi.fn(() => {
+  }),
+  broadcast: vi.fn(() => {
+  }),
+  subscriberCount: 0
+});
+export {
+  createMockBridge,
+  createMockHmrManager
+};