upgrade-interactive 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# 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.
+
+## Install / run
+
+```sh
+npx upgrade-interactive
+# or, once published/linked:
+npm install -g upgrade-interactive
+nui
+```
+
+Requires Node 18+ and an interactive terminal.
+
+### Using it inside a project (`npm run`)
+
+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:
+
+```json
+"scripts": {
+  "upgrade-interactive": "upgrade-interactive"
+}
+```
+
+Then `npm run upgrade-interactive` works from that project, every time.
+
+## What it does
+
+1. Reads `dependencies` and `devDependencies` from `package.json`.
+2. For each package, looks up two candidate upgrades from the npm registry:
+   - **Range** — the highest version that still satisfies your current
+     semver range (what `npm outdated` calls "Wanted").
+   - **Latest** — the version tagged `latest` on the registry, even if it's
+     outside your current range (a major bump, for example).
+   Both are re-formatted using your existing range modifier (`^`, `~`, or
+   exact), and packages with nothing new to offer are left out of the list
+   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`.
+
+## Controls
+
+| Key                | Action                                              |
+| ------------------ | ---------------------------------------------------- |
+| `↑` / `↓`          | 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 |
+| `Enter`            | Apply the selected upgrades and run `npm install`     |
+| `Ctrl+C` / `Esc`   | Abort — nothing is written                            |
+
+Version numbers are colorized by the size of the bump (yellow-ish for
+minor, red for major), with only the part of the version that actually
+changed highlighted — same idea as yarn's diff highlighting.
+
+## Flags
+
+- `--no-install` — update `package.json` only, skip the `npm install` step
+- `-h, --help`, `-v, --version`
+
+## How closely does this match yarn?
+
+Matched exactly:
+- 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)
+- The `c`/`r`/`l` bulk-select shortcuts, including `l`'s fallback to the
+  Range value when a package has no separate Latest suggestion
+- Packages with no available upgrade never appear in the list
+- The version-diff coloring algorithm (segment-by-segment: modifier → major
+  → minor → patch)
+
+Intentional differences:
+- 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).
+- Only `dependencies`/`devDependencies` are scanned (matches yarn's own
+  scope for this command — it skips `peerDependencies`/`optionalDependencies` too).
+- The list stays alphabetically sorted the whole time it's loading. Yarn's
+  actual implementation fills rows in whatever order each network request
+  finishes, which can make rows jump around while loading — this clone
+  avoids that instead of reproducing it.
+- No monorepo/workspace support (single `package.json` only).
+
+## Project layout
+
+```
+src/
+  cli.js                 entry point, arg parsing, apply + npm install
+  registry.js             npm registry client
+  semver-suggest.js       Current/Range/Latest suggestion + diff coloring
+  package-file.js          package.json read/write
+  components/
+    App.js                 state machine + keybindings
+    Header.js, Prompt.js, Row.js   presentation
+test/
+  app.test.mjs            simulated-keypress smoke tests (ink-testing-library)
+```

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "upgrade-interactive",
+  "version": "1.0.0",
+  "description": "A faithful clone of `yarn upgrade-interactive` (Yarn Berry / Yarn 4) for npm projects.",
+  "type": "module",
+  "bin": {
+    "upgrade-interactive": "./src/cli.js",
+    "nui": "./src/cli.js"
+  },
+  "main": "./src/cli.js",
+  "scripts": {
+    "test": "node test/app.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "npm",
+    "yarn",
+    "upgrade-interactive",
+    "dependencies",
+    "cli",
+    "interactive"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "ink": "^5.2.1",
+    "react": "^18.3.1",
+    "semver": "^7.8.5"
+  },
+  "devDependencies": {
+    "ink-testing-library": "^4.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import React from 'react';
+import { render } from 'ink';
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+import { App } from './components/App.js';
+import { loadManifest, applyUpgrades } from './package-file.js';
+
+const e = React.createElement;
+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.
+
+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
+
+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
+  <enter>         apply the selected upgrades (and run npm install)
+  <ctrl+c> / esc  abort without changing anything
+`;
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('-h') || args.includes('--help')) {
+    process.stdout.write(HELP + '\n');
+    return;
+  }
+
+  if (args.includes('-v') || args.includes('--version')) {
+    const pkgRaw = await readFile(path.join(__dirname, '..', 'package.json'), 'utf8');
+    process.stdout.write(JSON.parse(pkgRaw).version + '\n');
+    return;
+  }
+
+  const skipInstall = args.includes('--no-install');
+
+  if (!process.stdin.isTTY) {
+    process.stderr.write('upgrade-interactive requires an interactive terminal (TTY).\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const cwd = process.cwd();
+  let manifest;
+  try {
+    manifest = await loadManifest(cwd);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = await new Promise((resolve) => {
+    const { waitUntilExit } = render(
+      e(App, {
+        descriptors: manifest.descriptors,
+        onSubmit: (selections) => resolve({ type: 'submit', selections }),
+        onAbort: () => resolve({ type: 'abort' }),
+      }),
+      { exitOnCtrlC: false }
+    );
+    waitUntilExit().catch(() => resolve({ type: 'abort' }));
+  });
+
+  if (result.type === 'abort') {
+    process.stdout.write('\nAborted. No changes were made.\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (result.selections.size === 0) {
+    process.stdout.write('\nNo changes selected.\n');
+    return;
+  }
+
+  const applied = await applyUpgrades(manifest, result.selections);
+
+  process.stdout.write('\n');
+  const byField = { dependencies: [], devDependencies: [] };
+  for (const change of applied) byField[change.field].push(change);
+
+  for (const field of ['dependencies', 'devDependencies']) {
+    if (byField[field].length === 0) continue;
+    process.stdout.write(`${field}\n`);
+    for (const change of byField[field]) {
+      process.stdout.write(`  ${change.name}  ${change.from} \u2192 ${change.to}\n`);
+    }
+  }
+
+  if (skipInstall) {
+    process.stdout.write('\nUpdated package.json. Run npm install to apply.\n');
+    return;
+  }
+
+  process.stdout.write('\nRunning npm install...\n');
+  await runNpmInstall(cwd);
+}
+
+function runNpmInstall(cwd) {
+  return new Promise((resolve) => {
+    const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const child = spawn(npmCmd, ['install'], { cwd, stdio: 'inherit' });
+    child.on('exit', (code) => {
+      process.exitCode = code ?? 0;
+      resolve();
+    });
+    child.on('error', () => {
+      process.stderr.write('Failed to run npm install. Run it manually to finish updating your lockfile.\n');
+      process.exitCode = 1;
+      resolve();
+    });
+  });
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack || err}\n`);
+  process.exitCode = 1;
+});

package/src/components/App.js

@@ -0,0 +1,207 @@
+import React, { useEffect, useRef, useState, useCallback } from 'react';
+import { Box, Text, useInput, useApp } from 'ink';
+import { Prompt } from './Prompt.js';
+import { Header } from './Header.js';
+import { Row, LoadingRow } from './Row.js';
+import { fetchSuggestions } from '../semver-suggest.js';
+import { mapWithConcurrency } from '../registry.js';
+
+const e = React.createElement;
+const CONCURRENCY = 8;
+
+function clamp(n, min, max) {
+  return Math.max(min, Math.min(max, n));
+}
+
+function findNavigable(entries, from, direction) {
+  let i = from;
+  for (let step = 0; step < entries.length; step++) {
+    i += direction;
+    if (i < 0 || i >= entries.length) return from;
+    if (entries[i] && typeof entries[i] === 'object') return i;
+  }
+  return from;
+}
+
+function firstNavigable(entries) {
+  for (let i = 0; i < entries.length; i++) {
+    if (entries[i] && typeof entries[i] === 'object') return i;
+  }
+  return -1;
+}
+
+export function App({ descriptors, onSubmit, onAbort }) {
+  const { exit } = useApp();
+  const [entries, setEntries] = useState(() => descriptors.map(() => null));
+  const [allLoaded, setAllLoaded] = useState(descriptors.length === 0);
+  const [focusedIndex, setFocusedIndex] = useState(-1);
+  const [selectedColumns, setSelectedColumns] = useState({});
+  const mountedRef = useRef(true);
+
+  useEffect(() => {
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  useEffect(() => {
+    if (descriptors.length === 0) return;
+    let cancelled = false;
+
+    mapWithConcurrency(
+      descriptors,
+      CONCURRENCY,
+      async (descriptor) => {
+        const suggestions = await fetchSuggestions(descriptor);
+        return suggestions ? { descriptor, suggestions } : null;
+      },
+      (result, _descriptor, index) => {
+        if (cancelled || !mountedRef.current) return;
+        setEntries((prev) => {
+          const next = [...prev];
+          next[index] = result;
+          return next;
+        });
+      }
+    ).then(() => {
+      if (cancelled || !mountedRef.current) return;
+      setAllLoaded(true);
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [descriptors]);
+
+  // Keep focus pinned to a navigable (loaded, upgradeable) row as things load in.
+  useEffect(() => {
+    if (focusedIndex !== -1 && entries[focusedIndex] && typeof entries[focusedIndex] === 'object') return;
+    const next = firstNavigable(entries);
+    if (next !== focusedIndex) setFocusedIndex(next);
+  }, [entries, focusedIndex]);
+
+  const cycleColumn = useCallback(
+    (direction) => {
+      if (focusedIndex === -1) return;
+      const entry = entries[focusedIndex];
+      if (!entry) return;
+      const name = entry.descriptor.name;
+      const current = selectedColumns[name] ?? 0;
+      let next = current;
+      for (let step = 0; step < entry.suggestions.length; step++) {
+        next = clamp(next + direction, 0, entry.suggestions.length - 1);
+        if (entry.suggestions[next].spans.length > 0 || next === 0) break;
+        if (next === current) break;
+      }
+      setSelectedColumns((prev) => ({ ...prev, [name]: next }));
+    },
+    [focusedIndex, entries, selectedColumns]
+  );
+
+  const bulkSelect = useCallback(
+    (which) => {
+      setSelectedColumns((prev) => {
+        const next = { ...prev };
+        for (const entry of entries) {
+          if (!entry) continue;
+          const { name } = entry.descriptor;
+          if (which === 'c') {
+            next[name] = 0;
+          } else if (which === 'r') {
+            next[name] = 1;
+          } else if (which === 'l') {
+            next[name] = entry.suggestions[2].value != null ? 2 : 1;
+          }
+        }
+        return next;
+      });
+    },
+    [entries]
+  );
+
+  useInput((input, key) => {
+    if (key.ctrl && input === 'c') {
+      onAbort();
+      exit();
+      return;
+    }
+    if (key.escape) {
+      onAbort();
+      exit();
+      return;
+    }
+    if (key.upArrow) {
+      setFocusedIndex((idx) => findNavigable(entries, idx, -1));
+      return;
+    }
+    if (key.downArrow) {
+      setFocusedIndex((idx) => findNavigable(entries, idx, 1));
+      return;
+    }
+    if (key.leftArrow) {
+      cycleColumn(-1);
+      return;
+    }
+    if (key.rightArrow) {
+      cycleColumn(1);
+      return;
+    }
+    if (input === 'c' || input === 'r' || input === 'l') {
+      bulkSelect(input);
+      return;
+    }
+    if (key.return) {
+      const selections = new Map();
+      for (const entry of entries) {
+        if (!entry) continue;
+        const col = selectedColumns[entry.descriptor.name] ?? 0;
+        const value = entry.suggestions[col]?.value ?? null;
+        if (value) selections.set(entry.descriptor.name, value);
+      }
+      onSubmit(selections);
+      exit();
+    }
+  });
+
+  const displayIndices = allLoaded
+    ? entries.map((_, i) => i).filter((i) => entries[i] !== null)
+    : entries.map((_, i) => i);
+
+  if (allLoaded && displayIndices.length === 0) {
+    return e(
+      Box,
+      { flexDirection: 'column' },
+      e(Prompt, null),
+      e(Header, null),
+      e(Text, { dimColor: true }, 'No upgrades found.')
+    );
+  }
+
+  const termRows = (process.stdout && process.stdout.rows) || 24;
+  const maxRows = Math.max(5, termRows - 11);
+  const posInDisplay = Math.max(0, displayIndices.indexOf(focusedIndex));
+  let windowStart = clamp(posInDisplay - Math.floor(maxRows / 2), 0, Math.max(0, displayIndices.length - maxRows));
+  const windowEnd = Math.min(displayIndices.length, windowStart + maxRows);
+  const visible = displayIndices.slice(windowStart, windowEnd);
+
+  return e(
+    Box,
+    { flexDirection: 'column' },
+    e(Prompt, null),
+    e(Header, null),
+    windowStart > 0 ? e(Text, { dimColor: true }, `  \u2191 ${windowStart} more above`) : null,
+    ...visible.map((i) => {
+      const entry = entries[i];
+      if (!entry) return e(LoadingRow, { key: i });
+      const col = selectedColumns[entry.descriptor.name] ?? 0;
+      return e(Row, {
+        key: i,
+        name: entry.descriptor.name,
+        active: i === focusedIndex,
+        suggestions: entry.suggestions,
+        selectedColumn: col,
+      });
+    }),
+    windowEnd < displayIndices.length ? e(Text, { dimColor: true }, `  \u2193 ${displayIndices.length - windowEnd} more below`) : null
+  );
+}

package/src/components/Header.js

@@ -0,0 +1,19 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+
+const e = React.createElement;
+
+export function Header() {
+  return e(
+    Box,
+    { flexDirection: 'row', paddingTop: 1, paddingBottom: 1 },
+    e(
+      Box,
+      { width: 50 },
+      e(Text, { bold: true }, e(Text, { color: 'greenBright' }, '?'), ' Pick the packages you want to upgrade.')
+    ),
+    e(Box, { width: 17 }, e(Text, { bold: true, underline: true, color: 'gray' }, 'Current')),
+    e(Box, { width: 17 }, e(Text, { bold: true, underline: true, color: 'gray' }, 'Range')),
+    e(Box, { width: 17 }, e(Text, { bold: true, underline: true, color: 'gray' }, 'Latest'))
+  );
+}

package/src/components/Prompt.js

@@ -0,0 +1,56 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+
+const e = React.createElement;
+
+function Key({ children }) {
+  return e(Text, { bold: true, color: 'cyanBright' }, children);
+}
+
+export function Prompt() {
+  return e(
+    Box,
+    { flexDirection: 'row' },
+    e(
+      Box,
+      { flexDirection: 'column', width: 49 },
+      e(
+        Box,
+        { marginLeft: 1 },
+        e(Text, null, 'Press ', e(Key, null, '<up>'), '/', e(Key, null, '<down>'), ' to select packages.')
+      ),
+      e(
+        Box,
+        { marginLeft: 1 },
+        e(Text, null, 'Press ', e(Key, null, '<left>'), '/', e(Key, null, '<right>'), ' to select versions.')
+      ),
+      e(
+        Box,
+        { marginLeft: 1 },
+        e(
+          Text,
+          null,
+          'Press ',
+          e(Key, null, 'c'),
+          '/',
+          e(Key, null, 'r'),
+          '/',
+          e(Key, null, 'l'),
+          ' to select all ',
+          e(Key, null, 'current'),
+          '/',
+          e(Key, null, 'range'),
+          '/',
+          e(Key, null, 'latest'),
+          '.'
+        )
+      )
+    ),
+    e(
+      Box,
+      { flexDirection: 'column' },
+      e(Box, { marginLeft: 1 }, e(Text, null, 'Press ', e(Key, null, '<enter>'), ' to install.')),
+      e(Box, { marginLeft: 1 }, e(Text, null, 'Press ', e(Key, null, '<ctrl+c>'), ' to abort.'))
+    )
+  );
+}

package/src/components/Row.js

@@ -0,0 +1,51 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+
+const e = React.createElement;
+
+function Spans({ spans, inverse }) {
+  if (!spans || spans.length === 0) return e(Text, null, '');
+  return e(
+    Text,
+    { inverse },
+    ...spans.map((span, i) => e(Text, { key: i, color: span.color || undefined }, span.text))
+  );
+}
+
+function Column({ suggestion, selected }) {
+  const hasContent = suggestion && suggestion.spans.length > 0;
+  return e(
+    Box,
+    { width: 17 },
+    hasContent
+      ? e(Text, null, selected ? '\u25CF ' : '\u25CB ', e(Spans, { spans: suggestion.spans, inverse: selected }))
+      : e(Text, { dimColor: true }, selected ? '\u25CF' : '')
+  );
+}
+
+export function Row({ name, active, suggestions, selectedColumn }) {
+  const padLength = Math.max(1, 45 - name.length);
+  return e(
+    Box,
+    { flexDirection: 'row' },
+    e(Box, { width: 2 }, e(Text, { color: 'cyanBright', bold: true }, active ? '\u276F ' : '  ')),
+    e(
+      Box,
+      { width: 45 },
+      e(Text, { bold: true }, name),
+      e(Text, null, ' '.repeat(padLength))
+    ),
+    e(Column, { suggestion: suggestions[0], selected: selectedColumn === 0 }),
+    e(Column, { suggestion: suggestions[1], selected: selectedColumn === 1 }),
+    e(Column, { suggestion: suggestions[2], selected: selectedColumn === 2 })
+  );
+}
+
+export function LoadingRow() {
+  return e(
+    Box,
+    { flexDirection: 'row' },
+    e(Box, { width: 2 }),
+    e(Box, { width: 45 }, e(Text, { dimColor: true }, 'Loading...'))
+  );
+}

package/src/package-file.js

@@ -0,0 +1,61 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies'];
+
+export async function loadManifest(cwd) {
+  const filePath = path.join(cwd, 'package.json');
+  let raw;
+  try {
+    raw = await readFile(filePath, 'utf8');
+  } catch {
+    throw new Error(`No package.json found in ${cwd}`);
+  }
+
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Could not parse package.json: ${err.message}`);
+  }
+
+  const indentMatch = raw.match(/^[ \t]+/m);
+  const indent = indentMatch ? indentMatch[0] : '  ';
+  const trailingNewline = raw.endsWith('\n');
+
+  const descriptors = [];
+  for (const field of DEPENDENCY_FIELDS) {
+    const section = json[field];
+    if (!section || typeof section !== 'object') continue;
+    for (const [name, range] of Object.entries(section)) {
+      descriptors.push({ name, range, field });
+    }
+  }
+
+  descriptors.sort((a, b) => a.name.localeCompare(b.name));
+
+  return { filePath, json, raw, indent, trailingNewline, descriptors };
+}
+
+/**
+ * Apply a Map<name, newRange> of accepted upgrades to the manifest and
+ * write it back to disk. Returns the list of { name, field, from, to } applied.
+ */
+export async function applyUpgrades(manifest, selections) {
+  const applied = [];
+
+  for (const descriptor of manifest.descriptors) {
+    const newRange = selections.get(descriptor.name);
+    if (!newRange || newRange === descriptor.range) continue;
+
+    manifest.json[descriptor.field][descriptor.name] = newRange;
+    applied.push({ name: descriptor.name, field: descriptor.field, from: descriptor.range, to: newRange });
+  }
+
+  if (applied.length === 0) return applied;
+
+  const serialized = JSON.stringify(manifest.json, null, manifest.indent) + (manifest.trailingNewline ? '\n' : '');
+  await writeFile(manifest.filePath, serialized, 'utf8');
+
+  return applied;
+}

