bosia 1.2.3 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "1.2.3",
+	"version": "1.2.4",
 	"type": "module",
 	"engines": {
 		"bun": ">=1.4"

package/src/core/build.ts

@@ -405,7 +405,7 @@ if (!devBuild) {
 		await prerenderStaticRoutes(manifest, target);
 	} catch (err) {
 		if (!(err instanceof PrerenderEntriesError)) throw err;
-		console.error(`❌ ${err.message}`);
+		console.error(err.message);
 		process.exit(1);
 	}
 }

package/src/core/html.ts

@@ -700,30 +700,3 @@ export function compressBytes(
 	}
 	return new Response(bytes, { status, headers });
 }
-
-// ─── Static File Detection ────────────────────────────────
-
-const STATIC_EXTS = new Set([
-	".ico",
-	".png",
-	".jpg",
-	".jpeg",
-	".gif",
-	".webp",
-	".svg",
-	".css",
-	".js",
-	".woff",
-	".woff2",
-	".ttf",
-	".xml",
-	".txt",
-	".json",
-	".webmanifest",
-]);
-
-export function isStaticPath(path: string): boolean {
-	if (path.startsWith("/dist/") || path.startsWith("/__bosia/")) return true;
-	const dot = path.lastIndexOf(".");
-	return dot !== -1 && STATIC_EXTS.has(path.slice(dot));
-}

package/src/core/prerender.ts

@@ -8,6 +8,7 @@ import { BOSIA_NODE_PATH, OUT_DIR } from "./paths.ts";
 import { currentBase } from "./appBase.ts";
 import { prerenderSkipReason, wantsPrerender } from "./scanner.ts";
 import { isDynamic, segmentName, segmentRank } from "./matcher.ts";
