GEMINI.md

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.