package/src/registry.js

@@ -0,0 +1,62 @@
+// Minimal npm registry client.
+// Uses the "abbreviated" metadata format (much smaller / faster than full docs).
+
+const REGISTRY = 'https://registry.npmjs.org';
+const cache = new Map();
+
+function encodePackageName(name) {
+  // Scoped packages (@scope/name) keep the slash un-encoded for the
+  // registry.npmjs.org convention, everything else is encoded normally.
+  if (name.startsWith('@')) {
+    const [scope, pkg] = name.split('/');
+    return `${encodeURIComponent(scope)}/${encodeURIComponent(pkg)}`;
+  }
+  return encodeURIComponent(name);
+}
+
+/**
+ * Fetch { versions: string[], distTags: Record<string,string> } for a package.
+ * Returns null if the package can't be resolved (404, network error, etc).
+ */
+export async function fetchPackageMeta(name) {
+  if (cache.has(name)) return cache.get(name);
+
+  const promise = (async () => {
+    try {
+      const res = await fetch(`${REGISTRY}/${encodePackageName(name)}`, {
+        headers: {
+          Accept: 'application/vnd.npm.install-v1+json, application/json',
+          'User-Agent': 'upgrade-interactive',
+        },
+      });
+      if (!res.ok) return null;
+      const json = await res.json();
+      const versions = Object.keys(json.versions || {});
+      const distTags = json['dist-tags'] || {};
+      if (versions.length === 0) return null;
+      return { versions, distTags };
+    } catch {
+      return null;
+    }
+  })();
+
+  cache.set(name, promise);
+  return promise;
+}
+
+/**
+ * Run `worker` over `items` with at most `limit` in flight at once.
+ * Calls `onEach(result, item, index)` as each one resolves (out of order).
+ */
+export async function mapWithConcurrency(items, limit, worker, onEach) {
+  let cursor = 0;
+  const runners = new Array(Math.min(limit, items.length)).fill(null).map(async () => {
+    while (cursor < items.length) {
+      const index = cursor++;
+      const item = items[index];
+      const result = await worker(item, index);
+      if (onEach) onEach(result, item, index);
+    }
+  });
+  await Promise.all(runners);
+}

