/**
 * @since 4.0.0
 */
import type * as Config from "../../Config.ts"
import type * as Effect from "../../Effect.ts"
import { dual, type LazyArg } from "../../Function.ts"
import type * as Option from "../../Option.ts"
import type * as Redacted from "../../Redacted.ts"
import type * as Result from "../../Result.ts"
import type * as Schema from "../../Schema.ts"
import type * as CliError from "./CliError.ts"
import * as Param from "./Param.ts"
import type * as Primitive from "./Primitive.ts"

// -------------------------------------------------------------------------------------
// models
// -------------------------------------------------------------------------------------

/**
 * Represents a command-line flag.
 *
 * @since 4.0.0
 * @category models
 */
export interface Flag<A> extends Param.Param<typeof Param.flagKind, A> {}

// -------------------------------------------------------------------------------------
// constructors
// -------------------------------------------------------------------------------------

/**
 * Creates a string flag that accepts text input.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const nameFlag = Flag.string("name")
 * // Usage: --name "John Doe"
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const string = (name: string): Flag<string> => Param.string(Param.flagKind, name)

/**
 * Creates a boolean flag that can be enabled or disabled.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const verboseFlag = Flag.boolean("verbose")
 * // Usage: --verbose (true) or --no-verbose (false)
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const boolean = (name: string): Flag<boolean> => Param.boolean(Param.flagKind, name)

/**
 * Creates an integer flag that accepts whole number input.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const portFlag = Flag.integer("port")
 * // Usage: --port 8080
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const integer = (name: string): Flag<number> => Param.integer(Param.flagKind, name)

/**
 * Creates a float flag that accepts decimal number input.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const rateFlag = Flag.float("rate")
 * // Usage: --rate 3.14
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const float = (name: string): Flag<number> => Param.float(Param.flagKind, name)

/**
 * Creates a date flag that accepts date input in ISO format.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const startDateFlag = Flag.date("start-date")
 * // Usage: --start-date 2023-12-25
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const date = (name: string): Flag<Date> => Param.date(Param.flagKind, name)

/**
 * Constructs option parameters that represent a choice between several inputs.
 * Each tuple maps a string flag value to an associated typed value.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * // simple enum like choice mapping directly to string union
 * const color = Flag.choice("color", ["red", "green", "blue"])
 *
 * // choice with custom value mapping
 * const logLevel = Flag.choiceWithValue("log-level", [
 *   ["debug", "Debug" as const],
 *   ["info", "Info" as const],
 *   ["error", "Error" as const]
 * ])
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const choiceWithValue = <const Choice extends ReadonlyArray<readonly [string, any]>>(
  name: string,
  choices: Choice
): Flag<Choice[number][1]> => Param.choiceWithValue(Param.flagKind, name, choices)

/**
 * Simpler variant of `choiceWithValue` which maps each string to itself.
 *
 * @since 4.0.0
 * @category constructors
 */
export const choice = <const Choices extends ReadonlyArray<string>>(
  name: string,
  choices: Choices
): Flag<Choices[number]> => Param.choice(Param.flagKind, name, choices)

/**
 * Creates a path flag that accepts file system path input with validation options.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * // Basic path flag
 * const pathFlag = Flag.path("config-path")
 *
 * // File-only path that must exist
 * const fileFlag = Flag.path("input-file", {
 *   pathType: "file",
 *   mustExist: true
 * })
 *
 * // Directory path with custom type name
 * const dirFlag = Flag.path("output-dir", {
 *   pathType: "directory",
 *   typeName: "OUTPUT_DIRECTORY"
 * })
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const path = (name: string, options?: {
  readonly pathType?: "file" | "directory" | "either" | undefined
  readonly mustExist?: boolean | undefined
  readonly typeName?: string | undefined
}): Flag<string> => Param.path(Param.flagKind, name, options)

/**
 * Creates a file path flag that accepts file paths with optional existence validation.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * // Basic file flag
 * const inputFlag = Flag.file("input")
 * // Usage: --input ./data.json
 *
 * // File that must exist
 * const configFlag = Flag.file("config", { mustExist: true })
 * // Usage: --config ./config.yaml (file must exist)
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const file = (name: string, options?: {
  readonly mustExist?: boolean | undefined
}): Flag<string> => Param.file(Param.flagKind, name, options)

/**
 * Creates a directory path flag that accepts directory paths with optional existence validation.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * // Basic directory flag
 * const outputFlag = Flag.directory("output")
 * // Usage: --output ./build
 *
 * // Directory that must exist
 * const sourceFlag = Flag.directory("source", { mustExist: true })
 * // Usage: --source ./src (directory must exist)
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const directory = (name: string, options?: {
  readonly mustExist?: boolean | undefined
}): Flag<string> => Param.directory(Param.flagKind, name, options)

/**
 * Creates a redacted flag that securely handles sensitive string input.
 *
 * @example
 * ```ts
 * import { Effect, Redacted } from "effect"
 * import { Flag } from "effect/unstable/cli"
 *
 * const passwordFlag = Flag.redacted("password")
 *
 * const program = Effect.gen(function*() {
 *   const [leftover, password] = yield* passwordFlag.parse({
 *     arguments: [],
 *     flags: { "password": ["abc123"] }
 *   })
 *   const value = Redacted.value(password) // Access the underlying value
 *   console.log("Password length:", value.length)
 * })
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const redacted = (name: string): Flag<Redacted.Redacted<string>> => Param.redacted(Param.flagKind, name)

/**
 * Creates a flag that reads and returns file content as a string.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const config = Flag.fileText("config-file")
 * // --config-file ./app.json will read the file content
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const fileText = (name: string): Flag<string> => Param.fileText(Param.flagKind, name)

/**
 * Creates a flag that reads and parses the content of the specified file.
 *
 * The parser that is utilized will depend on the specified `format`, or the
 * extension of the file passed on the command-line if no `format` is specified.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * // Will use the extension of the file passed on the command line to determine
 * // the parser to use
 * const config = Flag.fileParse("config")
 *
 * // Will use the JSON parser
 * const jsonConfig = Flag.fileParse("json-config", { format: "json" })
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const fileParse = (
  name: string,
  options?: Primitive.FileParseOptions | undefined
): Flag<unknown> => Param.fileParse(Param.flagKind, name, options)

/**
 * Creates a flag that reads and validates file content using the specified
 * schema.
 *
 * @example
 * ```ts
 * import { Schema } from "effect"
 * import { Flag } from "effect/unstable/cli"
 *
 * const ConfigSchema = Schema.Struct({
 *   port: Schema.Number,
 *   host: Schema.String
 * })
 *
 * const config = Flag.fileSchema("config", ConfigSchema, { format: "json" })
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const fileSchema = <A>(
  name: string,
  schema: Schema.Decoder<A>,
  options?: Primitive.FileSchemaOptions | undefined
): Flag<A> => Param.fileSchema(Param.flagKind, name, schema, options)

/**
 * Creates a flag that parses key=value pairs.
 * Useful for options that accept configuration values.
 *
 * Note: Requires at least one key=value pair. Multiple pairs are merged
 * into a single record.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const env = Flag.keyValuePair("env")
 * // --env FOO=bar --env BAZ=qux will parse to { FOO: "bar", BAZ: "qux" }
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const keyValuePair = (name: string): Flag<Record<string, string>> => Param.keyValuePair(Param.flagKind, name)

/**
 * Creates an empty sentinel flag that always fails to parse.
 * This is useful for creating placeholder flags or for combinators.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * // Used as a placeholder in flag combinators
 * const conditionalFlag = true ? Flag.string("value") : Flag.none
 * ```
 *
 * @since 4.0.0
 * @category constructors
 */
