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

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

@@ -10,26 +10,16 @@ declare const TypeId = "~effect/cli/CliError";
  *
  * **Example** (Checking CLI errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
- * const handleError = (error: unknown) => {
- *   if (CliError.isCliError(error)) {
- *     console.log("CLI Error:", error.message)
- *     return Effect.succeed("Handled CLI error")
- *   }
- *   return Effect.fail("Unknown error")
- * }
+ * const error = new CliError.MissingOption({ option: "api-key" })
+ * const program = CliError.isCliError(error)
+ *   ? Effect.succeed(error.message)
+ *   : Effect.fail("Unknown error")
  *
- * // Example usage in error handling
- * const program = Effect.gen(function*() {
- *   const result = yield* Effect.try({
- *     try: () => ({ success: true }),
- *     catch: (error) => error
- *   })
- *   handleError(result)
- * })
+ * await Effect.runPromise(program) // => "Missing required flag: --api-key"
  * ```
  *
  * @category guards
@@ -41,31 +31,28 @@ export declare const isCliError: (u: unknown) => u is CliError;
  *
  * **Example** (Handling CLI errors)
  *
- * ```ts
- * import type { CliError } from "effect/unstable/cli"
+ * ```ts import.meta.vitest
+ * import { CliError } from "effect/unstable/cli"
  *
- * const handleCliError = (error: CliError.CliError): void => {
+ * const describe = (error: CliError.CliError): string => {
  *   switch (error._tag) {
  *     case "UnrecognizedOption":
- *       console.log(`Unknown flag: ${error.option}`)
- *       break
+ *       return `Unknown flag: ${error.option}`
  *     case "MissingOption":
- *       console.log(`Required flag missing: ${error.option}`)
- *       break
+ *       return `Required flag missing: ${error.option}`
  *     case "InvalidValue":
- *       console.log(`Invalid value: ${error.value} for ${error.option}`)
- *       break
+ *       return `Invalid value: ${error.value} for ${error.option}`
  *     case "ShowHelp":
- *       // Display help for the command path
- *       console.log(`Help requested for: ${error.commandPath.join(" ")}`)
- *       break
+ *       return `Help requested for: ${error.commandPath.join(" ")}`
  *     default:
- *       console.log(error.message)
+ *       return error.message
  *   }
  * }
+ *
+ * describe(new CliError.MissingOption({ option: "token" })) // => "Required flag missing: token"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export type CliError = UnrecognizedOption | DuplicateOption | MissingOption | MissingArgument | UnexpectedArgument | InvalidValue | UnknownSubcommand | ShowHelp | UserError;
@@ -79,7 +66,7 @@ declare const UnrecognizedOption_base: Schema.Class<UnrecognizedOption, Schema.T
  *
  * **Example** (Creating unrecognized option errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -90,21 +77,21 @@ declare const UnrecognizedOption_base: Schema.Class<UnrecognizedOption, Schema.T
  *   suggestions: ["--verbose", "--force"]
  * })
  *
- * console.log(unrecognizedError.message)
- * // "Unrecognized flag: --unknown-flag in command deploy production
- * //
- * //  Did you mean this?
- * //    --verbose
- * //    --force"
+ * unrecognizedError._tag // => "UnrecognizedOption"
+ * unrecognizedError.option // => "--unknown-flag"
+ * unrecognizedError.command // => ["deploy", "production"]
  *
  * // In CLI parsing context
  * const parseCommand = Effect.gen(function*() {
  *   // If parsing encounters unknown flag
  *   return yield* unrecognizedError
  * })
+ *
+ * const parseError = await Effect.runPromise(Effect.flip(parseCommand))
+ * parseError._tag // => "UnrecognizedOption"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export declare class UnrecognizedOption extends UnrecognizedOption_base {
@@ -131,7 +118,7 @@ declare const DuplicateOption_base: Schema.Class<DuplicateOption, Schema.TaggedS
  *
  * **Example** (Creating duplicate option errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { CliError } from "effect/unstable/cli"
  *
  * const duplicateError = new CliError.DuplicateOption({
@@ -140,12 +127,13 @@ declare const DuplicateOption_base: Schema.Class<DuplicateOption, Schema.TaggedS
  *   childCommand: "deploy"
  * })
  *
- * console.log(duplicateError.message)
- * // "Duplicate flag name "--verbose" in parent command "myapp" and subcommand "deploy".
- * // Parent will always claim this flag (Mode A semantics). Consider renaming one of them to avoid confusion."
+ * duplicateError._tag // => "DuplicateOption"
+ * duplicateError.option // => "--verbose"
+ * duplicateError.parentCommand // => "myapp"
+ * duplicateError.childCommand // => "deploy"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export declare class DuplicateOption extends DuplicateOption_base {
@@ -170,7 +158,7 @@ declare const MissingOption_base: Schema.Class<MissingOption, Schema.TaggedStruc
  *
  * **Example** (Creating missing option errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -178,8 +166,7 @@ declare const MissingOption_base: Schema.Class<MissingOption, Schema.TaggedStruc
  *   option: "api-key"
  * })
  *
- * console.log(missingOptionError.message)
- * // "Missing required flag: --api-key"
+ * const details = [missingOptionError._tag, missingOptionError.option] // => ["MissingOption", "api-key"]
  *
  * // In validation context
  * const validateRequiredOptions = (options: Record<string, string | undefined>) =>
@@ -190,9 +177,12 @@ declare const MissingOption_base: Schema.Class<MissingOption, Schema.TaggedStruc
  *     }
  *     return apiKey
  *   })
+ *
+ * const validationError = await Effect.runPromise(Effect.flip(validateRequiredOptions({})))
+ * validationError._tag // => "MissingOption"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export declare class MissingOption extends MissingOption_base {
@@ -217,7 +207,7 @@ declare const MissingArgument_base: Schema.Class<MissingArgument, Schema.TaggedS
  *
  * **Example** (Creating missing argument errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -225,8 +215,7 @@ declare const MissingArgument_base: Schema.Class<MissingArgument, Schema.TaggedS
  *   argument: "target"
  * })
  *
- * console.log(missingArgError.message)
- * // "Missing required argument: target"
+ * const details = [missingArgError._tag, missingArgError.argument] // => ["MissingArgument", "target"]
  *
  * // In argument parsing
  * const parseArguments = (args: Array<string>) =>
@@ -236,9 +225,12 @@ declare const MissingArgument_base: Schema.Class<MissingArgument, Schema.TaggedS
  *     }
  *     return args[0]
  *   })
+ *
+ * const parseError = await Effect.runPromise(Effect.flip(parseArguments([])))
+ * parseError._tag // => "MissingArgument"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export declare class MissingArgument extends MissingArgument_base {
@@ -264,18 +256,17 @@ declare const UnexpectedArgument_base: Schema.Class<UnexpectedArgument, Schema.T
  *
  * **Example** (Reporting unexpected arguments)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { CliError } from "effect/unstable/cli"
  *
  * const error = new CliError.UnexpectedArgument({
  *   arguments: ["extra.txt"]
  * })
  *
- * console.log(error.message)
- * // "Unexpected positional argument: \"extra.txt\""
+ * const details = [error._tag, error.arguments] // => ["UnexpectedArgument", ["extra.txt"]]
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export declare class UnexpectedArgument extends UnexpectedArgument_base {
@@ -303,8 +294,7 @@ declare const InvalidValue_base: Schema.Class<InvalidValue, Schema.TaggedStruct<
  *
  * **Example** (Creating invalid value errors)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
  * import { CliError } from "effect/unstable/cli"
  *
  * const invalidValueError = new CliError.InvalidValue({
@@ -314,8 +304,10 @@ declare const InvalidValue_base: Schema.Class<InvalidValue, Schema.TaggedStruct<
  *   kind: "flag"
  * })
  *
- * console.log(invalidValueError.message)
- * // "Invalid value for flag --port: "abc123". Expected: integer between 1 and 65535"
+ * invalidValueError._tag // => "InvalidValue"
+ * invalidValueError.kind // => "flag"
+ * invalidValueError.option // => "port"
+ * invalidValueError.value // => "abc123"
  *
  * // For positional arguments
  * const invalidArgError = new CliError.InvalidValue({
@@ -325,11 +317,10 @@ declare const InvalidValue_base: Schema.Class<InvalidValue, Schema.TaggedStruct<
  *   kind: "argument"
  * })
  *
- * console.log(invalidArgError.message)
- * // "Invalid value for argument <count>: "abc". Expected: integer"
+ * const details = [invalidArgError.kind, invalidArgError.option, invalidArgError.value] // => ["argument", "count", "abc"]
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export declare class InvalidValue extends InvalidValue_base {
@@ -356,7 +347,7 @@ declare const UnknownSubcommand_base: Schema.Class<UnknownSubcommand, Schema.Tag
  *
  * **Example** (Creating unknown subcommand errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -366,12 +357,9 @@ declare const UnknownSubcommand_base: Schema.Class<UnknownSubcommand, Schema.Tag
  *   suggestions: ["deploy", "destroy"]
  * })
  *
- * console.log(unknownSubcommandError.message)
- * // "Unknown subcommand "deplyo" for "myapp"
- * //
- * //  Did you mean this?
- * //    deploy
- * //    destroy"
+ * unknownSubcommandError._tag // => "UnknownSubcomand"
+ * unknownSubcommandError.subcommand // => "deplyo"
+ * unknownSubcommandError.parent // => ["myapp"]
  *
  * // In subcommand parsing
  * const parseSubcommand = (subcommand: string) =>
@@ -382,9 +370,12 @@ declare const UnknownSubcommand_base: Schema.Class<UnknownSubcommand, Schema.Tag
  *     }
  *     return subcommand
  *   })
+ *
+ * const parseError = await Effect.runPromise(Effect.flip(parseSubcommand("deplyo")))
+ * parseError._tag // => "UnknownSubcomand"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export declare class UnknownSubcommand extends UnknownSubcommand_base {
@@ -409,7 +400,7 @@ declare const UserError_base: Schema.Class<UserError, Schema.TaggedStruct<"UserE
  *
  * **Example** (Wrapping user errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -430,14 +421,16 @@ declare const UserError_base: Schema.Class<UserError, Schema.TaggedStruct<"UserE
  * // In error handling
  * const handleError = (error: CliError.CliError): Effect.Effect<number> => {
  *   if (error._tag === "UserError") {
- *     console.log("Command failed:", error.cause)
  *     return Effect.succeed(1) // Exit code 1
  *   }
  *   return Effect.succeed(0)
  * }
+ *
+ * await Effect.runPromise(deployCommand) // => { deployed: true }
+ * await Effect.runPromise(handleError(userError)) // => 1
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export declare class UserError extends UserError_base {
@@ -456,7 +449,7 @@ export declare class UserError extends UserError_base {
  * This excludes `ShowHelp` itself, allowing parse and validation errors to be
  * stored in `ShowHelp.errors` without nesting another help-control value.
  *
- * @category models
+ * @category schemas
  * @since 4.0.0
  */
 export declare const NonShowHelpErrors: Schema.Union<readonly [
@@ -478,7 +471,7 @@ export declare const NonShowHelpErrors: Schema.Union<readonly [
  * runner should display help along with the underlying parse or validation
  * failures.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export type NonShowHelpErrors = typeof NonShowHelpErrors.Type;
@@ -495,7 +488,7 @@ declare const ShowHelp_base: Schema.Class<ShowHelp, Schema.TaggedStruct<"ShowHel
  * that should be shown with help text. When `errors` is non-empty, the runtime
  * exit code is `1`; otherwise it is `0`.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export declare class ShowHelp extends ShowHelp_base {

package/dist/unstable/cli/CliError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CliError.d.ts","sourceRoot":"","sources":["../../../src/unstable/cli/CliError.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC;;;GAGG;AACH,QAAA,MAAM,MAAM,yBAAyB,CAAA;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,UAAU,MAAO,OAAO,KAAG,CAAC,IAAI,QAA4C,CAAA;AAEzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,QAAQ,GAChB,kBAAkB,GAClB,eAAe,GACf,aAAa,GACb,eAAe,GACf,kBAAkB,GAClB,YAAY,GACZ,iBAAiB,GACjB,QAAQ,GACR,SAAS,CAAA;;;;;;AAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,kBAAmB,SAAQ,uBAMtC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,0BAAS;IAE1B;;;;OAIG;IACH,IAAa,OAAO,WAQnB;CACF;;;;;;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,SAAQ,oBAMnC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,0BAAS;IAE1B;;;;OAIG;IACH,IAAa,OAAO,WAGnB;CACF;;;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,aAAc,SAAQ,kBAIjC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,0BAAS;IAE1B;;;;OAIG;IACH,IAAa,OAAO,WAEnB;CACF;;;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,eAAgB,SAAQ,oBAInC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,0BAAS;IAE1B;;;;OAIG;IACH,IAAa,OAAO,WAEnB;CACF;;;;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAmB,SAAQ,uBAItC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,0BAAS;IAE1B;;;;OAIG;IACH,IAAa,OAAO,WAGnB;CACF;;;;;;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,YAAa,SAAQ,iBAOhC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,0BAAS;IAE1B;;;;OAIG;IACH,IAAa,OAAO,WAWnB;CACF;;;;;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,iBAAkB,SAAQ,sBAMrC;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,0BAAS;IAE1B;;;;OAIG;IACH,IAAa,OAAO,WAOnB;CACF;;;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,SAAU,SAAQ,cAI7B;IACA;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,0BAAS;CAC3B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,KAAK,CAC1C,SAAS;IACP,OAAO,kBAAkB;IACzB,OAAO,eAAe;IACtB,OAAO,aAAa;IACpB,OAAO,eAAe;IACtB,OAAO,kBAAkB;IACzB,OAAO,YAAY;IACnB,OAAO,iBAAiB;IACxB,OAAO,SAAS;CACjB,CAUD,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAA;;;;;AAE7D;;;;;;;;;;;GAWG;AACH,qBAAa,QAAS,SAAQ,aAK5B;IACA,QAAQ,CAAC,CAAC,MAAM,CAAC,0BAAS;IAE1B,SAAkB,CAAC,OAAO,CAAC,aAAa,CAAC,SAA6B;IACtE,SAAkB,CAAC,OAAO,CAAC,aAAa,CAAC,SAAQ;IAEjD,IAAa,OAAO,WAEnB;CACF"}
+{"version":3,"file":"CliError.d.ts","sourceRoot":"","sources":["../../../src/unstable/cli/CliError.ts"],"names":[],"mappings":"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"}

package/dist/unstable/cli/CliError.js

@@ -23,26 +23,16 @@ const TypeId = "~effect/cli/CliError";
  *
  * **Example** (Checking CLI errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
- * const handleError = (error: unknown) => {
- *   if (CliError.isCliError(error)) {
- *     console.log("CLI Error:", error.message)
- *     return Effect.succeed("Handled CLI error")
- *   }
- *   return Effect.fail("Unknown error")
- * }
+ * const error = new CliError.MissingOption({ option: "api-key" })
+ * const program = CliError.isCliError(error)
+ *   ? Effect.succeed(error.message)
+ *   : Effect.fail("Unknown error")
  *
- * // Example usage in error handling
- * const program = Effect.gen(function*() {
- *   const result = yield* Effect.try({
- *     try: () => ({ success: true }),
- *     catch: (error) => error
- *   })
- *   handleError(result)
- * })
+ * await Effect.runPromise(program) // => "Missing required flag: --api-key"
  * ```
  *
  * @category guards
@@ -54,7 +44,7 @@ export const isCliError = u => Predicate.hasProperty(u, TypeId);
  *
  * **Example** (Creating unrecognized option errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -65,21 +55,21 @@ export const isCliError = u => Predicate.hasProperty(u, TypeId);
  *   suggestions: ["--verbose", "--force"]
  * })
  *
