effect 4.0.0-beta.13 → 4.0.0-beta.15

package/src/internal/effect.ts

@@ -50,7 +50,9 @@ import type {
   ExcludeTag,
   ExtractReason,
   ExtractTag,
+  NarrowReason,
   NoInfer,
+  OmitReason,
   ReasonOf,
   ReasonTags,
   Simplify,
@@ -2824,8 +2826,16 @@ export const catchReason: {
   >(
     errorTag: K,
     reasonTag: RK,
-    f: (reason: ExtractReason<ExtractTag<NoInfer<E>, K>, RK>) => Effect.Effect<A2, E2, R2>,
-    orElse?: ((reasons: ExcludeReason<ExtractTag<NoInfer<E>, K>, RK>) => Effect.Effect<A3, E3, R3>) | undefined
+    f: (
+      reason: ExtractReason<ExtractTag<NoInfer<E>, K>, RK>,
+      error: NarrowReason<ExtractTag<NoInfer<E>, K>, RK>
+    ) => Effect.Effect<A2, E2, R2>,
+    orElse?:
+      | ((
+        reasons: ExcludeReason<ExtractTag<NoInfer<E>, K>, RK>,
+        error: OmitReason<ExtractTag<NoInfer<E>, K>, RK>
+      ) => Effect.Effect<A3, E3, R3>)
+      | undefined
   ): <A, R>(
     self: Effect.Effect<A, E, R>
   ) => Effect.Effect<
@@ -2849,8 +2859,16 @@ export const catchReason: {
     self: Effect.Effect<A, E, R>,
     errorTag: K,
     reasonTag: RK,
-    f: (reason: ExtractReason<ExtractTag<E, K>, RK>) => Effect.Effect<A2, E2, R2>,
-    orElse?: ((reasons: ExcludeReason<ExtractTag<E, K>, RK>) => Effect.Effect<A3, E3, R3>) | undefined
+    f: (
+      reason: ExtractReason<ExtractTag<E, K>, RK>,
+      error: NarrowReason<ExtractTag<E, K>, RK>
+    ) => Effect.Effect<A2, E2, R2>,
+    orElse?:
+      | ((
+        reasons: ExcludeReason<ExtractTag<E, K>, RK>,
+        error: OmitReason<ExtractTag<E, K>, RK>
+      ) => Effect.Effect<A3, E3, R3>)
+      | undefined
   ): Effect.Effect<
     A | A2 | Exclude<A3, unassigned>,
     (A3 extends unassigned ? E : ExcludeTag<E, K>) | E2 | E3,
@@ -2874,8 +2892,13 @@ export const catchReason: {
     self: Effect.Effect<A, E, R>,
     errorTag: K,
     reasonTag: RK,
-    f: (reason: ExtractReason<ExtractTag<E, K>, RK>) => Effect.Effect<A2, E2, R2>,
-    orElse?: ((reasons: ExcludeReason<ExtractTag<E, K>, RK>) => Effect.Effect<A3, E3, R3>) | undefined
+    f: (reason: ExtractReason<ExtractTag<E, K>, RK>, error: ExtractTag<E, K>) => Effect.Effect<A2, E2, R2>,
+    orElse?:
+      | ((
+        reasons: ExcludeReason<ExtractTag<E, K>, RK>,
+        error: OmitReason<ExtractTag<E, K>, RK>
+      ) => Effect.Effect<A3, E3, R3>)
+      | undefined
   ): Effect.Effect<
     A | A2 | Exclude<A3, unassigned>,
     (A3 extends unassigned ? E : ExcludeTag<E, K>) | E2 | E3,
@@ -2886,8 +2909,8 @@ export const catchReason: {
       ((e: any) => isTagged(e, errorTag) && hasProperty(e, "reason")) as any,
       (e: any): Effect.Effect<A2 | A3, E | E2 | E3, R2 | R3> => {
         const reason = e.reason as any
-        if (isTagged(reason, reasonTag)) return f(reason as any)
-        return orElse ? internalCall(() => orElse(reason)) : fail(e)
+        if (isTagged(reason, reasonTag)) return f(reason as any, e)
+        return orElse ? internalCall(() => orElse(reason, e)) : fail(e)
       }
     ) as any
 )
@@ -2899,7 +2922,8 @@ export const catchReasons: {
     E,
     Cases extends {
       [RK in ReasonTags<ExtractTag<NoInfer<E>, K>>]+?: (
-        reason: ExtractReason<ExtractTag<NoInfer<E>, K>, RK>
+        reason: ExtractReason<ExtractTag<NoInfer<E>, K>, RK>,
+        error: NarrowReason<ExtractTag<NoInfer<E>, K>, RK>
       ) => Effect.Effect<any, any, any>
     },
     A2 = unassigned,
@@ -2910,7 +2934,8 @@ export const catchReasons: {
     cases: Cases,
     orElse?:
       | ((
-        reason: ExcludeReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>
+        reason: ExcludeReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>,
+        error: OmitReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>
       ) => Effect.Effect<A2, E2, R2>)
       | undefined
   ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<
@@ -2937,7 +2962,8 @@ export const catchReasons: {
     K extends Tags<E>,
     Cases extends {
       [RK in ReasonTags<ExtractTag<E, K>>]+?: (
-        reason: ExtractReason<ExtractTag<E, K>, RK>
+        reason: ExtractReason<ExtractTag<E, K>, RK>,
+        error: NarrowReason<ExtractTag<E, K>, RK>
       ) => Effect.Effect<any, any, any>
     },
     A2 = unassigned,
@@ -2949,7 +2975,8 @@ export const catchReasons: {
     cases: Cases,
     orElse?:
       | ((
-        reason: ExcludeReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>
+        reason: ExcludeReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>,
+        error: OmitReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>
       ) => Effect.Effect<A2, E2, R2>)
       | undefined
   ): Effect.Effect<
@@ -2982,9 +3009,9 @@ export const catchReasons: {
       const reason = e.reason
       keys ??= Object.keys(cases)
       if (keys.includes(reason._tag)) {
-        return internalCall(() => (cases as any)[reason._tag](reason))
+        return internalCall(() => (cases as any)[reason._tag](reason, e))
       }
-      return orElse ? internalCall(() => orElse(reason)) : fail(e)
+      return orElse ? internalCall(() => orElse(reason, e)) : fail(e)
     }
   )
 })

package/src/unstable/ai/LanguageModel.ts

@@ -527,13 +527,16 @@ export type ExtractError<Options> = Options extends {
  * @category utility types
  */
 export type ExtractServices<Options> = Options extends {
-  readonly toolkit: Toolkit.WithHandler<infer _Tools>
-}
+  readonly disableToolCallResolution: true
+} ? never
+  : Options extends {
+    readonly toolkit: Toolkit.WithHandler<infer _Tools>
+  }
   // Required for tool call execution
-  ?
-    | Tool.ResultEncodingServices<_Tools[keyof _Tools]>
-    // Required for decoding large language model responses
-    | Tool.ResultDecodingServices<_Tools[keyof _Tools]>
+    ?
+      | Tool.ResultEncodingServices<_Tools[keyof _Tools]>
+      // Required for decoding large language model responses
+      | Tool.ResultDecodingServices<_Tools[keyof _Tools]>
   : Options extends {
     readonly toolkit: Effect.Yieldable<
       Toolkit.Toolkit<infer _Tools>,

package/src/unstable/cli/Command.ts

@@ -6,10 +6,12 @@ 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 * as Layer from "../../Layer.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 * as ServiceMap from "../../ServiceMap.ts"
 import * as Terminal from "../../Terminal.ts"
@@ -20,7 +22,7 @@ import * as CliOutput from "./CliOutput.ts"
 import * as GlobalFlag from "./GlobalFlag.ts"
 import { checkForDuplicateFlags, makeCommand, toImpl, TypeId } from "./internal/command.ts"
 import { parseConfig } from "./internal/config.ts"
-import { getHelpForCommandPath } from "./internal/help.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 Param from "./Param.ts"
@@ -586,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,
@@ -659,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                                                                */
   /* ========================================================================== */
@@ -691,11 +693,12 @@ 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
@@ -940,6 +943,7 @@ export const withSubcommands: {
     shortDescription: impl.shortDescription,
     alias: impl.alias,
     annotations: impl.annotations,
+    globalFlags: impl.globalFlags,
     examples: impl.examples,
     service: impl.service,
     subcommands: normalized.groups,
@@ -948,7 +952,50 @@ export const withSubcommands: {
   })
 })
 
