feat: add local template support with --from-path option (#763)

This PR adds local template support through the new `--from-path` CLI
option. Users can initialize CDK projects from local custom templates,
copying the template as is without placeholder processing.

The feature includes language auto-detection when templates contain a
single language option and error handling for invalid paths. 3 new test
cases covering basic local template functionality, language
auto-detection, and error handling scenarios were added.

Fixes #

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

---------

Signed-off-by: github-actions <[email protected]>
Co-authored-by: github-actions <[email protected]>
Co-authored-by: Ian Hou <[email protected]>

Author: 3 people

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

@@ -109,6 +109,13 @@ function makeYargs(config: CliConfig, helpers: CliHelpers): Statement {
       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));
+      }
+    }
+
     yargsExpr = yargsExpr.callMethod('command', ...commandCallArgs);
   }
 

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

@@ -7,6 +7,7 @@ interface YargsCommand {
 
 export interface CliAction extends YargsCommand {
   options?: { [optionName: string]: CliOption };
+  implies?: { [key: string]: string };
 }
 
 interface YargsArg {

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

@@ -400,8 +400,11 @@ export async function makeConfig(): Promise<CliConfig> {
           'language': { type: 'string', alias: 'l', desc: 'The language to be used for the new project (default can be configured in ~/.cdk.json)', choices: await availableInitLanguages() },
           'list': { type: 'boolean', desc: 'List the available templates' },
           'generate-only': { type: 'boolean', default: false, desc: 'If true, only generates project files, without executing additional operations such as setting up a git repo, installing dependencies or compiling the project' },
-          'lib-version': { type: 'string', alias: 'V', default: undefined, desc: 'The version of the CDK library (aws-cdk-lib) to initialize the project with. Defaults to the version that was current when this CLI was built.' },
+          '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 },
         },
+        implies: { 'template-path': 'from-path' },
       },
       'migrate': {
         description: 'Migrate existing AWS resources into a CDK app',

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

@@ -865,8 +865,24 @@
         "lib-version": {
           "type": "string",
           "alias": "V",
-          "desc": "The version of the CDK library (aws-cdk-lib) to initialize the project with. Defaults to the version that was current when this CLI was built."
+          "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
         }
+      },
+      "implies": {
+        "template-path": "from-path"
       }
     },
     "migrate": {

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

@@ -516,13 +516,19 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
         if (args.list) {
           return printAvailableTemplates(ioHelper, language);
         } else {
+          // Gate custom template support with unstable flag
+          if (args['from-path'] && !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({
             ioHelper,
             type: args.TEMPLATE,
             language,
             canUseNetwork: undefined,
             generateOnly: args.generateOnly,
             libVersion: args.libVersion,
+            fromPath: args['from-path'],
+            templatePath: args['template-path'],
           });
         }
       case 'migrate':

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

@@ -245,6 +245,8 @@ export function convertYargsToUserInput(args: any): UserInput {
         list: args.list,
         generateOnly: args.generateOnly,
         libVersion: args.libVersion,
+        fromPath: args.fromPath,
+        templatePath: args.templatePath,
         TEMPLATE: args.TEMPLATE,
       };
       break;
@@ -481,6 +483,8 @@ export function convertConfigToUserInput(config: any): UserInput {
     list: config.init?.list,
     generateOnly: config.init?.generateOnly,
     libVersion: config.init?.libVersion,
+    fromPath: config.init?.fromPath,
+    templatePath: config.init?.templatePath,
   };
   const migrateOptions = {
     stackName: config.migrate?.stackName,

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

@@ -862,7 +862,20 @@ export function parseCommandLineArguments(args: Array<string>): any {
           default: undefined,
           type: 'string',
           alias: 'V',
-          desc: 'The version of the CDK library (aws-cdk-lib) to initialize the project with. Defaults to the version that was current when this CLI was built.',
+          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.',
+        })
+        .option('from-path', {
+          default: undefined,
+          type: 'string',
+          desc: 'Path to a local custom template directory or multi-template repository',
+          requiresArg: true,
+          conflicts: ['lib-version'],
+        })
+        .option('template-path', {
+          default: undefined,
+          type: 'string',
+          desc: 'Path to a specific template within a multi-template repository',
+          requiresArg: true,
         }),
     )
     .command('migrate', 'Migrate existing AWS resources into a CDK app', (yargs: Argv) =>

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

@@ -1363,14 +1363,28 @@ export interface InitOptions {
   readonly generateOnly?: boolean;
 
   /**
-   * The version of the CDK library (aws-cdk-lib) to initialize the project with. Defaults to the version that was current when this CLI was built.
+   * 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.
    *
    * aliases: V
    *
    * @default - undefined
    */
   readonly libVersion?: string;
 
+  /**
+   * Path to a local custom template directory or multi-template repository
+   *
+   * @default - undefined
+   */
+  readonly fromPath?: string;
+
+  /**
+   * Path to a specific template within a multi-template repository
+   *
+   * @default - undefined
+   */
+  readonly templatePath?: string;
+
   /**
    * Positional argument for init
    */