@effected/env 0.1.0

package/internal/keys.js

@@ -0,0 +1,19 @@
+import { agentCiKeys } from "./agentCi.js";
+import { colorKeys } from "./colorDepth.js";
+import { terminalKeys } from "./osc8/detect.js";
+
+//#region src/internal/keys.ts
+/**
+* Every environment variable any detector reads: the union of the agent/CI, colour and terminal key lists, without
+* duplicates.
+*
+* @internal
+*/
+const allKeys = [.../* @__PURE__ */ new Set([
+	...agentCiKeys,
+	...colorKeys,
+	...terminalKeys
+])];
+
+//#endregion
+export { allKeys };

package/internal/osc8/detect.js

@@ -0,0 +1,148 @@
+import { envIsTruthy } from "./env.js";
+import { compareSemver } from "./semver.js";
+import { NO_CAPS, lookupTerminal } from "./terminals.js";
+import { detectWrapper } from "./wrappers.js";
+import { Option } from "effect";
+
+//#region src/internal/osc8/detect.ts
+const explanationFor = (reason, terminal, terminalVersion, wrapper) => {
+	switch (reason) {
+		case "force-env": return "FORCE_HYPERLINK env var is set";
+		case "no-hyperlink-env": return "NO_HYPERLINK env var is set";
+		case "no-color-env": return "NO_COLOR env var is set";
+		case "not-a-tty": return "stdout is not a TTY";
+		case "wrapper-strips": return `inside ${wrapper?.name ?? "wrapper"}; passthrough not verifiable without subprocess`;
+		case "terminal-known-supported": return `detected ${terminal}${terminalVersion ? ` ${terminalVersion}` : ""}`;
+		case "terminal-known-unsupported": return `detected ${terminal}; terminal does not support OSC8`;
+		case "terminal-known-too-old": return `detected ${terminal} ${terminalVersion ?? ""}; below minimum version`;
+		case "terminal-unknown": return "no identifying signal matched";
+	}
+};
+/**
+* Run the 7-rule precedence ladder for a single stream's TTY state.
+* Shared by stdout and stderr so the two paths cannot drift.
+*/
+const evaluateGate = (isTTY, force, noHyperlink, noColor, wrapper, match) => {
+	if (force) return {
+		supported: true,
+		reason: "force-env",
+		override: "force-hyperlink"
+	};
+	if (noHyperlink) return {
+		supported: false,
+		reason: "no-hyperlink-env",
+		override: "no-hyperlink"
+	};
+	if (noColor) return {
+		supported: false,
+		reason: "no-color-env",
+		override: "no-color"
+	};
+	if (!isTTY) return {
+		supported: false,
+		reason: "not-a-tty",
+		override: null
+	};
+	if (wrapper) return {
+		supported: false,
+		reason: "wrapper-strips",
+		override: null
+	};
+	if (!match) return {
+		supported: false,
+		reason: "terminal-unknown",
+		override: null
+	};
+	if (!match.entry.supported) return {
+		supported: false,
+		reason: "terminal-known-unsupported",
+		override: null
+	};
+	if (match.entry.minVersion && (match.identify.version === null || compareSemver(match.identify.version, match.entry.minVersion) < 0)) return {
+		supported: false,
+		reason: "terminal-known-too-old",
+		override: null
+	};
+	return {
+		supported: true,
+		reason: "terminal-known-supported",
+		override: null
+	};
+};
+/**
+* Determine OSC8 support from a process snapshot. Pure: same input ⇒ same
+* output.
+*/
+const detect = (snap) => {
+	const { env, isStdoutTTY, isStderrTTY } = snap;
+	const wrapper = detectWrapper(env);
+	const force = envIsTruthy(env.FORCE_HYPERLINK);
+	const noHyperlink = envIsTruthy(env.NO_HYPERLINK);
+	const noColor = envIsTruthy(env.NO_COLOR, "no-color");
+	const match = lookupTerminal(env);
+	const terminal = match?.entry.name ?? null;
+	const terminalRaw = match?.identify.rawIdentifier ?? null;
+	const terminalVersion = match?.identify.version ?? null;
+	const stdout = evaluateGate(isStdoutTTY, force, noHyperlink, noColor, wrapper, match);
+	const stderr = evaluateGate(isStderrTTY, force, noHyperlink, noColor, wrapper, match);
+	const capabilities = match?.entry.capabilities ?? NO_CAPS;
+	return {
+		supported: stdout.supported,
+		supportedForStderr: stderr.supported,
+		reason: stdout.reason,
+		explanation: explanationFor(stdout.reason, terminal, terminalVersion, wrapper),
+		terminal,
+		terminalRaw,
+		terminalVersion,
+		wrapper,
+		isStdoutTTY,
+		isStderrTTY,
+		override: stdout.override,
+		capabilities
+	};
+};
+/**
+* Project {@link detect} onto {@link Osc8Detection}: `supported` becomes
+* `stdout`, `supportedForStderr` becomes `stderr`, and the terminal name and
+* version become an `Option`.
+*/
+const detectOsc8 = (env, isStdoutTTY, isStderrTTY) => {
+	const info = detect({
+		env,
+		isStdoutTTY,
+		isStderrTTY
+	});
+	return {
+		stdout: info.supported,
+		stderr: info.supportedForStderr,
+		terminal: Option.map(Option.fromNullishOr(info.terminal), (name) => ({
+			name,
+			version: Option.fromNullishOr(info.terminalVersion)
+		}))
+	};
+};
+/**
+* Every environment variable name the ported detectors read. A caller that
+* builds an {@link Env} from `Config` reads exactly these keys.
+*/
+const terminalKeys = [
+	"FORCE_HYPERLINK",
+	"NO_HYPERLINK",
+	"NO_COLOR",
+	"TMUX",
+	"STY",
+	"TERM",
+	"TERM_PROGRAM",
+	"TERM_PROGRAM_VERSION",
+	"VTE_VERSION",
+	"KONSOLE_VERSION",
+	"WT_SESSION",
+	"KITTY_WINDOW_ID",
+	"TERMINAL_EMULATOR",
+	"TERMINAL_NAME",
+	"ConEmuPID",
+	"TERMINOLOGY"
+];
+
+//#endregion
+export { detect, detectOsc8, terminalKeys };

