View source for Proposals/Mahara Shell

== tl;dr; ==

* add a <code>mash</code> command to the project root
* for [https://bugs.launchpad.net/mahara/+bug/1953562 reasons] we should move the existing CLI scripts out of the webroot.
* create a single wrapper for all CLI commands
* creates a consistent 'pattern' for CLI commands
* moves the processing of these commands to the libraries they act on/from.

== The issue & proposal ==

[https://bugs.launchpad.net/mahara/+bug/1953562 There are some reasons] to move the CLI scripts out of the webroot.  They are outlined on the linked bug.

The current way we build new 'commands' is to create a new one-shot script to do a task. All the logic for that lives in the script and is distinctly separate from the code that it may be using. This makes for potential issues when updates may alter the data structure being acted on. Bringing the actual command code into the class that it is acting on will remove that separation.

Command discovery is difficult.  Unless you know 'there is a script for that' you are unlikely to check for it.  The new approach will expose all commands available through a simple call to <code>./mash</code> with no parameters.

== Effort ==

The proposed approach would be to have a single script that examines the codebase looking for cli commands.  This would start with walking over;

* a stand-alone directory outside of the webroot for outlier commands (commands that don't really fit in existing libraries)
* all plugins
* all modules

These are currently discoverable and easily checked.  Each class is included and checked for the command declaration method. This returns a simple array with the details to describe/execute the commands made available.

=== Progress ===

I've been working on the Elasticsearch 7 upgrade and found myself doing resets of things very frequently. This was more time consuming than I liked so I actually made a start on this.

Currently I have the following commands already working for me:
* <code>./mash search-queue</code>
* <code>./mash search-reset-index</code>
* <code>./mash search-reset-cron-lock</code>
* <code>./mash cache-clear</code>

The <code>mash</code> script currently does command discovery.  I would like to refactor how this works already and add annotation based discovery rather than checking for the existence of the method. The discovery code is currently in the <code>mash</code> script and this should be moved to the <code>cli</code> class.

The items currently working are very basic from the perspective of how much of the <code>cli</code> class is used. More fully featured use of the class still needs to be tested.

==== Creating a mash command ====

Currently there are 2 methods you can add to a class to get a new command added.

<code>cliGetCommands()</code> : Returns an array defining any commands the class adds. This is an array of arrays and gives, at minimum, a title, name, and method.  Title as the plain label of the command. Name is the name of the command. e.g. <code>./mash [name]</code>. Method is the function in the class that is executed.

<code>cliMyMashCommand</code> : The method executed.

At this point I'm using <code>cli</code> as a prefix to identify methods for the <code>mash</code> command. I'm considering changing this to <code>mash</code> to make it stand out a bit better.