@effected/cli 0.9.0 → 0.11.0

package/CliInteractive.js

@@ -0,0 +1,71 @@
+import { canPrompt } from "./internal/canPrompt.js";
+import { Context, Effect, Layer } from "effect";
+import { Audience, TerminalEnv } from "@effected/env";
+
+//#region src/CliInteractive.ts
+/**
+* Whether this run may prompt a person: a human audience, with a terminal on
+* both standard input and standard output, and a `TERM` that is not `dumb`.
+*
+* @remarks
+* A `Context.Reference`, not a `Context.Service`, for three reasons. It is one
+* boolean with a safe default, which is what a reference is for. A scoped
+* override, {@link CliInteractive.unless}, is a plain
+* `Effect.provideService`, so a command can switch prompting off for one
+* subtree without a layer. And forgetting to provide it is not a type error
+* but a harmless answer, since it reads `false` when no layer is provided: a
+* program that never wired it refuses to prompt rather than hanging on a
+* terminal that is not there. Read it with `yield* CliInteractive`.
+*
+* Because a reference's key type is `never`, {@link CliInteractive.layer} and
+* {@link CliInteractive.layerTest} are typed `Layer<never>`: they set the
+* reference rather than provide a service.
+*
+* @public
+*/
+var CliInteractive = class CliInteractive extends Context.Reference("@effected/cli/CliInteractive", { defaultValue: () => false }) {
+	/**
+	* Decide from the audience and the terminal: `true` only for a human audience with a terminal on both
+	* standard input and standard output, and a `TERM` that is not `dumb`.
+	*
+	* @remarks
+	* A dumb terminal is a terminal, but it cannot move the cursor or take synchronized output, which a prompt or a
+	* screen redrawing in place needs: it gets what a pipe gets. `TERM` is read through the ambient `ConfigProvider`,
+	* as `@effected/env` reads the environment, so it adds no requirement; a test fixes it with
+	* `Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromUnknown({ TERM: "dumb" }))`.
+	*
+	* Bind the layer to a constant and provide it once; `Audience` and `TerminalEnv` come from `@effected/env`.
+	*/
+	static layer = Layer.effect(CliInteractive, Effect.gen(function* () {
+		const audience = yield* Audience;
+		const terminal = yield* TerminalEnv;
+		return audience.kind === "human" && (yield* canPrompt(terminal));
+	}));
+	/**
+	* A fixed answer that needs nothing.
+	*
+	* @param value - whether the run is interactive
+	*/
+	static layerTest = (value) => Layer.succeed(CliInteractive, value);
+	/**
+	* Run `self` with interactivity switched off when `condition` holds.
+	*
+	* @remarks
+	* It only narrows: `unless(false)` leaves the current value alone and never turns interactivity on, so a
+	* non-interactive scope stays non-interactive. The outer value is restored when `self` ends, whether it
+	* succeeds, fails or is interrupted.
+	*
+	* A flag that resolves the audience (`--human`, under `CliAudience.runWith` or `provide`) recomputes interactivity
+	* from the terminal facts, so it can override an outer `unless` or a `layerTest(false)`: those narrow the
+	* environment's answer, and the flag is a later, explicit one.
+	*
+	* @param condition - `true` to switch prompting off for `self`
+	*/
+	static unless = (condition) => (self) => Effect.gen(function* () {
+		const current = yield* CliInteractive;
+		return yield* Effect.provideService(self, CliInteractive, current && !condition);
+	});
+};
+
+//#endregion
+export { CliInteractive };

package/CliLinks.js

