@fern-api/fern-api-dev 4.82.0 → 4.83.0

package/cli.cjs

@@ -469477,8 +469477,7 @@ var CliError = class _CliError extends Error {
     NetworkError: "NETWORK_ERROR",
     AuthError: "AUTH_ERROR",
     ConfigError: "CONFIG_ERROR",
-    UserError: "USER_ERROR",
-    Unclassified: "UNCLASSIFIED"
+    UserError: "USER_ERROR"
   };
 })(CliError || (CliError = {}));
 var SENTRY_REPORTABLE = {
@@ -469494,8 +469493,7 @@ var SENTRY_REPORTABLE = {
   [CliError.Code.NetworkError]: false,
   [CliError.Code.AuthError]: false,
   [CliError.Code.ConfigError]: false,
-  [CliError.Code.UserError]: false,
-  [CliError.Code.Unclassified]: false
+  [CliError.Code.UserError]: false
 };
 function shouldReportToSentry(code5) {
   return SENTRY_REPORTABLE[code5];
@@ -469519,7 +469517,7 @@ function resolveErrorCode(error50, explicitCode) {
   if (isNodeVersionError(error50)) {
     return CliError.Code.EnvironmentError;
   }
-  return CliError.Code.Unclassified;
+  return CliError.Code.InternalError;
 }
 
 // ../logger/lib/LogLevel.js
@@ -486637,7 +486635,7 @@ async function checkVersionDoesNotAlreadyExist({ version: version7, packageName,
   }
   if (exists2) {
     if (isPublishMode) {
-      context3.failAndThrow(`Version ${version7} of ${resolvedPackageName} already exists on the ${getRegistryName(language)} registry. Please use a different version number. If you want to automatically increment the version, omit the --version flag.`);
+      context3.failAndThrow(`Version ${version7} of ${resolvedPackageName} already exists on the ${getRegistryName(language)} registry. Please use a different version number. If you want to automatically increment the version, omit the --version flag.`, void 0, { code: CliError.Code.VersionError });
     } else {
       context3.logger.warn(`Version ${version7} of ${resolvedPackageName} already exists on the ${getRegistryName(language)} registry. If your CI pipeline publishes this version, it may fail.`);
     }
@@ -518575,13 +518573,13 @@ function convertToHttpMethod(httpMethod) {
     delete: () => schemas_exports2.HttpMethodSchema.Delete,
     head: () => schemas_exports2.HttpMethodSchema.Head,
     options: () => {
-      throw new Error("OPTIONS is unsupported");
+      throw new CliError({ message: "OPTIONS is unsupported", code: CliError.Code.ConfigError });
     },
     trace: () => {
-      throw new Error("TRACE is unsupported");
+      throw new CliError({ message: "TRACE is unsupported", code: CliError.Code.ConfigError });
     },
     _other: () => {
-      throw new Error("Unknown http method is unsupported");
+      throw new CliError({ message: "Unknown http method is unsupported", code: CliError.Code.ConfigError });
     }
   });
 }
@@ -518815,7 +518813,10 @@ function buildEndpoint({ endpoint: endpoint3, declarationFile, context: context3
         };
       },
       _other: () => {
-        throw new Error("Unrecognized Response type: " + endpoint3.response?.type);
+        throw new CliError({
+          message: "Unrecognized Response type: " + endpoint3.response?.type,
+          code: CliError.Code.InternalError
+        });
       }
     });
   }
@@ -519345,7 +519346,10 @@ function getUnresolvedEndpointLocation(endpoint3) {
     }
   }
   if (fileParts.length >= operationIdTokens.length) {
-    throw new Error(`Cannot get file for endpoint ${JSON.stringify(endpoint3)}`);
+    throw new CliError({
+      message: `Cannot get file for endpoint ${JSON.stringify(endpoint3)}`,
+      code: CliError.Code.InternalError
+    });
   }
   return {
     file: RelativeFilePath.of(camelCase_default(fileParts.join("_")) + ".yml"),
@@ -519587,7 +519591,10 @@ function buildWebhooks(context3) {
           };
         },
         _other: () => {
-          throw new Error("Unrecognized Response type: " + webhook.response?.type);
+          throw new CliError({
+            message: "Unrecognized Response type: " + webhook.response?.type,
+            code: CliError.Code.InternalError
+          });
         }
       });
     }
@@ -520179,7 +520186,10 @@ var FernDefinitionDirectory = class _FernDefinitionDirectory {
     }
     const [directory, ...remainingPath] = pathParts;
     if (directory == null) {
-      throw new Error(`Internal error; cannot add file with path: ${pathParts}`);
+      throw new CliError({
+        message: `Internal error; cannot add file with path: ${pathParts}`,
+        code: CliError.Code.InternalError
+      });
     }
     if (!this.directories[directory]) {
       this.directories[directory] = new _FernDefinitionDirectory();
@@ -562872,7 +562882,10 @@ var ValidNavigationRule = {
           }
           const expectedItems = directoryToChildren[dirname6(relativeFilepath)];
           if (expectedItems == null) {
-            throw new Error(`Could not find expected contents of ${relativeFilepath}`);
+            throw new CliError({
+              message: `Could not find expected contents of ${relativeFilepath}`,
+              code: CliError.Code.InternalError
+            });
           }
           const violations = [];
           const seen = /* @__PURE__ */ new Set();
@@ -564116,7 +564129,10 @@ var ValidPaginationRule = {
               pathPagination: endpointPagination
             });
           }
-          throw new Error("Invalid pagination schema");
+          throw new CliError({
+            message: "Invalid pagination schema",
+            code: CliError.Code.ValidationError
+          });
         }
       }
     };
