effect 4.0.0-beta.97 → 4.0.0-beta.99

package/src/internal/schema/schema.ts

@@ -1,10 +1,9 @@
 import * as Cause from "../../Cause.ts"
-import * as Data from "../../Data.ts"
 import * as Effect from "../../Effect.ts"
-import * as Exit from "../../Exit.ts"
 import * as Pipeable from "../../Pipeable.ts"
 import type * as Schema from "../../Schema.ts"
 import * as SchemaAST from "../../SchemaAST.ts"
+import { SchemaError } from "../../SchemaError.ts"
 import type { Issue } from "../../SchemaIssue.ts"
 import * as SchemaParser from "../../SchemaParser.ts"
 
@@ -35,34 +34,16 @@ export function make<S extends Schema.Constraint>(ast: S["ast"], options?: objec
   }
   self.ast = ast
   self.rebuild = (ast: SchemaAST.AST) => make(ast, options)
+  const makeEffect = SchemaParser.makeEffect(self)
   self.makeEffect = (input: S["~type.make.in"], options?: Schema.MakeOptions) =>
-    mapSchemaIssueEffect(SchemaParser.makeEffect(self)(input, options))
+    fromIssueEffect(makeEffect(input, options))
   self.make = SchemaParser.make(self)
   self.makeOption = SchemaParser.makeOption(self)
   return self
 }
 
 /** @internal */
