@torpor/build 0.4.14 → 1.0.0

package/src/response/unprocessable.ts

@@ -1,4 +1,10 @@
 import response from "./response";
+import type { Jsonify } from "../types/Jsonify";
+import type TypedResponse from "./TypedResponse";
+
+type UnprocessableResponse<T extends object | string | undefined> = T extends object
+	? TypedResponse<Jsonify<T>>
+	: Response;
 
 /**
  * 422 Unprocessable Content
@@ -11,8 +17,14 @@ import response from "./response";
  * Clients that receive a 422 response should expect that repeating the request
  * without modification will fail with the same error.
  *
+ * An object body is typed: it becomes the page's `$props.form` (with its JSON
+ * form) after a form submit, so validation errors can be surfaced with their
+ * field types via `PageForm`.
+ *
  * See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/422
  */
-export default function unprocessable(body?: object | string): Response {
-	return response(422, body ?? "Unprocessable");
+export default function unprocessable<T extends object | string | undefined>(
+	body?: T,
+): UnprocessableResponse<T> {
+	return response(422, body ?? "Unprocessable") as UnprocessableResponse<T>;
 }

package/src/run/depCache.ts

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import {
+	existsSync,
+	readFileSync,
+	readdirSync,
+	realpathSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import type { PackageJson } from "../utils/torporPackages";
+
+/**
+ * Vite's dep-optimization cache (node_modules/.vite) keys off the lockfile
+ * and config, but not the content of workspace packages. When a workspace
+ * package is rebuilt while the cache holds prebundled copies of it, dev SSR
+ * keeps executing the stale modules -- producing bizarre errors (missing
+ * runtime identifiers, "$cache must be used in a getter", ...) that only a
+ * manual cache delete fixes.
+ *
+ * clearStaleDepCache runs at `tb --dev` startup: it fingerprints every
+ * workspace package the site depends on (path, size and mtime of each file)
+ * and, when the fingerprint differs from the previous run, deletes the cache
+ * so Vite re-optimizes from the rebuilt packages.
+ *
+ * Live rebuilds while the server is up are still not hot-invalidated (that
+ * needs a watcher feeding Vite's module graph); this closes the "restart and
+ * hope you remember the trick" gap.
+ */
+
+const STORE_NAME = ".torpor-dev-cache.json";
+
+/**
+ * Clears site/node_modules/.vite when workspace packages changed since the
+ * last dev run. Returns true when the cache was removed.
+ */
+export function clearStaleDepCache(siteRoot: string, log?: (message: string) => void): boolean {
+	try {
+		const workspaceRoot = findWorkspaceRoot(siteRoot);
+		if (!workspaceRoot) return false;
+
+		const cacheDir = path.join(siteRoot, "node_modules", ".vite");
+		const storePath = path.join(siteRoot, "node_modules", STORE_NAME);
+
+		const fingerprint = fingerprintWorkspacePackages(siteRoot, workspaceRoot);
+		if (fingerprint === undefined) return false;
+
+		const previous = readStore(storePath);
+
+		let cleared = false;
+		if (existsSync(cacheDir) && previous !== fingerprint) {
+			rmSync(cacheDir, { recursive: true, force: true });
+			cleared = true;
+			log?.("Workspace packages changed; clearing the Vite dep cache");
+		}
+		writeFileSync(storePath, JSON.stringify({ fingerprint }));
+
+		return cleared;
+	} catch (e) {
+		if (process.env.TORPOR_DEBUG_CACHE) throw e;
+		// Never break dev startup over cache bookkeeping
+		return false;
+	}
+}
+
+export function findWorkspaceRoot(from: string): string | undefined {
+	let dir = path.resolve(from);
+	while (true) {
+		// pnpm-style marker, or a root package.json declaring npm workspaces
+		if (existsSync(path.join(dir, "pnpm-workspace.yaml"))) {
+			return dir;
+		}
+		if (hasWorkspacesField(dir)) {
+			return dir;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) return undefined;
+		dir = parent;
+	}
+}
+
+function hasWorkspacesField(dir: string): boolean {
+	const packageJsonPath = path.join(dir, "package.json");
+	if (!existsSync(packageJsonPath)) return false;
+	try {
+		const pkg: PackageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+		return Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0;
+	} catch {
+		return false;
+	}
+}
+
+function readStore(storePath: string): string | undefined {
+	if (!existsSync(storePath)) return undefined;
+	try {
+		const store = JSON.parse(readFileSync(storePath, "utf8")) as { fingerprint?: string };
+		return store.fingerprint;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Resolves every site dependency that lives inside the workspace to its
+ * package folder. Shared with the other dev-startup checks (e.g. the stale
+ * .torp copy report), which need the same set of packages.
+ */
+export function workspaceDependencyDirs(siteRoot: string, workspaceRoot: string): string[] {
+	const sitePackageJson = path.join(siteRoot, "package.json");
+	if (!existsSync(sitePackageJson)) return [];
+
+	const pkg: PackageJson = JSON.parse(readFileSync(sitePackageJson, "utf8"));
+	const require = createRequire(sitePackageJson);
+
+	const packageDirs = new Set<string>();
+	for (const name of dependencyNames(pkg)) {
+		const dir = resolvePackageDir(name, require);
+		if (dir && insideWorkspace(realpathSync(dir), workspaceRoot)) {
+			packageDirs.add(realpathSync(dir));
+		}
+	}
+	return [...packageDirs].sort();
+}
+
+function fingerprintWorkspacePackages(siteRoot: string, workspaceRoot: string): string | undefined {
+	const sitePackageJson = path.join(siteRoot, "package.json");
+	if (!existsSync(sitePackageJson)) return undefined;
+
+	const packageDirs = workspaceDependencyDirs(siteRoot, workspaceRoot);
+	if (packageDirs.length === 0) return undefined;
+
+	const hash = createHash("sha1");
+	for (let dir of packageDirs) {
+		hash.update(`package:${dir}\n`);
+		fingerprintDir(dir, dir, hash);
+	}
+	return hash.digest("hex");
+}
+
+function dependencyNames(pkg: PackageJson): string[] {
+	return [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})];
+}
+
+function resolvePackageDir(name: string, require: NodeRequire): string | undefined {
+	try {
+		const packageJsonPath = require.resolve(`${name}/package.json`);
+		return path.dirname(packageJsonPath);
+	} catch {
+		return undefined;
+	}
+}
+
+function insideWorkspace(dir: string, workspaceRoot: string): boolean {
+	const relative = path.relative(workspaceRoot, dir);
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function fingerprintDir(dir: string, root: string, hash: import("node:crypto").Hash): void {
+	for (let entry of readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name === "node_modules" || entry.name === ".git") continue;
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			fingerprintDir(full, root, hash);
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		const stats = statSync(full);
+		// NOTE: hash.update takes (data, encoding) -- join into one string
+		hash.update(
+			`file:${path.relative(root, full).replaceAll("\\", "/")}:${stats.size}:${Math.floor(stats.mtimeMs)}\n`,
+		);
+	}
+}

package/src/run/devPlugin.ts

@@ -0,0 +1,128 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { existsSync, promises as fs } from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { type Plugin, type ViteDevServer } from "vite";
+import { serverError } from "../response.ts";
+import Server from "../server/Server.ts";
+import flattenHeaders from "../server/connect/flattenHeaders.ts";
+import type Site from "../site/Site.ts";
+import prepareTemplate from "./prepareTemplate.ts";
+
+type ReqHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+
+/**
+ * The default Node-runtime dev plugin. Reads `src/site.html`, sets up a torpor
+ * `Server` whose catch-all route renders via `vite.ssrLoadModule`, and registers
+ * a Connect middleware (after Vite's own middlewares) that bridges Node
+ * req/res to the torpor Server's fetch handler.
+ *
+ * Adapters that need a different runtime (e.g. workerd) provide their own
+ * `dev()` plugin instead.
+ */
+export default function devPlugin(site: Site): Plugin {
+	return {
+		name: "torpor-dev",
+		configureServer(vite) {
+			// Kick off async setup immediately; the middleware awaits it so we
+			// don't depend on whether Vite awaits configureServer itself.
+			const handlerPromise = createDevHandler(vite, site);
+			// Return a post-hook so our middleware runs AFTER Vite's internal
+			// middlewares (static serving, transforms, HMR), acting as the SSR
+			// fallback.
+			return () => {
+				vite.middlewares.use(async (req, res, next) => {
+					try {
+						const handler = await handlerPromise;
+						await handler(req, res);
+					} catch (e) {
+						next(e as Error);
+					}
+				});
+			};
+		},
+	};
+}
+
+async function createDevHandler(vite: ViteDevServer, site: Site): Promise<ReqHandler> {
+	const siteFolder = path.resolve(site.root, "./node_modules/@torpor/build/src/site/");
+	const serverScript = path.join(siteFolder, "serverEntry.ts");
+
+	// Read site.html if present
+	// It's called site.html because @torpor/build builds the site (html, routes
+	// etc) while the user builds the app (components etc). An endpoints-only
+	// site has no site.html, and no template is needed
+	let template: string | undefined;
+	const templateFile = path.resolve(site.root, "src/site.html");
+	if (existsSync(templateFile)) {
+		template = await fs.readFile(templateFile, "utf-8");
+
+		// Apply Vite HTML transforms. This injects the Vite HMR client, and also
+		// applies HTML transforms from Vite plugins. Note that we only support a
+		// universal transform, not individual transforms for each route
+		template = await vite.transformIndexHtml("", template);
+
+		// Prepare site.html so that we can just splice components into it
+		const clientScript = path.join(siteFolder, "clientEntry.ts");
+		const clientDevScript = path.join(siteFolder, "clientEntryDev.ts");
+		template = prepareTemplate(template, clientScript, clientDevScript);
+	}
+
+	const server = new Server();
+
+	// Every request (GET, POST, etc) goes through loadEndPoint
+	server.add("*", async (ev) => {
+		try {
+			// Load the server entry. ssrLoadModule automatically transforms ESM
+			// source code to be usable in Node.js. No bundling is required, and
+			// it provides efficient invalidation similar to HMR
+			const { load } = await vite.ssrLoadModule(serverScript);
+
+			// Render the app HTML (or fetch server data etc) via serverEntry's
+			// exported `load` function
+			return await load(ev, template);
+		} catch (e: any) {
+			// If an error is caught, let Vite fix the stack trace so it maps
+			// back to your actual source code
+			vite.ssrFixStacktrace(e);
+			return serverError(e);
+		}
+	});
+
+	// Put adapter-specific functionality in the `adapter` property of
+	// globalThis for now
+	// @ts-ignore
+	globalThis.adapter = { env: process.env };
+
+	return async (req, res) => {
+		const request = await nodeReqToRequest(req);
+		const response = await server.fetch(request);
+		await sendResponse(response, res);
+	};
+}
+
+async function nodeReqToRequest(req: IncomingMessage): Promise<Request> {
+	const url = req.url ?? "/";
+	const host = req.headers.host ?? "localhost";
+	const protocol = "encrypted" in req.socket && req.socket.encrypted ? "https" : "http";
+	const init: RequestInit = {
+		method: req.method,
+		headers: flattenHeaders(req.headers),
+	};
+	if (req.method !== "GET" && req.method !== "HEAD") {
+		init.body = Readable.toWeb(req) as ReadableStream;
+		// @ts-ignore duplex is required when streaming a body
+		init.duplex = "half";
+	}
+	return new Request(`${protocol}://${host}${url}`, init);
+}
+
+async function sendResponse(response: Response, res: ServerResponse): Promise<void> {
+	res.statusCode = response.status;
+	response.headers.forEach((value, key) => res.setHeader(key, value));
+	if (!response.body) {
+		res.end();
+		return;
+	}
+	Readable.fromWeb(response.body as unknown as import("node:stream/web").ReadableStream).pipe(res);
+}

package/src/run/prepareTemplate.ts

@@ -15,10 +15,13 @@ export default function prepareTemplate(
 
 	// Put %COMPONENT_BODY% inside <div id="app"></div>
 	// This is where the component's HTML will go
-	let bodyStart = regexIndexOf(result, /<div\s+id=("app"|'app'|app)\s+/);
-	bodyStart = result.indexOf(">", bodyStart) + 1;
+	let divMatchStart = regexIndexOf(result, /<div\s+id=("app"|'app'|app)[\s>]/);
+	if (divMatchStart === -1) {
+		throw new Error(`Couldn't find <div id="app"></div>`);
+	}
+	let bodyStart = result.indexOf(">", divMatchStart) + 1;
 	let bodyEnd = result.indexOf("</div>", bodyStart);
-	if (bodyStart === -1 || bodyEnd === -1) {
+	if (bodyEnd === -1) {
 		throw new Error(`Couldn't find <div id="app"></div>`);
 	}
 	result = result.substring(0, bodyStart) + "%COMPONENT_BODY%" + result.substring(bodyEnd);

package/src/run/run.ts

@@ -1,62 +1,86 @@
 import fs from "node:fs";
 import path from "node:path";
-import { transformWithEsbuild } from "vite";
+import { createServer as createViteServer, type ViteDevServer } from "vite";
 import Site from "../site/Site";
 import runBuild from "./runBuild";
 import runDev from "./runDev";
 import runPreview from "./runPreview";
 
-export default async function run(
-	folder: string,
-	mode: "dev" | "build" | "preview",
-): Promise<void> {
+/**
+ * Looks for and loads a site.config.js/ts file in the working directory,
+ * running the site's plugins. The Vite server used to load the config is
+ * returned as well, so that (for example) route files can be loaded through
+ * it; callers are responsible for closing it.
+ */
+export async function loadSite(folder: string): Promise<{ site: Site; vite: ViteDevServer }> {
 	// Look for and load a site.config.js/ts file in the working directory
-	let configFile = "";
-	let deleteConfigFile = false;
 	const jsConfigFile = path.join(folder, "site.config.js");
 	const tsConfigFile = path.join(folder, "site.config.ts");
+	let configFile = "";
 	if (fs.existsSync(jsConfigFile)) {
-		// If it's JS, we can just import it straight up
 		configFile = jsConfigFile;
 	} else if (fs.existsSync(tsConfigFile)) {
-		// If it's TS, we need to convert it to JS
-		// TODO: Put the generated file somewhere better (dist?)
-		configFile = path.join(folder, "site.config.temp.js");
-		let source = fs.readFileSync(tsConfigFile, "utf-8");
-		let transformed = await transformWithEsbuild(source, tsConfigFile, {
-			loader: "ts",
-		});
-		fs.writeFileSync(configFile, transformed.code);
-		deleteConfigFile = true;
+		configFile = tsConfigFile;
 	} else {
 		throw new Error("site.config file not found");
 	}
 
-	const site = (await import(configFile)).default as Site;
-	if (!site || !site.root || !site.routes) {
-		throw new Error("Invalid site in config file");
-	}
-	if (deleteConfigFile) {
-		fs.rmSync(configFile);
-	}
+	// Use a temporary Vite server to load the config, so that local TS imports
+	// (e.g. a routes.ts file) and path aliases are resolved correctly
+	const vite = await createViteServer({
+		server: { middlewareMode: true },
+		appType: "custom",
+		resolve: { tsconfigPaths: true },
+		optimizeDeps: { noDiscovery: true },
+	});
+	try {
+		const site = (await vite.ssrLoadModule(configFile)).default as Site;
+		site.configFile = configFile;
 
-	switch (mode) {
-		case "dev": {
-			await runDev(site);
-			break;
-		}
-		case "build": {
-			await runBuild(site);
-			break;
+		if (!site || !site.root || !site.routes) {
+			throw new Error("Invalid site in config file");
 		}
-		case "preview": {
-			await runPreview(site);
-			break;
+
+		// Run the site's plugins. The manifest plugin also runs them when the
+		// server starts up (dev SSR and production), so that plugin routes are
+		// registered in the runtime as well
+		for (const plugin of site.plugins) {
+			await plugin(site);
 		}
-		default: {
-			console.log("No mode passed, running in dev");
-			await runDev(site);
-			break;
+
+		return { site, vite };
+	} catch (error) {
+		await vite.close();
+		throw error;
+	}
+}
+
+export default async function run(
+	folder: string,
+	mode: "dev" | "build" | "preview",
+): Promise<void> {
+	const { site, vite } = await loadSite(folder);
+	try {
+		switch (mode) {
+			case "dev": {
+				await runDev(site);
+				break;
+			}
+			case "build": {
+				await runBuild(site);
+				break;
+			}
+			case "preview": {
+				await runPreview(site);
+				break;
+			}
+			default: {
+				console.log("No mode passed, running in dev");
+				await runDev(site);
+				break;
+			}
 		}
+	} finally {
+		await vite.close();
 	}
 }

package/src/run/runBuild.ts

@@ -1,16 +1,31 @@
 import torpor from "@torpor/unplugin/vite";
 import { existsSync, promises as fs } from "node:fs";
 import path from "node:path";
-import { build, defineConfig } from "vite";
+import { build, defineConfig, type AliasOptions } from "vite";
 import Site from "../site/Site";
+import { checkApiCalls, checkRoutes, reportRouteIssues } from "../site/checkRoutes";
+import { checkLayoutSlots } from "../site/checkLayoutSlots";
 import manifest from "../site/manifest.ts";
+import tsconfigAliases, { type AliasEntry } from "../utils/tsconfigAliases";
+import { addTorporPackageConfig } from "../utils/torporPackages";
 
 // TODO: Don't cache index.html in dev?
-// TODO: Multiple hook.server locations
 // TODO: Don't reload layouts during client routing
 // TODO: Call the correct +page and +server routes when in the same folder
 
 export default async function runBuild(site: Site): Promise<void> {
+	// Check route type annotations and makeApi calls against the routes
+	// derived from file locations, and check that layouts render their slot;
+	// errors fail the build before anything is written
+	let errorCount = reportRouteIssues(checkRoutes(site));
+	errorCount += reportRouteIssues(checkApiCalls(site));
+	errorCount += reportRouteIssues(checkLayoutSlots(site));
+	if (errorCount > 0) {
+		throw new Error(
+			`Route type check failed with ${errorCount} error${errorCount === 1 ? "" : "s"} (see above)`,
+		);
+	}
+
 	// Delete the dist folder if it exists
 	const distFolder = path.resolve(site.root, "dist");
 	if (existsSync(distFolder)) {
@@ -25,7 +40,10 @@ export default async function runBuild(site: Site): Promise<void> {
 	}
 
 	// TODO: From a setting
-	let siteHtml = path.resolve(site.root, "src/site.html");
+	// An endpoints-only site has no site.html, so everything template-related
+	// is optional
+	const siteHtml = path.resolve(site.root, "src/site.html");
+	const hasSiteHtml = existsSync(siteHtml);
 
 	const siteFolder = path.resolve(site.root, "./node_modules/@torpor/build/src/site/");
 	let clientScript = path.join(siteFolder, "clientEntry.ts");
@@ -34,16 +52,27 @@ export default async function runBuild(site: Site): Promise<void> {
 	// Build the client assets, including site.html and the route files
 	// EXCLUDING anything with `server.js` in the name
 	const clientConfig = structuredClone(site.viteConfig ?? {});
-	clientConfig.plugins = [manifest(site), torpor(), ...site.plugins];
+	// Resolve tsconfig path aliases (e.g. `@/*`). Previously provided by the
+	// default `vite-tsconfig-paths` plugin on Site; vite-plus handles it inline
+	// for the client, but hardcodes tsconfigPaths:false on the SSR
+	// externalization path, so mirror tsconfig `compilerOptions.paths` as Vite
+	// `resolve.alias` to resolve them during transform for both client and SSR
+	clientConfig.resolve ??= {};
+	clientConfig.resolve.tsconfigPaths ??= true;
+	clientConfig.resolve.alias = [
+		...asAliasArray(clientConfig.resolve.alias),
+		...tsconfigAliases(site.root),
+	];
+	clientConfig.plugins = [manifest(site), torpor(), ...site.vitePlugins];
 	clientConfig.build ??= {};
 	clientConfig.build.outDir = clientFolder;
 	clientConfig.build.rollupOptions ??= {};
 	clientConfig.build.rollupOptions.input = [
-		siteHtml,
+		...(hasSiteHtml ? [siteHtml] : []),
 		clientScript,
 		...site.routes
-			.filter((r) => !/server\.(ts|js)$/.test(r.file))
-			.map((r) => path.resolve(site.root, r.file)),
+			.filter((r) => r.file && !/server\.(ts|js)$/.test(r.file))
+			.map((r) => path.resolve(site.root, r.file!)),
 		...site.inputs.filter((f) => !/server\.(ts|js)$/.test(f)),
 	];
 	clientConfig.build.ssrManifest = true;
@@ -52,13 +81,23 @@ export default async function runBuild(site: Site): Promise<void> {
 	// Build the server assets, including the server entry script and the route
 	// files
 	const serverConfig = structuredClone(site.viteConfig ?? {});
-	serverConfig.plugins = [manifest(site, true), torpor(), ...site.plugins];
+	// Resolve tsconfig path aliases (e.g. `@/*`), as above
+	serverConfig.resolve ??= {};
+	serverConfig.resolve.tsconfigPaths ??= true;
+	serverConfig.resolve.alias = [
+		...asAliasArray(serverConfig.resolve.alias),
+		...tsconfigAliases(site.root),
+	];
+	serverConfig.plugins = [manifest(site, true), torpor(), ...site.vitePlugins];
 	serverConfig.build ??= {};
 	serverConfig.build.outDir = serverFolder;
+	// Bundle packages that ship `.torp` files into the server build, as they
+	// need the torpor compiler (Node/workerd can't load them externalized)
+	addTorporPackageConfig(site.root, serverConfig);
 	serverConfig.build.rollupOptions ??= {};
 	serverConfig.build.rollupOptions.input = [
 		serverScript,
-		...site.routes.map((r) => path.resolve(site.root, r.file)),
+		...site.routes.filter((r) => r.file).map((r) => path.resolve(site.root, r.file!)),
 		...site.inputs,
 	];
 	serverConfig.build.ssr = serverScript;
@@ -66,12 +105,24 @@ export default async function runBuild(site: Site): Promise<void> {
 
 	// Move the site.html file into /client
 	// HACK: Should do this in Rollup if possible?
-	siteHtml = path.join(clientFolder, "site.html");
-	await fs.rename(path.join(clientFolder, "src", "site.html"), siteHtml);
-	await fs.rm(path.join(clientFolder, "src"), { recursive: true });
+	if (hasSiteHtml) {
+		await fs.rename(
+			path.join(clientFolder, "src", "site.html"),
+			path.join(clientFolder, "site.html"),
+		);
+		await fs.rm(path.join(clientFolder, "src"), { recursive: true });
+	}
 
 	// HOOK: Postbuild
 	if (site.adapter.postbuild) {
 		await site.adapter.postbuild(site);
 	}
 }
+
+function asAliasArray(alias: AliasOptions | undefined): AliasEntry[] {
+	// Normalize an existing `resolve.alias` value (array | object | undefined)
+	// into an array so we can concatenate our tsconfig-derived aliases.
+	if (!alias) return [];
+	if (Array.isArray(alias)) return alias;
+	return Object.entries(alias).map(([find, replacement]) => ({ find, replacement }));
+}