plugin

type Command struct {
	Namespace   string   `validate:"required"`              // full qualified name of the command's namespace
	Name        string   `validate:"required,ne=--version"` // name of the command
	Alias       string   // Deprecated: use Aliases instead.
	Aliases     []string // command aliases
	Description string   `validate:"required"`       // short description of the command
	Usage       string   `validate:"required,usage"` // usage detail to be displayed in command help
	Flags       []Flag   `validate:"dive"`           // command options
	Hidden      bool     // true to hide the command in help text
	Stage       Stage    // stage of the command
}

type Flag struct {
	Name        string `validate:"required,excludesall=<>"` // name of the option (excludes names like <invalidValue>)
	Description string `validate:"required"`                // description of the option
	HasValue    bool   // whether the option requires a value or not
	Hidden      bool   // true to hide the option in command help
}

type Namespace struct {
	ParentName  string   // full qualified name of the parent namespace
	Name        string   `validate:"required"` // base name
	Aliases     []string // aliases
	Description string   // description of the namespace
	Stage       Stage    // stage of the commands in the namespace
}

type Plugin interface {
	// GetMetadata returns the metadata of the plugin.
	GetMetadata() PluginMetadata

	// Run runs the plugin with given plugin context and arguments.
	//
	// Note: the first arg in args is a command or alias no matter the command
	// has namespace or not. To get the namespace, call
	// PluginContext.CommandNamespace.
	Run(c PluginContext, args []string)
}

type PluginConfig interface {
	// Get returns the value for a given key.
	// The value can be float64, bool, string, []interface{},
	// map[string]interface or nil if the key not exist.
	Get(key string) interface{}

	// GetWithDefault returns the value for a given key, or defaultVal if the
	// key not exist.
	GetWithDefault(key string, defaultVal interface{}) interface{}

	// GetString returns string value for a given key.
	GetString(key string) (string, error)

	// GetStringWithDefault returns string value for a given key or defaultVal
	// if the key not exist.
	GetStringWithDefault(key string, defaultVal string) (string, error)

	// GetBool returns boolean value for a given key.
	// If the value is a string, it attempts to convert it to bool.
	GetBool(key string) (bool, error)

	// GetBoolWithDefault returns boolean value for a given key or defaultVal if
	// the key not exist.
	GetBoolWithDefault(key string, defaultVal bool) (bool, error)

	// GetInt returns int value for a given key.
	// If the value is float or string, attempts to convert it to int.
	GetInt(key string) (int, error)

	// GetIntWithDefault returns int value for a given key or defaultVal if the
	// key not exist.
	// If the value is float or string, it attempts to convert it to int.
	GetIntWithDefault(key string, defaultVal int) (int, error)

	// GetFloat returns float64 value for a given key.
	// If the value is int or string, it attempts to convert it to float64.
	GetFloat(key string) (float64, error)

	// GetFloatWithDefault returns float64 value for a given key or defaultVal
	// if the key not exist.
	// If the value is int or string, it attempts to convert it to float64.
	GetFloatWithDefault(key string, defaultVal float64) (float64, error)

	// GetStringSlice return string slice for a given key.
	// If the key not exists, return empty string slice.
	GetStringSlice(key string) ([]string, error)

	// GetIntSlice return string slice for a given key.
	GetIntSlice(key string) ([]int, error)

	// GetFloatSlice return string slice for a given key.
	GetFloatSlice(key string) ([]float64, error)

	// GetStringMap return map[string]interface{} for a given key.
	GetStringMap(key string) (map[string]interface{}, error)

	// GetStringMap return map[string]string for a given key.
	GetStringMapString(key string) (map[string]string, error)

	// Exists checks whether the value for a given key exists or not.
	Exists(key string) bool

	// Set sets the value for a given key.
	Set(string, interface{}) error

	// Erase delete a given key.
	Erase(key string) error
}

type PluginConfigInvalidTypeError struct {
	Key          string
	ExpectedType string
	Value        interface{}
}

