@kubb/studio 5.10.1 → 5.10.2

package/README.md

@@ -75,6 +75,7 @@ running in a developer's project and a container running a fixed plugin set.
 | `pair.ts`        | `pairAgent`: RFC 8628 device pairing.                                            |
 | `snapshot.ts`    | `createSnapshot` for CI, and packing a generation into an npm tarball.           |
 | `generations.ts` | Running a generation and keeping its files and AST for `readFiles`/`readInput`.  |
+| `diff.ts`        | The paged line diff `readDiff` serves between two kept sets.                     |
 | `configFile.ts`  | Reading and patching plugin options in `kubb.config.ts`.                         |
 
 ## Connection

package/dist/index.cjs

@@ -36,6 +36,7 @@ let _kubb_core = require("@kubb/core");
 let capnweb = require("capnweb");
 let magicast = require("magicast");
 let node_module = require("node:module");
+let diff = require("diff");
 let node_util = require("node:util");
 let _kubb_ast = require("@kubb/ast");
 let ofetch = require("ofetch");
@@ -177,7 +178,7 @@ function getElapsedMs(hrStart) {
 }
 //#endregion
 //#region package.json
-var version = "5.10.1";
+var version = "5.10.2";
 //#endregion
 //#region src/resolveConfig.ts
 /**
@@ -279,22 +280,42 @@ function isAllowedPlugin({ packageName, extensions }) {
 *
 * @throws if the package cannot be imported or exports no callable factory.
 */
-async function loadFactory({ packageName, extensions }) {
+async function loadFactory({ packageName, extensions, kind = "plugin" }) {
+	const label = {
+		plugin: "Plugin",
+		adapter: "Adapter",
+		parser: "Parser"
+	}[kind];
 	let mod;
 	try {
 		mod = await importFromProject(packageName);
 	} catch (cause) {
-		throw new Error(`Plugin "${packageName}" could not be loaded. Make sure it is installed: \`npm install ${packageName}\``, { cause });
+		throw new _kubb_core.Diagnostics.Error({
+			code: kind === "plugin" ? _kubb_core.Diagnostics.code.pluginNotFound : _kubb_core.Diagnostics.code.unknown,
+			severity: "error",
+			message: `${label} "${packageName}" could not be loaded. Make sure it is installed: \`npm install ${packageName}\``,
+			cause: toError(cause)
+		});
 	}
 	const manifestExport = extensions.get(packageName)?.manifest.export;
 	if (manifestExport) {
 		if (typeof mod[manifestExport] === "function") return mod[manifestExport];
-		throw new Error(`Plugin "${packageName}" does not export "${manifestExport}", the factory its kubb-extension.json names.`);
+		throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.incompatibleExtension,
+			severity: "error",
+			message: `${label} "${packageName}" does not export "${manifestExport}", the factory its kubb-extension.json names.`,
+			help: "Install a version of the plugin whose exports match its kubb-extension.json."
+		});
 	}
 	const exportName = toExportName(packageName);
 	if (typeof mod[exportName] === "function") return mod[exportName];
 	if (typeof mod["default"] === "function") return mod["default"];
