effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/cli/Prompt.ts

@@ -1,4 +1,28 @@
 /**
+ * The `Prompt` module provides composable, effectful building blocks for
+ * interactive command-line questions. A `Prompt<A>` describes terminal UI that
+ * renders frames, reads keyboard input, validates responses, and eventually
+ * produces a value of type `A`.
+ *
+ * **Common tasks**
+ *
+ * - Ask for text, password, hidden, list, confirm, toggle, number, or date input
+ * - Let users choose from select, autocomplete, multi-select, and file prompts
+ * - Combine prompts with {@link all}, {@link map}, and {@link flatMap}
+ * - Build specialized prompts with {@link custom}
+ * - Run a prompt against the current terminal with {@link run}
+ *
+ * **Gotchas**
+ *
+ * - Prompts require terminal services and may fail with `Terminal.QuitError`
+ *   when input ends or the prompt is quit
+ * - Rendering is frame-based: custom prompts must return ANSI output from
+ *   `render` and matching ANSI clearing output from `clear`
+ * - Choices and file lists are paged by `maxPerPage`, so keyboard navigation
+ *   and filtering should account for hidden off-page entries
+ * - `password` and `hidden` return `Redacted` values; unwrap them only at the
+ *   boundary where the secret is needed
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -6,13 +30,12 @@ import type { NoSuchElementError } from "../../Cause.ts"
 import type * as Cause from "../../Cause.ts"
 import * as Data from "../../Data.ts"
 import * as Effect from "../../Effect.ts"
+import * as Effectable from "../../Effectable.ts"
 import * as FileSystem from "../../FileSystem.ts"
 import { dual, pipe } from "../../Function.ts"
-import { YieldableProto } from "../../internal/core.ts"
 import * as EffectNumber from "../../Number.ts"
 import * as Option from "../../Option.ts"
 import * as Path from "../../Path.ts"
-import * as Pipeable from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Queue from "../../Queue.ts"
 import * as Redacted from "../../Redacted.ts"
@@ -24,28 +47,34 @@ import type * as Primitive from "./Primitive.ts"
 const TypeId = "~effect/cli/Prompt"
 
 /**
- * @since 4.0.0
+ * Represents an interactive terminal prompt that produces an `Output` value.
+ *
+ * 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.
+ *
  * @category models
+ * @since 4.0.0
  */
