@effected/cli 0.8.0 → 0.10.0

package/CliColor.js

@@ -1,5 +1,5 @@
 import { Config, Effect, Layer, Option, Stdio } from "effect";
-import { CliOutput } from "effect/unstable/cli";
+import { CliOutput } from "effect/cli";
 
 //#region src/CliColor.ts
 const noColor = Config.option(Config.String("NO_COLOR"));

package/CliRuntime.js

@@ -2,8 +2,9 @@ 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";
+import { CliError } from "effect/cli";
 
 //#region src/CliRuntime.ts
 const isShowHelp = (u) => CliError.isCliError(u) && u._tag === "ShowHelp";
@@ -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/CliTest.js

@@ -1,5 +1,5 @@
 import { Effect, FileSystem, Path, Stream } from "effect";
-import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
 
 //#region src/CliTest.ts
 const text = (stream) => Stream.mkString(Stream.decodeText(stream));
@@ -47,7 +47,7 @@ var CliTest = class {
 	* @remarks
 	* `stdin` is never left as an inherited open pipe: when omitted or `""`
 	* the child gets an already-ended empty input (`Stream.empty`), so a
-	* stdin-reading bin exits instead of hanging on `effect/unstable/process`'s
+	* stdin-reading bin exits instead of hanging on `effect/process`'s
 	* default `"pipe"` stdio, which stays open until something writes to and
 	* ends it.
 	*/

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-The boundary layer of a command-line program built on `effect/unstable/cli`: how output reaches a human, how a failure is reported, and how a schema issue becomes a sentence someone can act on. `CliLogger` renders log records as plain lines and routes diagnostics to stderr, reading the `Console` off the fiber so it needs no platform package and the stream split is actually testable. `CliRuntime.reportFailures` catches inside your program so a failure prints through *your* logger instead of Effect's default one on stdout, then re-fails with the exit code and the no-double-report mark; `CliRuntime.main` assembles a whole program — platform layer, a fresh `CliExit`, failure reporting, and the logger — in the one order that reports every failure well. `CliExit` lets a findings command (a linter that found problems, say) succeed with a non-zero exit code, with finalizers intact on any runtime. `CliColor` decides once, per the no-color.org rule, whether output carries ANSI colour, and hands core's own `CliOutput.Formatter` the same decision. `SchemaIssueRenderer` and `ConfigIssueRenderer` turn issue trees into `unknown key at groups.g.rulesetz`. The `./testing` subpath's `CliTest` spawns a built bin hermetically for a test that wants a real subprocess.
+The boundary layer of a command-line program built on `effect/cli`: how output reaches a human, how a failure is reported, and how a schema issue becomes a sentence someone can act on. `CliLogger` renders log records as plain lines and routes diagnostics to stderr, reading the `Console` off the fiber so it needs no platform package and the stream split is actually testable. `CliRuntime.reportFailures` catches inside your program so a failure prints through *your* logger instead of Effect's default one on stdout, then re-fails with the exit code and the no-double-report mark; `CliRuntime.main` assembles a whole program — platform layer, a fresh `CliExit`, failure reporting, and the logger — in the one order that reports every failure well. `CliExit` lets a findings command (a linter that found problems, say) succeed with a non-zero exit code, with finalizers intact on any runtime. `CliColor` decides once, per the no-color.org rule, whether output carries ANSI colour, and hands core's own `CliOutput.Formatter` the same decision. `SchemaIssueRenderer` and `ConfigIssueRenderer` turn issue trees into `unknown key at groups.g.rulesetz`. The `./testing` subpath's `CliTest` spawns a built bin hermetically for a test that wants a real subprocess.
 
 > **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
 > development against a single pinned Effect v4 prerelease. Packages graduate to
@@ -25,7 +25,7 @@ Everything here shares one property: **you only discover you needed it by shippi
 
 Effect's default logger emits `[00:33:56.619] INFO (#2): message`. That is correct for a service being scraped and wrong for a tool someone is watching — it turns a formatted table into noise — and nothing at the call site suggests it. A platform `runMain` then reports an unhandled failure through that *same* default logger, which sits outside the layers your program was provided, so a program that carefully installs a CLI logger still prints its failures in the format that logger exists to replace, on **stdout**, the one stream errors must not use. And a decode failure arrives as a structured tree when what a user needs is a sentence naming the key they got wrong; core does ship formatters for this, but they live on `SchemaIssue` rather than `SchemaError`, are named `makeFormatter*`, and are not referenced by `SchemaError.message` — two engineers searched for two rounds and concluded they did not exist.
 
-This package is **not a CLI framework**. `effect/unstable/cli` owns argument parsing, flags, the command tree and help, and this package must never grow a second one.
+This package is **not a CLI framework**. `effect/cli` owns argument parsing, flags, the command tree and help, and this package must never grow a second one.
 
 ## Install
 
@@ -104,13 +104,13 @@ Print-then-`reported` is for a program run **without** `CliRuntime.main` or `rep
 
 A findings command — one whose non-zero exit reports a result rather than a
 crash — wires `CliRuntime.main`, `CliExit.set` and `CliColor.formatterLayer`
-around an ordinary `effect/unstable/cli` command:
+around an ordinary `effect/cli` command:
 
 ```ts
 import { CliColor, CliExit, CliRuntime } from "@effected/cli";
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
 import { Console, Effect, Layer } from "effect";
-import { Command, Flag } from "effect/unstable/cli";
+import { Command, Flag } from "effect/cli";
 
 const findProblems = (strict: boolean): ReadonlyArray<string> =>
   strict ? ["missing changeset", "unpinned dependency"] : ["missing changeset"];
@@ -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,5 +1,5 @@
-import { Context, Effect, Layer, LogLevel, Logger, MutableRef, Stdio } from "effect";
-import { CliOutput } from "effect/unstable/cli";
+import { Cause, Context, Effect, Layer, LogLevel, Logger, MutableRef, Stdio } from "effect";
+import { CliOutput } from "effect/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/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,8 +1,8 @@
 {
 	"name": "@effected/cli",
-	"version": "0.8.0",
+	"version": "0.10.0",
 	"private": false,
-	"description": "The boundary layer of an effect/unstable/cli program: plain CLI output, failure reporting, and schema-issue rendering",
+	"description": "The boundary layer of an effect/cli program: plain CLI output, failure reporting, and schema-issue rendering",
 	"keywords": [
 		"effect",
 		"cli",
@@ -40,8 +40,8 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.12.0",
-		"effect": "4.0.0-rc.117"
+		"@effected/config-file": "^0.13.0",
+		"effect": "4.0.0-rc.118"
 	},
 	"peerDependenciesMeta": {
 		"@effected/config-file": {

package/testing.d.ts

@@ -1,5 +1,5 @@
 import { Effect, FileSystem, Path, PlatformError, Scope } from "effect";
-import { ChildProcessSpawner } from "effect/unstable/process";
+import { ChildProcessSpawner } from "effect/process";
 //#region src/CliTest.d.ts
 /**
  * A hermetic temp directory minted by {@link CliTest.sandbox}, removed when its
@@ -83,7 +83,7 @@ export declare class CliTest {
    * @remarks
    * `stdin` is never left as an inherited open pipe: when omitted or `""`
    * the child gets an already-ended empty input (`Stream.empty`), so a
-   * stdin-reading bin exits instead of hanging on `effect/unstable/process`'s
+   * stdin-reading bin exits instead of hanging on `effect/process`'s
    * default `"pipe"` stdio, which stays open until something writes to and
    * ends it.
    */