@kubb/studio 5.8.0 → 5.8.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
-import { F as SnapshotUploadMetadata, a as AgentConnectInfo, k as PublishedSnapshot, o as AgentPermissions } from "./protocol-i7JV0P4z.js";
+import { B as SnapshotUploadMetadata, M as PublishedSnapshot, a as AgentConnectInfo, c as ConfigEdit, l as ConfigEditOutcome, m as ExtensionEntry, o as AgentPermissions } from "./protocol-BBGIgdIf.js";
 import { Config, Hookable, KubbHooks } from "@kubb/core";
 //#region src/connect.d.ts
 /**
@@ -242,5 +242,27 @@ export declare function createSnapshot({ studioUrl, apiKey, config, hooks, signa
  */
 export declare const defaultStudioUrl = "https://kubb.studio";
 //#endregion
-export type { ConnectAgentOptions, StudioConnectedContext };
+//#region src/extensions.d.ts
+/**
+ * The extension packages installed in a project, keyed by package name. Only these, besides
+ * `@kubb/plugin-*` packages, may be imported on behalf of Studio.
+ */
+type InstalledExtensions = ReadonlyMap<string, ExtensionEntry>;
+//#endregion
+//#region src/configFile.d.ts
+/**
+ * Applies `edits` to the config file at `filePath`, writing it only when something changed.
+ * `add-plugin` accepts `@kubb/plugin-*` packages and the plugins in `extensions`.
+ */
+export declare function writeConfigEdits({ filePath, edits, extensions }: {
+  filePath: string;
+  edits: Array<ConfigEdit>;
+  extensions?: InstalledExtensions;
+}): Promise<{
+  source: string;
+  outcomes: Array<ConfigEditOutcome>;
+  changed: boolean;
+}>;
+//#endregion
+export type { ConnectAgentOptions, InstalledExtensions, StudioConnectedContext };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -9,7 +9,7 @@ import process$1 from "node:process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { pathToFileURL } from "node:url";
 import { existsSync } from "node:fs";
-import { Diagnostics, Hookable, cacheStorage, createKubb, fsStorage, getInputKind, memoryStorage, resolveCacheDir, resolveMeta } from "@kubb/core";
+import { Diagnostics, Hookable, cacheStorage, createKubb, fsStorage, getInputKind, isPackageName, memoryStorage, readInstalledPackages, resolveCacheDir, resolveMeta } from "@kubb/core";
 import { RpcTarget, newWebSocketRpcSession } from "capnweb";
 import { detectCodeFormat, parseExpression, parseModule } from "magicast";
 import { promisify, stripVTControlCharacters } from "node:util";
@@ -192,7 +192,7 @@ function getElapsedMs(hrStart) {
 }
 //#endregion
 //#region package.json
-var version = "5.8.0";
+var version = "5.8.1";
 //#endregion
 //#region src/resolveConfig.ts
 /**
@@ -262,7 +262,7 @@ function isInstalled({ packageName, root }) {
 /**
 * The name Studio knows a plugin by: its `@kubb/plugin-*` package when one is installed, otherwise
 * the plugin's own `name`, so a plugin defined in the user's project is never reported as a Kubb
-* package that does not exist.
+* package that does not exist. An installed extension whose manifest `name` matches wins.
 *
 * @example
 * ```ts
@@ -270,7 +270,9 @@ function isInstalled({ packageName, root }) {
 * toStudioName({ name: 'plugin-zod-operations', root })  // 'plugin-zod-operations', a local plugin
 * ```
 */
