effect 4.0.0-beta.98 → 4.0.0-beta.99

package/src/Iterable.ts

@@ -5066,8 +5066,38 @@ export const cartesianWith: {
   <A, B, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): Iterable<C>
 } = dual(
   3,
-  <A, B, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): Iterable<C> =>
-    flatMap(self, (a) => map(that, (b) => f(a, b)))
+  <A, B, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): Iterable<C> => ({
+    [Symbol.iterator]() {
+      const cache: Array<B> = []
+      let iterator: Iterator<B> | undefined
+      let done = false
+      const replay: Iterable<B> = {
+        [Symbol.iterator]() {
+          let index = 0
+          return {
+            next(): IteratorResult<B> {
+              if (index < cache.length) {
+                return { done: false, value: cache[index++] }
+              }
+              if (done) {
+                return { done: true, value: undefined }
+              }
+              iterator ??= that[Symbol.iterator]()
+              const result = iterator.next()
+              if (result.done) {
+                done = true
+                return { done: true, value: undefined }
+              }
+              cache.push(result.value)
+              index++
+              return result
+            }
+          }
+        }
+      }
+      return flatMap(self, (a) => map(replay, (b) => f(a, b)))[Symbol.iterator]()
+    }
+  })
 )
 
 /**

package/src/Schema.ts

@@ -7552,7 +7552,7 @@ export function isInt(annotations?: Annotations.Filter) {
 export function isInt32(annotations?: Annotations.Filter) {
   return new SchemaAST.FilterGroup(
     [
-      isInt(annotations),
+      isInt(),
       isBetween({ minimum: -2147483648, maximum: 2147483647 })
     ],
     {

package/src/internal/effect.ts

@@ -851,10 +851,12 @@ export const fiberInterruptAll = <A extends Iterable<Fiber.Fiber<any, any>>>(
 ): Effect.Effect<void> =>
   withFiber((parent) => {
     const annotations = fiberStackAnnotations(parent)
+    let fiberArr = Arr.empty<Fiber.Fiber<any, any>>()
     for (const fiber of fibers) {
       fiber.interruptUnsafe(parent.id, annotations)
+      fiberArr.push(fiber)
     }
-    return asVoid(fiberAwaitAll(fibers))
+    return asVoid(fiberAwaitAll(fiberArr))
   })
 
 /** @internal */
@@ -867,8 +869,12 @@ export const fiberInterruptAllAs: {
 ): Effect.Effect<void> =>
   withFiber((parent) => {
     const annotations = fiberStackAnnotations(parent)
-    for (const fiber of fibers) fiber.interruptUnsafe(fiberId, annotations)
-    return asVoid(fiberAwaitAll(fibers))
+    const fiberArr = Arr.empty<Fiber.Fiber<any, any>>()
+    for (const fiber of fibers) {
+      fiber.interruptUnsafe(fiberId, annotations)
+      fiberArr.push(fiber)
+    }
+    return asVoid(fiberAwaitAll(fiberArr))
   }))
 
 /** @internal */

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

@@ -365,6 +365,9 @@ export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
     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}`
   }
 }

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.
  *
@@ -1277,8 +1295,7 @@ type ExtractSubcommand<T> = T extends Command<infer _Name, infer _Input, infer _
   : 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.
@@ -2066,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>>,
@@ -2110,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))
@@ -2294,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))
@@ -2312,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)
@@ -2335,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
       }
@@ -2353,7 +2427,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

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,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))
   })
 })
@@ -184,6 +185,24 @@ export const Version: Action<boolean> = action({
   })
 })
 
+/**
+ * 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
+})
+
 /**
  * Defines the `--completions` global flag, which prints a shell completion script for
  * the given shell.
@@ -259,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.
  *
@@ -277,8 +296,17 @@ export const LogLevel: Setting<"log-level", Option.Option<LogLevelType>> = setti
  * @since 4.0.0
  */
 export const BuiltIns: readonly [
+  Action<boolean>,
   Action<boolean>,
   Action<boolean>,
   Action<Option.Option<"bash" | "zsh" | "fish">>,
   Setting<"log-level", Option.Option<LogLevelType>>
-] = [Help, Version, Completions, LogLevel]
+] = [Help, Version, Wizard, Completions, LogLevel]
+
+/**
+ * Global flag included in the default command-runner configuration.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type BuiltIn = typeof BuiltIns[number]

package/src/unstable/cli/Param.ts

@@ -2898,9 +2898,19 @@ export const getUnderlyingSingleOrThrow = <Kind extends ParamKind, A>(
  */
 export const getParamMetadata = <Kind extends ParamKind, A>(
   param: Param<Kind, A>
-): { isOptional: boolean; isVariadic: boolean } => {
+): {
+  readonly isOptional: boolean
+  readonly isVariadic: boolean
+  readonly variadicMin: Option.Option<number>
+  readonly variadicMax: Option.Option<number>
+} => {
   return matchParam(param, {
-    Single: () => ({ isOptional: false, isVariadic: false }),
+    Single: () => ({
+      isOptional: false,
+      isVariadic: false,
+      variadicMin: Option.none(),
+      variadicMax: Option.none()
+    }),
     Map: (mapped) => getParamMetadata(mapped.param),
     Transform: (mapped) => getParamMetadata(mapped.param),
     Optional: (optional) => ({
@@ -2909,7 +2919,9 @@ export const getParamMetadata = <Kind extends ParamKind, A>(
     }),
     Variadic: (variadic) => ({
       ...getParamMetadata(variadic.param),
-      isVariadic: true
+      isVariadic: true,
+      variadicMin: variadic.min,
+      variadicMax: variadic.max
     })
   })
 }

package/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
  */

package/src/unstable/cli/internal/ansi.ts

@@ -57,6 +57,9 @@ export const red = `${ESC}31m`
 /** @internal */
 export const green = `${ESC}32m`
 
+/** @internal */
+export const magenta = `${ESC}35m`
+
 /** @internal */
 export const white = `${ESC}37m`
 

package/src/unstable/cli/internal/parser.ts

@@ -391,6 +391,18 @@ const invalidNegatedFlagValue = (
     kind: "flag"
   })
 
+const missingFlagValue = (spec: FlagParam): CliError.InvalidValue => {
+  const choices = Primitive.getChoiceKeys(spec.primitiveType)
+  return new CliError.InvalidValue({
+    option: spec.name,
+    value: "",
+    expected: choices === undefined
+      ? spec.typeName ?? Primitive.getTypeName(spec.primitiveType)
+      : choices.join(" | "),
+    kind: "flag"
+  })
+}
+
 /**
  * Checks whether a token is a boolean literal value.
  * Recognizes: true/false, yes/no, on/off, 1/0
@@ -497,8 +509,8 @@ const consumeFlagValueWithTokens = (
   }
 
   return {
-    _tag: "Value",
-    value: undefined,
+    _tag: "Error",
+    error: missingFlagValue(spec),
     tokens: []
   }
 }