@effected/cli-kit 0.0.0-stage → 0.26.0

package/CliLog.js

@@ -0,0 +1,367 @@
+import { makeCliLogger } from "./CliLogger.js";
+import { CliTheme } from "./CliTheme.js";
+import { sanitize } from "./Fmt.js";
+import { paintStyle } from "./internal/ansi.js";
+import { Level, passes } from "./internal/diagnostics.js";
+import { makeFileSink } from "./internal/fileSink.js";
+import { TrustedLine, neutralizeJson } from "./internal/logSafety.js";
+import { scanAudience } from "./internal/scanAudience.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";
+
+// src/CliLog.ts
+/** The most spaces a numeric `indent` writes. */
+const MAX_INDENT = 64;
+/** An indent as written before the glyph: spaces for a number, a string with nothing in it that is not text. */
+const indentOf = (indent) => {
+	if (indent === void 0) return "";
+	if (typeof indent === "number") return Number.isFinite(indent) && indent > 0 ? " ".repeat(Math.min(MAX_INDENT, Math.floor(indent))) : "";
+	return sanitize(indent).replace(/\r\n|\r|\n/g, "");
+};
+/** The accepted spellings of a level, lower-cased, to the level they mean. A `Map`, so no inherited key matches. */
+const LEVELS = /* @__PURE__ */ new Map([
+	["all", "All"],
+	["trace", "Trace"],
+	["debug", "Debug"],
+	["info", "Info"],
+	["warn", "Warn"],
+	["warning", "Warn"],
+	["error", "Error"],
+	["fatal", "Fatal"],
+	["none", "None"]
+]);
+/** A level's spelling, in any case, to the level it means. */
+const parseLevel = (text) => Option.fromUndefinedOr(LEVELS.get(text.toLowerCase()));
+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 = parseLevel(raw.value);
+	if (Option.isSome(level)) return {
+		level: level.value,
+		invalid: void 0
+	};
+	return {
+		level: "None",
+		invalid: `${envVar}=${raw.value} is not a log level (${[...LEVELS.keys()].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-kit"
+* 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;
+	/**
+	* Read a log level the way `CliLog.layer` reads its environment variable: `Option.some` of the level, or
+	* `Option.none()` when the text is not one.
+	*
+	* @remarks
+	* Case-insensitive, and not trimmed. The spellings are `all`, `trace`, `debug`, `info`, `warn` (or `warning`),
+	* `error`, `fatal` and `none`. For a host that reads a level from its own flag or config and wants the same answer
+	* the layer would give.
+	*
+	* @example
+	* ```ts
+	* CliLog.parseLevel("WARNING") // Option.some("Warn")
+	* CliLog.parseLevel("loud") // Option.none()
+	* ```
+	*
+	* @param text - the level's spelling
+	*/
+	static parseLevel(text) {
+		return parseLevel(text);
+	}
+	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);
+			})));
+		}));
+	}
+	/**
+	* Log a status line: its glyph painted through the theme, then `text`, at a level that follows the status.
+	*
+	* @remarks
+	* The line goes through the logger, so it is a diagnostic like any `Effect.log*` call: filtered by the level in
+	* force (`--log-level`, `CliLog.Level`), routed by `CliLogger`'s `stderrFrom` (stderr by default) and neutralized
+	* under GitHub Actions. What differs is the glyph: the logger sanitises every line a program logs, which strips a
+	* colour a program painted itself, so a glyph on the log channel was always drawn bare. Here the kit paints it and
+	* marks the line as its own, so the plain `CliLogger` line keeps the colour, while `text` is still sanitised:
+	* escape sequences and control characters in it are removed, as in every line the kit writes.
+	*
+	* The glyph is painted with stderr's theme (where diagnostics go) through {@link CliTheme.forAudience}, so an agent
+	* gets it unpainted, and an `Audience` is read only when provided, so it stays out of the requirements. ASCII glyphs
+	* give the status's ASCII form. A diagnostics record carries the line as its message as any record does: the `CliLog`
+	* sink's pretty line sanitises it (the glyph is drawn bare there), and NDJSON keeps it, JSON-escaped.
+	*
+	* The level defaults to the status's rank in `vocab`: `Error` at or above `failure`'s, `Warn` at or above
+	* `warning`'s, `Info` below, so a custom status follows its own rank. Pass `level` to choose it, and `indent` (a
+	* number of spaces, or a string, sanitised) to start the line inside an indented block: `    ✗ error   x: red`.
+	*
+	* @example
+	* ```ts
+	* import { CliLog, Status } from "@effected/cli-kit"
+	*
+	* // ✗ in the failure colour, then the message: on stderr, filtered by the log level.
+	* const reportError = (resource: string, message: string) =>
+	*   CliLog.status(Status.core, "failure", `${resource}: ${message}`)
+	* ```
+	*
+	* @param vocab - the vocabulary the status belongs to
+	* @param name - the status
+	* @param text - the text after the glyph, sanitised
+	* @param options - the level to log at, and the indent before the glyph
+	*/
+	static status = (vocab, name, text, options) => Effect.gen(function* () {
+		const audience = yield* Effect.serviceOption(Audience);
+		const theme = CliTheme.forAudience((yield* CliTheme).forStream("stderr"), Option.isSome(audience) ? audience.value.kind : void 0);
+		const line = `${indentOf(options?.indent)}${theme.status(vocab, name, sanitize(text))}`;
+		const core = vocab;
+		const rank = vocab.def(name).rank;
+		const level = options?.level ?? (rank >= core.def("failure").rank ? "Error" : rank >= core.def("warning").rank ? "Warn" : "Info");
+		yield* Effect.logWithLevel(level)(line).pipe(Effect.provideService(TrustedLine, true));
+	});
+	/**
+	* 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);
+	})]);
+}));
+
+export { CliLog, envBuildLogLayer, platformLogLayer };

package/CliLogger.js

@@ -0,0 +1,91 @@
+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";
+
+// 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: 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
+* 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.
+*
+* **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.
+*
+* 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
+* import { CliLogger } from "@effected/cli-kit"
+* import { Console, Effect } from "effect"
+*
+* const program = Effect.gen(function* () {
+*   yield* Effect.log("synced 3 repos")    // stderr, no timestamp — a diagnostic
+*   yield* Console.log("3 repos synced")   // stdout — the program's actual output
+*   yield* Effect.logError("one failed")   // stderr
+* })
+*
+* program.pipe(Effect.provide(CliLogger.layer()))
+* ```
+*
+* `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.
+*
+* @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 = {}) => makeCliLogger(options);
+	/**
+	* 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)]);
+};
+/**
+* `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);
+	});
+};
+
+export { CliLogger, makeCliLogger };