-	throw new Error(`Plugin "${packageName}" does not export a callable factory. Tried the named export "${exportName}" and "default".`);
+	throw new _kubb_core.Diagnostics.Error({
+		code: _kubb_core.Diagnostics.code.incompatibleExtension,
+		severity: "error",
+		message: `${label} "${packageName}" does not export a callable factory. Tried the named export "${exportName}" and "default".`,
+		help: "Install a Kubb plugin package that exports its factory."
+	});
 }
 /**
 * Resolves each plugin entry by dynamically importing its package and calling its factory with the
@@ -315,7 +336,11 @@ async function resolvePlugins({ plugins, extensions = /* @__PURE__ */ new Map()
 		if (!isAllowedPlugin({
 			packageName: name,
 			extensions
-		})) throw new Error(`Plugin "${name}" is not an installed Kubb plugin. Studio loads @kubb/plugin-* packages and installed packages that ship a kubb-extension.json with kind "plugin".`);
+		})) throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.pluginNotFound,
+			severity: "error",
+			message: `Plugin "${name}" is not an installed Kubb plugin. Studio loads @kubb/plugin-* packages and installed packages that ship a kubb-extension.json with kind "plugin".`
+		});
 		return (await loadFactory({
 			packageName: name,
 			extensions
@@ -442,7 +467,12 @@ async function mergePlugins({ diskPlugins, studioPlugins, extensions = /* @__PUR
 			extensions
 		}).catch((cause) => {
 			if (unchanged) return [diskPlugin];
-			throw new Error(`Plugin "${diskPlugin.name}" is not an installed @kubb/plugin-* package or Kubb extension, so Studio cannot change its options. Edit it in the config file, or only enable or disable it from Studio.`, { cause });
+			throw new _kubb_core.Diagnostics.Error({
+				code: _kubb_core.Diagnostics.code.pluginNotFound,
+				severity: "error",
+				message: `Plugin "${diskPlugin.name}" is not an installed @kubb/plugin-* package or Kubb extension, so Studio cannot change its options. Edit it in the config file, or only enable or disable it from Studio.`,
+				cause: toError(cause)
+			});
 		});
 		return resolved ?? diskPlugin;
 	}));
@@ -466,9 +496,15 @@ async function rebuildExtension({ disk, studioOptions, kind, extensions }) {
 	const { name } = (0, _kubb_core.resolveMeta)(disk);
 	return (await loadFactory({
 		packageName: [...extensions.values()].find(({ manifest }) => manifest.kind === kind && manifest.name === name)?.package ?? `@kubb/${kind}-${name}`,
-		extensions
+		extensions,
+		kind
 	}).catch((cause) => {
-		throw new Error(`The ${kind} "${name}" is not an installed Kubb extension, so Studio cannot change its options. Edit it in the config file.`, { cause });
+		throw new _kubb_core.Diagnostics.Error({
+			code: kind === "plugin" ? _kubb_core.Diagnostics.code.pluginNotFound : _kubb_core.Diagnostics.code.unknown,
+			severity: "error",
+			message: `The ${kind} "${name}" is not an installed Kubb extension, so Studio cannot change its options. Edit it in the config file.`,
+			cause: toError(cause)
+		});
 	}))(mergeOptions(disk.options ?? {}, studioOptions));
 }
 /**
@@ -545,7 +581,11 @@ function invalidEdit(edit) {
 }
 /** Where a node sits in the source text. */
 function rangeOf(node) {
-	if (typeof node.start !== "number" || typeof node.end !== "number") throw new Error("the config file could not be mapped back to its source text");
+	if (typeof node.start !== "number" || typeof node.end !== "number") throw new _kubb_core.Diagnostics.Error({
+		code: _kubb_core.Diagnostics.code.internalError,
+		severity: "error",
+		message: "the config file could not be mapped back to its source text"
+	});
 	return {
 		start: node.start,
 		end: node.end
@@ -797,6 +837,44 @@ function disabledBlocks(source, config) {
 		}];
 	});
 }
+/**
+* Reads an object option that holds some code: its literal members as `value`, and the paths of
+* the members that are code as `locked`. `set` can write any path outside `locked`, so Studio
+* edits those fields. `undefined` for a computed key, since it could set any path.
+*/
+function readPartial(node, prefix = []) {
+	const value = {};
+	const locked = [];
+	for (const [index, entry] of node.properties.entries()) {
+		if (entry.type === "SpreadElement") continue;
+		const key = memberKey(entry);
+		if (key === void 0) return void 0;
+		if (findMember(node, key)?.index !== index) continue;
+		const path = [...prefix, key];
+		if (!isSafeKey(key)) {
+			locked.push(path);
+			continue;
+		}
+		const member = entry.type === "ObjectProperty" && !isShadowed(node, index) ? entry.value : void 0;
+		const literal = readLiteral(member);
+		if (literal !== void 0) {
+			value[key] = literal;
+			continue;
+		}
+		if (member?.type !== "ObjectExpression") {
+			locked.push(path);
+			continue;
+		}
+		const nested = readPartial(member, path);
+		if (!nested) return void 0;
+		value[key] = nested.value;
+		locked.push(...nested.locked);
+	}
+	return {
+		value,
+		locked
+	};
+}
 /** The top-level options of a plugin call, each flagged with whether Studio may write it. */
 function readOptions(call) {
 	const entries = {};
@@ -805,10 +883,15 @@ function readOptions(call) {
 	for (const [index, entry] of options.properties.entries()) {
 		const key = memberKey(entry);
 		if (key === void 0 || !isSafeKey(key)) continue;
-		const value = entry.type === "ObjectProperty" && !isShadowed(options, index) ? readLiteral(entry.value) : void 0;
-		entries[key] = value === void 0 ? { literal: false } : {
+		const member = entry.type === "ObjectProperty" && !isShadowed(options, index) ? entry.value : void 0;
+		const value = readLiteral(member);
+		const partial = value === void 0 && member?.type === "ObjectExpression" ? readPartial(member) : void 0;
+		entries[key] = value !== void 0 ? {
 			literal: true,
 			value
+		} : {
+			literal: false,
+			...partial
 		};
 	}
 	return entries;
@@ -1094,6 +1177,38 @@ async function writeConfigEdits({ filePath, edits, extensions }) {
 	return result;
 }
 //#endregion
+//#region src/diff.ts
+const CONTEXT_LINES = 3;
+const DIFF_TIMEOUT_MS = 1e4;
+function diffHunks(before, after) {
+	return new Promise((resolve) => {
+		(0, diff.structuredPatch)("", "", before, after, void 0, void 0, {
+			context: CONTEXT_LINES,
+			timeout: DIFF_TIMEOUT_MS,
+			callback: (patch) => resolve(patch?.hunks)
+		});
+	});
+}
+function pageHunks({ hunks, cursor, limit }) {
+	const page = [];
+	const end = cursor + limit;
+	let start = 0;
+	for (const [index, hunk] of hunks.entries()) {
+		const next = start + hunk.lines.length;
+		if (next > cursor && start < end) page.push({
+			index,
+			oldStart: hunk.oldStart,
+			newStart: hunk.newStart,
+			lines: hunk.lines.slice(Math.max(0, cursor - start), end - start)
+		});
+		start = next;
+	}
+	return {
+		hunks: page,
+		nextCursor: end < start ? end : null
+	};
+}
+//#endregion
 //#region src/generations.ts
 const READ_CONCURRENCY = 50;
 const MB = 1048576;
@@ -1223,8 +1338,8 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 				if (path.split("/").includes("..")) return;
 				const content = await files.storage.readItem((0, node_path.resolve)(files.root, path));
 				if (content === null) return;
-				if (source === "output" && !content.trim()) return;
-				hashes[path] = hashOf(source === "output" ? `${content.trim()}\n` : content);
+				if (source === require_protocol.FileSource.OUTPUT && !content.trim()) return;
+				hashes[path] = hashOf(source === require_protocol.FileSource.OUTPUT ? `${content.trim()}\n` : content);
 				bytes += Buffer.byteLength(content);
 				if (bytes <= maxSetBytes) await storage.writeItem(`${dirOf(jobId)}${source}/${path}`, content);
 			}
@@ -1522,7 +1637,11 @@ function isLoopbackHost(hostname) {
 */
 function secureUrl({ studioUrl, path, socket = false }) {
 	const url = new URL(`${studioUrl.replace(/\/+$/, "")}${path}`);
-	if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname))) throw new Error(`Refusing to reach Kubb Studio at ${url.origin}: use an https:// URL, or a loopback host for local development`);
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname))) throw new _kubb_core.Diagnostics.Error({
+		code: _kubb_core.Diagnostics.code.unknown,
+		severity: "error",
+		message: `Refusing to reach Kubb Studio at ${url.origin}: use an https:// URL, or a loopback host for local development`
+	});
 	if (socket) url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
 	return url;
 }
