feat: use v2 deployment read endpoints (#23)

* chore: update upstream OpenAPI spec 2026-05-07

* feat: use v2 deployment read endpoints

Upstream RIG-Cluster shipped GET /v2/projects/{p}/deployments and
GET /v2/projects/{p}/deployments/{d} (closes the structural problem
flagged in RijksICTGilde/RIG-Cluster#51). The CLI no longer has to
fuse /logs and /tasks to reconstruct deployment state.

Client:
- add ZadClient.list_deployments_v2 and get_deployment_v2 wrappers
- list_deployments and describe_deployment now prefer the v2 endpoints
  and fall back to the legacy logs+tasks fusion on 404, so older
  Operations Manager deployments keep working
- legacy code paths preserved as _list_deployments_legacy and
  _describe_deployment_legacy

Models:
- add DeploymentStatus and ErrorCategory string enums
- add DeploymentDetail, DeploymentListResponse, DeploymentComponentDetail,
  StatusError pydantic models for the new response shapes

Describe rendering:
- show Status (color-coded), Revision (short SHA), Last sync
- when Status indicates a problem, show an Errors table with
  Category/Resource/Message and a deduplicated explanation footer
- hide the K8s Deployment column in the v2 path (the field doesn't
  exist there); legacy path still populates it

Tests:
- new respx tests for the v2 happy paths and the 404 fallback
- existing legacy-path tests now mock a 404 on the v2 endpoint to
  exercise the same fallback code

* fix: address review on PR #23

- describe_deployment now propagates a real 404 when the v2 list
  endpoint works but get-one 404s (deployment is genuinely missing).
  Previously the legacy fallback would silently return empty data.
  Probe by calling list_deployments_v2 to disambiguate "deployment
  missing" from "endpoint not registered on this upstream".
- _status_color: Suspended joins the red tier alongside Degraded,
  Missing, OutOfSync per upstream's documented severity ordering.
- backwards-compat baseline: register list_deployments_v2 and
  get_deployment_v2 as expected public methods.

* fix: address second review on PR #23

- list_deployments now disambiguates "project not found" from
  "v2 endpoint not registered on this upstream", mirroring the
  describe_deployment logic. Probes via list_projects (available on
  every upstream version) before falling back to the legacy fusion.
- "Last sync" label renamed to "Last sync attempt": per upstream
  spec, the timestamp is the most recent reconciliation attempt
  regardless of outcome, so a Degraded deployment with a recent
  failed sync no longer reads as if it last synced cleanly.
- Move _status_color above describe (helpers before callers).

* fix: only swallow 404 from list_projects probe

The disambiguation probe in list_deployments was catching every
ZadApiError from list_projects, including 401/403/5xx. An expired
API key or transient server error would silently route to the
legacy fusion path and surface a confusing error from /logs
instead of the real cause. Now only 404 means "old upstream";
everything else propagates.

* fix: extend describe_deployment 404 disambiguation

describe_deployment now mirrors list_deployments: when both v2
endpoints 404, it probes list_projects to tell "old upstream" from
"project does not exist on this upstream". The old code silently
fell back to the legacy logs+tasks fusion in both cases, masking
"Project not found" with empty-component results.

Both callers go through a shared _project_exists helper which only
swallows a 404 from list_projects (treating that as "even /projects
is missing, fall back"); 401/403/5xx propagate so the user sees the
real cause.

New test: describe_deployment raises ZadApiError(404) with a clear
"Project '<name>' not found" message when the project is missing.

* fix: address third review on PR #23

Three findings:

1. (Significant) project_status was unconditionally overwriting v2-supplied
   URLs with empty dicts on modern upstreams that have no recent completed
   tasks. The task probe is now best-effort: only overrides v2 URLs when
   it actually finds something.

2. Validate v2 read endpoint responses through pydantic.
   list_deployments_v2 and get_deployment_v2 now run the response through
   DeploymentListResponse / DeploymentDetail and re-emit a dict. Upstream
   schema drift surfaces as a clear pydantic error instead of leaking
   malformed data downstream.

3. Tests:
   - new test for project_status preserving v2 URLs when /tasks is empty
   - new test for the "/projects also 404s" branch (very old upstream)

* fix: v2 URLs are authoritative over task-history URLs

The previous fix inverted the priority — task_urls or dep["urls"] gave
task URLs priority when both were non-empty. v2 is authoritative when
present, so prefer dep["urls"] (the v2-supplied dict) and fall back to
the task probe only when v2 returned nothing (legacy upstreams or
deployments with no public components).

New test: when both v2 and task history carry URLs for the same
deployment, the v2 URLs win.

* fix: address fourth review on PR #23

Four findings:

1. (Significant) ValidationError from pydantic schema mismatch was not
   caught by @handle_api_errors and would surface as a raw traceback.
   New _parse_v2_response helper translates ValidationError to
   ZadApiError(502, "Unexpected API response shape: ...") so the
   existing error rendering path handles upstream schema drift cleanly.
   This becomes load-bearing as upstream adds new DeploymentStatus or
   ErrorCategory enum values without a breaking-change label.

2. (Minor) project_status URL merge now uses presence rather than
   truthiness. v2 returning {} legitimately means "no publish-on-web";
   stale task URLs no longer leak through after the config is removed.
   Legacy rows lack the "urls" key so the test still picks them up.

3. (Minor) New test: describe_deployment propagates non-404 (401/etc)
   from the disambiguation probe, mirroring the list_deployments test.

4. (Minor) New parametrized test for _status_color covering every
   DeploymentStatus enum value plus the empty-string fallback.

* fix: address fifth review on PR #23

- New CLI integration tests for deployment describe rendering, using
  typer's CliRunner with a stubbed ZadClient. Covers Healthy (no
  Errors table) and Degraded (Errors table with category, message,
  and explanation footer) so future Rich-markup or key-name
  regressions get caught at CI.
- Trim multi-paragraph docstrings on _parse_v2_response,
  list_deployments_v2, get_deployment_v2, list_deployments,
  describe_deployment, _project_exists per CLAUDE.md (one-line
  docstrings only). Reasoning lives in the PR description.
- _status_color now uses a dict keyed on DeploymentStatus enum
  members instead of bare string literals; if upstream renames a
  status the type system surfaces the dependency.

* refactor: drop legacy logs+tasks fallback paths

There is one production upstream and it has been upgraded to ship the
v2 read endpoints, so the fallback chain no longer earns its keep.

Removed:
- _list_deployments_legacy and _describe_deployment_legacy (logs+tasks
  fusion to reconstruct deployment state)
- _project_exists disambiguation probe and the layered 404 handling in
  list_deployments / describe_deployment
- project_status's /tasks call to recover URLs (v2 supplies them
  directly on every deployment)
- The optional `subdomain` plumbing and `k8s_deployment` column
  rendering, both vestigial after the legacy path is gone
- All tests covering legacy fallback paths, probe behavior, and stale
  task-history URL handling

resolve_namespace now uses get_deployment_v2 directly instead of
walking list_deployments. describe_deployment, list_deployments, and
project_status pass through v2 fields without `.get()` defaults: after
pydantic validation the required fields are guaranteed present and
the optional ones are explicitly None.

Net change: ~150 lines of client code and ~250 lines of tests removed,
no behavior change against the current upstream.

* fix: coerce unknown enum values instead of failing validation

Closed enums were brittle: an additive upstream change (a new
ErrorCategory or DeploymentStatus value) would make pydantic reject
the entire DeploymentListResponse, taking the whole `zad deployment
list` for a project down until the CLI is updated. Upstream's own
`Unknown` catch-all signals they expect callers to handle unknown
values gracefully, not hard-fail.

- StatusError now coerces unknown category strings to UNKNOWN via a
  before-validator.
- DeploymentDetail does the same for status.
- Tests cover both coercion paths plus the known-value passthrough.
- Drop vestigial `k8s_deployment` keys from the describe rendering
  test fixtures (the column was removed when v2 became the only
  source).

* fix: address final review on PR #23

- Restore `k8s_deployment` as a tombstone field in describe_deployment's
  component dicts. The v2 endpoint doesn't expose this field, but
  removing it from the public describe shape would break consumers
  reading `comp["k8s_deployment"]` from the JSON output. Per the
  backwards-compat policy, return-shape removals require a deprecation
  cycle; an empty-string tombstone is the additive-only path.
- Replace the private `_value2member_map_` access in the enum coercion
  validators with a public set comprehension `{e.value for e in Enum}`.
- Use a realistic 40-char SHA in the describe rendering test so the
  `[:12]` truncation is actually exercised.

* fix: tighten _STATUS_COLORS type and exercise SHA truncation

- _STATUS_COLORS is now annotated dict[DeploymentStatus, str], so type
  checkers flag a new enum value missing from the mapping instead of
  it silently falling through to "dim" at runtime.
- The Degraded fixture's sync_revision was exactly 12 characters, so
  the [:12] truncation was a no-op there. Pad to 40 chars to match
  the Healthy fixture and actually verify truncation.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: anneschuth

api/upstream-openapi.json

@@ -513,6 +513,121 @@
         ]
       }
     },
