@oclif/core 1.17.0 → 1.19.0

package/lib/command.d.ts

@@ -1,6 +1,7 @@
 import { Config } from './config';
 import * as Interfaces from './interfaces';
 import { PrettyPrintableError } from './errors';
+import { Deprecation } from './interfaces/parser';
 /**
  * An abstract class which acts as the base for each command
  * in your project.
@@ -22,10 +23,11 @@ export default abstract class Command {
      * If no summary, the first line of the description will be used as the summary.
      */
     static description: string | undefined;
-    /** Hide the command from help? */
+    /** Hide the command from help */
     static hidden: boolean;
-    /** Mark the command as a given state (e.g. beta) in help? */
-    static state?: string;
+    /** Mark the command as a given state (e.g. beta or deprecated) in help */
+    static state?: 'beta' | 'deprecated' | string;
+    static deprecationOptions?: Deprecation;
     /**
      * An override string (or strings) for the default usage documentation.
      */
@@ -95,6 +97,8 @@ export default abstract class Command {
      */
     abstract run(): PromiseLike<any>;
     protected init(): Promise<any>;
+    protected warnIfFlagDeprecated(flags: Record<string, unknown>): void;
+    protected warnIfCommandDeprecated(): void;
     protected parse<F extends Interfaces.FlagOutput, G extends Interfaces.FlagOutput, A extends {
         [name: string]: any;
     }>(options?: Interfaces.Input<F, G>, argv?: string[]): Promise<Interfaces.ParserOutput<F, G, A>>;

package/lib/command.js

@@ -7,6 +7,7 @@ const config_1 = require("./config");
 const Errors = require("./errors");
 const Parser = require("./parser");
 const Flags = require("./flags");
+const util_2 = require("./help/util");
 const pjson = require('../package.json');
 /**
  * swallows stdout epipe errors
@@ -122,13 +123,24 @@ class Command {
             Errors.config.debug = true;
         if (this.config.errlog)
             Errors.config.errlog = this.config.errlog;
-        // global['cli-ux'].context = global['cli-ux'].context || {
-        //   command: compact([this.id, ...this.argv]).join(' '),
-        //   version: this.config.userAgent,
-        // }
         const g = global;
         g['http-call'] = g['http-call'] || {};
         g['http-call'].userAgent = this.config.userAgent;
+        this.warnIfCommandDeprecated();
+    }
+    warnIfFlagDeprecated(flags) {
+        for (const flag of Object.keys(flags)) {
+            const deprecated = this.ctor.flags[flag]?.deprecated;
+            if (deprecated) {
+                this.warn((0, util_2.formatFlagDeprecationWarning)(flag, deprecated));
+            }
+        }
+    }
+    warnIfCommandDeprecated() {
+        if (this.ctor.state === 'deprecated') {
+            const cmdName = (0, index_1.toConfiguredId)(this.ctor.id, this.config);
+            this.warn((0, util_2.formatCommandDeprecationWarning)(cmdName, this.ctor.deprecationOptions));
+        }
     }
     async parse(options, argv = this.argv) {
         if (!options)
@@ -137,7 +149,9 @@ class Command {
         // the spread operator doesn't work with getters so we have to manually add it here
         opts.flags = options?.flags;
         opts.args = options?.args;
-        return Parser.parse(argv, opts);
+        const results = await Parser.parse(argv, opts);
+        this.warnIfFlagDeprecated(results.flags ?? {});
+        return results;
     }
     async catch(err) {
         process.exitCode = process.exitCode ?? err.exitCode ?? 1;
@@ -160,7 +174,6 @@ class Command {
             const config = Errors.config;
             if (config.errorLogger)
                 await config.errorLogger.flush();
-            // tslint:disable-next-line no-console
         }
         catch (error) {
             console.error(error);

package/lib/config/config.js

@@ -643,6 +643,7 @@ async function toCached(c, plugin) {
                 allowNo: flag.allowNo,
                 dependsOn: flag.dependsOn,
                 exclusive: flag.exclusive,
+                deprecated: flag.deprecated,
                 aliases: flag.aliases,
             };
         }
@@ -664,6 +665,7 @@ async function toCached(c, plugin) {
                 relationships: flag.relationships,
                 exclusive: flag.exclusive,
                 default: await defaultToCached(flag),
+                deprecated: flag.deprecated,
                 aliases: flag.aliases,
             };
             // a command-level placeholder in the manifest so that oclif knows it should regenerate the command during help-time
@@ -694,6 +696,7 @@ async function toCached(c, plugin) {
         state: c.state,
         aliases: c.aliases || [],
         examples: c.examples || c.example,
+        deprecationOptions: c.deprecationOptions,
         flags,
         args,
     };

package/lib/help/index.js

@@ -118,8 +118,11 @@ class Help extends HelpBase {
         const subCommands = this.sortedCommands.filter(c => c.id.startsWith(name + ':') && c.id.split(':').length === depth + 1);
         const plugin = this.config.plugins.find(p => p.name === command.pluginName);
         const state = this.config.pjson?.oclif?.state || plugin?.pjson?.oclif?.state || command.state;
-        if (state)
-            this.log(`This command is in ${state}.\n`);
+        if (state) {
+            this.log(state === 'deprecated' ?
+                `${(0, util_2.formatCommandDeprecationWarning)((0, util_2.toConfiguredId)(name, this.config), command.deprecationOptions)}` :
+                `This command is in ${state}.\n`);
+        }
         const summary = this.summary(command);
         if (summary) {
             this.log(summary + '\n');
@@ -144,8 +147,11 @@ class Help extends HelpBase {
         let rootTopics = this.sortedTopics;
         let rootCommands = this.sortedCommands;
         const state = this.config.pjson?.oclif?.state;
-        if (state)
-            this.log(`${this.config.bin} is in ${state}.\n`);
+        if (state) {
+            this.log(state === 'deprecated' ?
+                `${this.config.bin} is deprecated` :
+                `${this.config.bin} is in ${state}.\n`);
+        }
         this.log(this.formatRoot());
         this.log('');
         if (!this.opts.all) {

package/lib/help/util.d.ts

@@ -1,5 +1,6 @@
 import { Config as IConfig, HelpOptions } from '../interfaces';
 import { HelpBase } from '.';
+import { Deprecation } from '../interfaces/parser';
 interface HelpBaseDerived {
     new (config: IConfig, opts?: Partial<HelpOptions>): HelpBase;
 }
@@ -9,4 +10,6 @@ export declare function toStandardizedId(commandID: string, config: IConfig): st
 export declare function toConfiguredId(commandID: string, config: IConfig): string;
 export declare function standardizeIDFromArgv(argv: string[], config: IConfig): string[];
 export declare function getHelpFlagAdditions(config: IConfig): string[];
+export declare function formatFlagDeprecationWarning(flag: string, opts: true | Deprecation): string;
+export declare function formatCommandDeprecationWarning(command: string, opts?: Deprecation): string;
 export {};

package/lib/help/util.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getHelpFlagAdditions = exports.standardizeIDFromArgv = exports.toConfiguredId = exports.toStandardizedId = exports.template = exports.loadHelpClass = void 0;
+exports.formatCommandDeprecationWarning = exports.formatFlagDeprecationWarning = exports.getHelpFlagAdditions = exports.standardizeIDFromArgv = exports.toConfiguredId = exports.toStandardizedId = exports.template = exports.loadHelpClass = void 0;
 const ejs = require("ejs");
 const _1 = require(".");
 const module_loader_1 = require("../module-loader");
@@ -71,8 +71,8 @@ function toStandardizedId(commandID, config) {
 }
 exports.toStandardizedId = toStandardizedId;
 function toConfiguredId(commandID, config) {
-    const defaultTopicSeperator = ':';
-    return commandID.replace(new RegExp(defaultTopicSeperator, 'g'), config.topicSeparator || defaultTopicSeperator);
+    const defaultTopicSeparator = ':';
+    return commandID.replace(new RegExp(defaultTopicSeparator, 'g'), config.topicSeparator || defaultTopicSeparator);
 }
 exports.toConfiguredId = toConfiguredId;
 function standardizeIDFromArgv(argv, config) {
@@ -91,3 +91,29 @@ function getHelpFlagAdditions(config) {
     return [...new Set([...helpFlags, ...additionalHelpFlags]).values()];
 }
 exports.getHelpFlagAdditions = getHelpFlagAdditions;
+function formatFlagDeprecationWarning(flag, opts) {
+    let message = `The "${flag}" flag has been deprecated`;
+    if (opts === true)
+        return `${message}.`;
+    if (opts.message)
+        return opts.message;
+    if (opts.version) {
+        message += ` and will be removed in version ${opts.version}`;
+    }
+    message += opts.to ? `. Use "${opts.to}" instead.` : '.';
+    return message;
+}
+exports.formatFlagDeprecationWarning = formatFlagDeprecationWarning;
+function formatCommandDeprecationWarning(command, opts) {
+    let message = `The "${command}" command has been deprecated`;
+    if (!opts)
+        return `${message}.`;
+    if (opts.message)
+        return opts.message;
+    if (opts.version) {
+        message += ` and will be removed in version ${opts.version}`;
+    }
+    message += opts.to ? `. Use "${opts.to}" instead.` : '.';
+    return message;
+}
+exports.formatCommandDeprecationWarning = formatCommandDeprecationWarning;

package/lib/interfaces/command.d.ts

@@ -1,5 +1,5 @@
 import { Config, LoadOptions } from './config';
-import { ArgInput, BooleanFlagProps, FlagInput, OptionFlagProps } from './parser';
+import { ArgInput, BooleanFlagProps, Deprecation, FlagInput, OptionFlagProps } from './parser';
 import { Plugin as IPlugin } from './plugin';
 export declare type Example = string | {
     description: string;
@@ -8,10 +8,14 @@ export declare type Example = string | {
 export interface CommandProps {
     /** A command ID, used mostly in error or verbose reporting. */
     id: string;
-    /** Hide the command from help? */
+    /** Hide the command from help */
     hidden: boolean;
-    /** Mark the command as a given state (e.g. beta) in help? */
-    state?: string;
+    /** Mark the command as a given state (e.g. beta or deprecated) in help */
+    state?: 'beta' | 'deprecated' | string;
+    /**
+     * Provide details to the deprecation warning if state === 'deprecated'
+     */
+    deprecationOptions?: Deprecation;
     /** An array of aliases for this command. */
     aliases: string[];
     /**

package/lib/interfaces/parser.d.ts

@@ -92,6 +92,11 @@ export declare type Relationship = {
     type: 'all' | 'some' | 'none';
     flags: FlagRelationship[];
 };
+export declare type Deprecation = {
+    to?: string;
+    message?: string;
+    version?: string;
+};
 export declare type FlagProps = {
     name: string;
     char?: AlphabetLowercase | AlphabetUppercase;
@@ -143,6 +148,10 @@ export declare type FlagProps = {
      * Define complex relationships between flags.
      */
     relationships?: Relationship[];
+    /**
+     * Make the flag as deprecated.
+     */
+    deprecated?: true | Deprecation;
     /**
      * Alternate names that can be used for this flag.
      */

package/lib/interfaces/pjson.d.ts

@@ -50,7 +50,7 @@ export declare namespace PJSON {
             };
             additionalHelpFlags?: string[];
             additionalVersionFlags?: string[];
-            state?: string;
+            state?: 'beta' | 'deprecated' | string;
         };
     }
     interface S3 {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {