refactor(errors): migrate input validation errors to use the modeled exception. (#1848)

* feat(errors): migrate input parsing errors to modeled validation errors

* fix(errors): swap router tests to check for error type instead of message

* fix(errors): migrate source resolver to use input validation

Author: Hweinstock

src/handlers/config/config.test.tsx

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { createRootHandler } from "../index";
 import { createSilentLogger, TestCoreClient, testIO } from "../../testing";
 import { DefaultGlobalConfigAccessor } from "../../globalConfig";
+import { InputValidationError } from "../../errors";
 import { FsReadWriteJson } from "../../io";
 
 describe("config", () => {
@@ -94,13 +95,11 @@ describe("config", () => {
   });
 
   test("throws on invalid key", async () => {
-    // TODO: swap to validation error.
-    await expect(run(["nonexistent.key"])).rejects.toThrow(TypeError);
+    await expect(run(["nonexistent.key"])).rejects.toThrow(InputValidationError);
   });
 
   test("throws on invalid value for key", async () => {
-    // TODO: swap to validation error
-    await expect(run(["telemetry.enabled", "banana"])).rejects.toThrow(TypeError);
+    await expect(run(["telemetry.enabled", "banana"])).rejects.toThrow(InputValidationError);
   });
 
   test("coerces values based on schema", async () => {

src/handlers/config/handler.tsx

@@ -1,6 +1,7 @@
 import z from "zod";
 import { createHandler, argument, GlobalConfigAccessorKey } from "../../router";
 import { JsonRendererKey } from "../../tui";
+import { InputValidationError } from "../../errors";
 import { DEFAULT_GLOBAL_CONFIG, type GlobalConfig } from "../../globalConfig";
 
 /*
@@ -63,16 +64,14 @@ function coerceValue(current: unknown, raw: string, path: string): unknown {
       const normalized = raw.trim().toLowerCase();
       if (normalized === "true") return true;
       if (normalized === "false") return false;
-      // TODO: mark as validation error.
-      throw new TypeError(`Cannot coerce "${raw}" to boolean at "${path}"`);
+      throw new InputValidationError(`Cannot coerce "${raw}" to boolean at "${path}"`);
     }
 
     case "number": {
       const trimmed = raw.trim();
       const n = Number(trimmed);
       if (trimmed === "" || Number.isNaN(n)) {
-        // TODO: mark as validation error.
-        throw new TypeError(`Cannot coerce "${raw}" to number at "${path}"`);
+        throw new InputValidationError(`Cannot coerce "${raw}" to number at "${path}"`);
       }
       return n;
     }
@@ -81,15 +80,14 @@ function coerceValue(current: unknown, raw: string, path: string): unknown {
       try {
         return JSON.parse(raw);
       } catch (e) {
-        // TODO: mark as validation error.
-
-        throw new TypeError(`Cannot coerce "${raw}" to object at "${path}"`, { cause: e });
+        throw new InputValidationError(`Cannot coerce "${raw}" to object at "${path}"`, {
+          cause: e,
+        });
       }
     }
 
     default:
-      // TODO: mark as validation error.
-      throw new TypeError(`Unsupported target type "${typeof current}" at "${path}"`);
+      throw new InputValidationError(`Unsupported target type "${typeof current}" at "${path}"`);
   }
 }
 /** Type guard that narrows `value` to a plain object record. */

src/handlers/harness/create/index.tsx

@@ -13,6 +13,7 @@ import { createHandler, flag } from "../../../router";
 import type { Core } from "../../types.tsx";
 import { coreOptsFromCtx, parseJsonFlag } from "../../utils.tsx";
 import { JsonRendererKey } from "../../../tui";
+import { InputValidationError } from "../../../errors";
 import { parameterHelp } from "../parameterHelp.tsx";
 
 export const createCreateHarnessHandler = (core: Core) =>
@@ -93,7 +94,7 @@ export const createCreateHarnessHandler = (core: Core) =>
       // Required at runtime but declared optional so that a bare
       // `harness create` falls through to the TUI middleware instead.
       if (!flags["name"]) {
-        throw new TypeError("required option '--name <name>' not specified");
+        throw new InputValidationError("required option '--name <name>' not specified");
       }
 
       const response = await core.harness.createHarness(

src/handlers/harness/delete/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../router";
 import type { Core } from "../../types.tsx";
 import { coreOptsFromCtx } from "../../utils.tsx";
 import { JsonRendererKey } from "../../../tui";
+import { InputValidationError } from "../../../errors";
 
 export const createDeleteHarnessHandler = (core: Core) =>
   createHandler({
@@ -21,7 +22,7 @@ export const createDeleteHarnessHandler = (core: Core) =>
       // Required at runtime but declared optional so that a bare
       // `harness delete` falls through to the TUI middleware instead.
       if (!flags["id"]) {
-        throw new TypeError("required option '--id <id>' not specified");
+        throw new InputValidationError("required option '--id <id>' not specified");
       }
 
       const response = await core.harness.deleteHarness(

src/handlers/harness/endpoint/create/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import type { Core } from "../../../types.tsx";
 import { coreOptsFromCtx, parseJsonFlag } from "../../../utils.tsx";
 import { JsonRendererKey } from "../../../../tui";
+import { InputValidationError } from "../../../../errors";
 
 export const createCreateEndpointHandler = (core: Core) =>
   createHandler({
@@ -23,10 +24,10 @@ export const createCreateEndpointHandler = (core: Core) =>
       // Required at runtime but declared optional so that a bare
       // `harness endpoint create` falls through to the TUI middleware instead.
       if (!flags["id"]) {
-        throw new TypeError("required option '--id <id>' not specified");
+        throw new InputValidationError("required option '--id <id>' not specified");
       }
       if (!flags["name"]) {
-        throw new TypeError("required option '--name <name>' not specified");
+        throw new InputValidationError("required option '--name <name>' not specified");
       }
 
       const response = await core.harness.createHarnessEndpoint(

src/handlers/harness/endpoint/delete/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import type { Core } from "../../../types.tsx";
 import { coreOptsFromCtx } from "../../../utils.tsx";
 import { JsonRendererKey } from "../../../../tui";
+import { InputValidationError } from "../../../../errors";
 
 export const createDeleteEndpointHandler = (core: Core) =>
   createHandler({
@@ -17,10 +18,10 @@ export const createDeleteEndpointHandler = (core: Core) =>
       // Required at runtime but declared optional so that a bare
       // `harness endpoint delete` falls through to the TUI middleware instead.
       if (!flags["id"]) {
-        throw new TypeError("required option '--id <id>' not specified");
+        throw new InputValidationError("required option '--id <id>' not specified");
       }
       if (!flags["qualifier"]) {
-        throw new TypeError("required option '--qualifier <qualifier>' not specified");
+        throw new InputValidationError("required option '--qualifier <qualifier>' not specified");
       }
 
       const response = await core.harness.deleteHarnessEndpoint(

src/handlers/harness/endpoint/get/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import type { Core } from "../../../types.tsx";
 import { coreOptsFromCtx } from "../../../utils.tsx";
 import { JsonRendererKey } from "../../../../tui";
+import { InputValidationError } from "../../../../errors";
 
 export const createGetEndpointHandler = (core: Core) =>
   createHandler({
@@ -14,10 +15,10 @@ export const createGetEndpointHandler = (core: Core) =>
     ],
     handle: async (ctx, flags) => {
       if (!flags["id"]) {
-        throw new TypeError("required option '--id <id>' not specified");
+        throw new InputValidationError("required option '--id <id>' not specified");
       }
       if (!flags["qualifier"]) {
-        throw new TypeError("required option '--qualifier <qualifier>' not specified");
+        throw new InputValidationError("required option '--qualifier <qualifier>' not specified");
       }
 
       const endpoint = await core.harness.getHarnessEndpoint(

src/handlers/harness/endpoint/list/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import type { Core } from "../../../types.tsx";
 import { coreOptsFromCtx } from "../../../utils.tsx";
 import { JsonRendererKey } from "../../../../tui";
+import { InputValidationError } from "../../../../errors";
 
 export const createListEndpointsHandler = (core: Core) =>
   createHandler({
@@ -15,7 +16,7 @@ export const createListEndpointsHandler = (core: Core) =>
     ],
     handle: async (ctx, flags) => {
       if (!flags["id"]) {
-        throw new TypeError("required option '--id <id>' not specified");
+        throw new InputValidationError("required option '--id <id>' not specified");
       }
 
       const endpoints = await core.harness.listHarnessEndpoints(

src/handlers/harness/endpoint/update/index.tsx

@@ -3,6 +3,7 @@ import { createHandler, flag } from "../../../../router";
 import type { Core } from "../../../types.tsx";
 import { coreOptsFromCtx } from "../../../utils.tsx";
 import { JsonRendererKey } from "../../../../tui";
+import { InputValidationError } from "../../../../errors";
 
 export const createUpdateEndpointHandler = (core: Core) =>
   createHandler({
@@ -18,10 +19,10 @@ export const createUpdateEndpointHandler = (core: Core) =>
       // Required at runtime but declared optional so that a bare
       // `harness endpoint update` falls through to the TUI middleware instead.
       if (!flags["id"]) {
-        throw new TypeError("required option '--id <id>' not specified");
+        throw new InputValidationError("required option '--id <id>' not specified");
       }
       if (!flags["qualifier"]) {
-        throw new TypeError("required option '--qualifier <qualifier>' not specified");
+        throw new InputValidationError("required option '--qualifier <qualifier>' not specified");
       }
 
       const response = await core.harness.updateHarnessEndpoint(

src/handlers/harness/exec/index.tsx

@@ -5,6 +5,7 @@ import type { Core } from "../../types.tsx";
 import { coreOptsFromCtx } from "../../utils.tsx";
 import { JsonKey } from "../../keys.tsx";
 import { JsonRendererKey, renderTuiAt } from "../../../tui";
+import { InputValidationError } from "../../../errors";
 import { applyExecEvent, finishExec, newExecItem } from "../invoke/transcript.tsx";
 
 export const createExecHarnessHandler = (core: Core, io: AppIO) =>
@@ -34,15 +35,15 @@ export const createExecHarnessHandler = (core: Core, io: AppIO) =>
       // Required at runtime but declared optional so that a bare `harness exec`
       // falls through to the TUI middleware instead.
       if (!flags["id"]) {
-        throw new TypeError("required option '--id <id>' not specified");
+        throw new InputValidationError("required option '--id <id>' not specified");
       }
       // Without a command, open the interactive exec screen at this harness —
       // resuming the given session and targeting the given qualifier when
       // passed. The one-shot CLI run below needs --command (and is the only
       // shape JSON mode supports).
       if (!flags["command"]) {
         if (ctx.require(JsonKey)) {
-          throw new TypeError("required option '--command <command>' not specified");
+          throw new InputValidationError("required option '--command <command>' not specified");
         }
         let path = `${ctx.require(PathKey)}/${flags["id"]}`;
         if (flags["session-id"]) path += `/${flags["session-id"]}`;