@tschk/moonshine-framework 0.4.1 → 0.4.4

package/README.md

@@ -19,6 +19,12 @@ const route = defineRoute({
 const config = defineConfig({ runtime: "bun", mode: "auto" });
 ```
 
+Native manifests support Bun, Node, Cloudflare, and Vercel Node functions. Route
+runtimes match their adapter, with Vercel native functions using `node`. Vercel
+Edge remains unsupported. Cloudflare and Vercel reject request context, islands,
+and cache/revalidation options; see the [Cloudflare](../deploy-cloudflare/README.md)
+and [Vercel](../deploy-vercel/README.md) adapter limits.
+
 Exports include:
 
 - `RouteDefinition`, `RenderMode`, `RuntimeTarget`
@@ -28,3 +34,33 @@ Exports include:
 
 See [docs/MANIFEST.md](../../docs/MANIFEST.md) and
 [DESIGN.md](../../DESIGN.md).
+
+Server request context is opt-in with `requestContext: true` and requires matching
+Bun or Node deployment adapters and route runtimes. Import `runWithRequest` and
+`getRequest` from `@tschk/moonshine-framework/request`; this server-only subpath
+uses AsyncLocalStorage. The root export contains no request-context runtime.
+`RequestScope` is available as a root type for pipeline integration.
+
+Native page and layout server modules may export `metadata`, typed as `Metadata`:
+
+```ts
+import type { Metadata } from "@tschk/moonshine-framework";
+
+export const metadata: Metadata = ({ data }) => ({
+  title: (data as { title: string }).title,
+  description: "A server-rendered page",
+  lang: "en",
+});
+```
+
+`DocumentMetadata` supports only `title`, `description`, and `lang`. Outer layouts,
+inner layouts, then the page override individual fields. Undefined inherits; null
+clears an inherited field (including the default `lang="en"`). Values are escaped
+in the document head and HTML language attribute. Callbacks must be synchronous,
+pure functions of the render context, which contains already-loaded route data;
+Promises and invalid field types are rejected. No arbitrary head HTML is accepted.
+
+Metadata applies to native SSR, static output, and SPA document shells without
+mounting the SPA server component. API responses skip it. This adds no client head
+manager: subsequent client-side navigation must update document metadata explicitly.
+Legacy React rendering does not consume this export.

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@tschk/moonshine-framework",
-  "version": "0.4.1",
+  "version": "0.4.4",
   "license": "ISC",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./request": "./src/request.ts"
   },
+  "files": [
+    "src"
+  ],
   "scripts": {
     "format": "bunx prettier --check .",
     "lint": "bunx oxlint .",
@@ -15,7 +19,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@tschk/moonshine": "^0.4.1"
+    "@tschk/moonshine": "^0.4.4"
   },
   "devDependencies": {
     "@types/bun": "1.3.14",

package/src/build.ts

@@ -0,0 +1,136 @@
+import { copyFile, mkdir, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import type { DeploymentAdapter } from "./adapter";
+import type { MoonshineManifest } from "./manifest";
+
+export function resolveManifestFiles(
+  manifest: MoonshineManifest,
+  projectRoot: string,
+): MoonshineManifest {
+  return {
+    ...manifest,
+    routes: manifest.routes.map((route) => ({
+      ...route,
+      file: isAbsolute(route.file)
+        ? route.file
+        : resolve(projectRoot, route.file),
+      ...(route.dataFile && {
+        dataFile: isAbsolute(route.dataFile)
+          ? route.dataFile
+          : resolve(projectRoot, route.dataFile),
+      }),
+      ...(route.clientFile && {
+        clientFile: isAbsolute(route.clientFile)
+          ? route.clientFile
+          : resolve(projectRoot, route.clientFile),
+      }),
+      ...(route.layouts && {
+        layouts: route.layouts.map((layout) =>
+          isAbsolute(layout) ? layout : resolve(projectRoot, layout),
+        ),
+      }),
+      ...(route.middleware && {
+        middleware: route.middleware.map((middleware) =>
+          isAbsolute(middleware)
+            ? middleware
+            : resolve(projectRoot, middleware),
+        ),
+      }),
+      ...(route.errorBoundary && {
+        errorBoundary: isAbsolute(route.errorBoundary)
+          ? route.errorBoundary
+          : resolve(projectRoot, route.errorBoundary),
+      }),
+    })),
+  };
+}
+
+function within(root: string, file: string): boolean {
+  const path = relative(root, file);
+  return path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path);
+}
+
+export async function copyAsset(
+  asset: MoonshineManifest["assets"][number],
+  outDir: string,
+): Promise<string> {
+  const source = isAbsolute(asset.file)
+    ? asset.file
+    : resolve(outDir, asset.file);
+  const publicRoot = resolve(outDir, "public");
+  const [realSource, realPublic] = await Promise.all([
+    realpath(source),
+    realpath(publicRoot).catch(() => publicRoot),
+  ]);
+  if (within(publicRoot, source) && !within(realPublic, realSource))
+    throw new Error(`Public asset escapes its directory: ${asset.file}`);
+  if (within(realPublic, realSource)) {
+    const stored = within(publicRoot, source)
+      ? relative(publicRoot, source)
+      : relative(realPublic, realSource);
+    return `public/${stored.split(sep).join("/")}`;
+  }
+  const target = resolve(
+    outDir,
+    (asset.path ?? asset.file).replace(/^\/+/, ""),
+  );
+  await mkdir(dirname(target), { recursive: true });
+  if (source !== target) {
+    await copyFile(source, target);
+  }
+  return (asset.path ?? asset.file).replace(/^\/+/, "");
+}
+
+export async function copyAssets(
+  assets: MoonshineManifest["assets"],
+  outDir: string,
+): Promise<void> {
+  await Promise.all(assets.map((asset) => copyAsset(asset, outDir)));
+}
+
+export function validateRuntime(
+  adapter: DeploymentAdapter,
+  manifest: MoonshineManifest,
+): void {
+  const nativeRuntime = adapter.name === "vercel" ? "node" : adapter.name;
+  if (
+    manifest.renderer === "native" &&
+    (!["bun", "node", "cloudflare", "vercel"].includes(adapter.name) ||
+      manifest.routes.some((route) => route.runtime !== nativeRuntime))
+  ) {
+    throw new Error(
+      "Native renderer requires matching Bun, Node or Cloudflare runtimes; Vercel native functions require Node",
+    );
+  }
+  if (
+    manifest.requestContext &&
+    (!["bun", "node"].includes(adapter.name) ||
+      manifest.routes.some((route) => route.runtime !== adapter.name))
+  ) {
+    throw new Error(
+      "Request context supports only matching Bun or Node deployment adapters/runtimes",
+    );
+  }
+  const errors: string[] = [];
+  for (const route of manifest.routes) {
+    if (!adapter.runtimes.includes(route.runtime)) {
+      errors.push(
+        `${adapter.name} adapter does not support route "${route.path}" with runtime "${route.runtime}"; supported runtimes: ${adapter.runtimes.join(", ")}`,
+      );
+    }
+  }
+  if (errors.length) throw new Error(errors.join("\n"));
+}
+
+export function validateCapabilities(
+  adapter: DeploymentAdapter,
+  manifest: MoonshineManifest,
+): void {
+  for (const capability of manifest.capabilities) {
+    if (!adapter.capabilities.includes(capability)) {
+      throw new Error(
+        `${adapter.name} adapter does not support capability "${capability}"; supported capabilities: ${adapter.capabilities.join(", ")}`,
+      );
+    }
+  }
+}

package/src/config.ts

@@ -3,6 +3,7 @@ import type { RenderMode, RuntimeTarget } from "./routes";
 export type MoonshineConfig = {
   mode?: RenderMode;
   runtime?: RuntimeTarget;
+  requestContext?: boolean;
 };
 
 export function defineConfig<T extends MoonshineConfig>(config: T): T {

package/src/index.ts

@@ -4,3 +4,4 @@ export * from "./manifest";
 export * from "./renderer";
 export * from "./routes";
 export * from "./serialize";
+export * from "./build";

package/src/manifest.ts

@@ -1,4 +1,5 @@
 import type { RenderMode, RouteDefinition, RuntimeTarget } from "./routes";
+import type { RendererName } from "./renderer";
 
 export const MANIFEST_VERSION = 1 as const;
 
@@ -14,6 +15,7 @@ export type RouteArtifact = RouteDefinition & {
   decision: string;
   serverEntry?: string;
   clientEntries: string[];
+  clientStyles?: string[];
   staticOutput?: string;
   cache?: { control?: string; revalidate?: number };
   headers?: Record<string, string>;
@@ -22,6 +24,8 @@ export type RouteArtifact = RouteDefinition & {
 export type MoonshineManifest = {
   version: typeof MANIFEST_VERSION;
   frameworkVersion: string;
+  renderer?: RendererName;
+  requestContext?: boolean;
   routes: RouteArtifact[];
   assets: Array<{ path: string; file: string; integrity?: string }>;
   entries: { server?: string; client?: string };

package/src/renderer.ts

@@ -1,5 +1,7 @@
 import type { RouteArtifact } from "./manifest";
 
+export type RendererName = "react" | "solid" | "crepus" | "native";
+
 export type RenderContext = {
   request: Request;
   route: RouteArtifact;
@@ -8,8 +10,22 @@ export type RenderContext = {
   signal: AbortSignal;
 };
 
+/** Native document fields. Undefined inherits; null removes an inherited field. */
+export type DocumentMetadata = {
+  title?: string | null;
+  description?: string | null;
+  lang?: string | null;
+};
+
+/** Synchronous server-module metadata, evaluated with loaded route data. */
+export type Metadata =
+  DocumentMetadata | ((context: RenderContext) => DocumentMetadata);
+
 export type Renderer = {
   name: string;
   render(context: RenderContext): Promise<Response>;
   prerender(context: RenderContext): Promise<string>;
 };
+
+/** Runs the entire request pipeline in an optional server context. */
+export type RequestScope = <T>(request: Request, fn: () => T) => T;

package/src/request.ts

@@ -0,0 +1,12 @@
+/** Opt-in server request context; deliberately absent from the root barrel. */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { RequestScope } from "./renderer";
+
+const requests = new AsyncLocalStorage<Request>();
+
+export const runWithRequest: RequestScope = (request, fn) =>
+  requests.run(request, fn);
+
+export function getRequest(): Request | undefined {
+  return requests.getStore();
+}

package/src/routes.ts

@@ -5,6 +5,8 @@ export type RouteDefinition = {
   id: string;
   path: string;
   file: string;
+  /** Explicit browser-only page entry for native SPA rendering. */
+  clientFile?: string;
   mode?: RenderMode;
   runtime?: RuntimeTarget;
   layouts?: string[];

package/test/adapter.test.ts

@@ -1,26 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { defineRoute } from "../src/adapter";
-import type { RouteDefinition } from "../src/routes";
-
-describe("defineRoute", () => {
-  test("returns the exact route definition provided", () => {
-    const route: RouteDefinition = {
-      id: "test-route",
-      path: "/test",
-      file: "test.tsx",
-      mode: "ssr",
-      runtime: "bun",
-    };
-
-    const result = defineRoute(route);
-
-    expect(result).toBe(route);
-    expect(result).toEqual({
-      id: "test-route",
-      path: "/test",
-      file: "test.tsx",
-      mode: "ssr",
-      runtime: "bun",
-    });
-  });
-});

package/test/config.test.ts

@@ -1,45 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { defineConfig, type MoonshineConfig } from "../src/config";
-
-describe("defineConfig", () => {
-  test("returns the exact same object reference", () => {
-    const config: MoonshineConfig = {};
-    const result = defineConfig(config);
-    expect(result).toBe(config);
-  });
-
-  test("handles empty configuration", () => {
-    const result = defineConfig({});
-    expect(result).toEqual({});
-  });
-
-  test("handles configuration with mode", () => {
-    const result = defineConfig({ mode: "island" });
-    expect(result).toEqual({ mode: "island" });
-  });
-
-  test("handles configuration with runtime", () => {
-    const result = defineConfig({ runtime: "bun" });
-    expect(result).toEqual({ runtime: "bun" });
-  });
-
-  test("handles full configuration", () => {
-    const config = {
-      mode: "ssr" as const,
-      runtime: "cloudflare" as const,
-    };
-    const result = defineConfig(config);
-    expect(result).toEqual(config);
-  });
-
-  test("preserves additional properties (type safety with generic T)", () => {
-    const config = {
-      mode: "spa" as const,
-      customPlugin: true,
-    };
-    const result = defineConfig(config);
-    expect(result).toEqual(config);
-    // TypeScript check: result.customPlugin should exist
-    expect(result.customPlugin).toBe(true);
-  });
-});

package/test/contracts.test.ts

@@ -1,13 +0,0 @@
-import { expect, test } from "bun:test";
-import { defineConfig, defineRoute, MANIFEST_VERSION } from "../src";
-
-test("contracts preserve exact input and version one", () => {
-  const route = defineRoute({
-    id: "home",
-    path: "/",
-    file: "src/routes/index.tsx",
-  });
-  expect(route.path).toBe("/");
-  expect(defineConfig({ mode: "auto" }).mode).toBe("auto");
-  expect(MANIFEST_VERSION).toBe(1);
-});

package/test/serialize.test.ts

@@ -1,69 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { serializeData } from "../src/serialize";
-
-// The single HTML-safe JSON serializer: the server data payload and the island
-// props script are the same XSS-prevention primitive, so they share this one
-// implementation rather than drifting apart in two packages.
-describe("serializeData", () => {
-  test("escapes <, >, &, U+2028, and U+2029", () => {
-    const out = serializeData({
-      html: "<script>alert('&

')</script>",
-    });
-    expect(out).not.toContain("<");
-    expect(out).not.toContain(">");
-    expect(out).not.toContain("&");
-    expect(out).not.toContain("
");
-    expect(out).not.toContain("
");
-    expect(out).toContain("\\u003c");
-    expect(out).toContain("\\u003e");
-    expect(out).toContain("\\u0026");
-    expect(out).toContain("\\u2028");
-    expect(out).toContain("\\u2029");
-  });
-
-  test("omits undefined properties instead of nulling them", () => {
-    expect(serializeData({ a: 1, b: undefined })).toBe('{"a":1}');
-    expect(serializeData([1, undefined])).toBe("[1,null]");
-  });
-
-  test("rejects symbol-keyed properties rather than dropping them", () => {
-    expect(() => serializeData({ [Symbol("k")]: 1 })).toThrow(/symbol/);
-  });
-
-  test("serializes NaN and Infinity as null", () => {
-    expect(serializeData({ a: NaN, b: Infinity, c: -Infinity })).toBe(
-      '{"a":null,"b":null,"c":null}',
-    );
-  });
-
-  test("allows shared references and rejects only true cycles", () => {
-    const shared = { id: 1 };
-    expect(serializeData({ a: shared, b: shared })).toBe(
-      '{"a":{"id":1},"b":{"id":1}}',
-    );
-    expect(serializeData([shared, shared])).toBe('[{"id":1},{"id":1}]');
-
-    const cyclic: Record<string, unknown> = {};
-    cyclic.self = cyclic;
-    expect(() => serializeData(cyclic)).toThrow(/cyclic/);
-
-    const arr: unknown[] = [];
-    arr.push(arr);
-    expect(() => serializeData(arr)).toThrow(/cyclic/);
-  });
-
-  test("rejects functions, symbols, and bigints", () => {
-    expect(() => serializeData({ f: () => 1 })).toThrow(/function/);
-    expect(() => serializeData({ s: Symbol("x") })).toThrow(/symbol/);
-    expect(() => serializeData({ n: 1n })).toThrow(/bigint/);
-  });
-
-  test("omits properties with throwing getters", () => {
-    const obj = {
-      get thrower() {
-        throw new Error("Getter threw!");
-      },
-    };
-    expect(serializeData(obj)).toBe("{}");
-  });
-});

package/tsconfig.json

@@ -1,4 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "include": ["src/**/*", "test/**/*"]
-}