effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/unstable/ai/Tool.ts

@@ -63,7 +63,7 @@ import type * as JsonSchema from "../../JsonSchema.ts"
 import { pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
-import * as AST from "../../SchemaAST.ts"
+import * as SchemaAST from "../../SchemaAST.ts"
 import type * as Struct from "../../Struct.ts"
 import type * as Types from "../../Types.ts"
 import type * as AiError from "./AiError.ts"
@@ -1318,8 +1318,8 @@ export const make = <
  *
  * **When to use**
  *
- * Use when this is useful for tools where the schema isn't known at compile time,
- * such as MCP tools discovered at runtime or tools from external configurations.
+ * Use when you do not know a tool schema at compile time, such as MCP tools
+ * discovered at runtime or tools from external configurations.
  *
  * **Details**
  *
@@ -1363,8 +1363,8 @@ export const dynamic: {
    *
    * **When to use**
    *
-   * Use when this is useful for tools where the schema isn't known at compile time,
-   * such as MCP tools discovered at runtime or tools from external configurations.
+   * Use when you do not know a tool schema at compile time, such as MCP tools
+   * discovered at runtime or tools from external configurations.
    *
    * **Details**
    *
@@ -1595,7 +1595,7 @@ export const providerDefined = <
  * naming conflicts (i.e. `"web_search"`) to instead use custom names (i.e.
  * `"OpenAiWebSearch"`).
  *
- * @category utils
+ * @category models
  * @since 4.0.0
  */
 export class NameMapper<Tools extends ReadonlyArray<Any>> {
@@ -1673,7 +1673,7 @@ export class NameMapper<Tools extends ReadonlyArray<Any>> {
  * console.log(description) // "This is an example tool"
  * ```
  *
- * @category utils
+ * @category getters
  * @since 4.0.0
  */
 export const getDescription = <Tool extends Any>(tool: Tool): string | undefined => {
@@ -1681,7 +1681,7 @@ export const getDescription = <Tool extends Any>(tool: Tool): string | undefined
     return tool.description
   }
   if (Schema.isSchema(tool.parametersSchema)) {
-    return AST.resolveDescription(tool.parametersSchema.ast)
+    return SchemaAST.resolveDescription(tool.parametersSchema.ast)
   }
   return undefined
 }
@@ -1724,7 +1724,7 @@ export const getDescription = <Tool extends Any>(tool: Tool): string | undefined
  * // }
  * ```
  *
- * @category utils
+ * @category getters
  * @since 4.0.0
  */
 export const getJsonSchema = <Tool extends Any>(tool: Tool, options?: {
@@ -1746,7 +1746,7 @@ export const getJsonSchema = <Tool extends Any>(tool: Tool, options?: {
  * `Schema.toJsonSchemaDocument` and any generated definitions are attached as
  * `$defs`.
  *
- * @category utils
+ * @category converting
  * @since 4.0.0
  */
 export const getJsonSchemaFromSchema = <S extends Schema.Top>(schema: S, options?: {
@@ -1942,7 +1942,7 @@ export const Strict = Context.Reference<boolean | undefined>("effect/ai/Tool/Str
  *
  * @see {@link Strict} for the annotation read by this helper
  *
- * @category utils
+ * @category getters
  * @since 4.0.0
  */
 export const getStrictMode = <T extends Any>(tool: T): boolean | undefined => Context.get(tool.annotations, Strict)
@@ -2028,7 +2028,8 @@ function filter(obj: any) {
  *
  * **When to use**
  *
- * Use when thrown parse and security failures are acceptable.
+ * Use when you need a JSON parser that throws for invalid JSON or unsafe
+ * object shapes.
  *
  * **Gotchas**
  *
@@ -2036,7 +2037,7 @@ function filter(obj: any) {
  * `__proto__` property or a dangerous `constructor.prototype` shape throw a
  * `SyntaxError`.
  *
- * @category utils
+ * @category unsafe
  * @since 4.0.0
  */
 export const unsafeSecureJsonParse = (text: string): unknown => {
@@ -2068,7 +2069,7 @@ export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never>
  *
  * **When to use**
  *
- * Use when a tool needs an explicit no-parameter `parameters` schema.
+ * Use when you need an explicit no-parameter `parameters` schema for a tool.
  *
  * **Details**
  *
@@ -2083,6 +2084,6 @@ export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never>
 export const EmptyParams: EmptyParams = Schema.Record(Schema.String, Schema.Never)
 
 /** @internal */
-export function isEmptyParamsRecord(indexSignature: AST.IndexSignature): boolean {
-  return indexSignature.parameter === AST.string && AST.isNever(indexSignature.type)
+export function isEmptyParamsRecord(indexSignature: SchemaAST.IndexSignature): boolean {
+  return indexSignature.parameter === SchemaAST.string && SchemaAST.isNever(indexSignature.type)
 }

package/src/unstable/ai/Toolkit.ts

@@ -497,8 +497,8 @@ const resolveInput = <Tools extends ReadonlyArray<Tool.Any>>(
  *
  * **When to use**
  *
- * Use as a starting point for building toolkits or as a default value. Can
- * be extended using the merge function to add tools.
+ * Use when you need an empty starting point for building toolkits or a default
+ * toolkit value that can be extended with `merge`.
  *
  * @category constructors
  * @since 4.0.0

package/src/unstable/cli/Command.ts

@@ -1484,8 +1484,8 @@ export const withAlias: {
  *
  * **When to use**
  *
- * Use when you use this for experimental or internal subcommands that should be accepted but
- * not advertised on the public CLI surface.
+ * Use when experimental or internal subcommands should be accepted but not advertised on
+ * the public CLI surface.
  *
  * **Example** (Hiding a subcommand)
  *
@@ -1600,7 +1600,8 @@ export const annotate: {
  *
  * **When to use**
  *
- * Use when attaching an already-built `Context.Context` of command annotations.
+ * Use when you need to attach an already-built `Context.Context` of command
+ * annotations.
  *
  * **Details**
  *
@@ -1623,7 +1624,8 @@ export const annotateMerge: {
    *
    * **When to use**
    *
-   * Use when attaching an already-built `Context.Context` of command annotations.
+   * Use when you need to attach an already-built `Context.Context` of command
+   * annotations.
    *
    * **Details**
    *
@@ -1648,7 +1650,8 @@ export const annotateMerge: {
    *
    * **When to use**
    *
-   * Use when attaching an already-built `Context.Context` of command annotations.
+   * Use when you need to attach an already-built `Context.Context` of command
+   * annotations.
    *
    * **Details**
    *
@@ -1916,6 +1919,11 @@ export const provide: {
  * Provides the handler of a command with the implementation of a service that
  * optionally depends on the command-line input to be constructed.
  *
+ * **When to use**
+ *
+ * Use when a command handler needs a pure service implementation, optionally
+ * derived from the parsed command input.
+ *
  * @category providing services
  * @since 4.0.0
  */
@@ -1924,6 +1932,11 @@ export const provideSync: {
    * Provides the handler of a command with the implementation of a service that
    * optionally depends on the command-line input to be constructed.
    *
+   * **When to use**
+   *
+   * Use when a command handler needs a pure service implementation, optionally
+   * derived from the parsed command input.
+   *
    * @category providing services
    * @since 4.0.0
    */
@@ -1934,6 +1947,11 @@ export const provideSync: {
    * Provides the handler of a command with the implementation of a service that
    * optionally depends on the command-line input to be constructed.
    *
+   * **When to use**
+   *
+   * Use when a command handler needs a pure service implementation, optionally
+   * derived from the parsed command input.
+   *
    * @category providing services
    * @since 4.0.0
    */
@@ -2123,9 +2141,8 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
  *
  * **When to use**
  *
- * Use when you use `run` at an application entry point when arguments should come from
- * `Stdio`; use `runWith` when you need an explicit argument array, such as in
- * tests.
+ * Use when command-line arguments should come from `Stdio` at the application
+ * entry point.
  *
  * **Example** (Running commands with standard input)
  *
@@ -2146,6 +2163,8 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
  * })
  * ```
  *
+ * @see {@link runWith} for running a command with an explicit argument array
+ *
  * @category command execution
  * @since 4.0.0
  */
@@ -2155,9 +2174,8 @@ export const run: {
    *
    * **When to use**
    *
-   * Use when you use `run` at an application entry point when arguments should come from
-   * `Stdio`; use `runWith` when you need an explicit argument array, such as in
-   * tests.
+   * Use when command-line arguments should come from `Stdio` at the application
+   * entry point.
    *
    * **Example** (Running commands with standard input)
    *
@@ -2178,6 +2196,8 @@ export const run: {
    * })
    * ```
    *
+   * @see {@link runWith} for running a command with an explicit argument array
+   *
    * @category command execution
    * @since 4.0.0
    */
@@ -2193,9 +2213,8 @@ export const run: {
    *
    * **When to use**
    *
-   * Use when you use `run` at an application entry point when arguments should come from
-   * `Stdio`; use `runWith` when you need an explicit argument array, such as in
-   * tests.
+   * Use when command-line arguments should come from `Stdio` at the application
+   * entry point.
    *
    * **Example** (Running commands with standard input)
    *
@@ -2216,6 +2235,8 @@ export const run: {
    * })
    * ```
    *
+   * @see {@link runWith} for running a command with an explicit argument array
+   *
    * @category command execution
    * @since 4.0.0
    */
@@ -2243,8 +2264,8 @@ export const run: {
  *
  * **When to use**
  *
- * Use when you use this function for testing CLI applications or when you want to
- * programmatically execute commands with specific arguments.
+ * Use when you need to test CLI applications or programmatically execute
+ * commands with specific arguments.
  *
  * **Example** (Running commands with explicit arguments)
  *
@@ -2299,7 +2320,11 @@ export const runWith = <const Name extends string, Input, E, R, ContextInput>(
       // 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, errors: globalFlagErrors } = Parser.consumeKnownFlags(tokens, globalRegistry)
+      const { flagMap, remainder, errors: globalFlagErrors } = Parser.consumeGlobalFlags(
+        tokens,
+        command,
+        globalRegistry
+      )
       const emptyArgs: Param.ParsedArgs = { flags: flagMap, arguments: [] }
 
       // 3. Parse command arguments from remaining tokens

package/src/unstable/cli/Completions.ts

@@ -117,7 +117,7 @@ export type ArgumentType =
  *
  * **When to use**
  *
- * Use to produce an installable completion script when you already have a
+ * Use when you need an installable completion script from an existing
  * `CommandDescriptor`.
  *
  * **Details**

package/src/unstable/cli/Flag.ts

@@ -166,8 +166,8 @@ export const choiceWithValue = <const Choice extends ReadonlyArray<readonly [str
  *
  * **When to use**
  *
- * Use when a named option must be restricted to a fixed set of string values
- * and no custom value mapping is needed.
+ * Use when you need to define a named CLI flag with fixed string choices and no
+ * custom value mapping.
  *
  * **Gotchas**
  *
@@ -374,7 +374,8 @@ export const fileSchema = <A>(
  *
  * **When to use**
  *
- * Use when you use this for options that accept configuration values.
+ * Use when you need a CLI flag that accepts one or more `key=value`
+ * configuration entries.
  *
  * **Details**
  *
@@ -674,9 +675,9 @@ export const withMetavar: {
  *
  * **When to use**
  *
- * Use when you use this for experimental or internal flags that should be accepted but not
- * advertised, such as `--experimental-foo`, debug toggles, or escape hatches
- * that are not yet committed to the public CLI surface.
+ * Use when experimental or internal flags should be accepted but not advertised, such as
+ * `--experimental-foo`, debug toggles, or escape hatches that are not yet committed to the
+ * public CLI surface.
  *
  * **Example** (Hiding a flag from help)
  *

package/src/unstable/cli/GlobalFlag.ts

@@ -183,13 +183,14 @@ export const Help: Action<boolean> = action({
  *
  * **When to use**
  *
- * Use to add a built-in `--version` flag to a command runner.
+ * Use to add a built-in `--version / -v` flag to a command runner.
  *
  * @category references
  * @since 4.0.0
  */
 export const Version: Action<boolean> = action({
   flag: Flag.boolean("version").pipe(
+    Flag.withAlias("v"),
     Flag.withDescription("Show version information")
   ),
   run: (_, { command, version }) =>
@@ -266,6 +267,11 @@ export const LogLevel: Setting<"log-level", Option.Option<LogLevelType>> = setti
 /**
  * Built-in global flags in default precedence order.
  *
+ * **When to use**
+ *
+ * Use when extending or inspecting the default global-flag set that
+ * `Command.runWith` prepends before user-defined global flags.
+ *
  * **Details**
  *
  * The built-ins are `Help`, `Version`, `Completions`, and `LogLevel`.

package/src/unstable/cli/Param.ts

@@ -890,7 +890,8 @@ export const fileSchema = <Kind extends ParamKind, A>(
  *
  * **When to use**
  *
- * Use when you use it for options that accept configuration values.
+ * Use when you need command-line options or arguments that collect `key=value`
+ * configuration entries.
  *
  * **Details**
  *
@@ -935,7 +936,8 @@ export const keyValuePair = <Kind extends ParamKind>(
  *
  * **When to use**
  *
- * Use when this is useful for creating placeholder parameters or for combinators.
+ * Use when you need an empty CLI parameter sentinel for optional parameter
+ * construction or internal combinators.
  *
  * **Example** (Creating sentinel parameters)
  *
@@ -970,8 +972,8 @@ const FLAG_DASH_REGEXP = /^-+/
  *
  * **When to use**
  *
- * Use when aliases allow params to be specified with alternative names,
- * typically single-character shortcuts like "-f" for "--force".
+ * Use when you need a CLI parameter to accept an alternate name, such as "-f"
+ * for "--force".
  *
  * **Details**
  *
@@ -1006,8 +1008,8 @@ export const withAlias: {
    *
    * **When to use**
    *
-   * Use when aliases allow params to be specified with alternative names,
-   * typically single-character shortcuts like "-f" for "--force".
+   * Use when you need a CLI parameter to accept an alternate name, such as "-f"
+   * for "--force".
    *
    * **Details**
    *
@@ -1042,8 +1044,8 @@ export const withAlias: {
    *
    * **When to use**
    *
-   * Use when aliases allow params to be specified with alternative names,
-   * typically single-character shortcuts like "-f" for "--force".
+   * Use when you need a CLI parameter to accept an alternate name, such as "-f"
+   * for "--force".
    *
    * **Details**
    *
@@ -1170,8 +1172,8 @@ export const withDescription: {
  *
  * **When to use**
  *
- * Use when experimental, internal, or deprecated flags that should be
- * accepted but not advertised.
+ * Use when experimental, internal, or deprecated flags should be accepted but
+ * not advertised.
  *
  * **Example** (Hiding a flag from help)
  *
@@ -1666,7 +1668,7 @@ export const withDefault: {
  *
  * **When to use**
  *
- * Use when config should provide a fallback source for required flags or
+ * Use when you need config to provide a fallback source for required flags or
  * arguments that are absent from CLI input.
  *
  * **Details**
@@ -1691,7 +1693,7 @@ export const withFallbackConfig: {
    *
    * **When to use**
    *
-   * Use when config should provide a fallback source for required flags or
+   * Use when you need config to provide a fallback source for required flags or
    * arguments that are absent from CLI input.
    *
    * **Details**
@@ -1716,7 +1718,7 @@ export const withFallbackConfig: {
    *
    * **When to use**
    *
-   * Use when config should provide a fallback source for required flags or
+   * Use when you need config to provide a fallback source for required flags or
    * arguments that are absent from CLI input.
    *
    * **Details**
@@ -1866,7 +1868,7 @@ export const withFallbackPrompt: {
 /**
  * Represent options which can be used to configure variadic parameters.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type VariadicParamOptions = {
@@ -1886,8 +1888,8 @@ export type VariadicParamOptions = {
  * **Details**
  *
  * This is the base combinator for creating parameters that accept multiple values.
- * The min and max parameters are optional - if not provided, the parameter can be
- * specified any number of times (0 to infinity).
+ * The `min` and `max` parameters are optional. When they are not provided, the
+ * parameter can be specified any number of times, from 0 to infinity.
  *
  * **Example** (Accepting multiple values)
  *
@@ -2250,7 +2252,8 @@ export const atLeast: {
  *
  * **When to use**
  *
- * Use when you use this combinator for validation and transformation in a single step.
+ * Use when you need validation and transformation in a single parameter
+ * combinator.
  *
  * **Example** (Filtering and transforming values)
  *
@@ -2277,7 +2280,8 @@ export const filterMap: {
    *
    * **When to use**
    *
-   * Use when you use this combinator for validation and transformation in a single step.
+   * Use when you need validation and transformation in a single parameter
+   * combinator.
    *
    * **Example** (Filtering and transforming values)
    *
@@ -2304,7 +2308,8 @@ export const filterMap: {
    *
    * **When to use**
    *
-   * Use when you use this combinator for validation and transformation in a single step.
+   * Use when you need validation and transformation in a single parameter
+   * combinator.
    *
    * **Example** (Filtering and transforming values)
    *

package/src/unstable/cli/Primitive.ts

@@ -561,7 +561,7 @@ export const fileText: Primitive<string> = makePrimitive(
  * Represents options which can be provided to methods that deal with parsing
  * file content.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type FileParseOptions = {
@@ -625,7 +625,7 @@ export const fileParse = (options?: FileParseOptions): Primitive<unknown> => {
  * Represents options which can be provided to methods that deal with parsing
  * file content and decoding the file content with a `Schema`.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type FileSchemaOptions = Struct.Simplify<
@@ -728,7 +728,7 @@ export const keyValuePair: Primitive<Record<string, string>> = makePrimitive(
  *
  * **When to use**
  *
- * Use when you need flags that don't accept values.
+ * Use when you need a CLI primitive for flags that do not accept values.
  *
  * **Example** (Rejecting option values)
  *
@@ -754,7 +754,8 @@ export const none: Primitive<never> = makePrimitive("None", () => Effect.fail("T
  *
  * **When to use**
  *
- * Use when you need generating help documentation.
+ * Use when you need the display type name for a `Primitive`, such as when
+ * generating CLI help documentation.
  *
  * **Example** (Getting primitive type names)
  *
@@ -774,7 +775,7 @@ export const none: Primitive<never> = makePrimitive("None", () => Effect.fail("T
  * console.log(Primitive.getTypeName(logLevelChoice)) // "choice"
  * ```
  *
- * @category utils
+ * @category getters
  * @since 4.0.0
  */
 export const getTypeName = <A>(primitive: Primitive<A>): string => {

package/src/unstable/cli/Prompt.ts

@@ -149,7 +149,7 @@ export interface Handlers<State, Output> {
  * Options for a confirmation prompt that asks the user to choose a boolean
  * yes/no value.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface ConfirmOptions {
@@ -195,7 +195,7 @@ export interface ConfirmOptions {
  * Options for a date prompt, including the displayed message, initial value,
  * format mask, validation, and locale labels.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface DateOptions {
@@ -270,7 +270,7 @@ export interface DateOptions {
  * Options for an integer prompt, including bounds, keyboard step sizes, and
  * additional validation.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface IntegerOptions {
@@ -315,7 +315,7 @@ export interface IntegerOptions {
  * In addition to the numeric bounds and step settings from `IntegerOptions`,
  * the prompt can be configured with a display precision.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface FloatOptions extends IntegerOptions {
@@ -329,7 +329,7 @@ export interface FloatOptions extends IntegerOptions {
  * Options for a text prompt that returns a list of strings by splitting the
  * input on a delimiter.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface ListOptions extends TextOptions {
@@ -347,7 +347,7 @@ export interface ListOptions extends TextOptions {
  * They control which path type can be selected, the starting directory, paging,
  * and filtering of displayed entries.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface FileOptions {
@@ -383,7 +383,7 @@ export interface FileOptions {
  * Options for a prompt that asks the user to select one value from a list of
  * choices.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface SelectOptions<A> {
@@ -405,7 +405,7 @@ export interface SelectOptions<A> {
  * Options for an autocomplete prompt that lets the user filter selectable
  * choices by typing.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface AutoCompleteOptions<A> extends SelectOptions<A> {
@@ -427,7 +427,7 @@ export interface AutoCompleteOptions<A> extends SelectOptions<A> {
  * Options for a multi-select prompt, including bulk-selection labels and
  * minimum or maximum selection counts.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface MultiSelectOptions {
@@ -488,7 +488,7 @@ export interface SelectChoice<A> {
  * Options for text-entry prompts, including the displayed message, default
  * text, and effectful validation before submission.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface TextOptions {
@@ -511,7 +511,7 @@ export interface TextOptions {
  * Options for a toggle prompt that lets the user switch between active and
  * inactive boolean states.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface ToggleOptions {