@kubb/studio 5.2.5 → 5.2.7

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
-import { a as AgentPermissions, c as ClientInfo } from "./index-Dq2uq38g.js";
+import { AgentPermissions, ClientInfo, createJobId } from "./protocol.js";
 import { Storage } from "unstorage";
 import { Config, Hookable, KubbHooks } from "@kubb/core";
 //#region src/api.d.ts
@@ -11,6 +11,109 @@ import { Config, Hookable, KubbHooks } from "@kubb/core";
 export declare class InvalidAgentTokenError extends Error {
   constructor(studioUrl: string, options?: ErrorOptions);
 }
+/**
+ * Status values returned by Studio's jobs API.
+ */
+type StudioJobStatus = 'queued' | 'running' | 'success' | 'failed';
+/**
+ * Package view returned on a successful snapshot job from Studio.
+ */
+type StudioSnapshot = {
+  /**
+   * Immutable snapshot id.
+   */
+  id: string;
+  /**
+   * npm package name, or `null` when Studio stored none.
+   */
+  name: string | null;
+  /**
+   * npm package version, or `null` when Studio stored none.
+   */
+  version: string | null;
+  /**
+   * Subresource integrity hash for the tarball, or `null` when unavailable.
+   */
+  integrity: string | null;
+  /**
+   * Preferable download path, often the readable `/packages/{agentSlug}/{name}.tgz` form.
+   */
+  url: string;
+  /**
+   * Stable download path keyed by snapshot id.
+   */
+  snapshotIdUrl: string;
+  /**
+   * ISO timestamp after which Studio may delete the tarball.
+   */
+  expiresAt: string;
+};
+/**
+ * Job record from `POST /api/jobs` and `GET /api/jobs/{id}`.
+ */
+type StudioJob = {
+  /**
+   * Job id returned by Studio when the job was queued.
+   */
+  id: string;
+  /**
+   * Current status. Poll until `success` or `failed`.
+   */
+  status: StudioJobStatus;
+  /**
+   * Failure message when `status` is `failed`.
+   */
+  error?: string;
+  /**
+   * Package view when a snapshot job finished successfully.
+   */
+  snapshot?: StudioSnapshot;
+};
+/**
+ * Queues a generation or snapshot job on Studio (`POST /api/jobs`).
+ *
+ * Returns as soon as Studio accepts the job (`202`). Poll with {@link waitForJob} until it finishes.
+ * Authenticates with the organization CI API key via `x-api-key`.
+ *
+ * @example Snapshot job
+ * ```ts
+ * const job = await createJob({
+ *   studioUrl: 'https://kubb.studio',
+ *   token: process.env.KUBB_TOKEN!,
+ *   type: 'snapshot',
+ *   agentId: agent.id,
+ *   name: '@kubb/demo',
+ *   version: '1.0.0',
+ * })
+ * const finished = await waitForJob({ studioUrl, token, id: job.id })
+ * ```
+ */
+export declare function createJob({ studioUrl, token, type, agentId, name, version, config }: {
+  studioUrl: string;
+  token: string;
+  type: 'generation' | 'snapshot';
+  agentId: string;
+  name?: string;
+  version?: string;
+  config?: Record<string, unknown>;
+}): Promise<StudioJob>;
+/**
+ * Polls `GET /api/jobs/{id}` until the job reaches `success` or `failed`.
+ *
+ * A `failed` job resolves normally. Check `job.status` and `job.error`. Throws only when the
+ * deadline passes before Studio finishes.
+ */
+export declare function waitForJob({ studioUrl, token, id, timeoutMs }: {
+  studioUrl: string;
+  token: string;
+  id: string;
+  /**
+   * How long to keep polling before throwing, in milliseconds.
+   *
+   * @default 60000
+   */
+  timeoutMs?: number;
+}): Promise<StudioJob>;
 //#endregion
 //#region src/StudioSession.d.ts
 type StudioSessionOptions = {
@@ -377,5 +480,5 @@ type PollOptions = {
  */
 export declare function pollForPairingToken({ studioUrl, session, signal }: PollOptions): Promise<PairingResult>;
 //#endregion
-export type { Client, ClientOptions, ConnectionOptions, StudioConnectedContext };
+export { type Client, type ClientOptions, type ConnectionOptions, type StudioConnectedContext, type StudioJob, type StudioJobStatus, type StudioSnapshot, createJobId };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,9 +1,9 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
-import { isCommandMessage, isDisconnectMessage, isStudioPingMessage, isStudioReadyMessage } from "./protocol.js";
+import { createJobId, isCommandMessage, isDisconnectMessage, isStudioPingMessage, isStudioReadyMessage } from "./protocol.js";
 import { createRequire } from "node:module";
 import { styleText } from "node:util";
 import { readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
+import path, { isAbsolute, relative, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { FetchError, ofetch } from "ofetch";
 import { hash, randomBytes } from "node:crypto";
@@ -559,12 +559,62 @@ async function disconnect({ sessionId, token, studioUrl, slug }) {
 		});
 		console.log(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)}`));
 	}
 }
+/**
+* Queues a generation or snapshot job on Studio (`POST /api/jobs`).
+*
+* Returns as soon as Studio accepts the job (`202`). Poll with {@link waitForJob} until it finishes.
+* Authenticates with the organization CI API key via `x-api-key`.
+*
+* @example Snapshot job
+* ```ts
+* const job = await createJob({
+*   studioUrl: 'https://kubb.studio',
+*   token: process.env.KUBB_TOKEN!,
+*   type: 'snapshot',
+*   agentId: agent.id,
+*   name: '@kubb/demo',
+*   version: '1.0.0',
+* })
+* const finished = await waitForJob({ studioUrl, token, id: job.id })
+* ```
+*/
+async function createJob({ studioUrl, token, type, agentId, name, version, config }) {
+	const { job } = await ofetch(`${studioUrl}/api/jobs`, {
+		method: "POST",
+		headers: { "x-api-key": token },
+		body: {
+			type,
+			agentId,
+			name,
+			version,
+			config
+		}
+	});
+	return job;
+}
+/**
+* Polls `GET /api/jobs/{id}` until the job reaches `success` or `failed`.
+*
+* 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;
+	for (;;) {
+		const { job } = await ofetch(`${studioUrl}/api/jobs/${id}`, { headers: { "x-api-key": token } });
+		if (job.status === "success" || job.status === "failed") return job;
+		if (Date.now() >= deadline) throw new Error("Timed out waiting for the Studio job");
+		await new Promise((resolve) => setTimeout(resolve, 1e3));
+	}
+}
 //#endregion
 //#region package.json
-var version = "5.2.5";
+var version = "5.2.7";
 //#endregion
 //#region src/hooks.ts
 /**
@@ -1517,6 +1567,9 @@ const CONNECT_TIMEOUT_MS = 5e3;
 */
 const eventSeqCounters = /* @__PURE__ */ new WeakMap();
 const require = createRequire(import.meta.url);
+function relativeStoragePath(root, filePath) {
+	return (isAbsolute(filePath) ? relative(resolve(root), filePath) : filePath).replaceAll("\\", "/");
+}
 async function resolvePeerDependencies(names) {
 	const uniqueNames = [...new Set(names.map(toPackageName))];
 	const peerDependencies = {};
@@ -1571,9 +1624,10 @@ function sendAgentMessage(ws, message) {
 * Sends a single `kubb:error` payload to Studio, stamped from the same per-socket counter the event stream
 * uses so Studio can still order it against the generation events around it.
 */
-function sendErrorMessage(ws, error) {
+function sendErrorMessage(ws, error, jobId) {
 	sendAgentMessage(ws, {
 		type: "agent:data",
+		jobId,
 		payload: {
 			type: "kubb:error",
 			data: [{
@@ -1588,7 +1642,7 @@ function sendErrorMessage(ws, error) {
 /**
 * Forwards selected Kubb lifecycle events to Studio as data messages for the active session.
 */
-function setupEventsStream(ws, hooks) {
+function setupEventsStream(ws, hooks, jobId) {
 	const unhooks = [];
 	/**
 	* Registers a listener and keeps its remover, so one generation's listeners come off the session
@@ -1600,6 +1654,7 @@ function setupEventsStream(ws, hooks) {
 	function sendDataMessage(payload) {
 		sendAgentMessage(ws, {
 			type: "agent:data",
+			jobId,
 			payload: {
 				...payload,
 				timestamp: Date.now(),
@@ -1698,7 +1753,7 @@ function setupEventsStream(ws, hooks) {
 			limit: FILE_READ_CONCURRENCY,
 			run: async (path) => {
 				const content = await storage.readItem(path);
-				if (content !== null) files[path] = content;
+				if (content !== null) files[relativeStoragePath(config.root, path)] = content;
 			}
 		});
 		sendDataMessage({
@@ -1859,6 +1914,7 @@ var StudioSession = class {
 	#session;
 	#ws;
 	#studioVersion;
+	#activeJobId = null;
 	#disposed = false;
 	#isGenerating = false;
 	#heartbeatTimer;
@@ -1906,7 +1962,7 @@ var StudioSession = class {
 			signal?.addEventListener("abort", this.#onAbort, { once: true });
 			this.#unhooks.push(() => signal?.removeEventListener("abort", this.#onAbort));
 			this.#heartbeatTimer = setInterval(() => this.#sendHeartbeat(), heartbeatInterval);
-			this.#unhooks.push(this.#hooks.hook("kubb:error", ({ error }) => sendErrorMessage(ws, error)));
+			this.#unhooks.push(this.#hooks.hook("kubb:error", ({ error }) => sendErrorMessage(ws, error, this.#activeJobId ?? "connection")));
 		} catch (error) {
 			await this.#hooks.callHook("studio:error", { error: toError(error) });
 			if (error instanceof InvalidAgentTokenError) throw error;
@@ -2127,6 +2183,7 @@ var StudioSession = class {
 			return;
 		}
 		this.#isGenerating = true;
+		this.#activeJobId = data.jobId;
 		try {
 			const config = await loadConfig();
 			const patch = data.payload;
@@ -2139,7 +2196,7 @@ 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)];
+			const detach = [setupHookListener(this.#hooks, root), setupEventsStream(ws, this.#hooks, data.jobId)];
 			try {
 				await generate({
 					config: {
@@ -2167,6 +2224,7 @@ var StudioSession = class {
 			});
 		} finally {
 			this.#isGenerating = false;
+			this.#activeJobId = null;
 		}
 	}
 	async #handleSave(ws, data, command) {
@@ -2175,6 +2233,7 @@ var StudioSession = class {
 			await this.#warn("Ignored save: the message carried no edits");
 			sendAgentMessage(ws, {
 				type: "agent:save",
+				jobId: data.jobId,
 				payload: {
 					outcomes: [],
 					changed: false
@@ -2185,6 +2244,7 @@ var StudioSession = class {
 		const edits = data.edits;
 		const refuse = (reason) => sendAgentMessage(ws, {
 			type: "agent:save",
+			jobId: data.jobId,
 			payload: {
 				outcomes: edits.map((edit) => ({
 					edit,
@@ -2208,6 +2268,7 @@ var StudioSession = class {
 			if (changed) await writeFile(configFile, patched, "utf-8");
 			sendAgentMessage(ws, {
 				type: "agent:save",
+				jobId: data.jobId,
 				payload: {
 					outcomes,
 					changed,
@@ -2429,6 +2490,6 @@ async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, sessio
 	throw new Error("The pairing code expired, pair again");
 }
 //#endregion
-export { InvalidAgentTokenError, PairingCanceledError, createClient, createFileStorage, defaultStudioUrl, pollForPairingToken, runConnection, setStorage, startPairing };
+export { InvalidAgentTokenError, PairingCanceledError, createClient, createFileStorage, createJob, createJobId, defaultStudioUrl, pollForPairingToken, runConnection, setStorage, startPairing, waitForJob };
 
 //# sourceMappingURL=index.js.map