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

Đã đóng
  • Có gì không ổn?
#8,642 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Một pull request liên quan đã được merge.

  • #9276 của @okarin1511 — đã merge

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
node.js, typescript
Lĩnh vực
cli

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
TypeScript
Star
16.7k
Fork
808
Merge trung bình
12 giờ 16 phút
Pull request đã merge (30 ngày)
809

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của Effect-TS/effect

Tất cả issue của Effect-TS/effect

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.