Adds Digital Twin Runner utility (#110)

  - Adds a runner to manage digital twins. One instance of
    runner manages one digital twin.
  - Adds Lifecycle manager to support digital twin
     lifecycle phases.
    The lifecycle manager invokes a phase upon request and
    runs the same asynchronously. ⚠️ At the moment, only
    Linux system commands have been tested.
  - Creates npm package of the runner. Also the README
    contains instructions on setting up private npm repository
    for development purposes.
  - 🥂 Adds OpenAPI specification for DT Runner
  - Updates git-hooks to check against runner as well.

---------
Co-authored-by: nichlaes <[email protected]>

.git-hooks/pre-commit

@@ -1,9 +1,21 @@
 #!/usr/bin/env sh
 
+TOP_DIR="$(pwd)"
+export TOP_DIR
+
 if git diff --cached --name-only | grep "^client/" >/dev/null; then
     cd client || exit
     yarn install
     yarn format && yarn syntax
 else
-    printf "No changes in the client directory. Skipping pre-commit hook."
+    printf "No changes in the client directory. Skipping pre-commit hook.\n\n"
+fi
+
+cd "$TOP_DIR" || exit
+if git diff --cached --name-only | grep "^servers/execution/runner/" >/dev/null; then
+    cd "servers/execution/runner" || exit
+    yarn install
+    yarn format && yarn syntax
+else
+    printf "No changes in the servers/execution/runner directory. Skipping pre-commit hook.\n\n"
 fi

.git-hooks/pre-push

@@ -1,11 +1,22 @@
 #!/usr/bin/env sh
 
 BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
+TOP_DIR="$(pwd)"
+export TOP_DIR
 
 if git diff --name-only origin/"$BRANCH_NAME"...HEAD | grep "^client/" >/dev/null; then
     cd client || exit
     yarn install
     yarn jest . --coverage=false
 else
-    echo "No changes in the client directory. Skipping pre-push hook."
+    printf "No changes in the client directory. Skipping pre-push hook.\n\n"
+fi
+
+cd "$TOP_DIR" || exit
+if git diff --name-only origin/"$BRANCH_NAME"...HEAD | grep "^servers/execution/runner/" >/dev/null; then
+    cd "servers/execution/runner" || exit
+    yarn install
+    yarn test:nocov
+else
+    printf "No changes in the servers/execution/runner/ directory. Skipping pre-push hook.\n\n"
 fi

.github/workflows/runner.yml

@@ -0,0 +1,54 @@
+name: Digital twin runner
+
+on:
+  push:
+    paths:
+      - 'servers/execution/**'
+  pull_request:
+    paths:
+      - 'servers/execution/**'
+  workflow_dispatch:
+    paths:
+      - 'servers/execution/**'
+
+jobs:
+  test-runner:
+    name: Test digital twin runner
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: "yarn"
+          cache-dependency-path: "**/yarn.lock"
+
+      - name: Run linting checks on runner
+        run: |
+          cd servers/execution/runner
+          yarn install
+          yarn syntax
+
+      - name: Build the runner
+        if: success() || failure()
+        run: |
+          cd servers/execution/runner
+          yarn install	
+          yarn build
+
+      - name: Run tests
+        if: success() || failure()
+        run: |
+          cd servers/execution/runner
+          yarn install
+          yarn test
+
+      - name: Upload test coverage to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          files: servers/execution/runner/coverage/clover.xml
+          flags: dt-runner

.gitignore

@@ -10,6 +10,10 @@ yarn-debug.log*
 yarn-error.log*
 lerna-debug.log*
 
+# NPM registry configuration
+.yarnrc
+.npmrc
+
 # Diagnostic reports (https://nodejs.org/api/report.html)
 report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 
@@ -139,6 +143,7 @@ site/
 *.sublime-workspace
 
 # IDE - VSCode
+.vscode
 .vscode/*
 !.vscode/settings.json
 !.vscode/tasks.json

client/.gitignore

@@ -1 +1 @@
-playwright/.auth/
+playwright/.auth/

docs/PUBLISH.md

@@ -1,12 +1,15 @@
 
 # Project Documentation
 
-This file contains instructions for creation, compilation and publication of project documentation.
+This file contains instructions for creation, compilation and publication of
+project documentation.
 
-The documentation system is based on [Material for Mkdocs](https://squidfunk.github.io/mkdocs-material/). The documentation is generated based on the configuration files:
+The documentation system is based on
+[Material for Mkdocs](https://squidfunk.github.io/mkdocs-material/).
+The documentation is generated based on the configuration files:
 
 * **mkdocs.yml**: used for generating online documentation which is hosted on the web
-* **mkdocs_offline.yml**: used for generating offline documentation that can be downloaded and used on user computer.
+* **mkdocs-github.yml**: used for generating documentation in github actions
 
 Install Mkdocs using the following command.
 
@@ -16,24 +19,47 @@ pip install -r docs/requirements.txt
 
 ## Create documentation
 
-You can add, and edit the markdown files in `docs/` directory to update the documentation. There is a facility to check the status of your documentation by using:
+The document generation pipeline can generate both **html** and **pdf**
+versions of documentation.
+
+The generation of **pdf** version of documentation is controlled via
+a shell variable.
+
+```bash
+export MKDOCS_ENABLE_PDF_EXPORT=0 #disables generation of pdf document
+export MKDOCS_ENABLE_PDF_EXPORT=1 #enables generation of pdf document
+```
+
+The `mkdocs` utility allows for live editing of documentation
+on the developer computer.
+
+You can add, and edit the markdown files in `docs/` directory to update
+the documentation. There is a facility to check the status of your
+documentation by using:
 
 ```bash
 mkdocs serve --config-file mkdocs.yml
 ```
 
 ## Publish documentation
 
-You can compile and place the html version of documentation on the `webpage-docs` branch of the codebase.
+You can compile and place the html version of documentation on
+the `webpage-docs` branch of the codebase.
 
 ```bash
+export MKDOCS_ENABLE_PDF_EXPORT=1 #enable generation of pdf document
 source script/docs.sh [version]
 ```
 
-The command takes an optional version parameter. This version parameter is needed for making a release. Otherwise, the documentation gets published with the latest version tag. This command makes a new commit on `webpage-docs` branch. You need to push the branch to upstream.
+The command takes an optional version parameter. This version parameter is needed
+for making a release. Otherwise, the documentation gets published with
+the latest version tag. This command makes a new commit on `webpage-docs` branch.
+You need to push the branch to upstream.
 
 ```bash
 git push webpage-docs
 ```
 
-The github pages system serves the [project documentation](https://into-cps-association.github.io/DTaaS/) from this branch.
+The github pages system serves the
+[project documentation](https://into-cps-association.github.io/DTaaS/) from
+this branch.

servers/execution/runner/.eslintignore

@@ -0,0 +1,6 @@
+api/
+build/
+dist/
+node_modules/
+script/
+src/types.ts

servers/execution/runner/.eslintrc

@@ -0,0 +1,53 @@
+{
+  "env": {
+    "jest": true,
+    //"jest/globals": true,
+    "node": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "airbnb-base",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "globals": {
+    "Atomics": "readonly",
+    "SharedArrayBuffer": "readonly"
+  },
+  "settings": {
+    "import/resolver": {
+      "node": {
+        "extensions": [".js"]
+      }
+    }
+  },
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "requireConfigFile": false,
+    "ecmaVersion": 2022,
+    "sourceType": "module" // Allows for the use of imports
+  },
+  "plugins": ["jest", "@typescript-eslint", "import"],
+  "rules": {
+    "import/no-extraneous-dependencies": ["error", { "devDependencies": true }],
+    "no-console": "error",
+    "import/first": "error",
+    "linebreak-style": 0, // disable linter linebreak rule, to allow for both unix and windows developement
+    "import/no-unresolved": "off", // Whatever IDE will pass an error if if the module is not found, so no reason for this..
+    "import/extensions": "off", // That includes the production build.. We use linter for code checking / clean code optimization..
+    "no-use-before-define": "off"
+  },
+  "root": true,
+
+  "overrides": [
+    {
+      "files": ["*.ts"],
+      "parser": "@typescript-eslint/parser",
+      "parserOptions": {
+        "requireConfigFile": false,
+        "project": ["./tsconfig.json"]
+      },
+      "plugins": ["@typescript-eslint"]
+    }
+  ]
+}

servers/execution/runner/.npmignore

@@ -0,0 +1,7 @@
+src
+test
+jest.config.json
+tsconfig.json
+.eslintignore
+.eslintrc
+.env

servers/execution/runner/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}