export const none: Flag<never> = Param.none(Param.flagKind)

// -------------------------------------------------------------------------------------
// combinators
// -------------------------------------------------------------------------------------

/**
 * Adds an alias to a flag, allowing it to be referenced by multiple names.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * // Flag can be used as both --verbose and -v
 * const verboseFlag = Flag.boolean("verbose").pipe(
 *   Flag.withAlias("v")
 * )
 *
 * // Multiple aliases can be chained
 * const helpFlag = Flag.boolean("help").pipe(
 *   Flag.withAlias("h"),
 *   Flag.withAlias("?")
 * )
 * ```
 *
 * @since 4.0.0
 * @category aliasing
 */
export const withAlias: {
  // -------------------------------------------------------------------------------------
  // combinators
  // -------------------------------------------------------------------------------------

  /**
   * Adds an alias to a flag, allowing it to be referenced by multiple names.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * // Flag can be used as both --verbose and -v
   * const verboseFlag = Flag.boolean("verbose").pipe(
   *   Flag.withAlias("v")
   * )
   *
   * // Multiple aliases can be chained
   * const helpFlag = Flag.boolean("help").pipe(
   *   Flag.withAlias("h"),
   *   Flag.withAlias("?")
   * )
   * ```
   *
   * @since 4.0.0
   * @category aliasing
   */
  <A>(alias: string): (self: Flag<A>) => Flag<A>
  // -------------------------------------------------------------------------------------
  // combinators
  // -------------------------------------------------------------------------------------

  /**
   * Adds an alias to a flag, allowing it to be referenced by multiple names.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * // Flag can be used as both --verbose and -v
   * const verboseFlag = Flag.boolean("verbose").pipe(
   *   Flag.withAlias("v")
   * )
   *
   * // Multiple aliases can be chained
   * const helpFlag = Flag.boolean("help").pipe(
   *   Flag.withAlias("h"),
   *   Flag.withAlias("?")
   * )
   * ```
   *
   * @since 4.0.0
   * @category aliasing
   */
  <A>(self: Flag<A>, alias: string): Flag<A>
} = dual(2, <A>(self: Flag<A>, alias: string): Flag<A> => Param.withAlias(self, alias))

/**
 * Adds a description to a flag for help documentation.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const portFlag = Flag.integer("port").pipe(
 *   Flag.withDescription("The port number to listen on")
 * )
 *
 * const configFlag = Flag.file("config").pipe(
 *   Flag.withDescription("Path to the configuration file")
 * )
 * ```
 *
 * @since 4.0.0
 * @category help documentation
 */
export const withDescription: {
  /**
   * Adds a description to a flag for help documentation.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const portFlag = Flag.integer("port").pipe(
   *   Flag.withDescription("The port number to listen on")
   * )
   *
   * const configFlag = Flag.file("config").pipe(
   *   Flag.withDescription("Path to the configuration file")
   * )
   * ```
   *
   * @since 4.0.0
   * @category help documentation
   */
  <A>(description: string): (self: Flag<A>) => Flag<A>
  /**
   * Adds a description to a flag for help documentation.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const portFlag = Flag.integer("port").pipe(
   *   Flag.withDescription("The port number to listen on")
   * )
   *
   * const configFlag = Flag.file("config").pipe(
   *   Flag.withDescription("Path to the configuration file")
   * )
   * ```
   *
   * @since 4.0.0
   * @category help documentation
   */
  <A>(self: Flag<A>, description: string): Flag<A>
} = dual(2, <A>(self: Flag<A>, description: string) => Param.withDescription(self, description))

