@kubb/studio 5.10.1 → 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 { H as SnapshotUploadMetadata, M as PublishedSnapshot, a as AgentConnectInfo, c as ConfigEdit, l as ConfigEditOutcome, o as AgentPermissions, w as InstalledExtensions } from "./protocol-C1PwN9fa.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
 /**
@@ -46,7 +45,7 @@ declare global {
        * 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';
+        command: 'generate' | 'saveConfig' | 'readFiles' | 'readInput' | 'readDiff';
         info: string;
       }];
       /**
@@ -54,7 +53,7 @@ declare global {
        */
       'studio:warn': [ctx: {
         message: string;
-        permission?: keyof AgentPermissions;
+        permission?: AgentPermission;
       }];
       'studio:error': [ctx: {
         error: Error;