@vzn/vx-migrate 0.0.645 → 0.0.648

package/src/nx/nx-map.ts

@@ -20,12 +20,14 @@ import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { type Duration, type GeneratedProject, type GeneratedTask, UserError } from '@vzn/vx'
 import type { PackageMeta } from '../packages.js'
+import { refuseTaskNames } from '../plugin-gaps.js'
 import { withoutTakenBack } from '../glob-grammar.js'
 import { manifestGraph, type ManifestGraph } from '../manifest-graph.js'
 import { mapRunCommands, shellQuote } from '../nx-command.js'
-import { scriptCommand, yarnPnp } from '../script-command.js'
+import { type Owner, runsScriptHooks, scriptCommand, yarnPnp, yarnRun } from '../script-command.js'
 import {
   ownFileTakeBacks,
+  takingBack,
   excludeSiblingOutputs,
   excludeWorkspaceOutputs,
   resolveSharedOutputs,
@@ -274,6 +276,8 @@ type MapOpts = MapNxOptions & {
   /** The root TypeScript config Nx folds into every task's hash, if any. */
   readonly rootTsConfig: string | undefined
   readonly pnp: boolean
+  /** Whether the manager owning a directory runs `pre` / `post` hooks (`runsScriptHooks`). */
+  readonly hooks: (dir: string) => boolean
   /** Tasks per `syncGenerators` list, said once in the notes. */
   readonly syncTasks: Map<string, number>
 }
@@ -284,11 +288,20 @@ export interface NxMapping {
   readonly notes: string[]
 }
 
-/** A node's tags as vx takes them: a blank one would be refused at load. */
+/** A command that still runs Nx or Lerna (`nx-exec`, `nx-env`, `nx exec`, `lerna run`) or reads what they set. */
+const RUNS_NX = /(?:^|[\s;&|('"/])(?:nx(?:-exec|-env)?|lerna)\s|NX_TASK_TARGET_|LERNA_PACKAGE_NAME/
+
+/**
+ * A node's tags as vx takes them: a blank one would be refused at load, and
+ * `npm:public` / `npm:private` are Nx's own, read off package.json.
+ */
 function nxTags(node: NxNode | undefined): string[] {
   const tags = node?.data?.tags
   return Array.isArray(tags)
-    ? tags.filter((t): t is string => typeof t === 'string' && t.trim() !== '')
+    ? tags.filter(
+        (t): t is string =>
+          typeof t === 'string' && t.trim() !== '' && t !== 'npm:public' && t !== 'npm:private',
+      )
     : []
 }
 
@@ -316,6 +329,7 @@ export async function mapNxWorkspace(
   const g = graph
 
   const { namedInputs, cacheable, globalSync } = await readNxJsonFacts(root)
+  const hookMemo = new Map<string, Owner>()
   const mapOpts: MapOpts = {
     ...opts,
     cacheable: new Set([...opts.cacheable, ...cacheable]),
@@ -324,6 +338,7 @@ export async function mapNxWorkspace(
       existsSync(path.join(root, f)),
     ),
     pnp: yarnPnp(root),
+    hooks: (dir) => runsScriptHooks(dir, hookMemo) !== null,
     syncTasks: new Map(),
   }
 
@@ -353,6 +368,8 @@ export async function mapNxWorkspace(
     const relRoot = normRel(node?.data?.root ?? '')
     if (node?.data?.targets === undefined) continue
     const dir = relRoot === '' || relRoot === '.' ? root : path.join(root, relRoot)
+    const rel = path.relative(root, dir)
+    if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) continue
     let pkg: PackageMeta['packageJson'] = { name: nodeName }
     try {
       pkg = (await Bun.file(path.join(dir, 'package.json')).json()) as PackageMeta['packageJson']
@@ -377,7 +394,7 @@ export async function mapNxWorkspace(
     nodeNameOf.set(synthetic, nodeName)
   }
 
-  const upstream = planNxUpstream(nodeMap, g.dependencies, namedInputs, metaByNode)
+  const upstream = planNxUpstream(nodeMap, g.dependencies, namedInputs, metaByNode, opts.tracked)
 
   const taskNameFor: TaskNameFor = (project, target, configuration) => {
     const t = nodeMap[project]?.data?.targets?.[target]
@@ -481,7 +498,7 @@ export async function mapNxWorkspace(
     }
     mapped.push({ meta, tasks })
   }
-  // The `nx-input:<name>` twins the `^` inputs above asked for, in every
+  // The `inputs:<name>` twins the `^` inputs above asked for, in every
   // project a graph node owns — one with no targets too.
   const byMeta = new Map(mapped.map((m) => [m.meta, m]))
   for (const [nodeName, list] of upstream.inputTasks()) {
@@ -562,7 +579,7 @@ export async function mapNxWorkspace(
         )
         followNxGraph(t.task, nodeName, meta.name, nxEdges, metaByNode, emittedIds, reached)
       }
-      dropUnheldDeps(t, emitted, emittedIds)
+      dropUnheldDeps(t, meta.name, emitted, emittedIds)
       const reader = dependentReaders.get(t)
       if (reader !== undefined && !reachesProducer(t, meta.name, emittedIds, reached)) {
         delete t.task!['cache']
@@ -606,6 +623,7 @@ export async function mapNxWorkspace(
       `\`syncGenerators\` (${gens}) on ${n} task${n === 1 ? '' : 's'}: ` +
         `Nx runs them before those targets, and vx does not — ${syncAdvice}`,
     )
+  refuseTaskNames(projects, 'target')
   return { projects, notes }
 }
 
@@ -744,6 +762,7 @@ export async function readNxJsonFacts(root: string): Promise<NxJsonFacts> {
 
 function dropUnheldDeps(
   t: GeneratedTask,
+  owner: string,
   emitted: ReadonlySet<string>,
   emittedIds: ReadonlySet<string>,
 ): void {
@@ -757,7 +776,9 @@ function dropUnheldDeps(
     if (d.startsWith('^')) return emitted.has(d.slice(1))
     // `pkg#task` on a project no package holds (the root project with no
     // vx.config) refused the whole run as "no such project".
-    if (!d.includes('#') || emittedIds.has(d)) return true
+    // A same-project target written as no task (an `nx:noop` with nothing
+    // to chain) is nothing Nx runs; kept, `vx lock` refused the project.
+    if (emittedIds.has(d.includes('#') ? d : `${owner}#${d}`)) return true
     t.todos.push(
       `dependsOn ${JSON.stringify(d)}: no vx project runs it — edge dropped, and the key misses it`,
     )
@@ -813,6 +834,7 @@ function buildTask(
     todos,
     dotenv,
     opts.pnp,
+    opts.hooks(meta.dir),
     meta.packageJson,
     opts.manifestField,
     opts.executors,
@@ -827,6 +849,7 @@ function buildTask(
     rel: projectRel,
     name: projectName,
     outputs: nxProjectOutputs(nodeMap[nodeName]?.data?.targets, projectRel, projectName),
+    ...(opts.tracked === undefined ? {} : { tracked: opts.tracked }),
     rootDeps: opts.rootDeps,
   }
   expandNxInputs(target.inputs ?? [], upstream.namedOf(nodeName), at, inputs, todos)
@@ -855,7 +878,10 @@ function buildTask(
         patterns,
         Object.entries(nodeMap).map(([name, n]) => ({
           name,
-          tags: nxTags(n),
+          // Every tag Nx matches, its own `npm:*` too: nxTags is what vx writes.
+          tags: Array.isArray(n?.data?.tags)
+            ? n.data.tags.filter((t): t is string => typeof t === 'string')
+            : [],
           ...(typeof n?.data?.root === 'string' ? { root: n.data.root } : {}),
         })),
       ),
@@ -865,6 +891,12 @@ function buildTask(
       : { node: nodeName, configuration: variant.configuration! },
     options,
   )
+  // Nx draws no edge from a task to itself (`task.id !== selfTaskId`): a
+  // `projects: "*"` or a tag the project carries named it, and vx refused
+  // the workspace as a cycle (2026-10-28).
+  for (const own of [variant.name, `${meta.name}#${variant.name}`]) {
+    for (let i = deps.indexOf(own); i !== -1; i = deps.indexOf(own)) deps.splice(i, 1)
+  }
   // A nested `nx <target>` runs the target's default configuration, whatever this one runs.
   for (const c of mapped?.nxCalls ?? []) {
     const edge =
@@ -884,7 +916,7 @@ function buildTask(
   // vx cleans outputs before a run and Nx never does. With git's file list
   // known, a wildcard-first output (`**/*.d.ts`) stays cached: core never
   // cleans a committed file, so what the clean removes is what the task
-  // writes (owner, 2026-10-03). Without it, the sources cannot be told apart.
+  // writes (2026-10-03). Without it, the sources cannot be told apart.
   const wild =
     opts.tracked === undefined
       ? (wildcardOutput(outFiles) ?? wildcardOutput(wsOutFiles))
@@ -898,7 +930,7 @@ function buildTask(
   // saw nothing the task reads, and a changed document replayed the old
   // generated client (Growth, 2026-10-16).
   const orphanReader =
-    inputs.dependentOutputs.length > 0 && !deps.some((d) => !d.includes('#nx-input:'))
+    inputs.dependentOutputs.length > 0 && !deps.some((d) => !d.includes('#inputs:'))
   if (orphanReader && cacheWanted && !persistent) {
     todos.push(orphanReaderTodo(inputs.dependentOutputs, target.dependsOn))
   }
@@ -967,18 +999,24 @@ function buildTask(
   // `nx exec -- <cmd>`, a package script's way to run under Nx, reads it:
   // unset, it booted Nx's own task runner, which ran the target and its
   // dependencies again. `LERNA_PACKAGE_NAME` is the project too: Lerna
-  // runs on Nx's runner and documents it to scripts. A run-commands `env`
-  // still wins, as in Nx.
-  env.define = {
-    NX_TASK_TARGET_PROJECT: projectName,
-    NX_TASK_TARGET_TARGET: targetName,
-    LERNA_PACKAGE_NAME: projectName,
-    ...(variant.configuration === undefined
-      ? {}
-      : { NX_TASK_TARGET_CONFIGURATION: variant.configuration }),
+  // runs on Nx's runner and documents it to scripts. Only a command that
+  // still runs Nx or Lerna gets them: a native task names no other runner
+  // (2026-10-22). A run-commands `env` still wins, as in Nx.
+  const define = {
+    ...(RUNS_NX.test(mapped.command)
+      ? {
+          NX_TASK_TARGET_PROJECT: projectName,
+          NX_TASK_TARGET_TARGET: targetName,
+          LERNA_PACKAGE_NAME: projectName,
+          ...(variant.configuration === undefined
+            ? {}
+            : { NX_TASK_TARGET_CONFIGURATION: variant.configuration }),
+        }
+      : {}),
     ...mapped.env,
   }
-  exec.env = env
+  if (Object.keys(define).length > 0) env.define = define
+  if (Object.keys(env).length > 0) exec.env = env
   if (mapped.timeout !== undefined) exec.timeout = mapped.timeout
   if (readyWhen !== undefined) {
     exec.persistent = { readyWhen }
@@ -1005,8 +1043,8 @@ function buildTask(
   if (inputs.runtimeCmds.length > 0) keyed.workspaceRuntime = inputs.runtimeCmds
   task.inputs = keyed
   if (cacheEnabled) {
-    const outputs: Record<string, unknown> = { files: outFiles }
-    if (wsOutFiles.length > 0) outputs.workspaceFiles = wsOutFiles
+    const outputs: Record<string, unknown> = { files: takingBack(outFiles) }
+    if (wsOutFiles.length > 0) outputs.workspaceFiles = takingBack(wsOutFiles)
     task.cache = { outputs }
   }
 
@@ -1040,7 +1078,7 @@ function reachesProducer(
   if (!Array.isArray(deps)) return false
   return deps.some((d) => {
     if (typeof d !== 'string' || d.includes('*')) return true
-    if (d.includes('#nx-input:')) return false
+    if (d.includes('#inputs:')) return false
     if (d.startsWith('^'))
       return [...reached(project)].some((p) => emittedIds.has(`${p}#${d.slice(1)}`))
     return d.includes('#') || emittedIds.has(`${project}#${d}`)
@@ -1114,6 +1152,7 @@ function mapCommand(
   todos: string[],
   dotenv: readonly string[] | null,
   pnp: boolean,
+  hooks: boolean,
   manifest: { readonly name?: unknown; readonly version?: unknown },
   manifestField: MapNxOptions['manifestField'],
   executors: NxExecutors | undefined,
@@ -1184,10 +1223,11 @@ function mapCommand(
     // (novu's `test:watch: ""`, 2026-09-11); as a command it is a config
     // that refuses to load, so it is the placeholder with its todo.
     if (body !== undefined && body.length > 0) {
-      const command = scriptCommand(script, body, scripts, pnp)
+      // Nx runs `<pm> run <script>`: the hooks fold only where the manager runs them.
+      const command = scriptCommand(script, body, scripts, pnp, hooks)
       // `yarn run <name>` sets its own.
       const env =
-        command === `yarn run ${script}`
+        command === yarnRun(script)
           ? {}
           : npmScriptEnv(command, script, command !== body, manifest, manifestField, todos)
       return shell(command, undefined, { env, readyWhen: undefined })

package/src/nx/nx-outputs.ts

@@ -3,7 +3,7 @@
 
 import path from 'node:path'
 import { isLiteralPattern } from '@vzn/vx'
-import { literalGlob, minimatchToVx } from '../glob-grammar.js'
+import { gluedGlobstarAsStar, literalGlob, minimatchToVx, nxBareGroups } from '../glob-grammar.js'
 import { takingBack } from '../shared-outputs.js'
 
 interface NxOutputs {
@@ -59,11 +59,19 @@ export function withProjectDir(p: string, projectRel: string, asGlob: boolean):
   })
 }
 
-/** A workspace path relative to the project dir, or null when it lies outside. */
+/**
+ * A workspace path relative to the project dir, or null when it lies
+ * outside; `''` is the project dir itself, which Nx reads as the whole tree
+ * (`path_or_everything_under`). As a workspace path, `{projectRoot}` cached
+ * a literal core reads as another project's, and `{projectRoot}/` the empty
+ * path, which saved and keyed nothing.
+ */
 export function underProject(p: string, projectRel: string): string | null {
   if (projectRel === '.' || projectRel === '') return p
-  for (const dir of [masked(projectRel), projectRel])
-    if (p.startsWith(`${dir}/`)) return p.slice(dir.length + 1)
+  for (const dir of [masked(projectRel), projectRel]) {
+    if (p === dir) return ''
+    if (p.startsWith(`${dir}/`)) return p.slice(dir.length + 1).replace(/\/+$/, '')
+  }
   return null
 }
 
@@ -191,7 +199,7 @@ export function mapNxOutputs(
       const gs = g.slice(gn.length)
       const own = underProject(gs, projectRel)
       if (own !== null) {
-        outFiles.push(gn + withProjectDir(own, projectRel, true))
+        outFiles.push(gn + (own === '' ? '**' : withProjectDir(own, projectRel, true)))
         continue
       }
       const m = path.posix.normalize(gs).replace(/^\.\//, '')
@@ -215,7 +223,9 @@ export function mapNxOutputs(
  */
 function vxOutputGlobs(o: string): string[] | null {
   const negated = o.startsWith('!')
-  const segs = o.slice(negated ? 1 : 0).split('/')
+  const bare = nxBareGroups(o.slice(negated ? 1 : 0))
+  if (bare === null) return null
+  const segs = gluedGlobstarAsStar(bare).split('/')
   const at = segs.findIndex((seg) => /^!\([^()|{},]+(\|[^()|{},]+)*\)$/.test(seg))
   if (at !== -1) {
     if (negated) return null

package/src/nx/nx-upstream.ts

@@ -2,7 +2,7 @@
 // dependency's `name` input for every project the graph reaches, whether or
 // not a task edge exists, so a `test` with `^production` and no `dependsOn`
 // re-keys on a dependency's source. vx folds upstream KEYS along
-// `dependsOn`, so each project gets one `nx-input:<name>` task — a keyed
+// `dependsOn`, so each project gets one `inputs:<name>` task — a keyed
 // group, keyed on the project's own `name` input — with an edge to its
 // dependencies' twin. A task that reads `^name` depends on its direct
 // dependencies' twins and folds the whole closure through them: each
@@ -11,13 +11,14 @@
 //
 // The edges are the NX graph's, not vx's package graph (`^` in vx follows
 // package.json, and an Nx edge from a tsconfig path has no manifest entry),
-// so they are explicit `pkg#nx-input:<name>`. A graph node with no vx
+// so they are explicit `pkg#inputs:<name>`. A graph node with no vx
 // project is transparent: its files join as workspace globs and the walk
 // goes on through it. Nx allows a project cycle and vx's task graph does
 // not: inside a cycle a twin carries its peers' files as workspace globs
 // and edges only out of the cycle.
 import type { GeneratedTask } from '@vzn/vx'
 import type { PackageMeta } from '../packages.js'
+import type { TrackedKinds } from '../tracked-outputs.js'
 import { emptyNxInputs, expandNxInputs, type NxInputs } from './nx-inputs.js'
 import { nxProjectOutputs } from './nx-outputs.js'
 import { matchNxProjects } from './nx-deps.js'
@@ -47,8 +48,8 @@ const isFileset = (name: string): boolean =>
 /** A fileset twin is named by its hash: a glob's `*` is no task name. */
 const inputTask = (name: string): string =>
   isFileset(name)
-    ? `nx-input:fileset-${Bun.hash.xxHash3(name).toString(16).padStart(16, '0')}`
-    : `nx-input:${name}`
+    ? `inputs:fileset-${Bun.hash.xxHash3(name).toString(16).padStart(16, '0')}`
+    : `inputs:${name}`
 
 function normRel(p: string): string {
   const s = p.replace(/\/+$/, '')
@@ -63,7 +64,7 @@ export interface NxUpstream {
    * needs, with a transparent node's files added to `into`.
    */
   resolve(node: string, into: NxInputs, todos: string[]): string[]
-  /** Each project's `nx-input:<name>` tasks, for every twin an edge reaches. */
+  /** Each project's `inputs:<name>` tasks, for every twin an edge reaches. */
   inputTasks(): Map<string, GeneratedTask[]>
 }
 
@@ -72,6 +73,7 @@ export function planNxUpstream(
   dependencies: unknown,
   workspaceNamed: Readonly<Record<string, unknown[]>> | null,
   metaByNode: ReadonlyMap<string, PackageMeta>,
+  tracked?: (rel: string) => TrackedKinds,
 ): NxUpstream {
   const isProject = (n: string): boolean => typeof nodes[n]?.data?.root === 'string'
   const projectTags = Object.entries(nodes).map(([name, n]) => ({
@@ -221,6 +223,7 @@ export function planNxUpstream(
       rel,
       name: nm,
       outputs: nxProjectOutputs(nodes[node]?.data?.targets, rel || '.', nm),
+      ...(tracked === undefined ? {} : { tracked }),
     }
     expandNxInputs([name], namedOf(node), at, into, todos)
   }
@@ -289,6 +292,7 @@ export function planNxUpstream(
     into: NxInputs,
     todos: string[],
     edges: Set<string>,
+    depsOf = false,
   ): void => {
     // Nx reads the list as `dependsOn`'s `projects` (`findMatchingProjects`):
     // `*` patterns, `tag:` and `!` exclusions. Looked up as names, a
@@ -302,6 +306,10 @@ export function planNxUpstream(
     for (const p of literal)
       todos.push(`input project ${JSON.stringify(p)} is not a graph node — map manually`)
     for (const p of matchNxProjects(of, projectTags)) {
+      if (depsOf) {
+        fold(p, name, new Set(), into, todos, edges)
+        continue
+      }
       const u = { name }
       const meta = metaByNode.get(p)
       if (meta !== undefined) {
@@ -319,7 +327,7 @@ export function planNxUpstream(
     const edges = new Set<string>()
     for (const u of into.upstream) {
       if (u.of === 'deps') fold(node, u.name, new Set(), into, todos, edges)
-      else foldProjects(u.name, u.of, into, todos, edges)
+      else foldProjects(u.name, u.of, into, todos, edges, u.depsOf)
     }
     return [...edges]
   }
@@ -337,7 +345,7 @@ export function planNxUpstream(
       fold(node, name, peers, inputs, todos, edges)
       // A nested `^other` in this project's `name` input.
       for (const u of inputs.upstream) {
-        if (u.of !== 'deps') foldProjects(u.name, u.of, inputs, todos, edges)
+        if (u.of !== 'deps') foldProjects(u.name, u.of, inputs, todos, edges, u.depsOf)
         else if (u.name !== name) fold(node, u.name, peers, inputs, todos, edges)
       }
       // Nx hashes a fileset that matches nothing as nothing; core warns of

package/src/nx-cache/index.ts

@@ -17,9 +17,12 @@ import {
   type RemoteOpenContext,
   type VxPlugin,
   refuseUnknownOptions,
+  UserError,
   type PluginOptionKinds,
 } from '@vzn/vx'
-import { deadline } from '../remote-deadline.js'
+import { deadline, MAX_TIMER_MS } from '../remote-deadline.js'
+import { checkRemoteUrl } from '../remote-url.js'
+import { refusal } from '../remote-refusal.js'
 import { OutageBreaker } from '../remote-breaker.js'
 import { Cooldown, withRetry } from '../remote-retry.js'
 import {
@@ -31,13 +34,13 @@ import {
 
 export interface NxCacheOptions {
   /** Base URL of the cache server, or `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`. */
-  server?: string
+  url?: string
   /**
    * Bearer token, or `NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN`, then the OS
    * keychain. `''` (option or variable) is a server that runs open: no
    * token, nothing asked.
    */
-  accessToken?: string
+  token?: string
   /** Per-request deadline (default 30 s). */
   timeoutMs?: number
   /** Resends of a request answered 429 / 5xx or never connected (default 1); 0 turns them off. */
@@ -45,9 +48,9 @@ export interface NxCacheOptions {
 }
 
 export interface NxCacheConfig {
-  server: string
+  url: string
   /** Undefined: the layer's `open` asks the OS keychain; `''`: an open server. */
-  accessToken?: string
+  token?: string
   timeoutMs: number
   retries: number
 }
@@ -57,36 +60,22 @@ export function resolveNxCacheConfig(
   options: NxCacheOptions,
   env: Record<string, string | undefined> = Bun.env,
 ): NxCacheConfig | undefined {
-  const server = (options.server ?? env['NX_SELF_HOSTED_REMOTE_CACHE_SERVER'])?.replace(/\/+$/, '')
-  if (!server) return undefined
-  // The URL is printed in every refusal line, so a `user:pass@` in it would
-  // leak to the log. Credentials go in the access token.
-  if (URL.canParse(server)) {
-    const u = new URL(server)
-    if (u.username !== '' || u.password !== '')
-      throw new Error(
-        'vx/nx-cache: server carries credentials (user:pass@); pass them as the accessToken instead',
-      )
-  }
-  const accessToken = options.accessToken ?? env['NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN']
-  const fault = accessToken === undefined ? null : headerValueFault(accessToken)
+  // Named by its source: the env's was refused as a `url` option.
+  const from =
+    options.url !== undefined ? 'nxCache() option "url"' : 'NX_SELF_HOSTED_REMOTE_CACHE_SERVER'
+  const url = (options.url ?? env['NX_SELF_HOSTED_REMOTE_CACHE_SERVER'])?.replace(/\/+$/, '')
+  if (!url) return undefined
+  checkRemoteUrl(url, from)
+  const token = options.token ?? env['NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN']
+  const fault = token === undefined ? null : headerValueFault(token)
   if (fault !== null)
     throw new Error(
-      `vx/nx-cache: the access token holds ${fault}, which no HTTP header can carry — check the secret (it is not printed)`,
+      `nxCache(): the access token holds ${fault}, which no HTTP header can carry — check the secret (it is not printed)`,
     )
   const retries = options.retries ?? 1
-  // A NaN never reaches the bound, and the request would be resent forever.
-  if (!Number.isInteger(retries) || retries < 0)
-    throw new Error(`vx/nx-cache: retries must be a whole number ≥ 0, got ${retries}`)
-  // A zero timeout aborted every request as it started.
-  const ms = options.timeoutMs
-  if (ms !== undefined && !(typeof ms === 'number' && Number.isFinite(ms) && ms > 0))
-    throw new Error(
-      `vx/nx-cache: timeoutMs must be a positive number of ms, got ${JSON.stringify(ms)}`,
-    )
   return {
-    server,
-    ...(accessToken !== undefined ? { accessToken } : {}),
+    url,
+    ...(token !== undefined ? { token } : {}),
     timeoutMs: options.timeoutMs ?? 30_000,
     retries,
   }
@@ -98,7 +87,7 @@ export function resolveNxCacheConfig(
  * the prefetch pass calls `get`) is a GET whose body is cancelled before
  * it answers, so no probe holds a connection. It kept the response for a
  * `get` of the same hash, which no caller makes. Bodies stream: `get` returns the `fetch` Response and `put`
- * sends the Blob core hands it. `put` treats `409` as success:
+ * sends the Blob core hands it. `put` treats any 2xx and `409` as success:
  * the record is immutable and content-addressed, so "already there" is the
  * outcome wanted. An auth failure (401/403) throws ONCE — core
  * reports it — and then turns the layer off for the rest of the process
@@ -129,11 +118,11 @@ export class NxRemoteCache implements RemoteCacheLayer {
     private readonly fetchImpl: typeof fetch = fetch,
     private readonly wait: (ms: number) => Promise<void> = Bun.sleep,
   ) {
-    this.endpoint = `${config.server}/v1/cache`
-    this.token = config.accessToken
+    this.endpoint = `${config.url}/v1/cache`
+    this.token = config.token
     this.keychainRemote = {
       key: this.endpoint,
-      label: remoteLabel(config.server, undefined),
+      label: remoteLabel(config.url, undefined),
       env: 'NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN',
     }
   }
@@ -171,7 +160,7 @@ export class NxRemoteCache implements RemoteCacheLayer {
       () =>
         withRetry(
           () =>
-            this.fetchImpl(`${this.config.server}/v1/cache/${hash}`, {
+            this.fetchImpl(`${this.config.url}/v1/cache/${hash}`, {
               method,
               headers,
               ...(body === undefined ? {} : { body }),
@@ -187,23 +176,25 @@ export class NxRemoteCache implements RemoteCacheLayer {
       const first = !this.writesRefused
       this.writesRefused = true
       if (!first) return undefined
+      // The status and the server's own words, as turboCache() says them.
       throw new Error(
-        'HTTP 403: access forbidden (a read-only token cannot write); uploads off for this run, reads go on',
+        `${(await refusal(res)).message}: access forbidden (a read-only token cannot write); uploads off for this run, reads go on`,
       )
     }
     if (res.status === 401 || res.status === 403) {
       const first = !this.disabled
       this.disabled = true
       if (!first) return undefined
+      const said = (await refusal(res)).message
       const why =
         res.status === 401
           ? 'missing or invalid token'
           : 'access forbidden (the token may not read)'
       if (this.forget === undefined)
-        throw new Error(`HTTP ${res.status}: ${why}; remote cache off for this run`)
+        throw new Error(`${said}: ${why}; remote cache off for this run`)
       await this.forget()
       throw new Error(
-        `HTTP ${res.status}: ${why}; removed it from the OS keychain, so the next run asks again; remote cache off for this run`,
+        `${said}: ${why}; removed it from the OS keychain, so the next run asks again; remote cache off for this run`,
       )
     }
     return res
@@ -220,9 +211,11 @@ export class NxRemoteCache implements RemoteCacheLayer {
     const res = await this.request('GET', hash)
     if (res === undefined) return null
     if (res.status !== 200) {
-      await res.body?.cancel()
-      if (res.status === 404) return null
-      throw new Error(`HTTP ${res.status}`)
+      if (res.status === 404) {
+        await res.body?.cancel()
+        return null
+      }
+      throw await refusal(res)
     }
     return res
   }
@@ -236,19 +229,21 @@ export class NxRemoteCache implements RemoteCacheLayer {
   }
 
   // Nx's record carries no duration.
-  async put(hash: string, body: Blob): Promise<void> {
-    if (this.disabled || this.writesRefused) return
+  async put(hash: string, body: Blob): Promise<void | false> {
+    // Nothing sent, so no upload is counted.
+    if (this.disabled || this.writesRefused) return false
     const res = await this.request('PUT', hash, body)
-    if (res === undefined) return
-    if (res.status === 200 || res.status === 202 || res.status === 409) return
-    throw new Error(`HTTP ${res.status}`)
+    if (res === undefined) return false
+    // The spec answers 200; a store behind it may say 201 or 204.
+    if (res.ok || res.status === 409) return
+    throw await refusal(res)
   }
 }
 
 /** Each option `NxCacheOptions` names, with its kind: derived from the type, so the two cannot drift. */
 const NX_CACHE_KEYS: PluginOptionKinds<NxCacheOptions> = {
-  server: 'string',
-  accessToken: 'string',
+  url: 'string',
+  token: 'string',
   timeoutMs: 'number',
   retries: 'number',
 }
@@ -257,13 +252,28 @@ const NX_CACHE_KEYS: PluginOptionKinds<NxCacheOptions> = {
  * Declare in `.vx/workspace.ts`; the local store stays the floor beneath it:
  *
  * ```ts
- * plugins: [nxCache({ server: 'https://cache.example.com', accessToken: process.env.CACHE_TOKEN })]
+ * plugins: [nxCache({ url: 'https://cache.example.com', token: process.env.CACHE_TOKEN })]
  * ```
  *
- * Declines without a server, so it is safe to leave declared.
+ * Declines without a url, so it is safe to leave declared.
  */
 export function nxCache(options: NxCacheOptions = {}): VxPlugin {
   refuseUnknownOptions('nxCache()', options, NX_CACHE_KEYS)
+  // At the call: in the `cache` hook a laptop with no server named passed
+  // what failed the first CI run. A NaN never reaches the bound, and the
+  // request would be resent forever; a zero timeout, or one past the longest
+  // timer, aborted every request as it started.
+  const { retries, timeoutMs: ms } = options
+  if (retries !== undefined && !(Number.isInteger(retries) && retries >= 0))
+    throw new UserError(`nxCache() option "retries" must be a whole number ≥ 0, got ${retries}`)
+  if (ms !== undefined && !(ms > 0 && ms <= MAX_TIMER_MS))
+    throw new UserError(
+      `nxCache() option "timeoutMs" must be a positive number of ms up to ${MAX_TIMER_MS}, got ${ms}`,
+    )
+  // At the call too, as vxCache() checks its url: in the hook alone, a verb
+  // that opens no cache (`vx show`) took a url every run then failed on.
+  const url = options.url?.replace(/\/+$/, '')
+  if (url) checkRemoteUrl(url, 'nxCache() option "url"')
   return definePlugin(import.meta, {
     cache(): RemoteCacheLayer | undefined {
       const config = resolveNxCacheConfig(options)

package/src/nx-exec.cjs

@@ -133,7 +133,7 @@ async function loadGraph(nx, project) {
   }
   // A cache written before the project existed (one added since Nx last
   // ran) is stale: \`nx run\` computes the graph and finds it, so compute.
-  if (graph === null || graph.nodes[project] === undefined) {
+  if (graph === null || !Object.hasOwn(graph.nodes, project)) {
     graph = unwrapGraph(await pg.createProjectGraphAsync({ exitOnError: false }))
   }
   if (graph === null) throw new Error('nx produced a project graph with no nodes')
@@ -168,7 +168,7 @@ async function main(argv) {
   loadTaskEnv(nx, process.env, args.dotenv, undefined)
 
   const { graph, pg } = await loadGraph(nx, args.project)
-  const node = graph.nodes[args.project]
+  const node = Object.hasOwn(graph.nodes, args.project) ? graph.nodes[args.project] : undefined
   if (node === undefined) {
     process.stderr.write(
       `nx-exec: no project ${JSON.stringify(args.project)} in the Nx project graph\n`,