@effected/cli 0.1.0

package/CliLogger.js

@@ -0,0 +1,83 @@
+import { Console, LogLevel, Logger, References } from "effect";
+
+//#region src/CliLogger.ts
+const defaultRender = (message) => Array.isArray(message) ? message.map(String).join(" ") : String(message);
+/**
+* A `Logger` that renders CLI output rather than service logs.
+*
+* @remarks
+* Effect's default logger emits `[00:33:56.619] INFO (#2): message`. That is
+* the right shape for a long-running service being scraped and the wrong one
+* for a tool a person is watching: the timestamp, level and fiber id are noise
+* in front of output a human is reading, and they make a formatted block — a
+* permissions table, a summary — unreadable.
+*
+* **This is not a preference, and it is not visible from the call site.** A
+* program that never installs a CLI logger looks correct in review and ships
+* timestamps to its users; the consumer this package was extracted from had it
+* missing for a day while its own docs claimed it existed.
+*
+* ## Why the `Console` reference, and not `Stdio`
+*
+* The obvious design — write through `Stdio`'s `stdout()` / `stderr()` sinks —
+* does not fit. `Logger.make` takes a **synchronous** callback and a `Sink`
+* write is an `Effect`: a logger cannot `yield*`.
+*
+* Writing to `process.stdout` would fit, and is what the consumer did first,
+* but it drags a platform assumption into a library and — the part that
+* actually matters — makes the stream split **untestable**, because asserting
+* it means monkey-patching a global inside a runner that is itself writing to
+* those streams.
+*
+* So this takes the path core's own `defaultLogger` takes: read the `Console`
+* off the fiber, synchronously. `Console.Console` is a public
+* `Context.Reference`, so it carries a default and never appears in `R`, and a
+* test swaps the reference instead of stubbing a global.
+*
+* @example
+* ```ts
+* import { CliLogger } from "@effected/cli"
+* import { Effect } from "effect"
+*
+* const program = Effect.gen(function* () {
+*   yield* Effect.log("synced 3 repos")   // stdout, no timestamp
+*   yield* Effect.logError("one failed")  // stderr
+* })
+*
+* program.pipe(Effect.provide(CliLogger.layer()))
+* ```
+*
+* @public
+*/
+var CliLogger = class CliLogger {
+	constructor() {}
+	/**
+	* The logger itself, for composing into an existing `Logger.layer` set.
+	*
+	* @remarks
+	* Prefer {@link CliLogger.layer}. Reach for this only when you are building
+	* the logger set yourself and want this one among several.
+	*/
+	static make = (options = {}) => {
+		const render = options.render ?? defaultRender;
+		const stderrFrom = options.stderrFrom ?? "Error";
+		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));
+		});
+	};
+	/**
+	* Replace the default logger with this one.
+	*
+	* @remarks
+	* `Logger.layer` **replaces** rather than merges, so nothing is emitted twice.
+	*
+	* Merge this into the layer you provide to the whole program rather than
+	* providing it beneath: merged, it also covers lines emitted during layer
+	* construction, which is exactly where a startup failure prints.
+	*/
+	static layer = (options = {}) => Logger.layer([CliLogger.make(options)]);
+};
+
+//#endregion
+export { CliLogger };

package/CliRuntime.js

