fix(project): ship the toolkit's bootstrap template with the artifacts

Bootstrap uploads a CloudFormation template that @aws-cdk/toolkit-lib
ships as a file in its own package directory and finds at runtime
relative to where that directory sits on disk. Bundling the package
rewrote that lookup to the build machine's absolute path, so a released
build reached a node_modules that only exists on the machine that built
it: the npm bundle failed with ENOENT on the template, and the compiled
executables, which have no node_modules at all, failed the same way.
Nothing read that template until someone bootstrapped an account, so
every build check passed.

The bundle keeps the package external, as the pre-refactor CLI's esbuild
config did, so node resolves a real @aws-cdk/toolkit-lib -- it is a
declared runtime dependency, so installing the CLI installs it. That
also returns the bundle to its previous size (32.8 MB back to 6.4 MB)
and warm `agentcore --help` to ~0.5s, since the lazy import no longer
has a second CDK toolchain inlined behind it to parse.

A compiled executable cannot have externals, so the build embeds the
template as an asset and bootstrap is pointed at a copy written out for
it, in the one mode where the toolkit cannot find its own. The template
is read from the installed package rather than vendored here, so it
always matches the toolkit being compiled in, and compile fails if the
package stops shipping it or if the executable does not carry its bytes
-- the check the missing template needed and did not have.

Verified on the artifacts: with the toolkit's own template moved aside,
the executable bootstraps to the first AWS call, while the bundle under
node fails on exactly the ENOENT above.

Author: notgitika

scripts/build.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { $ } from "bun";
+import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { runWithExitCode } from "../src/runnable";
 
@@ -11,6 +12,16 @@ const DIST = join(REPO_ROOT, "dist");
 
 const ASSET_NAMING = "agentcore-assets/[dir]/[name].[ext]";
 
+// Kept out of the bundle so the toolkit stays a real directory in node_modules at
+// runtime: it reads its bootstrap template from its own package directory, which a
+// bundle would rewrite to this machine's absolute path. The npm package declares it
+// as a dependency, so installing the CLI installs it.
+const EXTERNAL = ["@aws-cdk/toolkit-lib"];
+
+// A compiled executable has no node_modules, so the template the toolkit would read
+// from its package directory is embedded instead. See loadBootstrapTemplate.
+const BOOTSTRAP_TEMPLATE = ["lib", "api", "bootstrap", "bootstrap-template.yaml"];
+
 // Shrink whitespace/syntax but keep identifiers: minified names make stack
 // traces unreadable and erase error names telemetry keys on.
 const MINIFY = { whitespace: true, syntax: true, identifiers: false } as const;
@@ -26,14 +37,54 @@ function assetLoaderPlugin(): Bun.BunPlugin {
   return {
     name: "asset-file-loader",
     setup(build) {
-      build.onLoad({ filter: /src[/\\]assets[/\\]/ }, async ({ path }) => ({
-        contents: await Bun.file(path).bytes(),
-        loader: "file",
-      }));
+      build.onLoad(
+        { filter: /src[/\\]assets[/\\]|bootstrap-template\.yaml$/ },
+        async ({ path }) => ({
+          contents: await Bun.file(path).bytes(),
+          loader: "file",
+        }),
+      );
     },
   };
 }
 
