// CLI annotation extension type.
//
// The fraser `ia` CLI is proto-driven: `cmd/protoc-gen-ia-cli` walks every
// service in the buf input and emits a Cobra command per RPC. The default
// mapping follows the IA convention (service noun + verb), and per-RPC
// `(tars.cli.v1.command)` annotations override individual mappings. Per-
// field `(tars.cli.v1.field)` annotations rename the generated CLI flag.
//
// Field number 50002 mirrors IA's allocation. Fraser's auth extension uses
// 50001; this proto reserves 50002 in google.protobuf.MethodOptions for
// CLI customization and 50003 in google.protobuf.FieldOptions for the
// per-field flag customization.
syntax = "proto3";

package tars.cli.v1;

import "google/protobuf/descriptor.proto";

option go_package = "github.com/tetrateio/fraser/api/tars/cli/v1;cliv1";

// Command customizes the CLI mapping for a single RPC.
//
// Every field is optional -- omitting `(tars.cli.v1.command)` leaves the
// default mapping in place. Customizations are additive: each field
// overrides one default behavior.
message Command {
  // Override the last segment of the command path. Default is the verb
  // portion of the RPC name in lower-kebab-case.
  string name = 1;

  // Additional command names that resolve to the same command. Useful for
  // short aliases on long actions, e.g. ["stop"] for "drain".
  repeated string aliases = 2;

  // Request field name (snake_case) that becomes the command's positional
  // argument instead of a flag. Typically the resource ID for action verbs:
  // dataplane_id on DrainDataplane -> `ia dataplanes drain DP_ID`.
  string primary_flag = 3;

  // 4 reserved (was `bool confirm`; removed before the first CLI shipped
  // because no RPC needed interactive confirmation -- destructive actions
  // are gated by --yes at the cobra layer).
  reserved 4;
  reserved "confirm";

  // Hide the command from --help. The command is still registered and
  // invokable; just not advertised. Used for internal-only commands.
  bool hidden = 5;

  // 6 reserved (was `string output_template`; removed because the
  // generator emits JSON only and no command supplied a template).
  reserved 6;
  reserved "output_template";

  // Full command path override. When set, takes precedence over both the
  // default service-noun + verb mapping and the `name` field. Each entry
  // is a segment in the command tree, e.g. ["whoami"] mounts the RPC at
  // the root, ["keys", "create"] mounts it under a `keys` parent.
  repeated string path = 7;
}

// Field customizes the CLI mapping for a single request-message field.
//
// Omitting `(tars.cli.v1.field)` leaves the default mapping in place
// (snake_case -> kebab-case flag name).
message Field {
  // Override the generated flag name. Default is the field name converted
  // from snake_case to kebab-case (e.g. customer_id -> customer-id).
  // Setting `flag: "customer"` produces `--customer`.
  string flag = 1;

  // Hide the flag from --help. The flag is still parsed when supplied.
  bool hidden = 2;
}

extend google.protobuf.MethodOptions {
  // Field 50002 holds the CLI-mapping override for this RPC. Coexists
  // with the existing `tars.auth.v1.auth` extension at 50001.
  Command command = 50002;
}

extend google.protobuf.FieldOptions {
  // Field 50003 holds the CLI flag override for this request-message
  // field. Picked to sit next to the method-level 50002 allocation.
  Field field = 50003;
}
