Add automatic --wizard command that generates menus and prompts

[jdegoes]

The structure of Command permits an interactive mode that generates menus and prompts, e.g.:

Please enter the command you would like to execute:

1. commit — Commits the changes
2. version — Prints out the version
...


Please enter the boolean flags you would like to use:

[ ] (f) Force — Forces the deletion
[ ] (r) Remove — Removes the files

Please enter any combination of r, f: 

This ticket is to prototype such a wizard mode, which will walk the user through providing arguments and options using interactive menu prompts.

[ioreskovic]

Heya, I'd like to give this a go!

[jdegoes]

@ioreskovic This one will be great fun!

There are a few steps:

1. Adding a new Options for a --wizard mode.
2. Ensuring CLIApp will run the wizard when --wizard is specified.
3. The Wizard implementation will be different for each type of Command. But for those commands that have options / arguments, they will match on the Options / Args, and prompt the user for them.
4. Eventually when all information has been collected, then the wizard can generate the command-line arguments as List[String].
5. Finally, the wizard can invoke CLIApp#run on the generated command-line arguments. Also, it would be helpful to print out these command-line arguments to the user, so they don't have to use the wizard again if they don't want. Something like:

   You may bypass the wizard and execute your command directly with the following options and arguments:
     --verbose 3 foo.txt --port 2334
   

You might find a person or two to pair with on the Discord (if you like). In any case, please reach out if you run into any issues or have any questions!

[ioreskovic]

@jdegoes
I don't think I'll be able to get this done in time for Hackaton, I found it to be much trickier than I initially assessed. 😞
Nevertheless, I'd like to continue working on it in my spare time. Is that OK?

I managed to get it to work*, but with shortcuts, and the code is ugly, and I would like to have some time to do it properly.

[jdegoes]

@ioreskovic Yes, it's fine to work on after the hackathon. Let me know if you need any help and be sure to fill out the form to claim your t-shirt!

[ioreskovic]

@jdegoes I was finally able to pick this up, and I have some questions/issues about how CliApp#run is structured, mainly when it comes to subcommands.

Let's take a subset of git

git
git stash
git stash push
git stash clear
git push

Then, using recursive encoding, it looks like this:

Subcommand(            <- 
  Single(git),         <- Opts(version: Boolean), Args()
  Fallback(            <- 
    Subcommand(        <- 
      Single(stash),   <- Opts(), Args()
      Fallback(        <- 
        Single(push),  <- Opts(force: Boolean), Args(files: List[Path])
        Single(clear)  <- Opts(), Args()
      )                <- 
    ),                 <- 
    Single(push)       <- Opts(repo: Option[String]), Args(files: List[Path])
  )                    <- 
)                      <- 

Now, let's take a look at type A in Command[+A] for the following structure.

  final case class GitModel(version: Boolean)
  case object GitStashModel
  final case class GitStashPushModel(force: Boolean)
  case object GitStashClearModel
  final case class GitPushModel(repo: Option[String])

  val git: Command[((GitModel, Unit), (Product, Serializable))] =
    Command("git", Options.bool("version", true).as(GitModel), Args.Empty).subcommands(
      Command("stash", Options.Empty.map(_ => GitStashModel), Args.Empty)
        .subcommands(
          Command("push", Options.bool("force", ifPresent = true).as(GitStashPushModel), Args.file("files", Exists.Yes).repeat1),
          Command("clear", Options.Empty.map(_ => GitStashClearModel), Args.Empty)
        ),
      Command("push", Options.text("repo").optional("Use different repository").as(GitPushModel), Args.file("files", Exists.Yes).repeat1)
    )

