feat: unify CLI entry point - eliminate binary/wheel split

BREAKING CHANGE: The separate  command is removed.
Wheel installation is now available through the unified
command.

New subcommand-based CLI:
  clang-tools install <version>             # auto-detect binary/wheel
  clang-tools install <version> --binary    # force binary
  clang-tools install <version> --wheel     # force wheel
  clang-tools install <tool-name> --wheel   # wheel install by tool name
  clang-tools uninstall <version>           # remove installed tools

Auto-detection logic:
- Version-like targets in supported range → binary first, fallback wheel
- Version-like targets out of range → wheel
- Tool name targets → wheel

Legacy / flags are preserved for backward
compatibility.

Author: shenxianpeng

README.md

@@ -71,14 +71,17 @@ For a full list of CLI options, see the [documentation](https://cpp-linter.githu
 ### Install binaries
 
 ```bash
-# Install version 13 binaries
-clang-tools --install 13
+# Install version 13 binaries (auto-detects binary vs wheel)
+clang-tools install 13
+
+# Force binary installation
+clang-tools install 13 --binary
 
 # Install to a specified directory
-clang-tools --install 13 --directory .
+clang-tools install 13 --directory .
 
 # Install specific tools
-clang-tools --install 14 --tool clang-format clang-query
+clang-tools install 14 --tool clang-format clang-query
 ```
 
 If the installed directory is in your path:
@@ -92,14 +95,14 @@ clang-format-13 --version
 
 ```bash
 # Install latest clang-format wheel
-clang-tools-wheel --tool clang-format
+clang-tools install clang-format --wheel
 
 # Install specific version
-clang-tools-wheel --tool clang-format --version 21
+clang-tools install clang-format --wheel --version 21
 ```
 
 > [!IMPORTANT]
-> The `clang-tools-wheel` command is primarily intended for
+> Wheel installation is primarily intended for
 > cpp-linter projects. For general use, install wheels directly
 > using `pip`, `pipx`, or `uv`.
 

clang_tools/main.py

@@ -2,27 +2,77 @@
 ``clang_tools.main``
 --------------------
 
-The module containing main entrypoint function.
+The module containing the unified main entrypoint function.
+Supports both binary (static build) and wheel-based installation
+via a single ``clang-tools`` command.
 """
 
 import argparse
+import sys
 
 from .install import install_clang_tools, uninstall_clang_tools
-from . import RESET_COLOR, YELLOW
+from . import RESET_COLOR, YELLOW, MIN_VERSION, MAX_VERSION
 from .util import Version
 
 
+def _is_version_like(target: str) -> bool:
+    """Check if *target* looks like a version number (e.g. ``"18"``, ``"18.1"``).
+    """
+    try:
+        parts = target.split(".")
+        for p in parts:
+            int(p)
+        return True
+    except ValueError:
+        return False
+
+
+#: Known tool names supported by wheel installs
+WHEEL_TOOLS = {"clang-format", "clang-tidy", "clang-query", "clang-apply-replacements"}
+
+
+def _wheel_install(tools: list[str], version: str | None) -> int:
+    """Install tool(s) via wheel (cpp_linter_hooks).
+
+    :returns: exit code (0 on success, 1 on failure).
+    """
+    from cpp_linter_hooks.util import resolve_install  # lazy import
+
+    ok = True
+    for tool in tools:
+        path = resolve_install(tool, version)
+        version_str = f" version {version}" if version else " latest version"
+        if path:
+            print(f"{tool}{version_str} installed at: {path}")
+        else:
+            print(f"Failed to install {tool}{version_str}", file=sys.stderr)
+            ok = False
+    return 0 if ok else 1
+
+
 def get_parser() -> argparse.ArgumentParser:
-    """Get and parser to interpret CLI args."""
-    parser = argparse.ArgumentParser()
+    """Get a parser to interpret CLI args (unified entry point)."""
+    parser = argparse.ArgumentParser(
+        description="Install and manage clang-tools (clang-format, clang-tidy, etc.)"
+    )
 
+    # ------------------------------------------------------------------
+    #  Backward-compatible top-level flags (deprecated – kept for
+    #  compatibility with older scripts / workflows)
+    # ------------------------------------------------------------------
     parser.add_argument(
         "-i",
         "--install",
         metavar="VERSION",
-        help="Install clang-tools about a specific version. This can be in the form of"
-        " a semantic version specification (``x.y.z``, ``x.y``, ``x``). NOTE: A "
-        "malformed version specification will cause a silent failure.",
+        help="(deprecated) Use 'clang-tools install <version>' instead",
+        dest="_legacy_install",
+    )
+    parser.add_argument(
+        "-u",
+        "--uninstall",
+        metavar="VERSION",
+        help="(deprecated) Use 'clang-tools uninstall <version>' instead",
+        dest="_legacy_uninstall",
     )
     parser.add_argument(
         "-t",
@@ -43,54 +93,236 @@ def get_parser() -> argparse.ArgumentParser:
         "-f",
         "--overwrite",
         action="store_true",
-        help="Force overwriting the symlink to the installed binary. This will only "
-        "overwrite an existing symlink.",
+        help="Force overwriting the symlink to the installed binary.",
     )
     parser.add_argument(
         "-b",
         "--no-progress-bar",
         action="store_true",
         help="Do not display a progress bar for downloads.",
     )
-    parser.add_argument(
-        "-u",
-        "--uninstall",
-        metavar="VERSION",
-        help="Uninstall clang-tools with specific version. "
-        "This is done before any install.",
+
+    # ------------------------------------------------------------------
+    #  Subcommands (new-style CLI)
+    # ------------------------------------------------------------------
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # --- ``clang-tools install <target>`` ---------------------------------
+    install_p = subparsers.add_parser("install", help="Install clang-tools")
+    install_p.add_argument(
+        "target",
+        help="Version number (e.g. 18) or tool name (e.g. clang-format)",
+    )
+    install_p.add_argument(
+        "--binary",
+        action="store_true",
+        help="Force binary (static build) installation",
+    )
+    install_p.add_argument(
+        "--wheel",
+        action="store_true",
+        help="Force wheel installation via cpp-linter-hooks",
+    )
+    install_p.add_argument(
+        "--version",
+        dest="explicit_version",
+        default=None,
+        metavar="VER",
+        help="Explicit version for wheel install (when target is a tool name)",
+    )
+    install_p.add_argument(
+        "-t",
+        "--tool",
+        nargs="+",
+        default=["clang-format", "clang-tidy"],
+        metavar="TOOL",
+        help="Specify which tool(s) to install.",
+    )
+    install_p.add_argument(
+        "-d",
+        "--directory",
+        default="",
+        metavar="DIR",
+        help="The directory where the clang-tools are installed.",
     )
+    install_p.add_argument(
+        "-f",
+        "--overwrite",
+        action="store_true",
+        help="Force overwriting the symlink to the installed binary.",
+    )
+    install_p.add_argument(
+        "-b",
+        "--no-progress-bar",
+        action="store_true",
+        help="Do not display a progress bar for downloads.",
+    )
+
+    # --- ``clang-tools uninstall <version>`` ------------------------------
+    uninstall_p = subparsers.add_parser("uninstall", help="Uninstall clang-tools")
+    uninstall_p.add_argument("version", help="Version to uninstall")
+    uninstall_p.add_argument(
+        "-t",
+        "--tool",
+        nargs="+",
+        default=["clang-format", "clang-tidy"],
+        metavar="TOOL",
+        help="Specify which tool(s) to uninstall.",
+    )
+    uninstall_p.add_argument(
+        "-d",
+        "--directory",
+        default="",
+        metavar="DIR",
+        help="The directory from which to uninstall the tools.",
+    )
+
     return parser
 
 
-def main():
-    """The main entrypoint to the CLI program."""
+def main() -> int:
+    """Unified entry point for the CLI program.
+
+    :returns: exit code (0 on success, 1 on failure).
+    """
     parser = get_parser()
     args = parser.parse_args()
 
-    if args.uninstall:
-        uninstall_clang_tools(args.uninstall, args.tool, args.directory)
-    elif args.install:
-        version = Version(args.install)
-        if version.info != (0, 0, 0):
-            install_clang_tools(
-                version,
-                args.tool,
-                args.directory,
-                args.overwrite,
-                args.no_progress_bar,
-            )
-        else:
-            print(
-                f"{YELLOW}The version specified is not a semantic",
-                f"specification{RESET_COLOR}",
+    # ---- Legacy backward-compat path ----------------------------------
+    if args._legacy_uninstall or args._legacy_install:
+        if args._legacy_uninstall:
+            uninstall_clang_tools(
+                args._legacy_uninstall, args.tool, args.directory
             )
-    else:
+        if args._legacy_install:
+            version = Version(args._legacy_install)
+            if version.info != (0, 0, 0):
+                install_clang_tools(
+                    version,
+                    args.tool,
+                    args.directory,
+                    args.overwrite,
+                    args.no_progress_bar,
+                )
+            else:
+                print(
+                    f"{YELLOW}The version specified is not a semantic",
+                    f"specification{RESET_COLOR}",
+                    file=sys.stderr,
+                )
+                return 1
+        return 0
+
+    # ---- No subcommand, no legacy flags → nothing to do --------------
+    if args.command is None:
         print(
-            f"{YELLOW}Nothing to do because `--install` and `--uninstall`",
-            f"was not specified.{RESET_COLOR}",
+            f"{YELLOW}Nothing to do. Use 'install' or 'uninstall' subcommand,"
+            f" or --install/--uninstall flags.{RESET_COLOR}",
+            file=sys.stderr,
         )
         parser.print_help()
+        return 0
+
+    # ---- ``uninstall`` subcommand ------------------------------------
+    if args.command == "uninstall":
+        uninstall_clang_tools(args.version, args.tool, args.directory)
+        return 0
+
+    # ---- ``install`` subcommand --------------------------------------
+    if args.command == "install":
+        target: str = args.target
+        binary: bool = args.binary
+        wheel: bool = args.wheel
+
+        # safety: --binary and --wheel are mutually exclusive
+        if binary and wheel:
+            print(
+                f"{YELLOW}Error: --binary and --wheel are mutually"
+                f" exclusive{RESET_COLOR}",
+                file=sys.stderr,
+            )
+            return 1
+
+        # ---- Case: --wheel (target may be tool name or version) -----
+        if wheel:
+            if _is_version_like(target):
+                # ``clang-tools install 18 --wheel``
+                return _wheel_install(args.tool, target)
+            else:
+                # ``clang-tools install clang-format --wheel``
+                # Install the target as the tool (ignore default --tool)
+                return _wheel_install([target], args.explicit_version)
+
+        # ---- Case: --binary (target must be a version) --------------
+        if binary:
+            if not _is_version_like(target):
+                print(
+                    f"{YELLOW}Error: --binary requires a version number"
+                    f" (got '{target}'){RESET_COLOR}",
+                    file=sys.stderr,
+                )
+                return 1
+            version = Version(target)
+            if version.info != (0, 0, 0):
+                install_clang_tools(
+                    version,
+                    args.tool,
+                    args.directory,
+                    args.overwrite,
+                    args.no_progress_bar,
+                )
+                return 0
+            print(
+                f"{YELLOW}The version specified is not a semantic"
+                f" specification{RESET_COLOR}",
+                file=sys.stderr,
+            )
+            return 1
+
+        # ---- Auto-detect (no --binary or --wheel flag) --------------
+        if _is_version_like(target):
+            version = Version(target)
+            if version.info != (0, 0, 0):
+                # try binary first, fall back to wheel
+                try:
+                    install_clang_tools(
+                        version,
+                        args.tool,
+                        args.directory,
+                        args.overwrite,
+                        args.no_progress_bar,
+                    )
+                    return 0
+                except Exception as exc:
+                    print(
+                        f"{YELLOW}Binary install failed"
+                        f" ({exc}), falling back to"
+                        f" wheel...{RESET_COLOR}",
+                        file=sys.stderr,
+                    )
+                # fallback to wheel
+                return _wheel_install(args.tool, target)
+            else:
+                print(
+                    f"{YELLOW}The version specified is not a semantic"
+                    f" specification{RESET_COLOR}",
+                    file=sys.stderr,
+                )
+                return 1
+        else:
+            # target is a tool name → install via wheel
+            if target not in WHEEL_TOOLS:
+                print(
+                    f"{YELLOW}Unknown target '{target}'. Expected a"
+                    f" version number or one of: "
+                    f"{', '.join(sorted(WHEEL_TOOLS))}{RESET_COLOR}",
+                    file=sys.stderr,
+                )
+                return 1
+            return _wheel_install([target], args.explicit_version)
+
+    return 0  # unreachable
 
 
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main())