Refactor arguments to command resources an mixed strings and objects for extensibility

[SteveL-MSFT]

PR Summary

• args are now always processed regardless if how input is specified, so it's technically possible to have the input passed as both an arg and stdin/env
• args now take a string or an object where the object currently supported looks like:

{
  "jsonInputArg": "<parameter>",
  "mandatory": true
}

The value of jsonInputArg is what the input gets passed to, so "jsonInputArg": "--foo" would be passed as command --foo $json effectively.

The mandatory indicates whether to pass the JSON even if empty. Default is false so it skips providing this parameter completely, but if true, it will always provide the parameter and an empty string if input is empty.

PR Context

Fix #218

[michaeltlombardi]

Rather than deleting this option entirely, I think it makes sense to allow resource authors to explicitly define the input kind as arg to preclude being sent the property bag as environment variables or over stdin and accounting for double processing.

If we do this, we could also update the JSON Schema (and code) to infer the input kind from the manifest - if the args array includes an object and input isn't defined, input is arg. If the args array is only made of strings and input isn't defined, input is stdin. The input is only ever env if it's explicitly defined.

We could then also use JSON schema to validate the args array - if it's explicitly defined as env or stdin, is must not include an object, only strings. If it's not explicitly defined or is defined as arg, it may only include one object in the array.

We could use this to provide better author-time feedback and validation for the resource manifest and direct authors towards best practices.

[michaeltlombardi]

Quick json schema example (a little pseudo code, bc it's a little complex to write initially but functional/useful):

# set property in manifest
input:
  type: string
  enum: [arg, env, stdin]
args:
  type: array
  contains: { type: object } # check if array includes objects
  minContains: 0 # allow string-only
  maxContains: 1 # allow json arg only once
  items:
    anyOf:
      - type: string
      - type: object # validate object structure
        required: [jsonInputArg]
        properties:
          jsonInputArg:
            type: string
          mandatory:
            type: boolean
            default: false
# Helper for validation/authoring
allOf:
  - if: # args items are only strings
    then:
      properties:
        input: { default: stdin }
  - if: # args items includes one object
    then:
      properties:
        input: { default: arg }
  - if: # input is arg (default or explicit)
      properties: { input: { const: arg } }
    then: # require object arg exactly once
      properties:
        args: { minContains: 1 }
    else: # forbid object arg entirely
      properties:
        args: { maxContains: 0 }

[SteveL-MSFT]

The resource author has to opt into any acceptance of the JSON whether it's env, stdin, or args so there isn't a case where it's accidentally sent. However, there might be a case where the resource might want the simplified reception of the JSON as env, but also keep a raw copy as an arg to pass to something else.

[tgauth]

would it be simpler to add this match block to process_args or as its own function since it's repeated within the other commands?

[SteveL-MSFT]

This function is only for processing args, but you're right there's some redundancy. Let me pull out the common part as a function.

[anmenaga]

Why it's not matching the

{
  "jsonInputArg": "<parameter>",
  "mandatory": true
}

syntax?

[SteveL-MSFT]

This is just a test resource that doesn't get run to validate the semver. Maybe I'll rename the type to make this clear and remove the args since they aren't used at all.

[anmenaga]

Kind of too generic message.

[SteveL-MSFT]

Wanted a debug message that may be useful in the future to know that there weren't any args