gcloud

type API struct {
	// Name is the name of the API. This should be the API name as it appears
	// in the normalized service config (e.g., "compute.googleapis.com").
	Name string `yaml:"name"`

	// APIVersion is the API version of the API (e.g., "v1", "v2beta1").
	APIVersion string `yaml:"api_version,omitempty"`

	// SupportsStarUpdateMasks indicates that this API supports '*' updateMasks
	// in accordance with https://google.aip.dev/134#request-message. The
	// default is assumed to be true for AIP compliant APIs.
	SupportsStarUpdateMasks bool `yaml:"supports_star_update_masks,omitempty"`

	// RootIsHidden applies the gcloud 'hidden' flag to the root command group
	// of the generated surface.  When true, the top-level command group for
	// this API will not appear in `--help` output by default.  See
	// go/gcloud-advanced-topics#hiding-commands-and-command-groups for more
	// details.
	RootIsHidden bool `yaml:"root_is_hidden"`

	// ReleaseTracks are the gcloud release tracks this surface should appear
	// in. This determines the visibility and stability level of the generated
	// commands and resources.
	ReleaseTracks []ReleaseTrack `yaml:"release_tracks,omitempty"`

	// HelpText contains all help text configurations for the surfaces
	// including groups, commands, resources, and flags/arguments related to
	// this API.
	HelpText *HelpTextRules `yaml:"help_text,omitempty"`

	// OutputFormatting contains all output formatting rules for commands
	// within this API. These rules dictate how the results of commands are
	// displayed to the user.
	OutputFormatting []*OutputFormatting `yaml:"output_formatting,omitempty"`

	// CommandOperationsConfig contains long running operations config for
	// methods within this API. This allows customization of how asynchronous
	// operations are handled and displayed.
	CommandOperationsConfig []*CommandOperationsConfig `yaml:"command_operations_config,omitempty"`
}

type ArgSpec struct {
	// APIField is the name of the field in the API message (e.g., "key", "value").
	// Origin: Hardcoded to "key" and "value" for map fields.
	APIField string `yaml:"api_field,omitempty"`
}

type Arguments struct {
	// Params is a slice of Param structs, each defining a single argument.
	// Origin: Generated by iterating over the fields of a method's request message.
	Params []Param `yaml:"params,omitempty"`
}

type Async struct {
	// Collection is the API collection for the long-running operation resource.
	// Origin: Hardcoded to the standard operations collection for the service.
	Collection StringOrSlice `yaml:"collection,omitempty"`

	// ExtractResourceResult indicates whether to extract the resource result from the LRO.
	ExtractResourceResult bool `yaml:"extract_resource_result,omitempty"`
}

type Attribute struct {
	// ParameterName is the name of the API field in the request path that this
	// attribute maps to (e.g., "projectsId").
	// Origin: Inferred from the literal collection identifier that precedes the variable
	// in the resource pattern (e.g., `projects/{project}` -> `projectsId`).
	ParameterName string `yaml:"parameter_name,omitempty"`
	// AttributeName is the name used for the gcloud flag for this attribute
	// (e.g., "project").
	// Origin: Inferred from the name of the variable in the resource pattern (e.g., `{project}`).
	AttributeName string `yaml:"attribute_name,omitempty"`
	// Help is the help text for the gcloud flag for this attribute.
	// Origin: Auto-generated using a standard template.
	Help string `yaml:"help,omitempty"`
	// Property is a gcloud core property that can be used as a fallback value
	// if the flag is not provided (e.g., "core/project").
	// Origin: Hardcoded for standard, well-known attributes like "project".
	Property string `yaml:"property,omitempty"`
}

type Choice struct {
	// ArgValue is the value as it appears on the command line (e.g., "balanced").
	// Origin: Derived from the proto enum value name, converted to kebab-case.
	ArgValue string `yaml:"arg_value,omitempty"`
	// EnumValue is the corresponding string value of the enum in the API.
	// Origin: The original name of the value in the proto enum definition.
	EnumValue string `yaml:"enum_value,omitempty"`
	// HelpText is the help text to show for the choice.
	HelpText string `yaml:"help_text,omitempty"`
}

