effect 4.0.6 → 4.1.0

package/src/cli/Command.ts

@@ -30,6 +30,7 @@ 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"
@@ -71,6 +72,7 @@ import * as Prompt from "./Prompt.ts"
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -460,6 +462,7 @@ export type Services<C> = C extends Command<
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -572,6 +575,7 @@ export const isCommand = (u: unknown): u is Command.Any => Predicate.hasProperty
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -666,6 +670,7 @@ export const make: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -761,6 +766,7 @@ export const make: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -856,6 +862,7 @@ export const make: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -960,6 +967,7 @@ export const make: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1017,6 +1025,7 @@ export const withHandler: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1076,6 +1085,7 @@ export const withHandler: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1436,6 +1446,7 @@ const normalizeSubcommandEntries = (
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1507,6 +1518,7 @@ export const withSubcommands: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1586,6 +1598,7 @@ export const withSubcommands: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1946,6 +1959,7 @@ type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>>
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1999,6 +2013,7 @@ export const withDescription: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2054,6 +2069,7 @@ export const withDescription: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2587,6 +2603,7 @@ const mapHandler = <Name extends string, Input, E, R, ContextInput, E2, R2>(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -2650,6 +2667,7 @@ export const provide: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2720,6 +2738,7 @@ export const provide: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2981,6 +3000,7 @@ export const provideEffectDiscard: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -3062,19 +3082,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* resolveFormatter
-    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* resolveFormatter
-    yield* Console.error(formatter.formatError(error))
-    error[Runtime.errorReported] = false
+    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 })
   })
 
 /**
@@ -3085,10 +3110,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)
  *
@@ -3106,6 +3133,7 @@ const showUserError = (error: CliError.UserError): Effect.Effect<void> =>
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -3148,10 +3176,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)
    *
@@ -3169,6 +3199,7 @@ export const run: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -3218,10 +3249,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)
    *
@@ -3239,6 +3272,7 @@ export const run: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -3301,10 +3335,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)
  *
@@ -3320,6 +3356,7 @@ export const run: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -3387,6 +3424,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)
 
@@ -3409,7 +3449,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*() {
@@ -3442,23 +3482,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)
       }
 
@@ -3479,11 +3513,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"
@@ -106,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.
  *

package/src/cli/Flag.ts

@@ -290,6 +290,7 @@ export const Directory = (name: string, options?: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -981,6 +982,7 @@ export const withHidden = <A>(self: Flag<A>): Flag<A> => Param.withHidden(self)
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1155,6 +1157,11 @@ export const withFallbackConfig: {
 /**
  * Adds a fallback prompt that is shown when a required flag is missing.
  *
+ * **Gotchas**
+ *
+ * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+ * the original `MissingOption` error is returned.
+ *
  * **Example** (Falling back to prompts)
  *
  * ```ts import.meta.vitest
@@ -1166,6 +1173,38 @@ export const withFallbackConfig: {
  * name.kind // => "flag"
  * ```
  *
+ * **Example** (Showing an introduction before fallback prompts)
+ *
+ * The prompt can be built by an effect, which only runs when the prompt is
+ * needed. Share a cached introduction between the prompt builders and
+ * `Command.provideEffectDiscard`: it runs once, before the first prompt, and
+ * also runs when every flag is supplied. Flags declared after the first
+ * prompted flag may not have been validated yet when the introduction runs.
+ *
+ * ```ts import.meta.vitest
+ * import { Console, Effect } from "effect"
+ * import { Command, Flag, Prompt } from "effect/cli"
+ *
+ * const program = Effect.gen(function*() {
+ *   const intro = yield* Effect.cached(Console.log("Welcome to demo"))
+ *
+ *   const ask = (name: string) =>
+ *     Flag.String(name).pipe(
+ *       Flag.withFallbackPrompt(
+ *         Effect.as(intro, Prompt.String({ message: `${name}?` }))
+ *       )
+ *     )
+ *
+ *   const demo = Command.make(
+ *     "demo",
+ *     { name: ask("name"), dir: ask("dir") },
+ *     (input) => Console.log(input)
+ *   ).pipe(Command.provideEffectDiscard(intro))
+ *
+ *   yield* Command.run(demo, { version: "1.0.0" })
+ * })
+ * ```
+ *
  * @stability unstable
  * @category combinators
  * @since 4.0.0
@@ -1174,6 +1213,11 @@ export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required flag is missing.
    *
+   * **Gotchas**
+   *
+   * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+   * the original `MissingOption` error is returned.
+   *
    * **Example** (Falling back to prompts)
    *
    * ```ts import.meta.vitest
@@ -1185,6 +1229,38 @@ export const withFallbackPrompt: {
    * name.kind // => "flag"
    * ```
    *
+   * **Example** (Showing an introduction before fallback prompts)
+   *
+   * The prompt can be built by an effect, which only runs when the prompt is
+   * needed. Share a cached introduction between the prompt builders and
+   * `Command.provideEffectDiscard`: it runs once, before the first prompt, and
+   * also runs when every flag is supplied. Flags declared after the first
+   * prompted flag may not have been validated yet when the introduction runs.
+   *
+   * ```ts import.meta.vitest
+   * import { Console, Effect } from "effect"
+   * import { Command, Flag, Prompt } from "effect/cli"
+   *
+   * const program = Effect.gen(function*() {
+   *   const intro = yield* Effect.cached(Console.log("Welcome to demo"))
+   *
+   *   const ask = (name: string) =>
+   *     Flag.String(name).pipe(
+   *       Flag.withFallbackPrompt(
+   *         Effect.as(intro, Prompt.String({ message: `${name}?` }))
+   *       )
+   *     )
+   *
+   *   const demo = Command.make(
+   *     "demo",
+   *     { name: ask("name"), dir: ask("dir") },
+   *     (input) => Console.log(input)
+   *   ).pipe(Command.provideEffectDiscard(intro))
+   *
+   *   yield* Command.run(demo, { version: "1.0.0" })
+   * })
+   * ```
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
@@ -1193,6 +1269,11 @@ export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required flag is missing.
    *
+   * **Gotchas**
+   *
+   * When `TerminalCapabilities.canPrompt` is `false`, the prompt is skipped and
+   * the original `MissingOption` error is returned.
+   *
    * **Example** (Falling back to prompts)
    *
    * ```ts import.meta.vitest
@@ -1204,6 +1285,38 @@ export const withFallbackPrompt: {
    * name.kind // => "flag"
    * ```
    *
+   * **Example** (Showing an introduction before fallback prompts)
+   *
+   * The prompt can be built by an effect, which only runs when the prompt is
+   * needed. Share a cached introduction between the prompt builders and
+   * `Command.provideEffectDiscard`: it runs once, before the first prompt, and
+   * also runs when every flag is supplied. Flags declared after the first
+   * prompted flag may not have been validated yet when the introduction runs.
+   *
+   * ```ts import.meta.vitest
+   * import { Console, Effect } from "effect"
+   * import { Command, Flag, Prompt } from "effect/cli"
+   *
+   * const program = Effect.gen(function*() {
+   *   const intro = yield* Effect.cached(Console.log("Welcome to demo"))
+   *
+   *   const ask = (name: string) =>
+   *     Flag.String(name).pipe(
+   *       Flag.withFallbackPrompt(
+   *         Effect.as(intro, Prompt.String({ message: `${name}?` }))
+   *       )
+   *     )
+   *
+   *   const demo = Command.make(
+   *     "demo",
+   *     { name: ask("name"), dir: ask("dir") },
+   *     (input) => Console.log(input)
+   *   ).pipe(Command.provideEffectDiscard(intro))
+   *
+   *   yield* Command.run(demo, { version: "1.0.0" })
+   * })
+   * ```
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
@@ -1305,6 +1418,7 @@ export const map: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1350,6 +1464,7 @@ export const mapEffect: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1395,6 +1510,7 @@ export const mapEffect: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1448,6 +1564,7 @@ export const mapEffect: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1505,6 +1622,7 @@ export const mapTryCatch: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1562,6 +1680,7 @@ export const mapTryCatch: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2131,6 +2250,7 @@ export const orElse: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -2179,6 +2299,7 @@ export const orElseResult: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -2227,6 +2348,7 @@ export const orElseResult: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void