- * console.log(unrecognizedError.message)
- * // "Unrecognized flag: --unknown-flag in command deploy production
- * //
- * //  Did you mean this?
- * //    --verbose
- * //    --force"
+ * unrecognizedError._tag // => "UnrecognizedOption"
+ * unrecognizedError.option // => "--unknown-flag"
+ * unrecognizedError.command // => ["deploy", "production"]
  *
  * // In CLI parsing context
  * const parseCommand = Effect.gen(function*() {
  *   // If parsing encounters unknown flag
  *   return yield* unrecognizedError
  * })
+ *
+ * const parseError = await Effect.runPromise(Effect.flip(parseCommand))
+ * parseError._tag // => "UnrecognizedOption"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class UnrecognizedOption extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId}/UnrecognizedOption`)("UnrecognizedOption", {
@@ -109,7 +99,7 @@ export class UnrecognizedOption extends /*#__PURE__*/Schema.TaggedErrorClass(`${
  *
  * **Example** (Creating duplicate option errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { CliError } from "effect/unstable/cli"
  *
  * const duplicateError = new CliError.DuplicateOption({
@@ -118,12 +108,13 @@ export class UnrecognizedOption extends /*#__PURE__*/Schema.TaggedErrorClass(`${
  *   childCommand: "deploy"
  * })
  *
