feat: bundle @aws/agentcore-cdk inside CLI tarball for testing (#731)

* feat: bundle @aws/agentcore-cdk inside CLI tarball

Bundle the L3 CDK constructs package directly into the CLI's distributed
assets so a single tarball install gives users everything they need —
no separate npm install of @aws/agentcore-cdk required.

- copy-assets.mjs: copies pre-built agentcore-cdk into dist/assets/bundled-agentcore-cdk/
- Vended CDK package.json: uses file:../.bundled/agentcore-cdk dependency
- CDKRenderer: copies bundled package into project during agentcore create

Constraint: L3 repo must be built before CLI build (npm run build in sibling dir)
Constraint: AGENTCORE_CDK_PATH env var overrides default sibling resolution
Rejected: Embedding as a direct CLI dependency | CDK constructs are only used in vended projects, not by CLI runtime
Confidence: high
Scope-risk: moderate
Not-tested: offline installs where npm registry is unreachable

* feat: add npm run bundle command for single-command packaging

Adds scripts/bundle.mjs that orchestrates the full build pipeline:
1. Finds CDK constructs via AGENTCORE_CDK_PATH, sibling dir, or clones latest from GitHub
2. Installs and builds CDK constructs
3. Installs and builds CLI (auto-bundles CDK)
4. Runs npm pack to produce the final tarball

* refactor: make CDK bundling non-intrusive to default build/deploy flow

The bundle script (npm run bundle) is now purely additive:
- Normal build: no CDK tarball in dist/assets, no behavior change
- Bundle build: CDK tarball placed in dist/assets/bundled-agentcore-cdk.tgz
- CDKRenderer checks for bundled tarball after npm install and overrides
  the registry version only if present

Reverts changes to copy-assets.mjs, vended package.json template, and
snapshot to their original state.

* feat: add timestamp-based versioning to bundle output

Both CLI and CDK tarballs get a unique e2e.<timestamp> version suffix.
Original versions are restored after packing so source files stay clean.

* chore: remove e2e prefix from bundle version tag

* fix: copy bundled CDK tarball locally before npm install

Copies the tarball into the CDK project dir and installs from
./bundled-agentcore-cdk.tgz instead of an absolute path. This avoids
npm writing ugly deep relative paths into package.json. The tarball
is cleaned up after install.

* fix: keep bundled CDK tarball in project for stable file: reference

Keep bundled-agentcore-cdk.tgz in the CDK project dir so the file:
reference in package.json stays valid for future npm install runs.

* fix: crash-safe version restore and explicit git pull branch

- Wrap npm pack calls in try/finally so package.json versions are
  always restored even if packing fails
- Use git pull origin main instead of bare git pull

* Potential fix for code scanning alert no. 22: Shell command built from environment values

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

* fix: update remaining run() calls to use execFileSync signature

The Copilot autofix changed run() from execSync(string) to
execFileSync(cmd, args[]), but only updated the git calls.
The 6 npm calls still used the old signature and would fail at runtime.

---------

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Author: jesseturner21

.gitignore

@@ -64,3 +64,6 @@ ProtocolTesting/
 
 # Git worktrees
 .worktrees/
+
+# Auto-cloned CDK constructs (from scripts/bundle.mjs)
+.cdk-constructs-clone/

package.json

@@ -68,7 +68,8 @@
     "test:unit": "vitest run --project unit --coverage",
     "test:e2e": "vitest run --project e2e",
     "test:update-snapshots": "vitest run --project unit --update",
-    "test:tui": "npm run build:harness && vitest run --project tui"
+    "test:tui": "npm run build:harness && vitest run --project tui",
+    "bundle": "node scripts/bundle.mjs"
   },
   "dependencies": {
     "@aws-cdk/toolkit-lib": "^1.16.0",

scripts/bundle.mjs

@@ -0,0 +1,162 @@
+/**
+ * bundle.mjs — Single command to build CLI + CDK constructs into one tarball.
+ *
+ * This is a testing-only workflow. It does NOT modify the default build or
+ * deployment flow. The normal `npm run build` + `npm pack` pipeline is unchanged.
+ *
+ * What this script does differently: after building both packages normally, it
+ * packs the CDK constructs into a tarball and places it in the CLI's dist/assets/.
+ * At `agentcore create` time, CDKRenderer detects this tarball and installs it
+ * after the normal `npm install`, overriding the registry version.
+ *
+ * Usage:
+ *   node scripts/bundle.mjs
+ *   npm run bundle
+ *
+ * Environment variables:
+ *   AGENTCORE_CDK_PATH — absolute path to the agentcore-l3-cdk-constructs repo
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const cliRoot = path.resolve(__dirname, '..');
+
+const CDK_REPO_URL = 'https://github.com/aws/agentcore-l3-cdk-constructs.git';
+
+function log(msg) {
+  console.log(`\n[bundle] ${msg}`);
+}
+
+function run(cmd, args = [], opts = {}) {
+  const display = [cmd, ...args].join(' ');
+  console.log(`  > ${display}`);
+  execFileSync(cmd, args, { stdio: 'inherit', ...opts });
+}
+
+/**
+ * Resolve the CDK constructs repo path. Priority:
+ * 1. AGENTCORE_CDK_PATH env var
+ * 2. Sibling directory ../agentcore-l3-cdk-constructs
+ * 3. Clone from GitHub into a temp directory under the CLI repo
+ */
+function resolveCdkPath() {
+  // 1. Env var
+  if (process.env.AGENTCORE_CDK_PATH) {
+    const p = path.resolve(process.env.AGENTCORE_CDK_PATH);
+    if (fs.existsSync(path.join(p, 'package.json'))) {
+      log(`Using CDK constructs from AGENTCORE_CDK_PATH: ${p}`);
+      return p;
+    }
+    console.warn(`  WARNING: AGENTCORE_CDK_PATH=${p} does not contain package.json, ignoring.`);
+  }
+
+  // 2. Sibling directory
+  const sibling = path.resolve(cliRoot, '..', 'agentcore-l3-cdk-constructs');
+  if (fs.existsSync(path.join(sibling, 'package.json'))) {
+    log(`Using CDK constructs from sibling directory: ${sibling}`);
+    return sibling;
+  }
+
+  // 3. Clone latest from GitHub
+  const cloneDir = path.join(cliRoot, '.cdk-constructs-clone');
+  log(`CDK constructs repo not found locally. Cloning latest from GitHub...`);
+
+  if (fs.existsSync(cloneDir)) {
+    log('Pulling latest changes...');
+    run('git', ['pull', 'origin', 'main'], { cwd: cloneDir });
+  } else {
+    run('git', ['clone', '--depth', '1', CDK_REPO_URL, cloneDir]);
+  }
+
+  return cloneDir;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+log('Starting bundle process...');
+
+const timestamp = Math.floor(Date.now() / 1000);
+log(`Bundle timestamp: ${timestamp}`);
+
+// Helper to bump a package version with a unique e2e timestamp tag.
+// Saves the original version so it can be restored after packing.
+function bumpVersion(pkgDir) {
+  const pkgJsonPath = path.join(pkgDir, 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+  const originalVersion = pkg.version;
+  const baseVersion = originalVersion.split('-')[0];
+  pkg.version = `${baseVersion}-${timestamp}`;
+  fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + '\n');
+  log(`Bumped ${pkg.name} version: ${originalVersion} -> ${pkg.version}`);
+  return { pkgJsonPath, originalVersion, bumpedVersion: pkg.version };
+}
+
+function restoreVersion({ pkgJsonPath, originalVersion }) {
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+  pkg.version = originalVersion;
+  fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + '\n');
+}
+
+// Step 1: Resolve and build CDK constructs
+const cdkPath = resolveCdkPath();
+
+log('Installing CDK constructs dependencies...');
+run('npm', ['install'], { cwd: cdkPath });
+
+log('Building CDK constructs...');
+run('npm', ['run', 'build'], { cwd: cdkPath });
+
+// Step 2: Bump CDK version and pack into a tarball
+const cdkVersionInfo = bumpVersion(cdkPath);
+try {
+  log('Packing CDK constructs...');
+  run('npm', ['pack'], { cwd: cdkPath });
+} finally {
+  restoreVersion(cdkVersionInfo);
+}
+
+const cdkTarballName = `aws-agentcore-cdk-${cdkVersionInfo.bumpedVersion}.tgz`;
+const cdkTarballSrc = path.join(cdkPath, cdkTarballName);
+
+if (!fs.existsSync(cdkTarballSrc)) {
+  console.error(`ERROR: Expected CDK tarball at ${cdkTarballSrc} but not found.`);
+  process.exit(1);
+}
+
+// Step 3: Build CLI normally (no modifications to copy-assets)
+log('Installing CLI dependencies...');
+run('npm', ['install'], { cwd: cliRoot });
+
+log('Building CLI...');
+run('npm', ['run', 'build'], { cwd: cliRoot });
+
+// Step 4: Copy CDK tarball into dist/assets/ so CDKRenderer can detect it
+const bundledTarballDest = path.join(cliRoot, 'dist', 'assets', 'bundled-agentcore-cdk.tgz');
+fs.copyFileSync(cdkTarballSrc, bundledTarballDest);
+log(`Placed CDK tarball at ${bundledTarballDest}`);
+
+// Step 5: Bump CLI version and pack into final tarball (includes the bundled CDK tarball)
+const cliVersionInfo = bumpVersion(cliRoot);
+try {
+  log('Packing CLI tarball...');
+  run('npm', ['pack'], { cwd: cliRoot });
+} finally {
+  restoreVersion(cliVersionInfo);
+}
+
+const cliTarballName = `aws-agentcore-${cliVersionInfo.bumpedVersion}.tgz`;
+const cliTarballPath = path.join(cliRoot, cliTarballName);
+
+if (fs.existsSync(cliTarballPath)) {
+  log(`Done! Tarball: ${cliTarballPath}`);
+  log(`Install with: npm install ${cliTarballPath}`);
+  log('When you run agentcore create, the bundled CDK constructs will be installed automatically.');
+} else {
+  log(`Done! Check ${cliRoot} for the .tgz file.`);
+}

src/cli/templates/CDKRenderer.ts

@@ -86,6 +86,10 @@ export class CDKRenderer {
     }
     logger?.logSubStep(`npm install completed (${(installDuration / 1000).toFixed(1)}s)`);
 
+    // If the CLI was built with a bundled CDK constructs tarball (via npm run bundle),
+    // install it to override the registry version. This is a no-op for normal builds.
+    await this.installBundledCdkIfPresent(outputDir, logger);
+
     // Format the CDK project files
     logger?.logSubStep('Running npm run format...');
     logger?.logCommand('npm', ['run', 'format']);
@@ -116,6 +120,39 @@ export class CDKRenderer {
     await fs.copyFile(readmeSrc, readmeDest);
   }
 
+  private async installBundledCdkIfPresent(cdkProjectDir: string, logger?: CreateLogger): Promise<void> {
+    const bundledTarball = path.join(this.assetsDir, 'bundled-agentcore-cdk.tgz');
+
+    try {
+      await fs.access(bundledTarball);
+    } catch {
+      // No bundled tarball — normal build, nothing to do
+      return;
+    }
+
+    // Copy tarball into the CDK project so npm resolves a clean local path
+    const localTarball = path.join(cdkProjectDir, 'bundled-agentcore-cdk.tgz');
+    await fs.copyFile(bundledTarball, localTarball);
+
+    logger?.logSubStep('Installing bundled @aws/agentcore-cdk override...');
+    const result = await runSubprocessCapture('npm', ['install', './bundled-agentcore-cdk.tgz'], {
+      cwd: cdkProjectDir,
+    });
+    if (result.stdout) {
+      logger?.logCommandOutput(result.stdout);
+    }
+    if (result.stderr) {
+      logger?.logCommandOutput(result.stderr);
+    }
+    if (result.code !== 0) {
+      throw new Error(`Failed to install bundled @aws/agentcore-cdk: ${result.stderr}`);
+    }
+
+    // Keep the tarball in the project so the file: reference in package.json
+    // stays valid for future npm install runs.
+    logger?.logSubStep('Bundled @aws/agentcore-cdk installed');
+  }
+
   private async writeLlmContext(configDir: string): Promise<void> {
     const llmContextDir = path.join(configDir, LLM_CONTEXT_DIR);
     await fs.mkdir(llmContextDir, { recursive: true });