@oclif/core 3.20.0 → 3.20.1-dev.1

package/lib/cache.d.ts

@@ -1,7 +1,12 @@
 import { PJSON, Plugin } from './interfaces';
+type OclifCoreInfo = {
+    name: string;
+    version: string;
+};
 type CacheContents = {
     rootPlugin: Plugin;
     exitCodes: PJSON.Plugin['oclif']['exitCodes'];
+    '@oclif/core': OclifCoreInfo;
 };
 type ValueOf<T> = T[keyof T];
 /**
@@ -9,8 +14,11 @@ type ValueOf<T> = T[keyof T];
  */
 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

@@ -48,7 +48,7 @@ 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;
@@ -262,7 +263,7 @@ class Config {
             (settings_1.settings.performanceEnabled === undefined ? this.options.enablePerf : settings_1.settings.performanceEnabled) ?? false;
         const marker = performance_1.Performance.mark(performance_1.OCLIF_MARKER_OWNER, 'config.load');
         this.pluginLoader = new plugin_loader_1.default({ plugins: this.options.plugins, root: this.options.root });
-        this.rootPlugin = await this.pluginLoader.loadRoot();
+        this.rootPlugin = await this.pluginLoader.loadRoot({ pjson: this.options.pjson });
         // Cache the root plugin so that we can reference it later when determining if
         // we should skip ts-node registration for an ESM plugin.
         const cache = cache_1.default.getInstance();
@@ -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_path_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/plugin-loader.d.ts

@@ -1,3 +1,4 @@
+import { PJSON } from '../interfaces';
 import { Plugin as IPlugin } from '../interfaces/plugin';
 type PluginLoaderOptions = {
     plugins?: IPlugin[] | PluginsMap;
@@ -21,7 +22,9 @@ export default class PluginLoader {
         errors: (Error | string)[];
         plugins: PluginsMap;
     }>;
-    loadRoot(): Promise<IPlugin>;
+    loadRoot({ pjson }: {
+        pjson?: PJSON.Plugin;
+    }): Promise<IPlugin>;
     private loadCorePlugins;
     private loadDevPlugins;
     private loadPlugins;

package/lib/config/plugin-loader.js

@@ -51,7 +51,7 @@ class PluginLoader {
         }
         return { errors: this.errors, plugins: this.plugins };
     }
-    async loadRoot() {
+    async loadRoot({ pjson }) {
         let rootPlugin;
         if (this.pluginsProvided) {
             const plugins = [...this.plugins.values()];
@@ -59,7 +59,7 @@ class PluginLoader {
         }
         else {
             const marker = performance_1.Performance.mark(performance_1.OCLIF_MARKER_OWNER, 'plugin.load#root');
-            rootPlugin = new Plugin.Plugin({ isRoot: true, root: this.options.root });
+            rootPlugin = new Plugin.Plugin({ isRoot: true, pjson, root: this.options.root });
             await rootPlugin.load();
             marker?.addDetails({
                 commandCount: rootPlugin.commands.length,

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_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)
@@ -131,19 +175,22 @@ class Plugin {
         // Linked plugins already have a root so there's no need to search for it.
         // However there could be child plugins nested inside the linked plugin, in which
         // case we still need to search for the child plugin's root.
-        const root = this.type === 'link' && !this.parent ? this.options.root : await (0, find_root_1.findRoot)(this.options.name, this.options.root);
+        const root = this.options.pjson && this.options.isRoot
+            ? this.options.root
+            : this.type === 'link' && !this.parent
+                ? this.options.root
+                : await (0, find_root_1.findRoot)(this.options.name, this.options.root);
         if (!root)
             throw new errors_1.CLIError(`could not find package.json with ${(0, node_util_1.inspect)(this.options)}`);
         this.root = root;
         this._debug(`loading ${this.type} plugin from ${root}`);
-        this.pjson = await (0, fs_1.readJson)((0, node_path_1.join)(root, 'package.json'));
+        this.pjson = this.options.pjson ?? (await (0, fs_1.readJson)((0, node_path_1.join)(root, 'package.json')));
         this.flexibleTaxonomy = this.options?.flexibleTaxonomy || this.pjson.oclif?.flexibleTaxonomy || false;
         this.moduleType = this.pjson.type === 'module' ? 'module' : 'commonjs';
         this.name = this.pjson.name;
         this.alias = this.options.name ?? this.pjson.name;
-        const pjsonPath = (0, node_path_1.join)(root, 'package.json');
         if (!this.name)
-            throw new errors_1.CLIError(`no name in ${pjsonPath}`);
+            throw new errors_1.CLIError(`no name in package.json (${root})`);
         // eslint-disable-next-line new-cap
         this._debug = (0, util_2.Debug)(this.name);
         this.version = this.pjson.version;
@@ -153,7 +200,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 +257,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,24 +304,68 @@ 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_path_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) {
         if (this.warned)
             return;

package/lib/execute.d.ts

@@ -42,6 +42,6 @@ import { LoadOptions } from './interfaces';
 export declare function execute(options: {
     args?: string[];
     development?: boolean;
-    dir: string;
+    dir?: string;
     loadOptions?: LoadOptions;
 }): Promise<unknown>;

package/lib/execute.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.execute = void 0;
 const flush_1 = require("./cli-ux/flush");
+const errors_1 = require("./errors");
 const handle_1 = require("./errors/handle");
 const main_1 = require("./main");
 const settings_1 = require("./settings");
@@ -46,6 +47,9 @@ const settings_1 = require("./settings");
  * ```
  */
 async function execute(options) {
+    if (!options.dir && !options.loadOptions) {
+        throw new errors_1.CLIError('dir or loadOptions is required.');
+    }
     if (options.development) {
         // In dev mode -> use ts-node and dev plugins
         process.env.NODE_ENV = 'development';

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[];
@@ -9,6 +9,7 @@ export interface PluginOptions {
     isRoot?: boolean;
     name?: string;
     parent?: Plugin;
+    pjson?: PJSON.Plugin;
     respectNoCacheDefault?: boolean;
     root: string;
     tag?: string;
@@ -20,6 +21,7 @@ export interface Options extends PluginOptions {
     devPlugins?: boolean;
     enablePerf?: boolean;
     jitPlugins?: boolean;
+    pjson?: PJSON.Plugin;
     plugins?: Map<string, Plugin>;
     userPlugins?: boolean;
     version?: string;
@@ -44,7 +46,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/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.20.0",
+  "version": "3.20.1-dev.1",
   "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",
@@ -129,7 +128,6 @@
     "test:integration": "mocha --forbid-only \"test/**/*.integration.ts\" --parallel --timeout 1200000",
     "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"