| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 12 | 0% |
| Commands | 3 | 3 | 5 | 27% |
| Section tags | 2 | 1 | 3 | 33% |
What each file covers
Sections
0 shared · 5 only in A · 12 only in B- − Gemini Agent Guide for Hermes
- − Project Overview & Architecture
- − Developer Workflow
- − Key Development Patterns
- − Gemini Agent Specific Notes
- + Hermes Project Rules for AI Agents
- + Project Purpose & Architecture
- + Developer Workflows
- + Code Structure & Patterns
- + Configuration & Flags
- + Logging & Error Handling
- + Output Conventions
- + Caching
- + Testing
- + Project Conventions
- + Integration Points
- + References
Commands
3 shared · 3 only in A · 5 only in B- − go run . <command> [flags]
- − go run . import goodreads -f path/to/export.csv
- − go.mod
- + task upgrade-deps
- + task clean
- + go run . import goodreads -f file.csv
- + task build-ci
- + go test ./...
- task build
- task test
- task lint
Section tags
2 shared · 1 only in A · 3 only in B- − agent-behaviour
- + test
- + lint-format
- + do-not
- code-style
- 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 · .cursor/rules/project-rules.mdc
@@ +1 @@
1# Hermes Project Rules for AI Agents
2
3## Project Purpose & Architecture
4
5- **Hermes** is a Go CLI tool to import/export data from sources (Goodreads, IMDb, Letterboxd, Steam) into Markdown, JSON, or SQLite/Datasette formats. See [docs/01_overview.md](../docs/01_overview.md) and [docs/03_architecture.md](../docs/03_architecture.md).
6- **Architecture:**
7 - `cmd/` – Each data source importer is a subdir/package (e.g., `cmd/goodreads/`).
8 - `internal/` – Shared utilities: `cmdutil/`, `config/`, `datastore/`, `errors/`, `fileutil/`, `humanlog/`.
9 - `cache/` – API response cache, organized by importer.
10 - `json/`, `markdown/` – Output directories, with subdirs per importer.
11 - `Taskfile.yml` – Build/test/lint automation.
12 - `main.go` – Entry point, runs `cmd.Execute()`.
13
14## Developer Workflows
15
16- **Build:** `task build` (runs tests, lint, then builds to `build/hermes`)
17- **Test:** `task test` (with coverage report in `coverage/`)
18- **Lint:** `task lint` (uses `golangci-lint`)
19- **Upgrade deps:** `task upgrade-deps`
20- **Clean:** `task clean`
21- **Run CLI:** `./hermes --help` or `go run . import goodreads -f file.csv`
22- **CI:** Use `task build-ci` for CI builds/tests.
23
24## Code Structure & Patterns
25
26- **Importers:** Each under `cmd/{source}/` with:
27 - `cmd.go` (command setup), `parser.go` (input parsing), `types.go` (models), `{api}.go` (API integration), `cache.go`, `json.go`, `markdown.go`, `testdata/`.
28- **Shared logic:** Use/extend `internal/` packages. Contribute reusable code back.
29- **Datastore:** Use `internal/datastore/` for SQLite (local) or Datasette (remote) output. See [docs/datasette_integration.md](../docs/datasette_integration.md).
30- **Output:** Use `internal/fileutil` for Markdown/JSON writing. Follow frontmatter and file naming conventions ([docs/05_output_formats.md](../docs/05_output_formats.md)).
31- **Caching:** Implemented per-importer in `cache.go`, stores JSON in `cache/{importer}/`. Always check cache before API calls.
32
33## Configuration & Flags
34
35- **Config:** YAML file (`config.yaml`), loaded via Viper. CLI flags > env vars > config file > defaults. See [docs/04_configuration.md](../docs/04_configuration.md).
36- **Global settings:** Output dirs, overwrite flag, loglevel.
37- **Importer settings:** Namespaced under importer key (e.g., `goodreads.csvfile`).
38- **Datasette:** Enable with config or flags for SQLite/remote export.
39
40## Logging & Error Handling
41
42- **Logging:** Use Go's `log/slog` with custom handler (`http://github.com/lepinkainen/humanlog`). Levels: Debug, Info, Warn, Error. Log progress, context, and errors. See [docs/07_logging_error_handling.md](../docs/07_logging_error_handling.md).
43- **Errors:** Return errors up the stack, wrap with context (`fmt.Errorf("context: %w", err)`). Use custom types (e.g., `RateLimitError` in `internal/errors/`).
44- **Recoverable errors:** Log and continue (e.g., skip item, warn on API miss).
45
46## Output Conventions
47
48- **Markdown:** YAML frontmatter with all metadata, Obsidian-compatible. Use `MarkdownBuilder` from `internal/fileutil/markdown.go`.
49- **JSON:** One file per item or array per importer. See examples in [docs/05_output_formats.md](../docs/05_output_formats.md).
50- **File naming:** Sanitize titles/IDs, use underscores/hyphens, add `.md`/`.json`.
51
52## Caching
53
54- **Location:** `cache/{importer}/` (e.g., `cache/goodreads/`).
55- **Format:** JSON, filename = cache key (e.g., ISBN, IMDb ID).
56- **Control:** Can disable/clear via flags. TTL and per-importer settings supported.
57
58## Testing
59
60- **Unit tests:** Place in `_test.go` in same package. Use `testdata/` for fixtures. Table-driven tests preferred.
61- **Run:** `task test` or `go test ./...`
62
63## Project Conventions
64
65- **Language:** Go only. Use idiomatic Go style. Run `gofmt -w .`.
66- **CLI:** Use Cobra/Kong for commands, Viper for config.
67- **Dependencies:** Prefer stdlib, justify new deps. Use `modernc.org/sqlite` for SQLite.
68- **Docs:** Update `docs/` and Go doc comments for all exported symbols. Keep CLI help up to date.
69
70## Integration Points
71
72- **APIs:** OMDB (IMDb/Letterboxd), OpenLibrary (Goodreads), Steam API. Respect rate limits, cache responses, handle errors.
73- **Datasette:** Local (SQLite) or remote (API). Use `internal/datastore/` abstraction.
74
75## References
76
77- [docs/01_overview.md](../docs/01_overview.md) – Project overview
78- [docs/03_architecture.md](../docs/03_architecture.md) – Architecture
79- [docs/04_configuration.md](../docs/04_configuration.md) – Configuration
80- [docs/05_output_formats.md](../docs/05_output_formats.md) – Output formats
81- [docs/06_caching.md](../docs/06_caching.md) – Caching
82- [docs/07_logging_error_handling.md](../docs/07_logging_error_handling.md) – Logging & error handling
83- [llm-shared/project_tech_stack.md](../../llm-shared/project_tech_stack.md) – Tech stack
84
85- Maintain consistent Go style and idiomatic patterns
86- Follow the existing architectural patterns
87- Each data source processor should be implemented as a separate command
88
@@ −1 +1 @@
1−# Gemini Agent Guide for Hermes
1+# Hermes Project Rules for AI Agents
22
3−This guide provides essential information for developing in the Hermes codebase.
3+## Project Purpose & Architecture
44
5−## Project Overview & Architecture
5+- **Hermes** is a Go CLI tool to import/export data from sources (Goodreads, IMDb, Letterboxd, Steam) into Markdown, JSON, or SQLite/Datasette formats. See [docs/01_overview.md](../docs/01_overview.md) and [docs/03_architecture.md](../docs/03_architecture.md).
6+- **Architecture:**
7+ - `cmd/` – Each data source importer is a subdir/package (e.g., `cmd/goodreads/`).
8+ - `internal/` – Shared utilities: `cmdutil/`, `config/`, `datastore/`, `errors/`, `fileutil/`, `humanlog/`.
9+ - `cache/` – API response cache, organized by importer.
10+ - `json/`, `markdown/` – Output directories, with subdirs per importer.
11+ - `Taskfile.yml` – Build/test/lint automation.
12+ - `main.go` – Entry point, runs `cmd.Execute()`.
613
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.
14+## Developer Workflows
815
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.
16+- **Build:** `task build` (runs tests, lint, then builds to `build/hermes`)
17+- **Test:** `task test` (with coverage report in `coverage/`)
18+- **Lint:** `task lint` (uses `golangci-lint`)
19+- **Upgrade deps:** `task upgrade-deps`
20+- **Clean:** `task clean`
21+- **Run CLI:** `./hermes --help` or `go run . import goodreads -f file.csv`
22+- **CI:** Use `task build-ci` for CI builds/tests.
1923
20−## Developer Workflow
24+## Code Structure & Patterns
2125
22−The project uses `Taskfile.yml` for task automation.
26+- **Importers:** Each under `cmd/{source}/` with:
27+ - `cmd.go` (command setup), `parser.go` (input parsing), `types.go` (models), `{api}.go` (API integration), `cache.go`, `json.go`, `markdown.go`, `testdata/`.
28+- **Shared logic:** Use/extend `internal/` packages. Contribute reusable code back.
29+- **Datastore:** Use `internal/datastore/` for SQLite (local) or Datasette (remote) output. See [docs/datasette_integration.md](../docs/datasette_integration.md).
30+- **Output:** Use `internal/fileutil` for Markdown/JSON writing. Follow frontmatter and file naming conventions ([docs/05_output_formats.md](../docs/05_output_formats.md)).
31+- **Caching:** Implemented per-importer in `cache.go`, stores JSON in `cache/{importer}/`. Always check cache before API calls.
2332
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`.
33+## Configuration & Flags
2834
29−## Key Development Patterns
35+- **Config:** YAML file (`config.yaml`), loaded via Viper. CLI flags > env vars > config file > defaults. See [docs/04_configuration.md](../docs/04_configuration.md).
36+- **Global settings:** Output dirs, overwrite flag, loglevel.
37+- **Importer settings:** Namespaced under importer key (e.g., `goodreads.csvfile`).
38+- **Datasette:** Enable with config or flags for SQLite/remote export.
3039
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+## Logging & Error Handling
4041
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.
42+- **Logging:** Use Go's `log/slog` with custom handler (`http://github.com/lepinkainen/humanlog`). Levels: Debug, Info, Warn, Error. Log progress, context, and errors. See [docs/07_logging_error_handling.md](../docs/07_logging_error_handling.md).
43+- **Errors:** Return errors up the stack, wrap with context (`fmt.Errorf("context: %w", err)`). Use custom types (e.g., `RateLimitError` in `internal/errors/`).
44+- **Recoverable errors:** Log and continue (e.g., skip item, warn on API miss).
4545
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.
46+## Output Conventions
4947
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.
48+- **Markdown:** YAML frontmatter with all metadata, Obsidian-compatible. Use `MarkdownBuilder` from `internal/fileutil/markdown.go`.
49+- **JSON:** One file per item or array per importer. See examples in [docs/05_output_formats.md](../docs/05_output_formats.md).
50+- **File naming:** Sanitize titles/IDs, use underscores/hyphens, add `.md`/`.json`.
5251
53−## Gemini Agent Specific Notes
54−- Always use `task build` to build the project.
52+## Caching
53+
54+- **Location:** `cache/{importer}/` (e.g., `cache/goodreads/`).
55+- **Format:** JSON, filename = cache key (e.g., ISBN, IMDb ID).
56+- **Control:** Can disable/clear via flags. TTL and per-importer settings supported.
57+
58+## Testing
59+
60+- **Unit tests:** Place in `_test.go` in same package. Use `testdata/` for fixtures. Table-driven tests preferred.
61+- **Run:** `task test` or `go test ./...`
62+
63+## Project Conventions
64+
65+- **Language:** Go only. Use idiomatic Go style. Run `gofmt -w .`.
66+- **CLI:** Use Cobra/Kong for commands, Viper for config.
67+- **Dependencies:** Prefer stdlib, justify new deps. Use `modernc.org/sqlite` for SQLite.
68+- **Docs:** Update `docs/` and Go doc comments for all exported symbols. Keep CLI help up to date.
69+
70+## Integration Points
71+
72+- **APIs:** OMDB (IMDb/Letterboxd), OpenLibrary (Goodreads), Steam API. Respect rate limits, cache responses, handle errors.
73+- **Datasette:** Local (SQLite) or remote (API). Use `internal/datastore/` abstraction.
74+
75+## References
76+
77+- [docs/01_overview.md](../docs/01_overview.md) – Project overview
78+- [docs/03_architecture.md](../docs/03_architecture.md) – Architecture
79+- [docs/04_configuration.md](../docs/04_configuration.md) – Configuration
80+- [docs/05_output_formats.md](../docs/05_output_formats.md) – Output formats
81+- [docs/06_caching.md](../docs/06_caching.md) – Caching
82+- [docs/07_logging_error_handling.md](../docs/07_logging_error_handling.md) – Logging & error handling
83+- [llm-shared/project_tech_stack.md](../../llm-shared/project_tech_stack.md) – Tech stack
84+
85+- Maintain consistent Go style and idiomatic patterns
86+- Follow the existing architectural patterns
87+- Each data source processor should be implemented as a separate command
88+
