Define schema for custom command

[cueckoo]

Originally opened by @adieu in cuelang/cue#223

We have following schema in pkg/tool/tool.cue

package tool

// A Command specifies a user-defined command.
Command: {
	//
	// Example:
	//     mycmd [-n] names
	usage?: string

	// short is short description of what the command does.
	short?: string

	// long is a longer description that spans multiple lines and
	// likely contain examples of usage of the command.
	long?: string

	// TODO: define flags and environment variables.

	// tasks specifies the list of things to do to run command. Tasks are
	// typically underspecified and completed by the particular internal
	// handler that is running them. Task de
	tasks <name>: Task
}

// A Task defines a step in the execution of a command.
Task: {
	// kind indicates the operation to run. It must be of the form
	// packagePath.Operation.
	kind: =~#"\."#
}

And following schema in cmd/cue/cmd/cmd.go

command: [Name=string]: { // from tool.Command
    // usage gives a short usage pattern of the command.
    // Example:
    //    fmt [-n] [-x] [packages]
    usage?: Name | string

    // short gives a brief on-line description of the command.
    // Example:
    //    reformat package sources
    short?: string

    // long gives a detailed description of the command, including a
    // description of flags usage and examples.
    long?: string

    // A task defines a single action to be run as part of this command.
    // Each task can have inputs and outputs, depending on the type
    // task. The outputs are initially unspecified, but are filled out
    // by the tooling
    task: [string]: { // from "tool".Task
        // supported fields depend on type
    }

    VarValue = string | bool | int | float | [...string|int|float]

    // var declares values that can be set by command line flags or
    // environment variables.
    //
    // Example:
    //   // environment to run in
    //   var env: "test" | "prod"
    // The tool would print documentation of this flag as:
    //   Flags:
    //      --env string    environment to run in: test(default) or prod
    var: [string]: VarValue

    // flag defines a command line flag.
    //
    // Example:
    //   var env: "test" | "prod"
    //
    //   // augment the flag information for var
    //   flag env: {
    //       shortFlag:   "e"
    //       description: "environment to run in"
    //   }
    //
    // The tool would print documentation of this flag as:
    //   Flags:
    //     -e, --env string    environment to run in: test(default), staging, or prod
    //
    flag [Name=_]: { // from "tool".Flag
        // value defines the possible values for this flag.
        // The default is string. Users can define default values by
        // using disjunctions.
        value: *env[Name].value | VarValue

        // name, if set, allows var to be set with the command-line flag
        // of the given name. null disables the command line flag.
        name?: *Name | string

        // short defines an abbreviated version of the flag.
        // Disabled by default.
        short?: string
    }

    // populate flag with the default values for
    for k, v in var {
        flag: { "\(k)": { value: v } | null  }
    }

    // env defines environment variables. It is populated with values
    // for var.
    //
    // To specify a var without an equivalent environment variable,
    // either specify it as a flag directly or disable the equally
    // named env entry explicitly:
    //
    //     var foo: string
    //     env foo: null  // don't use environment variables for foo
    //
    env: [Name=_]: {
        // name defines the environment variable that sets this flag.
        name?: *"CUE_VAR_" + strings.Upper(Name) | string

        // The value retrieved from the environment variable or null
        // if not set.
        value?: string | bytes
    }
    env: {
        for k, v in var {
            "\(k)": { value: v } | null
        }
    }
}

Since we're about to support flags and environment variables, maybe we can finalize the schema definition for command now.

[cueckoo]

Original reply by @mpvl in cuelang/cue#223 (comment)

The one in cmd.go is outdated and I forgot to update it. This is related to Issue #9: Ideally, all documentation is generated from a single source, which should probably be the CUE source.

The remaining question is related to designing flags and env variables. The current design assumes flags (and env vars) are a task. In that case, flags definitions just become a map:

command: foo: {
    task: flags: {
        // set how many times foo is run
        count: int | *3
    }

This works better with the hierarchical task design, in which flags could just be a top-level section as in the original design. This removes any of the magic that is still documented in cmd.go.