@raisenow/tamaro-cli 1.6.1 → 1.7.0-dev.1

package/.history/README_20230911145033.md

@@ -0,0 +1,245 @@
+# Getting started
+
+It’s a command-line interface for all operations with Tamaro customer configurations and _Tamaro Core_.
+
+You don’t need to install it manually. The recommended way to run it is by using the `npx` command, which comes along with NPM.
+
+# Usage
+
+To see an overview of all possible commands just run the following command without any arguments.
+
+```bash
+npx -y @raisenow/tamaro-cli
+```
+
+To see the informoation about some particular command (for example `dev` command), prepend `help` before the command name:
+
+```bash
+npx -y @raisenow/tamaro-cli help dev
+```
+
+Substitute `dev` with the command you want to get information about.
+
+# Commands
+
+Available commands:
+
+- [`dev`](#dev)
+- [`build`](#build)
+- [`serve`](#serve)
+- [`deploy`](#deploy)
+- [`list-deployed`](#list-deployed)
+- [`deploy-email-config`](#deploy-email-config)
+
+## `dev`
+
+Runs the local development server for _Tamaro Core_ or a particular customer configuration.
+
+### Options
+
+- `--local-core` – Load _Tamaro Core_ from localhost:1234 instead of the CDN
+- `--https` – Let local web server serve Tamaro with SSL encryption
+- `--port <port>` – Web server port (default: 1234)
+- `--env <env>` – Environment (dev, stage, prod)
+
+### Run local server using Tamaro Core from CDN
+
+Run the local development server for the _example-02-typical-customisations_ customer configuration. You will be able to access Tamaro on http://localhost:1234 (port may differ, see console output).
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli dev
+```
+
+### Run local server using a locally running Tamaro Core
+
+1.  Run the local development web server for _Tamaro Core_ in the first terminal tab. You will be able to access a default configuration of Tamaro on http://localhost:1234 (port may differ, see console output).
+
+    ```bash
+    cd /path/to/tamaro-core
+    npx -y @raisenow/tamaro-cli dev
+    ```
+
+2.  Run the local development web server for the _example-02-typical-customisations_ customer configuration in the second terminal tab. After running this command, you will able to access the configuration on http://localhost:1235 (port may differ, see console output).
+
+    ```bash
+    cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+    npx -y @raisenow/tamaro-cli dev --local-core
+    ```
+
+### Use Transport Level Security (HTTPS)
+
+You might want to the local web server to serve Tamaro over HTTPS, for example for testing wallet payments over Google Pay. For that, you have to install [mkcert](https://mkcert.org/), then generate a local certificate and key file and install it into your local trust stores using this command in the root directory of the Tamaro configuration repository (or Tamaro Core):
+
+Install `mkcert`:
+
+```bash
+brew install mkcert
+```
+
+Generate certificate:
+
+```bash
+mkcert -install -cert-file localhost.crt -key-file localhost.key localhost 127.0.0.1 0.0.0.0 ::1
+```
+
+You will see that the certificate and key files are created. Keep them for yourself. Do not share them or commit them. (They should be ignored by Git.)
+
+You can then use the flag `--https` with the CLI. If you are using the local Tamaro Core, you also have to serve that over HTTPS. Certificate and key files must be copied to Tamaro Core folder as well.
+
+## `build`
+
+Build an optimised (minified) bundle of _Tamaro Core_ or a customer configuration.
+
+### Options
+
+- `--local-core` – Load _Tamaro Core_ from localhost:1234 instead of the CDN
+- `--analyze` – Generate bundle statistics to `reports` folder
+- `--serve` – Run the generated bundle with a local web server
+- `--https` – Let local web server serve Tamaro with SSL encryption
+- `--port <port>` – Web server port (default: 1234)
+- `--env <env>` – Environment (dev, stage, prod)
+- `--deploy` – Deploy _Tamaro Core_ or a customer configuration bundle to AWS S3
+- `--tag <tag>` – Tag which should be used for the deployment of the bundle (default: “latest”)
+
+### Build and deploy a customer configuration
+
+Build and deploy an optimised (minified) bundle of the _example-02-typical-customisations_ customer configuration.
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli build --deploy
+```
+
+As a result, the bundle should be deployed to: https://tamaro.raisenow.com/example-02-typical-customisations/latest/
+
+### Build and deploy a customer configuration with a specific tag
+
+Build and deploy an optimised (minified) bundle of the _example-02-typical-customisations_ customer configuration with the tag _WEB-123_.
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli build --deploy --tag WEB-123
+```
+
+As a result, the bundle should be deployed to: https://tamaro.raisenow.com/example-02-typical-customisations/WEB-123/
+
+### Build and serve a customer configuration
+
+Build and serve an optimised (minified) bundle of the _example-02-typical-customisations_ customer configuration.
+
+After running this command, a local web server should be running on http://localhost:1234 (port may differ, see console output).
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli build --serve
+```
+
+## `serve`
+
+Run a local web server for pre-built bundle.
+
+### Example
+
+1.  Build an optimised (minified) bundle of the _example-02-typical-customisations_ customer configuration
+
+    ```bash
+    cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+    npx -y @raisenow/tamaro-cli build
+    ```
+
+2.  Serve it. After running this command, web-server should be running on http://localhost:1234 (port may differ, see console output).
+
+    ```bash
+    npx -y @raisenow/tamaro-cli serve
+    ```
+
+## `deploy`
+
+Deploy a pre-built _Tamaro Core_ or customer configuration bundle to AWS S3.
+
+### Options
+
+- `--tag <tag>` – Tag which should be used for the deployment of the bundle (default: “latest”)
+
+Make sure you have built the bundle before deploying it with this command, otherwise you may mistakenly deploy the bundle from a previous build.
+
+### Example
+
+1.  Build an optimised (minified) bundle of the _example-02-typical-customisations_ customer configuration
+
+    ```bash
+    cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+    npx -y @raisenow/tamaro-cli build
+    ```
+
+2.  Deploy it
+
+    ```bash
+    npx -y @raisenow/tamaro-cli deploy
+    ```
+
+3.  Optionally, deploy it with the _WEB-123_ tag
+
+    ```bash
+    npx -y @raisenow/tamaro-cli deploy --tag WEB-123
+    ```
+
+## `list-deployed`
+
+List deployments of _Tamaro Core_ or a particular customer configuration.
+
+### Options
+
+- `--config <config>` – Configuration name (default: current customer configuration)
+
+### Example
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli list-deployed
+```
+
+## `deploy-email-config`
+
+Deploy a widget’s email configuration to AWS S3.
+
+### Example
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli deploy-email-config
+```
+
+# Development
+
+Make sure you have installed and activated the proper `node` and `npm` versions.
+
+- `node: ">= 16"`
+- `npm: ">= 8"`
+
+Clone the repository and install its dependencies:
+
+```bash
+git clone git@bitbucket.org:raisenow/tamaro-cli.git
+cd tamaro-cli
+npm ci
+```
+
+Link package source to be able to run its local version:
+
+```bash
+npm link .
+```
+
+Run the `build:watch` script to watch source files and automatically rebuild on changes. It must be running during the _Tamaro CLI_ development process.
+
+```bash
+npm run build:watch
+```
+
+To use the locally linked version of _Tamaro CLI_, use it without `@raisenow/` scope, `-y` flag is also not needed:
+
+```bash
+npx tamaro-cli dev
+```

package/.history/README_20230911151749.md

@@ -0,0 +1,245 @@
+# Getting started
+
+It’s a command-line interface for all operations with Tamaro customer configurations and _Tamaro Core_.
+
+You don’t need to install it manually. The recommended way to run it is by using the `npx` command, which comes along with NPM.
+
+# Usage
+
+To see an overview of all possible commands just run the following command without any arguments.
+
+```bash
+npx -y @raisenow/tamaro-cli
+```
+
+To see the informoation about some particular command (for example `dev` command), prepend `help` before the command name:
+
+```bash
+npx -y @raisenow/tamaro-cli help dev
+```
+
+Substitute `dev` with the command you want to get information about.
+
+# Commands
+
+Available commands:
+
+- [`dev`](#dev)
+- [`build`](#build)
+- [`serve`](#serve)
+- [`deploy`](#deploy)
+- [`list-deployed`](#list-deployed)
+- [`deploy-email-config`](#deploy-email-config)
+
+## `dev`
+
+Runs the local development server for _Tamaro Core_ or a particular customer configuration.
+
+### Options
+
+- `--local-core` – Load _Tamaro Core_ from localhost:1234 instead of the CDN
+- `--https` – Let local web server serve Tamaro with SSL encryption
+- `--port <port>` – Web server port (default: 1234)
+- `--env <env>` – Environment (dev, stage, prod)
+
+### Run local server using Tamaro Core from CDN
+
+Run the local development server for the _example-02-typical-customisations_ customer configuration. You will be able to access Tamaro on http://localhost:1234 (port may differ, see console output).
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli dev
+```
+
+### Run local server using a locally running Tamaro Core
+
+1.  Run the local development web server for _Tamaro Core_ in the first terminal tab. You will be able to access a default configuration of Tamaro on http://localhost:1234 (port may differ, see console output).
+
+    ```bash
+    cd /path/to/tamaro-core
+    npx -y @raisenow/tamaro-cli dev
+    ```
+
+2.  Run the local development web server for the _example-02-typical-customisations_ customer configuration in the second terminal tab. After running this command, you will able to access the configuration on http://localhost:1235 (port may differ, see console output).
+
+    ```bash
+    cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+    npx -y @raisenow/tamaro-cli dev --local-core
+    ```
+
+### Use Transport Level Security (HTTPS)
+
+You might want to the local web server to serve Tamaro over HTTPS, for example for testing wallet payments over Google Pay. For that, you have to install [mkcert](https://mkcert.org/), then generate a local certificate and key file and install it into your local trust stores using this command in the root directory of the Tamaro configuration repository (or Tamaro Core):
+
+Install `mkcert`:
+
+```bash
+brew install mkcert
+```
+
+Generate certificate:
+
+```bash
+mkcert -install -cert-file localhost.crt -key-file localhost.key localhost 127.0.0.1 0.0.0.0 ::1
+```
+
+You will see that the certificate and key files are created. Keep them for yourself. Do not share them or commit them. (They should be ignored by Git.)
+
+You can then use the flag `--https` with the CLI. If you are using the local Tamaro Core, you also have to serve that over HTTPS. Certificate and key files must be copied to Tamaro Core folder as well.
+
+## `build`
+
+Build an optimised (minified) bundle of _Tamaro Core_ or a customer configuration.
+
+### Options
+
+- `--local-core` – Load _Tamaro Core_ from localhost:1234 instead of the CDN
+- `--analyze` – Generate bundle statistics to `reports` folder
+- `--serve` – Run the generated bundle with a local web server
+- `--https` – Let local web server serve Tamaro with SSL encryption
+- `--port <port>` – Web server port (default: 1234)
+- `--env <env>` – Environment (dev, stage, prod)
+- `--deploy` – Deploy _Tamaro Core_ or a customer configuration bundle to AWS S3
+- `--tag <tag>` – Tag which should be used for the deployment of the bundle (default: "latest")
+
+### Build and deploy a customer configuration
+
+Build and deploy an optimised (minified) bundle of the _example-02-typical-customisations_ customer configuration.
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli build --deploy
+```
+
+As a result, the bundle should be deployed to: https://tamaro.raisenow.com/example-02-typical-customisations/latest/
+
+### Build and deploy a customer configuration with a specific tag
+
+Build and deploy an optimised (minified) bundle of the _example-02-typical-customisations_ customer configuration with the tag _WEB-123_.
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli build --deploy --tag WEB-123
+```
+
+As a result, the bundle should be deployed to: https://tamaro.raisenow.com/example-02-typical-customisations/WEB-123/
+
+### Build and serve a customer configuration
+
+Build and serve an optimised (minified) bundle of the _example-02-typical-customisations_ customer configuration.
+
+After running this command, a local web server should be running on http://localhost:1234 (port may differ, see console output).
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli build --serve
+```
+
+## `serve`
+
+Run a local web server for pre-built bundle.
+
+### Example
+
+1.  Build an optimised (minified) bundle of the _example-02-typical-customisations_ customer configuration
+
+    ```bash
+    cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+    npx -y @raisenow/tamaro-cli build
+    ```
+
+2.  Serve it. After running this command, web-server should be running on http://localhost:1234 (port may differ, see console output).
+
+    ```bash
+    npx -y @raisenow/tamaro-cli serve
+    ```
+
+## `deploy`
+
+Deploy a pre-built _Tamaro Core_ or customer configuration bundle to AWS S3.
+
+### Options
+
+- `--tag <tag>` – Tag which should be used for the deployment of the bundle (default: "latest")
+
+Make sure you have built the bundle before deploying it with this command, otherwise you may mistakenly deploy the bundle from a previous build.
+
+### Example
+
+1.  Build an optimised (minified) bundle of the _example-02-typical-customisations_ customer configuration
+
+    ```bash
+    cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+    npx -y @raisenow/tamaro-cli build
+    ```
+
+2.  Deploy it
+
+    ```bash
+    npx -y @raisenow/tamaro-cli deploy
+    ```
+
+3.  Optionally, deploy it with the _WEB-123_ tag
+
+    ```bash
+    npx -y @raisenow/tamaro-cli deploy --tag WEB-123
+    ```
+
+## `list-deployed`
+
+List deployments of _Tamaro Core_ or a particular customer configuration.
+
+### Options
+
+- `--config <config>` – Configuration name (default: current customer configuration)
+
+### Example
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli list-deployed
+```
+
+## `deploy-email-config`
+
+Deploy a widget’s email configuration to AWS S3.
+
+### Example
+
+```bash
+cd /path/to/tamaro-configurations/configs/example-02-typical-customisations
+npx -y @raisenow/tamaro-cli deploy-email-config
+```
+
+# Development
+
+Make sure you have installed and activated the proper `node` and `npm` versions.
+
+- `node: ">= 16"`
+- `npm: ">= 8"`
+
+Clone the repository and install its dependencies:
+
+```bash
+git clone git@bitbucket.org:raisenow/tamaro-cli.git
+cd tamaro-cli
+npm ci
+```
+
+Link package source to be able to run its local version:
+
+```bash
+npm link .
+```
+
+Run the `build:watch` script to watch source files and automatically rebuild on changes. It must be running during the _Tamaro CLI_ development process.
+
+```bash
+npm run build:watch
+```
+
+To use the locally linked version of _Tamaro CLI_, use it without `@raisenow/` scope, `-y` flag is also not needed:
+
+```bash
+npx tamaro-cli dev
+```