@oclif/core 3.19.7 → 3.20.1-dev.0

package/lib/cache.d.ts

@@ -2,15 +2,23 @@ import { PJSON, Plugin } from './interfaces';
 type CacheContents = {
     rootPlugin: Plugin;
     exitCodes: PJSON.Plugin['oclif']['exitCodes'];
+    '@oclif/core': OclifCoreInfo;
 };
 type ValueOf<T> = T[keyof T];
+type OclifCoreInfo = {
+    name: string;
+    version: string;
+};
 /**
  * A simple cache for storing values that need to be accessed globally.
  */
 export default class Cache extends Map<keyof CacheContents, ValueOf<CacheContents>> {
     static instance: Cache;
+    constructor();
     static getInstance(): Cache;
+    get(key: '@oclif/core'): OclifCoreInfo;
     get(key: 'rootPlugin'): Plugin | undefined;
     get(key: 'exitCodes'): PJSON.Plugin['oclif']['exitCodes'] | undefined;
+    private getOclifCoreMeta;
 }
 export {};

package/lib/cache.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 /**
  * A simple cache for storing values that need to be accessed globally.
  */
 class Cache extends Map {
     static instance;
+    constructor() {
+        super();
+        this.set('@oclif/core', this.getOclifCoreMeta());
+    }
     static getInstance() {
         if (!Cache.instance) {
             Cache.instance = new Cache();
@@ -14,5 +20,22 @@ class Cache extends Map {
     get(key) {
         return super.get(key);
     }
+    getOclifCoreMeta() {
+        try {
+            // eslint-disable-next-line node/no-extraneous-require
+            return { name: '@oclif/core', version: require('@oclif/core/package.json').version };
+        }
+        catch {
+            try {
+                return {
+                    name: '@oclif/core',
+                    version: JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '..', 'package.json'), 'utf8')),
+                };
+            }
+            catch {
+                return { name: '@oclif/core', version: 'unknown' };
+            }
+        }
+    }
 }
 exports.default = Cache;

package/lib/cli-ux/config.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.config = exports.Config = void 0;
-const fs_1 = require("../util/fs");
+const cache_1 = __importDefault(require("../cache"));
 const simple_1 = __importDefault(require("./action/simple"));
 const spinner_1 = __importDefault(require("./action/spinner"));
 const g = global;
@@ -35,7 +35,8 @@ class Config {
 }
 exports.Config = Config;
 function fetch() {
-    const major = (0, fs_1.requireJson)(__dirname, '..', '..', 'package.json').version.split('.')[0];
+    const core = cache_1.default.getInstance().get('@oclif/core');
+    const major = core?.version.split('.')[0] || 'unknown';
     if (globals[major])
         return globals[major];
     globals[major] = new Config();

package/lib/command.js

@@ -30,16 +30,16 @@ exports.Command = void 0;
 const chalk_1 = __importDefault(require("chalk"));
 const node_url_1 = require("node:url");
 const node_util_1 = require("node:util");
+const cache_1 = __importDefault(require("./cache"));
 const cli_ux_1 = require("./cli-ux");
 const config_1 = require("./config");
 const Errors = __importStar(require("./errors"));
 const util_1 = require("./help/util");
 const Parser = __importStar(require("./parser"));
 const aggregate_flags_1 = require("./util/aggregate-flags");
-const fs_1 = require("./util/fs");
 const ids_1 = require("./util/ids");
 const util_2 = require("./util/util");
-const pjson = (0, fs_1.requireJson)(__dirname, '..', 'package.json');
+const pjson = cache_1.default.getInstance().get('@oclif/core');
 /**
  * swallows stdout epipe errors
  * this occurs when stdout closes such as when piping to head

package/lib/config/config.d.ts

@@ -18,6 +18,7 @@ export declare class Config implements IConfig {
     errlog: string;
     flexibleTaxonomy: boolean;
     home: string;
+    isSingleCommandCLI: boolean;
     name: string;
     npmRegistry?: string;
     nsisCustomization?: string;

package/lib/config/config.js

@@ -44,11 +44,11 @@ const fs_1 = require("../util/fs");
 const os_1 = require("../util/os");
 const util_2 = require("../util/util");
 const plugin_loader_1 = __importDefault(require("./plugin-loader"));
-const ts_node_1 = require("./ts-node");
+const ts_path_1 = require("./ts-path");
 const util_3 = require("./util");
 // eslint-disable-next-line new-cap
 const debug = (0, util_3.Debug)();
-const _pjson = (0, fs_1.requireJson)(__dirname, '..', '..', 'package.json');
+const _pjson = cache_1.default.getInstance().get('@oclif/core');
 const BASE = `${_pjson.name}@${_pjson.version}`;
 function channelFromVersion(version) {
     const m = version.match(/[^-]+(?:-([^.]+))?/);
@@ -98,6 +98,7 @@ class Config {
     errlog;
     flexibleTaxonomy;
     home;
+    isSingleCommandCLI = false;
     name;
     npmRegistry;
     nsisCustomization;
@@ -328,6 +329,10 @@ class Config {
                 ...(s3.templates && s3.templates.vanilla),
             },
         };
+        this.isSingleCommandCLI = Boolean(this.pjson.oclif.default ||
+            (typeof this.pjson.oclif.commands !== 'string' &&
+                this.pjson.oclif.commands?.strategy === 'single' &&
+                this.pjson.oclif.commands?.target));
         await this.loadPluginsAndCommands();
         debug('config done');
         marker?.addDetails({
@@ -482,14 +487,21 @@ class Config {
             };
             const hooks = p.hooks[event] || [];
             for (const hook of hooks) {
-                const marker = performance_1.Performance.mark(performance_1.OCLIF_MARKER_OWNER, `config.runHook#${p.name}(${hook})`);
+                const marker = performance_1.Performance.mark(performance_1.OCLIF_MARKER_OWNER, `config.runHook#${p.name}(${hook.target})`);
                 try {
                     /* eslint-disable no-await-in-loop */
-                    const { filePath, isESM, module } = await (0, module_loader_1.loadWithData)(p, await (0, ts_node_1.tsPath)(p.root, hook, p));
+                    const { filePath, isESM, module } = await (0, module_loader_1.loadWithData)(p, await (0, ts_path_1.tsPath)(p.root, hook.target, p));
                     debug('start', isESM ? '(import)' : '(require)', filePath);
+                    // If no hook is found using the identifier, then we should `search` for the hook but only if the hook identifier is 'default'
+                    // A named identifier (e.g. MY_HOOK) that isn't found indicates that the hook isn't implemented in the plugin.
+                    const hookFn = module[hook.identifier] ?? (hook.identifier === 'default' ? search(module) : undefined);
+                    if (!hookFn) {
+                        debug('No hook found for hook definition:', hook);
+                        continue;
+                    }
                     const result = timeout
-                        ? await withTimeout(timeout, search(module).call(context, { ...opts, config: this, context }))
-                        : await search(module).call(context, { ...opts, config: this, context });
+                        ? await withTimeout(timeout, hookFn.call(context, { ...opts, config: this, context }))
+                        : await hookFn.call(context, { ...opts, config: this, context });
                     final.successes.push({ plugin: p, result });
                     if (p.name === '@oclif/plugin-legacy' && event === 'init') {
                         this.insertLegacyPlugins(result);
@@ -511,7 +523,7 @@ class Config {
                 }
                 marker?.addDetails({
                     event,
-                    hook,
+                    hook: hook.target,
                     plugin: p.name,
                 });
                 marker?.stop();

package/lib/config/index.d.ts

@@ -1,3 +1,3 @@
 export { Config } from './config';
 export { Plugin } from './plugin';
-export { tsPath } from './ts-node';
+export { tsPath } from './ts-path';

package/lib/config/index.js

@@ -5,5 +5,5 @@ var config_1 = require("./config");
 Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return config_1.Config; } });
 var plugin_1 = require("./plugin");
 Object.defineProperty(exports, "Plugin", { enumerable: true, get: function () { return plugin_1.Plugin; } });
