supports-color 7.2.0: stderr

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify supports-color.stderr in pkg:npm/supports-color@7.2.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/supports-color@7.2.0
Demonstrate these symbols/APIs:
  - supports-color.stderr

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:846627d5819ab8c48aea75b71bb285bde70424ad267b1470a60512b1a50e79c7","contract":["supportsColor.stderr evaluates standard error stream returning false or a level descriptor object","supportsColor.stderr descriptor contains valid level number between 1 and 3 when color is supported","supportsColor returns false for non-TTY stderr stream when color is not forced","supportsColor returns false for stderr stream when TERM is set to dumb","supportsColor detects basic color support with level 1 for stderr stream when TERM is xterm","supportsColor detects 256 color support with level 2 for stderr stream when TERM is xterm-256color","supportsColor detects truecolor support with level 3 for stderr stream when COLORTERM is truecolor"],"goal":"verify supports-color.stderr in pkg:npm/supports-color@7.2.0","kind":"HOW","packages":["pkg:npm/supports-color@7.2.0"],"schemaVersion":1,"symbols":["supports-color.stderr"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/supports-color@7.2.0"],"schemaVersion":1,"subject":"pkg:npm/supports-color@7.2.0","symbols":["supports-color.stderr"],"verifierAdapter":"node-typescript@1"}

import supportsColor from 'supports-color';

/**
 * Returns the stderr color support descriptor or false if unsupported.
 * @returns {object|boolean}
 */
export function getStderrColorSupport() {
  return supportsColor.stderr;
}

/**
 * Checks whether standard error supports color.
 * @returns {boolean}
 */
export function hasStderrColorSupport() {
  return Boolean(supportsColor.stderr);
}

/**
 * Evaluates color support for a custom stderr-like stream.
 * @param {object} stream - Stream object with isTTY property
 * @returns {object|boolean}
 */
export function checkStderrStreamSupport(stream) {
  return supportsColor.supportsColor(stream);
}

export { supportsColor };
export default supportsColor;

{
  "name": "sample-supports-color-stderr",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-supports-color-stderr",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "supports-color": "7.2.0"
      }
    },
    "node_modules/has-flag": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
      "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==",
      "license": "MIT",
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/supports-color": {
      "version": "7.2.0",
      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
      "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
      "license": "MIT",
      "dependencies": {
        "has-flag": "^4.0.0"
      },
      "engines": {
        "node": ">=8"
      }
    }
  }
}

{
  "name": "sample-supports-color-stderr",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "main": "index.mjs",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "supports-color": "7.2.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify supports-color.stderr in pkg:npm/supports-color@7.2.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/supports-color@7.2.0"
  ],
  "symbols": [
    "supports-color.stderr"
  ]
}

import assert from 'node:assert/strict';
import supportsColor, {
  getStderrColorSupport,
  hasStderrColorSupport,
  checkStderrStreamSupport
} from '../index.mjs';

function validateColorDescriptor(desc) {
  if (desc === false) {
    return;
  }
  assert.equal(typeof desc, 'object', 'Color descriptor must be an object');
  assert.ok(desc !== null, 'Color descriptor must not be null');
  assert.equal(typeof desc.level, 'number', 'level property must be a number');
  assert.ok(desc.level >= 1 && desc.level <= 3, 'level must be between 1 and 3');
  assert.equal(typeof desc.hasBasic, 'boolean', 'hasBasic must be a boolean');
  assert.equal(typeof desc.has256, 'boolean', 'has256 must be a boolean');
  assert.equal(typeof desc.has16m, 'boolean', 'has16m must be a boolean');
  assert.equal(desc.hasBasic, true, 'hasBasic must be true when level >= 1');
  assert.equal(desc.has256, desc.level >= 2, 'has256 must match level >= 2');
  assert.equal(desc.has16m, desc.level >= 3, 'has16m must match level >= 3');
}

// 1. supportsColor.stderr evaluates standard error stream returning false or a level descriptor object
validateColorDescriptor(supportsColor.stderr);
validateColorDescriptor(getStderrColorSupport());
assert.deepEqual(supportsColor.stderr, getStderrColorSupport(), 'Exported helper must match supportsColor.stderr');
assert.equal(typeof hasStderrColorSupport(), 'boolean', 'hasStderrColorSupport must return boolean');
assert.equal(hasStderrColorSupport(), supportsColor.stderr !== false, 'hasStderrColorSupport must reflect color support boolean');

