💫 Toolkit to help you get started with SDD or any other process!
refactor(version): extract shared operation (#4863)
Manfred Riem62b6fcf49933
diff --git a/src/specify_cli/_operation_version.py b/src/specify_cli/_operation_version.pynew file mode 100644index 000000000..97318b6dd--- /dev/null+++ b/src/specify_cli/_operation_version.py@@ -0,0 +1,97 @@+"""Shared application operation for version information collection."""++from __future__ import annotations++import platform+from collections.abc import Callable+from dataclasses import dataclass++from ._assets import get_speckit_version+++@dataclass(frozen=True)+class VersionRuntime:+ """Runtime versions reported by the version operation."""++ python: str+ openssl: str | None+++@dataclass(frozen=True)+class VersionSystem:+ """Host system information reported by the version operation."""++ platform: str+ architecture: str+ os_version: str+++@dataclass(frozen=True)+class VersionResult:+ """Transport-neutral result of the version operation."""++ cli_version: str+ runtime: VersionRuntime | None+ system: VersionSystem | None+ features: dict[str, bool]+++def _feature_capabilities() -> dict[str, bool]:+ """Return stable local CLI capability flags for humans and agents."""+ return {+ "controlled_multi_install_integrations": True,+ "integration_use_command": True,+ "multi_install_safe_registry_metadata": True,+ "integration_upgrade_command": True,+ "self_check_command": True,+ "workflow_catalog": True,+ "bundled_templates": True,+ }+++def _openssl_version() -> str | None:+ """Return the loaded OpenSSL version, or None when unavailable."""+ try:+ import ssl+ except ImportError:+ return None++ value = getattr(ssl, "OPENSSL_VERSION", None)+ return value if isinstance(value, str) and value else None+++def collect_version_result(+ *,+ include_environment: bool = True,+ cli_version_getter: Callable[[], str] | None = None,+ openssl_version_getter: Callable[[], str | None] | None = None,+ feature_capabilities_getter: Callable[[], dict[str, bool]] | None = None,+) -> VersionResult:+ """Collect semantic version information for any delivery adapter."""+ get_cli_version = cli_version_getter or get_speckit_version+ get_openssl_version = openssl_version_getter or _openssl_version+ get_feature_capabilities = feature_capabilities_getter or _feature_capabilities++ cli_version = get_cli_version()+ features = get_feature_capabilities()+ if not include_environment:+ return VersionResult(+ cli_version=cli_version,+ runtime=None,+ system=None,+ features=features,+ )++ return VersionResult(+ cli_version=cli_version,+ runtime=VersionRuntime(+ python=platform.python_version(),+ openssl=get_openssl_version(),+ ),+ system=VersionSystem(+ platform=platform.system(),+ architecture=platform.machine(),+ os_version=platform.version(),+ ),+ features=features,+ )diff --git a/src/specify_cli/command_version.py b/src/specify_cli/command_version.pyindex c0ae9efba..976fa785b 100644--- a/src/specify_cli/command_version.py+++ b/src/specify_cli/command_version.py@@ -3,55 +3,52 @@from __future__ import annotationsimport json-import platformimport typerfrom rich.panel import Panelfrom rich.table import Table+from . import _operation_versionfrom ._console import console, show_banner+from ._operation_version import (+ VersionResult,+ _feature_capabilities,+ _openssl_version,+ collect_version_result,+)-_INTERNAL_ERROR_MESSAGE = "Unable to collect version information."-+platform = _operation_version.platform-def _feature_capabilities() -> dict[str, bool]:- """Return stable local CLI capability flags for humans and agents."""- return {- "controlled_multi_install_integrations": True,- "integration_use_command": True,- "multi_install_safe_registry_metadata": True,- "integration_upgrade_command": True,- "self_check_command": True,- "workflow_catalog": True,- "bundled_templates": True,- }+_INTERNAL_ERROR_MESSAGE = "Unable to collect version information."-def _openssl_version() -> str | None:- """Return the loaded OpenSSL version, or None when unavailable."""- try:- import ssl- except ImportError:- return None+def _json_result(cli_version: str) -> dict[str, object]:+ """Collect the complete machine-readable version result."""+ result = collect_version_result(+ cli_version_getter=lambda: cli_version,+ openssl_version_getter=_openssl_version,+ feature_capabilities_getter=_feature_capabilities,+ )+ return _result_payload(result)- value = getattr(ssl, "OPENSSL_VERSION", None)- return value if isinstance(value, str) and value else None+def _result_payload(result: VersionResult) -> dict[str, object]:+ """Map a complete operation result to the established CLI JSON shape."""+ if result.runtime is None or result.system is None:+ raise ValueError("Complete version information is required.")-def _json_result(cli_version: str) -> dict[str, object]:- """Collect the complete machine-readable version result."""return {- "cli_version": cli_version,+ "cli_version": result.cli_version,"runtime": {- "python": platform.python_version(),- "openssl": _openssl_version(),+ "python": result.runtime.python,+ "openssl": result.runtime.openssl,},"system": {- "platform": platform.system(),- "architecture": platform.machine(),- "os_version": platform.version(),+ "platform": result.system.platform,+ "architecture": result.system.architecture,+ "os_version": result.system.os_version,},- "features": _feature_capabilities(),+ "features": result.features,}@@ -77,7 +74,12 @@ def version(if json_output:try:- payload = _json_result(get_speckit_version())+ result = collect_version_result(+ cli_version_getter=get_speckit_version,+ openssl_version_getter=_openssl_version,+ feature_capabilities_getter=_feature_capabilities,+ )+ payload = _result_payload(result)rendered = _serialize_json(payload)except Exception: # noqa: BLE001# JSON mode must normalize every unexpected command failure.@@ -94,34 +96,45 @@ def version(typer.echo(rendered)return- cli_version = get_speckit_version()if features:- capabilities = _feature_capabilities()- console.print(f"Spec Kit CLI: {cli_version}")+ result = collect_version_result(+ include_environment=False,+ cli_version_getter=get_speckit_version,+ feature_capabilities_getter=_feature_capabilities,+ )+ console.print(f"Spec Kit CLI: {result.cli_version}")console.print()console.print("Features:")- for key, enabled in capabilities.items():+ for key, enabled in result.features.items():label = key.replace("_", " ")console.print(f"- {label}: {'yes' if enabled else 'no'}")return+ result = collect_version_result(+ cli_version_getter=get_speckit_version,+ openssl_version_getter=_openssl_version,+ feature_capabilities_getter=_feature_capabilities,+ )+ if result.runtime is None or result.system is None:+ raise RuntimeError("Complete version information is required.")+show_banner()info_table = Table(show_header=False, box=None, padding=(0, 2))info_table.add_column("Key", style="cyan", justify="right")info_table.add_column("Value", style="white")- info_table.add_row("CLI Version", cli_version)+ info_table.add_row("CLI Version", result.cli_version)info_table.add_row("", "")- info_table.add_row("Python", platform.python_version())- info_table.add_row("Platform", platform.system())- info_table.add_row("Architecture", platform.machine())- info_table.add_row("OS Version", platform.version())+ info_table.add_row("Python", result.runtime.python)+ info_table.add_row("Platform", result.system.platform)+ info_table.add_row("Architecture", result.system.architecture)+ info_table.add_row("OS Version", result.system.os_version)# The OpenSSL runtime the interpreter actually loaded. HTTPS failure# reports (#4433) hinge on which OpenSSL is in play, and on Windows it is# not obvious from the outside, so surface it here. An interpreter built# without the ssl extension skips the row rather than failing the command.- openssl_version = _openssl_version()+ openssl_version = result.runtime.opensslif openssl_version:info_table.add_row("OpenSSL", openssl_version)diff --git a/tests/specify_cli/test_command_version.py b/tests/specify_cli/test_command_version.pyindex d249b3c35..f1e6437bf 100644--- a/tests/specify_cli/test_command_version.py+++ b/tests/specify_cli/test_command_version.py@@ -9,6 +9,11 @@ import pytestfrom typer.testing import CliRunnerfrom specify_cli import app+from specify_cli._operation_version import (+ VersionResult,+ VersionRuntime,+ VersionSystem,+)runner = CliRunner()@@ -83,6 +88,43 @@ class TestVersionCommand:assert result.stderr == ""assert json.loads(result.stdout) == expected+ def test_version_json_renders_shared_operation_result(self):+ """The CLI adapter maps the shared typed result to its JSON contract."""+ operation_result = VersionResult(+ cli_version="1.2.3",+ runtime=VersionRuntime(+ python="3.13.1",+ openssl="OpenSSL 3.4.0",+ ),+ system=VersionSystem(+ platform="ExampleOS",+ architecture="example64",+ os_version="ExampleOS 4.5",+ ),+ features=EXPECTED_FEATURES,+ )+ with patch(+ "specify_cli.command_version.collect_version_result",+ return_value=operation_result,+ ) as collect:+ result = runner.invoke(app, ["version", "--json"])++ assert result.exit_code == 0+ assert json.loads(result.stdout) == {+ "cli_version": operation_result.cli_version,+ "runtime": {+ "python": operation_result.runtime.python,+ "openssl": operation_result.runtime.openssl,+ },+ "system": {+ "platform": operation_result.system.platform,+ "architecture": operation_result.system.architecture,+ "os_version": operation_result.system.os_version,+ },+ "features": operation_result.features,+ }+ collect.assert_called_once()+def test_version_features_json_is_exact_alias(self):"""--features does not filter JSON output or change its bytes."""with patch("specify_cli.get_speckit_version", return_value="1.2.3"):diff --git a/tests/specify_cli/test_operation_version.py b/tests/specify_cli/test_operation_version.pynew file mode 100644index 000000000..802d627b8--- /dev/null+++ b/tests/specify_cli/test_operation_version.py@@ -0,0 +1,130 @@+"""Tests for the shared version operation."""++import sys+from types import SimpleNamespace+from unittest.mock import Mock, patch++from specify_cli import _operation_version+from specify_cli._operation_version import (+ VersionResult,+ VersionRuntime,+ VersionSystem,+ collect_version_result,+)++EXPECTED_FEATURES = {+ "controlled_multi_install_integrations": True,+ "integration_use_command": True,+ "multi_install_safe_registry_metadata": True,+ "integration_upgrade_command": True,+ "self_check_command": True,+ "workflow_catalog": True,+ "bundled_templates": True,+}+++def test_collect_version_result_returns_complete_typed_result():+ """The operation owns complete semantic version collection."""+ with (+ patch(+ "specify_cli._operation_version.get_speckit_version",+ return_value="1.2.3",+ ),+ patch(+ "specify_cli._operation_version.platform.python_version",+ return_value="3.13.1",+ ),+ patch(+ "specify_cli._operation_version.platform.system",+ return_value="ExampleOS",+ ),+ patch(+ "specify_cli._operation_version.platform.machine",+ return_value="example64",+ ),+ patch(+ "specify_cli._operation_version.platform.version",+ return_value="ExampleOS 4.5",+ ),+ patch(+ "specify_cli._operation_version._openssl_version",+ return_value="OpenSSL 3.4.0",+ ),+ ):+ result = collect_version_result()++ assert result == VersionResult(+ cli_version="1.2.3",+ runtime=VersionRuntime(+ python="3.13.1",+ openssl="OpenSSL 3.4.0",+ ),+ system=VersionSystem(+ platform="ExampleOS",+ architecture="example64",+ os_version="ExampleOS 4.5",+ ),+ features=EXPECTED_FEATURES,+ )+++def test_openssl_version_returns_loaded_runtime(monkeypatch):+ """The operation reports the OpenSSL runtime loaded by Python."""+ monkeypatch.setitem(+ sys.modules,+ "ssl",+ SimpleNamespace(OPENSSL_VERSION="OpenSSL test"),+ )++ assert _operation_version._openssl_version() == "OpenSSL test"+++def test_openssl_version_returns_none_when_unavailable(monkeypatch):+ """The operation treats a missing ssl module as unavailable."""+ monkeypatch.setitem(sys.modules, "ssl", None)++ assert _operation_version._openssl_version() is None+++def test_feature_capabilities_are_stable_and_ordered():+ """Feature names and order remain part of the semantic result."""+ result = collect_version_result(+ include_environment=False,+ cli_version_getter=lambda: "1.2.3",+ )++ assert result.features == EXPECTED_FEATURES+ assert list(result.features) == list(EXPECTED_FEATURES)+ assert result.runtime is None+ assert result.system is None+++def test_feature_only_collection_skips_environment_probes():+ """Focused capability collection does not touch runtime or system probes."""+ openssl_version_getter = Mock(side_effect=AssertionError("must not run"))+ with (+ patch(+ "specify_cli._operation_version.platform.python_version",+ side_effect=AssertionError("must not run"),+ ),+ patch(+ "specify_cli._operation_version.platform.system",+ side_effect=AssertionError("must not run"),+ ),+ ):+ result = collect_version_result(+ include_environment=False,+ cli_version_getter=lambda: "1.2.3",+ openssl_version_getter=openssl_version_getter,+ )++ assert result.cli_version == "1.2.3"+ openssl_version_getter.assert_not_called()+++def test_operation_contract_is_transport_neutral():+ """The operation module exposes semantic data without adapter dependencies."""+ forbidden_names = {"typer", "rich", "mcp"}++ assert forbidden_names.isdisjoint(_operation_version.__dict__)+ assert VersionResult.__module__ == "specify_cli._operation_version"