AGENTS.md

1# Internal Go Guidelines
2 
3**Last Updated:** April 9, 2026
4 
5This file applies to `internal/` and defers subtree-specific rules to the narrower guides under `internal/api/`, `internal/config/`, `internal/commands/`, `internal/photoprism/`, and `internal/service/cluster/`.
6 
7## Internal Linting
8 
9- Run `make lint-go` after Go changes; for focused work, prefer `golangci-lint run ./internal/<pkg>/...`.
10 
11## Logging, Naming & Status
12 
13- When adding GORM struct fields with uppercase abbreviations such as `LabelNSFW`, `UserID`, or `URLHash`, set an explicit `gorm:"column:<name>"` tag so column names stay stable.
14- Use the shared logger via the package-level `log` variable backed by `event.Log`; avoid `fmt.Print*` and ad-hoc loggers.
15- In human-readable log text, prefer `instance` and `service`; reserve `node` for contract-bound names such as `/cluster/nodes`, `Node*`, and `PHOTOPRISM_NODE_*`.
16- End every `event.Audit*` slice with exactly one status token from `pkg/log/status`, such as `status.Succeeded`, `status.Failed`, or `status.Denied`.
17- When the outcome should be a sanitized error string, use `status.Error(err)` instead of hand-building it.
18 
19## Internal Tests & Fixtures
20 
21- Keep Go scratch work inside `internal/...`; Go rejects imports from `internal/` when helpers live under paths such as `/tmp`.
22- Heavy packages such as `internal/entity` and `internal/photoprism` run migrations and fixtures; expect slower first runs and narrow them with `-run`.
23- For database updates, prefer `entity.Values` over raw `map[string]interface{}`.
24- When adding persistent fixtures, generate IDs with `rnd.GenerateUID(...)` and the matching prefix instead of inventing manual strings.
25- Prefer `config.NewMinimalTestConfig(t.TempDir())` for filesystem or config scaffolding and `config.NewMinimalTestConfigWithDb("<name>", t.TempDir())` for isolated SQLite schemas.
26- `internal/config` test helpers now auto-discover the repository `assets/` directory; do not set `PHOTOPRISM_ASSETS_PATH` manually in `init()` unless you truly have a non-standard layout.
27- Hub API traffic is disabled in tests by default via `hub.ApplyTestConfig()`; opt back in with `PHOTOPRISM_TEST_HUB=test`.
28- Avoid `config.TestConfig()` in new tests unless you need the fully seeded singleton fixture set; tests that write to Originals or Import should use isolated minimal configs plus `conf.CreateDirectories()`.
29- `config.NewTestConfig("<pkg>")` defaults to SQLite with a per-suite DSN such as `.<pkg>.db`; do not assert an empty DSN, and clean up captured DSNs with `t.Cleanup(...)` if needed.
30- `NewTestConfig("<pkg>")` already calls `InitializeTestData()`. If you build a custom config, call `c.InitializeTestData()` and optionally `c.AssertTestData(t)` so Originals, Import, cache, and temp exist.
31- `PhotoFixtures.Get()` and similar helpers return value copies; re-query with helpers such as `entity.FindPhoto(...)` when a test needs the persisted row with associations.
32- Reuse shared `Example*` constants for illustrative credentials in tests and docs.
33 
34## Focused Internal Test Runs
35 
36- Thumbnails: `go test ./internal/thumb/... -count=1`
37- FFmpeg command builders: `go test ./internal/ffmpeg -run 'Remux|Transcode|Extract' -count=1`
38 
39## FFmpeg Hardware Gating
40 
41- Do not run GPU or hardware encoder integrations in CI by default; gate them with `PHOTOPRISM_FFMPEG_ENCODER` set to `vaapi`, `intel`, or `nvidia`.
42- Keep negative-path ffmpeg tests fast and always runnable: missing ffmpeg should fail immediately, and unwritable destinations should fail without creating files.
43- When hardware is unavailable, prefer command-string assertions; enable full hardware runs locally only when a device is configured.
44