Documentation
¶
Overview ¶
Package cmdmeta is the command-surface vocabulary AND the per-value validation engine over it, shared by the operation catalog and the command descriptors: value kinds, the flag and positional shapes, sections, response-field hints, auth, the safety classification, and NormalizeValue/CoerceValue (validate one value against its kind). Its only internal dependency is internal/output (the error taxonomy, a stdlib-only leaf), so any layer can describe AND validate a command surface without pulling in a routing or execution dependency. The cross-field rules that span several params of one operation live with the operations that own them (internal/ops), not here.
Index ¶
- func CoerceValue(p Param, v any, label string) (raw string, present bool, err error)
- func NormalizeValue(p Param, raw, label string) (string, error)
- func ParseDuration(value string) (d time.Duration, ok bool)
- type Auth
- type Param
- type Positional
- type ResponseField
- type Safety
- type Section
- type ValueKind
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CoerceValue ¶
CoerceValue applies the per-kind TYPE rules to an already-present, non-null value decoded to a Go any (bool | int64 | float64 | string | []any), and returns the raw string NormalizeValue then validates — exactly as a CLI flag string would be. It is the shared core behind the frontends whose inputs are typed values rather than already-string flags. Source-specific null/undefined detection stays in the caller; present=false means "treat as omitted" (a null/undefined value handled by the caller, or a false flag).
It owns the money guardrail: a decimal given a number rather than a string is rejected HERE, before any request is built — so no frontend can let a float into price/qty/amount.
func NormalizeValue ¶
NormalizeValue validates and normalizes one raw flag/positional value per its param, returning the value to send (API form). label is the user-facing name used in error messages, e.g. `--price`.
Types ¶
type Auth ¶
type Auth struct {
Permission string
}
Auth describes the signing requirement of an endpoint. A nil *Auth means the endpoint is public. Permission == "" means signed with any key; a non-empty Permission names the API permission the key must hold.
type Param ¶
type Param struct {
// Flag is the CLI flag name without leading dashes (kebab-case).
Flag string
// API is the Korbit parameter name the value is sent as.
API string
Kind ValueKind
Desc string
Required bool
EnumValues []string
Min *int
Max *int
Pattern *regexp.Regexp
PatternDesc string
Default string
// Experimental marks a flag belonging to an opt-in, not-yet-stable feature
// (gated behind --enable-experimental). Plain `--help` hides it; help shown
// with --enable-experimental reveals it. The machine catalog always publishes
// it (with this bit set) so agents can still discover it.
Experimental bool
}
Param is a single flag a command accepts.
type Positional ¶
type Positional struct {
Name string
API string
Kind ValueKind
Desc string
Required bool
Variadic bool
}
Positional is a positional argument.
type ResponseField ¶
ResponseField is one machine-readable success-response field hint for an endpoint: top-level fields, and for an array response the element's fields.
type Safety ¶
type Safety string
Safety classifies an operation's retry/idempotency posture, the basis for the call policy the operation layer derives.
const ( // SafetyReadOnly is a read (GET): retry-safe, no side effect. SafetyReadOnly Safety = "readOnly" // SafetyIdempotent is a non-GET write that is safe to send more than once // with no extra effect (a cancel, or an address generate that returns the // existing address). SafetyIdempotent Safety = "idempotent" // SafetyNonIdempotent is a money-moving write with no natural idempotency: it // is never blindly resent. SafetyNonIdempotent Safety = "nonIdempotent" )
type ValueKind ¶
type ValueKind string
ValueKind is the type of a flag or positional value. It drives validation.
const ( KindString ValueKind = "string" KindInt ValueKind = "int" KindDecimal ValueKind = "decimal" KindEnum ValueKind = "enum" KindSymbol ValueKind = "symbol" KindSymbols ValueKind = "symbols" KindCurrency ValueKind = "currency" KindCSV ValueKind = "csv" KindMs ValueKind = "ms" KindDuration ValueKind = "duration" KindFlag ValueKind = "flag" )
Source Files