refactor(errors): centralize custom errors (#1885)

Author: tejaskash

src/core/project/manager.test.ts

@@ -2,8 +2,8 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { mkdtemp, readdir, rm } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { tmpdir } from "node:os";
-import { FsProjectManager, NestedProjectError } from "./manager";
-import { ProjectFileExistsError } from "./tree";
+import { NestedProjectError, ProjectFileExistsError } from "../../errors";
+import { FsProjectManager } from "./manager";
 import { PROJECT_TEMPLATES } from "../../handlers/project/types";
 import { createSilentLogger } from "../../testing";
 

src/core/project/manager.tsx

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { AgentCoreCLIError, ERROR_SOURCE } from "../../errors";
+import { NestedProjectError } from "../../errors";
 import type {
   CreateProjectInput,
   ResolveProjectInput,
@@ -12,16 +12,6 @@ import { projectTree } from "./compose";
 import { defaultSource, type AssetSource } from "./source";
 import { writeTree } from "./tree";
 
-/** Thrown when scaffolding would nest a new project inside an existing AgentCore project. */
-export class NestedProjectError extends AgentCoreCLIError {
-  constructor(public readonly projectRoot: string) {
-    super(
-      `cannot create a project inside an existing AgentCore project (found ${join(projectRoot, "agentcore", "agentcore.json")})`,
-      { source: ERROR_SOURCE.USER, meta: { projectRoot } },
-    );
-  }
-}
-
 /** Walks up from directory looking for the agentcore/agentcore.json project marker. */
 function enclosingProjectRoot(directory: string): string | undefined {
   for (let current = directory; ; current = dirname(current)) {

src/core/project/source.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { EmbeddedAssetNotFoundError, EmbeddedAssetSource } from "./source";
+import { EmbeddedAssetNotFoundError } from "../../errors";
+import { EmbeddedAssetSource } from "./source";
 
 describe("EmbeddedAssetSource", () => {
   test("throws a modeled error when the asset is not embedded", () => {

src/core/project/source.ts

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { readFile, readdir } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { AgentCoreCLIError } from "../../errors";
+import { EmbeddedAssetNotFoundError } from "../../errors";
 
 /**
  * Reads and lists asset files by path relative to the asset root.
@@ -21,13 +21,6 @@ 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 };
 
-/** Thrown when an asset is missing from the compiled executable, indicating a packaging bug. */
-export class EmbeddedAssetNotFoundError extends AgentCoreCLIError {
-  constructor(public readonly assetPath: string) {
-    super(`Embedded asset not found: ${assetPath}`, { meta: { assetPath } });
-  }
-}
-
 /** Reads assets embedded in the compiled standalone executable. */
 export class EmbeddedAssetSource implements AssetSource {
   private blobs(): readonly NamedBlob[] {

src/core/project/tree.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { AgentCoreCLIError, ERROR_SOURCE } from "../../errors";
+import { ProjectFileExistsError } from "../../errors";
 import { atomicWrite } from "../../io";
 
 /**
@@ -34,16 +34,6 @@ export const file = (name: string, bytes: () => Promise<string>): FileNode => ({
   bytes,
 });
 
-/** Thrown when scaffolding would overwrite a file that already exists. */
-export class ProjectFileExistsError extends AgentCoreCLIError {
-  constructor(public readonly path: string) {
-    super(`Refusing to overwrite existing file: ${path}`, {
-      source: ERROR_SOURCE.USER,
-      meta: { path },
-    });
-  }
-}
-
 /**
  * Writes a project tree to the destination with atomic file writes.
  * Refuses to overwrite an existing file so a re-run fails loudly instead of clobbering user work.

src/errors/errors.tsx

@@ -1,4 +1,5 @@
 import { ServiceException } from "@smithy/core/client";
+import { join } from "node:path";
 import { ERROR_SOURCE, type ErrorSource } from "./types";
 
 export interface AgentCoreCLIErrorOptions extends ErrorOptions {
@@ -74,3 +75,70 @@ export class NotImplementedError extends AgentCoreCLIError {
     super(message ?? "not implemented yet", { ...options, source: ERROR_SOURCE.INTERNAL });
   }
 }
+
+/** Error raised when detecting an invalid environment */
+export class InvalidEnvironmentError extends AgentCoreCLIError {
+  constructor(message?: string, options?: Omit<AgentCoreCLIErrorOptions, "source">) {
+    super(message, { ...options, source: ERROR_SOURCE.USER });
+  }
+}
+
+export class SourceResolutionError extends InputValidationError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "SourceResolutionError";
+  }
+}
+
+// TODO: attach telemetry metadata to this error class.
+export class DeserializationError extends Error {
+  constructor(path: string, options?: { cause?: unknown }) {
+    super(`Failed to deserialize JSON at "${path}"`, options);
+    this.name = "DeserializationError";
+  }
+}
+
+/** Thrown when scaffolding would overwrite a file that already exists. */
+export class ProjectFileExistsError extends AgentCoreCLIError {
+  constructor(public readonly path: string) {
+    super(`Refusing to overwrite existing file: ${path}`, {
+      source: ERROR_SOURCE.USER,
+      meta: { path },
+    });
+  }
+}
+
+/** Thrown when scaffolding would nest a new project inside an existing AgentCore project. */
+export class NestedProjectError extends AgentCoreCLIError {
+  constructor(public readonly projectRoot: string) {
+    super(
+      `cannot create a project inside an existing AgentCore project (found ${join(projectRoot, "agentcore", "agentcore.json")})`,
+      { source: ERROR_SOURCE.USER, meta: { projectRoot } },
+    );
+  }
+}
+
+/** Thrown when an asset is missing from the compiled executable, indicating a packaging bug. */
+export class EmbeddedAssetNotFoundError extends AgentCoreCLIError {
+  constructor(public readonly assetPath: string) {
+    super(`Embedded asset not found: ${assetPath}`, { meta: { assetPath } });
+  }
+}
+
+export class RuntimeInvokeInterruptedError extends AgentCoreCLIError {
+  readonly reported: boolean;
+
+  constructor(cause?: unknown, reported = false) {
+    super("The operation was aborted", { cause, exitCode: 130 });
+    this.name = "AbortError";
+    this.reported = reported;
+  }
+}
+
+export class RuntimeInvokeResponseError extends AgentCoreCLIError {
+  readonly reported = true;
+
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause });
+  }
+}

src/errors/index.tsx

@@ -1,7 +1,15 @@
 export {
   AgentCoreCLIError,
+  DeserializationError,
+  EmbeddedAssetNotFoundError,
   InputValidationError,
+  InvalidEnvironmentError,
+  NestedProjectError,
   NotImplementedError,
+  ProjectFileExistsError,
+  RuntimeInvokeInterruptedError,
+  RuntimeInvokeResponseError,
+  SourceResolutionError,
   type AgentCoreCLIErrorOptions,
 } from "./errors";
 export { ERROR_SOURCE } from "./types";

src/handlers/runtime/invoke/errors.ts

@@ -1,12 +1,11 @@
 import z from "zod";
-import { InputValidationError } from "../../../errors";
+import { InputValidationError, RuntimeInvokeInterruptedError } from "../../../errors";
 import { createHandler, flag } from "../../../router";
 import type { AppIO } from "../../../io";
 import type { Core } from "../../types";
 import { coreOptsFromCtx } from "../../utils";
 import { JsonKey } from "../../keys";
 import { ExitCode } from "../../../runnable";
-import { RuntimeInvokeInterruptedError } from "./errors";
 import {
   normalizeRuntimeInvokeRequest,
   parseRuntimeInvokeHeaders,

src/handlers/runtime/invoke/index.tsx

@@ -1,8 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { Readable } from "node:stream";
 import type { GetAgentRuntimeResponse } from "@aws-sdk/client-bedrock-agentcore-control";
-import { InputValidationError } from "../../../errors";
-import { SourceResolutionError } from "../../../io";
+import { InputValidationError, SourceResolutionError } from "../../../errors";
 import {
   normalizeRuntimeInvokeRequest,
   parseRuntimeInvokeHeaders,