Refactor and enhance collider pkg subcommands for package management

- Introduced a new `pkg` subcommand to encapsulate package-related operations, including `install`, `search`, `push`, and `policy`.
- Updated the README and documentation to reflect changes in command usage, emphasizing the new `collider pkg` prefix for commands.
- Refactored existing `Install`, `Push`, `Search`, and `Policy` subcommands to reside under the `pkg` namespace, improving organization and clarity.
- Enhanced error handling and validation across subcommands to ensure robust package management.
- Added tests for the new `pkg` subcommand structure, ensuring comprehensive coverage for package operations.

Author: MaxandreOgeret

README.md

@@ -59,14 +59,14 @@ collider setup -- --buildtype=debug
 3) Push the project to a repository:
 
 ```bash
-collider push local
+collider pkg push local
 ```
 
 The package name and version come from Meson introspection in the build directory
 (default: `collider-build`). Collider generates the source archive and wrap file
 and stores them in the repository. Filesystem repositories must have `publish_url`
 configured so Collider can generate archive URLs. To attach a patch archive for
-an external source, pass `--patch-archive`. Create the patch with `collider patch` from a modified source tree, then run `collider push` from the **unmodified** tree and pass the patch archive (tar.xz) with `--patch-archive` so the repository stores base source plus patch.
+an external source, pass `--patch-archive`. Create the patch with `collider patch` from a modified source tree, then run `collider pkg push` from the **unmodified** tree and pass the patch archive (tar.xz) with `--patch-archive` so the repository stores base source plus patch.
 
 Collider also generates the wrap `[provide]` entry as `<name> = <name>_dep`
 (with `-` and `.` replaced by `_`). Ensure your Meson project exposes that
@@ -75,8 +75,8 @@ dependency variable for `dependency()` fallbacks.
 4) Install a dependency (online or offline):
 
 ```bash
-collider install my-lib
-collider install --offline my-lib
+collider pkg install my-lib
+collider pkg install --offline my-lib
 ```
 
 ## Configuration
@@ -105,7 +105,7 @@ Filesystem repositories are directories containing a wrap layout and `releases.j
 Wraps are stored under `<name>_<version>/<name>.wrap` and `releases.json` is generated at the root.
 Collider stores the generated source archive (and optional patch archive) under
 `archives/<name>_<version>/`.
-Filesystem repositories require `publish_url`. Set it to the HTTPS, HTTP, or `file://` base where the repository is served; `collider push`
+Filesystem repositories require `publish_url`. Set it to the HTTPS, HTTP, or `file://` base where the repository is served; `collider pkg push`
 uses it to rewrite archive URLs without requiring per-command flags.
 
 When served at `publish_url`, the expected URLs are:
@@ -124,9 +124,9 @@ in `config.json` that points to the server base URL.
 ## Repository workflow
 
 ```bash
-collider push local
-collider search '^my-lib$' --repository local --version '>=1.0.0'
-collider install my-lib
+collider pkg push local
+collider pkg search '^my-lib$' --repository local --version '>=1.0.0'
+collider pkg install my-lib
 ```
 
 ## Offline caching
@@ -159,7 +159,7 @@ Use `-v` or `--verbose` for debug logging.
 - `collider patch [--builddir PATH] [--base REV] [--output PATH] [--list] [--include-uncommitted / --no-include-uncommitted]`  
   Create a patch archive (tar.xz) from Git changes for use with Meson wrap `patch_url`. Reads project name and version from Meson introspection. Default output: `dist/<name>_<version>_patch.tar.xz`. Requires Git and an existing Meson build directory.
 
-- `collider push <repo> [--builddir PATH] [--patch-archive PATH] [--push-token-env VAR]`  
+- `collider pkg push <repo> [--builddir PATH] [--patch-archive PATH] [--push-token-env VAR]`  
   Generate a wrap and source archive, then publish it.
   For filesystem repositories, Collider writes directly to disk.
   For wrap repositories, Collider calls `POST /v2/_collider/v1/push` and reads bearer token from
@@ -171,16 +171,16 @@ Use `-v` or `--verbose` for debug logging.
   For non-filesystem repositories, `--publish-url` is ignored.
   If another repository already uses the same URL, Collider logs a warning but still adds the entry.
 
-- `collider search <pattern> [--repository NAME ...] [--version SPEC]`  
+- `collider pkg search <pattern> [--repository NAME ...] [--version SPEC]`  
   Search repositories.
 
-- `collider policy <name> [--repository NAME ...]`  
+- `collider pkg policy <name> [--repository NAME ...]`  
   Show versions, origins, and cache status.
 
 - `collider status`  
   Show collider-managed dependencies and local wrap status.
 
-- `collider install <name> [--offline]`  
+- `collider pkg install <name> [--offline]`  
   Install a wrap package into `subprojects/`.
 
 - `collider serve <path> [--host HOST] [--port PORT] [--push-token TOKEN] [--push-token-env VAR] [--publish-url URL]`  

collider/subcommand/Install.py collider/subcommand/pkg/Install.pycollider/subcommand/Install.py renamed to collider/subcommand/pkg/Install.py

