@adinsure-ops/ops-cli 4.0.0-rc10

package/README.md

@@ -0,0 +1,725 @@
+# Operations CLI
+
+Operations CLI for supporting AdInsure development processes.
+
+# Latest version
+
+4.0.0
+
+## Install
+
+OPS CLI can be downloaded and installed using installer.
+For versions check [tags](https://git.adacta-fintech.com/ops/ops-cli/-/tags)
+or [download a JSON](https://adinsure.blob.core.windows.net/ops-cli/version) containing version and other information.
+
+| Platform| Link|
+|:---|:---|
+|Windows 64-bit|https://adinsure.blob.core.windows.net/ops-cli/win/ops-v4.0.0-x64.exe|
+|Debian 64-bit |https://adinsure.blob.core.windows.net/ops-cli/deb/ops_4.0.0-1_amd64.deb|
+
+
+
+## CLI development
+
+For development you will need **[Node.js](https://nodejs.org/en/)** (recommended 16 LTS, minimal 8.0.0) and **[Yarn](https://yarnpkg.com/en/)** installed. 
+
+We recommend **[Visual Studio Code](https://code.visualstudio.com/)** IDE.
+
+To quick start development:
+
+- Clone this repository (`git clone https://git.adacta-fintech.com/ops/ops-cli.git`)
+- Open in VS Code
+- Run `yarn install`
+- For easier debugging, run `yarn link`
+
+You can run and debug commands directly from terminal by running `ops [command]` (if you `yarn link`-ed the package) or execute `.\bin\run [command]` (if you didn't).
+
+## Commands
+
+<!-- commands -->
+* [`ops help [COMMAND]`](#ops-help-command)
+* [`ops doctor`](#ops-doctor)
+* [`ops download:client <flags>`](#ops-download-client-flags)
+* [`ops download:identity-server <flags>`](#ops-download-identity-server-flags)
+* [`ops download:platform <flags>`](#ops-download-platform-flags)
+* [`ops download:scheduler <flags>`](#ops-download-scheduler-flags)
+* [`ops download:server <flags>`](#ops-download-server-flags)
+* [`ops download:studio <flags>`](#ops-download-studio-flags)
+* [`ops gitlab:next-nightly-tag`](#ops-gitlab-next-nightly-tag)
+* [`ops log <component> <issue> [options]`](#ops-log-component-issue-options)
+* [`ops log:gen [options]`](#ops-loggen-options)
+* [`ops log:validate [options]`](#ops-logvalidate-options)
+* [`ops login`](#ops-login)
+* [`ops npm:check-publish`](#ops-npm-check-publish)
+* [`ops npm:publish`](#ops-npm-publish)
+* [`ops prepare-content`](#ops-prepare-content)
+* [`ops sql <type> <module> [flags]`](#ops-sql-type-module-flags)
+* [`ops translate`](#ops-translate)
+* [`ops update`](#ops-update)
+* [`ops version <type> [flags]`](#ops-version)
+
+## `ops help [COMMAND]`
+
+display help for ops
+
+```
+USAGE
+  $ ops help [COMMAND]
+
+ARGUMENTS
+  COMMAND  command to show help for
+
+OPTIONS
+  --all  see all commands in CLI
+```
+
+_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v2.2.0/src\commands\help.ts)_
+
+
+## `ops doctor`
+
+check if everyting is installed
+
+```
+USAGE
+  $ ops doctor
+
+OPTIONS
+  -p, --fix  try to install missing packages
+
+EXAMPLE
+  $ ops doctor
+```
+
+## `ops download:client <flags>`
+
+download AdInsure Client zip from Azure storage
+
+```
+USAGE
+  $ ops download:client <flags>
+
+OPTIONS
+  -o, --output=output    [default: ./] output directory
+  -v, --version=version  (required) version we want to download
+
+EXAMPLE
+  $ ops download:client -v 3.2.0 -o ~/Downloads
+```
+
+## `ops download:identity-server <flags>`
+
+download AdInsure Identity Server zip from Azure storage
+
+```
+USAGE
+  $ ops download:identity-server <flags>
+
+OPTIONS
+  -o, --output=output    [default: ./] output directory
+  -v, --version=version  (required) version we want to download
+
+EXAMPLE
+  $ ops download:identity-server -v 3.0.3 -o ~/Downloads
+```
+
+## `ops download:platform <flags>`
+
+download AdInsure Platform bundle containing zip of Client, Server and IdentityServer from azure storage
+
+```
+USAGE
+  $ ops download <flags>
+
+OPTIONS
+  -o, --output=output    [default: ./] output directory
+  -v, --version=version  (required) version we want to download
+
+ALIASES
+  $ ops download
+
+EXAMPLE
+  $ ops download -v 6.0.0 -o ~/Downloads
+```
+
+## `ops download:scheduler <flags>`
+
+download AdInsure Scheduler zip from azure storage
+
+```
+USAGE
+  $ ops download:scheduler <flags>
+
+OPTIONS
+  -o, --output=output    [default: ./] output directory
+  -v, --version=version  (required) version we want to download
+
+EXAMPLE
+  $ ops download:scheduler -v 3.2.0 -o ~/Downloads
+```
+
+## `ops download:server <flags>`
+
+download AdInsure Server zip from Azure storage
+
+```
+USAGE
+  $ ops download:server <flags>
+
+OPTIONS
+  -o, --output=output    [default: ./] output directory
+  -v, --version=version  (required) version we want to download
+
+EXAMPLE
+  $ ops download:server -v 3.2.0 -o ~/Downloads
+```
+
+## `ops download:studio <flags>`
+
+download AdInsure Studio vsix from azure storage
+
+```
+USAGE
+  $ ops download:studio <flags>
+
+OPTIONS
+  -i, --install          install plugin to vscode. save to temp folder and remove vsix after.
+  -o, --output=output    [default: ./] output directory
+  -v, --version=version  (required) version we want to download
+
+EXAMPLES
+  $ ops download:studio -v 15.0.0 -o ~/Downloads
+  $ ops download:studio -v 15.0.0 -i
+```
+
+## `ops download:studio <flags>`
+
+download AdInsure Studio vsix from azure storage
+
+```
+USAGE
+  $ ops download:studio <flags>
+
+OPTIONS
+  -i, --install          install plugin to vscode. save to temp folder and remove vsix after.
+  -o, --output=output    [default: ./] output directory
+  -v, --version=version  (required) version we want to download
+
+EXAMPLES
+  $ ops download:studio -v 15.0.0 -o ~/Downloads
+  $ ops download:studio -v 15.0.0 -i
+```
+
+## `ops gitlab:next-nightly-tag`
+
+creates new gitlab tag
+
+```
+USAGE
+  $ ops gitlab:next-nightly-tag <version>
+
+ARGUMENTS
+  VERSION  Tag version
+
+OPTIONS
+  --dryRun               Only printout version and don't create it
+  --host=host            (required) [default: https://git.adacta-fintech.com] Server hostname
+  --pat=pat              (required) Token from user that has permissions to list and create tags
+  --project=project      (required) [default: 413] Project ID
+  --reference=reference  (required) Reference to create tag on (branch, commit, tag)
+```
+
+## `ops jira:issue <issue>`
+
+get Jira issue
+
+```
+USAGE
+  $ ops jira:issue <issue>
+
+ARGUMENTS
+  ISSUE  Jira issue number
+
+OPTIONS
+  --hostname=hostname  [default: https://jira.adacta-fintech.com] jira hostname
+  --password=password  (required) jira password
+  --username=username  (required) jira username
+
+EXAMPLE
+  $ ops jira:issue LJADIRD-1337
+```
+
+## `ops jira:issue <issue> -a [label] -r [label]`
+
+list or edit labels on Jira issue
+
+```
+USAGE
+  $ ops jira:labels <issue> -a [label] -r [label]
+
+ARGUMENTS
+  ISSUE  Jira issue number
+
+OPTIONS
+  -a, --add=add        add label
+  -r, --remove=remove  remove label
+  --hostname=hostname  [default: https://jira.adacta-fintech.com] jira hostname
+  --password=password  (required) jira password
+  --username=username  (required) jira username
+
+EXAMPLE
+  $ ops jira:labels LJADIRD-1337
+```
+
+## `ops log <issue> -t <type> -c [component]`
+
+creates a new changelog entry
+
+```
+USAGE
+  $ ops log <issue> -t <type> -c [component]
+
+ARGUMENTS
+  ISSUE      Jira issue number
+  TYPE       (feature|fixed|improve|breaking) Change type
+  COMPONENT  (Configuration|DevOps|Implementation|Platform) Component for which new changelog should be generated
+
+
+OPTIONS
+  -c, --component=component                  Component for which new changelog should be generated
+  -t, --type=feature|fixed|improve|breaking  (required) type of changelog
+
+ALIASES
+  $ ops log
+  $ ops log:add
+
+EXAMPLES
+  $ ops log LJADIRD-1234 -t feature
+  $ ops log LJADIRD-5678 -t fixed
+  $ ops log LJADIRD-8765 -t breaking -c Platform
+  $ ops log LJADIRD-4321 -t improve -c Configuration
+```
+
+## `ops log:gen [options]`
+
+generates final changelog from unreleased notes on the root,
+final changelog for implementation component is placed under basic/Changelog.md
+
+```
+USAGE
+  $ ops log:gen [options]
+
+OPTIONS
+  -c, --components=components  components separated by comma (,) to process for final changelog
+  -f, --file=file        [default: CHANGELOG.md] file to update with new changelogs
+  -p, --preview          generates a preview markdown of current unreleased changelogs
+  -v, --version=version  version for which you're generating changelogs
+  --force                update target file without prompting for confirmation
+  --ignore-no-changelogs generate final changelog even if no unreleased changelogs exist
+
+ALIASES
+  $ ops log:gen
+
+EXAMPLE
+  $ ops log:gen
+  $ ops log:gen -p
+  $ ops log:gen -c Platform
+  $ ops log:gen -c Platform,Configuration
+  $ ops log:gen -c Implementation -f CHANGELOG.Implementation.md
+```
+
+## `ops log:validate [options]`
+
+validates formatting of all unreleased changelogs:
+
+- 2.4.2 - added an exit statement that will force exit on changelog validation errors, preparing it for CI
+
+```
+USAGE
+  $ ops log:validate [options]
+
+ALIASES
+  $ ops log:validate
+
+EXAMPLE
+  $ ops log:validate
+```
+
+## `ops login`
+
+log in to use ops services
+
+```
+USAGE
+  $ ops login
+
+OPTIONS
+      --servicePrincipal    authenticate using service principal credentials
+  -c, --clientId            (application) client id
+  -s, --secret              client secret
+
+EXAMPLES
+  $ ops login
+  $ ops login --servicePrincipal -c {client id} -s {secret}
+```
+
+## `ops npm:check-publish`
+
+check if npm packages were published
+
+```
+USAGE
+  $ ops npm:check-publish [options]
+
+OPTIONS
+  -p, --package=package  package name filter you want to check
+  -v, --version=version  (required) version we want to check if published
+  -x, --exclude=exclude  exclude packages from filter
+  --pat=pat              PAT token or AZURE_DEVOPS_EXT_PAT environment variable
+
+EXAMPLES
+  $ ops npm:check-publish -v 6.0.1
+  $ ops npm:check-publish -p @adinsure/* -v 6.0.0
+  $ ops npm:check-publish -p @adinsure/* -x @adisure/demo -v 6.0.0
+```
+
+## `ops npm:publish`
+
+publish npm packages
+
+```
+USAGE
+  $ ops npm:publish [options]
+
+OPTIONS
+  -p, --package=package  package name filter you want to check
+  -v, --version=version  (required) version we want to check if published
+  -x, --exclude=exclude  exclude packages from filter
+  --pat=pat              PAT token or AZURE_DEVOPS_EXT_PAT environment variable
+
+EXAMPLES
+  $ ops npm:publish -v 15.0.0
+  $ ops npm:publish -v 15.0.0
+  $ ops npm:publish -p @adinsure-tooling/* -v 15.0.0
+  $ ops npm:publish -p @adinsure-tooling/* -x @adisure-tooling/studio-services -v 6.0.0
+```
+
+## `ops prepare-content -d <destination> -s [source]`
+
+creates a directory/file structure from `/source` to `/destination</source>` as defined in the `.opsprepare` file. Actual
+destination path for each file will be specified destination path with appended relative path from working directory where command is executed to specified source directory or current directory (if source is not specified). Be careful about using
+`..` notation in target and source paths as it may lead to unpredictable results due to relative path resolving.
+
+> Introduced in version 3.1.0.
+
+```
+USAGE
+  $ ops prepare-content -d <destination> -s [source]
+
+
+OPTIONS
+  -d, --destination=destination       path to target directory
+  -s, --source=source                 optional path to source directory containing .opsprepare file, (default: current directory)
+
+EXAMPLES
+$ ops prepare-content -d ./target_directory/
+  copies everything defined in .opsprepare
+  from current directory 
+  to ./target_directory
+
+$ ops prepare-content -d ./target_directory/ -s ./source_directory
+  copies everything defined in ./source_directory/.opsprepare 
+  from ./source_directory/
+  to ./target_directory/source_directory
+
+$ ops prepare-content -d C:\git\target_directory
+  copies everything defined in .opsprepare 
+  from current directory 
+  to C:\git\target_directory
+
+$ ops prepare-content -d C:\git\target_directory -s C:\git\subfolder\subfolder
+  when executed in c:\git it copies everything defined in C:\git\subfolder\subfolder\.opsprepare 
+  from C:\git\subfolder\subfolder
+  to C:\git\target_directory\subfolder\subfolder
+```
+
+### .opsprepare dotfile
+
+The prepare-content command uses `.opsprepare` dotfile as instruction set for content preparation.
+The syntax resembles that of `.gitignore` but differs in how it functions and doesn't support advanced
+pattern matching.
+
+Following operations/transformations are currently supported:
+
+- Copy: copies the file/directory from source path to destination path with same name
+- Transform: transform source file to destination file with same name
+- Removal: remove file/directory (based on source path) from destination path
+
+Before diving into the actual syntax and supported tokens let's look at an example
+of how using `ops prepare-content` creates a target directory structure with files
+based on the specified `.opsprepare` file residing in source directory.
+
+This is the example source directory structure:
+
+```
+src_data
+├── .opsprepare
+├── README.tpl
+├── bin
+│   ├── ops.sh
+│   └── run
+│       └── ops
+├── dist
+│   └── server
+│       └── main.cs
+├── src
+│   ├── commands
+│   │   ├── prepare.ts
+│   │   └── version.ts
+│   ├── config.ts
+│   └── main.ts
+└── transform
+    └── render-tpl.js
+```
+
+Contents of `.opsprepare` file in the `src_data` directory:
+
+```
+# Comment
+src
+dist/server
+!src/commands
+!src/config.ts
+src/config.ts {cp:/src/configuration.ts}
+# Another comment
+!bin/run
+README.md {js:/transform/render-tpl.js:render}
+README.tpl {cp:/README.tpl.src}
+```
+
+Running `ops -s src_data -d dst_data` with `src_data/.opsprepare` containing above content
+results in:
+
+```sh
+dst_data
+└── src_data
+    ├── README.md
+    ├── README.tpl.src
+    ├── dist
+    │   └── server
+    │       └── main.cs
+    └── src
+        ├── main.ts
+        └── src
+            └── configuration.ts
+```
+
+What actually happened:
+
+1. First note that all data was copied into `dst_data/src_data` because `.opsprepare` files relative
+   location to `ops` execution directiory is `src_data`.
+2. `src` directory was copied recursively to destination
+3. `dist/server` directory was copied recursively including its full path path relative to `src_data`
+4. `src/config.ts` file was transformed (copied) to `src/configuration.ts` in the destination
+5. `README.md` file was created at the destination as a result of JavaScript based transformation
+6. `README.tpl` file was transformed (copied) to `README.tpl.src` in the destination
+7. `src/commands` directory was removed from destination
+8. `src/config.ts` file was removed from destination
+9. `bin/run` directory was removed from destination
+
+Note that copying and explicit transformations are performed before any removal operations.
+
+#### Comments
+
+Any line prefixed by `#` is considered a comment and will not result in any file/directory operation.
+#### Copy operations
+
+Any file/directory not prefixed by `!` or `#` having explicit transformation defined in `{...}` after
+its name will be copied to the destination with it's full path relative to `ops` execution directory
+to the target directory.
+
+#### Transformation operations
+
+Transformation operations are always specified using curly braces following the source file name. Base
+syntax looks like this:
+
+```
+{<transformation type>:<transformation parameters>}
+```
+
+Two types of transformation operations are supported:
+
+- cp: copy transformation which supports renaming of the source file at the destination
+- js: JavasSript based transformation which results in the file containing string returned by the
+  transformation function contained in transformation module.
+
+**cp - copy transformation syntax**
+
+```
+{cp:<destination path>}
+
+Examples:
+{cp:/dst/newfilename}
+{cp:dst/newfilenames}
+```
+
+Copy transformation is supported for both files and directories. Source file or directory will be
+copied to the destination path with its new name. The destination will always be relative to the
+destination path of entire `prepare-content` operation therefore paths in the transformation block
+can start with or without the `/` character but using makes the syntax more readable.
+
+**js - JavaScript transformation syntax**
+
+```
+{js:<transformation_module_path>:<transformation_function_name>}
+
+Example:
+{js:/transformations/templateRenderer.js:renderEjsTemplate}
+```
+
+JavaScript transformation is supported only for files, not directories.
+
+Transformation module path should be relative to `.opsprepare` file but can start with `/` character
+for better readability. It can export multiple functions though only one can be used in single
+transformation specification.
+
+Transformation function that is defined in the transformation module will be called with a single
+parameter - absolute path of the source file.
+
+Transformation function MUST return a string. This string will become the content of the file on
+destination.
+
+Destination file will be created with the same name as source file and content returned by the
+transformation function. The existence of actual source file will not be validated by the
+`prepare-content` operation (warning is shown if it doesn't exist), such validation is responsibility
+of the transformation function if required.
+
+Example transformation module `transform.js` with exported function called transform:
+
+```js
+module.exports = {
+    render: (path) => {
+        /*
+        Some transformation happens in here and it's result which is
+        a string is assigned to result variable which is returned.
+        */
+        return result;
+    }
+}
+```
+
+#### Removal operations
+
+Any file/directory prefixed by `!` will be removed from the destination based on it's full path
+relative from `ops` execution directory to source file/directory path.
+## `ops version <type>`
+
+creates everything necessary for the new release
+
+```
+USAGE
+  $ ops version <type> [flags]
+
+ARGUMENTS
+  TYPE  (patch|minor|major|prerelease|preminor|premajor|new) Type of release
+
+OPTIONS
+  -i, --independent                      increment npm packages independent of VERSION file
+  -v, --version=version                  force version
+  --no-deps                              skip dependency update
+  --no-script                            skip creation of script
+  --only-npm-packages=only-npm-packages  [default: .*] regular expression for which NPM packages to include
+  --script-prefix=script-prefix          [default: 7.10] prefix for db script version creation.
+  --exclude-dir                          exclude directories where to search for package.json
+
+EXAMPLES
+  $ ops version minor
+  $ ops version new-version -v 3.4.0
+  $ ops version new-version -v 3.2.1 --script-prefix 7.10
+  $ ops version patch --no-deps
+  $ ops version patch --no-script
+  $ ops version new -v 3.2.1 --only-npm-packages "@adinsure/"
+```
+
+* *prerelease* is generated from YearMonth incremental number (example: 201909.1) or RC (example: rc.0). prereleases generated in same month will have only last number incremented and first prerelease generated in next month will bump first number and start with 0 (example: 201910.0)
+
+* *patch* increments third number and prerelease number is ommited. (example: 3.4.0-201909.2 -> 3.4.0 and 3.3.11 -> 3.3.12)
+
+* *preminor* increments for prerelease in second number (example: 3.2.3 -> 3.3.0-201910.0)
+
+* *minor* increments second number (example: 3.4.3 -> 3.5.0)
+
+* *premajor* increments to prerelease in first number (example: 3.4.3 -> 4.0.0-201911.0)
+
+* *major* increments first number (example: 3.4.5 -> 4.0.0)
+
+* *new-version* allows setting own version regardles of VERSION file. **Incrementing NPM version separately is not supported in this case. NPM packages are also bumped to specified version.**
+
+> Prerelease Note: Prerelease should only be user in **master** branch.
+
+> Patch Note: Patch is used on **release/x.x** branches for creating patch releases
+
+> When creating new **release/x.x** branch 2 steps are needed:
+> * creating *patch* version on **release/x.x** branch
+> * creating *preminor* or *premajor* version on **master** branch
+
+> Dependencies for packages are updated on all package.json files. If prerelease version in specified full version is specified (example: 4.0.0-201911.0), or if non prerelease version ends with x (example: 3.5.x)
+
+> NPM packages node: For npm package to update properly *wsrun-version* preset needs to be in *scripts* portion of *package.json*. (example: `"wsrun-version": "yarn wsrun -p @adinsure-tools/* -p @adinsure/* -c"`)
+
+## `ops sql <type> <module> [flags]`
+
+creates a new database script
+
+```
+USAGE
+  $ ops sql <type> <module> [flags]
+
+ARGUMENTS
+  TYPE    (schema|data|migration) Type of database scripts
+  MODULE  (acc|claims|core|pas|reins|shared) Module of data database scripts
+
+OPTIONS
+  -l, --layer=layer      name of the configuration layer for which you are generating database script
+  -v, --version=version  version for which you're generating database script
+
+EXAMPLES
+$ ops sql schema
+$ ops sql data shared --layer basic
+```
+
+## `ops translate`
+
+downloads translate from AdDictionary service
+
+```
+USAGE
+  $ ops translate <language> [flags]
+
+ARGUMENTS
+  LANGUAGE  language id you want to download. Values must be semi-colon (;) separated.
+
+OPTIONS
+  -f, --format=json|xml    (required) translations format [xml - server translations, json - client translations]
+  -m, --module=module      module name you want to download. Values must be semi-colon (;) separated.
+  -o, --output=output      [default: .] absolute or relative destination path to a folder where translations are extracted.
+  --filename=filename      specify filename of output (XML only).
+  --respectServerFilename  respect filename that is returned from AdDictionary server (XML only).
+
+EXAMPLES
+  $ ops translate "en-US=en-US;ru-Ru=ru-RU" -f json -m "Client business accounting;Client business base;"
+  $ ops translate "en-US=en-US;ru-Ru=ru-RU" -f xml -o translationDestination
+```
+
+## `ops update`
+
+update the ops CLI
+
+```
+USAGE
+  $ ops update [CHANNEL]
+
+OPTIONS
+  --from-local  interactively choose an already installed version
+```
+