+/**
+ * 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 ExtractGlobalFlagContext<T extends ReadonlyArray<GlobalFlag.GlobalFlag<any>>> = T[number] extends
+  GlobalFlag.Setting<infer Id, any> ? GlobalFlag.Setting.Identifier<Id> : never
 type ExtractSubcommand<T> = T extends Command<any, any, any, any> ? T
   : T extends Command.SubcommandGroup<infer Commands> ? Commands[number]
   : never
@@ -1532,6 +1579,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>,
@@ -1539,7 +1625,7 @@ const showHelp = <Name extends string, Input, E, R>(
 ): Effect.Effect<void, never, Environment> =>
   Effect.gen(function*() {
     const formatter = yield* CliOutput.Formatter
-    const helpDoc = yield* getHelpForCommandPath(command, commandPath, GlobalFlag.Registry)
+    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))
@@ -1696,15 +1782,11 @@ export const runWith = <const Name extends string, Input, E, R>(
     function*(args: ReadonlyArray<string>) {
       const { tokens, trailingOperands } = Lexer.lex(args)
 
-      // 1. Read registry and resolve each reference to its current value
-      const refs = yield* GlobalFlag.Registry
-      const flags: Array<GlobalFlag.GlobalFlag<any>> = []
-      for (const ref of refs) {
-        flags.push(yield* ref)
-      }
+      // 1. Collect known global flags from the command tree
+      const allFlags = getGlobalFlagsForCommandTree(command, GlobalFlag.BuiltIns)
 
       // 2. Extract global flag tokens
-      const allFlagParams = flags.flatMap((f) => Param.extractSingleParams(f.flag))
+      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: [] }
@@ -1713,9 +1795,17 @@ export const runWith = <const Name extends string, Input, E, R>(
       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)
 
-      // 4. Process action flags — first present action wins, then exit
-      for (const flag of flags) {
+      // 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])
+      }
+
+      // 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) => {
@@ -1728,7 +1818,7 @@ export const runWith = <const Name extends string, Input, E, R>(
         return
       }
 
-      // 5. Handle parsing errors
+      // 6. Handle parsing errors
       if (parsedArgs.errors && parsedArgs.errors.length > 0) {
         return yield* showHelp(command, commandPath, parsedArgs.errors)
       }
@@ -1737,17 +1827,25 @@ export const runWith = <const Name extends string, Input, E, R>(
         return yield* showHelp(command, commandPath, [parseResult.failure])
       }
 
-      // 6. Compose setting flag layers
-      let contextLayer: Layer.Layer<never> = Layer.empty
-      for (const flag of flags) {
+      // 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)
-        contextLayer = Layer.merge(contextLayer, flag.layer(value))
+        program = Effect.provideService(program, flag, value)
       }
 
-      // 7. Run command handler with composed context
-      const program = commandImpl.handle(parseResult.success, [command.name])
-      yield* Effect.provide(program, contextLayer)
+      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)
+      })
+
+      // 9. Run command handler with composed context
+      yield* Effect.provideServices(program, services)
     },
     Effect.catchIf(
       ((error: any) =>