@kubb/studio 5.9.3 → 5.9.5

package/README.md

@@ -74,7 +74,7 @@ running in a developer's project and a container running a fixed plugin set.
 | `connect.ts`     | `connectAgent`: the socket loop and the `Agent` that serves Studio's calls.      |
 | `pair.ts`        | `pairAgent`: RFC 8628 device pairing.                                            |
 | `snapshot.ts`    | `createSnapshot` for CI, and packing a generation into an npm tarball.           |
-| `generations.ts` | Running a generation and keeping its files for `readFiles`.                      |
+| `generations.ts` | Running a generation and keeping its files and AST for `readFiles`/`readInput`.  |
 | `configFile.ts`  | Reading and patching plugin options in `kubb.config.ts`.                         |
 
 ## Connection
@@ -107,7 +107,7 @@ Every permission is off by default, and each covers one trust boundary:
 | `allowWrite`      | Generated files are written to disk. Off means they exist only in memory and stream to Studio. |
 | `allowExec`       | The formatter, the linter, and `output.postGenerate` run as child processes.                   |
 | `allowConfigEdit` | Studio may change plugin options in `kubb.config.ts`.                                          |
-| `allowRead`       | Studio may read back the files a generation produced.                                          |
+| `allowRead`       | Studio may read back the files a generation produced and its parsed spec.                      |
 
 A sandbox never writes or edits config, and always allows reads.
 

package/dist/index.cjs

@@ -37,6 +37,7 @@ let capnweb = require("capnweb");
 let magicast = require("magicast");
 let node_module = require("node:module");
 let node_util = require("node:util");
+let _kubb_ast = require("@kubb/ast");
 let ofetch = require("ofetch");
 let node_zlib = require("node:zlib");
 //#region ../../internals/utils/src/casing.ts
@@ -176,10 +177,18 @@ function getElapsedMs(hrStart) {
 }
 //#endregion
 //#region package.json
-var version = "5.9.3";
+var version = "5.9.5";
 //#endregion
 //#region src/resolveConfig.ts
 /**
+* Turns the JSON config Studio sends back into live Kubb objects.
+*
+* A plugin or adapter instance carries closures (`parse`, `getImports`, ...) that cannot survive
+* JSON, so both sides pass options over the wire and the factory is re-invoked here with the merged
+* result. Only packages {@link isAllowedPlugin} accepts are resolved this way, never an arbitrary
+* module the payload names.
+*/
+/**
 * Imports a package, falling back to how the user's project would resolve it.
 *
 * `import()` resolves from this file, so a linked or globally installed Studio (`pnpm link`,
@@ -258,8 +267,9 @@ function isAllowedPlugin({ packageName, extensions }) {
 	return KUBB_PLUGIN_SPECIFIER.test(packageName) || extensions.get(packageName)?.manifest.kind === "plugin";
 }
 /**
-* Dynamically imports a plugin package and returns its factory. Only packages
-* {@link isAllowedPlugin} accepts reach `import()`.
+* Dynamically imports an extension package and returns its factory. Callers check
+* {@link isAllowedPlugin} or derive the package from a disk instance first, so an arbitrary module
+* never reaches `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.
@@ -267,13 +277,9 @@ function isAllowedPlugin({ packageName, extensions }) {
 * 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 is not allowed, cannot be imported, or exports no callable factory.
+* @throws if the package cannot be imported or exports no callable factory.
 */
