effect 4.0.0-beta.103 → 4.0.0-beta.104

package/src/unstable/cli/Param.ts

@@ -12,7 +12,7 @@
  */
 import * as Config from "../../Config.ts"
 import * as Effect from "../../Effect.ts"
-import { dual, identity } from "../../Function.ts"
+import { dual, identity, type LazyArg } from "../../Function.ts"
 import * as Option from "../../Option.ts"
 import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
@@ -226,7 +226,11 @@ export interface Transform<Kind extends ParamKind, in out A, out B> extends Para
   readonly _tag: "Transform"
   readonly kind: Kind
   readonly param: Param<Kind, A>
-  readonly f: (parse: Parse<A>) => Parse<B>
+  readonly alternatives: ReadonlyArray<LazyArg<Param<Kind, unknown>>>
+  readonly f: (
+    parse: Parse<A>,
+    alternatives: ReadonlyArray<LazyArg<Parse<unknown>>>
+  ) => Parse<B>
 }
 
 /**
@@ -1209,15 +1213,22 @@ export const map: {
 
 const transform = <Kind extends ParamKind, A, B>(
   self: Param<Kind, A>,
-  f: (parse: Parse<A>) => Parse<B>
-) =>
-  Object.assign(Object.create(Proto), {
+  f: (
+    parse: Parse<A>,
+    alternatives: ReadonlyArray<LazyArg<Parse<unknown>>>
+  ) => Parse<B>,
+  alternatives: ReadonlyArray<LazyArg<Param<Kind, unknown>>> = []
+): Transform<Kind, A, B> => {
+  const alternativeParsers = alternatives.map((alternative) => () => alternative().parse)
+  return Object.assign(Object.create(Proto), {
     _tag: "Transform",
     kind: self.kind,
     param: self,
+    alternatives,
     f,
-    parse: f(self.parse)
+    parse: f(self.parse, alternativeParsers)
   })
+}
 
 /**
  * Transforms the parsed value of an option using an effectful mapping function.
@@ -2719,7 +2730,7 @@ export const orElse: {
    * @category combinators
    * @since 4.0.0
    */
-  <B, Kind extends ParamKind>(orElse: (error: CliError.CliError) => Param<Kind, B>): <A>(self: Param<Kind, A>) => Param<Kind, A | B>
+  <B, Kind extends ParamKind>(orElse: LazyArg<Param<Kind, B>>): <A>(self: Param<Kind, A>) => Param<Kind, A | B>
   /**
    * Provides a fallback param to use if this param fails to parse.
    *
@@ -2737,14 +2748,16 @@ export const orElse: {
    * @category combinators
    * @since 4.0.0
    */
-  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: (error: CliError.CliError) => Param<Kind, B>): Param<Kind, A | B>
+  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: LazyArg<Param<Kind, B>>): Param<Kind, A | B>
 } = dual(2, <Kind extends ParamKind, A, B>(
   self: Param<Kind, A>,
-  orElse: (error: CliError.CliError) => Param<Kind, B>
+  orElse: LazyArg<Param<Kind, B>>
 ) =>
   transform(
     self,
-    (parse: Parse<A>): Parse<A | B> => (args: ParsedArgs) => Effect.catch(parse(args), (err) => orElse(err).parse(args))
+    (parse: Parse<A>, alternatives): Parse<A | B> => (args: ParsedArgs) =>
+      Effect.catch(parse(args), () => (alternatives[0]!() as Parse<B>)(args)),
+    [orElse]
   ))
 
 /**
@@ -2796,7 +2809,7 @@ export const orElseResult: {
    * @category combinators
    * @since 4.0.0
    */
-  <Kind extends ParamKind, B>(orElse: (error: CliError.CliError) => Param<Kind, B>): <A>(self: Param<Kind, A>) => Param<Kind, Result.Result<A, B>>
+  <Kind extends ParamKind, B>(orElse: LazyArg<Param<Kind, B>>): <A>(self: Param<Kind, A>) => Param<Kind, Result.Result<A, B>>
   /**
    * Provides a fallback param and returns a `Result` indicating which param
    * succeeded.
@@ -2821,22 +2834,23 @@ export const orElseResult: {
    * @category combinators
    * @since 4.0.0
    */
