@theia/plugin 1.66.0-next.44 → 1.66.0-next.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.66.0-next.44+5b6e49d13",
+  "version": "1.66.0-next.67+6fae23c43",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -32,5 +32,5 @@
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "5b6e49d139f9abbb18e233f138497a33a0758222"
+  "gitHead": "6fae23c43f4e850ef4dd6f7c85aa0422077f70e2"
 }

package/src/theia.d.ts

@@ -4538,6 +4538,11 @@ export module '@theia/plugin' {
      * sensitive.
      */
     export interface SecretStorage {
+        /**
+         * Retrieve the keys of all the secrets stored by this extension.
+         */
+        keys(): Thenable<string[]>;
+
         /**
          * Retrieve a secret that was stored with key. Returns undefined if there
          * is no password matching that key.
@@ -4562,7 +4567,7 @@ export module '@theia/plugin' {
         /**
          * Fires when a secret is stored or deleted.
          */
-        onDidChange: Event<SecretStorageChangeEvent>;
+        readonly onDidChange: Event<SecretStorageChangeEvent>;
     }
 
     /**
@@ -6306,7 +6311,7 @@ export module '@theia/plugin' {
          * (Examples include: an explicit call to [QuickInput.hide](#QuickInput.hide),
          * the user pressing Esc, some other input UI opening, etc.)
          */
-        onDidHide: Event<void>;
+        readonly onDidHide: Event<void>;
 
         /**
          * Dispose of this input UI and any associated resources. If it is still
@@ -15135,6 +15140,30 @@ export module '@theia/plugin' {
         account?: AuthenticationSessionAccountInformation;
     }
 
+    /**
+     * Represents parameters for creating a session based on a WWW-Authenticate header value.
+     * This is used when an API returns a 401 with a WWW-Authenticate header indicating
+     * that additional authentication is required. The details of which will be passed down
+     * to the authentication provider to create a session.
+     *
+     * @note The authorization provider must support handling challenges and specifically
+     * the challenges in this WWW-Authenticate value.
+     * @note For more information on WWW-Authenticate please see https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/WWW-Authenticate
+     */
+    export interface AuthenticationWwwAuthenticateRequest {
+        /**
+         * The raw WWW-Authenticate header value that triggered this challenge.
+         * This will be parsed by the authentication provider to extract the necessary
+         * challenge information.
+         */
+        readonly wwwAuthenticate: string;
+
+        /**
+         * The fallback scopes to use if no scopes are found in the WWW-Authenticate header.
+         */
+        readonly fallbackScopes?: readonly string[];
+    }
+
     /**
      * Basic information about an {@link AuthenticationProvider authenticationProvider}
      */
@@ -15256,47 +15285,47 @@ export module '@theia/plugin' {
      */
     export namespace authentication {
         /**
-         * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not
-         * registered, or if the user does not consent to sharing authentication information with
-         * the extension. If there are multiple sessions with the same scopes, the user will be shown a
-         * quickpick to select which account they would like to use.
+         * Get an authentication session matching the desired scopes or satisfying the WWW-Authenticate request. Rejects if
+         * a provider with providerId is not registered, or if the user does not consent to sharing authentication information
+         * with the extension. If there are multiple sessions with the same scopes, the user will be shown a quickpick to
+         * select which account they would like to use.
          *
          * Currently, there are only two authentication providers that are contributed from built in extensions
          * to VS Code that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
+         *
          * @param providerId The id of the provider to use
-         * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider
-         * @param options The {@link GetSessionOptions getSessionOptions} to use
+         * @param scopeListOrRequest A scope list of permissions requested or a WWW-Authenticate request. These are dependent on the authentication provider.
+         * @param options The {@link AuthenticationGetSessionOptions} to use
          * @returns A thenable that resolves to an authentication session
          */
-        export function getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & { createIfNone: true | AuthenticationGetSessionPresentationOptions }): Thenable<AuthenticationSession>;
+        export function getSession(providerId: string, scopeListOrRequest: ReadonlyArray<string> | AuthenticationWwwAuthenticateRequest, options: AuthenticationGetSessionOptions & { /** */createIfNone: true | AuthenticationGetSessionPresentationOptions }): Thenable<AuthenticationSession>;
 
         /**
-         * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not
-         * registered, or if the user does not consent to sharing authentication information with
-         * the extension. If there are multiple sessions with the same scopes, the user will be shown a
-         * quickpick to select which account they would like to use.
+         * Get an authentication session matching the desired scopes or request. Rejects if a provider with providerId is not
+         * registered, or if the user does not consent to sharing authentication information with the extension. If there
+         * are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.
          *
          * Currently, there are only two authentication providers that are contributed from built in extensions
          * to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
+         *
          * @param providerId The id of the provider to use
-         * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider
+         * @param scopeListOrRequest A scope list of permissions requested or a WWW-Authenticate request. These are dependent on the authentication provider.
          * @param options The {@link AuthenticationGetSessionOptions} to use
          * @returns A thenable that resolves to an authentication session
          */
-        export function getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & { forceNewSession: true | AuthenticationGetSessionPresentationOptions | AuthenticationForceNewSessionOptions }): Thenable<AuthenticationSession>;
+        export function getSession(providerId: string, scopeListOrRequest: ReadonlyArray<string> | AuthenticationWwwAuthenticateRequest, options: AuthenticationGetSessionOptions & { /** literal-type defines return type */forceNewSession: true | AuthenticationGetSessionPresentationOptions | AuthenticationForceNewSessionOptions }): Thenable<AuthenticationSession>;
 
         /**
-         * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not
-         * registered, or if the user does not consent to sharing authentication information with
-         * the extension. If there are multiple sessions with the same scopes, the user will be shown a
-         * quickpick to select which account they would like to use.
+         * Get an authentication session matching the desired scopes or request. Rejects if a provider with providerId is not
+         * registered, or if the user does not consent to sharing authentication information with the extension. If there
+         * are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.
          *
          * @param providerId The id of the provider to use
-         * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider
-         * @param options The {@link GetSessionOptions getSessionOptions} to use
-         * @returns A thenable that resolves to an authentication session if available, or undefined if there are no sessions
+         * @param scopeListOrRequest A scope list of permissions requested or a WWW-Authenticate request. These are dependent on the authentication provider.
+         * @param options The {@link AuthenticationGetSessionOptions} to use
+         * @returns A thenable that resolves to an authentication session or undefined if a silent flow was used and no session was found
          */
-        export function getSession(providerId: string, scopes: readonly string[], options?: AuthenticationGetSessionOptions): Thenable<AuthenticationSession | undefined>;
+        export function getSession(providerId: string, scopeListOrRequest: ReadonlyArray<string> | AuthenticationWwwAuthenticateRequest, options?: AuthenticationGetSessionOptions): Thenable<AuthenticationSession | undefined>;
 
         /**
          * Get all accounts that the user is logged in to for the specified provider.
@@ -17158,7 +17187,7 @@ export module '@theia/plugin' {
          * Fired when a user has changed whether this is a default profile. The
          * event contains the new value of {@link isDefault}
          */
-        onDidChangeDefault: Event<boolean>;
+        readonly onDidChangeDefault: Event<boolean>;
 
         /**
          * Whether this profile supports continuous running of requests. If so,
@@ -17540,7 +17569,7 @@ export module '@theia/plugin' {
          * An event fired when the editor is no longer interested in data
          * associated with the test run.
          */
-        onDidDispose: Event<void>;
+        readonly onDidDispose: Event<void>;
     }
 
     /**
@@ -18216,7 +18245,7 @@ export module '@theia/plugin' {
          * previously returned from this chat participant.
          * @stubbed
          */
