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

.vscode/settings.json

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

CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Welcome
+
+> [!IMPORTANT]
+>
+> This guide extends the
+> [core Guild contributing guide](https://github.com/the-guild-org/Stack/blob/master/CONTRIBUTING.md).
+> If you haven't read it yet or recently (e.g. past year), please read it first.
+
+## Setup
+
+1. `corepack enable`
+2. `pnpm install`
+3. `pnpm build:libraries`
+4. `pnpm build:services`
+4. `pnpm build`

packages/libraries/apollo/src/version.ts

@@ -1 +1 @@
-export const version = '0.36.2';
+export const version = '0.36.3';

packages/libraries/cli/README.md

@@ -17,12 +17,10 @@ A CLI util to manage and control your Hive.
 If you are running a JavaScript/NodeJS project, you can install Hive CLI from the `npm` registry:
 
 ```
-pnpm install -D @graphql-hive/cli
-yarn add -D @graphql-hive/cli
-npm install -D @graphql-hive/cli
+npm add -D @graphql-hive/cli
 ```
 
-> We recommend installing Hive CLI as part of your project, under `devDependencies`, instead of
+> [!NOTE] We recommend installing Hive CLI as part of your project, under `devDependencies`, instead of
 > using a global installation.
 
 ### Binary

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

@@ -1,19 +1,30 @@
 import colors from 'colors';
 import { print, type GraphQLError } from 'graphql';
 import type { ExecutionResult } from 'graphql';
+import { z, ZodUnion } 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 { PrettyPrintableError } from '@oclif/core/lib/interfaces';
 import { Config, GetConfigurationValueType, ValidConfigurationKeys } from './helpers/config';
 
-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 successDataSchema: OptionalSuccessSchema = undefined;
+
+  /**
+   * Whether to validate the data returned by the {@link BaseCommand.successData} method.
+   *
+   * @defaultValue `true`
+   */
+  public successDataValidateEnabled: boolean = true;
 
-export default abstract class BaseCommand<T extends typeof Command> extends Command {
   protected _userConfig: Config | undefined;
 
   static baseFlags = {
@@ -23,8 +34,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 +45,7 @@
     return this._userConfig!;
   }
 
-  public async init(): Promise<void> {
+  async init(): Promise<void> {
     await super.init();
 
     this._userConfig = new Config({
@@ -48,8 +60,22 @@
       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>;
+  }
+
+  /**
+   * Helper function that accepts the type of this command's {@link BaseCommand.successDataSchema}.
+   *
+   * If {@link BaseCommand.successDataValidateEnabled} is `true`, the data will be runtime-validated too.
+   * Otherwise this is just an identity function, convenient for static type checking.
+   */
+  successData<$Data extends InferConstraintSuccessData<$Command>>(data: $Data): $Data {
+    // this['successDataSchema']
+    // TODO apply the zod schema for runtime validation. This would guarantee that
+    // only valid data is ever returned. If the validation fails, we should throw an oclif cli error or whatever
+    // and maybe also attempt to send some telemetry data about the error so that our team can fix the issue.
+    return data;
   }
 
   success(...args: any[]) {
@@ -304,6 +330,29 @@
   }
 }
 
+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 OmitNever<T> = { [K in keyof T as T[K] extends never ? never : K]: T[K] };
+
+type InferConstraintSuccessData<$CommandClass extends typeof Command> =
+  'successDataSchema' extends keyof $CommandClass
+    ? $CommandClass['successDataSchema'] extends SuccessSchema
+      ? z.infer<$CommandClass['successDataSchema']>
+      : 'Error: Missing `static successDataSchema = ...` on your command.'
+    : 'Error: Missing `static successDataSchema = ...` on your command.';
+
+type OptionalSuccessSchema = undefined | SuccessSchema;
+
+type SuccessSchema =
+  | z.SomeZodObject
+  | z.ZodUnion<[z.SomeZodObject, z.SomeZodObject]>
+  | z.ZodUnion<[z.SomeZodObject, z.SomeZodObject, z.SomeZodObject]>
+  | z.ZodUnion<[z.SomeZodObject, z.SomeZodObject, z.SomeZodObject, z.SomeZodObject]>;
+
 function isClientError(error: Error): error is ClientError {
   return error instanceof ClientError;
 }

packages/libraries/cli/src/commands/introspect.ts

@@ -1,11 +1,23 @@
 import { writeFileSync } from 'node:fs';
 import { extname, resolve } from 'node:path';
 import { buildSchema, GraphQLError, introspectionFromSchema } from 'graphql';
+import { z } from 'zod';
 import { Args, Flags } from '@oclif/core';
 import Command from '../base-command';
 import { loadSchema } from '../helpers/schema';
 
 export default class Introspect extends Command<typeof Introspect> {
+  static successDataSchema = z.union([
+    z.object({
+      type: z.literal('file'),
+      path: z.string(),
+    }),
+    z.object({
+      type: z.literal('stdout'),
+      schema: z.string(),
+    }),
+  ]);
+
   static description = 'introspects a GraphQL Schema';
   static flags = {
     write: Flags.string({
@@ -63,7 +75,10 @@ export default class Introspect extends Command<typeof Introspect> {
 
     if (!flags.write) {
       this.log(schema);
-      return;
+      return this.successData({
+        type: 'stdout',
+        schema,
+      });
     }
 
     if (flags.write) {
@@ -94,6 +109,10 @@ export default class Introspect extends Command<typeof Introspect> {
       }
 
       this.success(`Saved to ${filepath}`);
+      return this.successData({
+        type: 'file',
+        path: filepath,
+      });
     }
   }
 }

packages/libraries/cli/src/commands/whoami.ts

@@ -1,4 +1,5 @@
 import colors from 'colors';
+import { z } from 'zod';
 import { Flags } from '@oclif/core';
 import Command from '../base-command';
 import { graphql } from '../gql';
@@ -33,6 +34,18 @@
 `);
 
 export default class WhoAmI extends Command<typeof WhoAmI> {
+  static successDataSchema = z.object({
+    tokenName: z.string(),
+    organization: z.string(),
+    project: z.string(),
+    target: z.string(),
+    authorization: z.object({
+      schema: z.object({
+        publish: z.boolean(),
+        check: z.boolean(),
+      }),
+    }),
+  });
   static description = 'shows information about the current token';
   static flags = {
     'registry.endpoint': Flags.string({
@@ -109,7 +122,20 @@
       });
 
       this.log(print());
+
+      return this.successData({
+        tokenName: tokenInfo.token.name,
+        organization: organization.slug,
+        project: project.slug,
+        target: target.slug,
+        authorization: {
+          schema: {
+            publish: tokenInfo.canPublishSchema,
+            check: tokenInfo.canCheckSchema,
+          },
+        },
+      });
     } else if (result.tokenInfo.__typename === 'TokenNotFoundError') {
       this.error(`Token not found. Reason: ${result.tokenInfo.message}`, {
         exit: 0,
         suggestions: [`How to create a token? https://docs.graphql-hive.com/features/tokens`],

packages/libraries/envelop/src/version.ts

@@ -1 +1 @@
-export const version = '0.33.10';
+export const version = '0.33.11';

packages/libraries/yoga/src/version.ts

@@ -1 +1 @@
-export const version = '0.39.0';
+export const version = '0.39.1';