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

package/src/unstable/cli/Param.ts

@@ -83,7 +83,15 @@ export type ParamKind = "argument" | "flag"
 export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal | ChildProcessSpawner
 
 /**
- * Kind discriminator for positional argument parameters.
+ * Defines the 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
@@ -91,7 +99,14 @@ export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal
 export const argumentKind: "argument" = "argument" as const
 
 /**
- * Kind discriminator for flag parameters.
+ * Defines the 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)
    *

package/src/unstable/cli/Primitive.ts

@@ -1,13 +1,62 @@
 /**
- * Primitive types for CLI parameter parsing.
+ * The `Primitive` module defines the lowest-level value parsers used by the
+ * unstable CLI package. A `Primitive<A>` takes one raw command-line string and
+ * returns an `Effect` that either produces an `A` or fails with a parser
+ * message.
+ *
+ * `Argument` and `Flag` build on primitives to add names, aliases, defaults,
+ * prompts, config fallbacks, repetition, and help metadata. Use this module
+ * directly when defining a custom CLI input shape or when composing parser
+ * behavior before it becomes an argument or flag.
+ *
+ * **Mental model**
+ *
+ * - A primitive parses one value token; it does not know whether the token came
+ *   from a positional argument or a named flag.
+ * - Parsing may be pure, such as {@link string}, {@link integer},
+ *   {@link boolean}, or {@link choice}, or effectful, such as {@link path},
+ *   {@link fileText}, {@link fileParse}, and {@link fileSchema}.
+ * - Failure is represented as a string message so higher-level CLI parsers can
+ *   attach it to generated usage and help output.
+ * - File and path primitives require filesystem and path services through the
+ *   parsing effect environment.
+ *
+ * **Common tasks**
+ *
+ * - Parse scalar values with {@link string}, {@link integer}, {@link float},
+ *   {@link boolean}, and {@link date}.
+ * - Restrict input to named alternatives with {@link choice}.
+ * - Resolve and validate filesystem paths with {@link path}.
+ * - Read raw file content with {@link fileText}, parse structured files with
+ *   {@link fileParse}, or decode parsed content with {@link fileSchema}.
+ * - Hide sensitive input with {@link redacted}.
+ * - Parse `key=value` entries with {@link keyValuePair}.
+ *
+ * **Example** (Parsing raw CLI values)
  *
- * Primitives handle the low-level parsing of string input into typed values.
- * Most users should use the higher-level `Argument` and `Flag` modules instead.
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Primitive } from "effect/unstable/cli"
+ *
+ * const parseValues = Effect.gen(function*() {
+ *   const port = yield* Primitive.integer.parse("8080")
+ *   const mode = yield* Primitive.choice([
+ *     ["dev", "development"],
+ *     ["prod", "production"]
+ *   ] as const).parse("prod")
+ *
+ *   return { port, mode }
+ * })
+ * ```
+ *
+ * **Gotchas**
  *
- * This module is primarily useful for:
- * - Creating custom primitive types
- * - Understanding how CLI parsing works internally
- * - Advanced customization of parsing behavior
+ * - `choice` matches input strings exactly; it does not normalize casing or
+ *   trim whitespace.
+ * - `fileParse` selects a parser from `options.format` or the file extension;
+ *   unsupported formats fail before schema decoding.
+ * - {@link none} is a sentinel parser that always fails. It is used by higher
+ *   layers for parameters that must reject attached values.
  *
  * @since 4.0.0
  */
@@ -675,11 +724,11 @@ export const keyValuePair: Primitive<Record<string, string>> = makePrimitive(
 )
 
 /**
- * A sentinel primitive that always fails to parse a value.
+ * Creates a sentinel primitive that always fails to parse a value.
  *
  * **When to use**
  *
- * Used for flags that don't accept values.
+ * Use when you need flags that don't accept values.
  *
  * **Example** (Rejecting option values)
  *
@@ -705,7 +754,7 @@ export const none: Primitive<never> = makePrimitive("None", () => Effect.fail("T
  *
  * **When to use**
  *
- * Used for generating help documentation.
+ * Use when you need generating help documentation.
  *
  * **Example** (Getting primitive type names)
  *

package/src/unstable/cli/Prompt.ts

@@ -158,7 +158,7 @@ export interface ConfirmOptions {
    */
   readonly message: string
   /**
-   * The intitial value of the confirm prompt (defaults to `false`).
+   * The initial value of the confirm prompt (defaults to `false`).
    */
   readonly initial?: boolean
   /**
@@ -278,6 +278,10 @@ export interface IntegerOptions {
    * The message to display in the prompt.
    */
   readonly message: string
+  /**
+   * The default value of the integer prompt.
+   */
+  readonly default?: number
   /**
    * The minimum value that can be entered by the user (defaults to `-Infinity`).
    */
