Initial contribution of @theia/terminal-external

The following commit adds a new extension `@theia/terminal-external`.
The extension adds support for spawning external terminals from Electron applications.

+ Supports opening native terminals by calling `Open New External Terminal` from the command palette.
+ The commit contributes the following preferences:
    - `terminal.external.windowsExec`
    - `terminal.external.osxExec`
    - `terminal.external.linuxExec`
to allow users to customize the desired terminal application to run on their current OS.

Co-authored-by: Paul <[email protected]>
Co-authored-by: vince-fugnitto <[email protected]>
Signed-off-by: Duc Nguyen <[email protected]>

configs/root-compilation.tsconfig.json

@@ -37,6 +37,9 @@
     {
       "path": "../packages/editor/compile.tsconfig.json"
     },
+    {
+      "path": "../packages/external-terminal/compile.tsconfig.json"
+    },
     {
       "path": "../packages/file-search/compile.tsconfig.json"
     },

examples/electron/compile.tsconfig.json

@@ -35,6 +35,9 @@
     {
       "path": "../../packages/editor-preview/compile.tsconfig.json"
     },
+    {
+      "path": "../../packages/external-terminal/compile.tsconfig.json"
+    },
     {
       "path": "../../packages/file-search/compile.tsconfig.json"
     },

examples/electron/package.json

@@ -23,6 +23,7 @@
     "@theia/editor": "1.11.0",
     "@theia/editor-preview": "1.11.0",
     "@theia/electron": "1.11.0",
+    "@theia/external-terminal": "1.11.0",
     "@theia/file-search": "1.11.0",
     "@theia/filesystem": "1.11.0",
     "@theia/getting-started": "1.11.0",

packages/external-terminal/.eslintrc.js

@@ -0,0 +1,10 @@
+/** @type {import('eslint').Linter.Config} */
+module.exports = {
+    extends: [
+        '../../configs/build.eslintrc.json'
+    ],
+    parserOptions: {
+        tsconfigRootDir: __dirname,
+        project: 'compile.tsconfig.json'
+    }
+};

packages/external-terminal/README.md

@@ -0,0 +1,46 @@
+<div align='center'>
+
+<br />
+
+<img src='https://raw.githubusercontent.com/eclipse-theia/theia/master/logo/theia.svg?sanitize=true' alt='theia-ext-logo' width='100px' />
+
+<h2>ECLIPSE THEIA - EXTERNAL-TERMINAL EXTENSION</h2>
+
+<hr />
+
+</div>
+
+## Description
+
+The `@theia/external-terminal` extension contributes the ability to spawn external terminals for `electron` applications.
+The extension includes the necessary logic to spawn the appropriate terminal application for each operating system (Windows, Linux, OSX)
+by identifying certain environment variables. The extension also contributes preferences to control this behavior if necessary.
+
+**Note:** The extension does not support browser applications.
+
+## Contributions
+
+### Commands
+
+- `OPEN_NATIVE_CONSOLE`: spawns an external terminal (native console) for different use-cases.
+
+### Preferences
+
+- `terminal.external.windowsExec`: the application executable for Windows.
+- `terminal.external.linuxExec`: the application executable for Linux.
+- `terminal.external.osxExec`: the application executable for OSX.
+
+## Additional Information
+
+- [Theia - GitHub](https://github.com/eclipse-theia/theia)
+- [Theia - Website](https://theia-ide.org/)
+
+## License
+
+-   [Eclipse Public License 2.0](http://www.eclipse.org/legal/epl-2.0/)
+-   [一 (Secondary) GNU General Public License, version 2 with the GNU Classpath Exception](https://projects.eclipse.org/license/secondary-gpl-2.0-cp)
+
+## Trademark
+
+"Theia" is a trademark of the Eclipse Foundation
+https://www.eclipse.org/theia

packages/external-terminal/compile.tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../configs/base.tsconfig",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../core/compile.tsconfig.json"
+    },
+    {
+      "path": "../editor/compile.tsconfig.json"
+    },
+    {
+      "path": "../workspace/compile.tsconfig.json"
+    }
+  ]
+}

packages/external-terminal/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@theia/external-terminal",
+  "version": "1.11.0",
+  "description": "Theia - External Terminal Extension",
+  "dependencies": {
+    "@theia/core": "1.11.0",
+    "@theia/editor": "1.11.0",
+    "@theia/workspace": "1.11.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "theiaExtensions": [
+    {
+      "backendElectron": "lib/electron-node/external-terminal-backend-module",
+      "frontendElectron": "lib/electron-browser/external-terminal-frontend-module"
+    }
+  ],
+  "keywords": [
+    "theia-extension"
+  ],
+  "license": "EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-theia/theia.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eclipse-theia/theia/issues"
+  },
+  "homepage": "https://github.com/eclipse-theia/theia",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "lint": "theiaext lint",
+    "build": "theiaext build",
+    "watch": "theiaext watch",
+    "clean": "theiaext clean",
+    "test": "theiaext test"
+  },
+  "devDependencies": {
+    "@theia/ext-scripts": "^1.9.0"
+  },
+  "nyc": {
+    "extends": "../../configs/nyc.json"
+  }
+}

