Coverage for  / home / runner / work / bijux-cli / bijux-cli / src / bijux_cli / services / diagnostics / contracts.py: 100%

1# SPDX-License-Identifier: Apache-2.0 

2# Copyright © 2025 Bijan Mousavi 

3 

4"""Defines contracts for diagnostics services.""" 

5 

6from __future__ import annotations 

7 

8from collections.abc import Mapping 

9from dataclasses import dataclass 

10from typing import Any, Protocol, runtime_checkable 

11 

12 

13@dataclass(frozen=True) 

14class DiagnosticsConfig: 

15 """Configuration for diagnostics services.""" 

16 

17 enabled: bool 

18 telemetry_enabled: bool 

19 

20 

21@runtime_checkable 

22class AuditProtocol(Protocol): 

23 """Defines the contract for auditing command execution.""" 

24 

25 def log(self, cmd: list[str], *, executor: str) -> None: 

26 """Record a command execution.""" 

27 ... 

28 

29 def run(self, cmd: list[str], *, executor: str) -> tuple[int, bytes, bytes]: 

30 """Run a command through the audit service.""" 

31 ... 

32 

33 def cli_audit(self) -> None: 

34 """Run an audit of the CLI environment.""" 

35 ... 

36 

37 def shutdown(self) -> None: 

38 """Shutdown the audit service.""" 

39 ... 

40 

41 

42@runtime_checkable 

43class DocsProtocol(Protocol): 

44 """Defines the contract for documentation generation.""" 

45 

46 def render(self, spec: Mapping[str, Any], *, fmt: Any, pretty: bool = False) -> str: 

47 """Render a document spec to a string.""" 

48 ... 

49 

50 def write( 

51 self, 

52 spec: Mapping[str, Any], 

53 *, 

54 fmt: Any, 

55 name: str, 

56 pretty: bool = False, 

57 ) -> str: 

58 """Write a document spec to disk.""" 

59 ... 

60 

61 

62@runtime_checkable 

63class DoctorProtocol(Protocol): 

64 """Defines the contract for health checks.""" 

65 

66 def check_health(self) -> str: 

67 """Run health checks and return a summary.""" 

68 ... 

69 

70 

71@runtime_checkable 

72class MemoryProtocol(Protocol): 

73 """Defines the contract for key-value memory storage.""" 

74 

75 def get(self, key: str) -> Any: 

76 """Retrieve a stored value.""" 

77 ... 

78 

79 def set(self, key: str, value: Any) -> None: 

80 """Store a key-value pair.""" 

81 ... 

82 

83 def delete(self, key: str) -> None: 

84 """Delete a stored value.""" 

85 ... 

86 

87 def clear(self) -> None: 

88 """Clear all stored values.""" 

89 ... 

90 

91 def keys(self) -> list[str]: 

92 """List stored keys.""" 

93 ... 

94 

95 

96__all__ = [ 

97 "AuditProtocol", 

98 "DocsProtocol", 

99 "DoctorProtocol", 

100 "MemoryProtocol", 

101 "DiagnosticsConfig", 

102]