@dotcms/dotcli 24.1.26

package/README.md

@@ -0,0 +1,278 @@
+# dotCMS CLI 
+The dotCMS CLI is a command-line tool that you can use to populate and modify your dotCMS instances from a command shell.
+
+## Quick start
+1. Download the CLI: The dotCMS CLI is delivered as an uber jar that can be downloaded from [here](https://repo.dotcms.com/artifactory/libs-snapshot-local/com/dotcms/dotcms-cli/).
+ Once downloaded, you just need to run it with: 
+
+```shell script
+java -jar dotcli.jar
+```
+
+2. Configure the dotCMS instances you want to connect to using a dot-service.yml file. More details on how to do it [on this section](## CLI Instance Configuration). Make sure you make a site active in the yml file, otherwise you will have to active one using the [`instance` command](## Available Commands)
+
+3. Log in to the selected instance
+```shell script
+java -jar dotcli.jar login --user={USER} --password  
+```
+
+
+
+## Available Commands
+
+| Command                                    | Description                                                                         |
+|--------------------------------------------|-------------------------------------------------------------------------------------|
+| [content-type](cli/docs/content-type.adoc) | Performs operations over content types. For example: pull, push, remove             |
+| [files](cli/docs/files.adoc)               | Performs operations over files. For example: tree, ls, push                         |
+| [instance](cli/docs/instance.adoc)         | Prints a list of available dotCMS instances                                         |
+| [language](cli/docs/language.adoc)         | Performs operations over languages. For example: pull, push, remove                 |
+| [login](cli/docs/login.adoc)               | Logs into a dotCMS instance                                                         |
+| [push](cli/docs/push.adoc)                 | Global push command used to sync a GitHub repo with a target dotCMS environment     |
+| [pull](cli/docs/pull.adoc)                 | Global pull command used to sync a target dotCMS environment with a local workspace |
+| [site](cli/docs/site.adoc)                 | Performs operations over sites. For example: pull, push, remove                     |
+| [status](cli/docs/status.adoc)             | Provides information about the current logged-in user and dotCMS instance status    |
+
+
+You can find more details about how to use the dotCMS CLI in the [Examples](#examples) section.
+
+
+
+## Examples
+
+1. Log in with an admin user
+```shell script
+login --user=admin@dotCMS.com --password
+```
+2. List and choose the dotCMS instance we want to run against
+```shell script
+instance --list
+```
+3. Activate a dotCMS instance profile called `demo`
+```shell script
+instance --activate demo
+```
+4. Get info of the current instance running
+```shell
+
+status
+	
+#You will get an output similar to:
+2023-02-22 11:25:29,499 INFO  [com.dot.api.cli.HybridServiceManagerImpl] (Quarkus Main Thread) Service [default] is missing credentials.
+2023-02-22 11:25:29,500 INFO  [com.dot.api.cli.HybridServiceManagerImpl] (Quarkus Main Thread) Service [demo] is missing credentials.
+Active instance is [demo] API is [https://demo.dotcms.com/api] No active user Use login Command.
+```
+
+5. Pull a content type
+```shell script
+content-type pull FileAsset
+```
+6. Create a new site
+```shell script
+site create "my.cool.bikes.site.com"
+```
+
+## Building the CLI (dev mode)
+
+The CLI is a quarkus/pico-cli project made up of two modules [cli](cli) and [api-data-module](api-data-model).
+This project acts as a maven reactor pom build. You can build at the top level to build the modules.
+
+```shell script
+./mvnw clean install -DskipTests=true
+```
+
+We suggest to build the project ignoring test execution (`-DskipTests=true`). It will run faster and avoid setting up a testing environment.
+
+#### Running the CLI (dev mode)
+
+You might use [quarkus cli](https://es.quarkus.io/guides/cli-tooling) or [maven](https://maven.apache.org/install.html)
+First, start a dotCMS instance locally. 
+Then, execute the following commands
+
+```shell script
+# from top level to build all
+cd cli
+# command is same as the following to run the quarkus build plugin
+# ../mvnw quarkus:dev 
+quarkus dev
+```
+**NOTE:**  To reduce duplication in the multi-module project, mvnw is not included on each submodule.
+The quarkus command finds the executable
+
+To run mvnw from a submodule just use a relative path to the parent mvn.
+If running from a submodule folder, all the dependencies will need to be up to date and installed to the local mvn with maven install
+
+Alternatively, you can specify the subproject from the parent folder
+```shell script
+# from top level to build all
+cd cli
+# The command is same as the following to run the quarkus build plugin
+# ../mvnw quarkus:dev 
+../mvnw -pl cli quarkus:dev
+```
+
+Once the cli is launched in dev mode it'll print out a list of available commands.
+
+followed by 
+
+```shell script
+--
+Tests paused
+Press [space] to restart, [e] to edit command line args (currently ''), [r] to resume testing, [o] Toggle test output, [:] for the terminal, [h] for more options>
+```
+
+We can also instruct Quarkus dev mode to launch our cli using a preconfigured param by doing:
+```shell script
+../mvn quarkus:dev -Dquarkus.args=status
+```
+This will launch the cli passing directly into it the arguments that tell them to execute the command status.
+
+## Building a CLI jar 
+In order to generate the cli as a jar packaged with all necessary dependencies you need to run the following command from the `cli` directory:
+```shell script
+../mvnw clean install package
+```
+
+All the commands can be executed directly from the generated jar which can be found under `cli/target/quarkus-app/`.
+
+Example:
+```shell script
+java -jar ./cli/target/quarkus-app/quarkus-run.jar status
+```
+
+## Logging
+
+When running the CLI, a **_dotcms-cli.log_** file will be created in the directory where the CLI
+executable is run.
+
+#### File log level
+
+To increase the file log level to _DEBUG_ when running in dev mode, use the following command:
+
+```shell
+../mvnw quarkus:dev -Dquarkus.log.file.level=DEBUG
+```
+
+#### Console log level
+
+To increase the console log level to _DEBUG_ when running in dev mode, use the following command:
+
+```shell
+../mvnw quarkus:dev -Dquarkus.log.handler.console.\"DOTCMS_CONSOLE\".level=DEBUG
+```
+
+#### File log location
+
+To override the default location of the log file, you have two options:
+
+##### 1. Set the environment variable
+
+Example:
+
+```shell
+export QUARKUS_LOG_FILE_PATH=/Users/my-user/CLI/dotcms-cli.log
+java -jar cli-1.0.0-SNAPSHOT-runner.jar login -u admin@dotcms.com -p
+```
+
+##### 2. Set the system property
+
+Example:
+
+```shell
+../mvnw quarkus:dev -Dquarkus.log.file.path=/Users/my-user/CLI/dotcms-cli.log
+```
+
+## CLI Instance Configuration
+
+The CLI can be used to manage multiple dotCMS instances. Each instance profile is defined in the `~/.dotcms/dot-service.yml` file. 
+Whatever profile is active will be used by the CLI to execute the commands.
+The selected profile can be obtained by running the `status` command.
+Here's an example of the default `dot-service.yml` file shipped with the CLI:
+
+```yaml
+- name: "default"
+  credentials:
+    user: "admin@dotcms.com"
+- name: "demo"
+  active: true
+  credentials:
+    user: "admin@dotCMS.com"
+```
+
+The profiles declared on this file are paired up with properties defined in an internal `application.properties` file.
+
+```properties
+# Your configuration properties
+dotcms.client.servers.default=http://localhost:8080/api
+dotcms.client.servers.demo=https://demo.dotcms.com/api
+```
+
+Notice how the `dotcms.client.servers` property has a suffix matching the profile name in the `dot-service.yml` file.
+
+Therefore, in order to add a new instance profile, you need to add a new entry in the `dot-service.yml` file and a new property extending the `application.properties` file.
+Application properties can be extended via system properties, environment variables, `.env` file or in `$PWD/config/application.properties` file.
+
+To learn more about how to extend the `application.properties` file see the Quarkus configuration guide [Here](https://es.quarkus.io/guides/config-reference#application-properties-file) 
+
+In future versions this process will be facilitated by the CLI itself.
+
+### Workspace
+
+The CLI needs a workspace to be able to pull and push content to a dotCMS instance. 
+The workspace is basically a set of directories and files used to house and organize the different type of assets that can be managed by the CLI.
+Additionally, a marker file called `.dot-workspace.yml` indicates to the CLI that the current directory is a valid workspace.
+In the following table you can see the different directories and files that conform a workspace.
+
+| File/Directory       | Type | Description             |
+|----------------------|------|-------------------------|
+| `content-types/`     | Dir  | Content-Types directory |
+| `files/`             | Dir  | Files directory         |
+| `languages/`         | Dir  | Languages Directory     |
+| `sites/`             | Dir  | Sites Directory         |
+| `.dot-workspace.yml` | File | CLI workspace marker    |
+
+## GitHub Actions Integration
+We provide support for GitHub Actions to be able to run the CLI as part of your CI/CD pipeline. 
+
+The following example shows how to create a brand-new repository and seed it with a CLI workspace.
+In order to incorporate the CLI into your GitHub Actions workflow, you need to:
+
+- Create a GitHub Repository to manage your dotCMS assets.
+- Copy the contents of the [action](./action) directory into your root project `.github/workflows` directory.
+- In Your repository General Settings, enable the following permissions:
+  -  Workflow Permissions : Read and Write permissions 
+- In Your repository General Settings, Secrets and variables, Actions
+  - Create a new variable called `DOT_API_URL` and set the value to a valid dotCMS URL. e.g. `https://demo.dotcms.com/api`
+  ![How to create a variable](doc_images/create_variable.png)
+  - Create a new secret called `DOT_TOKEN` and set the value to a valid dotCMS CLI token. 
+  ![How to create a secret](doc_images/create_secret.png)
+-  Seed your local repository with a CLI workspace
+    * A cli workspace can be created by running any pull command e.g. `java -jar dotcli.jar files pull //demo.dotcms.com`  
+    * Run any pull command from the root of your project see [examples](#examples) section.
+    * A valid CLI workspace should contain a `.dot-workspace` file in the root of your project. Make sure to commit this file to your repository and the others that conform your workspace see the [workspace](#workspace) section. 
+    * Commit and push the changes to your repository. 
+
+- Now if the integration is successful, you should see a new commits made into your repository reflect in you dotCMS instance.
+
+Here's an example of how a Git repository could look like after the GitHub Action has been integrated:
+
+| File/Directory       | Type | Description               |
+|----------------------|------|---------------------------|
+| `.github/workflows/` | Dir  | GitHub Actions workflow   |
+| `content-types/`     | Dir  | Content-Types directory   |
+| `files/`             | Dir  | Files directory           |
+| `languages/`         | Dir  | Languages Directory       |
+| `sites/`             | Dir  | Sites Directory           |
+| `.dot-workspace.yml` | File | CLI workspace marker      |
+| `.gitignore`         | File | Git files exclude         |
+| `README.md`          | File | Project readme            |
+| `.env`               | File | Push command Options Spec |
+
+- The default command executed by our GitHub Action is the global `push` 
+- Global Push has different options. For more details to control the execution of the command see [Global Push](cli/docs/push.adoc) section for more details.
+- Any additional Options required by the Global push command can be specified in the `.env` file in the following format `DOT_CLI_OPTS="--option1 --option2"`
+So a valid example of a `.env` file could look like this `DOT_CLI_OPTS="--force --dry-run"`
+```shell script
+   DOT_CLI_OPTS=" --removeAssets --removeFolders --removeSites --removeContentTypes --removeLanguages --errors"
+```
+These options can cause data loss, so use them with caution. That's why they are not enabled by default.
+Do not enable them unless you know what you are doing.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@dotcms/dotcli",
+  "version": "24.01.26",
+  "scripts": {
+    "postinstall": "node src/postinstall.js install",
+    "postuninstall": "node src/postinstall.js uninstall && npm prune"
+  },
+  "binaries": {
+    "dotcms-cli-darwin-arm64": "bin/dotcms-cli-24.01.26-osx-aarch_64",
+    "dotcms-cli-darwin-x64": "bin/dotcms-cli-24.01.26-osx-x86_64",
+    "dotcms-cli-linux-x64": "bin/dotcms-cli-24.01.26-linux-x86_64"
+  },
+  "alias": "dotcli",
+  "packageName": "dotcms-cli",
+  "files": [
+    "bin",
+    "src"
+  ],
+  "description": "Official command-line tool to manage dotCMS content.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotCMS/core.git#master"
+  },
+  "keywords": [
+    "dotCMS",
+    "CMS",
+    "Content Management",
+    "CLI",
+    "dotCMS CLI",
+    "dotCMS command-line tool"
+  ],
+  "author": "dotcms <dev@dotcms.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/dotCMS/core/issues"
+  }
+}

package/src/postinstall.js

@@ -0,0 +1,154 @@
+"use strict";
+
+const path = require('path');
+const fs = require('fs').promises;
+const os = require('os');
+
+const ARCHITECTURE_MAPPING = {
+    "x64": "x86_64",
+    "arm64": "aarch_64"
+};
+
+const PLATFORM_MAPPING = {
+    "darwin": "osx",
+    "linux": "linux"
+};
+
+function getGlobalBinPath() {
+    const npmGlobalPrefix = process.env.PREFIX || process.env.npm_config_prefix || process.env.HOME;
+    return path.join(npmGlobalPrefix, 'bin');
+}
+
+function validatePackageConfig(packageJson) {
+    if (!packageJson.version || !packageJson.packageName || !packageJson.alias || !packageJson.binaries || typeof packageJson.binaries !== "object") {
+        throw new Error("Invalid package.json. 'version', 'packageName', 'alias' and 'binaries' must be specified.");
+    }
+}
+
+async function parsePackageJson() {
+
+    console.log("Installing CLI");
+    const platform = os.platform();
+    const architecture = os.arch();
+
+    console.log("Platform: " + platform);
+    console.log("Architecture: " + architecture);
+
+    if (!(os.arch() in ARCHITECTURE_MAPPING) || !(os.platform() in PLATFORM_MAPPING)) {
+        throw new Error(`Installation is not supported for this ${platform}/${architecture} combination.`);
+    }
+
+    const packageJsonPath = path.join(".", "package.json");
+
+    try {
+        const packageJsonContent = await fs.readFile(packageJsonPath, "utf-8");
+        const packageJson = JSON.parse(packageJsonContent.toString());
+        validatePackageConfig(packageJson);
+
+        const packageName = packageJson.packageName;
+        const alias = packageJson.alias;
+        const binaries = packageJson.binaries;
+        const extension = platform === "win32" ? ".exe" : "";
+        const binaryKey = `${packageName}-${platform}-${architecture}`;
+        const binaryPath = binaries[binaryKey];
+
+        if (binaryPath) {
+            console.log(`Binary found for your platform ${platform}-${architecture}: ${binaryPath}`);
+        } else {
+            throw new Error(`No binary found for your platform ${platform}-${architecture}.`);
+        }
+
+        return {
+            alias,
+            binaryKey,
+            binaryPath,
+            extension
+        };
+    } catch (error) {
+        throw new Error("Unable to read or parse package.json. Please run this script at the root of the package you want to be installed.");
+    }
+}
+
+
+async function createSymlink(binarySource, binaryDestination) {
+    const globalBinPath = getGlobalBinPath();
+    const symlinkPath = path.join(globalBinPath, binaryDestination);
+
+    try {
+        try {
+            await fs.access(symlinkPath, fs.constants.F_OK);
+            // If the symlink exists, remove it.
+            await fs.unlink(symlinkPath);
+            console.log(`Existing symlink ${symlinkPath} found and removed.`);
+        } catch (error) {
+            // The symlink does not exist, continue.
+        }
+
+        if (os.platform() === "win32") {
+            // Create a junction for the binary for Windows.
+            // await fs.symlink(binarySource, symlinkPath, "junction");
+        } else {
+            // Create a symlink for the binary for macOS and Linux.
+            await fs.symlink(binarySource, symlinkPath);
+        }
+        console.info(`Created symlink ${symlinkPath} pointing to ${binarySource}`);
+    } catch (error) {
+        console.error("Error while creating symlink:", error);
+        throw new Error("Failed to create symlink.");
+    }
+}
+
+async function installCli() {
+    const config = await parsePackageJson();
+
+    console.log({
+        config
+    });
+
+    console.info(`Creating symlink for the relevant binary for your platform ${os.platform()}-${os.arch()}`);
+
+    const currentDir = __dirname;
+    const targetDir = path.join(currentDir, '..');
+    const binarySource = path.join(targetDir, config.binaryPath);
+    const binaryDestination = config.alias;
+
+    console.info("Installing cli:", binarySource, binaryDestination);
+
+    await createSymlink(binarySource, binaryDestination + config.extension);
+}
+
+async function uninstallCli() {
+    const config = await parsePackageJson();
+
+    try {
+        const globalBinPath = getGlobalBinPath();
+        const symlinkPath = path.join(globalBinPath, config.alias + config.extension);
+
+        console.info("Removing symlink:", symlinkPath);
+
+        await fs.unlink(symlinkPath);
+    } catch (ex) {
+        console.error("Error while uninstalling:", ex);
+    }
+
+    console.info("Uninstalled cli successfully");
+}
+
+const actions = {
+    "install": installCli,
+    "uninstall": uninstallCli
+};
+
+const [cmd] = process.argv.slice(2);
+if (cmd && actions[cmd]) {
+    actions[cmd]().then(
+        () => process.exit(0),
+        (err) => {
+            console.error(err);
+            process.exit(1);
+        }
+    );
+} else {
+    console.log("Invalid command. `install` and `uninstall` are the only supported commands");
+    process.exit(1);
+}