// -------------------------------------------------------------------------------------
// metadata
// -------------------------------------------------------------------------------------

/**
 * Sets a custom metavar (placeholder name) for the flag in help documentation.
 *
 * The metavar is displayed in usage text to indicate what value the user should provide.
 * For example, `--output FILE` shows `FILE` as the metavar.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const databaseFlag = Flag.string("database-url").pipe(
 *   Flag.withMetavar("URL"),
 *   Flag.withDescription("Database connection URL")
 * )
 * // In help: --database-url URL
 *
 * const timeoutFlag = Flag.integer("timeout").pipe(
 *   Flag.withMetavar("SECONDS")
 * )
 * // In help: --timeout SECONDS
 * ```
 *
 * @since 4.0.0
 * @category metadata
 */
export const withMetavar: {
  // -------------------------------------------------------------------------------------
  // metadata
  // -------------------------------------------------------------------------------------

  /**
   * Sets a custom metavar (placeholder name) for the flag in help documentation.
   *
   * The metavar is displayed in usage text to indicate what value the user should provide.
   * For example, `--output FILE` shows `FILE` as the metavar.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const databaseFlag = Flag.string("database-url").pipe(
   *   Flag.withMetavar("URL"),
   *   Flag.withDescription("Database connection URL")
   * )
   * // In help: --database-url URL
   *
   * const timeoutFlag = Flag.integer("timeout").pipe(
   *   Flag.withMetavar("SECONDS")
   * )
   * // In help: --timeout SECONDS
   * ```
   *
   * @since 4.0.0
   * @category metadata
   */
  <A>(metavar: string): (self: Flag<A>) => Flag<A>
  // -------------------------------------------------------------------------------------
  // metadata
  // -------------------------------------------------------------------------------------

  /**
   * Sets a custom metavar (placeholder name) for the flag in help documentation.
   *
   * The metavar is displayed in usage text to indicate what value the user should provide.
   * For example, `--output FILE` shows `FILE` as the metavar.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const databaseFlag = Flag.string("database-url").pipe(
   *   Flag.withMetavar("URL"),
   *   Flag.withDescription("Database connection URL")
   * )
   * // In help: --database-url URL
   *
   * const timeoutFlag = Flag.integer("timeout").pipe(
   *   Flag.withMetavar("SECONDS")
   * )
   * // In help: --timeout SECONDS
   * ```
   *
   * @since 4.0.0
   * @category metadata
   */
  <A>(self: Flag<A>, metavar: string): Flag<A>
} = dual(2, <A>(self: Flag<A>, metavar: string) => Param.withMetavar(self, metavar))

/**
 * Makes a flag optional, returning an Option type that can be None if not provided.
 *
 * @example
 * ```ts
 * import { Effect, Option } from "effect"
 * import { Flag } from "effect/unstable/cli"
 *
 * const optionalPort = Flag.optional(Flag.integer("port"))
 *
 * const program = Effect.gen(function*() {
 *   const [leftover, port] = yield* optionalPort.parse({
 *     arguments: [],
 *     flags: { "port": ["4000"] }
 *   })
 *   if (Option.isSome(port)) {
 *     console.log("Port specified:", port.value)
 *   } else {
 *     console.log("No port specified, using default")
 *   }
 * })
 * ```
 *
 * @since 4.0.0
 * @category optionality
 */
export const optional = <A>(param: Flag<A>): Flag<Option.Option<A>> => Param.optional(param)

/**
 * Provides a default value for a flag when it's not specified.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const portFlag = Flag.integer("port").pipe(
 *   Flag.withDefault(8080)
 * )
 * // If --port is not provided, defaults to 8080
 *
 * const hostFlag = Flag.string("host").pipe(
 *   Flag.withDefault("localhost")
 * )
 * // If --host is not provided, defaults to "localhost"
 * ```
 *
 * @since 4.0.0
 * @category optionality
 */
export const withDefault: {
  /**
   * Provides a default value for a flag when it's not specified.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const portFlag = Flag.integer("port").pipe(
   *   Flag.withDefault(8080)
   * )
   * // If --port is not provided, defaults to 8080
   *
   * const hostFlag = Flag.string("host").pipe(
   *   Flag.withDefault("localhost")
   * )
   * // If --host is not provided, defaults to "localhost"
   * ```
   *
   * @since 4.0.0
   * @category optionality
   */
  <const B>(defaultValue: B | Effect.Effect<B, CliError.CliError, Param.Environment>): <A>(self: Flag<A>) => Flag<A | B>
  /**
   * Provides a default value for a flag when it's not specified.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const portFlag = Flag.integer("port").pipe(
   *   Flag.withDefault(8080)
   * )
   * // If --port is not provided, defaults to 8080
   *
   * const hostFlag = Flag.string("host").pipe(
   *   Flag.withDefault("localhost")
   * )
   * // If --host is not provided, defaults to "localhost"
   * ```
   *
   * @since 4.0.0
   * @category optionality
   */
  <A, const B>(
   self: Flag<A>,
   defaultValue: B | Effect.Effect<B, CliError.CliError, Param.Environment>
  ): Flag<A | B>
} = Param.withDefault

/**
 * Adds a fallback config that is loaded when a required flag is missing.
 *
 * @example
 * ```ts
 * import { Config } from "effect"
 * import { Flag } from "effect/unstable/cli"
 *
 * const verbose = Flag.boolean("verbose").pipe(
 *   Flag.withFallbackConfig(Config.boolean("VERBOSE"))
 * )
 * ```
 *
 * @since 4.0.0
 * @category combinators
 */
