Align command-line interface across all projects

[jeromesimeon]

There are a number of variations in CLIs across the various projects, which could be smoothed out to facilitate understanding for users.

The existing CLIs include:

@accordproject/concerto-cli
concerto -- for Concerto code generation / download
@accordproject/markdown-transform
markus -- for CommonMark/CiceroMark/Slate transform and generation
@accordproject/ergo-cli
ergoc -- for the Ergo compiler
ergorun -- for Ergo standalone execution
@accordproject/cicero-cli
cicero -- for template parsing/generation/execution

It would help if those use the same version of yargs as well since the usage/help output varies between them.

[jeromesimeon]

A proposal for aligning all the CLIs:

1. Ergo:

ergo <cmd> [args]                                              // replaces ergorun & ergoc

Commands:
  generate      generate a markdown sample from contract data
  execute       execute a contract with a request
  invoke        invoke a clause within a contract
  init          initialize a contract
  compile       generate code for a target platform            // replaces ergoc

2. Cicero:

cicero <cmd> [args]

Commands:
  parse         parse a markdown sample using a template
  generate      generate a markdown sample from template data  // used to be generateText
  roundtrip     roundtrip a markdown sample using a template   // new
  execute       execute a template with a request
  invoke        invoke a clause within a template              // new
  init          initialize a contract template
  archive       archive a template directory
  compile       generate code for a target platform            // used to be generate
  get           save local copies of external dependencies     // new

3. Markus:

markus <cmd> [args]

Commands:
  parse         parse a markdown sample
  roundtrip     rountrip a markdown sample

4. Concerto:

concerto <cmd> [args]

Commands:
  validate      validate JSON against model files
  compile       generate code from model files                 // used to be generate
  get           save local copies of external dependencies

[jeromesimeon]

Additional alignment could happen on the options for some of the commands. For instance:

1. --out / --outputDirectory --> --output for all commands
2. --format / --target --> --target for the compile command
3. --data / --contract --> --data for the generate command
4. --template --> Should always be to load a template directory
   ...

[DianaLease]

I mentioned this on the Ergo call, but will reiterate here for those who were not able to make it:
I do not use the CLIs very often, so this may not be a real concern (I would be interested in hearing opinions from those that do currently use it often), but my one thought is that it may be confusing for people who use the generate command currently, since that command will still exist but will be doing something different than before. In this case, it may be better to come up with a new term entirely to avoid confusion.

[jeromesimeon]

I mentioned this on the Ergo call, but will reiterate here for those who were not able to make it:
I do not use the CLIs very often, so this may not be a real concern (I would be interested in hearing opinions from those that do currently use it often), but my one thought is that it may be confusing for people who use the generate command currently, since that command will still exist but will be doing something different than before. In this case, it may be better to come up with a new term entirely to avoid confusion.

Thanks for the feedback @DianaLease

The second proposal above uses draft instead of generateText or generate.

[jeromesimeon]

ergo <cmd> [args]                                              // replaces ergorun & ergoc

Commands:
  draft         create a contract text from data               // new
  execute       send a request to the contract
  invoke        invoke a clause of the contract
  initalize     initialize a contract                          // used to be init
  compile       generate code for a target platform            // replaces ergoc

1. Cicero:

cicero <cmd> [args]

Commands:
  parse         parse a contract text using a template
  draft         create contract text from data                 // used to be generateText
  redraft       parse a contract text and re-create it         // new
  execute       send a request to the contract
  invoke        invoke a clause of the contract                // new
  initialize    initialize a contract                          // used to be init
  archive       create a template archive
  compile       generate code for a target platform            // used to be generate
  get           save local copies of external dependencies     // new

1. Markus:

markus <cmd> [args]

Commands:
  parse         parse a markdown text
  draft         create markdown text from data
  redraft       parse a markdown text and re-create it

1. Concerto:

concerto <cmd> [args]

Commands:
  validate      validate JSON against model files
  compile       generate code for a target platform           // used to be generate
  get           save local copies of external dependencies

Command changes:

• generateText -> draft
• init -> initialize
• compile / generate --> compile
• Ergo gets a new draft command (like Cicero)
• Cicero gets a new invoke command (like Ergo)
• Cicero gets a new get command (like Concerto)
• CLIs with both parse and draft (Markus and Cicero) get a new command redraft for round-tripping