@@ -0,0 +1,108 @@
+import { Cause, Effect, Runtime } from "effect";
+
+//#region src/CliRuntime.ts
+const toLines = (rendered) => typeof rendered === "string" ? [rendered] : rendered;
+/**
+* The error's own exit code when it carries one, otherwise the fallback.
+*
+* @remarks
+* `Runtime.getErrorExitCode` cannot serve alone here: it answers `1` both for
+* an error marked `1` and for an unmarked one, so an `exitCode` option would
+* silently override a deliberate `1`. Testing for the marker keeps "the error
+* chose its code" distinct from "nothing chose".
+*/
+const chooseExitCode = (error, fallback) => typeof error === "object" && error !== null && Runtime.errorExitCode in error ? Runtime.getErrorExitCode(error) : fallback ?? 1;
+/**
+* Report a CLI program's failures through the program's own logger.
+*
+* @remarks
+* ## The bug this exists to prevent
+*
+* A platform `runMain` reports an unhandled failure using Effect's **default**
+* logger. That logger sits **outside** the layers the program was provided —
+* `makeRunMain` composes its reporting `tapCause` around the already-provided
+* effect — so a program that carefully installs {@link CliLogger} still prints
+* its failures in the structured format that logger exists to replace, and
+* prints them on **stdout**, the one stream errors must not use.
+*
+* Nothing about the call site suggests this. The program looks correct, the
+* logger is installed, every success path is right, and only a failure reveals
+* it.
+*
+* ## Why a combinator, and not a `runMain`
+*
+* The fix has to happen **inside** the effect, before any `runMain` sees it. So
+* this is a combinator you apply to your program, and you still call your own
+* platform's runner:
+*
+* @example
+* ```ts
+* import { CliRuntime } from "@effected/cli"
+* import { NodeRuntime } from "@effect/platform-node"
+* import { Effect } from "effect"
+*
+* NodeRuntime.runMain(program.pipe(CliRuntime.reportFailures(), Effect.provide(MainLive)))
+* ```
+*
+* Wrapping `runMain` itself would drag a platform choice into a library that
+* has no business making one, and would make this package unusable from Bun or
+* Deno for no gain.
+*
+* ## What it does with the failure
+*
+* Renders it through the ambient logger, then **re-fails with a marked error**
+* so the runtime still sees a failure — the exit code is the runtime's to set,
+* and swallowing the failure would make a broken run exit `0`.
+*
+* The marks are core's own, and they are what make this work without a platform
+* import:
+*
+* - `Runtime.errorExitCode` — `defaultTeardown` takes the squashed error's
+*   value as the process exit code. An error that already carries one **keeps
+*   it**: that was a deliberate choice by whatever raised it, and flattening
+*   every failure to a single code would discard it.
+* - `Runtime.errorReported` — set to `false`, which suppresses the runtime's own
+*   duplicate report. **The polarity is inverted relative to the name**: the
+*   marker means "should this be reported", so the intuitive
+*   `errorReported: true` — "I have reported it, stay quiet" — produces exactly
+*   the double report it was meant to prevent.
+*
+* An **interrupt is left alone**: it is not a failure to report, and the
+* default teardown already maps an interrupt-only cause to `130`.
+*
+* @public
+*/
+var CliRuntime = class CliRuntime {
+	constructor() {}
+	/**
+	* Catch, render through the ambient logger, and re-fail with the exit code
+	* and the no-double-report mark.
+	*/
+	static reportFailures = (options = {}) => (effect) => effect.pipe(Effect.catchCause((cause) => {
+		if (Cause.hasInterruptsOnly(cause)) return Effect.failCause(cause);
+		const error = Cause.squash(cause);
+		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)));
+		});
+	}));
+	/**
+	* Mark an error as already reported, carrying an exit code.
+	*
+	* @remarks
+	* Exported because a program that reports a failure itself — a validation
+	* command that prints its own diagnostics, say — needs the same two marks
+	* and should not have to rediscover the inverted polarity.
+	*/
+	static reported = (error, exitCode = 1) => {
+		const marked = error instanceof Error ? error : new Error(String(error));
+		return Object.assign(marked, {
+			[Runtime.errorReported]: false,
+			[Runtime.errorExitCode]: exitCode
+		});
+	};
+};
+
+//#endregion
+export { CliRuntime };

package/ConfigIssueRenderer.js

