@vzn/vx-migrate 0.0.646 → 0.0.648

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`,

package/src/package-fs.ts

@@ -1,6 +1,6 @@
 // What packages.ts needs of the file system and of globs, as core has
 // them: core's copies are not on the façade, and these left core with the
-// package-manager discovery (M, 2026-10-14).
+// package-manager discovery (2026-10-14).
 
 import { readlinkSync, realpathSync } from 'node:fs'
 import path from 'node:path'
@@ -123,6 +123,11 @@ export async function gitTop(dir: string): Promise<string | null> {
     if (await file.exists()) {
       const gitdir = await file.text().catch(() => '')
       if (!/(^|[\s/])\.git\/modules\//.test(gitdir)) return d || '/'
+      // A submodule's own worktree points there too, and is a top-level:
+      // git writes `commondir` in a worktree's gitdir alone.
+      const to = gitdir.replace(/^gitdir:\s*/, '').trim()
+      if (await Bun.file(`${to.startsWith('/') ? '' : `${d}/`}${to}/commondir`).exists())
+        return d || '/'
     }
     if (d === '') return null
   }

package/src/packages.ts

@@ -1,11 +1,11 @@
 // Package-manager workspaces: the members `package.json#workspaces` or
 // `pnpm-workspace.yaml` list, and the root a migration writes
-// `.vx/workspace.ts` at. Core reads neither (M, 2026-10-14): a project is a
+// `.vx/workspace.ts` at. Core reads neither (2026-10-14): a project is a
 // directory holding a vx.config.
 import { constants, existsSync, type Dirent } from 'node:fs'
 import { access, readdir, realpath, stat } from 'node:fs/promises'
 import path from 'node:path'
-import { PROJECT_CONFIG_FILENAMES, UserError } from '@vzn/vx'
+import { PROJECT_CONFIG_FILENAMES, ui, UserError } from '@vzn/vx'
 import {
   BUN_GLOB_WILDCARDS,
   EXTGLOB,
@@ -75,7 +75,7 @@ const decoder = new TextDecoder()
  * Inside git the walk never goes above the git top-level ({@link gitTop}),
  * so a manifest above the checkout is never even read: a `package.json`
  * planted in a shared directory above it claimed it, and its workspace
- * config ran as you (owner, 2026-10-13: "find the root based on git").
+ * config ran as you (2026-10-13: "find the root based on git").
  *
  * Outside git the walk stops above `start` at a manifest another user
  * owns (root aside), the same case without a top-level to stop at
@@ -641,8 +641,9 @@ async function readManifest(root: string, dir: string, file: string): Promise<st
       () => false,
     )
     if (searchable) unreadable(err, file)
-    process.stderr.write(
-      `vx: ${shownDir(root, dir)} is not readable by this user — skipped, with any project in it\n`,
+    ui.say(
+      'warn',
+      `vx: ${shownDir(root, dir)} is not readable by this user — skipped, with any project in it`,
     )
     return null
   }
