feat(cli): introduce structured CliError with typed error codes and Sentry routing

packages/cli/cli-logger/src/logErrorMessage.ts

@@ -2,6 +2,8 @@ import { Logger, LogLevel } from "@fern-api/logger";
 import { TaskAbortSignal } from "@fern-api/task-context";
 import chalk from "chalk";
 
+const USE_NODE_18_OR_ABOVE_MESSAGE = "The Fern CLI requires Node 18+ or above.";
+
 export function logErrorMessage({
     message,
     error,
@@ -42,6 +44,10 @@ function convertErrorToString(error: unknown): string | undefined {
         return error;
     }
     if (error instanceof Error) {
+        if ((error as Error)?.message?.includes("globalThis")) {
+            return USE_NODE_18_OR_ABOVE_MESSAGE;
+        }
+
         return error.message;
     }
     return undefined;

packages/cli/cli-v2/src/__test__/compile.test.ts

@@ -1,10 +1,11 @@
 import { AbsoluteFilePath, doesPathExist } from "@fern-api/fs-utils";
+import { CliError } from "@fern-api/task-context";
+
 import { randomUUID } from "crypto";
 import { readFile, rm } from "fs/promises";
 import { join } from "path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { CompileCommand } from "../commands/api/compile/command.js";
-import { CliError } from "../errors/CliError.js";
 import { createTestContextWithCapture } from "./utils/createTestContext.js";
 
 const FIXTURES_DIR = AbsoluteFilePath.of(join(__dirname, "fixtures"));

packages/cli/cli-v2/src/auth/errors/KeyringUnavailableError.ts

@@ -1,12 +1,18 @@
+import { CliError } from "@fern-api/task-context";
+
 /**
  * Error thrown when the system keyring is unavailable.
  */
-export class KeyringUnavailableError extends Error {
+export class KeyringUnavailableError extends CliError {
     public readonly platform: NodeJS.Platform;
-    public readonly cause?: Error;
+    public override readonly cause?: Error;
 
     constructor(platform: NodeJS.Platform, cause?: Error) {
-        super(getKeyringErrorMessage(platform));
+        super({
+            message: getKeyringErrorMessage(platform),
+            code: CliError.Code.AuthError
+        });
+        Object.setPrototypeOf(this, KeyringUnavailableError.prototype);
         this.platform = platform;
         this.cause = cause;
     }

packages/cli/cli-v2/src/commands/api/check/command.ts

@@ -1,9 +1,10 @@
+import { CliError } from "@fern-api/task-context";
+
 import chalk from "chalk";
 import type { Argv } from "yargs";
 import { ApiChecker } from "../../../api/checker/ApiChecker.js";
 import type { Context } from "../../../context/Context.js";
 import type { GlobalArgs } from "../../../context/GlobalArgs.js";
-import { CliError } from "../../../errors/CliError.js";
 import { Icons } from "../../../ui/format.js";
 import { command } from "../../_internal/command.js";
 import { type JsonOutput, toJsonViolation } from "../../_internal/toJsonViolation.js";
@@ -26,7 +27,8 @@ export class CheckCommand {
         if (args.api != null && workspace.apis[args.api] == null) {
             const availableApis = Object.keys(workspace.apis).join(", ");
             throw new CliError({
-                message: `API '${args.api}' not found. Available APIs: ${availableApis}`
+                message: `API '${args.api}' not found. Available APIs: ${availableApis}`,
+                code: CliError.Code.ConfigError
             });
         }
 
@@ -43,7 +45,7 @@ export class CheckCommand {
             const response = this.buildJsonResponse({ apiCheckResult: result, hasErrors });
             context.stdout.info(JSON.stringify(response, null, 2));
             if (hasErrors) {
-                throw CliError.exit();
+                throw CliError.validationError();
             }
             return;
         }
@@ -56,7 +58,7 @@ export class CheckCommand {
         }
 
         if (hasErrors) {
-            throw CliError.exit();
+            throw CliError.validationError();
         }
 
         if (result.warningCount > 0) {

packages/cli/cli-v2/src/commands/api/compile/command.ts

@@ -1,5 +1,7 @@
 import { Audiences } from "@fern-api/configuration";
 import { streamObjectToFile } from "@fern-api/fs-utils";
+import { CliError } from "@fern-api/task-context";
+
 import chalk from "chalk";
 import { JsonStreamStringify } from "json-stream-stringify";
 import type { Argv } from "yargs";
@@ -8,7 +10,6 @@ import { IrCompiler } from "../../../api/compiler/IrCompiler.js";
 import type { ApiDefinition } from "../../../api/config/ApiDefinition.js";
 import type { Context } from "../../../context/Context.js";
 import type { GlobalArgs } from "../../../context/GlobalArgs.js";
-import { CliError } from "../../../errors/CliError.js";
 import { LANGUAGES } from "../../../sdk/config/Language.js";
 import type { Workspace } from "../../../workspace/Workspace.js";
 import { command } from "../../_internal/command.js";
@@ -67,7 +68,8 @@ export class CompileCommand {
             if (definition == null) {
                 const available = apiNames.join(", ");
                 throw new CliError({
-                    message: `API '${args.api}' not found. Available APIs: ${available}`
+                    message: `API '${args.api}' not found. Available APIs: ${available}`,
+                    code: CliError.Code.ConfigError
                 });
             }
             return { apiName: args.api, definition };
@@ -77,21 +79,24 @@ export class CompileCommand {
             const apiName = apiNames[0];
             if (apiName == null) {
                 throw new CliError({
-                    message: "Internal error; no APIs found in workspace"
+                    message: "Internal error; no APIs found in workspace",
+                    code: CliError.Code.InternalError
                 });
             }
             const definition = workspace.apis[apiName];
             if (definition == null) {
                 throw new CliError({
-                    message: `Internal error; API '${apiName}' not found in workspace`
+                    message: `Internal error; API '${apiName}' not found in workspace`,
+                    code: CliError.Code.InternalError
                 });
             }
             return { apiName, definition };
         }
 
         const available = apiNames.join(", ");
         throw new CliError({
-            message: `Multiple APIs found: ${available}. Use --api to select one.`
+            message: `Multiple APIs found: ${available}. Use --api to select one.`,
+            code: CliError.Code.ConfigError
         });
     }
 
@@ -112,7 +117,7 @@ export class CompileCommand {
                     `${violation.displayRelativeFilepath}:${violation.line}:${violation.column}: ${violation.message}`
                 );
             }
-            throw CliError.exit();
+            throw CliError.validationError(`API '${apiName}' has ${result.violations.length} validation errors`);
         }
     }
 

packages/cli/cli-v2/src/commands/api/merge/command.ts

@@ -1,4 +1,6 @@
 import { applyOpenAPIOverlay, mergeWithOverrides } from "@fern-api/core-utils";
+import { CliError } from "@fern-api/task-context";
+
 import chalk from "chalk";
 import { unlink, writeFile } from "fs/promises";
 import path from "path";
@@ -7,7 +9,6 @@ import { FERN_YML_FILENAME } from "../../../config/fern-yml/constants.js";
 import { FernYmlEditor } from "../../../config/fern-yml/FernYmlEditor.js";
 import type { Context } from "../../../context/Context.js";
 import type { GlobalArgs } from "../../../context/GlobalArgs.js";
-import { CliError } from "../../../errors/CliError.js";
 import { Icons } from "../../../ui/format.js";
 import { command } from "../../_internal/command.js";
 import { type OverlayDocument, toOverlay } from "../split/diffSpecs.js";
@@ -27,7 +28,7 @@ export class MergeCommand {
         const workspace = await context.loadWorkspaceOrThrow();
 
         if (Object.keys(workspace.apis).length === 0) {
-            throw new CliError({ message: "No APIs found in workspace." });
+            throw new CliError({ message: "No APIs found in workspace.", code: CliError.Code.ConfigError });
         }
 
         const entries = filterSpecs(workspace, { api: args.api });
@@ -42,7 +43,8 @@ export class MergeCommand {
             const fernYmlPath = workspace.absoluteFilePath;
             if (fernYmlPath == null) {
                 throw new CliError({
-                    message: `No ${FERN_YML_FILENAME} found. Run 'fern init' to initialize a project.`
+                    message: `No ${FERN_YML_FILENAME} found. Run 'fern init' to initialize a project.`,
+                    code: CliError.Code.ConfigError
                 });
             }
             editor = await FernYmlEditor.load({ fernYmlPath });

packages/cli/cli-v2/src/commands/api/split/command.ts

@@ -1,5 +1,6 @@
 import { extractErrorMessage, mergeWithOverrides } from "@fern-api/core-utils";
 import type { AbsoluteFilePath } from "@fern-api/fs-utils";
+import { CliError } from "@fern-api/task-context";
 import chalk from "chalk";
 import { execFile } from "child_process";
 import { readFile, writeFile } from "fs/promises";
@@ -10,7 +11,6 @@ import { FERN_YML_FILENAME } from "../../../config/fern-yml/constants.js";
 import { FernYmlEditor } from "../../../config/fern-yml/FernYmlEditor.js";
 import type { Context } from "../../../context/Context.js";
 import type { GlobalArgs } from "../../../context/GlobalArgs.js";
-import { CliError } from "../../../errors/CliError.js";
 import { Icons } from "../../../ui/format.js";
 import { command } from "../../_internal/command.js";
 import type { SpecEntry } from "../utils/filterSpecs.js";
@@ -46,7 +46,7 @@ export class SplitCommand {
         const workspace = await context.loadWorkspaceOrThrow();
 
         if (Object.keys(workspace.apis).length === 0) {
-            throw new CliError({ message: "No APIs found in workspace." });
+            throw new CliError({ message: "No APIs found in workspace.", code: CliError.Code.ConfigError });
         }
 
         const entries = filterSpecs(workspace, { api: args.api });
@@ -60,7 +60,8 @@ export class SplitCommand {
         const fernYmlPath = workspace.absoluteFilePath;
         if (fernYmlPath == null) {
             throw new CliError({
-                message: `No ${FERN_YML_FILENAME} found. Run 'fern init' to initialize a project.`
+                message: `No ${FERN_YML_FILENAME} found. Run 'fern init' to initialize a project.`,
+                code: CliError.Code.ConfigError
             });
         }
         const editor = await FernYmlEditor.load({ fernYmlPath });
@@ -240,7 +241,8 @@ export class SplitCommand {
         } catch (error: unknown) {
             const detail = extractErrorMessage(error);
             throw new CliError({
-                message: `Failed to get file from git HEAD: ${absolutePath}. Is the file tracked by git and has at least one commit?\n  Cause: ${detail}`
+                message: `Failed to get file from git HEAD: ${absolutePath}. Is the file tracked by git and has at least one commit?\n  Cause: ${detail}`,
+                code: CliError.Code.ParseError
             });
         }
     }
@@ -257,7 +259,10 @@ export class SplitCommand {
 function resolvePathOrThrow(context: Context, outputPath: string): AbsoluteFilePath {
     const resolved = context.resolveOutputFilePath(outputPath);
     if (resolved == null) {
-        throw new CliError({ message: `Could not resolve output path: ${outputPath}` });
+        throw new CliError({
+            message: `Could not resolve output path: ${outputPath}`,
+            code: CliError.Code.ConfigError
+        });
     }
     return resolved;
 }

packages/cli/cli-v2/src/commands/api/utils/loadSpec.ts

@@ -1,7 +1,8 @@
 import type { AbsoluteFilePath } from "@fern-api/fs-utils";
+import { CliError } from "@fern-api/task-context";
+
 import { readFile } from "fs/promises";
 import yaml from "js-yaml";
-import { CliError } from "../../../errors/CliError.js";
 import { isEnoentError } from "./isEnoentError.js";
 
 // biome-ignore lint/suspicious/noExplicitAny: OpenAPI specs can have any shape
@@ -17,9 +18,9 @@ export async function loadSpec(filepath: AbsoluteFilePath): Promise<Spec> {
         contents = await readFile(filepath, "utf8");
     } catch (error) {
         if (isEnoentError(error)) {
-            throw new CliError({ message: `File does not exist: ${filepath}` });
+            throw new CliError({ message: `File does not exist: ${filepath}`, code: CliError.Code.ConfigError });
         }
-        throw new CliError({ message: `Failed to read file: ${filepath}` });
+        throw new CliError({ message: `Failed to read file: ${filepath}`, code: CliError.Code.ParseError });
     }
     return parseSpec(contents, filepath);
 }
@@ -35,7 +36,10 @@ export function parseSpec(contents: string, filepath: string): Spec {
         try {
             return yaml.load(contents) as Spec;
         } catch {
-            throw new CliError({ message: `Failed to parse file as JSON or YAML: ${filepath}` });
+            throw new CliError({
+                message: `Failed to parse file as JSON or YAML: ${filepath}`,
+                code: CliError.Code.ParseError
+            });
         }
     }
 }

packages/cli/cli-v2/src/commands/auth/login/command.ts

@@ -1,13 +1,12 @@
 import { verifyAndDecodeJwt } from "@fern-api/auth";
 import { LogLevel } from "@fern-api/logger";
 import { type Auth0TokenResponse, getTokenFromAuth0 } from "@fern-api/login";
+import { CliError } from "@fern-api/task-context";
 import chalk from "chalk";
 import type { Argv } from "yargs";
-
 import { TaskContextAdapter } from "../../../context/adapter/TaskContextAdapter.js";
 import type { Context } from "../../../context/Context.js";
 import type { GlobalArgs } from "../../../context/GlobalArgs.js";
-import { CliError } from "../../../errors/CliError.js";
 import { Icons } from "../../../ui/format.js";
 import { command } from "../../_internal/command.js";
 
@@ -42,13 +41,13 @@ export class LoginCommand {
         const payload = await verifyAndDecodeJwt(idToken);
         if (payload == null) {
             context.stdout.error(`${Icons.error} Internal error; could not verify ID token`);
-            throw CliError.exit();
+            throw CliError.internalError();
         }
 
         const email = payload.email;
         if (email == null) {
             context.stdout.error(`${Icons.error} Internal error; ID token does not contain email claim`);
-            throw CliError.exit();
+            throw CliError.internalError();
         }
 
         const { isNew, totalAccounts } = await context.tokenService.login(email, accessToken);

packages/cli/cli-v2/src/commands/auth/logout/command.ts

@@ -1,11 +1,10 @@
+import { CliError } from "@fern-api/task-context";
 import chalk from "chalk";
 import inquirer from "inquirer";
 import type { Argv } from "yargs";
-
 import { TokenService } from "../../../auth/TokenService.js";
 import type { Context } from "../../../context/Context.js";
 import type { GlobalArgs } from "../../../context/GlobalArgs.js";
-import { CliError } from "../../../errors/CliError.js";
 import { Icons } from "../../../ui/format.js";
 import { command } from "../../_internal/command.js";
 
@@ -65,7 +64,7 @@ export class LogoutCommand {
 
         if (!context.isTTY) {
             context.stdout.error(`${Icons.error} Use --force to skip confirmation in non-interactive mode`);
-            throw CliError.exit();
+            throw new CliError({ code: CliError.Code.ValidationError });
         }
 
         const { confirmed } = await inquirer.prompt<{ confirmed: boolean }>([
@@ -91,7 +90,9 @@ export class LogoutCommand {
 
         if (!removed) {
             context.stdout.error(`${Icons.error} Account not found: ${user}`);
-            throw CliError.exit();
+            throw new CliError({
+                code: CliError.Code.EnvironmentError
+            });
         }
 
         context.stdout.info(`${Icons.success} Logged out of ${chalk.bold(user)}`);
@@ -106,7 +107,9 @@ export class LogoutCommand {
             context.stdout.error(
                 `${Icons.error} Multiple accounts found. Use --user or --all in non-interactive mode.`
             );
-            throw CliError.exit();
+            throw new CliError({
+                code: CliError.Code.EnvironmentError
+            });
         }
 
         const choices = accounts.map((account) => ({