export const withFallbackConfig: {
  /**
   * Adds a fallback config that is loaded when a required flag is missing.
   *
   * @example
   * ```ts
   * import { Config } from "effect"
   * import { Flag } from "effect/unstable/cli"
   *
   * const verbose = Flag.boolean("verbose").pipe(
   *   Flag.withFallbackConfig(Config.boolean("VERBOSE"))
   * )
   * ```
   *
   * @since 4.0.0
   * @category combinators
   */
  <B>(config: Config.Config<B>): <A>(self: Flag<A>) => Flag<A | B>
  /**
   * Adds a fallback config that is loaded when a required flag is missing.
   *
   * @example
   * ```ts
   * import { Config } from "effect"
   * import { Flag } from "effect/unstable/cli"
   *
   * const verbose = Flag.boolean("verbose").pipe(
   *   Flag.withFallbackConfig(Config.boolean("VERBOSE"))
   * )
   * ```
   *
   * @since 4.0.0
   * @category combinators
   */
  <A, B>(self: Flag<A>, config: Config.Config<B>): Flag<A | B>
} = dual(2, <A, B>(self: Flag<A>, config: Config.Config<B>) => Param.withFallbackConfig(self, config))

/**
 * Adds a fallback prompt that is shown when a required flag is missing.
 *
 * @example
 * ```ts
 * import { Flag, Prompt } from "effect/unstable/cli"
 *
 * const name = Flag.string("name").pipe(
 *   Flag.withFallbackPrompt(Prompt.text({ message: "Name" }))
 * )
 * ```
 *
 * @since 4.0.0
 * @category combinators
 */
export const withFallbackPrompt: {
  /**
   * Adds a fallback prompt that is shown when a required flag is missing.
   *
   * @example
   * ```ts
   * import { Flag, Prompt } from "effect/unstable/cli"
   *
   * const name = Flag.string("name").pipe(
   *   Flag.withFallbackPrompt(Prompt.text({ message: "Name" }))
   * )
   * ```
   *
   * @since 4.0.0
   * @category combinators
   */
  <B>(prompt: Param.FallbackPrompt<B>): <A>(self: Flag<A>) => Flag<A | B>
  /**
   * Adds a fallback prompt that is shown when a required flag is missing.
   *
   * @example
   * ```ts
   * import { Flag, Prompt } from "effect/unstable/cli"
   *
   * const name = Flag.string("name").pipe(
   *   Flag.withFallbackPrompt(Prompt.text({ message: "Name" }))
   * )
   * ```
   *
   * @since 4.0.0
   * @category combinators
   */
  <A, B>(self: Flag<A>, prompt: Param.FallbackPrompt<B>): Flag<A | B>
} = dual(2, <A, B>(self: Flag<A>, prompt: Param.FallbackPrompt<B>) => Param.withFallbackPrompt(self, prompt))

/**
 * Transforms the parsed value of a flag using a mapping function.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * // Convert string to uppercase
 * const nameFlag = Flag.string("name").pipe(
 *   Flag.map((name) => name.toUpperCase())
 * )
 *
 * // Convert port to URL
 * const urlFlag = Flag.integer("port").pipe(
 *   Flag.map((port) => `http://localhost:${port}`)
 * )
 * ```
 *
 * @since 4.0.0
 * @category mapping
 */
export const map: {
  /**
   * Transforms the parsed value of a flag using a mapping function.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * // Convert string to uppercase
   * const nameFlag = Flag.string("name").pipe(
   *   Flag.map((name) => name.toUpperCase())
   * )
   *
   * // Convert port to URL
   * const urlFlag = Flag.integer("port").pipe(
   *   Flag.map((port) => `http://localhost:${port}`)
   * )
   * ```
   *
   * @since 4.0.0
   * @category mapping
   */
  <A, B>(f: (a: A) => B): (self: Flag<A>) => Flag<B>
  /**
   * Transforms the parsed value of a flag using a mapping function.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * // Convert string to uppercase
   * const nameFlag = Flag.string("name").pipe(
   *   Flag.map((name) => name.toUpperCase())
   * )
   *
   * // Convert port to URL
   * const urlFlag = Flag.integer("port").pipe(
   *   Flag.map((port) => `http://localhost:${port}`)
   * )
   * ```
   *
   * @since 4.0.0
   * @category mapping
   */
  <A, B>(self: Flag<A>, f: (a: A) => B): Flag<B>
} = dual(2, <A, B>(self: Flag<A>, f: (a: A) => B) => Param.map(self, f))

/**
 * Transforms the parsed value using an Effect that can perform IO operations.
 *
 * @example
 * ```ts
 * import { Effect, FileSystem } from "effect"
 * import { Flag } from "effect/unstable/cli"
 *
 * // Read file size from path flag
 * const fileSizeFlag = Flag.file("input").pipe(
 *   Flag.mapEffect(Effect.fnUntraced(function*(path) {
 *     const fs = yield* FileSystem.FileSystem
 *     const stats = yield* Effect.orDie(fs.stat(path))
 *     return stats.size
 *   }))
 * )
 * ```
 *
 * @since 4.0.0
 * @category mapping
 */
