@oclif/core 2.6.4 → 2.7.0

package/lib/command.js

@@ -157,16 +157,21 @@ class Command {
     }
     warnIfFlagDeprecated(flags) {
         for (const flag of Object.keys(flags)) {
-            const deprecated = this.ctor.flags[flag]?.deprecated;
+            const flagDef = this.ctor.flags[flag];
+            const deprecated = flagDef?.deprecated;
             if (deprecated) {
                 this.warn((0, util_2.formatFlagDeprecationWarning)(flag, deprecated));
             }
-            const deprecateAliases = this.ctor.flags[flag]?.deprecateAliases;
-            const aliases = (this.ctor.flags[flag]?.aliases ?? []).map(a => a.length === 1 ? `-${a}` : `--${a}`);
+            const deprecateAliases = flagDef?.deprecateAliases;
+            const aliases = (flagDef?.aliases ?? []).map(a => a.length === 1 ? `-${a}` : `--${a}`);
             if (deprecateAliases && aliases.length > 0) {
                 const foundAliases = aliases.filter(alias => this.argv.some(a => a.startsWith(alias)));
                 for (const alias of foundAliases) {
-                    this.warn((0, util_2.formatFlagDeprecationWarning)(alias, { to: this.ctor.flags[flag]?.name }));
+                    let preferredUsage = `--${flagDef?.name}`;
+                    if (flagDef?.char) {
+                        preferredUsage += ` | -${flagDef?.char}`;
+                    }
+                    this.warn((0, util_2.formatFlagDeprecationWarning)(alias, { to: preferredUsage }));
                 }
             }
         }

package/lib/config/config.d.ts

@@ -136,4 +136,4 @@ export declare class Config implements IConfig {
     private determinePriority;
     private insertLegacyPlugins;
 }
-export declare function toCached(c: Command.Class, plugin?: IPlugin): Promise<Command.Cached>;
+export declare function toCached(c: Command.Class, plugin?: IPlugin | undefined, isWritingManifest?: boolean): Promise<Command.Cached>;

package/lib/config/config.js

@@ -713,11 +713,11 @@ class Config {
 }
 exports.Config = Config;
 // when no manifest exists, the default is calculated.  This may throw, so we need to catch it
-const defaultFlagToCached = async (flag) => {
+const defaultFlagToCached = async (flag, isWritingManifest = false) => {
     // Prefer the helpDefaultValue function (returns a friendly string for complex types)
     if (typeof flag.defaultHelp === 'function') {
         try {
-            return await flag.defaultHelp();
+            return await flag.defaultHelp({ options: flag, flags: {} }, isWritingManifest);
         }
         catch {
             return;
@@ -726,7 +726,7 @@ const defaultFlagToCached = async (flag) => {
     // if not specified, try the default function
     if (typeof flag.default === 'function') {
         try {
-            return await flag.default({ options: {}, flags: {} });
+            return await flag.default({ options: {}, flags: {} }, isWritingManifest);
         }
         catch { }
     }
@@ -734,11 +734,11 @@ const defaultFlagToCached = async (flag) => {
         return flag.default;
     }
 };
-const defaultArgToCached = async (arg) => {
+const defaultArgToCached = async (arg, isWritingManifest = false) => {
     // Prefer the helpDefaultValue function (returns a friendly string for complex types)
     if (typeof arg.defaultHelp === 'function') {
         try {
-            return await arg.defaultHelp();
+            return await arg.defaultHelp({ options: arg, flags: {} }, isWritingManifest);
         }
         catch {
             return;
@@ -747,7 +747,7 @@ const defaultArgToCached = async (arg) => {
     // if not specified, try the default function
     if (typeof arg.default === 'function') {
         try {
-            return await arg.default({ options: {}, flags: {} });
+            return await arg.default({ options: arg, flags: {} }, isWritingManifest);
         }
         catch { }
     }
@@ -755,7 +755,7 @@ const defaultArgToCached = async (arg) => {
         return arg.default;
     }
 };
-async function toCached(c, plugin) {
+async function toCached(c, plugin, isWritingManifest) {
     const flags = {};
     for (const [name, flag] of Object.entries(c.flags || {})) {
         if (flag.type === 'boolean') {
@@ -796,7 +796,7 @@ async function toCached(c, plugin) {
                 dependsOn: flag.dependsOn,
                 relationships: flag.relationships,
                 exclusive: flag.exclusive,
-                default: await defaultFlagToCached(flag),
+                default: await defaultFlagToCached(flag, isWritingManifest),
                 deprecated: flag.deprecated,
                 deprecateAliases: c.deprecateAliases,
                 aliases: flag.aliases,
@@ -815,7 +815,7 @@ async function toCached(c, plugin) {
             description: arg.description,
             required: arg.required,
             options: arg.options,
-            default: await defaultArgToCached(arg),
+            default: await defaultArgToCached(arg, isWritingManifest),
             hidden: arg.hidden,
         };
     }

package/lib/config/plugin.d.ts

@@ -28,7 +28,13 @@ export declare class Plugin implements IPlugin {
     protected _debug: (..._: any) => void;
     protected warned: boolean;
     constructor(options: PluginOptions);
-    load(): Promise<void>;
+    /**
+     * Loads a plugin
+     * @param isWritingManifest - if true, exclude selected data from manifest
+     * default is false to maintain backwards compatibility
+     * @returns Promise<void>
+     */
+    load(isWritingManifest?: boolean): Promise<void>;
     get topics(): Topic[];
     get commandsDir(): string | undefined;
     get commandIDs(): string[];
@@ -38,7 +44,7 @@ export declare class Plugin implements IPlugin {
     findCommand(id: string, opts?: {
         must: boolean;
     }): Promise<Command.Class | undefined>;
-    protected _manifest(ignoreManifest: boolean, errorOnManifestCreate?: boolean): Promise<Manifest>;
+    protected _manifest(ignoreManifest: boolean, errorOnManifestCreate?: boolean, isWritingManifest?: boolean): Promise<Manifest>;
     protected warn(err: string | Error | CLIError, scope?: string): void;
     private addErrorScope;
 }

package/lib/config/plugin.js

@@ -100,7 +100,13 @@ class Plugin {
         this._debug = (0, util_2.Debug)();
         this.warned = false;
     }
-    async load() {
+    /**
+     * Loads a plugin
+     * @param isWritingManifest - if true, exclude selected data from manifest
+     * default is false to maintain backwards compatibility
+     * @returns Promise<void>
+     */
+    async load(isWritingManifest) {
         this.type = this.options.type || 'core';
         this.tag = this.options.tag;
         const root = await findRoot(this.options.name, this.options.root);
@@ -126,7 +132,7 @@ class Plugin {
             this.pjson.oclif = this.pjson['cli-engine'] || {};
         }
         this.hooks = (0, util_3.mapValues)(this.pjson.oclif.hooks || {}, i => Array.isArray(i) ? i : [i]);
-        this.manifest = await this._manifest(Boolean(this.options.ignoreManifest), Boolean(this.options.errorOnManifestCreate));
+        this.manifest = await this._manifest(Boolean(this.options.ignoreManifest), Boolean(this.options.errorOnManifestCreate), isWritingManifest);
         this.commands = Object
             .entries(this.manifest.commands)
             .map(([id, c]) => ({
@@ -205,7 +211,7 @@ class Plugin {
         marker?.stop();
         return cmd;
     }
-    async _manifest(ignoreManifest, errorOnManifestCreate = false) {
+    async _manifest(ignoreManifest, errorOnManifestCreate = false, isWritingManifest = false) {
         const readManifest = async (dotfile = false) => {
             try {
                 const p = path.join(this.root, `${dotfile ? '.' : ''}oclif.manifest.json`);
@@ -242,7 +248,7 @@ class Plugin {
             version: this.version,
             commands: (await Promise.all(this.commandIDs.map(async (id) => {
                 try {
-                    return [id, await (0, config_1.toCached)(await this.findCommand(id, { must: true }), this)];
+                    return [id, await (0, config_1.toCached)(await this.findCommand(id, { must: true }), this, isWritingManifest)];
                 }
                 catch (error) {
                     const scope = 'toCached';

package/lib/help/index.js

@@ -91,7 +91,7 @@ class Help extends HelpBase {
         const command = this.config.findCommand(subject);
         if (command) {
             if (command.hasDynamicHelp && command.pluginType !== 'jit') {
-                const dynamicCommand = await (0, config_1.toCached)(await command.load());
+                const dynamicCommand = await (0, config_1.toCached)(await command.load(), undefined, false);
                 await this.showCommandHelp(dynamicCommand);
             }
             else {

package/lib/help/util.js

@@ -101,7 +101,7 @@ function formatFlagDeprecationWarning(flag, opts) {
     if (opts.version) {
         message += ` and will be removed in version ${opts.version}`;
     }
-    message += opts.to ? `. Use "--${opts.to}" instead.` : '.';
+    message += opts.to ? `. Use "${opts.to}" instead.` : '.';
     return message;
 }
 exports.formatFlagDeprecationWarning = formatFlagDeprecationWarning;

package/lib/interfaces/parser.d.ts

@@ -50,6 +50,7 @@ export type Metadata = {
 };
 type MetadataFlag = {
     setFromDefault?: boolean;
+    defaultHelp?: unknown;
 };
 export type ListItem = [string, string | undefined];
 export type List = ListItem[];
@@ -58,10 +59,91 @@ export type DefaultContext<T> = {
     options: T;
     flags: Record<string, string>;
 };
-export type FlagDefault<T, P = CustomOptions> = T | ((context: DefaultContext<P & OptionFlag<T, P>>) => Promise<T>);
-export type FlagDefaultHelp<T, P = CustomOptions> = T | ((context: DefaultContext<P & OptionFlag<T, P>>) => Promise<string | undefined>);
-export type ArgDefault<T, P = CustomOptions> = T | ((context: DefaultContext<Arg<T, P>>) => Promise<T>);
-export type ArgDefaultHelp<T, P = CustomOptions> = T | ((context: DefaultContext<Arg<T, P>>) => Promise<string | undefined>);
+/**
+ * Type to define a default value for a flag.
+ * @param context The context of the flag.
+ * @param isWritingManifest Informs the function that a manifest file is being written.
+ * The manifest file is used to store the flag definitions, with a default value if present, for a command and is published to npm.
+ * When a manifest file is being written, the default value may contain data that should not be included in the manifest.
+ * The plugin developer can use isWritingManifest to determine if the default value should be omitted from the manifest.
+ * in the function's implementation.
+ * @example
+ * static flags = {
+ *   foo: flags.string({
+ *     defaultHelp: async (context, isWritingManifest) => {
+ *       if (isWritingManifest) {
+ *         return undefined
+ *       }
+ *       return 'value that is used outside a manifest'
+ *     },
+ *    }),
+ *  }
+ */
+export type FlagDefault<T, P = CustomOptions> = T | ((context: DefaultContext<P & OptionFlag<T, P>>, isWritingManifest?: boolean) => Promise<T>);
+/**
+ * Type to define a defaultHelp value for a flag.
+ * The defaultHelp value is used in the help output for the flag and when writing a manifest.
+ * It is also can be used to provide a value for the flag when issuing certain error messages.
+ *
+ * @param context The context of the flag.
+ * @param isWritingManifest Informs the function that a manifest file is being written.
+ * The manifest file is used to store the flag definitions, with a default value if present via defaultHelp, for a command and is published to npm.
+ * When a manifest file is being written, the default value may contain data that should not be included in the manifest.
+ * The plugin developer can use isWritingManifest to determine if the defaultHelp value should be omitted from the manifest.
+ * in the function's implementation.
+ * @example
+ * static flags = {
+ *   foo: flags.string({
+ *     defaultHelp: async (context, isWritingManifest) => {
+ *       if (isWritingManifest) {
+ *         return undefined
+ *       }
+ *       return 'value that is used outside a manifest'
+ *     },
+ *    }),
+ *  }
+ */
+export type FlagDefaultHelp<T, P = CustomOptions> = T | ((context: DefaultContext<P & OptionFlag<T, P>>, isWritingManifest?: boolean) => Promise<string | undefined>);
+/**
+ * Type to define a default value for an arg.
+ * @param context The context of the arg.
+ * @param isWritingManifest Informs the function that a manifest file is being written.
+ * The manifest file is used to store the arg definitions, with a default value if present, for a command and is published to npm.
+ * When a manifest file is being written, the default value may contain data that should not be included in the manifest.
+ * The plugin developer can use isWritingManifest to determine if the default value should be omitted from the manifest.
+ * in the function's implementation.
+ * @example
+ *   public static readonly args = {
+ *     one: Args.string({
+ *       default: async (context, isWritingManifest) => {
+ *          if (isWritingManifest) {
+ *             return undefined
+ *          }
+ *          return 'value that is used outside a manifest'
+ *       }),
+ *   };
+ */
+export type ArgDefault<T, P = CustomOptions> = T | ((context: DefaultContext<Arg<T, P>>, isWritingManifest?: boolean) => Promise<T>);
+/**
+ * Type to define a defaultHelp value for an arg.
+ * @param context The context of the arg.
+ * @param isWritingManifest Informs the function that a manifest file is being written.
+ * The manifest file is used to store the arg definitions, with a default value if present via defaultHelp, for a command and is published to npm.
+ * When a manifest file is being written, the default value may contain data that should not be included in the manifest.
+ * The plugin developer can use isWritingManifest to determine if the default value should be omitted from the manifest.
+ * in the function's implementation.
+ * @example
+ *   public static readonly args = {
+ *     one: Args.string({
+ *       defaultHelp: async (context, isWritingManifest) => {
+ *          if (isWritingManifest) {
+ *             return undefined
+ *          }
+ *          return 'value that is used outside a manifest'
+ *       }),
+ *   };
+ */
+export type ArgDefaultHelp<T, P = CustomOptions> = T | ((context: DefaultContext<Arg<T, P>>, isWritingManifest?: boolean) => Promise<string | undefined>);
 export type FlagRelationship = string | {
     name: string;
     when: (flags: Record<string, unknown>) => Promise<boolean>;

package/lib/interfaces/plugin.d.ts

@@ -74,5 +74,5 @@ export interface Plugin {
     findCommand(id: string, opts?: {
         must: boolean;
     }): Promise<Command.Class> | undefined;
-    load(): Promise<void>;
+    load(isWritingManifest: boolean): Promise<void>;
 }

package/lib/parser/parse.js

@@ -178,6 +178,12 @@ class Parser {
             const flag = this.input.flags[token.flag];
             if (!flag)
                 throw new errors_1.CLIError(`Unexpected flag ${token.flag}`);
+            // if flag has defaultHelp, capture its value into metadata
+            if (Reflect.has(flag, 'defaultHelp')) {
+                const defaultHelpProperty = Reflect.get(flag, 'defaultHelp');
+                const defaultHelp = (typeof defaultHelpProperty === 'function' ? await defaultHelpProperty({ options: flag, flags, ...this.context }) : defaultHelpProperty);
+                this.metaData.flags[token.flag] = { ...this.metaData.flags[token.flag], defaultHelp };
+            }
             if (flag.type === 'boolean') {
                 if (token.input === `--no-${flag.name}`) {
                     flags[token.flag] = false;
@@ -216,7 +222,7 @@ class Parser {
             const flag = this.input.flags[k];
             if (flags[k])
                 continue;
-            if (flag.env && Object.prototype.hasOwnProperty.call(process.env, flag.env)) {
+            if (flag.env && Reflect.has(process.env, flag.env)) {
                 const input = process.env[flag.env];
                 if (flag.type === 'option') {
                     if (input) {
@@ -230,7 +236,7 @@ class Parser {
                 }
             }
             if (!(k in flags) && flag.default !== undefined) {
-                this.metaData.flags[k] = { setFromDefault: true };
+                this.metaData.flags[k] = { ...this.metaData.flags[k], setFromDefault: true };
                 const defaultValue = (typeof flag.default === 'function' ? await flag.default({ options: flag, flags, ...this.context }) : flag.default);
                 flags[k] = defaultValue;
             }

package/lib/parser/validate.js

@@ -94,7 +94,8 @@ async function validate(parse) {
             if (parse.output.metadata.flags && parse.output.metadata.flags[name]?.setFromDefault)
                 continue;
             if (parse.output.flags[flag] !== undefined) {
-                return { ...base, status: 'failed', reason: `--${flag}=${parse.output.flags[flag]} cannot also be provided when using --${name}` };
+                const flagValue = parse.output.metadata.flags?.[flag]?.defaultHelp ?? parse.output.flags[flag];
+                return { ...base, status: 'failed', reason: `--${flag}=${flagValue} cannot also be provided when using --${name}` };
             }
         }
         return { ...base, status: 'success' };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "2.6.4",
+  "version": "2.7.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {
@@ -37,9 +37,9 @@
   },
   "devDependencies": {
     "@commitlint/config-conventional": "^12.1.4",
-    "@oclif/plugin-help": "^5.2.7",
+    "@oclif/plugin-help": "^5.2.8",
     "@oclif/plugin-plugins": "^2.4.1",
-    "@oclif/test": "^2.3.9",
+    "@oclif/test": "^2.3.11",
     "@types/ansi-styles": "^3.2.1",
     "@types/chai": "^4.3.4",
     "@types/chai-as-promised": "^7.1.5",
@@ -65,7 +65,7 @@
     "eslint": "^7.32.0",
     "eslint-config-oclif": "^4.0.0",
     "eslint-config-oclif-typescript": "^1.0.3",
-    "fancy-test": "^2.0.12",
+    "fancy-test": "^2.0.15",
     "globby": "^11.1.0",
     "husky": "6",
     "mocha": "^8.4.0",