feat(plugins/scripts-runner): introduce exec command to run scripts

This commit introduces a new features that enables users to run (migration) scripts.
Similar to deployment hooks, scripts are functions that may perform operations on newly
deployed Smart Contracts.

Therefore a script needs to export a function that has access to some dependencies like so:

```
// scripts/001-some-script.js

module.exports = async ({contracts, web3, logger}) => {
  ...
};
```

Where `contracts` is a map of freshly deployed Smart Contract instances, `web3` a blockchain connector
instance and `logger` Embark's logger instance. Script functions can but don't have to be `async`.

To execute such a script users use the newly introduced `exec` command:

```
$ embark exec development scripts/001-some-script.js
```

In the example above, `development` defines the environment in which Smart Contracts are being
deployed to as well as where tracking data is stored (implemented in a follow-up commit).
Alternativey, users can also provide a directory in which case Embark will try to execute every
script living inside of it:

```
$ embark exec development scripts
```

Scripts can fail and therefore emit and error accordingly. When this happens, Embark will
abort the script execution (in case multiple are scheduled to run) and informs the user
about the original error:

```
.. 001_foo.js running....
Script '001_foo.js' failed to execute. Original error: Error: Some error
```

It's recommended for scripts to emit proper instances of `Error`.

packages/embark/src/cmd/cmd.js

@@ -15,6 +15,7 @@ class Cmd {
     this.demo();
     this.build();
     this.run();
+    this.exec();
     this.console();
     this.blockchain();
     this.simulator();
@@ -174,6 +175,28 @@ class Cmd {
       });
   }
 
+  exec() {
+    program
+      .command('exec [environment] [script|directory]')
+      .description(__("Executes specified scripts or all scripts in 'directory'"))
+      .action((env, target) => {
+        embark.exec({
+          env,
+          target
+        }, (err) => {
+          if (err) {
+            console.error(err.message ? err.message : err);
+            process.exit(1);
+          }
+          console.log('Done.');
+          // TODO(pascal): Ideally this shouldn't be needed.
+          // Seems like there's a pending child process at this point that needs
+          // to be stopped.
+          process.exit(0);
+        });
+      });
+  }
+
   console() {
     program
       .command('console [environment]')

packages/embark/src/cmd/cmd_controller.js

@@ -349,6 +349,42 @@ class EmbarkController {
     });
   }
 
