Coverage for src/prosemark/ports/daily_repo.py: 100%

1"""DailyRepo abstract base class for freewrite management. 

2 

3This module defines the DailyRepo abstract base class which provides 

4the contract for creating timestamped freewrite files outside the 

5binder structure. Freewrites are standalone markdown files with 

6optional titles and UUIDv7 identifiers. 

7""" 

8 

9from abc import ABC, abstractmethod 

10 

11 

12class DailyRepo(ABC): 

13 """Abstract base class for daily freewrite file management. 

14 

15 The DailyRepo provides a simple interface for creating timestamped 

16 freewrite files that exist outside the binder hierarchy. These files 

17 offer frictionless writing opportunities with automatic timestamping 

18 and unique identification. 

19 

20 Implementations should: 

21 - Generate filenames with format: YYYYMMDDTHHMM_<uuid7>.md 

22 - Support optional title in frontmatter 

23 - Create standalone files (no binder integration) 

24 - Use UUIDv7 for unique identification 

25 

26 This abstract base class supports the hexagonal architecture by 

27 isolating freewrite file creation logic from the domain and 

28 application layers, enabling different storage mechanisms while 

29 maintaining consistent behavior. 

30 """ 

31 

32 @abstractmethod 

33 def write_freeform(self, title: str | None = None) -> str: 

34 """Create a new timestamped freewrite file. 

35 

36 Creates a new markdown file with a timestamped filename and 

37 optional title in the frontmatter. The file is created as a 

38 standalone entity outside any binder structure. 

39 

40 Args: 

41 title: Optional title to include in the file's frontmatter. 

42 If provided, will be added as a 'title' field in the 

43 YAML frontmatter block. 

44 

45 Returns: 

46 The filename of the created freewrite file, following the 

47 format YYYYMMDDTHHMM_<uuid7>.md 

48 

49 Raises: 

50 FilesystemError: If the file cannot be created due to I/O 

51 errors, permission issues, or disk space 

52 constraints. 

53 

54 Example: 

55 >>> repo = FilesystemDailyRepo('/path/to/daily') 

56 >>> filename = repo.write_freeform('Morning Thoughts') 

57 >>> print(filename) 

58 "20250911T0830_01932c5a-7f3e-7000-8000-000000000001.md" 

59 

60 """