@constela/start 0.3.0 → 0.4.0

package/dist/chunk-JXIOHPG5.js

@@ -0,0 +1,399 @@
+// src/router/file-router.ts
+import fg from "fast-glob";
+import { existsSync, statSync } from "fs";
+import { join } from "path";
+function filePathToPattern(filePath, _routesDir) {
+  let normalized = filePath.replace(/\\/g, "/");
+  normalized = normalized.replace(/\.(ts|tsx|js|jsx)$/, "");
+  const segments = normalized.split("/");
+  const processedSegments = segments.map((segment) => {
+    if (segment.startsWith("[...") && segment.endsWith("]")) {
+      return "*";
+    }
+    if (segment.startsWith("[") && segment.endsWith("]")) {
+      const paramName = segment.slice(1, -1);
+      return `:${paramName}`;
+    }
+    return segment;
+  });
+  if (processedSegments.at(-1) === "index") {
+    processedSegments.pop();
+  }
+  const path = "/" + processedSegments.join("/");
+  if (path === "/") {
+    return "/";
+  }
+  return path.endsWith("/") ? path.slice(0, -1) : path;
+}
+function extractParams(filePath) {
+  const params = [];
+  const normalized = filePath.replace(/\\/g, "/");
+  const regex = /\[(?:\.\.\.)?([^\]]+)\]/g;
+  let match;
+  while ((match = regex.exec(normalized)) !== null) {
+    const paramName = match[1];
+    if (paramName !== void 0) {
+      params.push(paramName);
+    }
+  }
+  return params;
+}
+function determineRouteType(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const fileName = normalized.split("/").pop() ?? "";
+  if (fileName.startsWith("_middleware.")) {
+    return "middleware";
+  }
+  if (normalized.startsWith("api/") || normalized.includes("/api/")) {
+    return "api";
+  }
+  return "page";
+}
+function shouldIncludeRoute(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const fileName = normalized.split("/").pop() ?? "";
+  if (fileName.endsWith(".d.ts")) {
+    return false;
+  }
+  if (fileName.startsWith("_") && !fileName.startsWith("_middleware.")) {
+    return false;
+  }
+  return true;
+}
+async function scanRoutes(routesDir) {
+  if (!existsSync(routesDir)) {
+    throw new Error(`Routes directory does not exist: ${routesDir}`);
+  }
+  const stats = statSync(routesDir);
+  if (!stats.isDirectory()) {
+    throw new Error(`Routes path is not a directory: ${routesDir}`);
+  }
+  const files = await fg("**/*.{ts,tsx,js,jsx}", {
+    cwd: routesDir,
+    ignore: ["node_modules/**", "**/*.d.ts"],
+    onlyFiles: true,
+    followSymbolicLinks: false
+  });
+  const routes = [];
+  for (const filePath of files) {
+    if (!shouldIncludeRoute(filePath)) {
+      continue;
+    }
+    const route = {
+      file: join(routesDir, filePath),
+      pattern: filePathToPattern(filePath, routesDir),
+      type: determineRouteType(filePath),
+      params: extractParams(filePath)
+    };
+    routes.push(route);
+  }
+  routes.sort((a, b) => {
+    return compareRoutes(a, b);
+  });
+  return routes;
+}
+function compareRoutes(a, b) {
+  if (a.type === "middleware" && b.type !== "middleware") return -1;
+  if (b.type === "middleware" && a.type !== "middleware") return 1;
+  const segmentsA = a.pattern.split("/").filter(Boolean);
+  const segmentsB = b.pattern.split("/").filter(Boolean);
+  const minLen = Math.min(segmentsA.length, segmentsB.length);
+  for (let i = 0; i < minLen; i++) {
+    const segA = segmentsA[i] ?? "";
+    const segB = segmentsB[i] ?? "";
+    const typeA = getSegmentType(segA);
+    const typeB = getSegmentType(segB);
+    if (typeA !== typeB) {
+      return typeA - typeB;
+    }
+    if (typeA === 0 && segA !== segB) {
+      return segA.localeCompare(segB);
+    }
+  }
+  if (segmentsA.length !== segmentsB.length) {
+    return segmentsA.length - segmentsB.length;
+  }
+  return a.pattern.localeCompare(b.pattern);
+}
+function getSegmentType(segment) {
+  if (segment === "*") return 2;
+  if (segment.startsWith(":")) return 1;
+  return 0;
+}
+
+// src/static/index.ts
+import { extname, join as join2, normalize, resolve } from "path";
+import { existsSync as existsSync2, statSync as statSync2 } from "fs";
+var MIME_TYPES = {
+  // Images
+  ".ico": "image/x-icon",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  // Fonts
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".eot": "application/vnd.ms-fontobject",
+  // Web assets
+  ".css": "text/css",
+  ".js": "text/javascript",
+  ".json": "application/json",
+  ".txt": "text/plain",
+  ".html": "text/html",
+  ".xml": "application/xml",
+  // Other
+  ".pdf": "application/pdf",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".map": "application/json"
+};
+var DEFAULT_MIME_TYPE = "application/octet-stream";
+function isPathSafe(pathname) {
+  if (!pathname) {
+    return false;
+  }
+  if (!pathname.startsWith("/")) {
+    return false;
+  }
+  if (pathname.includes("\\")) {
+    return false;
+  }
+  if (pathname.includes("//")) {
+    return false;
+  }
+  if (pathname.includes("\0") || pathname.includes("%00")) {
+    return false;
+  }
+  let decoded;
+  try {
+    decoded = pathname;
+    let prevDecoded = "";
+    while (decoded !== prevDecoded) {
+      prevDecoded = decoded;
+      decoded = decodeURIComponent(decoded);
+    }
+  } catch {
+    return false;
+  }
+  if (decoded.includes("\0")) {
+    return false;
+  }
+  if (decoded.includes("..")) {
+    return false;
+  }
+  const segments = decoded.split("/").filter(Boolean);
+  for (const segment of segments) {
+    if (segment.startsWith(".")) {
+      return false;
+    }
+  }
+  return true;
+}
+function getMimeType(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] ?? DEFAULT_MIME_TYPE;
+}
+function hasObviousAttackPattern(pathname) {
+  if (!pathname) {
+    return true;
+  }
+  if (!pathname.startsWith("/")) {
+    return true;
+  }
+  if (pathname.includes("\\")) {
+    return true;
+  }
+  if (pathname.includes("//")) {
+    return true;
+  }
+  if (pathname.includes("\0") || pathname.includes("%00")) {
+    return true;
+  }
+  let decoded;
+  try {
+    decoded = pathname;
+    let prevDecoded = "";
+    while (decoded !== prevDecoded) {
+      prevDecoded = decoded;
+      decoded = decodeURIComponent(decoded);
+    }
+  } catch {
+    return true;
+  }
+  if (decoded.includes("\0")) {
+    return true;
+  }
+  const segments = decoded.split("/").filter(Boolean);
+  for (const segment of segments) {
+    if (segment.startsWith(".") && segment !== "..") {
+      return true;
+    }
+  }
+  if (decoded.startsWith("/..")) {
+    return true;
+  }
+  return false;
+}
+function resolveStaticFile(pathname, publicDir) {
+  if (hasObviousAttackPattern(pathname)) {
+    return {
+      exists: false,
+      filePath: null,
+      mimeType: null,
+      error: "path_traversal"
+    };
+  }
+  let decodedPathname;
+  try {
+    decodedPathname = decodeURIComponent(pathname);
+  } catch {
+    return {
+      exists: false,
+      filePath: null,
+      mimeType: null,
+      error: "path_traversal"
+    };
+  }
+  const relativePath = decodedPathname.slice(1);
+  const resolvedPath = normalize(join2(publicDir, relativePath));
+  const absolutePublicDir = resolve(publicDir);
+  const publicDirWithSep = absolutePublicDir.endsWith("/") ? absolutePublicDir : absolutePublicDir + "/";
+  if (!resolvedPath.startsWith(publicDirWithSep) && resolvedPath !== absolutePublicDir) {
+    return {
+      exists: false,
+      filePath: null,
+      mimeType: null,
+      error: "outside_public"
+    };
+  }
+  const mimeType = getMimeType(resolvedPath);
+  let exists = false;
+  if (existsSync2(resolvedPath)) {
+    try {
+      const stats = statSync2(resolvedPath);
+      exists = stats.isFile();
+    } catch {
+      exists = false;
+    }
+  }
+  return {
+    exists,
+    filePath: resolvedPath,
+    mimeType
+  };
+}
+
+// src/dev/server.ts
+import { createServer } from "http";
+import { createReadStream } from "fs";
+import { join as join3 } from "path";
+var DEFAULT_PORT = 3e3;
+var DEFAULT_HOST = "localhost";
+var DEFAULT_PUBLIC_DIR = "public";
+async function createDevServer(options = {}) {
+  const {
+    port = DEFAULT_PORT,
+    host = DEFAULT_HOST,
+    routesDir: _routesDir = "src/routes",
+    publicDir = join3(process.cwd(), DEFAULT_PUBLIC_DIR)
+  } = options;
+  let httpServer = null;
+  let actualPort = port;
+  const devServer = {
+    get port() {
+      return actualPort;
+    },
+    async listen() {
+      return new Promise((resolve2, reject) => {
+        httpServer = createServer((req, res) => {
+          const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+          const pathname = url.pathname;
+          const staticResult = resolveStaticFile(pathname, publicDir);
+          if (staticResult.error === "path_traversal" || staticResult.error === "outside_public") {
+            res.writeHead(403, { "Content-Type": "text/plain" });
+            res.end("Forbidden");
+            return;
+          }
+          if (staticResult.exists && staticResult.filePath && staticResult.mimeType) {
+            res.writeHead(200, { "Content-Type": staticResult.mimeType });
+            const stream = createReadStream(staticResult.filePath);
+            stream.pipe(res);
+            stream.on("error", () => {
+              if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "text/plain" });
+              }
+              res.end("Internal Server Error");
+            });
+            return;
+          }
+          if (staticResult.filePath && !staticResult.exists) {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("Not Found");
+            return;
+          }
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end("<html><body>Constela Dev Server</body></html>");
+        });
+        httpServer.on("error", (err) => {
+          reject(err);
+        });
+        httpServer.listen(port, host, () => {
+          const address = httpServer?.address();
+          if (address) {
+            actualPort = address.port;
+          }
+          resolve2();
+        });
+      });
+    },
+    async close() {
+      return new Promise((resolve2, reject) => {
+        if (!httpServer) {
+          resolve2();
+          return;
+        }
+        httpServer.close((err) => {
+          if (err) {
+            reject(err);
+          } else {
+            httpServer = null;
+            resolve2();
+          }
+        });
+      });
+    }
+  };
+  return devServer;
+}
+
+// src/build/index.ts
+async function build(options) {
+  const outDir = options?.outDir ?? "dist";
+  const routesDir = options?.routesDir ?? "src/routes";
+  let routes = [];
+  try {
+    const scannedRoutes = await scanRoutes(routesDir);
+    routes = scannedRoutes.map((r) => r.pattern);
+  } catch {
+  }
+  return {
+    outDir,
+    routes
+  };
+}
+
+export {
+  filePathToPattern,
+  scanRoutes,
+  isPathSafe,
+  getMimeType,
+  resolveStaticFile,
+  createDevServer,
+  build
+};

