fix(lambda-nodejs): use direct spawn for local bundling (#37292)

### Reason for this change

The local bundling path builds a single shell command string and executes it via `spawnSync("bash", ["-c", command])`. User-controlled bundling properties are interpolated into this string without sanitization. Using direct `spawnSync` with argument arrays is the idiomatic Node.js approach and avoids shell interpretation entirely.

### Description of changes

Replace shell-based command execution in the local bundling path with direct `spawnSync` calls using argument arrays.

- `PackageManager.runBinCommand()` returns `string[]` instead of a joined string. Docker-path callers use `.join(" ")`.
- New `BundlingStep` discriminated union type: `shell` (commandHooks), `spawn` (esbuild/tsc/install), `fs` (file operations).
- `createLocalBundlingSteps()` builds the step sequence for local bundling using `toCliArgsArray()` and `getTsconfigCompilerOptionsArray()` (no shell quoting needed).
- `tryBundle()` executes steps sequentially by type.
- Docker bundling path's command is escaped, the default command relies on bash already existing so we can escape it with the bash syntax.
- `commandHooks` remain shell-executed (user-provided by contract).

### Describe any new or updated permissions being added

N/A

### Description of how you validated changes

- All 125 existing aws-lambda-nodejs tests pass (6 suites).
- Updated `Local bundling` test to assert direct spawn calls.
- Added 6 new tests: esbuild options via spawn, nodeModules with fs operations, commandHooks via shell, preCompilation with tsc spawn, shell metacharacter handling, and pnpm workspace/cleanup.
- Full `lerna run build --scope=aws-cdk-lib` passes.
- Locally created a stack comparing the docker and local asset output

### Checklist
- [x] My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

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

Author: Abogical

packages/aws-cdk-lib/aws-lambda-nodejs/lib/bundling.ts

@@ -1,11 +1,12 @@
+import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import type { IConstruct } from 'constructs';
 import { PackageInstallation } from './package-installation';
 import { LockFile, PackageManager } from './package-manager';
 import type { BundlingOptions } from './types';
 import { OutputFormat, SourceMapMode } from './types';
-import { exec, extractDependencies, findUp, getTsconfigCompilerOptions, isSdkV2Runtime } from './util';
+import { exec, extractDependencies, findUp, getTsconfigCompilerOptionsArray, isSdkV2Runtime } from './util';
 import type { Architecture, AssetCode } from '../../aws-lambda';
 import { Code, Runtime } from '../../aws-lambda';
 import * as cdk from '../../core';
@@ -216,24 +217,16 @@ export class Bundling implements cdk.BundlingOptions {
     }
   }
 
