feat(cloudrun): friendly auth and not-found error messages (#4986)

Slice 6 of the snapshot cloud-run feature. cloudrun.Classify maps
gRPC Unauthenticated / PermissionDenied / NotFound responses into
actionable messages and preserves the underlying error via %w; other
codes pass through. The Unauthenticated message names all three
credential sources (env var, gcloud command, GCE/GKE metadata server
or Workload Identity) because the production deployment is a cluster
cron job, not a local-dev gcloud session.

Classification lives in internal/cloudrun (the package owns GCP
knowledge) but is applied at the command boundary, not inside
Client.ListServices. Doing it inside the Client would double-wrap
real-call errors when the command also classified them, and it would
bypass the stubbed test path entirely. Calling Classify once at the
command boundary covers both real and stub error sources.

cloudrun.New now wraps construction errors with a generic "GCP client
setup failed" prefix; the cluster case rarely fails here, and the SDK
message is preserved for diagnosis.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ToreMerkely

cmd/kosli/snapshotCloudRun.go

@@ -92,7 +92,7 @@ func (o *snapshotCloudRunOptions) run(args []string) error {
 	}
 	services, err := client.ListServices(ctx, o.project, o.region)
 	if err != nil {
-		return err
+		return cloudrun.Classify(err, o.project, o.region)
 	}
 
 	filtered := services[:0]

cmd/kosli/snapshotCloudRun_test.go

@@ -9,6 +9,8 @@ import (
 	"github.com/kosli-dev/cli/internal/cloudrun"
 	"github.com/stretchr/testify/require"
 	"github.com/stretchr/testify/suite"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
 )
 
 type stubCloudRunLister struct {
@@ -170,6 +172,22 @@ func (suite *SnapshotCloudRunTestSuite) TestSnapshotCloudRunFilter_ExcludeRegex(
 	require.Contains(suite.T(), out, `"service_name": "beta"`)
 }
 
+// TestSnapshotCloudRunCmd_UnauthenticatedReturnsFriendlyError verifies that a
+// gRPC Unauthenticated error from GCP surfaces as the actionable ADC message
+// rather than a raw SDK string.
+func (suite *SnapshotCloudRunTestSuite) TestSnapshotCloudRunCmd_UnauthenticatedReturnsFriendlyError() {
+	newCloudRunClient = func(_ context.Context) (cloudRunLister, error) {
+		return stubCloudRunLister{err: status.Error(codes.Unauthenticated, "token expired")}, nil
+	}
+
+	cmd := fmt.Sprintf(`snapshot cloud-run %s --project p --region r %s`, suite.envName, suite.defaultKosliArguments)
+	_, combined, _, _, err := executeCommandC(cmd)
+
+	require.Error(suite.T(), err)
+	require.Contains(suite.T(), combined, "GCP authentication failed")
+	require.Contains(suite.T(), combined, "metadata server")
+}
+
 func TestSnapshotCloudRunCommandTestSuite(t *testing.T) {
 	suite.Run(t, new(SnapshotCloudRunTestSuite))
 }

docs/handover/2026-04-28-4986-google-cloud-run-1.md

@@ -36,6 +36,7 @@ GCP test environment (provisioned, ADC already configured on this machine):
 - Digest extraction follows the ECS pattern (`internal/aws/aws.go:670-693`): use a `@sha256:` substring if present, else leave the digest empty rather than calling Artifact Registry. Registry-lookup mode (analogous to Azure's `--digests-source acr`) is deferred until customers ask for it.
 - Wire payload mirrors `EcsEnvRequest` plus `project` and `region` fields per artifact (so each row is self-describing). Endpoint name is `report/cloud-run` (kebab-case, parallels `report/azure-apps`). Server-side endpoint does not yet exist; the forced dry-run means no network call is made.
 - Command depends on a local `cloudRunLister` interface and a package-level `newCloudRunClient` variable so tests can substitute a stub without touching ADC. The seam stays in `cmd/kosli/snapshotCloudRun.go` rather than being exposed from `internal/cloudrun` — keeps the public package surface minimal.
+- Error classification (`Classify`) lives in `internal/cloudrun` (GCP knowledge belongs to the package) but is *applied* at the command layer, not inside `Client.ListServices`. Why: applying it inside `ListServices` would double-wrap real-call errors when the command also classified them, and bypass the friendly path entirely for stub-driven tests. Calling it once at the command boundary covers both real and stub error sources.
 
 ---
 
@@ -47,6 +48,6 @@ Slice plan (each slice is a separate, independently-mergeable branch):
 - [x] **Slice 2:** Internal `internal/cloudrun` package — wraps `cloud.google.com/go/run/apiv2` to list services in project+region; unit-tested with a fake. Done 2026-04-28: `Client.ListServices` returns `Service{Name, URI, Revisions}` with one `Revision{Name, Digests, CreatedAt}` per traffic-configured revision (any percent including 0%, with `LATEST` resolved via `LatestReadyRevision` and dupes removed). Digest extraction mirrors the ECS fallback (`@sha256:` parse, else empty string). 9 unit tests passing.
 - [x] **Slice 3:** End-to-end happy path — wire the package into `RunE`, build the snapshot payload, POST to the server `cloud-run` endpoint (still dry-run only). Done 2026-04-28: command now calls `cloudrun.New` + `ListServices`, builds an `EnvRequest` via `ToEnvRequest(services, project, region)`, and submits PUT `report/cloud-run` via `kosliClient.Do` (dry-run forced, so no network call leaves the client). Tested against the real `hello-world-cli-demo` GCP project — emits a digest-pinned artifact for the running `hello-world` service.
 - [x] **Slice 4:** Filtering flags — `--services`, `--services-regex`, `--exclude`, `--exclude-regex`. Done 2026-04-28: backed by `filters.ResourceFilterOptions` (same struct ECS uses); 4 mutex pairs validated in `PreRunE`. Filter is applied in the command after `cloudrun.ListServices` returns — services excluded by name still cost their revision-fetch round-trips. If that becomes a bottleneck, push the filter into `cloudrun.ListServices` so excluded services skip the per-revision API calls.
-- [ ] **Slice 5:** Multi-revision / traffic splitting — handle services with multiple active revisions and services with no active revisions.
-- [ ] **Slice 6:** Auth error UX — clear messages for ADC / `GOOGLE_APPLICATION_CREDENTIALS` failures and for missing project/region.
+- [x] **Slice 5:** ~~Multi-revision / traffic splitting — handle services with multiple active revisions and services with no active revisions.~~ Dropped 2026-04-28: multi-revision (traffic splitting), `LATEST` resolution, and dedup were all completed in Slice 2; the only remaining edge case (services with no active revisions emitting a placeholder artifact) was deferred until the server-side wire contract is defined, since picking the format unilaterally now risks rework. Re-open as a small slice once the server contract lands.
+- [x] **Slice 6:** Auth error UX — clear messages for ADC / `GOOGLE_APPLICATION_CREDENTIALS` failures and for missing project/region. Done 2026-04-28: `cloudrun.Classify(err, project, region)` maps gRPC `Unauthenticated` → ADC advice, `PermissionDenied` → `roles/run.viewer` advice, `NotFound` → "project or region not found"; other codes pass through. Auth message names all three credential sources (env var, `gcloud auth application-default login`, GCE/GKE metadata server / Workload Identity) since the production deployment is a GKE cron job. `cloudrun.New(ctx)` errors get a generic "GCP client setup failed" prefix.
 - [ ] **Slice 7:** Unhide the command, lift the forced dry-run, update CLI reference docs and examples.

go.mod

@@ -47,6 +47,7 @@ require (
 	golang.org/x/oauth2 v0.36.0
 	golang.org/x/term v0.42.0
 	google.golang.org/api v0.274.0
+	google.golang.org/grpc v1.80.0
 	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v3 v3.0.1
 	k8s.io/api v0.35.0
@@ -231,7 +232,6 @@ require (
 	google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20260401024825-9d38bb4040a9 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 // indirect
-	google.golang.org/grpc v1.80.0 // indirect
 	gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect

internal/cloudrun/cloudrun.go

@@ -46,15 +46,18 @@ type Client struct {
 }
 
 // New returns a Client backed by the real Cloud Run Admin API v2 using
-// Application Default Credentials.
+// Application Default Credentials. Construction errors (typically rare in a
+// cluster cron job, since the metadata server provides credentials) are
+// wrapped with a generic "GCP client setup failed" prefix; the SDK's own
+// message is preserved via %w for diagnosis.
 func New(ctx context.Context) (*Client, error) {
 	services, err := run.NewServicesClient(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("creating Cloud Run services client: %w", err)
+		return nil, fmt.Errorf("GCP client setup failed: %w", err)
 	}
 	revisions, err := run.NewRevisionsClient(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("creating Cloud Run revisions client: %w", err)
+		return nil, fmt.Errorf("GCP client setup failed: %w", err)
 	}
 	return &Client{api: &gcpAPI{services: services, revisions: revisions}}, nil
 }

internal/cloudrun/errors.go

@@ -0,0 +1,45 @@
+package cloudrun
+
+import (
+	"fmt"
+
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+// Classify wraps a Cloud Run SDK error with a user-actionable message based on
+// the gRPC status code. Errors without a recognised code (or non-gRPC errors)
+// pass through unchanged so callers can still inspect them.
+//
+// project and region are interpolated into messages where they help the user
+// localise the failure (e.g. NotFound on a misspelled project).
+func Classify(err error, project, region string) error {
+	if err == nil {
+		return nil
+	}
+	s, ok := status.FromError(err)
+	if !ok {
+		return err
+	}
+	switch s.Code() {
+	case codes.Unauthenticated:
+		return fmt.Errorf(
+			"GCP authentication failed: ensure Application Default Credentials are available "+
+				"(GOOGLE_APPLICATION_CREDENTIALS, 'gcloud auth application-default login', "+
+				"or GCE/GKE metadata server / Workload Identity) (underlying error: %w)",
+			err,
+		)
+	case codes.PermissionDenied:
+		return fmt.Errorf(
+			"GCP permission denied: the caller needs 'roles/run.viewer' on project %q (underlying error: %w)",
+			project, err,
+		)
+	case codes.NotFound:
+		return fmt.Errorf(
+			"GCP project %q or region %q not found or not accessible (underlying error: %w)",
+			project, region, err,
+		)
+	default:
+		return err
+	}
+}

internal/cloudrun/errors_test.go

@@ -0,0 +1,61 @@
+package cloudrun
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+func TestClassify_NilStaysNil(t *testing.T) {
+	require.NoError(t, Classify(nil, "p", "r"))
+}
+
+func TestClassify_NonGRPCErrorPassesThrough(t *testing.T) {
+	original := errors.New("some plain go error")
+	got := Classify(original, "p", "r")
+	require.Same(t, original, got)
+}
+
+func TestClassify_UnknownGRPCCodePassesThrough(t *testing.T) {
+	original := status.Error(codes.ResourceExhausted, "rate limited")
+	got := Classify(original, "p", "r")
+	require.Same(t, original, got)
+}
+
+func TestClassify_UnauthenticatedReturnsADCAdvice(t *testing.T) {
+	original := status.Error(codes.Unauthenticated, "token expired")
+	got := Classify(original, "proj-1", "europe-west1")
+
+	require.Error(t, got)
+	require.Contains(t, got.Error(), "GCP authentication failed")
+	require.Contains(t, got.Error(), "GOOGLE_APPLICATION_CREDENTIALS")
+	require.Contains(t, got.Error(), "gcloud auth application-default login")
+	require.Contains(t, got.Error(), "metadata server")
+	require.Contains(t, got.Error(), "Workload Identity")
+	require.ErrorIs(t, got, original, "underlying error must be preserved via %%w")
+}
+
+func TestClassify_PermissionDeniedNamesProjectAndRoleViewer(t *testing.T) {
+	original := status.Error(codes.PermissionDenied, "missing iam role")
+	got := Classify(original, "proj-1", "europe-west1")
+
+	require.Error(t, got)
+	require.Contains(t, got.Error(), "GCP permission denied")
+	require.Contains(t, got.Error(), "roles/run.viewer")
+	require.Contains(t, got.Error(), `"proj-1"`)
+	require.ErrorIs(t, got, original)
+}
+
+func TestClassify_NotFoundNamesProjectAndRegion(t *testing.T) {
+	original := status.Error(codes.NotFound, "no such resource")
+	got := Classify(original, "bad-project", "europe-west1")
+
+	require.Error(t, got)
+	require.Contains(t, got.Error(), "not found or not accessible")
+	require.Contains(t, got.Error(), `"bad-project"`)
+	require.Contains(t, got.Error(), `"europe-west1"`)
+	require.ErrorIs(t, got, original)
+}