type Command struct {
	// ReleaseTracks specifies the release tracks (e.g., GA, BETA, ALPHA) for which
	// this command is available.
	// Origin: Derived from the `release_tracks` field in the `gcloud.yaml` config file.
	ReleaseTracks []string `yaml:"release_tracks,omitempty"`

	// AutoGenerated indicates that this command was generated by a tool.
	// Origin: Hardcoded to `true` by this generator.
	AutoGenerated bool `yaml:"auto_generated,omitempty"`

	// Hidden specifies whether this command should be hidden from the user in
	// help text and command listings.
	// Origin: Hardcoded to `true` by this generator.
	Hidden bool `yaml:"hidden,omitempty"`

	// HelpText contains the brief and detailed help text for the command.
	// Origin: Populated from `method_rules` in the `gcloud.yaml` config file.
	HelpText HelpText `yaml:"help_text"`

	// Arguments defines the set of flags and positional arguments for the command.
	// Origin: Generated by parsing the fields of the method's request message from the proto.
	Arguments Arguments `yaml:"arguments"`

	// Request specifies the details of the API request to be made when the
	// command is executed.
	// Origin: Generated by `newRequest`, which determines the API version and collection.
	Request *Request `yaml:"request,omitempty"`

	// Async specifies the configuration for handling long-running operations.
	// Origin: Generated by `newAsync` if the proto method is annotated as a long-running operation.
	Async *Async `yaml:"async,omitempty"`

	// Response specifies the details of the API response.
	Response *Response `yaml:"response,omitempty"`

	// Update specifies configuration for update commands.
	Update *UpdateConfig `yaml:"update,omitempty"`

	// Output specifies configuration for command output.
	Output *OutputConfig `yaml:"output,omitempty"`
}

type CommandOperationsConfig struct {
	// Selector is a comma-separated list of patterns for any element such as a
	// method, a field, an enum value. Each pattern is a qualified name of the
	// element which may end in "*", indicating a wildcard. Wildcards are only
	// allowed at the end and for a whole component of the qualified name, i.e.
	// "foo.*" is ok, but not "foo.b*" or "foo.*.bar".
	//
	// Wildcard may not be applicable for some elements, in those cases an
	// 'InvalidSelectorWildcardError' error will be thrown.  Additionally, some
	// gcloud data elements expect a singular selector, if a comma separated
	// selector string is passed, a 'InvalidSelectorList' error will be thrown.
	//
	// See http://google3/google/api/documentation.proto;l=253;rcl=525006895
	// for API selector details.
	Selector string `yaml:"selector"`

	// DisplayOperationResult determines whether to display the resource result
	// in the output of the command by default.  Set to `true` to display the
	// operation result instead of the final resource.  See
	// http://go/gcloud-creating-commands#async for more details.
	DisplayOperationResult bool `yaml:"display_operation_result"`
}

type Config struct {
	// ServiceName is the name of a service. Each gcloud.yaml file should
	// correlate to a single service config with one or more APIs defined.
	ServiceName string `yaml:"service_name"`

	// APIs describes the APIs for which to generate a gcloud surface.
	APIs []API `yaml:"apis,omitempty"`

	// ResourcePatterns describes resource patterns not included in
	// descriptors, providing additional patterns that might be used for
	// resource identification or command generation.
	ResourcePatterns []ResourcePattern `yaml:"resource_patterns,omitempty"`
}

type HelpText struct {
	// Brief is a short, one-line summary of what the command does.
	// Origin: From the `brief` field in a `method_rule` in `gcloud.yaml`.
	Brief string `yaml:"brief"`
	// Description is a more detailed explanation of the command's functionality.
	// Origin: From the `description` field in a `method_rule` in `gcloud.yaml`.
	Description string `yaml:"description"`
	// Examples provides one or more examples of how to use the command.
	// Origin: From the `examples` field in a `method_rule` in `gcloud.yaml`.
	Examples string `yaml:"examples,omitempty"`
}

type HelpTextElement struct {
	// Brief is a concise, single-line summary of the help text for the CLI
	// element.
	Brief string `yaml:"brief,omitempty"`

	// Description provides a detailed, multi-line description for the CLI
	// element.
	Description string `yaml:"description,omitempty"`

	// Examples provides a list of string examples illustrating how to use the
	// CLI element.
	Examples []string `yaml:"examples,omitempty"`
}

