@raisenow/tamaro-cli 1.0.6 → 1.0.10

package/readme.md

@@ -0,0 +1,227 @@
+# 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)
+- [`deploy`](#deploy)
+- [`serve`](#serve)
+- [`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 instead of the CDN
+
+### 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
+    ```
+
+## `build`
+
+Build an optimised (minified) bundle of _Tamaro Core_ or a customer configuration.
+
+### Options
+
+- `--local-core` – Load _Tamaro Core_ from localhost instead of the CDN
+- `--analyze` – Generate bundle statistics to `reports` folder
+- `--deploy` – Deploy _Tamaro Core_ or a customer configuration bundle to AWS S3
+- `--serve` – Run the generated bundle with a local web server
+- `--tag <tag>` – Tag which should be used for the deployment of the bundle (default: “latest”)
+- `--profile <profile>` – AWS profile which should be used for the deployment of the bundle (default: “payments-prod-cs-deployer”)
+
+### 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
+```
+
+## `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”)
+- `--profile <profile>` – AWS profile which should be used for the deployment of the bundle (default: “payments-prod-cs-deployer”)
+
+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
+   ```
+
+## `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
+    ```
+
+## `list-deployed`
+
+List deployments of _Tamaro Core_ or a particular customer configuration.
+
+### Options
+
+- `--config <config>` – Configuration name (default: current customer configuration)
+- `--profile <profile>` – AWS profile which should be used for fetching deployments (default: “payments-prod-cs-deployer”)
+
+### 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.
+
+### Options
+
+- `--bucket <bucket>` – AWS S3 bucket where it should be deployed (default: “rnw-email-service”)
+- `--profile <profile>` – AWS profile which should be used for the deployment of email configuration (default: “payments-prod-cs-deployer”)
+
+### 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 `dev` script to watch source files and automatically rebuild on changes. It must be running during the _Tamaro CLI_ development process.
+
+```bash
+npm run dev
+```
+
+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/src/cli.ts

@@ -2,10 +2,18 @@
 
 import {createCommand} from 'commander'
 import pkg from '../package.json'
+import {logError} from 'lib/helpers'
 import {dev, DevOptions} from 'commands/dev'
 import {build, BuildOptions} from 'commands/build'
-import {deploy, DeployOptions} from 'commands/deploy'
+import {DEFAULT_TAG, deploy, DeployOptions} from 'commands/deploy'
 import {serve} from 'commands/serve'
+import {listDeployed, ListDeployedOptions} from 'commands/list-deployed'
+import {
+  DEFAULT_AWS_S3_EMAIL_CONFIG_BUCKET,
+  deployEmailConfig,
+  DeployEmailConfigOptions,
+} from 'commands/deploy-email-config'
+import {DEFAULT_AWS_PROFILE} from 'lib/aws'
 
 ///////////////////////////////////////////////////////////////////////////////
 
@@ -18,7 +26,7 @@ process.on('unhandledRejection', (error) => {
 
 // Exit on ctrl+c
 process.on('SIGINT', () => {
-  process.exit(0)
+  process.exit(1)
 })
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -29,22 +37,46 @@ const cli = createCommand().name(pkg.name).version(pkg.version, '-v, --version')
 
 cli
   .command('dev')
-  .description('Run dev web-server for Tamaro Core or customer configuration')
-  .option('--local-core', 'Load Tamaro Core from localhost instead of CDN')
+  .description(
+    'Run the local development server for Tamaro Core or a particular customer configuration',
+  )
+  .option(
+    '--local-core',
+    'Load Tamaro Core from localhost instead of the CDN',
+    false,
+  )
   .action(async (options: DevOptions) => {
     await dev(options)
   })
 
 cli
   .command('build')
-  .description('Build Tamaro Core or customer configuration for production')
-  .option('--local-core', 'Load Tamaro Core from localhost instead of CDN')
-  .option('--analyze', 'Generate build statistics to "reports" folder')
-  .option('--deploy', 'Deploy to AWS')
-  .option('--latest', 'Deploy with tag "latest"')
-  .option('--serve', 'Run web-server for previously created build')
-  .option('--tag <tag>', 'Deploy with a specific tag')
-  .action(async (options: BuildOptions) => {
+  .description(
+    'Build an optimised (minified) bundle of Tamaro Core or a customer configuration',
+  )
+  .option(
+    '--local-core',
+    'Load Tamaro Core from localhost instead of the CDN',
+    false,
+  )
+  .option('--analyze', 'Generate bundle statistics to "reports" folder', false)
+  .option(
+    '--deploy',
+    'Deploy Tamaro Core or a customer configuration bundle to AWS S3',
+    false,
+  )
+  .option('--serve', 'Run the generated bundle with a local web server', false)
+  .option(
+    '--tag <tag>',
+    'Tag which should be used for the deployment of the bundle',
+    DEFAULT_TAG,
+  )
+  .option(
+    '--profile <profile>',
+    'AWS profile which should be used for the deployment of the bundle',
+    DEFAULT_AWS_PROFILE,
+  )
+  .action(async (options: BuildOptions & DeployOptions) => {
     await build(options)
 
     if (options.deploy) {
@@ -58,21 +90,72 @@ cli
 
 cli
   .command('deploy')
-  .description('Deploy Tamaro Core or customer configuration to AWS')
-  .option('--latest', 'Deploy with tag "latest"')
-  .option('--tag <tag>', 'Deploy with a specific tag')
+  .description(
+    'Deploy a pre-built Tamaro Core or customer configuration bundle to AWS S3',
+  )
+  .option(
+    '--tag <tag>',
+    'Tag which should be used for the deployment of the bundle',
+    DEFAULT_TAG,
+  )
+  .option(
+    '--profile <profile>',
+    'AWS profile which should be used for the deployment of the bundle',
+    DEFAULT_AWS_PROFILE,
+  )
   .action(async (options: DeployOptions) => {
     await deploy(options)
   })
 
 cli
   .command('serve')
-  .description('Run web-server for previously created build')
+  .description('Run a local web server for pre-built bundle')
   .action(async () => {
     await serve()
   })
 
+cli
+  .command('list-deployed')
+  .description(
+    'List deployments of Tamaro Core or a particular customer configuration',
+  )
+  .option(
+    '--config <config>',
+    'Configuration name (default: current customer configuration)',
+  )
+  .option(
+    '--profile <profile>',
+    'AWS profile which should be used for fetching deployments',
+    DEFAULT_AWS_PROFILE,
+  )
+  .action(async (options: ListDeployedOptions) => {
+    await listDeployed(options)
+  })
+
+cli
+  .command('deploy-email-config')
+  .description('Deploy a widget’s email configuration to AWS S3')
+  .option(
+    '--bucket <bucket>',
+    'AWS S3 bucket where it should be deployed',
+    DEFAULT_AWS_S3_EMAIL_CONFIG_BUCKET,
+  )
+  .option(
+    '--profile <profile>',
+    'AWS profile which should be used for the deployment of email configuration',
+    DEFAULT_AWS_PROFILE,
+  )
+  .action(async (options: DeployEmailConfigOptions) => {
+    await deployEmailConfig(options)
+  })
+
 ///////////////////////////////////////////////////////////////////////////////
 ;(async () => {
-  await cli.parseAsync(process.argv)
+  try {
+    await cli.parseAsync(process.argv)
+  } catch (error: any) {
+    if (error.signal === 'SIGINT' && error.signalDescription) {
+      logError(`\n${error.signalDescription}`)
+    }
+  }
 })()

package/src/commands/build.ts

@@ -0,0 +1,97 @@
+import resolveBin from 'resolve-bin'
+import {
+  fail,
+  getIfCoreFns,
+  getPaths,
+  getWidgetUuid,
+  logCommand,
+  logDataTable,
+  logTitle,
+  notify,
+  resolveOwn,
+  runCommandSync,
+} from 'lib/helpers'
+import {assertProfileValid} from 'lib/aws'
+import {CORE_CONFIG_NAME, DeployOptions} from 'commands/deploy'
+
+///////////////////////////////////////////////////////////////////////////////
+
+export type BuildOptions = {
+  localCore: boolean
+  analyze: boolean
+  deploy: boolean
+  serve: boolean
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+export const build = async (
+  options: BuildOptions & DeployOptions,
+): Promise<void> => {
+  assertOptionsValid(options)
+
+  const flags = prepareFlags(options)
+  const {ifCore} = getIfCoreFns()
+  const paths = getPaths(ifCore)
+  const configName = ifCore(CORE_CONFIG_NAME, getWidgetUuid())
+  const title = ifCore(
+    'Building optimised (minified) bundle of Tamaro Core …',
+    `Building optimised (minified) bundle of “${configName}” customer configuration …`,
+  )
+
+  const wpBin = resolveBin.sync('webpack')
+  const wpConfig = resolveOwn('dist/webpack.config.js')
+  const cmd = `
+    ${wpBin}
+      --config ${wpConfig}
+      --env min
+      ${flags}
+  `
+
+  logTitle(title)
+  logCommand(cmd)
+  runCommandSync(cmd, {stdio: 'inherit'})
+
+  /////////////////////////////////////////////////////////////////////////////
+
+  logDataTable(
+    {'Path:': paths.appDist},
+    `Bundle for “${configName}” customer configuration is done.`,
+  )
+
+  /////////////////////////////////////////////////////////////////////////////
+
+  notify({
+    title: 'build',
+    message: `Bundle for “${configName}” customer configuration is done.`,
+  })
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+const assertOptionsValid = (options: BuildOptions & DeployOptions) => {
+  const {localCore, deploy, profile} = options
+  const {ifCore} = getIfCoreFns()
+
+  if (ifCore() && localCore) {
+    fail('Flag "--local-core" is redundant if running in Tamaro Core context.')
+  }
+
+  if (localCore && deploy) {
+    fail('Flags "--local-core" and "--deploy" must not be used together.')
+  }
+
+  assertProfileValid(profile)
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+const prepareFlags = (options: BuildOptions): string => {
+  const {localCore, analyze} = options
+  let flags: string[] = []
+
+  flags = localCore ? [...flags, '--env localCore'] : flags
+  flags = analyze ? [...flags, '--env analyze'] : flags
+
+  return flags.join(' ')
+}

package/src/commands/deploy-email-config.ts

@@ -0,0 +1,107 @@
+import {existsSync} from 'fs'
+import {
+  fail,
+  getIfCoreFns,
+  getPaths,
+  getWidgetUuid,
+  logCommand,
+  logDataTable,
+  logTitle,
+  notify,
+} from 'lib/helpers'
+import {assertProfileValid, AwsOptions, runAwsCommandSync} from 'lib/aws'
+
+///////////////////////////////////////////////////////////////////////////////
+
+export type DeployEmailConfigOptions = AwsOptions & {
+  bucket: string
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+export const DEFAULT_AWS_S3_EMAIL_CONFIG_BUCKET = 'rnw-email-service'
+
+///////////////////////////////////////////////////////////////////////////////
+
+export const deployEmailConfig = async (
+  options: DeployEmailConfigOptions,
+): Promise<void> => {
+  const {ifCore} = getIfCoreFns()
+  const paths = getPaths(ifCore)
+  const emailConfigPath = `${paths.app}/email-config`
+
+  assertOptionsValid(options)
+  assertEmailConfigPathExists(emailConfigPath)
+  assertIsNotCore()
+
+  const {bucket} = options
+  const configName = getWidgetUuid()
+  const deployUrl = `s3://${bucket}/${configName}`
+
+  const cmd = `
+    aws s3 sync ${emailConfigPath} ${deployUrl}
+      --delete
+      --exact-timestamps
+  `
+  logTitle(
+    `Deploying email configuration for “${configName}” customer configuration to AWS S3 …`,
+  )
+  logCommand(cmd)
+
+  try {
+    runAwsCommandSync(cmd, {stdout: 'inherit'})
+  } catch (error: any) {
+    fail(error.stderr)
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+
+  logDataTable(
+    {'Deploy URL:': deployUrl},
+    `Email configuration for “${configName}” customer configuration is deployed.`,
+  )
+
+  /////////////////////////////////////////////////////////////////////////////
+
+  notify({
+    title: `deploy-email-config`,
+    message: `Email configuration for “${configName}” customer configuration is deployed.`,
+  })
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+const assertOptionsValid = (options: DeployEmailConfigOptions) => {
+  const {bucket, profile} = options
+
+  assertBucketValid(bucket)
+  assertProfileValid(profile)
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+const assertEmailConfigPathExists = (distPath: string) => {
+  if (!existsSync(distPath)) {
+    fail('Email config folder does not exists. Nothing to deploy.')
+  }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+const assertBucketValid = (tag: string) => {
+  const regex = /^[a-zA-Z0-9-_]+$/
+
+  if (!regex.test(tag)) {
+    fail(`Flag "--bucket" has forbidden format. Allowed format: ${regex}.`)
+  }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+
+const assertIsNotCore = () => {
+  const {ifCore} = getIfCoreFns()
+
+  if (ifCore()) {
+    fail('You cannot deploy widget email configuration for Tamaro Core.')
+  }
+}