@kubb/studio 5.6.0 → 5.6.1

package/dist/index.d.ts

@@ -1,424 +1,126 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
-import { AGENT_INSTANCE_HEADER, AgentApi, AgentCapacity, AgentCloseCode, AgentLoad, AgentPermissions, AgentRegisterInput, AgentRegisterResponse, ConfigEdit, ConnectMessagePayload, GenerateInput, GenerateResult, GenerationEvent, GenerationEventPayloads, GenerationEventType, GenerationRun, PublishSnapshotInput, PublishSnapshotResult, RpcClose, RpcConnection, RpcConnector, StudioApi, generationEventTypes } from "./protocol.js";
-import { Storage } from "unstorage";
+import { F as SnapshotUploadMetadata, a as AgentConnectInfo, k as PublishedSnapshot, o as AgentPermissions } from "./protocol-P0znFp9w.js";
 import { Config, Hookable, KubbHooks } from "@kubb/core";
-//#region src/operations/api.d.ts
+//#region src/connect.d.ts
 /**
- * Thrown when Studio rejects the agent token itself (401). Retrying cannot help: the token was
- * revoked, or the agent it belonged to was deleted in the Studio UI. Hosts catch this to forget
- * the stored credential and pair again.
+ * Studio closed with {@link AgentCloseCode.UNAUTHORIZED}. Hosts forget the token and pair again.
  */
 export declare class InvalidAgentTokenError extends Error {
-  constructor(studioUrl: string, options?: ErrorOptions);
+  constructor(studioUrl: string);
 }
 /**
- * Thrown when Studio refuses this agent's protocol version (426). Retrying cannot help until the
- * agent is upgraded, so hosts stop instead of reconnecting.
+ * Studio closed with {@link AgentCloseCode.INCOMPATIBLE}. Only an upgrade helps.
  */
 export declare class IncompatibleAgentError extends Error {
-  constructor(studioUrl: string, detail?: string, options?: ErrorOptions);
+  constructor({ studioUrl, detail }: {
+    studioUrl: string;
+    detail?: string;
+  });
 }
