Add dry run, license setting & additional readme enhancement

Changes include implementing the dry run functionality, enabling the setting of license within the composer package, and allowing additional readme content to be appended to the usual readme. This development also entails minor code optimizations and bug fixes, making the package building scripts more robust and easier to use.

src/octopower

@@ -3,8 +3,8 @@
 # Program name
 PROGRAM_NAME="OctoPower"
 PROGRAM_CODE="octopower"
-PROGRAM_VERSION="1.0.1"
-PROGRAM_V="1.0"
+PROGRAM_VERSION="2.0.1"
+PROGRAM_V="2.0"
 PROGRAM_URL="https://git.vdm.dev/octoleo/${PROGRAM_CODE}"
 
 # Do some prep work
@@ -16,6 +16,10 @@ command -v curl >/dev/null 2>&1 || {
   echo >&2 "[error] We require curl for $PROGRAM_NAME v${PROGRAM_VERSION} to work, but it's not installed.  Aborting."
   exit 1
 }
+command -v wget >/dev/null 2>&1 || {
+  echo >&2 "[error] We require wget for $PROGRAM_NAME v${PROGRAM_VERSION} to work, but it's not installed.  Aborting."
+  exit 1
+}
 command -v jq >/dev/null 2>&1 || {
   echo >&2 "[error] We require jq for $PROGRAM_NAME v${PROGRAM_VERSION} to work, but it's not installed.  Aborting."
   exit 1
@@ -24,7 +28,13 @@ command -v zip >/dev/null 2>&1 || {
   echo >&2 "[error] We require zip for $PROGRAM_NAME v${PROGRAM_VERSION} to work, but it's not installed.  Aborting."
   exit 1
 }
+command -v sed >/dev/null 2>&1 || {
+  echo >&2 "[error] We require sed for $PROGRAM_NAME v${PROGRAM_VERSION} to work, but it's not installed.  Aborting."
+  exit 1
+}
 
+# Subshell to isolate variables
+(
   # main function ˘Ô≈ôﺣ
   function main() {
     # check if we have project overrides for the environment variables
@@ -34,6 +44,8 @@ function main() {
       clearMainEnv
       exit 1
     }
+    # when a dry run
+    showDryRunNotice
     # get the package details
     getPackageDetails || {
       echo >&2 "[error] We require config file with correct packaging details for $PROGRAM_NAME v${PROGRAM_VERSION} to work, but it's not found in/at $VDM_PACKAGE_CONF_FILE.  Aborting."
@@ -60,6 +72,8 @@ function main() {
     }
     # set the package composer file
     setPackageComposerFile
+    # set license
+    setLicenseFile
     # set the readme
     setReadMe
     # get package repository
@@ -82,6 +96,23 @@ function main() {
     _echo "[Success] Package completely updated!"
   }
 
+  # show dry run notice
+  function showDryRunNotice() {
+    _dry_run ""
+    _dry_run "======================================================================"
+    _dry_run "      THIS IS A DRY RUN!"
+    _dry_run "======================================================================"
+    _dry_run ""
+    _dry_run " This means we will not update remote systems."
+    _dry_run " But will perform all expected tasks locally."
+    _dry_run " We will not clear folders and files created, and set locally."
+    _dry_run " Which mean you will need to clear those manually (after review)."
+    _dry_run ""
+    _dry_run "ALL remote changing events will be explained and marked as [dry-run]"
+    _dry_run "======================================================================"
+    _dry_run ""
+  }
+
   # set the package details
   function getPackageDetails() {
     # little information of progress
@@ -110,13 +141,16 @@ function getPackageDetails() {
     getConfigValue 'VDM_PACKAGE_PHP' '.package.php' || has_error=true
     getConfigValue 'VDM_PACKAGE_JOOMLA_FRAMEWORK' '.package.joomla_framework' false || unset VDM_PACKAGE_JOOMLA_FRAMEWORK
     getConfigValue 'VDM_PACKAGE_VERSION' '.package.version' || has_error=true
-  getConfigValue 'VDM_LICENSE' '.package.license' || has_error=true
-  getConfigValue 'VDM_LICENSE_FILE' '.package.license_file' false || unset VDM_LICENSE_FILE
-  getConfigValue 'VDM_LICENSE_FILE_PATH' '.package.license_file_path' false || unset VDM_LICENSE_FILE_PATH
+    getConfigValue 'VDM_PACKAGE_LICENSE' '.package.license' || has_error=true
+    getConfigValue 'VDM_PACKAGE_LICENSE_FILE' '.package.license_file' false || unset VDM_PACKAGE_LICENSE_FILE
+    getConfigValue 'VDM_PACKAGE_LICENSE_FILE_PATH' '.package.license_file_path' false || unset VDM_PACKAGE_LICENSE_FILE_PATH
     getConfigValue 'VDM_AUTHOR' '.package.author' false || unset VDM_AUTHOR
     getConfigValue 'VDM_AUTHOR_EMAIL' '.package.author_email' false || unset VDM_AUTHOR_EMAIL
     getConfigValue 'VDM_AUTHOR_URL' '.package.author_url' false || unset VDM_AUTHOR_URL
     getConfigValue 'VDM_AUTHOR_ROLE' '.package.author_role' false || unset VDM_AUTHOR_ROLE
+    getConfigValue 'VDM_PACKAGE_ADDITIONAL_README' '.package.additional_readme' false || unset VDM_PACKAGE_ADDITIONAL_README
+    getConfigValue 'VDM_PACKAGE_ADDITIONAL_README_FILE' '.package.additional_readme_file' false || unset VDM_PACKAGE_ADDITIONAL_README_FILE
+    getConfigValue 'VDM_PACKAGE_README_FILE_PATH' '.package.readme_file_path' false || unset VDM_PACKAGE_README_FILE_PATH
     # check if we have some errors already
     $has_error && return 13
 
@@ -147,6 +181,7 @@ function getRepositoryDetails() {
       getConfigValue 'VDM_REPOSITORY_TOKEN_NAME' '.repository.token_name' false || VDM_REPOSITORY_TOKEN_NAME="VDM_GLOBAL_TOKEN"
       getConfigValue 'VDM_REPOSITORY_URL_NAME' '.repository.url_name' false || VDM_REPOSITORY_URL_NAME="VDM_GLOBAL_URL"
       getConfigValue 'VDM_REPOSITORY_API_NAME' '.repository.api_name' false || VDM_REPOSITORY_API_NAME="VDM_GLOBAL_API"
+      getConfigValue 'VDM_REPOSITORY_REPLACEMENT' '.repository.replace' false || unset VDM_REPOSITORY_REPLACEMENT
       # set the package (api/url/toke)
       tmp_token=${!VDM_REPOSITORY_TOKEN_NAME}
       tmp_url=${!VDM_REPOSITORY_URL_NAME}
@@ -175,27 +210,27 @@ function setPackageDir() {
     # little information of progress
     _echo "[info] Setting the Package Directories..."
     # the full project path
-  VDM_PACKAGE_DIR="${VDM_MAIN_DIR}/${VDM_REPOSITORY_REPO}"
-  VDM_PACKAGE_GIT_DIR="${VDM_MAIN_DIR}/git"
-  VDM_PACKAGE_SRC_DIR="${VDM_PACKAGE_DIR}/src"
-  VDM_PACKAGE_ZIP_FILE="${VDM_PACKAGE_GIT_DIR}/${VDM_REPOSITORY_REPO}.${VDM_PACKAGE_VERSION:-1.0.0}.zip"
+    : "${VDM_PACKAGE_DIR:="${VDM_MAIN_DIR}/${VDM_REPOSITORY_REPO}"}"
+    : "${VDM_PACKAGE_GIT_DIR:="${VDM_MAIN_DIR}/git"}"
+    : "${VDM_PACKAGE_SRC_DIR:="${VDM_PACKAGE_DIR}/src"}"
+    : "${VDM_PACKAGE_ZIP_FILE:="${VDM_PACKAGE_GIT_DIR}/${VDM_REPOSITORY_REPO}.${VDM_PACKAGE_VERSION:-1.0.0}.zip"}"
     # makes the project path available
     export VDM_PACKAGE_DIR
     export VDM_PACKAGE_GIT_DIR
     export VDM_PACKAGE_SRC_DIR
     export VDM_PACKAGE_ZIP_FILE
     # always remove previous files (if found)
-  clearFiles
+    resetFiles
     # set the license file
-  VDM_PACKAGE_LICENSE_FILE_PATH="${VDM_PACKAGE_DIR}/LICENSE"
+    : "${VDM_PACKAGE_LICENSE_FILE_PATH:="${VDM_PACKAGE_DIR}/LICENSE"}"
+    # set the README
+    : "${VDM_PACKAGE_README_FILE_PATH:="${VDM_PACKAGE_DIR}/README.md"}"
     # set the package composer file
     VDM_PACKAGE_COMPOSER_FILE="${VDM_PACKAGE_DIR}/composer.json"
-  # set the README
-  VDM_README_MD="${VDM_PACKAGE_DIR}/README.md"
     # makes the project file locations available
     export VDM_PACKAGE_LICENSE_FILE_PATH
+    export VDM_PACKAGE_README_FILE_PATH
     export VDM_PACKAGE_COMPOSER_FILE
-  export VDM_README_MD
     # make sure the packages dir is created
     mkdir -p "${VDM_PACKAGE_DIR}" || return 12
     #make sure the src dir is created
@@ -214,6 +249,14 @@ function setPowers() {
     local has_powers=false
     # load all the repositories
     loadSuperpowerRepositories || return 13
+    # Check if the .exclude-powers[] field exists and is not empty
+    if [ "$(echo "${VDM_CONFIG_DATA}" | jq '.exclude_powers | length')" -gt 0 ]; then
+      # Iterate over the exclude-powers array
+      for exclude_power in $(echo "${VDM_CONFIG_DATA}" | jq -r '.exclude_powers[]'); do
+        # Load the exclude power
+        loadExcludePower "${exclude_power}"
+      done
+    fi
     # search for the powers
     for power in $(echo "${VDM_CONFIG_DATA}" | jq -r '.powers[]'); do
       # load the power
@@ -225,16 +268,54 @@ function setPowers() {
     return 0
   }
 
+  # load the exclude power
+  function loadExcludePower() {
+    local guid="$1"
+    if [[ $guid == "//"* ]]; then
+      return 0 # skip comments ;)
+    elif [ ${#guid} -ge 30 ] && validateGuid "${guid}"; then
+      setExcludePower "$guid" || return 19
+      return 0
+    fi
+    return 0
+  }
+
+  # set the exclude power found
+  function setExcludePower() {
+    local guid="$1"
+
+    # Remove the power from VDM_POWERS if it exists
+    if existingPower "$guid"; then
+      VDM_POWERS=$(jq --arg guid "$guid" '
+        map(select(. != $guid))
+      ' <<< "$VDM_POWERS")
+    fi
+
+    # check if we have already loaded this power
+    existingExcludePower "${guid}" && return 0
+
+    # Add the guid to VDM_EXCLUDE_POWERS
+    VDM_EXCLUDE_POWERS=$(jq --arg guid "$guid" '
+      . + [ $guid ]
+    ' <<< "$VDM_EXCLUDE_POWERS")
+
+    return 0
+  }
+
   # load the power
   function loadPower() {
     local guid="$1"
     if [[ $guid == "//"* ]]; then
       return 0 # skip comments ;)
     elif [ ${#guid} -ge 30 ] && validateGuid "${guid}"; then
+      if  existingExcludePower "$guid"; then
+        return 0 # skip excluded ;)
+      else
         setPower "$guid" || return 19
         loadChildrenPowers "$guid" || return 19
         return 0
       fi
+    fi
     return 19
   }
 
@@ -357,6 +438,23 @@ function loadChildrenPowers() {
     return 0
   }
 
+  # Check if a given power already exists in VDM_EXCLUDE_POWERS
+  function existingExcludePower() {
+    local guid="$1"
+    local exists
+
+    # Check if the power is already in VDM_EXCLUDE_POWERS
+    exists=$(jq --arg guid "$guid" '
+        map(select(. == $guid)) | length > 0
+      ' <<< "$VDM_EXCLUDE_POWERS")
+
+    if [ "$exists" = "true" ]; then
+      return 0  # GUID exists
+    else
+      return 1  # GUID does not exist
+    fi
+  }
+
   # Check if a given power already exists in VDM_POWERS
   function existingPower() {
     local guid="$1"
@@ -529,6 +627,8 @@ function setPowerData() {
       clearPowerDataEnv
       return 11
     fi
+    # replace any strings in namespace as needed
+    [ -n "${VDM_REPOSITORY_REPLACEMENT}" ] && VDM_POWER_NAMESPACE=$(strReplace "${VDM_POWER_NAMESPACE}")
     # we must add these locally to avoid collusion
     owner="${VDM_POWER_OWNER}"
     repo="${VDM_POWER_REPO}"
@@ -577,6 +677,8 @@ function setPowerData() {
       mkdir -p "${class_path}"
       # move the class into place
       mv -f "${VDM_API_FILE_PATH}" "${class_path}/${name}.php"
+      # replace any strings in code as needed
+      [ -n "${VDM_REPOSITORY_REPLACEMENT}" ] && fileReplaceStrings "${class_path}/${name}.php"
     else
       # always clear memory
       clearPowerDataEnv
@@ -820,7 +922,7 @@ function clearMainEnv() {
     unset VDM_PACKAGE_ZIP_FILE
     unset VDM_PACKAGE_LICENSE_FILE_PATH
     unset VDM_PACKAGE_COMPOSER_FILE
-  unset VDM_README_MD
+    unset VDM_PACKAGE_README_FILE_PATH
     # SET IN: getPackageDetails
     unset VDM_CONFIG_DATA
     unset VDM_PACKAGER
@@ -837,9 +939,8 @@ function clearMainEnv() {
     unset VDM_PACKAGE_PHP
     unset VDM_PACKAGE_JOOMLA_FRAMEWORK
     unset VDM_PACKAGE_VERSION
-  unset VDM_LICENSE
-  unset VDM_LICENSE_FILE
-  unset VDM_LICENSE_FILE_PATH
+    unset VDM_PACKAGE_LICENSE
+    unset VDM_PACKAGE_LICENSE_FILE
     unset VDM_AUTHOR
     unset VDM_AUTHOR_EMAIL
     unset VDM_AUTHOR_URL
@@ -859,6 +960,17 @@ function clearMainEnv() {
 
   # clear all this projects files
   function clearFiles() {
+    # when a dry run
+    _dry_run "[dry-run] We would have cleared all directories."
+    _dry_run "[dry-run] Therefore, ${VDM_PACKAGE_GIT_DIR:?}/${VDM_REPOSITORY_REPO:?} should still exist." && return 0
+    # always remove files
+    rm -fr "${VDM_PACKAGE_DIR:?}"
+    rm -fr "${VDM_PACKAGE_GIT_DIR:?}/${VDM_REPOSITORY_REPO:?}"
+    rm -fr "${VDM_PACKAGE_ZIP_FILE:?}"
+  }
+
+  # clear all the projects files if they exist
+  function resetFiles() {
     # always remove files
     rm -fr "${VDM_PACKAGE_DIR:?}"
     rm -fr "${VDM_PACKAGE_GIT_DIR:?}/${VDM_REPOSITORY_REPO:?}"
@@ -1121,12 +1233,40 @@ function getJoomlaFrameworkRequired() {
     echo -n "$json"
   }
 
+  # get the additional readme content
+  function getAdditionalReadme() {
+      # check if the additional readme content file is passed via a URL
+      if [ -n "${VDM_PACKAGE_ADDITIONAL_README_FILE}" ]; then
+        if [[ "${VDM_PACKAGE_ADDITIONAL_README_FILE}" =~ ^"http:" ]] || [[ "${VDM_PACKAGE_ADDITIONAL_README_FILE}" =~ ^"https:" ]]; then
+            # check if the URL is accessible
+            # shellcheck disable=SC2143
+            if [[ $(wget -S --spider "${VDM_PACKAGE_ADDITIONAL_README_FILE}" 2>&1 | grep 'HTTP/1.1 200 OK') ]]; then
+              echo ""
+              # fetch and print the content from the URL
+              wget --quiet -O - "${VDM_PACKAGE_ADDITIONAL_README_FILE}"
+            fi
+        elif [ -f "${VDM_PACKAGE_ADDITIONAL_README_FILE}" ]; then
+          echo ""
+          # print the content of the local file
+          cat "${VDM_PACKAGE_ADDITIONAL_README_FILE}"
+        fi
+      fi
+      # check if we have additional readme content set and print it
+      if [ -n "${VDM_PACKAGE_ADDITIONAL_README}" ]; then
+        echo ""
+        echo "${VDM_PACKAGE_ADDITIONAL_README}"
+        echo ""
+      fi
+  }
+
+
   # Convert JOOMLA_FRAMEWORK to a Markdown list
   function getJoomlaFramework() {
     if [ ${#JOOMLA_FRAMEWORK[@]} -eq 0 ]; then
       echo -n ""
     else
       local markdown_list="\n## Joomla Framework Dependencies\n\n"
+      markdown_list+="> Here we list the framework dependencies and provide links to where they are used.\n\n";
       if [ -z "${VDM_PACKAGE_JOOMLA_FRAMEWORK}" ]; then
         markdown_list+="> You should add the following to your project to ensure the Joomla! framework classes are included.\n\n"
         for key in $(printf "%s\n" "${!JOOMLA_FRAMEWORK[@]}" | sort); do
@@ -1152,6 +1292,7 @@ function getJoomlaDependencies() {
       echo -n ""
     else
       local markdown_list="\n## Joomla CMS Dependencies\n\n"
+      markdown_list+="> Here we list the CMS dependencies and provide links to where they are used.\n\n";
       for key in $(printf "%s\n" "${!JOOMLA_NAMESPACES[@]}" | sort); do
         markdown_list+="- ${key}\n";
         markdown_list+=$(getLinkedClassesMarkdown "${key}");
@@ -1200,11 +1341,11 @@ function setReadMe() {
         [ -n "${!VDM_PACKAGE_DESCRIPTION}" ] && echo "${!VDM_PACKAGE_DESCRIPTION}" || echo "${VDM_PACKAGE_DESCRIPTION}"
       fi
       echo ""
-    echo "## Details"
+      echo "## Composer Package Details"
       echo ""
       echo "- Packager: [${VDM_PACKAGER}](${VDM_PACKAGER_URL})"
       echo "- Author: [${VDM_AUTHOR:-$PROGRAM_NAME}](${VDM_AUTHOR_URL:-$PROGRAM_URL})"
-    echo "- Creation Date: ${CREATION_DATE}"
+      echo "- Package Build Date: ${VDM_PACKAGE_BUILD_DATE}"
       echo ""
       echo "### Installation via Composer"
       echo ""
@@ -1223,38 +1364,41 @@ function setReadMe() {
       echo "\`\`\`"
       echo "composer require ${VDM_NAME:-error}:${VDM_PACKAGE_VERSION:-1.0.0}"
       echo "\`\`\`"
+      getAdditionalReadme
       getJoomlaFramework
       getJoomlaDependencies
       echo ""
       echo "### License"
-    echo "> ${VDM_LICENSE:-none}"
+      echo "> ${VDM_PACKAGE_LICENSE:-none}"
       echo ""
-  } >"${VDM_README_MD}"
+    } >"${VDM_PACKAGE_README_FILE_PATH}"
   }
 
   # set the license file
   function setLicenseFile() {
     local has_error=false
     # check if the license file is passed via a URL
-  if [[ "${VDM_LICENSE_FILE}" =~ ^"http:" ]] || [[ "${VDM_LICENSE_FILE}" =~ ^"https:" ]]; then
+    if [ -n "${VDM_PACKAGE_LICENSE_FILE}" ]; then
+      if [[ "${VDM_PACKAGE_LICENSE_FILE}" =~ ^"http:" ]] || [[ "${VDM_PACKAGE_LICENSE_FILE}" =~ ^"https:" ]]; then
         # shellcheck disable=SC2143
-    if [[ $(wget -S --spider "${VDM_LICENSE_FILE}" 2>&1 | grep 'HTTP/1.1 200 OK') ]]; then
-      wget --quiet "${VDM_LICENSE_FILE}" -O "${VDM_LICENSE_FILE_PATH}"
-      VDM_LICENSE_FILE="LICENSE"
+        if [[ $(wget -S --spider "${VDM_PACKAGE_LICENSE_FILE}" 2>&1 | grep 'HTTP/1.1 200 OK') ]]; then
+          wget --quiet "${VDM_PACKAGE_LICENSE_FILE}" -O "${VDM_PACKAGE_LICENSE_FILE_PATH}"
         else
-      echo >&2 "[error] The license:${VDM_LICENSE_FILE} is not a valid URL."
+          echo >&2 "[error] The license:${VDM_PACKAGE_LICENSE_FILE} is not a valid URL."
           has_error=true
         fi
-  elif [ -f "${VDM_LICENSE_DIR}/${VDM_LICENSE_FILE}" ]; then
+      elif [ -f "${VDM_LICENSE_DIR}/${VDM_PACKAGE_LICENSE_FILE}" ]; then
         # now copy the license file
-    cp "${VDM_LICENSE_DIR}/${VDM_LICENSE_FILE}" "${VDM_LICENSE_FILE_PATH}"
+        cp "${VDM_LICENSE_DIR}/${VDM_PACKAGE_LICENSE_FILE}" "${VDM_PACKAGE_LICENSE_FILE_PATH}"
       else
-    echo >&2 "[error] The license:${VDM_LICENSE_DIR}/${VDM_LICENSE_FILE} not found."
+        echo >&2 "[error] The license:${VDM_LICENSE_DIR}/${VDM_PACKAGE_LICENSE_FILE} not found."
         has_error=true
       fi
+      VDM_PACKAGE_LICENSE_FILE=$(basename "${VDM_PACKAGE_LICENSE_FILE_PATH}")
+    fi
     # check if we have some errors
     if $has_error; then
-    return 16
+      return 0
     fi
     # little information of progress
     _echo "[info] Setting the License File..."
@@ -1305,6 +1449,13 @@ function setRepository() {
         makeGitCommit "${message}" "${VDM_PACKAGE_VERSION:-1.0.0}" "$VDM_TAG_EXIST" || return 28
         # give little notice of progress
         _echo "[info] Pushing changes to (${VDM_REPOSITORY_OWNER}/${VDM_REPOSITORY_REPO}) repository"
+        # when a dry run
+        _dry_run "[dry-run] We would have pushed the update to the existing repo on the Gitea system." && {
+          if ! $VDM_TAG_EXIST; then
+            _dry_run "[dry-run] We would have pushed the tags to the existing repo on the Gitea system."
+          fi
+          return 0
+        }
         # make a normal push update
         git push >/dev/null 2>&1 || return 30
         if ! $VDM_TAG_EXIST; then
@@ -1315,6 +1466,9 @@ function setRepository() {
         setGitRepository || return 29
         # give little notice of progress
         _echo "[info] Pushing (TO CREATE) changes to (${VDM_REPOSITORY_OWNER}/${VDM_REPOSITORY_REPO}) repository"
+        # when a dry run
+        _dry_run "[dry-run] We would have pushed the changes to the new repo:${VDM_REPOSITORY_BRANCH} on the Gitea system."
+        _dry_run "[dry-run] We would have pushed the tags to the new repo on the Gitea system." && return 0
         # push to creat the repository (if allowed)
         if [[ "${VDM_REPOSITORY_BRANCH}" == 'default' ]]; then
           git push -u origin master >/dev/null 2>&1 || return 30
@@ -1450,6 +1604,10 @@ function setRepositoryNewFiles() {
 
   # set a composer package
   function setComposerPackage() {
+    # when a dry run
+    _dry_run "[dry-run] We would have removed ${VDM_PACKAGE_GIT_DIR}/${VDM_REPOSITORY_REPO}/.git"
+    _dry_run "[dry-run] Then we would have zipped ${VDM_PACKAGE_GIT_DIR}/${VDM_REPOSITORY_REPO} into ${VDM_PACKAGE_ZIP_FILE}"
+    _dry_run "[dry-run] Then we would have pushed the composer package up to the Gitea system." && return 0
     # remove the git directory
     rm -fr "${VDM_PACKAGE_GIT_DIR}/${VDM_REPOSITORY_REPO}/.git" || return 31
     # zip the package
@@ -1496,6 +1654,15 @@ function _echo() {
     fi
   }
 
+  # when this is a dry run
+  function _dry_run() {
+    if (("$VDM_DRY_RUN" == 1)); then
+      _echo "$1"
+      return 0
+    fi
+    return 1
+  }
+
   # Zip the content of a path
   function _zip() {
       local folder_path="${1}"
@@ -1516,6 +1683,56 @@ function _zip() {
       return 1
   }
 
+  # Perform string replacements (VDM_REPOSITORY_REPLACEMENT)
+  function strReplace() {
+      local content="$1"
+      local result="$content"
+      local pairs
+      local pair_decoded
+      local key
+      local value
+
+      # Extract keys and values and perform replacements
+      pairs=$(echo "$VDM_REPOSITORY_REPLACEMENT" | jq -r 'to_entries | .[] | @base64')
+
+      # Loop over the pairs without creating a subshell
+      while IFS= read -r pair; do
+          # Decode from base64
+          pair_decoded=$(echo "$pair" | base64 --decode)
+          key=$(echo "$pair_decoded" | jq -r .key)
+          value=$(echo "$pair_decoded" | jq -r .value)
+
+          # Perform replacements in the string
+          # shellcheck disable=SC2001
+          result=$(echo "$result" | sed "s|${key//\\/\\\\}|${value//\\/\\\\}|g")
+      done <<< "$pairs"  # Redirect the variable into the loop to avoid subshells
+
+      echo "$result"
+  }
+
+  # Replace strings in a file directly (VDM_REPOSITORY_REPLACEMENT)
+  function fileReplaceStrings() {
+      local file_path="$1"
+
+      # Check if the file exists
+      if [[ ! -f "$file_path" ]]; then
+          echo "File does not exist: $file_path"
+          return 1
+      fi
+
+      # Extract keys and values and perform replacements
+      echo "$VDM_REPOSITORY_REPLACEMENT" | jq -r 'to_entries | .[] | @base64' |
+      while IFS= read -r pair; do
+          # Decode from base64
+          pair_decoded=$(echo "$pair" | base64 --decode)
+          key=$(echo "$pair_decoded" | jq -r .key)
+          value=$(echo "$pair_decoded" | jq -r .value)
+
+          # Perform replacements in the file using unescaped values
+          sed -i "s|${key//\\/\\\\}|${value//\\/\\\\}|g" "$file_path"
+      done
+  }
+
   # uninstalls the octopc program.
   function runUninstall() {
     # now remove the script
@@ -1659,15 +1876,18 @@ START_BUILD=$(date +"%s")
   # use UTC+00:00 time also called zulu
   # shellcheck disable=SC2034
   START_DATE=$(TZ=":ZULU" date +"%m/%d/%Y @ %R (UTC)")
-CREATION_DATE=$(TZ=":ZULU" date +"%B %Y")
+  VDM_PACKAGE_BUILD_DATE=$(TZ=":ZULU" date +"%B %Y")
 
   # the quiet switch
-QUIET="${QUIET:-0}"
+  : "${QUIET:=0}"
+
+  # the dry run switch
+  : "${VDM_DRY_RUN:=0}"
 
   # we set the packager directories
   tmp_path="/home/$USER/${PROGRAM_CODE}"
   # ALWAYS USE GLOBAL IF SET
-VDM_MAIN_DIR="${VDM_MAIN_DIR:-$tmp_path}"
+  : "${VDM_MAIN_DIR:="${VDM_MAIN_DIR:-$tmp_path}"}"
 
   # we set the licenses directory
   tmp_path="${VDM_MAIN_DIR}/licenses"
@@ -1675,7 +1895,7 @@ tmp_path="${VDM_MAIN_DIR}/licenses"
   # if path not set try $PWD path
   [ -d "$tmp_path" ] || tmp_path="$PWD"
   # ALWAYS USE GLOBAL IF SET
-VDM_LICENSE_DIR="${VDM_LICENSE_DIR:-$tmp_path}"
+  : "${VDM_LICENSE_DIR:="$tmp_path"}"
 
   # the environment file variables path
   tmp_path="$PWD/.env_${PROGRAM_CODE}"
@@ -1684,7 +1904,7 @@ tmp_path="$PWD/.env_${PROGRAM_CODE}"
   # if file not set try $VDM_MAIN_DIR path
   [ -f "$tmp_path" ] || tmp_path="/home/$USER/.config/${PROGRAM_CODE}/.env"
   # ALWAYS USE GLOBAL IF SET
-VDM_ENV_FILE_PATH="${VDM_ENV_FILE_PATH:-$tmp_path}"
+  : "${VDM_ENV_FILE_PATH:="$tmp_path"}"
 
   # clear this tmp out
   unset tmp_path
@@ -1699,6 +1919,9 @@ while :; do
     -q | --quiet)
       QUIET=1
       ;;
+    -n | --dry-run)
+      VDM_DRY_RUN=1
+      ;;
     --uninstall)
       runUninstall
       shift
@@ -1728,6 +1951,13 @@ while :; do
         exit 17
       fi
       ;;
+    -l=* | --licence=*)
+      VDM_PACKAGE_LICENSE=${1#*=}
+      if [ -z "$VDM_PACKAGE_LICENSE" ]; then
+        echo '[error] "--licence" requires a non-empty option argument.'
+        exit 17
+      fi
+      ;;
     -ld=* | --licence-dir=*)
       VDM_LICENSE_DIR=${1#*=}
       if [ -z "$VDM_LICENSE_DIR" ]; then
@@ -1798,8 +2028,10 @@ if [ -f "$VDM_ENV_FILE_PATH" ]; then
   fi
 
   # Initialize the global JSON array if not already initialized
-VDM_SUPERPOWERS=${VDM_SUPERPOWERS:-"[]"}
-VDM_POWERS=${VDM_POWERS:-"[]"}
+  : "${VDM_SUPERPOWERS:="[]"}"
+  : "${VDM_POWERS:="[]"}"
+  : "${VDM_EXCLUDE_POWERS:="[]"}"
+
   # Create a global temporary file to store the dataset
   VDM_SUPERPOWERS_FILE=$(mktemp)
   # Initialize the global variable as an empty array or use the environment value if provided
@@ -1819,7 +2051,7 @@ tmp_path="$PWD/.${PROGRAM_CODE}"
   # if file not set try $VDM_MAIN_DIR path
   [ -f "$tmp_path" ] || tmp_path="$VDM_MAIN_DIR/.${PROGRAM_CODE}"
   # ALWAYS USE GLOBAL IF SET
-VDM_PACKAGE_CONF_FILE=${VDM_PACKAGE_CONF_FILE:-$tmp_path}
+  : "${VDM_PACKAGE_CONF_FILE:="$tmp_path"}"
 
   # Check if the config file is passed as a URL
   if [[ "$VDM_PACKAGE_CONF_FILE" =~ ^http: ]] || [[ "$VDM_PACKAGE_CONF_FILE" =~ ^https: ]]; then
@@ -1827,10 +2059,8 @@ if [[ "$VDM_PACKAGE_CONF_FILE" =~ ^http: ]] || [[ "$VDM_PACKAGE_CONF_FILE" =~ ^h
     if curl --output /dev/null --silent --head --fail "$VDM_PACKAGE_CONF_FILE"; then
       # Create the directory for the configuration file if it doesn't exist
       mkdir -p "$HOME/.config/$PROGRAM_CODE/projects"
-
       # get a file name
       file_name=$(getUniqueFileName "$VDM_PACKAGE_CONF_FILE")
-
       # Download the configuration file
       curl --silent "$VDM_PACKAGE_CONF_FILE" -o "$HOME/.config/$PROGRAM_CODE/projects/${file_name}_conf.json"
       VDM_PACKAGE_CONF_FILE="$HOME/.config/$PROGRAM_CODE/projects/${file_name}_conf.json"
@@ -1848,6 +2078,7 @@ fi
   }
 
   # run Main ┬┴┬┴┤(･_├┬┴┬┴
-main
+  main "$@"
+)
 
 exit 0