Cursor rule

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