@noverax/courier-build 0.0.0-stage → 0.4.0

package/lib/load-config-BeedbpkN.js

@@ -0,0 +1,1419 @@
+import { n as isRecord, t as errnoCode } from "./errno-code-CNx_E80R.js";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+import { closeSync, constants, existsSync, fstatSync, futimesSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { CourierError, createLogger } from "@noverax/courier";
+import { createHash, randomBytes } from "node:crypto";
+import { parseJSON5 } from "confbox";
+// src/config/config-candidates.ts
+/** The file names a Courier config may have, in the order they are looked for */
+const CONFIG_BASENAMES = [
+	"courier.config.ts",
+	"courier.config.mts",
+	"courier.config.cts",
+	"courier.config.js",
+	"courier.config.mjs",
+	"courier.config.cjs"
+];
+const PROJECT_TOP_MARKERS = [
+	".git",
+	".hg",
+	".jj",
+	"pnpm-workspace.yaml"
+];
+/**
+* Every path a config is looked for at from a folder, in the order it is
+* looked for: each of {@link CONFIG_BASENAMES} in the folder, then in each
+* folder above it, up to the top of the project — the first folder that
+* holds its repository (`.git`, `.hg`, `.jj`) or is the root of its
+* workspace (`pnpm-workspace.yaml`, or a `package.json` that declares
+* `workspaces`) — or, with no such folder, the root of the file system.
+*
+* @param startDir - The folder to look in first
+* @returns The paths, absolute, whether there or not
+* @example
+* ```ts
+* configCandidates("/repo/apps/web"); // → ["/repo/apps/web/courier.config.ts", …, "/repo/courier.config.cjs"]
+* ```
+*/
+function configCandidates(startDir) {
+	const candidates = [];
+	let dir = resolve(startDir);
+	while (true) {
+		for (const basename of CONFIG_BASENAMES) candidates.push(join(dir, basename));
+		const parent = dirname(dir);
+		if (parent === dir || isProjectTop(dir)) return candidates;
+		dir = parent;
+	}
+}
+function isProjectTop(dir) {
+	return PROJECT_TOP_MARKERS.some((marker) => existsSync(join(dir, marker))) || declaresWorkspaces(join(dir, "package.json"));
+}
+function declaresWorkspaces(manifest) {
+	if (!existsSync(manifest)) return false;
+	try {
+		const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+		return isRecord(parsed) && parsed.workspaces !== void 0;
+	} catch {
+		return false;
+	}
+}
+// src/config/installed-packages.ts
+/**
+* Which packages a project has installed, for the path aliases to stop at.
+*/
+/**
+* The packages installed where `projectRoot` resolves them, each looked up
+* once.
+*
+* @param projectRoot - Directory holding the project's `tsconfig.json`
+* @returns The lookup
+* @example
+* ```ts
+* installedPackages("/app").has("@acme/ui"); // true once it is in node_modules
+* ```
+*/
+function installedPackages(projectRoot) {
+	const require = createRequire(resolve(projectRoot, "tsconfig.json"));
+	const known = /* @__PURE__ */ new Map();
+	return { has(name) {
+		let installed = known.get(name);
+		if (installed === void 0) {
+			installed = resolves(require, name);
+			known.set(name, installed);
+		}
+		return installed;
+	} };
+}
+/**
+* The package a specifier or an alias prefix names: `@scope/name`, or its
+* first segment; `null` when it names none, as `@scope/` does.
+*
+* @param specifier - A specifier, or an alias's text before its wildcard
+* @returns The package's name, or `null`
+* @example
+* ```ts
+* packageNameOf("@acme/ui/button"); // "@acme/ui"
+* ```
+*/
+function packageNameOf(specifier) {
+	const segments = specifier.split("/");
+	const wanted = specifier.startsWith("@") ? 2 : 1;
+	if (segments.length < wanted) return null;
+	const name = segments.slice(0, wanted);
+	return name.every((segment) => segment.length > 0) ? name.join("/") : null;
+}
+function resolves(require, name) {
+	try {
+		require.resolve(name);
+		return true;
+	} catch (error) {
+		return errnoCode(error) !== "MODULE_NOT_FOUND";
+	}
+}
+// src/config/scope-alias.ts
+/**
+* An alias for a whole scope, `@acme/*`, in the shape the module loader takes.
+*/
+const log$7 = createLogger("Config");
+const MODULE_EXTENSION = /\.(d\.ts|[cm]?[jt]sx?|json)$/;
+/**
+* The scope's name, `@acme`, when `prefix` is an alias's text before the
+* wildcard of a pattern for a whole scope, `@acme/*`.
+*
+* @param prefix - An alias's text before its wildcard
+* @returns The scope, or `undefined` for any other prefix
+* @example
+* ```ts
+* scopeOf("@acme/"); // "@acme"
+* ```
+*/
+function scopeOf(prefix) {
+	return /^(@[^/]+)\/$/.exec(prefix)?.[1];
+}
+/**
+* One loader alias per name a scope alias leads to, leaving out the names of
+* installed packages. The loader follows an alias whatever it finds there,
+* where TypeScript takes an installed package past it: `@acme/*` to
+* `./src/*` keeps `@acme/utils` on `src/utils` while `@acme/ui`, installed,
+* loads the build it ships.
+*
+* @param scope - The scope, `@acme`
+* @param directory - The directory the alias's `*` stands in, absolute
+* @param installed - The packages the project installed
+* @returns Prefix → absolute target, for each name the directory holds
+* @example
+* ```ts
+* scopeAliases("@acme", "/app/src", installed); // { "@acme/utils": "/app/src/utils" }
+* ```
+*/
+function scopeAliases(scope, directory, installed) {
+	const alias = {};
+	for (const entry of entriesOf(directory)) {
+		const name = entry.replace(MODULE_EXTENSION, "");
+		if (!installed.has(`${scope}/${name}`)) alias[`${scope}/${name}`] = join(directory, name);
+	}
+	return alias;
+}
+function entriesOf(directory) {
+	try {
+		return readdirSync(directory);
+	} catch (error) {
+		const code = errnoCode(error);
+		if (code !== "ENOENT" && code !== "ENOTDIR") log$7.warn(`Could not list ${directory} for a path alias; the alias leads nowhere`, error);
+		return [];
+	}
+}
+// src/config/read-tsconfig-file.ts
+const log$6 = createLogger("Config");
+function isTextList(value) {
+	if (!Array.isArray(value)) return false;
+	return value.every((item) => typeof item === "string");
+}
+function readText(path) {
+	try {
+		if (!statSync(path).isFile()) {
+			log$6.warn(`${path} is not a regular file, so its path aliases are ignored`);
+			return null;
+		}
+		return readFileSync(path, "utf-8");
+	} catch (err) {
+		log$6.warn(`Could not read ${path}, so its path aliases are ignored`, err);
+		return null;
+	}
+}
+function extendsOf(value, path) {
+	if (value === void 0 || value === null) return [];
+	if (typeof value === "string") return [value];
+	if (!Array.isArray(value)) {
+		log$6.warn(`${path}: "extends" is neither a path nor a list of paths, so it is not followed`);
+		return [];
+	}
+	const entries = value;
+	const paths = entries.filter((entry) => typeof entry === "string");
+	if (paths.length < entries.length) log$6.warn(`${path}: "extends" lists something other than a path, which is skipped`);
+	return paths;
+}
+function pathsOf(value, path) {
+	if (value === void 0) return void 0;
+	if (!isRecord(value)) {
+		log$6.warn(`${path}: "paths" is not an object, so its path aliases are ignored`);
+		return;
+	}
+	const kept = [];
+	for (const [pattern, targets] of Object.entries(value)) if (isTextList(targets)) kept.push([pattern, targets]);
+	else log$6.warn(`${path}: "paths" maps "${pattern}" to something other than a list of paths, so it is ignored`);
+	return Object.fromEntries(kept);
+}
+function optionsOf(value, path) {
+	if (value === void 0) return {};
+	if (!isRecord(value)) {
+		log$6.warn(`${path}: "compilerOptions" is not an object, so its path aliases are ignored`);
+		return {};
+	}
+	const { baseUrl } = value;
+	const paths = pathsOf(value.paths, path);
+	const base = typeof baseUrl === "string" ? baseUrl : void 0;
+	if (baseUrl !== void 0 && base === void 0) log$6.warn(`${path}: "baseUrl" is not a path, so its aliases resolve from its own directory`);
+	return {
+		...base !== void 0 && { baseUrl: base },
+		...paths && { paths }
+	};
+}
+/**
+* Read the fields of a tsconfig that its path mapping depends on. A field
+* of another shape than TypeScript takes is left out with a warning, as
+* TypeScript reports it, rather than failing the load of the config that
+* reads the mapping.
+*
+* @param path - The tsconfig
+* @returns What it declares; `null` when it cannot be read or parsed
+* @example
+* ```ts
+* readTsconfigFile("/app/tsconfig.json");
+* // → { extends: ["./tsconfig.base.json"], paths: { "@/*": ["./src/*"] } }
+* ```
+*/
+function readTsconfigFile(path) {
+	const text = readText(path);
+	if (text === null) return null;
+	let parsed;
+	try {
+		parsed = parseJSON5(text);
+	} catch (err) {
+		log$6.warn(`Could not parse ${path}, so its path aliases are ignored`, err);
+		return null;
+	}
+	if (!isRecord(parsed)) {
+		log$6.warn(`${path} does not hold an object, so its path aliases are ignored`);
+		return null;
+	}
+	return {
+		extends: extendsOf(parsed.extends, path),
+		...optionsOf(parsed.compilerOptions, path)
+	};
+}
+// src/config/tsconfig-paths.ts
+/**
+* Read a project's `compilerOptions.paths` without loading TypeScript.
+*
+* The compiler would do this for us, but its API is exactly what a config
+* reader must not depend on: it is an optional peer a JavaScript-only project
+* is entitled not to have, and TypeScript 7 publishes no parser under the
+* package root at all. Reading the file directly costs one JSONC parse.
+*
+* `paths` is not merged down an `extends` chain — TypeScript replaces the map
+* wholesale — so the nearest config that declares one wins, and its targets
+* resolve against its own `baseUrl`, or its own directory when it has none.
+*
+* Parsing is JSON5 rather than strict JSONC: a tsconfig is hand-edited and
+* routinely carries comments and trailing commas, both of which TypeScript
+* accepts. Refusing them would drop a real project's aliases without a word.
+*/
+const log$5 = createLogger("Config");
+/**
+* Read the path mapping that applies to files in `directory`: the one of the
+* nearest `tsconfig.json` at or above it, as TypeScript finds it, so a config
+* file kept below the project root — `deploy/server.config.ts` — keeps every
+* alias the project declares.
+*
+* @param directory - Directory of the file whose imports are resolved
+* @returns The mapping, or `null` when no tsconfig declares one
+*
+* @example
+* ```ts
+* const mapping = readTsconfigPaths("/app/deploy");
+* // → { baseUrl: "/app", paths: { "@/*": ["./src/*"] } }
+* ```
+*/
+function readTsconfigPaths(directory) {
+	const tsconfig = nearestTsconfig(resolve(directory));
+	return tsconfig ? findPaths(tsconfig, /* @__PURE__ */ new Set()) : null;
+}
+function nearestTsconfig(directory) {
+	for (let dir = directory;; dir = dirname(dir)) {
+		const candidate = resolve(dir, "tsconfig.json");
+		if (existsSync(candidate)) return candidate;
+		if (dirname(dir) === dir) return null;
+	}
+}
+/** Walk the `extends` chain depth-first, stopping at the first declared map. */
+function findPaths(file, visited) {
+	const path = resolve(file);
+	if (visited.has(path)) return null;
+	visited.add(path);
+	const config = readTsconfigFile(path);
+	if (!config) return null;
+	if (config.paths) return {
+		baseUrl: resolve(dirname(path), config.baseUrl ?? "."),
+		paths: config.paths
+	};
+	for (const specifier of [...config.extends].reverse()) {
+		const parent = resolveExtends(specifier, dirname(path));
+		if (!parent) {
+			log$5.warn(`${path} extends "${specifier}", which cannot be found, so its path aliases are not read`);
+			continue;
+		}
+		const found = findPaths(parent, visited);
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* Resolve an `extends` specifier: a path, a directory holding a
+* `tsconfig.json`, or an installed package that ships one.
+*/
+function resolveExtends(specifier, fromDir) {
+	if (specifier.startsWith(".") || isAbsolute(specifier)) {
+		const candidate = resolve(fromDir, specifier);
+		if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+			const nested = resolve(candidate, "tsconfig.json");
+			return existsSync(nested) ? nested : null;
+		}
+		if (existsSync(candidate)) return candidate;
+		const suffixed = `${candidate}.json`;
+		return existsSync(suffixed) ? suffixed : null;
+	}
+	const requireFrom = createRequire(resolve(fromDir, "tsconfig.json"));
+	for (const target of [specifier, `${specifier}/tsconfig.json`]) {
+		const found = resolveFrom(requireFrom, target);
+		if (found) return found;
+	}
+	return null;
+}
+function resolveFrom(requireFrom, target) {
+	try {
+		return requireFrom.resolve(target);
+	} catch (err) {
+		log$5.debug(`"${target}" does not resolve to a tsconfig`, err);
+		return null;
+	}
+}
+// src/config/path-aliases.ts
+/**
+* Turn a project's tsconfig `paths` into the two shapes that reading a config
+* needs: the alias map the module loader takes, and a lookup the dependency
+* walker uses to follow an aliased import.
+*
+* An alias that shadows an installed package is left out of both. Such an
+* entry redirects a dependency to its sources for the bundler's benefit —
+* `@acme/ui` to `../ui/src`, or a whole scope, `@acme/*` — and following it
+* would load a library's source instead of the build it ships, then treat
+* every file inside it as something the config depends on. A dependency
+* changes when it is reinstalled, not while the developer is editing; the
+* graph stops at the package boundary. A catch-all `*` covers every package,
+* so it is left out too: the loader, which cannot fall back to the package as
+* TypeScript does, would put its target before every path it loads.
+*/
+const EMPTY = {
+	loader: {},
+	candidatesFor: () => []
+};
+/**
+* Read the path aliases that apply to `projectRoot`.
+*
+* @param projectRoot - Directory holding the project's `tsconfig.json`
+* @returns The aliases, empty when the project declares none
+*
+* @example
+* ```ts
+* const aliases = readPathAliases("/app");
+* aliases.candidatesFor("@/lib/sources"); // → ["/app/src/lib/sources"]
+* ```
+*/
+function readPathAliases(projectRoot) {
+	const mapping = readTsconfigPaths(projectRoot);
+	if (!mapping) return EMPTY;
+	const installed = installedPackages(projectRoot);
+	const entries = toEntries(mapping).filter((entry) => !shadowsInstalled(entry, installed));
+	if (entries.length === 0) return EMPTY;
+	return {
+		loader: toLoaderAlias(entries, installed),
+		candidatesFor: (specifier) => candidatesOf(entries, specifier, installed)
+	};
+}
+function shadowsInstalled(entry, installed) {
+	if (entry.prefix === "") return true;
+	if (entry.wildcard && scopeOf(entry.prefix) !== void 0) return false;
+	const name = packageNameOf(entry.prefix);
+	return name !== null && installed.has(name);
+}
+function toEntries({ baseUrl, paths }) {
+	const entries = [];
+	for (const [pattern, targets] of Object.entries(paths)) {
+		const star = pattern.indexOf("*");
+		entries.push(star === -1 ? {
+			prefix: pattern,
+			suffix: "",
+			wildcard: false,
+			base: baseUrl,
+			targets
+		} : {
+			prefix: pattern.slice(0, star),
+			suffix: pattern.slice(star + 1),
+			wildcard: true,
+			base: baseUrl,
+			targets
+		});
+	}
+	return entries;
+}
+/** TypeScript picks the single match with the longest prefix before `*`. */
+function candidatesOf(entries, specifier, installed) {
+	let best = null;
+	for (const entry of entries) {
+		if (!matches(entry, specifier)) continue;
+		if (!best || entry.prefix.length > best.prefix.length) best = entry;
+	}
+	if (!best) return [];
+	const { base } = best;
+	if (!best.wildcard) return best.targets.map((target) => resolve(base, target));
+	const name = scopeOf(best.prefix) === void 0 ? null : packageNameOf(specifier);
+	if (name !== null && installed.has(name)) return [];
+	const matched = specifier.slice(best.prefix.length, specifier.length - best.suffix.length);
+	return best.targets.map((target) => resolve(base, withStarFilled(target, matched)));
+}
+function withStarFilled(target, matched) {
+	const star = target.indexOf("*");
+	return star === -1 ? target : `${target.slice(0, star)}${matched}${target.slice(star + 1)}`;
+}
+function matches(entry, specifier) {
+	if (!entry.wildcard) return specifier === entry.prefix;
+	return specifier.length >= entry.prefix.length + entry.suffix.length && specifier.startsWith(entry.prefix) && specifier.endsWith(entry.suffix);
+}
+/**
+* Only a mapping that ends in `*` on both sides translates to a prefix alias;
+* one with a suffix after the wildcard has no equivalent and stays behind. A
+* scope's alias becomes one alias per name it leads to that is not installed.
+*/
+function toLoaderAlias(entries, installed) {
+	const alias = {};
+	for (const entry of entries) {
+		const written = entry.targets[0];
+		if (!written) continue;
+		const target = resolve(entry.base, written);
+		if (!entry.wildcard) alias[entry.prefix] = target;
+		else if (entry.suffix === "" && target.endsWith("*")) {
+			const scope = scopeOf(entry.prefix);
+			if (scope === void 0) alias[entry.prefix] = target.slice(0, -1);
+			else Object.assign(alias, scopeAliases(scope, target.slice(0, -1), installed));
+		}
+	}
+	return alias;
+}
+// src/config/config-jiti.ts
+let ownTransform;
+function jitiOwnTransform(createJiti) {
+	if (ownTransform) return ownTransform;
+	const { transform } = createJiti(fileURLToPath(import.meta.url), {
+		fsCache: false,
+		moduleCache: false
+	}).options;
+	if (!transform) throw new Error("jiti created an instance without its own transform");
+	ownTransform = transform;
+	return transform;
+}
+/**
+* The module loader for Courier's project files — `courier.config.*` and
+* `courier.mocks.*` — with the options both need: the project's tsconfig path
+* aliases, default-export interop, no module cache, and no native import
+* tried before the loader's own.
+*
+* The module cache is off because this is also the reload path: the dev
+* server loads the files again on every edit, and a cached module would hand
+* back the file as it was before the user changed it. Every load therefore
+* reads and evaluates every file again; a `transformCache` only spares the
+* transform of a file whose bytes are unchanged.
+*
+* jiti's native attempt, which imports every module natively before falling
+* back to its own loader, stays off too, whatever `JITI_TRY_NATIVE` says and
+* under Bun, where it defaults to on: a module imported natively is the
+* runtime's first evaluation of it for the life of the process, so an edit to
+* it would never be seen, and the attempt comes before the module cache
+* `evalModule` is handed, so two files evaluated over one cache would each
+* evaluate a module they both import.
+*
+* jiti's own file cache stays off, with or without a `transformCache`:
+* - it writes each entry in place, so concurrent writers can leave an entry
+*   torn between two transforms that its check still accepts;
+* - an entry it cannot write makes the whole load throw `EACCES`;
+* - unless the file's own directory has a `node_modules`, it falls back to
+*   `os.tmpdir()/jiti`, where another user of the machine can place an entry
+*   that is then run;
+* - its key ignores `interopDefault` and the babel options, so a transform
+*   made under other options can be handed back;
+* - nothing ever prunes it.
+*
+* jiti is loaded here rather than at the top of a module so a bundler that
+* merely reaches this code does not pull a TypeScript transpiler into its
+* graph; only a process that actually reads such a file pays for it.
+*
+* @param file - Absolute, symlink-resolved path of the file to load; modules
+*   and aliases resolve from its directory
+* @param options - Whether to resolve through the project's path aliases
+*   (default: yes), and where to reuse transforms (default: nowhere)
+* @returns A jiti instance for that file
+* @example
+* ```ts
+* const transformCache = createTransformCache();
+* const jiti = await createConfigJiti(configFile, { transformCache });
+* const config = await jiti.import(configFile, { default: true });
+* ```
+*/
+async function createConfigJiti(file, { aliases = true, transformCache, onModule, runTransform } = {}) {
+	const { createJiti } = await import("jiti");
+	const options = {
+		alias: aliases ? readPathAliases(dirname(file)).loader : {},
+		interopDefault: true,
+		moduleCache: false,
+		fsCache: false,
+		tryNative: false
+	};
+	if (!transformCache && !onModule && !runTransform) return createJiti(file, options);
+	const compute = jitiOwnTransform(createJiti);
+	const cached = transformCache ? (transformOptions) => transformCache.transform(transformOptions, compute) : compute;
+	const transform = (given) => {
+		const transformOptions = given.filename === void 0 ? given : {
+			...given,
+			filename: normalize(given.filename)
+		};
+		if (onModule && transformOptions.filename !== void 0) onModule(transformOptions.filename);
+		return runTransform ? runTransform(() => cached(transformOptions)) : cached(transformOptions);
+	};
+	return createJiti(file, {
+		...options,
+		transform
+	});
+}
+// src/config/untrusted-config-error.ts
+/**
+* The config nearest a folder lies in a folder above it, and someone else
+* could have put it there: it belongs to another user, or any user may
+* write it. It was not run, as it would run with the rights of whoever
+* builds or serves the project.
+*
+* @example
+* ```ts
+* throw new UntrustedConfigError("/tmp/courier.config.ts", "/tmp/app", "it belongs to uid 1001");
+* ```
+*/
+var UntrustedConfigError = class extends CourierError {
+	/**
+	* @param configFile - The config that was not run, absolute
+	* @param folder - The folder it was looked for from
+	* @param reason - Why it is not trusted, worded to follow "and"
+	*/
+	constructor(configFile, folder, reason) {
+		super(`${configFile} was not run: it lies above ${folder}, and ${reason}. A config in a folder above the project runs only when it is yours and no one else may change it; move it into the project, or name the project's own config.`, {
+			code: "CONFIG_NOT_TRUSTED",
+			context: {
+				configFile,
+				folder
+			}
+		});
+	}
+};
+// src/config/assert-own-config.ts
+const OTHERS_WRITE = 2;
+/**
+* Refuse a config found in a folder above the one it was looked for from,
+* unless it belongs to this process's user or to the owner of that folder,
+* and no user outside its group may write it. A folder many users share,
+* such as `/tmp`, lets anyone put a config there, and it would run with the
+* rights of whoever builds a project below it. Windows has no owner of that
+* kind, so nothing is refused there.
+*
+* @param configFile - The config found, absolute
+* @param folder - The folder it was looked for from, absolute
+* @throws UntrustedConfigError when someone else could have put it there
+* @example
+* ```ts
+* assertOwnConfig("/repo/courier.config.ts", "/repo/apps/web");
+* ```
+*/
+function assertOwnConfig(configFile, folder) {
+	const uid = process.getuid?.();
+	if (uid === void 0) return;
+	const stats = statSync(configFile);
+	const folderOwner = statSync(folder, { throwIfNoEntry: false })?.uid ?? uid;
+	if (stats.uid !== uid && stats.uid !== folderOwner) throw new UntrustedConfigError(configFile, folder, `it belongs to uid ${stats.uid}, neither this user (${uid}) nor the owner of the folder (${folderOwner})`);
+	if ((stats.mode & OTHERS_WRITE) !== 0) throw new UntrustedConfigError(configFile, folder, "any user may write it");
+}
+// src/config/transform-entry-format.ts
+/**
+* How the first line of a transform cache entry is written.
+*
+* - `prefix`: how every entry starts, whatever the version of its format, so
+*   pruning can tell an entry from a file someone else put in the directory.
+* - `version`: the version this code writes; an entry in any other version
+*   is ignored and replaced.
+*/
+const TRANSFORM_ENTRY_FORMAT = {
+	prefix: "// courier-transform ",
+	version: "2"
+};
+// src/config/encode-transform-entry.ts
+/**
+* The bytes of an entry holding `code`, the transform of the input whose
+* digest is `digest`.
+*
+* The first line names the format's version, the input digest, and the byte
+* length and sha256 of the UTF-8 body that follows it, so a reader can tell
+* a complete entry from a truncated or altered one.
+*
+* @param digest - The input digest, as `transformDigest` computes it
+* @param code - The transformed code; well-formed UTF-16, so UTF-8 keeps it exactly
+* @returns The entry's bytes
+* @example
+* ```ts
+* writeFileSync(path, encodeTransformEntry(digest, result.code));
+* ```
+*/
+function encodeTransformEntry(digest, code) {
+	const { prefix, version } = TRANSFORM_ENTRY_FORMAT;
+	const body = Buffer.from(code, "utf8");
+	const bodySha256 = createHash("sha256").update(body).digest("hex");
+	const header = `${prefix}${version} ${digest} ${body.length} ${bodySha256}\n`;
+	return Buffer.concat([Buffer.from(header, "latin1"), body]);
+}
+// src/config/prune-transform-cache.ts
+const log$4 = createLogger("Config");
+const HOUR_MS = 36e5;
+const ENTRY_MAX_AGE_MS = 720 * HOUR_MS;
+const TEMPORARY_MAX_AGE_MS = HOUR_MS;
+const READ_FLAGS$1 = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+const PREFIX = Buffer.from(TRANSFORM_ENTRY_FORMAT.prefix, "latin1");
+function expiryOf(name) {
+	if (name.endsWith(".tmp")) return {
+		maxAgeMs: TEMPORARY_MAX_AGE_MS,
+		prefix: null
+	};
+	if (name.endsWith(".js")) return {
+		maxAgeMs: ENTRY_MAX_AGE_MS,
+		prefix: PREFIX
+	};
+	return null;
+}
+function isExpired(path, { maxAgeMs, prefix }, now) {
+	const fd = openSync(path, READ_FLAGS$1);
+	try {
+		const stats = fstatSync(fd);
+		if (!stats.isFile() || now - stats.mtimeMs <= maxAgeMs) return false;
+		if (prefix === null) return true;
+		const start = Buffer.alloc(prefix.length);
+		return readSync(fd, start, 0, prefix.length, 0) === prefix.length && start.equals(prefix);
+	} finally {
+		closeSync(fd);
+	}
+}
+/**
+* Delete what a transform cache directory holds for nothing: entries not
+* read for 30 days, and temporary files a writer abandoned more than an hour
+* ago.
+*
+* Only regular files directly inside the directory are considered, and no
+* link is followed: a link, a subdirectory, or a `.js` file that does not
+* start like an entry is left alone, whatever its age. A file that cannot be
+* judged or deleted, such as one another process deleted first, is logged at
+* debug level and skipped.
+*
+* @param directory - The transform cache directory
+* @param now - The current time in milliseconds (default: `Date.now()`)
+* @example
+* ```ts
+* pruneTransformCache("/app/node_modules/.cache/courier/transform");
+* ```
+*/
+function pruneTransformCache(directory, now = Date.now()) {
+	let entries;
+	try {
+		entries = readdirSync(directory, { withFileTypes: true });
+	} catch (error) {
+		log$4.debug(`Transform cache: cannot list ${directory} to prune it`, error);
+		return;
+	}
+	for (const entry of entries) {
+		const expiry = entry.isFile() ? expiryOf(entry.name) : null;
+		if (expiry === null) continue;
+		const path = join(directory, entry.name);
+		try {
+			if (isExpired(path, expiry, now)) unlinkSync(path);
+		} catch (error) {
+			log$4.debug(`Transform cache: cannot prune ${path}`, error);
+		}
+	}
+}
+// src/config/decode-transform-entry.ts
+const HEADER = new RegExp(`^${TRANSFORM_ENTRY_FORMAT.prefix}${TRANSFORM_ENTRY_FORMAT.version} ([0-9a-f]{64}) (\\d{1,15}) ([0-9a-f]{64})$`);
+const NEWLINE = 10;
+const MAX_HEADER_BYTES = 256;
+function sha256Hex(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+* Read an entry as the answer for the input whose digest is `digest`.
+*
+* @param bytes - The whole entry, as read from disk
+* @param digest - The digest of the input being transformed
+* @returns Its code when the header names that input and the body matches
+*   the header's length and sha256; otherwise why it is not a hit
+* @example
+* ```ts
+* const entry = decodeTransformEntry(readFileSync(path), digest);
+* if (entry.state === "hit") return entry.code;
+* ```
+*/
+function decodeTransformEntry(bytes, digest) {
+	const end = bytes.subarray(0, MAX_HEADER_BYTES).indexOf(NEWLINE);
+	if (end === -1) return { state: "stale" };
+	const header = HEADER.exec(bytes.toString("latin1", 0, end));
+	if (header === null || header[1] !== digest) return { state: "stale" };
+	const body = bytes.subarray(end + 1);
+	if (body.length !== Number(header[2]) || sha256Hex(body) !== header[3]) return { state: "damaged" };
+	return {
+		state: "hit",
+		code: body.toString("utf8")
+	};
+}
+// src/config/why-untrusted.ts
+const SHARED_WRITE = 18;
+/**
+* Why a path cannot be trusted to hold only what this user put there, or
+* `null` when it can.
+*
+* A symbolic link can lead anywhere, and something of another kind is not
+* what the caller expects. On POSIX, a path owned by another user, or one the
+* group or others may write, lets someone else place code that this process
+* would then run. Windows has no owner or mode bits of that kind, so only
+* the first two rules apply there.
+*
+* @param stats - The `lstat` of the path, or the `fstat` of a descriptor opened on it
+* @param kind - What the path should be
+* @param options - Whether write permission for the group and others is accepted (default: no)
+* @returns The reason, worded to follow "is", or `null`
+* @example
+* ```ts
+* const reason = whyUntrusted(lstatSync(nodeModules), "directory");
+* if (reason !== null) log.debug(`${nodeModules} is ${reason}`);
+* ```
+*/
+function whyUntrusted(stats, kind, { allowSharedWrite = false } = {}) {
+	if (stats.isSymbolicLink()) return "a symbolic link";
+	if (!(kind === "file" ? stats.isFile() : stats.isDirectory())) return `not a ${kind}`;
+	const uid = process.getuid?.();
+	if (uid === void 0) return null;
+	if (stats.uid !== uid) return `owned by uid ${stats.uid}, not ${uid}`;
+	if (!allowSharedWrite && (stats.mode & SHARED_WRITE) !== 0) return "writable by its group or others";
+	return null;
+}
+// src/config/read-transform-entry.ts
+const log$3 = createLogger("Config");
+const READ_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+const ABSENT_CODES = /* @__PURE__ */ new Set(["ENOENT", "ENOTDIR"]);
+const LINK_CODES = /* @__PURE__ */ new Set(["ELOOP", "EMLINK"]);
+function openEntry(path) {
+	try {
+		return openSync(path, READ_FLAGS);
+	} catch (error) {
+		const code = errnoCode(error);
+		if (code !== void 0 && ABSENT_CODES.has(code)) return null;
+		if (code === void 0 || !LINK_CODES.has(code)) throw error;
+		log$3.debug(`Transform cache: ignoring ${path}, a symbolic link`);
+		return null;
+	}
+}
+function markUsed(fd, path) {
+	try {
+		const now = /* @__PURE__ */ new Date();
+		if (process.platform === "win32") utimesSync(path, now, now);
+		else futimesSync(fd, now, now);
+	} catch (error) {
+		log$3.debug(`Transform cache: cannot mark ${path} as used`, error);
+	}
+}
+function readOpenEntry(fd, path, digest, mark) {
+	const reason = whyUntrusted(fstatSync(fd), "file");
+	if (reason !== null) {
+		log$3.debug(`Transform cache: ignoring ${path}, ${reason}`);
+		return null;
+	}
+	const entry = decodeTransformEntry(readFileSync(fd), digest);
+	if (entry.state === "damaged") log$3.debug(`Transform cache: ignoring ${path}, whose body does not match its header`);
+	if (entry.state !== "hit") return null;
+	if (mark) markUsed(fd, path);
+	return entry.code;
+}
+/**
+* Read the transform of one input from its entry.
+*
+* The entry is read through one descriptor, opened without blocking and, on
+* POSIX, without following a link. It is used only when it is a regular
+* file — on POSIX also owned by this user and writable by no one else — and
+* when it holds exactly that input's transform. A link, another kind of
+* file, an untrusted owner or mode, and a damaged body are logged at debug
+* level; a stale or missing entry is not. On Windows a link is followed, and
+* what it leads to is judged like the entry itself.
+*
+* @param path - The entry's path
+* @param digest - The digest of the input being transformed
+* @param mark - Whether a hit updates the entry's modification time, which
+*   keeps an entry in use from being pruned
+* @returns The kept code, or `null` on a miss
+* @throws The file system's error for anything else, such as `EACCES`
+* @example
+* ```ts
+* const code = readTransformEntry(join(directory, `${name}.js`), digest, true);
+* ```
+*/
+function readTransformEntry(path, digest, mark) {
+	const fd = openEntry(path);
+	if (fd === null) return null;
+	try {
+		return readOpenEntry(fd, path, digest, mark);
+	} finally {
+		closeSync(fd);
+	}
+}
+// src/config/write-transform-entry.ts
+const log$2 = createLogger("Config");
+const PASSING_RENAME_CODES = /* @__PURE__ */ new Set([
+	"EPERM",
+	"EBUSY",
+	"EACCES"
+]);
+function heldOpen(error, path) {
+	const code = errnoCode(error);
+	if (code === void 0 || !PASSING_RENAME_CODES.has(code)) return false;
+	return lstatSync(path, { throwIfNoEntry: false })?.isDirectory() !== true;
+}
+function discard(temporary) {
+	try {
+		unlinkSync(temporary);
+	} catch (error) {
+		log$2.debug(`Transform cache: cannot remove ${temporary}`, error);
+	}
+}
+function writeTemporary(temporary, bytes) {
+	const fd = openSync(temporary, "wx", 384);
+	try {
+		try {
+			writeFileSync(fd, bytes);
+		} finally {
+			closeSync(fd);
+		}
+	} catch (error) {
+		discard(temporary);
+		throw error;
+	}
+}
+/**
+* Replace the entry at `path` with `bytes`, so that a reader sees either the
+* old entry or the whole new one.
+*
+* The bytes go to a temporary file beside the entry, named after it, this
+* process and random bytes, which is then renamed over the entry. On any
+* failure the temporary file is removed. A rename refused because the entry
+* is held open (`EPERM`, `EBUSY` or `EACCES`, while no folder stands in its
+* place) skips this one write, logged at debug level.
+*
+* @param path - The entry's path, in a directory that exists
+* @param bytes - The whole entry
+* @throws The file system's error for any other failure
+* @example
+* ```ts
+* writeTransformEntry(join(directory, `${name}.js`), encodeTransformEntry(digest, code));
+* ```
+*/
+function writeTransformEntry(path, bytes) {
+	const temporary = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+	writeTemporary(temporary, bytes);
+	try {
+		renameSync(temporary, path);
+	} catch (error) {
+		discard(temporary);
+		if (!heldOpen(error, path)) throw error;
+		log$2.debug(`Transform cache: skipped writing ${path} (${errnoCode(error)})`);
+	}
+}
+// src/config/transform-cache-disk.ts
+const log$1 = createLogger("Config");
+const prunedDirectories = /* @__PURE__ */ new Set();
+const markedEntries = /* @__PURE__ */ new Set();
+/**
+* Keep transforms in `directory`, where the next process can read them.
+*
+* Each entry is named after the sha256 of its key and replaced atomically,
+* so a reader sees a whole entry or none. It is read only when it is a
+* regular file — on POSIX also not a symbolic link, owned by this user and
+* writable by no one else — and when its header names the same input and its
+* body the header's length and sha256. Anything else is a miss, and the
+* write that follows replaces it. The first hit on an entry in a process
+* marks it as used, so pruning spares it.
+*
+* The first write of each cache creates the directory with mode 0700; the
+* first write in the process prunes it. A failure is never fatal: a missing
+* entry is a quiet miss; any other read error is logged once and is a miss.
+* A directory removed while the process runs, as by clearing
+* `node_modules/.cache`, is created again at the next write. A rename refused
+* because the entry is held open skips that one write; any other write error
+* is logged once, naming the directory and the code, and stops this cache's
+* writes while reads go on.
+*
+* A `readOnly` one reads entries by the same rules and changes nothing: its
+* writes are dropped, and a hit leaves the entry's time as it was, so the
+* process that keeps the entries alone decides what pruning spares.
+*
+* @param directory - Where entries are kept; see `findTransformCacheDirectory`
+* @param options - Whether the directory is only read (default: no)
+* @returns The directory's reader and writer
+* @example
+* ```ts
+* const disk = createTransformCacheDisk("/app/node_modules/.cache/courier/transform");
+* const code = disk.read(key, digest) ?? transformAndKeep();
+* ```
+*/
+function createTransformCacheDisk(directory, { readOnly = false } = {}) {
+	const root = resolve(directory);
+	let readFailureLogged = false;
+	let created = false;
+	let writable = true;
+	function entryPath(key) {
+		return join(root, `${createHash("sha256").update(key).digest("hex").slice(0, 40)}.js`);
+	}
+	function warn(failure, outcome, error) {
+		const code = errnoCode(error);
+		const message = `Transform cache: cannot ${failure} ${root} (${code ?? "unexpected error"}); ${outcome}`;
+		log$1.warn(message, code === void 0 ? error : void 0);
+	}
+	function stopWriting(error) {
+		writable = false;
+		warn("write to", "this process keeps new transforms in memory only", error);
+	}
+	function create() {
+		mkdirSync(root, {
+			recursive: true,
+			mode: 448
+		});
+		const reason = whyUntrusted(lstatSync(root), "directory");
+		if (reason !== null) {
+			writable = false;
+			log$1.warn(`Transform cache: ${root} is ${reason}; this process keeps new transforms in memory only`);
+			return false;
+		}
+		created = true;
+		if (prunedDirectories.has(root)) return true;
+		prunedDirectories.add(root);
+		pruneTransformCache(root);
+		return true;
+	}
+	function writeEntry(path, bytes) {
+		if (!created && !create()) return;
+		try {
+			writeTransformEntry(path, bytes);
+		} catch (error) {
+			if (errnoCode(error) !== "ENOENT") throw error;
+			if (create()) writeTransformEntry(path, bytes);
+		}
+	}
+	return {
+		read(key, digest) {
+			const path = entryPath(key);
+			const mark = !readOnly && !markedEntries.has(path);
+			try {
+				const code = readTransformEntry(path, digest, mark);
+				if (code !== null && mark) markedEntries.add(path);
+				return code;
+			} catch (error) {
+				if (readFailureLogged) log$1.debug(`Transform cache: cannot read ${path}`, error);
+				else warn("read entries in", "such modules are transformed instead", error);
+				readFailureLogged = true;
+				return null;
+			}
+		},
+		write(key, digest, code) {
+			if (readOnly || !writable || !code.isWellFormed()) return;
+			try {
+				writeEntry(entryPath(key), encodeTransformEntry(digest, code));
+			} catch (error) {
+				stopWriting(error);
+			}
+		}
+	};
+}
+// src/config/transform-digest.ts
+let jitiVersion;
+function hasVersion(manifest) {
+	return typeof manifest === "object" && manifest !== null && "version" in manifest && typeof manifest.version === "string";
+}
+function readJitiVersion() {
+	if (jitiVersion !== void 0) return jitiVersion;
+	const manifest = createRequire(import.meta.url)("jiti/package.json");
+	if (!hasVersion(manifest)) throw new Error("jiti/package.json names no version");
+	jitiVersion = manifest.version;
+	return jitiVersion;
+}
+function isPlainData(value) {
+	const prototype = Object.getPrototypeOf(value);
+	if (Array.isArray(value)) return prototype === Array.prototype;
+	return prototype === Object.prototype || prototype === null;
+}
+function describe(value, open) {
+	if (value === void 0) return "u";
+	if (value === null) return "n";
+	if (typeof value === "boolean") return value ? "t" : "f";
+	if (typeof value === "number") return Object.is(value, -0) ? "#-0" : `#${value}`;
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value !== "object" || open.has(value) || !isPlainData(value)) return null;
+	open.add(value);
+	const entries = [];
+	const fields = Object.entries(value);
+	for (const [key, item] of fields) {
+		const described = describe(item, open);
+		if (described === null) return null;
+		entries.push(`${JSON.stringify(key)}:${described}`);
+	}
+	open.delete(value);
+	const [start, end] = Array.isArray(value) ? ["[", "]"] : ["{", "}"];
+	return `${start}${entries.join(",")}${end}`;
+}
+/**
+* The digest of everything that shapes jiti's transform of a module: jiti's
+* version, every option but the source, and the source.
+*
+* Two inputs share a digest only when every option is alike and the source is
+* the same string, code unit for code unit, so a source that is not
+* well-formed UTF-16 is not confused with the text it would decode to. An
+* option whose value cannot be told apart from another — a babel plugin given
+* as a function, a RegExp, a cycle — yields no digest.
+*
+* @param options - What jiti hands its transform
+* @returns A hex sha256, or `null` when an option holds such a value
+* @example
+* ```ts
+* const digest = transformDigest({ filename: "/app/courier.config.ts", source, ts: true });
+* ```
+*/
+function transformDigest({ source, ...rest }) {
+	const described = describe({
+		...rest,
+		async: rest.async === true
+	}, /* @__PURE__ */ new Set());
+	if (described === null) return null;
+	return createHash("sha256").update(`${readJitiVersion()}\0${described}\0`).update(source, "utf16le").digest("hex");
+}
+// src/config/transform-cache.ts
+const DEFAULT_MAX_MEMORY_CHARS = 128 * 2 ** 20;
+function keyOf({ filename, async }) {
+	if (filename === void 0 || !isAbsolute(filename)) return null;
+	return `${async === true}\0${filename}`;
+}
+/**
+* Create a {@link TransformCache} that keeps transforms in memory for the
+* life of the process and, given a `directory`, on disk for the next one.
+*
+* Each file holds one entry per module system — required and imported are
+* transformed differently, and a module reached both ways keeps both. An
+* entry is reused only when the digest of jiti's version, the options and
+* the source matches, so an edited file is transformed again the first time
+* it is loaded.
+*
+* A transform is looked for in memory, then in the directory, where a hit
+* is also kept in memory; only when both miss is it computed, and a success
+* is then kept in both. The directory is shared with every process that
+* names it, and a directory that cannot be read or written only costs
+* transforms; see `createTransformCacheDisk` for what an entry must be to be
+* used. A mock worker, which loads once the modules Studio has just loaded,
+* opens Studio's directory `readOnly` with `maxMemoryChars: 0`: it reads
+* what Studio kept, adds nothing to the directory, and holds nothing in
+* memory past its one load.
+*
+* A failed transform, one whose result carries an `error`, is never kept:
+* babel can fail on bytes it transforms without complaint a moment later,
+* such as a deeply nested module that overflows the stack while babel is
+* still cold. Such a file is transformed again on every load, and every
+* failure reaches jiti with its error, as it does without a cache. A file
+* named by a relative path, or not named, is transformed every time.
+*
+* @param options - The directory (default: none, memory only), the memory
+*   bound (default: 128 Mi characters), and whether the directory is only
+*   read (default: no)
+* @returns A cache to pass to `createConfigJiti` or `loadCourierConfig`
+* @example
+* ```ts
+* const transformCache = createTransformCache({
+*   directory: findTransformCacheDirectory(projectRoot),
+* });
+* const first = await loadCourierConfig({ cwd: projectRoot, transformCache });
+* // Unchanged modules are not transformed again, here or in the next process:
+* const second = await loadCourierConfig({ cwd: projectRoot, transformCache });
+*
+* // A process that loads once what another has just kept:
+* const reader = createTransformCache({ directory, readOnly: true, maxMemoryChars: 0 });
+* ```
+*/
+function createTransformCache({ directory, maxMemoryChars = DEFAULT_MAX_MEMORY_CHARS, readOnly = false } = {}) {
+	const disk = directory ? createTransformCacheDisk(directory, { readOnly }) : null;
+	const memo = /* @__PURE__ */ new Map();
+	let memoryChars = 0;
+	function forget(key) {
+		const entry = memo.get(key);
+		if (!entry) return;
+		memo.delete(key);
+		memoryChars -= entry.code.length;
+	}
+	function remember(key, entry) {
+		forget(key);
+		if (maxMemoryChars <= 0 || entry.code.length > maxMemoryChars) return;
+		memo.set(key, entry);
+		memoryChars += entry.code.length;
+		for (const oldest of memo.keys()) {
+			if (memoryChars <= maxMemoryChars) break;
+			forget(oldest);
+		}
+	}
+	return { transform(options, compute) {
+		const key = keyOf(options);
+		const digest = key === null ? null : transformDigest(options);
+		if (key === null || digest === null) return compute(options);
+		const hit = memo.get(key);
+		if (hit?.digest === digest) {
+			memo.delete(key);
+			memo.set(key, hit);
+			return { code: hit.code };
+		}
+		const kept = disk === null ? null : disk.read(key, digest);
+		if (kept !== null) {
+			remember(key, {
+				digest,
+				code: kept
+			});
+			return { code: kept };
+		}
+		const result = compute(options);
+		if (result.error !== void 0) return result;
+		remember(key, {
+			digest,
+			code: result.code
+		});
+		disk?.write(key, digest, result.code);
+		return result;
+	} };
+}
+// src/config/transform-cache-directory.ts
+const log = createLogger("Config");
+/** Values of `COURIER_TRANSFORM_CACHE` that turn the directory off. */
+const OFF_VALUES = /* @__PURE__ */ new Set([
+	"0",
+	"false",
+	"off"
+]);
+/** Values of `COURIER_TRANSFORM_CACHE` that keep it, as leaving it unset does. */
+const ON_VALUES = /* @__PURE__ */ new Set([
+	"",
+	"1",
+	"true",
+	"on"
+]);
+const unknownSettings = /* @__PURE__ */ new Set();
+function nearestNodeModules(start) {
+	let directory = start;
+	while (true) {
+		const candidate = join(directory, "node_modules");
+		const stats = lstatSync(candidate, { throwIfNoEntry: false });
+		if (stats?.isDirectory() || stats?.isSymbolicLink()) return candidate;
+		const parent = dirname(directory);
+		if (parent === directory) return null;
+		directory = parent;
+	}
+}
+function whyRefused(levels) {
+	for (const [path, options] of levels) {
+		const stats = lstatSync(path, { throwIfNoEntry: false });
+		const reason = stats === void 0 ? null : whyUntrusted(stats, "directory", options);
+		if (reason !== null) return `${path} is ${reason}`;
+	}
+	return null;
+}
+const TOOL_OWNED = { allowSharedWrite: true };
+const STUDIO_OWNED = {};
+const lastRefusals = /* @__PURE__ */ new Map();
+function refuse(root, reason, error) {
+	const key = error instanceof Error ? `${reason}\0${error.message}` : reason;
+	if (lastRefusals.get(root) === key) return null;
+	lastRefusals.set(root, key);
+	if (error === void 0) log.debug(`Transform cache directory off: ${reason}`);
+	else log.debug(`Transform cache directory off: ${reason}`, error);
+	return null;
+}
+function locate(projectRoot) {
+	const nodeModules = nearestNodeModules(projectRoot);
+	if (nodeModules === null) return { refusal: `no node_modules at or above ${projectRoot}` };
+	const cache = join(nodeModules, ".cache");
+	const courier = join(cache, "courier");
+	const directory = join(courier, "transform");
+	const refusal = whyRefused([
+		[nodeModules, TOOL_OWNED],
+		[cache, TOOL_OWNED],
+		[courier, STUDIO_OWNED],
+		[directory, STUDIO_OWNED]
+	]);
+	return refusal === null ? { directory } : { refusal };
+}
+/**
+* Where a project's transforms are kept across processes:
+* `.cache/courier/transform` in the nearest `node_modules` directory at or
+* above the project root.
+*
+* The nearest one is taken, not the one module resolution would reach: under
+* pnpm that lies inside `.pnpm`, and what keeps the directory safe is the
+* rule below, not where it is. Every file in it holds code that Studio, mock
+* workers and build plugins run, so on POSIX the directory is refused when
+* `node_modules`, `.cache`, `courier` or `transform` — those that exist — is
+* a symbolic link or belongs to another user, and when `courier` or
+* `transform`, which only Studio creates, is writable by its group or
+* others; any of these lets someone else replace or remove entries, or put
+* the directory somewhere they control. `node_modules` and `.cache` may be
+* group-writable, as package managers leave them under a umask of 002:
+* whoever can write `node_modules` can replace any package in it already. On
+* Windows only links and other kinds of file are refused.
+*
+* There is none when no `node_modules` exists, as with Yarn Plug'n'Play, or
+* when `COURIER_TRANSFORM_CACHE` is `0`, `false` or `off` in any case. The
+* system temporary directory, which every user of the machine may write, is
+* never used instead. Why there is none is logged at debug level, once for
+* each root until the reason changes, however often the root is looked up.
+*
+* @param projectRoot - The directory holding `courier.config.*`
+* @param env - The environment to read `COURIER_TRANSFORM_CACHE` from
+*   (default: `process.env`)
+* @returns The directory, which may not exist yet, or `null` for none
+* @example
+* ```ts
+* const transformCache = createTransformCache({
+*   directory: findTransformCacheDirectory(projectRoot),
+* });
+* ```
+*/
+function findTransformCacheDirectory(projectRoot, env = process.env) {
+	const root = resolve(projectRoot);
+	const setting = env.COURIER_TRANSFORM_CACHE?.trim().toLowerCase();
+	if (setting !== void 0 && OFF_VALUES.has(setting)) return refuse(root, `COURIER_TRANSFORM_CACHE=${setting}`);
+	if (setting !== void 0 && !ON_VALUES.has(setting) && !unknownSettings.has(setting)) {
+		unknownSettings.add(setting);
+		log.warn(`COURIER_TRANSFORM_CACHE=${setting} is not one of 0, false, off, 1, true or on; the transform cache stays on`);
+	}
+	let located;
+	try {
+		located = locate(root);
+	} catch (error) {
+		return refuse(root, `cannot inspect the directories above ${root}`, error);
+	}
+	if (located.refusal !== void 0) return refuse(root, located.refusal);
+	lastRefusals.delete(root);
+	return located.directory;
+}
+// src/config/load-config.ts
+/**
+* Unified `courier.config.{ts,mts,cts,js,mjs,cjs}` loader — the single
+* canonical way to resolve and load a user's config file.
+*
+* Two-stage design:
+*
+*  1. **File discovery** — walk up from `cwd` to the top of the project
+*     looking for a `courier.config.*` file, using nothing but Node builtins.
+*
+*  2. **File loading** — `jiti` imports the file, transpiling a TypeScript
+*     config transparently across Node / Next.js dev / tsx / bun / deno and
+*     resolving the project's `tsconfig` path aliases.
+*
+* Every consumer resolves the config through this one code path:
+*
+*  - The Studio dev server (`@noverax/courier-studio`) wraps this loader and
+*    adds dev-only concerns on top (validation, source-key stamping,
+*    dependency extraction for the fs watcher, rich error reporting).
+*
+*  - The user-app runtime (`attachRuntime` on the server side) calls it
+*    directly to discover and register sources without requiring the user
+*    to import the config file manually.
+*
+*  - `courier-cli`, the standalone server and the MCP server load the
+*    project's config with it, and the bundler plugins read a page's routes
+*    from the config it loads.
+*
+* A missing config is not an error: `null` lets the runtime caller fall back
+* to adapter auto-discovery. A config that exists and cannot be loaded is a
+* different thing entirely and throws, because reporting it as "no config"
+* sends the reader looking for a file that is right where they left it.
+*/
+/**
+* Walk up from `startDir` looking for a `courier.config.*` file, up to the
+* top of the project: the folder that holds its repository or is the root
+* of its workspace (see {@link configCandidates}). A config found in a folder
+* above `startDir` is taken only when it belongs to this user or to the
+* owner of `startDir`, and no user outside its group may write it: a folder
+* many users share, such as `/tmp`, would otherwise run anyone's config.
+*
+* @param startDir - The directory to look in first
+* @returns The absolute path of the first match, or `null` when no directory
+*   up to the top of the project holds one
+* @throws UntrustedConfigError when the nearest config lies above `startDir`
+*   and someone else could have put it there
+* @example
+* ```ts
+* findConfigFile("/app/src"); // → "/app/courier.config.ts", or null
+* ```
+*/
+function findConfigFile(startDir) {
+	const folder = resolve(startDir);
+	const found = configCandidates(folder).find((candidate) => existsSync(candidate));
+	if (found === void 0) return null;
+	if (dirname(found) !== folder) assertOwnConfig(found, folder);
+	return found;
+}
+/**
+* Find a config file in `cwd` itself, without walking up.
+*
+* @param cwd - The directory to look in
+* @returns The first of {@link CONFIG_BASENAMES} present there, or `null`
+* @example
+* ```ts
+* findConfigFileAt(process.cwd()); // → "/app/courier.config.ts", or null
+* ```
+*/
+function findConfigFileAt(cwd) {
+	for (const basename of CONFIG_BASENAMES) {
+		const candidate = resolve(cwd, basename);
+		if (existsSync(candidate)) return candidate;
+	}
+	return null;
+}
+/**
+* Find and load a `courier.config.*` file.
+*
+* Returns `null` when no config file exists, so a caller can fall back.
+* Throws when a file was found and loading it failed, reporting what the
+* loader reported — for a TypeScript config, usually an unresolvable import.
+*
+* @param options - Where to look, and where to reuse transforms
+* @returns The config and its canonical path, or `null` when there is no config
+* @example
+* ```ts
+* const loaded = await loadCourierConfig({ cwd: projectRoot, requireAtCwd: true });
+* ```
+*/
+async function loadCourierConfig(options = {}) {
+	const startDir = resolve(options.cwd ?? process.cwd());
+	const found = options.requireAtCwd ? findConfigFileAt(startDir) : findConfigFile(startDir);
+	if (!found) return null;
+	return loadCourierConfigFile(found, {
+		transformCache: options.transformCache ?? (options.projectTransforms === true ? projectTransformCache(dirname(found)) : void 0),
+		onModule: options.onModule
+	});
+}
+/**
+* The transforms kept in a project's `node_modules/.cache` — the ones Studio
+* keeps — for a process that loads the project's modules once: it reuses
+* them, keeps there the ones it makes, and holds none in memory.
+*
+* @param projectRoot - The project's root
+* @returns The cache, or `undefined` when the project has no directory to keep them in
+* @example
+* ```ts
+* await loadCourierConfigFile(file, { transformCache: projectTransformCache(dirname(file)) });
+* ```
+*/
+function projectTransformCache(projectRoot) {
+	const directory = findTransformCacheDirectory(projectRoot);
+	return directory === null ? void 0 : createTransformCache({
+		directory,
+		maxMemoryChars: 0
+	});
+}
+/**
+* Load one config file, found by whatever means the caller chose — the
+* standalone server takes it from `--config`.
+*
+* @param file - Absolute path of an existing config file
+* @param options - How the loader resolves imports and where it reuses
+*   transforms, see {@link ConfigJitiOptions}, and what runs before the config
+* @returns The config and the canonical path it was loaded from
+* @throws What the loader reported when the file will not load — for a
+*   TypeScript config, usually an unresolvable import
+* @example
+* ```ts
+* const { config } = await loadCourierConfigFile("/app/courier.config.ts", {
+*   transformCache: createTransformCache(),
+* });
+* ```
+*/
+async function loadCourierConfigFile(file, { beforeRun, ...options } = {}) {
+	const configFile = realpathSync(file);
+	const jiti = await createConfigJiti(configFile, options);
+	beforeRun?.();
+	return {
+		config: await jiti.import(configFile, { default: true }),
+		configFile
+	};
+}
+export { projectTransformCache as a, UntrustedConfigError as c, CONFIG_BASENAMES as d, configCandidates as f, loadCourierConfigFile as i, createConfigJiti as l, findConfigFileAt as n, findTransformCacheDirectory as o, loadCourierConfig as r, createTransformCache as s, findConfigFile as t, readPathAliases as u };