@kubb/studio 5.10.1 → 5.10.3

package/dist/index.js

@@ -1,5 +1,4 @@
-import "./rolldown-runtime-CRm0XQPb.js";
-import { AGENT_INSTANCE_HEADER, AGENT_SOCKET_PATH, AgentCloseCode, GENERATION_GONE_MESSAGE, MAX_PAGE_LINES, MAX_SNAPSHOT_BYTES, NO_INPUT_MESSAGE, READ_AST_NOT_ALLOWED_MESSAGE, READ_NOT_ALLOWED_MESSAGE, generationEventTypes } from "./protocol.js";
+import { AGENT_INSTANCE_HEADER, AGENT_SOCKET_PATH, AgentCloseCode, AgentMessage, AgentPermission, FileSource, MAX_PAGE_LINES, MAX_SNAPSHOT_BYTES, generationEventTypes } from "./protocol.js";
 import { createRequire } from "node:module";
 import { createHash, hash, randomUUID } from "node:crypto";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
@@ -12,10 +11,12 @@ import { existsSync } from "node:fs";
 import { Diagnostics, Hookable, cacheStorage, createKubb, fsStorage, getInputKind, isPackageName, memoryStorage, readInstalledPackages, resolveCacheDir, resolveMeta } from "@kubb/core";
 import { RpcTarget, newWebSocketRpcSession } from "capnweb";
 import { detectCodeFormat, parseExpression, parseModule } from "magicast";
+import { structuredPatch } from "diff";
 import { stripVTControlCharacters } from "node:util";
 import { ast } from "@kubb/ast";
 import { ofetch } from "ofetch";
 import { gzipSync } from "node:zlib";
+//#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
 * Shared implementation for camelCase and PascalCase conversion.
@@ -153,7 +154,7 @@ function getElapsedMs(hrStart) {
 }
 //#endregion
 //#region package.json
