@vzn/vx-migrate 0.0.635 → 0.0.637

package/src/turbo/turbo-map.ts

@@ -12,24 +12,25 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
-import { buildPackageGraph, pruneOrphanPersistentNotes, type ProjectMeta, UserError } from '@vzn/vx'
+import { isLiteralPattern, pruneOrphanPersistentNotes, UserError } from '@vzn/vx'
+import type { PackageMeta } from '../packages.js'
 import { literalGlob, minimatchToVx, withoutTakenBack } from '../glob-grammar.js'
 import { shellQuote } from '../nx-command.js'
 import { scriptCommand, yarnPnp } from '../script-command.js'
 import {
-  ownFileOutput,
-  ownFileTodo,
+  ownFileTakeBacks,
   excludeSiblingOutputs,
   excludeWorkspaceOutputs,
   resolveSharedOutputs,
   resolveSharedWorkspaceOutputs,
   takingBack,
-  literalTailMatches,
+  wildcardCleanTodo,
   wildcardOutput,
   wildcardTodo,
 } from '../shared-outputs.js'
+import { manifestGraph, type ManifestGraph } from '../manifest-graph.js'
 import { isRecord, packageScripts, relPosix } from '../paths.js'
-import { MAX_SPARED, type TrackedKinds } from '../tracked-outputs.js'
+import type { TrackedKinds } from '../tracked-outputs.js'
 import {
   DOTENV_PROBE,
   DOTENV_PROBE_TOP,
@@ -76,7 +77,7 @@ const keyable = (name: string): boolean =>
  * one of `configs` (turbo.json texts, any string, a superset) or in Turbo's
  * framework table matches, and each core cannot key (a literal one is
  * dropped only when no variable has it). The kept mapping keyed on every
- * name, so any variable that came or went (a CI step's, `VX_TIMING`)
+ * name, so any variable that came or went (a CI step's, `VX_DEBUG_TIMING`)
  * remapped the workspace: ~330 ms a run on vercel/ai.
  */
 export function envNamesThatMap(configs: readonly string[], names: readonly string[]): string[] {
@@ -299,7 +300,7 @@ export interface TurboMapping {
 
 export interface MapTurboOptions {
   /**
-   * What a task's array holds for one global field: `vx migrate` splices a
+   * What a task's array holds for one global field: `bunx @vzn/vx-migrate` splices a
    * preset import (`{ raw: '...globalInputs' }`), the plugin the values
    * themselves. Called only for a global that is non-empty.
    */
@@ -307,7 +308,7 @@ export interface MapTurboOptions {
   /** The TODO attached to a persistent task, in the consumer's words. */
   persistentTodo: string
   /**
-   * A task's `npm_package_name` / `npm_package_version`: `vx migrate` reads
+   * A task's `npm_package_name` / `npm_package_version`: `bunx @vzn/vx-migrate` reads
    * them from the manifest it imports (`{ raw: 'pkg.version' }`), so a bump
    * reaches them; absent, the values themselves.
    */
@@ -315,7 +316,7 @@ export interface MapTurboOptions {
   /**
    * The environment's variable names, when the mapping runs where the tasks
    * will (`turbo()`): an env wildcard (`NEXT_PUBLIC_*`) expands over them.
-   * Absent (`vx migrate` writes files), a wildcard is a todo.
+   * Absent (`bunx @vzn/vx-migrate` writes files), a wildcard is a todo.
    */
   envNames?: readonly string[]
   /**
@@ -360,6 +361,28 @@ interface Literals {
 }
 type Named = readonly ['files' | 'workspaceFiles' | null, string]
 
+/**
+ * X for a Turbo glob `X/**` whose X has a wildcard, else null. Turbo's
+ * trailing `/**` matches zero segments too (doublestar v4: `**` is zero or
+ * more path segments, so `*\/**` matches `tsconfig.tsbuildinfo` at the
+ * package root); vx's matches only below X, and medusa's `*\/**` build lost
+ * its root `tsconfig.tsbuildinfo` on a restore. A literal X is left as is:
+ * it names the output directory, which `X/**` already covers.
+ */
+function zeroSegments(glob: string): string | null {
+  if (!glob.endsWith('/**')) return null
+  const head = glob.slice(0, -'/**'.length)
+  // An escaped character (`literalGlob`'s `g\{1\}`) is no wildcard.
+  return head === '' || isLiteralPattern(head.replace(/\\./g, '_')) ? null : head
+}
+
+/** A glob, `!` or not, and the X its `X/**` also matches in Turbo (`zeroSegments`). */
+function withZeroSegments(glob: string): string[] {
+  const neg = glob.startsWith('!') ? '!' : ''
+  const head = zeroSegments(glob.slice(neg.length))
+  return head === null ? [glob] : [glob, neg + head]
+}
+
 /** No glob syntax: one path, which git may ignore. */
 const isLiteral = (glob: string): boolean => !/[*?[\]{}()!]/.test(glob)
 
@@ -504,7 +527,7 @@ function taskAt(tasks: Record<string, TurboTask>, key: string): TurboTask | unde
   return Object.hasOwn(tasks, key) ? tasks[key] : undefined
 }
 
-function declares(meta: ProjectMeta, dependency: string): boolean {
+function declares(meta: PackageMeta, dependency: string): boolean {
   const pj = meta.packageJson as unknown as Record<string, unknown>
   // Turbo counts every kind but a peer in a monorepo.
   return ['dependencies', 'devDependencies', 'optionalDependencies'].some((field) => {
@@ -820,11 +843,11 @@ function withGlobal(cfg: TurboJson): TurboJson {
  */
 function rootDependencyGlobs(
   root: string,
-  rootPkg: ProjectMeta['packageJson'],
-  metas: readonly ProjectMeta[],
+  rootPkg: PackageMeta['packageJson'],
+  metas: readonly PackageMeta[],
 ): string[] {
   const byName = new Map(metas.map((m) => [m.name, m]))
-  const depsOf = (pkg: ProjectMeta['packageJson']): string[] =>
+  const depsOf = (pkg: PackageMeta['packageJson']): string[] =>
     (['dependencies', 'devDependencies', 'optionalDependencies'] as const).flatMap((f) => {
       const d: unknown = pkg[f]
       return d !== null && typeof d === 'object' ? Object.keys(d) : []
@@ -847,11 +870,11 @@ function rootDependencyGlobs(
 }
 
 /** The root's manifest; `{}` when it is missing or no object. */
-async function rootPackageJson(root: string): Promise<ProjectMeta['packageJson']> {
+async function rootPackageJson(root: string): Promise<PackageMeta['packageJson']> {
   const pkg = (await Bun.file(path.join(root, 'package.json'))
     .json()
     .catch(() => null)) as unknown
-  return (pkg !== null && typeof pkg === 'object' ? pkg : {}) as ProjectMeta['packageJson']
+  return (pkg !== null && typeof pkg === 'object' ? pkg : {}) as PackageMeta['packageJson']
 }
 
 /**
@@ -886,7 +909,7 @@ export function microfrontendsConfigs(
 
 export async function mapTurboWorkspace(
   root: string,
-  metas: readonly ProjectMeta[],
+  metas: readonly PackageMeta[],
   opts: MapTurboOptions,
 ): Promise<TurboMapping> {
   // A workspace with no Turbo config answered with a bare ENOENT and a stack
@@ -894,7 +917,7 @@ export async function mapTurboWorkspace(
   const rootFile = await turboConfigFile(root)
   if (rootFile === null) {
     throw new UserError(
-      `no turbo.json or turbo.jsonc at the workspace root (${root}): turbo() maps a Turbo repo's config — add one, or remove turbo() from vx.workspace.ts`,
+      `no turbo.json or turbo.jsonc at the workspace root (${root}): turbo() maps a Turbo repo's config — add one, or remove turbo() from .vx/workspace.ts`,
     )
   }
   const rootCfg = withGlobal(await readTurboJson(rootFile, root))
@@ -1003,7 +1026,7 @@ export async function mapTurboWorkspace(
   // plain tasks on its root package (its `non-monorepo` example). As a
   // `//#task` holder only, the root planned nothing: "no projects declare".
   const singlePackage = rootMeta !== undefined && metas.length === 1
-  const definitions = (meta: ProjectMeta) => {
+  const definitions = (meta: PackageMeta) => {
     if (meta === rootMeta && !singlePackage) {
       const defined = new Set(rootTaskNames)
       const defFor = (name: string): TurboTask | undefined =>
@@ -1082,13 +1105,11 @@ export async function mapTurboWorkspace(
   // package reaches in a package something depends on stays none (a
   // `test: [build]` in a package with no tests adds nothing its
   // dependants' `^build` does not).
-  let graph: ReturnType<typeof buildPackageGraph> | undefined
+  let graph: ManifestGraph | undefined
   // The root runs only its `//#` tasks, so its dependencies are no reach
   // (ai's root dev-depends on `konsistent-provider`).
   const depended = (pkg: string): boolean =>
-    (graph ??= buildPackageGraph([...metas]))
-      .transitiveDependents(pkg)
-      .some((d) => d !== rootMeta?.name)
+    (graph ??= manifestGraph(metas)).transitiveDependents(pkg).some((d) => d !== rootMeta?.name)
   const sidecarGroups = new Set<string>()
   for (const meta of metas) {
     const scripts = packageScripts(meta)
@@ -1207,10 +1228,10 @@ export async function mapTurboWorkspace(
   const inferredOf = new Map<string, readonly string[]>()
   // The names a package's files and its workspace dependencies' spell, once.
   const spelledMemo = new Map<string, Promise<readonly string[]>>()
-  const spelledBy = (m: ProjectMeta): Promise<readonly string[]> => {
+  const spelledBy = (m: PackageMeta): Promise<readonly string[]> => {
     let names = spelledMemo.get(m.name)
     if (names === undefined) {
-      const closure = new Set<ProjectMeta>([m])
+      const closure = new Set<PackageMeta>([m])
       for (const p of closure)
         for (const d of metas) if (!closure.has(d) && declares(p, d.name)) closure.add(d)
       names = opts.sourceNames!([...closure].map((p) => p.dir))
@@ -1257,18 +1278,22 @@ export async function mapTurboWorkspace(
       sourcedOf.set(fw, [...(sourcedOf.get(fw) ?? []), m.name])
     } else usersOf.set(fw, [...(usersOf.get(fw) ?? []), m.name])
   }
+  // One short line per framework: nitro's twelve names and a long package
+  // list ran past any terminal (Growth's first-run funnel F7, 2026-10-13).
+  const few = (list: readonly string[]): string =>
+    list.length <= 3
+      ? list.join(', ')
+      : `${list.slice(0, 3).join(', ')} and ${list.length - 3} more`
   for (const [fw, users] of sourcedOf)
     notes.push(
-      `Turbo infers ${fw.slug} in ${users.join(', ')} and hashes and passes ${fw.env.join(', ')} ` +
-        'to its tasks; the configs list the names their files and their workspace ' +
-        'dependencies’ spell — add any only an installed dependency reads to cache.inputs.env ' +
-        'and exec.env.passThrough',
+      `${fw.slug} in ${few(users)}: Turbo passes ${few(fw.env)} implicitly; the configs list ` +
+        'the names the package and its workspace dependencies spell, so add any an installed ' +
+        'dependency reads to cache.inputs.env and exec.env.passThrough',
     )
   for (const [fw, users] of usersOf)
     notes.push(
-      `Turbo infers ${fw.slug} in ${users.join(', ')} and hashes and passes ${fw.env.join(', ')} to ` +
-        'its tasks; vx env names are explicit — list the ones they read in cache.inputs.env ' +
-        'and exec.env.passThrough',
+      `${fw.slug} in ${few(users)}: Turbo passes ${few(fw.env)} implicitly; list the ones ` +
+        'they read in cache.inputs.env and exec.env.passThrough',
     )
 
   // A task's own `*` env name, in a written config: expanded over the
@@ -1452,7 +1477,7 @@ export async function mapTurboWorkspace(
       for (const sel of dep.from ?? def!.dependsOn ?? []) {
         if (envDependency(sel) !== null) continue
         const hash = sel.indexOf('#')
-        const producers: [ProjectMeta | undefined, string][] = sel.startsWith('^')
+        const producers: [PackageMeta | undefined, string][] = sel.startsWith('^')
           ? metas.filter((m) => declares(meta, m.name)).map((m) => [m, sel.slice(1)])
           : hash === -1
             ? [[meta, sel]]
@@ -1615,7 +1640,7 @@ function reanchor(glob: string, dir: string): string | null {
  */
 function pruneUnreachedPersistentNotes(
   projects: readonly TurboMappedProject[],
-  metas: readonly ProjectMeta[],
+  metas: readonly PackageMeta[],
   note: string,
 ): void {
   const byName = new Map(metas.map((m) => [m.name, m]))
@@ -1691,7 +1716,7 @@ function npmScriptEnv(
   task: Record<string, unknown>,
   script: string,
   unfolded: boolean,
-  meta: ProjectMeta,
+  meta: PackageMeta,
   opts: MapTurboOptions,
 ): void {
   const exec = task['exec'] as { command: string; env?: Record<string, unknown> }
@@ -2008,11 +2033,11 @@ function buildTask(
           continue
         }
         if (body.startsWith('$TURBO_ROOT$/')) {
-          wsFiles.push((neg ? '!' : '') + body.slice('$TURBO_ROOT$/'.length))
+          wsFiles.push(...withZeroSegments((neg ? '!' : '') + body.slice('$TURBO_ROOT$/'.length)))
           const rel = body.slice('$TURBO_ROOT$/'.length)
           if (!neg) rels.set(rel, ['workspaceFiles', rel])
         } else if (up !== null) {
-          wsFiles.push(up)
+          wsFiles.push(...withZeroSegments(up))
           if (!neg) rels.set(up, ['workspaceFiles', up])
         } else if (body.startsWith('../')) {
           todos.push(`input ${JSON.stringify(i)}: leaves the workspace — map manually`)
@@ -2022,7 +2047,8 @@ function buildTask(
               'prefix (→ cache.inputs.workspaceFiles) — map manually',
           )
         } else {
-          files.push(translated)
+          // Unkeyed, a root file edit `*\/**` reaches in Turbo replayed a stale hit.
+          files.push(...withZeroSegments(translated))
           const rel = path.posix.join(atRoot ? '.' : pkgDir, body)
           if (!neg) rels.set(rel, [atRoot ? 'workspaceFiles' : 'files', translated])
         }
@@ -2041,6 +2067,7 @@ function buildTask(
     if (Array.isArray(dotEnv) && dotEnv.some((f) => typeof f === 'string')) pkgDotenv = true
 
     const outFiles: string[] = []
+    const zeroed = new Set<string>()
     const wsOutFiles: string[] = []
     for (const raw of def.outputs ?? []) {
       // The first segment stays a literal (a route directory, item 667);
@@ -2061,10 +2088,16 @@ function buildTask(
       // before every run while vx outputs could not exclude.
       const neg = mapped.startsWith('!') ? '!' : ''
       const o = mapped.slice(neg.length)
+      const signed = (g: string) => {
+        const head = zeroSegments(g)
+        if (head === null) return [neg + g]
+        zeroed.add(neg + head)
+        return [neg + g, neg + head]
+      }
       if (o.startsWith('$TURBO_ROOT$/')) {
-        wsOutFiles.push(neg + o.slice('$TURBO_ROOT$/'.length))
+        wsOutFiles.push(...signed(o.slice('$TURBO_ROOT$/'.length)))
       } else if (climbed(o) !== null) {
-        wsOutFiles.push(neg + climbed(o)!)
+        wsOutFiles.push(...signed(climbed(o)!))
       } else if (o.startsWith('../')) {
         todos.push(`output ${JSON.stringify(o)}: leaves the workspace — map manually`)
       } else if (o.includes('$TURBO_ROOT$')) {
@@ -2072,27 +2105,30 @@ function buildTask(
           `output ${JSON.stringify(o)}: $TURBO_ROOT$ only maps as a '$TURBO_ROOT$/<path>' ` +
             'prefix (→ cache.outputs.workspaceFiles) — map manually',
         )
-      } else outFiles.push(neg + o)
+      } else outFiles.push(...signed(o))
     }
 
-    // A committed file a literal-tail wildcard reaches is taken back, as
-    // the runtime spares a tracked output; past the runtime's limit the
-    // task stays uncached.
-    for (const o of [...outFiles]) {
-      const hits = literalTailMatches(o, opts.tracked?.(pkgDir))
-      if (hits !== null && hits.length <= MAX_SPARED)
-        for (const h of hits) if (!outFiles.includes(`!${h}`)) outFiles.push(`!${h}`)
-    }
-    const wild = wildcardOutput(outFiles, opts.tracked?.(pkgDir), true)
-    if (wild !== undefined) {
+    // With git's file list known, a wildcard-first output stays cached as
+    // nx() keeps it (owner, 2026-10-03; turbo() 2026-10-14): core never
+    // cleans a committed file. Turbo never cleans, so the untracked files
+    // it reaches are named. An X added for `X/**` is judged with it.
+    const wild = wildcardOutput(
+      outFiles.filter((g) => !zeroed.has(g)),
+      opts.tracked?.(pkgDir),
+      true,
+    )
+    if (wild !== undefined && opts.tracked === undefined) {
       todos.push(wildcardTodo(wild))
       return { name, todos, task, uses }
     }
-    const own = ownFileOutput(outFiles, opts.ownConfig?.(pkgDir))
-    if (own !== undefined) {
-      todos.push(ownFileTodo(own))
-      return { name, todos, task, uses }
-    }
+    if (wild !== undefined) todos.push(wildcardCleanTodo(wild))
+    // An output over the project's own package.json (trpc's builds list
+    // it: tsdown rewrites `exports`) is taken back and keeps the cache, as
+    // nx() does (owner, 2026-10-03). The build rewrites an input the key
+    // folds, so its identical rewrite counts as unchanged ('mutable').
+    const takeBacks = ownFileTakeBacks(outFiles, opts.ownConfig?.(pkgDir))
+    outFiles.push(...takeBacks)
+    const rewritesManifest = takeBacks.includes('!package.json')
 
     const cacheEnv = uniq([...global('env'), ...envNames], hidden('env'))
 
@@ -2115,7 +2151,11 @@ function buildTask(
     const outputs: Record<string, unknown> = { files: takingBack(outFiles) }
     const ws = takingBack(wsOutFiles)
     if (ws.length > 0) outputs.workspaceFiles = ws
-    task.cache = { inputs, outputs }
+    task.cache = {
+      inputs,
+      outputs,
+      ...(rewritesManifest ? { inputStability: { strategy: 'mutable' } } : {}),
+    }
   }
 
   return { name, todos, task, uses }

package/src/turbo-cache/index.ts

@@ -4,7 +4,7 @@
 // spec. The wire is Turbo's; the bytes are vx's own artifacts under vx's
 // own keys, so the server is storage — a Turbo binary cannot read them.
 //
-// Nothing is on by default: declare `turboCache()` in `vx.workspace.ts`
+// Nothing is on by default: declare `turboCache()` in `.vx/workspace.ts`
 // (the local store is the floor beneath it) and give it a URL and a token (options, or
 // Turbo's own environment variables and turbo.json's `remoteCache` so a
 // self-hosted setup carries over).
@@ -17,8 +17,6 @@ import { tmpdir } from 'node:os'
 import path from 'node:path'
 import {
   definePlugin,
-  LayeredCache,
-  type CacheLayer,
   type RemoteCacheLayer,
   type VxPlugin,
   refuseUnknownOptions,
@@ -366,7 +364,7 @@ const MAX_SIGNED_BODY = 2 * 1024 ** 3 + ((2 * 1024 ** 3) >> 8) + 64 * 1024
 /**
  * The seam implementation: `has` is HEAD, `hasMany` is the batch query,
  * `get`/`put` carry `x-artifact-duration` (and the tag when signing). An
- * auth failure (401/403) throws ONCE — LayeredCache reports it — and then
+ * auth failure (401/403) throws ONCE — core reports it — and then
  * turns the layer off for the rest of the process (an upload's 403 turns off
  * uploads alone: the read-only token), so a bad token costs one
  * line, not one per task — the requests already in flight when it lands
@@ -389,6 +387,8 @@ export class TurboRemoteCache implements RemoteCacheLayer {
   private writesRefused = false
   private readonly key: Uint8Array | undefined
   readonly endpoint: string
+  /** What `TURBO_REMOTE_CACHE_READ_ONLY` and friends leave this run (`turboRemoteAccess`). */
+  access?: { read: boolean; write: boolean }
   constructor(
     private readonly config: TurboCacheConfig,
     private readonly fetchImpl: typeof fetch = fetch,
@@ -630,10 +630,10 @@ export class TurboRemoteCache implements RemoteCacheLayer {
 
 /**
  * What Turbo's own switches leave of the remote cache: `TURBO_CACHE`
- * (`--cache`'s syntax, where an omitted source is off) and
+ * (`--cache-policy`'s syntax, where an omitted source is off) and
  * `TURBO_REMOTE_CACHE_READ_ONLY`. A CI that sets either for an untrusted
  * pull request kept Turbo from writing the shared cache and not vx. They
- * only narrow what `--cache` allows, never widen it.
+ * only narrow what `--cache-policy` allows, never widen it.
  */
 export function turboRemoteAccess(env: Record<string, string | undefined>): {
   read: boolean
@@ -648,7 +648,7 @@ export function turboRemoteAccess(env: Record<string, string | undefined>): {
       const m = /^(local|remote):([rw]*)$/.exec(part.trim())
       if (m === null)
         throw new Error(
-          `vx/turbo-cache: TURBO_CACHE ${JSON.stringify(spec)} is not --cache's syntax (e.g. local:rw,remote:r)`,
+          `vx/turbo-cache: TURBO_CACHE ${JSON.stringify(spec)} is not --cache-policy's syntax (e.g. local:rw,remote:r)`,
         )
       if (m[1] !== 'remote') continue
       read = m[2]!.includes('r')
@@ -713,7 +713,7 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
 }
 
 /**
- * Declare in `vx.workspace.ts`; the local store stays the floor beneath it:
+ * Declare in `.vx/workspace.ts`; the local store stays the floor beneath it:
  *
  * ```ts
  * plugins: [turboCache({ apiUrl: 'https://cache.example.com', token: process.env.CACHE_TOKEN })]
@@ -724,7 +724,7 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
 export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
   refuseUnknownOptions('turboCache()', options, TURBO_CACHE_KEYS)
   return definePlugin(import.meta, {
-    cache(ctx): CacheLayer | undefined {
+    cache(ctx): RemoteCacheLayer | undefined {
       const config = resolveTurboCacheConfig(
         options,
         Bun.env,
@@ -732,20 +732,14 @@ export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
         localConfigOf(ctx.workspaceRoot),
       )
       if (config === undefined) return undefined
-      const remote = turboRemoteAccess(Bun.env)
-      const policy = {
-        ...ctx.policy,
-        remoteRead: ctx.policy.remoteRead && remote.read,
-        remoteWrite: ctx.policy.remoteWrite && remote.write,
-      }
-      if (!policy.remoteRead && !policy.remoteWrite) return undefined
+      const access = turboRemoteAccess(Bun.env)
+      if (!access.read && !access.write) return undefined
       // A signed download waits in a temp until its tag checks: in vx's
       // cache directory, which the sandbox walls, not the shared temp dir a
       // sandboxed task may read (L-45).
-      return new LayeredCache(ctx.localCache, new TurboRemoteCache(config, fetch, ctx.cacheDir), {
-        policy,
-        onRemoteError: (err) => ctx.warn(`vx/turbo-cache: ${err.message}`),
-      })
+      const remote = new TurboRemoteCache(config, fetch, ctx.cacheDir)
+      remote.access = access
+      return remote
     },
   })
 }

package/src/vite-task/vite-task-map.ts

@@ -7,7 +7,8 @@
 
 import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { type GeneratedProject, type GeneratedTask, type ProjectMeta, UserError } from '@vzn/vx'
+import { type GeneratedProject, type GeneratedTask, UserError } from '@vzn/vx'
+import type { PackageMeta } from '../packages.js'
 import { minimatchToVx, withoutTakenBack } from '../glob-grammar.js'
 import { packageScripts, relPosix } from '../paths.js'
 import { scriptCommand, yarnPnp } from '../script-command.js'
@@ -158,8 +159,8 @@ const asStrings = (v: unknown): string[] =>
  */
 export async function viteTaskProjects(
   root: string,
-  metas: readonly ProjectMeta[],
-): Promise<{ metas: ProjectMeta[]; notes: string[] }> {
+  metas: readonly PackageMeta[],
+): Promise<{ metas: PackageMeta[]; notes: string[] }> {
   if (metas.some((m) => path.resolve(m.dir) === path.resolve(root)))
     return { metas: [...metas], notes: [] }
   const file = viteConfigFile(root)
@@ -186,7 +187,7 @@ export async function viteTaskProjects(
 /** Every project's Vite Task tasks and package.json scripts as vx tasks. */
 export async function mapViteTaskWorkspace(
   root: string,
-  metas: readonly ProjectMeta[],
+  metas: readonly PackageMeta[],
   opts: ViteTaskOptions = {},
 ): Promise<ViteTaskMapping> {
   const rootFile = viteConfigFile(root)
@@ -207,12 +208,12 @@ export async function mapViteTaskWorkspace(
           : await readRunConfig(file, root),
     )
   }
-  const tasksOf = (m: ProjectMeta): Record<string, unknown> => runs.get(m.name)?.tasks ?? {}
-  const defines = (m: ProjectMeta, task: string): boolean =>
+  const tasksOf = (m: PackageMeta): Record<string, unknown> => runs.get(m.name)?.tasks ?? {}
+  const defines = (m: PackageMeta, task: string): boolean =>
     Object.hasOwn(tasksOf(m), task) || typeof packageScripts(m)[task] === 'string'
   const byName = new Map(metas.map((m) => [m.name, m]))
   /** Workspace members `m` lists under each field, by name. */
-  const depsIn = (m: ProjectMeta, field: string): string[] => {
+  const depsIn = (m: PackageMeta, field: string): string[] => {
     const deps = (m.packageJson as unknown as Record<string, unknown>)[field]
     if (typeof deps !== 'object' || deps === null) return []
     return Object.keys(deps).filter((n) => byName.has(n) && n !== m.name)
@@ -225,7 +226,7 @@ export async function mapViteTaskWorkspace(
    * leading chain of them becomes `dependsOn` edges, and the task a group
    * when nothing else is left; a form with no edge spelling is a TODO.
    */
-  function inlineRuns(t: GeneratedTask, self: ProjectMeta): void {
+  function inlineRuns(t: GeneratedTask, self: PackageMeta): void {
     const exec = t.task?.['exec'] as { command?: unknown } | undefined
     if (typeof exec?.command !== 'string') return
     const parts = exec.command.split('&&').map((p) => p.trim())
@@ -252,7 +253,7 @@ export async function mapViteTaskWorkspace(
   }
 
   /** The edges one `vp run` stands for, or null when it has none. */
-  function runEdges(segment: string, self: ProjectMeta, own: string): string[] | null {
+  function runEdges(segment: string, self: PackageMeta, own: string): string[] | null {
     const words = segment.split(/\s+/)
     words.splice(0, words.indexOf(words[0] === 'vpr' ? 'vpr' : 'run') + 1)
     let recursive = false
@@ -279,7 +280,7 @@ export async function mapViteTaskWorkspace(
       const m = byName.get(spec.slice(0, hash))
       return recursive || workspace || filters.length > 0 || m === undefined ? null : [spec]
     }
-    let picked: ProjectMeta[]
+    let picked: PackageMeta[]
     if (filters.length > 0) {
       // Package names only: pnpm's directory, glob and graph selectors are not.
       if (filters.some((f) => !byName.has(f))) return null
@@ -314,7 +315,7 @@ export async function mapViteTaskWorkspace(
     })
     let spelled: readonly string[] | undefined
     if (wild && opts.sourceNames !== undefined) {
-      const closure = new Set<ProjectMeta>([meta])
+      const closure = new Set<PackageMeta>([meta])
       for (const p of closure)
         for (const field of [...DEP_FIELDS, 'optionalDependencies'])
           for (const n of depsIn(p, field)) closure.add(byName.get(n)!)
@@ -342,7 +343,7 @@ export async function mapViteTaskWorkspace(
      * defines it. `^task` is that set while no member listed under another
      * field defines it too (vx's `^` follows every field); else the edges.
      */
-    function fromDeps(m: ProjectMeta, entry: { task: string; from: unknown }): string[] {
+    function fromDeps(m: PackageMeta, entry: { task: string; from: unknown }): string[] {
       const fields = (Array.isArray(entry.from) ? entry.from : [entry.from]).filter(
         (f): f is DepField => (DEP_FIELDS as readonly unknown[]).includes(f),
       )

package/src/workspace-notes.ts

@@ -1,11 +1,11 @@
-// What the written configs leave to vx.workspace.ts, said once by both
+// What the written configs leave to .vx/workspace.ts, said once by both
 // migrators: the adoption plugin `vx init` declared still reads the old
 // tool's file every run, and the old tool keyed each package on its own
 // lockfile entries where core keys every task on the whole lockfile.
 // Without a lockfile plugin a dependency bump re-ran every task (hey-api:
 // a `pnpm-lock.yaml` edit re-keyed all 42 builds, none with `pnpm()`).
 
-import { existsSync, readdirSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import path from 'node:path'
 
 /** Each lockfile and the `@vzn/vx-lockfile` plugin that claims it. */
@@ -35,11 +35,18 @@ interface AdoptedTool {
   readonly runner: string
 }
 
+const WORKSPACE_FILES = ['ts', 'mts', 'js', 'mjs', 'cts', 'cjs'].map((e) => `.vx/workspace.${e}`)
+
+/** The workspace file under `root`, in any extension the loader reads. */
+export function workspaceFileAt(root: string): string | undefined {
+  return WORKSPACE_FILES.find((n) => existsSync(path.join(root, n)))
+}
+
 export async function adoptedToolNotes(root: string, tool: AdoptedTool): Promise<string[]> {
   const notes: string[] = []
   let declared = ''
-  for (const name of readdirSync(root)) {
-    if (!/^vx\.workspace\.(ts|mts|js|mjs|cts|cjs)$/.test(name)) continue
+  const name = workspaceFileAt(root)
+  if (name !== undefined) {
     declared = await Bun.file(path.join(root, name)).text()
     if (new RegExp(`\\b${tool.plugin}\\s*\\(`).test(declared))
       notes.push(
@@ -47,14 +54,13 @@ export async function adoptedToolNotes(root: string, tool: AdoptedTool): Promise
           'a vx.config does not declare; the configs written here declare them all. Once ' +
           `\`vx run\` does what ${tool.runner} did, remove ${tool.plugin}() (and its import), then ${tool.config}`,
       )
-    break
   }
   const lock = lockfilePlugin(root)
   if (lock !== undefined && !new RegExp(`\\b${lock.factory}\\s*\\(`).test(declared))
     notes.push(
       `${tool.keys(lock.file)}; vx keys every task on the whole ` +
         `file, so a dependency bump re-runs them all. Declare ${lock.factory}() from @vzn/vx-lockfile ` +
-        "in vx.workspace.ts to key each task on its package's dependency closure",
+        "in .vx/workspace.ts to key each task on its package's dependency closure",
     )
   return notes
 }