add stable repository element filtering

Author: slashburygin

.gitignore

@@ -139,3 +139,4 @@ docs/source/*.png
 pgdata/
 
 .tasks
+graphify-out

docs/openapi/openapi_user.yaml

@@ -28617,6 +28617,14 @@ paths:
             example: 00000000-0000-0000-0000-000000000000
             format: uuid
             nullable: true
+        - name: latest
+          in: query
+          schema:
+            type: string
+            enum:
+              - "true"
+            example: "true"
+            description: Return only the latest version for each unique element name
       responses:
         '200':
           description: RepoElement_Filter

exordos_core/repo/dm/models.py

@@ -20,6 +20,7 @@
 import typing as tp
 from urllib.parse import urljoin
 
+from packaging import version as packaging_version
 from restalchemy.dm import filters as ra_filters
 from restalchemy.dm import models
 from restalchemy.dm import properties
@@ -28,6 +29,7 @@
 from restalchemy.dm import types_dynamic
 from restalchemy.storage.sql import orm
 
+from exordos_core.common import exceptions as common_exc
 from exordos_core.common import utils
 from exordos_core.repo import constants as rc
 
@@ -37,6 +39,13 @@
     from exordos_core.repo.drivers.base import AbstractProxyRepoDriver
 
 
+def is_stable_version(version: str) -> bool:
+    try:
+        return not packaging_version.parse(version).is_prerelease
+    except packaging_version.InvalidVersion:
+        return False
+
+
 class SyncMode(str, enum.Enum):
     COPY = "copy"
     LAZY = "lazy"
@@ -213,10 +222,10 @@ def load_driver(self) -> "AbstractProxyRepoDriver":
         instantiate them with the current repository. If a driver is
         successfully loaded, it is stored in a cache for faster access.
 
-        If no driver is found, a ValueError is raised.
+        If no driver is found, a ValidateException is raised.
 
         :return: The loaded driver instance
-        :raises ValueError: If no driver is found
+        :raises ValidateException: If no driver is found
         """
         driver_key = str(self.driver_spec)
 
@@ -234,7 +243,9 @@ def load_driver(self) -> "AbstractProxyRepoDriver":
                 # Just try another driver
                 pass
 
-        raise ValueError(f"Driver for spec '{self.driver_spec}' not found")
+        raise common_exc.ValidateException(
+            err=f"Driver for spec '{self.driver_spec}' not found"
+        )
 
     def iter_elements_in_inventory(
         self, inventory: dict | None = None
@@ -309,13 +320,15 @@ def upload(
             Created RepoElement instance
 
         Raises:
-            ValueError: If upload is not supported by driver
+            ValidateException: If upload is not supported by driver
         """
         driver = self.load_driver()
 
         # Check if driver supports upload
         if not driver.can_upload_element(element_name, element_version):
-            raise ValueError("Upload is not supported by this repository driver")
+            raise common_exc.ValidateException(
+                err="Upload is not supported by this repository driver"
+            )
 
         # Create element
         element = RepoElement(
@@ -418,6 +431,10 @@ class RepoElement(
         default=None,
     )
 
+    @property
+    def is_stable(self) -> bool:
+        return is_stable_version(self.version)
+
     @property
     def dependencies(self) -> dict[str, dict[str, str]]:
         """Compute dependencies from manifest requirements.
@@ -466,7 +483,7 @@ def dependencies(self) -> dict[str, dict[str, str]]:
 
     def install(self) -> "RepoElement":
         if self.installation_state != RepoElementInstallationState.UNINSTALLED:
-            raise ValueError("Element must be uninstalled")
+            raise common_exc.ValidateException(err="Element must be uninstalled")
 
         # Check there is no installed element with the same name
         existing = RepoElement.objects.get_all(
@@ -478,15 +495,17 @@ def install(self) -> "RepoElement":
             }
         )
         if existing:
-            raise ValueError("Element with the same name is already installed")
+            raise common_exc.ValidateException(
+                err="Element with the same name is already installed"
+            )
 
         self.installation_state = RepoElementInstallationState.INSTALLED.value
         self.update()
         return self
 
     def uninstall(self) -> "RepoElement":
         if self.installation_state != RepoElementInstallationState.INSTALLED:
-            raise ValueError("Element must be installed")
+            raise common_exc.ValidateException(err="Element must be installed")
 
         # Check that no other elements depend on this one. The dependency
         # bindings table records transitive dependencies, so if any record
@@ -496,8 +515,8 @@ def uninstall(self) -> "RepoElement":
             filters={"depends_on": ra_filters.EQ(self.uuid)}
         )
         if dependents:
-            raise ValueError(
-                "Element cannot be uninstalled: other elements depend on it"
+            raise common_exc.ValidateException(
+                err="Element cannot be uninstalled: other elements depend on it"
             )
 
         self.installation_state = RepoElementInstallationState.UNINSTALLED.value
@@ -516,7 +535,9 @@ def uninstall(self) -> "RepoElement":
 
     def upgrade(self, target: str) -> "RepoElement":
         if self.element is None:
-            raise ValueError("Element must be installed to upgrade")
+            raise common_exc.ValidateException(
+                err="Element must be installed to upgrade"
+            )
 
         target_element = RepoElement.objects.get_one(
             filters={
@@ -528,7 +549,7 @@ def upgrade(self, target: str) -> "RepoElement":
             target_element.installation_state
             != RepoElementInstallationState.UNINSTALLED
         ):
-            raise ValueError("Target element must be uninstalled")
+            raise common_exc.ValidateException(err="Target element must be uninstalled")
         runtime_element = self.element
         self.installation_state = RepoElementInstallationState.UNINSTALLED.value
         self.update()
@@ -545,20 +566,20 @@ def edit(self, manifest: dict) -> "RepoElement":
             manifest: New manifest dict
 
         Raises:
-            ValueError: If manifest name or version does not match element name/version
+            ValidateException: If manifest name or version does not match element name/version
         """
         # Validate that name and version in manifest match the element
         manifest_name = manifest.get("name")
         manifest_version = manifest.get("version")
 
         if manifest_name != self.name:
-            raise ValueError(
-                f"Manifest name '{manifest_name}' does not match element name '{self.name}'"
+            raise common_exc.ValidateException(
+                err=f"Manifest name '{manifest_name}' does not match element name '{self.name}'"
             )
 
         if manifest_version != self.version:
-            raise ValueError(
-                f"Manifest version '{manifest_version}' does not match element version '{self.version}'"
+            raise common_exc.ValidateException(
+                err=f"Manifest version '{manifest_version}' does not match element version '{self.version}'"
             )
 
         self.manifest = manifest

exordos_core/tests/functional/restapi/repo/__init__.py

@@ -0,0 +1,15 @@
+#    Copyright 2026 Genesis Corporation.
+#
+#    All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.