@@ -1592,6 +1711,7 @@ var Agent = class extends capnweb.RpcTarget {
 	#session;
 	#limits = resolveGenerationLimits();
 	#store;
+	#diffs = /* @__PURE__ */ new Map();
 	constructor({ options, session }) {
 		super();
 		this.#options = options;
@@ -1630,10 +1750,18 @@ var Agent = class extends capnweb.RpcTarget {
 			message,
 			permission
 		});
-		throw new Error(message);
+		throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.unknown,
+			severity: "error",
+			message
+		});
 	}
 	#assertConnected() {
-		if (!this.#session.info) throw new Error("Studio must call connect() before any other command");
+		if (!this.#session.info) throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.internalError,
+			severity: "error",
+			message: "Studio must call connect() before any other command"
+		});
 	}
 	#logCommand(command, info) {
 		return emit(this.#options.hooks, "studio:command", {
@@ -1730,7 +1858,11 @@ var Agent = class extends capnweb.RpcTarget {
 	/** Runs one job and keeps its output, and its input with `allowRead`, for later reads. */
 	async #runGeneration(input, controller) {
 		this.#assertConnected();
-		if (this.#session.closed) throw new Error("Connection is closed");
+		if (this.#session.closed) throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.internalError,
+			severity: "error",
+			message: "Connection is closed"
+		});
 		if (this.#session.active) return this.#refuse({ message: "A generation is already in progress, please wait for it to finish" });
 		const settled = Promise.withResolvers();
 		this.#session.active = {
@@ -1788,7 +1920,7 @@ var Agent = class extends capnweb.RpcTarget {
 		}) : void 0;
 		const disk = diskFiles ? await this.#generations.keep({
 			jobId,
-			source: "disk",
+			source: require_protocol.FileSource.DISK,
 			files: diskFiles,
 			maxSetMb: this.#limits.maxSnapshotMb
 		}) : void 0;
