@vzn/vx 0.0.644 → 0.0.646

package/src/cli/init.ts

@@ -1,8 +1,8 @@
 // `vx init [--dry [--format json]] [--force] [--mjs] [--native|--keep]` — a workspace from nowhere.
-// Core reads no package.json (M, 2026-10-14): a repo with one (package.json
-// scripts, Turbo, Nx) is `@vzn/vx-migrate`'s, which maps it and installs
-// what it writes (`migrate`); without one, the workspace file and an empty
-// root project are written here, then the lock (`starter`).
+// It installs vx globally and, where a package.json is, as its devDependency
+// (M, 2026-10-20). A Turbo or Nx repo is `@vzn/vx-migrate`'s, which maps it
+// and installs what it writes (`migrate`); any other gets the workspace file
+// and an empty root project, then the lock (`starter`).
 // `vx init --plugin <seam>` writes a runnable plugin for one seam and its
 // test instead (plugin-templates.ts, the examples the gate runs).
 
@@ -13,13 +13,19 @@ import { gitTop, workspaceFileWritten } from '../handoff.js'
 import { flagHint, formatValue, refuse, seeHelp } from './help.js'
 import { lockAfterMigration } from './lock.js'
 import { PLUGIN_TEMPLATES } from './plugin-templates.js'
-import { isCompiledBinary, targetVersion } from './upgrade.js'
+import {
+  isCompiledBinary,
+  projectManager,
+  startedVersion,
+  targetVersion,
+  upgradeArgv,
+  type ManagedInstall,
+} from './upgrade.js'
 import { VERSION } from '../version.js'
 import { DOT_VX_GITATTRIBUTES, DOT_VX_GITIGNORE, ui, UserError, sayNotice } from '../util/index.js'
 import {
   findWorkspaceRoot,
   PROJECT_CONFIG_FILENAMES,
-  vxInvocation,
   WORKSPACE_CONFIG_FILENAMES,
 } from '../workspace/index.js'
 
@@ -107,13 +113,104 @@ export async function initCmd(args: readonly string[]): Promise<number> {
     dirs.push(d)
     if (d === top || path.dirname(d) === d) break
   }
-  const manifest = dirs.some((d) => MANIFESTS.some((f) => existsSync(path.join(d, f))))
-  if (manifest) return migrate(dirs, parsed)
-  return starter(marked ?? cwd, top === null, parsed)
+  if (dirs.some((d) => TOOL_CONFIGS.some((f) => existsSync(path.join(d, f))))) {
+    return migrate(dirs, parsed)
+  }
+  // The topmost package.json: a monorepo's root, wherever below it init ran.
+  const pkgRoot = dirs.findLast((d) => existsSync(path.join(d, 'package.json'))) ?? null
+  return starter(marked ?? pkgRoot ?? cwd, pkgRoot, top === null, parsed)
+}
+
+/** What makes a repo vx-migrate's to map: a Turbo or Nx config. */
+const TOOL_CONFIGS = ['turbo.json', 'turbo.jsonc', 'nx.json']
+
+/**
+ * The installs `vx init` runs (M, 2026-10-20): vx at `version` globally,
+ * with the manager that started init, so a bare `vx` is on PATH, unless
+ * the global vx already answers `version`; and, where `pkgRoot` has a
+ * package.json, as its devDependency with the repo's own manager.
+ */
+export function initInstalls(
+  version: string,
+  userAgent: string | undefined,
+  pkgRoot: string | null,
+  globalAt: string | undefined,
+  execPath = process.execPath,
+  plugins: readonly string[] = [],
+): { argv: string[]; cwd: string | null }[] {
+  const out: { argv: string[]; cwd: string | null }[] = []
+  if (globalAt !== version) {
+    const runner = /^(npm|pnpm|yarn|bun)\//.exec(userAgent ?? '')?.[1] ?? 'bun'
+    const manager = runner as ManagedInstall['manager']
+    out.push({ argv: upgradeArgv({ manager, scope: 'global', cwd: '' }, version), cwd: null })
+  }
+  if (pkgRoot !== null) {
+    const install: ManagedInstall = {
+      manager: projectManager(pkgRoot, execPath),
+      scope: 'project',
+      cwd: pkgRoot,
+      field: 'devDependencies',
+      plugins: [...plugins],
+    }
+    out.push({ argv: upgradeArgv(install, version), cwd: pkgRoot })
+  }
+  return out
 }
 
