@velox0/cerver 0.4.3 → 0.5.2-nightly.20260524.1

package/README.md

@@ -16,7 +16,7 @@ Cerver takes a Next.js-style file-based routing structure (written in a strict s
 - **Microscopic Footprint**: Generated executables are tiny and start in milliseconds.
 - **Single-Binary Deployment**: Static assets (HTML, CSS, JS, images) are automatically minified and embedded directly into the executable as C byte arrays.
 - **Native Performance**: Uses `kqueue` (macOS) or `epoll` (Linux) event loops for high-performance non-blocking I/O.
-- **File-Based Routing**: Intuitive `app/routes/` directory structure, supporting dynamic segments (e.g., `/item/[id].js`).
+- **File-Based Routing**: Intuitive `routes/` directory structure, supporting dynamic segments (e.g., `/item/[id].js`).
 
 ## Benchmarks (Autocannon)
 
@@ -57,9 +57,9 @@ cerver run
 
 ## Routing
 
-Routes are defined in the `app/routes/` directory.
+Routes are defined in the `routes/` directory.
 
-`app/routes/index.js` (maps to `/`)
+`routes/index.js` (maps to `/`)
 
 ```javascript
 export function GET(req, res) {
@@ -67,7 +67,7 @@ export function GET(req, res) {
 }
 ```
 
-`app/routes/api/status.js` (maps to `/api/status`)
+`routes/api/status.js` (maps to `/api/status`)
 
 ```javascript
 export function GET(req, res) {
@@ -75,7 +75,7 @@ export function GET(req, res) {
 }
 ```
 
-`app/routes/users/[id].js` (maps to `/users/:id`)
+`routes/users/[id].js` (maps to `/users/:id`)
 
 ```javascript
 export function GET(req, res) {
@@ -84,6 +84,16 @@ export function GET(req, res) {
 }
 ```
 
+### Clean URL Asset Mapping
+
+Cerver has a special asset routing convention that prevents folder clutter:
+- **Root Index**: `public/index.html` is automatically served at the root `/`.
+- **Directory Indexing**: Nested `index.html` files inside directories (e.g. `public/page/index.html`) are **not** implicitly aliased to `/page` (they remain at `/page/index.html`).
+- **Clean Folder Slugs**: If an HTML file has the exact same name as its parent directory, it is mapped to the clean directory URL. For example:
+  - `public/about/about.html` maps to `/about` (and `/about/`)
+  - `public/blog/posts/posts.html` maps to `/blog/posts` (and `/blog/posts/`)
+- **Other Static Assets**: All other assets like CSS, JS, images, and non-directory-matching HTML files serve directly at their file paths (e.g., `public/about/style.css` maps to `/about/style.css`).
+
 ## The Request & Response Objects
 
 Because Cerver compiles to C, the API surface is restricted.

package/lib/assets/embed.js

@@ -82,6 +82,8 @@ async function generateEmbeddedAssets(assets, shouldMinify, compression) {
   const algo = compression || "none";
 
   lines.push("/* Auto-generated embedded assets — do not edit */");
+  lines.push('#include "cerver.h"');
+  lines.push("#include <stddef.h>");
   lines.push("");
 
   const assetEntries = [];
@@ -155,14 +157,37 @@ async function generateEmbeddedAssets(assets, shouldMinify, compression) {
       brLen,
     });
 
-    /* Auto-alias: /any/path/index.html → /any/path */
-    if (asset.servePath.endsWith("/index.html")) {
-      const dirPath = asset.servePath === "/index.html"
-        ? "/"
-        : asset.servePath.slice(0, -"/index.html".length);
+    /* Auto-alias rule:
+       1. /index.html → /
+       2. /path/to/name/name.html → /path/to/name
+    */
+    let shouldAlias = false;
+    let aliasPath = null;
+
+    if (asset.servePath === "/index.html") {
+      shouldAlias = true;
+      aliasPath = "/";
+    } else if (asset.servePath.endsWith(".html")) {
+      const parts = asset.servePath.split("/");
+      if (parts.length >= 3) {
+        const fileNameWithExt = parts[parts.length - 1];
+        const parentDir = parts[parts.length - 2];
+        const baseName = fileNameWithExt.slice(0, -5); // Remove ".html"
+        if (baseName === parentDir) {
+          shouldAlias = true;
+          const lengthToRemove = fileNameWithExt.length + 1; // filename plus the slash before it
+          aliasPath = asset.servePath.slice(0, -lengthToRemove);
+          if (aliasPath === "") {
+            aliasPath = "/";
+          }
+        }
+      }
+    }
+
+    if (shouldAlias && aliasPath !== null) {
       assetEntries.push({
         name,
-        servePath: dirPath,
+        servePath: aliasPath,
         mime,
         gzName,
         gzLen,
@@ -173,7 +198,7 @@ async function generateEmbeddedAssets(assets, shouldMinify, compression) {
   }
 
   /* Generate the asset table */
-  lines.push("static cerver_asset_t cerver_embedded_assets[] = {");
+  lines.push("cerver_asset_t cerver_embedded_assets[] = {");
   for (const entry of assetEntries) {
     lines.push(
       `    { "${entry.servePath}", "${entry.mime}", ` +
@@ -185,7 +210,7 @@ async function generateEmbeddedAssets(assets, shouldMinify, compression) {
   }
   lines.push("};");
   lines.push(
-    `static const int cerver_embedded_asset_count = ${assetEntries.length};`
+    `const int cerver_embedded_asset_count = ${assetEntries.length};`
   );
 
   return lines.join("\n");

package/lib/codegen/dispatch_gen.js

@@ -40,7 +40,7 @@ function generateDispatch(routes) {
 
   /* Generate the dispatch function */
   lines.push(
-    "static cerver_handler_fn cerver_generated_dispatch(cerver_request_t *req) {"
+    "cerver_handler_fn cerver_generated_dispatch(cerver_request_t *req) {"
   );
   lines.push("    const char *path = req->path;");
   lines.push("    size_t path_len = 0;");

package/lib/codegen/generator.js

@@ -5,33 +5,36 @@ const { generateRouteTable } = require("./route_table");
 const { generateDispatch } = require("./dispatch_gen");
 
 /**
- * Generate the complete C server source file from IR routes.
+ * Generate server.c content.
  *
- * @param {IRRoute[]} routes - All IR routes
- * @param {object} config - Build config (port, embed, etc.)
- * @param {string|null} assetsCode - Generated embedded assets C code, or null
- * @returns {string} - Complete C source file
+ * @param {object} config - Build config (port, threads, etc.)
+ * @param {boolean} hasAssets - Whether embedding assets is enabled
+ * @returns {string} - C source for server.c
  */
-function generateServer(routes, config, assetsCode) {
+function generateServerC(config, hasAssets) {
   const lines = [];
 
-  /* ---- Header ---- */
   lines.push("/*");
   lines.push(" * Auto-generated by cerver — do not edit.");
   lines.push(" */");
   lines.push("");
   lines.push('#include "cerver.h"');
-  lines.push("");
   lines.push("#include <stdio.h>");
   lines.push("#include <stdlib.h>");
-  lines.push("#include <string.h>");
   lines.push("");
 
-  /* ---- Embedded assets (if any) ---- */
-  if (assetsCode) {
-    lines.push("/* ---- Embedded Assets ---- */");
-    lines.push("");
-    lines.push(assetsCode);
+  /* Routing externs */
+  lines.push("/* Routing and Handler declarations */");
+  lines.push("extern cerver_route_t cerver_routes[];");
+  lines.push("extern const int cerver_route_count;");
+  lines.push("extern cerver_handler_fn cerver_generated_dispatch(cerver_request_t *req);");
+  lines.push("");
+
+  /* Asset declarations */
+  if (hasAssets) {
+    lines.push("/* Embedded Assets */");
+    lines.push("extern cerver_asset_t cerver_embedded_assets[];");
+    lines.push("extern const int cerver_embedded_asset_count;");
     lines.push("");
   } else {
     lines.push("/* No embedded assets */");
@@ -40,6 +43,63 @@ function generateServer(routes, config, assetsCode) {
     lines.push("");
   }
 
+  /* Main function */
+  lines.push("/* ---- Entry Point ---- */");
+  lines.push("");
+  lines.push("int main(int argc, char *argv[]) {");
+  lines.push("    (void)argc;");
+  lines.push("    (void)argv;");
+  lines.push("");
+  lines.push(`    int port = ${config.port};`);
+  lines.push("");
+  lines.push("    /* Allow PORT env override */");
+  lines.push('    const char *env_port = getenv("CERVER_PORT");');
+  lines.push('    if (!env_port) env_port = getenv("PORT");');
+  lines.push("    if (env_port) port = atoi(env_port);");
+  lines.push("");
+  lines.push("    cerver_server_t srv;");
+  lines.push(`    cerver_init(&srv, port, ${config.threads});`);
+  lines.push("");
+  lines.push(
+    "    cerver_add_routes(&srv, cerver_routes, cerver_route_count);"
+  );
+  lines.push("");
+  lines.push("    /* Use generated compile-time dispatch for fast routing */");
+  lines.push("    cerver_set_dispatch(&srv, cerver_generated_dispatch);");
+  lines.push("");
+  if (hasAssets) {
+    lines.push(
+      "    cerver_set_assets(&srv, cerver_embedded_assets, cerver_embedded_asset_count);"
+    );
+  } else {
+    lines.push('    cerver_set_public_dir(&srv, "./public");');
+  }
+  lines.push("");
+  lines.push("    return cerver_listen(&srv);");
+  lines.push("}");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate routes.c content.
+ *
+ * @param {IRRoute[]} routes - All IR routes
+ * @returns {string} - C source for routes.c
+ */
+function generateRoutesC(routes) {
+  const lines = [];
+
+  lines.push("/*");
+  lines.push(" * Auto-generated route handler logic — do not edit.");
+  lines.push(" */");
+  lines.push("");
+  lines.push('#include "cerver.h"');
+  lines.push("#include <string.h>");
+  lines.push("#include <stdlib.h>");
+  lines.push("");
+
   /* ---- Route table (forward decls + table) ---- */
   lines.push("/* ---- Routes ---- */");
   lines.push("");
@@ -76,47 +136,22 @@ function generateServer(routes, config, assetsCode) {
   lines.push("");
   lines.push(generateDispatch(routes));
 
-  /* ---- Main function ---- */
-  lines.push("/* ---- Entry Point ---- */");
-  lines.push("");
-  lines.push("int main(int argc, char *argv[]) {");
-  lines.push("    (void)argc;");
-  lines.push("    (void)argv;");
-  lines.push("");
-  lines.push(`    int port = ${config.port};`);
-  lines.push("");
-  lines.push("    /* Allow PORT env override */");
-  lines.push('    const char *env_port = getenv("CERVER_PORT");');
-  lines.push('    if (!env_port) env_port = getenv("PORT");');
-  lines.push("    if (env_port) port = atoi(env_port);");
-  lines.push("");
-  lines.push("    cerver_server_t srv;");
-  lines.push(`    cerver_init(&srv, port, ${config.threads});`);
-  lines.push("");
-  lines.push(
-    "    cerver_add_routes(&srv, cerver_routes, cerver_route_count);"
-  );
-  lines.push("");
-
-  /* Wire up generated dispatch */
-  lines.push("    /* Use generated compile-time dispatch for fast routing */");
-  lines.push("    cerver_set_dispatch(&srv, cerver_generated_dispatch);");
-  lines.push("");
-
-  if (assetsCode) {
-    lines.push(
-      "    cerver_set_assets(&srv, cerver_embedded_assets, cerver_embedded_asset_count);"
-    );
-  } else {
-    lines.push('    cerver_set_public_dir(&srv, "./public");');
-  }
-
-  lines.push("");
-  lines.push("    return cerver_listen(&srv);");
-  lines.push("}");
-  lines.push("");
-
   return lines.join("\n");
 }
 
-module.exports = { generateServer };
+/**
+ * Generate the complete C server source structures from IR routes.
+ *
+ * @param {IRRoute[]} routes - All IR routes
+ * @param {object} config - Build config (port, embed, etc.)
+ * @param {boolean} hasAssets - Whether embedding assets is enabled
+ * @returns {{ serverC: string, routesC: string }} - Generated files object
+ */
+function generateServer(routes, config, hasAssets) {
+  return {
+    serverC: generateServerC(config, hasAssets),
+    routesC: generateRoutesC(routes),
+  };
+}
+
+module.exports = { generateServer, generateServerC, generateRoutesC };

package/lib/codegen/route_table.js

@@ -25,7 +25,7 @@ function generateRouteTable(routes) {
   lines.push("");
 
   /* Route table array */
-  lines.push("static cerver_route_t cerver_routes[] = {");
+  lines.push("cerver_route_t cerver_routes[] = {");
   for (const route of routes) {
     const name = handlerName(route.method, route.urlPath);
     lines.push(
@@ -34,7 +34,7 @@ function generateRouteTable(routes) {
   }
   lines.push("};");
   lines.push(
-    `static const int cerver_route_count = ${routes.length};`
+    `const int cerver_route_count = ${routes.length};`
   );
   lines.push("");
 

package/lib/commands/build.js

@@ -3,7 +3,7 @@
 const fs = require("fs");
 const path = require("path");
 
-const { loadConfig } = require("../config");
+const { loadConfig, findProjectRoot } = require("../config");
 const { discoverRoutes } = require("../parser/discover");
 const { parseFile } = require("../parser/parse");
 const { validate } = require("../validator/validate");
@@ -17,7 +17,13 @@ const { compile: compileC } = require("../compiler/compile");
  * Full build pipeline: parse → validate → IR → codegen → compile
  */
 async function build(opts) {
-  const projectDir = process.cwd();
+  const projectDir = findProjectRoot();
+  if (!projectDir) {
+    console.log("Not a cerver project");
+    process.exit(1);
+  }
+  process.chdir(projectDir);
+
   const startTime = Date.now();
 
   console.log("\n  cerver build\n");
@@ -35,12 +41,15 @@ async function build(opts) {
   );
 
   /* ---- 2. Discover routes ---- */
-  const routesDir = path.join(projectDir, "app", "routes");
+  let routesDir = path.join(projectDir, "routes");
+  if (!fs.existsSync(routesDir)) {
+    routesDir = path.join(projectDir, "app", "routes");
+  }
   console.log("  → discovering routes...");
   const routeFiles = discoverRoutes(routesDir);
 
   if (routeFiles.length === 0) {
-    console.warn("  ⚠ no route files found in app/routes/");
+    console.warn(`  ⚠ no route files found in ${path.relative(projectDir, routesDir)}/`);
   } else {
     for (const r of routeFiles) {
       console.log(`    ${r.urlPath} ← ${path.relative(projectDir, r.filePath)}`);
@@ -70,18 +79,20 @@ async function build(opts) {
     const assets = discoverAssets(publicDir);
 
     if (assets.length > 0) {
-      let totalSize = 0;
-      for (const a of assets) {
-        totalSize += a.size;
+      const totalSize = assets.reduce((sum, a) => sum + a.size, 0);
+      for (let i = 0; i < Math.min(assets.length, 5); i++) {
+        const a = assets[i];
         console.log(
           `    ${a.servePath} (${(a.size / 1024).toFixed(1)} KB)`
         );
       }
-
+      if (assets.length > 5) {
+        console.log(`    ... and ${assets.length - 5} more assets`);
+      }
       assetsCode = await generateEmbeddedAssets(assets, config.minify, config.compression);
       console.log(
         `    ${assets.length} asset(s), ${(totalSize / 1024).toFixed(1)} KB total` +
-          (config.compression !== "none" ? ` (${config.compression} compressed)` : "")
+        (config.compression !== "none" ? ` (${config.compression} compressed)` : "")
       );
     } else {
       console.log("    no assets found in public/");
@@ -90,15 +101,29 @@ async function build(opts) {
 
   /* ---- 5. Generate C source ---- */
   console.log("  → generating C source...");
-  const cSource = generateServer(allRoutes, config, assetsCode);
+  const { serverC, routesC } = generateServer(allRoutes, config, !!assetsCode);
 
   /* Write to dist/ */
   const distDir = path.join(projectDir, "dist");
   fs.mkdirSync(distDir, { recursive: true });
 
   const serverCPath = path.join(distDir, "server.c");
-  fs.writeFileSync(serverCPath, cSource);
-  console.log(`    wrote ${(cSource.length / 1024).toFixed(1)} KB → dist/server.c`);
+  fs.writeFileSync(serverCPath, serverC);
+  console.log(`    wrote ${(serverC.length / 1024).toFixed(1)} KB → dist/server.c`);
+
+  const routesCPath = path.join(distDir, "routes.c");
+  fs.writeFileSync(routesCPath, routesC);
+  console.log(`    wrote ${(routesC.length / 1024).toFixed(1)} KB → dist/routes.c`);
+
+  const assetsCPath = path.join(distDir, "assets.c");
+  if (assetsCode) {
+    fs.writeFileSync(assetsCPath, assetsCode);
+    console.log(`    wrote ${(assetsCode.length / 1024).toFixed(1)} KB → dist/assets.c`);
+  } else {
+    if (fs.existsSync(assetsCPath)) {
+      fs.unlinkSync(assetsCPath);
+    }
+  }
 
   /* ---- 6. Copy runtime headers ---- */
   const runtimeDir = path.join(__dirname, "..", "..", "runtime");

package/lib/commands/dev.js

@@ -5,12 +5,19 @@ const path = require("path");
 const { spawn } = require("child_process");
 const chokidar = require("chokidar");
 const { build } = require("./build");
+const { findProjectRoot } = require("../config");
 
 /**
  * Dev mode: watch for changes, auto-rebuild, auto-restart.
  */
 async function dev(opts) {
-  const projectDir = process.cwd();
+  const projectDir = findProjectRoot();
+  if (!projectDir) {
+    console.log("Not a cerver project");
+    process.exit(1);
+  }
+  process.chdir(projectDir);
+
   const binaryPath = path.join(projectDir, "dist", "server");
 
   let serverProcess = null;
@@ -32,10 +39,15 @@ async function dev(opts) {
     /* Kill existing server */
     if (serverProcess) {
       console.log("\n  ↻ restarting...\n");
-      serverProcess.kill("SIGTERM");
-      serverProcess = null;
-      /* Small delay for port release */
-      await new Promise((r) => setTimeout(r, 200));
+      const procToKill = serverProcess;
+      try {
+        procToKill.kill("SIGTERM");
+        serverProcess = null;
+      } catch (err) {
+        console.error(`  ✗ failed to kill server: ${err.message}`);
+      }
+      /* Wait for old process to fully exit so the port is released */
+      await waitForExit(procToKill, 2000);
     }
 
     try {
@@ -66,29 +78,50 @@ async function dev(opts) {
     const env = { ...process.env };
     if (port) env.CERVER_PORT = port;
 
-    serverProcess = spawn(binaryPath, [], {
+    const proc = spawn(binaryPath, [], {
       stdio: "inherit",
       env,
       cwd: projectDir,
     });
 
-    serverProcess.on("error", (err) => {
+    serverProcess = proc;
+
+    proc.on("error", (err) => {
       console.error(`  ✗ server error: ${err.message}`);
-      serverProcess = null;
+      if (serverProcess === proc) serverProcess = null;
     });
 
-    serverProcess.on("exit", (code, signal) => {
-      if (signal !== "SIGTERM" && signal !== "SIGINT") {
+    proc.on("exit", (code, signal) => {
+      /* Only warn on truly unexpected exits — not intentional kills */
+      if (serverProcess === proc && signal !== "SIGTERM" && signal !== "SIGINT" && code !== 0) {
         console.error(`  ✗ server exited (code: ${code}, signal: ${signal})`);
       }
-      serverProcess = null;
+      if (serverProcess === proc) serverProcess = null;
     });
   }
 
-  function waitForExit(proc) {
+  function waitForExit(proc, timeoutMs = 2000) {
     if (!proc) return Promise.resolve();
+    if (proc.exitCode !== null || proc.signalCode !== null) {
+      return Promise.resolve();
+    }
     return new Promise((resolve) => {
-      const done = () => resolve();
+      let resolved = false;
+      const done = () => {
+        if (resolved) return;
+        resolved = true;
+        clearTimeout(timer);
+        proc.removeListener("exit", done);
+        proc.removeListener("close", done);
+        proc.removeListener("error", done);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        if (resolved) return;
+        /* Process did not exit in time — force kill */
+        try { proc.kill("SIGKILL"); } catch (_) {}
+        done();
+      }, timeoutMs);
       proc.once("exit", done);
       proc.once("close", done);
       proc.once("error", done);
@@ -97,7 +130,7 @@ async function dev(opts) {
 
   /* ---- Watch for changes ---- */
   const watchPaths = [
-    path.join(projectDir, "app"),
+    path.join(projectDir, "routes"),
     path.join(projectDir, "public"),
     path.join(projectDir, "cerver.config.js"),
   ].filter((p) => fs.existsSync(p));
@@ -139,7 +172,9 @@ async function dev(opts) {
     watcher.close();
     if (debounceTimer) clearTimeout(debounceTimer);
     if (serverProcess) {
-      serverProcess.kill("SIGTERM");
+      try {
+        serverProcess.kill("SIGTERM");
+      } catch (_) {}
       await waitForExit(serverProcess);
     }
     process.exit(0);