feat: support pnpm catalogs

packages/nuxt-cli/package.json

@@ -67,6 +67,7 @@
     "perfect-debounce": "^2.1.0",
     "picocolors": "^1.1.1",
     "pkg-types": "^2.3.1",
+    "pnpm-workspace-yaml": "^1.6.1",
     "rc9": "^3.0.1",
     "scule": "^1.3.0",
     "source-map": "^0.7.6",

packages/nuxt-cli/src/commands/info.ts

@@ -15,6 +15,7 @@ import { writeText } from 'tinyclip'
 import { version as nuxiVersion } from '../../package.json'
 
 import { getBuilder } from '../utils/banner'
+import { resolveCatalogEntry } from '../utils/catalog'
 import { formatInfoBox } from '../utils/formatting'
 import { tryResolveNuxt } from '../utils/kit'
 import { logger } from '../utils/logger'
@@ -40,7 +41,8 @@ export default defineCommand({
     const nuxtConfig = await getNuxtConfig(cwd)
 
     // Find nearest package.json
-    const { dependencies = {}, devDependencies = {} } = await readPackageJSON(cwd).catch(() => ({} as PackageJson))
+    const projectPkg = await readPackageJSON(cwd).catch(() => ({} as PackageJson))
+    const { dependencies = {}, devDependencies = {} } = projectPkg
 
     // Utils to query a dependency version
     const nuxtPath = tryResolveNuxt(cwd)
@@ -54,7 +56,8 @@ export default defineCommand({
           return pkg.version!
         }
       }
-      return dependencies[name] || devDependencies[name]
+      return resolveCatalogEntry(cwd, projectPkg, name)?.specifier
+        ?? (dependencies[name] || devDependencies[name])
     }
 
     async function listModules(arr: NonNullable<NuxtConfig['modules']> = []) {

packages/nuxt-cli/src/commands/upgrade.ts

@@ -1,5 +1,6 @@
 import type { PackageJson } from 'pkg-types'
 
+import type { UpdateCatalogEntriesResult } from '../utils/catalog'
 import type { InstallResult } from '../utils/install'
 
 import { existsSync } from 'node:fs'
@@ -12,13 +13,14 @@ import { dirname, relative, resolve } from 'pathe'
 import colors from 'picocolors'
 import { findWorkspaceDir, readPackageJSON } from 'pkg-types'
 
+import { resolveCatalogEntry, updateCatalogEntries } from '../utils/catalog'
 import { createInstallLog, runDedupe, runInstall, takeUnreportedIgnoredBuilds } from '../utils/install'
 import { loadKit } from '../utils/kit'
 import { logger } from '../utils/logger'
 import { cleanupNuxtDirs, nuxtVersionToGitIdentifier } from '../utils/nuxt'
 import { getPackageManagerVersion } from '../utils/packageManagers'
 import { relativeToProcess, resolveRootDir } from '../utils/paths'
-import { getNuxtVersion } from '../utils/versions'
+import { getNuxtVersion, resolveRegistryVersion } from '../utils/versions'
 import { logLevelArgs, rootDirArgs } from './_shared'
 
 function checkNuxtDependencyType(pkg: PackageJson): 'dependencies' | 'devDependencies' {
@@ -31,6 +33,67 @@ function checkNuxtDependencyType(pkg: PackageJson): 'dependencies' | 'devDepende
   return 'dependencies'
 }
 
+const ALIAS_SPEC_RE = /^npm:(.+)@([^@]+)$/
+
+export interface InstallSpec {
+  /** Name the dependency is declared under. */
+  name: string
+  /** Package the version is resolved from, which differs from `name` for an aliased install. */
+  target: string
+  /** Dist-tag or semver range to resolve. */
+  range: string
+  /** Whether `target` is reached through an `npm:` alias. */
+  aliased: boolean
+}
+
+/**
+ * Split an install argument such as `nuxt@latest` or
+ * `nuxt@npm:nuxt-nightly@latest` into the parts needed to resolve a concrete
+ * version for it.
+ */
+export function parseInstallSpec(spec: string): InstallSpec {
+  const separator = spec.lastIndexOf('@')
+  if (separator < 1) {
+    return { name: spec, target: spec, range: 'latest', aliased: false }
+  }
+
+  const name = spec.slice(0, separator)
+  const rest = spec.slice(separator + 1)
+
+  const alias = spec.slice(spec.indexOf('@', 1) + 1).match(ALIAS_SPEC_RE)
+  if (alias) {
+    return { name: spec.slice(0, spec.indexOf('@', 1)), target: alias[1]!, range: alias[2]!, aliased: true }
+  }
+
+  return { name, target: name, range: rest, aliased: false }
+}
+
+const CATALOG_RANGE_RE = /^(?:npm:.+@)?([~^]?)\d+\.\d+\.\d+(?:[-+].+)?$/
+
+/**
+ * The range operator to keep when rewriting `specifier`, so an entry pinned to an
+ * exact version stays pinned. Anything that is not a plain version (a range such
+ * as `>=4.0.0`, or no entry at all) gets a caret, as `pnpm add` would write.
+ */
+export function resolveRangePrefix(specifier: string | undefined): string {
+  return specifier?.match(CATALOG_RANGE_RE)?.[1] ?? '^'
+}
+
+/**
+ * The specifier a catalog entry should hold for `spec`. pnpm resolves dist-tags
+ * and ranges itself when it writes to `package.json`, but a catalog entry we
+ * write ourselves has to name a concrete version. `current` is the specifier the
+ * entry holds today, whose range operator is preserved.
+ */
+export async function resolveCatalogSpecifier(spec: InstallSpec, current?: string): Promise<string | undefined> {
+  const version = await resolveRegistryVersion(spec.target, spec.range)
+  if (!version) {
+    return undefined
+  }
+  const range = `${resolveRangePrefix(current)}${version}`
+  return spec.aliased ? `npm:${spec.target}@${range}` : range
+}
+
 const nuxtVersionTags = {
   '3.x': '3x',
   '4.x': 'latest',
@@ -136,7 +199,23 @@ export default defineCommand({
     const packagesToUpdate = pkg ? corePackages.filter(p => pkg.dependencies?.[p] || pkg.devDependencies?.[p]) : []
 
     // Install latest version
-    const { npmPackages, nuxtVersion } = await getRequiredNewVersion(['nuxt', ...packagesToUpdate], ctx.args.channel)
+    const packageNames = ['nuxt', ...packagesToUpdate]
+    const { npmPackages, nuxtVersion } = await getRequiredNewVersion(packageNames, ctx.args.channel)
+
+    // A `catalog:` dependency has to be upgraded in `pnpm-workspace.yaml`: asking
+    // pnpm to add a pinned version instead replaces the reference in
+    // `package.json`, silently taking the dependency out of the catalog.
+    const catalogUpdates: Array<{ catalog: string, current?: string, spec: InstallSpec }> = []
+    const directPackages: string[] = []
+    for (const [index, name] of packageNames.entries()) {
+      const entry = packageManagerName === 'pnpm' ? resolveCatalogEntry(cwd, pkg, name) : undefined
+      if (entry) {
+        catalogUpdates.push({ catalog: entry.catalog, current: entry.specifier, spec: parseInstallSpec(npmPackages[index]!) })
+      }
+      else {
+        directPackages.push(npmPackages[index]!)
+      }
+    }
 
     // Force install
     const toRemove = ['node_modules']
@@ -192,21 +271,73 @@ export default defineCommand({
 
     const verbose = ctx.args.logLevel === 'verbose' || Boolean(process.env.DEBUG)
 
+    let catalogResult: UpdateCatalogEntriesResult | 'skipped' = 'skipped'
+
+    if (catalogUpdates.length > 0) {
+      const catalogSpinner = spinner()
+      catalogSpinner.start('Updating catalog entries')
+
+      const resolved: Array<{ catalog: string, pkg: string, specifier: string }> = []
+      const unresolved: string[] = []
+
+      for (const { catalog, current, spec } of catalogUpdates) {
+        const specifier = await resolveCatalogSpecifier(spec, current)
+        if (!specifier) {
+          unresolved.push(spec.name)
+          continue
+        }
+        resolved.push({ catalog, pkg: spec.name, specifier })
+      }
+
+      if (resolved.length > 0) {
+        catalogResult = updateCatalogEntries(cwd, resolved)
+      }
+
+      catalogSpinner.stop(
+        catalogResult === 'updated'
+          ? `Catalog entries updated: ${resolved.map(({ pkg, specifier }) => `${pkg}@${specifier}`).join(', ')}`
+          : 'No catalog entries updated',
+      )
+
+      if (unresolved.length > 0) {
+        logger.warn(`Unable to resolve a ${versionType} version for ${unresolved.map(name => colors.cyan(name)).join(', ')} from the npm registry. Their catalog entries were left unchanged.`)
+        logger.info(`Run with ${colors.cyan('DEBUG=nuxi')} to see why the lookup failed.`)
+      }
+
+      if (catalogResult === 'failed') {
+        logger.warn(`Unable to update the catalog entries for ${resolved.map(({ pkg }) => colors.cyan(pkg)).join(', ')}. Check ${colors.cyan('pnpm-workspace.yaml')} is readable and valid.`)
+      }
+
+      // Without a catalog entry pointing at the new version there is nothing for
+      // the install to upgrade, and reporting success would be a lie.
+      const nuxtUpgradeFailed = catalogResult === 'failed'
+        ? resolved.some(({ pkg }) => pkg === 'nuxt')
+        : unresolved.includes('nuxt')
+      if (nuxtUpgradeFailed) {
+        logger.error(`Unable to upgrade ${colors.cyan('nuxt')} in ${colors.cyan('pnpm-workspace.yaml')}.`)
+        outro('Upgrade cancelled.')
+        process.exit(1)
+      }
+    }
+
     const installFailed = await withInstallSpinner(
       `Installing ${versionType} Nuxt ${nuxtVersion} release`,
       'Nuxt packages installed',
       { verbose },
       hooks => runInstall({
         cwd,
         packageManager,
-        dependencies: npmPackages,
+        dependencies: directPackages,
         dev: nuxtDependencyType === 'devDependencies',
         workspace: packageManager.name === 'pnpm' && existsSync(resolve(cwd, 'pnpm-workspace.yaml')),
         ...hooks,
       }),
     )
 
     if (installFailed) {
+      if (catalogResult === 'updated') {
+        logger.info(`Your ${colors.cyan('pnpm-workspace.yaml')} catalog entries were already updated, so review them before retrying.`)
+      }
       process.exit(1)
     }
 

packages/nuxt-cli/src/utils/catalog.ts

@@ -0,0 +1,152 @@
+import type { PackageJson } from 'pkg-types'
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+
+import { dirname, join, resolve } from 'pathe'
+import { parsePnpmWorkspaceYaml } from 'pnpm-workspace-yaml'
+
+const CATALOG_SPECIFIER_RE = /^catalog:(.*)$/
+
+const DEFAULT_CATALOG = 'default'
+
+export interface CatalogEntry {
+  /** The catalog the specifier points at. `default` for a bare `catalog:`. */
+  catalog: string
+  /** The specifier the catalog resolves to, e.g. `^4.2.0`. Absent when the catalog has no such entry. */
+  specifier?: string
+}
+
+export interface CatalogConfig {
+  /** Absolute path of the `pnpm-workspace.yaml` the catalogs are declared in. */
+  filePath: string
+  catalogs: Record<string, Record<string, string>>
+}
+
+/**
+ * The catalog a `catalog:` / `catalog:name` specifier refers to, or `undefined`
+ * for any other specifier.
+ */
+export function parseCatalogSpecifier(specifier: string | undefined): string | undefined {
+  const match = specifier?.match(CATALOG_SPECIFIER_RE)
+  if (!match) {
+    return undefined
+  }
+  return match[1] || DEFAULT_CATALOG
+}
+
+/** Nearest `pnpm-workspace.yaml` at or above `cwd`. */
+export function findPnpmWorkspaceYaml(cwd: string): string | undefined {
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    const filePath = join(dir, 'pnpm-workspace.yaml')
+    if (existsSync(filePath)) {
+      return filePath
+    }
+    if (dir === dirname(dir)) {
+      return undefined
+    }
+  }
+}
+
+const configCache = new Map<string, CatalogConfig | undefined>()
+
+/** Discard memoised catalog configuration, so a later read sees changes on disk. */
+export function clearCatalogCache(): void {
+  configCache.clear()
+}
+
+/**
+ * Catalogs declared in the nearest `pnpm-workspace.yaml`, keyed by catalog name.
+ * The top-level `catalog` key is exposed as {@link DEFAULT_CATALOG}.
+ *
+ * Results are memoised per workspace file, as commands such as `nuxi info` query
+ * dozens of dependencies in a row.
+ */
+export function readCatalogConfig(cwd: string): CatalogConfig | undefined {
+  const filePath = findPnpmWorkspaceYaml(cwd)
+  if (!filePath) {
+    return undefined
+  }
+
+  if (configCache.has(filePath)) {
+    return configCache.get(filePath)
+  }
+
+  const config = parseCatalogConfig(filePath)
+  configCache.set(filePath, config)
+  return config
+}
+
+function parseCatalogConfig(filePath: string): CatalogConfig | undefined {
+  let workspace: ReturnType<typeof parsePnpmWorkspaceYaml>
+  try {
+    workspace = parsePnpmWorkspaceYaml(readFileSync(filePath, 'utf-8'))
+  }
+  catch {
+    return undefined
+  }
+
+  const json = workspace.toJSON()
+  const catalogs: CatalogConfig['catalogs'] = { ...json.catalogs }
+  if (json.catalog) {
+    catalogs[DEFAULT_CATALOG] = json.catalog
+  }
+
+  if (Object.keys(catalogs).length === 0) {
+    return undefined
+  }
+
+  return { filePath, catalogs }
+}
+
+/**
+ * Resolve the specifier `pkg` is declared with in `pkgJson` through the project's
+ * catalogs. Returns `undefined` when the dependency is absent or not
+ * catalog-managed, so a caller can fall back to the declared specifier.
+ */
+export function resolveCatalogEntry(cwd: string, pkgJson: PackageJson | null | undefined, pkg: string): CatalogEntry | undefined {
+  const specifier = pkgJson?.dependencies?.[pkg] || pkgJson?.devDependencies?.[pkg]
+  const catalog = parseCatalogSpecifier(specifier)
+  if (!catalog) {
+    return undefined
+  }
+
+  const config = readCatalogConfig(cwd)
+  return { catalog, specifier: config?.catalogs[catalog]?.[pkg] }
+}
+
+/** The outcome of a {@link updateCatalogEntries} call. */
+export type UpdateCatalogEntriesResult = 'updated' | 'unchanged' | 'failed'
+
+export interface CatalogEntryUpdate {
+  catalog: string
+  pkg: string
+  specifier: string
+}
+
+/**
+ * Point catalog entries at new specifiers in a single read/write of
+ * `pnpm-workspace.yaml`, preserving its comments, anchors and aliases.
+ */
+export function updateCatalogEntries(cwd: string, updates: CatalogEntryUpdate[]): UpdateCatalogEntriesResult {
+  const filePath = findPnpmWorkspaceYaml(cwd)
+  if (!filePath) {
+    return 'failed'
+  }
+
+  try {
+    const workspace = parsePnpmWorkspaceYaml(readFileSync(filePath, 'utf-8'))
+    for (const { catalog, pkg, specifier } of updates) {
+      workspace.setPackage(catalog, pkg, specifier)
+    }
+    if (!workspace.hasChanged()) {
+      return 'unchanged'
+    }
+
+    writeFileSync(filePath, workspace.toString(), 'utf-8')
+    configCache.delete(filePath)
+    return 'updated'
+  }
+  catch {
+    return 'failed'
+  }
+}