@velox0/cerver 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# Cerver
+
+A lightweight, compile-time web framework that transpiles restricted JavaScript server logic into highly optimized native C HTTP server binaries.
+
+Cerver takes a Next.js-style file-based routing structure (written in a strict subset of JavaScript), parses it, generates equivalent C code, embeds your static assets, and compiles it all into a single, standalone executable (~50KB) that runs with zero Node.js dependency.
+
+## Features
+
+- **Compile-Time Framework**: Your JavaScript is parsed and compiled to native C. There is no JavaScript engine (like V8) or interpreter included in the final binary.
+- **Microscopic Footprint**: Generated executables are typically ~50KB 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., `/art/[key].js`).
+
+## Getting Started
+
+1. Install globally (requires `gcc` or `clang` on your system):
+   ```bash
+   npm install -g cerver
+   ```
+
+2. Create a new project:
+   ```bash
+   cerver new my-fast-api
+   cd my-fast-api
+   ```
+
+3. Build and Run:
+   ```bash
+   cerver build
+   cerver run
+   ```
+
+## Routing
+
+Routes are defined in the `app/routes/` directory.
+
+`app/routes/index.js` (maps to `/`)
+```javascript
+export function GET(req, res) {
+  return res.html(200, "<h1>Hello World!</h1>");
+}
+```
+
+`app/routes/api/status.js` (maps to `/api/status`)
+```javascript
+export function GET(req, res) {
+  return res.json(200, '{"status": "online"}');
+}
+```
+
+`app/routes/users/[id].js` (maps to `/users/:id`)
+```javascript
+export function GET(req, res) {
+  const userId = req.params.id;
+  return res.text(200, "User ID: " + userId);
+}
+```
+
+## The Request & Response Objects
+
+Because Cerver compiles to C, the API surface is restricted.
+
+**Request (`req`)**
+- `req.path` — The request URL path
+- `req.method` — The HTTP method
+- `req.headers["user-agent"]` — Access request headers
+- `req.query.search` — Access URL query parameters
+- `req.params.id` — Access dynamic path segments
+
+**Response (`res`)**
+- `res.text(status, string)` — Send plain text
+- `res.json(status, string)` — Send JSON
+- `res.html(status, string)` — Send HTML
+
+## Supported JavaScript
+
+Cerver supports a strict, synchronous subset of JavaScript suitable for C code generation:
+- `if`/`else` statements
+- `const` / `let` variable declarations
+- String and Number literals
+- Template literals
+- Basic comparisons (`===`, `!==`, `<`, `>`)
+
+**Not Supported (Compile-Time Errors):**
+- `async`/`await` and Promises
+- Loops (`for`, `while`)
+- Classes and the `new` keyword
+- `eval()`
+- Runtime `import`/`require`
+
+## Configuration
+
+`cerver.config.js`:
+```javascript
+export default {
+  port: 8080,        // Default port
+  embed: true,       // Embed assets from public/ into the binary
+  minify: true,      // Minify HTML/CSS/JS before embedding
+  compression: "none" // Future: pre-compress assets
+}
+```
+
+## How It Works
+
+1. **Parser**: Uses Acorn to parse your JS route files into ASTs.
+2. **Validator**: Scans the AST to ensure no unsupported JS features are used.
+3. **IR**: Transforms the AST into an Intermediate Representation.
+4. **Generator**: Emits optimized C code mapping directly to your JS logic.
+5. **Asset Pipeline**: Scans the `public/` folder, minifies files, and converts them to C byte arrays.
+6. **Compiler**: Invokes `gcc` or `clang` to compile the generated code and the Cerver runtime into a native binary.

package/bin/cerver.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { Command } = require("commander");
+const pkg = require("../package.json");
+
+const program = new Command();
+
+program
+  .name("cerver")
+  .description("Compile restricted JavaScript into native C server binaries")
+  .version(pkg.version);
+
+program
+  .command("new <name>")
+  .description("Create a new cerver project")
+  .action((name) => {
+    const { newProject } = require("../lib/commands/new");
+    newProject(name);
+  });
+
+program
+  .command("build")
+  .description("Compile the project into a native binary")
+  .option("--embed", "Embed static assets into the binary", true)
+  .option("--no-embed", "Serve static assets from the filesystem")
+  .option("--static", "Produce a statically linked binary")
+  .option("--no-minify", "Skip asset minification")
+  .action((opts) => {
+    const { build } = require("../lib/commands/build");
+    build(opts);
+  });
+
+program
+  .command("run")
+  .description("Run the compiled binary")
+  .option("-p, --port <port>", "Override the port")
+  .action((opts) => {
+    const { run } = require("../lib/commands/run");
+    run(opts);
+  });
+
+program.parse();

package/lib/assets/discover.js

