color-capable 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# color-capable
+
+> Detect whether a terminal supports color
+
+## Install
+
+```sh
+npm install color-capable
+```
+
+## Usage
+
+```js
+const supportsColor = require("color-capable")
+
+if (supportsColor.stdout) {
+	console.log("Terminal stdout supports color")
+}
+
+if (supportsColor.stdout.has256) {
+	console.log("Terminal stdout supports 256 colors")
+}
+
+if (supportsColor.stderr.has16m) {
+	console.log("Terminal stderr supports 16 million colors (truecolor)")
+}
+```
+
+## API
+
+Returns an `object` with a `stdout` and `stderr` property for testing either streams. Each property is an `Object`, or `false` if color is not supported.
+
+The `stdout`/`stderr` objects specifies a level of support for color through a `.level` property and a corresponding flag:
+
+- `.level = 1` and `.hasBasic = true`: Basic color support (16 colors)
+- `.level = 2` and `.has256 = true`: 256 color support
+- `.level = 3` and `.has16m = true`: Truecolor support (16 million colors)
+
+### Custom instance
+
+The package also exposes the named export `createSupportColor` function that takes an arbitrary write stream (for example, `process.stdout`) and an optional options object to (re-)evaluate color support for an arbitrary stream.
+
+```js
+const { createSupportsColor } = require("color-capable")
+
+const stdoutSupportsColor = createSupportsColor(process.stdout)
+
+if (stdoutSupportsColor) {
+	console.log("Terminal stdout supports color")
+}
+
+// `stdoutSupportsColor` is the same as `supportsColor.stdout`
+```
+
+The options object supports a single boolean property `sniffFlags`. By default it is `true`, which instructs the detection to sniff `process.argv` for the multitude of `--color` flags (see _Info_ below). If `false`, then `process.argv` is not considered when determining color support.
+
+## Info
+
+It obeys the `--color` and `--no-color` CLI flags.
+
+For situations where using `--color` is not possible, use the environment variable `FORCE_COLOR=1` (level 1), `FORCE_COLOR=2` (level 2), or `FORCE_COLOR=3` (level 3) to forcefully enable color, or `FORCE_COLOR=0` to forcefully disable. The use of `FORCE_COLOR` overrides all other color support checks.
+
+Explicit 256/Truecolor mode can be enabled using the `--color=256` and `--color=16m` flags, respectively.
+
+## Tests
+This has tests. You can do a git clone and run npm test to try them out.

package/index.js