+    "/api/v2/projects/{project_name}/deployments": {
+      "get": {
+        "tags": [
+          "v2",
+          "v2",
+          "deployments"
+        ],
+        "summary": "List Deployments V2",
+        "description": "List deployments in a project with components, images, and computed URLs.\n\nReturns only deployments targeting the current cluster.\n\nHeaders:\n    X-API-Key: The API key for the project (required)",
+        "operationId": "list_deployments_v2_api_v2_projects__project_name__deployments_get",
+        "parameters": [
+          {
+            "name": "project_name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "title": "Project Name"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeploymentListResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found"
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "APIKeyHeader": []
+          }
+        ]
+      }
+    },
+    "/api/v2/projects/{project_name}/deployments/{deployment_name}": {
+      "get": {
+        "tags": [
+          "v2",
+          "v2",
+          "deployments"
+        ],
+        "summary": "Get Deployment V2",
+        "description": "Get a single deployment with components, images, and computed URLs.\n\nReturns the current state of a deployment as defined in the project file,\nwith computed public URLs for components that have publish-on-web.\n\nHeaders:\n    X-API-Key: The API key for the project (required)",
+        "operationId": "get_deployment_v2_api_v2_projects__project_name__deployments__deployment_name__get",
+        "parameters": [
+          {
+            "name": "project_name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "title": "Project Name"
+            }
+          },
+          {
+            "name": "deployment_name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "title": "Deployment Name"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeploymentDetail"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found"
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "APIKeyHeader": []
+          }
+        ]
+      }
+    },
     "/api/v2/projects/{project_name}/deployments/{deployment_name}/:clone-bucket": {
       "post": {
         "tags": [
@@ -6261,6 +6376,151 @@
         "title": "DeploymentBackupResponse",
         "description": "Response for combined deployment backup operations (PVCs, databases, buckets)."
       },
+      "DeploymentComponentDetail": {
+        "properties": {
+          "reference": {
+            "type": "string",
+            "title": "Reference",
+            "description": "Component name reference"
+          },
+          "image": {
+            "type": "string",
+            "title": "Image",
+            "description": "Container image URL"
+          }
+        },
+        "type": "object",
+        "required": [
+          "reference",
+          "image"
+        ],
+        "title": "DeploymentComponentDetail",
+        "description": "Component within a deployment, including image reference."
+      },
+      "DeploymentDetail": {
+        "properties": {
+          "name": {
+            "type": "string",
+            "title": "Name",
+            "description": "Deployment name"
+          },
+          "project": {
+            "type": "string",
+            "title": "Project",
+            "description": "Project name"
+          },
+          "cluster": {
+            "type": "string",
+            "title": "Cluster",
+            "description": "Target cluster"
+          },
+          "namespace": {
+            "type": "string",
+            "title": "Namespace",
+            "description": "Kubernetes namespace"
+          },
+          "subdomain": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Subdomain",
+            "description": "DNS subdomain override"
+          },
+          "components": {
+            "items": {
+              "$ref": "#/components/schemas/DeploymentComponentDetail"
+            },
+            "type": "array",
+            "title": "Components",
+            "description": "Component references"
+          },
+          "urls": {
+            "additionalProperties": {
+              "type": "string"
+            },
+            "type": "object",
+            "title": "Urls",
+            "description": "Computed public URLs, keyed by component name"
+          },
+          "status": {
+            "$ref": "#/components/schemas/DeploymentStatus",
+            "description": "Overall deployment state. Always present; check value to render."
+          },
+          "sync_revision": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Sync Revision",
+            "description": "Git revision (full SHA) the cluster last reconciled; null if never reconciled"
+          },
+          "last_synced_at": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Last Synced At",
+            "description": "ISO timestamp of the last reconciliation attempt against git, regardless of outcome. Combine with status to know whether that attempt succeeded; for a Degraded deployment this can be the time of a failed sync, not a healthy one. Null if no reconciliation has ever happened."
+          },
+          "errors": {
+            "items": {
+              "$ref": "#/components/schemas/StatusError"
+            },
+            "type": "array",
+            "title": "Errors",
+            "description": "Cluster-side error entries; populated only when status indicates a problem (Degraded, OutOfSync, Suspended, Missing). Empty otherwise."
+          }
+        },
+        "type": "object",
+        "required": [
+          "name",
+          "project",
+          "cluster",
+          "namespace",
+          "status"
+        ],
+        "title": "DeploymentDetail",
+        "description": "Full deployment state as returned by the GET endpoints."
+      },
+      "DeploymentListResponse": {
+        "properties": {
+          "project": {
+            "type": "string",
+            "title": "Project"
+          },
+          "cluster": {
+            "type": "string",
+            "title": "Cluster"
+          },
+          "deployments": {
+            "items": {
+              "$ref": "#/components/schemas/DeploymentDetail"
+            },
+            "type": "array",
+            "title": "Deployments"
+          }
+        },
+        "type": "object",
+        "required": [
+          "project",
+          "cluster"
+        ],
+        "title": "DeploymentListResponse",
+        "description": "Response for GET /projects/{project_name}/deployments."
+      },
       "DeploymentRestoreRequest": {
         "properties": {
           "resource_type": {
@@ -6412,6 +6672,36 @@
           "status": "success"
         }
       },
+      "DeploymentStatus": {
+        "type": "string",
+        "enum": [
+          "Healthy",
+          "Degraded",
+          "Progressing",
+          "OutOfSync",
+          "Suspended",
+          "Missing",
+          "Pending",
+          "Unavailable",
+          "Unknown"
+        ],
+        "title": "DeploymentStatus",
+        "description": "Overall deployment state.\n\nA single enum covering everything a caller wants to switch on. Argo's\ntwo orthogonal dimensions (sync, health) are collapsed using a\nworst-of-both priority: Degraded/Suspended/Missing > OutOfSync >\nProgressing > Healthy. Pending and Unavailable are *our* states for\n\"we have no data,\" distinct from Argo's own Unknown."
+      },
+      "ErrorCategory": {
+        "type": "string",
+        "enum": [
+          "ImagePull",
+          "CrashLoop",
+          "OutOfMemory",
+          "HealthCheck",
+          "SyncFailed",
+          "ComparisonError",
+          "Unknown"
+        ],
+        "title": "ErrorCategory",
+        "description": "Programmatic categorization of a cluster error. Use ``message`` for the raw text.\n\nCategories are intentionally broader than literal Kubernetes reasons (e.g.\n``ImagePull`` covers ``ImagePullBackOff``, ``ErrImagePull``, manifest-unknown\npulls, etc.) so app-level categories can be added later without breaking\nconsumers tied to specific K8s state names."
+      },
       "HTTPValidationError": {
         "properties": {
           "detail": {
@@ -7029,6 +7319,56 @@
         "title": "SnapshotInfoModel",
         "description": "Information about a Kopia snapshot."
       },
+      "StatusError": {
+        "properties": {
+          "resource": {
+            "type": "string",
+            "title": "Resource",
+            "description": "Kind/name (e.g. 'Pod/frontend-abc') or 'Event/<obj>' for events"
+          },
+          "message": {
+            "type": "string",
+            "title": "Message",
+            "description": "Raw cluster message \u2014 for automation, regex matching, correlation"
+          },
+          "category": {
+            "$ref": "#/components/schemas/ErrorCategory",
+            "description": "Programmatic category for filtering, grouping, colorizing"
+          },
+          "explanation": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Explanation",
+            "description": "Human-friendly explanation of the category and what to do next; null when the category has no canned guidance (e.g. Unknown)"
+          },
+          "timestamp": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Timestamp",
+            "description": "ISO timestamp if known"
+          }
+        },
+        "type": "object",
+        "required": [
+          "resource",
+          "message",
+          "category"
+        ],
+        "title": "StatusError",
+        "description": "A single error or warning entry surfaced from the cluster."
+      },
       "StorageAction": {
         "properties": {
           "action": {