bump-cli 2.7.3 → 2.8.1

package/README.md

@@ -87,7 +87,7 @@ $ bump --help
 The Bump.sh CLI is used to interact with your API documentation hosted on Bump.sh by using the API of developers.bump.sh
 
 VERSION
-  bump-cli/2.7.2 linux-x64 node-v16.17.0
+  bump-cli/2.8.0 linux-x64 node-v16.19.0
 
 USAGE
   $ bump [COMMAND]
@@ -96,6 +96,7 @@ COMMANDS
   deploy   Create a new version of your documentation from the given file or URL.
   diff     Get a comparison diff with your documentation from the given file or URL.
   help     Display help for bump.
+  overlay  Apply an OpenAPI specified overlay to your API definition.
   preview  Create a documentation preview from the given file or URL.
 ```
 
@@ -112,6 +113,7 @@ Head over to your Documentation settings in the “CI deployment” section or y
 * [`bump deploy [FILE]`](#bump-deploy-file)
 * [`bump diff [FILE]`](#bump-diff-file)
 * [`bump preview [FILE]`](#bump-preview-file)
+* [`bump overlay [DEFINITION_FILE] [OVERLAY_FILE]`](#bump-overlay-definition_file-overlay_file)
 
 ### `bump deploy [FILE]`
 
@@ -245,6 +247,26 @@ _Note: the additional `--open` flag helps to automatically open the preview URL
 
 Please check `bump preview --help` for more usage details
 
+### `bump overlay [DEFINITION_FILE] [OVERLAY_FILE]`
+
+> This feature implements the [OpenAPI Overlay specification](https://github.com/OAI/Overlay-Specification). It is possible to apply an Overlay to any kind of document, be it an OpenAPI or AsyncAPI definition file.
+
+The Overlay specification of OpenAPI makes it possible to modify the content of an API definition file by adding a layer on top of it. That layer helps adding, removing or changing some or all of the content of the original definition. 
+
+Technically, the `bump overlay` command will output a modified version of the `[DEFINITION_FILE]` (an OpenAPI or AsyncAPI document) by applying the operations described in the `[OVERLAY_FILE]` Overlay file to the original API document.
+
+To redirect the output of the command to a new file you can run:
+
+```shell
+bump overlay api-document.yaml overlay-file.yaml > api-overlayed-document.yaml
+```
+
+_Note: you can also apply the overlay during the [`bump deploy` command]((#bump-deploy-file)) with the new `--overlay` flag:_
+
+```shell
+bump deploy api-document.yaml --doc my-doc --token my-token --overlay overlay-file.yaml 
+```
+
 ## Development
 
 Make sure to have Node.js (At least v14) installed on your machine.
@@ -283,6 +305,10 @@ We currently support [OpenAPI](https://github.com/OAI/OpenAPI-Specification) fro
 
 Bug reports and pull requests are welcome on GitHub at <https://github.com/bump-sh/cli>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
+## Thanks
+
+- [Lorna Mitchel](https://github.com/lornajane/) for [openapi-overlay-js](https://github.com/lornajane/openapi-overlays-js)
+
 ## License
 
 The Bump CLI project is released under the [MIT License](http://opensource.org/licenses/MIT).

package/lib/args.d.ts

@@ -7,4 +7,9 @@ declare const otherFileArg: {
     name: string;
     description: string;
 };
-export { fileArg, otherFileArg };
+declare const overlayFileArg: {
+    name: string;
+    required: boolean;
+    description: string;
+};
+export { fileArg, otherFileArg, overlayFileArg };

package/lib/args.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.otherFileArg = exports.fileArg = void 0;
+exports.overlayFileArg = exports.otherFileArg = exports.fileArg = void 0;
 const fileArg = {
     name: 'FILE',
     required: true,
@@ -12,3 +12,9 @@ const otherFileArg = {
     description: 'Path or URL to a second API documentation file to compute its diff',
 };
 exports.otherFileArg = otherFileArg;
+const overlayFileArg = {
+    name: 'OVERLAY_FILE',
+    required: true,
+    description: 'Path or URL to an overlay file',
+};
+exports.overlayFileArg = overlayFileArg;

package/lib/commands/deploy.d.ts

@@ -14,6 +14,7 @@ export default class Deploy extends Command {
         interactive: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;
         'filename-pattern': flagsBuilder.IOptionFlag<string | undefined>;
         'dry-run': import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;
+        overlay: flagsBuilder.IOptionFlag<string | undefined>;
     };
     static args: {
         name: string;

package/lib/commands/deploy.js

@@ -22,7 +22,7 @@ class Deploy extends command_1.default {
     */
     async run() {
         const { args, flags } = this.parse(Deploy);
-        const [dryRun, documentation, token, hub, autoCreate, interactive, filenamePattern, documentationName, branch,] = [
+        const [dryRun, documentation, token, hub, autoCreate, interactive, filenamePattern, documentationName, branch, overlay,] = [
             flags['dry-run'],
             flags.doc,
             /* eslint-disable-next-line @typescript-eslint/no-non-null-assertion */
@@ -36,6 +36,7 @@ class Deploy extends command_1.default {
             flags['filename-pattern'],
             flags['doc-name'],
             flags.branch,
+            flags.overlay,
         ];
         if ((0, file_1.isDir)(args.FILE)) {
             if (hub) {
@@ -49,7 +50,7 @@ class Deploy extends command_1.default {
             if (documentation) {
                 const api = await definition_1.API.load(args.FILE);
                 this.d(`${args.FILE} looks like an ${api.specName} spec version ${api.version}`);
-                await this.deploySingleFile(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch);
+                await this.deploySingleFile(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay);
             }
             else {
                 throw new errors_1.RequiredFlagError({ flag: Deploy.flags.doc, parse: {} });
@@ -86,14 +87,14 @@ class Deploy extends command_1.default {
             });
         }
         else {
-            throw new errors_2.CLIError(`No documentations found in ${dir}.\nYou should check the ${chalk_1.default.dim('--filename-pattern')} flag to select your files from your naming convention.\nIf you don't have a naming convention we can help naming your API definition files:\nTry the ${chalk_1.default.dim('--interactive')} flag for that.`);
+            throw new errors_2.CLIError(`No documentation found in ${dir} with the pattern '${filenamePattern}'.\nYou should check with the ${chalk_1.default.dim('--filename-pattern')} flag to select your files from your naming convention.\nIf you don't have a naming convention we can help naming your API definition files:\nTry the ${chalk_1.default.dim('--interactive')} flag for that.`);
         }
         return;
     }