@@ -360,6 +364,10 @@ export interface FileOptions {
    * to the current working directory.
    */
   readonly startingPath?: string
+  /**
+   * The default path to select when the prompt is first displayed.
+   */
+  readonly default?: string
   /**
    * The number of choices to display at one time, defaulting to `10`.
    */
@@ -708,6 +716,17 @@ const annotateErrorLine = (line: string): string => Ansi.annotate(line, Ansi.com
  * Creates a confirmation prompt that asks the user to choose a boolean yes/no
  * value.
  *
+ * **When to use**
+ *
+ * Use to ask for a yes/no answer that can be submitted directly.
+ *
+ * **Details**
+ *
+ * `initial` defaults to `false`. Enter submits the current default, yes-style
+ * input submits `true`, no-style input submits `false`, and other input beeps.
+ *
+ * @see {@link toggle} for an interactive switch-before-submit boolean prompt
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -767,6 +786,20 @@ export const custom = <State, Output>(
  * Creates a date prompt that lets the user edit a formatted date value and
  * validates the final `Date` before submission.
  *
+ * **Details**
+ *
+ * `initial` defaults to the current `Date`, `dateMask` defaults to
+ * `YYYY-MM-DD HH:mm:ss`, mask parsing creates editable date parts plus literal
+ * tokens, `locales` customizes month and weekday labels, and `validate` runs on
+ * submission.
+ *
+ * **Gotchas**
+ *
+ * A supplied `initial` `Date` is edited in place during prompt interaction.
+ * Date edits use JavaScript `Date` setters, so out-of-range typed values can
+ * normalize before validation. If the prompt is meant to be editable,
+ * `dateMask` should contain at least one editable date token.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -813,6 +846,7 @@ export const file = (options: FileOptions = {}): Prompt<string> => {
     type: options.type ?? "file",
     message: options.message ?? `Choose a file`,
     startingPath: Option.fromUndefinedOr(options.startingPath),
+    default: Option.fromUndefinedOr(options.default),
     maxPerPage: options.maxPerPage ?? 10,
     filter: options.filter ?? (() => Effect.succeed(true))
   }
@@ -822,9 +856,22 @@ export const file = (options: FileOptions = {}): Prompt<string> => {
     Environment
   > = Effect.gen(function*() {
     const currentPath = yield* resolveCurrentPath(Option.none(), opts)
-    const files = yield* getFileList(currentPath, opts)
+    const path = yield* Path.Path
+    const defaultPath = Option.map(opts.default, (defaultValue) => path.resolve(currentPath, defaultValue))
+    const initialPath = Option.match(defaultPath, {
+      onNone: () => currentPath,
+      onSome: (defaultPath) => path.dirname(defaultPath)
+    })
+    const files = yield* getFileList(initialPath, opts)
+    const cursor = Option.match(defaultPath, {
+      onNone: () => 0,
+      onSome: (defaultPath) => {
+        const index = files.indexOf(path.basename(defaultPath))
+        return index === -1 ? 0 : index
+      }
+    })
     const confirm = Confirm.Hide()
-    return { cursor: 0, files, allFiles: files, query: "", path: Option.none(), confirm }
+    return { cursor, files, allFiles: files, query: "", path: Option.map(defaultPath, path.dirname), confirm }
   })
   return custom(initialState, {
     render: handleFileRender(opts),
@@ -834,24 +881,21 @@ export const file = (options: FileOptions = {}): Prompt<string> => {
 }
 
 /**
- * Sequences prompts by using the output of this prompt to create the next
- * prompt.
+ * Composes prompts by using the output of this prompt to create the next prompt.
  *
  * @category combinators
  * @since 4.0.0
  */
 export const flatMap: {
   /**
-   * Sequences prompts by using the output of this prompt to create the next
-   * prompt.
+   * Composes 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>
   /**
-   * Sequences prompts by using the output of this prompt to create the next
-   * prompt.
+   * Composes prompts by using the output of this prompt to create the next prompt.
    *
    * @category combinators
    * @since 4.0.0
@@ -881,6 +925,7 @@ export const flatMap: {
  */
 export const float = (options: FloatOptions): Prompt<number> => {
   const opts: FloatOptionsReq = {
+    default: 0,
     min: Number.NEGATIVE_INFINITY,
     max: Number.POSITIVE_INFINITY,
     incrementBy: 1,
@@ -897,9 +942,10 @@ export const float = (options: FloatOptions): Prompt<number> => {
     },
     ...options
   }
+  const initialValue = options.default === undefined ? "" : `${opts.default}`
   const initialState: NumberState = {
-    cursor: 0,
-    value: "",
+    cursor: initialValue.length,
+    value: initialValue,
     error: Option.none()
   }
   return custom(initialState, {
@@ -932,6 +978,7 @@ export const hidden = (
  */
 export const integer = (options: IntegerOptions): Prompt<number> => {
   const opts: IntegerOptionsReq = {
+    default: 0,
     min: Number.NEGATIVE_INFINITY,
     max: Number.POSITIVE_INFINITY,
     incrementBy: 1,
@@ -947,9 +994,10 @@ export const integer = (options: IntegerOptions): Prompt<number> => {
     },
     ...options
   }
+  const initialValue = options.default === undefined ? "" : `${opts.default}`
   const initialState: NumberState = {
-    cursor: 0,
-    value: "",
+    cursor: initialValue.length,
+    value: initialValue,
     error: Option.none()
   }
   return custom(initialState, {
@@ -1999,8 +2047,9 @@ class Meridiem extends DatePart {
   }
 }
 
-interface FileOptionsReq extends Required<Omit<FileOptions, "startingPath">> {
+interface FileOptionsReq extends Required<Omit<FileOptions, "startingPath" | "default">> {
   readonly startingPath: Option.Option<string>
+  readonly default: Option.Option<string>
 }
 
 interface FileState {