create-jen-app 1.2.2 → 1.2.4

package/templates/static/lib/plugin/plugin-manager.js

@@ -0,0 +1,177 @@
+import { log } from "../shared/log.js";
+/**
+ * Central plugin manager for Jen.js framework.
+ *
+ * Manages plugin loading, hook registration, and execution.
+ * Plugins can hook into any stage of the build, dev, or request lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const manager = new PluginManager(config, "development");
+ * await manager.loadPlugins([myPlugin]);
+ * await manager.emitHook("beforeBuild", { config, data: {} });
+ * ```
+ */
+export class PluginManager {
+  plugins = [];
+  hooks = new Map();
+  config;
+  mode;
+  rootDir;
+  initialized = false;
+  constructor(config, rootDir, mode = "development") {
+    this.config = config;
+    this.rootDir = rootDir;
+    this.mode = mode;
+  }
+  /**
+   * Load plugins from configuration or explicit list.
+   */
+  async loadPlugins(plugins = []) {
+    try {
+      for (const plugin of plugins) {
+        const resolved =
+          typeof plugin === "string"
+            ? await this.resolvePlugin(plugin)
+            : plugin;
+        this.plugins.push(resolved);
+        log.info(`[Plugin] Loaded: ${resolved.name}@${resolved.version}`);
+      }
+      this.initialized = true;
+    } catch (error) {
+      log.error(
+        `[Plugin] Failed to load plugins: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      throw error;
+    }
+  }
+  /**
+   * Resolve a plugin by name (from node_modules or path).
+   */
+  async resolvePlugin(pluginName) {
+    try {
+      // Try to import from node_modules
+      const imported = await import(pluginName);
+      return imported.default || imported;
+    } catch {
+      // Try to import from relative path
+      const path = pluginName.startsWith("/")
+        ? pluginName
+        : `${this.rootDir}/${pluginName}`;
+      const imported = await import(path);
+      return imported.default || imported;
+    }
+  }
+  /**
+   * Initialize all loaded plugins.
+   */
+  async initialize() {
+    if (!this.initialized) {
+      throw new Error("Plugins must be loaded before initialization");
+    }
+    const context = {
+      config: this.config,
+      rootDir: this.rootDir,
+      mode: this.mode,
+      onHook: (stage, handler) => this.registerHook(stage, handler),
+      emitHook: (stage, context) => this.emitHook(stage, context),
+    };
+    for (const plugin of this.plugins) {
+      if (plugin.init) {
+        try {
+          await plugin.init(context);
+          log.info(`[Plugin] Initialized: ${plugin.name}`);
+        } catch (error) {
+          log.error(
+            `[Plugin] Initialization failed for ${plugin.name}: ${error instanceof Error ? error.message : String(error)}`,
+          );
+          throw error;
+        }
+      }
+      // Register plugin hooks
+      if (plugin.hooks) {
+        for (const [stage, handler] of Object.entries(plugin.hooks)) {
+          if (handler) {
+            this.registerHook(stage, handler);
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Register a hook handler for a specific stage.
+   */
+  registerHook(stage, handler) {
+    if (!this.hooks.has(stage)) {
+      this.hooks.set(stage, []);
+    }
+    this.hooks.get(stage).push(handler);
+  }
+  /**
+   * Emit a hook event, executing all registered handlers.
+   */
+  async emitHook(stage, context) {
+    const handlers = this.hooks.get(stage) || [];
+    if (handlers.length === 0) {
+      return;
+    }
+    try {
+      // Execute hooks sequentially by default
+      for (const handler of handlers) {
+        try {
+          await handler(context);
+        } catch (error) {
+          log.error(
+            `[Plugin Hook] Error in ${stage}: ${error instanceof Error ? error.message : String(error)}`,
+          );
+          throw error;
+        }
+      }
+    } catch (error) {
+      log.error(`[Plugin] Hook execution failed for stage: ${stage}`);
+      throw error;
+    }
+  }
+  /**
+   * Get all registered plugins.
+   */
+  getPlugins() {
+    return [...this.plugins];
+  }
+  /**
+   * Get handlers for a specific hook stage.
+   */
+  getHooks(stage) {
+    return this.hooks.get(stage) || [];
+  }
+  /**
+   * Check if a hook stage has handlers registered.
+   */
+  hasHook(stage) {
+    return this.hooks.has(stage) && this.hooks.get(stage).length > 0;
+  }
+}
+/**
+ * Global plugin manager instance (singleton).
+ */
+let globalPluginManager = null;
+/**
+ * Get or create the global plugin manager.
+ */
+export function getPluginManager(config, rootDir, mode) {
+  if (!globalPluginManager) {
+    if (!config || !rootDir) {
+      throw new Error(
+        "Plugin manager not initialized. Call getPluginManager with config and rootDir",
+      );
+    }
+    globalPluginManager = new PluginManager(config, rootDir, mode);
+  }
+  return globalPluginManager;
+}
+/**
+ * Reset the global plugin manager (for testing).
+ */
+export function resetPluginManager() {
+  globalPluginManager = null;
+}

package/templates/static/lib/plugin/types.js

@@ -0,0 +1,28 @@
+/**
+ * Plugin lifecycle and hook system.
+ * Plugins hook into key stages of build, dev, and request handling.
+ */
+/**
+ * Hookable stages available to plugins.
+ */
+export var HookStage;
+(function (HookStage) {
+  // Build lifecycle
+  HookStage["BEFORE_BUILD"] = "beforeBuild";
+  HookStage["AFTER_BUILD"] = "afterBuild";
+  HookStage["BEFORE_ASSET_OPTIMIZE"] = "beforeAssetOptimize";
+  HookStage["AFTER_ASSET_OPTIMIZE"] = "afterAssetOptimize";
+  HookStage["BEFORE_RENDER"] = "beforeRender";
+  HookStage["AFTER_RENDER"] = "afterRender";
+  // Request lifecycle
+  HookStage["BEFORE_REQUEST"] = "beforeRequest";
+  HookStage["AFTER_REQUEST"] = "afterRequest";
+  // Response generation
+  HookStage["BEFORE_RESPONSE"] = "beforeResponse";
+  HookStage["AFTER_RESPONSE"] = "afterResponse";
+  // Cache operations
+  HookStage["BEFORE_CACHE"] = "beforeCache";
+  HookStage["AFTER_CACHE"] = "afterCache";
+  // Custom stage (plugins can register their own)
+  HookStage["CUSTOM"] = "custom";
+})(HookStage || (HookStage = {}));

package/templates/static/lib/runtime/client-runtime.js

@@ -1,28 +1,25 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
+/**
+ * Retrieve framework data injected by the server into the page HTML.
+ * The server embeds loader result data, route params, and query parameters
+ * into a hidden DOM element with id "__FRAMEWORK_DATA__" as JSON.
  *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
+ * This data is passed to page components during hydration as props.
+ * Returns null if the element does not exist or JSON is malformed,
+ * allowing graceful degradation without throwing errors.
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
+ * Usage:
+ *   const data = getFrameworkData();
+ *   // data = { data: {...}, params: {...}, query: {...} }
  *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ * @returns Framework data object { data, params, query } or null if not found.
  */
 export function getFrameworkData() {
-    const el = document.getElementById("__FRAMEWORK_DATA__");
-    if (!el)
-        return null;
-    try {
-        return JSON.parse(el.textContent || "null");
-    }
-    catch {
-        return null;
-    }
+  const el = document.getElementById("__FRAMEWORK_DATA__");
+  if (!el) return null;
+  try {
+    return JSON.parse(el.textContent || "null");
+  } catch {
+    // Silently return null if JSON is invalid; page hydrates with default props
+    return null;
+  }
 }

package/templates/static/lib/runtime/hmr.js

@@ -1,22 +1,24 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
+/**
+ * Client-side Hot Module Replacement (HMR) / Live Reload code.
+ * This script is injected into the browser during development mode.
  *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
+ * Features:
+ * - Establishes Server-Sent Events (SSE) connection to /__hmr endpoint
+ * - Listens for "reload" events (full page reload on route/component changes)
+ * - Listens for "style-update" events (CSS updates without full reload)
+ * - Automatically retries connection if lost
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
+ * The script uses IIFE (Immediately Invoked Function Expression) to avoid
+ * polluting the global scope.
  *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ * How it works:
+ * 1. Server watches file system for changes
+ * 2. On change, server sends SSE event to clients
+ * 3. Client receives event and either reloads or updates CSS
+ * 4. CSS updates use cache-busting query params to force fresh load
+ *
+ * Only injected in development mode; production builds do not include this.
  */
-// Client-side Hot Module Replacement (HMR) / Live Reload
-// Injected into the browser during development
 export const HMR_CLIENT_SCRIPT = `
 (function() {
   console.log("[Jen.js] Connecting to HMR...");
@@ -24,21 +26,23 @@ export const HMR_CLIENT_SCRIPT = `
 
   evt.onopen = () => console.log("[Jen.js] HMR Connected");
 
+  // Full page reload on route or component changes
   evt.addEventListener("reload", () => {
     console.log("[Jen.js] Reloading...");
     window.location.reload();
   });
 
+  // CSS-only reload without full page reload (faster UX for style-only changes)
   evt.addEventListener("style-update", (e) => {
     const file = JSON.parse(e.data).file; // e.g., "styles.css"
     console.log("[Jen.js] Style update:", file);
     
-    // Find matching link tags
+    // Find matching link tags by pathname
     const links = document.querySelectorAll('link[rel="stylesheet"]');
     for (const link of links) {
       const url = new URL(link.href);
       if (url.pathname.endsWith(file)) {
-        // Force reload by updating query param
+        // Force reload by updating cache-busting query param (timestamp)
         url.searchParams.set("t", Date.now());
         link.href = url.toString();
         console.log("[Jen.js] Updated stylesheet:", file);
@@ -47,8 +51,9 @@ export const HMR_CLIENT_SCRIPT = `
   });
 
   evt.onerror = () => {
+    // Connection closed; EventSource automatically retries
+    // (commented out: chatty in development; uncomment if needed for debugging)
     // console.log("[Jen.js] HMR disconnected, retrying...");
-    // EventSource automatically retries
   };
 })();
 `;

package/templates/static/lib/runtime/hydrate.js

@@ -1,45 +1,55 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
+import { hydrate } from "preact";
+import { h } from "preact";
+import { getFrameworkData } from "./client-runtime.js";
+/**
+ * Hydrate a server-rendered page with client-side interactivity.
+ * This function is called once on page load in the browser.
+ * It attaches Preact event listeners and state management to existing DOM without re-rendering.
  *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
+ * Flow:
+ * 1. Retrieve framework data (loader result, route params, query) injected by server into page HTML
+ * 2. Dynamically import the route component module
+ * 3. Construct Preact component tree passing data as props
+ * 4. Attach to existing #app element (matches server-rendered HTML structure)
  *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
+ * Errors during hydration are logged but do not throw; the page remains functional
+ * with reduced interactivity if hydration fails.
  *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ * @param entryPath - Path to the route component module (e.g., "./routes/index.js")
+ *   This path is typically injected into the HTML as a script attribute by the server.
  */
-import { hydrate } from "preact";
-import { h } from "preact";
-import { getFrameworkData } from "./client-runtime.js";
 export async function hydrateClient(entryPath) {
-    try {
-        const data = getFrameworkData();
-        const mod = await import(entryPath);
-        if (!mod.default) {
-            console.error(`Failed to hydrate: route module does not export default component`);
-            return;
-        }
-        const Page = mod.default;
-        const app = h(Page, {
-            data: data?.data ?? null,
-            params: data?.params ?? {},
-            query: data?.query ?? {},
-        });
-        const root = document.getElementById("app");
-        if (!root) {
-            console.error("Failed to hydrate: #app element not found in DOM");
-            return;
-        }
-        hydrate(app, root);
+  try {
+    // Retrieve loader data, params, and query injected into page HTML by server
+    const data = getFrameworkData();
+    // Dynamically import route component
+    const mod = await import(entryPath);
+    // Validate that route exports a default component
+    if (!mod.default) {
+      console.error(
+        `Failed to hydrate: route module does not export default component`,
+      );
+      return;
     }
-    catch (err) {
-        console.error("Hydration failed:", err instanceof Error ? err.message : String(err));
+    // Construct Preact VDOM tree with data as props
+    const Page = mod.default;
+    const app = h(Page, {
+      data: data?.data ?? null,
+      params: data?.params ?? {},
+      query: data?.query ?? {},
+    });
+    // Find root DOM element for hydration
+    const root = document.getElementById("app");
+    if (!root) {
+      console.error("Failed to hydrate: #app element not found in DOM");
+      return;
     }
+    // Attach Preact to existing DOM tree without re-rendering
+    hydrate(app, root);
+  } catch (err) {
+    console.error(
+      "Hydration failed:",
+      err instanceof Error ? err.message : String(err),
+    );
+  }
 }