refactor(project): load the CDK toolkit lazily and test the adapter

The toolkit is the heaviest dependency in the CLI and src/io/index.ts
re-exports runCdk, so a static import made every command load it:
agentcore --help ran in 2.7s from source, 0.7s once the import moved
inside the function that builds the toolkit. The compiled binary is
unchanged either way, since --compile embeds the module regardless.

src/io/cdk.ts splits into the three things a run does -- load the
toolkit, perform one operation with it, bridge its reporting to a
generator -- so each is reachable from a test. src/io/cdk.test.ts covers
them against the real toolkit package: constructing a Toolkit and its
BootstrapEnvironments, BootstrapStackParameters, and
StackSelectionStrategy helpers resolves no credentials and calls no API,
so the arguments a deploy passes are asserted against the values the
toolkit itself defines rather than stand-ins. What the tests assert
includes the ones a caller cannot see and a fake cannot check: that
messages are yielded while the operation is still running, that a
failure surfaces only after the output explaining it, that a request is
answered with its suggested default rather than prompting, and that
createCustomerMasterKey and PATTERN_MUST_MATCH reach the toolkit.

The fake in TestCoreClient still buffers rather than streams; it now
says so, and names the test that covers the real behaviour.

ProjectEvent becomes a discriminated union. It documented that exactly
one of step and output is set while typing both optional, which allowed
{} and both-at-once and spread `if (event.output)` checks through three
handlers. Both variants carry `message`, so a consumer that only writes
text needs no switch, and those checks are gone.

Author: notgitika

src/core/project/manager.test.ts

@@ -273,7 +273,7 @@ describe("FsProjectManager.build", () => {
         cwd: cdkDir,
       },
     ]);
