feat(@graphql-hive/cli): json output

.vscode/settings.json

@@ -28,5 +28,8 @@
     ["cx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"],
     ["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"],
     ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
-  ]
+  ],
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
 }

packages/libraries/cli/src/base-command.ts

@@ -1,19 +1,34 @@
 import colors from 'colors';
 import { print, type GraphQLError } from 'graphql';
 import type { ExecutionResult } from 'graphql';
+import { z } from 'zod';
 import { http } from '@graphql-hive/core';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { Command, Errors, Flags, Interfaces } from '@oclif/core';
 import { Config, GetConfigurationValueType, ValidConfigurationKeys } from './helpers/config';
+import { OmitNever, OptionalizePropertyUnsafe } from './helpers/general';
+import { OutputSchema } from './helpers/output-schema';
 
-export type Flags<T extends typeof Command> = Interfaces.InferredFlags<
-  (typeof BaseCommand)['baseFlags'] & T['flags']
->;
-export type Args<T extends typeof Command> = Interfaces.InferredArgs<T['args']>;
+export default abstract class BaseCommand<$Command extends typeof Command> extends Command {
+  public static enableJsonFlag = true;
 
-type OmitNever<T> = { [K in keyof T as T[K] extends never ? never : K]: T[K] };
+  /**
+   * The data type returned by this command when successfully executed.
+   *
+   * Used by the {@link BaseCommand.successData} method.
+   */
+  public static SuccessSchema: OutputSchema = OutputSchema.Envelope;
+
+  /**
+   * Whether to validate the data returned by the {@link BaseCommand.successData} method.
+   *
+   * WARNING: If disabling validation, then you must not any of Zod's value coercing features
+   * since they won't be run when validation is disabled.
+   *
+   * @defaultValue `true`
+   */
+  public SuccessSchemaValidationEnabled: boolean = true;
 
-export default abstract class BaseCommand<T extends typeof Command> extends Command {
   protected _userConfig: Config | undefined;
 
   static baseFlags = {
@@ -23,8 +38,9 @@
     }),
   };
 