-        onDidReceiveFeedback: Event<ChatResultFeedback>;
+        readonly onDidReceiveFeedback: Event<ChatResultFeedback>;
 
         /**
          * Dispose this participant and free resources.
@@ -19135,22 +19164,25 @@ export module '@theia/plugin' {
          * Various features that the model supports such as tool calling or image input.
          * @stubbed
          */
-        readonly capabilities: {
+        readonly capabilities: LanguageModelChatCapabilities;
+    }
 
-            /**
-             * Whether image input is supported by the model.
-             * Common supported images are jpg and png, but each model will vary in supported mimetypes.
-             * @stubbed
-             */
-            readonly imageInput?: boolean;
+    /**
+     * Various features that the {@link LanguageModelChatInformation} supports such as tool calling or image input.
+     * @stubbed
+     */
+    export interface LanguageModelChatCapabilities {
+        /**
+         * Whether image input is supported by the model.
+         * Common supported images are jpg and png, but each model will vary in supported mimetypes.
+         */
+        readonly imageInput?: boolean;
 
-            /**
-             * Whether tool calling is supported by the model.
-             * If a number is provided, that is the maximum number of tools that can be provided in a request to the model.
-             * @stubbed
-             */
-            readonly toolCalling?: boolean | number;
-        };
+        /**
+         * Whether tool calling is supported by the model.
+         * If a number is provided, that is the maximum number of tools that can be provided in a request to the model.
+         */
+        readonly toolCalling?: boolean | number;
     }
 
     /**
@@ -19370,7 +19402,7 @@ export module '@theia/plugin' {
          * An event that fires when access information changes.
          * @stubbed
          */