type HelpTextRule struct {
	// Selector is a comma-separated list of patterns for any element such as a
	// method, a field, an enum value. Each pattern is a qualified name of the
	// element which may end in "*", indicating a wildcard. Wildcards are only
	// allowed at the end and for a whole component of the qualified name, i.e.
	// "foo.*" is ok, but not "foo.b*" or "foo.*.bar".
	//
	// Wildcard may not be applicable for some elements, in those cases an
	// 'InvalidSelectorWildcardError' error will be thrown.  Additionally, some
	// gcloud data elements expect a singular selector, if a comma separated
	// selector string is passed, a 'InvalidSelectorList' error will be thrown.
	//
	// See http://google3/google/api/documentation.proto;l=253;rcl=525006895
	// for API selector details.
	Selector string `yaml:"selector,omitempty"`

	// HelpText contains the detailed help text content for the selected
	// element.
	HelpText *HelpTextElement `yaml:"help_text,omitempty"`
}

type HelpTextRules struct {
	// ServiceRules defines help text rules specifically for services.
	ServiceRules []*HelpTextRule `yaml:"service_rules,omitempty"`

	// MessageRules defines help text rules specifically for messages (resource
	// command groups).
	MessageRules []*HelpTextRule `yaml:"message_rules,omitempty"`

	// MethodRules defines help text rules specifically for API methods
	// (commands).
	MethodRules []*HelpTextRule `yaml:"method_rules,omitempty"`

	// FieldRules defines help text rules specifically for individual fields
	// (flags/arguments).
	FieldRules []*HelpTextRule `yaml:"field_rules,omitempty"`
}

type OutputConfig struct {
	// Format is the output format for the command (e.g., "table(name, ...)").
	Format string `yaml:"format,omitempty"`
}

type OutputFormatting struct {
	// Selector is a comma-separated list of patterns for any element such as a
	// method, a field, an enum value. Each pattern is a qualified name of the
	// element which may end in "*", indicating a wildcard. Wildcards are only
	// allowed at the end and for a whole component of the qualified name, i.e.
	// "foo.*" is ok, but not "foo.b*" or "foo.*.bar".
	//
	// Wildcard may not be applicable for some elements, in those cases an
	// 'InvalidSelectorWildcardError' error will be thrown.  Additionally, some
	// gcloud data elements expect a singular selector, if a comma separated
	// selector string is passed, a 'InvalidSelectorList' error will be thrown.
	//
	// See http://google3/google/api/documentation.proto;l=253;rcl=525006895
	// for API selector details.  Must point to a single RPC/command. Wildcards
	// ('*') not allowed for output formatting.
	Selector string `yaml:"selector"`

	// Format is the output formatting string to apply. This string typically
	// follows the `gcloud topic formats` specification (e.g., "table(name,
	// createTime)", "json").
	Format string `yaml:"format"`
}

type Param struct {
	// ArgName is the name of the argument as it appears on the command line
	// (e.g., "instance-id").
	// Origin: Derived from the proto field name, converted to kebab-case.
	// TODO(https://github.com/googleapis/librarian/issues/3287): Support arg groups.
	// TODO(https://github.com/googleapis/librarian/issues/3288): Handle arg name collisions with path prefixes.
	ArgName string `yaml:"arg_name,omitempty"`
	// APIField is the dot-separated path to the field in the API request message
	// that this argument's value should be placed in (e.g., "instance.name").
	// Origin: Derived from the `json_name` of the proto field, with prefixes for nested messages.
	APIField string `yaml:"api_field,omitempty"`
	// HelpText is the help text for this specific argument.
	// Origin: From a `field_rule` in `gcloud.yaml`, or a default value is generated if none is provided.
	HelpText string `yaml:"help_text"`
	// IsPositional indicates that this argument is a positional argument rather
	// than a flag.
	// Origin: Set to `true` for the primary resource argument of a command.
	IsPositional bool `yaml:"is_positional,omitempty"`
	// IsPrimaryResource indicates that this argument represents the primary
	// resource being acted upon by the command.
	// Origin: Set to `true` for the primary resource argument, identified by its field name (e.g., "name").
	IsPrimaryResource bool `yaml:"is_primary_resource,omitempty"`
	// RequestIDField is the name of the field in the request message that should
	// hold the ID of the resource being created. This is used for `Create` methods.
	// Origin: Derived from the name of the primary resource's ID field (e.g., "instance_id").
	RequestIDField string `yaml:"request_id_field,omitempty"`
	// ResourceSpec defines the structure of a resource argument, including its
	// name, collection, and attributes.
	// Origin: Generated for fields that have a `(google.api.resource_reference)` annotation.
	ResourceSpec *ResourceSpec `yaml:"resource_spec,omitempty"`
	// Required indicates that this argument must be provided by the user.
	// Origin: Inferred from the `(google.api.field_behavior) = REQUIRED` annotation on the proto field.
	Required bool `yaml:"required"`
	// Repeated indicates that this argument can be specified multiple times.
	// Origin: Inferred from the `repeated` keyword on the proto field.
	Repeated bool `yaml:"repeated"`
	// Clearable indicates whether to add update flags for update commands.
	// Origin: Used for map and repeated fields in Update commands to allow clearing values.
	Clearable bool `yaml:"clearable,omitempty"`
	// Type specifies the data type of the argument's value (e.g., "long", "float").
	// Origin: Mapped from the proto field's data type (e.g., `int64` becomes `long`).
	Type string `yaml:"type,omitempty"`
	// Choices is a list of valid values for an enum-based argument.
	// Origin: Generated by iterating over the values of a proto `enum`.
	Choices []Choice `yaml:"choices,omitempty"`
	// Spec defines the structure for complex argument types, such as key-value pairs for a map.
	// Origin: Generated for `map` fields in a proto message.
	Spec []ArgSpec `yaml:"spec,omitempty"`
	// ResourceMethodParams maps API method parameters to resource attributes,
	// used for non-standard resource name formats.
	// Origin: Generated for resource reference arguments to map the parsed name correctly.
	ResourceMethodParams map[string]string `yaml:"resource_method_params,omitempty"`
}

