smaoog 0.0.1

package/src/server-only.js

@@ -0,0 +1,122 @@
+import { sep } from "node:path";
+
+// The server-only file convention: any module whose name ends in `.server.<ext>`
+// is forbidden from the browser bundle. Route handlers and the SSR build may
+// import these freely; the client may not.
+//
+// Matches a resolved file path or an import specifier with an extension, and
+// tolerates a trailing query (Vite appends ?v=, ?import, etc.).
+export const SERVER_MODULE_RE = /\.server\.[cm]?[jt]sx?(\?|$)/;
+
+// Removes whole `import ... from "….server.*"` statements (and bare
+// `import "….server.*"`) from source. The clause character class excludes quotes
+// so a match can't span across a previous import's specifier. Used in dev, where
+// there is no bundler to tree-shake a route's handler-only server imports out of
+// the browser module.
+const SERVER_IMPORT_RE =
+  /import\s+(?:[\w*${},\s]+\s+from\s+)?["'][^"']*\.server(?:\.[cm]?[jt]sx?)?["']\s*;?/g;
+
+export function stripServerImports(code) {
+  return code.replace(SERVER_IMPORT_RE, "");
+}
+
+// Browser route modules are hydrated through their default export only (the page
+// component); a route's `meta` and HTTP handlers are read on the server. React
+// Fast Refresh, however, only keeps a module hot when *every* export is a
+// component — a stray `export const meta`/`export function GET` makes it bail to a
+// full page reload. So in the browser transform we demote every non-default
+// export to a plain local: the page keeps Fast Refresh, and the now-unused
+// handlers/meta are harmless (and tree-shake away in the production build).
+//
+// Operates on raw TS/TSX (this runs before the JSX/TS transform), so it is a
+// keyword rewrite, not an AST pass: drop the `export` keyword from a non-default
+// declaration, and drop `export { … }` / `export * …` statements whole. Uses
+// [ \t] rather than \s so line breaks survive and source positions stay stable.
+const EXPORT_DECL_RE =
+  /\bexport[ \t]+(?!default\b)(?=(?:async[ \t]+)?(?:function|class|const|let|var)\b)/g;
+const EXPORT_LIST_RE =
+  /\bexport[ \t]*(?:\{[^}]*\}|\*(?:[ \t]+as[ \t]+[\w$]+)?)[ \t]*(?:from[ \t]*["'][^"']*["'])?[ \t]*;?/g;
+
+export function stripNonDefaultExports(code) {
+  return code.replace(EXPORT_DECL_RE, "").replace(EXPORT_LIST_RE, "");
+}
+
+// Whether `file` lives under the routes directory — i.e. it is a route module,
+// whose server imports belong to handlers (server-only) and are expected to be
+// dropped from the client rather than rejected. A query suffix is ignored.
+function isRouteModule(file, routesDir) {
+  if (!file) return false;
+  const path = file.split("?")[0];
+  return path.startsWith(routesDir.endsWith(sep) ? routesDir : routesDir + sep);
+}
+
+function leakError(target, importer) {
+  const who = importer ? ` (imported by "${importer.split("?")[0]}")` : "";
+  return new Error(
+    `[smaoog] server-only module "${target.split("?")[0]}" must not reach the client bundle${who}. ` +
+      `Move browser-safe code out of .server.* files; import them only from route handlers.`,
+  );
+}
+
+// Build-pass guard for the client bundle. Route-handler `.server.*` imports are
+// marked side-effect-free so an unused one tree-shakes away; a `.server.*`
+// imported by any non-route browser module (client entry, a component) is a hard
+// error; and if one still survives into a client chunk (a page actually used it),
+// generateBundle rejects the build.
+export function serverOnlyBuildGuard({ routesDir }) {
+  return {
+    name: "smaoog:server-only-build",
+    // Resolve before Vite's own resolver so the side-effect-free tag actually
+    // takes hold (a later resolver would fix the module's default side effects).
+    enforce: "pre",
+    async resolveId(source, importer, options) {
+      if (options?.ssr || !source.includes(".server")) return null;
+      const resolved = await this.resolve(source, importer, { skipSelf: true, ...options });
+      if (!resolved || !SERVER_MODULE_RE.test(resolved.id)) return null;
+      if (isRouteModule(importer, routesDir)) {
+        // Handler-only import: let it tree-shake out (generateBundle catches it
+        // if a page actually pulled it into the client).
+        return { ...resolved, moduleSideEffects: false };
+      }
+      throw leakError(resolved.id, importer);
+    },
+    generateBundle(_options, bundle) {
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type !== "chunk") continue;
+        for (const moduleId of Object.keys(chunk.modules ?? {})) {
+          if (SERVER_MODULE_RE.test(moduleId)) throw leakError(moduleId, "the client bundle");
+        }
+      }
+    },
+  };
+}
+
+// Dev guard + Fast Refresh shim for route modules. There is no bundler in dev,
+// so a route module's browser transform strips its handler-only `.server.*`
+// imports (the handlers never run in the browser) and demotes its non-default
+// exports to locals so React Fast Refresh keeps the page hot. Any other
+// browser-context `.server.*` import — from the client entry or a component — is
+// a hard error.
+export function serverOnlyDevPlugin({ routesDir }) {
+  return {
+    name: "smaoog:server-only-dev",
+    enforce: "pre",
+    transform(code, id, options) {
+      // Browser transform of a route module only. SSR keeps the handlers, meta,
+      // and server imports it actually runs.
+      if (options?.ssr || !isRouteModule(id, routesDir)) return null;
+      let out = code;
+      // Drop handler-only `.server.*` imports (no bundler to tree-shake them).
+      if (out.includes(".server")) out = stripServerImports(out);
+      // Demote non-default exports so React Fast Refresh keeps the page hot.
+      out = stripNonDefaultExports(out);
+      return out === code ? null : { code: out, map: null };
+    },
+    async resolveId(source, importer, options) {
+      if (options?.ssr || !source.includes(".server")) return null;
+      const resolved = await this.resolve(source, importer, { skipSelf: true, ...options });
+      if (!resolved || !SERVER_MODULE_RE.test(resolved.id)) return null;
+      throw leakError(resolved.id, importer);
+    },
+  };
+}

