@vzn/vx 0.0.635 → 0.0.637

package/src/cli/upgrade.ts

@@ -1,25 +1,45 @@
-// `vx upgrade [TAG]` — self-update the compiled binary in place.
-// Asks the GitHub release API for the asset of this os/arch and the
-// SHA-256 digest it publishes, downloads the asset, verifies the digest,
-// writes next to the current executable, atomic rename over it. The
-// digest is what makes a cut or corrupted transfer (a proxy that drops a
-// connection, a disk that fills) a refusal instead of a binary that does
-// not start: the rename is the last step, and a mismatch replaces
-// nothing. It guards the TRANSFER only: the digest comes from the same
-// release API as the download URL, and GitHub recomputes it when an asset
-// is uploaded, so whoever can replace the asset replaces its digest too
-// (item 1096). Nothing here verifies who built the binary.
+// `vx upgrade [TAG]` — bring this vx to a newer release, the way it was
+// installed. A compiled binary installed by hand replaces itself: it reads
+// its platform package (`@vzn/vx-<os>-<arch>`) from the npm registry,
+// checks npm's registry signature over `name@version:integrity` against
+// the key pinned below, checks the tarball's SHA-512 against that signed
+// integrity, and only then extracts the binary, stages it beside the old
+// one and renames it over. The signature is what proves the bytes are the
+// ones npm published: the host that serves the tarball cannot mint it
+// (pnpm's installer, pnpm/get, checks the same). A vx installed by a
+// package manager (npm, pnpm, bun, yarn; global or a project's
+// dependency) is upgraded by that package manager, never by a rename over
+// a file it owns. vx never installs Node or a package manager.
 // Named `upgrade` (not `update`) per CLI convention: bun upgrade,
 // deno upgrade — "update" is what package managers do to indexes.
 
-import { constants } from 'node:fs'
+import { constants, existsSync, readFileSync } from 'node:fs'
+import { createPublicKey, verify } from 'node:crypto'
 import { access, chmod, chown, link, mkdtemp, rename, rm, stat } from 'node:fs/promises'
 import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
 import { UserError } from '../util/index.js'
 import { VERSION } from '../version.js'
 
