effect 4.0.4 → 4.0.6

package/src/cli/Param.ts

@@ -213,6 +213,15 @@ export interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
   readonly primitiveType: Primitive.Primitive<A>
   readonly typeName?: string | undefined
   readonly hidden: boolean
+  /**
+   * Raw value used for a bare flag. See `withOptionalValue`.
+   */
+  readonly optionalValue?: string | undefined
+  /**
+   * Long name that sets a boolean flag to `false`. `undefined` means the
+   * default `no-<name>`, `false` means no negated form. See `withNegation`.
+   */
+  readonly negation?: string | false | undefined
 }
 
 /**
@@ -362,6 +371,8 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
   readonly description?: Option.Option<string> | undefined
   readonly aliases?: ReadonlyArray<string> | undefined
   readonly hidden?: boolean | undefined
+  readonly optionalValue?: string | undefined
+  readonly negation?: string | false | undefined
 }): Single<Kind, A> => {
   const parse: Parse<A> = (args) =>
     params.kind === argumentKind
@@ -2664,6 +2675,213 @@ export const withMetavar: {
       typeName: metavar
     })))
 
+/**
+ * Lets a flag be given without a value, in which case `value` is used.
+ *
+ * **Details**
+ *
+ * Follows GNU-style optional values. An explicit value must be attached with
+ * `=` (`--watch=until-done`), and a bare `--watch` is parsed as
+ * `--watch=<value>`. The flag never consumes the next token. It is still
+ * required unless it is made optional or given a default.
+ *
+ * **Example** (Flag with an optional value)
+ *
+ * ```ts import.meta.vitest
+ * import { Param } from "effect/cli"
+ *
+ * const watch = Param.String(Param.flagKind, "watch").pipe(
+ *   Param.withOptionalValue("first-failure"),
+ *   Param.optional
+ * )
+ * watch.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withOptionalValue: {
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values. An explicit value must be attached with
+   * `=` (`--watch=until-done`), and a bare `--watch` is parsed as
+   * `--watch=<value>`. The flag never consumes the next token. It is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Param } from "effect/cli"
+   *
+   * const watch = Param.String(Param.flagKind, "watch").pipe(
+   *   Param.withOptionalValue("first-failure"),
+   *   Param.optional
+   * )
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  (value: string): <A>(self: Param<typeof flagKind, A>) => Param<typeof flagKind, A>
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values. An explicit value must be attached with
+   * `=` (`--watch=until-done`), and a bare `--watch` is parsed as
+   * `--watch=<value>`. The flag never consumes the next token. It is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Param } from "effect/cli"
+   *
+   * const watch = Param.String(Param.flagKind, "watch").pipe(
+   *   Param.withOptionalValue("first-failure"),
+   *   Param.optional
+   * )
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <A>(self: Param<typeof flagKind, A>, value: string): Param<typeof flagKind, A>
+} = dual(2, <A>(
+  self: Param<typeof flagKind, A>,
+  value: string
+) =>
+  transformSingle(self, (single) =>
+    makeSingle({
+      ...single,
+      optionalValue: value
+    })))
+
+/**
+ * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+ *
+ * **Details**
+ *
+ * The new name replaces the default, so `--no-<name>` is no longer accepted.
+ * Has no effect on non-boolean flags.
+ *
+ * **Example** (Renaming a boolean flag's negation)
+ *
+ * ```ts import.meta.vitest
+ * import { Param } from "effect/cli"
+ *
+ * // --validate sets true, --skip-validate sets false
+ * const validate = Param.Boolean(Param.flagKind, "validate").pipe(
+ *   Param.withNegation("skip-validate")
+ * )
+ * validate.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withNegation: {
+  /**
+   * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+   *
+   * **Details**
+   *
+   * The new name replaces the default, so `--no-<name>` is no longer accepted.
+   * Has no effect on non-boolean flags.
+   *
+   * **Example** (Renaming a boolean flag's negation)
+   *
+   * ```ts import.meta.vitest
+   * import { Param } from "effect/cli"
+   *
+   * // --validate sets true, --skip-validate sets false
+   * const validate = Param.Boolean(Param.flagKind, "validate").pipe(
+   *   Param.withNegation("skip-validate")
+   * )
+   * validate.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  (name: string): <A>(self: Param<typeof flagKind, A>) => Param<typeof flagKind, A>
+  /**
+   * Renames the negated form of a boolean flag, which defaults to `--no-<name>`.
+   *
+   * **Details**
+   *
+   * The new name replaces the default, so `--no-<name>` is no longer accepted.
+   * Has no effect on non-boolean flags.
+   *
+   * **Example** (Renaming a boolean flag's negation)
+   *
+   * ```ts import.meta.vitest
+   * import { Param } from "effect/cli"
+   *
+   * // --validate sets true, --skip-validate sets false
+   * const validate = Param.Boolean(Param.flagKind, "validate").pipe(
+   *   Param.withNegation("skip-validate")
+   * )
+   * validate.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <A>(self: Param<typeof flagKind, A>, name: string): Param<typeof flagKind, A>
+} = dual(2, <A>(
+  self: Param<typeof flagKind, A>,
+  name: string
+) =>
+  transformSingle(self, (single) =>
+    makeSingle({
+      ...single,
+      negation: name
+    })))
+
+/**
+ * Removes the negated `--no-<name>` form of a boolean flag.
+ *
+ * **Details**
+ *
+ * The negated form is then rejected as an unrecognized flag and left out of
+ * shell completions. Has no effect on non-boolean flags.
+ *
+ * **Example** (Disabling a boolean flag's negation)
+ *
+ * ```ts import.meta.vitest
+ * import { Param } from "effect/cli"
+ *
+ * // --unsafe sets true, --no-unsafe is rejected
+ * const unsafe = Param.Boolean(Param.flagKind, "unsafe").pipe(
+ *   Param.withoutNegation
+ * )
+ * unsafe.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withoutNegation = <A>(self: Param<typeof flagKind, A>): Param<typeof flagKind, A> =>
+  transformSingle(self, (single) =>
+    makeSingle({
+      ...single,
+      negation: false
+    }))
+
 /**
  * Validates parsed values against a Schema, providing detailed error messages.
  *

package/src/cli/TerminalCapabilities.ts

@@ -0,0 +1,156 @@
+/**
+ * Detection of whether a CLI can color, animate, or prompt.
+ *
+ * The default reads `NO_COLOR`, `FORCE_COLOR`, `TERM`, and the TTY state of
+ * the current process. The layer reads the same variables through
+ * `ConfigProvider`, plus the TTY state of `Stdio`. Unless a
+ * `CliOutput.Formatter` is provided, the built-in help, version, and error
+ * output of `Command` follows `canColor`.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Config from "../Config.ts"
+import * as Context from "../Context.ts"
+import * as Effect from "../Effect.ts"
+import * as Layer from "../Layer.ts"
+import * as Option from "../Option.ts"
+import * as Stdio from "../Stdio.ts"
+
+/**
+ * Terminal rendering flags for the current process.
+ *
+ * **Details**
+ *
+ * `canColor` says whether styling will be rendered rather than stored as
+ * bytes. `canAnimate` says whether output is being watched, so pacing means
+ * something. `canPrompt` says whether a question can be asked and answered.
+ * Only `canColor` is read by the built-in `Command` output; the other two are
+ * for application code that renders its own output.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface TerminalCapabilities {
+  readonly canColor: boolean
+  readonly canAnimate: boolean
+  readonly canPrompt: boolean
+}
+
+/**
+ * Reference to the terminal capabilities of the current process.
+ *
+ * **When to use**
+ *
+ * Use when application output should share the built-in help, version, and
+ * error output's answer. Provide `layer` to detect through
+ * `ConfigProvider` and `Stdio`, or provide a value to override detection.
+ *
+ * **Details**
+ *
+ * The default is detected from the current process the first time it is
+ * read, so later changes to the environment do not affect it. Without a
+ * `process` global, every flag is `false`.
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export const TerminalCapabilities: Context.Reference<TerminalCapabilities> = Context.Reference(
+  "effect/cli/TerminalCapabilities",
+  { defaultValue: () => fromProcess() }
+)
+
+const isPresent = (value: string | undefined): value is string => value !== undefined && value.length > 0
+
+const isForcingColor = (value: string | undefined): boolean =>
+  isPresent(value) && value !== "0" && value.toLowerCase() !== "false"
+
+const detect = (input: {
+  readonly noColor: string | undefined
+  readonly forceColor: string | undefined
+  readonly term: string | undefined
+  readonly stdinIsTerminal: boolean
+  readonly stdoutIsTerminal: boolean
+}): TerminalCapabilities => {
+  if (input.term === "dumb") {
+    return { canColor: false, canAnimate: false, canPrompt: false }
+  }
+
+  return {
+    canColor: !isPresent(input.noColor) && (isForcingColor(input.forceColor) || input.stdoutIsTerminal),
+    canAnimate: input.stdoutIsTerminal,
+    canPrompt: input.stdinIsTerminal && input.stdoutIsTerminal
+  }
+}
+
+const fromProcess = (): TerminalCapabilities => {
+  const process = (globalThis as any).process
+  return detect({
+    noColor: process?.env?.NO_COLOR,
+    forceColor: process?.env?.FORCE_COLOR,
+    term: process?.env?.TERM,
+    stdinIsTerminal: process?.stdin?.isTTY === true,
+    stdoutIsTerminal: process?.stdout?.isTTY === true
+  })
+}
+
+const environment = Config.all({
+  noColor: Config.option(Config.String("NO_COLOR")),
+  forceColor: Config.option(Config.String("FORCE_COLOR")),
+  term: Config.option(Config.String("TERM"))
+})
+
+/**
+ * Detects terminal capabilities from `Stdio` and the current `ConfigProvider`.
+ *
+ * **Details**
+ *
+ * `TERM=dumb` clears all three flags, because a terminal that cannot move the
+ * cursor can neither animate nor redraw a prompt. Otherwise `NO_COLOR`, when
+ * set to any non-empty value, disables color and wins over `FORCE_COLOR`.
+ * `FORCE_COLOR` forces color even off a TTY, except for `0` and `false`, which
+ * mean "not forcing". Empty variables count as unset, matching
+ * `ConfigProvider.fromEnv`, so `FORCE_COLOR=` does not force color on.
+ * `canPrompt` requires both standard input and standard output to be
+ * terminals. A `ConfigProvider` fault is a defect, so the layer never fails.
+ *
+ * **Example** (NO_COLOR wins over FORCE_COLOR)
+ *
+ * ```ts import.meta.vitest
+ * import { ConfigProvider, Effect, Stdio } from "effect"
+ * import { TerminalCapabilities } from "effect/cli"
+ *
+ * const program = Effect.gen(function*() {
+ *   const caps = yield* TerminalCapabilities.TerminalCapabilities
+ *   return caps.canColor
+ * }).pipe(
+ *   Effect.provide(TerminalCapabilities.layer),
+ *   Effect.provide(Stdio.layerTest({ stdoutIsTerminal: Effect.succeed(true) })),
+ *   Effect.provideService(
+ *     ConfigProvider.ConfigProvider,
+ *     ConfigProvider.fromEnv({ env: { NO_COLOR: "1", FORCE_COLOR: "1" } })
+ *   )
+ * )
+ *
+ * Effect.runSync(program) // => false
+ * ```
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layer: Layer.Layer<never, never, Stdio.Stdio> = Layer.effect(
+  TerminalCapabilities
+)(Effect.gen(function*() {
+  const stdio = yield* Stdio.Stdio
+  const env = yield* Effect.orDie(environment)
+  return detect({
+    noColor: Option.getOrUndefined(env.noColor),
+    forceColor: Option.getOrUndefined(env.forceColor),
+    term: Option.getOrUndefined(env.term),
+    stdinIsTerminal: yield* stdio.stdinIsTerminal,
+    stdoutIsTerminal: yield* stdio.stdoutIsTerminal
+  })
+}))

package/src/cli/index.ts

@@ -76,3 +76,9 @@ export * as Primitive from "./Primitive.ts"
  * @since 4.0.0
  */
 export * as Prompt from "./Prompt.ts"