-var version = "5.10.1";
+var version = "5.10.3";
 //#endregion
 //#region src/resolveConfig.ts
 /**
@@ -255,22 +256,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 Diagnostics.Error({
+			code: kind === "plugin" ? Diagnostics.code.pluginNotFound : 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 Diagnostics.Error({
+			code: 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 Diagnostics.Error({
+		code: 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
@@ -291,7 +312,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 Diagnostics.Error({
+			code: 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
@@ -418,7 +443,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 Diagnostics.Error({
+				code: 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;
 	}));
@@ -442,9 +472,15 @@ async function rebuildExtension({ disk, studioOptions, kind, extensions }) {
 	const { name } = 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 Diagnostics.Error({
+			code: kind === "plugin" ? Diagnostics.code.pluginNotFound : 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));
 }
 /**
@@ -521,7 +557,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 Diagnostics.Error({
+		code: 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
@@ -773,6 +813,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 = {};
@@ -781,10 +859,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;
@@ -1070,6 +1153,159 @@ async function writeConfigEdits({ filePath, edits, extensions }) {
 	return result;
 }
 //#endregion
+//#region src/diff.ts
+const CONTEXT_LINES = 3;
+const DIFF_TIMEOUT_MS = 1e3;
+const splitLines = (text) => text === "" ? [] : text.split(/(?<=\n)/);
+function longestIncreasing(values) {
+	const tails = [];
+	const prev = [];
+	for (const [index, value] of values.entries()) {
+		let low = 0;
+		let high = tails.length;
+		while (low < high) {
+			const mid = low + high >> 1;
+			if (values[tails[mid]] < value) low = mid + 1;
+			else high = mid;
+		}
+		prev[index] = low > 0 ? tails[low - 1] : -1;
+		tails[low] = index;
+	}
+	const result = [];
+	for (let index = tails.at(-1) ?? -1; index !== -1; index = prev[index]) result.push(index);
+	return result.reverse();
+}
+function cutPoints(before, after) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const [index, line] of before.entries()) {
+		const count = counts.get(line);
+		if (count) count.before++;
+		else counts.set(line, {
+			before: 1,
+			after: 0,
+			index
+		});
+	}
+	const afterIndex = /* @__PURE__ */ new Map();
+	for (const [index, line] of after.entries()) {
+		const count = counts.get(line);
+		if (!count) continue;
+		count.after++;
+		afterIndex.set(line, index);
+	}
+	const unique = [...counts].filter(([, count]) => count.before === 1 && count.after === 1).map(([line, count]) => [count.index, afterIndex.get(line)]);
+	const anchors = longestIncreasing(unique.map(([, index]) => index)).map((index) => unique[index]);
+	const cuts = [[0, 0]];
+	let run = {
+		before: 0,
+		after: 0,
+		length: 0
+	};
+	const closeRun = () => {
+		if (run.length > 6) cuts.push([run.before + CONTEXT_LINES, run.after + CONTEXT_LINES]);
+	};
+	let i = 0;
+	let j = 0;
+	for (const [anchorBefore, anchorAfter] of anchors) {
+		const unchanged = anchorBefore - i === anchorAfter - j && before.slice(i, anchorBefore).every((line, offset) => line === after[j + offset]);
+		if (unchanged && run.length && run.before + run.length === i) run.length += anchorBefore - i + 1;
+		else {
+			closeRun();
+			run = unchanged ? {
+				before: i,
+				after: j,
+				length: anchorBefore - i + 1
+			} : {
+				before: anchorBefore,
+				after: anchorAfter,
+				length: 1
+			};
+		}
+		i = anchorBefore + 1;
+		j = anchorAfter + 1;
+	}
+	closeRun();
+	cuts.push([before.length, after.length]);
+	return cuts;
+}
+function replaceHunk(before, after) {
+	let start = 0;
+	while (start < before.length && start < after.length && before[start] === after[start]) start++;
+	let end = 0;
+	while (end < before.length - start && end < after.length - start && before[before.length - 1 - end] === after[after.length - 1 - end]) end++;
+	const removed = before.slice(start, before.length - end);
+	const added = after.slice(start, after.length - end);
+	if (!removed.length && !added.length) return [];
+	const lines = (prefix, rows) => rows.flatMap((row) => row.endsWith("\n") ? [`${prefix}${row.slice(0, -1)}`] : [`${prefix}${row}`, "\"]);
+	return [{
+		oldStart: start + 1,
+		oldLines: removed.length,
+		newStart: start + 1,
+		newLines: added.length,
+		lines: [...lines("-", removed), ...lines("+", added)]
+	}];
+}
+function diffHunks(before, after, timeout = DIFF_TIMEOUT_MS) {
+	const beforeLines = splitLines(before);
+	const afterLines = splitLines(after);
+	const cuts = cutPoints(beforeLines, afterLines);
+	const deadline = Date.now() + timeout;
+	const hunks = [];
+	let coarse = false;
+	for (const [index, [beforeStart, afterStart]] of cuts.slice(0, -1).entries()) {
+		const [beforeEnd, afterEnd] = cuts[index + 1];
+		const segmentBefore = beforeLines.slice(beforeStart, beforeEnd);
+		const segmentAfter = afterLines.slice(afterStart, afterEnd);
+		const patch = structuredPatch("", "", segmentBefore.join(""), segmentAfter.join(""), void 0, void 0, {
+			context: CONTEXT_LINES,
+			timeout: Math.max(0, deadline - Date.now())
+		});
+		if (!patch) coarse = true;
+		for (const hunk of patch?.hunks ?? replaceHunk(segmentBefore, segmentAfter)) hunks.push({
+			...hunk,
+			oldStart: hunk.oldStart + beforeStart,
+			newStart: hunk.newStart + afterStart
+		});
+	}
+	const lines = hunks.flatMap((hunk) => hunk.lines);
+	return {
+		hunks,
+		stats: {
+			additions: lines.filter((line) => line[0] === "+").length,
+			deletions: lines.filter((line) => line[0] === "-").length,
+			hunks: hunks.length,
+			lines: lines.length,
+			coarse
+		}
+	};
+}
+function pageHunks({ hunks, cursor, limit }) {
+	const page = [];
+	let used = 0;
+	let start = 0;
+	for (const [index, hunk] of hunks.entries()) {
+		const offset = Math.max(0, cursor - start);
+		start += hunk.lines.length;
+		const remaining = hunk.lines.length - offset;
+		if (remaining <= 0) continue;
+		if (used > 0 && remaining > limit - used) break;
+		let take = Math.min(remaining, limit - used);
+		if (hunk.lines[offset + take]?.startsWith("\\")) take++;
+		page.push({
+			index,
+			...hunk,
+			lines: hunk.lines.slice(offset, offset + take)
+		});
+		used += take;
+		if (used >= limit) break;
+	}
+	const total = hunks.reduce((sum, hunk) => sum + hunk.lines.length, 0);
+	return {
+		hunks: page,
+		nextCursor: cursor + used < total ? cursor + used : null
+	};
+}
+//#endregion
 //#region src/generations.ts
 const READ_CONCURRENCY = 50;
 const MB = 1048576;
@@ -1199,8 +1435,8 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 				if (path.split("/").includes("..")) return;
 				const content = await files.storage.readItem(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 === FileSource.OUTPUT && !content.trim()) return;
+				hashes[path] = hashOf(source === FileSource.OUTPUT ? `${content.trim()}\n` : content);
 				bytes += Buffer.byteLength(content);
 				if (bytes <= maxSetBytes) await storage.writeItem(`${dirOf(jobId)}${source}/${path}`, content);
 			}
@@ -1302,7 +1538,7 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 //#region src/generationEvents.ts
 const MAX_QUEUED_EVENTS = 1024;
 const RESERVED_EVENTS = 64;
-const isDiscardable = (event) => event.type === "kubb:files:processing:update" || event.type === "kubb:info" || event.type === "kubb:success";
+const isDiscardable = (type) => type === "kubb:files:processing:update" || type === "kubb:info" || type === "kubb:success";
 /** Forwards selected Kubb lifecycle events to a native Cap'n Web stream. */
 function createGenerationStream(hooks, jobId) {
 	const unhooks = [];
@@ -1334,7 +1570,7 @@ function createGenerationStream(hooks, jobId) {
 			version: 1,
 			timestamp: Date.now()
 		};
-		if (controller.desiredSize <= RESERVED_EVENTS && isDiscardable(event)) return;
+		if (controller.desiredSize <= RESERVED_EVENTS && isDiscardable(type)) return;
 		if (controller.desiredSize <= 0) {
 			fail(/* @__PURE__ */ new Error(`Generation event stream exceeded ${MAX_QUEUED_EVENTS} queued events`));
 			return;
@@ -1438,7 +1674,10 @@ function createGenerationStream(hooks, jobId) {
 		}]
 	};
 	function forward(type) {
-		on(type, (...args) => emitEvent(type, projections[type](...args)));
+		on(type, (...args) => {
+			emitEvent(type, projections[type](...args));
+			if (!isDiscardable(type)) return new Promise((resolve) => setImmediate(resolve));
+		});
 	}
 	on("kubb:build:start", ({ config }) => {
 		root = config.root;
@@ -1498,7 +1737,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 Diagnostics.Error({
+		code: 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;
 }
@@ -1568,6 +1811,7 @@ var Agent = class extends RpcTarget {
 	#session;
 	#limits = resolveGenerationLimits();
 	#store;
+	#diffs = /* @__PURE__ */ new Map();
 	constructor({ options, session }) {
 		super();
 		this.#options = options;
@@ -1606,10 +1850,18 @@ var Agent = class extends RpcTarget {
 			message,
 			permission
 		});
-		throw new Error(message);
+		throw new Diagnostics.Error({
+			code: 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 Diagnostics.Error({
+			code: Diagnostics.code.internalError,
+			severity: "error",
+			message: "Studio must call connect() before any other command"
+		});
 	}
 	#logCommand(command, info) {
 		return emit(this.#options.hooks, "studio:command", {
@@ -1706,7 +1958,11 @@ var Agent = class extends 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 Diagnostics.Error({
+			code: 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 = {
@@ -1764,7 +2020,7 @@ var Agent = class extends RpcTarget {
 		}) : void 0;
 		const disk = diskFiles ? await this.#generations.keep({
 			jobId,
-			source: "disk",
+			source: FileSource.DISK,
 			files: diskFiles,
 			maxSetMb: this.#limits.maxSnapshotMb
 		}) : void 0;
@@ -1787,7 +2043,7 @@ var Agent = class extends RpcTarget {
 		});
 		const output = await this.#generations.keep({
 			jobId,
-			source: "output",
+			source: FileSource.OUTPUT,
 			files,
 			maxSetMb: this.#limits.maxMb
 		});
@@ -1859,14 +2115,14 @@ var Agent = class extends RpcTarget {
 	async readInput(input) {
 		this.#assertConnected();
 		if (!this.#permissions.allowReadAst) return this.#refuse({
-			message: READ_AST_NOT_ALLOWED_MESSAGE,
-			permission: "allowReadAst"
+			message: AgentMessage.READ_AST_NOT_ALLOWED,
+			permission: 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: GENERATION_GONE_MESSAGE });
+		if (!generation) return this.#refuse({ message: AgentMessage.GENERATION_GONE });
 		const kept = generation.inputBytes ? await this.#generations.readInput(input.jobId) : void 0;
-		if (!kept) return this.#refuse({ message: NO_INPUT_MESSAGE });
+		if (!kept) return this.#refuse({ message: AgentMessage.NO_INPUT });
 		await this.#logCommand("readInput", "read the API input");
 		return { input: kept };
 	}
@@ -1876,16 +2132,16 @@ var Agent = class extends RpcTarget {
 	async readFiles(input) {
 		this.#assertConnected();
 		if (!this.#permissions.allowRead) return this.#refuse({
-			message: READ_NOT_ALLOWED_MESSAGE,
-			permission: "allowRead"
+			message: AgentMessage.READ_NOT_ALLOWED,
+			permission: 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: GENERATION_GONE_MESSAGE });
+		if (!generation) return this.#refuse({ message: 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 ${MAX_PAGE_LINES} lines` });
-		const source = input.source === "disk" ? "disk" : "output";
+		const source = input.source === FileSource.DISK ? FileSource.DISK : 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,
@@ -1897,6 +2153,72 @@ var Agent = class extends 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: AgentMessage.READ_NOT_ALLOWED,
+			permission: 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 ${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: AgentMessage.GENERATION_GONE });
+		const baseSource = base.source === FileSource.DISK ? FileSource.DISK : 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: 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,
+			stats: {
+				additions: 0,
+				deletions: 0,
+				hunks: 0,
+				lines: 0,
+				coarse: false
+			}
+		};
+		const key = JSON.stringify([
+			jobId,
+			base.jobId,
+			baseSource,
+			path
+		]);
+		let diff = this.#diffs.get(key);
+		if (!diff) {
+			diff = diffHunks(beforeContent, afterContent ?? "");
+			this.#diffs.set(key, diff);
+			if (this.#diffs.size > 4) this.#diffs.delete(this.#diffs.keys().next().value);
+		}
+		await this.#logCommand("readDiff", `read the diff of ${path}`);
+		return {
+			...pageHunks({
+				hunks: diff.hunks,
+				cursor,
+				limit
+			}),
+			hasBase: true,
+			stats: diff.stats
+		};
+	}
 };
 const openWebSocketRpc = ({ url, token, instanceId, agent }) => {
 	const socket = new WebSocket(url, { headers: {
@@ -2105,7 +2427,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 Diagnostics.Error({
+			code: 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();
@@ -2146,7 +2473,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 Diagnostics.Error({
+				code: 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();
@@ -2154,7 +2486,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 Diagnostics.Error({
+			code: 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;
@@ -2162,7 +2498,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 Diagnostics.Error({
+			code: Diagnostics.code.unknown,
+			severity: "error",
+			message: response.error_description ?? `Pairing failed (${response.error})`,
+			help: "Pair again with `kubb studio login`."
+		});
 	}
 	throw new PairingExpiredError();
 }
@@ -2212,7 +2553,12 @@ function splitEntryPath(path) {
 			prefix
 		};
 	}
-	throw new Error(`Snapshot path is too long for a tar entry: ${path}`);
+	throw new Diagnostics.Error({
+		code: 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);
@@ -2245,7 +2591,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 Diagnostics.Error({
+			code: 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
@@ -2335,7 +2686,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(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 Diagnostics.Error({
+			code: 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) => resolveMeta(plugin).name);
@@ -2348,7 +2703,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 Diagnostics.Error({
+		code: 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: {
@@ -2357,7 +2717,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 ${MAX_SNAPSHOT_BYTES / 1024 / 1024} MB limit`);
+	if (bytes.length > 52428800) throw new Diagnostics.Error({
+		code: Diagnostics.code.unknown,
+		severity: "error",
+		message: `The snapshot is ${Math.ceil(bytes.length / 1024 / 1024)} MB, over the ${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({
@@ -2377,9 +2742,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 Diagnostics.Error({
+			code: 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 Diagnostics.Error({
+		code: Diagnostics.code.inputRequestFailed,
+		severity: "error",
+		message: `Kubb Studio returned no snapshot (status ${status})`,
+		help: "Try again later."
+	});
 	return _data.snapshot;
 }
 //#endregion