-/**
- * Status values returned by Studio's jobs API.
- */
-type StudioJobStatus = 'queued' | 'running' | 'success' | 'failed' | 'canceled';
-/** How a snapshot's files differ from an earlier snapshot of the same package, relative to `output.path`. */
-type StudioSnapshotChanges = {
-  /** The snapshot these changes are measured against, `null` when there is none to compare with. */
-  base: {
-    id: string;
-    version: string | null;
-    /** The commit the base snapshot was built from, when reported. */
-    commit?: string;
-    createdAt: string;
-  } | null;
-  added: Array<string>;
-  changed: Array<string>;
-  removed: Array<string>;
-};
-/**
- * `StudioSnapshotChanges` against a pull request's base branch. `baseFound` tells apart the two
- * reasons `base` can be `null`: `false` when no CI agent is registered for the branch yet (the
- * workflow has never run there), `true` when that agent exists but has no snapshot of this package
- * to compare with.
- */
-type StudioBranchSnapshotChanges = StudioSnapshotChanges & {
-  baseFound: boolean;
-};
-/**
- * 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;
-  /** What changed since the previous snapshot on the same agent. Absent when Studio or the agent predates it. */
-  changes?: StudioSnapshotChanges;
-  /** What differs from the latest snapshot of the CI agent `baseId` names. Absent without a base. */
-  branchChanges?: StudioBranchSnapshotChanges;
-};
-/**
- * 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`, `failed`, or `canceled`.
-   */
-  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`.
- *
- * A busy agent, a full queue, or a momentary lack of a live connection (409, 429, 503) retries with
- * exponential backoff and jitter, honoring Studio's `Retry-After` header when it sends one, up to
- * `timeoutMs`. Every other failure, including a missing agent (404), throws immediately.
- *
- * @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, commit, baseId, config, instanceId, timeoutMs, signal }: {
-  studioUrl: string;
-  token: string;
-  type: 'generation' | 'snapshot';
-  agentId: string;
-  name?: string;
-  version?: string;
-  /** The commit this snapshot is built from, so the next one can diff against it. */
-  commit?: string;
-  /** The `id` another CI agent's runs register under, such as the base branch's; this snapshot is also compared with its latest one. */
-  baseId?: string;
-  config?: Record<string, unknown>;
-  /**
-   * The agent process to run the job on, the `instanceId` its client connected with. A CI run passes
-   * its own, so an overlapping pipeline under the same CI agent never builds its checkout.
-   */
-  instanceId?: string;
-  /**
-   * How long to keep retrying a busy or queue-full response before giving up, in milliseconds.
-   *
-   * @default 60000
-   */
-  timeoutMs?: number;
-  signal?: AbortSignal;
-}): Promise<StudioJob>;
-/**
- * Polls `GET /api/jobs/{id}` until the job reaches a terminal status, 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.
- */
-export declare function waitForJob({ studioUrl, token, id, timeoutMs, signal }: {
-  studioUrl: string;
-  token: string;
-  id: string;
-  /**
-   * How long to keep polling before throwing, in milliseconds.
-   *
-   * @default 60000
-   */
-  timeoutMs?: number;
-  signal?: AbortSignal;
-}): Promise<StudioJob>;
-/**
- * CI agent returned by {@link createAgent}. The token is issued only once, at creation or reuse.
- */
-type StudioAgent = {
-  /**
-   * Agent id, passed to {@link createJob} as `agentId`.
-   */
-  id: string;
-  /**
-   * Human-readable slug, used to build the readable snapshot URL and the agent's Studio page.
-   */
-  slug: string;
-  /**
-   * Agent display name.
-   */
-  name: string;
-  /**
-   * Bearer token for the WebSocket agent session. Mask it before logging.
-   */
-  token: string;
-};
-/**
- * Creates or reuses a CI agent (`POST /api/agents`), keyed by `(organization, machineToken)`.
- * Authenticates via `x-api-key`. Reusing the same `machineToken` reuses the same agent instead of
- * consuming a new one from the organization's agent limit.
- */
-export declare function createAgent({ studioUrl, token, name, machineToken }: {
-  studioUrl: string;
-  token: string;
-  name: string;
-  machineToken: string;
-}): Promise<StudioAgent>;
-//#endregion
-//#region src/runtime/StudioSession.d.ts
-type StudioSessionOptions = {
-  connector?: RpcConnector;
-  token: string;
-  studioUrl?: string;
-  configPath: string;
-  /**
-   * Loads the on-disk Kubb config. Injected so each host resolves config its own way: the Docker
-   * agent from an explicit `KUBB_AGENT_CONFIG` path, the CLI through the same discovery
-   * `kubb generate` uses.
-   */
-  loadConfig: () => Promise<Config>;
-  /**
-   * The runtime's own version, reported to Studio next to the `kubb` version.
-   */
-  version: string;
-  /**
-   * What Studio may do in this project, off unless the host grants it. A sandbox session narrows
-   * them further: it never writes to disk and never edits a config file, and it always generates
-   * from the spec Studio sends.
-   */
-  permissions?: Partial<AgentPermissions>;
-  root?: string;
-  /**
-   * Maximum reconnect backoff in milliseconds.
-   */
-  retryInterval?: number;
-  /**
-   * Milliseconds between keep-alive pings, clamped to `agentDefaults.maxHeartbeatIntervalMs`.
-   * Raise it to halve the traffic and database writes a long-lived agent costs, at the price of
-   * Studio taking that much longer to notice the agent has gone. Lower it in development to see
-   * connection state move immediately.
-   */
-  heartbeatInterval?: number;
-  /**
-   * What this agent process can take on, reported to Studio at registration. Unset fields come from
-   * `KUBB_AGENT_MAX_CONCURRENT`.
-   */
-  capacity?: Partial<AgentCapacity>;
-  /**
-   * Names this agent process to Studio, sent at registration and as {@link AGENT_INSTANCE_HEADER}
-   * on the socket. `runConnection` sets one per process, so a reconnect is the same instance and a
-   * restart is a new one. Not meant to be set directly by a host.
-   */
-  instanceId?: string;
-  /**
-   * Aborting this disconnects the session and stops the reconnect loop. Hosts wire it to their own
-   * shutdown signal, usually `SIGINT` or `SIGTERM`.
-   */
-  signal?: AbortSignal;
-  /**
-   * Installs listeners on the session's event emitter, which carries both the session events and
-   * the generations it runs. Left out, the runtime prints nothing, which is what a library should
-   * default to.
-   */
-  installLogger?: (hooks: Hookable<KubbHooks>) => void | Promise<void>;
-};
-//#endregion
-//#region src/runtime/client.d.ts
-type ClientOptions = Omit<StudioSessionOptions, 'signal'> & {
-  /** Called once when a background reconnect rejects the credential. */
-  onAuthRequired?: (error: InvalidAgentTokenError) => void;
-};
-type Client = {
-  connect: () => Promise<void>;
-  disconnect: () => void;
-};
-/** Compatibility facade over the shared connection loop. */
-export declare function createClient({ onAuthRequired, ...options }: ClientOptions): Client;
-//#endregion
-//#region src/operations/hooks.d.ts
-type StudioConnectedContext = {
-  /**
-   * The Studio instance this session attached to.
-   */
+type StudioConnectedContext = AgentConnectInfo & {
   url: string;
   /**
-   * Both sides of the connection, so a host can print them and make a mismatch visible.
+   * The Studio, runtime, and host versions, so a host can show a mismatch.
    */
   versions: {
-    /**
-     * The Studio instance's own version, when it sent one.
-     */
-    studio?: string;
-    /**
-     * The version of the runtime that connected.
-     */
+    studio: string;
     kubb: string;
-    /**
-     * The version of the host itself, such as the `kubb` CLI or the agent image.
-     */
     agent: string;
   };
-  /**
-   * This agent's slug, refreshed on every connect so a rename in Studio shows up without a
-   * re-pair. Absent when Studio predates the field.
-   */
-  agentSlug?: string;
-  /**
-   * This agent's organization slug, absent for a sandbox or global agent, which has none, or when
-   * Studio predates the field.
-   */
-  organizationSlug?: string;
 };
-/**
- * Events a host emits about its Kubb Studio session, as opposed to a generation. `kubb:` stays
- * reserved for generation lifecycle.
- */
 declare global {
   namespace Kubb {
     interface KubbHooksRegistry {
       /**
-       * The Studio instance this session is opening against.
+       * Fired after each handshake, including reconnects.
        */
-      'studio:connecting': [ctx: {
-        url: string;
-      }];
       'studio:connected': [ctx: StudioConnectedContext];
-      /**
-       * Fired once Studio confirms the `agent:connect` handshake was received and the session is
-       * fully registered. Distinct from `studio:connected`, which only means the socket is open.
-       */
-      'studio:ready': [ctx: Record<string, never>];
-      /**
-       * Why Studio ended the session.
-       */
       'studio:disconnected': [ctx: {
+        code: number;
         reason: string;
       }];
-      /**
-       * Milliseconds until the next connection attempt.
-       */
       'studio:reconnecting': [ctx: {
         delayMs: number;
       }];
       /**
-       * The command Studio sent, without its `studio:` prefix: `generate`, `connect` or `save`.
+       * A finished command and what it did, such as `applied 2/3 edits to kubb.config.ts`.
        */
-      'studio:command:start': [ctx: {
-        command: string;
+      'studio:command': [ctx: {
+        command: 'generate' | 'saveConfig' | 'readFiles';
+        info: string;
       }];
       /**
-       * The command that finished, with what it did when there is something to report:
-       * `applied 2/3 edits to kubb.config.ts`.
-       */
-      'studio:command:end': [ctx: {
-        command: string;
-        info?: string;
-      }];
-      /**
-       * What was refused or ignored, and the missing permission if that is why, so the host can
-       * append its own remedy.
+       * A refused or ignored request, with the missing permission so the host can add a remedy.
        */
       'studio:warn': [ctx: {
         message: string;
         permission?: keyof AgentPermissions;
       }];
-      /**
-       * The failure, for the host's own output. One Studio needs to hear about goes over the
-       * socket through the `kubb:error` generation hook instead.
-       */
       'studio:error': [ctx: {
         error: Error;
       }];
     }
   }
 }
-//#endregion
-//#region src/operations/constants.d.ts
-/**
- * Hosted Kubb Studio URL. Exported so credential stores can bind tokens to the resolved instance,
- * not whatever default the client would pick on its own.
- */
-export declare const defaultStudioUrl = "https://kubb.studio";
-//#endregion
-//#region src/operations/machine.d.ts
-/**
- * Installs the storage driver the runtime persists to. Call once, before connecting.
- */
-export declare function setStorage(next: Storage): void;
-/**
- * A storage backed by files under `base`, so the machine secret and the last Studio config
- * survive a restart. Repeated pairings of one machine depend on that secret staying put.
- */
-export declare function createFileStorage(base: string): Storage;
-/**
- * Hashes a stable secret into the machine token Studio expects, so a host can derive one from its
- * own identity without duplicating `getMachineToken`'s SHA-256 step.
- */
-export declare function machineTokenFrom(secret: string): string;
-//#endregion
-//#region src/runtime/runConnection.d.ts
-type ConnectionOutcome = 'shutdown' | 'stopped';
-type TokenRejection<TCredentials> = {
-  error: InvalidAgentTokenError;
-  credentials: TCredentials;
-  /** Whether this credential already served a ready session. */
-  live: boolean;
-};
-type ConnectionOptions<TCredentials extends {
+type ConnectAgentOptions = {
+  /**
+   * The agent's bearer token, from {@link pairAgent}.
+   */
   token: string;
-}> = {
-  credentials: TCredentials;
-  clientOptions: (credentials: TCredentials) => Omit<StudioSessionOptions, 'token' | 'signal'>;
-  onTokenRejected: (rejection: TokenRejection<TCredentials>) => Promise<TCredentials | null>;
+  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;
-  /** Used by the client facade once startup succeeds or schedules its first retry. */
-  onStarted?: () => void;
+  /**
+   * Longest wait between reconnect attempts, in milliseconds.
+   * @default 30000
+   */
+  maxRetryDelay?: number;
+  /**
+   * Milliseconds between keep-alive pings, at most 60000.
+   * @default 30000
+   */
+  heartbeatInterval?: number;
 };
-/** Runs the process's one connection loop, including retries and credential replacement. */
-export declare function runConnection<TCredentials extends {
-  token: string;
-}>({ credentials, clientOptions, onTokenRejected, signal, onStarted }: ConnectionOptions<TCredentials>): Promise<ConnectionOutcome>;
+/**
+ * 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/operations/pair.d.ts
+//#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.
@@ -485,38 +187,15 @@ type StartPairingOptions = {
   name: string;
   hostname: string;
   /**
-   * Aborting this cancels the request in flight and rejects with {@link PairingCanceledError}.
+   * 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.
    */
-  signal?: AbortSignal;
-};
-/**
- * Asks Studio for a pairing code. The machine token travels with the request and is stored against
- * the code, so approval knows which machine it is pairing: the same machine pairing twice rotates
- * one agent's token instead of creating a second agent.
- */
-export declare function startPairing({ studioUrl, type, name, hostname, signal }: StartPairingOptions): Promise<PairingSession>;
-type PollOptions = {
-  studioUrl?: string;
-  session: PairingSession;
+  machineId: string;
   /**
-   * Aborting this stops polling and rejects with {@link PairingCanceledError}, whether the abort
-   * lands between polls or during the wait for the next one.
+   * Aborting this cancels the request in flight and rejects with {@link PairingCanceledError}.
    */
   signal?: AbortSignal;
-  /** Called when a poll could not reach Studio. Polling carries on. */
-  onRetry?: (error: Error) => void;
 };
-/**
- * Polls until the user approves or denies, honoring the server's `slow_down` back-off.
- *
- * Studio's own endpoint is used rather than the auth layer's `/device/token`, because an approved
- * Kubb pairing is worth an agent bearer token, not a user session.
- *
- * @throws {PairingExpiredError} when the code expires before anyone approves it.
- * @throws {PairingDeniedError} when the pairing is denied in the browser.
- * @throws {PairingCanceledError} when `signal` aborts.
- */
-export declare function pollForPairingToken({ studioUrl, session, signal, onRetry }: PollOptions): Promise<PairingResult>;
 type PairAgentOptions = StartPairingOptions & {
   /** Shows the code to whoever approves it. Called again for each fresh code. */
   onCode: (session: PairingSession, attempt: number) => void | Promise<void>;
@@ -533,18 +212,45 @@ type PairAgentOptions = StartPairingOptions & {
  */
 export declare function pairAgent({ onCode, onRetry, maxAttempts, ...options }: PairAgentOptions): Promise<PairingResult>;
 //#endregion
-//#region src/operations/rpc.d.ts
+//#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. Like `kubb generate`, it writes to `output.path`, then runs the
+   * formatter, the linter, and `output.postGenerate`.
+   */
+  config: Config;
+  hooks?: Hookable<KubbHooks>;
+  signal?: AbortSignal;
+};
 /**
- * Opens an authenticated Cap'n Web session to Studio over a WebSocket. Rejects an unencrypted URL
- * before opening the socket, so a bearer token never reaches a plaintext host.
+ * Generates the project, packs it as an npm tarball, and publishes it to Studio in one
+ * `POST /api/snapshots` request.
  *
  * @example
  * ```ts
