| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 14 | 0% |
| Commands | 0 | 6 | 0 | 0% |
| Section tags | 1 | 2 | 4 | 14% |
What each file covers
Sections
0 shared · 5 only in A · 14 only in B- − Gemini Agent Guide for Hermes
- − Project Overview & Architecture
- − Developer Workflow
- − Key Development Patterns
- − Gemini Agent Specific Notes
- + Hermes Project Rules
- + Tech Stack Reference
- + Project-Specific Guidelines
- + Code Structure
- + Implementation Requirements
- + Error Handling
- + Configuration Management
- + Logging
- + Caching
- + Output Formats & Handling
- + External API Interaction
- + Testing
- + Utilities
- + Documentation
Commands
0 shared · 6 only in A · 0 only in B- − task build
- − task test
- − task lint
- − go run . <command> [flags]
- − go run . import goodreads -f path/to/export.csv
- − go.mod
Section tags
1 shared · 2 only in A · 4 only in B- − code-style
- − agent-behaviour
- + test
- + api
- + do-not
- + docs
- architecture
Line diff
lepinkainen/hermes · GEMINI.md
@@ −1 @@
1# Gemini Agent Guide for Hermes
2
3This guide provides essential information for developing in the Hermes codebase.
4
5## Project Overview & Architecture
6
7Hermes is a Go-based CLI tool for importing data from sources like Goodreads, IMDb, and Steam, and exporting it into Markdown, JSON, or SQLite/Datasette formats.
8
9- **Entrypoint**: `main.go` calls `cmd.Execute()` to start the Kong CLI application.
10- **Commands (`cmd/`)**: Each data importer is a self-contained package within a subdirectory (e.g., `cmd/goodreads/`, `cmd/steam/`). This is the primary location for adding or modifying importer logic.
11- **Shared Logic (`internal/`)**: Contains reusable packages for common functionality:
12 - `config`: Viper-based configuration management.
13 - `fileutil`: Helpers for writing Markdown and JSON files.
14 - `datastore`: SQLite and Datasette integration.
15 - `errors`: Custom error types (e.g., for rate limiting).
16- **Configuration**: Managed via a `config.yaml` file. CLI flags take precedence over config file settings.
17- **Output**: Data is written to `json/` and `markdown/` directories by default.
18- **Caching**: API responses are cached in the `cache/` directory, with subdirectories for each importer, to minimize external calls.
19
20## Developer Workflow
21
22The project uses `Taskfile.yml` for task automation.
23
24- **Build & Test**: `task build` - This is the primary command for development. It automatically runs tests, lints the code, and compiles the binary to `build/hermes`.
25- **Run Tests**: `task test` - Runs all tests and generates a coverage report in `coverage/`.
26- **Lint Code**: `task lint` - Runs `golangci-lint`.
27- **Run the CLI**: For development, use `go run . <command> [flags]`. For example: `go run . import goodreads -f path/to/export.csv`.
28
29## Key Development Patterns
30
31- **Adding a New Importer**:
32 1. Create a new package under `cmd/`.
33 2. Mimic the structure of an existing importer (e.g., `cmd/goodreads`):
34 - `cmd.go`: Kong command definition.
35 - `parser.go`: Logic for parsing the source data file.
36 - `types.go`: Structs for the data models.
37 - `api.go` (or similar): Client for external APIs (e.g., OMDB, OpenLibrary).
38 - `cache.go`, `json.go`, `markdown.go`: Handlers for caching and output formats.
39 3. Add the new command to `cmd/root.go`.
40
41- **Error Handling**:
42 - Return errors up the call stack.
43 - Wrap errors with context using `fmt.Errorf("...: %w", err)` to provide a clear trace.
44 - Use custom error types from `internal/errors` where applicable.
45
46- **Utilities**:
47 - Always use helpers from `internal/` for common tasks like file writing (`fileutil`) and configuration (`config`).
48 - Contribute new, reusable logic back to the `internal/` packages.
49
50- **Dependencies**:
51 - The project uses Go modules. Key libraries include `kong` for the CLI, `viper` for configuration, and `modernc.org/sqlite` for the database. Add new dependencies to `go.mod` only when necessary.
52
53## Gemini Agent Specific Notes
54- Always use `task build` to build the project.
lepinkainen/hermes · .clinerules/project-rules.md
@@ +1 @@
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
@@ −1 +1 @@
1−# Gemini Agent Guide for Hermes
1+# Hermes Project Rules
22
3−This guide provides essential information for developing in the Hermes codebase.
3+## Tech Stack Reference
44
5−## Project Overview & Architecture
5+See `llm-shared/project_tech_stack.md` for core technology choices, build system configuration, and library preferences.
66
7−Hermes is a Go-based CLI tool for importing data from sources like Goodreads, IMDb, and Steam, and exporting it into Markdown, JSON, or SQLite/Datasette formats.
7+## Project-Specific Guidelines
88
9−- **Entrypoint**: `main.go` calls `cmd.Execute()` to start the Kong CLI application.
10−- **Commands (`cmd/`)**: Each data importer is a self-contained package within a subdirectory (e.g., `cmd/goodreads/`, `cmd/steam/`). This is the primary location for adding or modifying importer logic.
11−- **Shared Logic (`internal/`)**: Contains reusable packages for common functionality:
12− - `config`: Viper-based configuration management.
13− - `fileutil`: Helpers for writing Markdown and JSON files.
14− - `datastore`: SQLite and Datasette integration.
15− - `errors`: Custom error types (e.g., for rate limiting).
16−- **Configuration**: Managed via a `config.yaml` file. CLI flags take precedence over config file settings.
17−- **Output**: Data is written to `json/` and `markdown/` directories by default.
18−- **Caching**: API responses are cached in the `cache/` directory, with subdirectories for each importer, to minimize external calls.
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
1911
20−## Developer Workflow
12+## Code Structure
2113
22−The project uses `Taskfile.yml` for task automation.
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
2317
24−- **Build & Test**: `task build` - This is the primary command for development. It automatically runs tests, lints the code, and compiles the binary to `build/hermes`.
25−- **Run Tests**: `task test` - Runs all tests and generates a coverage report in `coverage/`.
26−- **Lint Code**: `task lint` - Runs `golangci-lint`.
27−- **Run the CLI**: For development, use `go run . <command> [flags]`. For example: `go run . import goodreads -f path/to/export.csv`.
18+## Implementation Requirements
2819
29−## Key Development Patterns
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
3023
31−- **Adding a New Importer**:
32− 1. Create a new package under `cmd/`.
33− 2. Mimic the structure of an existing importer (e.g., `cmd/goodreads`):
34− - `cmd.go`: Kong command definition.
35− - `parser.go`: Logic for parsing the source data file.
36− - `types.go`: Structs for the data models.
37− - `api.go` (or similar): Client for external APIs (e.g., OMDB, OpenLibrary).
38− - `cache.go`, `json.go`, `markdown.go`: Handlers for caching and output formats.
39− 3. Add the new command to `cmd/root.go`.
24+## Error Handling
4025
41−- **Error Handling**:
42− - Return errors up the call stack.
43− - Wrap errors with context using `fmt.Errorf("...: %w", err)` to provide a clear trace.
44− - Use custom error types from `internal/errors` where applicable.
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.
4530
46−- **Utilities**:
47− - Always use helpers from `internal/` for common tasks like file writing (`fileutil`) and configuration (`config`).
48− - Contribute new, reusable logic back to the `internal/` packages.
31+## Configuration Management
4932
50−- **Dependencies**:
51− - The project uses Go modules. Key libraries include `kong` for the CLI, `viper` for configuration, and `modernc.org/sqlite` for the database. Add new dependencies to `go.mod` only when necessary.
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.
5237
53−## Gemini Agent Specific Notes
54−- Always use `task build` to build the project.
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+
