@vzn/vx-migrate 0.0.0 → 0.0.485

package/src/nx-dotenv.cjs

@@ -0,0 +1,41 @@
+// Nx's per-task `.env` loading for the two bins that run Nx targets —
+// `nx-exec` (an executor, in its own process) and `nx-env` (a shell line) —
+// through Nx's own `loadAndExpandDotEnvFile` / `unloadDotEnvFile`
+// (tasks-runner/task-env.ts), so the parsing, `${VAR}` expansion and
+// precedence are the workspace's Nx version's, not a copy's.
+//
+// Which files: the mapper lists the ones that exist, in Nx's order
+// (`getEnvPathsForTask`), relative to the task's working directory. What
+// Nx does with them: the first file to define a name wins, and a name the
+// environment already holds wins over every file — which under vx is the
+// isolated task env, so the target's `env` (exec.env.define) stays on top
+// as in Nx. Nx first UNLOADS the root files it loaded into its own process
+// at start-up; nothing loaded them here, so there is nothing to unload.
+
+'use strict'
+
+const path = require('node:path')
+
+/**
+ * Loads `files` into `env`, then run-commands' `envFile`, which Nx loads
+ * over the result the same way (a name already set wins) and whose
+ * unreadable file fails the task.
+ */
+function loadTaskEnv(nx, env, files, envFile) {
+  if (files.length === 0 && envFile === undefined) return
+  const { loadAndExpandDotEnvFile, unloadDotEnvFile } = nx('nx/src/tasks-runner/task-env')
+  if (files.length > 0) {
+    loadAndExpandDotEnvFile(
+      files.map((f) => path.resolve(f)),
+      env,
+    )
+  }
+  if (envFile !== undefined) {
+    const file = path.resolve(envFile)
+    unloadDotEnvFile(file, env)
+    const result = loadAndExpandDotEnvFile(file, env)
+    if (result && result.error) throw result.error
+  }
+}
+
+module.exports = { loadTaskEnv }