-export interface Prompt<Output>
-  extends Pipeable.Pipeable, Effect.Yieldable<Prompt<Output>, Output, Terminal.QuitError, Environment>
-{
+export interface Prompt<Output> extends Effect.Effect<Output, Terminal.QuitError, Environment> {
   readonly [TypeId]: {
     readonly _Output: Covariant<Output>
   }
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` if the provided value is a `Prompt`.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export const isPrompt = (u: unknown): u is Prompt<unknown> => Predicate.hasProperty(u, TypeId)
 
 /**
  * Represents the services available to a custom `Prompt`.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal
 
@@ -53,8 +82,8 @@ export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal
  * Represents the action that should be taken by a `Prompt` based upon the
  * user input received during the current frame.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export type Action<State, Output> = Data.TaggedEnum<{
   readonly Beep: {}
@@ -63,12 +92,13 @@ export type Action<State, Output> = Data.TaggedEnum<{
 }>
 
 /**
- * Represents the definition of an `Action`.
+ * Type-level definition for the tagged `Prompt.Action` variants.
  *
- * Required to create a `Data.TaggedEnum` with generic type arguments.
+ * It connects the action state and output type parameters to the `Beep`,
+ * `NextFrame`, and `Submit` action cases.
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface ActionDefinition extends Data.TaggedEnum.WithGenerics<2> {
   readonly taggedEnum: Action<this["A"], this["B"]>
@@ -81,8 +111,8 @@ export interface ActionDefinition extends Data.TaggedEnum.WithGenerics<2> {
  *   - Process user input and determine the next `Prompt.Action` to take
  *   - Clear the terminal screen before the next frame
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface Handlers<State, Output> {
   /**
@@ -123,8 +153,11 @@ export interface Handlers<State, Output> {
 }
 
 /**
- * @since 4.0.0
+ * Options for a confirmation prompt that asks the user to choose a boolean
+ * yes/no value.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface ConfirmOptions {
   /**
@@ -166,8 +199,11 @@ export interface ConfirmOptions {
 }
 
 /**
- * @since 4.0.0
+ * Options for a date prompt, including the displayed message, initial value,
+ * format mask, validation, and locale labels.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface DateOptions {
   /**
@@ -238,8 +274,11 @@ export interface DateOptions {
 }
 
 /**
- * @since 4.0.0
+ * Options for an integer prompt, including bounds, keyboard step sizes, and
+ * additional validation.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface IntegerOptions {
   /**
@@ -272,8 +311,13 @@ export interface IntegerOptions {
 }
 
 /**
- * @since 4.0.0
+ * Options for a floating-point number prompt.
+ *
+ * In addition to the numeric bounds and step settings from `IntegerOptions`,
+ * the prompt can be configured with a display precision.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface FloatOptions extends IntegerOptions {
   /**
@@ -283,8 +327,11 @@ export interface FloatOptions extends IntegerOptions {
 }
 
 /**
- * @since 4.0.0
+ * Options for a text prompt that returns a list of strings by splitting the
+ * input on a delimiter.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface ListOptions extends TextOptions {
   /**
@@ -294,8 +341,13 @@ export interface ListOptions extends TextOptions {
 }
 
 /**
- * @since 4.0.0
+ * Options for a file-system selection prompt.
+ *
+ * They control which path type can be selected, the starting directory, paging,
+ * and filtering of displayed entries.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface FileOptions {
   /**
@@ -332,8 +384,11 @@ export interface FileOptions {
 }
 
 /**
- * @since 4.0.0
+ * Options for a prompt that asks the user to select one value from a list of
+ * choices.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface SelectOptions<A> {
   /**
@@ -351,8 +406,11 @@ export interface SelectOptions<A> {
 }
 
 /**
- * @since 4.0.0
+ * Options for an autocomplete prompt that lets the user filter selectable
+ * choices by typing.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface AutoCompleteOptions<A> extends SelectOptions<A> {
   /**
@@ -370,8 +428,11 @@ export interface AutoCompleteOptions<A> extends SelectOptions<A> {
 }
 
 /**
- * @since 4.0.0
+ * Options for a multi-select prompt, including bulk-selection labels and
+ * minimum or maximum selection counts.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface MultiSelectOptions {
   /**
@@ -397,8 +458,11 @@ export interface MultiSelectOptions {
 }
 
 /**
- * @since 4.0.0
+ * Represents one choice displayed by select, autocomplete, and multi-select
+ * prompts.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface SelectChoice<A> {
   /**
@@ -425,8 +489,11 @@ export interface SelectChoice<A> {
 }
 
 /**
- * @since 4.0.0
+ * Options for text-entry prompts, including the displayed message, default
+ * text, and effectful validation before submission.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface TextOptions {
   /**
@@ -445,8 +512,11 @@ export interface TextOptions {
 }
 
 /**
- * @since 4.0.0
+ * Options for a toggle prompt that lets the user switch between active and
+ * inactive boolean states.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface ToggleOptions {
   /**
@@ -510,22 +580,33 @@ export const platformFigures = Effect.map(
 )
 
 /**
- * @since 4.0.0
+ * Type alias for any `Prompt`, regardless of its output type.
+ *
  * @category utility types
+ * @since 4.0.0
  */
 export type Any = Prompt<unknown>
 
 /**
+ * Namespace containing return-type helpers for `Prompt.all`.
+ *
  * @since 4.0.0
  */
 export declare namespace All {
   /**
+   * Computes the prompt returned by `Prompt.all` for an iterable of prompts.
+   *
+   * The resulting prompt produces an array of each prompt's output value.
+   *
    * @since 4.0.0
    */
   export type ReturnIterable<T extends Iterable<Any>> = [T] extends [Iterable<Prompt<infer A>>] ? Prompt<Array<A>>
     : never
 
   /**
+   * Computes the prompt returned by `Prompt.all` for a readonly tuple or array
+   * of prompts, preserving tuple positions in the output type.
+   *
    * @since 4.0.0
    */
   export type ReturnTuple<T extends ReadonlyArray<unknown>> = Prompt<
@@ -534,6 +615,9 @@ export declare namespace All {
   > extends infer X ? X : never
 
   /**
+   * Computes the prompt returned by `Prompt.all` for a record of prompts,
+   * preserving the record keys and replacing each prompt with its output type.
+   *
    * @since 4.0.0
    */
   export type ReturnObject<T> = [T] extends [{ [K: string]: Any }] ? Prompt<
@@ -544,6 +628,9 @@ export declare namespace All {
     : never
 
   /**
+   * Computes the return prompt type for `Prompt.all` based on the input
+   * structure.
+   *
    * @since 4.0.0
    */
   export type Return<
@@ -584,8 +671,8 @@ export declare namespace All {
  * const allWithRecord = Prompt.all({ username, password })
  * ```
  *
- * @since 4.0.0
  * @category collecting & elements
+ * @since 4.0.0
  */
 export const all: <
   const Arg extends Iterable<Prompt<any>> | Record<string, Prompt<any>>
@@ -622,8 +709,11 @@ const annotateLine = (line: string): string => Ansi.annotate(line, Ansi.bold)
 const annotateErrorLine = (line: string): string => Ansi.annotate(line, Ansi.combine(Ansi.italicized, Ansi.red))
 
 /**
- * @since 4.0.0
+ * Creates a confirmation prompt that asks the user to choose a boolean yes/no
+ * value.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const confirm = (options: ConfirmOptions): Prompt<boolean> => {
   const opts: Required<ConfirmOptions> = {
@@ -672,8 +762,8 @@ export const confirm = (options: ConfirmOptions): Prompt<boolean> => {
  *      action and returns an ANSI escape string used to clear the screen of
  *      the `Terminal`
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const custom = <State, Output>(
   initialState: State | Effect.Effect<State, never, Environment>,
@@ -689,8 +779,11 @@ export const custom = <State, Output>(
 }
 
 /**
- * @since 4.0.0
+ * Creates a date prompt that lets the user edit a formatted date value and
+ * validates the final `Date` before submission.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const date = (options: DateOptions): Prompt<Date> => {
   const opts: Required<DateOptions> = {
@@ -720,8 +813,13 @@ export const date = (options: DateOptions): Prompt<Date> => {
 }
 
 /**
- * @since 4.0.0
+ * Creates a file-system selection prompt and returns the selected path.
+ *
+ * The prompt can be configured to select files, directories, or either path
+ * type.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const file = (options: FileOptions = {}): Prompt<string> => {
   const opts: FileOptionsReq = {
@@ -749,18 +847,27 @@ export const file = (options: FileOptions = {}): Prompt<string> => {
 }
 
 /**
- * @since 4.0.0
+ * Sequences prompts by using the output of this prompt to create the next
+ * prompt.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const flatMap: {
   /**
-   * @since 4.0.0
+   * Sequences prompts by using the output of this prompt to create the next
+   * prompt.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <Output, Output2>(f: (output: Output) => Prompt<Output2>): (self: Prompt<Output>) => Prompt<Output2>
   /**
-   * @since 4.0.0
+   * Sequences prompts by using the output of this prompt to create the next
+   * prompt.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <Output, Output2>(self: Prompt<Output>, f: (output: Output) => Prompt<Output2>): Prompt<Output2>
 } = dual(2, <Output, Output2>(
@@ -775,8 +882,13 @@ export const flatMap: {
 })
 
 /**
- * @since 4.0.0
+ * Creates a floating-point number prompt.
+ *
+ * The prompt supports minimum and maximum bounds, keyboard step sizes, display
+ * precision, and additional validation before submission.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const float = (options: FloatOptions): Prompt<number> => {
   const opts: FloatOptionsReq = {
@@ -808,16 +920,24 @@ export const float = (options: FloatOptions): Prompt<number> => {
   })
 }
 /**
- * @since 4.0.0
+ * Creates a text prompt that does not echo typed input and returns the
+ * submitted value wrapped in `Redacted`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const hidden = (
   options: TextOptions
 ): Prompt<Redacted.Redacted> => basePrompt(options, "hidden").pipe(map(Redacted.make))
 
 /**
- * @since 4.0.0
+ * Creates an integer prompt.
+ *
+ * The prompt supports minimum and maximum bounds, keyboard step sizes, and
+ * additional validation before submission.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const integer = (options: IntegerOptions): Prompt<number> => {
   const opts: IntegerOptionsReq = {
@@ -849,8 +969,11 @@ export const integer = (options: IntegerOptions): Prompt<number> => {
 }
 
 /**
- * @since 4.0.0
+ * Creates a text prompt that returns an array of strings by splitting the
+ * submitted input on the configured delimiter.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const list = (options: ListOptions): Prompt<Array<string>> =>
   text(options).pipe(
@@ -858,18 +981,24 @@ export const list = (options: ListOptions): Prompt<Array<string>> =>
   )
 
 /**
- * @since 4.0.0
+ * Transforms the output value produced by a prompt.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const map: {
   /**
-   * @since 4.0.0
+   * Transforms the output value produced by a prompt.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <Output, Output2>(f: (output: Output) => Output2): (self: Prompt<Output>) => Prompt<Output2>
   /**
-   * @since 4.0.0
+   * Transforms the output value produced by a prompt.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <Output, Output2>(self: Prompt<Output>, f: (output: Output) => Output2): Prompt<Output2>
 } = dual(2, <Output, Output2>(
@@ -878,18 +1007,25 @@ export const map: {
 ) => flatMap(self, (a) => succeed(f(a))))
 
 /**
- * @since 4.0.0
+ * Creates a password prompt that masks typed input and returns the submitted
+ * value wrapped in `Redacted`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const password = (
   options: TextOptions
 ): Prompt<Redacted.Redacted> => basePrompt(options, "password").pipe(map(Redacted.make))
 
 /**
- * Executes the specified `Prompt`.
+ * Runs a prompt by reading terminal input and rendering prompt frames until the
+ * prompt submits a value.
+ *
+ * The returned effect may fail with `Terminal.QuitError` if terminal input ends
+ * or the prompt is quit.
  *
- * @since 4.0.0
  * @category execution
+ * @since 4.0.0
  */
 export const run: <Output>(
   self: Prompt<Output>
@@ -926,8 +1062,13 @@ const getSelectInitialIndex = <A>(choices: ReadonlyArray<SelectChoice<A>>): numb
 }
 
 /**
- * @since 4.0.0
+ * Creates a prompt that lets the user select a single value from a list of
+ * choices.
+ *
+ * At most one choice may be marked as selected by default.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const select = <const A>(options: SelectOptions<A>): Prompt<A> => {
   const opts: SelectOptionsReq<A> = {
@@ -960,8 +1101,8 @@ export const select = <const A>(options: SelectOptions<A>): Prompt<A> => {
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const autoComplete = <const A>(options: AutoCompleteOptions<A>): Prompt<A> => {
   const opts: AutoCompleteOptionsReq<A> = {
@@ -991,8 +1132,14 @@ export const autoComplete = <const A>(options: AutoCompleteOptions<A>): Prompt<A
 }
 
 /**
- * @since 4.0.0
+ * Creates a prompt that lets the user select multiple choices and returns their
+ * values as an array.
+ *
+ * The prompt supports default selected choices, bulk-selection commands, and
+ * minimum or maximum selection counts.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const multiSelect = <const A>(
   options: SelectOptions<A> & MultiSelectOptions
@@ -1023,8 +1170,8 @@ export const multiSelect = <const A>(
  * **NOTE**: This method will not attempt to obtain user input or render
  * anything to the screen.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const succeed = <A>(value: A): Prompt<A> => {
   const op = Object.create(proto)
@@ -1034,16 +1181,22 @@ export const succeed = <A>(value: A): Prompt<A> => {
 }
 
 /**
- * @since 4.0.0
+ * Creates a text-entry prompt that echoes input and returns the submitted
+ * string after validation.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const text = (
   options: TextOptions
 ): Prompt<string> => basePrompt(options, "text")
 
 /**
- * @since 4.0.0
+ * Creates a toggle prompt that lets the user switch between active and inactive
+ * states and returns the selected boolean value.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const toggle = (options: ToggleOptions): Prompt<boolean> => {
   const opts: ToggleOptionsReq = {
@@ -1060,15 +1213,14 @@ export const toggle = (options: ToggleOptions): Prompt<boolean> => {
 }
 
 const proto = {
-  ...YieldableProto,
+  ...Effectable.Prototype<Prompt<any>>({
+    label: "Prompt",
+    evaluate() {
+      return run(this)
+    }
+  }),
   [TypeId]: {
     _Output: (_: never) => _
-  },
-  asEffect(): Effect.Effect<unknown, Terminal.QuitError, Environment> {
-    return run(this as any)
-  },
-  pipe() {
-    return Pipeable.pipeArguments(this, arguments)
   }
 }
 
@@ -1882,7 +2034,7 @@ const resolveCurrentPath = (
   }
   if (Option.isSome(options.startingPath)) {
     const startingPath = options.startingPath.value
-    return Effect.flatMap(FileSystem.FileSystem.asEffect(), (fs) =>
+    return Effect.flatMap(FileSystem.FileSystem, (fs) =>
       // Ensure the user provided starting path exists
       Effect.orDie(fs.exists(startingPath)).pipe(
         Effect.flatMap((exists) =>

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

@@ -1,3 +1,16 @@
+/**
+ * Internal ANSI escape sequence helpers used by the unstable CLI rendering
+ * implementation. This module centralizes the control codes for text styling,
+ * cursor movement, line erasing, and terminal notifications so renderers can
+ * compose terminal output without scattering raw escape sequences throughout
+ * the CLI internals.
+ *
+ * The helpers deliberately work with plain strings because terminal rendering
+ * is sensitive to ordering: style codes must be reset after annotated text,
+ * cursor operations must account for one-based terminal coordinates, and line
+ * clearing usually needs to preserve the cursor position expected by the next
+ * frame.
+ */
 const ESC = "\x1B["
 const BEL = "\x07"
 const SEP = ";"