feat: add a --clean-cache command to clean up locations specified at CIBW_CACHE_PATH (#2489)

* Add `clean_cache` to command-line arguments

* Add `--clean-cache` to parser

* Add logic

* Add test to clean cache when it exists

* Ad test to run cache cleaning when none exists

* Add test to run cache cleaning on unwritable path

* Use `main()` instead

* tests: move command tests

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* Create cibuildwheel cache sentinel file

* Add sentinel to existing tests + add new test

* Add signature and switch to `CACHEDIR.TAG`

Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Another instance to replace with `CACHEDIR.TAG`

* Verify `CACHEDIR.TAG` signature

* Simplify code branching and control flow

* Add test

* Add link to `CACHEDIR.TAG` specification

* Write with UTF-8 encoding

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
Co-authored-by: Henry Schreiner <henryschreineriii@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

cibuildwheel/__main__.py

@@ -23,7 +23,7 @@ from cibuildwheel.options import CommandLineArguments, Options, compute_options
 from cibuildwheel.platforms import ALL_PLATFORM_MODULES, get_build_identifiers, native_platform
 from cibuildwheel.selector import BuildSelector, EnableGroup, selector_matches
 from cibuildwheel.typing import PLATFORMS, PlatformName
-from cibuildwheel.util.file import CIBW_CACHE_PATH
+from cibuildwheel.util.file import CIBW_CACHE_PATH, ensure_cache_sentinel
 from cibuildwheel.util.helpers import strtobool
 from cibuildwheel.util.resources import read_all_configs
 
@@ -179,6 +179,12 @@ def main_inner(global_options: GlobalOptions) -> None:
         help="Print the build identifiers matched by the current invocation and exit.",
     )
 
+    parser.add_argument(
+        "--clean-cache",
+        action="store_true",
+        help="Clear the cibuildwheel cache and exit.",
+    )
+
     parser.add_argument(
         "--allow-empty",
         action="store_true",
@@ -196,6 +202,48 @@ def main_inner(global_options: GlobalOptions) -> None:
 
     global_options.print_traceback_on_error = args.debug_traceback
 
+    if args.clean_cache:
+        if not CIBW_CACHE_PATH.exists():
+            print(f"Cache directory does not exist: {CIBW_CACHE_PATH}")
+            sys.exit(0)
+
+        sentinel_file = CIBW_CACHE_PATH / "CACHEDIR.TAG"
+        if not sentinel_file.exists():
+            print(
+                f"Error: {CIBW_CACHE_PATH} does not appear to be a cibuildwheel cache directory.",
+                "Only directories with a CACHEDIR.TAG sentinel file can be cleaned.",
+                sep="\n",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        # Verify signature to ensure it's a proper cache dir
+        # See https://bford.info/cachedir/ for more
+        try:
+            sentinel_content = sentinel_file.read_text(encoding="utf-8")
+        except OSError as e:
+            print(f"Error reading cache directory tag: {e}", file=sys.stderr)
+            sys.exit(1)
+
+        if not sentinel_content.startswith("Signature: 8a477f597d28d172789f06886806bc55"):
+            print(
+                f"Error: {sentinel_file} does not contain a valid cache directory signature.",
+                "For safety, only properly signed cache directories can be cleaned.",
+                sep="\n",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        print(f"Clearing cache directory: {CIBW_CACHE_PATH}")
+        try:
+            shutil.rmtree(CIBW_CACHE_PATH)
+            print("Cache cleared successfully.")
+        except OSError as e:
+            print(f"Error clearing cache: {e}", file=sys.stderr)
+            sys.exit(1)
+
+        sys.exit(0)
+
     args.package_dir = args.package_dir.resolve()
 
     # This are always relative to the base directory, even in SDist builds
@@ -309,6 +357,7 @@ def build_in_directory(args: CommandLineArguments) -> None:
 
     # create the cache dir before it gets printed & builds performed
     CIBW_CACHE_PATH.mkdir(parents=True, exist_ok=True)
+    ensure_cache_sentinel(CIBW_CACHE_PATH)
 
     print_preamble(platform=platform, options=options, identifiers=identifiers)