feat: add safe media upgrade rollback

rf4_research/media_cli.py

@@ -8,7 +8,7 @@ import urllib.error
 import urllib.request
 
 from .community_cli import MIN_FETCH_INTERVAL_SECONDS, USER_AGENT, _StrictRedirectHandler, _read_state, _validate_url_before_io, check_and_reserve, fetch_html, fetch_site_key
-from .media_assets import approve_stored_assets, audit_media_catalog, compare_quality_upgrades, extract_media_candidates, media_coverage, media_quality_report, merge_manifest, publish_quality_upgrades, queue_quality_upgrades, reconcile_queued_duplicates, reclassify_manifest, review_asset, store_asset
+from .media_assets import approve_stored_assets, audit_media_catalog, compare_quality_upgrades, extract_media_candidates, generate_media_derivatives, generate_quality_contact_sheets, media_coverage, media_quality_report, merge_manifest, publish_quality_upgrades, queue_quality_upgrades, reconcile_queued_duplicates, reclassify_manifest, review_asset, rollback_quality_upgrade, store_asset
 
 
 DEFAULT_ROOT = Path("data/media")
@@ -187,6 +187,7 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--queue-quality-upgrades", action="store_true", help="Queue alternatives to published fish below the minimum resolution")
     parser.add_argument("--approve-stored", action="store_true", help="Publish all stored assets after explicit owner approval")
     parser.add_argument("--publish-upgrades", action="store_true", help="Atomically publish all stored quality upgrades and retain fallbacks")
+    parser.add_argument("--rollback-upgrade", action="store_true", help="Restore one superseded fallback after an explicit review decision")
     parser.add_argument("--review-url", help="Review an asset already present in the manifest")
     parser.add_argument("--decision", choices=("approved", "rejected"))
     parser.add_argument("--entity-type", choices=("fish", "waterbody", "tackle", "reference"))
@@ -197,6 +198,8 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--quality-report", action="store_true", help="Report low-resolution published fish and known alternatives without network access")
     parser.add_argument("--compare-quality-upgrades", action="store_true", help="Compare stored quality candidates with their published fallbacks")
     parser.add_argument("--queue-plan", action="store_true", help="Show the next useful queued asset per domain without network access")
+    parser.add_argument("--generate-derivatives", action="store_true", help="Generate deterministic WebP/AVIF variants for approved local assets")
+    parser.add_argument("--contact-sheet-dir", type=Path, help="Write offline quality-upgrade contact sheets to this directory")
     parser.add_argument("--root", type=Path, default=DEFAULT_ROOT)
     parser.add_argument("--state-file", type=Path, default=Path(".cache/community-fetch-state.json"))
     args = parser.parse_args(argv)
@@ -218,6 +221,14 @@ def main(argv: list[str] | None = None) -> int:
         if args.queue_plan:
             print(json.dumps(media_queue_plan(args.root, args.state_file), ensure_ascii=False, indent=2))
             return 0
+        if args.generate_derivatives:
+            report = generate_media_derivatives(args.root)
+            print(json.dumps(report, ensure_ascii=False, indent=2))
+            return 1 if report["issues"] else 0
+        if args.contact_sheet_dir:
+            report = generate_quality_contact_sheets(args.root, args.contact_sheet_dir)
+            print(json.dumps(report, ensure_ascii=False, indent=2))
+            return 1 if report["issues"] else 0
         if args.review_url:
             if not args.decision:
                 parser.error("--decision is required with --review-url")
@@ -244,6 +255,11 @@ def main(argv: list[str] | None = None) -> int:
                 parser.error("--note is required with --publish-upgrades")
             print(json.dumps(publish_quality_upgrades(args.root / "manifest.json", note=args.note), ensure_ascii=False, indent=2))
             return 0
+        if args.rollback_upgrade:
+            if not args.asset_url or not args.note:
+                parser.error("--asset-url and --note are required with --rollback-upgrade")
+            print(json.dumps(rollback_quality_upgrade(args.root / "manifest.json", asset_url=args.asset_url, note=args.note), ensure_ascii=False, indent=2))
+            return 0
         if args.download_one:
             print(_download_one(args.root, args.state_file, args.asset_url))
             return 0