refactor(project): move build behind a project backend

src/core/project/backends/cdk.test.ts

@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { ProjectSpecSchema } from "../../../projectSchemas/project";
+import { createSilentLogger } from "../../../testing";
+import type { Project, ProjectEvent } from "../../../handlers/project/types";
+import { CdkBackend } from "./cdk";
+
+const tempDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    tempDirectories.splice(0).map((directory) => rm(directory, { recursive: true, force: true })),
+  );
+});
+
+async function project(withDependencies = true): Promise<Project> {
+  const rootPath = await mkdtemp(join(tmpdir(), "agentcore-cdk-backend-"));
+  tempDirectories.push(rootPath);
+  const cdkDir = join(rootPath, "agentcore", "cdk");
+  await mkdir(withDependencies ? join(cdkDir, "node_modules") : cdkDir, { recursive: true });
+  return {
+    name: "example",
+    rootPath,
+    spec: ProjectSpecSchema.parse({ name: "example", version: 1 }),
+  };
+}
+
+async function drain(generator: AsyncGenerator<ProjectEvent, void>): Promise<ProjectEvent[]> {
+  const events: ProjectEvent[] = [];
+  for await (const event of generator) events.push(event);
+  return events;
+}
+
+describe("CdkBackend.build", () => {
+  test("compiles and synthesizes through the generated CDK script", async () => {
+    const commands: { command: string[]; cwd: string }[] = [];
+    const subject = new CdkBackend({
+      logger: createSilentLogger(),
+      runner: async (command, { cwd }) => {
+        commands.push({ command, cwd });
+      },
+      checkTool: async () => {},
+    });
+    const input = await project();
+
+    expect(await drain(subject.build(input))).toEqual([
+      { message: "Synthesizing CloudFormation templates" },
+    ]);
+    expect(commands).toEqual([
+      {
+        command: ["npm", "run", "cdk", "--", "synth", "--quiet"],
+        cwd: join(input.rootPath, "agentcore", "cdk"),
+      },
+    ]);
+  });
+
+  test("fails actionably when CDK dependencies are missing", async () => {
+    const commands: string[][] = [];
+    const subject = new CdkBackend({
+      logger: createSilentLogger(),
+      runner: async (command) => {
+        commands.push(command);
+      },
+      checkTool: async () => {},
+    });
+
+    await expect(drain(subject.build(await project(false)))).rejects.toThrow(/npm install/);
+    expect(commands).toEqual([]);
+  });
+
+  test("propagates synthesis failures", async () => {
+    const subject = new CdkBackend({
+      logger: createSilentLogger(),
+      runner: async () => {
+        throw new Error("cdk synth exploded");
+      },
+      checkTool: async () => {},
+    });
+
+    await expect(drain(subject.build(await project()))).rejects.toThrow("cdk synth exploded");
+  });
+});

src/core/project/backends/cdk.ts

@@ -0,0 +1,44 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { ProjectStateError } from "../../../errors/errors";
+import type { Project, ProjectEvent } from "../../../handlers/project/types";
+import { requireTool, runProcess, type ProcessRunner } from "../../../io";
+import type { Logger } from "../../../logging";
+import type { ProjectBackend } from "./types";
+
+export type CdkBackendConfig = {
+  logger: Logger;
+  runner?: ProcessRunner;
+  checkTool?: typeof requireTool;
+};
+
+/** Builds projects through the CDK app scaffolded by `agentcore project create`. */
+export class CdkBackend implements ProjectBackend {
+  private readonly logger: Logger;
+  private readonly runner: ProcessRunner;
+  private readonly checkTool: typeof requireTool;
+
+  constructor(config: CdkBackendConfig) {
+    this.logger = config.logger;
+    this.runner = config.runner ?? runProcess;
+    this.checkTool = config.checkTool ?? requireTool;
+  }
+
+  public async *build(project: Project): AsyncGenerator<ProjectEvent, void> {
+    const cdkDir = join(project.rootPath, "agentcore", "cdk");
+
+    if (!existsSync(join(cdkDir, "node_modules"))) {
+      throw new ProjectStateError(
+        `CDK dependencies are missing for project '${project.name}'. ` +
+          `Run 'cd ${cdkDir} && npm install'.`,
+      );
+    }
+    await this.checkTool("npm", "Install Node.js: https://nodejs.org/");
+
+    yield { message: "Synthesizing CloudFormation templates" };
+    await this.runner(["npm", "run", "cdk", "--", "synth", "--quiet"], {
+      cwd: cdkDir,
+      onOutput: (chunk) => this.logger.debug(chunk),
+    });
+  }
+}

src/core/project/backends/types.ts

@@ -0,0 +1,6 @@
+import type { Project, ProjectEvent } from "../../../handlers/project/types";
+
+/** Builds the deployable artifacts owned by a project's selected backend. */
+export interface ProjectBackend {
+  build(project: Project): AsyncGenerator<ProjectEvent, void>;
+}

