effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/unstable/cli/Command.ts

@@ -453,6 +453,11 @@ export interface ParsedTokens {
 /**
  * Returns `true` if the provided value is a `Command`.
  *
+ * **Gotchas**
+ *
+ * This checks for the `Command` type-id property; it does not validate the full
+ * command shape.
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -1479,7 +1484,7 @@ export const withAlias: {
  *
  * **When to use**
  *
- * Use this for experimental or internal subcommands that should be accepted but
+ * Use when you use this for experimental or internal subcommands that should be accepted but
  * not advertised on the public CLI surface.
  *
  * **Example** (Hiding a subcommand)
@@ -1509,6 +1514,22 @@ export const withHidden = <const Name extends string, Input, E, R, ContextInput>
 /**
  * Adds a custom annotation to a command.
  *
+ * **When to use**
+ *
+ * Use to attach one command-scoped metadata value under a `Context.Key`,
+ * especially for consumers such as custom help formatters.
+ *
+ * **Details**
+ *
+ * Annotations are stored on the command's annotation context and flow into
+ * generated help document annotations.
+ *
+ * **Gotchas**
+ *
+ * Adding the same `Context.Key` again replaces the earlier value.
+ *
+ * @see {@link annotateMerge} for merging an existing annotation context
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -1516,6 +1537,22 @@ export const annotate: {
   /**
    * Adds a custom annotation to a command.
    *
+   * **When to use**
+   *
+   * Use to attach one command-scoped metadata value under a `Context.Key`,
+   * especially for consumers such as custom help formatters.
+   *
+   * **Details**
+   *
+   * Annotations are stored on the command's annotation context and flow into
+   * generated help document annotations.
+   *
+   * **Gotchas**
+   *
+   * Adding the same `Context.Key` again replaces the earlier value.
+   *
+   * @see {@link annotateMerge} for merging an existing annotation context
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -1525,6 +1562,22 @@ export const annotate: {
   /**
    * Adds a custom annotation to a command.
    *
+   * **When to use**
+   *
+   * Use to attach one command-scoped metadata value under a `Context.Key`,
+   * especially for consumers such as custom help formatters.
+   *
+   * **Details**
+   *
+   * Annotations are stored on the command's annotation context and flow into
+   * generated help document annotations.
+   *
+   * **Gotchas**
+   *
+   * Adding the same `Context.Key` again replaces the earlier value.
+   *
+   * @see {@link annotateMerge} for merging an existing annotation context
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -1545,6 +1598,22 @@ export const annotate: {
 /**
  * Merges a Context of annotations into a command.
  *
+ * **When to use**
+ *
+ * Use when attaching an already-built `Context.Context` of command annotations.
+ *
+ * **Details**
+ *
+ * Merged annotations are stored on the command and exposed through generated
+ * help document annotations.
+ *
+ * **Gotchas**
+ *
+ * If both contexts contain the same `Context.Key`, the incoming annotations
+ * context wins.
+ *
+ * @see {@link annotate} for adding a single annotation without constructing a `Context`
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -1552,6 +1621,22 @@ export const annotateMerge: {
   /**
    * Merges a Context of annotations into a command.
    *
+   * **When to use**
+   *
+   * Use when attaching an already-built `Context.Context` of command annotations.
+   *
+   * **Details**
+   *
+   * Merged annotations are stored on the command and exposed through generated
+   * help document annotations.
+   *
+   * **Gotchas**
+   *
+   * If both contexts contain the same `Context.Key`, the incoming annotations
+   * context wins.
+   *
+   * @see {@link annotate} for adding a single annotation without constructing a `Context`
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -1561,6 +1646,22 @@ export const annotateMerge: {
   /**
    * Merges a Context of annotations into a command.
    *
+   * **When to use**
+   *
+   * Use when attaching an already-built `Context.Context` of command annotations.
+   *
+   * **Details**
+   *
+   * Merged annotations are stored on the command and exposed through generated
+   * help document annotations.
+   *
+   * **Gotchas**
+   *
+   * If both contexts contain the same `Context.Key`, the incoming annotations
+   * context wins.
+   *
+   * @see {@link annotate} for adding a single annotation without constructing a `Context`
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -1857,6 +1958,15 @@ export const provideSync: {
  * Provides the handler of a command with the service produced by an effect
  * that optionally depends on the command-line input to be created.
  *
+ * **When to use**
+ *
+ * Use to acquire a service effectfully for each command run, optionally using
+ * parsed command input.
+ *
+ * @see {@link provideSync} for synchronous service acquisition
+ * @see {@link provide} for providing an already-available service
+ * @see {@link provideEffectDiscard} for running an effect before the handler without providing a service
+ *
  * @category providing services
  * @since 4.0.0
  */
@@ -1865,6 +1975,15 @@ export const provideEffect: {
    * Provides the handler of a command with the service produced by an effect
    * that optionally depends on the command-line input to be created.
    *
+   * **When to use**
+   *
+   * Use to acquire a service effectfully for each command run, optionally using
+   * parsed command input.
+   *
+   * @see {@link provideSync} for synchronous service acquisition
+   * @see {@link provide} for providing an already-available service
+   * @see {@link provideEffectDiscard} for running an effect before the handler without providing a service
+   *
    * @category providing services
    * @since 4.0.0
    */
@@ -1878,6 +1997,15 @@ export const provideEffect: {
    * Provides the handler of a command with the service produced by an effect
    * that optionally depends on the command-line input to be created.
    *
+   * **When to use**
+   *
+   * Use to acquire a service effectfully for each command run, optionally using
+   * parsed command input.
+   *
+   * @see {@link provideSync} for synchronous service acquisition
+   * @see {@link provide} for providing an already-available service
+   * @see {@link provideEffectDiscard} for running an effect before the handler without providing a service
+   *
    * @category providing services
    * @since 4.0.0
    */
@@ -1995,7 +2123,7 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
  *
  * **When to use**
  *
- * Use `run` at an application entry point when arguments should come from
+ * 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.
  *
@@ -2027,7 +2155,7 @@ export const run: {
    *
    * **When to use**
    *
-   * Use `run` at an application entry point when arguments should come from
+   * 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.
    *
@@ -2065,7 +2193,7 @@ export const run: {
    *
    * **When to use**
    *
-   * Use `run` at an application entry point when arguments should come from
+   * 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.
    *
@@ -2115,7 +2243,7 @@ export const run: {
  *
  * **When to use**
  *
- * Use this function for testing CLI applications or when you want to
+ * Use when you use this function for testing CLI applications or when you want to
  * programmatically execute commands with specific arguments.
  *
  * **Example** (Running commands with explicit arguments)

package/src/unstable/cli/Completions.ts

@@ -1,5 +1,32 @@
 /**
- * Shell completion descriptors and script generation for the unstable CLI API.
+ * The `Completions` module turns a plain description of an Effect CLI command
+ * tree into shell completion scripts for Bash, Zsh, and Fish. It is the
+ * low-level script generation surface used by the unstable CLI package and by
+ * the built-in completions global flag.
+ *
+ * **Mental model**
+ *
+ * - {@link CommandDescriptor} is a shell-agnostic tree of commands,
+ *   subcommands, flags, and positional arguments.
+ * - {@link FlagDescriptor} and {@link ArgumentDescriptor} carry just enough
+ *   metadata for shells to complete names, choices, paths, and value-shaped
+ *   arguments.
+ * - {@link generate} selects the shell-specific generator and returns a static
+ *   script string for one executable name.
+ *
+ * **Common tasks**
+ *
+ * - Generate an installable completion script with {@link generate}.
+ * - Preserve help text in completions by filling descriptor descriptions.
+ * - Use `Choice` descriptors for finite values and `Path` descriptors when the
+ *   shell should complete files or directories.
+ *
+ * **Gotchas**
+ *
+ * - This module does not inspect a `Command` directly; it consumes an already
+ *   built {@link CommandDescriptor}.
+ * - Generated scripts are returned as strings. Printing, installing, or caching
+ *   those scripts is handled by the caller.
  *
  * @since 4.0.0
  */
@@ -88,6 +115,19 @@ export type ArgumentType =
 /**
  * Generates a shell completion script for a command descriptor.
  *
+ * **When to use**
+ *
+ * Use to produce an installable completion script when you already have a
+ * `CommandDescriptor`.
+ *
+ * **Details**
+ *
+ * Dispatches by `shell` to Bash, Zsh, or Fish generation and returns a static
+ * script string for `executableName`.
+ *
+ * @see {@link Shell} for supported shell names
+ * @see {@link CommandDescriptor} for the command shape used by completion generation
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cli/Flag.ts

@@ -161,7 +161,19 @@ export const choiceWithValue = <const Choice extends ReadonlyArray<readonly [str
 ): Flag<Choice[number][1]> => Param.choiceWithValue(Param.flagKind, name, choices)
 
 /**
- * Simpler variant of `choiceWithValue` which maps each string to itself.
+ * Creates a flag that accepts one of the provided string choices and returns
+ * the selected string.
+ *
+ * **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.
+ *
+ * **Gotchas**
+ *
+ * An empty choices array compiles, but no input value can parse successfully.
+ *
+ * @see {@link choiceWithValue} for mapping accepted strings to different typed values
  *
  * @category constructors
  * @since 4.0.0
@@ -362,7 +374,7 @@ export const fileSchema = <A>(
  *
  * **When to use**
  *
- * Use this for options that accept configuration values.
+ * Use when you use this for options that accept configuration values.
  *
  * **Details**
  *
@@ -662,7 +674,7 @@ export const withMetavar: {
  *
  * **When to use**
  *
- * Use this for experimental or internal flags that should be accepted but not
+ * 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.
  *

package/src/unstable/cli/GlobalFlag.ts

@@ -156,8 +156,11 @@ let settingIdCounter = 0
 /* ========================================================================== */
 
 /**
- * The `--help` / `-h` global flag.
- * Shows help documentation for the command.
+ * The `--help` / `-h` global flag, which shows help documentation for the
+ * active command path.
+ *
+ * @see {@link BuiltIns} for the default list containing this flag
+ * @see {@link action} for defining custom action global flags
  *
  * @category references
  * @since 4.0.0
@@ -194,8 +197,13 @@ export const Version: Action<boolean> = action({
 })
 
 /**
- * The `--completions` global flag.
- * Prints shell completion script for the given shell.
+ * The `--completions` global flag, which prints a shell completion script for
+ * the given shell.
+ *
+ * **Details**
+ *
+ * Accepted values are `bash`, `zsh`, `fish`, and `sh`; `sh` is normalized to
+ * `bash`.
  *
  * @category references
  * @since 4.0.0
@@ -251,6 +259,22 @@ export const LogLevel: Setting<"log-level", Option.Option<LogLevelType>> = setti
 /**
  * Built-in global flags in default precedence order.
  *
+ * **Details**
+ *
+ * The built-ins are `Help`, `Version`, `Completions`, and `LogLevel`.
+ * `Command.runWith` prepends these built-ins when collecting and parsing global
+ * flags.
+ *
+ * **Gotchas**
+ *
+ * Action flags are processed in active flag order and the first present action
+ * exits, so this array controls built-in action precedence.
+ *
+ * @see {@link Help} for the help action flag
+ * @see {@link Version} for the version action flag
+ * @see {@link Completions} for the shell-completions action flag
+ * @see {@link LogLevel} for the built-in log-level setting flag
+ *
  * @category references
  * @since 4.0.0
  */

package/src/unstable/cli/Param.ts

@@ -85,6 +85,14 @@ export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal
 /**
  * Kind discriminator for positional argument parameters.
  *
+ * **When to use**
+ *
+ * Use to build low-level `Param` constructors or type positions for positional
+ * argument parameters.
+ *
+ * @see {@link flagKind} for the named flag parameter discriminator
+ * @see {@link ParamKind} for the full parameter kind union
+ *
  * @category constants
  * @since 4.0.0
  */
@@ -93,6 +101,13 @@ export const argumentKind: "argument" = "argument" as const
 /**
  * Kind discriminator for flag parameters.
  *
+ * **When to use**
+ *
+ * Use to build low-level `Param` constructors or type positions for named flag
+ * parameters.
+ *
+ * @see {@link argumentKind} for the positional argument parameter discriminator
+ *
  * @category constants
  * @since 4.0.0
  */
@@ -875,7 +890,7 @@ export const fileSchema = <Kind extends ParamKind, A>(
  *
  * **When to use**
  *
- * Use it for options that accept configuration values.
+ * Use when you use it for options that accept configuration values.
  *
  * **Details**
  *
@@ -920,7 +935,7 @@ export const keyValuePair = <Kind extends ParamKind>(
  *
  * **When to use**
  *
- * This is useful for creating placeholder parameters or for combinators.
+ * Use when this is useful for creating placeholder parameters or for combinators.
  *
  * **Example** (Creating sentinel parameters)
  *
@@ -955,7 +970,7 @@ const FLAG_DASH_REGEXP = /^-+/
  *
  * **When to use**
  *
- * Aliases allow params to be specified with alternative names,
+ * Use when aliases allow params to be specified with alternative names,
  * typically single-character shortcuts like "-f" for "--force".
  *
  * **Details**
@@ -991,7 +1006,7 @@ export const withAlias: {
    *
    * **When to use**
    *
-   * Aliases allow params to be specified with alternative names,
+   * Use when aliases allow params to be specified with alternative names,
    * typically single-character shortcuts like "-f" for "--force".
    *
    * **Details**
@@ -1027,7 +1042,7 @@ export const withAlias: {
    *
    * **When to use**
    *
-   * Aliases allow params to be specified with alternative names,
+   * Use when aliases allow params to be specified with alternative names,
    * typically single-character shortcuts like "-f" for "--force".
    *
    * **Details**
@@ -1155,7 +1170,7 @@ export const withDescription: {
  *
  * **When to use**
  *
- * Useful for experimental, internal, or deprecated flags that should be
+ * Use when experimental, internal, or deprecated flags that should be
  * accepted but not advertised.
  *
  * **Example** (Hiding a flag from help)
@@ -1649,6 +1664,24 @@ export const withDefault: {
 /**
  * Adds a fallback config that is loaded when a required parameter is missing.
  *
+ * **When to use**
+ *
+ * Use when config should provide a fallback source for required flags or
+ * arguments that are absent from CLI input.
+ *
+ * **Details**
+ *
+ * Provided CLI values win. Config is loaded only after a missing option or
+ * missing argument error.
+ *
+ * **Gotchas**
+ *
+ * Missing config preserves the original missing-parameter error. Config parse
+ * failure becomes `CliError.InvalidValue`.
+ *
+ * @see {@link withDefault} for a pure default value
+ * @see {@link withFallbackPrompt} for prompting interactively when input is missing
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -1656,6 +1689,24 @@ export const withFallbackConfig: {
   /**
    * Adds a fallback config that is loaded when a required parameter is missing.
    *
+   * **When to use**
+   *
+   * Use when config should provide a fallback source for required flags or
+   * arguments that are absent from CLI input.
+   *
+   * **Details**
+   *
+   * Provided CLI values win. Config is loaded only after a missing option or
+   * missing argument error.
+   *
+   * **Gotchas**
+   *
+   * Missing config preserves the original missing-parameter error. Config parse
+   * failure becomes `CliError.InvalidValue`.
+   *
+   * @see {@link withDefault} for a pure default value
+   * @see {@link withFallbackPrompt} for prompting interactively when input is missing
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -1663,6 +1714,24 @@ export const withFallbackConfig: {
   /**
    * Adds a fallback config that is loaded when a required parameter is missing.
    *
+   * **When to use**
+   *
+   * Use when config should provide a fallback source for required flags or
+   * arguments that are absent from CLI input.
+   *
+   * **Details**
+   *
+   * Provided CLI values win. Config is loaded only after a missing option or
+   * missing argument error.
+   *
+   * **Gotchas**
+   *
+   * Missing config preserves the original missing-parameter error. Config parse
+   * failure becomes `CliError.InvalidValue`.
+   *
+   * @see {@link withDefault} for a pure default value
+   * @see {@link withFallbackPrompt} for prompting interactively when input is missing
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -1701,6 +1770,25 @@ export const withFallbackConfig: {
 /**
  * Adds a fallback prompt that is shown when a required parameter is missing.
  *
+ * **When to use**
+ *
+ * Use when a CLI should ask interactively for a missing required flag or
+ * argument.
+ *
+ * **Details**
+ *
+ * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
+ * Effectful prompt creation is lazy and runs only when the fallback is needed.
+ *
+ * **Gotchas**
+ *
+ * This only handles missing options and missing arguments. Invalid values do not
+ * prompt, and prompt cancellation re-fails with the original missing error.
+ *
+ * @see {@link FallbackPrompt} for accepted fallback prompt forms
+ * @see {@link withFallbackConfig} for loading a fallback from config
+ * @see {@link withDefault} for a pure default value
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -1708,6 +1796,25 @@ export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required parameter is missing.
    *
+   * **When to use**
+   *
+   * Use when a CLI should ask interactively for a missing required flag or
+   * argument.
+   *
+   * **Details**
+   *
+   * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
+   * Effectful prompt creation is lazy and runs only when the fallback is needed.
+   *
+   * **Gotchas**
+   *
+   * This only handles missing options and missing arguments. Invalid values do not
+   * prompt, and prompt cancellation re-fails with the original missing error.
+   *
+   * @see {@link FallbackPrompt} for accepted fallback prompt forms
+   * @see {@link withFallbackConfig} for loading a fallback from config
+   * @see {@link withDefault} for a pure default value
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -1715,6 +1822,25 @@ export const withFallbackPrompt: {
   /**
    * Adds a fallback prompt that is shown when a required parameter is missing.
    *
+   * **When to use**
+   *
+   * Use when a CLI should ask interactively for a missing required flag or
+   * argument.
+   *
+   * **Details**
+   *
+   * `FallbackPrompt` accepts either a `Prompt` or an effect that builds one.
+   * Effectful prompt creation is lazy and runs only when the fallback is needed.
+   *
+   * **Gotchas**
+   *
+   * This only handles missing options and missing arguments. Invalid values do not
+   * prompt, and prompt cancellation re-fails with the original missing error.
+   *
+   * @see {@link FallbackPrompt} for accepted fallback prompt forms
+   * @see {@link withFallbackConfig} for loading a fallback from config
+   * @see {@link withDefault} for a pure default value
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -2124,7 +2250,7 @@ export const atLeast: {
  *
  * **When to use**
  *
- * Use this combinator for validation and transformation in a single step.
+ * Use when you use this combinator for validation and transformation in a single step.
  *
  * **Example** (Filtering and transforming values)
  *
@@ -2151,7 +2277,7 @@ export const filterMap: {
    *
    * **When to use**
    *
-   * Use this combinator for validation and transformation in a single step.
+   * Use when you use this combinator for validation and transformation in a single step.
    *
    * **Example** (Filtering and transforming values)
    *
@@ -2178,7 +2304,7 @@ export const filterMap: {
    *
    * **When to use**
    *
-   * Use this combinator for validation and transformation in a single step.
+   * Use when you use this combinator for validation and transformation in a single step.
    *
    * **Example** (Filtering and transforming values)
    *