@kubb/studio 5.12.0 → 5.12.2

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { F as PublishedSnapshot, G as SnapshotUploadMetadata, O as InstalledExtensions, a as AgentConnectInfo, c as AgentPermissions, d as ConfigEditOutcome, s as AgentPermission, u as ConfigEdit } from "./protocol-Dn1jdnFB.cjs";
+import { A as InstalledExtensions, L as PublishedSnapshot, a as AgentConnectInfo, c as AgentPermissions, d as ConfigEditOutcome, q as SnapshotUploadMetadata, s as AgentPermission, u as ConfigEdit } from "./protocol-DhNrwhqp.cjs";
 import { Config, Hookable, KubbHooks } from "@kubb/core";
 //#region src/connect.d.ts
 /**
@@ -45,7 +45,7 @@ declare global {
        * A finished command and what it did, such as `applied 2/3 edits to kubb.config.ts`.
        */
       'studio:command': [ctx: {
-        command: 'generate' | 'saveConfig' | 'readFiles' | 'readInput' | 'readDiff';
+        command: 'generate' | 'saveConfig' | 'installExtension' | 'updateExtensions' | 'readFiles' | 'readInput' | 'readDiff';
         info: string;
         /**
          * The Studio user who asked for the command, when Studio names one.
@@ -97,6 +97,8 @@ type ConnectAgentOptions = {
    * What Studio may do in this project. Every permission is off unless granted.
    */
   permissions?: Partial<AgentPermissions>;
+  /** The CLI entry `installExtension` runs `kubb add` with. Found through the project's `kubb` or `@kubb/cli` dependency when omitted. */
+  kubbBin?: string;
   /**
    * Receives the `studio:*` hooks and the `kubb:*` hooks of every generation.
    */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { F as PublishedSnapshot, G as SnapshotUploadMetadata, O as InstalledExtensions, a as AgentConnectInfo, c as AgentPermissions, d as ConfigEditOutcome, s as AgentPermission, u as ConfigEdit } from "./protocol-Dn1jdnFB.js";
+import { A as InstalledExtensions, L as PublishedSnapshot, a as AgentConnectInfo, c as AgentPermissions, d as ConfigEditOutcome, q as SnapshotUploadMetadata, s as AgentPermission, u as ConfigEdit } from "./protocol-DhNrwhqp.js";
 import { Config, Hookable, KubbHooks } from "@kubb/core";
 //#region src/connect.d.ts
 /**
@@ -45,7 +45,7 @@ declare global {
        * A finished command and what it did, such as `applied 2/3 edits to kubb.config.ts`.
        */
       'studio:command': [ctx: {
-        command: 'generate' | 'saveConfig' | 'readFiles' | 'readInput' | 'readDiff';
+        command: 'generate' | 'saveConfig' | 'installExtension' | 'updateExtensions' | 'readFiles' | 'readInput' | 'readDiff';
         info: string;
         /**
          * The Studio user who asked for the command, when Studio names one.
@@ -97,6 +97,8 @@ type ConnectAgentOptions = {
    * What Studio may do in this project. Every permission is off unless granted.
    */
   permissions?: Partial<AgentPermissions>;
+  /** The CLI entry `installExtension` runs `kubb add` with. Found through the project's `kubb` or `@kubb/cli` dependency when omitted. */
+  kubbBin?: string;
   /**
    * Receives the `studio:*` hooks and the `kubb:*` hooks of every generation.
    */

package/dist/index.js

@@ -1,19 +1,25 @@
 import { AGENT_INSTANCE_HEADER, AGENT_SOCKET_PATH, AgentCloseCode, AgentMessage, AgentPermission, MAX_SNAPSHOT_BYTES, generationEventTypes } from "./protocol.js";
 import { createRequire } from "node:module";
 import { createHash, hash, randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 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 { x } from "tinyexec";
 import { mkdir, mkdir as mkdir$1, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import { Diagnostics, Hookable, cacheStorage, createKubb, fsStorage, getInputKind, isPackageName, readInstalledPackages, resolveCacheDir, resolveMeta } from "@kubb/core";
+import { Diagnostics, Hookable, cacheStorage, checkoutGitInput, createKubb, fsStorage, getInputKind, isPackageName, isPublicAddress, readInstalledPackages, resolveCacheDir, resolveMeta } from "@kubb/core";
 import { RpcTarget, newWebSocketRpcSession } from "capnweb";
 import { detectCodeFormat, parseExpression, parseModule } from "magicast";
+import { pathToFileURL } from "node:url";
 import { structuredPatch } from "diff";
 import { stripVTControlCharacters } from "node:util";
 import { ast } from "@kubb/ast";
+import dns from "node:dns";
+import http from "node:http";
+import https from "node:https";
+import net from "node:net";
+import { Readable, Transform } from "node:stream";
 import { ofetch } from "ofetch";
 import { gzipSync } from "node:zlib";
 //#endregion
@@ -196,7 +202,7 @@ function getElapsedMs(hrStart) {
 }
 //#endregion
 //#region package.json
-var version = "5.12.0";
+var version = "5.12.2";
 //#endregion
 //#region src/resolveConfig.ts
 /**
@@ -1842,6 +1848,106 @@ function createGenerationStream(hooks, jobId) {
 	};
 }
 //#endregion
+//#region src/publicFetch.ts
+const MAX_REDIRECTS = 5;
+const MAX_BYTES = 52428800;
+const REDIRECTS = /* @__PURE__ */ new Set([
+	301,
+	302,
+	303,
+	307,
+	308
+]);
+const NO_BODY = /* @__PURE__ */ new Set([
+	204,
+	205,
+	304
+]);
+function notPublic(host) {
+	return /* @__PURE__ */ new Error(`${host} is not a public address, so a managed agent does not fetch from it`);
+}
+function createLookup(blocked) {
+	return (hostname, options, callback) => {
+		dns.lookup(hostname, {
+			...options,
+			all: true
+		}, (error, addresses) => {
+			if (error) return callback(error, "", 0);
+			const found = addresses;
+			if (!found.length || found.some(({ address }) => !isPublicAddress(address, blocked))) return callback(notPublic(hostname), "", 0);
+			return options.all ? callback(null, found) : callback(null, found[0].address, found[0].family);
+		});
+	};
+}
+function request({ url, blocked, signal }) {
+	if (url.protocol !== "http:" && url.protocol !== "https:") return Promise.reject(/* @__PURE__ */ new Error(`Only http and https URLs are fetched, not ${url.protocol}`));
+	const host = url.hostname.replace(/^\[|\]$/g, "");
+	if (net.isIP(host) && !isPublicAddress(host, blocked)) return Promise.reject(notPublic(host));
+	return new Promise((resolve, reject) => {
+		const req = (url.protocol === "https:" ? https.request : http.request)(url, {
+			method: "GET",
+			lookup: createLookup(blocked),
+			signal: signal ?? void 0,
+			headers: { "accept-encoding": "identity" }
+		}, (res) => {
+			const headers = new Headers();
+			for (const [key, value] of Object.entries(res.headers)) for (const item of [value].flat()) if (item !== void 0) headers.append(key, item);
+			let total = 0;
+			const limit = new Transform({ transform(chunk, _encoding, done) {
+				total += chunk.length;
+				done(total > MAX_BYTES ? /* @__PURE__ */ new Error("The response is larger than 50 MB") : null, chunk);
+			} });
+			res.on("error", (error) => limit.destroy(error));
+			res.pipe(limit);
+			const body = NO_BODY.has(res.statusCode ?? 0) ? null : Readable.toWeb(limit);
+			resolve(new Response(body, {
+				status: res.statusCode,
+				statusText: res.statusMessage,
+				headers
+			}));
+		});
+		req.on("error", reject);
+		req.end();
+	});
+}
+/**
+* Builds a `fetch` that only reaches addresses `blocked` does not list. It follows redirects itself
+* and checks every hop, and takes GET requests only, since that is all a spec load needs.
+*/
+function createPublicFetch(blocked) {
+	const publicFetch = async (input, init) => {
+		if (typeof input !== "string" && !(input instanceof URL)) throw new TypeError("A managed agent fetches by URL only");
+		if (init?.method && init.method.toUpperCase() !== "GET") throw new TypeError("A managed agent only sends GET requests");
+		let url = new URL(input);
+		for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+			const response = await request({
+				url,
+				blocked,
+				signal: init?.signal
+			});
+			const location = response.headers.get("location");
+			if (!REDIRECTS.has(response.status) || !location) return response;
+			await response.body?.cancel();
+			url = new URL(location, url);
+		}
+		throw new Error(`Stopped after ${MAX_REDIRECTS} redirects from ${String(input)}`);
+	};
+	return publicFetch;
+}
+/**
+* Runs `run` with the global `fetch` limited to public addresses, then puts the original back.
+* A managed agent runs one job at a time, so nothing else shares the window.
+*/
+async function withPublicFetch(run) {
+	const original = globalThis.fetch;
+	globalThis.fetch = createPublicFetch();
+	try {
+		return await run();
+	} finally {
+		globalThis.fetch = original;
+	}
+}
+//#endregion
 //#region src/url.ts
 /**
 * Hosted Kubb Studio URL, used when a host passes none.
@@ -1878,6 +1984,11 @@ const OPEN_TIMEOUT_MS = 5e3;
 const MAX_RETRY_DELAY_MS = 3e4;
 const DISK_SNAPSHOT_MAX_FILES = 1e4;
 const SANDBOX_GENERATION_TTL_MS = 9e5;
+const MANAGED_INPUT_KINDS = /* @__PURE__ */ new Set([
+	"inline",
+	"url",
+	"git"
+]);
 /** Extensions `kubb` ships with, so they count as installed without being a direct dependency. */
 const BUILT_IN_PACKAGES = [
 	"@kubb/adapter-oas",
@@ -1903,6 +2014,43 @@ var IncompatibleAgentError = class extends Error {
 		this.name = "IncompatibleAgentError";
 	}
 };
+const INSTALL_TIMEOUT_MS = 3e5;
+/** `owner/slug` or `slug`, as `kubb add` takes it. Checked before it becomes an argument. */
+const REGISTRY_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)?$/;
+/** The CLI the project depends on, so `kubb add` installs next to what the config imports. */
+function findKubbBin(root) {
+	const require = createRequire(path.resolve(root, "package.json"));
+	const names = ["kubb", "@kubb/cli"];
+	return (require.resolve.paths("kubb") ?? []).flatMap((dir) => names.map((name) => path.join(dir, name, "bin", "kubb.js"))).find((bin) => existsSync(bin));
+}
+/** Runs a `kubb` command without a shell, and keeps the end of its output for the failure reason. */
+async function runKubb({ bin, args, cwd, signal }) {
+	try {
+		const { stdout, stderr, exitCode } = await x(process$1.execPath, [bin, ...args], {
+			signal,
+			timeout: INSTALL_TIMEOUT_MS,
+			throwOnError: false,
+			nodeOptions: {
+				cwd,
+				env: {
+					...process$1.env,
+					NO_COLOR: "1",
+					FORCE_COLOR: "0"
+				}
+			}
+		});
+		const output = `${stdout}\n${stderr}`.trim().split("\n").slice(-20).join("\n");
+		return {
+			failed: exitCode !== 0,
+			output: output || `kubb ${args[0]} exited with ${exitCode ?? "a signal"}`
+		};
+	} catch (error) {
+		return {
+			failed: true,
+			output: `kubb ${args[0]} did not run: ${getErrorMessage(error)}`
+		};
+	}
+}
 function emit(hooks, name, ...args) {
 	return Promise.resolve(hooks.callHook(name, ...args)).catch(() => {});
 }
@@ -1964,12 +2112,17 @@ var Agent = class extends RpcTarget {
 	get #sandbox() {
 		return this.#session.info?.sandbox === true;
 	}
+	get #managed() {
+		return this.#session.info?.managed === true;
+	}
 	get #permissions() {
 		const { permissions } = this.#options;
 		return this.#sandbox ? {
 			...permissions,
 			allowWrite: false,
 			allowConfigEdit: false,
+			allowInstall: false,
+			allowUpdate: false,
 			allowRead: true,
 			allowReadAst: true
 		} : permissions;
@@ -2121,6 +2274,8 @@ var Agent = class extends RpcTarget {
 			message: "Connection is closed"
 		});
 		if (this.#session.active) return this.#refuse({ message: AgentMessage.GENERATION_IN_PROGRESS });
+		if (this.#session.install) return this.#refuse({ message: AgentMessage.INSTALL_IN_PROGRESS });
+		if (this.#session.saving) return this.#refuse({ message: AgentMessage.SAVE_IN_PROGRESS });
 		const settled = Promise.withResolvers();
 		this.#session.active = {
 			jobId: input.jobId,
@@ -2159,8 +2314,9 @@ var Agent = class extends RpcTarget {
 	*/
 	async #generate({ input, root, outputRoot, signal }) {
 		const { jobId, config: patch } = input;
-		const studioInput = this.#sandbox ? patch?.input : void 0;
+		const studioInput = this.#sandbox || this.#managed ? patch?.input : void 0;
 		if (this.#sandbox && (typeof studioInput !== "string" || !studioInput.trim() || getInputKind(studioInput) !== "inline")) return this.#refuse({ message: AgentMessage.SANDBOX_INPUT_ONLY });
+		if (this.#managed && studioInput !== void 0 && !MANAGED_INPUT_KINDS.has(getInputKind(studioInput))) return this.#refuse({ message: AgentMessage.MANAGED_INPUT_KIND });
 		const [configs, extensions] = await Promise.all([this.#options.loadConfigs(), this.#installedExtensions()]);
 		const config = pickConfig(configs, patch?.config);
 		if (!config) return this.#refuse({ message: AgentMessage.CONFIG_ENTRY_NOT_FOUND });
@@ -2189,12 +2345,13 @@ var Agent = class extends RpcTarget {
 			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 files = await generate({
+		if (patch?.input && !this.#sandbox && !this.#managed) await emit(this.#options.hooks, "kubb:warn", { message: "Ignored the spec from Studio: generating from a Studio spec is only available to a sandbox or managed agent" });
+		const checkout = this.#managed && studioInput !== void 0 && getInputKind(studioInput) === "git" ? await checkoutGitInput(studioInput, signal, { publicOnly: true }).catch((error) => this.#refuse({ message: getErrorMessage(error) })) : void 0;
+		const run = () => generate({
 			config: {
 				...config,
 				root,
-				input: studioInput ?? config.input,
+				input: checkout?.path ?? studioInput ?? config.input,
 				storage: outputRoot ? stagingStorage({
 					root,
 					directory: outputRoot
@@ -2206,11 +2363,12 @@ var Agent = class extends RpcTarget {
 			hooks: this.#options.hooks,
 			signal,
 			allowExec: this.#permissions.allowWrite && this.#permissions.allowExec
-		}).catch(async (error) => {
+		});
+		const files = await (this.#managed ? withPublicFetch(run) : run()).catch(async (error) => {
 			await this.#generations.drop(jobId);
 			await this.#logCommand("generate", getErrorMessage(error), input.requestedBy, true);
 			throw error;
-		});
+		}).finally(() => checkout?.dispose());
 		const output = await this.#generations.keep({
 			jobId,
 			files,
@@ -2258,7 +2416,9 @@ var Agent = class extends RpcTarget {
 			await this.#warn({ message: "Ignored save: editing kubb.config.ts was not granted" });
 			return refuse("the agent was not granted permission to edit kubb.config.ts");
 		}
-		if (this.#session.active) return refuse("a generation is in progress");
+		const busy = this.#busy();
+		if (busy) return refuse(busy);
+		this.#session.saving = true;
 		try {
 			const { outcomes, changed } = await writeConfigEdits({
 				filePath: configFile,
@@ -2274,6 +2434,110 @@ var Agent = class extends RpcTarget {
 		} catch (error) {
 			await emit(this.#options.hooks, "studio:error", { error: toError(error) });
 			return refuse(getErrorMessage(error));
+		} finally {
+			this.#session.saving = false;
+		}
+	}
+	/**
+	* Installs a registry extension into the project with `kubb add <id> --yes`, which also adds a
+	* plugin to `kubb.config.ts`. Studio calls `connect()` again afterwards to see the result.
+	*/
+	async installExtension(input) {
+		this.#assertConnected();
+		const { root, configFile, kubbBin = findKubbBin(root) } = this.#options;
+		const refuse = async (reason, permission) => {
+			await this.#warn({
+				message: `Ignored install: ${reason}`,
+				permission
+			});
+			return {
+				installed: false,
+				reason
+			};
+		};
+		if (typeof input?.id !== "string" || !REGISTRY_ID.test(input.id)) return refuse("the message carried no registry id");
+		if (!this.#permissions.allowInstall) return refuse("installing extensions was not granted", AgentPermission.INSTALL);
+		if (!this.#permissions.allowConfigEdit) return refuse("editing kubb.config.ts was not granted", AgentPermission.CONFIG_EDIT);
+		const busy = this.#busy();
+		if (busy) return refuse(busy);
+		if (!kubbBin) return refuse("kubb is not installed in the project");
+		const { failed, output } = await this.#runKubb({
+			bin: kubbBin,
+			args: [
+				"add",
+				input.id,
+				"--yes",
+				"--config",
+				configFile
+			]
+		});
+		await this.#logCommand("installExtension", `${failed ? "failed to install" : "installed"} ${input.id}`, input.requestedBy, failed);
+		return failed ? {
+			installed: false,
+			reason: output
+		} : { installed: true };
+	}
+	/**
+	* Moves installed extensions to the registry's version with `kubb update [ids] --yes`, which
+	* installs packages and leaves `kubb.config.ts` alone. Studio calls `connect()` again afterwards.
+	*/
+	async updateExtensions(input) {
+		this.#assertConnected();
+		const { root, kubbBin = findKubbBin(root) } = this.#options;
+		const refuse = async (reason, permission) => {
+			await this.#warn({
+				message: `Ignored update: ${reason}`,
+				permission
+			});
+			return {
+				updated: false,
+				reason
+			};
+		};
+		const ids = input?.ids ?? [];
+		if (!Array.isArray(ids) || !ids.every((id) => typeof id === "string" && REGISTRY_ID.test(id))) return refuse("the message carried an invalid registry id");
+		if (!this.#permissions.allowUpdate) return refuse("updating extensions was not granted", AgentPermission.UPDATE);
+		const busy = this.#busy();
+		if (busy) return refuse(busy);
+		if (!kubbBin) return refuse("kubb is not installed in the project");
+		const { failed, output } = await this.#runKubb({
+			bin: kubbBin,
+			args: [
+				"update",
+				...ids,
+				"--yes"
+			]
+		});
+		await this.#logCommand("updateExtensions", `${failed ? "failed to update" : "updated"} ${ids.join(", ") || "all extensions"}`, input?.requestedBy, failed);
+		return failed ? {
+			updated: false,
+			reason: output
+		} : { updated: true };
+	}
+	/** Why a command that touches the project cannot start right now. */
+	#busy() {
+		if (this.#session.active) return "a generation is in progress";
+		if (this.#session.install) return "an install or update is in progress";
+		if (this.#session.saving) return "a save is in progress";
+	}
+	/** Runs `kubb` in the project while holding off saves and generations, and ends it when the socket closes. */
+	async #runKubb({ bin, args }) {
+		const controller = new AbortController();
+		const settled = Promise.withResolvers();
+		this.#session.install = {
+			abort: () => controller.abort(),
+			settled: settled.promise
+		};
+		try {
+			return await runKubb({
+				bin,
+				args,
+				cwd: this.#options.root,
+				signal: controller.signal
+			});
+		} finally {
+			this.#session.install = void 0;
+			settled.resolve();
 		}
 	}
 	/**
@@ -2458,6 +2722,8 @@ async function runSession({ options, openRpc, url, instanceId }) {
 		await emit(hooks, "studio:warn", { message: "Canceled the running generation: the connection to Kubb Studio closed" });
 	}
 	await active?.settled;
+	session.install?.abort();
+	await session.install?.settled;
 	await agent.clear();
 	return {
 		...close,
@@ -2526,6 +2792,8 @@ async function runAgent({ options, openRpc }) {
 		permissions: {
 			allowWrite: false,
 			allowConfigEdit: false,
+			allowInstall: false,
+			allowUpdate: false,
 			allowExec: false,
 			allowRead: false,
 			allowReadAst: false,