@effected/env 0.1.0

package/Audience.js

@@ -0,0 +1,94 @@
+import { CurrentRuntimeEnv } from "./RuntimeEnv.js";
+import { Config, Context, Effect, Layer, Option } from "effect";
+
+//#region src/Audience.ts
+const KINDS = [
+	"human",
+	"agent",
+	"ci"
+];
+/**
+* Who the output is for, decided once.
+*
+* @remarks
+* Precedence: a valid override environment variable, then an agent, then CI, then a human, so an agent inside a
+* CI job gets agent output. A human typing a command inside an agent-detected shell is still detected as an
+* agent, never refused: the override variable flips it back. The shape is one immutable value, so the service is
+* provided with `Layer.succeed` and there is no `Layer.mock` to reach for.
+*
+* @example
+* ```ts
+* import { Audience, CurrentRuntimeEnv } from "@effected/env"
+* import { Effect, Layer } from "effect"
+*
+* const AudienceLive = Audience.layer({ envVar: "MYTOOL_AUDIENCE" }).pipe(Layer.provide(CurrentRuntimeEnv.layer))
+*
+* const program = Effect.gen(function* () {
+* 	const { kind, source } = yield* Audience
+* 	return `${kind} (${source})`
+* }).pipe(Effect.provide(AudienceLive))
+* ```
+*
+* @public
+*/
+var Audience = class Audience extends Context.Service()("@effected/env/Audience") {
+	/**
+	* Decide the audience from `CurrentRuntimeEnv`, and from the override variable named by `options.envVar`.
+	*
+	* @remarks
+	* The variable is read through `Config`, lower-cased and matched against `human`, `agent` and `ci`. An empty
+	* or absent variable is unset. An invalid value logs one warning through `Effect.logWarning` and falls back to
+	* detection; it never fails the run. That warning is once per layer build, so building the layer a second time
+	* warns again. The warning goes through `Effect.logWarning`, and Effect's default logger writes to stdout unless
+	* `References.LogToStderr` is set: an MCP server or any stdio-sensitive host must route logs to stderr (the `cli`
+	* package's `CliLogger` does). Without `options.envVar` the audience is always detected. A layer-returning function
+	* mints a fresh layer per call: call it once and bind the result to a constant.
+	*
+	* @param options - `envVar` names the override variable
+	*/
+	static layer(options) {
+		return Layer.effect(Audience, Effect.gen(function* () {
+			const runtimeEnv = yield* CurrentRuntimeEnv;
+			const detected = {
+				kind: Audience.detect(runtimeEnv),
+				source: "detected"
+			};
+			const envVar = options?.envVar;
+			if (envVar === void 0) return detected;
+			const raw = yield* Config.option(Config.String(envVar)).pipe(Effect.orElseSucceed(() => Option.none()));
+			if (Option.isNone(raw) || raw.value === "") return detected;
+			const value = raw.value.toLowerCase();
+			const kind = KINDS.find((candidate) => candidate === value);
+			if (kind !== void 0) return {
+				kind,
+				source: "override"
+			};
+			yield* Effect.logWarning(`${envVar}=${raw.value} is not one of ${KINDS.join("|")}; ignoring it`);
+			return detected;
+		}));
+	}
+	/**
+	* A fixed audience that touches neither `CurrentRuntimeEnv` nor `Config`.
+	*
+	* @remarks
+	* `source` defaults to `override`, since a test that fixes the kind has decided it. Pass `detected` to test a
+	* layer stacked on top, such as a CLI flag that only applies when the environment variable did not decide, or
+	* `flag` to test a consumer of that layer's result.
+	*
+	* @param kind - the audience to fix
+	* @param source - what decided it: `override` (the default), `detected`, or `flag`
+	*/
+	static layerTest = (kind, source = "override") => Layer.succeed(Audience, {
+		kind,
+		source
+	});
+	/**
+	* The audience a {@link RuntimeEnv} implies, ignoring any override: an agent, else CI, else a human.
+	*
+	* @param env - the runtime snapshot to decide from
+	*/
+	static detect = (env) => Option.isSome(env.agent) ? "agent" : Option.isSome(env.ci) ? "ci" : "human";
+};
+
+//#endregion
+export { Audience };

package/EnvOverride.js

