Add stale command exit-code option

Author: shouryasrivastava

docs/CATALOG.md

@@ -178,6 +178,14 @@ or on the command line, where stdout is exactly the pipeable source-URI list:
 hflow stale --catalog data/catalog --pipeline pipeline.py | xargs hflow ingest
 ```
 
+Pass `--exit-code` to make the command exit with status 1 when it finds any
+stale episodes, which lets CI gate on stale data without changing the default
+pipe-friendly behavior:
+
+```bash
+hflow stale --catalog data/catalog --pipeline pipeline.py --exit-code
+```
+
 `--pipeline` imports your pipeline file and compares against its current
 `pipeline_version` plus the current episode format version; pass
 `--pipeline-version <hash>` instead to compare against a known hash without

src/hflow/cli.py

@@ -72,6 +72,11 @@ def _build_parser() -> argparse.ArgumentParser:
         default="./data/catalog",
         help="catalog directory or object-store prefix (default: ./data/catalog)",
     )
+    stale_parser.add_argument(
+        "--exit-code",
+        action="store_true",
+        help="exit 1 when any stale episode is found",
+    )
     stale_group = stale_parser.add_mutually_exclusive_group(required=True)
     stale_group.add_argument(
         "--pipeline",
@@ -315,7 +320,7 @@ def _command_stale(arguments: argparse.Namespace) -> int:
         + (f" / schema_version {schema_version}" if schema_version is not None else ""),
         file=sys.stderr,
     )
-    return 0
+    return 1 if arguments.exit_code and stale else 0
 
 
 def _command_up(arguments: argparse.Namespace) -> int:

tests/test_catalog_curation.py

@@ -366,6 +366,36 @@ def test_cli_stale_prints_source_uris_for_ingest(
     assert "1 episode(s)" in captured.err
 
 
+@pytest.mark.parametrize(
+    ("pipeline_version", "expected_exit_code"),
+    [("somethingnewer", 1), (FAKE_STAMPS.pipeline_version, 0)],
+)
+def test_cli_stale_exit_code_gates_on_stale_episodes(
+    tmp_path: Path,
+    pipeline_version: str,
+    expected_exit_code: int,
+) -> None:
+    catalog = Catalog(tmp_path / "catalog")
+    catalog.append_episode(
+        canonical_path=_fake_canonical(tmp_path),
+        stamps=FAKE_STAMPS,
+        episode_metadata={},
+        check_rows=[],
+        source_uri="episodes-in/run_0001.mcap",
+    )
+    exit_code = cli_main(
+        [
+            "stale",
+            "--catalog",
+            str(tmp_path / "catalog"),
+            "--pipeline-version",
+            pipeline_version,
+            "--exit-code",
+        ]
+    )
+    assert exit_code == expected_exit_code
+
+
 def test_cli_stale_reports_a_broken_pipeline_file_instead_of_crashing(
     tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None: