fix(python): UTC-normalize galaxy-last-deploy output, add deploy-event collector, help text, test

clients/python/src/zb_mom_ww_mxgateway_cli/commands.py

@@ -22,6 +22,7 @@ from zb_mom_ww_mxgateway.auth import redact_secret
 from zb_mom_ww_mxgateway.client import GatewayClient
 from zb_mom_ww_mxgateway.errors import MxGatewayError
 from zb_mom_ww_mxgateway.galaxy import GalaxyRepositoryClient
+from zb_mom_ww_mxgateway.generated import galaxy_repository_pb2 as galaxy_pb
 from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
 from zb_mom_ww_mxgateway.options import ClientOptions
 from zb_mom_ww_mxgateway.values import MxValueInput, to_mx_value
@@ -561,8 +562,20 @@ def galaxy_discover(**kwargs: Any) -> None:
     help="ISO-8601 timestamp; when it matches the current cached deploy time the "
     "bootstrap event is suppressed.",
 )
-@click.option("--max-events", default=1, type=int, show_default=True)
-@click.option("--timeout", default=5.0, type=float, show_default=True)
+@click.option(
+    "--max-events",
+    default=1,
+    type=int,
+    show_default=True,
+    help="Stop after collecting this many deploy events.",
+)
+@click.option(
+    "--timeout",
+    default=5.0,
+    type=float,
+    show_default=True,
+    help="Seconds to wait for each event before stopping.",
+)
 @click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
 def galaxy_watch(**kwargs: Any) -> None:
     """Stream a bounded number of Galaxy deploy events."""
@@ -998,7 +1011,10 @@ async def _galaxy_last_deploy(**kwargs: Any) -> dict[str, Any]:
             "present": last_deploy is not None,
         }
         if last_deploy is not None:
-            payload["timeOfLastDeploy"] = last_deploy.isoformat()
+            # galaxy.py returns a timezone-NAIVE UTC datetime (protobuf ToDatetime()).
+            # Stamp it as UTC so the emitted ISO-8601 carries an unambiguous offset,
+            # matching the Go client's "...Z" output.
+            payload["timeOfLastDeploy"] = last_deploy.replace(tzinfo=timezone.utc).isoformat()
         return payload
 
 
@@ -1015,7 +1031,7 @@ async def _galaxy_watch(**kwargs: Any) -> dict[str, Any]:
     last_seen = kwargs.get("last_seen_deploy_time")
     last_seen_dt = _parse_datetime(last_seen) if last_seen else None
     async with await _connect_galaxy(kwargs) as galaxy:
-        events = await _collect_events(
+        events = await _collect_deploy_events(
             galaxy.watch_deploy_events(last_seen_dt),
             max_events=kwargs["max_events"],
             timeout=kwargs["timeout"],
@@ -1178,6 +1194,34 @@ async def _collect_alarm_messages(
     return collected
 
 
+async def _collect_deploy_events(
+    events: Any,
+    *,
+    max_events: int,
+    timeout: float,
+) -> list[galaxy_pb.DeployEvent]:
+    if max_events > MAX_AGGREGATE_EVENTS:
+        raise click.BadParameter(
+            f"must be less than or equal to {MAX_AGGREGATE_EVENTS}",
+            param_hint="--max-events",
+        )
+
+    collected: list[galaxy_pb.DeployEvent] = []
+    iterator = events.__aiter__()
+    try:
+        while len(collected) < max_events:
+            collected.append(await asyncio.wait_for(iterator.__anext__(), timeout=timeout))
+    except StopAsyncIteration:
+        pass
+    except asyncio.TimeoutError:
+        pass
+    finally:
+        close = getattr(iterator, "aclose", None)
+        if close is not None:
+            await close()
+    return collected
+
+
 def _parse_value(raw_value: str, value_type: str) -> MxValueInput:
     normalized = value_type.lower()
     if normalized == "bool":