effect 4.0.5 → 4.0.6

package/src/cli/CliError.ts

@@ -3,10 +3,11 @@
  *
  * 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, 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
@@ -83,6 +84,7 @@ export type CliError =
   | UnexpectedArgument
   | InvalidValue
   | UnknownSubcommand
+  | ValidationError
   | ShowHelp
   | UserError
 
@@ -500,6 +502,47 @@ export class UnknownSubcommand extends Schema.TaggedError<UnknownSubcommand>(
   }
 }
 
+/**
+ * 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 Schema.TaggedError<ValidationError>(
+  `${TypeId}/ValidationError`
+)("ValidationError", {
+  message: Schema.String
+}) {
+  /**
+   * Marks this value as a CLI validation error for runtime guards.
+   *
+   * @stability unstable
+   * @since 4.1.0
+   */
+  readonly [TypeId] = TypeId
+}
+
 /**
  * Error wrapper for user handler failures in the CLI error channel.
  *
@@ -604,6 +647,7 @@ export const NonShowHelpErrors: Schema.Union<
     typeof UnexpectedArgument,
     typeof InvalidValue,
     typeof UnknownSubcommand,
+    typeof ValidationError,
     typeof UserError
   ]
 > = Schema.Union([
@@ -614,6 +658,7 @@ export const NonShowHelpErrors: Schema.Union<
   UnexpectedArgument,
   InvalidValue,
   UnknownSubcommand,
+  ValidationError,
   UserError
 ])
 

package/src/cli/Command.ts

@@ -30,10 +30,10 @@ import * as Terminal from "../Terminal.ts"
 import type { Contravariant, Covariant, NoInfer, Simplify } from "../Types.ts"
 import * as CliConfig from "./CliConfig.ts"
 import * as CliError from "./CliError.ts"
-import * as CliOutput from "./CliOutput.ts"
 import * as GlobalFlag from "./GlobalFlag.ts"
 import { checkForDuplicateFlags, makeCommand, makeParser, toImpl, TypeId } from "./internal/command.ts"
 import { mergeConfig, parseConfig } from "./internal/config.ts"
+import { resolveFormatter } from "./internal/formatter.ts"
 import { getGlobalFlagsForCommandPath, getGlobalFlagsForCommandTree, getHelpForCommandPath } from "./internal/help.ts"
 import * as Lexer from "./internal/lexer.ts"
 import * as Parser from "./internal/parser.ts"
@@ -1121,6 +1121,247 @@ export const withHandler: {
 ): Command<Name, A, ContextInput, E, Exclude<R, BuiltInSettingContext>> =>
   makeCommand({ ...toImpl(self), handle: handler } as any))
 
+/**
+ * Validates the parsed input of a command before the handler runs.
+ *
+ * **Details**
+ *
+ * Use this for rules that involve several flags or arguments, such as
+ * mutually exclusive flags. The validation receives the same input as the
+ * handler, with defaults, prompts and the wizard already applied. A failure
+ * is shown with the command help, like a parse error, and the handler does
+ * not run. Fail with `CliError.ValidationError` to supply the message, or
+ * with any other `CliError`. Validations run in the order they were added and
+ * stop at the first failure. Adding a handler later with `withHandler` keeps
+ * them.
+ *
+ * A validation sees only the input that exists where it is applied. Add it
+ * after `withSharedFlags` to see the shared flags. Added after
+ * `withSubcommands`, it also runs when a subcommand is selected, with the
+ * parent's shared flags as input.
+ *
+ * **Example** (Rejecting mutually exclusive flags)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
+ * import { CliError, Command, Flag } from "effect/cli"
+ * import { ChildProcessSpawner } from "effect/process"
+ * import { TestConsole } from "effect/testing"
+ *
+ * const CliTestLayer = Layer.mergeAll(
+ *   FileSystem.layerNoop({}),
+ *   Path.layer,
+ *   Stdio.layerTest({}),
+ *   TestConsole.layer,
+ *   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 download = Command.make("download", {
+ *   useApi: Flag.Boolean("use-api").pipe(Flag.withDefault(false)),
+ *   useDocker: Flag.Boolean("use-docker").pipe(Flag.withDefault(false))
+ * }, () => Effect.void).pipe(
+ *   Command.validate(({ useApi, useDocker }) =>
+ *     useApi && useDocker
+ *       ? Effect.fail(
+ *         new CliError.ValidationError({
+ *           message: "--use-api and --use-docker are mutually exclusive"
+ *         })
+ *       )
+ *       : Effect.void
+ *   )
+ * )
+ *
+ * const error = await Effect.runPromise(
+ *   Command.runWith(download, { version: "1.0.0" })(["--use-api", "--use-docker"]).pipe(
+ *     Effect.flip,
+ *     Effect.provide(CliTestLayer)
+ *   )
+ * )
+ * error._tag // => "ShowHelp"
+ * error.errors[0].message // => "--use-api and --use-docker are mutually exclusive"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const validate: {
+  /**
+   * Validates the parsed input of a command before the handler runs.
+   *
+   * **Details**
+   *
+   * Use this for rules that involve several flags or arguments, such as
+   * mutually exclusive flags. The validation receives the same input as the
+   * handler, with defaults, prompts and the wizard already applied. A failure
+   * is shown with the command help, like a parse error, and the handler does
+   * not run. Fail with `CliError.ValidationError` to supply the message, or
+   * with any other `CliError`. Validations run in the order they were added and
+   * stop at the first failure. Adding a handler later with `withHandler` keeps
+   * them.
+   *
+   * A validation sees only the input that exists where it is applied. Add it
+   * after `withSharedFlags` to see the shared flags. Added after
+   * `withSubcommands`, it also runs when a subcommand is selected, with the
+   * parent's shared flags as input.
+   *
+   * **Example** (Rejecting mutually exclusive flags)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
+   * import { CliError, Command, Flag } from "effect/cli"
+   * import { ChildProcessSpawner } from "effect/process"
+   * import { TestConsole } from "effect/testing"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   TestConsole.layer,
+   *   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 download = Command.make("download", {
+   *   useApi: Flag.Boolean("use-api").pipe(Flag.withDefault(false)),
+   *   useDocker: Flag.Boolean("use-docker").pipe(Flag.withDefault(false))
+   * }, () => Effect.void).pipe(
+   *   Command.validate(({ useApi, useDocker }) =>
+   *     useApi && useDocker
+   *       ? Effect.fail(
+   *         new CliError.ValidationError({
+   *           message: "--use-api and --use-docker are mutually exclusive"
+   *         })
+   *       )
+   *       : Effect.void
+   *   )
+   * )
+   *
+   * const error = await Effect.runPromise(
+   *   Command.runWith(download, { version: "1.0.0" })(["--use-api", "--use-docker"]).pipe(
+   *     Effect.flip,
+   *     Effect.provide(CliTestLayer)
+   *   )
+   * )
+   * error._tag // => "ShowHelp"
+   * error.errors[0].message // => "--use-api and --use-docker are mutually exclusive"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <Input>(f: (input: Input) => Effect.Effect<void, CliError.CliError, Environment>): <Name extends string, ContextInput, E, R>(
+    self: Command<Name, Input, ContextInput, E, R>
+  ) => Command<Name, Input, ContextInput, E, R>
+  /**
+   * Validates the parsed input of a command before the handler runs.
+   *
+   * **Details**
+   *
+   * Use this for rules that involve several flags or arguments, such as
+   * mutually exclusive flags. The validation receives the same input as the
+   * handler, with defaults, prompts and the wizard already applied. A failure
+   * is shown with the command help, like a parse error, and the handler does
+   * not run. Fail with `CliError.ValidationError` to supply the message, or
+   * with any other `CliError`. Validations run in the order they were added and
+   * stop at the first failure. Adding a handler later with `withHandler` keeps
+   * them.
+   *
+   * A validation sees only the input that exists where it is applied. Add it
+   * after `withSharedFlags` to see the shared flags. Added after
+   * `withSubcommands`, it also runs when a subcommand is selected, with the
+   * parent's shared flags as input.
+   *
+   * **Example** (Rejecting mutually exclusive flags)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, FileSystem, Layer, Path, Stdio, Terminal } from "effect"
+   * import { CliError, Command, Flag } from "effect/cli"
+   * import { ChildProcessSpawner } from "effect/process"
+   * import { TestConsole } from "effect/testing"
+   *
+   * const CliTestLayer = Layer.mergeAll(
+   *   FileSystem.layerNoop({}),
+   *   Path.layer,
+   *   Stdio.layerTest({}),
+   *   TestConsole.layer,
+   *   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 download = Command.make("download", {
+   *   useApi: Flag.Boolean("use-api").pipe(Flag.withDefault(false)),
+   *   useDocker: Flag.Boolean("use-docker").pipe(Flag.withDefault(false))
+   * }, () => Effect.void).pipe(
+   *   Command.validate(({ useApi, useDocker }) =>
+   *     useApi && useDocker
+   *       ? Effect.fail(
+   *         new CliError.ValidationError({
+   *           message: "--use-api and --use-docker are mutually exclusive"
+   *         })
+   *       )
+   *       : Effect.void
+   *   )
+   * )
+   *
+   * const error = await Effect.runPromise(
+   *   Command.runWith(download, { version: "1.0.0" })(["--use-api", "--use-docker"]).pipe(
+   *     Effect.flip,
+   *     Effect.provide(CliTestLayer)
+   *   )
+   * )
+   * error._tag // => "ShowHelp"
+   * error.errors[0].message // => "--use-api and --use-docker are mutually exclusive"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <Name extends string, Input, ContextInput, E, R>(
+    self: Command<Name, Input, ContextInput, E, R>,
+    f: (input: Input) => Effect.Effect<void, CliError.CliError, Environment>
+  ): Command<Name, Input, ContextInput, E, R>
+} = dual(2, <Name extends string, Input, ContextInput, E, R>(
+  self: Command<Name, Input, ContextInput, E, R>,
+  f: (input: Input) => Effect.Effect<void, CliError.CliError, Environment>
+): Command<Name, Input, ContextInput, E, R> => {
+  const impl = toImpl(self)
+  return makeCommand({
+    ...impl,
+    parse: (raw) => Effect.tap(impl.parse(raw), f)
+  }) as any
+})
+
 interface SubcommandGroupInternal {
   readonly group: string | undefined
   readonly commands: NonEmptyReadonlyArray<Command.Any>
@@ -1475,7 +1716,7 @@ export const withSubcommands: {
     unlisted: impl.unlisted,
     annotations: impl.annotations,
     globalFlags: impl.globalFlags,
-    examples: impl.examples,
+    resolveExamples: impl.resolveExamples,
     service: impl.service,
     subcommands: normalized.groups,
     parse,
@@ -1597,7 +1838,7 @@ export const withSharedFlags: {
       unlisted: impl.unlisted,
       annotations: impl.annotations,
       globalFlags: impl.globalFlags,
-      examples: impl.examples,
+      resolveExamples: impl.resolveExamples,
       service: impl.service as Context.Key<CommandContext<Name>, NextContextInput>,
       subcommands: impl.subcommands,
       parse,
@@ -2163,6 +2404,10 @@ export const annotateMerge: {
  * Examples are exposed in structured `HelpDoc` data and rendered by the
  * default formatter in an `EXAMPLES` section.
  *
+ * Pass a function to build examples from the `commandPath` shown in help, so
+ * they stay correct wherever the command is mounted. The `examples` field
+ * resolves the function with the command's own name as the path.
+ *
  * **Example** (Adding usage examples)
  *
  * ```ts import.meta.vitest
@@ -2178,6 +2423,20 @@ export const annotateMerge: {
  * login.examples.map((example) => example.command) // => ["myapp login", "myapp login --token sbp_abc123"]
  * ```
  *
+ * **Example** (Deriving examples from the command path)
+ *
+ * ```ts import.meta.vitest
+ * import { Command } from "effect/cli"
+ *
+ * const deploy = Command.make("deploy").pipe(
+ *   Command.withExamples(({ commandPath }) => [
+ *     { command: `${commandPath.join(" ")} --yes`, description: "Take every default" }
+ *   ])
+ * )
+ *
+ * deploy.examples.map((example) => example.command) // => ["deploy --yes"]
+ * ```
+ *
  * @stability unstable
  * @category combinators
  * @since 4.0.0
@@ -2191,6 +2450,10 @@ export const withExamples: {
    * Examples are exposed in structured `HelpDoc` data and rendered by the
    * default formatter in an `EXAMPLES` section.
    *
+   * Pass a function to build examples from the `commandPath` shown in help, so
+   * they stay correct wherever the command is mounted. The `examples` field
+   * resolves the function with the command's own name as the path.
+   *
    * **Example** (Adding usage examples)
    *
    * ```ts import.meta.vitest
@@ -2206,11 +2469,29 @@ export const withExamples: {
    * login.examples.map((example) => example.command) // => ["myapp login", "myapp login --token sbp_abc123"]
    * ```
    *
+   * **Example** (Deriving examples from the command path)
+   *
+   * ```ts import.meta.vitest
+   * import { Command } from "effect/cli"
+   *
+   * const deploy = Command.make("deploy").pipe(
+   *   Command.withExamples(({ commandPath }) => [
+   *     { command: `${commandPath.join(" ")} --yes`, description: "Take every default" }
+   *   ])
+   * )
+   *
+   * deploy.examples.map((example) => example.command) // => ["deploy --yes"]
+   * ```
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
    */
