@theia/plugin 1.37.1 → 1.38.0-next.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.37.1",
+  "version": "1.38.0-next.27+39dfc8ca1",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -27,10 +27,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.37.1"
+    "@theia/ext-scripts": "1.37.0"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "3bc4e97b2f730db070f596e97f3bd6e331ad8414"
+  "gitHead": "39dfc8ca1294b972c693e5c3b31f5f6685238d10"
 }

package/src/theia-proposed.d.ts

@@ -613,7 +613,153 @@ export module '@theia/plugin' {
 
     }
 
+    // #region DocumentPaste
+
+    // https://github.com/microsoft/vscode/issues/30066/
+
+    /**
+     * Provider invoked when the user copies and pastes code.
+     */
+    export interface DocumentPasteEditProvider {
+
+        /**
+         * Optional method invoked after the user copies text in a file.
+         *
+         * During {@link prepareDocumentPaste}, an extension can compute metadata that is attached to
+         * a {@link DataTransfer} and is passed back to the provider in {@link provideDocumentPasteEdits}.
+         *
+         * @param document Document where the copy took place.
+         * @param ranges Ranges being copied in the `document`.
+         * @param dataTransfer The data transfer associated with the copy. You can store additional values on this for later use in  {@link provideDocumentPasteEdits}.
+         * @param token A cancellation token.
+         */
+        prepareDocumentPaste?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, token: CancellationToken): void | Thenable<void>;
+
+        /**
+         * Invoked before the user pastes into a document.
+         *
+         * In this method, extensions can return a workspace edit that replaces the standard pasting behavior.
+         *
+         * @param document Document being pasted into
+         * @param ranges Currently selected ranges in the document.
+         * @param dataTransfer The data transfer associated with the paste.
+         * @param token A cancellation token.
+         *
+         * @return Optional workspace edit that applies the paste. Return undefined to use standard pasting.
+         */
+        provideDocumentPasteEdits(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, token: CancellationToken): ProviderResult<DocumentPasteEdit>;
+    }
+
+    /**
+     * An operation applied on paste
+     */
+    class DocumentPasteEdit {
+        /**
+         * The text or snippet to insert at the pasted locations.
+         */
+        insertText: string | SnippetString;
+
+        /**
+         * An optional additional edit to apply on paste.
+         */
+        additionalEdit?: WorkspaceEdit;
+
+        /**
+         * @param insertText The text or snippet to insert at the pasted locations.
+         */
+        constructor(insertText: string | SnippetString);
+    }
+
+    interface DocumentPasteProviderMetadata {
+        /**
+         * Mime types that `provideDocumentPasteEdits` should be invoked for.
+         *
+         * Use the special `files` mimetype to indicate the provider should be invoked if any files are present in the `DataTransfer`.
+         */
+        readonly pasteMimeTypes: readonly string[];
+    }
+
+    namespace languages {
+        export function registerDocumentPasteEditProvider(selector: DocumentSelector, provider: DocumentPasteEditProvider, metadata: DocumentPasteProviderMetadata): Disposable;
+    }
+    // #endregion
+
+    // #region SessionIdentityProvider
+    export namespace workspace {
+        /**
+         *
+         * @param scheme The URI scheme that this provider can provide edit session identities for.
+         * @param provider A provider which can convert URIs for workspace folders of scheme @param scheme to
+         * an edit session identifier which is stable across machines. This enables edit sessions to be resolved.
+         */
+        export function registerEditSessionIdentityProvider(scheme: string, provider: EditSessionIdentityProvider): Disposable;
+    }
+
+    export interface EditSessionIdentityProvider {
+        /**
+         *
+         * @param workspaceFolder The workspace folder to provide an edit session identity for.
+         * @param token A cancellation token for the request.
+         * @returns An string representing the edit session identity for the requested workspace folder.
+         */
+        provideEditSessionIdentity(workspaceFolder: WorkspaceFolder, token: CancellationToken): ProviderResult<string>;
+    }
+
     // #endregion
