@rainy-updates/cli 0.5.1-rc.3 → 0.5.2-rc.1

package/CHANGELOG.md

@@ -1,7 +1,151 @@
-# Changelog
+# CHANGELOG
 
 All notable changes to this project are documented in this file.
 
+## [0.5.2] - 2026-02-27
+
+### Added
+
+- **New `unused` command**: Detect unused and missing npm dependencies by statically scanning source files.
+  - Walks `src/` (configurable via `--src`) and extracts all import/require specifiers (ESM static, ESM dynamic, CJS, re-exports).
+  - Cross-references against `package.json` `dependencies`, `devDependencies`, and `optionalDependencies`.
+  - Reports two problem classes: `declared-not-imported` (unused bloat) and `imported-not-declared` (missing declarations).
+  - `--fix` — removes unused entries from `package.json` atomically (with `--dry-run` preview).
+  - `--no-dev` — skip `devDependencies` from the unused scan.
+  - `--json-file <path>` — write structured JSON report for CI pipelines.
+  - Exit code `1` when unused or missing dependencies are found.
+
+- **New `resolve` command**: Pure-TS in-memory peer dependency conflict detector — **no `npm install` subprocess spawned**.
+  - Builds a `PeerGraph` from declared dependencies, enriched with `peerDependencies` fetched in parallel from the registry (cache-first — instant on warm cache, offline-capable).
+  - Performs a single-pass O(n × peers) BFS traversal using the new `satisfies()` semver util.
+  - Classifies conflicts as `error` (ERESOLVE-level, different major) or `warning` (soft peer incompatibility).
+  - Generates human-readable fix suggestions per conflict.
+  - `--after-update` — simulates proposed `rup check` updates in-memory _before_ writing anything, showing you peer conflicts before they happen.
+  - `--safe` — exits non-zero on any error-level conflict.
+  - `--json-file <path>` — write structured JSON conflict report.
+  - Exit code `1` when error-level conflicts are detected.
+
+- **New `licenses` command**: SPDX license compliance scanning with SBOM generation.
+  - Fetches the `license` field from each dependency's npm packument in parallel.
+  - Normalizes raw license strings to SPDX 2.x identifiers.
+  - `--allow <spdx,...>` — allowlist mode: flag any package not in the list.
+  - `--deny <spdx,...>` — denylist mode: flag any package matching these identifiers.
+  - `--sbom <path>` — generate a standards-compliant **SPDX 2.3 JSON SBOM** document (`DESCRIBES` + `DEPENDS_ON` relationship graph, required by CISA/EU CRA mandates).
+  - `--json-file <path>` — write full license report as JSON.
+  - Exit code `1` when license violations are detected.
+
+- **New `snapshot` command**: Save, list, restore, and diff dependency state snapshots.
+  - `rup snapshot save [--label <name>]` — captures `package.json` contents and lockfile hashes for all workspace packages into a lightweight JSON store (`.rup-snapshots.json`).
+  - `rup snapshot list` — shows all saved snapshots with timestamp and label.
+  - `rup snapshot restore <id|label>` — writes back captured `package.json` files atomically; prompts to re-run the package manager install.
+  - `rup snapshot diff <id|label>` — shows dependency version changes since the snapshot.
+  - JSON-file store (no SQLite dependency), human-readable and git-committable.
+  - `--store <path>` — custom store file location.
+
+- **Impact Score engine** (`src/core/impact.ts`): Per-update risk assessment.
+  - Computes a 0–100 composite score: `diffTypeWeight` (patch=10, minor=25, major=55) + CVE presence bonus (+35) + workspace spread (up to +20).
+  - Ranks each update as `critical`, `high`, `medium`, or `low`.
+  - `applyImpactScores()` batch helper for the check/upgrade pipeline.
+  - ANSI `impactBadge()` for terminal table rendering (wired to `--show-impact` flag, coming in a follow-up).
+
+- **`satisfies(version, range)` utility** (`src/utils/semver.ts`): Pure-TS semver range checker.
+  - Handles `^`, `~`, `>=`, `<=`, `>`, `<`, exact, `*`/empty (always true).
+  - Supports compound AND ranges (`>=1.0.0 <2.0.0`) and OR union ranges (`^16 || ^18`).
+  - Falls through gracefully on non-semver inputs (e.g., `workspace:*`, `latest`) — no false-positive conflicts.
+  - Used by `rup resolve` peer graph resolver.
+
+### Architecture
+
+- `unused`, `resolve`, `licenses`, and `snapshot` are fully isolated modules under `src/commands/`. All are lazy-loaded (dynamic `import()`) on first invocation — zero startup cost penalty.
+- `src/core/options.ts` dispatches all 4 new commands to their isolated sub-parsers. `KNOWN_COMMANDS` now contains **13 entries**.
+- `ParsedCliArgs` union extended with 4 new command variants.
+- `src/types/index.ts` extended with: `ImpactScore`, `PeerNode`, `PeerGraph`, `PeerConflict`, `PeerConflictSeverity`, `UnusedKind`, `UnusedDependency`, `UnusedOptions`, `UnusedResult`, `PackageLicense`, `SbomDocument`, `SbomPackage`, `SbomRelationship`, `LicenseOptions`, `LicenseResult`, `SnapshotEntry`, `SnapshotAction`, `SnapshotOptions`, `SnapshotResult`, `ResolveOptions`, `ResolveResult`.
+- `PackageUpdate` extended with optional `impactScore?: ImpactScore` and `homepage?: string` fields.
+
+### Changed
+
+- CLI global help updated to list all **13 commands** including `unused`, `resolve`, `licenses`, and `snapshot`.
+- `src/bin/cli.ts` exit codes: `unused` exits `1` on any unused/missing dep; `resolve` exits `1` on error-level peer conflicts; `licenses` exits `1` on violations; `snapshot` exits `1` on store errors.
+
+---
+
+## [0.5.1] - 2026-02-27
+
+### Added
+
+- **New `audit` command**: Scan dependencies for known CVEs using [OSV.dev](https://osv.dev) (Google's open vulnerability database). Runs queries in parallel for all installed packages.
+  - `--severity critical|high|medium|low` — Filter by minimum severity level
+  - `--fix` — Print the minimum-secure-version `npm install` command to patch advisories
+  - `--dry-run` — Preview without side effects
+  - `--report json` — Machine-readable JSON output
+  - `--json-file <path>` — Write JSON report to file for CI pipelines
+  - Exit code `1` when vulnerabilities are found; `0` when clean.
+
+- **New `health` command**: Surface stale, deprecated, and unmaintained packages before they become liabilities.
+  - `--stale 12m|180d|365` — Flag packages with no release in the given period (supports months and days)
+  - `--deprecated` / `--no-deprecated` — Control deprecated package detection
+  - `--alternatives` — Suggest active alternatives for deprecated packages
+  - `--report json` — Machine-readable JSON output
+  - Exit code `1` when flagged packages are found.
+
+- **New `bisect` command**: Binary search across semver versions to find the exact version that introduced a failing test or breaking change.
+  - `rup bisect <package> --cmd "<test command>"` — Specify test oracle command
+  - `--range <start>..<end>` — Narrow the search to a specific version range
+  - `--dry-run` — Simulate without installing anything
+  - Exit code `1` when a breaking version is identified.
+
+- **New CLI binary aliases for developer ergonomics**:
+  - `rup` — Ultra-short power-user alias (e.g., `rup ci`, `rup audit`)
+  - `rainy-up` — Human-friendly alias (e.g., `rainy-up check`)
+  - `rainy-updates` retained for backwards compatibility with CI scripts.
+
+### Architecture
+
+- `bisect`, `audit`, and `health` are fully isolated modules under `src/commands/`. They are lazy-loaded (dynamic `import()`) only when their command is invoked — zero startup cost penalty.
+- `src/core/options.ts` now dispatches `bisect`, `audit`, and `health` to their isolated sub-parsers, keeping the command router clean and extensible.
+- New type definitions: `AuditOptions`, `AuditResult`, `CveAdvisory`, `BisectOptions`, `BisectResult`, `HealthOptions`, `HealthResult`, `PackageHealthMetric`.
+
+### Changed
+
+- CLI global help updated to list all 9 commands.
+- Error messages now include `(rup)` in the binary identifier.
+- `package.json` description updated to reflect DevOps-first positioning.
+
+## [0.5.1-rc.4] - 2026-02-27
+
+### Added
+
+- New registry and stream controls:
+  - `--registry-timeout-ms <n>`
+  - `--registry-retries <n>`
+  - `--stream`
+- New lockfile execution control:
+  - `--lockfile-mode preserve|update|error`
+- Policy extensions:
+  - package rule `target` override
+  - package rule `autofix` control for fix-PR flows
+- New additive summary/output metadata:
+  - `streamedEvents`
+  - `policyOverridesApplied`
+  - `registryAuthFailure`
+  - `streamed_events` GitHub output key
+  - `policy_overrides_applied` GitHub output key
+  - `registry_auth_failures` GitHub output key
+
+### Changed
+
+- Registry client now supports configurable retry count and timeout defaults.
+- Registry resolution now supports `.npmrc` auth token/basic auth parsing for scoped/private registries.
+- Fix-PR automation now excludes updates with `autofix: false`.
+- CI workflow templates generated by `init-ci` now include stream mode and registry control flags.
+- Upgrade flow now enforces explicit lockfile policy semantics via `--lockfile-mode`.
+
+### Tests
+
+- Extended options parsing tests for registry/stream/lockfile flags.
+- Extended policy tests for `target` and `autofix` rule behavior.
+- Updated output and summary tests for additive metadata fields.
+
 ## [0.5.1-rc.3] - 2026-02-27
 
 ### Fixed
@@ -182,7 +326,6 @@ All notable changes to this project are documented in this file.
   - `--schedule weekly|daily|off`
   - package-manager-aware install step generation (npm/pnpm)
 
-
 ## [0.4.0] - 2026-02-27
 
 ### Added

package/README.md

@@ -1,8 +1,8 @@
 # @rainy-updates/cli
 
-Agentic CLI to detect, control, and apply dependency updates across npm/pnpm projects and monorepos.
+The fastest DevOps-first dependency CLI. Checks, audits, upgrades, bisects, and automates npm/pnpm dependencies in CI.
 
-`@rainy-updates/cli` is built for teams that need fast dependency intelligence, policy-aware upgrades, and automation-ready output for CI/CD and pull request workflows.
+`@rainy-updates/cli` is built for teams that need fast dependency intelligence, security auditing, policy-aware upgrades, and automation-ready output for CI/CD and pull request workflows.
 
 ## Why this package
 
@@ -15,47 +15,104 @@ Agentic CLI to detect, control, and apply dependency updates across npm/pnpm pro
 ## Install
 
 ```bash
-npm i -D @rainy-updates/cli
+# As a project dev dependency (recommended for teams)
+npm install --save-dev @rainy-updates/cli
 # or
 pnpm add -D @rainy-updates/cli
 ```
 
-## Core commands
+Once installed, three binary aliases are available in your `node_modules/.bin/`:
 
-- `check`: analyze dependencies and report available updates.
-- `upgrade`: rewrite dependency ranges in manifests, optionally install lockfile updates.
-- `ci`: run CI-focused dependency automation (warm cache, check/upgrade, policy gates).
-- `warm-cache`: prefetch package metadata for fast and offline checks.
-- `baseline`: save and compare dependency baseline snapshots.
+| Alias           | Use case                                    |
+| --------------- | ------------------------------------------- |
+| `rup`           | Power-user shortcut — `rup ci`, `rup audit` |
+| `rainy-up`      | Human-friendly — `rainy-up check`           |
+| `rainy-updates` | Backwards-compatible (safe in CI scripts)   |
+
+```bash
+# All three are identical — use whichever you prefer:
+rup check
+rainy-up check
+rainy-updates check
+```
+
+### One-off usage with npx (no install required)
+
+```bash
+# Always works without installing:
+npx @rainy-updates/cli check
+npx @rainy-updates/cli audit --severity high
+npx @rainy-updates/cli ci --workspace --mode strict
+```
+
+> **Note:** The short aliases (`rup`, `rainy-up`) only work after installing the package. For one-off `npx` runs, use `npx @rainy-updates/cli <command>`.
+
+## Commands
+
+### Dependency management
+
+- `check` — analyze dependencies and report available updates
+- `upgrade` — rewrite dependency ranges in manifests, optionally install lockfile updates
+- `ci` — run CI-focused dependency automation (warm cache, check/upgrade, policy gates)
+- `warm-cache` — prefetch package metadata for fast and offline checks
+- `baseline` — save and compare dependency baseline snapshots
+
+### Security & health (_new in v0.5.1_)
+
+- `audit` — scan dependencies for CVEs using [OSV.dev](https://osv.dev) (Google's open vulnerability database)
+- `health` — detect stale, deprecated, and unmaintained packages before they become liabilities
+- `bisect` — binary-search across semver versions to find the exact version that broke your tests
 
 ## Quick usage
 
+> Commands work with `npx` (no install) **or** with the `rup` / `rainy-up` shortcut if the package is installed.
+
 ```bash
 # 1) Detect updates
 npx @rainy-updates/cli check --format table
+rup check --format table                      # if installed
 
 # 2) Strict CI mode (non-zero when updates exist)
 npx @rainy-updates/cli check --workspace --ci --format json --json-file .artifacts/updates.json
+rup check --workspace --ci --format json --json-file .artifacts/updates.json
 
-# 2b) CI orchestration mode
-npx @rainy-updates/cli ci --workspace --mode strict --format github --json-file .artifacts/updates.json
+# 3) CI orchestration with policy gates
+npx @rainy-updates/cli ci --workspace --mode strict --format github
+rup ci --workspace --mode strict --format github
 
-# 2c) Batch fix branches by scope
+# 4) Batch fix branches by scope (enterprise)
 npx @rainy-updates/cli ci --workspace --mode enterprise --group-by scope --fix-pr --fix-pr-batch-size 2
+rup ci --workspace --mode enterprise --group-by scope --fix-pr --fix-pr-batch-size 2
 
-# 3) Apply upgrades with workspace sync
+# 5) Apply upgrades with workspace sync
 npx @rainy-updates/cli upgrade --target latest --workspace --sync --install
+rup upgrade --target latest --workspace --sync --install
 
-# 3b) Generate a fix branch + commit for CI automation
-npx @rainy-updates/cli check --workspace --fix-pr --fix-branch chore/rainy-updates
-
-# 4) Warm cache for deterministic offline checks
+# 6) Warm cache → deterministic offline CI check
 npx @rainy-updates/cli warm-cache --workspace --concurrency 32
 npx @rainy-updates/cli check --workspace --offline --ci
 
-# 5) Save and compare baseline drift in CI
+# 7) Save and compare baseline drift
 npx @rainy-updates/cli baseline --save --file .artifacts/deps-baseline.json --workspace
 npx @rainy-updates/cli baseline --check --file .artifacts/deps-baseline.json --workspace --ci
+
+# 8) Scan for known CVEs  ── NEW in v0.5.1
+npx @rainy-updates/cli audit
+npx @rainy-updates/cli audit --severity high
+npx @rainy-updates/cli audit --fix          # prints the patching npm install command
+rup audit --severity high                   # if installed
+
+# 9) Check dependency maintenance health  ── NEW in v0.5.1
+npx @rainy-updates/cli health
+npx @rainy-updates/cli health --stale 6m   # flag packages with no release in 6 months
+npx @rainy-updates/cli health --stale 180d # same but in days
+rup health --stale 6m                       # if installed
+
+# 10) Find which version introduced a breaking change  ── NEW in v0.5.1
+npx @rainy-updates/cli bisect axios --cmd "bun test"
+npx @rainy-updates/cli bisect react --range "18.0.0..19.0.0" --cmd "npm test"
+npx @rainy-updates/cli bisect lodash --cmd "npm run test:unit" --dry-run
+rup bisect axios --cmd "bun test"           # if installed
 ```
 
 ## What it does in production
@@ -65,7 +122,9 @@ npx @rainy-updates/cli baseline --check --file .artifacts/deps-baseline.json --w
 - Scans dependency groups: `dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`.
 - Resolves versions per unique package to reduce duplicate network requests.
 - Uses network concurrency controls and resilient retries.
+- Supports explicit registry retry/timeout tuning (`--registry-retries`, `--registry-timeout-ms`).
 - Supports stale-cache fallback when registry calls fail.
+- Supports streamed progress output for long CI runs (`--stream`).
 
 ### Workspace support
 
@@ -80,6 +139,7 @@ npx @rainy-updates/cli baseline --check --file .artifacts/deps-baseline.json --w
 - Apply global ignore patterns.
 - Apply package-specific rules.
 - Enforce max upgrade target per package (for safer rollout).
+- Support per-package target override and fix-pr inclusion (`target`, `autofix`).
 
 Example policy file:
 
@@ -87,7 +147,7 @@ Example policy file:
 {
   "ignore": ["@types/*", "eslint*"],
   "packageRules": {
-    "react": { "maxTarget": "minor" },
+    "react": { "maxTarget": "minor", "target": "patch", "autofix": false },
     "typescript": { "ignore": true }
   }
 }
@@ -116,17 +176,16 @@ npx @rainy-updates/cli check --policy-file .rainyupdates-policy.json
 
 These outputs are designed for CI pipelines, security tooling, and PR review automation.
 
-
 ## Automatic CI bootstrap
 
 Generate a workflow in the target project automatically:
 
 ```bash
-# strict mode (recommended)
-npx @rainy-updates/cli init-ci --mode enterprise --schedule weekly
+# enterprise mode (recommended)
+rup init-ci --mode enterprise --schedule weekly
 
 # lightweight mode
-npx @rainy-updates/cli init-ci --mode minimal --schedule daily
+rup init-ci --mode minimal --schedule daily
 ```
 
 Generated file:
@@ -155,7 +214,10 @@ Schedule:
 - `--dep-kinds deps,dev,optional,peer`
 - `--concurrency <n>`
 - `--cache-ttl <seconds>`
+- `--registry-timeout-ms <n>`
+- `--registry-retries <n>`
 - `--offline`
+- `--stream`
 - `--fail-on none|patch|minor|major|any`
 - `--max-updates <n>`
 - `--group-by none|name|scope|kind|risk`
@@ -175,6 +237,7 @@ Schedule:
 - `--fix-branch <name>`
 - `--fix-commit-message <text>`
 - `--fix-dry-run`
+- `--lockfile-mode preserve|update|error`
 - `--no-pr-report`
 - `--ci`
 
@@ -201,9 +264,13 @@ Configuration can be loaded from:
 ## CLI help
 
 ```bash
+rup --help
+rup <command> --help
+rup --version
+
+# or with the full name:
 rainy-updates --help
-rainy-updates <command> --help
-rainy-updates --version
+npx @rainy-updates/cli --help
 ```
 
 ## Reliability characteristics
@@ -223,7 +290,6 @@ This package ships with production CI/CD pipelines in the repository:
 - Tag-driven release pipeline for npm publishing with provenance.
 - Release preflight validation for npm auth/scope checks before publishing.
 
-
 ## Product roadmap
 
 The long-term roadmap is maintained in [`ROADMAP.md`](./ROADMAP.md).

package/dist/bin/cli.js

@@ -66,16 +66,68 @@ async function main() {
             process.exitCode = 1;
             return;
         }
+        // ─── v0.5.1 commands: lazy-loaded, isolated from check pipeline ──────────
+        if (parsed.command === "bisect") {
+            const { runBisect } = await import("../commands/bisect/runner.js");
+            const result = await runBisect(parsed.options);
+            process.exitCode = result.breakingVersion ? 1 : 0;
+            return;
+        }
+        if (parsed.command === "audit") {
+            const { runAudit } = await import("../commands/audit/runner.js");
+            const result = await runAudit(parsed.options);
+            process.exitCode = result.advisories.length > 0 ? 1 : 0;
+            return;
+        }
+        if (parsed.command === "health") {
+            const { runHealth } = await import("../commands/health/runner.js");
+            const result = await runHealth(parsed.options);
+            process.exitCode = result.totalFlagged > 0 ? 1 : 0;
+            return;
+        }
+        // ─── v0.5.2 commands ─────────────────────────────────────────────────────
+        if (parsed.command === "unused") {
+            const { runUnused } = await import("../commands/unused/runner.js");
+            const result = await runUnused(parsed.options);
+            process.exitCode =
+                result.totalUnused > 0 || result.totalMissing > 0 ? 1 : 0;
+            return;
+        }
+        if (parsed.command === "resolve") {
+            const { runResolve } = await import("../commands/resolve/runner.js");
+            const result = await runResolve(parsed.options);
+            process.exitCode = result.errorConflicts > 0 ? 1 : 0;
+            return;
+        }
+        if (parsed.command === "licenses") {
+            const { runLicenses } = await import("../commands/licenses/runner.js");
+            const result = await runLicenses(parsed.options);
+            process.exitCode = result.totalViolations > 0 ? 1 : 0;
+            return;
+        }
+        if (parsed.command === "snapshot") {
+            const { runSnapshot } = await import("../commands/snapshot/runner.js");
+            const result = await runSnapshot(parsed.options);
+            process.exitCode = result.errors.length > 0 ? 1 : 0;
+            return;
+        }
         const result = await runCommand(parsed);
-        if (parsed.options.fixPr && (parsed.command === "check" || parsed.command === "upgrade" || parsed.command === "ci")) {
+        if (parsed.options.fixPr &&
+            (parsed.command === "check" ||
+                parsed.command === "upgrade" ||
+                parsed.command === "ci")) {
             result.summary.fixPrApplied = false;
-            result.summary.fixBranchName = parsed.options.fixBranch ?? "chore/rainy-updates";
+            result.summary.fixBranchName =
+                parsed.options.fixBranch ?? "chore/rainy-updates";
             result.summary.fixCommitSha = "";
             result.summary.fixPrBranchesCreated = 0;
             if (parsed.command === "ci") {
                 const batched = await applyFixPrBatches(parsed.options, result);
                 result.summary.fixPrApplied = batched.applied;
-                result.summary.fixBranchName = batched.branches[0] ?? (parsed.options.fixBranch ?? "chore/rainy-updates");
+                result.summary.fixBranchName =
+                    batched.branches[0] ??
+                        parsed.options.fixBranch ??
+                        "chore/rainy-updates";
                 result.summary.fixCommitSha = batched.commits[0] ?? "";
                 result.summary.fixPrBranchesCreated = batched.branches.length;
                 if (batched.branches.length > 1) {
@@ -98,14 +150,17 @@ async function main() {
         const renderStartedAt = Date.now();
         let rendered = renderResult(result, parsed.options.format);
         result.summary.durationMs.render = Math.max(0, Date.now() - renderStartedAt);
-        if (parsed.options.format === "json" || parsed.options.format === "metrics") {
+        if (parsed.options.format === "json" ||
+            parsed.options.format === "metrics") {
             rendered = renderResult(result, parsed.options.format);
         }
         if (parsed.options.onlyChanged &&
             result.updates.length === 0 &&
             result.errors.length === 0 &&
             result.warnings.length === 0 &&
-            (parsed.options.format === "table" || parsed.options.format === "minimal" || parsed.options.format === "github")) {
+            (parsed.options.format === "table" ||
+                parsed.options.format === "minimal" ||
+                parsed.options.format === "github")) {
             rendered = "";
         }
         if (parsed.options.jsonFile) {
@@ -122,7 +177,7 @@ async function main() {
         process.exitCode = resolveExitCode(result, result.summary.failReason);
     }
     catch (error) {
-        process.stderr.write(`rainy-updates: ${String(error)}\n`);
+        process.stderr.write(`rainy-updates (rup): ${String(error)}\n`);
         process.exitCode = 2;
     }
 }
@@ -141,7 +196,10 @@ Options:
   --reject <pattern>
   --dep-kinds deps,dev,optional,peer
   --concurrency <n>
+  --registry-timeout-ms <n>
+  --registry-retries <n>
   --cache-ttl <seconds>
+  --stream
   --policy-file <path>
   --offline
   --fix-pr
@@ -162,6 +220,7 @@ Options:
   --cooldown-days <n>
   --pr-limit <n>
   --only-changed
+  --lockfile-mode preserve|update|error
   --log-level error|warn|info|debug
   --ci`;
     }
@@ -177,8 +236,11 @@ Options:
   --reject <pattern>
   --dep-kinds deps,dev,optional,peer
   --concurrency <n>
+  --registry-timeout-ms <n>
+  --registry-retries <n>
   --cache-ttl <seconds>
   --offline
+  --stream
   --json-file <path>
   --github-output <path>
   --sarif-file <path>
@@ -197,12 +259,15 @@ Options:
   --target patch|minor|major|latest
   --policy-file <path>
   --concurrency <n>
+  --registry-timeout-ms <n>
+  --registry-retries <n>
   --fix-pr
   --fix-branch <name>
   --fix-commit-message <text>
   --fix-dry-run
   --fix-pr-no-checkout
   --fix-pr-batch-size <n>
+  --lockfile-mode preserve|update|error
   --no-pr-report
   --json-file <path>
   --pr-report-file <path>`;
@@ -222,6 +287,9 @@ Options:
   --only-changed
   --offline
   --concurrency <n>
+  --registry-timeout-ms <n>
+  --registry-retries <n>
+  --stream
   --fix-pr
   --fix-branch <name>
   --fix-commit-message <text>
@@ -235,6 +303,7 @@ Options:
   --pr-report-file <path>
   --fail-on none|patch|minor|major|any
   --max-updates <n>
+  --lockfile-mode preserve|update|error
   --log-level error|warn|info|debug
   --ci`;
     }
@@ -262,7 +331,7 @@ Options:
   --dep-kinds deps,dev,optional,peer
   --ci`;
     }
-    return `rainy-updates <command> [options]
+    return `rainy-updates (rup / rainy-up) <command> [options]
 
 Commands:
   check       Detect available updates
@@ -271,6 +340,13 @@ Commands:
   warm-cache  Warm local cache for fast/offline checks
   init-ci     Scaffold GitHub Actions workflow
   baseline    Save/check dependency baseline snapshots
+  audit       Scan dependencies for CVEs (OSV.dev)
+  health      Detect stale/deprecated/unmaintained packages
+  bisect      Find which version of a dep introduced a failure
+  unused      Detect unused or missing npm dependencies
+  resolve     Check peer dependency conflicts (pure-TS, no subprocess)
+  licenses    Scan dependency licenses and generate SPDX SBOM
+  snapshot    Save, list, restore, and diff dependency state snapshots
 
 Global options:
   --cwd <path>
@@ -299,8 +375,12 @@ Global options:
   --no-pr-report
   --log-level error|warn|info|debug
   --concurrency <n>
+  --registry-timeout-ms <n>
+  --registry-retries <n>
   --cache-ttl <seconds>
   --offline
+  --stream
+  --lockfile-mode preserve|update|error
   --ci
   --help, -h
   --version, -v`;

package/dist/commands/audit/fetcher.d.ts

@@ -0,0 +1,6 @@
+import type { CveAdvisory, AuditOptions } from "../../types/index.js";
+/**
+ * Fetches CVE advisories for all given package names in parallel.
+ * Uses OSV.dev as primary source.
+ */
+export declare function fetchAdvisories(packageNames: string[], options: Pick<AuditOptions, "concurrency" | "registryTimeoutMs">): Promise<CveAdvisory[]>;

package/dist/commands/audit/fetcher.js

@@ -0,0 +1,79 @@
+import { asyncPool } from "../../utils/async-pool.js";
+const OSV_API = "https://api.osv.dev/v1/query";
+const GITHUB_ADVISORY_API = "https://api.github.com/advisories";
+/**
+ * Queries OSV.dev for advisories for a single npm package.
+ */
+async function queryOsv(packageName, timeoutMs) {
+    const body = JSON.stringify({
+        package: { name: packageName, ecosystem: "npm" },
+    });
+    let response;
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        response = await fetch(OSV_API, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+    }
+    catch {
+        return [];
+    }
+    if (!response.ok)
+        return [];
+    const data = (await response.json());
+    const advisories = [];
+    for (const vuln of data.vulns ?? []) {
+        const cveId = vuln.id ?? "UNKNOWN";
+        const rawSeverity = (vuln.database_specific?.severity ?? "medium").toLowerCase();
+        const severity = (["critical", "high", "medium", "low"].includes(rawSeverity)
+            ? rawSeverity
+            : "medium");
+        let patchedVersion = null;
+        let vulnerableRange = "*";
+        for (const affected of vuln.affected ?? []) {
+            if (affected.package?.name !== packageName)
+                continue;
+            for (const range of affected.ranges ?? []) {
+                const fixedEvent = range.events?.find((e) => e.fixed);
+                if (fixedEvent?.fixed) {
+                    patchedVersion = fixedEvent.fixed;
+                    const introducedEvent = range.events?.find((e) => e.introduced);
+                    vulnerableRange = introducedEvent?.introduced
+                        ? `>=${introducedEvent.introduced} <${patchedVersion}`
+                        : `<${patchedVersion}`;
+                }
+            }
+        }
+        advisories.push({
+            cveId,
+            packageName,
+            severity,
+            vulnerableRange,
+            patchedVersion,
+            title: vuln.summary ?? cveId,
+            url: vuln.references?.[0]?.url ?? `https://osv.dev/vulnerability/${cveId}`,
+        });
+    }
+    return advisories;
+}
+/**
+ * Fetches CVE advisories for all given package names in parallel.
+ * Uses OSV.dev as primary source.
+ */
+export async function fetchAdvisories(packageNames, options) {
+    const tasks = packageNames.map((name) => () => queryOsv(name, options.registryTimeoutMs));
+    const results = await asyncPool(options.concurrency, tasks);
+    const advisories = [];
+    for (const r of results) {
+        if (!(r instanceof Error)) {
+            for (const adv of r)
+                advisories.push(adv);
+        }
+    }
+    return advisories;
+}