effect 4.0.5 → 4.0.7

package/dist/cli/Argument.js.map

@@ -1 +1 @@
-{"version":3,"file":"Argument.js","names":[],"sources":["../../src/cli/Argument.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"Argument.js","names":[],"sources":["../../src/cli/Argument.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/cli/CliError.d.ts

@@ -28,6 +28,77 @@ declare const TypeId = "~effect/cli/CliError";
  * @since 4.0.0
  */
 export declare const isCliError: (u: unknown) => u is CliError;
+/**
+ * Defines the string property key used to give an object error a user-facing
+ * message.
+ *
+ * **When to use**
+ *
+ * Use to type the property key that marks handler failures for rendering by
+ * `Command.run`.
+ *
+ * @stability unstable
+ * @category annotations
+ * @since 4.0.0
+ */
+export type userMessage = "~effect/cli/CliError/userMessage";
+/**
+ * Defines the runtime property key used to give an object error a user-facing
+ * message.
+ *
+ * **When to use**
+ *
+ * Use when a handler fails with a domain error that should be shown to the
+ * user without wrapping it in {@link UserError}.
+ *
+ * **Details**
+ *
+ * When a handler failure has a string `[CliError.userMessage]`, `Command.run`
+ * renders it with the installed formatter, sets `Runtime.errorReported` to
+ * `false`, and rethrows the original error, so its tag is preserved. The
+ * global `Error` interface declares this key as an optional string.
+ *
+ * **Example** (Rendering a tagged handler failure)
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import { CliError } from "effect/cli"
+ *
+ * class Occupied extends Schema.TaggedError<Occupied>()("Occupied", {
+ *   path: Schema.String
+ * }) {
+ *   override get [CliError.userMessage]() {
+ *     return `${this.path} already exists`
+ *   }
+ * }
+ *
+ * const error = new Occupied({ path: "config.yaml" })
+ * CliError.getUserMessage(error) // => "config.yaml already exists"
+ * ```
+ *
+ * @see {@link getUserMessage} for reading the message stored under this key
+ *
+ * @stability unstable
+ * @category annotations
+ * @since 4.0.0
+ */
+export declare const userMessage: userMessage;
+declare global {
+    interface Error {
+        readonly [userMessage]?: string;
+    }
+}
+/**
+ * Reads the `CliError.userMessage` annotation from an error object, returning
+ * `undefined` when it is unset or not a string.
+ *
+ * @see {@link userMessage} for the annotation key this getter reads
+ *
+ * @stability unstable
+ * @category annotations
+ * @since 4.0.0
+ */
+export declare const getUserMessage: (error: object) => string | undefined;
 /**
  * Union type representing all possible CLI error conditions.
  *
@@ -58,7 +129,7 @@ export declare const isCliError: (u: unknown) => u is CliError;
  * @category errors
  * @since 4.0.0
  */
-export type CliError = UnrecognizedOption | DuplicateOption | MissingOption | MissingArgument | UnexpectedArgument | InvalidValue | UnknownSubcommand | ShowHelp | UserError;
+export type CliError = UnrecognizedOption | DuplicateOption | MissingOption | MissingArgument | UnexpectedArgument | InvalidValue | UnknownSubcommand | ValidationError | ShowHelp | UserError;
 declare const UnrecognizedOption_base: Schema.Class<UnrecognizedOption, Schema.TaggedStruct<"UnrecognizedOption", {
     readonly option: Schema.String;
     readonly command: Schema.optional<Schema.$Array<Schema.String>>;
@@ -416,6 +487,45 @@ export declare class UnknownSubcommand extends UnknownSubcommand_base {
      */
     get message(): string;
 }
+declare const ValidationError_base: Schema.Class<ValidationError, Schema.TaggedStruct<"ValidationError", {
+    readonly message: Schema.String;
+}>, import("../Cause.ts").YieldableError>;
+/**
+ * Error for parsed input that fails a rule of your own, such as two flags
+ * that cannot be used together.
+ *
+ * **Details**
+ *
+ * Fail with it from `Command.validate`, `Flag.mapEffect` or
+ * `Argument.mapEffect`. The runner shows it with the command help, like any
+ * other parse error. Handlers report their own failures with `UserError`.
+ *
+ * **Example** (Rejecting a flag combination)
+ *
+ * ```ts import.meta.vitest
+ * import { CliError } from "effect/cli"
+ *
+ * const error = new CliError.ValidationError({
+ *   message: "--use-api and --use-docker are mutually exclusive"
+ * })
+ *
+ * error._tag // => "ValidationError"
+ * error.message // => "--use-api and --use-docker are mutually exclusive"
+ * ```
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.0
+ */
+export declare class ValidationError extends ValidationError_base {
+    /**
+     * Marks this value as a CLI validation error for runtime guards.
+     *
+     * @stability unstable
+     * @since 4.1.0
+     */
+    readonly [TypeId] = "~effect/cli/CliError";
+}
 declare const UserError_base: Schema.Class<UserError, Schema.TaggedStruct<"UserError", {
     readonly cause: Schema.Defect;
     readonly userMessage: Schema.optionalKey<Schema.String>;
@@ -489,6 +599,13 @@ export declare class UserError extends UserError_base {
      * @since 4.0.0
      */
     get message(): string;
+    /**
+     * Exposes `message` as the user-facing message rendered by `Command.run`.
+     *
+     * @stability unstable
+     * @since 4.0.0
+     */
+    get [userMessage](): string;
 }
 /**
  * Schema for concrete CLI errors that can be reported together with help output.
@@ -510,6 +627,7 @@ export declare const NonShowHelpErrors: Schema.Union<readonly [
     typeof UnexpectedArgument,
     typeof InvalidValue,
     typeof UnknownSubcommand,
+    typeof ValidationError,
     typeof UserError
 ]>;
 /**
@@ -528,7 +646,7 @@ export declare const NonShowHelpErrors: Schema.Union<readonly [
 export type NonShowHelpErrors = typeof NonShowHelpErrors.Type;
 declare const ShowHelp_base: Schema.Class<ShowHelp, Schema.TaggedStruct<"ShowHelp", {
     readonly commandPath: Schema.$Array<Schema.String>;
-    readonly errors: Schema.$Array<Schema.Union<readonly [typeof UnrecognizedOption, typeof DuplicateOption, typeof MissingOption, typeof MissingArgument, typeof UnexpectedArgument, typeof InvalidValue, typeof UnknownSubcommand, typeof UserError]>>;
+    readonly errors: Schema.$Array<Schema.Union<readonly [typeof UnrecognizedOption, typeof DuplicateOption, typeof MissingOption, typeof MissingArgument, typeof UnexpectedArgument, typeof InvalidValue, typeof UnknownSubcommand, typeof ValidationError, typeof UserError]>>;
 }>, import("../Cause.ts").YieldableError>;
 /**
  * Error data requesting CLI help rendering for a command path.

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

@@ -1 +1 @@
-{"version":3,"file":"CliError.d.ts","sourceRoot":"","sources":["../../src/cli/CliError.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CliError.d.ts","sourceRoot":"","sources":["../../src/cli/CliError.ts"],"names":[],"mappings":"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"}

package/dist/cli/CliError.js

@@ -3,10 +3,12 @@
  *
  * CLI errors describe problems such as unknown or duplicate flags, missing
  * flags or arguments, unexpected positional arguments, invalid values, unknown
- * subcommands, user handler failures, and requests to show command help. This
- * module includes the `CliError` union, the `isCliError` guard, schema-backed
- * error classes with display messages, and the `NonShowHelpErrors` union used
- * when parse or validation errors should be shown with help output.
+ * subcommands, rejected input combinations, user handler failures, and
+ * requests to show command help. This module includes the `CliError` union,
+ * the `isCliError` guard, the `userMessage` annotation for rendering handler
+ * failures, schema-backed error classes with display messages, and the
+ * `NonShowHelpErrors` union used when parse or validation errors should be
+ * shown with help output.
  *
  * @stability unstable
  * @since 4.0.0
@@ -42,6 +44,58 @@ const TypeId = "~effect/cli/CliError";
  * @since 4.0.0
  */
 export const isCliError = u => Predicate.hasProperty(u, TypeId);
+/**
+ * Defines the runtime property key used to give an object error a user-facing
+ * message.
+ *
+ * **When to use**
+ *
+ * Use when a handler fails with a domain error that should be shown to the
+ * user without wrapping it in {@link UserError}.
+ *
+ * **Details**
+ *
+ * When a handler failure has a string `[CliError.userMessage]`, `Command.run`
+ * renders it with the installed formatter, sets `Runtime.errorReported` to
+ * `false`, and rethrows the original error, so its tag is preserved. The
+ * global `Error` interface declares this key as an optional string.
+ *
+ * **Example** (Rendering a tagged handler failure)
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import { CliError } from "effect/cli"
+ *
+ * class Occupied extends Schema.TaggedError<Occupied>()("Occupied", {
+ *   path: Schema.String
+ * }) {
+ *   override get [CliError.userMessage]() {
+ *     return `${this.path} already exists`
+ *   }
+ * }
+ *
+ * const error = new Occupied({ path: "config.yaml" })
+ * CliError.getUserMessage(error) // => "config.yaml already exists"
+ * ```
+ *
+ * @see {@link getUserMessage} for reading the message stored under this key
+ *
+ * @stability unstable
+ * @category annotations
+ * @since 4.0.0
+ */
+export const userMessage = "~effect/cli/CliError/userMessage";
+/**
+ * Reads the `CliError.userMessage` annotation from an error object, returning
+ * `undefined` when it is unset or not a string.
+ *
+ * @see {@link userMessage} for the annotation key this getter reads
+ *
+ * @stability unstable
+ * @category annotations
+ * @since 4.0.0
+ */
+export const getUserMessage = error => userMessage in error && typeof error[userMessage] === "string" ? error[userMessage] : undefined;
 /**
  * Error thrown when an unrecognized option is encountered.
  *
@@ -417,6 +471,44 @@ export class UnknownSubcommand extends /*#__PURE__*/Schema.TaggedError(`${TypeId
     return this.parent ? `Unknown subcommand "${this.subcommand}" for "${this.parent.join(" ")}"${suggestionText}` : `Unknown subcommand "${this.subcommand}"${suggestionText}`;
   }
 }
+/**
+ * Error for parsed input that fails a rule of your own, such as two flags
+ * that cannot be used together.
+ *
+ * **Details**
+ *
+ * Fail with it from `Command.validate`, `Flag.mapEffect` or
+ * `Argument.mapEffect`. The runner shows it with the command help, like any
+ * other parse error. Handlers report their own failures with `UserError`.
+ *
+ * **Example** (Rejecting a flag combination)
+ *
+ * ```ts import.meta.vitest
+ * import { CliError } from "effect/cli"
+ *
+ * const error = new CliError.ValidationError({
+ *   message: "--use-api and --use-docker are mutually exclusive"
+ * })
+ *
+ * error._tag // => "ValidationError"
+ * error.message // => "--use-api and --use-docker are mutually exclusive"
+ * ```
+ *
+ * @stability unstable
+ * @category errors
+ * @since 4.1.0
+ */
+export class ValidationError extends /*#__PURE__*/Schema.TaggedError(`${TypeId}/ValidationError`)("ValidationError", {
+  message: Schema.String
+}) {
+  /**
+   * Marks this value as a CLI validation error for runtime guards.
+   *
+   * @stability unstable
+   * @since 4.1.0
+   */
+  [TypeId] = TypeId;
+}
 /**
  * Error wrapper for user handler failures in the CLI error channel.
  *
@@ -494,6 +586,15 @@ export class UserError extends /*#__PURE__*/Schema.TaggedError(`${TypeId}/UserEr
     if (this.cause instanceof Error && this.cause.message) return this.cause.message;
     return "An error occurred";
   }
+  /**
+   * Exposes `message` as the user-facing message rendered by `Command.run`.
+   *
+   * @stability unstable
+   * @since 4.0.0
+   */
+  get [userMessage]() {
+    return this.message;
+  }
 }
 /**
  * Schema for concrete CLI errors that can be reported together with help output.
@@ -507,7 +608,7 @@ export class UserError extends /*#__PURE__*/Schema.TaggedError(`${TypeId}/UserEr
  * @category schemas
  * @since 4.0.0
  */
-export const NonShowHelpErrors = /*#__PURE__*/Schema.Union([UnrecognizedOption, DuplicateOption, MissingOption, MissingArgument, UnexpectedArgument, InvalidValue, UnknownSubcommand, UserError]);
+export const NonShowHelpErrors = /*#__PURE__*/Schema.Union([UnrecognizedOption, DuplicateOption, MissingOption, MissingArgument, UnexpectedArgument, InvalidValue, UnknownSubcommand, ValidationError, UserError]);
 /**
  * Error data requesting CLI help rendering for a command path.
  *

package/dist/cli/CliError.js.map

@@ -1 +1 @@
-{"version":3,"file":"CliError.js","names":[],"sources":["../../src/cli/CliError.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"CliError.js","names":[],"sources":["../../src/cli/CliError.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/cli/CliOutput.d.ts

@@ -1,16 +1,16 @@
 /**
- * Formats CLI help and errors as text.
+ * Formats and presents CLI help, errors, and version information.
  *
- * This module turns help documents, CLI errors, grouped errors, and version
- * information into strings. It does not write those strings to the terminal
- * itself. It includes the `Formatter` interface, the formatter service, a layer
- * for custom formatters, and the default formatter with configurable color
- * support.
+ * The `Formatter` service turns help documents, errors, and version
+ * information into strings. The `Presenter` service decides where the built-in
+ * help, version, and invalid-invocation output of `Command.runWith` is written,
+ * and can be replaced to suppress or redirect it.
  *
  * @stability unstable
  * @since 4.0.0
  */
 import * as Context from "../Context.ts";
+import * as Effect from "../Effect.ts";
 import * as Layer from "../Layer.ts";
 import type * as CliError from "./CliError.ts";
 import type { HelpDoc } from "./HelpDoc.ts";
@@ -196,6 +196,119 @@ export interface Formatter {
      */
     readonly formatErrors: (errors: ReadonlyArray<CliError.CliError>) => string;
 }
+/**
+ * Presents the built-in help, version, and invalid-invocation output of
+ * `Command.runWith`.
+ *
+ * **When to use**
+ *
+ * Use to suppress, redirect, or replace that output, for example to keep
+ * stdout clean for machine-readable results.
+ *
+ * **Details**
+ *
+ * Events carry the help document and errors rather than rendered text, so a
+ * presenter can still render them with the `Formatter` service. Presenting an
+ * event does not change the result of the run: implicit help and invalid
+ * invocations still fail with `CliError.ShowHelp`.
+ *
+ * **Gotchas**
+ *
+ * `--completions` scripts, wizard mode output, and handler failures rendered
+ * through `CliError.userMessage` do not go through the presenter.
+ *
+ * **Example** (Writing invalid-invocation output to stderr)
+ *
+ * ```ts import.meta.vitest
+ * import { Console, Effect } from "effect"
+ * import { CliOutput } from "effect/cli"
+ *
+ * const StderrPresenter = CliOutput.layerPresenter({
+ *   present: (event) =>
+ *     event._tag === "InvalidInvocation"
+ *       ? Effect.gen(function*() {
+ *         const formatter = yield* CliOutput.Formatter
+ *         yield* Console.error(formatter.formatHelpDoc(event.helpDoc))
+ *         yield* Console.error(formatter.formatErrors(event.errors))
+ *       })
+ *       : CliOutput.defaultPresenter.present(event)
+ * })
+ * ```
+ *
+ * @see {@link defaultPresenter} for the default console output
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Presenter {
+    /**
+     * Presents a CLI output event.
+     *
+     * @stability unstable
+     * @since 4.0.0
+     */
+    readonly present: (event: Presenter.Event) => Effect.Effect<void>;
+}
+/**
+ * Types used by the `Presenter` service.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+export declare namespace Presenter {
+    /**
+     * Output events produced while running a CLI command.
+     *
+     * @stability unstable
+     * @category models
+     * @since 4.0.0
+     */
+    type Event = Help | InvalidInvocation | Version;
+    /**
+     * Help for a command path.
+     *
+     * **Details**
+     *
+     * `reason` is `"Requested"` for `--help`, and `"Implicit"` when the run
+     * fails with a `CliError.ShowHelp` that carries no errors, such as selecting
+     * a command that has no handler, or when `renderErrors` is `false`.
+     *
+     * @stability unstable
+     * @category models
+     * @since 4.0.0
+     */
+    interface Help {
+        readonly _tag: "Help";
+        readonly reason: "Requested" | "Implicit";
+        readonly commandPath: ReadonlyArray<string>;
+        readonly helpDoc: HelpDoc;
+    }
+    /**
+     * Help and parse or validation errors for an invalid invocation.
+     *
+     * @stability unstable
+     * @category models
+     * @since 4.0.0
+     */
+    interface InvalidInvocation {
+        readonly _tag: "InvalidInvocation";
+        readonly commandPath: ReadonlyArray<string>;
+        readonly helpDoc: HelpDoc;
+        readonly errors: ReadonlyArray<CliError.NonShowHelpErrors>;
+    }
+    /**
+     * Version information requested with `--version`.
+     *
+     * @stability unstable
+     * @category models
+     * @since 4.0.0
+     */
+    interface Version {
+        readonly _tag: "Version";
+        readonly name: string;
+        readonly version: string;
+    }
+}
 /**
  * Service reference for the CLI output formatter. Provides a default implementation
  * that can be overridden for custom formatting or testing.
@@ -225,6 +338,33 @@ export interface Formatter {
  * @since 4.0.0
  */
 export declare const Formatter: Context.Reference<Formatter>;
+/**
+ * Default presenter that renders events with the current `Formatter` and
+ * writes them with `Console`.
+ *
+ * **Details**
+ *
+ * Help and version output goes to `Console.log`. Invalid invocations write
+ * help to `Console.log` and errors to `Console.error`. When no `Formatter` is
+ * installed, the default formatter colors output when `TerminalCapabilities`
+ * says it can.
+ *
+ * @see {@link Presenter} for replacing the default output
+ * @stability unstable
+ * @category defaults
+ * @since 4.0.0
+ */
+export declare const defaultPresenter: Presenter;
+/**
+ * Service reference for the CLI output presenter. Defaults to
+ * `defaultPresenter`.
+ *
+ * @see {@link layerPresenter} for providing a custom presenter
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export declare const Presenter: Context.Reference<Presenter>;
 /**
  * Creates a Layer that provides a custom Formatter implementation.
  *
@@ -254,6 +394,15 @@ export declare const Formatter: Context.Reference<Formatter>;
  * @since 4.0.0
  */
 export declare const layer: (formatter: Formatter) => Layer.Layer<never>;
+/**
+ * Creates a Layer that provides a custom Presenter implementation.
+ *
+ * @see {@link Presenter} for the events a presenter receives
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export declare const layerPresenter: (presenter: Presenter) => Layer.Layer<never>;
 /**
  * Creates a default formatter with configurable options.
  *

package/dist/cli/CliOutput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CliOutput.d.ts","sourceRoot":"","sources":["../../src/cli/CliOutput.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,OAAO,MAAM,eAAe,CAAA;AACxC,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AAEpC,OAAO,KAAK,KAAK,QAAQ,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAG3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAA;IAEhD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,KAAK,MAAM,CAAA;IAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,KAAK,MAAM,CAAA;IAE1D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IAEjE;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAA;CAC5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,SAAS,CAGlD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,KAAK,cAAe,SAAS,KAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAwC,CAAA;AAOtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,gBAAgB,aAAc;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,KAAG,SA+DjE,CAAA;AA8CD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,MAM3C,CAAA"}
+{"version":3,"file":"CliOutput.d.ts","sourceRoot":"","sources":["../../src/cli/CliOutput.ts"],"names":[],"mappings":"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"}

package/dist/cli/CliOutput.js

@@ -1,19 +1,21 @@
 /**
- * Formats CLI help and errors as text.
+ * Formats and presents CLI help, errors, and version information.
  *
- * This module turns help documents, CLI errors, grouped errors, and version
- * information into strings. It does not write those strings to the terminal
- * itself. It includes the `Formatter` interface, the formatter service, a layer
- * for custom formatters, and the default formatter with configurable color
- * support.
+ * The `Formatter` service turns help documents, errors, and version
+ * information into strings. The `Presenter` service decides where the built-in
+ * help, version, and invalid-invocation output of `Command.runWith` is written,
+ * and can be replaced to suppress or redirect it.
  *
  * @stability unstable
  * @since 4.0.0
  */
+import * as Console from "../Console.js";
 import * as Context from "../Context.js";
+import * as Effect from "../Effect.js";
 import * as Layer from "../Layer.js";
 import * as Option from "../Option.js";
 import * as Ansi from "./internal/ansi.js";
+import * as TerminalCapabilities from "./TerminalCapabilities.js";
 /**
  * Service reference for the CLI output formatter. Provides a default implementation
  * that can be overridden for custom formatting or testing.
@@ -45,6 +47,51 @@ import * as Ansi from "./internal/ansi.js";
 export const Formatter = /*#__PURE__*/Context.Reference("effect/cli/CliOutput", {
   defaultValue: () => defaultFormatter()
 });
+/**
+ * Default presenter that renders events with the current `Formatter` and
+ * writes them with `Console`.
+ *
+ * **Details**
+ *
+ * Help and version output goes to `Console.log`. Invalid invocations write
+ * help to `Console.log` and errors to `Console.error`. When no `Formatter` is
+ * installed, the default formatter colors output when `TerminalCapabilities`
+ * says it can.
+ *
+ * @see {@link Presenter} for replacing the default output
+ * @stability unstable
+ * @category defaults
+ * @since 4.0.0
+ */
+export const defaultPresenter = {
+  present: /*#__PURE__*/Effect.fnUntraced(function* (event) {
+    const context = yield* Effect.context();
+    const formatter = Context.getOrUndefined(context, Formatter) ?? defaultFormatter({
+      colors: Context.get(context, TerminalCapabilities.TerminalCapabilities).canColor
+    });
+    switch (event._tag) {
+      case "Help":
+        return yield* Console.log(formatter.formatHelpDoc(event.helpDoc));
+      case "InvalidInvocation":
+        yield* Console.log(formatter.formatHelpDoc(event.helpDoc));
+        return yield* Console.error(formatter.formatErrors(event.errors));
+      case "Version":
+        return yield* Console.log(formatter.formatVersion(event.name, event.version));
+    }
+  })
+};
+/**
+ * Service reference for the CLI output presenter. Defaults to
+ * `defaultPresenter`.
+ *
+ * @see {@link layerPresenter} for providing a custom presenter
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export const Presenter = /*#__PURE__*/Context.Reference("effect/cli/CliOutput/Presenter", {
+  defaultValue: () => defaultPresenter
+});
 /**
  * Creates a Layer that provides a custom Formatter implementation.
  *
@@ -74,6 +121,15 @@ export const Formatter = /*#__PURE__*/Context.Reference("effect/cli/CliOutput",
  * @since 4.0.0
  */
 export const layer = formatter => Layer.succeed(Formatter)(formatter);
+/**
+ * Creates a Layer that provides a custom Presenter implementation.
+ *
+ * @see {@link Presenter} for the events a presenter receives
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerPresenter = presenter => Layer.succeed(Presenter)(presenter);
 const escapeControlCharacters = text =>
 // oxlint-disable-next-line no-control-regex
 text.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, character => `\\x${character.charCodeAt(0).toString(16).padStart(2, "0")}`);