@kubb/studio 5.3.2 → 5.3.4

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
 import { AgentPermissions, ClientInfo, createJobId } from "./protocol.js";
-import { Storage } from "unstorage";
 import { Config, Hookable, KubbHooks } from "@kubb/core";
+import { Storage } from "unstorage";
 //#region src/api.d.ts
 /**
  * Thrown when Studio rejects the agent token itself (401). Retrying cannot help: the token was
@@ -98,7 +98,9 @@ export declare function createJob({ studioUrl, token, type, agentId, name, versi
   config?: Record<string, unknown>;
 }): Promise<StudioJob>;
 /**
- * Polls `GET /api/jobs/{id}` until the job reaches `success` or `failed`.
+ * Polls `GET /api/jobs/{id}` until the job reaches `success` or `failed`, waiting
+ * {@link INITIAL_POLL_DELAY_MS} first and doubling up to {@link MAX_POLL_INTERVAL_MS} so a long
+ * job stays inside the API key's rate limit.
  *
  * A `failed` job resolves normally. Check `job.status` and `job.error`. Throws only when the
  * deadline passes before Studio finishes.
@@ -197,6 +199,13 @@ type StudioSessionOptions = {
    * default to.
    */
   installLogger?: (hooks: Hookable<KubbHooks>) => void | Promise<void>;
+  /**
+   * Threshold for the reconnect loop's own `console.error` lines, using the numeric constants
+   * `@kubb/core` exports as `logLevel`. Left out, those lines never print, the same silent default
+   * as an unset `installLogger` — a reconnect happens outside any one session's hooks, so it has no
+   * other way to ask a host how loud to be.
+   */
+  logLevel?: number;
   /**
    * Called when this session's background reconnect is rejected with an invalid token. Unlike
    * `ClientOptions.onAuthRequired`, this fires once per session rather than once per pool:

package/dist/index.js

@@ -1,21 +1,24 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
 import { createJobId, isCommandMessage, isDisconnectMessage, isStudioPongMessage, isStudioReadyMessage } from "./protocol.js";
 import { createRequire } from "node:module";
-import { styleText } from "node:util";
+import { promisify, styleText } from "node:util";
 import process$1 from "node:process";
 import { spawn } from "node:child_process";
-import { readFile, writeFile } from "node:fs/promises";
-import path, { isAbsolute, relative, resolve } from "node:path";
+import { glob, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import path, { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { Diagnostics, Hookable, createKubb, fsStorage, logLevel, memoryStorage } from "@kubb/core";
 import { FetchError, ofetch } from "ofetch";
-import { hash, randomBytes } from "node:crypto";
+import { createHash, hash, randomBytes } from "node:crypto";
 import { createStorage } from "unstorage";
 import fsDriver from "unstorage/drivers/fs";
-import { Diagnostics, Hookable, createKubb, fsStorage, memoryStorage } from "@kubb/core";
 import { x } from "tinyexec";
 import { builders, detectCodeFormat, generateCode, parseModule } from "magicast";
 import { existsSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { mergeDeep } from "remeda";
+import { tmpdir } from "node:os";
+import { gzip } from "node:zlib";
+import { build } from "tsdown";
 import WebSocket from "ws";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 //#region src/constants.ts
@@ -556,19 +559,20 @@ async function runRegistration({ token, studioUrl, poolSize }) {
 * Called on process termination or server close. A failed notify is logged and swallowed: the
 * local socket is already gone, and failing teardown must not block shutdown or reconnect.
 */
