import { withBuilderExtensions } from '@black-flag/extensions';
import type { ExecutionContext } from '@black-flag/core/util';
import type { BfeBuilderObject, WithBuilderExtensionsConfig, WithBuilderExtensionsReturnType } from '@black-flag/extensions';
import type { ExtendedDebugger, ExtendedLogger } from 'rejoinder';
import type { Merge } from 'type-fest';
export { withUsageExtensions as withStandardUsage } from '@black-flag/extensions';
/**
 * This {@link ExecutionContext} subtype contains state related to
 * {@link standardCommonCliArguments}, both of which are required for the proper
 * function of {@link withStandardBuilder}.
 *
 * See also: {@link StandardExecutionContextWithListr2}
 */
export type StandardExecutionContext = ExecutionContext & {
  /**
   * The {@link ExtendedLogger} for the CLI (not Black Flag's).
   */
  standardLog: ExtendedLogger;
  /**
   * The {@link ExtendedDebugger} for the CLI (not Black Flag's).
   */
  standardDebug: ExtendedDebugger;
  state: {
    /**
     * If `true`, the program should not output anything at all. It also implies
     * `isQuieted` and `isHushed` are both `true`.
     */
    isSilenced: boolean;
    /**
     * If `true`, the program should be dramatically less verbose. It also
     * implies `isHushed` is `true`.
     */
    isQuieted: boolean;
    /**
     * If `true`, the program should output only the most pertinent information.
     */
    isHushed: boolean;
    /**
     * A `Date` object representing the start time of execution.
     */
    startTime: Date;
  };
  /**
   * The global Listr task manager singleton. This is `undefined` if listr2
   * support has not been explicitly enabled.
   */
  taskManager?: unknown;
};
/**
 * This {@link ExecutionContext} subtype contains state related to
 * {@link standardCommonCliArguments}, both of which are required for the proper
 * function of {@link withStandardBuilder}. Also includes listr2 support.
 *
 * See also: {@link StandardExecutionContext}
 */
export type StandardExecutionContextWithListr2 = Merge<StandardExecutionContext, {
  /**
   * The global Listr task manager singleton.
   */
  taskManager: import('rejoinder-listr2').ListrManager;
}>;
/**
 * These properties will be available in the `argv` object of any command that
 * uses {@link withStandardBuilder} to construct its `builder`.
 *
 * This type is manually synchronized with {@link standardCommonCliArguments},
 * but the keys may differ slightly (e.g. hyphens may be elided in favor of
 * camelCase).
 *
 * Note that this type purposely excludes the `help` and `version` keys, which
 * are considered standard common CLI arguments by this package.
 */
export type StandardCommonCliArguments = {
  hush: boolean;
  quiet: boolean;
  silent: boolean;
};
/**
 * This {@link BfeBuilderObject} instance describes the CLI arguments available
 * in the `argv` object of any command that uses {@link withStandardBuilder} to
 * construct its `builder`.
 *
 * This object is manually synchronized with {@link StandardCommonCliArguments},
 * but the keys may differ slightly (e.g. hyphens may be elided in favor of
 * camelCase).
 *
 * Note that this object purposely excludes the `help` and `version` keys, which
 * are considered standard common CLI arguments by this package.
 */
export declare const standardCommonCliArguments: {
  readonly hush: {
    readonly boolean: true;
    readonly default: false;
    readonly description: "Set output to be somewhat less verbose";
  };
  readonly quiet: {
    readonly boolean: true;
    readonly default: false;
    readonly implies: {
      readonly hush: true;
    };
    readonly description: "Set output to be dramatically less verbose (implies --hush)";
  };
  readonly silent: {
    readonly boolean: true;
    readonly default: false;
    readonly implies: {
      readonly quiet: true;
      readonly hush: true;
    };
    readonly description: "No output will be generated (implies --quiet)";
  };
};
/**
 * This is an array of the keys in {@link standardCommonCliArguments}, each of
 * which have a one-to-one relation with a key of
 * {@link StandardCommonCliArguments}.
 *
 * Note that this array purposely excludes `'help'` and `'version'`, which are
 * considered standard common CLI arguments by this package and are therefore
 * automatically included when appropriate.
 */
export declare const standardCommonCliArgumentsKeys: (keyof typeof standardCommonCliArguments)[];
/**
 * This function enables several options-related units of functionality
 * considered standard across [Xunnamius](https://github.com/Xunnamius)'s CLI
 * projects.
 *
 * This function is a relatively thin wrapper around
 * {@link withBuilderExtensions}. It also disables
 * [`duplicate-arguments-array`](https://github.com/yargs/yargs-parser?tab=readme-ov-file#duplicate-arguments-array)
 * and enables
 * [`strip-dashed`](https://github.com/yargs/yargs-parser?tab=readme-ov-file#strip-dashed)
 * and
 * [`strip-aliased`](https://github.com/yargs/yargs-parser?tab=readme-ov-file#strip-aliased)
 * in yargs-parser.
 *
 * When providing a `customBuilder` function or object, any key in the returned
 * object that is also a key in {@link standardCommonCliArguments} will have its
 * value merged with the value in {@link standardCommonCliArguments} _instead_
 * of fully overwriting it. This means you can pass minimal configuration values
 * for the keys that are also in {@link standardCommonCliArguments} and those
 * values will be shallowly merged.
 */
export declare function withStandardBuilder<CustomCliArguments extends StandardCommonCliArguments, CustomExecutionContext extends StandardExecutionContext>(customBuilder?: Parameters<typeof withBuilderExtensions<CustomCliArguments, CustomExecutionContext>>[0], {
  additionalCommonOptions,
  disableAutomaticGrouping,
  disableAutomaticSorting
}?: Omit<WithBuilderExtensionsConfig<CustomCliArguments>, 'commonOptions' | 'enableAutomaticSorting'> & {
  /**
   * Set to `true` to disable BFE's support for automatic sorting of options.
   *
   * See [the
   * documentation](https://github.com/Xunnamius/black-flag/blob/main/packages/extensions/README.md#automatic-sorting-of-options)
   * for details.
   *
   * @default false
   */
  disableAutomaticSorting?: boolean;
  /**
   * An array of zero or more options that should be grouped under _"Common
   * Options"_ when [automatic grouping of related
   * options](https://github.com/Xunnamius/black-flag-extensions?tab=readme-ov-file#automatic-grouping-of-related-options)
   * is enabled.
   *
   * Target options can be specified in one of two forms:
   *
   * - As a string key of `CustomCliArguments`, or the string `'version'`.
   *   Note that `'help'` is always implicitly included and need not be
   *   specified.
   *
   * - A {@link BfeBuilderObject} instance defining additional "standard
   *   common arguments," which will be shallowly merged into
   *   {@link standardCommonCliArguments}. Its string keys will then be
   *   considered like with the first form.
   *
   * This setting is ignored if `disableAutomaticGrouping === true`.
   *
   * @default []
   */
  additionalCommonOptions?: (NonNullable<WithBuilderExtensionsConfig<CustomCliArguments>['commonOptions']>[number] | BfeBuilderObject<CustomCliArguments, CustomExecutionContext>)[];
}): WithBuilderExtensionsReturnType<CustomCliArguments, CustomExecutionContext>;