feat(cli): add withConditionalBehavior combinator for conditional command behaviors

Introduces a composable combinator approach for adding conditional behaviors to commands.
Instead of having separate runWith* methods, this provides a single, extensible pattern.

Key features:
- Command.withConditionalBehavior() wraps commands with conditional behavior
- Predicate function determines when behavior should trigger
- Supports built-in "wizard" mode or custom behavior functions
- Fully composable with other Command combinators via .pipe()
- Backwards compatible with existing --wizard flag

Example usage:
```typescript
const command = Command.make("greet", {
  name: Options.text("name")
}, ({ name }) => Effect.log(`Hello, ${name}!`))
  .pipe(
    Command.withConditionalBehavior(
      (args) => args.length <= 1,  // Run wizard when no args provided
      "wizard"
    )
  )

Command.run(command, { name: "MyApp", version: "1.0.0" })
```

This design avoids API explosion (runWithWizard, runWithHelp, etc.) and follows
functional composition patterns. The same combinator can be extended for other
conditional behaviors like help display, validation, or custom prompting.

Fixes #5699

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ryanbas21

.changeset/soft-oranges-arrive.md

@@ -0,0 +1,7 @@
+---
+"@effect/cli": minor
+---
+
+Add withConditionalBehavior combinator for composable conditional command behaviors
+
+Introduces a new `withConditionalBehavior` combinator that allows wrapping commands with conditional behaviors based on CLI arguments. This composable approach replaces the need for separate `runWith*` methods and can be used for wizard mode, help display, or any custom behavior.

packages/cli/src/Command.ts

@@ -441,3 +441,61 @@ export const run: {
     config: Omit<CliApp.ConstructorArgs<never>, "command">
   ): (args: ReadonlyArray<string>) => Effect<void, E | ValidationError, R | CliApp.Environment>
 } = Internal.run
+
+/**
+ * A combinator that wraps a command to conditionally trigger a behavior (like wizard mode)
+ * based on a predicate function evaluated against the CLI arguments.
+ * 
+ * This is a composable approach to adding conditional behaviors to commands. Instead of
+ * having separate `runWith*` methods for each behavior, this single combinator can handle
+ * wizard mode, help display, or any custom behavior.
+ *
+ * @example
+ * ```typescript
+ * import { Command, Options } from "@effect/cli"
+ * import { Effect } from "effect"
+ * 
+ * const command = Command.make("greet", {
+ *   name: Options.text("name")
+ * }, ({ name }) => 
+ *   Effect.log(\`Hello, \${name}!\`)
+ * )
+ * 
+ * // Run wizard mode when no arguments are provided (besides the command name)
+ * const commandWithWizard = Command.withConditionalBehavior(
+ *   command,
+ *   (args) => args.length <= 1,
+ *   "wizard"
+ * )
+ * 
+ * const cli = Command.run(commandWithWizard, {
+ *   name: "MyApp",
+ *   version: "1.0.0"
+ * })
+ * 
+ * // Running \`mycli\` (no args) will start wizard mode
+ * // Running \`mycli --name John\` will execute normally
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const withConditionalBehavior: {
+  <Name extends string, R, E, A>(
+    predicate: (args: ReadonlyArray<string>) => boolean,
+    behavior: "wizard" | ((
+      command: Command<Name, R, E, A>,
+      args: ReadonlyArray<string>
+    ) => Effect<ReadonlyArray<string>, QuitException | ValidationError, FileSystem | Path | Terminal>)
+  ): (
+    self: Command<Name, R, E, A>
+  ) => Command<Name, R, E, A>
+  <Name extends string, R, E, A>(
+    self: Command<Name, R, E, A>,
+    predicate: (args: ReadonlyArray<string>) => boolean,
+    behavior: "wizard" | ((
+      command: Command<Name, R, E, A>,
+      args: ReadonlyArray<string>
+    ) => Effect<ReadonlyArray<string>, QuitException | ValidationError, FileSystem | Path | Terminal>)
+  ): Command<Name, R, E, A>
+} = Internal.withConditionalBehavior

packages/cli/src/internal/command.ts

@@ -25,6 +25,7 @@ import type * as Usage from "../Usage.js"
 import * as ValidationError from "../ValidationError.js"
 import * as InternalArgs from "./args.js"
 import * as InternalCliApp from "./cliApp.js"
+import * as InternalCliConfig from "./cliConfig.js"
 import * as InternalDescriptor from "./commandDescriptor.js"
 import * as InternalOptions from "./options.js"
 
@@ -556,5 +557,77 @@ export const run = dual<
   })
   registeredDescriptors.set(self.tag, self.descriptor)
   const handler = (args: any) => self.transform(self.handler(args), args)
-  return (args) => InternalCliApp.run(app, args, handler)
+  const normalRun = (args: ReadonlyArray<string>) => InternalCliApp.run(app, args, handler)
+  
+  // Check if the command has conditional behavior attached
+  const conditionalBehavior = (self as any).conditionalBehavior
+  if (conditionalBehavior) {
+    const { predicate, behavior } = conditionalBehavior
+    
+    return (args) => {
+      // If the predicate matches, run the behavior first
+      if (predicate(args)) {
+        // Determine which behavior to run
+        const behaviorEffect = behavior === "wizard"
+          ? wizard(self, Arr.take(args, 1), InternalCliConfig.defaultConfig)
+          : behavior(self, args)
+        
+        // Run the behavior to get new args, then run normally with those args
+        return Effect.flatMap(
+          behaviorEffect,
+          (newArgs: ReadonlyArray<string>) => normalRun(newArgs)
+        )
+      }
+      
+      // Predicate didn't match, run normally
+      return normalRun(args)
+    }
+  }
+  
+  return normalRun
+})
+
+/** @internal */
+export const withConditionalBehavior = dual<
+  <Name extends string, R, E, A>(
+    predicate: (args: ReadonlyArray<string>) => boolean,
+    behavior: "wizard" | ((
+      command: Command.Command<Name, R, E, A>,
+      args: ReadonlyArray<string>
+    ) => Effect.Effect<
+      ReadonlyArray<string>,
+      Terminal.QuitException | ValidationError.ValidationError,
+      FileSystem.FileSystem | Path.Path | Terminal.Terminal
+    >)
+  ) => (
+    self: Command.Command<Name, R, E, A>
+  ) => Command.Command<Name, R, E, A>,
+  <Name extends string, R, E, A>(
+    self: Command.Command<Name, R, E, A>,
+    predicate: (args: ReadonlyArray<string>) => boolean,
+    behavior: "wizard" | ((
+      command: Command.Command<Name, R, E, A>,
+      args: ReadonlyArray<string>
+    ) => Effect.Effect<
+      ReadonlyArray<string>,
+      Terminal.QuitException | ValidationError.ValidationError,
+      FileSystem.FileSystem | Path.Path | Terminal.Terminal
+    >)
+  ) => Command.Command<Name, R, E, A>
+>(3, <Name extends string, R, E, A>(
+  self: Command.Command<Name, R, E, A>,
+  predicate: (args: ReadonlyArray<string>) => boolean,
+  behavior: "wizard" | ((
+    command: Command.Command<Name, R, E, A>,
+    args: ReadonlyArray<string>
+  ) => Effect.Effect<
+    ReadonlyArray<string>,
+    Terminal.QuitException | ValidationError.ValidationError,
+    FileSystem.FileSystem | Path.Path | Terminal.Terminal
+  >)
+): Command.Command<Name, R, E, A> => {
+  const command: Command.Command<Name, R, E, A> = makeDerive(self, {})
+  // Store the conditional behavior metadata on the command
+  ;(command as any).conditionalBehavior = { predicate, behavior }
+  return command
 })