-  private createBundlingCommand(scope: IConstruct, options: BundlingCommandOptions): string {
-    const pathJoin = osPathJoin(options.osPlatform);
-    let relativeEntryPath = pathJoin(options.inputDir, this.relativeEntryPath);
-    let tscCommand = '';
-
-    if (this.props.preCompilation) {
-      const tsconfig = this.props.tsconfig ?? findUp('tsconfig.json', path.dirname(this.props.entry));
-      if (!tsconfig) {
-        throw new ValidationError('CannotFindTsconfigJsonPre', 'Cannot find a `tsconfig.json` but `preCompilation` is set to `true`, please specify it via `tsconfig`', scope);
-      }
-      const compilerOptions = getTsconfigCompilerOptions(tsconfig);
-      tscCommand = `${options.tscRunner} "${relativeEntryPath}" ${compilerOptions}`;
-      relativeEntryPath = relativeEntryPath.replace(/\.ts(x?)$/, '.js$1');
-    }
-
-    const loaders = Object.entries(this.props.loader ?? {});
-    const defines = Object.entries(this.props.define ?? {});
-
+  /**
+   * Builds the raw esbuild CLI arguments as an array of strings.
+   * No shell quoting — callers apply their own formatting.
+   */
+  private buildEsbuildArgs(
+    scope: IConstruct,
+    inputDir: string,
+    outputDir: string,
+    pathJoin: (...parts: string[]) => string,
+  ): string[] {
     if (this.props.sourceMap === false && this.props.sourceMapMode) {
       throw new ValidationError('SourceMapModeCannotSource', 'sourceMapMode cannot be used when sourceMap is false', scope);
     }
@@ -242,31 +235,54 @@ export class Bundling implements cdk.BundlingOptions {
     const sourceMapMode = this.props.sourceMapMode ?? SourceMapMode.DEFAULT;
     const sourceMapValue = sourceMapMode === SourceMapMode.DEFAULT ? '' : `=${this.props.sourceMapMode}`;
     const sourcesContent = this.props.sourcesContent ?? true;
-
     const outFile = this.props.format === OutputFormat.ESM ? 'index.mjs' : 'index.js';
-    const esbuildCommand: string[] = [
-      options.esbuildRunner,
-      '--bundle', `"${relativeEntryPath}"`,
+
+    return [
       `--target=${this.props.target ?? toTarget(scope, this.props.runtime)}`,
       '--platform=node',
       ...this.props.format ? [`--format=${this.props.format}`] : [],
-      `--outfile="${pathJoin(options.outputDir, outFile)}"`,
+      `--outfile=${pathJoin(outputDir, outFile)}`,
       ...this.props.minify ? ['--minify'] : [],
       ...sourceMapEnabled ? [`--sourcemap${sourceMapValue}`] : [],
       ...sourcesContent ? [] : [`--sources-content=${sourcesContent}`],
       ...this.externals.map(external => `--external:${external}`),
-      ...loaders.map(([ext, name]) => `--loader:${ext}=${name}`),
-      ...defines.map(([key, value]) => `--define:${key}=${JSON.stringify(value)}`),
+      ...Object.entries(this.props.loader ?? {}).map(([ext, name]) => `--loader:${ext}=${name}`),
+      ...Object.entries(this.props.define ?? {}).map(([key, value]) => `--define:${key}=${value}`),
       ...this.props.logLevel ? [`--log-level=${this.props.logLevel}`] : [],
       ...this.props.keepNames ? ['--keep-names'] : [],
-      ...this.relativeTsconfigPath ? [`--tsconfig="${pathJoin(options.inputDir, this.relativeTsconfigPath)}"`] : [],
-      ...this.props.metafile ? [`--metafile="${pathJoin(options.outputDir, 'index.meta.json')}"`] : [],
-      ...this.props.banner ? [`--banner:js=${JSON.stringify(this.props.banner)}`] : [],
-      ...this.props.footer ? [`--footer:js=${JSON.stringify(this.props.footer)}`] : [],
+      ...this.relativeTsconfigPath ? [`--tsconfig=${pathJoin(inputDir, this.relativeTsconfigPath)}`] : [],
+      ...this.props.metafile ? [`--metafile=${pathJoin(outputDir, 'index.meta.json')}`] : [],
+      ...this.props.banner ? [`--banner:js=${this.props.banner}`] : [],
+      ...this.props.footer ? [`--footer:js=${this.props.footer}`] : [],
       ...this.props.mainFields ? [`--main-fields=${this.props.mainFields.join(',')}`] : [],
-      ...this.props.inject ? this.props.inject.map(i => `--inject:"${i}"`) : [],
-      ...this.props.esbuildArgs ? [toCliArgs(this.props.esbuildArgs)] : [],
+      ...this.props.inject ? this.props.inject.map(i => `--inject:${i}`) : [],
     ];
+  }
+
+  private createBundlingCommand(scope: IConstruct, options: BundlingCommandOptions): string {
+    const pathJoin = osPathJoin(options.osPlatform);
+    let relativeEntryPath = pathJoin(options.inputDir, this.relativeEntryPath);
+    let tscCommand = '';
+
+    if (this.props.preCompilation) {
+      const tsconfig = this.props.tsconfig ?? findUp('tsconfig.json', path.dirname(this.props.entry));
+      if (!tsconfig) {
+        throw new ValidationError('CannotFindTsconfigJsonPre', 'Cannot find a `tsconfig.json` but `preCompilation` is set to `true`, please specify it via `tsconfig`', scope);
+      }
+      const compilerOptionsArray = getTsconfigCompilerOptionsArray(tsconfig);
+      tscCommand = preparePosixShellCommand([options.tscRunner!, relativeEntryPath, ...compilerOptionsArray]);
+      relativeEntryPath = relativeEntryPath.replace(/\.ts(x?)$/, '.js$1');
+    }
+
+    const rawArgs = this.buildEsbuildArgs(scope, options.inputDir, options.outputDir, pathJoin);
+
+    const esbuildArgv: string[] = [
+      options.esbuildRunner,
+      '--bundle', relativeEntryPath,
+      ...rawArgs,
+      ...this.props.esbuildArgs ? toCliArgsArray(this.props.esbuildArgs) : [],
+    ];
+    const esbuildCommand = preparePosixShellCommand(esbuildArgv);
 
     let depsCommand = '';
     if (this.props.nodeModules) {
@@ -301,7 +317,7 @@ export class Bundling implements cdk.BundlingOptions {
     return chain([
       ...this.props.commandHooks?.beforeBundling(options.inputDir, options.outputDir) ?? [],
       tscCommand,
-      esbuildCommand.join(' '),
+      esbuildCommand,
       ...(this.props.nodeModules && this.props.commandHooks?.beforeInstall(options.inputDir, options.outputDir)) ?? [],
       depsCommand,
       ...this.props.commandHooks?.afterBundling(options.inputDir, options.outputDir) ?? [],
@@ -310,15 +326,10 @@ export class Bundling implements cdk.BundlingOptions {
 
   private getLocalBundlingProvider(scope: IConstruct): cdk.ILocalBundling {
     const osPlatform = os.platform();
-    const createLocalCommand = (outputDir: string, esbuild: PackageInstallation, tsc?: PackageInstallation) => this.createBundlingCommand(scope, {
-      inputDir: this.projectRoot,
-      outputDir,
-      esbuildRunner: esbuild.isLocal ? this.packageManager.runBinCommand('esbuild') : 'esbuild',
-      tscRunner: tsc && (tsc.isLocal ? this.packageManager.runBinCommand('tsc') : 'tsc'),
-      osPlatform,
-    });
     const environment = this.props.environment ?? {};
     const cwd = this.projectRoot;
+    const createSteps = (outputDir: string, esbuild: PackageInstallation, tsc?: PackageInstallation) =>
+      this.createLocalBundlingSteps(scope, outputDir, esbuild, tsc);
 
     return {
       tryBundle(outputDir: string) {
@@ -331,31 +342,162 @@ export class Bundling implements cdk.BundlingOptions {
           throw new ValidationError('ExpectedEsbuildVersion', `Expected esbuild version ${ESBUILD_MAJOR_VERSION}.x but got ${Bundling.esbuildInstallation.version}`, scope);
         }
 
-        const localCommand = createLocalCommand(outputDir, Bundling.esbuildInstallation, Bundling.tscInstallation);
-
-        exec(
-          osPlatform === 'win32' ? 'cmd' : 'bash',
-          [
-            osPlatform === 'win32' ? '/c' : '-c',
-            localCommand,
-          ],
-          {
-            env: { ...process.env, ...environment },
-            stdio: [ // show output
-              'ignore', // ignore stdio
-              process.stderr, // redirect stdout to stderr
-              'inherit', // inherit stderr
-            ],
-            cwd,
-            windowsVerbatimArguments: osPlatform === 'win32',
-          });
+        const execOptions = {
+          env: { ...process.env, ...environment },
+          stdio: [
+            'ignore', // ignore stdio
+            process.stderr, // redirect stdout to stderr
+            'inherit', // inherit stderr
+          ] as ['ignore', NodeJS.WriteStream, 'inherit'],
+          cwd,
+        };
+
+        const steps = createSteps(outputDir, Bundling.esbuildInstallation, Bundling.tscInstallation);
+        for (const step of steps) {
+          switch (step.type) {
+            case 'shell':
+              for (const cmd of step.commands) {
+                exec(
+                  osPlatform === 'win32' ? (process.env.COMSPEC ?? 'cmd') : 'bash',
+                  [osPlatform === 'win32' ? '/c' : '-c', cmd],
+                  { ...execOptions, windowsVerbatimArguments: osPlatform === 'win32' },
+                );
+              }
+              break;
+            case 'spawn':
+              exec(step.command[0], step.command.slice(1), {
+                ...execOptions,
+                cwd: step.cwd ?? cwd,
+              });
+              break;
+            case 'callback':
+              try {
+                step.operation();
+              } catch (err) {
+                throw new ValidationError('LocalBundlingFileOperationFailed', `Local bundling file operation failed: ${err instanceof Error ? err.message : String(err)}`, scope);
+              }
+              break;
+          }
+        }
 
         return true;
       },
     };
   }
+
+  /**
+   * Creates structured bundling steps for local execution via direct spawn (no shell).
+   */
+  private createLocalBundlingSteps(
+    scope: IConstruct,
+    outputDir: string,
+    esbuild: PackageInstallation,
+    tsc?: PackageInstallation,
+  ): BundlingStep[] {
+    const steps: BundlingStep[] = [];
+
+    let relativeEntryPath = path.join(this.projectRoot, this.relativeEntryPath);
+
+    // Before bundling hooks
+    const beforeBundling = this.props.commandHooks?.beforeBundling(this.projectRoot, outputDir) ?? [];
+    if (beforeBundling.length) {
+      steps.push({ type: 'shell', commands: beforeBundling });
+    }
+
+    // Pre-compilation with tsc
+    if (this.props.preCompilation) {
+      const tsconfig = this.props.tsconfig ?? findUp('tsconfig.json', path.dirname(this.props.entry));
+      if (!tsconfig) {
+        throw new ValidationError('CannotFindTsconfigJsonPre', 'Cannot find a `tsconfig.json` but `preCompilation` is set to `true`, please specify it via `tsconfig`', scope);
+      }
+      const compilerOptionsArray = getTsconfigCompilerOptionsArray(tsconfig);
+      const tscRunner = tsc && (tsc.isLocal ? this.packageManager.runBinCommand('tsc') : ['tsc']);
+      if (tscRunner) {
+        steps.push({ type: 'spawn', command: [...tscRunner, relativeEntryPath, ...compilerOptionsArray] });
+      }
+      relativeEntryPath = relativeEntryPath.replace(/\.ts(x?)$/, '.js$1');
+    }
+
+    // Esbuild
+    const esbuildRunner = esbuild.isLocal ? this.packageManager.runBinCommand('esbuild') : ['esbuild'];
+
+    const esbuildArgs: string[] = [
+      ...this.buildEsbuildArgs(scope, this.projectRoot, outputDir, (...args: string[]) => path.join(...args)),
+      ...this.props.esbuildArgs ? toCliArgsArray(this.props.esbuildArgs) : [],
+    ];
+
+    steps.push({ type: 'spawn', command: [...esbuildRunner, '--bundle', relativeEntryPath, ...esbuildArgs] });
+
+    // Node modules installation
+    if (this.props.nodeModules) {
+      const pkgPath = findUp('package.json', path.dirname(this.props.entry));
+      if (!pkgPath) {
+        throw new ValidationError('CannotFindPackageJsonProject', 'Cannot find a `package.json` in this project. Using `nodeModules` requires a `package.json`.', scope);
+      }
+
+      // Before install hooks
+      const beforeInstall = this.props.commandHooks?.beforeInstall(this.projectRoot, outputDir) ?? [];
+      if (beforeInstall.length) {
+        steps.push({ type: 'shell', commands: beforeInstall });
+      }
+
+      const dependencies = extractDependencies(pkgPath, this.props.nodeModules);
+      const lockFilePath = path.join(this.projectRoot, this.relativeDepsLockFilePath ?? this.packageManager.lockFile);
+      const isPnpm = this.packageManager.lockFile === LockFile.PNPM;
+      const isBun = this.packageManager.lockFile === LockFile.BUN_LOCK || this.packageManager.lockFile === LockFile.BUN;
+
+      steps.push({
+        type: 'callback',
+        operation: () => {
+          if (isPnpm) {
+            fs.writeFileSync(path.join(outputDir, 'pnpm-workspace.yaml'), '');
+          }
+          fs.writeFileSync(path.join(outputDir, 'package.json'), JSON.stringify({ dependencies }));
+          fs.copyFileSync(lockFilePath, path.join(outputDir, this.packageManager.lockFile));
+        },
+      });
+
+      steps.push({ type: 'spawn', command: [...this.packageManager.installCommand], cwd: outputDir });
+
+      if (isPnpm || isBun) {
+        steps.push({
+          type: 'callback',
+          operation: () => {
+            if (isPnpm) {
+              const modulesYaml = path.join(outputDir, 'node_modules', '.modules.yaml');
+              if (fs.existsSync(modulesYaml)) {
+                fs.rmSync(modulesYaml, { force: true });
+              }
+            }
+            if (isBun) {
+              const cacheDir = path.join(outputDir, 'node_modules', '.cache');
+              if (fs.existsSync(cacheDir)) {
+                fs.rmSync(cacheDir, { recursive: true, force: true });
+              }
+            }
+          },
+        });
+      }
+    }
+
+    // After bundling hooks
+    const afterBundling = this.props.commandHooks?.afterBundling(this.projectRoot, outputDir) ?? [];
+    if (afterBundling.length) {
+      steps.push({ type: 'shell', commands: afterBundling });
+    }
+
+    return steps;
+  }
 }
 
+/**
+ * A single step in the local bundling process.
+ */
+type BundlingStep =
+  | { type: 'shell'; commands: string[] }
+  | { type: 'spawn'; command: string[]; cwd?: string }
+  | { type: 'callback'; operation: () => void };
+
 interface BundlingCommandOptions {
   readonly inputDir: string;
   readonly outputDir: string;
@@ -416,6 +558,24 @@ class OsCommand {
   }
 }
 
+/**
+ * Converts a clean argv array into a single POSIX shell command string.
+ * Each argument is escaped if it contains characters that have special
+ * meaning in a shell. Safe characters (alphanumeric plus a few punctuation
+ * marks commonly found in CLI flags) are left unquoted for readability.
+ */
+function preparePosixShellCommand(argv: string[]): string {
+  return argv.map(posixShellEscape).join(' ');
+}
+
+/**
+ * Escapes a single argument for safe inclusion in a POSIX shell command.
+ * Every argument is single-quoted unconditionally (like Python's shlex.quote).
+ */
+function posixShellEscape(arg: string): string {
+  return "'" + arg.replace(/'/g, "'\\''") + "'";
+}
+
 /**
  * Chain commands
  */
@@ -450,21 +610,24 @@ function toTarget(scope: IConstruct, runtime: Runtime): string {
   return `node${match[1]}`;
 }
 
-function toCliArgs(esbuildArgs: { [key: string]: string | boolean }): string {
-  const args = new Array<string>();
+/**
+ * Converts esbuild args to an array of CLI arguments for direct spawn (no shell quoting).
+ */
+function toCliArgsArray(esbuildArgs: { [key: string]: string | boolean }): string[] {
+  const args: string[] = [];
   const reSpecifiedKeys = ['--alias', '--drop', '--pure', '--log-override', '--out-extension'];
 
   for (const [key, value] of Object.entries(esbuildArgs)) {
     if (value === true || value === '') {
       args.push(key);
     } else if (reSpecifiedKeys.includes(key)) {
-      args.push(`${key}:"${value}"`);
+      args.push(`${key}:${value}`);
     } else if (value) {
-      args.push(`${key}="${value}"`);
+      args.push(`${key}=${value}`);
     }
   }
 
-  return args.join(' ');
+  return args;
 }
 
 /**

packages/aws-cdk-lib/aws-lambda-nodejs/lib/package-manager.ts

@@ -78,13 +78,13 @@ export class PackageManager {
     this.argsSeparator = props.argsSeparator;
   }
 
-  public runBinCommand(bin: string): string {
+  public runBinCommand(bin: string): string[] {
     const [runCommand, ...runArgs] = this.runCommand;
     return [
       os.platform() === 'win32' ? `${runCommand}.cmd` : runCommand,
       ...runArgs,
       ...(this.argsSeparator ? [this.argsSeparator] : []),
       bin,
-    ].join(' ');
+    ];
   }
 }