@@ -566549,7 +566565,10 @@ var ConjureImporter = class extends APIDefinitionImporter {
       if (definition3.services == null || Object.keys(definition3.services ?? {}).length === 0) {
         const fernFilePath = this.conjureFilepathToFernFilepath[filepath];
         if (fernFilePath == null) {
-          throw new Error(`Failed to find corresponding fern filepath for conjure file ${filepath}`);
+          throw new CliError({
+            message: `Failed to find corresponding fern filepath for conjure file ${filepath}`,
+            code: CliError.Code.InternalError
+          });
         }
         for (const [import_, importedFilepath] of Object.entries(definition3.types?.conjureImports ?? {})) {
           const fernFileToImport = this.getFernFileToImport({
@@ -566611,7 +566630,10 @@ var ConjureImporter = class extends APIDefinitionImporter {
             for (const pathParameter of endpointLocator.pathParameters) {
               const pathParameterType = endpointDeclaration.args[pathParameter];
               if (pathParameterType == null) {
-                throw new Error(`Failed to find path parameter ${pathParameter} in ${endpointDeclaration.http}`);
+                throw new CliError({
+                  message: `Failed to find path parameter ${pathParameter} in ${endpointDeclaration.http}`,
+                  code: CliError.Code.InternalError
+                });
               }
               pathParameters[pathParameter] = typeof pathParameterType === "string" ? pathParameterType : (
                 // biome-ignore lint/suspicious/noExplicitAny: allow explicit any
@@ -566747,7 +566769,10 @@ var ConjureImporter = class extends APIDefinitionImporter {
     const relativeFilePathToImportedFile = relativize(absoluteFilePathToConjureFolder, absoluteFilePathToImportedFile);
     const correspondingFernFilePath = this.conjureFilepathToFernFilepath[relativeFilePathToImportedFile];
     if (correspondingFernFilePath == null) {
-      throw new Error(`Failed to find corresponding fern filepath for conjure file ${relativeFilePathToImportedFile}`);
+      throw new CliError({
+        message: `Failed to find corresponding fern filepath for conjure file ${relativeFilePathToImportedFile}`,
+        code: CliError.Code.InternalError
+      });
     }
     return correspondingFernFilePath;
   }
@@ -581884,7 +581909,9 @@ function getPathToLocalStorageDependency(dependency) {
 }
 async function validateLocalDependencyAndGetDefinition({ dependency, context: context3, cliVersion, settings, loadAPIWorkspace: loadAPIWorkspace2 }) {
   if (loadAPIWorkspace2 == null) {
-    context3.failWithoutThrowing("Failed to load api definition");
+    context3.failWithoutThrowing("Failed to load api definition", void 0, {
+      code: CliError.Code.ResolutionError
+    });
     return void 0;
   }
   context3.logger.info("Parsing...");
@@ -581895,7 +581922,9 @@ async function validateLocalDependencyAndGetDefinition({ dependency, context: co
     workspaceName: void 0
   });
   if (!loadDependencyWorkspaceResult.didSucceed) {
-    context3.failWithoutThrowing("Failed to load api definition", loadDependencyWorkspaceResult.failures);
+    context3.failWithoutThrowing("Failed to load api definition", loadDependencyWorkspaceResult.failures, {
+      code: CliError.Code.ResolutionError
+    });
     return void 0;
   }
   context3.logger.info("Modifying source filepath ...");
@@ -581917,16 +581946,24 @@ async function validateVersionedDependencyAndGetDefinition({ dependency, context
     if (!response.ok) {
       response.error._visit({
         orgDoesNotExistError: () => {
-          context3.failWithoutThrowing("Organization does not exist");
+          context3.failWithoutThrowing("Organization does not exist", void 0, {
+            code: CliError.Code.ResolutionError
+          });
         },
         apiDoesNotExistError: () => {
-          context3.failWithoutThrowing("API does not exist");
+          context3.failWithoutThrowing("API does not exist", void 0, {
+            code: CliError.Code.ResolutionError
+          });
         },
         versionDoesNotExistError: () => {
-          context3.failWithoutThrowing("Version does not exist");
+          context3.failWithoutThrowing("Version does not exist", void 0, {
+            code: CliError.Code.ResolutionError
+          });
         },
         _other: (error50) => {
-          context3.failWithoutThrowing("Failed to download API manifest", error50);
+          context3.failWithoutThrowing("Failed to download API manifest", error50, {
+            code: CliError.Code.NetworkError
+          });
         }
       });
       return void 0;
@@ -581936,14 +581973,14 @@ async function validateVersionedDependencyAndGetDefinition({ dependency, context
     const parsedCliVersionOfDependency = parseVersion(response.body.cliVersion);
     if (parsedYamlVersionOfDependency != null) {
       if (parsedYamlVersionOfDependency > YAML_SCHEMA_VERSION) {
-        context3.failWithoutThrowing(`${dependency.organization}/${dependency.apiName}@${dependency.version} on a higher version of fern. Upgrade this workspace to ${response.body.cliVersion}`);
+        context3.failWithoutThrowing(`${dependency.organization}/${dependency.apiName}@${dependency.version} on a higher version of fern. Upgrade this workspace to ${response.body.cliVersion}`, void 0, { code: CliError.Code.VersionError });
         return void 0;
       } else if (parsedYamlVersionOfDependency < YAML_SCHEMA_VERSION) {
-        context3.failWithoutThrowing(`${dependency.organization}/${dependency.apiName}@${dependency.version} on a lower version of fern. Upgrade it to ${cliVersion}`);
+        context3.failWithoutThrowing(`${dependency.organization}/${dependency.apiName}@${dependency.version} on a lower version of fern. Upgrade it to ${cliVersion}`, void 0, { code: CliError.Code.VersionError });
         return void 0;
       }
     } else if (parsedCliVersion.major !== parsedCliVersionOfDependency.major || parsedCliVersion.minor !== parsedCliVersionOfDependency.minor) {
-      context3.failWithoutThrowing(`CLI version is ${response.body.cliVersion}. Expected ${parsedCliVersion.major}.${parsedCliVersion.minor}.x (to match current workspace).`);
+      context3.failWithoutThrowing(`CLI version is ${response.body.cliVersion}. Expected ${parsedCliVersion.major}.${parsedCliVersion.minor}.x (to match current workspace).`, void 0, { code: CliError.Code.VersionError });
       return void 0;
     }
     context3.logger.info("Downloading...");
@@ -581955,7 +581992,9 @@ async function validateVersionedDependencyAndGetDefinition({ dependency, context
         absolutePathToLocalOutput: pathToDefinition
       });
     } catch (error50) {
-      context3.failWithoutThrowing("Failed to download API", error50);
+      context3.failWithoutThrowing("Failed to download API", error50, {
+        code: CliError.Code.NetworkError
+      });
       return void 0;
     }
     metadata = response.body;
@@ -581965,7 +582004,9 @@ async function validateVersionedDependencyAndGetDefinition({ dependency, context
   }
   context3.logger.info("Parsing...");
   if (loadAPIWorkspace2 == null) {
-    context3.failWithoutThrowing("Failed to load API");
+    context3.failWithoutThrowing("Failed to load API", void 0, {
+      code: CliError.Code.ResolutionError
+    });
     return void 0;
   }
   const loadDependencyWorkspaceResult = await loadAPIWorkspace2({
@@ -581975,12 +582016,14 @@ async function validateVersionedDependencyAndGetDefinition({ dependency, context
     workspaceName: void 0
   });
   if (!loadDependencyWorkspaceResult.didSucceed) {
-    context3.failWithoutThrowing("Failed to parse dependency after downloading", loadDependencyWorkspaceResult.failures);
+    context3.failWithoutThrowing("Failed to parse dependency after downloading", loadDependencyWorkspaceResult.failures, { code: CliError.Code.ParseError });
     return void 0;
   }
   const workspaceOfDependency = loadDependencyWorkspaceResult.workspace;
   if (workspaceOfDependency.type === "oss") {
-    context3.failWithoutThrowing("Dependency must be a fern workspace.");
+    context3.failWithoutThrowing("Dependency must be a fern workspace.", void 0, {
+      code: CliError.Code.ConfigError
+    });
     return void 0;
   }
   return await loadDependencyWorkspaceResult.workspace.getDefinition({ context: context3 }, settings);
@@ -592520,7 +592563,9 @@ var LazyFernWorkspace = class extends AbstractAPIWorkspace {
       const parseResult = await parseYamlFiles(yamlFiles);
       if (!parseResult.didSucceed) {
         handleFailedWorkspaceParserResultRaw(parseResult.failures, defaultedContext.logger);
-        return defaultedContext.failAndThrow();
+        return defaultedContext.failAndThrow(void 0, void 0, {
+          code: CliError.Code.ValidationError
+        });
       }
       const structuralValidationResult = validateStructureOfYamlFiles({
         files: parseResult.files,
@@ -592529,7 +592574,9 @@ var LazyFernWorkspace = class extends AbstractAPIWorkspace {
       });
       if (!structuralValidationResult.didSucceed) {
         handleFailedWorkspaceParserResultRaw(structuralValidationResult.failures, defaultedContext.logger);
-        return defaultedContext.failAndThrow();
+        return defaultedContext.failAndThrow(void 0, void 0, {
+          code: CliError.Code.ValidationError
+        });
       }
       const processPackageMarkersResult = await processPackageMarkers({
         dependenciesConfiguration,
@@ -592541,7 +592588,9 @@ var LazyFernWorkspace = class extends AbstractAPIWorkspace {
       });
       if (!processPackageMarkersResult.didSucceed) {
         handleFailedWorkspaceParserResultRaw(processPackageMarkersResult.failures, defaultedContext.logger);
-        return defaultedContext.failAndThrow();
+        return defaultedContext.failAndThrow(void 0, void 0, {
+          code: CliError.Code.ValidationError
+        });
       }
       let definition3 = {
         absoluteFilePath: absolutePathToDefinition,
@@ -592608,7 +592657,9 @@ async function mergeWithOverrides2({ absoluteFilePathToOverrides, data: data2, c
       parsedOverrides = jsYaml.load(contents, { json: true });
     }
   } catch (err) {
-    return context3.failAndThrow(`Failed to read overrides from file ${absoluteFilePathToOverrides}`);
+    return context3.failAndThrow(`Failed to read overrides from file ${absoluteFilePathToOverrides}`, void 0, {
+      code: CliError.Code.ParseError
+    });
   }
   return mergeWithOverrides({ data: data2, overrides: parsedOverrides, allowNullKeys });
 }
@@ -592768,7 +592819,10 @@ async function resolveExternalRefs(obj, baseDir, mainFileAbsPath, registry2, app
     }
     const cacheKey = `${absoluteRefPath}#${jsonPointer}`;
     if (visited.has(cacheKey)) {
-      throw new Error(`Circular $ref detected: "${ref2}" (resolved to "${cacheKey}")`);
+      throw new CliError({
+        message: `Circular $ref detected: "${ref2}" (resolved to "${cacheKey}")`,
+        code: CliError.Code.ReferenceError
+      });
     }
     const newVisited = new Set(visited);
     newVisited.add(cacheKey);
@@ -592851,7 +592905,9 @@ async function parseOverlayFile(absoluteFilePathToOverlay, context3) {
   try {
     contents = await (0, import_promises26.readFile)(absoluteFilePathToOverlay, "utf8");
   } catch (err) {
-    return context3.failAndThrow(`Failed to read overlay file at ${absoluteFilePathToOverlay}: ${err}`);
+    return context3.failAndThrow(`Failed to read overlay file at ${absoluteFilePathToOverlay}: ${err}`, void 0, {
+      code: CliError.Code.ConfigError
+    });
   }
   try {
     try {
@@ -592860,7 +592916,9 @@ async function parseOverlayFile(absoluteFilePathToOverlay, context3) {
       return jsYaml.load(contents, { json: true });
     }
   } catch (err) {
-    return context3.failAndThrow(`Failed to parse overlay file at ${absoluteFilePathToOverlay}: ${err}`);
+    return context3.failAndThrow(`Failed to parse overlay file at ${absoluteFilePathToOverlay}: ${err}`, void 0, {
+      code: CliError.Code.ParseError
+    });
   }
 }
 function validateOverlay(overlay, context3) {
@@ -596183,7 +596241,10 @@ function createTypeReferenceFromFernType(fernType) {
           string: (value2) => Literal.string(value2),
           boolean: (value2) => Literal.boolean(value2),
           _other: () => {
-            throw new Error("Unexpected literal type");
+            throw new CliError({
+              message: "Unexpected literal type",
+              code: CliError.Code.InternalError
+            });
           }
         })));
       },
@@ -600224,7 +600285,10 @@ var ChannelConverter3_0 = class extends AbstractChannelConverter {
   }
   getChannelPathFromOperation(operation) {
     if (!operation.channel.$ref.startsWith(CHANNEL_REFERENCE_PREFIX2)) {
-      throw new Error(`Failed to resolve channel path from operation ${operation.channel.$ref}`);
+      throw new CliError({
+        message: `Failed to resolve channel path from operation ${operation.channel.$ref}`,
+        code: CliError.Code.ReferenceError
+      });
     }
     return operation.channel.$ref.substring(CHANNEL_REFERENCE_PREFIX2.length);
   }
@@ -605060,7 +605124,7 @@ function getPlatformInfo() {
       osName = "Windows";
       break;
     default:
-      throw new Error(`Unsupported platform: ${platform3}`);
+      throw new CliError({ message: `Unsupported platform: ${platform3}`, code: CliError.Code.EnvironmentError });
   }
   let archName;
   switch (arch3) {
@@ -605071,7 +605135,7 @@ function getPlatformInfo() {
       archName = platform3 === "linux" ? "aarch64" : "arm64";
       break;
     default:
-      throw new Error(`Unsupported architecture: ${arch3}`);
+      throw new CliError({ message: `Unsupported architecture: ${arch3}`, code: CliError.Code.EnvironmentError });
   }
   return {
     os: osName,
@@ -605145,7 +605209,10 @@ async function acquireLock(logger4) {
         await new Promise((resolve14) => setTimeout(resolve14, LOCK_RETRY_INTERVAL_MS));
       }
     }
-    throw new Error(`Failed to acquire buf lock after timeout and retry`);
+    throw new CliError({
+      message: `Failed to acquire buf lock after timeout and retry`,
+      code: CliError.Code.InternalError
+    });
   }
   return createLockReleaser(lockPath, logger4);
 }
@@ -605334,7 +605401,10 @@ async function ensureBufCommand(logger4) {
       logger4.debug(`Using auto-downloaded buf: ${downloadedBufPath}`);
       return downloadedBufPath;
     }
-    throw new Error("Missing required dependency; please install 'buf' to continue (e.g. 'brew install buf').");
+    throw new CliError({
+      message: "Missing required dependency; please install 'buf' to continue (e.g. 'brew install buf').",
+      code: CliError.Code.EnvironmentError
+    });
   }
 }
 var PROTOBUF_GENERATOR_CONFIG_FILENAME = "buf.gen.yaml";
@@ -605551,7 +605621,7 @@ var ProtobufIRGenerator = class {
           try {
             await (0, import_promises34.access)(bufLockPath);
           } catch {
-            this.context.failAndThrow("Air-gapped mode requires a pre-cached buf.lock file. Please run 'buf dep update' at build time to cache dependencies.");
+            this.context.failAndThrow("Air-gapped mode requires a pre-cached buf.lock file. Please run 'buf dep update' at build time to cache dependencies.", void 0, { code: CliError.Code.InternalError });
           }
         } else {
           await buf(["dep", "update"]);
@@ -605559,7 +605629,9 @@ var ProtobufIRGenerator = class {
       }
       const bufGenerateResult = await buf(["generate"]);
       if (bufGenerateResult.exitCode !== 0) {
-        this.context.failAndThrow(bufGenerateResult.stderr);
+        this.context.failAndThrow(bufGenerateResult.stderr, void 0, {
+          code: CliError.Code.IrConversionError
+        });
       }
       await (0, import_promises34.unlink)(bufYamlPath);
     } catch (error50) {
@@ -605575,11 +605647,15 @@ var ProtobufIRGenerator = class {
     try {
       this.resolvedBufCommand = await ensureBufCommand(this.context.logger);
     } catch (error50) {
-      this.context.failAndThrow(error50 instanceof Error ? error50.message : String(error50));
+      this.context.failAndThrow(error50 instanceof Error ? error50.message : String(error50), void 0, {
+        code: CliError.Code.EnvironmentError
+      });
     }
   }
   async generateRemote() {
-    this.context.failAndThrow("Remote Protobuf generation is unimplemented.");
+    this.context.failAndThrow("Remote Protobuf generation is unimplemented.", void 0, {
+      code: CliError.Code.InternalError
+    });
   }
 };
 
@@ -605619,7 +605695,7 @@ function getPlatformInfo2() {
       osName = "windows";
       break;
     default:
-      throw new Error(`Unsupported platform: ${platform3}`);
+      throw new CliError({ message: `Unsupported platform: ${platform3}`, code: CliError.Code.EnvironmentError });
   }
   let archName;
   switch (arch3) {
@@ -605630,7 +605706,7 @@ function getPlatformInfo2() {
       archName = "arm64";
       break;
     default:
-      throw new Error(`Unsupported architecture: ${arch3}`);
+      throw new CliError({ message: `Unsupported architecture: ${arch3}`, code: CliError.Code.EnvironmentError });
   }
   return {
     os: osName,
@@ -605704,7 +605780,10 @@ async function acquireLock2(logger4) {
         await new Promise((resolve14) => setTimeout(resolve14, LOCK_RETRY_INTERVAL_MS2));
       }
     }
-    throw new Error(`Failed to acquire lock after timeout and retry`);
+    throw new CliError({
+      message: `Failed to acquire lock after timeout and retry`,
+      code: CliError.Code.InternalError
+    });
   }
   return createLockReleaser2(lockPath, logger4);
 }
@@ -605822,7 +605901,9 @@ var ProtobufOpenAPIGenerator = class {
    */
   async prepare({ absoluteFilepathToProtobufRoot, relativeFilepathToProtobufRoot, local, deps }) {
     if (!local) {
-      this.context.failAndThrow("Remote Protobuf generation is unimplemented.");
+      this.context.failAndThrow("Remote Protobuf generation is unimplemented.", void 0, {
+        code: CliError.Code.InternalError
+      });
     }
     await this.ensureBufResolved();
     await this.ensureProtocGenOpenAPIResolved();
@@ -605842,7 +605923,7 @@ var ProtobufOpenAPIGenerator = class {
         try {
           await (0, import_promises36.access)(bufLockPath);
         } catch {
-          this.context.failAndThrow("Air-gapped mode requires a pre-cached buf.lock file. Please run 'buf dep update' at build time to cache dependencies.");
+          this.context.failAndThrow("Air-gapped mode requires a pre-cached buf.lock file. Please run 'buf dep update' at build time to cache dependencies.", void 0, { code: CliError.Code.InternalError });
         }
       } else {
         const bufCommand = this.resolvedBufCommand ?? "buf";
@@ -605879,7 +605960,9 @@ var ProtobufOpenAPIGenerator = class {
     });
     const bufGenerateResult = await buf(["generate", target.toString()]);
     if (bufGenerateResult.exitCode !== 0) {
-      this.context.failAndThrow(bufGenerateResult.stderr);
+      this.context.failAndThrow(bufGenerateResult.stderr, void 0, {
+        code: CliError.Code.IrConversionError
+      });
     }
     const outputPath = join8(preparedDir.cwd, RelativeFilePath2.of(PROTOBUF_GENERATOR_OUTPUT_FILEPATH2));
     const uniqueOutput = AbsoluteFilePath2.of((await import_tmp_promise7.default.file({ postfix: ".yaml" })).path);
@@ -605937,7 +606020,7 @@ var ProtobufOpenAPIGenerator = class {
           try {
             await (0, import_promises36.access)(bufLockPath);
           } catch {
-            this.context.failAndThrow("Air-gapped mode requires a pre-cached buf.lock file. Please run 'buf dep update' at build time to cache dependencies.");
+            this.context.failAndThrow("Air-gapped mode requires a pre-cached buf.lock file. Please run 'buf dep update' at build time to cache dependencies.", void 0, { code: CliError.Code.InternalError });
           }
         } else {
           await buf(["dep", "update"]);
@@ -605950,7 +606033,9 @@ var ProtobufOpenAPIGenerator = class {
       }
       const bufGenerateResult = await buf(["generate", target.toString()]);
       if (bufGenerateResult.exitCode !== 0) {
-        this.context.failAndThrow(bufGenerateResult.stderr);
+        this.context.failAndThrow(bufGenerateResult.stderr, void 0, {
+          code: CliError.Code.IrConversionError
+        });
       }
       if (cleanupBufLock) {
         await (0, import_promises36.unlink)(bufLockPath);
@@ -605988,7 +606073,7 @@ var ProtobufOpenAPIGenerator = class {
         this.protocGenOpenAPIResolved = true;
         return;
       } catch {
-        this.context.failAndThrow("FERN_USE_LOCAL_PROTOC_GEN_OPENAPI is set but protoc-gen-openapi was not found on PATH.");
+        this.context.failAndThrow("FERN_USE_LOCAL_PROTOC_GEN_OPENAPI is set but protoc-gen-openapi was not found on PATH.", void 0, { code: CliError.Code.EnvironmentError });
       }
     }
     this.context.logger.debug("Resolving protoc-gen-openapi (preferring auto-downloaded fern fork)");
@@ -606013,7 +606098,7 @@ var ProtobufOpenAPIGenerator = class {
       }
       this.protocGenOpenAPIResolved = true;
     } catch {
-      this.context.failAndThrow("Missing required dependency; please install 'protoc-gen-openapi' to continue (e.g. 'brew install go && go install github.com/fern-api/protoc-gen-openapi/cmd/protoc-gen-openapi@latest').");
+      this.context.failAndThrow("Missing required dependency; please install 'protoc-gen-openapi' to continue (e.g. 'brew install go && go install github.com/fern-api/protoc-gen-openapi/cmd/protoc-gen-openapi@latest').", void 0, { code: CliError.Code.EnvironmentError });
     }
   }
   async ensureBufResolved() {
@@ -606023,11 +606108,15 @@ var ProtobufOpenAPIGenerator = class {
     try {
       this.resolvedBufCommand = await ensureBufCommand(this.context.logger);
     } catch (error50) {
-      this.context.failAndThrow(error50 instanceof Error ? error50.message : String(error50));
+      this.context.failAndThrow(error50 instanceof Error ? error50.message : String(error50), void 0, {
+        code: CliError.Code.EnvironmentError
+      });
     }
   }
   async generateRemote() {
-    this.context.failAndThrow("Remote Protobuf generation is unimplemented.");
+    this.context.failAndThrow("Remote Protobuf generation is unimplemented.", void 0, {
+      code: CliError.Code.InternalError
+    });
   }
 };
 function getProtobufGeneratorConfig({ relativeFilepathToProtobufRoot }) {
@@ -606406,7 +606495,10 @@ var OSSWorkspace = class _OSSWorkspace extends BaseOpenAPIWorkspace {
       }
     }
     if (mergedIr === void 0) {
-      throw new Error("Failed to generate intermediate representation");
+      throw new CliError({
+        message: "Failed to generate intermediate representation",
+        code: CliError.Code.IrConversionError
+      });
     }
     if (authOverrides != null) {
       mergedIr = resolveOAuthEndpointReferences({ ir: mergedIr, authOverrides });
@@ -606502,7 +606594,10 @@ var OSSWorkspace = class _OSSWorkspace extends BaseOpenAPIWorkspace {
   }
   async convertSpecsOverrideToSpecs(specsOverride) {
     if (!Array.isArray(specsOverride)) {
-      throw new Error("Conjure specs override is not yet supported");
+      throw new CliError({
+        message: "Conjure specs override is not yet supported",
+        code: CliError.Code.InternalError
+      });
     }
     const specs = [];
     for (const spec of specsOverride) {
@@ -606536,7 +606631,10 @@ var OSSWorkspace = class _OSSWorkspace extends BaseOpenAPIWorkspace {
         };
         specs.push(openApiSpec);
       } else {
-        throw new Error(`Spec type override not yet supported. Only OpenAPI specs are currently supported in specs override.`);
+        throw new CliError({
+          message: `Spec type override not yet supported. Only OpenAPI specs are currently supported in specs override.`,
+          code: CliError.Code.InternalError
+        });
       }
     }
     return specs;
@@ -614668,7 +614766,7 @@ var AccessTokenPosthogManager = class {
         properties: {
           ...event,
           ...event.properties,
-          version: "4.82.0",
+          version: "4.83.0",
           usingAccessToken: true
         }
       });
@@ -614722,7 +614820,7 @@ var UserPosthogManager = class {
       distinctId: this.userId ?? await this.getPersistedDistinctId(),
       event: "CLI",
       properties: {
-        version: "4.82.0",
+        version: "4.83.0",
         ...event,
         ...event.properties,
         usingAccessToken: false,
@@ -615602,7 +615700,7 @@ async function doAuth0DeviceAuthorizationFlow({ auth0Domain: auth0Domain2, auth0
     validateStatus: () => true
   });
   if (deviceCodeResponse.status !== 200) {
-    context3.failAndThrow("Failed to authenticate", deviceCodeResponse.data);
+    context3.failAndThrow("Failed to authenticate", deviceCodeResponse.data, { code: CliError.Code.AuthError });
   }
   await (0, import_open.default)(deviceCodeResponse.data.verification_uri_complete);
   context3.logger.info([
@@ -615657,7 +615755,7 @@ async function pollForToken({ auth0Domain: auth0Domain2, auth0ClientId, deviceCo
     case "access_denied":
     case "expired_token":
     default:
-      return context3.failAndThrow("Failed to authenticate", data2);
+      return context3.failAndThrow("Failed to authenticate", data2, { code: CliError.Code.AuthError });
   }
 }
 
@@ -615747,10 +615845,10 @@ async function getTokenFromCode({ auth0Domain: auth0Domain2, auth0ClientId, code
   });
   const { access_token: accessToken, id_token: idToken } = response.data;
   if (accessToken == null) {
-    throw new Error("Access token is not defined");
+    throw new CliError({ message: "Access token is not defined", code: CliError.Code.AuthError });
   }
   if (idToken == null) {
-    throw new Error("ID token is not defined");
+    throw new CliError({ message: "ID token is not defined", code: CliError.Code.AuthError });
   }
   return { accessToken, idToken };
 }
@@ -615781,17 +615879,26 @@ async function resolveSsoConnection({ dashboardBaseUrl, email: email3 }) {
     });
   } catch (error50) {
     if (axios_default.isAxiosError(error50) && error50.response?.status === 404) {
-      throw new Error(`No SSO connection associated with email: ${email3}`);
+      throw new CliError({
+        message: `No SSO connection associated with email: ${email3}`,
+        code: CliError.Code.AuthError
+      });
     }
     throw error50;
   }
   const responseData = response.data;
   if (typeof responseData !== "object" || responseData == null) {
-    throw new Error("Invalid response format from SSO resolve endpoint");
+    throw new CliError({
+      message: "Invalid response format from SSO resolve endpoint",
+      code: CliError.Code.AuthError
+    });
   }
   const { connection } = responseData;
   if (typeof connection !== "string" || connection.length === 0) {
-    throw new Error("No SSO connection found for this email");
+    throw new CliError({
+      message: "No SSO connection found for this email",
+      code: CliError.Code.AuthError
+    });
   }
   return connection;
 }
@@ -615859,14 +615966,14 @@ async function askToLogin(context3) {
   if (!await isLoggedIn() && process.stdout.isTTY) {
     await context3.takeOverTerminal(async () => {
       if (!await askForConfirmation("Login required. Continue?")) {
-        context3.failAndThrow();
+        context3.failAndThrow(void 0, void 0, { code: CliError.Code.AuthError });
       }
     });
     await login(context3);
   }
   const token = await getToken2();
   if (token == null) {
-    context3.failAndThrow("Authentication required. Please run 'fern login' or set the FERN_TOKEN environment variable.");
+    context3.failAndThrow("Authentication required. Please run 'fern login' or set the FERN_TOKEN environment variable.", void 0, { code: CliError.Code.AuthError });
   }
   return token;
 }
@@ -617898,7 +618005,10 @@ var YamlSourceResolver = class {
       case "boolean":
         return new SourcedBoolean(value2, location2);
       default:
-        throw new Error(`Unexpected value type: ${typeof value2}`);
+        throw new CliError({
+          message: `Unexpected value type: ${typeof value2}`,
+          code: CliError.Code.InternalError
+        });
     }
   }
 };
@@ -617978,7 +618088,10 @@ var YamlConfigLoader = class {
     try {
       return await this.parser.parseDocument({ absoluteFilePath, cwd: this.cwd });
     } catch (err) {
-      throw new Error(`Failed to parse YAML file ${absoluteFilePath}: ${extractErrorMessage(err)}`);
+      throw new CliError({
+        message: `Failed to parse YAML file ${absoluteFilePath}: ${extractErrorMessage(err)}`,
+        code: CliError.Code.ParseError
+      });
     }
   }
   async resolveReferences({ document: document4, resolveReferences }) {
@@ -742470,7 +742583,7 @@ function convertTypes(types4) {
           return IrVersions_exports.V54.types.Type.undiscriminatedUnion(convertUndiscriminatedUnion(undiscriminatedUnion21));
         },
         _other: () => {
-          throw new Error("Encountered unknown shape");
+          throw new CliError({ message: "Encountered unknown shape", code: CliError.Code.InternalError });
         }
       })
     };
@@ -742633,7 +742746,10 @@ function convertTypeReference(typeReference2) {
     named: IrVersions_exports.V54.types.TypeReference.named,
     unknown: IrVersions_exports.V54.types.TypeReference.unknown,
     _other: () => {
-      throw new Error("Unknown type reference: " + typeReference2.type);
+      throw new CliError({
+        message: "Unknown type reference: " + typeReference2.type,
+        code: CliError.Code.InternalError
+      });
     }
   });
 }
@@ -742661,7 +742777,10 @@ function convertContainerType(container) {
     }),
     literal: IrVersions_exports.V54.types.ContainerType.literal,
     _other: () => {
-      throw new Error("Unknown ContainerType: " + container.type);
+      throw new CliError({
+        message: "Unknown ContainerType: " + container.type,
+        code: CliError.Code.InternalError
+      });
     }
   });
 }
@@ -742680,7 +742799,10 @@ function convertSingleUnionTypeProperties(properties7) {
     }),
     noProperties: IrVersions_exports.V54.types.SingleUnionTypeProperties.noProperties,
     _other: () => {
-      throw new Error(`Unknown SingleUnionTypeProperties: ${JSON.stringify(properties7)}`);
+      throw new CliError({
+        message: `Unknown SingleUnionTypeProperties: ${JSON.stringify(properties7)}`,
+        code: CliError.Code.InternalError
+      });
     }
   });
 }