-  protected flags!: Flags<T>;
-  protected args!: Args<T>;
+  protected flags!: Flags<$Command>;
+
+  protected args!: Args<$Command>;
 
   protected get userConfig(): Config {
     if (!this._userConfig) {
@@ -33,7 +49,7 @@
     return this._userConfig!;
   }
 
-  public async init(): Promise<void> {
+  async init(): Promise<void> {
     await super.init();
 
     this._userConfig = new Config({
@@ -45,26 +61,66 @@
     const { args, flags } = await this.parse({
       flags: this.ctor.flags,
       baseFlags: (super.ctor as typeof BaseCommand).baseFlags,
+      enableJsonFlag: this.ctor.enableJsonFlag,
       args: this.ctor.args,
       strict: this.ctor.strict,
     });
-    this.flags = flags as Flags<T>;
-    this.args = args as Args<T>;
+    this.flags = flags as Flags<$Command>;
+    this.args = args as Args<$Command>;
   }
 
-  success(...args: any[]) {
+  /**
+   * Helper function for creating data that adheres to the type specified by your command's {@link BaseCommand.SuccessSchema}.
+   *
+   * If {@link BaseCommand.SuccessSchemaValidationEnabled} is `true`, then the given data will be runtime-validated too.
+   *
+   * For ease of use some standard properties are added for you automatically, simplifying the input you have to provide.
+   */
+  successData(dataInput: InferSuccessDataInput<$Command>): InferSuccessDataOutput<$Command> {
+    const dataOutput = {
+      ...(dataInput as object),
+      ok: true,
+      // warnings: [] as string[],
+    } as InferSuccessDataOutput<$Command>;
+
+    if (this.SuccessSchemaValidationEnabled) {
+      // @ts-expect-error TS doesn't support static property access on this.constructor for some reason.
+      const schema = this.constructor.SuccessSchema as OutputSchema;
+      const result = schema.safeParse(dataOutput);
+      if (!result.success) {
+        throw new Errors.CLIError(result.error.message);
+      }
+      return result.data as InferSuccessDataOutput<$Command>;
+    }
+
+    return dataOutput;
+  }
+
+  /**
+   * {@link Command.log} with success styling.
+   */
+  logSuccess(...args: any[]) {
     this.log(colors.green('✔'), ...args);
   }
 
-  fail(...args: any[]) {
+  /**
+   * {@link Command.log} with failure styling.
+   */
+  logFail(...args: any[]) {
     this.log(colors.red('✖'), ...args);
   }
 
-  info(...args: any[]) {
+  /**
+   * {@link Command.log} with info styling.
+   */
+  logInfo(...args: any[]) {
     this.log(colors.yellow('ℹ'), ...args);
   }
 
-  infoWarning(...args: any[]) {
+  /**
+   * {@link Command.log} with warning styling.
+   */
+  logWarning(...args: any[]) {
     this.log(colors.yellow('⚠'), ...args);
   }
 
@@ -304,6 +360,28 @@
   }
 }
 
+export type Flags<T extends typeof Command> = Interfaces.InferredFlags<
+  (typeof BaseCommand)['baseFlags'] & T['flags']
+>;
+
+export type Args<T extends typeof Command> = Interfaces.InferredArgs<T['args']>;
+
+type InferSuccessDataOutput<$CommandClass extends typeof Command> =
+  'SuccessSchema' extends keyof $CommandClass
+    ? $CommandClass['SuccessSchema'] extends OutputSchema
+      ? z.infer<$CommandClass['SuccessSchema']>
+      : never
+    : never;
+
+type InferSuccessDataInput<$CommandClass extends typeof Command> =
+  'SuccessSchema' extends keyof $CommandClass
+    ? $CommandClass['SuccessSchema'] extends OutputSchema
+      ? Omit<z.infer<$CommandClass['SuccessSchema']>, 'ok'>
+      : InferSuccessDataInputError
+    : InferSuccessDataInputError;
+
+type InferSuccessDataInputError = 'Error: Missing `static SuccessSchema = ...` on your command.';
+
 function isClientError(error: Error): error is ClientError {
   return error instanceof ClientError;
 }

packages/libraries/cli/src/commands/app/create.ts

@@ -1,3 +1,4 @@
+import { OutputSchema } from 'src/helpers/output-schema';
 import { z } from 'zod';
 import { Args, Flags } from '@oclif/core';
 import Command from '../../base-command';
@@ -6,6 +7,22 @@ import { AppDeploymentStatus } from '../../gql/graphql';
 import { graphqlEndpoint } from '../../helpers/config';
 
 export default class AppCreate extends Command<typeof AppCreate> {
+  static SuccessSchema = z.union([
+    OutputSchema.Effect.Skipped.extend({
+      data: z.object({
+        // TODO improve type to match GQL Schema enum
+        status: OutputSchema.NonEmptyString,
+      }),
+    }),
+    OutputSchema.Effect.Executed.extend({
+      data: z.object({
+        id: OutputSchema.NonEmptyString,
+        name: OutputSchema.NonEmptyString,
+        version: OutputSchema.NonEmptyString,
+      }),
+    }),
+  ]);
+
   static description = 'create an app deployment';
   static flags = {
     'registry.endpoint': Flags.string({
@@ -79,10 +96,15 @@ export default class AppCreate extends Command<typeof AppCreate> {
     }
 
     if (result.createAppDeployment.ok.createdAppDeployment.status !== AppDeploymentStatus.Pending) {
-      this.log(
-        `App deployment "${flags['name']}@${flags['version']}" is "${result.createAppDeployment.ok.createdAppDeployment.status}". Skip uploading documents...`,
-      );
-      return;
+      const message = `App deployment "${flags['name']}@${flags['version']}" is "${result.createAppDeployment.ok.createdAppDeployment.status}". Skip uploading documents...`;
+      this.log(message);
+      return this.successData({
+        message,
+        effect: 'skipped',
+        data: {
+          status: result.createAppDeployment.ok.createdAppDeployment.status,
+        },
+      });
     }
 
     let buffer: Array<{ hash: string; body: string }> = [];
@@ -114,7 +136,7 @@ export default class AppCreate extends Command<typeof AppCreate> {
                   ? affectedOperation.body.substring(0, maxCharacters) + '...'
                   : affectedOperation.body
               ).replace(/\n/g, '\\n');
-              this.infoWarning(
+              this.logWarning(
                 `Failed uploading document: ${result.addDocumentsToAppDeployment.error.details.message}` +
                   `\nOperation hash: ${affectedOperation?.hash}` +
                   `\nOperation body: ${truncatedBody}`,
@@ -137,9 +159,17 @@ export default class AppCreate extends Command<typeof AppCreate> {
 
     await flush(true);
 
-    this.log(
-      `\nApp deployment "${flags['name']}@${flags['version']}" (${counter} operations) created.\nActive it with the "hive app:publish" command.`,
-    );
+    const message = `App deployment "${flags['name']}@${flags['version']}" (${counter} operations) created.\nActivate it with the "hive app:publish" command.`;
+    this.log(message);
+    return this.successData({
+      message,
+      effect: 'executed',
+      data: {
+        id: result.createAppDeployment.ok.createdAppDeployment.id,
+        name: flags['name'],
+        version: flags['version'],
+      },
+    });
   }
 }
 

packages/libraries/cli/src/commands/app/publish.ts

@@ -1,9 +1,24 @@
+import { OutputSchema } from 'src/helpers/output-schema';
+import { z } from 'zod';
 import { Flags } from '@oclif/core';
 import Command from '../../base-command';
 import { graphql } from '../../gql';
 import { graphqlEndpoint } from '../../helpers/config';
 
 export default class AppPublish extends Command<typeof AppPublish> {
+  static SuccessSchema = z.union([
+    OutputSchema.Effect.Skipped.extend({
+      data: z.object({
+        name: OutputSchema.NonEmptyString,
+      }),
+    }),
+    OutputSchema.Effect.Executed.extend({
+      data: z.object({
+        name: OutputSchema.NonEmptyString,
+      }),
+    }),
+  ]);
+
   static description = 'publish an app deployment';
   static flags = {
     'registry.endpoint': Flags.string({
@@ -55,10 +70,25 @@ export default class AppPublish extends Command<typeof AppPublish> {
       const name = `${result.activateAppDeployment.ok.activatedAppDeployment.name}@${result.activateAppDeployment.ok.activatedAppDeployment.version}`;
 
       if (result.activateAppDeployment.ok.isSkipped) {
-        this.warn(`App deployment "${name}" is already published. Skipping...`);
-        return;
+        const message = `App deployment "${name}" is already published. Skipping...`;
+        this.warn(message);
+        return this.successData({
+          message,
+          effect: 'skipped',
+          data: {
+            name,
+          },
+        });
       }
-      this.log(`App deployment "${name}" published successfully.`);
+      const message = `App deployment "${name}" published successfully.`;
+      this.log(message);
+      return this.successData({
+        message,
+        effect: 'executed',
+        data: {
+          name,
+        },
+      });
     }
   }
 }

packages/libraries/cli/src/commands/artifact/fetch.ts

@@ -1,8 +1,19 @@
+import { OutputSchema } from 'src/helpers/output-schema';
+import { z } from 'zod';
 import { http, URL } from '@graphql-hive/core';
 import { Flags } from '@oclif/core';
 import Command from '../../base-command';
 
 export default class ArtifactsFetch extends Command<typeof ArtifactsFetch> {
+  static SuccessSchema = z.union([
+    OutputSchema.Envelope.extend({
+      data: OutputSchema.DataOutputMode.File,
+    }),
+    OutputSchema.Envelope.extend({
+      data: OutputSchema.DataOutputMode.Stdout,
+    }),
+  ]);
+
   static description = 'fetch artifacts from the CDN';
   static flags = {
     'cdn.endpoint': Flags.string({
@@ -69,10 +80,24 @@ export default class ArtifactsFetch extends Command<typeof ArtifactsFetch> {
       const fs = await import('fs/promises');
       const contents = Buffer.from(await response.arrayBuffer());
       await fs.writeFile(flags.outputFile, contents);
-      this.log(`Wrote ${contents.length} bytes to ${flags.outputFile}`);
-      return;
+      const message = `Wrote ${contents.length} bytes to ${flags.outputFile}`;
+      this.log(message);
+      return this.successData({
+        message,
+        data: {
+          outputMode: 'file',
+          path: flags.outputFile,
+        },
+      });
     }
 
-    this.log(await response.text());
+    const content = await response.text();
+    this.log(content);
+    return this.successData({
+      data: {
+        outputMode: 'stdout',
+        content,
+      },
+    });
   }
 }

packages/libraries/cli/src/commands/config/delete.ts

@@ -1,9 +1,18 @@
+import { OutputSchema } from 'src/helpers/output-schema';
+import { z } from 'zod';
 import { Args } from '@oclif/core';
 import Command from '../../base-command';
 
 export default class DeleteConfig extends Command<typeof DeleteConfig> {
-  static description = 'deletes specific cli configuration';
+  static SuccessSchema = OutputSchema.Envelope.extend({
+    data: z.object({
+      key: OutputSchema.NonEmptyString,
+    }),
+  });
+  static description = 'delete a specific cli configuration key';
   static args = {
+    // TODO Terms like "property" or "setting" are more clear.
+    // "key" is overloaded with authN/authZ concepts.
     key: Args.string({
       name: 'key',
       required: true,
@@ -14,6 +23,13 @@ export default class DeleteConfig extends Command<typeof DeleteConfig> {
   async run() {
     const { args } = await this.parse(DeleteConfig);
     this._userConfig!.delete(args.key);
-    this.success(this.bolderize(`Config flag "${args.key}" was deleted`));
+    const message = `Config key "${args.key}" was deleted`;
+    this.logSuccess(this.bolderize(message));
+    return this.successData({
+      message,
+      data: {
+        key: args.key,
+      },
+    });
   }
 }