Enhance ISO selection logic and update documentation for improved clarity and usage instructions

tests/test_domain.py

@@ -1,4 +1,9 @@
-from pve_vm_setup.domain import build_create_payload, select_latest_nixos_iso, validate_all_steps
+from pve_vm_setup.domain import (
+    build_create_payload,
+    select_latest_nixos_iso,
+    select_preferred_iso,
+    validate_all_steps,
+)
 from pve_vm_setup.models.workflow import VmConfig
 from pve_vm_setup.settings import AppSettings
 
@@ -15,6 +20,32 @@ def test_select_latest_nixos_iso_prefers_latest_year_month() -> None:
     assert choice == "cephfs:iso/nixos-minimal-25.05.ffffeeee-x86_64-linux.iso"
 
 
+def test_select_preferred_iso_uses_glob_selector_when_configured() -> None:
+    choice = select_preferred_iso(
+        [
+            "cephfs:iso/debian-12.iso",
+            "cephfs:iso/nixos-minimal-24.11.1234abcd-x86_64-linux.iso",
+            "cephfs:iso/ubuntu-24.04.iso",
+        ],
+        "*ubuntu*",
+    )
+
+    assert choice == "cephfs:iso/ubuntu-24.04.iso"
+
+
+def test_select_preferred_iso_uses_regex_selector_when_prefixed() -> None:
+    choice = select_preferred_iso(
+        [
+            "cephfs:iso/debian-12.iso",
+            "cephfs:iso/nixos-minimal-24.11.1234abcd-x86_64-linux.iso",
+            "cephfs:iso/nixos-graphical-25.05.iso",
+        ],
+        r"regex:nixos-graphical-\d{2}\.\d{2}\.iso$",
+    )
+
+    assert choice == "cephfs:iso/nixos-graphical-25.05.iso"
+
+
 def test_build_create_payload_applies_safety_name_tag_and_key_settings() -> None:
     settings = AppSettings.from_env(
         {

tests/test_settings.py

@@ -20,6 +20,7 @@ def test_settings_load_defaults_and_normalize_api_base() -> None:
     assert settings.proxmox_api_base == "/api2/json"
     assert settings.proxmox_verify_tls is False
     assert settings.request_timeout_seconds == 15
+    assert settings.default_iso_selector is None
     assert settings.effective_username == "root@pam"
     assert settings.safety_policy.prevent_create is False
     assert settings.safety_policy.enable_test_mode is False
@@ -54,3 +55,13 @@ def test_settings_allow_create_by_default_when_prevent_flag_is_unset() -> None:
 
     assert settings.safety_policy.prevent_create is False
     assert settings.safety_policy.allow_create is True
+
+
+def test_settings_reject_invalid_default_iso_regex_selector() -> None:
+    with pytest.raises(SettingsError):
+        AppSettings.from_env(
+            {
+                "PROXMOX_DEFAULT_ISO_SELECTOR": "regex:[unterminated",
+            },
+            load_dotenv_file=False,
+        )