author: Roels G - DIGIT.B.3
last reviesion: 

date | who ? | what ?
--- | --- | ---
2022-05-18 | roelsgr | document creation
<hr>
<br><br>

# eUI tools - part 1 - Introduction

## History

The initial main purpose of eUI tools was to have a comitted pipeline and avoid duplication of code in Bamboo, yes at that time there wasn't any Bamboo specs, which would have facilited the approach, if we wanted to have the pipeline as compiled code... which makes it not so handy for maintenance and "live" testing.

But nevertheless, eUI tools was there, at first it was really a bunch of promises scripts triggered by a bin files like npm library allowing obfuscation of pipeline flow : assemble/build/set version/publish. 

For sure like all things, it started simple and got more complicated, but it's in constant refactoring, basically things become unreadable  time for a refactoring ;)

## Challenges ?

Probably the most crucial one to tackle : eUI tools should use itself to build itself, sounds like recursive stuffs, but that's one of the main advantage of javascript maybe here.

This with the help of the CSDR pipeline for sure, executed through job/stage in gitlab.

Why ? because the pipeline when building a package / npm / backend etc... is split in 2 main parts : 
- the "init" phase: initialize / clone / mount the necessary repository(ies) instructed by the build param, basically a "pkg" package name and in CSDR it's always the repository name, easy to spot / easy and a few other arguments like : git "branch",  associated "project", and some other deployment parameters.
- the "release" phase : where the build / test / versioning / metadata entries / publication are done.

The fact that the init is decoupled from the release part makes it easy, the init is almost always static from version to version, so once building eUI tools, it initializes itself, clone its last version in the repository that has been pushed and after that symlinks itself on its node_modules installation, making at that time build itself as all the modules called from the release phase are now the ones of the latest commited version cloned during the init phase before.

What's the benefits ? allow new stages in the pipeline to be developed and used directly by the eUI tools themselves, this way, if there's a build failure at that level for itself, it's not shipped so it does not have any impact on others using it (basically all CSDR developers / eUI but it's safer there as the ultimate latest version of the package is not pushed constantly : only when eUI new version is released)

Another challenge here was to use the exact same build tools / installation scripts / synchronization script both for local development 
and on the CI side. So when commands are executed locally, they are battle tested when it comes to execute them too on the CI.
This makes it handy for developers building locally their packages first to have the exact same result as they would have when the pipeline is executing to build and publish their code.


## Why this exists ? bunch of bash script can do the same after all

Sure they can, but needs probably need to be a Unix expert to fully understand at first sight what's their purpose, in this agglomerated bunch of cryptic abbreviations and pipes ;)

So Javascript as the most stupid and simple language was used for the first early version, quickly became unreadable too because of its verbosity at some point for executing internal functions, promises etc...

So let's enter the black box ;)


## Where to start ?

As it's a bin bash execution javascript library, it all starts in the **/bin** folder.

Over each bin sub-scripts (launched by eui-script SCRIPT_NAME from any eUI app root package.json).

**eui-scripts.js** is the entry point file is the "bin" files defined in the package.json. This is used for scripts execution, and handle command line parameters so : 
```
eui-scripts SCRIPT_NAME [params]
```

Called scripts are located in **/scripts**, and basically their structure is almost always the same, if we take for example the most commonly used one : *sync*
```
const { syncUtils } = require('../../scripts');

Promise.resolve()
  .then(() => {
    return syncUtils.sync();
  })
  .catch((e) => {
    console.log(e);
    process.exit(1);
  })
```
Most of the times it contains : 

- **core** script import: here *syncUtils*,
- **promise wrapper**, for simplicity of the code (ok more verbose) everything is a promise in the core scripts.
- **catch** exiting the current process and displaying the exception handled or undhandled when excuting the core script.


