Add config.min_version to cookieplone-config.json for version gating

Closes #180

Author: ericof

cookieplone/cli/__init__.py

@@ -9,6 +9,7 @@
 from cookieplone._types import GenerateConfig
 from cookieplone.exceptions import GeneratorException
 from cookieplone.exceptions import PreFlightException
+from cookieplone.exceptions import VersionTooOldException
 from cookieplone.generator import generate
 from cookieplone.logger import configure_logger
 from cookieplone.logger import logger
@@ -124,7 +125,6 @@ def prompt_for_template(base_path: Path, all_: bool = False) -> t.CookieploneTem
     groups = get_template_groups(base_path, all_)
     if groups:
         group = prompt_for_group(groups)
-        console.clear_screen()
         templates = group.templates
     else:
         templates = get_template_options(base_path, all_)
@@ -303,10 +303,7 @@ def cli(
     )
     try:
         generate(gen_config)
-    except GeneratorException as exc:
-        console.error(exc.message)
-        raise typer.Exit(1)  # noQA:B904
-    except PreFlightException as exc:
+    except (GeneratorException, PreFlightException, VersionTooOldException) as exc:
         console.error(exc.message)
         raise typer.Exit(1)  # noQA:B904
     except Exception as exc:

cookieplone/config/schemas/repository_config.schema.json

@@ -50,6 +50,10 @@
         "renderer": {
           "type": "string",
           "minLength": 1
+        },
+        "min_version": {
+          "type": "string",
+          "minLength": 1
         }
       },
       "additionalProperties": false

cookieplone/exceptions.py

@@ -88,3 +88,8 @@ class FailedHookException(exc.FailedHookException):
 
 class InvalidConfiguration(exc.InvalidConfiguration):
     """Raised when a configuration is invalid."""
+
+
+class VersionTooOldException(CookieploneException):
+    """Raised when the installed cookieplone version is older than the
+    repository's ``config.min_version`` requirement."""

cookieplone/repository.py

@@ -9,6 +9,8 @@
 from cookieplone.exceptions import PreFlightException
 from cookieplone.exceptions import RepositoryException
 from cookieplone.exceptions import RepositoryNotFound
+from cookieplone.exceptions import VersionTooOldException
+from packaging.version import Version
 from pathlib import Path
 from typing import Any
 