+/**
+ * Absolute path of the toolkit's own bootstrap template.
+ *
+ * Resolved from the installed package rather than a copy in this repo, so the
+ * embedded template is always the one the toolkit being compiled in expects.
+ */
+function bootstrapTemplate(): string {
+  const manifest = Bun.resolveSync("@aws-cdk/toolkit-lib/package.json", REPO_ROOT);
+  const template = join(resolve(manifest, ".."), ...BOOTSTRAP_TEMPLATE);
+  if (!existsSync(template)) {
+    throw new Error(
+      `@aws-cdk/toolkit-lib no longer ships ${BOOTSTRAP_TEMPLATE.join("/")}; ` +
+        `bootstrap in a compiled executable reads the embedded copy, so this must be found. Looked in ${template}`,
+    );
+  }
+  return template;
+}
+
+/**
+ * Fail loudly unless the compiled executable carries the bootstrap template's bytes.
+ *
+ * Nothing reads that template until someone bootstraps an AWS account, so an
+ * executable that lost it looks healthy in every build check and fails in a user's
+ * first deploy instead.
+ */
+async function assertTemplateIsEmbedded(outfile: string, template: string): Promise<void> {
+  const [executable, bytes] = await Promise.all([
+    Bun.file(outfile).bytes(),
+    Bun.file(template).bytes(),
+  ]);
+  if (!Buffer.from(executable).includes(bytes)) {
+    throw new Error(
+      `${outfile} does not carry ${BOOTSTRAP_TEMPLATE.join("/")}, so bootstrap would fail wherever it runs`,
+    );
+  }
+}
+
 /** Fail loudly on a non-UTF-8 asset — the source reads every asset as text. */
 async function assertAssetsAreText(assets: string[]): Promise<void> {
   const decoder = new TextDecoder("utf-8", { fatal: true });
@@ -54,6 +105,7 @@ async function bundle(): Promise<void> {
     outdir: DIST,
     target: "node",
     minify: MINIFY,
+    external: EXTERNAL,
   });
 
   // Mirror assets beside the emitted module for resolveAssetsRoot().
