Skip to content

Improve Toolcraft help rendering for commands with a small number of options #418

Description

@kamilio

Problem

Toolcraft currently renders command options with generic value placeholders in the command list, for example:

init [--backend <value>]   Initialize a wire workspace in the current directory.

For small enum options, <value> is less useful than showing the valid values directly. The command-specific help can still provide longer descriptions, but root/group help should make compact enums self-explanatory.

Desired behavior

When an option is backed by a small enum, Toolcraft should render the enum choices inline in the command signature.

Example direction:

init [--backend sqlite|files]   Initialize a wire workspace in the current directory.

For longer enums, dynamic values, strings, numbers, or complex schemas, Toolcraft can keep the existing placeholder style such as <value> or <path>.

Suggested approach

  • In command parameter token formatting, detect enum schemas for non-global option fields.
  • If the enum has a small number of values, likely 2 or 3, render the value token as value1|value2 instead of <value>.
  • Keep optional wrapping behavior unchanged, so optional enum options render like [--backend sqlite|files].
  • Keep positional argument formatting and leaf command help behavior unchanged unless the same enum rendering naturally applies there too.
  • Preserve scope filtering, hidden commands, aliases, defaults, and global controls.
  • Fall back to the existing placeholder format for long enum lists or values that would make root help noisy.

Acceptance criteria

  • A command option defined as S.Enum(["sqlite", "files"]) renders in group help as [--backend sqlite|files].
  • Commands with long enum option lists remain compact and readable.
  • Non-enum options continue to render with the existing placeholder behavior.
  • Leaf command help output remains compatible with current behavior.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions