package rpc import ( "encoding/csv" "fmt" "strconv" "strings" "github.com/flanksource/clicky" "github.com/flanksource/clicky/flags" "github.com/spf13/cobra" "github.com/spf13/pflag" ) // Converter handles converting Cobra commands to generic RPC operations type Converter struct { config *Config } // NewConverter creates a new RPC converter with the given configuration func NewConverter(config *Config) *Converter { if config == nil { config = DefaultConfig() } return &Converter{ config: config, } } // ConvertCommand converts a single Cobra command to an RPC operation func (c *Converter) ConvertCommand(cmd *cobra.Command) (*RPCOperation, error) { cmdPath := getCommandPath(cmd) commandMeta := clicky.GetCommandOpenAPIMeta(cmd) // Build input schema from flags schema := Schema{ Type: "object", Properties: make(map[string]Property), Required: []string{}, } var parameters []RPCParameter if clicky.AcceptsPositionalArgs(cmd) && !optionalIDShadowedByFlag(cmd, commandMeta) { parameters = addPositionalParameter(cmd, &schema, parameters, commandMeta != nil && commandMeta.OptionalID) } parameters, err := c.addFlagParameters(cmd, &schema, parameters) if err != nil { return nil, fmt.Errorf("%s: %w", cmdPath, err) } // Generate HTTP method based on command semantics method := c.inferHTTPMethod(cmd, cmdPath) // Generate REST path if enabled path := "" if c.config.AutoGeneratePaths { path = c.generateRESTPath(cmd, cmdPath) } // Update parameter locations based on path c.updateParameterLocations(¶meters, path) // Combine default tags with command-specific tags tags := append([]string{}, c.config.DefaultTags...) if parentName := c.getParentCommandName(cmd); parentName != "" { tags = append(tags, parentName) } operation := &RPCOperation{ Name: cmdPath, Description: cmd.Short, Parameters: parameters, Schema: schema, Command: NewCobraExecutableCommand(cmd), Path: path, Method: method, Tags: tags, } operation.Clicky = &ClickyOperationMeta{ Command: strings.ReplaceAll(cmdPath, " ", "/"), } if commandMeta != nil { applyCommandMeta(operation, commandMeta) } attachCommandFuncs(operation, cmd) return operation, nil } // optionalIDShadowedByFlag reports whether an optional-id action also declares // a flag named like its positional (recon's `resource sync --id`): the flag // owns that name over HTTP, so publishing the positional would steal its values. func optionalIDShadowedByFlag(cmd *cobra.Command, meta *clicky.CommandOpenAPIMeta) bool { name := extractParameterName(cmd.Use) return meta != nil && meta.OptionalID && name != "" && cmd.Flags().Lookup(name) != nil } // addPositionalParameter publishes the command's positional argument: a named // string parameter when Use names one, otherwise a generic args array. An // optional id is query-only: it stays out of the body schema (which also // shapes tool inputs), so collection actions that never read it — and hosts // that decode their body strictly — are not offered a phantom body field. func addPositionalParameter(cmd *cobra.Command, schema *Schema, parameters []RPCParameter, queryOnly bool) []RPCParameter { name, typ, description := extractParameterName(cmd.Use), "string", "Positional argument from command" if name == "" { name, typ, description = "args", "array", "Positional arguments for the command" } // cobra validates args itself: a command that rejects none requires one. required := cmd.Args != nil && cmd.Args(cmd, nil) != nil if !queryOnly { schema.Properties[name] = Property{Type: typ, Description: description} if required { schema.Required = append(schema.Required, name) } } // In is updated to "path" later if the parameter appears in the URL. return append(parameters, RPCParameter{Name: name, Type: typ, Description: description, Required: required, In: "query", Positional: true}) } // addFlagParameters publishes the command's own flags. LocalNonPersistentFlags // keeps out the inherited persistent globals (format/log-level/properties/...) // that cobra folds into Flags(), and the command's own persistent flags, which // exist to cascade to children rather than parameterize this operation. func (c *Converter) addFlagParameters(cmd *cobra.Command, schema *Schema, parameters []RPCParameter) ([]RPCParameter, error) { var flagErr error cmd.LocalNonPersistentFlags().VisitAll(func(flag *pflag.Flag) { // cobra's own --help/--version are not operation arguments; they join the // command's local flags once it has been executed. if flag.Hidden || len(flag.Annotations[cobra.FlagSetByCobraAnnotation]) > 0 { return } param, err := flagParameter(flag) if err != nil && flagErr == nil { flagErr = err } // Boolean flags always have defaults, so they are never required. if flag.Value.Type() != "bool" && c.isFlagRequired(cmd, flag.Name) { schema.Required = append(schema.Required, flag.Name) param.Required = true } schema.Properties[flag.Name] = Property{Type: param.Type, Description: flag.Usage, Default: param.Default, Enum: flags.AllowedValues(flag)} parameters = append(parameters, param) }) return parameters, flagErr } // flagParameter maps a flag's pflag type and default onto a query parameter. // A malformed slice default is reported, but the parameter is still returned. func flagParameter(flag *pflag.Flag) (RPCParameter, error) { param := RPCParameter{ Name: flag.Name, Description: flag.Usage, In: "query", Enum: flags.AllowedValues(flag), } switch flag.Value.Type() { case "bool": param.Type = "boolean" if flag.DefValue != "" { param.Default = flag.DefValue == "true" } case "int", "int8", "int16", "int32", "int64", "float32", "float64": param.Type = "number" if strings.HasPrefix(flag.Value.Type(), "int") { param.Type = "integer" } if n, err := strconv.ParseFloat(flag.DefValue, 64); err == nil { param.Default = n } case "stringSlice", "stringArray", "intSlice", "int32Slice", "int64Slice", "uintSlice", "float32Slice", "float64Slice", "boolSlice", "durationSlice": param.Type = "array" values, err := sliceDefault(flag.DefValue) if len(values) > 0 { param.Default = values } if err != nil { return param, fmt.Errorf("--%s: %w", flag.Name, err) } default: param.Type = "string" // pflag renders an empty slice default as the literal "[]". Emitting // that as a schema default puts the two characters "[]" in every // generated form field, and a client that posts the pre-filled value // back sends a one-element slice containing "[]". A repeatable flag // with no default simply has none. if flag.DefValue != "" && (!isSliceFlag(flag) || flag.DefValue != "[]") { param.Default = flag.DefValue } } return param, nil } // applyCommandMeta copies a command's OpenAPI annotations onto the operation. func applyCommandMeta(operation *RPCOperation, meta *clicky.CommandOpenAPIMeta) { operation.Clicky.SurfaceID = clickySurfaceID(meta.Entity, meta.Parent, meta.Admin) operation.Clicky.Entity = meta.Entity operation.Clicky.Parent = meta.Parent operation.Clicky.Aliases = append([]string(nil), meta.Aliases...) operation.Clicky.Admin = meta.Admin operation.Clicky.Icon = meta.Icon operation.Clicky.Path = meta.Path operation.Clicky.Title = meta.Title operation.Clicky.Verb = meta.Verb operation.Clicky.Scope = meta.Scope if meta.Verb == "" && meta.Entity != "" { operation.Clicky.Verb = "list" operation.Clicky.Scope = "collection" } operation.Clicky.ActionName = meta.ActionName if !meta.OptionalID { operation.Clicky.IDParam = meta.IDParam } operation.Clicky.SupportsLookup = meta.SupportsLookup operation.Clicky.SupportsFilterMode = meta.SupportsFilterMode operation.Clicky.Schedule = meta.Schedule hints := meta.ToolHints if hints.Group == "" { hints.Group = meta.ToolGroup } operation.ToolHints = hints operation.Clicky.ToolHints = hints if !hints.IsZero() { operation.Clicky.OpenAPIToolHints = &hints } operation.Clicky.Group = hints.Group operation.Group = hints.Group } // attachCommandFuncs wires the command's registered data, stream and lookup // handlers and its declared media and response shape onto the operation. func attachCommandFuncs(operation *RPCOperation, cmd *cobra.Command) { if df := clicky.GetDataFunc(cmd); df != nil { operation.DataFunc = df } if cdf := clicky.GetContextDataFunc(cmd); cdf != nil { operation.ContextDataFunc = ContextDataFunc(cdf) } if sf := clicky.GetStreamFunc(cmd); sf != nil { operation.StreamFunc = sf } if media := clicky.GetCommandMedia(cmd); media.Request != nil || media.Response != nil { operation.RequestMedia, operation.ResponseMedia = media.Request, media.Response } if lf := clicky.GetLookupFunc(cmd); lf != nil { operation.LookupFunc = lf } if clf := clicky.GetContextLookupFunc(cmd); clf != nil { operation.ContextLookupFunc = ContextLookupFunc(clf) } if meta := clicky.GetCommandResponseMeta(cmd); meta != nil { operation.ResponseType = meta.Type operation.ResponseArray = meta.Array operation.ResponsePaged = meta.Paged operation.ResponseEntityID = meta.EntityID } } func clickySurfaceID(entity string, parent string, admin bool) string { if entity == "" { return "" } parts := []string{"entity", entity} if parent != "" { parts = append(parts, "parent", parent) } if admin { parts = append(parts, "admin") } return strings.Join(parts, ":") } // ConvertCommandTree recursively converts a command and its subcommands func (c *Converter) ConvertCommandTree(rootCmd *cobra.Command) (*RPCService, error) { var operations []RPCOperation err := c.walkCommands(rootCmd, func(cmd *cobra.Command) error { if c.shouldConvertCommand(cmd) { op, err := c.ConvertCommand(cmd) if err != nil { return err } operations = append(operations, *op) } return nil }) if err != nil { return nil, err } // Get service name from root command serviceName := rootCmd.Name() if serviceName == "" { serviceName = "api" } service := &RPCService{ Name: serviceName, Version: "1.0.0", Description: rootCmd.Long, Operations: operations, } return service, nil } // shouldConvertCommand determines if a command should be converted to an RPC operation func (c *Converter) shouldConvertCommand(cmd *cobra.Command) bool { // Skip root command and commands without Run function if cmd.Parent() == nil || (cmd.Run == nil && cmd.RunE == nil) { return false } // A command the author marked local-only administers the process rather than // serving a resource. Publishing the CLI published these too, so an // unauthenticated request could run a schema migration or start a nested // server. if clicky.IsLocalOnly(cmd) { return false } // Skip an entity's `list` subcommand when its parent entity-root is itself // runnable as a list shortcut (parent has RunE, an entity annotation, and // no operation verb). Both produce the same GET /api/v1/, and the // parent is the canonical endpoint that mirrors the CLI. if meta := clicky.GetCommandOpenAPIMeta(cmd); meta != nil && meta.Verb == "list" { parent := cmd.Parent() if parent != nil && (parent.RunE != nil || parent.Run != nil) { if parentMeta := clicky.GetCommandOpenAPIMeta(parent); parentMeta != nil && parentMeta.Verb == "" && parentMeta.Entity != "" { return false } } } return true } // walkCommands recursively walks through all commands func (c *Converter) walkCommands(cmd *cobra.Command, fn func(*cobra.Command) error) error { // Process current command if err := fn(cmd); err != nil { return err } // Process subcommands for _, subCmd := range cmd.Commands() { if err := c.walkCommands(subCmd, fn); err != nil { return err } } return nil } // inferHTTPMethod attempts to infer appropriate HTTP method from command semantics func (c *Converter) inferHTTPMethod(cmd *cobra.Command, cmdPath string) string { if meta := clicky.GetCommandOpenAPIMeta(cmd); meta != nil { if meta.Method != "" { return strings.ToUpper(meta.Method) } // Entity-root command (annotated with entity name but no operation verb). // It mirrors the CLI: typing `xero-cli accounts` lists, so the matching // REST endpoint is GET /api/v1/accounts. Without this, the cmdPath // "accounts" matches no CRUD keyword below and falls through to // DefaultMethod (POST), colliding with the entity's `create` subcommand. if meta.Verb == "" && meta.Entity != "" { return "GET" } // An annotated operation states its verb, so use it rather than guessing // from the command path. The guess below matches CRUD keywords anywhere // in that path, which silently misreads any entity whose *name* contains // one: "target update" contains "get", so it inferred GET and collided // with the entity's own list route. "budget delete" and "asset set" fail // the same way. if method := methodForVerb(meta.Verb); method != "" { return method } } // Match the last segment — the verb — rather than searching the whole path. // A command path carries its parents' names, and matching anywhere in it // reads a CRUD keyword out of a noun: "target scan" contains "get", so the // action that starts a scan was published as a safe, prefetchable GET. verb := strings.ToLower(cmdPath) if index := strings.LastIndex(verb, " "); index != -1 { verb = verb[index+1:] } switch verb { case "get", "list", "show", "describe": return "GET" case "create", "add", "new": return "POST" case "update", "edit", "modify", "set": return "PUT" case "delete", "remove", "destroy": return "DELETE" } // Anything else does something rather than returning something, so the // configured default (POST) is the safe reading. return c.config.DefaultMethod } // methodForVerb maps an entity operation verb to its HTTP method. An empty // result means the verb is not one of the CRUD four — a custom action, say — // and the caller should fall back to inferring one. func methodForVerb(verb string) string { switch strings.ToLower(verb) { case "list", "get": return "GET" case "create": return "POST" case "update": return "PUT" case "delete": return "DELETE" default: return "" } } // generateRESTPath generates a REST API path from command hierarchy // joinRoutePath resolves a declared operation path. An absolute path is the // whole URL, so a route keeps a shape the prefix does not describe; a relative // one is joined to the prefix, so the common case does not repeat it. func joinRoutePath(prefix, declared string) string { if strings.HasPrefix(declared, "/") { return declared } return strings.TrimSuffix(prefix, "/") + "/" + declared } func (c *Converter) generateRESTPath(cmd *cobra.Command, cmdPath string) string { // Convert command path to REST path // e.g., "user create" -> "/api/v1/user" // e.g., "user get [id]" -> "/api/v1/user/{id}" // e.g., "policy recalculate " -> "/api/v1/policy/{id}/recalculate" // e.g., "policy bulk-suspend [id...]" -> "/api/v1/policy/{id}/bulk-suspend" parts := strings.Split(cmdPath, " ") operationMeta := clicky.GetCommandOpenAPIMeta(cmd) // A declared path is the answer. Nothing below can improve on a URL the // registration named deliberately, and the derivation must not quietly // move an operation its callers already address. if operationMeta != nil && operationMeta.RoutePath != "" { return joinRoutePath(c.config.PathPrefix, operationMeta.RoutePath) } // Build path with prefix pathParts := []string{c.config.PathPrefix} // A bulk action is an action on a selection whatever it is called: `delete` // aimed at forty rows is not the entity's own delete, so the CRUD-name // shortcuts below — which collapse a verb onto /entity/{id} — must not claim // it. Its route is /entity/{id}/ like every other bulk action's. bulkAction := isBulkActionCommand(operationMeta) for i, part := range parts { // Skip the last part if it's a CRUD operation if i == len(parts)-1 { if isCRUDOperation(part) && !bulkAction && (operationMeta == nil || !operationMeta.SupportsFilterMode) { partLower := strings.ToLower(part) // get/delete/inspect always take an {id} path parameter if partLower == "get" || partLower == "delete" || partLower == "inspect" { paramName := extractParameterName(cmd.Use) if paramName == "" { paramName = "id" } pathParts = append(pathParts, "{"+paramName+"}") } break } } // Use resource names as-is without pluralization if i < len(parts)-1 || !isCRUDOperation(part) || bulkAction || (operationMeta != nil && operationMeta.SupportsFilterMode) { pathParts = append(pathParts, part) } } // For non-CRUD action commands with positional args under a parent entity, // restructure to /entity/{id}/action pattern. // e.g., /api/v1/policy/recalculate with Use="recalculate " // -> /api/v1/policy/{id}/recalculate // Only applies when the command is nested under a parent entity command // (not at the top level under the root command). // // Actions declared with WithOptionalID are exempt: they are invocable // without an id (collection-level summaries like `activity overview`), so // inserting an {id} segment would make the no-id REST call (which the // frontend issues) fall through to the entity's get-by-id route. Keep the // flat /entity/action path for those. if operationMeta != nil && operationMeta.OptionalID { return strings.Join(pathParts, "/") } // A multi-operand action (e.g. `diff `) compares two instances and // has no single entity id to lift into the path — both operands are body // args. Lifting the first into {id} produces /entity/{a}/diff, which the // flat-path frontend never calls. Keep it flat; only single-positional // actions (`recalculate `) restructure to /entity/{id}/action. if positionalOperandCount(cmd.Use) > 1 { return strings.Join(pathParts, "/") } if cmd.Parent() != nil && cmd.Parent().Parent() != nil && (bulkAction || !isCRUDOperation(cmd.Name())) && len(pathParts) >= 2 { if paramName := actionIDParam(cmd); paramName != "" { // Insert {id} before the action verb last := len(pathParts) - 1 pathParts = append(pathParts[:last:last], "{"+paramName+"}", pathParts[last]) } } return strings.Join(pathParts, "/") } // actionIDParam names the id an action lifts into its path: the positional // named in Use, else the first common id flag (, Number, id). func actionIDParam(cmd *cobra.Command) string { if paramName := extractParameterName(cmd.Use); paramName != "" { return paramName } parentName := cmd.Parent().Name() for _, flagName := range []string{parentName, parentName + "Number", "id"} { if cmd.Flags().Lookup(flagName) != nil { return flagName } } return "" } // extractParameterName extracts parameter name from Use field // e.g., "get [policyNumber]" -> "policyNumber" // e.g., "get [id]" -> "id" func extractParameterName(use string) string { // Try first (e.g., "get ") start := strings.Index(use, "<") end := strings.Index(use, ">") if start != -1 && end != -1 && end > start { name := strings.TrimSpace(use[start+1 : end]) if isValidParamName(name) { return name } } // Try [param] (e.g., "get [id]") start = strings.Index(use, "[") end = strings.Index(use, "]") if start != -1 && end != -1 && end > start { name := strings.TrimSpace(use[start+1 : end]) if isValidParamName(name) { return name } } return "" } // positionalOperandCount counts the valid positional operands declared in a // command's Use string — both and [optional] forms. Variadic / // body-style tokens (`[args...]`, `key=value`) and the conventional `[flags]` // placeholder are not operands and don't count. Used to distinguish a single-id // action (`recalculate `, count 1, lifts to /entity/{id}/action) from a // multi-operand action (`diff `, count 2, stays flat). func positionalOperandCount(use string) int { count := 0 for _, open := range []struct{ l, r byte }{{'<', '>'}, {'[', ']'}} { s := use for { start := strings.IndexByte(s, open.l) if start == -1 { break } end := strings.IndexByte(s[start:], open.r) if end == -1 { break } end += start name := strings.TrimSpace(s[start+1 : end]) if name != "flags" && isValidParamName(name) { count++ } s = s[end+1:] } } return count } // isBulkActionCommand reports whether an operation is an entity bulk action — // an action on a collection that still addresses its selection through an id // path parameter. That combination is unique to bulk actions: a single action // is entity-scoped, and a collection-scoped action invocable without an id // (WithOptionalID) takes its optional id as a query parameter, not a path one. func isBulkActionCommand(meta *clicky.CommandOpenAPIMeta) bool { return meta != nil && meta.ActionName != "" && meta.IDParam != "" && meta.Scope == "collection" && !meta.OptionalID } func isValidParamName(name string) bool { if name == "" { return false } // Reject variadic/body-style args like "key=value ...", "[args...]" if strings.Contains(name, "=") || strings.Contains(name, "...") || strings.Contains(name, " ") { return false } return true } // updateParameterLocations updates parameter "In" field to "path" for parameters that appear in the URL path func (c *Converter) updateParameterLocations(parameters *[]RPCParameter, path string) { for i := range *parameters { param := &(*parameters)[i] // Check if parameter name appears in path as {paramName} if strings.Contains(path, "{"+param.Name+"}") { param.In = "path" param.Required = true // Path parameters are always required } } } // isCRUDOperation checks if a command part represents a CRUD operation func isCRUDOperation(part string) bool { crudOps := []string{"create", "get", "list", "update", "delete", "show", "describe", "set", "add", "remove"} partLower := strings.ToLower(part) for _, op := range crudOps { if partLower == op { return true } } return false } // getParentCommandName returns the name of the parent command for tagging func (c *Converter) getParentCommandName(cmd *cobra.Command) string { if cmd.Parent() != nil && cmd.Parent().Parent() != nil { return cmd.Parent().Name() } return "" } // sliceDefault parses pflag's rendering of a slice flag default ("[a,b]") into // its values; the empty slice "[]" has none. func sliceDefault(defValue string) ([]any, error) { inner := strings.TrimSuffix(strings.TrimPrefix(defValue, "["), "]") if inner == "" { return nil, nil } record, err := csv.NewReader(strings.NewReader(inner)).Read() if err != nil { return nil, fmt.Errorf("slice default %q: %w", defValue, err) } values := make([]any, len(record)) for i, v := range record { values[i] = v } return values, nil } // isSliceFlag reports whether a flag holds multiple values, i.e. whether pflag // would render its zero value as "[]". func isSliceFlag(flag *pflag.Flag) bool { _, ok := flag.Value.(pflag.SliceValue) return ok } // isFlagRequired checks if a flag is marked as required using reflection func (c *Converter) isFlagRequired(cmd *cobra.Command, flagName string) bool { // Look up the flag in the command's flag set flag := cmd.Flags().Lookup(flagName) if flag == nil { // Try persistent flags if not found in local flags flag = cmd.PersistentFlags().Lookup(flagName) if flag == nil { return false } } // Check if the flag has been marked as required by looking for Cobra's // internal required flag annotation. When MarkFlagRequired is called, // Cobra adds the "cobra_annotation_bash_completion_one_required_flag" // annotation to the flag. if flag.Annotations != nil { _, isRequired := flag.Annotations["cobra_annotation_bash_completion_one_required_flag"] return isRequired } return false } // getCommandPath returns the full command path (e.g., "status", "ai cache") func getCommandPath(cmd *cobra.Command) string { if cmd.Parent() == nil { return cmd.Name() } parts := []string{} for c := cmd; c.Parent() != nil; c = c.Parent() { parts = append([]string{c.Name()}, parts...) } return strings.Join(parts, " ") }