package/internal/osc8/env.js

@@ -0,0 +1,21 @@
+//#region src/internal/osc8/env.ts
+const DEFAULT_FALSY = /* @__PURE__ */ new Set([
+	"0",
+	"false",
+	"off",
+	"no"
+]);
+/**
+* Evaluate whether an env-var value should be considered truthy.
+*
+* @param value - The env-var value (commonly `process.env.SOMETHING`).
+* @param spec - Which semantics to apply. Default: "default".
+*/
+const envIsTruthy = (value, spec = "default") => {
+	if (value === void 0 || value === "") return false;
+	if (spec === "no-color") return true;
+	return !DEFAULT_FALSY.has(value.toLowerCase());
+};
+
+//#endregion
+export { envIsTruthy };

package/internal/osc8/semver.js

@@ -0,0 +1,46 @@
+//#region src/internal/osc8/semver.ts
+const SEMVER_RE = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?/;
+/**
+* Compare two semver-like strings (`MAJOR[.MINOR[.PATCH]]`). Prerelease tags
+* (e.g. `-beta`, `-rc.1`) are stripped and ignored. Malformed inputs are
+* treated as equal — this is a permissive helper, not a strict parser.
+*
+* @returns negative if `a` is less than `b`, positive if `a` is greater than `b`, 0 if equal or malformed.
+*/
+const compareSemver = (a, b) => {
+	const parsed = (s) => {
+		const m = SEMVER_RE.exec(s);
+		if (!m) return null;
+		return [
+			Number(m[1] ?? 0),
+			Number(m[2] ?? 0),
+			Number(m[3] ?? 0)
+		];
+	};
+	const aa = parsed(a);
+	const bb = parsed(b);
+	if (!aa || !bb) return 0;
+	for (let i = 0; i < 3; i++) {
+		const diff = (aa[i] ?? 0) - (bb[i] ?? 0);
+		if (diff !== 0) return diff;
+	}
+	return 0;
+};
+/**
+* Parse a VTE_VERSION env value. VTE encodes versions as
+* `MAJOR * 10000 + MINOR * 100 + PATCH`. So `5202` means `0.52.2`.
+*/
+const parseVteVersion = (raw) => {
+	if (!raw) return null;
+	const n = Number.parseInt(raw, 10);
+	if (!Number.isFinite(n) || n < 0) return null;
+	return `${Math.floor(n / 1e4)}.${Math.floor(n % 1e4 / 100)}.${n % 100}`;
+};
+/**
+* Parse a KONSOLE_VERSION env value. Konsole uses calendar versioning
+* packed identically to VTE: `YY * 10000 + MM * 100 + PATCH`.
+*/
+const parseKonsoleVersion = parseVteVersion;
+
+//#endregion
+export { compareSemver, parseKonsoleVersion, parseVteVersion };

