Skip to content

Restore argument parsing behaviour for commands in Ahoy to fix #182 - #185

Merged
ocean merged 4 commits into
ahoy-cli:masterfrom
ocean:fix/issue-182-arg-passthrough
Sep 2, 2026
Merged

ocean merged 4 commits into
ahoy-cli:masterfrom
ocean:fix/issue-182-arg-passthrough

Conversation

@ocean

@ocean ocean commented Sep 1, 2026 •

Copy link
Copy Markdown
Member

Summary

Fixes the v3.0.0 regression reported in #182, where flags passed to a command defined in .ahoy.yml were silently discarded along with the token following each one.

Thanks for the detailed report @jurgenhaas, including the root cause.

$ ahoy echoargs AAA --log-junit x.xml --configuration y.dist BBB
AAA BBB # v3.0.0
AAA --log-junit x.xml --configuration y.dist BBB # v2.5.0, and this PR

Root cause

This comment in getCommands() was mistaken:

// Don't use DisableFlagParsing - it prevents persistent flags from being parsed.
// Instead, we use FParseErrWhitelist to allow unknown flags to pass through.

FParseErrWhitelist.UnknownFlags only suppresses the error. pflag still drops the flag token, and stripUnknownFlagValue drops the following token and nothing else is passed through.

There is a second half to this that the issue didn't cover. Ahoy's own flags were being claimed after the command name too, that was a deliberate change in v3 but was a poor decision. v2 gave every token after the command name to the command, and this PR restores that.

The fix

The pre-parser in flag.go already stops at the first non-flag token, so it already knows where a command's arguments begin. Three changes make that boundary authoritative:

  1. flag.go - record everything from the command name onwards as commandArgs, sliced from the original arguments so the tail keeps the dashes the user typed.
    2.main() - rootCmd.SetArgs(state.commandArgs), so cobra never sees a flag intended for a wrapped command.
  2. getCommands() - DisableFlagParsing on commands that run something. Commands that only group imports keep normal parsing, so subcommand routing and help still work.

Ahoy's flags are now recognised in exactly one place: before the command name, by the pre-parser that already handled them.

Behaviour changes

Two consequences follow from the contract. Both are what v2 did, but both should be noted here:

  • ahoy <command> --help now reaches the command. ahoy help <command> gives Ahoy's own help from your .ahoy.yml file.
  • -v / --verbose after a command name belong to the command. Before the command name they are Ahoy's, as always.

Anyone relying on v3.0.0's flags-anywhere behaviour will need to move those flags ahead of the command name. Given v3.0.0 is only 10 days old and the behaviour it replaced silently corrupted wrapped commands, that seems ok.

Testing

New tests/argument-passthrough.bats covers all five rows from the issue plus imported subcommands, the -- separator, both flag positions, and every spelling of a global flag (-f, -file, --file, and their = forms).

Docs

I'll update the ahoy-docs repo now too, I've changed the wrapper-commands guide to show the wrapped tool keeping its own flags, and the CLI reference gains a table of where each token goes.

Closes #182

Summary by CodeRabbit

  • New Features

    • Added ahoy help <command> for displaying command-specific help.
    • Added support for passing command arguments through unchanged, including flags, quoted values and positional arguments.
  • Bug Fixes

    • Prevented command-specific flags from being incorrectly interpreted as Ahoy options.
    • Ensured global options are recognised only before the command name.
    • Preserved argument order and formatting for wrapped and imported commands.

v3.0.0 let cobra parse a command's arguments before running it. The comment
in getCommands claimed FParseErrWhitelist would pass unknown flags through,
but it only suppresses the error: pflag drops the flag token and, via
stripUnknownFlagValue, the token after it too. So `ahoy fix-perms chown -R
www-data:www-data .` reached the container as `chown .` - a silent change
of meaning in a tool whose whole job is wrapping other CLIs.

Ahoy's own flags were claimed there as well, by design, which is the same
defect wearing a friendlier hat: `ahoy phpunit -v` ate the -v.

