/**
 * The `GlobalFlag` module defines flags that are available to every command in
 * an Effect CLI application. Global flags are useful for cross-cutting command
 * line behavior such as printing help, showing the application version,
 * generating shell completions, or configuring shared handler settings like the
 * minimum log level.
 *
 * **Common tasks**
 *
 * - Create an action flag with {@link action} for side effects that should run
 *   before the selected command, such as `--help` or `--version`
 * - Create a setting flag with {@link setting} for values that should be made
 *   available to command handlers through the Effect context
 * - Reuse the built-in {@link Help}, {@link Version}, {@link Completions}, and
 *   {@link LogLevel} flags when constructing command runners
 *
 * **Gotchas**
 *
 * - Action flags are intended to perform their effect and exit instead of
 *   continuing into the command handler
 * - Setting flags allocate a distinct context service for each call to
 *   {@link setting}, so reuse exported settings when handlers need to read the
 *   same parsed global value
 *
 * @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 Flag from "./Flag.ts";
/**
 * Context passed to action handlers.
 *
 * @category models
 * @since 4.0.0
 */
export interface HandlerContext {
    readonly command: Command.Command.Any;
    readonly commandPath: ReadonlyArray<string>;
    readonly version: string;
}
/**
 * Action flag: side effect + exit (--help, --version, --completions).
 *
 * @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).
 *
 * @category models
 * @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.
 *
 * @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.
     *
     * @category models
     * @since 4.0.0
     */
    type Identifier<Id extends string> = `effect/unstable/cli/GlobalFlag/${Id}`;
}
/**
 * Global flag discriminated union.
 *
 * @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.
 *
 * @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.
 *
 * @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
 *
 * @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` flag to a command runner.
 *
 * @category references
 * @since 4.0.0
 */
export declare const Version: Action<boolean>;
/**
 * Defines the `--completions` global flag, which prints a shell completion script for
 * the given shell.
 *
 * **Details**
 *
 * Accepted values are `bash`, `zsh`, `fish`, and `sh`; `sh` is normalized to
 * `bash`.
 *
 * @category references
 * @since 4.0.0
 */
export declare const Completions: Action<Option.Option<"bash" | "zsh" | "fish">>;
/**
 * 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.
 *
 * @category references
 * @since 4.0.0
 */
export declare const LogLevel: Setting<"log-level", Option.Option<LogLevelType>>;
/**
 * Built-in global flags in default precedence order.
 *
 * **Details**
 *
 * The built-ins are `Help`, `Version`, `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
 *
 * @category references
 * @since 4.0.0
 */
export declare const BuiltIns: ReadonlyArray<GlobalFlag<any>>;
/**
 * Built-in setting context identifiers.
 *
 * @category models
 * @since 4.0.0
 */
export type BuiltInSettingContext = Setting.Identifier<"log-level">;
//# sourceMappingURL=GlobalFlag.d.ts.map