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

package/src/unstable/cli/Param.ts

@@ -272,17 +272,15 @@ const Proto = {
  *
  * **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 const isParam = (u: unknown): u is Param<any, ParamKind> => Predicate.hasProperty(u, TypeId)
@@ -292,17 +290,17 @@ export const isParam = (u: unknown): u is Param<any, ParamKind> => Predicate.has
  *
  * **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 const isSingle = <const Kind extends ParamKind, A>(
@@ -358,7 +356,7 @@ export 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
@@ -368,6 +366,7 @@ export 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
@@ -388,7 +387,7 @@ export const string = <const Kind extends ParamKind>(
  *
  * **Example** (Creating boolean parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a boolean flag
@@ -399,6 +398,7 @@ export const string = <const Kind extends ParamKind>(
  *
  * // 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
@@ -419,7 +419,7 @@ export const boolean = <const Kind extends ParamKind>(
  *
  * **Example** (Creating integer parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create an integer flag
@@ -429,6 +429,7 @@ export const boolean = <const Kind extends ParamKind>(
  * 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
@@ -449,7 +450,7 @@ export const integer = <const Kind extends ParamKind>(
  *
  * **Example** (Creating float parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a float flag
@@ -459,6 +460,7 @@ export const integer = <const Kind extends ParamKind>(
  * 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
@@ -479,7 +481,7 @@ export const float = <const Kind extends ParamKind>(
  *
  * **Example** (Creating date parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a date flag
@@ -490,6 +492,7 @@ export const float = <const Kind extends ParamKind>(
  *
  * // 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
@@ -511,7 +514,7 @@ export const date = <const Kind extends ParamKind>(
  *
  * **Example** (Creating valued choices)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * type Animal = Dog | Cat
@@ -528,6 +531,7 @@ export const date = <const Kind extends ParamKind>(
  *   ["dog", { _tag: "Dog" }],
  *   ["cat", { _tag: "Cat" }]
  * ])
+ * animal.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -549,7 +553,7 @@ export const choiceWithValue = <
  *
  * **Example** (Creating string choices)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const logLevel = Param.choice(Param.flagKind, "log-level", [
@@ -558,6 +562,7 @@ export const choiceWithValue = <
  *   "warn",
  *   "error"
  * ])
+ * logLevel.kind // => "flag"
  * ```
  *
  * @category constructors
@@ -576,7 +581,7 @@ export const choice = <
  *
  * **Example** (Creating path parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic path parameter
@@ -591,6 +596,7 @@ export const choice = <
  *   mustExist: true,
  *   typeName: "config-file"
  * })
+ * const kinds = [outputPath.kind, inputPath.kind, configFile.kind] // => ["flag", "flag", "flag"]
  * ```
  *
  * @category constructors
@@ -622,7 +628,7 @@ export const path = <Kind extends ParamKind>(
  *
  * **Example** (Creating directory parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic directory parameter
@@ -632,6 +638,7 @@ export const path = <Kind extends ParamKind>(
  * 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
@@ -660,7 +667,7 @@ export const directory = <Kind extends ParamKind>(
  *
  * **Example** (Creating file parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Basic file parameter
@@ -670,6 +677,7 @@ export const directory = <Kind extends ParamKind>(
  * 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
@@ -694,7 +702,7 @@ export const file = <Kind extends ParamKind>(
  *
  * **Example** (Creating redacted parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Create a password parameter
@@ -704,6 +712,7 @@ export const file = <Kind extends ParamKind>(
  * 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
@@ -724,7 +733,7 @@ export const redacted = <Kind extends ParamKind>(
  *
  * **Example** (Reading file text)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Read a config file as string
@@ -734,6 +743,7 @@ export const redacted = <Kind extends ParamKind>(
  * 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
@@ -756,7 +766,7 @@ export const fileText = <Kind extends ParamKind>(kind: Kind, name: string): Para
  *
  * **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
@@ -767,6 +777,7 @@ export const fileText = <Kind extends ParamKind>(kind: Kind, name: string): Para
  * const jsonConfig = Param.fileParse(Param.flagKind, "json-config", {
  *   format: "json"
  * })
+ * const kinds = [config.kind, jsonConfig.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -788,7 +799,7 @@ export const fileParse = <Kind extends ParamKind>(
  *
  * **Example** (Validating file contents)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema } from "effect"
  * import { Param } from "effect/unstable/cli"
  * // Parse JSON config file
@@ -807,6 +818,7 @@ export const fileParse = <Kind extends ParamKind>(
  * })
  *
  * // Usage: --config config.json (reads and validates file content)
+ * const kinds = [config.kind, yamlConfig.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -839,7 +851,7 @@ export const fileSchema = <Kind extends ParamKind, A>(
  *
  * **Example** (Parsing key-value pairs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const env = Param.keyValuePair(Param.flagKind, "env")
@@ -847,6 +859,7 @@ export const fileSchema = <Kind extends ParamKind, A>(
  *
  * const props = Param.keyValuePair(Param.flagKind, "property")
  * // --property name=value --property debug=true
+ * const kinds = [env.kind, props.kind] // => ["flag", "flag"]
  * ```
  *
  * @category constructors
@@ -878,7 +891,7 @@ export const keyValuePair = <Kind extends ParamKind>(
  *
  * **Example** (Creating sentinel parameters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const disabledDebugParam = Param.none(Param.flagKind)
@@ -886,8 +899,8 @@ export const keyValuePair = <Kind extends ParamKind>(
  * 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
@@ -917,7 +930,7 @@ const FLAG_DASH_REGEXP = /^-+/
  *
  * **Example** (Adding parameter aliases)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const force = Param.boolean(Param.flagKind, "force").pipe(
@@ -930,6 +943,7 @@ const FLAG_DASH_REGEXP = /^-+/
  *   Param.optional,
  *   Param.withAlias("-c") // finds the underlying Single and adds alias
  * )
+ * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -951,7 +965,7 @@ export 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(
@@ -964,6 +978,7 @@ export const withAlias: {
    *   Param.optional,
    *   Param.withAlias("-c") // finds the underlying Single and adds alias
    * )
+   * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
    * ```
    *
    * @category combinators
@@ -985,7 +1000,7 @@ export 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(
@@ -998,6 +1013,7 @@ export const withAlias: {
    *   Param.optional,
    *   Param.withAlias("-c") // finds the underlying Single and adds alias
    * )
+   * const kinds = [force.kind, count.kind] // => ["flag", "flag"]
    * ```
    *
    * @category combinators
@@ -1022,13 +1038,14 @@ export 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
@@ -1045,13 +1062,14 @@ export 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
@@ -1068,13 +1086,14 @@ export 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
@@ -1100,12 +1119,13 @@ export 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
@@ -1123,12 +1143,13 @@ export const withHidden = <Kind extends ParamKind, A>(self: Param<Kind, A>): Par
  *
  * **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
@@ -1140,12 +1161,13 @@ export 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
@@ -1157,12 +1179,13 @@ export 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
@@ -1201,9 +1224,27 @@ const transform = <Kind extends ParamKind, A, B>(
  *
  * **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) =>
@@ -1219,6 +1260,14 @@ const transform = <Kind extends ParamKind, A, B>(
  *       )
  *   )
  * )
+ *
+ * const [, value] = await Effect.runPromise(
+ *   validatedEmail.parse({
+ *     arguments: [],
+ *     flags: { email: ["alice@example.com"] }
+ *   }).pipe(Effect.provide(CliTestLayer))
+ * )
+ * value // => "alice@example.com"
  * ```
  *
  * @category combinators
@@ -1230,9 +1279,27 @@ export 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) =>
@@ -1248,6 +1315,14 @@ export 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
@@ -1259,9 +1334,27 @@ export 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) =>
@@ -1277,6 +1370,14 @@ export 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
@@ -1305,8 +1406,27 @@ export 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(
@@ -1315,6 +1435,14 @@ export 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
@@ -1327,8 +1455,27 @@ export 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(
@@ -1337,6 +1484,14 @@ export 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
@@ -1349,8 +1504,27 @@ export 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(
@@ -1359,6 +1533,14 @@ export 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
@@ -1405,13 +1587,14 @@ export 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
@@ -1461,7 +1644,7 @@ export const optional = <Kind extends ParamKind, 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
@@ -1475,6 +1658,7 @@ export const optional = <Kind extends ParamKind, A>(
  *   Param.withDescription("Enable verbose output"),
  *   Param.withDefault(false)
  * )
+ * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -1491,7 +1675,7 @@ export 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
@@ -1505,6 +1689,7 @@ export const withDefault: {
    *   Param.withDescription("Enable verbose output"),
    *   Param.withDefault(false)
    * )
+   * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
    * ```
    *
    * @category combinators
@@ -1521,7 +1706,7 @@ export 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
@@ -1535,6 +1720,7 @@ export const withDefault: {
    *   Param.withDescription("Enable verbose output"),
    *   Param.withDefault(false)
    * )
+   * const kinds = [port.kind, verbose.kind] // => ["flag", "flag"]
    * ```
    *
    * @category combinators
@@ -1790,7 +1976,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)
@@ -1807,6 +1993,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
@@ -1844,7 +2031,7 @@ export const variadic = <Kind extends ParamKind, A>(
  *
  * **Example** (Bounding repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Allow 1-3 file inputs
@@ -1863,6 +2050,7 @@ export const variadic = <Kind extends ParamKind, A>(
  *
  * // Parse: --tag dev --tag staging --tag v1.0
  * // Result: ["dev", "staging", "v1.0"]
+ * const kinds = [files.kind, tags.kind] // => ["flag", "flag"]
  * ```
  *
  * @category combinators
@@ -1879,7 +2067,7 @@ export const between: {
    *
    * **Example** (Bounding repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Allow 1-3 file inputs
@@ -1898,6 +2086,7 @@ export 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
@@ -1914,7 +2103,7 @@ export const between: {
    *
    * **Example** (Bounding repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Allow 1-3 file inputs
@@ -1933,6 +2122,7 @@ export 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
@@ -1960,7 +2150,7 @@ export const between: {
  *
  * **Example** (Limiting repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Allow at most 3 warning suppressions
@@ -1970,6 +2160,7 @@ export const between: {
  *
  * // Parse: --suppress warning1 --suppress warning2
  * // Result: ["warning1", "warning2"]
+ * suppressions.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -1986,7 +2177,7 @@ export const atMost: {
    *
    * **Example** (Limiting repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Allow at most 3 warning suppressions
@@ -1996,6 +2187,7 @@ export const atMost: {
    *
    * // Parse: --suppress warning1 --suppress warning2
    * // Result: ["warning1", "warning2"]
+   * suppressions.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2012,7 +2204,7 @@ export const atMost: {
    *
    * **Example** (Limiting repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Allow at most 3 warning suppressions
@@ -2022,6 +2214,7 @@ export const atMost: {
    *
    * // Parse: --suppress warning1 --suppress warning2
    * // Result: ["warning1", "warning2"]
+   * suppressions.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2045,7 +2238,7 @@ export const atMost: {
  *
  * **Example** (Requiring repeated values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * // Require at least 2 input files
@@ -2056,6 +2249,7 @@ export const atMost: {
  *
  * // Parse: --input file1.txt --input file2.txt --input file3.txt
  * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+ * inputs.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -2072,7 +2266,7 @@ export const atLeast: {
    *
    * **Example** (Requiring repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Require at least 2 input files
@@ -2083,6 +2277,7 @@ export const atLeast: {
    *
    * // Parse: --input file1.txt --input file2.txt --input file3.txt
    * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+   * inputs.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2099,7 +2294,7 @@ export const atLeast: {
    *
    * **Example** (Requiring repeated values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * // Require at least 2 input files
@@ -2110,6 +2305,7 @@ export const atLeast: {
    *
    * // Parse: --input file1.txt --input file2.txt --input file3.txt
    * // Result: ["file1.txt", "file2.txt", "file3.txt"]
+   * inputs.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2134,7 +2330,7 @@ export 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(
@@ -2143,6 +2339,7 @@ export const atLeast: {
  *     (n) => `Expected positive integer, got ${n}`
  *   )
  * )
+ * positiveInt.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -2160,7 +2357,7 @@ export 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(
@@ -2169,6 +2366,7 @@ export const filterMap: {
    *     (n) => `Expected positive integer, got ${n}`
    *   )
    * )
+   * positiveInt.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2186,7 +2384,7 @@ export 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(
@@ -2195,6 +2393,7 @@ export const filterMap: {
    *     (n) => `Expected positive integer, got ${n}`
    *   )
    * )
+   * positiveInt.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2232,7 +2431,7 @@ export 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(
@@ -2241,6 +2440,7 @@ export const filterMap: {
  *     (n) => `Expected even number, got ${n}`
  *   )
  * )
+ * evenNumber.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -2252,7 +2452,7 @@ export 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(
@@ -2261,6 +2461,7 @@ export const filter: {
    *     (n) => `Expected even number, got ${n}`
    *   )
    * )
+   * evenNumber.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2272,7 +2473,7 @@ export 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(
@@ -2281,6 +2482,7 @@ export const filter: {
    *     (n) => `Expected even number, got ${n}`
    *   )
    * )
+   * evenNumber.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2307,7 +2509,7 @@ export const filter: {
  *
  * **Example** (Setting metavars)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Param } from "effect/unstable/cli"
  *
  * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -2317,6 +2519,7 @@ export const filter: {
  *     () => "Port must be between 1 and 65535"
  *   )
  * )
+ * port.kind // => "flag"
  * ```
  *
  * @category metadata
@@ -2333,7 +2536,7 @@ export const withMetavar: {
    *
    * **Example** (Setting metavars)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -2343,6 +2546,7 @@ export const withMetavar: {
    *     () => "Port must be between 1 and 65535"
    *   )
    * )
+   * port.kind // => "flag"
    * ```
    *
    * @category metadata
@@ -2359,7 +2563,7 @@ export const withMetavar: {
    *
    * **Example** (Setting metavars)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Param } from "effect/unstable/cli"
    *
    * const port = Param.integer(Param.flagKind, "port").pipe(
@@ -2369,6 +2573,7 @@ export const withMetavar: {
    *     () => "Port must be between 1 and 65535"
    *   )
    * )
+   * port.kind // => "flag"
    * ```
    *
    * @category metadata
@@ -2390,7 +2595,7 @@ export 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@]+$/)
@@ -2402,6 +2607,7 @@ export const withMetavar: {
  * const email = Param.string(Param.flagKind, "email").pipe(
  *   Param.withSchema(Email)
  * )
+ * email.kind // => "flag"
  * ```
  *
  * @category combinators
@@ -2413,7 +2619,7 @@ export 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@]+$/)
@@ -2425,6 +2631,7 @@ export const withSchema: {
    * const email = Param.string(Param.flagKind, "email").pipe(
    *   Param.withSchema(Email)
    * )
+   * email.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2438,7 +2645,7 @@ export 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@]+$/)
@@ -2450,6 +2657,7 @@ export const withSchema: {
    * const email = Param.string(Param.flagKind, "email").pipe(
    *   Param.withSchema(Email)
    * )
+   * email.kind // => "flag"
    * ```
    *
    * @category combinators
@@ -2481,12 +2689,13 @@ export 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
@@ -2498,12 +2707,13 @@ export 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
@@ -2515,12 +2725,13 @@ export 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
@@ -2547,13 +2758,14 @@ export 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
@@ -2571,13 +2783,14 @@ export 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
@@ -2595,13 +2808,14 @@ export 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