Skip to content

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

@kamilio

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
    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