effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/unstable/cli/Param.ts

@@ -50,6 +50,8 @@ const TypeId = "~effect/cli/Param"
 /**
  * Polymorphic CLI parameter shared by `Argument` and `Flag`.
  *
+ * **Details**
+ *
  * A parameter knows whether it consumes positional arguments or flags and
  * parses a `ParsedArgs` value into its typed result.
  *
@@ -124,6 +126,8 @@ export type AnyFlag = Param<typeof flagKind, unknown>
  * Function type used by parameters to parse currently available flags and
  * positional arguments.
  *
+ * **Details**
+ *
  * It returns the remaining positional arguments together with the parsed value,
  * or fails with a `CliError` while requiring the CLI parsing environment.
  *
@@ -191,6 +195,8 @@ export type FallbackPrompt<A> =
 /**
  * Leaf parameter that reads one named argument or flag with a primitive parser.
  *
+ * **Details**
+ *
  * Single parameters carry the user-facing name, aliases, description, primitive
  * type, and optional metavar/type name used in help output.
  *
@@ -334,6 +340,8 @@ export const isFlagParam = <A>(
  * Constructs a leaf `Single` parameter from its kind, name, primitive parser,
  * and optional help metadata.
  *
+ * **Details**
+ *
  * The returned parser reads either one positional argument or the named flag,
  * depending on `kind`.
  *
@@ -641,6 +649,8 @@ export const path = <Kind extends ParamKind>(
 /**
  * Creates a directory path parameter.
  *
+ * **Details**
+ *
  * This is a convenience function that creates a path parameter with the
  * `pathType` set to `"directory"` and a default type name of `"directory"`.
  *
@@ -679,6 +689,8 @@ export const directory = <Kind extends ParamKind>(
 /**
  * Creates a file path parameter.
  *
+ * **Details**
+ *
  * This is a convenience function that creates a path parameter with a
  * `pathType` set to `"file"` and a default type name of `"file"`.
  *
@@ -779,6 +791,8 @@ export const fileText = <Kind extends ParamKind>(kind: Kind, name: string): Para
 /**
  * Creates a param that reads and parses the content of the specified file.
  *
+ * **Details**
+ *
  * The parser that is utilized will depend on the specified `format`, or the
  * extension of the file passed on the command-line if no `format` is specified.
  *
@@ -858,10 +872,15 @@ export const fileSchema = <Kind extends ParamKind, A>(
 
 /**
  * Creates a param that parses key=value pairs.
- * Useful for options that accept configuration values.
  *
- * Note: Requires at least one key=value pair. The parsed pairs are merged
- * into a single record object.
+ * **When to use**
+ *
+ * Use it for options that accept configuration values.
+ *
+ * **Details**
+ *
+ * Requires at least one key=value pair. The parsed pairs are merged into a
+ * single record object.
  *
  * **Example** (Parsing key-value pairs)
  *
@@ -899,6 +918,8 @@ export const keyValuePair = <Kind extends ParamKind>(
 /**
  * Creates an empty sentinel parameter that always fails to parse.
  *
+ * **When to use**
+ *
  * This is useful for creating placeholder parameters or for combinators.
  *
  * **Example** (Creating sentinel parameters)
@@ -932,9 +953,13 @@ const FLAG_DASH_REGEXP = /^-+/
 /**
  * Adds an alias to an option.
  *
+ * **When to use**
+ *
  * Aliases allow params to be specified with alternative names,
  * typically single-character shortcuts like "-f" for "--force".
  *
+ * **Details**
+ *
  * This works on any param structure by recursively finding the underlying
  * `Single` node and applying the alias there.
  *
@@ -964,9 +989,13 @@ export const withAlias: {
   /**
    * Adds an alias to an option.
    *
+   * **When to use**
+   *
    * Aliases allow params to be specified with alternative names,
    * typically single-character shortcuts like "-f" for "--force".
    *
+   * **Details**
+   *
    * This works on any param structure by recursively finding the underlying
    * `Single` node and applying the alias there.
    *
@@ -996,9 +1025,13 @@ export const withAlias: {
   /**
    * Adds an alias to an option.
    *
+   * **When to use**
+   *
    * Aliases allow params to be specified with alternative names,
    * typically single-character shortcuts like "-f" for "--force".
    *
+   * **Details**
+   *
    * This works on any param structure by recursively finding the underlying
    * `Single` node and applying the alias there.
    *
@@ -1036,6 +1069,8 @@ export const withAlias: {
 /**
  * Adds a description to an option for help text.
  *
+ * **Details**
+ *
  * Descriptions provide users with information about what the option does
  * when they view help documentation.
  *
@@ -1059,6 +1094,8 @@ export const withDescription: {
   /**
    * Adds a description to an option for help text.
    *
+   * **Details**
+   *
    * Descriptions provide users with information about what the option does
    * when they view help documentation.
    *
@@ -1082,6 +1119,8 @@ export const withDescription: {
   /**
    * Adds a description to an option for help text.
    *
+   * **Details**
+   *
    * Descriptions provide users with information about what the option does
    * when they view help documentation.
    *
@@ -1114,6 +1153,8 @@ export const withDescription: {
  * Hides a parameter from generated help output and completions while keeping
  * it parseable on the command line.
  *
+ * **When to use**
+ *
  * Useful for experimental, internal, or deprecated flags that should be
  * accepted but not advertised.
  *
@@ -1436,6 +1477,8 @@ export const mapTryCatch: {
 /**
  * Makes a flag or positional argument optional.
  *
+ * **Details**
+ *
  * When the parameter is absent, parsing succeeds with `Option.none()` instead
  * of failing with a missing option or missing argument error. When present, the
  * parsed value is wrapped in `Option.some()`.
@@ -1491,6 +1534,8 @@ export const optional = <Kind extends ParamKind, A>(
 /**
  * Makes a flag or positional argument optional by supplying a fallback value.
  *
+ * **Details**
+ *
  * The fallback may be a pure value or an effect. It is used only when the
  * parameter is absent; provided values are parsed normally.
  *
@@ -1521,6 +1566,8 @@ export const withDefault: {
   /**
    * Makes a flag or positional argument optional by supplying a fallback value.
    *
+   * **Details**
+   *
    * The fallback may be a pure value or an effect. It is used only when the
    * parameter is absent; provided values are parsed normally.
    *
@@ -1551,6 +1598,8 @@ export const withDefault: {
   /**
    * Makes a flag or positional argument optional by supplying a fallback value.
    *
+   * **Details**
+   *
    * The fallback may be a pure value or an effect. It is used only when the
    * parameter is absent; provided values are parsed normally.
    *
@@ -1708,6 +1757,8 @@ export type VariadicParamOptions = {
 /**
  * Creates a variadic parameter that can be specified multiple times.
  *
+ * **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).
@@ -1763,6 +1814,8 @@ export const variadic = <Kind extends ParamKind, A>(
 /**
  * Wraps an option to allow it to be specified multiple times within a range.
  *
+ * **Details**
+ *
  * This combinator transforms an option to accept between `min` and `max`
  * occurrences on the command line, returning an array of all provided values.
  *
@@ -1798,6 +1851,8 @@ export const between: {
   /**
    * Wraps an option to allow it to be specified multiple times within a range.
    *
+   * **Details**
+   *
    * This combinator transforms an option to accept between `min` and `max`
    * occurrences on the command line, returning an array of all provided values.
    *
@@ -1833,6 +1888,8 @@ export const between: {
   /**
    * Wraps an option to allow it to be specified multiple times within a range.
    *
+   * **Details**
+   *
    * This combinator transforms an option to accept between `min` and `max`
    * occurrences on the command line, returning an array of all provided values.
    *
@@ -1879,6 +1936,8 @@ export const between: {
 /**
  * Wraps an option to allow it to be specified at most `max` times.
  *
+ * **Details**
+ *
  * This combinator transforms an option to accept between 0 and `max`
  * occurrences on the command line, returning an array of all provided values.
  *
@@ -1905,6 +1964,8 @@ export const atMost: {
   /**
    * Wraps an option to allow it to be specified at most `max` times.
    *
+   * **Details**
+   *
    * This combinator transforms an option to accept between 0 and `max`
    * occurrences on the command line, returning an array of all provided values.
    *
@@ -1931,6 +1992,8 @@ export const atMost: {
   /**
    * Wraps an option to allow it to be specified at most `max` times.
    *
+   * **Details**
+   *
    * This combinator transforms an option to accept between 0 and `max`
    * occurrences on the command line, returning an array of all provided values.
    *
@@ -1964,6 +2027,8 @@ export const atMost: {
 /**
  * Wraps an option to require it to be specified at least `min` times.
  *
+ * **Details**
+ *
  * This combinator transforms an option to accept at least `min`
  * occurrences on the command line, returning an array of all provided values.
  *
@@ -1991,6 +2056,8 @@ export const atLeast: {
   /**
    * Wraps an option to require it to be specified at least `min` times.
    *
+   * **Details**
+   *
    * This combinator transforms an option to accept at least `min`
    * occurrences on the command line, returning an array of all provided values.
    *
@@ -2018,6 +2085,8 @@ export const atLeast: {
   /**
    * Wraps an option to require it to be specified at least `min` times.
    *
+   * **Details**
+   *
    * This combinator transforms an option to accept at least `min`
    * occurrences on the command line, returning an array of all provided values.
    *
@@ -2051,9 +2120,11 @@ export const atLeast: {
 
 /**
  * Filters and transforms parsed values, failing with a custom error message
- * if the filter function returns None.
+ * if the filter function returns `Option.none()`.
+ *
+ * **When to use**
  *
- * This combinator is useful for validation and transformation in a single step.
+ * Use this combinator for validation and transformation in a single step.
  *
  * **Example** (Filtering and transforming values)
  *
@@ -2076,9 +2147,11 @@ export const atLeast: {
 export const filterMap: {
   /**
    * Filters and transforms parsed values, failing with a custom error message
-   * if the filter function returns None.
+   * if the filter function returns `Option.none()`.
    *
-   * This combinator is useful for validation and transformation in a single step.
+   * **When to use**
+   *
+   * Use this combinator for validation and transformation in a single step.
    *
    * **Example** (Filtering and transforming values)
    *
@@ -2101,9 +2174,11 @@ export const filterMap: {
   <A, B>(filter: (a: A) => Option.Option<B>, onNone: (a: A) => string): <Kind extends ParamKind>(self: Param<Kind, A>) => Param<Kind, B>
   /**
    * Filters and transforms parsed values, failing with a custom error message
-   * if the filter function returns None.
+   * if the filter function returns `Option.none()`.
+   *
+   * **When to use**
    *
-   * This combinator is useful for validation and transformation in a single step.
+   * Use this combinator for validation and transformation in a single step.
    *
    * **Example** (Filtering and transforming values)
    *
@@ -2229,6 +2304,8 @@ export const filter: {
 /**
  * Sets a custom metavar (placeholder name) for the param in help documentation.
  *
+ * **Details**
+ *
  * The metavar is displayed in usage text to indicate what value the user should provide.
  * For example, `--output FILE` shows `FILE` as the metavar.
  *
@@ -2255,6 +2332,8 @@ export const withMetavar: {
   /**
    * Sets a custom metavar (placeholder name) for the param in help documentation.
    *
+   * **Details**
+   *
    * The metavar is displayed in usage text to indicate what value the user should provide.
    * For example, `--output FILE` shows `FILE` as the metavar.
    *
@@ -2281,6 +2360,8 @@ export const withMetavar: {
   /**
    * Sets a custom metavar (placeholder name) for the param in help documentation.
    *
+   * **Details**
+   *
    * The metavar is displayed in usage text to indicate what value the user should provide.
    * For example, `--output FILE` shows `FILE` as the metavar.
    *
@@ -2476,6 +2557,8 @@ export const orElse: {
  * Provides a fallback param and returns a `Result` indicating which param
  * succeeded.
  *
+ * **Details**
+ *
  * The original param's value is returned as `Result.succeed`, while the
  * fallback param's value is returned as `Result.fail`.
  *
@@ -2500,6 +2583,8 @@ export const orElseResult: {
    * Provides a fallback param and returns a `Result` indicating which param
    * succeeded.
    *
+   * **Details**
+   *
    * The original param's value is returned as `Result.succeed`, while the
    * fallback param's value is returned as `Result.fail`.
    *
@@ -2524,6 +2609,8 @@ export const orElseResult: {
    * Provides a fallback param and returns a `Result` indicating which param
    * succeeded.
    *
+   * **Details**
+   *
    * The original param's value is returned as `Result.succeed`, while the
    * fallback param's value is returned as `Result.fail`.
    *

package/src/unstable/cli/Primitive.ts

@@ -119,6 +119,8 @@ const makeSchemaPrimitive = <T, E>(
 /**
  * Creates a primitive that parses boolean values from string input.
  *
+ * **Details**
+ *
  * Recognizes various forms of true/false values:
  * - True values: "true", "1", "y", "yes", "on"
  * - False values: "false", "0", "n", "no", "off"
@@ -408,6 +410,8 @@ export const path = (
 /**
  * Creates a primitive that wraps string input in `Redacted`.
  *
+ * **Details**
+ *
  * The wrapped value is hidden when formatted or inspected, while the original
  * string remains available through the `Redacted` API when explicitly needed.
  *
@@ -527,6 +531,8 @@ const fileParsers: Record<string, (content: string) => unknown> = {
  * Creates a primitive that reads a file and parses its content as structured
  * data.
  *
+ * **Details**
+ *
  * The parser is selected from `options.format` when provided, otherwise from
  * the file extension. Supported formats include INI, JSON, TOML, YAML, and YML.
  *
@@ -671,6 +677,8 @@ export const keyValuePair: Primitive<Record<string, string>> = makePrimitive(
 /**
  * A sentinel primitive that always fails to parse a value.
  *
+ * **When to use**
+ *
  * Used for flags that don't accept values.
  *
  * **Example** (Rejecting option values)
@@ -695,6 +703,8 @@ export const none: Primitive<never> = makePrimitive("None", () => Effect.fail("T
 /**
  * Gets a human-readable type name for a primitive.
  *
+ * **When to use**
+ *
  * Used for generating help documentation.
  *
  * **Example** (Getting primitive type names)

package/src/unstable/cli/Prompt.ts

@@ -49,6 +49,8 @@ const TypeId = "~effect/cli/Prompt"
 /**
  * Represents an interactive terminal prompt that produces an `Output` value.
  *
+ * **Details**
+ *
  * A `Prompt` is an `Effect` that may fail with `Terminal.QuitError` and
  * requires the prompt environment needed to render frames, read input, and
  * access files or paths when a prompt uses them.
@@ -94,6 +96,8 @@ export type Action<State, Output> = Data.TaggedEnum<{
 /**
  * Type-level definition for the tagged `Prompt.Action` variants.
  *
+ * **Details**
+ *
  * It connects the action state and output type parameters to the `Beep`,
  * `NextFrame`, and `Submit` action cases.
  *
@@ -105,11 +109,12 @@ export interface ActionDefinition extends Data.TaggedEnum.WithGenerics<2> {
 }
 
 /**
- * Represents the set of handlers used by a `Prompt` to:
+ * Represents the set of handlers used by a `Prompt`.
+ *
+ * **Details**
  *
- *   - Render the current frame of the prompt
- *   - Process user input and determine the next `Prompt.Action` to take
- *   - Clear the terminal screen before the next frame
+ * The handlers render the current frame, process user input into the next
+ * `Prompt.Action`, and clear the terminal screen before the next frame.
  *
  * @category models
  * @since 4.0.0
@@ -301,6 +306,8 @@ export interface IntegerOptions {
 /**
  * Options for a floating-point number prompt.
  *
+ * **Details**
+ *
  * In addition to the numeric bounds and step settings from `IntegerOptions`,
  * the prompt can be configured with a display precision.
  *
@@ -331,6 +338,8 @@ export interface ListOptions extends TextOptions {
 /**
  * Options for a file-system selection prompt.
  *
+ * **Details**
+ *
  * They control which path type can be selected, the starting directory, paging,
  * and filtering of displayed entries.
  *
@@ -339,34 +348,25 @@ export interface ListOptions extends TextOptions {
  */
 export interface FileOptions {
   /**
-   * The path type that will be selected.
-   *
-   * Defaults to `"file"`.
+   * The path type that will be selected, defaulting to `"file"`.
    */
   readonly type?: Primitive.PathType
   /**
-   * The message to display in the prompt.
-   *
-   * Defaults to `"Choose a file"`.
+   * The message to display in the prompt, defaulting to `"Choose a file"`.
    */
   readonly message?: string
   /**
-   * Where the user will initially be prompted to select files from.
-   *
-   * Defaults to the current working directory.
+   * Where the user will initially be prompted to select files from, defaulting
+   * to the current working directory.
    */
   readonly startingPath?: string
   /**
-   * The number of choices to display at one time
-   *
-   * Defaults to `10`.
+   * The number of choices to display at one time, defaulting to `10`.
    */
   readonly maxPerPage?: number
   /**
-   * A function which removes any file from the prompt display where the
-   * specified predicate returns `true`.
-   *
-   * Defaults to returning all files.
+   * A predicate or effect that keeps a file in the prompt when it returns
+   * `true`, defaulting to returning all files.
    */
   readonly filter?: (file: string) => boolean | Effect.Effect<boolean, never, Environment>
 }
