Documentation
¶
Overview ¶
Package argval holds typed argument extractors for MCP tool handlers.
Before argval, handlers reached into the raw argument map with req.GetInt / req.GetString and ad-hoc presence checks. Those checks could not distinguish "argument missing" from "argument present but wrong type" (both collapsed to the Go zero value), so a string passed for a numeric id reported "missing required parameter: id", and an explicit id:0 looked missing too. argval reads the raw map directly and returns a structured *Error carrying a dotted code, the field name, and the offending value, so MCP clients can branch on {code, field, got} instead of parsing prose.
Index ¶
- Constants
- type Error
- func EnumOneOf(args map[string]any, field string, allowed []string) (string, *Error)
- func Hash(args map[string]any, field string, minLen int) (string, *Error)
- func Int(args map[string]any, field string, opts ...IntOption) (value int, present bool, err *Error)
- func MutuallyRequired(args map[string]any, fieldA, fieldB string) *Error
- func OneOfRequired(args map[string]any, fields ...string) *Error
- func RefName(args map[string]any, field string) (string, *Error)
- type IntOption
Constants ¶
const ( CodeMissing = "arg.missing" CodeInvalidType = "arg.invalid_type" CodeOutOfRange = "arg.out_of_range" CodeInvalidValue = "arg.invalid_value" )
Error codes. These are client-side validation codes, distinct from the backend.ErrorCode catalogue (which classifies server responses).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Error ¶
type Error struct {
Code string `json:"code"`
Field string `json:"field"`
Got string `json:"got,omitempty"`
Message string `json:"message"`
}
Error is a client-side argument-validation failure. It maps to the MCP tool-error envelope as {code, field, got, message}. Code is a dotted token (e.g. "arg.invalid_type") so clients can branch without parsing the human-readable Message.
func EnumOneOf ¶
EnumOneOf extracts a string argument that must be one of allowed. An empty allowed set, or an empty string member, is a programming error: EnumOneOf panics so the "" member that produced merge_pr's "must be one of , merge, squash" message can never be reintroduced. A missing key returns ("", nil) when not required so callers can apply a default; pass Required-style presence checking separately if needed.
func Hash ¶
Hash extracts and validates a commit-hash argument. The value must be present, non-empty, at least minLen characters, and composed solely of hex digits. minLen defaults to 7 when <= 0 (the conventional short-hash floor). Rejecting "a" and "NOT_HEX" client-side stops them reaching the Cloud API as a generic 404.
func Int ¶
func Int(args map[string]any, field string, opts ...IntOption) (value int, present bool, err *Error)
Int extracts an integer argument from a raw argument map.
It distinguishes three failure modes that the old req.GetInt collapsed:
- missing key → present=false; *Error{Code: arg.missing} only when Required().
- present non-number → *Error{Code: arg.invalid_type, got: "<type>"}.
- out of [Min,Max] → *Error{Code: arg.out_of_range}.
An explicit 0 (or any in-range value) is reported present=true, fixing the Go zero-value "falsely missing" bug. JSON numbers arrive as float64; a non-integral float64 (e.g. 1.5) is rejected as invalid_type.
func MutuallyRequired ¶
MutuallyRequired enforces that two arguments are supplied together: if either field or dependency is present (non-empty / non-nil), the other must be too. This makes add_pr_comment's inline-anchor check symmetric — inline_line without inline_path is now caught, not just the reverse.
func OneOfRequired ¶
OneOfRequired enforces that at least one of fields is present. Used by update_pr so a call with neither title nor body is rejected client-side ("nothing to update") instead of hitting the API.
func RefName ¶
RefName extracts and validates a Git branch/ref name. It rejects names that Git refuses by spec (git check-ref-format rules, the subset that matters for branch creation):
- empty, or "/" / leading / trailing / doubled slash
- "." at the start of any path component, or a component ending ".lock"
- the sequences "..", "@{", a lone "@"
- ASCII control chars and the set space ~ ^ : ? * [ \
This stops "/" and "feature/" reaching the API as a generic 404.
Source Files