-export const SchemaErrorTypeId = "~effect/Schema/SchemaError"
-
-// purposefully not internal
-export class SchemaError extends Data.TaggedError("SchemaError")<{
-  readonly issue: Issue
-}> {
-  readonly [SchemaErrorTypeId]: typeof SchemaErrorTypeId = SchemaErrorTypeId
-  constructor(issue: Issue) {
-    super({ issue })
-  }
-  override get message() {
-    return this.issue.toString()
-  }
-  override toString() {
-    return `SchemaError(${this.message})`
-  }
-}
-
-/** @internal */
-export function mapSchemaIssueEffect<A, R>(
+export function fromIssueEffect<A, R>(
   self: Effect.Effect<A, Issue, R>
 ): Effect.Effect<A, SchemaError, R> {
   return Effect.catchCause(
@@ -71,20 +52,6 @@ export function mapSchemaIssueEffect<A, R>(
   )
 }
 
-/** @internal */
-export function mapSchemaErrorEffect<A, R>(
-  self: Effect.Effect<A, SchemaError, R>
-): Effect.Effect<A, Issue, R> {
-  return Effect.catchCause(self, (cause) => Effect.failCauseSync(() => Cause.map(cause, (error) => error.issue)))
-}
-
-/** @internal */
-export function mapSchemaIssueExit<A>(exit: Exit.Exit<A, Issue>): Exit.Exit<A, SchemaError> {
-  return Exit.isSuccess(exit)
-    ? Exit.succeed(exit.value)
-    : Exit.failCause(Cause.map(exit.cause, (issue) => new SchemaError(issue)))
-}
-
 /** @internal */
 export const jsonReorder = makeReorder(getJsonPriority)
 

package/src/unstable/ai/Tool.ts

@@ -1028,37 +1028,34 @@ export type RequiresHandler<Tool extends Any> = Tool extends ProviderDefined<
 // Constructors
 // =============================================================================
 
+// Clones a tool while preserving its prototype (and thus its kind, e.g.
+// user-defined vs. provider-defined vs. dynamic) and its own properties such
+// as `id`. Optional `overrides` replace individual fields on the clone.
+const clone = (self: Any, overrides?: Record<string, unknown>): any =>
+  Object.assign(Object.create(Object.getPrototypeOf(self)), self, overrides)
+
 const Proto = {
   [TypeId]: { _Requirements: identity },
   pipe() {
     return pipeArguments(this, arguments)
   },
   addDependency(this: Any) {
-    return userDefinedProto({ ...this })
+    return clone(this)
   },
   setParameters(this: Any, parametersSchema: Schema.Constraint) {
-    return userDefinedProto({
-      ...this,
-      parametersSchema
-    })
+    return clone(this, { parametersSchema })
   },
   setSuccess(this: Any, successSchema: Schema.Constraint) {
-    return userDefinedProto({ ...this, successSchema })
+    return clone(this, { successSchema })
   },
   setFailure(this: Any, failureSchema: Schema.Constraint) {
-    return userDefinedProto({ ...this, failureSchema })
+    return clone(this, { failureSchema })
   },
   annotate<I, S>(this: Any, tag: Context.Key<I, S>, value: S) {
-    return userDefinedProto({
-      ...this,
-      annotations: Context.add(this.annotations, tag, value)
-    })
+    return clone(this, { annotations: Context.add(this.annotations, tag, value) })
   },
   annotateMerge<I>(this: Any, context: Context.Context<I>) {
-    return userDefinedProto({
-      ...this,
-      annotations: Context.merge(this.annotations, context)
-    })
+    return clone(this, { annotations: Context.merge(this.annotations, context) })
   }
 }
 
@@ -1132,7 +1129,7 @@ const providerDefinedProto = <
     readonly failureMode: Mode
   },
   RequiresHandler
-> => Object.assign(Object.create(ProviderDefinedProto), { ...options })
+> => Object.assign(Object.create(ProviderDefinedProto), { annotations: Context.empty(), ...options })
 
 const dynamicProto = <
   const Name extends string,

package/src/unstable/cli/CliConfig.ts

@@ -0,0 +1,85 @@
+/**
+ * Configuration for Effect CLI command execution.
+ *
+ * @since 4.0.0
+ */
+import * as Context from "../../Context.ts"
+import * as Layer from "../../Layer.ts"
+import * as GlobalFlag from "./GlobalFlag.ts"
+
+/**
+ * Context reference for configuration shared by CLI parsing, help generation,
+ * and command execution.
+ *
+ * **When to use**
+ *
+ * Use when you need to customize runner-wide CLI behavior, such as which
+ * built-in global flags are available.
+ *
+ * @category services
+ * @since 4.0.0
+ */
+export class CliConfig extends Context.Reference<CliConfig.Service>("effect/unstable/cli/CliConfig", {
+  defaultValue: () => defaults
+}) {}
+
+/**
+ * Types used by the `CliConfig` context reference.
+ *
+ * @since 4.0.0
+ */
+export declare namespace CliConfig {
+  /**
+   * Configuration values used while running a CLI command.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface Service {
+    /** Ordered built-in global flags, with earlier action flags taking precedence. */
+    readonly builtIns: ReadonlyArray<GlobalFlag.BuiltIn>
+  }
+}
+
+/**
+ * Default CLI configuration containing every built-in global flag.
+ *
+ * @category defaults
+ * @since 4.0.0
+ */
+export const defaults: CliConfig.Service = {
+  builtIns: GlobalFlag.BuiltIns
+}
+
+/**
+ * Creates CLI configuration by merging the provided options over `defaults`.
+ *
+ * **When to use**
+ *
+ * Use when you need a configuration value to provide directly through the
+ * `CliConfig` context reference.
+ *
+ * @see {@link layer} for providing configuration as a layer
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = (options?: Partial<CliConfig.Service>): CliConfig.Service => ({
+  ...defaults,
+  ...options
+})
+
+/**
+ * Creates a layer that provides CLI configuration merged over `defaults`.
+ *
+ * **When to use**
+ *
+ * Use when wiring customized CLI behavior into an application layer.
+ *
+ * @see {@link make} for creating a configuration value directly
+ *
+ * @category layers
+ * @since 4.0.0
+ */
+export const layer = (options?: Partial<CliConfig.Service>): Layer.Layer<never> =>
+  Layer.succeed(CliConfig, make(options))

package/src/unstable/cli/CliError.ts

@@ -127,8 +127,9 @@ export type CliError =
  * @category models
  * @since 4.0.0
  */