@@ -742691,7 +742813,10 @@ function convertResolvedType(resolvedType) {
     primitive: (primitiveType2) => IrVersions_exports.V54.types.ResolvedTypeReference.primitive(convertPrimitiveType(primitiveType2)),
     unknown: IrVersions_exports.V54.types.ResolvedTypeReference.unknown,
     _other: () => {
-      throw new Error("Unknown ResolvedTypeReference: " + resolvedType.type);
+      throw new CliError({
+        message: "Unknown ResolvedTypeReference: " + resolvedType.type,
+        code: CliError.Code.InternalError
+      });
     }
   });
 }
@@ -742890,7 +743015,10 @@ function convertSdkRequestShape(shape) {
     justRequestBody: (reference4) => IrVersions_exports.V54.http.SdkRequestShape.justRequestBody(convertSdkRequestBodyType(reference4)),
     wrapper: IrVersions_exports.V54.http.SdkRequestShape.wrapper,
     _other: () => {
-      throw new Error("Unknown SdkRequestShape: " + shape.type);
+      throw new CliError({
+        message: "Unknown SdkRequestShape: " + shape.type,
+        code: CliError.Code.InternalError
+      });
     }
   });
 }
@@ -742940,7 +743068,10 @@ function convertRequestBody(requestBody) {
       return IrVersions_exports.V54.http.HttpRequestBody.bytes(bytes);
     },
     _other: () => {
-      throw new Error("Unknown HttpRequestBody: " + requestBody.type);
+      throw new CliError({
+        message: "Unknown HttpRequestBody: " + requestBody.type,
+        code: CliError.Code.InternalError
+      });
     }
   });
 }
