fix(cli): improve error messages for node 17 or below incompatibility (…

…#4997)

generators/typescript/utils/core-utilities/fetcher/src/fetcher/Fetcher.ts

@@ -21,7 +21,7 @@ export declare namespace Fetcher {
         withCredentials?: boolean;
         abortSignal?: AbortSignal;
         requestType?: "json" | "file" | "bytes";
-        responseType?: "json" | "blob" | "sse" | "streaming" | "text";
+        responseType?: "json" | "blob" | "sse" | "streaming" | "text" | "arrayBuffer";
         duplex?: "half";
     }
 

generators/typescript/utils/core-utilities/fetcher/src/fetcher/getResponseBody.ts

@@ -3,6 +3,8 @@ import { chooseStreamWrapper } from "./stream-wrappers/chooseStreamWrapper";
 export async function getResponseBody(response: Response, responseType?: string): Promise<unknown> {
     if (response.body != null && responseType === "blob") {
         return await response.blob();
+    } else if (response.body != null && responseType === "arrayBuffer") {
+        return await response.arrayBuffer();
     } else if (response.body != null && responseType === "sse") {
         return response.body;
     } else if (response.body != null && responseType === "streaming") {

packages/cli/cli/package.json

@@ -76,6 +76,7 @@
     "@fern-api/workspace-loader": "workspace:*",
     "@fern-fern/fiddle-sdk": "0.0.584",
     "@fern-fern/generators-sdk": "0.114.0-5745f9e74",
+    "@fern-typescript/fetcher": "workspace:*",
     "@types/axios": "^0.14.0",
     "@types/boxen": "^3.0.1",
     "@types/get-port": "^4.2.0",
@@ -113,5 +114,5 @@
     "vitest": "^2.0.5",
     "yaml": "^2.4.5",
     "yargs": "^17.4.1"
-  } 
+  }
 }

packages/cli/cli/src/cli-context/CliContext.ts

@@ -174,6 +174,7 @@ export class CliContext {
         return context;
     }
 