-async function disconnect({ sessionId, token, studioUrl, slug }) {
+async function disconnect({ sessionId, token, studioUrl, slug, logLevel: logLevel$2 }) {
 	const url = `${studioUrl}/api/agent/sessions/${sessionId}/disconnect`;
 	const tag = slug ?? "agent";
+	const canLog = logLevel$2 !== void 0 && logLevel$2 > logLevel.silent;
 	try {
 		await ofetch(url, {
 			method: "POST",
 			headers: { Authorization: `Bearer ${token}` }
 		});
-		console.log(styleText("green", `[${tag}] Disconnected from Studio`));
+		if (canLog) console.error(styleText("green", `[${tag}] Disconnected from Studio`));
 	} catch (error) {
 		const statusCode = error?.statusCode;
 		if (statusCode !== void 0 && statusCode >= 400 && statusCode < 500) return;
-		console.warn(styleText("yellow", `[${tag}] Failed to notify Studio of disconnection: ${getErrorMessage(error)}`));
+		if (canLog) console.warn(styleText("yellow", `[${tag}] Failed to notify Studio of disconnection: ${getErrorMessage(error)}`));
 	}
 }
 /**
@@ -605,18 +609,41 @@ async function createJob({ studioUrl, token, type, agentId, name, version, confi
 	return job;
 }
 /**
-* Polls `GET /api/jobs/{id}` until the job reaches `success` or `failed`.
+* A job runs a generation and packs a tarball, so it is never done the instant it is queued.
+*/
+const INITIAL_POLL_DELAY_MS = 2e3;
+/**
+* Slowest the poll backs off to. Requests per run are roughly `timeoutMs` divided by this, and
+* every concurrent run on the same organization key draws on one budget.
+*/
+const MAX_POLL_INTERVAL_MS = 3e4;
+/**
+* Polls `GET /api/jobs/{id}` until the job reaches `success` or `failed`, waiting
+* {@link INITIAL_POLL_DELAY_MS} first and doubling up to {@link MAX_POLL_INTERVAL_MS} so a long
+* job stays inside the API key's rate limit.
 *
 * A `failed` job resolves normally. Check `job.status` and `job.error`. Throws only when the
 * deadline passes before Studio finishes.
 */
 async function waitForJob({ studioUrl, token, id, timeoutMs = 6e4 }) {
 	const deadline = Date.now() + timeoutMs;
+	let interval = INITIAL_POLL_DELAY_MS;
 	for (;;) {
-		const { job } = await ofetch(`${studioUrl}/api/jobs/${id}`, { headers: { "x-api-key": token } });
-		if (job.status === "success" || job.status === "failed") return job;
+		await new Promise((resolve) => setTimeout(resolve, Math.max(Math.min(interval, deadline - Date.now()), 0)));
 		if (Date.now() >= deadline) throw new Error("Timed out waiting for the Studio job");
-		await new Promise((resolve) => setTimeout(resolve, 1e3));
+		interval = Math.min(interval * 2, MAX_POLL_INTERVAL_MS);
+		try {
+			const { job } = await ofetch(`${studioUrl}/api/jobs/${id}`, {
+				headers: { "x-api-key": token },
+				retry: false
+			});
+			if (job.status === "success" || job.status === "failed") return job;
+		} catch (error) {
+			const response = error.response;
+			if (response?.status !== 429) throw error;
+			const retryAfter = response._data?.data?.tryAgainIn;
+			interval = Math.max(interval, typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : MAX_POLL_INTERVAL_MS);
+		}
 	}
 }
 /**
@@ -646,7 +673,7 @@ async function createAgent({ studioUrl, token, name, machineToken }) {
 }
 //#endregion
 //#region package.json
-var version = "5.3.2";
+var version = "5.3.4";
 //#endregion
 //#region src/hooks.ts
 /**
@@ -1579,6 +1606,134 @@ async function generate({ config, hooks }) {
 	}
 }
 //#endregion
+//#region src/snapshotPackage.ts
+const gzipAsync = promisify(gzip);
+/**
+* Maps a generated file's path to its place inside the tarball, stripping everything before a
+* `src`/`dist` segment and any `..`/empty path segment so a crafted file name cannot escape the
+* `package/` root.
+*/
+function packagePath(filePath) {
+	const normalized = filePath.replaceAll("\\", "/");
+	return `package/${(normalized.match(/\/(?:src|dist)\/.*$/)?.[0].slice(1) ?? normalized.replace(/^\/+/, "")).split("/").filter((part) => part && part !== "." && part !== "..").join("/")}`;
+}
+/**
+* Splits a tarball entry path into the legacy 100-byte `name` field and, when the path does not
+* fit, the 155-byte USTAR `prefix` field that extends it. Throws rather than silently truncating
+* a path the format cannot address (max 256 bytes: 100 name + 1 separator + 155 prefix).
+*/
+function splitEntryPath(path) {
+	if (Buffer.byteLength(path, "utf8") <= 100) return {
+		name: path,
+		prefix: ""
+	};
+	for (let i = path.length - 1; i >= 0; i--) {
+		if (path[i] !== "/") continue;
+		const prefix = path.slice(0, i);
+		const name = path.slice(i + 1);
+		if (Buffer.byteLength(prefix, "utf8") <= 155 && Buffer.byteLength(name, "utf8") <= 100) return {
+			name,
+			prefix
+		};
+	}
+	throw new Error(`Snapshot path is too long for a tar entry: ${path}`);
+}
+function header(path, size) {
+	const { name, prefix } = splitEntryPath(path);
+	const value = Buffer.alloc(512);
+	value.write(name, 0, "utf8");
+	value.write("0000644\0", 100, "ascii");
+	value.write("0000000\0", 108, "ascii");
+	value.write("0000000\0", 116, "ascii");
+	value.write(`${size.toString(8).padStart(11, "0")}\0`, 124, "ascii");
+	value.write(`${Math.floor(Date.now() / 1e3).toString(8).padStart(11, "0")}\0`, 136, "ascii");
+	value.fill(32, 148, 156);
+	value.write("0", 156, "ascii");
+	value.write("ustar\0", 257, "ascii");
+	value.write("00", 263, "ascii");
+	value.write("0000000\0", 265, "ascii");
+	value.write("0000000\0", 297, "ascii");
+	value.write(prefix, 345, "utf8");
+	const checksum = [...value].reduce((sum, byte) => sum + byte, 0);
+	value.write(`${checksum.toString(8).padStart(6, "0")}\0 `, 148, "ascii");
+	return value;
+}
+/**
+* Packs a generation's files into a gzipped, npm-installable tarball: a `package/` root with the
+* generated sources, a `tsdown`-built `dist/` (esm + cjs), and a `package.json` manifest.
+*/
+async function createSnapshotPackage(files, packageInfo) {
+	const root = await mkdtemp(join(tmpdir(), "kubb-snapshot-"));
+	const dist = join(root, "dist");
+	const resolvedPaths = Object.entries(files).map(([name, content]) => ({
+		name,
+		content,
+		target: packagePath(name)
+	}));
+	const targetOwners = /* @__PURE__ */ new Map();
+	for (const { name, target } of resolvedPaths) {
+		const owner = targetOwners.get(target);
+		if (owner) throw new Error(`Snapshot has two generated files that sanitize to the same path "${target}": "${owner}" and "${name}"`);
+		targetOwners.set(target, name);
+	}
+	try {
+		await mkdir(dist);
+		await Promise.all(resolvedPaths.map(async ({ content, target }) => {
+			const path = join(root, target.slice(8));
+			await mkdir(join(path, ".."), { recursive: true });
+			await writeFile(path, content);
+		}));
+		const sourceEntries = resolvedPaths.filter(({ name }) => /\.(?:[cm]?[jt]sx?)$/.test(name)).map(({ target }) => join(root, target.slice(8)));
+		if (sourceEntries.length) await build({
+			entry: sourceEntries,
+			outDir: dist,
+			format: ["esm", "cjs"],
+			dts: false,
+			sourcemap: false,
+			unbundle: true,
+			report: false,
+			logLevel: "silent",
+			fixedExtension: true
+		});
+		const builtEntries = await Promise.all((await Array.fromAsync(glob("**/*", {
+			cwd: dist,
+			withFileTypes: true
+		}))).filter((entry) => entry.isFile()).map(async (entry) => {
+			const filePath = join(entry.parentPath, entry.name);
+			return [`package/dist/${relative(dist, filePath).split(sep).join("/")}`, await readFile(filePath, "utf8")];
+		}));
+		const entries = {
+			"package/package.json": JSON.stringify({
+				...packageInfo,
+				type: "module",
+				main: "./dist/index.cjs",
+				module: "./dist/index.mjs",
+				exports: { ".": {
+					import: "./dist/index.mjs",
+					require: "./dist/index.cjs"
+				} }
+			}, null, 2),
+			...Object.fromEntries(resolvedPaths.map(({ content, target }) => [target, content])),
+			...Object.fromEntries(builtEntries)
+		};
+		const chunks = [];
+		for (const [name, content] of Object.entries(entries)) {
+			const bytes = Buffer.from(content);
+			chunks.push(header(name, bytes.length), bytes, Buffer.alloc((512 - bytes.length % 512) % 512));
+		}
+		const bytes = await gzipAsync(Buffer.concat([...chunks, Buffer.alloc(1024)]));
+		return {
+			bytes,
+			integrity: `sha512-${createHash("sha512").update(bytes).digest("base64")}`
+		};
+	} finally {
+		await rm(root, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
 //#region src/ws.ts
 /**
 * How many generated files are read from storage at once when building the
@@ -1674,7 +1829,7 @@ function sendErrorMessage(ws, error, jobId) {
 /**
 * Forwards selected Kubb lifecycle events to Studio as data messages for the active session.
 */
-function setupEventsStream(ws, hooks, jobId) {
+function setupEventsStream(ws, hooks, jobId, options = {}) {
 	const unhooks = [];
 	/**
 	* Registers a listener and keeps its remover, so one generation's listeners come off the session
@@ -1788,11 +1943,12 @@ function setupEventsStream(ws, hooks, jobId) {
 				if (content !== null) files[relativeStoragePath(config.root, path)] = content;
 			}
 		});
+		options.onGenerationEnd?.(files);
 		sendDataMessage({
 			type: "kubb:generation:end",
 			data: [{
 				config,
-				storage: files,
+				storage: options.skipStorage ? {} : files,
 				peerDependencies,
 				missingDependencies
 			}]
@@ -1909,15 +2065,15 @@ function applyStudioDefaults(options) {
 * socket, its hook emitter, or its session id alive for the length of the retry interval.
 */
 function reconnect(options) {
-	const { signal, retryInterval, onTokenRejected } = options;
+	const { signal, retryInterval, onTokenRejected, logLevel: logLevel$1 } = options;
 	if (signal?.aborted) return;
-	console.info(styleText("dim", `Retrying connection in ${retryInterval}ms to Kubb Studio ...`));
+	if (logLevel$1 !== void 0 && logLevel$1 > logLevel.silent) console.error(styleText("dim", `Retrying connection in ${retryInterval}ms to Kubb Studio ...`));
 	const cancel = () => clearTimeout(timer);
 	const timer = setTimeout(() => {
 		signal?.removeEventListener("abort", cancel);
 		if (signal?.aborted) return;
 		new StudioSession(options).connect().catch((error) => {
-			console.error(styleText("red", `Reconnect attempt to Kubb Studio failed: ${getErrorMessage(error)}`));
+			if (logLevel$1 !== void 0 && logLevel$1 > logLevel.silent) console.error(styleText("red", `Reconnect attempt to Kubb Studio failed: ${getErrorMessage(error)}`));
 			if (error instanceof InvalidAgentTokenError) {
 				onTokenRejected?.(error);
 				return;
@@ -1952,6 +2108,7 @@ var StudioSession = class {
 	#heartbeatTimer;
 	#readyTimer;
 	#lastPongAt = Date.now();
+	#lastGeneration;
 	constructor(options) {
 		this.#options = applyStudioDefaults(options);
 	}
@@ -2134,7 +2291,7 @@ var StudioSession = class {
 	* `#disposed` keeps the close event from running this twice, and a shutdown from reconnecting.
 	*/
 	async #end({ reason, retry }) {
-		const { studioUrl, token } = this.#options;
+		const { studioUrl, token, logLevel } = this.#options;
 		if (this.#disposed) return;
 		this.#disposed = true;
 		if (reason === "shutdown" && this.#ws) sendAgentMessage(this.#ws, {
@@ -2146,7 +2303,8 @@ var StudioSession = class {
 			sessionId: this.#session.sessionId,
 			studioUrl,
 			token,
-			slug: this.#session.slug
+			slug: this.#session.slug,
+			logLevel
 		}).catch(() => {});
 		if (retry) reconnect(this.#options);
 	}
@@ -2205,6 +2363,9 @@ var StudioSession = class {
 			case "studio:save":
 				await this.#handleSave(ws, data, command);
 				return;
+			case "studio:snapshot":
+				await this.#handleSnapshot(ws, data, command);
+				return;
 		}
 	}
 	async #handleGenerate(ws, data, command) {
@@ -2228,7 +2389,13 @@ var StudioSession = class {
 				await this.#warn(`Ignored the spec from Studio; set ${remedy} to generate from it`);
 			}
 			const resolvedPlugins = plugins ?? config.plugins;
-			const detach = [setupHookListener(this.#hooks, root), setupEventsStream(ws, this.#hooks, data.jobId)];
+			let generatedFiles;
+			const detach = [setupHookListener(this.#hooks, root), setupEventsStream(ws, this.#hooks, data.jobId, {
+				skipStorage: client?.kind === "ci",
+				onGenerationEnd: (files) => {
+					generatedFiles = files;
+				}
+			})];
 			try {
 				await generate({
 					config: {
@@ -2249,6 +2416,7 @@ var StudioSession = class {
 				});
 			} finally {
 				for (const remove of detach) remove();
+				this.#lastGeneration = generatedFiles;
 			}
 			await this.#hooks.callHook("studio:command:end", {
 				command,
@@ -2317,6 +2485,68 @@ var StudioSession = class {
 			refuse(getErrorMessage(error));
 		}
 	}
+	async #handleSnapshot(ws, data, command) {
+		const refuse = (message) => sendAgentMessage(ws, {
+			type: "agent:snapshot",
+			jobId: data.jobId,
+			payload: {
+				status: "error",
+				message
+			}
+		});
+		if (this.#isSandbox) {
+			await this.#warn("Ignored snapshot: a sandbox agent has no project to build a package from");
+			refuse("a sandbox agent has no project to build a package from");
+			return;
+		}
+		const { name, version, peerDependencies, uploadPath } = data.payload;
+		if (!name || !version || !uploadPath) {
+			await this.#warn("Ignored snapshot: the message was missing required fields");
+			refuse("the message was missing required fields");
+			return;
+		}
+		const files = this.#lastGeneration;
+		if (!files) {
+			await this.#warn("Ignored snapshot: no prior generation to pack");
+			refuse("no prior generation exists to pack, run a generation first");
+			return;
+		}
+		try {
+			const { bytes, integrity } = await createSnapshotPackage(files, {
+				name,
+				version,
+				peerDependencies: peerDependencies ?? {}
+			});
+			const { token, studioUrl } = this.#options;
+			const redirect = await fetch(new URL(uploadPath, studioUrl), {
+				method: "PUT",
+				headers: { Authorization: `Bearer ${token}` },
+				redirect: "manual"
+			});
+			const storageUrl = redirect.headers.get("location");
+			if (redirect.status !== 307 || !storageUrl) throw new Error(`Studio did not provide a storage URL (status ${redirect.status})`);
+			const response = await fetch(storageUrl, {
+				method: "PUT",
+				body: new Uint8Array(bytes)
+			});
+			if (!response.ok) throw new Error(`Snapshot upload failed with status ${response.status}`);
+			sendAgentMessage(ws, {
+				type: "agent:snapshot",
+				jobId: data.jobId,
+				payload: {
+					status: "ok",
+					integrity
+				}
+			});
+			await this.#hooks.callHook("studio:command:end", {
+				command,
+				info: `packed ${Object.keys(files).length} file${Object.keys(files).length === 1 ? "" : "s"}`
+			});
+		} catch (error) {
+			await this.#hooks.callHook("studio:error", { error: toError(error) });
+			refuse(getErrorMessage(error));
+		}
+	}
 };
 //#endregion
 //#region src/client.ts