(feature): Implement fern generate --preview (#3363)

packages/cli/cli/package.json

@@ -68,7 +68,7 @@
     "@fern-api/yaml-formatter": "workspace:*",
     "@fern-api/yaml-migrations": "workspace:*",
     "@fern-api/yaml-schema": "workspace:*",
-    "@fern-fern/fiddle-sdk": "^0.0.503",
+    "@fern-fern/fiddle-sdk": "^0.0.508",
     "ansi-escapes": "^5.0.0",
     "axios": "^0.28.0",
     "boxen": "^7.0.0",

packages/cli/cli/src/cli.ts

@@ -1,6 +1,6 @@
 import {
-    generatorsYml,
     fernConfigJson,
+    generatorsYml,
     GENERATORS_CONFIGURATION_FILENAME,
     getFernDirectory,
     PROJECT_CONFIG_FILENAME
@@ -352,8 +352,12 @@ function addGenerateCommand(cli: Argv<GlobalCliOptions>, cliContext: CliContext)
         async (argv) => {
             if (argv.api != null && argv.docs != null) {
                 return cliContext.failWithoutThrowing("Cannot specify both --api and --docs. Please choose one.");
-            } else if (argv.api != null) {
-                await generateAPIWorkspaces({
+            }
+            if (argv.local && argv.preview) {
+                return cliContext.failWithoutThrowing("The --local flag is incompatible with --preview.");
+            }
+            if (argv.api != null) {
+                return await generateAPIWorkspaces({
                     project: await loadProjectAndRegisterWorkspacesWithContext(cliContext, {
                         commandLineApiWorkspace: argv.api,
                         defaultToAllApiWorkspaces: false
@@ -363,16 +367,18 @@ function addGenerateCommand(cli: Argv<GlobalCliOptions>, cliContext: CliContext)
                     groupName: argv.group,
                     shouldLogS3Url: argv.printZipUrl,
                     keepDocker: argv.keepDocker,
-                    useLocalDocker: argv.local
+                    useLocalDocker: argv.local,
+                    preview: argv.preview
                 });
-            } else if (argv.docs != null) {
+            }
+            if (argv.docs != null) {
                 if (argv.group != null) {
                     cliContext.logger.warn("--group is ignored when generating docs");
                 }
                 if (argv.version != null) {
                     cliContext.logger.warn("--version is ignored when generating docs");
                 }
-                await generateDocsWorkspace({
+                return await generateDocsWorkspace({
                     project: await loadProjectAndRegisterWorkspacesWithContext(
                         cliContext,
                         {
@@ -385,21 +391,21 @@ function addGenerateCommand(cli: Argv<GlobalCliOptions>, cliContext: CliContext)
                     instance: argv.instance,
                     preview: argv.preview
                 });
-            } else {
-                // default to loading api workspace to preserve legacy behavior
-                await generateAPIWorkspaces({
-                    project: await loadProjectAndRegisterWorkspacesWithContext(cliContext, {
-                        commandLineApiWorkspace: argv.api,
-                        defaultToAllApiWorkspaces: false
-                    }),
-                    cliContext,
-                    version: argv.version,
-                    groupName: argv.group,
-                    shouldLogS3Url: argv.printZipUrl,
-                    keepDocker: argv.keepDocker,
-                    useLocalDocker: argv.local
-                });
             }
+            // default to loading api workspace to preserve legacy behavior
+            return await generateAPIWorkspaces({
+                project: await loadProjectAndRegisterWorkspacesWithContext(cliContext, {
+                    commandLineApiWorkspace: argv.api,
+                    defaultToAllApiWorkspaces: false
+                }),
+                cliContext,
+                version: argv.version,
+                groupName: argv.group,
+                shouldLogS3Url: argv.printZipUrl,
+                keepDocker: argv.keepDocker,
+                useLocalDocker: argv.local,
+                preview: argv.preview
+            });
         }
     );
 }

packages/cli/cli/src/commands/generate/generateAPIWorkspace.ts

@@ -4,6 +4,7 @@ import {
     fernConfigJson,
     GENERATORS_CONFIGURATION_FILENAME
 } from "@fern-api/configuration";
+import { AbsoluteFilePath } from "@fern-api/fs-utils";
 import { runLocalGenerationForWorkspace } from "@fern-api/local-workspace-runner";
 import { runRemoteGenerationForAPIWorkspace } from "@fern-api/remote-workspace-runner";
 import { TaskContext } from "@fern-api/task-context";
@@ -21,7 +22,8 @@ export async function generateWorkspace({
     shouldLogS3Url,
     token,
     useLocalDocker,
-    keepDocker
+    keepDocker,
+    absolutePathToPreview
 }: {
     organization: string;
     workspace: FernWorkspace;
@@ -33,6 +35,7 @@ export async function generateWorkspace({
     token: FernToken;
     useLocalDocker: boolean;
     keepDocker: boolean;
+    absolutePathToPreview: AbsoluteFilePath | undefined;
 }): Promise<void> {
     if (workspace.generatorsConfiguration == null) {
         context.logger.warn("This workspaces has no generators.yml");
@@ -77,7 +80,8 @@ export async function generateWorkspace({
             version,
             shouldLogS3Url,
             token,
-            whitelabel: workspace.generatorsConfiguration.whitelabel
+            whitelabel: workspace.generatorsConfiguration.whitelabel,
+            absolutePathToPreview
         });
     }
 }

packages/cli/cli/src/commands/generate/generateAPIWorkspaces.ts

@@ -1,8 +1,10 @@
 import { createOrganizationIfDoesNotExist } from "@fern-api/auth";
+import { join, RelativeFilePath } from "@fern-api/fs-utils";
 import { askToLogin } from "@fern-api/login";
 import { Project } from "@fern-api/project-loader";
 import { convertOpenApiWorkspaceToFernWorkspace, FernWorkspace } from "@fern-api/workspace-loader";
 import { CliContext } from "../../cli-context/CliContext";
+import { PREVIEW_DIRECTORY } from "../../constants";
 import { generateWorkspace } from "./generateAPIWorkspace";
 
 export async function generateAPIWorkspaces({
@@ -12,7 +14,8 @@ export async function generateAPIWorkspaces({
     groupName,
     shouldLogS3Url,
     keepDocker,
-    useLocalDocker
+    useLocalDocker,
+    preview
 }: {
     project: Project;
     cliContext: CliContext;
@@ -21,6 +24,7 @@ export async function generateAPIWorkspaces({
     shouldLogS3Url: boolean;
     useLocalDocker: boolean;
     keepDocker: boolean;
+    preview: boolean;
 }): Promise<void> {
     const token = await cliContext.runTask(async (context) => {
         return askToLogin(context);
@@ -69,6 +73,14 @@ export async function generateAPIWorkspaces({
                         ? workspace
                         : await convertOpenApiWorkspaceToFernWorkspace(workspace, context);
 
+                const absolutePathToPreview = preview
+                    ? join(fernWorkspace.absoluteFilepath, RelativeFilePath.of(PREVIEW_DIRECTORY))
+                    : undefined;
+
+                if (absolutePathToPreview != null) {
+                    context.logger.info(`Writing preview to ${absolutePathToPreview}`);
+                }
+
                 await generateWorkspace({
                     organization: project.config.organization,
                     workspace: fernWorkspace,
@@ -79,7 +91,8 @@ export async function generateAPIWorkspaces({
                     shouldLogS3Url,
                     token,
                     useLocalDocker,
-                    keepDocker
+                    keepDocker,
+                    absolutePathToPreview
                 });
             });
         })

packages/cli/cli/src/constants.ts

@@ -1,3 +1,4 @@
 export const API_CLI_OPTION = "api";
 export const GROUP_CLI_OPTION = "group";
 export const TOKEN_STDIN_OPTION = "token-stdin";
+export const PREVIEW_DIRECTORY = ".preview";

packages/cli/configuration/package.json

@@ -32,7 +32,7 @@
     "@fern-api/fdr-sdk": "0.73.1-9d67ec828",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/task-context": "workspace:*",
-    "@fern-fern/fiddle-sdk": "^0.0.503",
+    "@fern-fern/fiddle-sdk": "^0.0.508",
     "find-up": "^6.3.0",
     "immer": "^9.0.15",
     "js-yaml": "^4.1.0",

packages/cli/generation/local-generation/local-workspace-runner/package.json

@@ -35,7 +35,7 @@
     "@fern-api/logging-execa": "workspace:*",
     "@fern-api/task-context": "workspace:*",
     "@fern-api/workspace-loader": "workspace:*",
-    "@fern-fern/fiddle-sdk": "^0.0.503",
+    "@fern-fern/fiddle-sdk": "^0.0.508",
     "@fern-fern/generator-exec-sdk": "0.0.687",
     "chalk": "^5.0.1",
     "decompress": "^4.2.1",

packages/cli/generation/remote-generation/remote-workspace-runner/package.json

@@ -41,7 +41,7 @@
     "@fern-api/register": "workspace:*",
     "@fern-api/task-context": "workspace:*",
     "@fern-api/workspace-loader": "workspace:*",
-    "@fern-fern/fiddle-sdk": "^0.0.503",
+    "@fern-fern/fiddle-sdk": "^0.0.508",
     "axios": "^0.28.0",
     "chalk": "^5.0.1",
     "decompress": "^4.2.1",

packages/cli/generation/remote-generation/remote-workspace-runner/src/RemoteTaskHandler.ts

@@ -1,6 +1,6 @@
 import { generatorsYml } from "@fern-api/configuration";
 import { noop } from "@fern-api/core-utils";
-import { AbsoluteFilePath, doesPathExist } from "@fern-api/fs-utils";
+import { AbsoluteFilePath, doesPathExist, join, RelativeFilePath } from "@fern-api/fs-utils";
 import { LogLevel } from "@fern-api/logger";
 import { InteractiveTaskContext } from "@fern-api/task-context";
 import { FernFiddle } from "@fern-fern/fiddle-sdk";
@@ -20,6 +20,7 @@ export declare namespace RemoteTaskHandler {
         taskId: FernFiddle.remoteGen.RemoteGenTaskId;
         interactiveTaskContext: InteractiveTaskContext;
         generatorInvocation: generatorsYml.GeneratorInvocation;
+        absolutePathToPreview: AbsoluteFilePath | undefined;
     }
     export interface Response {
         createdSnippets: boolean;
@@ -30,11 +31,13 @@ export declare namespace RemoteTaskHandler {
 export class RemoteTaskHandler {
     private context: InteractiveTaskContext;
     private generatorInvocation: generatorsYml.GeneratorInvocation;
+    private absolutePathToPreview: AbsoluteFilePath | undefined;
     private lengthOfLastLogs = 0;
 
-    constructor({ interactiveTaskContext, generatorInvocation }: RemoteTaskHandler.Init) {
+    constructor({ interactiveTaskContext, generatorInvocation, absolutePathToPreview }: RemoteTaskHandler.Init) {
         this.context = interactiveTaskContext;
         this.generatorInvocation = generatorInvocation;
+        this.absolutePathToPreview = absolutePathToPreview;
     }
 
     public async processUpdate(
@@ -54,15 +57,17 @@ export class RemoteTaskHandler {
             });
         });
 
-        this.context.setSubtitle(
-            coordinates.length > 0
-                ? coordinates
-                      .map((coordinate) => {
-                          return `◦ ${coordinate}`;
-                      })
-                      .join("\n")
-                : undefined
-        );
+        if (this.absolutePathToPreview == null) {
+            this.context.setSubtitle(
+                coordinates.length > 0
+                    ? coordinates
+                          .map((coordinate) => {
+                              return `◦ ${coordinate}`;
+                          })
+                          .join("\n")
+                    : undefined
+            );
+        }
 
         for (const newLog of remoteTask.logs.slice(this.lengthOfLastLogs)) {
             this.context.logger.log(convertLogLevel(newLog.level), newLog.message);
@@ -89,16 +94,19 @@ export class RemoteTaskHandler {
             finished: async (finishedStatus) => {
                 if (finishedStatus.s3PreSignedReadUrlV2 != null) {
                     logS3Url(finishedStatus.s3PreSignedReadUrlV2);
-                    if (this.generatorInvocation.absolutePathToLocalOutput != null) {
+                    const absolutePathToLocalOutput = this.getAbsolutePathToLocalOutput();
+                    if (absolutePathToLocalOutput != null) {
                         await downloadFilesForTask({
                             s3PreSignedReadUrl: finishedStatus.s3PreSignedReadUrlV2,
-                            absolutePathToLocalOutput: this.generatorInvocation.absolutePathToLocalOutput,
+                            absolutePathToLocalOutput,
                             context: this.context
                         });
                     }
                 }
-                for (const coordinate of coordinates) {
-                    this.context.logger.info(`Published ${coordinate}`);
+                if (this.absolutePathToPreview == null) {
+                    for (const coordinate of coordinates) {
+                        this.context.logger.info(`Published ${coordinate}`);
+                    }
                 }
                 this.#isFinished = true;
                 this.#createdSnippets = finishedStatus.createdSnippets != null ? finishedStatus.createdSnippets : false;
@@ -117,6 +125,12 @@ export class RemoteTaskHandler {
             : undefined;
     }
 
+    private getAbsolutePathToLocalOutput(): AbsoluteFilePath | undefined {
+        return this.absolutePathToPreview != null
+            ? join(this.absolutePathToPreview, RelativeFilePath.of(path.basename(this.generatorInvocation.name)))
+            : this.generatorInvocation.absolutePathToLocalOutput;
+    }
+
     #isFinished = false;
     public get isFinished(): boolean {
         return this.#isFinished;