Extensible canonical internal processing refactoring

src/markitect_tool/cli/extensions.py

@@ -0,0 +1,64 @@
+"""CLI extension specifications derived from internal extension descriptors."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from markitect_tool.extension import ExtensionDescriptor, ExtensionRegistry
+
+
+@dataclass(frozen=True)
+class CliCommandSpec:
+    """Inspectable command affordance declared by an extension."""
+
+    command: str
+    extension_id: str
+    kind: str
+    summary: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        data = {
+            "command": self.command,
+            "extension_id": self.extension_id,
+            "kind": self.kind,
+            "summary": self.summary,
+            "metadata": self.metadata,
+        }
+        return {
+            key: value
+            for key, value in data.items()
+            if value not in (None, {}, [])
+        }
+
+
+def command_specs_from_extension(descriptor: ExtensionDescriptor) -> list[CliCommandSpec]:
+    """Return CLI command specs declared by one extension descriptor."""
+
+    raw_commands = descriptor.cli.get("commands", [])
+    if isinstance(raw_commands, str):
+        raw_commands = [raw_commands]
+    return [
+        CliCommandSpec(
+            command=str(command),
+            extension_id=descriptor.id,
+            kind=descriptor.kind,
+            summary=descriptor.summary,
+            metadata={
+                key: value
+                for key, value in descriptor.cli.items()
+                if key != "commands"
+            },
+        )
+        for command in raw_commands
+    ]
+
+
+def collect_cli_command_specs(registry: ExtensionRegistry) -> list[CliCommandSpec]:
+    """Collect CLI affordances from a registry of extension descriptors."""
+
+    specs: list[CliCommandSpec] = []
+    for descriptor in registry.list():
+        specs.extend(command_specs_from_extension(descriptor))
+    return sorted(specs, key=lambda spec: (spec.command, spec.extension_id))