cli/_output(refactor[typing]): Add JSON payload TypedDicts

why: Make plan/output JSON structures explicit for safer indexing and clearer contracts.

what:
- Introduce JsonValue aliases plus typed payloads for plan entry/summary/result
- Type OutputFormatter payload handling and cast summary/status payloads
- Adjust plan output tests for TypedDict iteration

Author: tony

src/vcspull/cli/_output.py

@@ -8,6 +8,64 @@
 from dataclasses import dataclass, field
 from enum import Enum
 
+from typing_extensions import NotRequired
+
+JsonPrimitive: t.TypeAlias = str | int | float | bool | None
+JsonValue: t.TypeAlias = JsonPrimitive | dict[str, "JsonValue"] | list["JsonValue"]
+JsonObject: t.TypeAlias = t.Mapping[str, JsonValue]
+OutputPayload: t.TypeAlias = JsonObject | "PlanEntryPayload" | "PlanSummaryPayload"
+
+
+class PlanEntryPayload(t.TypedDict):
+    """Typed JSON payload for a plan entry."""
+
+    format_version: str
+    type: str
+    name: str
+    path: str
+    workspace_root: str
+    action: str
+    detail: NotRequired[str]
+    url: NotRequired[str]
+    branch: NotRequired[str]
+    remote_branch: NotRequired[str]
+    current_rev: NotRequired[str]
+    target_rev: NotRequired[str]
+    ahead: NotRequired[int]
+    behind: NotRequired[int]
+    dirty: NotRequired[bool]
+    error: NotRequired[str]
+    diagnostics: NotRequired[list[str]]
+
+
+class PlanSummaryPayload(t.TypedDict):
+    """Typed JSON payload for a plan summary."""
+
+    format_version: str
+    type: str
+    clone: int
+    update: int
+    unchanged: int
+    blocked: int
+    errors: int
+    total: int
+    duration_ms: NotRequired[int]
+
+
+class PlanWorkspacePayload(t.TypedDict):
+    """Typed JSON payload for a workspace grouping."""
+
+    path: str
+    operations: list[PlanEntryPayload]
+
+
+class PlanResultPayload(t.TypedDict):
+    """Typed JSON payload for a plan result."""
+
+    format_version: str
+    workspaces: list[PlanWorkspacePayload]
+    summary: PlanSummaryPayload
+
 
 class OutputMode(Enum):
     """Output format modes."""
@@ -47,9 +105,9 @@ class PlanEntry:
     error: str | None = None
     diagnostics: list[str] = field(default_factory=list)
 
-    def to_payload(self) -> dict[str, t.Any]:
+    def to_payload(self) -> PlanEntryPayload:
         """Convert the plan entry into a serialisable payload."""