-var ts_node_1 = require("./ts-node");
-Object.defineProperty(exports, "tsPath", { enumerable: true, get: function () { return ts_node_1.tsPath; } });
+var ts_path_1 = require("./ts-path");
+Object.defineProperty(exports, "tsPath", { enumerable: true, get: function () { return ts_path_1.tsPath; } });

package/lib/config/plugin.d.ts

@@ -1,6 +1,6 @@
 import { Command } from '../command';
 import { Manifest } from '../interfaces/manifest';
-import { PJSON } from '../interfaces/pjson';
+import { HookOptions, PJSON } from '../interfaces/pjson';
 import { Plugin as IPlugin, PluginOptions } from '../interfaces/plugin';
 import { Topic } from '../interfaces/topic';
 export declare class Plugin implements IPlugin {
@@ -13,7 +13,7 @@ export declare class Plugin implements IPlugin {
     commandsDir: string | undefined;
     hasManifest: boolean;
     hooks: {
-        [k: string]: string[];
+        [key: string]: HookOptions[];
     };
     isRoot: boolean;
     manifest: Manifest;
@@ -29,6 +29,8 @@ export declare class Plugin implements IPlugin {
     protected warned: boolean;
     _base: string;
     protected _debug: (..._: any) => void;
+    private commandCache;
+    private commandDiscoveryOpts;
     private flexibleTaxonomy;
     constructor(options: PluginOptions);
     get topics(): Topic[];
@@ -42,6 +44,9 @@ export declare class Plugin implements IPlugin {
     private _manifest;
     private addErrorScope;
     private getCommandIDs;
+    private getCommandIdsFromPattern;
+    private getCommandIdsFromTarget;
     private getCommandsDir;
+    private loadCommandsFromTarget;
     private warn;
 }

package/lib/config/plugin.js

@@ -7,16 +7,18 @@ exports.Plugin = void 0;
 const globby_1 = __importDefault(require("globby"));
 const node_path_1 = require("node:path");
 const node_util_1 = require("node:util");
+const cache_1 = __importDefault(require("../cache"));
 const errors_1 = require("../errors");
 const module_loader_1 = require("../module-loader");
 const performance_1 = require("../performance");
+const symbols_1 = require("../symbols");
 const cache_command_1 = require("../util/cache-command");
 const find_root_1 = require("../util/find-root");
 const fs_1 = require("../util/fs");
 const util_1 = require("../util/util");
-const ts_node_1 = require("./ts-node");
+const ts_path_1 = require("./ts-path");
 const util_2 = require("./util");
-const _pjson = (0, fs_1.requireJson)(__dirname, '..', '..', 'package.json');
+const _pjson = cache_1.default.getInstance().get('@oclif/core');
 function topicsToArray(input, base) {
     if (!input)
         return [];
@@ -30,13 +32,17 @@ function topicsToArray(input, base) {
     });
 }
 const cachedCommandCanBeUsed = (manifest, id) => Boolean(manifest?.commands[id] && 'isESM' in manifest.commands[id] && 'relativePath' in manifest.commands[id]);
-const search = (cmd) => {
+const searchForCommandClass = (cmd) => {
     if (typeof cmd.run === 'function')
         return cmd;
     if (cmd.default && cmd.default.run)
         return cmd.default;
     return Object.values(cmd).find((cmd) => typeof cmd.run === 'function');
 };
+const ensureCommandClass = (cmd) => {
+    if (cmd && typeof cmd.run === 'function')
+        return cmd;
+};
 const GLOB_PATTERNS = [
     '**/*.+(js|cjs|mjs|ts|tsx|mts|cts)',
     '!**/*.+(d.ts|test.ts|test.js|spec.ts|spec.js|d.mts|d.cts)?(x)',
@@ -47,9 +53,34 @@ function processCommandIds(files) {
         const topics = p.dir.split('/');
         const command = p.name !== 'index' && p.name;
         const id = [...topics, command].filter(Boolean).join(':');
-        return id === '' ? '.' : id;
+        return id === '' ? symbols_1.SINGLE_COMMAND_CLI_SYMBOL : id;
     });
 }
+function determineCommandDiscoveryOptions(commandDiscovery, defaultCmdId) {
+    if (!commandDiscovery)
+        return;
+    if (typeof commandDiscovery === 'string' && defaultCmdId) {
+        return { strategy: 'single', target: commandDiscovery };
+    }
+    if (typeof commandDiscovery === 'string') {
+        return { globPatterns: GLOB_PATTERNS, strategy: 'pattern', target: commandDiscovery };
+    }
+    if (!commandDiscovery.target)
+        throw new errors_1.CLIError('`oclif.commandDiscovery.target` is required.');
+    if (!commandDiscovery.strategy)
+        throw new errors_1.CLIError('`oclif.commandDiscovery.strategy` is required.');
+    if (commandDiscovery.strategy === 'explicit' && !commandDiscovery.identifier) {
+        commandDiscovery.identifier = 'default';
+    }
+    return commandDiscovery;
+}
+function determineHookOptions(hook) {
+    if (typeof hook === 'string')
+        return { identifier: 'default', target: hook };
+    if (!hook.identifier)
+        return { ...hook, identifier: 'default' };
+    return hook;
+}
 class Plugin {
     options;
     alias;
@@ -76,6 +107,8 @@ class Plugin {
     _base = `${_pjson.name}@${_pjson.version}`;
     // eslint-disable-next-line new-cap
     _debug = (0, util_2.Debug)();
+    commandCache;
+    commandDiscoveryOpts;
     flexibleTaxonomy;
     constructor(options) {
         this.options = options;
@@ -89,32 +122,43 @@ class Plugin {
             plugin: this.name,
         });
         const fetch = async () => {
-            const commandsDir = await this.getCommandsDir();
-            if (!commandsDir)
-                return;
-            let module;
-            let isESM;
-            let filePath;
-            try {
-                ;
-                ({ filePath, isESM, module } = cachedCommandCanBeUsed(this.manifest, id)
-                    ? await (0, module_loader_1.loadWithDataFromManifest)(this.manifest.commands[id], this.root)
-                    : await (0, module_loader_1.loadWithData)(this, (0, node_path_1.join)(commandsDir ?? this.pjson.oclif.commands, ...id.split(':'))));
-                this._debug(isESM ? '(import)' : '(require)', filePath);
+            if (this.commandDiscoveryOpts?.strategy === 'pattern') {
+                const commandsDir = await this.getCommandsDir();
+                if (!commandsDir)
+                    return;
+                let module;
+                let isESM;
+                let filePath;
+                try {
+                    ;
+                    ({ filePath, isESM, module } = cachedCommandCanBeUsed(this.manifest, id)
+                        ? await (0, module_loader_1.loadWithDataFromManifest)(this.manifest.commands[id], this.root)
+                        : await (0, module_loader_1.loadWithData)(this, (0, node_path_1.join)(commandsDir ?? this.pjson.oclif.commands, ...id.split(':'))));
+                    this._debug(isESM ? '(import)' : '(require)', filePath);
+                }
+                catch (error) {
+                    if (!opts.must && error.code === 'MODULE_NOT_FOUND')
+                        return;
+                    throw error;
+                }
+                const cmd = searchForCommandClass(module);
+                if (!cmd)
+                    return;
+                cmd.id = id;
+                cmd.plugin = this;
+                cmd.isESM = isESM;
+                cmd.relativePath = (0, node_path_1.relative)(this.root, filePath || '').split(node_path_1.sep);
+                return cmd;
             }
-            catch (error) {
-                if (!opts.must && error.code === 'MODULE_NOT_FOUND')
+            if (this.commandDiscoveryOpts?.strategy === 'single' || this.commandDiscoveryOpts?.strategy === 'explicit') {
+                const commandCache = await this.loadCommandsFromTarget();
+                const cmd = ensureCommandClass(commandCache?.[id]);
+                if (!cmd)
                     return;
-                throw error;
+                cmd.id = id;
+                cmd.plugin = this;
+                return cmd;
             }
-            const cmd = search(module);
-            if (!cmd)
-                return;
-            cmd.id = id;
-            cmd.plugin = this;
-            cmd.isESM = isESM;
-            cmd.relativePath = (0, node_path_1.relative)(this.root, filePath || '').split(node_path_1.sep);
-            return cmd;
         };
         const cmd = await fetch();
         if (!cmd && opts.must)
@@ -153,7 +197,12 @@ class Plugin {
         else {
             this.pjson.oclif = this.pjson['cli-engine'] || {};
         }
-        this.hooks = Object.fromEntries(Object.entries(this.pjson.oclif.hooks ?? {}).map(([k, v]) => [k, (0, util_1.castArray)(v)]));
+        this.hooks = Object.fromEntries(Object.entries(this.pjson.oclif.hooks ?? {}).map(([k, v]) => [
+            k,
+            (0, util_1.castArray)(v).map((v) => determineHookOptions(v)),
+        ]));
+        this.commandDiscoveryOpts = determineCommandDiscoveryOptions(this.pjson.oclif?.commands, this.pjson.oclif?.default);
+        this._debug('command discovery options', this.commandDiscoveryOpts);
         this.manifest = await this._manifest();
         this.commands = Object.entries(this.manifest.commands)
             .map(([id, c]) => ({
@@ -205,7 +254,13 @@ class Plugin {
         const manifest = {
             commands: (await Promise.all(this.commandIDs.map(async (id) => {
                 try {
-                    const cached = await (0, cache_command_1.cacheCommand)(await this.findCommand(id, { must: true }), this, respectNoCacheDefault);
+                    const found = await this.findCommand(id, { must: true });
+                    const cached = await (0, cache_command_1.cacheCommand)(found, this, respectNoCacheDefault);
+                    // Ensure that id is set to the id being processed
+                    // This is necessary because the id is set by findCommand but if there
+                    // are multiple instances of a Command, then the id will be set to the
+                    // last one found.
+                    cached.id = id;
                     if (this.flexibleTaxonomy) {
                         const permutations = (0, util_2.getCommandIdPermutations)(id);
                         const aliasPermutations = cached.aliases.flatMap((a) => (0, util_2.getCommandIdPermutations)(a));
@@ -246,25 +301,70 @@ class Plugin {
         return err;
     }
     async getCommandIDs() {
-        const commandsDir = await this.getCommandsDir();
-        if (!commandsDir)
-            return [];
         const marker = performance_1.Performance.mark(performance_1.OCLIF_MARKER_OWNER, `plugin.getCommandIDs#${this.name}`, { plugin: this.name });
-        this._debug(`loading IDs from ${commandsDir}`);
-        const files = await (0, globby_1.default)(GLOB_PATTERNS, { cwd: commandsDir });
-        const ids = processCommandIds(files);
+        let ids;
+        switch (this.commandDiscoveryOpts?.strategy) {
+            case 'explicit': {
+                ids = (await this.getCommandIdsFromTarget()) ?? [];
+                break;
+            }
+            case 'pattern': {
+                ids = await this.getCommandIdsFromPattern();
+                break;
+            }
+            case 'single': {
+                ids = (await this.getCommandIdsFromTarget()) ?? [];
+                break;
+            }
+            default: {
+                ids = [];
+            }
+        }
         this._debug('found commands', ids);
         marker?.addDetails({ count: ids.length });
         marker?.stop();
         return ids;
     }
+    async getCommandIdsFromPattern() {
+        const commandsDir = await this.getCommandsDir();
+        if (!commandsDir)
+            return [];
+        this._debug(`loading IDs from ${commandsDir}`);
+        const files = await (0, globby_1.default)(this.commandDiscoveryOpts?.globPatterns ?? GLOB_PATTERNS, { cwd: commandsDir });
+        return processCommandIds(files);
+    }
+    async getCommandIdsFromTarget() {
+        const commandsFromExport = await this.loadCommandsFromTarget();
+        if (commandsFromExport) {
+            return Object.entries((await this.loadCommandsFromTarget()) ?? [])
+                .filter(([, cmd]) => ensureCommandClass(cmd))
+                .map(([id]) => id);
+        }
+    }
     async getCommandsDir() {
         if (this.commandsDir)
             return this.commandsDir;
-        this.commandsDir = await (0, ts_node_1.tsPath)(this.root, this.pjson.oclif.commands, this);
+        this.commandsDir = await (0, ts_path_1.tsPath)(this.root, this.commandDiscoveryOpts?.target, this);
         return this.commandsDir;
     }
+    async loadCommandsFromTarget() {
+        if (this.commandCache)
+            return this.commandCache;
+        if (this.commandDiscoveryOpts?.strategy === 'explicit' && this.commandDiscoveryOpts.target) {
+            const filePath = await (0, ts_path_1.tsPath)(this.root, this.commandDiscoveryOpts.target, this);
+            const module = await (0, module_loader_1.load)(this, filePath);
+            this.commandCache = module[this.commandDiscoveryOpts?.identifier ?? 'default'] ?? {};
+            return this.commandCache;
+        }
+        if (this.commandDiscoveryOpts?.strategy === 'single' && this.commandDiscoveryOpts.target) {
+            const filePath = await (0, ts_path_1.tsPath)(this.root, this.commandDiscoveryOpts?.target ?? this.root, this);
+            const module = await (0, module_loader_1.load)(this, filePath);
+            this.commandCache = { [symbols_1.SINGLE_COMMAND_CLI_SYMBOL]: searchForCommandClass(module) };
+            return this.commandCache;
+        }
+    }
     warn(err, scope) {
+        console.trace();
         if (this.warned)
             return;
         if (typeof err === 'string')

package/lib/config/{ts-node.js → ts-path.js}

@@ -13,9 +13,50 @@ const read_tsconfig_1 = require("../util/read-tsconfig");
 const util_1 = require("../util/util");
 const util_2 = require("./util");
 // eslint-disable-next-line new-cap
-const debug = (0, util_2.Debug)('ts-node');
+const debug = (0, util_2.Debug)('ts-path');
 exports.TS_CONFIGS = {};
 const REGISTERED = new Set();
+function determineRuntime() {
+    /**
+     * Examples:
+     * #!/usr/bin/env bun
+     * bun bin/run.js
+     * bun bin/dev.js
+     */
+    if (process.execPath.split(node_path_1.sep).includes('bun'))
+        return 'bun';
+    /**
+     * Examples:
+     * #!/usr/bin/env node
+     * #!/usr/bin/env node --loader ts-node/esm --experimental-specifier-resolution=node --no-warnings
+     * node bin/run.js
+     * node bin/dev.js
+     */
+    if (process.execArgv.length === 0)
+        return 'node';
+    /**
+     * Examples:
+     * #!/usr/bin/env ts-node
+     * #!/usr/bin/env node_modules/.bin/ts-node
+     * ts-node bin/run.js
+     * ts-node bin/dev.js
+     */
+    if (process.execArgv[0] === '--require' && process.execArgv[1].split(node_path_1.sep).includes('ts-node'))
+        return 'ts-node';
+    if (process.execArgv[0].split(node_path_1.sep).includes('ts-node'))
+        return 'ts-node';
+    /**
+     * Examples:
+     * #!/usr/bin/env tsx
+     * #!/usr/bin/env node_modules/.bin/tsx
+     * tsx bin/run.js
+     * tsx bin/dev.js
+     */
+    if (process.execArgv[0] === '--require' && process.execArgv[1].split(node_path_1.sep).includes('tsx'))
+        return 'tsx';
+    return 'node';
+}
+const RUN_TIME = determineRuntime();
 function isErrno(error) {
     return 'code' in error && error.code === 'ENOENT';
 }
@@ -23,22 +64,23 @@ async function loadTSConfig(root) {
     try {
         if (exports.TS_CONFIGS[root])
             return exports.TS_CONFIGS[root];
-        exports.TS_CONFIGS[root] = await (0, read_tsconfig_1.readTSConfig)(root);
+        const tsconfig = await (0, read_tsconfig_1.readTSConfig)(root);
+        if (!tsconfig)
+            return;
+        debug('tsconfig: %O', tsconfig);
+        exports.TS_CONFIGS[root] = tsconfig;
         return exports.TS_CONFIGS[root];
     }
     catch (error) {
         if (isErrno(error))
             return;
-        debug(`Could not parse tsconfig.json. Skipping ts-node registration for ${root}.`);
+        debug(`Could not parse tsconfig.json. Skipping typescript path lookup for ${root}.`);
         (0, errors_1.memoizedWarn)(`Could not parse tsconfig.json for ${root}. Falling back to compiled source.`);
     }
 }
-async function registerTSNode(root) {
-    const tsconfig = await loadTSConfig(root);
-    if (!tsconfig)
-        return;
+async function registerTSNode(root, tsconfig) {
     if (REGISTERED.has(root))
-        return tsconfig;
+        return;
     debug('registering ts-node at', root);
     const tsNodePath = require.resolve('ts-node', { paths: [root, __dirname] });
     debug('ts-node path:', tsNodePath);
@@ -87,11 +129,9 @@ async function registerTSNode(root) {
         skipProject: true,
         transpileOnly: true,
     };
+    debug('ts-node options: %O', conf);
     tsNode.register(conf);
     REGISTERED.add(root);
-    debug('tsconfig: %O', tsconfig);
-    debug('ts-node options: %O', conf);
-    return tsconfig;
 }
 /**
  * Skip ts-node registration for ESM plugins in production.
@@ -121,17 +161,22 @@ function cannotUseTsNode(root, plugin, isProduction) {
     if (plugin?.moduleType !== 'module' || isProduction)
         return false;
     const nodeMajor = Number.parseInt(process.version.replace('v', '').split('.')[0], 10);
-    const tsNodeExecIsUsed = process.execArgv[0] === '--require' && process.execArgv[1].split(node_path_1.sep).includes(`ts-node`);
-    return tsNodeExecIsUsed && nodeMajor >= 20;
+    return RUN_TIME === 'ts-node' && nodeMajor >= 20;
 }
 /**
  * Determine the path to the source file from the compiled ./lib files
  */
 async function determinePath(root, orig) {
-    const tsconfig = await registerTSNode(root);
+    const tsconfig = await loadTSConfig(root);
     if (!tsconfig)
         return orig;
-    debug(`determining path for ${orig}`);
+    debug(`Determining path for ${orig}`);
+    if (RUN_TIME === 'tsx' || RUN_TIME === 'bun') {
+        debug(`Skipping ts-node registration for ${root} because the runtime is: ${RUN_TIME}`);
+    }
+    else {
+        await registerTSNode(root, tsconfig);
+    }
     const { baseUrl, outDir, rootDir, rootDirs } = tsconfig.compilerOptions;
     const rootDirPath = rootDir ?? (rootDirs ?? [])[0] ?? baseUrl;
     if (!rootDirPath) {
@@ -171,24 +216,25 @@ async function tsPath(root, orig, plugin) {
         return orig;
     orig = orig.startsWith(root) ? orig : (0, node_path_1.join)(root, orig);
     // NOTE: The order of these checks matter!
-    if (settings_1.settings.tsnodeEnabled === false) {
-        debug(`Skipping ts-node registration for ${root} because tsNodeEnabled is explicitly set to false`);
+    const enableAutoTranspile = settings_1.settings.enableAutoTranspile ?? settings_1.settings.tsnodeEnabled;
+    if (enableAutoTranspile === false) {
+        debug(`Skipping typescript path lookup for ${root} because enableAutoTranspile is explicitly set to false`);
         return orig;
     }
     const isProduction = (0, util_1.isProd)();
     // Do not skip ts-node registration if the plugin is linked
-    if (settings_1.settings.tsnodeEnabled === undefined && isProduction && plugin?.type !== 'link') {
-        debug(`Skipping ts-node registration for ${root} because NODE_ENV is NOT "test" or "development"`);
+    if (enableAutoTranspile === undefined && isProduction && plugin?.type !== 'link') {
+        debug(`Skipping typescript path lookup for ${root} because NODE_ENV is NOT "test" or "development"`);
         return orig;
     }
     if (cannotTranspileEsm(rootPlugin, plugin, isProduction)) {
-        debug(`Skipping ts-node registration for ${root} because it's an ESM module (NODE_ENV: ${process.env.NODE_ENV}, root plugin module type: ${rootPlugin?.moduleType})`);
+        debug(`Skipping typescript path lookup for ${root} because it's an ESM module (NODE_ENV: ${process.env.NODE_ENV}, root plugin module type: ${rootPlugin?.moduleType})`);
         if (plugin?.type === 'link')
             (0, errors_1.memoizedWarn)(`${plugin?.name} is a linked ESM module and cannot be auto-transpiled. Existing compiled source will be used instead.`);
         return orig;
     }
     if (cannotUseTsNode(root, plugin, isProduction)) {
-        debug(`Skipping ts-node registration for ${root} because ts-node is run in node version ${process.version}"`);
+        debug(`Skipping typescript path lookup for ${root} because ts-node is run in node version ${process.version}"`);
         (0, errors_1.memoizedWarn)(`ts-node executable cannot transpile ESM in Node 20. Existing compiled source will be used instead. See https://github.com/oclif/core/issues/817.`);
         return orig;
     }

package/lib/help/docopts.js

@@ -77,7 +77,7 @@ class DocOpts {
         return new DocOpts(cmd).toString();
     }
     toString() {
-        const opts = this.cmd.id === '.' || this.cmd.id === '' ? [] : ['<%= command.id %>'];
+        const opts = ['<%= command.id %>'];
         if (this.cmd.args) {
             const a = Object.values((0, ensure_arg_object_1.ensureArgObject)(this.cmd.args)).map((arg) => arg.required ? arg.name.toUpperCase() : `[${arg.name.toUpperCase()}]`) || [];
             opts.push(...a);

package/lib/help/index.js

@@ -10,6 +10,7 @@ const theme_1 = require("../cli-ux/theme");
 const write_1 = __importDefault(require("../cli-ux/write"));
 const errors_1 = require("../errors");
 const module_loader_1 = require("../module-loader");
+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");
@@ -189,8 +190,8 @@ class Help extends HelpBase {
             argv = (0, util_2.standardizeIDFromArgv)(argv, this.config);
         const subject = getHelpSubject(argv, this.config);
         if (!subject) {
-            if (this.config.pjson.oclif.default) {
-                const rootCmd = this.config.findCommand(this.config.pjson.oclif.default);
+            if (this.config.isSingleCommandCLI) {
+                const rootCmd = this.config.findCommand(symbols_1.SINGLE_COMMAND_CLI_SYMBOL);
                 if (rootCmd) {
                     await this.showCommandHelp(rootCmd);
                     return;
@@ -201,6 +202,12 @@ class Help extends HelpBase {
         }
         const command = this.config.findCommand(subject);
         if (command) {
+            if (command.id === symbols_1.SINGLE_COMMAND_CLI_SYMBOL) {
+                // If the command is the root command of a single command CLI,
+                // then set the command id to an empty string to prevent the
+                // the SINGLE_COMMAND_CLI_SYMBOL from being displayed in the help output.
+                command.id = '';
+            }
             if (command.hasDynamicHelp && command.pluginType !== 'jit') {
                 const loaded = await command.load();
                 for (const [name, flag] of Object.entries(loaded.flags ?? {})) {

package/lib/interfaces/config.d.ts

@@ -96,6 +96,7 @@ export interface Config {
      * example: /home/myuser
      */
     readonly home: string;
+    readonly isSingleCommandCLI: boolean;
     readonly name: string;
     /**
      * npm registry to use for installing plugins

package/lib/interfaces/pjson.d.ts

@@ -16,6 +16,86 @@ export interface PJSON {
     };
     version: string;
 }
+export type CommandDiscovery = {
+    /**
+     * The strategy to use for loading commands.
+     *
+     * - `pattern` will use glob patterns to find command files in the specified `target`.
+     * - `explicit` will use `import` (or `require` for CJS) to load the commands from the
+     *    specified `target`.
+     * - `single` will use the `target` which should export a command class. This is for CLIs that
+     *    only have a single command.
+     *
+     * In both cases, the `oclif.manifest.json` file will be used to find the commands if it exists.
+     */
+    strategy: 'pattern' | 'explicit' | 'single';
+    /**
+     * If the `strategy` is `pattern`, this is the **directory** to use to find command files.
+     *
+     * If the `strategy` is `explicit`, this is the **file** that exports the commands.
+     *   - This export must be an object with keys that are the command names and values that are the command classes.
+     *   - Unless `identifier` is specified, the default export will be used.
+     *
+     * @example
+     * ```typescript
+     * // in src/commands.ts
+     * import {Command} from '@oclif/core'
+     * import Hello from './commands/hello/index.js'
+     * import HelloWorld from './commands/hello/world.js'
+     *
+     * export default {
+     *   hello: Hello,
+     *   'hello:world': HelloWorld,
+     * } satisfies Record<string, Command.Class>
+     * ```
+     */
+    target: string;
+    /**
+     * The glob patterns to use to find command files when no `oclif.manifest.json` is present.
+     * This is only used when `strategy` is `pattern`.
+     */
+    globPatterns?: string[];
+    /**
+     * The name of the export to used when loading the command object from the `target` file. Only
+     * used when `strategy` is `explicit`. Defaults to `default`.
+     *
+     * @example
+     * ```typescript
+     * // in src/commands.ts
+     * import {Command} from '@oclif/core'
+     * import Hello from './commands/hello/index.js'
+     * import HelloWorld from './commands/hello/world.js'
+     *
+     * export const MY_COMMANDS = {
+     *  hello: Hello,
+     * 'hello:world': HelloWorld,
+     * } satisfies Record<string, Command.Class>
+     * ```
+     *
+     * In the package.json:
+     * ```json
+     * {
+     *  "oclif": {
+     *   "commands": {
+     *     "strategy": "explicit",
+     *     "target": "./dist/index.js",
+     *     "identifier": "MY_COMMANDS"
+     *    }
+     * }
+     * ```
+     */
+    identifier?: string;
+};
+export type HookOptions = {
+    /**
+     * The file path containing hook.
+     */
+    target: string;
+    /**
+     * The name of the export to use when loading the hook function from the `target` file. Defaults to `default`.
+     */
+    identifier: string;
+};
 export declare namespace PJSON {
     interface Plugin extends PJSON {
         name: string;
@@ -25,7 +105,13 @@ export declare namespace PJSON {
             aliases?: {
                 [name: string]: null | string;
             };
-            commands?: 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;
             description?: string;
             devPlugins?: string[];
@@ -42,7 +128,7 @@ export declare namespace PJSON {
             helpClass?: string;
             helpOptions?: HelpOptions;
             hooks?: {
-                [name: string]: string | string[];
+                [name: string]: string | string[] | HookOptions | HookOptions[];
             };
             jitPlugins?: Record<string, string>;
             macos?: {

package/lib/interfaces/plugin.d.ts

@@ -1,5 +1,5 @@
 import { Command } from '../command';
-import { PJSON } from './pjson';
+import { HookOptions, PJSON } from './pjson';
 import { Topic } from './topic';
 export interface PluginOptions {
     children?: Plugin[];
@@ -44,7 +44,7 @@ export interface Plugin {
     }): Promise<Command.Class> | undefined;
     readonly hasManifest: boolean;
     hooks: {
-        [k: string]: string[];
+        [key: string]: HookOptions[];
     };
     /**
      * True if the plugin is the root plugin.

package/lib/main.js

@@ -6,9 +6,10 @@ const cli_ux_1 = require("./cli-ux");
 const config_1 = require("./config");
 const help_1 = require("./help");
 const performance_1 = require("./performance");
+const symbols_1 = require("./symbols");
 const debug = require('debug')('oclif:main');
 const helpAddition = (argv, config) => {
-    if (argv.length === 0 && !config.pjson.oclif.default)
+    if (argv.length === 0 && !config.isSingleCommandCLI)
         return true;
     const mergedHelpFlags = (0, help_1.getHelpFlagAdditions)(config);
     for (const arg of argv) {
@@ -52,7 +53,11 @@ async function run(argv, options) {
         options = (0, node_url_1.fileURLToPath)(options);
     }
     const config = await config_1.Config.load(options ?? require.main?.filename ?? __dirname);
-    let [id, ...argvSlice] = (0, help_1.normalizeArgv)(config, argv);
+    // If this is a single command CLI, then insert the SINGLE_COMMAND_CLI_SYMBOL into the argv array to serve as the command id.
+    if (config.isSingleCommandCLI) {
+        argv = [symbols_1.SINGLE_COMMAND_CLI_SYMBOL, ...argv];
+    }
+    const [id, ...argvSlice] = (0, help_1.normalizeArgv)(config, argv);
     // run init hook
     await config.runHook('init', { argv: argvSlice, id });
     // display version if applicable
@@ -76,17 +81,8 @@ async function run(argv, options) {
             await collectPerf();
             return;
         }
-        if (config.pjson.oclif.default) {
-            id = config.pjson.oclif.default;
-            argvSlice = argv;
-        }
     }
     initMarker?.stop();
-    // If the the default command is '.' (signifying that the CLI is a single command CLI) and '.' is provided
-    // as an argument, we need to add back the '.' to argv since it was stripped out earlier as part of the
-    // command id.
-    if (config.pjson.oclif.default === '.' && id === '.' && argv[0] === '.')
-        argvSlice = ['.', ...argvSlice];
     try {
         return await config.runCommand(id, argvSlice, cmd);
     }

package/lib/module-loader.js

@@ -4,7 +4,7 @@ exports.isPathModule = exports.loadWithDataFromManifest = exports.loadWithData =
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_url_1 = require("node:url");
-const ts_node_1 = require("./config/ts-node");
+const ts_path_1 = require("./config/ts-path");
 const errors_1 = require("./errors");
 const fs_1 = require("./util/fs");
 const getPackageType = require('get-package-type');
@@ -164,7 +164,7 @@ async function resolvePath(config, modulePath) {
     }
     catch {
         filePath =
-            (isPlugin(config) ? await (0, ts_node_1.tsPath)(config.root, modulePath, config) : await (0, ts_node_1.tsPath)(config.root, modulePath)) ??
+            (isPlugin(config) ? await (0, ts_path_1.tsPath)(config.root, modulePath, config) : await (0, ts_path_1.tsPath)(config.root, modulePath)) ??
                 modulePath;
         let fileExists = false;
         let isDirectory = false;

package/lib/settings.d.ts

@@ -9,7 +9,7 @@ export type Settings = {
     /**
      * Show additional debug output without DEBUG. Mainly shows stackstraces.
      *
-     * Useful to set in the ./bin/dev script.
+     * Useful to set in the ./bin/dev.js script.
      * oclif.settings.debug = true;
      */
     debug?: boolean;
@@ -25,15 +25,18 @@ export type Settings = {
      */
     performanceEnabled?: boolean;
     /**
-     * Try to use ts-node to load typescript source files instead of
-     * javascript files.
+     * Try to use ts-node to load typescript source files instead of javascript files.
+     * Defaults to true in development and test environments (e.g. using bin/dev.js or
+     * NODE_ENV=development or NODE_ENV=test).
      *
-     * NOTE: This requires registering ts-node first.
-     * require('ts-node').register();
-     *
-     * Environment Variable:
-     *   NODE_ENV=development
+     * @deprecated use enableAutoTranspile instead.
      */
     tsnodeEnabled?: boolean;
+    /**
+     * Enable automatic transpilation of TypeScript files to JavaScript.
+     *
+     * Defaults to true in development and test environments (e.g. using bin/dev.js or NODE_ENV=development or NODE_ENV=test).
+     */
+    enableAutoTranspile?: boolean;
 };
 export declare const settings: Settings;

package/lib/symbols.d.ts

@@ -0,0 +1 @@
+export declare const SINGLE_COMMAND_CLI_SYMBOL: string;

package/lib/symbols.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SINGLE_COMMAND_CLI_SYMBOL = void 0;
+exports.SINGLE_COMMAND_CLI_SYMBOL = Symbol('SINGLE_COMMAND_CLI').toString();

package/lib/util/fs.d.ts

@@ -1,4 +1,3 @@
-export declare function requireJson<T>(...pathParts: string[]): T;
 /**
  * Parser for Args.directory and Flags.directory. Checks that the provided path
  * exists and is a directory.

package/lib/util/fs.js

@@ -1,13 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.existsSync = exports.safeReadJson = exports.readJsonSync = exports.readJson = exports.fileExists = exports.dirExists = exports.requireJson = void 0;
+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 node_path_1 = require("node:path");
-function requireJson(...pathParts) {
-    return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(...pathParts), 'utf8'));
-}
-exports.requireJson = requireJson;
 /**
  * Parser for Args.directory and Flags.directory. Checks that the provided path
  * exists and is a directory.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "3.19.7",
+  "version": "3.20.1-dev.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {
@@ -114,7 +114,6 @@
     "access": "public"
   },
   "scripts": {
-    "build:dev": "shx rm -rf lib && tsc --sourceMap",
     "build": "shx rm -rf lib && tsc",
     "commitlint": "commitlint",
     "compile": "tsc",
@@ -127,9 +126,8 @@
     "test:circular-deps": "madge lib/ -c",
     "test:debug": "nyc mocha --debug-brk --inspect \"test/**/*.test.ts\"",
     "test:integration": "mocha --forbid-only \"test/**/*.integration.ts\" --parallel --timeout 1200000",
-    "test:esm-cjs": "cross-env DEBUG=integration:* ts-node test/integration/esm-cjs.ts",
+    "test:interoperability": "cross-env DEBUG=integration:* ts-node test/integration/interop.ts",
     "test:perf": "ts-node test/perf/parser.perf.ts",
-    "test:dev": "nyc mocha \"test/**/*.test.ts\"",
     "test": "nyc mocha --forbid-only \"test/**/*.test.ts\""
   },
   "types": "lib/index.d.ts"