As we can see here, inferred type is Command[((GitModel, Unit), (Product, Serializable))], which is not that helpful, especially when you need to "extract" a certain subcommand to execute. Extracting the command from the tree to run it, to my understanding, is required because of the structure of run effect:

  def run(args: List[String]): ZIO[R with Console, Nothing, ExitCode] =
    (for {
      builtInValidationResult  <- command.parseBuiltIn(args, config)
      (remainingArgs, builtIn) = builtInValidationResult
      _                        <- handleBuiltIn(args, builtIn)
      validationResult         <- command.parse(remainingArgs, config)
    } yield validationResult)
      .foldM(printDocs, success => execute(success._2))
      .exitCode

Since wizard is a built-in, it should be handled by handleBuiltIn and instead of Unit in ZIO[Console, Nothing, Unit] return something more descriptive.

My initial idea was to either return List[String], where it would represent wizard-generated args & opts, and for other cases in handleBuiltIn, empty list. However, then command#parse would have to take those generated opts, args (and subcommands, since you want to run git stash push --force build.sbt, for example), traverse the recursive structure, and return a top-level model in order to be able to execute it.

But, since that model differs (nested commands may have different models than the top one) from the one execute operates, I cannot execute it.

Another possible approach would be to have wizard also execute the command, and then short-circuit the rest of the code in run, effectively making it not that much transparent, when you look at the code, and possibly "abusing" the types to signal that wizard has already executed it "internally", and that the rest of the code should simply not do anything. I have fiddled a bit with it, so I still do not have concrete examples of what might go wrong/ugly.

I don't have much experience with recursion schemes, but this smells a bit like it to me, since we have a recursive data structure, which we want to be able to traverse independently of performing specific operations on it's data.

However, as I mentioned earlier, the types are giving me a problem, since they do not need to be a part of ADT (or an HList).
Ideally, I would like to achieve the following user-experience akin to this:

sealed trait GitCommand
final case class Git(...) extends GitCommand
case object GitStash extends GitCommand
final case class GitStashPush(...) extends GitCommand
...

val command: Command[ArgsAndOptsADT] = ...

val result = command.execute {
  case Git(version: Boolean) => ...
  case GitStash => ...
  case GitStashPush(force: Boolean, files: List[Path]) => ...
  ...
}

but I am not sure how to do it.

Any thoughts?

[jdegoes]

I think you should not care about the types at all, and simply generate a List[String] which will be parsed and processed via the ordinary mechanisms for doing so.

Note that in a real application, when you use .subcommands, you would feed it commands that generate a sum type (sealed trait), rather than different, unrelated case classes.

[jdegoes]

We could do a pair programming session for 30 minutes, would that help?

[ioreskovic]

I would love to, but my timetable is packed until Wednesday.
I'll try to fiddle with it until Wednesday, and then reach you on Discord if I still have issues? Is that OK?

[jdegoes]

Yes, sounds good!

[jdegoes]

/bounty $500

Solution must create very user-friendly menus, and must, after execution, print out the command-line args necessary to re-create that execution.

[algora-pbc]

💎 $500 bounty created by jdegoes
🙋 If you start working on this, comment /attempt #24 to notify everyone
👉 To claim this bounty, submit a pull request that includes the text /claim #24 somewhere in its body
📝 Before proceeding, please make sure you can receive payouts in your country
💵 Payment arrives in your account 2-5 days after the bounty is rewarded
💯 You keep 100% of the bounty award
🙏 Thank you for contributing to zio/zio-cli!

Attempt	Started (GMT+0)	Solution
🔴 @pablf	Jun 27, 2023, 8:08:45 PM	#218

[jdegoes]

@jorge-vasquez-2301 If you are interested in finishing this ticket (with the menus, prompts and other deluxe features), feel free to /attempt #24

[jorge-vasquez-2301]

/attempt #24

[pablf]

/attempt #24

[algora-pbc]

@pablf: Reminder that in 7 days the bounty will become up for grabs, so please submit a pull request before then 🙏

[algora-pbc]

💡 @pablf submitted a pull request that claims the bounty. You can visit your org dashboard to reward.

[algora-pbc]

🎉🎈 @pablf has been awarded $500! 🎈🎊