path-key 3.1.1: pathKey

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 pathKey in pkg:npm/path-key@3.1.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/path-key@3.1.1
Demonstrate these symbols/APIs:
  - pathKey

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:fcb7cb1b1d635d5ae4e80a119a448b25dda5c21116e4102d078a3c1cce8e951e","contract":["assert pathKey returns PATH on POSIX platforms like linux and darwin","assert pathKey returns PATH by default on current POSIX environment","assert pathKey returns Path on Windows when no PATH environment variable exists","assert pathKey returns the specific PATH casing present in Windows environment options","assert pathKey returns the last matching key in reverse order when multiple PATH casings exist on Windows","assert pathKey accepts custom environment and platform options"],"goal":"verify pathKey in pkg:npm/path-key@3.1.1","kind":"HOW","packages":["pkg:npm/path-key@3.1.1"],"schemaVersion":1,"symbols":["pathKey"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/path-key@3.1.1"],"schemaVersion":1,"subject":"pkg:npm/path-key@3.1.1","symbols":["pathKey"],"verifierAdapter":"node-typescript@1"}

const pathKey = require('path-key');

/**
 * Returns the environment variable key for PATH on cross-platform systems.
 *
 * @param {object} [options] - Options specifying custom env and platform.
 * @returns {string} The PATH environment variable key name.
 */
function getPathKey(options) {
  return pathKey(options);
}

/**
 * Retrieves the value of the PATH environment variable from the provided environment.
 *
 * @param {object} [env] - Environment object (defaults to process.env).
 * @param {object} [options] - Options passed to pathKey.
 * @returns {string|undefined} The PATH environment variable value.
 */
function getPathValue(env = process.env, options = {}) {
  const opts = { ...options, env };
  const key = pathKey(opts);
  return env[key];
}

module.exports = {
  pathKey,
  getPathKey,
  getPathValue,
};

{
  "name": "sample-path-key",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-path-key",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "path-key": "3.1.1"
      }
    },
    "node_modules/path-key": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
      "license": "MIT",
      "engines": {
        "node": ">=8"
      }
    }
  }
}

{
  "name": "sample-path-key",
  "version": "1.0.0",
  "description": "Clean-room sample verifying pathKey in path-key",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "path-key": "3.1.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pathKey in pkg:npm/path-key@3.1.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/path-key@3.1.1"
  ],
  "symbols": [
    "pathKey"
  ]
}

import assert from 'node:assert';
import pathKey from 'path-key';
import { getPathKey, getPathValue } from '../index.js';

// 1. Default invocation on current platform
const defaultKey = pathKey();
assert(typeof defaultKey === 'string' && defaultKey.length > 0, 'pathKey() must return a non-empty string');
assert.strictEqual(getPathKey(), defaultKey, 'getPathKey() wrapper must return the same result as pathKey()');

// 2. POSIX platforms always return 'PATH'
const linuxKey = pathKey({ platform: 'linux' });
assert.strictEqual(linuxKey, 'PATH', 'pathKey must return "PATH" on linux platform');

const darwinKey = pathKey({ platform: 'darwin' });
assert.strictEqual(darwinKey, 'PATH', 'pathKey must return "PATH" on darwin platform');

const aixKey = pathKey({ platform: 'aix' });
assert.strictEqual(aixKey, 'PATH', 'pathKey must return "PATH" on aix platform');

// 3. Windows platform with explicit PATH casing in env
const winPathUpper = pathKey({ platform: 'win32', env: { PATH: 'mock-path-entry' } });
assert.strictEqual(winPathUpper, 'PATH', 'pathKey must detect "PATH" in env on win32');

const winPathMixed = pathKey({ platform: 'win32', env: { Path: 'mock-path-entry' } });
assert.strictEqual(winPathMixed, 'Path', 'pathKey must detect "Path" in env on win32');

const winPathLower = pathKey({ platform: 'win32', env: { path: 'mock-path-entry' } });
assert.strictEqual(winPathLower, 'path', 'pathKey must detect "path" in env on win32');

// 4. Windows platform fallback when no PATH key exists
const winFallback = pathKey({ platform: 'win32', env: { FOO: 'bar' } });
assert.strictEqual(winFallback, 'Path', 'pathKey must fallback to "Path" on win32 when no PATH variable exists');

// 5. Windows platform reverse search when multiple keys exist
const winMulti = pathKey({
  platform: 'win32',
  env: {
    Path: 'entry-first',
    PATH: 'entry-second',
  },
});
assert.strictEqual(winMulti, 'PATH', 'pathKey must return the last matching key in reverse order on win32');

// 6. getPathValue helper verification
const mockEnv = { Path: 'mock-path-value' };
const retrievedValue = getPathValue(mockEnv, { platform: 'win32' });
assert.strictEqual(retrievedValue, 'mock-path-value', 'getPathValue must resolve value using detected key');

const posixEnv = { PATH: 'posix-path-value' };
const retrievedPosix = getPathValue(posixEnv, { platform: 'linux' });
assert.strictEqual(retrievedPosix, 'posix-path-value', 'getPathValue must resolve PATH on POSIX');

console.log('All pathKey contract assertions passed successfully.');