refactor(cli): align project-scoped credential errors with API

Rename ErrProjectScopedCredentials (ErrCIScopedCredentials alias), update
messages for single-project scope, and match CLI_PROJECT_SCOPED from API.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

pkg/gateway/mcp/tool_projects_errors.go

@@ -20,15 +20,16 @@ func listProjectsFailureMessage(err error) string {
 }
 
 func shouldSuggestReauthAfterListProjectsFailure(err error) bool {
-	if errors.Is(err, project.ErrCIScopedCredentials) {
+	if errors.Is(err, project.ErrProjectScopedCredentials) {
 		return true
 	}
 	var apiErr *hookdeck.APIError
 	if errors.As(err, &apiErr) {
 		if apiErr.StatusCode == http.StatusForbidden || apiErr.StatusCode == http.StatusUnauthorized {
 			return true
 		}
-		if strings.Contains(strings.ToUpper(apiErr.Message), "CLI_USER_REQUIRED") {
+		msg := strings.ToUpper(apiErr.Message)
+		if strings.Contains(msg, "CLI_PROJECT_SCOPED") || strings.Contains(msg, "CLI_USER_REQUIRED") {
 			return true
 		}
 		return strings.Contains(strings.ToLower(apiErr.Message), "fatal")

pkg/gateway/mcp/tool_projects_errors_test.go

@@ -16,13 +16,13 @@ func TestShouldSuggestReauthAfterListProjectsFailure(t *testing.T) {
 		want bool
 	}{
 		{
-			name: "CI scoped credentials",
-			err:  project.ErrCIScopedCredentials,
+			name: "project-scoped credentials",
+			err:  project.ErrProjectScopedCredentials,
 			want: true,
 		},
 		{
-			name: "APIError 403 CLI_USER_REQUIRED",
-			err:  &hookdeck.APIError{StatusCode: 403, Message: "CLI_USER_REQUIRED: listing projects requires login"},
+			name: "APIError 403 CLI_PROJECT_SCOPED",
+			err:  &hookdeck.APIError{StatusCode: 403, Message: "CLI_PROJECT_SCOPED: cannot list all projects"},
 			want: true,
 		},
 		{

pkg/login/client_login.go

@@ -65,7 +65,7 @@ func Login(config *configpkg.Config, input io.Reader) error {
 		} else {
 			ansi.StopSpinner(s, "", os.Stdout)
 			if !stdinIsTerminal() {
-				return project.ErrCIScopedCredentials
+				return project.ErrProjectScopedCredentials
 			}
 			fmt.Fprintln(os.Stdout, "Your saved key is scoped to a single project (CI). Starting browser sign-in...")
 			config.Profile.APIKey = ""

pkg/login/client_login_test.go

@@ -164,7 +164,7 @@ api_key = "hk_test_cikey_abcdefghij"
 	cfg.TelemetryDisabled = true
 
 	err = Login(cfg, strings.NewReader("\n"))
-	require.ErrorIs(t, err, project.ErrCIScopedCredentials)
+	require.ErrorIs(t, err, project.ErrProjectScopedCredentials)
 	require.False(t, sawCLIAuthPost)
 }
 

pkg/project/credentials.go

@@ -1,60 +1,65 @@
-package project
-
-import (
-	"errors"
-	"fmt"
-
-	"github.com/hookdeck/hookdeck-cli/pkg/config"
-	"github.com/hookdeck/hookdeck-cli/pkg/hookdeck"
-)
-
-// ErrCIScopedCredentials is returned when the stored CLI key is valid but not
-// associated with a user (for example after hookdeck ci).
-var ErrCIScopedCredentials = errors.New(
-	"listing projects requires a user-associated CLI key; keys from hookdeck ci are scoped to a single project; " +
-		"run hookdeck login in an interactive terminal, hookdeck login --cli-key with a product CLI key, or hookdeck_login via MCP for full account access",
-)
-
-// ValidateCredentials calls GET /cli-auth/validate without sending X-Team-ID.
-func ValidateCredentials(config *config.Config) (*hookdeck.ValidateAPIKeyResponse, error) {
-	return config.GetAPIClient().ValidateAPIKey()
-}
-
-// EnsureUserAssociatedCredentials rejects CI-scoped keys before cross-project calls.
-func EnsureUserAssociatedCredentials(config *config.Config) error {
-	response, err := ValidateCredentials(config)
-	if err != nil {
-		return err
-	}
-	if response.UserID == "" {
-		return ErrCIScopedCredentials
-	}
-	return nil
-}
-
-// EnsureUserAssociatedClient rejects CI-scoped keys for an in-memory API client (MCP).
-func EnsureUserAssociatedClient(client *hookdeck.Client) error {
-	if client == nil || client.APIKey == "" {
-		return fmt.Errorf("not authenticated")
-	}
-	response, err := client.ValidateAPIKey()
-	if err != nil {
-		return err
-	}
-	if response.UserID == "" {
-		return ErrCIScopedCredentials
-	}
-	return nil
-}
-
-// CredentialsLackUserAssociation reports whether validate succeeded without a user_id.
-func CredentialsLackUserAssociation(client *hookdeck.Client) (bool, error) {
-	if client == nil || client.APIKey == "" {
-		return false, nil
-	}
-	response, err := client.ValidateAPIKey()
-	if err != nil {
-		return false, err
-	}
-	return response.UserID == "", nil
-}
+package project
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/hookdeck/hookdeck-cli/pkg/config"
+	"github.com/hookdeck/hookdeck-cli/pkg/hookdeck"
+)
+
+// ErrProjectScopedCredentials is returned when the stored CLI key is valid but
+// limited to a single project (for example after hookdeck ci).
+var ErrProjectScopedCredentials = errors.New(
+	"this credential is scoped to a single project and cannot list all projects; " +
+		"keys from hookdeck ci are project-scoped; " +
+		"run hookdeck login in an interactive terminal, hookdeck login --cli-key with a product CLI key, or hookdeck_login via MCP for account-wide access",
+)
+
+// ErrCIScopedCredentials is an alias for ErrProjectScopedCredentials.
+var ErrCIScopedCredentials = ErrProjectScopedCredentials
+
+// ValidateCredentials calls GET /cli-auth/validate without sending X-Team-ID.
+func ValidateCredentials(config *config.Config) (*hookdeck.ValidateAPIKeyResponse, error) {
+	return config.GetAPIClient().ValidateAPIKey()
+}
+
+// EnsureUserAssociatedCredentials rejects project-scoped keys before cross-project calls.
+func EnsureUserAssociatedCredentials(config *config.Config) error {
+	response, err := ValidateCredentials(config)
+	if err != nil {
+		return err
+	}
+	if response.UserID == "" {
+		return ErrProjectScopedCredentials
+	}
+	return nil
+}
+
+// EnsureUserAssociatedClient rejects project-scoped keys for an in-memory API client (MCP).
+func EnsureUserAssociatedClient(client *hookdeck.Client) error {
+	if client == nil || client.APIKey == "" {
+		return fmt.Errorf("not authenticated")
+	}
+	response, err := client.ValidateAPIKey()
+	if err != nil {
+		return err
+	}
+	if response.UserID == "" {
+		return ErrProjectScopedCredentials
+	}
+	return nil
+}
+
+// CredentialsLackUserAssociation reports whether validate succeeded for a project-scoped key
+// (no user_id — our proxy for single-project credential scope today).
+func CredentialsLackUserAssociation(client *hookdeck.Client) (bool, error) {
+	if client == nil || client.APIKey == "" {
+		return false, nil
+	}
+	response, err := client.ValidateAPIKey()
+	if err != nil {
+		return false, err
+	}
+	return response.UserID == "", nil
+}

pkg/project/credentials_test.go

@@ -1,44 +1,44 @@
-package project
-
-import (
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	configpkg "github.com/hookdeck/hookdeck-cli/pkg/config"
-	"github.com/hookdeck/hookdeck-cli/pkg/hookdeck"
-	"github.com/stretchr/testify/require"
-)
-
-func TestEnsureUserAssociatedCredentials_rejectsCIKey(t *testing.T) {
-	configpkg.ResetAPIClientForTesting()
-	t.Cleanup(configpkg.ResetAPIClientForTesting)
-
-	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		require.Equal(t, hookdeck.APIPathPrefix+"/cli-auth/validate", r.URL.Path)
-		w.Header().Set("Content-Type", "application/json")
-		_ = json.NewEncoder(w).Encode(hookdeck.ValidateAPIKeyResponse{
-			ProjectID:        "tm_ci",
-			ProjectMode:      "inbound",
-			OrganizationName: "Org",
-			OrganizationID:   "org_1",
-			ProjectName:      "CI Project",
-		})
-	}))
-	t.Cleanup(ts.Close)
-
-	cfg := &configpkg.Config{
-		APIBaseURL:        ts.URL,
-		LogLevel:          "error",
-		TelemetryDisabled: true,
-	}
-	cfg.Profile = configpkg.Profile{
-		Name:   "default",
-		APIKey: "hk_test_ci_key_abcdefghij",
-		Config: cfg,
-	}
-
-	err := EnsureUserAssociatedCredentials(cfg)
-	require.ErrorIs(t, err, ErrCIScopedCredentials)
-}
+package project
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	configpkg "github.com/hookdeck/hookdeck-cli/pkg/config"
+	"github.com/hookdeck/hookdeck-cli/pkg/hookdeck"
+	"github.com/stretchr/testify/require"
+)
+
+func TestEnsureUserAssociatedCredentials_rejectsProjectScopedKey(t *testing.T) {
+	configpkg.ResetAPIClientForTesting()
+	t.Cleanup(configpkg.ResetAPIClientForTesting)
+
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		require.Equal(t, hookdeck.APIPathPrefix+"/cli-auth/validate", r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(hookdeck.ValidateAPIKeyResponse{
+			ProjectID:        "tm_ci",
+			ProjectMode:      "inbound",
+			OrganizationName: "Org",
+			OrganizationID:   "org_1",
+			ProjectName:      "CI Project",
+		})
+	}))
+	t.Cleanup(ts.Close)
+
+	cfg := &configpkg.Config{
+		APIBaseURL:        ts.URL,
+		LogLevel:          "error",
+		TelemetryDisabled: true,
+	}
+	cfg.Profile = configpkg.Profile{
+		Name:   "default",
+		APIKey: "hk_test_ci_key_abcdefghij",
+		Config: cfg,
+	}
+
+	err := EnsureUserAssociatedCredentials(cfg)
+	require.ErrorIs(t, err, ErrProjectScopedCredentials)
+}

test/acceptance/project_use_test.go

@@ -346,5 +346,5 @@ func TestProjectListFailsWithCIKeyAcceptance(t *testing.T) {
 	combined := stdout + stderr
 	assert.NotContains(t, combined, "Fatal Error")
 	assert.NotContains(t, combined, "status=500")
-	assert.Contains(t, combined, "user-associated CLI key")
+	assert.Contains(t, combined, "single project")
 }