@effected/env 0.1.0

package/index.d.ts

@@ -0,0 +1,442 @@
+import { ConfigProvider, Context, Effect, Layer, Option, Schema, Stdio, Terminal } from "effect";
+//#region src/RuntimeEnv.d.ts
+/**
+ * The CI providers a {@link RuntimeEnv} names: `github-actions` when `GITHUB_ACTIONS` is set, `generic` for any other
+ * CI signal (`CI`, `CONTINUOUS_INTEGRATION`).
+ *
+ * @public
+ */
+type CiName = "github-actions" | "generic";
+declare const RuntimeEnv_base: Schema.Class<RuntimeEnv, Schema.Struct<{
+  /**
+   * The AI agent running the process, as its family (`claude` for Claude Code, whatever `AI_AGENT` says it is
+   * beyond that), or `None`.
+   */
+  readonly agent: Schema.withDecodingDefaultTypeKey<Schema.OptionFromNullOr<Schema.String>, never>;
+  /** The CI the process runs in: {@link CiName}, so a consumer can match it exhaustively, or `None`. */
+  readonly ci: Schema.withDecodingDefaultTypeKey<Schema.OptionFromNullOr<Schema.Literals<readonly ["github-actions", "generic"]>>, never>;
+  /** The identified terminal program and its version when it exposes one, or `None`. */
+  readonly terminal: Schema.withDecodingDefaultTypeKey<Schema.OptionFromNullOr<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly version: Schema.withDecodingDefaultTypeKey<Schema.OptionFromNullOr<Schema.String>, never>;
+  }>>, never>;
+}>, {}>;
+/**
+ * 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
+ */
+export declare class RuntimeEnv extends RuntimeEnv_base {
+  /**
+   * 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: Readonly<Record<string, string | undefined>>): RuntimeEnv;
+}
+/**
+ * The fields {@link CurrentRuntimeEnv.layerTest} can override.
+ *
+ * @public
+ */
+interface RuntimeEnvOverrides {
+  /** Replaces the detected agent. */
+  readonly agent?: Option.Option<string>;
+  /** Replaces the detected CI. */
+  readonly ci?: Option.Option<CiName>;
+  /** Replaces the detected terminal. */
+  readonly terminal?: Option.Option<{
+    readonly name: string;
+    readonly version: Option.Option<string>;
+  }>;
+}
+declare const CurrentRuntimeEnv_base: Context.ServiceClass<CurrentRuntimeEnv, "@effected/env/CurrentRuntimeEnv", RuntimeEnv>;
+/**
+ * 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
+ */
+export declare class CurrentRuntimeEnv extends CurrentRuntimeEnv_base {
+  /**
+   * 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 readonly layer: Layer.Layer<CurrentRuntimeEnv>;
+  /**
+   * 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 readonly layerFrom: (source: Readonly<Record<string, string | undefined>> | ConfigProvider.ConfigProvider) => Layer.Layer<CurrentRuntimeEnv>;
+  /**
+   * A fixed snapshot that never touches `Config`: every field is `None` unless `overrides` sets it.
+   *
+   * @param overrides - the fields to set
+   */
+  static readonly layerTest: (overrides?: RuntimeEnvOverrides) => Layer.Layer<CurrentRuntimeEnv>;
+}
+//#endregion
+//#region src/Audience.d.ts
+/**
+ * Who the output is for: a person at a terminal, an AI agent, or a CI job.
+ *
+ * @public
+ */
+type AudienceKind = "human" | "agent" | "ci";
+/**
+ * The shape of the {@link Audience} service: one immutable value.
+ *
+ * @public
+ */
+interface AudienceShape {
+  /** Who the output is for. */
+  readonly kind: AudienceKind;
+  /**
+   * What decided the kind: the override environment variable, detection, or a flag. `Audience.layer` produces
+   * `override` or `detected`; `flag` is for a layer stacked on top (a CLI's `--audience` flag re-provides
+   * `Audience`), which lets its own consumers tell what spoke last.
+   */
+  readonly source: "override" | "detected" | "flag";
+}
+/**
+ * The options {@link Audience.layer} takes.
+ *
+ * @public
+ */
+interface AudienceOptions {
+  /** The environment variable that overrides detection; without it the audience is always detected. */
+  readonly envVar?: string;
+}
+declare const Audience_base: Context.ServiceClass<Audience, "@effected/env/Audience", AudienceShape>;
+/**
+ * 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
+ */
+export declare class Audience extends Audience_base {
+  /**
+   * 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?: AudienceOptions): Layer.Layer<Audience, never, CurrentRuntimeEnv>;
+  /**
+   * 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 readonly layerTest: (kind: AudienceKind, source?: AudienceShape["source"]) => Layer.Layer<Audience>;
+  /**
+   * 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 readonly detect: (env: RuntimeEnv) => AudienceKind;
+}
+//#endregion
+//#region src/ColorLevel.d.ts
+/**
+ * The colour support of one output stream: none, 16 colours, 256 colours or truecolor.
+ *
+ * @public
+ */
+type ColorLevel = "none" | "basic" | "256" | "truecolor";
+//#endregion
+//#region src/EnvOverride.d.ts
+/**
+ * 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
+ */
+export declare class EnvOverride {
+  private 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<const M extends Record<AudienceKind, ReadonlyArray<string>>>(options: {
+    readonly envVar: string;
+    readonly accepts: M;
+    readonly source?: Readonly<Record<string, string | undefined>> | ConfigProvider.ConfigProvider | undefined;
+  }): Effect.Effect<{
+    readonly audience: AudienceKind;
+    readonly accepted: Option.Option<M[AudienceKind][number]>;
+    readonly rejected: Option.Option<{
+      readonly value: string;
+      readonly audience: AudienceKind;
+      readonly accepts: ReadonlyArray<string>;
+    }>;
+  }, never, Audience>;
+  /**
+   * 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<const M extends Record<AudienceKind, ReadonlyArray<string>>>(options: {
+    readonly envVar: string;
+    readonly accepts: M;
+  }): Effect.Effect<Option.Option<M[AudienceKind][number]>, never, Audience>;
+}
+//#endregion
+//#region src/TerminalEnv.d.ts
+/**
+ * What one output stream can do.
+ *
+ * @public
+ */
+interface StreamEnv {
+  /** Whether the stream is attached to a terminal. */
+  readonly isTerminal: boolean;
+  /** The colour level: `none` unless the stream is a terminal or `FORCE_COLOR` says otherwise. */
+  readonly color: ColorLevel;
+  /**
+   * Whether the terminal can render OSC 8 hyperlinks on this stream.
+   *
+   * @remarks
+   * Decided in this order: a truthy `FORCE_HYPERLINK` turns links on, even on a stream that is not a terminal; a
+   * truthy `NO_HYPERLINK` or a non-empty `NO_COLOR` turns them off; then the stream must be a terminal, not inside a
+   * multiplexer that strips them (tmux, GNU screen), and a known terminal at a version that renders them.
+   *
+   * This is terminal capability only and does not consider the audience. Turning links off for an agent audience
+   * is applied by `@effected/cli`, where the audience is known.
+   */
+  readonly hyperlinks: boolean;
+  /**
+   * The terminal width in columns, or `None` when it is unknown.
+   *
+   * @remarks
+   * Core's `Terminal` exposes one width, so `stderr.columns` reports stdout's width.
+   */
+  readonly columns: Option.Option<number>;
+}
+/**
+ * The options {@link TerminalEnv.layer} takes.
+ *
+ * @public
+ */
+interface TerminalEnvOptions {
+  /** Overrides the stderr TTY check; `Stdio` reports only stdout, so stderr mirrors stdout when this is omitted. */
+  readonly stderrIsTerminal?: Effect.Effect<boolean>;
+}
+/**
+ * The options {@link TerminalEnv.layerTest} takes: fields to set over the quiet terminal.
+ *
+ * @public
+ */
+interface TerminalEnvTestOptions {
+  /** Whether standard input is a terminal. */
+  readonly stdinIsTerminal?: boolean;
+  /** Fields merged over the quiet stdout. */
+  readonly stdout?: Partial<StreamEnv>;
+  /** Fields merged over the quiet stderr. */
+  readonly stderr?: Partial<StreamEnv>;
+}
+/**
+ * The shape of the {@link TerminalEnv} service: a snapshot taken when the layer is built, not a live view.
+ *
+ * @public
+ */
+interface TerminalEnvShape {
+  /** Whether standard input is attached to a terminal. */
+  readonly stdinIsTerminal: boolean;
+  /** The capabilities of standard output. */
+  readonly stdout: StreamEnv;
+  /** The capabilities of standard error; its `columns` is stdout's width, since core's `Terminal` has one. */
+  readonly stderr: StreamEnv;
+  /**
+   * The width to lay output out at: the stdout columns, else the `COLUMNS` variable, else `fallback`.
+   *
+   * @param fallback - the width when nothing else is known; defaults to 80
+   */
+  readonly width: (fallback?: number) => number;
+}
+declare const TerminalEnv_base: Context.ServiceClass<TerminalEnv, "@effected/env/TerminalEnv", TerminalEnvShape>;
+/**
+ * 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
+ */
+export declare class TerminalEnv extends TerminalEnv_base {
+  /**
+   * 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?: TerminalEnvOptions): Layer.Layer<TerminalEnv, never, Stdio.Stdio | Terminal.Terminal>;
+  /**
+   * 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?: TerminalEnvOptions): Layer.Layer<TerminalEnv, never, Stdio.Stdio>;
+  /**
+   * 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 readonly layerTest: (partial?: TerminalEnvTestOptions) => Layer.Layer<TerminalEnv>;
+  /**
+   * 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: "stdout"): Effect.Effect<ColorLevel, never, Stdio.Stdio>;
+}
+//#endregion
+export type { AudienceKind, AudienceOptions, AudienceShape, CiName, ColorLevel, RuntimeEnvOverrides, StreamEnv, TerminalEnvOptions, TerminalEnvShape, TerminalEnvTestOptions };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,6 @@
+import { CurrentRuntimeEnv, RuntimeEnv } from "./RuntimeEnv.js";
+import { Audience } from "./Audience.js";
+import { EnvOverride } from "./EnvOverride.js";
+import { TerminalEnv } from "./TerminalEnv.js";
+
+export { Audience, CurrentRuntimeEnv, EnvOverride, RuntimeEnv, TerminalEnv };

package/internal/agentCi.js

@@ -0,0 +1,69 @@
+import { Option } from "effect";
+
+//#region src/internal/agentCi.ts
+const matches = (value, pattern) => !!value && pattern.test(value);
+const AGENT_RULES = [
+	["claude", ["CLAUDECODE", "CLAUDE_CODE"]],
+	["replit", ["REPL_ID"]],
+	["gemini", ["GEMINI_CLI"]],
+	["codex", ["CODEX_SANDBOX", "CODEX_THREAD_ID"]],
+	["opencode", ["OPENCODE"]],
+	["pi", (env) => matches(env.PATH, /\.pi[\\/]agent/)],
+	["auggie", ["AUGMENT_AGENT"]],
+	["goose", ["GOOSE_PROVIDER"]],
+	["junie", ["JUNIE_DATA", "JUNIE_SHIM_PATH"]],
+	["copilot", ["COPILOT_AGENT", "COPILOT_CLI"]],
+	["devin", (env) => matches(env.EDITOR, /devin/)],
+	["cursor", ["CURSOR_AGENT"]]
+];
+const AGENT_FAMILIES = [...AGENT_RULES.map(([name]) => name), "kiro"];
+/** The family a lower-cased `AI_AGENT` value belongs to: equal to it, or starting with it then `-` or `_`. */
+const familyOf = (value) => AGENT_FAMILIES.find((family) => value === family || value.startsWith(`${family}-`) || value.startsWith(`${family}_`)) ?? value;
+/**
+* The name of the AI agent running this process, if any, as its family: `claude`, not the
+* `claude-code_2-1-285_agent` Claude Code puts in `AI_AGENT`.
+*
+* @remarks
+* `AI_AGENT` wins over every table row. It is lower-cased, the two `github_copilot_*` names collapse to
+* `copilot`, and a value that is a known family or starts with one followed by `-` or `_` becomes that family.
+* Any other value is returned as it was lower-cased.
+*
+* @internal
+*/
+const detectAgent = (env) => {
+	if (env.AI_AGENT) {
+		const name = env.AI_AGENT.toLowerCase();
+		return Option.some(name === "github_copilot_vscode_agent" || name === "github_copilot_cloud_agent" ? "copilot" : familyOf(name));
+	}
+	for (const [name, rule] of AGENT_RULES) if (typeof rule === "function" ? rule(env) : rule.some((key) => !!env[key])) return Option.some(name);
+	return Option.none();
+};
+const isFalsy = (value) => value === void 0 || value === "" || value.toLowerCase() === "false" || value === "0";
+/**
+* The CI this process runs in: `github-actions` when `GITHUB_ACTIONS` is truthy (even under `CI=false`, since the
+* provider signal is explicit), else `generic` when `CI` or `CONTINUOUS_INTEGRATION` is truthy.
+*
+* @internal
+*/
+const detectCi = (env) => {
+	if (!isFalsy(env.GITHUB_ACTIONS)) return Option.some("github-actions");
+	if (!isFalsy(env.CI) || !isFalsy(env.CONTINUOUS_INTEGRATION)) return Option.some("generic");
+	return Option.none();
+};
+/**
+* Every environment variable name the detectors read.
+*
+* @internal
+*/
+const agentCiKeys = [
+	"AI_AGENT",
+	...AGENT_RULES.flatMap(([, rule]) => typeof rule === "function" ? [] : rule),
+	"PATH",
+	"EDITOR",
+	"GITHUB_ACTIONS",
+	"CI",
+	"CONTINUOUS_INTEGRATION"
+];
+
+//#endregion
+export { agentCiKeys, detectAgent, detectCi };

package/internal/colorDepth.js

@@ -0,0 +1,128 @@
+//#region src/internal/colorDepth.ts
+const TERM_ENVS = /* @__PURE__ */ new Map([
+	["eterm", "basic"],
+	["cons25", "basic"],
+	["console", "basic"],
+	["cygwin", "basic"],
+	["dtterm", "basic"],
+	["gnome", "basic"],
+	["hurd", "basic"],
+	["jfbterm", "basic"],
+	["konsole", "basic"],
+	["kterm", "basic"],
+	["mlterm", "basic"],
+	["mosh", "truecolor"],
+	["putty", "basic"],
+	["st", "basic"],
+	["rxvt-unicode-24bit", "truecolor"],
+	["terminator", "truecolor"],
+	["xterm-kitty", "truecolor"]
+]);
+const CI_ENVS = [
+	["APPVEYOR", "256"],
+	["BUILDKITE", "256"],
+	["CIRCLECI", "truecolor"],
+	["DRONE", "256"],
+	["GITEA_ACTIONS", "truecolor"],
+	["GITHUB_ACTIONS", "truecolor"],
+	["GITLAB_CI", "256"],
+	["TRAVIS", "256"]
+];
+const TERM_ENVS_REG_EXP = [
+	/ansi/,
+	/color/,
+	/linux/,
+	/direct/,
+	/^con[0-9]*x[0-9]/,
+	/^rxvt/,
+	/^screen/,
+	/^xterm/,
+	/^vt100/,
+	/^vt220/
+];
+const isSet = (value) => value !== void 0 && value !== "";
+/**
+* The table: Node's getColorDepth with the FORCE_COLOR branch and warning removed, and its win32 branch keyed on
+* `OS=Windows_NT`.
+*
+* @remarks
+* Node's win32 branch reads `process.platform` and the OS release: truecolor from Windows 10 build 14931, 256 colours
+* from build 10586, 16 before. Here the environment is read only through `Config`, so `OS=Windows_NT`, which Windows
+* sets system-wide and Git Bash keeps, stands in for the platform, and the branch gives truecolor. That approximates
+* Node on Windows 10 build 14931 and later; an older build gets more colour than Node would give it.
+*/
+const fromTable = (env) => {
+	if (isSet(env.NODE_DISABLE_COLORS) || isSet(env.NO_COLOR) || env.TERM === "dumb") return "none";
+	if (env.OS === "Windows_NT") return "truecolor";
+	if (env.TMUX) return "truecolor";
+	if (env.TF_BUILD !== void 0 && env.AGENT_NAME !== void 0) return "basic";
+	if (env.CI !== void 0) {
+		for (const [name, level] of CI_ENVS) if (env[name] !== void 0) return level;
+		if (env.CI_NAME === "codeship") return "256";
+		return "none";
+	}
+	if (env.TEAMCITY_VERSION !== void 0) return /^(9\.(0*[1-9]\d*)\.|\d{2,}\.)/.test(env.TEAMCITY_VERSION) ? "basic" : "none";
+	switch (env.TERM_PROGRAM) {
+		case "iTerm.app":
+			if (!env.TERM_PROGRAM_VERSION || /^[0-2]\./.test(env.TERM_PROGRAM_VERSION)) return "256";
+			return "truecolor";
+		case "HyperTerm":
+		case "MacTerm": return "truecolor";
+		case "Apple_Terminal": return "256";
+	}
+	if (env.COLORTERM === "truecolor" || env.COLORTERM === "24bit") return "truecolor";
+	if (env.TERM) {
+		if (/truecolor/.test(env.TERM)) return "truecolor";
+		if (/^xterm-256/.test(env.TERM)) return "256";
+		const term = env.TERM.toLowerCase();
+		const known = TERM_ENVS.get(term);
+		if (known !== void 0) return known;
+		if (TERM_ENVS_REG_EXP.some((re) => re.test(term))) return "basic";
+	}
+	if (env.COLORTERM) return "basic";
+	return "none";
+};
+/**
+* The colour level of one stream. `FORCE_COLOR`, when present, decides alone (it beats `NO_COLOR`, as in
+* Node); otherwise a stream that is not a TTY has none; otherwise the terminal table decides, which gives a Windows
+* terminal (`OS=Windows_NT`) truecolor unless colour is disabled.
+*
+* @internal
+*/
+const colorDepth = (env, isTTY) => {
+	if (env.FORCE_COLOR !== void 0) switch (env.FORCE_COLOR) {
+		case "":
+		case "1":
+		case "true": return "basic";
+		case "2": return "256";
+		case "3": return "truecolor";
+		default: return "none";
+	}
+	if (!isTTY) return "none";
+	return fromTable(env);
+};
+/**
+* Every environment variable name {@link colorDepth} reads, including the CI provider table.
+*
+* @internal
+*/
+const colorKeys = [
+	"FORCE_COLOR",
+	"NO_COLOR",
+	"NODE_DISABLE_COLORS",
+	"OS",
+	"TERM",
+	"TMUX",
+	"TF_BUILD",
+	"AGENT_NAME",
+	"CI",
+	"CI_NAME",
+	"TEAMCITY_VERSION",
+	"TERM_PROGRAM",
+	"TERM_PROGRAM_VERSION",
+	"COLORTERM",
+	...CI_ENVS.map(([name]) => name)
+];
+
+//#endregion
+export { colorDepth, colorKeys };

package/internal/envRecord.js

@@ -0,0 +1,24 @@
+import { Config, Effect, Option } from "effect";
+
+//#region src/internal/envRecord.ts
+/**
+* Drop an absent or empty value from a plain record, so it carries non-empty values only: the normalisation
+* {@link readEnv} applies to what it reads, for a record a caller already holds.
+*
+* @internal
+*/
+const normalizeEnv = (record) => Object.fromEntries(Object.entries(record).filter(([, value]) => value !== void 0 && value !== ""));
+/**
+* Read a fixed key set from the ambient `ConfigProvider` into a plain {@link Env} record.
+*
+* @remarks
+* A key that is absent, or whose read fails for any reason, is left out of the record, so the record carries
+* non-empty values only. An empty string is normalized to absent here, under every provider, including one built
+* with `preserveEmptyStrings: true`, so `FORCE_COLOR=""` reads as unset whichever provider is ambient.
+*
+* @internal
+*/
+const readEnv = (keys) => Effect.forEach(keys, (key) => Config.option(Config.String(key)).pipe(Effect.orElseSucceed(() => Option.none()), Effect.map((value) => [key, value]))).pipe(Effect.map((entries) => Object.fromEntries(entries.flatMap(([key, value]) => Option.isSome(value) && value.value !== "" ? [[key, value.value]] : []))));
+
+//#endregion
+export { normalizeEnv, readEnv };