@kubb/studio 5.6.1 → 5.6.3

package/dist/index.js

@@ -4,14 +4,14 @@ import { createRequire } from "node:module";
 import { createHash, hash, randomUUID } from "node:crypto";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import path, { isAbsolute, join, relative, resolve, sep } from "node:path";
+import path, { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import process$1 from "node:process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { pathToFileURL } from "node:url";
 import { existsSync } from "node:fs";
-import { Diagnostics, Hookable, cacheStorage, createKubb, fsStorage, memoryStorage, resolveCacheDir } from "@kubb/core";
+import { Diagnostics, Hookable, cacheStorage, createKubb, fsStorage, getInputKind, memoryStorage, resolveCacheDir } from "@kubb/core";
 import { RpcTarget, newWebSocketRpcSession } from "capnweb";
-import { builders, detectCodeFormat, generateCode, parseModule } from "magicast";
+import { detectCodeFormat, parseExpression, parseModule } from "magicast";
 import { promisify, stripVTControlCharacters } from "node:util";
 import { ofetch } from "ofetch";
 import { gzip } from "node:zlib";
@@ -192,7 +192,7 @@ function getElapsedMs(hrStart) {
 }
 //#endregion
 //#region package.json
-var version = "5.6.1";
+var version = "5.6.3";
 //#endregion
 //#region src/resolveConfig.ts
 /**
@@ -237,6 +237,46 @@ function toPluginName(packageName) {
 function toPackageName(name) {
 	return name.startsWith("plugin-") ? `@kubb/${name}` : name;
 }
+function resolvesFrom(base, packageName) {
+	try {
+		createRequire(base).resolve(`${packageName}/package.json`);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Whether `packageName` resolves from the project at `root`, from this package, or from the `kubb`
+* package the project installs, which brings the plugins Kubb adds on its own such as
+* `@kubb/plugin-barrel`. Only resolves the package, it never runs it.
+*/
+function isInstalled({ packageName, root }) {
+	const project = pathToFileURL(`${root}/`);
+	if (resolvesFrom(project, packageName) || resolvesFrom(import.meta.url, packageName)) return true;
+	try {
+		return resolvesFrom(createRequire(project).resolve("kubb/package.json"), packageName);
+	} catch {
+		return false;
+	}
+}
+/**
+* The name Studio knows a plugin by: its `@kubb/plugin-*` package when one is installed, otherwise
+* the plugin's own `name`, so a plugin defined in the user's project is never reported as a Kubb
+* package that does not exist.
+*
+* @example
+* ```ts
+* toStudioName({ name: 'plugin-ts', root })              // '@kubb/plugin-ts'
+* toStudioName({ name: 'plugin-zod-operations', root })  // 'plugin-zod-operations', a local plugin
+* ```
+*/
+function toStudioName({ name, root }) {
+	const packageName = toPackageName(name);
+	return packageName !== name && isInstalled({
+		packageName,
+		root
+	}) ? packageName : name;
+}
 /**
 * Derives the conventional named export for a `@kubb/*` plugin package from its package name.
 *
@@ -332,6 +372,38 @@ async function resolvePeerDependencies(names) {
 	};
 }
 /**
+* Keys that reach an object's prototype when assigned. Never read from or written into options.
+*/
+const UNSAFE_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/**
+* Whether `key` can be used as an option key without touching an object's prototype.
+*/
+function isSafeKey(key) {
+	return !UNSAFE_KEYS.has(key);
+}
+/**
+* A JSON copy of plugin or adapter options: functions and other values JSON cannot hold are left
+* out, so nothing callable crosses the socket. Options that cannot be copied at all, such as a
+* circular structure, come back empty.
+*
+* @example
+* ```ts
+* toJSONOptions({ output: { path: 'types' }, group: { name: () => 'x' } }) // { output: { path: 'types' }, group: {} }
+* ```
+*/
+function toJSONOptions(options) {
+	try {
+		const copy = JSON.parse(JSON.stringify(options ?? {}, (key, value) => isSafeKey(key) && typeof value !== "bigint" ? value : void 0));
+		return isPlainObject(copy) ? copy : {};
+	} catch {
+		return {};
+	}
+}
+/**
 * Whether `value` is an object literal or a null-prototype object, not an array or class instance.
 */
 function isPlainObject(value) {
@@ -348,7 +420,7 @@ function isOptionValue(value) {
 	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
 	if (typeof value === "number") return Number.isFinite(value);
 	if (Array.isArray(value)) return value.every(isOptionValue);
-	if (isPlainObject(value)) return Object.values(value).every(isOptionValue);
+	if (isPlainObject(value)) return Object.entries(value).every(([key, entry]) => isSafeKey(key) && isOptionValue(entry));
 	return false;
 }
 /**
@@ -366,6 +438,7 @@ function isOptionValue(value) {
 function mergeOptions(disk, studio) {
 	const merged = { ...disk };
 	for (const [key, value] of Object.entries(studio)) {
+		if (!isSafeKey(key)) continue;
 		const current = disk[key];
 		if (isPlainObject(current) && isPlainObject(value)) {
 			merged[key] = mergeOptions(current, value);
@@ -398,11 +471,16 @@ async function mergePlugins(diskPlugins, studioPlugins) {
 	const merged = await Promise.all(activeDiskPlugins.map(async (diskPlugin) => {
 		const studioEntry = studioEntryByName.get(diskPlugin.name);
 		if (!studioEntry) return diskPlugin;
-		const options = mergeOptions(diskPlugin.options ?? {}, studioEntry.options ?? {});
+		const diskOptions = diskPlugin.options ?? {};
+		const options = mergeOptions(diskOptions, studioEntry.options ?? {});
+		const unchanged = JSON.stringify(toJSONOptions(options)) === JSON.stringify(toJSONOptions(diskOptions));
 		const [resolved] = await resolvePlugins([{
 			name: studioEntry.name,
 			options
-		}]);
+		}]).catch((cause) => {
+			if (unchanged) return [diskPlugin];
+			throw new Error(`Plugin "${diskPlugin.name}" is not an installed @kubb/plugin-* package, so Studio cannot change its options. Edit it in the config file, or only enable or disable it from Studio.`, { cause });
+		});
 		return resolved ?? diskPlugin;
 	}));
 	const studioOnly = activeStudioPlugins.filter((entry) => !diskNames.has(toPluginName(entry.name)));
@@ -432,142 +510,130 @@ async function mergeAdapter(diskAdapter, studioOptions) {
 */
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 /**
-* `key: value` as an object literal property, in the file's quote and key style.
-*
-* Uses magicast's literal builder for the key/value nodes, then wraps them as a Babel
-* `ObjectProperty`, the type the rest of this file reads.
-*/
-function literalProperty({ key, value }) {
-	const built = builders.literal({ [key]: value }).properties[0];
+* The marker line a `disable-plugin` writes above the block it comments out. It carries the block's
+* line count, so `enable-plugin` restores exactly those lines and not whatever comments follow.
+*/
+const DISABLED_MARKER = /^\/\/ kubb:disabled (.+)\s+(\d+)$/;
+const OPERATIONS = /* @__PURE__ */ new Set([
+	"set",
+	"remove",
+	"add-plugin",
+	"disable-plugin",
+	"enable-plugin"
+]);
+/**
+* Why an edit from Studio cannot be applied as sent, checked before anything reads its fields.
+* The edit crossed the wire, so its declared type is a promise the sender may not have kept.
+*/
+function invalidEdit(edit) {
+	const { operation, plugin, config, path, importName } = typeof edit === "object" && edit !== null ? edit : {};
+	if (typeof operation !== "string" || !OPERATIONS.has(operation)) return `unknown operation ${JSON.stringify(operation)}`;
+	if (typeof plugin !== "string" || !plugin) return "the edit names no plugin";
+	if (config !== void 0 && typeof config !== "string" && !Number.isSafeInteger(config)) return "config must name an entry or give its index";
+	if (operation === "set" || operation === "remove") {
+		if (!Array.isArray(path) || !path.every((key) => typeof key === "string" && key)) return "path must be a list of option names";
+		if (!path.length) return "no option path given";
+		const unsafe = path.find((key) => !isSafeKey(key));
+		if (unsafe !== void 0) return `${unsafe} cannot be used as an option name`;
+	}
+	if (operation === "add-plugin" && importName !== void 0 && typeof importName !== "string") return "importName must be a string";
+}
+/** 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");
 	return {
-		type: "ObjectProperty",
-		key: built.key,
-		value: built.value,
-		computed: false,
-		shorthand: false
+		start: node.start,
+		end: node.end
 	};
 }
-/**
-* Marks the comment block a `disable-plugin` leaves behind, so `enable-plugin` can find its way
-* back to the exact lines it commented out. Carries the block's line count, so `enable-plugin`
-* restores exactly those lines instead of scanning forward through whatever comments follow.
-*/
-const DISABLED_MARKER = "kubb:disabled";
-/**
-* The plugin and comment-block length a marker line names, when `line` is one.
-*/
-function parseMarker(line) {
-	const trimmed = line.trim();
-	if (!trimmed.startsWith(`// ${DISABLED_MARKER} `)) return;
-	const match = trimmed.slice(`// ${DISABLED_MARKER} `.length).match(/^(.+)\s+(\d+)$/);
-	return match ? {
-		plugin: match[1],
-		lineCount: Number(match[2])
-	} : void 0;
+/** `source` with the text between `start` and `end` replaced by `text`. */
+function splice(source, start, end, text = "") {
+	return `${source.slice(0, start)}${text}${source.slice(end)}`;
+}
+function bodyOf(mod) {
+	return mod.$ast.type === "Program" ? mod.$ast.body : [];
 }
 /**
 * Steps through a config's wrappers to the object literal underneath: a `satisfies`/`as`
 * assertion, a `() => ...` factory, or a factory whose block body returns the config.
 */
 function unwrap(node) {
-	if (!node) return;
+	if (!node) return void 0;
 	if (node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression") return unwrap(node.expression);
 	if (node.type !== "ArrowFunctionExpression" && node.type !== "FunctionExpression") return node;
 	if (node.body.type !== "BlockStatement") return unwrap(node.body);
 	return unwrap(node.body.body.find((statement) => statement.type === "ReturnStatement")?.argument);
 }
+function isModuleExports(node) {
+	return node.type === "MemberExpression" && !node.computed && node.object.type === "Identifier" && node.object.name === "module" && node.property.type === "Identifier" && node.property.name === "exports";
+}
 /**
-* Every config object in `export default defineConfig(...)`, or why the file is unmanaged.
-*
-* An array export gets one entry per element, matching {@link ConfigRef}'s numeric index.
+* Parses `source` and finds every config object in `export default defineConfig(...)` or
+* `module.exports = defineConfig(...)`, or why the file is unmanaged. An array export gets one entry
+* per element, matching a numeric `config` index.
 *
 * Walks the parsed AST rather than magicast's proxies, which throw on node types they cannot
 * cast, most of what an unmanaged config file is made of.
 */
-function findConfigs(mod) {
-	const exported = unwrap((mod.$ast.type === "Program" ? mod.$ast.body : []).find((node) => node.type === "ExportDefaultDeclaration")?.declaration);
-	if (!exported) return { reason: "no default export found" };
-	if (exported.type !== "CallExpression" || exported.callee.type !== "Identifier" || exported.callee.name !== "defineConfig") return { reason: "default export is not a defineConfig(...) call" };
-	const argument = unwrap(exported.arguments[0]);
-	if (!argument) return { reason: "defineConfig(...) was called without a config" };
-	if (argument.type === "ArrayExpression") {
-		const configs = [];
-		for (const element of argument.elements) {
-			const entry = unwrap(element);
-			if (entry?.type !== "ObjectExpression") return { reason: "config is not an object literal" };
-			configs.push(entry);
+function parseConfigs(source) {
+	let mod;
+	try {
+		mod = parseModule(source);
+	} catch {
+		return { reason: "the config file could not be parsed" };
+	}
+	let exported;
+	let kind = "esm";
+	for (const node of bodyOf(mod)) {
+		if (node.type === "ExportDefaultDeclaration") {
+			exported = node.declaration;
+			break;
+		}
+		if (node.type === "ExpressionStatement" && node.expression.type === "AssignmentExpression" && isModuleExports(node.expression.left)) {
+			exported = node.expression.right;
+			kind = "cjs";
+			break;
 		}
-		return { configs };
 	}
-	if (argument.type !== "ObjectExpression") return { reason: "config is not an object literal" };
-	return { configs: [argument] };
+	const value = unwrap(exported);
+	if (!value) return { reason: "no `export default` or `module.exports` found" };
+	if (value.type !== "CallExpression" || value.callee.type !== "Identifier" || value.callee.name !== "defineConfig") return { reason: "the exported config is not a defineConfig(...) call" };
+	const argument = unwrap(value.arguments[0]);
+	if (!argument) return { reason: "defineConfig(...) was called without a config" };
+	const entries = argument.type === "ArrayExpression" ? argument.elements.map((element) => unwrap(element)) : [argument];
+	const configs = entries.filter((entry) => entry?.type === "ObjectExpression");
+	if (configs.length !== entries.length) return { reason: "config is not an object literal" };
+	return {
+		mod,
+		configs,
+		kind
+	};
 }
-/**
-* The config entry an edit names, defaulting to the first when it names none.
-*/
-function selectConfig(configs, ref) {
-	if (ref === void 0) return configs[0];
-	if (typeof ref === "number") return configs[ref];
-	return configs.find((config) => configName(config) === ref);
+/** The name of a `key` or `'key'` member, `undefined` for a spread or a computed key. */
+function memberKey(entry) {
+	if (entry.type === "SpreadElement" || entry.computed) return void 0;
+	return entry.key.type === "Identifier" ? entry.key.name : entry.key.type === "StringLiteral" ? entry.key.value : void 0;
+}
+/** The member named `key`. The last one wins when the key repeats, as it does when the object is evaluated. */
+function findMember(node, key) {
+	const index = node.properties.findLastIndex((entry) => memberKey(entry) === key);
+	return index === -1 ? void 0 : {
+		member: node.properties[index],
+		index
+	};
+}
+/** The value node of a member. A method or accessor is its own value: it is code, never a literal. */
+function property(node, key) {
+	const member = findMember(node, key)?.member;
+	return member?.type === "ObjectProperty" ? member.value : member;
 }
 function configName(config) {
 	const name = property(config, "name");
 	return name?.type === "StringLiteral" ? name.value : void 0;
 }
-/**
-* The name of an object literal property, for the two key shapes a config uses: `key: value` and
-* `'key': value`. `undefined` for a computed key, which the patcher never touches.
-*/
-function propertyKey(entry) {
-	if (entry.key.type === "Identifier") return entry.key.name;
-	if (entry.key.type === "StringLiteral") return entry.key.value;
-}
-/**
-* The index of an object literal's own property named `key`, `-1` when it has none.
-*/
-function entryIndex({ node, key }) {
-	return node.properties.findIndex((entry) => entry.type === "ObjectProperty" && propertyKey(entry) === key);
-}
-/**
-* The value node of an object literal's own property.
-*/
-function property(node, key) {
-	const index = entryIndex({
-		node,
-		key
-	});
-	return index === -1 ? void 0 : node.properties[index].value;
-}
-/**
-* Writes `key: value` on an object literal, replacing the value when the property is already there.
-*
-* An existing property has its value swapped in place rather than being replaced whole, so recast
-* reprints only that value and leaves the object's own layout alone.
-*/
-function setProperty({ node, key, value }) {
-	const entry = literalProperty({
-		key,
-		value
-	});
-	const index = entryIndex({
-		node,
-		key
-	});
-	if (index === -1) {
-		node.properties.push(entry);
-		return;
-	}
-	node.properties[index].value = entry.value;
-}
-/**
-* Drops `key` from an object literal.
-*/
-function removeProperty({ node, key }) {
-	const index = entryIndex({
-		node,
-		key
-	});
-	if (index !== -1) node.properties.splice(index, 1);
+/** Whether a `...spread` after the member at `index` could override it. */
+function isShadowed(node, index) {
+	return node.properties.slice(index + 1).some((entry) => entry.type === "SpreadElement");
 }
 /**
 * Reads a literal node's value: a primitive, or an object/array built only from primitives.
@@ -575,42 +641,109 @@ function removeProperty({ node, key }) {
 * whether a node is a literal at all.
 */
 function readLiteral(node) {
-	if (!node) return;
-	if (node.type === "StringLiteral" || node.type === "NumericLiteral" || node.type === "BooleanLiteral") return node.value;
-	if (node.type === "NullLiteral") return null;
-	if (node.type === "TemplateLiteral") return node.expressions.length === 0 ? node.quasis[0]?.value.cooked ?? "" : void 0;
-	if (node.type === "UnaryExpression") {
-		const value = readLiteral(node.argument);
-		if (typeof value !== "number") return;
-		if (node.operator === "-") return -value;
-		if (node.operator === "+") return value;
-		return;
-	}
-	if (node.type === "ArrayExpression") {
-		const values = node.elements.map((element) => element ? readLiteral(element) : void 0);
-		return values.every((value) => value !== void 0) ? values : void 0;
-	}
-	if (node.type === "ObjectExpression") {
-		const entries = {};
-		for (const entry of node.properties) {
-			if (entry.type !== "ObjectProperty") return;
-			const key = propertyKey(entry);
-			const value = readLiteral(entry.value);
-			if (key === void 0 || value === void 0) return;
-			entries[key] = value;
+	switch (node?.type) {
+		case "StringLiteral":
+		case "NumericLiteral":
+		case "BooleanLiteral": return node.value;
+		case "NullLiteral": return null;
+		case "TemplateLiteral": return node.expressions.length ? void 0 : node.quasis[0]?.value.cooked ?? "";
+		case "UnaryExpression": {
+			const value = readLiteral(node.argument);
+			if (typeof value !== "number") return void 0;
+			return node.operator === "-" ? -value : node.operator === "+" ? value : void 0;
+		}
+		case "ArrayExpression": {
+			const values = node.elements.map((element) => readLiteral(element));
+			return values.every((value) => value !== void 0) ? values : void 0;
+		}
+		case "ObjectExpression": {
+			const entries = {};
+			for (const entry of node.properties) {
+				if (entry.type !== "ObjectProperty") return void 0;
+				const key = memberKey(entry);
+				const value = readLiteral(entry.value);
+				if (key === void 0 || !isSafeKey(key) || value === void 0) return void 0;
+				entries[key] = value;
+			}
+			return entries;
 		}
-		return entries;
 	}
 }
-/**
-* Maps a factory identifier in the file back to the module it was imported from.
-*/
+/** Writes `value` as a single-line literal with the file's quote style. */
+function printValue(value, quote) {
+	if (typeof value === "string") {
+		const escaped = JSON.stringify(value).slice(1, -1);
+		return quote === `"` ? `"${escaped}"` : `'${escaped.replaceAll(`\\"`, `"`).replaceAll(`'`, `\\'`)}'`;
+	}
+	if (value === null || typeof value !== "object") return String(value);
+	if (Array.isArray(value)) return `[${value.map((item) => printValue(item, quote)).join(", ")}]`;
+	const entries = Object.entries(value);
+	return entries.length ? `{ ${entries.map(([key, item]) => `${printKey(key, quote)}: ${printValue(item, quote)}`).join(", ")} }` : "{}";
+}
+/** An object key as source text: bare when it is an identifier, quoted otherwise. */
+function printKey(key, quote) {
+	return IDENTIFIER.test(key) ? key : printValue(key, quote);
+}
+/** `value` wrapped in one object per key of `path`: `nest(['enum', 'type'], 'enum')` is `{ enum: { type: 'enum' } }`. */
+function nest(path, value) {
+	return path.reduceRight((inner, key) => ({ [key]: inner }), value);
+}
+/**
+* Adds `text` as the last item of an object or array literal, following its layout: on a line of
+* its own with the last item's indentation when the literal spans lines, inline otherwise.
+*/
+function insertItem(source, container, text) {
+	const { start, end } = rangeOf(container);
+	const last = (container.type === "ObjectExpression" ? container.properties : container.elements).filter((item) => item !== null).at(-1);
+	if (!last) {
+		const inner = source.slice(start + 1, end - 1);
+		if (inner.trim()) return splice(source, start + 1, start + 1, /^\s/.test(inner) ? `${text},` : `${text}, `);
+		return splice(source, start, end, container.type === "ObjectExpression" ? `{ ${text} }` : `[${text}]`);
+	}
+	const lastRange = rangeOf(last);
+	const between = source.slice(lastRange.end, end - 1);
+	if (!between.includes("\n")) return splice(source, lastRange.end, lastRange.end, `, ${text}`);
+	const lineStart = source.lastIndexOf("\n", lastRange.start - 1) + 1;
+	const indent = source.slice(lineStart).match(/^[ \t]*/)?.[0] ?? "";
+	const lineEnd = source.indexOf("\n", lastRange.end);
+	const comma = /^\s*,/.test(between);
+	return `${source.slice(0, lastRange.end)}${comma ? "" : ","}${source.slice(lastRange.end, lineEnd)}\n${indent}${text}${comma ? "," : ""}${source.slice(lineEnd)}`;
+}
+/** Drops the member at `index` from an object literal, with its own lines when it sits on them alone. */
+function removeMember(source, node, index) {
+	if (node.properties.length === 1) return splice(source, rangeOf(node).start, rangeOf(node).end, "{}");
+	const { start, end } = rangeOf(node.properties[index]);
+	const lineStart = source.lastIndexOf("\n", start - 1) + 1;
+	const nextNewline = source.indexOf("\n", end);
+	const lineEnd = nextNewline === -1 ? source.length : nextNewline;
+	if (!source.slice(lineStart, start).trim() && /^\s*,?\s*(\/\/.*)?$/.test(source.slice(end, lineEnd))) return splice(source, lineStart, Math.min(lineEnd + 1, source.length));
+	const next = node.properties[index + 1];
+	return next ? splice(source, start, rangeOf(next).start) : splice(source, rangeOf(node.properties[index - 1]).end, end);
+}
+/** The module a `require('...')` call loads, when `node` is one. */
+function requiredModule(node) {
+	if (node?.type !== "CallExpression" || node.callee.type !== "Identifier" || node.callee.name !== "require") return void 0;
+	const [argument] = node.arguments;
+	return argument?.type === "StringLiteral" ? argument.value : void 0;
+}
+/** Maps each identifier the file imports, through `import { x } from` or `const { x } = require(...)`, to its module. */
 function importedFrom(mod) {
-	return new Map(mod.imports.$items.map((item) => [item.local, item.from]));
+	const imports = /* @__PURE__ */ new Map();
+	for (const statement of bodyOf(mod)) {
+		if (statement.type === "ImportDeclaration") {
+			for (const specifier of statement.specifiers) imports.set(specifier.local.name, statement.source.value);
+			continue;
+		}
+		if (statement.type !== "VariableDeclaration") continue;
+		for (const declarator of statement.declarations) {
+			const from = requiredModule(declarator.init);
+			if (from === void 0 || declarator.id.type !== "ObjectPattern") continue;
+			for (const entry of declarator.id.properties) if (entry.type === "ObjectProperty" && entry.value.type === "Identifier") imports.set(entry.value.name, from);
+		}
+	}
+	return imports;
 }
-/**
-* Every `pluginX(...)` element of a config's plugins array that resolves to an import.
-*/
+/** Every `pluginX(...)` element of a config's plugins array that resolves to an import. */
 function pluginCalls(mod, config) {
 	const plugins = property(config, "plugins");
 	if (plugins?.type !== "ArrayExpression") return [];
@@ -626,19 +759,51 @@ function pluginCalls(mod, config) {
 	});
 }
 /**
-* Plugins a previous `disable-plugin` commented out of this config, keyed by package name.
-*
-* Read from the marker lines rather than the AST, since a commented-out call is no longer a node.
+* The blocks a previous `disable-plugin` commented out of this config, read from the marker lines
+* since a commented-out call is no longer a node. `code` holds the block's lines as they were.
 */
-function disabledMarkers(source) {
-	return source.split("\n").flatMap((line, index) => {
-		const marker = parseMarker(line);
-		return marker ? [{
-			packageName: marker.plugin,
-			line: index + 1
-		}] : [];
+function disabledBlocks(source, config) {
+	const lines = source.split("\n");
+	const first = config.loc?.start.line ?? 0;
+	const last = config.loc?.end.line ?? Number.POSITIVE_INFINITY;
+	return lines.flatMap((text, index) => {
+		const match = text.trim().match(DISABLED_MARKER);
+		if (!match || index + 1 < first || index + 1 > last) return [];
+		const end = index + 1 + Number(match[2]);
+		const code = lines.slice(index + 1, end).map((line) => line.replace(/^(\s*)\/\/ ?/, "$1").replace(/^\s+$/, ""));
+		return [{
+			packageName: match[1],
+			line: index + 1,
+			end,
+			code
+		}];
 	});
 }
+/** The top-level options of a plugin call, each flagged with whether Studio may write it. */
+function readOptions(call) {
+	const entries = {};
+	const options = call.arguments[0];
+	if (options?.type !== "ObjectExpression") return entries;
+	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 } : {
+			literal: true,
+			value
+		};
+	}
+	return entries;
+}
+/** The options a commented-out plugin call holds, so Studio can show them while it is disabled. */
+function readDisabledOptions(code) {
+	try {
+		const call = parseExpression(code.join("\n").trim().replace(/,$/, "")).$ast;
+		return call.type === "CallExpression" ? readOptions(call) : {};
+	} catch {
+		return {};
+	}
+}
 /**
 * Reads which plugins the file declares and which of their options Studio may write.
 *
@@ -658,37 +823,27 @@ function readConfig(source) {
 	};
 	const { mod, configs } = parsed;
 	const importNames = new Map([...importedFrom(mod)].map(([local, from]) => [from, local]));
-	const disabled = disabledMarkers(source);
 	return {
 		managed: true,
 		configs: configs.map((config) => {
-			const plugins = pluginCalls(mod, config).map(({ importName, packageName, call }) => {
-				const entries = {};
-				const options = call.arguments[0];
-				if (options?.type === "ObjectExpression") for (const entry of options.properties) {
-					if (entry.type !== "ObjectProperty") continue;
-					const key = propertyKey(entry);
-					if (key === void 0) continue;
-					const value = readLiteral(entry.value);
-					entries[key] = value === void 0 ? { literal: false } : {
-						literal: true,
-						value
-					};
-				}
-				return {
+			const active = pluginCalls(mod, config).map(({ importName, packageName, call }) => ({
+				line: call.loc?.start.line ?? 0,
+				plugin: {
 					importName,
 					packageName,
-					options: entries
-				};
-			});
-			const start = config.loc?.start.line ?? 0;
-			const end = config.loc?.end.line ?? Number.POSITIVE_INFINITY;
-			for (const { packageName } of disabled.filter((entry) => entry.line >= start && entry.line <= end)) plugins.push({
-				importName: importNames.get(packageName) ?? toExportName(packageName),
-				packageName,
-				options: {},
-				disabled: true
-			});
+					options: readOptions(call)
+				}
+			}));
+			const disabled = disabledBlocks(source, config).map(({ packageName, line, code }) => ({
+				line,
+				plugin: {
+					importName: importNames.get(packageName) ?? toExportName(packageName),
+					packageName,
+					options: readDisabledOptions(code),
+					disabled: true
+				}
+			}));
+			const plugins = [...active, ...disabled].sort((a, b) => a.line - b.line).map(({ plugin }) => plugin);
 			return {
 				name: configName(config),
 				plugins
@@ -697,173 +852,131 @@ function readConfig(source) {
 	};
 }
 /**
-* The options object of a plugin call, when it was called with one.
+* Walks `path` through a plugin's options to the literal at its last key. Returns `missing` with
+* the index of the first key that is not there yet, so `set` can write the rest of the path as one
+* nested literal and `remove` can report it as unset. Refuses a value customized in code, so it is
+* never overwritten.
 */
-function getOptions(call) {
-	const options = call.arguments[0];
-	return options?.type === "ObjectExpression" ? options : void 0;
-}
-/**
-* The options object of a plugin call, creating an empty one when the plugin was called bare.
-*/
-function ensureOptions(call) {
-	if (call.arguments.length === 0) call.arguments.push({
-		type: "ObjectExpression",
-		properties: []
-	});
-	return getOptions(call);
-}
-/**
-* Walks `path` down to the object holding its last key, descending only through object literals.
-*/
-function optionParent(options, path) {
+function walk(options, path) {
 	let object = options;
-	for (const [index, key] of path.entries()) {
-		if (index === path.length - 1) return {
+	for (const [depth, key] of path.entries()) {
+		const found = findMember(object, key);
+		if (!found) return {
 			object,
-			key
+			missing: depth
 		};
-		if (property(object, key) === void 0) setProperty({
-			node: object,
-			key,
-			value: {}
-		});
-		const next = property(object, key);
-		if (next?.type !== "ObjectExpression") return { reason: `${key} is not an object, so ${path.join(".")} cannot be reached` };
-		object = next;
+		if (isShadowed(object, found.index)) return { reason: `${path.slice(0, depth + 1).join(".")} can be overridden by a spread after it, so it is customized in code` };
+		const { member, index } = found;
+		if (depth === path.length - 1) return member.type === "ObjectProperty" && readLiteral(member.value) !== void 0 ? {
+			object,
+			index,
+			value: member.value
+		} : { reason: `${path.join(".")} is customized in code` };
+		if (member.type !== "ObjectProperty" || member.value.type !== "ObjectExpression") return { reason: `${key} is not an object, so ${path.join(".")} cannot be reached` };
+		object = member.value;
 	}
 	return { reason: "no option path given" };
 }
-/**
-* Writes `value` at `path` inside a plugin call's options, creating the options object and any
-* intermediate object along the path as needed. Refuses when the current value at `path` is
-* something other than a literal, so an option customized in code is never overwritten.
-*/
-function applySet(call, path, value) {
-	if (!isOptionValue(value)) return "the value is not a literal that can be written to a config file";
-	const options = ensureOptions(call);
-	if (!options) return "the plugin was not called with an object literal";
-	const target = optionParent(options, path);
-	if ("reason" in target) return target.reason;
-	const current = property(target.object, target.key);
-	if (current !== void 0 && readLiteral(current) === void 0) return `${path.join(".")} is customized in code`;
-	setProperty({
-		node: target.object,
-		key: target.key,
-		value
-	});
+/** Writes `value` at `path` inside a plugin call's options, adding the options object and any intermediate object it needs. */
+function applySet(source, call, path, value, quote) {
+	if (!isOptionValue(value)) return { reason: "the value is not a literal that can be written to a config file" };
+	const options = call.arguments[0];
+	if (!options) {
+		const closing = rangeOf(call).end - 1;
+		if (source[closing] !== ")") return { reason: "the plugin call could not be located in the file" };
+		return { source: splice(source, closing, closing, printValue(nest(path, value), quote)) };
+	}
+	if (options.type !== "ObjectExpression") return { reason: "the plugin was not called with an object literal" };
+	const target = walk(options, path);
+	if ("reason" in target) return target;
+	if ("missing" in target) {
+		const [key, ...rest] = path.slice(target.missing);
+		return { source: insertItem(source, target.object, `${printKey(key, quote)}: ${printValue(nest(rest, value), quote)}`) };
+	}
+	return { source: splice(source, rangeOf(target.value).start, rangeOf(target.value).end, printValue(value, quote)) };
+}
+/** Deletes the option at `path`, falling the plugin back to its default for it. */
+function applyRemove(source, call, path) {
+	const options = call.arguments[0];
+	if (options?.type !== "ObjectExpression") return { reason: "the plugin has no options to remove" };
+	const target = walk(options, path);
+	if ("reason" in target) return target;
+	if ("missing" in target) return { reason: `${path.join(".")} is not set` };
+	return { source: removeMember(source, target.object, target.index) };
 }
 /**
-* Deletes the property at `path` inside a plugin call's options, falling the plugin back to its
-* default for that option. Refuses when the value at `path` is not a literal, for the same reason
-* `applySet` does.
+* Writes an import after the last one already in the file, matching its quote style and whether it
+* ends in a semicolon: `import { x } from '...'`, or `const { x } = require('...')` in a CommonJS file.
+* The last import is read off the AST, so a multi-line `import {\n  x,\n} from '...'` counts to its closing line.
 */
-function applyRemove(call, path) {
-	const options = getOptions(call);
-	if (!options) return "the plugin has no options to remove";
-	const target = optionParent(options, path);
-	if ("reason" in target) return target.reason;
-	const current = property(target.object, target.key);
-	if (current === void 0) return `${path.join(".")} is not set`;
-	if (readLiteral(current) === void 0) return `${path.join(".")} is customized in code`;
-	removeProperty({
-		node: target.object,
-		key: target.key
-	});
+function insertImport(source, { mod, kind }, importName, moduleSpecifier) {
+	const afterLine = bodyOf(mod).findLast((node) => kind === "esm" ? node.type === "ImportDeclaration" : node.type === "VariableDeclaration" && node.declarations.some((declarator) => requiredModule(declarator.init) !== void 0))?.loc?.end.line ?? 0;
+	const lines = source.split("\n");
+	const lastImportLine = afterLine > 0 ? lines[afterLine - 1] : void 0;
+	const quote = lastImportLine?.includes(`"`) ? `"` : `'`;
+	const semicolon = lastImportLine?.trimEnd().endsWith(";") ? ";" : "";
+	const specifier = `${quote}${moduleSpecifier}${quote}`;
+	lines.splice(afterLine, 0, kind === "esm" ? `import { ${importName} } from ${specifier}${semicolon}` : `const { ${importName} } = require(${specifier})${semicolon}`);
+	if (afterLine === 0) lines.splice(1, 0, "");
+	return lines.join("\n");
 }
 /**
-* Adds a `pluginX(...)` call to a config's plugins array. Replaying the same add is a no-op, while
-* an import name collision with an unrelated package remains an error.
+* Adds a `pluginX(...)` call to a config's plugins array, and its import. Replaying the same add is
+* a no-op, while an import name collision with an unrelated package remains an error.
 */
-function applyAddPlugin(mod, config, edit) {
+function applyAddPlugin(source, parsed, config, edit, quote) {
 	if (!isKubbPluginSpecifier(edit.plugin)) return { reason: `"${edit.plugin}" is not a @kubb/plugin-* package` };
 	const importName = edit.importName ?? toExportName(edit.plugin);
 	if (!IDENTIFIER.test(importName)) return { reason: `"${importName}" is not a valid import name` };
-	if (pluginCalls(mod, config).some((plugin) => plugin.packageName === edit.plugin)) return { noop: true };
-	const taken = importedFrom(mod).get(importName);
+	if (pluginCalls(parsed.mod, config).some((plugin) => plugin.packageName === edit.plugin)) return { source };
+	const taken = importedFrom(parsed.mod).get(importName);
 	if (taken && taken !== edit.plugin) return { reason: `${importName} is already imported from ${taken}` };
 	const options = edit.options ?? {};
 	if (!isOptionValue(options)) return { reason: "the options are not literals that can be written to a config file" };
 	const plugins = property(config, "plugins");
 	if (plugins?.type !== "ArrayExpression") return { reason: "plugins is not an array literal" };
-	const call = Object.keys(options).length ? builders.functionCall(importName, options) : builders.functionCall(importName);
-	plugins.elements.push(call.$ast);
-	return taken ? {} : { addImport: {
-		importName,
-		moduleSpecifier: edit.plugin
-	} };
+	const next = insertItem(source, plugins, `${importName}(${Object.keys(options).length ? printValue(options, quote) : ""})`);
+	return { source: taken ? next : insertImport(next, parsed, importName, edit.plugin) };
 }
-/**
-* Comments out a plugin call in place, keeping its options on disk so `enable-plugin` can restore
-* them exactly. Operates on `source` text rather than the AST: a commented-out call is no longer a
-* node magicast can address, and the surrounding array must not reflow when its element count
-* never actually changes.
-*/
+/** Comments out a plugin call in place, keeping its options on disk so `enable-plugin` can restore them exactly. */
 function disablePlugin(source, mod, config, plugin) {
-	const target = pluginCalls(mod, config).find((entry) => entry.packageName === plugin);
-	if (!target) return { reason: `${plugin} is not in the plugins array` };
-	const loc = target.call.loc;
-	if (!loc?.start || !loc.end) return { reason: `${plugin} has no source location to comment out` };
+	const loc = pluginCalls(mod, config).find((entry) => entry.packageName === plugin)?.call.loc;
+	if (!loc) return { reason: `${plugin} is not in the plugins array` };
 	const lines = source.split("\n");
 	const from = loc.start.line - 1;
 	const to = loc.end.line - 1;
 	const firstLine = lines[from] ?? "";
-	const lastLine = lines[to] ?? "";
-	if (firstLine.slice(0, loc.start.column).trim() !== "" || !/^,?\s*$/.test(lastLine.slice(loc.end.column))) return { reason: `${plugin} shares a line with other code, so it cannot be commented out safely` };
+	if (firstLine.slice(0, loc.start.column).trim() || !/^,?\s*$/.test((lines[to] ?? "").slice(loc.end.column))) return { reason: `${plugin} shares a line with other code, so it cannot be commented out safely` };
 	const indent = firstLine.match(/^\s*/)?.[0] ?? "";
-	const commented = lines.slice(from, to + 1).map((line) => line.trim() ? `${indent}// ${line.slice(indent.length)}` : indent ? `${indent}//` : "//");
-	lines.splice(from, to - from + 1, `${indent}// ${DISABLED_MARKER} ${plugin} ${commented.length}`, ...commented);
+	const commented = lines.slice(from, to + 1).map((line) => line.trim() ? `${indent}// ${line.slice(indent.length)}` : `${indent}//`);
+	lines.splice(from, commented.length, `${indent}// kubb:disabled ${plugin} ${commented.length}`, ...commented);
 	return { source: lines.join("\n") };
 }
-/**
-* Uncomments the block a previous `disable-plugin` left behind for `plugin`.
-*/
-function enablePlugin(source, plugin) {
+/** Uncomments the block a previous `disable-plugin` left behind for `plugin` in this config. */
+function enablePlugin(source, config, plugin) {
+	const block = disabledBlocks(source, config).find((entry) => entry.packageName === plugin);
+	if (!block) return { reason: `${plugin} is not disabled` };
 	const lines = source.split("\n");
-	for (const [index, line] of lines.entries()) {
-		const marker = parseMarker(line);
-		if (marker?.plugin !== plugin) continue;
-		const end = index + 1 + marker.lineCount;
-		const restored = lines.slice(index + 1, end).map((commented) => commented.replace(/^(\s*)\/\/ ?/, "$1"));
-		lines.splice(index, end - index, ...restored);
-		return { source: lines.join("\n") };
-	}
-	return { reason: `${plugin} is not disabled` };
-}
-/**
-* Parses `source` and finds the config entries it exports.
-*/
-function parseConfigs(source) {
-	let mod;
-	try {
-		mod = parseModule(source);
-	} catch {
-		return { reason: "the config file could not be parsed" };
-	}
-	const found = findConfigs(mod);
-	return "reason" in found ? found : {
-		mod,
-		configs: found.configs
-	};
+	lines.splice(block.line - 1, block.end - block.line + 1, ...block.code);
+	return { source: lines.join("\n") };
 }
-/**
-* Re-parses `source` and resolves the config entry an edit targets. Every edit re-parses rather
-* than sharing one module across the batch, since the disable/enable edits rewrite `source` as
-* text and would otherwise leave the others working from a stale tree.
-*/
-function parseTarget(source, ref) {
+/** Applies one edit to `source`. Every edit re-parses the file, since the previous one rewrote it. */
+function applyEdit(source, edit, quote) {
 	const parsed = parseConfigs(source);
 	if ("reason" in parsed) return parsed;
-	const config = selectConfig(parsed.configs, ref);
+	const ref = edit.config;
+	const config = typeof ref === "string" ? parsed.configs.find((entry) => configName(entry) === ref) : parsed.configs[ref ?? 0];
 	if (!config) return { reason: `no config entry found for ${JSON.stringify(ref)}` };
-	return {
-		mod: parsed.mod,
-		config
-	};
+	if (edit.operation === "disable-plugin") return disablePlugin(source, parsed.mod, config, edit.plugin);
+	if (edit.operation === "enable-plugin") return enablePlugin(source, config, edit.plugin);
+	if (edit.operation === "add-plugin") return applyAddPlugin(source, parsed, config, edit, quote);
+	const call = pluginCalls(parsed.mod, config).find((plugin) => plugin.packageName === edit.plugin)?.call;
+	if (!call) return { reason: disabledBlocks(source, config).some((block) => block.packageName === edit.plugin) ? `${edit.plugin} is disabled, enable it first` : `${edit.plugin} is not in the plugins array` };
+	return edit.operation === "set" ? applySet(source, call, edit.path, edit.value, quote) : applyRemove(source, call, edit.path);
 }
 /**
-* Applies edits to a `kubb.config.ts` in place. Every node the edits do not touch keeps its
-* original text, so comments, formatting, and hand-written code around the config survive.
+* Applies edits to a `kubb.config.ts` in place. Each edit rewrites only the text it targets, so
+* comments, formatting, and hand-written code around the config survive.
 *
 * Edits are independent: one that cannot be applied is reported in `outcomes` and the rest still run.
 *
@@ -873,25 +986,19 @@ function parseTarget(source, ref) {
 *   { operation: 'set', plugin: '@kubb/plugin-ts', path: ['enum', 'type'], value: 'enum' },
 * ])
 * ```
-*
-* @note recast always reprints a semicolon on a reprinted statement, so editing a block-body
-* `defineConfig` in a semicolon-free file adds one to the `return` line. This is a known gap.
-* Strip it when `detectCodeFormat` reports `useSemi: false`, if it turns out to matter in practice.
 */
 function applyConfigEdits(source, edits) {
 	let current = source;
-	const format = detectCodeFormat(source);
-	const endsWithNewline = source.endsWith("\n");
+	const quote = detectCodeFormat(source).quote === "double" ? `"` : `'`;
 	const outcomes = edits.map((edit) => {
-		const target = parseTarget(current, edit.config);
-		if ("reason" in target) return {
+		const invalid = invalidEdit(edit);
+		if (invalid) return {
 			edit,
 			applied: false,
-			reason: target.reason
+			reason: invalid
 		};
-		const { mod, config } = target;
-		if (edit.operation === "disable-plugin" || edit.operation === "enable-plugin") {
-			const result = edit.operation === "disable-plugin" ? disablePlugin(current, mod, config, edit.plugin) : enablePlugin(current, edit.plugin);
+		try {
+			const result = applyEdit(current, edit, quote);
 			if ("reason" in result) return {
 				edit,
 				applied: false,
@@ -902,44 +1009,13 @@ function applyConfigEdits(source, edits) {
 				edit,
 				applied: true
 			};
-		}
-		if (edit.operation === "add-plugin") {
-			const result = applyAddPlugin(mod, config, edit);
-			if ("reason" in result) return {
-				edit,
-				applied: false,
-				reason: result.reason
-			};
-			if ("noop" in result) return {
-				edit,
-				applied: true
-			};
-			const afterLine = lastImportEndLine(mod);
-			let next = generateCode(mod, { format }).code;
-			if (result.addImport) next = insertImportLine({
-				source: next,
-				afterLine,
-				...result.addImport
-			});
-			current = withTrailingNewline(next, endsWithNewline);
+		} catch (error) {
 			return {
 				edit,
-				applied: true
+				applied: false,
+				reason: getErrorMessage(error)
 			};
 		}
-		const pluginCall = pluginCalls(mod, config).find((plugin) => plugin.packageName === edit.plugin);
-		if (!pluginCall) return {
-			edit,
-			applied: false,
-			reason: `${edit.plugin} is not in the plugins array`
-		};
-		const reason = edit.operation === "set" ? applySet(pluginCall.call, edit.path, edit.value) : applyRemove(pluginCall.call, edit.path);
-		if (!reason) current = withTrailingNewline(generateCode(mod, { format }).code, endsWithNewline);
-		return {
-			edit,
-			applied: !reason,
-			reason
-		};
 	});
 	return {
 		source: current,
@@ -947,42 +1023,12 @@ function applyConfigEdits(source, edits) {
 		changed: current !== source
 	};
 }
+/** Applies `edits` to the config file at `filePath`, writing it only when something changed. */
 async function writeConfigEdits({ filePath, edits }) {
 	const result = applyConfigEdits(await read(filePath), edits);
 	if (result.changed) await writeFile(filePath, result.source, "utf-8");
 	return result;
 }
-/**
-* The 1-based line where the file's last import declaration ends, or `0` when it has none. Read
-* off the parsed module, so a multi-line `import {\n  x,\n} from '...'` reports its closing line
-* rather than the `import` keyword.
-*/
-function lastImportEndLine(mod) {
-	return (mod.$ast.type === "Program" ? mod.$ast.body : []).filter((node) => node.type === "ImportDeclaration").at(-1)?.loc?.end.line ?? 0;
-}
-/**
-* Writes an import after the last one already in the file, matching its quote style and whether it
-* ends in a semicolon. `afterLine` is where that last import ends, `0` for a file with none.
-*
-* Written as plain text rather than through magicast's import builder, which prints a brand-new
-* import declaration with its own default spacing and a semicolon regardless of `format`, since
-* that formatting only governs nodes recast can diff against the original source.
-*/
-function insertImportLine({ source, importName, moduleSpecifier, afterLine }) {
-	const lines = source.split("\n");
-	const lastImportLine = afterLine > 0 ? lines[afterLine - 1] : void 0;
-	const quote = lastImportLine?.includes(`"`) ? `"` : `'`;
-	const line = `import { ${importName} } from ${quote}${moduleSpecifier}${quote}${lastImportLine?.trimEnd().endsWith(";") ? ";" : ""}`;
-	lines.splice(afterLine, 0, ...afterLine > 0 ? [line] : [line, ""]);
-	return lines.join("\n");
-}
-/**
-* `generateCode` always drops the file's trailing newline. Restore it when the input had one.
-*/
-function withTrailingNewline(code, hadTrailingNewline) {
-	if (!hadTrailingNewline || code.endsWith("\n")) return code;
-	return `${code}\n`;
-}
 //#endregion
 //#region src/generations.ts
 const READ_CONCURRENCY = 50;
@@ -1034,19 +1080,21 @@ async function generate({ config, hooks, signal, allowExec }) {
 		lint: false,
 		postGenerate: []
 	};
-	const result = await createKubb({
+	const kubb = createKubb({
 		...config,
 		output
 	}, {
 		hooks,
 		signal
-	}).generate();
+	});
+	const result = await kubb.generate();
 	if (!result.success) throw generationFailure(result.diagnostics);
+	const { storage, root } = kubb.config;
 	return {
-		storage: config.storage,
-		root: config.root,
+		storage,
+		root,
 		paths: new Set(result.files.map((file) => relativeStoragePath({
-			root: config.root,
+			root,
 			filePath: file.path
 		})))
 	};
@@ -1103,7 +1151,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;
-				hashes[path] = hashOf(content);
+				if (source === "output" && !content.trim()) return;
+				hashes[path] = hashOf(source === "output" ? `${content.trim()}\n` : content);
 				bytes += Buffer.byteLength(content);
 				if (bytes <= maxSetBytes) await storage.writeItem(`${dirOf(jobId)}${source}/${path}`, content);
 			}
@@ -1510,8 +1559,11 @@ var Agent = class extends RpcTarget {
 				path: configPath,
 				file,
 				plugins: config.plugins.map((plugin) => ({
-					name: toPackageName(plugin.name),
-					options: plugin.options ?? {}
+					name: toStudioName({
+						name: plugin.name,
+						root
+					}),
+					options: toJSONOptions(plugin.options)
 				}))
 			},
 			permissions: this.#permissions
@@ -1568,11 +1620,15 @@ var Agent = class extends RpcTarget {
 	}
 	async #generate({ input, root, signal }) {
 		const { jobId, config: patch } = input;
+		const studioInput = this.#sandbox ? patch?.input : void 0;
+		if (this.#sandbox && (typeof studioInput !== "string" || !studioInput.trim() || getInputKind(studioInput) !== "inline")) return this.#refuse({ message: "A sandbox agent generates only from the OpenAPI document content Studio sends, not from a file path or URL" });
 		const config = await this.#options.loadConfig();
-		const plugins = await mergePlugins(config.plugins, patch?.plugins) ?? config.plugins;
-		const adapter = await mergeAdapter(config.adapter, patch?.adapter);
-		const studioInput = this.#sandbox ? patch?.input ?? "" : void 0;
-		if (patch?.input && !this.#sandbox) await this.#warn({ message: "Ignored the spec from Studio: generating from a Studio spec is only available to a sandbox agent" });
+		const [plugins, adapter] = await Promise.all([mergePlugins(config.plugins, patch?.plugins), mergeAdapter(config.adapter, patch?.adapter)]).catch(async (error) => {
+			await emit(this.#options.hooks, "kubb:error", { error: toError(error) });
+			throw error;
+		});
+		const activePlugins = plugins ?? config.plugins;
+		if (patch?.input && !this.#sandbox) await emit(this.#options.hooks, "kubb:warn", { message: "Ignored the spec from Studio: generating from a Studio spec is only available to a sandbox agent" });
 		const diskFiles = !this.#sandbox && this.#permissions.allowRead ? await listDisk({
 			root,
 			outputPath: config.output.path,
@@ -1590,7 +1646,7 @@ var Agent = class extends RpcTarget {
 				root,
 				input: studioInput ?? config.input,
 				storage: this.#permissions.allowWrite ? fsStorage() : memoryStorage(),
-				plugins,
+				plugins: activePlugins,
 				adapter
 			},
 			hooks: this.#options.hooks,
@@ -1620,7 +1676,7 @@ var Agent = class extends RpcTarget {
 				hashes: output.hashes,
 				disk: disk ? { hashes: disk.hashes } : void 0
 			},
-			info: `${plugins.length} plugin${plugins.length === 1 ? "" : "s"}, ${this.#permissions.allowWrite ? "written to disk" : "in memory"}${studioInput !== void 0 ? ", from a Studio spec" : ""}`
+			info: `${activePlugins.length} plugin${activePlugins.length === 1 ? "" : "s"}, ${this.#permissions.allowWrite ? "written to disk" : "in memory"}${studioInput !== void 0 ? ", from a Studio spec" : ""}`
 		};
 	}
 	saveConfig(input) {
@@ -1775,8 +1831,12 @@ async function runSession({ options, openRpc, url, instanceId }) {
 	clearTimeout(timer);
 	signal?.removeEventListener("abort", rpc.close);
 	session.connected.reject(/* @__PURE__ */ new Error("The socket closed before Studio called connect()"));
-	session.active?.abort();
-	await session.active?.settled;
+	const active = session.active;
+	if (active) {
+		active.abort();
+		await emit(hooks, "studio:warn", { message: "Canceled the running generation: the connection to Kubb Studio closed" });
+	}
+	await active?.settled;
 	return {
 		...close,
 		connected: session.info !== void 0
@@ -1991,29 +2051,24 @@ const gzipAsync = promisify(gzip);
 const UPLOAD_TIMEOUT_MS = 12e4;
 const BUNDLED_DEPENDENCIES = ["@kubb/plugin-barrel"];
 /**
-* Maps a generated file's path to its place inside the tarball, stripping everything before a
-* `src`/`dist` segment and any `..`/empty path segment so a crafted file name cannot escape the
-* `package/` root.
+* Maps a generated file to its path in the package, from its `src`/`dist` segment on, without `..` parts that could escape it.
 */
 function packagePath(filePath) {
 	const normalized = filePath.replaceAll("\\", "/");
-	return `package/${(normalized.match(/\/(?:src|dist)\/.*$/)?.[0].slice(1) ?? normalized.replace(/^\/+/, "")).split("/").filter((part) => part && part !== "." && part !== "..").join("/")}`;
+	return (normalized.match(/\/(?:src|dist)\/.*$/)?.[0] ?? normalized).split("/").filter((part) => part && part !== "." && part !== "..").join("/");
 }
 /**
-* Splits a tarball entry path into the legacy 100-byte `name` field and, when the path does not
-* fit, the 155-byte USTAR `prefix` field that extends it. Throws rather than silently truncating
-* a path the format cannot address (max 256 bytes: 100 name + 1 separator + 155 prefix).
+* Splits a tar path into the 100-byte USTAR `name` and the 155-byte `prefix`, and throws for a path that fits neither.
 */
 function splitEntryPath(path) {
-	if (Buffer.byteLength(path, "utf8") <= 100) return {
+	if (Buffer.byteLength(path) <= 100) return {
 		name: path,
 		prefix: ""
 	};
-	for (let i = path.length - 1; i >= 0; i--) {
-		if (path[i] !== "/") continue;
+	for (let i = path.lastIndexOf("/"); i > 0; i = path.lastIndexOf("/", i - 1)) {
 		const prefix = path.slice(0, i);
 		const name = path.slice(i + 1);
-		if (Buffer.byteLength(prefix, "utf8") <= 155 && Buffer.byteLength(name, "utf8") <= 100) return {
+		if (Buffer.byteLength(prefix) <= 155 && Buffer.byteLength(name) <= 100) return {
 			name,
 			prefix
 		};
@@ -2023,21 +2078,23 @@ function splitEntryPath(path) {
 function header(path, size) {
 	const { name, prefix } = splitEntryPath(path);
 	const value = Buffer.alloc(512);
-	value.write(name, 0, "utf8");
-	value.write("0000644\0", 100, "ascii");
-	value.write("0000000\0", 108, "ascii");
-	value.write("0000000\0", 116, "ascii");
-	value.write(`${size.toString(8).padStart(11, "0")}\0`, 124, "ascii");
-	value.write("03560116604\0", 136, "ascii");
+	value.write(name);
+	value.write("0000644\0", 100);
+	for (const offset of [
+		108,
+		116,
+		265,
+		297
+	]) value.write("0000000\0", offset);
+	value.write(`${size.toString(8).padStart(11, "0")}\0`, 124);
+	value.write("03560116604\0", 136);
 	value.fill(32, 148, 156);
-	value.write("0", 156, "ascii");
-	value.write("ustar\0", 257, "ascii");
-	value.write("00", 263, "ascii");
-	value.write("0000000\0", 265, "ascii");
-	value.write("0000000\0", 297, "ascii");
-	value.write(prefix, 345, "utf8");
-	const checksum = [...value].reduce((sum, byte) => sum + byte, 0);
-	value.write(`${checksum.toString(8).padStart(6, "0")}\0 `, 148, "ascii");
+	value.write("0", 156);
+	value.write("ustar\0", 257);
+	value.write("00", 263);
+	value.write(prefix, 345);
+	const checksum = value.reduce((sum, byte) => sum + byte, 0);
+	value.write(`${checksum.toString(8).padStart(6, "0")}\0 `, 148);
 	return value;
 }
 /**
@@ -2045,31 +2102,29 @@ function header(path, size) {
 * generated sources, a `tsdown`-built `dist/` (esm + cjs), and a `package.json` manifest.
 */
 async function createSnapshotPackage({ files, packageInfo }) {
+	const sources = /* @__PURE__ */ new Map();
+	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}"`);
+		sources.set(path, {
+			name,
+			content
+		});
+	}
 	const root = await mkdtemp(join(tmpdir(), "kubb-snapshot-"));
 	const dist = join(root, "dist");
-	const resolvedPaths = Object.entries(files).map(([name, content]) => ({
-		name,
-		content,
-		target: packagePath(name)
-	}));
-	const targetOwners = /* @__PURE__ */ new Map();
-	for (const { name, target } of resolvedPaths) {
-		const owner = targetOwners.get(target);
-		if (owner) throw new Error(`Snapshot has two generated files that sanitize to the same path "${target}": "${owner}" and "${name}"`);
-		targetOwners.set(target, name);
-	}
 	try {
 		await mkdir(dist);
-		await Promise.all(resolvedPaths.map(async ({ content, target }) => {
-			const path = join(root, target.slice(8));
-			await mkdir(join(path, ".."), { recursive: true });
-			await writeFile(path, content);
+		await Promise.all([...sources].map(async ([path, { content }]) => {
+			await mkdir(dirname(join(root, path)), { recursive: true });
+			await writeFile(join(root, path), content);
 		}));
-		const sourceEntries = resolvedPaths.filter(({ name }) => /\.(?:[cm]?[jt]sx?)$/.test(name)).map(({ target }) => join(root, target.slice(8)));
-		if (sourceEntries.length) {
+		const entry = [...sources.keys()].filter((path) => /\.(?:[cm]?[jt]sx?)$/.test(path)).map((path) => join(root, path));
+		if (entry.length) {
 			const { build } = await import("tsdown");
 			await build({
-				entry: sourceEntries,
+				entry,
 				outDir: dist,
 				format: ["esm", "cjs"],
 				dts: false,
@@ -2080,38 +2135,38 @@ async function createSnapshotPackage({ files, packageInfo }) {
 				fixedExtension: true
 			});
 		}
-		const builtEntries = await Promise.all((await fsStorage().readKeys(dist)).map(async (key) => [`package/dist/${key}`, await readFile(join(dist, key), "utf8")]));
-		const builtPaths = new Set(builtEntries.map(([path]) => path));
-		const hasBarrel = builtPaths.has("package/dist/index.mjs") && builtPaths.has("package/dist/index.cjs");
-		const barrelFields = hasBarrel ? {
-			main: "./dist/index.cjs",
-			module: "./dist/index.mjs"
-		} : {};
-		const barrelExport = hasBarrel ? { ".": {
-			import: "./dist/index.mjs",
-			require: "./dist/index.cjs"
-		} } : {};
-		const entries = {
-			"package/package.json": JSON.stringify({
-				...packageInfo,
-				type: "module",
-				...barrelFields,
-				exports: {
-					...barrelExport,
-					"./*": {
-						import: "./dist/*.mjs",
-						require: "./dist/*.cjs"
-					}
+		const built = await fsStorage().readKeys(dist);
+		const hasBarrel = built.includes("index.mjs") && built.includes("index.cjs");
+		const manifest = {
+			...packageInfo,
+			type: "module",
+			...hasBarrel ? {
+				main: "./dist/index.cjs",
+				module: "./dist/index.mjs"
+			} : {},
+			exports: {
+				...hasBarrel ? { ".": {
+					import: "./dist/index.mjs",
+					require: "./dist/index.cjs"
+				} } : {},
+				"./*": {
+					import: "./dist/*.mjs",
+					require: "./dist/*.cjs"
 				}
-			}, null, 2),
-			...Object.fromEntries(resolvedPaths.map(({ content, target }) => [target, content])),
-			...Object.fromEntries(builtEntries)
+			}
 		};
-		const chunks = [];
-		for (const [name, content] of Object.entries(entries)) {
+		const chunks = [...new Map([
+			["package.json", JSON.stringify(manifest, null, 2)],
+			...[...sources].map(([path, { content }]) => [path, content]),
+			...await Promise.all(built.map(async (key) => [`dist/${key}`, await readFile(join(dist, key), "utf8")]))
+		])].flatMap(([path, content]) => {
 			const bytes = Buffer.from(content);
-			chunks.push(header(name, bytes.length), bytes, Buffer.alloc((512 - bytes.length % 512) % 512));
-		}
+			return [
+				header(`package/${path}`, bytes.length),
+				bytes,
+				Buffer.alloc((512 - bytes.length % 512) % 512)
+			];
+		});
 		return await gzipAsync(Buffer.concat([...chunks, Buffer.alloc(1024)]));
 	} finally {
 		await rm(root, {
@@ -2120,25 +2175,12 @@ async function createSnapshotPackage({ files, packageInfo }) {
 		});
 	}
 }
-function failureMessage({ status, _data }) {
-	const upgrade = _data?.data?.upgradeUrl ? ` Upgrade at ${_data.data.upgradeUrl}.` : "";
-	return `Kubb Studio refused the snapshot (status ${status})${_data?.message ? `: ${_data.message}` : ""}.${upgrade}`;
-}
 /**
-* Generates the project, packs it as an npm tarball, and publishes it to Studio in one
-* `POST /api/snapshots` request.
+* Generates the project, packs it as an npm tarball, and publishes it to Studio in one `POST /api/snapshots` request.
 *
 * @example
 * ```ts
-* const snapshot = await createSnapshot({
-*   apiKey: process.env.KUBB_TOKEN!,
-*   config,
-*   id: 'gh:123:pr-4',
-*   name: 'acme/api#4',
-*   packageName: '@acme/api',
-*   version: '1.0.0',
-* })
-* console.log(snapshot.url, snapshot.changes)
+* const { url } = await createSnapshot({ apiKey: process.env.KUBB_TOKEN!, config, id: 'gh:123:pr-4', name: 'acme/api#4', packageName: '@acme/api', version: '1.0.0' })
 * ```
 */
 async function createSnapshot({ studioUrl = defaultStudioUrl, apiKey, config, hooks, signal, ...metadata }) {
@@ -2178,7 +2220,7 @@ async function createSnapshot({ studioUrl = defaultStudioUrl, apiKey, config, ho
 	}));
 	body.set("tarball", new Blob([new Uint8Array(bytes)], { type: "application/gzip" }), "snapshot.tgz");
 	const timeout = AbortSignal.timeout(UPLOAD_TIMEOUT_MS);
-	const response = await ofetch.raw(url.href, {
+	const { ok, status, _data } = await ofetch.raw(url.href, {
 		method: "POST",
 		headers: { "x-api-key": apiKey },
 		body,
@@ -2186,10 +2228,12 @@ async function createSnapshot({ studioUrl = defaultStudioUrl, apiKey, config, ho
 		signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
 		ignoreResponseError: true
 	});
-	if (!response.ok) throw new Error(failureMessage(response));
-	const snapshot = response._data?.snapshot;
-	if (!snapshot) throw new Error(`Kubb Studio returned no snapshot (status ${response.status})`);
-	return snapshot;
+	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}`);
+	}
+	if (!_data?.snapshot) throw new Error(`Kubb Studio returned no snapshot (status ${status})`);
+	return _data.snapshot;
 }
 //#endregion
 export { IncompatibleAgentError, InvalidAgentTokenError, PairingCanceledError, PairingDeniedError, PairingExpiredError, connectAgent, createSnapshot, defaultStudioUrl, pairAgent };