upgrade-interactive 1.0.0 → 1.1.0

package/README.md

@@ -1,9 +1,12 @@
 # upgrade-interactive
 
-A clone of `yarn upgrade-interactive` (the Yarn Berry / Yarn 4 version, built into
-Yarn since v4) for npm projects. It was built by reading Yarn's actual source
-(`@yarnpkg/plugin-interactive-tools`) rather than guessing at the UI, so the
-keybindings, columns, and version-suggestion logic mirror it closely.
+An interactive dependency upgrader for npm projects, **inspired by** `yarn
+upgrade-interactive` (the Yarn Berry / Yarn 4 version, built into Yarn since v4).
+The three-column layout, keybindings, and version-suggestion logic follow yarn's
+closely — they were built by reading Yarn's actual source
+(`@yarnpkg/plugin-interactive-tools`) — but this tool also adds things yarn
+doesn't have, notably built-in **vulnerability warnings** and one-key npm
+**`overrides`**, so it deliberately diverges where that improves the experience.
 
 ## Install / run
 
@@ -16,11 +19,20 @@ nui
 
 Requires Node 18+ and an interactive terminal.
 
-### Using it inside a project (`npm run`)
+### Using it inside a project
 
-npm has no plugin system for adding real subcommands the way yarn does, so
-`npm upgrade-interactive` (no `run`) isn't possible. The closest equivalent,
-and the standard way to wire up any custom npm command, is a script entry:
+Because this package ships a `bin`, you don't need `npm run` — or any
+`package.json` change — to use it in a project. Install it and call it with npx:
+
+```sh
+npm install -D upgrade-interactive
+npx upgrade-interactive     # runs the locally-installed copy (npx prefers node_modules/.bin)
+npx nui                      # same thing, short name
+```
+
+npm has no plugin/subcommand system the way Yarn Berry does, so the literal
+`npm upgrade-interactive` isn't possible — but `npx upgrade-interactive` is the
+native, no-`run` equivalent. If you'd still rather have a named script, add:
 
 ```json
 "scripts": {
@@ -28,7 +40,7 @@ and the standard way to wire up any custom npm command, is a script entry:
 }
 ```
 
-Then `npm run upgrade-interactive` works from that project, every time.
+and run `npm run upgrade-interactive`.
 
 ## What it does
 
@@ -43,7 +55,26 @@ Then `npm run upgrade-interactive` works from that project, every time.
    entirely — same as yarn.
 3. Lets you pick, per package, whether to stay on **Current**, take the
    **Range** upgrade, or take the **Latest** upgrade.
