ns-replace-package

name	ns-replace-package
description	Finds and evaluates alternatives to an npm package. Use when the user wants to replace, drop, or swap a dependency, migrate away from a deprecated/abandoned/risky package, or asks "what can I use instead of X?" Compares candidates with NCM data and provides migration/API-diff guidance. Use ns-upgrade-package for staying on the same package.

1. Identify the Package to Replace

• Extract the package name from the user's request.
• Read package.json to confirm whether it is installed and note the current version and whether it is a direct or dev dependency.
• Detect package manager by lockfile (pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm; default npm).

2. Fetch NCM Data for the Target Package

• Call getPackageQuality for the package being replaced.
• Document: vulnerabilities (severity + title), license, module risks flagged by NCM (e.g. install scripts, obfuscation, author risk, malware), quality scores.
• Use these findings as the objective reasons why replacement is warranted.

3. Propose Alternatives

• Based on the package's domain and the user's context, identify 2–3 realistic alternative packages.
• For each proposed alternative, call getPackageQuality to retrieve its own vulnerability, license, and quality data before recommending it.
• Discard any alternative that has critical/high vulnerabilities or critical module risks unless the user explicitly asks to include it.
• Do not invent unpublished packages or packages you are not confident exist.

4. Compare and Recommend

Present a comparison table or ranked list with these columns:

• Package name
• NCM vulnerability status
• License
• NCM module risks
• Maintenance signal (latest version age, if available from NCM)
• Why it is or isn't recommended

Lead with the strongest recommendation and explain the tradeoff clearly.

5. Migration Plan

For the top recommended alternative, provide:

1. Why replace — reference the NCM-reported issues with the original package.
2. Install command — exact command for the detected package manager.
3. Uninstall command — exact command to remove the original package.
4. API differences — key differences between the two APIs with before/after code examples. Focus on the most commonly used features.
5. Configuration changes — any config files, environment variables, or build-tool settings that need updating.
6. Test checklist — what to verify after migration.

Tools

• getPackageQuality — call once for the target package and once for each proposed alternative. Do not recommend an alternative without querying NCM for it first.

Guardrails

• Do not invent unpublished or fictional alternatives. Only recommend packages that genuinely exist and are relevant to the use case.
• Ground the "why replace" section in NCM-reported data, not general opinion.
• Validate every proposed alternative via getPackageQuality before including it in the comparison.
• If NCM data is unavailable for the target, state that clearly and proceed with general guidance only, flagging the absence of grounded data.