smaoog 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aggelos Gesoulis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# smaoog
+
+A lightweight, SSR React framework for standalone Node, with file-based routing.
+
+> **Status: alpha (`0.0.x`).** The API is still settling and may change between releases.
+
+smaoog renders React on the server, hydrates it in the browser and routes by the files in your `src/routes` directory. It runs as a plain long-lived Node server. That means no edge runtime support is planned.
+
+## Quick start
+
+The fastest way to start is the scaffolder:
+
+```bash
+npm create smaoog my-app
+cd my-app
+npm install
+npm run dev
+```
+
+That gives you a TypeScript app with Tailwind wired up. Pass `--js` for the JavaScript app.
+
+## How it works
+
+### File routes
+
+Files under `src/routes` become routes:
+
+```txt
+src/routes/index.tsx        ->  /
+src/routes/about.tsx        ->  /about
+src/routes/posts/index.tsx  ->  /posts
+src/routes/posts/[id].tsx   ->  /posts/:id
+```
+
+A module's **default export** is the page component. You can export named HTTP method handlers (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) for endpoints and mutations. A default export with no `GET` is automatically the route's `GET` handler.
+
+```jsx
+// src/routes/posts/[id].jsx
+export async function GET(req, res) {
+  const post = await loadPost(req.params.id);
+  return res.render({ post });
+}
+
+export default function Post({ post }) {
+  return <article>{post.title}</article>;
+}
+```
+
+### Handlers
+
+Handlers receive request/response wrappers:
+
+```txt
+req.method  req.path  req.params  req.query  req.headers
+await req.body()  await req.rawBody()  req.raw
+
+res.status(code)  res.headers({...})  res.text()  res.json()
+res.redirect(path)  res.render(props?)  res.notFound(props?)
+```
+
+### Navigation and forms
+
+- `<Link href>` does client-side navigation without a full reload.
+- `<Form>` enhances mutations and GET search forms. A handler can answer a submission with `res.redirect()`, JSON (`onSuccess`/`onError`), or `res.render()` to swap the page in place — the standard server-validation flow.
+
+```jsx
+import { Link, Form } from "smaoog";
+```
+
+### Metadata
+
+Export `meta` (an object or a function of `{ props }`) to manage the document head:
+
+```jsx
+export const meta = { title: "Posts", description: "All posts" };
+or
+export function meta({ props }) {
+  return { title: props.title };
+}
+```
+
+### Server-only modules
+
+Any module named `*.server.{js,jsx,ts,tsx}` is server-only. Route handlers and the server build may import it. If it ever reaches the client bundle the build fails.Use it for database clients and secrets.
+
+```js
+// src/db.server.js
+import { MongoClient } from "mongodb";
+export const db = new MongoClient(process.env.MONGO_URL).db("app");
+```
+
+## Commands
+
+```bash
+smaoog dev      # development server
+smaoog build    # production build into .smaoog/
+smaoog start    # serve the production build
+```
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "smaoog",
+  "version": "0.0.1",
+  "description": "A lightweight SSR React framework for standalone Node with file-based routing.",
+  "license": "MIT",
+  "author": "Aggelos Gesoulis",
+  "type": "module",
+  "types": "./src/index.d.ts",
+  "keywords": [
+    "react",
+    "ssr",
+    "framework",
+    "node"
+  ],
+  "homepage": "https://github.com/anges244/smaoog#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anges244/smaoog.git",
+    "directory": "packages/smaoog"
+  },
+  "bugs": {
+    "url": "https://github.com/anges244/smaoog/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "smaoog": "./src/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./client": {
+      "types": "./src/client/index.d.ts",
+      "default": "./src/client/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.js"
+  ],
+  "dependencies": {
+    "@vitejs/plugin-react": "^4.3.4",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vite": "^6.0.0"
+  }
+}

package/src/assets.js

