@dotcms/dotcli - npm Package Compare versions

Comparing version 1.0.0-rc2 to 1.0.0-rc3

package.json

 {
   "name": "@dotcms/dotcli",
-  "version": "1.0.0-rc2",
+  "version": "1.0.0-rc3",
   "scripts": {
@@ -5,0 +5,0 @@ "postinstall": "node src/postinstall.js install",

README.md

 # 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.
 
-## Quick start
+## 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
+
 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/).
@@ -12,3 +24,3 @@ Once downloaded, you just need to run it with:
 
-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. 
 
@@ -26,2 +38,3 @@ 3. Log in to the selected instance
 |--------------------------------------------|-------------------------------------------------------------------------------------|
+| [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             |
@@ -44,4 +57,18 @@ | [files](cli/docs/files.adoc)               | Performs operations over files. For example: tree, ls, push                         |
 
-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=[e-mail] --password
@@ -187,6 +214,6 @@ ```
 
-## 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.
@@ -197,5 +224,7 @@ Here's an example of the default `dot-service.yml` file shipped with the CLI:
 - name: "default"
+  url: "http://localhost:8080"
   credentials:
     user: "[e-mail]"
 - name: "demo"
+  url: "https://demo.dotcms.com"
   active: true
@@ -206,19 +235,13 @@ credentials:
 
-The profiles declared on this file are paired up with properties defined in an internal `application.properties` 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.
 
-```properties
-# Your configuration properties
-dotcms.client.servers.default=http://localhost:8080/api
-dotcms.client.servers.demo=https://demo.dotcms.com/api
-```
+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.
 
-Notice how the `dotcms.client.servers` property has a suffix matching the profile name in the `dot-service.yml` 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.
 
-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
@@ -231,2 +254,3 @@
 
+
 | File/Directory       | Type | Description             |
@@ -251,3 +275,3 @@ |----------------------|------|-------------------------|
 - 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)
@@ -254,0 +278,0 @@ - Create a new secret called `DOT_TOKEN` and set the value to a valid dotCMS CLI token.

src/postinstall.js

 "use strict";
 
+// Dependencies
 const path = require('path');
@@ -7,2 +8,3 @@ const fs = require('fs').promises;
 
+// Architecture and platform mappings
 const ARCHITECTURE_MAPPING = {
@@ -18,2 +20,8 @@ "x64": "x86_64",
 
+const EXTENSION_MAP = {
+    "win32": ".exe",
+    "default": ""
+};
+
+// Utility functions
 function getGlobalBinPath() {
@@ -25,2 +33,3 @@ const npmGlobalPrefix = process.env.PREFIX || process.env.npm_config_prefix || process.env.HOME;
 function validatePackageConfig(packageJson) {
+    // Validation of package.json configuration
     if (!packageJson.version || !packageJson.packageName || !packageJson.alias || !packageJson.binaries || typeof packageJson.binaries !== "object") {
@@ -31,5 +40,6 @@ 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");
 
-    console.log("Installing CLI");
     const platform = os.platform();
@@ -41,2 +51,3 @@ const architecture = os.arch();
 
+    // Check installation support for platform and architecture
     if (!(os.arch() in ARCHITECTURE_MAPPING) || !(os.platform() in PLATFORM_MAPPING)) {
@@ -56,3 +67,3 @@ throw new Error(`Installation is not supported for this ${platform}/${architecture} combination.`);
         const binaries = packageJson.binaries;
-        const extension = platform === "win32" ? ".exe" : "";
+        const extension = EXTENSION_MAP[platform] || EXTENSION_MAP.default;
         const binaryKey = `${packageName}-${platform}-${architecture}`;
@@ -78,25 +89,16 @@ const binaryPath = binaries[binaryKey];
 
+// 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) {
@@ -108,38 +110,56 @@ console.error("Error while creating symlink:", error);
 
-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 = {
@@ -150,2 +170,3 @@ "install": installCli,
 
+// Execute action based on provided command
 const [cmd] = process.argv.slice(2);
@@ -163,2 +184,2 @@ if (cmd && actions[cmd]) {
     process.exit(1);
-}
+}

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

349931830

increased by0.73%

Lines of code

144

increased by18.03%

Number of lines in readme file

303

increased by8.6%

No dependency changes