@dotcms/dotcli 1.0.0-rc2 → 1.0.0-rc4

package/README.md

@@ -1,7 +1,19 @@
 # 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.
+The **dotCMS CLI**, sometimes shortened to **dotCLI**, is a standalone tool for interacting with a dotCMS instance through a command shell, allowing a wide array of automated operations and behaviors.
+
+## Getting Started
+
+### Installation
+
+### NPM
+
+The simplest and most recommended way to get the dotCMS CLI is from its npm package:
+
+```shell script
+npm install -g @dotcms/dotcli
+```
+### Manual JAR Download
 
-## 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: 
 
@@ -9,7 +21,7 @@ The dotCMS CLI is a command-line tool that you can use to populate and modify yo
 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)
+2. Configure the dotCMS instances you want to connect to using the `config` command. More details on how to do it on the [Configuration](#Configuration) section. 
 
 3. Log in to the selected instance
 ```shell script
@@ -22,6 +34,7 @@ java -jar dotcli.jar login --user={USER} --password
 
 | Command                                    | Description                                                                         |
 |--------------------------------------------|-------------------------------------------------------------------------------------|
+| [config](cli/docs/config.adoc)             | Sets the initial configuration required by all commands to operate                  |
 | [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                                         |
@@ -39,7 +52,21 @@ You can find more details about how to use the dotCMS CLI in the [Examples](#exa
 
 ## Examples
 
-1. Log in with an admin user
+1. Run Configuration command to set the initial configuration required by all commands to operate
+```shell script
+config 
+Enter the key/name that will serve to identify the dotCMS instance (must be unique) [local].
+The name is [local]
+Enter the dotCMS base URL (must be a valid URL starting protocol http or https) [http://localhost:8080]
+The URL is [http://localhost:8080]
+Are these values OK? (Enter to confirm or N to cancel)  (Y/n)
+...
+Do you want to continue adding another dotCMS instance?  (Y/n)n
+ 0. Profile [local], Uri [http://localhost:8080], active [no].
+ 1. Profile [local#1], Uri [https://demo.dotcms.com], active [no].
+One of these profiles needs to be made the current active one. Please select the number of the profile you want to activate. 1
+```
+2. Log in with an admin user
 ```shell script
 login --user=admin@dotCMS.com --password
 ```
@@ -181,39 +208,35 @@ Example:
 ../mvnw quarkus:dev -Dquarkus.log.file.path=/Users/my-user/CLI/dotcms-cli.log
 ```
 
-## CLI Instance Configuration
+## 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.
+Whatever profile is active will be used by the CLI to execute the commands on
 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"
+  url: "http://localhost:8080"
   credentials:
     user: "admin@dotcms.com"
 - name: "demo"
+  url: "https://demo.dotcms.com"
   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` as it is shown on the example above.
+The `active` attribute indicates which profile is currently active. The CLI will use the active profile to execute the commands. 
+If more than one profile is marked active, this will result in an InvalidStateException.
+The `credentials` section is optional. If the credentials are not provided, the CLI will prompt the user to enter them when the `login` command is executed.
 
-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.
+If the `dot-service.yml` file does not exist, the CLI will prompt to create one No commands can operate without having a valid configuration in place.
 
-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) 
+The CLI provides a `config` command to set the initial configuration required by all commands to operate. The command will guide you through the process of adding a new instance profile to the `dot-service.yml` file. and setting the active profile.
+See the [Configuration](cli/docs/config.adoc) section for more details. And the [Examples](#examples) section for a practical example.
 
-In future versions this process will be facilitated by the CLI itself.
 
 ### Workspace
 
@@ -222,6 +245,7 @@ The workspace is basically a set of directories and files used to house and orga
 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 |
@@ -241,7 +265,7 @@ In order to incorporate the CLI into your GitHub Actions workflow, you need to:
 - 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`
+  - Create a new variable called `DOT_API_URL` and set the value to a valid dotCMS URL. e.g. `https://demo.dotcms.com`
   ![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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/dotcli",
-  "version": "1.0.0-rc2",
+  "version": "1.0.0-rc4",
   "scripts": {
     "postinstall": "node src/postinstall.js install",
     "postuninstall": "node src/postinstall.js uninstall && npm prune"

package/src/postinstall.js

@@ -1,9 +1,11 @@
 "use strict";
 
+// Dependencies
 const path = require('path');
 const fs = require('fs').promises;
 const os = require('os');
 
+// Architecture and platform mappings
 const ARCHITECTURE_MAPPING = {
     "x64": "x86_64",
     "arm64": "aarch_64"
@@ -14,26 +16,35 @@ const PLATFORM_MAPPING = {
     "linux": "linux"
 };
 
+const EXTENSION_MAP = {
+    "win32": ".exe",
+    "default": ""
+};
+
+// Utility functions
 function getGlobalBinPath() {
     const npmGlobalPrefix = process.env.PREFIX || process.env.npm_config_prefix || process.env.HOME;
     return path.join(npmGlobalPrefix, 'bin');
 }
 
 function validatePackageConfig(packageJson) {
+    // Validation of package.json configuration
     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.");
     }
 }
 
+// Read and parse package.json
 async function parsePackageJson() {
-
     console.log("Installing CLI");
+
     const platform = os.platform();
     const architecture = os.arch();
 
     console.log("Platform: " + platform);
     console.log("Architecture: " + architecture);
 
+    // Check installation support for platform and architecture
     if (!(os.arch() in ARCHITECTURE_MAPPING) || !(os.platform() in PLATFORM_MAPPING)) {
         throw new Error(`Installation is not supported for this ${platform}/${architecture} combination.`);
     }
@@ -48,7 +59,7 @@ async function parsePackageJson() {
         const packageName = packageJson.packageName;
         const alias = packageJson.alias;
         const binaries = packageJson.binaries;
-        const extension = platform === "win32" ? ".exe" : "";
+        const extension = EXTENSION_MAP[platform] || EXTENSION_MAP.default;
         const binaryKey = `${packageName}-${platform}-${architecture}`;
         const binaryPath = binaries[binaryKey];
 
@@ -69,76 +80,86 @@ async function parsePackageJson() {
     }
 }
 
+// Create symlink for the binary
+async function createSymlink(globalBinPath, config) {
+    try {
+        console.info(`Creating symlink for the relevant binary for your platform ${os.platform()}-${os.arch()}`);
 
-async function createSymlink(binarySource, binaryDestination) {
-    const globalBinPath = getGlobalBinPath();
-    const symlinkPath = path.join(globalBinPath, binaryDestination);
+        const currentDir = __dirname;
+        const targetDir = path.join(currentDir, '..');
+        const binarySource = path.join(targetDir, config.binaryPath);
+        const binaryDestination = config.alias;
+        const fullSymlinkPath = 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.
-        }
+        await fs.symlink(binarySource, fullSymlinkPath);
 
-        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}`);
+        console.info(`Created symlink ${fullSymlinkPath} 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();
+// Remove symlink if exists
+async function removeSymlinkIfExists(globalBinPath, config) {
+    try {
+        console.info("Global bin path location:", globalBinPath);
 
-    console.log({
-        config
-    });
+        const files = await fs.readdir(globalBinPath);
+        const symlinkFileName = config.alias + config.extension;
+        const symlinkPath = files.find(file => file === symlinkFileName);
 
-    console.info(`Creating symlink for the relevant binary for your platform ${os.platform()}-${os.arch()}`);
+        if (!symlinkPath) {
+            console.warn(`Symlink '${symlinkFileName}' not found in the global bin directory.`);
+            return;
+        }
 
-    const currentDir = __dirname;
-    const targetDir = path.join(currentDir, '..');
-    const binarySource = path.join(targetDir, config.binaryPath);
-    const binaryDestination = config.alias;
+        const fullSymlinkPath = path.join(globalBinPath, symlinkPath);
+        await fs.unlink(fullSymlinkPath);
+        console.info(`Removed symlink: ${fullSymlinkPath}`);
+    } catch (error) {
+        console.warn("Error while removing symlink:", error);
+    }
+}
 
-    console.info("Installing cli:", binarySource, binaryDestination);
+// Install CLI
+async function installCli() {
+    const config = await parsePackageJson();
+    const globalBinPath = getGlobalBinPath();
 
-    await createSymlink(binarySource, binaryDestination + config.extension);
+    try{
+        await removeSymlinkIfExists(globalBinPath, config);
+        await createSymlink(globalBinPath, config);
+    } catch (ex) {
+        console.error("Error while installing:", ex);
+        throw new Error(`Failed to install ${config.alias}.`);
+    }
+
+    console.info(`${config.alias} installed successfully.`);
 }
 
+// Uninstall CLI
 async function uninstallCli() {
     const config = await parsePackageJson();
+    const globalBinPath = getGlobalBinPath();
 
     try {
-        const globalBinPath = getGlobalBinPath();
-        const symlinkPath = path.join(globalBinPath, config.alias + config.extension);
-
-        console.info("Removing symlink:", symlinkPath);
-
-        await fs.unlink(symlinkPath);
+        await removeSymlinkIfExists(globalBinPath, config);
     } catch (ex) {
         console.error("Error while uninstalling:", ex);
+        throw new Error(`Failed to uninstall ${config.alias}.`);
     }
 
-    console.info("Uninstalled cli successfully");
+    console.info(`${config.alias} uninstalled successfully.`);
 }
 
+// Available actions
 const actions = {
     "install": installCli,
     "uninstall": uninstallCli
 };
 
+// Execute action based on provided command
 const [cmd] = process.argv.slice(2);
 if (cmd && actions[cmd]) {
     actions[cmd]().then(
@@ -151,4 +172,4 @@ if (cmd && actions[cmd]) {
 } else {
     console.log("Invalid command. `install` and `uninstall` are the only supported commands");
     process.exit(1);
-}
+}