@d-cat/tag-cli/README.md

# [@d-cat/tag-cli](https://www.npmjs.com/package/@d-cat/tag-cli)

[![npm](https://img.shields.io/npm/v/@d-cat/tag-cli?color=brightgreen)](https://www.npmjs.com/package/@d-cat/tag-cli) [![node](https://img.shields.io/node/v/@d-cat/tag-cli?color=brightgreen)](<(https://www.npmjs.com/package/@d-cat/tag-cli)>) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) [![codecov](https://codecov.io/gl/d-cat:templates:ci-cd/tag-cli/branch/master/graph/badge.svg?token=l7O5FqoJsT)](https://codecov.io/gl/d-cat:templates:ci-cd/tag-cli)

> [@d-cat/tag-cli](https://www.npmjs.com/package/@d-cat/tag-cli) is a [VZ](https://vodafoneziggo.com) CLI package that should be used to configure containers and tags when using [@d-cat/tag-manager](https://www.npmjs.com/package/@d-cat/tag-manager).

## Install

```bash
npm i -D @d-cat/tag-cli
```

## Usage
@d-cat/tag-cli is a toolkit to deploy and develop a Tag Manager with Tags using GitLab and Google Cloud Platform.

### create-tag-manager
The `create-tag-manager` creates a Tag Manager boilerplate designed to use with @d-cat/tag-cli within GitLab CI/CD. Please make sure you update the e2e and unit tests to suite your needs and match the TMS you want to deploy.

```bash
Options:
  --version               Show version number                          [boolean]
  --help                  Show help                                    [boolean]
```

#### What's included
The Tag Manager boilerplate contains everything to:
* unit test the build version of the tag manager
* e2e test the build version of the tag manager in chrome headless browser
* deploy test/prod containers in a GCP bucket
* deploy testable open websites with the TMS running on it for functional testing
* dockerized TMS to run the TMS locally in isolation
* dockerized TMS that registers images in GitLab private registery
* stable pipeline file with artifacts enabled both on success as failure
* babel/ts for browser compatibility

Some parts of the generated boilerplate can look weird as the pipeline will interpolate varialbes/files/libs and build the full version when running `npx tag-cli bundle-tag-manager`. 

> The roadmap is to replace interpolated files with a configuration (json/yml) file to make it more intuitive.

#### Dependencies
By default dependencies are fixed in the package-lock.json and package.json files. Updating a package manually will break the pipeline as it runs `npm ci`, thus you have to update both package.json as package-lock.json:

```bash
npm i yourpackage@1.0.0
```

#### Examples
Make sure docker is installed and you've updated your [.env](https://docs.docker.com/compose/environment-variables/) file.

```bash
# creating a tag manager boilerplate
npx tag-cli create-tag-manager

# running a tag manager locally in isolation on localhost:8080
docker build -t ${img_name} .
docker run --name ${container_name} --rm -p 8080:8080 -ti ${img_name}:latest

# running a tag manager locally in isolation with docker-compose
docker-compose build bundle
docker-compose up bundle

# running the full tms pipeline (except deployment in gcp/test sites) locally in isolation
docker-compose build deploy
docker-compose up deploy
```


### create-new-tag
The `create-new-tag` command creates a new Tag boilerplate designed to use with @d-cat/tag-cli within GitLab CI/CD.

```bash
Options:
  --version               Show version number                          [boolean]
  --help                  Show help                                    [boolean]
```

#### What's included
The Tag boilerplate contains all configurations to:
* Jest setup
* tslint setup
* prettier
* husky
* tag config file (`tag-cli.json`)
* dockerized tag environment to run the tag locally in isolation
* dockerized TMS that registers images in GitLab private registery
* stable pipeline file with artifacts enabled both on success and failure
* standard-version to created changelog + semver in the pipeline

#### Dependencies
By default dependencies are fixed in the package-lock.json and package.json files. Updating a package manually will break the pipeline as it runs `npm ci`, thus you have to update both package.json as package-lock.json:

```bash
npm i yourpackage@1.0.0
```

#### Examples
Make sure docker is installed and you've updated your [.env](https://docs.docker.com/compose/environment-variables/) file.

```bash
# creating a tag boilerplate
npx tag-cli create-new-tag

# running a tag locally in isolation on localhost:1234
docker build -t ${img_name} .
docker run --name ${tag_name} --rm -p 1234:1234 ${img_name}:latest

# running a tag locally in isolation with docker-compose
docker-compose build build
docker-compose up build

# running the full tag pipeline (except uploading artifacts) locally in isolation
docker-compose build pipeline
docker-compose up pipeline
```

### bundle-tag-manager
The `bundle-tag-manager` command bundles tag `artifacts` to eventually transpile and deploy a Tag Manager. 

![bundle-tag-manager](https://www.plantuml.com/plantuml/png/PP4nRuD038Nt-nLFx205MBf46IfbQQTaYpeud8Ee21Tn9b9LyTzxLYyj5zY-Ppy_czjveL6cQsykhhSy8ZkuAsFVoHkTiH_TTClmRH2QkWir0g6sJh5AiKnnOsRpDpkEVULRxxuUqyd7ECs9dKVsSkY4DokbN2dLIgdD38F_s2ErUAU1MXxrc5DW_w5xDRsRhCRY97Pu2LyXlnLBGcVoZCms93aFzzpoNTruf0M7uiBx6Rp0h7wz74MnHGmBN3vnzSJrakEIAgMxBG5vlatILzNuPysE1niU-GS0)

```bash
Options:
  --version                Show version number                         [boolean]
  --help                   Show help                                   [boolean]
  --access-token, --token  The GitLab personal accesstoken with owner rights.
  --group-id, --id         The GitLab Group ID that should be analyzed.
  --dir-name, --dir        The unique dir name where to store the temporary artifacts.
  --branch-name, --branch  The current branch.
  --job-token, --j         GitLabs built-in job token: $CI_JOB_TOKEN. This token is generated for each job.
  --environment --e        TMS environment, should be either `development` or `production`.
```

#### Example
Note that all flags are either mandatory or are set as a node environment variable.

```bash
npx tag-cli bundle-tag-manager
```

### update-dependents
If not using npm semver, you can use `update-dependents` to keep track of dependencies. The `update-dependents` command updates and triggers the first 1000 [default branches](https://docs.gitlab.com/ee/user/project/repository/branches/#default-branch) of all GitLab projects that either use the current package as dependency or as devDependency, using the [GitLab API](https://docs.gitlab.com/ce/api/projects.html#list-all-projects). Please note all arguments are mandatory, however you could be using environment variables.

```bash
# flags
Options:
  --version                Show version number                         [boolean]
  --help                   Show help                                   [boolean]
  --access-token, --token  The GitLab personal accesstoken with owner rights.
  --project-id, --d        The current project ID, equal to: $CI_PROJECT_ID.
  --project-path, --p      The relative path to the project's repository in GitLab. This equals GitLab's built-in variable: $CI_PROJECT_PATH.
  --key, --k               SSH Key linked to your personal GitLab account.
  --user, -u               Git username linked to your personal GitLab account.
  --email, -e              Git email linked to your personal GitLab account.
  --job-token, --j         GitLabs built-in job token: $CI_JOB_TOKEN. This token is generated for each job.
```

![update-dependents](https://www.plantuml.com/plantuml/png/dT4x3iCW40JGtgT0z3Wo7-WYxX5Hh6pa8X1PoVh-yG7C8hOU7iE8-4FuubdBTC3wXZqB6JUr0ZuGTeMv7WKmgqLEz04jwTnqSjihS9qBV2SFLy7hTbeIIZt5RQRJk34COnd6fSOWIwDXunacj1wdavZd1beQHOPXBCCusj1ev5izmmJQnFpPpbh-)

#### Example
Note that all flags are either mandatory or are set as an environment variable:

```bash
ACCESS_TOKEN=myAccesToken
DIR_NAME=foo
PROJECT_ID=1210
SSH_KEY=key
GIT_EMAIL=myEmail
```

```bash
npx tag-cli update-dependents --user myGitName
```

#### Troubleshooting

`GitLab API: Fetching projects. Unexpected response received from GitLab: [object Object], or the amount of received projects meets the maximum of 1000. Received: undefined` : Retry the pipeline, as the GitLab API didn't returned a correct response. It has probably something to do with a connection lost / timeout.

### deploy-tag-template
The `deploy-tag-template` command deploys a tag template on a NPM public registery.

```bash
Options:
  --version                  Show version number                         [boolean]
  --help                     Show help                                   [boolean]
  --access-token, --token    The GitLab personal accesstoken with owner rights.
  --branch-name, --branch    The current branch.
  --project-path, --p        The relative path to the project's repository in GitLab. This equals GitLab's built-in variable: $CI_PROJECT_PATH.
  --key, --k                 SSH Key linked to your personal GitLab account.
  --user, -u                 Git username linked to your personal GitLab account.
  --email, -e                Git email linked to your personal GitLab account.
  --o-auth-token, --oauth    NPM Registery authentication file.
```

#### Examples
Note that all flags are either mandatory or are set as an environment variable.

```bash
npx tag-cli deploy-tag-template
```

### publish-tag
The `publish-tag` command publishes an tags artifact.

```bash
Options:
  --version             Show version number                              [boolean]
  --help                Show help                                        [boolean]
  --job-token, -j       The GitLab's built-in job token: $CI_JOB_TOKEN. This token
                        is generated for each job.
  --token, -t           GitLab's personal access token with admin rights.
  --tag-manager-id, -i  GitLab's Tag Manager project ID.
  --key, -k             SSH Key linked to your personal GitLab account.
  --user, -u            Git username linked to your personal GitLab account.
  --email, -e           Git email linked to your personal GitLab account.
  --increment-version   Boolean that indicates if standard-version should invoke.
```

### Examples
Note that all flags are either mandatory or are set as an environment variable.

```bash
# incrementing version
npx tag-cli publish-tag --increment-version

# do not inrement version
npx tag-cli publish-tag --no-increment-version
```

### test-tag
The `test-tag` command is part of the tags pipeline and run both the unit tests as uploading a code coverage report to [Codecov](https://codecov.io/).

```bash
Options:
  --version                 Show version number                              [boolean]
  --help                    Show help                                        [boolean]
  --codecov, -c             Your Codecov token to publish code coverage report.
  --branch-name, --n        The current branch name, equal to: $CI_COMMIT_REF_NAME.
```

### Examples
Note that all flags are either mandatory or are set as an environment variable.

```bash
npx tag-cli test-tag
```

### lint-tag
The `lint-tag` command runs the [TypeScript linter](https://palantir.github.io/tslint/), as described in the tslint.json.

```bash
Options:
  --version                 Show version number                              [boolean]
  --help                    Show help                                        [boolean]
  --branch-name, --n        The current branch name, equal to: $CI_COMMIT_REF_NAME.
```

### Examples
Note that all flags are either mandatory or are set as an environment variable.

```bash
npx tag-cli lint-tag --branch-name $CI_COMMIT_REF_NAME
```

### type-tag
The `type-tag` command runs type checks the tag according TypeScript specs. 

```bash
Options:
  --version                 Show version number                              [boolean]
  --help                    Show help                                        [boolean]
  --branch-name, --n        The current branch name, equal to: $CI_COMMIT_REF_NAME.
```

### Examples
Note that all flags are either mandatory or are set as an environment variable.

```bash
npx tag-cli type-tag --branch-name $CI_COMMIT_REF_NAME
```

### deploy-test-instance
The `deploy-test-instance` command deploys a build version of the Tag Manager on a private or public website at https://instances.gitlab.io/[tagmanager_id]/[branchName]. It can take up to 10 minutes before your test instance is deployed, starting from your push.

```bash
Options:
  --version                Show version number                          [boolean]
  --help                   Show help                                    [boolean]
  --access-token, --token  The GitLab personal accesstoken with owner rights.
  --group-id, --id         The GitLab Group ID that should be analyzed
  --branch-name, --n       The current branch name, equal to: $CI_COMMIT_REF_NAME.
  --job-token, --j         The GitLab's built-in job token: $CI_JOB_TOKEN. This token is generated for each job.
```

### Examples
Note that all flags are either mandatory or are set as an environment variable.

```bash
npx tag-cli deploy-test-instance
```

### deploy-tag-manager
The deploy tag manager commands deploys the build tag manager to a GCP bucket and a GitLab test page.

```bash
Options:
  --version            Show version number                               [boolean]
  --help               Show help                                         [boolean]
  --bucket-name, -b    Name of the Google Cloud Bucket.
  --key-file-name, -k  Google Cloud authentication JSON key.
  --group-name, -i     The namespace of the GitLab Group, equal to: $CI_PROJECT_NAMESPACE.
  --branch-name, -n    The current branch name, equal to: $CI_COMMIT_REF_NAME.
  --node-email, -gm    Gmail email address, that can function as transporter. More info at: https://nodemailer.com/usage/using-gmail/.
  --node-pass, -pass   Password of the gmail account that functions as transporter.
  --receivers, -list   String array of receivers.
  --is-empty -e        Boolean that indicates if an empty container should be deployed. Defaults to false.
```

### Examples
Note that all flags are either mandatory or are set as an environment variable.

```bash
# deploy empty
npx tag-cli deploy-tag-manager --is-empty

# deploy non-empty (default)
npx tag-cli deploy-tag-manager --no-is-empty
```

## GitLab Configurations

### Setup of a Tag Manager

The `create-tag-manager` creates a Tag Manager boilerplate.

> It's recommended to not modify the generated files.

```bash
mkdir tag-manager
cd tag-manager
npm init --y
npm i -D @d-cat/tag-cli
npx tag-cli create-tag-manager
```

### GitLab configuration

Make sure you did all necessary steps to [start with GitLab](https://docs.gitlab.com/ee/gitlab-basics/).

- Create a new GitLab (sub)group with name as Container ID: (i.e. 8030);
- Create a new project, called Tag Manager;
- Create CI/CD variables.

#### CI/CD variables to create in GitLab

Before you run the pipeline and the tag manager can be deployed, make sure you [create the necessary CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#custom-environment-variables) in your GitLab project.

| CI/CD variable          |   Type   |                                                                                                Description |
| ----------------------- | :------: | :--------------------------------------------------------------------------------------------------------- |
| `PERSONAL_ACCESS_TOKEN` | variable |                                       Your personal access token, that has owner rights of the tags group. |
| `CONTAINER_ID`          | variable |                                                                  Group ID that should be queried for tags. |
| `GCLOUD_SERVICE_KEY`    |   file   | Your [authentication file](https://cloud.google.com/docs/authentication/getting-started) for Google Cloud. |
| `SSH_KEY`               |   file   |                                                           Your SSH key to clone and push repo's of GitLab. |
| `GIT_USER_EMAIL`        | variable |                                                                   Your git email: `git config user.email`. |
| `GIT_USER_NAME`         | variable |                                                                Your git user name: `git config user.name`. |

## Troubleshooting
- `Publishing tag TypeError: Cannot read property 'map' of undefined`: make sure your `tag-cli.json` has an string array of both `branchesToImportInTagManager` and `branchesToRunInPipeline`.
- `Publishing tag This tag didn't triggered the pipeline.`: Make sure the branch that triggered the pipeline equals a branch that is whitelisted in your `tag-cli.json`.
  When having other issues, please contact [D-CAT](https://data.ziggo.nl/).
- `GitLab API: Fetching projects. Unexpected response received from GitLab: [object Object], or the amount of received projects meets the maximum of 1000. Received: undefined` : Retry the pipeline, as the GitLab API didn't returned a correct response. It has probably something to do with a connection lost / timeout.


### Setup of a Tag
Steps to create a tag.

```bash
mkdir my-tag
cd my-tag
npm init
npm i -D @d-cat/tag-cli
npx tag-cli create-new-tag
```

#### tag-cli.json

The `create-new-tag` command will create a file called `tag-cli.json`. This file contains all settings to indicate it's behavior. The `tag-cli.json` file includes both `pipeline` as `tag manager` settings.

##### Pipeline settings

This are settings that indicates how a tag should behave.

| Prop        | Type           | Desc  |
| ------------- |:-------------:| :-----|
| `isPipelineActive`      | Boolean | Boolean that indicates if the tags pipeline should run.|
| `pipelineBranches`      | String[]      | String array of branches that should trigger the Tag's pipeline. |
| `isImportInTagManager` | Boolean      |   Boolean to indicate if the tag should be imported in the tag manager. |
| `tagManagerBranches`      | String[]      | String array of tag branches that should be included in a tag manager bundle. |
| `isActive` | Boolean      | Boolean that indicates if the tag is active. |
| `isTrigger` | Boolean      | Boolean that indicates if the tag should trigger the Tag Managers pipeline after a publish. |

##### Tag Manager settings

This are settings that determine how the tag should behave inside the Tag Manager.

| Prop        | Type           | Desc  |
| ------------- |:-------------:| :-----|
| `firingAmount`      | Number | Amount a tag should be invoked when all business rules apply. |
| `priority`      | Number      | Priority of tag. 1 is highest priority. |
| `id` | String      |   UUID. |
| `urls`      | IUrl[]      | Object Array that contains 2 props: `url` (RegExp) and `reverse` (boolean).  |
| `triggers` | ITrigger[]      | Boolean that indicates if the tag is active. |

###### `ITrigger`

| Options   |  Type   | Required  Description |
| --------- | :-----: | :------ |:---- |
| `type`    | String  |     true | Type of the trigger, this must be one of the following: `instantly`, `datalayer`, `event`, `domEvent`, `persisted`. Note that when using `instantly`, this means the other triggers automatically are ignored, thus the tag will execute immediately. |
| `id`      | String  |     true |                                                                                                                                    Uniquely generated ID. Using the CLI this will generate an ID using [uuid/v1](https://www.npmjs.com/package/uuid). |
| `name`    | String  |    false |                                                                                                                                                                                         Depending on the type, the name key has a different function. |
| `value`   | String  |    false |                                                                                                                                                                                        Depending on the type, the value key has a different function. |
| `reverse` | Boolean |    false |                                                                                                                                                                                                            Reverse the match on either value or name. |
| `element` | String  |    false |                                                                                                                                                                                                 `window`, `document` both as string or an element ID. |

#### GitLab configuration

Make sure you did all necessary steps to [start with GitLab](https://docs.gitlab.com/ee/gitlab-basics/).

- Create a new project inside a GitLab group.
- Create CI/CD variables
- Push branches to GitLab

##### CI/CD variables to create in GitLab

Before you run the pipeline and the tag manager can be deployed, make sure you [create the necessary CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#custom-environment-variables) in your GitLab project.

| CI/CD variable          |   Type   |                                                                                                Description |
| ----------------------- | :------: | :----- |
| `PERSONAL_ACCESS_TOKEN` | variable |                                       Your personal access token, that has owner rights of the tags group. |
| `TAG_MANAGER_ID`        | variable |                                                                      Gitlab Project ID of the Tag Manager. |
| `GCLOUD_SERVICE_KEY`    |   file   | Your [authentication file](https://cloud.google.com/docs/authentication/getting-started) for Google Cloud. |
| `SSH_KEY`               |   file   |                                                           Your SSH key to clone and push repo's of GitLab. |
| `GIT_USER_EMAIL`        | variable |                                                                   Your git email: `git config user.email`. |
| `GIT_USER_NAME`         | variable |                                                                Your git user name: `git config user.name`. |
| `CODECOV_TOKEN`         | variable |                                                       Your Codecov token to publish code coverage reports. |

#### Troubleshooting
> If the pipeline isn't running after the initial commit, trigger the pipeline manually.