Support -- remaining args syntax

[nielsenko]

It is not clear to me how to allow, and extract remaining arguments from BetterCommand.

Ie. support:

dart run command -a -- --some --remaining --args.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• [BetterCommand] lacks support for allowTrailingOptions #89

👤 Suggested Assignees

• indraneel12

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Enable developers to access remaining arguments (those after the -- separator) from BetterCommand implementations by exposing a convenient API and documenting the usage pattern. The implementation adds a restArguments property to BetterCommand, provides comprehensive documentation and examples, and ensures proper test coverage.

Observations

The cli_tools package provides BetterCommand and BetterCommandRunner as enhanced CLI building blocks that extend the args package's Command class. BetterCommand uses the config package to provide typed argument parsing through Configuration objects. The framework follows a pattern where command subclasses override runWithConfig() to access parsed arguments. Rest arguments (unparsed arguments after --) are already supported by the underlying ArgParser and accessible through the inherited argResults.rest property, but this is not documented or exposed through BetterCommand's API.

Assumptions

Assumption 1: API Design for Rest Arguments Access

Options Considered:

• Add a restArguments property to BetterCommand
• Pass rest arguments as a parameter to runWithConfig()
• Create a separate RestArgumentsProvider class

Chosen Option: Add a restArguments property to BetterCommand

Rationale: Maintains consistency with the existing BetterCommand API pattern where command implementations access data through properties rather than parameters. The getter approach is discoverable, clean, and follows the same pattern as accessing argResults.

Assumption 2: Separation from Configuration System

Options Considered:

• Keep rest arguments separate from typed Configuration
• Integrate rest arguments into the Configuration object

Chosen Option: Keep rest arguments separate from typed Configuration

Rationale: Rest arguments are fundamentally different from typed options - they are unparsed remainders intentionally left for downstream tools. Mixing them with the typed Configuration system would blur the distinction between parsed options and unparsed arguments.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Expose Rest Arguments API

Add a clean, discoverable way for BetterCommand subclasses to access rest arguments while maintaining the separation between typed Configuration (for options) and rest arguments (for unparsed remainders).

Task 1: Add restArguments Property to BetterCommand

Add a public getter property that exposes rest arguments in a null-safe, convenient way.

• Add restArguments getter to BetterCommand class in packages/cli_tools/lib/src/better_command_runner/better_command.dart that returns argResults?.rest ?? const <String>[]
• Add comprehensive doc comments explaining what rest arguments are, when they're populated (after -- separator), and common use cases
• Include a doc comment example showing: dart run command -a value -- --some --remaining --args and how restArguments would contain ['--some', '--remaining', '--args']

Task 2: Document Rest Arguments Feature

Update package documentation to explain rest arguments and their usage.

• Add a "Rest Arguments" section to packages/cli_tools/README.md explaining the -- separator syntax and the restArguments property
• Include examples showing commands that pass additional arguments to external tools or scripts
• Document that rest arguments are separate from the typed Configuration system by design

🤖 Prompt for AI agents

Expose rest arguments API in BetterCommand by adding a restArguments property.

Add a public `restArguments` getter to the BetterCommand class that returns
`argResults?.rest ?? const <String>[]`.

Add doc comments explaining:
- What rest arguments are and when they're populated (after `--` separator)
- Common use cases
- Example: `dart run command -a value -- --some --remaining --args` produces
`restArguments` containing `['--some', '--remaining', '--args']`

Update README.md with a "Rest Arguments" section:
- Explain the `--` separator syntax and `restArguments` property
- Include examples of passing arguments to external tools
- Document that rest arguments are separate from the typed Configuration system

Phase 2: Demonstrate Usage with Examples

Provide concrete examples showing developers how to use rest arguments in practice.

Task 1: Create Rest Arguments Example

Add a new example file demonstrating the rest arguments feature.

• Create new example file in packages/cli_tools/example/ directory showing a command that accepts options before -- and passes rest arguments to an external tool
• Example should show accessing both commandConfig.value() for typed options and restArguments for remaining args
• Include example invocations in file comments showing different usage patterns

Task 2: Add to Existing Examples