@@ -0,0 +1,118 @@
+export const ASSET_PREFIX = "/_smaoog/assets/";
+
+function trimLeadingSlash(value) {
+  return value.replace(/^\/+/, "");
+}
+
+// Strip a leading slash so a source path can be compared by its in-app form
+// (e.g. "/src/app.css" and "src/app.css" both normalize to "src/app.css").
+export function normalizeAppPath(path) {
+  return trimLeadingSlash(String(path));
+}
+
+export function appPath(path) {
+  const value = String(path);
+  return value.startsWith("/") ? value : `/${value}`;
+}
+
+// The public URL for a built asset. Build output file names are relative to the
+// client out dir ("assets/app-HASH.css"); they are served under the reserved
+// asset prefix, so the leading "assets/" is folded into ASSET_PREFIX.
+export function assetHref(file) {
+  return ASSET_PREFIX + trimLeadingSlash(file).replace(/^assets\//, "");
+}
+
+// The Phase 14 client manifest is built straight from the client build's Rollup
+// output — entry chunks carry their input `name`, their emitted `fileName`, and
+// the CSS they import; standalone stylesheet inputs come out as CSS assets named
+// after their input. Reading the output object avoids parsing Vite's manifest
+// JSON and guessing at its keys.
+//
+//   entry:       { id, file, href, css, imports } | null
+//   routes:      { [routeId]: { file, href, css, imports } }   page routes only
+//   stylesheets: { [source]: { file, href } }
+//
+// Later phases (hydration, navigation) consume this shape; they must not
+// redefine it.
+export function createClientManifest({
+  output = [],
+  routeEntries = [],
+  clientEntry = null,
+  stylesheets = [],
+}) {
+  const entryChunks = new Map();
+  const cssAssets = new Map();
+  for (const item of output) {
+    if (item.type === "chunk" && item.isEntry) {
+      entryChunks.set(item.name, item);
+    } else if (item.type === "asset" && item.fileName?.endsWith(".css")) {
+      // A stylesheet input emits a CSS asset whose name is "<input>.css".
+      const base = (item.name ?? "").replace(/\.css$/, "");
+      if (base) cssAssets.set(base, item.fileName);
+    }
+  }
+
+  const chunkAsset = (name) => {
+    const chunk = entryChunks.get(name);
+    if (!chunk) return null;
+    return {
+      file: chunk.fileName,
+      href: assetHref(chunk.fileName),
+      css: [...(chunk.viteMetadata?.importedCss ?? [])].map(assetHref),
+      imports: (chunk.imports ?? []).map(assetHref),
+    };
+  };
+
+  const routes = {};
+  for (const { id, name } of routeEntries) {
+    const asset = chunkAsset(name);
+    if (asset) routes[id] = asset;
+  }
+
+  const stylesheetAssets = {};
+  for (const { source, name } of stylesheets) {
+    const file = cssAssets.get(name);
+    if (file) stylesheetAssets[source] = { file, href: assetHref(file) };
+  }
+
+  const entryAsset = clientEntry ? chunkAsset(clientEntry.name) : null;
+
+  return {
+    version: 1,
+    assetPrefix: ASSET_PREFIX,
+    entry: entryAsset ? { id: clientEntry.id, ...entryAsset } : null,
+    routes,
+    stylesheets: stylesheetAssets,
+  };
+}
+
+// The render-time view of the client build: it resolves the dev/prod URL for a
+// stylesheet, the browser entry, and a page's hydration module. The Document
+// helpers (Stylesheet/ClientEntry) read it through the render context.
+//
+//   dev:  modules and styles are served from source by Vite, so URLs are the
+//         in-app source path ("/src/app.css", "/src/routes/index.tsx").
+//   prod: URLs come from the Phase 14 manifest's hashed assets.
+export function createClientContext({ dev = false, manifest = null } = {}) {
+  return {
+    dev,
+    stylesheetHref(source) {
+      if (dev) return appPath(source);
+      return manifest?.stylesheets?.[normalizeAppPath(source)]?.href ?? appPath(source);
+    },
+    entryHref(source) {
+      if (dev) return appPath(source);
+      // Resolve by the declared source, like stylesheets: a <ClientEntry src>
+      // that doesn't match the built entry resolves to nothing in prod, matching
+      // dev (where the wrong source 404s) instead of silently using the entry.
+      const entry = manifest?.entry;
+      return entry && normalizeAppPath(source) === entry.id ? entry.href : null;
+    },
+    pageModuleHref(routeId) {
+      if (!routeId) return null;
+      if (dev) return appPath(routeId);
+      return manifest?.routes?.[routeId]?.href ?? null;
+    },
+    page: null,
+  };
+}

package/src/build.js

@@ -0,0 +1,216 @@
+import { existsSync } from "node:fs";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import react from "@vitejs/plugin-react";
+import { build as viteBuild } from "vite";
+import { createClientManifest } from "./assets.js";
+import {
+  CLIENT_ENTRY_FILES,
+  DOCUMENT_FILES,
+  ERROR_PAGE_FILES,
+  STYLESHEET_FILES,
+  findFirst,
+} from "./conventions.js";
+import { scanRoutes } from "./routes.js";
+import { serverOnlyBuildGuard } from "./server-only.js";
+import { loadTailwindPlugin } from "./tailwind.js";
+
+// Where the production build is written. `smaoog start` reads only from here.
+export const OUTPUT_DIR = ".smaoog";
+
+// Virtual module id for a route's browser entry. It re-exports only the page
+// component (see routeClientPlugin), so the route's HTTP handlers — and anything
+// they import — tree-shake out of the client bundle.
+const VIRTUAL_ROUTE_PREFIX = "\0smaoog-route-client:";
+
+// Fresh plugin instances per build — Vite plugins are stateful for one build, so
+// the SSR and client passes must not share them.
+async function appPlugins(root) {
+  return [react(), ...(await loadTailwindPlugin(root))];
+}
+
+// Exposes a route's default export (the page) as a standalone client entry,
+// dropping its server-side handlers via tree-shaking.
+function routeClientPlugin() {
+  return {
+    name: "smaoog:route-client",
+    resolveId(id) {
+      if (id.startsWith(VIRTUAL_ROUTE_PREFIX)) return id;
+    },
+    load(id) {
+      if (id.startsWith(VIRTUAL_ROUTE_PREFIX)) {
+        const file = id.slice(VIRTUAL_ROUTE_PREFIX.length);
+        return `export { default } from ${JSON.stringify(file)};`;
+      }
+    },
+  };
+}
+
+// Flatten viteBuild's result into a single Rollup output array.
+function collectOutput(result) {
+  const outputs = Array.isArray(result) ? result : [result];
+  return outputs.flatMap((out) => out.output ?? []);
+}
+
+// Build the production output under `.smaoog`:
+//   .smaoog/server/*.js     built route/document/error-page modules (ESM)
+//   .smaoog/client/assets/  hashed browser assets owned by smaoog
+//   .smaoog/manifest.json   route table + server module map + client manifest
+//
+// Two Vite passes share one toolchain (no throwaway compiler path):
+//   1. SSR pass  — route/document/error-page modules the Node server renders.
+//   2. client pass — per-page browser entries, the client entry, and stylesheets,
+//      emitted under the reserved asset prefix with the manifest hydration/nav
+//      will consume.
+export async function buildApp({ root = process.cwd(), logLevel = "warn" } = {}) {
+  const routesDir = join(root, "src", "routes");
+  const routes = existsSync(routesDir) ? await scanRoutes(routesDir) : [];
+
+  const outDir = join(root, OUTPUT_DIR);
+  const serverDir = join(outDir, "server");
+  const clientDir = join(outDir, "client");
+
+  // Start clean so a stale module/asset from a previous build can never be
+  // served or referenced by the new manifest.
+  await rm(outDir, { recursive: true, force: true });
+
+  // Map a unique, filesystem-safe entry name to each source module. Names avoid
+  // route bracket syntax and stay parallel between the SSR and client passes.
+  const serverInput = {};
+  const manifestRoutes = routes.map((route, i) => {
+    serverInput[`route${i}`] = route.file;
+    return {
+      id: route.id,
+      pattern: route.pattern,
+      segments: route.segments,
+      module: `route${i}.js`,
+    };
+  });
+
+  const documentRel = findFirst(root, DOCUMENT_FILES);
+  if (documentRel) serverInput.document = join(root, documentRel);
+  const notFoundRel = findFirst(root, ERROR_PAGE_FILES.notFound);
+  if (notFoundRel) serverInput._404 = join(root, notFoundRel);
+  const errorRel = findFirst(root, ERROR_PAGE_FILES.error);
+  if (errorRel) serverInput._500 = join(root, errorRel);
+
+  // --- SSR pass ---------------------------------------------------------------
+  let ssrOutput = [];
+  if (Object.keys(serverInput).length > 0) {
+    const result = await viteBuild({
+      root,
+      configFile: false,
+      logLevel,
+      plugins: await appPlugins(root),
+      resolve: { dedupe: ["react", "react-dom"] },
+      // Keep node_modules deps out of the SSR bundle; they resolve at runtime.
+      ssr: { external: ["smaoog", "react", "react-dom"] },
+      build: {
+        ssr: true,
+        outDir: serverDir,
+        emptyOutDir: true,
+        // SSR output is JS modules only; public assets are served from public/
+        // at runtime, not copied into the server bundle dir.
+        copyPublicDir: false,
+        rollupOptions: {
+          input: serverInput,
+          output: {
+            format: "es",
+            entryFileNames: "[name].js",
+            chunkFileNames: "chunks/[name]-[hash].js",
+          },
+        },
+      },
+    });
+    ssrOutput = collectOutput(result);
+  } else {
+    await mkdir(serverDir, { recursive: true });
+  }
+
+  // A route gets a browser entry only if it has a page (default export). The
+  // SSR chunk's export list tells us this without executing the module — so a
+  // route's server-only imports never run at build time.
+  const ssrExports = new Map();
+  for (const item of ssrOutput) {
+    if (item.type === "chunk") ssrExports.set(item.name, item.exports ?? []);
+  }
+  const isPageRoute = (i) => (ssrExports.get(`route${i}`) ?? []).includes("default");
+
+  // --- client pass ------------------------------------------------------------
+  const clientInput = {};
+  const routeEntries = [];
+  routes.forEach((route, i) => {
+    if (!isPageRoute(i)) return;
+    const name = `route${i}`;
+    clientInput[name] = VIRTUAL_ROUTE_PREFIX + route.file;
+    routeEntries.push({ id: route.id, name });
+  });
+
+  const clientEntryRel = findFirst(root, CLIENT_ENTRY_FILES);
+  const clientEntry = clientEntryRel
+    ? { id: clientEntryRel, name: "client-entry" }
+    : null;
+  if (clientEntry) clientInput[clientEntry.name] = join(root, clientEntryRel);
+
+  const stylesheets = STYLESHEET_FILES.filter((rel) => existsSync(join(root, rel))).map(
+    (rel, i) => {
+      const name = `style${i}`;
+      clientInput[name] = join(root, rel);
+      return { source: rel, name };
+    },
+  );
+
+  let client;
+  if (Object.keys(clientInput).length > 0) {
+    const result = await viteBuild({
+      root,
+      configFile: false,
+      logLevel,
+      // Assets are served from the reserved prefix, so their public URLs (and
+      // any CSS url() rewrites) resolve there.
+      base: "/_smaoog/",
+      // The server-only guard runs first so it can reject (or tree-shake) a
+      // `.server.*` import before other plugins resolve it.
+      plugins: [serverOnlyBuildGuard({ routesDir }), routeClientPlugin(), ...(await appPlugins(root))],
+      resolve: { dedupe: ["react", "react-dom"] },
+      build: {
+        outDir: clientDir,
+        emptyOutDir: true,
+        copyPublicDir: false,
+        rollupOptions: {
+          input: clientInput,
+          // Keep each entry's exports (the re-exported page component) so the
+          // page survives tree-shaking; the default (`false`) would drop it.
+          preserveEntrySignatures: "allow-extension",
+          output: {
+            entryFileNames: "assets/[name]-[hash].js",
+            chunkFileNames: "assets/[name]-[hash].js",
+            assetFileNames: "assets/[name]-[hash][extname]",
+          },
+        },
+      },
+    });
+    client = createClientManifest({
+      output: collectOutput(result),
+      routeEntries,
+      clientEntry,
+      stylesheets,
+    });
+  } else {
+    await mkdir(clientDir, { recursive: true });
+    client = createClientManifest({});
+  }
+
+  const manifest = {
+    routes: manifestRoutes,
+    document: documentRel ? "document.js" : null,
+    errorPages: {
+      notFound: notFoundRel ? "_404.js" : null,
+      error: errorRel ? "_500.js" : null,
+    },
+    client,
+  };
+  await writeFile(join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+
+  return { outDir, serverDir, clientDir, manifest };
+}

package/src/cli.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { buildApp } from "./build.js";
+import { startDev } from "./dev.js";
+import { startProd } from "./start.js";
+
+// Run `smaoog dev`: start the dev server (Vite + node:http) and report the URL.
+async function dev() {
+  const port = Number(process.env.PORT) || 3000;
+  const { server } = await startDev({ root: process.cwd(), port });
+  const { port: actualPort } = server.address();
+  console.log(`smaoog dev listening on http://localhost:${actualPort}`);
+}
+
+// Run `smaoog build`: produce the SSR-only production output under .smaoog.
+async function build() {
+  const { outDir } = await buildApp({ root: process.cwd() });
+  console.log(`smaoog build complete: ${outDir}`);
+}
+
+// Run `smaoog start`: serve the built SSR app from .smaoog.
+async function start() {
+  const port = Number(process.env.PORT) || 3000;
+  const { server } = await startProd({ root: process.cwd(), port });
+  const { port: actualPort } = server.address();
+  console.log(`smaoog start listening on http://localhost:${actualPort}`);
+}
+
+async function main() {
+  const command = process.argv[2];
+
+  switch (command) {
+    case "dev":
+      await dev();
+      break;
+    case "build":
+      await build();
+      break;
+    case "start":
+      await start();
+      break;
+    default:
+      if (command) {
+        console.error(`Unknown command: ${command}`);
+      } else {
+        console.error(
+          "Usage: smaoog <command>\n\nCommands:\n  dev      Start the dev server\n  build    Build the production SSR output\n  start    Serve the built production app",
+        );
+      }
+      process.exitCode = 1;
+  }
+}
+
+main().catch((err) => {
+  // Surface a clean message (e.g. "run `smaoog build` first") instead of a
+  // Node stack trace for expected failures.
+  console.error(err?.message ?? err);
+  process.exitCode = 1;
+});

package/src/client/index.d.ts

@@ -0,0 +1,6 @@
+export interface HydrateOptions {
+  load?: (url: string) => Promise<{ default?: unknown }>;
+}
+
+export function hydrate(options?: HydrateOptions): Promise<unknown>;
+

package/src/client/index.js

@@ -0,0 +1,12 @@
+import { hydrate } from "./runtime.js";
+
+// `import "smaoog/client"` (from the app's client entry) boots hydration in the
+// browser. Guarded so importing the entry without a DOM — SSR, tests, or a
+// build that never reaches a browser — is a safe no-op. The catch keeps a failed
+// dynamic import or a corrupted bootstrap (e.g. a stale deploy) from surfacing as
+// an unhandled rejection.
+if (typeof document !== "undefined") {
+  hydrate().catch((err) => console.error("[smaoog] hydration failed", err));
+}
+
+export { hydrate };