@@ -1811,7 +1943,7 @@ var Agent = class extends capnweb.RpcTarget {
 		});
 		const output = await this.#generations.keep({
 			jobId,
-			source: "output",
+			source: require_protocol.FileSource.OUTPUT,
 			files,
 			maxSetMb: this.#limits.maxMb
 		});
@@ -1883,14 +2015,14 @@ var Agent = class extends capnweb.RpcTarget {
 	async readInput(input) {
 		this.#assertConnected();
 		if (!this.#permissions.allowReadAst) return this.#refuse({
-			message: require_protocol.READ_AST_NOT_ALLOWED_MESSAGE,
-			permission: "allowReadAst"
+			message: require_protocol.AgentMessage.READ_AST_NOT_ALLOWED,
+			permission: require_protocol.AgentPermission.READ_AST
 		});
 		if (typeof input.jobId !== "string" || !input.jobId) return this.#refuse({ message: "The request must name a job" });
 		const generation = await this.#generations.get(input.jobId);
-		if (!generation) return this.#refuse({ message: require_protocol.GENERATION_GONE_MESSAGE });
+		if (!generation) return this.#refuse({ message: require_protocol.AgentMessage.GENERATION_GONE });
 		const kept = generation.inputBytes ? await this.#generations.readInput(input.jobId) : void 0;
-		if (!kept) return this.#refuse({ message: require_protocol.NO_INPUT_MESSAGE });
+		if (!kept) return this.#refuse({ message: require_protocol.AgentMessage.NO_INPUT });
 		await this.#logCommand("readInput", "read the API input");
 		return { input: kept };
 	}