@@ -359,6 +361,28 @@ def _run_pre_hook(
     return repo_dir
 
 
+def _check_min_version(config_section: dict[str, Any]) -> None:
+    """Raise if the installed cookieplone is older than ``config.min_version``.
+
+    :param config_section: The ``config`` dict from ``cookieplone-config.json``.
+    :raises VersionTooOldException: When the installed version is too old.
+    """
+    min_version_str = config_section.get("min_version", "")
+    if not min_version_str:
+        return
+    from cookieplone import __version__
+
+    installed = Version(__version__)
+    required = Version(min_version_str)
+    if installed < required:
+        msg = (
+            f"This template requires cookieplone >= {required}, "
+            f"but you have {installed} installed.\n"
+            f"Please upgrade:  uvx --no-cache cookieplone@{required}"
+        )
+        raise VersionTooOldException(msg)
+
+
 def get_repository(
     repository: str | Path,
     template_name: str,
@@ -434,6 +458,7 @@ def get_repository(
             repo_config_section = repo_config.get("config", {})
             global_versions = repo_config_section.get("versions", {})
             renderer = repo_config_section.get("renderer", "")
+            _check_min_version(repo_config_section)
         except RuntimeError:
             pass
 

cookieplone/utils/console.py

@@ -5,6 +5,7 @@
 from .internal import version_info
 from collections.abc import Sequence
 from contextlib import contextmanager
+from cookieplone import __version__ as cookieplone_version
 from cookieplone import _types as t
 from cookieplone.settings import QUIET_MODE_VAR
 from pathlib import Path
@@ -17,6 +18,7 @@
 from rich.table import Table
 from rich.text import Text
 from textwrap import dedent
+from typing import Any
 
 import os
 
@@ -95,39 +97,44 @@ def print(msg: str, style: str = "", color: str = ""):  # noQA:A001
     _print(f"{tag_open}{escape(msg)}{tag_close}")
 
 
-def print_plone_banner():
+def print_plone_banner() -> None:
     """Print Plone banner."""
     style: str = "bold"
     color: str = "blue"
     banner = choose_banner()
     print(banner, style, color)
 
 
-def info(msg: str):
+def info(msg: str) -> None:
+    """Print an informational message in bold white."""
     style: str = "bold"
     color: str = "white"
     print(msg, style, color)
 
 
-def success(msg: str):
+def success(msg: str) -> None:
+    """Print a success message in bold green."""
     style: str = "bold"
     color: str = "green"
     print(msg, style, color)
 
 
-def error(msg: str):
+def error(msg: str) -> None:
+    """Print an error message in bold red."""
     style: str = "bold"
     color: str = "red"
     print(msg, style, color)
 
 
-def warning(msg: str):
+def warning(msg: str) -> None:
+    """Print a warning message in bold yellow."""
     style: str = "bold"
     color: str = "yellow"
     print(msg, style, color)
 
 
-def panel(title: str, msg: str = "", subtitle: str = "", url: str = ""):
+def panel(title: str, msg: str = "", subtitle: str = "", url: str = "") -> None:
+    """Print a Rich panel with an optional subtitle and clickable URL."""
     msg = dedent(msg)
     if url:
         msg = f"{msg}\n[link]{url}[/link]"
@@ -143,9 +150,16 @@ def panel(title: str, msg: str = "", subtitle: str = "", url: str = ""):
 def create_table(
     columns: list[dict] | None = None,
     rows: Sequence[Sequence[str]] | None = None,
-    **kwargs,
+    **kwargs: Any,
 ) -> Table:
-    """Create table."""
+    """Create a Rich :class:`~rich.table.Table` from column definitions and row data.
+
+    :param columns: List of dicts, each containing a ``title`` key and any
+        extra keyword arguments accepted by :meth:`~rich.table.Table.add_column`.
+    :param rows: Sequence of row tuples passed to :meth:`~rich.table.Table.add_row`.
+    :param kwargs: Forwarded to the :class:`~rich.table.Table` constructor.
+    :returns: A fully populated :class:`~rich.table.Table`.
+    """
     table = Table(**kwargs)
     for column in columns:
         col_title = column.pop("title", "")
@@ -188,7 +202,19 @@ def list_available_groups(
 def welcome_screen(
     templates: dict[str, t.CookieploneTemplate] | None = None,
     groups: dict[str, t.CookieploneTemplateGroup] | None = None,
-):
+) -> None:
+    """Display the Cookieplone welcome screen with an optional template or group list.
+
+    Clears the terminal, renders the Plone banner, and — when provided —
+    appends a panel listing either template *groups* (category selection)
+    or individual *templates* (template selection).
+
+    :param templates: Templates to list.  Mutually exclusive with *groups*.
+    :param groups: Template groups to list.  Takes precedence over *templates*.
+    """
+    # Always clear the screen, even if we're not printing the banner,
+    # to ensure a clean start.
+    clear_screen()
     banner = choose_banner()
     items = [
         Align.center(f"[bold blue]{banner}[/bold blue]"),
@@ -205,19 +231,26 @@ def welcome_screen(
                 title_align="left",
             )
         )
+    panel_title = f"cookieplone ({cookieplone_version})"
     panel = Panel(
         Group(*items),
-        title="cookieplone",
+        title=panel_title,
     )
     base_print(panel)
 
 
-def version_screen():
+def version_screen() -> None:
     """Print version information."""
     base_print(version_info())
 
 
-def info_screen(repository: str | Path, passwd: str, tag: str):
+def info_screen(repository: str | Path, passwd: str, tag: str) -> None:
+    """Print a detailed information panel about the current Cookieplone installation.
+
+    :param repository: Template repository URL or local path.
+    :param passwd: Repository password (may be empty).
+    :param tag: Git tag or branch used for the repository.
+    """
     info = cookieplone_info(repository, passwd, tag)
     title = info["title"]
     subtitle = info["subtitle"]

docs/src/reference/repository-config.md

@@ -130,6 +130,7 @@ Global configuration shared across all templates in the repository.
 ```json
 {
   "config": {
+    "min_version": "2.0.0a2",
     "versions": {
       "gha_version_checkout": "v6",
       "gha_version_setup_node": "v4",
@@ -174,6 +175,29 @@ If the configured renderer name is not registered with `tui_forms`, Cookieplone
 
 See {doc}`/reference/environment-variables` for the corresponding environment variable.
 
+### `config.min_version`
+
+Declares the minimum Cookieplone version required by the templates in this repository.
+The value must be a valid [PEP 440](https://peps.python.org/pep-0440/) version string, including pre-release versions such as `2.0.0a1`.
+
+```json
+{
+  "config": {
+    "min_version": "2.0.0a2"
+  }
+}
+```
+
+When present, Cookieplone compares the installed version against this value before any generation begins.
+If the installed version is older, generation stops with an actionable error message:
+
+```text
+This template requires cookieplone >= 2.0.0a2, but you have 1.3.0 installed.
+Please upgrade:  uvx --no-cache cookieplone@2.0.0a2
+```
+
+When the key is absent or empty, no version check is performed (backwards compatible with existing repositories).
+
 (repo-extends)=
 ## `extends`
 
@@ -261,6 +285,7 @@ Cookieplone checks for `cookieplone-config.json` first, then falls back to `cook
     }
   },
   "config": {
+    "min_version": "2.0.0a2",
     "versions": {
       "gha_version_checkout": "v6",
       "frontend_pnpm": "10.20.0"

news/180.feature

@@ -0,0 +1 @@
+Added `config.min_version` to `cookieplone-config.json` so template repositories can declare the minimum Cookieplone version they require. @ericof

tests/test_repository.py

@@ -1,6 +1,8 @@
 from cookiecutter.exceptions import FailedHookException
 from cookieplone import repository
 from cookieplone.exceptions import PreFlightException
+from cookieplone.exceptions import VersionTooOldException
+from cookieplone.repository import _check_min_version
 from pathlib import Path
 
 import json
@@ -127,3 +129,85 @@ def test_no_repo_config_means_empty_renderer(self, tmp_path, monkeypatch):
             template_path="",
         )
         assert info.renderer == ""
+
+
+class TestCheckMinVersion:
+    """Tests for _check_min_version."""
+
+    def test_no_min_version_key(self):
+        """No-op when min_version is absent."""
+        _check_min_version({})
+
+    def test_empty_min_version(self):
+        """No-op when min_version is an empty string."""
+        _check_min_version({"min_version": ""})
+
+    def test_version_satisfied(self, monkeypatch):
+        """No error when installed version meets the requirement."""
+        monkeypatch.setattr("cookieplone.__version__", "2.1.0")
+        _check_min_version({"min_version": "2.0.0"})
+
+    def test_version_exact_match(self, monkeypatch):
+        """No error when installed version equals min_version."""
+        monkeypatch.setattr("cookieplone.__version__", "2.0.0")
+        _check_min_version({"min_version": "2.0.0"})
+
+    def test_version_too_old(self, monkeypatch):
+        """Raises VersionTooOldException when installed version is older."""
+        monkeypatch.setattr("cookieplone.__version__", "1.3.0")
+        with pytest.raises(VersionTooOldException, match=r"cookieplone >= 2\.0\.0"):
+            _check_min_version({"min_version": "2.0.0"})
+
+    def test_error_message_includes_versions(self, monkeypatch):
+        """Error message includes both the required and installed versions."""
+        monkeypatch.setattr("cookieplone.__version__", "1.5.0")
+        with pytest.raises(VersionTooOldException, match=r"1\.5\.0") as exc_info:
+            _check_min_version({"min_version": "2.0.0"})
+        assert "uvx --no-cache cookieplone@2.0.0" in exc_info.value.message
+
+    def test_prerelease_satisfied(self, monkeypatch):
+        """Pre-release installed version satisfies a pre-release requirement."""
+        monkeypatch.setattr("cookieplone.__version__", "2.0.0a2")
+        _check_min_version({"min_version": "2.0.0a1"})
+
+    def test_prerelease_too_old(self, monkeypatch):
+        """Pre-release installed version fails against a newer pre-release."""
+        monkeypatch.setattr("cookieplone.__version__", "2.0.0a1")
+        with pytest.raises(VersionTooOldException):
+            _check_min_version({"min_version": "2.0.0a2"})
+
+    def test_dev_version_satisfies_prerelease(self, monkeypatch):
+        """Dev version (e.g. 2.0.0a2.dev0) satisfies an older pre-release."""
+        monkeypatch.setattr("cookieplone.__version__", "2.0.0a2.dev0")
+        _check_min_version({"min_version": "2.0.0a1"})
+
+    def test_get_repository_raises_on_min_version(self, tmp_path, monkeypatch):
+        """get_repository raises VersionTooOldException when min_version fails."""
+        repo_dir = tmp_path / "repo"
+        repo_dir.mkdir()
+        _write_repo_config(repo_dir, {"min_version": "99.0.0"})
+        monkeypatch.setattr(
+            repository,
+            "get_user_config",
+            lambda **_: {
+                "abbreviations": {},
+                "cookiecutters_dir": str(repo_dir.parent),
+                "replay_dir": str(repo_dir.parent),
+            },
+        )
+        monkeypatch.setattr(
+            repository,
+            "determine_repo_dir",
+            lambda **_: (repo_dir, False),
+        )
+        monkeypatch.setattr(
+            repository,
+            "_run_pre_hook",
+            lambda base, repo, accept_hooks: repo,
+        )
+        with pytest.raises(VersionTooOldException, match=r"cookieplone >= 99\.0\.0"):
+            repository.get_repository(
+                repository=str(repo_dir),
+                template_name="project",
+                template_path="",
+            )