Enhance existing examples to reference the rest arguments capability where appropriate.

• Update packages/cli_tools/example/main.dart to include a comment or doc string mentioning that rest arguments can be accessed via restArguments property
• Ensure examples directory demonstrates the pattern of using Configuration for typed options and restArguments for unparsed remainders

🤖 Prompt for AI agents

Create examples demonstrating rest arguments usage.

Create a new example file in `packages/cli_tools/example/` showing:
- A command that accepts options before `--` and passes rest arguments to an
external tool
- Accessing both `commandConfig.value()` for typed options and `restArguments`
for remaining args
- Example invocations in comments with different usage patterns

Update `packages/cli_tools/example/main.dart`:
- Add comment/doc string mentioning the `restArguments` property
- Demonstrate the pattern of using Configuration for typed options and
restArguments for unparsed remainders

Phase 3: Add Test Coverage

Ensure the rest arguments feature is properly tested.

Task 1: Add Unit Tests for restArguments Property

Create tests validating the restArguments getter behavior.

• Add tests to packages/cli_tools/test/better_command_runner/better_command_test.dart or create a dedicated test file for rest arguments
• Test cases should cover: command with rest arguments present, command with no rest arguments (empty list), command with options before -- and rest args after
• Verify that restArguments returns immutable empty list when argResults is null or rest is empty
• Test integration with command execution to ensure rest arguments are available during runWithConfig()

Task 2: Add Integration Tests

Create end-to-end tests showing rest arguments working with BetterCommandRunner.

• Add tests in packages/cli_tools/test/better_command_runner/ that run complete commands with various rest argument patterns
• Test scenarios: passing flags to external commands, mixing options and rest args, empty rest args
• Verify rest arguments are correctly separated from parsed options and accessible through the property

🤖 Prompt for AI agents

Add comprehensive test coverage for rest arguments feature.

Add unit tests for `restArguments` property:
- Test command with rest arguments present
- Test command with no rest arguments (returns empty list)
- Test command with options before `--` and rest args after
- Verify `restArguments` returns immutable empty list when argResults is null or
rest is empty
- Test that rest arguments are available during `runWithConfig()`

Add integration tests:
- Run complete commands with various rest argument patterns
- Test scenarios: passing flags to external commands, mixing options and rest
args, empty rest args
- Verify rest arguments are correctly separated from parsed options and
accessible through the property

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Expose rest arguments API in BetterCommand by adding a restArguments property.

Add a public `restArguments` getter to the BetterCommand class that returns
`argResults?.rest ?? const <String>[]`.

Add doc comments explaining:
- What rest arguments are and when they're populated (after `--` separator)
- Common use cases
- Example: `dart run command -a value -- --some --remaining --args` produces
`restArguments` containing `['--some', '--remaining', '--args']`

Update README.md with a "Rest Arguments" section:
- Explain the `--` separator syntax and `restArguments` property
- Include examples of passing arguments to external tools
- Document that rest arguments are separate from the typed Configuration system
===============================================================================

Task: 2

Create examples demonstrating rest arguments usage.

Create a new example file in `packages/cli_tools/example/` showing:
- A command that accepts options before `--` and passes rest arguments to an
external tool
- Accessing both `commandConfig.value()` for typed options and `restArguments`
for remaining args
- Example invocations in comments with different usage patterns

Update `packages/cli_tools/example/main.dart`:
- Add comment/doc string mentioning the `restArguments` property
- Demonstrate the pattern of using Configuration for typed options and
restArguments for unparsed remainders
===============================================================================

Task: 3

Add comprehensive test coverage for rest arguments feature.

Add unit tests for `restArguments` property:
- Test command with rest arguments present
- Test command with no rest arguments (returns empty list)
- Test command with options before `--` and rest args after
- Verify `restArguments` returns immutable empty list when argResults is null or
rest is empty
- Test that rest arguments are available during `runWithConfig()`

Add integration tests:
- Run complete commands with various rest argument patterns
- Test scenarios: passing flags to external commands, mixing options and rest
args, empty rest args
- Verify rest arguments are correctly separated from parsed options and
accessible through the property

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!