apps/photoprism
1
0
Fork 0
mirror of https://github.com/photoprism/photoprism.git synced 2025-09-26 12:51:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

CLI: Update Download CLI developer docs and testing hints #5219

Browse Source 
Signed-off-by: Michael Mayer <michael@photoprism.app>
This commit is contained in:
Michael Mayer
2025-09-20 14:59:48 +02:00
parent f7fe6b569a
commit ecdec6b408
2 changed files with 55 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
AGENTS.md
View File

@@ -262,6 +262,42 @@ The following conventions summarize the insights gained when adding new configur
- CLI commands: Some commands defer `conf.Shutdown()` or emit signals that close the DB. The harness re‑opens DB before each run, but avoid invoking `start` or emitting signals in unit tests.
- Signals: `internal/commands/start.go` waits on `process.Signal`; calling `process.Shutdown()/Restart()` can close DB. Prefer not to trigger signals in tests.
### Download CLI Workbench (yt-dlp, remux, importer)
- Code anchors
- CLI flags and examples: `internal/commands/download.go`
- Core implementation (testable): `internal/commands/download_impl.go`
- yt-dlp helpers and arg wiring: `internal/photoprism/dl/*` (`options.go`, `info.go`, `file.go`, `meta.go`)
- Importer entry point: `internal/photoprism/get/import.go`; options: `internal/photoprism/import_options.go`
- Quick test runs (fast feedback)
- yt-dlp package: `go test ./internal/photoprism/dl -run 'Options|Created|PostprocessorArgs' -count=1`
- CLI command: `go test ./internal/commands -run 'DownloadImpl|HelpFlags' -count=1`
- FFmpeg-less tests
- In tests: set `c.Options().FFmpegBin = "/bin/false"` and `c.Settings().Index.Convert = false` to avoid ffmpeg dependencies when not validating remux.
- Stubbing yt-dlp (no network)
- Use a tiny shell script that:
- prints minimal JSON for `--dump-single-json`
- creates a file and prints its path when `--print` is requested
- Harness env vars (supported by our tests):
- `YTDLP_ARGS_LOG` — append final args for assertion
- `YTDLP_OUTPUT_FILE` — absolute file path to create for `--print`
- `YTDLP_DUMMY_CONTENT` — file contents to avoid importer duplicate detection between tests
- Remux policy and metadata
- Pipe method: PhotoPrism remux (ffmpeg) always embeds title/description/created.
- File method: yt‑dlp writes files; we pass `--postprocessor-args 'ffmpeg:-metadata creation_time=<RFC3339>'` so imports get `Created` even without local remux (fallback from `upload_date`/`release_date`).
- Default remux policy: `auto`; use `always` for the most complete metadata (chapters, extended tags).
- Testing
- Prefer targeted runs before the full suite:
- `go test ./internal/<pkg> -run <Name> -count=1`
- Avoid `./...` unless you intend to run everything.
- Importer duplicates: When reusing names/paths across tests, the importer may dedupe; vary file bytes via `YTDLP_DUMMY_CONTENT` or adjust `dest` to ensure assertions see the new file.
- Long-running packages: `internal/photoprism` is heavy; validate CLI/dl changes first in their packages, then run broader suites.
### Sessions & Redaction (building sessions in tests)
- Admin session (full view): `AuthenticateAdmin(app, router)`.

19
CODEMAP.md
View File

@@ -157,6 +157,25 @@ Frequently Touched Files (by topic)
- Cluster: `internal/service/cluster/*`
- Headers: `pkg/service/http/header/*`
Downloads (CLI) & yt-dlp helpers
- CLI command & core:
- `internal/commands/download.go` (flags, defaults, examples)
- `internal/commands/download_impl.go` (testable implementation used by CLI)
- yt-dlp wrappers:
- `internal/photoprism/dl/options.go` (arg wiring; `FFmpegPostArgs` hook for `--postprocessor-args`)
- `internal/photoprism/dl/info.go` (metadata discovery)
- `internal/photoprism/dl/file.go` (file method with `--output`/`--print`)
- `internal/photoprism/dl/meta.go` (`CreatedFromInfo` fallback; `RemuxOptionsFromInfo`)
- Importer:
- `internal/photoprism/get/import.go` (work pool)
- `internal/photoprism/import_options.go` (`ImportOptionsMove/Copy`)
- Testing hints:
- Fast loops: `go test ./internal/photoprism/dl -run 'Options|Created|PostprocessorArgs' -count=1`
- CLI only: `go test ./internal/commands -run 'DownloadImpl|HelpFlags' -count=1`
- Disable ffmpeg when not needed: set `FFmpegBin = "/bin/false"`, `Settings.Index.Convert=false` in tests.
- Stub yt-dlp: shell script that prints JSON for `--dump-single-json`, creates a file and prints path for `--print`.
- Avoid importer dedup: vary file bytes (e.g., `YTDLP_DUMMY_CONTENT`) or dest.
Useful Make Targets (selection)
- `make help` — list targets
- `make dep` — install Go/JS deps in container