mctl_list_previews reports count 0 when the ArgoCD query fails #698

Summary

When its ArgoCD query fails, mctl_list_previews reports {"count": 0, "items": []}. A failed read is presented as "no previews". In addition, the handler lists ArgoCD Applications, but previews are not ArgoCD Applications. So even a successful query cannot find them.

Observed (2026-10-18)

mctl_list_previews(team=labs, service=psa-smoke) returned:

{"count":0,"items":[],"note":"ArgoCD query failed: parsing argocd list response: missing items array"}

At that moment a preview Helm release for labs/psa-smoke existed in labs-preview.

Defect 1: a failed read becomes an empty list

internal/api/handlers_read.go:683 (ListPreviews), origin/main:

• :705: apps, err := h.opts.ArgoCD.ListApps(team)
• :707-713: ErrUnauthenticated returns HTTP 200 with items: [], count: 0 and an error string.
• :715-721: ErrForbidden returns HTTP 200 with items: [], count: 0 and a note.
• :722-728: any other error, including internal/argocd/client.go:364 "missing items array", returns HTTP 200 with items: [], count: 0 and a note.

This breaks the workspace rule that "could not observe" is never "observed absent". A failed, partial or malformed read must surface as an error or an explicit unknown state, never as an empty set or a zero. Anything that checks count == 0, including an agent deciding whether a stale preview needs cleanup, is told there is nothing there. The MCP wrapper (internal/mcp/server.go:2107) passes the body through as a successful result.

Defect 2: the handler queries the wrong source of truth

• The handler (handlers_read.go:703-705, :730-733) and the tool description (internal/mcp/server.go:2112-2115) assume preview ArgoCD Applications named preview-{team}-{service}-{id}.
• mctl-gitops wft-preview-deploy does not create an ArgoCD Application. It runs helm upgrade --install directly into {team}-preview (mctl-gitops platform-gitops/argo-workflows/cluster-templates/wft-preview-deploy.yaml:357 for NS="${TEAM}-preview" and :450 for helm upgrade --install).
• The release name is preview-${COMPONENT}-${PREVIEW_ID} (wft-preview-deploy.yaml:388), with no team segment. The handler's prefix preview-{team}-{service}- could not match it even if such Applications existed.

So, as written, ListPreviews cannot return a preview created by mctl_create_preview, whether or not ArgoCD answers.

Proposed

1. On any failed read (unauthenticated, forbidden, transport, malformed envelope), return an error: a non-2xx status and an MCP tool error. Do not return count: 0. If a soft result is ever needed, use an explicit "state": "unknown" with no count field.
2. List from the actual source of truth: the Helm release Secrets (owner=helm, name=preview-<service>-*) or the resources labelled mctl.ai/preview=true / mctl.ai/preview-id in {team}-preview, filtered by service. Then update the tool description to match.
3. Add tests for both: a failing backend yields an error and not count: 0, and a release named the way wft-preview-deploy names it is listed.

Related: mctl-gitops wft-preview-deploy / wft-preview-delete, and the TTL issue filed alongside this one.

🤖 Generated with Claude Code