@npmcli/installed-package-contents 3.0.0

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 pkg:npm/%40npmcli/installed-package-contents@3.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40npmcli/installed-package-contents@3.0.0

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:8476c7bb1a2eba741bb6a7a6b41ee5fd0bce85c769e46efbd336792af4cd8322","contract":["installedPackageContents({ path, depth: 1 }) resolves to an array containing surface files/directories, linked bin scripts in node_modules/.bin, and bundled dependency directories in node_modules while excluding non-bundled dependencies","installedPackageContents({ path, depth: Infinity }) recursively traverses subdirectories and bundled dependencies to list all installed files","installedPackageContents({ path, depth: 0 }) returns only the package directory path itself and its linked bin entries in node_modules/.bin","installedPackageContents({ path }) resolves to an empty array when the target path does not exist"],"goal":"verify pkg:npm/%40npmcli/installed-package-contents@3.0.0","kind":"HOW","packages":["pkg:npm/%40npmcli/installed-package-contents@3.0.0"],"schemaVersion":1},"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/%40npmcli/installed-package-contents@3.0.0"],"schemaVersion":1,"subject":"pkg:npm/%40npmcli/installed-package-contents@3.0.0","verifierAdapter":"node-typescript@1"}

{
  "name": "installed-package-contents-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "installed-package-contents-sample",
      "version": "1.0.0",
      "dependencies": {
        "@npmcli/installed-package-contents": "3.0.0"
      }
    },
    "node_modules/@npmcli/installed-package-contents": {
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/@npmcli/installed-package-contents/-/installed-package-contents-3.0.0.tgz",
      "integrity": "sha512-fkxoPuFGvxyrH+OQzyTkX2LUEamrF4jZSmxjAtPPHHGO0dqsQ8tTKjnIS8SAnPHdk2I03BDtSMR5K/4loKg79Q==",
      "license": "ISC",
      "dependencies": {
        "npm-bundled": "^4.0.0",
        "npm-normalize-package-bin": "^4.0.0"
      },
      "bin": {
        "installed-package-contents": "bin/index.js"
      },
      "engines": {
        "node": "^18.17.0 || >=20.5.0"
      }
    },
    "node_modules/npm-bundled": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/npm-bundled/-/npm-bundled-4.0.0.tgz",
      "integrity": "sha512-IxaQZDMsqfQ2Lz37VvyyEtKLe8FsRZuysmedy/N06TU1RyVppYKXrO4xIhR0F+7ubIBox6Q7nir6fQI3ej39iA==",
      "license": "ISC",
      "dependencies": {
        "npm-normalize-package-bin": "^4.0.0"
      },
      "engines": {
        "node": "^18.17.0 || >=20.5.0"
      }
    },
    "node_modules/npm-normalize-package-bin": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/npm-normalize-package-bin/-/npm-normalize-package-bin-4.0.0.tgz",
      "integrity": "sha512-TZKxPvItzai9kN9H/TkmCtx/ZN/hvr3vUycjlfmH0ootY9yFBzNOpiXAdIn1Iteqsvk4lQn6B5PTrt+n6h8k/w==",
      "license": "ISC",
      "engines": {
        "node": "^18.17.0 || >=20.5.0"
      }
    }
  }
}

{
  "name": "installed-package-contents-sample",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@npmcli/installed-package-contents": "3.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40npmcli/installed-package-contents@3.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40npmcli/installed-package-contents@3.0.0"
  ]
}

import installedPackageContents from '@npmcli/installed-package-contents'

export async function listSurfaceContents(pkgPath) {
  return installedPackageContents({ path: pkgPath, depth: 1 })
}

export async function listDeepContents(pkgPath) {
  return installedPackageContents({ path: pkgPath, depth: Infinity })
}

export async function listRootAndBins(pkgPath) {
  return installedPackageContents({ path: pkgPath, depth: 0 })
}

import assert from 'node:assert/strict'
import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join, relative } from 'node:path'
import installedPackageContents from '@npmcli/installed-package-contents'
import {
  listSurfaceContents,
  listDeepContents,
  listRootAndBins,
} from '../src/index.mjs'

const root = await mkdtemp(join(tmpdir(), 'ipc-contract-'))

try {
  const nm = join(root, 'node_modules')
  const binDir = join(nm, '.bin')
  const pkgDir = join(nm, 'demo-pkg')
  const pkgLibDir = join(pkgDir, 'lib')
  const bundledDir = join(pkgDir, 'node_modules', 'bundled-dep')
  const unbundledDir = join(pkgDir, 'node_modules', 'unbundled-dep')

  await mkdir(binDir, { recursive: true })
  await mkdir(pkgLibDir, { recursive: true })
  await mkdir(bundledDir, { recursive: true })
  await mkdir(unbundledDir, { recursive: true })

  await writeFile(join(binDir, 'demo-cli'), '#!/usr/bin/env node\n')
  await writeFile(
    join(pkgDir, 'package.json'),
    JSON.stringify({
      name: 'demo-pkg',
      version: '1.0.0',
      bin: { 'demo-cli': 'lib/cli.js' },
      dependencies: {
        'bundled-dep': '1.0.0',
        'unbundled-dep': '1.0.0',
      },
      bundleDependencies: ['bundled-dep'],
    })
  )
  await writeFile(join(pkgLibDir, 'cli.js'), 'console.log("ok")\n')
  await writeFile(
    join(bundledDir, 'package.json'),
    JSON.stringify({ name: 'bundled-dep', version: '1.0.0' })
  )
  await writeFile(join(bundledDir, 'index.js'), 'module.exports = 1\n')
  await writeFile(
    join(unbundledDir, 'package.json'),
    JSON.stringify({ name: 'unbundled-dep', version: '1.0.0' })
  )

  const toRel = (paths) => paths.map((p) => relative(nm, p)).sort()

  // 1. Default / depth: 1 lists surface files/dirs, linked bin, and bundled dep root (excluding unbundled deps)
  const surface = toRel(await listSurfaceContents(pkgDir))
  assert.deepEqual(surface, [
    '.bin/demo-cli',
    'demo-pkg/lib',
    'demo-pkg/node_modules/bundled-dep',
    'demo-pkg/package.json',
  ])

  // 2. depth: Infinity traverses recursively into subdirectories and bundled dependencies
  const deep = toRel(await listDeepContents(pkgDir))
  assert.deepEqual(deep, [
    '.bin/demo-cli',
    'demo-pkg/lib/cli.js',
    'demo-pkg/node_modules/bundled-dep/index.js',
    'demo-pkg/node_modules/bundled-dep/package.json',
    'demo-pkg/package.json',
  ])

  // 3. depth: 0 returns only the package path itself and its linked bin entries
  const rootOnly = toRel(await listRootAndBins(pkgDir))
  assert.deepEqual(rootOnly, [
    '.bin/demo-cli',
    'demo-pkg',
  ])

  // 4. Missing path resolves to an empty array
  const missing = await installedPackageContents({ path: join(nm, 'non-existent') })
  assert.deepEqual(missing, [])
} finally {
  await rm(root, { recursive: true, force: true })
}