@@ -744378,7 +744509,7 @@ function convertAuthScheme(scheme) {
     case "inferred":
       return IrVersions_exports.V62.AuthScheme.inferred(scheme);
     default:
-      throw new Error("Unknown AuthScheme type");
+      throw new CliError({ message: "Unknown AuthScheme type", code: CliError.Code.InternalError });
   }
 }
 function convertTypeDeclaration2(typeDeclaration2) {
@@ -746793,10 +746924,16 @@ var IntermediateRepresentationMigratorImpl = class {
       if (targetGenerator != null) {
         const minVersion = this.getMinimumGeneratorVersion(targetGenerator.name);
         if (minVersion != null) {
-          throw new Error(`${targetGenerator.name}@${targetGenerator.version} is not compatible with CLI v4.x.x+. Please upgrade to ${targetGenerator.name}@${minVersion} or later using 'fern generator upgrade --include-major'.`);
+          throw new CliError({
+            message: `${targetGenerator.name}@${targetGenerator.version} is not compatible with CLI v4.x.x+. Please upgrade to ${targetGenerator.name}@${minVersion} or later using 'fern generator upgrade --include-major'.`,
+            code: CliError.Code.VersionError
+          });
         }
       }
-      throw new Error("This generator version is not compatible with CLI v4.x.x+. Please upgrade your generator using 'fern generator upgrade --include-major'.");
+      throw new CliError({
+        message: "This generator version is not compatible with CLI v4.x.x+. Please upgrade your generator using 'fern generator upgrade --include-major'.",
+        code: CliError.Code.VersionError
+      });
     }
   }
   migrateThroughVersion({ version: version7, intermediateRepresentation, context: context3, targetGenerator }) {
@@ -746822,7 +746959,7 @@ var IntermediateRepresentationMigratorImpl = class {
       targetGenerator
     });
     if (!hasEncounteredMigrationYet) {
-      context3.failAndThrow(`IR ${version7} does not exist`);
+      context3.failAndThrow(`IR ${version7} does not exist`, void 0, { code: CliError.Code.VersionError });
     }
     return migrated;
   }
