Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Command.runWith has no way to opt out of its own console-rendered help/error output on parse failures

Đã đóng
  • Có gì không ổn?
#6,313 2 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

@IMax153 đang làm issue này rồi.

Từ ngày 29/7/2026.

  • #6743 của @IMax153 — đang mở

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
48/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Ít trao đổi
Công nghệ
typescript
Lĩnh vực
cli

Hướng nghiên cứu

Start in packages/effect/src/unstable/cli/Command.ts, reading runWith, its ShowHelp catchFilter, and showHelp. Run the missing-name reproduction to observe the console writes and surfaced failure. Done means a supported runWith configuration or hook provides the requested control without requiring ambient Console buffering, with behavior covered by relevant CLI tests.

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

Mô tả

4.0 enhancement
Effect version

4.0.0-beta.93 (effect/unstable/cli)

Description

Command.runWith's parser (packages/effect/src/unstable/cli/Command.ts) unconditionally renders its own help/error output to the console whenever a run fails with CliError.ShowHelp, with no way for a host application to opt out of, redirect, or make that rendering conditional on the specific failure. The catchFilter at the end of runWith catches every ShowHelp failure and calls showHelp(command, error) before re-failing with the same error:

const showHelp = <Name extends string, Input, E, R, ContextInput>(
  command: Command<Name, Input, ContextInput, E, R>,
  error: CliError.ShowHelp
): Effect.Effect<void, CliError.CliError, Environment> =>
  Effect.gen(function*() {
    const formatter = yield* CliOutput.Formatter
    const helpDoc = yield* getHelpForCommandPath(command, error.commandPath, GlobalFlag.BuiltIns)
    yield* Console.log(formatter.formatHelpDoc(helpDoc))
    if (error.errors.length > 0) {
      yield* Console.error(formatter.formatErrors(error.errors as any))
    }
  })

// ...
Effect.catchFilter(
  (error) =>
    CliError.isCliError(error) && error._tag === "ShowHelp"
      ? Result.succeed(error)
      : Result.fail(error),
  (error) => Effect.andThen(showHelp(command, error), Effect.fail(error))
),

A host CLI that wants full ownership of its own error/usage rendering — to match a different CLI framework's exact wording, to choose which stream a given failure lands on, or to suppress the built-in render entirely for specific failure tags — has no supported way to do that. runWith's config parameter is just { version: string }; there's no hook to skip, replace, or redirect the internal Console.log/Console.error calls.

Today the only way to get that control is to swap out the ambient Console.Console service for the duration of the run, buffer every log/error write, wait for the run's Exit, inspect the ShowHelp's errors array to classify what should have happened, and then selectively replay/redirect/drop the buffered writes. That means:

  • Re-implementing (outside the library) which ShowHelp cases the library itself would consider "should still show usage" vs. "already showed everything needed" — knowledge only runWith/showHelp really have.
  • Coupling to showHelp's exact Console call pattern (that it's exactly one log then, conditionally, one error) — any change to that internal implementation silently breaks the workaround.
  • No way to prevent the render for a subset of failures without inspecting error internals from outside the library (e.g. wanting to keep the help dump for an unrecognized flag but suppress it for a missing required flag, to match a host framework that treats those differently).
Reproduction
import { Effect, Console } from "effect"
import { Command, Flag } from "effect/unstable/cli"

const cmd = Command.make("greet", { name: Flag.string("name") }, () => Effect.void)

const writes: Array<string> = []
const bufferingConsole = {
  ...console,
  log: (...args: unknown[]) => Effect.sync(() => writes.push(`log: ${args.join(" ")}`)),
  error: (...args: unknown[]) => Effect.sync(() => writes.push(`error: ${args.join(" ")}`)),
}

const program = Command.runWith(cmd, { version: "1.0.0" })([]).pipe(
  Effect.provideService(Console.Console, bufferingConsole as any),
  Effect.exit,
)

Effect.runPromise(program).then((exit) => {
  console.log("writes:", writes) // always has the library's own help+error render
  console.log("exit:", exit)     // caller ALSO gets the ShowHelp error to handle itself
})

Running this for a missing required flag (name never supplied) produces both:

  1. The library's own Console.log/Console.error render (captured in writes above), which happens unconditionally.
  2. The ShowHelp failure surfacing through exit, for the caller to render again if it wants its own error message.

There is no runWith option to get #2 without #1.

Suggested fix

A few shapes that would work, roughly in order of preference:

  • A. Add a runWith config option (e.g. renderHelp?: boolean, default true) that skips the internal showHelp call entirely, so a host that wants to own rendering gets the bare ShowHelp failure with no console side effect at all.
  • B. Let runWith accept a render hook (e.g. config.onShowHelp?: (error: CliError.ShowHelp, formatter: CliOutput.Formatter) => Effect.Effect<void>) in place of the hardcoded Console.log/Console.error pair, so a host can redirect output per-failure-tag without needing to intercept Console at all.
  • C. At minimum, export showHelp (or an equivalent pure "format without printing" function) as public API, so hosts that need to suppress the built-in render can still reproduce it faithfully on their own terms instead of re-deriving formatter.formatHelpDoc/formatErrors's call order by trial and error.

Happy to open a PR for whichever direction maintainers prefer — we're working around this downstream in our own CLI (built on effect/unstable/cli) by swapping the ambient Console.Console service, but it's fragile against any change to showHelp's internals and duplicates classification logic the library already has.

Ngôn ngữ chính
TypeScript
Star
16.7k
Fork
808
Merge trung bình
10 giờ 17 phút
Pull request đã merge (30 ngày)
850

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.