auth: handle account-only profiles cleanly for workspace and describe commands (#5340)

## Why

Two related bugs in a bug bash, both rooted in profiles created with
\`databricks auth login --skip-workspace\` (no \`workspace_id\`, or the
legacy \`workspace_id = none\` sentinel):

1. **Workspace commands** (e.g. \`databricks clusters list --profile
<account-only>\`) failed with the opaque backend error \"Credential was
not sent or was of an unsupported type for this API\" — the SDK
forwarded the literal sentinel as a routing identifier, or sent an
unrouted request to the account-plane.
2. **\`databricks auth describe --profile <account-only>\`** printed the
false-negative \`Unable to authenticate: Unable to load OAuth Config\`
on a perfectly valid profile — describe calls \`w.CurrentUser.Me()\`
after MustAnyClient, which hits the workspace plane without a
workspace_id and the backend rejects the call.

Reproduced both against \`db-deco-test.databricks.com\` with a real
\`--skip-workspace\` profile.

## Changes

- \`workspaceClientOrPrompt\` detects an account-only profile
(\`account_id\` set + \`workspace_id\` empty or the legacy \"none\"
sentinel + an explicit \`Profile\`) before any API call and returns a
typed \`ErrAccountOnlyProfile\` with an actionable message naming the
profile.
- \`MustAnyClient\` (used by \`auth describe\` and similar) recognizes
\`ErrAccountOnlyProfile\` and falls through to the account client, so
account-only profiles describe cleanly via the account plane.
- Workspace commands (\`MustWorkspaceClient\` directly) keep getting the
actionable error — they need a workspace.

After the fix on the same \`db-deco-test\` profile:
\`\`\`
$ databricks auth describe --profile bug2-test
Host: https://db-deco-test.databricks.com
Account ID: 968367da-...
Authenticated with: databricks-cli
✓ host: https://db-deco-test.databricks.com (from .databrickscfg)
✓ account_id: 968367da-... (from .databrickscfg)
✓ workspace_id: none (from .databrickscfg)
✓ profile: bug2-test (from --profile flag)
✓ auth_type: databricks-cli
...

$ databricks clusters list --profile bug2-test
Error: profile \"bug2-test\" has no workspace_id set (account-only);
this command requires a workspace.
Edit the profile to set workspace_id to a real ID, or pass --profile
with a workspace-scoped profile
\`\`\`

The env-var-only path (no \`Profile\` set) is intentionally left alone —
unified hosts can serve workspace APIs from the account host with just
\`DATABRICKS_HOST\` + \`DATABRICKS_ACCOUNT_ID\` + a token, and we don't
want to reject those.

## Test plan

- [x] Reproduced both bugs against \`db-deco-test.databricks.com\` with
a real \`--skip-workspace\`-created profile.
- [x] After the fix: \`auth describe --profile bug2-test\` succeeds and
shows account info; \`clusters list --profile bug2-test\` gives the
actionable error.
- [x] Existing valid SPOG workspace profile (with \`workspace_id\`)
still works against the same host — no regression.
- [x] New unit tests:
\`TestWorkspaceClientOrPromptRejectsAccountOnlyProfile\` (both shapes),
\`TestMustAnyClientFallsThroughOnAccountOnlyProfile\`.
- [x] \`go test ./cmd/root/...\`, \`./task checks\`, \`./task lint-q\`.

Author: simonfaltum

cmd/root/auth.go

@@ -52,6 +52,25 @@ func initProfileFlag(cmd *cobra.Command) {
 	cmd.RegisterFlagCompletionFunc("profile", profile.ProfileCompletion)
 }
 
+// ErrAccountOnlyProfile signals that the resolved profile has an account_id
+// but no workspace_id, so workspace APIs can't be reached. Workspace-only
+// commands surface this as an actionable error; MustAnyClient (used by `auth
+// describe` and similar) recognizes the type and falls through to the account
+// client so account-only profiles still describe cleanly.
+type ErrAccountOnlyProfile struct {
+	profileName string
+}
+
+func (e ErrAccountOnlyProfile) Error() string {
+	return fmt.Sprintf("profile %q has no workspace_id set (account-only); this command requires a workspace. Edit the profile to set workspace_id to a real ID, or pass --profile with a workspace-scoped profile", e.profileName)
+}
+
+// accountOnlyProfileError describes why a workspace command can't run against
+// a profile that has an account_id but no workspace_id.
+func accountOnlyProfileError(profileName string) error {
+	return ErrAccountOnlyProfile{profileName: profileName}
+}
+
 func profileFlagValue(cmd *cobra.Command) (string, bool) {
 	profileFlag := cmd.Flag("profile")
 	if profileFlag == nil {
@@ -127,9 +146,11 @@ func MustAnyClient(cmd *cobra.Command, args []string) (bool, error) {
 	}
 
 	// If the error indicates a wrong config type (workspace host used for account client,
-	// or config type mismatch detected by workspaceClientOrPrompt), fall through to try
-	// account client.
-	if _, ok := errors.AsType[ErrNoWorkspaceProfiles](werr); !errors.Is(werr, errNotWorkspaceClient) && !ok {
+	// or config type mismatch detected by workspaceClientOrPrompt), or an account-only
+	// profile (no workspace_id), fall through to try the account client.
+	_, noWorkspaceProfiles := errors.AsType[ErrNoWorkspaceProfiles](werr)
+	_, accountOnly := errors.AsType[ErrAccountOnlyProfile](werr)
+	if !errors.Is(werr, errNotWorkspaceClient) && !noWorkspaceProfiles && !accountOnly {
 		return false, werr
 	}
 
@@ -190,6 +211,19 @@ func MustAccountClient(cmd *cobra.Command, args []string) error {
 // Helper function to create a workspace client or prompt once if the given configuration is not valid.
 func workspaceClientOrPrompt(ctx context.Context, cfg *config.Config, allowPrompt bool) (*databricks.WorkspaceClient, error) {
 	w, err := databricks.NewWorkspaceClient((*databricks.Config)(cfg))
+	if err == nil && cfg.Profile != "" && cfg.AccountID != "" &&
+		(cfg.WorkspaceID == "" || cfg.WorkspaceID == auth.WorkspaceIDNone) {
+		// Account-only profile (created with --skip-workspace): account_id is
+		// set but workspace_id is absent (new shape) or the legacy "none"
+		// sentinel. Without a workspace_id the SDK would either send "none" as
+		// a routing identifier or fail later with an opaque auth error.
+		// Reject up front with a message the user can act on.
+		//
+		// We require cfg.Profile to be set so we don't reject env-var-only
+		// configs targeting a unified host where workspace APIs are also
+		// served from the account host.
+		return nil, accountOnlyProfileError(cfg.Profile)
+	}
 	if err == nil {
 		err = w.Config.Authenticate(emptyHttpRequest(ctx))
 	}

cmd/root/auth_test.go

@@ -454,6 +454,71 @@ func TestAccountClientOrPromptReturnsErrorForWrongHostType(t *testing.T) {
 	assert.ErrorIs(t, err, databricks.ErrNotAccountClient)
 }
 
+func TestWorkspaceClientOrPromptRejectsAccountOnlyProfile(t *testing.T) {
+	tests := []struct {
+		name        string
+		workspaceID string
+	}{
+		// New shape: --skip-workspace omits workspace_id entirely.
+		{name: "empty workspace_id", workspaceID: ""},
+		// Legacy shape: older CLIs persisted the "none" sentinel.
+		{name: "legacy none sentinel", workspaceID: "none"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			testutil.CleanupEnvironment(t)
+			t.Setenv("PATH", "")
+
+			cfg := &config.Config{
+				Host:          "https://example.test/",
+				AccountID:     "abc-123",
+				WorkspaceID:   tt.workspaceID,
+				Token:         "foobar",
+				Profile:       "bb",
+				HTTPTransport: noNetworkTransport,
+			}
+
+			w, err := workspaceClientOrPrompt(t.Context(), cfg, false)
+			assert.Nil(t, w)
+			require.Error(t, err)
+			var accountOnly ErrAccountOnlyProfile
+			require.ErrorAs(t, err, &accountOnly)
+			assert.Contains(t, err.Error(), `profile "bb"`)
+			assert.Contains(t, err.Error(), "account-only")
+			assert.Contains(t, err.Error(), "no workspace_id set")
+		})
+	}
+}
+
+func TestMustAnyClientFallsThroughOnAccountOnlyProfile(t *testing.T) {
+	testutil.CleanupEnvironment(t)
+	t.Setenv("PATH", "")
+
+	configFile := filepath.Join(t.TempDir(), ".databrickscfg")
+	err := os.WriteFile(configFile, []byte(`
+[skipws]
+host         = https://accounts.azuredatabricks.net/
+account_id   = abc-123
+token        = foobar
+workspace_id = none
+`), 0o600)
+	require.NoError(t, err)
+	t.Setenv("DATABRICKS_CONFIG_FILE", configFile)
+
+	ctx, tt := cmdio.SetupTest(t.Context(), cmdio.TestOptions{PromptSupported: true})
+	t.Cleanup(tt.Done)
+	cmd := New(ctx)
+	require.NoError(t, cmd.PersistentFlags().Set("profile", "skipws"))
+
+	// Workspace path returns ErrAccountOnlyProfile. MustAnyClient must
+	// recognize the type and fall through to the account client so
+	// `auth describe` shows account info for account-only profiles.
+	isAccount, err := MustAnyClient(cmd, []string{})
+	require.NoError(t, err)
+	require.True(t, isAccount, "expected fall-through to account client")
+	require.NotNil(t, cmdctx.AccountClient(cmd.Context()))
+}
+
 func TestWorkspaceClientOrPromptReturnsSuccessWhenAuthSucceeds(t *testing.T) {
 	testutil.CleanupEnvironment(t)
 	t.Setenv("PATH", "")