package/CliMessage.js

@@ -0,0 +1,79 @@
+import { CliTheme } from "./CliTheme.js";
+import { sanitize } from "./Fmt.js";
+import { underGithubActions } from "./internal/autoFormat.js";
+import { Status } from "./Status.js";
+import { Console, Effect } from "effect";
+import { Audience } from "@effected/env";
+import { CommandNeutralizer } from "@effected/github-commands";
+
+// src/CliMessage.ts
+/**
+* One-line status messages: a glyph and some text, themed for a person and plain for an agent.
+*
+* @remarks
+* Each line goes through `Console`, `log` for stdout and `error` for stderr, never through the logger, so no
+* log level can silence it. Only the glyph is painted; the text stays plain. An `agent` audience gets the glyph
+* and the text and never colour, even when the theme has colour. `success` and `info` go to stdout, `warning`
+* and `failure` to stderr.
+*
+* The text is whatever the caller supplies, so it is sanitised: escape sequences and control characters are removed
+* (a line break is kept as one, a tab becomes a space), as in a document. Under GitHub Actions, where
+* `CurrentRuntimeEnv` says so, a line the runner would read as a workflow command is neutralized as well. The glyph
+* comes from the vocabulary, sanitised too (`Status.glyph`), so a glyph built from data cannot inject an escape either.
+*
+* @public
+*/
+var CliMessage = class CliMessage {
+	constructor() {}
+	/**
+	* Print a status line from a vocabulary.
+	*
+	* @remarks
+	* The stream defaults to stderr when the status ranks at or above `warning` in `vocab`, and stdout
+	* otherwise, so a custom status follows its own rank: a `timeout` ranked 85 goes to stderr.
+	*
+	* @param vocab - the vocabulary the status belongs to
+	* @param name - the status
+	* @param text - the text after the glyph
+	* @param options - the stream override
+	*/
+	static status = (vocab, name, text, options) => Effect.gen(function* () {
+		const theme = yield* CliTheme;
+		const audience = yield* Audience;
+		const def = vocab.def(name);
+		const message = sanitize(text);
+		const warning = vocab.def("warning").rank;
+		const stream = options?.stream ?? (def.rank >= warning ? "stderr" : "stdout");
+		const streamTheme = theme.forStream(stream);
+		let line;
+		line = CliTheme.forAudience(streamTheme, audience.kind).status(vocab, name, message);
+		if (yield* underGithubActions) line = CommandNeutralizer.text(line);
+		yield* stream === "stderr" ? Console.error(line) : Console.log(line);
+	});
+	/**
+	* A success line, on stdout.
+	*
+	* @param text - the text after the glyph
+	*/
+	static success = (text) => CliMessage.status(Status.core, "success", text);
+	/**
+	* An informational line, on stdout.
+	*
+	* @param text - the text after the glyph
+	*/
+	static info = (text) => CliMessage.status(Status.core, "info", text);
+	/**
+	* A warning line, on stderr.
+	*
+	* @param text - the text after the glyph
+	*/
+	static warning = (text) => CliMessage.status(Status.core, "warning", text);
+	/**
+	* A failure line, on stderr.
+	*
+	* @param text - the text after the glyph
+	*/
+	static failure = (text) => CliMessage.status(Status.core, "failure", text);
+};
+
+export { CliMessage };