@@ -0,0 +1,77 @@
+import { formatIssue } from "./internal/format.js";
+
+//#region src/ConfigIssueRenderer.ts
+/**
+* Render a `@effected/config-file` validation failure.
+*
+* @remarks
+* `ConfigValidationError` carries the structured `issue` tree rather than a
+* string, which is the right design and leaves the consumer holding a tree it
+* has to turn into sentences. This is that step, and it is the same treatment
+* {@link SchemaIssueRenderer} gives a bare issue.
+*
+* **This module is the only thing in the package that references
+* `@effected/config-file`, deliberately.** The peer is declared optional, and
+* an optional peer whose import is reachable from a shared module is not
+* optional — it is a crash for every consumer who took the manifest at its word
+* and did not install it. So nothing else in this package imports this module;
+* only the entrypoint re-exports it, and the shared rendering lives in
+* `internal/format`.
+*
+* The import is additionally `import type`, so it is erased at build time and
+* the runtime reach is **zero** — a consumer without `@effected/config-file`
+* installed can import this module and call `render` on any value without the
+* resolver ever being asked for the package.
+*
+* ## Why this and not just the error's message
+*
+* `ConfigValidationError.message` names the file. It does not name the value,
+* and the difference is the whole diagnostic: a consumer that printed only the
+* message told users "your config is invalid, run the doctor command", and the
+* doctor command — which guessed from a hand-written list of known keys — could
+* only ever find a *misspelling*. A wrongly **shaped** value left the two
+* commands pointing at each other and neither saying what was wrong.
+*
+* @example
+* ```ts
+* import { ConfigIssueRenderer } from "@effected/cli"
+* import { Effect } from "effect"
+*
+* const load = configFile.load.pipe(
+*   Effect.catchTag("ConfigValidationError", (error) =>
+*     Effect.gen(function* () {
+*       yield* Effect.logError(String(error))
+*       for (const line of ConfigIssueRenderer.render(error)) yield* Effect.logError(`  ${line}`)
+*     }),
+*   ),
+* )
+* ```
+*
+* @public
+*/
+var ConfigIssueRenderer = class {
+	constructor() {}
+	/**
+	* One line per rejected value.
+	*
+	* @remarks
+	* Takes the **error**, not its `issue`, because that is what a `catchTag`
+	* hands you and because `issue` is typed `Schema.Defect` — reaching into it
+	* at every call site is exactly the ceremony this removes.
+	*
+	* The parameter is the **typed** error rather than `unknown`. An earlier
+	* draft wrote `ConfigValidationError | unknown` to be accommodating, which
+	* collapses to plain `unknown` in TypeScript — so it accepted anything, said
+	* nothing, and left the type import in the `.d.ts` earning nothing. Inside
+	* `Effect.catchTag("ConfigValidationError", …)` the error is already this
+	* type, which is where this is called.
+	*
+	* It still cannot throw on a malformed value: the issue tree is validated by
+	* a guard before it is read, so a renderer on an error path never becomes the
+	* reason a program dies.
+	*/
+	static render = (error) => formatIssue(error?.issue);
+};
+
+//#endregion
+export { ConfigIssueRenderer };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @effected/cli
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fcli?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![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`.
+
+> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
+> development against a single pinned Effect v4 beta. Packages graduate to
+> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
+> exactly the ones the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/cli
+
+Everything here shares one property: **you only discover you needed it by shipping bad output to a person.** None of it fails a type-check, a test, or a review of the code in isolation.
+
+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.
+
+## Install
+
+```bash
+npm install @effected/cli effect
+```
+
+```bash
+pnpm add @effected/cli effect
+```
+
+Requires Node.js >=24.11.0. `effect` v4 is a peer dependency.
+
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
+
+`@effected/config-file` is an **optional** peer, needed only for `ConfigIssueRenderer`. It lives in its own module and is imported as a type, so nothing at runtime reaches for it.
+
+## Quick start
+
+```ts
+import { CliLogger, CliRuntime } from "@effected/cli";
+import { NodeRuntime } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+
+declare const AppLive: Layer.Layer<never>;
+
+const program = Effect.gen(function* () {
+  yield* Effect.log("building 3 packages");
+  yield* Effect.logError("nothing to build");
+});
+
+// Merged, not provided beneath: this way it also covers lines emitted during
+// layer construction, which is exactly where a startup failure prints.
+const MainLive = Layer.mergeAll(AppLive, CliLogger.layer());
+
+NodeRuntime.runMain(program.pipe(CliRuntime.reportFailures(), Effect.provide(MainLive)));
+// stdout: building 3 packages
+// stderr: nothing to build
+// No timestamp, no level, no fiber id — and the diagnostic line never lands on stdout.
+```
+
+Rendering a bad config into something actionable:
+
+```ts
+import { CliRuntime, ConfigIssueRenderer } from "@effected/cli";
+import { Effect } from "effect";
+
+configFile.load.pipe(
+  Effect.catchTag("ConfigValidationError", (error) =>
+    Effect.gen(function* () {
+      yield* Effect.logError(String(error));
+      for (const line of ConfigIssueRenderer.render(error)) yield* Effect.logError(`  ${line}`);
+
+      // Re-fail, or the handler SUCCEEDS and a CLI exits 0 on invalid config.
+      // `reported` carries the exit code and the mark that stops the runtime
+      // printing the same failure a second time.
+      return yield* Effect.fail(CliRuntime.reported(error));
+    }),
+  ),
+);
+```
+
+```text
+ConfigValidationError: Config validation failed at "/home/me/.config/app/config.toml"
+  unknown key at variables.keep.KEEP_ME
+  Missing key at variables.keep.file
+  Missing key at variables.keep.value
+  Missing key at variables.keep.resolved
+```
+
+## 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.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.
+- `SchemaIssueRenderer.render(issue)` — a `SchemaIssue` tree becomes one line per rejected value.
+- `ConfigIssueRenderer.render(error)` — the same rendering, reading `issue` off a `ConfigValidationError`.
+
+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.
+
+## License
+
+[MIT](LICENSE)

package/SchemaIssueRenderer.js

@@ -0,0 +1,51 @@
+import { formatIssue } from "./internal/format.js";
+
+//#region src/SchemaIssueRenderer.ts
+/**
+* Turn a `SchemaIssue` tree into lines a user can act on.
+*
+* @remarks
+* A decode failure arrives as a structured tree; a person needs
+* `unknown key at groups.g.cleanup.rulesetz`.
+*
+* **Core already ships the formatters this wraps, and they are effectively
+* undiscoverable.** They live on `SchemaIssue` rather than `SchemaError` or
+* `Schema`, they are named `makeFormatter*` rather than anything containing
+* "render" or "format issue", and `SchemaError.message` does not use them — so
+* the obvious probe, printing the error, hints at nothing. Two engineers
+* searched for two rounds and concluded core had none. This export exists to
+* end that search, and the one phrasing override is a bonus rather than the
+* point.
+*
+* @example
+* ```ts
+* import { SchemaIssueRenderer } from "@effected/cli"
+* import { Effect, Schema } from "effect"
+*
+* const result = Schema.decodeUnknownEffect(MySchema)(input, {
+*   onExcessProperty: "error",
+*   errors: "all",
+* })
+*
+* const reported = result.pipe(
+*   Effect.catchTag("SchemaError", (error) =>
+*     Effect.forEach(SchemaIssueRenderer.render(error.issue), (line) => Effect.logError(`  ${line}`)),
+*   ),
+* )
+* ```
+*
+* @public
+*/
+var SchemaIssueRenderer = class {
+	constructor() {}
+	/**
+	* One line per rejected value, deepest path last.
+	*
+	* @param issue - a `SchemaIssue` tree, or any value
+	* @returns the lines, or empty when `issue` is not an issue tree
+	*/
+	static render = (issue) => formatIssue(issue);
+};
+
+//#endregion
+export { SchemaIssueRenderer };

package/index.d.ts

@@ -0,0 +1,317 @@
+import { Effect, Layer, LogLevel, Logger } from "effect";
+import { ConfigValidationError } from "@effected/config-file";
+//#region src/CliLogger.d.ts
+/**
+ * How a log record is turned into a line.
+ *
+ * @public
+ */
+interface CliLoggerOptions {
+  /**
+   * Render one message. Defaults to joining an array with spaces and
+   * `String`-ing anything else.
+   *
+   * @remarks
+   * An array arrives because `Effect.log("synced", 3, "repos")` is variadic.
+   */
+  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.
+   */
+  readonly stderrFrom?: LogLevel.LogLevel | undefined;
+}
+/**
+ * A `Logger` that renders CLI output rather than service logs.
+ *
+ * @remarks
+ * Effect's default logger emits `[00:33:56.619] INFO (#2): message`. That is
+ * the right shape for a long-running service being scraped and the wrong one
+ * for a tool a person is watching: the timestamp, level and fiber id are noise
+ * in front of output a human is reading, and they make a formatted block — a
+ * permissions table, a summary — unreadable.
+ *
+ * **This is not a preference, and it is not visible from the call site.** A
+ * program that never installs a CLI logger looks correct in review and ships
+ * timestamps to its users; the consumer this package was extracted from had it
+ * missing for a day while its own docs claimed it existed.
+ *
+ * ## Why the `Console` reference, and not `Stdio`
+ *
+ * The obvious design — write through `Stdio`'s `stdout()` / `stderr()` sinks —
+ * does not fit. `Logger.make` takes a **synchronous** callback and a `Sink`
+ * write is an `Effect`: a logger cannot `yield*`.
+ *
+ * Writing to `process.stdout` would fit, and is what the consumer did first,
+ * but it drags a platform assumption into a library and — the part that
+ * actually matters — makes the stream split **untestable**, because asserting
+ * it means monkey-patching a global inside a runner that is itself writing to
+ * those streams.
+ *
+ * So this takes the path core's own `defaultLogger` takes: read the `Console`
+ * off the fiber, synchronously. `Console.Console` is a public
+ * `Context.Reference`, so it carries a default and never appears in `R`, and a
+ * test swaps the reference instead of stubbing a global.
+ *
+ * @example
+ * ```ts
+ * import { CliLogger } from "@effected/cli"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   yield* Effect.log("synced 3 repos")   // stdout, no timestamp
+ *   yield* Effect.logError("one failed")  // stderr
+ * })
+ *
+ * program.pipe(Effect.provide(CliLogger.layer()))
+ * ```
+ *
+ * @public
+ */
+declare class CliLogger {
+  private constructor();
+  /**
+   * The logger itself, for composing into an existing `Logger.layer` set.
+   *
+   * @remarks
+   * Prefer {@link CliLogger.layer}. Reach for this only when you are building
+   * the logger set yourself and want this one among several.
+   */
+  static readonly make: (options?: CliLoggerOptions) => Logger.Logger<unknown, void>;
+  /**
+   * Replace the default logger with this one.
+   *
+   * @remarks
+   * `Logger.layer` **replaces** rather than merges, so nothing is emitted twice.
+   *
+   * Merge this into the layer you provide to the whole program rather than
+   * providing it beneath: merged, it also covers lines emitted during layer
+   * construction, which is exactly where a startup failure prints.
+   */
+  static readonly layer: (options?: CliLoggerOptions) => Layer.Layer<never>;
+}
+//#endregion
+//#region src/CliRuntime.d.ts
+/**
+ * How a failure is turned into output and an exit code.
+ *
+ * @public
+ */
+interface ReportFailuresOptions {
+  /**
+   * Render the failure. Defaults to `String(error)`, one line.
+   *
+   * @remarks
+   * Return several lines to print several: a config error's own message
+   * followed by the rendered issue lines, say.
+   */
+  readonly render?: ((error: unknown) => string | ReadonlyArray<string>) | undefined;
+  /**
+   * The exit code to use when the error does not carry one.
+   *
+   * @remarks
+   * An error carrying `Runtime.errorExitCode` keeps its own; this is only the
+   * fallback, and it defaults to `1`.
+   */
+  readonly exitCode?: number | undefined;
+}
+/**
+ * Report a CLI program's failures through the program's own logger.
+ *
+ * @remarks
+ * ## The bug this exists to prevent
+ *
+ * A platform `runMain` reports an unhandled failure using Effect's **default**
+ * logger. That logger sits **outside** the layers the program was provided —
+ * `makeRunMain` composes its reporting `tapCause` around the already-provided
+ * effect — so a program that carefully installs {@link CliLogger} still prints
+ * its failures in the structured format that logger exists to replace, and
+ * prints them on **stdout**, the one stream errors must not use.
+ *
+ * Nothing about the call site suggests this. The program looks correct, the
+ * logger is installed, every success path is right, and only a failure reveals
+ * it.
+ *
+ * ## Why a combinator, and not a `runMain`
+ *
+ * The fix has to happen **inside** the effect, before any `runMain` sees it. So
+ * this is a combinator you apply to your program, and you still call your own
+ * platform's runner:
+ *
+ * @example
+ * ```ts
+ * import { CliRuntime } from "@effected/cli"
+ * import { NodeRuntime } from "@effect/platform-node"
+ * import { Effect } from "effect"
+ *
+ * NodeRuntime.runMain(program.pipe(CliRuntime.reportFailures(), Effect.provide(MainLive)))
+ * ```
+ *
+ * Wrapping `runMain` itself would drag a platform choice into a library that
+ * has no business making one, and would make this package unusable from Bun or
+ * Deno for no gain.
+ *
+ * ## What it does with the failure
+ *
+ * Renders it through the ambient logger, then **re-fails with a marked error**
+ * so the runtime still sees a failure — the exit code is the runtime's to set,
+ * and swallowing the failure would make a broken run exit `0`.
+ *
+ * The marks are core's own, and they are what make this work without a platform
+ * import:
+ *
+ * - `Runtime.errorExitCode` — `defaultTeardown` takes the squashed error's
+ *   value as the process exit code. An error that already carries one **keeps
+ *   it**: that was a deliberate choice by whatever raised it, and flattening
+ *   every failure to a single code would discard it.
+ * - `Runtime.errorReported` — set to `false`, which suppresses the runtime's own
+ *   duplicate report. **The polarity is inverted relative to the name**: the
+ *   marker means "should this be reported", so the intuitive
+ *   `errorReported: true` — "I have reported it, stay quiet" — produces exactly
+ *   the double report it was meant to prevent.
+ *
+ * An **interrupt is left alone**: it is not a failure to report, and the
+ * default teardown already maps an interrupt-only cause to `130`.
+ *
+ * @public
+ */
+declare class CliRuntime {
+  private constructor();
+  /**
+   * Catch, render through the ambient logger, and re-fail with the exit code
+   * 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>;
+  /**
+   * Mark an error as already reported, carrying an exit code.
+   *
+   * @remarks
+   * Exported because a program that reports a failure itself — a validation
+   * command that prints its own diagnostics, say — needs the same two marks
+   * and should not have to rediscover the inverted polarity.
+   */
+  static readonly reported: (error: unknown, exitCode?: number) => Error;
+}
+//#endregion
+//#region src/ConfigIssueRenderer.d.ts
+/**
+ * Render a `@effected/config-file` validation failure.
+ *
+ * @remarks
+ * `ConfigValidationError` carries the structured `issue` tree rather than a
+ * string, which is the right design and leaves the consumer holding a tree it
+ * has to turn into sentences. This is that step, and it is the same treatment
+ * {@link SchemaIssueRenderer} gives a bare issue.
+ *
+ * **This module is the only thing in the package that references
+ * `@effected/config-file`, deliberately.** The peer is declared optional, and
+ * an optional peer whose import is reachable from a shared module is not
+ * optional — it is a crash for every consumer who took the manifest at its word
+ * and did not install it. So nothing else in this package imports this module;
+ * only the entrypoint re-exports it, and the shared rendering lives in
+ * `internal/format`.
+ *
+ * The import is additionally `import type`, so it is erased at build time and
+ * the runtime reach is **zero** — a consumer without `@effected/config-file`
+ * installed can import this module and call `render` on any value without the
+ * resolver ever being asked for the package.
+ *
+ * ## Why this and not just the error's message
+ *
+ * `ConfigValidationError.message` names the file. It does not name the value,
+ * and the difference is the whole diagnostic: a consumer that printed only the
+ * message told users "your config is invalid, run the doctor command", and the
+ * doctor command — which guessed from a hand-written list of known keys — could
+ * only ever find a *misspelling*. A wrongly **shaped** value left the two
+ * commands pointing at each other and neither saying what was wrong.
+ *
+ * @example
+ * ```ts
+ * import { ConfigIssueRenderer } from "@effected/cli"
+ * import { Effect } from "effect"
+ *
+ * const load = configFile.load.pipe(
+ *   Effect.catchTag("ConfigValidationError", (error) =>
+ *     Effect.gen(function* () {
+ *       yield* Effect.logError(String(error))
+ *       for (const line of ConfigIssueRenderer.render(error)) yield* Effect.logError(`  ${line}`)
+ *     }),
+ *   ),
+ * )
+ * ```
+ *
+ * @public
+ */
+declare class ConfigIssueRenderer {
+  private constructor();
+  /**
+   * One line per rejected value.
+   *
+   * @remarks
+   * Takes the **error**, not its `issue`, because that is what a `catchTag`
+   * hands you and because `issue` is typed `Schema.Defect` — reaching into it
+   * at every call site is exactly the ceremony this removes.
+   *
+   * The parameter is the **typed** error rather than `unknown`. An earlier
+   * draft wrote `ConfigValidationError | unknown` to be accommodating, which
+   * collapses to plain `unknown` in TypeScript — so it accepted anything, said
+   * nothing, and left the type import in the `.d.ts` earning nothing. Inside
+   * `Effect.catchTag("ConfigValidationError", …)` the error is already this
+   * type, which is where this is called.
+   *
+   * It still cannot throw on a malformed value: the issue tree is validated by
+   * a guard before it is read, so a renderer on an error path never becomes the
+   * reason a program dies.
+   */
+  static readonly render: (error: ConfigValidationError) => ReadonlyArray<string>;
+}
+//#endregion
+//#region src/SchemaIssueRenderer.d.ts
+/**
+ * Turn a `SchemaIssue` tree into lines a user can act on.
+ *
+ * @remarks
+ * A decode failure arrives as a structured tree; a person needs
+ * `unknown key at groups.g.cleanup.rulesetz`.
+ *
+ * **Core already ships the formatters this wraps, and they are effectively
+ * undiscoverable.** They live on `SchemaIssue` rather than `SchemaError` or
+ * `Schema`, they are named `makeFormatter*` rather than anything containing
+ * "render" or "format issue", and `SchemaError.message` does not use them — so
+ * the obvious probe, printing the error, hints at nothing. Two engineers
+ * searched for two rounds and concluded core had none. This export exists to
+ * end that search, and the one phrasing override is a bonus rather than the
+ * point.
+ *
+ * @example
+ * ```ts
+ * import { SchemaIssueRenderer } from "@effected/cli"
+ * import { Effect, Schema } from "effect"
+ *
+ * const result = Schema.decodeUnknownEffect(MySchema)(input, {
+ *   onExcessProperty: "error",
+ *   errors: "all",
+ * })
+ *
+ * const reported = result.pipe(
+ *   Effect.catchTag("SchemaError", (error) =>
+ *     Effect.forEach(SchemaIssueRenderer.render(error.issue), (line) => Effect.logError(`  ${line}`)),
+ *   ),
+ * )
+ * ```
+ *
+ * @public
+ */
+declare class SchemaIssueRenderer {
+  private constructor();
+  /**
+   * One line per rejected value, deepest path last.
+   *
+   * @param issue - a `SchemaIssue` tree, or any value
+   * @returns the lines, or empty when `issue` is not an issue tree
+   */
+  static readonly render: (issue: unknown) => ReadonlyArray<string>;
+}
+//#endregion
+export { CliLogger, type CliLoggerOptions, CliRuntime, ConfigIssueRenderer, type ReportFailuresOptions, SchemaIssueRenderer };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,6 @@
+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 };

package/internal/format.js

@@ -0,0 +1,50 @@
+import { SchemaIssue } from "effect";
+
+//#region src/internal/format.ts
+/**
+* Core's structured formatter, with one phrasing override.
+*
+* @remarks
+* Built once: it is a pure function of the issue tree and carries no state.
+*
+* Core renders an excess property as `"Expected no excess property"`, which
+* describes the **schema's rule** rather than the **user's mistake**. The path
+* already names the key, so `unknown key at groups.g.cleanup.rulesetz` says the
+* same thing in the words someone editing a config file would use. Every other
+* leaf keeps core's phrasing, which is why this goes through `defaultLeafHook`
+* rather than a table of our own.
+*
+* @internal
+*/
+const formatter = SchemaIssue.makeFormatterStandardSchemaV1({ leafHook: (issue) => issue._tag === "UnexpectedKey" ? "unknown key" : SchemaIssue.defaultLeafHook(issue) });
+/**
+* Flatten an issue tree to one line per rejected value.
+*
+* @remarks
+* Shared by `SchemaIssueRenderer` and `ConfigIssueRenderer` and imported by
+* nothing else. It lives here rather than in either module so that
+* `ConfigIssueRenderer` — the only export that references the optional
+* `@effected/config-file` peer — can stay a module no other module imports.
+*
+* **No walker of our own.** `makeFormatterStandardSchemaV1` already flattens the
+* tree to `{ message, path }` entries, and `defaultLeafHook` covers every leaf
+* variant, so a wrong *type* renders as sensibly as an unknown key and a
+* variant added upstream is covered without a change here.
+*
+* Nodes are never stringified: each carries the entire AST inline, annotations
+* included, so `String(node)` would dump the schema rather than describe the
+* failure. Only `message` and `path` are read.
+*
+* @internal
+*/
+const formatIssue = (issue) => {
+	if (!SchemaIssue.isIssue(issue)) return [];
+	const lines = formatter(issue).issues.map((entry) => {
+		const path = (entry.path ?? []).map(String).join(".");
+		return path === "" ? entry.message : `${entry.message} at ${path}`;
+	});
+	return [...new Set(lines)];
+};
+
+//#endregion
+export { formatIssue };

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@effected/cli",
+	"version": "0.1.0",
+	"private": false,
+	"description": "The boundary layer of an effect/unstable/cli program: plain CLI output, failure reporting, and schema-issue rendering",
+	"keywords": [
+		"effect",
+		"cli",
+		"logger",
+		"terminal"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/cli#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/cli"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"@effected/config-file": "^0.4.0",
+		"effect": "4.0.0-beta.107"
+	},
+	"peerDependenciesMeta": {
+		"@effected/config-file": {
+			"optional": true
+		}
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.12"
+    }
+  ]
+}