export const mapEffect: {
  /**
   * Transforms the parsed value using an Effect that can perform IO operations.
   *
   * @example
   * ```ts
   * import { Effect, FileSystem } from "effect"
   * import { Flag } from "effect/unstable/cli"
   *
   * // Read file size from path flag
   * const fileSizeFlag = Flag.file("input").pipe(
   *   Flag.mapEffect(Effect.fnUntraced(function*(path) {
   *     const fs = yield* FileSystem.FileSystem
   *     const stats = yield* Effect.orDie(fs.stat(path))
   *     return stats.size
   *   }))
   * )
   * ```
   *
   * @since 4.0.0
   * @category mapping
   */
  <A, B>(f: (a: A) => Effect.Effect<B, CliError.CliError, Param.Environment>): (self: Flag<A>) => Flag<B>
  /**
   * Transforms the parsed value using an Effect that can perform IO operations.
   *
   * @example
   * ```ts
   * import { Effect, FileSystem } from "effect"
   * import { Flag } from "effect/unstable/cli"
   *
   * // Read file size from path flag
   * const fileSizeFlag = Flag.file("input").pipe(
   *   Flag.mapEffect(Effect.fnUntraced(function*(path) {
   *     const fs = yield* FileSystem.FileSystem
   *     const stats = yield* Effect.orDie(fs.stat(path))
   *     return stats.size
   *   }))
   * )
   * ```
   *
   * @since 4.0.0
   * @category mapping
   */
  <A, B>(
   self: Flag<A>,
   f: (a: A) => Effect.Effect<B, CliError.CliError, Param.Environment>
  ): Flag<B>
} = dual(2, <A, B>(
  self: Flag<A>,
  f: (a: A) => Effect.Effect<B, CliError.CliError, Param.Environment>
) => Param.mapEffect(self, f))

/**
 * Transforms the parsed value using a function that might throw, with error handling.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * // Parse JSON string with error handling
 * const jsonFlag = Flag.string("config").pipe(
 *   Flag.mapTryCatch(
 *     (json) => JSON.parse(json),
 *     (error) => `Invalid JSON: ${error}`
 *   )
 * )
 *
 * // Parse URL with error handling
 * const urlFlag = Flag.string("url").pipe(
 *   Flag.mapTryCatch(
 *     (url) => new URL(url),
 *     (error) => `Invalid URL: ${error}`
 *   )
 * )
 * ```
 *
 * @since 4.0.0
 * @category mapping
 */
export const mapTryCatch: {
  /**
   * Transforms the parsed value using a function that might throw, with error handling.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * // Parse JSON string with error handling
   * const jsonFlag = Flag.string("config").pipe(
   *   Flag.mapTryCatch(
   *     (json) => JSON.parse(json),
   *     (error) => `Invalid JSON: ${error}`
   *   )
   * )
   *
   * // Parse URL with error handling
   * const urlFlag = Flag.string("url").pipe(
   *   Flag.mapTryCatch(
   *     (url) => new URL(url),
   *     (error) => `Invalid URL: ${error}`
   *   )
   * )
   * ```
   *
   * @since 4.0.0
   * @category mapping
   */
  <A, B>(f: (a: A) => B, onError: (error: unknown) => string): (self: Flag<A>) => Flag<B>
  /**
   * Transforms the parsed value using a function that might throw, with error handling.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * // Parse JSON string with error handling
   * const jsonFlag = Flag.string("config").pipe(
   *   Flag.mapTryCatch(
   *     (json) => JSON.parse(json),
   *     (error) => `Invalid JSON: ${error}`
   *   )
   * )
   *
   * // Parse URL with error handling
   * const urlFlag = Flag.string("url").pipe(
   *   Flag.mapTryCatch(
   *     (url) => new URL(url),
   *     (error) => `Invalid URL: ${error}`
   *   )
   * )
   * ```
   *
   * @since 4.0.0
   * @category mapping
   */
  <A, B>(self: Flag<A>, f: (a: A) => B, onError: (error: unknown) => string): Flag<B>
} = dual(3, <A, B>(
  self: Flag<A>,
  f: (a: A) => B,
  onError: (error: unknown) => string
) => Param.mapTryCatch(self, f, onError))

/**
 * Requires a flag to be specified at least a minimum number of times.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const sourceFlag = Flag.atLeast(Flag.file("source"), 2)
 * // Requires at least 2 source files
 * // Usage: --source file1.ts --source file2.ts
 *
 * const tagFlag = Flag.string("tag").pipe(
 *   Flag.atLeast(1)
 * )
 * // Requires at least 1 tag
 * ```
 *
 * @since 4.0.0
 * @category repetition
 */