package/dist/cli/index.js

@@ -1,15 +1,39 @@
+import {
+  build,
+  createDevServer
+} from "../chunk-JXIOHPG5.js";
+
 // src/cli/index.ts
 import { Command } from "commander";
 var devHandler = async (options) => {
-  console.log("Development server not yet implemented");
-  return { port: Number(options.port) };
+  const port = parseInt(options.port, 10);
+  const host = options.host ?? "localhost";
+  const server = await createDevServer({ port, host });
+  await server.listen();
+  console.log(`Development server running at http://${host}:${server.port}`);
+  process.on("SIGINT", async () => {
+    console.log("\nShutting down server...");
+    await server.close();
+    process.exit(0);
+  });
+  return { port: server.port };
 };
-var buildHandler = async () => {
-  console.log("Build not yet implemented");
+var buildHandler = async (options) => {
+  console.log("Building for production...");
+  await build(options.outDir ? { outDir: options.outDir } : {});
+  console.log("Build complete");
 };
 var startHandler = async (options) => {
-  console.log("Production server not yet implemented");
-  return { port: Number(options.port) };
+  const port = parseInt(options.port, 10);
+  const server = await createDevServer({ port, host: "0.0.0.0" });
+  await server.listen();
+  console.log(`Production server running at http://0.0.0.0:${server.port}`);
+  process.on("SIGINT", async () => {
+    console.log("\nShutting down server...");
+    await server.close();
+    process.exit(0);
+  });
+  return { port: server.port };
 };
 function setDevHandler(handler) {
   devHandler = handler;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { CompiledProgram } from '@constela/compiler';
+import { LayoutProgram, Program, StaticPathsDefinition, DataSource } from '@constela/core';
 
 /**
  * Scanned route from file system
@@ -38,11 +39,22 @@ interface MiddlewareContext {
 }
 type MiddlewareNext = () => Promise<Response>;
 type Middleware = (ctx: MiddlewareContext, next: MiddlewareNext) => Promise<Response> | Response;
+/**
+ * Function-form page export that receives route params.
+ *
+ * @example
+ * // pages/users/[id].ts
+ * export default async function(params: Record<string, string>) {
+ *   const user = await fetchUser(params.id);
+ *   return createUserPage(user);
+ * }
+ */
+type PageExportFunction = (params: Record<string, string>) => Promise<CompiledProgram> | CompiledProgram;
 /**
  * Page module with Constela program
  */
 interface PageModule {
-    default: CompiledProgram;
+    default: CompiledProgram | PageExportFunction;
     getStaticPaths?: () => Promise<StaticPathsResult> | StaticPathsResult;
 }
 interface StaticPathsResult {
@@ -185,14 +197,30 @@ interface BuildResult {
  */
 declare function build(options?: BuildOptions): Promise<BuildResult>;
 
+/**
+ * Provider function for static paths when getStaticPaths is not available in the module.
+ * Used for dependency injection in tests.
+ */
+type StaticPathsProvider = (pattern: string) => StaticPathsResult | null | Promise<StaticPathsResult | null>;
+/**
+ * Options for generateStaticPages function
+ */
+interface GenerateStaticPagesOptions {
+    /**
+     * Optional provider for static paths when module doesn't export getStaticPaths.
+     * Primarily used for testing purposes.
+     */
+    staticPathsProvider?: StaticPathsProvider;
+}
 /**
  * Generate static pages for SSG routes
  *
  * @param routes - Array of scanned routes
  * @param outDir - Output directory for generated HTML files
+ * @param options - Optional configuration including staticPathsProvider for DI
  * @returns Array of generated file paths
  */
-declare function generateStaticPages(routes: ScannedRoute[], outDir: string): Promise<string[]>;
+declare function generateStaticPages(routes: ScannedRoute[], outDir: string, options?: GenerateStaticPagesOptions): Promise<string[]>;
 
 /**
  * Create handler function from API module
@@ -227,4 +255,187 @@ interface EdgeAdapter {
  */
 declare function createAdapter(options: AdapterOptions): EdgeAdapter;
 
-export { type APIContext, type APIModule, type BuildOptions, type ConstelaConfig, type DevServerOptions, type Middleware, type MiddlewareContext, type MiddlewareNext, type PageModule, type ScannedRoute, type StaticFileResult, type StaticPathsResult, build, createAPIHandler, createAdapter, createDevServer, createMiddlewareChain, filePathToPattern, generateStaticPages, getMimeType, isPathSafe, resolveStaticFile, scanRoutes };
+/**
+ * Type guard to check if a page export is a function (dynamic) or a static program
+ *
+ * @param exported - The default export from a page module
+ * @returns true if the export is a function, false if it's a static CompiledProgram
+ */
+declare function isPageExportFunction(exported: CompiledProgram | PageExportFunction): exported is PageExportFunction;
+/**
+ * Resolve a page export to a CompiledProgram
+ *
+ * If the export is a function, it will be called with the route params.
+ * If the export is a static CompiledProgram, it will be returned as-is.
+ *
+ * @param pageDefault - The default export from a page module (function or static program)
+ * @param params - Route parameters extracted from the URL
+ * @param expectedParams - Optional array of expected parameter names for validation
+ * @returns Promise resolving to a CompiledProgram
+ * @throws Error if expectedParams is provided and a required param is missing
+ */
+declare function resolvePageExport(pageDefault: CompiledProgram | PageExportFunction, params: Record<string, string>, expectedParams?: string[]): Promise<CompiledProgram>;
+
+/**
+ * Layout Resolver - Scans and resolves layout files for Constela Start
+ *
+ * This module provides functionality to:
+ * - Scan layout directories for layout files
+ * - Resolve layout by name
+ * - Load and validate layout programs
+ * - Compose layouts with page content
+ */
+
+interface ScannedLayout {
+    name: string;
+    file: string;
+}
+interface LayoutInfo {
+    name: string;
+    file: string;
+    program?: LayoutProgram;
+}
+/**
+ * Scans a directory for layout files
+ *
+ * @param layoutsDir - Directory to scan for layouts
+ * @returns Array of scanned layouts with name and file path
+ * @throws Error if directory doesn't exist or is not a directory
+ */
+declare function scanLayouts(layoutsDir: string): Promise<ScannedLayout[]>;
+/**
+ * Resolves a layout by name from scanned layouts
+ *
+ * @param layoutName - Name of the layout to resolve
+ * @param layouts - Array of scanned layouts
+ * @returns The matching layout or undefined
+ */
+declare function resolveLayout(layoutName: string, layouts: ScannedLayout[]): ScannedLayout | undefined;
+/**
+ * Loads and validates a layout file
+ *
+ * @param layoutFile - Path to the layout file
+ * @returns The loaded LayoutProgram
+ * @throws Error if file cannot be loaded or is not a valid layout
+ */
+declare function loadLayout(layoutFile: string): Promise<LayoutProgram>;
+/**
+ * LayoutResolver - Manages layout scanning, resolution, and composition
+ */
+declare class LayoutResolver {
+    private layoutsDir;
+    private layouts;
+    private loadedLayouts;
+    private initialized;
+    constructor(layoutsDir: string);
+    /**
+     * Initialize the resolver by scanning the layouts directory
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if a layout exists
+     */
+    hasLayout(name: string): boolean;
+    /**
+     * Get a layout by name
+     *
+     * @param name - Layout name
+     * @returns The layout program or undefined if not found
+     */
+    getLayout(name: string): Promise<LayoutProgram | undefined>;
+    /**
+     * Compose a page with its layout
+     *
+     * @param page - Page program to compose
+     * @returns Composed program (or original if no layout)
+     * @throws Error if specified layout is not found
+     */
+    composeWithLayout(page: Program): Promise<Program>;
+    /**
+     * Get all scanned layouts
+     */
+    getAll(): ScannedLayout[];
+}
+
+/**
+ * Data Loader for Build-time Content Loading
+ *
+ * This module provides utilities for loading data sources at build time:
+ * - Glob patterns for multiple files
+ * - Single file loading
+ * - API fetching
+ * - MDX/YAML/CSV transformations
+ * - Static path generation for SSG
+ */
+
+interface GlobResult {
+    file: string;
+    raw: string;
+    frontmatter?: Record<string, unknown>;
+    content?: string;
+}
+interface StaticPath {
+    params: Record<string, string>;
+    data?: unknown;
+}
+/**
+ * Transform MDX content - parse frontmatter and content
+ */
+declare function transformMdx(content: string): {
+    frontmatter: Record<string, unknown>;
+    content: string;
+};
+/**
+ * Transform YAML content
+ */
+declare function transformYaml(content: string): Record<string, unknown>;
+/**
+ * Transform CSV content to array of objects
+ */
+declare function transformCsv(content: string): Record<string, string>[];
+/**
+ * Load files matching a glob pattern
+ */
+declare function loadGlob(baseDir: string, pattern: string, transform?: string): Promise<GlobResult[]>;
+/**
+ * Load a single file
+ */
+declare function loadFile(baseDir: string, filePath: string, transform?: string): Promise<unknown>;
+/**
+ * Load data from API endpoint
+ */
+declare function loadApi(url: string, transform?: string): Promise<unknown>;
+/**
+ * Generate static paths from data using params expression
+ */
+declare function generateStaticPaths(data: unknown[], staticPathsDef: StaticPathsDefinition): Promise<StaticPath[]>;
+/**
+ * DataLoader class for managing data source loading with caching
+ */
+declare class DataLoader {
+    private cache;
+    private projectRoot;
+    constructor(projectRoot: string);
+    /**
+     * Load a single data source
+     */
+    loadDataSource(name: string, dataSource: DataSource): Promise<unknown>;
+    /**
+     * Load all data sources
+     */
+    loadAllDataSources(dataSources: Record<string, DataSource>): Promise<Record<string, unknown>>;
+    /**
+     * Clear cache for a specific data source or all caches
+     */
+    clearCache(name?: string): void;
+    /**
+     * Clear all cache entries
+     */
+    clearAllCache(): void;
+    /**
+     * Get the current cache size
+     */
+    getCacheSize(): number;
+}
+
+export { type APIContext, type APIModule, type BuildOptions, type ConstelaConfig, DataLoader, type DevServerOptions, type GenerateStaticPagesOptions, type GlobResult, type LayoutInfo, LayoutResolver, type Middleware, type MiddlewareContext, type MiddlewareNext, type PageExportFunction, type PageModule, type ScannedLayout, type ScannedRoute, type StaticFileResult, type StaticPath, type StaticPathsProvider, type StaticPathsResult, build, createAPIHandler, createAdapter, createDevServer, createMiddlewareChain, filePathToPattern, generateStaticPages, generateStaticPaths, getMimeType, isPageExportFunction, isPathSafe, loadApi, loadFile, loadGlob, loadLayout, resolveLayout, resolvePageExport, resolveStaticFile, scanLayouts, scanRoutes, transformCsv, transformMdx, transformYaml };