+
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as TerminalCapabilities from "./TerminalCapabilities.ts"

package/src/cli/internal/command.ts

@@ -48,6 +48,7 @@ export interface CommandInternal<Name extends string, Input, E, R, ContextInput>
     commandPath: ReadonlyArray<string>
   ) => Effect.Effect<void, E | CliError.CliError, R | Environment>
   readonly buildHelpDoc: (commandPath: ReadonlyArray<string>) => HelpDoc
+  readonly resolveExamples: (commandPath: ReadonlyArray<string>) => ReadonlyArray<Command.Example>
 }
 
 /* ========================================================================== */
@@ -99,7 +100,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
   readonly shortDescription?: string | undefined
   readonly alias?: string | undefined
   readonly unlisted?: boolean | undefined
-  readonly examples?: ReadonlyArray<Command.Example> | undefined
+  readonly resolveExamples?: ((commandPath: ReadonlyArray<string>) => ReadonlyArray<Command.Example>) | undefined
   readonly subcommands?: ReadonlyArray<SubcommandGroup> | undefined
   readonly parse?: ((input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>) | undefined
   readonly parseContext?:
@@ -115,6 +116,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
   const annotations = options.annotations ?? Context.empty()
   const globalFlags = options.globalFlags ?? []
   const subcommands = options.subcommands ?? []
+  const resolveExamples = options.resolveExamples ?? noExamples
 
   const handle = (
     input: Input,
@@ -188,7 +190,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
       })
     }
 
