gcloud

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
}

type Argument 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
	// 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
	// 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
	// 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
	// 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
	// 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
	// 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
	// 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
	// Repeated indicates that this argument can be specified multiple times.
	// Origin: Inferred from the `repeated` keyword on the proto field.
	Repeated bool
	// 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
	// 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
	// Action specifies the action for the argument (e.g., "store_true", "store_true_false").
	// Origin: Derived for boolean fields based on command type.
	Action string
	// 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
	// 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
	// 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
}

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 []string

	// ExtractResourceResult indicates whether to extract the resource result from the LRO.
	ExtractResourceResult bool
}

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
	// 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
	// Help is the help text for the gcloud flag for this attribute.
	// Origin: Auto-generated using a standard template.
	Help string
	// 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
}

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
	// 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
	// HelpText is the help text to show for the choice.
	HelpText string
}

type Command struct {
	// Name specifies the name of the command.
	Name string

	// 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

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

	// 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 []Argument

	// 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

	// 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 []string

	// Method is the name of the API method to call.
	Method string

	// 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

	// ResponseIDField is the name of the field in the response that contains the resource ID.
	// Origin: Derived from `ResourceMethodParams`.
	ResponseIDField string

	// ReadModifyUpdate indicates whether to use a read-modify-update cycle for Update commands.
	ReadModifyUpdate bool

	// DisableAutoFieldMask disables the field mask auto generation.
	DisableAutoFieldMask bool

	// StarUpdateMask indicates whether to add updateMask="*" to static_fields in request.
	StarUpdateMask bool

	// OutputFormat is the output format for the command (e.g., "table(name, ...)").
	OutputFormat string
}

type CommandGroup struct {
	Name     string
	Path     []string
	HelpText string
	Commands map[string]*Command
	Groups   map[string]*CommandGroup
}

type CommandGroupsByTrack struct {
	GA    *CommandGroup
	BETA  *CommandGroup
	ALPHA *CommandGroup
}

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
	// 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
	// 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
}

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
	// 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
	// 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
	// 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
	// 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
}