@effected/cli 0.7.0 → 0.8.0

package/CliColor.js

@@ -0,0 +1,66 @@
+import { Config, Effect, Layer, Option, Stdio } from "effect";
+import { CliOutput } from "effect/unstable/cli";
+
+//#region src/CliColor.ts
+const noColor = Config.option(Config.String("NO_COLOR"));
+/**
+* Whether a CLI's output should carry ANSI colour, decided once and shared by
+* everything that renders — help text, error output, and any rendered result.
+*
+* @remarks
+* Follows the no-color.org rule: colour is off when stdout is not a
+* terminal, or when `NO_COLOR` is set to any **non-empty** value — an empty
+* `NO_COLOR=""` does not disable colour. `FORCE_COLOR` is ignored, matching
+* core's own formatter. The environment is read through the ambient
+* `ConfigProvider`, never `process`, so a test swaps it with
+* `Effect.provideService(ConfigProvider.ConfigProvider, ...)`. The kit's
+* default providers (`fromEnv`, `fromUnknown`) already treat an empty
+* `NO_COLOR` as unset, so the explicit `set === ""` check exists for a
+* provider constructed with `{ preserveEmptyStrings: true }`.
+*
+* @public
+*/
+var CliColor = class CliColor {
+	constructor() {}
+	/**
+	* The decision, for passing to a pure renderer as a plain boolean.
+	*
+	* @public
+	*/
+	static enabled = Effect.gen(function* () {
+		if (!(yield* (yield* Stdio.Stdio).stdoutIsTerminal)) return false;
+		const value = yield* noColor.pipe(Effect.orElseSucceed(() => Option.none()));
+		return Option.match(value, {
+			onNone: () => true,
+			onSome: (set) => set === ""
+		});
+	});
+	/**
+	* Core's default `CliOutput.Formatter`, coloured by the same decision as
+	* {@link CliColor.enabled}, so help text, parse errors and rendered
+	* output never disagree on whether colour is on.
+	*
+	* @remarks
+	* `overrides` replaces individual methods of the default formatter — for
+	* example `formatVersion`, to append a "via `<carrier>`" line without
+	* losing the other defaults. Each call mints a fresh layer; bind the
+	* result to a `const` or the decision is re-read every time it is
+	* provided.
+	*
+	* The `never` in its output does not mean it installs nothing.
+	* `CliOutput.Formatter` is a `Context.Reference`, whose key type is
+	* `never`, so this layer sets the formatter reference rather than
+	* providing a service. Every command it is provided to renders with the
+	* formatter it sets, and without it they fall back to core's default
+	* formatter.
+	*
+	* @public
+	*/
+	static formatterLayer = (overrides = {}) => Layer.unwrap(Effect.map(CliColor.enabled, (colors) => CliOutput.layer({
+		...CliOutput.defaultFormatter({ colors }),
+		...overrides
+	})));
+};
+
+//#endregion
+export { CliColor };

package/CliExit.js

@@ -0,0 +1,65 @@
+import { isExitCode } from "./internal/isExitCode.js";
+import { Context, Effect, Layer, MutableRef } from "effect";
+
+//#region src/CliExit.ts
+/**
+* The exit code a successful run wants, for commands whose findings are a
+* result rather than a failure (a linter that found problems, say).
+*
+* @remarks
+* Findings are not a failure — a JSON `tapError` must not fire, and the
+* handler must return normally — yet the process must exit non-zero. Writing
+* `process.exitCode` works only because Node's `runMain` skips
+* `process.exit(0)` on success; `process.exit(n)` in a handler skips every
+* finalizer. {@link CliRuntime.main} reads this cell after the program
+* succeeds and turns a non-zero code into a marked failure the runtime's
+* teardown honours, on any runtime, with finalizers intact.
+*
+* A `Service`, not a `Reference`: forgetting `CliRuntime.main` is a type error,
+* never a silently ignored global.
+*
+* @public
+*/
+var CliExit = class CliExit extends Context.Service()("@effected/cli/CliExit") {
+	/**
+	* A fresh cell at `0`; `CliRuntime.main` provides it, and tests provide it
+	* directly.
+	*
+	* @remarks
+	* Every provide mints a new cell. Layers memoize by reference across
+	* `Effect.provide` calls, so without `Layer.fresh` a second provide of this
+	* layer anywhere in the program — a nested `CliRuntime.main`, a test
+	* helper — would silently share the first run's cell and inherit its code.
+	*
+	* A program run under `CliRuntime.main` must NOT provide `CliExit.layer`
+	* itself: `main` already provides one, and a second provide mints a second,
+	* unrelated cell that `main` never reads back, so `CliExit.set` calls made
+	* against it are silently discarded and the run exits `0`.
+	*/
+	static layer = Layer.fresh(Layer.sync(this, () => ({ code: MutableRef.make(0) })));
+	/**
+	* Record an exit code; the highest code set during the run wins.
+	*
+	* @remarks
+	* Highest-wins, not last-wins, so a later "clean" step cannot quietly
+	* downgrade an earlier finding's code.
+	*
+	* The code must be an integer in `0..255` — the range a POSIX exit status
+	* can carry. Anything else dies as a defect naming the value: `256` would
+	* wrap to exit `0` and silently pass a run with findings, and a fraction
+	* such as `1.5` makes `process.exit` throw `ERR_OUT_OF_RANGE` after the
+	* program has finished.
+	*
+	* The code only applies to a run that **succeeds**. A program failure beats
+	* findings: when the program fails, `CliRuntime.main` never reads this
+	* cell, and the failure's own exit code (or the `exitCode` fallback) wins.
+	*/
+	static set = (code) => Effect.gen(function* () {
+		if (!isExitCode(code)) return yield* Effect.die(/* @__PURE__ */ new Error(`CliExit.set: exit code must be an integer 0..255, received ${code}`));
+		const exit = yield* CliExit;
+		if (code > MutableRef.get(exit.code)) MutableRef.set(exit.code, code);
+	});
+};
+
+//#endregion
+export { CliExit };

