feat(cli): add --debug-app and --debug-cli flags

.projenrc.ts

@@ -345,7 +345,7 @@ const repoProject = new yarn.Monorepo({
 });
 
 repoProject.tryFindObjectFile(`${repoProject.name}.code-workspace`)?.patch(
-  pj.JsonPatch.add('/settings/jest.jestCommandLine', 'npx jest'),
+  pj.JsonPatch.add('/settings/jest.jestCommandLine', 'yarn jest'),
   pj.JsonPatch.add('/settings/js~1ts.tsdk.path', '<root>/node_modules/typescript/lib'),
 );
 

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/doctor/cdk-doctor.integtest.ts

@@ -4,7 +4,7 @@ integTest(
   'cdk doctor displays diagnostic information',
   withDefaultFixture(async (fixture) => {
     const output = await fixture.cdk(['doctor']);
-    expect(output).toContain('CDK Version');
+    expect(output).toContain('CDK CLI Version');
     expect(output).toContain('AWS environment variables');
     expect(output).toContain('CDK environment variables');
   }),

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/environment.ts

@@ -89,7 +89,7 @@ export function synthParametersFromSettings(settings: Settings): {
     env: {
       // An environment variable instead of a context variable, so it can also
       // be accessed in framework code where we don't have access to a construct tree.
-      ...settings.get(['debug']) ? { CDK_DEBUG: 'true' } : {},
+      ...settings.get(['debugApp']) ? { CDK_DEBUG: 'true' } : {},
     },
   };
 }

packages/@aws-cdk/toolkit-lib/test/api/cloud-assembly/environment.test.ts

@@ -1,5 +1,6 @@
 import * as fs from 'fs-extra';
-import { guessExecutable } from '../../../lib/api/cloud-assembly/environment';
+import { guessExecutable, synthParametersFromSettings } from '../../../lib/api/cloud-assembly/environment';
+import { Settings } from '../../../lib/api/settings';
 
 const BOTH = 'both' as const;
 const DONTCARE = 'DONT-CARE';
@@ -76,3 +77,25 @@ function explodeBoth<F extends unknown, R extends unknown[]>(input: [F, ...R]):
 
 type NotBoth<A> = Exclude<A, 'both'>;
 type NotBothA<A extends unknown[]> = { [I in keyof A]: NotBoth<A[I]> };
+
+describe('synthParametersFromSettings sets CDK_DEBUG from debugApp', () => {
+  test('debugApp: true sets CDK_DEBUG', () => {
+    const { env } = synthParametersFromSettings(new Settings({ debugApp: true }));
+    expect(env.CDK_DEBUG).toBe('true');
+  });
+
+  test('debugApp: false does not set CDK_DEBUG', () => {
+    const { env } = synthParametersFromSettings(new Settings({ debugApp: false }));
+    expect(env.CDK_DEBUG).toBeUndefined();
+  });
+
+  test('debugCli alone does not set CDK_DEBUG', () => {
+    const { env } = synthParametersFromSettings(new Settings({ debugCli: true }));
+    expect(env.CDK_DEBUG).toBeUndefined();
+  });
+
+  test('no debug settings does not set CDK_DEBUG', () => {
+    const { env } = synthParametersFromSettings(new Settings({}));
+    expect(env.CDK_DEBUG).toBeUndefined();
+  });
+});

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

@@ -2,7 +2,7 @@ import type { IScope, Statement } from '@cdklabs/typewriter';
 import { $E, Expression, ExternalModule, FreeFunction, Module, SelectiveModuleImport, ThingSymbol, Type, TypeScriptRenderer, code, expr } from '@cdklabs/typewriter';
 import { EsLintRules } from '@cdklabs/typewriter/lib/eslint-rules';
 import * as prettier from 'prettier';
-import { lit, SOURCE_OF_TRUTH } from './util';
+import { lit, SOURCE_OF_TRUTH, kebabToCamelCase } from './util';
 import type { CliConfig, CliOption, YargsOption } from './yargs-types';
 
 // to import lodash.clonedeep properly, we would need to set esModuleInterop: true