- * console.log(duplicateError.message)
- * // "Duplicate flag name "--verbose" in parent command "myapp" and subcommand "deploy".
- * // Parent will always claim this flag (Mode A semantics). Consider renaming one of them to avoid confusion."
+ * duplicateError._tag // => "DuplicateOption"
+ * duplicateError.option // => "--verbose"
+ * duplicateError.parentCommand // => "myapp"
+ * duplicateError.childCommand // => "deploy"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class DuplicateOption extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId}/DuplicateOption`)("DuplicateOption", {
@@ -151,7 +142,7 @@ export class DuplicateOption extends /*#__PURE__*/Schema.TaggedErrorClass(`${Typ
  *
  * **Example** (Creating missing option errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -159,8 +150,7 @@ export class DuplicateOption extends /*#__PURE__*/Schema.TaggedErrorClass(`${Typ
  *   option: "api-key"
  * })
  *
- * console.log(missingOptionError.message)
- * // "Missing required flag: --api-key"
+ * const details = [missingOptionError._tag, missingOptionError.option] // => ["MissingOption", "api-key"]
  *
  * // In validation context
  * const validateRequiredOptions = (options: Record<string, string | undefined>) =>
@@ -171,9 +161,12 @@ export class DuplicateOption extends /*#__PURE__*/Schema.TaggedErrorClass(`${Typ
  *     }
  *     return apiKey
  *   })
+ *
+ * const validationError = await Effect.runPromise(Effect.flip(validateRequiredOptions({})))
+ * validationError._tag // => "MissingOption"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class MissingOption extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId}/MissingOption`)("MissingOption", {
@@ -199,7 +192,7 @@ export class MissingOption extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeI
  *
  * **Example** (Creating missing argument errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -207,8 +200,7 @@ export class MissingOption extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeI
  *   argument: "target"
  * })
  *
- * console.log(missingArgError.message)
- * // "Missing required argument: target"
+ * const details = [missingArgError._tag, missingArgError.argument] // => ["MissingArgument", "target"]
  *
  * // In argument parsing
  * const parseArguments = (args: Array<string>) =>
@@ -218,9 +210,12 @@ export class MissingOption extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeI
  *     }
  *     return args[0]
  *   })