-  (examples: ReadonlyArray<Command.Example>): <const Name extends string, Input, E, R, ContextInput>(
+  (
+    examples:
+      | ReadonlyArray<Command.Example>
+      | ((context: { readonly commandPath: ReadonlyArray<string> }) => ReadonlyArray<Command.Example>)
+  ): <const Name extends string, Input, E, R, ContextInput>(
     self: Command<Name, Input, ContextInput, E, R>
   ) => Command<Name, Input, ContextInput, E, R>
   /**
@@ -2221,6 +2502,10 @@ export const withExamples: {
    * Examples are exposed in structured `HelpDoc` data and rendered by the
    * default formatter in an `EXAMPLES` section.
    *
+   * Pass a function to build examples from the `commandPath` shown in help, so
+   * they stay correct wherever the command is mounted. The `examples` field
+   * resolves the function with the command's own name as the path.
+   *
    * **Example** (Adding usage examples)
    *
    * ```ts import.meta.vitest
@@ -2236,18 +2521,40 @@ export const withExamples: {
    * login.examples.map((example) => example.command) // => ["myapp login", "myapp login --token sbp_abc123"]
    * ```
    *
+   * **Example** (Deriving examples from the command path)
+   *
+   * ```ts import.meta.vitest
+   * import { Command } from "effect/cli"
+   *
+   * const deploy = Command.make("deploy").pipe(
+   *   Command.withExamples(({ commandPath }) => [
+   *     { command: `${commandPath.join(" ")} --yes`, description: "Take every default" }
+   *   ])
+   * )
+   *
+   * deploy.examples.map((example) => example.command) // => ["deploy --yes"]
+   * ```
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
    */
   <const Name extends string, Input, E, R, ContextInput>(
     self: Command<Name, Input, ContextInput, E, R>,
-    examples: ReadonlyArray<Command.Example>
+    examples:
+      | ReadonlyArray<Command.Example>
+      | ((context: { readonly commandPath: ReadonlyArray<string> }) => ReadonlyArray<Command.Example>)
   ): Command<Name, Input, ContextInput, E, R>
 } = dual(2, <const Name extends string, Input, E, R, ContextInput>(
   self: Command<Name, Input, ContextInput, E, R>,
-  examples: ReadonlyArray<Command.Example>
-) => makeCommand({ ...toImpl(self), examples }))
+  examples:
+    | ReadonlyArray<Command.Example>
+    | ((context: { readonly commandPath: ReadonlyArray<string> }) => ReadonlyArray<Command.Example>)
+) =>
+  makeCommand({
+    ...toImpl(self),
+    resolveExamples: Predicate.isFunction(examples) ? (commandPath) => examples({ commandPath }) : () => examples
+  }))
 
 /* ========================================================================== */
 /* Providing Services                                                         */
