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

Chiusa
  • Qualcosa non va?
#8,642 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Una pull request collegata è già stata integrata.

  • #9276 di @okarin1511 — integrata

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
node.js, typescript
Ambito
cli

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.
Lingua principale
TypeScript
Stelle
16.7k
Fork
808
Merge medio
11h 40m
PR unite (30g)
827

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Effect-TS/effect

Tutte le issue di Effect-TS/effect

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.