-export class UnrecognizedOption extends Schema.ErrorClass<UnrecognizedOption>(`${TypeId}/UnrecognizedOption`)({
-  _tag: Schema.tag("UnrecognizedOption"),
+export class UnrecognizedOption extends Schema.TaggedErrorClass<UnrecognizedOption>(
+  `${TypeId}/UnrecognizedOption`
+)("UnrecognizedOption", {
   option: Schema.String,
   command: Schema.optional(Schema.Array(Schema.String)),
   suggestions: Schema.Array(Schema.String)
@@ -178,8 +179,9 @@ export class UnrecognizedOption extends Schema.ErrorClass<UnrecognizedOption>(`$
  * @category models
  * @since 4.0.0
  */
-export class DuplicateOption extends Schema.ErrorClass<DuplicateOption>(`${TypeId}/DuplicateOption`)({
-  _tag: Schema.tag("DuplicateOption"),
+export class DuplicateOption extends Schema.TaggedErrorClass<DuplicateOption>(
+  `${TypeId}/DuplicateOption`
+)("DuplicateOption", {
   option: Schema.String,
   parentCommand: Schema.String,
   childCommand: Schema.String
@@ -232,8 +234,9 @@ export class DuplicateOption extends Schema.ErrorClass<DuplicateOption>(`${TypeI
  * @category models
  * @since 4.0.0
  */
-export class MissingOption extends Schema.ErrorClass<MissingOption>(`${TypeId}/MissingOption`)({
-  _tag: Schema.tag("MissingOption"),
+export class MissingOption extends Schema.TaggedErrorClass<MissingOption>(
+  `${TypeId}/MissingOption`
+)("MissingOption", {
   option: Schema.String
 }) {
   /**
@@ -282,8 +285,9 @@ export class MissingOption extends Schema.ErrorClass<MissingOption>(`${TypeId}/M
  * @category models
  * @since 4.0.0
  */
-export class MissingArgument extends Schema.ErrorClass<MissingArgument>(`${TypeId}/MissingArgument`)({
-  _tag: Schema.tag("MissingArgument"),
+export class MissingArgument extends Schema.TaggedErrorClass<MissingArgument>(
+  `${TypeId}/MissingArgument`
+)("MissingArgument", {
   argument: Schema.String
 }) {
   /**
@@ -337,8 +341,9 @@ export class MissingArgument extends Schema.ErrorClass<MissingArgument>(`${TypeI
  * @category models
  * @since 4.0.0
  */
-export class InvalidValue extends Schema.ErrorClass<InvalidValue>(`${TypeId}/InvalidValue`)({
-  _tag: Schema.tag("InvalidValue"),
+export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
+  `${TypeId}/InvalidValue`
+)("InvalidValue", {
   option: Schema.String,
   value: Schema.String,
   expected: Schema.String,
@@ -360,6 +365,9 @@ export class InvalidValue extends Schema.ErrorClass<InvalidValue>(`${TypeId}/Inv
     if (this.kind === "argument") {
       return `Invalid value for argument <${this.option}>: "${this.value}". Expected: ${this.expected}`
     }
+    if (this.value.length === 0) {
+      return `Missing value for flag --${this.option}. Expected: ${this.expected}`
+    }
     return `Invalid value for flag --${this.option}: "${this.value}". Expected: ${this.expected}`
   }
 }
@@ -400,8 +408,9 @@ export class InvalidValue extends Schema.ErrorClass<InvalidValue>(`${TypeId}/Inv
  * @category models
  * @since 4.0.0
  */
-export class UnknownSubcommand extends Schema.ErrorClass<UnknownSubcommand>(`${TypeId}/UnknownSubcommand`)({
-  _tag: Schema.tag("UnknownSubcommand"),
+export class UnknownSubcommand extends Schema.TaggedErrorClass<UnknownSubcommand>(
+  `${TypeId}/UnknownSubcommand`
+)("UnknownSubcomand", {
   subcommand: Schema.String,
   parent: Schema.optional(Schema.Array(Schema.String)),
   suggestions: Schema.Array(Schema.String)
@@ -464,8 +473,9 @@ export class UnknownSubcommand extends Schema.ErrorClass<UnknownSubcommand>(`${T
  * @category models
  * @since 4.0.0
  */
-export class UserError extends Schema.ErrorClass<UserError>(`${TypeId}/UserError`)({
-  _tag: Schema.tag("UserError"),
+export class UserError extends Schema.TaggedErrorClass<UserError>(
+  `${TypeId}/UserError`
+)("UserError", {
   cause: Schema.Defect()
 }) {
   /**
@@ -533,8 +543,9 @@ export type NonShowHelpErrors = typeof NonShowHelpErrors.Type
  * @category models
  * @since 4.0.0
  */
-export class ShowHelp extends Schema.ErrorClass<ShowHelp>(`${TypeId}/ShowHelp`)({
-  _tag: Schema.tag("ShowHelp"),
+export class ShowHelp extends Schema.TaggedErrorClass<ShowHelp>(
+  `${TypeId}/ShowHelp`
+)("ShowHelp", {
   commandPath: Schema.Array(Schema.String),
   errors: Schema.Array(NonShowHelpErrors)
 }) {

package/src/unstable/cli/Command.ts

@@ -26,6 +26,7 @@ import * as Stdio from "../../Stdio.ts"
 import * as Terminal from "../../Terminal.ts"
 import type { Contravariant, Covariant, NoInfer, Simplify } from "../../Types.ts"
 import type { ChildProcessSpawner } from "../process/ChildProcessSpawner.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"
@@ -34,7 +35,9 @@ import { mergeConfig, parseConfig } from "./internal/config.ts"
 import { getGlobalFlagsForCommandPath, getGlobalFlagsForCommandTree, getHelpForCommandPath } from "./internal/help.ts"
 import * as Lexer from "./internal/lexer.ts"
 import * as Parser from "./internal/parser.ts"
+import * as Wizard from "./internal/wizard.ts"
 import * as Param from "./Param.ts"
+import * as Prompt from "./Prompt.ts"
 
 /* ========================================================================== */
 /* Public Types                                                               */
@@ -369,6 +372,21 @@ export type Error<C> = C extends Command<
 > ? _Error :
   never
 
+/**
+ * A utility type to extract the required services type from a `Command`.
+ *
+ * @category utility types
+ * @since 4.0.0
+ */
+export type Services<C> = C extends Command<
+  infer _Name,
+  infer _Input,
+  infer _ContextInput,
+  infer _Error,
+  infer _Requirements
+> ? _Requirements :
+  never
+
 /**
  * Service context for a specific command, enabling subcommands to access their parent's parsed configuration.
  *
@@ -697,7 +715,7 @@ export const make: {
     name: Name,
     config: Config,
     handler: (config: Command.Config.Infer<Config>) => Effect.Effect<void, E, R>
-  ): Command<Name, Command.Config.Infer<Config>, {}, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>
+  ): Command<Name, Command.Config.Infer<Config>, {}, E, Exclude<R, BuiltInSettingContext>>
 } = ((
   name: string,
   config?: Command.Config,
@@ -772,7 +790,7 @@ export const withHandler: {
    */
   <A, R, E>(handler: (value: A) => Effect.Effect<void, E, R>): <Name extends string, XR, XE, ContextInput>(
     self: Command<Name, A, ContextInput, XE, XR>
-  ) => Command<Name, A, ContextInput, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>
+  ) => Command<Name, A, ContextInput, E, Exclude<R, BuiltInSettingContext>>
   /* ========================================================================== */
   /* Combinators                                                                */
   /* ========================================================================== */
@@ -805,11 +823,11 @@ export const withHandler: {
   <Name extends string, A, XR, XE, R, E, ContextInput>(
     self: Command<Name, A, ContextInput, XE, XR>,
     handler: (value: A) => Effect.Effect<void, E, R>
-  ): Command<Name, A, ContextInput, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>
+  ): Command<Name, A, ContextInput, E, Exclude<R, BuiltInSettingContext>>
 } = dual(2, <Name extends string, A, XR, XE, R, E, ContextInput>(
   self: Command<Name, A, ContextInput, XE, XR>,
   handler: (value: A) => Effect.Effect<void, E, R>
-): Command<Name, A, ContextInput, E, Exclude<R, GlobalFlag.BuiltInSettingContext>> =>
+): Command<Name, A, ContextInput, E, Exclude<R, BuiltInSettingContext>> =>
   makeCommand({ ...toImpl(self), handle: handler } as any))
 
 interface SubcommandGroupInternal {
@@ -1272,12 +1290,12 @@ type ExtractGlobalFlagContext<T extends ReadonlyArray<GlobalFlag.GlobalFlag<any>
   ? F extends GlobalFlag.Setting<infer Id, infer _A> ? GlobalFlag.Setting.Identifier<Id>
   : never
   : never
+type BuiltInSettingContext = ExtractGlobalFlagContext<typeof GlobalFlag.BuiltIns>
 type ExtractSubcommand<T> = T extends Command<infer _Name, infer _Input, infer _CI, infer _E, infer _R> ? T
   : T extends Command.SubcommandGroup<infer Commands> ? Commands[number]
   : never
 type ExtractSubcommandErrors<T extends ReadonlyArray<Command.SubcommandEntry>> = Error<ExtractSubcommand<T[number]>>
-type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>> = ExtractSubcommand<T[number]> extends
-  Command<infer _Name, infer _Input, infer _CI, infer _E, infer _R> ? _R : never
+type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>> = Services<ExtractSubcommand<T[number]>>
 
 /**
  * Sets the description for a command.
@@ -2065,6 +2083,38 @@ export const provideEffectDiscard: {
 /* Execution                                                                  */
 /* ========================================================================== */
 
+/**
+ * Interactively constructs command-line arguments for a command.
+ *
+ * **Details**
+ *
+ * The returned arguments include the command name and can be inspected,
+ * modified, or passed to another command runner by the caller.
+ *
+ * **Example** (Constructing command arguments)
+ *
+ * ```ts
+ * import { Console, Effect } from "effect"
+ * import { Command } from "effect/unstable/cli"
+ *
+ * const command = Command.make("app")
+ *
+ * const program = Effect.gen(function*() {
+ *   const args = yield* Command.wizard(command)
+ *   yield* Console.log(args.join(" "))
+ * })
+ * ```
+ *
+ * @category command execution
+ * @since 4.0.0
+ */
+export const wizard = <Name extends string, Input, E, R, ContextInput>(
+  command: Command<Name, Input, ContextInput, E, R>,
+  options?: {
+    readonly prefix?: ReadonlyArray<string> | undefined
+  } | undefined
+): Effect.Effect<Array<string>, CliError.CliError | Terminal.QuitError, Environment> => Wizard.run(command, options)
+
 const getOutOfScopeGlobalFlagErrors = (
   allFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>,
   activeFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>,
@@ -2109,8 +2159,9 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
   error: CliError.ShowHelp
 ): 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, GlobalFlag.BuiltIns)
+    const helpDoc = yield* getHelpForCommandPath(command, error.commandPath, builtIns)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
     if (error.errors.length > 0) {
       yield* Console.error(formatter.formatErrors(error.errors as any))
@@ -2293,10 +2344,11 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
   const commandImpl = toImpl(command)
   return Effect.fnUntraced(
     function*(args: ReadonlyArray<string>) {
+      const { builtIns } = yield* CliConfig.CliConfig
       const { tokens, trailingOperands } = Lexer.lex(args)
 
       // 1. Collect known global flags from the command tree
-      const allFlags = getGlobalFlagsForCommandTree(command, GlobalFlag.BuiltIns)
+      const allFlags = getGlobalFlagsForCommandTree(command, builtIns)
 
       // 2. Extract global flag tokens
       const allFlagParams = allFlags.flatMap((f) => Param.extractSingleParams(f.flag))
@@ -2311,8 +2363,8 @@ 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 handlerCtx: GlobalFlag.HandlerContext = { command, commandPath, version: config.version }
-      const activeFlags = getGlobalFlagsForCommandPath(command, commandPath, GlobalFlag.BuiltIns)
+      const handlerCtx: GlobalFlag.HandlerContext = { builtIns, command, commandPath, version: config.version }
+      const activeFlags = getGlobalFlagsForCommandPath(command, commandPath, builtIns)
 
       // 4. Reject globals that were passed outside the active command scope
       const outOfScopeErrors = getOutOfScopeGlobalFlagErrors(allFlags, activeFlags, flagMap, commandPath)
@@ -2334,6 +2386,29 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
         })
         if (!hasEntry) continue
         const [, value] = yield* flag.flag.parse(emptyArgs)
+        if (flag === GlobalFlag.Wizard) {
+          return yield* Effect.gen(function*() {
+            yield* Console.log(Wizard.renderIntroduction(command.name, config.version, command.description))
+            const prefix = [
+              command.name,
+              ...args.filter((arg) => arg !== "--wizard" && !arg.startsWith("--wizard="))
+            ]
+            const wizardArgs = yield* Wizard.run(command, { commandPath, prefix })
+            yield* Console.log(Wizard.renderCompletion(wizardArgs))
+            const shouldRun = yield* Prompt.run(Prompt.toggle({
+              message: "Run this command?",
+              initial: true,
+              active: "yes",
+              inactive: "no"
+            }))
+            if (shouldRun) {
+              yield* Console.log()
+              yield* runWith(command, config)(wizardArgs.slice(1))
+            }
+          }).pipe(
+            Effect.catchTag("QuitError", () => Console.log(Wizard.renderQuit()))
+          )
+        }
         yield* flag.run(value, handlerCtx)
         return
       }
@@ -2352,15 +2427,16 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
 
       // 7. Provide setting values
       let program = commandImpl.handle(parseResult.success, [command.name])
+      const logLevel = activeFlags.includes(GlobalFlag.LogLevel)
+        ? (yield* GlobalFlag.LogLevel.flag.parse(emptyArgs))[1]
+        : Option.none()
+      program = Effect.provideService(program, GlobalFlag.LogLevel, logLevel)
       for (const flag of activeFlags) {
-        if (flag._tag !== "Setting") continue
+        if (flag._tag !== "Setting" || flag === GlobalFlag.LogLevel) continue
         const [, value] = yield* flag.flag.parse(emptyArgs)
         program = Effect.provideService(program, flag, value)
       }
 
-      const [, logLevel] = yield* GlobalFlag.LogLevel.flag.parse(emptyArgs)
-      program = Effect.provideService(program, GlobalFlag.LogLevel, logLevel)
-
       // 8. Apply built-in setting behavior
       const services = Option.match(logLevel, {
         onNone: () => Context.empty(),

package/src/unstable/cli/GlobalFlag.ts

@@ -5,7 +5,7 @@
  * This module defines two kinds of global flags: action flags, which run an
  * effect and stop normal command execution, and setting flags, which provide a
  * parsed value to the command handler through the Effect context. It also
- * defines the built-in help, version, shell-completion, and log-level flags
+ * defines the built-in help, version, wizard, shell-completion, and log-level flags
  * used by `Command.run` and `Command.runWith`.
  *
  * @since 4.0.0
@@ -37,6 +37,7 @@ export interface HandlerContext {
   readonly command: Command.Command.Any
   readonly commandPath: ReadonlyArray<string>
   readonly version: string
+  readonly builtIns: ReadonlyArray<BuiltIn>
 }
 
 /**
@@ -156,12 +157,11 @@ export const Help: Action<boolean> = action({
     Flag.withAlias("h"),
     Flag.withDescription("Show help information")
   ),
-  run: (_, { command, commandPath }) =>
-    Effect.gen(function*() {
-      const formatter = yield* CliOutput.Formatter
-      const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, BuiltIns)
-      yield* Console.log(formatter.formatHelpDoc(helpDoc))
-    })
+  run: Effect.fnUntraced(function*(_, { builtIns, command, commandPath }) {
+    const formatter = yield* CliOutput.Formatter
+    const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, builtIns)
+    yield* Console.log(formatter.formatHelpDoc(helpDoc))
+  })
 })
 
 /**
@@ -179,11 +179,28 @@ export const Version: Action<boolean> = action({
     Flag.withAlias("v"),
     Flag.withDescription("Show version information")
   ),
-  run: (_, { command, version }) =>
-    Effect.gen(function*() {
-      const formatter = yield* CliOutput.Formatter
-      yield* Console.log(formatter.formatVersion(command.name, version))
-    })
+  run: Effect.fnUntraced(function*(_, { command, version }) {
+    const formatter = yield* CliOutput.Formatter
+    yield* Console.log(formatter.formatVersion(command.name, version))
+  })
+})
+
+/**
+ * Defines the global action flag for starting interactive wizard mode.
+ *
+ * **Details**
+ *
+ * `Command.run` and `Command.runWith` handle this action specially so the
+ * generated arguments can be passed back through the command parser.
+ *
+ * @category references
+ * @since 4.0.0
+ */
+export const Wizard: Action<boolean> = action({
+  flag: Flag.boolean("wizard").pipe(
+    Flag.withDescription("Start wizard mode for a command")
+  ),
+  run: () => Effect.void
 })
 
 /**
@@ -206,14 +223,13 @@ export const Completions: Action<Option.Option<"bash" | "zsh" | "fish">> = actio
       Flag.withMetavar("<bash|zsh|fish|sh>"),
       Flag.withDescription("Print shell completion script")
     ),
-  run: (shell, { command }) =>
-    Effect.gen(function*() {
-      if (Option.isNone(shell)) return
-      const descriptor = CommandDescriptor.fromCommand(command)
-      yield* Console.log(
-        Completions_.generate(command.name, shell.value, descriptor)
-      )
-    })
+  run: Effect.fnUntraced(function*(shell, { command }) {
+    if (Option.isNone(shell)) return
+    const descriptor = CommandDescriptor.fromCommand(command)
+    yield* Console.log(
+      Completions_.generate(command.name, shell.value, descriptor)
+    )
+  })
 })
 
 /**
@@ -262,7 +278,7 @@ export const LogLevel: Setting<"log-level", Option.Option<LogLevelType>> = setti
  *
  * **Details**
  *
- * The built-ins are `Help`, `Version`, `Completions`, and `LogLevel`.
+ * The built-ins are `Help`, `Version`, `Wizard`, `Completions`, and `LogLevel`.
  * `Command.runWith` prepends these built-ins when collecting and parsing global
  * flags.
  *
@@ -279,17 +295,18 @@ export const LogLevel: Setting<"log-level", Option.Option<LogLevelType>> = setti
  * @category references
  * @since 4.0.0
  */
-export const BuiltIns: ReadonlyArray<GlobalFlag<any>> = [
-  Help,
-  Version,
-  Completions,
-  LogLevel
-]
+export const BuiltIns: readonly [
+  Action<boolean>,
+  Action<boolean>,
+  Action<boolean>,
+  Action<Option.Option<"bash" | "zsh" | "fish">>,
+  Setting<"log-level", Option.Option<LogLevelType>>
+] = [Help, Version, Wizard, Completions, LogLevel]
 
 /**
- * Built-in setting context identifiers.
+ * Global flag included in the default command-runner configuration.
  *
  * @category models
  * @since 4.0.0
  */
-export type BuiltInSettingContext = Setting.Identifier<"log-level">
+export type BuiltIn = typeof BuiltIns[number]