Enumerate necessary capabilities for advanced APIs

[littledan]

In this issue, let's verify that our CLI API has sufficient capabilities for advanced argument parsing and tab completion. I'm not sure what's required here, but I hope my coworker @molisani can help lay out requirements, as he has significant experience in advanced Node CLIs.

Note

The initial CLI API should not provide a high-level argument parser or tab completion engine--we should focus on low-level capabilities first, and build more high-level abstractions once we have the basis (so that we're not tempted to put low-level hooks in the higher-level APIs, given that their use is optional).

[CanadaHonk]

Is it worth considering that WinterCG or another party could provide a standard userland library (written in JS) using the initial CLI API for argument parsing (and others each separately) instead of a potential "V2" in future? I see various pros (not dependent on runtime implementing, less runtime effort, more interoperability) / cons (performance? not sure) so probably should be brought up.

[sheplu]

What is considered part of "advanced apis" ?

I think it would make sense to include some functionalities to simplify how we handle most common operation in a CLI. Or even if this is not included as a default in the runtime (for size / not bloat the runtime with that) we should also define some core concepts -that are always used - like

• task list
• color / styling ( i saw an issue about color/no_color)
• retry on interactive phases
• clearing a terminal
• reading / loading config (to simplify between local config, system config and other ways - which also open the issue of config)

@CanadaHonk Depending what you prefer, do you want to keep the previous point in this issue, or should we split that in multiple issue as the discussion may not be the same depending on the expectation? (I more that happy to open / handle the issues)

[molisani]

At the risk of sounding dogmatic, I'd like to recommend the Command Line Interface Guidelines for a good definition/specification of the features and behaviors that this advanced API would seek to support. I don't think that it should be exhaustively implemented, but a sufficiently advanced API should implement argument/flag parsing in such a way that requires minimal overhead for a developer building an application.

Consider util.parseArgs in Node. It was added relatively recently but has a purposefully minimal scope, choosing only to target simple use cases. It requires the executable info to be stripped prior to parsing, only supports string/boolean argument types, and passes-through all of the positional arguments. It also provides a tokenizer and this is what I see as the true core of the API. Not that it should be directly exposed to end users, but it is the logic that shouldn't need to be re-implemented in user space.

I would agree that some of the other features listed here or in other discussions (color, interactivity, config) are important to CLIs, but I don't think they fall under the exclusive domain of a CLI API. Colors (even NO_COLOR support) are generally solved by third-party libraries. Likewise for interactivity.

However I do think that there's a gap for local configuration management in server runtimes. I've wondered why these runtimes haven't implemented something like the web's localStorage, which would be great for application-level configuration (or at least something with a similar interface). I'm not sure this fits under the scope of a CLI API, but something to consider.