package/internal/osc8/terminals.js

@@ -0,0 +1,319 @@
+import { parseKonsoleVersion, parseVteVersion } from "./semver.js";
+
+//#region src/internal/osc8/terminals.ts
+const NO_CAPS = {
+	params: false,
+	fileUrls: false,
+	fileUrlsRemoteUnsafe: false
+};
+const TERMINALS = [
+	{
+		name: "iTerm.app",
+		identify: (env) => env.TERM_PROGRAM === "iTerm.app" ? {
+			version: env.TERM_PROGRAM_VERSION ?? null,
+			rawIdentifier: env.TERM_PROGRAM
+		} : null,
+		supported: true,
+		minVersion: "3.1.0",
+		capabilities: {
+			params: true,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "Apple_Terminal",
+		identify: (env) => env.TERM_PROGRAM === "Apple_Terminal" ? {
+			version: env.TERM_PROGRAM_VERSION ?? null,
+			rawIdentifier: env.TERM_PROGRAM
+		} : null,
+		supported: false,
+		minVersion: null,
+		capabilities: NO_CAPS
+	},
+	{
+		name: "VTE",
+		identify: (env) => env.VTE_VERSION ? {
+			version: parseVteVersion(env.VTE_VERSION),
+			rawIdentifier: env.VTE_VERSION
+		} : null,
+		supported: true,
+		minVersion: "0.50.0",
+		capabilities: {
+			params: false,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "Konsole",
+		identify: (env) => env.KONSOLE_VERSION ? {
+			version: parseKonsoleVersion(env.KONSOLE_VERSION),
+			rawIdentifier: env.KONSOLE_VERSION
+		} : null,
+		supported: true,
+		minVersion: "22.4.0",
+		capabilities: {
+			params: true,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "WezTerm",
+		identify: (env) => env.TERM_PROGRAM === "WezTerm" ? {
+			version: env.TERM_PROGRAM_VERSION ?? null,
+			rawIdentifier: env.TERM_PROGRAM
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: true,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "kitty",
+		identify: (env) => {
+			if (env.TERM === "xterm-kitty") return {
+				version: null,
+				rawIdentifier: env.TERM
+			};
+			if (env.KITTY_WINDOW_ID) return {
+				version: null,
+				rawIdentifier: env.KITTY_WINDOW_ID
+			};
+			return null;
+		},
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: true,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "vscode",
+		identify: (env) => env.TERM_PROGRAM === "vscode" ? {
+			version: env.TERM_PROGRAM_VERSION ?? null,
+			rawIdentifier: env.TERM_PROGRAM
+		} : null,
+		supported: true,
+		minVersion: "1.71.0",
+		capabilities: {
+			params: false,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: true
+		}
+	},
+	{
+		name: "Hyper",
+		identify: (env) => env.TERM_PROGRAM === "Hyper" ? {
+			version: env.TERM_PROGRAM_VERSION ?? null,
+			rawIdentifier: env.TERM_PROGRAM
+		} : null,
+		supported: true,
+		minVersion: "3.0.0",
+		capabilities: {
+			params: false,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "mintty",
+		identify: (env) => env.TERM_PROGRAM === "mintty" ? {
+			version: env.TERM_PROGRAM_VERSION ?? null,
+			rawIdentifier: env.TERM_PROGRAM
+		} : null,
+		supported: true,
+		minVersion: "3.6.0",
+		capabilities: {
+			params: true,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "WindowsTerminal",
+		identify: (env) => env.WT_SESSION ? {
+			version: null,
+			rawIdentifier: env.WT_SESSION
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: false,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "Alacritty",
+		identify: (env) => env.TERM === "alacritty" ? {
+			version: null,
+			rawIdentifier: env.TERM
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: false,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "Ghostty",
+		identify: (env) => env.TERM_PROGRAM === "ghostty" ? {
+			version: env.TERM_PROGRAM_VERSION ?? null,
+			rawIdentifier: env.TERM_PROGRAM
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: true,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "JediTerm",
+		identify: (env) => env.TERMINAL_EMULATOR === "JetBrains-JediTerm" ? {
+			version: null,
+			rawIdentifier: env.TERMINAL_EMULATOR
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: false,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "Tabby",
+		identify: (env) => env.TERM_PROGRAM === "Tabby" ? {
+			version: env.TERM_PROGRAM_VERSION ?? null,
+			rawIdentifier: env.TERM_PROGRAM
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: true,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "Foot",
+		identify: (env) => env.TERM === "foot" || env.TERM === "foot-extra" ? {
+			version: null,
+			rawIdentifier: env.TERM
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: true,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "Rio",
+		identify: (env) => env.TERM_PROGRAM === "rio" ? {
+			version: env.TERM_PROGRAM_VERSION ?? null,
+			rawIdentifier: env.TERM_PROGRAM
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: false,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "Contour",
+		identify: (env) => env.TERMINAL_NAME === "contour" ? {
+			version: null,
+			rawIdentifier: env.TERMINAL_NAME
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: true,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "ConEmu",
+		identify: (env) => env.ConEmuPID ? {
+			version: null,
+			rawIdentifier: env.ConEmuPID
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: false,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "WarpTerminal",
+		identify: (env) => env.TERM_PROGRAM === "WarpTerminal" ? {
+			version: env.TERM_PROGRAM_VERSION ?? null,
+			rawIdentifier: env.TERM_PROGRAM
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: false,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "WaveTerminal",
+		identify: (env) => env.TERM_PROGRAM === "WaveTerminal" ? {
+			version: env.TERM_PROGRAM_VERSION ?? null,
+			rawIdentifier: env.TERM_PROGRAM
+		} : null,
+		supported: true,
+		minVersion: null,
+		capabilities: {
+			params: false,
+			fileUrls: true,
+			fileUrlsRemoteUnsafe: false
+		}
+	},
+	{
+		name: "Terminology",
+		identify: (env) => env.TERMINOLOGY === "1" ? {
+			version: null,
+			rawIdentifier: env.TERMINOLOGY
+		} : null,
+		supported: false,
+		minVersion: null,
+		capabilities: NO_CAPS
+	}
+];
+/**
+* Find the first allowlist entry whose `identify()` returns non-null.
+*/
+const lookupTerminal = (env) => {
+	for (const entry of TERMINALS) {
+		const id = entry.identify(env);
+		if (id) return {
+			entry,
+			identify: id
+		};
+	}
+	return null;
+};
+
+//#endregion
+export { NO_CAPS, lookupTerminal };

package/internal/osc8/wrappers.js

@@ -0,0 +1,23 @@
+//#region src/internal/osc8/wrappers.ts
+/**
+* Detect a multiplexer wrapper from the env. Conservative — `passesThrough`
+* is always `false` because we cannot verify version or config without
+* spawning a subprocess, which this package never does.
+*
+* Users who know their tmux ≥ 3.4 has `set -g allow-passthrough on` can
+* opt back in via FORCE_HYPERLINK=1.
+*/
+const detectWrapper = (env) => {
+	if (env.TMUX) return {
+		name: "tmux",
+		passesThrough: false
+	};
+	if (env.STY) return {
+		name: "screen",
+		passesThrough: false
+	};
+	return null;
+};
+
+//#endregion
+export { detectWrapper };

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@effected/env",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Effect-native environment detection: agent, CI, terminal colour level, hyperlinks, columns and audience — read once through Config, swapped in tests with layerTest",
+	"keywords": [
+		"effect",
+		"env",
+		"ci",
+		"agent",
+		"color",
+		"tty",
+		"osc8",
+		"hyperlinks",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/env#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/env"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"effect": "^4.0.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.59.1"
+    }
+  ]
+}