src/core/project/index.tsx

@@ -1 +1,3 @@
 export { FsProjectManager } from "./manager";
+export { CdkBackend, type CdkBackendConfig } from "./backends/cdk";
+export type { ProjectBackend } from "./backends/types";

src/core/project/manager.tsx

@@ -20,7 +20,7 @@ import {
 } from "../../io";
 import { defaultSource, type AssetSource } from "./source";
 import { createHarnessTreeFromSpec, createProjectTreeFromTemplate, TEMPLATES } from "./templates";
-import { ProjectSpecSchema } from "../../projectSchemas/project";
+import { ProjectSpecSchema, type ManagedBy } from "../../projectSchemas/project";
 import { enclosingProjectRoot } from "./fsUtils";
 import {
   AgentCoreCLIError,
@@ -30,13 +30,16 @@ import {
 } from "../../errors/errors";
 import type { HarnessSpecSchema } from "../../projectSchemas/harness";
 import z from "zod";
+import { CdkBackend } from "./backends/cdk";
+import type { ProjectBackend } from "./backends/types";
 
 type ProjectManagerConfig = {
   logger: Logger;
   source?: AssetSource; // Bun executable or dist/assets depending on runtime
   runner?: ProcessRunner; // injectable so tests never spawn real processes
   checkTool?: typeof requireTool; // injectable so tests don't depend on the host's PATH
   json?: ReadWriteJson; // injectable so tests read fixtures instead of disk
+  backends?: Partial<Record<ManagedBy, ProjectBackend>>;
 };
 
 /**
@@ -48,13 +51,21 @@ export class FsProjectManager implements ProjectManager {
   private readonly runner: ProcessRunner;
   private readonly checkTool: typeof requireTool;
   private readonly json: ReadWriteJson;
+  private readonly backends: Partial<Record<ManagedBy, ProjectBackend>>;
 
   constructor(config: ProjectManagerConfig) {
     this.logger = config.logger;
     this.source = config.source ?? defaultSource();
     this.runner = config.runner ?? runProcess;
     this.checkTool = config.checkTool ?? requireTool;
     this.json = config.json ?? new FsReadWriteJson({ logger: config.logger });
+    this.backends = config.backends ?? {
+      CDK: new CdkBackend({
+        logger: config.logger,
+        runner: config.runner,
+        checkTool: config.checkTool,
+      }),
+    };
   }
 
   public async resolve(input: ResolveProjectInput): Promise<Project | undefined> {
@@ -229,47 +240,17 @@ export class FsProjectManager implements ProjectManager {
   }
 
   public async *build(project: Project): AsyncGenerator<ProjectEvent, void> {
-    // agentcore.json records which backend owns the project's artifacts. CDK is the
-    // only one today; a terraform or no-IaC backend adds an arm here rather than
-    // editing the CDK path.
-    switch (project.spec.managedBy) {
-      case "CDK":
-        yield* this.buildWithCdk(project);
-        break;
-      default: {
-        // Exhaustiveness: a new ManagedBy member fails to compile until it is handled.
-        const unsupported: never = project.spec.managedBy;
-        throw new ProjectStateError(
-          `project '${project.name}' declares an unsupported backend: ${String(unsupported)}`,
-        );
-      }
-    }
+    yield* this.backendFor(project).build(project);
   }
 
-  // Compiles the generated CDK app and synthesizes its CloudFormation templates.
-  private async *buildWithCdk(project: Project): AsyncGenerator<ProjectEvent, void> {
-    const cdkDir = join(project.rootPath, "agentcore", "cdk");
-
-    // The generated CDK app is built from its own node_modules; without them the
-    // failure would otherwise surface as an opaque "cdk: not found".
-    if (!existsSync(join(cdkDir, "node_modules"))) {
+  private backendFor(project: Project): ProjectBackend {
+    const backend = this.backends[project.spec.managedBy];
+    if (!backend) {
       throw new ProjectStateError(
-        `CDK dependencies are missing for project '${project.name}'. ` +
-          `Run 'cd ${cdkDir} && npm install'.`,
+        `project '${project.name}' declares an unsupported backend: ${project.spec.managedBy}`,
       );
     }
-    await this.checkTool("npm", "Install Node.js: https://nodejs.org/");
-
-    // The generated package.json defines `cdk` as "npm run build && cdk", so this
-    // single command compiles the app and then synthesizes it. Synthesis needs no
-    // AWS credentials: each stack's environment comes from aws-targets.json.
-    //
-    // Build deliberately does not require a deployment target. A freshly created
-    // project has none, and building is how the user first typechecks their agent, so
-    // the generated app synthesizes one environment-agnostic stack when the list is
-    // empty. Only deploying somewhere needs a real target.
-    yield { message: "Synthesizing CloudFormation templates" };
-    await this.run(["npm", "run", "cdk", "--", "synth", "--quiet"], cdkDir);
+    return backend;
   }
 
   // Runs a command with its output streamed to the file logger.