You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 wiringcmd.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.
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).