@@ -0,0 +1,154 @@
+import { sanitize } from "./Fmt.js";
+import { isAllowedLinkUrl } from "./internal/linkScheme.js";
+import { DRIVE, UNC, encodeForOsc8, fileUrlPath } from "./internal/linkTarget.js";
+import { Config, Context, Effect, FileSystem, Layer, Option, Path } from "effect";
+import { CurrentRuntimeEnv } from "@effected/env";
+import { Walker } from "@effected/walker";
+
+//#region src/CliLinks.ts
+const MODES = [
+	"auto",
+	"vscode",
+	"file",
+	"off"
+];
+const parseSetting = (raw) => MODES.find((mode) => mode === raw.trim().toLowerCase());
+/** A URL with its control characters and line breaks removed: none is legal in one, and each could end an OSC 8 early. */
+const cleanUrl = (url) => sanitize(url).replace(/[\r\n]/g, "");
+const makeTarget = (mode, absolute) => (target) => {
+	if ("url" in target) {
+		const url = cleanUrl(target.url);
+		return url === "" || !isAllowedLinkUrl(url) ? Option.none() : Option.some(url);
+	}
+	if (mode === "off") return Option.none();
+	const resolved = absolute(target.file);
+	if (resolved === void 0) return Option.none();
+	const path = fileUrlPath(resolved);
+	if (path === void 0) return Option.none();
+	if (mode === "file") return Option.some(`file://${path}`);
+	const position = target.line === void 0 ? "" : target.col === void 0 ? `:${target.line}` : `:${target.line}:${target.col}`;
+	return Option.some(`vscode://file${path}${position}`);
+};
+const isDirectory = (fs, path) => fs.stat(path).pipe(Effect.map((info) => info.type === "Directory"), Effect.orElseSucceed(() => false));
+const exists = (fs, path) => fs.exists(path).pipe(Effect.orElseSucceed(() => false));
+/**
+* The nearest directory, from `cwd` up, that holds `.git` or `pnpm-workspace.yaml`.
+*
+* It looks at `cwd` and then climbs at most {@link MAX_ASCENT} directories, through `Walker.ascend`, which also stops
+* where `dirname` reaches a fixpoint (the filesystem root). `Walker.findRoot` absorbs a failed probe as "not a root",
+* so one unreadable directory never hides a root above it. `None` when there is none.
+*/
+const findRoot = (fs, path, cwd) => Walker.ascend(cwd, { maxDepth: 65 }).pipe(Effect.provideService(Path.Path, path), Effect.flatMap((directories) => Walker.findRoot(directories, (directory) => Effect.gen(function* () {
+	return (yield* exists(fs, path.join(directory, ".git"))) || (yield* exists(fs, path.join(directory, "pnpm-workspace.yaml")));
+}))));
+const readOption = (name) => Config.option(Config.String(name)).pipe(Effect.orElseSucceed(() => Option.none()));
+const build = (options, ambient) => Effect.gen(function* () {
+	const runtime = yield* CurrentRuntimeEnv;
+	const raw = options.envVar === void 0 ? "" : Option.getOrElse(yield* readOption(options.envVar), () => "").trim();
+	const fromEnv = parseSetting(raw);
+	if (options.envVar !== void 0 && raw !== "" && fromEnv === void 0) yield* Effect.logWarning(`${options.envVar}=${raw} is not one of ${MODES.join("|")}; ignoring it`);
+	const setting = fromEnv ?? options.editorLinks ?? "auto";
+	const pwd = options.cwd === void 0 ? yield* readOption("PWD") : Option.none();
+	const cwd = options.cwd ?? Option.getOrUndefined(pwd) ?? (Option.isSome(ambient.path) ? ambient.path.value.resolve(".") : void 0);
+	const path = Option.getOrUndefined(ambient.path);
+	const absolute = (file) => {
+		if (UNC.test(file)) return void 0;
+		if (DRIVE.test(file)) return file;
+		if (path === void 0) return file.startsWith("/") ? file : void 0;
+		if (path.isAbsolute(file)) return file;
+		return cwd === void 0 ? void 0 : path.resolve(cwd, file);
+	};
+	const mode = setting !== "auto" ? setting : Option.exists(runtime.terminal, (terminal) => terminal.name === "vscode") ? "vscode" : yield* Effect.gen(function* () {
+		if (Option.isNone(ambient.fs) || path === void 0 || cwd === void 0) return "file";
+		const root = yield* findRoot(ambient.fs.value, path, cwd);
+		const base = Option.getOrElse(root, () => cwd);
+		return (yield* isDirectory(ambient.fs.value, path.join(base, ".vscode"))) ? "vscode" : "file";
+	});
+	return {
+		mode,
+		target: makeTarget(mode, absolute)
+	};
+});
+/**
+* Editor-aware links for file targets: where a link to a file opens.
+*
+* @remarks
+* The mode is decided once, when the layer is built. `auto` is `vscode` when `CurrentRuntimeEnv.terminal` is
+* `vscode` (`TERM_PROGRAM=vscode`) or a `.vscode/` directory sits at the project root, and `file` otherwise. The
+* root is the nearest directory, from the working directory up, that holds `.git` or `pnpm-workspace.yaml`; the
+* climb is bounded, at most 64 directories above the working directory, and stops where `Path.dirname` reaches the
+* filesystem root. With no root, the working directory itself is checked.
+*
+* Whether a link is written at all is a separate question, answered by {@link CliLinks.linker}.
+*
+* @public
+*/
+var CliLinks = class CliLinks extends Context.Service()("@effected/cli/CliLinks") {
+	/**
+	* The links for the working directory, reading the filesystem for a `.vscode/` directory.
+	*
+	* @remarks
+	* A layer-returning function mints a fresh layer per call: call it once and bind the result to a constant.
+	*
+	* @param options - the setting, the environment variable that overrides it, and the working directory
+	*/
+	static layer = (options = {}) => Layer.effect(CliLinks, Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		return yield* build(options, {
+			fs: Option.some(fs),
+			path: Option.some(path)
+		});
+	}));
+	/**
+	* Links fixed to a mode, with no filesystem: a relative path has no link, since there is no working directory.
+	*
+	* @param mode - `vscode`, `file` or `off`
+	*/
+	static layerTest = (mode) => Layer.succeed(CliLinks, {
+		mode,
+		target: makeTarget(mode, (file) => file.startsWith("/") || DRIVE.test(file) ? file : void 0)
+	});
+	/**
+	* The function that writes a link: a target and a label in, the label out, wrapped in OSC 8 when it should be.
+	*
+	* @remarks
+	* It writes the hyperlink `ESC ] 8 ; ; URL ESC \ label ESC ] 8 ; ; ESC \` only when the stream's terminal can
+	* render it (`hyperlinks`) and the audience is not an agent, which never gets an escape of any kind; in every other
+	* case, and whenever the target has no URL, it returns the label unchanged. The URL has its control characters
+	* removed again here, so a hostile target cannot end the sequence early or start another, and a URL whose scheme is
+	* not one a link may have (`javascript:`, `data:`, and the like; the same list markdown uses) is the label alone. It is pure and cheap,
+	* which {@link RenderContext}'s `link` requires.
+	*
+	* @param options - the links, whether hyperlinks are available, and the audience
+	*/
+	static linker = (options) => (target, label) => {
+		if (!options.hyperlinks || options.audience === "agent") return label;
+		const url = options.links.target(target);
+		if (Option.isNone(url)) return label;
+		const written = encodeForOsc8(cleanUrl(url.value));
+		if (!isAllowedLinkUrl(written)) return label;
+		return `\u001B]8;;${written}\u001B\\${label}\u001B]8;;\u001B\\`;
+	};
+};
+/**
+* The links for {@link CliEnv.layer}: the same as {@link CliLinks.layer}, except that `FileSystem` and `Path` are
+* taken from the environment if it has them, not required.
+*
+* Without them there is no `.vscode/` to look for and no working directory to resolve a relative path against, so
+* `auto` is `vscode` only on the terminal signal. This keeps the requirements of `CliEnv.layer` and of every
+* `CliRuntime.main` overload unchanged.
+*
+* @internal
+*/
+const ambientLinksLayer = (options = {}) => Layer.effect(CliLinks, Effect.gen(function* () {
+	const fs = yield* Effect.serviceOption(FileSystem.FileSystem);
+	const path = yield* Effect.serviceOption(Path.Path);
+	return yield* build(options, {
+		fs,
+		path
+	});
+}));
+
+//#endregion
+export { CliLinks, ambientLinksLayer };

