create-jen-app 1.2.2 → 1.2.4

package/templates/static/lib/core/paths.js

@@ -1,24 +1,39 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
+import { join } from "node:path";
+/**
+ * Resolve an absolute path relative to the configured site directory.
+ * Used throughout the framework to locate source files, assets, pages, and other site content.
  *
- * 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.
+ * The site directory is typically where user-written code (pages, routes, components, etc.) resides.
+ * This function ensures consistent path resolution across different environments and working directories.
  *
- * 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.
+ * @param config Framework configuration object containing the siteDir path.
+ * @param p Path segments to join with the site directory. Can be multiple arguments.
+ * @returns Absolute file system path.
  *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ * @example
+ * const config = { siteDir: 'src' };
+ * resolveSitePath(config, 'pages', 'index.tsx');
+ * // Returns: /absolute/path/to/project/src/pages/index.tsx
  */
-import { join } from "node:path";
 export function resolveSitePath(config, ...p) {
-    return join(process.cwd(), config.siteDir, ...p);
+  return join(process.cwd(), config.siteDir, ...p);
 }
+/**
+ * Resolve an absolute path relative to the configured distribution/build output directory.
+ * Used to locate compiled assets, static files, and build artifacts.
+ *
+ * The distribution directory contains the output of the build process: compiled HTML,
+ * CSS, JavaScript bundles, and other files ready for deployment or serving.
+ *
+ * @param config Framework configuration object containing the distDir path.
+ * @param p Path segments to join with the dist directory. Can be multiple arguments.
+ * @returns Absolute file system path.
+ *
+ * @example
+ * const config = { distDir: 'dist' };
+ * resolveDistPath(config, 'styles.css');
+ * // Returns: /absolute/path/to/project/dist/styles.css
+ */
 export function resolveDistPath(config, ...p) {
-    return join(process.cwd(), config.distDir, ...p);
+  return join(process.cwd(), config.distDir, ...p);
 }

package/templates/static/lib/core/routes/advanced.js