@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 MOG Robotics OÜ
+
+"""Package operations; subcommands are discovered from this package."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from collider.Context import Context
+from collider.log import logger
+from collider.subcommand.SubcommandInterface import SubcommandInterface
+from collider.utils import core
+from collider.utils.compat import override
+
+
+Interface = SubcommandInterface
+
+# Mutable holder so we can cache without a global statement (Pylint W0603).
+_PKG_SUBCOMMANDS_HOLDER: list[dict[str, type[SubcommandInterface]] | None] = [None]
+
+
+def _get_pkg_subcommands() -> dict[str, type[SubcommandInterface]]:
+    """
+    Discover nested pkg subcommands once; reused in register() and execute().
+    :return: Map of subcommand name to implementation class.
+    """
+    if _PKG_SUBCOMMANDS_HOLDER[0] is None:
+        pkg_module = sys.modules[__name__]
+        _PKG_SUBCOMMANDS_HOLDER[0] = core.discover_plugins(pkg_module)
+    return _PKG_SUBCOMMANDS_HOLDER[0]
+
+
+def _pkg_help_summary() -> str:
+    """Build the help line from discovered subcommand names."""
+    names = sorted(_get_pkg_subcommands().keys())
+    return 'Package operations: ' + ', '.join(names) + '.'
+
+
+class Pkg(SubcommandInterface):
+    """Package operations; subcommands are discovered from this package."""
+
+    @staticmethod
+    def help() -> str:
+        """Short help string surfaced by the CLI."""
+        return _pkg_help_summary()
+
+    @staticmethod
+    def epilog() -> str | None:
+        """Optional examples appended to the help output."""
+        lines = ['Examples:']
+        for name in sorted(_get_pkg_subcommands().keys()):
+            lines.append(f'  ‣ collider pkg {name} <args>')
+        return '\n'.join(lines) + '\n'
+
+    @staticmethod
+    def register(parser: argparse.ArgumentParser) -> None:
+        """Keep argparse wiring co-located with the command."""
+        subparsers = parser.add_subparsers(dest='pkg_subcommand', required=True)
+        for name, subcommand_class in _get_pkg_subcommands().items():
+            subparser = subparsers.add_parser(
+                name,
+                help=subcommand_class.help(),
+                description=subcommand_class.help(),
+                epilog=subcommand_class.epilog(),
+            )
+            subcommand_class.register(subparser)
+            subparser.set_defaults(pkg_action=name)
+
+    @override
+    def execute(self) -> int:
+        """Run the pkg command.
+        :return: Exit code.
+        """
+        action = getattr(self.args, 'pkg_action', None)
+        subcommands = _get_pkg_subcommands()
+        if action is None or action not in subcommands:
+            logger.critical(f'Unknown pkg subcommand: {action}')
+            return os.EX_USAGE
+        subcommand_class = subcommands[action]
+        return subcommand_class(self.args, self.context).execute()
+
+
+__all__ = ['Interface', 'Pkg']

collider/subcommand/Policy.py collider/subcommand/pkg/Policy.pycollider/subcommand/Policy.py renamed to collider/subcommand/pkg/Policy.py

@@ -46,7 +46,7 @@ Patch archives may use any extension; `collider patch` produces a `.tar.xz` by d
 
 ### Wrap Repository (Remote)
 - WrapDB-compatible endpoint backed by `releases.json` and wraps.
-- Used by `collider install` and `collider search`.
+- Used by `collider pkg install` and `collider pkg search`.
 - HTTPS preferred; HTTP is allowed with a warning.
 
 **Why**
@@ -81,7 +81,7 @@ Patch archives may use any extension; `collider patch` produces a `.tar.xz` by d
 - Generates a wrap file that points at the repository `publish_url`.
 - Optional: stage a patch archive with `--patch-archive`.
 - Filesystem repos use `publish_url` from `config.json` to build archive URLs.
-- Wrap repos can be pushed through `POST /v2/_collider/v1/push`; `collider push` reads bearer token from env (`COLLIDER_PUSH_TOKEN` by default).
+- Wrap repos can be pushed through `POST /v2/_collider/v1/push`; `collider pkg push` reads bearer token from env (`COLLIDER_PUSH_TOKEN` by default).
 - Auto-generates `[provide]` using `<name>` and a sanitized `<name>_dep` variable.
 
 **Why**
@@ -94,7 +94,7 @@ Patch archives may use any extension; `collider patch` produces a `.tar.xz` by d
 - Uses Meson introspection (build directory, default `collider-build`) for package name and version.
 - Output default: `dist/<name>_<version>_patch.tar.xz`. Requires Git and an existing Meson build.
 - Options: `--base` (revision to diff against), `--include-uncommitted` / `--no-include-uncommitted`, `--output`, `--list` (dry-run list of files).
-- **Typical workflow for patched upstreams**: (1) Modify the source tree as needed, (2) Run `collider patch` to produce the patch archive (tar.xz), (3) Revert the tree to the unmodified upstream (or use a clean copy), (4) Run `collider push <repo> --patch-archive <path-to-patch.tar.xz>` so the repository stores the base source archive plus the patch. Consumers then get base + patch on install.
+- **Typical workflow for patched upstreams**: (1) Modify the source tree as needed, (2) Run `collider patch` to produce the patch archive (tar.xz), (3) Revert the tree to the unmodified upstream (or use a clean copy), (4) Run `collider pkg push <repo> --patch-archive <path-to-patch.tar.xz>` so the repository stores the base source archive plus the patch. Consumers then get base + patch on install.
 
 ### `repo add`
 - Adds a repository entry to `config.json`.

collider/subcommand/Push.py collider/subcommand/pkg/Push.pycollider/subcommand/Push.py renamed to collider/subcommand/pkg/Push.py

@@ -42,7 +42,7 @@ When push auth is configured, Collider also exposes:
   - Requires `Authorization: Bearer <token>`.
   - This is a minimal in-process auth mode.
 
-`collider push <wrap-repo-name>` can use this endpoint automatically and reads the token from
+`collider pkg push <wrap-repo-name>` can use this endpoint automatically and reads the token from
 `$COLLIDER_PUSH_TOKEN` by default (`--push-token-env` can override variable name).
 
 `<base>` is the server root used by `collider serve`.

collider/subcommand/Search.py collider/subcommand/pkg/Search.pycollider/subcommand/Search.py renamed to collider/subcommand/pkg/Search.py

@@ -10,10 +10,7 @@
 class Subcommand(str, Enum):
     INIT = 'init'
     SETUP = 'setup'
-    PUSH = 'push'
-    SEARCH = 'search'
-    POLICY = 'policy'
-    INSTALL = 'install'
+    PKG = 'pkg'
     STATUS = 'status'
     REPO = 'repo'
 

collider/subcommand/pkg/__init__.py

@@ -19,7 +19,7 @@
 from collider.Package import WrapPackage
 from collider.repository.entries import RepoPackageEntry
 from collider.repository.implementation.RepositoryInterface import RepositoryInterface
-from collider.subcommand.Install import Install
+from collider.subcommand.pkg.Install import Install
 from collider.utils.packaging.Dependency import Dependency, DependencySource
 from collider.utils.packaging.PackageType import PackageType
 from collider.utils.packaging.repo_key import make_repo_key
@@ -86,7 +86,7 @@ def test_install_wrap_success(tmp_path: Path, monkeypatch) -> None:
     cwd = os.getcwd()
     try:
         os.chdir(tmp_path)
-        with patch('collider.subcommand.Install.search_packages', return_value=all_matches):
+        with patch('collider.subcommand.pkg.Install.search_packages', return_value=all_matches):
             assert cmd.execute() == os.EX_OK
     finally:
         os.chdir(cwd)
@@ -125,7 +125,7 @@ def test_install_offline_uses_cache(tmp_path: Path, caplog: pytest.LogCaptureFix
     cwd = os.getcwd()
     try:
         os.chdir(tmp_path)
-        with patch('collider.subcommand.Install.search_packages', return_value=all_matches):
+        with patch('collider.subcommand.pkg.Install.search_packages', return_value=all_matches):
             assert cmd.execute() == os.EX_OK
     finally:
         os.chdir(cwd)
@@ -155,7 +155,7 @@ def test_install_offline_remote_missing_cache(tmp_path: Path) -> None:
     cwd = os.getcwd()
     try:
         os.chdir(tmp_path)
-        with patch('collider.subcommand.Install.search_packages', return_value=all_matches):
+        with patch('collider.subcommand.pkg.Install.search_packages', return_value=all_matches):
             assert cmd.execute() == os.EX_IOERR
     finally:
         os.chdir(cwd)
@@ -182,7 +182,7 @@ def test_install_offline_local_missing_archive(tmp_path: Path) -> None:
     cwd = os.getcwd()
     try:
         os.chdir(tmp_path)
-        with patch('collider.subcommand.Install.search_packages', return_value=all_matches):
+        with patch('collider.subcommand.pkg.Install.search_packages', return_value=all_matches):
             assert cmd.execute() == os.EX_IOERR
     finally:
         os.chdir(cwd)
@@ -214,7 +214,7 @@ def test_install_updates_dependency_version(tmp_path: Path, monkeypatch) -> None
     cwd = os.getcwd()
     try:
         os.chdir(tmp_path)
-        with patch('collider.subcommand.Install.search_packages', return_value=all_matches):
+        with patch('collider.subcommand.pkg.Install.search_packages', return_value=all_matches):
             assert cmd.execute() == os.EX_OK
     finally:
         os.chdir(cwd)
@@ -253,7 +253,7 @@ def test_install_fails_on_existing_different_wrap(tmp_path: Path, monkeypatch) -
     cwd = os.getcwd()
     try:
         os.chdir(tmp_path)
-        with patch('collider.subcommand.Install.search_packages', return_value=all_matches):
+        with patch('collider.subcommand.pkg.Install.search_packages', return_value=all_matches):
             assert cmd.execute() == os.EX_IOERR
     finally:
         os.chdir(cwd)