Task extension

This extension provides the means to execute scripts or executables, from a frontend client, in the backend. Tasks life cycle events are send from the backend to the frontend clients, whenever a task is created or terminates. A task client can ask the backend for the list of tasks that are currently running. We support having multiple frontend task clients that are using the same backend task server. Each client uses its workspace root as context parameter, in all its communications with the backend. Whenever the backend sends notifications to its clients, the original client context is sent along. It's then up-to the clients to determine if they are interested in the event, given its context, and show it to the user or not. This mechanism makes it possible for multiple clients, opened on the same workspace, to all get the notifications related to all tasks that execute from that workspace. At the same time, clients can ignore tasks that are run from another workspace. Fixes #686 Signed-off-by: Marc Dumais <[email protected]>
eclipse-theia · Dec 18, 2017 · 812e2dd · 812e2dd
1 parent 1c96e7b
commit 812e2dd
Show file tree

Hide file tree

Showing 26 changed files with 1,862 additions and 4 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -29,7 +29,8 @@
         "packages/process/coverage/lcov.info",
         "packages/python/coverage/lcov.info",
         "packages/terminal/coverage/lcov.info",
-        "packages/workspace/coverage/lcov.info"
+        "packages/workspace/coverage/lcov.info",
+        "packages/task/coverage/lcov.info"
     ],
     "lcov.watch": [
         {

diff --git a/examples/browser/package.json b/examples/browser/package.json
@@ -25,7 +25,8 @@
     "@theia/typescript": "^0.3.1",
     "@theia/userstorage": "^0.3.0",
     "@theia/workspace": "^0.3.0",
-    "@theia/keymaps": "^0.3.0"
+    "@theia/keymaps": "^0.3.0",
+    "@theia/task": "^0.3.0"
   },
   "scripts": {
     "prepare": "yarn run clean && yarn build",

diff --git a/examples/electron/package.json b/examples/electron/package.json
@@ -28,7 +28,8 @@
     "@theia/typescript": "^0.3.1",
     "@theia/userstorage": "^0.3.0",
     "@theia/workspace": "^0.3.0",
-    "@theia/keymaps": "^0.3.0"
+    "@theia/keymaps": "^0.3.0",
+    "@theia/task": "^0.3.0"
   },
   "scripts": {
     "prepare": "yarn run clean && yarn build",

diff --git a/packages/process/src/node/terminal-process.ts b/packages/process/src/node/terminal-process.ts
@@ -46,7 +46,9 @@ export class TerminalProcess extends Process {
             options.args,
             options.options);
 
-        this.terminal.on('exit', this.emitOnExit.bind(this));
+        this.terminal.on('exit', (code: number, signal?: number) => {
+            this.emitOnExit(code, signal ? signal.toString() : undefined);
+        });
 
         this.terminal.on('data', (data: string) => {
             ringBuffer.enq(data);

diff --git a/packages/task/README.md b/packages/task/README.md
@@ -0,0 +1,125 @@
+# Theia - Task Extension
+
+This extension permits executing scripts or binaries in Theia's backend. 
+
+Tasks launch configurations can be defined independently for each workspace, under `.theia/tasks.json`. When present, they are automatically picked-up when a client opens a workspace, and watches for changes. A task can be executed by triggering the "Run Task" command (shortcut F1). A list of known tasks will then be available, one of which can be selected to trigger execution. 
+
+Each task configuration looks like this:
+``` json
+     {
+        "label": "Test task - list workspace files recursively",
+        "processType": "terminal",
+        "cwd": "$workspace",
+        "processOptions": {
+            "command": "ls",
+            "args": [
+                "-alR"
+            ]
+        },
+        "windowsProcessOptions": {
+            "command": "cmd.exe",
+            "args": [
+                "/c",
+                "dir",
+                "/s"
+            ]
+       }
+    }
+```
+
+*label*: A unique string that identifies the task. That's what's shown to the user, when it's time to chose one task configuration to run.
+
+*processType*: Determines what type of process will be used to execute the task. Can be "raw" or "terminal". Terminal processes can be shown in Theia's frontend, in a terminal widget. Raw processes are run without their output being shown. 
+
+*cwd*: The current working directory, in which the task's command will execute. This is the equivalent of doing a "cd" to that directory, on the command-line, before running the command. This can contain the symbol *$workspace*, which will be replaced at execution time by the path of the current workspace. If left undefined, will by default be set to workspace root. 
+
+*processOptions.command*: the actual command or script to execute. The command can have no path (e.g. "ls") if it can be found in the system path. Else it can have an absolute path, in which case there is no confusion. Or it can have a relative path, in which case it will be interpreted to be relative to cwd. e.g. "./task" would be interpreted to mean a script or binary called "task", right under the workspace root directory.
+
+*processOptions.args*: a list of strings, each one being one argument to pass to the command. 
+
+*windowsProcessOptions*: By default, *processOption* above is used on all platforms. However it's not always possible to express a task in the same way, both on Unix and Windows. The command and/or arguments may be different, for example. If a task needs to work on both Linux/MacOS and Windows, it can be better to have two separate process options. If *windowsProcessOptions* is defined, it will be used instead of *processOptions*, when a task is executed on a Windows backend. 
+
+
+
+Here is a sample tasks.json that can be used to test tasks. Just add this content under the theia source directory, in directory `.theia`: 
+``` json
+{
+    // Some sample Theia tasks
+    "tasks": [
+        {
+            "label": "[Task] short runnning test task (~3s)",
+            "processType": "terminal",
+            "cwd": "$workspace/packages/task/src/node/test-resources/",
+            "processOptions": {
+                "command": "./task",
+                "args": [
+                    "1",
+                    "2",
+                    "3"
+                ]
+            },
+            "windowsProcessOptions": {
+                "command": "cmd.exe",
+                "args": [
+                    "/c",
+                    "task.bat",
+                    "abc"
+                ]
+            }
+        },
+        {
+            "label": "[Task] long runnning test task (~300s)",
+            "processType": "terminal",
+            "cwd": "$workspace/packages/task/src/node/test-resources/",
+            "processOptions": {
+                "command": "./task-long-running",
+                "args": []
+            },
+            "windowsProcessOptions": {
+                "command": "cmd.exe",
+                "args": [
+                    "/c",
+                    "task-long-running.bat"
+                ]
+            }
+        },
+        {
+            "label": "[Task] recursively list files from workspace root",
+            "processType": "terminal",
+            "cwd": "$workspace",
+            "processOptions": {
+                "command": "ls",
+                "args": [
+                    "-alR"
+                ]
+            },
+            "windowsProcessOptions": {
+                "command": "cmd.exe",
+                "args": [
+                    "/c",
+                    "dir",
+                    "/s"
+                ]
+            }
+        },
+        {
+            "label": "[Task] Echo a string",
+            "processType": "terminal",
+            "cwd": "$workspace",
+            "processOptions": {
+                "command": "bash",
+                "args": [
+                    "-c",
+                    "echo 1 2 3"
+                ]
+            }
+        }
+    ]
+}
+```
+
+
+See [here](https://github.com/theia-ide/theia) for other Theia documentation.
+
+## License
+[Apache-2.0](https://github.com/theia-ide/theia/blob/master/LICENSE)
diff --git a/packages/task/compile.tsconfig.json b/packages/task/compile.tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../configs/base.tsconfig",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": [
+    "src"
+  ]
+}
diff --git a/packages/task/package.json b/packages/task/package.json
@@ -0,0 +1,52 @@
+{
+  "name": "@theia/task",
+  "version": "0.3.0",
+  "description": "Theia - Task extension. This extension adds support for executing raw or terminal processes in the backend.",
+  "dependencies": {
+    "@theia/core": "^0.3.0",
+    "@theia/markers": "^0.3.0",
+    "@theia/process": "^0.3.0",
+    "@theia/terminal": "^0.3.0",
+    "@theia/workspace": "^0.3.0",
+    "jsonc-parser": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "theiaExtensions": [
+    {
+      "frontend": "lib/browser/task-frontend-module",
+      "backend": "lib/node/task-backend-module"
+    }
+  ],
+  "keywords": [
+    "theia-extension"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/theia-ide/theia.git"
+  },
+  "bugs": {
+    "url": "https://github.com/theia-ide/theia/issues"
+  },
+  "homepage": "https://github.com/theia-ide/theia",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "prepare": "yarn run clean && yarn run build",
+    "clean": "theiaext clean",
+    "build": "theiaext build",
+    "watch": "theiaext watch",
+    "test": "theiaext test",
+    "docs": "theiaext docs"
+  },
+  "devDependencies": {
+    "@theia/ext-scripts": "^0.2.0"
+  },
+  "nyc": {
+    "extends": "../../configs/nyc.json"
+  }
+}
diff --git a/packages/task/src/browser/index.ts b/packages/task/src/browser/index.ts
@@ -0,0 +1,8 @@
+/*
+ * Copyright (C) 2017 Ericsson and others.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+export * from './task-service';
diff --git a/packages/task/src/browser/quick-open-task.ts b/packages/task/src/browser/quick-open-task.ts
@@ -0,0 +1,121 @@
+/*
+ * Copyright (C) 2017 Ericsson and others.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import { inject, injectable } from "inversify";
+import { TaskService } from './task-service';
+import { TaskInfo } from '../common/task-protocol';
+import { QuickOpenService, QuickOpenModel, QuickOpenItem, QuickOpenMode } from '@theia/core/lib/browser/quick-open/';
+
+@injectable()
+export class QuickOpenTask implements QuickOpenModel {
+
+    protected items: QuickOpenItem[];
+
+    constructor(
+        @inject(TaskService) protected readonly taskService: TaskService,
+        @inject(QuickOpenService) protected readonly quickOpenService: QuickOpenService
+    ) { }
+
+    open(): void {
+        this.items = [];
+
+        const tasks: string[] = this.taskService.getTasks();
+        for (const task of tasks) {
+            this.items.push(new TaskRunQuickOpenItem(task, this.taskService));
+        }
+        this.quickOpenService.open(this, {
+            placeholder: 'Type the name of a task you want to execute',
+            fuzzyMatchLabel: true,
+            fuzzySort: true
+        });
+    }
+
+    attach(): void {
+        this.items = [];
+
+        this.taskService.getRunningTasks().then(tasks => {
+            for (const task of tasks) {
+                // can only attach to terminal processes, so only list those
+                if (task.terminalId) {
+                    this.items.push(
+                        new TaskAttachQuickOpenItem(
+                            task,
+                            this.getRunningTaskLabel(task),
+                            this.taskService
+                        )
+                    );
+                }
+            }
+            this.quickOpenService.open(this, {
+                placeholder: 'Choose task to open',
+                fuzzyMatchLabel: true,
+                fuzzySort: true
+            });
+        });
+    }
+
+    public getItems(lookFor: string): QuickOpenItem[] {
+        return this.items;
+    }
+
+    onType(lookFor: string, acceptor: (items: QuickOpenItem[]) => void): void {
+        acceptor(this.items);
+    }
+
+    protected getRunningTaskLabel(task: TaskInfo): string {
+        return `Task id: ${task.taskId}, label: ${task.label}`;
+    }
+
+}
+
+export class TaskRunQuickOpenItem extends QuickOpenItem {
+
+    constructor(
+        protected readonly taskLabel: string,
+        protected taskService: TaskService
+    ) {
+        super();
+    }
+
+    getLabel(): string {
+        return this.taskLabel!;
+    }
+
+    run(mode: QuickOpenMode): boolean {
+        if (mode !== QuickOpenMode.OPEN) {
+            return false;
+        }
+        this.taskService.run(this.taskLabel);
+
+        return true;
+    }
+}
+
+export class TaskAttachQuickOpenItem extends QuickOpenItem {
+
+    constructor(
+        protected readonly task: TaskInfo,
+        protected readonly taskLabel: string,
+        protected taskService: TaskService
+    ) {
+        super();
+    }
+
+    getLabel(): string {
+        return this.taskLabel!;
+    }
+
+    run(mode: QuickOpenMode): boolean {
+        if (mode !== QuickOpenMode.OPEN) {
+            return false;
+        }
+        if (this.task.terminalId) {
+            this.taskService.attach(this.task.terminalId, this.task.taskId);
+        }
+        return true;
+    }
+}