stub TerminalCompletionProvider proposed API

fixes #14604

contributed on behalf of STMicroelectronics

Signed-off-by: Remi Schnekenburger <[email protected]>

Author: rschnekenbu

packages/plugin-ext/src/plugin/plugin-context.ts

@@ -236,7 +236,9 @@ import {
     PortAutoForwardAction,
     PortAttributes,
     DebugVisualization,
-    TerminalShellExecutionCommandLineConfidence
+    TerminalShellExecutionCommandLineConfidence,
+    TerminalCompletionItemKind,
+    TerminalCompletionList
 } from './types-impl';
 import { AuthenticationExtImpl } from './authentication-ext';
 import { SymbolKind } from '../common/plugin-api-rpc-model';
@@ -656,6 +658,13 @@ export function createAPIFactory(
             registerProfileContentHandler(id: string, profileContentHandler: theia.ProfileContentHandler): theia.Disposable {
                 return Disposable.NULL;
             },
+            /** @stubbed TerminalCompletionProvider */
+            registerTerminalCompletionProvider<T extends theia.TerminalCompletionItem>(
+                provider: theia.TerminalCompletionProvider<T>,
+                ...triggerCharacters: string[]
+            ): theia.Disposable {
+                return Disposable.NULL;
+            },
             /** @stubbed TerminalQuickFixProvider */
             registerTerminalQuickFixProvider(id: string, provider: theia.TerminalQuickFixProvider): theia.Disposable {
                 return terminalExt.registerTerminalQuickFixProvider(id, provider);
@@ -1570,7 +1579,9 @@ export function createAPIFactory(
             PortAutoForwardAction,
             PortAttributes,
             DebugVisualization,
-            TerminalShellExecutionCommandLineConfidence
+            TerminalShellExecutionCommandLineConfidence,
+            TerminalCompletionItemKind,
+            TerminalCompletionList
         };
     };
 }

packages/plugin-ext/src/plugin/types-impl.ts

@@ -3842,6 +3842,33 @@ export enum EditSessionIdentityMatch {
 }
 // #endregion
 
+// #region terminalCompletionProvider
+export class TerminalCompletionList<T extends theia.TerminalCompletionItem> {
+
+    resourceRequestConfig?: theia.TerminalResourceRequestConfig;
+
+    items: T[];
+
+    /**
+     * Creates a new completion list.
+     *
+     * @param items The completion items.
+     * @param resourceRequestConfig Indicates which resources should be shown as completions for the cwd of the terminal.
+     * @stubbed
+     */
+    constructor(items?: T[], resourceRequestConfig?: theia.TerminalResourceRequestConfig) {
+    }
+}
+
+export enum TerminalCompletionItemKind {
+    File = 0,
+    Folder = 1,
+    Flag = 2,
+    Method = 3,
+    Argument = 4
+}
+// #endregion
+
 // #region terminalQuickFixProvider
 export class TerminalQuickFixTerminalCommand {
     /**

packages/plugin/src/theia.d.ts

@@ -43,6 +43,7 @@ import './theia.proposed.profileContentHandlers';
 import './theia.proposed.resolvers';
 import './theia.proposed.scmValidation';
 import './theia.proposed.shareProvider';
+import './theia.proposed.terminalCompletionProvider';
 import './theia.proposed.terminalQuickFixProvider';
 import './theia.proposed.textSearchProvider';
 import './theia.proposed.timeline';

packages/plugin/src/theia.proposed.terminalCompletionProvider.d.ts

@@ -0,0 +1,143 @@
+// *****************************************************************************
+// Copyright (C) 2025 STMicroelectronics and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+/*---------------------------------------------------------------------------------------------
+ *  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
+
+declare module '@theia/plugin' {
+
+    // https://github.com/microsoft/vscode/issues/226562
+
+    export interface TerminalCompletionProvider<T extends TerminalCompletionItem> {
+        id: string;
+        /**
+         * Provide completions for the given position and document.
+         * @param terminal The terminal for which completions are being provided.
+         * @param context Information about the terminal's current state.
+         * @param token A cancellation token.
+         * @return A list of completions.
+         */
+        provideTerminalCompletions(terminal: Terminal, context: TerminalCompletionContext, token: CancellationToken): ProviderResult<T[] | TerminalCompletionList<T>>;
+    }
+
+    export interface TerminalCompletionItem {
+        /**
+         * The label of the completion.
+         */
+        label: string;
+
+        /**
+         * The index of the start of the range to replace.
+         */
+        replacementIndex: number;
+
+        /**
+         * The length of the range to replace.
+         */
+        replacementLength: number;
+
+        /**
+         * The completion's detail which appears on the right of the list.
+         */
+        detail?: string;
+
+        /**
+         * The completion's kind. Note that this will map to an icon.
+         */
+        kind?: TerminalCompletionItemKind;
+    }
+
+    /**
+     * Terminal item kinds.
+     */
+    export enum TerminalCompletionItemKind {
+        File = 0,
+        Folder = 1,
+        Flag = 2,
+        Method = 3,
+        Argument = 4
+    }
+
+    export interface TerminalCompletionContext {
+        /**
+         * The complete terminal command line.
+         */
+        commandLine: string;
+        /**
+         * The index of the
+         * cursor in the command line.
+         */
+        cursorPosition: number;
+    }
+
+    export namespace window {
+        /**
+         * Register a completion provider for a certain type of terminal.
+         *
+         * @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;
+    }
+
+    /**
+     * Represents a collection of {@link TerminalCompletionItem completion items} to be presented
+     * in the terminal.
+     */
+    export class TerminalCompletionList<T extends TerminalCompletionItem = TerminalCompletionItem> {
+
+        /**
+         * Resources that should be shown in the completions list for the cwd of the terminal.
+         */
+        resourceRequestConfig?: TerminalResourceRequestConfig;
+
+        /**
+         * The completion items.
+         */
+        items: T[];
+
+        /**
+         * Creates a new completion list.
+         *
+         * @param items The completion items.
+         * @param resourceRequestConfig Indicates which resources should be shown as completions for the cwd of the terminal.
+         */
+        constructor(items?: T[], resourceRequestConfig?: TerminalResourceRequestConfig);
+    }
+
+    export interface TerminalResourceRequestConfig {
+        /**
+         * Show files as completion items.
+         */
+        filesRequested?: boolean;
+        /**
+         * Show folders as completion items.
+         */
+        foldersRequested?: boolean;
+        /**
+         * If no cwd is provided, no resources will be shown as completions.
+         */
+        cwd?: Uri;
+        /**
+         * The path separator to use when constructing paths.
+         */
+        pathSeparator: string;
+    }
+}