-    async deploySingleFile(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch) {
+    async deploySingleFile(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay) {
         const action = dryRun ? 'validate' : 'deploy';
         cli_1.cli.action.start(`Let's ${action} a new version to your ${documentation} documentation on Bump.sh`);
-        const response = await new deploy_1.Deploy(this.config).run(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch);
+        const response = await new deploy_1.Deploy(this.config).run(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay);
         if (dryRun) {
             await cli_1.cli.styledSuccess('Definition is valid');
         }
@@ -158,5 +159,6 @@ Deploy.flags = {
     interactive: flagsBuilder.interactive(),
     'filename-pattern': flagsBuilder.filenamePattern(),
     'dry-run': flagsBuilder.dryRun(),
+    overlay: flagsBuilder.overlay(),
 };
 Deploy.args = [args_1.fileArg];

package/lib/commands/overlay.d.ts

@@ -0,0 +1,16 @@
+import Command from '../command';
+import * as flagsBuilder from '../flags';
+export default class Overlay extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        help: import("@oclif/parser/lib/flags").IBooleanFlag<void>;
+        out: flagsBuilder.IOptionFlag<string | undefined>;
+    };
+    static args: {
+        name: string;
+        required: boolean;
+        description: string;
+    }[];
+    run(): Promise<void>;
+}

package/lib/commands/overlay.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
+const promises_1 = require("node:fs/promises");
+const node_fs_1 = require("node:fs");
+const path_1 = require("path");
+const definition_1 = require("../definition");
+const prompts_1 = require("../core/utils/prompts");
+const command_1 = (0, tslib_1.__importDefault)(require("../command"));
+const flagsBuilder = (0, tslib_1.__importStar)(require("../flags"));
+const args_1 = require("../args");
+const cli_1 = require("../cli");
+class Overlay extends command_1.default {
+    async run() {
+        const { args, flags } = this.parse(Overlay);
+        const outputPath = flags.out;
+        cli_1.cli.action.start("* Let's apply the overlay to the main definition");
+        const api = await definition_1.API.load(args.FILE);
+        await api.applyOverlay(args.OVERLAY_FILE);
+        const [overlayedDefinition] = api.extractDefinition(outputPath);
+        cli_1.cli.action.stop();
+        if (outputPath) {
+            await (0, promises_1.mkdir)((0, path_1.dirname)(outputPath), { recursive: true });
+            let confirm = true;
+            if ((0, node_fs_1.existsSync)(outputPath)) {
+                await (0, prompts_1.confirm)(`Do you want to override the existing destination file? (${outputPath})`).catch(() => {
+                    confirm = false;
+                });
+            }
+            if (confirm) {
+                await (0, promises_1.writeFile)(outputPath, overlayedDefinition);
+            }
+        }
+        else {
+            cli_1.cli.log(overlayedDefinition);
+        }
+        return;
+    }
+}
+exports.default = Overlay;
+Overlay.description = 'Apply an OpenAPI specified overlay to your API definition.';
+Overlay.examples = [
+    `Apply the OVERLAY_FILE to the existing DEFINITION_FILE. The resulting
+definition is output on stdout meaning you can redirect it to a new
+file.
+
+${chalk_1.default.dim('$ bump overlay DEFINITION_FILE OVERLAY_FILE > destination/file.json')}
+* Let's apply the overlay to the main definition... done
+`,
+];
+Overlay.flags = {
+    help: flagsBuilder.help({ char: 'h' }),
+    out: flagsBuilder.out(),
+};
+Overlay.args = [args_1.fileArg, args_1.overlayFileArg];

package/lib/core/deploy.d.ts

