Repository Guidelines

Project Structure & Module Organization

The Go entrypoint lives in main.go, delegating to packages inside internal/. internal/config loads JSON config, internal/dl wraps yt-dlp invocation, internal/model defines show metadata, and internal/format, metadata, nfo, and scheduler handle parsing, artwork, and task orchestration. Sample configuration, OPML exports, and binary artifacts are kept at the repo root (config.json, youtube_subs.opml, subsyt, yt-dlp). Treat vids/ and tmp/ as working directories; avoid checking large media into git.

Build, Test, and Development Commands

CGO_ENABLED=0 go build -o subsyt: produce the statically linked binary expected by downstream deployments.
go run . --config=/path/to/config.json: execute against a config file; CONFIG=/abs/config.json also works.
go test ./...: run package tests; add -run TestName when iterating locally.
go fmt ./... && go vet ./...: format the tree and catch common correctness issues before review.

Coding Style & Naming Conventions

Follow idiomatic Go style enforced by gofmt. Packages stay lowercase (internal/dl), exported types use PascalCase, and helpers remain unexported unless they serve multiple packages. Keep configuration fields aligned with the JSON schema in internal/config; when introducing new options, document both the struct tags and sample configs.

Testing Guidelines

Write table-driven tests in _test.go files alongside the code under test, using Go’s standard testing package. Cover OPML parsing, identifier generation, and scheduler edge cases with realistic fixtures placed under testdata/ (create it if missing). Target branch coverage for new logic, and ensure go test ./... passes without external network calls by mocking downloader interfaces.

Commit & Pull Request Guidelines

Commits follow a Conventional Commits prefix (fix:, refactor:) in imperative mood, mirroring existing history (git log --oneline). Group related changes, and keep generated files out of the diff. Pull requests should summarize behavioural changes, note config schema updates, link to any tracking issues, and include before/after snippets or logs when touching downloader flows. Confirm the static binary still builds before requesting review.

Configuration & External Tools

Document expected locations for yt-dlp, cookies, and OPML files when altering defaults. If a change requires bgutil or other external services, provide startup commands and update the sample config.json. Ensure new options degrade gracefully for existing configs and call out migration steps in the PR description.

HTTP API

Enable the intake server with http_api.enable (default bind 0.0.0.0:6901). Set auth_token or point auth_token_file at a mounted secret, and use queue_file to persist pending jobs. Example: curl -H "Authorization: Bearer $TOKEN" -d '{"url":"https://youtu.be/ID","out_dir":"Channel"}' http://127.0.0.1:6901/v1/videos. Inspect the queue with curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:6901/status.

3.1 KiB Raw Blame History Unescape Escape