packages/external-terminal/src/common/external-terminal.ts

@@ -0,0 +1,55 @@
+/********************************************************************************
+ * Copyright (C) 2021 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
+ ********************************************************************************/
+
+export const ExternalTerminalService = Symbol('ExternalTerminalService');
+export const externalTerminalServicePath = '/services/external-terminal';
+
+/**
+ * Represents the external terminal configuration options.
+ */
+export interface ExternalTerminalConfiguration {
+    /**
+     * The external terminal executable for Windows.
+     */
+    'terminal.external.windowsExec': string;
+    /**
+     * The external terminal executable for OSX.
+     */
+    'terminal.external.osxExec': string;
+    /**
+     * The external terminal executable for Linux.
+     */
+    'terminal.external.linuxExec': string;
+}
+
+export interface ExternalTerminalService {
+
+    /**
+     * Open a native terminal in the designated working directory.
+     *
+     * @param configuration the configuration for opening external terminals.
+     * @param cwd the string URI of the current working directory where the terminal should open from.
+     */
+    openTerminal(configuration: ExternalTerminalConfiguration, cwd: string): Promise<void>;
+
+    /**
+     * Get the default executable.
+     *
+     * @returns the default terminal executable.
+     */
+    getDefaultExec(): Promise<string>;
+
+}

packages/external-terminal/src/electron-browser/external-terminal-contribution.ts

