extensions

type Argument struct {
	// Name is the argument name
	Name string `json:"name"`
	// Description explains the purpose of the argument
	Description string `json:"description"`
	// Required indicates if the argument is required
	Required bool `json:"required"`
	// Variadic indicates if the argument accepts multiple values
	Variadic bool `json:"variadic,omitempty"`
	// ValidValues contains the allowed values for the argument
	ValidValues []string `json:"validValues,omitempty"`
}

type CapabilityType string

type Command struct {
	// Name is the command path as an array of strings (e.g., ["demo", "context"])
	Name []string `json:"name"`
	// Short is a brief one-line description of the command
	Short string `json:"short"`
	// Long is an optional detailed multi-line description (markdown supported)
	Long string `json:"long,omitempty"`
	// Usage is an optional usage template string
	Usage string `json:"usage,omitempty"`
	// Examples contains example usages of the command
	Examples []CommandExample `json:"examples,omitempty"`
	// Args defines the positional arguments accepted by the command, in the order it is received
	Args []Argument `json:"args,omitempty"`
	// Flags defines the flags/options accepted by the command
	Flags []Flag `json:"flags,omitempty"`
	// Subcommands contains nested subcommands
	Subcommands []Command `json:"subcommands,omitempty"`
	// Hidden indicates if the command should be hidden from help output
	Hidden bool `json:"hidden,omitempty"`
	// Aliases contains alternative names for the command
	Aliases []string `json:"aliases,omitempty"`
	// Deprecated contains a deprecation notice if the command is deprecated
	Deprecated string `json:"deprecated,omitempty"`
}

type CommandExample struct {
	// Description explains what the example demonstrates
	Description string `json:"description"`
	// Command is the example command string
	Command string `json:"command"`
}

type ConfigurationMetadata struct {
	// Global contains JSON Schema for global-level configuration options
	Global *jsonschema.Schema `json:"global,omitempty"`
	// Project contains JSON Schema for project-level configuration options
	Project *jsonschema.Schema `json:"project,omitempty"`
	// Service contains JSON Schema for service-level configuration options
	Service *jsonschema.Schema `json:"service,omitempty"`
	// EnvironmentVariables describes environment variables used by the extension
	EnvironmentVariables []EnvironmentVariable `json:"environmentVariables,omitempty"`
}

type EnvironmentVariable struct {
	// Name is the environment variable name (e.g., "EXTENSION_API_KEY")
	Name string `json:"name"`
	// Description explains when and why to use this environment variable
	Description string `json:"description"`
	// Default is the default value used if the environment variable is not set
	Default string `json:"default,omitempty"`
	// Example provides an example value for documentation purposes
	Example string `json:"example,omitempty"`
}

type Extension struct {
	Id                string           `json:"id"`
	Namespace         string           `json:"namespace"`
	Capabilities      []CapabilityType `json:"capabilities,omitempty"`
	DisplayName       string           `json:"displayName"`
	Description       string           `json:"description"`
	Version           string           `json:"version"`
	Usage             string           `json:"usage"`
	Path              string           `json:"path"`
	Source            string           `json:"source"`
	Providers         []Provider       `json:"providers,omitempty"`
	McpConfig         *McpConfig       `json:"mcp,omitempty"`
	LastUpdateWarning string           `json:"lastUpdateWarning,omitempty"`
	// contains filtered or unexported fields
}

type ExtensionArtifact struct {
	// URL is the location of the artifact
	URL string `json:"url"`
	// Checksum is the checksum of the artifact
	Checksum ExtensionChecksum `json:"checksum"`
	// AdditionalMetadata is a map of additional metadata for the artifact
	AdditionalMetadata map[string]any `json:"-"`
}

type ExtensionChecksum struct {
	// Algorithm is the algorithm used to calculate the checksum
	// Examples: sha256, sha512
	Algorithm string `json:"algorithm"`
	// Value is the checksum value to match during the integrity check.
	Value string `json:"value"`
}

type ExtensionClaims struct {
	jwt.RegisteredClaims
	Capabilities []CapabilityType `json:"cap,omitempty"`
}

