feat(backup)!: mandatory repo-name and databases-csv, --only-files, --only-sql

Two defaults could not be right. --repo-name fell back to the literal 'backup-docker-to-local' while its help promised the git repo folder name, which nothing ever derived. --databases-csv pointed inside the installed package directory, where credentials must not live; when it applied, load_databases_df read a missing file as empty and the run finished without a single dump and without an error. Both are required now, --repo-name in the restore CLI too. The file itself may still be absent - babadcb's tolerance is untouched, only the path must be named.

--everything is withdrawn. Its one effect was to ignore --images-no-stop-required, which is what leaving that list empty already does, and its branch was the default path minus the requires_stop check. No caller, no test, and help and README described it differently.

--dump-only-sql becomes --only-sql, and --only-files joins it as the opposite half: no dumps at all, every volume as files. They form a mutually exclusive group. A host that only copies files has no business holding database passwords, so --databases-csv is not required there and is never read.

The smallest valid argv turned out to be written four times across the test tree; it now lives once. Withdrawn flags are listed in one place and proven to exit 2.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

tests/unit/backup/__init__.py

@@ -0,0 +1,10 @@
+"""The smallest argv the backup CLI accepts, shared by every test that drives it."""
+
+REQUIRED_PAIRS = [
+    ("--compose-dir", "/compose"),
+    ("--backups-dir", "/backups"),
+    ("--repo-name", "stack"),
+    ("--databases-csv", "/etc/baudolo/databases.csv"),
+]
+REQUIRED = [arg for pair in REQUIRED_PAIRS for arg in pair]
+BASE_ARGV = ["baudolo", *REQUIRED]

tests/unit/backup/test_app_only_files.py

@@ -0,0 +1,65 @@
+"""Contract of --only-files: no dump is attempted, every volume is copied."""
+
+from __future__ import annotations
+
+import unittest
+from unittest import mock
+
+from baudolo.backup import app
+from baudolo.backup.volume import Backing
+
+from . import REQUIRED_PAIRS
+
+ARGV_WITHOUT_CSV = [
+    "baudolo",
+    *[arg for pair in REQUIRED_PAIRS if pair[0] != "--databases-csv" for arg in pair],
+    "--only-files",
+]
+
+
+def drive(argv: list[str]) -> tuple[list[str], list, list]:
+    backed_up: list[str] = []
+
+    def record_backup(versions_dir, volume_name, volume_dir, *, authoritative, source):
+        backed_up.append(volume_name)
+
+    with (
+        mock.patch("sys.argv", argv),
+        mock.patch.object(app, "get_machine_id", return_value="machine"),
+        mock.patch.object(app, "create_version_directory", return_value="/gen"),
+        mock.patch.object(app, "create_volume_directory", return_value="/gen/vol"),
+        mock.patch.object(app, "load_databases_df") as load_csv,
+        mock.patch.object(app, "docker_volume_names", return_value=["pgdata"]),
+        mock.patch.object(app, "containers_using_volume", return_value=["db"]),
+        mock.patch.object(app, "volume_is_fully_ignored", return_value=False),
+        mock.patch.object(app, "backup_dumps_for_volume") as dumps,
+        mock.patch.object(app, "inspect_backing", return_value=Backing("/data")),
+        mock.patch.object(app, "stamp_directory"),
+        mock.patch.object(app, "handle_docker_compose_services"),
+        mock.patch.object(app.os.path, "isdir", return_value=True),
+        mock.patch.object(app, "backup_volume", side_effect=record_backup),
+        mock.patch.object(app, "filter_stoppable", return_value=[]),
+        mock.patch.object(app, "requires_stop", return_value=False),
+        mock.patch.object(app, "change_containers_status"),
+    ):
+        app.main()
+    return backed_up, dumps.mock_calls, load_csv.mock_calls
+
+
+class TestOnlyFiles(unittest.TestCase):
+    def test_no_dump_is_attempted(self) -> None:
+        _backed_up, dumps, _load_csv = drive(ARGV_WITHOUT_CSV)
+        self.assertEqual(dumps, [])
+
+    def test_the_databases_csv_is_never_read(self) -> None:
+        """It may legitimately be absent, so reading it would abort the run."""
+        _backed_up, _dumps, load_csv = drive(ARGV_WITHOUT_CSV)
+        self.assertEqual(load_csv, [])
+
+    def test_the_volume_is_still_copied(self) -> None:
+        backed_up, _dumps, _load_csv = drive(ARGV_WITHOUT_CSV)
+        self.assertEqual(backed_up, ["pgdata"])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/backup/test_app_snapshot.py

@@ -10,17 +10,15 @@ from baudolo.backup import snapshot as snapshot_mod
 from baudolo.backup.snapshot import volume_snapshot
 from baudolo.backup.volume import Backing
 
