updating-npm-purl-package

name	updating-npm-purl-package
description	Sync feature parity with the upstream purl npm package. Use for purl parity, API coverage, registry validation, or normalization checks.
user-invocable	true
allowed-tools	Agent, Bash(pnpm:*), Bash(npm:*), Bash(git:*), Bash(node:*), Bash(rg:*), Bash(grep:*), Bash(find:*), Bash(ls:*), Bash(cat:*), Bash(head:*), Bash(tail:*), Bash(wc:*), Bash(diff:*), Read, Write, Edit, Grep, Glob, WebFetch

updating-npm-purl-package

Your task is to compare socket-packageurl-js against the purl npm package (https://github.com/ljharb/purl) and implement any missing features or fix any behavioral differences to maintain feature parity. **What is this?** The `purl` npm package by Jordan Harband is a reference TC54 PURL implementation. socket-packageurl-js should maintain feature parity with it while preserving our additional features (builder pattern, Result types, pattern matching, etc.).

Upstream Package:

• npm: purl (https://www.npmjs.com/package/purl)
• Repository: https://github.com/ljharb/purl
• Standard: TC54/ECMA-427

Feature Comparison Areas:

1. URL type coverage - registry URL generation for each ecosystem
2. Registry validation - which ecosystems support existence checks
3. Normalization behavior - type-specific case and encoding rules
4. Component handling - edge cases in parsing and serialization
5. API surface - new functions or methods added upstream

Reference: See reference.md for detailed feature comparison matrix and implementation guidance.

**Requirements:** - Start with clean working directory - Never remove existing features (only add or fix) - Maintain 100% test coverage - All changes must pass `pnpm run check && pnpm test`

CI Mode (detected via CI=true or GITHUB_ACTIONS):

• Create atomic commits, skip build validation

Interactive Mode (default):

• Report feature gaps to user before implementing
• Validate each change with build/tests

Do NOT:

• Copy code from the purl package (different license terms may apply)
• Remove or change our additional features (builder, Result types, matching)
• Change the public API signature of existing functions without user approval

Do ONLY:

• Add missing URL type handlers
• Add missing registry validation support
• Fix normalization differences that deviate from TC54 spec
• Add new API features that the purl package offers

Process

Phase 1: Validate Environment

Check working directory and detect mode:

if [ "$CI" = "true" ] || [ -n "$GITHUB_ACTIONS" ]; then
  CI_MODE=true
else
  CI_MODE=false
fi
git status --porcelain

---

Phase 2: Fetch Upstream Package Info

Get the latest purl package version and check for changes:

# Current purl version
npm view purl version

# Check purl changelog/releases
gh api repos/ljharb/purl/releases --jq '.[0:5] | .[] | {tag: .tag_name, date: .published_at, name: .name}'

# Get recent commits for feature changes
gh api repos/ljharb/purl/commits --jq '.[0:20] | .[] | {sha: .sha[0:7], date: .commit.author.date, message: .commit.message}'

---

Phase 3: Compare URL Type Coverage

Compare registry URL generation between purl and our implementation:

purl supports URL generation for: bioconductor, bitbucket, cargo, chrome, clojars, cocoapods, composer, conan, conda, cpan, deno, docker, elm, gem, github, golang, hackage, hex, homebrew, huggingface, luarocks, maven, npm, nuget, pub, pypi, swift, vscode

Check our UrlConverter coverage:

# Extract types from our url-converter.ts
grep "case '" src/url-converter.ts | sed "s/.*case '//;s/'.*//" | sort -u

Compare lists. Missing types need new case handlers in src/url-converter.ts.

---

Phase 4: Compare Registry Validation Coverage

Compare registry existence checking support:

purl validate() supports: npm, pypi, gem, cargo, nuget, hex, maven, composer, pub, hackage, cocoapods

Check our purlExists coverage:

grep -E 'Exists\(' src/purl-exists.ts | grep 'export' | sed 's/.*function //;s/Exists.*//' | sort

Compare lists and identify gaps.

---

Phase 5: Compare Normalization Behaviors

Test key normalization differences:

For each supported type, compare how purl and our implementation normalize:

• Type casing
• Namespace casing and encoding
• Name casing and encoding
• Version encoding
• Qualifier key ordering
• @ encoding in npm scoped packages

Use the purl npm package's test suite as a reference:

gh api repos/ljharb/purl/contents/test --jq '.[].name'

---

Phase 6: Implement Missing Features

For each identified gap, implement the feature:

What to add per gap class: URL type handlers in url-converter.ts, registry validators in purl-exists.ts, normalization fixes in the per-type handler, plus the validate-then-commit-atomically commands

For each missing URL type:

1. Add case handler to src/url-converter.ts (both toRepositoryUrl and toDownloadUrl)
2. Add test cases to test/url-converter.test.mts

For each missing registry validator:

1. Add function to src/purl-exists.ts
2. Add test cases to corresponding test/registry-*.test.mts

For normalization fixes:

1. Update type handler in src/purl-types/{type}.ts
2. Add edge case tests

# Validate after each change
pnpm run check
pnpm test

Commit atomically per logical feature:

git add <files>
git commit -m "feat(url-converter): add {type} registry URL support

Added repository and download URL generation for {type} ecosystem."

---

Phase 7: Final Validation

Run full validation (skip in CI mode):

if [ "$CI_MODE" = "true" ]; then
  echo "CI mode: Skipping final validation"
else
  pnpm run fix
  pnpm run check
  pnpm test
  pnpm run cover
fi

---

Phase 8: Report Summary

Generate feature parity report:

The feature-parity report template: URL type coverage table, registry validation table, normalization fixes, API features, and commits created

## Feature Parity Sync Complete

### purl npm package version: vX.Y.Z

### URL Type Coverage:
| Type | purl | socket-packageurl-js | Status |
|------|------|---------------------|--------|
| ... | ... | ... | Added/Already supported/N/A |

### Registry Validation:
| Type | purl | socket-packageurl-js | Status |
|------|------|---------------------|--------|
| ... | ... | ... | Added/Already supported |

### Normalization Fixes:
- [list any fixes applied]

### API Features:
- [list any new features added]

### Commits Created:
- [list commits]

Success Criteria

• URL type coverage matches or exceeds purl package
• Registry validation covers all purl-supported types
• Normalization behavior matches TC54 spec
• All tests pass with 100% coverage
• Feature parity report generated

Context

This skill is useful for:

• Monthly feature parity checks
• After new purl npm releases
• Before major version releases
• When users report behavioral differences vs purl package

Safety: Read-only analysis first, changes only after user review (interactive mode).