@@ -746852,15 +746989,28 @@ var IntermediateRepresentationMigratorImpl = class {
   shouldRunMigration({ migration: migration23, targetGenerator }) {
     const minVersionToExclude = migration23.firstGeneratorVersionToConsumeNewIR[targetGenerator.name];
     if (minVersionToExclude == null) {
-      throw new Error(`Cannot migrate intermediate representation. Unrecognized generator: ${targetGenerator.name}. If leveraging a custom generator, ensure you are specifying "ir-version" within the generator configuration.`);
+      throw new CliError({
+        message: `Cannot migrate intermediate representation. Unrecognized generator: ${targetGenerator.name}. If leveraging a custom generator, ensure you are specifying "ir-version" within the generator configuration.`,
+        code: CliError.Code.ConfigError
+      });
     }
     switch (minVersionToExclude) {
       case GeneratorWasNeverUpdatedToConsumeNewIR:
         return true;
       case GeneratorWasNotCreatedYet:
-        throw new Error(`Cannot migrate intermediate representation. Generator was created after intermediate representation ${migration23.laterVersion}.`);
+        throw new CliError({
+          message: `Cannot migrate intermediate representation. Generator was created after intermediate representation ${migration23.laterVersion}.`,
+          code: CliError.Code.VersionError
+        });
+    }
+    try {
+      return isVersionAhead(minVersionToExclude, targetGenerator.version);
+    } catch (error50) {
+      throw new CliError({
+        message: `Failed to compare versions: ${error50 instanceof Error ? error50.message : String(error50)}`,
+        code: CliError.Code.VersionError
+      });
     }
-    return isVersionAhead(minVersionToExclude, targetGenerator.version);
   }
   getIRVersionForGenerator({ targetGenerator }) {
     let lastIrVersion = this.migrations[0]?.laterVersion;
@@ -786748,7 +786898,10 @@ function mergeEndpointPairs({ children: children2, findEndpointById, stringifyEn
     }
     const endpoint3 = findEndpointById(child.endpointId);
     if (endpoint3 == null) {
-      throw new Error(`Endpoint ${child.endpointId} not found`);
+      throw new CliError({
+        message: `Endpoint ${child.endpointId} not found`,
+        code: CliError.Code.InternalError
+      });
     }
     const methodAndPath = `${endpoint3.method} ${stringifyEndpointPathParts3(endpoint3)}`;
     const existing = methodAndPathToEndpointNode.get(methodAndPath);
@@ -787752,7 +787905,9 @@ ${tagInfo.description}`;
   getFileId(filepath) {
     const fileId = this.collectedFileIds.get(filepath);
     if (fileId == null) {
-      return this.taskContext.failAndThrow("Failed to locate file after uploading: " + filepath);
+      return this.taskContext.failAndThrow("Failed to locate file after uploading: " + filepath, void 0, {
+        code: CliError.Code.InternalError
+      });
     }
     return fileId;
   }
@@ -787794,7 +787949,10 @@ var NodeIdGenerator2 = class _NodeIdGenerator {
       hashedId = this.#getHashedId(id);
       loop++;
       if (loop > 100) {
-        throw new Error(`Infinite loop detected for id: ${id}`);
+        throw new CliError({
+          message: `Infinite loop detected for id: ${id}`,
+          code: CliError.Code.ReferenceError
+        });
       }
     }
     return hashedId;
@@ -792404,7 +792562,7 @@ var DocsDefinitionResolver = class {
   _parsedDocsConfig;
   get parsedDocsConfig() {
     if (this._parsedDocsConfig == null) {
-      throw new Error("parsedDocsConfig is not set");
+      throw new CliError({ message: "parsedDocsConfig is not set", code: CliError.Code.InternalError });
     }
     return this._parsedDocsConfig;
   }
@@ -792900,7 +793058,7 @@ var DocsDefinitionResolver = class {
 A valid API configuration was not found at the path: fern/apis/${apiSection.apiName}.
 Learn more about project structure:
 https://buildwithfern.com/learn/docs/getting-started/project-structure#api-definitions` : "Failed to load API Definition referenced in docs.\nLearn more about project structure:\nhttps://buildwithfern.com/learn/docs/getting-started/project-structure#api-definitions";
-    throw new Error(errorMessage);
+    throw new CliError({ message: errorMessage, code: CliError.Code.ConfigError });
   }
   getOpenApiWorkspaceForApiSection(apiSection) {
     if (apiSection.apiName != null) {
@@ -792915,7 +793073,7 @@ https://buildwithfern.com/learn/docs/getting-started/project-structure#api-defin
 A valid API configuration was not found at the path: fern/apis/${apiSection.apiName}.
 Learn more about project structure:
 https://buildwithfern.com/learn/docs/getting-started/project-structure#api-definitions` : "Failed to load API Definition referenced in docs.\nLearn more about project structure:\nhttps://buildwithfern.com/learn/docs/getting-started/project-structure#api-definitions";
-    throw new Error(errorMessage);
+    throw new CliError({ message: errorMessage, code: CliError.Code.ConfigError });
   }
   async toRootNode() {
     const slug = navigation_exports.V1.SlugGenerator.init(navigation_exports.slugjoin(this.getDocsBasePath()));
@@ -792992,7 +793150,10 @@ https://buildwithfern.com/learn/docs/getting-started/project-structure#api-defin
     const id = this.#idgen.get("versioned");
     const defaultVersion = versioned.versions[0];
     if (defaultVersion?.hidden === true) {
-      throw new Error(`The default version "${defaultVersion.version}" cannot be hidden. Please set a non-hidden version as the first version in your versions list, or remove the hidden flag from the default version.`);
+      throw new CliError({
+        message: `The default version "${defaultVersion.version}" cannot be hidden. Please set a non-hidden version as the first version in your versions list, or remove the hidden flag from the default version.`,
+        code: CliError.Code.ConfigError
+      });
     }
     const BATCH_SIZE2 = 5;
     const children2 = [];
@@ -793296,7 +793457,7 @@ https://buildwithfern.com/learn/docs/getting-started/project-structure#api-defin
     }
     if (this.docsWorkspace.config.settings?.substituteEnvVars) {
       ir10 = replaceEnvVariables(ir10, {
-        onError: (e5) => this.taskContext.failAndThrow(`Error substituting environment variables in API spec: ${e5}`)
+        onError: (e5) => this.taskContext.failAndThrow(`Error substituting environment variables in API spec: ${e5}`, void 0, { code: CliError.Code.EnvironmentError })
       }, { substituteAsEmpty: false });
     }
     let graphqlWorkspace = openapiWorkspace;
@@ -793708,7 +793869,9 @@ https://buildwithfern.com/learn/docs/getting-started/project-structure#api-defin
     }
     const fileId = this.collectedFileIds.get(filepath);
     if (fileId == null) {
-      return this.taskContext.failAndThrow("Failed to locate file after uploading: " + filepath);
+      return this.taskContext.failAndThrow("Failed to locate file after uploading: " + filepath, void 0, {
+        code: CliError.Code.InternalError
+      });
     }
     return DocsV1Write_exports.FileId(fileId);
   }
@@ -793865,7 +794028,9 @@ https://buildwithfern.com/learn/docs/getting-started/project-structure#api-defin
         value: this.getFileId(value2)
       }),
       url: ({ value: value2 }) => ({ type: "url", value: DocsV1Write_exports.Url(value2) }),
