smaoog 0.0.1

package/src/router.js

@@ -0,0 +1,497 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { extname, resolve, sep } from "node:path";
+import React from "react";
+import { ASSET_PREFIX, createClientContext } from "./assets.js";
+import { runHandler } from "./dispatch.js";
+import { matchRoute } from "./routes.js";
+import { createRenderIntent, sendJson, sendResult } from "./response.js";
+import { SUBMIT_HEADER } from "./protocol.js";
+import { RESERVED_PREFIX } from "./server.js";
+
+// The client navigation endpoint. A `<Link>` click fetches `?to=/target` here;
+// the framework runs the target route's GET handler and serializes its
+// RenderIntent as a JSON page-swap payload (see sendResult's nav mode).
+const NAV_PATH = "/_smaoog/nav";
+
+// HTTP methods a route module may export as named handlers, in canonical order.
+// The order is reused for the Allow header so it is deterministic.
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+const renderPage = (req, res) => res.render();
+
+// Pathname without the query string. A dummy origin lets the URL parser handle
+// path-only request targets like "/about?x=1".
+function pathnameOf(url) {
+  return new URL(url, "http://localhost").pathname;
+}
+
+// Requests Vite owns in dev: its virtual/internal endpoints, pre-bundled deps,
+// and transformed source modules. CSS under /src stays on the framework's own
+// path (traversal-safe), so only non-CSS /src files are delegated here.
+function isViteModuleRequest(path) {
+  if (path.startsWith("/@") || path.startsWith("/node_modules/")) return true;
+  if (path.startsWith("/src/")) return !path.endsWith(".css");
+  return false;
+}
+
+function hasPage(mod) {
+  return typeof mod.default === "function";
+}
+
+function DefaultNotFoundPage() {
+  return React.createElement("h1", null, "Not Found");
+}
+
+// `message` is only populated in dev (see errorProps); in production it is
+// omitted so internal error detail never reaches the client.
+function DefaultErrorPage({ message }) {
+  return React.createElement(
+    "div",
+    null,
+    React.createElement("h1", null, "Internal Server Error"),
+    message ? React.createElement("pre", null, message) : null,
+  );
+}
+
+// Resolve the route module's final method handler set. A lowercase export of a
+// known method (`get`, `post`, ...) is almost always a typo for the uppercase
+// name, so it is a clear error rather than a silently dead handler. Page routes
+// without an explicit GET get an implicit render GET.
+function resolveHandlers(mod) {
+  const handlers = {};
+  for (const method of HTTP_METHODS) {
+    const lower = method.toLowerCase();
+    if (typeof mod[lower] === "function") {
+      throw new Error(
+        `Route exports "${lower}" but HTTP method handlers must be uppercase ("${method}").`,
+      );
+    }
+    if (typeof mod[method] === "function") {
+      handlers[method] = mod[method];
+    }
+  }
+
+  if (!handlers.GET && hasPage(mod)) {
+    handlers.GET = renderPage;
+  }
+
+  return handlers;
+}
+
+// The Allow header value for a route: its declared methods plus the ones the
+// framework derives — HEAD (from GET) and the always-available OPTIONS.
+function allowHeader(handlers) {
+  const methods = HTTP_METHODS.filter((method) => handlers[method]);
+  if (handlers.GET) methods.push("HEAD");
+  methods.push("OPTIONS");
+  return methods.join(", ");
+}
+
+function sendText(nodeRes, status, body, headers = {}) {
+  nodeRes.statusCode = status;
+  nodeRes.setHeader("content-type", "text/plain; charset=utf-8");
+  for (const [key, value] of Object.entries(headers)) nodeRes.setHeader(key, value);
+  nodeRes.end(body);
+}
+
+function contentType(file) {
+  switch (extname(file).toLowerCase()) {
+    case ".css":
+      return "text/css; charset=utf-8";
+    case ".html":
+      return "text/html; charset=utf-8";
+    case ".js":
+      return "text/javascript; charset=utf-8";
+    case ".json":
+      return "application/json; charset=utf-8";
+    case ".svg":
+      return "image/svg+xml";
+    case ".ico":
+      return "image/x-icon";
+    case ".png":
+      return "image/png";
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".txt":
+      return "text/plain; charset=utf-8";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+function safeFilePath(root, pathname) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  const file = resolve(root, `.${decoded}`);
+  const boundary = root.endsWith(sep) ? root : `${root}${sep}`;
+  if (file !== root && !file.startsWith(boundary)) return null;
+  return file;
+}
+
+// Whether `pathname` resolves to an existing regular file under `root` (and
+// stays within it). Used to decide if a stylesheet is worth transforming before
+// handing the path to Vite, which throws for a missing module.
+async function isFile(root, pathname) {
+  const file = safeFilePath(root, pathname);
+  if (!file) return false;
+  try {
+    return (await stat(file)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function sendFile(root, pathname, nodeReq, nodeRes) {
+  const method = (nodeReq.method ?? "GET").toUpperCase();
+  if (method !== "GET" && method !== "HEAD") return false;
+
+  const file = safeFilePath(root, pathname);
+  if (!file) return false;
+
+  let info;
+  try {
+    info = await stat(file);
+  } catch {
+    return false;
+  }
+  if (!info.isFile()) return false;
+
+  nodeRes.statusCode = 200;
+  nodeRes.setHeader("content-type", contentType(file));
+  nodeRes.setHeader("content-length", String(info.size));
+
+  if (method === "HEAD") {
+    nodeRes.end();
+    return true;
+  }
+
+  await new Promise((resolveStream, rejectStream) => {
+    const stream = createReadStream(file);
+    stream.on("error", rejectStream);
+    nodeRes.on("error", rejectStream);
+    nodeRes.on("finish", resolveStream);
+    stream.pipe(nodeRes);
+  });
+  return true;
+}
+
+// Build the framework's request handler. It owns the reserved prefix, route
+// matching, HTTP method matching, error pages, and static file serving — but
+// not how modules are loaded. `loader` abstracts that:
+//   - loader.route(route)  -> the route's module
+//   - loader.document()    -> the document module, or null
+//   - loader.errorPage(kind) -> the user _404/_500 module, or null
+// In dev that's Vite SSR loading; in production it's importing built modules.
+// `srcRoot` enables the dev-only source-CSS path when provided. `viteMiddlewares`
+// (dev only) serves transformed browser modules and Vite internals.
+export function createRequestHandler({
+  routes,
+  loader,
+  publicRoot,
+  srcRoot = null,
+  assetsRoot = null,
+  clientAssets = null,
+  viteMiddlewares = null,
+  transformStylesheet = null,
+  dev = false,
+  options = {},
+}) {
+  // Resolves dev/prod URLs for stylesheets, the client entry, and page hydration
+  // modules; the Document helpers read it through the render context.
+  const clientContext = createClientContext({ dev, manifest: clientAssets });
+  // Props for an error page. In dev the raw message is shown to aid debugging;
+  // in production it is kept server-side (logged) and never sent to the client.
+  function errorProps(err) {
+    if (dev) return { message: err?.message ?? String(err) };
+    console.error("[smaoog] route error:", err);
+    return {};
+  }
+  // Load a user error page, or fall back to the framework default. The id is the
+  // convention name so meta/hydration have a stable identity in both cases.
+  async function loadErrorPage(kind) {
+    const id = kind === "notFound" ? "_404" : "_500";
+    const mod = await loader.errorPage(kind);
+    if (!mod) {
+      return {
+        id,
+        mod: { default: kind === "notFound" ? DefaultNotFoundPage : DefaultErrorPage },
+      };
+    }
+    if (!hasPage(mod)) {
+      throw new Error(`Error page "${id}" must have a default export.`);
+    }
+    return { id, mod };
+  }
+
+  async function renderErrorPage(
+    nodeRes,
+    kind,
+    { status, props = {}, headers = {}, head = false, mode = "html" },
+  ) {
+    try {
+      const page = await loadErrorPage(kind);
+      // Only the full-load (html) path wraps the page in a document; enhanced
+      // requests serialize the error page as a JSON render envelope.
+      const documentMod = mode === "html" ? await loader.document() : null;
+      sendResult(
+        nodeRes,
+        createRenderIntent({
+          status,
+          headers,
+          props,
+          routeId: page.id,
+          Page: page.mod.default,
+          Document: documentMod?.default,
+          routeModule: page.mod,
+          client: clientContext,
+        }),
+        { head, mode },
+      );
+    } catch (err) {
+      // A broken notFound page falls back to the error page once; a broken error
+      // page falls back to plain text so we never recurse forever.
+      if (kind !== "error" && !nodeRes.headersSent) {
+        await renderErrorPage(nodeRes, "error", {
+          status: 500,
+          props: errorProps(err),
+          head,
+          mode,
+        });
+        return;
+      }
+
+      if (!nodeRes.headersSent) {
+        if (!dev) console.error("[smaoog] error page failed:", err);
+        const detail = dev ? `\n\n${err?.message ?? err}` : "";
+        sendText(nodeRes, 500, `Internal Server Error${detail}`);
+      } else if (!nodeRes.writableEnded) {
+        nodeRes.end();
+      }
+    }
+  }
+
+  // Serve a matched route. Shared by ordinary requests, the navigation endpoint,
+  // and <Form> mutations, so all three run the exact same matching, method
+  // resolution, and handler dispatch — the only difference is how the result is
+  // serialized (`mode`). `reqUrl` is the URL the handler should see; for nav it
+  // is the target URL, not `/_smaoog/nav`.
+  async function dispatchMatch(nodeReq, nodeRes, { match, method, head, mode, reqUrl }) {
+    const mod = await loader.route(match.route);
+    // The document only wraps rendered HTML, so endpoint-only routes (no default
+    // export) — and enhanced requests, which never render a document — skip it.
+    const documentMod = mode === "html" && hasPage(mod) ? await loader.document() : null;
+    const handlers = resolveHandlers(mod);
+    const allow = allowHeader(handlers);
+
+    // OPTIONS is answered by the framework: 204 with the Allow header.
+    if (method === "OPTIONS") {
+      nodeRes.statusCode = 204;
+      nodeRes.setHeader("Allow", allow);
+      nodeRes.end();
+      return;
+    }
+
+    // HEAD runs the GET handler but the body is stripped on the way out.
+    const handler = handlers[head ? "GET" : method];
+
+    // Known route, unsupported method. A navigation request can't swap a page
+    // it has no GET for, so it falls back to a full load; a normal request gets
+    // the usual 405 with the Allow header.
+    if (!handler) {
+      if (mode === "nav") {
+        sendJson(nodeRes, 200, { kind: "reload" });
+        return;
+      }
+      sendText(nodeRes, 405, "Method Not Allowed", { Allow: allow });
+      return;
+    }
+
+    await runHandler(handler, nodeReq, nodeRes, {
+      ...options,
+      params: match.params,
+      url: reqUrl,
+      head,
+      mode,
+      // Rendering is only allowed when the route has a page (default export).
+      canRender: hasPage(mod),
+      renderInfo: {
+        routeId: match.route.id,
+        Page: mod.default,
+        routeModule: mod,
+        Document: documentMod?.default,
+        client: clientContext,
+      },
+      notFoundHandler: (result, opts) =>
+        renderErrorPage(nodeRes, "notFound", {
+          status: result.status,
+          props: result.props,
+          headers: result.headers,
+          head: opts.head,
+          mode,
+        }),
+      errorHandler: (err, opts) =>
+        renderErrorPage(nodeRes, "error", {
+          status: 500,
+          props: errorProps(err),
+          head: opts.head,
+          mode,
+        }),
+    });
+  }
+
+  // The /_smaoog/nav endpoint: render the target route for client navigation.
+  // It does not implement a second router — it parses the target URL, runs the
+  // normal matcher, and dispatches the target's GET handler with `nav` mode so
+  // the RenderIntent is serialized as a JSON page-swap payload.
+  async function handleNav(nodeReq, nodeRes) {
+    const to = new URL(nodeReq.url, "http://localhost").searchParams.get("to");
+    if (!to) {
+      sendJson(nodeRes, 400, { kind: "error", message: "Missing 'to' parameter" });
+      return;
+    }
+
+    let target;
+    try {
+      target = new URL(to, "http://localhost");
+    } catch {
+      sendJson(nodeRes, 400, { kind: "error", message: "Invalid 'to' parameter" });
+      return;
+    }
+
+    // Navigation never targets framework internals; let the browser handle it.
+    if (target.pathname === "/_smaoog" || target.pathname.startsWith(RESERVED_PREFIX)) {
+      sendJson(nodeRes, 200, { kind: "reload" });
+      return;
+    }
+
+    const match = matchRoute(routes, target.pathname);
+    if (!match) {
+      // No route — the full-page request would 404, so the client swaps to the
+      // 404 page using the same payload shape.
+      await renderErrorPage(nodeRes, "notFound", { status: 404, mode: "nav" });
+      return;
+    }
+
+    // The handler runs as a GET for the target URL (path + query), so it sees
+    // the same params and query it would when serving the page directly.
+    await dispatchMatch(nodeReq, nodeRes, {
+      match,
+      method: "GET",
+      head: false,
+      mode: "nav",
+      reqUrl: to,
+    });
+  }
+
+  return async function handle(nodeReq, nodeRes) {
+    const method = (nodeReq.method ?? "GET").toUpperCase();
+    const head = method === "HEAD";
+    // An enhanced <Form> mutation carries the submit header; it serializes
+    // render/redirect results as JSON envelopes while leaving plain responses
+    // untouched. Everything else is an ordinary full-load (html) request.
+    // Computed up front so unmatched and error paths serialize consistently too.
+    const mode = nodeReq.headers[SUBMIT_HEADER] !== undefined ? "form" : "html";
+
+    try {
+      const path = pathnameOf(nodeReq.url);
+
+      // Reserved prefix: never matched against user content. The navigation
+      // endpoint lives here; production client assets are served here; anything
+      // else is a 404, but a distinguishable one.
+      if (path === "/_smaoog" || path.startsWith(RESERVED_PREFIX)) {
+        if (path === NAV_PATH) {
+          await handleNav(nodeReq, nodeRes);
+          return;
+        }
+        if (assetsRoot && path.startsWith(ASSET_PREFIX)) {
+          const assetPath = path.slice(ASSET_PREFIX.length - 1);
+          if (await sendFile(assetsRoot, assetPath, nodeReq, nodeRes)) return;
+        }
+        sendText(nodeRes, 404, "Not Found", { "X-Smaoog-Reserved": "1" });
+        return;
+      }
+
+      const match = matchRoute(routes, path);
+      if (!match) {
+        // Dev-only: serve linked source stylesheets, scoped to src/ so the path
+        // can't resolve to other .css files under the root. When a Vite
+        // transformer is wired (the `smaoog dev` path), the CSS goes through it
+        // so Tailwind/PostCSS and `@import` resolution run — matching the
+        // production stylesheet pipeline. `?direct` makes Vite return compiled
+        // CSS rather than the HMR JS module a bare import would yield. A compile
+        // error throws and surfaces on the dev error page; otherwise (no
+        // transformer, or nothing to transform) the raw file is streamed.
+        if (srcRoot && path.startsWith("/src/") && path.endsWith(".css")) {
+          const cssPath = path.slice("/src".length);
+          // Only transform a stylesheet that exists, and only for GET/HEAD (the
+          // guard sendFile enforces). A missing file or a write method falls
+          // through to a 404 as the raw path did, rather than letting Vite throw
+          // for a missing module and turning it into a 500. A transform error on
+          // a file that *does* exist still surfaces on the dev error page.
+          const method = (nodeReq.method ?? "GET").toUpperCase();
+          if (
+            transformStylesheet &&
+            (method === "GET" || method === "HEAD") &&
+            (await isFile(srcRoot, cssPath))
+          ) {
+            const result = await transformStylesheet(path + "?direct");
+            if (result) {
+              nodeRes.statusCode = 200;
+              nodeRes.setHeader("content-type", "text/css; charset=utf-8");
+              nodeRes.setHeader("content-length", String(Buffer.byteLength(result.code)));
+              nodeRes.end(method === "HEAD" ? undefined : result.code);
+              return;
+            }
+          }
+          if (await sendFile(srcRoot, cssPath, nodeReq, nodeRes)) return;
+        }
+        // Dev: hand transformed browser modules and Vite's own endpoints
+        // (`/@…`, `/node_modules/…`, non-CSS `/src/…`) to Vite. This runs only
+        // after route matching, so a user route that happens to live at one of
+        // those URLs still wins — dev and prod resolve it the same way.
+        if (viteMiddlewares && isViteModuleRequest(path)) {
+          await new Promise((done) => {
+            viteMiddlewares(nodeReq, nodeRes, () => {
+              if (!nodeRes.headersSent) sendText(nodeRes, 404, "Not Found");
+              done();
+            });
+            nodeRes.on("close", done);
+          });
+          return;
+        }
+        if (await sendFile(publicRoot, path, nodeReq, nodeRes)) {
+          return;
+        }
+        await renderErrorPage(nodeRes, "notFound", { status: 404, head, mode });
+        return;
+      }
+
+      await dispatchMatch(nodeReq, nodeRes, {
+        match,
+        method,
+        head,
+        mode,
+        reqUrl: nodeReq.url,
+      });
+    } catch (err) {
+      if (!nodeRes.headersSent) {
+        await renderErrorPage(nodeRes, "error", {
+          status: 500,
+          props: errorProps(err),
+          head,
+          mode,
+        });
+      } else if (!nodeRes.writableEnded) {
+        // A handler wrote through res.raw and then threw: headers are already
+        // out, so end the response rather than leaving the client hanging.
+        nodeRes.end();
+      }
+    }
+  };
+}

package/src/routes.js

@@ -0,0 +1,175 @@
+import { readdir } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+
+// Route source extensions, in no particular precedence (a single path may only
+// have one route file; duplicates across extensions are a conflict).
+export const ROUTE_EXTENSIONS = [".js", ".jsx", ".ts", ".tsx"];
+
+// The framework-reserved namespace under src/routes.
+const RESERVED_SEGMENT = "_smaoog";
+
+// Recursively collect every file under `dir` (absolute paths).
+async function walk(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walk(full)));
+    } else if (entry.isFile()) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+// Strip a known route extension from a filename; returns null if it isn't a
+// route file.
+function stripExtension(name) {
+  for (const ext of ROUTE_EXTENSIONS) {
+    if (name.endsWith(ext)) return name.slice(0, -ext.length);
+  }
+  return null;
+}
+
+// Turn a raw path segment ("posts", "[id]") into a route segment, rejecting
+// unsupported syntax (catch-all/optional are not in v0).
+function toSegment(raw) {
+  if (raw.startsWith("[") || raw.endsWith("]")) {
+    const match = /^\[([A-Za-z0-9_]+)\]$/.exec(raw);
+    if (!match) {
+      throw new Error(
+        `Unsupported route segment "${raw}": only single [param] segments are supported in v0`,
+      );
+    }
+    return { type: "param", name: match[1] };
+  }
+  return { type: "static", value: raw };
+}
+
+// Build the pattern string ("/posts/:id") from route segments.
+function toPattern(segments) {
+  if (segments.length === 0) return "/";
+  return (
+    "/" +
+    segments.map((s) => (s.type === "static" ? s.value : `:${s.name}`)).join("/")
+  );
+}
+
+// A structural key that ignores param names, so two dynamic routes at the same
+// position ("[id]" vs "[slug]") collide.
+function matchKey(segments) {
+  return segments.map((s) => (s.type === "static" ? s.value : ":")).join("/");
+}
+
+// Scan `routesDir` and return a deterministic, conflict-checked list of routes.
+export async function scanRoutes(routesDir) {
+  const files = await walk(routesDir);
+  const routes = [];
+
+  for (const file of files) {
+    const rel = relative(routesDir, file);
+    const routeId = `src/routes/${rel.split(sep).join("/")}`;
+    const parts = rel.split(sep);
+
+    const stripped = stripExtension(parts[parts.length - 1]);
+    if (stripped === null) continue; // not a route file
+
+    // Raw names: folders + filename without extension.
+    const rawSegments = [...parts.slice(0, -1), stripped];
+
+    // Reserved namespace check runs before the generic underscore rule so the
+    // user gets a clear error instead of a silent skip.
+    if (rawSegments[0] === RESERVED_SEGMENT) {
+      throw new Error(
+        `"${RESERVED_SEGMENT}" is reserved for the framework; user routes cannot live under src/routes/${RESERVED_SEGMENT}/`,
+      );
+    }
+
+    // Files/folders starting with "_" are private and ignored by the router.
+    if (rawSegments.some((s) => s.startsWith("_"))) continue;
+
+    // A trailing "index" denotes the folder's index route.
+    const routeNames =
+      rawSegments[rawSegments.length - 1] === "index"
+        ? rawSegments.slice(0, -1)
+        : rawSegments;
+
+    const segments = routeNames.map(toSegment);
+
+    routes.push({
+      id: routeId,
+      file,
+      pattern: toPattern(segments),
+      segments,
+    });
+  }
+
+  // Conflict detection: any two routes resolving to the same structural path.
+  const seen = new Map();
+  for (const route of routes) {
+    const key = matchKey(route.segments);
+    const other = seen.get(key);
+    if (other) {
+      throw new Error(
+        `Route conflict: "${other.id}" and "${route.id}" resolve to the same path`,
+      );
+    }
+    seen.set(key, route);
+  }
+
+  // Deterministic order regardless of filesystem read order.
+  routes.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return routes;
+}
+
+// More-static-first comparator for routes of equal length.
+function compareSpecificity(a, b) {
+  for (let i = 0; i < a.segments.length; i++) {
+    const ta = a.segments[i].type;
+    const tb = b.segments[i].type;
+    if (ta !== tb) return ta === "static" ? -1 : 1;
+  }
+  return 0;
+}
+
+// Match a pathname against the scanned routes. Returns { route, params } for
+// the most specific match (static beats dynamic), or null.
+export function matchRoute(routes, pathname) {
+  const parts = pathname.split("/").filter(Boolean);
+
+  const candidates = [];
+  for (const route of routes) {
+    if (route.segments.length !== parts.length) continue;
+
+    const params = {};
+    let matched = true;
+    for (let i = 0; i < parts.length; i++) {
+      const seg = route.segments[i];
+      if (seg.type === "static") {
+        if (seg.value !== parts[i]) {
+          matched = false;
+          break;
+        }
+      } else {
+        let value;
+        try {
+          value = decodeURIComponent(parts[i]);
+        } catch {
+          value = parts[i];
+        }
+        Object.defineProperty(params, seg.name, {
+          value,
+          enumerable: true,
+          configurable: true,
+          writable: true,
+        });
+      }
+    }
+    if (matched) candidates.push({ route, params });
+  }
+
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => compareSpecificity(a.route, b.route));
+  return candidates[0];
+}

package/src/serialize.js

@@ -0,0 +1,17 @@
+// Ids for the inline JSON scripts the server emits and the client runtime reads.
+// They carry the hydration props and the route identity/module for the page.
+export const PROPS_SCRIPT_ID = "__SMAOOG_PROPS__";
+export const ROUTE_SCRIPT_ID = "__SMAOOG_ROUTE__";
+
+// Serialize a value for embedding inside `<script type="application/json">`.
+// JSON is valid as element text except for the few sequences that could end the
+// script element or break HTML/JS line parsing, so each is escaped to its JSON
+// unicode form (still valid JSON the client parses back losslessly):
+//   <  >  &  stop a literal "</script>" or entity-ish sequence,
+//   U+2028 / U+2029 are raw newlines in a JS string context.
+export function serializeJsonForScript(value) {
+  return JSON.stringify(value ?? null).replace(
+    /[<>&\u2028\u2029]/g,
+    (ch) => "\\u" + ch.charCodeAt(0).toString(16).padStart(4, "0"),
+  );
+}