create-jen-app 1.2.2 → 1.2.4

package/templates/ssr-isr/lib/auth/jwt.js

@@ -0,0 +1,57 @@
+/**
+ * JWT token utilities for creating and validating JSON Web Tokens.
+ * This module provides stub implementations that require an external JWT library.
+ * Users must install a JWT library (e.g., jsonwebtoken) and implement these functions
+ * using that library's APIs to enable authentication features.
+ *
+ * The module validates that JWT_SECRET is configured in the environment,
+ * ensuring token signing and verification can proceed securely.
+ */
+// JWT signing and verification require an external library not included by default.
+// Users should install jsonwebtoken: npm install jsonwebtoken
+const SECRET = process.env.JWT_SECRET;
+// Validate that JWT_SECRET is set. This environment variable is required for all token operations.
+// Without a secret, tokens cannot be securely signed or verified.
+if (!SECRET) {
+  throw new Error(
+    "CRITICAL: JWT_SECRET environment variable is required. Set JWT_SECRET in your .env file or environment.",
+  );
+}
+/**
+ * Creates a signed JWT token containing the provided payload.
+ * This function is a stub that requires implementing with an external JWT library.
+ *
+ * @param payload The data to encode in the token.
+ * @param expiresIn Token expiration time (default "1h"). Format: "1h", "7d", "30s", etc.
+ * @returns The signed JWT token as a string.
+ * @throws Error indicating that a JWT library must be installed.
+ *
+ * @example
+ * const token = signToken({ userId: 123, role: 'admin' }, '24h');
+ * // Implementation using jsonwebtoken:
+ * // jwt.sign(payload, SECRET, { expiresIn });
+ */
+export function signToken(payload, expiresIn = "1h") {
+  throw new Error(
+    "JWT implementation requires external library. Install: npm install jsonwebtoken",
+  );
+}
+/**
+ * Verifies and decodes a JWT token, returning the payload if valid.
+ * This function is a stub that requires implementing with an external JWT library.
+ *
+ * @param token The JWT token string to verify.
+ * @returns The decoded payload from the token.
+ * @throws Error indicating that a JWT library must be installed.
+ * @throws Error if the token is invalid, expired, or fails verification.
+ *
+ * @example
+ * const payload = verifyToken(token);
+ * // Implementation using jsonwebtoken:
+ * // jwt.verify(token, SECRET);
+ */
+export function verifyToken(token) {
+  throw new Error(
+    "JWT implementation requires external library. Install: npm install jsonwebtoken",
+  );
+}

package/templates/ssr-isr/lib/auth/session.d.ts

@@ -0,0 +1,44 @@
+interface SessionData {
+  userId: string;
+  createdAt: number;
+  expiresAt: number;
+  [key: string]: any;
+}
+/**
+ * In-memory session manager
+ * WARNING: Sessions are lost on server restart
+ * For production, use persistent storage (Redis, Database, etc.)
+ */
+export declare class SessionManager {
+  private sessions;
+  constructor();
+  /**
+   * Create a new session with automatic expiration
+   */
+  createSession(userId: string, data?: Record<string, any>): string;
+  /**
+   * Get session with expiration check
+   */
+  getSession(sessionId: string): SessionData | null;
+  /**
+   * Destroy session immediately
+   */
+  destroySession(sessionId: string): void;
+  /**
+   * Verify session is valid and return user ID
+   */
+  verifySession(sessionId: string): string | null;
+  /**
+   * Update session expiration
+   */
+  refreshSession(sessionId: string): boolean;
+  /**
+   * Generate cryptographically secure session ID
+   */
+  private generateSecureSessionId;
+  /**
+   * Clean up expired sessions
+   */
+  private cleanupExpiredSessions;
+}
+export {};

package/templates/ssr-isr/lib/auth/session.js

