Skip to content

F11 follow-up: annotate bounded-input flags with vers:enum:* #192

@AlephNotation

Description

@AlephNotation

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:

  1. agent-context consumers learn the constraint without parsing --help text or reading server responses.
  2. 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

  1. Audit every --<flag> in cmd/ that takes a string with a closed set of valid values.
  2. Add cmd.Annotations["vers:enum:<flag>"] = "..." for each.
  3. Wire errorsx.EnumError(flagName, got, valid) (new helper) and use it on validation paths.
  4. Update the relevant flag's Long/Usage to mention the enum.
  5. Verify in agent-context output: jq '.commands.<name>.flags."--<flag>".enum' returns the array.

Out of scope

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions