donna 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

donna/primitives/artifacts/specification.py

@@ -1,8 +1,10 @@
 from typing import TYPE_CHECKING, ClassVar
 
+import pydantic
+
 from donna.machine.artifacts import ArtifactSectionConfig
 from donna.machine.primitives import Primitive
-from donna.world.sources.markdown import MarkdownSectionMixin
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
 
 if TYPE_CHECKING:
     pass
@@ -16,5 +18,14 @@ class Text(MarkdownSectionMixin, Primitive):
     config_class: ClassVar[type[TextConfig]] = TextConfig
 
 
+class SpecificationConfig(ArtifactSectionConfig):
+    @pydantic.field_validator("tags", mode="after")
+    @classmethod
+    def ensure_specification_tag(cls, value: list[str]) -> list[str]:
+        if "specification" in value:
+            return value
+        return [*value, "specification"]
+
+
 class Specification(MarkdownSectionMixin, Primitive):
-    pass
+    config_class: ClassVar[type[SpecificationConfig]] = SpecificationConfig

donna/primitives/artifacts/workflow.py

@@ -1,5 +1,7 @@
 from typing import TYPE_CHECKING, ClassVar, Iterable, cast
 
+import pydantic
+
 from donna.core import errors as core_errors
 from donna.core.errors import ErrorsList
 from donna.core.result import Err, Ok, Result, unwrap_to_error
@@ -8,8 +10,8 @@ from donna.machine.artifacts import Artifact, ArtifactSection, ArtifactSectionCo
 from donna.machine.errors import ArtifactValidationError
 from donna.machine.operations import FsmMode, OperationMeta
 from donna.machine.primitives import Primitive
-from donna.world import markdown
-from donna.world.sources.markdown import MarkdownSectionMixin
+from donna.workspaces import markdown
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
 
 if TYPE_CHECKING:
     from donna.machine.changes import Change
