effect 4.0.0-beta.70 → 4.0.0-beta.72

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
  */
@@ -1221,7 +1226,7 @@ export const withSharedFlags: {
 )
 
 /**
- * Declares global flags for a command scope.
+ * Adds global flags to a command scope.
  *
  * **Details**
  *
@@ -1232,7 +1237,7 @@ export const withSharedFlags: {
  */
 export const withGlobalFlags: {
   /**
-   * Declares global flags for a command scope.
+   * Adds global flags to a command scope.
    *
    * **Details**
    *
@@ -1245,7 +1250,7 @@ export const withGlobalFlags: {
     self: Command<Name, Input, ContextInput, E, R>
   ) => Command<Name, Input, ContextInput, E, Exclude<R, ExtractGlobalFlagContext<GlobalFlags>>>
   /**
-   * Declares global flags for a command scope.
+   * Adds global flags to a command scope.
    *
    * **Details**
    *
@@ -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.
  *
@@ -1136,7 +1148,7 @@ export const mapTryCatch: {
 ) => Param.mapTryCatch(self, f, onError))
 
 /**
- * Requires a flag to be specified at least a minimum number of times.
+ * Ensures a flag is specified at least a minimum number of times.
  *
  * **Example** (Requiring repeated values)
  *
@@ -1158,7 +1170,7 @@ export const mapTryCatch: {
  */
 export const atLeast: {
   /**
-   * Requires a flag to be specified at least a minimum number of times.
+   * Ensures a flag is specified at least a minimum number of times.
    *
    * **Example** (Requiring repeated values)
    *
@@ -1180,7 +1192,7 @@ export const atLeast: {
    */
   <A>(min: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
   /**
-   * Requires a flag to be specified at least a minimum number of times.
+   * Ensures a flag is specified at least a minimum number of times.
    *
    * **Example** (Requiring repeated values)
    *
@@ -1204,7 +1216,7 @@ export const atLeast: {
 } = dual(2, <A>(self: Flag<A>, min: number) => Param.atLeast(self, min))
 
 /**
- * Limits a flag to be specified at most a maximum number of times.
+ * Ensures a flag is specified at most a maximum number of times.
  *
  * **Example** (Limiting repeated values)
  *
@@ -1226,7 +1238,7 @@ export const atLeast: {
  */
 export const atMost: {
   /**
-   * Limits a flag to be specified at most a maximum number of times.
+   * Ensures a flag is specified at most a maximum number of times.
    *
    * **Example** (Limiting repeated values)
    *
@@ -1248,7 +1260,7 @@ export const atMost: {
    */
   <A>(max: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
   /**
-   * Limits a flag to be specified at most a maximum number of times.
+   * Ensures a flag is specified at most a maximum number of times.
    *
    * **Example** (Limiting repeated values)
    *
@@ -1272,7 +1284,7 @@ export const atMost: {
 } = dual(2, <A>(self: Flag<A>, max: number) => Param.atMost(self, max))
 
 /**
- * Constrains a flag to be specified between a minimum and maximum number of times.
+ * Ensures a flag is specified between a minimum and maximum number of times.
  *
  * **Example** (Bounding repeated values)
  *
@@ -1294,7 +1306,7 @@ export const atMost: {
  */
 export const between: {
   /**
-   * Constrains a flag to be specified between a minimum and maximum number of times.
+   * Ensures a flag is specified between a minimum and maximum number of times.
    *
    * **Example** (Bounding repeated values)
    *
@@ -1316,7 +1328,7 @@ export const between: {
    */
   <A>(min: number, max: number): (self: Flag<A>) => Flag<ReadonlyArray<A>>
   /**
-   * Constrains a flag to be specified between a minimum and maximum number of times.
+   * Ensures a flag is specified between a minimum and maximum number of times.
    *
    * **Example** (Bounding repeated values)
    *

package/src/unstable/cli/GlobalFlag.ts

@@ -156,8 +156,11 @@ let settingIdCounter = 0
 /* ========================================================================== */
 
 /**
- * The `--help` / `-h` global flag.
- * Shows help documentation for the command.
+ * Defines 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
@@ -176,8 +179,11 @@ export const Help: Action<boolean> = action({
 })
 
 /**
- * The `--version` global flag.
- * Shows version information for the command.
+ * Defines the global action flag for showing command version information.
+ *
+ * **When to use**
+ *
+ * Use to add a built-in `--version` flag to a command runner.
  *
  * @category references
  * @since 4.0.0
@@ -194,8 +200,13 @@ export const Version: Action<boolean> = action({
 })
 
 /**
- * The `--completions` global flag.
- * Prints shell completion script for the given shell.
+ * Defines 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
@@ -218,8 +229,12 @@ export const Completions: Action<Option.Option<"bash" | "zsh" | "fish">> = actio
 })
 
 /**
- * The `--log-level` global flag.
- * Sets the minimum log level for the command.
+ * Defines the global setting flag for command log level.
+ *
+ * **When to use**
+ *
+ * Use to add a built-in `--log-level` option that configures the minimum log
+ * level for the command.
  *
  * @category references
  * @since 4.0.0
@@ -251,6 +266,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
  */