@kubb/studio 5.10.2 → 5.10.3

package/dist/index.d.cts

@@ -0,0 +1,260 @@
+import { D as InstalledExtensions, P as PublishedSnapshot, W as SnapshotUploadMetadata, a as AgentConnectInfo, c as AgentPermissions, d as ConfigEditOutcome, s as AgentPermission, u as ConfigEdit } from "./protocol-CrMJymjT.cjs";
+import { Config, Hookable, KubbHooks } from "@kubb/core";
+//#region src/connect.d.ts
+/**
+ * Studio closed with {@link AgentCloseCode.UNAUTHORIZED}. Hosts forget the token and pair again.
+ */
+export declare class InvalidAgentTokenError extends Error {
+  constructor(studioUrl: string);
+}
+/**
+ * Studio closed with {@link AgentCloseCode.INCOMPATIBLE}. Only an upgrade helps.
+ */
+export declare class IncompatibleAgentError extends Error {
+  constructor({ studioUrl, detail }: {
+    studioUrl: string;
+    detail?: string;
+  });
+}
+type StudioConnectedContext = AgentConnectInfo & {
+  url: string;
+  /**
+   * The Studio, runtime, and host versions, so a host can show a mismatch.
+   */
+  versions: {
+    studio: string;
+    kubb: string;
+    agent: string;
+  };
+};
+declare global {
+  namespace Kubb {
+    interface KubbHooksRegistry {
+      /**
+       * Fired after each handshake, including reconnects.
+       */
+      'studio:connected': [ctx: StudioConnectedContext];
+      'studio:disconnected': [ctx: {
+        code: number;
+        reason: string;
+      }];
+      'studio:reconnecting': [ctx: {
+        delayMs: number;
+      }];
+      /**
+       * A finished command and what it did, such as `applied 2/3 edits to kubb.config.ts`.
+       */
+      'studio:command': [ctx: {
+        command: 'generate' | 'saveConfig' | 'readFiles' | 'readInput' | 'readDiff';
+        info: string;
+      }];
+      /**
+       * A refused or ignored request, with the missing permission so the host can add a remedy.
+       */
+      'studio:warn': [ctx: {
+        message: string;
+        permission?: AgentPermission;
+      }];
+      'studio:error': [ctx: {
+        error: Error;
+      }];
+    }
+  }
+}
+type ConnectAgentOptions = {
+  /**
+   * The agent's bearer token, from {@link pairAgent}.
+   */
+  token: string;
+  studioUrl?: string;
+  /**
+   * The config path shown in Studio, relative to `root` unless absolute.
+   */
+  configPath: string;
+  /**
+   * Called for every handshake and every generation, so edits on disk show up.
+   */
+  loadConfig: () => Promise<Config>;
+  /**
+   * The host's own version, reported to Studio next to the runtime's.
+   */
+  version: string;
+  /**
+   * The project root generation runs against.
+   * @default process.cwd()
+   */
+  root?: string;
+  /**
+   * What Studio may do in this project. Every permission is off unless granted.
+   */
+  permissions?: Partial<AgentPermissions>;
+  /**
+   * Receives the `studio:*` hooks and the `kubb:*` hooks of every generation.
+   */
+  hooks?: Hookable<KubbHooks>;
+  signal?: AbortSignal;
+  /**
+   * Longest wait between reconnect attempts, in milliseconds.
+   * @default 30000
+   */
+  maxRetryDelay?: number;
+  /**
+   * Milliseconds between keep-alive pings, at most 60000.
+   * @default 30000
+   */
+  heartbeatInterval?: number;
+};
+/**
+ * Connects this project to Kubb Studio and serves its commands until `signal` aborts. Reconnects
+ * with jittered backoff, and resolves when another process of the agent takes over. Rejects with
+ * {@link InvalidAgentTokenError} so the host can pair again, or {@link IncompatibleAgentError}.
+ *
+ * @example
+ * ```ts
+ * const hooks = new Hookable<KubbHooks>()
+ * hooks.hook('studio:connected', ({ agentSlug }) => console.log(`Connected as ${agentSlug}`))
+ *
+ * await connectAgent({ token, configPath: 'kubb.config.ts', loadConfig, version: '1.0.0', hooks, signal })
+ * ```
+ */
+export declare function connectAgent(options: ConnectAgentOptions): Promise<void>;
+//#endregion
+//#region src/pair.d.ts
+/**
+ * RFC 8628 device-authorization response from Studio's `/api/auth/device/code` endpoint.
+ * Field names match the RFC; the CLI polls with `device_code` and shows `user_code` to the user.
+ */
+type PairingSession = {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  verification_uri_complete: string;
+  expires_in: number;
+  interval: number;
+};
+type PairingResult = {
+  /**
+   * Bearer token for this machine. Write credentials with mode 0600 and never log the value.
+   */
+  token: string;
+  agent: {
+    /**
+     * Stable agent id in Studio.
+     */
+    id: string;
+    /**
+     * Short slug used in logs and the UI (for example `brave-otter`).
+     */
+    slug: string;
+    /**
+     * Display name chosen at pairing time.
+     */
+    name: string;
+    /**
+     * This agent's organization slug, absent for a sandbox or global agent, which has none.
+     */
+    organizationSlug?: string;
+  };
+};
+/**
+ * What this machine registers as. Any member may approve `cli` (`kubb studio`); only an admin may
+ * approve `user` and `sandbox` (the Docker image). A `ci` agent never pairs.
+ */
+type PairingAgentType = 'cli' | 'user' | 'sandbox';
+/**
+ * Thrown when a caller aborts `startPairing` or `pollForPairingToken` through their `signal`, such
+ * as a `kubb studio` shutdown mid-pairing. Distinct from a denial or an expired code, so a host can
+ * exit quietly instead of reporting a pairing failure.
+ */
+export declare class PairingCanceledError extends Error {
+  constructor();
+}
+/** Thrown when the code expired unapproved. A fresh code can still succeed. */
+export declare class PairingExpiredError extends Error {
+  constructor(message?: string);
+}
+/** Thrown when the pairing was denied in the browser, including by the organization's agent limit. */
+export declare class PairingDeniedError extends Error {
+  constructor(message?: string);
+}
+type StartPairingOptions = {
+  studioUrl?: string;
+  type: PairingAgentType;
+  /**
+   * Display name for the agent, usually the project or machine name.
+   */
+  name: string;
+  hostname: string;
+  /**
+   * A stable secret the host keeps for this machine. Studio stores its hash against the agent, so
+   * the same machine pairing again rotates one agent's token instead of creating a second agent.
+   */
+  machineId: string;
+  /**
+   * Aborting this cancels the request in flight and rejects with {@link PairingCanceledError}.
+   */
+  signal?: AbortSignal;
+};
+type PairAgentOptions = StartPairingOptions & {
+  /** Shows the code to whoever approves it. Called again for each fresh code. */
+  onCode: (session: PairingSession, attempt: number) => void | Promise<void>;
+  /** Called when a poll could not reach Studio. Polling carries on. */
+  onRetry?: (error: Error) => void;
+  /**
+   * Codes to ask for in total when one expires unapproved. A denial or abort ends it at once.
+   * @default 1
+   */
+  maxAttempts?: number;
+};
+/**
+ * Pairs this machine with Studio: asks for a code, hands it to the host to show, and waits for approval.
+ */
+export declare function pairAgent({ onCode, onRetry, maxAttempts, ...options }: PairAgentOptions): Promise<PairingResult>;
+//#endregion
+//#region src/snapshot.d.ts
+type CreateSnapshotOptions = Omit<SnapshotUploadMetadata, 'hashes' | 'peerDependencies'> & {
+  studioUrl?: string;
+  /**
+   * Organization CI API key, sent as `x-api-key`.
+   */
+  apiKey: string;
+  /**
+   * The project's Kubb config, generated like `kubb generate`: formatter, linter, and `output.postGenerate` included.
+   */
+  config: Config;
+  hooks?: Hookable<KubbHooks>;
+  signal?: AbortSignal;
+};
+/**
+ * Generates the project, packs it as an npm tarball, and publishes it to Studio in one `POST /api/snapshots` request.
+ *
+ * @example
+ * ```ts
+ * const { url } = await createSnapshot({ apiKey: process.env.KUBB_TOKEN!, config, id: 'gh:123:pr-4', name: 'acme/api#4', packageName: '@acme/api', version: '1.0.0' })
+ * ```
+ */
+export declare function createSnapshot({ studioUrl, apiKey, config, hooks, signal, ...metadata }: CreateSnapshotOptions): Promise<PublishedSnapshot>;
+//#endregion
+//#region src/url.d.ts
+/**
+ * Hosted Kubb Studio URL, used when a host passes none.
+ */
+export declare const defaultStudioUrl = "https://kubb.studio";
+//#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, StudioConnectedContext };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
-import { E as InstalledExtensions, N as PublishedSnapshot, U as SnapshotUploadMetadata, a as AgentConnectInfo, c as AgentPermissions, d as ConfigEditOutcome, s as AgentPermission, u as ConfigEdit } from "./protocol-DQfI1aLV.js";
+import { D as InstalledExtensions, P as PublishedSnapshot, W as SnapshotUploadMetadata, a as AgentConnectInfo, c as AgentPermissions, d as ConfigEditOutcome, s as AgentPermission, u as ConfigEdit } from "./protocol-CrMJymjT.js";
 import { Config, Hookable, KubbHooks } from "@kubb/core";
 //#region src/connect.d.ts
 /**

package/dist/index.js

@@ -1,4 +1,3 @@
-import "./rolldown-runtime-CRm0XQPb.js";
 import { AGENT_INSTANCE_HEADER, AGENT_SOCKET_PATH, AgentCloseCode, AgentMessage, AgentPermission, FileSource, MAX_PAGE_LINES, MAX_SNAPSHOT_BYTES, generationEventTypes } from "./protocol.js";
 import { createRequire } from "node:module";
 import { createHash, hash, randomUUID } from "node:crypto";
@@ -17,6 +16,7 @@ import { stripVTControlCharacters } from "node:util";
 import { ast } from "@kubb/ast";
 import { ofetch } from "ofetch";
 import { gzipSync } from "node:zlib";
+//#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
 * Shared implementation for camelCase and PascalCase conversion.
@@ -154,7 +154,7 @@ function getElapsedMs(hrStart) {
 }
 //#endregion
 //#region package.json
-var version = "5.10.2";
+var version = "5.10.3";
 //#endregion
 //#region src/resolveConfig.ts
 /**
@@ -1155,33 +1155,154 @@ async function writeConfigEdits({ filePath, edits, extensions }) {
 //#endregion
 //#region src/diff.ts
 const CONTEXT_LINES = 3;
-const DIFF_TIMEOUT_MS = 1e4;
-function diffHunks(before, after) {
-	return new Promise((resolve) => {
-		structuredPatch("", "", before, after, void 0, void 0, {
+const DIFF_TIMEOUT_MS = 1e3;
+const splitLines = (text) => text === "" ? [] : text.split(/(?<=\n)/);
+function longestIncreasing(values) {
+	const tails = [];
+	const prev = [];
+	for (const [index, value] of values.entries()) {
+		let low = 0;
+		let high = tails.length;
+		while (low < high) {
+			const mid = low + high >> 1;
+			if (values[tails[mid]] < value) low = mid + 1;
+			else high = mid;
+		}
+		prev[index] = low > 0 ? tails[low - 1] : -1;
+		tails[low] = index;
+	}
+	const result = [];
+	for (let index = tails.at(-1) ?? -1; index !== -1; index = prev[index]) result.push(index);
+	return result.reverse();
+}
+function cutPoints(before, after) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const [index, line] of before.entries()) {
+		const count = counts.get(line);
+		if (count) count.before++;
+		else counts.set(line, {
+			before: 1,
+			after: 0,
+			index
+		});
+	}
+	const afterIndex = /* @__PURE__ */ new Map();
+	for (const [index, line] of after.entries()) {
+		const count = counts.get(line);
+		if (!count) continue;
+		count.after++;
+		afterIndex.set(line, index);
+	}
+	const unique = [...counts].filter(([, count]) => count.before === 1 && count.after === 1).map(([line, count]) => [count.index, afterIndex.get(line)]);
+	const anchors = longestIncreasing(unique.map(([, index]) => index)).map((index) => unique[index]);
+	const cuts = [[0, 0]];
+	let run = {
+		before: 0,
+		after: 0,
+		length: 0
+	};
+	const closeRun = () => {
+		if (run.length > 6) cuts.push([run.before + CONTEXT_LINES, run.after + CONTEXT_LINES]);
+	};
+	let i = 0;
+	let j = 0;
+	for (const [anchorBefore, anchorAfter] of anchors) {
+		const unchanged = anchorBefore - i === anchorAfter - j && before.slice(i, anchorBefore).every((line, offset) => line === after[j + offset]);
+		if (unchanged && run.length && run.before + run.length === i) run.length += anchorBefore - i + 1;
+		else {
+			closeRun();
+			run = unchanged ? {
+				before: i,
+				after: j,
+				length: anchorBefore - i + 1
+			} : {
+				before: anchorBefore,
+				after: anchorAfter,
+				length: 1
+			};
+		}
+		i = anchorBefore + 1;
+		j = anchorAfter + 1;
+	}
+	closeRun();
+	cuts.push([before.length, after.length]);
+	return cuts;
+}
+function replaceHunk(before, after) {
+	let start = 0;
+	while (start < before.length && start < after.length && before[start] === after[start]) start++;
+	let end = 0;
+	while (end < before.length - start && end < after.length - start && before[before.length - 1 - end] === after[after.length - 1 - end]) end++;
+	const removed = before.slice(start, before.length - end);
+	const added = after.slice(start, after.length - end);
+	if (!removed.length && !added.length) return [];
+	const lines = (prefix, rows) => rows.flatMap((row) => row.endsWith("\n") ? [`${prefix}${row.slice(0, -1)}`] : [`${prefix}${row}`, "\"]);
+	return [{
+		oldStart: start + 1,
+		oldLines: removed.length,
+		newStart: start + 1,
+		newLines: added.length,
+		lines: [...lines("-", removed), ...lines("+", added)]
+	}];
+}
+function diffHunks(before, after, timeout = DIFF_TIMEOUT_MS) {
+	const beforeLines = splitLines(before);
+	const afterLines = splitLines(after);
+	const cuts = cutPoints(beforeLines, afterLines);
+	const deadline = Date.now() + timeout;
+	const hunks = [];
+	let coarse = false;
+	for (const [index, [beforeStart, afterStart]] of cuts.slice(0, -1).entries()) {
+		const [beforeEnd, afterEnd] = cuts[index + 1];
+		const segmentBefore = beforeLines.slice(beforeStart, beforeEnd);
+		const segmentAfter = afterLines.slice(afterStart, afterEnd);
+		const patch = structuredPatch("", "", segmentBefore.join(""), segmentAfter.join(""), void 0, void 0, {
 			context: CONTEXT_LINES,
-			timeout: DIFF_TIMEOUT_MS,
-			callback: (patch) => resolve(patch?.hunks)
+			timeout: Math.max(0, deadline - Date.now())
 		});
-	});
+		if (!patch) coarse = true;
+		for (const hunk of patch?.hunks ?? replaceHunk(segmentBefore, segmentAfter)) hunks.push({
+			...hunk,
+			oldStart: hunk.oldStart + beforeStart,
+			newStart: hunk.newStart + afterStart
+		});
+	}
+	const lines = hunks.flatMap((hunk) => hunk.lines);
+	return {
+		hunks,
+		stats: {
+			additions: lines.filter((line) => line[0] === "+").length,
+			deletions: lines.filter((line) => line[0] === "-").length,
+			hunks: hunks.length,
+			lines: lines.length,
+			coarse
+		}
+	};
 }
 function pageHunks({ hunks, cursor, limit }) {
 	const page = [];
-	const end = cursor + limit;
+	let used = 0;
 	let start = 0;
 	for (const [index, hunk] of hunks.entries()) {
-		const next = start + hunk.lines.length;
-		if (next > cursor && start < end) page.push({
+		const offset = Math.max(0, cursor - start);
+		start += hunk.lines.length;
+		const remaining = hunk.lines.length - offset;
+		if (remaining <= 0) continue;
+		if (used > 0 && remaining > limit - used) break;
+		let take = Math.min(remaining, limit - used);
+		if (hunk.lines[offset + take]?.startsWith("\\")) take++;
+		page.push({
 			index,
-			oldStart: hunk.oldStart,
-			newStart: hunk.newStart,
-			lines: hunk.lines.slice(Math.max(0, cursor - start), end - start)
+			...hunk,
+			lines: hunk.lines.slice(offset, offset + take)
 		});
-		start = next;
+		used += take;
+		if (used >= limit) break;
 	}
+	const total = hunks.reduce((sum, hunk) => sum + hunk.lines.length, 0);
 	return {
 		hunks: page,
-		nextCursor: end < start ? end : null
+		nextCursor: cursor + used < total ? cursor + used : null
 	};
 }
 //#endregion
@@ -1417,7 +1538,7 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 //#region src/generationEvents.ts
 const MAX_QUEUED_EVENTS = 1024;
 const RESERVED_EVENTS = 64;
-const isDiscardable = (event) => event.type === "kubb:files:processing:update" || event.type === "kubb:info" || event.type === "kubb:success";
+const isDiscardable = (type) => type === "kubb:files:processing:update" || type === "kubb:info" || type === "kubb:success";
 /** Forwards selected Kubb lifecycle events to a native Cap'n Web stream. */
 function createGenerationStream(hooks, jobId) {
 	const unhooks = [];
@@ -1449,7 +1570,7 @@ function createGenerationStream(hooks, jobId) {
 			version: 1,
 			timestamp: Date.now()
 		};
-		if (controller.desiredSize <= RESERVED_EVENTS && isDiscardable(event)) return;
+		if (controller.desiredSize <= RESERVED_EVENTS && isDiscardable(type)) return;
 		if (controller.desiredSize <= 0) {
 			fail(/* @__PURE__ */ new Error(`Generation event stream exceeded ${MAX_QUEUED_EVENTS} queued events`));
 			return;
@@ -1553,7 +1674,10 @@ function createGenerationStream(hooks, jobId) {
 		}]
 	};
 	function forward(type) {
-		on(type, (...args) => emitEvent(type, projections[type](...args)));
+		on(type, (...args) => {
+			emitEvent(type, projections[type](...args));
+			if (!isDiscardable(type)) return new Promise((resolve) => setImmediate(resolve));
+		});
 	}
 	on("kubb:build:start", ({ config }) => {
 		root = config.root;
@@ -2063,7 +2187,14 @@ var Agent = class extends RpcTarget {
 		if (beforeContent === void 0) return {
 			hunks: [],
 			nextCursor: null,
-			hasBase: false
+			hasBase: false,
+			stats: {
+				additions: 0,
+				deletions: 0,
+				hunks: 0,
+				lines: 0,
+				coarse: false
+			}
 		};
 		const key = JSON.stringify([
 			jobId,
@@ -2071,25 +2202,21 @@ var Agent = class extends RpcTarget {
 			baseSource,
 			path
 		]);
-		let hunks = this.#diffs.get(key);
-		if (!hunks) {
-			hunks = diffHunks(beforeContent, afterContent ?? "");
-			this.#diffs.set(key, hunks);
+		let diff = this.#diffs.get(key);
+		if (!diff) {
+			diff = diffHunks(beforeContent, afterContent ?? "");
+			this.#diffs.set(key, diff);
 			if (this.#diffs.size > 4) this.#diffs.delete(this.#diffs.keys().next().value);
 		}
-		const all = await hunks;
-		if (!all) {
-			this.#diffs.delete(key);
-			return this.#refuse({ message: "The two versions differ too much to diff" });
-		}
 		await this.#logCommand("readDiff", `read the diff of ${path}`);
 		return {
 			...pageHunks({
-				hunks: all,
+				hunks: diff.hunks,
 				cursor,
 				limit
 			}),
-			hasBase: true
+			hasBase: true,
+			stats: diff.stats
 		};
 	}
 };