Documentation
¶
Overview ¶
Package cmdutil provides reusable CLI helper functions for Cobra commands. Both the open-source CLI and private overlays import this package to avoid duplicating flag validation, time parsing, and UX helpers.
Index ¶
- Constants
- Variables
- func ConfirmDelete(cmd *cobra.Command, resourceType, resourceName string) bool
- func DetectNumericTypeError(err error) (flagName, badValue string, ok bool)
- func FlagOrFallback(cmd *cobra.Command, primary string, aliases ...string) string
- func GroupRunE(cmd *cobra.Command, args []string) error
- func HintSubCmd(use, hint string) *cobra.Command
- func IsEnvelopeSourced(cmd *cobra.Command) bool
- func IsGroup(cmd *cobra.Command) bool
- func IsLeafCmd(cmd *cobra.Command) bool
- func IsPluginSourced(cmd *cobra.Command) bool
- func LevenshteinDist(a, b string) int
- func LevenshteinThreshold(nameLen int) int
- func MarkEnvelopeSource(cmd *cobra.Command)
- func MarkGroup(cmd *cobra.Command)
- func MarkPluginSource(cmd *cobra.Command)
- func MergeHardcodedLeaves(dynamicRoot, hardcodedRoot *cobra.Command) *cobra.Command
- func MustFlagOrFallback(cmd *cobra.Command, primary string, aliases ...string) (string, error)
- func MustFlagWithHint(cmd *cobra.Command, name, example string) (string, error)
- func MustGetFlag(cmd *cobra.Command, name string) string
- func OverridePriority(cmd *cobra.Command) int
- func ParseISOTimeToMillis(flagName, value string) (int64, error)
- func SetOverridePriority(cmd *cobra.Command, priority int)
- func SuffixLooksLikeValue(suffix, typ, format string, enum []string) bool
- func ValidateRequiredFlagWithAliases(cmd *cobra.Command, primary string, aliases ...string) error
- func ValidateRequiredFlags(cmd *cobra.Command, names ...string) error
- func ValidateTimeRange(startMs, endMs int64) error
- func VisibleFlagNames(cmd *cobra.Command) []string
- type FlagFixResult
Constants ¶
const KindAnnotation = "dws.kind"
KindAnnotation is the annotation key for marking command kinds.
const KindGroup = "group"
KindGroup marks a command created as a group container.
const OverridePriorityAnnotation = "dws.override-priority"
OverridePriorityAnnotation is the cobra.Command.Annotations key used to declare a command's merge-time override priority. Higher values win when same-named leaves collide during merge. Exported so overlays and helpers can reference the same key as the core merge logic without spelling drift.
const SourceAnnotation = "dws.source"
SourceAnnotation records where a command tree came from. Edition overlays use it to distinguish runtime-authored commands from helper fallbacks that happen to share the same top-level product name.
const SourceEnvelope = "envelope"
SourceEnvelope marks a command as authored by the runtime discovery envelope.
const SourcePlugin = "plugin"
SourcePlugin marks a command as an installed plugin extension. Plugin commands are part of the runtime CLI surface, not the embedded base Schema.
Variables ¶
var CommonFlagAliases = map[string]string{
"json": "format json",
"output": "format",
"out": "format",
"o": "format",
"silent": "quiet",
"dry": "dry-run",
"force": "yes",
"f": "yes",
"timeout-seconds": "timeout",
"device-flow": "device",
"deviceflow": "device",
}
CommonFlagAliases maps commonly misused flag names to their correct equivalents.
var FlexTimeLayouts = []string{ time.RFC3339, "2006-01-02T15:04:05Z", "2006-01-02T15:04:05-07:00", "2006-01-02T15:04:05", "2006-01-02 15:04:05", "2006-01-02T15:04", "2006-01-02 15:04", "2006-01-02", "2006/01/02 15:04:05", "2006/01/02", "20060102", }
FlexTimeLayouts is the ordered list of time formats tried by ParseISOTimeToMillis.
Functions ¶
func ConfirmDelete ¶
ConfirmDelete asks for interactive confirmation before destructive operations. Returns true if --yes/-y flag is set or the user types "yes"/"y".
func DetectNumericTypeError ¶
DetectNumericTypeError checks if err is a Cobra/pflag numeric type validation error. Returns the flag name and the bad value if detected.
func FlagOrFallback ¶
FlagOrFallback reads the primary flag; if empty, falls back through alias flags in order, returning the first non-empty value.
func GroupRunE ¶
GroupRunE is a reusable RunE for parent (group) commands that have no business logic of their own. With args it returns an error listing available subcommands; without args it shows help.
func HintSubCmd ¶
HintSubCmd creates a hidden subcommand that only prints a disambiguation hint.
func IsEnvelopeSourced ¶ added in v1.0.16
IsEnvelopeSourced reports whether cmd was authored by the runtime discovery envelope.
func IsPluginSourced ¶ added in v1.0.54
IsPluginSourced reports whether cmd came from an installed plugin.
func LevenshteinDist ¶
LevenshteinDist returns the edit distance between two strings.
func LevenshteinThreshold ¶
LevenshteinThreshold returns the max edit distance allowed based on string length.
func MarkEnvelopeSource ¶ added in v1.0.16
MarkEnvelopeSource stamps cmd with runtime discovery provenance.
func MarkPluginSource ¶ added in v1.0.54
MarkPluginSource stamps cmd with installed-plugin provenance.
func MergeHardcodedLeaves ¶ added in v1.0.16
MergeHardcodedLeaves grafts leaves from hardcodedRoot onto dynamicRoot when the same-named path does not already exist. Groups recurse. On leaf conflicts, the dynamic side wins by default because the runtime envelope is authoritative; hardcoded commands are retained as fallback for paths the envelope does not declare.
A hardcoded leaf or group can opt into replacement by carrying a strictly higher OverridePriority than the dynamic command at the same path.
MergeHardcodedLeaves mutates dynamicRoot in place and returns it. Grafted commands are detached from hardcodedRoot so Cobra parent pointers remain correct.
func MustFlagOrFallback ¶
MustFlagOrFallback works like FlagOrFallback but returns an error when all flags are empty.
func MustFlagWithHint ¶
MustFlagWithHint returns an error with an explicit usage example when the flag is empty.
func MustGetFlag ¶
MustGetFlag retrieves a string flag value, checking both local and inherited flags.
func OverridePriority ¶ added in v1.0.16
OverridePriority returns the override priority annotation value on cmd, or 0 if the annotation is absent or malformed.
func ParseISOTimeToMillis ¶
ParseISOTimeToMillis parses a time string into a millisecond Unix timestamp. Supports RFC3339, UTC Z, timezone-less, space-separated, date-only, and more. When the input lacks an explicit timezone, Asia/Shanghai is assumed.
func SetOverridePriority ¶ added in v1.0.16
SetOverridePriority stamps the override priority annotation on cmd. A positive value asks the merge layer to promote this command over a same-named leaf with a lower (or unset) priority.
func SuffixLooksLikeValue ¶ added in v1.0.27
SuffixLooksLikeValue decides whether a candidate suffix from a glued "--flagsuffix" token plausibly represents a value for a flag's declared type/format/enum. Shared by StickyHandler (PreParse) and SuggestFlagFix (unknown-flag recovery).
typ is a pflag value type string (e.g. "int", "bool", "string"); format is JSON Schema "format" when present (e.g. "date-time"); enum is the schema enum list when present.
func ValidateRequiredFlagWithAliases ¶
ValidateRequiredFlagWithAliases checks that at least one of the primary flag or its aliases is non-empty.
func ValidateRequiredFlags ¶
ValidateRequiredFlags checks that all named string flags are non-empty. Returns a formatted error listing all missing flags, or nil.
func ValidateTimeRange ¶
ValidateTimeRange checks that endMs is strictly after startMs.
func VisibleFlagNames ¶ added in v1.0.27
VisibleFlagNames returns sorted candidate flag names for cmd.Flags() using flagFixCandidate. Intended for agent-facing error recovery (available_flags).
Types ¶
type FlagFixResult ¶
FlagFixResult holds the result of SuggestFlagFix analysis.
func SuggestFlagFix ¶
func SuggestFlagFix(cmd *cobra.Command, flagErr error) FlagFixResult
SuggestFlagFix detects flag-value concatenation errors, common flag aliases, and Levenshtein-close typos.
Source Files