draft info command proposal

[davidgamero]

Is your feature request related to a problem? Please describe.
Draft's current capabilities are designed to be easy to wrap, and should be implementable by other services easily.

In order to make supported language and field discovery easier, I proposed adding a draft info command that prints supported deployment types, languages, and other important configuration information in a parsing-friendly format such as yaml or json.

Mention what platform you want to support the new feature
The base draft cli tool should implement this feature to allow easy discovery of the available values for dependent services.

For a first milestone, I suggest a default output of json for the draft info command, that prints the following properties: supportedLanguages and supportedDeploymentTypes each as an array of strings.

Future milestones could include:

• supported addons list
• yaml output support using an output flag ex: draft info -o yaml
• printing builder variables for a specified template, or all templates (to make consuming the binary easier)

Describe the solution you'd like
The draft info command should return a standardized output similar to the following:

{
  "supportedLanguages": [
    "javascript",
    "gomodule",
    ...
    "csharp"
    ],
  "supportedDeploymentTypes": [
    "manifest",
    "helm",
    "kustomize"
  ]
}

Describe alternatives you've considered
One alternative route is to publish a file that includes this information the draft repo, so that it can be referenced by other projects, potentially bundling an additional file with each release that details the available commands.
This alternative approach would incur more file-management, and break the single-binary goal of the current cli tool.

Additional context
To further the goal of making draft an extensible, opinionated tool with baked-in best practices, it must be not only extensible, but discoverable. Adding an info command is a step towards making draft even easier to rely on from an external service.

[davidgamero]

@Tatsinnit @OliverMKing @qpetraroia @sabbour @bfoley13

[OliverMKing]

It would be good to add version to the supportedLanguages part.

{
  "supportedLanguages": [
    {
        "name": "javascript",
        "defaultVersion": "Node16", // or whatever the default is
        "recommendedVersions": ["18", "16", "14"],
    },
    ...
  ],
  "supportedDeploymentTypes": [
    "manifest",
    "helm",
    "kustomize"
  ]
}

[sabbour]

How are we storing the mapping of language, version, and Dockerfile to use today? Can we expose that mapping instead of maintaining that logic separately in this command?

[davidgamero]

How are we storing the mapping of language, version, and Dockerfile to use today? Can we expose that mapping instead of maintaining that logic separately in this command?

Most of this information is stored in the templates, which are embedded in the binary.

Dependent tools could reference those directories from the source instead, but then those tools would be dependent on the paths within the draft source code instead of an exposed command. This could open up a scenario where we refactor the code and suddenly break dependent tools without failing any checks or breaking changes to the binary tool.

Having the command solidifies a contract for where we can always expect that information to be retrieved, and removing the command or changing its format would require reviewing a breaking change, while refactoring a template folder would not.

If we want to expose that mapping logic, we could define a mapping file in the source code and do our best to protect it from changes. For dependencies that use draft as a go module we could export a package, but for dependencies like the vscode extension that wrap the binary they would have to just pull a file straight from the draft repo source code whereas currently it only uses the built draft binary.

[sabbour]

Can this command generate the mapping based on the template file/folder structure in the binary? I'm trying to minimize the potential drift that could happen when adding new templates/add-ons. I also want it to be easier for contributors to add templates without having to worry about updating the info command constantly.

If we want to maintain the contract so that changes are breaking, perhaps a tool that runs as part of the pull request flow can build the contract?

[davidgamero]

I think I didn't clarify this in the original proposal enough, but the info command would not just echo some hard-coded information. It traverses the templates to read the available values from the current codebase, so it would stay updated since its output is generated from the templates to begin with.

Is the drift that you are referring to between the "info" command vs the actual templates? If so, the output of the command will be a generated by reading the templates, so it will keep itself in sync.

[sabbour]

It traverses the templates to read the available values from the current codebase, so it would stay updated since its output is generated from the templates to begin with.

That sounds great. Thumbs up 👍

[qpetraroia]

Approved!

[Tatsinnit]

💡 ⛩️ Thank you so much for the ping and adding me to this. Here is my 20 cents worth of thoughts/idea share from what I can get from this write-up.

To understand better about the purpose, motivation and usage: (here is my thinking and sharing it if you find it useful).

What is the target use-case for this new command? (consuming tools vs specific tool usage)

• Is it: Draft is installed, and it traverse through the user's dir code and identify the languages? How about then present it if the language is supported or not?

• If this new command is one stop shop to get all info associated with the draft tool as a purpose for the consuming tool then we should treat it as that and might be re-phrase it as draft getinfo and route that draft --help to this command usage as well.

• I would like to point out at this instance that What do you like about Draft? Does it help you accomplish your goals? #140 makes some really good points for adding some documentations for the existing commands.

All this action is post Draft install, how about pre-install check for the tool?

• How is this command intended to be used? reason I ask is because: if as a user/dev/consumer - if I only want to know what current Draft language support is, without trying to traverse through my code then I would prefer a tool not to and pass me the list which draft tool support.
• getinfo could then be used as consumable endpoint by command-line, but then why not make this info a web-api end point call for-example: currently here is draft info release json object https://api.github.com/repos/Azure/draft/releases/latest

If other folks know the use-case etc getting catered for this instance, then please ignore this input and go-ahead please. Thank you so much. cc: @qpetraroia, @sabbour

[davidgamero]

@Tatsinnit thank you for your feedback and ideas!

What is the target use-case for this new command? (consuming tools vs specific tool usage)

The use case for this command is retrieving supported values for the draft config parameters in a machine readable format such as json.

If this new command is one stop shop to get all info associated with the draft tool as a purpose for the consuming tool then we should treat it as that and might be re-phrase it as draft getinfo and route that draft --help to this command usage as well.

draft --help is designed to provide human readable information to explain command usage, which isn't easy for a program to parse since it includes additional spacing and formatting, so this proposed command carries out a separate functionality

How is this command intended to be used? reason I ask is because: if as a user/dev/consumer - if I only want to know what current Draft language support is, without trying to traverse through my code then I would prefer a tool not to and pass me the list which draft tool support.

this proposal is exclusively for the binary-wrapping consumer usage pattern, in which the draft binary is executed in a controlled environment and knowing valid values prior to executing a run can be used to elevate these options to the binary-wrapping context in a consistent way

documentation improvement proposals from #140

i completely agree with these suggestions for improving the draft documentation, but they are outside the scope of this PR since this only aims to add a specific new command

getinfo could then be used as consumable endpoint by command-line, but then why not make this info a web-api end point call for-example: currently here is draft info release json object

this is a viable alternative approach, and is similar to what @sabbour was proposing higher up, but we decided against it since it would only work for templates that are provided with draft. Since one of the major ways that draft is extensible is through custom templates, adding a command allows us to create a process that generates the machine readable info for a binary-wrapping consumption pattern in a template-agnostic way.

Thanks again for bringing these points up! They really helped clarify what the objective of the feature is, and I hope I addressed them all 😄