effect 4.0.5 → 4.0.7

package/src/cli/Command.ts

@@ -34,6 +34,7 @@ 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 +1122,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 +1717,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 +1839,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 +2405,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 +2424,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 +2451,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 +2470,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 +2503,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 +2522,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,19 +3063,24 @@ 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 helpDoc = yield* getHelpForCommandPath(command, error.commandPath, builtIns)
-    yield* Console.log(formatter.formatHelpDoc(helpDoc))
-    if (renderErrors && error.errors.length > 0) {
-      yield* Console.error(formatter.formatErrors(error.errors as any))
-    }
+    const presenter = yield* CliOutput.Presenter
+    const { commandPath, errors } = error
+    const helpDoc = yield* getHelpForCommandPath(command, commandPath, builtIns)
+    yield* presenter.present(
+      renderErrors && errors.length > 0
+        ? { _tag: "InvalidInvocation", commandPath, helpDoc, errors }
+        : { _tag: "Help", reason: "Implicit", commandPath, helpDoc }
+    )
   })
 
-const showUserError = (error: CliError.UserError): Effect.Effect<void> =>
+const showUserError = (error: object, userMessage: string): Effect.Effect<void> =>
   Effect.gen(function*() {
-    const formatter = yield* CliOutput.Formatter
-    yield* Console.error(formatter.formatError(error))
-    error[Runtime.errorReported] = false
+    const formatter = yield* resolveFormatter
+    const rendered = error instanceof CliError.UserError
+      ? error
+      : new CliError.UserError({ cause: error, userMessage })
+    yield* Console.error(formatter.formatError(rendered))
+    Object.assign(error, { [Runtime.errorReported]: false })
   })
 
 /**
@@ -2778,10 +3091,12 @@ const showUserError = (error: CliError.UserError): Effect.Effect<void> =>
  * Use when command-line arguments should come from `Stdio` at the application
  * entry point.
  *
- * Help documents are always rendered. By default, parse error details and
- * `CliError.UserError` failures are also rendered with the installed
- * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
- * `false` when the host application owns error rendering.
+ * Help, version, and parse error output is written through
+ * `CliOutput.Presenter`. Help documents are always presented. By default,
+ * parse error details are also presented, and handler failures annotated with
+ * `CliError.userMessage`, including `CliError.UserError`, are rendered with the
+ * installed `CliOutput.Formatter` before the error is rethrown. Set
+ * `renderErrors` to `false` when the host application owns error rendering.
  *
  * **Example** (Running commands with standard input)
  *
@@ -2841,10 +3156,12 @@ export const run: {
    * Use when command-line arguments should come from `Stdio` at the application
    * entry point.
    *
-   * Help documents are always rendered. By default, parse error details and
-   * `CliError.UserError` failures are also rendered with the installed
-   * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
-   * `false` when the host application owns error rendering.
+   * Help, version, and parse error output is written through
+   * `CliOutput.Presenter`. Help documents are always presented. By default,
+   * parse error details are also presented, and handler failures annotated with
+   * `CliError.userMessage`, including `CliError.UserError`, are rendered with the
+   * installed `CliOutput.Formatter` before the error is rethrown. Set
+   * `renderErrors` to `false` when the host application owns error rendering.
    *
    * **Example** (Running commands with standard input)
    *
@@ -2911,10 +3228,12 @@ export const run: {
    * Use when command-line arguments should come from `Stdio` at the application
    * entry point.
    *
-   * Help documents are always rendered. By default, parse error details and
-   * `CliError.UserError` failures are also rendered with the installed
-   * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
-   * `false` when the host application owns error rendering.
+   * Help, version, and parse error output is written through
+   * `CliOutput.Presenter`. Help documents are always presented. By default,
+   * parse error details are also presented, and handler failures annotated with
+   * `CliError.userMessage`, including `CliError.UserError`, are rendered with the
+   * installed `CliOutput.Formatter` before the error is rethrown. Set
+   * `renderErrors` to `false` when the host application owns error rendering.
    *
    * **Example** (Running commands with standard input)
    *
@@ -2994,10 +3313,12 @@ export const run: {
  * Use when you need to test CLI applications or programmatically execute
  * commands with specific arguments.
  *
- * Help documents are always rendered. By default, parse error details and
- * `CliError.UserError` failures are also rendered with the installed
- * `CliOutput.Formatter` before the error is rethrown. Set `renderErrors` to
- * `false` when the host application owns error rendering.
+ * Help, version, and parse error output is written through
+ * `CliOutput.Presenter`. Help documents are always presented. By default,
+ * parse error details are also presented, and handler failures annotated with
+ * `CliError.userMessage`, including `CliError.UserError`, are rendered with the
+ * installed `CliOutput.Formatter` before the error is rethrown. Set
+ * `renderErrors` to `false` when the host application owns error rendering.
  *
  * **Example** (Running commands with explicit arguments)
  *
@@ -3080,6 +3401,9 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
       // 3. Parse command arguments from remaining tokens
       const parsedArgs = yield* Parser.parseArgs({ tokens: remainder, trailingOperands }, command)
       const commandPath = [command.name, ...Parser.getCommandPath(parsedArgs)] as const
+      const toShowHelp = Effect.mapError((error: CliError.CliError) =>
+        error._tag === "ShowHelp" ? error : new CliError.ShowHelp({ commandPath, errors: [error] })
+      )
       const handlerCtx: GlobalFlag.HandlerContext = { builtIns, command, commandPath, version: config.version }
       const activeFlags = getGlobalFlagsForCommandPath(command, commandPath, builtIns)
 
@@ -3102,7 +3426,7 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
           return entries !== undefined && entries.length > 0
         })
         if (!hasEntry) continue
-        const [, value] = yield* flag.flag.parse(emptyArgs)
+        const [, value] = yield* flag.flag.parse(emptyArgs).pipe(toShowHelp)
         if (flag === GlobalFlag.Wizard) {
           const { colors } = yield* Prompt.Theme
           return yield* Effect.gen(function*() {
@@ -3135,23 +3459,17 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
       if (parsedArgs.errors && parsedArgs.errors.length > 0) {
         return yield* new CliError.ShowHelp({ commandPath, errors: parsedArgs.errors })
       }
-      const parseResult = yield* Effect.result(commandImpl.parse(parsedArgs))
-      if (parseResult._tag === "Failure") {
-        return yield* new CliError.ShowHelp({
-          commandPath,
-          errors: [parseResult.failure as CliError.NonShowHelpErrors]
-        })
-      }
+      const input = yield* commandImpl.parse(parsedArgs).pipe(toShowHelp)
 
       // 7. Provide setting values
-      let program = commandImpl.handle(parseResult.success, [command.name])
+      let program = commandImpl.handle(input, [command.name])
       const logLevel = activeFlags.includes(GlobalFlag.LogLevel)
-        ? (yield* GlobalFlag.LogLevel.flag.parse(emptyArgs))[1]
+        ? (yield* GlobalFlag.LogLevel.flag.parse(emptyArgs).pipe(toShowHelp))[1]
         : Option.none()
       program = Effect.provideService(program, GlobalFlag.LogLevel, logLevel)
       for (const flag of activeFlags) {
         if (flag._tag !== "Setting" || flag === GlobalFlag.LogLevel) continue
-        const [, value] = yield* flag.flag.parse(emptyArgs)
+        const [, value] = yield* flag.flag.parse(emptyArgs).pipe(toShowHelp)
         program = Effect.provideService(program, flag, value)
       }
 
@@ -3172,11 +3490,12 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
       (error) => Effect.andThen(showHelp(command, error, config.renderErrors !== false), Effect.fail(error))
     ),
     Effect.catchFilter(
-      (error) =>
-        config.renderErrors !== false && CliError.isCliError(error) && error._tag === "UserError"
-          ? Result.succeed(error)
-          : Result.fail(error),
-      (error) => Effect.andThen(showUserError(error), Effect.fail(error))
+      (error) => {
+        if (config.renderErrors === false || !Predicate.isObjectKeyword(error)) return Result.fail(error)
+        const userMessage = CliError.getUserMessage(error)
+        return userMessage === undefined ? Result.fail(error) : Result.succeed({ error, userMessage })
+      },
+      ({ error, userMessage }) => Effect.andThen(showUserError(error, userMessage), Effect.fail(error))
     ),
     Effect.catchFilter(
       (e) =>

package/src/cli/Completions.ts

@@ -7,7 +7,9 @@
  * @stability unstable
  * @since 4.0.0
  */
