Update document for 1.9

gh-pages/content/en/docs/overview/built-in-commands.md

@@ -26,7 +26,7 @@ Use `cola config [key] [value]` to set one configuration.
 
 ## completion
 
-Setup auto completion. See help to get instructions:
+setup auto completion. See help to get instructions:
 
 ```shell
 cola completion --help
@@ -89,9 +89,17 @@ Remove a dropin package from the package name defined in manifest
 cola package delete command-launcher-example-package
 ```
 
+### package setup
+
+Manually trigger the package [setup hook](../manifest/#__setup__)
+
+```shell
+cola package setup command-launcher-example-package
+```
+
 ## remote
 
-A collection of commands to manage extra remote registries
+A collection of commands to manage extra remote registries. A registry is a URI that hosts multiple packages. The list of available packages of the registry is defined in its `/index.json` endpoint.
 
 ### remote list
 
@@ -116,3 +124,42 @@ Delete a remote registry by its name.
 ```shell
 cola delete myregistry
 ```
+
+## rename
+
+### rename
+
+Rename a command into a different name
+
+To avoid command conflicts, each command has a unique full name in form of `[name]@[group]@[package]@[repository]`, for group command and root level command, it's group is empty. For example: `hello@@my-package@dropin` is the full name of the command `hello` in `my-package` package, which can be found in the `dropin` repository.
+
+Usually, such command is launched through: `cola [group] [name]`. You can rename the group and the name of the command to a different name, so that you can call it through: `cola [new group] [new name]`
+
+To rename a command to a different name, use following commands:
+
+```shell
+# To change the group name:
+cola rename [group]@@[package]@[repository] [new group]
+
+# To change the command name:
+cola rename [name]@[group]@[package]@[repository] [new name]
+```
+
+For example, you can rename the `hello` command to `bonjour` using following rename command:
+
+```shell
+cola rename hello@@my-package@dropin bonjour
+
+# now call it from cola will trigger the original hello command
+cola bonjour
+```
+
+### rename --delete
+
+To delete a renamed command name
+
+```shell
+cola rename --delete [command full name]
+```
+
+Now you have to use its original name to call the command

gh-pages/content/en/docs/overview/config.md

@@ -43,6 +43,32 @@ toc: true
 | system_package_public_key_file   | string   | the public key file to verify the system package signature                                                                    |
 | verify_package_checksum          | bool     | whether to verify the package checksum during package installation                                                            |
 | verify_package_signature         | bool     | whether to verify the package signature during package installation (will be available in 1.8)                                |
+| extra_remotes                    | map      | extra remote registry configurations, see extra remote configuration  (available 1.8+)                                        |
+| enable_package_setup_hook        | bool     | call setup hook after a new version of package is installed (available 1.9+)                                                  |
+
+### extra remote configuration
+
+Each extra remote must have a unique name, it is used to identify the command as part of the command full name. The example configuration looks like the following:
+
+```json
+{
+    "extra_remotes": {
+        "remote1": {
+            "remote_base_url": "",
+            "sync_policy": "always",
+            "repository_dir": ""
+        }
+    }
+}
+```
+
+| Config Name     | Type   | Description                                                                                                    |
+|-----------------|--------|----------------------------------------------------------------------------------------------------------------|
+| remote_base_url | string | the base url of the remote repository, it must contain a `/index.json` endpoint to list all available packages |
+| sync_policy     | string | how often the repository is synched from its remote, always, hourly, daily, weekly, or monthly                 |
+| repository_dir  | string | the absolute path of the local repository folder to keep the downloaded local packages                         |
+
+> You don't need to manage these extra remote configurations by your self. Use the built-in `remote` command instead
 
 ## Change configuration
 
@@ -52,4 +78,4 @@ It is recommended to use the built-in `config` command to change the configurati
 cola config user_consent_life 24h
 ```
 
-sets the user consent life to 24 hours.
+set the user consent life to 24 hours.

gh-pages/content/en/docs/overview/manifest.md

@@ -64,7 +64,10 @@ Here is an example
 | args               | no                 | the argument list to pass to the executable, command launcher arguments will be appended to the list |
 | validArgs          | no                 | the static list of options for auto-complete the arguments                                           |
 | validArgsCmd       | no                 | array of string, command to run to get the dynamic auto-complete options for arguments               |
-| requiredFlags      | no                 | the static list of options for the command flags                                                     |
+| requiredFlags      | no                 | the static list of options for the command flags (deprecated in 1.9)                                 |
+| flags              | no                 | the flag list (available in 1.9+)                                                                    |
+| exclusiveFlags     | no                 | group of exclusive flags (available in 1.9+)                                                         |
+| groupFlags         | no                 | group of grouped flags, which must be presented together (available in 1.9+)                         |
 | checkFlags         | no                 | whether check the flags defined in manifest before calling the command, default false                |
 | requestedResources | no                 | the resources that the command requested, ex, USERNAME, PASSWORD                                     |
 
@@ -325,8 +328,136 @@ When you type `[cola] city poplution [TAB]`, command launcher will run the comma
 
 More details see: [Auto-Complete](./AUTO_COMPLETE.md)
 
+### flags
+
+> Available in 1.9+
+
+Define flags (options) of the command. Each flags could have the following properties
+
+| Property | Required | Description                                                                             |
+|----------|----------|-----------------------------------------------------------------------------------------|
+| name     | yes      | flag name                                                                               |
+| short    | no       | flag short name, usually one letter                                                     |
+| desc     | no       | flag description                                                                        |
+| type     | no       | flag type, default "string", currently support "string" and bool"                       |
+| default  | no       | flag default value, only available for string type, bool flag's default is always false |
+| required | no       | boolean, is the flag required, default false                                            |
+
+**Example**
+
+```json
+{
+   "cmds": [
+    {
+      "name": "population",
+      "type": "executable",
+      "group": "city",
+      "executable": "get-city-population",
+      "args": [],
+      "validArgs": [
+        "paris",
+        "rome",
+        "london"
+      ],
+      "flags": [
+        {
+          "name": "human",
+          "short": "H",
+          "desc": "return the human readabe format",
+          "type": "bool"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### exclusiveFlags
+
+> Available in 1.9+
+
+Declare two or more flags are mutually exclusive. For example, a flag `json` that outputs JSON format will be exclusive to the flag `text`, which outputs in plain text format.
+
+**Example**
+
+```json
+{
+  "cmds": [
+    {
+      "name": "population",
+      "type": "executable",
+      "group": "city",
+      "executable": "get-city-population",
+      "args": [],
+      "validArgs": [
+        "paris",
+        "rome",
+        "london"
+      ],
+      "flags": [
+        {
+          "name": "human",
+          "short": "H",
+          "desc": "return the human readabe format",
+          "type": "bool"
+        },
+        {
+          "name": "json",
+          "short": "j",
+          "desc": "return the JSON format",
+          "type": "bool"
+        }
+      ],
+      "exclusiveFlags": [
+        [ "human", "json" ]
+      ]
+    }
+  ]
+}
+```
+
+### groupFlags
+
+> Available in 1.9+
+
+Ensure that two or more flags are presented at the same time.
+
+**Example**
+
+```json
+{
+  "cmds": [
+    {
+      "name": "population",
+      "type": "executable",
+      "group": "city",
+      "executable": "get-city-population",
+      "args": [],
+      "flags": [
+        {
+          "name": "country",
+          "short": "c",
+          "desc": "country name",
+          "required": true
+        },
+        {
+          "name": "city",
+          "short": "t",
+          "desc": "city name"
+        }
+      ],
+      "groupFlags": [
+        [ "country", "city" ]
+      ]
+    }
+  ]
+}
+```
+
 ### requiredFlags
 
+> Deprecated in 1.9, see [flags](./#flags) property
+
 The static list of flags for your command
 
 **Example**
@@ -375,13 +506,15 @@ Beside the complete form, it is also possible to have a short form:
 
 Whether parse and check flags before execute the command. Default: false.
 
-The `requiredFlags`, `validArgs` and `validArgsCmd` are mainly used for auto completion. Command launcher will not parse the arguments by default, it will simply pass the arguments to the callee command. In other words, in this case, it is the callee command's responsibility to parse the flags and arguments. This works fine when the command is implemented with languages that has advanced command line supports, like golang.
+The `requiredFlags` (deprecated in 1.9), `flags`, `validArgs` and `validArgsCmd` are mainly used for auto completion. Command launcher will not parse the flag and arguments by default, it will simply pass through them to the callee command. In other words, in this case, it is the callee command's responsibility to parse the flags and arguments. This works fine when the command is implemented with languages that has advanced command line supports, like golang.
 
 For some cases, arguments parsing is difficult or has less support, for example, implementing the command in shell script. Enable `checkFlags` will allow command launcher to parse the arguments and catch errors. Further more, command launcher will pass the parsed flags and arguments to the callee command through environment variables:
 
 - For flags: `COLA_FLAG_[FLAG_NAME]` ('-' is replaced with '_'). Example: flag `--user-name` is passed through environment variable `COLA_FLAG_USER_NAME`
 
-- For arguments: `COLA_ARG_[INDEX]` where the index starts from 1. Example: command `cola get-city-population France Paris` will get environment variable `COLA_ARG_1=France` and `COLA_ARG_2=Paris`
+- For arguments: `COLA_ARG_[INDEX]` where the index starts from 1. Example: command `cola get-city-population France Paris` will get environment variable `COLA_ARG_1=France` and `COLA_ARG_2=Paris`. An additional environment variable `COLA_NARGS` (available in 1.9+) is available as well to get the number of arguments.
+
+> Even checkFlags is set to `true`, command launcher will still pass through the original arguments to the callee command as well, in addition, to the original arguments, parsed flags and arguments are passed to the callee as environment variables.
 
 Another behavior change is that once `checkFlags` is enabled, the `-h` and `--help` flags are handled by command launcher. The original behavior is managed by the callee command itself.
 
@@ -405,3 +538,28 @@ The following snippet requests to access the user name and password resources.
   ]
 }
 ```
+
+## System commands
+
+Besides the [system command](../system-package/#system-commands) defined in a [system package](../system-package). You can define package level system command as a lifecycle hook.
+
+### \_\_setup\_\_
+
+When a package is installed, sometimes it requires some setups to make it work properly. For example, a command written in javascript could require a `npm install` to install all its dependencies. You can define a system command `__setup__` in your package as a normal command, with type `system`, it will be called when the package is installed. (You can disable this behavior, by turning the configuration `enable_package_setup_hook` to `false`). You can also manually trigger it through the built-in command: `cola package setup`
+
+> Make sure the setup hook is idempotent, when a new version is installed the setup hook will be called again.
+
+**Example**
+
+```yaml
+pkgName: package-demo
+version: 1.0.0
+cmds:
+    - name: __setup__
+      type: system
+      executable: "{{.PackageDir}}/hooks/setup-hook"
+      args: [ "predefined-arg1", "predefined-arg2" ]
+    - name: other-commands
+      type: executable
+      executable: "{{.PackageDir}}/scripts/other-cmd.sh"
+```