@@ -0,0 +1,92 @@
+const SESSION_TIMEOUT = parseInt(process.env.SESSION_TIMEOUT ?? "86400000", 10); // 24 hours default
+/**
+ * In-memory session manager
+ * WARNING: Sessions are lost on server restart
+ * For production, use persistent storage (Redis, Database, etc.)
+ */
+export class SessionManager {
+  sessions = new Map();
+  constructor() {
+    // Cleanup expired sessions every 30 minutes
+    setInterval(() => this.cleanupExpiredSessions(), 30 * 60 * 1000);
+  }
+  /**
+   * Create a new session with automatic expiration
+   */
+  createSession(userId, data = {}) {
+    // Validate userId
+    if (!userId || typeof userId !== "string" || userId.length > 255) {
+      throw new Error("Invalid userId");
+    }
+    const sessionId = this.generateSecureSessionId();
+    const now = Date.now();
+    const session = {
+      userId,
+      createdAt: now,
+      expiresAt: now + SESSION_TIMEOUT,
+      ...data,
+    };
+    this.sessions.set(sessionId, session);
+    return sessionId;
+  }
+  /**
+   * Get session with expiration check
+   */
+  getSession(sessionId) {
+    if (!sessionId) return null;
+    const session = this.sessions.get(sessionId);
+    if (!session) return null;
+    // Check if session expired
+    if (Date.now() > session.expiresAt) {
+      this.sessions.delete(sessionId);
+      return null;
+    }
+    return session;
+  }
+  /**
+   * Destroy session immediately
+   */
+  destroySession(sessionId) {
+    this.sessions.delete(sessionId);
+  }
+  /**
+   * Verify session is valid and return user ID
+   */
+  verifySession(sessionId) {
+    const session = this.getSession(sessionId);
+    return session?.userId ?? null;
+  }
+  /**
+   * Update session expiration
+   */
+  refreshSession(sessionId) {
+    const session = this.getSession(sessionId);
+    if (!session) return false;
+    session.expiresAt = Date.now() + SESSION_TIMEOUT;
+    return true;
+  }
+  /**
+   * Generate cryptographically secure session ID
+   */
+  generateSecureSessionId() {
+    // In production, use crypto.randomBytes
+    const chars =
+      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    let result = "";
+    for (let i = 0; i < 32; i++) {
+      result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+  }
+  /**
+   * Clean up expired sessions
+   */
+  cleanupExpiredSessions() {
+    const now = Date.now();
+    for (const [sessionId, session] of this.sessions.entries()) {
+      if (now > session.expiresAt) {
+        this.sessions.delete(sessionId);
+      }
+    }
+  }
+}

package/templates/ssr-isr/lib/build/asset-hashing.d.ts

@@ -0,0 +1,10 @@
+export declare class AssetHasher {
+  /**
+   * Calculate hash of file content
+   */
+  static hashContent(content: string | Buffer): string;
+  /**
+   * Rename file to include hash (e.g. style.css -> style.a1b2c3.css)
+   */
+  static hashFile(filePath: string): string;
+}

package/templates/ssr-isr/lib/build/asset-hashing.js

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+import { readFileSync, renameSync } from "node:fs";
+import { join, dirname, basename, extname } from "node:path";
+export class AssetHasher {
+  /**
+   * Calculate hash of file content
+   */
+  static hashContent(content) {
+    return createHash("md5").update(content).digest("hex").slice(0, 10);
+  }
+  /**
+   * Rename file to include hash (e.g. style.css -> style.a1b2c3.css)
+   */
+  static hashFile(filePath) {
+    const content = readFileSync(filePath);
+    const hash = this.hashContent(content);
+    const dir = dirname(filePath);
+    const ext = extname(filePath);
+    const name = basename(filePath, ext);
+    const newName = `${name}.${hash}${ext}`;
+    const newPath = join(dir, newName);
+    renameSync(filePath, newPath);
+    return newName;
+  }
+}

package/templates/ssr-isr/lib/build/asset-manifest.d.ts

@@ -0,0 +1,11 @@
+export interface Manifest {
+  [key: string]: string;
+}
+export declare class AssetManifest {
+  private manifest;
+  private manifestPath;
+  constructor(distDir: string);
+  set(original: string, hashed: string): void;
+  get(original: string): string | undefined;
+  save(): void;
+}

package/templates/ssr-isr/lib/build/asset-manifest.js

@@ -0,0 +1,21 @@
+import { writeFileSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+export class AssetManifest {
+  manifest = {};
+  manifestPath;
+  constructor(distDir) {
+    this.manifestPath = join(distDir, "manifest.json");
+    if (existsSync(this.manifestPath)) {
+      this.manifest = JSON.parse(readFileSync(this.manifestPath, "utf8"));
+    }
+  }
+  set(original, hashed) {
+    this.manifest[original] = hashed;
+  }
+  get(original) {
+    return this.manifest[original];
+  }
+  save() {
+    writeFileSync(this.manifestPath, JSON.stringify(this.manifest, null, 2));
+  }
+}

package/templates/ssr-isr/lib/build/build.d.ts

@@ -0,0 +1,24 @@
+import type { FrameworkConfig } from "../core/config.js";
+/**
+ * Builds a static site by pre-rendering all routes to HTML files.
+ * This is the core static site generation (SSG) function that runs at build time.
+ * It performs the following steps:
+ * 1. Clears the previous build output directory
+ * 2. Discovers all route files in the configured site directory
+ * 3. Renders each route to a static HTML file
+ * 4. Copies static assets from the source directory
+ * 5. Bundles Vue and Svelte components for client-side rehydration
+ * 6. Compiles SCSS to CSS for the global stylesheet
+ *
+ * Routes are rendered with empty req/res objects (SSG mode) to avoid middleware execution.
+ * This produces pure static HTML that can be served by any web server.
+ * Hydration scripts are still injected if the route has hydrate:true, allowing for
+ * optional client-side interactivity in otherwise static pages.
+ *
+ * @param opts Configuration object.
+ * @param opts.config The Jen.js framework configuration.
+ * @throws Logs warnings for missing assets or component bundling failures but does not stop the build.
+ */
+export declare function buildSite(opts: {
+  config: FrameworkConfig;
+}): Promise<void>;

package/templates/ssr-isr/lib/build/build.js

@@ -0,0 +1,141 @@
+import {
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  existsSync,
+  copyFileSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import esbuild from "esbuild";
+import { createScssCompiler } from "../css/compiler.js";
+import {
+  vueEsbuildPlugin,
+  svelteEsbuildPlugin,
+} from "../compilers/esbuild-plugins.js";
+import { scanRoutes } from "../core/routes/scan.js";
+import { resolveDistPath } from "../core/paths.js";
+import { log } from "../shared/log.js";
+import { renderRouteToHtml } from "../runtime/render.js";
+/**
+ * Recursively copies a directory and all its contents.
+ * Used to copy static assets from the source directory to the build output.
+ * Creates the destination directory structure as needed.
+ *
+ * @param src The source directory path.
+ * @param dst The destination directory path.
+ */
+function copyDir(src, dst) {
+  if (!existsSync(src)) return;
+  mkdirSync(dst, { recursive: true });
+  for (const name of readdirSync(src)) {
+    const sp = join(src, name);
+    const dp = join(dst, name);
+    const st = statSync(sp);
+    if (st.isDirectory()) copyDir(sp, dp);
+    else copyFileSync(sp, dp);
+  }
+}
+/**
+ * Builds a static site by pre-rendering all routes to HTML files.
+ * This is the core static site generation (SSG) function that runs at build time.
+ * It performs the following steps:
+ * 1. Clears the previous build output directory
+ * 2. Discovers all route files in the configured site directory
+ * 3. Renders each route to a static HTML file
+ * 4. Copies static assets from the source directory
+ * 5. Bundles Vue and Svelte components for client-side rehydration
+ * 6. Compiles SCSS to CSS for the global stylesheet
+ *
+ * Routes are rendered with empty req/res objects (SSG mode) to avoid middleware execution.
+ * This produces pure static HTML that can be served by any web server.
+ * Hydration scripts are still injected if the route has hydrate:true, allowing for
+ * optional client-side interactivity in otherwise static pages.
+ *
+ * @param opts Configuration object.
+ * @param opts.config The Jen.js framework configuration.
+ * @throws Logs warnings for missing assets or component bundling failures but does not stop the build.
+ */
+export async function buildSite(opts) {
+  const { config } = opts;
+  // Clear and recreate the dist directory for a clean build.
+  const dist = resolveDistPath(config);
+  rmSync(dist, { recursive: true, force: true });
+  mkdirSync(dist, { recursive: true });
+  // Discover all routes and pre-render each to a static HTML file.
+  const routes = scanRoutes(config);
+  log.info(`Building SSG: ${routes.length} routes`);
+  for (const r of routes) {
+    // Create a synthetic URL for each route. Used as the request URL during rendering.
+    const url = new URL("http://localhost" + r.urlPath);
+    // Render the route to HTML. Empty req/res indicates SSG mode (no middleware execution).
+    const html = await renderRouteToHtml({
+      config,
+      route: r,
+      req: {},
+      res: {},
+      url,
+      params: {},
+      query: {},
+      headers: {},
+      cookies: {},
+    });
+    // Calculate output path. Root route goes to index.html, nested routes get their own directories.
+    const outPath =
+      r.urlPath === "/"
+        ? join(dist, "index.html")
+        : join(dist, r.urlPath.slice(1), "index.html");
+    mkdirSync(join(outPath, ".."), { recursive: true });
+    writeFileSync(outPath, html, "utf8");
+    log.info(`SSG: ${r.urlPath} -> ${outPath}`);
+  }
+  // Copy static assets from the source assets directory to the built site.
+  copyDir(join(process.cwd(), config.siteDir, "assets"), join(dist, "assets"));
+  // Bundle Vue and Svelte components found in the site directory.
+  // These are transpiled to JavaScript modules for client-side use in interactive pages.
+  const siteSourceDir = join(process.cwd(), config.siteDir);
+  const vueFiles = readdirSync(siteSourceDir, { recursive: true }).filter(
+    (f) => String(f).endsWith(".vue") || String(f).endsWith(".svelte"),
+  );
+  if (vueFiles.length > 0) {
+    log.info(`Found ${vueFiles.length} Vue/Svelte components, bundling...`);
+    try {
+      await esbuild.build({
+        entryPoints: vueFiles.map((f) => join(siteSourceDir, String(f))),
+        outdir: join(dist, "components"),
+        format: "esm",
+        target: "es2022",
+        bundle: false,
+        plugins: [vueEsbuildPlugin(), svelteEsbuildPlugin()],
+        external: ["preact", "vue", "svelte"],
+        logLevel: "info",
+      });
+      log.info("Vue/Svelte components bundled successfully.");
+    } catch (err) {
+      log.warn(`Failed to bundle Vue/Svelte components: ${err.message}`);
+    }
+  }
+  // Compile the global SCSS file to CSS.
+  // This stylesheet is injected into every page and contains framework-wide styles.
+  // Minification is enabled for production builds.
+  const scssPath = join(process.cwd(), config.css.globalScss);
+  if (existsSync(scssPath)) {
+    const compiler = createScssCompiler();
+    const result = compiler.compile({
+      inputPath: scssPath,
+      minified: true,
+    });
+    if (result.error) {
+      log.error(`SCSS Compilation Failed: ${result.error}`);
+      writeFileSync(join(dist, "styles.css"), "/* SCSS Compilation Failed */");
+    } else {
+      writeFileSync(join(dist, "styles.css"), result.css);
+      log.info(`Compiled global SCSS: ${config.css.globalScss}`);
+    }
+  } else {
+    log.warn(`Global SCSS file not found: ${scssPath}`);
+    writeFileSync(join(dist, "styles.css"), "/* No global SCSS found */");
+  }
+  log.info("Build complete.");
+}

package/templates/{static → ssr-isr}/lib/build/island-hydration.d.ts

@@ -1,10 +1,10 @@
 export interface Island {
-    id: string;
-    component: string;
-    props: any;
+  id: string;
+  component: string;
+  props: any;
 }
 export interface IslandRegistry {
-    islands: Island[];
+  islands: Island[];
 }
 /**
  * Creates an empty island registry for a request
@@ -22,4 +22,7 @@ export declare function extractIslandsFromHtml(html: string): Island[];
 /**
  * Inject hydration script into HTML
  */
-export declare function injectIslandScript(html: string, islands: Island[]): string;
+export declare function injectIslandScript(
+  html: string,
+  islands: Island[],
+): string;

package/templates/ssr-isr/lib/build/island-hydration.js

@@ -0,0 +1,44 @@
+/**
+ * Creates an empty island registry for a request
+ */
+export function createIslandRegistry() {
+  return { islands: [] };
+}
+/**
+ * Mark a component as an island (placeholder implementation)
+ * In a real framework, this would be a decorator or a HOC
+ */
+export function markIsland(name, props) {
+  const id = `island-${Math.random().toString(36).slice(2, 9)}`;
+  return `<div data-island="${name}" data-props='${JSON.stringify(props)}' id="${id}"></div>`;
+}
+/**
+ * Extract islands from HTML string
+ */
+export function extractIslandsFromHtml(html) {
+  const islands = [];
+  const regex = /data-island="([^"]+)" data-props='([^']+)' id="([^"]+)"/g;
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    islands.push({
+      component: match[1],
+      props: JSON.parse(match[2]),
+      id: match[3],
+    });
+  }
+  return islands;
+}
+/**
+ * Inject hydration script into HTML
+ */
+export function injectIslandScript(html, islands) {
+  if (islands.length === 0) return html;
+  const script = `
+    <script type="module">
+      import { hydrate } from '/__runtime/hydrate.js';
+      const islands = ${JSON.stringify(islands)};
+      islands.forEach(i => hydrate(i.component, i.id, i.props));
+    </script>
+  `;
+  return html.replace("</body>", `${script}</body>`);
+}

package/templates/ssr-isr/lib/build/minifier.d.ts

@@ -0,0 +1,20 @@
+export interface MinifyOptions {
+  minifyIdentifiers?: boolean;
+  minifySyntax?: boolean;
+  minifyWhitespace?: boolean;
+  target?: string | string[];
+}
+export declare class Minifier {
+  /**
+   * Minify JavaScript/TypeScript using esbuild
+   */
+  static minifyJs(code: string, options?: MinifyOptions): Promise<string>;
+  /**
+   * Minify CSS using esbuild
+   */
+  static minifyCss(code: string): Promise<string>;
+  /**
+   * Minify HTML (basic regex/string-based, as esbuild doesn't handle HTML)
+   */
+  static minifyHtml(html: string): string;
+}

package/templates/ssr-isr/lib/build/minifier.js

@@ -0,0 +1,46 @@
+import * as esbuild from "esbuild";
+import { log } from "../shared/log.js";
+export class Minifier {
+  /**
+   * Minify JavaScript/TypeScript using esbuild
+   */
+  static async minifyJs(code, options = {}) {
+    try {
+      const result = await esbuild.transform(code, {
+        loader: "js",
+        minify: true,
+        legalComments: "none",
+        ...options,
+      });
+      return result.code;
+    } catch (err) {
+      log.error("Minification failed (JS)");
+      throw err;
+    }
+  }
+  /**
+   * Minify CSS using esbuild
+   */
+  static async minifyCss(code) {
+    try {
+      const result = await esbuild.transform(code, {
+        loader: "css",
+        minify: true,
+      });
+      return result.code;
+    } catch (err) {
+      log.error("Minification failed (CSS)");
+      throw err;
+    }
+  }
+  /**
+   * Minify HTML (basic regex/string-based, as esbuild doesn't handle HTML)
+   */
+  static minifyHtml(html) {
+    return html
+      .replace(/<!--[\s\S]*?-->/g, "") // Remove comments
+      .replace(/>\s+</g, "><") // Remove whitespace between tags
+      .replace(/\s{2,}/g, " ") // Collapse multiple whitespaces
+      .trim();
+  }
+}

package/templates/ssr-isr/lib/build/page-renderer.d.ts

@@ -0,0 +1,17 @@
+import { FrameworkConfig } from "../core/config.js";
+import { RouteEntry } from "../core/routes/scan.js";
+export interface PageRenderContext {
+  config: FrameworkConfig;
+  route: RouteEntry;
+  url: URL;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+}
+export declare class PageRenderer {
+  /**
+   * Render a route to a full HTML string, including minification if requested
+   */
+  static render(ctx: PageRenderContext, minify?: boolean): Promise<string>;
+}

package/templates/ssr-isr/lib/build/page-renderer.js

@@ -0,0 +1,28 @@
+import { renderRouteToHtml } from "../runtime/render.js";
+import { Minifier } from "./minifier.js";
+export class PageRenderer {
+  /**
+   * Render a route to a full HTML string, including minification if requested
+   */
+  static async render(ctx, minify = false) {
+    // 1. Core Preact render
+    let html = await renderRouteToHtml({
+      config: ctx.config,
+      route: ctx.route,
+      req: {},
+      res: {},
+      url: ctx.url,
+      params: ctx.params,
+      query: ctx.query,
+      headers: ctx.headers,
+      cookies: ctx.cookies,
+    });
+    // 2. Post-processing (Layout injection, hydration script injection)
+    // Note: Hydration logic is handled by island-hydration.ts usually
+    // 3. Optional Minification
+    if (minify) {
+      html = Minifier.minifyHtml(html);
+    }
+    return html;
+  }
+}

package/templates/ssr-isr/lib/build/production-build.d.ts

@@ -0,0 +1,10 @@
+import { FrameworkConfig } from "../core/config.js";
+export interface ProductionBuildConfig {
+  config: FrameworkConfig;
+}
+export declare class ProductionBuilder {
+  /**
+   * Run the production build sequence
+   */
+  static build(opts: ProductionBuildConfig): Promise<void>;
+}

package/templates/ssr-isr/lib/build/production-build.js

@@ -0,0 +1,13 @@
+import { SSGPipeline } from "./ssg-pipeline.js";
+import { log } from "../shared/log.js";
+export class ProductionBuilder {
+  /**
+   * Run the production build sequence
+   */
+  static async build(opts) {
+    log.info("--- PRODUCTION BUILD START ---");
+    const pipeline = new SSGPipeline(opts.config);
+    await pipeline.run();
+    log.info("--- PRODUCTION BUILD COMPLETE ---");
+  }
+}

package/templates/ssr-isr/lib/build/ssg-pipeline.d.ts

@@ -0,0 +1,15 @@
+import { FrameworkConfig } from "../core/config.js";
+export declare class SSGPipeline {
+  private config;
+  private dist;
+  constructor(config: FrameworkConfig);
+  /**
+   * Run the full SSG Pipeline
+   */
+  run(): Promise<void>;
+  private prepareDist;
+  private processAssets;
+  private compileStyles;
+  private renderPages;
+  private copyRecursive;
+}