export const atLeast: {
  /**
   * Requires a flag to be specified at least a minimum number of times.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const sourceFlag = Flag.atLeast(Flag.file("source"), 2)
   * // Requires at least 2 source files
   * // Usage: --source file1.ts --source file2.ts
   *
   * const tagFlag = Flag.string("tag").pipe(
   *   Flag.atLeast(1)
   * )
   * // Requires at least 1 tag
   * ```
   *
   * @since 4.0.0
   * @category repetition
   */
  <A>(min: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
  /**
   * Requires a flag to be specified at least a minimum number of times.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const sourceFlag = Flag.atLeast(Flag.file("source"), 2)
   * // Requires at least 2 source files
   * // Usage: --source file1.ts --source file2.ts
   *
   * const tagFlag = Flag.string("tag").pipe(
   *   Flag.atLeast(1)
   * )
   * // Requires at least 1 tag
   * ```
   *
   * @since 4.0.0
   * @category repetition
   */
  <A>(self: Flag<A>, min: number): Flag<ReadonlyArray<A>>
} = dual(2, <A>(self: Flag<A>, min: number) => Param.atLeast(self, min))

/**
 * Limits a flag to be specified at most a maximum number of times.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const warningFlag = Flag.atMost(Flag.string("warning"), 3)
 * // Allows up to 3 warning flags
 * // Usage: --warning w1 --warning w2 --warning w3
 *
 * const debugFlag = Flag.string("debug").pipe(
 *   Flag.atMost(1)
 * )
 * // Allows at most 1 debug flag
 * ```
 *
 * @since 4.0.0
 * @category repetition
 */
export const atMost: {
  /**
   * Limits a flag to be specified at most a maximum number of times.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const warningFlag = Flag.atMost(Flag.string("warning"), 3)
   * // Allows up to 3 warning flags
   * // Usage: --warning w1 --warning w2 --warning w3
   *
   * const debugFlag = Flag.string("debug").pipe(
   *   Flag.atMost(1)
   * )
   * // Allows at most 1 debug flag
   * ```
   *
   * @since 4.0.0
   * @category repetition
   */
  <A>(max: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
  /**
   * Limits a flag to be specified at most a maximum number of times.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const warningFlag = Flag.atMost(Flag.string("warning"), 3)
   * // Allows up to 3 warning flags
   * // Usage: --warning w1 --warning w2 --warning w3
   *
   * const debugFlag = Flag.string("debug").pipe(
   *   Flag.atMost(1)
   * )
   * // Allows at most 1 debug flag
   * ```
   *
   * @since 4.0.0
   * @category repetition
   */
  <A>(self: Flag<A>, max: number): Flag<ReadonlyArray<A>>
} = dual(2, <A>(self: Flag<A>, max: number) => Param.atMost(self, max))

/**
 * Constrains a flag to be specified between a minimum and maximum number of times.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * const hostFlag = Flag.between(Flag.string("host"), 1, 3)
 * // Requires 1-3 host flags
 * // Usage: --host host1 --host host2
 *
 * const excludeFlag = Flag.string("exclude").pipe(
 *   Flag.between(0, 5)
 * )
 * // Allows 0-5 exclude patterns
 * ```
 *
 * @since 4.0.0
 * @category repetition
 */
export const between: {
  /**
   * Constrains a flag to be specified between a minimum and maximum number of times.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const hostFlag = Flag.between(Flag.string("host"), 1, 3)
   * // Requires 1-3 host flags
   * // Usage: --host host1 --host host2
   *
   * const excludeFlag = Flag.string("exclude").pipe(
   *   Flag.between(0, 5)
   * )
   * // Allows 0-5 exclude patterns
   * ```
   *
   * @since 4.0.0
   * @category repetition
   */
  <A>(min: number, max: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
  /**
   * Constrains a flag to be specified between a minimum and maximum number of times.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * const hostFlag = Flag.between(Flag.string("host"), 1, 3)
   * // Requires 1-3 host flags
   * // Usage: --host host1 --host host2
   *
   * const excludeFlag = Flag.string("exclude").pipe(
   *   Flag.between(0, 5)
   * )
   * // Allows 0-5 exclude patterns
   * ```
   *
   * @since 4.0.0
   * @category repetition
   */
  <A>(self: Flag<A>, min: number, max: number): Flag<ReadonlyArray<A>>
} = dual(3, <A>(self: Flag<A>, min: number, max: number) => Param.between(self, min, max))

/**
 * Transforms and filters a flag value, failing with a custom error if the transformation returns None.
 *
 * @example
 * ```ts
 * import { Option } from "effect"
 * import { Flag } from "effect/unstable/cli"
 *
 * // Parse positive integers only
 * const positiveInt = Flag.integer("count").pipe(
 *   Flag.filterMap(
 *     (n) => n > 0 ? Option.some(n) : Option.none(),
 *     (n) => `Expected positive integer, got ${n}`
 *   )
 * )
 *
 * // Parse valid email addresses
 * const emailFlag = Flag.string("email").pipe(
 *   Flag.filterMap(
 *     (email) => email.includes("@") ? Option.some(email) : Option.none(),
 *     (email) => `Invalid email address: ${email}`
 *   )
 * )
 * ```
 *
 * @since 4.0.0
 * @category filtering
 */
export const filterMap: {
  /**
   * Transforms and filters a flag value, failing with a custom error if the transformation returns None.
   *
   * @example
   * ```ts
   * import { Option } from "effect"
   * import { Flag } from "effect/unstable/cli"
   *
   * // Parse positive integers only
   * const positiveInt = Flag.integer("count").pipe(
   *   Flag.filterMap(
   *     (n) => n > 0 ? Option.some(n) : Option.none(),
   *     (n) => `Expected positive integer, got ${n}`
   *   )
   * )
   *
   * // Parse valid email addresses
   * const emailFlag = Flag.string("email").pipe(
   *   Flag.filterMap(
   *     (email) => email.includes("@") ? Option.some(email) : Option.none(),
   *     (email) => `Invalid email address: ${email}`
   *   )
   * )
   * ```
   *
   * @since 4.0.0
   * @category filtering
   */
  <A, B>(f: (a: A) => Option.Option<B>, onNone: (a: A) => string): (self: Flag<A>) => Flag<B>
  /**
   * Transforms and filters a flag value, failing with a custom error if the transformation returns None.
   *
   * @example
   * ```ts
   * import { Option } from "effect"
   * import { Flag } from "effect/unstable/cli"
   *
   * // Parse positive integers only
   * const positiveInt = Flag.integer("count").pipe(
   *   Flag.filterMap(
   *     (n) => n > 0 ? Option.some(n) : Option.none(),
   *     (n) => `Expected positive integer, got ${n}`
   *   )
   * )
   *
   * // Parse valid email addresses
   * const emailFlag = Flag.string("email").pipe(
   *   Flag.filterMap(
   *     (email) => email.includes("@") ? Option.some(email) : Option.none(),
   *     (email) => `Invalid email address: ${email}`
   *   )
   * )
   * ```
   *
   * @since 4.0.0
   * @category filtering
   */
  <A, B>(self: Flag<A>, f: (a: A) => Option.Option<B>, onNone: (a: A) => string): Flag<B>
} = dual(3, <A, B>(
  self: Flag<A>,
  f: (a: A) => Option.Option<B>,
  onNone: (a: A) => string
) => Param.filterMap(self, f, onNone))

/**
 * Filters a flag value based on a predicate, failing with a custom error if the predicate returns false.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * // Ensure port is in valid range
 * const portFlag = Flag.integer("port").pipe(
 *   Flag.filter(
 *     (port) => port >= 1 && port <= 65535,
 *     (port) => `Port ${port} is out of range (1-65535)`
 *   )
 * )
 *
 * // Ensure non-empty string
 * const nameFlag = Flag.string("name").pipe(
 *   Flag.filter(
 *     (name) => name.trim().length > 0,
 *     () => "Name cannot be empty"
 *   )
 * )
 * ```
 *
 * @since 4.0.0
 * @category filtering
 */
export const filter: {
  /**
   * Filters a flag value based on a predicate, failing with a custom error if the predicate returns false.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * // Ensure port is in valid range
   * const portFlag = Flag.integer("port").pipe(
   *   Flag.filter(
   *     (port) => port >= 1 && port <= 65535,
   *     (port) => `Port ${port} is out of range (1-65535)`
   *   )
   * )
   *
   * // Ensure non-empty string
   * const nameFlag = Flag.string("name").pipe(
   *   Flag.filter(
   *     (name) => name.trim().length > 0,
   *     () => "Name cannot be empty"
   *   )
   * )
   * ```
   *
   * @since 4.0.0
   * @category filtering
   */
  <A>(predicate: (a: A) => boolean, onFalse: (a: A) => string): (self: Flag<A>) => Flag<A>
  /**
   * Filters a flag value based on a predicate, failing with a custom error if the predicate returns false.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * // Ensure port is in valid range
   * const portFlag = Flag.integer("port").pipe(
   *   Flag.filter(
   *     (port) => port >= 1 && port <= 65535,
   *     (port) => `Port ${port} is out of range (1-65535)`
   *   )
   * )
   *
   * // Ensure non-empty string
   * const nameFlag = Flag.string("name").pipe(
   *   Flag.filter(
   *     (name) => name.trim().length > 0,
   *     () => "Name cannot be empty"
   *   )
   * )
   * ```
   *
   * @since 4.0.0
   * @category filtering
   */
  <A>(self: Flag<A>, predicate: (a: A) => boolean, onFalse: (a: A) => string): Flag<A>
} = dual(3, <A>(
  self: Flag<A>,
  predicate: (a: A) => boolean,
  onFalse: (a: A) => string
) => Param.filter(self, predicate, onFalse))

/**
 * Provides an alternative flag if the first one fails to parse.
 *
 * @example
 * ```ts
 * import { Flag } from "effect/unstable/cli"
 *
 * // Try parsing as integer, fallback to string
 * const valueFlag = Flag.orElse(
 *   Flag.integer("value"),
 *   () => Flag.string("value")
 * )
 *
 * // Multiple input sources with fallback
 * const configFlag = Flag.orElse(
 *   Flag.file("config"),
 *   () => Flag.string("config-url")
 * )
 * ```
 *
 * @since 4.0.0
 * @category alternatives
 */
export const orElse: {
  /**
   * Provides an alternative flag if the first one fails to parse.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * // Try parsing as integer, fallback to string
   * const valueFlag = Flag.orElse(
   *   Flag.integer("value"),
   *   () => Flag.string("value")
   * )
   *
   * // Multiple input sources with fallback
   * const configFlag = Flag.orElse(
   *   Flag.file("config"),
   *   () => Flag.string("config-url")
   * )
   * ```
   *
   * @since 4.0.0
   * @category alternatives
   */
  <B>(that: LazyArg<Flag<B>>): <A>(self: Flag<A>) => Flag<A | B>
  /**
   * Provides an alternative flag if the first one fails to parse.
   *
   * @example
   * ```ts
   * import { Flag } from "effect/unstable/cli"
   *
   * // Try parsing as integer, fallback to string
   * const valueFlag = Flag.orElse(
   *   Flag.integer("value"),
   *   () => Flag.string("value")
   * )
   *
   * // Multiple input sources with fallback
   * const configFlag = Flag.orElse(
   *   Flag.file("config"),
   *   () => Flag.string("config-url")
   * )
   * ```
   *
   * @since 4.0.0
   * @category alternatives
   */
  <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>): Flag<A | B>
} = dual(2, <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>) => Param.orElse(self, that))

/**
 * Tries to parse with the first flag, then the second, returning a Result that indicates which succeeded.
 *
 * @example
 * ```ts
 * import { Effect, Result } from "effect"
 * import { Flag } from "effect/unstable/cli"
 *
 * // Try file path, fallback to URL
 * const sourceFlag = Flag.orElseResult(
 *   Flag.file("source"),
 *   () => Flag.string("source-url")
 * )
 *
 * const program = Effect.gen(function*() {
 *   const [leftover, source] = yield* sourceFlag.parse({
 *     arguments: [],
 *     flags: { "source-url": ["https://google.com"] }
 *   })
 *   if (Result.isSuccess(source)) {
 *     console.log("Using file:", source.success)
 *   } else {
 *     console.log("Using URL:", source.failure)
 *   }
 * })
 * ```
 *
 * @since 4.0.0
 * @category alternatives
 */
export const orElseResult: {
  /**
   * Tries to parse with the first flag, then the second, returning a Result that indicates which succeeded.
   *
   * @example
   * ```ts
   * import { Effect, Result } from "effect"
   * import { Flag } from "effect/unstable/cli"
   *
   * // Try file path, fallback to URL
   * const sourceFlag = Flag.orElseResult(
   *   Flag.file("source"),
   *   () => Flag.string("source-url")
   * )
   *
   * const program = Effect.gen(function*() {
   *   const [leftover, source] = yield* sourceFlag.parse({
   *     arguments: [],
   *     flags: { "source-url": ["https://google.com"] }
   *   })
   *   if (Result.isSuccess(source)) {
   *     console.log("Using file:", source.success)
   *   } else {
   *     console.log("Using URL:", source.failure)
   *   }
   * })
   * ```
   *
   * @since 4.0.0
   * @category alternatives
   */
  <B>(that: LazyArg<Flag<B>>): <A>(self: Flag<A>) => Flag<Result.Result<A, B>>
  /**
   * Tries to parse with the first flag, then the second, returning a Result that indicates which succeeded.
   *
   * @example
   * ```ts
   * import { Effect, Result } from "effect"
   * import { Flag } from "effect/unstable/cli"
   *
   * // Try file path, fallback to URL
   * const sourceFlag = Flag.orElseResult(
   *   Flag.file("source"),
   *   () => Flag.string("source-url")
   * )
   *
   * const program = Effect.gen(function*() {
   *   const [leftover, source] = yield* sourceFlag.parse({
   *     arguments: [],
   *     flags: { "source-url": ["https://google.com"] }
   *   })
   *   if (Result.isSuccess(source)) {
   *     console.log("Using file:", source.success)
   *   } else {
   *     console.log("Using URL:", source.failure)
   *   }
   * })
   * ```
   *
   * @since 4.0.0
   * @category alternatives
   */
  <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>): Flag<Result.Result<A, B>>
} = dual(2, <A, B>(self: Flag<A>, that: LazyArg<Flag<B>>) => Param.orElseResult(self, that))