This restores the v2 contract. Ahoy's flags are recognised only before the
command name, where the pre-parser in flag.go already reads them; the
pre-parser now also records everything from the command name onwards, and
main() hands cobra only that, so cobra never sees a flag meant for a
wrapped command. Commands that run something get DisableFlagParsing;
commands that only group imports keep normal parsing so routing still works.

Two consequences follow from the contract, both of them v2 behaviour:

- `ahoy <command> --help` now reaches the command. `ahoy help <command>`
  reaches ahoy's own help, which the CLI reference already documented but
  which never worked - setupApp had replaced cobra's help command with a
  nameless hidden stub. It is now a real command.
- `-v` and `--verbose` after a command name are the command's.

The three verbose-flag tests that pinned the old contract are inverted
rather than deleted, since the behaviour they describe is the bug, and
tests/argument-passthrough.bats covers every case from the issue plus
imports and the '--' separator. Verified 8 of its 10 tests fail against
upstream master.

Closes ahoy-cli#182

Claude-Session: https://claude.ai/code/session_01629NFuQxTr678Tdh8AD39d
The pre-parser's arg slicing decides where a command's own arguments start,
so each spelling of a global flag has to be counted correctly. The '=' forms
had no coverage at all; a miscount there would leak the config path into the
command's arguments, or drop an argument, without failing anything.

Claude-Session: https://claude.ai/code/session_01629NFuQxTr678Tdh8AD39d
Documented in the CLI reference (`ahoy node --version` must report Node's
version, not ahoy's) but nothing tested it. Covers both positions.

Claude-Session: https://claude.ai/code/session_01629NFuQxTr678Tdh8AD39d
@coderabbitai

coderabbitai Bot commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 7753c4fa-2e74-4bfd-aecf-7878471c09d4

📥 Commits

Reviewing files that changed from the base of the PR and between 0ceb767 and 57ee7dc.

📒 Files selected for processing (5)
  • ahoy.go
  • flag.go
  • tests/argument-passthrough.bats
  • tests/descriptions.bats
  • tests/verbose-flag.bats

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.


Walkthrough

Ahoy now parses its own flags only before the command name. It preserves and forwards all later arguments verbatim. The help [command] command replaces command-specific --help handling.

Changes

Command argument forwarding and help

Layer / File(s) Summary
Capture and forward command arguments
ahoy.go, flag.go, tests/argument-passthrough.bats, tests/verbose-flag.bats
The pre-parser stores original arguments after the command name. Generated commands disable Cobra flag parsing and forward these arguments unchanged. Tests cover flag forms, positionals, separators, imported commands, and verbose flags.
Implement explicit command help
ahoy.go, tests/descriptions.bats
The application adds help [command], preserves the parsed simulation version, updates the help hint, and tests the new command-help behaviour.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 57ee7

This PR restores command-argument passthrough and adds focused coverage for the affected flag and subcommand behaviors; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Shell
  participant AhoyPreParser
  participant Cobra
  participant WrappedCommand
  Shell->>AhoyPreParser: provide command and arguments
  AhoyPreParser->>Cobra: set post-command arguments
  Cobra->>WrappedCommand: forward arguments verbatim
  WrappedCommand-->>Shell: return command output
Loading
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 5 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly describes the main change: restoring command argument parsing behaviour to fix issue #182.
Linked Issues check ✅ Passed The changes address issue #182 by preserving all arguments after the command name, disabling Cobra flag parsing for executable commands, retaining Ahoy flag parsing before the command, and adding regr…
Out of Scope Changes check ✅ Passed The code and test changes are directly related to restoring argument pass-through behaviour and validating the linked issue requirements. No unrelated changes are evident.
Full details: Linked Issues check

Explanation

The changes address issue #182 by preserving all arguments after the command name, disabling Cobra flag parsing for executable commands, retaining Ahoy flag parsing before the command, and adding regression tests.

  • Fix all pre-merge checks with AI
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@ocean
ocean merged commit 968aefa into ahoy-cli:master Sep 2, 2026
13 checks passed
@ocean
ocean deleted the fix/issue-182-arg-passthrough branch September 2, 2026 05:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

v3.0.0 regression: unknown flags and their values are stripped from .ahoy.yml commands

1 participant

⌂ 换网址