@theia/plugin 1.63.0-next.24 → 1.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.63.0-next.24+83b50cc66",
+  "version": "1.63.0",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -27,10 +27,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.62.0"
+    "@theia/ext-scripts": "1.63.0"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "83b50cc66b001a5b9100ccd944dcace04cd4ae2e"
+  "gitHead": "facf442522991134333495a0b90cf56a56990280"
 }

package/src/theia.d.ts

@@ -1454,6 +1454,24 @@ export module '@theia/plugin' {
          */
         readonly languageId: string;
 
+        /**
+         * The file encoding of this document that will be used when the document is saved.
+         *
+         * Use the {@link workspace.onDidChangeTextDocument onDidChangeTextDocument}-event to
+         * get notified when the document encoding changes.
+         *
+         * Note that the possible encoding values are currently defined as any of the following:
+         * 'utf8', 'utf8bom', 'utf16le', 'utf16be', 'windows1252', 'iso88591', 'iso88593',
+         * 'iso885915', 'macroman', 'cp437', 'windows1256', 'iso88596', 'windows1257',
+         * 'iso88594', 'iso885914', 'windows1250', 'iso88592', 'cp852', 'windows1251',
+         * 'cp866', 'cp1125', 'iso88595', 'koi8r', 'koi8u', 'iso885913', 'windows1253',
+         * 'iso88597', 'windows1255', 'iso88598', 'iso885910', 'iso885916', 'windows1254',
+         * 'iso88599', 'windows1258', 'gbk', 'gb18030', 'cp950', 'big5hkscs', 'shiftjis',
+         * 'eucjp', 'euckr', 'windows874', 'iso885911', 'koi8ru', 'koi8t', 'gb2312',
+         * 'cp865', 'cp850'.
+         */
+        readonly encoding: string;
+
         /**
          * The version number of this document (it will strictly increase after each
          * change, including undo/redo).
@@ -7871,29 +7889,75 @@ export module '@theia/plugin' {
          * Opens a document. Will return early if this document is already open. Otherwise
          * the document is loaded and the {@link workspace.onDidOpenTextDocument didOpen}-event fires.
          *
-         * The document is denoted by an {@link Uri uri}. Depending on the {@link Uri.scheme scheme} the
+         * The document is denoted by an {@link Uri}. Depending on the {@link Uri.scheme scheme} the
          * following rules apply:
-         * * `file`-scheme: Open a file on disk, will be rejected if the file does not exist or cannot be loaded.
-         * * `untitled`-scheme: A new file that should be saved on disk, e.g. `untitled:c:\frodo\new.js`. The language
-         * will be derived from the file name.
-         * * For all other schemes the registered text document content {@link TextDocumentContentProvider providers} are consulted.
+         * * `file`-scheme: Open a file on disk (`openTextDocument(Uri.file(path))`). Will be rejected if the file
+         * does not exist or cannot be loaded.
+         * * `untitled`-scheme: Open a blank untitled file with associated path (`openTextDocument(Uri.file(path).with({ scheme: 'untitled' }))`).
+         * The language will be derived from the file name.
+         * * For all other schemes contributed {@link TextDocumentContentProvider text document content providers} and
+         * {@link FileSystemProvider file system providers} are consulted.
          *
          * *Note* that the lifecycle of the returned document is owned by the editor and not by the extension. That means an
-         * [`onDidClose`](#workspace.onDidCloseTextDocument)-event can occur at any time after opening it.
+         * {@linkcode workspace.onDidCloseTextDocument onDidClose}-event can occur at any time after opening it.
          *
          * @param uri Identifies the resource to open.
-         * @return A promise that resolves to a {@link TextDocument document}.
+         * @returns A promise that resolves to a {@link TextDocument document}.
          */
-        export function openTextDocument(uri: Uri): Thenable<TextDocument | undefined>;
+        export function openTextDocument(uri: Uri, options?: {
+            /**
+             * The {@link TextDocument.encoding encoding} of the document to use
+             * for decoding the underlying buffer to text. If omitted, the encoding
+             * will be guessed based on the file content and/or the editor settings
+             * unless the document is already opened.
+             *
+             * Opening a text document that was already opened with a different encoding
+             * has the potential of changing the text contents of the text document.
+             * Specifically, when the encoding results in a different set of characters
+             * than the previous encoding. As such, an error is thrown for dirty documents
+             * when the specified encoding is different from the encoding of the document.
+             *
+             * See {@link TextDocument.encoding} for more information about valid
+             * values for encoding. Using an unsupported encoding will fallback to the
+             * default encoding for the document.
+             *
+             * *Note* that if you open a document with an encoding that does not
+             * support decoding the underlying bytes, content may be replaced with
+             * substitution characters as appropriate.
+             */
+            readonly encoding?: string;
+        }): Thenable<TextDocument>;
 
         /**
-         * A short-hand for `openTextDocument(Uri.file(fileName))`.
+         * A short-hand for `openTextDocument(Uri.file(path))`.
          *
-         * @see {@link openTextDocument openTextDocument}
-         * @param fileName A name of a file on disk.
-         * @return A promise that resolves to a {@link TextDocument document}.
+         * @see {@link workspace.openTextDocument}
+         * @param path A path of a file on disk.
+         * @returns A promise that resolves to a {@link TextDocument document}.
          */
-        export function openTextDocument(fileName: string): Thenable<TextDocument | undefined>;
+        export function openTextDocument(path: string, options?: {
+            /**
+             * The {@link TextDocument.encoding encoding} of the document to use
+             * for decoding the underlying buffer to text. If omitted, the encoding
+             * will be guessed based on the file content and/or the editor settings
+             * unless the document is already opened.
+             *
+             * Opening a text document that was already opened with a different encoding
+             * has the potential of changing the text contents of the text document.
+             * Specifically, when the encoding results in a different set of characters
+             * than the previous encoding. As such, an error is thrown for dirty documents
+             * when the specified encoding is different from the encoding of the document.
+             *
+             * See {@link TextDocument.encoding} for more information about valid
+             * values for encoding. Using an unsupported encoding will fallback to the
+             * default encoding for the document.
+             *
+             * *Note* that if you open a document with an encoding that does not
+             * support decoding the underlying bytes, content may be replaced with
+             * substitution characters as appropriate.
+             */
+            readonly encoding?: string;
+        }): Thenable<TextDocument>;
 
         /**
          * Opens an untitled text document. The editor will prompt the user for a file
@@ -7901,9 +7965,26 @@ export module '@theia/plugin' {
          * specify the *language* and/or the *content* of the document.
          *
          * @param options Options to control how the document will be created.
-         * @return A promise that resolves to a {@link TextDocument document}.
+         * @returns A promise that resolves to a {@link TextDocument document}.
          */
-        export function openTextDocument(options?: { language?: string; content?: string; }): Thenable<TextDocument | undefined>;
+        export function openTextDocument(options?: {
+            /**
+             * The {@link TextDocument.languageId language} of the document.
+             */
+            language?: string;
+            /**
+             * The initial contents of the document.
+             */
+            content?: string;
+            /**
+             * The {@link TextDocument.encoding encoding} of the document.
+             *
+             * See {@link TextDocument.encoding} for more information about valid
+             * values for encoding. Using an unsupported encoding will fallback to the
+             * default encoding for the document.
+             */
+            readonly encoding?: string;
+        }): Thenable<TextDocument>;
 
         /**
          *  Open a notebook. Will return early if this notebook is already {@link NotebookDocument loaded}.
@@ -8138,6 +8219,130 @@ export module '@theia/plugin' {
          * Event that fires when the current workspace has been trusted.
          */
         export const onDidGrantWorkspaceTrust: Event<void>;
+
+        /**
+         * Decodes the content from a `Uint8Array` to a `string`. You MUST
+         * provide the entire content at once to ensure that the encoding
+         * can properly apply. Do not use this method to decode content
+         * in chunks, as that may lead to incorrect results.
+         *
+         * Will pick an encoding based on settings and the content of the
+         * buffer (for example byte order marks).
+         *
+         * *Note* that if you decode content that is unsupported by the
+         * encoding, the result may contain substitution characters as
+         * appropriate.
+         *
+         * @throws This method will throw an error when the content is binary.
+         *
+         * @param content The text content to decode as a `Uint8Array`.
+         * @returns A thenable that resolves to the decoded `string`.
+         */
+        export function decode(content: Uint8Array): Thenable<string>;
+
+        /**
+         * Decodes the content from a `Uint8Array` to a `string` using the
+         * provided encoding. You MUST provide the entire content at once
+         * to ensure that the encoding can properly apply. Do not use this
+         * method to decode content in chunks, as that may lead to incorrect
+         * results.
+         *
+         * *Note* that if you decode content that is unsupported by the
+         * encoding, the result may contain substitution characters as
+         * appropriate.
+         *
+         * @throws This method will throw an error when the content is binary.
+         *
+         * @param content The text content to decode as a `Uint8Array`.
+         * @param options Additional context for picking the encoding.
+         * @returns A thenable that resolves to the decoded `string`.
+         */
+        export function decode(content: Uint8Array, options: {
+            /**
+             * Allows to explicitly pick the encoding to use.
+             * See {@link TextDocument.encoding} for more information
+             * about valid values for encoding.
+             * Using an unsupported encoding will fallback to the
+             * default configured encoding.
+             */
+            readonly encoding: string;
+        }): Thenable<string>;
+
+        /**
+         * Decodes the content from a `Uint8Array` to a `string`. You MUST
+         * provide the entire content at once to ensure that the encoding
+         * can properly apply. Do not use this method to decode content
+         * in chunks, as that may lead to incorrect results.
+         *
+         * The encoding is picked based on settings and the content
+         * of the buffer (for example byte order marks).
+         *
+         * *Note* that if you decode content that is unsupported by the
+         * encoding, the result may contain substitution characters as
+         * appropriate.
+         *
+         * @throws This method will throw an error when the content is binary.
+         *
+         * @param content The content to decode as a `Uint8Array`.
+         * @param options Additional context for picking the encoding.
+         * @returns A thenable that resolves to the decoded `string`.
+         */
+        export function decode(content: Uint8Array, options: {
+            /**
+             * The URI that represents the file if known. This information
+             * is used to figure out the encoding related configuration
+             * for the file if any.
+             */
+            readonly uri: Uri;
+        }): Thenable<string>;
+
+        /**
+         * Encodes the content of a `string` to a `Uint8Array`.
+         *
+         * Will pick an encoding based on settings.
+         *
+         * @param content The content to decode as a `string`.
+         * @returns A thenable that resolves to the encoded `Uint8Array`.
+         */
+        export function encode(content: string): Thenable<Uint8Array>;
+
+        /**
+         * Encodes the content of a `string` to a `Uint8Array` using the
+         * provided encoding.
+         *
+         * @param content The content to decode as a `string`.
+         * @param options Additional context for picking the encoding.
+         * @returns A thenable that resolves to the encoded `Uint8Array`.
+         */
+        export function encode(content: string, options: {
+            /**
+             * Allows to explicitly pick the encoding to use.
+             * See {@link TextDocument.encoding} for more information
+             * about valid values for encoding.
+             * Using an unsupported encoding will fallback to the
+             * default configured encoding.
+             */
+            readonly encoding: string;
+        }): Thenable<Uint8Array>;
+
+        /**
+         * Encodes the content of a `string` to a `Uint8Array`.
+         *
+         * The encoding is picked based on settings.
+         *
+         * @param content The content to decode as a `string`.
+         * @param options Additional context for picking the encoding.
+         * @returns A thenable that resolves to the encoded `Uint8Array`.
+         */
+        export function encode(content: string, options: {
+            /**
+             * The URI that represents the file if known. This information
+             * is used to figure out the encoding related configuration
+             * for the file if any.
+             */
+            readonly uri: Uri;
+        }): Thenable<Uint8Array>;
+
     }
 
     export interface WorkspaceTrustRequestButton {
@@ -18662,6 +18867,138 @@ export module '@theia/plugin' {
         toolMode?: LanguageModelChatToolMode;
     }
 
+    /**
+     * McpStdioServerDefinition represents an MCP server available by running
+     * a local process and operating on its stdin and stdout streams. The process
+     * will be spawned as a child process of the extension host and by default
+     * will not run in a shell environment.
+     */
+    export class McpStdioServerDefinition {
+        /**
+         * The human-readable name of the server.
+         */
+        readonly label: string;
+
+        /**
+         * The working directory used to start the server.
+         */
+        cwd?: Uri;
+
+        /**
+         * The command used to start the server. Node.js-based servers may use
+         * `process.execPath` to use the editor's version of Node.js to run the script.
+         */
+        command: string;
+
+        /**
+         * Additional command-line arguments passed to the server.
+         */
+        args: string[];
+
+        /**
+         * Optional additional environment information for the server. Variables
+         * in this environment will overwrite or remove (if null) the default
+         * environment variables of the editor's extension host.
+         */
+        env: Record<string, string | number | null>;
+
+        /**
+         * Optional version identification for the server. If this changes, the
+         * editor will indicate that tools have changed and prompt to refresh them.
+         */
+        version?: string;
+
+        /**
+         * @param label The human-readable name of the server.
+         * @param command The command used to start the server.
+         * @param args Additional command-line arguments passed to the server.
+         * @param env Optional additional environment information for the server.
+         * @param version Optional version identification for the server.
+         */
+        constructor(label: string, command: string, args?: string[], env?: Record<string, string | number | null>, version?: string);
+    }
+
+    /**
+     * McpHttpServerDefinition represents an MCP server available using the
+     * Streamable HTTP transport.
+     */
+    export class McpHttpServerDefinition {
+        /**
+         * The human-readable name of the server.
+         */
+        readonly label: string;
+
+        /**
+         * The URI of the server. The editor will make a POST request to this URI
+         * to begin each session.
+         */
+        uri: Uri;
+
+        /**
+         * Optional additional heads included with each request to the server.
+         */
+        headers: Record<string, string>;
+
+        /**
+         * Optional version identification for the server. If this changes, the
+         * editor will indicate that tools have changed and prompt to refresh them.
+         */
+        version?: string;
+
+        /**
+         * @param label The human-readable name of the server.
+         * @param uri The URI of the server.
+         * @param headers Optional additional heads included with each request to the server.
+         */
+        constructor(label: string, uri: Uri, headers?: Record<string, string>, version?: string);
+    }
+
+    /**
+     * Definitions that describe different types of Model Context Protocol servers,
+     * which can be returned from the {@link McpServerDefinitionProvider}.
+     */
+    export type McpServerDefinition = McpStdioServerDefinition | McpHttpServerDefinition;
+
+    /**
+     * A type that can provide Model Context Protocol server definitions. This
+     * should be registered using {@link lm.registerMcpServerDefinitionProvider}
+     * during extension activation.
+     */
+    export interface McpServerDefinitionProvider<T extends McpServerDefinition = McpServerDefinition> {
+        /**
+         * Optional event fired to signal that the set of available servers has changed.
+         */
+        readonly onDidChangeMcpServerDefinitions?: Event<void>;
+
+        /**
+         * Provides available MCP servers. The editor will call this method eagerly
+         * to ensure the availability of servers for the language model, and so
+         * extensions should not take actions which would require user
+         * interaction, such as authentication.
+         *
+         * @param token A cancellation token.
+         * @returns An array of MCP available MCP servers
+         */
+        provideMcpServerDefinitions(token: CancellationToken): ProviderResult<T[]>;
+
+        /**
+         * This function will be called when the editor needs to start a MCP server.
+         * At this point, the extension may take any actions which may require user
+         * interaction, such as authentication. Any non-`readonly` property of the
+         * server may be modified, and the extension should return the resolved server.
+         *
+         * The extension may return undefined to indicate that the server
+         * should not be started, or throw an error. If there is a pending tool
+         * call, the editor will cancel it and return an error message to the
+         * language model.
+         *
+         * @param server The MCP server to resolve
+         * @param token A cancellation token.
+         * @returns The resolved server or thenable that resolves to such. This may
+         * be the given `server` definition with non-readonly properties filled in.
+         */
+        resolveMcpServerDefinition?(server: T, token: CancellationToken): ProviderResult<T>;
+    }
     /**
      * Namespace for language model related functionality.
      */
@@ -18745,6 +19082,34 @@ export module '@theia/plugin' {
          * @stubbed
          */
         export function invokeTool(name: string, options: LanguageModelToolInvocationOptions<object>, token?: CancellationToken): Thenable<LanguageModelToolResult>;
+
+        /**
+         * Registers a provider that publishes Model Context Protocol servers for the editor to
+         * consume. This allows MCP servers to be dynamically provided to the editor in
+         * addition to those the user creates in their configuration files.
+         *
+         * Before calling this method, extensions must register the `contributes.mcpServerDefinitionProviders`
+         * extension point with the corresponding {@link id}, for example:
+         *
+         * ```js
+         * "contributes": {
+         *     "mcpServerDefinitionProviders": [
+         *         {
+         *              "id": "cool-cloud-registry.mcp-servers",
+         *              "label": "Cool Cloud Registry",
+         *         }
+         *     ]
+         * }
+         * ```
+         *
+         * When a new McpServerDefinitionProvider is available, the editor will present a 'refresh'
+         * action to the user to discover new servers. To enable this flow, extensions should
+         * call `registerMcpServerDefinitionProvider` during activation.
+         * @param id The ID of the provider, which is unique to the extension.
+         * @param provider The provider to register
+         * @returns A disposable that unregisters the provider when disposed.
+         */
+        export function registerMcpServerDefinitionProvider(id: string, provider: McpServerDefinitionProvider): Disposable;
     }
 
     /**