@kubb/studio 5.3.17 → 5.3.19

package/dist/index.cjs

@@ -35,7 +35,6 @@ let node_process = require("node:process");
 node_process = __toESM(node_process, 1);
 let node_child_process = require("node:child_process");
 let _kubb_core = require("@kubb/core");
-let tinyexec = require("tinyexec");
 let node_timers_promises = require("node:timers/promises");
 let ofetch = require("ofetch");
 let node_util = require("node:util");
@@ -52,6 +51,7 @@ let tsdown = require("tsdown");
 let capnweb = require("capnweb");
 let ws = require("ws");
 ws = __toESM(ws, 1);
+let tinyexec = require("tinyexec");
 //#region ../../internals/utils/src/casing.ts
 /**
 * Shared implementation for camelCase and PascalCase conversion.
@@ -375,89 +375,9 @@ function getElapsedMs(hrStart) {
 }
 //#endregion
 //#region package.json
-var version = "5.3.17";
-//#endregion
-//#region src/hooks.ts
-/**
-* Register a `kubb:hook:start` listener that spawns the requested command via tinyexec,
-* streams each stdout line as a `kubb:hook:line` event, and calls `kubb:hook:end` with the result.
-* Streaming the output lets Kubb Studio render live hook progress over the WebSocket connection.
-*
-* Returns a remover, so a session that runs one generation after another on the same emitter does
-* not stack a listener per run.
-*/
-function setupHookListener(hooks, root, signal) {
-	return hooks.hook("kubb:hook:start", async (ctx) => {
-		const { id, command, args } = ctx;
-		if (!id) return;
-		const commandWithArgs = args?.length ? `${command} ${args.join(" ")}` : command;
-		try {
-			const proc = (0, tinyexec.x)(command, [...args ?? []], {
-				signal,
-				nodeOptions: {
-					cwd: root,
-					detached: true
-				}
-			});
-			for await (const line of proc) await hooks.callHook("kubb:hook:line", {
-				id,
-				line
-			});
-			const { exitCode } = await proc;
-			if (exitCode !== 0) {
-				const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
-				await hooks.callHook("kubb:hook:end", {
-					id,
-					command,
-					args,
-					success: false,
-					error
-				});
-				await hooks.callHook("kubb:error", { error });
-				return;
-			}
-			await hooks.callHook("kubb:hook:end", {
-				id,
-				command,
-				args,
-				success: true,
-				error: null
-			});
-		} catch (caughtError) {
-			const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
-			error.cause = caughtError;
-			await hooks.callHook("kubb:hook:end", {
-				id,
-				command,
-				args,
-				success: false,
-				error
-			});
-			await hooks.callHook("kubb:error", { error });
-		}
-	});
-}
-/**
-* Waits for the `kubb:hook:end` matching `hookId`. Register this before calling `kubb:hook:start`:
-* `callHook` awaits its listeners, and {@link setupHookListener} calls `kubb:hook:end` from inside
-* that same listener, so a handler added afterward would already have missed it.
-*/
-function waitForHookEnd(hooks, hookId) {
-	return new Promise((resolve, reject) => {
-		const handleHookEnd = (ctx) => {
-			if (ctx.id !== hookId) return;
-			hooks.removeHook("kubb:hook:end", handleHookEnd);
-			if (ctx.success) {
-				resolve();
-				return;
-			}
-			reject(ctx.error);
-		};
-		hooks.hook("kubb:hook:end", handleHookEnd);
-	});
-}
+var version = "5.3.19";
 //#endregion
-//#region src/machine.ts
+//#region src/operations/machine.ts
 /**
 * Key-value storage the runtime uses for its machine secret and the last Studio config.
 *
@@ -517,7 +437,7 @@ async function getMachineToken() {
 	return machineTokenFrom(await fallbackSecretPromise);
 }
 //#endregion
-//#region src/api.ts
+//#region src/operations/api.ts
 /**
 * Reads a human-readable message from a Studio JSON error body, when it has one. `FetchError`'s own
 * message stops at the status line, so the detail Studio sends with a failure (an agent limit, a
@@ -653,7 +573,7 @@ function withJitter(ms) {
 * const finished = await waitForJob({ studioUrl, token, id: job.id })
 * ```
 */