@@ -70,15 +122,19 @@ async function compile(target: string): Promise<void> {
   const outfile = join(DIST, "bin", `agentcore-${target.replace(/^bun-/, "")}`);
   await $`mkdir -p ${join(DIST, "bin")}`;
 
+  const template = bootstrapTemplate();
   await Bun.build({
-    entrypoints: [ENTRYPOINT, ...assets],
+    entrypoints: [ENTRYPOINT, ...assets, template],
     compile: { target: target as Bun.Build.CompileTarget, outfile },
     minify: MINIFY,
     root: REPO_ROOT,
     naming: { asset: ASSET_NAMING },
     plugins: [assetLoaderPlugin()],
   });
-  console.log(`Compiled ${target} → ${outfile} (${assets.length} assets embedded)`);
+  await assertTemplateIsEmbedded(outfile, template);
+  console.log(
+    `Compiled ${target} → ${outfile} (${assets.length} assets embedded, plus the bootstrap template)`,
+  );
 }
 
 process.exit(

src/io/cdk.test.ts

@@ -1,13 +1,14 @@
 import { test, expect, describe } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import type { IIoHost, IoMessage, IoRequest } from "@aws-cdk/toolkit-lib";
 // The real toolkit package, so the arguments these tests assert on are the values
 // the toolkit itself defines rather than ones the tests made up. Imported statically
 // here, unlike in cdk.ts, because a test file pays no startup cost.
 import * as toolkit from "@aws-cdk/toolkit-lib";
 import {
+  loadBootstrapTemplate,
   loadCdkToolkit,
   performCdkOperation,
   runCdk,
@@ -24,6 +25,15 @@ function message(level: string, text: string): IoMessage<unknown> {
 
 const lib: CdkToolkitLib = toolkit;
 
+// What a compiled executable holds: the toolkit's template, under the name the
+// build's asset naming gives it, beside the assets it also embeds.
+function embedded(text: string): (Blob & { name: string })[] {
+  return [
+    new File(["unrelated"], "agentcore-assets/src/assets/cdk/cdk.json"),
+    new File([text], "agentcore-assets/lib/api/bootstrap/bootstrap-template.yaml"),
+  ];
+}
+
 async function collect(generator: AsyncGenerator<CdkEvent, void>): Promise<CdkEvent[]> {
   const events: CdkEvent[] = [];
   for await (const event of generator) events.push(event);
@@ -128,6 +138,10 @@ describe("performCdkOperation", () => {
       { assemblyDirectory: "/unused", region: "us-east-1" },
     );
 
+    // Nothing is embedded when running from source, so the toolkit reads its own
+    // template rather than one written out for it.
+    expect(calls[0]!.args[1]).not.toHaveProperty("source");
+
     expect(calls.map(({ method }) => method)).toEqual(["bootstrap"]);
     const [environments, options] = calls[0]!.args as [
       { getEnvironments: () => Promise<{ name: string; account: string; region: string }[]> },
@@ -141,6 +155,52 @@ describe("performCdkOperation", () => {
     expect(options.parameters.parameters).toEqual({ createCustomerMasterKey: true });
   });
 
+  test("bootstraps a compiled executable from the template it has embedded", async () => {
+    // The released-binary path: no node_modules, so the toolkit cannot find its own
+    // template and is handed the embedded copy instead.
+    let templateFile: string | undefined;
+    let uploaded: string | undefined;
+    const toolkit = {
+      bootstrap: async (_environments: unknown, options: { source?: { templateFile: string } }) => {
+        templateFile = options.source?.templateFile;
+        // Read here rather than after: the file lives only for the operation.
+        uploaded = await Bun.file(templateFile!).text();
+      },
+    } as unknown as CdkToolkit;
+
+    await performCdkOperation(
+      { lib, toolkit },
+      { kind: "bootstrap", environments: ["aws://111122223333/us-east-1"] },
+      { assemblyDirectory: "/unused", region: "us-east-1" },
+      embedded("Resources: {}"),
+    );
+
+    expect(uploaded).toBe("Resources: {}");
+    // Cleaned up, so a long-lived process bootstrapping repeatedly leaves nothing behind.
+    expect(await Bun.file(templateFile!).exists()).toBe(false);
+  });
+
+  test("removes the template it wrote out even when bootstrap fails", async () => {
+    let templateFile: string | undefined;
+    const toolkit = {
+      bootstrap: async (_environments: unknown, options: { source?: { templateFile: string } }) => {
+        templateFile = options.source?.templateFile;
+        throw new Error("bootstrap stack rollback complete");
+      },
+    } as unknown as CdkToolkit;
+
+    await expect(
+      performCdkOperation(
+        { lib, toolkit },
+        { kind: "bootstrap", environments: ["aws://111122223333/us-east-1"] },
+        { assemblyDirectory: "/unused", region: "us-east-1" },
+        embedded("Resources: {}"),
+      ),
+    ).rejects.toThrow(/rollback complete/);
+
+    expect(await Bun.file(templateFile!).exists()).toBe(false);
+  });
+
   test("deploys only the named stack, from the assembly build synthesized", async () => {
     const { toolkit, calls } = stubToolkit();
 
@@ -175,6 +235,23 @@ describe("performCdkOperation", () => {
   });
 });
 
+describe("loadBootstrapTemplate", () => {
+  test("writes the embedded template where the toolkit can read it", async () => {
+    const path = await loadBootstrapTemplate(embedded("Resources: {}"));
+
+    // A path, not bytes: the toolkit takes a template file to upload.
+    expect(path).toBeString();
+    expect(await Bun.file(path!).text()).toBe("Resources: {}");
+    await rm(dirname(path!), { recursive: true, force: true });
+  });
+
+  test("reports no template when nothing is embedded", async () => {
+    // Running from source or the bundle, where the toolkit package is a real
+    // directory on disk and finds its own template.
+    expect(await loadBootstrapTemplate([])).toBeUndefined();
+  });
+});
+
 describe("loadCdkToolkit", () => {
   test("builds a toolkit without needing credentials", async () => {
     // Constructing the toolkit resolves no credentials and calls no API, which is

src/io/cdk.ts

@@ -1,6 +1,9 @@
 // Programmatic CDK operations via @aws-cdk/toolkit-lib. Deploy drives the toolkit
 // in-process rather than shelling out to `npx cdk`, so its progress arrives as
 // structured messages and its failures as typed errors instead of scraped stdout.
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
 import type { IIoHost, IoMessageLevel, Toolkit } from "@aws-cdk/toolkit-lib";
 
 /** A message emitted by the toolkit while an operation runs. */
@@ -47,15 +50,52 @@ export type CdkToolkit = Pick<Toolkit, "bootstrap" | "fromAssemblyDirectory" | "
 /** The parts of the toolkit package an operation needs, loaded on demand. */
 export type CdkToolkitLib = Pick<
   typeof import("@aws-cdk/toolkit-lib"),
-  "BootstrapEnvironments" | "BootstrapStackParameters" | "StackSelectionStrategy"
+  | "BootstrapEnvironments"
+  | "BootstrapSource"
+  | "BootstrapStackParameters"
+  | "StackSelectionStrategy"
 >;
 
+/** An embedded file, whose name Bun's types widen away on Bun.embeddedFiles. */
+type NamedBlob = Blob & { readonly name: string };
+
+const BOOTSTRAP_TEMPLATE = "bootstrap-template.yaml";
+
+/** The files compiled into this executable, or none when running from source or a bundle. */
+function embeddedFiles(): readonly NamedBlob[] {
+  return typeof Bun === "undefined" ? [] : (Bun.embeddedFiles as readonly NamedBlob[]);
+}
+
+/**
+ * Writes the embedded bootstrap template to a file the toolkit can read, or returns
+ * undefined when it should read its own.
+ *
+ * Bootstrap uploads a CloudFormation template that the toolkit ships as a file in its
+ * package directory, found at runtime relative to where that package sits on disk. A
+ * compiled executable has no node_modules, and the path it was compiled with belongs
+ * to the build machine, so the build embeds the template and bootstrap is pointed at
+ * a copy of it. Everywhere else the package is a real directory and finds its own.
+ */
+export async function loadBootstrapTemplate(
+  files: readonly NamedBlob[] = embeddedFiles(),
+): Promise<string | undefined> {
+  const template = files.find((file) => file.name.endsWith(BOOTSTRAP_TEMPLATE));
+  if (!template) return undefined;
+
+  const directory = await mkdtemp(join(tmpdir(), "agentcore-bootstrap-"));
+  const path = join(directory, BOOTSTRAP_TEMPLATE);
+  await writeFile(path, await template.text());
+  return path;
+}
+
 /**
  * Loads the toolkit package and builds a toolkit that reports to `ioHost`.
  *
  * Loaded here rather than imported at module scope: the toolkit is the heaviest
  * dependency in the CLI and `src/io` is reachable from every command, so a static
  * import would make even `agentcore --help` pay to load a deploy it is not doing.
+ * The bundle keeps the package external, so a command that never deploys never
+ * reads it; a compiled executable has it inlined and pays only to parse it.
  */
 export async function loadCdkToolkit(
   ioHost: IIoHost,
@@ -72,18 +112,30 @@ export async function loadCdkToolkit(
   return { lib, toolkit };
 }
 
-/** Performs one operation, awaiting the toolkit call it maps to. */
+/**
+ * Performs one operation, awaiting the toolkit call it maps to.
+ *
+ * `files` is what this executable has embedded, taken as an argument so a test can
+ * exercise the compiled executable's bootstrap path without being one.
+ */
 export async function performCdkOperation(
   { lib, toolkit }: { lib: CdkToolkitLib; toolkit: CdkToolkit },
   operation: CdkOperation,
   options: CdkRunOptions,
+  files: readonly NamedBlob[] = embeddedFiles(),
 ): Promise<void> {
   if (operation.kind === "bootstrap") {
-    await toolkit.bootstrap(lib.BootstrapEnvironments.fromList(operation.environments), {
-      // Provisions a customer-managed KMS key for the staging bucket, matching
-      // the parameters the original CLI bootstraps with.
-      parameters: lib.BootstrapStackParameters.withExisting({ createCustomerMasterKey: true }),
-    });
+    const template = await loadBootstrapTemplate(files);
+    try {
+      await toolkit.bootstrap(lib.BootstrapEnvironments.fromList(operation.environments), {
+        // Provisions a customer-managed KMS key for the staging bucket, matching
+        // the parameters the original CLI bootstraps with.
+        parameters: lib.BootstrapStackParameters.withExisting({ createCustomerMasterKey: true }),
+        ...(template && { source: lib.BootstrapSource.customTemplate(template) }),
+      });
+    } finally {
+      if (template) await rm(dirname(template), { recursive: true, force: true });
+    }
     return;
   }