Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Cerrado
  • ¿Algo no está bien?
#6,313 2 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@IMax153 ya está trabajando en esto.

Desde el 29/7/2026.

  • #6743 de @IMax153 — abierto

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
48/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
typescript
Área
cli

Línea de trabajo

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.

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

Descripción

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.

Lenguaje dominante
TypeScript
Estrellas
16.7k
Forks
808
Merge medio
10 h 17 min
PR fusionados (30 d)
850

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.