@vzn/vx-migrate 0.0.635 → 0.0.637

package/src/nx/index.ts

@@ -23,6 +23,7 @@ import { stat } from 'node:fs/promises'
 import { availableParallelism } from 'node:os'
 import path from 'node:path'
 import {
+  type DiscoveredProject,
   refuseUnknownOptions,
   type PluginOptionKinds,
   type GeneratedProject,
@@ -30,6 +31,7 @@ import {
   UserError,
   type VxPlugin,
 } from '@vzn/vx'
+import type { PackageMeta } from '../packages.js'
 import { type AdoptionRun, adoptionPlugin } from '../adoption-plugin.js'
 import { collectGaps } from '../plugin-gaps.js'
 import {
@@ -43,6 +45,7 @@ import {
 } from './nx-map.js'
 import { exportGraph } from './export-graph.js'
 import { lernaJsonText } from './lerna.js'
+import { nxDependencyRules } from './nx-boundaries.js'
 export type {
   NxExecutors,
   NxExecutorTarget,
@@ -52,6 +55,7 @@ export type {
 import { listDotenv } from './nx-dotenv.js'
 import { trackedKinds } from '../tracked-outputs.js'
 import { relPosix } from '../paths.js'
+import { memberProjects, withManifests } from '../manifests.js'
 import type { AdoptionMapping } from '../mapping-cache.js'
 import { yarnrcText } from '../script-command.js'
 
@@ -119,10 +123,12 @@ export function nx(options: NxPluginOptions = {}): VxPlugin {
     cacheDir: string,
     projects: readonly ProjectMeta[],
     changes?: WorktreeChanges,
+    members: readonly DiscoveredProject[] = [],
   ) => {
     if (graphFor !== projects) {
       graphFor = projects
-      graph = loadGraph(root, cacheDir, projects, options.graph, changes)
+      const also = members.map((m) => ({ name: m.name ?? '', dir: m.dir, configPath: null }))
+      graph = loadGraph(root, cacheDir, [...projects, ...also], options.graph, changes)
     }
     return graph!
   }
@@ -142,33 +148,45 @@ export function nx(options: NxPluginOptions = {}): VxPlugin {
     {
       async config(workspace, ctx) {
         const root = options.root ?? ctx.workspaceRoot
-        if (workspace.affectedBase === undefined) {
+        if (workspace.run?.affectedBase === undefined) {
           const base = await nxBase(root)
-          if (base !== undefined) workspace.affectedBase = base
+          if (base !== undefined) workspace.run = { ...workspace.run, affectedBase: base }
         }
-        if (workspace.concurrency === undefined) {
+        if (workspace.run?.concurrency === undefined) {
           const parallel = await nxParallel(root)
-          if (parallel !== undefined) workspace.concurrency = parallel
+          if (parallel !== undefined) workspace.run = { ...workspace.run, concurrency: parallel }
         }
-        if (workspace.cacheRetention === undefined) {
+        if (workspace.run?.rules?.dependencies === undefined) {
+          const dependencies = await nxDependencyRules(root)
+          if (dependencies !== undefined && dependencies.length > 0)
+            workspace.run = {
+              ...workspace.run,
+              rules: { ...workspace.run?.rules, dependencies },
+            }
+        }
+        if (workspace.cache?.retention === undefined) {
           const maxSize = await nxMaxCacheSize(root)
-          if (maxSize !== undefined) workspace.cacheRetention = { maxSize }
+          if (maxSize !== undefined)
+            workspace.cache = { ...workspace.cache, retention: { maxSize } }
         }
       },
-      // An integrated Nx repo keeps projects out of the package manager's
-      // list (analogjs: `project.json` libraries no glob names), and their
+      // The package manager's members are projects, each with no vx.config
+      // written. An integrated Nx repo keeps projects out of that list
+      // (analogjs: `project.json` libraries no glob names), and their
       // targets had nowhere to attach: 1 of 21 `build` tasks ran. Each
-      // graph node with targets at a directory core did not find is named
-      // a project, by its package.json name or else its Nx name; a name a
+      // graph node with targets at a directory neither found is named a
+      // project, by its package.json name or else its Nx name; a name a
       // project already holds stays unattached, and the mapping says so.
       async discover(ctx) {
         const root = options.root ?? ctx.workspaceRoot
+        const members = await memberProjects(ctx.workspaceRoot)
         // Core's status is the workspace's: a root elsewhere asks git itself.
         const changes = options.root === undefined ? () => ctx.worktreeChanges() : undefined
-        const { graph } = await graphOf(root, ctx.cacheDir, ctx.projects, changes)
-        const dirs = new Set(ctx.projects.map((m) => path.resolve(m.dir)))
-        const names = new Set(ctx.projects.map((m) => m.name))
-        const named: Array<{ dir: string; name: string }> = []
+        const { graph } = await graphOf(root, ctx.cacheDir, ctx.projects, changes, members)
+        const found = [...ctx.projects, ...members]
+        const dirs = new Set(found.map((m) => path.resolve(m.dir)))
+        const names = new Set(found.map((m) => m.name))
+        const named = members.map((m) => ({ dir: path.resolve(m.dir), name: m.name! }))
         for (const [nodeName, node] of Object.entries(graph.nodes)) {
           if (node?.data?.targets === undefined) continue
           const dir = path.resolve(root, node.data.root ?? '')
@@ -190,12 +208,45 @@ export function nx(options: NxPluginOptions = {}): VxPlugin {
           dirs.add(dir)
           named.push({ dir, name })
         }
-        return named
+        const entries = withGraphEdges(root, graph, dirs, named)
+        const covered = new Set(entries.map((e) => e.dir))
+        return [...entries, ...named.filter((n) => !covered.has(n.dir))]
       },
     },
   )
 }
 
+/**
+ * Every project the graph and the workspace share, with its Nx graph edges
+ * (package deps, `implicitDependencies`, imports) as `deps`: nx() is an Nx
+ * repo's edge source, so `^task` follows Nx's graph with no lockfile plugin.
+ */
+function withGraphEdges(
+  root: string,
+  graph: NxGraph,
+  dirs: ReadonlySet<string>,
+  named: ReadonlyArray<{ dir: string; name: string }>,
+): DiscoveredProject[] {
+  const dirOf = new Map<string, string>()
+  for (const [nodeName, node] of Object.entries(graph.nodes)) {
+    const dir = path.resolve(root, node?.data?.root ?? '')
+    if (dirs.has(dir)) dirOf.set(nodeName, dir)
+  }
+  const nameOf = new Map(named.map((n) => [n.dir, n.name]))
+  const edges = (graph.dependencies ?? {}) as Record<string, ReadonlyArray<{ target?: unknown }>>
+  const out: DiscoveredProject[] = []
+  for (const [nodeName, dir] of dirOf) {
+    const deps = new Set<string>()
+    for (const e of edges[nodeName] ?? []) {
+      const to = typeof e?.target === 'string' ? dirOf.get(e.target) : undefined
+      if (to !== undefined && to !== dir) deps.add(to)
+    }
+    const name = nameOf.get(dir)
+    out.push({ dir, ...(name === undefined ? {} : { name }), deps: [...deps].sort() })
+  }
+  return out
+}
+
 function isWithin(root: string, dir: string): boolean {
   const rel = path.relative(root, dir)
   return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
@@ -268,10 +319,11 @@ interface LoadedGraph {
 
 async function mapAll(
   root: string,
-  metas: readonly ProjectMeta[],
+  projects: readonly ProjectMeta[],
   loaded: LoadedGraph,
   executors: NxExecutors | undefined,
 ): Promise<AdoptionRun> {
+  const metas = await withManifests(projects)
   const { text, graph, notes } = loaded
   const reads = await nxReads(root, metas, text, graph, notes)
   // The mapping is cached on what it read; a translator is code it ran.
@@ -304,7 +356,7 @@ const textOf = (file: string): Promise<string> =>
  */
 async function nxReads(
   root: string,
-  metas: readonly ProjectMeta[],
+  metas: readonly PackageMeta[],
   graphText: string,
   graph: NxGraph,
   notes: readonly string[],
@@ -346,7 +398,7 @@ async function nxReads(
 
 async function index(
   root: string,
-  metas: readonly ProjectMeta[],
+  metas: readonly PackageMeta[],
   graph: NxGraph,
   loadNotes: readonly string[],
   trackedFiles: () => Promise<readonly string[] | null>,
@@ -535,6 +587,9 @@ async function graphInputKey(
   // and stays in.
   const nxCache = (p: string): boolean =>
     p.startsWith('.nx/cache/') || p.startsWith('.nx/workspace-data/')
+  // vx's own directory (the lock `vx lock` rewrites, the workspace file):
+  // Nx reads nothing there, and under a root project each lock re-exported.
+  const vxDir = (p: string): boolean => p.startsWith('.vx/')
   // What can move the graph: a file under a project root (its sources, the
   // configs a plugin infers targets from), or a root file Nx reads. A task's
   // stray write at the root (a report, a log) is not, and counting it
@@ -546,7 +601,9 @@ async function graphInputKey(
     p.endsWith('/project.json') ||
     roots.some((r) => r === '' || p.startsWith(`${r}/`)) ||
     (!p.includes('/') && ROOT_GRAPH_FILE.test(p))
-  const listed = [...new Set(changed.filter((p) => !inCache(p) && !nxCache(p) && graphFile(p)))]
+  const listed = [
+    ...new Set(changed.filter((p) => !inCache(p) && !nxCache(p) && !vxDir(p) && graphFile(p))),
+  ]
   // A manifest needs no read of its own: git lists it when it is edited, and
   // HEAD moves when an edit is committed (reading all 2,000 cost 50 ms at
   // 1,000 projects). nx.json's chain does: a base may sit in node_modules,

package/src/nx/nx-boundaries.ts

@@ -0,0 +1,191 @@
+import path from 'node:path'
+
+/** `run.rules.dependencies`' entry, as core takes it. */
+interface DependencyRule {
+  from: string
+  allow?: string[]
+  deny?: string[]
+}
+
+const RULE_NAMES = ['@nx/enforce-module-boundaries', '@nrwl/nx/enforce-module-boundaries']
+const FLAT = ['eslint.config.mjs', 'eslint.config.js', 'eslint.config.cjs', 'eslint.config.ts']
+const LEGACY = ['.eslintrc.json', '.eslintrc']
+
+/**
+ * The root ESLint config's `@nx/enforce-module-boundaries` `depConstraints`,
+ * as vx's lock-time dependency rules. A flat config is read, never run:
+ * importing it loads ESLint's plugins on every vx run, for a rule only
+ * `vx lock` checks. So the constraints must be a literal array there; a
+ * spread or a variable maps nothing. Undefined when no rule is found.
+ */
+export async function nxDependencyRules(root: string): Promise<DependencyRule[] | undefined> {
+  for (const name of [...FLAT, ...LEGACY]) {
+    const file = Bun.file(path.join(root, name))
+    if (!(await file.exists())) continue
+    const text = await file.text()
+    const constraints = LEGACY.includes(name) ? fromJson(text) : fromSource(text)
+    return constraints === undefined ? undefined : mapConstraints(constraints)
+  }
+  return undefined
+}
+
+/** `rules` and each `overrides[].rules` of a JSON config, first rule found. */
+function fromJson(text: string): unknown[] | undefined {
+  let json: unknown
+  try {
+    json = Bun.JSONC.parse(text)
+  } catch {
+    return undefined
+  }
+  const configs = [json, ...((json as { overrides?: unknown[] })?.overrides ?? [])]
+  for (const c of configs) {
+    const rules = (c as { rules?: Record<string, unknown> } | null)?.rules
+    for (const r of RULE_NAMES) {
+      const entry = rules?.[r]
+      const options = Array.isArray(entry) ? entry[1] : undefined
+      const dc = (options as { depConstraints?: unknown } | undefined)?.depConstraints
+      if (Array.isArray(dc)) return dc
+    }
+  }
+  return undefined
+}
+
+/** The literal after the rule's `depConstraints:` in JS source. */
+function fromSource(text: string): unknown[] | undefined {
+  for (const r of RULE_NAMES) {
+    const at = text.indexOf(r)
+    if (at === -1) continue
+    const m = /depConstraints['"]?\s*:\s*\[/.exec(text.slice(at))
+    if (m === null) return undefined
+    try {
+      const v = new Literal(text, at + m.index + m[0].length - 1).value()
+      return Array.isArray(v) ? v : undefined
+    } catch {
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * Nx's constraint as a vx rule: `sourceTag` is `from`,
+ * `onlyDependOnLibsWithTags` is `allow`, `notDependOnLibsWithTags` is
+ * `deny`; `*` means any project. A constraint vx cannot say is left out:
+ * `allSourceTags` (every tag at once), a `/regex/` tag, or one that bans
+ * only external imports.
+ */
+function mapConstraints(constraints: unknown[]): DependencyRule[] {
+  const out: DependencyRule[] = []
+  const sel = (t: unknown) => (t === '*' ? '*' : `tag:${String(t)}`)
+  const tags = (v: unknown): string[] | undefined =>
+    Array.isArray(v) && v.every((t) => typeof t === 'string' && t !== '' && !t.startsWith('/'))
+      ? v.map(sel)
+      : undefined
+  for (const c of constraints) {
+    const { sourceTag, onlyDependOnLibsWithTags, notDependOnLibsWithTags } = (c ?? {}) as Record<
+      string,
+      unknown
+    >
+    if (typeof sourceTag !== 'string' || sourceTag === '' || sourceTag.startsWith('/')) continue
+    const allow = tags(onlyDependOnLibsWithTags)
+    const deny = tags(notDependOnLibsWithTags)
+    if (allow === undefined && deny === undefined) continue
+    out.push({
+      from: sel(sourceTag),
+      ...(allow !== undefined ? { allow } : {}),
+      ...(deny !== undefined ? { deny } : {}),
+    })
+  }
+  return out
+}
+
+/** A JS literal: arrays, objects, strings, numbers, booleans, null. Anything else throws. */
+class Literal {
+  constructor(
+    private readonly s: string,
+    private i: number,
+  ) {}
+
+  value(): unknown {
+    this.skip()
+    const c = this.s[this.i]
+    if (c === '[') {
+      this.i++
+      const out: unknown[] = []
+      while (!this.eat(']')) {
+        out.push(this.value())
+        if (!this.eat(',')) {
+          this.expect(']')
+          break
+        }
+      }
+      return out
+    }
+    if (c === '{') {
+      this.i++
+      const out: Record<string, unknown> = {}
+      while (!this.eat('}')) {
+        const key = this.key()
+        this.expect(':')
+        out[key] = this.value()
+        if (!this.eat(',')) {
+          this.expect('}')
+          break
+        }
+      }
+      return out
+    }
+    if (c === "'" || c === '"' || c === '`') return this.string(c)
+    const m = this.match(/true|false|null|-?\d+(?:\.\d+)?/y)
+    if (m === null) throw new Error('not a literal')
+    return JSON.parse(m)
+  }
+
+  private key(): string {
+    this.skip()
+    const c = this.s[this.i]
+    if (c === "'" || c === '"') return this.string(c)
+    const m = this.match(/[A-Za-z_$][\w$]*/y)
+    if (m === null) throw new Error('not a key')
+    return m
+  }
+
+  private string(q: string): string {
+    let out = ''
+    for (this.i++; this.i < this.s.length; this.i++) {
+      const c = this.s[this.i]!
+      if (c === q) {
+        this.i++
+        return out
+      }
+      if (c === '\\') out += this.s[++this.i]
+      else if (q === '`' && c === '$' && this.s[this.i + 1] === '{') throw new Error('template')
+      else out += c
+    }
+    throw new Error('unterminated')
+  }
+
+  private skip(): void {
+    while (this.match(/\s+|\/\/[^\n]*|\/\*[\s\S]*?\*\//y) !== null);
+  }
+
+  /** The sticky `re`'s match at the cursor, consumed; null when none. */
+  private match(re: RegExp): string | null {
+    re.lastIndex = this.i
+    const m = re.exec(this.s)
+    if (m === null || m[0] === '') return null
+    this.i += m[0].length
+    return m[0]
+  }
+
+  private eat(c: string): boolean {
+    this.skip()
+    if (this.s[this.i] !== c) return false
+    this.i++
+    return true
+  }
+
+  private expect(c: string): void {
+    if (!this.eat(c)) throw new Error(`expected ${c}`)
+  }
+}

package/src/nx/nx-deps.ts

@@ -6,7 +6,7 @@
 // vx-migrate itself wrote (walked the Nx path, 2026-09-20). Extracted from
 // `buildTask` in item 606; the rules are unchanged.
 
-import type { ProjectMeta } from '@vzn/vx'
+import type { PackageMeta } from '../packages.js'
 
 /** The vx task an Nx `project:target:configuration` reaches, or null when the target lacks it. */
 export type TaskNameFor = (project: string, target: string, configuration: string) => string | null
@@ -16,7 +16,7 @@ export type TaskNameFor = (project: string, target: string, configuration: strin
  * target (`processTasksForSingleProject`), and says nothing otherwise:
  * nx-examples' `targetDefaults` give every `typecheck` a `codegen` that
  * one project declares. Passed through, core refused the whole run —
- * "depends on …#codegen but no such task is declared". Dropped here as
+ * "dependsOn …#codegen but no such task is declared". Dropped here as
  * Nx drops it, for this project and a named one alike.
  */
 type HasTarget = (project: string, target: string) => boolean
@@ -142,7 +142,7 @@ function expandTargetGlobs(
 
 export function mapNxDeps(
   raw: readonly unknown[],
-  metaByNode: ReadonlyMap<string, ProjectMeta>,
+  metaByNode: ReadonlyMap<string, PackageMeta>,
   ownTarget: (name: string) => boolean,
   taskNameFor: TaskNameFor,
   hasTarget: HasTarget,

package/src/nx/nx-map.ts

@@ -2,9 +2,10 @@
 // consumers: `bunx @vzn/vx-migrate --from nx` writes it to files, and the
 // `nx()` plugin runs it live. Static by design: targets that Nx plugins
 // infer at runtime are whatever the graph says. Named inputs expand from
-// nx.json when readable; the graph's dependency edges are ignored (vx
-// derives package edges from package.json manifests) except for one
-// report line counting edges with no manifest counterpart.
+// nx.json when readable; the graph's dependency edges are ignored (vx's
+// package edges come from a lockfile plugin, which installs what the
+// manifests name) except for one report line counting edges with no
+// manifest counterpart.
 //
 // Executors: `nx:run-commands`, a plain `command` and `nx:run-script` are
 // shell; `nx:noop` is a group; an executor the workspace translates
@@ -16,14 +17,10 @@
 // default configuration is folded into the base task.
 
 import path from 'node:path'
-import {
-  buildPackageGraph,
-  type GeneratedProject,
-  type GeneratedTask,
-  type ProjectMeta,
-  UserError,
-} from '@vzn/vx'
+import { type Duration, type GeneratedProject, type GeneratedTask, UserError } from '@vzn/vx'
+import type { PackageMeta } from '../packages.js'
 import { withoutTakenBack } from '../glob-grammar.js'
+import { manifestGraph, type ManifestGraph } from '../manifest-graph.js'
 import { mapRunCommands, shellQuote } from '../nx-command.js'
 import { scriptCommand, yarnPnp } from '../script-command.js'
 import {
@@ -251,8 +248,8 @@ export interface NxExecutorTarget {
 /** What a translated target runs as. The command runs in the project dir. */
 export interface NxExecutorTranslation {
   readonly command: string
-  /** `exec.timeout`, in ms. */
-  readonly timeout?: number
+  /** `exec.timeout`, a duration with its unit (`'10m'`). */
+  readonly timeout?: Duration
   /** Defined in the task's environment, as a run-commands `env` is. */
   readonly env?: Readonly<Record<string, string>>
 }
@@ -298,7 +295,7 @@ function normRel(p: string): string {
 
 export async function mapNxWorkspace(
   root: string,
-  metas: readonly ProjectMeta[],
+  metas: readonly PackageMeta[],
   graph: NxGraph,
   opts: MapNxOptions,
 ): Promise<NxMapping> {
@@ -324,11 +321,11 @@ export async function mapNxWorkspace(
     syncTasks: new Map(),
   }
 
-  const metaByRel = new Map<string, ProjectMeta>()
+  const metaByRel = new Map<string, PackageMeta>()
   for (const meta of metas) metaByRel.set(normRel(relPosix(root, meta.dir)), meta)
-  const metaByNode = new Map<string, ProjectMeta>()
-  const nodeByMeta = new Map<ProjectMeta, NxNode>()
-  const nodeNameOf = new Map<ProjectMeta, string>()
+  const metaByNode = new Map<string, PackageMeta>()
+  const nodeByMeta = new Map<PackageMeta, NxNode>()
+  const nodeNameOf = new Map<PackageMeta, string>()
   for (const [nodeName, node] of Object.entries(nodeMap)) {
     const meta = metaByRel.get(normRel(node?.data?.root ?? ''))
     if (meta) {
@@ -343,16 +340,16 @@ export async function mapNxWorkspace(
   // workspace root, but Nx routinely defines root targets. Synthesize
   // a meta for any unmatched node whose root resolves inside the
   // workspace, so its targets migrate too.
-  const allMetas: ProjectMeta[] = [...metas]
+  const allMetas: PackageMeta[] = [...metas]
   const taken = new Set(metas.map((m) => m.name))
   for (const [nodeName, node] of Object.entries(nodeMap)) {
     if (metaByNode.has(nodeName)) continue
     const relRoot = normRel(node?.data?.root ?? '')
     if (node?.data?.targets === undefined) continue
     const dir = relRoot === '' || relRoot === '.' ? root : path.join(root, relRoot)
-    let pkg: ProjectMeta['packageJson'] = { name: nodeName }
+    let pkg: PackageMeta['packageJson'] = { name: nodeName }
     try {
-      pkg = (await Bun.file(path.join(dir, 'package.json')).json()) as ProjectMeta['packageJson']
+      pkg = (await Bun.file(path.join(dir, 'package.json')).json()) as PackageMeta['packageJson']
     } catch {
       // No manifest at the node root — keep the synthetic one.
     }
@@ -362,7 +359,7 @@ export async function mapNxWorkspace(
     const name = [pkg.name, nodeName].find((n) => n && !taken.has(n))
     if (name === undefined) continue
     taken.add(name)
-    const synthetic: ProjectMeta = {
+    const synthetic: PackageMeta = {
       name,
       dir,
       packageJson: pkg,
@@ -388,7 +385,7 @@ export async function mapNxWorkspace(
 
   // Once per project, not per task and variant: `path.relative` was a
   // fifth of the mapping at 1,000 projects (item 608).
-  const relOf = new Map<ProjectMeta, string>()
+  const relOf = new Map<PackageMeta, string>()
   for (const meta of allMetas) {
     if (nodeByMeta.get(meta)?.data?.targets) relOf.set(meta, normRel(relPosix(root, meta.dir)))
   }
@@ -399,7 +396,7 @@ export async function mapNxWorkspace(
       ? null
       : await listDotenv(root, [...relOf.values()])
 
-  const mapped: Array<{ meta: ProjectMeta; tasks: GeneratedTask[] }> = []
+  const mapped: Array<{ meta: PackageMeta; tasks: GeneratedTask[] }> = []
   let releasePublish = 0
   // A configuration variant's task (`build:production`) and what it runs.
   const configured = new WeakMap<GeneratedTask, string>()
@@ -521,11 +518,11 @@ export async function mapNxWorkspace(
     nxClosureMemo.set(from, (r = seen))
     return r
   }
-  // What vx's `^` already reaches: a manifest path, direct or through
-  // another project, orders `^x` and folds its key (item 931). Built once,
-  // on the first `^` edge.
-  let pkgGraph: ReturnType<typeof buildPackageGraph> | undefined
-  const packageGraph = () => (pkgGraph ??= buildPackageGraph([...metas]))
+  // What vx's `^` already reaches: a manifest path (the lockfile plugin's
+  // edges), direct or through another project, orders `^x` and folds its
+  // key (item 931). Built once, on the first `^` edge.
+  let pkgGraph: ManifestGraph | undefined
+  const packageGraph = () => (pkgGraph ??= manifestGraph(metas))
   let reach: ((name: string) => ReadonlySet<string>) | undefined
   const reached = (name: string): ReadonlySet<string> => {
     if (reach === undefined) {
@@ -776,7 +773,7 @@ function allTargetNames(nodeMap: Readonly<Record<string, NxNode>>): string[] {
 }
 
 function buildTask(
-  meta: ProjectMeta,
+  meta: PackageMeta,
   projectRel: string,
   scripts: Record<string, unknown>,
   projectName: string,
@@ -785,7 +782,7 @@ function buildTask(
   variant: Variant,
   nodeName: string,
   upstream: NxUpstream,
-  metaByNode: ReadonlyMap<string, ProjectMeta>,
+  metaByNode: ReadonlyMap<string, PackageMeta>,
   nodeMap: Readonly<Record<string, NxNode>>,
   taskNameFor: TaskNameFor,
   opts: MapOpts,
@@ -874,9 +871,8 @@ function buildTask(
   const readyWhen = mapped?.readyWhen
   const persistent = readyWhen !== undefined || persistentTarget(target)
   // vx cleans outputs before a run and Nx never does. With git's file list
-  // known, a wildcard-first output (`**/*.d.ts`) stays cached: each
-  // committed file it reaches is taken back with `!` after mapping
-  // (`spareTrackedOutputs`), and what the clean removes is what the task
+  // known, a wildcard-first output (`**/*.d.ts`) stays cached: core never
+  // cleans a committed file, so what the clean removes is what the task
   // writes (owner, 2026-10-03). Without it, the sources cannot be told apart.
   const wild =
     opts.tracked === undefined
@@ -1023,7 +1019,7 @@ interface MappedCommand {
   /** The `.env` files the command loads, relative to the project dir: key inputs. */
   readonly envInputs: readonly string[]
   /** A translated executor's `exec.timeout`. */
-  readonly timeout?: number
+  readonly timeout?: Duration
   /** The Nx targets a leading `nx <target> <project>` ran: dependency edges (nx-command.ts). */
   readonly nxCalls?: readonly { readonly project: string; readonly target: string }[]
 }
@@ -1169,7 +1165,7 @@ function mapCommand(
 function translation(
   t: unknown,
   at: string,
-): { command: string; env: Record<string, unknown>; timeout: number | undefined } {
+): { command: string; env: Record<string, unknown>; timeout: Duration | undefined } {
   if (!isRecord(t)) throw new UserError(`${at}: must return { command } or undefined`)
   for (const key of Object.keys(t))
     if (key !== 'command' && key !== 'timeout' && key !== 'env')
@@ -1179,13 +1175,13 @@ function translation(
   const timeout = t.timeout
   if (
     timeout !== undefined &&
-    !(typeof timeout === 'number' && Number.isInteger(timeout) && timeout > 0)
+    !(typeof timeout === 'string' && /^[1-9]\d*(ms|s|m|h|d)$/.test(timeout))
   )
-    throw new UserError(`${at}: timeout must be a positive integer (ms)`)
+    throw new UserError(`${at}: timeout must be a duration with its unit, like '30s' or '10m'`)
   const env = t.env ?? {}
   if (!isRecord(env) || Object.values(env).some((v) => typeof v !== 'string'))
     throw new UserError(`${at}: env must map names to strings`)
-  return { command: t.command, env, timeout }
+  return { command: t.command, env, timeout: timeout as Duration | undefined }
 }
 
 /**
@@ -1354,7 +1350,7 @@ function passConfiguration(
   nodeName: string,
   configuration: string,
   nxEdges: (from: string, target: string) => readonly string[],
-  metaByNode: ReadonlyMap<string, ProjectMeta>,
+  metaByNode: ReadonlyMap<string, PackageMeta>,
   emittedIds: ReadonlySet<string>,
   taskNameFor: TaskNameFor,
 ): void {
@@ -1394,7 +1390,7 @@ function narrowToNxGraph(
   pkgName: string,
   nxClosure: (node: string) => ReadonlySet<string>,
   nxEdges: (from: string, target: string) => readonly string[],
-  metaByNode: ReadonlyMap<string, ProjectMeta>,
+  metaByNode: ReadonlyMap<string, PackageMeta>,
   emittedIds: ReadonlySet<string>,
   directDeps: (pkg: string) => readonly string[],
 ): void {
@@ -1436,7 +1432,7 @@ function followNxGraph(
   nodeName: string,
   pkgName: string,
   nxEdges: (from: string, target: string) => readonly string[],
-  metaByNode: ReadonlyMap<string, ProjectMeta>,
+  metaByNode: ReadonlyMap<string, PackageMeta>,
   emittedIds: ReadonlySet<string>,
   reached: (name: string) => ReadonlySet<string>,
 ): void {

package/src/nx/nx-upstream.ts

@@ -16,7 +16,8 @@
 // goes on through it. Nx allows a project cycle and vx's task graph does
 // not: inside a cycle a twin carries its peers' files as workspace globs
 // and edges only out of the cycle.
-import type { GeneratedTask, ProjectMeta } from '@vzn/vx'
+import type { GeneratedTask } from '@vzn/vx'
+import type { PackageMeta } from '../packages.js'
 import { emptyNxInputs, expandNxInputs, type NxInputs } from './nx-inputs.js'
 import { nxProjectOutputs } from './nx-outputs.js'
 import { matchNxProjects } from './nx-deps.js'
@@ -70,7 +71,7 @@ export function planNxUpstream(
   nodes: Readonly<Record<string, GraphNode>>,
   dependencies: unknown,
   workspaceNamed: Readonly<Record<string, unknown[]>> | null,
-  metaByNode: ReadonlyMap<string, ProjectMeta>,
+  metaByNode: ReadonlyMap<string, PackageMeta>,
 ): NxUpstream {
   const isProject = (n: string): boolean => typeof nodes[n]?.data?.root === 'string'
   const projectTags = Object.entries(nodes).map(([name, n]) => ({