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

1# SPDX-License-Identifier: MIT 

2# Copyright © 2025 Bijan Mousavi 

3 

4"""Defines the contract for the command history management service. 

5 

6This module specifies the `HistoryProtocol`, a formal interface that any 

7service responsible for recording, retrieving, and managing CLI command 

8history events must implement. 

9""" 

10 

11from __future__ import annotations 

12 

13from collections.abc import Sequence 

14from pathlib import Path 

15from typing import Any, Protocol, TypeVar, runtime_checkable 

16 

17T = TypeVar("T") 

18 

19 

20@runtime_checkable 

21class HistoryProtocol(Protocol): 

22 """Defines the contract for command history management. 

23 

24 This interface specifies the methods for recording, retrieving, and managing 

25 command history events, including persistence and import/export 

26 functionality. 

27 """ 

28 

29 def add( 

30 self, 

31 command: str, 

32 *, 

33 params: Sequence[str] | None = None, 

34 success: bool | None = True, 

35 return_code: int | None = 0, 

36 duration_ms: float | None = None, 

37 ) -> None: 

38 """Records a command execution event. 

39 

40 Args: 

41 command (str): The full command string (e.g., "status --verbose"). 

42 params (Sequence[str] | None): The raw argument vector as executed. 

43 success (bool | None): True if the command was successful. 

44 return_code (int | None): The integer exit code of the command. 

45 duration_ms (float | None): Total execution time in milliseconds. 

46 

47 Returns: 

48 None: 

49 """ 

50 ... 

51 

52 def list( 

53 self, 

54 *, 

55 limit: int | None = 20, 

56 group_by: str | None = None, 

57 filter_cmd: str | None = None, 

58 sort: str | None = None, 

59 ) -> list[dict[str, Any]]: 

60 """Retrieves command history events. 

61 

62 Args: 

63 limit (int | None): The maximum number of events to return. 

64 group_by (str | None): A field name to group events by. 

65 filter_cmd (str | None): A substring to filter commands by. 

66 sort (str | None): A field name to sort the results by. 

67 

68 Returns: 

69 list[dict[str, Any]]: A list of history event dictionaries. 

70 """ 

71 ... 

72 

73 def clear(self) -> None: 

74 """Erases all command history events from the store.""" 

75 ... 

76 

77 def flush(self) -> None: 

78 """Persists any in-memory history data to permanent storage.""" 

79 ... 

80 

81 def export(self, path: Path) -> None: 

82 """Exports all history entries to a file. 

83 

84 Args: 

85 path (Path): The target file path, which will be overwritten. 

86 

87 Returns: 

88 None: 

89 """ 

90 ... 

91 

92 def import_(self, path: Path) -> None: 

93 """Imports history entries from a file, replacing existing entries. 

94 

95 Args: 

96 path (Path): The source file path containing history data. 

97 

98 Returns: 

99 None: 

100 """ 

101 ...