@kubb/studio 5.13.0 → 5.14.0

package/dist/{protocol-C4loKcxw.d.ts → protocol-DQTwqmNO.d.cts}

@@ -1,70 +1,22 @@
 import { ExtensionKind, ExtensionManifest } from "@kubb/core";
 import { InputNode } from "@kubb/ast";
-//#region src/protocol.d.ts
-/**
- * JSON-serializable Kubb config exchanged over RPC. A live `kubb/kit` config holds
- * functions and class instances that cannot survive JSON, so both sides pass this flattened shape
- * and rebuild the real config from it.
- */
-type JSONKubbConfig = {
-  /**
-   * Plugins with their serialized options. `name` is the package name (e.g. `@kubb/plugin-ts`)
-   * and `options` is an opaque blob the agent forwards unchanged to the plugin factory. An entry
-   * with `disabled: true` is dropped even when the disk config's `plugins` array still lists it.
-   */
-  plugins?: Array<{
-    name: string;
-    options?: object;
-    disabled?: boolean;
-  }>;
-  /**
-   * Raw OpenAPI / Swagger spec content (YAML or JSON string), never a file path.
-   * Required by a 'sandbox' agent, which has no disk config of its own and refuses anything else.
-   * A 'managed' agent also takes a URL or a `git+<repo>#<ref>:<path>` input, and falls back to its disk config without one.
-   * Any other agent always reads its spec from disk, so this is ignored with a `kubb:warn`.
-   */
-  input?: string;
-  /**
-   * Adapter option overrides sent from Studio UI. Merged into the disk config's adapter options
-   * and re-applied through the same adapter factory, since an adapter instance's functions
-   * (`parse`, `getImports`, ...) can't survive JSON serialization over the WebSocket.
-   */
-  adapter?: object;
-  /**
-   * Parser option overrides from Studio, matched to the disk config's parsers by `name` and
-   * re-applied through each parser's factory, the same way `adapter` is.
-   */
-  parsers?: Array<{
-    name: string;
-    options?: object;
-  }>;
-  /** Root `output` overrides for `barrel`, `format`, `lint`, `clean`, and `defaultBanner`. Other members are ignored. */
-  output?: object;
-  /**
-   * Which `defineConfig(...)` entry to generate from. Omitted runs the first one.
-   */
-  config?: ConfigRef;
-};
-/**
- * Which `defineConfig(...)` entry an edit targets, for a config file that exports an array.
- *
- * A number selects by position, a string matches the entry's `name`. Omitted targets the only
- * entry, or the first one when the file exports an array.
- */
+//#region ../../internals/shared/src/configFile/types.d.ts
+/** Which `defineConfig(...)` entry an edit targets: its index or `name`, the first entry when omitted. */
 type ConfigRef = string | number;
-/**
- * A value the agent can read out of a plugin option in `kubb.config.ts` and round-trip through JSON.
- */
+/** A literal option value that survives a JSON round trip. */
 type OptionValue = string | number | boolean | null | Array<OptionValue> | {
   [key: string]: OptionValue;
 };