@@ -0,0 +1,114 @@
+/********************************************************************************
+ * Copyright (C) 2021 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
+ ********************************************************************************/
+
+import { inject, injectable } from 'inversify';
+import { Command, CommandContribution, CommandRegistry } from '@theia/core/lib/common';
+import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
+import { QuickPickService } from '@theia/core/lib/common/quick-pick-service';
+import { KeybindingContribution, KeybindingRegistry, LabelProvider } from '@theia/core/lib/browser';
+import { EditorManager } from '@theia/editor/lib/browser/editor-manager';
+import { WorkspaceService } from '@theia/workspace/lib/browser';
+import { ExternalTerminalService } from '../common/external-terminal';
+import { ExternalTerminalPreferenceService } from './external-terminal-preference';
+
+export namespace ExternalTerminalCommands {
+    export const OPEN_NATIVE_CONSOLE: Command = {
+        id: 'workbench.action.terminal.openNativeConsole',
+        label: 'Open New External Terminal'
+    };
+}
+
+@injectable()
+export class ExternalTerminalFrontendContribution implements CommandContribution, KeybindingContribution {
+
+    @inject(EditorManager)
+    protected readonly editorManager: EditorManager;
+
+    @inject(EnvVariablesServer)
+    protected readonly envVariablesServer: EnvVariablesServer;
+
+    @inject(LabelProvider)
+    protected readonly labelProvider: LabelProvider;
+
+    @inject(QuickPickService)
+    protected readonly quickPickService: QuickPickService;
+
+    @inject(ExternalTerminalService)
+    protected readonly externalTerminalService: ExternalTerminalService;
+
+    @inject(ExternalTerminalPreferenceService)
+    protected readonly externalTerminalPreferences: ExternalTerminalPreferenceService;
+
+    @inject(WorkspaceService)
+    protected readonly workspaceService: WorkspaceService;
+
+    registerCommands(commands: CommandRegistry): void {
+        commands.registerCommand(ExternalTerminalCommands.OPEN_NATIVE_CONSOLE, {
+            execute: () => this.openExternalTerminal()
+        });
+    }
+
+    registerKeybindings(keybindings: KeybindingRegistry): void {
+        keybindings.registerKeybinding({
+            command: ExternalTerminalCommands.OPEN_NATIVE_CONSOLE.id,
+            keybinding: 'ctrlcmd+shift+c',
+            when: '!terminalFocus'
+        });
+    }
+
+    /**
+     * Open a native console on the host machine.
+     *
+     * - If multi-root workspace is open, displays a quick pick to let users choose which workspace to spawn the terminal.
+     * - If only one workspace is open, the terminal spawns at the root of the current workspace.
+     * - If no workspace is open and there is an active editor, the terminal spawns at the parent folder of that file.
+     * - If no workspace is open and there are no active editors, the terminal spawns at user home directory.
+     */
+    protected async openExternalTerminal(): Promise<void> {
+        const configuration = this.externalTerminalPreferences.getExternalTerminalConfiguration();
+
+        if (this.workspaceService.isMultiRootWorkspaceOpened) {
+            const chosenWorkspaceRoot = await this.selectCwd();
+            if (chosenWorkspaceRoot) {
+                await this.externalTerminalService.openTerminal(configuration, chosenWorkspaceRoot);
+            }
+            return;
+        }
+
+        if (this.workspaceService.opened) {
+            const workspaceRootUri = this.workspaceService.tryGetRoots()[0].resource;
+            await this.externalTerminalService.openTerminal(configuration, workspaceRootUri.toString());
+            return;
+        }
+
+        const fallbackUri = this.editorManager.activeEditor?.editor.uri.parent ?? await this.envVariablesServer.getHomeDirUri();
+        await this.externalTerminalService.openTerminal(configuration, fallbackUri.toString());
+    }
+
+    /**
+     * Display a quick pick for user to choose a target workspace in opened workspaces.
+     */
+    protected async selectCwd(): Promise<string | undefined> {
+        const roots = this.workspaceService.tryGetRoots();
+        return this.quickPickService.show(roots.map(
+            ({ resource }) => ({
+                label: this.labelProvider.getName(resource),
+                description: this.labelProvider.getLongName(resource),
+                value: resource.toString()
+            })
+        ), { placeholder: 'Select current working directory for new external terminal' });
+    }
+}

packages/external-terminal/src/electron-browser/external-terminal-frontend-module.ts

@@ -0,0 +1,33 @@
+/********************************************************************************
+ * Copyright (C) 2021 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
+ ********************************************************************************/
+
+import { ContainerModule, interfaces } from 'inversify';
+import { CommandContribution } from '@theia/core/lib/common';
+import { KeybindingContribution, WebSocketConnectionProvider } from '@theia/core/lib/browser';
+import { bindExternalTerminalPreferences } from './external-terminal-preference';
+import { ExternalTerminalFrontendContribution } from './external-terminal-contribution';
+import { ExternalTerminalService, externalTerminalServicePath } from '../common/external-terminal';
+
+export default new ContainerModule((bind: interfaces.Bind) => {
+    bind(ExternalTerminalFrontendContribution).toSelf().inSingletonScope();
+    bindExternalTerminalPreferences(bind);
+    [CommandContribution, KeybindingContribution].forEach(serviceIdentifier =>
+        bind(serviceIdentifier).toService(ExternalTerminalFrontendContribution)
+    );
+    bind(ExternalTerminalService).toDynamicValue(ctx =>
+        WebSocketConnectionProvider.createProxy<ExternalTerminalService>(ctx.container, externalTerminalServicePath)
+    ).inSingletonScope();
+});