package/CliLogger.js

@@ -37,16 +37,24 @@ const defaultRender = (message) => Array.isArray(message) ? message.map(String).
 * @example
 * ```ts
 * import { CliLogger } from "@effected/cli"
-* import { Effect } from "effect"
+* import { Console, Effect } from "effect"
 *
 * const program = Effect.gen(function* () {
-*   yield* Effect.log("synced 3 repos")   // stdout, no timestamp
-*   yield* Effect.logError("one failed")  // stderr
+*   yield* Effect.log("synced 3 repos")    // stderr, no timestamp — a diagnostic
+*   yield* Console.log("3 repos synced")   // stdout — the program's actual output
+*   yield* Effect.logError("one failed")   // stderr
 * })
 *
 * program.pipe(Effect.provide(CliLogger.layer()))
 * ```
 *
+* @remarks
+* `stderrFrom` defaults to `"All"`: a CLI's stdout is its product, so every
+* log level is a diagnostic unless a consumer narrows the threshold. Write
+* program output with `Console.log`, never `Effect.log`. Pass
+* `stderrFrom: "Error"` for a tool whose output *is* its log lines. This is
+* a breaking change on the 0.x line (#716).
+*
 * @public
 */
 var CliLogger = class CliLogger {
@@ -60,7 +68,7 @@ var CliLogger = class CliLogger {
 	*/
 	static make = (options = {}) => {
 		const render = options.render ?? defaultRender;
-		const stderrFrom = options.stderrFrom ?? "Error";
+		const stderrFrom = options.stderrFrom ?? "All";
 		return Logger.make(({ fiber, logLevel, message }) => {
 			const console = fiber.getRef(Console.Console);
 			(fiber.getRef(References.LogToStderr) || LogLevel.isGreaterThanOrEqualTo(logLevel, stderrFrom) ? console.error : console.log)(render(message));

package/CliRuntime.js

@@ -1,6 +1,14 @@
-import { Cause, Effect, Runtime } from "effect";
+import { isExitCode } from "./internal/isExitCode.js";
+import { CliExit } from "./CliExit.js";
+import { CliLogger } from "./CliLogger.js";
+import { ExitRequested } from "./internal/ExitRequested.js";
+import { Cause, Effect, MutableRef, Runtime } from "effect";
+import { CliError } from "effect/unstable/cli";
 
 //#region src/CliRuntime.ts
+const isShowHelp = (u) => CliError.isCliError(u) && u._tag === "ShowHelp";
+/** A `UserError` `Command.runWith` already printed: it sets the mark to `false` after rendering. */
+const isRenderedUserError = (u) => CliError.isCliError(u) && u._tag === "UserError" && Runtime.getErrorReported(u) === false;
 const toLines = (rendered) => typeof rendered === "string" ? [rendered] : rendered;
 /**
 * The error's own exit code when it carries one, otherwise the fallback.
@@ -70,6 +78,23 @@ const chooseExitCode = (error, fallback) => typeof error === "object" && error !
 * An **interrupt is left alone**: it is not a failure to report, and the
 * default teardown already maps an interrupt-only cause to `130`.
 *
+* A `CliError.ShowHelp` is never rendered: `Command.runWith` already printed
+* the help text (and any parse errors) before re-failing with it, so
+* rendering it again would print nothing but a stray "Help requested" line.
+* A `ShowHelp` carrying errors is remapped to `usageExitCode` (default `64`,
+* BSD `EX_USAGE`); a bare `--help` or root invocation — `errors` empty —
+* keeps exit `0`. A `CliError.UserError` whose `Runtime.errorReported` mark
+* is `false` is likewise skipped: that is how `Command.runWith` leaves one it
+* already rendered through its `CliOutput` formatter. It exits with its own
+* `Runtime.errorExitCode` when it carries one, otherwise `usageExitCode`;
+* under runWith's `renderErrors: false` the mark stays set, and it renders
+* here like any other failure. Every other
+* error renders even when it already carries the reported mark — a gate
+* failure marked with `CliRuntime.reported` still prints its line. The
+* private `ExitRequested` sentinel `CliRuntime.main`
+* raises is likewise never rendered; it only carries the exit code a
+* successful program recorded through `CliExit`.
+*
 * @public
 */
 var CliRuntime = class CliRuntime {
@@ -81,12 +106,46 @@ var CliRuntime = class CliRuntime {
 	static reportFailures = (options = {}) => (effect) => effect.pipe(Effect.catchCause((cause) => {
 		if (Cause.hasInterruptsOnly(cause)) return Effect.failCause(cause);
 		const error = Cause.squash(cause);
+		if (error instanceof ExitRequested) return Effect.fail(error);
+		if (isShowHelp(error)) {
+			const code = error.errors.length > 0 ? options.usageExitCode ?? 64 : 0;
+			return Effect.fail(CliRuntime.reported(error, code));
+		}
+		if (isRenderedUserError(error)) return Effect.fail(CliRuntime.reported(error, chooseExitCode(error, options.usageExitCode ?? 64)));
 		const render = options.render ?? ((value) => String(value));
 		return Effect.gen(function* () {
 			for (const line of toLines(render(error))) yield* Effect.logError(line);
 			return yield* Effect.fail(CliRuntime.reported(error, chooseExitCode(error, options.exitCode)));
 		});
 	}));
+	/**
+	* Assemble a CLI program in the one order that reports every failure well.
+	*
+	* @remarks
+	* - `CliExit` is provided fresh, and a non-zero code after success becomes a
+	*   marked failure the teardown honours.
+	* - The platform layer is provided **inside** failure reporting, so a
+	*   layer-build failure (`HOME` unset, say) renders as one line with the
+	*   fallback code rather than escaping to the runtime's stack trace.
+	* - The logger is provided **outermost**, so it is present whichever branch
+	*   fails.
+	*
+	* You still call your platform's runner:
+	*
+	* @example
+	* ```ts
+	* NodeRuntime.runMain(
+	*   CliRuntime.main(Command.run(root, { version }), { platform: NodeServices.layer, exitCode: 3 }),
+	* )
+	* ```
+	*/
+	static main = (program, options) => Effect.gen(function* () {
+		yield* 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}`));
+		if (code !== 0) return yield* Effect.fail(new ExitRequested(code));
+	}).pipe(Effect.provide(CliExit.layer), Effect.provide(options.platform), CliRuntime.reportFailures(options), Effect.provide(options.logger ?? CliLogger.layer()));
 	static reported(error, exitCode = 1) {
 		const marked = error instanceof Error ? error : new Error(String(error));
 		return Object.assign(marked, {

package/CliTest.js

@@ -0,0 +1,79 @@
+import { Effect, FileSystem, Path, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+//#region src/CliTest.ts
+const text = (stream) => Stream.mkString(Stream.decodeText(stream));
+/**
+* Spawn a built CLI bin hermetically and read its exit code and streams as data.
+*
+* @public
+*/
+var CliTest = class {
+	constructor() {}
+	/**
+	* A scoped temp directory with a fresh `HOME` and XDG tree, `NO_COLOR=1`,
+	* and the `PATH` you pass — the host environment is never inherited.
+	*
+	* @remarks
+	* Each call mints a fresh temp directory; bind the result to a `const`
+	* within one test rather than calling this more than once per assertion.
+	*/
+	static sandbox = (options) => Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const root = yield* fs.makeTempDirectoryScoped({ prefix: "effected-cli-test-" });
+		const home = path.join(root, "home");
+		const xdg = {
+			XDG_CONFIG_HOME: path.join(home, ".config"),
+			XDG_DATA_HOME: path.join(home, ".local", "share"),
+			XDG_STATE_HOME: path.join(home, ".local", "state"),
+			XDG_CACHE_HOME: path.join(home, ".cache")
+		};
+		for (const dir of Object.values(xdg)) yield* fs.makeDirectory(dir, { recursive: true });
+		return {
+			root,
+			home,
+			env: {
+				HOME: home,
+				...xdg,
+				PATH: options.path,
+				NO_COLOR: "1"
+			}
+		};
+	});
+	/**
+	* Run `execPath bin ...args`; a non-zero exit is returned, never failed.
+	*
+	* @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
+	* default `"pipe"` stdio, which stays open until something writes to and
+	* ends it.
+	*/
+	static run = (bin, args, options) => Effect.scoped(Effect.gen(function* () {
+		const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+		const command = ChildProcess.make(options.execPath, [bin, ...args], {
+			cwd: options.cwd ?? options.sandbox.root,
+			env: {
+				...options.sandbox.env,
+				...options.env
+			},
+			stdin: options.stdin === void 0 || options.stdin === "" ? Stream.empty : Stream.make(new TextEncoder().encode(options.stdin))
+		});
+		const handle = yield* spawner.spawn(command);
+		const [stdout, stderr, exitCode] = yield* Effect.all([
+			text(handle.stdout),
+			text(handle.stderr),
+			handle.exitCode
+		], { concurrency: "unbounded" });
+		return {
+			exitCode: Number(exitCode),
+			stdout,
+			stderr
+		};
+	}));
+};
+
+//#endregion
+export { CliTest };

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. `SchemaIssueRenderer` and `ConfigIssueRenderer` turn issue trees into `unknown key at groups.g.rulesetz`.
+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.
 
 > **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
@@ -48,12 +48,13 @@ All `@effected/*` packages are ESM-only: the exports maps publish only `import`
 ```ts
 import { CliLogger, CliRuntime } from "@effected/cli";
 import { NodeRuntime } from "@effect/platform-node";
-import { Effect, Layer } from "effect";
+import { Console, Effect, Layer } from "effect";
 
 declare const AppLive: Layer.Layer<never>;
 
 const program = Effect.gen(function* () {
-  yield* Effect.log("building 3 packages");
+  yield* Effect.logInfo("building 3 packages"); // a diagnostic, not the product
+  yield* Console.log("build.json contents");    // the program's actual output
   yield* Effect.logError("nothing to build");
 });
 
@@ -62,9 +63,10 @@ const program = Effect.gen(function* () {
 const MainLive = Layer.mergeAll(AppLive, CliLogger.layer());
 
 NodeRuntime.runMain(program.pipe(CliRuntime.reportFailures(), Effect.provide(MainLive)));
-// stdout: building 3 packages
+// stdout: build.json contents
+// stderr: building 3 packages
 // stderr: nothing to build
-// No timestamp, no level, no fiber id — and the diagnostic line never lands on stdout.
+// No timestamp, no level, no fiber id — and stdout carries only what Console.log wrote.
 ```
 
 Rendering a bad config into something actionable:
@@ -96,12 +98,63 @@ ConfigValidationError: Config validation failed at "/home/me/.config/app/config.
   Missing key at variables.keep.resolved
 ```
 
+Print-then-`reported` is for a program run **without** `CliRuntime.main` or `reportFailures`. Under either, do not print the failure yourself: `reportFailures` renders every error except a `ShowHelp`, a `CliError.UserError` whose reported mark is `false` (one `Command.runWith` already printed, or one you marked with `reported`) and the `CliExit` sentinel, so it would print twice. Fail with the error and put the multi-line rendering in the `render` option instead — see "Rendering a multi-line failure" in the [advanced guide](https://effected.spencerbeg.gs/cli/advanced#rendering-a-multi-line-failure).
+
+## Putting it together
+
+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:
+
+```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";
+
+const findProblems = (strict: boolean): ReadonlyArray<string> =>
+  strict ? ["missing changeset", "unpinned dependency"] : ["missing changeset"];
+
+const check = Command.make("check", { strict: Flag.Boolean("strict").pipe(Flag.withDefault(false)) }, (config) =>
+  Effect.gen(function* () {
+    const problems = findProblems(config.strict);
+    for (const problem of problems) yield* Console.log(problem);
+
+    // Findings, not a crash: the handler still SUCCEEDS. CliExit.set records
+    // the code CliRuntime.main turns into a real exit once the program ends.
+    if (problems.length > 0) yield* CliExit.set(1);
+  }),
+);
+
+// Satisfies Command.Environment (Command.run needs it) AND feeds Stdio to
+// CliColor.formatterLayer, so help text, parse errors and rendered output
+// never disagree about whether colour is on.
+const Platform = CliColor.formatterLayer().pipe(Layer.provideMerge(NodeServices.layer));
+
+// CliRuntime.main provides a fresh CliExit, the platform layer inside failure
+// reporting, and the logger outermost — do NOT provide CliExit.layer here
+// yourself, or CliExit.set writes to a second, unread cell and `check`
+// silently exits 0.
+NodeRuntime.runMain(CliRuntime.main(Command.run(check, { version: "1.0.0" }), { platform: Platform }));
+```
+
+```bash
+$ node check.js
+missing changeset
+$ echo $?
+1
+```
+
 ## Features
 
-- `CliLogger.layer(options?)` — replaces the default logger with plain lines, routing `Error` and above to stderr. The threshold is the `stderrFrom` option, compared ordinally, so a level added upstream lands on the right stream without a change here.
+- `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.
-- `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`.
+- `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.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.
+- `CliColor.formatterLayer(overrides?)` — core's `CliOutput.Formatter`, coloured by the same decision as `CliColor.enabled`.
 - `SchemaIssueRenderer.render(issue)` — a `SchemaIssue` tree becomes one line per rejected value.
 - `ConfigIssueRenderer.render(error)` — the same rendering, reading `issue` off a `ConfigValidationError`.
 
@@ -110,6 +163,40 @@ Two behaviours worth knowing before you rely on them:
 - `CliLogger` honours `References.LogToStderr` as a **one-way** override — it can force everything to stderr, and can never move an error onto stdout.
 - `CliRuntime` keeps an exit code the error already carries via `Runtime.errorExitCode`; the `exitCode` option is a fallback, not an override. An interrupt is left alone.
 
+## Testing
+
+`@effected/cli/testing` is a separate entrypoint — importing `@effected/cli`
+never pulls it in — for spawning a **built** bin hermetically and reading its
+exit code and streams as data:
+
+```ts
+import { CliTest } from "@effected/cli/testing";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import { Effect } from "effect";
+
+describe("check", () => {
+  it.effect("exits 1 when it finds a problem", () =>
+    Effect.gen(function* () {
+      const sandbox = yield* CliTest.sandbox({ path: process.env.PATH ?? "" });
+      const result = yield* CliTest.run("./dist/check.js", ["--strict"], {
+        sandbox,
+        execPath: process.execPath,
+      });
+      assert.strictEqual(result.exitCode, 1);
+      assert.include(result.stdout, "missing changeset");
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+  );
+});
+```
+
+`CliTest.sandbox({ path })` mints a scoped temp directory with a fresh `HOME`
+and `XDG_{CONFIG,DATA,STATE,CACHE}_HOME`, `NO_COLOR: "1"`, and the `path` you
+pass as `PATH` — the host environment is never inherited. `CliTest.run` never
+leaves `stdin` as an open pipe: when you omit it, or pass `""`, the child
+receives an already-ended empty input, so a stdin-reading bin cannot hang the
+test.
+
 ## License
 
 [MIT](LICENSE)

package/index.d.ts

@@ -1,5 +1,122 @@
-import { Effect, Layer, LogLevel, Logger } from "effect";
+import { 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
+/**
+ * Whether a CLI's output should carry ANSI colour, decided once and shared by
+ * everything that renders — help text, error output, and any rendered result.
+ *
+ * @remarks
+ * Follows the no-color.org rule: colour is off when stdout is not a
+ * terminal, or when `NO_COLOR` is set to any **non-empty** value — an empty
+ * `NO_COLOR=""` does not disable colour. `FORCE_COLOR` is ignored, matching
+ * core's own formatter. The environment is read through the ambient
+ * `ConfigProvider`, never `process`, so a test swaps it with
+ * `Effect.provideService(ConfigProvider.ConfigProvider, ...)`. The kit's
+ * default providers (`fromEnv`, `fromUnknown`) already treat an empty
+ * `NO_COLOR` as unset, so the explicit `set === ""` check exists for a
+ * provider constructed with `{ preserveEmptyStrings: true }`.
+ *
+ * @public
+ */
+export declare class CliColor {
+  private constructor();
+  /**
+   * The decision, for passing to a pure renderer as a plain boolean.
+   *
+   * @public
+   */
+  static readonly enabled: Effect.Effect<boolean, never, Stdio.Stdio>;
+  /**
+   * Core's default `CliOutput.Formatter`, coloured by the same decision as
+   * {@link CliColor.enabled}, so help text, parse errors and rendered
+   * output never disagree on whether colour is on.
+   *
+   * @remarks
+   * `overrides` replaces individual methods of the default formatter — for
+   * example `formatVersion`, to append a "via `<carrier>`" line without
+   * losing the other defaults. Each call mints a fresh layer; bind the
+   * result to a `const` or the decision is re-read every time it is
+   * provided.
+   *
+   * The `never` in its output does not mean it installs nothing.
+   * `CliOutput.Formatter` is a `Context.Reference`, whose key type is
+   * `never`, so this layer sets the formatter reference rather than
+   * providing a service. Every command it is provided to renders with the
+   * formatter it sets, and without it they fall back to core's default
+   * formatter.
+   *
+   * @public
+   */
+  static readonly formatterLayer: (overrides?: Partial<CliOutput.Formatter>) => Layer.Layer<never, never, Stdio.Stdio>;
+}
+//#endregion
+//#region src/CliExit.d.ts
+/**
+ * The shape behind {@link CliExit}.
+ *
+ * @public
+ */
+interface CliExitShape {
+  /** The highest exit code recorded during the run; `0` until one is set. */
+  readonly code: MutableRef.MutableRef<number>;
+}
+declare const CliExit_base: Context.ServiceClass<CliExit, "@effected/cli/CliExit", CliExitShape>;
+/**
+ * The exit code a successful run wants, for commands whose findings are a
+ * result rather than a failure (a linter that found problems, say).
+ *
+ * @remarks
+ * Findings are not a failure — a JSON `tapError` must not fire, and the
+ * handler must return normally — yet the process must exit non-zero. Writing
+ * `process.exitCode` works only because Node's `runMain` skips
+ * `process.exit(0)` on success; `process.exit(n)` in a handler skips every
+ * finalizer. {@link CliRuntime.main} reads this cell after the program
+ * succeeds and turns a non-zero code into a marked failure the runtime's
+ * teardown honours, on any runtime, with finalizers intact.
+ *
+ * A `Service`, not a `Reference`: forgetting `CliRuntime.main` is a type error,
+ * never a silently ignored global.
+ *
+ * @public
+ */
+export declare class CliExit extends CliExit_base {
+  /**
+   * A fresh cell at `0`; `CliRuntime.main` provides it, and tests provide it
+   * directly.
+   *
+   * @remarks
+   * Every provide mints a new cell. Layers memoize by reference across
+   * `Effect.provide` calls, so without `Layer.fresh` a second provide of this
+   * layer anywhere in the program — a nested `CliRuntime.main`, a test
+   * helper — would silently share the first run's cell and inherit its code.
+   *
+   * A program run under `CliRuntime.main` must NOT provide `CliExit.layer`
+   * itself: `main` already provides one, and a second provide mints a second,
+   * unrelated cell that `main` never reads back, so `CliExit.set` calls made
+   * against it are silently discarded and the run exits `0`.
+   */
+  static readonly layer: Layer.Layer<CliExit>;
+  /**
+   * Record an exit code; the highest code set during the run wins.
+   *
+   * @remarks
+   * Highest-wins, not last-wins, so a later "clean" step cannot quietly
+   * downgrade an earlier finding's code.
+   *
+   * The code must be an integer in `0..255` — the range a POSIX exit status
+   * can carry. Anything else dies as a defect naming the value: `256` would
+   * wrap to exit `0` and silently pass a run with findings, and a fraction
+   * such as `1.5` makes `process.exit` throw `ERR_OUT_OF_RANGE` after the
+   * program has finished.
+   *
+   * The code only applies to a run that **succeeds**. A program failure beats
+   * findings: when the program fails, `CliRuntime.main` never reads this
+   * cell, and the failure's own exit code (or the `exitCode` fallback) wins.
+   */
+  static readonly set: (code: number) => Effect.Effect<void, never, CliExit>;
+}
+//#endregion
 //#region src/CliLogger.d.ts
 /**
  * How a log record is turned into a line.
@@ -16,8 +133,14 @@ interface CliLoggerOptions {
    */
   readonly render?: ((message: unknown) => string) | undefined;
   /**
-   * The level at and above which output goes to stderr. Defaults to `"Error"`,
-   * so `Error` and `Fatal` are diagnostics and everything else is output.
+   * The level at and above which output goes to stderr. Defaults to `"All"`,
+   * so every log level is a diagnostic and stdout carries only what the
+   * program writes with `Console.log`.
+   *
+   * @remarks
+   * Pass `"Error"` to restore the old split, for a tool whose output *is*
+   * its log lines rather than a separate document written with
+   * `Console.log`.
    */
   readonly stderrFrom?: LogLevel.LogLevel | undefined;
 }
@@ -56,16 +179,24 @@ interface CliLoggerOptions {
  * @example
  * ```ts
  * import { CliLogger } from "@effected/cli"
- * import { Effect } from "effect"
+ * import { Console, Effect } from "effect"
  *
  * const program = Effect.gen(function* () {
- *   yield* Effect.log("synced 3 repos")   // stdout, no timestamp
- *   yield* Effect.logError("one failed")  // stderr
+ *   yield* Effect.log("synced 3 repos")    // stderr, no timestamp — a diagnostic
+ *   yield* Console.log("3 repos synced")   // stdout — the program's actual output
+ *   yield* Effect.logError("one failed")   // stderr
  * })
  *
  * program.pipe(Effect.provide(CliLogger.layer()))
  * ```
  *
+ * @remarks
+ * `stderrFrom` defaults to `"All"`: a CLI's stdout is its product, so every
+ * log level is a diagnostic unless a consumer narrows the threshold. Write
+ * program output with `Console.log`, never `Effect.log`. Pass
+ * `stderrFrom: "Error"` for a tool whose output *is* its log lines. This is
+ * a breaking change on the 0.x line (#716).
+ *
  * @public
  */
 export declare class CliLogger {
@@ -111,9 +242,40 @@ interface ReportFailuresOptions {
    *
    * @remarks
    * An error carrying `Runtime.errorExitCode` keeps its own; this is only the
-   * fallback, and it defaults to `1`.
+   * fallback, and it defaults to `1`. Pass an integer in `0..255`, the range a
+   * POSIX exit status can carry — `256` wraps to `0` and passes a failed run.
    */
   readonly exitCode?: number | undefined;
+  /**
+   * The exit code for a usage error: a `ShowHelp` carrying parse errors, or a
+   * `CliError.UserError` `Command.runWith` already printed.
+   *
+   * @remarks
+   * Defaults to `64` (BSD `EX_USAGE`); pass an integer in `0..255`. A
+   * `ShowHelp` with no errors — a bare root invocation, or `--help` — always
+   * exits `0`. A `UserError` that carries its own `Runtime.errorExitCode` —
+   * one marked with `CliRuntime.reported(error, 3)` — keeps that code instead.
+   *
+   * Keep `Command.runWith`'s default `renderErrors`: with `renderErrors: false`
+   * runWith prints no parse errors and `reportFailures` never renders a
+   * `ShowHelp`, so a parse error would exit with this code having printed
+   * nothing on stderr.
+   */
+  readonly usageExitCode?: number | undefined;
+}
+/**
+ * Options for {@link CliRuntime.main}.
+ *
+ * @public
+ */
+interface MainOptions<RP, EP> extends ReportFailuresOptions {
+  /**
+   * The platform layer, usually `NodeServices.layer` or an app platform built
+   * on it. Passed in so this package never imports a platform.
+   */
+  readonly platform: Layer.Layer<RP, EP>;
+  /** The logger, provided outermost. Defaults to `CliLogger.layer()`. */
+  readonly logger?: Layer.Layer<never> | undefined;
 }
 /**
  * Report a CLI program's failures through the program's own logger.
@@ -173,6 +335,23 @@ interface ReportFailuresOptions {
  * An **interrupt is left alone**: it is not a failure to report, and the
  * default teardown already maps an interrupt-only cause to `130`.
  *
+ * A `CliError.ShowHelp` is never rendered: `Command.runWith` already printed
+ * the help text (and any parse errors) before re-failing with it, so
+ * rendering it again would print nothing but a stray "Help requested" line.
+ * A `ShowHelp` carrying errors is remapped to `usageExitCode` (default `64`,
+ * BSD `EX_USAGE`); a bare `--help` or root invocation — `errors` empty —
+ * keeps exit `0`. A `CliError.UserError` whose `Runtime.errorReported` mark
+ * is `false` is likewise skipped: that is how `Command.runWith` leaves one it
+ * already rendered through its `CliOutput` formatter. It exits with its own
+ * `Runtime.errorExitCode` when it carries one, otherwise `usageExitCode`;
+ * under runWith's `renderErrors: false` the mark stays set, and it renders
+ * here like any other failure. Every other
+ * error renders even when it already carries the reported mark — a gate
+ * failure marked with `CliRuntime.reported` still prints its line. The
+ * private `ExitRequested` sentinel `CliRuntime.main`
+ * raises is likewise never rendered; it only carries the exit code a
+ * successful program recorded through `CliExit`.
+ *
  * @public
  */
 export declare class CliRuntime {
@@ -182,6 +361,28 @@ export declare class CliRuntime {
    * and the no-double-report mark.
    */
   static readonly reportFailures: (options?: ReportFailuresOptions) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, Error, R>;
+  /**
+   * Assemble a CLI program in the one order that reports every failure well.
+   *
+   * @remarks
+   * - `CliExit` is provided fresh, and a non-zero code after success becomes a
+   *   marked failure the teardown honours.
+   * - The platform layer is provided **inside** failure reporting, so a
+   *   layer-build failure (`HOME` unset, say) renders as one line with the
+   *   fallback code rather than escaping to the runtime's stack trace.
+   * - The logger is provided **outermost**, so it is present whichever branch
+   *   fails.
+   *
+   * You still call your platform's runner:
+   *
+   * @example
+   * ```ts
+   * NodeRuntime.runMain(
+   *   CliRuntime.main(Command.run(root, { version }), { platform: NodeServices.layer, exitCode: 3 }),
+   * )
+   * ```
+   */
+  static readonly main: <A, E, R, RP, EP>(program: Effect.Effect<A, E, R>, options: MainOptions<RP, EP>) => Effect.Effect<void, Error, Exclude<Exclude<R, CliExit>, RP>>;
   /**
    * Mark an error as already reported, carrying an exit code.
    *
@@ -190,6 +391,21 @@ export declare class CliRuntime {
    * command that prints its own diagnostics, say — needs the same two marks
    * and should not have to rediscover the inverted polarity.
    *
+   * Under {@link CliRuntime.main} or {@link CliRuntime.reportFailures}, do NOT
+   * print the failure yourself before failing with it: `reportFailures`
+   * renders every error except a `ShowHelp` and a `CliError.UserError` whose
+   * reported mark is `false`, so it would print twice. Fail with the marked
+   * error and put any multi-line rendering in the `render` option instead. The
+   * mark matters for a program run WITHOUT `reportFailures`, where it keeps the
+   * runtime from reporting a failure the program already printed.
+   *
+   * 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. `reportFailures` cannot tell a `UserError` that
+   * `Command.runWith` printed from one marked here: both carry the same `false`
+   * mark. It does keep the code you pass: `reported(userError, 3)` exits `3`,
+   * not `usageExitCode`.
+   *
    * The marks are added in place, so a typed error comes back as its own
    * type: the `E` overload returns the very instance it was given, and a
    * program failing with it keeps `catchTags` narrowing downstream without a
@@ -327,5 +543,5 @@ export declare class SchemaIssueRenderer {
   static readonly render: (issue: unknown) => ReadonlyArray<string>;
 }
 //#endregion
-export type { CliLoggerOptions, ReportFailuresOptions };
+export type { CliExitShape, CliLoggerOptions, MainOptions, ReportFailuresOptions };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,6 +1,8 @@
+import { CliColor } from "./CliColor.js";
+import { CliExit } from "./CliExit.js";
 import { CliLogger } from "./CliLogger.js";
 import { CliRuntime } from "./CliRuntime.js";
 import { ConfigIssueRenderer } from "./ConfigIssueRenderer.js";
 import { SchemaIssueRenderer } from "./SchemaIssueRenderer.js";
 
-export { CliLogger, CliRuntime, ConfigIssueRenderer, SchemaIssueRenderer };
+export { CliColor, CliExit, CliLogger, CliRuntime, ConfigIssueRenderer, SchemaIssueRenderer };

package/internal/ExitRequested.js

@@ -0,0 +1,22 @@
+import { Runtime } from "effect";
+
+//#region src/internal/ExitRequested.ts
+/**
+* The failure `CliRuntime.main` raises when a successful program recorded a
+* non-zero exit code through `CliExit`. Private: nothing outside this package
+* constructs or matches it, and `reportFailures` never renders it.
+*
+* @internal
+*/
+var ExitRequested = class extends Error {
+	[Runtime.errorReported] = false;
+	[Runtime.errorExitCode];
+	constructor(code) {
+		super(`exit ${code}`);
+		this.name = "ExitRequested";
+		this[Runtime.errorExitCode] = code;
+	}
+};
+
+//#endregion
+export { ExitRequested };

package/internal/isExitCode.js

@@ -0,0 +1,12 @@
+//#region src/internal/isExitCode.ts
+/**
+* Whether `code` is an exit status a POSIX process can carry: an integer in
+* `0..255`. `NaN`, fractions and out-of-range values all fail — a relational
+* check alone would admit `NaN`.
+*
+* @internal
+*/
+const isExitCode = (code) => Number.isInteger(code) && code >= 0 && code <= 255;
+
+//#endregion
+export { isExitCode };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/cli",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"private": false,
 	"description": "The boundary layer of an effect/unstable/cli program: plain CLI output, failure reporting, and schema-issue rendering",
 	"keywords": [
@@ -32,6 +32,11 @@
 			"import": "./index.js",
 			"default": "./index.js"
 		},
+		"./testing": {
+			"types": "./testing.d.ts",
+			"import": "./testing.js",
+			"default": "./testing.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {

package/testing.d.ts

@@ -0,0 +1,94 @@
+import { Effect, FileSystem, Path, PlatformError, Scope } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+//#region src/CliTest.d.ts
+/**
+ * A hermetic temp directory minted by {@link CliTest.sandbox}, removed when its
+ * scope closes.
+ *
+ * @public
+ */
+interface Sandbox {
+  /** The temp directory itself; the default working directory of {@link CliTest.run}. */
+  readonly root: string;
+  /** The fresh `HOME` inside `root`; the XDG base directories live under it. */
+  readonly home: string;
+  /**
+   * The complete child environment: `HOME`, the four `XDG_*_HOME` variables,
+   * the injected `PATH` and `NO_COLOR=1`. Nothing is inherited from the host.
+   */
+  readonly env: Readonly<Record<string, string>>;
+}
+/**
+ * How {@link CliTest.run} spawns a bin.
+ *
+ * @public
+ */
+interface RunOptions {
+  /** The sandbox whose environment and root the child runs in. */
+  readonly sandbox: Sandbox;
+  /** The node binary — pass `process.execPath` from the test file, never a PATH lookup. */
+  readonly execPath: string;
+  /** The child's working directory. Defaults to the sandbox `root`. */
+  readonly cwd?: string | undefined;
+  /**
+   * Extra environment variables, merged over the sandbox environment — the
+   * way to override `PATH` for one run.
+   */
+  readonly env?: Readonly<Record<string, string>> | undefined;
+  /**
+   * Text written to the child's stdin, which is then closed. Omitted or `""`,
+   * the child gets an already-ended empty input, never an open pipe.
+   */
+  readonly stdin?: string | undefined;
+}
+/**
+ * What a spawned bin did, as data: a non-zero exit is a result, not a failure.
+ *
+ * @public
+ */
+interface RunResult {
+  /** The child's exit code. */
+  readonly exitCode: number;
+  /** Everything the child wrote to stdout, decoded as UTF-8. */
+  readonly stdout: string;
+  /** Everything the child wrote to stderr, decoded as UTF-8. */
+  readonly stderr: string;
+}
+/**
+ * Spawn a built CLI bin hermetically and read its exit code and streams as data.
+ *
+ * @public
+ */
+export declare class CliTest {
+  private constructor();
+  /**
+   * A scoped temp directory with a fresh `HOME` and XDG tree, `NO_COLOR=1`,
+   * and the `PATH` you pass — the host environment is never inherited.
+   *
+   * @remarks
+   * Each call mints a fresh temp directory; bind the result to a `const`
+   * within one test rather than calling this more than once per assertion.
+   */
+  static readonly sandbox: (options: {
+    /**
+     * The `PATH` the child sees, passed explicitly because nothing else is
+     * inherited — `process.env.PATH` when the bin shells out to host tools,
+     * a narrower list to prove it does not.
+     */
+    readonly path: string;
+  }) => Effect.Effect<Sandbox, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Scope.Scope>;
+  /**
+   * Run `execPath bin ...args`; a non-zero exit is returned, never failed.
+   *
+   * @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
+   * default `"pipe"` stdio, which stays open until something writes to and
+   * ends it.
+   */
+  static readonly run: (bin: string, args: ReadonlyArray<string>, options: RunOptions) => Effect.Effect<RunResult, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
+}
+//#endregion
+export type { RunOptions, RunResult, Sandbox };
+//# sourceMappingURL=testing.d.ts.map

package/testing.js

@@ -0,0 +1,3 @@
+import { CliTest } from "./CliTest.js";
+
+export { CliTest };