@effected/cli 0.10.0 → 0.12.0

package/CliRuntime.js

@@ -1,15 +1,32 @@
+import { sanitize } from "./Fmt.js";
+import { FailureTargetCell, currentTarget, fallbackTarget, guardConsumerLines, linesOf, plainFailureLines, readSpans, refreshFailureTarget } from "./internal/failureTarget.js";
+import { CliColor } from "./CliColor.js";
+import { CliEnv } from "./CliEnv.js";
 import { isExitCode } from "./internal/isExitCode.js";
 import { CliExit } from "./CliExit.js";
-import { CliLogger } from "./CliLogger.js";
+import { TrustedLine } from "./internal/logSafety.js";
+import { CliLogger, makeCliLogger } from "./CliLogger.js";
+import { CliLog, envBuildLogLayer, platformLogLayer } from "./CliLog.js";
 import { ExitRequested } from "./internal/ExitRequested.js";
 import { routeHelpOnUsageError } from "./internal/HelpRouting.js";
-import { Cause, Effect, MutableRef, Runtime } from "effect";
+import { Cause, Effect, Layer, Logger, MutableRef, Runtime } from "effect";
 import { CliError } from "effect/cli";
+import { CommandNeutralizer } from "@effected/github-commands";
 
 //#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;
+/** The last line of defence of a failure report: the error's text, sanitised and neutralized, whatever else broke. */
+const lastResort = (error) => {
+	let text;
+	try {
+		text = String(error);
+	} catch {
+		text = "[unprintable failure]";
+	}
+	return CommandNeutralizer.lines(sanitize(text));
+};
 const toLines = (rendered) => typeof rendered === "string" ? [rendered] : rendered;
 /**
 * The error's own exit code when it carries one, otherwise the fallback.
@@ -25,7 +42,7 @@ const chooseExitCode = (error, fallback) => typeof error === "object" && error !
 * Report a CLI program's failures through the program's own logger.
 *
 * @remarks
-* ## The bug this exists to prevent
+* ## What it prevents
 *
 * A platform `runMain` reports an unhandled failure using Effect's **default**
 * logger. That logger sits **outside** the layers the program was provided —
@@ -42,18 +59,7 @@ const chooseExitCode = (error, fallback) => typeof error === "object" && error !
 *
 * 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
+* platform's runner. 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.
 *
@@ -96,13 +102,49 @@ const chooseExitCode = (error, fallback) => typeof error === "object" && error !
 * raises is likewise never rendered; it only carries the exit code a
 * successful program recorded through `CliExit`.
 *
+* @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)))
+* ```
+*
 * @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.
+	* What `reportFailures` and `main` render a failure as when no `render` option is given, for a consumer's own
+	* `render` to hand a failure back to.
+	*
+	* @remarks
+	* The plain lines of `CliFailure.toDoc(details.cause)`: a failure status line, a `Tree` for a schema failure, a
+	* defect's message with its cleaned `stack`, and the one fixed line each for `Cancelled` and `NotInteractive`.
+	* It has no terminal to ask, so it is the plain rendering for an agent, with absolute paths; the report `main` writes
+	* with no `render` option is the same document in the renderer the audience gets (painted for a person), and that
+	* report is `details.defaultLines`: return those to hand a failure back with the run's colour, links and path
+	* display. With `status: false` the leading status (the glyph, or `[FAIL]` in plain text) is left off, so a prefix
+	* such as the program's name reads cleanly; for that AND the run's settings, use `details.lines({ status: false })`.
+	* A custom `render` that only cares about its own errors delegates the rest:
+	*
+	* ```ts
+	* const render = (error: unknown, details: FailureDetails) =>
+	*   error instanceof MyError ? myLines(error) : CliRuntime.defaultRender(error, details)
+	* ```
+	*
+	* @param error - the squashed failure
+	* @param details - what `render` is told about the failure; accepted so a delegating `render` passes both
+	*   arguments through unchanged (only `cause` and `isDefect` are read)
+	* @param options - `status: false` leaves off the leading status glyph or `[FAIL]` tag
+	*/
+	static defaultRender = (error, details, options) => plainFailureLines(details.cause.reasons.length > 0 ? details.cause : Cause.fail(error), options?.status !== false);
+	/**
+	* Catch a program's failure, render it through the ambient logger, and re-fail with the exit code and the
+	* no-double-report mark.
+	*
+	* @param options - how to render the failure and which exit codes to use
 	*/
 	static reportFailures = (options = {}) => (effect) => effect.pipe(Effect.catchCause((cause) => {
 		if (Cause.hasInterruptsOnly(cause)) return Effect.failCause(cause);
@@ -113,50 +155,64 @@ var CliRuntime = class CliRuntime {
 			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));
-		const details = {
-			cause,
-			isDefect: !Cause.hasFails(cause)
-		};
+		const render = options.render;
 		return Effect.gen(function* () {
-			for (const line of toLines(render(error, details))) yield* Effect.logError(line);
+			const target = yield* currentTarget.pipe(Effect.catchCause(() => Effect.succeed(fallbackTarget)));
+			const reportLines = (status, spans) => {
+				try {
+					return linesOf(cause, target, status, spans ?? target.spans);
+				} catch {
+					try {
+						return plainFailureLines(cause, status, spans ?? target.spans);
+					} catch {
+						return lastResort(error);
+					}
+				}
+			};
+			const defaultLines = reportLines(true);
+			const details = {
+				cause,
+				isDefect: !Cause.hasFails(cause),
+				defaultLines,
+				lines: (options) => options?.status === false || options?.spans !== void 0 ? reportLines(options?.status !== false, options?.spans) : defaultLines
+			};
+			const lines = render === void 0 ? defaultLines : yield* guardConsumerLines(toLines(render(error, details)));
+			for (const line of lines) yield* Effect.logError(line).pipe(Effect.provideService(TrustedLine, true));
 			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* 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}`));
-		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 main(program, options) {
+		const env = options.env === void 0 ? void 0 : CliEnv.layer(options.env);
+		const envLog = options.env?.log;
+		const logger = options.logger ?? (env === void 0 || envLog === void 0 ? CliLogger.layer() : CliLog.layer(envLog).pipe(Layer.provide(env), Layer.provide(Layer.provideMerge(options.platform.pipe(Layer.provide(platformLogLayer(envLog, options.env?.audienceEnvVar))), envBuildLogLayer(envLog, options.env?.audienceEnvVar))), Layer.catchCause(() => CliLogger.layer(envLog.logger))));
+		const inside = env === void 0 ? Layer.empty : Layer.mergeAll(CliColor.formatterLayer(options.env?.formatter), Layer.effectDiscard(Effect.gen(function* () {
+			const { spans, invalid } = yield* readSpans(options.env?.spans, options.env?.spansEnvVar);
+			if (invalid !== void 0) yield* Effect.logWarning(invalid).pipe(Effect.provideService(Logger.CurrentLoggers, /* @__PURE__ */ new Set([makeCliLogger(envLog?.logger)])));
+			yield* refreshFailureTarget(void 0, {
+				displayPath: options.env?.displayPath,
+				stackFrames: options.env?.stackFrames,
+				spans,
+				appModule: options.env?.appModule
+			});
+		}))).pipe(Layer.provideMerge(env));
+		const run = Effect.gen(function* () {
+			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}`));
+			if (code !== 0) return yield* Effect.fail(new ExitRequested(code));
+		}).pipe(Effect.provide(CliExit.layer), Effect.provide(inside), Effect.provide(options.platform), CliRuntime.reportFailures(options), Effect.provide(logger));
+		return Effect.suspend(() => Effect.provideService(run, FailureTargetCell, MutableRef.make(void 0)));
+	}
 	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
