@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
Set of commands used to create, test or deploy tags/ tag managers / tag-templates.

### 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]
  --accessToken, --token   The GitLab personal accesstoken with owner rights.
  --groupId, --id          The GitLab Group ID that should be analyzed.
  --dirName, --dir         The unique dir name where to store the artifacts.
  --branchName, --branch   The current branch.
  --jobToken, --j          GitLabs built-in job token: $CI_JOB_TOKEN. This token is generated for each job.
  --environment --e        Environment string to indicate to what GCP bucket we deploy.
```

#### Example

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

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

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

#### Example

```bash
npx tag-cli create-tag-manager
```

### create-new-tag
Command to create a tag boilerplate.

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

### update-dependents
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]
  --accessToken, --token   The GitLab personal accesstoken with owner rights.
  --projectId, --d         The current project ID, equal to: $CI_PROJECT_ID.
  --projectPath, --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.
  --jobToken, --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-)

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

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 given tag template at NPM, including incrementing versioning based on your commit through [commitizen](http://commitizen.github.io/cz-cli/) / [commitlint](https://commitlint.js.org/#/).

```bash
Options:
  --version                Show version number                         [boolean]
  --help                   Show help                                   [boolean]
  --accessToken, --token   The GitLab personal accesstoken with owner rights.
  --branchName, --branch   The current branch.
  --projectPath, --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.
  --oAuthToken, --oauth    NPM Registery authentication file.
```

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

#### 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.

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

```bash
Options:
  --version           Show version number                              [boolean]
  --help              Show help                                        [boolean]
  --jobToken, -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.
  --tagManagerId, -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.
  --incrementVersion  Boolean that indicates if standard-version should invoke.
```

```bash
npx tag-cli publish-tag
```

### 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. # CODE_COV_TOKEN
  --branchName, --n       The current branch name, equal to: $CI_COMMIT_REF_NAME. # BRANCH_NAME
```

```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]
  --branchName, --n       The current branch name, equal to: $CI_COMMIT_REF_NAME.
```

```bash
npx tag-cli lint-tag
```

### type-tag
The `type-tag` command runs the [TypeScript transpiler](http://www.typescriptlang.org/), including declarations as described in the tsconfig.json. 

```bash
Options:
  --version           Show version number                              [boolean]
  --help              Show help                                        [boolean]
  --branchName, --n       The current branch name, equal to: $CI_COMMIT_REF_NAME. # or pass BRANCH_NAME as environment var
```

```bash
npx tag-cli lint-tag --branchName development
```

### deploy-test-instance
The `deploy-test-instance` command deploys a build version of the Tag Manager on a private test 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]
  --accessToken, --token  The GitLab personal accesstoken with owner rights.
  --groupId, --id         The GitLab Group ID that should be analyzed
  --branchName, --n       The current branch name, equal to: $CI_COMMIT_REF_NAME.
  --jobToken, --j         The GitLab's built-in job token: $CI_JOB_TOKEN. This token is generated for each job.
```

```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]
  --bucketName, -b   Name of the Google Cloud Bucket.
  --keyFileName, -k  Google Cloud authentication JSON key.
  --groupName, -i    The namespace of the GitLab Group, equal to: $CI_PROJECT_NAMESPACE.
  --branchName, -n   The current branch name, equal to: $CI_COMMIT_REF_NAME.
  --nodeEmail, -gm   Gmail email address, that can function as transporter. More info at: https://nodemailer.com/usage/using-gmail/.
  --nodePass, -pass  Password of the gmail account that functions as transporter.
  --receivers, -list String array of receivers.
```

```bash
npx tag-cli deploy-tag-manager
```

## 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.