effect 4.0.5 → 4.0.6

package/src/cli/Param.ts

@@ -217,6 +217,11 @@ export interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
    * 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
 }
 
 /**
@@ -367,6 +372,7 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
   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
@@ -2760,6 +2766,122 @@ export const withOptionalValue: {
       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.
  *

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

@@ -7,7 +7,7 @@
  * @internal
  */
 import type * as Completions from "../../Completions.ts"
-import { takesSeparateValue } from "./descriptor.ts"
+import { negatedName, takesSeparateValue } from "./descriptor.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -22,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
 }

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

@@ -96,7 +96,8 @@ export const fromCommand = (
         aliases: single.aliases,
         description: Option.getOrUndefined(single.description),
         type: toFlagType(single as Param.Single<"flag", unknown>),
-        optionalValue: single.optionalValue !== undefined
+        optionalValue: single.optionalValue !== undefined,
+        negation: single.negation
       })
     }
   }
@@ -148,3 +149,12 @@ export const fromCommand = (
  */
 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,7 +7,7 @@
  * @internal
  */
 import type * as Completions from "../../Completions.ts"
-import { takesSeparateValue } from "./descriptor.ts"
+import { negatedName, takesSeparateValue } from "./descriptor.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -62,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(" ")}`
 }
@@ -170,10 +171,11 @@ const generateCompletions = (
     lines.push(parts.join(" "))
 
     // Boolean negation
-    if (flag.type._tag === "Boolean") {
+    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}`)}'`)
         }

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

@@ -8,6 +8,7 @@
  * @internal
  */
 import type * as Completions from "../../Completions.ts"
+import { negatedName } from "./descriptor.ts"
 
 /**
  * Encode non-ASCII and control characters as `[char]` code units. Windows
@@ -46,12 +47,15 @@ const valueFields = (type: Completions.FlagType | Completions.ArgumentType): str
   `values = ${psArray(type._tag === "Choice" ? type.values : [])}; ` +
   `pathType = ${type._tag === "Path" ? quotePs(type.pathType) : "$null"}`
 
-const flagEntry = (flag: Completions.FlagDescriptor): string =>
-  `@{ name = ${quotePs(flag.name)}; forms = ${psArray(flagForms(flag))}; ` +
-  `takesValue = $${flag.type._tag !== "Boolean"}; ` +
-  (flag.optionalValue === true ? `optionalValue = $true; ` : "") +
-  `${valueFields(flag.type)}; ` +
-  `description = ${psOptional(flag.description)} }`
+const flagEntry = (flag: Completions.FlagDescriptor): string => {
+  const negation = negatedName(flag)
+  return `@{ name = ${quotePs(flag.name)}; forms = ${psArray(flagForms(flag))}; ` +
+    `takesValue = $${flag.type._tag !== "Boolean"}; ` +
+    (negation === undefined ? "" : `negation = ${quotePs(`--${negation}`)}; `) +
+    (flag.optionalValue === true ? `optionalValue = $true; ` : "") +
+    `${valueFields(flag.type)}; ` +
+    `description = ${psOptional(flag.description)} }`
+}
 
 const argumentEntry = (argument: Completions.ArgumentDescriptor): string =>
   `@{ name = ${quotePs(argument.name)}; variadic = $${argument.variadic}; ${valueFields(argument.type)}; ` +
@@ -154,10 +158,10 @@ const completer = (dataName: string): string =>
       foreach ($form in $flag.forms) {
         & $add $form 'ParameterName' $flag.description $typed ''
       }
-      if (-not $flag.takesValue) {
+      if ($flag.negation) {
         $tooltip = $null
         if ($flag.description) { $tooltip = 'Disable ' + $flag.name }
-        & $add ('--no-' + $flag.name) 'ParameterName' $tooltip $typed ''
+        & $add $flag.negation 'ParameterName' $tooltip $typed ''
       }
     }
   }
@@ -228,14 +232,19 @@ const completer = (dataName: string): string =>
       foreach ($form in $forms) {
         $pending = $null
         $flag = $lookup[$form]
-        if ($null -eq $flag) {
-          if ($form.StartsWith('--no-')) {
-            $name = $form.Substring(5)
-            $flag = $lookup['--' + $name]
-            if ($null -ne $flag -and -not $flag.takesValue -and $flag.name -ceq $name) { $used[$name] = $true }
+        # As in the CLI parser, a negation wins over an alias but not over a
+        # canonical name.
+        if ($null -eq $flag -or $form -cne ('--' + $flag.name)) {
+          $negated = $null
+          foreach ($candidate in $context.flags) {
+            if ($candidate.negation -ceq $form) { $negated = $candidate }
+          }
+          if ($null -ne $negated) {
+            $used[$negated.name] = $true
+            continue
           }
-          continue
         }
+        if ($null -eq $flag) { continue }
         $used[$flag.name] = $true
         # A flag with an optional value only takes a value attached with '='.
         if (-not $hasValue -and -not $flag.optionalValue) { $pending = $flag }

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

@@ -7,6 +7,7 @@
  * @internal
  */
 import type * as Completions from "../../Completions.ts"
