effect 4.0.0-beta.102 → 4.0.0-beta.103

package/dist/unstable/cli/Flag.js

@@ -8,11 +8,12 @@ import * as Param from "./Param.js";
  *
  * **Example** (Creating string flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const nameFlag = Flag.string("name")
  * // Usage: --name "John Doe"
+ * nameFlag.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -24,11 +25,12 @@ export const string = name => Param.string(Param.flagKind, name);
  *
  * **Example** (Creating boolean flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const verboseFlag = Flag.boolean("verbose")
  * // Usage: --verbose (true) or --no-verbose (false)
+ * verboseFlag.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -40,11 +42,12 @@ export const boolean = name => Param.boolean(Param.flagKind, name);
  *
  * **Example** (Creating integer flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const portFlag = Flag.integer("port")
  * // Usage: --port 8080
+ * portFlag.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -56,11 +59,12 @@ export const integer = name => Param.integer(Param.flagKind, name);
  *
  * **Example** (Creating float flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const rateFlag = Flag.float("rate")
  * // Usage: --rate 3.14
+ * rateFlag.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -72,11 +76,12 @@ export const float = name => Param.float(Param.flagKind, name);
  *
  * **Example** (Creating date flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const startDateFlag = Flag.date("start-date")
  * // Usage: --start-date 2023-12-25
+ * startDateFlag.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -89,7 +94,7 @@ export const date = name => Param.date(Param.flagKind, name);
  *
  * **Example** (Creating flag choices with values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // simple enum like choice mapping directly to string union
@@ -101,6 +106,7 @@ export const date = name => Param.date(Param.flagKind, name);
  *   ["info", "Info" as const],
  *   ["error", "Error" as const]
  * ])
+ * const kinds = [color.kind, logLevel.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -131,7 +137,7 @@ export const choice = (name, choices) => Param.choice(Param.flagKind, name, choi
  *
  * **Example** (Creating path flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Basic path flag
@@ -148,6 +154,7 @@ export const choice = (name, choices) => Param.choice(Param.flagKind, name, choi
  *   pathType: "directory",
  *   typeName: "OUTPUT_DIRECTORY"
  * })
+ * const kinds = [pathFlag.kind, fileFlag.kind, dirFlag.kind] // => ["flag", "flag", "flag"]
  * ```
  *
  * @category constructors
@@ -159,7 +166,7 @@ export const path = (name, options) => Param.path(Param.flagKind, name, options)
  *
  * **Example** (Creating file flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Basic file flag
@@ -169,6 +176,7 @@ export const path = (name, options) => Param.path(Param.flagKind, name, options)
  * // File that must exist
  * const configFlag = Flag.file("config", { mustExist: true })
  * // Usage: --config ./config.yaml (file must exist)
+ * const kinds = [inputFlag.kind, configFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -180,7 +188,7 @@ export const file = (name, options) => Param.file(Param.flagKind, name, options)
  *
  * **Example** (Creating directory flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Basic directory flag
@@ -190,6 +198,7 @@ export const file = (name, options) => Param.file(Param.flagKind, name, options)
  * // Directory that must exist
  * const sourceFlag = Flag.directory("source", { mustExist: true })
  * // Usage: --source ./src (directory must exist)
+ * const kinds = [outputFlag.kind, sourceFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -207,20 +216,39 @@ export const directory = (name, options) => Param.directory(Param.flagKind, name
  *
  * **Example** (Creating redacted flags)
  *
- * ```ts
- * import { Effect, Redacted } from "effect"
- * import { Flag } from "effect/unstable/cli"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Redacted, Stdio, Terminal } from "effect"
+ * import { Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
  * const passwordFlag = Flag.redacted("password")
  *
  * const program = Effect.gen(function*() {
- *   const [leftover, password] = yield* passwordFlag.parse({
+ *   const [, password] = yield* passwordFlag.parse({
  *     arguments: [],
  *     flags: { "password": ["abc123"] }
  *   })
- *   const value = Redacted.value(password) // Access the underlying value
- *   console.log("Password length:", value.length)
+ *   return Redacted.value(password).length
  * })
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(CliTestLayer))) // => 6
  * ```
  *
  * @category constructors
@@ -232,11 +260,12 @@ export const redacted = name => Param.redacted(Param.flagKind, name);
  *
  * **Example** (Reading file text)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const config = Flag.fileText("config-file")
  * // --config-file ./app.json will read the file content
+ * config.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -253,7 +282,7 @@ export const fileText = name => Param.fileText(Param.flagKind, name);
  *
  * **Example** (Parsing file contents)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Will use the extension of the file passed on the command line to determine
@@ -262,6 +291,7 @@ export const fileText = name => Param.fileText(Param.flagKind, name);
  *
  * // Will use the JSON parser
  * const jsonConfig = Flag.fileParse("json-config", { format: "json" })
+ * const kinds = [config.kind, jsonConfig.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -274,7 +304,7 @@ export const fileParse = (name, options) => Param.fileParse(Param.flagKind, name
  *
  * **Example** (Validating file contents)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
@@ -284,6 +314,7 @@ export const fileParse = (name, options) => Param.fileParse(Param.flagKind, name
  * })
  *
  * const config = Flag.fileSchema("config", ConfigSchema, { format: "json" })
+ * config.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -305,11 +336,12 @@ export const fileSchema = (name, schema, options) => Param.fileSchema(Param.flag
  *
  * **Example** (Parsing key-value pairs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const env = Flag.keyValuePair("env")
  * // --env FOO=bar --env BAZ=qux will parse to { FOO: "bar", BAZ: "qux" }
+ * env.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -322,14 +354,14 @@ export const keyValuePair = name => Param.keyValuePair(Param.flagKind, name);
  *
  * **Example** (Creating sentinel flags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const makeValueFlag = (includeValue: boolean) =>
  *   includeValue ? Flag.string("value") : Flag.none
  *
- * console.log(makeValueFlag(true) === Flag.none) // false
- * console.log(makeValueFlag(false) === Flag.none) // true
+ * makeValueFlag(true) === Flag.none // => false
+ * makeValueFlag(false) === Flag.none // => true
  * ```
  *
  * @category constructors
@@ -344,7 +376,7 @@ export const none = /*#__PURE__*/Param.none(Param.flagKind);
  *
  * **Example** (Adding flag aliases)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Flag can be used as both --verbose and -v
@@ -357,6 +389,7 @@ export const none = /*#__PURE__*/Param.none(Param.flagKind);
  *   Flag.withAlias("h"),
  *   Flag.withAlias("?")
  * )
+ * const kinds = [verboseFlag.kind, helpFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category aliasing
@@ -368,7 +401,7 @@ export const withAlias = /*#__PURE__*/dual(2, (self, alias) => Param.withAlias(s
  *
  * **Example** (Adding help descriptions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const portFlag = Flag.integer("port").pipe(
@@ -378,9 +411,10 @@ export const withAlias = /*#__PURE__*/dual(2, (self, alias) => Param.withAlias(s
  * const configFlag = Flag.file("config").pipe(
  *   Flag.withDescription("Path to the configuration file")
  * )
+ * const kinds = [portFlag.kind, configFlag.kind] // => ["flag", "flag"]
  * ```
  *
- * @category help documentation
+ * @category metadata
  * @since 4.0.0
  */
 export const withDescription = /*#__PURE__*/dual(2, (self, description) => Param.withDescription(self, description));
@@ -397,7 +431,7 @@ export const withDescription = /*#__PURE__*/dual(2, (self, description) => Param
  *
  * **Example** (Setting metavars)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const databaseFlag = Flag.string("database-url").pipe(
@@ -410,6 +444,7 @@ export const withDescription = /*#__PURE__*/dual(2, (self, description) => Param
  *   Flag.withMetavar("SECONDS")
  * )
  * // In help: --timeout SECONDS
+ * const kinds = [databaseFlag.kind, timeoutFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category metadata
@@ -428,13 +463,14 @@ export const withMetavar = /*#__PURE__*/dual(2, (self, metavar) => Param.withMet
  *
  * **Example** (Hiding a flag from help)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Flag still parses --experimental-foo, but it does not appear in --help.
  * const experimental = Flag.boolean("experimental-foo").pipe(
  *   Flag.withHidden
  * )
+ * experimental.kind // => "flag"
  * ```
  *
  * @category metadata
@@ -446,23 +482,39 @@ export const withHidden = self => Param.withHidden(self);
  *
  * **Example** (Making flags optional)
  *
- * ```ts
- * import { Effect, Option } from "effect"
- * import { Flag } from "effect/unstable/cli"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Option, Path, Stdio, Terminal } from "effect"
+ * import { Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
  * const optionalPort = Flag.optional(Flag.integer("port"))
  *
  * const program = Effect.gen(function*() {
- *   const [leftover, port] = yield* optionalPort.parse({
+ *   const [, 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")
- *   }
+ *   return port
  * })
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(CliTestLayer))) // => Option.some(4000)
  * ```
  *
  * @category optionality
@@ -474,7 +526,7 @@ export const optional = param => Param.optional(param);
  *
  * **Example** (Providing default values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const portFlag = Flag.integer("port").pipe(
@@ -486,6 +538,7 @@ export const optional = param => Param.optional(param);
  *   Flag.withDefault("localhost")
  * )
  * // If --host is not provided, defaults to "localhost"
+ * const kinds = [portFlag.kind, hostFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category optionality
@@ -497,13 +550,14 @@ export const withDefault = Param.withDefault;
  *
  * **Example** (Falling back to config)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
  * const verbose = Flag.boolean("verbose").pipe(
  *   Flag.withFallbackConfig(Config.boolean("VERBOSE"))
  * )
+ * verbose.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -515,12 +569,13 @@ export const withFallbackConfig = /*#__PURE__*/dual(2, (self, config) => Param.w
  *
  * **Example** (Falling back to prompts)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag, Prompt } from "effect/unstable/cli"
  *
  * const name = Flag.string("name").pipe(
  *   Flag.withFallbackPrompt(Prompt.text({ message: "Name" }))
  * )
+ * name.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -532,7 +587,7 @@ export const withFallbackPrompt = /*#__PURE__*/dual(2, (self, prompt) => Param.w
  *
  * **Example** (Mapping parsed values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Convert string to uppercase
@@ -544,6 +599,7 @@ export const withFallbackPrompt = /*#__PURE__*/dual(2, (self, prompt) => Param.w
  * const urlFlag = Flag.integer("port").pipe(
  *   Flag.map((port) => `http://localhost:${port}`)
  * )
+ * const kinds = [nameFlag.kind, urlFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category mapping
@@ -555,18 +611,39 @@ export const map = /*#__PURE__*/dual(2, (self, f) => Param.map(self, f));
  *
  * **Example** (Mapping parsed values effectfully)
  *
- * ```ts
- * import { Effect, FileSystem } from "effect"
- * import { Flag } from "effect/unstable/cli"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
+ * import { Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
- * // 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
- *   }))
+ * const upperName = Flag.string("name").pipe(
+ *   Flag.mapEffect((name) => Effect.succeed(name.toUpperCase()))
  * )
+ *
+ * const [, value] = await Effect.runPromise(
+ *   upperName.parse({
+ *     arguments: [],
+ *     flags: { name: ["alice"] }
+ *   }).pipe(Effect.provide(CliTestLayer))
+ * )
+ * value // => "ALICE"
  * ```
  *
  * @category mapping
@@ -578,8 +655,27 @@ export const mapEffect = /*#__PURE__*/dual(2, (self, f) => Param.mapEffect(self,
  *
  * **Example** (Mapping thrown errors)
  *
- * ```ts
- * import { Flag } from "effect/unstable/cli"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
+ * import { Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
  * // Parse JSON string with error handling
  * const jsonFlag = Flag.string("config").pipe(
@@ -596,6 +692,14 @@ export const mapEffect = /*#__PURE__*/dual(2, (self, f) => Param.mapEffect(self,
  *     (error) => `Invalid URL: ${error}`
  *   )
  * )
+ *
+ * const [, value] = await Effect.runPromise(
+ *   jsonFlag.parse({
+ *     arguments: [],
+ *     flags: { config: ['{"enabled":true}'] }
+ *   }).pipe(Effect.provide(CliTestLayer))
+ * )
+ * value // => { enabled: true }
  * ```
  *
  * @category mapping
@@ -607,7 +711,7 @@ export const mapTryCatch = /*#__PURE__*/dual(3, (self, f, onError) => Param.mapT
  *
  * **Example** (Requiring repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const sourceFlag = Flag.atLeast(Flag.file("source"), 2)
@@ -618,6 +722,7 @@ export const mapTryCatch = /*#__PURE__*/dual(3, (self, f, onError) => Param.mapT
  *   Flag.atLeast(1)
  * )
  * // Requires at least 1 tag
+ * const kinds = [sourceFlag.kind, tagFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category repetition
@@ -629,7 +734,7 @@ export const atLeast = /*#__PURE__*/dual(2, (self, min) => Param.atLeast(self, m
  *
  * **Example** (Limiting repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const warningFlag = Flag.atMost(Flag.string("warning"), 3)
@@ -640,6 +745,7 @@ export const atLeast = /*#__PURE__*/dual(2, (self, min) => Param.atLeast(self, m
  *   Flag.atMost(1)
  * )
  * // Allows at most 1 debug flag
+ * const kinds = [warningFlag.kind, debugFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category repetition
@@ -651,7 +757,7 @@ export const atMost = /*#__PURE__*/dual(2, (self, max) => Param.atMost(self, max
  *
  * **Example** (Bounding repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * const hostFlag = Flag.between(Flag.string("host"), 1, 3)
@@ -662,6 +768,7 @@ export const atMost = /*#__PURE__*/dual(2, (self, max) => Param.atMost(self, max
  *   Flag.between(0, 5)
  * )
  * // Allows 0-5 exclude patterns
+ * const kinds = [hostFlag.kind, excludeFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category repetition
@@ -673,7 +780,7 @@ export const between = /*#__PURE__*/dual(3, (self, min, max) => Param.between(se
  *
  * **Example** (Filtering and transforming values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Option } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
@@ -692,6 +799,7 @@ export const between = /*#__PURE__*/dual(3, (self, min, max) => Param.between(se
  *     (email) => `Invalid email address: ${email}`
  *   )
  * )
+ * const kinds = [positiveInt.kind, emailFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category filtering
@@ -703,7 +811,7 @@ export const filterMap = /*#__PURE__*/dual(3, (self, f, onNone) => Param.filterM
  *
  * **Example** (Filtering parsed values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Ensure port is in valid range
@@ -721,6 +829,7 @@ export const filterMap = /*#__PURE__*/dual(3, (self, f, onNone) => Param.filterM
  *     () => "Name cannot be empty"
  *   )
  * )
+ * const kinds = [portFlag.kind, nameFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category filtering
@@ -732,7 +841,7 @@ export const filter = /*#__PURE__*/dual(3, (self, predicate, onFalse) => Param.f
  *
  * **Example** (Falling back to another flag)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Flag } from "effect/unstable/cli"
  *
  * // Try parsing as integer, fallback to string
@@ -746,6 +855,7 @@ export const filter = /*#__PURE__*/dual(3, (self, predicate, onFalse) => Param.f
  *   Flag.file("config"),
  *   () => Flag.string("config-url")
  * )
+ * const kinds = [valueFlag.kind, configFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category alternatives
@@ -757,27 +867,42 @@ export const orElse = /*#__PURE__*/dual(2, (self, that) => Param.orElse(self, th
  *
  * **Example** (Returning fallback results)
  *
- * ```ts
- * import { Effect, Result } from "effect"
- * import { Flag } from "effect/unstable/cli"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Result, Stdio, Terminal } from "effect"
+ * import { Flag } from "effect/unstable/cli"
+ * import { ChildProcessSpawner } from "effect/unstable/process"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   Layer.succeed(Terminal.Terminal, Terminal.make({
+ *     columns: Effect.succeed(80),
+ *     rows: Effect.succeed(24),
+ *     readInput: Effect.die("unused"),
+ *     readLine: Effect.die("unused"),
+ *     display: () => Effect.void
+ *   })),
+ *   Layer.succeed(
+ *     ChildProcessSpawner.ChildProcessSpawner,
+ *     ChildProcessSpawner.make(() => Effect.die("unused"))
+ *   )
+ * )
  *
- * // Try file path, fallback to URL
  * const sourceFlag = Flag.orElseResult(
- *   Flag.file("source"),
+ *   Flag.string("source"),
  *   () => Flag.string("source-url")
  * )
  *
  * const program = Effect.gen(function*() {
- *   const [leftover, source] = yield* sourceFlag.parse({
+ *   const [, source] = yield* sourceFlag.parse({
  *     arguments: [],
- *     flags: { "source-url": ["https://google.com"] }
+ *     flags: { "source-url": ["https://example.com"] }
  *   })
- *   if (Result.isSuccess(source)) {
- *     console.log("Using file:", source.success)
- *   } else {
- *     console.log("Using URL:", source.failure)
- *   }
+ *   return source
  * })
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(CliTestLayer))) // => Result.fail("https://example.com")
  * ```
  *
  * @category alternatives
@@ -789,7 +914,7 @@ export const orElseResult = /*#__PURE__*/dual(2, (self, that) => Param.orElseRes
  *
  * **Example** (Validating with schemas)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Flag } from "effect/unstable/cli"
  *
@@ -816,6 +941,7 @@ export const orElseResult = /*#__PURE__*/dual(2, (self, that) => Param.orElseRes
  * const configFlag = Flag.string("config").pipe(
  *   Flag.withSchema(ConfigSchema)
  * )
+ * const kinds = [emailFlag.kind, configFlag.kind] // => ["flag", "flag"]
  * ```
  *
  * @category schemas