@kubb/studio 5.11.1 → 5.11.3

package/README.md

@@ -85,6 +85,10 @@ running in a developer's project and a container running a fixed plugin set.
 the agent is a sandbox and carries its slug and Studio's version. From then on the agent pings every
 30 seconds, and Studio schedules one job at a time on the socket.
 
+With `allowRead`, the connect payload includes the current `output.path` file list. Studio reads
+file contents from disk through `readFiles` when a user opens a file. Sandbox agents have no disk
+output, and output paths outside the project root are excluded.
+
 Studio ends a socket on purpose with one of these close codes:
 
 | Code   | Meaning                                       | `connectAgent`                        |
@@ -108,7 +112,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 existing output files and the files a generation produced.                     |
 | `allowReadAst`    | Studio may read back the parsed spec (the Kubb AST).                                           |
 
 A sandbox never writes or edits config, and always allows reads.

package/dist/index.cjs

@@ -140,6 +140,27 @@ async function read(path) {
 	if (runtime.isBun) return Bun.file(path).text();
 	return (0, node_fs_promises.readFile)(path, { encoding: "utf8" });
 }
+/**
+* Resolves to `true` when `path` is `parent` itself or nested inside it. Both sides are resolved
+* to absolute paths first, so relative and `..`-containing inputs compare correctly.
+*
+* Guards a destructive or an out-of-tree operation: before wiping an output directory, check that
+* it does not contain the project root, and before loading a path a caller supplied, check that it
+* did not escape the directory it is allowed to read from.
+*
+* @example
+* isPathInside('./src/gen', '.')   // true  — nested inside the root
+* isPathInside('.', '.')           // true  — the same directory counts as inside
+* isPathInside('.', './src/gen')   // false — the root is not inside its own output
+* isPathInside('../other', '.')    // false — escapes the root
+*/
+function isPathInside(path, parent) {
+	const resolvedPath = (0, node_path.resolve)(path);
+	const resolvedParent = (0, node_path.resolve)(parent);
+	if (resolvedPath === resolvedParent) return true;
+	const rel = (0, node_path.relative)(resolvedParent, resolvedPath);
+	return rel !== "" && !rel.startsWith("..") && !(0, node_path.isAbsolute)(rel);
+}
 //#endregion
 //#region ../../internals/utils/src/promise.ts
 /**
@@ -178,7 +199,7 @@ function getElapsedMs(hrStart) {
 }
 //#endregion
 //#region package.json
-var version = "5.11.1";
+var version = "5.11.3";
 //#endregion
 //#region src/resolveConfig.ts
 /**
@@ -483,6 +504,33 @@ async function mergePlugins({ diskPlugins, studioPlugins, extensions = /* @__PUR
 	})];
 }
 /**
+* Throws `KUBB_PATH_TRAVERSAL` when a plugin would write outside the config's output folder to a path
+* the disk config does not set. Studio can change `output.path`, also inside `override`, and add
+* plugins, so without this check any member of the Studio organization could write any file the agent
+* can reach, including `node_modules` code the next run imports. A path from the config file stays
+* allowed, since a monorepo may write outside its root.
+*/
+function assertOutputPaths({ plugins, diskPlugins, root, outputPath }) {
+	const base = node_path.default.resolve(root, outputPath);
+	const targetsOf = (plugin) => {
+		const { output, override } = plugin.options ?? {};
+		return [output, ...Array.isArray(override) ? override.map((entry) => entry?.options?.output) : []].flatMap((entry) => typeof entry?.path === "string" ? [node_path.default.resolve(base, entry.path)] : []);
+	};
+	const diskTargets = new Set(diskPlugins.flatMap(targetsOf));
+	for (const plugin of plugins) {
+		const target = targetsOf(plugin).find((resolved) => !diskTargets.has(resolved) && !isPathInside(resolved, base));
+		if (!target) continue;
+		throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.pathTraversal,
+			severity: "error",
+			message: `Plugin "${plugin.name}" would write to "${target}", outside the output folder "${base}". Studio can only set an output path inside it.`,
+			help: "Choose an output path inside the output folder, or set this path in the config file.",
+			location: { kind: "config" },
+			plugin: plugin.name
+		});
+	}
+}
+/**
 * Re-invokes the factory behind a disk adapter or parser with Studio's options merged over its own.
 * An instance carries live functions (`parse`, `print`, ...) that cannot survive JSON, so Studio's
 * options are a patch, not a replacement, and the factory is found from the disk instance itself: the
@@ -1425,6 +1473,33 @@ async function listDisk({ root, outputPath, maxFiles }) {
 		paths: new Set(paths)
 	};
 }
+async function readDiskFiles({ files: disk, paths, cursor = 0, limit }) {
+	const files = {};
+	const pages = {};
+	await inParallel({
+		items: paths.filter((path) => disk.paths.has(path)),
+		limit: READ_CONCURRENCY,
+		run: async (path) => {
+			const content = await disk.storage.readItem((0, node_path.resolve)(disk.root, path));
+			if (content === null) return;
+			if (limit === void 0) {
+				files[path] = content;
+				return;
+			}
+			const lines = content.split(/\r\n|\r|\n/);
+			const end = Math.min(cursor + limit, lines.length);
+			files[path] = lines.slice(cursor, end).join("\n");
+			pages[path] = {
+				nextCursor: end < lines.length ? end : null,
+				totalLines: lines.length
+			};
+		}
+	});
+	return limit === void 0 ? { files } : {
+		files,
+		pages
+	};
+}
 /**
 * Keeps recent generations by job id in `storage`, with an index next to them so a store on disk
 * survives a restart. A generation is only ever looked up by its job id, so on a pooled sandbox one
@@ -1448,7 +1523,7 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 	/**
 	* Copies `files` into the store as one set of `jobId`. Above `maxSetMb` only the hashes are kept.
 	*/