type ExtensionCommandMetadata struct {
	// SchemaVersion is the version of the metadata schema (e.g., "1.0")
	SchemaVersion string `json:"schemaVersion"`
	// ID is the extension identifier matching extension.yaml
	ID string `json:"id"`
	// Commands is the list of root-level commands provided by the extension
	Commands []Command `json:"commands"`
	// Configuration describes extension configuration options (Phase 2)
	Configuration *ConfigurationMetadata `json:"configuration,omitempty"`
}

type ExtensionDependency struct {
	// Id is the unique identifier of the dependent extension
	Id string `json:"id"`
	// Version is the version of the dependent extension and supports semantic versioning expressions.
	Version string `json:"version,omitempty"`
}

type ExtensionExample struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Usage       string `json:"usage"`
}

type ExtensionMetadata struct {
	// Id is a unique identifier for the extension
	Id string `json:"id"`
	// Namespace is used to expose extension commands within a named group
	Namespace string `json:"namespace,omitempty"`
	// DisplayName is the name of the extension
	DisplayName string `json:"displayName"`
	// Description is a brief description of the extension
	Description string `json:"description"`
	// Website is the URL to the extension's documentation or homepage
	Website string `json:"website,omitempty"`
	// Versions is a list of versions of the extension that are released over time.
	Versions []ExtensionVersion `json:"versions"`
	// Source is used to store the extension source from where the extension is fetched
	Source string `json:"source,omitempty"`
	// Tags is a list of tags that can be used to filter extensions
	Tags []string `json:"tags,omitempty"`
	// Platforms is a map of platform specific metadata required for extensions
	Platforms map[string]map[string]any `json:"platforms,omitempty"`
}

type ExtensionRunError struct {
	ExtensionId string
	Err         error
}

type ExtensionValidationResult struct {
	// Id is the extension ID (may be empty if missing).
	Id string `json:"id"`
	// DisplayName is the extension display name.
	DisplayName string `json:"displayName"`
	// LatestVersion is the latest version string found.
	LatestVersion string `json:"latestVersion"`
	// Capabilities lists the capabilities of the latest version.
	Capabilities []CapabilityType `json:"capabilities"`
	// Platforms lists the platforms of the latest version.
	Platforms []string `json:"platforms"`
	// Issues contains all validation issues found.
	Issues []ValidationIssue `json:"issues"`
	// Valid is true if no errors were found.
	Valid bool `json:"valid"`
}

type ExtensionVersion struct {
	// Version is the version of the extension
	Version string `json:"version"`
	// RequiredAzdVersion is the azd core version constraint required to use this extension version.
	// When set, azd will only install this version if the running azd version satisfies the constraint.
	// Supports semantic versioning constraint expressions (e.g. ">= 1.24.0").
	RequiredAzdVersion string `json:"requiredAzdVersion,omitempty"`
	// Capabilities is a list of capabilities that the extension provides
	Capabilities []CapabilityType `json:"capabilities,omitempty"`
	// Providers is a list of providers that this extension version registers
	Providers []Provider `json:"providers,omitempty"`
	// Usage is show how to use the extension
	Usage string `json:"usage"`
	// Examples is a list of examples for the extension
	Examples []ExtensionExample `json:"examples"`
	// Artifacts is a map of artifacts for the extension key on platform (os & architecture)
	Artifacts map[string]ExtensionArtifact `json:"artifacts,omitempty"`
	// Dependencies is a list of dependencies for the extension
	// An extension with dependencies and no artifacts is considered an extension pack.
	// The dependencies are resolved and installed when the extension pack is installed.
	Dependencies []ExtensionDependency `json:"dependencies,omitempty"`
	// Entry point is the entry point for the extension
	// This will typically be the name of the executable or script to run
	EntryPoint string `json:"entryPoint,omitempty"`
	// McpConfig is the MCP server configuration for this extension version
	McpConfig *McpConfig `json:"mcp,omitempty"`
}

type FilterOptions struct {
	// Id is used to specify the id of the extension to install
	Id string
	// Namespace is used to specify the namespace of the extension to install
	Namespace string
	// Version is used to specify the version of the extension to install
	Version string
	// Source is used to specify the source of the extension to install
	Source string
	// Tags is used to specify the tags of the extension to install
	Tags []string
	// Capability is used to filter extensions by capability type
	Capability CapabilityType
	// Provider is used to filter extensions by provider name
	Provider string
}