- * const rpc = await connectWebSocketRpc({ url: 'wss://studio.kubb.dev/s/1', token, local: session })
- * await rpc.studio.ping()
+ * const snapshot = await createSnapshot({
+ *   apiKey: process.env.KUBB_TOKEN!,
+ *   config,
+ *   id: 'gh:123:pr-4',
+ *   name: 'acme/api#4',
+ *   packageName: '@acme/api',
+ *   version: '1.0.0',
+ * })
+ * console.log(snapshot.url, snapshot.changes)
  * ```
  */
-export declare const connectWebSocketRpc: RpcConnector;
+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
-export { AGENT_INSTANCE_HEADER, type AgentApi, type AgentCapacity, AgentCloseCode, type AgentLoad, type AgentRegisterInput, type AgentRegisterResponse, type Client, type ClientOptions, type ConfigEdit, type ConnectMessagePayload, type ConnectionOptions, type GenerateInput, type GenerateResult, type GenerationEvent, type GenerationEventPayloads, type GenerationEventType, type GenerationRun, type PairingAgentType, type PairingResult, type PairingSession, type PublishSnapshotInput, type PublishSnapshotResult, type RpcClose, type RpcConnection, type RpcConnector, type StudioAgent, type StudioApi, type StudioBranchSnapshotChanges, type StudioConnectedContext, type StudioJob, type StudioJobStatus, type StudioSnapshot, type StudioSnapshotChanges, generationEventTypes };
+export type { ConnectAgentOptions, StudioConnectedContext };
 //# sourceMappingURL=index.d.ts.map