Add CLI config for built-in flags (#6397)

Author: IMax153

.changeset/cli-config-built-ins.md

@@ -0,0 +1,24 @@
+---
+"effect": patch
+---
+
+Add a scoped `CliConfig` service for customizing the built-in global flags used by CLI command runners.
+
+For example, provide an explicit list that omits `GlobalFlag.LogLevel` to remove the built-in `--log-level` flag:
+
+```ts
+import { Effect } from "effect"
+import { CliConfig, Command, GlobalFlag } from "effect/unstable/cli"
+
+const program = Command.run(command, { version: "1.0.0" }).pipe(
+  Effect.provide(
+    CliConfig.layer({
+      builtIns: [
+        GlobalFlag.Help,
+        GlobalFlag.Version,
+        GlobalFlag.Completions
+      ]
+    })
+  )
+)
+```

packages/effect/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))

packages/effect/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"
@@ -1412,8 +1413,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))
@@ -1530,10 +1532,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))
@@ -1548,8 +1551,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)
@@ -1589,7 +1592,9 @@ 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] = yield* GlobalFlag.LogLevel.flag.parse(emptyArgs)
+      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" || flag === GlobalFlag.LogLevel) continue

packages/effect/src/unstable/cli/GlobalFlag.ts

@@ -37,6 +37,7 @@ export interface HandlerContext {
   readonly command: Command.Command.Any
   readonly commandPath: ReadonlyArray<string>
   readonly version: string
+  readonly builtIns: ReadonlyArray<BuiltIn>
 }
 
 /**
@@ -156,9 +157,9 @@ export const Help: Action<boolean> = action({
     Flag.withAlias("h"),
     Flag.withDescription("Show help information")
   ),
-  run: Effect.fnUntraced(function*(_, { command, commandPath }) {
+  run: Effect.fnUntraced(function*(_, { builtIns, command, commandPath }) {
     const formatter = yield* CliOutput.Formatter
-    const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, BuiltIns)
+    const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, builtIns)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
   })
 })
@@ -282,3 +283,11 @@ export const BuiltIns: readonly [
   Action<Option.Option<"bash" | "zsh" | "fish">>,
   Setting<"log-level", Option.Option<LogLevelType>>
 ] = [Help, Version, Completions, LogLevel]
+
+/**
+ * Global flag included in the default command-runner configuration.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type BuiltIn = typeof BuiltIns[number]

packages/effect/src/unstable/cli/index.ts

@@ -9,6 +9,11 @@
  */
 export * as Argument from "./Argument.ts"
 
+/**
+ * @since 4.0.0
+ */
+export * as CliConfig from "./CliConfig.ts"
+
 /**
  * @since 4.0.0
  */

packages/effect/test/unstable/cli/Command.test.ts

@@ -1,7 +1,7 @@
 import { assert, describe, expect, it } from "@effect/vitest"
 import { Context, Effect, FileSystem, Layer, Option, Path, Stdio } from "effect"
 import { TestConsole } from "effect/testing"
-import { Argument, CliOutput, Command, Flag, GlobalFlag } from "effect/unstable/cli"
+import { Argument, CliConfig, CliOutput, Command, Flag, GlobalFlag } from "effect/unstable/cli"
 import { toImpl } from "effect/unstable/cli/internal/command"
 import { ChildProcessSpawner } from "effect/unstable/process"
 import * as Cli from "./fixtures/ComprehensiveCli.ts"
@@ -346,6 +346,32 @@ describe("Command", () => {
         assert.deepStrictEqual(captured, ["eu-west-1", "us-west-2"])
       }).pipe(Effect.provide(TestLayer)))
 
+    it.effect("should configure built-in global flags per run", () =>
+      Effect.gen(function*() {
+        const command = Command.make("app", {}, () => Effect.void)
+        const runCommand = Command.runWith(command, { version: "1.0.0" })
+        const config = CliConfig.make({
+          builtIns: GlobalFlag.BuiltIns.filter((flag) => flag !== GlobalFlag.LogLevel)
+        })
+
+        yield* runCommand(["--help"]).pipe(Effect.provide(CliConfig.layer(config)))
+        const configuredHelp = yield* TestConsole.logLines
+        assert.isFalse(configuredHelp.some((line) => String(line).includes("--log-level")))
+
+        yield* runCommand(["--log-level", "debug"]).pipe(
+          Effect.provideService(CliConfig.CliConfig, config),
+          Effect.ignore
+        )
+        const errors = yield* TestConsole.errorLines
+        assert.isTrue(errors.some((line) => String(line).includes("Unrecognized flag: --log-level")))
+
+        const helpCountBeforeDefault = (yield* TestConsole.logLines).length
+        yield* runCommand(["--help"])
+        const allHelp = yield* TestConsole.logLines
+        const defaultHelp = allHelp.slice(helpCountBeforeDefault)
+        assert.isTrue(defaultHelp.some((line) => String(line).includes("--log-level")))
+      }).pipe(Effect.provide(TestLayer)))
+
     it.effect("should support mixed action and setting global flags", () =>
       Effect.gen(function*() {
         const actions: Array<boolean> = []