package/CliPrompt.js

@@ -0,0 +1,110 @@
+import { Cancelled } from "./Cancelled.js";
+import { CliInteractive } from "./CliInteractive.js";
+import { answerWithoutPerson } from "./internal/fallbackAnswer.js";
+import { WizardDropped } from "./internal/wizardGate.js";
+import { Context, Effect, Layer, Queue, Terminal } from "effect";
+import { CliConfig, GlobalFlag, Prompt } from "effect/cli";
+
+// src/CliPrompt.ts
+/**
+* Prompts that know whether there is a person to ask.
+*
+* @public
+*/
+var CliPrompt = class {
+	constructor() {}
+	/**
+	* A fallback for `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` that only prompts when the run is
+	* interactive.
+	*
+	* @remarks
+	* Interactive (`CliInteractive`): the prompt runs and its answer is used. Not interactive: `otherwise` is used
+	* when given, and the terminal is never read; without it the parameter fails as missing, exactly as it would
+	* with no fallback, so core renders its own message and `CliRuntime.main` exits `64`. Name the parameter with
+	* `flag` (the name without dashes, as given to `Flag.String`) or `argument` so that error can be built.
+	*
+	* Why the prompt runs inside this function rather than being handed back to core: core's
+	* `withFallbackPrompt` turns a quit, such as Ctrl-C, into the original missing-parameter error, which would
+	* exit `64` as if the flag had been forgotten. Here a quit is `Cancelled` with reason `interrupt`, exit `130`.
+	* It is raised as a defect because core's parse step turns every typed failure into a usage error. Core then
+	* runs the already-answered `Prompt.succeed` it is handed. Because it travels as a defect, a handler's
+	* `Effect.catchTag("Cancelled", ...)` cannot see it, and only `CliRuntime.main` (or
+	* `CliRuntime.reportFailures`) renders it as one line with exit `130`; under a bare `runMain` it prints a
+	* stack.
+	*
+	* Core runs `Prompt.run` on the answered prompt it is handed, and an answered prompt never reads the terminal's
+	* input (core acquires it only when a prompt needs a key), so piped stdin is left untouched without any gate.
+	* `CliPrompt.gateTerminal`, which `CliEnv.layer` installs, covers the prompts this function does not wrap.
+	*
+	* Core calls a fallback only when its `TerminalCapabilities.canPrompt` is `true`, and its own default decides that
+	* from the process's terminal, so in a piped run it would fail the parameter as missing without calling this
+	* function and `otherwise` would be lost. `CliInteractive.layer` and `CliInteractive.layerTest` (and so
+	* `CliEnv.layer`) hold `canPrompt` at `true` for that reason: the decision is `CliInteractive`'s, made here. A
+	* `TerminalCapabilities` with `canPrompt: false` provided inside the program bypasses this fallback again, and a
+	* program that sets `CliInteractive` with neither layer keeps core's own gate.
+	*
+	* @param prompt - the prompt to show
+	* @param options - the parameter it stands in for, and the non-interactive default
+	*/
+	static fallback = (prompt, options) => Effect.gen(function* () {
+		if (yield* CliInteractive) {
+			const answer = yield* Prompt.run(prompt).pipe(Effect.catchTag("QuitError", () => Effect.die(new Cancelled({ reason: "interrupt" }))));
+			return Prompt.succeed(answer);
+		}
+		return yield* answerWithoutPerson(options);
+	});
+	/**
+	* Gates core's `Terminal` on `CliInteractive`, so a run that is not interactive never touches the real one.
+	*
+	* @remarks
+	* A prompt that needs a key reads the terminal's input, and the real Node terminal then attaches a readline to
+	* stdin, which drops piped input and puts a TTY stdin into raw mode. Core's `withFallbackPrompt`, a `Prompt.run`
+	* in a handler and the command wizard all do so whether or not anyone is there to answer. Not interactive, this
+	* terminal's input is an already-ended queue, its `readLine` fails as quit and its `display` writes nothing, so
+	* any such prompt is quit at once and the real terminal is never read. Its `columns`, `rows` and `size` always come
+	* from the real one, so layout keeps working. Interactive, every call passes through to the real terminal.
+	*
+	* The decision is made on every call, not when the layer is built, so a scope that narrows `CliInteractive`
+	* later, such as an audience flag under `CliAudience.runWith`, gates it too.
+	*
+	* It requires the real `Terminal`. `CliEnv.layer` installs it, after `TerminalEnv` is built from the real
+	* terminal, so consumers do not compose it.
+	*/
+	static gateTerminal = Layer.effect(Terminal.Terminal, Effect.gen(function* () {
+		const real = yield* Terminal.Terminal;
+		const endedInput = Effect.map(Queue.unbounded(), (queue) => {
+			Queue.endUnsafe(queue);
+			return queue;
+		});
+		return Terminal.make({
+			columns: real.columns,
+			rows: real.rows,
+			size: real.size,
+			readInput: Effect.flatMap(CliInteractive, (interactive) => interactive ? real.readInput : endedInput),
+			readLine: Effect.flatMap(CliInteractive, (interactive) => interactive ? real.readLine : Effect.fail(new Terminal.QuitError({}))),
+			display: (text) => Effect.flatMap(CliInteractive, (interactive) => interactive ? real.display(text) : Effect.void)
+		});
+	}));
+	/**
+	* Drops core's `--wizard` built-in flag when the run is not interactive.
+	*
+	* @remarks
+	* The wizard prompts, so offering it without a terminal only leads to a dead end. With the flag gone, core
+	* treats `--wizard` as an unknown flag, a usage error that exits `64`, and lists it nowhere in `--help`.
+	* The layer reads `CliInteractive` and the ambient `CliConfig` when it is built, so provide those first, for
+	* example `CliPrompt.gateWizard.pipe(Layer.provide(CliInteractive.layer))`. It filters the ambient `CliConfig`,
+	* so a consumer's own `builtIns` survive, and returns it untouched when interactive. An audience flag read
+	* later is covered by `CliAudience.runWith`, which drops the wizard too. When this layer removes the flag it records
+	* that it did, so `runWith` puts it back only when a flag turns interactivity on where this took it away: a
+	* consumer who never had `Wizard` in their `builtIns` keeps it out.
+	*/
+	static gateWizard = Layer.effectContext(Effect.gen(function* () {
+		const ambient = yield* CliConfig.CliConfig;
+		const unchanged = Context.make(CliConfig.CliConfig, ambient);
+		if ((yield* CliInteractive) || !ambient.builtIns.includes(GlobalFlag.Wizard)) return unchanged;
+		const dropped = CliConfig.make({ builtIns: ambient.builtIns.filter((flag) => flag !== GlobalFlag.Wizard) });
+		return Context.make(CliConfig.CliConfig, dropped).pipe(Context.add(WizardDropped, dropped));
+	}));
+};
+
+export { CliPrompt };