package/src/nx-env.cjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// `nx-env [--dotenv <file>]... [--envFile <file>] [--ready-when <string>]... -- <command> [args…]`
+//
+// A shell line with the `.env` files Nx gives the task it came from: what
+// `nx()` and the migrator wrap an `nx:run-commands` or `nx:run-script` line
+// in when the task has any (nx-dotenv.cjs has the rules). The command runs
+// as `sh -c`, with whatever follows it appended quoted — exactly what vx
+// appends to a line after `vx run … --` — so the line is the same one it
+// would be unwrapped.
+//
+// `--ready-when`, repeated: a run-commands target's several `readyWhen`
+// strings. Nx is ready once every one has appeared in the output, stdout
+// or stderr; vx's `readyWhen` is one pattern matched per line. So the
+// child's streams pass through unchanged, separately, and once all the
+// strings have been seen this prints one line, READY, which is the task's
+// `readyWhen`. (Nx's `isReady` marks at most one string per output chunk,
+// so two arriving together in a last chunk never made it ready; here each
+// counts.)
+//
+// Node and CommonJS for the reason `nx-exec` is: the loading is Nx's own,
+// resolved from the working directory up to the workspace's `nx`.
+
+'use strict'
+
+const { spawn, spawnSync } = require('node:child_process')
+const { createRequire } = require('node:module')
+const path = require('node:path')
+const { loadTaskEnv } = require('./nx-dotenv.cjs')
+
+// `--envFile`, Nx's own option name, and not `--env-file`: Node 22 takes
+// `--env-file` from anywhere on its command line, the script's arguments
+// included, and exits 9 when the file is missing.
+const USAGE =
+  'usage: nx-env [--dotenv <file>]... [--envFile <file>] [--ready-when <string>]... -- <command> [args…]'
+
+/** The line printed once every `--ready-when` string has been seen. */
+const READY = 'nx-env: ready'
+
+/** vx's own quoting for an appended argument (runner.ts `shellQuote`). */
+function shellQuote(arg) {
+  if (arg === '') return "''"
+  if (/^[A-Za-z0-9_\-.,/=:@%+]+$/.test(arg)) return arg
+  return `'${arg.replace(/'/g, "'\\''")}'`
+}
+
+function parseArgs(argv) {
+  const out = { dotenv: [], envFile: undefined, readyWhen: [], command: undefined, args: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--') {
+      out.command = argv[i + 1]
+      out.args = argv.slice(i + 2)
+      break
+    }
+    if (a === '--help' || a === '-h') return { help: true }
+    const value = argv[i + 1]
+    if ((a === '--dotenv' || a === '--envFile' || a === '--ready-when') && value !== undefined) {
+      if (a === '--dotenv') out.dotenv.push(value)
+      else if (a === '--ready-when') out.readyWhen.push(value)
+      else out.envFile = value
+      i++
+      continue
+    }
+    return { error: `unexpected ${JSON.stringify(a)}\n${USAGE}` }
+  }
+  if (out.command === undefined) return { error: `no command after --\n${USAGE}` }
+  return out
+}
+
+/**
+ * Runs `line` with the streams piped through, printing READY once every
+ * string has been seen in them; resolves with the shell's exit.
+ */
+function runWatched(line, env, strings) {
+  return new Promise((resolve) => {
+    const child = spawn('sh', ['-c', line], { stdio: ['inherit', 'pipe', 'pipe'], env })
+    const missing = new Set(strings)
+    const longest = Math.max(...strings.map((s) => s.length))
+    const watch = (stream, out) => {
+      // A string split across two chunks is still seen: the tail carries over.
+      let tail = ''
+      stream.on('data', (chunk) => {
+        out.write(chunk)
+        if (missing.size === 0) return
+        const text = tail + chunk.toString()
+        for (const s of [...missing]) if (text.includes(s)) missing.delete(s)
+        tail = text.slice(-longest)
+        if (missing.size === 0) process.stdout.write(`${READY}\n`)
+      })
+    }
+    watch(child.stdout, process.stdout)
+    watch(child.stderr, process.stderr)
+    child.on('error', (err) => {
+      process.stderr.write(`nx-env: ${err.message}\n`)
+      resolve(1)
+    })
+    child.on('close', (code, signal) => {
+      if (signal) resolve(128 + (require('node:os').constants.signals[signal] ?? 2))
+      else resolve(code ?? 1)
+    })
+  })
+}
+
+async function main(argv) {
+  const args = parseArgs(argv)
+  if (args.help) {
+    process.stdout.write(`${USAGE}\n`)
+    return 0
+  }
+  if (args.error) {
+    process.stderr.write(`nx-env: ${args.error}\n`)
+    return 2
+  }
+  const req = createRequire(path.join(process.cwd(), 'package.json'))
+  try {
+    req.resolve('nx/package.json')
+  } catch {
+    process.stderr.write(
+      `nx-env: cannot resolve \`nx\` from ${process.cwd()} — is it installed in this workspace?\n`,
+    )
+    return 1
+  }
+  const env = { ...process.env }
+  try {
+    loadTaskEnv((spec) => req(spec), env, args.dotenv, args.envFile)
+  } catch (err) {
+    process.stderr.write(`nx-env: ${err && err.message ? err.message : String(err)}\n`)
+    return 1
+  }
+  const line = [args.command, ...args.args.map(shellQuote)].join(' ')
+  // The task's process group gets vx's signals, the shell included; this
+  // process waits for the shell and reports its end rather than dying first.
+  for (const s of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(s, () => {})
+  if (args.readyWhen.length > 0) return runWatched(line, env, args.readyWhen)
+  const r = spawnSync('sh', ['-c', line], { stdio: 'inherit', env })
+  if (r.error) {
+    process.stderr.write(`nx-env: ${r.error.message}\n`)
+    return 1
+  }
+  if (r.signal) return 128 + (require('node:os').constants.signals[r.signal] ?? 2)
+  return r.status ?? 1
+}
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code
+  },
+  (err) => {
+    process.stderr.write(`nx-env: ${err && err.message ? err.message : String(err)}\n`)
+    process.exitCode = 1
+  },
+)

