Documentation
¶
Overview ¶
Package cmdutil provides shared utilities for CLI commands: the Factory, error types, and exit-code mapping.
Index ¶
- Constants
- Variables
- func APITimeout() (time.Duration, error)
- func AddJSONFlags(cmd *cobra.Command, exporter **Exporter)
- func CommandGroupArgs(cmd *cobra.Command, args []string) error
- func DebugEnabled() bool
- func ExactArgs(n int) cobra.PositionalArgs
- func ExitCode(err error) int
- func MaximumNArgs(n int) cobra.PositionalArgs
- func NewAPIClient(f *Factory, host, token string) (*api.Client, error)
- func NoArgs(cmd *cobra.Command, args []string) error
- func ShowCommandGroupHelp(cmd *cobra.Command, _ []string) error
- func UserAgent(version string) string
- func ValidatePageLimit(limit int) error
- type AuthError
- type Exporter
- type Factory
- type FlagError
Constants ¶
const MaxPageSize = 100
MaxPageSize is the largest page the public API accepts without silently clamping the caller's request.
Variables ¶
var ErrSilent = errors.New("silent error")
ErrSilent is a sentinel that signals the command has already printed its error and the runner should exit 1 without printing anything further.
Functions ¶
func APITimeout ¶ added in v0.4.0
APITimeout resolves the per-request API timeout from MELANGE_API_TIMEOUT, falling back to api.DefaultRequestTimeout. A set-but-unparsable value is a hard error rather than a silent fallback: an operator who asked for a specific timeout must not get a different one.
func AddJSONFlags ¶
AddJSONFlags registers the shared structured-output flags on cmd and, after flag parsing, points *exporter at a configured Exporter when any of them was used:
--json emit the complete documented result as JSON --jq <expr> filter the JSON through a jq expression (implies --json) --template <tpl> format the JSON with a Go template (implies --json)
--jq and --template are mutually exclusive; expression syntax errors are usage errors (FlagError, exit 2).
func CommandGroupArgs ¶
CommandGroupArgs rejects unmatched tokens as unknown subcommands. Cobra otherwise treats arguments to a non-runnable parent as a request for help, which can make a typo look like a successful command invocation.
func DebugEnabled ¶ added in v0.4.0
func DebugEnabled() bool
DebugEnabled reports whether MELANGE_DEBUG asks for verbose diagnostics on stderr. It is the single source of truth for the debug switch, shared by the API client's request logging and the MCP server's diagnostic logger.
func ExactArgs ¶
func ExactArgs(n int) cobra.PositionalArgs
ExactArgs is cobra.ExactArgs with FlagError-wrapped errors.
func ExitCode ¶
ExitCode maps err to the appropriate process exit code following the melange exit-code contract:
0 nil (success) 1 generic error / ErrSilent / other API errors 2 FlagError (usage error) 4 AuthError / API authentication_error 130 context.Canceled (SIGINT)
func MaximumNArgs ¶
func MaximumNArgs(n int) cobra.PositionalArgs
MaximumNArgs is cobra.MaximumNArgs with FlagError-wrapped errors.
func NewAPIClient ¶
NewAPIClient builds an api.Client for the given host and token, honoring the factory's base transport override and a truthy MELANGE_DEBUG (debug lines go to stderr). token may be empty for unauthenticated clients.
func ShowCommandGroupHelp ¶
ShowCommandGroupHelp keeps a bare command group useful while making it runnable so CommandGroupArgs is evaluated for unmatched subcommands.
func UserAgent ¶ added in v0.4.0
UserAgent is the User-Agent every outgoing Melange API request carries, whatever builds the client — the CLI's own commands or the MCP HTTP server's per-request clients. One function so the API only ever sees one shape of this string.
func ValidatePageLimit ¶
ValidatePageLimit keeps list commands honest about the number of results requested. Callers that need more than one page should use --paginate.
Types ¶
type AuthError ¶
type AuthError struct {
Err error
}
AuthError signals that the user is not authenticated. The runner maps it to exit 4.
type Exporter ¶
type Exporter struct {
// contains filtered or unexported fields
}
Exporter renders a command's documented result in one of the structured output modes selected by --json, --jq, or --template. A nil *Exporter means the command should use its human/tab output instead.
func NewExporter ¶
NewExporter builds an Exporter directly from a jq expression and/or Go template string (either may be empty). Commands that own their output contract (e.g. `melange api`) use this instead of AddJSONFlags.
type Factory ¶
type Factory struct {
IOStreams *iostreams.IOStreams
Config func() (*config.Config, error)
Executable string
Version string
NoInput bool
// HostOverride is the value of the persistent --host flag, set by the
// root command after flag parsing.
HostOverride string
// ApiClient returns an authenticated API client for the resolved
// host+token. It returns AuthError when no token is available, so only
// commands that require auth should call it.
ApiClient func() (*api.Client, error)
// HTTPTransport overrides the base transport of API clients (tests
// inject an httpmock.Registry here); nil means http.DefaultTransport.
HTTPTransport http.RoundTripper
}
Factory carries the shared dependencies that every command receives.
Source Files