refactor(project): align scaffolding with codebase conventions

Address review feedback:
- AssetSource implementations are now classes (EmbeddedAssetSource,
  FsAssetSource) matching how interfaces are implemented elsewhere
- TemplateSpec, Template, DirNode, and FileNode are types since they model
  concrete data, not extendable behavior
- ProjectFileExistsError extends AgentCoreCLIError with a user error source
  so it participates in error classification and exit codes
- atomicWrite moved from src/fs into the shared src/io module

Author: tejaskash

src/core/project/source.test.ts

@@ -1,8 +1,10 @@
 import { describe, expect, test } from "bun:test";
-import { embeddedSource } from "./source";
+import { EmbeddedAssetSource } from "./source";
 
-describe("embeddedSource", () => {
+describe("EmbeddedAssetSource", () => {
   test("throws when the asset is not embedded", () => {
-    expect(embeddedSource.read("cdk/package.json")).rejects.toThrow(/Embedded asset not found/);
+    expect(new EmbeddedAssetSource().read("cdk/package.json")).rejects.toThrow(
+      /Embedded asset not found/,
+    );
   });
 });

src/core/project/source.ts

@@ -8,9 +8,9 @@ import { fileURLToPath } from "node:url";
  * This is the one place that knows whether assets come from disk or from the compiled executable.
  */
 export interface AssetSource {
-  /** Reads the text of the asset at `assetPath`. */
+  /** Reads the text of the asset at assetPath. */
   read(assetPath: string): Promise<string>;
-  /** Lists asset paths of every file under `assetDir`, sorted, recursively. */
+  /** Lists asset paths of every file under assetDir, sorted, recursively. */
   list(assetDir: string): Promise<string[]>;
 }
 
@@ -20,41 +20,47 @@ const EMBEDDED_PREFIX = "agentcore-assets/src/assets/";
 // Embedded files carry a name property that Bun's types widen to Blob.
 type NamedBlob = Blob & { readonly name: string };
 
-const embeddedBlobs = () => Bun.embeddedFiles as readonly NamedBlob[];
-
 /** Reads assets embedded in the compiled standalone executable. */
-export const embeddedSource: AssetSource = {
-  async read(assetPath) {
+export class EmbeddedAssetSource implements AssetSource {
+  private blobs(): readonly NamedBlob[] {
+    return Bun.embeddedFiles as readonly NamedBlob[];
+  }
+
+  public async read(assetPath: string): Promise<string> {
     const name = `${EMBEDDED_PREFIX}${assetPath}`;
-    const blob = embeddedBlobs().find((f) => f.name === name);
+    const blob = this.blobs().find((f) => f.name === name);
     if (!blob) {
       throw new Error(`Embedded asset not found: ${assetPath}`);
     }
     return blob.text();
-  },
-  async list(assetDir) {
+  }
+
+  public async list(assetDir: string): Promise<string[]> {
     const prefix = `${EMBEDDED_PREFIX}${assetDir}/`;
-    return embeddedBlobs()
+    return this.blobs()
       .filter((f) => f.name.startsWith(prefix))
       .map((f) => f.name.slice(EMBEDDED_PREFIX.length))
       .sort();
-  },
-};
+  }
+}
 
 /** Reads assets from the assets directory on disk. */
-export function fileSource(assetsRoot = resolveAssetsRoot()): AssetSource {
-  return {
-    read: (assetPath) => readFile(join(assetsRoot, assetPath), "utf8"),
-    async list(assetDir) {
-      const root = join(assetsRoot, assetDir);
-      const entries = await readdir(root, { recursive: true, withFileTypes: true });
-      return entries
-        .filter((entry) => entry.isFile())
-        .map((entry) => join(assetDir, relative(root, join(entry.parentPath, entry.name))))
-        .map((p) => p.replaceAll("\\", "/"))
-        .sort();
-    },
-  };
+export class FsAssetSource implements AssetSource {
+  constructor(private readonly assetsRoot: string = resolveAssetsRoot()) {}
+
+  public read(assetPath: string): Promise<string> {
+    return readFile(join(this.assetsRoot, assetPath), "utf8");
+  }
+
+  public async list(assetDir: string): Promise<string[]> {
+    const root = join(this.assetsRoot, assetDir);
+    const entries = await readdir(root, { recursive: true, withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isFile())
+      .map((entry) => join(assetDir, relative(root, join(entry.parentPath, entry.name))))
+      .map((p) => p.replaceAll("\\", "/"))
+      .sort();
+  }
 }
 
 // Bundled builds place assets beside the emitted module and the source layout keeps them two levels up.
@@ -72,5 +78,5 @@ function resolveAssetsRoot(moduleDirectory = dirname(fileURLToPath(import.meta.u
  */
 export function defaultSource(): AssetSource {
   const embedded = typeof Bun !== "undefined" && Bun.embeddedFiles.length > 0;
-  return embedded ? embeddedSource : fileSource();
+  return embedded ? new EmbeddedAssetSource() : new FsAssetSource();
 }

src/core/project/templates.ts

@@ -1,23 +1,23 @@
 import { PROJECT_TEMPLATES, type ProjectTemplate } from "../../handlers/project/types";
 
-interface TemplateSpec {
+type TemplateSpec = {
   runtimes?: unknown[];
   memories?: unknown[];
   harnesses?: unknown[];
-}
+};
 
 /**
  * A project template pairs the agent code scaffolded under app/ with the resource
  * sections it registers in agentcore.json. Adding a template is one entry here plus its assets.
  */
-interface Template {
+type Template = {
   /** Directory under app/ the template code is written to. */
   appDir: string;
   /** Asset directory relative to the asset root, expanded into the app directory. */
   assetDir: string;
   /** Resource sections this template contributes to agentcore.json. */
   spec: TemplateSpec;
-}
+};
 
 export const TEMPLATES: Record<ProjectTemplate, Template> = {
   [PROJECT_TEMPLATES.HELLO_WORLD_PYTHON]: {

src/core/project/tree.ts

@@ -1,25 +1,26 @@
 import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { atomicWrite } from "../../fs";
+import { AgentCoreCLIError, ERROR_SOURCE } from "../../errors";
+import { atomicWrite } from "../../io";
 
 /**
  * A node in a project's file tree where directories nest and files are leaves.
  * File bytes come from a thunk so the tree never knows where the bytes originate.
  */
 export type ProjectNode = DirNode | FileNode;
 
-export interface DirNode {
+export type DirNode = {
   kind: "dir";
   name: string;
   children: ProjectNode[];
-}
+};
 
-export interface FileNode {
+export type FileNode = {
   kind: "file";
   name: string;
   bytes: () => Promise<string>;
-}
+};
 
 export const dir = (name: string, children: ProjectNode[]): DirNode => ({
   kind: "dir",
@@ -34,10 +35,12 @@ export const file = (name: string, bytes: () => Promise<string>): FileNode => ({
 });
 
 /** Thrown when scaffolding would overwrite a file that already exists. */
-export class ProjectFileExistsError extends Error {
+export class ProjectFileExistsError extends AgentCoreCLIError {
   constructor(public readonly path: string) {
-    super(`Refusing to overwrite existing file: ${path}`);
-    this.name = "ProjectFileExistsError";
+    super(`Refusing to overwrite existing file: ${path}`, {
+      source: ERROR_SOURCE.USER,
+      meta: { path },
+    });
   }
 }
 

src/fs/index.ts

@@ -1,3 +1,4 @@
+export { atomicWrite } from "./atomicWrite";
 export { FsReadWriteJson } from "./json";
 export { SourceResolutionError, SourceResolver, type SourceResolverConfig } from "./source";
 export type { AppIO, ReadWriteJson } from "./types";