/**
 * Validates and transforms a flag value using a Schema codec.
 *
 * @example
 * ```ts
 * import { Schema } from "effect"
 * import { Flag } from "effect/unstable/cli"
 *
 * const isEmail = Schema.isIncludes("@", {
 *   message: "Must be a valid email address"
 * })
 *
 * // Parse and validate email with custom schema
 * const EmailSchema = Schema.String.pipe(
 *   Schema.check(isEmail)
 * )
 *
 * const emailFlag = Flag.string("email").pipe(
 *   Flag.withSchema(EmailSchema)
 * )
 *
 * // Parse JSON configuration with schema validation
 * const ConfigSchema = Schema.Struct({
 *   port: Schema.Number,
 *   host: Schema.String,
 *   ssl: Schema.optional(Schema.Boolean)
 * }).pipe(Schema.fromJsonString)
 *
 * const configFlag = Flag.string("config").pipe(
 *   Flag.withSchema(ConfigSchema)
 * )
 * ```
 *
 * @since 4.0.0
 * @category schemas
 */
export const withSchema: {
  /**
   * Validates and transforms a flag value using a Schema codec.
   *
   * @example
   * ```ts
   * import { Schema } from "effect"
   * import { Flag } from "effect/unstable/cli"
   *
   * const isEmail = Schema.isIncludes("@", {
   *   message: "Must be a valid email address"
   * })
   *
   * // Parse and validate email with custom schema
   * const EmailSchema = Schema.String.pipe(
   *   Schema.check(isEmail)
   * )
   *
   * const emailFlag = Flag.string("email").pipe(
   *   Flag.withSchema(EmailSchema)
   * )
   *
   * // Parse JSON configuration with schema validation
   * const ConfigSchema = Schema.Struct({
   *   port: Schema.Number,
   *   host: Schema.String,
   *   ssl: Schema.optional(Schema.Boolean)
   * }).pipe(Schema.fromJsonString)
   *
   * const configFlag = Flag.string("config").pipe(
   *   Flag.withSchema(ConfigSchema)
   * )
   * ```
   *
   * @since 4.0.0
   * @category schemas
   */
  <A, B>(schema: Schema.Codec<B, A>): (self: Flag<A>) => Flag<B>
  /**
   * Validates and transforms a flag value using a Schema codec.
   *
   * @example
   * ```ts
   * import { Schema } from "effect"
   * import { Flag } from "effect/unstable/cli"
   *
   * const isEmail = Schema.isIncludes("@", {
   *   message: "Must be a valid email address"
   * })
   *
   * // Parse and validate email with custom schema
   * const EmailSchema = Schema.String.pipe(
   *   Schema.check(isEmail)
   * )
   *
   * const emailFlag = Flag.string("email").pipe(
   *   Flag.withSchema(EmailSchema)
   * )
   *
   * // Parse JSON configuration with schema validation
   * const ConfigSchema = Schema.Struct({
   *   port: Schema.Number,
   *   host: Schema.String,
   *   ssl: Schema.optional(Schema.Boolean)
   * }).pipe(Schema.fromJsonString)
   *
   * const configFlag = Flag.string("config").pipe(
   *   Flag.withSchema(ConfigSchema)
   * )
   * ```
   *
   * @since 4.0.0
   * @category schemas
   */
  <A, B>(self: Flag<A>, schema: Schema.Codec<B, A>): Flag<B>
} = dual(2, <A, B>(self: Flag<A>, schema: Schema.Codec<B, A>) => Param.withSchema(self, schema))