Add indexed positional parameters support (picocli-style)

[stalep]

Summary

Aesh currently supports one @Argument and one @Arguments field, but lacks a generalized positional-parameter model like picocli's positional parameters. This makes multi-positional command definitions and completion routing less flexible than needed.

This issue proposes adding indexed positional parameter support while preserving backward compatibility.

Motivation

Picocli-style positional parameters (single index and ranges) would allow aesh commands to model multiple positional values explicitly and deterministically.

Examples of desired capability:

• one positional at index 0 (script)
• one positional at index 1 (mode)
• remaining positionals at 2..* (passthrough args)

Proposed API (MVP)

Extend annotations with index metadata:

• @Argument
  • String index() default "0";
• @Arguments
  • String index() default "1..*";

Supported syntax (MVP):

• single index: "0", "1", ...
• bounded range: "1..3"
• open range: "2..*"

Behavioral Rules

• Positional definitions must not overlap.
• At most one open-ended range (..*).
• Existing features continue to work per positional: converter, completer, validator, arity, required, paramLabel.
• Legacy commands with no explicit index keep current behavior:
  • @Argument => index 0
  • @Arguments => index 1..*

Implementation Plan

1. Add index attribute to @Argument and @Arguments.
2. Add internal index/range parser + validation utility.
3. Extend processed metadata to store positional index/range info.
4. Update reflection path (AeshCommandContainerBuilder) to populate/validate positional definitions.
5. Update parsing logic (AeshCommandLineParser) to route positional tokens by index/range.
6. Update completion routing (AeshCommandLineCompletionParser) to complete the active positional by cursor position.
7. Update help/synopsis rendering to list positionals in index order.
8. Update annotation processor (aesh-processor CodeGenerator) for parity.
9. Add parser/completion/help/processor tests.
10. Document in docs site (arguments.md) with migration examples.

Acceptance Criteria

• Commands with multiple indexed positionals parse correctly.
• Correct positional completer is invoked based on active token index.
• Help/synopsis reflects positional order.
• Reflection and generated metadata paths stay equivalent.
• Existing commands without explicit index continue to work unchanged.

Related

• Picocli positional parameters reference: https://picocli.info/#_positional_parameters
• This also generalizes/future-proofs completion behavior around positional routing.