@pithy-sh/core 0.9.0 → 0.10.0

package/dist/error/unresolved.js

@@ -0,0 +1,599 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { causeMessage, prop, rootCause } from "./cause.js";
+import { packageOf } from "../naming/packageName.js";
+//#region src/error/unresolved.ts
+/**
+* The {@link InstalledProbe} a surface on Node or Bun passes: `pkg` on the `node_modules` chain above
+* `referrer`, **walked from where `referrer` really is**.
+*
+* Both runtimes resolve from the real path of the importing file, and Bun's isolated linker puts every
+* package behind a symlink into its store, with that package's own dependencies beside the real
+* directory and not beside the link. Walked from the link, the chain is the root's — a different copy,
+* or none — so a dependency the resolver could see was reported absent, and the adopter told to install
+* what was installed. A `referrer` that will not resolve is walked as given.
+*
+* Core has no filesystem, so the two calls are the caller's. The walk is here, once.
+*/
+function nodeModulesProbe(fs) {
+	return (pkg, referrer) => installedAt(fs, pkg, referrer) !== void 0;
+}
+/**
+* The {@link EntryProbe} a surface on Node or Bun passes: the same walk as {@link nodeModulesProbe}, then
+* the package's own `package.json`, and `exists` for the paths beside it.
+*/
+function packageEntryProbe(fs) {
+	return (pkg, from) => {
+		const dir = installedAt(fs, pkg, from);
+		if (dir === void 0) return void 0;
+		let manifest;
+		try {
+			manifest = JSON.parse(fs.read(`${dir}/package.json`));
+		} catch {
+			return;
+		}
+		return {
+			manifest,
+			has: (path) => fs.exists(path === "" ? dir : `${dir}/${path}`)
+		};
+	};
+}
+/** The entry an installed `pkg` declares, through the probe: `undefined` when there is no probe or no package. */
+function declaredBy(options, pkg, from) {
+	const installed = options.entry?.(pkg, from);
+	return installed === void 0 ? void 0 : declaredEntry(installed.manifest);
+}
+/** The directory `pkg` is installed in on the chain above `referrer`, walked from where it really is. */
+function installedAt(fs, pkg, referrer) {
+	let real = referrer;
+	try {
+		real = fs.realpath(referrer);
+	} catch {}
+	let dir = parentOf(real);
+	for (;;) {
+		const at = `${dir.replace(/[\\/]+$/, "")}/node_modules/${pkg}`;
+		if (fs.exists(`${at}/package.json`)) return at;
+		const up = parentOf(dir);
+		if (up === dir) return void 0;
+		dir = up;
+	}
+}
+/** The conditions an ESM import of a package matches, on Node and on Vite's runner. */
+const IMPORT_CONDITIONS = /* @__PURE__ */ new Set([
+	"import",
+	"node",
+	"module-sync",
+	"default"
+]);
+/**
+* The entry a manifest declares for an `import` of the package's bare name, or `null` for none. `exports`
+* wins when present — its `"."`, or the whole map when no key is a subpath — and a target is the first
+* one whose condition an import matches. With no `exports`, it is `main`.
+*/
+function declaredEntry(manifest) {
+	const exports = prop(manifest, "exports");
+	if (exports !== void 0 && exports !== null) return importTarget(subpathMap(exports)["."]);
+	const main = prop(manifest, "main");
+	return typeof main === "string" && main.length > 0 ? inside(main) : null;
+}
+/** An `exports` field as its subpath map: a target or a map of conditions alone is the package's `"."`. */
+function subpathMap(exports) {
+	return typeof exports === "object" && exports !== null && !Array.isArray(exports) && Object.keys(exports).some((key) => key.startsWith(".")) ? exports : { ".": exports };
+}
+/**
+* What an import of `subpath` (`"."`, `"./src/capability"`) takes from a manifest's `exports`, as Node and
+* Vite resolve it: an exact key first, then the pattern with the longest prefix, each target followed
+* through the conditions an import matches. `null` when the map does not export it — no key, no pattern,
+* or a `null` target — and `undefined` when the manifest has no `exports`, so the subpath is a file path.
+*/
+function exportedTarget(manifest, subpath) {
+	const exports = prop(manifest, "exports");
+	if (exports === void 0 || exports === null) return void 0;
+	const map = subpathMap(exports);
+	if (Object.hasOwn(map, subpath) && !subpath.includes("*")) {
+		const target = importTarget(map[subpath]);
+		return target === null ? null : { target };
+	}
+	let best;
+	for (const key of Object.keys(map)) {
+		const at = key.indexOf("*");
+		if (at === -1 || key.indexOf("*", at + 1) !== -1) continue;
+		const prefix = key.slice(0, at);
+		const suffix = key.slice(at + 1);
+		if (!subpath.startsWith(prefix) || subpath === prefix) continue;
+		if (!subpath.endsWith(suffix) || subpath.length < key.length) continue;
+		if (best !== void 0) {
+			const held = best.key.indexOf("*");
+			if (at < held || at === held && key.length <= best.key.length) continue;
+		}
+		best = {
+			key,
+			star: subpath.slice(prefix.length, subpath.length - suffix.length)
+		};
+	}
+	if (best === void 0) return null;
+	const pattern = importTarget(map[best.key]);
+	if (pattern === null) return null;
+	return {
+		target: pattern.replaceAll("*", best.star),
+		under: patternBase(pattern)
+	};
+}
+/**
+* The import that reaches `file` — a path inside the package, the one Node reports — through `exports`:
+* the key that maps to it, or the pattern whose `*` it fills. Only an answer that resolves back to `file`
+* through {@link exportedTarget} counts, so a pattern a longer one shadows never names the import.
+*/
+function exportedSubpath(manifest, file) {
+	const exports = prop(manifest, "exports");
+	if (exports === void 0 || exports === null) return void 0;
+	for (const [key, value] of Object.entries(subpathMap(exports))) {
+		const target = importTarget(value);
+		if (target === null) continue;
+		let subpath;
+		const at = target.indexOf("*");
+		if (!key.includes("*")) subpath = target === file ? key : void 0;
+		else if (at !== -1) {
+			const prefix = target.slice(0, at);
+			const suffix = target.slice(at + 1).split("*")[0] ?? "";
+			if (file.startsWith(prefix) && file.endsWith(suffix) && file.length > prefix.length + suffix.length) subpath = key.replace("*", file.slice(prefix.length, file.length - suffix.length));
+		}
+		const back = subpath === void 0 ? void 0 : exportedTarget(manifest, subpath);
+		if (subpath !== void 0 && back?.target === file) return {
+			...back,
+			subpath
+		};
+	}
+}
+/** The directory inside the package a pattern target's `*` expands under: `dist/*.js` → `dist`. */
+function patternBase(pattern) {
+	const head = pattern.slice(0, pattern.indexOf("*"));
+	return head.slice(0, Math.max(head.lastIndexOf("/"), 0));
+}
+/**
+* **A target the manifest declares and the disk does not have: the package unbuilt, or the import mistyped.**
+*
+* A key of its own is the package's word that the file exists, so its absence is the package's — unbuilt,
+* or a broken install. A pattern says nothing of the sort: `./src/*` matches `./src/capabilty` as readily as
+* `./src/capability`. What tells them apart is the directory the pattern expands under. With `dist` absent
+* the package was never built, and every import of it fails the same way whatever was typed; with `dist`
+* there, the build ran and this file is not in it, so the import names a path the package does not have.
+* A file deleted from a built `dist` reads as the second, and its remedy — check the version you have —
+* still leads to a reinstall.
+*/
+function exportedKind(found, installed) {
+	if (found.under === void 0) return "package-entry";
+	return installed.has(found.under) ? "package-subpath" : "package-entry";
+}
+/** One `exports` target, followed through conditions and fallbacks to the path an import takes. */
+function importTarget(target) {
+	if (typeof target === "string") return inside(target);
+	if (Array.isArray(target)) {
+		for (const option of target) {
+			const found = importTarget(option);
+			if (found !== null) return found;
+		}
+		return null;
+	}
+	if (typeof target !== "object" || target === null) return null;
+	for (const [condition, value] of Object.entries(target)) {
+		if (!IMPORT_CONDITIONS.has(condition)) continue;
+		const found = importTarget(value);
+		if (found !== null) return found;
+	}
+	return null;
+}
+/** A manifest's path, as a path inside the package: no `./`, no trailing slash. */
+function inside(path) {
+	return path.replace(/^\.\//, "").replace(/\/+$/, "");
+}
+/** Every code a runtime throws for a module it could not find, or would not load as a module. */
+const CODES = /* @__PURE__ */ new Set([
+	"ERR_MODULE_NOT_FOUND",
+	"MODULE_NOT_FOUND",
+	"ERR_PACKAGE_PATH_NOT_EXPORTED",
+	"ERR_PACKAGE_IMPORT_NOT_DEFINED",
+	"ERR_UNSUPPORTED_DIR_IMPORT",
+	"ERR_UNKNOWN_BUILTIN_MODULE",
+	"ERR_UNSUPPORTED_ESM_URL_SCHEME",
+	"ERR_RESOLVE_PACKAGE_ENTRY_FAIL"
+]);
+/** The same, said in prose by something that sets no code: Vite's module runner, and older loaders. */
+const SENTENCE = /Cannot find (?:package|module) |Failed to resolve (?:import|module)|Failed to load url |No such built-in module: |is not defined by "exports"|No "exports" main defined in |Package import specifier |is not exported under the conditions |Failed to resolve entry for package /;
+/**
+* Classify an import that would not resolve, or answer `undefined` when `cause` is not one.
+*
+* Read duck-typed, for `prop`'s reason in `cause.ts`, and through Bun's `AggregateError` wrapper, for
+* `rootCause`'s.
+*/
+function unresolvedImport(wrapped, options = {}) {
+	const cause = rootCause(wrapped);
+	if (!isUnresolved(cause)) return void 0;
+	const referrer = importerPath(cause);
+	const owner = ownerOf(referrer, options.loader);
+	const found = locate(cause, referrer, options);
+	const installHelps = found.kind === "package" || found.kind === "undetermined" || found.kind === "unnamed";
+	return {
+		...found,
+		...owner === void 0 ? {} : { owner },
+		installHelps,
+		remedy: remedy(found, owner)
+	};
+}
+/**
+* The package whose own source holds the import that did not resolve — **never a path**.
+*
+* #480 is why: `pithy add email` refused with *Nothing resolves "@pithy-sh/core/src/capability/capability"*
+* while core resolved throughout, because the import was `@pithy-sh/email`'s and email was the package
+* not linked. The importer is the half that points there. The **last** `node_modules` in the path wins,
+* because every store nests (pnpm's `.pnpm/<id>/node_modules/<pkg>`, Bun's `.bun/<pkg>@<v>/node_modules/<pkg>`),
+* and the name is held to what npm allows, so a store's bookkeeping directory answers nothing.
+*/
+function importingPackage(cause) {
+	return ownerOf(importerPath(cause), void 0);
+}
+function isUnresolved(cause) {
+	if (typeof cause !== "object" || cause === null) return false;
+	const code = prop(cause, "code");
+	if (typeof code === "string" && CODES.has(code)) return true;
+	if (prop(cause, "name") === "ResolveMessage") return true;
+	return SENTENCE.test(causeMessage(cause) ?? "");
+}
+/** A specifier that opens with a URL scheme: `node:`, `bun:`, `data:`. A Windows drive letter is one letter. */
+const URL_SCHEME = /^[a-z][a-z0-9+.-]+:/i;
+/** An absolute path: POSIX, a Windows drive, or a UNC share. */
+const ABSOLUTE = /^(?:\/|\\\\|[A-Za-z]:[\\/])/;
+function locate(cause, referrer, options) {
+	const code = prop(cause, "code");
+	const message = causeMessage(cause) ?? "";
+	if (code === "ERR_UNSUPPORTED_ESM_URL_SCHEME") {
+		const scheme = /Received protocol '([a-z][a-z0-9+.-]*:)'/i.exec(message)?.[1];
+		return scheme === void 0 ? { kind: "builtin" } : {
+			kind: "builtin",
+			shown: scheme
+		};
+	}
+	if (code === "ERR_PACKAGE_PATH_NOT_EXPORTED" || /is not defined by "exports"|No "exports" main defined in |is not exported under the conditions /.test(message)) return unexported(cause, message);
+	const unloadable = /Failed to resolve entry for package "([^"]+)"/.exec(message)?.[1];
+	if (unloadable !== void 0) {
+		const from = referrer ?? (options.relativeTo === void 0 ? void 0 : `${options.relativeTo}/package.json`);
+		return {
+			kind: (from === void 0 ? void 0 : declaredBy(options, unloadable, from)) === null ? "package-subpath" : "package-entry",
+			package: unloadable,
+			shown: unloadable
+		};
+	}
+	const specifier = writtenSpecifier(cause, message);
+	if (specifier === void 0) return { kind: "unnamed" };
+	if (code === "ERR_UNKNOWN_BUILTIN_MODULE") return {
+		kind: "builtin",
+		shown: specifier
+	};
+	if (specifier.startsWith("#")) return {
+		kind: "imports-map",
+		shown: specifier
+	};
+	if (specifier.startsWith("file:")) return atPath(urlPath(specifier), referrer, options);
+	if (URL_SCHEME.test(specifier)) return {
+		kind: "builtin",
+		shown: specifier
+	};
+	const url = prop(cause, "url");
+	if (typeof url === "string" && url.startsWith("file:")) return atPath(urlPath(url), referrer, options);
+	if (specifier.startsWith(".")) {
+		if (referrer === void 0) return {
+			kind: "local-file",
+			shown: specifier
+		};
+		return atPath(joinPath(parentOf(referrer), specifier), referrer, options, specifier);
+	}
+	if (ABSOLUTE.test(specifier)) {
+		const entry = /^Cannot find package '/.test(message) ? packageAt(specifier) : void 0;
+		if (entry !== void 0) return {
+			kind: declaredBy(options, entry.name, `${entry.dir}/package.json`) === null ? "package-subpath" : "package-entry",
+			package: entry.name,
+			shown: entry.name
+		};
+		return atPath(specifier, referrer, options);
+	}
+	const pkg = packageOf(specifier);
+	const bare = pkg === specifier;
+	if (options.installed === void 0 || referrer === void 0) return bare ? {
+		kind: "package",
+		package: pkg,
+		shown: pkg
+	} : {
+		kind: "undetermined",
+		package: pkg,
+		shown: specifier
+	};
+	if (!options.installed(pkg, referrer)) return {
+		kind: "package",
+		package: pkg,
+		shown: pkg
+	};
+	const installed = options.entry?.(pkg, referrer);
+	if (bare) return typeof (installed === void 0 ? void 0 : declaredEntry(installed.manifest)) === "string" ? {
+		kind: "package-entry",
+		package: pkg,
+		shown: pkg
+	} : {
+		kind: "package-subpath",
+		package: pkg,
+		shown: specifier
+	};
+	const exported = installed === void 0 ? void 0 : exportedTarget(installed.manifest, `./${specifier.slice(pkg.length + 1)}`);
+	return installed !== void 0 && exported !== void 0 && exported !== null ? {
+		kind: exportedKind(exported, installed),
+		package: pkg,
+		shown: specifier
+	} : {
+		kind: "package-subpath",
+		package: pkg,
+		shown: specifier
+	};
+}
+/**
+* An installed package that does not export the path. The loader's field is the import as written where
+* there is one; Node's sentence names the subpath and the package's `package.json`, from which the
+* package — never the path — is taken. An `exports` map with no `"."` is the bare name unexported, and
+* Node's sentence for it names only the `package.json`.
+*/
+function unexported(cause, message) {
+	const field = prop(cause, "specifier");
+	if (typeof field === "string" && field.length > 0 && !ABSOLUTE.test(field) && !field.startsWith(".")) return {
+		kind: "package-subpath",
+		package: packageOf(field),
+		shown: field
+	};
+	const main = /No "exports" main defined in (.+?)[\\/]package\.json/.exec(message)?.[1];
+	const entry = main === void 0 ? void 0 : packageAt(`${main}/package.json`);
+	if (entry !== void 0) return {
+		kind: "package-subpath",
+		package: entry.name,
+		shown: entry.name
+	};
+	const match = /Package subpath '([^']+)' is not defined by "exports" in (.+?)[\\/]package\.json/.exec(message) ?? /"([^"]+)" is not exported under the conditions \[[^\]]*\] from package (.+?) \(see exports field/.exec(message);
+	const at = match?.[2] === void 0 ? void 0 : packageAt(`${match[2]}/package.json`);
+	if (match?.[1] === void 0 || at === void 0) return { kind: "package-subpath" };
+	const subpath = match[1].replace(/^\.\/?/, "");
+	return {
+		kind: "package-subpath",
+		package: at.name,
+		shown: subpath === "" ? at.name : `${at.name}/${subpath}`
+	};
+}
+/**
+* A path that did not resolve, from either runtime: inside an installed package, or in the adopter's tree.
+*
+* Inside a package, it is that package's own missing file when the import was written in the same package,
+* and a path the package does not have when anything else asked for it. In the adopter's tree, it is shown
+* relative to the project, or as the relative import it was written as, or not at all.
+*/
+function atPath(path, referrer, options, written) {
+	const inPackage = packageAt(path);
+	if (inPackage !== void 0) {
+		const shown = inPackage.rest === "" ? inPackage.name : `${inPackage.name}/${inPackage.rest}`;
+		if (referrer !== void 0 && packageAt(referrer)?.name === inPackage.name) return {
+			kind: "package-file",
+			package: inPackage.name,
+			shown
+		};
+		const installed = options.entry?.(inPackage.name, `${inPackage.dir}/package.json`);
+		const declared = installed === void 0 ? void 0 : declaredEntry(installed.manifest);
+		if (typeof declared === "string" && isEntry(inPackage.rest, declared)) return {
+			kind: "package-entry",
+			package: inPackage.name,
+			shown: inPackage.name
+		};
+		const written = installed === void 0 ? void 0 : exportedSubpath(installed.manifest, inPackage.rest);
+		if (installed !== void 0 && written !== void 0) {
+			const subpath = written.subpath.replace(/^\.\/?/, "");
+			const as = subpath === "" ? inPackage.name : `${inPackage.name}/${subpath}`;
+			return {
+				kind: exportedKind(written, installed),
+				package: inPackage.name,
+				shown: as
+			};
+		}
+		return {
+			kind: "package-subpath",
+			package: inPackage.name,
+			shown
+		};
+	}
+	const { relativeTo } = options;
+	const shown = (relativeTo === void 0 ? void 0 : within(path, relativeTo)) ?? written;
+	return shown === void 0 ? { kind: "local-file" } : {
+		kind: "local-file",
+		shown
+	};
+}
+/** A package name as npm allows one: an optional `@scope/`, and never a store's dot-directory. */
+const PACKAGE_NAME = /^(?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i;
+/**
+* The package a path sits in, by the last `node_modules` in it: its name, its directory, and the path
+* inside it. The directory is for reading its manifest and never leaves this module.
+*/
+function packageAt(path) {
+	const segments = path.split(/[\\/]/);
+	const at = segments.lastIndexOf("node_modules");
+	if (at === -1) return void 0;
+	const tail = segments.slice(at + 1);
+	const name = packageOf(tail.join("/"));
+	if (!PACKAGE_NAME.test(name)) return void 0;
+	const depth = name.split("/").length;
+	return {
+		name,
+		dir: segments.slice(0, at + 1 + depth).join("/"),
+		rest: tail.slice(depth).join("/")
+	};
+}
+/**
+* Whether a path inside a package is the entry it declares, or that entry with the `.js` or `/index.js` a
+* `main` is tried with. Exact, so a deep import beneath a directory `main` is never read as the entry.
+*/
+function isEntry(rest, declared) {
+	return rest === declared || rest === `${declared}.js` || rest === `${declared}/index.js`;
+}
+/** The importing package, unless it is the loader's own frame. */
+function ownerOf(referrer, loader) {
+	const name = referrer === void 0 ? void 0 : packageAt(referrer)?.name;
+	return name === loader ? void 0 : name;
+}
+/** `path` as `./…` beneath `root`, or `undefined` when it is not beneath it. Separators are shown as `/`. */
+function within(path, root) {
+	const target = path.replaceAll("\\", "/");
+	const base = root.replaceAll("\\", "/").replace(/\/+$/, "");
+	if (target === base) return ".";
+	return target.startsWith(`${base}/`) ? `./${target.slice(base.length + 1)}` : void 0;
+}
+/** The directory a path is in. A root is its own parent, which is what ends a walk. */
+function parentOf(path) {
+	const trimmed = path.replace(/[\\/]+$/, "");
+	const at = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+	if (at < 0) return path;
+	if (at === 0) return path.slice(0, 1);
+	const head = trimmed.slice(0, at);
+	return /^[A-Za-z]:$/.test(head) ? `${head}${trimmed[at]}` : head;
+}
+/** A relative import, followed from the directory it was written in. `..` past the root stays at the root. */
+function joinPath(base, relative) {
+	const separator = base.includes("/") ? "/" : "\\";
+	const parts = base.replace(/[\\/]+$/, "").split(/[\\/]/);
+	for (const part of relative.split(/[\\/]/)) {
+		if (part === "" || part === ".") continue;
+		if (part === "..") {
+			if (parts.length > 1) parts.pop();
+			continue;
+		}
+		parts.push(part);
+	}
+	return parts.join(separator) || separator;
+}
+/** The path a `file:` URL names, or the URL with its scheme taken off when it will not parse as one. */
+function urlPath(specifier) {
+	try {
+		const path = decodeURIComponent(new URL(specifier).pathname);
+		return /^\/[A-Za-z]:\//.test(path) ? path.slice(1) : path;
+	} catch {
+		return specifier.replace(/^file:\/*/, "/");
+	}
+}
+/**
+* The import that did not resolve, as the runtime named it. Bun's field where there is one; otherwise the
+* one sentence each loader states it in. The prose around it names the referrer's absolute path, which
+* is why only the quoted part is taken.
+*/
+function writtenSpecifier(cause, message) {
+	const field = prop(cause, "specifier");
+	if (typeof field === "string" && field.length > 0) return field;
+	return (/Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(message) ?? /^Failed to load url (\S+) \(resolved id: /.exec(message) ?? /^No such built-in module: (\S+)$/.exec(message) ?? /^Package import specifier "([^"]+)" is not defined/.exec(message) ?? /^Directory import '([^']+)' is not supported/.exec(message))?.[1];
+}
+/**
+* The file the failing import was written in, as the runtime named it. **Module-private on purpose**: it
+* is an absolute path, and only its package half ever leaves here.
+*
+* Node ends its sentence with the path, so it is taken to the end — a directory may contain a space.
+* Vite's module runner quotes it, and its own `ERR_LOAD_URL` sentence names it before `. Does the file
+* exist?` (Vite 8.3.0, measured).
+*/
+function importerPath(cause) {
+	const field = prop(cause, "referrer");
+	if (typeof field === "string" && field.length > 0) return field;
+	const message = causeMessage(cause) ?? "";
+	return (/ imported from '(.+)'$/.exec(message) ?? / imported from (.+)$/.exec(message) ?? /^Failed to load url \S+ \(resolved id: [^)]*\) in (.+)\. Does the file exist\?$/.exec(message))?.[1];
+}
+/** Every remedy that cannot be helped by an install says so, in these words. */
+const NO_INSTALL = "installing dependencies will not help.";
+/** The one sentence for a classified import. Built only from fields that cannot carry a path. */
+function remedy(found, owner) {
+	const { kind, shown, package: pkg } = found;
+	switch (kind) {
+		case "package": {
+			const name = pkg ?? shown ?? "a package";
+			return owner === void 0 ? `"${name}" is not installed. Install the project's dependencies (bun install), or correct that import.` : `${owner} imports "${name}", which is not installed. Install the project's dependencies (bun install). If it is still missing, ${owner} does not declare it — report that to its maintainer.`;
+		}
+		case "package-subpath":
+			if (shown === void 0 || pkg === void 0) return `An import asks an installed package for a path it does not provide. Check the version you have, or correct that import — ${NO_INSTALL}`;
+			if (shown === pkg && (owner === void 0 || owner === pkg)) return `The installed ${pkg} has no entry to import by its bare name. Import one of its paths, or check the version of ${pkg} you have — ${NO_INSTALL}`;
+			return owner === void 0 || owner === pkg ? `"${shown}" is not something the installed ${pkg} provides. Check the version of ${pkg} you have, or correct that import — ${NO_INSTALL}` : `${owner} imports "${shown}", which the installed ${pkg} does not provide. Bring ${owner} and ${pkg} to matching versions, or report this to its maintainer — ${NO_INSTALL}`;
+		case "package-entry": {
+			const fix = `so it is unbuilt or its install is broken. Rebuild ${pkg}, or remove it and install it again.`;
+			const deep = shown !== void 0 && shown !== pkg;
+			const missing = deep ? `exports "${shown}" from a file that is not there, ${fix}` : `names an entry that is not there, ${fix}`;
+			if (owner === void 0 || owner === pkg) return `The installed ${pkg} ${missing}`;
+			return deep ? `${owner} imports "${shown}", and the installed ${pkg} exports it from a file that is not there, ${fix}` : `${owner} imports "${pkg}", and the installed ${pkg} ${missing}`;
+		}
+		case "package-file": return `${pkg} is missing its own file "${shown}". Report this to its maintainer — ${NO_INSTALL}`;
+		case "builtin":
+			if (shown === void 0) return `An import names a module this runtime does not provide. Correct that import — ${NO_INSTALL}`;
+			return owner === void 0 ? `"${shown}" is not a module this runtime provides. Correct that import — ${NO_INSTALL}` : `${owner} imports "${shown}", which this runtime does not provide. Run it on a runtime that has that module, or report this to its maintainer — ${NO_INSTALL}`;
+		case "local-file": return shown === void 0 ? `An import names a file that is not there. Create that file or correct the import — ${NO_INSTALL}` : `Nothing at "${shown}". Create that file or correct the import — ${NO_INSTALL}`;
+		case "imports-map": return owner === void 0 ? `"${shown}" is not in the project's imports map. Add it to the imports field of package.json, or correct the import — ${NO_INSTALL}` : `${owner} imports "${shown}", which its own imports map does not provide. Report this to its maintainer — ${NO_INSTALL}`;
+		case "undetermined": return owner === void 0 ? `Nothing resolves "${shown}". Install the project's dependencies (bun install), or correct that import.` : `${owner} imports "${shown}", and nothing resolves it. Install the project's dependencies (bun install), or bring ${owner} and ${pkg} to matching versions.`;
+		case "unnamed": return "An import does not resolve. Check the imports, then install the project's dependencies (bun install).";
+	}
+}
+/** What Node says of code whose syntax contradicts the module type its package declares. */
+const MODULE_TYPE = / is not defined in ES module scope|Cannot use import statement outside a module|Unexpected token 'export'|Cannot use 'import\.meta' outside a module/;
+/**
+* **A file inside an installed package would not load, so the package is named and never the config.**
+*
+* A `"type"` its code contradicts — `module` over `module.exports`, `commonjs` over `import` — throws from
+* inside that package, on Node and through Vite's runner alike, as a `ReferenceError` or a `SyntaxError`.
+* Unclassified, the first read as *the config threw while loading* and the second as *the config does not
+* parse*: the adopter told to fix a file that is fine. A package's file that does not parse at all is the
+* same fault in the same place, and is named the same way.
+*
+* **The file is the one that failed to load, and only that one.** Node heads a compile error with the file
+* and line it could not compile, and Bun 1.4.2 hands over a `BuildMessage` with no stack at all, the file
+* in its `position`. Otherwise the error's first stack frame must be a module's own top level, run as it
+* is imported — `at file:///…:L:C`, or Vite's `at eval (…)`, with no function of its own. A first frame
+* inside a function is the config calling into a package, and a later frame is a caller: so a package's
+* deliberate throw, which the config provoked — json5's `parse` throws a `SyntaxError` on bad input — is
+* never laid at the package's door. Only errors a module throws while it is loaded are read: a
+* `SyntaxError` or a `BuildMessage`, and a `ReferenceError` for a CommonJS global in a module's scope.
+*
+* `undefined` when the cause is not one, or was thrown in the adopter's own file — that stays theirs.
+*/
+function packageLoadFailure(wrapped, options = {}) {
+	const cause = rootCause(wrapped);
+	const typeMismatch = MODULE_TYPE.test(causeMessage(cause) ?? "");
+	const name = prop(cause, "name");
+	if (!typeMismatch && name !== "SyntaxError" && name !== "BuildMessage") return void 0;
+	const owner = ownerOf(failedToLoad(cause), options.loader);
+	if (owner === void 0) return void 0;
+	const check = `Check the version of ${owner} you have, or report this to its maintainer — ${NO_INSTALL}`;
+	return {
+		owner,
+		remedy: typeMismatch ? `The installed ${owner} does not load as the module type its package.json declares. ${check}` : `The installed ${owner} does not parse. ${check}`
+	};
+}
+/**
+* The file that failed as it loaded, or none: the file and line Node heads a compile error with, the file a
+* stackless `BuildMessage` names in its `position` (Bun 1.4.2), or a first frame at a module's top level.
+* Never a frame inside a function, which is code running after its module loaded. **Module-private**, like
+* {@link importerPath}: it is an absolute path.
+*/
+function failedToLoad(cause) {
+	const stack = prop(cause, "stack");
+	if (typeof stack !== "string") {
+		const file = prop(prop(cause, "position"), "file");
+		return typeof file === "string" ? locationPath(file) : void 0;
+	}
+	const lines = stack.split("\n");
+	const head = /^(.+):\d+$/.exec(lines[0] ?? "")?.[1];
+	if (head !== void 0 && (head.startsWith("file:") || ABSOLUTE.test(head))) return locationPath(head);
+	const frame = lines.find((line) => /^\s+at /.test(line));
+	if (frame === void 0) return void 0;
+	const at = /^\s+at eval \((.+?):\d+(?::\d+)?\)$/.exec(frame)?.[1] ?? /^\s+at ([^()]+?):\d+(?::\d+)?$/.exec(frame)?.[1];
+	return at === void 0 ? void 0 : locationPath(at);
+}
+/** A stack location as a path: a `file:` URL converted, an absolute path kept, anything else — `node:` — none. */
+function locationPath(location) {
+	if (location.startsWith("file:")) return urlPath(location);
+	return ABSOLUTE.test(location) ? location : void 0;
+}
+//#endregion
+export { declaredEntry, exportedTarget, importingPackage, nodeModulesProbe, packageEntryProbe, packageLoadFailure, unresolvedImport };

package/dist/error/wire.d.ts

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * The wire body of every error a route returns, whatever its status: `pithyErrorHandler` renders
+ * `{ error: clientError(payload) }`, and a socket's error frame carries the same `error` object. The payload's own schema is a union over every kit code, which
+ * would put several hundred variants into each operation, so the contract describes the envelope and
+ * names the code list's home instead.
+ */
+export declare const ErrorBody: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        status: z.ZodNumber;
+        message: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        issues: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ErrorBody = z.infer<typeof ErrorBody>;
+//# sourceMappingURL=wire.d.ts.map

package/dist/error/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/error/wire.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;iBAwB0B,CAAC;AACjD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC"}

package/dist/error/wire.js

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+//#region src/error/wire.ts
+/**
+* The wire body of every error a route returns, whatever its status: `pithyErrorHandler` renders
+* `{ error: clientError(payload) }`, and a socket's error frame carries the same `error` object. The payload's own schema is a union over every kit code, which
+* would put several hundred variants into each operation, so the contract describes the envelope and
+* names the code list's home instead.
+*/
+const ErrorBody = z.object({ error: z.object({
+	code: z.string().describe("Namespaced `domain/reason`, e.g. `auth/invalid_token`. Stable: a client switches on it. The full list is `pithy schema --json`'s `errorCodes`."),
+	status: z.number().int().describe("The HTTP status, repeated in the body."),
+	message: z.string().describe("English, for a person. A client that translates renders its own wording for `code` instead."),
+	params: z.record(z.string(), z.unknown()).optional().describe("Values a translating client interpolates into its own wording for `code`."),
+	issues: z.array(z.unknown()).optional().describe("For `validation/invalid_input`: one entry per field that failed, with its path.")
+}).describe("The public error payload. Never carries the operator's remedy or internal detail.") }).describe("The body of every error response.");
+//#endregion
+export { ErrorBody };

package/dist/http/oidcWebhook.d.ts

@@ -295,8 +295,8 @@ export interface OidcWebhookGuardOptions extends OidcWebhookScheme {
  */
 export declare function verifyOidcToken(token: string, options: VerifyOidcTokenOptions): Promise<OidcClaims>;
 /**
- * The OIDC gate, as a route wears it: `app.post(path, requireOidcWebhook({…}), zValidator("json", Body,
- * validationHook), handler)`.
+ * The OIDC gate, as a route wears it: `app.post(path, requireOidcWebhook({…}), validate("json", Body),
+ * handler)`.
  *
  * ## Why the header is read before anything else
  *
@@ -332,7 +332,7 @@ export declare function verifyOidcToken(token: string, options: VerifyOidcTokenO
  * null-check.
  *
  * The body is never read here — unlike the HMAC gate, whose proof covers the bytes. An OIDC token proves who
- * sent the request and says nothing about what they sent, so the route's `zValidator` is the only thing that
+ * sent the request and says nothing about what they sent, so the route's `validate` is the only thing that
  * touches the body, and it sees an untouched stream.
  */
 export declare function requireOidcWebhook(options: OidcWebhookGuardOptions): MiddlewareHandler<PithyHonoEnv>;