packages/cli/test/Wizard.test.ts

@@ -1,4 +1,5 @@
 import type * as CliApp from "@effect/cli/CliApp"
+import * as Args from "@effect/cli/Args"
 import * as Command from "@effect/cli/Command"
 import * as Options from "@effect/cli/Options"
 import { NodeFileSystem, NodePath } from "@effect/platform-node"
@@ -41,4 +42,60 @@ describe("Wizard", () => {
       const result = Array.some(lines, (line) => line.includes("Quitting wizard mode..."))
       expect(result).toBe(true)
     }).pipe(runEffect))
+
+  describe("withConditionalBehavior", () => {
+    it("should skip wizard mode when predicate returns false", () =>
+      Effect.gen(function*() {
+        let executedWithName: string | undefined
+        const command = Command.make("greet", {
+          name: Options.text("name")
+        }, ({ name }) => Effect.sync(() => { executedWithName = name })).pipe(
+          Command.withDescription("Greet someone"),
+          Command.withConditionalBehavior((args) => args.length <= 1, "wizard")
+        )
+
+        const cli = Command.run(command, {
+          name: "Test",
+          version: "1.0.0"
+        })
+
+        // Simulate running with args (should NOT trigger wizard)
+        const args = Array.make("node", "greet", "--name", "Bob")
+        yield* cli(args)
+
+        // Verify the command was executed with the provided value
+        expect(executedWithName).toBe("Bob")
+
+        const lines = yield* MockConsole.getLines({ stripAnsi: true })
+        const wizardStarted = Array.some(lines, (line) =>
+          line.includes("Wizard Mode") || line.includes("wizard")
+        )
+        // Wizard should NOT have been started
+        expect(wizardStarted).toBe(false)
+      }).pipe(runEffect))
+
+    it("should use standard wizard flag when predicate is not met", () =>
+      Effect.gen(function*() {
+        const command = Command.make("foo", { message: Options.text("message") }).pipe(
+          Command.withConditionalBehavior((args) => args.length <= 1, "wizard")
+        )
+
+        const cli = Command.run(command, {
+          name: "Test",
+          version: "1.0.0"
+        })
+
+        // Using --wizard flag explicitly (predicate returns false because args.length > 1)
+        const args = Array.make("node", "test", "--wizard")
+        const fiber = yield* Effect.fork(cli(args))
+        yield* MockTerminal.inputKey("c", { ctrl: true })
+        yield* Fiber.join(fiber)
+
+        const lines = yield* MockConsole.getLines({ stripAnsi: true })
+        const result = Array.some(lines, (line) => line.includes("Quitting wizard mode..."))
+        expect(result).toBe(true)
+      }).pipe(runEffect))
+
+    // TODO: Add test for custom behavior functions once the implementation is finalized
+  })
 })