+import { HEALTH_PATH, isFrameworkPath, isStaticPath } from "./staticPath.ts";
 
 /** Acquire an OS-assigned ephemeral port. Tiny TOCTOU race window; acceptable for build-time use. */
 export function getEphemeralPort(): Promise<number> {
@@ -55,8 +56,10 @@ const PRERENDER_CONCURRENCY = Number(process.env.PRERENDER_CONCURRENCY) || 6;
 
 // ─── Prerendering ─────────────────────────────────────────
 
-interface PrerenderTarget {
+export interface PrerenderTarget {
 	path: string;
+	/** Route pattern the path came from (`/[slug]`); equals `path` for a static route. */
+	route: string;
 	kind: "page" | "api";
 	/** Page targets only; APIs always write a single `.json` file regardless of slash mode. */
 	trailingSlash: TrailingSlash;
@@ -72,7 +75,7 @@ export function substituteParams(pattern: string, entry: Record<string, string>)
 	// Per segment, so an inserted value is never re-read as a placeholder.
 	return pattern
 		.split("/")
-		.map((seg) => {
+		.map((seg, i, segs) => {
 			const rank = segmentRank(seg);
 			if (!rank) return seg;
 			const name = segmentName(seg);
@@ -81,23 +84,28 @@ export function substituteParams(pattern: string, entry: Record<string, string>)
 			// A catch-all may end in one "/" ("guide/intro/"); the out path drops it.
 			const value = rank === 2 ? String(entry[name]).replace(/\/$/, "") : String(entry[name]);
 			const bad = (why: string): never => {
-				throw new Error(`entries() value "${entry[name]}" for ${seg} is unsafe — ${why}`);
+				throw new Error(
+					`entries() value ${JSON.stringify(String(entry[name]))} for ${seg} is unsafe — ${why}`,
+				);
 			};
-			// Check what the server will see: `%2e%2e` and `%2F` decode to `..` and `/`.
-			let decoded = value;
-			try {
-				decoded = decodeURIComponent(value);
-			} catch {
-				bad("invalid percent-encoding");
-			}
-			// `..` and `\` let a build write outside the output tree.
-			if (/\\|\.\./.test(decoded)) bad("path traversal characters are not allowed");
-			// The fetched URL would differ from the file written.
-			if (/[?#]/.test(decoded)) bad("`?` and `#` are not allowed");
-			if (rank === 1 && decoded.includes("/")) bad("`/` is only allowed in a [...rest] param");
-			// An empty or "." part would land on the parent route's file.
-			if (decoded.split("/").some((part) => part === "" || part === "."))
-				bad("empty or `.` parts are not allowed");
+			// Strict on purpose (decided 2026-10-14): ASCII unreserved URL characters only, so the
+			// fetched URL, the file written and a static host's lookup all agree, with nothing to
+			// percent-encode or decode. `50%-off`, `café`, `what%3F` fail by design: slugify them.
+			// No part may end in `.`: the URL parser folds `.`/`..`, and Windows drops trailing
+			// dots (`v1.` → `v1`), so the page would land on another route's file. No part may
+			// start with `.` either: static hosts hide dotfiles (`.env`).
+			const parts = rank === 2 ? value.split("/") : [value];
+			if (!parts.every((part) => /^(?!\.)[A-Za-z0-9._~-]*[A-Za-z0-9_~-]$/.test(part)))
+				bad(
+					`use only ASCII letters, digits, - _ . ~${rank === 2 ? " and /" : ""}, with no empty parts or leading/trailing \`.\``,
+				);
+			// Windows device names: writing `nul.html` hits the device, not a file.
+			if (parts.some((part) => /^(con|prn|aux|nul|com\d|lpt\d)(\.|$)/i.test(part)))
+				bad("Windows device names (con, nul, com1, …) are not allowed");
+			// Only the URL's last part names a file: `index` is written as `<parent>/index.html`,
+			// which serves the parent URL; `post.html` as `post.html.html`, never served for it.
+			if (i === segs.length - 1 && /^index$|\.(html|json)$/i.test(parts.at(-1)!))
+				bad("the last part can't be `index` or end with .html or .json");
 			return value;
 		})
 		.join("/");
@@ -128,6 +136,11 @@ export function prerenderDataPath(routePath: string): string {
 	return routePath === "/" ? "/index.json" : `${routePath.replace(/\/$/, "")}.json`;
 }
 
+/** Where a page's data payload is written. */
+export function prerenderDataOutPath(routePath: string): string {
+	return `${OUT_DIR}/prerendered/__bosia/data${prerenderDataPath(routePath)}`;
+}
+
 /**
  * Output filename for a prerendered API route. Always emits a single `.json`
  * file at the route's path (no trailing-slash variants — static hosts serve
@@ -142,6 +155,37 @@ export class PrerenderEntriesError extends Error {
 	override name = "PrerenderEntriesError";
 }
 
+/**
+ * Throws when a dynamic route's path would save the wrong thing. Pure, so the invariant
+ * tests (test/prerender-invariants.test.ts) can sweep every value × slash mode × kind.
+ */
+export function checkPrerenderPaths(
+	paths: string[],
+	kind: "page" | "api",
+	ts: TrailingSlash,
+): void {
+	for (const p of paths) {
+		// `dist/` and `__bosia/` are the framework's folders in static/: `dist/client` is copied
+		// after the pages, so on macOS/Windows a page folder `DIST/` would swallow the bundle
+		// (served as `DIST/client/…`, a 404 on case-sensitive hosts). A page `/dist` also fails:
+		// `/dist/` is answered as a static file, not 308'd to it.
+		// Lowercased for case-insensitive disks; a page's `/` form is tested too, so `/dist` fails.
+		const lower = p.toLowerCase();
+		if (isFrameworkPath(kind === "page" ? `${lower}/` : lower))
+			throw new Error(`entries() gives ${p}; dist and __bosia are the framework's folders`);
+		// The server answers `/_health`, and for pages any static-file ending like `.png`, itself,
+		// so the saved file would hold its reply, not the route. Checked on the slash-less form:
+		// `/logo.png` 404s before the 308 to `/logo.png/`, and the `/` form adds only the prefixes
+		// rejected above (the invariant test checks both forms).
+		if (p === HEALTH_PATH || (kind === "page" && isStaticPath(p)))
+			throw new Error(`entries() gives ${p}, a URL the server answers itself`);
+		// generateStaticSite copies prerendered/ over static/, where the 404 probe saves
+		// 404.html. A static src/routes/404 page may replace it on purpose; a slug may not.
+		if (kind === "page" && ts === "never" && lower === "/404")
+			throw new Error("an entries() value would overwrite 404.html, the not-found page");
+	}
+}
+
 /** Dynamic route → import module, call entries(), expand to concrete targets. */
 async function expandDynamicRoute(
 	pattern: string,
@@ -154,11 +198,11 @@ async function expandDynamicRoute(
 		if (typeof mod.entries !== "function")
 			throw new Error("prerender = true on a dynamic route needs an entries() export");
 		const entryList: Record<string, string>[] = await mod.entries();
-		return entryList.map((entry) => ({
-			path: substituteParams(pattern, entry),
-			kind,
-			trailingSlash: ts,
-		}));
+		// A repeated value (a tag on two posts) is written once. Only within this route:
+		// the same URL from two routes is a clash, reported by findPrerenderClash.
+		const paths = [...new Set(entryList.map((entry) => substituteParams(pattern, entry)))];
+		checkPrerenderPaths(paths, kind, ts);
+		return paths.map((path) => ({ path, route: pattern, kind, trailingSlash: ts }));
 	} catch (err) {
 		// Fail the build: skipping the route would silently drop every page it lists.
 		const why = err instanceof Error ? err.message : String(err);
@@ -166,7 +210,7 @@ async function expandDynamicRoute(
 	}
 }
 
-async function detectPrerenderRoutes(manifest: RouteManifest): Promise<PrerenderTarget[]> {
+export async function detectPrerenderRoutes(manifest: RouteManifest): Promise<PrerenderTarget[]> {
 	const pageTasks = manifest.pages.map(async (route): Promise<PrerenderTarget[]> => {
 		if (!route.pageServer) return [];
 		const filePath = join("src", "routes", route.pageServer);
@@ -179,7 +223,7 @@ async function detectPrerenderRoutes(manifest: RouteManifest): Promise<Prerender
 		}
 		const ts = route.trailingSlash;
 		if (isDynamic(route.pattern)) return expandDynamicRoute(route.pattern, filePath, "page", ts);
-		return [{ path: route.pattern, kind: "page", trailingSlash: ts }];
+		return [{ path: route.pattern, route: route.pattern, kind: "page", trailingSlash: ts }];
 	});
 
 	const apiTasks = manifest.apis.map(async (route): Promise<PrerenderTarget[]> => {
@@ -188,14 +232,63 @@ async function detectPrerenderRoutes(manifest: RouteManifest): Promise<Prerender
 		if (!wantsPrerender(content)) return [];
 		if (isDynamic(route.pattern))
 			return expandDynamicRoute(route.pattern, filePath, "api", "never");
-		return [{ path: route.pattern, kind: "api", trailingSlash: "never" }];
+		return [{ path: route.pattern, route: route.pattern, kind: "api", trailingSlash: "never" }];
 	});
 
-	// Unbounded Promise.all over all routes; each task holds only small text reads
+	// Unbounded Promise.allSettled over all routes; each task holds only small text reads
 	// and route metadata, so RAM stays trivial. Chunk it if route counts ever hit
 	// tens of thousands (open file descriptors would be the first limit).
-	const results = await Promise.all([...pageTasks, ...apiTasks]);
-	return results.flat();
+	const results = await Promise.allSettled([...pageTasks, ...apiTasks]);
+	// List every broken entries() route in one error, not just the first.
+	const failed = results.flatMap((r) => (r.status === "rejected" ? [r.reason] : []));
+	const other = failed.find((e) => !(e instanceof PrerenderEntriesError));
+	if (other) throw other;
+	// One `❌` per route; a multi-line message (a ZodError) stays under its own mark.
+	if (failed.length)
+		throw new PrerenderEntriesError(failed.map((e) => `❌ ${e.message}`).join("\n"), {
+			cause: failed,
+		});
+	const targets = results.flatMap((r) => (r.status === "fulfilled" ? r.value : []));
+	const clash = findPrerenderClash(targets);
+	if (clash.length) throw new PrerenderEntriesError(clash.join("\n"));
+	return targets;
+}
+
+/**
+ * Files two targets would both write. macOS/Windows ignore case, so `About` and `about`
+ * (or folders `A/` and `a/`) merge; a file and a folder can't share a path either.
+ * Every folder level counts, and so do data payloads.
+ */
+export function findPrerenderClash(targets: PrerenderTarget[]): string[] {
+	const owners = new Map<string, { path: string; who: string; file: boolean }>();
+	const clashes: string[] = [];
+	for (const t of targets) {
+		// Name the route a slug came from, so the message says which file to fix.
+		const who = t.route === t.path ? t.path : `${t.path} (from ${t.route})`;
+		let clash = "";
+		const files =
+			t.kind === "api"
+				? [prerenderApiOutPath(t.path)]
+				: [prerenderOutPath(t.path, t.trailingSlash), prerenderDataOutPath(t.path)];
+		// One ❌ per URL, but every file is still recorded so a later target can't slip past it.
+		for (const out of files) {
+			const segs = out.split("/");
+			for (let i = 1; i <= segs.length; i++) {
+				const path = segs.slice(0, i).join("/");
+				const file = i === segs.length;
+				const key = path.toLowerCase();
+				const prev = owners.get(key);
+				if (!prev) owners.set(key, { path, who, file });
+				// Only two folders with the exact same name may share a path.
+				else if (!clash && (prev.path !== path || file || prev.file)) {
+					const what = file && prev.file ? "file" : "path";
+					clash = `❌ Prerender: ${prev.who} and ${who} write the same ${what} (${path})`;
+				}
+			}
+		}
+		if (clash) clashes.push(clash);
+	}
+	return clashes;
 }
 
 export async function prerenderStaticRoutes(
@@ -322,7 +415,7 @@ export async function prerenderStaticRoutes(
 				});
 				if (dataRes.ok) {
 					const dataJson = await dataRes.text();
-					const dataOutPath = `${OUT_DIR}/prerendered/__bosia/data${dataPath}`;
+					const dataOutPath = prerenderDataOutPath(routePath);
 					mkdirSync(dataOutPath.substring(0, dataOutPath.lastIndexOf("/")), {
 						recursive: true,
 					});

package/src/core/routeTypes.ts

@@ -3,6 +3,7 @@ import { join } from "path";
 import type { RouteManifest } from "./types.ts";
 import { segmentName, segmentRank } from "./matcher.ts";
 import { toPosix } from "./paths.ts";
+import { PARAM_NAME } from "./scanner.ts";
 
 // ─── Route Types Generator ────────────────────────────────
 // Generates .bosia/types/src/routes/**/$types.d.ts for each
@@ -70,10 +71,11 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 		const srcBase = `${up}src/routes/${segments.length ? segments.join("/") + "/" : ""}`;
 
 		const params = paramsForDir(dir);
+		// Quoted fallback: a cached manifest (BOSIA_SKIP_ROUTE_SCAN) may predate the name check.
 		const paramsType =
 			params.length === 0
 				? `{}`
-				: `{ ${params.map((p) => `${/^[A-Za-z_$][\w$]*$/.test(p) ? p : JSON.stringify(p)}: string`).join("; ")} }`;
+				: `{ ${params.map((p) => `${PARAM_NAME.test(p) ? p : JSON.stringify(p)}: string`).join("; ")} }`;
 
 		const lines: string[] = ["// AUTO-GENERATED by bosia — do not edit\n"];
 		lines.push(`import type { LoadEvent, MetadataEvent, RequestEvent, Metadata } from 'bosia';`);

package/src/core/scanner.ts

@@ -278,23 +278,15 @@ function checkParams<T extends { pattern: string }>(routes: T[], fileOf: (r: T)
 		for (const [i, seg] of segs.entries()) {
 			const rank = segmentRank(seg);
 			if (!rank) {
-				// `[...]`, `[.x]`, `[id].json`, `post-[slug]`, `[[lang]]` would match only their literal text.
-				if (/^\[(\.\.\.)?[^[\]/]*\]$/.test(seg))
-					fail(`${seg} needs a param name that doesn't start with a dot, like [slug] or [...rest]`);
+				// `[...]`, `[.x]` would match only their literal text.
+				if (/^\[[^[\]/]*\]$/.test(seg)) fail(BAD_NAME(seg));
+				// `[id].json`, `post-[slug]`, `[[lang]]`.
 				if (/[[\]]/.test(seg)) fail(`${seg} must be a whole segment like [slug] or [...rest]`);
 				continue;
 			}
 			const name = segmentName(seg);
 			if (rank === 2 && i !== segs.length - 1) fail(`${seg} must be the last part of the route`);
-			const dots = rank === 2 ? "..." : "";
-			if (name.includes("="))
-				fail(`${seg}: param matchers aren't supported, use [${dots}${name.split("=")[0]}]`);
-			if (name.endsWith("?"))
-				fail(`${seg}: optional params aren't supported, use [${dots}${name.slice(0, -1)}]`);
-			if (/^…|[.…]$/.test(name))
-				fail(`${seg}: did you mean [...${name.replace(/^…|[.…]+$/g, "")}]?`);
-			if (!PARAM_NAME.test(name))
-				fail(`${seg}: a param name uses letters, digits, _, $, - and inner dots only`);
+			if (!PARAM_NAME.test(name)) fail(BAD_NAME(seg));
 			// params is a plain object: assigning "__proto__" sets the prototype, not a key.
 			if (name === "__proto__") fail(`"__proto__" can't be a param name`);
 			if (names.has(name)) fail(`the param "${name}" is used twice`);
@@ -303,8 +295,12 @@ function checkParams<T extends { pattern: string }>(routes: T[], fileOf: (r: T)
 	}
 }
 
-// `[slüg]`, `[$id]`, `[my-path]`, `[file.name]`, `[1st]`; no spaces, quotes, `…` or edge dots.
-const PARAM_NAME = /^[\p{L}\p{N}_$-]+(\.[\p{L}\p{N}_$-]+)*$/u;
+// Strict on purpose (decided 2026-10-14): an ASCII TypeScript identifier, so `params.name`
+// always works: `[slug]`, `[x123]`, `[user_id]`, `[_id]`, `[$id]`. `[post-id]`, `[file.name]`,
+// `[slüg]` fail by design, with one message (no per-typo hints).
+export const PARAM_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const BAD_NAME = (seg: string) =>
+	`${seg}: a param name uses ASCII letters, digits, _ and $, and can't start with a digit (like [slug], [user_id] or [...rest])`;
 
 /** A route tree the build refuses (two files at one URL, or an invalid param).
  *  Callers print `message` and exit. */

package/src/core/server.ts

@@ -15,6 +15,7 @@ import { NO_FRAME_GUARD_HEADER, type Handle, type RequestEvent } from "./hooks.t
 import { HttpError, Redirect, ActionFailure, isHttpError, isRedirect } from "./errors.ts";
 import { CookieJar } from "./cookies.ts";
 import { safePath } from "./safePath.ts";
+import { HEALTH_PATH, isFrameworkPath, isStaticPath } from "./staticPath.ts";
 import { checkCsrf } from "./csrf.ts";
 import type { CsrfConfig } from "./csrf.ts";
 import { applyCorsVary, getCorsHeaders, handlePreflight } from "./cors.ts";
@@ -25,7 +26,6 @@ import {
 	compress,
 	compressBytes,
 	encodeForRequest,
-	isStaticPath,
 	distManifest,
 	PRECOMPRESSED,
 	type Encoded,
@@ -372,7 +372,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 	const method = request.method.toUpperCase();
 
 	// Health check endpoint — for load balancers and orchestrators
-	if (path === "/_health") {
+	if (path === HEALTH_PATH) {
 		if (shuttingDown) {
 			return Response.json({ status: "shutting_down" }, { status: 503 });
 		}
@@ -593,7 +593,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 	// by a user `+server.ts`, so serve them straight from the manifest before the
 	// API scan. A miss falls through to the normal path (which 404s). Keeps the
 	// api-before-static ordering intact for every user-facing path.
-	if (staticManifest && (path.startsWith("/dist/") || path.startsWith("/__bosia/"))) {
+	if (staticManifest && isFrameworkPath(path)) {
 		const hit = lookupStatic(staticManifest, path);
 		if (hit) return serveStatic(hit, request);
 	}
@@ -1144,7 +1144,7 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 	}
 
 	// Reject new non-health requests during shutdown
-	if (shuttingDown && url.pathname !== "/_health") {
+	if (shuttingDown && url.pathname !== HEALTH_PATH) {
 		return new Response("Service Unavailable", {
 			status: 503,
 			headers: { "Retry-After": "5" },
@@ -1154,7 +1154,7 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 	// Shed load above MAX_INFLIGHT. Checked before any work so the 503 is
 	// cheap. /_health stays available so the orchestrator can still tell the
 	// process is alive (and decide whether to restart or scale out).
-	if (inFlight >= MAX_INFLIGHT && url.pathname !== "/_health") {
+	if (inFlight >= MAX_INFLIGHT && url.pathname !== HEALTH_PATH) {
 		return new Response("Service Unavailable", {
 			status: 503,
 			headers: { "Retry-After": "1" },
@@ -1215,7 +1215,7 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 		const path = event.url.pathname;
 		let response: Response | null = null;
 		let staticTried = false;
-		if (!dataReq && staticManifest && (path.startsWith("/dist/") || path.startsWith("/__bosia/"))) {
+		if (!dataReq && staticManifest && isFrameworkPath(path)) {
 			response = await serveStaticFile(path, request);
 			staticTried = true;
 		}

package/src/core/staticPath.ts

@@ -0,0 +1,35 @@
+// URLs the server answers as static files, never as pages. No imports and no top-level
+// work: the build loads this before loadEnv(), so it must not touch env or the base path.
+
+const STATIC_EXTS = new Set([
+	".ico",
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".svg",
+	".css",
+	".js",
+	".woff",
+	".woff2",
+	".ttf",
+	".xml",
+	".txt",
+	".json",
+	".webmanifest",
+]);
+
+// The server answers these itself; prerender rejects entries() values that reach them.
+export const HEALTH_PATH = "/_health";
+
+// The framework's own folders: built assets and data/runtime endpoints.
+export function isFrameworkPath(path: string): boolean {
+	return path.startsWith("/dist/") || path.startsWith("/__bosia/");
+}
+
+export function isStaticPath(path: string): boolean {
+	if (isFrameworkPath(path)) return true;
+	const dot = path.lastIndexOf(".");
+	return dot !== -1 && STATIC_EXTS.has(path.slice(dot));
+}