effect 4.0.6 → 4.1.0

package/src/cli/GlobalFlag.ts

@@ -17,11 +17,10 @@ import * as Context from "../Context.ts"
 import * as Effect from "../Effect.ts"
 import type { LogLevel as LogLevelType } from "../LogLevel.ts"
 import * as Option from "../Option.ts"
+import * as CliOutput from "./CliOutput.ts"
 import type * as Command from "./Command.ts"
 import * as Completions_ from "./Completions.ts"
 import * as Flag from "./Flag.ts"
-import * as CommandDescriptor from "./internal/completions/descriptor.ts"
-import { resolveFormatter } from "./internal/formatter.ts"
 import * as HelpInternal from "./internal/help.ts"
 
 /* ========================================================================== */
@@ -169,9 +168,9 @@ export const Help: Action<boolean> = Action({
     Flag.withDefault(false)
   ),
   run: Effect.fnUntraced(function*(_, { builtIns, command, commandPath }) {
-    const formatter = yield* resolveFormatter
+    const presenter = yield* CliOutput.Presenter
     const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, builtIns)
-    yield* Console.log(formatter.formatHelpDoc(helpDoc))
+    yield* presenter.present({ _tag: "Help", reason: "Requested", commandPath, helpDoc })
   })
 })
 
@@ -193,8 +192,8 @@ export const Version: Action<boolean> = Action({
     Flag.withDefault(false)
   ),
   run: Effect.fnUntraced(function*(_, { command, version }) {
-    const formatter = yield* resolveFormatter
-    yield* Console.log(formatter.formatVersion(command.name, version))
+    const presenter = yield* CliOutput.Presenter
+    yield* presenter.present({ _tag: "Version", name: command.name, version })
   })
 })
 