type ReleaseTrack string

type Request struct {
	// APIVersion is the version of the API to call (e.g., "v1").
	// Origin: Derived from the `api_version` field in the `gcloud.yaml` config file.
	APIVersion string `yaml:"api_version,omitempty"`
	// Collection is the list of API collections that this command operates on.
	// Origin: Constructed from the API service name and the resource's collection path.
	Collection StringOrSlice `yaml:"collection,omitempty"`
	// Method is the name of the API method to call.
	Method string `yaml:"method,omitempty"`
}

type ResourcePattern struct {
	// Type is the resource type (e.g., "example.googleapis.com/Service").
	Type string `yaml:"type"`

	// Patterns is a list of resource patterns (e.g.,
	// "projects/{project}/locations/{location}/services/{service}").  These
	// define the structure of resource names.
	Patterns []string `yaml:"patterns,omitempty"`

	// APIVersion is the API version associated with this resource pattern
	// (e.g., "v1").
	APIVersion string `yaml:"api_version,omitempty"`
}

type ResourceSpec struct {
	// Name is the singular name of the resource (e.g., "instance").
	// Origin: Inferred from the last variable segment of a resource pattern (e.g., `{instance}`).
	Name string `yaml:"name,omitempty"`
	// PluralName is the plural name of the resource (e.g., "instances").
	// Origin: Derived from the `plural` field in the `(google.api.resource)` annotation, or
	// inferred from the literal segment preceding the final variable in the resource pattern.
	PluralName string `yaml:"plural_name,omitempty"`
	// Collection is the unique identifier for the resource type in gcloud's
	// resource registry (e.g., "parallelstore.projects.locations.instances").
	// Origin: Constructed from the API's service name and the literal collection identifiers
	// in the resource's pattern string, as defined by AIP-122.
	Collection string `yaml:"collection,omitempty"`
	// Attributes defines the components that make up a resource's unique name.
	// Origin: Generated by parsing the variable segments (e.g., `{project}`, `{location}`)
	// from the resource's pattern string.
	Attributes []Attribute `yaml:"attributes,omitempty"`
	// DisableAutoCompleters prevents gcloud from attempting to provide tab-completion
	// for this resource.
	// Origin: Hardcoded to `true` for referenced resources to avoid cross-API complexities.
	DisableAutoCompleters bool `yaml:"disable_auto_completers"`
}

type Response struct {
	// IDField is the name of the field in the response that contains the resource ID.
	IDField string `yaml:"id_field,omitempty"`
}

type StringOrSlice []string

type UpdateConfig struct {
	// ReadModifyUpdate indicates whether to use a read-modify-update cycle.
	ReadModifyUpdate bool `yaml:"read_modify_update"`

	// DisableAutoFieldMask disables the field mask auto generation.
	DisableAutoFieldMask bool `yaml:"disable_auto_field_mask,omitempty"`
}