+ *
+ * const parseError = await Effect.runPromise(Effect.flip(parseArguments([])))
+ * parseError._tag // => "MissingArgument"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class MissingArgument extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId}/MissingArgument`)("MissingArgument", {
@@ -247,18 +242,17 @@ export class MissingArgument extends /*#__PURE__*/Schema.TaggedErrorClass(`${Typ
  *
  * **Example** (Reporting unexpected arguments)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { CliError } from "effect/unstable/cli"
  *
  * const error = new CliError.UnexpectedArgument({
  *   arguments: ["extra.txt"]
  * })
  *
- * console.log(error.message)
- * // "Unexpected positional argument: \"extra.txt\""
+ * const details = [error._tag, error.arguments] // => ["UnexpectedArgument", ["extra.txt"]]
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class UnexpectedArgument extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId}/UnexpectedArgument`)("UnexpectedArgument", {
@@ -285,8 +279,7 @@ export class UnexpectedArgument extends /*#__PURE__*/Schema.TaggedErrorClass(`${
  *
  * **Example** (Creating invalid value errors)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
  * import { CliError } from "effect/unstable/cli"
  *
  * const invalidValueError = new CliError.InvalidValue({
@@ -296,8 +289,10 @@ export class UnexpectedArgument extends /*#__PURE__*/Schema.TaggedErrorClass(`${
  *   kind: "flag"
  * })
  *
- * console.log(invalidValueError.message)
- * // "Invalid value for flag --port: "abc123". Expected: integer between 1 and 65535"
+ * invalidValueError._tag // => "InvalidValue"
+ * invalidValueError.kind // => "flag"
+ * invalidValueError.option // => "port"
+ * invalidValueError.value // => "abc123"
  *
  * // For positional arguments
  * const invalidArgError = new CliError.InvalidValue({
@@ -307,11 +302,10 @@ export class UnexpectedArgument extends /*#__PURE__*/Schema.TaggedErrorClass(`${
  *   kind: "argument"
  * })
  *
- * console.log(invalidArgError.message)
- * // "Invalid value for argument <count>: "abc". Expected: integer"
+ * const details = [invalidArgError.kind, invalidArgError.option, invalidArgError.value] // => ["argument", "count", "abc"]
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class InvalidValue extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId}/InvalidValue`)("InvalidValue", {
@@ -347,7 +341,7 @@ export class InvalidValue extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId
  *
  * **Example** (Creating unknown subcommand errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -357,12 +351,9 @@ export class InvalidValue extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId
  *   suggestions: ["deploy", "destroy"]
  * })
  *
- * console.log(unknownSubcommandError.message)
- * // "Unknown subcommand "deplyo" for "myapp"
- * //
- * //  Did you mean this?
- * //    deploy
- * //    destroy"
+ * unknownSubcommandError._tag // => "UnknownSubcomand"
+ * unknownSubcommandError.subcommand // => "deplyo"
+ * unknownSubcommandError.parent // => ["myapp"]
  *
  * // In subcommand parsing
  * const parseSubcommand = (subcommand: string) =>
@@ -373,9 +364,12 @@ export class InvalidValue extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId
  *     }
  *     return subcommand
  *   })
+ *
+ * const parseError = await Effect.runPromise(Effect.flip(parseSubcommand("deplyo")))
+ * parseError._tag // => "UnknownSubcomand"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class UnknownSubcommand extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId}/UnknownSubcommand`)("UnknownSubcomand", {
@@ -404,7 +398,7 @@ export class UnknownSubcommand extends /*#__PURE__*/Schema.TaggedErrorClass(`${T
  *
  * **Example** (Wrapping user errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -425,14 +419,16 @@ export class UnknownSubcommand extends /*#__PURE__*/Schema.TaggedErrorClass(`${T
  * // In error handling
  * const handleError = (error: CliError.CliError): Effect.Effect<number> => {
  *   if (error._tag === "UserError") {
- *     console.log("Command failed:", error.cause)
  *     return Effect.succeed(1) // Exit code 1
  *   }
  *   return Effect.succeed(0)
  * }
+ *
+ * await Effect.runPromise(deployCommand) // => { deployed: true }
+ * await Effect.runPromise(handleError(userError)) // => 1
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class UserError extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId}/UserError`)("UserError", {
@@ -453,7 +449,7 @@ export class UserError extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId}/U
  * This excludes `ShowHelp` itself, allowing parse and validation errors to be
  * stored in `ShowHelp.errors` without nesting another help-control value.
  *
- * @category models
+ * @category schemas
  * @since 4.0.0
  */
 export const NonShowHelpErrors = /*#__PURE__*/Schema.Union([UnrecognizedOption, DuplicateOption, MissingOption, MissingArgument, UnexpectedArgument, InvalidValue, UnknownSubcommand, UserError]);
@@ -466,7 +462,7 @@ export const NonShowHelpErrors = /*#__PURE__*/Schema.Union([UnrecognizedOption,
  * that should be shown with help text. When `errors` is non-empty, the runtime
  * exit code is `1`; otherwise it is `0`.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class ShowHelp extends /*#__PURE__*/Schema.TaggedErrorClass(`${TypeId}/ShowHelp`)("ShowHelp", {