@oclif/core 4.0.0-beta.9 → 4.0.0

package/lib/command.d.ts

@@ -15,6 +15,7 @@ export declare abstract class Command {
     static aliases: string[];
     /** An order-dependent object of arguments for the command */
     static args: ArgInput;
+    static baseFlags: FlagInput;
     /**
      * Emit deprecation warning when a command alias is used
      */
@@ -108,7 +109,7 @@ export declare abstract class Command {
     log(message?: string, ...args: any[]): void;
     protected logJson(json: unknown): void;
     logToStderr(message?: string, ...args: any[]): void;
-    protected parse<F extends FlagOutput, A extends ArgOutput>(options?: Input<F, A>, argv?: string[]): Promise<ParserOutput<F, A>>;
+    protected parse<F extends FlagOutput, B extends FlagOutput, A extends ArgOutput>(options?: Input<F, B, A>, argv?: string[]): Promise<ParserOutput<F, A>>;
     protected toErrorJson(err: unknown): any;
     protected toSuccessJson(result: unknown): any;
     warn(input: Error | string): Error | string;

package/lib/command.js

@@ -61,6 +61,7 @@ class Command {
     static aliases = [];
     /** An order-dependent object of arguments for the command */
     static args = {};
+    static baseFlags;
     /**
      * Emit deprecation warning when a command alias is used
      */
@@ -231,7 +232,7 @@ class Command {
         const opts = {
             context: this,
             ...options,
-            flags: (0, aggregate_flags_1.aggregateFlags)(options.flags, options.enableJsonFlag),
+            flags: (0, aggregate_flags_1.aggregateFlags)(options.flags, options.baseFlags, options.enableJsonFlag),
         };
         const hookResult = await this.config.runHook('preparse', { argv: [...argv], options: opts });
         // Since config.runHook will only run the hook for the root plugin, hookResult.successes will always have a length of 0 or 1
@@ -268,7 +269,7 @@ class Command {
         }
     }
     warnIfFlagDeprecated(flags) {
-        const allFlags = (0, aggregate_flags_1.aggregateFlags)(this.ctor.flags, this.ctor.enableJsonFlag);
+        const allFlags = (0, aggregate_flags_1.aggregateFlags)(this.ctor.flags, this.ctor.baseFlags, this.ctor.enableJsonFlag);
         for (const flag of Object.keys(flags)) {
             const flagDef = allFlags[flag];
             const deprecated = flagDef?.deprecated;

package/lib/config/ts-path.js

@@ -78,6 +78,24 @@ async function loadTSConfig(root) {
         (0, warn_1.memoizedWarn)(`Could not parse tsconfig.json for ${root}. Falling back to compiled source.`);
     }
 }
+async function registerTsx(root, moduleType) {
+    if (REGISTERED.has(root))
+        return;
+    try {
+        const apiPath = moduleType === 'module' ? 'tsx/esm/api' : 'tsx/cjs/api';
+        const tsxPath = require.resolve(apiPath, { paths: [root] });
+        if (!tsxPath)
+            return;
+        debug('registering tsx at', root);
+        debug('tsx path:', tsxPath);
+        const { register } = await import(tsxPath);
+        register();
+        REGISTERED.add(root);
+    }
+    catch {
+        debug(`Could not find tsx. Skipping tsx registration for ${root}.`);
+    }
+}
 async function registerTSNode(root, tsconfig) {
     if (REGISTERED.has(root))
         return;
@@ -135,18 +153,20 @@ async function registerTSNode(root, tsconfig) {
 }
 /**
  * Skip ts-node registration for ESM plugins in production.
- * The node ecosystem is not mature enough to support auto-transpiling ESM modules at this time.
+ * The node/ts-node ecosystem is not mature enough to support auto-transpiling ESM modules at this time.
  * See the following:
  * - https://github.com/TypeStrong/ts-node/issues/1791#issuecomment-1149754228
  * - https://github.com/nodejs/node/issues/49432
  * - https://github.com/nodejs/node/pull/49407
  * - https://github.com/nodejs/node/issues/34049
  *
- * We still register ts-node for ESM plugins when NODE_ENV is "test" or "development" and root plugin is also ESM
+ * We still register tsx/ts-node for ESM plugins when NODE_ENV is "test" or "development" and root plugin is also ESM
  * since that allows plugins to be auto-transpiled when developing locally using `bin/dev.js`.
  */
 function cannotTranspileEsm(rootPlugin, plugin, isProduction) {
-    return (isProduction || rootPlugin?.moduleType === 'commonjs') && plugin?.moduleType === 'module';
+    return ((isProduction || rootPlugin?.moduleType === 'commonjs') &&
+        plugin?.moduleType === 'module' &&
+        !plugin?.pjson.devDependencies?.tsx);
 }
 /**
  * If the dev script is run with ts-node for an ESM plugin, skip ts-node registration
@@ -166,15 +186,18 @@ function cannotUseTsNode(root, plugin, isProduction) {
 /**
  * Determine the path to the source file from the compiled ./lib files
  */
-async function determinePath(root, orig) {
+async function determinePath(root, orig, plugin) {
     const tsconfig = await loadTSConfig(root);
     if (!tsconfig)
         return orig;
     debug(`Determining path for ${orig}`);
-    if (RUN_TIME === 'tsx' || RUN_TIME === 'bun') {
+    if (RUN_TIME === 'bun') {
         debug(`Skipping ts-node registration for ${root} because the runtime is: ${RUN_TIME}`);
     }
     else {
+        // attempt to register tsx first. If it fails to register, we will fall back to ts-node
+        await registerTsx(root, plugin?.moduleType);
+        // if tsx registration succeeded, then this will exit early since the path will be in REGISTERED already
         await registerTSNode(root, tsconfig);
     }
     const { baseUrl, outDir, rootDir, rootDirs } = tsconfig.compilerOptions;
@@ -251,7 +274,7 @@ async function tsPath(root, orig, plugin) {
         return orig;
     }
     try {
-        return await determinePath(root, orig);
+        return await determinePath(root, orig, plugin);
     }
     catch (error) {
         debug(error);

package/lib/help/command.js

@@ -153,12 +153,7 @@ class CommandHelp extends formatter_1.HelpFormatter {
             label = labels.join(flag.char ? (0, theme_1.colorize)(this.config?.theme?.flagSeparator, ', ') : '  ');
         }
         if (flag.type === 'option') {
-            let value = flag.helpValue || (this.opts.showFlagNameInTitle ? flag.name : '<value>');
-            if (!flag.helpValue && flag.options) {
-                value = showOptions || this.opts.showFlagOptionsInTitle ? `${flag.options.join('|')}` : '<option>';
-            }
-            if (flag.multiple)
-                value += '...';
+            let value = docopts_1.DocOpts.formatUsageType(flag, this.opts.showFlagNameInTitle ?? false, this.opts.showFlagOptionsInTitle ?? showOptions);
             if (!value.includes('|'))
                 value = ansis_1.default.underline(value);
             label += `=${value}`;
@@ -304,7 +299,11 @@ class CommandHelp extends formatter_1.HelpFormatter {
             const dollarSign = (0, theme_1.colorize)(this.config?.theme?.dollarSign, '$');
             const bin = (0, theme_1.colorize)(this.config?.theme?.bin, this.config.bin);
             const command = (0, theme_1.colorize)(this.config?.theme?.command, '<%= command.id %>');
-            const commandDescription = (0, theme_1.colorize)(this.config?.theme?.sectionDescription, u.replace('<%= command.id %>', '').replace(standardId, '').replace(configuredId, '').trim());
+            const commandDescription = (0, theme_1.colorize)(this.config?.theme?.sectionDescription, u
+                .replace('<%= command.id %>', '')
+                .replace(new RegExp(`^${standardId}`), '')
+                .replace(new RegExp(`^${configuredId}`), '')
+                .trim());
             const line = `${dollarSign} ${bin} ${command} ${commandDescription}`.trim();
             if (line.length > allowedSpacing) {
                 const splitIndex = line.slice(0, Math.max(0, allowedSpacing)).lastIndexOf(' ');

package/lib/help/docopts.d.ts

@@ -60,6 +60,7 @@ export declare class DocOpts {
     private flagList;
     private flagMap;
     constructor(cmd: Command.Loadable);
+    static formatUsageType(flag: Command.Flag.Any, showFlagName: boolean, showOptions: boolean): string;
     static generate(cmd: Command.Loadable): string;
     toString(): string;
     private combineElementsToFlag;

package/lib/help/docopts.js

@@ -73,6 +73,27 @@ class DocOpts {
             return flag;
         });
     }
+    static formatUsageType(flag, showFlagName, showOptions) {
+        if (flag.type !== 'option')
+            return '';
+        let helpValues;
+        if (flag.helpValue) {
+            // if there is a given helpValue, use it
+            helpValues = typeof flag.helpValue === 'string' ? [flag.helpValue] : flag.helpValue;
+        }
+        else if (flag.options) {
+            // if there are options, show them if wanted
+            helpValues = [showOptions ? flag.options.join('|') : '<option>'];
+        }
+        else if (showFlagName) {
+            helpValues = [flag.name];
+        }
+        else {
+            // default to <value>
+            helpValues = ['<value>'];
+        }
+        return helpValues.map((v) => `${v}${flag.multiple ? '...' : ''}`).join(' ');
+    }
     static generate(cmd) {
         return new DocOpts(cmd).toString();
     }
@@ -93,7 +114,7 @@ class DocOpts {
                 const name = flag.char ? `-${flag.char}` : `--${flag.name}`;
                 if (flag.type === 'boolean')
                     return name;
-                return `${name}=<value>`;
+                return `${name}=${DocOpts.formatUsageType(flag, false, true)}`;
             }));
         }
         return opts.join(' ');
@@ -123,7 +144,7 @@ class DocOpts {
             // not all flags have short names
             const flagName = flag.char ? `-${flag.char}` : `--${flag.name}`;
             if (flag.type === 'option') {
-                type = flag.options ? ` ${flag.options.join('|')}` : ' <value>';
+                type = ` ${DocOpts.formatUsageType(flag, false, true)}`;
             }
             const element = `${flagName}${type}`;
             elementMap[flag.name] = element;

package/lib/interfaces/flags.d.ts

@@ -3,7 +3,7 @@ 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>
+ * export type StatusFlags = Interfaces.InferredFlags<typeof Status.flags && typeof Status.baseFlags>
  *
  * export abstract class BaseCommand extends Command {
  *   static enableJsonFlag = true
@@ -17,7 +17,6 @@ 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>>;
+            options: Input<OutputFlags<any>, 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 { OclifConfiguration, PJSON, S3, S3Templates, UserPJSON } from './pjson';
+export type { LinkedPlugin, OclifConfiguration, PJSON, S3, S3Templates, UserPJSON, UserPlugin } 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

@@ -198,7 +198,7 @@ export type BooleanFlagProps = FlagProps & {
 };
 export type OptionFlagProps = FlagProps & {
     type: 'option';
-    helpValue?: string;
+    helpValue?: string | string[];
     options?: readonly string[];
     multiple?: boolean;
     /**
@@ -426,8 +426,9 @@ export type FlagDefinition<T, P = CustomOptions, R extends ReturnTypeSwitches =
     }>>;
 };
 export type Flag<T> = BooleanFlag<T> | OptionFlag<T>;
-export type Input<TFlags extends FlagOutput, AFlags extends ArgOutput> = {
+export type Input<TFlags extends FlagOutput, BFlags extends FlagOutput, AFlags extends ArgOutput> = {
     flags?: FlagInput<TFlags>;
+    baseFlags?: FlagInput<BFlags>;
     enableJsonFlag?: true | false;
     args?: ArgInput<AFlags>;
     strict?: boolean | undefined;

package/lib/interfaces/pjson.d.ts

@@ -177,7 +177,7 @@ export type OclifConfiguration = {
      * Register hooks to run at various points in the CLI lifecycle.
      */
     hooks?: {
-        [name: string]: string | string[] | HookOptions | HookOptions[];
+        [name: string]: string | string[] | HookOptions | HookOptions[] | (string | HookOptions)[];
     };
     /**
      * Plugins that can be installed just-in-time.
@@ -279,12 +279,9 @@ export type LinkedPlugin = {
     root: string;
     type: 'link';
 };
-export type PluginTypes = {
-    root: string;
-} | UserPlugin | LinkedPlugin;
 export type UserPJSON = {
     oclif: {
-        plugins?: PluginTypes[];
+        plugins?: (UserPlugin | LinkedPlugin)[];
     };
     private?: boolean;
 };

package/lib/parser/index.d.ts

@@ -1,3 +1,3 @@
 import { Input, OutputArgs, OutputFlags, ParserOutput } from '../interfaces/parser';
 export { flagUsages } from './help';
-export declare function parse<TFlags extends OutputFlags<any>, TArgs extends OutputArgs<any>>(argv: string[], options: Input<TFlags, TArgs>): Promise<ParserOutput<TFlags, TArgs>>;
+export declare function parse<TFlags extends OutputFlags<any>, BFlags extends OutputFlags<any>, TArgs extends OutputArgs<any>>(argv: string[], options: Input<TFlags, BFlags, TArgs>): Promise<ParserOutput<TFlags, BFlags, TArgs>>;

package/lib/parser/parse.js

@@ -315,9 +315,7 @@ class Parser {
                             .map(async (v) => parseFlagOrThrowError(v, i.inputFlag.flag, this.context, {
                             ...(0, util_1.last)(i.tokens),
                             input: v,
-                        }))))
-                            // eslint-disable-next-line unicorn/no-await-expression-member
-                            .map((v) => validateOptions(i.inputFlag.flag, v)),
+                        })))).map((v) => validateOptions(i.inputFlag.flag, v)),
                     };
                 }
                 // multiple in the oclif-core style

package/lib/util/aggregate-flags.d.ts

@@ -1,2 +1,2 @@
 import { FlagInput, FlagOutput } from '../interfaces/parser';
-export declare function aggregateFlags<F extends FlagOutput>(flags: FlagInput<F> | undefined, enableJsonFlag: boolean | undefined): FlagInput<F>;
+export declare function aggregateFlags<F extends FlagOutput, B extends FlagOutput>(flags: FlagInput<F> | undefined, baseFlags: FlagInput<B> | undefined, enableJsonFlag: boolean | undefined): FlagInput<F>;

package/lib/util/aggregate-flags.js

@@ -6,7 +6,8 @@ const json = (0, flags_1.boolean)({
     description: 'Format output as json.',
     helpGroup: 'GLOBAL',
 });
-function aggregateFlags(flags, enableJsonFlag) {
-    return (enableJsonFlag ? { json, ...flags } : flags);
+function aggregateFlags(flags, baseFlags, enableJsonFlag) {
+    const combinedFlags = { ...baseFlags, ...flags };
+    return (enableJsonFlag ? { json, ...combinedFlags } : combinedFlags);
 }
 exports.aggregateFlags = aggregateFlags;

package/lib/util/cache-command.js

@@ -6,7 +6,8 @@ const cache_default_value_1 = require("./cache-default-value");
 const ensure_arg_object_1 = require("./ensure-arg-object");
 const util_1 = require("./util");
 // In order to collect static properties up the inheritance chain, we need to recursively
-// access the prototypes until there's nothing left.
+// access the prototypes until there's nothing left. This allows us to combine baseFlags
+// and flags as well as add in the json flag if enableJsonFlag is enabled.
 function mergePrototype(result, cmd) {
     const proto = Object.getPrototypeOf(cmd);
     const filteredProto = (0, util_1.pickBy)(proto, (v) => v !== undefined);
@@ -70,10 +71,10 @@ async function cacheCommand(uncachedCmd, plugin, respectNoCacheDefault = false)
     const cmd = mergePrototype(uncachedCmd, uncachedCmd);
     // @ts-expect-error because v2 commands have flags stored in _flags
     const uncachedFlags = cmd.flags ?? cmd._flags;
-    // @ts-expect-error because v2 commands have base flags stored in `_baseFlags` and v4 commands never have `baseFlags`
+    // @ts-expect-error because v2 commands have base flags stored in _baseFlags
     const uncachedBaseFlags = cmd.baseFlags ?? cmd._baseFlags;
     const [flags, args] = await Promise.all([
-        await cacheFlags((0, aggregate_flags_1.aggregateFlags)({ ...uncachedFlags, ...uncachedBaseFlags }, cmd.enableJsonFlag), respectNoCacheDefault),
+        await cacheFlags((0, aggregate_flags_1.aggregateFlags)(uncachedFlags, uncachedBaseFlags, cmd.enableJsonFlag), respectNoCacheDefault),
         await cacheArgs((0, ensure_arg_object_1.ensureArgObject)(cmd.args), respectNoCacheDefault),
     ]);
     const stdProperties = {

package/lib/util/fs.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.existsSync = exports.safeReadJson = exports.readJsonSync = exports.readJson = exports.fileExists = exports.dirExists = void 0;
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
+const util_1 = require("./util");
 /**
  * Parser for Args.directory and Flags.directory. Checks that the provided path
  * exists and is a directory.
@@ -43,7 +44,15 @@ const fileExists = async (input) => {
     return input;
 };
 exports.fileExists = fileExists;
-const cache = new Map();
+class ProdOnlyCache extends Map {
+    set(key, value) {
+        if ((0, util_1.isProd)() ?? false) {
+            super.set(key, value);
+        }
+        return this;
+    }
+}
+const cache = new ProdOnlyCache();
 async function readJson(path) {
     if (cache.has(path)) {
         return JSON.parse(cache.get(path));

package/lib/ux/index.d.ts

@@ -55,13 +55,13 @@ export declare const ux: {
      *
      * See node's util.format() for formatting options.
      */
-    stderr: (str: string | string[] | undefined, ...args: string[]) => void;
+    stderr: (str?: string | string[] | undefined, ...args: string[]) => void;
     /**
      * Log a formatted string to stdout.
      *
      * See node's util.format() for formatting options.
      */
-    stdout: (str: string | string[] | undefined, ...args: string[]) => void;
+    stdout: (str?: string | string[] | undefined, ...args: string[]) => void;
     /**
      * Prints a pretty warning message to stderr.
      */

package/lib/ux/supports-color.d.ts

@@ -0,0 +1 @@
+export declare function supportsColor(): boolean;

package/lib/ux/supports-color.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportsColor = void 0;
+const supports_color_1 = require("supports-color");
+function supportsColor() {
+    return Boolean(supports_color_1.stdout) && Boolean(supports_color_1.stderr);
+}
+exports.supportsColor = supportsColor;

package/lib/ux/theme.js

@@ -6,7 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseTheme = exports.colorize = void 0;
 const ansis_1 = __importDefault(require("ansis"));
 const theme_1 = require("../interfaces/theme");
-function isStandardChalk(color) {
+const supports_color_1 = require("./supports-color");
+function isStandardAnsi(color) {
     return theme_1.STANDARD_ANSI.includes(color);
 }
 /**
@@ -18,7 +19,9 @@ function isStandardChalk(color) {
 function colorize(color, text) {
     if (!color)
         return text;
-    if (isStandardChalk(color))
+    if (!(0, supports_color_1.supportsColor)())
+        return text;
+    if (isStandardAnsi(color))
         return ansis_1.default[color](text);
     if (color.startsWith('#'))
         return ansis_1.default.hex(color)(text);
@@ -39,5 +42,5 @@ function parseTheme(theme) {
 }
 exports.parseTheme = parseTheme;
 function isValid(color) {
-    return color.startsWith('#') || color.startsWith('rgb') || isStandardChalk(color) ? color : undefined;
+    return color.startsWith('#') || color.startsWith('rgb') || isStandardAnsi(color) ? color : undefined;
 }

package/lib/ux/write.d.ts

@@ -1,2 +1,2 @@
-export declare const stdout: (str: string | string[] | undefined, ...args: string[]) => void;
-export declare const stderr: (str: string | string[] | undefined, ...args: string[]) => void;
+export declare const stdout: (str?: string | string[] | undefined, ...args: string[]) => void;
+export declare const stderr: (str?: string | string[] | undefined, ...args: string[]) => void;

package/lib/ux/write.js

@@ -3,8 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.stderr = exports.stdout = void 0;
 const node_util_1 = require("node:util");
 const stdout = (str, ...args) => {
-    if (typeof str === 'string' || !str) {
-        process.stdout.write((0, node_util_1.format)(str, ...args) + '\n');
+    if (!str && args) {
+        process.stdout.write((0, node_util_1.format)(...args) + '\n');
+    }
+    else if (!str) {
+        process.stdout.write('\n');
+    }
+    else if (typeof str === 'string') {
+        process.stdout.write((str && (0, node_util_1.format)(str, ...args)) + '\n');
     }
     else {
         process.stdout.write((0, node_util_1.format)(...str, ...args) + '\n');
@@ -12,8 +18,14 @@ const stdout = (str, ...args) => {
 };
 exports.stdout = stdout;
 const stderr = (str, ...args) => {
-    if (typeof str === 'string' || !str) {
-        process.stderr.write((0, node_util_1.format)(str, ...args) + '\n');
+    if (!str && args) {
+        process.stderr.write((0, node_util_1.format)(...args) + '\n');
+    }
+    else if (!str) {
+        process.stderr.write('\n');
+    }
+    else if (typeof str === 'string') {
+        process.stderr.write((str && (0, node_util_1.format)(str, ...args)) + '\n');
     }
     else {
         process.stderr.write((0, node_util_1.format)(...str, ...args) + '\n');

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "4.0.0-beta.9",
+  "version": "4.0.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {
     "ansi-escapes": "^4.3.2",
-    "ansis": "^3.0.1",
+    "ansis": "^3.1.1",
     "clean-stack": "^3.0.1",
     "cli-spinners": "^2.9.2",
     "cosmiconfig": "^9.0.0",
-    "debug": "^4.3.4",
+    "debug": "^4.3.5",
     "ejs": "^3.1.10",
     "get-package-type": "^0.1.0",
     "globby": "^11.1.0",
@@ -18,7 +18,7 @@
     "is-wsl": "^2.2.0",
     "minimatch": "^9.0.4",
     "string-width": "^4.2.3",
-    "supports-color": "^9.4.0",
+    "supports-color": "^8",
     "widest-line": "^3.1.0",
     "wordwrap": "^1.0.0",
     "wrap-ansi": "^7.0.0"
@@ -40,11 +40,12 @@
     "@types/node": "^18",
     "@types/pnpapi": "^0.0.5",
     "@types/sinon": "^17.0.3",
+    "@types/supports-color": "^8.1.3",
     "@types/wordwrap": "^1.0.3",
     "@types/wrap-ansi": "^3.0.0",
     "benchmark": "^2.1.4",
     "chai": "^4.4.1",
-    "chai-as-promised": "^7.1.1",
+    "chai-as-promised": "^7.1.2",
     "commitlint": "^19",
     "cross-env": "^7.0.3",
     "eslint": "^8.57.0",