@oclif/core 4.0.0-beta.7 → 4.0.0-beta.9

package/lib/help/formatter.d.ts

@@ -59,9 +59,9 @@ export declare class HelpFormatter {
     indent(body: string, spacing?: number): string;
     renderList(input: (string | undefined)[][], opts: {
         indentation: number;
-        multiline?: boolean;
-        spacer?: string;
-        stripAnsi?: boolean;
+        multiline?: boolean | undefined;
+        spacer?: string | undefined;
+        stripAnsi?: boolean | undefined;
     }): string;
     section(header: string, body: [string, string | undefined][] | HelpSection | HelpSectionKeyValueTable | string): string;
     /**

package/lib/help/index.d.ts

@@ -3,6 +3,7 @@ import * as Interfaces from '../interfaces';
 import { CommandHelp } from './command';
 import { HelpFormatter } from './formatter';
 export { CommandHelp } from './command';
+export { HelpFormatter, type HelpSection, type HelpSectionKeyValueTable, type HelpSectionRenderer } from './formatter';
 export { getHelpFlagAdditions, normalizeArgv, standardizeIDFromArgv } from './util';
 export declare abstract class HelpBase extends HelpFormatter {
     constructor(config: Interfaces.Config, opts?: Partial<Interfaces.HelpOptions>);

package/lib/help/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadHelpClass = exports.Help = exports.HelpBase = exports.standardizeIDFromArgv = exports.normalizeArgv = exports.getHelpFlagAdditions = exports.CommandHelp = void 0;
+exports.loadHelpClass = exports.Help = exports.HelpBase = exports.standardizeIDFromArgv = exports.normalizeArgv = exports.getHelpFlagAdditions = exports.HelpFormatter = exports.CommandHelp = void 0;
 const ansis_1 = __importDefault(require("ansis"));
 const ts_path_1 = require("../config/ts-path");
 const error_1 = require("../errors/error");
@@ -12,7 +12,7 @@ const symbols_1 = require("../symbols");
 const cache_default_value_1 = require("../util/cache-default-value");
 const ids_1 = require("../util/ids");
 const util_1 = require("../util/util");
-const ux_1 = __importDefault(require("../ux"));
+const ux_1 = require("../ux");
 const theme_1 = require("../ux/theme");
 const command_1 = require("./command");
 const formatter_1 = require("./formatter");
@@ -20,6 +20,8 @@ const root_1 = __importDefault(require("./root"));
 const util_2 = require("./util");
 var command_2 = require("./command");
 Object.defineProperty(exports, "CommandHelp", { enumerable: true, get: function () { return command_2.CommandHelp; } });
+var formatter_2 = require("./formatter");
+Object.defineProperty(exports, "HelpFormatter", { enumerable: true, get: function () { return formatter_2.HelpFormatter; } });
 var util_3 = require("./util");
 Object.defineProperty(exports, "getHelpFlagAdditions", { enumerable: true, get: function () { return util_3.getHelpFlagAdditions; } });
 Object.defineProperty(exports, "normalizeArgv", { enumerable: true, get: function () { return util_3.normalizeArgv; } });
@@ -144,7 +146,7 @@ class Help extends HelpBase {
         return new this.CommandHelpClass(command, this.config, this.opts);
     }
     log(...args) {
-        this.opts.sendToStderr ? ux_1.default.stderr(args) : ux_1.default.stdout(args);
+        this.opts.sendToStderr ? ux_1.ux.stderr(args) : ux_1.ux.stdout(args);
     }
     async showCommandHelp(command) {
         const name = command.id;
@@ -314,17 +316,24 @@ exports.Help = Help;
 function extractClass(exported) {
     return exported && exported.default ? exported.default : exported;
 }
+function determineLocation(helpClass) {
+    if (typeof helpClass === 'string')
+        return { identifier: 'default', target: helpClass };
+    if (!helpClass.identifier)
+        return { ...helpClass, identifier: 'default' };
+    return helpClass;
+}
 async function loadHelpClass(config) {
-    const { pjson } = config;
-    const configuredClass = pjson.oclif?.helpClass;
-    if (configuredClass) {
+    if (config.pjson.oclif?.helpClass) {
+        const { identifier, target } = determineLocation(config.pjson.oclif?.helpClass);
         try {
-            const path = (await (0, ts_path_1.tsPath)(config.root, configuredClass)) ?? configuredClass;
-            const exported = await (0, module_loader_1.load)(config, path);
-            return extractClass(exported);
+            const path = (await (0, ts_path_1.tsPath)(config.root, target)) ?? target;
+            const module = await (0, module_loader_1.load)(config, path);
+            const helpClass = module[identifier] ?? (identifier === 'default' ? extractClass(module) : undefined);
+            return extractClass(helpClass);
         }
         catch (error) {
-            throw new Error(`Unable to load configured help class "${configuredClass}", failed with message:\n${error.message}`);
+            throw new Error(`Unable to load configured help class "${target}", failed with message:\n${error.message}`);
         }
     }
     return Help;

package/lib/index.d.ts

@@ -6,15 +6,14 @@ export { handle } from './errors/handle';
 export { execute } from './execute';
 export * as Flags from './flags';
 export { flush } from './flush';
-export { CommandHelp, Help, HelpBase, loadHelpClass } from './help';
-export { HelpSection, HelpSectionKeyValueTable, HelpSectionRenderer } from './help/formatter';
+export { CommandHelp, Help, HelpBase, type HelpSection, type HelpSectionKeyValueTable, type HelpSectionRenderer, loadHelpClass, } from './help';
 export * as Interfaces from './interfaces';
-export { Hook } from './interfaces/hooks';
+export { type Hook } from './interfaces/hooks';
 export { getLogger } from './logger';
 export { run } from './main';
 export * as ModuleLoader from './module-loader';
 export * as Parser from './parser';
 export { Performance } from './performance';
-export { Settings, settings } from './settings';
+export { type Settings, settings } from './settings';
 export { toConfiguredId, toStandardizedId } from './util/ids';
-export { methods as ux } from './ux';
+export { ux } from './ux';

package/lib/index.js

@@ -69,4 +69,4 @@ var ids_1 = require("./util/ids");
 Object.defineProperty(exports, "toConfiguredId", { enumerable: true, get: function () { return ids_1.toConfiguredId; } });
 Object.defineProperty(exports, "toStandardizedId", { enumerable: true, get: function () { return ids_1.toStandardizedId; } });
 var ux_1 = require("./ux");
-Object.defineProperty(exports, "ux", { enumerable: true, get: function () { return ux_1.methods; } });
+Object.defineProperty(exports, "ux", { enumerable: true, get: function () { return ux_1.ux; } });

package/lib/interfaces/config.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="node" />
 import { Command } from '../command';
 import { Hook, Hooks } from './hooks';
-import { PJSON } from './pjson';
+import { OclifConfiguration, PJSON, S3Templates } from './pjson';
 import { Options, Plugin } from './plugin';
 import { Theme } from './theme';
 import { Topic } from './topic';
@@ -34,8 +34,8 @@ export interface Config {
     /**
      * name of any bin aliases that will execute the cli
      */
-    readonly binAliases?: string[];
-    readonly binPath?: string;
+    readonly binAliases?: string[] | undefined;
+    readonly binPath?: string | undefined;
     /**
      * cache directory to use for CLI
      *
@@ -89,9 +89,9 @@ export interface Config {
     /**
      * npm registry to use for installing plugins
      */
-    readonly npmRegistry?: string;
-    readonly nsisCustomization?: string;
-    readonly pjson: PJSON.CLI;
+    readonly npmRegistry?: string | undefined;
+    readonly nsisCustomization?: string | undefined;
+    readonly pjson: PJSON;
     /**
      * process.platform
      */
@@ -101,7 +101,7 @@ export interface Config {
     runCommand<T = unknown>(id: string, argv?: string[], cachedCommand?: Command.Loadable): Promise<T>;
     runHook<T extends keyof Hooks>(event: T, opts: Hooks[T]['options'], timeout?: number, captureErrors?: boolean): Promise<Hook.Result<Hooks[T]['return']>>;
     s3Key(type: 'unversioned' | 'versioned', ext: '.tar.gz' | '.tar.xz', options?: Config.s3Key.Options): string;
-    s3Key(type: keyof PJSON.S3.Templates, options?: Config.s3Key.Options): string;
+    s3Key(type: keyof S3Templates, options?: Config.s3Key.Options): string;
     s3Url(key: string): string;
     scopedEnvVar(key: string): string | undefined;
     scopedEnvVarKey(key: string): string;
@@ -111,10 +111,10 @@ export interface Config {
      * active shell
      */
     readonly shell: string;
-    readonly theme?: Theme;
+    readonly theme?: Theme | undefined;
     topicSeparator: ' ' | ':';
     readonly topics: Topic[];
-    readonly updateConfig: NonNullable<PJSON.CLI['oclif']['update']>;
+    readonly updateConfig: NonNullable<OclifConfiguration['update']>;
     /**
      * user agent to use for http calls
      *

package/lib/interfaces/errors.d.ts

@@ -3,25 +3,25 @@ export type CommandError = Error & {
 };
 export interface OclifError {
     oclif: {
-        exit?: number;
+        exit?: number | undefined;
     };
 }
 export interface PrettyPrintableError {
     /**
      * a unique error code for this error class
      */
-    code?: string;
+    code?: string | undefined;
     /**
      * message to display related to the error
      */
-    message?: string;
+    message?: string | undefined;
     /**
      * a url to find out more information related to this error
      * or fixing the error
      */
-    ref?: string;
+    ref?: string | undefined;
     /**
      * a suggestion that may be useful or provide additional context
      */
-    suggestions?: string[];
+    suggestions?: string[] | undefined;
 }

package/lib/interfaces/flags.d.ts

@@ -3,12 +3,12 @@ import { FlagInput } from './parser';
  * Infer the flags that are returned by Command.parse. This is useful for when you want to assign the flags as a class property.
  *
  * @example
- * export type StatusFlags = Interfaces.InferredFlags<typeof Status.flags & typeof Status.baseFlags>
+ * export type StatusFlags = Interfaces.InferredFlags<typeof Status.flags>
  *
  * export abstract class BaseCommand extends Command {
  *   static enableJsonFlag = true
  *
- *   static baseFlags = {
+ *   static flags = {
  *     config: Flags.string({
  *       description: 'specify config file',
  *     }),
@@ -17,6 +17,7 @@ import { FlagInput } from './parser';
  *
  * export default class Status extends BaseCommand {
  *   static flags = {
+ *    ...BaseCommand.flags,
  *     force: Flags.boolean({char: 'f', description: 'a flag'}),
  *   }
  *

package/lib/interfaces/hooks.d.ts

@@ -74,7 +74,7 @@ export interface Hooks {
     preparse: {
         options: {
             argv: string[];
-            options: Input<OutputFlags<any>, OutputFlags<any>, OutputFlags<any>>;
+            options: Input<OutputFlags<any>, OutputFlags<any>>;
         };
         return: string[];
     };

package/lib/interfaces/index.d.ts

@@ -8,7 +8,7 @@ export type { Hook, Hooks } from './hooks';
 export type { Logger } from './logger';
 export type { Manifest } from './manifest';
 export type { Arg, BooleanFlag, CustomOptions, Deprecation, Flag, FlagDefinition, OptionFlag } from './parser';
-export type { PJSON } from './pjson';
+export type { OclifConfiguration, PJSON, S3, S3Templates, UserPJSON } from './pjson';
 export type { Options, Plugin, PluginOptions } from './plugin';
 export type { S3Manifest } from './s3-manifest';
 export type { Theme } from './theme';

package/lib/interfaces/parser.d.ts

@@ -8,10 +8,10 @@ export type ArgOutput = {
 };
 export type CLIParseErrorOptions = {
     parse: {
-        input?: ParserInput;
-        output?: ParserOutput;
+        input?: ParserInput | undefined;
+        output?: ParserOutput | undefined;
     };
-    exit?: number;
+    exit?: number | undefined;
 };
 export type OutputArgs<T extends ParserInput['args']> = {
     [P in keyof T]: any;
@@ -426,12 +426,11 @@ export type FlagDefinition<T, P = CustomOptions, R extends ReturnTypeSwitches =
     }>>;
 };
 export type Flag<T> = BooleanFlag<T> | OptionFlag<T>;
-export type Input<TFlags extends FlagOutput, BFlags extends FlagOutput, AFlags extends ArgOutput> = {
+export type Input<TFlags extends FlagOutput, AFlags extends ArgOutput> = {
     flags?: FlagInput<TFlags>;
-    baseFlags?: FlagInput<BFlags>;
     enableJsonFlag?: true | false;
     args?: ArgInput<AFlags>;
-    strict?: boolean;
+    strict?: boolean | undefined;
     context?: ParserContext;
     '--'?: boolean;
 };
@@ -441,10 +440,10 @@ export type ParserInput = {
     args: ArgInput<any>;
     strict: boolean;
     context: ParserContext | undefined;
-    '--'?: boolean;
+    '--'?: boolean | undefined;
 };
 export type ParserContext = Command & {
-    token?: FlagToken | ArgToken;
+    token?: FlagToken | ArgToken | undefined;
 };
 export type FlagInput<T extends FlagOutput = {
     [flag: string]: any;

package/lib/interfaces/pjson.d.ts

@@ -1,21 +1,5 @@
 import { HelpOptions } from './help';
-export interface PJSON {
-    [k: string]: any;
-    dependencies?: {
-        [name: string]: string;
-    };
-    devDependencies?: {
-        [name: string]: string;
-    };
-    oclif: {
-        bin?: string;
-        dirname?: string;
-        hooks?: Record<string, string | string[]>;
-        plugins?: string[];
-        schema?: number;
-    };
-    version: string;
-}
+import { Theme } from './theme';
 export type CommandDiscovery = {
     /**
      * The strategy to use for loading commands.
@@ -96,141 +80,223 @@ export type HookOptions = {
      */
     identifier: string;
 };
-export declare namespace PJSON {
-    interface Plugin extends PJSON {
-        name: string;
-        oclif: PJSON['oclif'] & {
-            additionalHelpFlags?: string[];
-            additionalVersionFlags?: string[];
-            aliases?: {
-                [name: string]: null | string;
-            };
-            commands?: string | CommandDiscovery;
-            /**
-             * Default command id when no command is found. This is used to support single command CLIs.
-             * Only supported value is "."
-             *
-             * @deprecated Use `commands.strategy: 'single'` instead.
-             */
-            default?: string;
+export type HelpLocationOptions = {
+    /**
+     * The file path containing help class.
+     */
+    target: string;
+    /**
+     * The name of the export to use when loading the help class from the `target` file. Defaults to `default`.
+     */
+    identifier: string;
+};
+export type S3Templates = {
+    baseDir?: string;
+    manifest?: string;
+    unversioned?: string;
+    versioned?: string;
+};
+export type S3 = {
+    acl?: string | undefined;
+    bucket?: string | undefined;
+    folder?: string | undefined;
+    gz?: boolean | undefined;
+    host?: string | undefined;
+    indexVersionLimit?: number | undefined;
+    templates?: {
+        target: S3Templates;
+        vanilla: S3Templates;
+    } | undefined;
+    xz?: boolean | undefined;
+};
+export type OclifConfiguration = {
+    /**
+     * Flags in addition to --help that should trigger help output.
+     */
+    additionalHelpFlags?: string[];
+    /**
+     * Flags in addition to --version that should trigger version output.
+     */
+    additionalVersionFlags?: string[];
+    /**
+     * Plugin aliases.
+     */
+    aliases?: {
+        [name: string]: null | string;
+    };
+    /**
+     * The name of the executable.
+     */
+    bin?: string;
+    /**
+     * Aliases for the executable.
+     */
+    binAliases?: string[];
+    commands?: string | CommandDiscovery;
+    /**
+     * Your CLI's description. Overrides the description in the package.json.
+     */
+    description?: string | undefined;
+    /**
+     * Plugins to load when in development mode.
+     */
+    devPlugins?: string[];
+    /**
+     * The directory name to use when determining the cache, config, and data directories.
+     */
+    dirname?: string;
+    /**
+     * Example plugin to use in @oclif/plugin-plugin's help output.
+     */
+    examplePlugin?: string;
+    /**
+     * Customize the exit codes for the CLI.
+     */
+    exitCodes?: {
+        default?: number;
+        failedFlagParsing?: number;
+        failedFlagValidation?: number;
+        invalidArgsSpec?: number;
+        nonExistentFlag?: number;
+        requiredArgs?: number;
+        unexpectedArgs?: number;
+    };
+    /**
+     * Enable flexible taxonomy for commands.
+     */
+    flexibleTaxonomy?: boolean;
+    /**
+     * The location of your custom help class.
+     */
+    helpClass?: string | HelpLocationOptions;
+    /**
+     * Options for the help output.
+     */
+    helpOptions?: HelpOptions;
+    /**
+     * Register hooks to run at various points in the CLI lifecycle.
+     */
+    hooks?: {
+        [name: string]: string | string[] | HookOptions | HookOptions[];
+    };
+    /**
+     * Plugins that can be installed just-in-time.
+     */
+    jitPlugins?: Record<string, string>;
+    macos?: {
+        identifier?: string;
+        sign?: string;
+    };
+    /**
+     * Use a private or alternate npm registry.
+     */
+    npmRegistry?: string;
+    /**
+     * Script to run during postinstall on windows.
+     */
+    nsisCustomization?: string;
+    /**
+     * Plugin prefix to use when working with plugins with @oclif/plugin-plugins.
+     *
+     * Defaults to `plugin-`.
+     */
+    pluginPrefix?: string;
+    /**
+     * Plugins to load.
+     */
+    plugins?: string[];
+    /**
+     * Template string used to build links to source code in CLI's README (when using `oclif readme`).
+     */
+    repositoryPrefix?: string;
+    schema?: number;
+    /**
+     * The namespace to be used for plugins of your CLI, e.g. `@salesforce`.
+     */
+    scope?: string;
+    /**
+     * State of your CLI
+     *
+     * - `beta` - will show message to user that command or CLI is in beta
+     * - `deprecated` - will show message to user that command or CLI is deprecated
+     */
+    state?: 'beta' | 'deprecated' | string;
+    /**
+     * The theme to ship with the CLI.
+     *
+     * Can be a path to a JSON file or a Theme object.
+     */
+    theme?: string | Theme;
+    /**
+     * Separator to use for your CLI. Can be `:` or ` `.
+     */
+    topicSeparator?: ' ' | ':';
+    /**
+     * Customize the topics in the CLI.
+     */
+    topics?: {
+        [k: string]: {
             description?: string;
-            devPlugins?: string[];
-            exitCodes?: {
-                default?: number;
-                failedFlagParsing?: number;
-                failedFlagValidation?: number;
-                invalidArgsSpec?: number;
-                nonExistentFlag?: number;
-                requiredArgs?: number;
-                unexpectedArgs?: number;
-            };
-            flexibleTaxonomy?: boolean;
-            helpClass?: string;
-            helpOptions?: HelpOptions;
-            hooks?: {
-                [name: string]: string | string[] | HookOptions | HookOptions[];
-            };
-            jitPlugins?: Record<string, string>;
-            macos?: {
-                identifier?: string;
-                sign?: string;
-            };
-            plugins?: string[];
-            repositoryPrefix?: string;
-            schema?: number;
-            state?: 'beta' | 'deprecated' | string;
-            theme?: string;
-            topicSeparator?: ' ' | ':';
-            topics?: {
-                [k: string]: {
-                    description?: string;
-                    hidden?: boolean;
-                    subtopics?: Plugin['oclif']['topics'];
-                };
-            };
-            update?: {
-                autoupdate?: {
-                    debounce?: number;
-                    rollout?: number;
-                };
-                disableNpmLookup?: boolean;
-                node: {
-                    targets?: string[];
-                    version?: string;
-                    options?: string | string[];
-                };
-                s3: S3;
-            };
-            windows?: {
-                homepage?: string;
-                keypath?: string;
-                name?: string;
-            };
-        };
-        version: string;
-    }
-    interface S3 {
-        acl?: string;
-        bucket?: string;
-        folder?: string;
-        gz?: boolean;
-        host?: string;
-        templates: {
-            target: S3.Templates;
-            vanilla: S3.Templates;
+            hidden?: boolean;
+            subtopics?: OclifConfiguration['topics'];
         };
-        xz?: boolean;
-    }
-    namespace S3 {
-        interface Templates {
-            baseDir?: string;
-            manifest?: string;
-            unversioned?: string;
-            versioned?: string;
-        }
-    }
-    interface CLI extends Plugin {
-        oclif: Plugin['oclif'] & {
-            bin?: string;
-            binAliases?: string[];
-            dirname?: string;
-            flexibleTaxonomy?: boolean;
-            jitPlugins?: Record<string, string>;
-            npmRegistry?: string;
-            nsisCustomization?: string;
-            schema?: number;
-            scope?: string;
-            pluginPrefix?: string;
-            'warn-if-update-available'?: {
-                authorization: string;
-                message: string;
-                registry: string;
-                timeoutInDays: number;
-                frequency: number;
-                frequencyUnit: 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds';
-            };
+    };
+    update?: {
+        autoupdate?: {
+            debounce?: number;
+            rollout?: number;
         };
-    }
-    interface User extends PJSON {
-        oclif: PJSON['oclif'] & {
-            plugins?: (PluginTypes.Link | PluginTypes.User | string)[];
+        disableNpmLookup?: boolean;
+        node?: {
+            targets?: string[];
+            version?: string;
+            options?: string | string[];
         };
-        private?: boolean;
-    }
-    type PluginTypes = {
-        root: string;
-    } | PluginTypes.Link | PluginTypes.User;
-    namespace PluginTypes {
-        interface User {
-            name: string;
-            tag?: string;
-            type: 'user';
-            url?: string;
-        }
-        interface Link {
-            name: string;
-            root: string;
-            type: 'link';
-        }
-    }
-}
+        s3?: S3;
+    };
+    'warn-if-update-available'?: {
+        authorization?: string;
+        message?: string;
+        registry?: string;
+        timeoutInDays?: number;
+        frequency?: number;
+        frequencyUnit?: 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds';
+    };
+    windows?: {
+        homepage?: string;
+        keypath?: string;
+        name?: string;
+    };
+};
+export type UserPlugin = {
+    name: string;
+    tag?: string;
+    type: 'user';
+    url?: string;
+};
+export type LinkedPlugin = {
+    name: string;
+    root: string;
+    type: 'link';
+};
+export type PluginTypes = {
+    root: string;
+} | UserPlugin | LinkedPlugin;
+export type UserPJSON = {
+    oclif: {
+        plugins?: PluginTypes[];
+    };
+    private?: boolean;
+};
+export type PJSON = {
+    [k: string]: any;
+    dependencies?: {
+        [name: string]: string;
+    };
+    devDependencies?: {
+        [name: string]: string;
+    };
+    name: string;
+    oclif: OclifConfiguration;
+    version: string;
+};