-      _other: () => this.taskContext.failAndThrow("Invalid metadata configuration")
+      _other: () => this.taskContext.failAndThrow("Invalid metadata configuration", void 0, {
+        code: CliError.Code.ConfigError
+      })
     });
   }
   /**
@@ -827068,7 +827233,10 @@ function collectLinksAndSources({ readFile: readFile104 = (path99) => (0, import
   do {
     loopCount++;
     if (loopCount > LOOP_LIMIT) {
-      throw new Error("Infinite loop detected while collecting links and sources");
+      throw new CliError({
+        message: "Infinite loop detected while collecting links and sources",
+        code: CliError.Code.ReferenceError
+      });
     }
     const popped = contentQueue.shift();
     if (popped == null) {
@@ -827077,7 +827245,10 @@ function collectLinksAndSources({ readFile: readFile104 = (path99) => (0, import
     const { content: content5, absoluteFilepath } = popped;
     if (absoluteFilepath != null) {
       if (visitedAbsoluteFilepaths.has(absoluteFilepath)) {
-        throw new Error(`Circular import detected: ${absoluteFilepath}`);
+        throw new CliError({
+          message: `Circular import detected: ${absoluteFilepath}`,
+          code: CliError.Code.ReferenceError
+        });
       }
       visitedAbsoluteFilepaths.add(absoluteFilepath);
     }
@@ -827294,7 +827465,7 @@ var ValidMarkdownLinks = {
     const resolvedDocsDefinition = await docsDefinitionResolver.resolve();
     const configRoot = resolvedDocsDefinition.config.root;
     if (!configRoot || !isV1RootNode2(configRoot)) {
-      throw new Error("Root node not found");
+      throw new CliError({ message: "Root node not found", code: CliError.Code.InternalError });
     }
     const root6 = navigation_exports.migrate.FernNavigationV1ToLatest.create().root(configRoot);
     const collector = navigation_exports.NodeCollector.collect(root6);
@@ -830444,7 +830615,10 @@ function buildPreviewDomain({ orgId, previewId }) {
   const availableSpace = SUBDOMAIN_LIMIT - prefix2.length;
   const minIdLength = 8;
   if (availableSpace < minIdLength) {
-    throw new Error(`Organization name "${orgId}" is too long to generate a valid preview URL`);
+    throw new CliError({
+      message: `Organization name "${orgId}" is too long to generate a valid preview URL`,
+      code: CliError.Code.ValidationError
+    });
   }
   const truncatedId = sanitizedId.slice(0, availableSpace).replace(/-+$/, "");
   return `${prefix2}${truncatedId}.${DOMAIN_SUFFIX}`;
@@ -832138,7 +832312,7 @@ var LOCAL_STORAGE_FOLDER4 = ".fern-dev";
 var LOGS_FOLDER_NAME = "logs";
 var MAX_LOGS_DIR_SIZE_BYTES = 100 * 1024 * 1024;
 function getCliSource() {
-  const version7 = "4.82.0";
+  const version7 = "4.83.0";
   return `cli@${version7}`;
 }
 var DebugLogger = class {
@@ -832646,7 +832820,10 @@ async function downloadBundle({ bucketUrl, logger: logger4, preferCached, app =
   try {
     const docsBundleZipResponse = await fetch(docsBundleUrl);
     if (!docsBundleZipResponse.ok) {
-      throw new Error(`Failed to download docs preview bundle. Status code: ${docsBundleZipResponse.status}`);
+      throw new CliError({
+        message: `Failed to download docs preview bundle. Status code: ${docsBundleZipResponse.status}`,
+        code: CliError.Code.NetworkError
+      });
     }
     const outputZipPath = join8(absoluteDirectoryToTmpDir, RelativeFilePath2.of(tryTar ? "output.tar.gz" : "output.zip"));
     if (docsBundleZipResponse.body == null) {
@@ -832787,7 +832964,10 @@ async function downloadBundle({ bucketUrl, logger: logger4, preferCached, app =
           doNotPipeOutput: true
         });
       } catch (error50) {
-        throw new Error("Requires [pnpm] to run local development. Please run: npm install -g pnpm, and then: fern docs dev");
+        throw new CliError({
+          message: "Requires [pnpm] to run local development. Please run: npm install -g pnpm, and then: fern docs dev",
+          code: CliError.Code.EnvironmentError
+        });
       }
       try {
         logger4.debug("Installing esbuild");
@@ -833086,7 +833266,7 @@ async function getPreviewDocsDefinition({ domain: domain3, project, context: con
   const docsWorkspace = project.docsWorkspaces;
   const apiWorkspaces = project.apiWorkspaces;
   if (docsWorkspace == null) {
-    throw new Error("No docs workspace found in project");
+    throw new CliError({ message: "No docs workspace found in project", code: CliError.Code.ConfigError });
   }
   if (editedAbsoluteFilepaths != null && previousDocsDefinition != null) {
     const allMarkdownFiles = editedAbsoluteFilepaths.every((filepath) => filepath.endsWith(".mdx") || filepath.endsWith(".md"));
@@ -833657,7 +833837,10 @@ async function runAppPreviewServer({ initialProject, reloadProject, validateProj
     try {
       const url3 = "https://dev2-local-preview-bundle4.s3.amazonaws.com/";
       if (url3 == null) {
-        throw new Error("Failed to connect to the docs preview server. Please contact support@buildwithfern.com");
+        throw new CliError({
+          message: "Failed to connect to the docs preview server. Please contact support@buildwithfern.com",
+          code: CliError.Code.InternalError
+        });
       }
       await downloadBundle({
         bucketUrl: url3,
@@ -833675,7 +833858,10 @@ async function runAppPreviewServer({ initialProject, reloadProject, validateProj
       try {
         const url3 = "https://dev2-local-preview-bundle3.s3.amazonaws.com/";
         if (url3 == null) {
-          throw new Error("Failed to connect to the docs preview server. Please contact support@buildwithfern.com");
+          throw new CliError({
+            message: "Failed to connect to the docs preview server. Please contact support@buildwithfern.com",
+            code: CliError.Code.InternalError
+          });
         }
         await downloadBundle({
           bucketUrl: url3,
@@ -834145,7 +834331,10 @@ async function runPreviewServer({ initialProject, reloadProject, validateProject
     try {
       const url3 = "https://dev2-local-preview-bundle2.s3.amazonaws.com/";
       if (url3 == null) {
-        throw new Error("Failed to connect to the docs preview server. Please contact support@buildwithfern.com");
+        throw new CliError({
+          message: "Failed to connect to the docs preview server. Please contact support@buildwithfern.com",
+          code: CliError.Code.InternalError
+        });
       }
       await downloadBundle({ bucketUrl: url3, logger: context3.logger, preferCached: true, tryTar: false });
     } catch (err) {
@@ -834827,7 +835016,16 @@ function createGeneratorsYmlAstVisitorForRules({ relativeFilepath, contents, all
 
 // ../yaml/generators-validator/lib/rules/compatible-ir-versions/compatible-ir-versions.js
 function getMaybeBadVersionMessage(generatorName, minCliVersion, cliVersion) {
-  if (!isVersionAhead(cliVersion, minCliVersion)) {
+  let isAhead;
+  try {
+    isAhead = isVersionAhead(cliVersion, minCliVersion);
+  } catch (error50) {
+    throw new CliError({
+      message: `Failed to compare versions: ${error50 instanceof Error ? error50.message : String(error50)}`,
+      code: CliError.Code.VersionError
+    });
+  }
+  if (!isAhead) {
     return [
       {
         severity: "fatal",
@@ -834962,7 +835160,7 @@ async function validateGeneratorsYmlFile({ contents, allRuleVisitors, cliVersion
 var import_validate_npm_package_name = __toESM(require_lib18(), 1);
 async function collectAPIWorkspaceViolations({ workspace, context: context3, ossWorkspace }) {
   if (!(0, import_validate_npm_package_name.default)(workspace.definition.rootApiFile.contents.name).validForNewPackages) {
-    context3.failAndThrow("API name is not valid.");
+    context3.failAndThrow("API name is not valid.", void 0, { code: CliError.Code.ValidationError });
   }
   const startTime = performance.now();
   const apiViolations = validateFernWorkspace(workspace, context3.logger);
@@ -835000,7 +835198,7 @@ async function validateAPIWorkspaceWithoutExiting({ workspace, context: context3
 }
 async function validateAPIWorkspaceAndLogIssues({ workspace, context: context3, logWarnings, ossWorkspace }) {
   if (!(0, import_validate_npm_package_name.default)(workspace.definition.rootApiFile.contents.name).validForNewPackages) {
-    context3.failAndThrow("API name is not valid.");
+    context3.failAndThrow("API name is not valid.", void 0, { code: CliError.Code.ValidationError });
   }
   const { hasErrors } = await validateAPIWorkspaceWithoutExiting({
     workspace,
@@ -835009,7 +835207,7 @@ async function validateAPIWorkspaceAndLogIssues({ workspace, context: context3,
     ossWorkspace
   });
   if (hasErrors) {
-    context3.failAndThrow();
+    context3.failAndThrow(void 0, void 0, { code: CliError.Code.ValidationError });
   }
 }
 
@@ -841438,11 +841636,17 @@ async function loadRawDocsConfiguration({ absolutePathOfConfiguration, context:
     } catch (err) {
       context3.logger.error(`Parsing failed even after sanitization: ${extractErrorMessage(err)}`);
       context3.logger.debug(`Sanitized JSON structure: ${JSON.stringify(sanitizedJson, null, 2)}`);
-      throw new Error(`Failed to parse ${absolutePathOfConfiguration}: ${extractErrorMessage(err)}`);
+      throw new CliError({
+        message: `Failed to parse ${absolutePathOfConfiguration}: ${extractErrorMessage(err)}`,
+        code: CliError.Code.ParseError
+      });
     }
   } else {
-    throw new Error(`Failed to parse docs.yml:
-${result.error?.message ?? "Unknown error"}`);
+    throw new CliError({
+      message: `Failed to parse docs.yml:
+${result.error?.message ?? "Unknown error"}`,
+      code: CliError.Code.ParseError
+    });
   }
 }
 
@@ -843740,7 +843944,7 @@ var LegacyDocsPublisher = class {
         previewId,
         disableTemplates: void 0,
         skipUpload,
-        cliVersion: "4.82.0"
+        cliVersion: "4.83.0"
       });
       if (taskContext.getResult() === TaskResult.Failure) {
         return { success: false };
@@ -900016,7 +900220,9 @@ async function createFernDirectoryAndWorkspace({ organization, taskContext, vers
         if (response.ok) {
           organization = response.body.organizationId;
         } else {
-          taskContext.failAndThrow("Unauthorized. FERN_TOKEN is invalid.");
+          taskContext.failAndThrow("Unauthorized. FERN_TOKEN is invalid.", void 0, {
+            code: CliError.Code.AuthError
+          });
           return { absolutePathToFernDirectory: AbsoluteFilePath2.of("/dummy"), organization: "dummy" };
         }
       }
@@ -900250,7 +900456,7 @@ async function formatFernWorkspace({ workspace, context: context3, shouldFix })
         context3.logger.info(source_default.green(`Formatted ${source_default.bold(relativeFilepath)}`));
       } else {
         context3.logger.info(source_default.red(`Invalid formatting: ${source_default.bold(relativeFilepath)}`));
-        context3.failWithoutThrowing();
+        context3.failWithoutThrowing(void 0, void 0, { code: CliError.Code.ValidationError });
       }
     }
   }
@@ -900556,9 +900762,21 @@ async function writeSampleApiDefinition({ directoryOfDefinition, apiName }) {
   await (0, import_promises113.mkdir)(directoryOfDefinition);
   await (0, import_promises113.writeFile)(join8(directoryOfDefinition, RelativeFilePath2.of(ROOT_API_FILENAME)), jsYaml.dump(rootApi));
   const absoluteFilepathToImdbYaml = join8(directoryOfDefinition, RelativeFilePath2.of("imdb.yml"));
-  await (0, import_promises113.writeFile)(absoluteFilepathToImdbYaml, await formatDefinitionFile({
-    fileContents: SAMPLE_IMDB_API
-  }));
+  let formattedContent;
+  try {
+    formattedContent = await formatDefinitionFile({
+      fileContents: SAMPLE_IMDB_API
+    });
+  } catch (error50) {
+    if (error50 instanceof CliError) {
+      throw error50;
+    }
+    throw new CliError({
+      message: `Failed to format definition file: ${error50 instanceof Error ? error50.message : String(error50)}`,
+      code: CliError.Code.ParseError
+    });
+  }
+  await (0, import_promises113.writeFile)(absoluteFilepathToImdbYaml, formattedContent);
 }
 
 // ../init/lib/initializeAPI.js
@@ -900750,7 +900968,7 @@ var FernDocsBuilderImpl = class extends FernDocsBuilder {
     return this.nonTabbedNavigation;
   }
   addVersion({ versionConfig, navigation: navigation2 }) {
-    throw new Error("Method not implemented.");
+    throw new CliError({ message: "Method not implemented.", code: CliError.Code.InternalError });
   }
   addNavbarLink({ link: link3 }) {
     if (this.docsYml.navbarLinks == null) {
@@ -901182,7 +901400,7 @@ var MintlifyImporter = class extends DocsImporter {
     if (Object.keys(this.tabUrlToInfo).length > 0) {
       const tabUrl = getTabForMintItem({ mintItem });
       if (tabUrl == null) {
-        return this.context.failAndThrow(`Failed to assign navigation item to a tab group: ${mintItem.group}`);
+        return this.context.failAndThrow(`Failed to assign navigation item to a tab group: ${mintItem.group}`, void 0, { code: CliError.Code.ConfigError });
       }
       const tab2 = this.tabUrlToInfo[tabUrl] ?? this.getDefaultDocumentationTab(builder);
       return tab2.navigationBuilder;
@@ -901226,19 +901444,23 @@ async function runMintlifyMigration({ absolutePathToMintJson, outputPath, taskCo
 // ../init/lib/initializeWithMintlify.js
 var initializeWithMintlify = async ({ pathToMintJson, taskContext, versionOfCli, organization }) => {
   if (!pathToMintJson?.includes("mint.json")) {
-    taskContext.failAndThrow("Provide a path to a mint.json file");
+    taskContext.failAndThrow("Provide a path to a mint.json file", void 0, {
+      code: CliError.Code.ConfigError
+    });
     return;
   }
   let absolutePathToMintJson = void 0;
   if (isURL(pathToMintJson)) {
-    taskContext.failAndThrow("Clone the repo locally and run this command again by referencing the path to the local mint.json file");
+    taskContext.failAndThrow("Clone the repo locally and run this command again by referencing the path to the local mint.json file", void 0, { code: CliError.Code.ConfigError });
     return;
   } else {
     absolutePathToMintJson = AbsoluteFilePath2.of(resolve6(cwd(), pathToMintJson));
   }
   const pathExists2 = await doesPathExist(absolutePathToMintJson);
   if (!pathExists2 || !absolutePathToMintJson) {
-    taskContext.failAndThrow(`${absolutePathToMintJson} does not exist`);
+    taskContext.failAndThrow(`${absolutePathToMintJson} does not exist`, void 0, {
+      code: CliError.Code.ConfigError
+    });
     return;
   }
   const outputPath = AbsoluteFilePath2.of(cwd());
@@ -901262,7 +901484,7 @@ function assertIsNumber(val) {
 }
 function assertIsDefined(val) {
   if (val === void 0 || val == null) {
-    throw new Error("Value is nullable.");
+    throw new CliError({ message: "Value is nullable.", code: CliError.Code.InternalError });
   }
 }
 function assertIsStringArray(val) {
@@ -914125,7 +914347,7 @@ async function startPuppeteer() {
   try {
     return await launch3({ headless: true, args: ["--ignore-certificate-errors"] });
   } catch (error50) {
-    throw new Error("Could not create a Puppeteer instance");
+    throw new CliError({ message: "Could not create a Puppeteer instance", code: CliError.Code.EnvironmentError });
   }
 }
 async function getHtmlWithPuppeteer(browser, url3) {
@@ -914150,18 +914372,18 @@ async function getHtmlWithPuppeteer(browser, url3) {
     await page.close();
     return content5;
   } catch (error50) {
-    throw new Error("Failed to download page from Puppeteer");
+    throw new CliError({ message: "Failed to download page from Puppeteer", code: CliError.Code.NetworkError });
   }
 }
 async function fetchPageResponse(url3) {
   try {
     const res = await fetch(url3);
     if (!res.ok) {
-      throw new Error(`${res.status} ${res.statusText}`);
+      throw new CliError({ message: `${res.status} ${res.statusText}`, code: CliError.Code.NetworkError });
     }
     return await res.text();
   } catch (error50) {
-    throw new Error("Failed to fetch page from source");
+    throw new CliError({ message: "Failed to fetch page from source", code: CliError.Code.NetworkError });
   }
 }
 async function fetchPageHtml({ url: url3, browser }) {
@@ -914175,22 +914397,28 @@ async function fetchPageHtml({ url: url3, browser }) {
     if (res) {
       return res;
     }
-    throw new Error("An unknown error occurred.");
+    throw new CliError({ message: "An unknown error occurred.", code: CliError.Code.NetworkError });
   } catch (error50) {
-    throw new Error(`Error retrieving HTML for ${url3.toString()}`);
+    throw new CliError({
+      message: `Error retrieving HTML for ${url3.toString()}`,
+      code: CliError.Code.NetworkError
+    });
   }
 }
 async function fetchImage(url3) {
   try {
     const res = await exponentialBackoff(() => fetch(url3));
     if (!res.ok) {
-      throw new Error(`${res.status} ${res.statusText}`);
+      throw new CliError({ message: `${res.status} ${res.statusText}`, code: CliError.Code.NetworkError });
     }
     const imageBuffer = await res.arrayBuffer();
     const imageData = new Uint8Array(imageBuffer);
     return imageData;
   } catch (error50) {
-    throw new Error(`Failed to retrieve image from source url ${url3}`);
+    throw new CliError({
+      message: `Failed to retrieve image from source url ${url3}`,
+      code: CliError.Code.NetworkError
+    });
   }
 }
 
@@ -914229,7 +914457,10 @@ async function writeImageToFile(src, rootPath) {
   const filename = removeMetadataFromImageSrc(src);
   const imagePath = (0, import_node_path40.join)(rootPath, filename);
   if (!isValidImageSrc(filename)) {
-    throw new Error(`${filename} - file extension not supported`);
+    throw new CliError({
+      message: `${filename} - file extension not supported`,
+      code: CliError.Code.InternalError
+    });
   }
   if ((0, import_node_fs31.existsSync)(imagePath)) {
     return imagePath;
@@ -914237,14 +914468,17 @@ async function writeImageToFile(src, rootPath) {
   try {
     (0, import_node_fs31.mkdirSync)((0, import_node_path40.dirname)(imagePath), { recursive: true });
   } catch (error50) {
-    throw new Error(`${imagePath} - failed to create directory`);
+    throw new CliError({ message: `${imagePath} - failed to create directory`, code: CliError.Code.InternalError });
   }
   try {
     const imageData = await fetchImage(src);
     write2(imagePath, imageData);
     return imagePath;
   } catch (error50) {
-    throw new Error(`${imagePath}: failed to download file from source`);
+    throw new CliError({
+      message: `${imagePath}: failed to download file from source`,
+      code: CliError.Code.NetworkError
+    });
   }
 }
 function isValidImageSrc(src) {
@@ -914623,7 +914857,9 @@ async function runReadmeMigration({ readmeUrl, outputPath, taskContext, versionO
 // ../init/lib/initializeWithReadme.js
 var initializeWithReadme = async ({ readmeUrl, organization, taskContext, versionOfCli }) => {
   if (!readmeUrl || !isURL(readmeUrl)) {
-    taskContext.failAndThrow("Provide a URL to a readme-generated site");
+    taskContext.failAndThrow("Provide a URL to a readme-generated site", void 0, {
+      code: CliError.Code.ConfigError
+    });
     return;
   }
   const outputPath = AbsoluteFilePath2.of(cwd());
@@ -918984,7 +919220,7 @@ var CliContext = class _CliContext {
     if (false) {
       this.logger.error("CLI_VERSION is not defined");
     }
-    return "4.82.0";
+    return "4.83.0";
   }
   getCliName() {
     if (false) {
@@ -919286,7 +919522,9 @@ var import_promises127 = require("fs/promises");
 async function loadProject({ context: context3, nameOverride, ...args }) {
   const fernDirectory = await getFernDirectory(nameOverride);
   if (fernDirectory == null) {
-    return context3.failAndThrow(`Directory "${nameOverride ?? FERN_DIRECTORY}" not found.`);
+    return context3.failAndThrow(`Directory "${nameOverride ?? FERN_DIRECTORY}" not found.`, void 0, {
+      code: CliError.Code.ConfigError
+    });
   }
   return await loadProjectFromDirectory({
     absolutePathToFernDirectory: fernDirectory,
@@ -919327,7 +919565,7 @@ Or one of the following directories:
  \u203A ${ASYNCAPI_DIRECTORY}/
 For more information:
  \u203A SDK project structure: https://buildwithfern.com/learn/api-definitions/overview/project-structure
- \u203A Docs project structure: https://buildwithfern.com/learn/docs/getting-started/project-structure`);
+ \u203A Docs project structure: https://buildwithfern.com/learn/docs/getting-started/project-structure`, void 0, { code: CliError.Code.ConfigError });
   }
   return {
     config: await loadProjectConfig({ directory: absolutePathToFernDirectory, context: context3 }),
@@ -919354,10 +919592,12 @@ async function loadApis({ cliName, fernDirectory, context: context3, cliVersion,
     }, []);
     if (commandLineApiWorkspace != null) {
       if (!apiWorkspaceDirectoryNames.includes(commandLineApiWorkspace)) {
-        return context3.failAndThrow("API does not exist: " + commandLineApiWorkspace);
+        return context3.failAndThrow("API does not exist: " + commandLineApiWorkspace, void 0, {
+          code: CliError.Code.ConfigError
+        });
       }
     } else if (apiWorkspaceDirectoryNames.length === 0) {
-      return context3.failAndThrow("No APIs found.");
+      return context3.failAndThrow("No APIs found.", void 0, { code: CliError.Code.ConfigError });
     } else if (apiWorkspaceDirectoryNames.length > 1 && !defaultToAllApiWorkspaces) {
       let message = "There are multiple workspaces. You must specify one with --api:\n";
       const longestWorkspaceName = Math.max(...apiWorkspaceDirectoryNames.map((workspaceName) => workspaceName.length));
@@ -919365,7 +919605,7 @@ async function loadApis({ cliName, fernDirectory, context: context3, cliVersion,
         const suggestedCommand = `${cliName} ${process.argv.slice(2).join(" ")} --api ${workspaceName}`;
         return ` \u203A ${source_default.bold(workspaceName.padEnd(longestWorkspaceName))}  ${source_default.dim(suggestedCommand)}`;
       }).join("\n");
-      return context3.failAndThrow(message);
+      return context3.failAndThrow(message, void 0, { code: CliError.Code.ConfigError });
     }
     const apiWorkspaces = [];
     const filteredWorkspaces = commandLineApiWorkspace != null ? apiWorkspaceDirectoryNames.filter((api2) => {
@@ -919382,7 +919622,7 @@ async function loadApis({ cliName, fernDirectory, context: context3, cliVersion,
         apiWorkspaces.push(workspace2.workspace);
       } else {
         handleFailedWorkspaceParserResult(workspace2, context3.logger);
-        context3.failAndThrow();
+        context3.failAndThrow(void 0, void 0, { code: CliError.Code.ConfigError });
       }
     }));
     return apiWorkspaces;
@@ -925647,7 +925887,10 @@ function renderCompoundPage(compound, meta5) {
       return renderVariablePage(compound.data, meta5);
     default: {
       const _exhaustive = compound;
-      throw new Error(`Unknown compound kind: ${JSON.stringify(_exhaustive)}`);
+      throw new CliError({
+        message: `Unknown compound kind: ${JSON.stringify(_exhaustive)}`,
+        code: CliError.Code.InternalError
+      });
     }
   }
 }
@@ -925941,7 +926184,10 @@ function categoryFolderForCompound(collected) {
       return "variables";
     default: {
       const _exhaustive = collected.compound;
-      throw new Error(`Unknown compound kind: ${JSON.stringify(_exhaustive)}`);
+      throw new CliError({
+        message: `Unknown compound kind: ${JSON.stringify(_exhaustive)}`,
+        code: CliError.Code.InternalError
+      });
     }
   }
 }
@@ -927203,7 +927449,10 @@ function resolveTarget({
     return { type: "id", value: id };
   }
   if (target == null) {
-    throw new Error("Must provide a preview URL or --id.");
+    throw new CliError({
+      message: "Must provide a preview URL or --id.",
+      code: CliError.Code.ConfigError
+    });
   }
   if (isPreviewUrl(target)) {
     return { type: "url", value: target };
@@ -930646,7 +930895,7 @@ var JsonSchemaConverterContext = class {
         this.context.logger.error(`Type ${typeName} not found`);
       } else {
       }
-      return this.context.failAndThrow();
+      return this.context.failAndThrow(void 0, void 0, { code: CliError.Code.ReferenceError });
     }
     return typeDeclaration2;
   }
@@ -939621,10 +939870,16 @@ function addDocsPreviewDeleteCommand(cli, cliContext) {
     }).check((argv) => {
       const sources = [argv.target, argv.url, argv.id].filter(Boolean);
       if (sources.length === 0) {
-        throw new Error("Must provide a preview URL or --id.");
+        throw new CliError({
+          message: "Must provide a preview URL or --id.",
+          code: CliError.Code.ConfigError
+        });
       }
       if (sources.length > 1) {
-        throw new Error("Provide only one of: [target], --url, or --id.");
+        throw new CliError({
+          message: "Provide only one of: [target], --url, or --id.",
+          code: CliError.Code.ConfigError
+        });
       }
       return true;
     }),