@@ -16,6 +16,7 @@ export class CliHelpers extends ExternalModule {
   public readonly isCI = makeCallableExpr(this, 'isCI');
   public readonly shouldDisplayNotices = makeCallableExpr(this, 'shouldDisplayNotices');
   public readonly yargsNegativeAlias = makeCallableExpr(this, 'yargsNegativeAlias');
+  public readonly yargsImplies = makeCallableExpr(this, 'yargsImplies');
 }
 
 function makeCallableExpr(scope: IScope, name: string) {
@@ -141,7 +142,7 @@ function makeOptions(prefix: Expression, options: { [optionName: string]: CliOpt
       optionProps.requiresArg = true;
     }
 
-    for (const optionProp of Object.keys(optionProps).filter(opt => !['negativeAlias'].includes(opt))) {
+    for (const optionProp of Object.keys(optionProps).filter(opt => !['negativeAlias', 'implies'].includes(opt))) {
       const optionValue = (optionProps as any)[optionProp];
       if (optionValue instanceof Expression) {
         optionArgs[optionProp] = optionValue;
@@ -164,6 +165,15 @@ function makeOptions(prefix: Expression, options: { [optionName: string]: CliOpt
       }));
       optionsExpr = optionsExpr.callMethod('middleware', middleware, lit(true));
     }
+
+    // Special case for `implies`: a flag that switches on other boolean options.
+    // We add a middleware that sets the implied options to `true` when the flag is set:
+    // .middleware(yargsImplies('debug', ['debugApp', 'debugCli']), true)
+    if (theOption.implies && theOption.implies.length > 0) {
+      const impliedOptions = theOption.implies.map((implied) => kebabToCamelCase(implied));
+      const middleware = helpers.yargsImplies.call(lit(kebabToCamelCase(option)), lit(impliedOptions));
+      optionsExpr = optionsExpr.callMethod('middleware', middleware, lit(true));
+    }
   }
 
   return optionsExpr;

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

@@ -31,6 +31,15 @@ export interface YargsOption {
 
 export interface CliOption extends Omit<YargsOption, 'nargs' | 'hidden'> {
   negativeAlias?: string;
+
+  /**
+   * Other (boolean) options that are switched on to `true` when this option is set.
+   *
+   * Implemented as a yargs middleware that runs before validation. Use kebab-case
+   * option names (e.g. `['debug-app', 'debug-cli']`); they are converted to the
+   * camelCase argv keys for you.
+   */
+  implies?: string[];
 }
 
 export interface Middleware {

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

@@ -29,7 +29,9 @@ export async function makeConfig(): Promise<CliConfig> {
       'ignore-errors': { type: 'boolean', default: false, desc: 'Ignores synthesis errors, which will likely produce an invalid output' },
       'json': { type: 'boolean', alias: 'j', desc: 'Use JSON output instead of YAML when templates are printed to STDOUT', default: false },
       'verbose': { type: 'boolean', alias: 'v', desc: 'Show debug logs (specify multiple times to increase verbosity)', default: false, count: true },
-      'debug': { type: 'boolean', desc: 'Debug the CDK app. Log additional information during synthesis, such as creation stack traces of tokens (sets CDK_DEBUG, will slow down synthesis)', default: false },
+      'debug': { type: 'boolean', default: false, implies: ['debug-app', 'debug-cli'], desc: 'Produce more detailed output to help diagnose unexpected behavior for the CDK app and CDK CLI. Note that this will significantly slow down synthesis time.' },
+      'debug-app': { type: 'boolean', default: false, desc: 'Debug the CDK app. Logs additional information during synthesis, such as creation stack traces and sets the CDK_DEBUG environment variable. Will slow down synthesis.' },
+      'debug-cli': { type: 'boolean', default: false, desc: 'Debug the CDK CLI itself.' },
       'profile': { type: 'string', desc: 'Use the indicated AWS profile as the default environment', requiresArg: true },
       'region': { type: 'string', desc: 'Use the indicated AWS region as the default region', requiresArg: true },
       'proxy': { type: 'string', desc: 'Use the indicated proxy. Will read from HTTPS_PROXY environment variable if not specified', requiresArg: true },

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

@@ -53,8 +53,22 @@
     },
     "debug": {
       "type": "boolean",
-      "desc": "Debug the CDK app. Log additional information during synthesis, such as creation stack traces of tokens (sets CDK_DEBUG, will slow down synthesis)",
-      "default": false
+      "default": false,
+      "implies": [
+        "debug-app",
+        "debug-cli"
+      ],
+      "desc": "Produce more detailed output to help diagnose unexpected behavior for the CDK app and CDK CLI. Note that this will significantly slow down synthesis time."
+    },
+    "debug-app": {
+      "type": "boolean",
+      "default": false,
+      "desc": "Debug the CDK app. Logs additional information during synthesis, such as creation stack traces and sets the CDK_DEBUG environment variable. Will slow down synthesis."
+    },
+    "debug-cli": {
+      "type": "boolean",
+      "default": false,
+      "desc": "Debug the CDK CLI itself."
     },
     "profile": {
       "type": "string",

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

@@ -6,7 +6,7 @@ import * as chalk from 'chalk';
 import { guessLanguage } from '../util';
 import { CdkToolkit, AssetBuildTime } from './cdk-toolkit';
 import { ciSystemIsStdErrSafe } from './ci-systems';
-import { displayVersionMessage } from './display-version';
+import { displayVersionMessage, shouldDisplayVersionMessage } from './display-version';
 import type { IoMessageLevel } from './io-host';
 import { CliIoHost } from './io-host';
 import { parseCommandLineArguments } from './parse-command-line-arguments';
@@ -88,12 +88,8 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
   }, true);
   const ioHelper = asIoHelper(ioHost, ioHost.currentAction as any);
 
-  // If users request debug information (which switches on CDK_DEBUG=1 to get the
-  // CDK app to emit more information), they probably are troubleshooting and we've
-  // historically decided they then want more logging from the CLI as well.
-  // There is currently no way to get the CDK to emit tracing information that
-  // does not cause the CLI to barf logs to the console.
-  setSdkTracing(argv.debug || argv.verbose > 2);
+  // CLI debugging (and the highest verbosity, `-vvv`) turns on verbose AWS SDK tracing.
+  setSdkTracing(Boolean(argv.debugCli) || argv.verbose > 2);
 
   try {
     await checkForPlatformWarnings(ioHelper);
@@ -246,7 +242,9 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
     await outDirLock?.release();
 
     // Do PSAs here
-    await displayVersionMessage(ioHelper);
+    if (shouldDisplayVersionMessage()) {
+      await displayVersionMessage(ioHelper);
+    }
 
     await refreshNotices;
     if (cmd === 'notices') {
@@ -323,6 +321,7 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
         ioHost.currentAction = 'doctor';
         return doctor({
           ioHelper,
+          settings: configuration.settings,
         });
 
       case 'ls':

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

@@ -20,6 +20,8 @@ export function convertYargsToUserInput(args: any): UserInput {
     json: args.json,
     verbose: args.verbose,
     debug: args.debug,
+    debugApp: args.debugApp,
+    debugCli: args.debugCli,
     profile: args.profile,
     region: args.region,
     proxy: args.proxy,
@@ -371,6 +373,8 @@ export function convertConfigToUserInput(config: any): UserInput {
     json: config.json,
     verbose: config.verbose,
     debug: config.debug,
+    debugApp: config.debugApp,
+    debugCli: config.debugCli,
     profile: config.profile,
     region: config.region,
     proxy: config.proxy,

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

@@ -95,15 +95,15 @@ function getMajorVersionUpgradeMessage(currentVersion: string): string | void {
   }
 }
 
+export function shouldDisplayVersionMessage(): boolean {
+  return !!process.stdout.isTTY && !process.env.CDK_DISABLE_VERSION_CHECK;
+}
+
 export async function displayVersionMessage(
   ioHelper: IoHelper,
   currentVersion = versionNumber(),
   versionCheckCache?: VersionCheckTTL,
 ): Promise<void> {
-  if (!process.stdout.isTTY || process.env.CDK_DISABLE_VERSION_CHECK) {
-    return;
-  }
-
   try {
     const versionMessages = await getVersionMessages(currentVersion, versionCheckCache ?? new VersionCheckTTL());
     for (const e of formatAsBanner(versionMessages)) {

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

@@ -73,7 +73,18 @@ export function parseCommandLineArguments(args: Array<string>): any {
     .option('debug', {
       default: false,
       type: 'boolean',
-      desc: 'Debug the CDK app. Log additional information during synthesis, such as creation stack traces of tokens (sets CDK_DEBUG, will slow down synthesis)',
+      desc: 'Produce more detailed output to help diagnose unexpected behavior for the CDK app and CDK CLI. Note that this will significantly slow down synthesis time.',
+    })
+    .middleware(helpers.yargsImplies('debug', ['debugApp', 'debugCli']), true)
+    .option('debug-app', {
+      default: false,
+      type: 'boolean',
+      desc: 'Debug the CDK app. Logs additional information during synthesis, such as creation stack traces and sets the CDK_DEBUG environment variable. Will slow down synthesis.',
+    })
+    .option('debug-cli', {
+      default: false,
+      type: 'boolean',
+      desc: 'Debug the CDK CLI itself.',
     })
     .option('profile', {
       default: undefined,

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

@@ -176,11 +176,19 @@ export class Configuration {
     this.context = new Context(...contextSources);
 
     // Build settings from what's left
-    this.settings = this.defaultConfig
+    const mergedSettings = this.defaultConfig
       .merge(userConfig)
       .merge(this.projectConfig)
-      .merge(this.commandLineArguments)
-      .makeReadOnly();
+      .merge(this.commandLineArguments);
+
+    // Backwards compatibility: a `debug: true` in a config file (cdk.json / ~/.cdk.json)
+    // implies both debug targets, mirroring the `--debug` CLI flag.
+    if (mergedSettings.get(['debug'])) {
+      mergedSettings.set(['debugApp'], true);
+      mergedSettings.set(['debugCli'], true);
+    }
+
+    this.settings = mergedSettings.makeReadOnly();
 
     await this.ioHelper.defaults.debug('merged settings:', this.settings.all);
 
@@ -304,7 +312,11 @@ export async function commandLineArgumentsToSettings(ioHelper: IoHelper, argv: A
     build: argv.build,
     caBundlePath: argv.caBundlePath,
     context,
-    debug: argv.debug,
+    // The `--debug` implication (both debug targets) is resolved during argument
+    // parsing, so here we only read the resolved per-target flags.
+    debugApp: argv.debugApp,
+    debugCli: argv.debugCli,
+    verbose: argv.verbose,
     tags,
     language: argv.language,
     pathMetadata: argv.pathMetadata,

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

@@ -237,12 +237,26 @@ export interface GlobalOptions {
   readonly verbose?: number;
 
   /**
-   * Debug the CDK app. Log additional information during synthesis, such as creation stack traces of tokens (sets CDK_DEBUG, will slow down synthesis)
+   * Produce more detailed output to help diagnose unexpected behavior for the CDK app and CDK CLI. Note that this will significantly slow down synthesis time.
    *
    * @default - false
    */
   readonly debug?: boolean;
 
+  /**
+   * Debug the CDK app. Logs additional information during synthesis, such as creation stack traces and sets the CDK_DEBUG environment variable. Will slow down synthesis.
+   *
+   * @default - false
+   */
+  readonly debugApp?: boolean;
+
+  /**
+   * Debug the CDK CLI itself.
+   *
+   * @default - false
+   */
+  readonly debugCli?: boolean;
+
   /**
    * Use the indicated AWS profile as the default environment
    *

packages/aws-cdk/lib/cli/util/yargs-helpers.ts

@@ -24,6 +24,25 @@ export function yargsNegativeAlias<T extends { [x in S | L]: boolean | undefined
   };
 }
 
+/**
+ * yargs middleware to switch on other boolean options when a flag is set.
+ * E.g. `--debug` implies `--debug-app` and `--debug-cli`.
+ *
+ * @param flag - The camelCase name of the flag that implies the others, e.g. `debug`
+ * @param impliedOptions - The camelCase names of the options to switch on, e.g. `['debugApp', 'debugCli']`
+ * @returns a middleware function that can be passed to yargs
+ */
+export function yargsImplies(flag: string, impliedOptions: string[]): (argv: Record<string, any>) => Record<string, any> {
+  return (argv: Record<string, any>) => {
+    if (argv[flag]) {
+      for (const implied of impliedOptions) {
+        argv[implied] = true;
+      }
+    }
+    return argv;
+  };
+}
+
 /**
  * Returns the current version of the CLI
  * @returns the current version of the CLI

packages/aws-cdk/lib/commands/context.ts

@@ -4,7 +4,6 @@ import * as chalk from 'chalk';
 import picomatch = require('picomatch');
 import type { Context } from '../api/context';
 import type { IoHelper } from '../api-private';
-import { displayVersionMessage } from '../cli/display-version';
 import { renderTable } from '../cli/tables';
 import { PROJECT_CONFIG, PROJECT_CONTEXT, USER_DEFAULTS } from '../cli/user-configuration';
 
@@ -72,7 +71,6 @@ export async function contextHandler(options: ContextOptions): Promise<number> {
       await listContext(ioHelper, options.context);
     }
   }
-  await displayVersionMessage(ioHelper);
 
   return 0;
 }