@constela/start 0.1.2 → 0.3.0

package/dist/cli/index.d.ts

@@ -0,0 +1,38 @@
+import { Command } from 'commander';
+
+type DevHandler = (options: {
+    port: string;
+    host?: string;
+}) => Promise<{
+    port: number;
+}>;
+type BuildHandler = (options: {
+    outDir?: string;
+}) => Promise<void>;
+type StartHandler = (options: {
+    port: string;
+}) => Promise<{
+    port: number;
+}>;
+/**
+ * Set custom dev handler (for testing)
+ */
+declare function setDevHandler(handler: DevHandler): void;
+/**
+ * Set custom build handler (for testing)
+ */
+declare function setBuildHandler(handler: BuildHandler): void;
+/**
+ * Set custom start handler (for testing)
+ */
+declare function setStartHandler(handler: StartHandler): void;
+/**
+ * Creates and configures the CLI program
+ */
+declare function createCLI(): Command;
+/**
+ * Main CLI entry point
+ */
+declare function main(): void;
+
+export { createCLI, main, setBuildHandler, setDevHandler, setStartHandler };

package/dist/cli/index.js

@@ -0,0 +1,47 @@
+// src/cli/index.ts
+import { Command } from "commander";
+var devHandler = async (options) => {
+  console.log("Development server not yet implemented");
+  return { port: Number(options.port) };
+};
+var buildHandler = async () => {
+  console.log("Build not yet implemented");
+};
+var startHandler = async (options) => {
+  console.log("Production server not yet implemented");
+  return { port: Number(options.port) };
+};
+function setDevHandler(handler) {
+  devHandler = handler;
+}
+function setBuildHandler(handler) {
+  buildHandler = handler;
+}
+function setStartHandler(handler) {
+  startHandler = handler;
+}
+function createCLI() {
+  const program = new Command();
+  program.name("constela-start").version("0.1.0").description("Meta-framework for Constela applications");
+  program.command("dev").description("Start development server").option("-p, --port <port>", "Port number", "3000").option("-h, --host <host>", "Host address").action(async (options) => {
+    await devHandler(options);
+  });
+  program.command("build").description("Build for production").option("-o, --outDir <outDir>", "Output directory").action(async (options) => {
+    await buildHandler(options);
+  });
+  program.command("start").description("Start production server").option("-p, --port <port>", "Port number", "3000").action(async (options) => {
+    await startHandler(options);
+  });
+  return program;
+}
+function main() {
+  const program = createCLI();
+  program.parse();
+}
+export {
+  createCLI,
+  main,
+  setBuildHandler,
+  setDevHandler,
+  setStartHandler
+};

package/dist/index.d.ts

@@ -68,6 +68,7 @@ interface DevServerOptions {
     port?: number;
     host?: string;
     routesDir?: string;
+    publicDir?: string;
 }
 /**
  * Build options
@@ -123,6 +124,55 @@ interface DevServer {
  */
 declare function createDevServer(options?: DevServerOptions): Promise<DevServer>;
 
+/**
+ * Static file serving utilities.
+ *
+ * Provides path validation, MIME type detection, and file resolution
+ * for serving static files from the public directory.
+ */
+/**
+ * Result of resolving a static file path
+ */
+interface StaticFileResult {
+    exists: boolean;
+    filePath: string | null;
+    mimeType: string | null;
+    error?: 'path_traversal' | 'outside_public';
+}
+/**
+ * Check if a URL pathname is safe from path traversal attacks.
+ *
+ * Rejects:
+ * - Paths containing '..' (decoded)
+ * - Double slashes '//'
+ * - Null bytes
+ * - Backslashes
+ * - Hidden files (starting with '.')
+ * - Paths not starting with '/'
+ * - Empty paths
+ *
+ * @param pathname - The URL pathname to validate
+ * @returns true if the path is safe, false otherwise
+ */
+declare function isPathSafe(pathname: string): boolean;
+/**
+ * Get the MIME type for a file based on its extension.
+ *
+ * @param filePath - The file path to check
+ * @returns The MIME type string, or 'application/octet-stream' for unknown types
+ */
+declare function getMimeType(filePath: string): string;
+/**
+ * Resolve a URL pathname to an absolute file path within the public directory.
+ *
+ * Performs security validation and checks if the file exists.
+ *
+ * @param pathname - The URL pathname (e.g., '/favicon.ico')
+ * @param publicDir - The absolute path to the public directory
+ * @returns StaticFileResult with resolution details
+ */
+declare function resolveStaticFile(pathname: string, publicDir: string): StaticFileResult;
+
 interface BuildResult {
     outDir: string;
     routes: string[];
@@ -177,4 +227,4 @@ 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 StaticPathsResult, build, createAPIHandler, createAdapter, createDevServer, createMiddlewareChain, filePathToPattern, generateStaticPages, scanRoutes };
+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 };

package/dist/index.js

@@ -129,13 +129,187 @@ function getSegmentType(segment) {
 
 // src/dev/server.ts
 import { createServer } from "http";
+import { createReadStream } from "fs";
+import { join as join3 } from "path";
+
+// 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
 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"
+    routesDir: _routesDir = "src/routes",
+    publicDir = join3(process.cwd(), DEFAULT_PUBLIC_DIR)
   } = options;
   let httpServer = null;
   let actualPort = port;