+import { negatedName } from "./descriptor.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -22,15 +23,16 @@ const escapeZshChoice = (s: string): string => s.replace(/[^A-Za-z0-9_.,/@%+-]/g
 const sanitize = (s: string): string => s.replace(/[^a-zA-Z0-9_]/g, "_")
 
 /**
- * All forms of a flag (--name, -alias, --no-name) for the exclusion group.
+ * All forms of a flag (--name, -alias, negation) for the exclusion group.
  */
 const allForms = (flag: Completions.FlagDescriptor): Array<string> => {
   const forms: Array<string> = [`--${flag.name}`]
   for (const alias of flag.aliases) {
     forms.push(alias.length === 1 ? `-${alias}` : `--${alias}`)
   }
-  if (flag.type._tag === "Boolean") {
-    forms.push(`--no-${flag.name}`)
+  const negation = negatedName(flag)
+  if (negation !== undefined) {
+    forms.push(`--${negation}`)
   }
   return forms
 }
@@ -89,9 +91,10 @@ const flagSpecs = (flag: Completions.FlagDescriptor): Array<string> => {
   }
 
   // Boolean negation
-  if (flag.type._tag === "Boolean") {
+  const negation = negatedName(flag)
+  if (negation !== undefined) {
     const negDesc = flag.description ? `[${escapeZshExplanation(`Disable ${flag.name}`)}]` : ""
-    specs.push(`'${excl}--no-${flag.name}${negDesc}'`)
+    specs.push(`'${excl}--${negation}${negDesc}'`)
   }
 
   return specs

package/src/cli/internal/formatter.ts

@@ -0,0 +1,18 @@
+import * as Context from "../../Context.ts"
+import * as Effect from "../../Effect.ts"
+import * as CliOutput from "../CliOutput.ts"
+import * as TerminalCapabilities from "../TerminalCapabilities.ts"
+
+/**
+ * The formatter for built-in command output. An installed `CliOutput.Formatter`
+ * wins, otherwise the default formatter colors when `TerminalCapabilities`
+ * says it can.
+ *
+ * @internal
+ */
+export const resolveFormatter: Effect.Effect<CliOutput.Formatter> = Effect.contextWith((context) =>
+  Effect.succeed(
+    Context.getOrUndefined(context, CliOutput.Formatter) ??
+      CliOutput.defaultFormatter({ colors: Context.get(context, TerminalCapabilities.TerminalCapabilities).canColor })
+  )
+)

package/src/cli/internal/lexer.ts

@@ -58,8 +58,12 @@ const lexTokens = (args: ReadonlyArray<string>): ReadonlyArray<Token> => {
       const equalIndex = arg.indexOf("=")
       if (equalIndex !== -1) {
         const name = arg.slice(2, equalIndex)
-        const value = arg.slice(equalIndex + 1)
-        tokens.push({ _tag: "LongOption", name, raw: arg, value })
+        if (name === "") {
+          tokens.push({ _tag: "Value", value: arg })
+        } else {
+          const value = arg.slice(equalIndex + 1)
+          tokens.push({ _tag: "LongOption", name, raw: arg, value })
+        }
       } else {
         tokens.push({ _tag: "LongOption", name: arg.slice(2), raw: arg })
       }
@@ -67,9 +71,12 @@ const lexTokens = (args: ReadonlyArray<string>): ReadonlyArray<Token> => {
       const flags = arg.slice(1)
       const equalIndex = flags.indexOf("=")
       if (equalIndex !== -1) {
-        const flag = flags.slice(0, equalIndex)
-        const value = flags.slice(equalIndex + 1)
-        tokens.push({ _tag: "ShortOption", flag, raw: `-${flag}`, value })
+        const chars = Array.from(flags.slice(0, equalIndex))
+        const flag = chars.pop() ?? ""
+        for (const ch of chars) {
+          tokens.push({ _tag: "ShortOption", flag: ch, raw: `-${ch}` })
+        }
+        tokens.push({ _tag: "ShortOption", flag, raw: `-${flag}`, value: flags.slice(equalIndex + 1) })
       } else {
         for (const ch of flags) {
           tokens.push({ _tag: "ShortOption", flag: ch, raw: `-${ch}` })