+    private readonly USE_NODE_18_OR_ABOVE_MESSAGE = "The Fern CLI requires Node 18+ or above.";
     private async runTaskWithInit<T>(
         init: TaskContextImpl.Init,
         run: (context: TaskContext) => T | Promise<T>
@@ -183,7 +184,12 @@ export class CliContext {
         try {
             result = await run(context);
         } catch (error) {
-            context.failWithoutThrowing(undefined, error);
+            if ((error as Error).message.includes("globalThis")) {
+                context.logger.error(this.USE_NODE_18_OR_ABOVE_MESSAGE);
+                context.failWithoutThrowing();
+            } else {
+                context.failWithoutThrowing(undefined, error);
+            }
             throw new FernCliError();
         } finally {
             context.finish();

packages/cli/cli/src/cli.ts

@@ -44,19 +44,25 @@ import { rerunFernCliAtVersion } from "./rerunFernCliAtVersion";
 import { isURL } from "./utils/isUrl";
 import { generateJsonschemaForWorkspaces } from "./commands/jsonschema/generateJsonschemaForWorkspace";
 import { generateDynamicIrForWorkspaces } from "./commands/generate-dynamic-ir/generateDynamicIrForWorkspaces";
-import { setGlobalDispatcher, Agent } from "undici";
 import { writeDocsDefinitionForProject } from "./commands/write-docs-definition/writeDocsDefinitionForProject";
-
-setGlobalDispatcher(new Agent({ connect: { timeout: 5_000 } }));
+import { RUNTIME } from "@fern-typescript/fetcher";
 
 void runCli();
 
+const USE_NODE_18_OR_ABOVE_MESSAGE = "The Fern CLI requires Node 18+ or above.";
+
 async function runCli() {
     const cliContext = new CliContext(process.stdout);
 
     const exit = async () => {
         await cliContext.exit();
     };
+
+    if (RUNTIME.type === "node" && RUNTIME.parsedVersion != null && RUNTIME.parsedVersion >= 18) {
+        const { setGlobalDispatcher, Agent } = await import("undici");
+        setGlobalDispatcher(new Agent({ connect: { timeout: 5_000 } }));
+    }
+
     // eslint-disable-next-line @typescript-eslint/no-misused-promises
     process.on("SIGINT", async () => {
         cliContext.suppressUpgradeMessage();
@@ -85,7 +91,10 @@ async function runCli() {
                 error
             }
         });
-        if (error instanceof FernCliError) {
+        if ((error as Error)?.message.includes("globalThis")) {
+            cliContext.logger.error(USE_NODE_18_OR_ABOVE_MESSAGE);
+            cliContext.failWithoutThrowing();
+        } else if (error instanceof FernCliError) {
             // thrower is responsible for logging, so we generally don't need to log here.
             cliContext.failWithoutThrowing();
         } else if (error instanceof LoggableFernCliError) {

packages/cli/cli/tsconfig.json

@@ -37,6 +37,7 @@
     { "path": "../cli-migrations" },
     { "path": "../fern-definition/schema" },
     { "path": "../fern-definition/ir-to-jsonschema" },
-    { "path": "../docs-resolver" }
+    { "path": "../docs-resolver" },
+    { "path": "../../../generators/typescript/utils/commons"}
   ]
 }

packages/cli/cli/versions.yml

@@ -1,3 +1,9 @@
+- changelogEntry:
+    - summary: |
+        `fern docs dev` now runs in Node 16 - Node 22 environments.
+      type: fix
+  irVersion: 53
+  version: 0.45.0-rc24
 
 - changelogEntry:
     - summary: |

packages/cli/docs-preview/package.json

@@ -36,10 +36,12 @@
     "@fern-api/project-loader": "workspace:*",
     "@fern-api/register": "workspace:*",
     "@fern-api/task-context": "workspace:*",
+    "@fern-typescript/fetcher": "workspace:*",
     "chalk": "^5.3.0",
     "cors": "^2.8.5",
     "decompress": "^4.2.1",
     "express": "^4.20.0",
+    "readable-stream": "^4.5.2",
     "tmp-promise": "^3.0.3",
     "uuid": "^9.0.1",
     "watcher": "^2.3.1",
@@ -51,6 +53,7 @@
     "@types/decompress": "^4.2.7",
     "@types/express": "^4.17.21",
     "@types/node": "18.7.18",
+    "@types/readable-stream": "^4.0.15",
     "@types/uuid": "^9.0.8",
     "@types/ws": "^8.5.10",
     "@types/xml2js": "^0.4.14",
@@ -62,4 +65,4 @@
     "typescript": "4.6.4",
     "vitest": "^2.0.5"
   }
-}
+}

packages/cli/docs-preview/src/downloadLocalDocsBundle.ts

@@ -1,13 +1,14 @@
 import { AbsoluteFilePath, doesPathExist, join, RelativeFilePath } from "@fern-api/fs-utils";
 import { Logger } from "@fern-api/logger";
 import decompress from "decompress";
-import { createWriteStream } from "fs";
+import { Readable } from "readable-stream";
 import { mkdir, readFile, rm, writeFile } from "fs/promises";
 import { homedir } from "os";
 import path from "path";
-import { pipeline } from "stream/promises";
 import tmp from "tmp-promise";
 import xml2js from "xml2js";
+import { fetcher } from "@fern-typescript/fetcher";
+import fs from "fs";
 
 const ETAG_FILENAME = "etag";
 const PREVIEW_FOLDER_NAME = "preview";
@@ -66,8 +67,18 @@ export async function downloadBundle({
     preferCached: boolean;
 }): Promise<DownloadLocalBundle.Result> {
     logger.debug("Setting up docs preview bundle...");
-    const response = await fetch(bucketUrl);
-    const body = await response.text();
+    const response = await fetcher<string>({
+        url: bucketUrl,
+        method: "GET",
+        responseType: "text",
+        duplex: "half"
+    });
+    if (!response.ok) {
+        return {
+            type: "failure"
+        };
+    }
+    const body = response.body;
     const parser = new xml2js.Parser();
     const parsedResponse = await parser.parseStringPromise(body);
     const eTag = parsedResponse?.ListBucketResult?.Contents?.[0]?.ETag?.[0];
@@ -99,10 +110,15 @@ export async function downloadBundle({
 
     logger.debug(`Downloading docs preview bundle from ${path.join(bucketUrl, key)}`);
     // download docs bundle
-    const docsBundleZipResponse = await fetch(`${path.join(bucketUrl, key)}`);
+    const docsBundleZipResponse = await fetcher<unknown>({
+        url: `${path.join(bucketUrl, key)}`,
+        method: "GET",
+        responseType: "arrayBuffer",
+        duplex: "half"
+    });
 
     if (!docsBundleZipResponse.ok) {
-        logger.error(`Failed to download docs preview bundle. ${docsBundleZipResponse.statusText}`);
+        logger.error("Failed to download docs preview bundle.");
         return {
             type: "failure"
         };
@@ -115,8 +131,10 @@ export async function downloadBundle({
             type: "failure"
         };
     }
+
     // eslint-disable-next-line  @typescript-eslint/no-explicit-any
-    await pipeline(contents as any, createWriteStream(outputZipPath));
+    const nodeBuffer = Buffer.from(contents as any);
+    await writeFile(outputZipPath, nodeBuffer);
     logger.debug(`Wrote output.zip to ${outputZipPath}`);
 
     const absolutePathToPreviewFolder = getPathToPreviewFolder();

packages/cli/docs-preview/src/runPreviewServer.ts

@@ -77,12 +77,13 @@ export async function runPreviewServer({
             await downloadBundle({ bucketUrl: url, logger: context.logger, preferCached: true });
         } catch (err) {
             const pathToBundle = getPathToBundleFolder();
+            if (err instanceof Error) {
+                context.logger.debug(`Failed to download latest docs bundle: ${(err as Error).message}`);
+            }
             if (await doesPathExist(pathToBundle)) {
-                context.logger.warn("Failed to download latest docs application. Falling back to existing bundle.");
+                context.logger.warn("Falling back to cached bundle...");
             } else {
-                context.logger.warn(
-                    "Failed to download docs application. Please reach out to [email protected]."
-                );
+                context.logger.warn("Please reach out to [email protected].");
                 return;
             }
         }

packages/cli/docs-preview/tsconfig.json

@@ -9,6 +9,7 @@
     { "path": "../logger" },
     { "path": "../project-loader" },
     { "path": "../register" },
-    { "path": "../task-context" }
+    { "path": "../task-context" },
+    { "path": "../../../generators/typescript/utils/core-utilities/fetcher"}
   ]
 }