@vzn/vx 0.0.591 → 0.0.595

package/src/workspace/migrate-scripts.ts

@@ -41,6 +41,7 @@ import {
   cacheTodo,
   pruneOrphanPersistentNotes,
 } from './migration.js'
+import { relPosix } from '../util/index.js'
 
 // `lint` is not here: a linter reads sources, and an edge to `build`
 // serialises the two for nothing (the init walkthrough, 2026-09-04).
@@ -127,12 +128,26 @@ function runsScriptHooks(dir: string, memo: Map<string, Owner>): string | null {
       : manager === 'npm'
         ? !set('ignore-scripts', 'true')
         : manager === 'pnpm'
-          ? !set('enable-pre-post-scripts', 'false') &&
-            !/^enablePrePostScripts:\s*false\s*$/m.test(read('pnpm-workspace.yaml') ?? '')
+          ? !set('enable-pre-post-scripts', 'false') && !pnpmSkipsHooks(read('pnpm-workspace.yaml'))
           : true
   return runs ? manager : null
 }
 
+/**
+ * `enablePrePostScripts: false` in `pnpm-workspace.yaml`, read as pnpm reads
+ * it, as YAML: a line regex missed `false # hooks off` and a flow mapping,
+ * which pnpm 10 honours, and folded hooks pnpm does not run.
+ */
+function pnpmSkipsHooks(yaml: string | undefined): boolean {
+  if (yaml === undefined) return false
+  try {
+    const parsed = Bun.YAML.parse(yaml) as { enablePrePostScripts?: unknown } | null
+    return parsed?.enablePrePostScripts === false
+  } catch {
+    return false
+  }
+}
+
 /** The package manager that owns a directory, and the directory that says so. */
 interface Owner {
   manager: string
@@ -155,8 +170,10 @@ function ownerOf(dir: string, memo: Map<string, Owner>): Owner {
   }
   let manager: string | undefined
   try {
-    const pm = (JSON.parse(read('package.json') ?? '') as { packageManager?: unknown })
-      .packageManager
+    // A byte-order mark is stripped, as npm, pnpm and discovery strip it:
+    // JSON.parse threw on one and the field went unread.
+    const manifest = (read('package.json') ?? '').replace(/^\uFEFF/, '')
+    const pm = (JSON.parse(manifest) as { packageManager?: unknown }).packageManager
     // A manager vx knows nothing of (zod's `nub@0.8.3`) says nothing about
     // hooks: the lockfile beside it does, and "nub ran `postbuild`" was a
     // claim nothing had checked (D-96).
@@ -524,7 +541,7 @@ function siblingRun(script: string, dir: string, others: readonly string[]): str
 function lernaPackages(dir: string): string[] | undefined {
   let json: unknown
   try {
-    json = JSON.parse(readFileSync(path.join(dir, 'lerna.json'), 'utf8'))
+    json = JSON.parse(readFileSync(path.join(dir, 'lerna.json'), 'utf8').replace(/^\uFEFF/, ''))
   } catch {
     return undefined
   }
@@ -789,7 +806,7 @@ export function migrateScripts(
   } else if (clash !== undefined && outsideDir !== undefined && unnamedMaps().length > 0) {
     const would = unnamedMaps()
     notes.push(
-      `${clash.name} (the workspace root) not mapped: ${path.relative(outsideDir, clash.dir).split(path.sep).join('/')} has the same "name", and vx names a project by it; rename the root's and run \`vx init\` again to map ${would.length} of its scripts (${would.slice(0, 8).join(', ')}${would.length > 8 ? ', …' : ''})`,
+      `${clash.name} (the workspace root) not mapped: ${relPosix(outsideDir, clash.dir)} has the same "name", and vx names a project by it; rename the root's and run \`vx init\` again to map ${would.length} of its scripts (${would.slice(0, 8).join(', ')}${would.length > 8 ? ', …' : ''})`,
     )
   } else if (rootName === 'package.json' && outsideDir !== undefined && unnamedMaps().length > 0) {
     // react's nameless root: "its scripts run the workspace" was not why,

package/src/workspace/package-graph.ts

@@ -73,7 +73,7 @@ export function buildPackageGraph(
     const dev = bucket(p.packageJson.devDependencies)
     const add = (key: string, spec: unknown, installed: boolean, into: Set<string>): void => {
       if (typeof spec !== 'string') return
-      const target = linked(key, spec.trim(), p.dir, installed)
+      const target = linked(key, fromCatalog(p, key, spec.trim()), p.dir, installed)
       if (target !== undefined && target !== p.name) into.add(target)
     }
     // Which entry is installed when a key sits in more than one field,
@@ -300,6 +300,19 @@ export function buildPackageGraph(
   }
 }
 
+/**
+ * The spec a `catalog:` / `catalog:<name>` entry stands for in the
+ * workspace's catalog, so it is an edge by the rule its range or protocol
+ * meets (zenstack's `nuxt: "catalog:"` is `4.3.1`, which the workspace's
+ * versionless `nuxt` sample does not satisfy). A catalog the graph was not
+ * given or that lacks the key leaves the spec, which keeps its edge.
+ */
+function fromCatalog(p: ProjectMeta, key: string, spec: string): string {
+  if (p.catalogs === undefined || !spec.startsWith('catalog:')) return spec
+  const resolved = p.catalogs.get(spec.slice('catalog:'.length).trim() || 'default')?.[key]
+  return typeof resolved === 'string' && !resolved.startsWith('catalog:') ? resolved.trim() : spec
+}
+
 function bucket(field: unknown): Readonly<Record<string, unknown>> {
   return typeof field === 'object' && field !== null ? (field as Record<string, unknown>) : {}
 }
@@ -377,8 +390,7 @@ function linkedTarget(
     if (!MAY_POINT_ELSEWHERE.test(spec)) {
       const local = byName.get(key)
       if (local === undefined) return undefined
-      // A catalog entry's range lives where the graph does not read
-      // (`pnpm-workspace.yaml`, bun's root `catalog`): it keeps the edge.
+      // A catalog entry its workspace's catalog did not resolve keeps the edge.
       if (!installed || spec.startsWith('catalog:')) return key
       return satisfies(local, spec) ? key : undefined
     }

package/src/workspace/project-loader.ts

@@ -269,6 +269,9 @@ interface BuildPosition {
   column?: number
 }
 
+/** A stack frame naming a file path, as a config's own throw has. */
+const NAMED_FRAME = /\n\s+at .*[\\/]/
+
 /**
  * Turn the two errors Bun's own loader throws into user errors naming the
  * file the user wrote; every other throw is the config's own and already
@@ -301,6 +304,13 @@ export function configLoadError(err: unknown, configPath: string, kind: string):
     return configLoadError(errors[0], configPath, kind)
   }
   if (typeof message !== 'string') return null
+  // Bun's JSON loader throws a `SyntaxError` whose stack, when it has one,
+  // holds no file frame: a malformed `import data from './data.json'`
+  // printed `vx: JSON Parse error: Expected '}'` and named nothing. A
+  // config's own `JSON.parse` has its line in the stack and passes through.
+  if (name === 'SyntaxError' && !NAMED_FRAME.test(String((err as { stack?: unknown }).stack))) {
+    return new UserError(`${kind} config ${configPath}: an import does not parse: ${message}`)
+  }
   if (name === 'ResolveMessage') {
     const spec = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(message)?.[1]
     const what = spec === undefined ? message.replace(BUST_QUERY, '') : `cannot find '${spec}'`
@@ -469,6 +479,7 @@ export async function loadProjectConfigs(
   let env: Readonly<Record<string, string | undefined>> = {}
   let cwd = ''
   let umask = -1
+  let unredirect: (() => void) | undefined
   // More than one evaluation in flight: a change seen after one load may
   // be another's.
   let overlapping = false
@@ -578,6 +589,7 @@ export async function loadProjectConfigs(
       else misses.push(i)
     }
     if (misses.length > 0) {
+      unredirect = stdoutToStderr()
       builtins = builtinSnapshot()
       env = { ...process.env }
       cwd = process.cwd()
@@ -641,6 +653,7 @@ export async function loadProjectConfigs(
       )
     return results.map((r) => (r as Loaded).config)
   } finally {
+    unredirect?.()
     endRound()
     if (store !== undefined && !tainted) {
       if (evals.length > 0) {
@@ -655,6 +668,72 @@ export async function loadProjectConfigs(
   }
 }
 
+/**
+ * Every route to fd 1 sent to stderr while configs evaluate in this
+ * process; returns the release. A verb's stdout is its output (`vx show
+ * --format json`), and a config's `console.log` came out ahead of the
+ * JSON. The worker does the same for a repeat load (D-64), `vx mcp` for
+ * its whole serve. Taken before a round's built-in snapshot and released
+ * after its check, so the guard sees no change of vx's own.
+ *
+ * Counted, because rounds overlap (`--affected`'s per-file sweep loads each
+ * config in a round of its own): a second install over the first moved
+ * `Bun.write` and `console` under the first round's snapshot, which refused
+ * the loads, and the undos ran out of order and left a redirect in place
+ * for good. The first taker installs; the last release restores.
+ */
+let redirectHolders = 0
+let undoRedirect = (): void => {}
+/**
+ * Bun's own `Console`, taken at load: the console a round finds may be a
+ * constructed one (`vx mcp` serves under its own), which has no `Console`.
+ * The global's, not `node:console`'s: the playground bundles this module
+ * for the browser, where that specifier is a stub.
+ */
+const BunConsole = (globalThis.console as { Console?: typeof console.Console }).Console
+
+function stdoutToStderr(): () => void {
+  if (redirectHolders++ === 0) undoRedirect = installRedirect()
+  return () => {
+    if (--redirectHolders === 0) undoRedirect()
+  }
+}
+
+function installRedirect(): () => void {
+  const out = process.stdout
+  const ownWrite = Object.getOwnPropertyDescriptor(out, 'write')
+  const ownConsole = globalThis.console
+  const bun = Bun as { write: typeof Bun.write }
+  const ownBunWrite = Bun.write
+  const ownWriter = Object.getOwnPropertyDescriptor(Bun.stdout, 'writer')
+  out.write = ((...args: Parameters<typeof process.stderr.write>) =>
+    process.stderr.write(...args)) as typeof out.write
+  bun.write = ((dest: unknown, ...rest: unknown[]) =>
+    (ownBunWrite as (...a: unknown[]) => Promise<number>)(
+      dest === Bun.stdout ? Bun.stderr : dest,
+      ...rest,
+    )) as typeof Bun.write
+  ;(Bun.stdout as { writer: typeof Bun.stdout.writer }).writer = ((
+    ...args: Parameters<typeof Bun.stderr.writer>
+  ) => Bun.stderr.writer(...args)) as typeof Bun.stdout.writer
+  // Bun's console adds `write`, which a constructed Console lacks.
+  globalThis.console = Object.assign(new BunConsole!(process.stderr, process.stderr), {
+    write: (...data: string[]) => {
+      const text = data.join('')
+      process.stderr.write(text)
+      return text.length
+    },
+  })
+  return () => {
+    if (ownWrite === undefined) delete (out as { write?: unknown }).write
+    else Object.defineProperty(out, 'write', ownWrite)
+    bun.write = ownBunWrite
+    if (ownWriter === undefined) delete (Bun.stdout as { writer?: unknown }).writer
+    else Object.defineProperty(Bun.stdout, 'writer', ownWriter)
+    globalThis.console = ownConsole
+  }
+}
+
 /**
  * The built-in prototypes a config's object is read through. A config that
  * set `Object.prototype.exec` gave every other project's task that
@@ -665,14 +744,19 @@ export async function loadProjectConfigs(
  */
 // `Bun` and `Bun.hash` are what vx itself runs on: `Bun.hash.xxHash3 = ()
 // => 7n` gave every task the key 00000000, and a changed command replayed
-// the old output (D-75).
+// the old output (D-75). `Bun` is read by its identifier, not through
+// globalThis: the docs playground bundles this file with the identifier
+// rewritten to its shim, and a browser has no global `Bun`.
 const WATCHED_BUILTINS: ReadonlyArray<readonly [string, object]> = WATCHED_BUILTIN_NAMES.map(
   (name) =>
     [
       name,
       name
         .split('.')
-        .reduce<unknown>((o, k) => (o as Record<string, unknown>)[k], globalThis) as object,
+        .reduce<unknown>(
+          (o, k) => (o === globalThis && k === 'Bun' ? Bun : (o as Record<string, unknown>)[k]),
+          globalThis,
+        ) as object,
     ] as const,
 )
 
@@ -736,6 +820,7 @@ const BUN_MEMBERS_VX_READS: readonly PropertyKey[] = [
   'sleep',
   'spawn',
   'spawnSync',
+  'stderr',
   'stdout',
   'stringWidth',
   'stripANSI',
@@ -1024,6 +1109,7 @@ export async function loadWorkspaceConfig(root: string): Promise<WorkspaceConfig
     // left out: it loads first in every run, filtered or not, so none
     // depends on what else loaded (D-122's case), and plugins' tests and
     // tools hand state through them.
+    const unredirect = stdoutToStderr()
     const builtins = builtinSnapshot('globalThis', true)
     const env = { ...process.env }
     const cwd = process.cwd()
@@ -1038,6 +1124,7 @@ export async function loadWorkspaceConfig(root: string): Promise<WorkspaceConfig
         ...restoreCwd(cwd),
         ...restoreUmask(umask),
       ]
+      unredirect()
       // eslint-disable-next-line no-unsafe-finally -- the refusal outranks the load's own error
       if (changed.length > 0) throw builtinsChanged(changed, configPath)
     }

package/src/workspace/workspace.ts

@@ -31,8 +31,18 @@ export interface Workspace {
   root: string
   /** Glob patterns relative to root that match project directories. */
   packageGlobs: string[]
+  /** The package manager's catalogs, when the root declares any. */
+  catalogs?: Catalogs
 }
 
+/**
+ * Catalog name → dependency → the spec a `catalog:<name>` entry stands
+ * for; `catalog:` alone is `default`. pnpm's from `pnpm-workspace.yaml`
+ * (`catalog`, `catalogs`), bun's from the root `package.json` (the same
+ * keys, top level or under `workspaces`).
+ */
+export type Catalogs = ReadonlyMap<string, Readonly<Record<string, unknown>>>
+
 export interface ProjectMeta {
   /** Canonical name from package.json. */
   name: string
@@ -41,6 +51,8 @@ export interface ProjectMeta {
   packageJson: PackageJson
   /** Absolute path to vx.config.{ts,mts,js,mjs,cts,cjs} or null. */
   configPath: string | null
+  /** The workspace's catalogs, which the package graph resolves `catalog:` specs through. */
+  catalogs?: Catalogs
 }
 
 /** A discovered project joined with its loaded vx config. */
@@ -115,8 +127,12 @@ export async function findWorkspaceRoot(
         // them: `packages/**` holding `packages/inner` (with `workspaces:
         // ['sub']`) and `packages/inner/sub` resolved `sub` to `inner` and
         // `inner` to the outer root, two roots and two keys for one tree.
-        if (claimsMember(dir, [claimed], globs) && claimsMember(dir, members, globs)) claimed = dir
-      } else if (claimsMember(dir, inner === null ? below : [inner], globs)) {
+        if (
+          (await claimsMember(dir, [claimed], globs)) &&
+          (await claimsMember(dir, members, globs))
+        )
+          claimed = dir
+      } else if (await claimsMember(dir, inner === null ? below : [inner], globs)) {
         claimed = dir
         members = inner === null ? [...below] : [inner]
       }
@@ -152,7 +168,11 @@ export async function findWorkspaceRoot(
 }
 
 /** True when one of `below` (dirs under `root`, toward `start`) is a member. */
-function claimsMember(root: string, below: readonly string[], globs: readonly string[]): boolean {
+async function claimsMember(
+  root: string,
+  below: readonly string[],
+  globs: readonly string[],
+): Promise<boolean> {
   if (below.length === 0 || globs.length === 0) return false
   const { positive, negative } = splitPackageGlobs(globs)
   const rels = below.map((d) => relPosix(root, d)).filter((rel) => !excludedBy(rel, negative))
@@ -160,12 +180,25 @@ function claimsMember(root: string, below: readonly string[], globs: readonly st
     const normalized = pattern.replace(/\/+$/, '')
     // `.` means the root itself is the project — never a directory below it.
     if (normalized === '' || normalized === '.') continue
-    const glob = new Bun.Glob(normalized)
-    if (rels.some((rel) => glob.match(rel))) return true
+    // Matched as discovery scans, on the manifest: `packages/**` lists
+    // `packages/package.json`, while against the directory `**` needs a
+    // segment below `packages`, and a run from there was its own root.
+    const glob = new Bun.Glob(`${normalized}/package.json`)
+    for (const rel of rels) {
+      if (!glob.match(`${rel}/package.json`)) continue
+      // `match` has no `dot: false`: `packages/*` matched `packages/.tpl`,
+      // which discovery skips, and a run from inside it found a workspace
+      // that does not list it. Such a path asks discovery's own walk.
+      if (!SKIPPED_SEGMENT.test(rel)) return true
+      const dirs = await memberDirs(root, pattern)
+      if (dirs.includes(path.join(root, rel))) return true
+    }
   }
   return false
 }
 
+const SKIPPED_SEGMENT = /(^|\/)(\.|node_modules(\/|$))/
+
 /**
  * pnpm, npm, yarn and Bun all take `!packages/fixtures` in the package
  * list. Handed to `Bun.Glob` raw, a leading `!` negates the WHOLE pattern,
@@ -213,17 +246,30 @@ function excludedBy(rel: string, negative: readonly string[]): boolean {
  * the root itself is the only project, hence `['.']`.
  */
 async function readPackageGlobs(dir: string, reads?: LoadReads): Promise<string[] | null> {
+  return (await readRootManifests(dir, reads)).globs
+}
+
+/** `readPackageGlobs`, and the catalogs the same manifests declare. */
+async function readRootManifests(
+  dir: string,
+  reads?: LoadReads,
+): Promise<{ globs: string[] | null; catalogs: Catalogs | undefined }> {
   const yamlPath = path.join(dir, 'pnpm-workspace.yaml')
   const yaml = await readOnce(reads, yamlPath)
   let yamlWithoutPackages = false
+  // pnpm reads its catalogs from this file alone, bun from package.json.
+  let catalogs: Catalogs | undefined
   if (yaml !== null) {
     const parsed = parseManifest(decoder.decode(yaml), yamlPath, Bun.YAML.parse)
     if (parsed !== null && parsed !== undefined) {
       if (typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new UserError(`${yamlPath}: must be a mapping (\`packages:\` and pnpm's settings)`)
       }
+      catalogs = catalogsOf([parsed])
       const packages = (parsed as { packages?: unknown }).packages
-      if (packages !== undefined) return assertGlobList(packages, yamlPath, 'packages')
+      if (packages !== undefined) {
+        return { globs: assertGlobList(packages, yamlPath, 'packages'), catalogs }
+      }
     }
     // No `packages:`: pnpm 10 keeps its settings and catalogs in this file
     // for a single-package repo too. The root's package.json decides, as it
@@ -233,18 +279,46 @@ async function readPackageGlobs(dir: string, reads?: LoadReads): Promise<string[
   }
   const pkgPath = path.join(dir, 'package.json')
   const pkgBytes = await readOnce(reads, pkgPath)
-  if (pkgBytes === null) return yamlWithoutPackages ? [] : null
+  if (pkgBytes === null) return { globs: yamlWithoutPackages ? [] : null, catalogs }
   const pkg = parsePackageJson(decoder.decode(pkgBytes), pkgPath)
   const ws = pkg.workspaces as unknown
-  if (ws === undefined || ws === null) return ['.']
+  if (yaml === null) {
+    catalogs = catalogsOf(
+      ws !== null && typeof ws === 'object' && !Array.isArray(ws) ? [pkg, ws] : [pkg],
+    )
+  }
+  if (ws === undefined || ws === null) return { globs: ['.'], catalogs }
   if (ws && typeof ws === 'object' && !Array.isArray(ws) && 'packages' in ws) {
-    return assertGlobList(
+    const globs = assertGlobList(
       (ws as { packages?: unknown }).packages ?? [],
       pkgPath,
       'workspaces.packages',
     )
+    return { globs, catalogs }
+  }
+  return { globs: assertGlobList(ws, pkgPath, 'workspaces'), catalogs }
+}
+
+/**
+ * The `catalog` and `catalogs` keys of the manifests (bun reads them at
+ * the top level and under `workspaces`), or undefined when none declares
+ * one. An entry that is not a mapping is no catalog: a `catalog:` spec
+ * through it keeps its edge, as one through an unknown catalog does.
+ */
+function catalogsOf(manifests: readonly object[]): Catalogs | undefined {
+  const isMap = (v: unknown): v is Record<string, unknown> =>
+    typeof v === 'object' && v !== null && !Array.isArray(v)
+  let out: Map<string, Readonly<Record<string, unknown>>> | undefined
+  for (const m of manifests) {
+    const { catalog, catalogs } = m as { catalog?: unknown; catalogs?: unknown }
+    if (isMap(catalogs)) {
+      for (const [name, c] of Object.entries(catalogs))
+        if (isMap(c)) (out ??= new Map()).set(name, c)
+    }
+    // `catalog` is the default catalog to pnpm and bun.
+    if (isMap(catalog)) (out ??= new Map()).set('default', catalog)
   }
-  return assertGlobList(ws, pkgPath, 'workspaces')
+  return out
 }
 
 /**
@@ -374,6 +448,11 @@ function extglobRefusal(pattern: string, file: string, field: string): UserError
  */
 export function resolveCacheDir(root: string, config: WorkspaceConfig | null): string {
   const rel = config?.cacheDir ?? (process.env['VX_CACHE_DIR'] || path.join('.vx', 'cache'))
+  // No shell expands `~` in a config string or a quoted variable, and
+  // `'~/.cache/vx'` made a directory named `~` in the workspace.
+  if (rel.startsWith('~/')) {
+    return path.join(process.env['HOME'] || homedir(), rel.slice(1))
+  }
   return path.resolve(root, rel)
 }
 
@@ -412,14 +491,14 @@ const repoIds = new Map<string, Promise<string | null>>()
  * itself is treated as a single-project workspace.
  */
 export async function loadWorkspace(root: string, reads?: LoadReads): Promise<Workspace> {
-  const packageGlobs = await readPackageGlobs(root, reads)
+  const { globs: packageGlobs, catalogs } = await readRootManifests(root, reads)
   if (packageGlobs === null) {
     // The CLI never lands here (findWorkspaceRoot returns only a dir that
     // passes one of the two checks); a direct call of this public function
     // on a bare dir does (D-58).
     throw new UserError(`workspace root ${root} has neither pnpm-workspace.yaml nor package.json`)
   }
-  return { root, packageGlobs }
+  return catalogs === undefined ? { root, packageGlobs } : { root, packageGlobs, catalogs }
 }
 
 // `<dir>/*` — the shape of nearly every workspace glob. Anything with another
@@ -697,6 +776,16 @@ export async function discoverProjects(
   for (const entry of loaded) {
     if (entry === null) continue
     const { dir, pkg, configPath } = entry
+    // npm and pnpm take `../ext/*`, but `--affected` asks git from the root
+    // and sees nothing outside it: an edit there moved the task's key and
+    // selected nothing, green.
+    const rel = relPosix(workspace.root, dir)
+    if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) {
+      throw new UserError(
+        `workspace member ${rel} (${dir}) is outside the workspace root ${workspace.root}: ` +
+          'vx keeps every project under the root. Move the workspace root up to a directory that holds every member.',
+      )
+    }
     if (!pkg.name) {
       nameless?.push(dir)
       // A nameless manifest can't be addressed, filtered, or made affected —
@@ -730,7 +819,7 @@ export async function discoverProjects(
     }
     if (group.length === 1) {
       const { dir, pkg, configPath } = group[0]!
-      projects.push({ name, dir, packageJson: pkg, configPath })
+      projects.push(withCatalogs({ name, dir, packageJson: pkg, configPath }, workspace))
       continue
     }
     // The root's own manifest is '' relative to itself, and the refusal read
@@ -809,6 +898,19 @@ export async function namedProject(
   if (typeof named?.name !== 'string' || named.name === '' || typeof named.dir !== 'string') {
     throw new UserError(`${where} ${JSON.stringify(named)}: expected { dir: string, name: string }`)
   }
+  // The rules `parsePackageJson` holds a manifest's name to: a plugin's name
+  // for a directory with no `name` of its own skipped them, and `a#b` planned
+  // under `--all` while no run spec or dependsOn could reach it.
+  if (named.name.trim() !== named.name) {
+    throw new UserError(
+      `${where} ${JSON.stringify(named.name)}: the name has surrounding whitespace`,
+    )
+  }
+  if (named.name.includes('#')) {
+    throw new UserError(
+      `${where} "${named.name}": the name holds "#" — vx addresses a task as <name>#<task>`,
+    )
+  }
   const dir = path.resolve(workspace.root, named.dir)
   const rel = relPosix(workspace.root, dir)
   if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) {
@@ -848,5 +950,10 @@ export async function namedProject(
       `${where} "${named.name}" at ${shown}: its package.json names it "${pkg.name ?? ''}"`,
     )
   }
-  return { name: named.name, dir, packageJson: pkg, configPath }
+  return withCatalogs({ name: named.name, dir, packageJson: pkg, configPath }, workspace)
+}
+
+function withCatalogs(meta: ProjectMeta, workspace: Workspace): ProjectMeta {
+  if (workspace.catalogs !== undefined) meta.catalogs = workspace.catalogs
+  return meta
 }