-/** What makes a repo vx-migrate's to map: a package manager's root, a Turbo or Nx config. */
-const MANIFESTS = ['package.json', 'pnpm-workspace.yaml', 'turbo.json', 'turbo.jsonc', 'nx.json']
+/** The version the global `vx` on PATH answers: not a runner's cache, not a project's bin. */
+function globalVersion(): string | undefined {
+  for (const dir of (process.env['PATH'] ?? '').split(path.delimiter)) {
+    const p = dir.split(path.sep).join('/')
+    if (p.includes('/_npx/') || /\/(bunx|dlx)-/.test(p) || p.includes('/node_modules/.bin'))
+      continue
+    const bin = path.join(dir, 'vx')
+    if (existsSync(bin)) return startedVersion(bin)?.split(' ')[1]
+  }
+  return undefined
+}
+
+/**
+ * Run `initInstalls`, in order. A source checkout (0.0.0, which npm never
+ * had) installs nothing: the release would replace the code under test.
+ */
+async function install(
+  pkgRoot: string | null,
+  dry: boolean,
+  plugins: readonly string[] = [],
+): Promise<string[]> {
+  if (VERSION === '0.0.0') return []
+  const version = await targetVersion(undefined, 'vx init')
+  const steps = initInstalls(
+    version,
+    process.env['npm_config_user_agent'],
+    pkgRoot,
+    globalVersion(),
+    process.execPath,
+    plugins,
+  )
+  if (dry) return steps.map((s) => s.argv.join(' '))
+  for (const s of steps) {
+    const bin = Bun.which(s.argv[0]!, { PATH: process.env['PATH'] ?? '' })
+    if (bin === null) {
+      throw new UserError(
+        `vx init: ${s.argv[0]} is not on PATH; run it yourself: ${s.argv.join(' ')}`,
+      )
+    }
+    ui.print(
+      'out',
+      ui.text([ui.cmd(s.argv.join(' ')), ui.dim(s.cwd === null ? '' : ` in ${s.cwd}`)]),
+    )
+    const proc = Bun.spawnSync({
+      cmd: [bin, ...s.argv.slice(1)],
+      cwd: s.cwd ?? process.cwd(),
+      stdio: ['inherit', 'inherit', 'inherit'],
+    })
+    if (proc.exitCode !== 0) {
+      throw new UserError(`vx init: ${s.argv.join(' ')} failed (exit ${proc.exitCode})`)
+    }
+  }
+  return steps.map((s) => s.argv.join(' '))
+}
 
 /** Write `plugins/<seam>.ts` and its test under `root`: the workspace root, else the cwd. */
 async function scaffoldPlugin(seam: string, root: string, args: InitArgs): Promise<number> {
@@ -145,30 +242,63 @@ async function scaffoldPlugin(seam: string, root: string, args: InitArgs): Promi
   return 0
 }
 
-const WORKSPACE =
-  "import { defineWorkspace } from '@vzn/vx'\n\nexport default defineWorkspace({ plugins: [] })\n"
+/**
+ * The `@vzn/vx-lockfile` plugin the lockfile at `pkgRoot` calls for: without
+ * it a JS workspace has no project edges, and the first `^build` a user
+ * writes is refused at `vx lock`.
+ */
+function lockfilePlugin(pkgRoot: string | null): 'pnpm' | 'bun' | 'yarn' | 'npm' | null {
+  if (pkgRoot === null) return null
+  const has = (f: string): boolean => existsSync(path.join(pkgRoot, f))
+  if (has('pnpm-lock.yaml')) return 'pnpm'
+  if (has('bun.lock') || has('bun.lockb')) return 'bun'
+  if (has('yarn.lock')) return 'yarn'
+  if (has('package-lock.json') || has('npm-shrinkwrap.json')) return 'npm'
+  return null
+}
+
+function workspaceSource(plugin: string | null): string {
+  if (plugin === null)
+    return "import { defineWorkspace } from '@vzn/vx'\n\nexport default defineWorkspace({ plugins: [] })\n"
+  return `import { defineWorkspace } from '@vzn/vx'\nimport { ${plugin} } from '@vzn/vx-lockfile'\n\nexport default defineWorkspace({ plugins: [${plugin}()] })\n`
+}
 const PROJECT =
   "import { defineProject } from '@vzn/vx'\n\nexport default defineProject({ tasks: {} })\n"
 
 /**
- * No package.json: `.vx/workspace.ts` declaring no plugin and a root
- * `vx.config.ts` with no task, then the lock. `@vzn/vx` resolves to the
- * running vx (core-alias.ts), so the two load with nothing installed.
- * A file already here is kept; `--force` replaces it.
+ * No Turbo or Nx config: the installs, then `.vx/workspace.ts` declaring
+ * no plugin and a root `vx.config.ts` with no task, then the lock.
+ * `@vzn/vx` resolves to the running vx (core-alias.ts), so the two load
+ * whatever got installed. A file already here is kept; `--force` replaces it.
  */
