EPMDEDP-17357: feat: Add auth status contract, Argo CD diagnostics, project versions

[geekhubuser]

Description

The krci-overview skill (EPMDEDP-17356) makes the CLI an agent's first tool on the platform, and writing it against the live CLI showed three places where the skill has to work around the CLI instead of using it. Each workaround is fragile and sends the agent to kubectl, which is unavailable for environments on remote clusters and outside the portal's RBAC.

• krci auth status printed Not authenticated to stderr and exited 0, for a missing and for an expired session alike, while docs/auth.md already promised a non-zero exit. The documented shell guard never fired and a script had to match stdout text. Now both cases exit 1 with the sentinel messages, and -o json returns the schemaVersion envelope: data.authenticated, data.user, data.name, data.groups (always an array), data.expiresAt (RFC3339 UTC or null), or error.message on failure.
• env get and project deployments fetched the full Argo CD Application but mapped only health and sync, so an environment showed unknown without the ComparisonError behind it (unreachable target cluster, chart that fails to render, build/<version> revision that does not exist); the same for status.detailed_message of a failed Stage or CDPipeline. Now every project of env get and every row of project deployments carries conditions[] (type, message, lastTransitionTime; always an array) and operation (phase, message, startedAt, finishedAt; null until the first sync); env get, deployment get, its stages and deployment list carry detailedMessage. Table mode prints a Message line and a Conditions or Messages block only when there is something to show. Existing fields and their absence rules are unchanged.
• Which image versions a project has produced lived only in CodebaseImageStream resources. New krci project versions <project> [--branch <name>] lists them one row per branch (count, newest version, created, image) or, with --branch, one row per version newest first. The git branch name is resolved through the owning CodebaseBranch, so the output says release/2.27, not the operator's release-2-27-<hash>. An unknown project is project '<name>' not found (exit 1); a project without streams is an empty result (exit 0). JSON: data.project, data.streams[] with branch, image, versions[].

All three read through the resources/list and resources/get routes the CLI already uses, so no portal change and no vendored spec change; they work against any portal that serves today's verbs. Keeping the workarounds in the skill was rejected because the skill would then encode CLI quirks that every other consumer of -o json hits as well.

Fixes EPMDEDP-17357

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Enhancement (non-breaking change which improves an existing feature or documentation)
• Breaking change (fix or feature that would cause existing functionality not to work as expected)

The only behaviour change for existing callers is the auth status exit code, which the documentation already stated. Every JSON change is an added field.

How Has This Been Tested?

Reproduced first: on the binary built from main, krci auth status without a session exited 0; on this branch it exits 1 and, with -o json, writes the error envelope. Unit tests were written before the code for every change (pkg/cmd/auth/status, internal/portal/diagnostics_test.go, internal/portal/project_versions_test.go, pkg/cmd/env/get, pkg/cmd/deployment/get, pkg/cmd/project/versions); go test ./..., go build and golangci-lint run pass.

Executed against the built binary, offline and then live against a portal with the developer role (read-only commands, every value checked against kubectl on the same namespace):

Row	Result
krci auth status without a session, table and -o json	exit 1, message on stderr, error envelope on stdout
krci auth status with a session, table and -o json	exit 0, data.user, data.groups, data.expiresAt match the token
krci project versions with no argument, BAD_NAME, -o yaml, a 254-character --branch	exit 1 with the tabled message
krci env get on an environment with a failing Application (remote cluster)	conditions[] and operation equal the Application's status.conditions and status.operationState; the Conditions block lists the ComparisonError and the Error operation
krci env get on an environment whose seven Applications point at a build/NaN revision	seven condition lines, operation: null
krci project deployments for that project	one row per environment with the same conditions and operation
krci project versions for a project with 13 builds; --branch for a release/x.y branch	branch names, version count, newest version and its created equal the CodebaseImageStream and CodebaseBranch resources; unknown project exits 1 with project '<name>' not found

Checklist

• I have performed a self-review of my code
• I have commented on my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Pull Request contains one commit. I squash my commits.

Screenshots (if appropriate)

N/A

Additional context

Docs: docs/auth.md, docs/env.md, docs/deployment.md, docs/project.md, docs/json-schemas.md, README command tree. e2e: e2e/auth/test-cases.md is new; e2e/env and e2e/project gain rows, placeholders and fixture examples.

Follow-up in KubeRocketCI/skills once this ships: krci-overview drops its stdout-matching session guard and stops sending agents to kubectl for Argo CD failure reasons and image versions.

Out of scope, each a separate decision: pod logs and events (need a portal REST route), deploy, promote and approve verbs, a generic krci get <kind>, unifying the JSON envelope across the older verbs, and a portal version in krci version.

[SergK]

/ok-to-test