+import type { Command } from "./Command.ts"
 import * as Bash from "./internal/completions/bash.ts"
+import * as Descriptor from "./internal/completions/descriptor.ts"
 import * as Fish from "./internal/completions/fish.ts"
 import * as PowerShell from "./internal/completions/powershell.ts"
 import * as Zsh from "./internal/completions/zsh.ts"
@@ -53,6 +55,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
 }
 
 /**
@@ -101,6 +108,55 @@ export type ArgumentType =
   | { readonly _tag: "Choice"; readonly values: ReadonlyArray<string> }
   | { readonly _tag: "Path"; readonly pathType: "file" | "directory" | "either" }
 
+/**
+ * Converts a command tree into a `CommandDescriptor` for completion script
+ * generation.
+ *
+ * **When to use**
+ *
+ * Use when you need to generate a completion script from an existing
+ * `Command`, for example in a build step, without running the CLI or
+ * capturing the output of the built-in `--completions` flag.
+ *
+ * **Details**
+ *
+ * Reads the command's flags, arguments, and subcommands, including flags
+ * shared with subcommands and aliases. Hidden flags and unlisted subcommands
+ * are omitted, matching `--help`. Command handlers are never run.
+ *
+ * **Example** (Generating a Zsh completion script at build time)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect } from "effect"
+ * import { Command, Completions, Flag } from "effect/cli"
+ *
+ * const start = Command.make(
+ *   "start",
+ *   { port: Flag.Int("port") },
+ *   ({ port }) => Effect.log(`Listening on ${port}`)
+ * )
+ *
+ * const cli = Command.make("server").pipe(
+ *   Command.withSubcommands([start])
+ * )
+ *
+ * const script = Completions.generate(
+ *   "server",
+ *   "zsh",
+ *   Completions.fromCommand(cli)
+ * )
+ *
+ * script.startsWith("#compdef server") // => true
+ * ```
+ *
+ * @see {@link generate} for turning the descriptor into a shell script
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.7
+ */
+export const fromCommand = (command: Command.Any): CommandDescriptor => Descriptor.fromCommand(command)
+
 /**
  * Generates a shell completion script for a command descriptor.
  *