(cli): git-like subcommand extension system

misterjoshua commented 2 years ago

Description

I'd like the CDK CLI to support a git-like subcommand system wherein users can type cdk <subcommand> and have the CDK CLI lookup and run a standalone executable (potentially named cdk-<subcommand>).

Use Case

In https://github.com/aws/aws-cdk/issues/18949, we attempted to introduce a cdk exec command to tighten up local development for lambdas and step functions. While the use case identified a legitimate pain point, and the concept of the command was well-received, AWS members expressed concerns both in terms of ownership of the feature and in adding more surface area to the CDK CLI.

Alternatively, we considered whether other AWS teams and the community could create stand-alone tools to interact with the cloud assembly to provide the desired functionality. While possible, these tools would have poor discoverability and could contribute to ecosystem fragmentation.

Proposed Solution

When the user types cdk <subcommand>, and if CDK doesn't know the subcommand, the CDK CLI should search the path for a command called cdk-<subcommand>. If found, the CDK CLI should run it, passing all arguments.

Meanwhile, if NPM packages implement this pattern, adding a keyword like cdk-extension should allow Construct Hub users to discover this extension.

Other information

First suggested by @rix0rrr in #18949

Possible extensions:

cdk-exec - Executes a Lambda or State Machine when given a cloud assembly and a path to the construct
cdk-describe - Lists the physical id and physical resource attributes of any resources backing a construct
cdk-pipeline - Pretty-print the CDK Pipeline's current status
cdk-integ - Provides an IntegrationTest construct and a subcommand extension to run one, some, or all of them, and report on the results.

Links: "How to integrate new subcommands" - Git IRC guide for how to add git subcommands. This might help to get a flavor for how Git accomplishes this.

Acknowledge

[ ] I may be able to implement this feature request
[ ] This feature might incur a breaking change

misterjoshua commented 2 years ago

@rix0rrr Is this like the git-like subcommand system you had in mind?

hoegertn commented 2 years ago

Ping @iliapolo for construct hub

rix0rrr commented 2 years ago

This is indeed what I had in mind. I guess it's up to the user to npm install -g this... but that's something we can sort out for later.

skinny85 commented 2 years ago

Or, they could depend on both of the aws-cdk package, and the third-party command package in their package.json file, and thus version-control this part like any other thing in their project 🙂.

Another good reason not to rely on globally installing these packages.

misterjoshua commented 2 years ago

I wonder whether the extension commands should show in cdk help.

I also wonder whether it matters for users to know whether any given command is an extension or from the standard cdk cli.

skinny85 commented 2 years ago

I wonder whether the extension commands should show in cdk help.

If we can do that, I think we should - I don't see a reason why not.

I also wonder whether it matters for users to know whether any given command is an extension or from the standard cdk cli.

I don't think that distinction is super important. I wouldn't bother with it.

skinny85 commented 2 years ago

I guess the one place that distinction might be important is where to report bugs with a given command.

misterjoshua commented 2 years ago

I guess the one place that distinction might be important is where to report bugs with a given command.

If we can show extension commands in cdk help, maybe we should place an indication of their being extensions in the usage description.

mrpackethead commented 2 years ago

The idea of extension commands is potentially good. I quite like it. I find myself disagreeing with @skinny85 in that i think its potentially confusing not to make it clear if its standard cdk or an extension. I am spending a lot of time with people who are just starting out in cdk, and its tricky enough now.

if they see cdk shineythingin some blog/doco they have no idea that its not standard cdk, and that they will need to install it.

cdk extn shineything is more to type.. but its very much clearer, and if you have that, then at least you have the opportunity for you create a sensible error.. "The cdk extension shineything has not been installed"

is there going to be acdk installextension command?

skinny85 commented 2 years ago

I feel like any blog post showing something like that would mention the custom command 🙂.

Showing the origin of the command in --help if it's external is a good idea.

exalted commented 1 year ago

:two-cents: in order to make an extension's availability explicit you may consider having to "enable" that extension in cdk.json file or in a new "cdk" section in package.json or something like that.

aws / aws-cdk