-    const examples: ReadonlyArray<ExampleDoc> = options.examples ?? []
+    const examples: ReadonlyArray<ExampleDoc> = resolveExamples(commandPath)
 
     return {
       description: options.description ?? "",
@@ -204,7 +206,8 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
   return Object.assign(Object.create(Proto), {
     [TypeId]: TypeId,
     name: options.name,
-    examples: options.examples ?? [],
+    examples: resolveExamples([options.name]),
+    resolveExamples,
     annotations,
     globalFlags,
     subcommands,
@@ -232,6 +235,8 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
 /* Helpers                                                                    */
 /* ========================================================================== */
 
+const noExamples = (): ReadonlyArray<Command.Example> => []
+
 /**
  * Converts a single flag param into a FlagDoc for help display.
  *
@@ -242,10 +247,11 @@ export const toFlagDoc = (
   metadata: ReturnType<typeof Param.getParamMetadata>
 ): FlagDoc => {
   const formattedAliases = single.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`)
+  const type = single.typeName ?? Primitive.getTypeName(single.primitiveType)
   return {
     name: single.name,
     aliases: formattedAliases,
-    type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
+    type: single.optionalValue === undefined ? type : `[=${type}]`,
     description: appendChoiceKeys(single.description, Primitive.getChoiceKeys(single.primitiveType)),
     required: single.primitiveType._tag !== "Boolean" && !metadata.isOptional
   }

package/src/cli/internal/completions/bash.ts

@@ -7,6 +7,7 @@
  * @internal
  */
 import type * as Completions from "../../Completions.ts"
+import { negatedName, takesSeparateValue } from "./descriptor.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -21,8 +22,9 @@ const flagNamesForWordlist = (flag: Completions.FlagDescriptor): Array<string> =
   for (const alias of flag.aliases) {
     names.push(alias.length === 1 ? `-${alias}` : `--${alias}`)
   }
-  if (flag.type._tag === "Boolean") {
-    names.push(`--no-${flag.name}`)
+  const negation = negatedName(flag)
+  if (negation !== undefined) {
+    names.push(`--${negation}`)
   }
   return names
 }
@@ -164,7 +166,7 @@ const generateFunction = (
   lines.push(``)
 
   // Build flag-value dispatch
-  const flagsWithValues = descriptor.flags.filter((f) => f.type._tag !== "Boolean")
+  const flagsWithValues = descriptor.flags.filter(takesSeparateValue)
   if (flagsWithValues.length > 0) {
     lines.push(`  # Flag value completions`)
     lines.push(`  case "$prev" in`)
@@ -196,7 +198,7 @@ const generateFunction = (
     lines.push(`    fi`)
     lines.push(`    case "\${words[i]}" in`)
     for (const flag of descriptor.flags) {
-      if (flag.type._tag === "Boolean") continue
+      if (!takesSeparateValue(flag)) continue
       const forms = flagNamesForWordlist(flag)
       lines.push(`      ${forms.join("|")}) _skip_next=1 ;;`)
       lines.push(`      ${forms.map((form) => `${form}=*`).join("|")}) ;;`)
@@ -248,7 +250,7 @@ const generateFunction = (
     lines.push(`      --) _end_of_options=1 ;;`)
     for (const flag of descriptor.flags) {
       const forms = flagNamesForWordlist(flag)
-      if (flag.type._tag === "Boolean") {
+      if (!takesSeparateValue(flag)) {
         lines.push(`      ${forms.join("|")}) ;;`)
       } else {
         lines.push(`      ${forms.join("|")}) _skip_next=1 ;;`)

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

@@ -95,7 +95,9 @@ export const fromCommand = (
         name: single.name,
         aliases: single.aliases,
         description: Option.getOrUndefined(single.description),
-        type: toFlagType(single as Param.Single<"flag", unknown>)
+        type: toFlagType(single as Param.Single<"flag", unknown>),
+        optionalValue: single.optionalValue !== undefined,
+        negation: single.negation
       })
     }
   }
@@ -139,3 +141,20 @@ export const fromCommand = (
     subcommands
   }
 }
+
+/**
+ * Whether the flag reads its value from the next word.
+ *
+ * @internal
+ */
+export const takesSeparateValue = (flag: Completions.FlagDescriptor): boolean =>
+  flag.type._tag !== "Boolean" && flag.optionalValue !== true
+
+/**
+ * Long name that sets a boolean flag to `false`, or `undefined` when the flag
+ * has no negated form.
+ *
+ * @internal
+ */
+export const negatedName = (flag: Completions.FlagDescriptor): string | undefined =>
+  flag.type._tag !== "Boolean" || flag.negation === false ? undefined : flag.negation ?? `no-${flag.name}`

package/src/cli/internal/completions/fish.ts

@@ -7,6 +7,7 @@
  * @internal
  */
 import type * as Completions from "../../Completions.ts"
+import { negatedName, takesSeparateValue } from "./descriptor.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -61,8 +62,9 @@ const flagContainsOptCondition = (flag: Completions.FlagDescriptor): string => {
       optArgs.push(alias)
     }
   }
-  if (flag.type._tag === "Boolean") {
-    optArgs.push(`no-${flag.name}`)
+  const negation = negatedName(flag)
+  if (negation !== undefined) {
+    optArgs.push(negation)
   }
   return `not __fish_contains_opt ${optArgs.join(" ")}`
 }
@@ -88,7 +90,7 @@ const flagCompletionArgs = (flag: Completions.FlagDescriptor): Array<string> =>
   if (flag.description) {
     args.push(`-d '${escapeFishString(flag.description)}'`)
   }
-  const valueArgs = flagValueArgs(flag.type)
+  const valueArgs = takesSeparateValue(flag) ? flagValueArgs(flag.type) : undefined
   if (valueArgs) {
     args.push(valueArgs)
   }
@@ -159,8 +161,7 @@ const generateCompletions = (
 
   // Flag completions
   for (const flag of descriptor.flags) {
-    const isBoolean = flag.type._tag === "Boolean"
-    const dedup = isBoolean ? flagContainsOptCondition(flag) : valueFlagDedupCondition(flag)
+    const dedup = takesSeparateValue(flag) ? valueFlagDedupCondition(flag) : flagContainsOptCondition(flag)
     const flagCondition = condition ? `${condition}; and ${dedup}` : dedup
     const flagCondArg = flagCondition ? `-n '${flagCondition}'` : ``
 
@@ -170,10 +171,11 @@ const generateCompletions = (
     lines.push(parts.join(" "))
 
     // Boolean negation
-    if (isBoolean) {
+    const negation = negatedName(flag)
+    if (negation !== undefined) {
       const negParts = [`complete -c ${executableName}`]
       if (flagCondArg) negParts.push(flagCondArg)
-      negParts.push(`-l no-${flag.name}`)
+      negParts.push(`-l ${negation}`)
       if (flag.description) {
         negParts.push(`-d '${escapeFishString(`Disable ${flag.name}`)}'`)
       }
@@ -192,7 +194,7 @@ const generateCompletions = (
 
     for (const flag of descriptor.flags) {
       const bareCondition = `${bareBase}; and ${flagContainsOptCondition(flag)}`
-      const isBoolean = flag.type._tag === "Boolean"
+      const negation = negatedName(flag)
 
       const parts = [`complete -c ${executableName}`]
       parts.push(`-n '${bareCondition}'`)
@@ -202,10 +204,10 @@ const generateCompletions = (
       }
       lines.push(parts.join(" "))
 
-      if (isBoolean) {
+      if (negation !== undefined) {
         const negParts = [`complete -c ${executableName}`]
         negParts.push(`-n '${bareCondition}'`)
-        negParts.push(`-f -a '--no-${flag.name}'`)
+        negParts.push(`-f -a '--${negation}'`)
         if (flag.description) {
           negParts.push(`-d '${escapeFishString(`Disable ${flag.name}`)}'`)
         }