-async function createJob({ studioUrl, token, type, agentId, name, version, commit, baseId, config, timeoutMs = 6e4, signal }) {
+async function createJob({ studioUrl, token, type, agentId, name, version, commit, baseId, config, instanceId, timeoutMs = 6e4, signal }) {
 	const deadline = Date.now() + timeoutMs;
 	let interval = CREATE_JOB_INITIAL_DELAY_MS;
 	for (;;) {
@@ -669,7 +589,8 @@ async function createJob({ studioUrl, token, type, agentId, name, version, commi
 					version,
 					commit,
 					baseId,
-					config
+					config,
+					instanceId
 				},
 				retry: false,
 				timeout: Math.max(deadline - Date.now(), 1),
@@ -758,7 +679,7 @@ async function createAgent({ studioUrl, token, name, machineToken }) {
 	}
 }
 //#endregion
-//#region src/resolveConfig.ts
+//#region src/operations/resolveConfig.ts
 /**
 * Imports a package, falling back to how the user's project would resolve it.
 *
@@ -916,7 +837,7 @@ async function mergeAdapter(diskAdapter, studioOptions) {
 	return factory((0, remeda.mergeDeep)(diskAdapter.options ?? {}, studioOptions));
 }
 //#endregion
-//#region src/configFile.ts
+//#region src/operations/configFile.ts
 /**
 * A valid JavaScript identifier, so an import name can only ever print as `import { name } from`,
 * never as source that breaks out of the import statement.
@@ -1456,6 +1377,11 @@ function applyConfigEdits(source, edits) {
 		changed: current !== source
 	};
 }
+async function writeConfigEdits({ filePath, edits }) {
+	const result = applyConfigEdits(await read(filePath), edits);
+	if (result.changed) await (0, node_fs_promises.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
@@ -1488,144 +1414,7 @@ function withTrailingNewline(code, hadTrailingNewline) {
 	return `${code}\n`;
 }
 //#endregion
-//#region src/generate.ts
-/**
-* `isToolAvailable` spawns a process, and a long-lived connection generates repeatedly, so each
-* executable is probed once per process. The CLI deliberately does not memoize: a `--watch` build
-* should keep noticing a tool installed mid-session.
-*/
-const detectTool = memoize(/* @__PURE__ */ new Map(), detectTool$1);
-/**
-* The two post-build tool steps. Formatting and linting differ only in which tools they look for,
-* so they run through one loop rather than two near-identical blocks.
-*
-* `noun` and `verbing` are spelled out instead of built from `kind`. Concatenating `` `${kind}ter` ``
-* and `` `${kind}ting` `` works for `format`, but doubles the `t` in `lint`, giving "lintter" and
-* "lintting" instead of "linter" and "linting".
-*/
-const TOOL_STEPS = [{
-	kind: "format",
-	noun: "formatter",
-	verbing: "Formatting",
-	tools: formatters,
-	detect: FORMATTER_PREFERENCE
-}, {
-	kind: "lint",
-	noun: "linter",
-	verbing: "Linting",
-	tools: linters,
-	detect: LINTER_PREFERENCE
-}];
-/**
-* Absolute path of the directory the formatter and linter are pointed at.
-*/
-function outputPath(config) {
-	return node_path.default.isAbsolute(config.output.path) ? config.output.path : node_path.default.resolve(node_process.default.cwd(), config.root, config.output.path);
-}
-/**
-* Emits `kubb:hook:start` and waits for the matching `kubb:hook:end`. The host spawns the process:
-* this only describes what to run and when it finished.
-*
-* @throws whatever the command failed with, so callers can report it their own way.
-*/
-async function runHook({ hooks, id, command, args }) {
-	const hookId = (0, node_crypto.hash)("sha256", id);
-	const hookEnd = waitForHookEnd(hooks, hookId);
-	await hooks.callHook("kubb:hook:start", {
-		id: hookId,
-		command,
-		args: [...args]
-	});
-	await hookEnd;
-}
-function isProblemErrorDiagnostic(diagnostic) {
-	return (diagnostic.kind ?? "problem") === "problem" && diagnostic.severity === "error";
-}
-/**
-* Folds error-severity diagnostics into one thrown error so logs name the failing plugin.
-*/
-function formatGenerationFailure(diagnostics) {
-	const reasons = diagnostics.filter(isProblemErrorDiagnostic).map((diagnostic) => diagnostic.plugin ? `${diagnostic.plugin}: ${diagnostic.message}` : diagnostic.message);
-	if (!reasons.length) return /* @__PURE__ */ new Error("Generation failed");
-	return /* @__PURE__ */ new Error(`Generation failed: ${reasons.length} error${reasons.length === 1 ? "" : "s"}: ${reasons.join("; ")}`);
-}
-/**
-* Runs a full Kubb code-generation cycle for the given config.
-*
-* Emits lifecycle events on the provided `hooks` emitter so callers (e.g. the WebSocket stream)
-* can forward progress to connected clients. After a successful build, auto-formatting and
-* linting are applied when configured, followed by any user-defined `hooks.done` commands.
-*/
-async function generate({ config, hooks, signal }) {
-	signal?.throwIfAborted();
-	const hrStart = node_process.default.hrtime();
-	await hooks.callHook("kubb:generation:start", { config });
-	await hooks.callHook("kubb:info", { message: config.name ? `Setup generation ${config.name}` : "Setup generation" });
-	const kubb = (0, _kubb_core.createKubb)(config, {
-		hooks,
-		signal
-	});
-	await kubb.setup();
-	await hooks.callHook("kubb:info", { message: config.name ? `Build generation ${config.name}` : "Build generation" });
-	const { files, diagnostics, storage } = await kubb.safeBuild();
-	signal?.throwIfAborted();
-	await hooks.callHook("kubb:info", { message: "Load summary" });
-	for (const diagnostic of diagnostics.filter(isProblemErrorDiagnostic)) await hooks.callHook("kubb:error", { error: new Error(diagnostic.plugin ? `${diagnostic.plugin}: ${diagnostic.message}` : diagnostic.message) });
-	const status = _kubb_core.Diagnostics.hasError(diagnostics) ? "failed" : "success";
-	await hooks.callHook("kubb:generation:end", {
-		config,
-		storage: {
-			...storage,
-			readKeys: async () => [...new Set(files.map((file) => file.path))]
-		},
-		diagnostics,
-		status,
-		hrStart,
-		filesCreated: files.length
-	});
-	if (status === "failed") throw formatGenerationFailure(diagnostics);
-	await hooks.callHook("kubb:success", { message: "Generation successfully" });
-	for (const step of TOOL_STEPS) {
-		const setting = config.output[step.kind];
-		if (!setting) continue;
-		await hooks.callHook(`kubb:${step.kind}:start`);
-		const tool = setting === "auto" ? await detectTool(step.detect) : setting;
-		if (!tool) await hooks.callHook("kubb:warn", { message: `No ${step.noun} found (${step.detect.join(", ")}). Skipping ${step.verbing.toLowerCase()}.` });
-		if (tool && setting === "auto") await hooks.callHook("kubb:info", { message: `Auto-detected ${step.noun}: ${(0, node_util.styleText)("dim", tool)}` });
-		const command = tool ? step.tools[tool] : void 0;
-		if (command) try {
-			await runHook({
-				hooks,
-				id: [config.name, tool].filter(Boolean).join("-"),
-				command: command.command,
-				args: command.args(outputPath(config))
-			});
-			await hooks.callHook("kubb:success", { message: `${step.verbing} with ${tool} successfully` });
-		} catch (caughtError) {
-			await hooks.callHook("kubb:error", { error: new Error(command.errorMessage, { cause: caughtError }) });
-			signal?.throwIfAborted();
-		}
-		await hooks.callHook(`kubb:${step.kind}:end`);
-	}
-	if (config.output.postGenerate?.length) {
-		await hooks.callHook("kubb:hooks:start");
-		for (const entry of config.output.postGenerate) {
-			const line = typeof entry === "string" ? entry : entry.command;
-			const [cmd, ...args] = tokenize(line);
-			if (!cmd) continue;
-			await runHook({
-				hooks,
-				id: line,
-				command: cmd,
-				args
-			});
-			await hooks.callHook("kubb:success", { message: `${line} successfully executed` });
-		}
-		await hooks.callHook("kubb:hooks:end");
-	}
-}
-//#endregion
-//#region src/constants.ts
+//#region src/operations/constants.ts
 /**
 * Hosted Kubb Studio URL. Exported so credential stores can bind tokens to the resolved instance,
 * not whatever default the client would pick on its own.
@@ -1669,18 +1458,16 @@ function resolveGenerationLimits(env = process.env) {
 	};
 }
 /**
-* An agent's capacity read from `KUBB_AGENT_MAX_CONCURRENT` and `KUBB_AGENT_MEMORY_BUDGET_MB`. An
-* unset or invalid value keeps the default: one job at a time, and no memory budget.
+* An agent's capacity read from `KUBB_AGENT_MAX_CONCURRENT`. An unset or invalid value keeps the
+* default: one job at a time.
 */
 function resolveAgentCapacity(env = process.env) {
-	return {
-		maxConcurrent: Math.max(1, Math.floor(positiveNumber(env.KUBB_AGENT_MAX_CONCURRENT) ?? agentDefaults.maxConcurrent)),
-		memoryBudgetMb: positiveNumber(env.KUBB_AGENT_MEMORY_BUDGET_MB)
-	};
+	return { maxConcurrent: Math.max(1, Math.floor(positiveNumber(env.KUBB_AGENT_MAX_CONCURRENT) ?? agentDefaults.maxConcurrent)) };
 }
 //#endregion
-//#region src/snapshotPackage.ts
+//#region src/operations/snapshotPackage.ts
 const gzipAsync = (0, node_util.promisify)(node_zlib.gzip);
+const UPLOAD_TIMEOUT_MS = 12e4;
 /**
 * 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
@@ -1818,8 +1605,31 @@ async function createSnapshotPackage(files, packageInfo) {
 		});
 	}
 }
+async function uploadSnapshot({ bytes, uploadPath, studioUrl, token, shutdown }) {
+	const uploadUrl = new URL(uploadPath, studioUrl);
+	if (uploadUrl.origin !== new URL(studioUrl).origin) throw new Error("Snapshot upload path must stay on the Studio origin");
+	const timeout = AbortSignal.timeout(UPLOAD_TIMEOUT_MS);
+	const signal = shutdown ? AbortSignal.any([shutdown, timeout]) : timeout;
+	const redirect = await fetch(uploadUrl, {
+		method: "PUT",
+		headers: { Authorization: `Bearer ${token}` },
+		redirect: "manual",
+		signal
+	});
+	const storageUrl = redirect.headers.get("location");
+	if (redirect.status !== 307 || !storageUrl) throw new Error(`Studio did not provide a storage URL (status ${redirect.status})`);
+	const storage = new URL(storageUrl);
+	if (storage.protocol !== "https:" && storage.hostname !== "localhost" && storage.hostname !== "127.0.0.1") throw new Error(`Refusing snapshot upload to ${storage.origin}`);
+	const response = await fetch(storage, {
+		method: "PUT",
+		body: new Uint8Array(bytes),
+		redirect: "error",
+		signal
+	});
+	if (!response.ok) throw new Error(`Snapshot upload failed with status ${response.status}`);
+}
 //#endregion
-//#region src/generations.ts
+//#region src/operations/generations.ts
 const READ_CONCURRENCY = 50;
 const MB$1 = 1048576;
 const INDEX_KEY = "studio/generations.json";
@@ -1937,12 +1747,7 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 	};
 }
 //#endregion
-//#region src/ws.ts
-/**
-* How long the initial handshake may take before the socket is closed and the reconnect loop
-* takes over.
-*/
-const CONNECT_TIMEOUT_MS = 5e3;
+//#region src/operations/generationEvents.ts
 const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
 function relativeStoragePath(root, filePath) {
 	return ((0, node_path.isAbsolute)(filePath) ? (0, node_path.relative)((0, node_path.resolve)(root), filePath) : filePath).replaceAll("\\", "/");
@@ -1972,27 +1777,24 @@ async function resolvePeerDependencies(names) {
 		missingDependencies
 	};
 }
-/**
-* Opens a Studio WebSocket connection and closes it when the initial handshake exceeds the configured timeout.
-*/
-function createWebsocket(url, options) {
-	const ws$1 = new ws.default(url, options);
-	const timer = setTimeout(() => {
-		if (ws$1.readyState === ws.default.CONNECTING) ws$1.close(3008, "Connection timeout");
-	}, CONNECT_TIMEOUT_MS);
-	ws$1.once("open", () => clearTimeout(timer));
-	ws$1.once("close", () => clearTimeout(timer));
-	return ws$1;
-}
+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";
 /** Forwards selected Kubb lifecycle events to a native Cap'n Web stream. */
 function createGenerationStream(hooks, jobId, options = {}) {
 	const unhooks = [];
 	let root = "";
-	const transform = new TransformStream(void 0, void 0, { highWaterMark: Infinity });
-	const writer = transform.writable.getWriter();
-	let writes = Promise.resolve();
+	let controller;
 	let closed = false;
-	let streamError;
+	const stream = new ReadableStream({
+		start: (value) => {
+			controller = value;
+		},
+		cancel: () => {
+			closed = true;
+			detach();
+		}
+	}, { highWaterMark: MAX_QUEUED_EVENTS });
 	/**
 	* Registers a listener and keeps its remover, so one generation's listeners come off the session
 	* emitter again when that generation ends.
@@ -2001,6 +1803,7 @@ function createGenerationStream(hooks, jobId, options = {}) {
 		unhooks.push(hooks.hook(name, handler));
 	}
 	function emitEvent(type, data) {
+		if (closed) return;
 		const event = {
 			jobId,
 			type,
@@ -2008,9 +1811,12 @@ function createGenerationStream(hooks, jobId, options = {}) {
 			version: 1,
 			timestamp: Date.now()
 		};
-		writes = writes.then(() => writer.write(event)).catch((error) => {
-			streamError = error;
-		});
+		if (controller.desiredSize <= RESERVED_EVENTS && isDiscardable(event)) return;
+		if (controller.desiredSize <= 0) {
+			fail(/* @__PURE__ */ new Error(`Generation event stream exceeded ${MAX_QUEUED_EVENTS} queued events`));
+			return;
+		}
+		controller.enqueue(event);
 	}
 	on("kubb:plugin:start", (ctx) => {
 		emitEvent("kubb:plugin:start", [{ plugin: { name: ctx.plugin.name } }]);
@@ -2156,25 +1962,38 @@ function createGenerationStream(hooks, jobId, options = {}) {
 		if (closed) return;
 		closed = true;
 		detach();
-		await writes;
-		if (streamError) return;
-		await writer.close().catch(() => void 0);
+		controller.close();
 	}
 	function fail(error) {
 		detach();
 		if (closed) return;
 		closed = true;
-		writer.abort(error).catch(() => void 0);
+		controller.error(error);
 	}
 	return {
-		stream: transform.readable,
+		stream,
 		close,
 		dispose: () => fail(),
 		fail
 	};
 }
 //#endregion
-//#region src/rpc.ts
+//#region src/operations/websocket.ts
+const CONNECT_TIMEOUT_MS = 5e3;
+/**
+* Opens a Studio WebSocket connection and closes it when the initial handshake exceeds the configured timeout.
+*/
+function createWebsocket(url, options) {
+	const ws$1 = new ws.default(url, options);
+	const timer = setTimeout(() => {
+		if (ws$1.readyState === ws.default.CONNECTING) ws$1.close(3008, "Connection timeout");
+	}, CONNECT_TIMEOUT_MS);
+	ws$1.once("open", () => clearTimeout(timer));
+	ws$1.once("close", () => clearTimeout(timer));
+	return ws$1;
+}
+//#endregion
+//#region src/operations/rpc.ts
 /**
 * The only methods Studio may call on an agent. A `StudioSession` carries far more than
 * {@link AgentApi}, so it is wrapped rather than exposed: what Cap'n Web can reach is exactly what
@@ -2235,16 +2054,253 @@ const connectWebSocketRpc = async ({ url, token, instanceId, local }) => {
 	};
 };
 //#endregion
-//#region src/StudioSession.ts
+//#region src/operations/hooks.ts
 /**
-* Past this many files in the output directory, no snapshot of it is taken before a run.
+* Register a `kubb:hook:start` listener that spawns the requested command via tinyexec,
+* streams each stdout line as a `kubb:hook:line` event, and calls `kubb:hook:end` with the result.
+* Streaming the output lets Kubb Studio render live hook progress over the WebSocket connection.
+*
+* Returns a remover, so a session that runs one generation after another on the same emitter does
+* not stack a listener per run.
 */
+function setupHookListener(hooks, root, signal) {
+	return hooks.hook("kubb:hook:start", async (ctx) => {
+		const { id, command, args } = ctx;
+		if (!id) return;
+		const commandWithArgs = args?.length ? `${command} ${args.join(" ")}` : command;
+		try {
+			const proc = (0, tinyexec.x)(command, [...args ?? []], {
+				signal,
+				nodeOptions: {
+					cwd: root,
+					detached: true
+				}
+			});
+			for await (const line of proc) await hooks.callHook("kubb:hook:line", {
+				id,
+				line
+			});
+			const { exitCode } = await proc;
+			if (exitCode !== 0) {
+				const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
+				await hooks.callHook("kubb:hook:end", {
+					id,
+					command,
+					args,
+					success: false,
+					error
+				});
+				await hooks.callHook("kubb:error", { error });
+				return;
+			}
+			await hooks.callHook("kubb:hook:end", {
+				id,
+				command,
+				args,
+				success: true,
+				error: null
+			});
+		} catch (caughtError) {
+			const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
+			error.cause = caughtError;
+			await hooks.callHook("kubb:hook:end", {
+				id,
+				command,
+				args,
+				success: false,
+				error
+			});
+			await hooks.callHook("kubb:error", { error });
+		}
+	});
+}
+/**
+* Waits for the `kubb:hook:end` matching `hookId`. Register this before calling `kubb:hook:start`:
+* `callHook` awaits its listeners, and {@link setupHookListener} calls `kubb:hook:end` from inside
+* that same listener, so a handler added afterward would already have missed it.
+*/
+function waitForHookEnd(hooks, hookId) {
+	return new Promise((resolve, reject) => {
+		const handleHookEnd = (ctx) => {
+			if (ctx.id !== hookId) return;
+			hooks.removeHook("kubb:hook:end", handleHookEnd);
+			if (ctx.success) {
+				resolve();
+				return;
+			}
+			reject(ctx.error);
+		};
+		hooks.hook("kubb:hook:end", handleHookEnd);
+	});
+}
+//#endregion
+//#region src/operations/generate.ts
 const DISK_SNAPSHOT_MAX_FILES = 1e4;
 /**
-* How long a sandbox keeps a generation readable. Its store is in memory and holds every tenant's
-* runs, so an old one has to go even when count and size leave room. A local agent keeps its runs
-* until count or size pushes them out, so a later run can still diff against the one before it.
+* `isToolAvailable` spawns a process, and a long-lived connection generates repeatedly, so each
+* executable is probed once per process. The CLI deliberately does not memoize: a `--watch` build
+* should keep noticing a tool installed mid-session.
+*/
+const detectTool = memoize(/* @__PURE__ */ new Map(), detectTool$1);
+/**
+* The two post-build tool steps. Formatting and linting differ only in which tools they look for,
+* so they run through one loop rather than two near-identical blocks.
+*
+* `noun` and `verbing` are spelled out instead of built from `kind`. Concatenating `` `${kind}ter` ``
+* and `` `${kind}ting` `` works for `format`, but doubles the `t` in `lint`, giving "lintter" and
+* "lintting" instead of "linter" and "linting".
+*/
+const TOOL_STEPS = [{
+	kind: "format",
+	noun: "formatter",
+	verbing: "Formatting",
+	tools: formatters,
+	detect: FORMATTER_PREFERENCE
+}, {
+	kind: "lint",
+	noun: "linter",
+	verbing: "Linting",
+	tools: linters,
+	detect: LINTER_PREFERENCE
+}];
+/**
+* Absolute path of the directory the formatter and linter are pointed at.
+*/
+function outputPath(config) {
+	return node_path.default.isAbsolute(config.output.path) ? config.output.path : node_path.default.resolve(node_process.default.cwd(), config.root, config.output.path);
+}
+/**
+* Emits `kubb:hook:start` and waits for the matching `kubb:hook:end`. The host spawns the process:
+* this only describes what to run and when it finished.
+*
+* @throws whatever the command failed with, so callers can report it their own way.
+*/
+async function runHook({ hooks, id, command, args }) {
+	const hookId = (0, node_crypto.hash)("sha256", id);
+	const hookEnd = waitForHookEnd(hooks, hookId);
+	await hooks.callHook("kubb:hook:start", {
+		id: hookId,
+		command,
+		args: [...args]
+	});
+	await hookEnd;
+}
+function isProblemErrorDiagnostic(diagnostic) {
+	return (diagnostic.kind ?? "problem") === "problem" && diagnostic.severity === "error";
+}
+/**
+* Folds error-severity diagnostics into one thrown error so logs name the failing plugin.
+*/
+function formatGenerationFailure(diagnostics) {
+	const reasons = diagnostics.filter(isProblemErrorDiagnostic).map((diagnostic) => diagnostic.plugin ? `${diagnostic.plugin}: ${diagnostic.message}` : diagnostic.message);
+	if (!reasons.length) return /* @__PURE__ */ new Error("Generation failed");
+	return /* @__PURE__ */ new Error(`Generation failed: ${reasons.length} error${reasons.length === 1 ? "" : "s"}: ${reasons.join("; ")}`);
+}
+/**
+* Runs a full Kubb code-generation cycle for the given config.
+*
+* Emits lifecycle events on the provided `hooks` emitter so callers (e.g. the WebSocket stream)
+* can forward progress to connected clients. After a successful build, auto-formatting and
+* linting are applied when configured, followed by any user-defined `hooks.done` commands.
 */
+async function generate({ config, hooks, signal }) {
+	signal?.throwIfAborted();
+	const hrStart = node_process.default.hrtime();
+	await hooks.callHook("kubb:generation:start", { config });
+	await hooks.callHook("kubb:info", { message: config.name ? `Setup generation ${config.name}` : "Setup generation" });
+	const kubb = (0, _kubb_core.createKubb)(config, {
+		hooks,
+		signal
+	});
+	await kubb.setup();
+	await hooks.callHook("kubb:info", { message: config.name ? `Build generation ${config.name}` : "Build generation" });
+	const { files, diagnostics, storage } = await kubb.safeBuild();
+	signal?.throwIfAborted();
+	await hooks.callHook("kubb:info", { message: "Load summary" });
+	for (const diagnostic of diagnostics.filter(isProblemErrorDiagnostic)) await hooks.callHook("kubb:error", { error: new Error(diagnostic.plugin ? `${diagnostic.plugin}: ${diagnostic.message}` : diagnostic.message) });
+	const status = _kubb_core.Diagnostics.hasError(diagnostics) ? "failed" : "success";
+	await hooks.callHook("kubb:generation:end", {
+		config,
+		storage: {
+			...storage,
+			readKeys: async () => [...new Set(files.map((file) => file.path))]
+		},
+		diagnostics,
+		status,
+		hrStart,
+		filesCreated: files.length
+	});
+	if (status === "failed") throw formatGenerationFailure(diagnostics);
+	await hooks.callHook("kubb:success", { message: "Generation successfully" });
+	for (const step of TOOL_STEPS) {
+		const setting = config.output[step.kind];
+		if (!setting) continue;
+		await hooks.callHook(`kubb:${step.kind}:start`);
+		const tool = setting === "auto" ? await detectTool(step.detect) : setting;
+		if (!tool) await hooks.callHook("kubb:warn", { message: `No ${step.noun} found (${step.detect.join(", ")}). Skipping ${step.verbing.toLowerCase()}.` });
+		if (tool && setting === "auto") await hooks.callHook("kubb:info", { message: `Auto-detected ${step.noun}: ${(0, node_util.styleText)("dim", tool)}` });
+		const command = tool ? step.tools[tool] : void 0;
+		if (command) try {
+			await runHook({
+				hooks,
+				id: [config.name, tool].filter(Boolean).join("-"),
+				command: command.command,
+				args: command.args(outputPath(config))
+			});
+			await hooks.callHook("kubb:success", { message: `${step.verbing} with ${tool} successfully` });
+		} catch (caughtError) {
+			await hooks.callHook("kubb:error", { error: new Error(command.errorMessage, { cause: caughtError }) });
+			signal?.throwIfAborted();
+		}
+		await hooks.callHook(`kubb:${step.kind}:end`);
+	}
+	if (config.output.postGenerate?.length) {
+		await hooks.callHook("kubb:hooks:start");
+		for (const entry of config.output.postGenerate) {
+			const line = typeof entry === "string" ? entry : entry.command;
+			const [cmd, ...args] = tokenize(line);
+			if (!cmd) continue;
+			await runHook({
+				hooks,
+				id: line,
+				command: cmd,
+				args
+			});
+			await hooks.callHook("kubb:success", { message: `${line} successfully executed` });
+		}
+		await hooks.callHook("kubb:hooks:end");
+	}
+}
+async function runGenerationOperation({ config, hooks, signal, jobId, store, snapshotRoot, maxSnapshotMb }) {
+	const diskFiles = snapshotRoot ? await listDisk({
+		root: snapshotRoot,
+		outputPath: config.output.path,
+		maxFiles: DISK_SNAPSHOT_MAX_FILES
+	}) : void 0;
+	const disk = diskFiles ? await store.keep({
+		jobId,
+		source: "disk",
+		files: diskFiles,
+		maxSetMb: maxSnapshotMb
+	}) : void 0;
+	const removeHookListener = setupHookListener(hooks, config.root, signal);
+	try {
+		await generate({
+			config,
+			hooks,
+			signal
+		});
+	} catch (error) {
+		await store.drop(jobId);
+		throw error;
+	} finally {
+		removeHookListener();
+	}
+	return disk;
+}
+//#endregion
+//#region src/runtime/StudioSession.ts
+/** A sandbox shares one in-memory generation store across tenants, so old generations expire. */
 const SANDBOX_GENERATION_TTL_MS = 9e5;
 /**
 * A fresh root for one sandbox job. Kubb keys its output manifest cache by root, so tenants that
@@ -2306,7 +2362,6 @@ function applyStudioDefaults(options) {
 		permissions: {
 			allowWrite: false,
 			allowConfigEdit: false,
-			allowInput: false,
 			allowExec: false,
 			allowRead: false,
 			...options.permissions
@@ -2442,13 +2497,6 @@ var StudioSession = class {
 		return !this.#isSandbox && this.#options.permissions.allowConfigEdit;
 	}
 	/**
-	* A sandbox agent always generates from the spec Studio supplies. A local agent only when the
-	* host opted in.
-	*/
-	get #canUseInput() {
-		return this.#isSandbox || this.#options.permissions.allowInput;
-	}
-	/**
 	* A sandbox agent always allows reading its output back; a local agent only when opted in.
 	*/
 	get #canRead() {
@@ -2554,20 +2602,12 @@ var StudioSession = class {
 			clearTimeout(timer);
 		}
 	}