-        payload: dict[str, t.Any] = {
+        payload: PlanEntryPayload = {
             "format_version": "1",
             "type": "operation",
             "name": self.name,
@@ -97,9 +155,9 @@ def total(self) -> int:
         """Return the total number of repositories accounted for."""
         return self.clone + self.update + self.unchanged + self.blocked + self.errors
 
-    def to_payload(self) -> dict[str, t.Any]:
+    def to_payload(self) -> PlanSummaryPayload:
         """Convert the summary to a serialisable payload."""
-        payload: dict[str, t.Any] = {
+        payload: PlanSummaryPayload = {
             "format_version": "1",
             "type": "summary",
             "clone": self.clone,
@@ -139,9 +197,9 @@ def to_workspace_mapping(self) -> dict[str, list[PlanEntry]]:
             grouped.setdefault(entry.workspace_root, []).append(entry)
         return grouped
 
-    def to_json_object(self) -> dict[str, t.Any]:
+    def to_json_object(self) -> PlanResultPayload:
         """Return the JSON structure for ``--json`` output."""
-        workspaces: list[dict[str, t.Any]] = []
+        workspaces: list[PlanWorkspacePayload] = []
         for workspace_root, entries in self.to_workspace_mapping().items():
             workspaces.append(
                 {
@@ -168,17 +226,18 @@ def __init__(self, mode: OutputMode = OutputMode.HUMAN) -> None:
             The output mode to use (human, json, ndjson)
         """
         self.mode = mode
-        self._json_buffer: list[dict[str, t.Any]] = []
+        self._json_buffer: list[OutputPayload] = []
 
-    def emit(self, data: dict[str, t.Any] | PlanEntry | PlanSummary) -> None:
+    def emit(self, data: OutputPayload | PlanEntry | PlanSummary) -> None:
         """Emit a data event.
 
         Parameters
         ----------
-        data : dict | PlanEntry | PlanSummary
+        data : OutputPayload | PlanEntry | PlanSummary
             Event data to emit. PlanEntry and PlanSummary instances are serialised
             automatically.
         """
+        payload: OutputPayload
         if isinstance(data, (PlanEntry, PlanSummary)):
             payload = data.to_payload()
         else:

src/vcspull/cli/status.py

@@ -19,7 +19,7 @@
 from vcspull.types import ConfigDict
 
 from ._colors import Colors, get_color_mode
-from ._output import OutputFormatter, get_output_mode
+from ._output import JsonObject, OutputFormatter, get_output_mode
 from ._workspaces import filter_by_workspace
 
 log = logging.getLogger(__name__)
@@ -451,25 +451,28 @@ def status_repos(
             summary["missing"] += 1
 
         # Emit status
-        formatter.emit(
+        status_payload = t.cast(
+            "JsonObject",
             {
                 "reason": "status",
                 **status,
             },
         )
+        formatter.emit(status_payload)
 
         # Human output
         _format_status_line(status, formatter, colors, detailed)
 
     # Emit summary
-    summary_data: dict[str, t.Any] = {
-        "reason": "summary",
-        **summary,
-    }
-    if duration_ms is not None:
-        summary_data["duration_ms"] = duration_ms
-
-    formatter.emit(summary_data)
+    summary_payload = t.cast(
+        "JsonObject",
+        {
+            "reason": "summary",
+            **summary,
+            **({"duration_ms": duration_ms} if duration_ms is not None else {}),
+        },
+    )
+    formatter.emit(summary_payload)
 
     # Human summary
     formatter.emit_text(

src/vcspull/cli/sync.py

@@ -32,6 +32,7 @@
 
 from ._colors import Colors, get_color_mode
 from ._output import (
+    JsonObject,
     OutputFormatter,
     OutputMode,
     PlanAction,
@@ -763,12 +764,14 @@ def silent_progress(output: str, timestamp: datetime) -> None:
                 f"{colors.error(str(e))}",
             )
             if exit_on_error:
-                formatter.emit(
+                summary_payload = t.cast(
+                    "JsonObject",
                     {
                         "reason": "summary",
                         **summary,
                     },
                 )
+                formatter.emit(summary_payload)
                 formatter.finalize()
                 if parser is not None:
                     parser.exit(status=1, message=EXIT_ON_ERROR_MSG)
@@ -783,12 +786,14 @@ def silent_progress(output: str, timestamp: datetime) -> None:
             f"{colors.muted('→')} {display_repo_path}",
         )
 
-    formatter.emit(
+    summary_payload = t.cast(
+        "JsonObject",
         {
             "reason": "summary",
             **summary,
         },
     )
+    formatter.emit(summary_payload)
 
     if formatter.mode == OutputMode.HUMAN:
         formatter.emit_text(

tests/cli/test_plan_output_helpers.py

@@ -93,12 +93,13 @@ def test_plan_entry_to_payload(
     """Ensure PlanEntry serialises optional fields correctly."""
     entry = PlanEntry(**kwargs)
     payload = entry.to_payload()
+    payload_map = t.cast(dict[str, t.Any], payload)
 
     for key, value in expected_keys.items():
-        assert payload[key] == value
+        assert payload_map[key] == value
 
     for key in unexpected_keys:
-        assert key not in payload
+        assert key not in payload_map
 
     assert payload["format_version"] == "1"
     assert payload["type"] == "operation"