-async function starter(root: string, noGit: boolean, args: InitArgs): Promise<number> {
+async function starter(
+  root: string,
+  pkgRoot: string | null,
+  noGit: boolean,
+  args: InitArgs,
+): Promise<number> {
   if (args.mode !== undefined) {
     throw new UserError(
-      `vx init: --${args.mode} answers a Turbo or Nx repo's question, and there is no package.json here`,
+      `vx init: --${args.mode} answers a Turbo or Nx repo's question, and there is no turbo.json or nx.json here`,
     )
   }
+  // A source checkout installs nothing, so it declares the plugin only where one is.
+  const found = lockfilePlugin(pkgRoot)
+  const plugin =
+    found !== null &&
+    (VERSION !== '0.0.0' ||
+      existsSync(path.join(pkgRoot!, 'node_modules', '@vzn', 'vx-lockfile', 'package.json')))
+      ? found
+      : null
+  const plugins = plugin === null ? [] : ['@vzn/vx-lockfile']
+  const installs = args.json === true || args.dry ? await install(pkgRoot, true, plugins) : []
   const ext = args.mjs ? 'mjs' : 'ts'
   const config = `vx.config.${ext}`
   const files: { path: string; contents: string }[] = []
   const kept: string[] = []
   const replaced: string[] = []
   for (const [names, name, contents] of [
-    [WORKSPACE_CONFIG_FILENAMES, `.vx/workspace.${ext}`, WORKSPACE],
+    [WORKSPACE_CONFIG_FILENAMES, `.vx/workspace.${ext}`, workspaceSource(plugin)],
     [PROJECT_CONFIG_FILENAMES, config, PROJECT],
   ] as const) {
     const existing = names.find((n) => existsSync(path.join(root, n)))
@@ -185,16 +315,16 @@ async function starter(root: string, noGit: boolean, args: InitArgs): Promise<nu
   ] as const) {
     if (!existsSync(path.join(root, name))) files.push({ path: name, contents })
   }
-  const vx = vxInvocation(process.env['npm_config_user_agent'], false)
-  const next = `${noGit ? 'git init, ' : ''}declare a task in ${kept.find((f) => f.startsWith('vx.config.')) ?? config}, then ${vx} lock && ${vx} run <task>`
+  const next = `${noGit ? 'git init, ' : ''}declare a task in ${kept.find((f) => f.startsWith('vx.config.')) ?? config}, then vx lock && vx run <task>`
   if (args.json === true) {
     process.stdout.write(
-      `${JSON.stringify({ dry: true, source: 'no package.json', files, kept, replaced, todos: [], notes: [], next })}\n`,
+      `${JSON.stringify({ dry: true, source: 'no turbo.json or nx.json', files, kept, replaced, todos: [], notes: [], next, installs })}\n`,
     )
     return 0
   }
-  const rows: ui.FieldRow[] = [['from', 'no package.json: one project, the root']]
+  const rows: ui.FieldRow[] = [['from', 'no turbo.json or nx.json: one project, the root']]
   if (args.dry) rows.push(['dry run', 'nothing written'])
+  if (installs.length > 0) rows.push(['install', ...installs])
   if (files.length > 0) rows.push(['files', ...files.map((f) => f.path)])
   if (kept.length > 0) rows.push(['kept', ...kept])
   if (replaced.length > 0) rows.push(['replaced', ...replaced])
@@ -203,6 +333,8 @@ async function starter(root: string, noGit: boolean, args: InitArgs): Promise<nu
     ui.print('out', ui.report(`vx init ${VERSION}`, [...rows, null, ['next', next]]))
     return 0
   }
+  const ran = await install(pkgRoot, false, plugins)
+  if (ran.length > 0) rows.push(['installed', ...ran])
   for (const f of files) await Bun.write(path.join(root, f.path), f.contents)
   for (const f of replaced) await unlink(path.join(root, f))
   // The lock that follows loads the workspace file just written.