-        onDidChange: Event<void>;
+        readonly onDidChange: Event<void>;
 
         /**
          * Checks if a request can be made to a language model.

package/src/theia.proposed.debugVisualization.d.ts

@@ -21,7 +21,7 @@
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-declare module '@theia/plugin' {
+export module '@theia/plugin' {
     export namespace debug {
         /**
          * Registers a custom data visualization for variables when debugging.

package/src/{theia.proposed.multiDocumentHighlightProvider.ts → theia.proposed.multiDocumentHighlightProvider.d.ts}

@@ -20,7 +20,7 @@
  *--------------------------------------------------------------------------------------------*/
 // code copied and modified from https://github.com/microsoft/vscode/blob/1.85.1/src/vscode-dts/vscode.proposed.multiDocumentHighlightProvider.d.ts
 
-declare module '@theia/plugin' {
+export module '@theia/plugin' {
 
     /**
      * Represents a collection of document highlights from multiple documents.

package/src/theia.proposed.notebookCellExecutionState.d.ts

@@ -19,7 +19,7 @@
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
 
-declare module '@theia/plugin' {
+export module '@theia/plugin' {
 
     // https://github.com/microsoft/vscode/issues/124970
 

package/src/theia.proposed.notebookKernelSource.d.ts

@@ -19,7 +19,7 @@
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
 
-declare module '@theia/plugin' {
+export module '@theia/plugin' {
     export interface NotebookControllerDetectionTask {
         /**
          * Dispose and remove the detection task.

package/src/theia.proposed.notebookMessaging.d.ts

@@ -19,7 +19,7 @@
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
 
-declare module '@theia/plugin' {
+export module '@theia/plugin' {
 
     // https://github.com/microsoft/vscode/issues/123601
 

package/src/theia.proposed.portsAttributes.d.ts

@@ -19,7 +19,7 @@
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
 
-declare module '@theia/plugin' {
+export module '@theia/plugin' {
 
     /**
      * The action that should be taken when a port is discovered through automatic port forwarding discovery.

package/src/theia.proposed.scmProviderOptions.d.ts

@@ -20,7 +20,7 @@
  *--------------------------------------------------------------------------------------------*/
 // code copied and modified from https://github.com/microsoft/vscode/blob/1.103.2/src/vscode-dts/vscode.proposed.scmProviderOptions.d.ts
 
-declare module '@theia/plugin' {
+export module '@theia/plugin' {
     // https://github.com/microsoft/vscode/issues/254910
 
     export interface SourceControl {

package/src/theia.proposed.statusBarItemTooltip.d.ts

@@ -21,7 +21,7 @@
 
 // Copied from https://github.com/microsoft/vscode/blob/85f2ce803d86e9fddeba10874fc2758a75b8e806/src/vscode-dts/vscode.proposed.statusBarItemTooltip.d.ts
 
-declare module '@theia/plugin' {
+export module '@theia/plugin' {
 
     // https://github.com/microsoft/vscode/issues/234339
 

package/src/theia.proposed.terminalCompletionProvider.d.ts

@@ -18,16 +18,28 @@
  *  Copyright (c) Microsoft Corporation. All rights reserved.
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
-// code copied and modified from https://github.com/microsoft/vscode/blob/1.96.2/src/vscode-dts/vscode.proposed.terminalCompletionProvider.d.ts
+// code copied and modified from https://github.com/microsoft/vscode/blob/1.105.0/src/vscode-dts/vscode.proposed.terminalCompletionProvider.d.ts
 
-declare module '@theia/plugin' {
+export module '@theia/plugin' {
 
     // https://github.com/microsoft/vscode/issues/226562
 
+    /**
+     * A provider that supplies terminal completion items.
+     *
+     * Implementations of this interface should return an array of {@link TerminalCompletionItem} or a
+     * {@link TerminalCompletionList} describing completions for the current command line.
+     *
+     * @example <caption>Simple provider returning a single completion</caption>
+     * window.registerTerminalCompletionProvider('extension-provider-id', {
+     *  provideTerminalCompletions(terminal, context) {
+     *      return [{ label: '--help', replacementIndex: Math.max(0, context.cursorPosition - 2), replacementLength: 2 }];
+     *  }
+     * });
+     */
     export interface TerminalCompletionProvider<T extends TerminalCompletionItem> {
-        id: string;
         /**
-         * Provide completions for the given position and document.
+         * Provide completions for the given terminal and context.
          * @param terminal The terminal for which completions are being provided.
          * @param context Information about the terminal's current state.
          * @param token A cancellation token.
@@ -36,11 +48,26 @@ declare module '@theia/plugin' {
         provideTerminalCompletions(terminal: Terminal, context: TerminalCompletionContext, token: CancellationToken): ProviderResult<T[] | TerminalCompletionList<T>>;
     }
 
+    /**
+     * Represents a completion suggestion for a terminal command line.
+     *
+     * @example <caption>Completion item for `ls -|`</caption>
+     * const item = {
+     *  label: '-A',
+     *  replacementIndex: 3,
+     *  replacementLength: 1,
+     *  detail: 'List all entries except for . and .. (always set for the super-user)',
+     *  kind: TerminalCompletionItemKind.Flag
+     * };
+     *
+     * The fields on a completion item describe what text should be shown to the user
+     * and which portion of the command line should be replaced when the item is accepted.
+     */
     export interface TerminalCompletionItem {
         /**
          * The label of the completion.
          */
-        label: string;
+        label: string | CompletionItemLabel;
 
         /**
          * The index of the start of the range to replace.
@@ -57,6 +84,11 @@ declare module '@theia/plugin' {
          */
         detail?: string;
 
+        /**
+         * A human-readable string that represents a doc-comment.
+         */
+        documentation?: string | MarkdownString;
+
         /**
          * The completion's kind. Note that this will map to an icon.
          */
@@ -64,7 +96,11 @@ declare module '@theia/plugin' {
     }
 
     /**
-     * Terminal item kinds.
+     * The kind of an individual terminal completion item.
+     *
+     * The kind is used to render an appropriate icon in the suggest list and to convey the semantic
+     * meaning of the suggestion (file, folder, flag, commit, branch, etc.).
+     *
      */
     export enum TerminalCompletionItemKind {
         File = 0,
@@ -86,32 +122,56 @@ declare module '@theia/plugin' {
         PullRequestDone = 16,
     }
 
+    /**
+     * Context information passed to {@link TerminalCompletionProvider.provideTerminalCompletions}.
+     *
+     * It contains the full command line, the current cursor position, and a flag indicating whether
+     * fallback completions are allowed when the exact completion type cannot be determined.
+     */
     export interface TerminalCompletionContext {
         /**
          * The complete terminal command line.
          */
         commandLine: string;
         /**
-         * The index of the
-         * cursor in the command line.
+         * The index of the cursor in the command line.
          */
         cursorPosition: number;
+        /**
+         * Whether completions should be provided when it is not clear to what type of completion is
+         * well known.
+         */
+        allowFallbackCompletions: boolean;
     }
 
     export namespace window {
         /**
-         * Register a completion provider for a certain type of terminal.
-         *
+         * Register a completion provider for terminals.
+         * @param id The unique identifier of the terminal provider, used as a settings key and shown in the information hover of the suggest widget.
          * @param provider The completion provider.
          * @returns A {@link Disposable} that unregisters this provider when being disposed.
-         * @stubbed
-         */
-        export function registerTerminalCompletionProvider<T extends TerminalCompletionItem>(provider: TerminalCompletionProvider<T>, ...triggerCharacters: string[]): Disposable;
+         *
+         * @example <caption>Register a provider for an extension</caption>
+         * window.registerTerminalCompletionProvider('extension-provider-id', {
+         *  provideTerminalCompletions(terminal, context) {
+         *      return new TerminalCompletionList([
+         *          { label: '--version', replacementIndex: Math.max(0, context.cursorPosition - 2), replacementLength: 2 }
+         *      ]);
+         *  }
+         * });
+         */
+        export function registerTerminalCompletionProvider<T extends TerminalCompletionItem>(
+            id: string, provider: TerminalCompletionProvider<T>, ...triggerCharacters: string[]): Disposable;
     }
 
     /**
      * Represents a collection of {@link TerminalCompletionItem completion items} to be presented
      * in the terminal.
+     *
+     * @example <caption>Create a completion list that requests files for the terminal cwd</caption>
+     * const list = new TerminalCompletionList([
+     *  { label: 'ls', replacementIndex: 0, replacementLength: 0, kind: TerminalCompletionItemKind.Method }
+     * ], { filesRequested: true, cwd: Uri.file('/home/user') });
      */
     export class TerminalCompletionList<T extends TerminalCompletionItem = TerminalCompletionItem> {
 
@@ -134,6 +194,12 @@ declare module '@theia/plugin' {
         constructor(items?: T[], resourceRequestConfig?: TerminalResourceRequestConfig);
     }
 
+    /**
+     * Configuration for requesting file and folder resources to be shown as completions.
+     *
+     * When a provider indicates that it wants file/folder resources, the terminal will surface completions for files and
+     * folders that match {@link globPattern} from the provided {@link cwd}.
+     */
     export interface TerminalResourceRequestConfig {
         /**
          * Show files as completion items.
@@ -144,12 +210,12 @@ declare module '@theia/plugin' {
          */
         foldersRequested?: boolean;
         /**
-         * If no cwd is provided, no resources will be shown as completions.
+         * A {@link GlobPattern glob pattern} that controls which files suggest should surface.
          */
-        cwd?: Uri;
+        globPattern?: GlobPattern;
         /**
-         * The path separator to use when constructing paths.
+         * The cwd from which to request resources.
          */
-        pathSeparator: string;
+        cwd: Uri;
     }
 }

package/src/theia.proposed.textEditorDiffInformation.d.ts

@@ -20,7 +20,7 @@
  *--------------------------------------------------------------------------------------------*/
 // code copied and modified from https://github.com/microsoft/vscode/blob/1.103.2/src/vscode-dts/vscode.proposed.textEditorDiffInformation.d.ts
 
-declare module '@theia/plugin' {
+export module '@theia/plugin' {
     // https://github.com/microsoft/vscode/issues/84899
 
     export enum TextEditorChangeKind {