-	/**
-	* Whether memory still leaves room for another job. Always, when the host set no budget.
-	*/
-	#isAccepting(memoryMb = rssMb()) {
-		const budget = this.#options.capacity.memoryBudgetMb;
-		return budget === void 0 || memoryMb <= budget * 1.5;
-	}
 	async #load() {
-		const memoryMb = rssMb();
 		return {
 			running: this.#isGenerating ? 1 : 0,
-			rssMb: Math.round(memoryMb),
+			rssMb: Math.round(rssMb()),
 			storeBytes: await this.#generations.bytes(),
-			accepting: this.#isAccepting(memoryMb)
+			accepting: true
 		};
 	}
 	/**
@@ -2605,7 +2645,6 @@ var StudioSession = class {
 			permissions: {
 				...permissions,
 				allowWrite: this.#canWrite,
-				allowInput: this.#canUseInput,
 				allowConfigEdit: this.#canEditConfig,
 				allowRead: this.#canRead
 			}
@@ -2676,7 +2715,6 @@ var StudioSession = class {
 	}
 	async #runGeneration(data, controller, cancelRun) {
 		if (this.#isGenerating) return this.#refuse("Ignored generate: a generation is already in progress", "A generation is already in progress, please wait for it to finish");
-		if (!this.#isAccepting()) return this.#refuse("Ignored generate: the agent is past its memory budget", "The agent is past its memory budget, try again once it frees memory");
 		this.#isGenerating = true;
 		this.#activeJob = {
 			jobId: data.jobId,
@@ -2692,48 +2730,33 @@ var StudioSession = class {
 			const patch = data.config;
 			const plugins = await mergePlugins(config.plugins, patch?.plugins);
 			const adapter = await mergeAdapter(config.adapter, patch?.adapter);
-			const inputOverride = this.#isSandbox ? patch?.input ?? "" : permissions.allowInput && patch?.input || void 0;
+			const inputOverride = this.#isSandbox ? patch?.input ?? "" : void 0;
 			if (permissions.allowWrite && this.#isSandbox) await this.#warn("Running in a sandbox, so writing files is disabled");
-			if (patch?.input && !this.#canUseInput) await this.#warn("Ignored the spec from Studio: generating from a Studio spec was not granted", "allowInput");
+			if (patch?.input && !this.#isSandbox) await this.#warn("Ignored the spec from Studio: generating from a Studio spec is only available to a sandbox agent");
 			const resolvedPlugins = plugins ?? config.plugins;
 			this.#lastGeneration = void 0;
-			const diskFiles = this.#hasProjectOnDisk ? await listDisk({
-				root,
-				outputPath: config.output.path,
-				maxFiles: DISK_SNAPSHOT_MAX_FILES
-			}) : void 0;
-			const disk = diskFiles ? await this.#generations.keep({
-				jobId: data.jobId,
-				source: "disk",
-				files: diskFiles,
-				maxSetMb: this.#limits.maxSnapshotMb
-			}) : void 0;
-			const detach = [setupHookListener(this.#hooks, root, controller.signal)];
-			try {
-				await generate({
-					config: {
-						...config,
-						root,
-						input: inputOverride ?? config.input,
-						storage: this.#canWrite ? (0, _kubb_core.fsStorage)() : (0, _kubb_core.memoryStorage)(),
-						output: permissions.allowExec ? { ...config.output } : {
-							...config.output,
-							format: false,
-							lint: false,
-							postGenerate: []
-						},
-						plugins: resolvedPlugins,
-						adapter
+			const disk = await runGenerationOperation({
+				config: {
+					...config,
+					root,
+					input: inputOverride ?? config.input,
+					storage: this.#canWrite ? (0, _kubb_core.fsStorage)() : (0, _kubb_core.memoryStorage)(),
+					output: permissions.allowExec ? { ...config.output } : {
+						...config.output,
+						format: false,
+						lint: false,
+						postGenerate: []
 					},
-					hooks: this.#hooks,
-					signal: controller.signal
-				});
-			} catch (error) {
-				await this.#generations.drop(data.jobId);
-				throw error;
-			} finally {
-				for (const remove of detach) remove();
-			}
+					plugins: resolvedPlugins,
+					adapter
+				},
+				hooks: this.#hooks,
+				signal: controller.signal,
+				jobId: data.jobId,
+				store: this.#generations,
+				snapshotRoot: this.#hasProjectOnDisk ? root : void 0,
+				maxSnapshotMb: this.#limits.maxSnapshotMb
+			});
 			await this.#hooks.callHook("studio:command:end", {
 				command,
 				info: `${resolvedPlugins.length} plugin${resolvedPlugins.length === 1 ? "" : "s"}, ${this.#canWrite ? "written to disk" : "in memory"}${inputOverride !== void 0 ? ", from a Studio spec" : ""}`
@@ -2795,8 +2818,10 @@ var StudioSession = class {
 		}
 		if (this.#isGenerating) return refuse("a generation is in progress");
 		try {
-			const { source: patched, outcomes, changed } = applyConfigEdits(await read(configFile), edits);
-			if (changed) await (0, node_fs_promises.writeFile)(configFile, patched, "utf-8");
+			const { source: patched, outcomes, changed } = await writeConfigEdits({
+				filePath: configFile,
+				edits
+			});
 			const applied = outcomes.filter((outcome) => outcome.applied).length;
 			await this.#hooks.callHook("studio:command:end", {
 				command,
@@ -2834,24 +2859,14 @@ var StudioSession = class {
 				version,
 				peerDependencies: generation.peerDependencies
 			});
-			const { token, studioUrl } = this.#options;
-			const uploadUrl = new URL(uploadPath, studioUrl);
-			if (uploadUrl.origin !== new URL(studioUrl).origin) throw new Error("Snapshot upload path must stay on the Studio origin");
-			const redirect = await fetch(uploadUrl, {
-				method: "PUT",
-				headers: { Authorization: `Bearer ${token}` },
-				redirect: "manual"
-			});
-			const storageUrl = redirect.headers.get("location");
-			if (redirect.status !== 307 || !storageUrl) throw new Error(`Studio did not provide a storage URL (status ${redirect.status})`);
-			const storage = new URL(storageUrl);
-			if (storage.protocol !== "https:" && storage.hostname !== "localhost" && storage.hostname !== "127.0.0.1") throw new Error(`Refusing snapshot upload to ${storage.origin}`);
-			const response = await fetch(storage, {
-				method: "PUT",
-				body: new Uint8Array(bytes),
-				redirect: "error"
+			const { token, studioUrl, signal } = this.#options;
+			await uploadSnapshot({
+				bytes,
+				uploadPath,
+				studioUrl,
+				token,
+				shutdown: signal
 			});
-			if (!response.ok) throw new Error(`Snapshot upload failed with status ${response.status}`);
 			await this.#hooks.callHook("studio:command:end", {
 				command,
 				info: `packed ${Object.keys(files).length} file${Object.keys(files).length === 1 ? "" : "s"}`
@@ -2865,10 +2880,7 @@ var StudioSession = class {
 			throw error;
 		}
 	}
-	/**
-	* An agent with a project on disk can show a run against what its output directory held before.
-	* A sandbox agent has no project.
-	*/
+	/** A sandbox has no project directory to snapshot. */
 	get #hasProjectOnDisk() {
 		return !this.#isSandbox && this.#canRead;
 	}
