@c9up/aurora 0.1.3

package/src/server/serveAssets.ts

@@ -0,0 +1,135 @@
+/**
+ * `serveAssets` — generic static-file handler exposed by aurora so an
+ * app can mount the runtime + the pages dist with a couple of routes:
+ *
+ *   router.get('/_assets/aurora/*', serveAssets({ root: auroraDistPath }))
+ *   router.get('/_assets/pages/*',  serveAssets({ root: pagesPath }))
+ *
+ * The handler is framework-agnostic: it reads `ctx.request.param('*')`
+ * and writes to `ctx.response`. Any context that satisfies
+ * `AssetsHttpContext` (Ream, AdonisJS, anything duck-typed) works.
+ */
+
+import { readFile, realpath } from "node:fs/promises";
+import { extname, join, resolve as resolvePath, sep } from "node:path";
+
+const CONTENT_TYPES: Record<string, string> = {
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".map": "application/json; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+};
+
+export interface AssetsRequest {
+	/**
+	 * Read the wildcard `*` segment of the matched route. Most routers
+	 * (Ream, AdonisJS, fastify with params) expose this as
+	 * `params['*']` — the duck-typed helper below accepts either
+	 * convention.
+	 */
+	param(name: string): unknown;
+}
+export interface AssetsResponse {
+	status(code: number): AssetsResponse;
+	header(name: string, value: string): AssetsResponse;
+	send(body: string | Buffer): void;
+}
+export interface AssetsHttpContext {
+	request: AssetsRequest;
+	response: AssetsResponse;
+}
+
+export interface ServeAssetsOptions {
+	/**
+	 * Absolute filesystem root the handler is allowed to serve from.
+	 * Requests resolving outside this root return 403.
+	 */
+	root: string;
+	/**
+	 * `Cache-Control` value to emit. Defaults to a dev-friendly
+	 * 60-second TTL. Production deployments should hash the asset
+	 * name and switch to `public, max-age=31536000, immutable`.
+	 */
+	cacheControl?: string;
+}
+
+export function serveAssets(
+	options: ServeAssetsOptions,
+): (ctx: AssetsHttpContext) => Promise<void> {
+	const root = options.root;
+	const cacheControl = options.cacheControl ?? "public, max-age=60";
+	// Canonicalize the root ONCE at handler creation. The realpath check
+	// below compares against this canonical form so a symlinked root
+	// (e.g. `/var/www/current → /var/www/release-42`) still resolves
+	// requests correctly. `realpath` failure at construction means the
+	// configured root doesn't exist yet — we fall back to the lexical
+	// resolve so the first request emits a clean 404 instead of a boot
+	// crash. The realpath re-check at request time handles that case.
+	let canonicalRoot: string | undefined;
+	realpath(root).then(
+		(p) => {
+			canonicalRoot = p;
+		},
+		() => {
+			/* root not yet on disk — request-time realpath will surface it */
+		},
+	);
+
+	return async (ctx) => {
+		const rest = ctx.request.param("*");
+		if (typeof rest !== "string" || rest.length === 0) {
+			ctx.response.status(400).send("missing asset path");
+			return;
+		}
+		// First gate: lexical containment check. `resolve()` collapses
+		// `../` segments; we assert the resolved path still starts with
+		// `root + sep`. This blocks the "../../../etc/passwd" class of
+		// requests before we ever touch the filesystem.
+		const absolute = resolvePath(join(root, rest));
+		if (!absolute.startsWith(root + sep) && absolute !== root) {
+			ctx.response.status(403).send("forbidden");
+			return;
+		}
+
+		// Second gate: dereference any symlinks under the root and
+		// re-check containment against the canonical root. Without this
+		// step a symlink planted at `<root>/legit → /etc/secrets` would
+		// pass the lexical check above and be served. We re-canonicalize
+		// the root each request when the constructor-time realpath
+		// hadn't resolved yet (root mounted after boot).
+		let canonicalAbsolute: string;
+		let canonicalRootNow: string;
+		try {
+			canonicalRootNow = canonicalRoot ?? (await realpath(root));
+			canonicalAbsolute = await realpath(absolute);
+		} catch {
+			// realpath fails if the target doesn't exist — emit a normal
+			// 404 here so symlink-escape probes can't be distinguished
+			// from genuine misses via response timing or status.
+			ctx.response.status(404).send("asset not found");
+			return;
+		}
+		if (
+			!canonicalAbsolute.startsWith(canonicalRootNow + sep) &&
+			canonicalAbsolute !== canonicalRootNow
+		) {
+			ctx.response.status(403).send("forbidden");
+			return;
+		}
+
+		let body: Buffer;
+		try {
+			body = await readFile(canonicalAbsolute);
+		} catch {
+			ctx.response.status(404).send("asset not found");
+			return;
+		}
+
+		const type =
+			CONTENT_TYPES[extname(canonicalAbsolute)] ?? "application/octet-stream";
+		ctx.response.header("content-type", type);
+		ctx.response.header("cache-control", cacheControl);
+		ctx.response.send(body);
+	};
+}

package/src/services/main.ts

@@ -0,0 +1,40 @@
+/**
+ * Default `AuroraManager` singleton — Adonis-style:
+ *
+ *   import aurora from '@c9up/aurora/services/main'
+ *
+ *   await aurora.render(ctx, 'ProjectPage', { project, tasks })
+ *
+ * Populated either by `AuroraProvider.boot()` (when the app uses
+ * `() => import('@c9up/aurora/provider')`) or by the app itself via
+ * `setAurora(myManager)`.
+ */
+
+import type { AuroraManager } from "../AuroraManager.js";
+
+let instance: AuroraManager | undefined;
+
+/** @internal Bind the singleton (called by AuroraProvider or by the app). */
+export function setAurora(value: AuroraManager): void {
+	instance = value;
+}
+
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getAurora(): AuroraManager | undefined {
+	return instance;
+}
+
+const aurora: AuroraManager = new Proxy({} as AuroraManager, {
+	get(_target, prop) {
+		if (!instance) {
+			throw new Error(
+				"[aurora] AuroraManager singleton accessed before AuroraProvider.boot() ran " +
+					"or `setAurora(myManager)` was called. Wire one of them first.",
+			);
+		}
+		const value = Reflect.get(instance, prop, instance);
+		return typeof value === "function" ? value.bind(instance) : value;
+	},
+});
+
+export default aurora;

package/src/ssr.ts

@@ -0,0 +1,179 @@
+/**
+ * Server-side rendering — produces an HTML string from a `TemplateResult`
+ * without ever touching the DOM.
+ *
+ * Reads each slot's value eagerly (signals get a one-shot snapshot,
+ * functions are invoked, nested TemplateResults recurse). Event handlers
+ * are dropped server-side; hydration re-binds them once the markup
+ * lands in the browser.
+ */
+
+import { isSignal } from "./reactive.js";
+import { isTemplateResult, type TemplateResult } from "./types.js";
+
+const VOID_ELEMENTS = new Set([
+	"area",
+	"base",
+	"br",
+	"col",
+	"embed",
+	"hr",
+	"img",
+	"input",
+	"keygen",
+	"link",
+	"meta",
+	"source",
+	"track",
+	"wbr",
+]);
+
+/**
+ * Stringify a TemplateResult into HTML. Returns the markup ready to be
+ * shipped over the wire — no surrounding `<html>`/`<head>`/`<body>`
+ * unless the template includes them.
+ *
+ * The function walks the `strings` array directly; it does NOT depend
+ * on the DOM-side template cache, so it works in any JS runtime (Node,
+ * Cloudflare Workers, Bun, Deno).
+ */
+export function renderToString(result: TemplateResult): string {
+	return stringifyTemplateResult(result);
+}
+
+function stringifyTemplateResult(result: TemplateResult): string {
+	const { strings, values } = result;
+	let out = "";
+	// When a segment ends with a directive (` @click="`, ` ?disabled="`,
+	// ` .value="`), we drop the directive prefix from that segment, skip
+	// the matching value, and consume the closing `"` from the next
+	// segment. This three-step coordination is why the loop holds a
+	// `pendingClosingQuote` flag.
+	let pendingClosingQuote = false;
+	for (let i = 0; i < strings.length; i++) {
+		let segment = strings[i];
+		if (pendingClosingQuote) {
+			segment = segment.replace(/^"/, "");
+			pendingClosingQuote = false;
+		}
+		const directiveMatch = segment.match(/\s([@?.][\w-]+)="$/);
+		const skipValue = directiveMatch !== null;
+		if (directiveMatch) {
+			segment = segment.slice(0, segment.length - directiveMatch[0].length);
+			pendingClosingQuote = true;
+		}
+		out += segment;
+		if (i < values.length && !skipValue) {
+			const value = values[i];
+			const inAttr = isInsideAttribute(out);
+			if (!inAttr && isReactiveStructuredSlot(value)) {
+				// Reactive text slot whose value is a nested template /
+				// array — wrap the rendered content in boundary markers so
+				// hydration can locate the exact node range and SWAP it when
+				// the signal changes client-side. Without these markers a
+				// nested-template slot hydrates once and then goes stale
+				// (no way to find where the subtree starts/ends). Scalar
+				// reactive slots (`${signal}` → text) are NOT wrapped: their
+				// hydration updates the text node in place, no range needed.
+				out += `<!--${SLOT_START}-->`;
+				out += stringifyValue(value, false);
+				out += `<!--${SLOT_END}-->`;
+			} else {
+				out += stringifyValue(value, inAttr);
+			}
+		}
+	}
+	return out;
+}
+
+/** Boundary-marker comment payloads (kept in sync with hydrate.ts). */
+const SLOT_START = "$";
+const SLOT_END = "/$";
+
+/**
+ * True when `value` is a reactive expression (signal / function) whose
+ * current evaluation is a structured node payload (a nested
+ * TemplateResult, or an array). These are the slots that can SWAP their
+ * subtree on a client-side change and therefore need boundary markers
+ * for hydration to find the range. A reactive slot resolving to a
+ * scalar (string / number) is updated in place and needs no markers.
+ */
+function isReactiveStructuredSlot(value: unknown): boolean {
+	if (!isSignal(value) && typeof value !== "function") return false;
+	let evaluated: unknown;
+	try {
+		evaluated = isSignal(value)
+			? (value as () => unknown)()
+			: (value as () => unknown)();
+	} catch {
+		return false;
+	}
+	return isTemplateResult(evaluated) || Array.isArray(evaluated);
+}
+
+/**
+ * Returns true if the position at the end of `htmlSoFar` lives inside
+ * the value region of an HTML tag (between `<` and `>`). The check
+ * walks backwards from the end, which is the smallest hint we need to
+ * decide between text-region and attribute-region escaping.
+ */
+function isInsideAttribute(htmlSoFar: string): boolean {
+	for (let i = htmlSoFar.length - 1; i >= 0; i--) {
+		const c = htmlSoFar.charCodeAt(i);
+		if (c === 60 /* '<' */) return true;
+		if (c === 62 /* '>' */) return false;
+	}
+	return false;
+}
+
+function stringifyValue(value: unknown, inAttribute: boolean): string {
+	if (value === null || value === undefined || value === false) return "";
+	if (value === true) return inAttribute ? "" : "true";
+	if (isSignal(value)) return stringifyValue(value(), inAttribute);
+	if (typeof value === "function") {
+		// In attribute position: directive handlers (`@click`, `?disabled`,
+		// `.prop`) have already been stripped by `stripDirectiveBefore`.
+		// A function reaching this point is a reactive-expression text
+		// slot (`${() => ...}`), which we evaluate eagerly server-side.
+		try {
+			return stringifyValue((value as () => unknown)(), inAttribute);
+		} catch {
+			return "";
+		}
+	}
+	if (Array.isArray(value)) {
+		let out = "";
+		for (const item of value) out += stringifyValue(item, inAttribute);
+		return out;
+	}
+	if (isTemplateResult(value)) return stringifyTemplateResult(value);
+	// Plain value — escape HTML entities (text) or attribute special
+	// characters (attribute value).
+	return inAttribute ? escapeAttr(String(value)) : escapeText(String(value));
+}
+
+function escapeText(s: string): string {
+	return s
+		.replaceAll("&", "&amp;")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;");
+}
+
+function escapeAttr(s: string): string {
+	// Escape BOTH quote styles: the engine doesn't force double-quoted
+	// attributes (the classifier only tracks `<`/`>`), so a template author
+	// writing `id='${x}'` must still be safe — without escaping `'` a value
+	// like `' onmouseover='alert(1)` would break out of a single-quoted
+	// attribute. `>` isn't strictly required inside a quoted value but is
+	// escaped to stay safe under stray scanners that hunt tag boundaries
+	// before resolving the quote context.
+	return s
+		.replaceAll("&", "&amp;")
+		.replaceAll('"', "&quot;")
+		.replaceAll("'", "&#39;")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;");
+}
+
+// VOID_ELEMENTS exported for downstream tooling (hydration heuristics).
+export { VOID_ELEMENTS };

package/src/types.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared types for aurora templates.
+ *
+ * A `TemplateResult` is what `html\`...\`` returns. It carries the raw
+ * pieces (strings, values) and a stable reference to the parsed
+ * `Template` (memoised by `strings`). Templates are framework-internal —
+ * apps only ever see `TemplateResult`.
+ */
+
+/**
+ * A lifecycle/effect callback that runs and OPTIONALLY returns a cleanup
+ * function — exactly React's `EffectCallback = () => void | (() => void)`.
+ *
+ * The `void` member of the return union is load-bearing: it is what makes a
+ * plain `() => {}` (whose return type is `void`) assignable here. Replacing it
+ * with `(() => void) | undefined` makes every void-returning callback a type
+ * error (a `() => void` is NOT assignable to `() => (() => void) | undefined`).
+ * So `noConfusingVoidType` is suppressed once, at this single definition,
+ * instead of being worked around at ~15 call sites with broken types.
+ */
+// biome-ignore lint/suspicious/noConfusingVoidType: `void` is required so plain void-returning callbacks stay assignable (React EffectCallback pattern; dropping it breaks ~10 call sites)
+export type EffectCallback = () => void | (() => void);
+
+/** Slot descriptor — where a `${value}` lives inside a parsed template. */
+export type SlotKind = "text" | "attr" | "event" | "boolean-attr" | "prop";
+
+/**
+ * Path to the binding point inside the cloned template. Each step is a
+ * child index. We never walk by query selectors because attribute and text
+ * placements would need synthetic markers in markup an app provided.
+ */
+export type NodePath = readonly number[];
+
+export interface TextSlot {
+	kind: "text";
+	path: NodePath;
+}
+export interface AttrSlot {
+	kind: "attr";
+	path: NodePath;
+	name: string;
+	/**
+	 * When the attribute interpolates more than one `${...}` slot, every
+	 * slot shares the same `name` and the static segments are stored under
+	 * `staticParts`. The render step joins them back together each tick.
+	 */
+	staticParts?: readonly string[];
+	staticPartIndex?: number;
+}
+export interface EventSlot {
+	kind: "event";
+	path: NodePath;
+	event: string;
+}
+export interface BooleanAttrSlot {
+	kind: "boolean-attr";
+	path: NodePath;
+	name: string;
+}
+export interface PropSlot {
+	kind: "prop";
+	path: NodePath;
+	name: string;
+}
+
+export type Slot = TextSlot | AttrSlot | EventSlot | BooleanAttrSlot | PropSlot;
+
+/** Compiled artefact — produced once per unique `strings` array. */
+export interface Template {
+	/**
+	 * A `<template>` element whose `content` fragment is cloned on every
+	 * render. Cloning is much cheaper than re-parsing the HTML string.
+	 */
+	readonly element: HTMLTemplateElement;
+	/** Slot descriptors in source order (same order as the `${...}` values). */
+	readonly slots: readonly Slot[];
+}
+
+/** Tagged-template return value — what `html\`\`` produces. */
+export interface TemplateResult {
+	readonly strings: TemplateStringsArray;
+	readonly values: readonly unknown[];
+	readonly [TEMPLATE_RESULT_BRAND]: true;
+}
+
+export const TEMPLATE_RESULT_BRAND: unique symbol = Symbol.for(
+	"aurora:template-result",
+);
+
+export function isTemplateResult(value: unknown): value is TemplateResult {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		(value as { [TEMPLATE_RESULT_BRAND]?: boolean })[TEMPLATE_RESULT_BRAND] ===
+			true
+	);
+}