@@ -6,7 +6,7 @@ export declare class Deploy {
     _bump: BumpApi;
     _config: Config.IConfig;
     constructor(config: Config.IConfig);
-    run(api: API, dryRun: boolean, documentation: string, token: string, hub: string | undefined, autoCreate: boolean, documentationName: string | undefined, branch: string | undefined): Promise<VersionResponse | undefined>;
+    run(api: API, dryRun: boolean, documentation: string, token: string, hub: string | undefined, autoCreate: boolean, documentationName: string | undefined, branch: string | undefined, overlay?: string | undefined): Promise<VersionResponse | undefined>;
     get bumpClient(): BumpApi;
     createVersion(request: VersionRequest, token: string): Promise<VersionResponse | undefined>;
     validateVersion(version: VersionRequest, token: string): Promise<undefined>;

package/lib/core/deploy.js

@@ -8,8 +8,11 @@ class Deploy {
     constructor(config) {
         this._config = config;
     }
-    async run(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch) {
+    async run(api, dryRun, documentation, token, hub, autoCreate, documentationName, branch, overlay) {
         let version = undefined;
+        if (overlay) {
+            await api.applyOverlay(overlay);
+        }
         const [definition, references] = api.extractDefinition();
         const request = {
             documentation,

package/lib/core/diff.d.ts

@@ -2,6 +2,7 @@ import * as Config from '@oclif/config';
 import { BumpApi } from '../api';
 import { VersionResponse, WithDiff, DiffResponse } from '../api/models';
 export declare class Diff {
+    static readonly TIMEOUT = 120;
     _bump: BumpApi;
     _config: Config.IConfig;
     constructor(config: Config.IConfig);

package/lib/core/diff.js

@@ -26,7 +26,7 @@ class Diff {
         }
         if (diffVersion) {
             return await this.waitResult(diffVersion, token, {
-                timeout: 30,
+                timeout: Diff.TIMEOUT,
                 format,
             });
         }
@@ -98,7 +98,7 @@ class Diff {
             pollingResponse = await this.bumpClient.getDiff(result.id, opts.format);
         }
         if (opts.timeout <= 0) {
-            throw new errors_1.CLIError('We were unable to compute your documentation diff. Sorry about that. Please try again later');
+            throw new errors_1.CLIError('We were unable to compute your documentation diff. Sorry about that. Please try again later. If the error persists, please contact support at https://bump.sh.');
         }
         switch (pollingResponse.status) {
             case 200:
@@ -152,3 +152,5 @@ class Diff {
     }
 }
 exports.Diff = Diff;
+// 120 seconds = 2 minutes
+Diff.TIMEOUT = 120;

package/lib/core/overlay.d.ts

@@ -0,0 +1,5 @@
+import { APIDefinition, OpenAPIOverlay } from '../definition';
+export declare class Overlay {
+    run(spec: APIDefinition, overlay: OpenAPIOverlay): APIDefinition;
+    d(formatter: any, ...args: any[]): void;
+}

package/lib/core/overlay.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Overlay = void 0;
+const tslib_1 = require("tslib");
+const debug_1 = (0, tslib_1.__importDefault)(require("debug"));
+const jsonpath_1 = (0, tslib_1.__importDefault)(require("jsonpath"));
+const mergician_1 = (0, tslib_1.__importDefault)(require("mergician"));
+class Overlay {
+    // WIP @github.com/lornajane/openapi-overlays-js
+    //
+    // I couldn't get the upstream lib to be imported properly due to
+    // some issues with ESM module imports so this is method was copied
+    // from github.com/lornajane/openapi-overlays-js and has been
+    // adapted to make our Typescript build happy.
+    //
+    // If you make any changes here, PLEASE ALSO MAKE THEM UPSTREAM.
+    run(spec, overlay) {
+        // Use jsonpath.apply to do the changes
+        if (overlay.actions && overlay.actions.length >= 1)
+            overlay.actions.forEach((a) => {
+                const action = a;
+                if (!action.target) {
+                    process.stderr.write('Action with a missing target\n');
+                    return;
+                }
+                const target = action.target;
+                // Is it a remove?
+                if (action.hasOwnProperty('remove')) {
+                    while (true) {
+                        const path = jsonpath_1.default.paths(spec, target, 1);
+                        if (path.length == 0) {
+                            break;
+                        }
+                        const parent = jsonpath_1.default.parent(spec, target);
+                        const thingToRemove = path[0][path[0].length - 1];
+                        if (Array.isArray(parent)) {
+                            parent.splice(thingToRemove, 1);
+                        }
+                        else {
+                            delete parent[thingToRemove];
+                        }
+                    }
+                }
+                else {
+                    try {
+                        // It must be an update
+                        // Deep merge objects using a module (built-in spread operator is only shallow)
+                        const merger = (0, mergician_1.default)({ appendArrays: true });
+                        if (target === '$') {
+                            // You can't actually merge an update on a root object
+                            // target with the jsonpath lib, this is just us merging
+                            // the given update with the whole spec.
+                            spec = merger(spec, action.update);
+                        }
+                        else {
+                            jsonpath_1.default.apply(spec, target, (chunk) => {
+                                if (typeof chunk === 'object' && typeof action.update === 'object') {
+                                    if (Array.isArray(chunk) && Array.isArray(action.update)) {
+                                        return chunk.concat(action.update);
+                                    }
+                                    else {
+                                        return merger(chunk, action.update);
+                                    }
+                                }
+                                else {
+                                    return action.update;
+                                }
+                            });
+                        }
+                    }
+                    catch (ex) {
+                        process.stderr.write(`Error applying overlay: ${ex.message}\n`);
+                        //return chunk
+                    }
+                }
+            });
+        return spec;
+    }
+    // Function signature type taken from @types/debug
+    // Debugger(formatter: any, ...args: any[]): void;
+    /* eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any */
+    d(formatter, ...args) {
+        return (0, debug_1.default)(`bump-cli:core:overlay`)(formatter, ...args);
+    }
+}
+exports.Overlay = Overlay;

package/lib/definition.d.ts

@@ -1,5 +1,5 @@
 import $RefParser from '@apidevtools/json-schema-ref-parser';
-import { JSONSchema4, JSONSchema4Object, JSONSchema6, JSONSchema6Object, JSONSchema7 } from 'json-schema';
+import { JSONSchema4, JSONSchema4Object, JSONSchema4Array, JSONSchema6, JSONSchema6Object, JSONSchema7 } from 'json-schema';
 declare type SpecSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
 declare class SupportedFormat {
     static readonly openapi: Record<string, SpecSchema>;
@@ -9,6 +9,7 @@ declare class API {
     readonly location: string;
     readonly rawDefinition: string;
     readonly definition: APIDefinition;
+    overlayedDefinition: APIDefinition | undefined;
     readonly references: APIReference[];
     readonly version: string;
     readonly specName: string;
@@ -17,26 +18,40 @@ declare class API {
     getSpec(definition: APIDefinition): SpecSchema;
     getSpecName(definition: APIDefinition): string;
     getVersion(definition: APIDefinition): string;
+    guessFormat(output?: string): string;
     versionWithoutPatch(): string;
     resolveRelativeLocation(absPath: string): string;
     resolveContent($refs: $RefParser.$Refs): [string, APIDefinition];
+    serializeDefinition(outputPath?: string): string;
     static isOpenAPI(definition: JSONSchema4Object | JSONSchema6Object): definition is OpenAPI;
     static isAsyncAPI(definition: JSONSchema4Object | JSONSchema6Object): definition is AsyncAPI;
-    extractDefinition(): [string, APIReference[]];
+    static isOpenAPIOverlay(definition: JSONSchema4Object | JSONSchema6Object): definition is OpenAPIOverlay;
+    extractDefinition(outputPath?: string): [string, APIReference[]];
+    applyOverlay(overlayPath: string): Promise<void>;
     static load(path: string): Promise<API>;
 }
 declare type APIReference = {
     location: string;
     content: string;
 };
-declare type APIDefinition = OpenAPI | AsyncAPI;
+declare type APIDefinition = OpenAPI | AsyncAPI | OpenAPIOverlay;
+declare type InfoObject = {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string;
+};
 declare type OpenAPI = JSONSchema4Object & {
     readonly openapi?: string;
     readonly swagger?: string;
-    readonly info: string;
+    readonly info: InfoObject;
+};
+declare type OpenAPIOverlay = JSONSchema4Object & {
+    readonly overlay: string;
+    readonly info: InfoObject;
+    readonly actions: JSONSchema4Array;
 };
 declare type AsyncAPI = JSONSchema4Object & {
     readonly asyncapi: string;
-    readonly info: string;
+    readonly info: InfoObject;
 };
-export { API, SupportedFormat };
+export { API, APIDefinition, OpenAPIOverlay, SupportedFormat };

package/lib/definition.js

@@ -7,6 +7,8 @@ const json_schema_ref_parser_1 = (0, tslib_1.__importDefault)(require("@apidevto
 const options_1 = require("@apidevtools/json-schema-ref-parser/lib/options");
 const specs_1 = (0, tslib_1.__importDefault)(require("@asyncapi/specs"));
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
+const yaml_1 = require("@stoplight/yaml");
+const overlay_1 = require("./core/overlay");
 class SupportedFormat {
 }
 exports.SupportedFormat = SupportedFormat;
@@ -53,6 +55,9 @@ class API {
         if (API.isAsyncAPI(definition)) {
             return SupportedFormat.asyncapi[this.versionWithoutPatch()];
         }
+        else if (API.isOpenAPIOverlay(definition)) {
+            return { overlay: { type: 'string' } };
+        }
         else {
             return SupportedFormat.openapi[this.versionWithoutPatch()];
         }
@@ -73,6 +78,9 @@ class API {
             return (definition.openapi || definition.swagger);
         }
     }
+    guessFormat(output) {
+        return (output || this.location).endsWith('.json') ? 'json' : 'yaml';
+    }
     versionWithoutPatch() {
         const [major, minor] = this.version.split('.', 3);
         return `${major}.${minor}`;
@@ -125,18 +133,38 @@ class API {
         if (!parsed || !(parsed instanceof Object) || !('info' in parsed)) {
             throw new UnsupportedFormat("Definition needs to be an object with at least an 'info' key");
         }
-        if (!API.isOpenAPI(parsed) && !API.isAsyncAPI(parsed)) {
+        if (!API.isOpenAPI(parsed) &&
+            !API.isAsyncAPI(parsed) &&
+            !API.isOpenAPIOverlay(parsed)) {
             throw new UnsupportedFormat();
         }
         return [raw, parsed];
     }
+    serializeDefinition(outputPath) {
+        if (this.overlayedDefinition) {
+            let serializedDefinition;
+            if (this.guessFormat(outputPath) == 'json') {
+                serializedDefinition = JSON.stringify(this.overlayedDefinition);
+            }
+            else {
+                serializedDefinition = (0, yaml_1.safeStringify)(this.overlayedDefinition);
+            }
+            return serializedDefinition;
+        }
+        else {
+            return this.rawDefinition;
+        }
+    }
     static isOpenAPI(definition) {
         return (typeof definition.openapi === 'string' || typeof definition.swagger === 'string');
     }
     static isAsyncAPI(definition) {
         return 'asyncapi' in definition;
     }
-    extractDefinition() {
+    static isOpenAPIOverlay(definition) {
+        return 'overlay' in definition;
+    }
+    extractDefinition(outputPath) {
         const references = [];
         for (let i = 0; i < this.references.length; i++) {
             const reference = this.references[i];
@@ -145,7 +173,15 @@ class API {
                 content: reference.content,
             });
         }
-        return [this.rawDefinition, references];
+        return [this.serializeDefinition(outputPath), references];
+    }
+    async applyOverlay(overlayPath) {
+        const overlay = await API.load(overlayPath);
+        const overlayDefinition = overlay.definition;
+        if (!API.isOpenAPIOverlay(overlayDefinition)) {
+            throw new Error(`${overlayPath} does not look like an OpenAPI overlay`);
+        }
+        this.overlayedDefinition = await new overlay_1.Overlay().run(this.definition, overlayDefinition);
     }
     static async load(path) {
         const JSONParser = options_1.defaults.parse.json;

package/lib/flags.d.ts

@@ -15,4 +15,6 @@ declare const failOnBreaking: (options?: {}) => Parser.flags.IBooleanFlag<boolea
 declare const live: (options?: {}) => Parser.flags.IBooleanFlag<boolean>;
 declare const format: flags.Definition<string>;
 declare const expires: flags.Definition<string>;
-export { doc, docName, hub, branch, token, autoCreate, interactive, filenamePattern, dryRun, open, failOnBreaking, live, format, expires, };
+declare const out: flags.Definition<string>;
+declare const overlay: flags.Definition<string>;
+export { doc, docName, hub, branch, token, autoCreate, interactive, filenamePattern, dryRun, open, failOnBreaking, live, format, expires, out, overlay, };

package/lib/flags.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.expires = exports.format = exports.live = exports.failOnBreaking = exports.open = exports.dryRun = exports.filenamePattern = exports.interactive = exports.autoCreate = exports.token = exports.branch = exports.hub = exports.docName = exports.doc = void 0;
+exports.overlay = exports.out = exports.expires = exports.format = exports.live = exports.failOnBreaking = exports.open = exports.dryRun = exports.filenamePattern = exports.interactive = exports.autoCreate = exports.token = exports.branch = exports.hub = exports.docName = exports.doc = void 0;
 const tslib_1 = require("tslib");
 const command_1 = require("@oclif/command");
 // Re-export oclif flags https://oclif.io/docs/flags
@@ -104,3 +104,13 @@ const expires = command_1.flags.build({
     description: "Specify a longer expiration date for public diffs (defaults to 1 day). Use iso8601 format to provide a date, or you can use `--expires 'never'` to keep the result live indefinitely.",
 });
 exports.expires = expires;
+const out = command_1.flags.build({
+    char: 'o',
+    description: 'Output file path',
+});
+exports.out = out;
+const overlay = command_1.flags.build({
+    char: 'o',
+    description: 'Path or URL of an overlay file to apply before deploying',
+});
+exports.overlay = overlay;

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 import { run } from '@oclif/command';
 import { Diff } from './core/diff';
+import { Overlay } from './core/overlay';
 import Deploy from './commands/deploy';
 import Preview from './commands/preview';
 export { VersionResponse, PreviewResponse, DiffResponse, WithDiff } from './api/models';
-export { run, Deploy, Diff, Preview };
+export { run, Deploy, Diff, Preview, Overlay };

package/lib/index.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Preview = exports.Diff = exports.Deploy = exports.run = void 0;
+exports.Overlay = exports.Preview = exports.Diff = exports.Deploy = exports.run = void 0;
 const tslib_1 = require("tslib");
 const command_1 = require("@oclif/command");
 Object.defineProperty(exports, "run", { enumerable: true, get: function () { return command_1.run; } });
 const diff_1 = require("./core/diff");
 Object.defineProperty(exports, "Diff", { enumerable: true, get: function () { return diff_1.Diff; } });
+const overlay_1 = require("./core/overlay");
+Object.defineProperty(exports, "Overlay", { enumerable: true, get: function () { return overlay_1.Overlay; } });
 const deploy_1 = (0, tslib_1.__importDefault)(require("./commands/deploy"));
 exports.Deploy = deploy_1.default;
 const preview_1 = (0, tslib_1.__importDefault)(require("./commands/preview"));

package/oclif.manifest.json

@@ -1 +1 @@
-{"version":"2.7.3","commands":{"deploy":{"id":"deploy","description":"Create a new version of your documentation from the given file or URL.","pluginName":"bump-cli","pluginType":"core","aliases":[],"examples":["Deploy a new version of an existing documentation\n\n$ bump deploy FILE --doc <your_doc_id_or_slug> --token <your_doc_token>\n* Let's deploy a new documentation version on Bump... done\n* Your new documentation version will soon be ready\n","Deploy a new version of an existing documentation attached to a hub\n\n$ bump deploy FILE --doc <doc_slug> --hub <your_hub_id_or_slug> --token <your_doc_token>\n* Let's deploy a new documentation version on Bump... done\n* Your new documentation version will soon be ready\n","Deploy a whole directory of API definitions files to a hub\n\n$ bump deploy DIR --filename-pattern *-{slug}-api --hub <hub_slug> --token <hub_token>\nWe've found 2 valid API definitions to deploy\n└─ DIR\n   └─ source-my-service-api.yml (OpenAPI spec version 3.1.0)\n   └─ source-my-jobs-service-api.yml (AsyncAPI spec version 2.6.0)\n\nLet's deploy those documentations to your <hub_slug> hub on Bump.sh\n\n* Your new documentation version will soon be ready\nLet's deploy a new version to your my-service documentation on Bump.sh... done\n\n* Your new documentation version will soon be ready\nLet's deploy a new version to your my-jobs-service documentation on Bump.sh... done\n","Validate a new documentation version before deploying it\n\n$ bump deploy FILE --dry-run --doc <doc_slug> --token <your_doc_token>\n* Let's validate a new documentation version on Bump... done\n* Definition is valid\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","allowNo":false},"doc":{"name":"doc","type":"option","char":"d","description":"Documentation public id or slug. Can be provided via BUMP_ID environment variable"},"doc-name":{"name":"doc-name","type":"option","char":"n","description":"Documentation name. Used with --auto-create flag."},"hub":{"name":"hub","type":"option","char":"b","description":"Hub id or slug. Can be provided via BUMP_HUB_ID environment variable"},"branch":{"name":"branch","type":"option","char":"B","description":"Branch name. Can be provided via BUMP_BRANCH_NAME environment variable"},"token":{"name":"token","type":"option","char":"t","description":"Documentation or Hub token. Can be provided via BUMP_TOKEN environment variable","required":true},"auto-create":{"name":"auto-create","type":"boolean","description":"Automatically create the documentation if needed (only available with a --hub flag). Documentation name can be provided with --doc-name flag. Default: false","allowNo":false},"interactive":{"name":"interactive","type":"boolean","description":"Interactively create a configuration file to deploy a Hub (only available with a --hub flag). This will start an interactive process if you don't have a CLI configuration file. Default: false","allowNo":false},"filename-pattern":{"name":"filename-pattern","type":"option","description":"Pattern to extract the documentation slug from filenames when deploying a DIRECTORY. Pattern uses only '*' and '{slug}' as special characters to extract the slug from a filename without extension. Used with --hub flag only.","default":"{slug}-api"},"dry-run":{"name":"dry-run","type":"boolean","description":"Validate a new documentation version. Does everything a normal deploy would do except publishing the new version. Useful in automated environments such as test platforms or continuous integration. Default: false","allowNo":false}},"args":[{"name":"FILE","description":"Path or URL to your API documentation file. OpenAPI (2.0 to 3.1.0) and AsyncAPI (2.x) specifications are currently supported.\nPath can also be a directory when deploying to a Hub.","required":true}]},"diff":{"id":"diff","description":"Get a comparison diff with your documentation from the given file or URL.","pluginName":"bump-cli","pluginType":"core","aliases":[],"examples":["Compare a potential new version with the currently published one:\n\n  $ bump diff FILE --doc <your_doc_id_or_slug> --token <your_doc_token>\n  * Comparing the given definition file with the currently deployed one... done\n  Removed: GET /compare\n  Added: GET /versions/{versionId}\n","Store the diff in a dedicated file:\n\n  $ bump diff FILE --doc <doc_slug> --token <doc_token> > /tmp/my-saved-diff\n  * Comparing the given definition file with the currently deployed one... done\n\n  $ cat /tmp/my-saved-diff\n  Removed: GET /compare\n  Added: GET /versions/{versionId}\n","In case of a non modified definition FILE compared to your existing documentation, no changes are output:\n\n  $ bump diff FILE --doc <doc_slug> --token <your_doc_token>\n  * Comparing the given definition file with the currently deployed one... done\n   ›   Warning: Your documentation has not changed\n","Compare two different input files or URL independently to the one published on bump.sh\n\n  $ bump diff FILE FILE2 --doc <doc_slug> --token <your_doc_token>\n  * Comparing the two given definition files... done\n  Updated: POST /versions\n    Body attribute added: previous_version_id\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","allowNo":false},"doc":{"name":"doc","type":"option","char":"d","description":"Documentation public id or slug. Can be provided via BUMP_ID environment variable"},"hub":{"name":"hub","type":"option","char":"b","description":"Hub id or slug. Can be provided via BUMP_HUB_ID environment variable"},"branch":{"name":"branch","type":"option","char":"B","description":"Branch name. Can be provided via BUMP_BRANCH_NAME environment variable"},"token":{"name":"token","type":"option","char":"t","description":"Documentation or Hub token. Can be provided via BUMP_TOKEN environment variable","required":false},"open":{"name":"open","type":"boolean","char":"o","description":"Open the visual diff in your browser","allowNo":false},"fail-on-breaking":{"name":"fail-on-breaking","type":"boolean","char":"F","description":"Fail when diff contains a breaking change","allowNo":false},"format":{"name":"format","type":"option","char":"f","description":"Format in which to provide the diff result","options":["text","markdown","json","html"],"default":"text"},"expires":{"name":"expires","type":"option","char":"e","description":"Specify a longer expiration date for public diffs (defaults to 1 day). Use iso8601 format to provide a date, or you can use `--expires 'never'` to keep the result live indefinitely."}},"args":[{"name":"FILE","description":"Path or URL to your API documentation file. OpenAPI (2.0 to 3.1.0) and AsyncAPI (2.x) specifications are currently supported.\nPath can also be a directory when deploying to a Hub.","required":true},{"name":"FILE2","description":"Path or URL to a second API documentation file to compute its diff"}]},"preview":{"id":"preview","description":"Create a documentation preview from the given file or URL.","pluginName":"bump-cli","pluginType":"core","aliases":[],"examples":["$ bump preview FILE\n* Your preview is visible at: https://bump.sh/preview/45807371-9a32-48a7-b6e4-1cb7088b5b9b\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","allowNo":false},"live":{"name":"live","type":"boolean","char":"l","description":"Generate a preview each time you save the given file","allowNo":false},"open":{"name":"open","type":"boolean","char":"o","description":"Open the generated preview URL in your browser","allowNo":false}},"args":[{"name":"FILE","description":"Path or URL to your API documentation file. OpenAPI (2.0 to 3.1.0) and AsyncAPI (2.x) specifications are currently supported.\nPath can also be a directory when deploying to a Hub.","required":true}]}}}
+{"version":"2.8.1","commands":{"deploy":{"id":"deploy","description":"Create a new version of your documentation from the given file or URL.","pluginName":"bump-cli","pluginType":"core","aliases":[],"examples":["Deploy a new version of an existing documentation\n\n$ bump deploy FILE --doc <your_doc_id_or_slug> --token <your_doc_token>\n* Let's deploy a new documentation version on Bump... done\n* Your new documentation version will soon be ready\n","Deploy a new version of an existing documentation attached to a hub\n\n$ bump deploy FILE --doc <doc_slug> --hub <your_hub_id_or_slug> --token <your_doc_token>\n* Let's deploy a new documentation version on Bump... done\n* Your new documentation version will soon be ready\n","Deploy a whole directory of API definitions files to a hub\n\n$ bump deploy DIR --filename-pattern *-{slug}-api --hub <hub_slug> --token <hub_token>\nWe've found 2 valid API definitions to deploy\n└─ DIR\n   └─ source-my-service-api.yml (OpenAPI spec version 3.1.0)\n   └─ source-my-jobs-service-api.yml (AsyncAPI spec version 2.6.0)\n\nLet's deploy those documentations to your <hub_slug> hub on Bump.sh\n\n* Your new documentation version will soon be ready\nLet's deploy a new version to your my-service documentation on Bump.sh... done\n\n* Your new documentation version will soon be ready\nLet's deploy a new version to your my-jobs-service documentation on Bump.sh... done\n","Validate a new documentation version before deploying it\n\n$ bump deploy FILE --dry-run --doc <doc_slug> --token <your_doc_token>\n* Let's validate a new documentation version on Bump... done\n* Definition is valid\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","allowNo":false},"doc":{"name":"doc","type":"option","char":"d","description":"Documentation public id or slug. Can be provided via BUMP_ID environment variable"},"doc-name":{"name":"doc-name","type":"option","char":"n","description":"Documentation name. Used with --auto-create flag."},"hub":{"name":"hub","type":"option","char":"b","description":"Hub id or slug. Can be provided via BUMP_HUB_ID environment variable"},"branch":{"name":"branch","type":"option","char":"B","description":"Branch name. Can be provided via BUMP_BRANCH_NAME environment variable"},"token":{"name":"token","type":"option","char":"t","description":"Documentation or Hub token. Can be provided via BUMP_TOKEN environment variable","required":true},"auto-create":{"name":"auto-create","type":"boolean","description":"Automatically create the documentation if needed (only available with a --hub flag). Documentation name can be provided with --doc-name flag. Default: false","allowNo":false},"interactive":{"name":"interactive","type":"boolean","description":"Interactively create a configuration file to deploy a Hub (only available with a --hub flag). This will start an interactive process if you don't have a CLI configuration file. Default: false","allowNo":false},"filename-pattern":{"name":"filename-pattern","type":"option","description":"Pattern to extract the documentation slug from filenames when deploying a DIRECTORY. Pattern uses only '*' and '{slug}' as special characters to extract the slug from a filename without extension. Used with --hub flag only.","default":"{slug}-api"},"dry-run":{"name":"dry-run","type":"boolean","description":"Validate a new documentation version. Does everything a normal deploy would do except publishing the new version. Useful in automated environments such as test platforms or continuous integration. Default: false","allowNo":false},"overlay":{"name":"overlay","type":"option","char":"o","description":"Path or URL of an overlay file to apply before deploying"}},"args":[{"name":"FILE","description":"Path or URL to your API documentation file. OpenAPI (2.0 to 3.1.0) and AsyncAPI (2.x) specifications are currently supported.\nPath can also be a directory when deploying to a Hub.","required":true}]},"diff":{"id":"diff","description":"Get a comparison diff with your documentation from the given file or URL.","pluginName":"bump-cli","pluginType":"core","aliases":[],"examples":["Compare a potential new version with the currently published one:\n\n  $ bump diff FILE --doc <your_doc_id_or_slug> --token <your_doc_token>\n  * Comparing the given definition file with the currently deployed one... done\n  Removed: GET /compare\n  Added: GET /versions/{versionId}\n","Store the diff in a dedicated file:\n\n  $ bump diff FILE --doc <doc_slug> --token <doc_token> > /tmp/my-saved-diff\n  * Comparing the given definition file with the currently deployed one... done\n\n  $ cat /tmp/my-saved-diff\n  Removed: GET /compare\n  Added: GET /versions/{versionId}\n","In case of a non modified definition FILE compared to your existing documentation, no changes are output:\n\n  $ bump diff FILE --doc <doc_slug> --token <your_doc_token>\n  * Comparing the given definition file with the currently deployed one... done\n   ›   Warning: Your documentation has not changed\n","Compare two different input files or URL independently to the one published on bump.sh\n\n  $ bump diff FILE FILE2 --doc <doc_slug> --token <your_doc_token>\n  * Comparing the two given definition files... done\n  Updated: POST /versions\n    Body attribute added: previous_version_id\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","allowNo":false},"doc":{"name":"doc","type":"option","char":"d","description":"Documentation public id or slug. Can be provided via BUMP_ID environment variable"},"hub":{"name":"hub","type":"option","char":"b","description":"Hub id or slug. Can be provided via BUMP_HUB_ID environment variable"},"branch":{"name":"branch","type":"option","char":"B","description":"Branch name. Can be provided via BUMP_BRANCH_NAME environment variable"},"token":{"name":"token","type":"option","char":"t","description":"Documentation or Hub token. Can be provided via BUMP_TOKEN environment variable","required":false},"open":{"name":"open","type":"boolean","char":"o","description":"Open the visual diff in your browser","allowNo":false},"fail-on-breaking":{"name":"fail-on-breaking","type":"boolean","char":"F","description":"Fail when diff contains a breaking change","allowNo":false},"format":{"name":"format","type":"option","char":"f","description":"Format in which to provide the diff result","options":["text","markdown","json","html"],"default":"text"},"expires":{"name":"expires","type":"option","char":"e","description":"Specify a longer expiration date for public diffs (defaults to 1 day). Use iso8601 format to provide a date, or you can use `--expires 'never'` to keep the result live indefinitely."}},"args":[{"name":"FILE","description":"Path or URL to your API documentation file. OpenAPI (2.0 to 3.1.0) and AsyncAPI (2.x) specifications are currently supported.\nPath can also be a directory when deploying to a Hub.","required":true},{"name":"FILE2","description":"Path or URL to a second API documentation file to compute its diff"}]},"overlay":{"id":"overlay","description":"Apply an OpenAPI specified overlay to your API definition.","pluginName":"bump-cli","pluginType":"core","aliases":[],"examples":["Apply the OVERLAY_FILE to the existing DEFINITION_FILE. The resulting\ndefinition is output on stdout meaning you can redirect it to a new\nfile.\n\n$ bump overlay DEFINITION_FILE OVERLAY_FILE > destination/file.json\n* Let's apply the overlay to the main definition... done\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","allowNo":false},"out":{"name":"out","type":"option","char":"o","description":"Output file path"}},"args":[{"name":"FILE","description":"Path or URL to your API documentation file. OpenAPI (2.0 to 3.1.0) and AsyncAPI (2.x) specifications are currently supported.\nPath can also be a directory when deploying to a Hub.","required":true},{"name":"OVERLAY_FILE","description":"Path or URL to an overlay file","required":true}]},"preview":{"id":"preview","description":"Create a documentation preview from the given file or URL.","pluginName":"bump-cli","pluginType":"core","aliases":[],"examples":["$ bump preview FILE\n* Your preview is visible at: https://bump.sh/preview/45807371-9a32-48a7-b6e4-1cb7088b5b9b\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","allowNo":false},"live":{"name":"live","type":"boolean","char":"l","description":"Generate a preview each time you save the given file","allowNo":false},"open":{"name":"open","type":"boolean","char":"o","description":"Open the generated preview URL in your browser","allowNo":false}},"args":[{"name":"FILE","description":"Path or URL to your API documentation file. OpenAPI (2.0 to 3.1.0) and AsyncAPI (2.x) specifications are currently supported.\nPath can also be a directory when deploying to a Hub.","required":true}]}}}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bump-cli",
   "description": "The Bump CLI is used to interact with your API documentation hosted on Bump by using the API of developers.bump.sh",
-  "version": "2.7.3",
+  "version": "2.8.1",
   "author": "Paul Bonaud <paulr@bump.sh>",
   "bin": {
     "bump": "./bin/run"
@@ -11,6 +11,7 @@
     "@oclif/dev-cli": "^1.26.0",
     "@oclif/test": "^2.0.3",
     "@types/debug": "^4.1.5",
+    "@types/jsonpath": "^0.2.4",
     "@types/mocha": "^10.0.0",
     "@types/node": "^20.7.0",
     "@typescript-eslint/eslint-plugin": "^5.21.0",
@@ -23,7 +24,7 @@
     "globby": "^11.0.3",
     "mocha": "^10.0.0",
     "nock": "^13.0.11",
-    "np": "^7.6.2",
+    "np": "^10.0.5",
     "nyc": "^15.1.0",
     "prettier": "^2.2.1",
     "sinon": "^14.0.0",
@@ -32,7 +33,7 @@
     "typescript": "4.5.5"
   },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=16.0.0"
   },
   "files": [
     "/bin",
@@ -89,9 +90,12 @@
     "@oclif/core": "1.20.4",
     "@oclif/plugin-help": "^5.1.10",
     "@oclif/plugin-warn-if-update-available": "^2.0.36",
+    "@stoplight/yaml": "^4.2.3",
     "async-mutex": "^0.4.0",
     "axios": "^0.27.2",
     "debug": "^4.3.1",
+    "jsonpath": "^1.1.1",
+    "mergician": "^1.0.3",
     "oas-schemas": "git+https://git@github.com/OAI/OpenAPI-Specification.git#0f9d3ec7c033fef184ec54e1ffc201b2d61ce023",
     "tslib": "^2.3.0"
   }