feat: add a new flag overwrite for build command (#1916)

**Issue number:** Issue #1913 ADDON-83527

### PR Type

**What kind of change does this PR introduce?**
* [x] Feature
* [ ] Bug Fix
* [ ] Refactoring (no functional or API changes)
* [x] Documentation Update
* [ ] Maintenance (dependency updates, CI, etc.)

## Summary

### Changes

Previously, when a user specified a custom build path using the
`--o/--output` parameter, the entire `output_path` was cleaned before
building the add-on. This could result in unintended loss of existing
files in that directory.

Therefore, added a new flag`--overwrite` for the build command. Now, we
only attempt to clean the `output_path/<ta_name>` directory if the
--overwrite flag is provided. If the --overwrite flag is not passed and
the `output_path/<ta_name>` directory already exists, the build will
fail and prompt the user to either pass the --overwrite flag or choose a
different output path.
### User experience

User files and directories will no longer be unintentionally deleted
when a custom build path is provided using the `--o/--output` parameter.
If the `output_path/<ta_name>` directory already exists, users must
explicitly pass the `--overwrite` flag to allow it to be overwritten.
## Checklist

If an item doesn't apply to your changes, leave it unchecked.

### Review

* [x] self-review - I have performed a self-review of this change
according to the [development
guidelines](https://splunk.github.io/addonfactory-ucc-generator/contributing/#development-guidelines)
* [x] Changes are documented. The documentation is understandable,
examples work [(more
info)](https://splunk.github.io/addonfactory-ucc-generator/contributing/#documentation-guidelines)
* [x] PR title and description follows the [contributing
principles](https://splunk.github.io/addonfactory-ucc-generator/contributing/#pull-requests)
* [ ] meeting - I have scheduled a meeting or recorded a demo to explain
these changes (if there is a video, put a link below and in the ticket)

### Tests

See [the testing
doc](https://splunk.github.io/addonfactory-ucc-generator/contributing/#build-and-test).

* [x] Unit - tests have been added/modified to cover the changes
* [ ] Smoke - tests have been added/modified to cover the changes
* [ ] UI - tests have been added/modified to cover the changes
* [x] coverage - I have checked the code coverage of my changes [(see
more)](https://splunk.github.io/addonfactory-ucc-generator/contributing/#checking-the-code-coverage)

**Demo/meeting:**

*Reviewers are encouraged to request meetings or demos if any part of
the change is unclear*

Author: hetangmodi-crest

docs/commands.md

@@ -38,6 +38,7 @@ It takes the following parameters:
     Example:  `--pip-custom-flag="--no-compile --prefer-binary --ignore-installed --report path/to/report.json --progress-bar on"`
 
 * `--build-custom-ui` - [optional] Additional flag that will trigger build of custom UI repo (execute build script from `./ui` repository).
+* `--overwrite` - [optional] overwrites the already existing add-on directory. By default, you can't build an add-on to an already existing directory.
 
 ### Verbose mode
 

splunk_add_on_ucc_framework/commands/build.py

@@ -248,13 +248,18 @@ def _get_addon_version(addon_version: Optional[str]) -> str:
     return addon_version.strip()
 
 
-def _get_build_output_path(output_directory: Optional[str] = None) -> str:
+def _get_build_output_path(
+    output_directory: Optional[str] = None, overwrite: bool = False
+) -> tuple[str, bool]:
     if output_directory is None:
-        return os.path.join(os.getcwd(), "output")
+        # To preserve the previous behaviour where we used to clean output dir
+        # when output_directory was set to None
+        overwrite = True
+        return os.path.join(os.getcwd(), "output"), overwrite
     else:
         if not os.path.isabs(output_directory):
-            return os.path.join(os.getcwd(), output_directory)
-        return output_directory
+            return os.path.join(os.getcwd(), output_directory), overwrite
+        return os.path.join(output_directory), overwrite
 
 
 def _get_python_version_from_executable(python_binary_name: str) -> str:
@@ -484,6 +489,7 @@ def generate(
     pip_legacy_resolver: bool = False,
     pip_custom_flag: Optional[str] = None,
     build_custom_ui: bool = False,
+    overwrite: bool = False,
 ) -> None:
     logger.info(f"ucc-gen version {__version__} is used")
     logger.info(f"Python binary name to use: {python_binary_name}")
@@ -495,21 +501,27 @@ def generate(
             f"Failed to identify Python version for library installation. Error: {e}"
         )
         sys.exit(1)
-
-    output_directory = _get_build_output_path(output_directory)
-    logger.info(f"Output folder is {output_directory}")
     addon_version = _get_addon_version(addon_version)
     logger.info(f"Add-on will be built with version '{addon_version}'")
     if not os.path.exists(source):
         logger.error(
             f"Source directory: '{source}' does not exist. Please verify that given source exists."
         )
         sys.exit(1)
-    shutil.rmtree(os.path.join(output_directory), ignore_errors=True)
-    os.makedirs(os.path.join(output_directory))
-    logger.info(f"Cleaned out directory {output_directory}")
     app_manifest = get_app_manifest(source)
     ta_name = app_manifest.get_addon_name()
+    output_directory, overwrite = _get_build_output_path(output_directory, overwrite)
+    logger.info(f"Output folder is {output_directory}")
+    if not overwrite and os.path.exists(os.path.join(output_directory, ta_name)):
+        logger.error(
+            f"The location {os.path.join(output_directory,ta_name)} is already taken, use `--overwrite` "
+            "option to overwrite the content of existing directory."
+        )
+        sys.exit(1)
+    if overwrite:
+        shutil.rmtree(os.path.join(output_directory, ta_name), ignore_errors=True)
+        os.makedirs(os.path.join(output_directory, ta_name))
+        logger.info(f"Cleaned out directory {os.path.join(output_directory,ta_name)}")
     generated_files = []
 
     gc_path = _get_and_check_global_config_path(source, config_path)

splunk_add_on_ucc_framework/main.py

@@ -147,6 +147,12 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         default=False,
         required=False,
     )
+    build_parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        default=False,
+        help="overwrite already present output/add-on dir",
+    )
 
     package_parser = subparsers.add_parser("package", description="Package an add-on")
     package_parser.add_argument(
@@ -304,6 +310,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             pip_legacy_resolver=args.pip_legacy_resolver,
             pip_custom_flag=args.pip_custom_flag,
             build_custom_ui=args.build_custom_ui,
+            overwrite=args.overwrite,
         )
     if args.command == "package":
         package.package(path_to_built_addon=args.path, output_directory=args.output)

tests/unit/commands/test_build.py

@@ -17,6 +17,7 @@
 )
 
 from splunk_add_on_ucc_framework import __version__
+from tests.unit.helpers import get_path_to_source_dir
 
 CURRENT_PATH = os.getcwd()
 
@@ -74,7 +75,7 @@
     ],
 )
 def test_get_build_output_path(output_directory, expected_output_directory):
-    assert expected_output_directory == _get_build_output_path(output_directory)
+    assert expected_output_directory == _get_build_output_path(output_directory)[0]
 
 
 @patch("splunk_add_on_ucc_framework.commands.build.subprocess.run")
@@ -222,8 +223,39 @@ def test_ta_name_mismatch(
         )
 
 
+@patch("os.path.exists")
+@patch("splunk_add_on_ucc_framework.commands.build.get_app_manifest")
+def test_existing_output_dir(mock_get_app_manifest, mock_os_path, caplog):
+    mock_os_path.return_value = True
+
+    mock_app_manifest = MagicMock()
+    mock_app_manifest.get_addon_name.return_value = "ta_name_1"
+    mock_get_app_manifest.return_value = mock_app_manifest
+
+    with pytest.raises(SystemExit):
+        generate(
+            source="source/path",
+            addon_version="1.0.0",
+            output_directory="dummy_path",
+            python_binary_name="python3",
+            verbose_file_summary_report=False,
+            pip_version="latest",
+            pip_legacy_resolver=False,
+        )
+    output_dir = os.path.abspath(
+        os.path.join(get_path_to_source_dir(), os.pardir, "dummy_path", "ta_name_1")
+    )
+    expected_msg = (
+        f"The location {output_dir} is already taken, use `--overwrite` option to overwrite "
+        "the content of existing directory."
+    )
+    assert expected_msg in caplog.text
+
+
 @patch("splunk_add_on_ucc_framework.commands.build._get_build_output_path")
-def test_uncaught_exception(mock_get_build_output_path, caplog):
+@patch("os.path.exists")
+def test_uncaught_exception(mock_get_build_output_path, mock_os_path, caplog):
+    mock_os_path.return_value = True
     mock_get_build_output_path.side_effect = ValueError("Some exc msg")
 
     expected_msg_1 = "Uncaught exception occurred. Exception details:"

tests/unit/test_main.py

@@ -21,6 +21,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
@@ -36,6 +37,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
@@ -51,6 +53,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
@@ -66,10 +69,11 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
-            ["-v", "--source", "package", "--ta-version", "2.1.0"],
+            ["-v", "--source", "package", "--ta-version", "2.1.0", "--overwrite"],
             {
                 "source": "package",
                 "config_path": None,
@@ -81,6 +85,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": True,
             },
         ),
         (
@@ -103,6 +108,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
@@ -127,6 +133,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
@@ -153,6 +160,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
@@ -180,6 +188,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
@@ -208,6 +217,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
@@ -238,6 +248,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
@@ -269,6 +280,7 @@
                 "pip_legacy_resolver": True,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
@@ -291,6 +303,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": False,
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
         (
@@ -315,6 +328,7 @@
                 "pip_legacy_resolver": False,
                 "pip_custom_flag": "--progress-bar on",
                 "build_custom_ui": False,
+                "overwrite": False,
             },
         ),
     ],