type PluginContext interface {
	// APIEndpoint returns the targeted API endpoint of IBM Cloud
	APIEndpoint() string

	// HasAPIEndpoint() returns whether an IBM Cloud has been targeted
	HasAPIEndpoint() bool

	// IsPrivateEndpointEnabled returns whether use of the private endpoint has been chosen
	IsPrivateEndpointEnabled() bool

	// IsAccessFromVPC returns true if the access from VPC private endpoint is enabled.
	IsAccessFromVPC() bool

	// ConsoleEndpoint returns console's public endpoint if api endpoint is public, or returns
	// private endpoint if api endpoint is private.
	ConsoleEndpoint() string

	// ConsoleEndpoints returns both the public and private endpoint of console.
	ConsoleEndpoints() models.Endpoints

	// IAMEndpoint returns IAM's public endpoint if api endpoint is public, or returns private
	// endpoint if api endpoint is private.
	IAMEndpoint() string

	// IAMEndpoints returns both the public and private endpoint of IAM.
	IAMEndpoints() models.Endpoints

	// GetEndpoint is a utility method to return private or public endpoint for a requested service.
	// It supports public cloud only. For non public clouds, plugin needs its own way to determine endpoint.
	GetEndpoint(endpoints.Service) (string, error)

	// CloudName returns the name of the target cloud
	CloudName() string

	// CloudType returns the type of the target cloud (like 'public',
	// 'dedicated' etc)
	CloudType() string

	// Region returns the targeted region
	CurrentRegion() models.Region

	// CRIType returns the type of compute resource the user logged in as, if applicable. Valid values are `IKS`, `VPC`, or `OTHER`
	CRIType() string

	// VPCCRITokenURL() returns the value specified by the environment variable 'IBMCLOUD_CR_VPC_URL', if set.
	// Otherwise, the default VPC auth url specified by the constant `DefaultServerEndpoint` is returned
	VPCCRITokenURL() string

	// HasTargetedRegion() return whether a region is targeted
	HasTargetedRegion() bool

	// IAMToken returns the IAM access token
	IAMToken() string

	// IAMRefreshToken returns the IAM refresh token
	IAMRefreshToken() string

	// RefreshIAMToken refreshes and returns the IAM access token
	RefreshIAMToken() (string, error)

	// UserEmail returns the Email of the logged in user
	UserEmail() string

	// IsLoggedIn returns if a user has logged into IBM Cloud
	IsLoggedIn() bool

	// IsLoggedInWithServiceID returns if a user has logged into IBM Cloud using service ID.
	IsLoggedInWithServiceID() bool

	// IsLoggedInAsProfile returns true if a user logged into IBM Cloud using an IAM token pertaining to a trusted profile
	IsLoggedInAsProfile() bool

	// IsLoggedInAsCRI returns true if a user logged into IBM Cloud as a compute resource.
	IsLoggedInAsCRI() bool

	// IMSAccountID returns ID of the IMS account linked to the targeted BSS
	// account
	IMSAccountID() string

	// Account returns the targeted a BSS account
	CurrentAccount() models.Account

	// HasTargetedAccount returns whether an account has been targeted
	HasTargetedAccount() bool

	// HasTargetedProfile returns whether a profile has been targeted
	HasTargetedProfile() bool

	// CurrentProfile returns the targeted trusted profile
	CurrentProfile() models.Profile

	// HasTargetedComputeResource returns whether a compute resource has been targeted
	HasTargetedComputeResource() bool

	// ResourceGroup returns the targeted resource group
	CurrentResourceGroup() models.ResourceGroup

	// HasTargetedResourceGroup returns whether a resource group has been targeted
	HasTargetedResourceGroup() bool

	// Locale returns user specified locale
	Locale() string

	// Trace returns user specified trace setting.
	// The value is "true", "false" or path of the trace output file.
	Trace() string

	// ColorEnabled returns whether terminal displays color or not
	ColorEnabled() string

	// IsSSLDisabled returns whether skipping SSL validation or not
	IsSSLDisabled() bool

	// PluginDirectory returns the installation directory of the plugin
	PluginDirectory() string

	// HTTPTimeout returns a timeout for HTTP Client
	HTTPTimeout() int

	// VersionCheckEnabled() returns whether checking for update is performmed
	VersionCheckEnabled() bool

	// PluginConfig returns the plugin specific configuarion
	PluginConfig() PluginConfig

	// CommandNamespace returns the name of the parsed namespace
	CommandNamespace() string

	// CLIName returns binary name of the Bluemix CLI that is invoking the plugin
	CLIName() string

	// MCPEnabled returns true if the CLI is functioning as an MCP server
	MCPEnabled() bool
}

type PluginMetadata struct {
	Name          string      `validate:"required"` // name of the plugin
	Aliases       []string    // aliases of the plugin
	Version       VersionType `validate:"required"`                     // version of the plugin
	MinCliVersion VersionType `validate:"required,mincliversion=2.0.0"` // minimal version of CLI required by the plugin
	Namespaces    []Namespace `validate:"required,min=1,dive"`          // list of namespaces provided by the plugin
	Commands      []Command   `validate:"required,min=1,dive"`          // list of commands provided by the plugin

	// SDKVersion is SDK version used by the plugin.
	// It is set by the plugin framework to check SDK compatibility with the CLI.
	SDKVersion VersionType

	// If DelegateBashCompletion is true, plugin command's completion is handled by plugin.
	// The CLI will invoke '<plugin_binary> SendCompletion <args>'
	DelegateBashCompletion bool

	// Whether the plugin supports private endpoint
	PrivateEndpointSupported bool

	// Whether the plugin supports private endpoint access via VPC
	IsAccessFromVPC bool

	// Whether the plugin was built using Cobra
	IsCobraPlugin bool
}

type PluginMetadataError struct {
	Namespace   string `json:"namespace"`
	CommandName string `json:"command,omitempty"`
	Error       string `json:"error"`
}

type PluginMetadataValidate interface {
	Errors(metadatas []PluginMetadata) PluginToValidationErrors
}

type PluginToValidationErrors map[string][]PluginMetadataError

type Stage string

type VersionType struct {
	Major int // major version
	Minor int // minimal version
	Build int // build number
}