PR #191 wired an enum-annotation hook into vers agent-context but did not apply it to any existing commands. This issue tracks the sweep.
Background
cmd/agent_context.go walks every flag and looks for an annotation on the parent command of the form vers:enum:<flag-name> with comma-separated valid values. When present, the flag's schema entry includes an enum: [...] array.
// Example wiring
cmd.Annotations["vers:enum:visibility"] = "public,private,unlisted"
This unlocks two agent-native wins:
agent-context consumers learn the constraint without parsing --help text or reading server responses.
errorsx can produce self-enumerating errors per principle 3 ("errors that teach"): error: --visibility must be one of: public, private, unlisted (got: "secret").
Candidates to annotate
A non-exhaustive sweep of bounded-input flags:
| Command |
Flag |
Probable enum |
repo visibility |
positional <visibility> |
public, private |
commit publish / unpublish |
(state shape) |
n/a |
Any future --deliver flag (F17) |
--deliver scheme |
stdout, file:, webhook: |
| Logging flags |
--log-level if added |
debug, info, warn, error |
Scope
- Audit every
--<flag> in cmd/ that takes a string with a closed set of valid values.
- Add
cmd.Annotations["vers:enum:<flag>"] = "..." for each.
- Wire
errorsx.EnumError(flagName, got, valid) (new helper) and use it on validation paths.
- Update the relevant flag's
Long/Usage to mention the enum.
- Verify in
agent-context output: jq '.commands.<name>.flags."--<flag>".enum' returns the array.
Out of scope
PR #191 wired an enum-annotation hook into
vers agent-contextbut did not apply it to any existing commands. This issue tracks the sweep.Background
cmd/agent_context.gowalks every flag and looks for an annotation on the parent command of the formvers:enum:<flag-name>with comma-separated valid values. When present, the flag's schema entry includes anenum: [...]array.This unlocks two agent-native wins:
agent-contextconsumers learn the constraint without parsing--helptext or reading server responses.errorsxcan produce self-enumerating errors per principle 3 ("errors that teach"):error: --visibility must be one of: public, private, unlisted (got: "secret").Candidates to annotate
A non-exhaustive sweep of bounded-input flags:
repo visibility<visibility>public, privatecommit publish/unpublish--deliverflag (F17)--deliverschemestdout, file:, webhook:--log-levelif addeddebug, info, warn, errorScope
--<flag>incmd/that takes a string with a closed set of valid values.cmd.Annotations["vers:enum:<flag>"] = "..."for each.errorsx.EnumError(flagName, got, valid)(new helper) and use it on validation paths.Long/Usageto mention the enum.agent-contextoutput:jq '.commands.<name>.flags."--<flag>".enum'returns the array.Out of scope
--profile(separate concern).