+  exec(options, callback) {
+    const engine = new Engine({
+      env: options.env,
+      embarkConfig: options.embarkConfig || 'embark.json'
+    });
+
+    engine.init({}, () => {
+      engine.registerModuleGroup("coreComponents", {
+        disableServiceMonitor: true
+      });
+      engine.registerModuleGroup("stackComponents");
+      engine.registerModuleGroup("blockchain");
+      engine.registerModuleGroup("compiler");
+      engine.registerModuleGroup("contracts");
+      engine.registerModulePackage('embark-deploy-tracker', {
+        plugins: engine.plugins
+      });
+      engine.registerModulePackage('embark-scripts-runner');
+
+      engine.startEngine(async (err) => {
+        if (err) {
+          return callback(err);
+        }
+        try {
+          await engine.events.request2("blockchain:node:start", engine.config.blockchainConfig);
+          const [contractsList, contractDependencies] = await compileSmartContracts(engine);
+          await engine.events.request2("deployment:contracts:deploy", contractsList, contractDependencies);
+          await engine.events.request2('scripts-runner:execute', options.target, { env: options.env });
+        } catch (err) {
+          return callback(err);
+        }
+        callback();
+      });
+    });
+  }
+
   console(options) {
     this.context = options.context || [constants.contexts.run, constants.contexts.console];
     const REPL = require('./dashboard/repl.js');

packages/plugins/scripts-runner/README.md

@@ -0,0 +1,10 @@
+embark-scripts-runner
+==========================
+
+> Embark Scripts Runner
+
+Plugin to run migration scripts for Smart Contract Deployment
+
+Visit [embark.status.im](https://embark.status.im/) to get started with
+[Embark](https://github.com/embarklabs/embark).
+

packages/plugins/scripts-runner/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "embark-scripts-runner",
+  "version": "5.1.0",
+  "description": "Embark Scripts Runner",
+  "repository": {
+    "directory": "packages/plugins/scripts-runner",
+    "type": "git",
+    "url": "https://github.com/embarklabs/embark/"
+  },
+  "author": "Iuri Matias <iuri.matias@gmail.com>",
+  "license": "MIT",
+  "bugs": "https://github.com/embarklabs/embark/issues",
+  "keywords": [],
+  "files": [
+    "dist/"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "embark-collective": {
+    "build:node": true,
+    "typecheck": true
+  },
+  "scripts": {
+    "_build": "npm run solo -- build",
+    "_typecheck": "npm run solo -- typecheck",
+    "ci": "npm run qa",
+    "clean": "npm run reset",
+    "lint": "npm-run-all lint:*",
+    "lint:ts": "tslint -c tslint.json \"src/**/*.ts\"",
+    "qa": "npm-run-all lint _typecheck _build test",
+    "reset": "npx rimraf dist embark-*.tgz package",
+    "solo": "embark-solo",
+    "test": "jest"
+  },
+  "dependencies": {
+    "async": "2.6.1",
+    "@babel/runtime-corejs3": "7.7.4",
+    "embark-core": "^5.1.0",
+    "embark-i18n": "^5.1.0",
+    "embark-logger": "^5.1.0",
+    "embark-utils": "^5.1.0",
+    "web3": "1.2.4"
+  },
+  "devDependencies": {
+    "@babel/core": "7.7.4",
+    "@types/node": "^10.5.3",
+    "babel-jest": "24.9.0",
+    "embark-solo": "^5.1.1-nightly.2",
+    "embark-testing": "^5.1.0",
+    "jest": "24.9.0",
+    "npm-run-all": "4.1.5",
+    "rimraf": "3.0.0",
+    "tmp-promise": "1.1.0"
+  },
+  "engines": {
+    "node": ">=10.17.0",
+    "npm": ">=6.11.3",
+    "yarn": ">=1.19.1"
+  },
+  "jest": {
+    "collectCoverage": true,
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/test/**/*.js"
+    ],
+    "transform": {
+      "\\.(js|ts)$": [
+        "babel-jest",
+        {
+          "rootMode": "upward"
+        }
+      ]
+    }
+  }
+}
+

packages/plugins/scripts-runner/src/index.ts

@@ -0,0 +1,178 @@
+import { eachSeries } from 'async';
+import { promises as fsPromises, stat, Stats } from 'fs';
+import path from 'path';
+import { Embark, Callback } from 'embark-core';
+import { Logger } from 'embark-logger';
+import { dappPath } from 'embark-utils';
+import Web3 from "web3";
+
+export enum ScriptsRunnerCommand {
+  Execute = 'scripts-runner:execute'
+}
+
+export interface ExecuteOptions {
+  env: string;
+}
+
+export interface ScriptDependencies {
+  web3: Web3 | null;
+  contracts: any;
+  logger: Logger;
+}
+
+enum FileType {
+  SymbolicLink = 'symbolic link',
+  Socket = 'socket',
+  Unknown = 'unknown'
+}
+
+class UnsupportedTargetError extends Error {
+
+  name = 'UnsupportedTargetError';
+
+  constructor(public stats: Stats) {
+    super();
+    // We can't access `this` before `super()` is called so we have to
+    // set `this.message` after that to get a dedicated error message.
+    this.setMessage();
+  }
+
+  private setMessage() {
+    let ftype = FileType.Unknown;
+    if (this.stats.isSymbolicLink()) {
+      ftype = FileType.SymbolicLink;
+    } else if (this.stats.isSocket()) {
+      ftype = FileType.Socket;
+    }
+    this.message = `Script execution target not supported. Expected file path or directory, got ${ftype} type.`;
+  }
+}
+
+class ScriptExecutionError extends Error {
+
+  name = 'ScriptExecutionError';
+
+  constructor(public target: string, public innerError: Error) {
+    super();
+    this.message = `Script '${path.basename(target)}' failed to execute. Original error: ${innerError}`;
+  }
+}
+
+export default class ScriptsRunnerPlugin {
+
+  embark: Embark;
+  private _web3: Web3 | null = null;
+
+  constructor(embark) {
+    this.embark = embark;
+    // TODO: it'd be wonderful if Embark called `registerCommandHandlers()` for us
+    this.registerCommandHandlers();
+  }
+
+  registerCommandHandlers() {
+    this.embark.events.setCommandHandler(ScriptsRunnerCommand.Execute, this.execute.bind(this));
+  }
+
+  private get web3() {
+    return (async () => {
+      if (!this._web3) {
+        const provider = await this.embark.events.request2('blockchain:client:provider', 'ethereum');
+        this._web3 = new Web3(provider);
+      }
+      return this._web3;
+    })();
+  }
+
+  private async execute(target: string, options: ExecuteOptions, callback: Callback<any>) {
+    const targetPath = !path.isAbsolute(target) ? dappPath(target) : target;
+    try {
+      const fstat = await fsPromises.stat(targetPath);
+      if (fstat.isDirectory()) {
+        const dependencies = await this.getScriptDependencies();
+        await this.executeAll(targetPath, dependencies, callback);
+      } else if (fstat.isFile()) {
+        const dependencies = await this.getScriptDependencies();
+        await this.executeSingle(targetPath, dependencies, callback);
+      } else {
+        callback(new UnsupportedTargetError(fstat));
+      }
+    } catch (e) {
+      callback(e);
+    }
+  }
+
+  private async executeSingle(target: string, dependencies: ScriptDependencies, callback: Callback<any>) {
+    const scriptToRun = require(target);
+    this.embark.logger.info(`.. ${path.basename(target)} running....`);
+    try {
+      const result = await scriptToRun(dependencies);
+      this.embark.logger.info(`.. finished.`);
+      callback(null, result);
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(e);
+      callback(new ScriptExecutionError(target, error));
+    }
+  }
+
+  private async executeAll(target: string, dependencies: ScriptDependencies, callback: Callback<any>) {
+    const files = await fsPromises.readdir(target);
+    const results: any[] = [];
+
+    eachSeries(files, (file, cb) => {
+      const targetPath = !path.isAbsolute(target) ? dappPath(target, file) : path.join(target, file);
+
+      stat(targetPath, (err, fstat) => {
+        if (err) {
+          return cb(err);
+        }
+        if (fstat.isFile()) {
+          return this.executeSingle(targetPath, dependencies, (e, result) => {
+            if (e) {
+              return cb(e);
+            }
+            results.push(result);
+            cb();
+          });
+        }
+        cb();
+      });
+    }, (err) => {
+      if (err) {
+        return callback(err);
+      }
+      callback(null, results);
+    });
+  }
+
+  private async getScriptDependencies() {
+    const contracts = await this.embark.events.request2('contracts:list');
+
+    const dependencies: ScriptDependencies  = {
+      logger:  this.embark.logger,
+      web3: null,
+      contracts: {}
+    };
+
+    dependencies.web3 = await this.web3;
+
+    for (const contract of contracts) {
+      const registeredInVM = this.checkContractRegisteredInVM(contract);
+      if (!registeredInVM) {
+        await this.embark.events.request2("embarkjs:contract:runInVm", contract);
+      }
+      const contractInstance = await this.embark.events.request2("runcode:eval", contract.className);
+      dependencies.contracts[contract.className] = contractInstance;
+    }
+    return dependencies;
+  }
+
+  // TODO(pascal): the same API is used in the specialconfigs plugin.
+  // Might make sense to either move this to code-runner and set up a
+  // command handler, or set up a command handler in specialconfigs.
+  private async checkContractRegisteredInVM(contract) {
+    const checkContract = `
+      return typeof ${contract.className} !== 'undefined';
+    `;
+    return this.embark.events.request2('runcode:eval', checkContract);
+  }
+}