effect 4.0.0-beta.2 → 4.0.0-beta.21

package/src/unstable/cli/Command.ts

@@ -1,29 +1,31 @@
 /**
  * @since 4.0.0
  */
+import type { NonEmptyArray, NonEmptyReadonlyArray } from "../../Array.ts"
 import * as Console from "../../Console.ts"
 import * as Effect from "../../Effect.ts"
 import type * as FileSystem from "../../FileSystem.ts"
 import { dual } from "../../Function.ts"
 import type * as Layer from "../../Layer.ts"
+import * as Option from "../../Option.ts"
 import type * as Path from "../../Path.ts"
 import type { Pipeable } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as References from "../../References.ts"
 import * as Result from "../../Result.ts"
-import type * as ServiceMap from "../../ServiceMap.ts"
+import * as ServiceMap from "../../ServiceMap.ts"
 import * as Terminal from "../../Terminal.ts"
-import type { Simplify } from "../../Types.ts"
+import type { NoInfer, Simplify } from "../../Types.ts"
 import type { ChildProcessSpawner } from "../process/ChildProcessSpawner.ts"
 import * as CliError from "./CliError.ts"
 import * as CliOutput from "./CliOutput.ts"
-import { checkForDuplicateFlags, getHelpForCommandPath, makeCommand, toImpl, TypeId } from "./internal/command.ts"
-import * as CommandDescriptor from "./internal/completions/CommandDescriptor.ts"
-import * as Completions from "./internal/completions/Completions.ts"
+import * as GlobalFlag from "./GlobalFlag.ts"
+import { checkForDuplicateFlags, makeCommand, toImpl, TypeId } from "./internal/command.ts"
 import { 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 type * as Param from "./Param.ts"
+import * as Param from "./Param.ts"
 
 /* ========================================================================== */
 /* Public Types                                                               */
@@ -94,16 +96,50 @@ export interface Command<Name extends string, Input, E = never, R = never> exten
    */
   readonly description: string | undefined
 
+  /**
+   * An optional short description used when listing subcommands.
+   */
+  readonly shortDescription: string | undefined
+
+  /**
+   * An optional alias that can be used as a shorter command name.
+   */
+  readonly alias: string | undefined
+
+  /**
+   * Optional usage examples for the command.
+   */
+  readonly examples: ReadonlyArray<Command.Example>
+
   /**
    * The subcommands available under this command.
    */
-  readonly subcommands: ReadonlyArray<Command.Any>
+  readonly subcommands: ReadonlyArray<{
+    readonly group: string | undefined
+    readonly commands: NonEmptyReadonlyArray<Command.Any>
+  }>
+
+  /**
+   * Custom annotations associated with this command.
+   */
+  readonly annotations: ServiceMap.ServiceMap<never>
 }
 
 /**
  * @since 4.0.0
  */
 export declare namespace Command {
+  /**
+   * Represents a concrete usage example for a command.
+   *
+   * @since 4.0.0
+   * @category models
+   */
+  export interface Example {
+    readonly command: string
+    readonly description?: string | undefined
+  }
+
   /**
    * Configuration object for defining command flags, arguments, and nested structures.
    *
@@ -209,6 +245,25 @@ export declare namespace Command {
    * @category models
    */
   export type Any = Command<string, unknown, unknown, unknown>
+
+  /**
+   * A grouped set of subcommands used by `Command.withSubcommands`.
+   *
+   * @since 4.0.0
+   * @category models
+   */
+  export interface SubcommandGroup<Commands extends ReadonlyArray<Any> = ReadonlyArray<Any>> {
+    readonly group: string
+    readonly commands: Commands
+  }
+
+  /**
+   * Entry type accepted by `Command.withSubcommands`.
+   *
+   * @since 4.0.0
+   * @category models
+   */
+  export type SubcommandEntry = Any | SubcommandGroup<ReadonlyArray<Any>>
 }
 
 /**
@@ -533,7 +588,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, R>
+  ): Command<Name, Command.Config.Infer<Config>, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>
 } = ((
   name: string,
   config?: Command.Config,
@@ -606,7 +661,7 @@ export const withHandler: {
    */
   <A, R, E>(handler: (value: A) => Effect.Effect<void, E, R>): <Name extends string, XR, XE>(
     self: Command<Name, A, XE, XR>
-  ) => Command<Name, A, E, R>
+  ) => Command<Name, A, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>
   /* ========================================================================== */
   /* Combinators                                                                */
   /* ========================================================================== */
