@theia/plugin-ext-headless 1.46.0-next.72

package/src/hosted/node/scanners/scanner-theia-headless.ts

@@ -0,0 +1,85 @@
+// *****************************************************************************
+// Copyright (C) 2024 EclipseSource 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
+// *****************************************************************************
+
+/* eslint-disable @theia/localization-check */
+
+import { injectable } from '@theia/core/shared/inversify';
+import { DeployedPlugin, PluginPackage, PluginEntryPoint } from '@theia/plugin-ext';
+import { AbstractPluginScanner } from '@theia/plugin-ext/lib/hosted/node/scanners/scanner-theia';
+import { deepClone } from '@theia/core/lib/common/objects';
+
+@injectable()
+export class TheiaHeadlessPluginScanner extends AbstractPluginScanner {
+
+    constructor() {
+        super('theiaHeadlessPlugin');
+    }
+
+    protected getEntryPoint(plugin: PluginPackage): PluginEntryPoint {
+        if (plugin?.theiaPlugin?.headless) {
+            return {
+                headless: plugin.theiaPlugin.headless
+            };
+        };
+
+        return {
+            headless: plugin.main
+        };
+    }
+
+    /**
+     * Adapt the given `plugin`'s metadata for headless deployment, where it does not
+     * already natively specify its headless deployment, such as is the case for plugins
+     * declaring the `"vscode"` or `"theiaPlugin"` engine. This consists of cloning the
+     * relevant properties of its deployment metadata and modifying them as required,
+     * including but not limited to:
+     *
+     * - renaming the `lifecycle` start and stop functions as 'activate' and 'deactivate'
+     *   following the VS Code naming convention (in case the `plugin` is a Theia-style
+     *   plugin that uses 'start' and 'stop')
+     * - deleting inapplicable information such as frontend and backend init script paths
+     * - filtering/rewriting contributions and/or activation events
+     *
+     * The cloning is necessary to retain the original information for the non-headless
+     * deployments that the plugin also supports.
+     */
+    adaptForHeadless(plugin: DeployedPlugin): DeployedPlugin {
+        return {
+            type: plugin.type,
+            metadata: this.adaptMetadataForHeadless(plugin),
+            contributes: this.adaptContributesForHeadless(plugin)
+        };
+    }
+
+    protected adaptMetadataForHeadless(plugin: DeployedPlugin): DeployedPlugin['metadata'] {
+        const result = deepClone(plugin.metadata);
+
+        const lifecycle = result.lifecycle;
+        delete lifecycle.frontendInitPath;
+        delete lifecycle.backendInitPath;
+
+        // Same as in VS Code
+        lifecycle.startMethod = 'activate';
+        lifecycle.stopMethod = 'deactivate';
+
+        return result;
+    }
+
+    protected adaptContributesForHeadless(plugin: DeployedPlugin): DeployedPlugin['contributes'] {
+        // We don't yet support and contribution points in headless plugins
+        return undefined;
+    }
+}

package/src/hosted/node-electron/plugin-ext-headless-hosted-electron-module.ts

