safe-version

name	safe-version
description	Find the newest version of a package that is free of known vulnerabilities, capped by a `--max-major-bump` policy. Use when picking an upgrade target for a vulnerable dep, evaluating major-version churn risk, generating a "safe pin" for a lockfile, or building an `overrides` block.
argument-hint	<package-name> [--ecosystem npm|pypi|...] [--max-major-bump 1]
user-invocable	true
allowed-tools	Bash, Read, Glob, Grep
model	sonnet
triggers	["safe version","newest safe","latest safe","upgrade target"]
chain	["fix","dep-resolve"]
outputBudget	short
cooldown	per-session

Vulnetix Safe Version Skill

Use when

• Picking the upgrade target: "what is the newest safe version of express?".
• Building a pnpm/yarn override block with the safe version as the target.
• Evaluating major-version churn — --max-major-bump 1 keeps you near the current major.
• Cross-checking which versions in a range are actually clean (the safe set is sometimes non-contiguous).
• Pre-pin decision: would pinning to vX.Y skip a known-vulnerable interval?

Don't use for

• Listing every version — use vulnetix vdb versions <package>.
• Applying the bump — use /vulnetix:fix or /vulnetix:dep-resolve.
• Single-CVE lookup — use /vulnetix:vuln.

Conventions

This skill follows _lib/contract.md: the Vulnetix CLI is auto-installed by hooks, .vulnetix/capabilities.yaml is always present, every vulnetix vdb call is piped through a verified jq filter from _lib/jq/, independent calls run in parallel as concurrent Bash tool calls, and trailing follow-ups are limited to one line. See the contract for output style, memory write rules, and cooldowns.

Step 1: Load capabilities

Default --ecosystem from derived.primary_package_manager.

Step 2: Pull versions and vulns

vulnetix vdb versions "$PACKAGE" --ecosystem "$ECO" -o json | jq -f "${CLAUDE_PLUGIN_ROOT}/skills/_lib/jq/versions.jq"
vulnetix vdb vulns "$PACKAGE" -o json | jq -f "${CLAUDE_PLUGIN_ROOT}/skills/_lib/jq/vulns.jq"
vulnetix vdb purl "pkg:${ECO}/${PACKAGE}@latest" -o json | jq -f "${CLAUDE_PLUGIN_ROOT}/skills/_lib/jq/purl.jq"

Step 3: Compute safe set

For each version in the version list:

• Mark unsafe if any known vuln's affected range includes it
• Apply --max-major-bump cap (default 1) to limit churn

Pick the newest safe version that doesn't exceed the major-bump cap.

Step 4: Render

Safe version of <package> (<ecosystem>):
Currently installed: <ver>
Latest published:   <ver>
Recommended safe:   <ver>   (skipping vulnerable: 4.16.0–4.17.2 affected by CVE-…)
Major-bump cap:     <n>

Suggest /vulnetix:fix or /vulnetix:dep-resolve to apply the bump.

No memory writes

Read-only.

Edge cases & gotchas

• --max-major-bump defaults to 1; pass 0 to stay within the current major (patch + minor only).
• Read-only — does not modify any manifests.
• Safe-version computation excludes pre-release tags (-beta, -rc); pass --include-prerelease to include them.
• vdb versions <package> returns versions across ALL ecosystems for the same package name — filter by --ecosystem to scope.
• Some versions in the response have ecosystem: "" (empty) for CVE-affected versions that do not map cleanly to a registry — ignore those for safe-version selection.
• Returns the NEWEST safe version, not the LOWEST-RISK — for risk-averse pinning, take the second-newest safe version (gives one minor of community soak time).