@kubb/studio 5.1.0 → 5.2.1

package/dist/index.d.ts

@@ -1,9 +1,19 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
-import { s as ClientInfo } from "./index-BVn89Nw2.js";
+import { a as AgentPermissions, c as ClientInfo } from "./index-Y-wkaxbL.js";
 import { Storage } from "unstorage";
 import { Config, Hookable, KubbHooks } from "@kubb/core";
-//#region src/connectStudio.d.ts
-type ConnectToStudioOptions = {
+//#region src/api.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.
+ */
+export declare class InvalidAgentTokenError extends Error {
+  constructor(studioUrl: string, options?: ErrorOptions);
+}
+//#endregion
+//#region src/StudioSession.d.ts
+type StudioSessionOptions = {
   token: string;
   studioUrl?: string;
   configPath: string;
@@ -21,25 +31,24 @@ type ConnectToStudioOptions = {
    * Identifies the host to Studio, so the UI can badge a CLI connection and show the real project.
    */
   client?: ClientInfo;
-  allowWrite?: boolean;
-  /**
-   * Whether Studio may edit the project's `kubb.config.ts`. Granted separately from `allowWrite`,
-   * which only covers generated output: this rewrites a file the user wrote by hand.
-   */
-  allowConfigEdit?: boolean;
-  allowInput?: boolean;
   /**
-   * Whether the formatter, the linter, and `output.postGenerate` may run as child processes.
-   * Defaults to true, which is what the Docker agent has always done. The CLI runs in the user's
-   * own project, so it defaults this off and asks before granting it.
+   * 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.
    */
-  allowExec?: boolean;
+  permissions?: Partial<AgentPermissions>;
   root?: string;
   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;
   /**
    * Number of pool sessions this agent serves. Read by `createClient`, which opens one
-   * `connectToStudio` per slot, and reported to Studio at registration.
+   * session per slot, and reported to Studio at registration.
    */
   poolSize?: number;
   /**
@@ -48,19 +57,36 @@ type ConnectToStudioOptions = {
    */
   signal?: AbortSignal;
   /**
-   * Installs listeners on an event emitter, once for the session and once per generation. Left out,
-   * the runtime prints nothing, which is what a library should default to.
+   * 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>;
+  /**
+   * 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:
+   * `createClient` wraps it into that deduped, pool-stopping callback. Not meant to be set
+   * directly by a host.
+   */
+  onTokenRejected?: (error: InvalidAgentTokenError) => void;
 };
 //#endregion
 //#region src/client.d.ts
-type ClientOptions = Omit<ConnectToStudioOptions, 'signal'> & {
+type ClientOptions = Omit<StudioSessionOptions, 'signal' | 'onTokenRejected'> & {
   /**
    * Where the machine secret and the last Studio config are persisted. Defaults to in-memory,
    * which gives up a stable machine identity across restarts.
    */
   storage?: Storage;
+  /**
+   * Called once when a live pool's token is rejected during background reconnect (401: revoked, or
+   * the agent was deleted). The whole pool is already stopped by the time this fires, so a host
+   * only needs to get a replacement token and start a new client.
+   *
+   * Never fires for a startup rejection, which `connect()` reports by throwing, nor for an ordinary
+   * session expiry or revocation, both of which reconnect on their own.
+   */
+  onAuthRequired?: (error: InvalidAgentTokenError) => void;
 };
 type Client = {
   /**
@@ -85,7 +111,7 @@ type Client = {
  * await studio.connect()
  * ```
  */
-declare function createClient({ storage, ...options }: ClientOptions): Client;
+export declare function createClient({ storage, onAuthRequired, ...options }: ClientOptions): Client;
 //#endregion
 //#region src/hooks.d.ts
 /**
@@ -170,33 +196,91 @@ declare global {
   }
 }
 //#endregion
-//#region src/api.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.
- */
-declare class InvalidAgentTokenError extends Error {
-  constructor(studioUrl: string, options?: ErrorOptions);
-}
-//#endregion
 //#region src/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.
  */
-declare const defaultStudioUrl = "https://kubb.studio";
+export declare const defaultStudioUrl = "https://kubb.studio";
 //#endregion
 //#region src/machine.d.ts
 /**
  * Installs the storage driver the runtime persists to. Call once, before connecting.
  */
-declare function setStorage(next: Storage): void;
+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.
  */
-declare function createFileStorage(base: string): Storage;
+export declare function createFileStorage(base: string): Storage;
+//#endregion
+//#region src/runConnection.d.ts
+/**
+ * Why a connection ended: the host asked it to stop through its `signal`, or the host declined to
+ * replace a rejected token.
+ */
+type ConnectionOutcome = 'shutdown' | 'stopped';
+/**
+ * A rejected token, and whether it was already serving a live session when Studio rejected it.
+ */
+type TokenRejection<TCredentials> = {
+  error: InvalidAgentTokenError;
+  /**
+   * The credential Studio rejected, so a host can carry parts of it into the replacement.
+   */
+  credentials: TCredentials;
+  /**
+   * `false` when the token was dead before a session ever opened, which is what `connect()` itself
+   * reports. `true` when a live pool's background reconnect was rejected, well after the session
+   * was up. Hosts treat the two differently: only the first has nothing to tear down.
+   */
+  live: boolean;
+};
+type ConnectionOptions<TCredentials extends {
+  token: string;
+}> = {
+  /**
+   * The credential to open with. Only its token is read here, so a host keeps whatever else it
+   * stores alongside.
+   */
+  credentials: TCredentials;
+  /**
+   * Builds the client options for one attempt. Called again for every reconnect, so a host whose
+   * options depend on which agent approved, such as the permissions it granted, re-derives them
+   * rather than reusing the ones the rejected token was opened with.
+   */
+  clientOptions: (credentials: TCredentials) => Omit<ClientOptions, 'token' | 'onAuthRequired'>;
+  /**
+   * Called when Studio rejects the token. Return the credential to reconnect with, or `null` to
+   * end the run. Throwing fails it, which is what a host does when it cannot pair again.
+   */
+  onTokenRejected: (rejection: TokenRejection<TCredentials>) => Promise<TCredentials | null>;
+  /**
+   * Aborting this disconnects and ends the run. Hosts wire it to their own shutdown: `SIGINT` in
+   * the CLI, Nitro's `close` hook in the Docker agent.
+   */
+  signal?: AbortSignal;
+};
+/**
+ * Keeps a host connected to Studio across token changes: it opens a client, waits until the run
+ * ends or Studio rejects the token, and reconnects with whatever credential the host hands back.
+ *
+ * The host owns everything around that. Where credentials live, whether a rejected token may be
+ * replaced, and how any of it is reported are all decisions `onTokenRejected` makes.
+ *
+ * @example
+ * ```ts
+ * const outcome = await runConnection({
+ *   credentials,
+ *   clientOptions: () => ({ studioUrl, configPath, version, loadConfig }),
+ *   signal: shutdown.signal,
+ *   onTokenRejected: ({ error, live }) => pairAgain(error, live),
+ * })
+ * ```
+ */
+export declare function runConnection<TCredentials extends {
+  token: string;
+}>({ credentials, clientOptions, onTokenRejected, signal }: ConnectionOptions<TCredentials>): Promise<ConnectionOutcome>;
 //#endregion
 //#region src/pair.d.ts
 /**
@@ -231,6 +315,14 @@ type PairingResult = {
     name: string;
   };
 };
+/**
+ * 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();
+}
 type StartPairingOptions = {
   studioUrl?: string;
   /**
@@ -248,16 +340,25 @@ type StartPairingOptions = {
    * and ignores it for the CLI.
    */
   agentKind?: 'user' | 'sandbox';
+  /**
+   * Aborting this cancels the request in flight and rejects with {@link PairingCanceledError}.
+   */
+  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.
  */
-declare function startPairing({ studioUrl, name, hostname, clientId, agentKind }: StartPairingOptions): Promise<PairingSession>;
+export declare function startPairing({ studioUrl, name, hostname, clientId, agentKind, signal }: StartPairingOptions): Promise<PairingSession>;
 type PollOptions = {
   studioUrl?: string;
   session: PairingSession;
+  /**
+   * Aborting this stops polling and rejects with {@link PairingCanceledError}, whether the abort
+   * lands between polls or during the wait for the next one.
+   */
+  signal?: AbortSignal;
 };
 /**
  * Polls until the user approves or denies, honoring the server's `slow_down` back-off. A poll that
@@ -268,7 +369,7 @@ type PollOptions = {
  *
  * @throws when the code expires, the user denies it, or Studio returns an unexpected error.
  */
-declare function pollForPairingToken({ studioUrl, session }: PollOptions): Promise<PairingResult>;
+export declare function pollForPairingToken({ studioUrl, session, signal }: PollOptions): Promise<PairingResult>;
 //#endregion
-export { type Client, type ClientOptions, InvalidAgentTokenError, type StudioCommandEndContext, type StudioCommandStartContext, type StudioConnectedContext, type StudioConnectingContext, type StudioDisconnectedContext, type StudioErrorContext, type StudioWarnContext, createClient, createFileStorage, defaultStudioUrl, pollForPairingToken, setStorage, startPairing };
+export type { Client, ClientOptions, ConnectionOptions, StudioConnectedContext };
 //# sourceMappingURL=index.d.ts.map