@@ -0,0 +1,114 @@
+/**
+ * Cache for storing evaluated route configurations
+ */
+const advancedConfigCache = new Map();
+/**
+ * Extract advanced routing config from a route module
+ *
+ * @param module Route module
+ * @returns Advanced route configuration
+ */
+export function extractAdvancedConfig(module) {
+  return module?.routeConfig ?? {};
+}
+/**
+ * Get advanced route config with caching
+ *
+ * @param filePath Route file path
+ * @returns Cached or newly evaluated config
+ */
+export async function getAdvancedRouteConfig(filePath) {
+  if (advancedConfigCache.has(filePath)) {
+    return advancedConfigCache.get(filePath);
+  }
+  try {
+    const module = await import(`file://${filePath}`);
+    const config = extractAdvancedConfig(module);
+    advancedConfigCache.set(filePath, config);
+    return config;
+  } catch {
+    const config = {};
+    advancedConfigCache.set(filePath, config);
+    return config;
+  }
+}
+/**
+ * Synchronously get advanced route config
+ *
+ * @param filePath Route file path
+ * @returns Configuration (empty if unavailable)
+ */
+export function getAdvancedRouteConfigSync(filePath) {
+  if (advancedConfigCache.has(filePath)) {
+    return advancedConfigCache.get(filePath);
+  }
+  const config = {};
+  advancedConfigCache.set(filePath, config);
+  return config;
+}
+/**
+ * Clear the advanced config cache
+ */
+export function clearAdvancedConfigCache() {
+  advancedConfigCache.clear();
+}
+/**
+ * Validate query parameters against a schema
+ *
+ * @param query Parsed query parameters
+ * @param schema Validation rules
+ * @returns { valid: boolean; errors: string[] }
+ */
+export function validateQueryParams(query, schema) {
+  const errors = [];
+  for (const [key, rule] of Object.entries(schema)) {
+    const value = query[key];
+    // Check required
+    if (rule.required && !value) {
+      errors.push(`Query parameter '${key}' is required`);
+      continue;
+    }
+    if (!value) continue;
+    // Check type
+    if (rule.type === "number" && isNaN(Number(value))) {
+      errors.push(`Query parameter '${key}' must be a number`);
+    }
+    if (rule.type === "boolean" && !["true", "false"].includes(value)) {
+      errors.push(`Query parameter '${key}' must be 'true' or 'false'`);
+    }
+    // Check enum
+    if (rule.enum && !rule.enum.includes(value)) {
+      errors.push(
+        `Query parameter '${key}' must be one of: ${rule.enum.join(", ")}`,
+      );
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+/**
+ * Apply defaults and coerce query parameters
+ *
+ * @param query Raw query parameters
+ * @param schema Validation schema
+ * @returns Processed query parameters
+ */
+export function processQueryParams(query, schema) {
+  const processed = { ...query };
+  for (const [key, rule] of Object.entries(schema)) {
+    let value = processed[key];
+    // Apply default
+    if (!value && rule.default !== undefined) {
+      value = rule.default;
+      processed[key] = value;
+    }
+    // Coerce type
+    if (value) {
+      if (rule.type === "number") {
+        processed[key] = Number(value);
+      } else if (rule.type === "boolean") {
+        processed[key] = value === "true";
+      }
+    }
+  }
+  return processed;
+}

package/templates/static/lib/core/routes/handlers.js

@@ -0,0 +1,181 @@
+import { scanRoutes } from "./scan.js";
+/**
+ * Handles redirects configured at the application level
+ *
+ * @param pathname URL path to check
+ * @param redirects Array of redirect configurations
+ * @returns Redirect target or null
+ *
+ * @example
+ * const redirect = getRedirect("/old-page", [
+ *   { from: "/old-page", to: "/new-page", status: 301 }
+ * ]);
+ * // Returns: { to: "/new-page", status: 301 }
+ */
+export function getRedirect(pathname, redirects) {
+  for (const r of redirects) {
+    // Exact match
+    if (r.from === pathname) {
+      return { to: r.to, status: r.status ?? 301 };
+    }
+    // Prefix match (for pattern-based redirects)
+    if (r.from.endsWith("*")) {
+      const prefix = r.from.slice(0, -1);
+      if (pathname.startsWith(prefix)) {
+        // Preserve the remaining path
+        const remaining = pathname.slice(prefix.length);
+        const target = r.to.endsWith("*")
+          ? r.to.slice(0, -1) + remaining
+          : r.to;
+        return { to: target, status: r.status ?? 301 };
+      }
+    }
+  }
+  return null;
+}
+/**
+ * Send a redirect response
+ *
+ * @param res ServerResponse object
+ * @param location Target URL
+ * @param status HTTP status code (default 301)
+ */
+export function sendRedirect(res, location, status = 301) {
+  res.statusCode = status;
+  res.setHeader("Location", location);
+  res.setHeader("content-type", "text/plain; charset=utf-8");
+  res.end(`Redirecting to ${location}`);
+}
+/**
+ * Send a 404 response with optional custom handler
+ *
+ * @param res ServerResponse object
+ * @param config 404 handler configuration
+ * @param pathname The path that was not found
+ */
+export function send404(res, config, pathname) {
+  res.statusCode = 404;
+  // Prefer JSON response if available
+  if (config.json) {
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(config.json));
+    return;
+  }
+  // Fallback to HTML
+  if (config.html) {
+    res.setHeader("content-type", "text/html; charset=utf-8");
+    res.end(config.html);
+    return;
+  }
+  // Default 404 response
+  res.setHeader("content-type", "text/plain; charset=utf-8");
+  res.end(`404 Not Found: ${pathname}`);
+}
+/**
+ * Find a custom 404 handler for a given pathname
+ * Searches the route tree for a matching 404 handler route
+ *
+ * @param config Framework configuration
+ * @param pathname URL path that was not found
+ * @returns NotFoundConfig with appropriate handler or null
+ *
+ * @example
+ * // With routes:
+ * // - (home).tsx
+ * // - /docs/(...rest).tsx (handles docs with custom 404)
+ * // - /api/(...rest).tsx (handles api with custom 404)
+ *
+ * // getNotFoundHandler(config, "/api/unknown") returns handler for /api/(...rest)
+ */
+export function getNotFoundHandler(config, pathname) {
+  const routes = scanRoutes(config);
+  // Find catch-all routes that match this pathname
+  let bestMatch = null;
+  let bestMatchLength = 0;
+  for (const route of routes) {
+    // Check if this is a catch-all route
+    if (!route.urlPath.includes("*")) continue;
+    // Extract the prefix before the catch-all
+    const prefix = route.urlPath.split("*")[0];
+    if (!prefix) continue; // Skip root catch-all for now
+    // Check if pathname matches this prefix
+    if (pathname.startsWith(prefix)) {
+      if (prefix.length > bestMatchLength) {
+        bestMatch = route;
+        bestMatchLength = prefix.length;
+      }
+    }
+  }
+  if (bestMatch) {
+    return { handler: bestMatch };
+  }
+  return null;
+}
+/**
+ * Create a default 404 HTML page
+ *
+ * @param pathname Path that was not found
+ * @returns HTML string
+ */
+export function createDefault404Html(pathname) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>404 Not Found</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+      margin: 0;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    }
+    .container {
+      text-align: center;
+      background: white;
+      padding: 2rem;
+      border-radius: 8px;
+      box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+    }
+    h1 {
+      font-size: 3rem;
+      margin: 0;
+      color: #333;
+    }
+    p {
+      margin: 1rem 0 0 0;
+      color: #666;
+    }
+    .path {
+      font-family: monospace;
+      background: #f5f5f5;
+      padding: 0.5rem 1rem;
+      margin: 1rem 0;
+      border-radius: 4px;
+      color: #333;
+    }
+    a {
+      color: #667eea;
+      text-decoration: none;
+      margin-top: 1rem;
+      display: inline-block;
+    }
+    a:hover {
+      text-decoration: underline;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>404</h1>
+    <p>Page Not Found</p>
+    <div class="path">${pathname}</div>
+    <a href="/">Go Home</a>
+  </div>
+</body>
+</html>`;
+}

package/templates/static/lib/core/routes/match.js

@@ -1,31 +1,136 @@
-/*
- * This file is part of Jen.js.
- * Copyright (C) 2026 oopsio
+/**
+ * Custom error type for invalid route parameters
+ */
+export class InvalidRouteParamError extends Error {
+  constructor(paramName, paramValue, reason) {
+    super(`Invalid route parameter "${paramName}": ${reason}`);
+    this.name = "InvalidRouteParamError";
+  }
+}
+/**
+ * Validates a route parameter to prevent path traversal and injection attacks.
+ *
+ * Security checks:
+ * - Rejects ".." (directory traversal)
+ * - Rejects leading "/" (absolute paths)
+ * - Rejects null bytes (\0)
+ * - Rejects unicode encoding tricks (e.g., %2e%2e are decoded by decodeURIComponent first)
+ * - For catch-all routes (*rest), allows "/" and other separators but still rejects traversal
+ * - For regular params, only allows alphanumeric, underscore, hyphen, dot
  *
- * 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.
+ * @param paramName Parameter name (e.g., "id", "rest")
+ * @param paramValue The decoded parameter value
+ * @param isCatchAll Whether this is a catch-all route parameter (allows more characters)
+ * @throws InvalidRouteParamError if validation fails
+ */
+export function validateRouteParam(paramName, paramValue, isCatchAll = false) {
+  // Check for null bytes
+  if (paramValue.includes("\0")) {
+    throw new InvalidRouteParamError(
+      paramName,
+      paramValue,
+      "contains null bytes",
+    );
+  }
+  // Check for leading forward slash (absolute path)
+  if (paramValue.startsWith("/")) {
+    throw new InvalidRouteParamError(
+      paramName,
+      paramValue,
+      "cannot start with /",
+    );
+  }
+  // Check for directory traversal: ".." as a complete component or at any position
+  if (paramValue.includes("..")) {
+    throw new InvalidRouteParamError(
+      paramName,
+      paramValue,
+      "contains .. (directory traversal)",
+    );
+  }
+  // Check for backslash (Windows path separator) to prevent escaping
+  if (paramValue.includes("\\")) {
+    throw new InvalidRouteParamError(
+      paramName,
+      paramValue,
+      "contains backslash",
+    );
+  }
+  // For catch-all parameters, allow more flexible paths with /, but still reject dangerous patterns
+  if (isCatchAll) {
+    // Additional check: if someone passes %2e%2e or other encoded traversal, it's already decoded
+    // by decodeURIComponent, so the ".." check above will catch it. Just verify no empty path components
+    // that could indicate traversal (though ".." is already blocked above)
+    return;
+  }
+  // For regular route parameters, only allow safe characters
+  // Allow: alphanumeric, underscore, hyphen, dot
+  if (!/^[a-zA-Z0-9_.-]+$/.test(paramValue)) {
+    throw new InvalidRouteParamError(
+      paramName,
+      paramValue,
+      "contains invalid characters (only alphanumeric, underscore, hyphen, dot allowed)",
+    );
+  }
+}
+/**
+ * Matches a URL pathname against a list of routes and returns the matching route with extracted parameters.
  *
- * 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.
+ * Algorithm:
+ * 1. Iterate through routes in specificity order (most specific first)
+ * 2. For each route, compile its regex pattern and test against pathname
+ * 3. On first match, extract captured groups as parameters
+ * 4. URL-decode parameter values to handle special characters
+ * 5. Validate all parameters to prevent path traversal attacks
+ * 6. Return matched route and parameters
  *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ * Route specificity:
+ * - Static routes (no parameters) are tried before dynamic routes
+ * - Exact matches are preferred over catch-alls
+ * - This order is determined by scanRoutes() and must not be changed
+ *
+ * @param routes Array of RouteEntry objects from scanRoutes(), must be pre-sorted by specificity
+ * @param pathname URL path to match, e.g., "/posts/42" or "/docs/api/reference"
+ *
+ * @returns MatchResult object with matched route and parameters, or null if no route matches
+ * @throws InvalidRouteParamError if any parameter contains invalid/dangerous content
+ *
+ * @example
+ * const routes = scanRoutes(config);
+ * const match = matchRoute(routes, "/posts/42");
+ * if (match) {
+ *   console.log(match.route.urlPath);  // "/posts/:id"
+ *   console.log(match.params.id);       // "42"
+ * }
  */
 export function matchRoute(routes, pathname) {
-    for (const r of routes) {
-        const re = new RegExp(r.pattern);
-        const m = pathname.match(re);
-        if (!m)
-            continue;
-        const params = {};
-        for (let i = 0; i < r.paramNames.length; i++) {
-            params[r.paramNames[i]] = decodeURIComponent(m[i + 1] ?? "");
-        }
-        return { route: r, params };
+  for (const r of routes) {
+    const re = new RegExp(r.pattern);
+    const m = pathname.match(re);
+    if (!m) {
+      console.error(
+        `[Route Match] Pattern "${r.pattern}" did not match "${pathname}"`,
+      );
+      continue;
+    }
+    /**
+     * Extract captured groups from the regex match.
+     * Captured group 0 is the entire match; groups 1+ are the parameters.
+     * Each parameter name from r.paramNames corresponds to its regex group by index.
+     * URL-decode parameter values since they came from a URL path.
+     * Then validate each parameter to prevent path traversal attacks.
+     */
+    const params = {};
+    for (let i = 0; i < r.paramNames.length; i++) {
+      const paramName = r.paramNames[i];
+      const paramValue = decodeURIComponent(m[i + 1] ?? "");
+      // Determine if this is a catch-all parameter (typically named "rest" or ends with "*")
+      const isCatchAll = paramName === "rest" || r.pattern.includes("*");
+      // Validate the parameter to prevent path traversal and injection attacks
+      validateRouteParam(paramName, paramValue, isCatchAll);
+      params[paramName] = paramValue;
     }
-    return null;
+    return { route: r, params };
+  }
+  return null;
 }

package/templates/static/lib/core/routes/orchestrator.js

@@ -0,0 +1,171 @@
+import { matchRoute } from "./match.js";
+import {
+  getAdvancedRouteConfig,
+  validateQueryParams,
+  processQueryParams,
+} from "./advanced.js";
+import {
+  getRedirect,
+  getNotFoundHandler,
+  send404,
+  sendRedirect,
+  createDefault404Html,
+} from "./handlers.js";
+import { log } from "../../shared/log.js";
+/**
+ * Advanced routing orchestrator that handles:
+ * - Dynamic route matching with parameter extraction
+ * - Query parameter parsing and validation
+ * - Catch-all routes
+ * - Middleware guards
+ * - Redirects (app-level and route-level)
+ * - 404 handling
+ */
+export class AdvancedRouter {
+  routes;
+  config;
+  constructor(routes, config) {
+    this.routes = routes;
+    this.config = config;
+  }
+  /**
+   * Resolve a request pathname to a route match, redirect, or 404
+   *
+   * @param pathname URL pathname
+   * @param url Full URL object
+   * @param headers Request headers
+   * @param cookies Parsed cookies
+   * @returns Route resolution result
+   */
+  async resolve(pathname, url, headers, cookies) {
+    log.info(`[Router] Resolving: ${pathname}`);
+    // Step 1: Check application-level redirects
+    if (this.config.redirects) {
+      const redirect = getRedirect(pathname, this.config.redirects);
+      if (redirect) {
+        log.info(`[Router] Redirect: ${pathname} -> ${redirect.to}`);
+        return {
+          type: "redirect",
+          location: redirect.to,
+          status: redirect.status,
+        };
+      }
+    }
+    // Step 2: Match against routes
+    const match = matchRoute(this.routes, pathname);
+    if (!match) {
+      log.info(`[Router] No route match for: ${pathname}`);
+      return { type: "not_found", pathname };
+    }
+    // Parse query parameters
+    const query = {};
+    for (const [k, v] of url.searchParams.entries()) query[k] = v;
+    // Step 3: Load advanced route config
+    const advancedConfig = await getAdvancedRouteConfig(match.route.filePath);
+    // Step 4: Handle route-level redirects
+    if (advancedConfig.redirect) {
+      const guardCtx = {
+        route: match.route,
+        params: match.params,
+        query,
+        url,
+        headers,
+        cookies,
+      };
+      const target =
+        typeof advancedConfig.redirect.to === "function"
+          ? advancedConfig.redirect.to(guardCtx)
+          : advancedConfig.redirect.to;
+      const status = advancedConfig.redirect.status ?? 301;
+      log.info(`[Router] Route redirect: ${pathname} -> ${target} (${status})`);
+      return {
+        type: "redirect",
+        location: target,
+        status,
+      };
+    }
+    // Step 5: Validate query parameters
+    if (advancedConfig.querySchema) {
+      const validation = validateQueryParams(query, advancedConfig.querySchema);
+      if (!validation.valid) {
+        log.warn(
+          `[Router] Query validation failed: ${validation.errors.join(", ")}`,
+        );
+        // For now, log but don't block. In strict mode, this could return 400.
+      }
+      // Apply defaults and type coercion
+      const processed = processQueryParams(query, advancedConfig.querySchema);
+      Object.assign(query, processed);
+    }
+    // Step 6: Run middleware guards
+    if (advancedConfig.guards && advancedConfig.guards.length > 0) {
+      const guardCtx = {
+        route: match.route,
+        params: match.params,
+        query,
+        url,
+        headers,
+        cookies,
+      };
+      for (const guard of advancedConfig.guards) {
+        const result = await guard(guardCtx);
+        if (result !== true) {
+          // Guard blocked or redirected
+          log.info(
+            `[Router] Guard blocked: ${pathname} (status: ${result.status})`,
+          );
+          return {
+            type: "redirect",
+            location: result.location || "/",
+            status: result.status,
+          };
+        }
+      }
+    }
+    log.info(`[Router] Matched: ${pathname} -> ${match.route.urlPath}`);
+    return {
+      type: "matched",
+      route: match.route,
+      params: match.params,
+      query,
+    };
+  }
+  /**
+   * Handle a 404 response
+   *
+   * @param res ServerResponse object
+   * @param pathname Path that was not found
+   */
+  async handle404(res, pathname) {
+    const notFoundConfig = getNotFoundHandler(this.config, pathname);
+    if (notFoundConfig) {
+      log.info(`[Router] Using custom 404 handler for: ${pathname}`);
+      send404(res, notFoundConfig, pathname);
+    } else {
+      log.info(`[Router] Using default 404 handler for: ${pathname}`);
+      const html = createDefault404Html(pathname);
+      send404(res, { html }, pathname);
+    }
+  }
+  /**
+   * Handle a redirect response
+   *
+   * @param res ServerResponse object
+   * @param location Target URL
+   * @param status HTTP status code
+   */
+  handleRedirect(res, location, status) {
+    log.info(`[Router] Sending redirect: ${location} (${status})`);
+    sendRedirect(res, location, status);
+  }
+}
+/**
+ * Create an advanced router from framework config and routes
+ *
+ * @param routes Scanned route entries
+ * @param config Framework configuration
+ * @returns AdvancedRouter instance
+ */
+export function createAdvancedRouter(routes, config) {
+  return new AdvancedRouter(routes, config);
+}