-4. Writes your choices back into `package.json` and runs `npm install`.
+4. **Checks for known vulnerabilities** (on by default) against npm's advisory
+   database, covering both your **direct and transitive** dependencies. A
+   flagged row shows a ⚠ icon, the severity (`low` / `moderate` / `high` /
+   `critical`), and the CVE id as a clickable link to the advisory — with the
+   plain URL printed alongside it when your terminal can't render clickable
+   links. The affected range and first fixed version are shown inline.
+5. Lets you press `o` on a vulnerable package to **pin it to a safe version via
+   an npm `overrides` entry** — the main way to patch a *transitive* dependency
+   you don't directly control.
+6. **Flags existing `overrides` that are no longer needed** — either because
+   nothing in the tree depends on that package anymore, or because your deps
+   would now resolve to a non-vulnerable version without the pin. Press `x` to
+   remove one. (It never removes an override that's still doing something, and
+   only ever removes one you explicitly select.)
+7. Writes your choices (overrides added and removed) back into `package.json`
+   and runs `npm install`.
+
+By default the list is grouped into **Dependencies**, **Dev dependencies**, and
+**Overrides** (transitive packages you've flagged for an override) sections. Pass
+`--no-section` for a single flat list.
 
 ## Controls
 
@@ -52,6 +83,8 @@ Then `npm run upgrade-interactive` works from that project, every time.
 | `↑` / `↓`          | Move between packages                                |
 | `←` / `→`          | Move between Current / Range / Latest for that package |
 | `c` / `r` / `l`     | Select **c**urrent / **r**ange / **l**atest for *every* package at once |
+| `o`                | Override the focused vulnerable package to a safe version (audit mode) |
+| `x`                | Remove the focused override when it's no longer needed (audit mode) |
 | `Enter`            | Apply the selected upgrades and run `npm install`     |
 | `Ctrl+C` / `Esc`   | Abort — nothing is written                            |
 
@@ -62,11 +95,34 @@ changed highlighted — same idea as yarn's diff highlighting.
 ## Flags
 
 - `--no-install` — update `package.json` only, skip the `npm install` step
+- `--audit` / `--no-audit` — enable/disable the vulnerability check (default: on)
+- `--section` / `--no-section` — grouped sections vs a flat list (default: on)
 - `-h, --help`, `-v, --version`
 
+### Persisting audit / section preferences
+
+Audit and sectioning are both on by default. To change the default permanently,
+set an environment variable or a `package.json` config block:
+
+```json
+"upgrade-interactive": { "audit": false, "section": true }
+```
+
+```sh
+NUI_AUDIT=0 npx upgrade-interactive     # disable auditing for this run
+```
+
+Precedence, highest first: command-line flag → `NUI_AUDIT` / `NUI_SECTION`
+environment variable → `package.json` config → default (on).
+
+> Vulnerability data comes from npm's advisory endpoint, so auditing needs
+> network access. When it can't reach the network the tool says so
+> (`no network — couldn't check for vulnerable packages`) rather than pretending
+> everything is clean, and the upgrade flow works as normal.
+
 ## How closely does this match yarn?
 
-Matched exactly:
+Follows yarn closely:
 - The three-column Current/Range/Latest layout and the help text wording
 - The up/down/left/right navigation model (selection = which column is
   highlighted per row, not a separate checkbox)
@@ -76,7 +132,14 @@ Matched exactly:
 - The version-diff coloring algorithm (segment-by-segment: modifier → major
   → minor → patch)
 
-Intentional differences:
+Deliberate additions / differences (this is *inspired by* yarn, not a clone):
+- **Vulnerability warnings + `overrides`** — flags vulnerable direct and
+  transitive packages, lets you pin a safe version via npm `overrides`, and
+  flags existing overrides that are no longer needed so you can remove them.
+  Yarn's command has no equivalent.
+- **Sectioned layout** — the list is grouped into Dependencies / Dev
+  dependencies / Overrides by default (yarn shows one flat list; use
+  `--no-section` to match that).
 - Only plain semver ranges are resolved (git/file/link/workspace ranges,
   and compound ranges like `>=1.0.0 <2.0.0`, are skipped — yarn handles
   these through its pluggable resolvers, which is out of scope here).
@@ -92,12 +155,16 @@ Intentional differences:
 
 ```
 src/
-  cli.js                 entry point, arg parsing, apply + npm install
-  registry.js             npm registry client
+  cli.js                 entry point, arg/flag parsing, apply + npm install
+  registry.js             npm registry client + bulk advisory lookup
   semver-suggest.js       Current/Range/Latest suggestion + diff coloring
-  package-file.js          package.json read/write
+  package-file.js          package.json read/write (+ overrides)
+  lockfile.js             installed versions from package-lock.json
+  vulnerabilities.js      advisory orchestration + severity/safe-version logic
+  links.js                OSC 8 terminal hyperlinks (with fallback)
   components/
     App.js                 state machine + keybindings
+    OverridePicker.js      safe-version chooser overlay
     Header.js, Prompt.js, Row.js   presentation
 test/
   app.test.mjs            simulated-keypress smoke tests (ink-testing-library)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "upgrade-interactive",
-  "version": "1.0.0",
-  "description": "A faithful clone of `yarn upgrade-interactive` (Yarn Berry / Yarn 4) for npm projects.",
+  "version": "1.1.0",
+  "description": "An interactive dependency upgrader for npm projects, inspired by `yarn upgrade-interactive` (Yarn Berry / Yarn 4), with built-in vulnerability warnings.",
   "type": "module",
   "bin": {
     "upgrade-interactive": "./src/cli.js",
@@ -9,7 +9,9 @@
   },
   "main": "./src/cli.js",
   "scripts": {
-    "test": "node test/app.test.mjs"
+    "test": "node --test \"test/unit/**/*.test.mjs\"",
+    "test:integration": "node test/app.test.mjs",
+    "test:all": "npm run test && npm run test:integration"
   },
   "engines": {
     "node": ">=18"

package/src/cli.js

@@ -15,24 +15,50 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const HELP = `
 upgrade-interactive (nui)
 
-A faithful clone of "yarn upgrade-interactive" (Yarn Berry / Yarn 4) for npm projects.
+An interactive dependency upgrader for npm projects, inspired by yarn's
+"upgrade-interactive" (Yarn Berry / Yarn 4).
 
 Usage
   $ npx upgrade-interactive [options]
 
 Options
-  --no-install   Update package.json only, skip running "npm install" afterwards
-  -h, --help     Show this help message
-  -v, --version  Show the version number
+  --no-install    Update package.json only, skip running "npm install" afterwards
+  --audit         Flag vulnerable packages (default: on)
+  --no-audit      Skip the vulnerability check (no advisory network calls)
+  --section       Group the list into Dependencies / Dev dependencies / Overrides (default: on)
+  --no-section    Show one flat list instead
+  -h, --help      Show this help message
+  -v, --version   Show the version number
+
+Audit and sectioning are on by default. Persist a preference either way with the
+NUI_AUDIT / NUI_SECTION environment variables, or a package.json config block:
+
+  "upgrade-interactive": { "audit": false, "section": true }
+
+Precedence: command-line flag > environment variable > package.json config > default (on).
 
 Controls (inside the interactive UI)
   <up>/<down>     select a package
   <left>/<right>  select which version to apply (Current / Range / Latest)
   c / r / l       select all packages' Current / Range / Latest column at once
+  o               override a vulnerable package to a safe version (audit mode)
+  x               remove an existing override that's no longer needed (audit mode)
   <enter>         apply the selected upgrades (and run npm install)
   <ctrl+c> / esc  abort without changing anything
 `;
 
+// Resolve a boolean toggle from flags > env var > package.json config > default(true).
+function resolveToggle({ args, env, config, onFlag, offFlag, envVar, configKey }) {
+  if (args.includes(offFlag)) return false;
+  if (args.includes(onFlag)) return true;
+  const envVal = env[envVar];
+  if (envVal != null && envVal !== '') {
+    return !/^(0|false|no|off)$/i.test(envVal.trim());
+  }
+  if (config && typeof config[configKey] === 'boolean') return config[configKey];
+  return true;
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
@@ -65,11 +91,23 @@ async function main() {
     return;
   }
 
+  const config = manifest.json['upgrade-interactive'];
+  const audit = resolveToggle({
+    args, env: process.env, config, onFlag: '--audit', offFlag: '--no-audit', envVar: 'NUI_AUDIT', configKey: 'audit',
+  });
+  const section = resolveToggle({
+    args, env: process.env, config, onFlag: '--section', offFlag: '--no-section', envVar: 'NUI_SECTION', configKey: 'section',
+  });
+
   const result = await new Promise((resolve) => {
     const { waitUntilExit } = render(
       e(App, {
         descriptors: manifest.descriptors,
-        onSubmit: (selections) => resolve({ type: 'submit', selections }),
+        audit,
+        section,
+        cwd,
+        overrides: manifest.json.overrides || {},
+        onSubmit: (selections, overrides, removals) => resolve({ type: 'submit', selections, overrides, removals }),
         onAbort: () => resolve({ type: 'abort' }),
       }),
       { exitOnCtrlC: false }
@@ -83,12 +121,23 @@ async function main() {
     return;
   }
 
-  if (result.selections.size === 0) {
+  const overrideSelections = result.overrides || {};
+  const overrideRemovals = result.removals || [];
+  if (
+    result.selections.size === 0 &&
+    Object.keys(overrideSelections).length === 0 &&
+    overrideRemovals.length === 0
+  ) {
     process.stdout.write('\nNo changes selected.\n');
     return;
   }
 
-  const applied = await applyUpgrades(manifest, result.selections);
+  const { applied, overrides, removed } = await applyUpgrades(
+    manifest,
+    result.selections,
+    overrideSelections,
+    overrideRemovals
+  );
 
   process.stdout.write('\n');
   const byField = { dependencies: [], devDependencies: [] };
@@ -102,6 +151,21 @@ async function main() {
     }
   }
 
+  if (overrides.length > 0 || removed.length > 0) {
+    process.stdout.write('overrides\n');
+    for (const change of overrides) {
+      process.stdout.write(`  ${change.name}  \u2192 ${change.to}\n`);
+    }
+    for (const change of removed) {
+      process.stdout.write(`  ${change.name}  removed\n`);
+    }
+  }
+
+  if (applied.length === 0 && overrides.length === 0 && removed.length === 0) {
+    process.stdout.write('No effective changes.\n');
+    return;
+  }
+
   if (skipInstall) {
     process.stdout.write('\nUpdated package.json. Run npm install to apply.\n');
     return;