-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".`);
+async function loadFactory({ packageName, extensions }) {
 	let mod;
 	try {
 		mod = await importFromProject(packageName);
@@ -292,7 +298,7 @@ async function loadPluginFactory({ packageName, extensions }) {
 }
 /**
 * 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.
+* provided options. Only packages {@link isAllowedPlugin} accepts are loaded.
 *
 * @example
 * ```ts
@@ -306,7 +312,11 @@ async function loadPluginFactory({ packageName, extensions }) {
 */
 async function resolvePlugins({ plugins, extensions = /* @__PURE__ */ new Map() }) {
 	return Promise.all(plugins.map(async ({ name, options }) => {
-		return (await loadPluginFactory({
+		if (!isAllowedPlugin({
+			packageName: name,
+			extensions
+		})) throw new Error(`Plugin "${name}" is not an installed Kubb plugin. Studio loads @kubb/plugin-* packages and installed packages that ship a kubb-extension.json with kind "plugin".`);
+		return (await loadFactory({
 			packageName: name,
 			extensions
 		}))(options ?? {});
@@ -454,13 +464,12 @@ async function mergePlugins({ diskPlugins, studioPlugins, extensions = /* @__PUR
 async function rebuildExtension({ disk, studioOptions, kind, extensions }) {
 	if (!studioOptions || !Object.keys(studioOptions).length) return disk;
 	const { name } = (0, _kubb_core.resolveMeta)(disk);
-	const installed = [...extensions.values()].find(({ manifest }) => manifest.kind === kind && manifest.name === name);
-	const packageName = installed?.package ?? `@kubb/${kind}-${name}`;
-	const factory = await importFromProject(packageName).then((mod) => mod[installed?.manifest.export ?? toExportName(packageName)]).catch((cause) => {
+	return (await loadFactory({
+		packageName: [...extensions.values()].find(({ manifest }) => manifest.kind === kind && manifest.name === name)?.package ?? `@kubb/${kind}-${name}`,
+		extensions
+	}).catch((cause) => {
 		throw new Error(`The ${kind} "${name}" is not an installed Kubb extension, so Studio cannot change its options. Edit it in the config file.`, { cause });
-	});
-	if (typeof factory !== "function") throw new Error(`The ${kind} "${name}" is not an installed Kubb extension, so Studio cannot change its options. Edit it in the config file.`);
-	return factory(mergeOptions(disk.options ?? {}, studioOptions));
+	}))(mergeOptions(disk.options ?? {}, studioOptions));
 }
 /**
 * Merges Studio-provided adapter option overrides into the disk config's adapter, see {@link rebuildExtension}.
@@ -1099,7 +1108,10 @@ function relativeStoragePath({ root, filePath }) {
 * The content fingerprint Studio compares snapshots by. Agent runs and CI uploads must agree on it.
 */
 const hashOf = (content) => (0, node_crypto.createHash)("sha1").update(content).digest("hex").slice(0, 16);
-const totalBytes = (entries) => entries.reduce((sum, { output, disk }) => sum + output.bytes + (disk?.bytes ?? 0), 0);
+/**
+* The bytes `entries` keep on disk: output, written files, and kept input.
+*/
+const totalBytes = (entries) => entries.reduce((sum, { output, disk, inputBytes }) => sum + output.bytes + (disk?.bytes ?? 0) + (inputBytes ?? 0), 0);
 function positiveNumber(value) {
 	const parsed = Number(value);
 	return value && Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
@@ -1142,7 +1154,11 @@ async function generate({ config, hooks, signal, allowExec }) {
 		hooks,
 		signal
 	});
-	const result = await kubb.generate();
+	let input = null;
+	const unhook = kubb.hooks.hook("kubb:build:end", (ctx) => {
+		if (ctx.config === kubb.config) input = kubb.driver.inputNode;
+	});
+	const result = await kubb.generate().finally(unhook);
 	if (!result.success) throw generationFailure(result.diagnostics);
 	const { storage, root } = kubb.config;
 	return {
@@ -1151,7 +1167,8 @@ async function generate({ config, hooks, signal, allowExec }) {
 		paths: new Set(result.files.map((file) => relativeStoragePath({
 			root,
 			filePath: file.path
-		})))
+		}))),
+		input
 	};
 }
 /**
@@ -1232,6 +1249,33 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 	return {
 		keep,
 		drop,
+		/**
+		* Keeps the `InputNode` of `jobId` and returns its size in bytes, or 0 when it keeps none. A ref schema loses
+		* the copy of its target, which `input.schemas` holds: with it, a large spec outgrows what `JSON.stringify` can return.
+		*/
+		async keepInput({ jobId, input, maxSetMb }) {
+			if (!input) return 0;
+			let json;
+			try {
+				json = JSON.stringify(_kubb_ast.ast.transform(input, { schema: (node) => node.type === "ref" && node.schema ? {
+					...node,
+					schema: void 0
+				} : void 0 }));
+			} catch {
+				return 0;
+			}
+			const bytes = Buffer.byteLength(json);
+			if (bytes > maxSetMb * MB) return 0;
+			await storage.writeItem(`${dirOf(jobId)}input.json`, json);
+			return bytes;
+		},
+		/**
+		* The input `keepInput` kept for `jobId`, or `undefined` when there is none.
+		*/
+		async readInput(jobId) {
+			const stored = await storage.readItem(`${dirOf(jobId)}input.json`);
+			return stored === null ? void 0 : JSON.parse(stored);
+		},
 		get: async (jobId) => (await load()).find((generation) => generation.jobId === jobId && isLive(generation)),
 		async add(generation) {
 			const current = await load();
@@ -1455,7 +1499,6 @@ function createGenerationStream(hooks, jobId) {
 	return {
 		stream,
 		close,
-		dispose: () => fail(),
 		fail
 	};
 }
@@ -1588,29 +1631,29 @@ var Agent = class extends capnweb.RpcTarget {
 		});
 		throw new Error(message);
 	}
-	async #command({ command, run }) {
+	#assertConnected() {
 		if (!this.#session.info) throw new Error("Studio must call connect() before any other command");
-		const { value, info } = await run();
-		if (info !== void 0) await emit(this.#options.hooks, "studio:command", {
+	}
+	#logCommand(command, info) {
+		return emit(this.#options.hooks, "studio:command", {
 			command,
 			info
 		});
-		return value;
 	}
-	async #readConfigFileView() {
+	async #readConfigFileView(source) {
 		if (!this.#permissions.allowConfigEdit) return void 0;
 		try {
-			return readConfig(await read(this.#options.configFile));
+			return readConfig(await source);
 		} catch (error) {
 			await this.#warn({ message: `Could not read ${this.#options.configFile}: ${getErrorMessage(error)}` });
 			return;
 		}
 	}
-	async #installedExtensions() {
-		const source = await read(this.#options.configFile).catch(() => "");
+	async #installedExtensions(source = read(this.#options.configFile)) {
+		const imports = await source.then(readImports, () => []);
 		const installed = await (0, _kubb_core.readInstalledPackages)({
 			root: this.#options.root,
-			packages: [...readImports(source), ...BUILT_IN_PACKAGES],
+			packages: [...imports, ...BUILT_IN_PACKAGES],
 			resolveFrom: ["kubb"]
 		});
 		return new Map(installed.flatMap(({ package: name, version, manifest }) => version !== void 0 && manifest ? [[name, {
@@ -1621,11 +1664,12 @@ var Agent = class extends capnweb.RpcTarget {
 	}
 	async connect(info) {
 		this.#session.info = info;
-		const { configPath, root, version: version$1, loadConfig } = this.#options;
+		const { configPath, root, version: version$1, loadConfig, configFile } = this.#options;
+		const source = read(configFile);
 		const [config, file, extensions] = await Promise.all([
 			loadConfig(),
-			this.#readConfigFileView(),
-			this.#installedExtensions()
+			this.#readConfigFileView(source),
+			this.#installedExtensions(source)
 		]);
 		this.#session.connected.resolve(info);
 		return {
@@ -1678,11 +1722,13 @@ var Agent = class extends capnweb.RpcTarget {
 			result,
 			stop: () => {
 				controller.abort(/* @__PURE__ */ new Error("Generation canceled"));
-				stream.dispose();
+				stream.fail();
 			}
 		});
 	}
+	/** Runs one job and keeps its output, and its input with `allowRead`, for later reads. */
 	async #runGeneration(input, controller) {
+		this.#assertConnected();
 		if (this.#session.closed) throw new Error("Connection is closed");
 		if (this.#session.active) return this.#refuse({ message: "A generation is already in progress, please wait for it to finish" });
 		const settled = Promise.withResolvers();
@@ -1694,13 +1740,10 @@ var Agent = class extends capnweb.RpcTarget {
 		let root = this.#options.root;
 		try {
 			if (this.#sandbox) root = await (0, node_fs_promises.mkdtemp)(node_path.default.join((0, node_os.tmpdir)(), "kubb-job-"));
-			return await this.#command({
-				command: "generate",
-				run: () => this.#generate({
-					input,
-					root,
-					signal: controller.signal
-				})
+			return await this.#generate({
+				input,
+				root,
+				signal: controller.signal
 			});
 		} finally {
 			if (root !== this.#options.root) await Promise.all([(0, node_fs_promises.rm)(root, {
@@ -1771,37 +1814,36 @@ var Agent = class extends capnweb.RpcTarget {
 			files,
 			maxSetMb: this.#limits.maxMb
 		});
+		const inputBytes = await this.#generations.keepInput({
+			jobId,
+			input: this.#permissions.allowRead ? files.input : null,
+			maxSetMb: this.#limits.maxMb
+		});
 		if (!output.paths.length && Object.keys(output.hashes).length) await this.#warn({ message: "Kept only the hashes of this generation: its output is too large to keep" });
 		await this.#generations.add({
 			jobId,
 			output,
-			disk
+			disk,
+			inputBytes
 		});
+		await this.#logCommand("generate", `${activePlugins.length} plugin${activePlugins.length === 1 ? "" : "s"}, ${this.#permissions.allowWrite ? "written to disk" : "in memory"}${studioInput !== void 0 ? ", from a Studio spec" : ""}`);
 		return {
-			value: {
-				status: "success",
-				files: [...files.paths],
-				fileCount: files.paths.size,
-				hashes: output.hashes,
-				disk: disk ? { hashes: disk.hashes } : void 0
-			},
-			info: `${activePlugins.length} plugin${activePlugins.length === 1 ? "" : "s"}, ${this.#permissions.allowWrite ? "written to disk" : "in memory"}${studioInput !== void 0 ? ", from a Studio spec" : ""}`
+			status: "success",
+			files: [...files.paths],
+			fileCount: files.paths.size,
+			hashes: output.hashes,
+			disk: disk ? { hashes: disk.hashes } : void 0
 		};
 	}
-	saveConfig(input) {
-		return this.#command({
-			command: "saveConfig",
-			run: () => this.#saveConfig(input)
-		});
-	}
-	async #saveConfig(input) {
+	async saveConfig(input) {
+		this.#assertConnected();
 		const { configPath, configFile } = this.#options;
 		if (!Array.isArray(input.edits)) {
 			await this.#warn({ message: "Ignored save: the message carried no edits" });
-			return { value: {
+			return {
 				outcomes: [],
 				changed: false
-			} };
+			};
 		}
 		const edits = input.edits;
 		const refuse = (reason) => ({
@@ -1814,9 +1856,9 @@ var Agent = class extends capnweb.RpcTarget {
 		});
 		if (!this.#permissions.allowConfigEdit) {
 			await this.#warn({ message: "Ignored save: editing kubb.config.ts was not granted" });
-			return { value: refuse("the agent was not granted permission to edit kubb.config.ts") };
+			return refuse("the agent was not granted permission to edit kubb.config.ts");
 		}
-		if (this.#session.active) return { value: refuse("a generation is in progress") };
+		if (this.#session.active) return refuse("a generation is in progress");
 		try {
 			const { outcomes, changed } = await writeConfigEdits({
 				filePath: configFile,
@@ -1824,27 +1866,40 @@ var Agent = class extends capnweb.RpcTarget {
 				extensions: await this.#installedExtensions()
 			});
 			const applied = outcomes.filter((outcome) => outcome.applied).length;
+			await this.#logCommand("saveConfig", `applied ${applied}/${outcomes.length} edits to ${configPath}`);
 			return {
-				value: {
-					outcomes,
-					changed
-				},
-				info: `applied ${applied}/${outcomes.length} edits to ${configPath}`
+				outcomes,
+				changed
 			};
 		} catch (error) {
 			await emit(this.#options.hooks, "studio:error", { error: toError(error) });
-			return { value: refuse(getErrorMessage(error)) };
+			return refuse(getErrorMessage(error));
 		}
 	}
-	readFiles(input) {
-		return this.#command({
-			command: "readFiles",
-			run: () => this.#readFiles(input)
+	/**
+	* Returns the Kubb AST a kept job parsed its spec into. Refused without `allowRead`.
+	*/
+	async readInput(input) {
+		this.#assertConnected();
+		if (!this.#permissions.allowRead) return this.#refuse({
+			message: require_protocol.READ_NOT_ALLOWED_MESSAGE,
+			permission: "allowRead"
 		});
+		if (typeof input.jobId !== "string" || !input.jobId) return this.#refuse({ message: "The request must name a job" });
+		const generation = await this.#generations.get(input.jobId);
+		if (!generation) return this.#refuse({ message: require_protocol.GENERATION_GONE_MESSAGE });
+		const kept = generation.inputBytes ? await this.#generations.readInput(input.jobId) : void 0;
+		if (!kept) return this.#refuse({ message: require_protocol.NO_INPUT_MESSAGE });
+		await this.#logCommand("readInput", "read the API input");
+		return { input: kept };
 	}
-	async #readFiles(input) {
+	/**
+	* Returns the requested files of a kept job, one page of lines at a time. Refused without `allowRead`.
+	*/
+	async readFiles(input) {
+		this.#assertConnected();
 		if (!this.#permissions.allowRead) return this.#refuse({
-			message: "The agent was not granted permission to read generated files",
+			message: require_protocol.READ_NOT_ALLOWED_MESSAGE,
 			permission: "allowRead"
 		});
 		if (!Array.isArray(input.paths) || typeof input.jobId !== "string" || !input.jobId) return this.#refuse({ message: "The request must name a job and carry paths" });
@@ -1862,10 +1917,8 @@ var Agent = class extends capnweb.RpcTarget {
 			cursor: input.cursor,
 			limit: input.limit
 		});
-		return {
-			value: result,
-			info: `read ${Object.keys(result.files).length}/${paths.length} requested file${paths.length === 1 ? "" : "s"}`
-		};
+		await this.#logCommand("readFiles", `read ${Object.keys(result.files).length}/${paths.length} requested file${paths.length === 1 ? "" : "s"}`);
+		return result;
 	}
 };
 const openWebSocketRpc = ({ url, token, instanceId, agent }) => {
@@ -2156,7 +2209,6 @@ async function pairAgent({ onCode, onRetry, maxAttempts = 1, ...options }) {
 }
 //#endregion
 //#region src/snapshot.ts
-const gzipAsync = (0, node_util.promisify)(node_zlib.gzip);
 const UPLOAD_TIMEOUT_MS = 12e4;
 const BUNDLED_DEPENDENCIES = ["@kubb/plugin-barrel"];
 /**
@@ -2276,7 +2328,7 @@ async function createSnapshotPackage({ files, packageInfo }) {
 				Buffer.alloc((512 - bytes.length % 512) % 512)
 			];
 		});
-		return await gzipAsync(Buffer.concat([...chunks, Buffer.alloc(1024)]));
+		return (0, node_zlib.gzipSync)(Buffer.concat([...chunks, Buffer.alloc(1024)]));
 	} finally {
 		await (0, node_fs_promises.rm)(root, {
 			recursive: true,