@@ -768,8 +769,9 @@ export async function discoverPackages(
     shared.sort()
     const shown =
       shared.slice(0, 2).join('; ') + (shared.length > 2 ? `; and ${shared.length - 2} more` : '')
-    process.stderr.write(
-      `vx: left out, as no project can be addressed by a name several manifests share (none has a vx config): ${shown}\n`,
+    ui.say(
+      'warn',
+      `vx: left out, as no project can be addressed by a name several manifests share (none has a vx config): ${shown}`,
     )
   }
 

package/src/plugin-gaps.ts

@@ -1,11 +1,13 @@
 // What a mapping could not say, reported once by `vx lock`, the pass that
-// checks configs (a run checks nothing, M 2026-10-15). What this machine
+// checks configs (a run checks nothing, 2026-10-15). What this machine
 // lacks to run the mapping (a bin, a graph export) is said on runs too. 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.
 
+import { taskNameProblem } from '@vzn/vx'
+
 /** What both mappers' projects have in common: a name and tasks with todos. */
 interface MappedProject {
   readonly name: string
@@ -39,25 +41,49 @@ export function collectGaps(
   return { notes, todos, live }
 }
 
-/** At `vx lock` every gap; on a run only the live notes. */
+/**
+ * At `vx lock` every gap; on a run only the live notes. Each says `[vx]`
+ * first, as every plugin warning does, then the package's short name.
+ */
 export function warnGaps(
   warn: (line: string) => void,
   pluginName: string,
   gaps: Gaps,
   lock: boolean,
 ): void {
-  for (const note of gaps.live) warn(`[${pluginName}] ${note}`)
+  const tag = `[vx] ${pluginName.replace(/^@vzn\//, '')}:`
+  for (const note of gaps.live) warn(`${tag} ${note}`)
   if (!lock) return
-  for (const note of gaps.notes) warn(`[${pluginName}] ${note}`)
+  for (const note of gaps.notes) warn(`${tag} ${note}`)
   for (const [todo, ids] of gaps.todos) {
     if (ids.length === 1) {
-      warn(`[${pluginName}] ${ids[0]}: ${todo}`)
+      warn(`${tag} ${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}`,
+      `${tag} ${ids.length} tasks (${names.join(', ')} across ${packages.size} package${packages.size === 1 ? '' : 's'}): ${todo}`,
     )
   }
 }
+
+/**
+ * A task whose name the schema refuses (`lint#fix`, `^up`) becomes a TODO,
+ * as the scripts migrator does (item 1033): written as a task, core
+ * refused the whole config on the next command.
+ */
+export function refuseTaskNames(
+  projects: readonly { tasks: { name: string; todos: string[]; task: object | null }[] }[],
+  what: string,
+): void {
+  for (const p of projects)
+    for (const t of p.tasks) {
+      const why = t.task === null ? null : taskNameProblem(t.name)
+      if (why === null) continue
+      t.task = null
+      t.todos = [
+        `${what} ${JSON.stringify(t.name)} not migrated: its name ${why} — rename it, or add it by hand under another name`,
+      ]
+    }
+}

package/src/remote-cache.ts

@@ -1,6 +1,6 @@
 // The remote cache a Turbo or Nx repo already uses, as the repo shows it,
 // so the workspace file a migration writes keeps sharing it: native or
-// keep, from `vx init` or `bunx @vzn/vx-migrate` (M, 2026-10-14). Nx
+// keep, from `vx init` or `bunx @vzn/vx-migrate` (2026-10-14). Nx
 // Cloud's wire is Nx's own, so it is named, never declared.
 
 import { readFileSync } from 'node:fs'
@@ -28,6 +28,7 @@ export function remoteCacheSignal(root: string, runner: 'turbo' | 'nx'): string
         rc = (
           Bun.JSONC.parse(readFileSync(path.join(root, f), 'utf8')) as { remoteCache?: unknown }
         )?.remoteCache
+        // quiet: a local config file: none read is none declared
       } catch {
         continue
       }
@@ -42,6 +43,7 @@ export function remoteCacheSignal(root: string, runner: 'turbo' | 'nx'): string
     let linked: unknown
     try {
       linked = JSON.parse(readFileSync(path.join(root, '.turbo', 'config.json'), 'utf8'))
+      // quiet: a local config file: none read is none linked
     } catch {}
     if (
       typeof linked === 'object' &&
@@ -63,6 +65,7 @@ export function remoteCacheSignal(root: string, runner: 'turbo' | 'nx'): string
     let text: string
     try {
       text = readFileSync(path.join(root, f), 'utf8')
+      // quiet: a local config file: none read is none declared
     } catch {
       continue
     }
@@ -84,6 +87,7 @@ function usesNxCloud(root: string): boolean {
   } | null
   try {
     json = Bun.JSONC.parse(readFileSync(path.join(root, 'nx.json'), 'utf8')) as typeof json
+    // quiet: a local config file: none read is none declared
   } catch {
     return false
   }

package/src/remote-deadline.ts

@@ -11,9 +11,15 @@
  */
 export function deadline(timeoutMs: number): AbortSignal {
   const controller = new AbortController()
+  // A timer past 2^31-1 ms fires after 1 ms: a 30-day
+  // TURBO_REMOTE_CACHE_TIMEOUT aborted every request as it started. Turbo
+  // defines that value, so it is held here; an option is refused at the call.
   setTimeout(
     () => controller.abort(new Error(`no answer within ${timeoutMs} ms`)),
-    timeoutMs,
+    Math.min(timeoutMs, MAX_TIMER_MS),
   ).unref()
   return controller.signal
 }
+
+/** The longest delay a timer holds. */
+export const MAX_TIMER_MS = 2 ** 31 - 1

package/src/remote-refusal.ts

@@ -0,0 +1,31 @@
+/** How long the body's first chunk is waited for: a refusal is not held on a body that never comes. */
+const BODY_WAIT_MS = 1_000
+
+/**
+ * A remote's refusal, named by its status and its own words: "HTTP 500"
+ * alone said nothing, and a batch query Vercel refused with 400 "Too many
+ * hashes. Limit is 100." read as no answer and was never seen (main
+ * f71b377, 2026-10-23). One line of the body, bounded: it is remote text.
+ * Shared by `turboCache()` and `nxCache()`.
+ */
+export async function refusal(res: Response, what = ''): Promise<Error> {
+  let said = ''
+  try {
+    const reader = res.body?.getReader()
+    if (reader !== undefined) {
+      let timer: ReturnType<typeof setTimeout> | undefined
+      const first = await Promise.race([
+        reader.read(),
+        new Promise<undefined>((r) => {
+          timer = setTimeout(() => r(undefined), BODY_WAIT_MS)
+        }),
+      ]).finally(() => clearTimeout(timer))
+      // quiet: read no further; a cancel that fails has nothing left to free
+      void reader.cancel().catch(() => undefined)
+      said = new TextDecoder().decode(first?.value?.subarray(0, 512)).replace(/\s+/g, ' ').trim()
+    }
+  } catch {
+    // quiet: the status alone still names the refusal
+  }
+  return new Error(`${what}HTTP ${res.status}${said === '' ? '' : `: ${said.slice(0, 200)}`}`)
+}

package/src/remote-retry.ts

@@ -24,7 +24,8 @@ export class Cooldown {
  * One request with Turbo's retry rule (`turborepo-api-client/src/retry.rs`):
  * a 5xx other than 501, or a request that never connected, is sent again
  * after 2 s, `retries` times. A 429 opens the remote's `cooldown` for its
- * `Retry-After` (capped at 10 s a wait, 2 s without one), and the request
+ * `Retry-After` (capped at 10 s a wait, 2 s without one or for a `0`
+ * after the first), and the request
  * is resent once it ends, as often as fits in 20 s from its first 429: a
  * limit longer than one capped wait lost every hit before (Growth's
  * parity run, 2026-10-16). A spent deadline is not retried, unlike
@@ -55,8 +56,12 @@ export async function withRetry(
       continue
     }
     if (res.status === 429) {
+      // `Retry-After: 0` resends at once, but only once in a row: each
+      // answered so sent again at once, hundreds a second for 20 s.
+      const asked = retryAfterMs(res)
+      const delay =
+        asked === undefined || (asked === 0 && firstLimit !== undefined) ? BACKOFF_MS : asked
       firstLimit ??= now()
-      const delay = retryAfterMs(res) ?? BACKOFF_MS
       if (retries === 0 || now() + delay - firstLimit > RATE_LIMIT_BUDGET_MS) return res
       cooldown.extend(delay)
       await res.body?.cancel()
@@ -77,10 +82,10 @@ function retryable(status: number): boolean {
   return status >= 500 && status !== 501
 }
 
-/** A refused port or an unresolved host, as Bun's `fetch` codes them (measured on 1.4.2). */
+/** A refused port or an unresolved host, as Bun's `fetch` codes them (1.4.4 took errno names). */
 function neverConnected(err: unknown): boolean {
   const code = (err as { code?: unknown } | null)?.code
-  return code === 'ConnectionRefused' || code === 'ENOTFOUND'
+  return code === 'ECONNREFUSED' || code === 'ENOTFOUND'
 }
 
 /** `Retry-After` as seconds or an HTTP date, capped as Turbo caps it. */

package/src/remote-url.ts

@@ -0,0 +1,28 @@
+import { UserError } from '@vzn/vx'
+
+/**
+ * A remote cache's URL, refused as `from` names it (an option, a variable,
+ * a config file). Shared by `turboCache()` and `nxCache()`, at the call for
+ * the option and when the cache opens for every source.
+ *
+ * Plain http:// to any host is taken, where vxCache() takes it only to
+ * loopback: Turbo and Nx both send their token over it, and their
+ * self-hosted servers document such URLs (`TURBO_API=http://cache:3000`
+ * beside a CI service container; nx-cache-server's
+ * `NX_SELF_HOSTED_REMOTE_CACHE_SERVER=http://your-server:3000`). These
+ * plugins run such a repo unchanged.
+ */
+export function checkRemoteUrl(url: string, from: string): void {
+  // With no scheme every request failed on its own, as a bare "Invalid URL".
+  if (!/^https?:\/\//.test(url))
+    throw new UserError(`${from} must be an http(s) URL, got ${JSON.stringify(url)}`)
+  // The URL is printed in every refusal line, so a `user:pass@` in it would
+  // leak to the log. Credentials go in the token.
+  if (URL.canParse(url)) {
+    const u = new URL(url)
+    if (u.username !== '' || u.password !== '')
+      throw new UserError(
+        `${from} carries credentials (user:pass@); pass them as the token instead`,
+      )
+  }
+}