type Flag struct {
	// Name is the flag name without dashes
	Name string `json:"name"`
	// Shorthand is the optional single character shorthand (without dash)
	Shorthand string `json:"shorthand,omitempty"`
	// Description explains the purpose of the flag
	Description string `json:"description"`
	// Type is the data type: "string", "bool", "int", "stringArray", "intArray"
	Type string `json:"type"`
	// Default is the default value when the flag is not provided
	Default any `json:"default,omitempty"`
	// Required indicates if the flag is required
	Required bool `json:"required,omitempty"`
	// ValidValues contains the allowed values for the flag
	ValidValues []string `json:"validValues,omitempty"`
	// Hidden indicates if the flag should be hidden from help output
	Hidden bool `json:"hidden,omitempty"`
	// Deprecated contains a deprecation notice if the flag is deprecated
	Deprecated string `json:"deprecated,omitempty"`
}

type InvokeOptions struct {
	Args        []string
	Env         []string
	StdIn       io.Reader
	StdOut      io.Writer
	StdErr      io.Writer
	Interactive bool

	// Global AZD flags to propagate as environment variables to extension processes.
	Debug       bool
	NoPrompt    bool
	Cwd         string
	Environment string
}

type Manager struct {
	// contains filtered or unexported fields
}

type McpConfig struct {
	// Server contains configuration for starting the extension's MCP server
	Server McpServerConfig `json:"server"`
}

type McpServerConfig struct {
	// Args are the command-line arguments to pass when starting the MCP server
	Args []string `json:"args"`
	// Env are additional environment variables to set when starting the MCP server
	Env []string `json:"env,omitempty"`
}

type Provider struct {
	// Name is the unique identifier for this provider within the extension
	Name string `json:"name"`
	// Type is the type of provider
	Type ProviderType `json:"type"`
	// Description is the description of what this provider does
	Description string `json:"description"`
}

type ProviderType string

type Registry struct {
	// Extensions is a list of extensions in the registry
	Extensions []*ExtensionMetadata `json:"extensions"`
}

type RegistryCache struct {
	// ExpiresOn is the time when this cache entry expires (RFC3339 format)
	ExpiresOn string `json:"expiresOn"`
	// Extensions is the list of extension metadata from the registry
	Extensions []*ExtensionMetadata `json:"extensions"`
}

type RegistryCacheManager struct {
	// contains filtered or unexported fields
}

type RegistryValidationResult struct {
	// Extensions contains validation results for each extension.
	Extensions []ExtensionValidationResult `json:"extensions"`
	// Valid is true if all extensions are valid.
	Valid bool `json:"valid"`
}

type Runner struct {
	// contains filtered or unexported fields
}

type Source interface {
	// Name returns the name of the source.
	Name() string
	// ListExtensions returns a list of AZD compatible templates.
	ListExtensions(ctx context.Context) ([]*ExtensionMetadata, error)
	// GetExtension returns a template by path.
	GetExtension(ctx context.Context, extensionId string) (*ExtensionMetadata, error)
}

type SourceConfig struct {
	Name     string     `json:"name,omitempty"`
	Type     SourceKind `json:"type,omitempty"`
	Location string     `json:"location,omitempty"`
}

type SourceKind string

type SourceManager struct {
	// contains filtered or unexported fields
}

type UpdateCheckResult struct {
	// HasUpdate is true if a newer version is available
	HasUpdate bool
	// InstalledVersion is the currently installed version
	InstalledVersion string
	// LatestVersion is the latest available version
	LatestVersion string
	// ExtensionId is the ID of the extension
	ExtensionId string
	// ExtensionName is the display name of the extension
	ExtensionName string
}

type UpdateChecker struct {
	// contains filtered or unexported fields
}

type ValidationIssue struct {
	// Severity is the severity of the validation issue (error or warning).
	Severity ValidationSeverity `json:"severity"`
	// Message describes the validation issue.
	Message string `json:"message"`
}

type ValidationSeverity string

type VersionCompatibilityResult struct {
	// Compatible contains only the extension versions compatible with the current azd version
	Compatible []ExtensionVersion
	// LatestOverall is the latest version available regardless of compatibility
	LatestOverall *ExtensionVersion
	// LatestCompatible is the latest version that is compatible with the current azd
	LatestCompatible *ExtensionVersion
	// HasNewerIncompatible is true when a newer version exists but is not compatible
	HasNewerIncompatible bool
}