+		for (const [key, value] of [[Runtime.errorReported, false], [Runtime.errorExitCode, exitCode]]) Object.defineProperty(marked, key, {
+			value,
+			writable: true,
+			configurable: true,
+			enumerable: false
 		});
+		return marked;
 	}
 };
 

package/CliTest.js

@@ -6,6 +6,22 @@ const text = (stream) => Stream.mkString(Stream.decodeText(stream));
 /**
 * Spawn a built CLI bin hermetically and read its exit code and streams as data.
 *
+* @example
+* ```ts
+* import * as NodeServices from "@effect/platform-node/NodeServices"
+* import { assert, it } from "@effect/vitest"
+* import { CliTest } from "@effected/cli/testing"
+* import { Effect } from "effect"
+*
+* it.effect("prints its version", () =>
+*   Effect.gen(function* () {
+*     const sandbox = yield* CliTest.sandbox({ path: process.env.PATH ?? "" })
+*     const result = yield* CliTest.run("dist/bin.js", ["--version"], { sandbox, execPath: process.execPath })
+*     assert.strictEqual(result.exitCode, 0)
+*   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+* )
+* ```
+*
 * @public
 */
 var CliTest = class {

package/CliTheme.js

@@ -0,0 +1,141 @@
+import { Glyphs } from "./Glyphs.js";
+import { openSequence, paintStyle } from "./internal/ansi.js";
+import { Token } from "./Token.js";
+import { Config, Context, Effect, Layer, Option } from "effect";
+import { TerminalEnv } from "@effected/env";
+import { Prompt } from "effect/cli";
+
+//#region src/CliTheme.ts
+/**
+* A stream theme at `color`, over a style resolution and a glyph set: the one way a {@link StreamTheme} is built.
+*
+* @internal
+*/
+const streamThemeAt = (resolve, glyphs, color) => {
+	const paint = (token, text) => paintStyle(resolve(token), color, text);
+	return {
+		paint,
+		style: resolve,
+		sgr: (token) => openSequence(resolve(token), color),
+		glyphs,
+		color,
+		status: (vocab, name, text) => {
+			const glyph = paint(vocab.def(name).token, vocab.glyph(name, glyphs));
+			return text === void 0 || text === "" ? glyph : `${glyph} ${text}`;
+		}
+	};
+};
+/** The audience rule, shared by `CliTheme.forAudience` and the class's own docs. */
+const forAudience = (theme, audience) => audience === "agent" && theme.color !== "none" ? streamThemeAt(theme.style, theme.glyphs, "none") : theme;
+const make = (colors, glyphs, overrides) => {
+	const resolve = (token) => Token.resolve(token, overrides);
+	const stdout = streamThemeAt(resolve, glyphs, colors.stdout);
+	const stderr = streamThemeAt(resolve, glyphs, colors.stderr);
+	return {
+		...stdout,
+		forStream: (stream) => stream === "stdout" ? stdout : stderr
+	};
+};
+/** The prompt glyphs that differ under ASCII; `Prompt.makeTheme` already holds the Unicode ones. */
+const ASCII_PROMPT_GLYPHS = {
+	prefix: "?",
+	arrowUp: "^",
+	arrowDown: "v",
+	checkboxOn: "[x]",
+	checkboxOff: "[ ]",
+	tick: "+",
+	pointerSmall: ">",
+	pointer: ">"
+};
+/**
+* The presentation of a CLI: colour tokens, glyphs and statuses, decided once from the terminal.
+*
+* @remarks
+* A `Context.Service`, not a `Reference`. A colour level is a fact about the terminal, not a preference with a
+* safe default, so there is nothing sensible for an unprovided theme to read; requiring it puts `CliTheme` in
+* `R` and a program that forgot to wire it fails to compile rather than printing plain text to a colour
+* terminal. {@link CliTheme.layer} reads `TerminalEnv`.
+*
+* @public
+*/
+var CliTheme = class CliTheme extends Context.Service()("@effected/cli/CliTheme") {
+	/**
+	* The theme for the terminal `TerminalEnv` describes.
+	*
+	* @remarks
+	* Bind the layer to a constant and provide it once. With `glyphs: "auto"` the glyph set is ASCII only when
+	* `TERM=dumb`, read through `Config`.
+	*
+	* @param options - token overrides and the glyph set
+	*/
+	static layer = (options) => Layer.effect(CliTheme, Effect.gen(function* () {
+		const terminal = yield* TerminalEnv;
+		const choice = options?.glyphs ?? "auto";
+		const term = choice === "auto" ? Option.getOrUndefined(yield* Config.option(Config.String("TERM")).pipe(Effect.orElseSucceed(() => Option.none()))) : void 0;
+		const glyphs = Glyphs.select({
+			ascii: choice === "ascii" ? true : choice === "unicode" ? false : "auto",
+			...term === void 0 ? {} : { term }
+		});
+		return make({
+			stdout: terminal.stdout.color,
+			stderr: terminal.stderr.color
+		}, glyphs, options?.tokens);
+	}));
+	/**
+	* The theme an audience sees of `theme`: for an agent, the same theme at colour `none` (`paint` the identity, `sgr`
+	* empty, `status` unpainted), whatever the terminal could do, because an agent never gets an escape of any kind; for
+	* anyone else, or when the audience is not known, `theme` itself.
+	*
+	* @remarks
+	* The one rule the kit applies wherever it paints for an audience: `Render.context` takes its colour and `paint`
+	* from it, `CliMessage` and `CliLog.status` paint their glyphs through it, and `./ui` gives it to the trees it
+	* mounts, so `useTheme`, `Styled` and the widgets' colour-`none` text markers all agree. A program that paints its
+	* own lines applies the same rule with it rather than re-implementing it:
+	*
+	* ```ts
+	* const line = Effect.gen(function* () {
+	*   const theme = CliTheme.forAudience((yield* CliTheme).forStream("stdout"), (yield* Audience).kind)
+	*   return theme.status(Status.core, "success", Fmt.sanitize(name))
+	* })
+	* ```
+	*
+	* Pure: it reads nothing, so the audience is the caller's to pass, `undefined` when it is not known.
+	*
+	* @param theme - a stream's theme, such as `CliTheme.forStream("stdout")`
+	* @param audience - who the output is for, or `undefined` when that is not known
+	*/
+	static forAudience = forAudience;
+	/**
+	* A fixed theme that needs nothing; `none` colour and Unicode glyphs unless told otherwise.
+	*
+	* @param options - the colour level and glyph set
+	*/
+	static layerTest = (options) => Layer.succeed(CliTheme, make({
+		stdout: options?.color ?? "none",
+		stderr: options?.stderrColor ?? options?.color ?? "none"
+	}, options?.glyphs === "ascii" ? Glyphs.ascii : Glyphs.unicode, void 0));
+	/**
+	* Sets core's `Prompt.Theme` from the tokens, so built-in prompts match the rest of the output.
+	*
+	* @remarks
+	* The colour fields are raw SGR openers and are empty strings when colour is `none`. Under ASCII glyphs the
+	* prompt symbols fall back to ASCII too. A colourless theme is not byte-clean: core's `Ansi.annotate`
+	* appends a `\x1b[0m` reset, and prompts write cursor and underline codes, whatever the theme says.
+	*/
+	static promptTheme = Layer.effect(Prompt.Theme, Effect.gen(function* () {
+		const theme = yield* CliTheme;
+		const open = (token) => theme.sgr(token);
+		return Prompt.makeTheme({
+			...theme.glyphs.kind === "ascii" ? ASCII_PROMPT_GLYPHS : {},
+			ellipsis: theme.glyphs.ellipsis,
+			primaryColor: open("accent"),
+			mutedColor: open("muted"),
+			successColor: open("success"),
+			errorColor: open("error"),
+			submittedColor: open("emphasis")
+		});
+	}));
+};
+
+//#endregion
+export { CliTheme, streamThemeAt };

package/ConfigIssueRenderer.js

@@ -2,35 +2,21 @@ import { formatIssue } from "./internal/format.js";
 
 //#region src/ConfigIssueRenderer.ts
 /**
-* Render a `@effected/config-file` validation failure.
+* Turns a `@effected/config-file` `ConfigValidationError` into one line per rejected value.
 *
 * @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.
+* string, so a caller holds a tree it has to turn into sentences. This is that
+* step, 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`.
+* `ConfigValidationError.message` names the file but not the value, and the
+* value is the diagnostic: printing only the message tells a user their config
+* is invalid without saying which value is wrong or how it is shaped.
 *
-* 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.
+* `@effected/config-file` is an optional peer, and this module only
+* `import type`s it, so the import is erased at build time. A consumer without
+* the package installed can import this module without the resolver being asked
+* for it.
 *
 * @example
 * ```ts
@@ -56,17 +42,12 @@ var ConfigIssueRenderer = class {
 	*
 	* @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
+	* hands you and because `issue` is typed `Schema.Defect`, which every call
+	* site would otherwise have to reach into. Inside
 	* `Effect.catchTag("ConfigValidationError", …)` the error is already this
-	* type, which is where this is called.
+	* type.
 	*
-	* It still cannot throw on a malformed value: the issue tree is validated by
+	* It 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.
 	*/