@vzn/vx-migrate 0.0.595 → 0.0.596

package/src/nx/nx-inputs.ts

@@ -7,7 +7,7 @@
 // (`dependentTasksOutputFiles`) is nothing; `externalDependencies` is a todo saying
 // so. Extracted from `buildTask` in item 606.
 
-import { nxWorkspacePath, underProject } from './nx-outputs.js'
+import { nxWorkspacePath, underProject, withProjectDir } from './nx-outputs.js'
 import { minimatchToVx } from '../glob-grammar.js'
 import { shellQuote } from '../nx-command.js'
 
@@ -70,15 +70,16 @@ export function expandNxInputs(
         }
         // Nx's file map skips gitignored files, so it hashes nothing here
         // either: a changed `dist` file is a cache hit under Nx 23.3 (YL-1).
-        if (neg === '' && at.outputs?.some((o) => p === o || p.startsWith(`${o}/`))) return
+        const lit = withProjectDir(p, at.rel, false)
+        if (neg === '' && at.outputs?.some((o) => lit === o || lit.startsWith(`${o}/`))) return
         const g = minimatchToVx(p, neg !== '')
         if (g === null) {
           todos.push(`input ${JSON.stringify(entry)}: glob syntax vx cannot take — map manually`)
           return
         }
         const own = underProject(g, at.rel)
-        if (own === null) into.wsFiles.push(neg + g)
-        else into.files.push(neg + own)
+        if (own === null) into.wsFiles.push(neg + withProjectDir(g, at.rel, true))
+        else into.files.push(neg + withProjectDir(own, at.rel, true))
         return
       }
       // Bare string = named-input reference.
@@ -193,7 +194,10 @@ export function expandNxInputs(
     }
     // A negation filters only other includeIgnored matches, and a literal
     // reads no others.
-    if (!neg) into.runtimeCmds.push(`cat -- ${shellQuote(p)} 2>/dev/null; echo "$?"`)
+    if (!neg)
+      into.runtimeCmds.push(
+        `cat -- ${shellQuote(withProjectDir(p, at.rel, false))} 2>/dev/null; echo "$?"`,
+      )
   }
   for (const entry of entries) expand(entry, new Set())
   // Nx matches a project fileset with no positive glob against every project

package/src/nx/nx-map.ts

@@ -37,6 +37,7 @@ import {
 } from '../shared-outputs.js'
 import type { TrackedKinds } from '../tracked-outputs.js'
 import { packageScripts, relPosix } from '../paths.js'
