87 lines
4.0 KiB
Markdown
87 lines
4.0 KiB
Markdown
# AGENTS.md
|
|
|
|
## Repo Overview
|
|
|
|
- Purpose: run `restic backup` against a Wasabi S3-compatible repository.
|
|
- Main entry point: `travel-backup-script.py`.
|
|
- Dependencies are intentionally minimal:
|
|
- Python standard library
|
|
- `python-dotenv`
|
|
- External binary: `restic` must already be installed and available on `PATH`
|
|
- There are currently no tests, package metadata files, or CI config in this repo.
|
|
|
|
## File Map
|
|
|
|
- `travel-backup-script.py`: single-script CLI implementation.
|
|
- `requirements.txt`: Python dependency list (`python-dotenv` only).
|
|
- `README.md`: user-facing setup and usage docs.
|
|
- `.env.example`: template for environment variables.
|
|
- `.gitignore`: ignores `.env.*` files (except `.env.example`).
|
|
|
|
## Current Script Behavior
|
|
|
|
The script uses two subcommands: `init` and `backup`.
|
|
|
|
1. Loads `.env.local` automatically via `load_dotenv(".env.local")`.
|
|
2. Parses CLI args into subcommands with shared repo flags and backup-specific source flags.
|
|
3. Resolves the repository string:
|
|
- `--repository` / `RESTIC_REPOSITORY` takes priority (validated against `s3:s3.<region>.wasabisys.com/...` format).
|
|
- Otherwise built from `--bucket` / `WASABI_BUCKET`, `--region` / `WASABI_REGION`, `WASABI_ENDPOINT`, and `--prefix` / `RESTIC_PREFIX`.
|
|
4. Constructs a minimal subprocess environment for `restic`:
|
|
- `WASABI_ENDPOINT`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `RESTIC_PASSWORD`
|
|
- `PATH`, `HOME` if present
|
|
- `SYSTEMROOT`, `SystemRoot`, `COMSPEC` (Windows-specific, required for DNS resolution and shell access)
|
|
5. For `init`: runs `restic init` against the resolved repository.
|
|
6. For `backup`: resolves input from `--source`, `--file`, or `FILE_PATH_CONFIG_PATH` env var, then runs `restic backup`.
|
|
7. Prints the repo, command, and redacted env status before optionally executing `restic`.
|
|
|
|
## Known Drift / Things To Watch
|
|
|
|
- The JSON config file must contain a top-level `paths` key with a non-empty array of non-empty strings.
|
|
- `--source` and `--file` are mutually exclusive; one of them or `FILE_PATH_CONFIG_PATH` is required for backup.
|
|
- `--region` has no default — it must be provided via CLI or `WASABI_REGION` when not using `--repository`.
|
|
|
|
## Local Development Workflow
|
|
|
|
Use this order when changing the repo:
|
|
|
|
1. Read `travel-backup-script.py` first. Nearly all behavior lives there.
|
|
2. Treat `README.md` as partially authoritative only after comparing it to the script.
|
|
3. If you change CLI flags, env loading, or repository construction, update code, README, and `.env.example` in the same change.
|
|
4. Preserve secret-handling behavior. Do not print raw credentials.
|
|
|
|
## Suggested Verification
|
|
|
|
Because the repo has no automated tests, prefer lightweight verification:
|
|
|
|
- Static review of argument parsing and env handling.
|
|
- Dry-run init:
|
|
- `python travel-backup-script.py init --bucket <bucket> --region <region> --dry-run`
|
|
- Dry-run backup with a direct source:
|
|
- `python travel-backup-script.py backup --source <path> --bucket <bucket> --region <region> --dry-run`
|
|
- Dry-run backup with a JSON config file:
|
|
- `python travel-backup-script.py backup --file <config.json> --bucket <bucket> --region <region> --dry-run`
|
|
|
|
Avoid real backup runs unless the user explicitly asks for them and valid credentials are present.
|
|
|
|
## Editing Guidelines
|
|
|
|
- Keep the implementation as a simple single-file CLI unless the user asks for a larger refactor.
|
|
- Favor backwards-compatible flag changes where practical.
|
|
- Be careful with subprocess environment changes:
|
|
- `PATH` must remain available so `restic` can be found.
|
|
- `HOME` is intentionally forwarded when present.
|
|
- On Windows, `SYSTEMROOT` and `COMSPEC` are required for DNS resolution and shell access.
|
|
- Do not commit real `.env.local` or other secret files.
|
|
- If adding tests later, prefer small CLI/unit tests around:
|
|
- `build_repo`
|
|
- `load_sources`
|
|
- `resolve_repo` (priority order, validation)
|
|
- missing `--bucket` handling
|
|
- env minimization/redaction behavior
|
|
|
|
## Agent Notes
|
|
|
|
- Start discovery from the script, not the README.
|
|
- Keep `README.md`, `.env.example`, and the script aligned when flags change.
|