+
+    // #region ProfileContentHandler
+
+    export interface ProfileContentHandler {
+        readonly name: string;
+        saveProfile(name: string, content: string, token: CancellationToken): Thenable<Uri | null>;
+        readProfile(uri: Uri, token: CancellationToken): Thenable<string | null>;
+    }
+
+    export namespace window {
+        export function registerProfileContentHandler(id: string, profileContentHandler: ProfileContentHandler): Disposable;
+    }
+
+    // #endregion ProfileContentHandler
+
+    // #region TerminalQuickFixProvider
+
+    export namespace window {
+        /**
+         * @param provider A terminal quick fix provider
+         * @return A {@link Disposable} that un-registers the provider when being disposed
+         */
+        export function registerTerminalQuickFixProvider(id: string, provider: TerminalQuickFixProvider): Disposable;
+    }
+
+    export interface TerminalQuickFixProvider {
+        /**
+         * Provides terminal quick fixes
+         * @param commandMatchResult The command match result for which to provide quick fixes
+         * @param token A cancellation token indicating the result is no longer needed
+         * @return Terminal quick fix(es) if any
+         */
+        provideTerminalQuickFixes(commandMatchResult: TerminalCommandMatchResult, token: CancellationToken): TerminalQuickFix[] | TerminalQuickFix | undefined;
+    }
+
+    export interface TerminalCommandMatchResult {
+        commandLine: string;
+        commandLineMatch: RegExpMatchArray;
+        outputMatch?: {
+            regexMatch: RegExpMatchArray;
+            outputLines?: string[];
+        };
+    }
+
+    interface TerminalQuickFix {
+        type: TerminalQuickFixType;
+    }
+
+    enum TerminalQuickFixType {
+        command = 'command',
+        opener = 'opener'
+    }
+
+    // #endRegion TerminalQuickFixProvider
 }
 
 /**

package/src/theia.d.ts

@@ -22,6 +22,7 @@
  *--------------------------------------------------------------------------------------------*/
 import './theia-extra';
 import './theia-proposed';
