/**
 * Global flags for Effect CLI command trees. Global flags are parsed outside a
 * single command's local flags and can apply to a command and its descendants.
 *
 * This module defines two kinds of global flags: action flags, which run an
 * effect and stop normal command execution, and setting flags, which provide a
 * parsed value to the command handler through the Effect context. It also
 * defines the built-in help, version, wizard, shell-completion, and log-level flags
 * used by `Command.run` and `Command.runWith`.
 *
 * @stability unstable
 * @since 4.0.0
 */
import * as Context from "../Context.ts";
import * as Effect from "../Effect.ts";
import type { LogLevel as LogLevelType } from "../LogLevel.ts";
import * as Option from "../Option.ts";
import type * as Command from "./Command.ts";
import * as Completions_ from "./Completions.ts";
import * as Flag from "./Flag.ts";
/**
 * Context passed to action handlers.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface HandlerContext {
    readonly command: Command.Command.Any;
    readonly commandPath: ReadonlyArray<string>;
    readonly version: string;
    readonly builtIns: ReadonlyArray<BuiltIn>;
}
/**
 * Action flag: side effect + exit (--help, --version, --completions).
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface Action<A> {
    readonly _tag: "Action";
    readonly flag: Flag.Flag<A>;
    readonly run: (value: A, context: HandlerContext) => Effect.Effect<void>;
}
/**
 * Setting flag: configure command handler's environment (--log-level, --config).
 *
 * @stability unstable
 * @category services
 * @since 4.0.0
 */
export interface Setting<Id extends string, A> extends Context.Service<Setting.Identifier<Id>, A> {
    readonly _tag: "Setting";
    readonly id: Id;
    readonly flag: Flag.Flag<A>;
}
/**
 * Namespace containing type helpers for global setting flags.
 *
 * @stability unstable
 * @since 4.0.0
 */
export declare namespace Setting {
    /**
     * Type-level service identifier used by `Setting` global flags for the
     * parsed value associated with a setting id.
     *
     * @stability unstable
     * @category models
     * @since 4.0.0
     */
    type Identifier<Id extends string> = `effect/cli/GlobalFlag/${Id}`;
}
/**
 * Global flag discriminated union.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export type GlobalFlag<A> = Action<A> | Setting<any, A>;
/**
 * Creates an Action flag that performs a side effect and exits.
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export declare const Action: <A>(options: {
    readonly flag: Flag.Flag<A>;
    readonly run: (value: A, context: HandlerContext) => Effect.Effect<void>;
}) => Action<A>;
/**
 * Creates a Setting flag that configures the command handler's environment.
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export declare const Setting: <const Id extends string>(id: Id) => <A>(options: {
    readonly flag: Flag.Flag<A>;
}) => Setting<Id, A>;
/**
 * Defines the `--help` / `-h` global flag, which shows help documentation for the
 * active command path.
 *
 * @see {@link BuiltIns} for the default list containing this flag
 * @see {@link Action} for defining custom action global flags
 *
 * @stability unstable
 * @category references
 * @since 4.0.0
 */
export declare const Help: Action<boolean>;
/**
 * Defines the global action flag for showing command version information.
 *
 * **When to use**
 *
 * Use to add a built-in `--version / -v` flag to a command runner.
 *
 * @stability unstable
 * @category references
 * @since 4.0.0
 */
export declare const Version: Action<boolean>;
/**
 * Defines the global action flag for starting interactive wizard mode.
 *
 * **Details**
 *
 * `Command.run` and `Command.runWith` handle this action specially so the
 * generated arguments can be passed back through the command parser.
 *
 * @stability unstable
 * @category references
 * @since 4.0.0
 */
export declare const Wizard: Action<boolean>;
/**
 * Defines the `--completions` global flag, which prints a shell completion script for
 * the given shell.
 *
 * **Details**
 *
 * Accepted values are `bash`, `zsh`, `fish`, `powershell`, `sh`, and `pwsh`;
 * `sh` is normalized to `bash` and `pwsh` to `powershell`.
 *
 * @stability unstable
 * @category references
 * @since 4.0.0
 */
export declare const Completions: Action<Option.Option<Completions_.Shell>>;
/**
 * Defines the global setting flag for command log level.
 *
 * **When to use**
 *
 * Use to add a built-in `--log-level` option that configures the minimum log
 * level for the command.
 *
 * @stability unstable
 * @category references
 * @since 4.0.0
 */
export declare const LogLevel: Setting<"log-level", Option.Option<LogLevelType>>;
/**
 * Built-in global flags in default precedence order.
 *
 * **When to use**
 *
 * Use when extending or inspecting the default global-flag set that
 * `Command.runWith` prepends before user-defined global flags.
 *
 * **Details**
 *
 * The built-ins are `Help`, `Version`, `Wizard`, `Completions`, and `LogLevel`.
 * `Command.runWith` prepends these built-ins when collecting and parsing global
 * flags.
 *
 * **Gotchas**
 *
 * Action flags are processed in active flag order and the first present action
 * exits, so this array controls built-in action precedence.
 *
 * @see {@link Help} for the help action flag
 * @see {@link Version} for the version action flag
 * @see {@link Completions} for the shell-completions action flag
 * @see {@link LogLevel} for the built-in log-level setting flag
 *
 * @stability unstable
 * @category references
 * @since 4.0.0
 */
export declare const BuiltIns: readonly [
    Action<boolean>,
    Action<boolean>,
    Action<boolean>,
    Action<Option.Option<Completions_.Shell>>,
    Setting<"log-level", Option.Option<LogLevelType>>
];
/**
 * Global flag included in the default command-runner configuration.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export type BuiltIn = typeof BuiltIns[number];
//# sourceMappingURL=GlobalFlag.d.ts.map