@@ -144,8 +318,33 @@ async function createDevServer(options = {}) {
       return actualPort;
     },
     async listen() {
-      return new Promise((resolve, reject) => {
-        httpServer = createServer((_req, res) => {
+      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>");
         });
@@ -157,14 +356,14 @@ async function createDevServer(options = {}) {
           if (address) {
             actualPort = address.port;
           }
-          resolve();
+          resolve2();
         });
       });
     },
     async close() {
-      return new Promise((resolve, reject) => {
+      return new Promise((resolve2, reject) => {
         if (!httpServer) {
-          resolve();
+          resolve2();
           return;
         }
         httpServer.close((err) => {
@@ -172,7 +371,7 @@ async function createDevServer(options = {}) {
             reject(err);
           } else {
             httpServer = null;
-            resolve();
+            resolve2();
           }
         });
       });
@@ -199,7 +398,7 @@ async function build(options) {
 
 // src/build/ssg.ts
 import { mkdir, writeFile } from "fs/promises";
-import { join as join2, dirname } from "path";
+import { join as join4, dirname } from "path";
 var defaultProgram = {
   version: "1.0",
   state: {},
@@ -225,10 +424,10 @@ var testStaticPaths = {
 var consumedPatterns = /* @__PURE__ */ new Set();
 function getOutputPath(pattern, outDir) {
   if (pattern === "/") {
-    return join2(outDir, "index.html");
+    return join4(outDir, "index.html");
   }
   const segments = pattern.slice(1).split("/");
-  return join2(outDir, ...segments, "index.html");
+  return join4(outDir, ...segments, "index.html");
 }
 function resolvePattern(pattern, params) {
   let resolved = pattern;
@@ -468,5 +667,8 @@ export {
   createMiddlewareChain,
   filePathToPattern,
   generateStaticPages,
+  getMimeType,
+  isPathSafe,
+  resolveStaticFile,
   scanRoutes
 };

package/dist/runtime/entry-client.d.ts

@@ -1,8 +1,41 @@
+import { CompiledProgram } from '@constela/compiler';
+import { AppInstance } from '@constela/runtime';
+
 /**
  * Client-side entry point for Constela applications
- * Handles hydration and client-side routing
+ * Handles hydration and Escape Hatch mechanism for external library integration.
+ */
+
+/**
+ * Context provided to EscapeHandler mount functions
+ */
+interface EscapeContext {
+    appInstance: AppInstance;
+    getState: (name: string) => unknown;
+    setState: (name: string, value: unknown) => void;
+    subscribe: (name: string, fn: (value: unknown) => void) => () => void;
+}
+/**
+ * Handler for escape hatch elements
+ */
+interface EscapeHandler {
+    name: string;
+    mount: (element: HTMLElement, ctx: EscapeContext) => () => void;
+}
+/**
+ * Options for initializing the client application
+ */
+interface InitClientOptions {
+    program: CompiledProgram;
+    container: HTMLElement;
+    escapeHandlers?: EscapeHandler[];
+}
+/**
+ * Initialize the client application with hydration and escape hatch support.
+ *
+ * @param options - Configuration options
+ * @returns AppInstance for controlling the application
  */
-declare function hydrate(): void;
-declare function mount(_element: HTMLElement): void;
+declare function initClient(options: InitClientOptions): AppInstance;
 
-export { hydrate, mount };
+export { type EscapeContext, type EscapeHandler, type InitClientOptions, initClient };

package/dist/runtime/entry-client.js

@@ -1,11 +1,58 @@
 // src/runtime/entry-client.ts
-function hydrate() {
-  throw new Error("hydrate is not yet implemented");
-}
-function mount(_element) {
-  throw new Error("mount is not yet implemented");
+import { hydrateApp } from "@constela/runtime";
+function initClient(options) {
+  const { program, container, escapeHandlers = [] } = options;
+  const appInstance = hydrateApp({ program, container });
+  const escapeElements = container.querySelectorAll(
+    "[data-constela-escape]"
+  );
+  const handlerMap = /* @__PURE__ */ new Map();
+  for (const handler of escapeHandlers) {
+    handlerMap.set(handler.name, handler);
+  }
+  const cleanupFns = [];
+  for (const element of escapeElements) {
+    const escapeName = element.getAttribute("data-constela-escape") ?? "";
+    const handler = handlerMap.get(escapeName);
+    if (!handler) {
+      continue;
+    }
+    const escapeContext = {
+      appInstance,
+      getState: (name) => appInstance.getState(name),
+      setState: (name, value) => appInstance.setState(name, value),
+      subscribe: (name, fn) => {
+        if (typeof appInstance.subscribe === "function") {
+          return appInstance.subscribe(name, fn);
+        }
+        return () => {
+        };
+      }
+    };
+    try {
+      const cleanup = handler.mount(element, escapeContext);
+      cleanupFns.push(cleanup);
+    } catch {
+    }
+  }
+  let destroyed = false;
+  return {
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      for (const cleanup of cleanupFns) {
+        cleanup();
+      }
+      appInstance.destroy();
+    },
+    setState(name, value) {
+      appInstance.setState(name, value);
+    },
+    getState(name) {
+      return appInstance.getState(name);
+    }
+  };
 }
 export {
-  hydrate,
-  mount
+  initClient
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/start",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Meta-framework for Constela applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,10 +34,15 @@
     "vite": "^6.0.0",
     "commander": "^12.0.0",
     "fast-glob": "^3.3.0",
+    "unified": "^11.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-mdx": "^3.0.0",
+    "remark-gfm": "^4.0.0",
+    "gray-matter": "^4.0.0",
     "@constela/compiler": "0.4.0",
+    "@constela/runtime": "0.7.0",
     "@constela/server": "0.1.2",
-    "@constela/router": "3.0.0",
-    "@constela/runtime": "0.6.0"
+    "@constela/router": "4.0.0"
   },
   "devDependencies": {
     "typescript": "^5.3.0",
@@ -46,7 +51,7 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "tsup src/index.ts src/runtime/entry-client.ts src/runtime/entry-server.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/runtime/entry-client.ts src/runtime/entry-server.ts src/cli/index.ts --format esm --dts --clean",
     "type-check": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",