@@ -1900,16 +2032,16 @@ var Agent = class extends capnweb.RpcTarget {
 	async readFiles(input) {
 		this.#assertConnected();
 		if (!this.#permissions.allowRead) return this.#refuse({
-			message: require_protocol.READ_NOT_ALLOWED_MESSAGE,
-			permission: "allowRead"
+			message: require_protocol.AgentMessage.READ_NOT_ALLOWED,
+			permission: require_protocol.AgentPermission.READ
 		});
 		if (!Array.isArray(input.paths) || typeof input.jobId !== "string" || !input.jobId) return this.#refuse({ message: "The request must name a job and carry paths" });
 		const { paths } = input;
 		if (paths.length > 50) return this.#refuse({ message: `At most 50 paths may be requested at once` });
 		const generation = await this.#generations.get(input.jobId);
-		if (!generation) return this.#refuse({ message: require_protocol.GENERATION_GONE_MESSAGE });
+		if (!generation) return this.#refuse({ message: require_protocol.AgentMessage.GENERATION_GONE });
 		if (!isValidPage(input)) return this.#refuse({ message: `The cursor must be a whole line from 0 and come with a limit of 1 to ${require_protocol.MAX_PAGE_LINES} lines` });
-		const source = input.source === "disk" ? "disk" : "output";
+		const source = input.source === require_protocol.FileSource.DISK ? require_protocol.FileSource.DISK : require_protocol.FileSource.OUTPUT;
 		if (!generation[source]) return this.#refuse({ message: "This agent kept no snapshot of the files on disk for that job" });
 		const result = await this.#generations.read({
 			generation,
@@ -1921,6 +2053,69 @@ var Agent = class extends capnweb.RpcTarget {
 		await this.#logCommand("readFiles", `read ${Object.keys(result.files).length}/${paths.length} requested file${paths.length === 1 ? "" : "s"}`);
 		return result;
 	}
+	/**
+	* Returns one page of the line diff of a file between two kept sets. Refused without `allowRead`.
+	*/
+	async readDiff(input) {
+		this.#assertConnected();
+		if (!this.#permissions.allowRead) return this.#refuse({
+			message: require_protocol.AgentMessage.READ_NOT_ALLOWED,
+			permission: require_protocol.AgentPermission.READ
+		});
+		const { jobId, path, base, cursor = 0, limit } = input;
+		if (typeof jobId !== "string" || !jobId || typeof path !== "string" || !path || typeof base?.jobId !== "string" || !base.jobId) return this.#refuse({ message: "The request must name a job, a base, and a path" });
+		if (!isValidPage({
+			cursor,
+			limit
+		})) return this.#refuse({ message: `The cursor must be a whole line from 0 and come with a limit of 1 to ${require_protocol.MAX_PAGE_LINES} lines` });
+		const [generation, baseGeneration] = await Promise.all([this.#generations.get(jobId), this.#generations.get(base.jobId)]);
+		if (!generation || !baseGeneration) return this.#refuse({ message: require_protocol.AgentMessage.GENERATION_GONE });
+		const baseSource = base.source === require_protocol.FileSource.DISK ? require_protocol.FileSource.DISK : require_protocol.FileSource.OUTPUT;
+		if (!baseGeneration[baseSource]) return this.#refuse({ message: "This agent kept no snapshot of the files on disk for that job" });
+		const [after, before] = await Promise.all([this.#generations.read({
+			generation,
+			source: require_protocol.FileSource.OUTPUT,
+			paths: [path]
+		}), this.#generations.read({
+			generation: baseGeneration,
+			source: baseSource,
+			paths: [path]
+		})]);
+		const afterContent = after.files[path];
+		if (afterContent === void 0 && path in generation.output.hashes) return this.#refuse({ message: "This agent kept only the hashes of that job" });
+		const beforeContent = before.files[path];
+		if (beforeContent === void 0) return {
+			hunks: [],
+			nextCursor: null,
+			hasBase: false
+		};
+		const key = JSON.stringify([
+			jobId,
+			base.jobId,
+			baseSource,
+			path
+		]);
+		let hunks = this.#diffs.get(key);
+		if (!hunks) {
+			hunks = diffHunks(beforeContent, afterContent ?? "");
+			this.#diffs.set(key, hunks);
+			if (this.#diffs.size > 4) this.#diffs.delete(this.#diffs.keys().next().value);
+		}
+		const all = await hunks;
+		if (!all) {
+			this.#diffs.delete(key);
+			return this.#refuse({ message: "The two versions differ too much to diff" });
+		}
+		await this.#logCommand("readDiff", `read the diff of ${path}`);
+		return {
+			...pageHunks({
+				hunks: all,
+				cursor,
+				limit
+			}),
+			hasBase: true
+		};
+	}
 };
 const openWebSocketRpc = ({ url, token, instanceId, agent }) => {
 	const socket = new WebSocket(url, { headers: {
@@ -2129,7 +2324,12 @@ async function startPairing({ studioUrl = defaultStudioUrl, type, name, hostname
 			},
 			signal
 		});
-		if (typeof pairing?.device_code !== "string") throw new Error("Kubb Studio returned no pairing code");
+		if (typeof pairing?.device_code !== "string") throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.unknown,
+			severity: "error",
+			message: "Kubb Studio returned no pairing code",
+			help: "Try again later. If it keeps failing, check the Kubb Studio status."
+		});
 		return pairing;
 	} catch (error) {
 		if (signal?.aborted) throw new PairingCanceledError();
@@ -2170,7 +2370,12 @@ async function pollForPairingToken({ studioUrl = defaultStudioUrl, session, sign
 				signal,
 				ignoreResponseError: true
 			});
-			if (status >= 500 || !_data || typeof _data !== "object") throw new Error(`Kubb Studio answered with status ${status}`);
+			if (status >= 500 || !_data || typeof _data !== "object") throw new _kubb_core.Diagnostics.Error({
+				code: _kubb_core.Diagnostics.code.inputRequestFailed,
+				severity: "error",
+				message: `Kubb Studio answered with status ${status}`,
+				help: "Try again later."
+			});
 			response = _data;
 		} catch (error) {
 			if (signal?.aborted) throw new PairingCanceledError();
@@ -2178,7 +2383,11 @@ async function pollForPairingToken({ studioUrl = defaultStudioUrl, session, sign
 			continue;
 		}
 		if (isPairingResult(response)) return response;
-		if (!("error" in response) || typeof response.error !== "string") throw new Error("Kubb Studio returned an empty pairing response, pair again");
+		if (!("error" in response) || typeof response.error !== "string") throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.unknown,
+			severity: "error",
+			message: "Kubb Studio returned an empty pairing response, pair again"
+		});
 		if (response.error === "authorization_pending") continue;
 		if (response.error === "slow_down") {
 			intervalMs += 5e3;
@@ -2186,7 +2395,12 @@ async function pollForPairingToken({ studioUrl = defaultStudioUrl, session, sign
 		}
 		if (response.error === "access_denied") throw new PairingDeniedError(response.error_description);
 		if (response.error === "expired_token" || response.error === "invalid_grant") throw new PairingExpiredError(response.error_description);
-		throw new Error(response.error_description ?? `Pairing failed (${response.error})`);
+		throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.unknown,
+			severity: "error",
+			message: response.error_description ?? `Pairing failed (${response.error})`,
+			help: "Pair again with `kubb studio login`."
+		});
 	}
 	throw new PairingExpiredError();
 }