-  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: (error: CliError.CliError) => Param<Kind, B>): Param<Kind, Result.Result<A, B>>
+  <Kind extends ParamKind, A, B>(self: Param<Kind, A>, orElse: LazyArg<Param<Kind, B>>): Param<Kind, Result.Result<A, B>>
 } = dual(2, <Kind extends ParamKind, A, B>(
   self: Param<Kind, A>,
-  orElse: (error: CliError.CliError) => Param<Kind, B>
+  orElse: LazyArg<Param<Kind, B>>
 ) => {
   return transform(
     self,
-    (parse: Parse<A>): Parse<Result.Result<A, B>> => (args: ParsedArgs) =>
+    (parse: Parse<A>, alternatives): Parse<Result.Result<A, B>> => (args: ParsedArgs) =>
       Effect.catch(
         Effect.map(parse(args), ([leftover, value]) => [leftover, Result.succeed(value)] as const),
-        (err) =>
+        () =>
           Effect.map(
-            orElse(err).parse(args),
+            (alternatives[0]!() as Parse<B>)(args),
             ([leftover, value]) => [leftover, Result.fail(value)] as const
           )
-      )
+      ),
+    [orElse]
   )
 })
 
@@ -3053,7 +3067,12 @@ const transformSingle = <Kind extends ParamKind, A>(
   return matchParam(param, {
     Single: (single) => f(single),
     Map: (mapped) => map(transformSingle(mapped.param, f), mapped.f),
-    Transform: (mapped) => transform(transformSingle(mapped.param, f), mapped.f),
+    Transform: (mapped) =>
+      transform(
+        transformSingle(mapped.param, f),
+        mapped.f,
+        mapped.alternatives.map((alternative) => () => transformSingle(alternative(), f))
+      ),
     Optional: (p) => optional(transformSingle(p.param, f)) as Param<Kind, A>,
     Variadic: (p) =>
       variadic(transformSingle(p.param, f), {
@@ -3075,7 +3094,10 @@ export const extractSingleParams = <Kind extends ParamKind, A>(
   return matchParam(param, {
     Single: (single) => [single as Single<Kind, unknown>],
     Map: (mapped) => extractSingleParams(mapped.param),
-    Transform: (mapped) => extractSingleParams(mapped.param),
+    Transform: (mapped) => [
+      ...extractSingleParams(mapped.param),
+      ...mapped.alternatives.flatMap((alternative) => extractSingleParams(alternative()))
+    ],
     Optional: (optional) => extractSingleParams(optional.param),
     Variadic: (variadic) => extractSingleParams(variadic.param)
   })

package/src/unstable/cli/Primitive.ts

@@ -10,9 +10,6 @@
  *
  * @since 4.0.0
  */
-import * as Ini from "ini"
-import * as Toml from "toml"
-import * as Yaml from "yaml"
 import * as Config from "../../Config.ts"
 import * as Effect from "../../Effect.ts"
 import * as FileSystem from "../../FileSystem.ts"
@@ -24,6 +21,9 @@ import * as Schema from "../../Schema.ts"
 import type { Formatter } from "../../SchemaIssue.ts"
 import type * as Struct from "../../Struct.ts"
 import type { Covariant } from "../../Types.ts"
+import * as Ini from "../encoding/Ini.ts"
+import * as Toml from "../encoding/Toml.ts"
+import * as Yaml from "../encoding/Yaml.ts"
 import type { Environment } from "./Command.ts"
 
 const TypeId = "~effect/cli/Primitive"
@@ -479,8 +479,8 @@ export type PathType = "file" | "directory" | "either"
 export const path = (
   pathType: PathType,
   mustExist?: boolean
-): Primitive<string> =>
-  makePrimitive(
+): Primitive<string> => {
+  const primitive = makePrimitive(
     "Path",
     Effect.fnUntraced(function*(value) {
       const fs = yield* FileSystem.FileSystem
@@ -518,6 +518,8 @@ export const path = (
       return absolutePath
     })
   )
+  return Object.assign(primitive, { pathType })
+}
 
 /**
  * Creates a primitive that wraps string input in `Redacted`.
@@ -984,3 +986,7 @@ export const getTypeName = <A>(primitive: Primitive<A>): string => {
 /** @internal */
 export const getChoiceKeys = (primitive: Primitive<unknown>): ReadonlyArray<string> | undefined =>
   primitive._tag === "Choice" ? (primitive as any).choiceKeys : undefined
+
+/** @internal */
+export const getPathType = (primitive: Primitive<unknown>): PathType | undefined =>
+  primitive._tag === "Path" ? (primitive as any).pathType : undefined

package/src/unstable/cli/Prompt.ts

@@ -693,10 +693,13 @@ export const all: <
   if (arguments.length === 1) {
     if (isPrompt(arguments[0])) {
       return map(arguments[0], (x) => [x]) as any
-    } else if (Array.isArray(arguments[0])) {
-      return allTupled(arguments[0]) as any
+    } else if (Predicate.isIterable(arguments[0])) {
+      return allTupled(Arr.fromIterable(arguments[0] as Iterable<Prompt<any>>)) as any
     } else {
       const entries = Object.entries(arguments[0] as Readonly<{ [K: string]: Prompt<any> }>)
+      if (entries.length === 0) {
+        return succeed({}) as any
+      }
       let result = map(entries[0][1], (value) => ({ [entries[0][0]]: value }))
       if (entries.length === 1) {
         return result as any
@@ -1274,7 +1277,7 @@ export const multiSelect = <const A>(
   const initialSelected = new Set<number>()
   for (let i = 0; i < opts.choices.length; i++) {
     const choice = opts.choices[i] as SelectChoice<A>
-    if (choice.selected === true) {
+    if (choice.selected === true && !choice.disabled) {
       initialSelected.add(i)
     }
   }
@@ -2057,6 +2060,9 @@ class Day extends DatePart {
   }
 
   private ordinalIndicator(day: number): string {
+    if (day >= 11 && day <= 13) {
+      return "th"
+    }
     switch (day % 10) {
       case 1:
         return "st"
@@ -2115,7 +2121,7 @@ class Year extends DatePart {
   override toString() {
     const year = `${this.date.getFullYear()}`.padStart(4, "0")
     return this.token.length === 2
-      ? year.substring(-2)
+      ? year.slice(-2)
       : year
   }
 }
@@ -2132,7 +2138,7 @@ class Meridiem extends DatePart {
   setValue(_value: string): void {}
 
   override toString() {
-    const meridiem = this.date.getHours() > 12 ? "pm" : "am"
+    const meridiem = this.date.getHours() >= 12 ? "pm" : "am"
     return /A/.test(this.token)
       ? meridiem.toUpperCase()
       : meridiem;
@@ -2619,9 +2625,9 @@ const renderMultiSelectChoices = <A>(
   renderOptions?: RenderOptions | undefined
 ) => {
   const choices = options.choices
-  const totalChoices = choices.length
-  const selectedCount = state.selectedIndices.size
-  const allSelected = selectedCount === totalChoices
+  const selectableCount = choices.filter((choice) => !choice.disabled).length
+  const selectedCount = Array.from(state.selectedIndices).filter((index) => !choices[index].disabled).length
+  const allSelected = selectedCount === selectableCount
 
   const selectAllText = allSelected
     ? options?.selectNone ?? "Select None"
@@ -2657,8 +2663,9 @@ const renderMultiSelectChoices = <A>(
       const annotatedCheckbox = isHighlighted && renderOptions?.plain !== true
         ? Ansi.annotate(checkbox, Ansi.cyanBright)
         : checkbox
-      const title = renderMultiSelectTitle(choice.title, isHighlighted, renderOptions)
-      const description = renderChoiceDescription(choice as SelectChoice<A>, isHighlighted, renderOptions)
+      const selectChoice = choice as SelectChoice<A>
+      const title = renderChoiceTitle(selectChoice, isHighlighted, renderOptions)
+      const description = renderChoiceDescription(selectChoice, isHighlighted, renderOptions)
       documents.push(prefix + " " + annotatedCheckbox + " " + title + " " + description)
     }
   }
@@ -2707,16 +2714,20 @@ const processSpace = <A>(
 ) => {
   const selectedIndices = new Set(state.selectedIndices)
   if (state.index === 0) {
-    if (state.selectedIndices.size === options.choices.length) {
+    const selectableCount = options.choices.filter((choice) => !choice.disabled).length
+    const selectedCount = Array.from(state.selectedIndices).filter((index) => !options.choices[index].disabled).length
+    if (selectedCount === selectableCount) {
       selectedIndices.clear()
     } else {
       for (let i = 0; i < options.choices.length; i++) {
-        selectedIndices.add(i)
+        if (!options.choices[i].disabled) {
+          selectedIndices.add(i)
+        }
       }
     }
   } else if (state.index === 1) {
     for (let i = 0; i < options.choices.length; i++) {
-      if (state.selectedIndices.has(i)) {
+      if (options.choices[i].disabled || state.selectedIndices.has(i)) {
         selectedIndices.delete(i)
       } else {
         selectedIndices.add(i)
@@ -2724,7 +2735,9 @@ const processSpace = <A>(
     }
   } else {
     const choiceIndex = state.index - metaOptionsCount
-    if (selectedIndices.has(choiceIndex)) {
+    if (options.choices[choiceIndex].disabled) {
+      return Effect.succeed(Action.Beep())
+    } else if (selectedIndices.has(choiceIndex)) {
       selectedIndices.delete(choiceIndex)
     } else {
       selectedIndices.add(choiceIndex)
@@ -2764,7 +2777,8 @@ const handleMultiSelectProcess = <A>(options: SelectOptionsReq<A> & MultiSelectO
       }
       case "enter":
       case "return": {
-        const selectedCount = state.selectedIndices.size
+        const selectedIndices = Array.from(state.selectedIndices).filter((index) => !options.choices[index].disabled)
+        const selectedCount = selectedIndices.length
         if (options.min !== undefined && selectedCount < options.min) {
           return Effect.succeed(
             Action.NextFrame({ state: { ...state, error: Option.some(`At least ${options.min} are required`) } })
@@ -2775,9 +2789,7 @@ const handleMultiSelectProcess = <A>(options: SelectOptionsReq<A> & MultiSelectO
             Action.NextFrame({ state: { ...state, error: Option.some(`At most ${options.max} choices are allowed`) } })
           )
         }
-        const selectedValues = Array.from(state.selectedIndices).sort(EffectNumber.Order).map((index) =>
-          options.choices[index].value
-        )
+        const selectedValues = selectedIndices.sort(EffectNumber.Order).map((index) => options.choices[index].value)
         return Effect.succeed(Action.Submit({ value: selectedValues }))
       }
       default: {
@@ -2933,10 +2945,14 @@ const defaultFloatProcessor = (input: string, state: NumberState) => {
     return Effect.succeed(Action.NextFrame({
       state: {
         ...state,
-        value: input === "." ? `${parsed}.` : `${parsed}`,
+        value: input === "."
+          ? `${parsed}.`
+          : state.value.includes(".") && /^\d$/.test(input)
+          ? state.value + input
+          : `${parsed}`,
         error: Option.none()
       }
-    }))
+    }));
   }
 }
 

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

@@ -79,9 +79,9 @@ export const combine = (...styles: Array<string>): Array<string> => styles
 /** @internal */
 export const cursorTo = (column: number, row?: number): string => {
   if (row === undefined) {
-    return `\x1b${Math.max(column + 1, 0)} G`
+    return `${ESC}${Math.max(column + 1, 0)}G`
   }
-  return `\x1b${row + 1}${SEP}${Math.max(column + 1, 0)} H`
+  return `${ESC}${row + 1}${SEP}${Math.max(column + 1, 0)}H`
 }
 
 /** @internal */

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

@@ -98,7 +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 unlisted?: boolean | undefined
   readonly examples?: ReadonlyArray<Command.Example> | undefined
   readonly subcommands?: ReadonlyArray<SubcommandGroup> | undefined
   readonly parse?: ((input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>) | undefined
@@ -139,7 +139,8 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
           name: single.name,
           type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
           description: single.description,
-          required: !metadata.isOptional,
+          required: !metadata.isOptional &&
+            (!metadata.isVariadic || Option.exists(metadata.variadicMin, (min) => min > 0)),
           variadic: metadata.isVariadic
         })
       }
@@ -147,8 +148,8 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
 
     let usage = commandPath.length > 0 ? commandPath.join(" ") : options.name
     // 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))) {
+    // exists; an all-unlisted subcommand tree should look like a leaf command.
+    if (subcommands.some((group) => group.commands.some((c) => !c.unlisted))) {
       usage += " <subcommand>"
     }
     usage += " [flags]"
@@ -159,21 +160,22 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
 
     for (const option of config.flags) {
       const singles = Param.extractSingleParams(option)
+      const metadata = Param.getParamMetadata(option)
       for (const single of singles) {
         // Hidden flags still parse on the command line but are omitted from
         // generated --help output.
         if (single.hidden) continue
-        flags.push(toFlagDoc(single))
+        flags.push(toFlagDoc(single, metadata))
       }
     }
 
     const subcommandDocs: Array<SubcommandGroupDoc> = []
 
     for (const group of subcommands) {
-      // Hidden subcommands still parse on the command line but are omitted
+      // Unlisted 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)
+      const visible = group.commands.filter((c) => !c.unlisted)
       if (visible.length === 0) continue
       subcommandDocs.push({
         group: group.group,
@@ -206,7 +208,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
     annotations,
     globalFlags,
     subcommands,
-    hidden: options.hidden ?? false,
+    unlisted: options.unlisted ?? false,
     config,
     contextConfig,
     service,
@@ -233,14 +235,17 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
 /**
  * Converts a single flag param into a FlagDoc for help display.
  */
-export const toFlagDoc = (single: Param.Single<typeof Param.flagKind, unknown>): FlagDoc => {
+export const toFlagDoc = (
+  single: Param.Single<typeof Param.flagKind, unknown>,
+  metadata: ReturnType<typeof Param.getParamMetadata>
+): FlagDoc => {
   const formattedAliases = single.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`)
   return {
     name: single.name,
     aliases: formattedAliases,
     type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
     description: appendChoiceKeys(single.description, Primitive.getChoiceKeys(single.primitiveType)),
-    required: single.primitiveType._tag !== "Boolean"
+    required: single.primitiveType._tag !== "Boolean" && !metadata.isOptional
   }
 }
 

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

@@ -100,7 +100,8 @@ const generateFunction = (
 
   lines.push(`${funcName}()`)
   lines.push(`{`)
-  lines.push(`  local cur prev words cword`)
+  lines.push(`  local cur prev words cword i`)
+  lines.push(parentPath.length === 0 ? `  local _command_index=0` : `  local _command_index="$1"`)
   lines.push(`  _init_completion || return`)
   lines.push(``)
 
@@ -129,13 +130,23 @@ const generateFunction = (
   // Subcommand dispatch
   if (descriptor.subcommands.length > 0) {
     lines.push(`  # Subcommand dispatch`)
-    lines.push(`  local i cmd`)
-    lines.push(`  for ((i = 1; i < cword; i++)); do`)
+    lines.push(`  local cmd _skip_next=0`)
+    lines.push(`  for ((i = _command_index + 1; i < cword; i++)); do`)
+    lines.push(`    if (( _skip_next )); then`)
+    lines.push(`      _skip_next=0`)
+    lines.push(`      continue`)
+    lines.push(`    fi`)
     lines.push(`    case "\${words[i]}" in`)
+    for (const flag of descriptor.flags) {
+      if (flag.type._tag === "Boolean") continue
+      const forms = flagNamesForWordlist(flag)
+      lines.push(`      ${forms.join("|")}) _skip_next=1 ;;`)
+      lines.push(`      ${forms.map((form) => `${form}=*`).join("|")}) ;;`)
+    }
     for (const sub of descriptor.subcommands) {
       const subFuncName = `_${[...currentPath, sub.name].map(sanitizeFunctionName).join("_")}`
       lines.push(`      ${sub.name})`)
-      lines.push(`        ${subFuncName}`)
+      lines.push(`        ${subFuncName} "$i"`)
       lines.push(`        return`)
       lines.push(`        ;;`)
     }
@@ -159,13 +170,52 @@ const generateFunction = (
   }
 
   // Positional argument completion
-  const argsWithCompletions = descriptor.arguments.filter((a) => argCompletion(a.type) !== undefined)
+  const argsWithCompletions = descriptor.arguments.flatMap((argument, index) => {
+    const completion = argCompletion(argument.type)
+    return completion === undefined ? [] : [{ argument, completion, index }]
+  })
   if (argsWithCompletions.length > 0) {
     lines.push(`  # Positional argument completions`)
-    for (const arg of argsWithCompletions) {
-      const comp = argCompletion(arg.type)!
-      lines.push(`  ${comp}`)
-      lines.push(`  return`)
+    lines.push(`  local _position=0 _skip_next=0 _end_of_options=0`)
+    lines.push(`  for ((i = _command_index + 1; i < cword; i++)); do`)
+    lines.push(`    if (( _skip_next )); then`)
+    lines.push(`      _skip_next=0`)
+    lines.push(`      continue`)
+    lines.push(`    fi`)
+    lines.push(`    if (( _end_of_options )); then`)
+    lines.push(`      ((_position += 1))`)
+    lines.push(`      continue`)
+    lines.push(`    fi`)
+    lines.push(`    case "\${words[i]}" in`)
+    lines.push(`      --) _end_of_options=1 ;;`)
+    for (const flag of descriptor.flags) {
+      const forms = flagNamesForWordlist(flag)
+      if (flag.type._tag === "Boolean") {
+        lines.push(`      ${forms.join("|")}) ;;`)
+      } else {
+        lines.push(`      ${forms.join("|")}) _skip_next=1 ;;`)
+        lines.push(`      ${forms.map((form) => `${form}=*`).join("|")}) ;;`)
+      }
+    }
+    lines.push(`      -*) ;;`)
+    lines.push(`      *) ((_position += 1)) ;;`)
+    lines.push(`    esac`)
+    lines.push(`  done`)
+    lines.push(`  case "$_position" in`)
+    for (const { argument, completion, index } of argsWithCompletions) {
+      if (argument.variadic) continue
+      lines.push(`    ${index})`)
+      lines.push(`      ${completion}`)
+      lines.push(`      return`)
+      lines.push(`      ;;`)
+    }
+    lines.push(`  esac`)
+    const variadic = argsWithCompletions.find(({ argument }) => argument.variadic)
+    if (variadic !== undefined) {
+      lines.push(`  if (( _position >= ${variadic.index} )); then`)
+      lines.push(`    ${variadic.completion}`)
+      lines.push(`    return`)
+      lines.push(`  fi`)
     }
   } else if (descriptor.subcommands.length > 0) {
     const subNames = descriptor.subcommands.map((s) => s.name)

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

@@ -30,15 +30,12 @@ const toFlagType = (single: Param.Single<"flag", unknown>): Completions.FlagType
       const keys = Primitive.getChoiceKeys(single.primitiveType)
       return { _tag: "Choice", values: keys ?? [] }
     }
-    case "Path": {
-      const typeName = single.typeName
-      const pathType: "file" | "directory" | "either" = typeName === "file"
-        ? "file"
-        : typeName === "directory"
-        ? "directory"
-        : "either"
-      return { _tag: "Path", pathType }
-    }
+    case "Path":
+      return { _tag: "Path", pathType: Primitive.getPathType(single.primitiveType) ?? "either" }
+    case "FileText":
+    case "FileParse":
+    case "FileSchema":
+      return { _tag: "Path", pathType: "file" }
     default:
       return { _tag: "String" }
   }
@@ -57,15 +54,12 @@ const toArgumentType = (single: Param.Single<"argument", unknown>): Completions.
       const keys = Primitive.getChoiceKeys(single.primitiveType)
       return { _tag: "Choice", values: keys ?? [] }
     }
-    case "Path": {
-      const typeName = single.typeName
-      const pathType: "file" | "directory" | "either" = typeName === "file"
-        ? "file"
-        : typeName === "directory"
-        ? "directory"
-        : "either"
-      return { _tag: "Path", pathType }
-    }
+    case "Path":
+      return { _tag: "Path", pathType: Primitive.getPathType(single.primitiveType) ?? "either" }
+    case "FileText":
+    case "FileParse":
+    case "FileSchema":
+      return { _tag: "Path", pathType: "file" }
     default:
       return { _tag: "String" }
   }
@@ -116,9 +110,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
+      // Omit unlisted subcommands from completion scripts so tab-completion in
       // the shell does not advertise commands that are absent from --help.
-      if (subcommand.hidden) continue
+      if (subcommand.unlisted) continue
       subcommands.push(fromCommand(subcommand))
     }
   }

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

@@ -18,7 +18,7 @@ const escapeFishString = (s: string): string => s.replace(/'/g, "\\'")
  * Build a Fish condition that checks the current subcommand context.
  *
  * For root-level completions with subcommands: `__fish_use_subcommand`
- * For nested commands: verify the parent subcommand is active AND none of its
+ * For nested commands: verify the full parent path is active AND none of its
  * child subcommands have been entered yet.
  */
 const subcommandCondition = (
@@ -31,14 +31,12 @@ const subcommandCondition = (
     }
     return ``
   }
-  const parent = parentPath[parentPath.length - 1]
+  const parentCondition = parentPath.map((parent) => `__fish_seen_subcommand_from ${parent}`).join("; and ")
   if (childSubcommandNames.length > 0) {
-    // Show only when parent is active but no child subcommand has been entered
-    return `__fish_seen_subcommand_from ${parent}; and not __fish_seen_subcommand_from ${
-      childSubcommandNames.join(" ")
-    }`
+    // Show only when the parent path is active but no child subcommand has been entered
+    return `${parentCondition}; and not __fish_seen_subcommand_from ${childSubcommandNames.join(" ")}`
   }
-  return `__fish_seen_subcommand_from ${parent}`
+  return parentCondition
 }
 
 /**

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

@@ -111,6 +111,7 @@ const getSharedFlagsForCommandPath = (
     const ancestorImpl = toImpl(ancestor)
     for (const flag of ancestorImpl.contextConfig.flags) {
       const singles = Param.extractSingleParams(flag)
+      const metadata = Param.getParamMetadata(flag)
       for (const single of singles) {
         if (seen.has(single.name)) {
           continue
@@ -122,7 +123,7 @@ const getSharedFlagsForCommandPath = (
           continue
         }
         seen.add(single.name)
-        sharedFlags.push(toFlagDoc(single))
+        sharedFlags.push(toFlagDoc(single, metadata))
       }
     }
   }
@@ -165,13 +166,14 @@ export const getHelpForCommandPath = <Name extends string, Input, E, R, ContextI
     const globalFlagDocs: Array<FlagDoc> = []
     for (const flag of flags) {
       const singles = Param.extractSingleParams(flag.flag)
+      const metadata = Param.getParamMetadata(flag.flag)
       for (const single of singles) {
         // Same rule as command-local flags: hidden globals are still parsed
         // and still trigger their handlers, they just don't appear under
         // "GLOBAL FLAGS" in --help.
         if (single.hidden) continue
         globalFlagDocs.push({
-          ...toFlagDoc(single),
+          ...toFlagDoc(single, metadata),
           required: false
         })
       }

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

@@ -826,12 +826,12 @@ const resolveFirstValue = (
   // Not a subcommand. Check if this looks like a typo.
   const expectsArgs = toImpl(command).config.arguments.length > 0
   if (!expectsArgs && subIndex.size > 0) {
-    // Exclude hidden subcommands so a typo cannot reveal a subcommand name
-    // that was intentionally kept out of --help. Hidden commands still
+    // Exclude unlisted subcommands so a typo cannot reveal a subcommand name
+    // that was intentionally kept out of --help. Unlisted commands still
     // resolve via subIndex when invoked by exact name.
     const visibleKeys: Array<string> = []
     for (const [key, sub] of subIndex) {
-      if (!sub.hidden) visibleKeys.push(key)
+      if (!sub.unlisted) visibleKeys.push(key)
     }
     const suggestions = suggest(value, visibleKeys)
     state.errors.push(