@noverax/courier-build 0.0.0-stage → 0.5.0

package/lib/engine/worker.js

@@ -0,0 +1,548 @@
+import { t as RoutesReadError } from "../routes-read-error-DQhKIE2F.js";
+import { n as isRecord } from "../errno-code-CNx_E80R.js";
+import { t as workerMessages } from "../worker-messages-BT2vvNQJ.js";
+import { T as configCandidates, a as projectTransformCache, c as UntrustedConfigError, d as configLoadError, h as localPath, i as loadCourierConfigFile, p as maskedError, t as findConfigFile } from "../load-config-barNPfXN.js";
+import * as nodeModule from "node:module";
+import { createRequire, syncBuiltinESMExports } from "node:module";
+import { basename, dirname, isAbsolute, sep } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseEnv } from "node:util";
+import { MessageChannel } from "node:worker_threads";
+// src/util/define-own.ts
+/**
+* Give a record a key of its own, whatever the key. Assigning `record[key]`
+* with the key `__proto__` sets the record's prototype instead, and the key
+* is lost: a source of that name went missing from the routes built of the
+* config's sources.
+*
+* @param record - The record: an object literal, which no key but `__proto__` sets through a setter
+* @param key - The key, as the config spells it
+* @param value - Its value
+* @example
+* ```ts
+* const routes: Record<string, CourierRoutes> = {};
+* defineOwn(routes, "__proto__", legacyRoutes);
+* Object.keys(routes); // → ["__proto__"]
+* ```
+*/
+function defineOwn(record, key, value) {
+	Object.defineProperty(record, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+}
+// src/engine/project-config.ts
+/**
+* The config a reading of the routes reads: the one the request names, or
+* the nearest found from its root, up to the top of the project.
+*
+* @param request - Where the project is, and the config it names
+* @returns The config, and where one was looked for first
+* @throws RoutesReadError `CONFIG_NOT_FOUND` with no config up to the top of
+*   the project, and `CONFIG_NOT_TRUSTED` for one above the root that someone
+*   else could have put there; either names every path looked at
+* @example
+* ```ts
+* projectConfigFile({ root: "/app/web", envFiles: [] });
+* // → { configFile: "/app/courier.config.ts", lookedFor: ["/app/web/courier.config.ts", …] }
+* ```
+*/
+function projectConfigFile(request) {
+	if (request.configFile !== void 0) return {
+		configFile: request.configFile,
+		lookedFor: []
+	};
+	const candidates = configCandidates(request.root);
+	const unread = (code, message, configFile) => new RoutesReadError(code, message, {
+		root: request.root,
+		configFile
+	}, { inputs: {
+		files: [...candidates].sort(),
+		env: []
+	} });
+	let found;
+	try {
+		found = findConfigFile(request.root);
+	} catch (error) {
+		if (!(error instanceof UntrustedConfigError)) throw error;
+		throw unread("CONFIG_NOT_TRUSTED", error.message, error.context.configFile);
+	}
+	if (found === null) throw unread("CONFIG_NOT_FOUND", `No courier.config.* in ${request.root} or a folder above it, up to the top of the project: the routes a page takes are read from it. Name another file with the plugin's \`config\` option.`);
+	return {
+		configFile: found,
+		lookedFor: candidates.slice(0, candidates.indexOf(found))
+	};
+}
+/**
+* Load the project's config with the project's transforms, kept in its
+* `node_modules/.cache` for the next reading.
+*
+* @param configFile - The config, absolute
+* @param request - Where the project is
+* @param options - What runs around the config's code
+* @returns The config, and its real path
+* @throws RoutesReadError `CONFIG_NOT_LOADED` with what the loader or the config threw
+* @example
+* ```ts
+* const loaded = await loadProjectConfig("/app/courier.config.ts", request, { onModule });
+* ```
+*/
+async function loadProjectConfig(configFile, request, options) {
+	try {
+		const transformCache = projectTransformCache(dirname(configFile));
+		return await loadCourierConfigFile(configFile, {
+			...options,
+			transformCache
+		});
+	} catch (error) {
+		const failure = configLoadError(error, { entry: configFile });
+		const message = `${basename(configFile)} did not load, so the routes a page takes were not read: ${failure.message} ${failure.hint}`;
+		throw new RoutesReadError("CONFIG_NOT_LOADED", message, {
+			root: request.root,
+			configFile
+		}, { stack: failure.cause instanceof Error ? failure.cause.stack : void 0 });
+	}
+}
+// src/engine/read-env-files.ts
+/**
+* Put the variables a project's env files give into `process.env` before its
+* config is read, as the framework's own server does: the first file to set
+* a variable wins, and one the process was started with keeps its value.
+* The bundler's own reading of them, when given, stands in for this one, so
+* a value built of others with `${VAR}` is the one the app sees.
+*
+* @param files - The env files, absolute, the first winning; one that is not there is passed over
+* @param given - The variables the bundler read from them, in place of reading them here
+* @returns The files that were there
+* @example
+* ```ts
+* readEnvFiles(["/app/.env.production.local", "/app/.env.production", "/app/.env.local", "/app/.env"]);
+* ```
+*/
+function readEnvFiles(files, given) {
+	const fromProcess = new Set(Object.keys(process.env));
+	const present = files.filter((file) => existsSync(file));
+	const values = given === void 0 ? Object.entries(parsedFrom(present)) : Object.entries(given);
+	for (const [key, value] of values) if (!fromProcess.has(key)) process.env[key] = value;
+	return present;
+}
+function parsedFrom(files) {
+	const parsed = {};
+	for (const file of files) for (const [key, value] of Object.entries(parseEnv(readFileSync(file, "utf8")))) if (value !== void 0 && !(key in parsed)) parsed[key] = value;
+	return parsed;
+}
+// src/engine/reading-failure.ts
+/**
+* Why a reading of the routes failed, as a `RoutesReadError` whatever it
+* threw. The engine's own failure is kept as it is, its text the engine's
+* words and what the loader quoted of the project, masked already. Anything
+* else came from the project's code, a getter of its config or a source the
+* core read, and is `CONFIG_NOT_LOADED`, its text and stack with no secret
+* left in them: a bundler prints them, shows them on the page, and a CI
+* log, which may be public, keeps them.
+*
+* @param thrown - What the reading threw
+* @param context - The project's root, and the config file once found
+* @param inputs - What the reading had read, for a failure that names none yet
+* @returns The failure
+* @example
+* ```ts
+* readingFailure(new Error(`bad ${process.env.API_KEY}`), { root: "/app" }).message;
+* // → "The routes a page takes were not read: bad [redacted]"
+* ```
+*/
+function readingFailure(thrown, context, inputs) {
+	if (thrown instanceof RoutesReadError) {
+		if (thrown.inputs !== void 0 || inputs === void 0) return thrown;
+		return new RoutesReadError(thrown.code, thrown.message, thrown.context, {
+			stack: thrown.stack,
+			inputs
+		});
+	}
+	const masked = maskedError(thrown);
+	return new RoutesReadError("CONFIG_NOT_LOADED", `The routes a page takes were not read: ${masked.message}`, context, {
+		stack: thrown instanceof Error ? masked.stack : void 0,
+		inputs
+	});
+}
+// src/engine/track-env-reads.ts
+/**
+* Note every environment variable the code that runs next looks at, by
+* putting a watcher in front of `process.env`: a name read, tested for or
+* described is noted, and listing them all notes them all.
+*
+* @param options - Whether to begin paused
+* @returns What was looked at, asked once the code has run
+* @example
+* ```ts
+* const reads = trackEnvReads();
+* process.env.API_URL;
+* reads.names(); // ["API_URL"]
+* ```
+*/
+function trackEnvReads({ paused: startPaused = false } = {}) {
+	const read = /* @__PURE__ */ new Set();
+	let all = false;
+	let waiting = startPaused;
+	let paused = waiting ? 1 : 0;
+	process.env = new Proxy(process.env, watcherOf({
+		read: (key) => {
+			if (paused === 0 && typeof key === "string") read.add(key);
+		},
+		listed: () => {
+			if (paused === 0) all = true;
+		}
+	}));
+	return {
+		names: () => all ? "*" : [...read].sort(),
+		untracked(run) {
+			paused += 1;
+			try {
+				return run();
+			} finally {
+				paused -= 1;
+			}
+		},
+		resume() {
+			if (waiting) paused -= 1;
+			waiting = false;
+		}
+	};
+}
+function watcherOf(looks) {
+	return {
+		get(target, key) {
+			looks.read(key);
+			return Reflect.get(target, key);
+		},
+		has(target, key) {
+			looks.read(key);
+			return Reflect.has(target, key);
+		},
+		getOwnPropertyDescriptor(target, key) {
+			looks.read(key);
+			return Reflect.getOwnPropertyDescriptor(target, key);
+		},
+		ownKeys(target) {
+			looks.listed();
+			return Reflect.ownKeys(target);
+		},
+		set: (target, key, value) => Reflect.set(target, key, value),
+		defineProperty: (target, key, descriptor) => Reflect.defineProperty(target, key, descriptor)
+	};
+}
+// src/engine/track-file-reads.ts
+const require$1 = createRequire(import.meta.url);
+const READS = [
+	"readFileSync",
+	"readFile",
+	"createReadStream",
+	"existsSync",
+	"statSync",
+	"lstatSync",
+	"stat",
+	"lstat",
+	"accessSync",
+	"access"
+];
+const LISTS = [
+	"readdirSync",
+	"readdir",
+	"opendirSync",
+	"opendir"
+];
+const PROMISED_READS = [
+	"readFile",
+	"stat",
+	"lstat",
+	"access"
+];
+const PROMISED_LISTS = ["readdir", "opendir"];
+/**
+* Note every path the code that runs next reads or looks at through `fs`,
+* and every folder it lists: a config that reads an OpenAPI document, or
+* builds its sources from a folder's entries, depends on them as on the
+* modules it imports. Each path is noted as the system names it, however
+* the code wrote it. Installed packages are left out, as the install
+* changes them, and so is anything `fs` is handed that names no path.
+*
+* @returns What was read, asked once the code has run
+* @example
+* ```ts
+* const reads = trackFileReads();
+* readFileSync("./openapi.json");
+* reads.paths(); // ["/app/openapi.json"]
+* ```
+*/
+function trackFileReads() {
+	const paths = /* @__PURE__ */ new Set();
+	const folders = /* @__PURE__ */ new Set();
+	const fs = require$1("node:fs");
+	const promises = require$1("node:fs/promises");
+	if (isRecord(fs)) {
+		noteCalls(fs, READS, paths);
+		noteCalls(fs, LISTS, folders);
+	}
+	if (isRecord(promises)) {
+		noteCalls(promises, PROMISED_READS, paths);
+		noteCalls(promises, PROMISED_LISTS, folders);
+	}
+	syncBuiltinESMExports();
+	return {
+		paths: () => [...paths],
+		folders: () => [...folders]
+	};
+}
+function noteCalls(target, names, noted) {
+	for (const name of names) {
+		const original = target[name];
+		if (typeof original !== "function") continue;
+		target[name] = Object.assign(function(...args) {
+			const path = pathOf(args[0]);
+			if (path !== void 0 && !path.split(sep).includes("node_modules")) noted.add(path);
+			return Reflect.apply(original, this, args);
+		}, original);
+	}
+}
+function pathOf(value) {
+	if (typeof value === "string") return localPath(value);
+	if (value instanceof URL) return value.protocol === "file:" ? fileURLToPath(value) : void 0;
+	if (Buffer.isBuffer(value)) return pathOf(value.toString());
+}
+// src/engine/note-resolved-files.ts
+const ASYNC_HOOKS = `let port;
+export function initialize(data) {
+  port = data.port;
+  port.on("message", (message) => { if (message === "flush") port.postMessage("flushed"); });
+  port.unref();
+}
+export async function resolve(specifier, context, nextResolve) {
+  const resolved = await nextResolve(specifier, context);
+  if (resolved.url.startsWith("file:")) port.postMessage(resolved.url);
+  return resolved;
+}
+`;
+/**
+* Note the file of every ES module Node resolves from now on, into a set:
+* with the synchronous hooks Node has from 22.15, as it resolves each one;
+* before, with hooks on the loader's own thread, whose notes arrive once
+* `settled()` resolves.
+*
+* @param noted - Where each file goes
+* @param hooks - Which hooks: the synchronous ones wherever Node has them
+* @returns How to wait for every note
+* @example
+* ```ts
+* const resolved = noteResolvedFiles(files);
+* await import(configUrl);
+* await resolved.settled(); // files now holds every module the import resolved
+* ```
+*/
+function noteResolvedFiles(noted, hooks = typeof nodeModule.registerHooks === "function" ? "sync" : "async") {
+	if (hooks === "sync" && typeof nodeModule.registerHooks === "function") {
+		nodeModule.registerHooks({ resolve(specifier, context, nextResolve) {
+			const resolved = nextResolve(specifier, context);
+			if (resolved.url.startsWith("file:")) noted.add(fileURLToPath(resolved.url));
+			return resolved;
+		} });
+		return { settled: () => Promise.resolve() };
+	}
+	return noteOffThread(noted);
+}
+function noteOffThread(noted) {
+	const { port1, port2 } = new MessageChannel();
+	const flushed = [];
+	port1.on("message", (message) => {
+		if (message === "flushed") flushed.shift()?.();
+		else if (typeof message === "string") noted.add(fileURLToPath(message));
+		if (flushed.length === 0) port1.unref();
+	});
+	port1.unref();
+	nodeModule.register(`data:text/javascript,${encodeURIComponent(ASYNC_HOOKS)}`, {
+		data: { port: port2 },
+		transferList: [port2]
+	});
+	return { settled: () => new Promise((resolve) => {
+		flushed.push(resolve);
+		port1.ref();
+		port1.postMessage("flush");
+	}) };
+}
+// src/engine/track-module-files.ts
+const require = createRequire(import.meta.url);
+/**
+* Note the file of every module the code that runs next loads: the ones
+* the config's loader transforms are told by `noteFile`; the ones Node
+* loads itself are read from its CommonJS cache and from each ES module it
+* resolves.
+*
+* @param hooks - How the ES modules Node resolves are noted: synchronously wherever Node can
+* @returns The files noted, and how to note one
+* @example
+* ```ts
+* const modules = trackModuleFiles();
+* await loadCourierConfigFile(file, { onModule: modules.noteFile });
+* await modules.files(); // ["/app/courier.config.ts", "/app/src/api.ts", …]
+* ```
+*/
+function trackModuleFiles(hooks) {
+	const noted = /* @__PURE__ */ new Set();
+	const resolved = noteResolvedFiles(noted, hooks);
+	return {
+		noteFile: (file) => noted.add(file),
+		files: async () => {
+			await resolved.settled();
+			return [...noted, ...Object.keys(require.cache).filter((key) => isAbsolute(key))];
+		}
+	};
+}
+// src/engine/track-reading.ts
+/**
+* Note what one reading of the routes reads, from now on: the modules Node
+* and the config's loader load, the files read and folders listed once the
+* config is found, and the environment variables the config's code looks at
+* once it runs, besides the config and the env files.
+*
+* @param request - The reading's request, whose env files are read before it
+* @returns The tracker
+* @example
+* ```ts
+* const reading = trackReading(request);
+* await loadProjectConfig(configFile, request, reading.loadOptions);
+* await reading.inputs(); // { configFile, files: [...], env: ["API_URL"] }
+* ```
+*/
+function trackReading(request) {
+	const modules = trackModuleFiles();
+	const env = trackEnvReads({ paused: true });
+	let configFile;
+	let reads;
+	const looked = /* @__PURE__ */ new Set();
+	return {
+		loadOptions: {
+			onModule: modules.noteFile,
+			beforeRun: env.resume,
+			runTransform: env.untracked
+		},
+		noteConfig(file, lookedFor) {
+			configFile = file;
+			reads ??= trackFileReads();
+			looked.add(file);
+			for (const path of lookedFor) looked.add(path);
+		},
+		inputs: async () => {
+			const files = [
+				...looked,
+				...request.envFiles,
+				...await modules.files()
+			];
+			return {
+				configFile,
+				files: [...new Set([...files, ...reads?.paths() ?? []].map(localPath))].sort(),
+				listed: [...reads?.folders() ?? []].sort(),
+				env: env.names()
+			};
+		}
+	};
+}
+// src/engine/read-project-routes.ts
+/**
+* Read a project's routes from its config: its env files first, then the
+* config, every module it reaches transformed once and kept for the next
+* process, then each source's routes by the rules the proxy applies. Run in
+* a process of its own, which it leaves changed: `process.env` is watched,
+* and Node's resolution hooked.
+*
+* @param request - Where the project is, and which env files it reads
+* @returns The routes, and every file and variable they depended on
+* @throws RoutesReadError `CONFIG_NOT_FOUND` with no config to read,
+*   `CONFIG_NOT_TRUSTED` for one someone else could have put above the root,
+*   and `CONFIG_NOT_LOADED` for one that would not load or holds no
+*   `sources`; each names what the reading had read, which may mend it
+* @example
+* ```ts
+* const { routes } = await readProjectRoutes({ root: "/app", envFiles: ["/app/.env"] });
+* ```
+*/
+async function readProjectRoutes(request) {
+	readEnvFiles(request.envFiles, request.env);
+	const reading = trackReading(request);
+	try {
+		const { configFile, lookedFor } = projectConfigFile(request);
+		reading.noteConfig(configFile, lookedFor);
+		const loaded = await loadProjectConfig(configFile, request, reading.loadOptions);
+		reading.noteConfig(loaded.configFile, lookedFor);
+		const routes = await routesOfSources(loaded, request.root);
+		return {
+			...await reading.inputs(),
+			configFile: loaded.configFile,
+			routes
+		};
+	} catch (error) {
+		const inputs = await reading.inputs();
+		throw readingFailure(error, {
+			root: request.root,
+			configFile: inputs.configFile
+		}, inputs);
+	}
+}
+async function routesOfSources(loaded, root) {
+	const sources = sourcesOf(loaded, root);
+	const read = await projectRoutesOf(loaded.configFile, root);
+	const routes = {};
+	for (const name of Object.keys(sources).sort(byCodeUnits)) defineOwn(routes, name, read(sources[name], name));
+	return routes;
+}
+function sourcesOf(loaded, root) {
+	const sources = isRecord(loaded.config) ? loaded.config.sources : void 0;
+	if (isRecord(sources)) return sources;
+	throw new RoutesReadError("CONFIG_NOT_LOADED", `${basename(loaded.configFile)} exports no \`sources\`: the routes a page takes are read from the APIs it names there.`, {
+		root,
+		configFile: loaded.configFile
+	});
+}
+async function projectRoutesOf(configFile, root) {
+	const path = createRequire(configFile).resolve("@noverax/courier/internal");
+	const core = await import(pathToFileURL(path).href);
+	if (typeof core.routesOf === "function") return core.routesOf;
+	throw new RoutesReadError("CONFIG_NOT_LOADED", `The @noverax/courier at ${path} reads no routes: update it to the version of @noverax/courier-build.`, {
+		root,
+		configFile
+	});
+}
+function byCodeUnits(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+// src/engine/worker.ts
+process.on("message", take);
+process.once("disconnect", () => process.exit(1));
+function take(message) {
+	if (!workerMessages.isRequest(message)) return;
+	process.off("message", take);
+	answer(message.request);
+}
+async function answer(request) {
+	const reply = await readProjectRoutes(request).then((snapshot) => ({
+		ok: true,
+		snapshot
+	}), (error) => failure(error, request));
+	process.send?.(workerMessages.reply(reply), () => process.exit(0));
+}
+function failure(error, request) {
+	const failed = readingFailure(error, {
+		root: request.root,
+		configFile: request.configFile
+	});
+	return {
+		ok: false,
+		code: failed.code,
+		message: failed.message,
+		context: failed.context,
+		stack: failed.stack,
+		inputs: failed.inputs
+	};
+}
+export {};

package/lib/errno-code-CNx_E80R.js

@@ -0,0 +1,32 @@
+// src/util/is-record.ts
+/**
+* Whether a value is an object read by its keys: not null, not an array.
+*
+* @param value - The value to check
+* @returns Whether it can be read as a record of fields
+*
+* @example
+* ```ts
+* isRecord({ sources: {} }); // true
+* isRecord(["shop"]); // false
+* ```
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// src/config/errno-code.ts
+/**
+* The `code` a Node system error carries, such as `ENOENT` or `EACCES`.
+*
+* @param error - Anything thrown
+* @returns The code, or `undefined` when the value carries none
+* @example
+* ```ts
+* if (errnoCode(err) === "ENOENT") return null;
+* ```
+*/
+function errnoCode(error) {
+	if (typeof error !== "object" || error === null || !("code" in error)) return void 0;
+	return typeof error.code === "string" ? error.code : void 0;
+}
+export { isRecord as n, errnoCode as t };

package/lib/esbuild/index.d.ts

@@ -0,0 +1,58 @@
+import { t as CourierRoutesOptions } from "../courier-routes-options-BYF7Sfdf.js";
+import { Plugin } from "esbuild";
+/**
+ * The esbuild plugin that builds the routes a page's proxy client may call
+ * from `courier.config.ts`, in place of the module `@noverax/courier/routes`
+ * ships. No routes file is written, and the routes carry no address, path or
+ * middleware. A page's bundle — any `platform` but `node` — that takes the
+ * config itself fails.
+ *
+ * A build that cannot read the config fails with why. A context that builds
+ * again, under `watch()` or `serve()`, follows every file the routes came
+ * from; when they cannot be read on a later build, it keeps the routes it
+ * read last and warns why.
+ *
+ * @param options - Where the config is, when it is not found from `absWorkingDir`
+ * @returns The plugin
+ * @example
+ * ```ts
+ * import { build } from "esbuild";
+ * import { courierRoutes } from "@noverax/courier-build/esbuild";
+ *
+ * await build({ entryPoints: ["src/main.ts"], bundle: true, plugins: [courierRoutes()] });
+ * ```
+ */
+export declare function courierRoutes(options?: CourierRoutesOptions): Plugin;
+/** Options of the esbuild plugin that takes the routes from a module written to disk. */
+interface WrittenRoutesOptions extends CourierRoutesOptions {
+  /** The project's root, absolute: the config is found from it. */
+  readonly root: string;
+  /** The module the routes are written to, absolute: the host must follow it as a file it reads. */
+  readonly file: string;
+  /** Whether the host builds again on a change: then the routes read last stay while the config is broken. */
+  readonly watch: boolean;
+  /** How the app names another place for the module, should that one not take it: said in the error. */
+  readonly elsewhere: string;
+}
+/**
+ * The esbuild plugin for a host that follows only the files its build read
+ * from disk, as Angular's builders do, not those a plugin names: the
+ * routes are written to a module there, which `@noverax/courier/routes`
+ * resolves to, and watchers of what they came from rewrite it on a change,
+ * so the host builds it again. A page's bundle — any `platform` but `node` —
+ * that takes the config itself fails.
+ *
+ * A build fails while the routes cannot be read, with why; a host that
+ * watches keeps the routes read last, and with none read yet the module
+ * fails where it is imported, saying why.
+ *
+ * @param options - Where the project, its config and the module are, and whether the host watches
+ * @returns The plugin, once the routes are written
+ * @throws RoutesReadError `ROUTES_NOT_WRITTEN` when the module cannot be written
+ * @example
+ * ```ts
+ * const plugin = await writtenRoutesPlugin({ root, file: join(dir, "routes.js"), watch: false, elsewhere: "TMPDIR" });
+ * ```
+ */
+export declare function writtenRoutesPlugin(options: WrittenRoutesOptions): Promise<Plugin>;
+export type { CourierRoutesOptions, WrittenRoutesOptions };