@effected/cli 0.8.0 → 0.9.0

package/CliRuntime.js

@@ -2,6 +2,7 @@ import { isExitCode } from "./internal/isExitCode.js";
 import { CliExit } from "./CliExit.js";
 import { CliLogger } from "./CliLogger.js";
 import { ExitRequested } from "./internal/ExitRequested.js";
+import { routeHelpOnUsageError } from "./internal/HelpRouting.js";
 import { Cause, Effect, MutableRef, Runtime } from "effect";
 import { CliError } from "effect/unstable/cli";
 
@@ -113,8 +114,12 @@ var CliRuntime = class CliRuntime {
 		}
 		if (isRenderedUserError(error)) return Effect.fail(CliRuntime.reported(error, chooseExitCode(error, options.usageExitCode ?? 64)));
 		const render = options.render ?? ((value) => String(value));
+		const details = {
+			cause,
+			isDefect: !Cause.hasFails(cause)
+		};
 		return Effect.gen(function* () {
-			for (const line of toLines(render(error))) yield* Effect.logError(line);
+			for (const line of toLines(render(error, details))) yield* Effect.logError(line);
 			return yield* Effect.fail(CliRuntime.reported(error, chooseExitCode(error, options.exitCode)));
 		});
 	}));
@@ -140,7 +145,7 @@ var CliRuntime = class CliRuntime {
 	* ```
 	*/
 	static main = (program, options) => Effect.gen(function* () {
-		yield* program;
+		yield* options.helpOnUsageError === "stderr" ? routeHelpOnUsageError(program) : program;
 		const exit = yield* CliExit;
 		const code = MutableRef.get(exit.code);
 		if (!isExitCode(code)) return yield* Effect.die(/* @__PURE__ */ new Error(`CliRuntime.main: CliExit code must be an integer 0..255, received ${code}`));

package/README.md

@@ -149,8 +149,8 @@ $ echo $?
 
 - `CliLogger.layer(options?)` — replaces the default logger with plain lines, routing every level to stderr by default. The threshold is the `stderrFrom` option (pass `"Error"` to restore the old split), compared ordinally, so a level added upstream lands on the right stream without a change here.
 - `CliLogger.make(options?)` — the `Logger` itself, for composing into a logger set you already have.
-- `CliRuntime.reportFailures(options?)` — reports through your logger, then re-fails with an exit code and the mark that stops the runtime reporting it a second time. Never renders a `CliError.ShowHelp` (already printed by `Command.runWith`) — a `ShowHelp` carrying errors is remapped to `usageExitCode` (default `64`).
-- `CliRuntime.main(program, { platform, logger?, ... })` — assembles a whole program in the one order that reports every failure well: a fresh `CliExit`, the platform layer inside failure reporting, and the logger outermost.
+- `CliRuntime.reportFailures(options?)` — reports through your logger, then re-fails with an exit code and the mark that stops the runtime reporting it a second time. `render(error, details)` receives the squashed error and a `FailureDetails` (`{ cause, isDefect }`), so a defect can render differently from a typed failure. Never renders a `CliError.ShowHelp` (already printed by `Command.runWith`) — a `ShowHelp` carrying errors is remapped to `usageExitCode` (default `64`).
+- `CliRuntime.main(program, { platform, logger?, ... })` — assembles a whole program in the one order that reports every failure well: a fresh `CliExit`, the platform layer inside failure reporting, and the logger outermost. `helpOnUsageError: "stderr"` moves the help printed with a parse error onto stderr beside the error, so a caller piping stdout into `jq` gets nothing on a usage error; `--help` and a bare group invocation still print on stdout.
 - `CliRuntime.reported(error, exitCode?)` — marks an error you reported yourself, so the runtime stays quiet about it. A typed `Error` comes back as its own type (the marks are added in place) when it passes `instanceof Error` at runtime; any other value — including one that only satisfies `Error`'s shape structurally — is wrapped in a plain `Error`. A `CliError.UserError` marked with `reported` is treated as already printed and is not rendered — use a different error type if the program has not printed it. It keeps the code you pass: `reported(userError, 3)` exits `3`, not `usageExitCode`.
 - `CliExit.set(code)` — records a findings exit code from a successful program; the highest code set during the run wins. `CliExit.layer` mints a fresh cell per provide (`Layer.fresh`) — `CliRuntime.main` provides it for you.
 - `CliColor.enabled` — `Effect<boolean, never, Stdio>`, the no-color.org decision: off when stdout is not a terminal, or `NO_COLOR` is a non-empty value. `FORCE_COLOR` is ignored.

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Context, Effect, Layer, LogLevel, Logger, MutableRef, Stdio } from "effect";
+import { Cause, Context, Effect, Layer, LogLevel, Logger, MutableRef, Stdio } from "effect";
 import { CliOutput } from "effect/unstable/cli";
 import { ConfigValidationError } from "@effected/config-file";
 //#region src/CliColor.d.ts
@@ -223,6 +223,21 @@ export declare class CliLogger {
 }
 //#endregion
 //#region src/CliRuntime.d.ts
+/**
+ * What `render` is told about a failure beyond the squashed error.
+ *
+ * @public
+ */
+interface FailureDetails {
+  /** The whole cause the program failed with, before squashing. */
+  readonly cause: Cause.Cause<unknown>;
+  /**
+   * `true` when the cause carries no typed failure, so `error` is a defect:
+   * a `die`, a thrown exception, a bug. `false` when `error` is a typed
+   * failure from the error channel.
+   */
+  readonly isDefect: boolean;
+}
 /**
  * How a failure is turned into output and an exit code.
  *
@@ -235,8 +250,14 @@ interface ReportFailuresOptions {
    * @remarks
    * Return several lines to print several: a config error's own message
    * followed by the rendered issue lines, say.
+   *
+   * `error` is the squashed cause: the first typed failure when there is
+   * one, otherwise the first defect. `details` says which it is, so a typed
+   * failure can render as one line and a defect as a full report, without
+   * guessing from the error's shape. A renderer that takes only `error`
+   * still fits.
    */
-  readonly render?: ((error: unknown) => string | ReadonlyArray<string>) | undefined;
+  readonly render?: ((error: unknown, details: FailureDetails) => string | ReadonlyArray<string>) | undefined;
   /**
    * The exit code to use when the error does not carry one.
    *
@@ -276,6 +297,25 @@ interface MainOptions<RP, EP> extends ReportFailuresOptions {
   readonly platform: Layer.Layer<RP, EP>;
   /** The logger, provided outermost. Defaults to `CliLogger.layer()`. */
   readonly logger?: Layer.Layer<never> | undefined;
+  /**
+   * Where the help document goes when it is printed with a usage error:
+   * `"stdout"` (the default, core's behaviour) or `"stderr"`, beside the
+   * errors.
+   *
+   * @remarks
+   * `"stderr"` keeps stdout clean for a caller that parses it, such as a
+   * hook piping JSON into `jq`: an unknown flag, a bad value or an unknown
+   * subcommand then writes nothing to stdout. An explicit `--help` and a
+   * bare invocation of a command group still print help on stdout: neither
+   * is an error.
+   *
+   * Two cases keep help on stdout even under `"stderr"`. A `CliOutput`
+   * Formatter or a `Console` provided inside `program` is not seen by
+   * `main`, so its help is not rerouted; provide the Formatter through
+   * `platform` instead. And with `Command.runWith`'s `renderErrors: false`
+   * no errors are printed, so nothing marks the help as a usage error's.
+   */
+  readonly helpOnUsageError?: "stdout" | "stderr" | undefined;
 }
 /**
  * Report a CLI program's failures through the program's own logger.
@@ -543,5 +583,5 @@ export declare class SchemaIssueRenderer {
   static readonly render: (issue: unknown) => ReadonlyArray<string>;
 }
 //#endregion
-export type { CliExitShape, CliLoggerOptions, MainOptions, ReportFailuresOptions };
+export type { CliExitShape, CliLoggerOptions, FailureDetails, MainOptions, ReportFailuresOptions };
 //# sourceMappingURL=index.d.ts.map

package/internal/HelpRouting.js

@@ -0,0 +1,90 @@
+import { Console, Effect } from "effect";
+import { CliOutput } from "effect/unstable/cli";
+
+//#region src/internal/HelpRouting.ts
+const OTHER_METHODS = Object.keys({
+	assert: true,
+	clear: true,
+	count: true,
+	countReset: true,
+	debug: true,
+	dir: true,
+	dirxml: true,
+	group: true,
+	groupCollapsed: true,
+	groupEnd: true,
+	info: true,
+	table: true,
+	time: true,
+	timeEnd: true,
+	timeLog: true,
+	trace: true,
+	warn: true
+});
+/**
+* Run `program` so a help document printed together with parse errors goes to
+* stderr, beside the errors, instead of stdout.
+*
+* @remarks
+* Core's `Command.runWith` prints a usage error as `Console.log(help)` then
+* `Console.error(errors)`, and an explicit `--help` or a bare group
+* invocation as the same `Console.log(help)` with nothing after it. The two
+* only differ in what follows, so the help is held: the Formatter records
+* every string its `formatHelpDoc` and `formatErrors` return, and a `log` of
+* a recorded help string waits for the next console call. An `error` of a
+* recorded errors string moves it to stderr; anything else, or the program
+* ending, releases it to stdout. At most one document is held, and output
+* order is kept.
+*
+* A Formatter or Console provided inside `program` is not wrapped, so help
+* stays on stdout there: core's own behaviour.
+*
+* @internal
+*/
+const routeHelpOnUsageError = (program) => Effect.gen(function* () {
+	const formatter = yield* CliOutput.Formatter;
+	const sink = yield* Console.Console;
+	const helps = /* @__PURE__ */ new Set();
+	const errors = /* @__PURE__ */ new Set();
+	let held;
+	const release = () => {
+		if (held === void 0) return;
+		const help = held;
+		held = void 0;
+		sink.log(...help);
+	};
+	const recording = Object.assign(Object.create(formatter), {
+		formatHelpDoc: (doc) => {
+			const text = formatter.formatHelpDoc(doc);
+			helps.add(text);
+			return text;
+		},
+		formatErrors: (list) => {
+			const text = formatter.formatErrors(list);
+			errors.add(text);
+			return text;
+		}
+	});
+	const routing = Object.create(sink);
+	for (const method of OTHER_METHODS) routing[method] = (...args) => {
+		release();
+		return sink[method](...args);
+	};
+	routing.log = (...args) => {
+		release();
+		if (args.length === 1 && typeof args[0] === "string" && helps.has(args[0])) held = args;
+		else sink.log(...args);
+	};
+	routing.error = (...args) => {
+		if (held !== void 0 && args.length === 1 && typeof args[0] === "string" && errors.has(args[0])) {
+			const help = held;
+			held = void 0;
+			sink.error(...help);
+		} else release();
+		sink.error(...args);
+	};
+	return yield* program.pipe(Effect.provideService(CliOutput.Formatter, recording), Effect.provideService(Console.Console, routing), Effect.ensuring(Effect.sync(release)));
+});
+
+//#endregion
+export { routeHelpOnUsageError };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/cli",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"private": false,
 	"description": "The boundary layer of an effect/unstable/cli program: plain CLI output, failure reporting, and schema-issue rendering",
 	"keywords": [