-	async function keep({ jobId, source, files, maxSetMb }) {
+	async function keep({ jobId, source, files, maxSetMb, normalize = source === require_protocol.FileSource.OUTPUT }) {
 		const maxSetBytes = maxSetMb * MB;
 		const hashes = {};
 		let bytes = 0;
@@ -1459,8 +1534,8 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 				if (path.split("/").includes("..")) return;
 				const content = await files.storage.readItem((0, node_path.resolve)(files.root, path));
 				if (content === null) return;
-				if (source === require_protocol.FileSource.OUTPUT && !content.trim()) return;
-				hashes[path] = hashOf(source === require_protocol.FileSource.OUTPUT ? `${content.trim()}\n` : content);
+				if (normalize && !content.trim()) return;
+				hashes[path] = hashOf(normalize ? `${content.trim()}\n` : content);
 				bytes += Buffer.byteLength(content);
 				if (bytes <= maxSetBytes) await storage.writeItem(`${dirOf(jobId)}${source}/${path}`, content);
 			}
@@ -1924,8 +1999,12 @@ var Agent = class extends capnweb.RpcTarget {
 			this.#readConfigFileView(source),
 			this.#installedExtensions(source)
 		]);
+		const output = await this.#readDiskOutput(config).catch(async (error) => {
+			await this.#warn({ message: `Could not read the output directory: ${getErrorMessage(error)}` });
+		});
 		this.#session.connected.resolve(info);
 		return {
+			output,
 			versions: {
 				kubb: version,
 				agent: version$1
@@ -1962,6 +2041,16 @@ var Agent = class extends capnweb.RpcTarget {
 			permissions: this.#permissions
 		};
 	}
+	async #readDiskOutput(config) {
+		if (this.#sandbox || !this.#permissions.allowRead || this.#session.active) return void 0;
+		const files = await listDisk({
+			root: this.#options.root,
+			outputPath: config.output.path,
+			maxFiles: DISK_SNAPSHOT_MAX_FILES
+		});
+		if (!files) return void 0;
+		return { files: [...files.paths] };
+	}
 	startGeneration(input) {
 		const stream = createGenerationStream(this.#options.hooks, input.jobId);
 		const controller = new AbortController();
@@ -1987,7 +2076,7 @@ var Agent = class extends capnweb.RpcTarget {
 			severity: "error",
 			message: "Connection is closed"
 		});
-		if (this.#session.active) return this.#refuse({ message: "A generation is already in progress, please wait for it to finish" });
+		if (this.#session.active) return this.#refuse({ message: require_protocol.AgentMessage.GENERATION_IN_PROGRESS });
 		const settled = Promise.withResolvers();
 		this.#session.active = {
 			jobId: input.jobId,
@@ -2014,16 +2103,25 @@ var Agent = class extends capnweb.RpcTarget {
 			settled.resolve();
 		}
 	}
+	/** Merges Studio's config over the disk config, refuses output paths outside the output folder, then generates in `root`. */
 	async #generate({ input, root, signal }) {
 		const { jobId, config: patch } = input;
 		const studioInput = this.#sandbox ? patch?.input : void 0;
-		if (this.#sandbox && (typeof studioInput !== "string" || !studioInput.trim() || (0, _kubb_core.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" });
+		if (this.#sandbox && (typeof studioInput !== "string" || !studioInput.trim() || (0, _kubb_core.getInputKind)(studioInput) !== "inline")) return this.#refuse({ message: require_protocol.AgentMessage.SANDBOX_INPUT_ONLY });
 		const [config, extensions] = await Promise.all([this.#options.loadConfig(), this.#installedExtensions()]);
 		const [plugins, adapter, parsers] = await Promise.all([
 			mergePlugins({
 				diskPlugins: config.plugins,
 				studioPlugins: patch?.plugins,
 				extensions
+			}).then((merged) => {
+				assertOutputPaths({
+					plugins: merged ?? [],
+					diskPlugins: config.plugins,
+					root,
+					outputPath: config.output.path
+				});
+				return merged;
 			}),
 			mergeAdapter(config.adapter, patch?.adapter, extensions),
 			mergeParsers({
@@ -2142,7 +2240,7 @@ var Agent = class extends capnweb.RpcTarget {
 			message: require_protocol.AgentMessage.READ_AST_NOT_ALLOWED,
 			permission: require_protocol.AgentPermission.READ_AST
 		});
-		if (typeof input.jobId !== "string" || !input.jobId) return this.#refuse({ message: "The request must name a job" });
+		if (typeof input.jobId !== "string" || !input.jobId) return this.#refuse({ message: require_protocol.AgentMessage.JOB_REQUIRED });
 		const generation = await this.#generations.get(input.jobId);
 		if (!generation) return this.#refuse({ message: require_protocol.AgentMessage.GENERATION_GONE });
 		const kept = generation.inputBytes ? await this.#generations.readInput(input.jobId) : void 0;
@@ -2159,14 +2257,32 @@ var Agent = class extends capnweb.RpcTarget {
 			message: require_protocol.AgentMessage.READ_NOT_ALLOWED,
 			permission: require_protocol.AgentPermission.READ
 		});
-		if (!Array.isArray(input.paths) || typeof input.jobId !== "string" || !input.jobId) return this.#refuse({ message: "The request must name a job and carry paths" });
+		if (!Array.isArray(input.paths) || typeof input.jobId !== "string" || !input.jobId || !["generation", "currentDisk"].includes(input.jobType)) return this.#refuse({ message: require_protocol.AgentMessage.FILE_REQUEST_INVALID });
 		const { paths } = input;
-		if (paths.length > 50) return this.#refuse({ message: `At most 50 paths may be requested at once` });
+		if (paths.length > 50) return this.#refuse({ message: require_protocol.AgentMessage.TOO_MANY_FILES });
+		if (!isValidPage(input)) return this.#refuse({ message: require_protocol.AgentMessage.INVALID_PAGE });
+		if (input.jobType === "currentDisk") {
+			if (this.#sandbox) return this.#refuse({ message: require_protocol.AgentMessage.SANDBOX_DISK_UNAVAILABLE });
+			const config = await this.#options.loadConfig();
+			const disk = await listDisk({
+				root: this.#options.root,
+				outputPath: config.output.path,
+				maxFiles: DISK_SNAPSHOT_MAX_FILES
+			});
+			if (!disk) return this.#refuse({ message: require_protocol.AgentMessage.GENERATION_GONE });
+			const result = await readDiskFiles({
+				files: disk,
+				paths,
+				cursor: input.cursor,
+				limit: input.limit
+			});
+			await this.#logCommand("readFiles", `read ${Object.keys(result.files).length}/${paths.length} requested file${paths.length === 1 ? "" : "s"}`);
+			return result;
+		}
 		const generation = await this.#generations.get(input.jobId);
 		if (!generation) return this.#refuse({ message: require_protocol.AgentMessage.GENERATION_GONE });
-		if (!isValidPage(input)) return this.#refuse({ message: `The cursor must be a whole line from 0 and come with a limit of 1 to ${require_protocol.MAX_PAGE_LINES} lines` });
 		const source = input.source === require_protocol.FileSource.DISK ? require_protocol.FileSource.DISK : require_protocol.FileSource.OUTPUT;
-		if (!generation[source]) return this.#refuse({ message: "This agent kept no snapshot of the files on disk for that job" });
+		if (!generation[source]) return this.#refuse({ message: require_protocol.AgentMessage.NO_DISK_SNAPSHOT });
 		const result = await this.#generations.read({
 			generation,
 			source,
@@ -2187,15 +2303,15 @@ var Agent = class extends capnweb.RpcTarget {
 			permission: require_protocol.AgentPermission.READ
 		});
 		const { jobId, path, base, cursor = 0, limit } = input;
-		if (typeof jobId !== "string" || !jobId || typeof path !== "string" || !path || typeof base?.jobId !== "string" || !base.jobId) return this.#refuse({ message: "The request must name a job, a base, and a path" });
+		if (typeof jobId !== "string" || !jobId || typeof path !== "string" || !path || typeof base?.jobId !== "string" || !base.jobId) return this.#refuse({ message: require_protocol.AgentMessage.DIFF_REQUEST_INVALID });
 		if (!isValidPage({
 			cursor,
 			limit
-		})) return this.#refuse({ message: `The cursor must be a whole line from 0 and come with a limit of 1 to ${require_protocol.MAX_PAGE_LINES} lines` });
+		})) return this.#refuse({ message: require_protocol.AgentMessage.INVALID_PAGE });
 		const [generation, baseGeneration] = await Promise.all([this.#generations.get(jobId), this.#generations.get(base.jobId)]);
 		if (!generation || !baseGeneration) return this.#refuse({ message: require_protocol.AgentMessage.GENERATION_GONE });
 		const baseSource = base.source === require_protocol.FileSource.DISK ? require_protocol.FileSource.DISK : require_protocol.FileSource.OUTPUT;
-		if (!baseGeneration[baseSource]) return this.#refuse({ message: "This agent kept no snapshot of the files on disk for that job" });
+		if (!baseGeneration[baseSource]) return this.#refuse({ message: require_protocol.AgentMessage.NO_DISK_SNAPSHOT });
 		const [after, before] = await Promise.all([this.#generations.read({
 			generation,
 			source: require_protocol.FileSource.OUTPUT,
@@ -2206,7 +2322,7 @@ var Agent = class extends capnweb.RpcTarget {
 			paths: [path]
 		})]);
 		const afterContent = after.files[path];
-		if (afterContent === void 0 && path in generation.output.hashes) return this.#refuse({ message: "This agent kept only the hashes of that job" });
+		if (afterContent === void 0 && path in generation.output.hashes) return this.#refuse({ message: require_protocol.AgentMessage.HASHES_ONLY });
 		const beforeContent = before.files[path];
 		if (beforeContent === void 0) return {
 			hunks: [],