-const REPO = 'vznjs/vx'
+const REGISTRY = 'https://registry.npmjs.org'
+const PACKAGE = '@vzn/vx'
+
+/**
+ * npm's registry signing key, from https://registry.npmjs.org/-/npm/v1/keys.
+ * Pinned, not fetched: a key read from the registry would prove nothing
+ * about the registry's own answers. When npm rotates it, a release of vx
+ * carries the new one, and an older vx refuses with that hint.
+ */
+export const NPM_SIGNING_KEY = {
+  id: 'SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U',
+  spki: 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY6Ya7W++7aUPzvMTrezH6Ycx3c+HOKYCcNGybJZSCJq/fd7Qa8uuAKtdIkUQtQiEKERhAmE5lMMJhP8OkDOa2g==',
+}
+
+/** A registry key: its id as npm names it, and its SPKI DER, base64. */
+export interface SigningKey {
+  id: string
+  spki: string
+}
 
 /**
  * A Bun standalone-binary path lives under the bunfs virtual root.
@@ -45,14 +65,15 @@ export function isCompiledBinary(): boolean {
 }
 
 /**
+ * The package dir/**
  * The package directory that owns `execPath` when it sits under a
  * `node_modules` — an npm install's platform binary, which the launcher
  * runs as `…/node_modules/@vzn/vx-<os>-<arch>/vx`. That file is npm's:
  * a rename over it upgrades this command until the next `npm install`
  * (or a lockfile-pinned CI checkout) puts the version npm knows back,
  * and `npm ls` never agrees with `vx --version` in between. Such an
- * install updates through npm, and `vx upgrade` says so. Null for a
- * binary installed by hand from a release.
+ * install updates through its package manager (`managedInstall`). Null
+ * for a binary installed by hand from a release.
  */
 export function npmOwnedBinary(execPath: string): string | null {
   const parts = execPath.split(/[\\/]/)
@@ -63,76 +84,23 @@ export function npmOwnedBinary(execPath: string): string | null {
   return pkg.length > 0 ? pkg : 'node_modules'
 }
 
-function assetName(): string {
-  const os = process.platform === 'darwin' ? 'darwin' : process.platform
+function platformPackage(): string {
+  const os = process.platform
   const arch = process.arch === 'x64' || process.arch === 'arm64' ? process.arch : null
   if ((os !== 'darwin' && os !== 'linux') || arch === null) {
     throw new UserError(`vx upgrade: unsupported platform ${process.platform}/${process.arch}`)
   }
-  return `vx-${os}-${arch}`
-}
-
-/** What the release API says about the asset this platform installs. */
-export interface ReleaseAsset {
-  /** The release's tag, as the API names it (`v0.4.0`). */
-  tag: string
-  url: string
-  /** Lower-case hex SHA-256 of the asset's bytes. */
-  sha256: string
+  return `${PACKAGE}-${os}-${arch}`
 }
 
-/**
- * Pick this platform's asset out of a release document and read the
- * digest the API publishes for it (`sha256:<hex>` on every asset a
- * release built through `release.yml` carries). A release without the
- * asset, or an asset without a digest, is refused here: an upgrade that
- * cannot be verified is not attempted.
- */
-export function releaseAsset(release: unknown, name: string): ReleaseAsset {
-  const tag =
-    typeof release === 'object' &&
-    release !== null &&
-    typeof (release as { tag_name?: unknown }).tag_name === 'string'
-      ? (release as { tag_name: string }).tag_name
-      : '(unknown)'
-  const assets =
-    typeof release === 'object' &&
-    release !== null &&
-    Array.isArray((release as { assets?: unknown }).assets)
-      ? (release as { assets: unknown[] }).assets
-      : []
-  const asset = assets.find(
-    (a): a is { name: string; browser_download_url?: unknown; digest?: unknown } =>
-      typeof a === 'object' && a !== null && (a as { name?: unknown }).name === name,
-  )
-  if (asset === undefined) {
-    throw new UserError(
-      `vx upgrade: release ${tag} has no asset ${name} for this platform — nothing replaced; npm install -g @vzn/vx@latest installs it instead`,
-    )
-  }
-  const url = asset.browser_download_url
-  if (typeof url !== 'string' || url.length === 0) {
-    throw new UserError(
-      `vx upgrade: release ${tag} names no download for ${name} — nothing replaced; npm install -g @vzn/vx@latest installs it instead`,
-    )
-  }
-  const digest = asset.digest
-  const m = typeof digest === 'string' ? /^sha256:([0-9a-f]{64})$/i.exec(digest) : null
-  if (m === null) {
-    throw new UserError(
-      `vx upgrade: release ${tag} publishes no SHA-256 digest for ${name} — nothing to verify the download against, so it is not attempted`,
-    )
+/** The registry spec for `TAG`: `v0.4.0` and `0.4.0` name a version; none is `latest`. */
+export function versionSpec(tag: string | undefined): string {
+  if (tag === undefined) return 'latest'
+  const v = tag.startsWith('v') ? tag.slice(1) : tag
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(v)) {
+    throw new UserError(`vx upgrade: ${tag} is not a version (expected v<major>.<minor>.<patch>)`)
   }
-  return { tag, url, sha256: m[1]!.toLowerCase() }
-}
-
-/**
- * Whether a release tag names the version this binary is: the upgrade
- * re-downloaded and replaced a binary with itself, printing `X → latest`
- * (item 1098). Tags are `v<version>`; a bare version is accepted too.
- */
-export function isThisVersion(tag: string, version: string): boolean {
-  return tag === `v${version}` || tag === version
+  return v
 }
 
 /**
@@ -171,31 +139,17 @@ async function readOrRefuse<T>(read: () => Promise<T>, url: string, what: string
   }
 }
 
-/** The release document for `latest` or a tag, from the GitHub API. */
-export async function fetchRelease(tag: string | undefined): Promise<unknown> {
-  const url =
-    tag === undefined
-      ? `https://api.github.com/repos/${REPO}/releases/latest`
-      : `https://api.github.com/repos/${REPO}/releases/tags/${encodeURIComponent(tag)}`
+/** The registry's document for `pkg@spec` (`latest` or a version). */
+export async function fetchManifest(pkg: string, spec: string): Promise<unknown> {
+  const url = `${REGISTRY}/${pkg}/${spec}`
   const res = await fetchOrRefuse(
     url,
-    {
-      redirect: 'follow',
-      headers: { Accept: 'application/vnd.github+json', 'User-Agent': `vx/${VERSION}` },
-    },
+    { redirect: 'follow', headers: { Accept: 'application/json', 'User-Agent': `vx/${VERSION}` } },
     'read the release',
   )
   if (!res.ok) {
-    // GitHub answers an unauthenticated address past its hourly budget with
-    // 403 (or 429) and says so in the headers; "could not read the release
-    // (403)" read as a permissions fault (item 1098).
-    const reset = Number(res.headers.get('x-ratelimit-reset'))
-    const limited =
-      (res.status === 403 || res.status === 429) && res.headers.get('x-ratelimit-remaining') === '0'
     throw new UserError(
-      limited
-        ? `vx upgrade: GitHub's API rate limit for this address is spent${Number.isFinite(reset) && reset > 0 ? ` until ${new Date(reset * 1000).toISOString()}` : ''} — re-run after that`
-        : `vx upgrade: could not read the release (${res.status}) — ${url}${res.status === 404 && tag !== undefined ? ` (is ${tag} a release tag?)` : ''}`,
+      `vx upgrade: could not read ${pkg}@${spec} from the npm registry (${res.status})${res.status === 404 && spec !== 'latest' ? ` — is ${spec} a published version?` : ''}`,
     )
   }
   // A body that is not JSON (a captive portal's page, a proxy's error
@@ -203,49 +157,184 @@ export async function fetchRelease(tag: string | undefined): Promise<unknown> {
   return await readOrRefuse(() => res.json(), url, 'read the release')
 }
 
+/** What a verified registry document names: the version, its tarball and the signed integrity. */
+export interface SignedRelease {
+  version: string
+  tarball: string
+  integrity: string
+}
+
 /**
- * Download `url`, verify its SHA-256 against `sha256`, and atomically
- * replace `dest` with it, keeping `dest`'s mode (and, as root, its owner):
- * a 0750 install came back 0755 and owned by whoever upgraded (item 1097).
- * `starts`, when given, is asked of the replaced binary; false puts the old
- * one back, since the digest proves the bytes, not that this machine can
- * run them (a CPU below the build's target, a `noexec` mount), and the
- * upgrade reported success over a vx that no longer started. Exported for
- * tests (which stub `fetch` and point `dest` at a tmp file); the CLI wires
- * it to the release asset and process.execPath.
+ * The tarball and integrity of `pkg` in `manifest`, once npm's registry
+ * signature over `pkg@version:integrity` verifies against `key`. Every
+ * refusal comes before a byte of the tarball is fetched. The message is
+ * built from the package vx asked for, so a signature npm made for
+ * another package does not verify here.
  */
-export async function replaceBinary(
-  dest: string,
-  url: string,
-  sha256: string,
-  starts?: (dest: string) => boolean,
-): Promise<void> {
-  // The swap writes beside the binary: a directory this user cannot write
-  // (a root-owned /usr/local/bin) failed at the rename, the whole release
-  // downloaded for nothing, and the hint named npm, which this binary is not.
-  const dir = path.dirname(dest)
-  await access(dir, constants.W_OK).catch((err: NodeJS.ErrnoException) => {
+export function verifiedRelease(
+  manifest: unknown,
+  pkg: string,
+  key: SigningKey = NPM_SIGNING_KEY,
+): SignedRelease {
+  const m = (typeof manifest === 'object' && manifest !== null ? manifest : {}) as {
+    version?: unknown
+    dist?: { tarball?: unknown; integrity?: unknown; signatures?: unknown }
+  }
+  const version = typeof m.version === 'string' ? m.version : ''
+  const tarball = m.dist?.tarball
+  const integrity = m.dist?.integrity
+  if (version === '' || typeof tarball !== 'string' || !tarball.startsWith('https://')) {
     throw new UserError(
-      `vx upgrade: cannot write to ${dir} (${err.code ?? err.message}), where this vx lives — nothing downloaded; re-run as a user who can (sudo vx upgrade), or install vx somewhere you can write`,
+      `vx upgrade: the npm registry published no tarball for ${pkg}${version === '' ? '' : `@${version}`} — nothing replaced`,
     )
+  }
+  if (typeof integrity !== 'string' || !/^sha512-[A-Za-z0-9+/]+=*$/.test(integrity)) {
+    throw new UserError(
+      `vx upgrade: the npm registry published no SHA-512 integrity for ${pkg}@${version} — nothing to verify the download against, so it is not attempted`,
+    )
+  }
+  const signatures = Array.isArray(m.dist?.signatures)
+    ? (m.dist.signatures as unknown[]).filter(
+        (s): s is { keyid: string; sig: string } =>
+          typeof s === 'object' &&
+          s !== null &&
+          typeof (s as { keyid?: unknown }).keyid === 'string' &&
+          typeof (s as { sig?: unknown }).sig === 'string',
+      )
+    : []
+  if (signatures.length === 0) {
+    throw new UserError(
+      `vx upgrade: ${pkg}@${version} carries no npm registry signature, so it cannot be verified — nothing replaced`,
+    )
+  }
+  const ours = signatures.filter((s) => s.keyid === key.id)
+  if (ours.length === 0) {
+    throw new UserError(
+      `vx upgrade: ${pkg}@${version} is signed with an npm key this vx does not know (${[...new Set(signatures.map((s) => s.keyid))].join(', ')}) — if npm rotated its signing key, this vx's installer needs updating: install the new release with npm install -g @vzn/vx@latest, or from https://github.com/vznjs/vx/releases. Nothing replaced`,
+    )
+  }
+  const publicKey = createPublicKey({
+    key: Buffer.from(key.spki, 'base64'),
+    format: 'der',
+    type: 'spki',
+  })
+  const message = Buffer.from(`${pkg}@${version}:${integrity}`)
+  const valid = ours.some((s) => {
+    try {
+      return verify('sha256', message, publicKey, Buffer.from(s.sig, 'base64'))
+    } catch {
+      return false
+    }
   })
-  const res = await fetchOrRefuse(url, { redirect: 'follow' }, 'download the release asset')
+  if (!valid) {
+    throw new UserError(
+      `vx upgrade: the npm registry signature for ${pkg}@${version} is not valid — refusing to install; nothing replaced`,
+    )
+  }
+  return { version, tarball, integrity }
+}
+
+/** Download `release.tarball` and check its bytes against the signed SHA-512. */
+async function downloadVerified(release: SignedRelease): Promise<Uint8Array> {
+  const url = release.tarball
+  const res = await fetchOrRefuse(url, { redirect: 'follow' }, 'download the release')
   if (!res.ok) {
     throw new UserError(
       `vx upgrade: download failed (${res.status}) — ${url} — nothing replaced; re-run`,
     )
   }
   const bytes = new Uint8Array(
-    await readOrRefuse(() => res.arrayBuffer(), url, 'download the release asset'),
+    await readOrRefuse(() => res.arrayBuffer(), url, 'download the release'),
   )
-  if (bytes.byteLength === 0) {
-    throw new UserError(`vx upgrade: empty download — ${url} — nothing replaced; re-run`)
+  const got = `sha512-${new Bun.CryptoHasher('sha512').update(bytes).digest('base64')}`
+  if (got !== release.integrity) {
+    throw new UserError(
+      `vx upgrade: the download did not match the integrity npm signed (expected ${release.integrity}, got ${got}) — nothing replaced; try again, and if it repeats the tarball is not the one npm published`,
+    )
   }
-  const got = new Bun.CryptoHasher('sha256').update(bytes).digest('hex')
-  if (got !== sha256.toLowerCase()) {
+  return bytes
+}
+
+/**
+ * The `package/vx` file of a platform package's tarball (gzip'd ustar, as
+ * npm packs it). Only a regular file by that name is taken: the tarball is
+ * already verified, so this reads, it does not defend.
+ */
+export function binaryFromTarball(tgz: Uint8Array): Uint8Array {
+  let tar: Uint8Array
+  try {
+    tar = Bun.gunzipSync(tgz as Uint8Array<ArrayBuffer>)
+  } catch {
+    throw new UserError('vx upgrade: the release tarball is not gzip — nothing replaced')
+  }
+  const text = (b: Uint8Array): string => new TextDecoder().decode(b).replace(/\0[\s\S]*$/, '')
+  for (let at = 0; at + 512 <= tar.length;) {
+    const head = tar.subarray(at, at + 512)
+    const name = text(head.subarray(0, 100))
+    if (name === '') break
+    const prefix = text(head.subarray(257, 263)) === 'ustar' ? text(head.subarray(345, 500)) : ''
+    const size = Number.parseInt(text(head.subarray(124, 136)).trim() || '0', 8)
+    const type = head[156]
+    const body = at + 512
+    if (
+      (prefix === '' ? name : `${prefix}/${name}`) === 'package/vx' &&
+      (type === 0x30 || type === 0)
+    ) {
+      return tar.slice(body, body + size)
+    }
+    at = body + Math.ceil(size / 512) * 512
+  }
+  throw new UserError('vx upgrade: the release tarball holds no package/vx — nothing replaced')
+}
+
+/**
+ * The binary of `pkg@spec`, verified: the registry document's signature,
+ * then the tarball's integrity, then the extraction, each refusing before
+ * the next step runs. Null when the release is this vx's own version;
+ * `announce` hears the version before the download starts.
+ */
+export async function releaseBinary(
+  pkg: string,
+  spec: string,
+  announce: (version: string) => void,
+  key: SigningKey = NPM_SIGNING_KEY,
+): Promise<Uint8Array | null> {
+  const release = verifiedRelease(await fetchManifest(pkg, spec), pkg, key)
+  if (release.version === VERSION) return null
+  announce(release.version)
+  return binaryFromTarball(await downloadVerified(release))
+}
+
+/**
+ * Replace `dest` with the bytes `fetchBinary` returns (null: nothing to
+ * do, and false is returned), keeping `dest`'s
+ * mode (and, as root, its owner): a 0750 install came back 0755 and owned
+ * by whoever upgraded (item 1097). Whether this user can write beside
+ * `dest` is checked before `fetchBinary` runs, so a refusal downloads
+ * nothing. `starts`, when given, is asked of the replaced binary; false
+ * puts the old one back, since a verified download proves the bytes, not
+ * that this machine can run them (a CPU below the build's target, a
+ * `noexec` mount), and the upgrade reported success over a vx that no
+ * longer started.
+ */
+export async function replaceBinary(
+  dest: string,
+  fetchBinary: () => Promise<Uint8Array | null>,
+  starts?: (dest: string) => boolean,
+): Promise<boolean> {
+  // The swap writes beside the binary: a directory this user cannot write
+  // (a root-owned /usr/local/bin) failed at the rename, the whole release
+  // downloaded for nothing, and the hint named npm, which this binary is not.
+  const dir = path.dirname(dest)
+  await access(dir, constants.W_OK).catch((err: NodeJS.ErrnoException) => {
     throw new UserError(
-      `vx upgrade: the download did not match the release's SHA-256 (expected ${sha256}, got ${got}) — nothing replaced; try again, and if it repeats the asset is not the one the release published`,
+      `vx upgrade: cannot write to ${dir} (${err.code ?? err.message}), where this vx lives — nothing downloaded; re-run as a user who can (sudo vx upgrade), or install vx somewhere you can write`,
     )
+  })
+  const bytes = await fetchBinary()
+  if (bytes === null) return false
+  if (bytes.byteLength === 0) {
+    throw new UserError(`vx upgrade: the release's binary is empty — nothing replaced`)
   }
   // A fresh directory beside the binary, not a name built from the pid:
   // anyone who can write the install directory could plant a link at a
@@ -285,7 +374,7 @@ export async function replaceBinary(
   }
   if (starts === undefined || starts(dest)) {
     await rm(stage, { recursive: true, force: true })
-    return
+    return true
   }
   if (kept) await rename(old, dest)
   await rm(stage, { recursive: true, force: true })
@@ -294,6 +383,171 @@ export async function replaceBinary(
   )
 }
 
+/** How a package manager installed this vx: who owns it, and where to run the update. */
+export interface ManagedInstall {
+  manager: 'npm' | 'pnpm' | 'bun' | 'yarn'
+  /** `global`: the manager's own global tree; `project`: a dependency of `cwd`'s package.json. */
+  scope: 'global' | 'project'
+  cwd: string
+  /** The project field that lists `@vzn/vx`. */
+  field?: 'dependencies' | 'devDependencies' | 'optionalDependencies'
+}
+
+const FIELDS = ['devDependencies', 'dependencies', 'optionalDependencies'] as const
+
+function readJson(file: string): Record<string, unknown> | null {
+  try {
+    const v: unknown = JSON.parse(readFileSync(file, 'utf8'))
+    return typeof v === 'object' && v !== null ? (v as Record<string, unknown>) : null
+  } catch {
+    return null
+  }
+}
+
+/** The field of `dir`'s package.json that lists `@vzn/vx`, if one does. */
+function listingField(dir: string): ManagedInstall['field'] | undefined {
+  const pkg = readJson(path.join(dir, 'package.json'))
+  return FIELDS.find((f) => {
+    const deps = pkg?.[f]
+    return typeof deps === 'object' && deps !== null && PACKAGE in deps
+  })
+}
+
+/** The project's package manager: its lockfile, then `packageManager`, then the tree's shape. */
+function projectManager(dir: string, execPath: string): ManagedInstall['manager'] {
+  for (let d = dir; ; d = path.dirname(d)) {
+    if (existsSync(path.join(d, 'pnpm-lock.yaml'))) return 'pnpm'
+    if (existsSync(path.join(d, 'bun.lock')) || existsSync(path.join(d, 'bun.lockb'))) return 'bun'
+    if (existsSync(path.join(d, 'yarn.lock'))) return 'yarn'
+    if (
+      existsSync(path.join(d, 'package-lock.json')) ||
+      existsSync(path.join(d, 'npm-shrinkwrap.json'))
+    )
+      return 'npm'
+    const declared = readJson(path.join(d, 'package.json'))?.['packageManager']
+    if (typeof declared === 'string') {
+      const name = declared.split('@')[0]
+      if (name === 'pnpm' || name === 'bun' || name === 'yarn' || name === 'npm') return name
+    }
+    if (path.dirname(d) === d) break
+  }
+  return execPath.includes(`${path.sep}node_modules${path.sep}.pnpm${path.sep}`) ? 'pnpm' : 'npm'
+}
+
+/**
+ * How a package manager installed the binary at `execPath`, or null when
+ * none did (a release binary installed by hand). The launcher runs the
+ * platform package's binary, `…/node_modules/@vzn/vx-<os>-<arch>/vx`, so
+ * the path names the tree: a manager's global directory, or a project
+ * whose package.json lists `@vzn/vx` (the tree's root, else the nearest
+ * one above `cwd`, for a workspace whose dependencies are hoisted). A
+ * package-manager cache (npx, bunx) is refused: nothing there to upgrade.
+ */
+export function managedInstall(execPath: string, cwd: string): ManagedInstall | null {
+  const owner = npmOwnedBinary(execPath)
+  if (owner === null) return null
+  const p = execPath.split(path.sep).join('/')
+  const root = p.slice(0, `${p}/`.indexOf('/node_modules/'))
+  if (p.includes('/_npx/') || /\/bunx-[^/]*\//.test(p)) {
+    throw new UserError(
+      `vx upgrade: this vx runs from a package-manager cache (${execPath}) — nothing is installed to upgrade; ask for the version you want instead: npx @vzn/vx@latest, or bunx @vzn/vx@latest`,
+    )
+  }
+  if (p.includes('/.bun/install/global/')) return { manager: 'bun', scope: 'global', cwd: root }
+  if (/\/pnpm\/global\/|\/pnpm-global\//.test(p))
+    return { manager: 'pnpm', scope: 'global', cwd: root }
+  if (/\/yarn\/global\//.test(p)) return { manager: 'yarn', scope: 'global', cwd: root }
+  const field = listingField(root)
+  if (field !== undefined) {
+    return { manager: projectManager(root, execPath), scope: 'project', cwd: root, field }
+  }
+  for (let d = path.resolve(cwd); d.startsWith(root); d = path.dirname(d)) {
+    const f = listingField(d)
+    if (f !== undefined)
+      return { manager: projectManager(d, execPath), scope: 'project', cwd: d, field: f }
+    if (path.dirname(d) === d) break
+  }
+  // npm's global tree: `<prefix>/lib/node_modules` (nvm, volta, Homebrew alike).
+  if (path.basename(root) === 'lib' && !existsSync(path.join(root, 'package.json'))) {
+    return { manager: 'npm', scope: 'global', cwd: root }
+  }
+  throw new UserError(
+    `vx upgrade: this vx was installed by a package manager (${execPath} belongs to ${owner}), but no package.json from ${cwd} up lists ${PACKAGE} — run the upgrade with the manager that installed it, e.g. npm install -g ${PACKAGE}@latest`,
+  )
+}
+
+/** The argv that brings `install` to `version`. */
+export function upgradeArgv(install: ManagedInstall, version: string): string[] {
+  const spec = `${PACKAGE}@${version}`
+  const { manager } = install
+  if (install.scope === 'global') {
+    if (manager === 'yarn') return ['yarn', 'global', 'add', spec]
+    return manager === 'npm' ? ['npm', 'install', '-g', spec] : [manager, 'add', '-g', spec]
+  }
+  const field = install.field ?? 'devDependencies'
+  const flag = {
+    npm: {
+      devDependencies: '--save-dev',
+      dependencies: '--save',
+      optionalDependencies: '--save-optional',
+    },
+    pnpm: {
+      devDependencies: '--save-dev',
+      dependencies: '--save-prod',
+      optionalDependencies: '--save-optional',
+    },
+    bun: { devDependencies: '--dev', dependencies: '', optionalDependencies: '--optional' },
+    yarn: { devDependencies: '--dev', dependencies: '', optionalDependencies: '--optional' },
+  }[manager][field]
+  const argv = manager === 'npm' ? ['npm', 'install', spec] : [manager, 'add', spec]
+  if (flag !== '') argv.push(flag)
+  // pnpm refuses an `add` at a workspace's root without saying it means the root.
+  if (manager === 'pnpm' && existsSync(path.join(install.cwd, 'pnpm-workspace.yaml')))
+    argv.push('--workspace-root')
+  return argv
+}
+
+/** The version `tag` names, or the registry's latest, read for the "already at" check. */
+async function targetVersion(tag: string | undefined): Promise<string> {
+  const spec = versionSpec(tag)
+  if (spec !== 'latest') return spec
+  const v = ((await fetchManifest(PACKAGE, 'latest')) as { version?: unknown } | null)?.version
+  if (typeof v !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(v)) {
+    throw new UserError(`vx upgrade: the npm registry named no latest version of ${PACKAGE}`)
+  }
+  return v
+}
+
+/** Run the package manager that owns this vx; vx never installs one. */
+async function upgradeManaged(install: ManagedInstall, tag: string | undefined): Promise<number> {
+  const version = await targetVersion(tag)
+  if (version === VERSION) {
+    process.stdout.write(`vx upgrade: already at ${VERSION} — nothing to do\n`)
+    return 0
+  }
+  const argv = upgradeArgv(install, version)
+  const bin = Bun.which(argv[0]!)
+  if (bin === null) {
+    throw new UserError(
+      `vx upgrade: this vx was installed by ${argv[0]}, which is not on PATH — vx does not install package managers; run it yourself: ${argv.join(' ')} (in ${install.cwd})`,
+    )
+  }
+  process.stdout.write(
+    `vx upgrade: ${VERSION} → ${version}: running ${argv.join(' ')} (in ${install.cwd})\n`,
+  )
+  const proc = Bun.spawnSync({
+    cmd: [bin, ...argv.slice(1)],
+    cwd: install.cwd,
+    stdio: ['inherit', 'inherit', 'inherit'],
+  })
+  if (proc.exitCode !== 0) {
+    throw new UserError(
+      `vx upgrade: ${argv.join(' ')} failed (exit ${proc.exitCode}) — vx changed nothing itself`,
+    )
+  }
+  return 0
+}
+
 export async function upgradeCmd(args: readonly string[]): Promise<number> {
   const unknown = args.find((a) => a.startsWith('-'))
   if (unknown !== undefined) {
@@ -316,26 +570,29 @@ export async function upgradeCmd(args: readonly string[]): Promise<number> {
     )
   }
   const dest = process.execPath
-  const owner = npmOwnedBinary(dest)
-  if (owner !== null) {
-    throw new UserError(
-      `vx upgrade: this vx was installed by npm (${dest} belongs to ${owner}) — npm owns that file, and the next npm install would put the version it knows back. Update with: npm install -g @vzn/vx@latest`,
-    )
-  }
-  const asset = releaseAsset(await fetchRelease(tag), assetName())
-  if (isThisVersion(asset.tag, VERSION)) {
-    process.stdout.write(`vx upgrade: already at ${VERSION} (${asset.tag}) — nothing to do\n`)
-    return 0
-  }
-  process.stdout.write(`vx upgrade: ${VERSION} → ${tag ?? 'latest'} (${dest})\n`)
-  // The replaced binary's own version: the new build speaks for itself
-  // rather than this process guessing, and one that cannot is rolled back.
+  const install = managedInstall(dest, process.cwd())
+  if (install !== null) return await upgradeManaged(install, tag)
+  const pkg = platformPackage()
+  const spec = versionSpec(tag)
   let installed = ''
-  await replaceBinary(dest, asset.url, asset.sha256, (bin) => {
-    installed = startedVersion(bin) ?? ''
-    return installed !== ''
-  })
-  process.stdout.write(`vx upgrade: installed ${installed}\n`)
+  const replaced = await replaceBinary(
+    dest,
+    () =>
+      releaseBinary(pkg, spec, (version) =>
+        process.stdout.write(`vx upgrade: ${VERSION} → ${version} (${dest})\n`),
+      ),
+    // The replaced binary's own version: the new build speaks for itself
+    // rather than this process guessing, and one that cannot is rolled back.
+    (bin) => {
+      installed = startedVersion(bin) ?? ''
+      return installed !== ''
+    },
+  )
+  process.stdout.write(
+    replaced
+      ? `vx upgrade: installed ${installed}\n`
+      : `vx upgrade: already at ${VERSION} — nothing to do\n`,
+  )
   return 0
 }