@redocly/cli 1.6.0 → 1.8.0

package/src/commands/build-docs/index.ts

@@ -6,7 +6,7 @@ import { performance } from 'perf_hooks';
 import { getObjectOrJSON, getPageHTML } from './utils';
 import type { BuildDocsArgv } from './types';
 import { Config, getMergedConfig, isAbsoluteUrl } from '@redocly/openapi-core';
-import { exitWithError, getExecutionTime, getFallbackApisOrExit } from '../../utils';
+import { exitWithError, getExecutionTime, getFallbackApisOrExit } from '../../utils/miscellaneous';
 
 export const handlerBuildCommand = async (argv: BuildDocsArgv, configFromFile: Config) => {
   const startedAt = performance.now();

package/src/commands/build-docs/utils.ts

@@ -10,7 +10,7 @@ import { existsSync, lstatSync, readFileSync } from 'fs';
 
 import type { BuildDocsOptions } from './types';
 import { red } from 'colorette';
-import { exitWithError } from '../../utils';
+import { exitWithError } from '../../utils/miscellaneous';
 
 export function getObjectOrJSON(
   openapiOptions: string | Record<string, unknown>,

package/src/commands/bundle.ts

@@ -18,12 +18,12 @@ import {
   printLintTotals,
   checkIfRulesetExist,
   sortTopLevelKeysForOas,
-} from '../utils';
+} from '../utils/miscellaneous';
 import type { OutputExtensions, Skips, Totals } from '../types';
 import { performance } from 'perf_hooks';
 import { blue, gray, green, yellow } from 'colorette';
 import { writeFileSync } from 'fs';
-import { checkForDeprecatedOptions } from '../utils';
+import { checkForDeprecatedOptions } from '../utils/miscellaneous';
 
 export type BundleOptions = {
   apis?: string[];

package/src/commands/join.ts

@@ -30,8 +30,8 @@ import {
   getAndValidateFileExtension,
   writeToFileByExtension,
   checkForDeprecatedOptions,
-} from '../utils';
-import { isObject, isString, keysOf } from '../js-utils';
+} from '../utils/miscellaneous';
+import { isObject, isString, keysOf } from '../utils/js-utils';
 import {
   Oas3Parameter,
   Oas3PathItem,

package/src/commands/lint.ts

@@ -17,7 +17,7 @@ import {
   printConfigLintTotals,
   printLintTotals,
   printUnusedWarnings,
-} from '../utils';
+} from '../utils/miscellaneous';
 import { blue, gray } from 'colorette';
 import { performance } from 'perf_hooks';
 

package/src/commands/login.ts

@@ -1,6 +1,6 @@
 import { Region, RedoclyClient, Config } from '@redocly/openapi-core';
 import { blue, green, gray } from 'colorette';
-import { promptUser } from '../utils';
+import { promptUser } from '../utils/miscellaneous';
 
 export function promptClientToken(domain: string) {
   return promptUser(

package/src/commands/preview-docs/index.ts

@@ -1,7 +1,11 @@
 import * as colorette from 'colorette';
 import * as chockidar from 'chokidar';
 import { bundle, RedoclyClient, getTotals, getMergedConfig, Config } from '@redocly/openapi-core';
-import { getFallbackApisOrExit, handleError, loadConfigAndHandleErrors } from '../../utils';
+import {
+  getFallbackApisOrExit,
+  handleError,
+  loadConfigAndHandleErrors,
+} from '../../utils/miscellaneous';
 import startPreviewServer from './preview-server/preview-server';
 import type { Skips } from '../../types';
 

package/src/commands/preview-docs/preview-server/preview-server.ts

@@ -6,7 +6,7 @@ import * as path from 'path';
 
 import { startHttpServer, startWsServer, respondWithGzip, mimeTypes } from './server';
 import type { IncomingMessage } from 'http';
-import { isSubdir } from '../../../utils';
+import { isSubdir } from '../../../utils/miscellaneous';
 
 function getPageHTML(
   htmlTemplate: string,

package/src/commands/preview-project/constants.ts

@@ -0,0 +1,23 @@
+import { Product } from './types';
+
+export const PRODUCT_PACKAGES = {
+  realm: '@redocly/realm',
+  'redoc-revel': '@redocly/redoc-revel',
+  'revel-reef': '@redocly/revel-reef',
+  'redoc-reef': '@redocly/redoc-reef',
+  redoc: '@redocly/redoc',
+  revel: '@redocly/revel',
+  reef: '@redocly/reef',
+};
+
+export const PRODUCT_NAMES: { [key in Product]: string } = {
+  redoc: 'Redoc',
+  revel: 'Revel',
+  reef: 'Reef',
+  realm: 'Realm',
+  'redoc-revel': 'Redoc + Revel',
+  'redoc-reef': 'Redoc + Reef',
+  'revel-reef': 'Revel + Reef',
+};
+
+export const PRODUCT_PLANS = ['pro', 'enterprise'] as const;

package/src/commands/preview-project/index.ts

@@ -0,0 +1,58 @@
+import path = require('path');
+import { existsSync, readFileSync } from 'fs';
+import { spawn } from 'child_process';
+import { PRODUCT_NAMES, PRODUCT_PACKAGES } from './constants';
+
+import type { PreviewProjectOptions, Product } from './types';
+
+export const previewProject = async (args: PreviewProjectOptions) => {
+  const { plan, port } = args;
+  const projectDir = args['source-dir'];
+
+  const product = args.product || tryGetProductFromPackageJson(projectDir);
+
+  if (!isValidProduct(product)) {
+    process.stderr.write(`Invalid product ${product}`);
+    throw new Error(`Project preview launch failed`);
+  }
+
+  const productName = PRODUCT_NAMES[product];
+  const packageName = PRODUCT_PACKAGES[product];
+
+  process.stdout.write(`\nLaunching preview of ${productName} ${plan} using NPX\n\n`);
+
+  spawn('npx', ['-y', packageName, 'develop', `--plan=${plan}`, `--port=${port || 4000}`], {
+    stdio: 'inherit',
+    cwd: projectDir,
+  });
+};
+
+const isValidProduct = (product: string | undefined): product is Product => {
+  if (!product) {
+    return false;
+  }
+
+  return !!PRODUCT_NAMES[product as Product];
+};
+
+const tryGetProductFromPackageJson = (projectDir: string): Product => {
+  const packageJsonPath = path.join(process.cwd(), projectDir, 'package.json');
+
+  if (existsSync(packageJsonPath)) {
+    try {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+      const packageJsonDeps = packageJson.dependencies || {};
+
+      for (const [product, packageName] of Object.entries(PRODUCT_PACKAGES)) {
+        if (packageJsonDeps[packageName]) {
+          process.stdout.write(`\n${packageName} detected in project's 'package.json'`);
+          return product as Product;
+        }
+      }
+    } catch (error) {
+      process.stdout.write(`Invalid 'package.json': ${packageJsonPath}. Using Realm.`);
+    }
+  }
+
+  return 'realm';
+};

package/src/commands/preview-project/types.ts

@@ -0,0 +1,12 @@
+import { PRODUCT_PACKAGES, PRODUCT_PLANS } from './constants';
+
+export type Product = keyof typeof PRODUCT_PACKAGES;
+export type ProductPlan = typeof PRODUCT_PLANS[number];
+
+export type PreviewProjectOptions = {
+  product?: Product | string;
+  plan: ProductPlan | string;
+  port?: number;
+  'source-dir': string;
+  config?: string;
+};

package/src/commands/push.ts

@@ -21,8 +21,9 @@ import {
   getFallbackApisOrExit,
   pluralize,
   dumpBundle,
-} from '../utils';
+} from '../utils/miscellaneous';
 import { promptClientToken } from './login';
+import { handlePush as handleCMSPush } from '../cms/commands/push';
 
 const DEFAULT_VERSION = 'latest';
 
@@ -44,6 +45,19 @@ export type PushOptions = {
   config?: string;
 };
 
+export function commonPushHandler({
+  project,
+  'mount-path': mountPath,
+}: {
+  project?: string;
+  'mount-path'?: string;
+}) {
+  if (project && mountPath) {
+    return handleCMSPush;
+  }
+  return handlePush;
+}
+
 export async function handlePush(argv: PushOptions, config: Config): Promise<void> {
   const client = new RedoclyClient(config.region);
   const isAuthorized = await client.isAuthorizedWithRedoclyByRegion();

package/src/commands/split/__tests__/index.test.ts

@@ -3,12 +3,11 @@ import * as path from 'path';
 import * as openapiCore from '@redocly/openapi-core';
 import { ComponentsFiles } from '../types';
 import { blue, green } from 'colorette';
-import { writeToFileByExtension } from '../../../utils';
 
-const utils = require('../../../utils');
+const utils = require('../../../utils/miscellaneous');
 
-jest.mock('../../../utils', () => ({
-  ...jest.requireActual('../../../utils'),
+jest.mock('../../../utils/miscellaneous', () => ({
+  ...jest.requireActual('../../../utils/miscellaneous'),
   writeToFileByExtension: jest.fn(),
 }));
 

package/src/commands/split/index.ts

@@ -15,8 +15,8 @@ import {
   langToExt,
   writeToFileByExtension,
   getAndValidateFileExtension,
-} from '../../utils';
-import { isString, isObject, isEmptyObject } from '../../js-utils';
+} from '../../utils/miscellaneous';
+import { isString, isObject, isEmptyObject } from '../../utils/js-utils';
 import {
   Definition,
   Oas2Definition,
@@ -97,8 +97,8 @@ function isStartsWithComponents(node: string) {
   return node.startsWith(componentsPath);
 }
 
-function isNotYaml(filename: string) {
-  return !(filename.endsWith('.yaml') || filename.endsWith('.yml'));
+function isSupportedExtension(filename: string) {
+  return filename.endsWith('.yaml') || filename.endsWith('.yml') || filename.endsWith('.json');
 }
 
 function loadFile(fileName: string) {
@@ -138,7 +138,7 @@ function traverseDirectoryDeepCallback(
   directory: string,
   componentsFiles: object
 ) {
-  if (isNotYaml(filename)) return;
+  if (!isSupportedExtension(filename)) return;
   const pathData = readYaml(filename);
   replace$Refs(pathData, directory, componentsFiles);
   writeToFileByExtension(pathData, filename);

package/src/commands/stats.ts

@@ -13,8 +13,8 @@ import {
   Stats,
   bundle,
 } from '@redocly/openapi-core';
-import { getFallbackApisOrExit } from '../utils';
-import { printExecutionTime } from '../utils';
+import { getFallbackApisOrExit } from '../utils/miscellaneous';
+import { printExecutionTime } from '../utils/miscellaneous';
 import type { StatsAccumulator, StatsName, WalkContext, OutputFormat } from '@redocly/openapi-core';
 
 const statsAccumulator: StatsAccumulator = {

package/src/index.ts

@@ -1,24 +1,27 @@
 #!/usr/bin/env node
 
-import './assert-node-version';
+import './utils/assert-node-version';
 import * as yargs from 'yargs';
-import { outputExtensions, regionChoices } from './types';
+import { outputExtensions, PushArguments, regionChoices } from './types';
 import { RedoclyClient } from '@redocly/openapi-core';
 import { previewDocs } from './commands/preview-docs';
 import { handleStats } from './commands/stats';
 import { handleSplit } from './commands/split';
 import { handleJoin } from './commands/join';
-import { handlePush, transformPush } from './commands/push';
+import { handlePushStatus, PushStatusOptions } from './cms/commands/push-status';
 import { handleLint } from './commands/lint';
 import { handleBundle } from './commands/bundle';
 import { handleLogin } from './commands/login';
 import { handlerBuildCommand } from './commands/build-docs';
-import { cacheLatestVersion, notifyUpdateCliVersion } from './update-version-notifier';
+import { cacheLatestVersion, notifyUpdateCliVersion } from './utils/update-version-notifier';
 import { commandWrapper } from './wrapper';
-import { version } from './update-version-notifier';
+import { version } from './utils/update-version-notifier';
 import type { Arguments } from 'yargs';
 import type { OutputFormat, RuleSeverity } from '@redocly/openapi-core';
 import type { BuildDocsArgv } from './commands/build-docs/types';
+import { previewProject } from './commands/preview-project';
+import { PRODUCT_PLANS } from './commands/preview-project/constants';
+import { commonPushHandler } from './commands/push';
 
 if (!('replaceAll' in String.prototype)) {
   require('core-js/actual/string/replace-all');
@@ -92,7 +95,7 @@ yargs
   )
   .command(
     'join [apis...]',
-    'Join definitions [experimental].',
+    'Join multiple API descriptions into one [experimental].',
     (yargs) =>
       yargs
         .positional('apis', {
@@ -101,7 +104,7 @@ yargs
           demandOption: true,
         })
         .option({
-          lint: { description: 'Lint definitions', type: 'boolean', default: false, hidden: true },
+          lint: { description: 'Lint descriptions', type: 'boolean', default: false, hidden: true },
           decorate: { description: 'Run decorators', type: 'boolean', default: false },
           preprocess: { description: 'Run preprocessors', type: 'boolean', default: false },
           'prefix-tags-with-info-prop': {
@@ -124,7 +127,7 @@ yargs
             type: 'boolean',
           },
           output: {
-            describe: 'Output file',
+            description: 'Output file.',
             alias: 'o',
             type: 'string',
           },
@@ -144,23 +147,75 @@ yargs
       commandWrapper(handleJoin)(argv);
     }
   )
-
   .command(
-    'push [api] [maybeDestination] [maybeBranchName]',
-    'Push an API description to the Redocly API registry.',
+    'push-status [pushId]',
+    false,
     (yargs) =>
       yargs
-        .usage('push [api]')
-        .positional('api', { type: 'string' })
-        .positional('maybeDestination', { type: 'string' })
-        .hide('maybeDestination')
-        .hide('maybeBranchName')
+        .positional('pushId', {
+          description: 'Push id.',
+          type: 'string',
+          required: true,
+        })
+        .implies('max-execution-time', 'wait')
         .option({
           organization: {
             description: 'Name of the organization to push to.',
             type: 'string',
             alias: 'o',
           },
+          project: {
+            description: 'Name of the project to push to.',
+            type: 'string',
+            alias: 'p',
+          },
+          domain: { description: 'Specify a domain.', alias: 'd', type: 'string' },
+          wait: {
+            description: 'Wait for build to finish.',
+            type: 'boolean',
+            default: false,
+          },
+          'max-execution-time': {
+            description: 'Maximum execution time in seconds.',
+            type: 'number',
+          },
+        }),
+    (argv) => {
+      process.env.REDOCLY_CLI_COMMAND = 'push-status';
+      commandWrapper(handlePushStatus)(argv as Arguments<PushStatusOptions>);
+    }
+  )
+  .command(
+    'push [apis...]',
+    'Push an API description to the Redocly API registry.',
+    (yargs) =>
+      yargs
+        .positional('apis', {
+          type: 'string',
+          array: true,
+          required: true,
+          default: [],
+        })
+        .hide('project')
+        .hide('domain')
+        .hide('mount-path')
+        .hide('author')
+        .hide('message')
+        .hide('default-branch')
+        .hide('verbose')
+        .hide('commit-sha')
+        .hide('commit-url')
+        .hide('namespace')
+        .hide('repository')
+        .hide('wait-for-deployment')
+        .hide('created-at')
+        .hide('max-execution-time')
+        .deprecateOption('batch-id', 'use --job-id')
+        .implies('job-id', 'batch-size')
+        .implies('batch-id', 'batch-size')
+        .implies('batch-size', 'job-id')
+        .implies('max-execution-time', 'wait-for-deployment')
+        .option({
           destination: {
             description: 'API name and version in the format `name@version`.',
             type: 'string',
@@ -215,20 +270,85 @@ yargs
             choices: ['warn', 'error', 'off'] as ReadonlyArray<RuleSeverity>,
             default: 'warn' as RuleSeverity,
           },
-        })
-        .deprecateOption('batch-id', 'use --job-id')
-        .deprecateOption('maybeDestination')
-        .implies('job-id', 'batch-size')
-        .implies('batch-id', 'batch-size')
-        .implies('batch-size', 'job-id'),
+          organization: {
+            description: 'Name of the organization to push to.',
+            type: 'string',
+            alias: 'o',
+          },
+          project: {
+            description: 'Name of the project to push to.',
+            type: 'string',
+            alias: 'p',
+          },
+          'mount-path': {
+            description: 'The path files should be pushed to.',
+            type: 'string',
+            alias: 'mp',
+          },
+          author: {
+            description: 'Author of the commit.',
+            type: 'string',
+            alias: 'a',
+          },
+          message: {
+            description: 'Commit message.',
+            type: 'string',
+            alias: 'm',
+          },
+          'commit-sha': {
+            description: 'Commit SHA.',
+            type: 'string',
+            alias: 'sha',
+          },
+          'commit-url': {
+            description: 'Commit URL.',
+            type: 'string',
+            alias: 'url',
+          },
+          namespace: {
+            description: 'Repository namespace.',
+            type: 'string',
+          },
+          repository: {
+            description: 'Repository name.',
+            type: 'string',
+          },
+          'created-at': {
+            description: 'Commit creation date.',
+            type: 'string',
+          },
+          domain: { description: 'Specify a domain.', alias: 'd', type: 'string' },
+          config: {
+            description: 'Path to the config file.',
+            requiresArg: true,
+            type: 'string',
+          },
+          'default-branch': {
+            type: 'string',
+            default: 'main',
+          },
+          'max-execution-time': {
+            description: 'Maximum execution time in seconds.',
+            type: 'number',
+          },
+          'wait-for-deployment': {
+            description: 'Wait for build to finish.',
+            type: 'boolean',
+            default: false,
+          },
+          verbose: {
+            type: 'boolean',
+            default: false,
+          },
+        }),
     (argv) => {
       process.env.REDOCLY_CLI_COMMAND = 'push';
-      commandWrapper(transformPush(handlePush))(argv);
+      commandWrapper(commonPushHandler(argv))(argv as PushArguments);
     }
   )
   .command(
     'lint [apis...]',
-    'Lint definition.',
+    'Lint an API description.',
     (yargs) =>
       yargs.positional('apis', { array: true, type: 'string', demandOption: true }).option({
         format: {
@@ -287,10 +407,14 @@ yargs
   )
   .command(
     'bundle [apis...]',
-    'Bundle definition.',
+    'Bundle a multi-file API description to a single file.',
     (yargs) =>
       yargs.positional('apis', { array: true, type: 'string', demandOption: true }).options({
-        output: { type: 'string', alias: 'o' },
+        output: {
+          type: 'string',
+          description: 'Output file.',
+          alias: 'o',
+        },
         format: {
           description: 'Use a specific output format.',
           choices: ['stylish', 'codeframe', 'json', 'checkstyle'] as ReadonlyArray<OutputFormat>,
@@ -413,9 +537,41 @@ yargs
       })(argv);
     }
   )
+  .command(
+    'preview',
+    'Preview Redocly project using one of the product NPM packages.',
+    (yargs) =>
+      yargs.options({
+        product: {
+          type: 'string',
+          choices: ['redoc', 'revel', 'reef', 'realm', 'redoc-revel', 'redoc-reef', 'revel-reef'],
+          description:
+            "Product used to launch preview. Default is inferred from project's package.json or 'realm' is used.",
+        },
+        plan: {
+          type: 'string',
+          choices: PRODUCT_PLANS,
+          default: 'enterprise',
+        },
+        port: {
+          type: 'number',
+          description: 'Preview port.',
+          default: 4000,
+        },
+        'source-dir': {
+          alias: 'd',
+          type: 'string',
+          description: 'Project directory.',
+          default: '.',
+        },
+      }),
+    (argv) => {
+      commandWrapper(previewProject)(argv);
+    }
+  )
   .command(
     'preview-docs [api]',
-    'Preview API reference docs for the specified definition.',
+    'Preview API reference docs for an API description.',
     (yargs) =>
       yargs.positional('api', { type: 'string' }).options({
         port: {
@@ -519,7 +675,7 @@ yargs
       commandWrapper(handlerBuildCommand)(argv as Arguments<BuildDocsArgv>);
     }
   )
-  .completion('completion', 'Generate completion script.')
+  .completion('completion', 'Generate autocomplete script for `redocly` command.')
   .demandCommand(1)
   .middleware([notifyUpdateCliVersion])
   .strict().argv;

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { BundleOutputFormat, Region, Config } from '@redocly/openapi-core';
+import type { ArgumentsCamelCase } from 'yargs';
 import type { LintOptions } from './commands/lint';
 import type { BundleOptions } from './commands/bundle';
 import type { JoinOptions } from './commands/join';
@@ -8,6 +9,10 @@ import type { StatsOptions } from './commands/stats';
 import type { SplitOptions } from './commands/split';
 import type { PreviewDocsOptions } from './commands/preview-docs';
 import type { BuildDocsArgv } from './commands/build-docs/types';
+import type { PushOptions as PushBhOptions } from './cms/commands/push';
+import type { PushStatusOptions } from './cms/commands/push-status';
+import type { PushOptions as CMSPushOptions } from './cms/commands/push';
+import type { PreviewProjectOptions } from './commands/preview-project/types';
 
 export type Totals = {
   errors: number;
@@ -26,11 +31,15 @@ export type CommandOptions =
   | SplitOptions
   | JoinOptions
   | PushOptions
+  | PushBhOptions
   | LintOptions
   | BundleOptions
   | LoginOptions
   | PreviewDocsOptions
-  | BuildDocsArgv;
+  | BuildDocsArgv
+  | PushStatusOptions
+  | PreviewProjectOptions;
+
 export type Skips = {
   'skip-rule'?: string[];
   'skip-decorator'?: string[];
@@ -38,3 +47,5 @@ export type Skips = {
 };
 
 export type ConfigApis = Pick<Config, 'apis' | 'configFile'>;
+
+export type PushArguments = ArgumentsCamelCase<PushOptions & CMSPushOptions & { apis: string[] }>;

package/src/{__mocks__/utils.ts → utils/__mocks__/miscellaneous.ts}

@@ -1,4 +1,4 @@
-import { ConfigFixture } from '../__tests__/fixtures/config';
+import { ConfigFixture } from '../../__tests__/fixtures/config';
 
 export const getFallbackApisOrExit = jest.fn((entrypoints) =>
   entrypoints.map((path: string) => ({ path }))

package/src/{fetch-with-timeout.ts → utils/fetch-with-timeout.ts}

@@ -1,20 +1,15 @@
 import nodeFetch from 'node-fetch';
+import AbortController from 'abort-controller';
 
 const TIMEOUT = 3000;
 
 export default async (url: string, options = {}) => {
   try {
-    if (!global.AbortController) {
-      return nodeFetch(url, options);
-    }
     const controller = new AbortController();
     const timeout = setTimeout(() => {
       controller.abort();
     }, TIMEOUT);
 
-    // FIXME: fix this (possibly along with this issue: https://github.com/Redocly/redocly-cli/issues/1260)
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
     const res = await nodeFetch(url, { signal: controller.signal, ...options });
     clearTimeout(timeout);
     return res;