Zero Command-Line Support

We're going to rebase the Zero CLI on Zero.

The Zero CLI is currently based upon Apache Ant. Ant is well-suited for build operations, but we've stretched it a bit to use it as the basis of an extensible CLI. The Ant tasks also face an awkward integration with Zero (e.g. a database setup task should have access to the db configuration, as specified in zero.config). Further, the switch will improve consistency for developers: Extensions to the Zero CLI will be event handlers, similar to all other components for Zero.

Design

Invocation
zero <mytask> [arg ...]

Help system
zero help <mytask> renders help text for task "mytask"

Implementation
We currently support invoking zero run with a custom event, which addresses the run-time aspects of CLI support. However, the new design goes further by including help text. We'll create a new convention to deal with CLI task implementation and help files.

One implementation is provided per CLI task.

app/tasks/mytask.groovy
         /help/mytask_full.txt
         /help/mytask_short.txt

• mytask.groovy is a handler for the "cliTask" event
• /event/task contains the name of the invoked task (useful for Java impls)
• /event/args contains a List of the command-line arguments; none if not specified
• content of mytask_short.txt is a one-line summary; all one-line summaries are rendered in response to zero or zero help
• content of mytask_full.txt is a full description (including formatting (e.g. tab))

Localization
Help content may be localized with lang subfolders. For example:

app/tasks/mytask.groovy
         /help/en/mytask_full.txt
         /help/en/mytask_short.txt
         /help/jp/mytask_full.txt
         /help/jp/mytask_short.txt

Search order is specific-to-general; for example app/tasks/help/en/mytask_full.txt, then app/tasks/help/mytask_full.txt.

Java
Ensure that we can register Java implementations of CLI tasks. For example:

/config/handlers += [{
   "events" : "cliTask",
   "handler" : "zero.core.task.ResolveTask.class",
   "conditions" : "/event/task =~ resolve"
}]

Subtasks
No special support for subtasks. Developers can emulate this concept with a naming convention. For example, "task" and "task_subtask".

Launching

In order to support invoking custom tasks as zero customTask arg1 arg2 rather than zero run -event customTask arg1 arg2, we will rebase the zero.bat/zero scripts to no longer rely on Ant/zero.tools.Main and instead invoke zero.core.Main directly.

There are two types of tasks, those that are app-based (run, resolve, etc.) and those that are not (create, install, get). App-based tasks must be invoked from within the app they are operating on or they will fail. Non app-based tasks can be run from anywhere since they will leverage the logging.properties and .zeroresolvedproperties from zero.home. zero.home will contain a logging.properties file that only writes to the ConsoleLogger by default.

There is no way for developers to provide their own non-app-based tasks. Our non-app-based tasks will be provided as part of zero.kernel.

App-based tasks will always load the config from an app, even when the task doesn't necessarily need it.

The current logic in zero.bat/zero scripts deals with three cases, two of them exceptional:

• If .zeroresolved.properties doesn't exist in zero.home, go get zero.tools and create .zeroresolved.properties
• If .zeroresolved.properties exists in zero.home, but zero.tools is not in the repo, most likely the user deleted their repo, so go get zero.tools
• If .zeroresolved.properties exists in zero.home and zero.tools is in the repo, launch the ant launcher and pass it zero.tools.Main, which will invoke the proper Ant target

The zero2.bat/zero2 scripts will have more cases to deal with:

• If .zeroresolved.properties exists in user.dir and zero.tools is in the repo, run zero.core.Main after building the appropriate classpath
• If .zeroresolved.properties doesn't exist in user dir, look for it in zero.home, if .zeroresolved.properties is there and zero.tools is in the repo, run zero.core.Main after building the appropriate classpath
• If .zeroresolved.properties doesn't exist in userdir or zero.home, go get zero.tools and create .zeroresolved.properties in zero.home
• if .zeroresolved.properties does exist in either user.dir or zero.home, but zero.tools is not in the repo, go get zero.tools