package/src/nx-exec.cjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// `nx-exec <executor> --project <p> --target <t> [--configuration <c>] --options '<json>'
+//   [--dotenv <file>]... [overrides…]`
+//
+// One Nx executor as one process, through Nx's own public `runExecutor`
+// (design: docs/design/nx-unchanged-2026-09.md). The command line carries
+// the executor and its options, so vx's key sees them and `vx show` prints
+// what runs; the workspace's cached project graph only supplies the
+// `ExecutorContext` executors read (project root, dependencies). The
+// target in the in-memory graph is REPLACED by the command line, so what
+// runs is what the command says, never what project.json says today.
+//
+// Node, not Bun, and CommonJS on purpose: the executor runs in this
+// process, and executors are Node programs (`@nx/nx-<platform>` native
+// binding, jest workers). `nx` resolves from the working directory — the
+// project dir vx runs every task in — up to the workspace's node_modules.
+// Deep `nx/src` imports over the `@nx/devkit` barrel: 50 ms less per
+// task, and a workspace with only `nx` and custom executors has no devkit.
+
+'use strict'
+
+const { createRequire, enableCompileCache } = require('node:module')
+const path = require('node:path')
+const { loadTaskEnv } = require('./nx-dotenv.cjs')
+
+// Nx's module graph is ~150 ms of every executed task; Node's on-disk
+// compile cache (22.1+, a no-op below) takes ~30 of them back on the
+// second task, under os.tmpdir() by default, with nothing in a key.
+if (typeof enableCompileCache === 'function') {
+  try {
+    enableCompileCache()
+  } catch {
+    // A read-only temp dir just means no cache.
+  }
+}
+
+const USAGE =
+  "usage: nx-exec <executor> --project <name> --target <name> [--configuration <name>] [--options '<json>'] [--dotenv <file>]... [overrides…]"
+
+/** The flags that are nx-exec's own, each taken once but `--dotenv`; everything else is Nx's. */
+const OWN = new Set(['project', 'target', 'configuration', 'options', 'dotenv'])
+
+/**
+ * Parsed argv, or `{ error }` — a usage error is exit 2, before Nx is loaded.
+ * Every token that is not the executor or the first of an own flag is an
+ * OVERRIDE, kept verbatim for Nx to parse: what `vx run … -- --otp=123`
+ * appends to the line is what `nx run p:t --otp=123` gives the executor,
+ * where it used to be a usage error (nx#12165).
+ */
+function parseArgs(argv) {
+  const out = {
+    executor: undefined,
+    project: undefined,
+    target: undefined,
+    configuration: undefined,
+    options: {},
+    dotenv: [],
+    overrides: [],
+  }
+  const seen = new Set()
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h') return { help: true }
+    if (!a.startsWith('--')) {
+      if (out.executor === undefined) out.executor = a
+      else out.overrides.push(a)
+      continue
+    }
+    const eq = a.indexOf('=')
+    const name = eq === -1 ? a.slice(2) : a.slice(2, eq)
+    if (!OWN.has(name) || seen.has(name)) {
+      out.overrides.push(a)
+      continue
+    }
+    if (name !== 'dotenv') seen.add(name)
+    const value = eq === -1 ? argv[++i] : a.slice(eq + 1)
+    if (value === undefined) return { error: `--${name} needs a value\n${USAGE}` }
+    if (name === 'dotenv') out.dotenv.push(value)
+    else if (name === 'options') {
+      try {
+        out.options = JSON.parse(value)
+      } catch (err) {
+        return { error: `--options is not JSON: ${err.message}` }
+      }
+      if (typeof out.options !== 'object' || out.options === null || Array.isArray(out.options)) {
+        return { error: '--options must be a JSON object' }
+      }
+    } else out[name] = value
+  }
+  if (out.executor === undefined) return { error: `expected one executor (got 0)\n${USAGE}` }
+  if (!out.executor.includes(':')) {
+    return { error: `executor must be <package>:<name>, got ${JSON.stringify(out.executor)}` }
+  }
+  for (const f of ['project', 'target']) {
+    if (out[f] === undefined || out[f] === '') return { error: `--${f} is required\n${USAGE}` }
+  }
+  return out
+}
+
+/** Both shapes a graph file takes: Nx's cache (`{ nodes, … }`) and `nx graph --file` (`{ graph: { nodes, … } }`). */
+function unwrapGraph(g) {
+  const inner = g && typeof g === 'object' && g.graph && typeof g.graph === 'object' ? g.graph : g
+  if (
+    !inner ||
+    typeof inner !== 'object' ||
+    typeof inner.nodes !== 'object' ||
+    inner.nodes === null
+  ) {
+    return null
+  }
+  if (inner.externalNodes === undefined) inner.externalNodes = {}
+  if (inner.dependencies === undefined) inner.dependencies = {}
+  return inner
+}
+
+/**
+ * The cached graph, or a fresh one when the cache is missing, unreadable or
+ * lacks the project.
+ * The daemon is never dialed: NX_DAEMON is off for this process before `nx`
+ * loads, so the fallback computes in-process — slow, bounded, and it writes
+ * Nx's cache for the next task.
+ */
+async function loadGraph(nx, project) {
+  const pg = nx('nx/src/project-graph/project-graph')
+  let graph = null
+  try {
+    graph = unwrapGraph(pg.readCachedProjectGraph())
+  } catch {
+    // No cache, or a shape the reader did not understand: compute below.
+  }
+  // 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) {
+    graph = unwrapGraph(await pg.createProjectGraphAsync({ exitOnError: false }))
+  }
+  if (graph === null) throw new Error('nx produced a project graph with no nodes')
+  return { graph, pg }
+}
+
+async function main(argv) {
+  const args = parseArgs(argv)
+  if (args.help) {
+    process.stdout.write(`${USAGE}\n`)
+    return 0
+  }
+  if (args.error) {
+    process.stderr.write(`nx-exec: ${args.error}\n`)
+    return 2
+  }
+  if (process.env.NX_DAEMON === undefined) process.env.NX_DAEMON = 'false'
+
+  const req = createRequire(path.join(process.cwd(), 'package.json'))
+  let nx
+  try {
+    req.resolve('nx/package.json')
+    nx = (spec) => req(spec)
+  } catch {
+    process.stderr.write(
+      `nx-exec: cannot resolve \`nx\` from ${process.cwd()} — is it installed in this workspace?\n`,
+    )
+    return 1
+  }
+  // Before anything reads the environment: the executor runs in this
+  // process, so the task's `.env` files (nx-dotenv.cjs) are its env.
+  loadTaskEnv(nx, process.env, args.dotenv, undefined)
+
+  const { graph, pg } = await loadGraph(nx, args.project)
+  const node = graph.nodes[args.project]
+  if (node === undefined) {
+    process.stderr.write(
+      `nx-exec: no project ${JSON.stringify(args.project)} in the Nx project graph\n`,
+    )
+    return 1
+  }
+  const target = { executor: args.executor, options: args.options }
+  // The options are already the configuration's, flattened by whoever wrote
+  // the command; the name is passed so an executor reading
+  // `context.configurationName` sees it, and Nx's merge finds it declared.
+  if (args.configuration !== undefined) target.configurations = { [args.configuration]: {} }
+  node.data = { ...node.data, targets: { ...node.data?.targets, [args.target]: target } }
+
+  const { readNxJson } = nx('nx/src/config/nx-json')
+  const { runExecutor } = nx('nx/src/command-line/run/run')
+  const { workspaceRoot } = nx('nx/src/utils/workspace-root')
+  // Nx forks an executor in the directory Nx was started from, the
+  // workspace root in CI (`forked-process-task-runner`); vx starts a task in
+  // its project dir. An executor that resolves against `process.cwd()`
+  // (@nx/js's ts transformers, prettier's config) read the project dir.
+  // The `.env` files above are already loaded from it.
+  process.chdir(workspaceRoot)
+  const context = {
+    root: workspaceRoot,
+    cwd: workspaceRoot,
+    isVerbose: process.env.NX_VERBOSE_LOGGING === 'true',
+    projectName: args.project,
+    targetName: args.target,
+    configurationName: args.configuration,
+    projectGraph: graph,
+    projectsConfigurations: pg.readProjectsConfigurationFromProjectGraph(graph),
+    nxJsonConfiguration: readNxJson(workspaceRoot),
+  }
+  // An executor yields once per result and a server yields for as long as it
+  // runs; the exit is the LAST result's, as `nx run` reports it.
+  const description = { project: args.project, target: args.target }
+  if (args.configuration !== undefined) description.configuration = args.configuration
+  // Parsed by Nx itself, as `nx run` parses what follows the target. Loaded
+  // only when there is something to parse: the module pulls in git helpers.
+  // `runExecutor` derives the unparsed list from the parsed overrides, so the
+  // parser's own copy is dropped — kept, it was serialized back as a flag,
+  // `--__overrides_unparsed__=--otp=123`, and handed to the executor. The
+  // derived list puts positional words first, where `nx run` keeps them in
+  // the order typed.
+  let overrides = {}
+  if (args.overrides.length > 0) {
+    const { createOverrides } = nx('nx/src/utils/command-line-utils')
+    const { __overrides_unparsed__: _raw, ...parsed } = createOverrides(args.overrides)
+    overrides = parsed
+  }
+  // As `nx run` reads it (`getLastValueFromAsyncIterableIterator`): the
+  // generator's RETURN value when it has one, else the last yield. A
+  // `for await` drops the return: an executor that only returns
+  // `{ success: true }` exited 1, and a server that yields success and
+  // returns failure when it dies (@nx/web:file-server) exited 0.
+  const results = await runExecutor(description, overrides, context)
+  const iterator = (results[Symbol.asyncIterator] || results[Symbol.iterator]).call(results)
+  let last
+  for (;;) {
+    const step = await iterator.next()
+    if (step.done) {
+      if (step.value !== undefined) last = step.value
+      break
+    }
+    last = step.value
+  }
+  const ok = last !== null && typeof last === 'object' && last.success === true
+  return ok ? 0 : 1
+}
+
+/** Does `pkg` resolve from the working directory (the workspace root, once Nx runs)? */
+function installed(pkg) {
+  try {
+    createRequire(path.join(process.cwd(), 'package.json')).resolve(`${pkg}/package.json`)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Exit once both streams have drained. An executor may leave a worker pool
+ * or a timer alive after its last result (Nx's own runner calls
+ * `process.exit` for the same reason); exiting in the write callbacks is
+ * what keeps a piped stdout whole on the platforms where pipes are async.
+ */
+function finish(code) {
+  process.exitCode = code
+  process.stdout.write('', () => process.stderr.write('', () => process.exit(code)))
+}
+
+// As `nx run` reports a thrown error (`handleErrors`): the message, and
+// the stack only under verbose logging. A missing executor package or an
+// executor's own throw printed a stack of Nx internals every time.
+main(process.argv.slice(2)).then(finish, (err) => {
+  const message = err && err.message ? err.message : String(err)
+  const verbose = process.env.NX_VERBOSE_LOGGING === 'true'
+  // Nx's "Unable to resolve <pkg>:<executor>." with a package Node cannot
+  // find from the workspace root: not installed. Nx's own second line
+  // varies (Node's "Cannot find module" and its require stack, or the
+  // local-plugin lookup's "unable to find tsconfig.base.json"); either,
+  // with a package Node cannot resolve, is the refusal. A local plugin
+  // Nx found and failed on says something else, and keeps Nx's message.
+  const unresolved = /^Unable to resolve (.+):([^:\n]+)\.\n([^\n]*)/.exec(message)
+  const notFound =
+    unresolved !== null &&
+    (unresolved[3].startsWith(`Cannot find module '${unresolved[1]}/package.json'`) ||
+      unresolved[3].startsWith('unable to find tsconfig'))
+  if (!verbose && notFound && !installed(unresolved[1])) {
+    process.stderr.write(
+      `nx-exec: executor package ${JSON.stringify(unresolved[1])} is not installed in this workspace ` +
+        `(${unresolved[1]}:${unresolved[2]}) — add it to devDependencies, or write the task as the command ` +
+        'the executor runs\n',
+    )
+    finish(1)
+    return
+  }
+  const more =
+    err && err.stack
+      ? verbose
+        ? `\n${err.stack}`
+        : '\nSet NX_VERBOSE_LOGGING=true to see the stack trace.'
+      : ''
+  process.stderr.write(`nx-exec: ${message}${more}\n`)
+  finish(1)
+})

package/src/paths.ts

@@ -0,0 +1,36 @@
+// The two package.json / path readings every mapper in this package shares.
+//
+// Both existed as per-file copies. `relPosix` had FOUR (migrate-turbo,
+// migrate-nx, turbo/turbo-map, nx-command), three identical and one that
+// mapped the same-directory case to `.` — a difference its own caller made
+// unreachable by returning early, which is the kind of divergence a copy
+// acquires quietly. `packageScripts` had two, and core guards the same read
+// while these did not (item 446).
+//
+// Neither divergence was reachable in a realistic workspace, which is why
+// this is consolidation rather than a fix. The reason to do it anyway is
+// item 445: one copy in this package HAD drifted into a defect, and the
+// cheapest moment to collapse a duplicate is before it does.
+
+import path from 'node:path'
+import type { ProjectMeta } from '@vzn/vx'
+
+/** `to` relative to `from`, POSIX-separated — core's `relPosix`, which is not on the façade. */
+export function relPosix(from: string, to: string): string {
+  return path.relative(from, to).split(path.sep).join('/')
+}
+
+/**
+ * A project's `scripts` map, or `{}` when the file holds something else.
+ *
+ * package.json is a system boundary, so the value is whatever the file
+ * holds: a string or an array would enumerate its INDICES as script names,
+ * and indexing one by a task named `0` yields a single character that reads
+ * as a usable command. Core's `migrate-scripts.ts` guards this read; these
+ * mappers did not.
+ */
+export function packageScripts(meta: ProjectMeta): Record<string, unknown> {
+  const raw = (meta.packageJson as unknown as { scripts?: unknown }).scripts
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return {}
+  return raw as Record<string, unknown>
+}

package/src/plugin-gaps.ts

@@ -0,0 +1,48 @@
+// What a mapping could not say, reported once per run by the plugin that
+// runs it live. One line per DISTINCT gap, not one per task: n8n has a
+// `dev` and a `watch` in most of its 84 packages, and astro's `build`
+// carries the same `!vendor/**` output in every package — the per-task
+// form was a hundred identical lines before the first frame (2026-09-11).
+// Shared by `turbo()` and `nx()` since the second one existed.
+
+/** What both mappers' projects have in common: a name and tasks with todos. */
+interface MappedProject {
+  readonly name: string
+  readonly tasks: readonly { readonly name: string; readonly todos: readonly string[] }[]
+}
+
+export interface Gaps {
+  readonly notes: readonly string[]
+  /** Every task-level gap, keyed on its text, to the `pkg#task` ids that carry it. */
+  readonly todos: ReadonlyMap<string, readonly string[]>
+}
+
+/** The gaps of a mapping, indexed for the one-line-per-gap report. */
+export function collectGaps(projects: readonly MappedProject[], notes: readonly string[]): Gaps {
+  const todos = new Map<string, string[]>()
+  for (const project of projects) {
+    for (const t of project.tasks) {
+      for (const todo of t.todos) {
+        let ids = todos.get(todo)
+        if (ids === undefined) todos.set(todo, (ids = []))
+        ids.push(`${project.name}#${t.name}`)
+      }
+    }
+  }
+  return { notes, todos }
+}
+
+export function warnGaps(warn: (line: string) => void, pluginName: string, gaps: Gaps): void {
+  for (const note of gaps.notes) warn(`[${pluginName}] ${note}`)
+  for (const [todo, ids] of gaps.todos) {
+    if (ids.length === 1) {
+      warn(`[${pluginName}] ${ids[0]}: ${todo}`)
+      continue
+    }
+    const names = [...new Set(ids.map((id) => id.slice(id.indexOf('#') + 1)))]
+    const packages = new Set(ids.map((id) => id.slice(0, id.indexOf('#'))))
+    warn(
+      `[${pluginName}] ${ids.length} task(s) (${names.join(', ')} across ${packages.size} package(s)): ${todo}`,
+    )
+  }
+}

package/src/remote-deadline.ts

@@ -0,0 +1,11 @@
+/**
+ * A request's deadline, named. The runtime's abort says "The operation
+ * timed out." and nothing else; core's degrade line already names the
+ * request, the artifact and the server, so the cause names the deadline
+ * that was spent. Shared by `turboCache()` and `nxCache()`.
+ */
+export function deadlineNamed(err: unknown, timeoutMs: number): unknown {
+  return (err as { name?: unknown } | null)?.name === 'TimeoutError'
+    ? new Error(`no answer within ${timeoutMs} ms`)
+    : err
+}

package/src/remote-retry.ts

@@ -0,0 +1,52 @@
+/**
+ * One request with Turbo's retry rule (`turborepo-api-client/src/retry.rs`):
+ * a 429 or a 5xx other than 501, or a request that never connected, is
+ * sent again after a backoff — 2 s, or a 429's `Retry-After` capped at
+ * 10 s. Without it one 503 from a gateway read as a miss and the task ran
+ * again. A spent deadline is not retried, unlike Turbo's reads: it has
+ * already cost its wait, and a hung server would cost it twice. Every
+ * request both wires make is idempotent (content-addressed, and Nx's
+ * second write is a 409 the caller takes as done), so a resend applies
+ * nothing twice. Shared by `turboCache()` and `nxCache()`.
+ */
+export async function withRetry(
+  send: () => Promise<Response>,
+  retries: number,
+  wait: (ms: number) => Promise<void> = Bun.sleep,
+): Promise<Response> {
+  for (let attempt = 0; ; attempt++) {
+    let res: Response
+    try {
+      res = await send()
+    } catch (err) {
+      if (attempt >= retries || !neverConnected(err)) throw err
+      await wait(BACKOFF_MS)
+      continue
+    }
+    if (attempt >= retries || !retryable(res.status)) return res
+    const delay = res.status === 429 ? (retryAfterMs(res) ?? BACKOFF_MS) : BACKOFF_MS
+    await res.body?.cancel()
+    await wait(delay)
+  }
+}
+
+const BACKOFF_MS = 2_000
+const MAX_RETRY_AFTER_MS = 10_000
+
+function retryable(status: number): boolean {
+  return status === 429 || (status >= 500 && status !== 501)
+}
+
+/** A refused port or an unresolved host, as Bun's `fetch` codes them (measured on 1.4.2). */
+function neverConnected(err: unknown): boolean {
+  const code = (err as { code?: unknown } | null)?.code
+  return code === 'ConnectionRefused' || code === 'ENOTFOUND'
+}
+
+/** `Retry-After` as seconds or an HTTP date, capped as Turbo caps it. */
+function retryAfterMs(res: Response): number | undefined {
+  const v = res.headers.get('retry-after')
+  if (v === null) return undefined
+  const ms = /^\d+$/.test(v.trim()) ? Number(v) * 1000 : Date.parse(v) - Date.now()
+  return Number.isFinite(ms) ? Math.min(Math.max(ms, 0), MAX_RETRY_AFTER_MS) : undefined
+}

package/src/remote-token.ts

@@ -0,0 +1,18 @@
+/**
+ * Why a string cannot be an HTTP header value, or null when it can. Bun's
+ * `fetch` refuses a value holding a line break or NUL, or a character past
+ * Latin-1, once it has trimmed the ends (measured on 1.4.2), and its error
+ * QUOTES the whole value: a token with an interior newline (a two-line
+ * secret file) reached every degrade warning as `'Bearer <token>'` (item
+ * 927). A caller refuses with this reason and never with the value. Shared
+ * by `turboCache()` and `nxCache()`.
+ */
+export function headerValueFault(value: string): string | null {
+  let past = false
+  for (const ch of value.trim()) {
+    const c = ch.codePointAt(0)!
+    if (c === 0x0a || c === 0x0d || c === 0) return 'a line break or NUL'
+    if (c > 0xff) past = true
+  }
+  return past ? 'a character past Latin-1' : null
+}