@@ -249,7 +248,7 @@ export const Completions: Action<Option.Option<Completions_.Shell>> = Action({
   ),
   run: Effect.fnUntraced(function*(shell, { command }) {
     if (Option.isNone(shell)) return
-    const descriptor = CommandDescriptor.fromCommand(command)
+    const descriptor = Completions_.fromCommand(command)
     yield* Console.log(
       Completions_.generate(command.name, shell.value, descriptor)
     )

package/src/cli/HelpDoc.ts

@@ -82,10 +82,27 @@ export interface HelpDoc {
   readonly flags: ReadonlyArray<FlagDoc>
 
   /**
-   * Global flags available to all commands (e.g., --help, --version).
+   * Shared flags inherited from ancestor commands.
+   */
+  readonly inheritedFlags?: ReadonlyArray<FlagDoc>
+
+  /**
+   * Global flags active at this command, including built-ins (e.g., --help).
    */
   readonly globalFlags?: ReadonlyArray<FlagDoc>
 
+  /**
+   * Root-to-command path of the nearest ancestor (or this command) declaring
+   * global flags. Defaults to the root for built-ins.
+   */
+  readonly globalFlagsScope?: ReadonlyArray<string>
+
+  /**
+   * Command names from the root command to this command, e.g.
+   * `["myapp", "deploy"]`.
+   */
+  readonly commandPath?: ReadonlyArray<string>
+
   /**
    * Custom command annotations.
    */

package/src/cli/Param.ts

@@ -25,6 +25,7 @@ import * as CliError from "./CliError.ts"
 import type { Environment } from "./Command.ts"
 import * as Primitive from "./Primitive.ts"
 import * as Prompt from "./Prompt.ts"
+import * as TerminalCapabilities from "./TerminalCapabilities.ts"
 
 const TypeId = "~effect/cli/Param"
 
@@ -1299,6 +1300,7 @@ const transform = <Kind extends ParamKind, A, B>(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1355,6 +1357,7 @@ export const mapEffect: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1411,6 +1414,7 @@ export const mapEffect: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1484,6 +1488,7 @@ export const mapEffect: {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -1534,6 +1539,7 @@ export const mapTryCatch: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1584,6 +1590,7 @@ export const mapTryCatch: {
    *   Layer.succeed(Terminal.Terminal, Terminal.make({
    *     columns: Effect.succeed(80),
    *     rows: Effect.succeed(24),
+   *     size: Effect.die("unused"),
    *     readInput: Effect.die("unused"),
    *     readLine: Effect.die("unused"),
    *     display: () => Effect.void
@@ -1931,6 +1938,9 @@ export const withFallbackConfig: {
  *
  * This only handles missing options and missing arguments. Invalid values do not
  * prompt, and prompt cancellation re-fails with the original missing error.
+ * When `TerminalCapabilities.canPrompt` is `false`, the fallback is skipped
+ * entirely: no prompt is built or shown, and the original missing error is
+ * returned.
  *
  * @see {@link FallbackPrompt} for accepted fallback prompt forms
  * @see {@link withFallbackConfig} for loading a fallback from config
@@ -1958,6 +1968,9 @@ export const withFallbackPrompt: {
    *
    * This only handles missing options and missing arguments. Invalid values do not
    * prompt, and prompt cancellation re-fails with the original missing error.
+   * When `TerminalCapabilities.canPrompt` is `false`, the fallback is skipped
+   * entirely: no prompt is built or shown, and the original missing error is
+   * returned.
    *
    * @see {@link FallbackPrompt} for accepted fallback prompt forms
    * @see {@link withFallbackConfig} for loading a fallback from config
@@ -1985,6 +1998,9 @@ export const withFallbackPrompt: {
    *
    * This only handles missing options and missing arguments. Invalid values do not
    * prompt, and prompt cancellation re-fails with the original missing error.
+   * When `TerminalCapabilities.canPrompt` is `false`, the fallback is skipped
+   * entirely: no prompt is built or shown, and the original missing error is
+   * returned.
    *
    * @see {@link FallbackPrompt} for accepted fallback prompt forms
    * @see {@link withFallbackConfig} for loading a fallback from config
@@ -1999,11 +2015,16 @@ export const withFallbackPrompt: {
   self: Param<Kind, A>,
   prompt: FallbackPrompt<B>
 ): Param<Kind, A | B> => {
-  const runPrompt = (error: CliError.MissingOption | CliError.MissingArgument, args: ParsedArgs) =>
-    Effect.flatMap(Prompt.isPrompt(prompt) ? Effect.succeed(prompt) : prompt, Prompt.run).pipe(
-      Effect.map((value) => [args.arguments, value as A | B] as const),
-      Effect.catchTag("QuitError", () => Effect.fail(error))
-    )
+  const runPrompt = Effect.fnUntraced(function*(
+    error: CliError.MissingOption | CliError.MissingArgument,
+    args: ParsedArgs
+  ) {
+    const { canPrompt } = yield* TerminalCapabilities.TerminalCapabilities
+    if (!canPrompt) return yield* Effect.fail(error)
+    const built = Prompt.isPrompt(prompt) ? prompt : yield* prompt
+    const value = yield* Effect.catchTag(Prompt.run(built), "QuitError", () => Effect.fail(error))
+    return [args.arguments, value as A | B] as const
+  })
   return transform(
     self,
     (parse) => (args) =>
@@ -3191,7 +3212,15 @@ const parseFlag: <A>(
     return yield* new CliError.MissingOption({ option: name })
   }
 
-  // Parse the first value (later we can handle multiple)
+  if (providedValues.length > 1) {
+    return yield* new CliError.InvalidValue({
+      option: name,
+      value: `${providedValues.length} occurrences`,
+      expected: "at most 1 value",
+      kind: "flag"
+    })
+  }
+
   const arg = providedValues[0]
   const value = yield* Effect.mapError(
     primitiveType.parse(arg),

package/src/cli/Primitive.ts

@@ -20,6 +20,7 @@ import { format } from "../Formatter.ts"
 import { identity } from "../Function.ts"
 import * as Path_ from "../Path.ts"
 import * as Redacted_ from "../Redacted.ts"
+import * as Result from "../Result.ts"
 import * as Schema from "../Schema.ts"
 import type { Formatter } from "../SchemaIssue.ts"
 import type * as Struct from "../Struct.ts"
@@ -45,6 +46,7 @@ const TypeId = "~effect/cli/Primitive"
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -157,6 +159,7 @@ const makeSchemaPrimitive = <T>(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -203,6 +206,7 @@ export const Boolean: Primitive<boolean> = makeSchemaPrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -248,6 +252,7 @@ export const Finite: Primitive<number> = makeSchemaPrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -293,6 +298,7 @@ export const Int: Primitive<number> = makeSchemaPrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -337,6 +343,7 @@ export const Date: Primitive<globalThis.Date> = makeSchemaPrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -379,6 +386,7 @@ export const String: Primitive<string> = makePrimitive("String", (value) => Effe
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -470,6 +478,7 @@ export type PathType = "file" | "directory" | "either"
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -560,6 +569,7 @@ export const Path = (
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -608,6 +618,7 @@ export const Redacted: Primitive<Redacted_.Redacted<string>> = makePrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -686,7 +697,7 @@ export type FileParseOptions = {
 const fileParsers: Record<string, (content: string) => unknown> = {
   ini: (content: string) => Ini.parse(content),
   json: (content: string) => JSON.parse(content),
-  toml: (content: string) => Toml.parse(content),
+  toml: (content: string) => Result.getOrThrow(Toml.parse(content)),
   yml: (content: string) => Yaml.parse(content),
   yaml: (content: string) => Yaml.parse(content)
 }
@@ -718,6 +729,7 @@ const fileParsers: Record<string, (content: string) => unknown> = {
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -795,6 +807,7 @@ export type FileSchemaOptions = Struct.Simplify<
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -862,6 +875,7 @@ export const FileSchema = <A>(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void
@@ -923,6 +937,7 @@ export const KeyValuePair: Primitive<Record<string, string>> = makePrimitive(
  *   Layer.succeed(Terminal.Terminal, Terminal.make({
  *     columns: Effect.succeed(80),
  *     rows: Effect.succeed(24),
+ *     size: Effect.die("unused"),
  *     readInput: Effect.die("unused"),
  *     readLine: Effect.die("unused"),
  *     display: () => Effect.void

package/src/cli/Prompt.ts

@@ -791,6 +791,7 @@ export declare namespace All {
  * const terminal = Terminal.make({
  *   columns: Effect.succeed(80),
  *   rows: Effect.succeed(24),
+ *   size: Effect.die("unused"),
  *   readInput: Effect.succeed({} as never),
  *   readLine: Effect.die("unused"),
  *   display: () => Effect.void

package/src/cli/TerminalCapabilities.ts

@@ -5,7 +5,9 @@
  * 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`.
+ * output of `Command` follows `canColor`. Fallback prompts added with
+ * `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` only run when
+ * `canPrompt` is `true`.
  *
  * @stability unstable
  * @since 4.0.0
@@ -25,8 +27,9 @@ import * as Stdio from "../Stdio.ts"
  * `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.
+ * The built-in `Command` output reads `canColor`, and fallback prompts for
+ * missing flags and arguments are skipped when `canPrompt` is `false`.
+ * `canAnimate` is for application code that renders its own output.
  *
  * @stability unstable
  * @category models

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

@@ -51,6 +51,10 @@ const buildFlagGroupDeclarations = (
   lines.push(``)
 }
 
+// Quoting these substitutions breaks quote matching on Bash 3.2.
+const removeQuotes = (variable: string): string =>
+  [`\\\\`, `\\"`, `\\'`].map((quote) => `${variable}=\${${variable}//${quote}/}`).join("; ")
+
 /**
  * Complete choices without `compgen -W`, which reparses quoted values. Escape
  * only the portion readline replaces for the active quote context.
@@ -71,9 +75,8 @@ const choicesHelper = (helperName: string, lines: Array<string>): void => {
   lines.push(`  esac`)
   lines.push(``)
   lines.push(`  local _prefix="$_cur" _committed="$_head"`)
-  // Quoting these substitutions breaks quote matching on Bash 3.2.
-  lines.push(`  _prefix=\${_prefix//\\\\/}; _prefix=\${_prefix//\\"/}; _prefix=\${_prefix//\\'/}`)
-  lines.push(`  _committed=\${_committed//\\\\/}; _committed=\${_committed//\\"/}; _committed=\${_committed//\\'/}`)
+  lines.push(`  ${removeQuotes("_prefix")}`)
+  lines.push(`  ${removeQuotes("_committed")}`)
   lines.push(``)
   lines.push(`  COMPREPLY=()`)
   lines.push(`  local _choice _rest _match`)
@@ -111,30 +114,76 @@ const choicesHelper = (helperName: string, lines: Array<string>): void => {
   lines.push(``)
 }
 
-const choiceCompletion = (helperName: string, values: ReadonlyArray<string>): string =>
-  `${helperName} "$cur" "$_comp_word" ${values.map((value) => `'${escapeForBash(value)}'`).join(" ")}`
+interface Helpers {
+  readonly choices: string
+  readonly paths: string
+}
 
-const flagValueCompletion = (type: Completions.FlagType, helperName: string): string | undefined => {
-  switch (type._tag) {
-    case "Boolean":
-      return undefined
-    case "Choice":
-      return choiceCompletion(helperName, type.values)
-    case "Path":
-      if (type.pathType === "directory") return `COMPREPLY=( $(compgen -d -- "$cur") )`
-      return `COMPREPLY=( $(compgen -f -- "$cur") )`
-    default:
-      return undefined
-  }
+/**
+ * Complete paths through the choice helper, one `compgen` line per candidate.
+ * The typed directory is kept as written so expansions in it still apply; only
+ * the completed name is quoted.
+ */
+const pathsHelper = (helpers: Helpers, lines: Array<string>): void => {
+  lines.push(`${helpers.paths}()`)
+  lines.push(`{`)
+  lines.push(`  local _kind="$1" _cur="$2" _word="$3"`)
+  lines.push(``)
+  lines.push(`  local _prefix="$_cur" _committed="\${_cur%"$_word"}"`)
+  lines.push(`  ${removeQuotes("_prefix")}`)
+  lines.push(`  ${removeQuotes("_committed")}`)
+  lines.push(``)
+  // Track a quote the typed directory leaves open.
+  lines.push(`  local _typed="" _dir="$_committed" _open="" _i`)
+  lines.push(`  if [[ "$_word" == */* ]]; then`)
+  lines.push(`    _typed="\${_word%/*}/"`)
+  lines.push(`    _dir="\${_prefix%/*}/"`)
+  lines.push(`    if [[ "$_cur" == "$_word" ]]; then`)
+  lines.push(`      for ((_i = 0; _i < \${#_typed}; _i++)); do`)
+  lines.push(`        case "$_open\${_typed:_i:1}" in`)
+  lines.push(`          \\\\|\\"\\\\) ((_i += 1)) ;;`)
+  lines.push(`          \\"|\\') _open="\${_typed:_i:1}" ;;`)
+  lines.push(`          \\"\\"|\\'\\') _open="" ;;`)
+  lines.push(`        esac`)
+  lines.push(`      done`)
+  lines.push(`    fi`)
+  lines.push(`  fi`)
+  lines.push(``)
+  lines.push(`  local _path _names=() _rest="\${_word#"$_typed"}"`)
+  lines.push(`  while IFS= read -r _path; do`)
+  lines.push(`    if [[ "$_path" == "$_dir"* ]]; then`)
+  lines.push(`      _names+=("$_committed\${_path#"$_dir"}")`)
+  lines.push(`    elif [[ -z "$_committed" ]]; then`)
+  // Bash 3.2 returns expanded paths, which replace the whole word.
+  lines.push(`      _names+=("$_path")`)
+  lines.push(`      _typed="" _rest="" _open=""`)
+  lines.push(`    fi`)
+  lines.push(`  done < <(compgen "$_kind" -- "$_prefix")`)
+  // Close the quote before the name so a common prefix stays balanced.
+  lines.push(`  if [[ -n "$_open" ]]; then`)
+  lines.push(`    _typed+="$_open"`)
+  lines.push(`    _rest="\${_prefix##*/}"`)
+  lines.push(`  fi`)
+  lines.push(``)
+  lines.push(`  ${helpers.choices} "\${_cur%"$_word"}$_rest" "$_rest" "\${_names[@]}"`)
+  lines.push(`  for ((_i = 0; _i < \${#COMPREPLY[@]}; _i++)); do`)
+  lines.push(`    COMPREPLY[_i]="$_typed\${COMPREPLY[_i]}"`)
+  lines.push(`  done`)
+  lines.push(`}`)
+  lines.push(``)
 }
 
-const argCompletion = (type: Completions.ArgumentType, helperName: string): string | undefined => {
+const valueCompletion = (
+  type: Completions.FlagType | Completions.ArgumentType,
+  helpers: Helpers
+): string | undefined => {
   switch (type._tag) {
-    case "Choice":
-      return choiceCompletion(helperName, type.values)
+    case "Choice": {
+      const values = type.values.map((value) => `'${escapeForBash(value)}'`).join(" ")
+      return `${helpers.choices} "$cur" "$_comp_word" ${values}`
+    }
     case "Path":
-      if (type.pathType === "directory") return `COMPREPLY=( $(compgen -d -- "$cur") )`
-      return `COMPREPLY=( $(compgen -f -- "$cur") )`
+      return `${helpers.paths} ${type.pathType === "directory" ? "-d" : "-f"} "$cur" "$_comp_word"`
     default:
       return undefined
   }
@@ -148,7 +197,7 @@ const generateFunction = (
   descriptor: Completions.CommandDescriptor,
   parentPath: ReadonlyArray<string>,
   lines: Array<string>,
-  helperName: string
+  helpers: Helpers
 ): void => {
   const currentPath = [...parentPath, descriptor.name]
   const funcName = `_${currentPath.map(sanitizeFunctionName).join("_")}`
@@ -175,7 +224,7 @@ const generateFunction = (
       for (const alias of flag.aliases) {
         longNames.push(alias.length === 1 ? `-${alias}` : `--${alias}`)
       }
-      const completion = flagValueCompletion(flag.type, helperName)
+      const completion = valueCompletion(flag.type, helpers)
       if (completion) {
         lines.push(`    ${longNames.join("|")})`)
         lines.push(`      ${completion}`)
@@ -231,7 +280,7 @@ const generateFunction = (
 
   // Positional argument completion
   const argsWithCompletions = descriptor.arguments.flatMap((argument, index) => {
-    const completion = argCompletion(argument.type, helperName)
+    const completion = valueCompletion(argument.type, helpers)
     return completion === undefined ? [] : [{ argument, completion, index }]
   })
   if (argsWithCompletions.length > 0) {
@@ -287,7 +336,7 @@ const generateFunction = (
 
   // Recurse into subcommands
   for (const sub of descriptor.subcommands) {
-    generateFunction(sub, currentPath, lines, helperName)
+    generateFunction(sub, currentPath, lines, helpers)
   }
 }
 
@@ -301,7 +350,7 @@ export const generate = (
   const lines: Array<string> = []
   const safeName = sanitizeFunctionName(executableName)
   // Sanitized command names cannot contain `-`.
-  const helperName = `_${safeName}--choices`
+  const helpers: Helpers = { choices: `_${safeName}--choices`, paths: `_${safeName}--paths` }
 
   lines.push(`###-begin-${escapeForBash(executableName)}-completions-###`)
   lines.push(`#`)
@@ -341,8 +390,9 @@ export const generate = (
   lines.push(`fi`)
   lines.push(``)
 
-  choicesHelper(helperName, lines)
-  generateFunction(descriptor, [], lines, helperName)
+  choicesHelper(helpers.choices, lines)
+  pathsHelper(helpers, lines)
+  generateFunction(descriptor, [], lines, helpers)
 
   lines.push(`complete -F _${safeName} ${escapeForBash(executableName)}`)
   lines.push(`###-end-${escapeForBash(executableName)}-completions-###`)

package/src/cli/internal/help.ts

@@ -96,7 +96,7 @@ const collectDeclaredGlobalFlags = (command: Command.Any): ReadonlyArray<GlobalF
   return dedupeGlobalFlags(collected)
 }
 
-const getSharedFlagsForCommandPath = (
+const getInheritedFlagsForCommandPath = (
   commands: ReadonlyArray<Command.Any>,
   currentFlags: ReadonlyArray<FlagDoc>
 ): ReadonlyArray<FlagDoc> => {
@@ -105,7 +105,7 @@ const getSharedFlagsForCommandPath = (
   }
 
   const seen = new Set(currentFlags.map((flag) => flag.name))
-  const sharedFlags: Array<FlagDoc> = []
+  const inheritedFlags: Array<FlagDoc> = []
 
   for (const ancestor of commands.slice(0, -1)) {
     const ancestorImpl = toImpl(ancestor)
@@ -116,19 +116,16 @@ const getSharedFlagsForCommandPath = (
         if (seen.has(single.name)) {
           continue
         }
-        // Hidden ancestor flags are excluded from the shared-flags section
-        // of subcommand help, the same way they're excluded from the owning
-        // command's own help output.
         if (single.hidden) {
           continue
         }
         seen.add(single.name)
-        sharedFlags.push(toFlagDoc(single, metadata))
+        inheritedFlags.push(toFlagDoc(single, metadata))
       }
     }
   }
 
-  return sharedFlags
+  return inheritedFlags
 }
 
 /**
@@ -160,7 +157,7 @@ export const getHelpForCommandPath = <Name extends string, Input, E, R, ContextI
 
     const baseDoc = toImpl(currentCommand).buildHelpDoc(commandPath)
 
-    const sharedFlags = getSharedFlagsForCommandPath(commands, baseDoc.flags)
+    const inheritedFlags = getInheritedFlagsForCommandPath(commands, baseDoc.flags)
 
     const flags = getGlobalFlagsForCommandPath(command, commandPath, builtIns)
     const globalFlagDocs: Array<FlagDoc> = []
@@ -179,5 +176,20 @@ export const getHelpForCommandPath = <Name extends string, Input, E, R, ContextI
       }
     }
 
-    return { ...baseDoc, flags: [...sharedFlags, ...baseDoc.flags], globalFlags: globalFlagDocs }
+    // Globals accumulate along the path, so the deepest declaring scope lists them all.
+    let scopeLength = 1
+    for (let i = commands.length - 1; i > 0; i--) {
+      if (toImpl(commands[i]).globalFlags.length > 0) {
+        scopeLength = i + 1
+        break
+      }
+    }
+
+    return {
+      ...baseDoc,
+      inheritedFlags,
+      globalFlags: globalFlagDocs,
+      globalFlagsScope: commandPath.slice(0, scopeLength),
+      commandPath
+    }
   })