-function toStudioName({ name, root }) {
+function toStudioName({ name, root, extensions = /* @__PURE__ */ new Map() }) {
+	const installed = [...extensions.values()].find(({ manifest }) => manifest.kind === "plugin" && manifest.name === name);
+	if (installed) return installed.package;
 	const packageName = toPackageName(name);
 	return packageName !== name && isInstalled({
 		packageName,
@@ -289,59 +291,69 @@ function toStudioName({ name, root }) {
 function toExportName(packageName) {
 	return camelCase(toPluginName(packageName));
 }
-/**
-* A `@kubb/plugin-*` package specifier. Nothing else may reach `import()`: only Kubb's own
-* plugins are supported, so a payload naming anything else, a third-party package or a path, is
-* refused before it can execute.
-*/
 const KUBB_PLUGIN_SPECIFIER = /^@kubb\/plugin-[\w.-]+$/;
 /**
-* Whether `name` is a `@kubb/plugin-*` specifier. Exported so `configFile.ts` can refuse the same
-* shape before printing a Studio-supplied plugin name into the config file's source text.
+* Whether Studio may import `packageName` as a plugin: a `@kubb/plugin-*` package, or an installed
+* package whose `kubb-extension.json` has `kind: "plugin"`. A path, URL or arbitrary package is
+* refused before it can execute. `configFile.ts` applies the same rule before printing a plugin name.
 */
-function isKubbPluginSpecifier(name) {
-	return KUBB_PLUGIN_SPECIFIER.test(name);
+function isAllowedPlugin({ packageName, extensions }) {
+	if (!isPackageName(packageName)) return false;
+	return KUBB_PLUGIN_SPECIFIER.test(packageName) || extensions.get(packageName)?.manifest.kind === "plugin";
 }
 /**
-* Dynamically imports a `@kubb/plugin-*` package and returns its factory function.
+* Dynamically imports a plugin package and returns its factory. Only packages
+* {@link isAllowedPlugin} accepts reach `import()`.
 *
 * Packages must be pre-installed in the Docker image at build time via the `KUBB_PACKAGES`
 * build ARG, no runtime installation is possible in the distroless container.
 *
-* Resolution order: the camelCase named export the package name implies (e.g. `pluginTs`), then
-* the default export.
+* Resolution order: the manifest's `export`, else the camelCase named export the package name
+* implies (e.g. `pluginTs`), then the default export.
 *
-* @throws if the package cannot be imported or exports no callable factory.
+* @throws if the package is not allowed, cannot be imported, or exports no callable factory.
 */
-async function loadPluginFactory(packageName) {
-	if (!isKubbPluginSpecifier(packageName)) throw new Error(`Plugin "${packageName}" is not a @kubb/plugin-* package. Kubb Studio only supports Kubb's own plugins.`);
+async function loadPluginFactory({ packageName, extensions }) {
+	if (!isAllowedPlugin({
+		packageName,
+		extensions
+	})) throw new Error(`Plugin "${packageName}" is not an installed Kubb plugin. Studio loads @kubb/plugin-* packages and installed packages that ship a kubb-extension.json with kind "plugin".`);
 	let mod;
 	try {
 		mod = await importFromProject(packageName);
 	} catch (cause) {
 		throw new Error(`Plugin "${packageName}" could not be loaded. Make sure it is installed: \`npm install ${packageName}\``, { cause });
 	}
+	const manifestExport = extensions.get(packageName)?.manifest.export;
+	if (manifestExport) {
+		if (typeof mod[manifestExport] === "function") return mod[manifestExport];
+		throw new Error(`Plugin "${packageName}" does not export "${manifestExport}", the factory its kubb-extension.json names.`);
+	}
 	const exportName = toExportName(packageName);
 	if (typeof mod[exportName] === "function") return mod[exportName];
 	if (typeof mod["default"] === "function") return mod["default"];
 	throw new Error(`Plugin "${packageName}" does not export a callable factory. Tried the named export "${exportName}" and "default".`);
 }
 /**
-* Resolves each plugin entry by dynamically importing the `@kubb/plugin-*` package and
-* calling its factory with the provided options.
-*
-* Packages must be pre-installed in the Docker image at build time, use the `KUBB_PACKAGES`
-* build ARG to control which ones are available at runtime.
+* Resolves each plugin entry by dynamically importing its package and calling its factory with the
+* provided options. See {@link loadPluginFactory} for which packages are allowed.
 *
 * @example
 * ```ts
-* { name: '@kubb/plugin-react-query', options: { output: { path: './hooks' } } }
-* { name: '@kubb/plugin-ts', options: { output: { path: './types' } } }
+* const plugins = await resolvePlugins({
+*   plugins: [
+*     { name: '@kubb/plugin-react-query', options: { output: { path: './hooks' } } },
+*     { name: '@kubb/plugin-ts', options: { output: { path: './types' } } },
+*   ],
+* })
 * ```
 */
-async function resolvePlugins(plugins) {
+async function resolvePlugins({ plugins, extensions = /* @__PURE__ */ new Map() }) {
 	return Promise.all(plugins.map(async ({ name, options }) => {
-		return (await loadPluginFactory(name))(options ?? {});
+		return (await loadPluginFactory({
+			packageName: name,
+			extensions
+		}))(options ?? {});
 	}));
 }
 /** The installed version of each plugin's package, plus the names that could not be resolved. */
@@ -459,14 +471,18 @@ function mergeOptions(disk, studio) {
 * For plugins present in both configs, the plugin is re-instantiated with merged options
 * so that all internal closures correctly reference the merged values.
 */
-async function mergePlugins(diskPlugins, studioPlugins) {
-	const disabledNames = new Set((studioPlugins ?? []).filter((entry) => entry.disabled).map((entry) => toPluginName(entry.name)));
+async function mergePlugins({ diskPlugins, studioPlugins, extensions = /* @__PURE__ */ new Map() }) {
+	const pluginNameOf = (packageName) => extensions.get(packageName)?.manifest.name ?? toPluginName(packageName);
+	const disabledNames = new Set((studioPlugins ?? []).filter((entry) => entry.disabled).map((entry) => pluginNameOf(entry.name)));
 	const activeDiskPlugins = disabledNames.size ? diskPlugins?.filter((plugin) => !disabledNames.has(resolveMeta(plugin).name)) : diskPlugins;
 	const activeStudioPlugins = studioPlugins?.filter((entry) => !entry.disabled);
 	if (!activeDiskPlugins && !activeStudioPlugins?.length) return void 0;
 	if (!activeStudioPlugins?.length) return activeDiskPlugins;
-	if (!activeDiskPlugins) return resolvePlugins(activeStudioPlugins);
-	const studioEntryByName = new Map(activeStudioPlugins.map((entry) => [toPluginName(entry.name), entry]));
+	if (!activeDiskPlugins) return resolvePlugins({
+		plugins: activeStudioPlugins,
+		extensions
+	});
+	const studioEntryByName = new Map(activeStudioPlugins.map((entry) => [pluginNameOf(entry.name), entry]));
 	const diskNames = new Set(activeDiskPlugins.map((plugin) => plugin.name));
 	const merged = await Promise.all(activeDiskPlugins.map(async (diskPlugin) => {
 		const studioEntry = studioEntryByName.get(resolveMeta(diskPlugin).name);
@@ -474,17 +490,23 @@ async function mergePlugins(diskPlugins, studioPlugins) {
 		const diskOptions = diskPlugin.options ?? {};
 		const options = mergeOptions(diskOptions, studioEntry.options ?? {});
 		const unchanged = JSON.stringify(toJSONOptions(options)) === JSON.stringify(toJSONOptions(diskOptions));
-		const [resolved] = await resolvePlugins([{
-			name: studioEntry.name,
-			options
-		}]).catch((cause) => {
+		const [resolved] = await resolvePlugins({
+			plugins: [{
+				name: studioEntry.name,
+				options
+			}],
+			extensions
+		}).catch((cause) => {
 			if (unchanged) return [diskPlugin];
-			throw new Error(`Plugin "${diskPlugin.name}" is not an installed @kubb/plugin-* package, so Studio cannot change its options. Edit it in the config file, or only enable or disable it from Studio.`, { cause });
+			throw new Error(`Plugin "${diskPlugin.name}" is not an installed @kubb/plugin-* package or Kubb extension, so Studio cannot change its options. Edit it in the config file, or only enable or disable it from Studio.`, { cause });
 		});
 		return resolved ?? diskPlugin;
 	}));
-	const studioOnly = activeStudioPlugins.filter((entry) => !diskNames.has(toPluginName(entry.name)));
-	return [...merged, ...await resolvePlugins(studioOnly)];
+	const studioOnly = activeStudioPlugins.filter((entry) => !diskNames.has(pluginNameOf(entry.name)));
+	return [...merged, ...await resolvePlugins({
+		plugins: studioOnly,
+		extensions
+	})];
 }
 /**
 * Merges Studio-provided adapter option overrides into the disk config's adapter.
@@ -851,6 +873,14 @@ function readConfig(source) {
 		})
 	};
 }
+/** The modules the config file imports, in source order. Empty when the file cannot be parsed. */
+function readImports(source) {
+	try {
+		return [...new Set(importedFrom(parseModule(source)).values())];
+	} catch {
+		return [];
+	}
+}
 /**
 * Walks `path` through a plugin's options to the literal at its last key. Returns `missing` with
 * the index of the first key that is not there yet, so `set` can write the rest of the path as one
@@ -924,9 +954,12 @@ function insertImport(source, { mod, kind }, importName, moduleSpecifier) {
 * Adds a `pluginX(...)` call to a config's plugins array, and its import. Replaying the same add is
 * a no-op, while an import name collision with an unrelated package remains an error.
 */
-function applyAddPlugin(source, parsed, config, edit, quote) {
-	if (!isKubbPluginSpecifier(edit.plugin)) return { reason: `"${edit.plugin}" is not a @kubb/plugin-* package` };
-	const importName = edit.importName ?? toExportName(edit.plugin);
+function applyAddPlugin({ source, parsed, config, edit, quote, extensions }) {
+	if (!isAllowedPlugin({
+		packageName: edit.plugin,
+		extensions
+	})) return { reason: `"${edit.plugin}" is not a @kubb/plugin-* package or an installed Kubb plugin` };
+	const importName = extensions.get(edit.plugin)?.manifest.export ?? edit.importName ?? toExportName(edit.plugin);
 	if (!IDENTIFIER.test(importName)) return { reason: `"${importName}" is not a valid import name` };
 	if (pluginCalls(parsed.mod, config).some((plugin) => plugin.packageName === edit.plugin)) return { source };
 	const taken = importedFrom(parsed.mod).get(importName);
@@ -961,7 +994,7 @@ function enablePlugin(source, config, plugin) {
 	return { source: lines.join("\n") };
 }
 /** Applies one edit to `source`. Every edit re-parses the file, since the previous one rewrote it. */
-function applyEdit(source, edit, quote) {
+function applyEdit({ source, edit, quote, extensions }) {
 	const parsed = parseConfigs(source);
 	if ("reason" in parsed) return parsed;
 	const ref = edit.config;
@@ -969,7 +1002,14 @@ function applyEdit(source, edit, quote) {
 	if (!config) return { reason: `no config entry found for ${JSON.stringify(ref)}` };
 	if (edit.operation === "disable-plugin") return disablePlugin(source, parsed.mod, config, edit.plugin);
 	if (edit.operation === "enable-plugin") return enablePlugin(source, config, edit.plugin);
-	if (edit.operation === "add-plugin") return applyAddPlugin(source, parsed, config, edit, quote);
+	if (edit.operation === "add-plugin") return applyAddPlugin({
+		source,
+		parsed,
+		config,
+		edit,
+		quote,
+		extensions
+	});
 	const call = pluginCalls(parsed.mod, config).find((plugin) => plugin.packageName === edit.plugin)?.call;
 	if (!call) return { reason: disabledBlocks(source, config).some((block) => block.packageName === edit.plugin) ? `${edit.plugin} is disabled, enable it first` : `${edit.plugin} is not in the plugins array` };
 	return edit.operation === "set" ? applySet(source, call, edit.path, edit.value, quote) : applyRemove(source, call, edit.path);
@@ -982,12 +1022,13 @@ function applyEdit(source, edit, quote) {
 *
 * @example
 * ```ts
-* const { source, outcomes } = applyConfigEdits(current, [
-*   { operation: 'set', plugin: '@kubb/plugin-ts', path: ['enum', 'type'], value: 'enum' },
-* ])
+* const { source, outcomes } = applyConfigEdits({
+*   source: current,
+*   edits: [{ operation: 'set', plugin: '@kubb/plugin-ts', path: ['enum', 'type'], value: 'enum' }],
+* })
 * ```
 */
-function applyConfigEdits(source, edits) {
+function applyConfigEdits({ source, edits, extensions = /* @__PURE__ */ new Map() }) {
 	let current = source;
 	const quote = detectCodeFormat(source).quote === "double" ? `"` : `'`;
 	const outcomes = edits.map((edit) => {
@@ -998,7 +1039,12 @@ function applyConfigEdits(source, edits) {
 			reason: invalid
 		};
 		try {
-			const result = applyEdit(current, edit, quote);
+			const result = applyEdit({
+				source: current,
+				edit,
+				quote,
+				extensions
+			});
 			if ("reason" in result) return {
 				edit,
 				applied: false,
@@ -1023,13 +1069,46 @@ function applyConfigEdits(source, edits) {
 		changed: current !== source
 	};
 }
-/** Applies `edits` to the config file at `filePath`, writing it only when something changed. */
-async function writeConfigEdits({ filePath, edits }) {
-	const result = applyConfigEdits(await read(filePath), edits);
+/**
+* Applies `edits` to the config file at `filePath`, writing it only when something changed.
+* `add-plugin` accepts `@kubb/plugin-*` packages and the plugins in `extensions`.
+*/
+async function writeConfigEdits({ filePath, edits, extensions }) {
+	const result = applyConfigEdits({
+		source: await read(filePath),
+		edits,
+		extensions
+	});
 	if (result.changed) await writeFile(filePath, result.source, "utf-8");
 	return result;
 }
 //#endregion
+//#region src/extensions.ts
+/** Extensions `kubb` ships with, so they count as installed without being a direct dependency. */
+const BUILT_IN_PACKAGES = [
+	"@kubb/adapter-oas",
+	"@kubb/parser-ts",
+	"@kubb/parser-md",
+	"@kubb/plugin-barrel"
+];
+/**
+* Finds the extensions installed in the project at `root`: its `dependencies` and `devDependencies`,
+* the `packages` its config file imports, and the extensions `kubb` ships with. Keeps each package
+* that resolves and ships a valid `kubb-extension.json`. Never throws.
+*/
+async function discoverExtensions({ root, packages = [] }) {
+	const installed = await readInstalledPackages({
+		root,
+		packages: [...packages, ...BUILT_IN_PACKAGES],
+		resolveFrom: ["kubb"]
+	});
+	return new Map(installed.flatMap(({ package: name, version, manifest }) => version !== void 0 && manifest ? [[name, {
+		package: name,
+		version,
+		manifest
+	}]] : []));
+}
+//#endregion
 //#region src/generations.ts
 const READ_CONCURRENCY = 50;
 const MB = 1048576;
@@ -1544,10 +1623,21 @@ var Agent = class extends RpcTarget {
 			return;
 		}
 	}
+	async #installedExtensions() {
+		const source = await read(this.#options.configFile).catch(() => "");
+		return discoverExtensions({
+			root: this.#options.root,
+			packages: readImports(source)
+		});
+	}
 	async connect(info) {
 		this.#session.info = info;
 		const { configPath, root, version: version$1, loadConfig } = this.#options;
-		const [config, file] = await Promise.all([loadConfig(), this.#readConfigFileView()]);
+		const [config, file, extensions] = await Promise.all([
+			loadConfig(),
+			this.#readConfigFileView(),
+			this.#installedExtensions()
+		]);
 		this.#session.connected.resolve(info);
 		return {
 			versions: {
@@ -1561,10 +1651,12 @@ var Agent = class extends RpcTarget {
 				plugins: config.plugins.map((plugin) => ({
 					name: toStudioName({
 						name: resolveMeta(plugin).name,
-						root
+						root,
+						extensions
 					}),
 					options: toJSONOptions(plugin.options)
-				}))
+				})),
+				extensions: [...extensions.values()]
 			},
 			permissions: this.#permissions
 		};
@@ -1622,8 +1714,12 @@ var Agent = class extends RpcTarget {
 		const { jobId, config: patch } = input;
 		const studioInput = this.#sandbox ? patch?.input : void 0;
 		if (this.#sandbox && (typeof studioInput !== "string" || !studioInput.trim() || getInputKind(studioInput) !== "inline")) return this.#refuse({ message: "A sandbox agent generates only from the OpenAPI document content Studio sends, not from a file path or URL" });
-		const config = await this.#options.loadConfig();
-		const [plugins, adapter] = await Promise.all([mergePlugins(config.plugins, patch?.plugins), mergeAdapter(config.adapter, patch?.adapter)]).catch(async (error) => {
+		const [config, extensions] = await Promise.all([this.#options.loadConfig(), this.#installedExtensions()]);
+		const [plugins, adapter] = await Promise.all([mergePlugins({
+			diskPlugins: config.plugins,
+			studioPlugins: patch?.plugins,
+			extensions
+		}), mergeAdapter(config.adapter, patch?.adapter)]).catch(async (error) => {
 			await emit(this.#options.hooks, "kubb:error", { error: toError(error) });
 			throw error;
 		});
@@ -1711,7 +1807,8 @@ var Agent = class extends RpcTarget {
 		try {
 			const { source, outcomes, changed } = await writeConfigEdits({
 				filePath: configFile,
-				edits
+				edits,
+				extensions: await this.#installedExtensions()
 			});
 			const applied = outcomes.filter((outcome) => outcome.applied).length;
 			return {
@@ -2236,6 +2333,6 @@ async function createSnapshot({ studioUrl = defaultStudioUrl, apiKey, config, ho
 	return _data.snapshot;
 }
 //#endregion
-export { IncompatibleAgentError, InvalidAgentTokenError, PairingCanceledError, PairingDeniedError, PairingExpiredError, connectAgent, createSnapshot, defaultStudioUrl, pairAgent };
+export { IncompatibleAgentError, InvalidAgentTokenError, PairingCanceledError, PairingDeniedError, PairingExpiredError, connectAgent, createSnapshot, defaultStudioUrl, pairAgent, writeConfigEdits };
 
 //# sourceMappingURL=index.js.map