package/src/server.js

@@ -0,0 +1,42 @@
+import { createServer as createHttpServer } from "node:http";
+
+// Reserved framework prefix. User routes can never be served from here;
+// it is owned by smaoog internals (client assets, nav payloads, manifests).
+export const RESERVED_PREFIX = "/_smaoog/";
+
+const DEFAULT_PORT = 3000;
+
+// Build the node:http server around a request handler, without binding it to a
+// port. Tests use this so they can listen on an ephemeral port. The handler is
+// the framework's request handler (see router.js); the server itself stays a
+// thin transport with no routing knowledge.
+export function createServer(requestHandler) {
+  return createHttpServer(requestHandler);
+}
+
+// Bind an already-created server to a port. Resolves once it is listening, and
+// rejects if binding fails (e.g. the port is already in use) so callers can
+// recover instead of hanging. Split out from startServer so the dev path can
+// create the server first (to share it with Vite's HMR WebSocket) and listen
+// only after the request handler is attached.
+export function listen(server, port = DEFAULT_PORT) {
+  return new Promise((resolve, reject) => {
+    function onError(err) {
+      server.removeListener("listening", onListening);
+      reject(err);
+    }
+    function onListening() {
+      server.removeListener("error", onError);
+      resolve(server);
+    }
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port);
+  });
+}
+
+// Create and start the server in one step. Resolves once it is listening, and
+// rejects if binding fails.
+export function startServer({ port = DEFAULT_PORT, requestHandler } = {}) {
+  return listen(createServer(requestHandler), port);
+}

package/src/start.js

@@ -0,0 +1,60 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { OUTPUT_DIR } from "./build.js";
+import { createRequestHandler } from "./router.js";
+import { startServer } from "./server.js";
+
+// A module loader backed by the built output. Modules are imported from
+// `.smaoog/server` via the manifest, so the running server never touches `src`.
+function createProdLoader({ serverDir, manifest }) {
+  const importBuilt = (file) => import(pathToFileURL(join(serverDir, file)).href);
+  return {
+    route: (route) => importBuilt(route.module),
+    document: () => (manifest.document ? importBuilt(manifest.document) : Promise.resolve(null)),
+    errorPage: (kind) => {
+      const file = manifest.errorPages[kind];
+      return file ? importBuilt(file) : Promise.resolve(null);
+    },
+  };
+}
+
+// Load the build manifest, or throw a clear error if the app hasn't been built.
+async function loadManifest(root) {
+  const outDir = join(root, OUTPUT_DIR);
+  const manifestPath = join(outDir, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error(
+      `No build found at ${OUTPUT_DIR}/. Run \`smaoog build\` before \`smaoog start\`.`,
+    );
+  }
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  return { manifest, serverDir: join(outDir, "server") };
+}
+
+// Build the production request handler from the manifest, without binding a
+// port. Useful for tests that drive an ephemeral port.
+export async function createProdRequestHandler({ root = process.cwd() } = {}) {
+  const { manifest, serverDir } = await loadManifest(root);
+  return createRequestHandler({
+    routes: manifest.routes,
+    loader: createProdLoader({ serverDir, manifest }),
+    publicRoot: join(root, "public"),
+    assetsRoot: join(root, OUTPUT_DIR, "client", "assets"),
+    clientAssets: manifest.client,
+  });
+}
+
+// Orchestrate `smaoog start`: serve the built SSR app from `.smaoog`. No Vite,
+// no `src` — production output only.
+export async function startProd({ root = process.cwd(), port = 3000 } = {}) {
+  const requestHandler = await createProdRequestHandler({ root });
+  const server = await startServer({ port, requestHandler });
+  return {
+    server,
+    async close() {
+      await new Promise((resolve) => server.close(resolve));
+    },
+  };
+}