@@ -0,0 +1,50 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Discover all static assets in the public/ directory.
+ *
+ * @param {string} publicDir - Absolute path to public/
+ * @returns {Array<{ filePath: string, servePath: string, ext: string, size: number }>}
+ */
+function discoverAssets(publicDir) {
+  const assets = [];
+
+  if (!fs.existsSync(publicDir)) {
+    return assets;
+  }
+
+  function walk(dir, prefix) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        walk(fullPath, prefix + "/" + entry.name);
+        continue;
+      }
+
+      if (entry.name.startsWith(".")) continue; /* skip dotfiles */
+
+      const stat = fs.statSync(fullPath);
+      const servePath = prefix + "/" + entry.name;
+      const ext = path.extname(entry.name).toLowerCase();
+
+      assets.push({
+        filePath: fullPath,
+        servePath,
+        ext,
+        size: stat.size,
+      });
+    }
+  }
+
+  walk(publicDir, "");
+
+  return assets;
+}
+
+module.exports = { discoverAssets };

package/lib/assets/embed.js

@@ -0,0 +1,124 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { minifyContent } = require("./minify");
+
+/**
+ * MIME type lookup for embedding.
+ */
+const MIME_MAP = {
+  ".html": "text/html; charset=utf-8",
+  ".htm": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".pdf": "application/pdf",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".xml": "application/xml",
+  ".md": "text/markdown; charset=utf-8",
+};
+
+function mimeFromExt(ext) {
+  return MIME_MAP[ext] || "application/octet-stream";
+}
+
+/**
+ * Convert a serve path to a C-safe variable name.
+ * e.g. "/static/styles.css" → "asset_static_styles_css"
+ */
+function varName(servePath) {
+  return (
+    "asset_" +
+    servePath
+      .replace(/^\//, "")
+      .replace(/[^a-zA-Z0-9]/g, "_")
+      .replace(/_+/g, "_")
+      .replace(/_$/, "")
+  );
+}
+
+/**
+ * Convert a buffer to a C hex byte array string.
+ * e.g. { 0x3c, 0x21, 0x44, ... }
+ */
+function bufferToHexArray(buf) {
+  const lines = [];
+  for (let i = 0; i < buf.length; i += 16) {
+    const slice = buf.slice(i, Math.min(i + 16, buf.length));
+    const hex = Array.from(slice)
+      .map((b) => "0x" + b.toString(16).padStart(2, "0"))
+      .join(", ");
+    lines.push("  " + hex + ",");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Generate C source code for embedded assets.
+ *
+ * @param {Array<{ filePath: string, servePath: string, ext: string }>} assets
+ * @param {boolean} shouldMinify - Whether to minify text assets
+ * @returns {Promise<string>} - C source code
+ */
+async function generateEmbeddedAssets(assets, shouldMinify) {
+  const lines = [];
+
+  lines.push("/* Auto-generated embedded assets — do not edit */");
+  lines.push("");
+
+  const assetEntries = [];
+
+  for (const asset of assets) {
+    let content = fs.readFileSync(asset.filePath);
+
+    /* Minify if applicable */
+    if (shouldMinify) {
+      content = await minifyContent(content, asset.ext);
+    }
+
+    const name = varName(asset.servePath);
+    const mime = mimeFromExt(asset.ext);
+
+    /* Generate the byte array */
+    lines.push(`static const unsigned char ${name}[] = {`);
+    lines.push(bufferToHexArray(content));
+    lines.push("};");
+    lines.push(
+      `static const unsigned int ${name}_len = ${content.length};`
+    );
+    lines.push("");
+
+    assetEntries.push({ name, servePath: asset.servePath, mime });
+  }
+
+  /* Generate the asset table */
+  lines.push("static cerver_asset_t cerver_embedded_assets[] = {");
+  for (const entry of assetEntries) {
+    lines.push(
+      `    { "${entry.servePath}", "${entry.mime}", ${entry.name}, ${entry.name}_len },`
+    );
+  }
+  lines.push("};");
+  lines.push(
+    `static const int cerver_embedded_asset_count = ${assetEntries.length};`
+  );
+
+  return lines.join("\n");
+}
+
+module.exports = { generateEmbeddedAssets, varName, mimeFromExt };

package/lib/assets/minify.js

@@ -0,0 +1,83 @@
+"use strict";
+
+const fs = require("fs");
+
+/**
+ * Minify assets using available tools.
+ *
+ * Falls back gracefully if minification packages aren't installed.
+ * Minification is done in-memory — original files are not modified.
+ *
+ * @param {Buffer} content - File content
+ * @param {string} ext - File extension (e.g. ".html", ".css", ".js")
+ * @returns {Buffer} - Minified content (or original if minification unavailable)
+ */
+async function minifyContent(content, ext) {
+  const source = content.toString("utf8");
+
+  try {
+    switch (ext) {
+      case ".html":
+      case ".htm": {
+        try {
+          const { minify } = require("html-minifier-terser");
+          const result = await minify(source, {
+            collapseWhitespace: true,
+            removeComments: true,
+            removeRedundantAttributes: true,
+            removeEmptyAttributes: true,
+            minifyCSS: true,
+            minifyJS: true,
+          });
+          return Buffer.from(result, "utf8");
+        } catch {
+          /* html-minifier-terser not installed — skip */
+          return content;
+        }
+      }
+
+      case ".css": {
+        try {
+          const { transform } = require("lightningcss");
+          const result = transform({
+            filename: "style.css",
+            code: content,
+            minify: true,
+          });
+          return Buffer.from(result.code);
+        } catch {
+          /* lightningcss not installed — try basic minification */
+          const minified = source
+            .replace(/\/\*[\s\S]*?\*\//g, "")  /* remove comments */
+            .replace(/\s+/g, " ")               /* collapse whitespace */
+            .replace(/\s*([{}:;,])\s*/g, "$1")  /* remove space around symbols */
+            .trim();
+          return Buffer.from(minified, "utf8");
+        }
+      }
+
+      case ".js":
+      case ".mjs": {
+        try {
+          const { minify } = require("terser");
+          const result = await minify(source);
+          if (result.code) {
+            return Buffer.from(result.code, "utf8");
+          }
+          return content;
+        } catch {
+          /* terser not installed — skip */
+          return content;
+        }
+      }
+
+      default:
+        return content;
+    }
+  } catch {
+    /* If minification fails for any reason, return original */
+    return content;
+  }
+}
+
+module.exports = { minifyContent };

package/lib/codegen/emit.js

@@ -0,0 +1,249 @@
+"use strict";
+
+/**
+ * emit.js — Low-level C code emission helpers.
+ *
+ * Builds C source strings from IR nodes with proper formatting,
+ * escaping, and indentation.
+ */
+
+/**
+ * Escape a string for use as a C string literal.
+ */
+function escapeC(str) {
+  return str
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t")
+    .replace(/\0/g, "\\0");
+}
+
+/**
+ * Generate a C string literal from a JS string.
+ */
+function cString(str) {
+  return `"${escapeC(str)}"`;
+}
+
+/**
+ * Generate an indented line.
+ */
+function indent(level) {
+  return "    ".repeat(level);
+}
+
+/**
+ * Convert a URL path + method into a C-safe function name.
+ * e.g. "GET", "/item/:id" → "handle_GET_item_id"
+ */
+function handlerName(method, urlPath) {
+  const safe = urlPath
+    .replace(/^\//, "")           /* remove leading slash */
+    .replace(/\//g, "_")          /* / → _ */
+    .replace(/:/g, "")            /* remove : from params */
+    .replace(/[^a-zA-Z0-9_]/g, "_")
+    .replace(/_+/g, "_")          /* collapse multiple underscores */
+    .replace(/_$/, "");           /* remove trailing underscore */
+
+  if (!safe) return `handle_${method}_index`;
+  return `handle_${method}_${safe}`;
+}
+
+/**
+ * Emit a C expression from an IR expression node.
+ */
+function emitExpression(expr) {
+  if (!expr) return '""';
+
+  switch (expr.type) {
+    case "StringLiteral":
+      return cString(expr.value);
+
+    case "NumberLiteral":
+      return String(expr.value);
+
+    case "Identifier":
+      return expr.name;
+
+    case "ParamAccess":
+      return `cerver_req_param(req, ${cString(expr.paramName)})`;
+
+    case "QueryAccess":
+      return `cerver_req_query(req, ${cString(expr.queryName)})`;
+
+    case "HeaderAccess":
+      return `cerver_req_header(req, ${cString(expr.headerName)})`;
+
+    case "Comparison": {
+      const left = emitExpression(expr.left);
+      const right = emitExpression(expr.right);
+
+      /* String comparisons use strcmp */
+      if (isStringExpr(expr.left) || isStringExpr(expr.right)) {
+        if (expr.operator === "===" || expr.operator === "==") {
+          return `(strcmp(${left}, ${right}) == 0)`;
+        }
+        if (expr.operator === "!==" || expr.operator === "!=") {
+          return `(strcmp(${left}, ${right}) != 0)`;
+        }
+      }
+
+      /* Numeric comparisons */
+      const cOp = expr.operator === "===" ? "==" : expr.operator === "!==" ? "!=" : expr.operator;
+      return `(${left} ${cOp} ${right})`;
+    }
+
+    case "Logical": {
+      const left = emitExpression(expr.left);
+      const right = emitExpression(expr.right);
+      return `(${left} ${expr.operator} ${right})`;
+    }
+
+    case "Unary": {
+      const arg = emitExpression(expr.argument);
+      return `(${expr.operator}${arg})`;
+    }
+
+    case "Concat": {
+      /* For template literals, we generate snprintf into a stack buffer */
+      /* This is handled specially in emitStatement when part of a return */
+      /* For simple cases, just concatenate literals */
+      const parts = expr.parts.map(emitExpression);
+      /* If all parts are string literals, we can concatenate at compile time */
+      const allLiteral = expr.parts.every((p) => p.type === "StringLiteral");
+      if (allLiteral) {
+        return cString(expr.parts.map((p) => p.value).join(""));
+      }
+      /* Otherwise, we'll need a runtime sprintf — return a placeholder */
+      /* The generator will handle this at the statement level */
+      return `__concat_${parts.length}__`;
+    }
+
+    case "Call": {
+      /* res.text(status, body) etc. */
+      if (expr.object === "res") {
+        const fnName = `cerver_res_${expr.method}`;
+        const args = expr.args.map(emitExpression);
+        return `${fnName}(res, ${args.join(", ")})`;
+      }
+
+      /* String method calls — map to C equivalents */
+      if (expr.method === "toLowerCase" || expr.method === "toUpperCase") {
+        /* These would need a helper — for now return the object as-is */
+        return emitExpression(expr.object);
+      }
+      if (expr.method === "includes") {
+        const haystack = emitExpression(expr.object);
+        const needle = expr.args[0] ? emitExpression(expr.args[0]) : '""';
+        return `(strstr(${haystack}, ${needle}) != NULL)`;
+      }
+
+      return '""';
+    }
+
+    default:
+      return '""';
+  }
+}
+
+/**
+ * Check if an IR expression evaluates to a string type.
+ */
+function isStringExpr(expr) {
+  if (!expr) return false;
+  return (
+    expr.type === "StringLiteral" ||
+    expr.type === "ParamAccess" ||
+    expr.type === "QueryAccess" ||
+    expr.type === "HeaderAccess" ||
+    expr.type === "Concat" ||
+    expr.type === "Identifier"
+  );
+}
+
+/**
+ * Emit a statement into C code lines.
+ * Returns an array of C source lines.
+ */
+function emitStatement(stmt, level) {
+  if (!stmt) return [];
+  const pad = indent(level);
+  const lines = [];
+
+  switch (stmt.type) {
+    case "Return": {
+      const fnName = `cerver_res_${stmt.responseType}`;
+      const valueCode = emitExpression(stmt.value);
+      lines.push(`${pad}${fnName}(res, ${stmt.status}, ${valueCode});`);
+      lines.push(`${pad}return;`);
+      break;
+    }
+
+    case "If": {
+      const cond = emitExpression(stmt.condition);
+      lines.push(`${pad}if (${cond}) {`);
+
+      if (stmt.thenBody) {
+        for (const s of stmt.thenBody) {
+          lines.push(...emitStatement(s, level + 1));
+        }
+      }
+
+      if (stmt.elseBody && stmt.elseBody.length > 0) {
+        /* Check if it's an else-if */
+        if (stmt.elseBody.length === 1 && stmt.elseBody[0].type === "If") {
+          lines.push(`${pad}} else `);
+          /* Emit the else-if inline */
+          const elseIfLines = emitStatement(stmt.elseBody[0], level);
+          /* Remove leading whitespace from first line to make it "} else if" */
+          if (elseIfLines.length > 0) {
+            elseIfLines[0] = elseIfLines[0].trimStart();
+            lines[lines.length - 1] += elseIfLines[0];
+            lines.push(...elseIfLines.slice(1));
+          }
+        } else {
+          lines.push(`${pad}} else {`);
+          for (const s of stmt.elseBody) {
+            lines.push(...emitStatement(s, level + 1));
+          }
+          lines.push(`${pad}}`);
+        }
+      } else {
+        lines.push(`${pad}}`);
+      }
+      break;
+    }
+
+    case "Variable": {
+      const val = emitExpression(stmt.initExpr);
+      if (stmt.valueType === "number") {
+        lines.push(`${pad}int ${stmt.name} = ${val};`);
+      } else {
+        lines.push(`${pad}const char *${stmt.name} = ${val};`);
+      }
+      break;
+    }
+
+    case "Call": {
+      lines.push(`${pad}${emitExpression(stmt)};`);
+      break;
+    }
+
+    default:
+      break;
+  }
+
+  return lines;
+}
+
+module.exports = {
+  escapeC,
+  cString,
+  indent,
+  handlerName,
+  emitExpression,
+  emitStatement,
+  isStringExpr,
+};