@@ -0,0 +1,255 @@
+const process = require("process")
+const os = require("os")
+const tty = require("tty")
+const getIntrinsic = require("es-intrinsic-cache")
+const $String = getIntrinsic("String")
+const $Number = getIntrinsic("Number")
+const hasFlag = require("has-argv-flag")
+const forEach = require("for-each")
+const { min, isUndefined, not, and, or, add, multiply } = require("aura3")
+const zero = require("@positive-numbers/zero")
+const one = require("@positive-numbers/one")
+const two = require("@positive-numbers/two")
+const three = require("@positive-numbers/three")
+const six = require("@positive-numbers/six")
+const ten = require("@positive-numbers/ten")
+const thirtyOne = require("@positive-numbers/thirty-one")
+const seventy = require("@positive-numbers/seventy")
+const eightySix = require("@positive-numbers/eighty-six")
+const ninetyNine = require("@positive-numbers/ninety-nine")
+const oneHundred = require("@positive-numbers/one-hundred")
+const fourThousandNineHundred = multiply(seventy, seventy)
+const tenThousand = multiply(oneHundred, oneHundred)
+const tenThousandFiveHundredEightySix = add(multiply(oneHundred, add(ninetyNine, six)), eightySix)
+const fourteenThousandNineHundredThirtyOne = add(tenThousand, add(fourThousandNineHundred, thirtyOne))
+const True = require("true-value")
+const False = require("false-value")
+const stringifiedTrue = $String(True())
+const stringifiedFalse = $String(False())
+const isEqual = require("@10xly/strict-equals")
+const parseInt = require("number.parseint")
+const includes = require("array-includes")
+const isZero = require("is-eq-zero")
+const construct = require("construct-new")
+const { TernaryCompare } = require("important-extremely-useful-classes")
+const emptyString = require("empty-string")
+
+const env = process.env
+
+const listOfFlagsThatDenyColor = [
+  "no-color",
+  "no-colors",
+  "color=false",
+  "color=never"
+]
+const listOfFlagsThatHappilyAllowColor = [
+  "color",
+  "colors",
+  "color=true",
+  "color=always"
+]
+
+let flagForceColor
+
+forEach(listOfFlagsThatDenyColor, function (flagThatDeniesColor) {
+  if (hasFlag(flagThatDeniesColor)) {
+    flagForceColor = zero
+  }
+})
+forEach(listOfFlagsThatHappilyAllowColor, function (flagThatHappilyAllowsColor) {
+  if (hasFlag(flagThatHappilyAllowsColor)) {
+    flagForceColor = one
+  }
+})
+
+const NAME_OF_THE_ENV_FORCE_COLOR_FLAG = "FORCE_COLOR"
+
+function envForceColor() {
+  if (not(NAME_OF_THE_ENV_FORCE_COLOR_FLAG in env)) {
+    return
+  }
+
+  if (isEqual(env[NAME_OF_THE_ENV_FORCE_COLOR_FLAG], stringifiedTrue)) {
+    return one
+  }
+
+  if (isEqual(env[NAME_OF_THE_ENV_FORCE_COLOR_FLAG], stringifiedFalse)) {
+    return zero
+  }
+
+  if (isEqual(env[NAME_OF_THE_ENV_FORCE_COLOR_FLAG].length, zero)) {
+    return zero
+  }
+
+  const level = min(parseInt(env.FORCE_COLOR, ten), three)
+
+  if (not(includes([zero, one, two, three], level))) {
+    return
+  }
+
+  return level
+}
+
+function translateLevel(level) {
+  if (isZero(level)) {
+    return False()
+  }
+
+  return {
+    level,
+    hasBasic: True(),
+    has256: level >= two,
+    has16m: level >= three,
+  }
+}
+
+function _supportsColor(haveStream, { streamIsTTY, sniffFlags = True() } = {}) {
+  const noFlagForceColor = envForceColor()
+  if (not(isUndefined(noFlagForceColor))) {
+    flagForceColor = noFlagForceColor
+  }
+
+  let forceColor = construct({
+    target: TernaryCompare,
+    args: [sniffFlags, () => flagForceColor, () => noFlagForceColor]
+  })
+  forceColor = forceColor.compare()
+  forceColor = forceColor()
+
+  if (isZero(forceColor)) {
+    return forceColor
+  }
+
+  if (sniffFlags) {
+    if (or(
+      hasFlag("color=16m"),
+      or(
+        hasFlag("color=full"),
+        hasFlag("color=truecolor")
+      )
+    )) {
+      return three
+    }
+
+    if (hasFlag("color=256")) {
+      return two
+    }
+  }
+
+  // Check for Azure DevOps pipelines.
+  // Has to be above the `!streamIsTTY` check.
+  if (and("TF_BUILD" in env, "AGENT_NAME" in env)) {
+    return one
+  }
+
+  if (and(haveStream, and(not(streamIsTTY), isUndefined(forceColor)))) {
+    return zero
+  }
+
+  const min = or(forceColor, zero)
+
+  if (isEqual(env.TERM, "dumb")) {
+    return min
+  }
+
+  if (isEqual(process.platform, "win32")) {
+    // Windows 10 build 10586 is the first Windows release that supports 256 colors.
+    // Windows 10 build 14931 is the first release that supports 16m/TrueColor.
+    const osRelease = os.release().split(".")
+    if (
+      and(
+      $Number(osRelease[zero]) >= ten
+      , $Number(osRelease[two]) >= tenThousandFiveHundredEightySix)
+    ) {
+      if ($Number(osRelease[two]) >= fourteenThousandNineHundredThirtyOne) {
+        return three
+      } else {
+        return two
+      }
+    }
+
+    return one
+  }
+
+  if ("CI" in env) {
+    if (["GITHUB_ACTIONS", "GITEA_ACTIONS", "CIRCLECI"].some(key => key in env)) {
+      return three
+    }
+
+    if (["TRAVIS", "APPVEYOR", "GITLAB_CI", "BUILDKITE", "DRONE"].some(sign => sign in env) || env.CI_NAME === "codeship") {
+      return one
+    }
+
+    return min
+  }
+
+  if ("TEAMCITY_VERSION" in env) {
+    if (/^(9\.(0*[1-9]\d*)\.|\d{2,}\.)/.test(env.TEAMCITY_VERSION)) {
+      return one
+    } else {
+      return zero
+    }
+  }
+
+  if (isEqual(env.COLORTERM, "truecolor")) {
+    return three
+  }
+
+  if (isEqual(env.TERM, "xterm-kitty")) {
+    return two
+  }
+
+  if (isEqual(env.TERM, "xterm-ghostty")) {
+    return three
+  }
+
+  if (isEqual(env.TERM, "wezterm")) {
+    return three
+  }
+
+  if ("TERM_PROGRAM" in env) {
+    const version = parseInt((or(env.TERM_PROGRAM_VERSION, emptyString)).split(".")[zero], ten)
+
+    if (isEqual(env.TERM_PROGRAM, "iTerm.app")) {
+      if (version >= three) {
+        return three
+      } else {
+        return two
+      }
+    }
+    if (isEqual(env.TERM_PROGRAM, "Apple_Terminal")) {
+      return two
+    }
+  }
+
+  if (/-256(color)?$/i.test(env.TERM)) {
+    return two
+  }
+
+  if (/^screen|^xterm|^vt100|^vt220|^rxvt|color|ansi|cygwin|linux/i.test(env.TERM)) {
+    return one
+  }
+
+  if ("COLORTERM" in env) {
+    return one
+  }
+
+  return min
+}
+
+function createSupportsColor(stream, options = {}) {
+  const level = _supportsColor(stream, {
+    streamIsTTY: and(stream, stream.isTTY),
+    ...options,
+  })
+
+  return translateLevel(level)
+}
+
+const supportsColor = {
+  stdout: createSupportsColor({ isTTY: tty.isatty(one) }),
+  stderr: createSupportsColor({ isTTY: tty.isatty(two) }),
+  createSupportsColor: createSupportsColor
+}
+
+module.exports = supportsColor

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "color-capable",
+  "version": "1.0.0",
+  "description": "Check if the terminal has support for color.",
+  "keywords": [
+    "supports",
+    "color",
+    "terminal",
+    "colors",
+    "support",
+    "has",
+    "has-color",
+    "supports-color",
+    "chalk4096",
+    "chalk"
+  ],
+  "homepage": "https://github.com/Chalk4096/color-capable#readme",
+  "bugs": {
+    "url": "https://github.com/Chalk4096/color-capable/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Chalk4096/color-capable.git"
+  },
+  "license": "MIT",
+  "author": "10x'ly Made",
+  "type": "commonjs",
+  "main": "index.js",
+  "scripts": {
+    "test": "mocha test.js --timeout 10000000"
+  },
+  "dependencies": {
+    "@10xly/strict-equals": "^1.0.0",
+    "@positive-numbers/eighty-six": "^3.0.0",
+    "@positive-numbers/ninety-nine": "^3.0.0",
+    "@positive-numbers/one": "^3.0.0",
+    "@positive-numbers/one-hundred": "^3.0.0",
+    "@positive-numbers/seventy": "^3.0.0",
+    "@positive-numbers/six": "^3.0.0",
+    "@positive-numbers/ten": "^3.0.0",
+    "@positive-numbers/thirty-one": "^3.0.0",
+    "@positive-numbers/three": "^3.0.0",
+    "@positive-numbers/two": "^3.0.0",
+    "@positive-numbers/zero": "^3.0.0",
+    "array-includes": "^3.1.9",
+    "aura3": "^1.0.3-enterprise.stable",
+    "construct-new": "^2.0.4",
+    "empty-string": "^1.1.1",
+    "es-intrinsic-cache": "^1.0.1",
+    "false-value": "^2.0.6",
+    "for-each": "^0.3.5",
+    "has-argv-flag": "^1.1.2",
+    "important-extremely-useful-classes": "^3.1.0",
+    "is-eq-zero": "^1.1.0",
+    "number.parseint": "^1.1.0",
+    "true-value": "^2.0.5"
+  },
+  "devDependencies": {
+    "chai": "^6.2.2",
+    "mocha": "^11.7.5",
+    "proxyquire": "^2.1.3"
+  }
+}