@@ -0,0 +1,22 @@
+// *****************************************************************************
+// Copyright (C) 2024 EclipseSource 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
+// *****************************************************************************
+
+import { interfaces } from '@theia/core/shared/inversify';
+import { bindCommonHostedBackend } from '../node/plugin-ext-headless-hosted-module';
+
+export function bindElectronBackend(bind: interfaces.Bind): void {
+    bindCommonHostedBackend(bind);
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// *****************************************************************************
+// Copyright (C) 2024 EclipseSource 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
+// *****************************************************************************
+
+export * from './common';

package/src/main/node/handlers/plugin-theia-headless-directory-handler.ts

@@ -0,0 +1,35 @@
+// *****************************************************************************
+// Copyright (C) 2024 EclipseSource 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
+// *****************************************************************************
+
+import { injectable } from '@theia/core/shared/inversify';
+
+import { PluginDeployerDirectoryHandlerContext, PluginDeployerEntryType, PluginPackage } from '@theia/plugin-ext';
+import { AbstractPluginDirectoryHandler } from '@theia/plugin-ext/lib/main/node/handlers/plugin-theia-directory-handler';
+
+@injectable()
+export class PluginTheiaHeadlessDirectoryHandler extends AbstractPluginDirectoryHandler {
+
+    protected acceptManifest(plugin: PluginPackage): boolean {
+        return plugin?.engines?.theiaPlugin === undefined && 'theiaHeadlessPlugin' in plugin.engines;
+    }
+
+    async handle(context: PluginDeployerDirectoryHandlerContext): Promise<void> {
+        await this.copyDirectory(context);
+        const types: PluginDeployerEntryType[] = [PluginDeployerEntryType.HEADLESS];
+        context.pluginEntry().accept(...types);
+    }
+
+}

package/src/main/node/headless-progress-client.ts

@@ -0,0 +1,44 @@
+// *****************************************************************************
+// Copyright (C) 2024 EclipseSource 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
+// *****************************************************************************
+
+import { injectable } from '@theia/core/shared/inversify';
+import {
+    CancellationToken,
+    ProgressClient, ProgressMessage, ProgressUpdate
+} from '@theia/core';
+
+/**
+ * A simple progress client for headless plugins that just writes debug messages to the console
+ * because there is no one connected frontend to which it is appropriate to send the messages.
+ */
+@injectable()
+export class HeadlessProgressClient implements ProgressClient {
+    async showProgress(_progressId: string, message: ProgressMessage, cancellationToken: CancellationToken): Promise<string | undefined> {
+        if (cancellationToken.isCancellationRequested) {
+            return ProgressMessage.Cancel;
+        }
+        console.debug(message.text);
+    }
+
+    async reportProgress(_progressId: string, update: ProgressUpdate, message: ProgressMessage, cancellationToken: CancellationToken): Promise<void> {
+        if (cancellationToken.isCancellationRequested) {
+            return;
+        }
+        const progress = update.work && update.work.total ? `[${100 * Math.min(update.work.done, update.work.total) / update.work.total}%]` : '';
+        const text = `${progress} ${update.message ?? 'completed ...'}`;
+        console.debug(text);
+    }
+}

package/src/main/node/main-context.ts

@@ -0,0 +1,35 @@
+// *****************************************************************************
+// Copyright (C) 2024 EclipseSource 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
+// *****************************************************************************
+import { interfaces } from '@theia/core/shared/inversify';
+import { RPCProtocol } from '@theia/plugin-ext/lib/common/rpc-protocol';
+import { EnvMainImpl } from '@theia/plugin-ext/lib/main/common/env-main';
+import { BasicMessageRegistryMainImpl } from '@theia/plugin-ext/lib/main/common/basic-message-registry-main';
+import { BasicNotificationMainImpl } from '@theia/plugin-ext/lib/main/common/basic-notification-main';
+
+import { HEADLESSMAIN_RPC_CONTEXT, HEADLESSPLUGIN_RPC_CONTEXT } from '../../common/headless-plugin-rpc';
+
+// This sets up only the minimal plugin API required by the plugin manager to report
+// messages and notifications to the main side and to initialize plugins.
+export function setUpPluginApi(rpc: RPCProtocol, container: interfaces.Container): void {
+    const envMain = new EnvMainImpl(rpc, container);
+    rpc.set(HEADLESSPLUGIN_RPC_CONTEXT.ENV_MAIN, envMain);
+
+    const messageRegistryMain = new BasicMessageRegistryMainImpl(container);
+    rpc.set(HEADLESSPLUGIN_RPC_CONTEXT.MESSAGE_REGISTRY_MAIN, messageRegistryMain);
+
+    const notificationMain = new BasicNotificationMainImpl(rpc, container, HEADLESSMAIN_RPC_CONTEXT.NOTIFICATION_EXT);
+    rpc.set(HEADLESSPLUGIN_RPC_CONTEXT.NOTIFICATION_MAIN, notificationMain);
+}

package/src/main/node/plugin-ext-headless-main-module.ts

@@ -0,0 +1,42 @@
+// *****************************************************************************
+// Copyright (C) 2024 EclipseSource 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
+// *****************************************************************************
+
+import { interfaces } from '@theia/core/shared/inversify';
+import {
+    MessageClient, MessageService,
+    ProgressClient, ProgressService,
+    bindContributionProvider
+} from '@theia/core';
+import { MainPluginApiProvider, PluginDeployerDirectoryHandler } from '@theia/plugin-ext';
+import { PluginTheiaHeadlessDirectoryHandler } from './handlers/plugin-theia-headless-directory-handler';
+import { HeadlessProgressClient } from './headless-progress-client';
+
+export function bindHeadlessMain(bind: interfaces.Bind): void {
+    bind(PluginDeployerDirectoryHandler).to(PluginTheiaHeadlessDirectoryHandler).inSingletonScope();
+}
+
+export function bindBackendMain(bind: interfaces.Bind, unbind: interfaces.Unbind, isBound: interfaces.IsBound, rebind: interfaces.Rebind): void {
+    bindContributionProvider(bind, MainPluginApiProvider);
+
+    //
+    // Main API dependencies
+    //
+
+    bind(MessageService).toSelf().inSingletonScope();
+    bind(MessageClient).toSelf().inSingletonScope(); // Just logs to console
+    bind(ProgressService).toSelf().inSingletonScope();
+    bind(ProgressClient).to(HeadlessProgressClient).inSingletonScope();
+}

package/src/package.spec.ts

@@ -0,0 +1,25 @@
+// *****************************************************************************
+// Copyright (C) 2024 EclipseSource 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
+// *****************************************************************************
+
+/*
+ * This is a placeholder for tests that the extension package should implement
+ * but as yet does not.
+ * Please delete this file when a real test is implemented.
+ */
+
+describe('plugin-ext-headless package', () => {
+    it('placeholder to enable mocha', () => true);
+});

package/src/plugin/headless-plugin-manager.ts

@@ -0,0 +1,50 @@
+// *****************************************************************************
+// Copyright (C) 2024 EclipseSource 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
+// *****************************************************************************
+
+import { injectable } from '@theia/core/shared/inversify';
+import { AbstractPluginManagerExtImpl } from '@theia/plugin-ext/lib/plugin/plugin-manager';
+import { HeadlessPluginManagerExt, HeadlessPluginManagerInitializeParams } from '../common/headless-plugin-rpc';
+import { Plugin } from '@theia/plugin-ext';
+
+@injectable()
+export class HeadlessPluginManagerExtImpl extends AbstractPluginManagerExtImpl<HeadlessPluginManagerInitializeParams> implements HeadlessPluginManagerExt {
+
+    private readonly supportedActivationEvents = new Set<string>();
+
+    async $init(params: HeadlessPluginManagerInitializeParams): Promise<void> {
+        params.activationEvents?.forEach(event => this.supportedActivationEvents.add(event));
+
+        this.storage.init(params.globalState, {});
+
+        this.envExt.setLanguage(params.env.language);
+        this.envExt.setApplicationName(params.env.appName);
+        this.envExt.setAppHost(params.env.appHost);
+
+        if (params.extApi) {
+            this.host.initExtApi(params.extApi);
+        }
+    }
+
+    protected override getActivationEvents(plugin: Plugin): string[] | undefined {
+        const result = plugin.rawModel?.headless?.activationEvents;
+        return Array.isArray(result) ? result : undefined;
+    }
+
+    protected isSupportedActivationEvent(activationEvent: string): boolean {
+        return this.supportedActivationEvents.has(activationEvent.split(':')[0]);
+    }
+
+}

package/src/plugin-ext-headless-electron-module.ts

@@ -0,0 +1,32 @@
+// *****************************************************************************
+// Copyright (C) 2024 EclipseSource 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
+// *****************************************************************************
+
+import { ContainerModule } from '@theia/core/shared/inversify';
+import { HeadlessPluginContainerModule } from './common/headless-plugin-container';
+import { bindElectronBackend } from './hosted/node-electron/plugin-ext-headless-hosted-electron-module';
+import { bindHeadlessMain, bindBackendMain } from './main/node/plugin-ext-headless-main-module';
+import { bindHeadlessHosted } from './hosted/node/plugin-ext-headless-hosted-module';
+
+const backendElectronModule = new ContainerModule((bind, unbind, isBound, rebind) => {
+    bindBackendMain(bind, unbind, isBound, rebind);
+    bindElectronBackend(bind);
+});
+
+export default new ContainerModule(bind => {
+    bind(HeadlessPluginContainerModule).toConstantValue(backendElectronModule);
+    bindHeadlessMain(bind);
+    bindHeadlessHosted(bind);
+});

package/src/plugin-ext-headless-module.ts

@@ -0,0 +1,31 @@
+// *****************************************************************************
+// Copyright (C) 2024 EclipseSource 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
+// *****************************************************************************
+
+import { ContainerModule } from '@theia/core/shared/inversify';
+import { HeadlessPluginContainerModule } from './common/headless-plugin-container';
+import { bindHeadlessHosted, bindCommonHostedBackend } from './hosted/node/plugin-ext-headless-hosted-module';
+import { bindHeadlessMain, bindBackendMain } from './main/node/plugin-ext-headless-main-module';
+
+const backendModule = new ContainerModule((bind, unbind, isBound, rebind) => {
+    bindBackendMain(bind, unbind, isBound, rebind);
+    bindCommonHostedBackend(bind);
+});
+
+export default new ContainerModule(bind => {
+    bind(HeadlessPluginContainerModule).toConstantValue(backendModule);
+    bindHeadlessMain(bind);
+    bindHeadlessHosted(bind);
+});