@@ -97,6 +99,13 @@ def find_workflow_sections(start_operation_id: ArtifactSectionId, artifact: Arti
 class WorkflowConfig(ArtifactSectionConfig):
     start_operation_id: ArtifactSectionId
 
+    @pydantic.field_validator("tags", mode="after")
+    @classmethod
+    def ensure_workflow_tag(cls, value: list[str]) -> list[str]:
+        if "workflow" in value:
+            return value
+        return [*value, "workflow"]
+
 
 class WorkflowMeta(ArtifactSectionMeta):
     start_operation_id: ArtifactSectionId

donna/primitives/directives/list.py

@@ -0,0 +1,86 @@
+from typing import Any
+
+from jinja2.runtime import Context
+
+from donna.core import errors as core_errors
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result
+from donna.domain.ids import FullArtifactIdPattern
+from donna.machine.templates import Directive, PreparedDirectiveResult
+from donna.protocol.modes import mode
+
+
+class EnvironmentError(core_errors.EnvironmentError):
+    cell_kind: str = "directive_error"
+
+
+class ListInvalidArguments(EnvironmentError):
+    code: str = "donna.directives.list.invalid_arguments"
+    message: str = (
+        "List directive requires exactly one positional argument: artifact_id_pattern (got {error.provided_count})."
+    )
+    ways_to_fix: list[str] = ["Provide exactly one argument: artifact_id_pattern."]
+    provided_count: int
+
+
+class ListInvalidKeyword(EnvironmentError):
+    code: str = "donna.directives.list.invalid_keyword"
+    message: str = "List directive accepts only the `tags` keyword argument (got {error.keyword})."
+    ways_to_fix: list[str] = ["Remove unsupported keyword arguments."]
+    keyword: str
+
+
+class ListInvalidTags(EnvironmentError):
+    code: str = "donna.directives.list.invalid_tags"
+    message: str = "List directive `tags` must be a list of strings."
+    ways_to_fix: list[str] = ["Provide tags as a list of strings, e.g. tags=['tag1', 'tag2']."]
+
+
+class List(Directive):
+    def _prepare_arguments(  # noqa: CCR001
+        self,
+        context: Context,
+        *argv: Any,
+        **kwargs: Any,
+    ) -> PreparedDirectiveResult:
+        if argv is None or len(argv) != 1:
+            return Err([ListInvalidArguments(provided_count=0 if argv is None else len(argv))])
+
+        for keyword in kwargs:
+            if keyword != "tags":
+                return Err([ListInvalidKeyword(keyword=keyword)])
+
+        artifact_pattern_result = FullArtifactIdPattern.parse(str(argv[0]))
+        errors = artifact_pattern_result.err()
+        if errors is not None:
+            return Err(errors)
+
+        artifact_pattern = artifact_pattern_result.ok()
+        assert artifact_pattern is not None
+
+        tags = kwargs.get("tags")
+        if tags is None:
+            tags_list: list[str] = []
+        elif isinstance(tags, (list, tuple, set)):
+            tags_list = [str(tag) for tag in tags]
+        else:
+            return Err([ListInvalidTags()])
+
+        return Ok((artifact_pattern, tags_list))
+
+    def render_view(
+        self, context: Context, artifact_pattern: FullArtifactIdPattern, tags: list[str]
+    ) -> Result[Any, ErrorsList]:
+        protocol = mode().value
+        tags_args = " ".join(f"--tag '{tag}'" for tag in tags)
+        tag_suffix = f" {tags_args}" if tags_args else ""
+        return Ok(f"{artifact_pattern} (donna -p {protocol} artifacts list '{artifact_pattern}'{tag_suffix})")
+
+    def render_analyze(
+        self, context: Context, artifact_pattern: FullArtifactIdPattern, tags: list[str]
+    ) -> Result[Any, ErrorsList]:
+        if not tags:
+            return Ok(f"$$donna {self.analyze_id} {artifact_pattern} donna$$")
+
+        tags_marker = ",".join(tags)
+        return Ok(f"$$donna {self.analyze_id} {artifact_pattern} tags={tags_marker} donna$$")

donna/primitives/directives/view.py

@@ -5,7 +5,7 @@ from jinja2.runtime import Context
 from donna.core import errors as core_errors
 from donna.core.errors import ErrorsList
 from donna.core.result import Err, Ok, Result
-from donna.domain.ids import FullArtifactId
+from donna.domain.ids import FullArtifactIdPattern
 from donna.machine.templates import Directive, PreparedDirectiveResult
 from donna.protocol.modes import mode
 
@@ -16,30 +16,71 @@ class EnvironmentError(core_errors.EnvironmentError):
 
 class ViewInvalidArguments(EnvironmentError):
     code: str = "donna.directives.view.invalid_arguments"
-    message: str = "View directive requires exactly one argument: specification_id (got {error.provided_count})."
-    ways_to_fix: list[str] = ["Provide exactly one argument: specification_id."]
+    message: str = (
+        "View directive requires exactly one positional argument: artifact_id_pattern (got {error.provided_count})."
+    )
+    ways_to_fix: list[str] = ["Provide exactly one argument: artifact_id_pattern."]
     provided_count: int
 
 
+class ViewInvalidKeyword(EnvironmentError):
+    code: str = "donna.directives.view.invalid_keyword"
+    message: str = "View directive accepts only the `tags` keyword argument (got {error.keyword})."
+    ways_to_fix: list[str] = ["Remove unsupported keyword arguments."]
+    keyword: str
+
+
+class ViewInvalidTags(EnvironmentError):
+    code: str = "donna.directives.view.invalid_tags"
+    message: str = "View directive `tags` must be a list of strings."
+    ways_to_fix: list[str] = ["Provide tags as a list of strings, e.g. tags=['tag1', 'tag2']."]
+
+
 class View(Directive):
-    def _prepare_arguments(
+    def _prepare_arguments(  # noqa: CCR001
         self,
         context: Context,
         *argv: Any,
+        **kwargs: Any,
     ) -> PreparedDirectiveResult:
         if argv is None or len(argv) != 1:
             return Err([ViewInvalidArguments(provided_count=0 if argv is None else len(argv))])
 
-        artifact_id_result = FullArtifactId.parse(str(argv[0]))
-        errors = artifact_id_result.err()
+        for keyword in kwargs:
+            if keyword != "tags":
+                return Err([ViewInvalidKeyword(keyword=keyword)])
+
+        artifact_pattern_result = FullArtifactIdPattern.parse(str(argv[0]))
+        errors = artifact_pattern_result.err()
         if errors is not None:
             return Err(errors)
 
-        artifact_id = artifact_id_result.ok()
-        assert artifact_id is not None
+        artifact_pattern = artifact_pattern_result.ok()
+        assert artifact_pattern is not None
+
+        tags = kwargs.get("tags")
+        if tags is None:
+            tags_list: list[str] = []
+        elif isinstance(tags, (list, tuple, set)):
+            tags_list = [str(tag) for tag in tags]
+        else:
+            return Err([ViewInvalidTags()])
 
-        return Ok((artifact_id,))
+        return Ok((artifact_pattern, tags_list))
 
-    def render_view(self, context: Context, specification_id: FullArtifactId) -> Result[Any, ErrorsList]:
+    def render_view(
+        self, context: Context, artifact_pattern: FullArtifactIdPattern, tags: list[str]
+    ) -> Result[Any, ErrorsList]:
         protocol = mode().value
-        return Ok(f"donna -p {protocol} artifacts view '{specification_id}'")
+        tags_args = " ".join(f"--tag '{tag}'" for tag in tags)
+        tag_suffix = f" {tags_args}" if tags_args else ""
+        return Ok(f"{artifact_pattern} (donna -p {protocol} artifacts view '{artifact_pattern}'{tag_suffix})")
+
+    def render_analyze(
+        self, context: Context, artifact_pattern: FullArtifactIdPattern, tags: list[str]
+    ) -> Result[Any, ErrorsList]:
+        if not tags:
+            return Ok(f"$$donna {self.analyze_id} {artifact_pattern} donna$$")
+
+        tags_marker = ",".join(tags)
+        return Ok(f"$$donna {self.analyze_id} {artifact_pattern} tags={tags_marker} donna$$")

donna/primitives/operations/finish_workflow.py

@@ -5,8 +5,10 @@ from donna.core.result import Ok, Result
 from donna.domain.ids import FullArtifactId
 from donna.machine.artifacts import ArtifactSection, ArtifactSectionConfig, ArtifactSectionMeta
 from donna.machine.operations import FsmMode, OperationConfig, OperationKind, OperationMeta
-from donna.world import markdown
-from donna.world.sources.markdown import MarkdownSectionMixin
+from donna.protocol.cells import Cell
+from donna.protocol.utils import instant_output
+from donna.workspaces import markdown
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
 
 if TYPE_CHECKING:
     from donna.machine.changes import Change
@@ -21,6 +23,15 @@ class FinishWorkflow(MarkdownSectionMixin, OperationKind):
     def execute_section(self, task: "Task", unit: "WorkUnit", operation: ArtifactSection) -> Iterator["Change"]:
         from donna.machine.changes import ChangeFinishTask
 
+        output_text = operation.description
+
+        output_cell = Cell.build_markdown(
+            kind="operation_output",
+            content=output_text,
+            operation_id=str(unit.operation_id),
+        )
+        instant_output([output_cell])
+
         yield ChangeFinishTask(task_id=task.id)
 
     config_class: ClassVar[type[FinishWorkflowConfig]] = FinishWorkflowConfig

donna/primitives/operations/output.py

@@ -0,0 +1,87 @@
+from typing import TYPE_CHECKING, ClassVar, Iterator, cast
+
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result
+from donna.domain.ids import ArtifactSectionId, FullArtifactId
+from donna.machine.artifacts import Artifact, ArtifactSection, ArtifactSectionConfig, ArtifactSectionMeta
+from donna.machine.errors import ArtifactValidationError
+from donna.machine.operations import OperationConfig, OperationKind, OperationMeta
+from donna.protocol.cells import Cell
+from donna.protocol.utils import instant_output
+from donna.workspaces import markdown
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
+
+if TYPE_CHECKING:
+    from donna.machine.changes import Change
+    from donna.machine.tasks import Task, WorkUnit
+
+
+class OutputMissingNextOperation(ArtifactValidationError):
+    code: str = "donna.workflows.output_missing_next_operation"
+    message: str = "Output operation `{error.section_id}` must define `next_operation`."
+    ways_to_fix: list[str] = [
+        'Add `next_operation = "<next_operation>"` to the operation config block.',
+    ]
+
+
+class OutputConfig(OperationConfig):
+    next_operation: ArtifactSectionId | None = None
+
+
+class OutputMeta(OperationMeta):
+    next_operation: ArtifactSectionId | None = None
+
+
+class Output(MarkdownSectionMixin, OperationKind):
+    config_class: ClassVar[type[OutputConfig]] = OutputConfig
+
+    def markdown_construct_meta(
+        self,
+        artifact_id: "FullArtifactId",
+        source: markdown.SectionSource,
+        section_config: ArtifactSectionConfig,
+        description: str,
+        primary: bool = False,
+    ) -> Result[ArtifactSectionMeta, ErrorsList]:
+        output_config = cast(OutputConfig, section_config)
+
+        allowed_transitions: set[ArtifactSectionId] = set()
+        if output_config.next_operation is not None:
+            allowed_transitions.add(output_config.next_operation)
+
+        return Ok(
+            OutputMeta(
+                fsm_mode=output_config.fsm_mode,
+                allowed_transtions=allowed_transitions,
+                next_operation=output_config.next_operation,
+            )
+        )
+
+    def execute_section(self, task: "Task", unit: "WorkUnit", operation: ArtifactSection) -> Iterator["Change"]:
+        from donna.machine.changes import ChangeAddWorkUnit
+
+        meta = cast(OutputMeta, operation.meta)
+
+        output_text = operation.description
+
+        output_cell = Cell.build_markdown(
+            kind="operation_output",
+            content=output_text,
+            operation_id=str(unit.operation_id),
+        )
+        instant_output([output_cell])
+
+        next_operation = meta.next_operation
+        assert next_operation is not None
+        full_operation_id = unit.operation_id.full_artifact_id.to_full_local(next_operation)
+
+        yield ChangeAddWorkUnit(task_id=task.id, operation_id=full_operation_id)
+
+    def validate_section(self, artifact: Artifact, section_id: ArtifactSectionId) -> Result[None, ErrorsList]:
+        section = artifact.get_section(section_id).unwrap()
+        meta = cast(OutputMeta, section.meta)
+
+        if meta.next_operation is None:
+            return Err([OutputMissingNextOperation(artifact_id=artifact.id, section_id=section_id)])
+
+        return Ok(None)

donna/primitives/operations/request_action.py

@@ -10,8 +10,8 @@ from donna.domain.ids import ArtifactSectionId, FullArtifactId
 from donna.machine.action_requests import ActionRequest
 from donna.machine.artifacts import ArtifactSection, ArtifactSectionConfig, ArtifactSectionMeta
 from donna.machine.operations import FsmMode, OperationConfig, OperationKind, OperationMeta
-from donna.world import markdown
-from donna.world.sources.markdown import MarkdownSectionMixin
+from donna.workspaces import markdown
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
 
 if TYPE_CHECKING:
     from donna.machine.changes import Change
@@ -74,13 +74,7 @@ class RequestAction(MarkdownSectionMixin, OperationKind):
     def execute_section(self, task: "Task", unit: "WorkUnit", operation: ArtifactSection) -> Iterator["Change"]:
         from donna.machine.changes import ChangeAddActionRequest
 
-        context: dict[str, object] = {
-            "scheme": operation,
-            "task": task,
-            "work_unit": unit,
-        }
-
-        request_text = operation.description.format(**context)
+        request_text = operation.description
 
         full_operation_id = unit.operation_id
 

donna/primitives/operations/run_script.py

@@ -12,8 +12,8 @@ from donna.domain.ids import ArtifactSectionId, FullArtifactId
 from donna.machine.artifacts import Artifact, ArtifactSection, ArtifactSectionConfig, ArtifactSectionMeta
 from donna.machine.errors import ArtifactValidationError
 from donna.machine.operations import OperationConfig, OperationKind, OperationMeta
-from donna.world import markdown
-from donna.world.sources.markdown import MarkdownSectionMixin
+from donna.workspaces import markdown
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
 
 if TYPE_CHECKING:
     from donna.machine.changes import Change

donna/protocol/utils.py

@@ -0,0 +1,22 @@
+import sys
+
+from donna.protocol.cells import Cell
+from donna.protocol.modes import get_cell_formatter
+
+
+def instant_output(cells: list[Cell]) -> None:
+    if not cells:
+        return
+
+    formatter = get_cell_formatter()
+
+    formatted_cells: list[bytes] = []
+    for cell in cells:
+        # TODO: we should refactor that hardcoded check somehow
+        if cell.kind == "donna_log":
+            formatted_cells.append(formatter.format_log(cell, single_mode=True))
+        else:
+            formatted_cells.append(formatter.format_cell(cell, single_mode=False))
+
+    sys.stdout.buffer.write(b"\n\n".join(formatted_cells) + b"\n\n")
+    sys.stdout.buffer.flush()

donna/workspaces/artifacts.py

@@ -0,0 +1,238 @@
+import pathlib
+
+from donna.core.entities import BaseEntity
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result, unwrap_to_error
+from donna.domain.ids import FullArtifactId, FullArtifactIdPattern, WorldId
+from donna.machine.artifacts import Artifact
+from donna.machine.tasks import Task, WorkUnit
+from donna.workspaces import errors
+from donna.workspaces.config import config
+from donna.workspaces.templates import RenderMode
+
+
+class ArtifactRenderContext(BaseEntity):
+    primary_mode: RenderMode
+    current_task: Task | None = None
+    current_work_unit: WorkUnit | None = None
+
+
+class ArtifactUpdateError(errors.WorkspaceError):
+    cell_kind: str = "artifact_update_error"
+    artifact_id: FullArtifactId
+    path: pathlib.Path
+
+    def content_intro(self) -> str:
+        return f"Error updating artifact '{self.artifact_id}' from the path '{self.path}'"
+
+
+class CanNotUpdateReadonlyWorld(ArtifactUpdateError):
+    code: str = "donna.workspaces.cannot_update_readonly_world"
+    message: str = "Cannot upload artifact to the read-only world `{error.world_id}`"
+    world_id: WorldId
+
+
+class ArtifactRemoveError(errors.WorkspaceError):
+    cell_kind: str = "artifact_remove_error"
+    artifact_id: FullArtifactId
+
+    def content_intro(self) -> str:
+        return f"Error removing artifact '{self.artifact_id}'"
+
+
+class CanNotRemoveReadonlyWorld(ArtifactRemoveError):
+    code: str = "donna.workspaces.cannot_remove_readonly_world"
+    message: str = "Cannot remove artifact from the read-only world `{error.world_id}`"
+    world_id: WorldId
+
+
+class InputPathHasNoExtension(ArtifactUpdateError):
+    code: str = "donna.workspaces.input_path_has_no_extension"
+    message: str = "Input path has no extension to determine artifact source type"
+
+
+class NoSourceForArtifactExtension(ArtifactUpdateError):
+    code: str = "donna.workspaces.no_source_for_artifact_extension"
+    message: str = "No source found for artifact extension of input path"
+    extension: str
+
+
+class ArtifactCopyError(errors.WorkspaceError):
+    cell_kind: str = "artifact_copy_error"
+    source_id: FullArtifactId
+    target_id: FullArtifactId
+
+    def content_intro(self) -> str:
+        return f"Error copying artifact '{self.source_id}' to '{self.target_id}'"
+
+
+class CanNotCopyToReadonlyWorld(ArtifactCopyError):
+    code: str = "donna.workspaces.cannot_copy_to_readonly_world"
+    message: str = "Cannot copy artifact to the read-only world `{error.world_id}`"
+    world_id: WorldId
+
+
+class SourceArtifactHasNoExtension(ArtifactCopyError):
+    code: str = "donna.workspaces.source_artifact_has_no_extension"
+    message: str = "Source artifact has no extension to determine source type"
+
+
+@unwrap_to_error
+def artifact_file_extension(full_id: FullArtifactId) -> Result[str, ErrorsList]:
+    world = config().get_world(full_id.world_id).unwrap()
+    return Ok(world.file_extension_for(full_id.artifact_id).unwrap().lstrip("."))
+
+
+@unwrap_to_error
+def fetch_artifact(full_id: FullArtifactId, output: pathlib.Path) -> Result[None, ErrorsList]:
+    world = config().get_world(full_id.world_id).unwrap()
+    content = world.fetch_source(full_id.artifact_id).unwrap()
+
+    with output.open("wb") as f:
+        f.write(content)
+
+    return Ok(None)
+
+
+@unwrap_to_error
+def update_artifact(full_id: FullArtifactId, input: pathlib.Path) -> Result[None, ErrorsList]:
+    world = config().get_world(full_id.world_id).unwrap()
+
+    if world.readonly:
+        return Err([CanNotUpdateReadonlyWorld(artifact_id=full_id, path=input, world_id=world.id)])
+
+    source_suffix = input.suffix.lower()
+    content_bytes = input.read_bytes()
+
+    if not source_suffix:
+        return Err([InputPathHasNoExtension(artifact_id=full_id, path=input)])
+
+    source_config = config().find_source_for_extension(source_suffix)
+    if source_config is None:
+        return Err([NoSourceForArtifactExtension(artifact_id=full_id, path=input, extension=source_suffix)])
+
+    render_context = ArtifactRenderContext(primary_mode=RenderMode.view)
+    test_artifact = source_config.construct_artifact_from_bytes(full_id, content_bytes, render_context).unwrap()
+    validation_result = test_artifact.validate_artifact()
+
+    validation_result.unwrap()
+    world.update(full_id.artifact_id, content_bytes, source_suffix).unwrap()
+
+    return Ok(None)
+
+
+@unwrap_to_error
+def copy_artifact(source_id: FullArtifactId, target_id: FullArtifactId) -> Result[None, ErrorsList]:
+    source_world = config().get_world(source_id.world_id).unwrap()
+    target_world = config().get_world(target_id.world_id).unwrap()
+
+    if target_world.readonly:
+        return Err(
+            [
+                CanNotCopyToReadonlyWorld(
+                    source_id=source_id,
+                    target_id=target_id,
+                    world_id=target_world.id,
+                )
+            ]
+        )
+
+    content_bytes = source_world.fetch_source(source_id.artifact_id).unwrap()
+    source_extension = source_world.file_extension_for(source_id.artifact_id).unwrap()
+
+    if not source_extension:
+        return Err([SourceArtifactHasNoExtension(source_id=source_id, target_id=target_id)])
+
+    source_extension = source_extension.lower()
+    source_config = config().find_source_for_extension(source_extension)
+    if source_config is None:
+        return Err(
+            [
+                NoSourceForArtifactExtension(
+                    artifact_id=source_id,
+                    path=pathlib.Path(str(source_id)),
+                    extension=source_extension,
+                )
+            ]
+        )
+
+    render_context = ArtifactRenderContext(primary_mode=RenderMode.view)
+    test_artifact = source_config.construct_artifact_from_bytes(target_id, content_bytes, render_context).unwrap()
+    test_artifact.validate_artifact().unwrap()
+
+    target_world.update(target_id.artifact_id, content_bytes, source_extension).unwrap()
+    return Ok(None)
+
+
+@unwrap_to_error
+def move_artifact(source_id: FullArtifactId, target_id: FullArtifactId) -> Result[None, ErrorsList]:
+    copy_result = copy_artifact(source_id, target_id)
+    if copy_result.is_err():
+        return copy_result
+
+    return remove_artifact(source_id)
+
+
+@unwrap_to_error
+def remove_artifact(full_id: FullArtifactId) -> Result[None, ErrorsList]:
+    world = config().get_world(full_id.world_id).unwrap()
+
+    if world.readonly:
+        return Err([CanNotRemoveReadonlyWorld(artifact_id=full_id, world_id=world.id)])
+
+    world.remove(full_id.artifact_id).unwrap()
+    return Ok(None)
+
+
+@unwrap_to_error
+def load_artifact(
+    full_id: FullArtifactId, render_context: ArtifactRenderContext | None = None
+) -> Result[Artifact, ErrorsList]:
+    if render_context is None:
+        render_context = ArtifactRenderContext(primary_mode=RenderMode.view)
+
+    world = config().get_world(full_id.world_id).unwrap()
+    return Ok(world.fetch(full_id.artifact_id, render_context).unwrap())
+
+
+def list_artifacts(  # noqa: CCR001
+    pattern: FullArtifactIdPattern,
+    render_context: ArtifactRenderContext | None = None,
+    tags: list[str] | None = None,
+) -> Result[list[Artifact], ErrorsList]:
+    if render_context is None:
+        render_context = ArtifactRenderContext(primary_mode=RenderMode.view)
+
+    tag_filters = tags or []
+
+    artifacts: list[Artifact] = []
+    errors: ErrorsList = []
+
+    for world in reversed(config().worlds_instances):
+        for artifact_id in world.list_artifacts(pattern):
+            full_id = FullArtifactId((world.id, artifact_id))
+            artifact_result = load_artifact(full_id, render_context)
+            if artifact_result.is_err():
+                errors.extend(artifact_result.unwrap_err())
+                continue
+            artifact = artifact_result.unwrap()
+            if tag_filters and not _artifact_matches_tags(artifact, tag_filters):
+                continue
+            artifacts.append(artifact)
+
+    if errors:
+        return Err(errors)
+
+    return Ok(artifacts)
+
+
+def _artifact_matches_tags(artifact: Artifact, tags: list[str]) -> bool:
+    if not tags:
+        return True
+
+    primary_result = artifact.primary_section()
+    if primary_result.is_err():
+        return False
+
+    primary = primary_result.unwrap()
+    return all(tag in primary.tags for tag in tags)

donna/{world → workspaces}/artifacts_discovery.py

@@ -3,7 +3,7 @@ from functools import lru_cache
 from typing import Iterable, Protocol
 
 from donna.domain.ids import ArtifactId, FullArtifactId, FullArtifactIdPattern, WorldId
-from donna.world.config import config
+from donna.workspaces.config import config
 
 
 class ArtifactListingNode(Protocol):