feat: add npm registry location type

[jimisola]

Context

With reqstool-typescript-tags getting ready, TypeScript/JavaScript projects will be able to produce reqstool artifacts. These artifacts will be published to npm registries, so reqstool needs a way to fetch them — just like it already supports Maven (ZIP) and PyPI (tar.gz) repositories.

Proposal

Add npm as a new location type, following the same patterns as the existing maven and pypi locations.

What's needed

1. NpmLocation — remote registry fetcher (src/reqstool/locations/npm_location.py)

   • Fetch package metadata from https://registry.npmjs.org/{package}/{version} (JSON API)
   • Extract the tarball URL from dist.tarball in the response
   • Download and extract the .tgz (tar.gz) — can reuse Utils.extract_targz()
   • Support custom registry URL and auth token (for private registries)

2. LocalNpmLocation — local tarball extractor (src/reqstool/locations/local_npm_location.py)

   • Minimal wrapper: extract a local .tgz file via Utils.extract_targz()
   • Used when local --npm PATH is specified

3. LOCATIONTYPES enum — add NPM = "npm" entry in src/reqstool/locations/location.py

4. CLI registration in src/reqstool/command.py:

   • Add npm subparser with --package, --version, and optional --url / --env_token arguments
   • Add --npm PATH to the local subparser (mutually exclusive with --maven / --pypi)
   • Add dispatch logic in _get_initial_source()

5. Tests — unit tests mirroring the existing Maven/PyPI location tests

npm registry API

The npm registry has a simple JSON API (no HTML scraping needed like PyPI):

GET https://registry.npmjs.org/{package}/{version}
→ { "dist": { "tarball": "https://registry.npmjs.org/{package}/-/{package}-{version}.tgz" } }

For scoped packages: https://registry.npmjs.org/@scope%2fpackage/{version}

CLI usage examples

# Remote npm registry
reqstool status npm --package @reqstool/my-ts-project --version 1.0.0

# Custom registry with auth
reqstool status npm --package @reqstool/my-ts-project --version 1.0.0 --url https://npm.pkg.github.com --env_token NPM_TOKEN

# Local tarball
reqstool status local --npm path/to/package.tgz -p path/to/reqstool

References

• Existing patterns: pypi_location.py, maven_location.py
• npm registry API: https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md