@kubb/studio 0.0.0-canary-20260903193839

package/dist/index.cjs

@@ -0,0 +1,1330 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_rolldown_runtime = require("./rolldown-runtime-qbf5tadS.cjs");
+const require_resolveConfig = require("./resolveConfig-Ci-BVhN_.cjs");
+const require_protocol = require("./protocol.cjs");
+let node_util = require("node:util");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+node_path = require_rolldown_runtime.__toESM(node_path, 1);
+let node_child_process = require("node:child_process");
+let ofetch = require("ofetch");
+let node_crypto = require("node:crypto");
+let node_process = require("node:process");
+node_process = require_rolldown_runtime.__toESM(node_process, 1);
+let unstorage = require("unstorage");
+let unstorage_drivers_fs = require("unstorage/drivers/fs");
+unstorage_drivers_fs = require_rolldown_runtime.__toESM(unstorage_drivers_fs, 1);
+let _kubb_core = require("@kubb/core");
+let tinyexec = require("tinyexec");
+let ws = require("ws");
+ws = require_rolldown_runtime.__toESM(ws, 1);
+let node_timers_promises = require("node:timers/promises");
+//#region src/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.
+*/
+const defaultStudioUrl = "https://kubb.studio";
+/**
+* Defaults the Studio client uses when a host passes nothing.
+* Config path is left out on purpose: each host discovers that itself.
+*/
+const agentDefaults = {
+	studioUrl: defaultStudioUrl,
+	retryIntervalMs: 3e4,
+	/**
+	* Maximum heartbeat interval. Studio drops agents from the active list after ~90s without a ping,
+	* so a slower override would make a healthy agent look dead.
+	*/
+	heartbeatIntervalMs: 3e4,
+	poolSize: 1
+};
+//#endregion
+//#region ../../internals/utils/src/errors.ts
+/**
+* Coerces an unknown thrown value to an `Error` instance.
+* Returns the value as-is when it is already an `Error`; otherwise wraps it with `String(value)`.
+*
+* @example
+* ```ts
+* try { ... } catch(err) {
+*   throw new Error('Build failed', { cause: toError(err) })
+* }
+* ```
+*/
+function toError(value) {
+	return value instanceof Error ? value : new Error(String(value));
+}
+/**
+* Extracts a human-readable message from any thrown value.
+*
+* @example
+* ```ts
+* getErrorMessage(new Error('oops')) // 'oops'
+* getErrorMessage('plain string')    // 'plain string'
+* ```
+*/
+function getErrorMessage(value) {
+	return value instanceof Error ? value.message : String(value);
+}
+//#endregion
+//#region ../../internals/utils/src/promise.ts
+/**
+* Wraps `factory` with a keyed cache backed by the provided store.
+*
+* Pass a `WeakMap` for object keys (results are GC-eligible when the key is
+* collected) or a `Map` for primitive keys. For multi-argument functions,
+* nest two `memoize` calls — the outer keyed by the first argument, the
+* inner (created once per outer miss) keyed by the second.
+*
+* Because the cache is owned by the caller, it can be shared, inspected, or
+* cleared independently of the memoized function.
+*
+* @example Single WeakMap key
+* ```ts
+* const cache = new WeakMap<SchemaNode, Set<string>>()
+* const getRefs = memoize(cache, (node) => collectRefs(node))
+* ```
+*
+* @example Single Map key (primitive)
+* ```ts
+* const cache = new Map<string, Resolver>()
+* const getResolver = memoize(cache, (name) => buildResolver(name))
+* ```
+*
+* @example Two-level (object + primitive)
+* ```ts
+* const outer = new WeakMap<Params[], Map<string, Params[]>>()
+* const fn = memoize(outer, (params) => memoize(new Map(), (key) => transform(params, key)))
+* fn(params)('camelcase')
+* ```
+*/
+function memoize(store, factory) {
+	return (key) => {
+		if (store.has(key)) return store.get(key);
+		const value = factory(key);
+		store.set(key, value);
+		return value;
+	};
+}
+/**
+* Runs `run` over every item with at most `limit` in flight. Workers share one iterator, so each
+* takes the next item the moment it frees up instead of waiting for a batch to drain.
+*
+* @example
+* ```ts
+* await inParallel({ items: files, limit: 50, run: (file) => storage.writeItem(file.path, file.source) })
+* ```
+*/
+async function inParallel({ items, limit, run }) {
+	const queue = items.entries();
+	const worker = async () => {
+		for (const [index, item] of queue) await run(item, index);
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()));
+}
+//#endregion
+//#region ../../internals/utils/src/tools.ts
+/**
+* CLI command descriptors for each supported code formatter.
+*/
+const formatters = {
+	prettier: {
+		command: "prettier",
+		args: (outputPath) => [
+			"--ignore-unknown",
+			"--write",
+			outputPath
+		],
+		errorMessage: "Prettier not found"
+	},
+	biome: {
+		command: "biome",
+		args: (outputPath) => [
+			"format",
+			"--write",
+			outputPath
+		],
+		errorMessage: "Biome not found"
+	},
+	oxfmt: {
+		command: "oxfmt",
+		args: (outputPath) => [outputPath],
+		errorMessage: "Oxfmt not found"
+	}
+};
+/**
+* CLI command descriptors for each supported linter.
+*/
+const linters = {
+	eslint: {
+		command: "eslint",
+		args: (outputPath) => [outputPath, "--fix"],
+		errorMessage: "Eslint not found"
+	},
+	biome: {
+		command: "biome",
+		args: (outputPath) => [
+			"lint",
+			"--fix",
+			outputPath
+		],
+		errorMessage: "Biome not found"
+	},
+	oxlint: {
+		command: "oxlint",
+		args: (outputPath) => [
+			"--fix",
+			"--no-ignore",
+			outputPath
+		],
+		errorMessage: "Oxlint not found"
+	}
+};
+/**
+* Preference order for `format: 'auto'`, most-preferred first. Spelled out rather than taken from
+* the table's key order, which is arbitrary and would silently change what `auto` picks.
+*/
+const FORMATTER_PREFERENCE = [
+	"oxfmt",
+	"biome",
+	"prettier"
+];
+/**
+* Preference order for `lint: 'auto'`, most-preferred first.
+*/
+const LINTER_PREFERENCE = [
+	"oxlint",
+	"biome",
+	"eslint"
+];
+/**
+* Whether `name` is on PATH and answers `--version` with a zero exit.
+*/
+function isToolAvailable(name) {
+	return new Promise((resolve) => {
+		const child = (0, node_child_process.spawn)(name, ["--version"], { stdio: "ignore" });
+		child.on("close", (code) => resolve(code === 0));
+		child.on("error", () => resolve(false));
+	});
+}
+/**
+* Returns the first installed executable from `candidates`, or `null` when none are found.
+*
+* Not memoized: a long-running host that probes repeatedly should cache the result itself, and a
+* `--watch` build should keep noticing a tool installed mid-session.
+*/
+async function detectTool$1(candidates) {
+	for (const candidate of candidates) if (await isToolAvailable(candidate)) return candidate;
+	return null;
+}
+require_rolldown_runtime.__name(detectTool$1, "detectTool");
+/**
+* Tokenizes a shell command string, respecting single and double quotes.
+*
+* @example
+* ```ts
+* tokenize('git commit -m "initial commit"')
+* // → ['git', 'commit', '-m', 'initial commit']
+* ```
+*/
+function tokenize(command) {
+	return (command.match(/[^\s"']+|"([^"]*)"|'([^']*)'/g) ?? []).map((token) => token.replace(/^["']|["']$/g, ""));
+}
+//#endregion
+//#region ../../internals/utils/src/time.ts
+/**
+* Calculates elapsed time in milliseconds from a high-resolution `process.hrtime` start time.
+* Rounds to 2 decimal places for sub-millisecond precision without noise.
+*
+* @example
+* ```ts
+* const start = process.hrtime()
+* doWork()
+* getElapsedMs(start) // 42.35
+* ```
+*/
+function getElapsedMs(hrStart) {
+	const [seconds, nanoseconds] = process.hrtime(hrStart);
+	const ms = seconds * 1e3 + nanoseconds / 1e6;
+	return Math.round(ms * 100) / 100;
+}
+//#endregion
+//#region src/machine.ts
+/**
+* Key-value storage the runtime uses for its machine secret and the last Studio config.
+*
+* One storage per process, since one process serves one config file. Hosts install their own
+* driver on startup: Nitro passes its `kubb` mount, the CLI an fs driver under `~/.kubb/cache`.
+* The in-memory default keeps the runtime usable without a host, at the cost of a machine
+* identity that changes on every restart.
+*/
+let storage = (0, unstorage.createStorage)();
+let hasInstalledStorage = false;
+/**
+* Installs the storage driver the runtime persists to. Call once, before connecting.
+*/
+function setStorage(next) {
+	storage = next;
+	hasInstalledStorage = true;
+}
+/**
+* A storage backed by files under `base`, so the machine secret and the last Studio config
+* survive a restart. Repeated pairings of one machine depend on that secret staying put.
+*/
+function createFileStorage(base) {
+	return (0, unstorage.createStorage)({ driver: (0, unstorage_drivers_fs.default)({ base }) });
+}
+let fallbackSecretPromise = null;
+/**
+* Loads the fallback machine secret from the runtime storage.
+* On first use it generates a secret and persists it, so the machine identity stays
+* stable across restarts. An identity that changes on every boot breaks session
+* creation with Studio whenever the startup registration call fails.
+*/
+async function loadOrCreateFallbackSecret() {
+	if (!hasInstalledStorage) console.warn((0, node_util.styleText)("yellow", "Deriving the machine token before a storage driver was installed"), "call setStorage() first, or set KUBB_AGENT_SECRET, to keep a stable machine identity across restarts");
+	const stored = await storage.getItem("machine-secret").catch(() => null);
+	if (typeof stored === "string" && stored) return stored;
+	const secret = (0, node_crypto.randomBytes)(32).toString("hex");
+	await storage.setItem("machine-secret", secret).catch(() => {
+		console.warn((0, node_util.styleText)("yellow", "Could not persist the generated machine secret"), "set KUBB_AGENT_SECRET to keep a stable machine identity across restarts");
+	});
+	return secret;
+}
+/**
+* Returns the machine token derived from the `KUBB_AGENT_SECRET` environment variable.
+* Falls back to a generated secret persisted in the runtime storage if the env var is not set.
+* The token is hashed with SHA-256.
+*/
+async function getMachineToken() {
+	if (node_process.default.env.KUBB_AGENT_SECRET) return (0, node_crypto.hash)("sha256", node_process.default.env.KUBB_AGENT_SECRET);
+	fallbackSecretPromise ??= loadOrCreateFallbackSecret();
+	return (0, node_crypto.hash)("sha256", await fallbackSecretPromise);
+}
+//#endregion
+//#region src/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
+* revoked token) would otherwise never reach the user.
+*/
+function responseMessage(data) {
+	if (!data || typeof data !== "object") return;
+	const body = data;
+	for (const value of [
+		body.error_description,
+		body.message,
+		body.error
+	]) if (typeof value === "string" && value) return value;
+}
+/**
+* Retries after the first registration attempt, each backing off twice as far as the last.
+*/
+const REGISTER_RETRIES = 3;
+/**
+* Shared in-flight registration so concurrent pool sessions trigger one purge, not N.
+*/
+let registrationInFlight = null;
+/**
+* Thrown when Studio rejects the agent token itself (401). Retrying cannot help: the token was
+* revoked, or the agent it belonged to was deleted in the Studio UI. Hosts catch this to forget
+* the stored credential and pair again.
+*/
+var InvalidAgentTokenError = class extends Error {
+	constructor(studioUrl, options) {
+		super(`Kubb Studio rejected this agent's token. It was revoked or the agent was deleted in ${studioUrl}.`, options);
+		this.name = "InvalidAgentTokenError";
+	}
+};
+/**
+* Whether a thrown value carries `statusCode`. Not narrowed to `FetchError`: a host wrapper can
+* throw its own error shape with the same field.
+*
+* A 401 means the agent token itself was rejected. A 403 from the session create endpoint means
+* the machine token stored in Studio no longer matches this agent (missing or mismatched).
+*/
+function rejectedWith(error, statusCode) {
+	return error?.statusCode === statusCode;
+}
+function sessionError(cause) {
+	const detail = (cause instanceof ofetch.FetchError ? responseMessage(cause.data) : void 0) ?? getErrorMessage(cause);
+	return new Error(detail ? `Failed to get agent session from Kubb Studio: ${detail}` : "Failed to get agent session from Kubb Studio", { cause });
+}
+/**
+* Performs the raw session create request against Studio.
+*/
+async function requestAgentSession({ token, studioUrl }) {
+	const url = `${studioUrl}/api/agent/sessions`;
+	const data = await (0, ofetch.ofetch)(url, {
+		method: "POST",
+		headers: { Authorization: `Bearer ${token}` },
+		body: { machineToken: await getMachineToken() }
+	});
+	if (!data) throw new Error("No data available for agent session");
+	return data;
+}
+/**
+* Obtain an agent session token from Kubb Studio via HTTP.
+*
+* When Studio rejects the machine token (403), for example after the agent restarted
+* with a new identity while the startup registration call failed, the agent re-registers
+* and retries once, so a single failed registration can't permanently block session creation.
+*/
+async function createAgentSession({ token, studioUrl }) {
+	try {
+		return await requestAgentSession({
+			token,
+			studioUrl
+		});
+	} catch (error) {
+		if (rejectedWith(error, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: error });
+		if (!rejectedWith(error, 403) || !await registerAgent({
+			token,
+			studioUrl
+		})) throw sessionError(error);
+		try {
+			return await requestAgentSession({
+				token,
+				studioUrl
+			});
+		} catch (retryError) {
+			if (rejectedWith(retryError, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: retryError });
+			throw sessionError(retryError);
+		}
+	}
+}
+/**
+* Register this agent with Kubb Studio by sending the machine ID.
+* Called on agent startup before creating a WebSocket session, and again when
+* Studio rejects the machine token during session creation.
+*
+* Retries with backoff because a failed registration leaves Studio with a stale
+* machine token that blocks every subsequent session create call. Registration
+* purges all of the agent's sessions on the Studio side, so concurrent callers
+* (multiple pool sessions hitting a 403 at once) share one in-flight run instead
+* of purging each other's fresh sessions.
+*/
+function registerAgent(props) {
+	registrationInFlight ??= runRegistration(props).finally(() => {
+		registrationInFlight = null;
+	});
+	return registrationInFlight;
+}
+async function runRegistration({ token, studioUrl, poolSize }) {
+	const machineToken = await getMachineToken();
+	try {
+		await (0, ofetch.ofetch)(`${studioUrl}/api/agent/connect`, {
+			method: "POST",
+			headers: { Authorization: `Bearer ${token}` },
+			body: {
+				machineToken,
+				poolSize
+			},
+			retry: REGISTER_RETRIES,
+			retryDelay: ({ options }) => 2e3 * 2 ** (REGISTER_RETRIES - Number(options.retry))
+		});
+		return true;
+	} catch (error) {
+		if (rejectedWith(error, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: error });
+		console.error((0, node_util.styleText)("red", `Failed to register agent with Studio after 4 attempts`));
+		return false;
+	}
+}
+/**
+* Notify Kubb Studio that this agent is disconnecting.
+* Called on process termination or server close. A failed notify is logged and swallowed: the
+* local socket is already gone, and failing teardown must not block shutdown or reconnect.
+*/
+async function disconnect({ sessionId, token, studioUrl, slug }) {
+	const url = `${studioUrl}/api/agent/sessions/${sessionId}/disconnect`;
+	const tag = slug ?? "agent";
+	try {
+		await (0, ofetch.ofetch)(url, {
+			method: "POST",
+			headers: { Authorization: `Bearer ${token}` }
+		});
+		console.log((0, node_util.styleText)("green", `[${tag}] Disconnected from Studio`));
+	} catch (error) {
+		console.warn((0, node_util.styleText)("yellow", `[${tag}] Failed to notify Studio of disconnection: ${getErrorMessage(error)}`));
+	}
+}
+//#endregion
+//#region package.json
+var version = "5.1.0";
+//#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.
+*/
+function setupHookListener(hooks, root) {
+	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 ?? []], { 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();
+			else reject(ctx.error);
+		};
+		hooks.hook("kubb:hook:end", handleHookEnd);
+	});
+}
+//#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 }) {
+	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 });
+	await kubb.setup();
+	await hooks.callHook("kubb:info", { message: config.name ? `Build generation ${config.name}` : "Build generation" });
+	const { files, diagnostics, storage } = await kubb.safeBuild();
+	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 }) });
+		}
+		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/ws.ts
+/**
+* How many generated files are read from storage at once when building the
+* `kubb:generation:end` payload. A spec producing thousands of files would otherwise fire one
+* `storage.readItem` per file simultaneously.
+*/
+const FILE_READ_CONCURRENCY = 50;
+/**
+* How long the initial handshake may take before the socket is closed and the reconnect loop
+* takes over.
+*/
+const CONNECT_TIMEOUT_MS = 5e3;
+/**
+* Per-socket event counter. Every data message carries the next value so Studio can restore the
+* agent's emission order even when the relay delivers frames out of order. Keyed by the socket so
+* the count stays monotonic across every generation run on one connection, and is dropped
+* automatically once the socket is collected.
+*/
+const eventSeqCounters = /* @__PURE__ */ new WeakMap();
+function nextEventSeq(ws$1) {
+	const seq = eventSeqCounters.get(ws$1) ?? 0;
+	eventSeqCounters.set(ws$1, seq + 1);
+	return seq;
+}
+/**
+* Opens a Studio WebSocket connection and closes it when the initial handshake exceeds the configured timeout.
+*/
+function createWebsocket(url, options) {
+	const ws$2 = new ws.default(url, options);
+	const timer = setTimeout(() => {
+		if (ws$2.readyState === ws.default.CONNECTING) ws$2.close(3008, "Connection timeout");
+	}, CONNECT_TIMEOUT_MS);
+	ws$2.once("open", () => clearTimeout(timer));
+	ws$2.once("close", () => clearTimeout(timer));
+	return ws$2;
+}
+/**
+* Sends a serialized agent message when the Studio socket is ready to accept frames.
+*/
+function sendAgentMessage(ws$3, message) {
+	try {
+		if (ws$3.readyState !== ws.default.OPEN) return;
+		ws$3.send(JSON.stringify(message));
+	} catch (error) {
+		throw new Error("Failed to send message to Kubb Studio", { cause: error });
+	}
+}
+/**
+* Sends a single `kubb:error` payload to Studio, stamped from the same per-socket counter the event stream
+* uses so Studio can still order it against the generation events around it.
+*/
+function sendErrorMessage(ws$4, error) {
+	sendAgentMessage(ws$4, {
+		type: "agent:data",
+		payload: {
+			type: "kubb:error",
+			data: [{
+				message: error.message,
+				stack: error.stack
+			}],
+			timestamp: Date.now(),
+			seq: nextEventSeq(ws$4)
+		}
+	});
+}
+/**
+* Forwards selected Kubb lifecycle events to Studio as data messages for the active session.
+*/
+function setupEventsStream(ws$5, hooks) {
+	function sendDataMessage(payload) {
+		sendAgentMessage(ws$5, {
+			type: "agent:data",
+			payload: {
+				...payload,
+				timestamp: Date.now(),
+				seq: nextEventSeq(ws$5)
+			}
+		});
+	}
+	hooks.hook("kubb:plugin:start", (ctx) => {
+		sendDataMessage({
+			type: "kubb:plugin:start",
+			data: [{ plugin: ctx.plugin }]
+		});
+	});
+	hooks.hook("kubb:plugin:end", (ctx) => {
+		sendDataMessage({
+			type: "kubb:plugin:end",
+			data: [{
+				plugin: ctx.plugin,
+				duration: ctx.duration,
+				success: ctx.success
+			}]
+		});
+	});
+	hooks.hook("kubb:build:start", ({ config, adapter }) => {
+		sendDataMessage({
+			type: "kubb:build:start",
+			data: [{
+				config: { name: config.name },
+				adapter: { name: adapter.name }
+			}]
+		});
+	});
+	hooks.hook("kubb:build:end", ({ files, outputDir }) => {
+		sendDataMessage({
+			type: "kubb:build:end",
+			data: [{
+				files: files.map((file) => ({
+					path: file.path,
+					name: file.name
+				})),
+				outputDir
+			}]
+		});
+	});
+	hooks.hook("kubb:files:processing:start", ({ files }) => {
+		sendDataMessage({
+			type: "kubb:files:processing:start",
+			data: [{ total: files.length }]
+		});
+	});
+	hooks.hook("kubb:files:processing:update", ({ files }) => {
+		sendDataMessage({
+			type: "kubb:files:processing:update",
+			data: [{ files: files.map(({ file, processed, total, percentage }) => ({
+				file: file.path,
+				processed,
+				total,
+				percentage
+			})) }]
+		});
+	});
+	hooks.hook("kubb:files:processing:end", ({ files }) => {
+		sendDataMessage({
+			type: "kubb:files:processing:end",
+			data: [{ total: files.length }]
+		});
+	});
+	for (const type of [
+		"kubb:info",
+		"kubb:success",
+		"kubb:warn"
+	]) hooks.hook(type, ({ message, info }) => {
+		sendDataMessage({
+			type,
+			data: [{
+				message,
+				info
+			}]
+		});
+	});
+	hooks.hook("kubb:generation:start", ({ config }) => {
+		sendDataMessage({
+			type: "kubb:generation:start",
+			data: [{
+				name: config.name,
+				plugins: config.plugins.length
+			}]
+		});
+	});
+	hooks.hook("kubb:generation:end", async ({ config, storage, diagnostics = [], status, hrStart, filesCreated }) => {
+		const paths = await storage.readKeys();
+		const files = {};
+		await inParallel({
+			items: paths,
+			limit: FILE_READ_CONCURRENCY,
+			run: async (path) => {
+				const content = await storage.readItem(path);
+				if (content !== null) files[path] = content;
+			}
+		});
+		sendDataMessage({
+			type: "kubb:generation:end",
+			data: [{
+				config,
+				storage: files
+			}]
+		});
+		if (!hrStart) return;
+		sendDataMessage({
+			type: "kubb:generation:summary",
+			data: [{
+				duration: Math.round(getElapsedMs(hrStart)),
+				fileCount: filesCreated ?? 0,
+				failedPlugins: _kubb_core.Diagnostics.failedPlugins(diagnostics).length,
+				status: status ?? "success"
+			}]
+		});
+	});
+	hooks.hook("kubb:error", ({ error }) => {
+		sendDataMessage({
+			type: "kubb:error",
+			data: [{
+				message: error.message,
+				stack: error.stack
+			}]
+		});
+	});
+	for (const type of [
+		"kubb:lifecycle:start",
+		"kubb:lifecycle:end",
+		"kubb:format:start",
+		"kubb:format:end",
+		"kubb:lint:start",
+		"kubb:lint:end",
+		"kubb:hooks:start",
+		"kubb:hooks:end"
+	]) hooks.hook(type, () => {
+		sendDataMessage({
+			type,
+			data: []
+		});
+	});
+	hooks.hook("kubb:hook:start", ({ id, command, args }) => {
+		sendDataMessage({
+			type: "kubb:hook:start",
+			data: [{
+				id,
+				command,
+				args: args ? [...args] : void 0
+			}]
+		});
+	});
+	hooks.hook("kubb:hook:line", ({ id, line }) => {
+		sendDataMessage({
+			type: "kubb:hook:line",
+			data: [{
+				id,
+				line
+			}]
+		});
+	});
+	hooks.hook("kubb:hook:end", ({ id, command, args, success, error }) => {
+		sendDataMessage({
+			type: "kubb:hook:end",
+			data: [{
+				id,
+				command,
+				args: args ? [...args] : void 0,
+				success,
+				error: error ? {
+					message: error.message,
+					stack: error.stack
+				} : void 0
+			}]
+		});
+	});
+}
+//#endregion
+//#region src/connectStudio.ts
+/**
+* Schedules another connection attempt.
+*
+* Hoisted out of `connectToStudio` on purpose: a pending retry timer reaches its whole enclosing
+* scope, so keeping it inside would pin the closed socket, the hook emitter, and the session id
+* alive for the length of every retry interval.
+*/
+function reconnect(options) {
+	const { signal, retryInterval = agentDefaults.retryIntervalMs } = options;
+	if (signal?.aborted) return;
+	console.info((0, node_util.styleText)("dim", `Retrying connection in ${retryInterval}ms to Kubb Studio ...`));
+	const cancel = () => clearTimeout(timer);
+	const timer = setTimeout(() => {
+		signal?.removeEventListener("abort", cancel);
+		if (signal?.aborted) return;
+		connectToStudio(options).catch((error) => {
+			console.error((0, node_util.styleText)("red", `Reconnect attempt to Kubb Studio failed: ${getErrorMessage(error)}`));
+			if (error instanceof InvalidAgentTokenError) return;
+			reconnect(options);
+		});
+	}, retryInterval);
+	signal?.addEventListener("abort", cancel, { once: true });
+}
+async function connectToStudio(options) {
+	const { token, studioUrl = agentDefaults.studioUrl, configPath, loadConfig, version: version$1, client, allowWrite = false, allowConfigEdit = false, allowInput = false, allowExec = false, root = node_process.default.cwd(), heartbeatInterval: requestedHeartbeatInterval = agentDefaults.heartbeatIntervalMs, signal, installLogger } = options;
+	const heartbeatInterval = Math.min(requestedHeartbeatInterval, agentDefaults.heartbeatIntervalMs);
+	const hooks = new _kubb_core.Hookable();
+	await installLogger?.(hooks);
+	try {
+		await hooks.callHook("studio:connecting", { url: studioUrl });
+		const { sessionId, slug, wsUrl, isSandbox, version: sessionStudioVersion } = await createAgentSession({
+			token,
+			studioUrl
+		});
+		let studioVersion = sessionStudioVersion;
+		const ws = createWebsocket(wsUrl, { headers: { Authorization: `Bearer ${token}` } });
+		const canWrite = isSandbox ? false : allowWrite;
+		const canEditConfig = isSandbox ? false : allowConfigEdit;
+		const configFilePath = node_path.default.resolve(root, configPath);
+		const canUseInput = isSandbox || allowInput;
+		let serverDisconnected = false;
+		let isGenerating = false;
+		let heartbeatTimer;
+		let lastPongAt = Date.now();
+		const onAbort = () => void teardown({
+			reason: "shutdown",
+			retry: false
+		});
+		function cleanup(reason = "cleanup") {
+			clearInterval(heartbeatTimer);
+			heartbeatTimer = void 0;
+			signal?.removeEventListener("abort", onAbort);
+			hooks.removeAllHooks();
+			try {
+				ws.close(1e3, reason);
+			} catch {}
+			ws.removeEventListener("open", onOpen);
+			ws.removeEventListener("close", onClose);
+			ws.removeEventListener("error", onError);
+			ws.removeEventListener("message", onMessage);
+		}
+		/**
+		* Reads `kubb.config.ts` and reports which plugin options Studio may edit.
+		*
+		* Skipped when the host did not grant `allowConfigEdit`. The patcher pulls in `magicast`
+		* (~25ms, ~55MB RSS), so read-only agents never import it.
+		*
+		* Not cached: the user can edit the file between two Studio actions.
+		*/
+		async function readConfigFileView(source) {
+			if (!canEditConfig) return;
+			try {
+				const { readConfig } = await Promise.resolve().then(() => require("./configFile-DjzP1_Ln.cjs"));
+				return readConfig(source ?? await (0, node_fs_promises.readFile)(configFilePath, "utf-8"));
+			} catch (error) {
+				await hooks.callHook("studio:warn", { message: `Could not read ${configFilePath}: ${getErrorMessage(error)}` });
+				return;
+			}
+		}
+		async function sendConnectedPayload() {
+			const config = await loadConfig();
+			sendAgentMessage(ws, {
+				type: "agent:connect",
+				payload: {
+					versions: {
+						kubb: version,
+						agent: version$1
+					},
+					root,
+					config: {
+						path: configPath,
+						file: await readConfigFileView(),
+						plugins: config.plugins.map((plugin) => ({
+							name: `@kubb/${plugin.name}`,
+							options: plugin.options ?? {}
+						}))
+					},
+					permissions: {
+						allowWrite: canWrite,
+						allowInput: canUseInput,
+						allowExec,
+						allowConfigEdit: canEditConfig
+					}
+				}
+			});
+		}
+		async function handleOpen() {
+			lastPongAt = Date.now();
+			await hooks.callHook("studio:connected", {
+				url: studioUrl,
+				versions: {
+					studio: studioVersion,
+					kubb: version,
+					agent: version$1
+				}
+			});
+			try {
+				await sendConnectedPayload();
+			} catch (error) {
+				await hooks.callHook("studio:warn", { message: `Failed to send the connect payload: ${getErrorMessage(error)}` });
+			}
+		}
+		const onOpen = () => void handleOpen().catch(() => {});
+		/**
+		* Drops the socket and tells Studio the session is over. `serverDisconnected` guards against
+		* the close event running this a second time, and against a shutdown reconnecting.
+		*/
+		async function teardown({ reason, retry }) {
+			if (serverDisconnected) return;
+			serverDisconnected = true;
+			if (reason === "shutdown") sendAgentMessage(ws, {
+				type: "agent:disconnect",
+				reason: "shutdown"
+			});
+			cleanup(reason);
+			await disconnect({
+				sessionId,
+				studioUrl,
+				token,
+				slug
+			}).catch(() => {});
+			if (retry) reconnect(options);
+		}
+		const onClose = () => teardown({ retry: true });
+		const onError = () => {
+			hooks.callHook("studio:error", { error: /* @__PURE__ */ new Error("Failed to connect to Kubb Studio") });
+			return onClose();
+		};
+		ws.addEventListener("open", onOpen);
+		ws.addEventListener("close", onClose);
+		ws.addEventListener("error", onError);
+		signal?.addEventListener("abort", onAbort, { once: true });
+		heartbeatTimer = setInterval(() => {
+			if (Date.now() - lastPongAt > heartbeatInterval * 2) {
+				hooks.callHook("studio:warn", { message: "No reply from Kubb Studio, terminating the stale connection" });
+				clearInterval(heartbeatTimer);
+				heartbeatTimer = void 0;
+				ws.terminate();
+				return;
+			}
+			sendAgentMessage(ws, { type: "agent:ping" });
+		}, heartbeatInterval);
+		hooks.hook("kubb:error", ({ error }) => sendErrorMessage(ws, error));
+		const onMessage = async (message) => {
+			try {
+				const data = JSON.parse(message.data);
+				if (require_protocol.isStudioPingMessage(data)) {
+					lastPongAt = Date.now();
+					return;
+				}
+				if (require_protocol.isDisconnectMessage(data)) {
+					await hooks.callHook("studio:disconnected", { reason: data.reason });
+					if (data.reason === "revoked") {
+						cleanup(`session_${data.reason}`);
+						return;
+					}
+					if (data.reason === "expired") {
+						cleanup();
+						reconnect(options);
+						return;
+					}
+					return;
+				}
+				if (require_protocol.isCommandMessage(data)) {
+					const command = data.type.slice(7);
+					await hooks.callHook("studio:command:start", { command });
+					if (data.type === "studio:generate") {
+						if (isGenerating) {
+							await hooks.callHook("studio:warn", { message: "Ignored generate: a generation is already in progress" });
+							await Promise.resolve(hooks.callHook("kubb:error", { error: /* @__PURE__ */ new Error("A generation is already in progress, please wait for it to finish") })).catch(() => {});
+							return;
+						}
+						isGenerating = true;
+						try {
+							const config = await loadConfig();
+							const patch = data.payload;
+							const plugins = await require_resolveConfig.mergePlugins(config.plugins, patch?.plugins);
+							const adapter = await require_resolveConfig.mergeAdapter(config.adapter, patch?.adapter);
+							const inputOverride = isSandbox ? patch?.input ?? "" : allowInput && patch?.input || void 0;
+							if (allowWrite && isSandbox) await hooks.callHook("studio:warn", { message: "Running in a sandbox, so writing files is disabled" });
+							if (patch?.input && !canUseInput) {
+								const remedy = client?.kind === "cli" ? "--allowInput, or answer yes when kubb studio asks," : "KUBB_AGENT_ALLOW_INPUT=true";
+								await hooks.callHook("studio:warn", { message: `Ignored the spec from Studio; set ${remedy} to generate from it` });
+							}
+							const generationHooks = new _kubb_core.Hookable();
+							await installLogger?.(generationHooks);
+							setupHookListener(generationHooks, root);
+							setupEventsStream(ws, generationHooks);
+							const resolvedPlugins = plugins ?? config.plugins;
+							await generate({
+								config: {
+									...config,
+									root,
+									input: inputOverride ?? config.input,
+									storage: canWrite ? (0, _kubb_core.fsStorage)() : (0, _kubb_core.memoryStorage)(),
+									output: allowExec ? { ...config.output } : {
+										...config.output,
+										format: false,
+										lint: false,
+										postGenerate: []
+									},
+									plugins: resolvedPlugins,
+									adapter
+								},
+								hooks: generationHooks
+							});
+							await hooks.callHook("studio:command:end", {
+								command,
+								info: `${resolvedPlugins.length} plugin${resolvedPlugins.length === 1 ? "" : "s"}, ${canWrite ? "written to disk" : "in memory"}${inputOverride !== void 0 ? ", from a Studio spec" : ""}`
+							});
+						} finally {
+							isGenerating = false;
+						}
+						return;
+					}
+					if (data.type === "studio:connect") {
+						studioVersion = data.version ?? studioVersion;
+						await sendConnectedPayload();
+						await hooks.callHook("studio:command:end", { command });
+						return;
+					}
+					if (data.type === "studio:save") {
+						if (!Array.isArray(data.edits)) {
+							await hooks.callHook("studio:warn", { message: "Ignored save: the message carried no edits" });
+							sendAgentMessage(ws, {
+								type: "agent:save",
+								payload: {
+									outcomes: [],
+									changed: false
+								}
+							});
+							return;
+						}
+						const edits = data.edits;
+						const refuse = (reason) => sendAgentMessage(ws, {
+							type: "agent:save",
+							payload: {
+								outcomes: edits.map((edit) => ({
+									edit,
+									applied: false,
+									reason
+								})),
+								changed: false
+							}
+						});
+						if (!canEditConfig) {
+							await hooks.callHook("studio:warn", { message: "Ignored save: editing kubb.config.ts was not granted" });
+							refuse("the agent was not granted permission to edit kubb.config.ts");
+							return;
+						}
+						if (isGenerating) {
+							refuse("a generation is in progress");
+							return;
+						}
+						try {
+							const { applyConfigEdits } = await Promise.resolve().then(() => require("./configFile-DjzP1_Ln.cjs"));
+							const { source: patched, outcomes, changed } = applyConfigEdits(await (0, node_fs_promises.readFile)(configFilePath, "utf-8"), edits);
+							if (changed) await (0, node_fs_promises.writeFile)(configFilePath, patched, "utf-8");
+							sendAgentMessage(ws, {
+								type: "agent:save",
+								payload: {
+									outcomes,
+									changed,
+									file: changed ? await readConfigFileView(patched) : void 0
+								}
+							});
+							const applied = outcomes.filter((outcome) => outcome.applied).length;
+							await hooks.callHook("studio:command:end", {
+								command,
+								info: `applied ${applied}/${outcomes.length} edits to ${configPath}`
+							});
+						} catch (error) {
+							await hooks.callHook("studio:error", { error: toError(error) });
+							refuse(getErrorMessage(error));
+						}
+						return;
+					}
+					return;
+				}
+				await hooks.callHook("studio:warn", { message: `Ignored an unknown message from Kubb Studio: ${data.type}` });
+			} catch (error) {
+				await hooks.callHook("studio:error", { error: toError(error) });
+				await Promise.resolve(hooks.callHook("kubb:error", { error: toError(error) })).catch(() => {});
+			}
+		};
+		ws.addEventListener("message", onMessage);
+	} catch (error) {
+		await hooks.callHook("studio:error", { error: toError(error) });
+		if (error instanceof InvalidAgentTokenError) throw error;
+		reconnect(options);
+	}
+}
+//#endregion
+//#region src/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.
+*
+* Every permission is off by default. A host that wants more grants it explicitly.
+*
+* @example
+* ```ts
+* const studio = createClient({ token, configPath, version, loadConfig: () => loadMyConfig() })
+* await studio.connect()
+* ```
+*/
+function createClient({ storage, ...options }) {
+	if (storage) setStorage(storage);
+	const controller = new AbortController();
+	const poolSize = options.poolSize ?? agentDefaults.poolSize;
+	return {
+		async connect() {
+			await registerAgent({
+				token: options.token,
+				studioUrl: options.studioUrl ?? agentDefaults.studioUrl,
+				poolSize
+			});
+			await Promise.all(Array.from({ length: poolSize }, () => connectToStudio({
+				...options,
+				signal: controller.signal
+			})));
+		},
+		disconnect() {
+			controller.abort();
+		}
+	};
+}
+//#endregion
+//#region src/pair.ts
+/**
+* Identifies the CLI to Studio's device authorization endpoint. A label, not a secret: what
+* authorizes a pairing is a signed-in person approving the code in the browser.
+*/
+const CLIENT_ID = "kubb-cli";
+/**
+* Asks Studio for a pairing code. The machine token travels with the request and is stored against
+* the code, so approval knows which machine it is pairing: the same machine pairing twice rotates
+* one agent's token instead of creating a second agent.
+*/
+async function startPairing({ studioUrl = agentDefaults.studioUrl, name, hostname, clientId = CLIENT_ID, agentKind }) {
+	return (0, ofetch.ofetch)(`${studioUrl}/api/auth/device/code`, {
+		method: "POST",
+		body: {
+			client_id: clientId,
+			name,
+			hostname,
+			machine_token: await getMachineToken(),
+			agent_kind: agentKind
+		}
+	});
+}
+function isPairingResult(response) {
+	return !!response && typeof response === "object" && "token" in response && typeof response.token === "string";
+}
+/**
+* Polls until the user approves or denies, honoring the server's `slow_down` back-off. A poll that
+* cannot reach Studio is warned about and retried, since the code stays valid either way.
+*
+* Studio's own endpoint is used rather than the auth layer's `/device/token`, because an approved
+* Kubb pairing is worth an agent bearer token, not a user session.
+*
+* @throws when the code expires, the user denies it, or Studio returns an unexpected error.
+*/
+async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, session }) {
+	const deadline = Date.now() + (session.expires_in > 0 ? session.expires_in : 600) * 1e3;
+	let intervalMs = (session.interval > 0 ? session.interval : 5) * 1e3;
+	while (Date.now() < deadline) {
+		await (0, node_timers_promises.setTimeout)(intervalMs);
+		let response;
+		try {
+			response = await (0, ofetch.ofetch)(`${studioUrl}/api/agent/token`, {
+				method: "POST",
+				body: { device_code: session.device_code },
+				ignoreResponseError: true
+			});
+		} catch (error) {
+			console.warn((0, node_util.styleText)("yellow", `Could not reach Kubb Studio while waiting for approval, retrying: ${getErrorMessage(error)}`));
+			continue;
+		}
+		if (isPairingResult(response)) return response;
+		if (!response || typeof response !== "object" || !("error" in response) || typeof response.error !== "string") throw new Error("Kubb Studio returned an empty pairing response, pair again");
+		if (response.error === "authorization_pending") continue;
+		if (response.error === "slow_down") {
+			intervalMs += 5e3;
+			continue;
+		}
+		if (response.error === "access_denied") throw new Error(response.error_description ?? "Pairing was denied in the browser");
+		if (response.error === "expired_token" || response.error === "invalid_grant") throw new Error(response.error_description ?? "The pairing code expired, pair again");
+		throw new Error(response.error_description ?? `Pairing failed (${response.error})`);
+	}
+	throw new Error("The pairing code expired, pair again");
+}
+//#endregion
+exports.InvalidAgentTokenError = InvalidAgentTokenError;
+exports.createClient = createClient;
+exports.createFileStorage = createFileStorage;
+exports.defaultStudioUrl = defaultStudioUrl;
+exports.pollForPairingToken = pollForPairingToken;
+exports.setStorage = setStorage;
+exports.startPairing = startPairing;
+
+//# sourceMappingURL=index.cjs.map