@kubb/studio 5.12.1 → 5.12.3

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-CG1bPO_H.cjs";
+import { J as SnapshotUploadMetadata, R as PublishedSnapshot, a as AgentConnectInfo, c as AgentPermissions, f as ConfigEditOutcome, j as InstalledExtensions, s as AgentPermission, u as ConfigEdit } from "./protocol-WYICLbSg.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-CG1bPO_H.js";
+import { J as SnapshotUploadMetadata, R as PublishedSnapshot, a as AgentConnectInfo, c as AgentPermissions, f as ConfigEditOutcome, j as InstalledExtensions, s as AgentPermission, u as ConfigEdit } from "./protocol-WYICLbSg.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,17 +1,17 @@
-import { AGENT_INSTANCE_HEADER, AGENT_SOCKET_PATH, AgentCloseCode, AgentMessage, AgentPermission, MAX_SNAPSHOT_BYTES, generationEventTypes } from "./protocol.js";
+import { AGENT_INSTANCE_HEADER, AGENT_SOCKET_PATH, AgentCloseCode, AgentMessage, AgentPermission, ConfigEditOperation, 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 { mkdir, mkdir as mkdir$1, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 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 { Readable, Transform } from "node:stream";
-import { existsSync } from "node:fs";
-import { mkdir, mkdir as mkdir$1, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { x } from "tinyexec";
 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";
@@ -19,6 +19,7 @@ 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
@@ -201,7 +202,7 @@ function getElapsedMs(hrStart) {
 }
 //#endregion
 //#region package.json
-var version = "5.12.1";
+var version = "5.12.3";
 //#endregion
 //#region src/resolveConfig.ts
 /**
@@ -599,13 +600,7 @@ const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 * line count, so `enable-plugin` restores exactly those lines and not whatever comments follow.
 */
 const DISABLED_MARKER = /^\/\/ kubb:disabled (.+)\s+(\d+)$/;
-const OPERATIONS = /* @__PURE__ */ new Set([
-	"set",
-	"remove",
-	"add-plugin",
-	"disable-plugin",
-	"enable-plugin"
-]);
+const OPERATIONS = new Set(Object.values(ConfigEditOperation));
 const KINDS = /* @__PURE__ */ new Set([
 	"plugin",
 	"adapter",
@@ -616,13 +611,14 @@ const KINDS = /* @__PURE__ */ new Set([
 * The edit crossed the wire, so its declared type is a promise the sender may not have kept.
 */
 function invalidEdit(edit) {
-	const { operation, plugin, config, path, kind } = typeof edit === "object" && edit !== null ? edit : {};
+	const { operation, plugin, config, path, kind, input } = typeof edit === "object" && edit !== null ? edit : {};
 	if (typeof operation !== "string" || !OPERATIONS.has(operation)) return `unknown operation ${JSON.stringify(operation)}`;
+	if (config !== void 0 && typeof config !== "string" && !Number.isSafeInteger(config)) return "config must name an entry or give its index";
+	if (operation === ConfigEditOperation.SET_INPUT) return typeof input === "string" && input.trim() ? void 0 : "the edit names no input";
 	if (typeof plugin !== "string" || !plugin) return "the edit names no plugin";
 	if (kind !== void 0 && (typeof kind !== "string" || !KINDS.has(kind))) return `unknown kind ${JSON.stringify(kind)}`;
-	if (kind !== void 0 && operation !== "set" && operation !== "remove") return `${operation} edits the plugins array, so it takes no kind`;
-	if (config !== void 0 && typeof config !== "string" && !Number.isSafeInteger(config)) return "config must name an entry or give its index";
-	if (operation === "set" || operation === "remove") {
+	if (kind !== void 0 && operation !== ConfigEditOperation.SET && operation !== ConfigEditOperation.REMOVE) return `${operation} edits the plugins array, so it takes no kind`;
+	if (operation === ConfigEditOperation.SET || operation === ConfigEditOperation.REMOVE) {
 		if (!Array.isArray(path) || !path.every((key) => typeof key === "string" && key)) return "path must be a list of option names";
 		if (!path.length) return "no option path given";
 		const unsafe = path.find((key) => !isSafeKey(key));
@@ -1063,6 +1059,15 @@ function applySet(source, call, path, value, quote) {
 	}
 	return { source: splice(source, rangeOf(target.value).start, rangeOf(target.value).end, printValue(value, quote)) };
 }
+/** Writes the config's top-level `input` as a string literal, replacing what it held. */
+function applySetInput(source, config, input, quote) {
+	const value = printValue(input, quote);
+	const found = findMember(config, "input");
+	if (!found) return { source: insertItem(source, config, `input: ${value}`) };
+	if (found.member.type !== "ObjectProperty") return { reason: "input is not a plain property" };
+	if (isShadowed(config, found.index)) return { reason: "a spread after input could override it" };
+	return { source: splice(source, rangeOf(found.member.value).start, rangeOf(found.member.value).end, value) };
+}
 /**
 * Deletes the option at `path`, falling the plugin back to its default for it. An option the file
 * does not set already has its default, so removing it changes nothing.
@@ -1159,7 +1164,8 @@ function applyEdit({ source, edit, quote, extensions }) {
 	const findConfig = (entries) => typeof ref === "string" ? entries.configs.find((entry) => configName(entry) === ref) : entries.configs[ref ?? 0];
 	const config = findConfig(parsed);
 	if (!config) return { reason: `no config entry found for ${JSON.stringify(ref)}` };
-	if (edit.operation === "disable-plugin") {
+	if (edit.operation === ConfigEditOperation.SET_INPUT) return applySetInput(source, config, edit.input, quote);
+	if (edit.operation === ConfigEditOperation.DISABLE_PLUGIN) {
 		const result = disablePlugin(source, parsed.mod, config, edit.plugin);
 		if (!("reason" in result) || !result.reason.includes("shares a line")) return result;
 		const expanded = expandPluginsArray(source, config);
@@ -1167,8 +1173,8 @@ function applyEdit({ source, edit, quote, extensions }) {
 		const reparsedConfig = reparsed && !("reason" in reparsed) ? findConfig(reparsed) : void 0;
 		return expanded !== void 0 && reparsed && !("reason" in reparsed) && reparsedConfig ? disablePlugin(expanded, reparsed.mod, reparsedConfig, edit.plugin) : result;
 	}
-	if (edit.operation === "enable-plugin") return enablePlugin(source, config, edit.plugin);
-	if (edit.operation === "add-plugin") return applyAddPlugin({
+	if (edit.operation === ConfigEditOperation.ENABLE_PLUGIN) return enablePlugin(source, config, edit.plugin);
+	if (edit.operation === ConfigEditOperation.ADD_PLUGIN) return applyAddPlugin({
 		source,
 		parsed,
 		config,
@@ -1184,7 +1190,7 @@ function applyEdit({ source, edit, quote, extensions }) {
 		if (kind === "adapter") return { reason: `${edit.plugin} is not the config's adapter` };
 		return { reason: kind === "plugin" && disabledBlocks(source, config).some((block) => block.packageName === edit.plugin) ? `${edit.plugin} is disabled, enable it first` : `${edit.plugin} is not in the ${kind}s array` };
 	}
-	return edit.operation === "set" ? applySet(source, call, edit.path, edit.value, quote) : applyRemove(source, call, edit.path);
+	return edit.operation === ConfigEditOperation.SET ? applySet(source, call, edit.path, edit.value, quote) : applyRemove(source, call, edit.path);
 }
 /**
 * Applies edits to a `kubb.config.ts` in place. Each edit rewrites only the text it targets, so
@@ -2013,6 +2019,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(() => {});
 }
@@ -2083,6 +2126,9 @@ var Agent = class extends RpcTarget {
 			...permissions,
 			allowWrite: false,
 			allowConfigEdit: false,
+			allowInstall: false,
+			allowUpdate: false,
+			allowSaveInput: false,
 			allowRead: true,
 			allowReadAst: true
 		} : permissions;
@@ -2108,13 +2154,13 @@ var Agent = class extends RpcTarget {
 			permission
 		});
 	}
-	async #refuse({ message, permission }) {
+	async #refuse({ message, permission, code = Diagnostics.code.unknown }) {
 		await this.#warn({
 			message,
 			permission
 		});
 		throw new Diagnostics.Error({
-			code: Diagnostics.code.unknown,
+			code,
 			severity: "error",
 			message
 		});
@@ -2234,6 +2280,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,
@@ -2304,7 +2352,13 @@ var Agent = class extends RpcTarget {
 		});
 		const activePlugins = plugins ?? config.plugins;
 		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 checkout = this.#managed && studioInput !== void 0 && getInputKind(studioInput) === "git" ? await checkoutGitInput(studioInput, signal, {
+			publicOnly: true,
+			authorization: input.gitAuth?.authorization
+		}).catch((error) => this.#refuse({
+			message: getErrorMessage(error),
+			code: Diagnostics.code.gitInputFailed
+		})) : void 0;
 		const run = () => generate({
 			config: {
 				...config,
@@ -2374,13 +2428,33 @@ 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({
+			const kept = [];
+			for (const edit of edits) kept.push(await this.#keepInput(edit));
+			const written = await writeConfigEdits({
 				filePath: configFile,
-				edits,
+				edits: kept.flatMap((edit) => "reason" in edit ? [] : [edit]),
 				extensions: await this.#installedExtensions()
 			});
+			let next = 0;
+			const outcomes = kept.map((edit, index) => "reason" in edit ? {
+				edit: edits[index],
+				applied: false,
+				reason: edit.reason
+			} : {
+				...written.outcomes[next++],
+				edit: edits[index]
+			});
+			let wroteDocument = false;
+			for (const [index, edit] of kept.entries()) {
+				if (!("document" in edit) || !edit.document || !outcomes[index].applied) continue;
+				await writeFile(path.join(this.#options.root, edit.document.fileName), edit.document.text, "utf-8");
+				wroteDocument = true;
+			}
+			const changed = written.changed || wroteDocument;
 			const applied = outcomes.filter((outcome) => outcome.applied).length;
 			await this.#logCommand("saveConfig", `applied ${applied}/${outcomes.length} edits to ${configPath}`, input.requestedBy);
 			return {
@@ -2390,6 +2464,137 @@ 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;
+		}
+	}
+	/**
+	* Readies a `set-input` edit for the config file: a document is pointed at `openapi.yaml` (`openapi.json`
+	* for JSON) in the project, one file per config entry, for `saveConfig` to write once the edit applies.
+	* A managed agent refuses a file path, as in a generation.
+	*/
+	async #keepInput(edit) {
+		if (edit?.operation !== ConfigEditOperation.SET_INPUT || typeof edit.input !== "string" || !edit.input.trim()) return edit;
+		if (!this.#permissions.allowSaveInput) {
+			await this.#warn({
+				message: "Ignored the spec to save: saving the input was not granted",
+				permission: AgentPermission.SAVE_INPUT
+			});
+			return { reason: "the agent was not granted permission to save the input" };
+		}
+		const kind = getInputKind(edit.input);
+		if (this.#managed && !MANAGED_INPUT_KINDS.has(kind)) return { reason: AgentMessage.MANAGED_INPUT_KIND };
+		if (kind !== "inline") return edit;
+		const fileName = `openapi${edit.config === void 0 || edit.config === 0 ? "" : `-${String(edit.config).replace(/[^\w.-]/g, "-")}`}.${isJson(edit.input) ? "json" : "yaml"}`;
+		return {
+			...edit,
+			input: `./${fileName}`,
+			document: {
+				fileName,
+				text: edit.input
+			}
+		};
+	}
+	/**
+	* 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();
 		}
 	}
 	/**
@@ -2574,6 +2779,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,
@@ -2589,6 +2796,15 @@ function pickConfig(configs, ref) {
 	if (ref !== void 0 && !Number.isSafeInteger(ref)) return void 0;
 	return configs[ref ?? 0];
 }
+/** Whether `text` parses as JSON, so a pasted document is saved under the matching extension. */
+function isJson(text) {
+	try {
+		JSON.parse(text);
+		return true;
+	} catch {
+		return false;
+	}
+}
 /** The input path or URL Studio may show: no inline document, and no credentials from a URL. */
 function reportedInput(input) {
 	if (typeof input !== "string") return void 0;
@@ -2642,6 +2858,9 @@ async function runAgent({ options, openRpc }) {
 		permissions: {
 			allowWrite: false,
 			allowConfigEdit: false,
+			allowInstall: false,
+			allowUpdate: false,
+			allowSaveInput: false,
 			allowExec: false,
 			allowRead: false,
 			allowReadAst: false,