+import './theia.proposed.externalUriOpener';
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable max-len */
@@ -7565,6 +7566,15 @@ export module '@theia/plugin' {
          */
         export const onDidChangeTelemetryEnabled: Event<boolean>;
 
+        /**
+         * Creates a new {@link TelemetryLogger telemetry logger}.
+         *
+         * @param sender The telemetry sender that is used by the telemetry logger.
+         * @param options Options for the telemetry logger.
+         * @returns A new telemetry logger
+         */
+        export function createTelemetryLogger(sender: TelemetrySender, options?: TelemetryLoggerOptions): TelemetryLogger;
+
         /**
          * The name of a remote. Defined by extensions, popular samples are `wsl` for the Windows
          * Subsystem for Linux or `ssh-remote` for remotes using a secure shell.
@@ -14209,6 +14219,144 @@ export module '@theia/plugin' {
         close(tabGroup: TabGroup | readonly TabGroup[], preserveFocus?: boolean): Thenable<boolean>;
     }
 
+    /**
+     * A special value wrapper denoting a value that is safe to not clean.
+     * This is to be used when you can guarantee no identifiable information is contained in the value and the cleaning is improperly redacting it.
+     */
+    export class TelemetryTrustedValue<T = any> {
+        readonly value: T;
+
+        constructor(value: T);
+    }
+
+    /**
+     * A telemetry logger which can be used by extensions to log usage and error telemetry.
+     *
+     * A logger wraps around a {@link TelemetrySender sender} but it guarantees that
+     * - user settings to disable or tweak telemetry are respected, and that
+     * - potential sensitive data is removed
+     *
+     * It also enables an "echo UI" that prints whatever data is send and it allows the editor
+     * to forward unhandled errors to the respective extensions.
+     *
+     * To get an instance of a `TelemetryLogger`, use
+     * {@link env.createTelemetryLogger `createTelemetryLogger`}.
+     */
+    export interface TelemetryLogger {
+
+        /**
+         * An {@link Event} which fires when the enablement state of usage or error telemetry changes.
+         */
+        readonly onDidChangeEnableStates: Event<TelemetryLogger>;
+
+        /**
+         * Whether or not usage telemetry is enabled for this logger.
+         */
+        readonly isUsageEnabled: boolean;
+
+        /**
+         * Whether or not error telemetry is enabled for this logger.
+         */
+        readonly isErrorsEnabled: boolean;
+
+        /**
+         * Log a usage event.
+         *
+         * After completing cleaning, telemetry setting checks, and data mix-in calls `TelemetrySender.sendEventData` to log the event.
+         * Automatically supports echoing to extension telemetry output channel.
+         * @param eventName The event name to log
+         * @param data The data to log
+         */
+        logUsage(eventName: string, data?: Record<string, any | TelemetryTrustedValue>): void;
+
+        /**
+         * Log an error event.
+         *
+         * After completing cleaning, telemetry setting checks, and data mix-in calls `TelemetrySender.sendEventData` to log the event. Differs from `logUsage` in that it will log the event if the telemetry setting is Error+.
+         * Automatically supports echoing to extension telemetry output channel.
+         * @param eventName The event name to log
+         * @param data The data to log
+         */
+        logError(eventName: string, data?: Record<string, any | TelemetryTrustedValue>): void;
+
+        /**
+         * Log an error event.
+         *
+         * Calls `TelemetrySender.sendErrorData`. Does cleaning, telemetry checks, and data mix-in.
+         * Automatically supports echoing to extension telemetry output channel.
+         * Will also automatically log any exceptions thrown within the extension host process.
+         * @param error The error object which contains the stack trace cleaned of PII
+         * @param data Additional data to log alongside the stack trace
+         */
+        logError(error: Error, data?: Record<string, any | TelemetryTrustedValue>): void;
+
+        /**
+         * Dispose this object and free resources.
+         */
+        dispose(): void;
+    }
+
+    /**
+     * The telemetry sender is the contract between a telemetry logger and some telemetry service. **Note** that extensions must NOT
+     * call the methods of their sender directly as the logger provides extra guards and cleaning.
+     *
+     * ```js
+     * const sender: vscode.TelemetrySender = {...};
+     * const logger = vscode.env.createTelemetryLogger(sender);
+     *
+     * // GOOD - uses the logger
+     * logger.logUsage('myEvent', { myData: 'myValue' });
+     *
+     * // BAD - uses the sender directly: no data cleansing, ignores user settings, no echoing to the telemetry output channel etc
+     * sender.logEvent('myEvent', { myData: 'myValue' });
+     * ```
+     */
+    export interface TelemetrySender {
+        /**
+         * Function to send event data without a stacktrace. Used within a {@link TelemetryLogger}
+         *
+         * @param eventName The name of the event which you are logging
+         * @param data A serializable key value pair that is being logged
+         */
+        sendEventData(eventName: string, data?: Record<string, any>): void;
+
+        /**
+         * Function to send an error. Used within a {@link TelemetryLogger}
+         *
+         * @param error The error being logged
+         * @param data Any additional data to be collected with the exception
+         */
+        sendErrorData(error: Error, data?: Record<string, any>): void;
+
+        /**
+         * Optional flush function which will give this sender a chance to send any remaining events
+         * as its {@link TelemetryLogger} is being disposed
+         */
+        flush?(): void | Thenable<void>;
+    }
+
+    /**
+     * Options for creating a {@link TelemetryLogger}
+     */
+    export interface TelemetryLoggerOptions {
+        /**
+         * Whether or not you want to avoid having the built-in common properties such as os, extension name, etc injected into the data object.
+         * Defaults to `false` if not defined.
+         */
+        readonly ignoreBuiltInCommonProperties?: boolean;
+
+        /**
+         * Whether or not unhandled errors on the extension host caused by your extension should be logged to your sender.
+         * Defaults to `false` if not defined.
+         */
+        readonly ignoreUnhandledErrors?: boolean;
+
+        /**
+         * Any additional common properties which should be injected into the data object.
+         */
+        readonly additionalCommonProperties?: Record<string, any>;
+    }
+
     /**
      * Represents a notebook editor that is attached to a {@link NotebookDocument notebook}.
      */

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

@@ -0,0 +1,158 @@
+// *****************************************************************************
+// Copyright (C) 2023 Ericsson 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 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://vscode.dev/github/microsoft/vscode/blob/1.77.3/src/vscode-dts/vscode.proposed.externalUriOpener.d.ts
+
+export module '@theia/plugin' {
+    /**
+     * Details if an `ExternalUriOpener` can open a uri.
+     *
+     * The priority is also used to rank multiple openers against each other and determine
+     * if an opener should be selected automatically or if the user should be prompted to
+     * select an opener.
+     *
+     * The editor will try to use the best available opener, as sorted by `ExternalUriOpenerPriority`.
+     * If there are multiple potential "best" openers for a URI, then the user will be prompted
+     * to select an opener.
+     */
+    export enum ExternalUriOpenerPriority {
+        /**
+         * The opener is disabled and will never be shown to users.
+         *
+         * Note that the opener can still be used if the user specifically
+         * configures it in their settings.
+         */
+        None = 0,
+
+        /**
+         * The opener can open the uri but will not cause a prompt on its own
+         * since the editor always contributes a built-in `Default` opener.
+         */
+        Option = 1,
+
+        /**
+         * The opener can open the uri.
+         *
+         * The editor's built-in opener has `Default` priority. This means that any additional `Default`
+         * openers will cause the user to be prompted to select from a list of all potential openers.
+         */
+        Default = 2,
+
+        /**
+         * The opener can open the uri and should be automatically selected over any
+         * default openers, include the built-in one from the editor.
+         *
+         * A preferred opener will be automatically selected if no other preferred openers
+         * are available. If multiple preferred openers are available, then the user
+         * is shown a prompt with all potential openers (not just preferred openers).
+         */
+        Preferred = 3,
+    }
+
+    /**
+     * Handles opening uris to external resources, such as http(s) links.
+     *
+     * Extensions can implement an `ExternalUriOpener` to open `http` links to a webserver
+     * inside of the editor instead of having the link be opened by the web browser.
+     *
+     * Currently openers may only be registered for `http` and `https` uris.
+     */
+    export interface ExternalUriOpener {
+
+        /**
+         * Check if the opener can open a uri.
+         *
+         * @param uri The uri being opened. This is the uri that the user clicked on. It has
+         * not yet gone through port forwarding.
+         * @param token Cancellation token indicating that the result is no longer needed.
+         *
+         * @return Priority indicating if the opener can open the external uri.
+         */
+        canOpenExternalUri(uri: Uri, token: CancellationToken): ExternalUriOpenerPriority | Thenable<ExternalUriOpenerPriority>;
+
+        /**
+         * Open a uri.
+         *
+         * This is invoked when:
+         *
+         * - The user clicks a link which does not have an assigned opener. In this case, first `canOpenExternalUri`
+         *   is called and if the user selects this opener, then `openExternalUri` is called.
+         * - The user sets the default opener for a link in their settings and then visits a link.
+         *
+         * @param resolvedUri The uri to open. This uri may have been transformed by port forwarding, so it
+         * may not match the original uri passed to `canOpenExternalUri`. Use `ctx.originalUri` to check the
+         * original uri.
+         * @param ctx Additional information about the uri being opened.
+         * @param token Cancellation token indicating that opening has been canceled.
+         *
+         * @return Thenable indicating that the opening has completed.
+         */
+        openExternalUri(resolvedUri: Uri, ctx: OpenExternalUriContext, token: CancellationToken): Thenable<void> | void;
+    }
+
+    /**
+     * Additional information about the uri being opened.
+     */
+    export interface OpenExternalUriContext {
+        /**
+         * The uri that triggered the open.
+         *
+         * This is the original uri that the user clicked on or that was passed to `openExternal.`
+         * Due to port forwarding, this may not match the `resolvedUri` passed to `openExternalUri`.
+         */
+        readonly sourceUri: Uri;
+    }
+
+    /**
+     * Additional metadata about a registered `ExternalUriOpener`.
+     */
+    interface ExternalUriOpenerMetadata {
+
+        /**
+         * List of uri schemes the opener is triggered for.
+         *
+         * Currently only `http` and `https` are supported.
+         */
+        readonly schemes: readonly string[];
+
+        /**
+         * Text displayed to the user that explains what the opener does.
+         *
+         * For example, 'Open in browser preview'
+         */
+        readonly label: string;
+    }
+
+    export namespace window {
+        /**
+         * Register a new `ExternalUriOpener`.
+         *
+         * When a uri is about to be opened, an `onOpenExternalUri:SCHEME` activation event is fired.
+         *
+         * @param id Unique id of the opener, such as `myExtension.browserPreview`. This is used in settings
+         *   and commands to identify the opener.
+         * @param opener Opener to register.
+         * @param metadata Additional information about the opener.
+         *
+         * @returns Disposable that unregisters the opener.
+         */
+        export function registerExternalUriOpener(id: string, opener: ExternalUriOpener, metadata: ExternalUriOpenerMetadata): Disposable;
+    }
+}