@@ -0,0 +1,109 @@
+import { Audience } from "./Audience.js";
+import { Config, ConfigProvider, Effect, Option } from "effect";
+
+//#region src/EnvOverride.ts
+const isProvider = (source) => typeof source.load === "function";
+/**
+* Reads an environment variable that picks a mode within an audience.
+*
+* @remarks
+* The kit never learns a consumer's literals: the caller passes, per audience, the values it accepts.
+*
+* @public
+*/
+var EnvOverride = class EnvOverride {
+	constructor() {}
+	/**
+	* Read `options.envVar` and say what happened, without logging.
+	*
+	* @remarks
+	* `accepted` is the literal the current audience accepts (matching is case-insensitive and yields the
+	* literal), `rejected` is a set value it does not, with the value as written, the audience and the literals
+	* that audience accepts, so the caller owns the wording, the stream and any once-per-run dedupe. Unset and
+	* empty are neither. At most one of the two is `Some`. {@link EnvOverride.read} is the logging convenience.
+	*
+	* The variable is read from the ambient `ConfigProvider` unless `source` is given: a record (read fresh on every
+	* call, so a host passing `process.env` sees each change, and an `undefined` value is unset) or a `ConfigProvider`
+	* of its own.
+	*
+	* Without `source`, every read takes the `ConfigProvider` of the fiber that runs it, so a reader built once at
+	* module level stays testable: a test provides its own provider around the read.
+	*
+	* ```ts
+	* const consoleMode = EnvOverride.readResult({ envVar: "MYTOOL_CONSOLE", accepts })
+	* // in a test:
+	* consoleMode.pipe(
+	*   Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromUnknown({ MYTOOL_CONSOLE: "silent" })),
+	* )
+	* ```
+	*
+	* `source` is for a long-lived host that must re-read a record on each call (`process.env` in a watch-mode runner,
+	* where core's default provider snapshots the environment once). It is fixed when the options object is built, so a
+	* host that wants it AND testability builds the options inside a function that takes the source:
+	*
+	* ```ts
+	* const consoleModeFrom = (source: Readonly<Record<string, string | undefined>>) =>
+	*   EnvOverride.readResult({ envVar: "MYTOOL_CONSOLE", accepts, source })
+	* // production: consoleModeFrom(process.env); a test: consoleModeFrom({ MYTOOL_CONSOLE: "silent" })
+	* ```
+	*
+	* @param options - `envVar` is the variable; `accepts` lists, per audience, the literals it accepts; `source`, if
+	*   given, is where the variable is read in place of the ambient environment: a long-lived host's record, re-read
+	*   on every call, or a `ConfigProvider`; omit it to read the fiber's `ConfigProvider`, which a test provides
+	*/
+	static readResult(options) {
+		return Effect.gen(function* () {
+			const { kind } = yield* Audience;
+			const config = Config.option(Config.String(options.envVar));
+			const { source } = options;
+			const raw = source === void 0 ? yield* config.pipe(Effect.orElseSucceed(() => Option.none())) : yield* config.parse(isProvider(source) ? source : ConfigProvider.fromEnvRecord({ ...source })).pipe(Effect.orElseSucceed(() => Option.none()));
+			if (Option.isNone(raw) || raw.value === "") return {
+				audience: kind,
+				accepted: Option.none(),
+				rejected: Option.none()
+			};
+			const accepts = options.accepts[kind];
+			const match = accepts.find((literal) => literal.toLowerCase() === raw.value.toLowerCase());
+			if (match !== void 0) return {
+				audience: kind,
+				accepted: Option.some(match),
+				rejected: Option.none()
+			};
+			return {
+				audience: kind,
+				accepted: Option.none(),
+				rejected: Option.some({
+					value: raw.value,
+					audience: kind,
+					accepts
+				})
+			};
+		});
+	}
+	/**
+	* Read `options.envVar` and accept it only when the current audience accepts it.
+	*
+	* @remarks
+	* Matching is case-insensitive and yields the accepted literal, so the result narrows to the union of every
+	* audience's literals. An unset or empty variable is `None`. A value the current audience does not accept logs
+	* one warning through `Effect.logWarning`, naming the accepted values, and is `None`; it never fails the run.
+	* The warning is once per read, so reading again warns again. It goes through `Effect.logWarning`, and Effect's
+	* default logger writes to stdout unless `References.LogToStderr` is set: an MCP server or any stdio-sensitive
+	* host must route logs to stderr (the `cli` package's `CliLogger` does).
+	*
+	* @param options - `envVar` is the variable; `accepts` lists, per audience, the literals it accepts
+	*/
+	static read(options) {
+		return Effect.gen(function* () {
+			const { accepted, rejected } = yield* EnvOverride.readResult(options);
+			if (Option.isSome(rejected)) {
+				const { value, audience, accepts } = rejected.value;
+				yield* Effect.logWarning(`${options.envVar}=${value} is not accepted for the ${audience} audience (accepts ${accepts.join("|")}); ignoring it`);
+			}
+			return accepted;
+		});
+	}
+};
+
+//#endregion
+export { EnvOverride };

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,102 @@
+# @effected/env
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fenv?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/env)
+[![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/)
+
+Effect-native environment detection for any front end of a tool: **who is running it** (an AI agent, a CI job, or neither), **what the terminal can do** (colour level, OSC 8 hyperlinks and width, per stream), and **who the output is for** (a human, an agent or CI). Every answer is read once through `Config`, never from `process`, and every service has a `layerTest`, so a test sets the environment it wants without touching a global.
+
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line 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. Full
+> policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/env
+
+Every tool that prints ends up asking these questions, usually by reading `process.env` and `process.stdout.isTTY` wherever the answer is needed. The answers then drift (the help text and the report disagree about colour), they cannot be tested without mutating globals, and the rules are subtle: `FORCE_COLOR` beats `NO_COLOR`, an empty `NO_COLOR` means unset, `TERM=dumb` is a terminal that cannot move the cursor, a Windows console sets no `TERM` at all yet draws truecolor, and an agent running inside CI should get agent output.
+
+This package makes each decision once, as a service, from rules taken from established sources: colour depth from Node's own `getColorDepth` (with `OS=Windows_NT` standing in for its platform check, which gives a Windows terminal truecolor as Node does from Windows 10 build 14931), hyperlink support from std-osc8's terminal table, and agent detection from std-env's table.
+
+## Install
+
+```bash
+npm install @effected/env effect
+```
+
+```bash
+pnpm add @effected/env effect
+```
+
+Requires Node.js >=24.11.0. `effect` v4 is the only peer. There are no runtime dependencies, no platform import and no `@effected/*` edge, so it runs unchanged on Node, Bun and Deno.
+
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED`. Import from an ES module.
+
+## Quick start
+
+Decide the audience once, as a service, and let anything that prints ask it:
+
+```ts
+import { Audience, CurrentRuntimeEnv } from "@effected/env";
+import { Effect, Layer } from "effect";
+
+// A valid MYTOOL_AUDIENCE beats detection; then an agent, then CI, then a human.
+const AudienceLive = Audience.layer({ envVar: "MYTOOL_AUDIENCE" }).pipe(Layer.provide(CurrentRuntimeEnv.layer));
+
+const program = Effect.gen(function* () {
+  const audience = yield* Audience;
+  if (audience.kind === "agent") {
+    // plain text, no escapes
+  }
+});
+
+Effect.runPromise(program.pipe(Effect.provide(AudienceLive)));
+```
+
+What the terminal can do comes from `TerminalEnv`, which reads core's `Stdio` and `Terminal` from your platform layer:
+
+```ts
+import { TerminalEnv } from "@effected/env";
+import { NodeServices } from "@effect/platform-node";
+import { Effect } from "effect";
+
+const describe = Effect.gen(function* () {
+  const terminal = yield* TerminalEnv;
+  return `${terminal.stdout.color} colour, ${terminal.width()} columns`;
+});
+
+Effect.runPromise(describe.pipe(Effect.provide(TerminalEnv.layer()), Effect.provide(NodeServices.layer)));
+```
+
+In a test, fix the answers instead:
+
+```ts
+import { Audience, TerminalEnv } from "@effected/env";
+import { Layer, Option } from "effect";
+
+const Environment = Layer.mergeAll(
+  Audience.layerTest("agent"),
+  TerminalEnv.layerTest({ stdout: { isTerminal: true, color: "256", columns: Option.some(120) } }),
+);
+```
+
+## What it exports
+
+- **`RuntimeEnv`**: a schema-class snapshot of the agent, the CI and the terminal program, persistable as plain JSON. `RuntimeEnv.fromRecord(env)` builds one as a pure function.
+- **`CurrentRuntimeEnv`**: that snapshot as a service. `layer` reads the ambient `ConfigProvider` once; `layerFrom(source)` reads a record or provider of your own, fresh on every use, for a long-lived host; `layerTest(overrides)` fixes it.
+- **`TerminalEnv`**: per-stream `isTerminal`, colour level (`none`, `basic`, `256`, `truecolor`), `hyperlinks` and `columns`, plus `width(fallback)`. `layer()` needs `Stdio` and `Terminal`; `layerStdio()` needs only `Stdio`; `colorLevel("stdout")` decides colour alone.
+- **`Audience`**: `human`, `agent` or `ci`, and the `source` that decided it. `layer({ envVar })` decides from `CurrentRuntimeEnv` and an override variable you name.
+- **`EnvOverride`**: reads a variable that picks a mode *within* an audience, accepting only the literals you list per audience. `readResult` reports without logging; `read` logs one warning for a rejected value.
+
+## Documentation
+
+The guides and the full API reference are at [effected.spencerbeg.gs/env](https://effected.spencerbeg.gs/env). [`@effected/cli`](https://www.npmjs.com/package/@effected/cli) builds its whole presentation layer on these services.
+
+## License
+
+[MIT](LICENSE)

package/RuntimeEnv.js

@@ -0,0 +1,117 @@
+import { detectAgent, detectCi } from "./internal/agentCi.js";
+import { normalizeEnv, readEnv } from "./internal/envRecord.js";
+import { detectOsc8 } from "./internal/osc8/detect.js";
+import { allKeys } from "./internal/keys.js";
+import { ConfigProvider, Context, Effect, Layer, Option, Schema } from "effect";
+
+//#region src/RuntimeEnv.ts
+/**
+* An `Option` field that encodes `None` as `null` and decodes when its key is absent, so a persisted snapshot keeps
+* decoding after a field is added.
+*/
+const optionField = (schema) => Schema.OptionFromNullOr(schema).pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed(Option.none())));
+/**
+* A snapshot of who is running the program: the agent, the CI, and the terminal.
+*
+* @remarks
+* Each field is an `Option` in memory and `null` when absent on the wire, so the snapshot persists as plain JSON
+* through `Schema.fromJsonString(RuntimeEnv)`. Every field decodes when its key is absent, so a persisted snapshot
+* keeps decoding after a field is added. Built from `Config` only (no stream is consulted), so it is safe inside a
+* stdio MCP server.
+*
+* @public
+*/
+var RuntimeEnv = class RuntimeEnv extends Schema.Class("@effected/env/RuntimeEnv")({
+	/**
+	* The AI agent running the process, as its family (`claude` for Claude Code, whatever `AI_AGENT` says it is
+	* beyond that), or `None`.
+	*/
+	agent: optionField(Schema.String),
+	/** The CI the process runs in: {@link CiName}, so a consumer can match it exhaustively, or `None`. */
+	ci: optionField(Schema.Literals(["github-actions", "generic"])),
+	/** The identified terminal program and its version when it exposes one, or `None`. */
+	terminal: optionField(Schema.Struct({
+		name: Schema.String,
+		version: optionField(Schema.String)
+	}))
+}) {
+	/**
+	* The snapshot of an environment record, as a pure function: no `Config`, no `process`, no service.
+	*
+	* @remarks
+	* It is what {@link CurrentRuntimeEnv.layer} computes from the variables it reads, so the two agree on the same
+	* record. An `undefined` or empty value reads as unset, under every caller. Use it where a service is in the
+	* way: a long-lived host that holds its own environment record, or a renderer with no Effect context.
+	*
+	* @param env - variable name to value
+	*/
+	static fromRecord(env) {
+		const clean = normalizeEnv(env);
+		return RuntimeEnv.make({
+			agent: detectAgent(clean),
+			ci: detectCi(clean),
+			terminal: detectOsc8(clean, false, false).terminal
+		});
+	}
+};
+/**
+* The {@link RuntimeEnv} of the running process, as a service.
+*
+* @remarks
+* The service's whole shape is one immutable value, so it is provided with `Layer.succeed` rather than mocked.
+* `layer` reads the ambient `ConfigProvider` once when it is built; `layerTest` is the only way a test changes the
+* environment.
+*
+* @example
+* ```ts
+* import { CurrentRuntimeEnv } from "@effected/env"
+* import { Effect, Option } from "effect"
+*
+* const program = Effect.gen(function* () {
+* 	const env = yield* CurrentRuntimeEnv
+* 	return Option.getOrElse(env.agent, () => "no agent")
+* }).pipe(Effect.provide(CurrentRuntimeEnv.layerTest({ agent: Option.some("claude") })))
+* ```
+*
+* @public
+*/
+var CurrentRuntimeEnv = class CurrentRuntimeEnv extends Context.Service()("@effected/env/CurrentRuntimeEnv") {
+	/**
+	* Reads the environment through `Config` once, when the layer is built. Requires nothing: the provider is read
+	* from the ambient `ConfigProvider`.
+	*
+	* @remarks
+	* Two things make this a frozen read, and a long-lived host (an MCP server, a watch-mode runner) trips on both.
+	* Core's default `ConfigProvider.fromEnv()` snapshots `process.env` once per process, so a change after the
+	* first read is never seen; and this is one static layer, memoized by reference, so two consumers that provide
+	* different providers in one graph share the first snapshot. Use {@link CurrentRuntimeEnv.layerFrom}, which is
+	* a fresh layer per call and per use, or provide a fresh `ConfigProvider` for every read.
+	*/
+	static layer = Layer.effect(this, Effect.map(readEnv(allKeys), (env) => RuntimeEnv.fromRecord(env)));
+	/**
+	* A snapshot of an explicit source: an environment record, or a `ConfigProvider` read instead of the ambient
+	* one.
+	*
+	* @remarks
+	* Each call returns a new layer, and the layer is `Layer.fresh`, so it is built again for every use rather
+	* than shared through the build's memo: two calls with different sources in one graph see different values,
+	* and a provider is read again each time the layer is used. A record is read when the layer is built, never
+	* at the call.
+	*
+	* @param source - a variable-name-to-value record, or a `ConfigProvider`
+	*/
+	static layerFrom = (source) => Layer.fresh(Layer.effect(CurrentRuntimeEnv, typeof source.load === "function" ? Effect.map(readEnv(allKeys).pipe(Effect.provideService(ConfigProvider.ConfigProvider, source)), (env) => RuntimeEnv.fromRecord(env)) : Effect.sync(() => RuntimeEnv.fromRecord(source))));
+	/**
+	* A fixed snapshot that never touches `Config`: every field is `None` unless `overrides` sets it.
+	*
+	* @param overrides - the fields to set
+	*/
+	static layerTest = (overrides = {}) => Layer.succeed(CurrentRuntimeEnv, RuntimeEnv.make({
+		agent: overrides.agent ?? Option.none(),
+		ci: overrides.ci ?? Option.none(),
+		terminal: overrides.terminal ?? Option.none()
+	}));
+};
+
+//#endregion
+export { CurrentRuntimeEnv, RuntimeEnv };

package/TerminalEnv.js

@@ -0,0 +1,144 @@
+import { readEnv } from "./internal/envRecord.js";
+import { colorDepth, colorKeys } from "./internal/colorDepth.js";
+import { detectOsc8 } from "./internal/osc8/detect.js";
+import { allKeys } from "./internal/keys.js";
+import { Context, Effect, Layer, Option, Stdio, Terminal } from "effect";
+
+//#region src/TerminalEnv.ts
+const make = (env, isTTY, columns) => {
+	const links = detectOsc8(env, isTTY.stdout, isTTY.stderr);
+	const fromEnv = /^\d+$/.test(env.COLUMNS ?? "") ? Number(env.COLUMNS) : 0;
+	return {
+		stdinIsTerminal: isTTY.stdin,
+		stdout: {
+			isTerminal: isTTY.stdout,
+			color: colorDepth(env, isTTY.stdout),
+			hyperlinks: links.stdout,
+			columns
+		},
+		stderr: {
+			isTerminal: isTTY.stderr,
+			color: colorDepth(env, isTTY.stderr),
+			hyperlinks: links.stderr,
+			columns
+		},
+		width: (fallback = 80) => Option.getOrElse(columns, () => fromEnv || fallback)
+	};
+};
+/** Read the TTY facts from `Stdio` and the environment from `Config`, with the width the caller already knows. */
+const snapshot = (options, columns) => Effect.gen(function* () {
+	const stdio = yield* Stdio.Stdio;
+	const stdin = yield* stdio.stdinIsTerminal;
+	const stdout = yield* stdio.stdoutIsTerminal;
+	const stderr = yield* options?.stderrIsTerminal ?? Effect.succeed(stdout);
+	const env = yield* readEnv([...allKeys, "COLUMNS"]);
+	return make(env, {
+		stdin,
+		stdout,
+		stderr
+	}, columns);
+});
+/** The quiet terminal {@link TerminalEnv.layerTest} starts from: not a terminal, no colour, no links, no width. */
+const quiet = {
+	isTerminal: false,
+	color: "none",
+	hyperlinks: false,
+	columns: Option.none()
+};
+/**
+* What the terminal can do: per-stream colour level, hyperlink support and columns, and the width to lay out at.
+*
+* @remarks
+* `layer` reads the environment through `Config` and the TTY state through `Stdio` and `Terminal` once, when it
+* is built. `layerTest` is the only way a test changes it, and defaults to a quiet terminal so a test opts into
+* colour. `colorLevel` needs `Stdio` alone, so a caller that only decides colour never requires `Terminal`.
+*
+* @example
+* ```ts
+* import { TerminalEnv } from "@effected/env"
+* import { Effect, Option } from "effect"
+*
+* const program = Effect.gen(function* () {
+* 	const terminal = yield* TerminalEnv
+* 	return { color: terminal.stdout.color, width: terminal.width() }
+* }).pipe(Effect.provide(TerminalEnv.layerTest({ stdout: { color: "256", columns: Option.some(100) } })))
+* ```
+*
+* @public
+*/
+var TerminalEnv = class TerminalEnv extends Context.Service()("@effected/env/TerminalEnv") {
+	/**
+	* Build the snapshot from `Stdio`, `Terminal` and the ambient `ConfigProvider`.
+	*
+	* @remarks
+	* `Stdio` reports only stdout, so stderr mirrors it unless `options.stderrIsTerminal` supplies its own answer.
+	* A layer-returning function mints a fresh layer per call: call it once and bind the result to a constant.
+	*
+	* @param options - `stderrIsTerminal` overrides the stderr TTY check
+	*/
+	static layer(options) {
+		return Layer.effect(TerminalEnv, Effect.gen(function* () {
+			const width = yield* (yield* Terminal.Terminal).columns;
+			return yield* snapshot(options, width > 0 ? Option.some(width) : Option.none());
+		}));
+	}
+	/**
+	* The snapshot from `Stdio` and the ambient `ConfigProvider` alone: it never requires or builds `Terminal`, and
+	* reports no columns.
+	*
+	* @remarks
+	* Everything else is what {@link TerminalEnv.layer} reports: the TTY facts come from `Stdio`, the colour and
+	* hyperlink decisions from the environment, and `width()` falls back to `COLUMNS`, then the fallback, since no
+	* terminal width is known. Use it where building the platform `Terminal` has a cost, for example a long-lived
+	* host, where `NodeTerminal` listens on `process.stdin`. A layer-returning function mints a fresh layer per
+	* call: call it once and bind the result to a constant.
+	*
+	* @param options - `stderrIsTerminal` overrides the stderr TTY check
+	*/
+	static layerStdio(options) {
+		return Layer.effect(TerminalEnv, snapshot(options, Option.none()));
+	}
+	/**
+	* A fixed snapshot that touches neither `Stdio`, `Terminal` nor `Config`. Everything is quiet unless a field of
+	* `partial` sets it.
+	*
+	* @param partial - the fields to set; `stdout` and `stderr` are merged over the quiet stream
+	*/
+	static layerTest = (partial) => {
+		const stdout = {
+			...quiet,
+			...partial?.stdout
+		};
+		return Layer.succeed(TerminalEnv, {
+			stdinIsTerminal: partial?.stdinIsTerminal ?? false,
+			stdout,
+			stderr: {
+				...quiet,
+				...partial?.stderr
+			},
+			width: (fallback = 80) => Option.getOrElse(stdout.columns, () => fallback)
+		});
+	};
+	/**
+	* The colour level of a stream.
+	*
+	* @remarks
+	* An ambient `TerminalEnv`, when one is provided, answers with its stdout colour, so a test that fixes the
+	* terminal with `layerTest` also fixes this. Without one it is decided from `Config` and `Stdio` alone. It
+	* requires only `Stdio`, never `Terminal` or `TerminalEnv`, so a caller that only decides colour (a CLI's
+	* output formatter) keeps a `Stdio`-only requirement.
+	*
+	* @param _stream - the stream to decide for; only `stdout` is available, since `Stdio` reports no other
+	*/
+	static colorLevel(_stream) {
+		return Effect.gen(function* () {
+			const ambient = yield* Effect.serviceOption(TerminalEnv);
+			if (Option.isSome(ambient)) return ambient.value.stdout.color;
+			const isTTY = yield* (yield* Stdio.Stdio).stdoutIsTerminal;
+			return colorDepth(yield* readEnv(colorKeys), isTTY);
+		});
+	}
+};
+
+//#endregion
+export { TerminalEnv };