@vzn/vx 0.0.278 → 0.0.280

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.278",
+  "version": "0.0.280",
   "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.278",
-    "@vzn/vx-linux-arm64": "0.0.278",
-    "@vzn/vx-darwin-x64": "0.0.278",
-    "@vzn/vx-darwin-arm64": "0.0.278"
+    "@vzn/vx-linux-x64": "0.0.280",
+    "@vzn/vx-linux-arm64": "0.0.280",
+    "@vzn/vx-darwin-x64": "0.0.280",
+    "@vzn/vx-darwin-arm64": "0.0.280"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/bin.ts

@@ -1,26 +1,25 @@
 #!/usr/bin/env -S bun --no-env-file --no-install
-import { registerCoreAlias, run } from './cli/index.js'
-import {
-  fsRefusalHint,
-  isFsRefusal,
-  isOutOfFds,
-  isUserError,
-  OUT_OF_FDS_HINT,
-} from './util/index.js'
-
-// Every `import … from '@vzn/vx'` this process evaluates — a plugin
-// package, a workspace or project config — resolves to THIS core, not to
-// a second copy from node_modules (core-alias.ts says why and what it
-// costs). Registered before any verb runs; the façade loads on first use.
-registerCoreAlias(() => import('./index.js') as Promise<Record<string, unknown>>)
-
 // Wrapped in an explicit async main so `bun build --compile` accepts
 // the file. The compile target doesn't allow top-level await.
 let settled = false
 
 async function main(): Promise<void> {
+  const argv = process.argv.slice(2)
   try {
-    const code = await run(process.argv.slice(2))
+    // `vx --version` needs one leaf module; the dispatcher and the util
+    // barrel it pulled in were 20 ms of its 28 (2026-10-01).
+    if (argv.length === 1 && (argv[0] === '--version' || argv[0] === 'version')) {
+      process.stdout.write(`vx ${(await import('./version.js')).VERSION}\n`)
+      settled = true
+      return
+    }
+    const { registerCoreAlias, run } = await import('./cli/index.js')
+    // Every `import … from '@vzn/vx'` this process evaluates — a plugin
+    // package, a workspace or project config — resolves to THIS core, not to
+    // a second copy from node_modules (core-alias.ts says why and what it
+    // costs). Registered before any verb runs; the façade loads on first use.
+    registerCoreAlias(() => import('./index.js') as Promise<Record<string, unknown>>)
+    const code = await run(argv)
     // NOTHING calls `process.exit` here, and that is the fix rather than a
     // simplification. Bun drops what a pipe has not yet taken when
     // `process.exit` follows a large write: 300 KB written then exit
@@ -34,6 +33,8 @@ async function main(): Promise<void> {
     // several hundred spawns of this binary would show at once.
     process.exitCode = code
   } catch (err) {
+    const { fsRefusalHint, isFsRefusal, isOutOfFds, isUserError, OUT_OF_FDS_HINT } =
+      await import('./util/index.js')
     // UserError (workspace not found, cycle, config invalid, ...) —
     // print the message only; the stack is noise the user can't act
     // on. Everything else gets the full stack so internal bugs are

package/src/cli/help.ts

@@ -61,7 +61,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                             foo, @scope/*, ./packages/foo, foo..., ...foo,',
     '                             foo^..., !foo, [<since>]',
     '      --affected[=<base>]  Sugar for --filter "...[<base>]". Default base =',
-    '                             origin/HEAD (falls back to HEAD~1).',
+    '                             affectedBase, else origin/HEAD, else HEAD~1.',
     "  pkg#task                 Run a specific project's task directly.",
     '',
     'Execution (for run):',
@@ -216,6 +216,9 @@ export function flagHint(verb: string, arg: string): string {
   if (!arg.startsWith('-')) return ''
   const name = arg.replace(/=.*$/, '')
   const flags = acceptedFlags(verb)
+  // `--json` is gh's and Nx's spelling; a verb with `--format` reads it
+  // there, and no edit budget reaches `--format json` from `--json`.
+  if (name === '--json' && flags.includes('--format')) return ' (did you mean --format json?)'
   // A flag cut short at a word (`--dry` for prune's `--dry-run`, which
   // `vx run` spells `--dry`) is too many edits away for either budget.
   const cut = flags.filter((f) => f.startsWith(`${name}-`))

package/src/cli/init.ts

@@ -180,7 +180,9 @@ async function adopt(
       : `wrote ${name}.`
   const cacheLine =
     remote === undefined
-      ? ''
+      ? runner === 'nx' && usesNxCloud(root)
+        ? 'nx.json connects Nx Cloud, whose cache vx cannot share: runs cache on this machine (nxCache() serves a self-hosted Nx cache).\n'
+        : ''
       : kept && !readFileSync(path.join(root, existing), 'utf8').includes(`${cache}(`)
         ? `${remote}: add ${cache}() from @vzn/vx-migrate to its plugins and vx shares that remote cache.\n`
         : kept
@@ -195,6 +197,31 @@ async function adopt(
 
 const REMOTE_CACHE = { turbo: 'turboCache', nx: 'nxCache' } as const
 
+/**
+ * nx.json names an Nx Cloud workspace (`nxCloudId`, `nxCloudAccessToken`,
+ * or the legacy `nx-cloud` runner). Its wire is Nx's own, so a user who
+ * expected their remote cache under vx heard nothing and ran cold.
+ */
+function usesNxCloud(root: string): boolean {
+  let json: {
+    nxCloudId?: unknown
+    nxCloudAccessToken?: unknown
+    tasksRunnerOptions?: { default?: { runner?: unknown } }
+  } | null
+  try {
+    json = Bun.JSONC.parse(readFileSync(path.join(root, 'nx.json'), 'utf8')) as typeof json
+  } catch {
+    return false
+  }
+  const set = (v: unknown) => typeof v === 'string' && v !== ''
+  const runner = json?.tasksRunnerOptions?.default?.runner
+  return (
+    set(json?.nxCloudId) ||
+    set(json?.nxCloudAccessToken) ||
+    (typeof runner === 'string' && /(^|\/)nx-cloud$/.test(runner))
+  )
+}
+
 /** The variable each runner's self-hosted remote cache is set by, as its plugin reads it. */
 const REMOTE_CACHE_ENV = { turbo: 'TURBO_TOKEN', nx: 'NX_SELF_HOSTED_REMOTE_CACHE_SERVER' } as const
 
@@ -202,7 +229,7 @@ const CI_FILES = ['.gitlab-ci.yml', '.circleci/config.yml']
 
 /**
  * Where the repo shows a remote cache its runner uses, or undefined: turbo.json's
- * enabled `remoteCache`, or a CI file that sets the runner's cache variable (a
+ * enabled `remoteCache`, a `turbo link`ed `.turbo/config.json`, or a CI file that sets the runner's cache variable (a
  * local repo holds no token; CI does).
  */
 function remoteCacheSignal(root: string, runner: 'turbo' | 'nx'): string | undefined {
@@ -222,6 +249,21 @@ function remoteCacheSignal(root: string, runner: 'turbo' | 'nx'): string | undef
         return `${f} names a remoteCache`
       }
     }
+    // `turbo link` writes the team here (gitignored, on the machine that
+    // linked); turboCache() reads it, so a linked repo has a remote cache.
+    let linked: unknown
+    try {
+      linked = JSON.parse(readFileSync(path.join(root, '.turbo', 'config.json'), 'utf8'))
+    } catch {}
+    if (
+      typeof linked === 'object' &&
+      linked !== null &&
+      Object.entries(linked).some(
+        ([k, v]) => /^(teamid|teamslug|token)$/i.test(k) && typeof v === 'string' && v !== '',
+      )
+    ) {
+      return '.turbo/config.json links a team (turbo link)'
+    }
   }
   const variable = REMOTE_CACHE_ENV[runner]
   // A line that sets it (`TURBO_TOKEN: …`, `TURBO_TOKEN=…`), not one that

package/src/cli/run.ts

@@ -17,6 +17,7 @@ import type { ContinueMode } from '../graph/index.js'
 import { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
 import { findCwdSelection, pickTask, resolveFilters } from './select.js'
 import { nxTargetHint, taskNamesHere } from './task-verb.js'
+import { loadCliWorkspace } from './workspace-config.js'
 import { MAX_TIMEOUT_MS, isUserError, parseDecimalInt, machineParallelism } from '../util/index.js'
 import { formatGraphDot, formatPlanJson, formatPlanText } from './plan-format.js'
 
@@ -464,6 +465,9 @@ export async function resolveRunOptions(
   if (parsed.affected !== undefined) {
     const root = await findWorkspaceRoot(cwd)
     let base = parsed.affected
+    // The workspace's `affectedBase` — or a plugin's `config` stage, from
+    // nx.json's `defaultBase` or `TURBO_SCM_BASE` — comes before the guess.
+    if (base === '') base = (await loadCliWorkspace(root)).workspaceConfig?.affectedBase ?? ''
     if (base === '') {
       try {
         base = await defaultAffectedBase(root)

package/src/config.ts

@@ -22,6 +22,12 @@ export interface WorkspaceConfig {
    * folded into a cache key.
    */
   cacheRetention?: { olderThan?: string; maxSize?: string }
+  /**
+   * The git ref a bare `--affected` compares with (`origin/develop`).
+   * `--affected=<base>` overrides it. Omitted → `origin/HEAD`, else
+   * `HEAD~1`. Never folded into a cache key.
+   */
+  affectedBase?: string
   /**
    * Plugins registered for this workspace, consulted in this order once
    * per `vx run`: each fills any of the pipeline stages and capabilities

package/src/workspace/config-schema.ts

@@ -35,6 +35,7 @@ const WORKSPACE_FIELDS = new Set([
   'cacheDir',
   'timeout',
   'cacheRetention',
+  'affectedBase',
   'plugins',
 ])
 
@@ -105,6 +106,12 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
     assertTimeoutInRange(config.timeout, `${configPath}: \`timeout\``)
   }
   if (config.cacheRetention !== undefined) validateRetention(config.cacheRetention, configPath)
+  if (config.affectedBase !== undefined) {
+    // A leading '-' would reach git as an option, not a ref.
+    if (typeof config.affectedBase !== 'string' || !/^[^-\s]\S*$/.test(config.affectedBase)) {
+      throw new UserError(`${configPath}: \`affectedBase\` must be a git ref like 'origin/main'`)
+    }
+  }
   if (config.plugins !== undefined) {
     if (!Array.isArray(config.plugins)) {
       throw new UserError(`${configPath}: \`plugins\` must be an array of plugin objects`)
@@ -768,7 +775,7 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
         'a cache plugin in `plugins` (`turboCache()` or `nxCache()` from `@vzn/vx-migrate`)',
       parallel: '`concurrency`',
       cacheDirectory: '`cacheDir`',
-      defaultBase: 'the base in `--affected=<base>` (default `origin/HEAD`)',
+      defaultBase: '`affectedBase`',
       tasksRunnerOptions: 'a cache plugin in `plugins` (`nxCache()` from `@vzn/vx-migrate`)',
       globalPassThroughEnv: '`exec.env.passThrough` on the tasks it passes to',
     },