+from . import BASE_ARGV
+
 
 def stubbed_snapshot(kind: str, subject: str, tag: str):
     return volume_snapshot(kind, subject, tag, run=lambda command: [])
 
 
 ARGV = [
-    "baudolo",
-    "--compose-dir",
-    "/compose",
-    "--backups-dir",
-    "/backups",
+    *BASE_ARGV,
     "--snapshot",
     "btrfs",
     "--snapshot-subject",

tests/unit/backup/test_app_volumes_no_backup_required.py

@@ -9,12 +9,10 @@ from unittest import mock
 from baudolo.backup import app
 from baudolo.backup.volume import Backing
 
+from . import BASE_ARGV
+
 ARGV = [
-    "baudolo",
-    "--compose-dir",
-    "/compose",
-    "--backups-dir",
-    "/backups",
+    *BASE_ARGV,
     "--volumes-no-backup-required",
     "derived",
 ]

tests/unit/backup/test_cli.py

@@ -7,7 +7,7 @@ from unittest import mock
 
 from baudolo.backup.cli import parse_args
 
-REQUIRED = ["--compose-dir", "/compose", "--backups-dir", "/backups"]
+from . import REQUIRED, REQUIRED_PAIRS
 
 
 def parse(*extra: str):
@@ -68,19 +68,42 @@ class TestSnapshotFlags(unittest.TestCase):
 
 
 class TestRequiredFlags(unittest.TestCase):
-    def test_backups_dir_is_required(self) -> None:
-        with (
-            mock.patch("sys.argv", ["baudolo", "--compose-dir", "/compose"]),
-            self.assertRaises(SystemExit),
-        ):
-            parse_args()
+    def test_no_flag_falls_back_to_a_default(self) -> None:
+        for omitted, _ in REQUIRED_PAIRS:
+            argv = [a for pair in REQUIRED_PAIRS if pair[0] != omitted for a in pair]
+            with (
+                self.subTest(omitted=omitted),
+                mock.patch("sys.argv", ["baudolo", *argv]),
+                self.assertRaises(SystemExit),
+            ):
+                parse_args()
 
-    def test_compose_dir_is_required(self) -> None:
-        with (
-            mock.patch("sys.argv", ["baudolo", "--backups-dir", "/backups"]),
-            self.assertRaises(SystemExit),
-        ):
-            parse_args()
+
+class TestBackupScope(unittest.TestCase):
+    """--only-sql and --only-files name the two halves a generation can hold."""
+
+    def test_both_halves_by_default(self) -> None:
+        args = parse()
+        self.assertFalse(args.only_sql)
+        self.assertFalse(args.only_files)
+
+    def test_either_half_alone_is_accepted(self) -> None:
+        self.assertTrue(parse("--only-sql").only_sql)
+        self.assertTrue(parse("--only-files").only_files)
+
+    def test_asking_for_both_halves_alone_is_rejected(self) -> None:
+        with self.assertRaises(SystemExit):
+            parse("--only-sql", "--only-files")
+
+    def test_only_files_needs_no_databases_csv(self) -> None:
+        argv = [
+            arg
+            for pair in REQUIRED_PAIRS
+            if pair[0] != "--databases-csv"
+            for arg in pair
+        ]
+        with mock.patch("sys.argv", ["baudolo", *argv, "--only-files"]):
+            self.assertIsNone(parse_args().databases_csv)
 
 
 if __name__ == "__main__":

tests/unit/backup/test_compose_hard_restart.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import unittest
 from unittest.mock import patch
 
+from . import BASE_ARGV
+
 
 class HardRestartArgTests(unittest.TestCase):
     """The hard-restart list defaults to empty (no compose down/up); callers
@@ -16,11 +18,7 @@ class HardRestartArgTests(unittest.TestCase):
         from baudolo.backup import cli
 
         argv = [
-            "baudolo",
-            "--compose-dir",
-            "/tmp",
-            "--backups-dir",
-            "/tmp/backup",
+            *BASE_ARGV,
             "--database-containers",
             "postgres",
             "--images-no-stop-required",
@@ -42,23 +40,6 @@ class HardRestartArgTests(unittest.TestCase):
         args = self._parse(["--hard-restart-projects", "mailu", "foo"])
         self.assertEqual(args.hard_restart_projects, ["mailu", "foo"])
 
-    def test_backups_dir_is_required(self) -> None:
-        import sys
-
-        from baudolo.backup import cli
-
-        argv = [
-            "baudolo",
-            "--compose-dir",
-            "/tmp",
-            "--database-containers",
-            "postgres",
-            "--images-no-stop-required",
-            "redis",
-        ]
-        with patch.object(sys, "argv", argv), self.assertRaises(SystemExit):
-            cli.parse_args()
-
 
 if __name__ == "__main__":
     unittest.main(verbosity=2)

tests/unit/restore/test_cli_version_flag.py

@@ -18,6 +18,8 @@ class TestVersionFlagReachesEveryEngine(unittest.TestCase):
             "app_vol",
             "hash",
             "20260817000000",
+            "--repo-name",
+            "repo",
             "--container",
             "db",
             "--db-password",