feat(cli): git repository support for custom init templates

Author: iankhou

packages/@aws-cdk/user-input-gen/lib/yargs-gen.ts

@@ -105,17 +105,22 @@ function makeYargs(config: CliConfig, helpers: CliHelpers): Statement {
     }
     commandCallArgs.push(lit(commandFacts.description));
 
-    if (commandFacts.options) {
-      commandCallArgs.push(optionsExpr);
-    }
-
     // Add implies calls if present
     if (commandFacts.implies) {
       for (const [key, value] of Object.entries(commandFacts.implies)) {
         optionsExpr = optionsExpr.callMethod('implies', lit(key), lit(value));
       }
     }
 
+    // Add check function if present
+    if (commandFacts.check) {
+      optionsExpr = optionsExpr.callMethod('check', code.expr.directCode(commandFacts.check.toString()));
+    }
+
+    if (commandFacts.options || commandFacts.check) {
+      commandCallArgs.push(optionsExpr);
+    }
+
     yargsExpr = yargsExpr.callMethod('command', ...commandCallArgs);
   }
 

packages/@aws-cdk/user-input-gen/lib/yargs-types.ts

@@ -8,6 +8,7 @@ interface YargsCommand {
 export interface CliAction extends YargsCommand {
   options?: { [optionName: string]: CliOption };
   implies?: { [key: string]: string };
+  check?: (argv: any) => boolean | undefined;
 }
 
 interface YargsArg {

packages/@aws-cdk/user-input-gen/test/yargs-gen.test.ts

@@ -105,16 +105,29 @@ describe('render', () => {
         return yargs
           .env('CDK')
           .usage('Usage: cdk -a <cdk-app> COMMAND')
-          .command(['test', 'spec'], 'the action under test', (yargs: Argv) =>
-            yargs
-              .option('one', {
-                default: undefined,
-                type: 'boolean',
-                alias: 'o',
-                desc: 'text for one',
-              })
-              .option('O', { type: 'boolean', hidden: true })
-              .middleware(helpers.yargsNegativeAlias('O', 'one'), true),
+          .command(
+            ['test', 'spec'],
+            'the action under test',
+            (yargs: Argv) =>
+              yargs
+                .option('one', {
+                  default: undefined,
+                  type: 'boolean',
+                  alias: 'o',
+                  desc: 'text for one',
+                })
+                .option('O', { type: 'boolean', hidden: true })
+                .middleware(helpers.yargsNegativeAlias('O', 'one'), true),
+            (yargs: Argv) =>
+              yargs
+                .option('one', {
+                  default: undefined,
+                  type: 'boolean',
+                  alias: 'o',
+                  desc: 'text for one',
+                })
+                .option('O', { type: 'boolean', hidden: true })
+                .middleware(helpers.yargsNegativeAlias('O', 'one'), true),
           )
           .version(helpers.cliVersion())
           .demandCommand(1, '')
@@ -186,20 +199,37 @@ describe('render', () => {
         return yargs
           .env('CDK')
           .usage('Usage: cdk -a <cdk-app> COMMAND')
-          .command('deploy', 'Notification Arns', (yargs: Argv) =>
-            yargs
-              .option('notification-arns', {
-                type: 'array',
-                desc: 'Deploy all stacks',
-                nargs: 1,
-                requiresArg: true,
-              })
-              .option('other-array', {
-                type: 'array',
-                desc: 'Other array',
-                nargs: 1,
-                requiresArg: true,
-              }),
+          .command(
+            'deploy',
+            'Notification Arns',
+            (yargs: Argv) =>
+              yargs
+                .option('notification-arns', {
+                  type: 'array',
+                  desc: 'Deploy all stacks',
+                  nargs: 1,
+                  requiresArg: true,
+                })
+                .option('other-array', {
+                  type: 'array',
+                  desc: 'Other array',
+                  nargs: 1,
+                  requiresArg: true,
+                }),
+            (yargs: Argv) =>
+              yargs
+                .option('notification-arns', {
+                  type: 'array',
+                  desc: 'Deploy all stacks',
+                  nargs: 1,
+                  requiresArg: true,
+                })
+                .option('other-array', {
+                  type: 'array',
+                  desc: 'Other array',
+                  nargs: 1,
+                  requiresArg: true,
+                }),
           )
           .version(helpers.cliVersion())
           .demandCommand(1, '')

packages/aws-cdk/lib/cli/cli-config.ts

@@ -8,6 +8,13 @@ import { getLanguageAlias } from '../commands/language';
 
 export const YARGS_HELPERS = new CliHelpers('./util/yargs-helpers');
 
+interface InitCommandArgs {
+  'template-path'?: string;
+  'from-path'?: string;
+  'from-git-url'?: string;
+  [key: string]: unknown;
+}
+
 /**
  * Source of truth for all CDK CLI commands. `user-input-gen` translates this into:
  *
@@ -406,8 +413,22 @@ export async function makeConfig(): Promise<CliConfig> {
           'lib-version': { type: 'string', alias: 'V', default: undefined, desc: 'The version of the CDK library (aws-cdk-lib) to initialize built-in templates with. Defaults to the version that was current when this CLI was built.' },
           'from-path': { type: 'string', desc: 'Path to a local custom template directory or multi-template repository', requiresArg: true, conflicts: ['lib-version'] },
           'template-path': { type: 'string', desc: 'Path to a specific template within a multi-template repository', requiresArg: true },
+          'from-git-url': { type: 'string', desc: 'Git repository URL to clone custom template from', requiresArg: true, conflicts: ['lib-version', 'from-path'] },
+        },
+        check: (argv: InitCommandArgs) => {
+          const hasTemplatePath = Boolean(argv['template-path']);
+          const hasValidSource = Boolean(argv['from-path'] || argv['from-git-url']);
+
+          if (hasTemplatePath && !hasValidSource) {
+            const e = new Error(
+              '--template-path can only be used with --from-path or --from-git-url',
+            );
+            e.name = 'ValidationError';
+            throw e;
+          }
+
+          return true;
         },
-        implies: { 'template-path': 'from-path' },
       },
       'migrate': {
         description: 'Migrate existing AWS resources into a CDK app',

packages/aws-cdk/lib/cli/cli-type-registry.json

@@ -897,10 +897,16 @@
           "type": "string",
           "desc": "Path to a specific template within a multi-template repository",
           "requiresArg": true
+        },
+        "from-git-url": {
+          "type": "string",
+          "desc": "Git repository URL to clone custom template from",
+          "requiresArg": true,
+          "conflicts": [
+            "lib-version",
+            "from-path"
+          ]
         }
-      },
-      "implies": {
-        "template-path": "from-path"
       }
     },
     "migrate": {

packages/aws-cdk/lib/cli/cli.ts

@@ -547,7 +547,7 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
           return printAvailableTemplates(ioHelper, language);
         } else {
           // Gate custom template support with unstable flag
-          if (args['from-path'] && !configuration.settings.get(['unstable']).includes('init')) {
+          if ((args['from-path'] || args['from-git-url']) && !configuration.settings.get(['unstable']).includes('init')) {
             throw new ToolkitError('Unstable feature use: \'init\' with custom templates is unstable. It must be opted in via \'--unstable\', e.g. \'cdk init --from-path=./my-template --unstable=init\'');
           }
           return cliInit({
@@ -558,6 +558,7 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
             generateOnly: args.generateOnly,
             libVersion: args.libVersion,
             fromPath: args['from-path'],
+            fromGitUrl: args['from-git-url'],
             templatePath: args['template-path'],
           });
         }

packages/aws-cdk/lib/cli/convert-to-user-input.ts

@@ -249,6 +249,7 @@ export function convertYargsToUserInput(args: any): UserInput {
         libVersion: args.libVersion,
         fromPath: args.fromPath,
         templatePath: args.templatePath,
+        fromGitUrl: args.fromGitUrl,
         TEMPLATE: args.TEMPLATE,
       };
       break;
@@ -491,6 +492,7 @@ export function convertConfigToUserInput(config: any): UserInput {
     libVersion: config.init?.libVersion,
     fromPath: config.init?.fromPath,
     templatePath: config.init?.templatePath,
+    fromGitUrl: config.init?.fromGitUrl,
   };
   const migrateOptions = {
     stackName: config.migrate?.stackName,

packages/aws-cdk/lib/cli/parse-command-line-arguments.ts

@@ -888,6 +888,23 @@ export function parseCommandLineArguments(args: Array<string>): any {
           type: 'string',
           desc: 'Path to a specific template within a multi-template repository',
           requiresArg: true,
+        })
+        .option('from-git-url', {
+          default: undefined,
+          type: 'string',
+          desc: 'Git repository URL to clone custom template from',
+          requiresArg: true,
+          conflicts: ['lib-version', 'from-path'],
+        })
+        .check((argv) => {
+          const hasTemplatePath = Boolean(argv['template-path']);
+          const hasValidSource = Boolean(argv['from-path'] || argv['from-git-url']);
+          if (hasTemplatePath && !hasValidSource) {
+            const e = new Error('--template-path can only be used with --from-path or --from-git-url');
+            e.name = 'ValidationError';
+            throw e;
+          }
+          return true;
         }),
     )
     .command('migrate', 'Migrate existing AWS resources into a CDK app', (yargs: Argv) =>

packages/aws-cdk/lib/cli/user-input.ts

@@ -1401,6 +1401,13 @@ export interface InitOptions {
    */
   readonly templatePath?: string;
 
+  /**
+   * Git repository URL to clone custom template from
+   *
+   * @default - undefined
+   */
+  readonly fromGitUrl?: string;
+
   /**
    * Positional argument for init
    */