@@ -217,7 +349,7 @@ async function starter(root: string, noGit: boolean, args: InitArgs): Promise<nu
 }
 
 /**
- * A repo with a package.json is `@vzn/vx-migrate`'s, at the latest
+ * A Turbo or Nx repo is `@vzn/vx-migrate`'s, after the global install, at the latest
  * release: it installs @vzn/vx and every @vzn/vx-* plugin the root lists
  * at its own version, so init always lands on latest with all of them
  * together, as `vx upgrade` moves them (M, 2026-10-16: an installed 0.0.637
@@ -232,6 +364,8 @@ async function migrate(dirs: readonly string[], args: InitArgs): Promise<number>
     args.mode !== undefined && `--${args.mode}`,
     args.json === true && '--format=json',
   ].filter((f): f is string => typeof f === 'string')
+  // vx-migrate installs the project's own vx.
+  if (!args.dry) await install(null, false)
   // An exact version: `bun x` may answer `@latest` from its cache.
   const latest = VERSION === '0.0.0' ? 'latest' : await targetVersion(undefined, 'vx init')
   return Bun.spawn(migrateCommand(dirs, flags, latest), {

package/src/cli/last.ts

@@ -365,10 +365,12 @@ export function formatTaskRows(tasks: readonly RunSummaryRow[]): string[] {
     ? [...hits].sort((a, b) => b.durationMs - a.durationMs).slice(0, HITS_SHOWN)
     : hits
   const ordered = [...failed, ...rest, ...shownHits]
-  const idW = Math.max(...ordered.map((t) => `${t.project}#${t.task}`.length), 4)
+  const at = (t: (typeof ordered)[number]): string =>
+    t.placement !== null ? `@${t.placement}` : ''
+  const idW = Math.max(...ordered.map((t) => `${t.project}#${t.task}${at(t)}`.length), 4)
   const lines = ['']
   for (const t of ordered) {
-    const id = `${t.project}#${t.task}`
+    const id = `${t.project}#${t.task}${at(t)}`
     // The terminal summary's own word for a task that runs every time
     // by design; a reader must not take its row for a miss.
     // A failure's row reads as the frame did — `failed (exit 137)` —

package/src/cli/plan-format.ts

@@ -1,7 +1,7 @@
 // Formatters for `--dry` (human / JSON).
 
 import type { AffectedReason, CacheStatus, RunPlan } from '../orchestrator/index.js'
-import { formatElapsed, maskedCommand } from '../util/index.js'
+import { formatBytes, formatElapsed, maskedCommand } from '../util/index.js'
 
 /**
  * Human-readable preview. One line per real task (groups hidden, same
@@ -65,7 +65,11 @@ export function formatPlanText(plan: RunPlan): string {
 
   const hitParts: string[] = []
   if (local > 0) hitParts.push(`${local} local`)
-  if (remote > 0) hitParts.push(`${remote} remote`)
+  if (remote > 0) {
+    // The remote's sizes, summed: what restoring the hits would download.
+    const bytes = real.reduce((sum, t) => sum + (t.remoteBytes ?? 0), 0)
+    hitParts.push(bytes > 0 ? `${remote} remote, ${formatBytes(bytes)}` : `${remote} remote`)
+  }
   const hits = local + remote
   const summary: string[] = [`${real.length} task(s) planned`]
   if (hits > 0) summary.push(`${hits} cache hit${hits === 1 ? '' : 's'} (${hitParts.join(', ')})`)

package/src/cli/plugin-commands.ts

@@ -9,9 +9,16 @@
 
 import type { CachePolicy, PluginCache, ResolvedRemote } from '../cache/index.js'
 import type { WorkspaceConfig } from '../config.js'
-import type { BranchFacts, VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
+import type {
+  BranchFacts,
+  VxPlugin,
+  PluginCommand,
+  CommandContext,
+  CacheFacts,
+  TaskArtifacts,
+} from '../orchestrator/index.js'
 import { configuredBaseBranch, findWorkspaceRoot } from '../workspace/index.js'
-import { machineParallelism, maskedLine } from '../util/index.js'
+import { machineParallelism, maskedLine, SecretBroker } from '../util/index.js'
 import { resolveSetting } from '../settings.js'
 
 export interface ResolvedPluginCommand {
@@ -111,6 +118,8 @@ export async function resolvePluginCommand(
           : [process.execPath, Bun.main],
         warn,
         cache: lazyCache(() => verbCache(ws, plugin.name)),
+        artifacts: lazyArtifacts(() => verbArtifacts(ws)),
+        artifactsFor: (facts) => lazyArtifacts(() => verbArtifacts(ws, facts)),
       },
     }
   }
@@ -138,10 +147,8 @@ async function verbCache(
   ws: Exclude<Awaited<ReturnType<typeof workspacePlugins>>, UnresolvedPluginCommand | null>,
   plugin: string,
 ): Promise<PluginCache> {
-  const [{ Cache, pluginCache }, { resolveCache, resolveCacheScope }] = await Promise.all([
-    import('../cache/index.js'),
-    import('../orchestrator/index.js'),
-  ])
+  const [{ Cache, pluginCache }, { cacheRefs, openRemotes, resolveCache, resolveCacheScope }] =
+    await Promise.all([import('../cache/index.js'), import('../orchestrator/index.js')])
   const scope = resolveCacheScope(
     ws.workspaceRoot,
     ws.branch.trusted === true ? null : ws.branch.scope,
@@ -162,13 +169,98 @@ async function verbCache(
     cacheDir: ws.cacheDir,
     warn,
     scope,
+    refs: cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig)),
     localCache,
     policy: VERB_POLICY,
     remotes,
   })
+  await openVerbRemotes(remotes, openRemotes)
   return pluginCache(plugin, { db: localCache.dbHandle(), policy: VERB_POLICY, remotes, scope })
 }
 
+/**
+ * The verb's `ctx.artifacts`: the workspace's cache as a run opens it, its
+ * policy and scope, a laptop writing no remote unless the policy names it.
+ * With `facts` (`ctx.artifactsFor`), under another run's refs and lent access.
+ */
+async function verbArtifacts(
+  ws: Exclude<Awaited<ReturnType<typeof workspacePlugins>>, UnresolvedPluginCommand | null>,
+  facts?: () => CacheFacts | undefined,
+): Promise<TaskArtifacts> {
+  const [
+    { Cache, FULL_CACHE_POLICY },
+    {
+      cacheRefs,
+      namesRemote,
+      openRemotes,
+      resolveCache,
+      resolveCacheScope,
+      taskArtifacts,
+      workspaceCachePolicy,
+    },
+    { onCI },
+  ] = await Promise.all([
+    import('../cache/index.js'),
+    import('../orchestrator/index.js'),
+    import('./run.js'),
+  ])
+  const asked = workspaceCachePolicy(ws.workspaceConfig) ?? FULL_CACHE_POLICY
+  const policy: CachePolicy =
+    onCI(process.env['CI']) || namesRemote(ws.workspaceConfig?.cache?.policy)
+      ? asked
+      : { ...asked, remoteWrite: false }
+  const scope = resolveCacheScope(
+    ws.workspaceRoot,
+    ws.branch.trusted === true ? null : ws.branch.scope,
+    ws.plugins.some((p) => p.cache !== undefined),
+    configuredBaseBranch(ws.workspaceConfig),
+  )
+  const localCache = new Cache(
+    ws.cacheDir,
+    { read: policy.localRead, write: policy.localWrite },
+    ws.workspaceRoot,
+    undefined,
+    'open',
+    await ws.storeRoot,
+  )
+  const remotes: ResolvedRemote[] = []
+  const cache = await resolveCache(ws.plugins, {
+    workspaceRoot: ws.workspaceRoot,
+    cacheDir: ws.cacheDir,
+    warn,
+    scope,
+    refs: facts?.()?.refs ?? cacheRefs(ws.workspaceRoot, configuredBaseBranch(ws.workspaceConfig)),
+    localCache,
+    policy,
+    remotes,
+    ...(facts === undefined ? {} : { lentBy: () => facts()?.lent }),
+  })
+  await openVerbRemotes(remotes, openRemotes)
+  return taskArtifacts(cache, ws.workspaceRoot)
+}
+
+/**
+ * Each remote's `open`, as a run's: a remote that takes its token there
+ * (turboCache's OIDC exchange, a lent token) had none, so an agent's
+ * uploads went nowhere and its run could not restore them.
+ */
+async function openVerbRemotes(
+  remotes: readonly ResolvedRemote[],
+  open: (typeof import('../orchestrator/index.js'))['openRemotes'],
+): Promise<void> {
+  const ci = (await import('./run.js')).onCI(process.env['CI'])
+  await open(remotes, ci, new SecretBroker(ci, warn))
+}
+
+function lazyArtifacts(open: () => Promise<TaskArtifacts>): TaskArtifacts {
+  let opened: Promise<TaskArtifacts> | undefined
+  const artifacts = (): Promise<TaskArtifacts> => (opened ??= open())
+  return {
+    save: async (key, task, run) => (await artifacts()).save(key, task, run),
+    restore: async (key, task) => (await artifacts()).restore(key, task),
+  }
+}
+
 function lazyCache(open: () => Promise<PluginCache>): PluginCache {
   let opened: Promise<PluginCache> | undefined
   const cache = (): Promise<PluginCache> => (opened ??= open())

package/src/cli/plugin-templates.ts

@@ -10,13 +10,13 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   },
   cache: {
     plugin:
-      "// `cache`: where artifacts live. A directory stands in for a remote store;\n// core puts it behind the local cache, so a remote error is a miss and a\n// warning, never a failed run.\nimport { link, mkdir, unlink } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<boolean> {\n    return Bun.file(path.join(this.endpoint, hash)).exists()\n  }\n  async get(hash: string) {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { body: file, durationMs: undefined } : null\n  }\n  async put(hash: string, body: Blob): Promise<void> {\n    await mkdir(this.endpoint, { recursive: true })\n    // Written aside, then linked: on a shared directory a rename can swap\n    // the file under a reader, while a link never replaces an existing one.\n    // EEXIST is success: the same hash means the same bytes.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    try {\n      await link(tmp, path.join(this.endpoint, hash))\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err\n    } finally {\n      await unlink(tmp)\n    }\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache() {\n      return new DirRemote(dir)\n    },\n  })\n}\n",
+      "// `cache`: where artifacts live. A directory stands in for a remote store;\n// core puts it behind the local cache, so a remote error is a miss and a\n// warning, never a failed run.\nimport { link, mkdir, unlink } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, type ArtifactInfo, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<ArtifactInfo | null> {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { size: file.size } : null\n  }\n  async get(hash: string) {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { body: file, durationMs: undefined } : null\n  }\n  async put(hash: string, body: Blob): Promise<void> {\n    await mkdir(this.endpoint, { recursive: true })\n    // Written aside, then linked: on a shared directory a rename can swap\n    // the file under a reader, while a link never replaces an existing one.\n    // EEXIST is success: the same hash means the same bytes.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    try {\n      await link(tmp, path.join(this.endpoint, hash))\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err\n    } finally {\n      await unlink(tmp)\n    }\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache() {\n      return new DirRemote(dir)\n    },\n  })\n}\n",
     test: "// A test for the example `cache` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-cache-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `dirCache()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'cache.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { dirCache } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('a run on an empty local cache restores from the directory', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'mkdir -p dist && echo built > dist/out.txt' },\n      inputs: { files: ['package.json'] }, cache: { outputs: { files: ['dist/**'] } },\n    } } }`,\n  )\n  await workspace(`dirCache(${JSON.stringify(path.join(root, 'remote'))})`)\n  const first = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(first.outcomes.map((o) => o.status)).toEqual(['success'])\n  await rm(path.join(root, '.vx', 'cache'), { recursive: true, force: true })\n  await rm(path.join(dir, 'dist'), { recursive: true, force: true })\n  const second = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(second.outcomes.map((o) => o.status)).toEqual(['cache-hit-remote'])\n  expect(await Bun.file(path.join(dir, 'dist', 'out.txt')).text()).toBe('built\\n')\n}, 20_000)\n",
   },
   commands: {
     plugin:
       "// `commands`: a CLI verb. `vx cache-dir` prints where this workspace's cache\n// lives. The verb's return value is the exit code.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function cacheDirVerb(): VxPlugin {\n  return definePlugin(import.meta, {\n    commands: {\n      'cache-dir': {\n        description: \"print this workspace's cache directory\",\n        run(argv, ctx) {\n          if (argv.length > 0) {\n            console.error(`vx cache-dir: takes no arguments, got ${argv.join(' ')}`)\n            return 2\n          }\n          console.log(ctx.cacheDir)\n          return 0\n        },\n      },\n    },\n  })\n}\n",
-    test: "// A test for the example `commands` plugin beside it: the verb is called\n// the way vx calls it, with the context vx hands it. `bun test` runs it.\nimport { expect, it, spyOn } from 'bun:test'\nimport { cacheDirVerb } from './commands.ts'\n\nconst verb = cacheDirVerb().commands!['cache-dir']!\nconst ctx = {\n  workspaceRoot: '/ws',\n  cacheDir: '/ws/.vx/cache',\n  warn() {},\n  concurrency: 1,\n  vx: ['vx'],\n  cache: {\n    get: async () => null,\n    put: async () => {},\n    has: async () => null,\n    hasMany: async () => null,\n    getRun: async () => null,\n  },\n}\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(console, 'log').mockImplementation(() => {})\n  const err = spyOn(console, 'error').mockImplementation(() => {})\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    expect(err.mock.calls).toEqual([['vx cache-dir: takes no arguments, got x']])\n  } finally {\n    out.mockRestore()\n    err.mockRestore()\n  }\n})\n",
+    test: "// A test for the example `commands` plugin beside it: the verb is called\n// the way vx calls it, with the context vx hands it. `bun test` runs it.\nimport { expect, it, spyOn } from 'bun:test'\nimport { cacheDirVerb } from './commands.ts'\n\nconst verb = cacheDirVerb().commands!['cache-dir']!\nconst ctx = {\n  workspaceRoot: '/ws',\n  cacheDir: '/ws/.vx/cache',\n  warn() {},\n  concurrency: 1,\n  vx: ['vx'],\n  cache: {\n    get: async () => null,\n    put: async () => {},\n    has: async () => null,\n    hasMany: async () => null,\n    getRun: async () => null,\n  },\n  artifacts: { save: async () => {}, restore: async () => null },\n  artifactsFor: () => ({ save: async () => {}, restore: async () => null }),\n}\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(console, 'log').mockImplementation(() => {})\n  const err = spyOn(console, 'error').mockImplementation(() => {})\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    expect(err.mock.calls).toEqual([['vx cache-dir: takes no arguments, got x']])\n  } finally {\n    out.mockRestore()\n    err.mockRestore()\n  }\n})\n",
   },
   executor: {
     plugin:

package/src/cli/run.ts

@@ -1,6 +1,5 @@
 import { isatty } from 'node:tty'
 import { findWorkspaceRoot } from '../workspace/index.js'
-import { translateForeign } from './foreign-flags.js'
 import { flagHint, refuse, seeHelp } from './help.js'
 import {
   planRun,
@@ -116,7 +115,7 @@ const SETTING_OPTIONS = [
 
 /** `verb` is the one being parsed for: `vx watch` reads `vx run`'s flags, and
  * its flag hints named `vx run` (M-58). The caller appends the help pointer. */
-export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' = 'run'): RunArgs {
+export function parseRunArgs(args: readonly string[], verb: 'run' | 'watch' = 'run'): RunArgs {
   const out: RunArgs = {
     tasks: [],
     filters: [],
@@ -132,10 +131,6 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
     affected: undefined,
   }
 
-  // A Turbo or Nx spelling becomes vx's, or a refusal naming vx's.
-  const translated = translateForeign(rawArgs)
-  if ('error' in translated) return { ...out, error: translated.error }
-  const args = translated
   const sepIdx = args.indexOf('--')
   const before = sepIdx === -1 ? args : args.slice(0, sepIdx)
   out.forwardArgs = sepIdx === -1 ? [] : args.slice(sepIdx + 1)
@@ -518,7 +513,6 @@ export async function resolveRunOptions(
   }
   if (parsed.profile !== undefined) opts.profile = parsed.profile
   // `--affected`'s base is the branch's for the cache scope too.
-  if (affectedFilter !== undefined) opts.scopeBase = affectedFilter.slice(4, -1)
 
   return opts
 }
@@ -664,6 +658,6 @@ export async function runCmd(args: readonly string[]): Promise<number> {
 }
 
 /** CI=0 and CI=false are "not CI": several vendors set CI=true. */
-function onCI(v: string | undefined): boolean {
+export function onCI(v: string | undefined): boolean {
   return v !== undefined && v !== '' && v !== '0' && v !== 'false'
 }

package/src/cli/select.ts

@@ -4,6 +4,7 @@
 // here goes through the staged load, so the answer is the run's.
 
 import path from 'node:path'
+import { settingEnv } from '../settings.js'
 import fs from 'node:fs'
 import {
   affectedChanges,
@@ -244,12 +245,13 @@ function refusalOf(err: unknown): Refusal {
 
 /**
  * The filter `--affected[=<base>]` stands for: `...[<base>]`, the changed
- * projects and their dependents. An empty base is a plugin's (`setBranch`:
- * a pull request's base commit), else the merge base with `baseBranch`.
+ * projects and their dependents. An empty base is `VX_AFFECTED_BASE`'s,
+ * else a plugin's (`setBranch`: a pull request's base commit), else the
+ * merge base with `baseBranch`.
  */
 export async function affectedFilterFor(cwd: string, affected: string): Promise<string | Refusal> {
   const root = await findWorkspaceRoot(cwd)
-  let base = affected
+  let base = affected || ((settingEnv('affectedBase') as string | undefined) ?? '')
   if (base === '') {
     const ws = await loadCliWorkspace(root)
     try {

package/src/cli/upgrade.ts

@@ -228,7 +228,7 @@ export function verifiedRelease(
   const ours = signatures.filter((s) => s.keyid === key.id)
   if (ours.length === 0) {
     throw new UserError(
-      `vx upgrade: ${pkg}@${version} is signed with an npm key this vx does not know (${[...new Set(signatures.map((s) => s.keyid))].join(', ')}) — if npm rotated its signing key, this vx's installer needs updating: install the new release with npm install -g @vzn/vx@latest, or from https://github.com/vznjs/vx/releases. Nothing replaced`,
+      `vx upgrade: ${pkg}@${version} is signed with an npm key this vx does not know (${[...new Set(signatures.map((s) => s.keyid))].join(', ')}) — if npm rotated its signing key, this vx's installer needs updating: install the new release with bun add -g @vzn/vx@latest, or from https://github.com/vznjs/vx/releases. Nothing replaced`,
     )
   }
   const publicKey = createPublicKey({
@@ -475,7 +475,7 @@ function installedVersion(dir: string, pkg: string): string | undefined {
 }
 
 /** The project's package manager: its lockfile, then `packageManager`, then the tree's shape. */
-function projectManager(dir: string, execPath: string): ManagedInstall['manager'] {
+export function projectManager(dir: string, execPath: string): ManagedInstall['manager'] {
   for (let d = dir; ; d = path.dirname(d)) {
     if (existsSync(path.join(d, 'pnpm-lock.yaml'))) return 'pnpm'
     if (existsSync(path.join(d, 'bun.lock')) || existsSync(path.join(d, 'bun.lockb'))) return 'bun'
@@ -511,7 +511,7 @@ export function managedInstall(execPath: string, cwd: string): ManagedInstall |
   const root = p.slice(0, `${p}/`.indexOf('/node_modules/'))
   if (p.includes('/_npx/') || /\/bunx-[^/]*\//.test(p)) {
     throw new UserError(
-      `vx upgrade: this vx runs from a package-manager cache (${execPath}) — nothing is installed to upgrade; ask for the version you want instead: npx @vzn/vx@latest, or bunx @vzn/vx@latest`,
+      `vx upgrade: this vx runs from a package-manager cache (${execPath}) — nothing is installed to upgrade; ask for the version you want instead: bunx @vzn/vx@latest`,
     )
   }
   if (p.includes('/.bun/install/global/')) return { manager: 'bun', scope: 'global', cwd: root }
@@ -733,7 +733,7 @@ export async function upgradeOnlyGlobal(
   const install = managedInstall(self, path.dirname(self))
   if (install?.scope === 'project') {
     throw new UserError(
-      `vx upgrade -g: no global vx ran — ${self} is the project's own. Install one (npm install -g ${PACKAGE}), or run \`vx upgrade\` to move the project's`,
+      `vx upgrade -g: no global vx ran — ${self} is the project's own. Install one (bun add -g ${PACKAGE}), or run \`vx upgrade\` to move the project's`,
     )
   }
   if (install === null) await upgradeBinary(self, version, current, 'global ')
@@ -771,8 +771,7 @@ export async function upgradeCmd(argv: readonly string[]): Promise<number> {
   }
   if (!isCompiledBinary()) {
     throw new UserError(
-      'vx upgrade: only the compiled binary upgrades itself; this vx runs from source — use git pull ' +
-        '(npm installs update with: npm install -g @vzn/vx@latest)',
+      'vx upgrade: only the compiled binary upgrades itself; this vx runs from source — use git pull',
     )
   }
   const dest = process.execPath

package/src/config.ts

@@ -102,11 +102,9 @@ export interface CacheSettings {
    * How the local cache keeps an entry. `embeddings` (default `'32KiB'`):
    * an entry up to this size inside the index; `false`, none. `decompress` (default true): a larger one as its
    * plain files, which a hit copies or clones out with no decode; off, as
-   * one `.tar.zst`. `verify` (default `'stat'`): what a hit on plain files
-   * checks first, each file's size and mtime, every byte (`'hash'`), or
-   * nothing (`'none'`).
+   * one `.tar.zst`.
    */
-  store?: { embeddings?: false | string; decompress?: boolean; verify?: 'stat' | 'hash' | 'none' }
+  store?: { embeddings?: false | string; decompress?: boolean }
   /**
    * Cache transfers at once. `download` and `upload` (per remote) default
    * to min(96, max(cores × 3, 64)); `restore`, local hits writing their