+import { withLernaOrder } from './lerna.js'
 import { mapNxDeps, matchNxProjects, type TaskNameFor } from './nx-deps.js'
 import {
   dotenvCandidates,
@@ -304,7 +305,17 @@ export async function mapNxWorkspace(
   graph: NxGraph,
   opts: MapNxOptions,
 ): Promise<NxMapping> {
-  const nodeMap = graph.nodes
+  const byRel = new Map(metas.map((m) => [normRel(relPosix(root, m.dir)), m.packageJson]))
+  const nodeMap = await withLernaOrder(
+    root,
+    graph.nodes,
+    (await readNxJson(root).catch(() => null))?.json,
+    async (rel) =>
+      (byRel.get(normRel(rel)) as Record<string, unknown> | undefined) ??
+      (await Bun.file(path.join(root, rel, 'package.json'))
+        .json()
+        .catch(() => undefined)),
+  )
   const g = graph
 
   const { namedInputs, cacheable, globalSync } = await readNxJsonFacts(root)
@@ -923,7 +934,10 @@ function buildTask(
   }
   const exec: Record<string, unknown> = { command: mapped.command }
   const env: Record<string, unknown> = {}
-  if (inputs.envNames.length > 0) env.passThrough = inputs.envNames
+  // A name that is no shell identifier never reached a task (`sh` drops it)
+  // and core refuses it in passThrough; the key still reads it.
+  const passThrough = inputs.envNames.filter((n) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(n))
+  if (passThrough.length > 0) env.passThrough = passThrough
   // Nx hands every task its target (`getNxEnvVariablesForTask`), and
   // `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

package/src/nx/nx-outputs.ts

@@ -2,7 +2,8 @@
 // workspace-root globs. Extracted from `buildTask` in item 606.
 
 import path from 'node:path'
-import { minimatchToVx } from '../glob-grammar.js'
+import { isLiteralPattern } from '@vzn/vx'
+import { literalGlob, minimatchToVx } from '../glob-grammar.js'
 import { takingBack } from '../shared-outputs.js'
 
 interface NxOutputs {
@@ -18,12 +19,13 @@ interface NxOutputs {
  * became the literal glob `coverage/{projectRoot}/**`, saved nothing, and a
  * hit restored nothing. Null when a token is left or the path leaves the
  * workspace; a brace set is no token (item 914 — 912 read one as a gap).
+ * The project dir comes back masked: {@link withProjectDir} writes it in.
  */
 export function nxWorkspacePath(s: string, projectRel: string, projectName: string): string | null {
   const rel = projectRel === '.' ? '' : projectRel
   const p = s
     .replaceAll('{workspaceRoot}', '')
-    .replaceAll('{projectRoot}', rel)
+    .replaceAll('{projectRoot}', masked(rel))
     .replaceAll('{projectName}', projectName)
   // A token left over is a gap; a brace set (`*.{ts,tsx}`) is a glob.
   if (/\{[\w.]+\}/.test(p)) return null
@@ -31,10 +33,38 @@ export function nxWorkspacePath(s: string, projectRel: string, projectName: stri
   return n === '.' || n === '..' || n.startsWith('../') ? null : n
 }
 
+// A project dir is a path, never a glob: `packages/a{b}` read as a token
+// dropped every `{projectRoot}` path, and `packages/[x]` translated as a
+// class reached `packages/x`. Each dir segment stands in as `\uE000<i>\uE001`
+// until the glob is vx's, so `..` still pops one.
+const MASKED = /\uE000(\d+)\uE001/g
+
+function masked(rel: string): string {
+  return rel === ''
+    ? ''
+    : rel
+        .split('/')
+        .map((_, i) => `\uE000${i}\uE001`)
+        .join('/')
+}
+
+/** `p` with the masked project dir written back: as a path, or escaped for a glob. */
+export function withProjectDir(p: string, projectRel: string, asGlob: boolean): string {
+  const segs = projectRel.split('/')
+  return p.replace(MASKED, (_, i: string, at: number) => {
+    const seg = segs[Number(i)]!
+    if (!asGlob) return seg
+    // Only a glob's head reads `!` as a negation.
+    return at === 0 ? literalGlob(seg) : literalGlob(`/${seg}`).slice(1)
+  })
+}
+
 /** A workspace path relative to the project dir, or null when it lies outside. */
 export function underProject(p: string, projectRel: string): string | null {
   if (projectRel === '.' || projectRel === '') return p
-  return p.startsWith(`${projectRel}/`) ? p.slice(projectRel.length + 1) : null
+  for (const dir of [masked(projectRel), projectRel])
+    if (p.startsWith(`${dir}/`)) return p.slice(dir.length + 1)
+  return null
 }
 
 /**
@@ -64,15 +94,16 @@ export function nxDefaultOutputs(
   }
   if (targetName !== 'build' && targetName !== 'prepare') return []
   const root = projectRel === '.' ? '' : projectRel
-  const at = (p: string): string => path.posix.join(root, p)
+  // As tokens, so the dir stays a path whatever its name holds.
+  const at = (p: string): string => (root === '' ? p : `{projectRoot}/${p}`)
   const held = ['build', 'public'].filter((d) => tops === undefined || tops.has(d))
   if (held.length > 0)
     todos.push(
-      `no outputs declared: Nx also caches ${held.map(at).join(' and ')} for this target — vx cleans an output before the run, so add ${held.length === 1 ? 'it' : 'them'} to the outputs by hand only if ${held.length === 1 ? 'it holds' : 'they hold'} nothing committed`,
+      `no outputs declared: Nx also caches ${held.map((d) => path.posix.join(root, d)).join(' and ')} for this target — vx cleans an output before the run, so add ${held.length === 1 ? 'it' : 'them'} to the outputs by hand only if ${held.length === 1 ? 'it holds' : 'they hold'} nothing committed`,
     )
   // The root project's two are one path.
   return [
-    ...new Set([path.posix.join('dist', root), at('dist')]),
+    ...new Set([root === '' ? 'dist' : '{workspaceRoot}/dist/{projectRoot}', at('dist')]),
     ...['build', 'public'].filter((d) => !held.includes(d)).map(at),
   ]
 }
@@ -145,7 +176,7 @@ export function mapNxOutputs(
     const norm = path.posix.normalize(s.replace(/^\/+/, ''))
     if (norm === '..' || norm.startsWith('../')) {
       todos.push(
-        `output ${JSON.stringify(o)} resolves to ${JSON.stringify(norm)}, outside the workspace — ` +
+        `output ${JSON.stringify(o)} resolves to ${JSON.stringify(withProjectDir(norm, projectRel, false))}, outside the workspace — ` +
           'vx caches only inside it; dropped',
       )
       continue
@@ -158,9 +189,18 @@ export function mapNxOutputs(
     for (const g of globs) {
       const gn = g.startsWith('!') ? '!' : ''
       const gs = g.slice(gn.length)
-      if (projectRel === '.') outFiles.push(g)
-      else if (gs.startsWith(`${projectRel}/`)) outFiles.push(gn + gs.slice(projectRel.length + 1))
-      else wsOutFiles.push(gn + path.posix.normalize(gs).replace(/^\.\//, ''))
+      const own = underProject(gs, projectRel)
+      if (own !== null) {
+        outFiles.push(gn + withProjectDir(own, projectRel, true))
+        continue
+      }
+      const m = path.posix.normalize(gs).replace(/^\.\//, '')
+      const w = withProjectDir(m, projectRel, true)
+      wsOutFiles.push(gn + w)
+      // An escaped brace makes a literal a glob, which core matches as the
+      // path alone (`asTrees` adds the tree only to a literal).
+      if (w !== withProjectDir(m, projectRel, false) && isLiteralPattern(m.replace(MASKED, '')))
+        wsOutFiles.push(`${gn}${w}/**`)
     }
   }
   return { outFiles: takingBack(outFiles), wsOutFiles: takingBack(wsOutFiles) }
@@ -217,9 +257,19 @@ export function nxProjectOutputs(
       projectName,
       scratch,
     )
-    for (const f of [...outFiles.map((f) => path.posix.join(rel, f)), ...wsOutFiles]) {
+    const literal = (f: string): string | null => {
       const lit = f.replace(/\/\*\*(\/\*)?$/, '')
-      if (!lit.startsWith('!') && !/[*?[{]/.test(lit)) out.add(lit)
+      return lit.startsWith('!') || /[*?[]|(?<!\\)[{}]/.test(lit)
+        ? null
+        : lit.replace(/\\([{}!])/g, '$1')
+    }
+    for (const f of outFiles) {
+      const lit = literal(f)
+      if (lit !== null) out.add(path.posix.join(rel, lit))
+    }
+    for (const f of wsOutFiles) {
+      const lit = literal(f)
+      if (lit !== null) out.add(lit)
     }
   }
   const r = [...out]

package/src/nx/nx-upstream.ts

@@ -20,6 +20,7 @@ import type { GeneratedTask, ProjectMeta } from '@vzn/vx'
 import { emptyNxInputs, expandNxInputs, type NxInputs } from './nx-inputs.js'
 import { nxProjectOutputs } from './nx-outputs.js'
 import { matchNxProjects } from './nx-deps.js'
+import { literalGlob } from '../glob-grammar.js'
 
 interface GraphNode {
   name?: string
@@ -192,7 +193,9 @@ export function planNxUpstream(
     const inputs = emptyNxInputs()
     for (const g of own.files) {
       const neg = g.startsWith('!') ? '!' : ''
-      inputs.wsFiles.push(rel === '' ? g : `${neg}${rel}/${neg === '' ? g : g.slice(1)}`)
+      inputs.wsFiles.push(
+        rel === '' ? g : `${neg}${literalGlob(rel)}/${neg === '' ? g : g.slice(1)}`,
+      )
     }
     inputs.wsFiles.push(...own.wsFiles)
     inputs.envNames.push(...own.envNames)

package/src/nx-cache/index.ts

@@ -21,6 +21,7 @@ import {
   type PluginOptionKinds,
 } from '@vzn/vx'
 import { deadlineNamed } from '../remote-deadline.js'
+import { OutageBreaker } from '../remote-breaker.js'
 import { withRetry } from '../remote-retry.js'
 import { headerValueFault } from '../remote-token.js'
 
@@ -102,6 +103,7 @@ export function resolveNxCacheConfig(
  */
 export class NxRemoteCache implements RemoteCacheLayer {
   private disabled = false
+  private readonly breaker = new OutageBreaker()
   /**
    * A `403` on a write is the spec's read-only token (a CI's pull-request
    * token): uploads stop, reads go on. Read as a refused token, it turned
@@ -140,19 +142,23 @@ export class NxRemoteCache implements RemoteCacheLayer {
       // every hit read as a corrupt artifact (nx#33092).
       headers['Accept'] = 'application/octet-stream'
     }
-    const res = await withRetry(
-      () =>
-        this.fetchImpl(`${this.config.server}/v1/cache/${hash}`, {
-          method,
-          headers,
-          ...(body === undefined ? {} : { body }),
-          signal: AbortSignal.timeout(this.config.timeoutMs),
-        }),
-      this.config.retries,
-      this.wait,
-    ).catch((err: unknown) => {
-      throw deadlineNamed(err, this.config.timeoutMs)
-    })
+    const res = await this.breaker
+      .send(() =>
+        withRetry(
+          () =>
+            this.fetchImpl(`${this.config.server}/v1/cache/${hash}`, {
+              method,
+              headers,
+              ...(body === undefined ? {} : { body }),
+              signal: AbortSignal.timeout(this.config.timeoutMs),
+            }),
+          this.config.retries,
+          this.wait,
+        ),
+      )
+      .catch((err: unknown) => {
+        throw deadlineNamed(err, this.config.timeoutMs)
+      })
     if (method === 'PUT' && res.status === 403) {
       const first = !this.writesRefused
       this.writesRefused = true
@@ -166,7 +172,7 @@ export class NxRemoteCache implements RemoteCacheLayer {
       this.disabled = true
       if (!first) return undefined
       throw new Error(
-        `HTTP ${res.status}: ${res.status === 401 ? 'missing or invalid token' : 'access forbidden (a read-only token cannot write)'}; remote cache off for this run`,
+        `HTTP ${res.status}: ${res.status === 401 ? 'missing or invalid token' : 'access forbidden (the token may not read)'}; remote cache off for this run`,
       )
     }
     return res

package/src/remote-breaker.ts

@@ -0,0 +1,60 @@
+/**
+ * Turbo's outage breaker (`turborepo-cache/src/outage_breaker.rs`): three
+ * outages in a row — no connection, no answer in time, or a 5xx once the
+ * retries are spent — open it for 30 s, and while open no request is sent.
+ * After the cooldown one request probes; its success closes the breaker,
+ * its outage opens it again. Without it a server that hung cost every
+ * task its full deadline. A result that lands after the breaker moved on
+ * (a request already in flight when it opened) changes nothing. Shared by
+ * `turboCache()` and `nxCache()`.
+ */
+export class OutageBreaker {
+  private failures = 0
+  private openUntil: number | undefined
+  private probing = false
+  private generation = 0
+  constructor(private readonly now: () => number = Date.now) {}
+
+  async send(request: () => Promise<Response>): Promise<Response> {
+    let probe = false
+    if (this.openUntil !== undefined) {
+      if (this.now() < this.openUntil || this.probing)
+        throw new Error(
+          `unavailable after ${FAILURE_THRESHOLD} failures in a row; not asked again for ${COOLDOWN_MS / 1000} s`,
+        )
+      this.probing = probe = true
+    }
+    const generation = this.generation
+    let res: Response
+    try {
+      res = await request()
+    } catch (err) {
+      this.finish(generation, probe, true)
+      throw err
+    }
+    this.finish(generation, probe, res.status >= 500)
+    return res
+  }
+
+  private finish(generation: number, probe: boolean, outage: boolean): void {
+    if (generation !== this.generation) return
+    if (outage) {
+      this.failures++
+      if (probe || this.failures >= FAILURE_THRESHOLD) {
+        this.openUntil = this.now() + COOLDOWN_MS
+        this.probing = false
+        this.generation++
+      }
+      return
+    }
+    this.failures = 0
+    if (probe) {
+      this.openUntil = undefined
+      this.probing = false
+      this.generation++
+    }
+  }
+}
+
+const FAILURE_THRESHOLD = 3
+const COOLDOWN_MS = 30_000

package/src/shared-outputs.ts

@@ -413,6 +413,8 @@ export function excludeWorkspaceOutputs(
     readonly dir: string
     readonly tasks: GeneratedTask[]
   }[],
+  /** The globs an opaque entry stands for (`vx-migrate`'s `...globalInputs` spread). */
+  expand: (entry: unknown) => readonly string[] = () => [],
 ): void {
   const positive = (v: unknown): string[] =>
     Array.isArray(v)
@@ -444,7 +446,7 @@ export function excludeWorkspaceOutputs(
         ?.inputs
       if (inputs === undefined || !Array.isArray(inputs.workspaceFiles)) continue
       const files = inputs.workspaceFiles as string[]
-      const reads = positive(files)
+      const reads = positive(files.flatMap((f) => (typeof f === 'string' ? [f] : expand(f))))
       if (reads.length === 0) continue
       for (const i of candidates(reads)) {
         const w = writers[i]!

package/src/spelled-env.ts

@@ -0,0 +1,36 @@
+// The env names a package's tracked source spells: what stands in, in a
+// written config, for a `*` env entry Turbo or Vite Task matched against
+// the environment a run sees.
+
+import path from 'node:path'
+import { relPosix } from './paths.js'
+
+/** Source and env-example files a framework build reads its variables from. */
+const SPELLS_ENV =
+  /\.(c|m)?(j|t)sx?$|\.(vue|svelte|astro|html)$|(^|\/)\.env\.(example|sample|template)$/
+
+/**
+ * The upper-case names the tracked source under `dirs` spells (`NEXT_PUBLIC_API`
+ * in `process.env.NEXT_PUBLIC_API` or an `.env.example`), sorted. Without
+ * git, none: the note still names the framework's prefix.
+ */
+export async function spelledNames(
+  root: string,
+  dirs: readonly string[],
+  tracked: readonly string[] | null,
+): Promise<string[]> {
+  if (tracked === null) return []
+  const prefixes = dirs.map((dir) => {
+    const rel = relPosix(root, dir)
+    return rel === '' || rel === '.' ? '' : `${rel}/`
+  })
+  const names = new Set<string>()
+  for (const f of tracked) {
+    if (!SPELLS_ENV.test(f) || !prefixes.some((p) => f.startsWith(p))) continue
+    const text = await Bun.file(path.join(root, f))
+      .text()
+      .catch(() => '')
+    for (const m of text.matchAll(/\b[A-Z][A-Z0-9_]*_[A-Z0-9_]+\b/g)) names.add(m[0])
+  }
+  return [...names].sort()
+}

package/src/turbo/turbo-map.ts

@@ -65,6 +65,8 @@ interface TurboJson {
   envMode?: unknown
 }
 
+const SHELL_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
 /** A name core takes in `cache.inputs.env` and `exec.env.passThrough`. */
 const keyable = (name: string): boolean =>
   name.length > 0 && !name.startsWith('!') && !/[*?[\]{}=\0]/.test(name)
@@ -1488,7 +1490,14 @@ export async function mapTurboWorkspace(
     )
   literalEnvGapsOnce(projects, notes)
   resolveSharedWorkspaceOutputs(root, projects)
-  excludeWorkspaceOutputs(root, projects)
+  // A written config spreads the preset (`...globalInputs`), which the
+  // take-back pass must read as its globs: unread, opencode's configs
+  // read `packages/plugin/**` with no `!packages/plugin/dist/**` and
+  // core refused to load them.
+  const opaque = new Map<string, readonly string[]>()
+  for (const e of opts.splice('inputs', globals.inputs))
+    if (typeof e !== 'string') opaque.set(JSON.stringify(e), globals.inputs)
+  excludeWorkspaceOutputs(root, projects, (e) => opaque.get(JSON.stringify(e)) ?? [])
   pruneUnreachedPersistentNotes(projects, metas, opts.persistentTodo)
   pruneOrphanPersistentNotes(projects, opts.persistentTodo)
   return { projects, notes, globals }
@@ -1882,10 +1891,12 @@ function buildTask(
     spelled,
   )
 
+  // A name that is no shell identifier never reached a task (`sh` drops it)
+  // and core refuses it in passThrough.
   const passThrough = uniq(
     [...global('env'), ...global('pass'), ...envNames, ...passNames],
     hidden('env', 'pass'),
-  )
+  ).filter((n) => typeof n !== 'string' || SHELL_NAME.test(n))
 
   const exec: Record<string, unknown> = { command }
   if (passThrough.length > 0) exec.env = { passThrough }

package/src/turbo-cache/index.ts

@@ -25,6 +25,7 @@ import {
   type PluginOptionKinds,
 } from '@vzn/vx'
 import { deadlineNamed } from '../remote-deadline.js'
+import { OutageBreaker } from '../remote-breaker.js'
 import { withRetry } from '../remote-retry.js'
 import { headerValueFault } from '../remote-token.js'
 
@@ -55,6 +56,12 @@ export interface TurboCacheOptions {
   uploadTimeoutMs?: number
   /** Resends of a request answered 429 / 5xx or never connected (default 1, Turbo's); 0 turns them off. */
   retries?: number
+  /**
+   * Send Turbo's preflight (`OPTIONS`) before each artifact request and
+   * follow its `Location`, or `TURBO_PREFLIGHT` / turbo.json's
+   * `remoteCache.preflight`; default off.
+   */
+  preflight?: boolean
 }
 
 /** turbo.json's `remoteCache` block: the source below Turbo's environment, as in Turbo. */
@@ -66,6 +73,7 @@ export interface TurboJsonRemoteCache {
   enabled?: unknown
   timeout?: unknown
   uploadTimeout?: unknown
+  preflight?: unknown
 }
 
 /** `.turbo/config.json`'s fields, under any of the spellings Turbo accepts. */
@@ -85,6 +93,7 @@ export interface TurboCacheConfig {
   timeoutMs: number
   uploadTimeoutMs: number
   retries: number
+  preflight: boolean
 }
 
 /** Turbo's signature message prefix (`crates/turborepo-cache/src/signature_authentication.rs`). */
@@ -250,18 +259,14 @@ export function resolveTurboCacheConfig(
     fromFile(file.teamId)
   const teamSlug =
     options.teamSlug ?? env['TURBO_TEAM'] ?? fromFile(local.teamSlug) ?? fromFile(file.teamSlug)
+  const preflight =
+    options.preflight ??
+    truthy(env['TURBO_PREFLIGHT'], 'TURBO_PREFLIGHT') ??
+    file.preflight === true
   // Turbo signs only under `remoteCache.signature: true`; the env key alone
   // signs nothing there, and a short one here refused the whole cache.
   // `TURBO_SIGNATURE` (1/true, 0/false) sits above turbo.json, as in Turbo.
-  const signEnv = env['TURBO_SIGNATURE']
-  let signing = file.signature === true
-  if (signEnv !== undefined && signEnv !== '') {
-    if (!/^(1|0|true|false)$/.test(signEnv))
-      throw new Error(
-        `vx/turbo-cache: TURBO_SIGNATURE should be 1 or 0, got ${JSON.stringify(signEnv)}`,
-      )
-    signing = signEnv === '1' || signEnv === 'true'
-  }
+  const signing = truthy(env['TURBO_SIGNATURE'], 'TURBO_SIGNATURE') ?? file.signature === true
   const signatureKey =
     options.signatureKey ?? (signing ? env['TURBO_REMOTE_CACHE_SIGNATURE_KEY'] : undefined)
   if (signatureKey !== undefined) {
@@ -303,9 +308,18 @@ export function resolveTurboCacheConfig(
       seconds(file.uploadTimeout, 'remoteCache.uploadTimeout') ??
       60_000,
     retries,
+    preflight,
   }
 }
 
+/** Turbo's `truth_env_var`: 1/true, 0/false; unset or empty is `undefined`. */
+function truthy(v: string | undefined, name: string): boolean | undefined {
+  if (v === undefined || v === '') return undefined
+  if (!/^(1|0|true|false)$/.test(v))
+    throw new Error(`vx/turbo-cache: ${name} should be 1 or 0, got ${JSON.stringify(v)}`)
+  return v === '1' || v === 'true'
+}
+
 /**
  * Turbo's timeout, whole seconds, as ms; `undefined` when unset. A value
  * Turbo would refuse is refused here rather than read as some other wait.
@@ -365,6 +379,7 @@ const MAX_SIGNED_BODY = 2 * 1024 ** 3 + ((2 * 1024 ** 3) >> 8) + 64 * 1024
  */
 export class TurboRemoteCache implements RemoteCacheLayer {
   private disabled = false
+  private readonly breaker = new OutageBreaker()
   /**
    * A `403` on an upload is a read-only token or server
    * (turborepo-remote-cache's `READ_ONLY` and its JWTs without the write
@@ -396,14 +411,50 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     return u.toString()
   }
 
-  private headers(extra: Record<string, string> = {}): Record<string, string> {
+  private headers(extra: Record<string, string> = {}, auth = true): Record<string, string> {
     return {
-      Authorization: `Bearer ${this.config.token}`,
+      ...(auth ? { Authorization: `Bearer ${this.config.token}` } : {}),
       'x-artifact-client-interactive': process.stdout.isTTY ? '1' : '0',
       ...extra,
     }
   }
 
+  /**
+   * Turbo's preflight: an `OPTIONS` to the request's URL names the method
+   * and headers to come; the answer's `Location` (relative to `apiUrl`) is
+   * where the request goes, as given — a signed storage URL signs its own
+   * query, so nothing is appended — and the token goes along only when
+   * `Access-Control-Allow-Headers` admits `Authorization` (or `*`), so it
+   * never reaches a third-party store. The answer's status is not read, as
+   * in Turbo.
+   */
+  private async preflight(
+    url: string,
+    method: string,
+    headers: Record<string, string>,
+    signal: () => AbortSignal | undefined,
+  ): Promise<{ url: string; auth: boolean }> {
+    const s = signal()
+    const res = await this.fetchImpl(url, {
+      method: 'OPTIONS',
+      headers: {
+        Authorization: `Bearer ${this.config.token}`,
+        'Access-Control-Request-Method': method === 'HEAD' ? 'GET' : method,
+        'Access-Control-Request-Headers': ['Authorization', ...Object.keys(headers)].join(', '),
+      },
+      ...(s === undefined ? {} : { signal: s }),
+    })
+    await res.body?.cancel()
+    const location = res.headers.get('location')
+    const allowed = res.headers.get('access-control-allow-headers') ?? ''
+    return {
+      url: location === null ? res.url || url : new URL(location, this.config.apiUrl).toString(),
+      auth:
+        allowed.trim() === '*' ||
+        allowed.split(',').some((h) => h.trim().toLowerCase() === 'authorization'),
+    }
+  }
+
   /**
    * `undefined` = the token was refused and the refusal is ALREADY
    * reported, so the caller degrades to its miss value in silence. Only the
@@ -416,20 +467,33 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     init: { body?: Blob | string; headers?: Record<string, string>; timeoutMs?: number } = {},
   ): Promise<Response | undefined> {
     const timeoutMs = init.timeoutMs ?? this.config.timeoutMs
-    const res = await withRetry(
-      () =>
-        this.fetchImpl(this.url(pathname), {
-          method,
-          headers: this.headers(init.headers),
-          ...(init.body === undefined ? {} : { body: init.body }),
-          // 0 is Turbo's "no deadline".
-          ...(timeoutMs === 0 ? {} : { signal: AbortSignal.timeout(timeoutMs) }),
-        }),
-      this.config.retries,
-      this.wait,
-    ).catch((err: unknown) => {
-      throw deadlineNamed(err, timeoutMs)
-    })
+    // 0 is Turbo's "no deadline".
+    const signal = () => (timeoutMs === 0 ? undefined : AbortSignal.timeout(timeoutMs))
+    // The batch query is never preflighted, as in Turbo.
+    const preflight = this.config.preflight && method !== 'POST'
+    const res = await this.breaker
+      .send(() =>
+        withRetry(
+          async () => {
+            const extra = init.headers ?? {}
+            const to = preflight
+              ? await this.preflight(this.url(pathname), method, extra, signal)
+              : { url: this.url(pathname), auth: true }
+            const s = signal()
+            return this.fetchImpl(to.url, {
+              method,
+              headers: this.headers(extra, to.auth),
+              ...(init.body === undefined ? {} : { body: init.body }),
+              ...(s === undefined ? {} : { signal: s }),
+            })
+          },
+          this.config.retries,
+          this.wait,
+        ),
+      )
+      .catch((err: unknown) => {
+        throw deadlineNamed(err, timeoutMs)
+      })
     if (method === 'PUT' && res.status === 403) {
       const first = !this.writesRefused
       this.writesRefused = true
@@ -551,7 +615,9 @@ export class TurboRemoteCache implements RemoteCacheLayer {
       timeoutMs: this.config.uploadTimeoutMs,
     })
     if (res === undefined) return
-    if (res.status !== 200 && res.status !== 202) throw new Error(`HTTP ${res.status}`)
+    // Turbo's client takes any 2xx (`error_for_status`); a server's 201 or
+    // 204 stored the artifact and was counted a failed upload.
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
   }
 }
 
@@ -636,6 +702,7 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
   timeoutMs: 'number',
   uploadTimeoutMs: 'number',
   retries: 'number',
+  preflight: 'boolean',
 }
 
 /**