package/test.js

@@ -0,0 +1,429 @@
+/* eslint-env mocha */
+"use strict";
+
+const { expect } = require("chai");
+const proxyquire = require("proxyquire").noCallThru();
+
+function loadSupportsColor({
+  env = {},
+  platform = "linux",
+  osRelease = "5.0.0",
+  stdoutIsTTY = true,
+  stderrIsTTY = true,
+  argvFlags = [],
+} = {}) {
+  const processStub = {
+    env: { ...env },
+    platform,
+  };
+
+  const osStub = {
+    release: () => osRelease,
+  };
+
+  const ttyStub = {
+    isatty: (fd) => {
+      if (fd === 1) return stdoutIsTTY;
+      if (fd === 2) return stderrIsTTY;
+      return false;
+    },
+  };
+
+  const hasArgvFlagStub = (flag) => argvFlags.includes(flag);
+
+  const supportsColor = proxyquire("./index", {
+    process: processStub,
+    os: osStub,
+    tty: ttyStub,
+    "has-argv-flag": hasArgvFlagStub,
+  });
+
+  return { supportsColor, processStub, osStub, ttyStub };
+}
+
+describe("supportsColor", function () {
+  describe("createSupportsColor basic behavior", function () {
+    it("returns false when level is 0 (e.g. FORCE_COLOR=false)", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { FORCE_COLOR: "false" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result).to.equal(false);
+    });
+
+    it("returns level 1 when FORCE_COLOR=true", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { FORCE_COLOR: "true" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result).to.deep.include({
+        level: 1,
+        hasBasic: true,
+        has256: false,
+        has16m: false,
+      });
+    });
+
+    it("returns level 2 when FORCE_COLOR=2", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { FORCE_COLOR: "2" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result).to.deep.include({
+        level: 2,
+        hasBasic: true,
+        has256: true,
+        has16m: false,
+      });
+    });
+
+    it("ignores invalid numeric FORCE_COLOR and falls back to TERM heuristics", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { FORCE_COLOR: "10", TERM: "xterm-256color" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      // no valid FORCE_COLOR => TERM-256color gives level 2
+      expect(result.level).to.equal(2);
+    });
+  });
+
+  describe("CLI flags (has-argv-flag)", function () {
+    it("forces flagForceColor = 0 with no-color", function () {
+      const { supportsColor } = loadSupportsColor({
+        argvFlags: ["no-color"],
+        env: { TERM: "xterm-256color" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      // translateLevel(0) => false
+      expect(result).to.equal(false);
+    });
+
+    it("forces flagForceColor = 1 with color", function () {
+      const { supportsColor } = loadSupportsColor({
+        argvFlags: ["color"],
+        env: {},
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(1);
+      expect(result.hasBasic).to.equal(true);
+    });
+
+    it("returns level 3 with color=16m flag", function () {
+      const { supportsColor } = loadSupportsColor({
+        argvFlags: ["color=16m"],
+        env: {},
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(3);
+      expect(result.has16m).to.equal(true);
+    });
+
+    it("returns level 2 with color=256 flag", function () {
+      const { supportsColor } = loadSupportsColor({
+        argvFlags: ["color=256"],
+        env: {},
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(2);
+      expect(result.has256).to.equal(true);
+    });
+
+    it("does not look at flags when sniffFlags = false", function () {
+      const { supportsColor } = loadSupportsColor({
+        argvFlags: ["color=16m"],
+        env: { TERM: "xterm-256color" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor(
+        { isTTY: true },
+        { sniffFlags: false }
+      );
+
+      // TERM=*-256color gives 2; color=16m is ignored
+      expect(result.level).to.equal(2);
+    });
+  });
+
+  describe("TTY behavior", function () {
+    it("returns false when stream is not TTY and no forceColor", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: {},
+        stdoutIsTTY: false,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: false });
+      expect(result).to.equal(false);
+    });
+
+    it("allows color when non-TTY but FORCE_COLOR=true", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { FORCE_COLOR: "true" },
+        stdoutIsTTY: false,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: false });
+      expect(result.level).to.equal(1);
+      expect(result.hasBasic).to.equal(true);
+    });
+  });
+
+  describe("Azure DevOps behavior", function () {
+    it("returns level 1 when TF_BUILD and AGENT_NAME exist", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { TF_BUILD: "1", AGENT_NAME: "agent" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(1);
+    });
+  });
+
+  describe("Windows behavior", function () {
+    it("returns level 1 for non-Windows 10 releases", function () {
+      const { supportsColor } = loadSupportsColor({
+        platform: "win32",
+        osRelease: "6.3.9600",
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(1);
+    });
+
+    it("returns level 2 for Windows 10 build 10586+", function () {
+      const { supportsColor } = loadSupportsColor({
+        platform: "win32",
+        osRelease: "10.0.10586",
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(2);
+      expect(result.has256).to.equal(true);
+    });
+
+    it("returns level 3 for Windows 10 build 14931+", function () {
+      const { supportsColor } = loadSupportsColor({
+        platform: "win32",
+        osRelease: "10.0.14931",
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(3);
+      expect(result.has16m).to.equal(true);
+    });
+  });
+
+  describe("CI behavior", function () {
+    it("returns level 3 on GitHub Actions", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { CI: "1", GITHUB_ACTIONS: "true" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(3);
+    });
+
+    it("returns level 1 on Travis", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { CI: "1", TRAVIS: "true" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(1);
+    });
+
+    it("returns min level when CI vendor is unknown", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { CI: "1" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      // min level when nothing else helps is 0 => false
+      expect(result === false || result.level === 0).to.equal(true);
+    });
+  });
+
+  describe("TEAMCITY behavior", function () {
+    it("returns level 1 for TEAMCITY_VERSION >= 9.1", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { TEAMCITY_VERSION: "9.1.0" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(1);
+    });
+
+    it("returns false for TEAMCITY_VERSION < 9.1", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { TEAMCITY_VERSION: "8.1.0" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result).to.equal(false);
+    });
+  });
+
+  describe("TERM / COLORTERM / TERM_PROGRAM heuristics", function () {
+    it("returns level 3 when COLORTERM=truecolor", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { COLORTERM: "truecolor" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(3);
+    });
+
+    it("returns level 2 when TERM=xterm-kitty", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { TERM: "xterm-kitty" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(2);
+    });
+
+    it("returns level 3 when TERM=xterm-ghostty", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { TERM: "xterm-ghostty" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(3);
+    });
+
+    it("returns level 3 when TERM=wezterm", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { TERM: "wezterm" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(3);
+    });
+
+    it("returns level 2 when TERM ends with -256color", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { TERM: "xterm-256color" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(2);
+    });
+
+    it("returns level 1 for generic color-capable TERM", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { TERM: "xterm" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(1);
+    });
+
+    it("returns level 1 if COLORTERM is set even if TERM is weird", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { COLORTERM: "yes", TERM: "weirdterm" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(1);
+    });
+
+    it("returns min (0) for TERM=dumb", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { TERM: "dumb" },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result === false || result.level === 0).to.equal(true);
+    });
+
+    it("returns level 3 for iTerm.app >= 3", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: {
+          TERM_PROGRAM: "iTerm.app",
+          TERM_PROGRAM_VERSION: "3.1.0",
+        },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(3);
+    });
+
+    it("returns level 2 for iTerm.app < 3", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: {
+          TERM_PROGRAM: "iTerm.app",
+          TERM_PROGRAM_VERSION: "2.9.0",
+        },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(2);
+    });
+
+    it("returns level 2 for Apple_Terminal", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: {
+          TERM_PROGRAM: "Apple_Terminal",
+          TERM_PROGRAM_VERSION: "999.0",
+        },
+        stdoutIsTTY: true,
+      });
+
+      const result = supportsColor.createSupportsColor({ isTTY: true });
+      expect(result.level).to.equal(2);
+    });
+  });
+
+  describe("top-level stdout and stderr", function () {
+    it("uses tty.isatty(1/2) for default stdout/stderr", function () {
+      const { supportsColor } = loadSupportsColor({
+        env: { TERM: "xterm-256color" },
+        stdoutIsTTY: true,
+        stderrIsTTY: false,
+      });
+
+      const { stdout, stderr } = supportsColor;
+
+      // stdout is TTY and TERM-256color => level >= 2
+      expect(stdout === false || stdout.level >= 2).to.equal(true);
+
+      // stderr is not TTY => likely false or 0
+      expect(stderr === false || stderr.level === 0).to.equal(true);
+    });
+  });
+});