-    expect(events).toEqual([{ message: "Synthesizing CloudFormation templates" }]);
+    expect(events).toEqual([{ kind: "step", message: "Synthesizing CloudFormation templates" }]);
   });
 
   test("fails actionably when the CDK dependencies are missing", async () => {
@@ -444,6 +444,11 @@ describe("FsProjectManager.deploy", () => {
     return events;
   }
 
+  // The toolkit's own messages, as opposed to the steps this CLI words itself.
+  function forwarded(events: ProjectEvent[]): string[] {
+    return events.filter((event) => event.kind === "output").map((event) => event.message);
+  }
+
   test("synthesizes, bootstraps the target environment, then deploys its stack", async () => {
     const directory = await inTempDirectory();
     const { manager: subject, commands, runs } = deployManager();
@@ -463,9 +468,9 @@ describe("FsProjectManager.deploy", () => {
       { operation: { kind: "deploy", stackName: stackName("default") }, options },
     ]);
     expect(events).toEqual([
-      { message: "Synthesizing CloudFormation templates" },
-      { message: "Bootstrapping aws://111122223333/us-east-1" },
-      { message: `Deploying ${stackName("default")}` },
+      { kind: "step", message: "Synthesizing CloudFormation templates" },
+      { kind: "step", message: "Bootstrapping aws://111122223333/us-east-1" },
+      { kind: "step", message: `Deploying ${stackName("default")}` },
     ]);
   });
 
@@ -554,6 +559,20 @@ describe("FsProjectManager.deploy", () => {
     expect(runs).toEqual([]);
   });
 
+  test("names the path it looked in when synthesis wrote no assembly", async () => {
+    const directory = await inTempDirectory();
+    const { manager: subject, runs } = deployManager();
+    const project = await scaffolded(subject, directory);
+    // Synthesis is stubbed in these tests, so removing the stand-in manifest is what
+    // a real synth writing somewhere else entirely would leave behind.
+    await rm(join(assemblyDirectory(directory), "manifest.json"));
+
+    await expect(
+      drain(subject.deploy(project, { region: REGION, skipBootstrap: false, target: "default" })),
+    ).rejects.toThrow(/No synthesized cloud assembly was found at .*manifest\.json/);
+    expect(runs).toEqual([]);
+  });
+
   test("skips bootstrapping when asked, and still deploys", async () => {
     const directory = await inTempDirectory();
     const { manager: subject, commands, runs } = deployManager();
@@ -569,7 +588,10 @@ describe("FsProjectManager.deploy", () => {
     expect(runs.map(({ operation }) => operation)).toEqual([
       { kind: "deploy", stackName: stackName("default") },
     ]);
-    expect(events).not.toContainEqual({ message: "Bootstrapping aws://111122223333/us-east-1" });
+    expect(events).not.toContainEqual({
+      kind: "step",
+      message: "Bootstrapping aws://111122223333/us-east-1",
+    });
   });
 
   test("names the file to fix when no deployment targets are configured", async () => {
@@ -622,7 +644,7 @@ describe("FsProjectManager.deploy", () => {
       subject.deploy(project, { region: REGION, skipBootstrap: true, target: "default" }),
     );
 
-    expect(events.map((event) => event.output).filter(Boolean)).toEqual([
+    expect(forwarded(events)).toEqual([
       "example-stack: creating CloudFormation changeset...",
       "example-stack: deployed",
     ]);
@@ -643,9 +665,7 @@ describe("FsProjectManager.deploy", () => {
     );
 
     // The suppressed ones are still in the debug log; only the warning is surfaced.
-    expect(events.map((event) => event.output).filter(Boolean)).toEqual([
-      "example-stack: no changes",
-    ]);
+    expect(forwarded(events)).toEqual(["example-stack: no changes"]);
   });
 
   test("yields the output that explains a failure before propagating it", async () => {
@@ -668,7 +688,7 @@ describe("FsProjectManager.deploy", () => {
         for await (const event of generator) events.push(event);
       })(),
     ).rejects.toThrow("cdk deploy exploded");
-    expect(events).toContainEqual({ output: "example-stack: CREATE_FAILED" });
+    expect(events).toContainEqual({ kind: "output", message: "example-stack: CREATE_FAILED" });
   });
 
   test("refuses a project managed by a backend it cannot deploy", async () => {

src/core/project/manager.tsx

@@ -103,15 +103,15 @@ export class FsProjectManager implements ProjectManager {
     const destination = join(process.cwd(), input.name);
     this.logger.debug(`scaffolding project "${input.name}" from template "${input.template}"`);
 
-    yield { message: "Creating project tree" };
+    yield { kind: "step", message: "Creating project tree" };
     const tree = await createProjectTreeFromTemplate(input.name, input.template, this.source);
     await tree.write(destination);
 
     // A failed step leaves the scaffolded files in place; the error tells the
     // user how to rerun the step by hand.
     if (!input.skipInstall) {
       await this.checkTool("npm", "Install Node.js: https://nodejs.org/");
-      yield { message: "Installing CDK dependencies with npm" };
+      yield { kind: "step", message: "Installing CDK dependencies with npm" };
       await this.run(["npm", "install"], join(destination, "agentcore", "cdk"));
 
       const appDir = join(destination, "app", TEMPLATES[input.template].appDir);
@@ -120,14 +120,14 @@ export class FsProjectManager implements ProjectManager {
           "uv",
           "Install uv: https://docs.astral.sh/uv/getting-started/installation/",
         );
-        yield { message: "Syncing Python dependencies with uv" };
+        yield { kind: "step", message: "Syncing Python dependencies with uv" };
         await this.run(["uv", "sync"], appDir);
       }
     }
 
     if (!input.skipGit) {
       await this.checkTool("git", "Install git: https://git-scm.com/downloads");
-      yield { message: "Initializing git repository" };
+      yield { kind: "step", message: "Initializing git repository" };
       await this.run(["git", "init"], destination);
     }
 
@@ -192,7 +192,7 @@ export class FsProjectManager implements ProjectManager {
     // reads this directory back. A project that sets cdk.json's `output` would
     // otherwise send synth somewhere deploy never looks, and deploy would ship
     // whatever stale assembly it found there while reporting success.
-    yield { message: "Synthesizing CloudFormation templates" };
+    yield { kind: "step", message: "Synthesizing CloudFormation templates" };
     await this.run(
       ["npm", "run", "cdk", "--", "synth", "--quiet", "--output", this.assemblyPath(project)],
       cdkDir,
@@ -279,11 +279,11 @@ export class FsProjectManager implements ProjectManager {
       // environment, so it runs every deploy rather than probing CloudFormation
       // first.
       const environment = `aws://${target.account}/${target.region}`;
-      yield { message: `Bootstrapping ${environment}` };
+      yield { kind: "step", message: `Bootstrapping ${environment}` };
       yield* this.streamCdk({ kind: "bootstrap", environments: [environment] }, run);
     }
 
-    yield { message: `Deploying ${stackName}` };
+    yield { kind: "step", message: `Deploying ${stackName}` };
     yield* this.streamCdk({ kind: "deploy", stackName }, run);
   }
 
@@ -296,7 +296,7 @@ export class FsProjectManager implements ProjectManager {
     for await (const event of this.cdk(operation, options)) {
       this.logger.debug(event.message);
       if (event.level === "debug" || event.level === "trace") continue;
-      yield { output: event.message };
+      yield { kind: "output", message: event.message };
     }
   }
 

src/handlers/project/build/index.ts

@@ -18,9 +18,7 @@ export const createBuildProjectHandler = (config: BuildProjectHandlerConfig) =>
       // Progress goes to stderr, keeping stdout for machine output. Subprocess
       // output goes to the debug log; on failure ProcessFailedError carries it.
       for await (const event of config.projectManager.build(project)) {
-        if (event.message) {
-          config.io.stderr.write(`${event.message}\n`);
-        }
+        config.io.stderr.write(`${event.message}\n`);
       }
 
       config.io.stderr.write(`Built project '${project.name}'\n`);

src/handlers/project/create/index.ts

@@ -35,9 +35,7 @@ export const createCreateProjectHandler = (config: CreateProjectHandlerConfig) =
         skipInstall: flags["skip-install"],
         skipGit: flags["skip-git"],
       })) {
-        if (event.message) {
-          config.io.stderr.write(`${event.message}\n`);
-        }
+        config.io.stderr.write(`${event.message}\n`);
       }
 
       config.io.stderr.write(`Created project '${flags["name"]}' in ./${flags["name"]}\n`);

src/handlers/project/deploy/index.ts

@@ -36,12 +36,7 @@ export const createDeployProjectHandler = (config: DeployProjectHandlerConfig) =
         skipBootstrap: flags["skip-bootstrap"],
         target: flags.target,
       })) {
-        if (event.message) {
-          config.io.stderr.write(`${event.message}\n`);
-        }
-        if (event.output) {
-          config.io.stderr.write(`${event.output}\n`);
-        }
+        config.io.stderr.write(`${event.message}\n`);
       }
 
       config.io.stderr.write(`Deployed project '${project.name}'\n`);

src/handlers/project/types.ts

@@ -33,14 +33,17 @@ export type CreateProjectInput = {
 };
 
 /**
- * A progress step reported while a long-running project operation runs, or a line
- * of output from the tool it drives. One of the two is set per event: a step is
- * this CLI's own wording, while output is forwarded as the tool phrased it.
+ * Something worth showing the user while a long-running project operation runs.
+ *
+ * A union rather than two optional fields, so an event is always exactly one of the
+ * two and a consumer that only writes text can read `message` without checking
+ * which it got.
  */
-export type ProjectEvent = {
-  message?: string;
-  output?: string;
-};
+export type ProjectEvent =
+  /** A progress step, in this CLI's own wording. */
+  | { kind: "step"; message: string }
+  /** A line of output, forwarded as the tool that produced it phrased it. */
+  | { kind: "output"; message: string };
 
 export type DeployProjectOptions = {
   /** The resolved AWS region, forwarded to the CDK subprocesses. */