Usage details and general requirements

[pedro-psb]

Hello everyone,

I've been thinking about some details of the usage that I'd like to discuss so we can start thinking of more specific solutions together.

Usage

Which one would be the primary use case for the tool? Please share anything not mentioned here, as well.

Wrap/redirect

Completely wrap a program/binary, redirecting the arguments unmodified, like:

$ up git
# call: docker run ... bash -c "git"

$ up git clone https://github.com/foo/bar.git
# call: docker run ... bash -c "git clone https://github.com/foo/bar.git"

$ up git <args>
# call: docker run ... bash -c "git $args"

Compose

Create commands that uses the original ones, writing custom help and mapping cmd+args to binary commands:

$ up mygit
# shouldn't need to call git here, just show custom help of the command

$ up mygit add-and-commit <msg>
# call: docker run ... bash -c "git add . && git commit -m $msg"

$ up mygit custom-cmd <args>
# mapped-cmd: "custom-cmd <args>" -> "binary ... && ..."
# call: docker run ... bash -c "$mapped-cmd"

Mix

Both cases are important:

$ up mygit add-and-commit <msg>
# map to custom cmd using git

$ up git <args>
# redirect to git
# OR 
$ up mygit --original <redirect to git>

Considerations

From what I understood from the proposal, the main usage is really wrapping another binary.

On the other hand, providing composed commands could be convenient to share with another team, because a given workflow usually requires a specific subset of commands from a CLI tool (that the other team may be unfamiliar with).

In this case, each pluggable tool would be:

• encapsulating the tool-provisioning through ansible/docker (essential)
• carrying on some relevant workflow commands and information from one team to another.

[fabiobarkoski]

I think the mix can be the best approach, from what I understood the CLI will not only wrap the binaries, but will provide some standard way to execute the binaries. Like:

$ cmd1 init

$ cmd2 --init

$ up cmd1 init

$ up cmd2 init

Of course, the standard way will be created by the user, and this is another point to think alongside the idea of change the up word to call the binaries.

[faermanj]

@pedro-psb you are correct, the main use case is use actual binaries, like up git clone ..., but it would be great to offer solutions in a standard way, something like up gitops erase secret ops.txt

[pedro-psb]

We could implement a core command/namespace, such as up raw {}, up run {} or up bin {} to direct access "binary commands" and allow plugin's to register other custom "solution commands" in up root namespace:

$ pip install up-git
$ pip install up-openshift


# binary-commands
$ up run --list # check currently registered binaries
git
openshift

$ up run git --version # direct access to git binary
git version 2.41.0

$ up run openshift --version # direct access to openshift binary
Version 4.12


# solution-commands
$ up --list
gitops - convenient commands for git operations
openshift - convenient commands for openshift (not the the same as 'up run openshift')

$ up gitops erase secret ops.txt # solution-command provided by plugin "up-git"
...

$ up openshift create cluster was # solution-command provided by plugin "up-openshift"
...

[pedro-psb]

I'll provide some implementation considerations about this idea.

Overview

Pluggy requires hookspec definitions which state how the plugins should implement some functionality. See here

For the "solution-commands", we could add a get_subcommand hook that returns a click/typer app. As Typer apps are composable (Clicks too), that's roughly all we need to register those as a subcommand:

Subcommand Registration Draft

up

# define hook
@pluggy.hookspec
def get_subcommand() -> typer.Typer():
    """Return a Typer app to be added as a subcommand of the `up` cli."""

# core `up` app
app = typer.Typer("up")

# load and add subcommands
collected_subcommands: list[typer.Typer] = ... # collected from found plugins
for solution_command in collected_hookimpl:
    app.add_typer(solution_command)

# implement root `up` commands
@app.command()
def run():
    ...
...

up-git

@pluggy.hookimpl
def get_subcommand() -> typer.Typer():
    """convenient commands for git operations"""
    app = typer.Typer("gitops")

    @app.command()
    def erase(file: Path):
        print(f"Erasing {file}")

    return app

[faermanj]

@fabiobarkoski We can't enforce standard, but i'm trying to keep the same $subject $action $object $profile format that many CLI tools are adopting, so commands could be up openshift create cluster aws (or less, I believe only subject would be absolutely required)