@@ -584,6 +584,8 @@ export declare namespace All {
   /**
    * Computes the prompt returned by `Prompt.all` for an iterable of prompts.
    *
+   * **Details**
+   *
    * The resulting prompt produces an array of each prompt's output value.
    *
    * @category utility types
@@ -637,6 +639,8 @@ export declare namespace All {
  * Runs all the provided prompts in sequence respecting the structure provided
  * in input.
  *
+ * **Details**
+ *
  * Supports either a tuple / iterable of prompts or a record / struct of prompts
  * as an argument.
  *
@@ -733,26 +737,15 @@ export const confirm = (options: ConfirmOptions): Prompt<boolean> => {
 /**
  * Creates a custom `Prompt` from the specified initial state and handlers.
  *
+ * **Details**
+ *
  * The initial state can either be a pure value or an `Effect`. This is
  * particularly useful when the initial state of the `Prompt` must be computed
- * by performing some effectful computation, such as reading data from the file
- * system.
- *
- * A `Prompt` is essentially a render loop where user input triggers a new frame
- * to be rendered to the `Terminal`. The `handlers` of a custom prompt are used
- * to control what is rendered to the `Terminal` each frame. During each frame,
- * the following occurs:
- *
- *   1. The `render` handler is called with this frame's prompt state and prompt
- *      action and returns an ANSI escape string to be rendered to the
- *      `Terminal`
- *   2. The `Terminal` obtains input from the user
- *   3. The `process` handler is called with the input obtained from the user
- *      and this frame's prompt state and returns the next prompt action that
- *      should be performed
- *   4. The `clear` handler is called with this frame's prompt state and prompt
- *      action and returns an ANSI escape string used to clear the screen of
- *      the `Terminal`
+ * by performing an effectful computation, such as reading data from the file
+ * system. A `Prompt` runs as a render loop: `render` returns ANSI output for
+ * the current frame, the `Terminal` obtains user input, `process` returns the
+ * next prompt action, and `clear` returns ANSI output used to clear the previous
+ * frame.
  *
  * @category constructors
  * @since 4.0.0
@@ -807,6 +800,8 @@ export const date = (options: DateOptions): Prompt<Date> => {
 /**
  * Creates a file-system selection prompt and returns the selected path.
  *
+ * **Details**
+ *
  * The prompt can be configured to select files, directories, or either path
  * type.
  *
@@ -876,6 +871,8 @@ export const flatMap: {
 /**
  * Creates a floating-point number prompt.
  *
+ * **Details**
+ *
  * The prompt supports minimum and maximum bounds, keyboard step sizes, display
  * precision, and additional validation before submission.
  *
@@ -925,6 +922,8 @@ export const hidden = (
 /**
  * Creates an integer prompt.
  *
+ * **Details**
+ *
  * The prompt supports minimum and maximum bounds, keyboard step sizes, and
  * additional validation before submission.
  *
@@ -1013,6 +1012,8 @@ export const password = (
  * Runs a prompt by reading terminal input and rendering prompt frames until the
  * prompt submits a value.
  *
+ * **Gotchas**
+ *
  * The returned effect may fail with `Terminal.QuitError` if terminal input ends
  * or the prompt is quit.
  *
@@ -1057,6 +1058,8 @@ const getSelectInitialIndex = <A>(choices: ReadonlyArray<SelectChoice<A>>): numb
  * Creates a prompt that lets the user select a single value from a list of
  * choices.
  *
+ * **Gotchas**
+ *
  * At most one choice may be marked as selected by default.
  *
  * @category constructors
@@ -1127,6 +1130,8 @@ export const autoComplete = <const A>(options: AutoCompleteOptions<A>): Prompt<A
  * Creates a prompt that lets the user select multiple choices and returns their
  * values as an array.
  *
+ * **Details**
+ *
  * The prompt supports default selected choices, bulk-selection commands, and
  * minimum or maximum selection counts.
  *
@@ -1159,8 +1164,10 @@ export const multiSelect = <const A>(
 /**
  * Creates a `Prompt` which immediately succeeds with the specified value.
  *
- * **NOTE**: This method will not attempt to obtain user input or render
- * anything to the screen.
+ * **Details**
+ *
+ * This prompt does not attempt to obtain user input or render anything to the
+ * screen.
  *
  * @category constructors
  * @since 4.0.0

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

@@ -98,6 +98,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
   readonly description?: string | undefined
   readonly shortDescription?: string | undefined
   readonly alias?: string | undefined
+  readonly hidden?: boolean | undefined
   readonly examples?: ReadonlyArray<Command.Example> | undefined
   readonly subcommands?: ReadonlyArray<SubcommandGroup> | undefined
   readonly parse?: ((input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>) | undefined
@@ -145,7 +146,9 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
     }
 
     let usage = commandPath.length > 0 ? commandPath.join(" ") : options.name
-    if (subcommands.some((group) => group.commands.length > 0)) {
+    // Only render `<subcommand>` in usage when at least one visible subcommand
+    // exists; an all-hidden subcommand tree should look like a leaf command.
+    if (subcommands.some((group) => group.commands.some((c) => !c.hidden))) {
       usage += " <subcommand>"
     }
     usage += " [flags]"
@@ -167,9 +170,14 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
     const subcommandDocs: Array<SubcommandGroupDoc> = []
 
     for (const group of subcommands) {
+      // Hidden subcommands still parse on the command line but are omitted
+      // from --help. Drop the whole group when nothing visible remains so we
+      // don't render an empty heading.
+      const visible = group.commands.filter((c) => !c.hidden)
+      if (visible.length === 0) continue
       subcommandDocs.push({
         group: group.group,
-        commands: Arr.map(group.commands, (subcommand) => ({
+        commands: Arr.map(visible as unknown as Arr.NonEmptyReadonlyArray<Command.Any>, (subcommand) => ({
           name: subcommand.name,
           alias: subcommand.alias,
           shortDescription: subcommand.shortDescription,
@@ -198,6 +206,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
     annotations,
     globalFlags,
     subcommands,
+    hidden: options.hidden ?? false,
     config,
     contextConfig,
     service,

package/src/unstable/cli/internal/completions/descriptor.ts

@@ -116,6 +116,9 @@ export const fromCommand = (cmd: Command.Any): Completions.CommandDescriptor =>
   const subcommands: Array<Completions.CommandDescriptor> = []
   for (const group of cmd.subcommands) {
     for (const subcommand of group.commands) {
+      // Omit hidden subcommands from completion scripts so tab-completion in
+      // the shell does not advertise commands that are absent from --help.
+      if (subcommand.hidden) continue
       subcommands.push(fromCommand(subcommand))
     }
   }