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

package/dist/unstable/cli/Param.d.ts

@@ -237,17 +237,15 @@ export interface Variadic<Kind extends ParamKind, A> extends Param<Kind, Readonl
  *
  * **Example** (Checking for params)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const maybeParam = Param.string(Param.flagKind, "name")
  *
- * if (Param.isParam(maybeParam)) {
- *   console.log("This is a Param")
- * }
+ * Param.isParam(maybeParam) // => true
  * ```
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export declare const isParam: (u: unknown) => u is Param<any, ParamKind>;
@@ -256,17 +254,17 @@ export declare const isParam: (u: unknown) => u is Param<any, ParamKind>;
  *
  * **Example** (Checking for single params)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const nameParam = Param.string(Param.flagKind, "name")
  * const optionalParam = Param.optional(nameParam)
  *
- * console.log(Param.isSingle(nameParam)) // true
- * console.log(Param.isSingle(optionalParam)) // false
+ * Param.isSingle(nameParam) // => true
+ * Param.isSingle(optionalParam) // => false
  * ```
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export declare const isSingle: <const Kind extends ParamKind, A>(param: Param<Kind, A>) => param is Single<Kind, A>;
@@ -296,7 +294,7 @@ export declare const makeSingle: <const Kind extends ParamKind, A>(params: {
  *
  * **Example** (Creating string parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a string flag
@@ -306,6 +304,7 @@ export declare const makeSingle: <const Kind extends ParamKind, A>(params: {
  * const fileArg = Param.string(Param.argumentKind, "file")
  *
  * // Usage in CLI: --name "John Doe" or as positional argument
+ * const kinds = [nameFlag.kind, fileArg.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -317,7 +316,7 @@ export declare const string: <const Kind extends ParamKind>(kind: Kind, name: st
  *
  * **Example** (Creating boolean parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a boolean flag
@@ -328,6 +327,7 @@ export declare const string: <const Kind extends ParamKind>(kind: Kind, name: st
  *
  * // Usage in CLI: --verbose (defaults to true when present, false when absent)
  * // or as positional: true/false
+ * const kinds = [verboseFlag.kind, enableArg.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -339,7 +339,7 @@ export declare const boolean: <const Kind extends ParamKind>(kind: Kind, name: s
  *
  * **Example** (Creating integer parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create an integer flag
@@ -349,6 +349,7 @@ export declare const boolean: <const Kind extends ParamKind>(kind: Kind, name: s
  * const countArg = Param.integer(Param.argumentKind, "count")
  *
  * // Usage in CLI: --port 8080 or as positional argument: 42
+ * const kinds = [portFlag.kind, countArg.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -360,7 +361,7 @@ export declare const integer: <const Kind extends ParamKind>(kind: Kind, name: s
  *
  * **Example** (Creating float parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a float flag
@@ -370,6 +371,7 @@ export declare const integer: <const Kind extends ParamKind>(kind: Kind, name: s
  * const thresholdArg = Param.float(Param.argumentKind, "threshold")
  *
  * // Usage in CLI: --rate 0.95 or as positional argument: 3.14159
+ * const kinds = [rateFlag.kind, thresholdArg.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -381,7 +383,7 @@ export declare const float: <const Kind extends ParamKind>(kind: Kind, name: str
  *
  * **Example** (Creating date parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a date flag
@@ -392,6 +394,7 @@ export declare const float: <const Kind extends ParamKind>(kind: Kind, name: str
  *
  * // Usage in CLI: --start-date "2023-12-25" or as positional: "2023-01-01"
  * // Parses to JavaScript Date object
+ * const kinds = [startFlag.kind, dueDateArg.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -404,7 +407,7 @@ export declare const date: <const Kind extends ParamKind>(kind: Kind, name: stri
  *
  * **Example** (Creating valued choices)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * type Animal = Dog | Cat
@@ -421,6 +424,7 @@ export declare const date: <const Kind extends ParamKind>(kind: Kind, name: stri
  *   ["dog", { _tag: "Dog" }],
  *   ["cat", { _tag: "Cat" }]
  * ])
+ * animal.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -433,7 +437,7 @@ export declare const choiceWithValue: <const Kind extends ParamKind, const Choic
  *
  * **Example** (Creating string choices)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const logLevel = Param.choice(Param.flagKind, "log-level", [
@@ -442,6 +446,7 @@ export declare const choiceWithValue: <const Kind extends ParamKind, const Choic
  *   "warn",
  *   "error"
  * ])
+ * logLevel.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -453,7 +458,7 @@ export declare const choice: <const Kind extends ParamKind, const Choices extend
  *
  * **Example** (Creating path parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic path parameter
@@ -468,6 +473,7 @@ export declare const choice: <const Kind extends ParamKind, const Choices extend
  *   mustExist: true,
  *   typeName: "config-file"
  * })
+ * const kinds = [outputPath.kind, inputPath.kind, configFile.kind] // => ["flag", "flag", "flag"]
  * ```
  *
  * @category constructors
@@ -488,7 +494,7 @@ export declare const path: <Kind extends ParamKind>(kind: Kind, name: string, op
  *
  * **Example** (Creating directory parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic directory parameter
@@ -498,6 +504,7 @@ export declare const path: <Kind extends ParamKind>(kind: Kind, name: string, op
  * const sourceDir = Param.directory(Param.flagKind, "source", { mustExist: true })
  *
  * // Usage: --output-dir /path/to/dir --source /existing/dir
+ * const kinds = [outputDir.kind, sourceDir.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -516,7 +523,7 @@ export declare const directory: <Kind extends ParamKind>(kind: Kind, name: strin
  *
  * **Example** (Creating file parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic file parameter
@@ -526,6 +533,7 @@ export declare const directory: <Kind extends ParamKind>(kind: Kind, name: strin
  * const inputFile = Param.file(Param.flagKind, "input", { mustExist: true })
  *
  * // Usage: --output result.txt --input existing-file.txt
+ * const kinds = [outputFile.kind, inputFile.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -540,7 +548,7 @@ export declare const file: <Kind extends ParamKind>(kind: Kind, name: string, op
  *
  * **Example** (Creating redacted parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a password parameter
@@ -550,6 +558,7 @@ export declare const file: <Kind extends ParamKind>(kind: Kind, name: string, op
  * const apiKey = Param.redacted(Param.argumentKind, "api-key")
  *
  * // Usage: --password (value will be hidden in help/logs)
+ * const kinds = [password.kind, apiKey.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -561,7 +570,7 @@ export declare const redacted: <Kind extends ParamKind>(kind: Kind, name: string
  *
  * **Example** (Reading file text)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Read a config file as string
@@ -571,6 +580,7 @@ export declare const redacted: <Kind extends ParamKind>(kind: Kind, name: string
  * const templateContent = Param.fileText(Param.argumentKind, "template")
  *
  * // Usage: --config config.txt (reads file content into string)
+ * const kinds = [configContent.kind, templateContent.kind] // => ["flag", "argument"]
  * ```
  *
  * @category constructors
@@ -587,7 +597,7 @@ export declare const fileText: <Kind extends ParamKind>(kind: Kind, name: string
  *
  * **Example** (Parsing file contents)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Will use the extension of the file passed on the command line to determine
@@ -598,6 +608,7 @@ export declare const fileText: <Kind extends ParamKind>(kind: Kind, name: string
  * const jsonConfig = Param.fileParse(Param.flagKind, "json-config", {
  *   format: "json"
  * })
+ * const kinds = [config.kind, jsonConfig.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -609,7 +620,7 @@ export declare const fileParse: <Kind extends ParamKind>(kind: Kind, name: strin
  *
  * **Example** (Validating file contents)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Param } from "effect/unstable/cli"
  * // Parse JSON config file
@@ -628,6 +639,7 @@ export declare const fileParse: <Kind extends ParamKind>(kind: Kind, name: strin
  * })
  *
  * // Usage: --config config.json (reads and validates file content)
+ * const kinds = [config.kind, yamlConfig.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -649,7 +661,7 @@ export declare const fileSchema: <Kind extends ParamKind, A>(kind: Kind, name: s
  *
  * **Example** (Parsing key-value pairs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const env = Param.keyValuePair(Param.flagKind, "env")
@@ -657,6 +669,7 @@ export declare const fileSchema: <Kind extends ParamKind, A>(kind: Kind, name: s
  *
  * const props = Param.keyValuePair(Param.flagKind, "property")
  * // --property name=value --property debug=true
+ * const kinds = [env.kind, props.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -673,7 +686,7 @@ export declare const keyValuePair: <Kind extends ParamKind>(kind: Kind, name: st
  *
  * **Example** (Creating sentinel parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const disabledDebugParam = Param.none(Param.flagKind)
@@ -681,8 +694,8 @@ export declare const keyValuePair: <Kind extends ParamKind>(kind: Kind, name: st
  * const makeDebugParam = (enableDebug: boolean) =>
  *   enableDebug ? Param.string(Param.flagKind, "debug") : disabledDebugParam
  *
- * console.log(makeDebugParam(true) === disabledDebugParam) // false
- * console.log(makeDebugParam(false) === disabledDebugParam) // true
+ * makeDebugParam(true) === disabledDebugParam // => false
+ * makeDebugParam(false) === disabledDebugParam // => true
  * ```
  *
  * @category constructors
@@ -704,7 +717,7 @@ export declare const none: <Kind extends ParamKind>(kind: Kind) => Param<Kind, n
  *
  * **Example** (Adding parameter aliases)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const force = Param.boolean(Param.flagKind, "force").pipe(
@@ -717,6 +730,7 @@ export declare const none: <Kind extends ParamKind>(kind: Kind) => Param<Kind, n
  *   Param.optional,
  *   Param.withAlias("-c") // finds the underlying Single and adds alias
  * )
+ * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -738,7 +752,7 @@ export declare const withAlias: {
      *
      * **Example** (Adding parameter aliases)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const force = Param.boolean(Param.flagKind, "force").pipe(
@@ -751,6 +765,7 @@ export declare const withAlias: {
      *   Param.optional,
      *   Param.withAlias("-c") // finds the underlying Single and adds alias
      * )
+     * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -772,7 +787,7 @@ export declare const withAlias: {
      *
      * **Example** (Adding parameter aliases)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const force = Param.boolean(Param.flagKind, "force").pipe(
@@ -785,6 +800,7 @@ export declare const withAlias: {
      *   Param.optional,
      *   Param.withAlias("-c") // finds the underlying Single and adds alias
      * )
+     * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -802,13 +818,14 @@ export declare const withAlias: {
  *
  * **Example** (Adding help descriptions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
  *   Param.withAlias("-v"),
  *   Param.withDescription("Enable verbose output")
  * )
+ * verbose.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -825,13 +842,14 @@ export declare const withDescription: {
      *
      * **Example** (Adding help descriptions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
      *   Param.withAlias("-v"),
      *   Param.withDescription("Enable verbose output")
      * )
+     * verbose.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -848,13 +866,14 @@ export declare const withDescription: {
      *
      * **Example** (Adding help descriptions)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const verbose = Param.boolean(Param.flagKind, "verbose").pipe(
      *   Param.withAlias("-v"),
      *   Param.withDescription("Enable verbose output")
      * )
+     * verbose.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -873,12 +892,13 @@ export declare const withDescription: {
  *
  * **Example** (Hiding a flag from help)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const experimental = Param.boolean(Param.flagKind, "experimental-foo").pipe(
  *   Param.withHidden
  * )
+ * experimental.kind // => "flag"
  * ```
  *
  * @category metadata
@@ -890,12 +910,13 @@ export declare const withHidden: <Kind extends ParamKind, A>(self: Param<Kind, A
  *
  * **Example** (Mapping parsed values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const port = Param.integer(Param.flagKind, "port").pipe(
  *   Param.map((n) => ({ port: n, url: `http://localhost:${n}` }))
  * )
+ * port.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -907,12 +928,13 @@ export declare const map: {
      *
      * **Example** (Mapping parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const port = Param.integer(Param.flagKind, "port").pipe(
      *   Param.map((n) => ({ port: n, url: `http://localhost:${n}` }))
      * )
+     * port.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -924,12 +946,13 @@ export declare const map: {
      *
      * **Example** (Mapping parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const port = Param.integer(Param.flagKind, "port").pipe(
      *   Param.map((n) => ({ port: n, url: `http://localhost:${n}` }))
      * )
+     * port.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -942,9 +965,27 @@ export declare const map: {
  *
  * **Example** (Mapping parsed values effectfully)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { CliError, Param } 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 validatedEmail = Param.string(Param.flagKind, "email").pipe(
  *   Param.mapEffect((email) =>
@@ -960,6 +1001,14 @@ export declare const map: {
  *       )
  *   )
  * )
+ *
+ * const [, value] = await Effect.runPromise(
+ *   validatedEmail.parse({
+ *     arguments: [],
+ *     flags: { email: ["alice@example.com"] }
+ *   }).pipe(Effect.provide(CliTestLayer))
+ * )
+ * value // => "alice@example.com"
  * ```
  *
  * @category combinators
@@ -971,9 +1020,27 @@ export declare const mapEffect: {
      *
      * **Example** (Mapping parsed values effectfully)
      *
-     * ```ts
-     * import { Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
      * import { CliError, Param } 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 validatedEmail = Param.string(Param.flagKind, "email").pipe(
      *   Param.mapEffect((email) =>
@@ -989,6 +1056,14 @@ export declare const mapEffect: {
      *       )
      *   )
      * )
+     *
+     * const [, value] = await Effect.runPromise(
+     *   validatedEmail.parse({
+     *     arguments: [],
+     *     flags: { email: ["alice@example.com"] }
+     *   }).pipe(Effect.provide(CliTestLayer))
+     * )
+     * value // => "alice@example.com"
      * ```
      *
      * @category combinators
@@ -1000,9 +1075,27 @@ export declare const mapEffect: {
      *
      * **Example** (Mapping parsed values effectfully)
      *
-     * ```ts
-     * import { Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
      * import { CliError, Param } 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 validatedEmail = Param.string(Param.flagKind, "email").pipe(
      *   Param.mapEffect((email) =>
@@ -1018,6 +1111,14 @@ export declare const mapEffect: {
      *       )
      *   )
      * )
+     *
+     * const [, value] = await Effect.runPromise(
+     *   validatedEmail.parse({
+     *     arguments: [],
+     *     flags: { email: ["alice@example.com"] }
+     *   }).pipe(Effect.provide(CliTestLayer))
+     * )
+     * value // => "alice@example.com"
      * ```
      *
      * @category combinators
@@ -1031,8 +1132,27 @@ export declare const mapEffect: {
  *
  * **Example** (Mapping thrown errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
  * import { Param } 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 parsedJson = Param.string(Param.flagKind, "config").pipe(
  *   Param.mapTryCatch(
@@ -1041,6 +1161,14 @@ export declare const mapEffect: {
  *       `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
  *   )
  * )
+ *
+ * const [, value] = await Effect.runPromise(
+ *   parsedJson.parse({
+ *     arguments: [],
+ *     flags: { config: ['{"enabled":true}'] }
+ *   }).pipe(Effect.provide(CliTestLayer))
+ * )
+ * value // => { enabled: true }
  * ```
  *
  * @category combinators
@@ -1053,8 +1181,27 @@ export declare const mapTryCatch: {
      *
      * **Example** (Mapping thrown errors)
      *
-     * ```ts
+     * ```ts import.meta.vitest
+     * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
      * import { Param } 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 parsedJson = Param.string(Param.flagKind, "config").pipe(
      *   Param.mapTryCatch(
@@ -1063,6 +1210,14 @@ export declare const mapTryCatch: {
      *       `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
      *   )
      * )
+     *
+     * const [, value] = await Effect.runPromise(
+     *   parsedJson.parse({
+     *     arguments: [],
+     *     flags: { config: ['{"enabled":true}'] }
+     *   }).pipe(Effect.provide(CliTestLayer))
+     * )
+     * value // => { enabled: true }
      * ```
      *
      * @category combinators
@@ -1075,8 +1230,27 @@ export declare const mapTryCatch: {
      *
      * **Example** (Mapping thrown errors)
      *
-     * ```ts
+     * ```ts import.meta.vitest
+     * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
      * import { Param } 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 parsedJson = Param.string(Param.flagKind, "config").pipe(
      *   Param.mapTryCatch(
@@ -1085,6 +1259,14 @@ export declare const mapTryCatch: {
      *       `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
      *   )
      * )
+     *
+     * const [, value] = await Effect.runPromise(
+     *   parsedJson.parse({
+     *     arguments: [],
+     *     flags: { config: ['{"enabled":true}'] }
+     *   }).pipe(Effect.provide(CliTestLayer))
+     * )
+     * value // => { enabled: true }
      * ```
      *
      * @category combinators
@@ -1103,13 +1285,14 @@ export declare const mapTryCatch: {
  *
  * **Example** (Making parameters optional)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create an optional port option
  * // - When not provided: returns Option.none()
  * // - When provided: returns Option.some(parsedValue)
  * const port = Param.optional(Param.integer(Param.flagKind, "port"))
+ * port.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1126,7 +1309,7 @@ export declare const optional: <Kind extends ParamKind, A>(param: Param<Kind, A>
  *
  * **Example** (Providing default values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Using the pipe operator to make an option optional
@@ -1140,6 +1323,7 @@ export declare const optional: <Kind extends ParamKind, A>(param: Param<Kind, A>
  *   Param.withDescription("Enable verbose output"),
  *   Param.withDefault(false)
  * )
+ * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -1156,7 +1340,7 @@ export declare const withDefault: {
      *
      * **Example** (Providing default values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Using the pipe operator to make an option optional
@@ -1170,6 +1354,7 @@ export declare const withDefault: {
      *   Param.withDescription("Enable verbose output"),
      *   Param.withDefault(false)
      * )
+     * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -1186,7 +1371,7 @@ export declare const withDefault: {
      *
      * **Example** (Providing default values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Using the pipe operator to make an option optional
@@ -1200,6 +1385,7 @@ export declare const withDefault: {
      *   Param.withDescription("Enable verbose output"),
      *   Param.withDefault(false)
      * )
+     * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -1389,7 +1575,7 @@ export type VariadicParamOptions = {
  *
  * **Example** (Accepting multiple values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic variadic parameter (0 to infinity)
@@ -1406,6 +1592,7 @@ export type VariadicParamOptions = {
  *   min: 2, // at least 2 times
  *   max: 2 // at most 2 times
  * })
+ * const kinds = [tags.kind, inputs.kind, limited.kind] // => ["flag", "flag", "flag"]
  * ```
  *
  * @category combinators
@@ -1422,7 +1609,7 @@ export declare const variadic: <Kind extends ParamKind, A>(self: Param<Kind, A>,
  *
  * **Example** (Bounding repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Allow 1-3 file inputs
@@ -1441,6 +1628,7 @@ export declare const variadic: <Kind extends ParamKind, A>(self: Param<Kind, A>,
  *
  * // Parse: --tag dev --tag staging --tag v1.0
  * // Result: ["dev", "staging", "v1.0"]
+ * const kinds = [files.kind, tags.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -1457,7 +1645,7 @@ export declare const between: {
      *
      * **Example** (Bounding repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Allow 1-3 file inputs
@@ -1476,6 +1664,7 @@ export declare const between: {
      *
      * // Parse: --tag dev --tag staging --tag v1.0
      * // Result: ["dev", "staging", "v1.0"]
+     * const kinds = [files.kind, tags.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -1492,7 +1681,7 @@ export declare const between: {
      *
      * **Example** (Bounding repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Allow 1-3 file inputs
@@ -1511,6 +1700,7 @@ export declare const between: {
      *
      * // Parse: --tag dev --tag staging --tag v1.0
      * // Result: ["dev", "staging", "v1.0"]
+     * const kinds = [files.kind, tags.kind] // => ["flag", "flag"]
      * ```
      *
      * @category combinators
@@ -1528,7 +1718,7 @@ export declare const between: {
  *
  * **Example** (Limiting repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Allow at most 3 warning suppressions
@@ -1538,6 +1728,7 @@ export declare const between: {
  *
  * // Parse: --suppress warning1 --suppress warning2
  * // Result: ["warning1", "warning2"]
+ * suppressions.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1554,7 +1745,7 @@ export declare const atMost: {
      *
      * **Example** (Limiting repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Allow at most 3 warning suppressions
@@ -1564,6 +1755,7 @@ export declare const atMost: {
      *
      * // Parse: --suppress warning1 --suppress warning2
      * // Result: ["warning1", "warning2"]
+     * suppressions.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1580,7 +1772,7 @@ export declare const atMost: {
      *
      * **Example** (Limiting repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Allow at most 3 warning suppressions
@@ -1590,6 +1782,7 @@ export declare const atMost: {
      *
      * // Parse: --suppress warning1 --suppress warning2
      * // Result: ["warning1", "warning2"]
+     * suppressions.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1607,7 +1800,7 @@ export declare const atMost: {
  *
  * **Example** (Requiring repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Require at least 2 input files
@@ -1618,6 +1811,7 @@ export declare const atMost: {
  *
  * // Parse: --input file1.txt --input file2.txt --input file3.txt
  * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+ * inputs.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1634,7 +1828,7 @@ export declare const atLeast: {
      *
      * **Example** (Requiring repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Require at least 2 input files
@@ -1645,6 +1839,7 @@ export declare const atLeast: {
      *
      * // Parse: --input file1.txt --input file2.txt --input file3.txt
      * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+     * inputs.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1661,7 +1856,7 @@ export declare const atLeast: {
      *
      * **Example** (Requiring repeated values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * // Require at least 2 input files
@@ -1672,6 +1867,7 @@ export declare const atLeast: {
      *
      * // Parse: --input file1.txt --input file2.txt --input file3.txt
      * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+     * inputs.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1690,7 +1886,7 @@ export declare const atLeast: {
  *
  * **Example** (Filtering and transforming values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Option } from "effect"
  * import { Param } from "effect/unstable/cli"
  * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -1699,6 +1895,7 @@ export declare const atLeast: {
  *     (n) => `Expected positive integer, got ${n}`
  *   )
  * )
+ * positiveInt.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1716,7 +1913,7 @@ export declare const filterMap: {
      *
      * **Example** (Filtering and transforming values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Option } from "effect"
      * import { Param } from "effect/unstable/cli"
      * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -1725,6 +1922,7 @@ export declare const filterMap: {
      *     (n) => `Expected positive integer, got ${n}`
      *   )
      * )
+     * positiveInt.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1742,7 +1940,7 @@ export declare const filterMap: {
      *
      * **Example** (Filtering and transforming values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Option } from "effect"
      * import { Param } from "effect/unstable/cli"
      * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -1751,6 +1949,7 @@ export declare const filterMap: {
      *     (n) => `Expected positive integer, got ${n}`
      *   )
      * )
+     * positiveInt.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1763,7 +1962,7 @@ export declare const filterMap: {
  *
  * **Example** (Filtering parsed values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const evenNumber = Param.integer(Param.flagKind, "num").pipe(
@@ -1772,6 +1971,7 @@ export declare const filterMap: {
  *     (n) => `Expected even number, got ${n}`
  *   )
  * )
+ * evenNumber.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1783,7 +1983,7 @@ export declare const filter: {
      *
      * **Example** (Filtering parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const evenNumber = Param.integer(Param.flagKind, "num").pipe(
@@ -1792,6 +1992,7 @@ export declare const filter: {
      *     (n) => `Expected even number, got ${n}`
      *   )
      * )
+     * evenNumber.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1803,7 +2004,7 @@ export declare const filter: {
      *
      * **Example** (Filtering parsed values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const evenNumber = Param.integer(Param.flagKind, "num").pipe(
@@ -1812,6 +2013,7 @@ export declare const filter: {
      *     (n) => `Expected even number, got ${n}`
      *   )
      * )
+     * evenNumber.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1829,7 +2031,7 @@ export declare const filter: {
  *
  * **Example** (Setting metavars)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -1839,6 +2041,7 @@ export declare const filter: {
  *     () => "Port must be between 1 and 65535"
  *   )
  * )
+ * port.kind // => "flag"
  * ```
  *
  * @category metadata
@@ -1855,7 +2058,7 @@ export declare const withMetavar: {
      *
      * **Example** (Setting metavars)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -1865,6 +2068,7 @@ export declare const withMetavar: {
      *     () => "Port must be between 1 and 65535"
      *   )
      * )
+     * port.kind // => "flag"
      * ```
      *
      * @category metadata
@@ -1881,7 +2085,7 @@ export declare const withMetavar: {
      *
      * **Example** (Setting metavars)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -1891,6 +2095,7 @@ export declare const withMetavar: {
      *     () => "Port must be between 1 and 65535"
      *   )
      * )
+     * port.kind // => "flag"
      * ```
      *
      * @category metadata
@@ -1903,7 +2108,7 @@ export declare const withMetavar: {
  *
  * **Example** (Validating with schemas)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Param } from "effect/unstable/cli"
  * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -1915,6 +2120,7 @@ export declare const withMetavar: {
  * const email = Param.string(Param.flagKind, "email").pipe(
  *   Param.withSchema(Email)
  * )
+ * email.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1926,7 +2132,7 @@ export declare const withSchema: {
      *
      * **Example** (Validating with schemas)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Schema } from "effect"
      * import { Param } from "effect/unstable/cli"
      * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -1938,6 +2144,7 @@ export declare const withSchema: {
      * const email = Param.string(Param.flagKind, "email").pipe(
      *   Param.withSchema(Email)
      * )
+     * email.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1949,7 +2156,7 @@ export declare const withSchema: {
      *
      * **Example** (Validating with schemas)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Schema } from "effect"
      * import { Param } from "effect/unstable/cli"
      * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -1961,6 +2168,7 @@ export declare const withSchema: {
      * const email = Param.string(Param.flagKind, "email").pipe(
      *   Param.withSchema(Email)
      * )
+     * email.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -1973,12 +2181,13 @@ export declare const withSchema: {
  *
  * **Example** (Falling back to another parameter)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const config = Param.file(Param.flagKind, "config").pipe(
  *   Param.orElse(() => Param.string(Param.flagKind, "config-url"))
  * )
+ * config.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1990,12 +2199,13 @@ export declare const orElse: {
      *
      * **Example** (Falling back to another parameter)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const config = Param.file(Param.flagKind, "config").pipe(
      *   Param.orElse(() => Param.string(Param.flagKind, "config-url"))
      * )
+     * config.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -2007,12 +2217,13 @@ export declare const orElse: {
      *
      * **Example** (Falling back to another parameter)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const config = Param.file(Param.flagKind, "config").pipe(
      *   Param.orElse(() => Param.string(Param.flagKind, "config-url"))
      * )
+     * config.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -2031,13 +2242,14 @@ export declare const orElse: {
  *
  * **Example** (Returning fallback results)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const configSource = Param.file(Param.flagKind, "config").pipe(
  *   Param.orElseResult(() => Param.string(Param.flagKind, "config-url"))
  * )
  * // Returns Result<string, string>
+ * configSource.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -2055,13 +2267,14 @@ export declare const orElseResult: {
      *
      * **Example** (Returning fallback results)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const configSource = Param.file(Param.flagKind, "config").pipe(
      *   Param.orElseResult(() => Param.string(Param.flagKind, "config-url"))
      * )
      * // Returns Result<string, string>
+     * configSource.kind // => "flag"
      * ```
      *
      * @category combinators
@@ -2079,13 +2292,14 @@ export declare const orElseResult: {
      *
      * **Example** (Returning fallback results)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Param } from "effect/unstable/cli"
      *
      * const configSource = Param.file(Param.flagKind, "config").pipe(
      *   Param.orElseResult(() => Param.string(Param.flagKind, "config-url"))
      * )
      * // Returns Result<string, string>
+     * configSource.kind // => "flag"
      * ```
      *
      * @category combinators