package/CliLog.js

@@ -0,0 +1,294 @@
+import { sanitize } from "./Fmt.js";
+import { paintStyle } from "./internal/ansi.js";
+import { scanAudience } from "./internal/scanAudience.js";
+import { neutralizeJson } from "./internal/logSafety.js";
+import { makeCliLogger } from "./CliLogger.js";
+import { Level, passes } from "./internal/diagnostics.js";
+import { makeFileSink } from "./internal/fileSink.js";
+import { Cause, Config, Console, Context, Effect, Layer, LogLevel, Logger, Option, Path, References } from "effect";
+import { Audience, CurrentRuntimeEnv, TerminalEnv } from "@effected/env";
+import { CommandNeutralizer } from "@effected/github-commands";
+
+//#region src/CliLog.ts
+/** The accepted spellings of a level, lower-cased, to the level they mean. */
+const LEVELS = {
+	all: "All",
+	trace: "Trace",
+	debug: "Debug",
+	info: "Info",
+	warn: "Warn",
+	warning: "Warn",
+	error: "Error",
+	fatal: "Fatal",
+	none: "None"
+};
+const LEVEL_STYLES = {
+	FATAL: {
+		fg: "red",
+		bold: true
+	},
+	ERROR: { fg: "red" },
+	WARN: { fg: "yellow" },
+	INFO: { fg: "cyan" },
+	DEBUG: { fg: "blue" },
+	TRACE: { dim: true }
+};
+/** The diagnostics level: the option when given, else the env var, and the raw text when that is not a level. */
+const readLevel = (explicit, envVar) => Effect.gen(function* () {
+	if (explicit !== void 0) return {
+		level: explicit,
+		invalid: void 0
+	};
+	if (envVar === void 0) return {
+		level: "None",
+		invalid: void 0
+	};
+	const raw = yield* Config.option(Config.String(envVar)).pipe(Effect.orElseSucceed(() => Option.none()));
+	if (Option.isNone(raw) || raw.value === "") return {
+		level: "None",
+		invalid: void 0
+	};
+	const level = LEVELS[raw.value.toLowerCase()];
+	if (level !== void 0) return {
+		level,
+		invalid: void 0
+	};
+	return {
+		level: "None",
+		invalid: `${envVar}=${raw.value} is not a log level (${Object.keys(LEVELS).join("|")}); ignoring it`
+	};
+});
+/**
+* Whether a record's line is neutralized: the `neutralize` option when it is a boolean, else whether the logging
+* fiber's `CurrentRuntimeEnv`, or `fallback` where the fiber has none, says GitHub Actions.
+*/
+const actionsDecision = (neutralize, fallback) => (fiber) => {
+	if (neutralize !== "auto") return neutralize;
+	const inFiber = Context.getOption(fiber.context, CurrentRuntimeEnv);
+	const runtime = Option.isSome(inFiber) ? inFiber : fallback;
+	return Option.contains(Option.flatMap(runtime, (env) => env.ci), "github-actions");
+};
+/**
+* Diagnostics kept apart from a program's output: a level, a format and a place to write.
+*
+* @remarks
+* Two kinds of line must never be silenced by a diagnostics default: the failure report
+* `CliRuntime.reportFailures` writes through `CliLogger`, and the `CliMessage` lines. This package therefore
+* never makes the diagnostics level a global switch. The diagnostics logger filters on its **own** threshold,
+* {@link CliLog.Level}, and writes to stderr only.
+*
+* `CliLog.layer` **owns the whole logger set**. It builds a `CliLogger` for ordinary log lines and the
+* diagnostics sink itself and replaces whatever was installed, without reading it, so there is no order to get
+* wrong. Use it instead of `CliLogger.layer`, not with it: `CliLogger.layer` alone is the no-diagnostics path,
+* and a `CliLogger.layer` layered on top would replace this layer's set.
+*
+* Effect drops a record below `MinimumLogLevel` before any logger runs, so to let a debug record reach the
+* diagnostics logger `MinimumLogLevel` has to be lowered. `CliLog.layer` does that only when the
+* diagnostics level is below the ambient minimum, and in the same step floors the `CliLogger` it built at the
+* minimum it had, so it never prints a record the diagnostics level alone let through. A failure report is
+* written outside the scope core's `--log-level` flag sets, so `--log-level none` does not silence it either.
+*
+* `format: "auto"`, the default, decides by the audience alone, at build time and at runtime alike: NDJSON for an
+* agent or a CI, the pretty line for a human, whatever stderr's terminal state. A human piping stderr therefore gets
+* plain lines (without escapes unless stderr is a colour terminal); pass `format: "json"` for machine-readable logs.
+*
+* The text a program logs is sanitised before anything is painted in the pretty line (the message, the component and an
+* error's cause lose their escape sequences and control characters), and under GitHub Actions, where
+* `CurrentRuntimeEnv` in the logging fiber's context says so, a line the runner would read as a workflow command is
+* neutralized. An NDJSON record is not safe merely because `JSON.stringify` escapes control characters: the runner's
+* legacy parser reads `##[` anywhere in a line, so under Actions it is written as the JSON escape `#\u0023[`, which
+* decodes to the identical text. The file sink's lines are not read by the runner and are written as they are.
+*
+* `CurrentRuntimeEnv` is read from the logging fiber's context, and where that has none, from the `runtimeEnv` option,
+* else from the layer's own build context (captured if present, never required), so a host that builds the layer over
+* its environment, or names it with `runtimeEnv`, neutralizes every record. A record with none of the three (a program
+* with no `CurrentRuntimeEnv` anywhere) is sanitised but not neutralized, unless the `neutralize` option says otherwise.
+*
+* Core's `--log-level` flag sets `MinimumLogLevel` inside the command. While it is set to something other than
+* the value this layer installed, the diagnostics logger follows the flag instead of its own level: it writes
+* every record that reaches it. The `CliLogger` prints the same record too, so a record at or above the ambient
+* minimum is written twice, once plain and once to the diagnostics sink. Stderr is therefore not pure NDJSON while
+* diagnostics are on: a parser reads the lines that start with `{`.
+*
+* One edge: a `--log-level` value that EQUALS the level this layer installed cannot be told from no flag, so the
+* sink keeps filtering on its own level rather than following the flag. The plain `CliLogger` prints those records
+* regardless.
+*
+* @example
+* ```ts
+* import { CliRuntime } from "@effected/cli"
+* import { NodeRuntime, NodeServices } from "@effect/platform-node"
+*
+* // `env.log` makes `main` install `CliLog.layer`: set MYTOOL_LOG_LEVEL=debug to get diagnostics on stderr.
+* NodeRuntime.runMain(
+*   CliRuntime.main(program, {
+*     platform: NodeServices.layer,
+*     env: { audienceEnvVar: "MYTOOL_AUDIENCE", log: { envVar: "MYTOOL_LOG_LEVEL" } },
+*   }),
+* )
+* ```
+*
+* @public
+*/
+var CliLog = class CliLog {
+	constructor() {}
+	/**
+	* The diagnostics threshold. Defaults to `None`, silent.
+	*
+	* @remarks
+	* `CliLog.layer` sets it from the environment variable. A scope may raise it to narrow the output; it
+	* cannot lower it below the level the layer installed, because Effect has already dropped those records.
+	*/
+	static Level = Level;
+	static layer(options = {}) {
+		const file = "file" in options ? options.file : void 0;
+		const format = options.format ?? "auto";
+		return Layer.unwrap(Effect.gen(function* () {
+			const audience = format === "auto" ? yield* Audience : void 0;
+			const terminal = format === "json" ? void 0 : yield* TerminalEnv;
+			const { level, invalid } = yield* readLevel(options.level, options.envVar);
+			const ambient = yield* References.MinimumLogLevel;
+			const captured = yield* Effect.serviceOption(CurrentRuntimeEnv);
+			const fallback = options.runtimeEnv === void 0 ? captured : Option.some(options.runtimeEnv);
+			const underActionsIn = actionsDecision(options.neutralize ?? "auto", fallback);
+			const color = terminal?.stderr.color ?? "none";
+			const isPretty = (record) => {
+				if (format !== "auto") return format === "pretty";
+				const inForce = Context.getOption(record.fiber.context, Audience);
+				return (Option.isSome(inForce) ? inForce.value.kind : audience?.kind) === "human";
+			};
+			const lowered = LogLevel.isLessThan(level, ambient) ? level : ambient;
+			const isLowered = lowered !== ambient;
+			const render = (record) => {
+				const underActions = underActionsIn(record.fiber);
+				if (!isPretty(record)) {
+					const json = Logger.formatJson.log(record);
+					return underActions ? neutralizeJson(json) : json;
+				}
+				const annotations = record.fiber.getRef(References.CurrentLogAnnotations);
+				const component = annotations.component === void 0 ? "" : ` [${sanitize(String(annotations.component))}]`;
+				const message = sanitize(Array.isArray(record.message) ? record.message.map(String).join(" ") : String(record.message));
+				const name = record.logLevel.toUpperCase();
+				const levelText = paintStyle(LEVEL_STYLES[name] ?? {}, color, name);
+				const cause = record.cause.reasons.length > 0 ? `\n${sanitize(Cause.pretty(record.cause))}` : "";
+				const line = `${record.date.toISOString().slice(11, 23)} ${levelText}${component} ${message}${cause}`;
+				return underActions ? CommandNeutralizer.text(line) : line;
+			};
+			const sink = Logger.make((record) => {
+				if (!passes(record, lowered)) return;
+				record.fiber.getRef(Console.Console).error(render(record));
+			});
+			const floor = (inner) => isLowered ? Logger.make((record) => {
+				const current = record.fiber.getRef(References.MinimumLogLevel);
+				const threshold = current === lowered ? ambient : current;
+				if (LogLevel.isGreaterThanOrEqualTo(record.logLevel, threshold)) inner.log(record);
+			}) : inner;
+			const cliLogger = floor(makeCliLogger(options.logger, underActionsIn));
+			const extras = (options.extraLoggers ?? []).map(floor);
+			if (invalid !== void 0) yield* Effect.logWarning(invalid).pipe(Effect.provideService(Logger.CurrentLoggers, /* @__PURE__ */ new Set([cliLogger])));
+			return Layer.mergeAll(Layer.succeed(CliLog.Level, level), isLowered ? Layer.succeed(References.MinimumLogLevel, lowered) : Layer.empty, Layer.effect(Logger.CurrentLoggers, Effect.gen(function* () {
+				const loggers = [
+					...options.plainLogger === false ? [] : [cliLogger],
+					sink,
+					...extras
+				];
+				if (file !== void 0) {
+					const target = "path" in file ? Option.some(file.path) : yield* Config.option(Config.String(file.envVar)).pipe(Effect.orElseSucceed(() => Option.none()));
+					if (Option.isSome(target) && target.value !== "") {
+						const location = yield* Path.Path;
+						loggers.push(yield* makeFileSink(location.resolve(target.value), lowered, underActionsIn));
+					}
+				}
+				return new Set(loggers);
+			})));
+		}));
+	}
+	/**
+	* Mark the log records an effect emits as coming from `name`.
+	*
+	* @remarks
+	* Shown as `[name]` in pretty output and as `annotations.component` in NDJSON.
+	*
+	* @param name - the component
+	*/
+	static component = (name) => (self) => Effect.annotateLogs(self, "component", name);
+};
+/**
+* The audience while the platform builds, from what needs no platform: a flag in `argv` (the rule `CliAudience` reads
+* argv with), else the override variable, else detection from the environment. No terminal is consulted. Silent: the
+* environment layer warns about an invalid override value itself, once.
+*/
+const buildTimeAudience = (argv, audienceEnvVar, detected) => {
+	const { given, conflict } = scanAudience(argv ?? []);
+	const [flagged] = given;
+	if (!conflict && flagged !== void 0) return Effect.succeed(flagged);
+	return Effect.map(Audience, (audience) => audience.kind).pipe(Effect.provide(Audience.layer(audienceEnvVar === void 0 ? void 0 : { envVar: audienceEnvVar }).pipe(Layer.provide(Layer.succeed(CurrentRuntimeEnv, detected)))), Effect.provideService(Logger.CurrentLoggers, /* @__PURE__ */ new Set()));
+};
+/** What the build-time loggers decide from, read once: the format and the runtime environment to neutralize by. */
+const buildTimeDecision = (options, audienceEnvVar) => Effect.gen(function* () {
+	const detected = yield* Effect.provide(CurrentRuntimeEnv, CurrentRuntimeEnv.layer);
+	const format = options.format ?? "auto";
+	return {
+		ndjson: format === "json" || format === "auto" && (yield* buildTimeAudience(options.argv, audienceEnvVar, detected)) !== "human",
+		runtimeEnv: options.runtimeEnv ?? detected
+	};
+});
+/**
+* The logger the platform is built under by `CliRuntime.main` with `env.log`: the log level and env var apply to
+* what the platform logs while it builds, too.
+*
+* @remarks
+* With `format: "json"`, or `auto` when the build-time audience (`argv`, the override variable, detection) is an
+* agent or a CI, it is the full `CliLog.layer` in NDJSON (that format needs neither the audience nor the terminal,
+* which the platform has not built yet), without the file sink, whose `FileSystem` the platform provides. Otherwise it
+* is the plain `CliLogger`, with `MinimumLogLevel` lowered to the resolved level. Either way it neutralizes under
+* GitHub Actions from the detected environment. The level is resolved silently: the program's own `CliLog.layer` warns
+* about an invalid value, once.
+*
+* @internal
+*/
+const platformLogLayer = (options, audienceEnvVar) => Layer.unwrap(Effect.gen(function* () {
+	const { level } = yield* readLevel(options.level, options.envVar);
+	const ambient = yield* References.MinimumLogLevel;
+	const { ndjson, runtimeEnv } = yield* buildTimeDecision(options, audienceEnvVar);
+	if (ndjson) return CliLog.layer({
+		level,
+		format: "json",
+		...options.plainLogger === void 0 ? {} : { plainLogger: options.plainLogger },
+		...options.logger === void 0 ? {} : { logger: options.logger },
+		...options.extraLoggers === void 0 ? {} : { extraLoggers: options.extraLoggers },
+		...options.neutralize === void 0 ? {} : { neutralize: options.neutralize },
+		runtimeEnv
+	});
+	return Layer.merge(Logger.layer([makeCliLogger(options.logger, actionsDecision(options.neutralize ?? "auto", Option.some(runtimeEnv)))]), LogLevel.isLessThan(level, ambient) ? Layer.succeed(References.MinimumLogLevel, level) : Layer.empty);
+}));
+/**
+* The logger `CliRuntime.main` builds the environment layer under: one line per record, in the build-time format.
+*
+* @remarks
+* What the environment layer logs is a configuration error (an invalid audience override, which interpolates the
+* variable's value), so it is never silenced and never written twice: NDJSON alone for an agent or a CI (`json`, or
+* `auto` for that build-time audience), a plain `CliLogger` line otherwise, whatever `plainLogger` and the diagnostics
+* level say, and neutralized under GitHub Actions like the platform's lines. It goes to stderr alone, whatever
+* `stderrFrom` the program's `CliLogger` options raise, and never to `extraLoggers` or the file sink. Only this
+* logger is pinned to stderr: the platform's build-time logger keeps the host's `stderrFrom`. It floors at `Warning` and installs no
+* `MinimumLogLevel`, so `CliLog.layer`'s own build, which shares this context, reads the ambient minimum.
+*
+* @internal
+*/
+const envBuildLogLayer = (options, audienceEnvVar) => Layer.unwrap(Effect.gen(function* () {
+	const { ndjson, runtimeEnv } = yield* buildTimeDecision(options, audienceEnvVar);
+	const underActions = actionsDecision(options.neutralize ?? "auto", Option.some(runtimeEnv));
+	if (!ndjson) return Logger.layer([makeCliLogger({
+		...options.logger,
+		stderrFrom: "All"
+	}, underActions)]);
+	return Logger.layer([Logger.make((record) => {
+		if (!LogLevel.isGreaterThanOrEqualTo(record.logLevel, "Warn")) return;
+		const json = Logger.formatJson.log(record);
+		record.fiber.getRef(Console.Console).error(underActions(record.fiber) ? neutralizeJson(json) : json);
+	})]);
+}));
+
+//#endregion
+export { CliLog, envBuildLogLayer, platformLogLayer };

