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

.changeset/olive-ducks-fold.md

@@ -0,0 +1,16 @@
+---
+'@graphql-hive/cli': minor
+---
+
+Add JSON output mode.
+
+All commands now have a `--json` flag that will enable JSON output as opposed to plain text.
+
+Caveats:
+
+- The `dev` command is not yet supported.
+- Common command output cases have been updated to support JSON output, but coverage is not 100% complete, in particular failure cases.
+- There is no official documentation for the schema. For now, just try it out to see what outputs you get, or review to the source code. Its accessible: each command has its own module that contains its declaratively defined output schema (using Typebox).
+
+
+Remember that the Hive CLI is pre-1.0.0 and every minor release could bring breaking changes. Going forward we will mention in the changelog any time the schema has breaking changes.

.github/workflows/tests-integration.yaml

@@ -71,8 +71,6 @@ jobs:
 
       - name: run integration tests
         timeout-minutes: 10
-        env:
-          HIVE_DEBUG: 1
         run: |
           VITEST_MAX_THREADS=${{ steps.cpu-cores.outputs.count }} pnpm --filter integration-tests test:integration --shard=${{ matrix.shardIndex }}/3
 

.vscode/settings.json

@@ -1,4 +1,9 @@
 {
+  "search.exclude": {
+    "**/dist": true,
+    "**/pnpm-lock.yaml": true,
+    "**/*.tsbuildinfo": true
+  },
   "commands.commands": [
     {
       "command": "terminals.runTerminals",
@@ -28,5 +33,8 @@
     ["cx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"],
     ["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"],
     ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
-  ]
+  ],
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
 }

codegen.mts

@@ -85,7 +85,7 @@ const config: CodegenConfig = {
     },
     // CLI
     './packages/libraries/cli/src/gql/': {
-      documents: ['./packages/libraries/cli/src/(commands|helpers)/**/*.ts'],
+      documents: ['./packages/libraries/cli/src/(commands|fragments)/**/*.ts'],
       preset: 'client',
       plugins: [],
       config: {

integration-tests/package.json

@@ -21,6 +21,7 @@
     "@hive/schema": "workspace:*",
     "@hive/server": "workspace:*",
     "@hive/storage": "workspace:*",
+    "@sinclair/typebox": "^0.34.12",
     "@trpc/client": "10.45.2",
     "@trpc/server": "10.45.2",
     "@types/async-retry": "1.4.8",
@@ -36,7 +37,7 @@
     "slonik": "30.4.4",
     "strip-ansi": "7.1.0",
     "tslib": "2.8.1",
-    "vitest": "2.0.5",
+    "vitest": "2.1.8",
     "zod": "3.23.8"
   }
 }

integration-tests/testkit/cli.ts

@@ -1,38 +1,27 @@
 import { randomUUID } from 'node:crypto';