package/src/semver-suggest.js

@@ -0,0 +1,128 @@
+import semver from 'semver';
+import { fetchPackageMeta } from './registry.js';
+
+// Same regex yarn uses to split a "simple" semver range into
+// [modifier, major, .minor, .patch, -prerelease] groups.
+const SIMPLE_SEMVER = /^((?:[\^~]|>=?)?)([0-9]+)(\.[0-9]+)(\.[0-9]+)((?:-\S+)?)$/;
+
+// Ranges we can't safely resolve against the registry (git/file/link/workspace
+// protocols, npm aliases, complex boolean ranges, dist-tags other than a bare
+// tag name, etc). Yarn handles these through pluggable resolvers; we just skip them.
+function isSimpleRange(range) {
+  if (!range) return false;
+  if (/^(git|github|gitlab|bitbucket|file|link|workspace|http|https|npm):/.test(range)) return false;
+  // Reject compound ranges ("1.x || 2.x", "1.0.0 - 2.0.0", etc) and anything
+  // with internal whitespace; those aren't resolvable by our simple scheme.
+  if (/\s/.test(range)) return false;
+  return true;
+}
+
+function getModifier(range) {
+  const match = range.match(SIMPLE_SEMVER);
+  if (match) return match[1];
+  if (range.startsWith('^')) return '^';
+  if (range.startsWith('~')) return '~';
+  return '';
+}
+
+/** Re-apply the original range's modifier (^, ~, or exact) to a resolved version. */
+function applyModifier(modifier, version) {
+  return `${modifier}${version}`;
+}
+
+/**
+ * Resolve the highest published version matching `targetRange` (a semver
+ * range OR a dist-tag name like "latest"), then re-format it using the
+ * original descriptor's modifier style. Mirrors yarn's fetchUpdatedDescriptor.
+ */
+function resolveAgainstMeta(meta, originalRange, targetRange) {
+  const modifier = getModifier(originalRange);
+
+  if (Object.prototype.hasOwnProperty.call(meta.distTags, targetRange)) {
+    const version = meta.distTags[targetRange];
+    if (!version) return null;
+    return applyModifier(modifier, version);
+  }
+
+  const best = semver.maxSatisfying(meta.versions, targetRange, { includePrerelease: false });
+  if (!best) return null;
+  return applyModifier(modifier, best);
+}
+
+/**
+ * Colorize the part of `to` that differs from `from`, segment by segment
+ * (modifier / major / minor / patch / prerelease), exactly like yarn's
+ * colorizeVersionDiff. Returns an array of { text, color } spans ready to
+ * be rendered as a sequence of <Text color=...> chunks.
+ */
+export function colorizeVersionDiff(from, to) {
+  if (from === to) return [{ text: to, color: null }];
+
+  const matchedFrom = from.match(SIMPLE_SEMVER);
+  const matchedTo = to.match(SIMPLE_SEMVER);
+  if (!matchedFrom || !matchedTo) return [{ text: to, color: null }];
+
+  const SEMVER_COLORS = ['gray', 'red', 'yellow', 'green', 'magenta'];
+  let color = null;
+  const spans = [];
+
+  for (let t = 1; t < matchedTo.length; ++t) {
+    const differs = matchedFrom[t] !== matchedTo[t];
+    if (color !== null || differs) {
+      if (color === null) color = SEMVER_COLORS[Math.min(t - 1, SEMVER_COLORS.length - 1)];
+      spans.push({ text: matchedTo[t], color });
+    } else {
+      spans.push({ text: matchedTo[t], color: null });
+    }
+  }
+
+  return spans;
+}
+
+/**
+ * Compute the { label: 'current'|'range'|'latest', value, spans }[] suggestion
+ * set for a single descriptor, or null if there's nothing to upgrade to
+ * (mirrors yarn: a package with no viable Range/Latest suggestion is
+ * dropped from the list entirely).
+ */
+export async function fetchSuggestions(descriptor) {
+  const { name, range } = descriptor;
+  if (!isSimpleRange(range)) return null;
+
+  const meta = await fetchPackageMeta(name);
+  if (!meta) return null;
+
+  const referenceRange = semver.valid(range) ? `^${range}` : range;
+
+  let rangeResolution = null;
+  let latestResolution = null;
+  try {
+    rangeResolution = resolveAgainstMeta(meta, range, referenceRange);
+  } catch {
+    rangeResolution = null;
+  }
+  try {
+    latestResolution = resolveAgainstMeta(meta, range, 'latest');
+  } catch {
+    latestResolution = null;
+  }
+
+  const suggestions = [
+    { key: 'current', value: null, spans: [{ text: range, color: null }] },
+    { key: 'range', value: null, spans: [] },
+    { key: 'latest', value: null, spans: [] },
+  ];
+
+  if (rangeResolution && rangeResolution !== range) {
+    suggestions[1] = { key: 'range', value: rangeResolution, spans: colorizeVersionDiff(range, rangeResolution) };
+  }
+
+  if (latestResolution && latestResolution !== rangeResolution && latestResolution !== range) {
+    suggestions[2] = { key: 'latest', value: latestResolution, spans: colorizeVersionDiff(range, latestResolution) };
+  }
+
+  const usableCount = suggestions.filter((s) => s.spans.length > 0).length;
+  if (usableCount <= 1) return null;
+
+  return suggestions;
+}