DRAFT: cli: shared and global flags can't be listed in the root command's help only

Cerrado
  • ¿Algo no está bien?
#8,642 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Ya se ha fusionado un pull request relacionado.

  • #9276 de @okarin1511 — fusionado

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
node.js, typescript
Área
cli

Línea de trabajo

Start with packages/effect/src/cli/internal/help.ts:99-132 and :152-183, then reproduce the root and deploy help output from the issue. Compare the flag-level and CliConfig directions with related issue #6376 and confirm the intended inheritance behavior. Done should include an agreed help-layout design that preserves parsing and covers shared, global, and built-in flags.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

We build multi-command CLIs on effect/cli, and we're asking whether a help-layout option would fit.

What we observed

A flag declared at the root with Command.withSharedFlags or Command.withGlobalFlags is listed again in every subcommand's --help, and the built-in global flags are too. For a tool with a handful of such flags and many subcommands, every subcommand page repeats the same block, and the flags specific to that subcommand get lost in it. Flag.withHidden is the only other option, and it hides the flag from the root's help too.

We haven't found a way to say "list this flag in the root's help only; still accept and parse it everywhere".

Environment: [email protected] (tag [email protected], ad61db8) and @effect/[email protected], on Node 26.10.0 and macOS. From reading the source, the same lines are unchanged on main at 8b0eac6 (packages/effect/src/cli/internal/help.ts:99-132, :152-183).

Reproduction
import * as NodeRuntime from "@effect/platform-node/NodeRuntime"
import * as NodeServices from "@effect/platform-node/NodeServices"
import { Effect } from "effect"
import { Command, Flag, GlobalFlag } from "effect/cli"

const Color = GlobalFlag.Setting("color")({
  flag: Flag.Boolean("color").pipe(Flag.withDescription("Colour the output"), Flag.withDefault(true))
})

const deploy = Command.make("deploy", { target: Flag.String("target") }, () => Effect.void)
const status = Command.make("status", {}, () => Effect.void)

const app = Command.make("app").pipe(
  Command.withSharedFlags({
    profile: Flag.String("profile").pipe(
      Flag.withDescription("Profile to use"),
      Flag.withDefault("default"),
      (flag) => process.env.HIDE === "1" ? Flag.withHidden(flag) : flag
    )
  }),
  Command.withGlobalFlags([Color]),
  Command.withSubcommands([deploy, status])
)

Command.run(app, { version: "0.0.0" }).pipe(Effect.provide(NodeServices.layer), NodeRuntime.runMain)

The output, captured live:

$ node app.ts --help
USAGE
  app <subcommand> [flags]

FLAGS
  --profile string    Profile to use

GLOBAL FLAGS
  --help, -h                                                          Show help information
  --version, -v                                                       Show version information
  --wizard                                                            Start wizard mode for a command
  --completions <bash|zsh|fish|sh>                                    Print shell completion script (choices: bash, zsh, fish, sh)
  --log-level <all|trace|debug|info|warn|warning|error|fatal|none>    Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none)
  --color                                                             Colour the output

SUBCOMMANDS
  deploy    
  status    

$ node app.ts deploy --help
USAGE
  app deploy [flags]

FLAGS
  --profile string    Profile to use
  --target string     

GLOBAL FLAGS
  --help, -h                                                          Show help information
  --version, -v                                                       Show version information
  --wizard                                                            Start wizard mode for a command
  --completions <bash|zsh|fish|sh>                                    Print shell completion script (choices: bash, zsh, fish, sh)
  --log-level <all|trace|debug|info|warn|warning|error|fatal|none>    Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none)
  --color                                                             Colour the output

With Flag.withHidden, the shared flag leaves the root's help as well, although it still parses (the unchanged built-in lines are elided as …):

$ HIDE=1 node app.ts --help
USAGE
  app <subcommand> [flags]

GLOBAL FLAGS
  --help, -h                                                          Show help information
  …
  --color                                                             Colour the output

SUBCOMMANDS
  deploy    
  status    

$ HIDE=1 node app.ts deploy --profile staging --target prod; echo "exit=$?"
exit=0
Where it happens
  • help.ts:99-132: getSharedFlagsForCommandPath copies every non-hidden ancestor flag into the subcommand's FLAGS section.
  • help.ts:152-183: getHelpForCommandPath lists every global flag active on the path, built-ins included, under GLOBAL FLAGS. single.hidden is the only thing that removes a flag from either section, so a hidden flag disappears from every level.
Would an option fit?

Is there already a way to do this that we missed? If not, one possible direction is a flag-level marker, next to withHidden, that keeps a flag in the help of the command that declares it and leaves it out of descendants' help. Another is a CliConfig option for how subcommand help treats inherited and global flags: listed in full, or replaced with one line pointing at the root's --help. The second would also cover the built-ins.

Related
  • #6376 (open) asks for public control over the built-in global flags' help rendering. It's adjacent to this, though it doesn't cover where inherited flags appear.
Lenguaje dominante
TypeScript
Estrellas
16.7k
Forks
808
Merge medio
11 h 3 min
PR fusionados (30 d)
839

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Effect-TS/effect

Todos los issues de Effect-TS/effect

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.