-/**
- * The kinds of {@link ConfigEdit}, one per `operation`.
- */
+declare const extensionKinds: {
+  readonly plugin: 'plugin';
+  readonly adapter: 'adapter';
+  readonly parser: 'parser';
+};
 declare const ConfigEditOperation: {
-  readonly SET: 'set';
-  readonly REMOVE: 'remove';
+  readonly SET_OPTION: 'set-option';
+  readonly REMOVE_OPTION: 'remove-option';
   readonly ADD_PLUGIN: 'add-plugin';
+  readonly REMOVE_EXTENSION: 'remove-extension';
   readonly DISABLE_PLUGIN: 'disable-plugin';
   readonly ENABLE_PLUGIN: 'enable-plugin';
   readonly SET_INPUT: 'set-input';
@@ -73,177 +25,170 @@ declare const ConfigEditOperation: {
 };
 type ConfigEditOperation = (typeof ConfigEditOperation)[keyof typeof ConfigEditOperation];
 /**
- * One change to a plugin's options in the user's `kubb.config.ts`.
- *
- * `plugin` is the package name (`@kubb/plugin-ts`), the same identity used in {@link JSONKubbConfig}.
- * The agent applies these to the file with an AST patch, so only the targeted values are rewritten.
- *
- * Declared here rather than in `configFile.ts` because this is the wire contract, and the patcher
- * imports it from here. Type-only, so nothing pulls `magicast` into this entry point.
+ * One change to `kubb.config.ts`. `plugin` is the package name, and `kind` picks the `plugins` entry
+ * (default), the `adapter`, or a `parsers` entry. `path` walks nested option objects.
  */
-type ConfigEdit =
-/**
- * Write a literal option value. `path` walks nested objects, so `['enum', 'type']` targets
- * `pluginTs({ enum: { type } })`. `kind` names which factory call `plugin` is: one in `plugins`
- * when left out, the config's `adapter`, or one in `parsers`.
- */
-{
-  operation: typeof ConfigEditOperation.SET;
+type ConfigEdit = {
+  operation: typeof ConfigEditOperation.SET_OPTION;
   config?: ConfigRef;
   kind?: ExtensionKind;
   plugin: string;
   path: Array<string>;
   value: unknown;
-} |
-/**
- * Drop an option so the extension falls back to its default. `kind` as for `set`.
- */
-{
-  operation: typeof ConfigEditOperation.REMOVE;
+} | {
+  operation: typeof ConfigEditOperation.REMOVE_OPTION;
   config?: ConfigRef;
   kind?: ExtensionKind;
   plugin: string;
   path: Array<string>;
 } |
-/**
- * Add a plugin factory call and its import to the `plugins` array.
- */
+/** With `kind: 'parser'`, adds to `parsers`. A config without `parsers` gets the defaults written next to it, so they keep running. */
 {
   operation: typeof ConfigEditOperation.ADD_PLUGIN;
   config?: ConfigRef;
+  kind?: typeof extensionKinds.plugin | typeof extensionKinds.parser;
   plugin: string;
   options?: Record<string, unknown>;
 } |
-/**
- * Comment the plugin call out, keeping its options in the file so enabling it again restores them.
- */
+/** Deletes every call of a plugin, or a parser with `kind: 'parser'`, a disabled block included, and the imports nothing else uses. */
 {
+  operation: typeof ConfigEditOperation.REMOVE_EXTENSION;
+  config?: ConfigRef;
+  kind?: typeof extensionKinds.plugin | typeof extensionKinds.parser;
+  plugin: string;
+} | {
   operation: typeof ConfigEditOperation.DISABLE_PLUGIN;
   config?: ConfigRef;
   plugin: string;
-} |
-/**
- * Uncomment a plugin call a previous `disable-plugin` commented out.
- */
-{
+} | {
   operation: typeof ConfigEditOperation.ENABLE_PLUGIN;
   config?: ConfigRef;
   plugin: string;
-} |
-/**
- * Point the config's `input` at a spec. The agent writes a document to `openapi.yaml` (or
- * `openapi.json`, and `openapi-<entry>` for a later entry) in its project and points `input` there.
- * Refused without `allowSaveInput`, and a managed agent takes only a document, a URL, or a `git+` file.
- */
-{
+} | {
   operation: typeof ConfigEditOperation.SET_INPUT;
   config?: ConfigRef;
   input: string;
-} |
-/** Write a literal inside the root `output` object, for the members `JSONKubbConfig.output` takes. */
-{
+} | {
   operation: typeof ConfigEditOperation.SET_OUTPUT;
   config?: ConfigRef;
   path: Array<string>;
   value: unknown;
-} |
-/** Drop a member of the root `output` object that `set-output` may write. */
-{
+} | {
   operation: typeof ConfigEditOperation.REMOVE_OUTPUT;
   config?: ConfigRef;
   path: Array<string>;
 };
-/** The top-level keys of an object in the config file, as {@link PluginView.options} describes. */
+/** Option keys, each with whether Studio may write it. `locked` lists the code paths inside a partly literal object. */
 type OptionsView = Record<string, {
   literal: boolean;
   value?: OptionValue;
   locked?: Array<Array<string>>;
 }>;
-/**
- * A factory call the agent found in a `defineConfig(...)`: a plugin in `plugins`, the `adapter`, or
- * a parser in `parsers`.
- */
+/** A factory call in `plugins`, `adapter`, or `parsers`. `importName` is the local name, alias included. */
 type PluginView = {
-  /**
-   * Local identifier of the factory in the file, e.g. `pluginTs`. This is the alias when the plugin
-   * was imported under one.
-   */
   importName: string;
-  /**
-   * Module the factory is imported from, e.g. `@kubb/plugin-ts`.
-   */
   packageName: string;
-  /**
-   * Top-level option keys, each flagged with whether the agent may write it and, when it can, the
-   * value found in the file. An option marked `literal: false` holds a function or a reference the
-   * agent will not overwrite, so Studio shows the control disabled rather than hiding it, and
-   * `value` is absent since there is nothing safe to display as the current value.
-   *
-   * An object option that holds code in only some members, such as
-   * `output: { path: './gen', banner: () => '' }`, also carries `value` with its literal members
-   * and `locked` with the paths of the members that are code, relative to the option
-   * (`[['banner']]`). A `set` at any deeper path outside `locked` succeeds, so Studio can edit
-   * `output.path` there.
-   */
   options: OptionsView;
-  /**
-   * Set when the plugin call is commented out in the file. Its options stay on disk but are not
-   * readable, so `options` is empty until it is enabled again.
-   */
+  /** The call is commented out by `disable-plugin`. */
   disabled?: true;
 };
-/**
- * One `defineConfig(...)` entry. A config file that exports a single object has exactly one.
- */
 type ConfigView = {
-  /**
-   * The entry's `name`, when it sets one. Studio labels the config picker with it.
-   */
   name?: string;
-  /**
-   * Each plugin call in the entry, with its top-level option keys.
-   */
   plugins: Array<PluginView>;
-  /**
-   * The `adapter` call, when the entry sets one through an imported factory.
-   */
   adapter?: PluginView;
-  /**
-   * The parser calls in `parsers`, when the entry lists any through imported factories.
-   */
   parsers?: Array<PluginView>;
-  /** The root `output` members Studio may set. Absent when `output` is not an object literal. */
+  /** The root `output` members Studio may set, absent when `output` is not an object literal. */
   output?: OptionsView;
 };
-/**
- * What the agent found in the user's config file, so Studio knows which controls it may offer.
- * Absent when the agent could not read the file at all.
- */
+/** The config file as Studio may edit it, or why it cannot. */
 type ConfigFileView = {
   managed: true;
-  /**
-   * One entry per config the file exports, in source order. Every {@link ConfigEdit} names
-   * which of these it targets through its `config` field.
-   */
   configs: Array<ConfigView>;
 } | {
   managed: false;
-  /**
-   * Why the file is outside what the agent edits, for example a default export that is not a
-   * `defineConfig(...)` call. Studio shows this and offers no property-level controls.
-   */
   reason: string;
 };
-/**
- * Outcome of a single {@link ConfigEdit}, returned in a {@link SaveResult}.
- */
 type ConfigEditOutcome = {
   edit: ConfigEdit;
   applied: boolean;
+  reason?: string;
+};
+type ExtensionEntry = {
+  package: string;
+  version: string;
+  manifest: ExtensionManifest;
+  /** Ships with `kubb` at its version, so updating `kubb` updates it and `kubb update` cannot. */
+  bundled?: true;
+};
+/** Installed extensions by package name, the only ones Studio may import besides `@kubb/plugin-*`. */
+type InstalledExtensions = ReadonlyMap<string, ExtensionEntry>;
+//#endregion
+//#region ../../internals/shared/src/configFile/configFile.d.ts
+/** Applies edits in place, touching only the text each targets. A refused edit is reported and the rest still run. */
+declare function editConfig({ source, edits, extensions }: {
+  source: string;
+  edits: Array<ConfigEdit>;
+  extensions?: InstalledExtensions;
+}): {
+  source: string;
+  outcomes: Array<ConfigEditOutcome>;
+  changed: boolean;
+};
+/** Applies `edits` to `filePath`, writing only when something changed. */
+declare function editConfigFile({ filePath, edits, extensions }: {
+  filePath: string;
+  edits: Array<ConfigEdit>;
+  extensions?: InstalledExtensions;
+}): Promise<{
+  source: string;
+  outcomes: Array<ConfigEditOutcome>;
+  changed: boolean;
+}>;
+//#endregion
+//#region src/protocol.d.ts
+/**
+ * JSON-serializable Kubb config exchanged over RPC. A live `kubb/kit` config holds
+ * functions and class instances that cannot survive JSON, so both sides pass this flattened shape
+ * and rebuild the real config from it.
+ */
+type JSONKubbConfig = {
   /**
-   * Why the edit was refused, absent when it was applied.
+   * Plugins with their serialized options. `name` is the package name (e.g. `@kubb/plugin-ts`)
+   * and `options` is an opaque blob the agent forwards unchanged to the plugin factory. An entry
+   * with `disabled: true` is dropped even when the disk config's `plugins` array still lists it.
    */
-  reason?: string;
+  plugins?: Array<{
+    name: string;
+    options?: object;
+    disabled?: boolean;
+  }>;
+  /**
+   * Raw OpenAPI / Swagger spec content (YAML or JSON string), never a file path.
+   * Required by a 'sandbox' agent, which has no disk config of its own and refuses anything else.
+   * A 'managed' agent also takes a URL or a `git+<repo>#<ref>:<path>` input, and falls back to its disk config without one.
+   * Any other agent always reads its spec from disk, so this is ignored with a `kubb:warn`.
+   */
+  input?: string;
+  /**
+   * Adapter option overrides sent from Studio UI. Merged into the disk config's adapter options
+   * and re-applied through the same adapter factory, since an adapter instance's functions
+   * (`parse`, `getImports`, ...) can't survive JSON serialization over the WebSocket.
+   */
+  adapter?: object;
+  /**
+   * Parser option overrides from Studio, matched to the disk config's parsers by `name` and
+   * re-applied through each parser's factory, the same way `adapter` is.
+   */
+  parsers?: Array<{
+    name: string;
+    options?: object;
+  }>;
+  /** Root `output` overrides for `barrel`, `format`, `lint`, `clean`, and `defaultBanner`. Other members are ignored. */
+  output?: object;
+  /**
+   * Which `defineConfig(...)` entry to generate from. Omitted runs the first one.
+   */
+  config?: ConfigRef;
 };
 /**
  * The public, JSON-safe subset of Kubb lifecycle hooks. The core registry remains extensible;
@@ -455,6 +400,16 @@ type UpdateExtensionsResult = {
   updated: boolean;
   reason?: string;
 };
+/** Asks the agent to run `kubb remove <id> --yes`. `requestedBy` as for {@link GenerateInput}. */
+type RemoveExtensionInput = {
+  id: string;
+  requestedBy?: string;
+};
+/** `removed` is false when the agent refused or `kubb remove` failed, with `reason` saying why. */
+type RemoveExtensionResult = {
+  removed: boolean;
+  reason?: string;
+};
 /**
  * Reads an immutable output set kept on disk, from a generation or the initial connection.
  */
@@ -613,6 +568,8 @@ type AgentApi = {
   installExtension: (input: InstallExtensionInput) => Promise<InstallExtensionResult>;
   /** Refused without `allowUpdate`. Installs packages only, so `kubb.config.ts` stays as it is. */
   updateExtensions: (input: UpdateExtensionsInput) => Promise<UpdateExtensionsResult>;
+  /** Refused without `allowRemove` and `allowConfigEdit`. An agent from before `removeExtension` rejects the call. */
+  removeExtension: (input: RemoveExtensionInput) => Promise<RemoveExtensionResult>;
   readFiles: (input: ReadFilesInput) => Promise<ReadFilesResult>;
   /**
    * Refused unless the agent was granted `allowRead`, like {@link AgentApi.readFiles}.
@@ -733,14 +690,6 @@ type ConfigEntryView = {
     options?: object;
   }>;
 };
-/** An installed extension package and the manifest it ships. */
-type ExtensionEntry = {
-  package: string;
-  version: string;
-  manifest: ExtensionManifest;
-};
-/** Installed extension packages by package name, the only ones Studio may import besides `@kubb/plugin-*`. */
-type InstalledExtensions = ReadonlyMap<string, ExtensionEntry>;
 /**
  * What an agent may do in the project it serves. Every one is off unless the host granted it, and
  * a sandbox narrows them further.
@@ -764,6 +713,8 @@ type AgentPermissions = {
   allowInstall: boolean;
   /** Whether the agent may run `kubb update` in the project, which installs newer extension versions and leaves `kubb.config.ts` alone. */
   allowUpdate: boolean;
+  /** Whether the agent may run `kubb remove` in the project, which edits `kubb.config.ts` and uninstalls packages. Needs `allowConfigEdit` as well. */
+  allowRemove: boolean;
   /** Whether the agent may keep the spec Studio sends: a document in `openapi.yaml` and `input` in `kubb.config.ts`. Needs `allowConfigEdit` as well. */
   allowSaveInput: boolean;
   /**
@@ -787,6 +738,7 @@ declare const AgentPermission: {
   readonly CONFIG_EDIT: 'allowConfigEdit';
   readonly INSTALL: 'allowInstall';
   readonly UPDATE: 'allowUpdate';
+  readonly REMOVE: 'allowRemove';
   readonly SAVE_INPUT: 'allowSaveInput';
   readonly EXEC: 'allowExec';
 };
@@ -879,5 +831,5 @@ type PublishedSnapshot = {
   branchChanges?: BranchSnapshotChanges;
 };
 //#endregion
-export { generationEventTypes as $, InstallExtensionResult as A, ReadDiffInput as B, GenerateInput as C, GenerationEventType as D, GenerationEventPayloads as E, MAX_SNAPSHOT_BYTES as F, ReadInputResult as G, ReadFilesInput as H, OptionValue as I, SnapshotChanges as J, SaveConfigInput as K, OptionsView as L, JSONKubbConfig as M, MAX_FILES_PER_REQUEST as N, GenerationRun as O, MAX_PAGE_LINES as P, UpdateExtensionsResult as Q, PluginView as R, FilePage as S, GenerationEvent as T, ReadFilesResult as U, ReadDiffResult as V, ReadInputInput as W, StudioApi as X, SnapshotUploadMetadata as Y, UpdateExtensionsInput as Z, ConnectMessagePayload as _, AgentConnectInfo as a, DiskOutput as b, AgentPermissions as c, ConfigEditOperation as d, ConfigEditOutcome as f, ConfigView as g, ConfigRef as h, AgentCloseCode as i, InstalledExtensions as j, InstallExtensionInput as k, BranchSnapshotChanges as l, ConfigFileView as m, AGENT_SOCKET_PATH as n, AgentMessage as o, ConfigEntryView as p, SaveResult as q, AgentApi as r, AgentPermission as s, AGENT_INSTANCE_HEADER as t, ConfigEdit as u, DiffHunk as v, GenerateResult as w, ExtensionEntry as x, DiffStats as y, PublishedSnapshot as z };
-//# sourceMappingURL=protocol-C4loKcxw.d.ts.map
+export { ExtensionEntry as $, ReadDiffResult as A, SnapshotUploadMetadata as B, InstallExtensionResult as C, MAX_SNAPSHOT_BYTES as D, MAX_PAGE_LINES as E, RemoveExtensionInput as F, editConfig as G, UpdateExtensionsInput as H, RemoveExtensionResult as I, ConfigEditOperation as J, editConfigFile as K, SaveConfigInput as L, ReadFilesResult as M, ReadInputInput as N, PublishedSnapshot as O, ReadInputResult as P, ConfigView as Q, SaveResult as R, InstallExtensionInput as S, MAX_FILES_PER_REQUEST as T, UpdateExtensionsResult as U, StudioApi as V, generationEventTypes as W, ConfigFileView as X, ConfigEditOutcome as Y, ConfigRef as Z, GenerateResult as _, AgentConnectInfo as a, GenerationEventType as b, AgentPermissions as c, ConnectMessagePayload as d, InstalledExtensions as et, DiffHunk as f, GenerateInput as g, FilePage as h, AgentCloseCode as i, ReadFilesInput as j, ReadDiffInput as k, BranchSnapshotChanges as l, DiskOutput as m, AGENT_SOCKET_PATH as n, OptionsView as nt, AgentMessage as o, DiffStats as p, ConfigEdit as q, AgentApi as r, PluginView as rt, AgentPermission as s, AGENT_INSTANCE_HEADER as t, OptionValue as tt, ConfigEntryView as u, GenerationEvent as v, JSONKubbConfig as w, GenerationRun as x, GenerationEventPayloads as y, SnapshotChanges as z };
+//# sourceMappingURL=protocol-DQTwqmNO.d.cts.map