[mttrbrts]

As per the working group call discussion, IMO:

• redraft should become normalize
• invoke should be removed from cicero
• execute should become trigger

[jeromesimeon]

Comments from Technology WG call:

• Unsure about draft, any other suggestion?
• People really do not like redraft, suggestions would be to move it back to an option (on --parse or --draft) or to rename it, e.g., to `normalize
• Confusion about invoke what it is and whether a better name could be used.
• execute has a very different legal meaning from the one here. It could be changed. e.g., trigger

[jeromesimeon]

As per the working group call discussion, IMO:

• redraft should become normalize
• invoke should be removed from cicero
• execute should become trigger

• I like trigger!
• I don't love normalize which to me doesn't mean much to a lawyer or to a developer unless explained (and it relates neither to parse nor draft). With that said, I don't have a better idea so I'll use that. (side note: there was some push back about roundtrip on the Ergo call two weeks ago).
• if we remove invoke from cicero I feel it should be also removed from ergo. However this is a very fundamental call -- e.g., that's how init and draft are implemented. What is the rationale for removing it?

[jeromesimeon]

As per the working group call discussion, IMO:

• redraft should become normalize
• invoke should be removed from cicero
• execute should become trigger

Additional question: should the API calls be renamed accordingly:

TemplateInstance.generateText -> TemplateInstance.draft
new TemplateInstance.normalize

Engine.execute -> Engine.trigger
Engine.init -> Engine.initialize
new Engine.invoke

[jeromesimeon]

Summary of discussion with @mttrbrts on this, I will implement the following:

cicero <cmd> [args]

Commands:
  parse         parse a contract text using a template
  draft         create contract text from data                 // used to be generateText
  normalize     parse a contract text and re-create it         // new
  trigger       send a request to the contract
  invoke        invoke a clause of the contract                // new
  initialize    initialize a contract                          // used to be init
  archive       create a template archive
  compile       generate code for a target platform            // used to be generate
  get           save local copies of external dependencies     // new

And I will update the API on the template instance and engine to reflect those commands.

[jeromesimeon]

The final, implemented proposal:

1. Cicero Command Line

concerto <cmd> [args]

Commands:
  concerto validate  validate JSON against model files
  concerto compile   generate code for a target platform
  concerto get       save local copies of external model dependencies

Options:
  --version      Show version number                                   [boolean]
  --verbose, -v                                                 [default: false]
  --help         Show help                                             [boolean]

2. Markus Command Line

markus <cmd> [args]

Commands:
  markus parse      parse and transform sample markdown
  markus draft      create markdown text from data
  markus normalize  normalize markdown in a sample (parse & draft)

Options:
  --version      Show version number                                   [boolean]
  --verbose, -v                                                 [default: false]
  --help         Show help                                             [boolean]

3. Ergo Command Line

ergo <command>

Commands:
  ergo draft       create a contract text from data
  ergo trigger     send a request to the contract
  ergo invoke      invoke a clause of the contract
  ergo initialize  initialize the state for a contract
  ergo compile     compile a contract

Options:
  --help         Show help                                             [boolean]
  --version      Show version number                                   [boolean]
  --verbose, -v                                                 [default: false]

4. Cicero Command Line

cicero <cmd> [args]

Commands:
  cicero parse       parse a contract text
  cicero draft       create contract text from data
  cicero normalize   normalize markdown (parse & redraft)
  cicero trigger     send a request to the contract
  cicero invoke      invoke a clause of the contract
  cicero initialize  initialize a clause
  cicero archive     create a template archive
  cicero compile     generate code for a target platform
  cicero get         save local copies of external dependencies

Options:
  --version      Show version number                                   [boolean]
  --verbose, -v                                                 [default: false]
  --help         Show help                                             [boolean]

Command changes:

• generateText -> draft
• init -> initialize
• execute -> trigger
• compile / generate --> compile
• Ergo gets a new draft command (like Cicero)
• Cicero gets a new invoke command (like Ergo)
• Cicero gets a new get command (like Concerto)
• CLIs with both parse and draft (Markus and Cicero) get a new command normalise for round-tripping

[jeromesimeon]

This work is now completed, part of the upcoming 0.20 release.