@@ -2755,7 +3062,7 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
 ): Effect.Effect<void, CliError.CliError, Environment> =>
   Effect.gen(function*() {
     const { builtIns } = yield* CliConfig.CliConfig
-    const formatter = yield* CliOutput.Formatter
+    const formatter = yield* resolveFormatter
     const helpDoc = yield* getHelpForCommandPath(command, error.commandPath, builtIns)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
     if (renderErrors && error.errors.length > 0) {
@@ -2765,7 +3072,7 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
 
 const showUserError = (error: CliError.UserError): Effect.Effect<void> =>
   Effect.gen(function*() {
-    const formatter = yield* CliOutput.Formatter
+    const formatter = yield* resolveFormatter
     yield* Console.error(formatter.formatError(error))
     error[Runtime.errorReported] = false
   })

package/src/cli/Completions.ts

@@ -53,6 +53,11 @@ export interface FlagDescriptor {
    * `=` (`--name=value`), never given as the next word.
    */
   readonly optionalValue?: boolean | undefined
+  /**
+   * Long name that sets a boolean flag to `false`. Defaults to `no-<name>`;
+   * `false` means the flag has no negated form.
+   */
+  readonly negation?: string | false | undefined
 }
 
 /**

package/src/cli/Flag.ts

@@ -712,6 +712,123 @@ export const withOptionalValue: {
   <A>(self: Flag<A>, value: string): Flag<A>
 } = dual(2, <A>(self: Flag<A>, value: string) => Param.withOptionalValue(self, value))
 
+/**
+ * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+ *
+ * **Details**
+ *
+ * The new name replaces the default, so `--no-<name>` is no longer accepted
+ * and shell completions offer the new name instead. Has no effect on
+ * non-boolean flags.
+ *
+ * **Example** (Renaming a boolean flag's negation)
+ *
+ * ```ts import.meta.vitest
+ * import { Flag } from "effect/cli"
+ *
+ * const validate = Flag.Boolean("validate").pipe(
+ *   Flag.withDefault(true),
+ *   Flag.withNegation("skip-validate")
+ * )
+ * // --validate       => true
+ * // --skip-validate  => false
+ * // --no-validate    => unrecognized flag
+ * validate.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withNegation: {
+  /**
+   * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+   *
+   * **Details**
+   *
+   * The new name replaces the default, so `--no-<name>` is no longer accepted
+   * and shell completions offer the new name instead. Has no effect on
+   * non-boolean flags.
+   *
+   * **Example** (Renaming a boolean flag's negation)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const validate = Flag.Boolean("validate").pipe(
+   *   Flag.withDefault(true),
+   *   Flag.withNegation("skip-validate")
+   * )
+   * // --validate       => true
+   * // --skip-validate  => false
+   * // --no-validate    => unrecognized flag
+   * validate.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  (name: string): <A>(self: Flag<A>) => Flag<A>
+  /**
+   * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+   *
+   * **Details**
+   *
+   * The new name replaces the default, so `--no-<name>` is no longer accepted
+   * and shell completions offer the new name instead. Has no effect on
+   * non-boolean flags.
+   *
+   * **Example** (Renaming a boolean flag's negation)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const validate = Flag.Boolean("validate").pipe(
+   *   Flag.withDefault(true),
+   *   Flag.withNegation("skip-validate")
+   * )
+   * // --validate       => true
+   * // --skip-validate  => false
+   * // --no-validate    => unrecognized flag
+   * validate.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <A>(self: Flag<A>, name: string): Flag<A>
+} = dual(2, <A>(self: Flag<A>, name: string) => Param.withNegation(self, name))
+
+/**
+ * Removes the negated `--no-<name>` form of a boolean flag.
+ *
+ * **Details**
+ *
+ * The negated form is then rejected as an unrecognized flag and left out of
+ * shell completions. Has no effect on non-boolean flags.
+ *
+ * **Example** (Disabling a boolean flag's negation)
+ *
+ * ```ts import.meta.vitest
+ * import { Flag } from "effect/cli"
+ *
+ * const unsafe = Flag.Boolean("unsafe").pipe(
+ *   Flag.withDefault(false),
+ *   Flag.withoutNegation
+ * )
+ * // --unsafe     => true
+ * // --no-unsafe  => unrecognized flag
+ * unsafe.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withoutNegation = <A>(self: Flag<A>): Flag<A> => Param.withoutNegation(self)
+
 // -------------------------------------------------------------------------------------
 // metadata
 // -------------------------------------------------------------------------------------

package/src/cli/GlobalFlag.ts

@@ -17,11 +17,11 @@ import * as Context from "../Context.ts"
 import * as Effect from "../Effect.ts"
 import type { LogLevel as LogLevelType } from "../LogLevel.ts"
 import * as Option from "../Option.ts"
-import * as CliOutput from "./CliOutput.ts"
 import type * as Command from "./Command.ts"
 import * as Completions_ from "./Completions.ts"
 import * as Flag from "./Flag.ts"
 import * as CommandDescriptor from "./internal/completions/descriptor.ts"
+import { resolveFormatter } from "./internal/formatter.ts"
 import * as HelpInternal from "./internal/help.ts"
 
 /* ========================================================================== */
@@ -169,7 +169,7 @@ export const Help: Action<boolean> = Action({
     Flag.withDefault(false)
   ),
   run: Effect.fnUntraced(function*(_, { builtIns, command, commandPath }) {
-    const formatter = yield* CliOutput.Formatter
+    const formatter = yield* resolveFormatter
     const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, builtIns)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
   })
@@ -193,7 +193,7 @@ export const Version: Action<boolean> = Action({
     Flag.withDefault(false)
   ),
   run: Effect.fnUntraced(function*(_, { command, version }) {
-    const formatter = yield* CliOutput.Formatter
+    const formatter = yield* resolveFormatter
     yield* Console.log(formatter.formatVersion(command.name, version))
   })
 })