package/src/tailwind.js

@@ -0,0 +1,20 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+// Optionally pull in the app's Tailwind Vite plugin. It is a starter default,
+// not a framework dependency: if `@tailwindcss/vite` isn't installed in the app,
+// dev and build proceed without it. Resolving from the app's package.json (not
+// smaoog's) keeps Tailwind an app-owned choice, matching how the scaffold ships
+// it as a dependency of the generated app rather than of the framework.
+export async function loadTailwindPlugin(root) {
+  const requireFromApp = createRequire(join(root, "package.json"));
+  let resolved;
+  try {
+    resolved = requireFromApp.resolve("@tailwindcss/vite");
+  } catch {
+    return [];
+  }
+  const mod = await import(resolved);
+  const plugin = mod.default;
+  return typeof plugin === "function" ? [plugin()] : [];
+}

package/src/vite.js

@@ -0,0 +1,69 @@
+import { join } from "node:path";
+import { createServer as createViteDevServer } from "vite";
+import react from "@vitejs/plugin-react";
+import { serverOnlyDevPlugin } from "./server-only.js";
+import { loadTailwindPlugin } from "./tailwind.js";
+
+// Create smaoog's internal Vite dev server. This is the module boundary:
+// route modules, documents, and React pages will be loaded through it in
+// later phases. It is never exposed as a user-facing command.
+//
+// - middlewareMode keeps Vite from owning an HTTP server; smaoog's node:http
+//   server stays in control.
+// - appType "custom" disables Vite's built-in HTML/SPA handling.
+// - configFile false means the user never needs a vite.config.
+// - plugins [react()] gives the automatic JSX runtime (no `import React`)
+//   and Fast Refresh, whose preamble (see ReactRefresh in index.js) pulls
+//   Vite's HMR client into the browser.
+// - HMR rides on the shared `server` when one is passed (the `smaoog dev`
+//   path), so Fast Refresh connects over the page's own origin/port — no
+//   second port and proxy-friendly. Without a server (tests, one-off module
+//   loads) HMR stays off; otherwise every Vite instance would bind the default
+//   HMR port (24678) and collide.
+export async function createViteServer({ root = process.cwd(), logLevel, server } = {}) {
+  return createViteDevServer({
+    root,
+    configFile: false,
+    appType: "custom",
+    logLevel,
+    // react() for the JSX runtime + Fast Refresh; the server-only guard keeps
+    // .server.* modules out of browser requests (stripping a route's
+    // handler-only imports, rejecting any other browser import of one); Tailwind
+    // (when the app installs it) processes `@import "tailwindcss"` so dev matches
+    // the build, instead of the browser fetching a literal /src/tailwindcss 404.
+    plugins: [
+      react(),
+      serverOnlyDevPlugin({ routesDir: join(root, "src", "routes") }),
+      ...(await loadTailwindPlugin(root)),
+    ],
+    // The app owns React; smaoog also depends on it. Dedupe so a single React
+    // instance is used — duplicate copies break SSR/hydration later.
+    resolve: {
+      dedupe: ["react", "react-dom"],
+    },
+    server: {
+      middlewareMode: true,
+      // Share smaoog's HTTP server for the HMR WebSocket when one is provided;
+      // the Fast Refresh client then connects to the same host/port as the page.
+      // With no server, disable HMR entirely (`hmr: false` + `ws: false`) so a
+      // bare Vite instance never binds the standalone HMR port (24678).
+      ...(server ? { hmr: { server } } : { hmr: false, ws: false }),
+    },
+  });
+}
+
+// Load a module through Vite's SSR pipeline, transforming TS/TSX/JSX into
+// runnable ESM. `id` is a path relative to the Vite root, e.g. "/index.tsx".
+export function loadModule(vite, id) {
+  return vite.ssrLoadModule(id);
+}
+
+// Drop a previously loaded module from Vite's graph so the next loadModule
+// re-reads it from disk. Returns whether a cached module was found.
+export async function invalidateModule(vite, id) {
+  const mod = await vite.moduleGraph.getModuleByUrl(id, true);
+  if (mod) {
+    vite.moduleGraph.invalidateModule(mod);
+  }
+  return Boolean(mod);
+}