Error context is missing current command information

[zanieb]

Hi!

I'm not sure if I'm holding it wrong, or what — so I'm starting here.

Over in astral-sh/uv#8313 you can see we have a bad recommendation:

$ uv python remove cpython-3.13.0-macos-aarch64-none
error: unrecognized subcommand 'remove'
tip: a similar subcommand exists: 'uv pip uninstall'

We should recommend uv python uninstall.

This is our fault; it's from some error handling we added a while back, I think intending to suggest uv pip uninstall for uv remove. However, now we have a bunch of other command namespaces. I took a look at trying to fix this in astral-sh/uv#8316 but I don't see a way to retrieve the Command at which the InvalidSubcommand error occurred. For quick reference, it looks like the context attached to the error is:

    context: FlatMap {
        keys: [
            InvalidSubcommand,
            Usage,
        ],
        values: [
            String(
                "remove",
            ),
            StyledStr(
                StyledStr(
                    "\u{1b}[1m\u{1b}[32mUsage:\u{1b}[0m \u{1b}[1m\u{1b}[36muv python\u{1b}[0m \u{1b}[36m[OPTIONS]\u{1b}[0m \u{1b}[36m<COMMAND>\u{1b}[0m",
                ),
            ),
        ],
    },

You can tell Clap has context on the current command from the Usage, but that's not really usable for logic. If I had access to the command, I could improve the suggestion.

If there's not some way to do this, I think this will require a change to clap. The idea is probably to do something like 9696146 (we can either store the Command or just the Command.name) in the context (as PriorCommand or Command) which would allow errors to be customized based on where in the CLI the failure occurred.

[zanieb]

@epage should I open an issue for this? or a pull request? is there more information I can provide to make this easier to triage?

[epage]

I recently went on a business trip and am still going through my backlog as well as the tasks I couldn't do (like the next Cargo blog post). I'll be getting back to you on this.

[zanieb]

Okay no rush — just thought you may have missed it due to your previous promptness :)

As I said, let me know if there's anything I can do to make your life easier here.

[epage]

As I focus on use cases, we first need to break down

This is our fault; it's from some error handling we added a while back, I think intending to suggest uv pip uninstall for uv remove.

So I take it what you are doing is that you check for the remove subcommand and if that was unrecognized, then you change the suggested command to pip uninstall

Cargo had a similar need for arguments and we created UnknownArgumentValueParser. As we don't have hooks for subcommands (yet?), there isn't a good place to cause something similar to happen.

However, not everything needs to live in clap. What you could do is mark uv remove as a hidden command and create a custom error when you try to execute it to suggest uv pip uninstall. I think this would be my recommendation for solving the problem.

You can tell Clap has context on the current command from the Usage, but that's not really usable for logic. If I had access to the command, I could improve the suggestion.

Overall, the context is mostly centered on rendering, rather than programmatic use. For us to do so, we'd need to provide at least every piece of context in terms of full command name path and the argument or group ID. That is a major shift and I'm not entirely sure I want clap errors to be taking on the responsibility to track all of that, especially if there are other reasonable ways of resolving the use cases.

[zanieb]

This is thinking of the problem in isolation, ie "what do I need", which is a small piece of information. If you consider the problem holistically of "clap errors should provide their information in a way to programmatically interpret" then I hope that clarifies what the major shift is.

I think I was focused on your statement "we'd need to provide at least every piece of context in terms of full command name path and the argument or group ID". If the idea is that these structured errors are not intended to be interpreted programmatically, then I agree we're just using it wrong and it's not a trivial change.

Thanks for all the additional details, I appreciate you pointing out #4853 — that'd be a deal breaker for our use-case too. Unfortunately, I feel I'm at a bit of an impass here. My options look like:

• Maintain a patch that adds this suggested extension (bad for distributors of uv and the ecosystem)
• Drop these suggestions entirely (bad for our users)
• Use hidden commands (can result in confusing suggestions for our users, which seems contrary to the goal)
• Wait for something to change here

It's reassuring that a new completion system is underway, but it's not clear it'll address our use case and #4853 doesn't seem to be moving towards consensus. It seems possible there's a need for another dedicated variant for commands and options that are deprecated (or, more generally, that should error and suggest an alternative). It's a common part of the tool lifecycle, and thus seems worth crafting a good experience around. It seems like hide tries to address the use-case, but is limited by being more general too? Is there context somewhere on the original intent of hide?

[epage]

It's reassuring that a new completion system is underway, but it's not clear it'll address our use case

How so?

#4853 doesn't seem to be moving towards consensus.

Mostly it needs someone to help drive it to understanding.

It's a common part of the tool lifecycle, and thus seems worth crafting a good experience around.

#3321 was opened to discuss this.

Is there context somewhere on the original intent of hide?

Not that I have and the question is not just the intent but how people use it.

[zanieb]

I was referring to your note:

This might not work in your case because most shells don't seem to allow us to complete multiple arguments at once which would be needed for python remove

And that a new completion system just addresses one of the caveats of the hide strategy, it doesn't solve the more general problem of guiding users to the correct command. There's the idea of using the shell completions to help, i.e.:

I've also considered the idea of allowing cases like UnknownArgumentValueParser. to be complete with the alternative suggestion.

But it's not clear to me if most users install shell completions or whether there will similar solution for subcommands. It seems like regardless we'll need to do more.

I'll read up on the linked issues.

[epage]

I was referring to your note:

This might not work in your case because most shells don't seem to allow us to complete multiple arguments at once which would be needed for python remove

That was only referring to be extra fancy where if someone does uv remo<TAB> that they'd instead get uv pip uninstall instead of uv remove. It would still be hidden when completing uv <TAB>, it would have the description you give it which could be about it not being supported, etc.

[zanieb]

Thanks again for your thoughtful replies. I'll explore alternative patterns and engage on some of those designs if I have time.