@@ -2236,7 +2450,12 @@ function splitEntryPath(path) {
 			prefix
 		};
 	}
-	throw new Error(`Snapshot path is too long for a tar entry: ${path}`);
+	throw new _kubb_core.Diagnostics.Error({
+		code: _kubb_core.Diagnostics.code.unknown,
+		severity: "error",
+		message: `Snapshot path is too long for a tar entry: ${path}`,
+		help: "Shorten the output path or the generated file names."
+	});
 }
 function header(path, size) {
 	const { name, prefix } = splitEntryPath(path);
@@ -2269,7 +2488,12 @@ async function createSnapshotPackage({ files, packageInfo }) {
 	for (const [name, content] of Object.entries(files)) {
 		const path = packagePath(name);
 		const owner = sources.get(path)?.name;
-		if (owner) throw new Error(`Snapshot has two generated files that sanitize to the same path "package/${path}": "${owner}" and "${name}"`);
+		if (owner) throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.unknown,
+			severity: "error",
+			message: `Snapshot has two generated files that sanitize to the same path "package/${path}": "${owner}" and "${name}"`,
+			help: "Rename one of the generated files, for example with a plugin resolver."
+		});
 		sources.set(path, {
 			name,
 			content
@@ -2359,7 +2583,11 @@ async function createSnapshot({ studioUrl = defaultStudioUrl, apiKey, config, ho
 	});
 	const files = Object.fromEntries(await Promise.all([...generated.paths].map(async (path) => {
 		const content = await generated.storage.readItem((0, node_path.resolve)(generated.root, path));
-		if (content === null) throw new Error(`The generation listed ${path} but did not keep its content`);
+		if (content === null) throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.internalError,
+			severity: "error",
+			message: `The generation listed ${path} but did not keep its content`
+		});
 		return [path, content];
 	})));
 	const pluginNames = config.plugins.map((plugin) => (0, _kubb_core.resolveMeta)(plugin).name);
@@ -2372,7 +2600,12 @@ async function createSnapshot({ studioUrl = defaultStudioUrl, apiKey, config, ho
 	const names = [...new Set(pluginNames.map(packageOf))];
 	const peerDependencies = Object.fromEntries(installed.flatMap(({ package: name, version }) => names.includes(name) && version ? [[name, version]] : []));
 	const missing = names.filter((name) => !(name in peerDependencies) && !BUNDLED_DEPENDENCIES.includes(name));
-	if (missing.length) throw new Error(`Missing dependencies: ${missing.join(", ")}`);
+	if (missing.length) throw new _kubb_core.Diagnostics.Error({
+		code: _kubb_core.Diagnostics.code.missingDependency,
+		severity: "error",
+		message: `Missing dependencies: ${missing.join(", ")}`,
+		help: "Install the listed plugin packages in the project."
+	});
 	const bytes = await createSnapshotPackage({
 		files,
 		packageInfo: {
@@ -2381,7 +2614,12 @@ async function createSnapshot({ studioUrl = defaultStudioUrl, apiKey, config, ho
 			peerDependencies
 		}
 	});
-	if (bytes.length > 52428800) throw new Error(`The snapshot is ${Math.ceil(bytes.length / 1024 / 1024)} MB, over the ${require_protocol.MAX_SNAPSHOT_BYTES / 1024 / 1024} MB limit`);
+	if (bytes.length > 52428800) throw new _kubb_core.Diagnostics.Error({
+		code: _kubb_core.Diagnostics.code.unknown,
+		severity: "error",
+		message: `The snapshot is ${Math.ceil(bytes.length / 1024 / 1024)} MB, over the ${require_protocol.MAX_SNAPSHOT_BYTES / 1024 / 1024} MB limit`,
+		help: "Generate fewer files, for example with `include` or `exclude` on the plugins."
+	});
 	const hashes = Object.fromEntries(Object.entries(files).map(([path, content]) => [path, hashOf(content)]));
 	const body = new FormData();
 	body.set("metadata", JSON.stringify({
@@ -2401,9 +2639,19 @@ async function createSnapshot({ studioUrl = defaultStudioUrl, apiKey, config, ho
 	});
 	if (!ok) {
 		const upgrade = _data?.data?.upgradeUrl ? ` Upgrade at ${_data.data.upgradeUrl}.` : "";
-		throw new Error(`Kubb Studio refused the snapshot (status ${status})${_data?.message ? `: ${_data.message}` : ""}.${upgrade}`);
+		throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.inputRequestFailed,
+			severity: "error",
+			message: `Kubb Studio refused the snapshot (status ${status})${_data?.message ? `: ${_data.message}` : ""}.${upgrade}`,
+			help: "Check the API key and your plan, then try again."
+		});
 	}
-	if (!_data?.snapshot) throw new Error(`Kubb Studio returned no snapshot (status ${status})`);
+	if (!_data?.snapshot) throw new _kubb_core.Diagnostics.Error({
+		code: _kubb_core.Diagnostics.code.inputRequestFailed,
+		severity: "error",
+		message: `Kubb Studio returned no snapshot (status ${status})`,
+		help: "Try again later."
+	});
 	return _data.snapshot;
 }
 //#endregion