npm-run-path 4.0.1: get augmented PATH string with npm-run-path

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: get augmented PATH string with npm-run-path
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/npm-run-path@4.0.1
Demonstrate these symbols/APIs:
  - npmRunPath
  - npmRunPath.env

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:242ac396d6f8e8d5cb3d8f61421f1f7f168bf71833d5220870072fd237a41cb4","contract":["npmRunPath returns a string containing local node_modules/.bin directories and node binary path","npmRunPath with custom cwd and path prepends parent node_modules/.bin directories to custom path","npmRunPath with custom execPath includes directory of specified executable","npmRunPath.env returns copy of environment with augmented PATH key","npmRunPath.env with custom env object augments custom PATH without mutating original input","npmRunPath.default export provides interop compatibility"],"goal":"get augmented PATH string with npm-run-path","kind":"HOW","packages":["pkg:npm/npm-run-path@4.0.1"],"schemaVersion":1,"symbols":["npmRunPath","npmRunPath.env"]},"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/npm-run-path@4.0.1"],"schemaVersion":1,"subject":"pkg:npm/npm-run-path@4.0.1","symbols":["npmRunPath","npmRunPath.env"],"verifierAdapter":"node-typescript@1"}

const npmRunPath = require('npm-run-path');

function getAugmentedPath(options) {
  return npmRunPath(options);
}

function getAugmentedEnv(options) {
  return npmRunPath.env(options);
}

module.exports = {
  npmRunPath,
  getAugmentedPath,
  getAugmentedEnv,
};

{
  "name": "sample-npm-run-path",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-npm-run-path",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "npm-run-path": "4.0.1"
      }
    },
    "node_modules/npm-run-path": {
      "version": "4.0.1",
      "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-4.0.1.tgz",
      "integrity": "sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==",
      "license": "MIT",
      "dependencies": {
        "path-key": "^3.0.0"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "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-npm-run-path",
  "version": "1.0.0",
  "description": "Get augmented PATH string and environment with npm-run-path",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "npm-run-path": "4.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "get augmented PATH string with npm-run-path",
  "kind": "HOW",
  "packages": [
    "pkg:npm/npm-run-path@4.0.1"
  ],
  "symbols": [
    "npmRunPath",
    "npmRunPath.env"
  ]
}

import assert from 'node:assert';
import path from 'node:path';
import npmRunPath from 'npm-run-path';
import { getAugmentedPath, getAugmentedEnv } from '../index.js';

// 1. npmRunPath returns a string containing local node_modules/.bin directories and node binary path
const defaultPath = npmRunPath();
assert.strictEqual(typeof defaultPath, 'string', 'default npmRunPath() must return a string');
assert(defaultPath.includes('node_modules' + path.sep + '.bin'), 'default path must contain node_modules/.bin');

const helperPath = getAugmentedPath();
assert.strictEqual(typeof helperPath, 'string', 'getAugmentedPath helper must return a string');
assert(helperPath.includes('node_modules' + path.sep + '.bin'), 'helper path must contain node_modules/.bin');

// 2. npmRunPath with custom cwd and path prepends parent node_modules/.bin directories to custom path
const fakeCwd = path.resolve('fake-project', 'sub-dir');
const fakeExecPath = path.resolve('fake-bin', 'node');
const customPath = npmRunPath({
  cwd: fakeCwd,
  path: 'fake-custom-bin',
  execPath: fakeExecPath,
});
const pathParts = customPath.split(path.delimiter);
assert(pathParts.includes(path.join(fakeCwd, 'node_modules/.bin')), 'must include cwd node_modules/.bin');
assert(pathParts.includes(path.join(path.dirname(fakeCwd), 'node_modules/.bin')), 'must include parent node_modules/.bin');
assert(pathParts.includes('fake-custom-bin'), 'must retain custom input path');
assert(pathParts.includes(path.dirname(fakeExecPath)), 'must include dirname of custom execPath');

// 3. npmRunPath with custom execPath includes directory of specified executable
const execDir = path.resolve('fake-opt', 'node', 'bin');
const execPath = path.join(execDir, 'node');
const customExecResult = npmRunPath({
  cwd: path.resolve('fake-app'),
  path: '',
  execPath,
});
const customExecParts = customExecResult.split(path.delimiter);
assert(customExecParts.includes(execDir), 'must include directory of custom execPath');

// 4. npmRunPath.env returns copy of environment with augmented PATH key
const envResult = npmRunPath.env();
assert.strictEqual(typeof envResult, 'object', 'npmRunPath.env() must return an object');
assert('PATH' in envResult || 'Path' in envResult, 'augmented environment must have a PATH key');
const helperEnv = getAugmentedEnv();
assert.strictEqual(typeof helperEnv, 'object', 'getAugmentedEnv helper must return an object');

// 5. npmRunPath.env with custom env object augments custom PATH without mutating original input
const originalEnv = {
  PATH: 'fake-base-bin',
  CUSTOM_VAR: 'csx_test_value',
};
const customEnvCwd = path.resolve('fake-test-app');
const augmentedEnv = npmRunPath.env({
  env: originalEnv,
  cwd: customEnvCwd,
  execPath: fakeExecPath,
});
assert.strictEqual(originalEnv.PATH, 'fake-base-bin', 'original env object must not be mutated');
assert.strictEqual(augmentedEnv.CUSTOM_VAR, 'csx_test_value', 'custom environment variables must be preserved');
assert(augmentedEnv.PATH.includes(path.join(customEnvCwd, 'node_modules/.bin')), 'augmented PATH must include node_modules/.bin');
assert(augmentedEnv.PATH.includes('fake-base-bin'), 'augmented PATH must include original base path');

// 6. npmRunPath.default export provides interop compatibility
assert.strictEqual(typeof npmRunPath, 'function', 'npmRunPath must be callable');
assert.strictEqual(npmRunPath.default, npmRunPath, 'npmRunPath.default must point to npmRunPath for CJS/ESM interop');
assert.strictEqual(typeof npmRunPath.env, 'function', 'npmRunPath.env must be a function');

console.log('All npm-run-path contract assertions passed.');