package/CliLogger.js

@@ -1,9 +1,13 @@
+import { sanitize } from "./Fmt.js";
+import { TrustedLine, sanitizeParts, underActionsIn } from "./internal/logSafety.js";
 import { Console, LogLevel, Logger, References } from "effect";
+import { CommandNeutralizer } from "@effected/github-commands";
 
 //#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.
+* A `Logger` that renders CLI output rather than service logs: no timestamp, level or fiber id, with every level
+* going to stderr by default so stdout carries only what the program writes.
 *
 * @remarks
 * Effect's default logger emits `[00:33:56.619] INFO (#2): message`. That is
@@ -12,27 +16,15 @@ const defaultRender = (message) => Array.isArray(message) ? message.map(String).
 * 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.
+* **A program that never installs a CLI logger looks correct in review and
+* ships timestamps to its users**, so install this one at the program's
+* boundary.
 *
-* ## 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.
+* It writes through the `Console` reference read off the logging fiber,
+* synchronously, as core's own default logger does: `Logger.make` takes a
+* synchronous callback, and a `Stdio` sink write is an `Effect` a logger cannot
+* `yield*`. `Console.Console` is a `Context.Reference`, so it never appears in
+* `R`, and a test swaps the reference rather than stubbing a global.
 *
 * @example
 * ```ts
@@ -48,12 +40,10 @@ const defaultRender = (message) => Array.isArray(message) ? message.map(String).
 * 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).
+* `stderrFrom: "Error"` for a tool whose output *is* its log lines.
 *
 * @public
 */
@@ -66,14 +56,7 @@ var CliLogger = class CliLogger {
 	* 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 ?? "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));
-		});
-	};
+	static make = (options = {}) => makeCliLogger(options);
 	/**
 	* Replace the default logger with this one.
 	*
@@ -86,6 +69,24 @@ var CliLogger = class CliLogger {
 	*/
 	static layer = (options = {}) => Logger.layer([CliLogger.make(options)]);
 };
+/**
+* `CliLogger.make`, with the neutralizing decision as a parameter: `CliLog.layer` passes its own (the fiber's
+* `CurrentRuntimeEnv`, else the one captured at build, or its `neutralize` option), so its plain line and its
+* diagnostics line are neutralized alike.
+*
+* @internal
+*/
+const makeCliLogger = (options = {}, underActions = underActionsIn) => {
+	const custom = options.render;
+	const render = custom ?? defaultRender;
+	const stderrFrom = options.stderrFrom ?? "All";
+	return Logger.make(({ fiber, logLevel, message }) => {
+		const console = fiber.getRef(Console.Console);
+		const write = fiber.getRef(References.LogToStderr) || LogLevel.isGreaterThanOrEqualTo(logLevel, stderrFrom) ? console.error : console.log;
+		const rendered = fiber.getRef(TrustedLine) ? render(message) : custom === void 0 ? sanitize(render(message)) : render(sanitizeParts(message));
+		write(underActions(fiber) ? CommandNeutralizer.text(rendered) : rendered);
+	});
+};
 
 //#endregion
-export { CliLogger };
+export { CliLogger, makeCliLogger };