// 2. supportsColor.stderr descriptor contains valid level number between 1 and 3 when color is supported
if (supportsColor.stderr !== false) {
  assert.ok(supportsColor.stderr.level >= 1 && supportsColor.stderr.level <= 3, 'Color level must be 1, 2, or 3');
  assert.equal(supportsColor.stderr.hasBasic, true, 'Basic color support must be true');
}

// Save original environment
const originalTerm = process.env.TERM;
const originalColorTerm = process.env.COLORTERM;
const originalCi = process.env.CI;
const originalTeamcity = process.env.TEAMCITY_VERSION;
const originalTermProgram = process.env.TERM_PROGRAM;
const originalForceColor = process.env.FORCE_COLOR;

try {
  delete process.env.CI;
  delete process.env.TEAMCITY_VERSION;
  delete process.env.TERM_PROGRAM;
  delete process.env.FORCE_COLOR;

  // 3. supportsColor returns false for non-TTY stderr stream when color is not forced
  process.env.TERM = 'xterm-256color';
  delete process.env.COLORTERM;
  const nonTtyResult = supportsColor.supportsColor({ isTTY: false });
  assert.equal(nonTtyResult, false, 'Non-TTY stream must yield false without forced color');
  assert.equal(checkStderrStreamSupport({ isTTY: false }), false, 'Helper with non-TTY stream must return false');

  // 4. supportsColor returns false for stderr stream when TERM is set to dumb
  process.env.TERM = 'dumb';
  delete process.env.COLORTERM;
  const dumbResult = supportsColor.supportsColor({ isTTY: true });
  assert.equal(dumbResult, false, 'dumb terminal must yield false');
  assert.equal(checkStderrStreamSupport({ isTTY: true }), false, 'Helper with dumb terminal must return false');

  // 5. supportsColor detects basic color support with level 1 for stderr stream when TERM is xterm
  process.env.TERM = 'xterm';
  delete process.env.COLORTERM;
  const basicResult = supportsColor.supportsColor({ isTTY: true });
  assert.deepEqual(basicResult, {
    level: 1,
    hasBasic: true,
    has256: false,
    has16m: false
  }, 'xterm terminal must detect level 1 basic color support');
  assert.deepEqual(checkStderrStreamSupport({ isTTY: true }), {
    level: 1,
    hasBasic: true,
    has256: false,
    has16m: false
  }, 'Helper must detect level 1 basic color support');

  // 6. supportsColor detects 256 color support with level 2 for stderr stream when TERM is xterm-256color
  process.env.TERM = 'xterm-256color';
  delete process.env.COLORTERM;
  const color256Result = supportsColor.supportsColor({ isTTY: true });
  assert.deepEqual(color256Result, {
    level: 2,
    hasBasic: true,
    has256: true,
    has16m: false
  }, 'xterm-256color terminal must detect level 2 color support');
  assert.deepEqual(checkStderrStreamSupport({ isTTY: true }), {
    level: 2,
    hasBasic: true,
    has256: true,
    has16m: false
  }, 'Helper must detect level 2 color support');

  // 7. supportsColor detects truecolor support with level 3 for stderr stream when COLORTERM is truecolor
  process.env.TERM = 'xterm';
  process.env.COLORTERM = 'truecolor';
  const trueColorResult = supportsColor.supportsColor({ isTTY: true });
  assert.deepEqual(trueColorResult, {
    level: 3,
    hasBasic: true,
    has256: true,
    has16m: true
  }, 'COLORTERM=truecolor must detect level 3 16m truecolor support');
  assert.deepEqual(checkStderrStreamSupport({ isTTY: true }), {
    level: 3,
    hasBasic: true,
    has256: true,
    has16m: true
  }, 'Helper must detect level 3 16m truecolor support');

} finally {
  if (originalTerm !== undefined) process.env.TERM = originalTerm; else delete process.env.TERM;
  if (originalColorTerm !== undefined) process.env.COLORTERM = originalColorTerm; else delete process.env.COLORTERM;
  if (originalCi !== undefined) process.env.CI = originalCi; else delete process.env.CI;
  if (originalTeamcity !== undefined) process.env.TEAMCITY_VERSION = originalTeamcity; else delete process.env.TEAMCITY_VERSION;
  if (originalTermProgram !== undefined) process.env.TERM_PROGRAM = originalTermProgram; else delete process.env.TERM_PROGRAM;
  if (originalForceColor !== undefined) process.env.FORCE_COLOR = originalForceColor; else delete process.env.FORCE_COLOR;
}

console.log('Contract test passed successfully.');