@@ -638,11 +693,63 @@ export const withHandler: {
   <Name extends string, A, XR, XE, R, E>(
     self: Command<Name, A, XE, XR>,
     handler: (value: A) => Effect.Effect<void, E, R>
-  ): Command<Name, A, E, R>
+  ): Command<Name, A, E, Exclude<R, GlobalFlag.BuiltInSettingContext>>
 } = dual(2, <Name extends string, A, XR, XE, R, E>(
   self: Command<Name, A, XE, XR>,
   handler: (value: A) => Effect.Effect<void, E, R>
-): Command<Name, A, E, R> => makeCommand({ ...toImpl(self), handle: handler }))
+): Command<Name, A, E, Exclude<R, GlobalFlag.BuiltInSettingContext>> =>
+  makeCommand({ ...toImpl(self), handle: handler }))
+
+interface SubcommandGroupInternal {
+  readonly group: string | undefined
+  readonly commands: NonEmptyReadonlyArray<Command.Any>
+}
+
+const normalizeSubcommandEntries = (
+  entries: ReadonlyArray<Command.SubcommandEntry>
+): {
+  readonly flat: ReadonlyArray<Command.Any>
+  readonly groups: ReadonlyArray<SubcommandGroupInternal>
+} => {
+  const flat: Array<Command.Any> = []
+  const grouped = new Map<string | undefined, NonEmptyArray<Command.Any>>()
+
+  const addToGroup = (group: string | undefined, command: Command.Any): void => {
+    flat.push(command)
+    const existing = grouped.get(group)
+    if (existing) {
+      existing.push(command)
+    } else {
+      grouped.set(group, [command])
+    }
+  }
+
+  for (const entry of entries) {
+    if (isCommand(entry)) {
+      addToGroup(undefined, entry)
+      continue
+    }
+    for (const command of entry.commands) {
+      addToGroup(entry.group, command)
+    }
+  }
+
+  const groups: Array<SubcommandGroupInternal> = []
+  const ungroupedCommands = grouped.get(undefined)
+
+  if (ungroupedCommands && ungroupedCommands.length > 0) {
+    groups.push({ group: undefined, commands: ungroupedCommands })
+  }
+
+  for (const [group, commands] of grouped) {
+    if (group === undefined) {
+      continue
+    }
+    groups.push({ group, commands })
+  }
+
+  return { flat, groups }
+}
 
 /**
  * Adds subcommands to a command, creating a hierarchical command structure.
@@ -717,7 +824,7 @@ export const withSubcommands: {
    * @since 4.0.0
    * @category combinators
    */