-import { writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { execaCommand } from '@esm2cjs/execa';
 import { fetchLatestSchema, fetchLatestValidSchema } from './flow';
+import { generateTmpFile } from './fs';
 import { getServiceHost } from './utils';
 
 const binPath = resolve(__dirname, '../../packages/libraries/cli/bin/run');
 const cliDir = resolve(__dirname, '../../packages/libraries/cli');
 
-async function generateTmpFile(content: string, extension: string) {
-  const dir = tmpdir();
-  const fileName = randomUUID();
-  const filepath = join(dir, `${fileName}.${extension}`);
-
-  await writeFile(filepath, content, 'utf-8');
-
-  return filepath;
-}
-
-async function exec(cmd: string) {
-  const outout = await execaCommand(`${binPath} ${cmd}`, {
+export async function exec(cmd: string) {
+  const result = await execaCommand(`${binPath} ${cmd}`, {
     shell: true,
     env: {
       OCLIF_CLI_CUSTOM_PATH: cliDir,
       NODE_OPTIONS: '--no-deprecation',
     },
   });
 
-  if (outout.failed) {
-    throw new Error(outout.stderr);
+  if (result.failed) {
+    throw new Error('CLI execution marked as "failed".', { cause: result.stderr });
   }
 
-  return outout.stdout;
+  return result.stdout;
 }
 
 export async function schemaPublish(args: string[]) {
@@ -70,6 +59,8 @@ async function dev(args: string[]) {
   );
 }
 
+export type CLI = ReturnType<typeof createCLI>;
+
 export function createCLI(tokens: { readwrite: string; readonly: string }) {
   let publishCount = 0;
 
@@ -81,6 +72,7 @@ export function createCLI(tokens: { readwrite: string; readonly: string }) {
     expect: expectedStatus,
     legacy_force,
     legacy_acceptBreakingChanges,
+    json,
   }: {
     sdl: string;
     commit?: string;
@@ -90,6 +82,7 @@ export function createCLI(tokens: { readwrite: string; readonly: string }) {
     legacy_force?: boolean;
     legacy_acceptBreakingChanges?: boolean;
     expect: 'latest' | 'latest-composable' | 'ignored' | 'rejected';
+    json?: boolean;
   }): Promise<string> {
     const publishName = ` #${++publishCount}`;
     const commit = randomUUID();
@@ -106,6 +99,7 @@ export function createCLI(tokens: { readwrite: string; readonly: string }) {
       ...(metadata ? ['--metadata', await generateTmpFile(JSON.stringify(metadata), 'json')] : []),
       ...(legacy_force ? ['--force'] : []),
       ...(legacy_acceptBreakingChanges ? ['--experimental_acceptBreakingChanges'] : []),
+      ...(json ? ['--json'] : []),
       await generateTmpFile(sdl, 'graphql'),
     ]);
 
@@ -177,15 +171,18 @@ export function createCLI(tokens: { readwrite: string; readonly: string }) {
     sdl,
     serviceName,
     expect: expectedStatus,
+    json,
   }: {
     sdl: string;
     serviceName?: string;
     expect: 'approved' | 'rejected';
+    json?: boolean;
   }): Promise<string> {
     const cmd = schemaCheck([
       '--registry.accessToken',
       tokens.readonly,
       ...(serviceName ? ['--service', serviceName] : []),
+      ...(json ? ['--json'] : []),
       await generateTmpFile(sdl, 'graphql'),
     ]);
 
@@ -199,11 +196,19 @@ export function createCLI(tokens: { readwrite: string; readonly: string }) {
   async function deleteCommand({
     serviceName,
     expect: expectedStatus,
+    json,
   }: {
     serviceName?: string;
+    json?: boolean;
     expect: 'latest' | 'latest-composable' | 'rejected';
   }): Promise<string> {
-    const cmd = schemaDelete(['--token', tokens.readwrite, '--confirm', serviceName ?? '']);
+    const cmd = schemaDelete([
+      '--token',
+      tokens.readwrite,
+      '--confirm',
+      serviceName ?? '',
+      ...(json ? ['--json'] : []),
+    ]);
 
     const before = {
       latest: await fetchLatestSchema(tokens.readonly).then(r => r.expectNoGraphQLErrors()),
@@ -259,11 +264,13 @@ export function createCLI(tokens: { readwrite: string; readonly: string }) {
       url: string;
       sdl: string;
     }>;
+    json?: boolean;
     remote: boolean;
     write?: string;
     useLatestVersion?: boolean;
   }) {
     return dev([
+      ...(input.json ? ['--json'] : []),
       ...(input.remote
         ? [
             '--remote',

integration-tests/testkit/fs.ts

@@ -0,0 +1,27 @@
+import { randomUUID } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export function tmpFile(extension: string) {
+  const dir = tmpdir();
+  const fileName = randomUUID();
+  const filepath = join(dir, `${fileName}.${extension}`);
+
+  return {
+    filepath,
+    read() {
+      return readFile(filepath, 'utf-8');
+    },
+  };
+}
+
+export async function generateTmpFile(content: string, extension: string) {
+  const dir = tmpdir();
+  const fileName = randomUUID();
+  const filepath = join(dir, `${fileName}.${extension}`);
+
+  await writeFile(filepath, content, 'utf-8');
+
+  return filepath;
+}

integration-tests/testkit/seed.ts

@@ -62,6 +62,12 @@ import { UpdateSchemaPolicyForOrganization, UpdateSchemaPolicyForProject } from
 import { collect, CollectedOperation, legacyCollect } from './usage';
 import { generateUnique } from './utils';
 
+export type Seed = ReturnType<typeof initSeed>;
+export type OwnerSeed = Awaited<ReturnType<Seed['createOwner']>>;
+export type OrgSeed = Awaited<ReturnType<OwnerSeed['createOrg']>>;
+export type ProjectSeed = Awaited<ReturnType<OrgSeed['createProject']>>;
+export type TargetAccessTokenSeed = Awaited<ReturnType<ProjectSeed['createTargetAccessToken']>>;
+
 export function initSeed() {
   const pg = {
     user: ensureEnv('POSTGRES_USER'),

integration-tests/testkit/test.ts

@@ -0,0 +1,102 @@
+/**
+ * This module uses Vitest's fixture system to make common usage patterns
+ * of our testkit easily consumable in test cases. @see https://vitest.dev/guide/test-context.html#test-extend
+ */
+
+import { test as testBase } from 'vitest';
+import { CLI, createCLI } from './cli';
+import { ProjectType } from './gql/graphql';
+import { initSeed, OrgSeed, OwnerSeed, ProjectSeed, Seed, TargetAccessTokenSeed } from './seed';
+
+interface Context {
+  seed: Seed;
+  owner: OwnerSeed;
+  org: OrgSeed;
+  //
+  // "single" branch
+  //
+  projectSingle: ProjectSeed;
+  targetAccessTokenSingle: TargetAccessTokenSeed;
+  cliSingle: CLI;
+  //
+  // "federation" branch
+  //
+  projectFederation: ProjectSeed;
+  targetAccessTokenFederation: TargetAccessTokenSeed;
+  cliFederation: CLI;
+  //
+  // "stitching" branch
+  //
+  projectStitching: ProjectSeed;
+  targetAccessTokenStitching: TargetAccessTokenSeed;
+  cliStitching: CLI;
+}
+
+export const test = testBase.extend<Context>({
+  seed: async ({}, use) => {
+    const seed = await initSeed();
+    await use(seed);
+  },
+  owner: async ({ seed }, use) => {
+    const owner = await seed.createOwner();
+    await use(owner);
+  },
+  org: async ({ owner }, use) => {
+    const org = await owner.createOrg();
+    await use(org);
+  },
+  //
+  // "single" branch
+  //
+  projectSingle: async ({ org }, use) => {
+    const project = await org.createProject(ProjectType.Single);
+    await use(project);
+  },
+  targetAccessTokenSingle: async ({ projectSingle }, use) => {
+    const targetAccessToken = await projectSingle.createTargetAccessToken({});
+    await use(targetAccessToken);
+  },
+  cliSingle: async ({ targetAccessTokenSingle }, use) => {
+    const cli = createCLI({
+      readwrite: targetAccessTokenSingle.secret,
+      readonly: targetAccessTokenSingle.secret,
+    });
+    await use(cli);
+  },
+  //
+  // "federation" branch
+  //
+  projectFederation: async ({ org }, use) => {
+    const project = await org.createProject(ProjectType.Federation);
+    await use(project);
+  },
+  targetAccessTokenFederation: async ({ projectFederation }, use) => {
+    const targetAccessToken = await projectFederation.createTargetAccessToken({});
+    await use(targetAccessToken);
+  },
+  cliFederation: async ({ targetAccessTokenFederation }, use) => {
+    const cli = createCLI({
+      readwrite: targetAccessTokenFederation.secret,
+      readonly: targetAccessTokenFederation.secret,
+    });
+    await use(cli);
+  },
+  //
+  // "stitching" branch
+  //
+  projectStitching: async ({ org }, use) => {
+    const project = await org.createProject(ProjectType.Stitching);
+    await use(project);
+  },
+  targetAccessTokenStitching: async ({ projectStitching }, use) => {
+    const targetAccessToken = await projectStitching.createTargetAccessToken({});
+    await use(targetAccessToken);
+  },
+  cliStitching: async ({ targetAccessTokenStitching }, use) => {
+    const cli = createCLI({
+      readwrite: targetAccessTokenStitching.secret,
+      readonly: targetAccessTokenStitching.secret,
+    });
+    await use(cli);
+  },
+});

integration-tests/tests/cli/__snapshot_serializers__/_.ts

@@ -0,0 +1 @@
+export * from './cli-output';

integration-tests/tests/cli/__snapshot_serializers__/__.ts

@@ -0,0 +1 @@
+export * as SnapshotSerializers from './_';