@@ -2897,7 +2909,7 @@ var StudioSession = class {
 	}
 };
 //#endregion
-//#region src/client.ts
+//#region src/runtime/client.ts
 /**
 * Creates the Kubb Studio client: the connection, the command loop, and the generation event
 * stream shared by the `kubb studio` CLI command and the Docker agent.
@@ -2913,7 +2925,7 @@ var StudioSession = class {
 */
 function createClient({ onAuthRequired, ...options }) {
 	const controller = new AbortController();
-	const instanceId = (0, node_crypto.randomUUID)();
+	const instanceId = options.instanceId ?? (0, node_crypto.randomUUID)();
 	function notifyAuthRequired(error) {
 		if (controller.signal.aborted) return;
 		controller.abort();
@@ -2934,7 +2946,7 @@ function createClient({ onAuthRequired, ...options }) {
 	};
 }
 //#endregion
-//#region src/runConnection.ts
+//#region src/runtime/runConnection.ts
 /**
 * Waits for whichever comes first: the shutdown signal, or Studio rejecting the token during a
 * background reconnect. Resolves with the rejection, or nothing when the run is being shut down.
@@ -3007,7 +3019,7 @@ async function runConnection({ credentials, clientOptions, onTokenRejected, sign
 	}
 }
 //#endregion
-//#region src/pair.ts
+//#region src/operations/pair.ts
 /** Labels, not secrets: a person approving the code in the browser is what authorizes a pairing. */
 const CLIENT_IDS = {
 	cli: "kubb-cli",