-  <const Subcommands extends ReadonlyArray<Command<any, any, any, any>>>(subcommands: Subcommands): <Name extends string, Input, E, R>(
+  <const Subcommands extends ReadonlyArray<Command.SubcommandEntry>>(subcommands: Subcommands): <Name extends string, Input, E, R>(
     self: Command<Name, Input, E, R>
   ) => Command<
     Name,
@@ -766,7 +873,7 @@ export const withSubcommands: {
     Input,
     E,
     R,
-    const Subcommands extends ReadonlyArray<Command<any, any, any, any>>
+    const Subcommands extends ReadonlyArray<Command.SubcommandEntry>
   >(self: Command<Name, Input, E, R>, subcommands: Subcommands): Command<
     Name,
     Input,
@@ -778,7 +885,7 @@ export const withSubcommands: {
   Input,
   E,
   R,
-  const Subcommands extends ReadonlyArray<Command<any, any, any, any>>
+  const Subcommands extends ReadonlyArray<Command.SubcommandEntry>
 >(
   self: Command<Name, Input, E, R>,
   subcommands: Subcommands
@@ -788,10 +895,11 @@ export const withSubcommands: {
   E | ExtractSubcommandErrors<Subcommands>,
   R | Exclude<ExtractSubcommandContext<Subcommands>, CommandContext<Name>>
 > => {
-  checkForDuplicateFlags(self, subcommands)
+  const normalized = normalizeSubcommandEntries(subcommands)
+  checkForDuplicateFlags(self, normalized.flat)
 
   const impl = toImpl(self)
-  const byName = new Map(subcommands.map((s) => [s.name, toImpl(s)] as const))
+  const byName = new Map(normalized.flat.map((s) => [s.name, toImpl(s)] as const))
 
   // Internal type for routing - not exposed in public type
   type SubcommandInfo = { readonly name: string; readonly result: unknown }
@@ -832,16 +940,69 @@ export const withSubcommands: {
     name: impl.name,
     config: impl.config,
     description: impl.description,
+    shortDescription: impl.shortDescription,
+    alias: impl.alias,
+    annotations: impl.annotations,
+    globalFlags: impl.globalFlags,
+    examples: impl.examples,
     service: impl.service,
-    subcommands,
+    subcommands: normalized.groups,
     parse,
     handle
   })
 })
 
+/**
+ * Declares global flags for a command scope.
+ *
+ * Declared global flags apply to the command and all of its descendants.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withGlobalFlags: {
+  /**
+   * Declares global flags for a command scope.
+   *
+   * Declared global flags apply to the command and all of its descendants.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const GlobalFlags extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>>(globalFlags: GlobalFlags): <Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>>
+  /**
+   * Declares global flags for a command scope.
+   *
+   * Declared global flags apply to the command and all of its descendants.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <Name extends string, Input, E, R, const GlobalFlags extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>>(self: Command<Name, Input, E, R>, globalFlags: GlobalFlags): Command<Name, Input, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>>
+} = dual(
+  2,
+  <Name extends string, Input, E, R, const GlobalFlags extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>>(
+    self: Command<Name, Input, E, R>,
+    globalFlags: GlobalFlags
+  ): Command<Name, Input, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>> => {
+    const impl = toImpl(self)
+    const next = Array.from(new Set([...impl.globalFlags, ...globalFlags]))
+    return makeCommand({ ...impl, globalFlags: next })
+  }
+)
+
 // Type extractors for subcommand arrays - T[number] gives union of all elements
-type ExtractSubcommandErrors<T extends ReadonlyArray<Command<any, any, any, any>>> = Error<T[number]>
-type ExtractSubcommandContext<T extends ReadonlyArray<Command<any, any, any, any>>> = T[number] extends
+type ExtractGlobalFlagContext<T extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>> = T[number] extends infer F
+  ? F extends GlobalFlag.Setting<infer Id, any> ? GlobalFlag.Setting.Identifier<Id>
+  : never
+  : never
+type ExtractSubcommand<T> = T extends Command<any, any, any, any> ? 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<any, any, any, infer R> ? R : never
 
 /**
@@ -926,6 +1087,223 @@ export const withDescription: {
   description: string
 ) => makeCommand({ ...toImpl(self), description }))
 
+/**
+ * Sets a short description for a command.
+ *
+ * Short descriptions are used when listing subcommands in help output and
+ * shell completions. If no short description is provided, the full
+ * `description` is used as a fallback.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withShortDescription: {
+  /**
+   * Sets a short description for a command.
+   *
+   * Short descriptions are used when listing subcommands in help output and
+   * shell completions. If no short description is provided, the full
+   * `description` is used as a fallback.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (shortDescription: string): <const Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Sets a short description for a command.
+   *
+   * Short descriptions are used when listing subcommands in help output and
+   * shell completions. If no short description is provided, the full
+   * `description` is used as a fallback.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const Name extends string, Input, E, R>(self: Command<Name, Input, E, R>, shortDescription: string): Command<Name, Input, E, R>
+} = dual(2, <const Name extends string, Input, E, R>(
+  self: Command<Name, Input, E, R>,
+  shortDescription: string
+) => makeCommand({ ...toImpl(self), shortDescription }))
+
+/**
+ * Sets an alias for a command.
+ *
+ * Aliases are accepted as alternate subcommand names during parsing and are
+ * shown in help output as `name, alias`.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withAlias: {
+  /**
+   * Sets an alias for a command.
+   *
+   * Aliases are accepted as alternate subcommand names during parsing and are
+   * shown in help output as `name, alias`.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (alias: string): <const Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Sets an alias for a command.
+   *
+   * Aliases are accepted as alternate subcommand names during parsing and are
+   * shown in help output as `name, alias`.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const Name extends string, Input, E, R>(self: Command<Name, Input, E, R>, alias: string): Command<Name, Input, E, R>
+} = dual(2, <const Name extends string, Input, E, R>(
+  self: Command<Name, Input, E, R>,
+  alias: string
+) => makeCommand({ ...toImpl(self), alias }))
+
+/**
+ * Adds a custom annotation to a command.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const annotate: {
+  /**
+   * Adds a custom annotation to a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <I, S>(service: ServiceMap.Key<I, S>, value: NoInfer<S>): <Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Adds a custom annotation to a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <Name extends string, Input, E, R, I, S>(
+    self: Command<Name, Input, E, R>,
+    service: ServiceMap.Key<I, S>,
+    value: NoInfer<S>
+  ): Command<Name, Input, E, R>
+} = dual(3, <Name extends string, Input, E, R, I, S>(
+  self: Command<Name, Input, E, R>,
+  service: ServiceMap.Key<I, S>,
+  value: NoInfer<S>
+) => {
+  const impl = toImpl(self)
+  return makeCommand({ ...impl, annotations: ServiceMap.add(impl.annotations, service, value) })
+})
+
+/**
+ * Merges a ServiceMap of annotations into a command.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const annotateMerge: {
+  /**
+   * Merges a ServiceMap of annotations into a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <I>(annotations: ServiceMap.ServiceMap<I>): <Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Merges a ServiceMap of annotations into a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <Name extends string, Input, E, R, I>(self: Command<Name, Input, E, R>, annotations: ServiceMap.ServiceMap<I>): Command<Name, Input, E, R>
+} = dual(2, <Name extends string, Input, E, R, I>(
+  self: Command<Name, Input, E, R>,
+  annotations: ServiceMap.ServiceMap<I>
+) => {
+  const impl = toImpl(self)
+  return makeCommand({ ...impl, annotations: ServiceMap.merge(impl.annotations, annotations) })
+})
+
+/**
+ * Sets usage examples for a command.
+ *
+ * Examples are exposed in structured `HelpDoc` data and rendered by the
+ * default formatter in an `EXAMPLES` section.
+ *
+ * @example
+ * ```ts
+ * import { Command } from "effect/unstable/cli"
+ *
+ * const login = Command.make("login").pipe(
+ *   Command.withExamples([
+ *     { command: "myapp login", description: "Log in with browser OAuth" },
+ *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
+ *   ])
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withExamples: {
+  /**
+   * Sets usage examples for a command.
+   *
+   * Examples are exposed in structured `HelpDoc` data and rendered by the
+   * default formatter in an `EXAMPLES` section.
+   *
+   * @example
+   * ```ts
+   * import { Command } from "effect/unstable/cli"
+   *
+   * const login = Command.make("login").pipe(
+   *   Command.withExamples([
+   *     { command: "myapp login", description: "Log in with browser OAuth" },
+   *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
+   *   ])
+   * )
+   * ```
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (examples: ReadonlyArray<Command.Example>): <const Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Sets usage examples for a command.
+   *
+   * Examples are exposed in structured `HelpDoc` data and rendered by the
+   * default formatter in an `EXAMPLES` section.
+   *
+   * @example
+   * ```ts
+   * import { Command } from "effect/unstable/cli"
+   *
+   * const login = Command.make("login").pipe(
+   *   Command.withExamples([
+   *     { command: "myapp login", description: "Log in with browser OAuth" },
+   *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
+   *   ])
+   * )
+   * ```
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const Name extends string, Input, E, R>(self: Command<Name, Input, E, R>, examples: ReadonlyArray<Command.Example>): Command<Name, Input, E, R>
+} = dual(2, <const Name extends string, Input, E, R>(
+  self: Command<Name, Input, E, R>,
+  examples: ReadonlyArray<Command.Example>
+) => makeCommand({ ...toImpl(self), examples }))
+
 /* ========================================================================== */
 /* Providing Services                                                         */
 /* ========================================================================== */
@@ -1088,10 +1466,7 @@ export const provideSync: {
    * @since 4.0.0
    * @category providing services
    */
-  <I, S, Input>(
-    service: ServiceMap.Service<I, S>,
-    implementation: S | ((input: Input) => S)
-  ): <const Name extends string, E, R>(
+  <I, S, Input>(service: ServiceMap.Key<I, S>, implementation: S | ((input: Input) => S)): <const Name extends string, E, R>(
     self: Command<Name, Input, E, R>
   ) => Command<Name, Input, E, Exclude<R, I>>
   /**
@@ -1103,12 +1478,12 @@ export const provideSync: {
    */
   <const Name extends string, Input, E, R, I, S>(
     self: Command<Name, Input, E, R>,
-    service: ServiceMap.Service<I, S>,
+    service: ServiceMap.Key<I, S>,
     implementation: S | ((input: Input) => S)
   ): Command<Name, Input, E, Exclude<R, I>>
 } = dual(3, <const Name extends string, Input, E, R, I, S>(
   self: Command<Name, Input, E, R>,
-  service: ServiceMap.Service<I, S>,
+  service: ServiceMap.Key<I, S>,
   implementation: S | ((input: Input) => S)
 ) =>
   mapHandler(self, (handler, input) =>
@@ -1134,7 +1509,7 @@ export const provideEffect: {
    * @category providing services
    */
   <I, S, Input, R2, E2>(
-    service: ServiceMap.Service<I, S>,
+    service: ServiceMap.Key<I, S>,
     effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)
   ): <const Name extends string, E, R>(
     self: Command<Name, Input, E, R>
@@ -1148,12 +1523,12 @@ export const provideEffect: {
    */
   <const Name extends string, Input, E, R, I, S, R2, E2>(
     self: Command<Name, Input, E, R>,
-    service: ServiceMap.Service<I, S>,
+    service: ServiceMap.Key<I, S>,
     effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)
   ): Command<Name, Input, E | E2, Exclude<R, I> | R2>
 } = dual(3, <const Name extends string, Input, E, R, I, S, R2, E2>(
   self: Command<Name, Input, E, R>,
-  service: ServiceMap.Service<I, S>,
+  service: ServiceMap.Key<I, S>,
   effect: Effect.Effect<S, E2, R2> | ((input: Input) => Effect.Effect<S, E2, R2>)
 ) =>
   mapHandler(
@@ -1203,6 +1578,45 @@ export const provideEffectDiscard: {
 /* Execution                                                                  */
 /* ========================================================================== */
 
+const getOutOfScopeGlobalFlagErrors = (
+  allFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>,
+  activeFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>,
+  flagMap: Record<string, ReadonlyArray<string>>,
+  commandPath: ReadonlyArray<string>
+): ReadonlyArray<CliError.CliError> => {
+  const activeSet = new Set(activeFlags)
+  const errors: Array<CliError.CliError> = []
+  const seen = new Set<string>()
+
+  for (const flag of allFlags) {
+    if (activeSet.has(flag)) {
+      continue
+    }
+
+    const singles = Param.extractSingleParams(flag.flag)
+    for (const single of singles) {
+      const entries = flagMap[single.name]
+      if (!entries || entries.length === 0) {
+        continue
+      }
+      const option = `--${single.name}`
+      if (seen.has(option)) {
+        continue
+      }
+      seen.add(option)
+      errors.push(
+        new CliError.UnrecognizedOption({
+          option,
+          suggestions: [],
+          command: commandPath
+        })
+      )
+    }
+  }
+
+  return errors
+}
+
 const showHelp = <Name extends string, Input, E, R>(
   command: Command<Name, Input, E, R>,
   commandPath: ReadonlyArray<string>,
@@ -1210,7 +1624,7 @@ const showHelp = <Name extends string, Input, E, R>(
 ): Effect.Effect<void, never, Environment> =>
   Effect.gen(function*() {
     const formatter = yield* CliOutput.Formatter
-    const helpDoc = getHelpForCommandPath(command, commandPath)
+    const helpDoc = yield* getHelpForCommandPath(command, commandPath, GlobalFlag.BuiltIns)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
     if (errors && errors.length > 0) {
       yield* Console.error(formatter.formatErrors(errors))
@@ -1266,12 +1680,13 @@ export const run: {
    * @since 4.0.0
    * @category command execution
    */
-  <Name extends string, Input, E, R>(
-    command: Command<Name, Input, E, R>,
+  (
     config: {
       readonly version: string
     }
-  ): Effect.Effect<void, E | CliError.CliError, R | Environment>
+  ): <Name extends string, Input, E, R>(
+    command: Command<Name, Input, E, R>
+  ) => Effect.Effect<void, E | CliError.CliError, R | Environment>
   /**
    * Runs a command with the provided input arguments.
    *
@@ -1296,13 +1711,12 @@ export const run: {
    * @since 4.0.0
    * @category command execution
    */
-  (
+  <Name extends string, Input, E, R>(
+    command: Command<Name, Input, E, R>,
     config: {
       readonly version: string
     }
-  ): <Name extends string, Input, E, R>(
-    command: Command<Name, Input, E, R>
-  ) => Effect.Effect<void, E | CliError.CliError, R | Environment>
+  ): Effect.Effect<void, E | CliError.CliError, R | Environment>
 } = dual(2, <Name extends string, Input, E, R>(
   command: Command<Name, Input, E, R>,
   config: {
@@ -1365,29 +1779,45 @@ export const runWith = <const Name extends string, Input, E, R>(
   const commandImpl = toImpl(command)
   return Effect.fnUntraced(
     function*(args: ReadonlyArray<string>) {
-      // Lex and extract built-in flags
       const { tokens, trailingOperands } = Lexer.lex(args)
-      const { completions, help, logLevel, remainder, version } = yield* Parser.extractBuiltInOptions(tokens)
+
+      // 1. Collect known global flags from the command tree
+      const allFlags = getGlobalFlagsForCommandTree(command, GlobalFlag.BuiltIns)
+
+      // 2. Extract global flag tokens
+      const allFlagParams = allFlags.flatMap((f) => Param.extractSingleParams(f.flag))
+      const globalRegistry = Parser.createFlagRegistry(allFlagParams.filter(Param.isFlagParam))
+      const { flagMap, remainder } = Parser.consumeKnownFlags(tokens, globalRegistry)
+      const emptyArgs: Param.ParsedArgs = { flags: flagMap, arguments: [] }
+
+      // 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 formatter = yield* CliOutput.Formatter
+      const handlerCtx: GlobalFlag.HandlerContext = { command, commandPath, version: config.version }
+      const activeFlags = getGlobalFlagsForCommandPath(command, commandPath, GlobalFlag.BuiltIns)
 
-      // Handle built-in flags (early exits)
-      if (help) {
-        yield* Console.log(formatter.formatHelpDoc(getHelpForCommandPath(command, commandPath)))
-        return
-      }
-      if (completions !== undefined) {
-        const descriptor = CommandDescriptor.fromCommand(command)
-        yield* Console.log(Completions.generate(command.name, completions, descriptor))
-        return
+      // 4. Reject globals that were passed outside the active command scope
+      const outOfScopeErrors = getOutOfScopeGlobalFlagErrors(allFlags, activeFlags, flagMap, commandPath)
+      if (outOfScopeErrors.length > 0) {
+        const parseErrors = parsedArgs.errors ?? []
+        return yield* showHelp(command, commandPath, [...outOfScopeErrors, ...parseErrors])
       }
-      if (version) {
-        yield* Console.log(formatter.formatVersion(command.name, config.version))
+
+      // 5. Process action flags — first present action wins, then exit
+      for (const flag of activeFlags) {
+        if (flag._tag !== "Action") continue
+        const singles = Param.extractSingleParams(flag.flag)
+        const hasEntry = singles.some((s) => {
+          const entries = flagMap[s.name]
+          return entries !== undefined && entries.length > 0
+        })
+        if (!hasEntry) continue
+        const [, value] = yield* flag.flag.parse(emptyArgs)
+        yield* flag.run(value, handlerCtx)
         return
       }
 
-      // Handle parsing errors
+      // 6. Handle parsing errors
       if (parsedArgs.errors && parsedArgs.errors.length > 0) {
         return yield* showHelp(command, commandPath, parsedArgs.errors)
       }
@@ -1395,24 +1825,35 @@ export const runWith = <const Name extends string, Input, E, R>(
       if (parseResult._tag === "Failure") {
         return yield* showHelp(command, commandPath, [parseResult.failure])
       }
-      const parsed = parseResult.success
 
-      // Create and run the execution program
-      const program = commandImpl.handle(parsed, [command.name])
-      const withLogLevel = logLevel !== undefined
-        ? Effect.provideService(program, References.MinimumLogLevel, logLevel)
-        : program
+      // 7. Provide setting values
+      let program = commandImpl.handle(parseResult.success, [command.name])
+      for (const flag of activeFlags) {
+        if (flag._tag !== "Setting") 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: () => ServiceMap.empty(),
+        onSome: (level) => ServiceMap.make(References.MinimumLogLevel, level)
+      })
 
-      yield* withLogLevel
+      // 9. Run command handler with composed context
+      yield* Effect.provideServices(program, services)
     },
-    Effect.catchIf(
+    Effect.catchFilter(
       ((error: any) =>
         CliError.isCliError(error) && error._tag === "ShowHelp"
           ? Result.succeed(error)
           : Result.fail(error)) as any,
       (error: any) => showHelp(command, error.commandPath)
     ),
-    Effect.catchIf(
+    Effect.catchFilter(
       (e) =>
         Terminal.isQuitError(e)
           ? Result.succeed(e)