Cline rules

1# Hermes Project Rules
2 
3## Tech Stack Reference
4 
5See `llm-shared/project_tech_stack.md` for core technology choices, build system configuration, and library preferences.
6 
7## Project-Specific Guidelines
8 
9- **Unit Tests:** Write basic unit tests for new functionality. Always check the tests pass after finishing changes.
10- **Purpose:** See README.md for project definition
11 
12## Code Structure
13 
14- All import processors go under the `cmd/` directory
15- The internal/ directory contains common utility functions, use it when possible. Add to it when necessary.
16- Each processor has its own subdirectory and Go package
17 
18## Implementation Requirements
19 
20- Maintain consistent Go style and idiomatic patterns
21- Follow the existing architectural patterns
22- Each data source processor should be implemented as a separate command
23 
24## Error Handling
25 
26- Use standard Go error handling (`errors.New`, `fmt.Errorf`). Return errors up the call stack for handling by Cobra's `RunE`.
27- Wrap errors with context where appropriate to aid debugging (e.g., `fmt.Errorf("failed to process item %s: %w", itemID, err)`).
28- Utilize custom error types from `internal/errors` for specific conditions like API rate limits when applicable.
29- Log significant errors within the command logic but generally return them to let the top level (`main.go` or Cobra) handle exit codes.
30 
31## Configuration Management
32 
33- Configuration is managed via Viper, reading `config.yaml` by default.
34- Global settings (like output directories, overwrite flag) are defined in `root.go` and accessed via `internal/config` or Viper directly.
35- Command-specific configuration (e.g., input file paths, API keys) should use keys namespaced by the command name in `config.yaml` (e.g., `goodreads.csvfile`, `steam.apikey`).
36- Prioritize command-line flags over config file values when both are provided.
37 
38## Logging
39 
40- Log informational messages about progress (e.g., starting import, items processed) at `InfoLevel`.
41- Use `DebugLevel` for verbose information useful for debugging (e.g., detailed API request/response info, cache hits/misses).
42- Use `WarnLevel` for recoverable issues (e.g., skipping an item due to missing data but continuing the import).
43- Use `ErrorLevel` for significant problems encountered within functions, often just before returning an error.
44 
45## Caching
46 
47- Use the `cache/` directory for caching external API responses.
48- Organize cache files into subdirectories named after the data source (e.g., `cache/goodreads/`, `cache/omdb/`).
49- Implement caching logic within the specific command package (e.g., `cmd/goodreads/cache.go`).
50- Respect API rate limits using appropriate delays or by handling specific rate limit errors.
51 
52## Output Formats & Handling
53 
54- Default output directories (`markdown/`, `json/`) are set in `root.go` and configurable via `config.yaml`.
55- Commands should allow specifying subdirectories for their output via flags/config (e.g., `markdown/goodreads/`).
56- Use `internal/fileutil` for writing Markdown and JSON files, ensuring consistent formatting and handling the `overwrite` flag logic.
57- Follow existing patterns for Markdown frontmatter and JSON structure for each data type.
58 
59## External API Interaction
60 
61- Implement API client logic within the relevant command package (e.g., `cmd/goodreads/openlibrary.go`).
62- Respect API rate limits using appropriate delays (`time.Sleep`) or by handling specific rate limit errors.
63- Utilize caching (`cache/`) to minimize redundant API calls.
64- Handle common API errors gracefully (e.g., log a warning for 404 Not Found, retry or fail on persistent errors).
65 
66## Testing
67 
68- Write unit tests for parsing logic, API interaction (using mocks/stubs), and output generation.
69- Place tests in `_test.go` files within the same package.
70- Use the `testdata/` subdirectory within each command package for input fixtures and expected output files.
71- Employ table-driven tests for validating multiple input cases efficiently.
72 
73## Utilities
74 
75- Use shared utility functions from `internal/` packages (e.g., `cmdutil` for command setup, `fileutil` for file operations).
76- Contribute reusable logic back to these `internal/` packages when appropriate.
77 
78## Documentation
79 
80- Write Go doc comments for all exported functions, types, and constants.
81- Keep command help messages (`Short`, `Long` fields in `cobra.Command`) clear and up-to-date.
82- Update `README.md` and any relevant files in `docs/` when adding new commands or changing functionality significantly.
83