| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 11 | 11 | 4% |
| Commands | 4 | 5 | 4 | 31% |
| Section tags | 5 | 2 | 0 | 71% |
What each file covers
Sections
1 shared · 11 only in A · 11 only in B- − Repository Guidelines
- − Managing AI-Generated Planning Documents
- − AI planning documents (ephemeral)
- − Important Rules
- − LLM Reference
- − Project Structure & Module Organization
- − Build, Test, and Development Commands
- − Coding Style & Naming Conventions
- − Testing Guidelines
- − Commit & Pull Request Guidelines
- − Landing the Plane (Session Completion)
- + Hermes Project Rules for AI Agents
- + Project Purpose & Architecture
- + Developer Workflows
- + Code Structure & Patterns
- + Configuration & Flags
- + Logging & Error Handling
- + Output Conventions
- + Testing
- + Project Conventions
- + Integration Points
- + References
- Caching
Commands
4 shared · 5 only in A · 4 only in B- − git pull --rebase
- − git push
- − git status
- − go test -race -coverprofile=coverage/coverage.out ./...
- − go run ./cmd/root.go --help
- + task upgrade-deps
- + task clean
- + go run . import goodreads -f file.csv
- + task build-ci
- task build
- task test
- task lint
- go test ./...
Section tags
5 shared · 2 only in A · 0 only in B- − build
- − git-pr
- test
- lint-format
- code-style
- architecture
- do-not
Line diff
lepinkainen/hermes · AGENTS.md
@@ −1 @@
1# Repository Guidelines
2
3### Managing AI-Generated Planning Documents
4
5AI assistants often create planning and design documents during development:
6
7- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
8- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
9- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
10
11**Best Practice: Use a dedicated directory for these ephemeral files**
12
13**Recommended approach:**
14
15- Create a `history/` directory in the project root
16- Store ALL AI-generated planning/design docs in `history/`
17- Keep the repository root clean and focused on permanent project files
18- Only access `history/` when explicitly asked to review past planning
19
20**Example .gitignore entry (optional):**
21
22```
23# AI planning documents (ephemeral)
24history/
25```
26
27**Benefits:**
28
29- ✅ Clean repository root
30- ✅ Clear separation between ephemeral and permanent documentation
31- ✅ Easy to exclude from version control if desired
32- ✅ Preserves planning history for archeological research
33- ✅ Reduces noise when browsing the project
34
35### Important Rules
36
37- ✅ Store AI planning docs in `history/` directory
38- ✅ Always run `task build` before claiming work is done
39- ❌ Do NOT clutter repo root with planning documents
40
41### LLM Reference
42
43Need a quick tour of the shared helpers under `internal/`? Read `docs/internal_llm_reference.md` for package-by-package guidance before writing new utilities.
44
45## Project Structure & Module Organization
46
47- `main.go` wires the CLI and dispatches importer subcommands.
48- `cmd/` hosts CLI entrypoints per provider (e.g. `cmd/goodreads`, `cmd/steam`).
49- `internal/` contains shared services: `cache` for local stores, `datastore` for SQLite/JSON writers, `config` for settings.
50- `docs/` is the canonical reference; update it alongside behaviour changes and new flags.
51- Generated build and coverage artifacts live in `build/` and `coverage/`; sample exports under `exports/` and `json/` support local runs but keep large fixtures out of commits.
52
53## Caching
54
55- Hermes caches provider responses in `cache.db` (SQLite) in the repo root; it is safe to delete and is separate from `hermes.db`.
56- Default TTL is `720h` (30 days); override with `--cache-db-file`, `--cache-ttl`, or env vars `CACHE_DBFILE`/`CACHE_TTL`.
57- Tables are created automatically per provider (`omdb_cache`, `openlibrary_cache`, `steam_cache`, `letterboxd_cache`, `tmdb_cache`); entries past TTL refresh on next use and malformed entries are retried.
58- Warm caches by running the relevant importer once; invalidate selectively with `hermes cache invalidate tmdb|omdb|steam|letterboxd|openlibrary` or delete `cache.db` to clear everything.
59- Legacy JSON caches under `cache/` are deprecated and can be removed; negative TMDB results are intentionally not cached to allow future discoveries.
60
61## Build, Test, and Development Commands
62
63- `task build` runs lint, tests, and produces `build/hermes` with the current Git SHA embedded.
64- `task test` executes `go test -race -coverprofile=coverage/coverage.out ./...` and emits `coverage/coverage.html` for review.
65- `task lint` wraps `golangci-lint run ./...`; resolve findings before opening a PR.
66- `go run ./cmd/root.go --help` is a quick sanity check for new flags; swap in a provider folder (e.g. `./cmd/goodreads`) to exercise importer flows.
67
68## Coding Style & Naming Conventions
69
70- Format Go sources with `gofmt` or goimports integrations; Go defaults to tab-indentation, so avoid manual overrides.
71- Keep package names lowercase and singular; exported identifiers use UpperCamelCase, unexported ones use lowerCamelCase.
72- Prefer context-aware logging through the `humanlog` helpers and centralize config lookups in `internal/config` to keep importer packages lean.
73
74## Testing Guidelines
75
76- Co-locate `_test.go` files with the code under test; favour table-driven cases and `testify` assertions for clarity.
77- Run `task test` (or `go test ./...` when iterating) before pushing; inspect `coverage/coverage.html` for critical paths such as `internal/datastore` or importer pipelines.
78- Store lightweight fixtures under package-level `testdata/` directories and avoid reusing the large exports shipped at the repo root.
79
80## Commit & Pull Request Guidelines
81
82- Follow the existing Title-Case, imperative commit style (`Refactor caching`, `Add Steam importer config`) and keep each commit focused.
83- PRs should explain the motivation, list manual verification steps, and link issues; attach screenshots or sample output when behaviour is user-visible.
84- Before requesting review, ensure lint/tests pass, docs in `docs/` reflect the change, and configuration updates reference `config.yml` or `.env` expectations.
85
86## Landing the Plane (Session Completion)
87
88**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
89
90**MANDATORY WORKFLOW:**
91
921. **Note remaining work** - Capture anything that needs follow-up in the handoff
932. **Run quality gates** (if code changed) - Tests, linters, builds
943. **PUSH TO REMOTE** - This is MANDATORY:
95 ```bash
96 git pull --rebase
97 git push
98 git status # MUST show "up to date with origin"
99 ```
1004. **Clean up** - Clear stashes, prune remote branches
1015. **Verify** - All changes committed AND pushed
1026. **Hand off** - Provide context for next session
103
104**CRITICAL RULES:**
105- Work is NOT complete until `git push` succeeds
106- NEVER stop before pushing - that leaves work stranded locally
107- NEVER say "ready to push when you are" - YOU must push
108- If push fails, resolve and retry until it succeeds
109
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−# Repository Guidelines
1+# Hermes Project Rules for AI Agents
22
3−### Managing AI-Generated Planning Documents
3+## Project Purpose & Architecture
44
5−AI assistants often create planning and design documents during development:
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−- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
8−- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
9−- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
14+## Developer Workflows
1015
11−**Best Practice: Use a dedicated directory for these ephemeral files**
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.
1223
13−**Recommended approach:**
24+## Code Structure & Patterns
1425
15−- Create a `history/` directory in the project root
16−- Store ALL AI-generated planning/design docs in `history/`
17−- Keep the repository root clean and focused on permanent project files
18−- Only access `history/` when explicitly asked to review past planning
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.
1932
20−**Example .gitignore entry (optional):**
33+## Configuration & Flags
2134
22−```
23−# AI planning documents (ephemeral)
24−history/
25−```
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.
2639
27−**Benefits:**
40+## Logging & Error Handling
2841
29−- ✅ Clean repository root
30−- ✅ Clear separation between ephemeral and permanent documentation
31−- ✅ Easy to exclude from version control if desired
32−- ✅ Preserves planning history for archeological research
33−- ✅ Reduces noise when browsing the project
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).
3445
35−### Important Rules
46+## Output Conventions
3647
37−- ✅ Store AI planning docs in `history/` directory
38−- ✅ Always run `task build` before claiming work is done
39−- ❌ Do NOT clutter repo root with planning documents
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`.
4051
41−### LLM Reference
42−
43−Need a quick tour of the shared helpers under `internal/`? Read `docs/internal_llm_reference.md` for package-by-package guidance before writing new utilities.
44−
45−## Project Structure & Module Organization
46−
47−- `main.go` wires the CLI and dispatches importer subcommands.
48−- `cmd/` hosts CLI entrypoints per provider (e.g. `cmd/goodreads`, `cmd/steam`).
49−- `internal/` contains shared services: `cache` for local stores, `datastore` for SQLite/JSON writers, `config` for settings.
50−- `docs/` is the canonical reference; update it alongside behaviour changes and new flags.
51−- Generated build and coverage artifacts live in `build/` and `coverage/`; sample exports under `exports/` and `json/` support local runs but keep large fixtures out of commits.
52−
5352 ## Caching
5453
55−- Hermes caches provider responses in `cache.db` (SQLite) in the repo root; it is safe to delete and is separate from `hermes.db`.
56−- Default TTL is `720h` (30 days); override with `--cache-db-file`, `--cache-ttl`, or env vars `CACHE_DBFILE`/`CACHE_TTL`.
57−- Tables are created automatically per provider (`omdb_cache`, `openlibrary_cache`, `steam_cache`, `letterboxd_cache`, `tmdb_cache`); entries past TTL refresh on next use and malformed entries are retried.
58−- Warm caches by running the relevant importer once; invalidate selectively with `hermes cache invalidate tmdb|omdb|steam|letterboxd|openlibrary` or delete `cache.db` to clear everything.
59−- Legacy JSON caches under `cache/` are deprecated and can be removed; negative TMDB results are intentionally not cached to allow future discoveries.
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.
6057
61−## Build, Test, and Development Commands
58+## Testing
6259
63−- `task build` runs lint, tests, and produces `build/hermes` with the current Git SHA embedded.
64−- `task test` executes `go test -race -coverprofile=coverage/coverage.out ./...` and emits `coverage/coverage.html` for review.
65−- `task lint` wraps `golangci-lint run ./...`; resolve findings before opening a PR.
66−- `go run ./cmd/root.go --help` is a quick sanity check for new flags; swap in a provider folder (e.g. `./cmd/goodreads`) to exercise importer flows.
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 ./...`
6762
68−## Coding Style & Naming Conventions
63+## Project Conventions
6964
70−- Format Go sources with `gofmt` or goimports integrations; Go defaults to tab-indentation, so avoid manual overrides.
71−- Keep package names lowercase and singular; exported identifiers use UpperCamelCase, unexported ones use lowerCamelCase.
72−- Prefer context-aware logging through the `humanlog` helpers and centralize config lookups in `internal/config` to keep importer packages lean.
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.
7369
74−## Testing Guidelines
70+## Integration Points
7571
76−- Co-locate `_test.go` files with the code under test; favour table-driven cases and `testify` assertions for clarity.
77−- Run `task test` (or `go test ./...` when iterating) before pushing; inspect `coverage/coverage.html` for critical paths such as `internal/datastore` or importer pipelines.
78−- Store lightweight fixtures under package-level `testdata/` directories and avoid reusing the large exports shipped at the repo root.
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.
7974
80−## Commit & Pull Request Guidelines
75+## References
8176
82−- Follow the existing Title-Case, imperative commit style (`Refactor caching`, `Add Steam importer config`) and keep each commit focused.
83−- PRs should explain the motivation, list manual verification steps, and link issues; attach screenshots or sample output when behaviour is user-visible.
84−- Before requesting review, ensure lint/tests pass, docs in `docs/` reflect the change, and configuration updates reference `config.yml` or `.env` expectations.
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
8584
86−## Landing the Plane (Session Completion)
87−
88−**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
89−
90−**MANDATORY WORKFLOW:**
91−
92−1. **Note remaining work** - Capture anything that needs follow-up in the handoff
93−2. **Run quality gates** (if code changed) - Tests, linters, builds
94−3. **PUSH TO REMOTE** - This is MANDATORY:
95− ```bash
96− git pull --rebase
97− git push
98− git status # MUST show "up to date with origin"
99− ```
100−4. **Clean up** - Clear stashes, prune remote branches
101−5. **Verify** - All changes committed AND pushed
102−6. **Hand off** - Provide context for next session
103−
104−**CRITICAL RULES:**
105−- Work is NOT complete until `git push` succeeds
106−- NEVER stop before pushing - that leaves work stranded locally
107−- NEVER say "ready to push when you are" - YOU must push
108−- If push fails, resolve and retry until it succeeds
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
10988
